Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

fix(Text, Heading): a long unbroken token wraps in text that is not truncated (#9351)

Cindy Zhang389dc8448dff
diff --git a/.changeset/text-heading-long-tokens-wrap.md b/.changeset/text-heading-long-tokens-wrap.md
new file mode 100644
index 0000000000..0167ca5449
--- /dev/null
+++ b/.changeset/text-heading-long-tokens-wrap.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/core': patch
+---
+
+[fix] Text and Heading: a long unbroken word, URL or ID in text that isn't truncated now wraps instead of running past its container, so in ordinary flow a phone-width page (320 px) no longer scrolls sideways. Ordinary text lays out exactly as before, and truncation (`maxLines`) is unchanged. Inside a flex row, the flex child still needs `min-width: 0`. Text and Heading now set `overflow-wrap` themselves, so a container you style with `overflow-wrap: anywhere` no longer reaches their text; Astryx's own containers (CommandPaletteEmpty, Toast, FieldStatus, Banner) pass their `anywhere` wrap through.
+
+@cixzhang
diff --git a/apps/storybook/stories/TextReflowA11y.stories.tsx b/apps/storybook/stories/TextReflowA11y.stories.tsx
new file mode 100644
index 0000000000..726ab806bd
--- /dev/null
+++ b/apps/storybook/stories/TextReflowA11y.stories.tsx
@@ -0,0 +1,81 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file TextReflowA11y.stories.tsx
+ * @input Text, Heading, CommandPaletteEmpty and Banner given a long unbroken token
+ * @output Browser fixtures for Text and Heading FR3 at 320 CSS px (spec:AST-020
+ * FR1, WCAG 2.2 1.4.10): untruncated text wraps the token; single-line
+ * truncation still clips; Text inside a container that wraps with `anywhere`
+ * keeps `anywhere`
+ * @position Read by TextReflow.a11y.chromium.spec.ts; `no-visual`, so the
+ * stable visual plan never captures these fixtures
+ */
+
+import type {Meta, StoryObj} from '@storybook/react';
+import {Banner} from '@astryxdesign/core/Banner';
+import {CommandPaletteEmpty} from '@astryxdesign/core/CommandPalette';
+import {Heading} from '@astryxdesign/core/Heading';
+import {Text} from '@astryxdesign/core/Text';
+
+const TOKEN =
+ 'https://example.com/releases/2026/aVeryLongUnbrokenTokenThatIsMuchWiderThanAPhone';
+
+const meta = {
+ title: 'A11y/Text reflow',
+ tags: ['no-visual'],
+ parameters: {layout: 'fullscreen'},
+} satisfies Meta;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+/** Untruncated Text (inline and block) and Heading with the token. */
+export const Untruncated: Story = {
+ render: () => (
+ <div style={{padding: 8}}>
+ <Heading level={1} data-testid="heading">
+ {TOKEN}
+ </Heading>
+ <Text data-testid="text-inline">{TOKEN}</Text>
+ <Text display="block" data-testid="text-block">
+ {TOKEN}
+ </Text>
+ </div>
+ ),
+};
+
+/** Single-line truncation keeps clipping the token on one line. */
+export const Truncated: Story = {
+ render: () => (
+ <div style={{padding: 8}}>
+ <Heading level={1} maxLines={1} data-testid="heading">
+ {TOKEN}
+ </Heading>
+ <Text maxLines={1} data-testid="text">
+ {TOKEN}
+ </Text>
+ </div>
+ ),
+};
+
+/** A `<Text>` message in the command palette's empty state. */
+export const CommandPaletteEmptyText: Story = {
+ render: () => (
+ <CommandPaletteEmpty>
+ <Text data-testid="text">{`No results for ${TOKEN}`}</Text>
+ </CommandPaletteEmpty>
+ ),
+};
+
+/** A `<Text>` description in a banner. */
+export const BannerText: Story = {
+ render: () => (
+ <div style={{padding: 8}}>
+ <Banner
+ status="info"
+ title="Release notes"
+ description={<Text data-testid="text">{TOKEN}</Text>}
+ />
+ </div>
+ ),
+};
diff --git a/docs/specs/components/Heading/Heading.spec.md b/docs/specs/components/Heading/Heading.spec.md
index 2c6844e6cf..d5a3dcf9ed 100644
--- a/docs/specs/components/Heading/Heading.spec.md
+++ b/docs/specs/components/Heading/Heading.spec.md
@@ -15,6 +15,8 @@ verified_by:
.github/visual-baseline/manifest.json,
packages/core/src/Heading/Heading.test.tsx,
packages/core/src/Text/useTruncation.test.tsx,
+ packages/core/src/Text/__tests__/TextReflow.a11y.chromium.spec.ts,
+ scripts/text-overflow-wrap-anywhere.test.mjs,
packages/core/src/theme/themingTargets.test.ts,
packages/core/src/theme/extensibleAxes.test.ts,
apps/storybook/stories/Heading.stories.tsx,
@@ -33,15 +35,15 @@ system_specs: [spec:AST-009, spec:AST-024]
## Contract at a glance
-| Area | Contract |
-| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| Public contract | A semantic heading with a required `level`, an optional theme-extensible visual `type`, `weight`, `accessibilityLevel`, and the shared text controls documented in `Heading.doc.mjs`. |
-| Behavior | `level` picks `h1`–`h6` and the default visual scale; `type` and `weight` change only appearance; `accessibilityLevel` sets `aria-level` when it differs. |
-| End-user impact | Screen-reader users navigate a document outline that matches the page's sections, whatever size each heading is drawn at. |
-| Builder impact | None; the record describes shipped behavior. |
-| Compatibility/readiness | Released behavior recorded as current; no API, default, or output changes. One implementation gap is listed under Current-state impact. |
-| Review checks | Reject a visual `type` or `weight` that changes the element or level, a heading that renders without a level baseline, or a duplicate native tooltip for truncation. |
-| Governing rules | `spec:AST-024` (custom visual types, weight precedence, unchanged accessibility); `architecture:component-theming-surface/INV6,INV14`; `architecture:public-component-api/INV5,INV6,INV8`. |
+| Area | Contract |
+| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Public contract | A semantic heading with a required `level`, an optional theme-extensible visual `type`, `weight`, `accessibilityLevel`, and the shared text controls documented in `Heading.doc.mjs`. |
+| Behavior | `level` picks `h1`–`h6` and the default visual scale; `type` and `weight` change only appearance; `accessibilityLevel` sets `aria-level` when it differs. |
+| End-user impact | Screen-reader users navigate a document outline that matches the page's sections, whatever size each heading is drawn at. |
+| Builder impact | A long unbroken token in non-truncated Heading wraps. Inside a flex row, the flex child needs `min-width: 0` for the wrap to apply, and a caller's own container that sets `overflow-wrap: anywhere` does not reach Heading's text; Core's `anywhere` containers pass their wrap to it. |
+| Compatibility/readiness | Released behavior recorded as current, with one styling output change: non-truncated Heading sets `overflow-wrap` (`break-word`, or `anywhere` inside Core's `anywhere` containers). No API change. One implementation gap is listed under Current-state impact. |
+| Review checks | Reject a visual `type` or `weight` that changes the element or level, a heading that renders without a level baseline, or a duplicate native tooltip for truncation. |
+| Governing rules | `spec:AST-024` (custom visual types, weight precedence, unchanged accessibility); `architecture:component-theming-surface/INV6,INV14`; `architecture:public-component-api/INV5,INV6,INV8`. |
This table is a review projection; the body below is authoritative.
@@ -56,8 +58,10 @@ Heading's own contract.
## Compatibility and migration
- Released default preserved: `yes`
-- Compatibility class: records shipped behavior; no public prop, default, DOM,
- or styling output changes
+- Compatibility class: one styling output change, with no public prop,
+ default, or DOM change: non-truncated Heading sets `overflow-wrap`
+ (`break-word`, or `anywhere` inside Core's `anywhere` containers), so a long
+ unbroken token wraps (FR3)
- Controlled/uncontrolled behavior: not applicable
- Migration decision: none
@@ -101,13 +105,13 @@ Consumer migration instructions belong in consumer docs and release notes.
## Behavioral and layout contract
-| ID | Invariant | Basis |
-| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ |
-| FR1 | `level` renders `h1`–`h6`. `accessibilityLevel` adds `aria-level` only when it differs from `level`. | Current source and tests |
-| FR2 | The heading carries the `heading` target reflecting `level`, `color`, and any supplied `type` and `weight`. A built-in `type` applies its display scale and default weight; otherwise the level's scale applies. A theme-added `type` keeps the level's scale as its baseline. An explicit `weight` wins over the type and level defaults. | Current source and tests |
-| FR3 | `color` defaults to `primary`; a theme-added color keeps the primary baseline until a theme paints it. `hasCapsize` renders `block` and trims to cap height; otherwise `maxLines` above 1 renders the line-clamp box, `maxLines={1}` renders `block`, and otherwise `display` (default `block`) applies. `justify` uses logical values; `start`, the default, sets no alignment, so the element follows its container's. `textWrap` and `hasStrikethrough` apply their text treatments. | Current source and tests |
-| FR4 | `maxLines={1}` clips one line with an ellipsis; a larger value clamps to that many lines unless `hasCapsize` is set, whose `block` display removes the clamp. With truncation, `wordBreak` defaults to `break-all` for one line and `break-word` otherwise. When the text is measured as truncated and `hasTruncateTooltip` is not `false`, a lazily loaded Tooltip anchored to the heading shows the full text at the given placement (default `above`); no native `title` is added. `hasTruncateTooltip={false}` takes no measurement. A truncation tooltip can be opened from the keyboard (WCAG 2.2 2.1.1). Implementation gap: the tooltip opens on hover and touch only, because the heading is not focusable (Current-state impact). | Current source and tests |
-| FR5 | `ref` reaches the heading element. Supported DOM, ARIA, data, and event props reach it after the derived `aria-level`, so a caller `aria-level` wins; `xstyle`, `className`, and `style` merge in that order after component styles, with the line clamp applied after `style`. | Current source and tests |
+| ID | Invariant | Basis |
+| --- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ |
+| FR1 | `level` renders `h1`–`h6`. `accessibilityLevel` adds `aria-level` only when it differs from `level`. | Current source and tests |
+| FR2 | The heading carries the `heading` target reflecting `level`, `color`, and any supplied `type` and `weight`. A built-in `type` applies its display scale and default weight; otherwise the level's scale applies. A theme-added `type` keeps the level's scale as its baseline. An explicit `weight` wins over the type and level defaults. | Current source and tests |
+| FR3 | `color` defaults to `primary`; a theme-added color keeps the primary baseline until a theme paints it. `hasCapsize` renders `block` and trims to cap height; otherwise `maxLines` above 1 renders the line-clamp box, `maxLines={1}` renders `block`, and otherwise `display` (default `block`) applies. `justify` uses logical values; `start`, the default, sets no alignment, so the element follows its container's. `textWrap` and `hasStrikethrough` apply their text treatments. Without truncation, a token longer than its line wraps, so in ordinary flow the text does not force horizontal scrolling at 320 CSS px (`spec:AST-020` FR1, WCAG 2.2 1.4.10 Reflow). The heading's `overflow-wrap` is `break-word`, which keeps min-content, so tables and auto-sized columns lay out ordinary words unchanged; inside a Core container that wraps its content with `anywhere` (CommandPaletteEmpty, Toast, FieldStatus, Banner), it is `anywhere`, as the container's own text is. A flex child needs `min-width: 0` from its container, and a caller's own container that sets `overflow-wrap: anywhere` does not reach the heading's text. | Current source and tests |
+| FR4 | `maxLines={1}` clips one line with an ellipsis; a larger value clamps to that many lines unless `hasCapsize` is set, whose `block` display removes the clamp. With truncation, `wordBreak` defaults to `break-all` for one line and `break-word` otherwise. When the text is measured as truncated and `hasTruncateTooltip` is not `false`, a lazily loaded Tooltip anchored to the heading shows the full text at the given placement (default `above`); no native `title` is added. `hasTruncateTooltip={false}` takes no measurement. A truncation tooltip can be opened from the keyboard (WCAG 2.2 2.1.1). Implementation gap: the tooltip opens on hover and touch only, because the heading is not focusable (Current-state impact). | Current source and tests |
+| FR5 | `ref` reaches the heading element. Supported DOM, ARIA, data, and event props reach it after the derived `aria-level`, so a caller `aria-level` wins; `xstyle`, `className`, and `style` merge in that order after component styles, with the line clamp applied after `style`. | Current source and tests |
### Allowed variation
@@ -174,16 +178,17 @@ Tooltip.
## Verification map
-| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
-| -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------ |
-| FR1, AR2 | `Heading.test.tsx` level and `accessibilityLevel` tests | Levels 1–6; differing and equal override | A wrong element, a missing `aria-level` for a differing override, or an `aria-level` added for an equal one fails. | `audit:Heading/a11y` |
-| FR2 | `Heading.test.tsx` target, type, theme-added type, weight, and omitted-type tests; `extensibleAxes.test.ts`; `HeadingAudit.a11y.chromium.spec.ts` on the AuditMatrix story | Display types, theme-added type, weight | A lost `heading` class or `data-level`, `data-color`, `data-type`, or `data-weight` reflection, a reflected omitted type, or a theme-added type losing its level baseline fails. Display sizes out of order, or an explicit `bold` no heavier than the display default, fails the browser spec. Gap: the level scales and the level default weights have no paint check. | `audit:Heading/theming` |
-| FR3 | Stable visual baseline `core-heading--level-1`; `Heading.stories.tsx`; `HeadingAudit.a11y.chromium.spec.ts` | Level 1 default; secondary color; `center` and `end` alignment | A changed level-1 scale, color, or display comes back changed for review; a `justify` that does not resolve to logical `center` or `end`, or heading text below its WCAG contrast threshold, fails the browser spec. Gap: `display` precedence, `textWrap`, cap-height trim, strikethrough, and the theme-added color baseline have no automated check. | `audit:Heading/behavior` |
-| FR4, PR1 | `Heading.test.tsx` truncation-measurement tests; `useTruncation.test.tsx`; `HeadingAudit.a11y.chromium.spec.ts` | Tooltip on and off; content change; one and two lines | Measuring with the tooltip off, not measuring with it on, or a missed re-measure fails. A one-line heading without its ellipsis, a two-line clamp that does not hold two lines, or a clipped heading whose hover shows no full-text tooltip fails the browser spec. Gap: the `wordBreak` defaults and the tooltip placement have no automated check. | `audit:Heading/behavior` |
-| FR5 | `Heading.test.tsx` ref, `id`, passthrough, `aria-level` precedence, styling-input, and line-clamp tests | Rerender; `id`; `data-testid`; caller `aria-level`; `className`, `xstyle`, and `style` | A detached ref, a lost `id` or test id, a derived `aria-level` that overrides the caller's, a `className` or `xstyle` that is dropped or merges before the component styles, or a caller `WebkitLineClamp` that replaces the clamp fails. | `audit:Heading/behavior` |
-| AR1 | `Heading.test.tsx` display-type element tests | Levels with display and theme-added types | A visual type that changes the element fails. | `audit:Heading/a11y` |
-| AR3 | `Heading.test.tsx` truncation title test; `HeadingAudit.a11y.chromium.spec.ts` | Truncated heading | A native `title` on a truncated heading fails both. | `audit:Heading/a11y` |
-| AR1, AR2 | `HeadingAudit.a11y.chromium.spec.ts` reading Chromium's accessibility tree (`spec:AST-009` FR3) | Levels, equal and differing override, display types | A heading exposed with a role or level other than its element or `aria-level` requires fails the browser spec. | `audit:Heading/a11y` |
+| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
+| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------ |
+| FR1, AR2 | `Heading.test.tsx` level and `accessibilityLevel` tests | Levels 1–6; differing and equal override | A wrong element, a missing `aria-level` for a differing override, or an `aria-level` added for an equal one fails. | `audit:Heading/a11y` |
+| FR2 | `Heading.test.tsx` target, type, theme-added type, weight, and omitted-type tests; `extensibleAxes.test.ts`; `HeadingAudit.a11y.chromium.spec.ts` on the AuditMatrix story | Display types, theme-added type, weight | A lost `heading` class or `data-level`, `data-color`, `data-type`, or `data-weight` reflection, a reflected omitted type, or a theme-added type losing its level baseline fails. Display sizes out of order, or an explicit `bold` no heavier than the display default, fails the browser spec. Gap: the level scales and the level default weights have no paint check. | `audit:Heading/theming` |
+| FR3 | Stable visual baseline `core-heading--level-1`; `Heading.stories.tsx`; `HeadingAudit.a11y.chromium.spec.ts` | Level 1 default; secondary color; `center` and `end` alignment | A changed level-1 scale, color, or display comes back changed for review; a `justify` that does not resolve to logical `center` or `end`, or heading text below its WCAG contrast threshold, fails the browser spec. Gap: `display` precedence, `textWrap`, cap-height trim, strikethrough, and the theme-added color baseline have no automated check. | `audit:Heading/behavior` |
+| FR3 (reflow) | `Heading.test.tsx` long unbroken tokens; `TextReflow.a11y.chromium.spec.ts`; `scripts/text-overflow-wrap-anywhere.test.mjs` | A long unbroken token, untruncated and single-line truncated, at 320 CSS px; Text inside CommandPaletteEmpty and Banner | A token that does not wrap in an untruncated heading, a page that scrolls sideways at 320 px, single-line truncation that no longer clips on one line, Text inside CommandPaletteEmpty or Banner that loses the container's `anywhere` wrap or crosses an inline edge, or a Core style that sets `overflow-wrap: anywhere` without passing it to Text, fails. | `audit:Heading/a11y` |
+| FR4, PR1 | `Heading.test.tsx` truncation-measurement tests; `useTruncation.test.tsx`; `HeadingAudit.a11y.chromium.spec.ts` | Tooltip on and off; content change; one and two lines | Measuring with the tooltip off, not measuring with it on, or a missed re-measure fails. A one-line heading without its ellipsis, a two-line clamp that does not hold two lines, or a clipped heading whose hover shows no full-text tooltip fails the browser spec. Gap: the `wordBreak` defaults and the tooltip placement have no automated check. | `audit:Heading/behavior` |
+| FR5 | `Heading.test.tsx` ref, `id`, passthrough, `aria-level` precedence, styling-input, and line-clamp tests | Rerender; `id`; `data-testid`; caller `aria-level`; `className`, `xstyle`, and `style` | A detached ref, a lost `id` or test id, a derived `aria-level` that overrides the caller's, a `className` or `xstyle` that is dropped or merges before the component styles, or a caller `WebkitLineClamp` that replaces the clamp fails. | `audit:Heading/behavior` |
+| AR1 | `Heading.test.tsx` display-type element tests | Levels with display and theme-added types | A visual type that changes the element fails. | `audit:Heading/a11y` |
+| AR3 | `Heading.test.tsx` truncation title test; `HeadingAudit.a11y.chromium.spec.ts` | Truncated heading | A native `title` on a truncated heading fails both. | `audit:Heading/a11y` |
+| AR1, AR2 | `HeadingAudit.a11y.chromium.spec.ts` reading Chromium's accessibility tree (`spec:AST-009` FR3) | Levels, equal and differing override, display types | A heading exposed with a role or level other than its element or `aria-level` requires fails the browser spec. | `audit:Heading/a11y` |
## Decision log
diff --git a/docs/specs/components/Text/Text.spec.md b/docs/specs/components/Text/Text.spec.md
index ed5fcfbf53..e32d309b0c 100644
--- a/docs/specs/components/Text/Text.spec.md
+++ b/docs/specs/components/Text/Text.spec.md
@@ -15,6 +15,8 @@ verified_by:
.github/visual-baseline/manifest.json,
packages/core/src/Text/Text.test.tsx,
packages/core/src/Text/useTruncation.test.tsx,
+ packages/core/src/Text/__tests__/TextReflow.a11y.chromium.spec.ts,
+ scripts/text-overflow-wrap-anywhere.test.mjs,
packages/core/src/theme/themingTargets.test.ts,
apps/storybook/stories/Text.stories.tsx,
]
@@ -31,15 +33,15 @@ system_specs: [spec:AST-009]
## Contract at a glance
-| Area | Contract |
-| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| Public contract | A polymorphic text element with a semantic `type`, optional `size`, `color`, and `weight` overrides, an `as` element choice, and the text layout controls documented in `Text.doc.mjs`. |
-| Behavior | `type` sets size, weight, and default color from the theme; theme-added types and colors fall back to the body and primary baselines; truncated text offers its full content in a Tooltip. |
-| End-user impact | Readers get consistent type across the product; clamped text keeps its full content available on hover and in the DOM. |
-| Builder impact | None; the record describes shipped behavior. |
-| Compatibility/readiness | Released behavior recorded as current; no API, default, or output changes. One implementation gap is listed under Current-state impact. |
-| Review checks | Reject a theme-added type or color that renders unstyled, a native `title` beside the truncation Tooltip, or measurement when the tooltip is off. |
-| Governing rules | `architecture:component-theming-surface/INV6,INV14`; `architecture:public-component-api/INV5,INV6,INV8`. |
+| Area | Contract |
+| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Public contract | A polymorphic text element with a semantic `type`, optional `size`, `color`, and `weight` overrides, an `as` element choice, and the text layout controls documented in `Text.doc.mjs`. |
+| Behavior | `type` sets size, weight, and default color from the theme; theme-added types and colors fall back to the body and primary baselines; truncated text offers its full content in a Tooltip. |
+| End-user impact | Readers get consistent type across the product; clamped text keeps its full content available on hover and in the DOM. |
+| Builder impact | A long unbroken token in non-truncated Text wraps. Inside a flex row, the flex child needs `min-width: 0` for the wrap to apply, and a caller's own container that sets `overflow-wrap: anywhere` does not reach Text's text; Core's `anywhere` containers pass their wrap to it. |
+| Compatibility/readiness | Released behavior recorded as current, with one styling output change: non-truncated Text sets `overflow-wrap` (`break-word`, or `anywhere` inside Core's `anywhere` containers). No API change. One implementation gap is listed under Current-state impact. |
+| Review checks | Reject a theme-added type or color that renders unstyled, a native `title` beside the truncation Tooltip, or measurement when the tooltip is off. |
+| Governing rules | `architecture:component-theming-surface/INV6,INV14`; `architecture:public-component-api/INV5,INV6,INV8`. |
This table is a review projection; the body below is authoritative.
@@ -53,8 +55,10 @@ the truncation behavior of that element. Heading is documented beside Text in
## Compatibility and migration
- Released default preserved: `yes`
-- Compatibility class: records shipped behavior; no public prop, default, DOM,
- or styling output changes
+- Compatibility class: one styling output change, with no public prop,
+ default, or DOM change: non-truncated Text sets `overflow-wrap`
+ (`break-word`, or `anywhere` inside Core's `anywhere` containers), so a long
+ unbroken token wraps (FR3)
- Controlled/uncontrolled behavior: not applicable
- Migration decision: none
@@ -98,13 +102,13 @@ Consumer migration instructions belong in consumer docs and release notes.
## Behavioral and layout contract
-| ID | Invariant | Basis |
-| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------ |
-| FR1 | Text renders one element chosen by `as` (default `span`) carrying the `text` target, which reflects `type`, `size`, and the resolved `color`. | Current source and tests |
-| FR2 | A built-in `type` applies its size, line height, and default weight; a theme-added type applies the body baseline. `size` overrides the type's size while keeping its other properties; `weight` overrides the type's default weight. The resolved color is `color`, else the type's default; a theme-added color applies the primary baseline. | Current source and tests |
-| FR3 | `hasCapsize` renders `block` and trims to cap height; otherwise `maxLines` above 1 renders the line-clamp box, `maxLines={1}` renders `block`, and otherwise `display` (default `inline`) applies. `justify` uses logical values; `start`, the default, sets no alignment, so the element follows its container's. `textWrap`, `hasStrikethrough`, and `hasTabularNumbers` apply their text treatments. | Current source and tests |
-| FR4 | `maxLines={1}` clips one line with an ellipsis; a larger value clamps to that many lines unless `hasCapsize` is set, whose `block` display removes the clamp. With truncation, `wordBreak` defaults to `break-all` for one line and `break-word` otherwise. When the text is measured as truncated and `hasTruncateTooltip` is not `false`, a lazily loaded Tooltip anchored to the element shows the full text at the given placement (default `above`), and Text adds no native `title`. `hasTruncateTooltip={false}` takes no measurement. A truncation tooltip can be opened from the keyboard (WCAG 2.2 2.1.1). Implementation gap: the tooltip opens on hover and touch only, because the element is not focusable (Current-state impact). Truncation re-measures when the content changes without a resize. | Current source and tests |
-| FR5 | `ref` reaches the element. Supported DOM, ARIA, data, and event props reach it; `xstyle`, `className`, and `style` merge in that order after component styles, with the line clamp applied after `style`. | Current source and tests |
+| ID | Invariant | Basis |
+| --- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ |
+| FR1 | Text renders one element chosen by `as` (default `span`) carrying the `text` target, which reflects `type`, `size`, and the resolved `color`. | Current source and tests |
+| FR2 | A built-in `type` applies its size, line height, and default weight; a theme-added type applies the body baseline. `size` overrides the type's size while keeping its other properties; `weight` overrides the type's default weight. The resolved color is `color`, else the type's default; a theme-added color applies the primary baseline. | Current source and tests |
+| FR3 | `hasCapsize` renders `block` and trims to cap height; otherwise `maxLines` above 1 renders the line-clamp box, `maxLines={1}` renders `block`, and otherwise `display` (default `inline`) applies. `justify` uses logical values; `start`, the default, sets no alignment, so the element follows its container's. `textWrap`, `hasStrikethrough`, and `hasTabularNumbers` apply their text treatments. Without truncation, a token longer than its line wraps, so in ordinary flow the text does not force horizontal scrolling at 320 CSS px (`spec:AST-020` FR1, WCAG 2.2 1.4.10 Reflow). The element's `overflow-wrap` is `break-word`, which keeps min-content, so tables and auto-sized columns lay out ordinary words unchanged; inside a Core container that wraps its content with `anywhere` (CommandPaletteEmpty, Toast, FieldStatus, Banner), it is `anywhere`, as the container's own text is. A flex child needs `min-width: 0` from its container, and a caller's own container that sets `overflow-wrap: anywhere` does not reach the element's text. | Current source and tests |
+| FR4 | `maxLines={1}` clips one line with an ellipsis; a larger value clamps to that many lines unless `hasCapsize` is set, whose `block` display removes the clamp. With truncation, `wordBreak` defaults to `break-all` for one line and `break-word` otherwise. When the text is measured as truncated and `hasTruncateTooltip` is not `false`, a lazily loaded Tooltip anchored to the element shows the full text at the given placement (default `above`), and Text adds no native `title`. `hasTruncateTooltip={false}` takes no measurement. A truncation tooltip can be opened from the keyboard (WCAG 2.2 2.1.1). Implementation gap: the tooltip opens on hover and touch only, because the element is not focusable (Current-state impact). Truncation re-measures when the content changes without a resize. | Current source and tests |
+| FR5 | `ref` reaches the element. Supported DOM, ARIA, data, and event props reach it; `xstyle`, `className`, and `style` merge in that order after component styles, with the line clamp applied after `style`. | Current source and tests |
### Allowed variation
@@ -171,13 +175,14 @@ record declares no anatomy-theming block rather than assign `heading` to Text.
## Verification map
-| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
-| ------------- | ------------------------------------------------------------------------------------------ | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- |
-| FR1, AR1 | `Text.test.tsx` element, target, and reflection tests | Default `span`; `p`, `div`, `label` | A wrong element, a lost `text` class, or a lost `data-type`, `data-size`, or `data-color` reflection fails. Gap: no test asserts that Text adds no role, and no accessibility-tree check proves the element's role (`spec:AST-009` FR3). | `audit:Text/behavior` |
-| FR2 | `Text.test.tsx` theme-added type and color tests; stable visual baseline `core-text--body` | Theme-added type and color; built-in color; body default | A theme-added type or color losing its reflection, a theme-added color losing its primary baseline, or a lost color override, fails; a changed body scale or color comes back changed for review. Gap: no test asserts a theme-added type's body baseline (the custom-type test checks only the class and `data-type`), and the built-in type tests assert presence only, so each type's size, line height, and weight, and the `size` and `weight` overrides in paint, have no automated check. Each type's default color and a built-in color's paint also have no automated check; the color tests assert `data-color` only. | `audit:Text/theming` |
-| FR3 | `Text.stories.tsx` | Display, cap-height trim, wrap, strikethrough, tabular numbers | Gap: the prop tests assert presence only, so `display` precedence, `justify`, and every text treatment have no automated check. | `audit:Text/behavior` |
-| FR4, AR2, PR1 | `Text.test.tsx` native-title and truncation-measurement tests; `useTruncation.test.tsx` | Truncated with tooltip; tooltip off; content change | A native `title`, measuring with the tooltip off, not measuring with it on, or a missed re-measure fails. Gap: the ellipsis and line clamp, the `wordBreak` defaults, and the tooltip's appearance and placement have no automated check. | `audit:Text/a11y` |
-| FR5 | `Text.test.tsx` ref and passthrough tests | Rerender; `data-testid` | A detached ref or a lost test id fails. Gap: no test covers other DOM passthrough, the styling-input merge order, or the line clamp after `style`. | `audit:Text/behavior` |
+| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
+| ------------- | ------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- |
+| FR1, AR1 | `Text.test.tsx` element, target, and reflection tests | Default `span`; `p`, `div`, `label` | A wrong element, a lost `text` class, or a lost `data-type`, `data-size`, or `data-color` reflection fails. Gap: no test asserts that Text adds no role, and no accessibility-tree check proves the element's role (`spec:AST-009` FR3). | `audit:Text/behavior` |
+| FR2 | `Text.test.tsx` theme-added type and color tests; stable visual baseline `core-text--body` | Theme-added type and color; built-in color; body default | A theme-added type or color losing its reflection, a theme-added color losing its primary baseline, or a lost color override, fails; a changed body scale or color comes back changed for review. Gap: no test asserts a theme-added type's body baseline (the custom-type test checks only the class and `data-type`), and the built-in type tests assert presence only, so each type's size, line height, and weight, and the `size` and `weight` overrides in paint, have no automated check. Each type's default color and a built-in color's paint also have no automated check; the color tests assert `data-color` only. | `audit:Text/theming` |
+| FR3 | `Text.stories.tsx` | Display, cap-height trim, wrap, strikethrough, tabular numbers | Gap: the prop tests assert presence only, so `display` precedence, `justify`, and every text treatment have no automated check. | `audit:Text/behavior` |
+| FR3 (reflow) | `Text.test.tsx` long unbroken tokens; `TextReflow.a11y.chromium.spec.ts`; `scripts/text-overflow-wrap-anywhere.test.mjs` | A long unbroken token, inline and block, untruncated and single-line truncated, at 320 CSS px; Text inside CommandPaletteEmpty and Banner | A token that does not wrap in untruncated text, a page that scrolls sideways at 320 px, single-line truncation that no longer clips on one line, Text inside CommandPaletteEmpty or Banner that loses the container's `anywhere` wrap or crosses an inline edge, or a Core style that sets `overflow-wrap: anywhere` without passing it to Text, fails. | `audit:Text/a11y` |
+| FR4, AR2, PR1 | `Text.test.tsx` native-title and truncation-measurement tests; `useTruncation.test.tsx` | Truncated with tooltip; tooltip off; content change | A native `title`, measuring with the tooltip off, not measuring with it on, or a missed re-measure fails. Gap: the ellipsis and line clamp, the `wordBreak` defaults, and the tooltip's appearance and placement have no automated check. | `audit:Text/a11y` |
+| FR5 | `Text.test.tsx` ref and passthrough tests | Rerender; `data-testid` | A detached ref or a lost test id fails. Gap: no test covers other DOM passthrough, the styling-input merge order, or the line clamp after `style`. | `audit:Text/behavior` |
## Decision log
diff --git a/packages/core/src/Banner/Banner.tsx b/packages/core/src/Banner/Banner.tsx
index b787a740aa..6820e8ca57 100644
--- a/packages/core/src/Banner/Banner.tsx
+++ b/packages/core/src/Banner/Banner.tsx
@@ -286,6 +286,8 @@ const styles = stylex.create({
// the flex item's min-content width and pushes the page into horizontal
// scrolling at 320px, which is a WCAG 1.4.10 reflow failure.
overflowWrap: 'anywhere',
+ // Text inside keeps `anywhere` too (Text FR3).
+ '--_astryx-text-overflow-wrap': 'anywhere',
},
description: {
margin: 0,
@@ -295,6 +297,8 @@ const styles = stylex.create({
lineHeight: typeScaleVars['--text-supporting-leading'],
color: colorVars['--color-text-secondary'],
overflowWrap: 'anywhere',
+ // Text inside keeps `anywhere` too (Text FR3).
+ '--_astryx-text-overflow-wrap': 'anywhere',
},
// Built-in status title, description, and icon inherit the header's on-muted
// color. Built-in controls receive the same context on their Button element
diff --git a/packages/core/src/CommandPalette/CommandPaletteEmpty.tsx b/packages/core/src/CommandPalette/CommandPaletteEmpty.tsx
index ed49e41c90..6d2658abe3 100644
--- a/packages/core/src/CommandPalette/CommandPaletteEmpty.tsx
+++ b/packages/core/src/CommandPalette/CommandPaletteEmpty.tsx
@@ -40,6 +40,8 @@ const styles = stylex.create({
// instead of setting the centered line's minimum width, which pushes text
// past both inline edges where neither side can scroll to it.
overflowWrap: 'anywhere',
+ // Text inside keeps `anywhere` too (Text FR3).
+ '--_astryx-text-overflow-wrap': 'anywhere',
},
});
diff --git a/packages/core/src/FieldStatus/FieldStatus.tsx b/packages/core/src/FieldStatus/FieldStatus.tsx
index 304a452644..868510a060 100644
--- a/packages/core/src/FieldStatus/FieldStatus.tsx
+++ b/packages/core/src/FieldStatus/FieldStatus.tsx
@@ -67,6 +67,8 @@ const styles = stylex.create({
// URL). Let such an unbroken token wrap inside the field instead of
// painting past its edges (WCAG 2.2 SC 1.4.10 Reflow).
overflowWrap: 'anywhere',
+ // Text inside keeps `anywhere` too (Text FR3).
+ '--_astryx-text-overflow-wrap': 'anywhere',
},
attached: {
marginTop: `calc(-1 * ${ATTACHED_OVERLAP})`,
diff --git a/packages/core/src/Heading/Heading.test.tsx b/packages/core/src/Heading/Heading.test.tsx
index 7989fdc784..89da9f0b0a 100644
--- a/packages/core/src/Heading/Heading.test.tsx
+++ b/packages/core/src/Heading/Heading.test.tsx
@@ -303,6 +303,36 @@ function countScrollWidthReads(run: () => void): number {
return reads;
}
+// jsdom does not resolve var(); the browser spec checks the resolved value.
+// Untruncated text reads the private container override, else break-word.
+const DEFAULT_WRAP = 'var(--_astryx-text-overflow-wrap,break-word)';
+const wrapOf = (element: Element) =>
+ getComputedStyle(element).overflowWrap.replace(/\s/g, '');
+
+// Heading FR3 (spec:AST-020 FR1, WCAG 2.2 1.4.10): a token longer than its
+// line wraps in a heading that is not truncated; truncation is unchanged.
+describe('Heading long unbroken tokens', () => {
+ const token =
+ 'https://example.com/aVeryLongUnbrokenTokenThatIsWiderThan320px';
+
+ it('wraps them when the heading is not truncated', () => {
+ render(<Heading level={1}>{token}</Heading>);
+ expect(wrapOf(screen.getByText(token))).toBe(DEFAULT_WRAP);
+ });
+
+ it('leaves single-line truncation clipping on one line', () => {
+ render(
+ <Heading level={1} maxLines={1}>
+ {token}
+ </Heading>,
+ );
+ const style = getComputedStyle(screen.getByText(token));
+ expect(style.whiteSpace).toBe('nowrap');
+ expect(style.textOverflow).toBe('ellipsis');
+ expect(style.overflowWrap).not.toBe('break-word');
+ });
+});
+
describe('Heading maxLines without a truncation tooltip', () => {
it('takes no truncation measurement when hasTruncateTooltip is false', () => {
const reads = countScrollWidthReads(() => {
diff --git a/packages/core/src/Layer/layerStructureReset.stylex.ts b/packages/core/src/Layer/layerStructureReset.stylex.ts
index 6c65b7da6a..c3387247aa 100644
--- a/packages/core/src/Layer/layerStructureReset.stylex.ts
+++ b/packages/core/src/Layer/layerStructureReset.stylex.ts
@@ -27,5 +27,10 @@ export const layerStructureReset = stylex.create({
// fallback. A value set on the inner Stepper, through its `stepper` theme
// target, or by a caller style on this layer root still applies.
'--step-connector-gap': 'initial',
+ // A container that wraps with `overflow-wrap: anywhere` passes it to the
+ // Text inside it (Text and Heading FR3). Text in a layer opened from such
+ // a container keeps its own `break-word`: `initial` makes the variable
+ // invalid, so Text falls back.
+ '--_astryx-text-overflow-wrap': 'initial',
},
});
diff --git a/packages/core/src/Text/Heading.doc.mjs b/packages/core/src/Text/Heading.doc.mjs
index a3fc3b9bd9..1926c16443 100644
--- a/packages/core/src/Text/Heading.doc.mjs
+++ b/packages/core/src/Text/Heading.doc.mjs
@@ -79,7 +79,7 @@ export const docs = {
name: 'wordBreak',
type: "'break-word' | 'break-all'",
description:
- "Word break behavior when truncating. Defaults to 'break-all' for single-line truncation, 'break-word' otherwise.",
+ "Word break behavior when truncating. Defaults to 'break-all' for single-line truncation, 'break-word' otherwise. Without truncation, a token longer than its line (a URL, an ID) wraps (`overflow-wrap: break-word`), so in ordinary flow text does not make the page scroll sideways. Inside a flex row, give the flex child `min-width: 0` so it can shrink. A container you style with `overflow-wrap: anywhere` does not reach this text; Astryx's own containers pass their wrap through.",
},
{
name: 'textWrap',
@@ -203,7 +203,7 @@ export const docsZh = {
name: 'wordBreak',
type: "'break-word' | 'break-all'",
description:
- "截断时的断词行为。单行截断默认为 'break-all',其他情况默认为 'break-word'。",
+ "截断时的断词行为。单行截断默认为 'break-all',其他情况默认为 'break-word'。不截断时,超过一行宽度的长串(如 URL、ID)会换行(`overflow-wrap: break-word`),因此在普通文档流中文本不会让页面横向滚动。在 flex 行中,请为 flex 子元素设置 `min-width: 0` 以便其收缩。你自己设置了 `overflow-wrap: anywhere` 的容器不会作用于此文本;Astryx 自带的容器会传递其换行方式。",
},
{
name: 'textWrap',
@@ -281,7 +281,7 @@ export const docsDense = {
hasTruncateTooltip:
"Tooltip for truncated text; true=default position, false=disabled, or a placement ('above' | 'below' | 'start' | 'end').",
wordBreak:
- "Word break behavior; defaults 'break-all' for single-line, 'break-word' otherwise.",
+ "Word break behavior when truncating; defaults 'break-all' for single-line, 'break-word' otherwise. Untruncated long tokens wrap (overflow-wrap: break-word); a flex child needs min-width: 0; your own container's overflow-wrap: anywhere does not reach this text (Astryx containers pass theirs through).",
textWrap: 'Text wrapping behavior.',
justify:
"Text alignment (justification); logical values 'start' | 'center' | 'end' for RTL.",
diff --git a/packages/core/src/Text/Text.doc.mjs b/packages/core/src/Text/Text.doc.mjs
index e92a066012..bd2b8f0b8a 100644
--- a/packages/core/src/Text/Text.doc.mjs
+++ b/packages/core/src/Text/Text.doc.mjs
@@ -118,7 +118,7 @@ export const docs = {
name: 'wordBreak',
type: "'break-word' | 'break-all'",
description:
- "Word break behavior when truncating. Defaults to 'break-all' for single-line truncation, 'break-word' otherwise.",
+ "Word break behavior when truncating. Defaults to 'break-all' for single-line truncation, 'break-word' otherwise. Without truncation, a token longer than its line (a URL, an ID) wraps (`overflow-wrap: break-word`), so in ordinary flow text does not make the page scroll sideways. Inside a flex row, give the flex child `min-width: 0` so it can shrink. A container you style with `overflow-wrap: anywhere` does not reach this text; Astryx's own containers pass their wrap through.",
},
{
name: 'textWrap',
diff --git a/packages/core/src/Text/Text.test.tsx b/packages/core/src/Text/Text.test.tsx
index 9495be2b4e..b6bf6f5a9b 100644
--- a/packages/core/src/Text/Text.test.tsx
+++ b/packages/core/src/Text/Text.test.tsx
@@ -11,6 +11,12 @@ import {Text} from './Text';
import type {TextType} from './Text';
import type {TextColor} from '../theme/types';
+// jsdom does not resolve var(); the browser spec checks the resolved value.
+// Untruncated text reads the private container override, else break-word.
+const DEFAULT_WRAP = 'var(--_astryx-text-overflow-wrap,break-word)';
+const wrapOf = (element: Element) =>
+ getComputedStyle(element).overflowWrap.replace(/\s/g, '');
+
describe('Text', () => {
describe('rendering', () => {
it('renders without type prop (defaults to body)', () => {
@@ -224,6 +230,33 @@ describe('Text', () => {
});
});
+ // Text FR3 (spec:AST-020 FR1, WCAG 2.2 1.4.10): a token longer than its line
+ // wraps in text that is not truncated; truncation keeps its own treatment.
+ describe('long unbroken tokens', () => {
+ const token =
+ 'https://example.com/aVeryLongUnbrokenTokenThatIsWiderThan320px';
+
+ it('wraps them in inline and block text that is not truncated', () => {
+ render(
+ <>
+ <Text>{token}</Text>
+ <Text display="block">{`${token}/block`}</Text>
+ </>,
+ );
+ expect(wrapOf(screen.getByText(token))).toBe(DEFAULT_WRAP);
+ expect(wrapOf(screen.getByText(`${token}/block`))).toBe(DEFAULT_WRAP);
+ });
+
+ it('leaves single-line truncation clipping on one line', () => {
+ render(<Text maxLines={1}>{token}</Text>);
+ const style = getComputedStyle(screen.getByText(token));
+ expect(style.whiteSpace).toBe('nowrap');
+ expect(style.textOverflow).toBe('ellipsis');
+ expect(style.wordBreak).toBe('break-all');
+ expect(style.overflowWrap).not.toBe('break-word');
+ });
+ });
+
it('renders the stable target and type data attribute for theme targeting', () => {
render(<Text type="body">Themed Text</Text>);
const element = screen.getByText('Themed Text');
diff --git a/packages/core/src/Text/__tests__/TextReflow.a11y.chromium.spec.ts b/packages/core/src/Text/__tests__/TextReflow.a11y.chromium.spec.ts
new file mode 100644
index 0000000000..039359e4d4
--- /dev/null
+++ b/packages/core/src/Text/__tests__/TextReflow.a11y.chromium.spec.ts
@@ -0,0 +1,142 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file TextReflow.a11y.chromium.spec.ts
+ * @input Storybook stories a11y-text-reflow--untruncated, --truncated,
+ * --command-palette-empty-text and --banner-text at a 320 CSS px viewport
+ * @output Text and Heading FR3 in a real browser (spec:AST-020 FR1, WCAG 2.2
+ * 1.4.10 Reflow): an untruncated long unbroken token wraps (`break-word`),
+ * so the page never scrolls sideways; single-line truncation still clips on
+ * one line; Text inside a container that wraps with `anywhere`
+ * (CommandPaletteEmpty, Banner) keeps `anywhere` and stays inside both
+ * inline edges. A control frame with `overflow-wrap: normal` forced shows
+ * the page scroll the wrap prevents. Frames go to
+ * test-results/text-reflow-evidence/.
+ * @position Text and Heading FR3 browser evidence
+ */
+
+import {expect, test, type Locator, type Page} from '@playwright/test';
+import {
+ DEFAULT_STORYBOOK_DIR,
+ serveStorybook,
+ type StaticServer,
+} from '@astryxdesign/a11y-spec/storybook';
+
+const EVIDENCE = 'test-results/text-reflow-evidence';
+const WIDTH = 320;
+
+let storybook: StaticServer;
+test.beforeAll(async () => {
+ storybook = await serveStorybook(
+ process.env.ASTRYX_STORYBOOK_DIR ?? DEFAULT_STORYBOOK_DIR,
+ );
+});
+test.afterAll(async () => {
+ await storybook?.close();
+});
+test.use({viewport: {width: WIDTH, height: 640}});
+
+async function open(page: Page, story: string): Promise<void> {
+ await page.goto(
+ `${storybook.origin}/iframe.html?id=a11y-text-reflow--${story}&viewMode=story`,
+ );
+ await expect(page.getByTestId(/./).first()).toBeVisible();
+}
+
+/** How far the page scrolls sideways, in CSS px (0 = no horizontal scroll). */
+async function pageOverflow(page: Page): Promise<number> {
+ return page.evaluate(
+ () =>
+ document.documentElement.scrollWidth -
+ document.documentElement.clientWidth,
+ );
+}
+
+/** How many line boxes the element's text occupies. */
+async function lineCount(target: Locator): Promise<number> {
+ return target.evaluate(element => {
+ const range = document.createRange();
+ range.selectNodeContents(element);
+ return new Set(
+ Array.from(range.getClientRects(), rect => Math.round(rect.top)),
+ ).size;
+ });
+}
+
+async function wrapOf(target: Locator): Promise<string> {
+ return target.evaluate(element => getComputedStyle(element).overflowWrap);
+}
+
+/** The element's box stays within both inline edges of the viewport. */
+async function expectInsideViewport(target: Locator): Promise<void> {
+ const box = await target.boundingBox();
+ if (box == null) {
+ throw new Error('the element has no box');
+ }
+ expect(box.x).toBeGreaterThanOrEqual(0);
+ expect(box.x + box.width).toBeLessThanOrEqual(WIDTH);
+}
+
+test('untruncated Text and Heading wrap a long token at 320 px, with no page scroll', async ({
+ page,
+}) => {
+ await open(page, 'untruncated');
+ for (const id of ['heading', 'text-inline', 'text-block']) {
+ const target = page.getByTestId(id);
+ expect(await wrapOf(target), id).toBe('break-word');
+ expect(await lineCount(target), id).toBeGreaterThan(1);
+ }
+ await expectInsideViewport(page.getByTestId('text-block'));
+ expect(await pageOverflow(page)).toBe(0);
+ await page.screenshot({path: `${EVIDENCE}/untruncated-320.png`});
+
+ // Control: without the wrap, the same tokens scroll the page sideways.
+ await page.addStyleTag({
+ content: '[data-testid] { overflow-wrap: normal !important; }',
+ });
+ expect(await pageOverflow(page)).toBeGreaterThan(0);
+ await page.screenshot({path: `${EVIDENCE}/untruncated-320-control.png`});
+});
+
+test('single-line truncation still clips the token on one line at 320 px', async ({
+ page,
+}) => {
+ await open(page, 'truncated');
+ for (const id of ['heading', 'text']) {
+ const target = page.getByTestId(id);
+ const style = await target.evaluate(element => {
+ const computed = getComputedStyle(element);
+ return {
+ whiteSpace: computed.whiteSpace,
+ textOverflow: computed.textOverflow,
+ };
+ });
+ expect(style, id).toEqual({whiteSpace: 'nowrap', textOverflow: 'ellipsis'});
+ expect(await lineCount(target), id).toBe(1);
+ expect(
+ await target.evaluate(
+ element => element.scrollWidth > element.clientWidth,
+ ),
+ id,
+ ).toBe(true);
+ }
+ expect(await pageOverflow(page)).toBe(0);
+ await page.screenshot({path: `${EVIDENCE}/truncated-320.png`});
+});
+
+for (const {story, name} of [
+ {story: 'command-palette-empty-text', name: 'CommandPaletteEmpty'},
+ {story: 'banner-text', name: 'Banner'},
+]) {
+ test(`Text inside ${name} keeps the container's anywhere wrap at 320 px`, async ({
+ page,
+ }) => {
+ await open(page, story);
+ const target = page.getByTestId('text');
+ expect(await wrapOf(target)).toBe('anywhere');
+ expect(await lineCount(target)).toBeGreaterThan(1);
+ await expectInsideViewport(target);
+ expect(await pageOverflow(page)).toBe(0);
+ await page.screenshot({path: `${EVIDENCE}/${name}-text-320.png`});
+ });
+}
diff --git a/packages/core/src/Text/text.stylex.ts b/packages/core/src/Text/text.stylex.ts
index 1cfe26f993..392fa2ada6 100644
--- a/packages/core/src/Text/text.stylex.ts
+++ b/packages/core/src/Text/text.stylex.ts
@@ -229,12 +229,24 @@ export const sizeByLevelStyles = stylex.create({
// Display Styles
// =============================================================================
+// Text that is not truncated. A token longer than its line (a URL, an ID)
+// wraps instead of overflowing, so in ordinary flow text does not force
+// horizontal scrolling at 320 CSS px (WCAG 2.2 1.4.10; Text and Heading FR3).
+// `break-word` keeps min-content, so tables and auto-sized columns lay out
+// ordinary words as before; a flex child still needs `min-width: 0` from its
+// container. A container that wraps with `anywhere` (an empty state, a toast,
+// a banner) sets the private `--_astryx-text-overflow-wrap` beside its own
+// `overflow-wrap`, so Text inside it keeps `anywhere`.
+const NON_TRUNCATED_OVERFLOW_WRAP =
+ 'var(--_astryx-text-overflow-wrap, break-word)';
export const displayStyles = stylex.create({
inline: {
display: 'inline',
+ overflowWrap: NON_TRUNCATED_OVERFLOW_WRAP,
},
block: {
display: 'block',
+ overflowWrap: NON_TRUNCATED_OVERFLOW_WRAP,
},
});
diff --git a/packages/core/src/Toast/Toast.tsx b/packages/core/src/Toast/Toast.tsx
index 5b263e7573..b912c385ef 100644
--- a/packages/core/src/Toast/Toast.tsx
+++ b/packages/core/src/Toast/Toast.tsx
@@ -109,6 +109,8 @@ const styles = stylex.create({
flex: 1,
minWidth: 0,
overflowWrap: 'anywhere',
+ // Text inside keeps `anywhere` too (Text FR3).
+ '--_astryx-text-overflow-wrap': 'anywhere',
},
exiting: {
opacity: 0,
diff --git a/packages/core/src/theme/derivedVarRegistry.test.ts b/packages/core/src/theme/derivedVarRegistry.test.ts
index d8ca838b6a..2c43dbfc10 100644
--- a/packages/core/src/theme/derivedVarRegistry.test.ts
+++ b/packages/core/src/theme/derivedVarRegistry.test.ts
@@ -265,6 +265,19 @@ const DIR_TO_REGISTRY_KEY: Record<string, string> = {
* e.g. Carousel and Thumbnail set --_button-radius for their child Buttons,
* but --_button-radius is documented in Button's doc.
*/
+/**
+ * Private system variables a component sets that are never a theming surface:
+ * no component documents them, and a theme never writes them. Each is named
+ * by the record that requires it.
+ */
+const PRIVATE_SYSTEM_VARS = new Set([
+ // Text and Heading FR3: a container that wraps with `overflow-wrap:
+ // anywhere` passes it to the Text inside it; Text reads it with a
+ // `break-word` fallback. scripts/text-overflow-wrap-anywhere.test.mjs
+ // keeps every such container setting it.
+ '--_astryx-text-overflow-wrap',
+]);
+
const CROSS_COMPONENT_VARS: Record<string, string[]> = {
Carousel: ['--_button-radius'],
Thumbnail: ['--_button-radius'],
@@ -387,7 +400,10 @@ describe('component CSS vars are documented and themeable', () => {
it(`${dir}: all source vars are in doc file`, () => {
const undocumented = sourceVars.filter(
- v => !docVars.includes(v) && !crossVars.has(v),
+ v =>
+ !docVars.includes(v) &&
+ !crossVars.has(v) &&
+ !PRIVATE_SYSTEM_VARS.has(v),
);
expect(
undocumented,
diff --git a/packages/lab/src/DiffViewer/DiffViewer.tsx b/packages/lab/src/DiffViewer/DiffViewer.tsx
index ada55d1fd5..e877d67afa 100644
--- a/packages/lab/src/DiffViewer/DiffViewer.tsx
+++ b/packages/lab/src/DiffViewer/DiffViewer.tsx
@@ -822,6 +822,8 @@ const styles = stylex.create({
whiteSpace: 'pre-wrap',
wordBreak: 'normal',
overflowWrap: 'anywhere',
+ // Text inside keeps `anywhere` too (Text FR3).
+ '--_astryx-text-overflow-wrap': 'anywhere',
},
// Row tints are a background-image layer so a pinned (sticky) cell can lay
// them over an opaque syntax background.
@@ -960,6 +962,8 @@ const annotationStyles = stylex.create({
content: {
direction: {default: null, ':is([dir="rtl"] *)': 'rtl'},
overflowWrap: 'anywhere',
+ // Text inside keeps `anywhere` too (Text FR3).
+ '--_astryx-text-overflow-wrap': 'anywhere',
contain: 'inline-size',
},
});
diff --git a/packages/lab/src/LogStream/LogStream.tsx b/packages/lab/src/LogStream/LogStream.tsx
index 18e2e65453..76003a91fa 100644
--- a/packages/lab/src/LogStream/LogStream.tsx
+++ b/packages/lab/src/LogStream/LogStream.tsx
@@ -257,6 +257,8 @@ const styles = stylex.create({
message: {
minWidth: 0,
overflowWrap: 'anywhere',
+ // Text inside keeps `anywhere` too (Text FR3).
+ '--_astryx-text-overflow-wrap': 'anywhere',
whiteSpace: 'pre-wrap',
},
messageTerminal: {
diff --git a/scripts/text-overflow-wrap-anywhere.test.mjs b/scripts/text-overflow-wrap-anywhere.test.mjs
new file mode 100644
index 0000000000..48514eac28
--- /dev/null
+++ b/scripts/text-overflow-wrap-anywhere.test.mjs
@@ -0,0 +1,106 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file text-overflow-wrap-anywhere.test.mjs
+ * @input Every component source under packages/<package>/src
+ * @output Fails when a style sets `overflowWrap: 'anywhere'` without also
+ * setting the private `--_astryx-text-overflow-wrap` to `anywhere`
+ * @position Guardrail for Text and Heading FR3: untruncated Text and Heading
+ * set `overflow-wrap: var(--_astryx-text-overflow-wrap, break-word)`, so a
+ * container that wraps its content with `anywhere` must pass that down
+ * through the variable, or a `<Text>` it holds stops wrapping long tokens
+ * the container's way (a centered or flex message is then cut off at 320 px).
+ * The variable stops at a layer boundary (layerStructureReset).
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import {describe, expect, it} from 'vitest';
+
+const ROOT = path.resolve(import.meta.dirname, '..');
+const VAR_LINE = "'--_astryx-text-overflow-wrap': 'anywhere'";
+
+function sources(dir) {
+ const out = [];
+ for (const entry of fs.readdirSync(dir, {withFileTypes: true})) {
+ const full = path.join(dir, entry.name);
+ if (entry.isDirectory()) {
+ if (['node_modules', 'dist', '__tests__'].includes(entry.name)) continue;
+ out.push(...sources(full));
+ } else if (
+ /\.(tsx?|mts)$/.test(entry.name) &&
+ !/\.(test|spec|stories)\./.test(entry.name)
+ ) {
+ out.push(full);
+ }
+ }
+ return out;
+}
+
+/**
+ * Each `overflowWrap: 'anywhere'` and whether the style object holding it
+ * also sets the variable (scanned to the object's closing brace).
+ */
+export function anywhereWithoutVar(source) {
+ const misses = [];
+ const lines = source.split('\n');
+ lines.forEach((line, index) => {
+ if (!/overflowWrap:\s*['"]anywhere['"]/.test(line)) return;
+ let depth = 0;
+ let start = index;
+ // Back to the opening brace of the enclosing object.
+ for (; start >= 0; start--) {
+ depth += (lines[start].match(/}/g) ?? []).length;
+ depth -= (lines[start].match(/{/g) ?? []).length;
+ if (depth < 0) break;
+ }
+ depth = 0;
+ let end = index;
+ for (; end < lines.length; end++) {
+ depth += (lines[end].match(/{/g) ?? []).length;
+ depth -= (lines[end].match(/}/g) ?? []).length;
+ if (depth < 0) break;
+ }
+ const block = lines.slice(Math.max(start, 0), end + 1).join('\n');
+ if (!block.includes(VAR_LINE)) misses.push(index + 1);
+ });
+ return misses;
+}
+
+describe('overflow-wrap: anywhere reaches Text through the private variable', () => {
+ it('flags a style that sets anywhere without the variable, and passes one that sets both', () => {
+ expect(
+ anywhereWithoutVar(
+ "const s = {\n message: {\n overflowWrap: 'anywhere',\n },\n};",
+ ),
+ ).toEqual([3]);
+ expect(
+ anywhereWithoutVar(
+ `const s = {\n message: {\n overflowWrap: 'anywhere',\n ${VAR_LINE},\n },\n};`,
+ ),
+ ).toEqual([]);
+ });
+
+ it('stops at a layer boundary, so Text in a layer keeps its own wrap (AST-038 FR7)', () => {
+ const reset = fs.readFileSync(
+ path.join(ROOT, 'packages/core/src/Layer/layerStructureReset.stylex.ts'),
+ 'utf8',
+ );
+ expect(reset).toContain("'--_astryx-text-overflow-wrap': 'initial'");
+ });
+
+ it('holds for every package source', () => {
+ const packages = path.join(ROOT, 'packages');
+ const offenders = [];
+ for (const pkg of fs.readdirSync(packages)) {
+ const src = path.join(packages, pkg, 'src');
+ if (!fs.existsSync(src)) continue;
+ for (const file of sources(src)) {
+ for (const line of anywhereWithoutVar(fs.readFileSync(file, 'utf8'))) {
+ offenders.push(`${path.relative(ROOT, file)}:${line}`);
+ }
+ }
+ }
+ expect(offenders).toEqual([]);
+ });
+});