coder · Parkreiner · Jan 7, 2024 · Dec 21, 2023 · Dec 21, 2023 · Dec 21, 2023
diff --git a/.vscode/settings.json b/.vscode/settings.json
@@ -60,6 +60,7 @@
     "idtoken",
     "Iflag",
     "incpatch",
+    "initialisms",
     "ipnstate",
     "isatty",
     "Jobf",

@@ -0,0 +1,74 @@
+import { type PropsWithChildren } from "react";
+import type { Meta, StoryObj } from "@storybook/react";
+import { Abbr } from "./Abbr";
+
+// Just here to make the abbreviated part more obvious in the component library
+const Underline = ({ children }: PropsWithChildren) => (
+  <span css={{ textDecoration: "underline dotted" }}>{children}</span>
+);
+
+const meta: Meta<typeof Abbr> = {
+  title: "components/Abbr",
+  component: Abbr,
+  decorators: [
+    (Story) => (
+      <>
+        <p>Try the following text out in a screen reader!</p>
+        <Story />
+      </>
+    ),
+  ],
+};
+
+export default meta;
+type Story = StoryObj<typeof Abbr>;
+
+export const InlinedShorthand: Story = {
+  args: {
+    pronunciation: "shorthand",
+    children: "ms",
+    title: "milliseconds",
+  },
+  decorators: [
+    (Story) => (
+      <p css={{ maxWidth: "40em" }}>
+        The physical pain of getting bonked on the head with a cartoon mallet
+        lasts precisely 593{" "}
+        <Underline>
+          <Story />
+        </Underline>
+        . The emotional turmoil and complete embarrassment lasts forever.
+      </p>
+    ),
+  ],
+};
+
+export const Acronym: Story = {
+  args: {
+    pronunciation: "acronym",
+    children: "NASA",
+    title: "National Aeronautics and Space Administration",
+  },
+  decorators: [
+    (Story) => (
+      <Underline>
+        <Story />
+      </Underline>
+    ),
+  ],
+};
+
+export const Initialism: Story = {
+  args: {
+    pronunciation: "initialism",
+    children: "CLI",
+    title: "Command-Line Interface",
+  },
+  decorators: [
+    (Story) => (
+      <Underline>
+        <Story />
+      </Underline>
+    ),
+  ],
+};
@@ -0,0 +1,97 @@
+import { render, screen } from "@testing-library/react";
+import { Abbr, type Pronunciation } from "./Abbr";
+
+type AbbreviationData = {
+  abbreviation: string;
+  title: string;
+  expectedLabel: string;
+};
+
+type AssertionInput = AbbreviationData & {
+  pronunciation: Pronunciation;
+};
+
+function assertAccessibleLabel({
+  abbreviation,
+  title,
+  expectedLabel,
+  pronunciation,
+}: AssertionInput) {
+  const { unmount } = render(
+    <Abbr title={title} pronunciation={pronunciation}>
+      {abbreviation}
+    </Abbr>,
+  );
+
+  screen.getByLabelText(expectedLabel, { selector: "abbr" });
+  unmount();
+}
+
+describe(Abbr.name, () => {
+  it("Has an aria-label that equals the title if the abbreviation is shorthand", () => {
+    const sampleShorthands: AbbreviationData[] = [
+      {
+        abbreviation: "ms",
+        title: "milliseconds",
+        expectedLabel: "milliseconds",
+      },
+      {
+        abbreviation: "g",
+        title: "grams",
+        expectedLabel: "grams",
+      },
+    ];
+
+    for (const shorthand of sampleShorthands) {
+      assertAccessibleLabel({ ...shorthand, pronunciation: "shorthand" });
+    }
+  });
+
+  it("Has an aria label with title and 'flattened' pronunciation if abbreviation is acronym", () => {
+    const sampleAcronyms: AbbreviationData[] = [
+      {
+        abbreviation: "NASA",
+        title: "National Aeronautics and Space Administration",
+        expectedLabel: "Nasa (National Aeronautics and Space Administration)",
+      },
+      {
+        abbreviation: "AWOL",
+        title: "Absent without Official Leave",
+        expectedLabel: "Awol (Absent without Official Leave)",
+      },
+      {
+        abbreviation: "YOLO",
+        title: "You Only Live Once",
+        expectedLabel: "Yolo (You Only Live Once)",
+      },
+    ];
+
+    for (const acronym of sampleAcronyms) {
+      assertAccessibleLabel({ ...acronym, pronunciation: "acronym" });
+    }
+  });
+
+  it("Has an aria label with title and initialized pronunciation if abbreviation is initialism", () => {
+    const sampleInitialisms: AbbreviationData[] = [
+      {
+        abbreviation: "FBI",
+        title: "Federal Bureau of Investigation",
+        expectedLabel: "F.B.I. (Federal Bureau of Investigation)",
+      },
+      {
+        abbreviation: "YMCA",
+        title: "Young Men's Christian Association",
+        expectedLabel: "Y.M.C.A. (Young Men's Christian Association)",
+      },
+      {
+        abbreviation: "CLI",
+        title: "Command-Line Interface",
+        expectedLabel: "C.L.I. (Command-Line Interface)",
+      },
+    ];
+
+    for (const initialism of sampleInitialisms) {
+      assertAccessibleLabel({ ...initialism, pronunciation: "initialism" });
+    }
+  });
+});
@@ -0,0 +1,66 @@
+import { type FC, type HTMLAttributes } from "react";
+
+export type Pronunciation = "shorthand" | "acronym" | "initialism";
+
+type AbbrProps = HTMLAttributes<HTMLElement> & {
+  children: string;
+  title: string;
+  pronunciation?: Pronunciation;
+};
+
+/**
+ * A more sophisticated version of the native <abbr> element.
+ *
+ * Features:
+ * - Better type-safety (requiring you to include certain properties)
+ * - All built-in HTML styling is stripped away by default
+ * - Better integration with screen readers (like exposing the title prop to
+ *   them), with more options for influencing how they pronounce text
+ */
+export const Abbr: FC<AbbrProps> = ({
+  children,
+  title,
+  pronunciation = "shorthand",
+  ...delegatedProps
+}) => {
+  return (
+    <abbr
+      // Title attributes usually aren't natively available to screen readers;
+      // always have to supplement with aria-label
+      title={title}
+      aria-label={getAccessibleLabel(children, title, pronunciation)}
+      css={{
+        textDecoration: "inherit",
+        letterSpacing: children === children.toUpperCase() ? "0.02em" : "0",
+      }}
+      {...delegatedProps}
+    >
+      <span aria-hidden>{children}</span>
+    </abbr>
+  );
+};
+
+function getAccessibleLabel(
+  abbreviation: string,
+  title: string,
+  pronunciation: Pronunciation,
+): string {
+  if (pronunciation === "initialism") {
+    return `${initializeText(abbreviation)} (${title})`;
+  }
+
+  if (pronunciation === "acronym") {
+    return `${flattenPronunciation(abbreviation)} (${title})`;
+  }
+
+  return title;
+}
+
+function initializeText(text: string): string {
+  return text.trim().toUpperCase().replaceAll(/\B/g, ".") + ".";
+}
+
+function flattenPronunciation(text: string): string {
+  const trimmed = text.trim();
+  return (trimmed[0] ?? "").toUpperCase() + trimmed.slice(1).toLowerCase();
+}