@astryxdesign/core 0.2.0-canary.f306f13 → 0.2.0-canary.fc53ff7

package/src/CheckboxList/CheckboxList.test.tsx

@@ -154,14 +154,105 @@ describe('CheckboxList', () => {
       </CheckboxList>,
     );
 
-    // Click the interactive row (invisible-button pattern), which is where the
-    // composed onClick lives — not the inner checkbox.
-    await user.click(screen.getByRole('button', {name: 'Option B'}));
+    // The row is a pointer-only click surface (no invisible row button — the
+    // checkbox is the option's only tab stop). Click the row's label area,
+    // where the composed onClick fires — not the inner checkbox.
+    expect(
+      screen.queryByRole('button', {name: 'Option B'}),
+    ).not.toBeInTheDocument();
+    // The text also exists in the checkbox's visually hidden <label>; target
+    // the row's label <span> to click the row surface.
+    await user.click(screen.getByText('Option B', {selector: 'span'}));
 
     expect(handleClick).toHaveBeenCalledTimes(1);
     expect(handleChange).toHaveBeenCalledWith(['a', 'b']);
   });
 
+  describe('single tab stop per option (WCAG 4.1.2 / APG checkbox pattern)', () => {
+    it('renders exactly one focusable control per option — the checkbox, no row button', () => {
+      render(
+        <CheckboxList label="Preferences" value={['a']} onChange={() => {}}>
+          <CheckboxListItem label="Option A" value="a" />
+          <CheckboxListItem label="Option B" value="b" />
+        </CheckboxList>,
+      );
+      // No invisible whole-row button duplicating the checkbox's action.
+      expect(screen.queryByRole('button')).not.toBeInTheDocument();
+      for (const item of screen.getAllByRole('listitem')) {
+        const focusables = item.querySelectorAll(
+          'button, a[href], input, select, textarea, [tabindex]:not([tabindex="-1"])',
+        );
+        expect(focusables).toHaveLength(1);
+        expect(focusables[0]).toBe(within(item).getByRole('checkbox'));
+      }
+    });
+
+    it('Tab moves directly from one option checkbox to the next', async () => {
+      const user = userEvent.setup();
+      render(
+        <CheckboxList label="Preferences" value={[]} onChange={() => {}}>
+          <CheckboxListItem label="Option A" value="a" />
+          <CheckboxListItem label="Option B" value="b" />
+        </CheckboxList>,
+      );
+      await user.tab();
+      expect(screen.getByRole('checkbox', {name: 'Option A'})).toHaveFocus();
+      await user.tab();
+      expect(screen.getByRole('checkbox', {name: 'Option B'})).toHaveFocus();
+      // No further tab stop inside the list (the row itself is not focusable).
+      await user.tab();
+      expect(document.body).toHaveFocus();
+    });
+
+    it('clicking the row surface (outside the checkbox) still toggles', async () => {
+      const user = userEvent.setup();
+      const handleChange = vi.fn();
+      render(
+        <CheckboxList label="Preferences" value={['a']} onChange={handleChange}>
+          <CheckboxListItem label="Option A" value="a" />
+          <CheckboxListItem label="Option B" value="b" />
+        </CheckboxList>,
+      );
+      // The text also exists in the checkbox's visually hidden <label>;
+      // target the row's label <span> to click the row surface.
+      await user.click(screen.getByText('Option B', {selector: 'span'}));
+      expect(handleChange).toHaveBeenCalledTimes(1);
+      expect(handleChange).toHaveBeenCalledWith(['a', 'b']);
+    });
+
+    it('toggles with Space on the focused checkbox, which reports checked state', async () => {
+      const user = userEvent.setup();
+      const handleChange = vi.fn();
+      render(
+        <CheckboxList label="Preferences" value={['a']} onChange={handleChange}>
+          <CheckboxListItem label="Option A" value="a" />
+          <CheckboxListItem label="Option B" value="b" />
+        </CheckboxList>,
+      );
+      await user.tab();
+      // The focused control is the checkbox itself, so its accessible name
+      // and checked state are what assistive tech announces on focus.
+      const checkboxA = screen.getByRole('checkbox', {name: 'Option A'});
+      expect(checkboxA).toHaveFocus();
+      expect(checkboxA).toBeChecked();
+      await user.keyboard(' ');
+      expect(handleChange).toHaveBeenCalledTimes(1);
+      expect(handleChange).toHaveBeenCalledWith([]);
+    });
+
+    it('the row itself is not focusable', () => {
+      render(
+        <CheckboxList label="Preferences" value={[]} onChange={() => {}}>
+          <CheckboxListItem label="Option A" value="a" />
+        </CheckboxList>,
+      );
+      const item = screen.getByRole('listitem');
+      expect(item).not.toHaveAttribute('tabindex');
+      item.focus();
+      expect(item).not.toHaveFocus();
+    });
+  });
+
   it('disables all checkboxes when group isDisabled is true', () => {
     render(
       <CheckboxList

package/src/CheckboxList/CheckboxListItem.tsx

@@ -16,12 +16,11 @@
  * - /packages/cli/templates/blocks/components/CheckboxList/ (showcase blocks)
  */
 
-import {use, type MouseEvent, type ReactNode} from 'react';
+import {use, useRef, type ReactNode} from 'react';
 import * as stylex from '@stylexjs/stylex';
 import type {StyleXStyles} from '@stylexjs/stylex';
 import {colorVars} from '../theme/tokens.stylex';
 import type {BaseProps} from '../BaseProps';
-import {composeEventHandlers} from '../utils';
 import {useDevWarning} from '../hooks/useDevWarning';
 import {CheckboxInput} from '../CheckboxInput/CheckboxInput';
 import {ListItem} from '../List/ListItem';
@@ -212,6 +211,14 @@ export function CheckboxListItem({
   // Whether this item is interactive (has a toggle handler)
   const isInteractive = !effectiveReadOnly && (ctx != null || onCheck != null);
 
+  // The checkbox is the row's single keyboard control and action. The row is
+  // an enlarged click/tap target that delegates surface clicks to it via
+  // ListItem's `interactiveRef` (useClickableContainer), so each option is
+  // exactly one tab stop. Delegate whenever the row should respond to clicks:
+  // a toggleable item, or one carrying a consumer `onClick`.
+  const checkboxRef = useRef<HTMLInputElement | null>(null);
+  const hasRowInteraction = isInteractive || onClickProp != null;
+
   const handleToggle = () => {
     if (effectiveDisabled || effectiveReadOnly || isBusy) {
       return;
@@ -244,14 +251,12 @@ export function CheckboxListItem({
       description={description}
       endContent={endContent}
       isDisabled={effectiveDisabled}
-      onClick={
-        isInteractive || onClickProp
-          ? composeEventHandlers<MouseEvent>(
-              onClickProp as ((event: MouseEvent) => void) | undefined,
-              isInteractive ? handleToggle : undefined,
-            )
-          : undefined
-      }
+      // Delegate row clicks to the checkbox instead of wiring onClick (which
+      // would add an invisible row button = a second tab stop). The checkbox
+      // stays the option's sole focusable control (WCAG 4.1.2 / APG checkbox
+      // pattern). A consumer onClick rides on the checkbox itself (below), so
+      // it still fires for both direct and delegated (row-surface) clicks.
+      interactiveRef={hasRowInteraction ? checkboxRef : undefined}
       aria-busy={isBusy || undefined}
       xstyle={
         [
@@ -266,10 +271,12 @@ export function CheckboxListItem({
       style={style}
       startContent={
         <CheckboxInput
+          ref={checkboxRef}
           label={checkboxLabel}
           isLabelHidden
           value={resolvedChecked}
           onChange={() => handleToggle()}
+          onClick={onClickProp}
           isDisabled={effectiveDisabled}
           isReadOnly={effectiveReadOnly}
           isLoading={isBusy}

package/src/CodeBlock/CodeBlock.test.tsx

@@ -14,6 +14,7 @@ import {act, render, screen, fireEvent, waitFor} from '@testing-library/react';
 import {CodeBlock} from './CodeBlock';
 import {__resetLiveRegionsForTest} from '../hooks/useAnnounce';
 import {dracula} from '../theme/syntax';
+import {InternationalizationProvider} from '../i18n';
 
 function politeRegion(): HTMLElement | null {
   return document.querySelector('[data-astryx-live-region="polite"]');
@@ -72,6 +73,22 @@ describe('CodeBlock', () => {
     });
   });
 
+  it('localizes the copy announcement through the i18n catalog', async () => {
+    render(
+      <InternationalizationProvider
+        locale="fr"
+        overrides={{fr: {'@astryx.codeBlock.copied': 'Copié'}}}>
+        <CodeBlock code="const x = 1;" language="javascript" />
+      </InternationalizationProvider>,
+    );
+    // The button label and the live-region announcement share the same key.
+    fireEvent.click(screen.getByRole('button', {name: 'Copy code'}));
+    await waitFor(() => {
+      expect(politeRegion()).toHaveTextContent('Copié');
+    });
+    expect(screen.getByRole('button', {name: 'Copié'})).toBeInTheDocument();
+  });
+
   it('keeps the copied indicator a full 2s after a rapid re-copy', async () => {
     vi.useFakeTimers();
     try {

package/src/CodeBlock/CodeBlock.tsx

@@ -786,7 +786,7 @@ export function CodeBlock({
       setCopied(true);
       // Swapping the button's aria-label alone isn't reliably announced by
       // screen readers, so confirm the copy via a polite live region.
-      announce('Copied');
+      announce(t('@astryx.codeBlock.copied'));
       onCopy?.();
       // Restart the reset timer on every copy — otherwise a rapid re-copy
       // is reverted early by the previous click's timer.
@@ -800,7 +800,7 @@ export function CodeBlock({
     } catch {
       // Clipboard failures leave the copied state unchanged.
     }
-  }, [code, onCopy, announce]);
+  }, [code, onCopy, announce, t]);
 
   const sizeStyle = size === 'sm' ? styles.sizeSm : styles.sizeMd;
   // Digits in the largest line number — sizes the gutter column width.

package/src/ContextMenu/ContextMenu.test.tsx

@@ -136,6 +136,21 @@ describe('ContextMenu', () => {
     expect(HTMLElement.prototype.hidePopover).toHaveBeenCalled();
   });
 
+  it('closes the menu when Tab is pressed inside it (APG menu pattern)', () => {
+    render(
+      <ContextMenu items={[{label: 'Item 1'}]}>
+        <div>Right-click me</div>
+      </ContextMenu>,
+    );
+
+    fireEvent.contextMenu(screen.getByText('Right-click me'));
+    expect(HTMLElement.prototype.showPopover).toHaveBeenCalled();
+
+    const menu = screen.getByRole('menu', {hidden: true});
+    fireEvent.keyDown(menu, {key: 'Tab'});
+    expect(HTMLElement.prototype.hidePopover).toHaveBeenCalled();
+  });
+
   it('ignores Escape during IME composition', () => {
     render(
       <ContextMenu items={[{label: 'Item 1'}]}>
@@ -552,7 +567,7 @@ describe('ContextMenu selectable items', () => {
             <ContextMenuRadioGroup
               value="name"
               onChange={() => {}}
-              aria-label="Sort by">
+              label="Sort by">
               <ContextMenuRadioItem value="name" label="Sort by name" />
               <ContextMenuRadioItem value="date" label="Sort by date" />
             </ContextMenuRadioGroup>
@@ -587,7 +602,7 @@ describe('ContextMenu selectable items', () => {
             <ContextMenuRadioGroup
               value="name"
               onChange={onSort}
-              aria-label="Sort by">
+              label="Sort by">
               <ContextMenuRadioItem value="name" label="Sort by name" />
               <ContextMenuRadioItem value="date" label="Sort by date" />
             </ContextMenuRadioGroup>

package/src/ContextMenu/ContextMenu.tsx

@@ -353,13 +353,22 @@ export function ContextMenu({
         }
         return;
       }
+      // APG menu pattern: Tab closes the menu. Menu items are tabIndex={-1}
+      // so Tab would otherwise leak focus into the page while the menu stayed
+      // open (menus-5). Do NOT preventDefault — closing restores focus to the
+      // previously focused element, and the browser's default Tab then
+      // continues from there to the next element.
+      if (e.key === 'Tab') {
+        closeMenu();
+        return;
+      }
       if (typeahead.onKeyDown(e)) {
         e.preventDefault();
         return;
       }
       listNavKeyDown(e);
     },
-    [listNavKeyDown, typeahead, ownsEvent],
+    [listNavKeyDown, closeMenu, typeahead, ownsEvent],
   );
 
   // Place the zero-size cursor anchor at a point in the trigger's local

package/src/DropdownMenu/DropdownMenuRadioGroup.doc.mjs

@@ -22,16 +22,10 @@ export const docs = {
       description: 'Callback fired when the selected value changes.',
     },
     {
-      name: 'aria-label',
+      name: 'label',
       type: 'string',
       description:
-        'Accessible label for the group. Required (or aria-labelledby) so screen readers announce the radios as a named set, e.g. "Sort by".',
-    },
-    {
-      name: 'aria-labelledby',
-      type: 'string',
-      description:
-        'The id of an element that labels the group, as an alternative to aria-label.',
+        'Accessible name for the group, applied as aria-label so screen readers announce the radios as a named set, e.g. "Sort by". Required. Pass aria-labelledby (via base props) instead when the name already exists as a visible element.',
     },
     {
       name: 'hasCloseOnSelect',
@@ -57,8 +51,7 @@ export const docsZh = {
   propDescriptions: {
     value: '组中当前选中的值。尚无选中项时传 undefined。',
     onChange: '所选值变化时触发的回调。',
-    'aria-label': '组的无障碍标签。必需（或 aria-labelledby），以便屏幕阅读器将单选项作为命名集合朗读。',
-    'aria-labelledby': '标记该组的元素 id，作为 aria-label 的替代。',
+    label: '组的无障碍名称，作为 aria-label 应用，以便屏幕阅读器将单选项作为命名集合朗读，例如“Sort by”。必需。当名称已作为可见元素存在时，可改用 aria-labelledby（通过基础属性）。',
     hasCloseOnSelect: '选择某值是否关闭菜单。默认关闭。',
     children: '组成该组的 DropdownMenuRadioItem。',
   },
@@ -72,8 +65,7 @@ export const docsDense = {
   propDescriptions: {
     value: 'selected value (undefined = none)',
     onChange: 'fired when selected value changes',
-    'aria-label': 'accessible group name (or aria-labelledby); required',
-    'aria-labelledby': 'id of labelling element (alt to aria-label)',
+    label: 'accessible group name (applied as aria-label); required',
     hasCloseOnSelect: 'close menu on select (default true)',
     children: 'the DropdownMenuRadioItems',
   },

package/src/DropdownMenu/DropdownMenuRadioGroup.tsx

@@ -49,16 +49,13 @@ export interface DropdownMenuRadioGroupProps extends Omit<
    */
   onChange: (value: string) => void;
   /**
-   * Accessible label for the group. Required (together with `aria-labelledby`,
-   * one of the two) so screen readers announce the radios as a named set,
-   * e.g. "Sort by".
+   * Accessible name for the group, announced by screen readers so the radios
+   * read as a named set (e.g. "Sort by"). Applied as the group's `aria-label`.
+   * Required -- an unnamed radio group is an accessibility defect. Pass
+   * `aria-labelledby` (via base props) instead if the name already exists as a
+   * visible element on the page.
    */
-  'aria-label'?: string;
-  /**
-   * The id of an element that labels the group, as an alternative to
-   * `aria-label`.
-   */
-  'aria-labelledby'?: string;
+  label: string;
   /**
    * Whether selecting a value closes the menu. Radio items default to closing
    * on selection (a single-choice commit), unlike checkbox items which stay
@@ -82,7 +79,7 @@ export interface DropdownMenuRadioGroupProps extends Omit<
  *   DropdownMenuRadioItem,
  * } from '@astryxdesign/core/DropdownMenu';
  * <DropdownMenu button={{label: 'Sort'}}>
- *   <DropdownMenuRadioGroup value={sort} onChange={setSort} aria-label="Sort by">
+ *   <DropdownMenuRadioGroup value={sort} onChange={setSort} label="Sort by">
  *     <DropdownMenuRadioItem value="newest" label="Newest" />
  *     <DropdownMenuRadioItem value="oldest" label="Oldest" />
  *   </DropdownMenuRadioGroup>
@@ -92,6 +89,7 @@ export interface DropdownMenuRadioGroupProps extends Omit<
 export function DropdownMenuRadioGroup({
   value,
   onChange,
+  label,
   hasCloseOnSelect = true,
   children,
   className,
@@ -107,6 +105,7 @@ export function DropdownMenuRadioGroup({
     <div
       {...rest}
       role="group"
+      aria-label={label}
       {...mergeProps(stylex.props(styles.group), {className, style})}>
       <DropdownMenuRadioGroupContext value={contextValue}>
         {children}

package/src/DropdownMenu/DropdownMenuRadioItem.tsx

@@ -145,7 +145,7 @@ export interface DropdownMenuRadioItemProps extends Omit<
  *
  * @example
  * ```
- * <DropdownMenuRadioGroup value={sort} onChange={setSort} aria-label="Sort by">
+ * <DropdownMenuRadioGroup value={sort} onChange={setSort} label="Sort by">
  *   <DropdownMenuRadioItem value="newest" label="Newest" />
  *   <DropdownMenuRadioItem value="oldest" label="Oldest" icon="clock" />
  * </DropdownMenuRadioGroup>

package/src/DropdownMenu/DropdownMenuSelectable.test.tsx

@@ -110,7 +110,7 @@ describe('DropdownMenuRadioGroup / RadioItem', () => {
         <DropdownMenuRadioGroup
           value="newest"
           onChange={() => {}}
-          aria-label="Sort by">
+          label="Sort by">
           <DropdownMenuRadioItem value="newest" label="Newest" />
           <DropdownMenuRadioItem value="oldest" label="Oldest" />
         </DropdownMenuRadioGroup>
@@ -136,7 +136,7 @@ describe('DropdownMenuRadioGroup / RadioItem', () => {
         <DropdownMenuRadioGroup
           value="newest"
           onChange={onChange}
-          aria-label="Sort by">
+          label="Sort by">
           <DropdownMenuRadioItem value="newest" label="Newest" />
           <DropdownMenuRadioItem value="oldest" label="Oldest" />
         </DropdownMenuRadioGroup>
@@ -149,6 +149,24 @@ describe('DropdownMenuRadioGroup / RadioItem', () => {
     expect(onChange).toHaveBeenCalledWith('oldest');
   });
 
+  it('names the group from the required label prop', async () => {
+    const user = userEvent.setup();
+    render(
+      <DropdownMenu button={{label: 'Sort'}}>
+        <DropdownMenuRadioGroup
+          value="newest"
+          onChange={() => {}}
+          label="Sort by">
+          <DropdownMenuRadioItem value="newest" label="Newest" />
+        </DropdownMenuRadioGroup>
+      </DropdownMenu>,
+    );
+    await user.click(screen.getByRole('button', {name: /Sort/}));
+    expect(
+      screen.getByRole('group', {name: 'Sort by', hidden: true}),
+    ).toBeInTheDocument();
+  });
+
   it('throws when a radio item is used outside a group', () => {
     const spy = vi.spyOn(console, 'error').mockImplementation(() => {});
     expect(() =>

package/src/DropdownMenu/DropdownMenuSubMenu.test.tsx

@@ -8,7 +8,7 @@
 
 import {describe, it, expect, vi, beforeEach} from 'vitest';
 import {useState} from 'react';
-import {render, screen, waitFor} from '@testing-library/react';
+import {render, screen, waitFor, fireEvent} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import {DropdownMenu} from './DropdownMenu';
 import {DropdownMenuItem} from './DropdownMenuItem';
@@ -510,6 +510,34 @@ describe('DropdownMenuSubMenu accessibility (WCAG 2.2 / APG)', () => {
     expect(onPick).toHaveBeenCalledWith('data');
   });
 
+  // Regression: hovering the submenu trigger while a sibling item still holds
+  // focus must move the single focus-driven highlight onto the trigger — not
+  // leave two items highlighted at once (the trigger via :hover, the sibling
+  // via :focus). Mirrors DropdownMenuItem's hover-focus behavior.
+  it('moves focus to the submenu trigger on hover, keeping a single highlight', async () => {
+    const user = userEvent.setup();
+    render(<MoveMenu />);
+    await user.click(screen.getByRole('button', {name: /Actions/}));
+
+    const rename = screen.getByRole('menuitem', {
+      name: 'Rename',
+      hidden: true,
+    });
+    const trigger = screen.getByRole('menuitem', {
+      name: /Move to/,
+      hidden: true,
+    });
+
+    rename.focus();
+    expect(rename).toHaveFocus();
+
+    // A mouse hover over the submenu trigger moves focus onto it, so the single
+    // focus-driven highlight follows the pointer instead of leaving two.
+    fireEvent.pointerMove(trigger, {pointerType: 'mouse'});
+    expect(trigger).toHaveFocus();
+    expect(rename).not.toHaveFocus();
+  });
+
   // 1.4.13 Content on Hover or Focus: the flyout stays open while the pointer
   // is over it (moving onto the flyout must not dismiss it).
   it('keeps the flyout open while the pointer is over it', async () => {

package/src/DropdownMenu/DropdownMenuSubMenu.tsx

@@ -44,6 +44,7 @@ import React, {
   useMemo,
   useRef,
   useState,
+  type PointerEvent,
   type ReactNode,
 } from 'react';
 import * as stylex from '@stylexjs/stylex';
@@ -78,6 +79,7 @@ import {
   useDropdownMenuContext,
   type DropdownMenuContextValue,
 } from './DropdownMenuContext';
+import {focusMenuItemOnHover} from './menuItemHover';
 
 const triggerStyles = stylex.create({
   root: {
@@ -93,11 +95,6 @@ const triggerStyles = stylex.create({
       default: 'transparent',
       ':focus': colorVars['--color-overlay-hover'],
     },
-    ':hover': {
-      '@media (hover: hover)': {
-        backgroundColor: colorVars['--color-overlay-hover'],
-      },
-    },
     border: 'none',
     cursor: 'pointer',
     textAlign: 'start',
@@ -393,6 +390,16 @@ export function DropdownMenuSubMenu(
     [isDisabled, open],
   );
 
+  // Move the single focus-driven highlight onto the trigger as the pointer
+  // enters it, so a sibling item that still holds focus doesn't stay
+  // highlighted alongside the hovered trigger. This is separate from the
+  // hover-open intent (onMouseEnter/onMouseLeave) — the flyout still opens on
+  // the hover delay; this only keeps the highlight single.
+  const handlePointerMove = useCallback(
+    (e: PointerEvent<HTMLElement>) => focusMenuItemOnHover(e, isDisabled),
+    [isDisabled],
+  );
+
   // Enter/Space activate the focused row; typeahead jumps by first character;
   // the close key (Left, or Right in RTL) returns focus to the trigger;
   // arrows/Home/End defer to useListFocus (RTL-aware).
@@ -494,6 +501,7 @@ export function DropdownMenuSubMenu(
         data-testid={testId}
         onMouseEnter={triggerProps.onMouseEnter}
         onMouseLeave={triggerProps.onMouseLeave}
+        onPointerMove={handlePointerMove}
         startContent={
           icon
             ? renderIconSlot(icon, {size: 'sm', color: 'secondary'})

package/src/DropdownMenu/menuItemHover.ts

@@ -16,6 +16,7 @@
  * - /packages/core/src/DropdownMenu/DropdownMenuItem.tsx
  * - /packages/core/src/DropdownMenu/DropdownMenuCheckboxItem.tsx
  * - /packages/core/src/DropdownMenu/DropdownMenuRadioItem.tsx
+ * - /packages/core/src/DropdownMenu/DropdownMenuSubMenu.tsx
  */
 
 import type {PointerEvent} from 'react';

package/src/Field/Field.doc.mjs

@@ -30,6 +30,10 @@ export const docs = {
       {className: 'astryx-field', visualProps: ['layout']},
       {className: 'astryx-field-label'},
       {className: 'astryx-field-status', visualProps: ['type', 'variant']},
+      {
+        className: 'astryx-input-status-icon',
+        visualProps: ['size', 'status'],
+      },
     ],
     vars: [
       {name: '--_field-radius', description: 'Border radius of input fields', default: 'var(--radius-element)', private: true},

package/src/Field/FieldLabel.test.tsx

@@ -12,6 +12,7 @@
 import {describe, it, expect, vi} from 'vitest';
 import {render, screen} from '@testing-library/react';
 import {TestIcon} from '../__tests__/TestIcon';
+import {InternationalizationProvider} from '../i18n';
 import {FieldLabel} from './FieldLabel';
 
 describe('FieldLabel', () => {
@@ -36,6 +37,30 @@ describe('FieldLabel', () => {
     expect(screen.getByText(/Required/)).toBeInTheDocument();
   });
 
+  it('localizes the required indicator via the i18n provider', () => {
+    render(
+      <InternationalizationProvider
+        locale="fr"
+        overrides={{fr: {'@astryx.field.required': 'Obligatoire'}}}>
+        <FieldLabel label="Nom" inputID="name-input" isRequired />
+      </InternationalizationProvider>,
+    );
+    expect(screen.getByText(/Obligatoire/)).toBeInTheDocument();
+    expect(screen.queryByText(/Required/)).not.toBeInTheDocument();
+  });
+
+  it('localizes the optional indicator via the i18n provider', () => {
+    render(
+      <InternationalizationProvider
+        locale="fr"
+        overrides={{fr: {'@astryx.field.optional': 'Facultatif'}}}>
+        <FieldLabel label="Nom" inputID="name-input" isOptional />
+      </InternationalizationProvider>,
+    );
+    expect(screen.getByText(/Facultatif/)).toBeInTheDocument();
+    expect(screen.queryByText(/Optional/)).not.toBeInTheDocument();
+  });
+
   it('shows Optional when both isOptional and isRequired are true', () => {
     render(
       <FieldLabel label="Name" inputID="name-input" isOptional isRequired />,

package/src/Field/FieldLabel.tsx

@@ -1,8 +1,10 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
+'use client';
+
 /**
  * @file FieldLabel.tsx
- * @input Uses React, Icon, IconType
+ * @input Uses React, Icon, IconType, useTranslator
  * @output Exports FieldLabel component, FieldLabelProps
  * @position Core label implementation; used by Field, CheckboxInput, Switch
  *
@@ -10,6 +12,7 @@
  * - /packages/core/src/Field/Field.doc.mjs (props table, features, implementation notes)
  * - /packages/core/src/Field/index.ts (exports if types change)
  * - /packages/cli/templates/blocks/components/Field/ (showcase blocks)
+ * - /packages/core/locales/en.json (@astryx.field.required / @astryx.field.optional)
  */
 
 import type {ReactNode} from 'react';
@@ -26,6 +29,7 @@ import {
 } from '../theme/tokens.stylex';
 import {Icon, renderIconSlot, type IconType} from '../Icon';
 import {Tooltip} from '../Tooltip';
+import {useTranslator} from '../i18n';
 import {themeProps} from '../utils/themeProps';
 
 const styles = stylex.create({
@@ -177,7 +181,12 @@ export function FieldLabel({
   ref,
   ...rest
 }: FieldLabelProps) {
-  const statusText = isOptional ? 'Optional' : isRequired ? 'Required' : null;
+  const t = useTranslator();
+  const statusText = isOptional
+    ? t('@astryx.field.optional')
+    : isRequired
+      ? t('@astryx.field.required')
+      : null;
 
   // A group label (e.g. for a radiogroup) must not be a literal `<label>`
   // element: a `<label>` semantically names a single form control and can't be

package/src/FieldStatus/FieldStatus.doc.mjs

@@ -12,6 +12,7 @@ export const docs = {
   theming: {
     targets: [
       {className: 'astryx-field-status', visualProps: ['type', 'variant']},
+      {className: 'astryx-field-status-icon', visualProps: ['type']},
     ],
   },
   props: [