@astryxdesign/core 0.1.8 → 0.1.9-canary.02ef052

package/src/DropdownMenu/renderDropdownItems.tsx

@@ -10,6 +10,7 @@ import type {ReactNode} from 'react';
 import * as stylex from '@stylexjs/stylex';
 import {Divider} from '../Divider';
 import {DropdownMenuItem} from './DropdownMenuItem';
+import {DropdownMenuSubMenu} from './DropdownMenuSubMenu';
 import {
   spacingVars,
   typographyVars,
@@ -49,18 +50,14 @@ function getSectionKey(section: DropdownMenuSection, index: number): string {
  * Converts data-driven items into DropdownMenuItem components,
  * so both modes share the same rendering and keyboard navigation path.
  */
-export function renderDropdownItems(
-  items: DropdownMenuOption[],
-): ReactNode {
+export function renderDropdownItems(items: DropdownMenuOption[]): ReactNode {
   const elements: ReactNode[] = [];
 
   for (let i = 0; i < items.length; i++) {
     const option = items[i];
 
     if ('type' in option && option.type === 'divider') {
-      elements.push(
-        <Divider key={`divider-${i}`} xstyle={styles.divider} />,
-      );
+      elements.push(<Divider key={`divider-${i}`} xstyle={styles.divider} />);
     } else if ('type' in option && option.type === 'section') {
       elements.push(
         <div
@@ -84,15 +81,32 @@ export function renderDropdownItems(
         </div>,
       );
     } else if (!('type' in option)) {
-      elements.push(
-        <DropdownMenuItem
-          key={getItemKey(option)}
-          icon={option.icon}
-          label={option.label}
-          onClick={option.onClick}
-          isDisabled={option.isDisabled}
-        />,
-      );
+      // A plain item that declares nested `items` becomes a submenu (data-mode
+      // parity with the compound DropdownMenuSubMenu API); otherwise it's a
+      // leaf. renderDropdownItems owns the recursion and hands the rendered
+      // children to DropdownMenuSubMenu — so DropdownMenuSubMenu never imports
+      // this module back (no import cycle).
+      if (option.items && option.items.length > 0) {
+        elements.push(
+          <DropdownMenuSubMenu
+            key={getItemKey(option)}
+            icon={option.icon}
+            label={option.label}
+            isDisabled={option.isDisabled}>
+            {renderDropdownItems(option.items)}
+          </DropdownMenuSubMenu>,
+        );
+      } else {
+        elements.push(
+          <DropdownMenuItem
+            key={getItemKey(option)}
+            icon={option.icon}
+            label={option.label}
+            onClick={option.onClick}
+            isDisabled={option.isDisabled}
+          />,
+        );
+      }
     }
   }
 

package/src/Field/Field.test.tsx

@@ -9,10 +9,22 @@
  * SYNC: When Field.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 {Field} from './Field';
 import {FormLayoutContext} from '../FormLayout/FormLayoutContext';
+import {__resetLiveRegionsForTest} from '../hooks/useAnnounce';
+
+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('Field', () => {
   it('renders with label', () => {
@@ -228,7 +240,11 @@ describe('Field', () => {
     expect(document.querySelector('svg')).not.toBeInTheDocument();
   });
 
-  it('status has role="alert" and aria-live="assertive" for error type', () => {
+  // The status message is announced through the persistent useAnnounce live
+  // regions rather than role/aria-live on the (conditionally mounted)
+  // FieldStatus element itself — regions born with their content are not
+  // reliably announced by assistive technology.
+  it('announces error status assertively via the persistent live region', async () => {
     render(
       <Field
         label="Email"
@@ -237,12 +253,13 @@ describe('Field', () => {
         <input id="email-input" />
       </Field>,
     );
-    const status = screen.getByRole('alert');
-    expect(status).toHaveTextContent('Invalid email');
-    expect(status).toHaveAttribute('aria-live', 'assertive');
+    expect(screen.getByText('Invalid email')).not.toHaveAttribute('role');
+    await waitFor(() => {
+      expect(assertiveRegion()).toHaveTextContent('Invalid email');
+    });
   });
 
-  it('status has role="status" and aria-live="polite" for warning type', () => {
+  it('announces warning status politely via the persistent live region', async () => {
     render(
       <Field
         label="Email"
@@ -251,9 +268,34 @@ describe('Field', () => {
         <input id="email-input" />
       </Field>,
     );
-    const status = screen.getByRole('status');
-    expect(status).toHaveTextContent('Check this');
-    expect(status).toHaveAttribute('aria-live', 'polite');
+    expect(screen.getByText('Check this')).not.toHaveAttribute('aria-live');
+    await waitFor(() => {
+      expect(politeRegion()).toHaveTextContent('Check this');
+    });
+  });
+
+  // Regression: the status live region must NOT be born together with its
+  // content. A message that appears after mount (the common validation flow)
+  // has to land in the persistent announce region.
+  it('announces a status message that appears after mount', async () => {
+    const {rerender} = render(
+      <Field label="Email" inputID="email-input">
+        <input id="email-input" />
+      </Field>,
+    );
+    expect(assertiveRegion()).toBeNull();
+
+    rerender(
+      <Field
+        label="Email"
+        inputID="email-input"
+        status={{type: 'error', message: 'Email is required'}}>
+        <input id="email-input" />
+      </Field>,
+    );
+    await waitFor(() => {
+      expect(assertiveRegion()).toHaveTextContent('Email is required');
+    });
   });
 
   it('auto-generates description ID as {inputID}-desc when descriptionID is not provided', () => {
@@ -277,7 +319,10 @@ describe('Field', () => {
         <input id="my-input" />
       </Field>,
     );
-    expect(screen.getByRole('alert')).toHaveAttribute('id', 'my-input-status');
+    expect(screen.getByText('Required')).toHaveAttribute(
+      'id',
+      'my-input-status',
+    );
   });
 
   it('warns when isOptional and isRequired are both set', () => {
@@ -421,7 +466,7 @@ describe('Field', () => {
         </Field>,
         {wrapper: horizontalLabelsWrapper},
       );
-      const statusEl = screen.getByRole('alert');
+      const statusEl = screen.getByText('Required');
       const inputEl = screen.getByTestId('email');
       // Both status and input should be inside the same wrapper div (column 2)
       expect(statusEl.parentElement).toBe(inputEl.parentElement);

package/src/Field/Field.tsx

@@ -22,9 +22,11 @@ import type {BaseProps} from '../BaseProps';
 import type {SizeValue} from '../utils/types';
 import {FieldLabel} from './FieldLabel';
 import {FieldStatus} from '../FieldStatus/FieldStatus';
+import type {FieldStatusVariant} from '../FieldStatus/FieldStatus';
 import {spacingVars, borderVars} from '../theme/tokens.stylex';
 import type {IconType} from '../Icon';
 import {mergeProps} from '../utils';
+import {useDevWarning} from '../hooks/useDevWarning';
 import {FormLayoutContext} from '../FormLayout/FormLayoutContext';
 import {Text} from '../Text';
 import {themeProps} from '../utils/themeProps';
@@ -155,9 +157,10 @@ export interface FieldProps extends Omit<
    * How the status message is rendered relative to the input.
    * - 'attached': Status sits directly below the input (default, for bordered inputs)
    * - 'detached': Status is a separate element below the field (for checkboxes, switches, sliders)
+   * - 'tooltip': No message box; the input surfaces status through a tooltip on its on-field icon
    * @default 'attached'
    */
-  statusVariant?: 'attached' | 'detached';
+  statusVariant?: FieldStatusVariant;
   /**
    * Width of the field. Numbers are treated as pixels, strings are used as-is
    * (e.g. `'100%'`). Sizes the whole field — label, control, and status — so
@@ -215,11 +218,11 @@ export function Field({
   const resolvedMessageID =
     status?.messageID ?? (status?.message ? `${inputID}-status` : undefined);
 
-  if (isOptional && isRequired) {
-    console.warn(
-      'Field: isOptional and isRequired are mutually exclusive. isOptional takes precedence.',
-    );
-  }
+  useDevWarning(
+    'Field',
+    'isOptional and isRequired are mutually exclusive. isOptional takes precedence.',
+    isOptional && isRequired,
+  );
 
   const labelNode = (
     <FieldLabel
@@ -238,14 +241,17 @@ export function Field({
     />
   );
 
-  const statusNode = status?.message ? (
-    <FieldStatus
-      type={status.type}
-      message={status.message}
-      id={resolvedMessageID}
-      variant={statusVariant}
-    />
-  ) : null;
+  // The 'tooltip' variant surfaces status through the input's on-field icon
+  // tooltip, so Field renders no message box for it.
+  const statusNode =
+    status?.message && statusVariant !== 'tooltip' ? (
+      <FieldStatus
+        type={status.type}
+        message={status.message}
+        id={resolvedMessageID}
+        variant={statusVariant}
+      />
+    ) : null;
 
   // ─── Horizontal-labels mode ───────────────────────────────────────────
   // Use display:contents so the parent grid's `auto 1fr` columns place

package/src/Field/FieldLabel.tsx

@@ -48,7 +48,7 @@ const styles = stylex.create({
     borderStyle: 'none',
     clip: 'rect(0, 0, 0, 0)',
     height: 1,
-    left: 0,
+    insetInlineStart: 0,
     margin: -1,
     overflow: 'hidden',
     padding: 0,
@@ -171,7 +171,11 @@ export function FieldLabel({
   labelTooltip,
   description,
   descriptionID,
+  className,
+  style,
+  xstyle,
   ref,
+  ...rest
 }: FieldLabelProps) {
   const statusText = isOptional ? 'Optional' : isRequired ? 'Required' : null;
 
@@ -207,13 +211,17 @@ export function FieldLabel({
         // `htmlFor` only applies to a real `<label>` associating with a single
         // control; a group label (span) has no `htmlFor`.
         htmlFor={isGroupLabel ? undefined : inputID}
+        {...rest}
         {...mergeProps(
           themeProps('field-label'),
           stylex.props(
             styles.label,
             isDisabled && styles.labelDisabled,
             isLabelHidden && styles.srOnly,
+            xstyle,
           ),
+          className,
+          style,
         )}>
         {labelContent}
       </LabelElement>

package/src/Field/inputStyles.stylex.ts

@@ -67,6 +67,8 @@ export const inputWrapperStyles = stylex.create({
     cursor: 'not-allowed',
     opacity: 0.5,
     borderColor: colorVars['--color-border-emphasized'],
+    // Suppress the base hover ring — a disabled control must not react to hover.
+    boxShadow: 'none',
   },
 });
 

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();
     });
   });