An open source design system that's fully customizable and agent ready
TypeScript
fix(lab): a11y minors — Step status text, LogStream live muting, SVGIcon labels, ChatReasoning collapse (#4384)
Baraa Hamodi40065e055a05
diff --git a/.changeset/a11y-lab-minors-i18n.md b/.changeset/a11y-lab-minors-i18n.mdnew file mode 100644index 0000000000..ee221fc917--- /dev/null+++ b/.changeset/a11y-lab-minors-i18n.md@@ -0,0 +1,6 @@+---+'@astryxdesign/core': patch+---++[fix] i18n: add `@astryx.step.*` catalog keys (`goToStep`, `goToStepWithStatus`, `status.completed`/`status.warning`/`status.error`) backing the lab Stepper's localized status text and clickable-step accessible names.+@bhamodidiff --git a/packages/core/locales/en.json b/packages/core/locales/en.jsonindex 5ee38041a8..31eb1c6bb4 100644--- a/packages/core/locales/en.json+++ b/packages/core/locales/en.json@@ -879,6 +879,26 @@"defaultMessage": "Expand all rows","description": "Screen-reader-only label on the header expand-all/collapse-all button when at least one row is collapsed (clicking expands every expandable row). Part of the four-way set."},+ "@astryx.step.goToStep": {+ "defaultMessage": "Go to step {stepNumber, number}: {label}",+ "description": "Accessible name for a clickable step in the lab Stepper. {stepNumber} is the 1-based position, {label} is the step's visible label."+ },+ "@astryx.step.goToStepWithStatus": {+ "defaultMessage": "Go to step {stepNumber, number}: {label}, {status}",+ "description": "Accessible name for a clickable lab Stepper step that also carries a status. {status} is one of the translated `step.status.*` words (completed/warning/error). Keep the pattern parallel to `step.goToStep`."+ },+ "@astryx.step.status.completed": {+ "defaultMessage": "completed",+ "description": "Screen-reader-only status word rendered next to a lab Stepper step label when the step is done (either progress-completed or status=success). Lowercase adjective; it is read mid-sentence after the step label."+ },+ "@astryx.step.status.warning": {+ "defaultMessage": "warning",+ "description": "Screen-reader-only status word rendered next to a lab Stepper step label when status=warning. Lowercase noun/adjective; read mid-sentence after the step label."+ },+ "@astryx.step.status.error": {+ "defaultMessage": "error",+ "description": "Screen-reader-only status word rendered next to a lab Stepper step label when status=error. Lowercase noun; read mid-sentence after the step label."+ },"@astryx.tableTree.collapseRow": {"defaultMessage": "Collapse row","description": "Aria label for the Table tree-data expander chevron when the row is currently expanded."diff --git a/packages/lab/src/ChatReasoning/ChatReasoning.test.tsx b/packages/lab/src/ChatReasoning/ChatReasoning.test.tsxindex f8223117e3..70861920d7 100644--- a/packages/lab/src/ChatReasoning/ChatReasoning.test.tsx+++ b/packages/lab/src/ChatReasoning/ChatReasoning.test.tsx@@ -53,4 +53,29 @@ describe('ChatReasoning', () => {render(<ChatReasoning defaultIsExpanded>Content</ChatReasoning>);expect(screen.getByRole('button')).toHaveAttribute('aria-expanded', 'true');});++ it('wires the trigger to the content region via aria-controls', () => {+ render(<ChatReasoning>Full reasoning body</ChatReasoning>);+ const button = screen.getByRole('button');+ const controlsId = button.getAttribute('aria-controls');+ expect(controlsId).toBeTruthy();+ const region = document.getElementById(controlsId as string);+ expect(region).not.toBeNull();+ expect(region).toHaveTextContent('Full reasoning body');+ });++ it('marks the collapsed content inert and lifts it when expanded', () => {+ render(<ChatReasoning>Hidden reasoning</ChatReasoning>);+ const button = screen.getByRole('button');+ const region = document.getElementById(+ button.getAttribute('aria-controls') as string,+ ) as HTMLElement;+ // Collapsed: visually clipped by the 0fr grid row, so it must also be+ // removed from the accessibility tree.+ expect(region).toHaveAttribute('inert');+ fireEvent.click(button);+ expect(region).not.toHaveAttribute('inert');+ fireEvent.click(button);+ expect(region).toHaveAttribute('inert');+ });});diff --git a/packages/lab/src/ChatReasoning/ChatReasoning.tsx b/packages/lab/src/ChatReasoning/ChatReasoning.tsxindex d0eec729ab..1fa0cbfa2b 100644--- a/packages/lab/src/ChatReasoning/ChatReasoning.tsx+++ b/packages/lab/src/ChatReasoning/ChatReasoning.tsx@@ -15,7 +15,7 @@* Expandable on click.*/-import {useState, useCallback, type ReactNode} from 'react';+import {useCallback, useId, useState, type ReactNode} from 'react';import type {BaseProps} from '@astryxdesign/core';import * as stylex from '@stylexjs/stylex';import {@@ -245,6 +245,7 @@ export function ChatReasoning(props: ChatReasoningProps) {const [internalExpanded, setInternalExpanded] = useState(defaultIsExpanded);const isControlled = controlledExpanded !== undefined;const isExpanded = isControlled ? controlledExpanded : internalExpanded;+ const contentId = useId();const toggle = useCallback(() => {const next = !isExpanded;@@ -272,6 +273,7 @@ export function ChatReasoning(props: ChatReasoningProps) {role="button"tabIndex={0}aria-expanded={isExpanded}+ aria-controls={contentId}onClick={toggle}onKeyDown={e => {if (e.key === 'Enter' || e.key === ' ') {@@ -310,6 +312,12 @@ export function ChatReasoning(props: ChatReasoningProps) {</div><div+ id={contentId}+ // Collapsed content is only clipped visually (0fr grid row + overflow+ // hidden), which leaves it in the accessibility tree. `inert` removes+ // it from AT and the tab order while keeping the element rendered, so+ // the grid-template-rows expand/collapse transition still runs.+ inert={!isExpanded}{...stylex.props(styles.content, isExpanded && styles.contentExpanded)}><div {...stylex.props(styles.contentInner)}><div {...stylex.props(styles.contentPadding)}>{children}</div>diff --git a/packages/lab/src/LogStream/LogStream.doc.mjs b/packages/lab/src/LogStream/LogStream.doc.mjsindex b0d4ba6d30..b2ab931a05 100644--- a/packages/lab/src/LogStream/LogStream.doc.mjs+++ b/packages/lab/src/LogStream/LogStream.doc.mjs@@ -11,7 +11,7 @@ export const docs = {usage: {description:- 'Experimental streaming log viewer: mono grid rows (timestamp | level | source | message) with token-derived level accents, expandable per-row detail panels, follow-scroll live tailing with a "Jump to latest" affordance, and an always-dark terminal variant. Appended rows fade in via @starting-style.',+ 'Experimental streaming log viewer: mono grid rows (timestamp | level | source | message) with token-derived level accents, expandable per-row detail panels, follow-scroll live tailing with a "Jump to latest" affordance, and an always-dark terminal variant. Appended rows fade in via @starting-style. Live announcements follow the pinning state: the role="log" region is aria-live="polite" only while following the tail, and aria-live="off" while unfollowed, so a busy stream never floods assistive tech.',},props: [diff --git a/packages/lab/src/LogStream/LogStream.test.tsx b/packages/lab/src/LogStream/LogStream.test.tsxindex 7d1310a579..68105f75bd 100644--- a/packages/lab/src/LogStream/LogStream.test.tsx+++ b/packages/lab/src/LogStream/LogStream.test.tsx@@ -223,6 +223,31 @@ describe('LogStream', () => {expect(scroller.scrollTop).toBe(1000);});+ it('mutes live announcements while unfollowed and restores them while following (controlled)', () => {+ const {rerender} = render(+ <LogStream entries={ENTRIES} isFollowing={false} />,+ );+ const log = screen.getByRole('log');+ expect(log).toHaveAttribute('aria-live', 'off');+ rerender(<LogStream entries={ENTRIES} isFollowing />);+ expect(log).toHaveAttribute('aria-live', 'polite');+ });++ it('unmutes the live region when "Jump to latest" resumes following (uncontrolled)', () => {+ render(<LogStream entries={ENTRIES} maxHeight={200} />);+ const log = screen.getByRole('log');+ // Initially unpinned — the stream must not announce.+ expect(log).toHaveAttribute('aria-live', 'off');+ // Scroll away from the tail so the "Jump to latest" affordance appears.+ setScrollMetrics(log, {scrollHeight: 1000, clientHeight: 200});+ log.scrollTop = 100;+ fireEvent.scroll(log);+ expect(log).toHaveAttribute('aria-live', 'off');+ // Re-pinning restores polite announcements.+ fireEvent.click(screen.getByRole('button', {name: /jump to latest/i}));+ expect(log).toHaveAttribute('aria-live', 'polite');+ });+it('renderEntry replaces the default row', () => {render(<LogStreamdiff --git a/packages/lab/src/LogStream/LogStream.tsx b/packages/lab/src/LogStream/LogStream.tsxindex 400905b23c..5b2475c366 100644--- a/packages/lab/src/LogStream/LogStream.tsx+++ b/packages/lab/src/LogStream/LogStream.tsx@@ -329,6 +329,10 @@ const LEVEL_STYLE_TERMINAL: Record<LogStreamLevel, stylex.StyleXStyles> = {* polling; rows use `content-visibility: auto` for offscreen skip but are* NOT virtualized (window large streams in the caller).*+ * Live announcements are tied to follow pinning: the `role="log"` region is+ * `aria-live="polite"` only while following the tail and `aria-live="off"`+ * while unfollowed, so appends never flood assistive tech.+ ** @example* ```* <LogStream@@ -538,6 +542,12 @@ export function LogStream({ref={scrollerRef}role="log"aria-label={label}+ // role="log" is implicitly aria-live="polite" — on a busy stream that+ // floods assistive tech with every appended row (WCAG 2.2.2 / 4.1.3).+ // Follow-pinning doubles as the mute switch: while the user is away+ // from the tail (unfollowed), the region is aria-live="off"; resuming+ // follow ("Jump to latest") restores polite announcements.+ aria-live={following ? 'polite' : 'off'}onScroll={handleScroll}{...stylex.props(styles.scroller(maxHeight ?? null))}>{entries.map(entry => (diff --git a/packages/lab/src/SVGIcon/SVGIcon.test.tsx b/packages/lab/src/SVGIcon/SVGIcon.test.tsxnew file mode 100644index 0000000000..0be95605aa--- /dev/null+++ b/packages/lab/src/SVGIcon/SVGIcon.test.tsx@@ -0,0 +1,40 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++import {describe, it, expect} from 'vitest';+import {render, screen} from '@testing-library/react';+import {SVGIcon} from './SVGIcon';+import {bellIcon} from './icons';++describe('SVGIcon', () => {+ it('defaults to decorative (aria-hidden) when no accessible name is given', () => {+ const {container} = render(<SVGIcon icon={bellIcon} />);+ const svg = container.querySelector('svg');+ expect(svg).toHaveAttribute('aria-hidden', 'true');+ expect(svg).not.toHaveAttribute('role');+ });++ it('respects a consumer aria-label: role="img" and no aria-hidden', () => {+ render(<SVGIcon icon={bellIcon} aria-label="Notifications" />);+ const svg = screen.getByRole('img', {name: 'Notifications'});+ expect(svg).not.toHaveAttribute('aria-hidden');+ });++ it('respects a consumer aria-labelledby: role="img" and no aria-hidden', () => {+ render(+ <>+ <span id="svg-icon-lbl">Alerts</span>+ <SVGIcon icon={bellIcon} aria-labelledby="svg-icon-lbl" />+ </>,+ );+ const svg = screen.getByRole('img', {name: 'Alerts'});+ expect(svg).not.toHaveAttribute('aria-hidden');+ });++ it('still lets an explicit aria-hidden from the consumer win', () => {+ const {container} = render(+ <SVGIcon icon={bellIcon} aria-label="Notifications" aria-hidden="true" />,+ );+ const svg = container.querySelector('svg');+ expect(svg).toHaveAttribute('aria-hidden', 'true');+ });+});diff --git a/packages/lab/src/SVGIcon/SVGIcon.tsx b/packages/lab/src/SVGIcon/SVGIcon.tsxindex b8d1e3c1e8..0763b03abd 100644--- a/packages/lab/src/SVGIcon/SVGIcon.tsx+++ b/packages/lab/src/SVGIcon/SVGIcon.tsx@@ -32,11 +32,7 @@ import {themeProps} from '@astryxdesign/core/utils';// =============================================================================export type SVGIconVariation =- | 'linear'- | 'bold'- | 'twotone'- | 'bulk'- | 'broken';+ 'linear' | 'bold' | 'twotone' | 'bulk' | 'broken';export type SVGIconSize = 'xsm' | 'sm' | 'md' | 'lg';export type SVGIconColor =| 'primary'@@ -359,11 +355,23 @@ export function SVGIcon({...(strokeWidth != null ? strokeWidthOverride : undefined),};+ // Decorative by default, meaningful when named — mirroring core Icon's+ // `label` logic. When the consumer passes an accessible name+ // (aria-label / aria-labelledby), expose the svg as role="img" instead of+ // hiding it: an aria-hidden element is removed from the accessibility+ // tree, so its accessible name would be ignored. Spread BEFORE {...props}+ // so an explicit aria-hidden/role from the consumer always wins.+ const hasAccessibleName =+ props['aria-label'] != null || props['aria-labelledby'] != null;+ const a11yProps = hasAccessibleName+ ? ({role: 'img'} as const)+ : ({'aria-hidden': true} as const);+return (<svgxmlns="http://www.w3.org/2000/svg"viewBox={viewBox}- aria-hidden="true"+ {...a11yProps}{...mergeProps(themeProps('svg-icon', {variation, size, color}),stylex.props(diff --git a/packages/lab/src/Stepper/Step.tsx b/packages/lab/src/Stepper/Step.tsxindex 7c6a53dcdc..0c35e0a49b 100644--- a/packages/lab/src/Stepper/Step.tsx+++ b/packages/lab/src/Stepper/Step.tsx@@ -31,6 +31,8 @@ import {import {mergeProps} from '@astryxdesign/core/utils';import type {BaseProps} from '@astryxdesign/core';import {Icon} from '@astryxdesign/core/Icon';+import {VisuallyHidden} from '@astryxdesign/core/VisuallyHidden';+import {useTranslator} from '@astryxdesign/core/i18n';import {useStepperContext} from './StepperContext';import {themeProps} from '@astryxdesign/core/utils';import type {StepStatus} from './StepStatus';@@ -81,6 +83,11 @@ export interface StepProps extends BaseProps<HTMLLIElement> {* `accent` is color-only. The current (in-progress) step always keeps its* current-step indicator regardless of `status`. Never recolors the* connector/track.+ *+ * Because the indicator glyphs are decorative (aria-hidden), the status also+ * reaches assistive technology as text: visually hidden "completed" /+ * "warning" / "error" next to the label, and composed into the accessible+ * name of clickable steps.*/status?: StepStatus;/**@@ -630,6 +637,7 @@ export function Step({'data-testid': dataTestId,...rest}: StepProps) {+ const t = useTranslator();const ctx = useStepperContext();const {activeStep,@@ -806,6 +814,36 @@ export function Step({}}+ // Every indicator glyph above is aria-hidden (pure decoration), so the+ // step's progress/status must also reach assistive tech as text+ // (WCAG 1.4.1 / 1.3.1). `error`/`warning` announce the semantic status;+ // `success` and a completed step both announce "completed". The current+ // step is announced via aria-current="step" instead, and not-started steps+ // stay silent (the default state needs no qualifier).+ const statusText: string | null =+ status === 'error'+ ? t('@astryx.step.status.error')+ : status === 'warning'+ ? t('@astryx.step.status.warning')+ : status === 'success' || progress === 'completed'+ ? t('@astryx.step.status.completed')+ : null;++ // Rendered next to the label: hidden text for static steps, and composed+ // into the button's accessible name for clickable ones (an aria-label on+ // the button would otherwise override the hidden text). Two separate keys+ // rather than string concatenation so translations control the joiner.+ const statusTextNode =+ statusText != null ? <VisuallyHidden>{statusText}</VisuallyHidden> : null;+ const stepAriaLabel =+ statusText != null+ ? t('@astryx.step.goToStepWithStatus', {+ stepNumber: step + 1,+ label,+ status: statusText,+ })+ : t('@astryx.step.goToStep', {stepNumber: step + 1, label});+const hasIndicator = indicator !== 'none';const isNumber =hasIndicator &&@@ -827,6 +865,7 @@ export function Step({<div {...stylex.props(styles.iconLabelRow)}>{indicatorNode}<span {...stylex.props(styles.label, labelColorStyle)}>{label}</span>+ {statusTextNode}{isOptional && (<><span {...stylex.props(styles.optionalDot)}>•</span>@@ -900,6 +939,7 @@ export function Step({isVertical ? styles.otLabelRowStart : styles.otLabelRowCenter,)}><span {...stylex.props(styles.label, labelColorStyle)}>{label}</span>+ {statusTextNode}{isOptional && (<><span {...stylex.props(styles.optionalDot)}>•</span>@@ -980,7 +1020,7 @@ export function Step({<buttontype="button"onClick={handleClick}- aria-label={`Go to step ${step + 1}: ${label}`}+ aria-label={stepAriaLabel}{...stylex.props(styles.otInteractive,styles.otRowWrap,@@ -1058,7 +1098,7 @@ export function Step({<buttontype="button"onClick={handleClick}- aria-label={`Go to step ${step + 1}: ${label}`}+ aria-label={stepAriaLabel}{...stylex.props(styles.otInteractive,styles.otColWrap,@@ -1112,7 +1152,7 @@ export function Step({<buttontype="button"onClick={handleClick}- aria-label={`Go to step ${step + 1}: ${label}`}+ aria-label={stepAriaLabel}{...stylex.props(styles.buttonReset,styles.focusRing,@@ -1168,7 +1208,7 @@ export function Step({<buttontype="button"onClick={handleClick}- aria-label={`Go to step ${step + 1}: ${label}`}+ aria-label={stepAriaLabel}{...stylex.props(styles.buttonReset,styles.focusRing,diff --git a/packages/lab/src/Stepper/Stepper.test.tsx b/packages/lab/src/Stepper/Stepper.test.tsxindex 1320f96de1..1f863a793d 100644--- a/packages/lab/src/Stepper/Stepper.test.tsx+++ b/packages/lab/src/Stepper/Stepper.test.tsx@@ -1,7 +1,7 @@// Copyright (c) Meta Platforms, Inc. and affiliates.import {describe, it, expect, vi} from 'vitest';-import {render, screen} from '@testing-library/react';+import {render, screen, within} from '@testing-library/react';import userEvent from '@testing-library/user-event';import {Stepper} from './Stepper';import {Step} from './Step';@@ -95,7 +95,7 @@ describe('Stepper', () => {</Stepper>,);await user.click(- screen.getByRole('button', {name: 'Go to step 1: Step 1'}),+ screen.getByRole('button', {name: 'Go to step 1: Step 1, completed'}),);expect(handleClick).toHaveBeenCalledWith(0);});@@ -156,7 +156,7 @@ describe('Stepper', () => {</Stepper>,);expect(- screen.queryByRole('button', {name: 'Go to step 1: Step 1'}),+ screen.queryByRole('button', {name: /Go to step 1: Step 1/}),).not.toBeInTheDocument();});@@ -412,4 +412,85 @@ describe('Stepper', () => {expect(future.textContent).not.toContain('2');expect(future.querySelector('svg')).toBeTruthy();});++ it('exposes progress/status as visually hidden text (indicators are aria-hidden)', () => {+ render(+ <Stepper activeStep={2}>+ <Step step={0} label="Account" data-testid="done" />+ <Step step={1} label="Payment" status="error" data-testid="failed" />+ <Step step={2} label="Review" data-testid="current" />+ <Step step={3} label="Confirm" data-testid="upcoming" />+ </Stepper>,+ );+ // Completed step announces "completed"; error status wins over completion.+ expect(+ within(screen.getByTestId('done')).getByText('completed'),+ ).toBeInTheDocument();+ expect(+ within(screen.getByTestId('failed')).getByText('error'),+ ).toBeInTheDocument();+ expect(+ within(screen.getByTestId('failed')).queryByText('completed'),+ ).not.toBeInTheDocument();+ // Current step is announced via aria-current, not hidden text; upcoming+ // steps stay silent.+ expect(+ within(screen.getByTestId('current')).queryByText('completed'),+ ).not.toBeInTheDocument();+ expect(+ within(screen.getByTestId('upcoming')).queryByText(+ /completed|error|warning/,+ ),+ ).not.toBeInTheDocument();+ });++ it('exposes warning and success statuses as visually hidden text', () => {+ render(+ <Stepper activeStep={2}>+ <Step step={0} label="Build" status="warning" data-testid="warned" />+ <Step step={1} label="Deploy" status="success" data-testid="passed" />+ </Stepper>,+ );+ expect(+ within(screen.getByTestId('warned')).getByText('warning'),+ ).toBeInTheDocument();+ expect(+ within(screen.getByTestId('passed')).getByText('completed'),+ ).toBeInTheDocument();+ });++ it('composes status into the accessible name of clickable steps', () => {+ render(+ <Stepper activeStep={2} onStepClick={() => {}}>+ <Step step={0} label="Account" />+ <Step step={1} label="Payment" status="error" />+ <Step step={2} label="Review" />+ </Stepper>,+ );+ expect(+ screen.getByRole('button', {name: 'Go to step 1: Account, completed'}),+ ).toBeInTheDocument();+ expect(+ screen.getByRole('button', {name: 'Go to step 2: Payment, error'}),+ ).toBeInTheDocument();+ // The current step gets no status suffix (aria-current covers it).+ expect(+ screen.getByRole('button', {name: 'Go to step 3: Review'}),+ ).toBeInTheDocument();+ });++ it('exposes hidden status text in the on-track layout too', () => {+ render(+ <Stepper activeStep={1} indicatorPosition="on-track">+ <Step step={0} label="Account" data-testid="ot-done" />+ <Step step={1} label="Payment" data-testid="ot-current" />+ </Stepper>,+ );+ expect(+ within(screen.getByTestId('ot-done')).getByText('completed'),+ ).toBeInTheDocument();+ expect(+ within(screen.getByTestId('ot-current')).queryByText('completed'),+ ).not.toBeInTheDocument();+ });});