@astryxdesign/core 0.4.3 → 0.4.4-canary.0e8af82

package/src/FileInput/FileInput.test.tsx

@@ -20,6 +20,12 @@ import {
 import userEvent from '@testing-library/user-event';
 import {FileInput} from './FileInput';
 import {__resetLiveRegionsForTest} from '../hooks/useAnnounce';
+import {InternationalizationProvider} from '../i18n';
+
+// The `=1` branch names the file; the `other` branch must not. Both come from
+// this test, so neither can pass against a hardcoded English string.
+const FILE_SELECTED = 'Un fichier choisi : {fileName}';
+const FILES_SELECTED = '{count, number} fichiers choisis';
 
 afterEach(() => {
   __resetLiveRegionsForTest();
@@ -324,23 +330,36 @@ describe('FileInput', () => {
 
   describe('announcements', () => {
     it('announces a single file selection politely', async () => {
-      render(<FileInput label="Upload" value={null} onChange={() => {}} />);
+      render(
+        <InternationalizationProvider
+          locale="fr"
+          overrides={{fr: {'@astryx.fileInput.fileSelected': FILE_SELECTED}}}>
+          <FileInput label="Upload" value={null} onChange={() => {}} />
+        </InternationalizationProvider>,
+      );
       fireEvent.change(fileInputEl(), {
         target: {files: [createFile('report.pdf', 100)]},
       });
       await waitFor(() => {
-        expect(politeRegion()).toHaveTextContent('1 file selected: report.pdf');
+        // The single-file key, carrying the file name.
+        expect(politeRegion()?.textContent).toBe(
+          'Un fichier choisi : report.pdf',
+        );
       });
     });
 
     it('announces a multi-file count politely', async () => {
       render(
-        <FileInput
-          label="Upload"
-          value={null}
-          onChange={() => {}}
-          isMultiple
-        />,
+        <InternationalizationProvider
+          locale="fr"
+          overrides={{fr: {'@astryx.fileInput.filesSelected': FILES_SELECTED}}}>
+          <FileInput
+            label="Upload"
+            value={null}
+            onChange={() => {}}
+            isMultiple
+          />
+        </InternationalizationProvider>,
       );
       const files = [
         createFile('a.txt', 100),
@@ -349,7 +368,32 @@ describe('FileInput', () => {
       ];
       fireEvent.change(fileInputEl(), {target: {files}});
       await waitFor(() => {
-        expect(politeRegion()).toHaveTextContent('3 files selected');
+        // The multi-file key: a count, and no file name.
+        expect(politeRegion()?.textContent).toBe('3 fichiers choisis');
+      });
+      expect(politeRegion()?.textContent).not.toContain('a.txt');
+    });
+
+    it('speaks the selection from a provider catalog', async () => {
+      render(
+        <InternationalizationProvider
+          locale="fr"
+          messages={{
+            fr: {
+              '@astryx.fileInput.fileSelected': {defaultMessage: FILE_SELECTED},
+            },
+          }}>
+          <FileInput label="Upload" value={null} onChange={() => {}} />
+        </InternationalizationProvider>,
+      );
+      fireEvent.change(fileInputEl(), {
+        target: {files: [createFile('report.pdf', 100)]},
+      });
+      await waitFor(() => {
+        // Same key through the catalog path rather than `overrides`.
+        expect(politeRegion()?.textContent).toBe(
+          'Un fichier choisi : report.pdf',
+        );
       });
     });
 

package/src/FormLayout/FormLayout.doc.mjs

@@ -16,6 +16,12 @@ export const docs = {
         'Controls field arrangement. Vertical stacks top-to-bottom, horizontal arranges left-to-right with equal flex-grow, and horizontal-labels uses CSS Grid with labels to the left of inputs (collapses to vertical on narrow viewports <=480px).',
       default: "'vertical'",
     },
+    {
+      name: 'defaultOptionality',
+      type: "'optional' | 'required'",
+      description:
+        'The state the form treats as its default, so only the exception shows an optional/required indicator. With "optional", only fields marked isRequired show an indicator; with "required", only fields marked isOptional do. A field that restates the default shows nothing. Under "required" the unmarked fields also expose aria-required so screen readers match the visual default — aria-required only, never the native required attribute. Leave unset for today\'s per-field behavior.',
+    },
     {
       name: 'children',
       type: 'ReactNode',
@@ -64,6 +70,12 @@ export const docsZh = {
         '控制字段排列方式。vertical 从上到下堆叠，horizontal 从左到右排列且等比弹性增长，horizontal-labels 使用 CSS Grid 将标签放在输入框左侧（在窄视口 <=480px 时折叠为垂直布局）。',
       default: "'vertical'",
     },
+    {
+      name: 'defaultOptionality',
+      type: "'optional' | 'required'",
+      description:
+        '表单视为默认的状态，因此仅例外字段显示可选/必填指示器。设为 "optional" 时，仅标记 isRequired 的字段显示指示器；设为 "required" 时，仅标记 isOptional 的字段显示。与默认一致的字段不显示任何内容。设为 "required" 时，未标记的字段仍会暴露 aria-required，使屏幕阅读器与视觉默认一致——仅作用于 aria-required，不改变原生 required 属性。不设置则保持当前逐字段行为。',
+    },
     {
       name: 'children',
       type: 'ReactNode',
@@ -122,6 +134,7 @@ export const docsDense = {
   },
   propDescriptions: {
     direction: 'Field arrangement. Vertical stacks top-to-bottom, horizontal arranges left-to-right w/ equal flex-grow, horizontal-labels uses CSS Grid w/ labels left of inputs (collapses <=480px).',
+    defaultOptionality: 'State the form treats as default, so only the exception is marked. "optional" → only isRequired fields show an indicator; "required" → only isOptional fields do. Under "required" unmarked fields also expose aria-required (aria only, not native required). Unset = per-field behavior.',
     children: 'Form fields to arrange. Accepts Astryx inputs + Field-wrapped custom controls.',
     xstyle: 'StyleX styles for layout customization. Must be stylex.create() value.',
   },

package/src/FormLayout/FormLayout.test.tsx

@@ -16,6 +16,8 @@ import {FormLayout} from './FormLayout';
 import {FormLayoutContext} from './FormLayoutContext';
 import type {FormLayoutDirection} from './FormLayoutContext';
 import {Field} from '../Field';
+import {TextInput} from '../TextInput';
+import {CheckboxInput} from '../CheckboxInput';
 
 // Helper component to read context
 function DirectionReader() {
@@ -23,6 +25,12 @@ function DirectionReader() {
   return <span data-testid="direction">{direction}</span>;
 }
 
+// Helper component to read the defaultOptionality context value
+function OptionalityReader() {
+  const {defaultOptionality} = use(FormLayoutContext);
+  return <span data-testid="optionality">{defaultOptionality ?? 'unset'}</span>;
+}
+
 describe('FormLayout', () => {
   // ─── Basic rendering ────────────────────────────────────────────────────
 
@@ -154,6 +162,178 @@ describe('FormLayout', () => {
     expect(screen.getByTestId('inner-child-2')).toBeInTheDocument();
   });
 
+  // ─── defaultOptionality context propagation ─────────────────────────────
+
+  it('leaves defaultOptionality unset by default', () => {
+    render(
+      <FormLayout>
+        <OptionalityReader />
+      </FormLayout>,
+    );
+    expect(screen.getByTestId('optionality')).toHaveTextContent('unset');
+  });
+
+  it('provides defaultOptionality="optional" to children', () => {
+    render(
+      <FormLayout defaultOptionality="optional">
+        <OptionalityReader />
+      </FormLayout>,
+    );
+    expect(screen.getByTestId('optionality')).toHaveTextContent('optional');
+  });
+
+  it('provides defaultOptionality="required" to children', () => {
+    render(
+      <FormLayout defaultOptionality="required">
+        <OptionalityReader />
+      </FormLayout>,
+    );
+    expect(screen.getByTestId('optionality')).toHaveTextContent('required');
+  });
+
+  it('an inner layout shadows the outer defaultOptionality', () => {
+    render(
+      <FormLayout defaultOptionality="optional">
+        <FormLayout defaultOptionality="required">
+          <OptionalityReader />
+        </FormLayout>
+      </FormLayout>,
+    );
+    expect(screen.getByTestId('optionality')).toHaveTextContent('required');
+  });
+
+  // ─── defaultOptionality indicator behavior (through Field) ───────────────
+  //
+  // The rule: only the *exception* is marked. A field that restates the form
+  // default shows nothing; a deviation shows its indicator.
+
+  it('optional default: only isRequired fields show an indicator', () => {
+    render(
+      <FormLayout defaultOptionality="optional">
+        <Field label="Bio" inputID="bio">
+          <input id="bio" />
+        </Field>
+        <Field label="Nickname" inputID="nick" isOptional>
+          <input id="nick" />
+        </Field>
+        <Field label="Email" inputID="email" isRequired>
+          <input id="email" />
+        </Field>
+      </FormLayout>,
+    );
+    // Plain + isOptional match the default → nothing shown.
+    expect(screen.queryByText(/Optional/)).not.toBeInTheDocument();
+    // isRequired deviates → the required indicator shows.
+    expect(screen.getByText(/Required/)).toBeInTheDocument();
+  });
+
+  it('required default: only isOptional fields show an indicator', () => {
+    render(
+      <FormLayout defaultOptionality="required">
+        <Field label="Name" inputID="name">
+          <input id="name" />
+        </Field>
+        <Field label="Email" inputID="email" isRequired>
+          <input id="email" />
+        </Field>
+        <Field label="Nickname" inputID="nick" isOptional>
+          <input id="nick" />
+        </Field>
+      </FormLayout>,
+    );
+    // Plain + isRequired match the default → nothing shown.
+    expect(screen.queryByText(/Required/)).not.toBeInTheDocument();
+    // isOptional deviates → the optional indicator shows.
+    expect(screen.getByText(/Optional/)).toBeInTheDocument();
+  });
+
+  it('unset default preserves per-field indicators (backwards compatible)', () => {
+    render(
+      <FormLayout>
+        <Field label="Email" inputID="email" isRequired>
+          <input id="email" />
+        </Field>
+        <Field label="Nickname" inputID="nick" isOptional>
+          <input id="nick" />
+        </Field>
+      </FormLayout>,
+    );
+    expect(screen.getByText(/Required/)).toBeInTheDocument();
+    expect(screen.getByText(/Optional/)).toBeInTheDocument();
+  });
+
+  // ─── defaultOptionality aria-required resolution ─────────────────────────
+  //
+  // The indicator is suppressed for the unmarked majority, so the matching
+  // `aria-required` must still be exposed — otherwise a sighted user reads a
+  // field as required (form default, no indicator) while a screen reader hears
+  // "not required". Native `required` stays bound to the explicit prop so a
+  // layout default never switches on browser validation.
+
+  it('required default: an unmarked input still exposes aria-required', () => {
+    render(
+      <FormLayout defaultOptionality="required">
+        <TextInput label="Name" value="" onChange={() => {}} />
+      </FormLayout>,
+    );
+    expect(screen.getByLabelText('Name')).toHaveAttribute(
+      'aria-required',
+      'true',
+    );
+  });
+
+  it('required default: an isOptional input is not aria-required', () => {
+    render(
+      <FormLayout defaultOptionality="required">
+        <TextInput label="Nickname" value="" onChange={() => {}} isOptional />
+      </FormLayout>,
+    );
+    expect(screen.getByRole('textbox')).not.toHaveAttribute('aria-required');
+  });
+
+  it('optional default: an unmarked input is not aria-required', () => {
+    render(
+      <FormLayout defaultOptionality="optional">
+        <TextInput label="Bio" value="" onChange={() => {}} />
+      </FormLayout>,
+    );
+    expect(screen.getByLabelText('Bio')).not.toHaveAttribute('aria-required');
+  });
+
+  it('no layout: an unmarked input is not aria-required (backwards compatible)', () => {
+    render(<TextInput label="Solo" value="" onChange={() => {}} />);
+    expect(screen.getByLabelText('Solo')).not.toHaveAttribute('aria-required');
+  });
+
+  it('required default resolves aria-required without native required', () => {
+    render(
+      <FormLayout defaultOptionality="required">
+        <CheckboxInput label="Terms" value={false} onChange={() => {}} />
+      </FormLayout>,
+    );
+    const checkbox = screen.getByRole('checkbox', {name: 'Terms'});
+    // Announced as required (form default)…
+    expect(checkbox).toHaveAttribute('aria-required', 'true');
+    // …but the native `required` attribute is not switched on by the layout.
+    expect(checkbox).not.toHaveAttribute('required');
+  });
+
+  it('explicit isRequired still drives native required under a layout', () => {
+    render(
+      <FormLayout defaultOptionality="required">
+        <CheckboxInput
+          label="Consent"
+          value={false}
+          onChange={() => {}}
+          isRequired
+        />
+      </FormLayout>,
+    );
+    const checkbox = screen.getByRole('checkbox', {name: 'Consent'});
+    expect(checkbox).toHaveAttribute('aria-required', 'true');
+    expect(checkbox).toHaveAttribute('required');
+  });
+
   // ─── Snapshot tests ─────────────────────────────────────────────────────
 
   it('matches snapshot for vertical direction', () => {
@@ -223,10 +403,7 @@ describe('FormLayout', () => {
   it('horizontal-labels with Field: label and input wrapper are siblings under display:contents', () => {
     render(
       <FormLayout direction="horizontal-labels" data-testid="layout">
-        <Field
-          label="Username"
-          inputID="username"
-          data-testid="username-field">
+        <Field label="Username" inputID="username" data-testid="username-field">
           <input id="username" data-testid="username-input" />
         </Field>
       </FormLayout>,

package/src/FormLayout/FormLayout.tsx

@@ -10,7 +10,10 @@
  *
  * SYNC: When modified, update these files to stay in sync:
  * - /packages/core/src/FormLayout/FormLayout.test.tsx (tests for new/changed behavior)
+ * - /packages/core/src/FormLayout/FormLayoutContext.ts (context value shape)
+ * - /packages/core/src/FormLayout/FormLayout.doc.mjs (props table)
  * - /packages/core/src/FormLayout/index.ts (exports if types change)
+ * - /packages/core/src/Field/FieldLabel.tsx (defaultOptionality indicator resolution)
  * - /apps/storybook/stories/FormLayout.stories.tsx (storybook stories)
  * - /packages/cli/assets/templates/blocks/components/FormLayout/ (showcase blocks)
  */
@@ -19,7 +22,11 @@ import {useMemo, type ReactNode} from 'react';
 import type {BaseProps} from '../BaseProps';
 import * as stylex from '@stylexjs/stylex';
 import {spacingVars} from '../theme/tokens.stylex';
-import {FormLayoutContext, type FormLayoutDirection} from './FormLayoutContext';
+import {
+  FormLayoutContext,
+  type FormLayoutDirection,
+  type FormOptionality,
+} from './FormLayoutContext';
 import {mergeProps} from '../utils';
 import {themeProps} from '../utils/themeProps';
 
@@ -82,6 +89,26 @@ export interface FormLayoutProps extends BaseProps<HTMLDivElement> {
    * @default 'vertical'
    */
   direction?: FormLayoutDirection;
+
+  /**
+   * Which state the form treats as its default, so only the *exception*
+   * carries a visible optional/required indicator. It also resolves each
+   * field's `aria-required` so the unmarked majority is still announced
+   * correctly — but only `aria-required`, never the native `required`
+   * attribute, so a layout default can't switch on browser validation.
+   *
+   * - `'optional'` — fields read as optional; only a field with `isRequired`
+   *   shows an indicator (the "required" one).
+   * - `'required'` — fields read as required; only a field with `isOptional`
+   *   shows an indicator (the "optional" one). Fields without `isOptional`
+   *   expose `aria-required` even though they show no indicator.
+   * - unset — today's behavior: `isRequired` and `isOptional` each show their
+   *   own indicator independently.
+   *
+   * A field that merely restates the default (e.g. `isOptional` under
+   * `'optional'`) shows nothing. An inner `FormLayout` shadows an outer one.
+   */
+  defaultOptionality?: FormOptionality;
 }
 
 // =============================================================================
@@ -109,13 +136,17 @@ export interface FormLayoutProps extends BaseProps<HTMLDivElement> {
 export function FormLayout({
   children,
   direction = 'vertical',
+  defaultOptionality,
   xstyle,
   className,
   style,
   ref,
   ...props
 }: FormLayoutProps) {
-  const contextValue = useMemo(() => ({direction}), [direction]);
+  const contextValue = useMemo(
+    () => ({direction, defaultOptionality}),
+    [direction, defaultOptionality],
+  );
 
   return (
     <FormLayoutContext value={contextValue}>

package/src/FormLayout/FormLayoutContext.ts

@@ -5,10 +5,13 @@
 /**
  * @file FormLayoutContext.ts
  * @input Uses React createContext
- * @output Exports FormLayoutContext and FormLayoutDirection type
- * @position Context for form layout direction detection
+ * @output Exports FormLayoutContext, FormLayoutDirection, and FormOptionality types
+ * @position Context for form layout direction + default-optionality detection
  *
  * SYNC: When modified, update these files to stay in sync:
+ * - /packages/core/src/FormLayout/FormLayout.tsx (prop + context value)
+ * - /packages/core/src/Field/FieldLabel.tsx (indicator resolution)
+ * - /packages/core/src/FormLayout/index.ts (exports if types change)
  */
 
 import {createContext} from 'react';
@@ -22,15 +25,27 @@ import {createContext} from 'react';
  *   of their inputs (settings/admin panel pattern).
  */
 export type FormLayoutDirection =
-  | 'vertical'
-  | 'horizontal'
-  | 'horizontal-labels';
+  'vertical' | 'horizontal' | 'horizontal-labels';
 
 /**
- * Context for detecting which form layout direction a component is rendered in.
- * Children can use this to adapt their rendering based on the parent layout.
+ * Which state a form treats as its default, so only the *exception* carries a
+ * visible optional/required indicator.
+ *
+ * - `'optional'` — fields are optional unless a field opts into `isRequired`;
+ *   only required fields show an indicator.
+ * - `'required'` — fields are required unless a field opts into `isOptional`;
+ *   only optional fields show an indicator.
+ */
+export type FormOptionality = 'optional' | 'required';
+
+/**
+ * Context for detecting which form layout a component is rendered in. Children
+ * can use this to adapt their rendering based on the parent layout — direction
+ * for spatial arrangement, and `defaultOptionality` so a field can suppress the
+ * indicator that merely restates the form-wide default.
  */
 export const FormLayoutContext = createContext<{
   direction: FormLayoutDirection;
+  defaultOptionality?: FormOptionality;
 }>({direction: 'vertical'});
 FormLayoutContext.displayName = 'FormLayoutContext';

package/src/FormLayout/index.ts

@@ -13,5 +13,5 @@
 
 export {FormLayout} from './FormLayout';
 export type {FormLayoutProps} from './FormLayout';
-export type {FormLayoutDirection} from './FormLayoutContext';
+export type {FormLayoutDirection, FormOptionality} from './FormLayoutContext';
 export {FormLayoutContext} from './FormLayoutContext';

package/src/Lightbox/Lightbox.test.tsx

@@ -4,6 +4,7 @@ import {describe, it, expect, vi, beforeEach, afterEach} from 'vitest';
 import {render, screen, fireEvent, waitFor} from '@testing-library/react';
 import {Lightbox} from './Lightbox';
 import {__resetLiveRegionsForTest} from '../hooks/useAnnounce';
+import {InternationalizationProvider} from '../i18n';
 
 // Mock showModal/close for jsdom
 beforeEach(() => {
@@ -27,6 +28,17 @@ function politeRegion(): HTMLElement | null {
   return document.querySelector('[data-astryx-live-region="polite"]');
 }
 
+// Both position messages, supplied by the test. Overriding the pair means an
+// assertion also proves which of the two keys the component reached for.
+const POSITION_MESSAGES = {
+  fr: {
+    '@astryx.lightbox.mediaPosition':
+      '{alt}, vue {index, number} sur {total, number}',
+    '@astryx.lightbox.imagePosition':
+      'Photo {index, number} sur {total, number}',
+  },
+};
+
 describe('Lightbox', () => {
   it('renders as a dialog element', () => {
     render(
@@ -320,47 +332,53 @@ describe('Lightbox', () => {
 
     it('announces the new image and position when navigating next via button', async () => {
       render(
-        <Lightbox
-          isOpen={true}
-          onOpenChange={() => {}}
-          media={media}
-          defaultIndex={0}
-        />,
+        <InternationalizationProvider locale="fr" overrides={POSITION_MESSAGES}>
+          <Lightbox
+            isOpen={true}
+            onOpenChange={() => {}}
+            media={media}
+            defaultIndex={0}
+          />
+        </InternationalizationProvider>,
       );
       fireEvent.click(screen.getByLabelText('Next'));
       await waitFor(() => {
-        expect(politeRegion()).toHaveTextContent('Image B, 2 of 3');
+        expect(politeRegion()?.textContent).toBe('Image B, vue 2 sur 3');
       });
     });
 
     it('announces the new image and position when navigating via arrow keys', async () => {
       render(
-        <Lightbox
-          isOpen={true}
-          onOpenChange={() => {}}
-          media={media}
-          defaultIndex={1}
-        />,
+        <InternationalizationProvider locale="fr" overrides={POSITION_MESSAGES}>
+          <Lightbox
+            isOpen={true}
+            onOpenChange={() => {}}
+            media={media}
+            defaultIndex={1}
+          />
+        </InternationalizationProvider>,
       );
       const dialog = document.querySelector('dialog')!;
       fireEvent.keyDown(dialog, {key: 'ArrowRight'});
       await waitFor(() => {
-        expect(politeRegion()).toHaveTextContent('Image C, 3 of 3');
+        expect(politeRegion()?.textContent).toBe('Image C, vue 3 sur 3');
       });
     });
 
     it('announces the new image and position when navigating prev', async () => {
       render(
-        <Lightbox
-          isOpen={true}
-          onOpenChange={() => {}}
-          media={media}
-          defaultIndex={2}
-        />,
+        <InternationalizationProvider locale="fr" overrides={POSITION_MESSAGES}>
+          <Lightbox
+            isOpen={true}
+            onOpenChange={() => {}}
+            media={media}
+            defaultIndex={2}
+          />
+        </InternationalizationProvider>,
       );
       fireEvent.click(screen.getByLabelText('Previous'));
       await waitFor(() => {
-        expect(politeRegion()).toHaveTextContent('Image B, 2 of 3');
+        expect(politeRegion()?.textContent).toBe('Image B, vue 2 sur 3');
       });
     });
 
@@ -370,16 +388,19 @@ describe('Lightbox', () => {
         {src: '/b.jpg', alt: ''},
       ];
       render(
-        <Lightbox
-          isOpen={true}
-          onOpenChange={() => {}}
-          media={unlabeled}
-          defaultIndex={0}
-        />,
+        <InternationalizationProvider locale="fr" overrides={POSITION_MESSAGES}>
+          <Lightbox
+            isOpen={true}
+            onOpenChange={() => {}}
+            media={unlabeled}
+            defaultIndex={0}
+          />
+        </InternationalizationProvider>,
       );
       fireEvent.click(screen.getByLabelText('Next'));
       await waitFor(() => {
-        expect(politeRegion()).toHaveTextContent('Image 2 of 2');
+        // imagePosition, not a mediaPosition with an empty {alt}.
+        expect(politeRegion()?.textContent).toBe('Photo 2 sur 2');
       });
     });
 

package/src/Lightbox/Lightbox.tsx

@@ -378,9 +378,13 @@ export function Lightbox({
       return;
     }
     const item = mediaArray[Math.min(index, mediaArray.length - 1)];
-    const position = `${index + 1} of ${mediaArray.length}`;
-    announce(item?.alt ? `${item.alt}, ${position}` : `Image ${position}`);
-  }, [index, isOpen, announce, mediaArray]);
+    const position = {index: index + 1, total: mediaArray.length};
+    announce(
+      item?.alt
+        ? t('@astryx.lightbox.mediaPosition', {alt: item.alt, ...position})
+        : t('@astryx.lightbox.imagePosition', position),
+    );
+  }, [index, isOpen, announce, mediaArray, t]);
 
   // Open/close dialog
   useIsomorphicLayoutEffect(() => {