An open source design system that's fully customizable and agent ready
TypeScript
fix(Link): a button Link lines up its wrapped text like an anchor Link (#9584)
Cindy Zhang271bd70d376c
diff --git a/.changeset/link-button-wrapped-text-align.md b/.changeset/link-button-wrapped-text-align.mdnew file mode 100644index 0000000000..f68b4592aa--- /dev/null+++ b/.changeset/link-button-wrapped-text-align.md@@ -0,0 +1,7 @@+---+'@astryxdesign/core': patch+---++[fix] A `Link` rendered as a button (with `onClick` and no `href`) lines up its wrapped text like the text around it, as an `href` Link does, instead of centring its second and later lines.++@duytbpdiff --git a/apps/storybook/stories/Link.stories.tsx b/apps/storybook/stories/Link.stories.tsxindex 846926cd9e..ba9603ff45 100644--- a/apps/storybook/stories/Link.stories.tsx+++ b/apps/storybook/stories/Link.stories.tsx@@ -165,6 +165,40 @@ export const TruncatedInConstrainedLine: Story = {),};+/**+ * An anchor Link and a button Link whose text wraps, in a start-aligned+ * line, a right-to-left line and a centred line: each form lines up its+ * wrapped lines the same way.+ */+export const WrappedLines: Story = {+ tags: ['!autodocs'],+ render: () => (+ <div style={{display: 'grid', gap: 16, width: 180}}>+ {(+ [+ ['start', 'ltr', undefined],+ ['rtl', 'rtl', undefined],+ ['center', 'ltr', 'center'],+ ] as const+ ).map(([alignment, dir, textAlign]) =>+ (['anchor', 'button'] as const).map(form => (+ <p+ key={`${alignment}-${form}`}+ dir={dir}+ data-wrapped-line={`${alignment}-${form}`}+ style={{margin: 0, textAlign}}>+ <Link+ href={form === 'anchor' ? '/invitations/phone' : undefined}+ onClick={form === 'button' ? () => {} : undefined}>+ Send the phone interview invitation now+ </Link>+ </p>+ )),+ )}+ </div>+ ),+};+export const AllVariants: Story = {render: () => (<divdiff --git a/docs/specs/components/Link/Link.spec.md b/docs/specs/components/Link/Link.spec.mdindex 456238dd37..bd13d455f4 100644--- a/docs/specs/components/Link/Link.spec.md+++ b/docs/specs/components/Link/Link.spec.md@@ -17,6 +17,7 @@ verified_by:packages/core/src/Link/__tests__/Link.a11y.chromium.spec.ts,packages/core/src/Link/__tests__/Link.navigation.a11y.chromium.spec.ts,packages/core/src/Link/__tests__/Link.truncation.a11y.chromium.spec.ts,+ packages/core/src/Link/__tests__/Link.wrappedLines.a11y.chromium.spec.ts,]modules: []families: [family:navigation-destinations]@@ -108,7 +109,7 @@ Consumer migration instructions belong in consumer docs and release notes.| FR3 | An external Link that is not rendered as a button shows a trailing extra-small external-link icon that inherits the root's color, followed by visually hidden new-tab text: `newTabLabel`, else the localized default. | Current source and tests || FR4 | A destination reaches the link component only through the shared navigation rule; a rejected destination renders an inert anchor and never invokes a router. | `family:navigation-destinations` FR1–FR6; `spec:AST-005` || FR5 | A disabled Link stays focusable with `aria-disabled="true"`, never navigates, and never runs `onClick`. The disabled anchor form omits `href`, `target`, and `rel`, takes a Tab stop, and skips the custom link component. In every form, clicks are cancelled and stopped, Enter and Space are suppressed, other keys reach the caller's `onKeyDown`, and the Link paints at half opacity with no pointer events and no press paint. A focused Link that becomes disabled MUST keep focus and expose the change on that element (`spec:AST-085` FR4, FR5), and a caller `aria-disabled`, `role`, or `tabIndex` MUST NOT replace the disabled exposure (`architecture:public-component-api` INV5). Implementation gap: caller props spread after Link's own, so a caller `aria-disabled`, `role`, or `tabIndex` overrides them. Implementation gap: an enabled link renders through the safe link component and a disabled one as a plain anchor (or a `<button>` when it has `onClick`), so a focused link that becomes disabled (or re-enabled) is replaced and focus falls to the page. | `spec:AST-085` FR1, FR2, FR4, FR5; `family:navigation-destinations` FR7; current tests |-| FR6 | Children render inside Text with `type` (default `body`), `size`, `weight`, `color` (default `accent`), `display` (default `inline`), and `maxLines` (default `0`). The root inherits font family, size, weight, and line height and lays content out with a small gap; with `maxLines` above 0 it stops at its container, so its Text truncates inside a constrained line; `isStandalone` sets the body size and leading on the root. A Link inside a Text with `maxLines` MUST truncate with that text. Implementation gap: the root is `inline-flex`, so an ancestor Text clamp does not truncate it. | Current source and tests |+| FR6 | Children render inside Text with `type` (default `body`), `size`, `weight`, `color` (default `accent`), `display` (default `inline`), and `maxLines` (default `0`). The root inherits font family, size, weight, line height, and text alignment and lays content out with a small gap; with `maxLines` above 0 it stops at its container, so its Text truncates inside a constrained line; `isStandalone` sets the body size and leading on the root. A Link inside a Text with `maxLines` MUST truncate with that text. Implementation gap: the root is `inline-flex`, so an ancestor Text clamp does not truncate it. | Current source and tests || FR7 | The root paints the chosen color for the six built-in colors, which the underline and the external icon take; the label's color comes from Text (FR6). On hover-capable pointers an enabled Link underlines on hover, and for `primary`, `secondary`, and `accent` the root color mixes in the hover tint. `hasUnderline` underlines at rest. | Current source and tests || FR8 | Press feedback follows `design:user-states` DR1 and DR2 for Link's text surface: an enabled link or button form paints the pressed overlay, and a disabled Link does not. | `design:user-states` DR1, DR2; current tests || FR9 | `label`, when non-empty, becomes `aria-label` and replaces the content as the accessible name; a caller `aria-label` overrides it; otherwise the content is the name. | Current tests |@@ -186,19 +187,19 @@ carries no anatomy-theming map.## Verification map-| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |-| ---------------- | ----------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------- |-| FR1, AR1 | `Link.test.tsx` element-form, `as`, and provider cases; `Link.a11y.chromium.spec.ts` | Native, router, button form, disabled | A wrong element form or role fails. Evidence gap: no test renders Link under an inherited interactive role (FR1 (c)). | `audit:Link/anatomy` |-| FR2, FR3, AR3 | `Link.test.tsx` external, target, rel, and new-tab cases; `Link.a11y.chromium.spec.ts` external state | External; explicit `_blank`; custom label | A missing safety token, icon, or new-tab text fails. Evidence gap: no test checks the accessible name of an external link with `label`. Evidence gap: no test sets `referrerPolicy` or asserts the external icon's size or color. | `audit:Link/accessibility` |-| FR4 | `Link.navigation.a11y.chromium.spec.ts` | Rejected and ordinary schemes; native, router, downloads | A rejected destination that navigates or reaches a router fails. | `audit:Link/behavior` |-| FR5, AR2 | `Link.test.tsx` disabled cases | Disabled anchor; disabled button form; with `onClick` | Navigation, a consumer `onClick`, a lost Tab stop, or a custom component on a disabled link fails. Evidence gap: no test disables a focused link or passes a caller `aria-disabled`, `role`, or `tabIndex`. Evidence gap: no test asserts that other keys reach the caller's `onKeyDown`, or the half-opacity, no-pointer-events paint. | `audit:Link/accessibility` |-| FR6 (type) | `Link.test.tsx` text-type cases | Default `body`; `type="inherit"` | A dropped Text `type` fails. `Link.truncation.a11y.chromium.spec.ts`: an anchor and a button Link with `maxLines={1}` in a fixed-width line stop at the line and draw an ellipsis. Evidence gap: no test asserts that `size`, `weight`, `color`, or `display` reach Text, or the `isStandalone` root size. | `audit:Link/visual` |-| FR6, FR7 (paint) | Evidence gap: the color, underline, and standalone cases assert only that a link renders; hover paint is untested | Each color; `hasUnderline`; `isStandalone` | — | `audit:Link/visual` |-| FR8 | `Link.test.tsx` pressed-state suite | Link, button form, disabled | No press paint, or press paint on a disabled Link, fails. | `audit:Link/behavior` |-| FR9, FR11, AR4 | `Link.test.tsx` label, ref, and theme-class cases | With and without `label`; `data-color` | A missing or extra `aria-label`, target, `data-color`, or ref fails. The accessibility suites assert a passed `data-*` attribute and `aria-current` on the root, and the navigation suite asserts `download`. Evidence gap: no test passes both `label` and `aria-label`, or passes `className`, `style`, or `xstyle`. | `audit:Link/theming` |-| FR10 | Evidence gap: the tooltip case asserts only that the link renders | Tooltip | — | `audit:Link/accessibility` |-| ORD1–ORD3 | Covered by the FR1–FR3 rows | — | — | `audit:Link/behavior` |-| PR1, AR5 | Evidence gap: no test asserts the absence of per-link listeners or the focus indicator | — | — | `audit:Link/accessibility` |+| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |+| ---------------- | ----------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------- |+| FR1, AR1 | `Link.test.tsx` element-form, `as`, and provider cases; `Link.a11y.chromium.spec.ts` | Native, router, button form, disabled | A wrong element form or role fails. Evidence gap: no test renders Link under an inherited interactive role (FR1 (c)). | `audit:Link/anatomy` |+| FR2, FR3, AR3 | `Link.test.tsx` external, target, rel, and new-tab cases; `Link.a11y.chromium.spec.ts` external state | External; explicit `_blank`; custom label | A missing safety token, icon, or new-tab text fails. Evidence gap: no test checks the accessible name of an external link with `label`. Evidence gap: no test sets `referrerPolicy` or asserts the external icon's size or color. | `audit:Link/accessibility` |+| FR4 | `Link.navigation.a11y.chromium.spec.ts` | Rejected and ordinary schemes; native, router, downloads | A rejected destination that navigates or reaches a router fails. | `audit:Link/behavior` |+| FR5, AR2 | `Link.test.tsx` disabled cases | Disabled anchor; disabled button form; with `onClick` | Navigation, a consumer `onClick`, a lost Tab stop, or a custom component on a disabled link fails. Evidence gap: no test disables a focused link or passes a caller `aria-disabled`, `role`, or `tabIndex`. Evidence gap: no test asserts that other keys reach the caller's `onKeyDown`, or the half-opacity, no-pointer-events paint. | `audit:Link/accessibility` |+| FR6 (type) | `Link.test.tsx` text-type cases; `Link.wrappedLines.a11y.chromium.spec.ts` (wrapped text alignment) | Default `body`; `type="inherit"`; wrapped button and anchor forms in a start-aligned, right-to-left and centred line | A dropped Text `type` fails. `Link.truncation.a11y.chromium.spec.ts`: an anchor and a button Link with `maxLines={1}` in a fixed-width line stop at the line and draw an ellipsis. Evidence gap: no test asserts that `size`, `weight`, `color`, or `display` reach Text, or the `isStandalone` root size. A button form whose wrapped lines line up differently from the anchor form fails. | `audit:Link/visual` |+| FR6, FR7 (paint) | Evidence gap: the color, underline, and standalone cases assert only that a link renders; hover paint is untested | Each color; `hasUnderline`; `isStandalone` | — | `audit:Link/visual` |+| FR8 | `Link.test.tsx` pressed-state suite | Link, button form, disabled | No press paint, or press paint on a disabled Link, fails. | `audit:Link/behavior` |+| FR9, FR11, AR4 | `Link.test.tsx` label, ref, and theme-class cases | With and without `label`; `data-color` | A missing or extra `aria-label`, target, `data-color`, or ref fails. The accessibility suites assert a passed `data-*` attribute and `aria-current` on the root, and the navigation suite asserts `download`. Evidence gap: no test passes both `label` and `aria-label`, or passes `className`, `style`, or `xstyle`. | `audit:Link/theming` |+| FR10 | Evidence gap: the tooltip case asserts only that the link renders | Tooltip | — | `audit:Link/accessibility` |+| ORD1–ORD3 | Covered by the FR1–FR3 rows | — | — | `audit:Link/behavior` |+| PR1, AR5 | Evidence gap: no test asserts the absence of per-link listeners or the focus indicator | — | — | `audit:Link/accessibility` |## Current-state impactdiff --git a/packages/core/src/Link/Link.tsx b/packages/core/src/Link/Link.tsxindex b8b38f218b..26b521f825 100644--- a/packages/core/src/Link/Link.tsx+++ b/packages/core/src/Link/Link.tsx@@ -98,6 +98,9 @@ const styles = stylex.create({backgroundColor: 'transparent',borderStyle: 'none',padding: 0,+ // Browsers centre a button's text; a wrapped label lines up as an+ // anchor's does.+ textAlign: 'inherit',pointerEvents: 'auto',position: 'relative',},diff --git a/packages/core/src/Link/__tests__/Link.wrappedLines.a11y.chromium.spec.ts b/packages/core/src/Link/__tests__/Link.wrappedLines.a11y.chromium.spec.tsnew file mode 100644index 0000000000..bfede24a2d--- /dev/null+++ b/packages/core/src/Link/__tests__/Link.wrappedLines.a11y.chromium.spec.ts@@ -0,0 +1,72 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.+// @pr-a11y scope ^(packages/core/src/Link/|packages/core/src/Text/|apps/storybook/stories/Link\.stories)++/**+ * @file Link.wrappedLines.a11y.chromium.spec.ts+ * @input Storybook story core-link--wrapped-lines+ * @output A button Link lines up its wrapped lines as an anchor Link does: in+ * a start-aligned line, a right-to-left line and a centred line, the last+ * line of each form starts at the same place within the Link and both forms+ * compute the same text alignment.+ * @position Real-browser check: jsdom applies no button styles and lays out+ * no lines.+ */++import {expect, test} from '@playwright/test';+import {+ DEFAULT_STORYBOOK_DIR,+ serveStorybook,+ type StaticServer,+} from '@astryxdesign/a11y-spec/storybook';++let storybook: StaticServer;++test.beforeAll(async () => {+ storybook = await serveStorybook(+ process.env.ASTRYX_STORYBOOK_DIR ?? DEFAULT_STORYBOOK_DIR,+ );+});++test.afterAll(async () => storybook?.close());++for (const alignment of ['start', 'rtl', 'center'] as const) {+ test(`a button Link wraps like an anchor Link in a ${alignment} line`, async ({+ page,+ }) => {+ await page.goto(+ `${storybook.origin}/iframe.html?id=core-link--wrapped-lines&viewMode=story`,+ );+ const measure = async (form: 'anchor' | 'button') =>+ page+ .locator(`[data-wrapped-line="${alignment}-${form}"]`)+ .evaluate(line => {+ const root = line.firstElementChild as HTMLElement;+ const range = document.createRange();+ range.selectNodeContents(root);+ const lines = Array.from(range.getClientRects()).filter(+ rect => rect.width > 0,+ );+ const box = root.getBoundingClientRect();+ const last = lines[lines.length - 1];+ return {+ tag: root.tagName,+ lineCount: new Set(lines.map(rect => Math.round(rect.top))).size,+ textAlign: getComputedStyle(root).textAlign,+ // Where the last line sits inside the Link's own box.+ lastLeft: last.left - box.left,+ lastRight: box.right - last.right,+ };+ });+ const anchor = await measure('anchor');+ const button = await measure('button');+ expect(anchor.tag).toBe('A');+ expect(button.tag).toBe('BUTTON');+ expect(anchor.lineCount, 'the text wraps').toBeGreaterThan(1);+ expect(button.lineCount, 'the text wraps').toBeGreaterThan(1);+ expect(button.textAlign).toBe(anchor.textAlign);+ expect(Math.abs(button.lastLeft - anchor.lastLeft)).toBeLessThanOrEqual(1);+ expect(Math.abs(button.lastRight - anchor.lastRight)).toBeLessThanOrEqual(+ 1,+ );+ });+}