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

package/src/Stack/Stack.test.tsx

@@ -13,6 +13,22 @@ import {describe, it, expect, vi} from 'vitest';
 import {render, screen} from '@testing-library/react';
 import {Stack} from './Stack';
 
+/**
+ * The functional class output, as an order-insensitive set. StyleX's dev
+ * runtime also emits readable debug classes naming the style object a
+ * declaration came from ("padding__paddingBlockStyles.2"); those record
+ * provenance rather than applied CSS and survive even when the declaration
+ * they name loses a merge, so they are dropped here.
+ */
+function classSet(el: HTMLElement): Set<string> {
+  return new Set(
+    el.className
+      .split(' ')
+      .filter(Boolean)
+      .filter(c => !c.includes('__') && !c.includes('.')),
+  );
+}
+
 describe('Stack', () => {
   it('defaults to vertical direction', () => {
     render(
@@ -314,4 +330,144 @@ describe('Stack', () => {
     const withScroll = screen.getByTestId('stack').className;
     expect(withScroll).not.toBe(withoutScroll);
   });
+
+  it('applies a class when paddingBlockStart is set on its own', () => {
+    const {rerender} = render(
+      <Stack data-testid="stack">
+        <div>Content</div>
+      </Stack>,
+    );
+    const baseline = screen.getByTestId('stack').className;
+    rerender(
+      <Stack paddingBlockStart={2} data-testid="stack">
+        <div>Content</div>
+      </Stack>,
+    );
+    expect(screen.getByTestId('stack').className).not.toBe(baseline);
+  });
+
+  it('lets paddingBlockStart/paddingBlockEnd override only their own edge', () => {
+    const {rerender} = render(
+      <Stack padding={4} paddingBlockStart={2} data-testid="stack">
+        <div>Content</div>
+      </Stack>,
+    );
+    const perEdge = classSet(screen.getByTestId('stack'));
+    rerender(
+      <Stack
+        paddingInline={4}
+        paddingBlockStart={2}
+        paddingBlockEnd={4}
+        data-testid="stack">
+        <div>Content</div>
+      </Stack>,
+    );
+    expect(perEdge).toEqual(classSet(screen.getByTestId('stack')));
+  });
+
+  it('gives paddingBlockEnd precedence over paddingBlock', () => {
+    const {rerender} = render(
+      <Stack paddingBlock={6} paddingBlockEnd={0} data-testid="stack">
+        <div>Content</div>
+      </Stack>,
+    );
+    const overridden = classSet(screen.getByTestId('stack'));
+    rerender(
+      <Stack paddingBlockStart={6} paddingBlockEnd={0} data-testid="stack">
+        <div>Content</div>
+      </Stack>,
+    );
+    expect(overridden).toEqual(classSet(screen.getByTestId('stack')));
+  });
+
+  it('leaves padding/paddingBlock output unchanged when no edge prop is set', () => {
+    const {rerender} = render(
+      <Stack padding={3} data-testid="stack">
+        <div>Content</div>
+      </Stack>,
+    );
+    const uniform = classSet(screen.getByTestId('stack'));
+    rerender(
+      <Stack paddingInline={3} paddingBlock={3} data-testid="stack">
+        <div>Content</div>
+      </Stack>,
+    );
+    expect(uniform).toEqual(classSet(screen.getByTestId('stack')));
+  });
+
+  it('applies a class when paddingInlineStart is set on its own', () => {
+    const {rerender} = render(
+      <Stack data-testid="stack">
+        <div>Content</div>
+      </Stack>,
+    );
+    const baseline = screen.getByTestId('stack').className;
+    rerender(
+      <Stack paddingInlineStart={2} data-testid="stack">
+        <div>Content</div>
+      </Stack>,
+    );
+    expect(screen.getByTestId('stack').className).not.toBe(baseline);
+  });
+
+  it('lets paddingInlineStart/paddingInlineEnd override only their own edge', () => {
+    const {rerender} = render(
+      <Stack padding={4} paddingInlineStart={2} data-testid="stack">
+        <div>Content</div>
+      </Stack>,
+    );
+    const perEdge = classSet(screen.getByTestId('stack'));
+    rerender(
+      <Stack
+        paddingInlineStart={2}
+        paddingInlineEnd={4}
+        paddingBlock={4}
+        data-testid="stack">
+        <div>Content</div>
+      </Stack>,
+    );
+    expect(perEdge).toEqual(classSet(screen.getByTestId('stack')));
+  });
+
+  it('gives paddingInlineEnd precedence over paddingInline', () => {
+    const {rerender} = render(
+      <Stack paddingInline={6} paddingInlineEnd={0} data-testid="stack">
+        <div>Content</div>
+      </Stack>,
+    );
+    const overridden = classSet(screen.getByTestId('stack'));
+    rerender(
+      <Stack paddingInlineStart={6} paddingInlineEnd={0} data-testid="stack">
+        <div>Content</div>
+      </Stack>,
+    );
+    expect(overridden).toEqual(classSet(screen.getByTestId('stack')));
+  });
+
+  it('resolves all four edges independently', () => {
+    // One prop per edge, each a different step: the four-edge spelling and the
+    // shorthand-plus-overrides spelling must agree.
+    const {rerender} = render(
+      <Stack
+        paddingInlineStart={1}
+        paddingInlineEnd={2}
+        paddingBlockStart={3}
+        paddingBlockEnd={4}
+        data-testid="stack">
+        <div>Content</div>
+      </Stack>,
+    );
+    const explicit = classSet(screen.getByTestId('stack'));
+    rerender(
+      <Stack
+        padding={4}
+        paddingInlineStart={1}
+        paddingInlineEnd={2}
+        paddingBlockStart={3}
+        data-testid="stack">
+        <div>Content</div>
+      </Stack>,
+    );
+    expect(explicit).toEqual(classSet(screen.getByTestId('stack')));
+  });
 });

package/src/Stack/Stack.tsx

@@ -25,8 +25,10 @@ import {
 } from './stack.stylex';
 import type {SizeValue} from '../utils/types';
 import {
-  paddingInlineStyles,
-  paddingBlockStyles,
+  paddingInlineStartStyles,
+  paddingInlineEndStyles,
+  paddingBlockStartStyles,
+  paddingBlockEndStyles,
 } from '../Layout/padding.stylex';
 import {mergeProps} from '../utils';
 import {themeProps} from '../utils/themeProps';
@@ -140,12 +142,38 @@ export interface StackProps extends BaseProps<HTMLElement> {
    */
   paddingInline?: SpacingStep;
 
+  /**
+   * Inline-start padding, using the spacing scale. Logical: the left edge in
+   * LTR, the right edge in RTL.
+   * Overrides `paddingInline` and `padding` on that edge only.
+   */
+  paddingInlineStart?: SpacingStep;
+
+  /**
+   * Inline-end padding, using the spacing scale. Logical: the right edge in
+   * LTR, the left edge in RTL.
+   * Overrides `paddingInline` and `padding` on that edge only.
+   */
+  paddingInlineEnd?: SpacingStep;
+
   /**
    * Block (vertical) padding, using the spacing scale.
    * Overrides `padding` on the block axis when both are set.
    */
   paddingBlock?: SpacingStep;
 
+  /**
+   * Block-start (top) padding, using the spacing scale.
+   * Overrides `paddingBlock` and `padding` on that edge only.
+   */
+  paddingBlockStart?: SpacingStep;
+
+  /**
+   * Block-end (bottom) padding, using the spacing scale.
+   * Overrides `paddingBlock` and `padding` on that edge only.
+   */
+  paddingBlockEnd?: SpacingStep;
+
   /**
    * Enables scrollable overflow (`overflow: auto`) for the stack.
    *
@@ -211,7 +239,11 @@ export function Stack({
   gap,
   padding,
   paddingInline,
+  paddingInlineStart,
+  paddingInlineEnd,
   paddingBlock,
+  paddingBlockStart,
+  paddingBlockEnd,
   isScrollable,
   width,
   height,
@@ -242,10 +274,14 @@ export function Stack({
       ? (resolvedVAlign as StackCrossAlignment | undefined)
       : (resolvedHAlign as StackCrossAlignment | undefined);
 
-  // Resolve padding to per-axis values: `padding` sets both axes; `paddingInline`
-  // / `paddingBlock` take precedence on their own axis when provided.
-  const resolvedPaddingInline = paddingInline ?? padding;
-  const resolvedPaddingBlock = paddingBlock ?? padding;
+  // Resolve padding to per-edge values. Most specific wins, per edge:
+  // edge prop -> axis prop -> `padding`.
+  const resolvedPaddingInlineStart =
+    paddingInlineStart ?? paddingInline ?? padding;
+  const resolvedPaddingInlineEnd = paddingInlineEnd ?? paddingInline ?? padding;
+  const resolvedPaddingBlockStart =
+    paddingBlockStart ?? paddingBlock ?? padding;
+  const resolvedPaddingBlockEnd = paddingBlockEnd ?? paddingBlock ?? padding;
 
   const stylexProps = stylex.props(
     ...stack({
@@ -255,8 +291,14 @@ export function Stack({
       gap,
       wrap,
     }),
-    resolvedPaddingInline != null && paddingInlineStyles[resolvedPaddingInline],
-    resolvedPaddingBlock != null && paddingBlockStyles[resolvedPaddingBlock],
+    resolvedPaddingInlineStart != null &&
+      paddingInlineStartStyles[resolvedPaddingInlineStart],
+    resolvedPaddingInlineEnd != null &&
+      paddingInlineEndStyles[resolvedPaddingInlineEnd],
+    resolvedPaddingBlockStart != null &&
+      paddingBlockStartStyles[resolvedPaddingBlockStart],
+    resolvedPaddingBlockEnd != null &&
+      paddingBlockEndStyles[resolvedPaddingBlockEnd],
     isScrollable && overflowStyles.scrollable,
     xstyle,
   );

package/src/StatusDot/StatusDot.doc.mjs

@@ -33,6 +33,12 @@ export const docs = {
       description:
         'Tooltip text shown on hover to explain the status meaning.',
     },
+    {
+      name: 'icon',
+      type: 'ReactNode',
+      description:
+        'Optional icon rendered centered inside the dot, painted in currentColor (the variant\'s ink). Gives the status a non-color mark, so use a different icon per status. Booleans and empty strings are ignored, so `cond && <Icon />` is safe. Same contract as AvatarStatusDot.',
+    },
     {
       name: 'xstyle',
       type: 'StyleXStyles',
@@ -84,6 +90,12 @@ export const docsZh = {
         '启用脉冲动画；尊重 prefers-reduced-motion: reduce 设置。',
       default: 'false',
     },
+    {
+      name: 'icon',
+      type: 'ReactNode',
+      description:
+        '可选图标，居中渲染于圆点内，以 currentColor（变体的前景色）着色。为状态提供非颜色标记，请为每个状态使用不同图标。布尔值和空字符串会被忽略，因此 `cond && <Icon />` 是安全的。与 AvatarStatusDot 的契约一致。',
+    },
     {
       name: 'xstyle',
       type: 'StyleXStyles',
@@ -132,6 +144,7 @@ export const docsDense = {
     label: 'Accessible label via aria-label.',
     isPulsing: 'Pulse animation; respects prefers-reduced-motion: reduce.',
     tooltip: 'Tooltip text on hover to explain status meaning.',
+    icon: 'Optional ReactNode rendered centered in the dot (currentColor ink); a non-color mark for the status, use a different icon per status. Booleans/empty strings ignored (safe for cond && <Icon/>). Same contract as AvatarStatusDot.',
     xstyle: 'StyleX layout styles; must be stylex.create() value.',
   },
 };

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;