@astryxdesign/core 0.4.4 → 0.4.5-canary.1dc3e5d

package/src/StatusDot/StatusDot.test.tsx

@@ -2,8 +2,16 @@
 
 import {describe, it, expect} from 'vitest';
 import {render, screen} from '@testing-library/react';
+import * as stylex from '@stylexjs/stylex';
+import {colorVars} from '../theme/tokens.stylex';
 import {StatusDot} from './StatusDot';
 
+/** Renders a StatusDot and returns its root element. */
+function renderDot(props: React.ComponentProps<typeof StatusDot>) {
+  render(<StatusDot {...props} />);
+  return screen.getByRole('img', {name: props.label});
+}
+
 describe('StatusDot', () => {
   it('renders with role="img" and aria-label', () => {
     render(<StatusDot variant="success" label="Online" />);
@@ -27,9 +35,7 @@ describe('StatusDot', () => {
     ] as const;
 
     for (const variant of variants) {
-      const {unmount} = render(
-        <StatusDot variant={variant} label={variant} />,
-      );
+      const {unmount} = render(<StatusDot variant={variant} label={variant} />);
       expect(screen.getByRole('img', {name: variant})).toBeInTheDocument();
       unmount();
     }
@@ -49,11 +55,7 @@ describe('StatusDot', () => {
 
   it('supports data-testid', () => {
     render(
-      <StatusDot
-        variant="success"
-        label="Online"
-        data-testid="status-dot"
-      />,
+      <StatusDot variant="success" label="Online" data-testid="status-dot" />,
     );
     expect(screen.getByTestId('status-dot')).toBeInTheDocument();
   });
@@ -81,4 +83,109 @@ describe('StatusDot', () => {
     const dot = screen.getByRole('img', {name: 'Online'});
     expect(dot).toBeInTheDocument();
   });
+
+  it('renders every variant as a plain childless dot by default (design review #4373)', () => {
+    // The dot is deliberately a colour-only signal by default — no built-in
+    // per-variant glyph. Making the status accessible in context (label,
+    // icon, or an accessible alternative) is the builder's responsibility;
+    // see the usage guidance.
+    const variants = [
+      'success',
+      'warning',
+      'error',
+      'accent',
+      'neutral',
+    ] as const;
+    for (const variant of variants) {
+      const dot = renderDot({variant, label: `plain-${variant}`});
+      expect(dot.childElementCount, variant).toBe(0);
+    }
+  });
+
+  describe('custom icon (parity with AvatarStatusDot)', () => {
+    const ICON_TESTID = 'custom-icon';
+    function Icon() {
+      return <svg data-testid={ICON_TESTID} />;
+    }
+
+    it('renders a provided icon inside the dot', () => {
+      renderDot({variant: 'success', label: 'Verified', icon: <Icon />});
+      expect(screen.getByTestId(ICON_TESTID)).toBeInTheDocument();
+    });
+
+    it('hides the icon wrapper from assistive tech (the label carries the status)', () => {
+      renderDot({variant: 'success', label: 'Verified', icon: <Icon />});
+      const iconEl = screen.getByTestId(ICON_TESTID);
+      expect(iconEl.closest('[aria-hidden="true"]')).not.toBeNull();
+    });
+
+    it.each([false, true, null, undefined, ''])(
+      'ignores %s and keeps the plain dot (safe for `cond && <Icon />`)',
+      value => {
+        const dot = renderDot({
+          variant: 'error',
+          label: 'Offline',
+          icon: value,
+        });
+        expect(dot.childElementCount).toBe(0);
+      },
+    );
+
+    it('keeps the accessible name on the dot when an icon renders', () => {
+      const dot = renderDot({
+        variant: 'success',
+        label: 'Verified',
+        icon: <Icon />,
+      });
+      expect(dot).toHaveAttribute('role', 'img');
+      expect(dot).toHaveAttribute('aria-label', 'Verified');
+    });
+  });
+
+  describe('variant ink (a passed icon paints from currentColor)', () => {
+    it('pairs the warning plate with the dedicated dark on-warning ink', () => {
+      // The regression this guards: a light surface ink on the yellow warning
+      // plate lands near 2:1, while `--color-on-warning` is the fixed dark
+      // ink (~9.6:1). An icon inherits the ink via `currentColor`, so the
+      // pairing is what keeps custom icons legible.
+      const probe = stylex.create({
+        warning: {
+          backgroundColor: colorVars['--color-warning'],
+          color: colorVars['--color-on-warning'],
+        },
+      });
+      const dot = renderDot({variant: 'warning', label: 'Degraded'});
+      const atomicClasses = (stylex.props(probe.warning).className ?? '')
+        .split(' ')
+        // Dev mode prepends a per-file `File__style.key` debug class that
+        // legitimately differs between the probe and the component.
+        .filter(cls => !cls.includes('__'));
+      expect(atomicClasses.length).toBeGreaterThan(0);
+      for (const cls of atomicClasses) {
+        expect(dot.className).toContain(cls);
+      }
+    });
+  });
+
+  describe('accessible name (label reaches AT without hover)', () => {
+    it('exposes the status label as the accessible name for every variant, without a tooltip', () => {
+      const variants = [
+        'success',
+        'warning',
+        'error',
+        'accent',
+        'neutral',
+      ] as const;
+      for (const variant of variants) {
+        const {unmount} = render(
+          <StatusDot variant={variant} label={`Status: ${variant}`} />,
+        );
+        const dot = screen.getByRole('img', {name: `Status: ${variant}`});
+        expect(dot).toHaveAttribute('aria-label', `Status: ${variant}`);
+        // The name must not depend on hover or focus.
+        expect(dot.getAttribute('tabindex')).toBeNull();
+        unmount();
+      }
+    });
+  });
 });

package/src/StatusDot/StatusDot.tsx

@@ -16,11 +16,13 @@
  * - /packages/cli/assets/templates/blocks/components/StatusDot/ (showcase blocks)
  */
 
+import type {ReactNode} from 'react';
+
 import * as stylex from '@stylexjs/stylex';
 import {colorVars} from '../theme/tokens.stylex';
 import type {BaseProps} from '../BaseProps';
 import {Tooltip} from '../Tooltip/Tooltip';
-import {mergeProps} from '../utils';
+import {isRenderable, mergeProps} from '../utils';
 import {themeProps} from '../utils/themeProps';
 import type {StatusDotVariantMap} from './index';
 
@@ -33,16 +35,21 @@ const pulseKeyframes = stylex.keyframes({
   '100%': {opacity: 1},
 });
 
+/** Fixed dot size in px. A user-supplied icon is drawn into this same field. */
+const DOT_SIZE = 8;
+
 /**
  * Base styles
  */
 const styles = stylex.create({
   base: {
-    display: 'inline-block',
+    display: 'inline-flex',
+    alignItems: 'center',
+    justifyContent: 'center',
     borderRadius: '50%',
     flexShrink: 0,
-    width: '8px',
-    height: '8px',
+    width: `${DOT_SIZE}px`,
+    height: `${DOT_SIZE}px`,
   },
   pulsing: {
     animationName: pulseKeyframes,
@@ -55,26 +62,49 @@ const styles = stylex.create({
       animationName: 'none',
     },
   },
+  // A user-supplied icon fills the whole 8px field and paints from
+  // `currentColor` (the variant's ink).
+  icon: {
+    display: 'flex',
+    alignItems: 'center',
+    justifyContent: 'center',
+    lineHeight: 0,
+    width: `${DOT_SIZE}px`,
+    height: `${DOT_SIZE}px`,
+  },
 });
 
 /**
- * Variant styles mapping to theme color tokens
+ * Variant styles mapping to theme color tokens.
+ *
+ * Each variant sets both the plate colour and an ink colour: a user-supplied
+ * `icon` paints from `currentColor`, so plate and ink can never drift out of
+ * contrast (same contract as AvatarStatusDot). The ink is each plate's
+ * dedicated `--color-on-*` pairing (the Badge precedent), not the surface
+ * colour: on-warning is a fixed dark ink, which keeps an icon legible on the
+ * yellow plate (~9.6:1) where a light surface ink lands near 2:1. Neutral has
+ * no `--color-on-*` token; its mid-grey plate takes the surface ink.
  */
 const variants = stylex.create({
   success: {
     backgroundColor: colorVars['--color-success'],
+    color: colorVars['--color-on-success'],
   },
   warning: {
     backgroundColor: colorVars['--color-warning'],
+    color: colorVars['--color-on-warning'],
   },
   error: {
     backgroundColor: colorVars['--color-error'],
+    color: colorVars['--color-on-error'],
   },
   accent: {
     backgroundColor: colorVars['--color-accent'],
+    color: colorVars['--color-on-accent'],
   },
   neutral: {
     backgroundColor: colorVars['--color-icon-secondary'],
+    color: colorVars['--color-background-surface'],
   },
 });
 
@@ -92,7 +122,8 @@ export interface StatusDotProps extends BaseProps<HTMLSpanElement> {
    */
   variant: StatusDotVariant;
   /**
-   * Accessible label describing the status. Required for a11y.
+   * Accessible label describing the status. Required for a11y — it is the
+   * dot's `aria-label`, so the status reaches screen readers without hover.
    */
   label: string;
   /**
@@ -106,12 +137,36 @@ export interface StatusDotProps extends BaseProps<HTMLSpanElement> {
    * When omitted, no tooltip is rendered.
    */
   tooltip?: string;
+  /**
+   * Optional icon to render centered inside the dot. Accepts any ReactNode
+   * (typically an SVG icon), painted in the dot's `currentColor` ink. Same
+   * contract as `AvatarStatusDot`'s `icon`.
+   *
+   * By default the dot is a colour-only signal; an icon gives the status a
+   * non-colour mark, so use a different icon per status — the same icon on
+   * every variant leaves the statuses distinguishable by colour alone
+   * (WCAG 2.1 SC 1.4.1). Booleans and empty strings are ignored (safe for
+   * `cond && <Icon />`).
+   *
+   * @example
+   * ```
+   * <StatusDot variant="success" label="Verified" icon={<CheckIcon />} />
+   * ```
+   */
+  icon?: ReactNode;
 }
 
 /**
  * A small colored dot indicator for status display (online/offline, severity, etc).
  *
- * Fixed 8px size. Renders as a non-focusable `<span>` with `role="img"` and
+ * Fixed 8px size. By default the dot conveys status by colour only, which is
+ * not accessible in isolation (WCAG 2.1 SC 1.4.1) — treat it as a signal the
+ * surrounding UI must make accessible: use it as a binary present/absent
+ * signal, pair it with a visible label, pass `icon` so the status carries a
+ * non-colour mark, or convey the status accessibly elsewhere. See the usage
+ * guidance in the component docs.
+ *
+ * Renders as a non-focusable `<span>` with `role="img"` and
  * `aria-label` for accessibility. Styles use Astryx theme tokens via StyleX.
  * Wrap your app in `<Theme>` to apply a theme.
  *
@@ -121,6 +176,7 @@ export interface StatusDotProps extends BaseProps<HTMLSpanElement> {
  * <StatusDot variant="error" label="Offline" />
  * <StatusDot variant="success" label="Live" isPulsing />
  * <StatusDot variant="success" label="Online" tooltip="Online" />
+ * <StatusDot variant="success" label="Verified" icon={<CheckIcon />} />
  * ```
  */
 export function StatusDot({
@@ -128,12 +184,16 @@ export function StatusDot({
   label,
   isPulsing = false,
   tooltip,
+  icon,
   xstyle,
   className,
   style,
   ref,
   ...props
 }: StatusDotProps) {
+  // Booleans and empty renders don't count (safe for `cond && <Icon />`) —
+  // same contract as AvatarStatusDot.
+  const showsIcon = isRenderable(icon);
   const dot = (
     <span
       ref={ref}
@@ -151,8 +211,13 @@ export function StatusDot({
         className,
         style,
       )}
-      {...props}
-    />
+      {...props}>
+      {showsIcon && (
+        <span aria-hidden="true" {...stylex.props(styles.icon)}>
+          {icon}
+        </span>
+      )}
+    </span>
   );
 
   if (tooltip) {

package/src/Switch/Switch.tsx

@@ -47,6 +47,7 @@ import type {BaseProps} from '../BaseProps';
 import type {SizeValue} from '../utils/types';
 import {themeProps} from '../utils/themeProps';
 import {VisuallyHidden} from '../VisuallyHidden';
+import {useResolvedRequired} from '../hooks/useResolvedRequired';
 
 const wrapperSizeStyles = stylex.create({
   sm: {
@@ -503,6 +504,10 @@ export function Switch({
   const id = useId();
   const descriptionID = useId();
   const statusMessageID = useId();
+  // Announce the effective required state (form default included) while the
+  // native `required` stays bound to the explicit `isRequired` so a layout
+  // default never switches on browser validation.
+  const isEffectivelyRequired = useResolvedRequired({isRequired, isOptional});
 
   const [, startTransition] = useTransition();
   const [optimisticValue, setOptimisticValue] = useOptimistic(value);
@@ -559,6 +564,7 @@ export function Switch({
         aria-disabled={showsDisabledMessage ? 'true' : undefined}
         form={showsDisabledMessage ? '' : undefined}
         required={isRequired}
+        aria-required={isEffectivelyRequired ? 'true' : undefined}
         onChange={e => {
           if (isDisabled || isBusy) {
             return;

package/src/Table/plugins/rowExpansion/useTableRowExpansion.tsx

@@ -23,6 +23,7 @@ import {spacingVars, colorVars, radiusVars} from '../../../theme/tokens.stylex';
 import {Icon} from '../../../Icon';
 import {resolveContextActions} from '../../tableContextMenu';
 import {useTranslator} from '../../../i18n';
+import {rtlStyles} from '../../../utils';
 import type {
   TablePlugin,
   TableColumn,
@@ -92,8 +93,20 @@ const expansionStyles = stylex.create({
       color: colorVars['--color-icon-primary'],
     },
   },
+  // The RTL mirror is folded into each state's transform rather than living
+  // on a parent span, matching TreeListItem's chevron (both are `transform`,
+  // so on one element the later value would win).
   chevronExpanded: {
-    transform: 'rotate(90deg)',
+    transform: {
+      default: 'rotate(90deg)',
+      ':is([dir="rtl"] *)': 'scaleX(-1) rotate(90deg)',
+    },
+  },
+  chevronCollapsed: {
+    transform: {
+      default: 'rotate(0deg)',
+      ':is([dir="rtl"] *)': 'scaleX(-1) rotate(0deg)',
+    },
   },
   expandedRow: {
     backgroundColor: colorVars['--color-background-muted'],
@@ -121,7 +134,9 @@ function ExpansionChevron({
       type="button"
       {...stylex.props(
         expansionStyles.chevronButton,
-        isExpanded && expansionStyles.chevronExpanded,
+        isExpanded
+          ? expansionStyles.chevronExpanded
+          : expansionStyles.chevronCollapsed,
       )}
       onClick={e => {
         e.stopPropagation();
@@ -249,6 +264,9 @@ export function useTableRowExpansion<T extends Record<string, unknown>>(
                   icon={isExpanded ? 'chevronDown' : 'chevronRight'}
                   size="xsm"
                   aria-hidden
+                  // chevronDown needs no mirroring; chevronRight (collapsed,
+                  // pointing toward the reveal direction) does.
+                  xstyle={!isExpanded && rtlStyles.mirror}
                 />
               ),
               onSelect: () => onToggle(key),

package/src/TextArea/TextArea.tsx

@@ -52,6 +52,7 @@ import type {SizeValue} from '../utils/types';
 import {useInputContainer} from '../hooks/useInputContainer';
 import {useInputStatusIcon} from '../hooks/useInputStatusIcon';
 import {useAnnounce} from '../hooks/useAnnounce';
+import {useResolvedRequired} from '../hooks/useResolvedRequired';
 import {useSize} from '../SizeContext/SizeContext';
 import {themeProps} from '../utils/themeProps';
 import {characterCount} from '../utils/characters';
@@ -394,6 +395,7 @@ export function TextArea({
 }: TextAreaProps) {
   const size = useSize(sizeProp, 'md');
   const t = useTranslator();
+  const isEffectivelyRequired = useResolvedRequired({isRequired, isOptional});
   const announce = useAnnounce();
   const id = useId();
   const descriptionID = useId();
@@ -598,7 +600,7 @@ export function TextArea({
           autoFocus={hasAutoFocus}
           data-autofocus={hasAutoFocus || undefined}
           aria-describedby={ariaDescribedBy}
-          aria-required={isRequired && !isOptional ? 'true' : undefined}
+          aria-required={isEffectivelyRequired ? 'true' : undefined}
           aria-invalid={
             status?.type === 'error' ||
             (maxLength != null && valueLength > maxLength)

package/src/TextInput/TextInput.tsx

@@ -101,6 +101,7 @@ import {mergeProps, mergeRefs} from '../utils';
 import {useSize} from '../SizeContext/SizeContext';
 import {useInputContainer} from '../hooks/useInputContainer';
 import {useInputStatusIcon} from '../hooks/useInputStatusIcon';
+import {useResolvedRequired} from '../hooks/useResolvedRequired';
 import {useInputGroup} from '../InputGroup/InputGroupContext';
 import type {BaseProps} from '../BaseProps';
 import type {SizeValue} from '../utils/types';
@@ -301,6 +302,7 @@ export function TextInput({
   ...rest
 }: TextInputProps) {
   const t = useTranslator();
+  const isEffectivelyRequired = useResolvedRequired({isRequired, isOptional});
   const size = useSize(sizeProp, 'md');
 
   const id = useId();
@@ -445,7 +447,7 @@ export function TextInput({
         autoFocus={hasAutoFocus}
         data-autofocus={hasAutoFocus || undefined}
         aria-describedby={ariaDescribedBy}
-        aria-required={isRequired === true ? 'true' : undefined}
+        aria-required={isEffectivelyRequired ? 'true' : undefined}
         aria-invalid={status?.type === 'error' ? 'true' : undefined}
         aria-busy={isBusy || undefined}
         aria-labelledby={ariaLabelledBy}

package/src/TimeInput/TimeInput.tsx

@@ -67,6 +67,7 @@ import {useSize} from '../SizeContext/SizeContext';
 import {useAnnounce} from '../hooks/useAnnounce';
 import {useInputContainer} from '../hooks/useInputContainer';
 import {useInputStatusIcon} from '../hooks/useInputStatusIcon';
+import {useResolvedRequired} from '../hooks/useResolvedRequired';
 import {useInputGroup} from '../InputGroup/InputGroupContext';
 import {groupStyles} from '../InputGroup/groupStyles';
 import {useTooltip} from '../Tooltip';
@@ -347,6 +348,7 @@ export function TimeInput({
   ref,
 }: TimeInputProps) {
   const t = useTranslator();
+  const isEffectivelyRequired = useResolvedRequired({isRequired, isOptional});
   const placeholder =
     placeholderFromProps ?? t('@astryx.timeInput.placeholder');
   const size = useSize(sizeProp, 'md');
@@ -664,7 +666,7 @@ export function TimeInput({
         autoFocus={hasAutoFocus}
         data-autofocus={hasAutoFocus || undefined}
         aria-describedby={ariaDescribedBy}
-        aria-required={isRequired === true ? 'true' : undefined}
+        aria-required={isEffectivelyRequired ? 'true' : undefined}
         aria-invalid={
           status?.type === 'error' || !isInputValid ? 'true' : undefined
         }

package/src/hooks/useResolvedRequired.ts

@@ -0,0 +1,42 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file useResolvedRequired.ts
+ * @input Uses React, FormLayoutContext
+ * @output Exports useResolvedRequired
+ * @position Resolves a field's effective aria-required against the form default
+ *
+ * SYNC: When modified, update these files to stay in sync:
+ * - /packages/core/src/FormLayout/FormLayoutContext.ts (defaultOptionality source)
+ * - /packages/core/src/FormLayout/FormLayout.tsx (prop doc: aria-required behavior)
+ */
+
+import {use} from 'react';
+import {FormLayoutContext} from '../FormLayout/FormLayoutContext';
+
+/**
+ * Resolve a field's effective *required* state for `aria-required`, honoring a
+ * surrounding `FormLayout`'s `defaultOptionality`.
+ *
+ * Under `defaultOptionality="required"` a field is required unless it opts out
+ * with `isOptional`. The visible indicator is suppressed for the unmarked
+ * majority, so those fields must still expose `aria-required` — otherwise a
+ * sighted user reads them as required (form-wide default, no indicator) while a
+ * screen reader hears "not required". This closes that mismatch.
+ *
+ * Semantics only: this drives `aria-required`, never the native `required`
+ * attribute, so a layout-level default can't silently switch on browser
+ * validation bubbles. `isOptional` takes precedence, matching `FieldLabel`.
+ */
+export function useResolvedRequired({
+  isRequired = false,
+  isOptional = false,
+}: {
+  isRequired?: boolean;
+  isOptional?: boolean;
+}): boolean {
+  const {defaultOptionality} = use(FormLayoutContext);
+  return !isOptional && (isRequired || defaultOptionality === 'required');
+}

package/src/utils/plainDate.test.ts

@@ -13,6 +13,7 @@ import {
   plainDateDayOfWeek,
   plainDateAddMonths,
   plainDateAddDays,
+  plainDateDiffDays,
   plainDateToInstant,
   plainDateFromInstant,
   plainDateIsBefore,
@@ -312,6 +313,55 @@ describe('plainDateAddDays', () => {
   });
 });
 
+describe('plainDateDiffDays', () => {
+  it('counts whole days forward', () => {
+    expect(
+      plainDateDiffDays(
+        {year: 2026, month: 1, day: 10},
+        {year: 2026, month: 1, day: 17},
+      ),
+    ).toBe(7);
+  });
+
+  it('is negative when the second date is earlier', () => {
+    expect(
+      plainDateDiffDays(
+        {year: 2026, month: 1, day: 10},
+        {year: 2026, month: 1, day: 3},
+      ),
+    ).toBe(-7);
+  });
+
+  it('is zero for the same day', () => {
+    expect(
+      plainDateDiffDays(
+        {year: 2026, month: 6, day: 15},
+        {year: 2026, month: 6, day: 15},
+      ),
+    ).toBe(0);
+  });
+
+  it('counts across month and year boundaries', () => {
+    expect(
+      plainDateDiffDays(
+        {year: 2025, month: 12, day: 30},
+        {year: 2026, month: 1, day: 2},
+      ),
+    ).toBe(3);
+  });
+
+  it('ignores DST — every calendar day counts once across a spring-forward', () => {
+    // US DST 2026 begins Mar 8. The gap Mar 7 → Mar 9 is two calendar days
+    // even though one of them is 23 hours long.
+    expect(
+      plainDateDiffDays(
+        {year: 2026, month: 3, day: 7},
+        {year: 2026, month: 3, day: 9},
+      ),
+    ).toBe(2);
+  });
+});
+
 describe('plainDateToInstant / plainDateFromInstant', () => {
   it('converts a PlainDate to midnight in the requested timezone', () => {
     expect(

package/src/utils/plainDate.ts

@@ -88,6 +88,18 @@ export function plainDateAddDays(pd: PlainDate, n: number): PlainDate {
   return plainDateFromDate(d);
 }
 
+/**
+ * Whole calendar days from `a` to `b`, ignoring time of day. Positive when
+ * `b` is after `a`, negative when before. Uses UTC midnight so DST shifts
+ * never add or drop a day.
+ */
+export function plainDateDiffDays(a: PlainDate, b: PlainDate): number {
+  const msPerDay = 24 * 60 * 60 * 1000;
+  const aUTC = Date.UTC(a.year, a.month - 1, a.day);
+  const bUTC = Date.UTC(b.year, b.month - 1, b.day);
+  return Math.round((bUTC - aUTC) / msPerDay);
+}
+
 /**
  * The wall-clock fields an instant reads as in a given zone.
  *