@astryxdesign/core 0.1.9 → 0.2.0-canary.0f56f82

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.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/Field.tsx

@@ -22,6 +22,7 @@ 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';
@@ -156,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
@@ -239,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.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({
@@ -48,7 +52,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,
@@ -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/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

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

package/src/FieldStatus/FieldStatus.test.tsx

@@ -300,6 +300,139 @@ describe('FieldStatus', () => {
     });
   });
 
+  // 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();
+    });
+  });
+
+  describe('field-status-icon theme target', () => {
+    // The stable theme target lands on the detached message box's leading glyph
+    // itself, so a theme can restyle (e.g. resize) just this icon via
+    // `defineTheme`. It reflects the status type as a data attribute so themes
+    // can target per status, mirroring the parent astryx-field-status.
+    const getStatusIcon = (root: HTMLElement): HTMLElement => {
+      const icon = root.querySelector('.astryx-field-status-icon');
+      if (icon == null) {
+        throw new Error('status icon not found');
+      }
+      return icon as HTMLElement;
+    };
+
+    it('renders the target on the detached leading icon', () => {
+      render(
+        <FieldStatus
+          type="error"
+          message="msg"
+          variant="detached"
+          data-testid="fs"
+        />,
+      );
+      const icon = getStatusIcon(screen.getByTestId('fs'));
+      expect(icon).toHaveClass('astryx-field-status-icon');
+      expect(icon).toHaveClass('astryx-icon');
+      expect(icon).toHaveAttribute('data-type', 'error');
+    });
+
+    it('reflects the status type per status', () => {
+      for (const type of ['error', 'warning', 'success'] as const) {
+        const {unmount} = render(
+          <FieldStatus
+            type={type}
+            message="msg"
+            variant="detached"
+            data-testid="fs"
+          />,
+        );
+        expect(getStatusIcon(screen.getByTestId('fs'))).toHaveAttribute(
+          'data-type',
+          type,
+        );
+        unmount();
+      }
+    });
+
+    it('does not render the target for the attached variant', () => {
+      render(
+        <FieldStatus
+          type="error"
+          message="msg"
+          variant="attached"
+          data-testid="fs"
+        />,
+      );
+      expect(
+        screen.getByTestId('fs').querySelector('.astryx-field-status-icon'),
+      ).toBeNull();
+    });
+  });
+
   describe('edge cases', () => {
     it('renders an empty message without crashing', () => {
       render(<FieldStatus type="error" message="" data-testid="fs" />);

package/src/FieldStatus/FieldStatus.tsx

@@ -2,7 +2,7 @@
 
 /**
  * @file FieldStatus.tsx
- * @input Uses React, stylex, theme tokens, useAnnounce
+ * @input Uses React, stylex, theme tokens, useAnnounce, Icon
  * @output Exports FieldStatus component, FieldStatusProps
  * @position Core implementation; consumed by Field, Switch, CheckboxInput, and the FieldStatus entrypoint
  *
@@ -31,6 +31,19 @@ import {
 import type {InputStatusType} from '../Field/types';
 import {useEntryAnimation} from '../hooks/useEntryAnimation';
 import {themeProps} from '../utils/themeProps';
+import {Icon} from '../Icon';
+import type {IconName} from '../Icon';
+
+/**
+ * Maps each status type to its status glyph. Mirrors the mapping the input
+ * controls already use for the on-field status affordance, so the detached
+ * message shows the same icon a consumer sees elsewhere for that status.
+ */
+const statusIconMap: Record<InputStatusType, IconName> = {
+  warning: 'warning',
+  error: 'error',
+  success: 'success',
+};
 
 const styles = stylex.create({
   base: {
@@ -43,8 +56,8 @@ const styles = stylex.create({
     paddingBlockStart: `calc(${spacingVars['--spacing-1-5']} + ${spacingVars['--spacing-2']})`,
     paddingBlockEnd: spacingVars['--spacing-2'],
     paddingInline: spacingVars['--spacing-2'],
-    borderBottomLeftRadius: radiusVars['--radius-element'],
-    borderBottomRightRadius: radiusVars['--radius-element'],
+    borderEndStartRadius: radiusVars['--radius-element'],
+    borderEndEndRadius: radiusVars['--radius-element'],
   },
   detached: {
     marginTop: spacingVars['--spacing-1'],
@@ -52,6 +65,20 @@ const styles = stylex.create({
     paddingInline: spacingVars['--spacing-2'],
     borderRadius: radiusVars['--radius-element'],
   },
+  detachedContent: {
+    display: 'flex',
+    alignItems: 'flex-start',
+    gap: spacingVars['--spacing-1'],
+  },
+  detachedIcon: {
+    // Center the glyph within the first text-line box so it aligns to the
+    // first line of the message (rather than the top of the flex row) when the
+    // message wraps to multiple lines.
+    display: 'inline-flex',
+    alignItems: 'center',
+    height: `calc(${typeScaleVars['--text-supporting-size']} * ${typeScaleVars['--text-supporting-leading']})`,
+    flexShrink: 0,
+  },
 });
 
 const colorStyles = stylex.create({
@@ -85,6 +112,7 @@ const colorStyles = stylex.create({
 export interface FieldStatusVariantMap {
   attached: true;
   detached: true;
+  tooltip: true;
 }
 
 /**
@@ -114,6 +142,15 @@ export interface FieldStatusProps extends BaseProps<HTMLDivElement> {
 /**
  * A status message component for form fields.
  *
+ * The `detached` variant renders a leading status icon before the message so
+ * status is not conveyed by color or position alone (WCAG 1.4.1). The icon is
+ * decorative for assistive tech (`aria-hidden`): the message text already names
+ * the status in words and is announced through the live region. The `attached`
+ * variant keeps its status affordance on the bordered input, so it renders no
+ * icon here to avoid a duplicate. The `tooltip` variant renders no message box
+ * at all — the input surfaces the status through a tooltip on its on-field
+ * icon — so callers skip rendering FieldStatus for it.
+ *
  * Screen-reader announcements go through the persistent `useAnnounce` live
  * regions (assertive for errors, polite otherwise) rather than `role`/
  * `aria-live` on the rendered element. Live regions that mount together with
@@ -176,7 +213,27 @@ export function FieldStatus({
         className,
         style,
       )}>
-      {message}
+      {variant === 'detached' ? (
+        <span {...stylex.props(styles.detachedContent)}>
+          <span {...stylex.props(styles.detachedIcon)}>
+            <Icon
+              icon={statusIconMap[type]}
+              size="sm"
+              color="inherit"
+              // Stable theme target on the detached message box's leading glyph
+              // itself, so a theme can restyle just this icon (color, size) —
+              // and each status — via `defineTheme`. Same-element rules in
+              // @layer astryx-theme win over the icon's own base
+              // width/height/fontSize, which a field-level target could not
+              // reach.
+              {...themeProps('field-status-icon', {type})}
+            />
+          </span>
+          <span>{message}</span>
+        </span>
+      ) : (
+        message
+      )}
     </div>
   );
 }

package/src/FileInput/FileInput.doc.mjs

@@ -78,7 +78,7 @@ export const docs = {
       name: 'isRequired',
       type: 'boolean',
       description:
-        'Displays a "Required" indicator next to the label and sets aria-required. Mutually exclusive with isOptional.',
+        'Displays a "Required" indicator next to the label and adds a screen-reader-only "Required" description to the trigger (assistive tech does not reliably announce aria-required on the trigger). Mutually exclusive with isOptional.',
       default: 'false',
     },
     {
@@ -119,12 +119,25 @@ export const docs = {
       description:
         'Validation status: applies a colored border. If message is provided, displays a floating message below the input. Error type also sets aria-invalid.',
     },
+    {
+      name: 'statusVariant',
+      type: "'attached' | 'detached' | 'tooltip'",
+      description:
+        'How the status message is placed relative to the input. attached overlaps directly below the input (bordered treatment); detached floats below as a separate element with spacing; tooltip hides the message box and surfaces it in a tooltip on the status icon.',
+      default: "'attached'",
+    },
     {
       name: 'labelTooltip',
       type: 'string',
       description:
         'Tooltip text displayed in an info icon at the end of the label.',
     },
+    {
+      name: 'width',
+      type: 'SizeValue',
+      description:
+        'Width of the field (number = pixels, string used as-is, e.g. "100%"). Sizes the whole field (label, control, and status) so they stay aligned.',
+    },
   ],
   theming: {
     targets: [
@@ -246,6 +259,13 @@ export const docsZh = {
       type: "{type: 'error' | 'warning' | 'success', message?: string}",
       description: '验证状态。',
     },
+    {
+      name: 'statusVariant',
+      type: "'attached' | 'detached' | 'tooltip'",
+      description:
+        '状态消息相对于输入框的放置方式。attached 直接叠加在输入框下方（带边框处理）；detached 作为独立元素浮于下方并留有间距；tooltip 隐藏消息框，并在状态图标上以提示气泡形式显示。',
+      default: "'attached'",
+    },
   ],
   theming: {
     targets: [
@@ -308,7 +328,7 @@ export const docsDense = {
     isLabelHidden: 'Visually hides label; keeps screen reader access.',
     description: 'Description text between label+input.',
     isOptional: 'Shows "Optional" indicator.',
-    isRequired: 'Shows "Required" indicator+sets aria-required.',
+    isRequired: 'Shows "Required" indicator+SR-only trigger description.',
     isDisabled: 'Disables input, prevents interaction.',
     disabledMessage:
       'Explains why input is disabled. With isDisabled, shows tooltip on hover/focus + keeps trigger focusable via aria-disabled (opening picker stays blocked). Use instead of wrapping a disabled FileInput in Tooltip.',
@@ -316,6 +336,7 @@ export const docsDense = {
     placeholder: 'Placeholder when no files selected.',
     mode: "Visual mode: 'input' (compact) or 'dropzone' (drag-and-drop).",
     status: 'Validation status; colored border. Message floats below.',
+    statusVariant: 'How status message is placed: attached overlaps below input; detached floats below w/ spacing; tooltip hides the box and shows it on the status icon.',
     labelTooltip: 'Tooltip in info icon at label end.',
   },
 };