@astryxdesign/core 0.6.0 → 0.6.1

package/src/FieldStatus/__tests__/StatusMessage.a11y.renders.tsx

@@ -0,0 +1,305 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file StatusMessage.a11y.renders.tsx
+ * @input Uses current Core status-message components and the binding state ids
+ * @output One public-interface rendering for every Core status-message binding state
+ * @position Shared jsdom and checked-in Storybook fixture layer
+ */
+
+import {useEffect, useState, type ReactElement, type ReactNode} from 'react';
+import {ChatSystemMessage} from '../../Chat/ChatSystemMessage';
+import {ProgressBar} from '../../ProgressBar/ProgressBar';
+import {Spinner} from '../../Spinner/Spinner';
+import {Toast} from '../../Toast/Toast';
+import {ToastViewport} from '../../Toast/ToastViewport';
+import {useToast} from '../../Toast/useToast';
+import {useAnnounce, type AnnouncePoliteness} from '../../hooks/useAnnounce';
+import {FieldStatus} from '../FieldStatus';
+import type {CoreStatusMessageStateId} from './StatusMessage.a11y.states';
+
+const transitionTestId = (name: string) => `status-transition-${name}`;
+
+function TransitionButton({
+  name,
+  onClick,
+}: {
+  name: string;
+  onClick: () => void;
+}) {
+  return (
+    <button
+      data-testid={transitionTestId(name)}
+      type="button"
+      onClick={onClick}>
+      {name}
+    </button>
+  );
+}
+
+function Frame({
+  children,
+  isReady = true,
+}: {
+  children: ReactNode;
+  isReady?: boolean;
+}) {
+  return (
+    <div>
+      <span data-a11y-ready={String(isReady)} hidden />
+      <button data-a11y-relation="focus-anchor" type="button">
+        Keep focus
+      </button>
+      {children}
+    </div>
+  );
+}
+
+/**
+ * Establishes the same singleton channel the component will update, then clears
+ * the seed before the test starts. This lets a browser binding inspect the
+ * pre-existing empty node; the contract's plain-HTML fixtures separately prove
+ * the first-use insertion order.
+ */
+function PrimeLiveRegion({politeness}: {politeness: AnnouncePoliteness}) {
+  const announce = useAnnounce();
+  const [isReady, setIsReady] = useState(false);
+  useEffect(() => {
+    let secondFrame = 0;
+    announce('Preparing status channel', politeness);
+    const firstFrame = requestAnimationFrame(() => {
+      secondFrame = requestAnimationFrame(() => {
+        announce('', politeness);
+        setIsReady(true);
+      });
+    });
+    return () => {
+      cancelAnimationFrame(firstFrame);
+      cancelAnimationFrame(secondFrame);
+    };
+  }, [announce, politeness]);
+  return <span data-a11y-ready={String(isReady)} hidden />;
+}
+
+function ToastAnnouncementButtons({type}: {type: 'info' | 'error'}) {
+  const toast = useToast();
+  const message = type === 'error' ? 'Upload failed' : 'Changes saved';
+  const replacement =
+    type === 'error' ? 'Connection failed' : 'Profile updated';
+  const show = (body: string) =>
+    toast({
+      body,
+      type,
+      uniqueID: `status-contract-${type}`,
+      isAutoHide: false,
+    });
+  return (
+    <>
+      <TransitionButton name="show" onClick={() => show(message)} />
+      <TransitionButton name="replace" onClick={() => show(replacement)} />
+      <TransitionButton name="repeat" onClick={() => show(message)} />
+    </>
+  );
+}
+
+function ToastAnnouncementHarness({type}: {type: 'info' | 'error'}) {
+  const politeness = type === 'error' ? 'assertive' : 'polite';
+  return (
+    <ToastViewport isTopLayer={false}>
+      <PrimeLiveRegion politeness={politeness} />
+      <button data-a11y-relation="focus-anchor" type="button">
+        Keep focus
+      </button>
+      <ToastAnnouncementButtons type={type} />
+    </ToastViewport>
+  );
+}
+
+function ToastCardHarness({type}: {type: 'info' | 'error'}) {
+  const message = type === 'error' ? 'Upload failed' : 'Changes saved';
+  const replacement =
+    type === 'error' ? 'Connection failed' : 'Profile updated';
+  const [body, setBody] = useState(message);
+  return (
+    <Frame>
+      <TransitionButton name="show" onClick={() => setBody(message)} />
+      <TransitionButton name="replace" onClick={() => setBody(replacement)} />
+      <Toast
+        type={type}
+        body={body}
+        isAutoHide={false}
+        autoHideDuration={5000}
+        onDismiss={() => {}}
+      />
+    </Frame>
+  );
+}
+
+function FieldStatusHarness({
+  type,
+  variant,
+  message,
+  replacement,
+}: {
+  type: 'error' | 'warning' | 'success';
+  variant: 'attached' | 'detached';
+  message: string;
+  replacement: string;
+}) {
+  const politeness = type === 'error' ? 'assertive' : 'polite';
+  const [current, setCurrent] = useState('');
+  const [version, setVersion] = useState(0);
+  return (
+    <>
+      <PrimeLiveRegion politeness={politeness} />
+      <button data-a11y-relation="focus-anchor" type="button">
+        Keep focus
+      </button>
+      <TransitionButton name="show" onClick={() => setCurrent(message)} />
+      <TransitionButton
+        name="replace"
+        onClick={() => setCurrent(replacement)}
+      />
+      <TransitionButton
+        name="repeat"
+        onClick={() => {
+          setCurrent(message);
+          setVersion(value => value + 1);
+        }}
+      />
+      <FieldStatus
+        key={version}
+        type={type}
+        variant={variant}
+        message={current}
+      />
+    </>
+  );
+}
+
+function SpinnerHarness({visibleLabel}: {visibleLabel: boolean}) {
+  const initial = visibleLabel ? 'Fetching data' : undefined;
+  const replacement = visibleLabel ? 'Saving data' : 'Saving';
+  const [label, setLabel] = useState<string | undefined>(initial);
+  return (
+    <Frame>
+      <TransitionButton name="show" onClick={() => setLabel(initial)} />
+      <TransitionButton name="replace" onClick={() => setLabel(replacement)} />
+      {visibleLabel ? (
+        <Spinner label={label ?? 'Fetching data'} />
+      ) : label == null ? (
+        <Spinner />
+      ) : (
+        <Spinner aria-label={label} />
+      )}
+    </Frame>
+  );
+}
+
+function ChatSystemMessageHarness() {
+  const initial = 'Conversation started';
+  const [message, setMessage] = useState(initial);
+  return (
+    <Frame>
+      <TransitionButton name="show" onClick={() => setMessage(initial)} />
+      <TransitionButton
+        name="replace"
+        onClick={() => setMessage('A file was shared')}
+      />
+      <TransitionButton name="clear" onClick={() => setMessage('')} />
+      <ChatSystemMessage>{message}</ChatSystemMessage>
+    </Frame>
+  );
+}
+
+function ProgressHarness({
+  initial,
+  progressValue = 40,
+  completionValue = 100,
+  max = 100,
+  withMark = false,
+}: {
+  initial?: 'loading' | number;
+  progressValue?: number;
+  completionValue?: number;
+  max?: number;
+  withMark?: boolean;
+}) {
+  const [progress, setProgress] = useState<'loading' | number>(
+    initial ?? (withMark ? 20 : 'loading'),
+  );
+  return (
+    <Frame>
+      <TransitionButton
+        name="progress"
+        onClick={() => setProgress(progressValue)}
+      />
+      <TransitionButton
+        name="complete"
+        onClick={() => setProgress(completionValue)}
+      />
+      <ProgressBar
+        label="Upload progress"
+        isIndeterminate={progress === 'loading'}
+        value={typeof progress === 'number' ? progress : 0}
+        max={max}
+        marks={withMark ? [{value: 75, label: 'Target'}] : undefined}
+      />
+    </Frame>
+  );
+}
+
+export type CoreStatusMessageStateRender = () => ReactElement;
+
+export const CORE_STATUS_MESSAGE_STATE_RENDERS: Record<
+  CoreStatusMessageStateId,
+  CoreStatusMessageStateRender
+> = {
+  'toast-info-announcement': () => <ToastAnnouncementHarness type="info" />,
+  'toast-error-announcement': () => <ToastAnnouncementHarness type="error" />,
+  'toast-info-card-mounted': () => <ToastCardHarness type="info" />,
+  'toast-error-card-mounted': () => <ToastCardHarness type="error" />,
+  'field-status-error-attached': () => (
+    <FieldStatusHarness
+      type="error"
+      variant="attached"
+      message="This field is required"
+      replacement="Enter a valid email address"
+    />
+  ),
+  'field-status-warning-detached': () => (
+    <FieldStatusHarness
+      type="warning"
+      variant="detached"
+      message="Check this value"
+      replacement="This value may be visible to others"
+    />
+  ),
+  'field-status-success-detached': () => (
+    <FieldStatusHarness
+      type="success"
+      variant="detached"
+      message="Looks good"
+      replacement="Changes saved"
+    />
+  ),
+  'spinner-default-label-mounted': () => (
+    <SpinnerHarness visibleLabel={false} />
+  ),
+  'spinner-visible-label-mounted': () => <SpinnerHarness visibleLabel />,
+  'chat-system-status-mounted': () => <ChatSystemMessageHarness />,
+  'progress-loading-to-complete': () => <ProgressHarness />,
+  'progress-custom-range': () => (
+    <ProgressHarness
+      initial={1}
+      progressValue={3}
+      completionValue={5}
+      max={5}
+    />
+  ),
+  'progress-mark-focused-update': () => <ProgressHarness withMark />,
+};
+
+export {transitionTestId};

package/src/FieldStatus/__tests__/StatusMessage.a11y.states.ts

@@ -0,0 +1,317 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file StatusMessage.a11y.states.ts
+ * @input Uses StatusMessageStateFacts from the shared accessibility contract
+ * @output The AST-021 inventory for current Core status-message parts and states, plus explicit exclusions
+ * @position Data-only binding inventory shared by jsdom, Storybook, and Chromium
+ */
+
+import type {StatusMessageStateFacts} from '@astryxdesign/a11y-spec';
+
+export type CoreStatusMessageBinding =
+  | 'Toast announcement channel'
+  | 'Toast card'
+  | 'FieldStatus announcement channel'
+  | 'Spinner'
+  | 'ChatSystemMessage'
+  | 'ProgressBar';
+
+export interface CoreStatusMessageBindingDefinition {
+  readonly id: string;
+  readonly binding: CoreStatusMessageBinding;
+  readonly summary: string;
+  readonly facts: StatusMessageStateFacts;
+  readonly focusSelector?: string;
+  readonly storyId: string;
+}
+
+function liveFacts({
+  role,
+  politeness,
+  message,
+  replacement,
+  initialMessage = '',
+  messageSource = 'text',
+  semanticTransitions,
+}: {
+  role: 'status' | 'alert' | null;
+  politeness: 'polite' | 'assertive';
+  message: string;
+  replacement: string;
+  initialMessage?: string;
+  messageSource?: 'text' | 'accessible-name';
+  semanticTransitions: ReadonlyArray<'show' | 'replace' | 'clear' | 'repeat'>;
+}): StatusMessageStateFacts {
+  return {
+    kind: 'live-region',
+    role,
+    politeness,
+    messageSource,
+    initialMessage,
+    message,
+    replacement,
+    semanticTransitions,
+  };
+}
+
+export const CORE_STATUS_MESSAGE_BINDING_STATES = [
+  {
+    id: 'toast-info-announcement',
+    binding: 'Toast announcement channel',
+    summary:
+      'an info toast dispatch updates and can repeat through the persistent polite channel',
+    facts: liveFacts({
+      role: 'status',
+      politeness: 'polite',
+      message: 'Changes saved',
+      replacement: 'Profile updated',
+      semanticTransitions: ['show', 'replace', 'repeat'],
+    }),
+    storyId: 'a11y-status-message-pattern--toast-info-announcement',
+  },
+  {
+    id: 'toast-error-announcement',
+    binding: 'Toast announcement channel',
+    summary:
+      'an error toast dispatch updates and can repeat through the persistent assertive channel',
+    facts: liveFacts({
+      role: 'alert',
+      politeness: 'assertive',
+      message: 'Upload failed',
+      replacement: 'Connection failed',
+      semanticTransitions: ['show', 'replace', 'repeat'],
+    }),
+    storyId: 'a11y-status-message-pattern--toast-error-announcement',
+  },
+  {
+    id: 'toast-info-card-mounted',
+    binding: 'Toast card',
+    summary:
+      'the visible info card is mounted with its polite live-region content',
+    facts: liveFacts({
+      role: 'status',
+      politeness: 'polite',
+      initialMessage: 'Changes saved',
+      message: 'Changes saved',
+      replacement: 'Profile updated',
+      semanticTransitions: ['replace'],
+    }),
+    storyId: 'a11y-status-message-pattern--toast-info-card-mounted',
+  },
+  {
+    id: 'toast-error-card-mounted',
+    binding: 'Toast card',
+    summary:
+      'the visible error card is mounted with its assertive live-region content',
+    facts: liveFacts({
+      role: 'alert',
+      politeness: 'assertive',
+      initialMessage: 'Upload failed',
+      message: 'Upload failed',
+      replacement: 'Connection failed',
+      semanticTransitions: ['replace'],
+    }),
+    storyId: 'a11y-status-message-pattern--toast-error-card-mounted',
+  },
+  {
+    id: 'field-status-error-attached',
+    binding: 'FieldStatus announcement channel',
+    summary:
+      'an attached error enters and updates through the persistent assertive channel',
+    facts: liveFacts({
+      role: 'alert',
+      politeness: 'assertive',
+      message: 'This field is required',
+      replacement: 'Enter a valid email address',
+      semanticTransitions: ['show', 'replace', 'repeat'],
+    }),
+    storyId: 'a11y-status-message-pattern--field-status-error-attached',
+  },
+  {
+    id: 'field-status-warning-detached',
+    binding: 'FieldStatus announcement channel',
+    summary:
+      'a detached warning enters and updates through the persistent polite channel',
+    facts: liveFacts({
+      role: 'status',
+      politeness: 'polite',
+      message: 'Check this value',
+      replacement: 'This value may be visible to others',
+      semanticTransitions: ['show', 'replace', 'repeat'],
+    }),
+    storyId: 'a11y-status-message-pattern--field-status-warning-detached',
+  },
+  {
+    id: 'field-status-success-detached',
+    binding: 'FieldStatus announcement channel',
+    summary:
+      'a detached success enters and updates through the persistent polite channel',
+    facts: liveFacts({
+      role: 'status',
+      politeness: 'polite',
+      message: 'Looks good',
+      replacement: 'Changes saved',
+      semanticTransitions: ['show', 'replace', 'repeat'],
+    }),
+    storyId: 'a11y-status-message-pattern--field-status-success-detached',
+  },
+  {
+    id: 'spinner-default-label-mounted',
+    binding: 'Spinner',
+    summary:
+      'a loading spinner is mounted with its default accessible status name',
+    facts: liveFacts({
+      role: 'status',
+      politeness: 'polite',
+      initialMessage: 'Loading',
+      messageSource: 'accessible-name',
+      message: 'Loading',
+      replacement: 'Saving',
+      semanticTransitions: ['replace'],
+    }),
+    storyId: 'a11y-status-message-pattern--spinner-default-label-mounted',
+  },
+  {
+    id: 'spinner-visible-label-mounted',
+    binding: 'Spinner',
+    summary:
+      'a loading spinner is mounted with a visible label that names its status role',
+    facts: liveFacts({
+      role: 'status',
+      politeness: 'polite',
+      initialMessage: 'Fetching data',
+      messageSource: 'accessible-name',
+      message: 'Fetching data',
+      replacement: 'Saving data',
+      semanticTransitions: ['replace'],
+    }),
+    storyId: 'a11y-status-message-pattern--spinner-visible-label-mounted',
+  },
+  {
+    id: 'chat-system-status-mounted',
+    binding: 'ChatSystemMessage',
+    summary: 'a chat status notice is mounted with its live-region content',
+    facts: liveFacts({
+      role: 'status',
+      politeness: 'polite',
+      initialMessage: 'Conversation started',
+      message: 'Conversation started',
+      replacement: 'A file was shared',
+      semanticTransitions: ['replace', 'clear'],
+    }),
+    storyId: 'a11y-status-message-pattern--chat-system-status-mounted',
+  },
+  {
+    id: 'progress-loading-to-complete',
+    binding: 'ProgressBar',
+    summary:
+      'an indeterminate operation becomes 40 percent complete and then finishes',
+    facts: {
+      kind: 'progressbar',
+      politeness: null,
+      name: 'Upload progress',
+      initialValue: null,
+      initialMin: 0,
+      initialMax: 100,
+      progressValue: 40,
+      completionValue: 100,
+      minValue: 0,
+      maxValue: 100,
+    },
+    storyId: 'a11y-status-message-pattern--progress-loading-to-complete',
+  },
+  {
+    id: 'progress-custom-range',
+    binding: 'ProgressBar',
+    summary: 'a five-step operation exposes and updates its non-default range',
+    facts: {
+      kind: 'progressbar',
+      politeness: null,
+      name: 'Upload progress',
+      initialValue: 1,
+      initialMin: 0,
+      initialMax: 5,
+      progressValue: 3,
+      completionValue: 5,
+      minValue: 0,
+      maxValue: 5,
+    },
+    storyId: 'a11y-status-message-pattern--progress-custom-range',
+  },
+  {
+    id: 'progress-mark-focused-update',
+    binding: 'ProgressBar',
+    summary:
+      'a determinate value update preserves focus on a labeled target mark',
+    facts: {
+      kind: 'progressbar',
+      politeness: null,
+      name: 'Upload progress',
+      initialValue: 20,
+      initialMin: 0,
+      initialMax: 100,
+      progressValue: 40,
+      completionValue: 100,
+      minValue: 0,
+      maxValue: 100,
+    },
+    focusSelector: '[role="progressbar"] [tabindex="0"]',
+    storyId: 'a11y-status-message-pattern--progress-mark-focused-update',
+  },
+] as const satisfies ReadonlyArray<CoreStatusMessageBindingDefinition>;
+
+export type CoreStatusMessageBindingState =
+  (typeof CORE_STATUS_MESSAGE_BINDING_STATES)[number];
+export type CoreStatusMessageStateId = CoreStatusMessageBindingState['id'];
+
+export const CORE_STATUS_MESSAGE_EXCLUSIONS = [
+  {
+    owner: 'FieldStatus visible message box',
+    part: 'visible validation text',
+    reason:
+      'component:FieldStatus AR2 keeps the visible box role-free as the input description target; its separate persistent announcement channel is bound above.',
+  },
+  {
+    owner: 'Spinner compositions',
+    part: 'aria-hidden decorative spinner',
+    reason:
+      'A composing control that marks Spinner aria-hidden owns the surrounding busy semantics; the decorative ring is not another status message.',
+  },
+  {
+    owner: 'ChatSystemMessage divider',
+    part: 'date or section separator',
+    reason:
+      'A divider does not report success, results, waiting, progress, or an error. Its current forced status role is tracked as a separate ownership mismatch rather than adopted here.',
+  },
+  {
+    owner: 'ChatMessageList and streaming logs',
+    part: 'role=log transcript updates',
+    reason:
+      'Sequential log announcements and stream batching are a distinct log pattern, not one atomic status message.',
+  },
+  {
+    owner: 'ChatComposer and ChatToolCalls',
+    part: 'composer errors and tool-run states',
+    reason:
+      'These adjacent surfaces have their own state ownership and were not named by this bounded first status-message migration.',
+  },
+  {
+    owner: 'Switch',
+    part: 'busy announcement',
+    reason:
+      'The current switch pattern has no busy announcement expectation, and overlapping work is changing this path; it is not silently absorbed into this migration.',
+  },
+  {
+    owner: 'ProgressBar marks and Tooltip',
+    part: 'focusable target-mark triggers and labels',
+    reason:
+      'The marked progress state above proves that value updates preserve mark focus. ProgressBar and Tooltip local tests own trigger labeling and interaction; ARIA ownership of focusable descendants is tracked separately.',
+  },
+  {
+    owner: 'ProgressBar component and theme',
+    part: 'visual fill, track, animation, and status cadence',
+    reason:
+      'The binding covers browser-exposed role, name, values, and focus preservation. Paint stays in visual evidence; spoken cadence and timing stay under AST-009.',
+  },
+] as const;