Skip to content

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.md
new file mode 100644
index 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.
+
+@duytbp
diff --git a/apps/storybook/stories/Link.stories.tsx b/apps/storybook/stories/Link.stories.tsx
index 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: () => (
<div
diff --git a/docs/specs/components/Link/Link.spec.md b/docs/specs/components/Link/Link.spec.md
index 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 impact
diff --git a/packages/core/src/Link/Link.tsx b/packages/core/src/Link/Link.tsx
index 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.ts
new file mode 100644
index 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,
+ );
+ });
+}