@astryxdesign/core 0.1.8 → 0.1.9

package/src/Dialog/Dialog.tsx

@@ -16,7 +16,14 @@
  * - /packages/cli/templates/blocks/components/Dialog/ (showcase blocks)
  */
 
-import {useEffect, useMemo, useRef, type ReactNode} from 'react';
+import {
+  useCallback,
+  useEffect,
+  useId,
+  useMemo,
+  useRef,
+  type ReactNode,
+} from 'react';
 import type {BaseProps} from '../BaseProps';
 import * as stylex from '@stylexjs/stylex';
 import {useScrollLock} from '../hooks/useScrollLock';
@@ -39,6 +46,7 @@ import {
 } from '../Layout/padding.stylex';
 import type {SpacingStep} from '../utils/types';
 import {mergeProps, mergeRefs} from '../utils';
+import {devWarn} from '../utils/devWarning';
 import {DialogContext} from './DialogContext';
 import {themeProps} from '../utils/themeProps';
 
@@ -152,7 +160,13 @@ const styles = stylex.create({
   open: {
     display: 'flex',
     opacity: 1,
-    animationName: enterDirectional,
+    // Disable the entry keyframe animation under
+    // `prefers-reduced-motion: reduce` so the dialog appears instantly
+    // instead of translating/scaling in (same pattern as layerAnimations).
+    animationName: {
+      default: enterDirectional,
+      '@media (prefers-reduced-motion: reduce)': 'none',
+    },
   },
   // Backdrop using ::backdrop pseudo-element
   backdrop: {
@@ -312,6 +326,9 @@ export interface DialogProps extends BaseProps<HTMLDialogElement> {
  *
  * Designed to be used with Layout as its child for structured content.
  * Uses the browser's built-in modal behavior for optimal accessibility.
+ * When a DialogHeader is rendered inside, its title automatically names the
+ * dialog via aria-labelledby; pass `aria-label` or `aria-labelledby` to
+ * override.
  *
  * @example
  * ```
@@ -348,10 +365,47 @@ export function Dialog({
   const paddingToken = spacingStepToToken[effectivePadding] as SpacingToken;
 
   const isFullscreen = variant === 'fullscreen';
-  const dialogContextValue = useMemo(() => ({isInline}), [isInline]);
+
+  // Default accessible name: publish a title id through DialogContext so a
+  // DialogHeader applies it to its heading (mirrors AlertDialog's explicit
+  // useId wiring). Whether to emit the default aria-labelledby is decided
+  // imperatively in the callback ref below by checking whether the title
+  // element actually rendered — so a dialog with no header never points at a
+  // missing id, and we avoid the extra render a registration-via-state effect
+  // would cost at the dialog level.
+  const titleId = useId();
+
+  const dialogContextValue = useMemo(
+    () => ({isInline, titleId}),
+    [isInline, titleId],
+  );
+
+  // Consumer-provided labels always win over the DialogHeader default.
+  const hasConsumerName =
+    props['aria-label'] != null || props['aria-labelledby'] != null;
 
   const dialogRef = useRef<HTMLDialogElement>(null);
 
+  // Callback ref on the <dialog>: sync the default aria-labelledby from the
+  // DialogHeader title (if one rendered) in the same commit, with no second
+  // render. Consumer aria-label/aria-labelledby win — when present we leave
+  // the attribute to the {...safeProps} spread and never touch it here.
+  const attachDialog = useCallback(
+    (node: HTMLDialogElement | null) => {
+      dialogRef.current = node;
+      if (!node || hasConsumerName) {
+        return;
+      }
+      const hasTitle = node.querySelector(`#${CSS.escape(titleId)}`) != null;
+      if (hasTitle) {
+        node.setAttribute('aria-labelledby', titleId);
+      } else {
+        node.removeAttribute('aria-labelledby');
+      }
+    },
+    [titleId, hasConsumerName],
+  );
+
   // Capture the element that was focused when the dialog opened,
   // for directional animation origin and focus restoration on close.
   const triggerElementRef = useRef<HTMLElement | null>(null);
@@ -440,6 +494,29 @@ export function Dialog({
     return () => dialog.removeEventListener('keydown', handleKeyDown);
   }, [isOpen, isInline, allowEscape, onOpenChange]);
 
+  // Dev-time guardrail: an open modal should always have an accessible name.
+  // The header-title check reads the DOM, so this stays in an effect; the ref
+  // keeps it to one warning per component instance.
+  const warnedUnnamedDialogRef = useRef(false);
+  useEffect(() => {
+    const hasHeaderTitle =
+      dialogRef.current?.querySelector(`#${CSS.escape(titleId)}`) != null;
+    if (
+      isOpen &&
+      !isInline &&
+      !hasConsumerName &&
+      !hasHeaderTitle &&
+      !warnedUnnamedDialogRef.current
+    ) {
+      warnedUnnamedDialogRef.current = true;
+      devWarn(
+        'Dialog',
+        'open dialog has no accessible name. Add a DialogHeader ' +
+          'with a `title`, or pass `aria-label`/`aria-labelledby`.',
+      );
+    }
+  }, [isOpen, isInline, hasConsumerName, titleId]);
+
   // Handle backdrop click — when the user clicks the ::backdrop pseudo-element,
   // the event target is the <dialog> element itself; clicks on child content
   // always target the child. This avoids false positives from native browser
@@ -531,7 +608,11 @@ export function Dialog({
           ),
           className,
           style,
-        )}>
+        )}
+        data-testid={
+          (props as Record<string, unknown>)['data-testid'] as
+            string | undefined
+        }>
         {innerContent}
       </div>
     );
@@ -541,7 +622,7 @@ export function Dialog({
 
   return (
     <dialog
-      ref={mergeRefs(ref, dialogRef)}
+      ref={mergeRefs(ref, attachDialog)}
       {...safeProps}
       {...mergeProps(
         themeProps('dialog', {variant}),
@@ -566,6 +647,9 @@ export function Dialog({
       onClick={handleClick}
       onCancel={handleCancel}
       aria-modal="true"
+      // The default aria-labelledby (from a DialogHeader title) is set
+      // imperatively in `attachDialog`; a consumer-provided aria-labelledby
+      // flows through {...safeProps} above and wins.
       {...(purpose === 'required' ? {role: 'alertdialog'} : undefined)}>
       {innerContent}
     </dialog>

package/src/Dialog/DialogContext.ts

@@ -5,8 +5,8 @@
 /**
  * @file DialogContext.ts
  * @input React context
- * @output Internal dialog context for child focus behavior
- * @position Dialog internals; consumed by focus-managing children
+ * @output Internal dialog context for child focus behavior and default labelling
+ * @position Dialog internals; consumed by focus-managing children and DialogHeader
  */
 
 import {createContext, use} from 'react';
@@ -14,6 +14,13 @@ import {createContext, use} from 'react';
 export interface DialogContextValue {
   /** Whether the dialog is rendered inline for docs/showcases. */
   isInline: boolean;
+  /**
+   * Id the DialogHeader title should render with so the dialog can name
+   * itself via aria-labelledby. The dialog detects the title element's
+   * presence directly (via a callback ref), so it only emits aria-labelledby
+   * when the title actually rendered — never pointing at a nonexistent id.
+   */
+  titleId?: string;
 }
 
 export const DialogContext = createContext<DialogContextValue | null>(null);

package/src/Dialog/DialogHeader.doc.mjs

@@ -12,7 +12,7 @@ export const docs = {
     {
       name: 'title',
       type: 'string',
-      description: 'Dialog title (receives focus on open).',
+      description: 'Dialog title (receives focus on open and labels the dialog via aria-labelledby).',
     },
     {
       name: 'subtitle',
@@ -158,7 +158,7 @@ export const docsDense = {
   displayName: 'Dialog Header',
   description: 'dialog header w/ title, optional subtitle, close button, start/end content slots',
   propDescriptions: {
-    title: 'dialog title (receives focus on open)',
+    title: 'dialog title (focused on open; labels dialog via aria-labelledby)',
     subtitle: 'subtitle below title',
     onOpenChange: 'close button callback (omit=no button)',
     startContent: 'content before title (e.g. back button)',

package/src/Dialog/DialogHeader.tsx

@@ -65,7 +65,9 @@ export interface DialogHeaderProps extends BaseProps<HTMLDivElement> {
   ref?: React.Ref<HTMLDivElement>;
   /**
    * The title of the dialog.
-   * This title receives focus when the dialog opens for screen reader accessibility.
+   * This title receives focus when the dialog opens for screen reader
+   * accessibility, and names the parent Dialog via aria-labelledby unless the
+   * consumer passes an explicit aria-label/aria-labelledby to the Dialog.
    */
   title: string;
 
@@ -105,7 +107,8 @@ export interface DialogHeaderProps extends BaseProps<HTMLDivElement> {
  * Renders a title that receives focus when a modal dialog opens (for screen reader accessibility)
  * and an optional close button. Inline documentation previews suppress this autofocus.
  * The title is an h2 element with tabIndex={-1} so it can be programmatically focused but
- * doesn't appear in the tab order.
+ * doesn't appear in the tab order. The title also names the parent Dialog via
+ * aria-labelledby (unless the Dialog receives an explicit aria-label/aria-labelledby).
  *
  * Uses LayoutHeader internally for consistent styling with other layout headers.
  *
@@ -137,10 +140,13 @@ export function DialogHeader({
   const titleRef = useRef<HTMLHeadingElement>(null);
   const dialogContext = useDialogContext();
   const shouldAutoFocus = dialogContext?.isInline !== true;
+  const titleId = dialogContext?.titleId;
 
   // Auto-focus the title when mounted for screen reader accessibility.
   // Inline dialogs are documentation/showcase previews, so suppress focus to
   // avoid stealing scroll position from the surrounding page.
+  // The parent Dialog detects this title (by `titleId`) via a callback ref to
+  // set its default aria-labelledby — no registration handshake needed here.
   useEffect(() => {
     if (shouldAutoFocus && titleRef.current) {
       titleRef.current.focus();
@@ -162,6 +168,7 @@ export function DialogHeader({
         <div {...stylex.props(styles.titleWrapper)}>
           <Heading
             ref={titleRef}
+            id={titleId}
             level={2}
             tabIndex={-1}
             xstyle={styles.titleFocusable}>

package/src/Divider/Divider.tsx

@@ -172,6 +172,7 @@ export function Divider({
   return (
     <div
       ref={ref}
+      {...props}
       role="separator"
       aria-orientation={orientation}
       {...mergeProps(
@@ -186,8 +187,7 @@ export function Divider({
         ),
         className,
         style,
-      )}
-      {...props}>
+      )}>
       <div
         {...stylex.props(
           isHorizontal ? lineStyles.horizontalLine : lineStyles.verticalLine,

package/src/DropdownMenu/DropdownMenu.test.tsx

@@ -613,3 +613,172 @@ describe('DropdownMenu compound mode', () => {
     ).toBeInTheDocument();
   });
 });
+
+describe('DropdownMenu keyboard access for menuitemradio/menuitemcheckbox (#3829)', () => {
+  it('arrow navigation reaches consumer-rendered menuitemradio and menuitemcheckbox items', async () => {
+    const user = userEvent.setup();
+    render(
+      <DropdownMenu button={{label: 'Sort'}}>
+        <DropdownMenuItem label="Edit" onClick={() => {}} />
+        <div role="menuitemradio" tabIndex={-1} aria-checked="false">
+          Newest
+        </div>
+        <div role="menuitemcheckbox" tabIndex={-1} aria-checked="false">
+          Archived
+        </div>
+      </DropdownMenu>,
+    );
+
+    await user.click(screen.getByRole('button', {name: /Sort/}));
+    const menu = screen.getByRole('menu', {hidden: true});
+    screen.getByRole('menuitem', {name: 'Edit', hidden: true}).focus();
+
+    fireEvent.keyDown(menu, {key: 'ArrowDown'});
+    expect(
+      screen.getByRole('menuitemradio', {name: 'Newest', hidden: true}),
+    ).toHaveFocus();
+
+    fireEvent.keyDown(menu, {key: 'ArrowDown'});
+    expect(
+      screen.getByRole('menuitemcheckbox', {name: 'Archived', hidden: true}),
+    ).toHaveFocus();
+  });
+
+  it('activates a focused menuitemradio with Enter and a menuitemcheckbox with Space', async () => {
+    const user = userEvent.setup();
+    const onSelect = vi.fn();
+    const onToggle = vi.fn();
+    render(
+      <DropdownMenu button={{label: 'Sort'}}>
+        <DropdownMenuItem label="Edit" onClick={() => {}} />
+        <div
+          role="menuitemradio"
+          tabIndex={-1}
+          aria-checked="false"
+          onClick={onSelect}>
+          Newest
+        </div>
+        <div
+          role="menuitemcheckbox"
+          tabIndex={-1}
+          aria-checked="false"
+          onClick={onToggle}>
+          Archived
+        </div>
+      </DropdownMenu>,
+    );
+
+    await user.click(screen.getByRole('button', {name: /Sort/}));
+    const menu = screen.getByRole('menu', {hidden: true});
+
+    screen.getByRole('menuitemradio', {name: 'Newest', hidden: true}).focus();
+    fireEvent.keyDown(menu, {key: 'Enter'});
+    expect(onSelect).toHaveBeenCalledTimes(1);
+
+    screen
+      .getByRole('menuitemcheckbox', {name: 'Archived', hidden: true})
+      .focus();
+    fireEvent.keyDown(menu, {key: ' '});
+    expect(onToggle).toHaveBeenCalledTimes(1);
+  });
+
+  it('typeahead matches a menuitemradio label', async () => {
+    const user = userEvent.setup();
+    render(
+      <DropdownMenu button={{label: 'Sort'}}>
+        <DropdownMenuItem label="Edit" onClick={() => {}} />
+        <div role="menuitemradio" tabIndex={-1} aria-checked="false">
+          Newest
+        </div>
+        <div role="menuitemcheckbox" tabIndex={-1} aria-checked="false">
+          Archived
+        </div>
+      </DropdownMenu>,
+    );
+
+    await user.click(screen.getByRole('button', {name: /Sort/}));
+    fireEvent.keyDown(screen.getByRole('menu', {hidden: true}), {key: 'n'});
+    expect(
+      screen.getByRole('menuitemradio', {name: 'Newest', hidden: true}),
+    ).toHaveFocus();
+  });
+
+  it('typeahead matches a menuitemcheckbox label', async () => {
+    const user = userEvent.setup();
+    render(
+      <DropdownMenu button={{label: 'Sort'}}>
+        <DropdownMenuItem label="Edit" onClick={() => {}} />
+        <div role="menuitemradio" tabIndex={-1} aria-checked="false">
+          Newest
+        </div>
+        <div role="menuitemcheckbox" tabIndex={-1} aria-checked="false">
+          Archived
+        </div>
+      </DropdownMenu>,
+    );
+
+    await user.click(screen.getByRole('button', {name: /Sort/}));
+    fireEvent.keyDown(screen.getByRole('menu', {hidden: true}), {key: 'a'});
+    expect(
+      screen.getByRole('menuitemcheckbox', {name: 'Archived', hidden: true}),
+    ).toHaveFocus();
+  });
+
+  it('typeahead skips an aria-disabled item and matches the next enabled label', async () => {
+    const user = userEvent.setup();
+    render(
+      <DropdownMenu button={{label: 'Sort'}}>
+        <DropdownMenuItem label="Edit" onClick={() => {}} />
+        <div role="menuitemradio" tabIndex={-1} aria-disabled="true">
+          Newest
+        </div>
+        <div role="menuitemcheckbox" tabIndex={-1} aria-checked="false">
+          Nightly
+        </div>
+      </DropdownMenu>,
+    );
+
+    await user.click(screen.getByRole('button', {name: /Sort/}));
+    // Anchor the search on 'Edit' so typeahead scans forward and meets the
+    // disabled 'Newest' (also an 'n' match) before the enabled 'Nightly'.
+    // This pins the `:not([aria-disabled="true"])` in MENU_ITEM_SELECTOR: the
+    // menus never pass useTypeahead's `isDisabled` option, so that clause is
+    // the only thing keeping disabled rows out of the typeahead list. An
+    // arrow-key test cannot cover it — useListFocus re-filters disabled items
+    // independently, so arrow navigation is guarded twice over.
+    // The disabled row keeps tabIndex={-1} on purpose: it stays focusable, so
+    // the selector clause is the sole reason focus skips it.
+    screen.getByRole('menuitem', {name: 'Edit', hidden: true}).focus();
+    fireEvent.keyDown(screen.getByRole('menu', {hidden: true}), {key: 'n'});
+    expect(
+      screen.getByRole('menuitemcheckbox', {name: 'Nightly', hidden: true}),
+    ).toHaveFocus();
+  });
+
+  it('skips aria-disabled menuitemradio and menuitemcheckbox items during arrow navigation', async () => {
+    const user = userEvent.setup();
+    render(
+      <DropdownMenu button={{label: 'Sort'}}>
+        <DropdownMenuItem label="Edit" onClick={() => {}} />
+        <div role="menuitemradio" tabIndex={-1} aria-disabled="true">
+          Newest
+        </div>
+        <div role="menuitemcheckbox" tabIndex={-1} aria-disabled="true">
+          Archived
+        </div>
+        <div role="menuitemradio" tabIndex={-1} aria-checked="false">
+          Oldest
+        </div>
+      </DropdownMenu>,
+    );
+
+    await user.click(screen.getByRole('button', {name: /Sort/}));
+    const menu = screen.getByRole('menu', {hidden: true});
+    screen.getByRole('menuitem', {name: 'Edit', hidden: true}).focus();
+
+    fireEvent.keyDown(menu, {key: 'ArrowDown'});
+    expect(
+      screen.getByRole('menuitemradio', {name: 'Oldest', hidden: true}),
+    ).toHaveFocus();
+  });
+});

package/src/DropdownMenu/DropdownMenuCheckboxItem.tsx

@@ -152,8 +152,7 @@ export interface DropdownMenuCheckboxItemProps extends Omit<
  *
  * @example
  * ```
- *  * import {DropdownMenuCheckboxItem} from '@astryxdesign/core/DropdownMenu';
- *
+ * import {DropdownMenuCheckboxItem} from '@astryxdesign/core/DropdownMenu';
  * <DropdownMenu button={{label: 'View'}}>
  *   <DropdownMenuCheckboxItem
  *     label="Show archived"

package/src/DropdownMenu/DropdownMenuRadioGroup.tsx

@@ -77,11 +77,10 @@ export interface DropdownMenuRadioGroupProps extends Omit<
  *
  * @example
  * ```
- *  * import {
+ * import {
  *   DropdownMenuRadioGroup,
  *   DropdownMenuRadioItem,
  * } from '@astryxdesign/core/DropdownMenu';
- *
  * <DropdownMenu button={{label: 'Sort'}}>
  *   <DropdownMenuRadioGroup value={sort} onChange={setSort} aria-label="Sort by">
  *     <DropdownMenuRadioItem value="newest" label="Newest" />

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

@@ -25,6 +25,7 @@ import {FieldStatus} 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';
@@ -215,11 +216,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

package/src/Field/FieldLabel.tsx

@@ -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/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: {