@astryxdesign/core 0.1.8 → 0.1.9-canary.08c278e

package/src/FieldStatus/FieldStatus.doc.mjs

@@ -8,7 +8,7 @@ export const docs = {
   category: 'Data Input',
   isHiddenFromOverview: true,
   description:
-    'Status message component for form field validation feedback.',
+    'Status message component for form field validation feedback. Messages are announced to screen readers through persistent live regions (assertive for errors, polite otherwise), so conditional mounting is safe.',
   theming: {
     targets: [
       {className: 'astryx-field-status', visualProps: ['type', 'variant']},
@@ -66,12 +66,24 @@ export const docs = {
 /** @type {import('../docs-types').TranslationDoc} */
 export const docsDense = {
   description:
-    'Validation feedback message for fields/custom controls. Supports error, warning, success and attached/detached variants.',
+    'Validation feedback message for fields/custom controls. Supports error, warning, success and attached/detached variants. Announced via persistent live regions (assertive for errors, polite otherwise).',
   usage: {
     bestPractices: [
-      {guidance: true, description: 'Use attached status below bordered inputs when message belongs to that input.'},
-      {guidance: true, description: 'Use detached status for checkboxes, switches, and custom controls where overlap is visually awkward.'},
-      {guidance: false, description: 'Use FieldStatus for general alerts or page-level notices; use Banner or Toast instead.'},
+      {
+        guidance: true,
+        description:
+          'Use attached status below bordered inputs when message belongs to that input.',
+      },
+      {
+        guidance: true,
+        description:
+          'Use detached status for checkboxes, switches, and custom controls where overlap is visually awkward.',
+      },
+      {
+        guidance: false,
+        description:
+          'Use FieldStatus for general alerts or page-level notices; use Banner or Toast instead.',
+      },
     ],
   },
   propDescriptions: {

package/src/FieldStatus/FieldStatus.test.tsx

@@ -9,15 +9,27 @@
  * SYNC: When FieldStatus.tsx changes, update tests to match new behavior
  */
 
-import {describe, it, expect, vi} from 'vitest';
-import {render, screen} from '@testing-library/react';
+import {describe, it, expect, vi, afterEach} from 'vitest';
+import {render, screen, waitFor} from '@testing-library/react';
 import * as stylex from '@stylexjs/stylex';
 import {FieldStatus} from './FieldStatus';
+import {__resetLiveRegionsForTest} from '../hooks/useAnnounce';
 
 const testStyles = stylex.create({
   custom: {color: 'rebeccapurple'},
 });
 
+function politeRegion(): HTMLElement | null {
+  return document.querySelector('[data-astryx-live-region="polite"]');
+}
+function assertiveRegion(): HTMLElement | null {
+  return document.querySelector('[data-astryx-live-region="assertive"]');
+}
+
+afterEach(() => {
+  __resetLiveRegionsForTest();
+});
+
 describe('FieldStatus', () => {
   it('renders the message text', () => {
     render(<FieldStatus type="error" message="This field is required" />);
@@ -29,47 +41,75 @@ describe('FieldStatus', () => {
     expect(screen.getByTestId('fs').tagName).toBe('DIV');
   });
 
-  describe('role semantics', () => {
-    // Errors are urgent — they get role="alert" so assistive tech interrupts.
-    it('uses role="alert" for error status', () => {
-      render(<FieldStatus type="error" message="msg" />);
-      expect(screen.getByRole('alert')).toHaveTextContent('msg');
+  describe('screen-reader announcements', () => {
+    // The rendered element is NOT itself a live region: FieldStatus is
+    // conditionally mounted by every caller, and live regions born together
+    // with their content are not reliably announced. Announcements go through
+    // the persistent useAnnounce singletons instead.
+    it('does not carry role or aria-live on the rendered element', () => {
+      render(<FieldStatus type="error" message="msg" data-testid="fs" />);
+      const el = screen.getByTestId('fs');
+      expect(el).not.toHaveAttribute('role');
+      expect(el).not.toHaveAttribute('aria-live');
     });
 
-    // Non-error statuses are advisory — role="status" is a polite live region.
-    it('uses role="status" for warning status', () => {
-      render(<FieldStatus type="warning" message="msg" data-testid="fs" />);
-      expect(screen.getByTestId('fs')).toHaveAttribute('role', 'status');
-      expect(screen.queryByRole('alert')).not.toBeInTheDocument();
+    // Errors are urgent — they interrupt via the assertive channel.
+    it('announces error messages assertively, including on first mount', async () => {
+      render(<FieldStatus type="error" message="This field is required" />);
+      await waitFor(() => {
+        expect(assertiveRegion()).toHaveTextContent('This field is required');
+      });
+      expect(politeRegion()).toHaveTextContent('');
     });
 
-    it('uses role="status" for success status', () => {
-      render(<FieldStatus type="success" message="msg" data-testid="fs" />);
-      expect(screen.getByTestId('fs')).toHaveAttribute('role', 'status');
+    it('announces warning messages politely', async () => {
+      render(<FieldStatus type="warning" message="Check this value" />);
+      await waitFor(() => {
+        expect(politeRegion()).toHaveTextContent('Check this value');
+      });
+      expect(assertiveRegion()).toHaveTextContent('');
     });
-  });
 
-  describe('aria-live politeness', () => {
-    // Error → assertive so screen readers announce immediately.
-    it('sets aria-live="assertive" for error', () => {
-      render(<FieldStatus type="error" message="msg" data-testid="fs" />);
-      expect(screen.getByTestId('fs')).toHaveAttribute(
-        'aria-live',
-        'assertive',
-      );
+    it('announces success messages politely', async () => {
+      render(<FieldStatus type="success" message="Looks good" />);
+      await waitFor(() => {
+        expect(politeRegion()).toHaveTextContent('Looks good');
+      });
     });
 
-    it('sets aria-live="polite" for warning', () => {
-      render(<FieldStatus type="warning" message="msg" data-testid="fs" />);
-      expect(screen.getByTestId('fs')).toHaveAttribute('aria-live', 'polite');
+    it('announces message changes', async () => {
+      const {rerender} = render(<FieldStatus type="error" message="First" />);
+      await waitFor(() => {
+        expect(assertiveRegion()).toHaveTextContent('First');
+      });
+      rerender(<FieldStatus type="error" message="Second" />);
+      await waitFor(() => {
+        expect(assertiveRegion()).toHaveTextContent('Second');
+      });
+    });
+
+    // Severity changes re-route the announcement to the matching channel.
+    it('re-routes to the polite channel when type changes from error', async () => {
+      const {rerender} = render(<FieldStatus type="error" message="msg" />);
+      await waitFor(() => {
+        expect(assertiveRegion()).toHaveTextContent('msg');
+      });
+      rerender(<FieldStatus type="success" message="msg" />);
+      await waitFor(() => {
+        expect(politeRegion()).toHaveTextContent('msg');
+      });
     });
 
-    it('sets aria-live="polite" for success', () => {
-      render(<FieldStatus type="success" message="msg" data-testid="fs" />);
-      expect(screen.getByTestId('fs')).toHaveAttribute('aria-live', 'polite');
+    it('does not announce an empty message', () => {
+      render(<FieldStatus type="error" message="" />);
+      // The live regions are created lazily on first announce; an empty
+      // message must not trigger one.
+      expect(assertiveRegion()).toBeNull();
+      expect(politeRegion()).toBeNull();
     });
 
-    // The element is a live region, never hidden from assistive tech.
+    // The visible message stays perceivable by assistive tech (it is the
+    // aria-describedby target for the input).
     it('does not mark itself aria-hidden', () => {
       render(<FieldStatus type="error" message="msg" data-testid="fs" />);
       expect(screen.getByTestId('fs')).not.toHaveAttribute('aria-hidden');
@@ -245,20 +285,90 @@ describe('FieldStatus', () => {
       expect(screen.getByTestId('fs')).toHaveTextContent('Second');
     });
 
-    // Switching from error to a non-error type must relax both the role and
-    // the live-region politeness in lockstep.
-    it('relaxes role and aria-live when type changes from error', () => {
+    // The element must never regain live-region semantics when the type
+    // changes — announcements always flow through the persistent regions.
+    it('keeps the element role-free when type changes from error', () => {
       const {rerender} = render(
         <FieldStatus type="error" message="msg" data-testid="fs" />,
       );
-      let el = screen.getByTestId('fs');
-      expect(el).toHaveAttribute('role', 'alert');
-      expect(el).toHaveAttribute('aria-live', 'assertive');
+      expect(screen.getByTestId('fs')).not.toHaveAttribute('role');
 
       rerender(<FieldStatus type="success" message="msg" data-testid="fs" />);
-      el = screen.getByTestId('fs');
-      expect(el).toHaveAttribute('role', 'status');
-      expect(el).toHaveAttribute('aria-live', 'polite');
+      const el = screen.getByTestId('fs');
+      expect(el).not.toHaveAttribute('role');
+      expect(el).not.toHaveAttribute('aria-live');
+    });
+  });
+
+  // The detached message must convey status by more than color/position:
+  // a leading status glyph precedes the message text (WCAG 1.4.1). The glyph
+  // is decorative for AT (aria-hidden) because the message text already names
+  // the status in words and it is announced via the live region.
+  describe('detached leading status icon (use-of-color a11y)', () => {
+    it('renders a leading status icon before the message for the detached variant', () => {
+      render(
+        <FieldStatus
+          type="error"
+          message="Something went wrong"
+          variant="detached"
+          data-testid="fs"
+        />,
+      );
+      const el = screen.getByTestId('fs');
+      const icon = el.querySelector('[aria-hidden="true"]');
+      const text = screen.getByText('Something went wrong');
+      expect(icon).toBeInTheDocument();
+      // Icon comes before the message text in document order.
+      expect(
+        icon!.compareDocumentPosition(text) & Node.DOCUMENT_POSITION_FOLLOWING,
+      ).toBeTruthy();
+    });
+
+    it('marks the status icon aria-hidden (visual redundancy, not a second announcement)', () => {
+      render(
+        <FieldStatus
+          type="warning"
+          message="Heads up"
+          variant="detached"
+          data-testid="fs"
+        />,
+      );
+      const icon = screen
+        .getByTestId('fs')
+        .querySelector('[aria-hidden="true"]');
+      expect(icon).toBeInTheDocument();
+      expect(icon).toHaveAttribute('aria-hidden', 'true');
+    });
+
+    it('renders a status icon for each status type in the detached variant', () => {
+      for (const type of ['error', 'warning', 'success'] as const) {
+        const {unmount} = render(
+          <FieldStatus
+            type={type}
+            message="msg"
+            variant="detached"
+            data-testid="fs"
+          />,
+        );
+        expect(
+          screen.getByTestId('fs').querySelector('[aria-hidden="true"]'),
+        ).toBeInTheDocument();
+        unmount();
+      }
+    });
+
+    it('does not render a leading status icon for the attached variant', () => {
+      render(
+        <FieldStatus
+          type="error"
+          message="msg"
+          variant="attached"
+          data-testid="fs"
+        />,
+      );
+      expect(
+        screen.getByTestId('fs').querySelector('[aria-hidden="true"]'),
+      ).toBeNull();
     });
   });
 

package/src/FieldStatus/FieldStatus.tsx

@@ -2,7 +2,7 @@
 
 /**
  * @file FieldStatus.tsx
- * @input Uses React, stylex, theme tokens
+ * @input Uses React, stylex, theme tokens, useAnnounce, Icon
  * @output Exports FieldStatus component, FieldStatusProps
  * @position Core implementation; consumed by Field, Switch, CheckboxInput, and the FieldStatus entrypoint
  *
@@ -16,9 +16,10 @@
 
 'use client';
 
-import React from 'react';
+import React, {useEffect} from 'react';
 import * as stylex from '@stylexjs/stylex';
 import type {BaseProps} from '../BaseProps';
+import {useAnnounce} from '../hooks/useAnnounce';
 import {mergeProps} from '../utils';
 import {
   colorVars,
@@ -30,6 +31,19 @@ import {
 import type {InputStatusType} from '../Field/types';
 import {useEntryAnimation} from '../hooks/useEntryAnimation';
 import {themeProps} from '../utils/themeProps';
+import {Icon} from '../Icon';
+import type {IconName} from '../Icon';
+
+/**
+ * Maps each status type to its status glyph. Mirrors the mapping the input
+ * controls already use for the on-field status affordance, so the detached
+ * message shows the same icon a consumer sees elsewhere for that status.
+ */
+const statusIconMap: Record<InputStatusType, IconName> = {
+  warning: 'warning',
+  error: 'error',
+  success: 'success',
+};
 
 const styles = stylex.create({
   base: {
@@ -51,6 +65,17 @@ const styles = stylex.create({
     paddingInline: spacingVars['--spacing-2'],
     borderRadius: radiusVars['--radius-element'],
   },
+  detachedContent: {
+    display: 'flex',
+    alignItems: 'flex-start',
+    gap: spacingVars['--spacing-1'],
+  },
+  detachedIcon: {
+    // Match the height of the first text line so the glyph top-aligns to it
+    // (rather than to the flex box) when the message wraps to multiple lines.
+    lineHeight: typeScaleVars['--text-supporting-leading'],
+    flexShrink: 0,
+  },
 });
 
 const colorStyles = stylex.create({
@@ -113,6 +138,21 @@ export interface FieldStatusProps extends BaseProps<HTMLDivElement> {
 /**
  * A status message component for form fields.
  *
+ * The `detached` variant renders a leading status icon before the message so
+ * status is not conveyed by color or position alone (WCAG 1.4.1). The icon is
+ * decorative for assistive tech (`aria-hidden`): the message text already names
+ * the status in words and is announced through the live region. The `attached`
+ * variant keeps its status affordance on the bordered input, so it renders no
+ * icon here to avoid a duplicate.
+ *
+ * Screen-reader announcements go through the persistent `useAnnounce` live
+ * regions (assertive for errors, polite otherwise) rather than `role`/
+ * `aria-live` on the rendered element. Live regions that mount together with
+ * their content are not reliably announced by assistive technology, and
+ * FieldStatus is almost always conditionally rendered by its callers. The
+ * message is announced whenever it appears — including on first mount — and
+ * whenever it changes.
+ *
  * @example
  * ```
  * <FieldStatus
@@ -138,13 +178,22 @@ export function FieldStatus({
   ...rest
 }: FieldStatusProps) {
   const entryStyle = useEntryAnimation('slideDown');
+  const announce = useAnnounce();
+
+  // Announce the message through the persistently-mounted live regions.
+  // Announce-on-mount is intentional: callers conditionally mount FieldStatus
+  // when a status appears (and whole forms can mount with a server-side
+  // validation error already present), and both cases must be heard.
+  useEffect(() => {
+    if (message) {
+      announce(message, type === 'error' ? 'assertive' : 'polite');
+    }
+  }, [announce, message, type]);
 
   return (
     <div
       ref={ref}
       id={id}
-      role={type === 'error' ? 'alert' : 'status'}
-      aria-live={type === 'error' ? 'assertive' : 'polite'}
       {...rest}
       {...mergeProps(
         themeProps('field-status', {type, variant}),
@@ -158,7 +207,16 @@ export function FieldStatus({
         className,
         style,
       )}>
-      {message}
+      {variant === 'detached' ? (
+        <span {...stylex.props(styles.detachedContent)}>
+          <span {...stylex.props(styles.detachedIcon)}>
+            <Icon icon={statusIconMap[type]} size="sm" color="inherit" />
+          </span>
+          <span>{message}</span>
+        </span>
+      ) : (
+        message
+      )}
     </div>
   );
 }

package/src/FileInput/FileInput.doc.mjs

@@ -78,7 +78,7 @@ export const docs = {
       name: 'isRequired',
       type: 'boolean',
       description:
-        'Displays a "Required" indicator next to the label and sets aria-required. Mutually exclusive with isOptional.',
+        'Displays a "Required" indicator next to the label and adds a screen-reader-only "Required" description to the trigger (aria-required is not supported on role="button"). Mutually exclusive with isOptional.',
       default: 'false',
     },
     {
@@ -119,6 +119,13 @@ export const docs = {
       description:
         'Validation status: applies a colored border. If message is provided, displays a floating message below the input. Error type also sets aria-invalid.',
     },
+    {
+      name: 'statusVariant',
+      type: "'attached' | 'detached'",
+      description:
+        'How the status message is placed relative to the input. attached overlaps directly below the input (bordered treatment); detached floats below as a separate element with spacing.',
+      default: "'attached'",
+    },
     {
       name: 'labelTooltip',
       type: 'string',
@@ -246,6 +253,13 @@ export const docsZh = {
       type: "{type: 'error' | 'warning' | 'success', message?: string}",
       description: '验证状态。',
     },
+    {
+      name: 'statusVariant',
+      type: "'attached' | 'detached'",
+      description:
+        '状态消息相对于输入框的放置方式。attached 直接叠加在输入框下方（带边框处理）；detached 作为独立元素浮于下方并留有间距。',
+      default: "'attached'",
+    },
   ],
   theming: {
     targets: [
@@ -308,7 +322,7 @@ export const docsDense = {
     isLabelHidden: 'Visually hides label; keeps screen reader access.',
     description: 'Description text between label+input.',
     isOptional: 'Shows "Optional" indicator.',
-    isRequired: 'Shows "Required" indicator+sets aria-required.',
+    isRequired: 'Shows "Required" indicator+SR-only trigger description.',
     isDisabled: 'Disables input, prevents interaction.',
     disabledMessage:
       'Explains why input is disabled. With isDisabled, shows tooltip on hover/focus + keeps trigger focusable via aria-disabled (opening picker stays blocked). Use instead of wrapping a disabled FileInput in Tooltip.',
@@ -316,6 +330,7 @@ export const docsDense = {
     placeholder: 'Placeholder when no files selected.',
     mode: "Visual mode: 'input' (compact) or 'dropzone' (drag-and-drop).",
     status: 'Validation status; colored border. Message floats below.',
+    statusVariant: 'How status message is placed: attached overlaps below input; detached floats below w/ spacing.',
     labelTooltip: 'Tooltip in info icon at label end.',
   },
 };

package/src/FileInput/FileInput.test.tsx

@@ -147,16 +147,33 @@ describe('FileInput', () => {
     expect(screen.getByText('Upload')).toBeInTheDocument();
   });
 
-  it('sets aria-required when isRequired is true', () => {
+  it('conveys required state through the accessible description', () => {
     render(
       <FileInput label="Resume" isRequired value={null} onChange={() => {}} />,
     );
-    // aria-required lives on the focusable role="button" wrapper, not the
+    const trigger = screen.getByRole('button', {name: 'Resume'});
+    // Required is conveyed via a visually hidden "Required" node referenced
+    // from aria-describedby on the focusable role="button" trigger — not the
     // hidden file input (forms-6).
-    expect(screen.getByRole('button', {name: 'Resume'})).toHaveAttribute(
-      'aria-required',
-      'true',
+    expect(trigger).toHaveAccessibleDescription(/Required/);
+    // aria-required is not a supported property of role="button" in
+    // WAI-ARIA 1.2 (AT does not announce it), so it must never appear.
+    expect(trigger).not.toHaveAttribute('aria-required');
+  });
+
+  it('combines required with the description in the accessible description', () => {
+    render(
+      <FileInput
+        label="Resume"
+        description="PDF only"
+        isRequired
+        value={null}
+        onChange={() => {}}
+      />,
     );
+    const trigger = screen.getByRole('button', {name: 'Resume'});
+    expect(trigger).toHaveAccessibleDescription(/PDF only/);
+    expect(trigger).toHaveAccessibleDescription(/Required/);
   });
 
   it('places aria-describedby on the focusable button, not the hidden input (forms-6)', () => {
@@ -176,11 +193,11 @@ describe('FileInput', () => {
     expect(input).toHaveAttribute('aria-hidden', 'true');
   });
 
-  it('does not set aria-required by default', () => {
+  it('does not mention required without isRequired', () => {
     render(<FileInput label="Resume" value={null} onChange={() => {}} />);
-    expect(screen.getByRole('button', {name: 'Resume'})).not.toHaveAttribute(
-      'aria-required',
-    );
+    const trigger = screen.getByRole('button', {name: 'Resume'});
+    expect(trigger).not.toHaveAccessibleDescription(/Required/);
+    expect(trigger).not.toHaveAttribute('aria-required');
   });
 
   it('sets disabled attribute when isDisabled is true', () => {
@@ -348,9 +365,44 @@ describe('FileInput', () => {
       fireEvent.change(fileInputEl(), {
         target: {files: [createFile('note.txt', 100)]},
       });
-      // A rejected selection creates no polite region (only the error goes to
-      // the existing role="status" region).
-      expect(politeRegion()).toBeNull();
+      // A rejected selection announces nothing politely. (The region pair may
+      // exist because the validation error itself is announced assertively via
+      // FieldStatus, but the polite channel must stay empty.)
+      expect(politeRegion()?.textContent ?? '').toBe('');
+    });
+
+    it('announces a validation error exactly once across live regions', async () => {
+      render(
+        <FileInput
+          label="Upload"
+          value={null}
+          onChange={() => {}}
+          accept=".pdf"
+        />,
+      );
+      fireEvent.change(fileInputEl(), {
+        target: {files: [createFile('note.txt', 100)]},
+      });
+      const errorText = '"note.txt" is not an accepted file type';
+      // The error lands in the assertive announce region (via the FieldStatus
+      // the derived error status mounts)…
+      await waitFor(() => {
+        expect(
+          document.querySelector('[data-astryx-live-region="assertive"]'),
+        ).toHaveTextContent(errorText);
+      });
+      // …and in exactly one live region overall. FileInput's own role="status"
+      // region used to duplicate the FieldStatus announcement, so the same
+      // error was read twice (assertively, then politely).
+      const liveRegions = Array.from(
+        document.querySelectorAll(
+          '[role="status"], [role="alert"], [aria-live]',
+        ),
+      );
+      const regionsWithError = liveRegions.filter(el =>
+        (el.textContent ?? '').includes(errorText),
+      );
+      expect(regionsWithError).toHaveLength(1);
     });
   });
 
@@ -641,6 +693,54 @@ describe('FileInput', () => {
     });
   });
 
+  describe('trigger accessible name', () => {
+    it('includes the selected file name in the trigger name', () => {
+      const file = createFile('report.pdf', 1024, 'application/pdf');
+      render(<FileInput label="Document" value={file} onChange={() => {}} />);
+      expect(
+        screen.getByRole('button', {name: 'Document, report.pdf'}),
+      ).toBeInTheDocument();
+    });
+
+    it('includes all selected file names when multiple files are selected', () => {
+      const files = [createFile('a.txt', 100), createFile('b.txt', 200)];
+      render(
+        <FileInput
+          label="Files"
+          value={files}
+          onChange={() => {}}
+          isMultiple
+        />,
+      );
+      expect(
+        screen.getByRole('button', {name: 'Files, a.txt, b.txt'}),
+      ).toBeInTheDocument();
+    });
+
+    it('uses exactly the label when no files are selected', () => {
+      render(<FileInput label="Document" value={null} onChange={() => {}} />);
+      expect(screen.getByRole('button', {name: 'Document'})).toHaveAttribute(
+        'aria-label',
+        'Document',
+      );
+    });
+
+    it('includes the selected file name in dropzone mode', () => {
+      const file = createFile('doc.pdf', 100, 'application/pdf');
+      render(
+        <FileInput
+          label="Upload"
+          value={file}
+          onChange={() => {}}
+          mode="dropzone"
+        />,
+      );
+      expect(
+        screen.getByRole('button', {name: 'Upload, doc.pdf'}),
+      ).toBeInTheDocument();
+    });
+  });
+
   describe('data-testid', () => {
     it('passes data-testid to native input', () => {
       render(
@@ -800,3 +900,26 @@ describe('FileInput', () => {
     });
   });
 });
+
+
+describe('FileInput statusVariant forwarding', () => {
+  it('defaults to attached (status renders with data-variant="attached")', () => {
+    const {container} = render(
+      <FileInput label="Upload" value={null} onChange={() => {}} status={{type: 'error', message: 'Something went wrong'}} />,
+    );
+    expect(container.querySelector('.astryx-field-status')).toHaveAttribute(
+      'data-variant',
+      'attached',
+    );
+  });
+
+  it('forwards statusVariant="detached" to the underlying Field status', () => {
+    const {container} = render(
+      <FileInput label="Upload" value={null} onChange={() => {}} status={{type: 'error', message: 'Something went wrong'}} statusVariant="detached" />,
+    );
+    expect(container.querySelector('.astryx-field-status')).toHaveAttribute(
+      'data-variant',
+      'detached',
+    );
+  });
+});