@astryxdesign/core 0.3.0 → 0.4.0

package/src/Indicator/Indicator.test.tsx

@@ -0,0 +1,393 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {describe, expect, it} from 'vitest';
+import {render, renderHook, screen} from '@testing-library/react';
+import type {PropsWithChildren, ReactNode} from 'react';
+import {Theme} from '../theme/Theme';
+import {defineTheme} from '../theme/defineTheme';
+import {CheckboxIndicator} from './CheckboxIndicator';
+import {CheckIndicator} from './CheckIndicator';
+import {RadioIndicator} from './RadioIndicator';
+import {getIndicator} from './indicatorRegistry';
+import {useIndicator} from './useIndicator';
+import type {IndicatorProps} from './types';
+
+function createThemeWrapper(theme: ReturnType<typeof defineTheme>) {
+  function ThemeWrapper({children}: PropsWithChildren): ReactNode {
+    return <Theme theme={theme}>{children}</Theme>;
+  }
+  return ThemeWrapper;
+}
+
+describe('default indicators', () => {
+  it('renders the checkbox theme target with state and size', () => {
+    render(<CheckboxIndicator state="indeterminate" size="sm" />);
+
+    const box = document.querySelector('.astryx-checkbox');
+    expect(box).toBeInTheDocument();
+    expect(box).toHaveAttribute('data-checked', 'indeterminate');
+    expect(box).toHaveAttribute('data-size', 'sm');
+    // Decorative: the owning control keeps the role and accessible name.
+    expect(box).toHaveAttribute('aria-hidden', 'true');
+  });
+
+  it('renders the radio dot only when checked, in both states', () => {
+    const {rerender} = render(<RadioIndicator state="unchecked" />);
+
+    // The circle draws in the unchecked state — this is what lets a radio act
+    // as a selection indicator where an icon would render nothing.
+    expect(document.querySelector('.astryx-radio')).toBeInTheDocument();
+    expect(document.querySelector('.astryx-radio-dot')).not.toBeInTheDocument();
+
+    rerender(<RadioIndicator state="checked" />);
+    expect(document.querySelector('.astryx-radio-dot')).toBeInTheDocument();
+    expect(document.querySelector('.astryx-radio')).toHaveAttribute(
+      'data-checked',
+      'checked',
+    );
+  });
+
+  it('renders children instead of the state mark', () => {
+    render(
+      <CheckboxIndicator state="checked">
+        <span data-testid="busy" />
+      </CheckboxIndicator>,
+    );
+
+    expect(screen.getByTestId('busy')).toBeInTheDocument();
+  });
+
+  it('reflects the disabled state for theme targeting', () => {
+    render(<RadioIndicator state="checked" isDisabled />);
+
+    expect(document.querySelector('.astryx-radio')).toHaveAttribute(
+      'data-disabled',
+      'disabled',
+    );
+  });
+});
+
+/**
+ * CheckIndicator is the one indicator that draws nothing in a state, which is
+ * what makes it the default selection mark — and what made its two escape
+ * hatches (props and children) easy to get wrong. Both are pinned here.
+ */
+describe('CheckIndicator', () => {
+  it('draws the mark when checked and nothing when not', () => {
+    const {container, rerender} = render(<CheckIndicator state="checked" />);
+
+    const mark = container.querySelector('.astryx-icon');
+    expect(mark).toBeInTheDocument();
+    expect(mark).toHaveAttribute('aria-hidden', 'true');
+
+    rerender(<CheckIndicator state="unchecked" />);
+    // No empty box beside an unchosen row — the reason a check is the default.
+    expect(container).toBeEmptyDOMElement();
+  });
+
+  it('renders children INSTEAD of the mark, in both states', () => {
+    // A host shows a pending Spinner through `children` in whatever state the
+    // row is in, and an unchosen row is the common one. The unchecked case
+    // used to render nothing at all.
+    for (const state of ['checked', 'unchecked'] as const) {
+      const {unmount} = render(
+        <CheckIndicator state={state}>
+          <span data-testid="busy" />
+        </CheckIndicator>,
+      );
+
+      expect(screen.getByTestId('busy'), `state=${state}`).toBeInTheDocument();
+      // The mark is replaced, not accompanied.
+      expect(document.querySelector('.astryx-icon')).not.toBeInTheDocument();
+      unmount();
+    }
+  });
+
+  it('forwards caller props and styling on both render paths', () => {
+    // Same contract whether or not children are present: a data-testid, an id
+    // and an xstyle-driven class must survive either branch.
+    const {container, rerender} = render(
+      <CheckIndicator state="checked" data-testid="mark" id="pinned" />,
+    );
+
+    expect(screen.getByTestId('mark')).toHaveAttribute('id', 'pinned');
+
+    rerender(
+      <CheckIndicator
+        state="checked"
+        data-testid="mark"
+        id="pinned"
+        className="host-target">
+        <span data-testid="busy" />
+      </CheckIndicator>,
+    );
+
+    const withChildren = screen.getByTestId('mark');
+    expect(withChildren).toHaveAttribute('id', 'pinned');
+    expect(withChildren).toHaveClass('host-target');
+    expect(withChildren).toHaveAttribute('aria-hidden', 'true');
+    expect(container.querySelector('[data-testid="busy"]')).toBeInTheDocument();
+  });
+});
+
+/**
+ * The busy idiom a host actually writes is `children={isBusy && <Spinner/>}`,
+ * which passes `false` when it is not busy. `false` is non-null and is not
+ * caught by `??`, so both a `!= null` guard and a `children ?? mark` fallback
+ * take the children path, render nothing in it, and delete the state mark
+ * (#4893). Every indicator gets the same case, because all three had the bug.
+ */
+describe('falsy children never suppress the state mark (#4893)', () => {
+  const cases = [
+    {
+      name: 'CheckIndicator',
+      render: (children: ReactNode) =>
+        render(<CheckIndicator state="checked">{children}</CheckIndicator>),
+      markSelector: '.astryx-icon',
+    },
+    {
+      name: 'CheckboxIndicator',
+      render: (children: ReactNode) =>
+        render(
+          <CheckboxIndicator state="checked">{children}</CheckboxIndicator>,
+        ),
+      markSelector: 'svg',
+    },
+    {
+      name: 'RadioIndicator',
+      render: (children: ReactNode) =>
+        render(<RadioIndicator state="checked">{children}</RadioIndicator>),
+      markSelector: '.astryx-radio-indicator-dot',
+    },
+  ] as const;
+
+  // Everything React renders as nothing. `0` is deliberately absent: it
+  // renders the visible text "0", so it IS content and must replace the mark.
+  const emptyValues = [
+    ['false — the `isBusy && …` idiom', false],
+    ['null', null],
+    ['undefined', undefined],
+    ['empty string', ''],
+  ] as const;
+
+  for (const {name, render: renderCase, markSelector} of cases) {
+    for (const [label, child] of emptyValues) {
+      it(`${name} keeps its mark when children is ${label}`, () => {
+        const {container} = renderCase(child);
+
+        expect(
+          container.querySelector(markSelector),
+          `${name} lost its mark to a falsy child`,
+        ).toBeInTheDocument();
+      });
+    }
+
+    it(`${name} still lets real children replace the mark`, () => {
+      // The negative control: without this, "always render the mark" would
+      // pass every case above and break the busy state instead.
+      const {container} = renderCase(<span data-testid="busy" />);
+
+      expect(
+        container.querySelector('[data-testid="busy"]'),
+      ).toBeInTheDocument();
+      expect(container.querySelector(markSelector)).not.toBeInTheDocument();
+    });
+  }
+
+  it('treats 0 as content, not as empty', () => {
+    // isRenderable's documented edge: 0 renders the character "0".
+    const {container} = render(
+      <CheckIndicator state="checked">{0}</CheckIndicator>,
+    );
+
+    expect(container.textContent).toBe('0');
+    expect(container.querySelector('.astryx-icon')).not.toBeInTheDocument();
+  });
+});
+
+/**
+ * An indicator is decorative BY CONTRACT: the owning control supplies the role
+ * and the accessible name, so an indicator that is also announced says the same
+ * thing twice (#4918).
+ *
+ * The contract is held in two places, because neither covers the whole thing:
+ *
+ *   - `IndicatorProps` omits the a11y props, which makes `role` a compile
+ *     error. It does NOT make `aria-hidden` one: TypeScript exempts JSX
+ *     attribute names that are not valid JS identifiers from excess-property
+ *     checking, so anything hyphenated slips through. That is a language rule,
+ *     not a gap in our types — the second test below is the proof, and it will
+ *     start failing the day TS changes its mind, which is when we can drop the
+ *     ordering.
+ *   - So each component emits its own `aria-hidden` AFTER `{...rest}`, which is
+ *     what actually keeps a caller from un-hiding it. Nothing is stripped.
+ */
+describe('the decorative contract (#4918)', () => {
+  it('rejects `role` and `tabIndex` at compile time', () => {
+    // Both are valid JS identifiers, so excess-property checking applies and
+    // the type alone is enough — no runtime guard needed. `tabIndex` matters
+    // because the element is unconditionally aria-hidden: a tab stop on it is
+    // a focusable node in a hidden subtree (axe `aria-hidden-focus`).
+    const rejected = [
+      // @ts-expect-error — the owning control holds the role.
+      <CheckIndicator key="a" state="checked" role="checkbox" />,
+      // @ts-expect-error — the owning control holds the focus.
+      <CheckboxIndicator key="b" state="checked" tabIndex={0} />,
+    ];
+
+    expect(rejected).toHaveLength(2);
+  });
+
+  it('cannot reject a hyphenated a11y attribute — TS exempts those', () => {
+    // NO @ts-expect-error here, deliberately: this compiles, and the comment
+    // above explains why. Runtime order is what makes it harmless.
+    const accepted = <CheckIndicator state="checked" aria-label="inert" />;
+
+    expect(accepted).toBeTruthy();
+  });
+
+  it('cannot reject a SPREAD either — which is the ordinary host idiom', () => {
+    // Also no @ts-expect-error, also deliberate. A spread bypasses
+    // excess-property checking for every member, so even `role` and `tabIndex`
+    // — the two the type catches as literals — get through this way.
+    //
+    // Left alone on purpose. Nothing in the repo spreads a hostile object at an
+    // indicator, `aria-hidden` is settled by attribute order regardless, and a
+    // forwarded `role`/`aria-label` is inert inside a hidden subtree. Guarding
+    // it at runtime would cost a module to defend a case no call site reaches.
+    const hostile = {role: 'checkbox', tabIndex: 0};
+    const accepted = <CheckIndicator state="checked" {...hostile} />;
+
+    expect(accepted).toBeTruthy();
+  });
+
+  const cases = [
+    {
+      name: 'CheckIndicator (glyph path)',
+      render: (p: Record<string, unknown>) => (
+        <CheckIndicator state="checked" {...p} />
+      ),
+    },
+    {
+      name: 'CheckIndicator (children path)',
+      render: (p: Record<string, unknown>) => (
+        <CheckIndicator state="checked" {...p}>
+          <b />
+        </CheckIndicator>
+      ),
+    },
+    {
+      name: 'CheckboxIndicator',
+      render: (p: Record<string, unknown>) => (
+        <CheckboxIndicator state="checked" {...p} />
+      ),
+    },
+    {
+      name: 'RadioIndicator',
+      render: (p: Record<string, unknown>) => (
+        <RadioIndicator state="checked" {...p} />
+      ),
+    },
+  ] as const;
+
+  for (const {name, render: renderCase} of cases) {
+    it(`${name} stays aria-hidden even when a caller passes false`, () => {
+      const {container} = render(renderCase({'aria-hidden': 'false'}));
+
+      expect(container.firstElementChild).toHaveAttribute(
+        'aria-hidden',
+        'true',
+      );
+    });
+
+    it(`${name} still forwards ordinary props`, () => {
+      // The negative control: order must not turn into "drop everything".
+      const {container} = render(
+        renderCase({'data-testid': 'ind', id: 'pinned', dir: 'rtl'}),
+      );
+      const el = container.firstElementChild;
+
+      expect(el).toHaveAttribute('data-testid', 'ind');
+      expect(el).toHaveAttribute('id', 'pinned');
+      expect(el).toHaveAttribute('dir', 'rtl');
+    });
+  }
+});
+
+describe('useIndicator', () => {
+  it('returns the built-in indicator without a theme override', () => {
+    const {result} = renderHook(() => useIndicator('checkbox'));
+
+    expect(result.current).toBe(CheckboxIndicator);
+  });
+
+  it('resolves an indicator component from the nearest theme', () => {
+    function BrandCheckbox({state}: IndicatorProps) {
+      return <span data-testid="brand">{state}</span>;
+    }
+    const theme = defineTheme({
+      name: 'brand-indicators',
+      indicators: {checkbox: BrandCheckbox},
+    });
+
+    const {result} = renderHook(() => useIndicator('checkbox'), {
+      wrapper: createThemeWrapper(theme),
+    });
+
+    expect(result.current).toBe(BrandCheckbox);
+    // Unmapped indicators keep the built-in.
+    expect(getIndicator('radio', theme)).toBe(RadioIndicator);
+  });
+});
+
+/**
+ * A theme target is public API. Renaming one to follow the
+ * `<component>-kebab` convention (`checkbox` → `checkbox-indicator`) would
+ * silently break every theme styling the old name — the CSS still compiles, it
+ * just stops matching. So both names are emitted for a deprecation window, and
+ * these tests pin that promise from both ends: the new name exists, and the
+ * old one has not quietly disappeared.
+ */
+describe('renamed theme targets stay non-breaking', () => {
+  const cases = [
+    {
+      name: 'CheckboxIndicator',
+      render: () => <CheckboxIndicator state="checked" />,
+      current: 'astryx-checkbox-indicator',
+      legacy: 'astryx-checkbox',
+    },
+    {
+      name: 'RadioIndicator',
+      render: () => <RadioIndicator state="checked" />,
+      current: 'astryx-radio-indicator',
+      legacy: 'astryx-radio',
+    },
+  ] as const;
+
+  for (const {name, render: renderCase, current, legacy} of cases) {
+    it(`${name} emits both the current and the legacy target`, () => {
+      const {container} = render(renderCase());
+      const el = container.querySelector(`.${current}`);
+      expect(el, `${name} should render ${current}`).toBeInTheDocument();
+      expect(el, `${name} must keep emitting ${legacy}`).toHaveClass(legacy);
+    });
+  }
+
+  it('keeps the legacy dot target on the radio mark', () => {
+    const {container} = render(<RadioIndicator state="checked" />);
+    const dot = container.querySelector('.astryx-radio-indicator-dot');
+    expect(dot).toBeInTheDocument();
+    expect(dot).toHaveClass('astryx-radio-dot');
+  });
+
+  it('puts both names on ONE element, so either selector wins equally', () => {
+    // If the legacy class were moved to a wrapper instead, an old theme's
+    // rules would land on a different box than a new theme's — same-element
+    // is what makes the two names interchangeable.
+    const {container} = render(<CheckboxIndicator state="unchecked" />);
+    expect(container.querySelectorAll('.astryx-checkbox')).toHaveLength(1);
+    expect(container.querySelector('.astryx-checkbox')).toBe(
+      container.querySelector('.astryx-checkbox-indicator'),
+    );
+  });
+});

package/src/Indicator/RadioIndicator.tsx

@@ -0,0 +1,206 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file RadioIndicator.tsx
+ * @input Indicator state props
+ * @output Exports RadioIndicator — the default radio selection visual
+ * @position Decorative radio visual shared by RadioList, decorative menu
+ *           markers, and any selection slot themed to use a radio
+ */
+
+import * as stylex from '@stylexjs/stylex';
+import {
+  borderVars,
+  colorVars,
+  durationVars,
+  easeVars,
+  radiusVars,
+} from '../theme/tokens.stylex';
+import {isRenderable, mergeProps, themeProps} from '../utils';
+import {indicatorScope} from './indicator.markers.stylex';
+import type {IndicatorProps} from './types';
+
+const styles = stylex.create({
+  circle: {
+    boxSizing: 'border-box',
+    display: 'flex',
+    alignItems: 'center',
+    justifyContent: 'center',
+    flexShrink: 0,
+    borderWidth: borderVars['--border-width'],
+    borderStyle: 'solid',
+    // A circle, in tokens: --radius-full is the house "fully rounded" value
+    // (9999px) and renders pixel-identical to 50% on a square box, which the
+    // size styles below guarantee. Themeable through --radius-full, unlike a
+    // raw 50%.
+    borderRadius: radiusVars['--radius-full'],
+    transitionProperty: 'background-color, border-color',
+    transitionDuration: {
+      default: durationVars['--duration-fast'],
+      '@media (prefers-reduced-motion: reduce)': '0s',
+    },
+    transitionTimingFunction: easeVars['--ease-standard'],
+  },
+  unchecked: {
+    borderColor: {
+      default: colorVars['--color-border-emphasized'],
+      [stylex.when.ancestor(':hover', indicatorScope)]: {
+        '@media (hover: hover)': `color-mix(in srgb, ${colorVars['--color-border-emphasized']}, ${colorVars['--color-tint-hover']} 20%)`,
+      },
+    },
+    backgroundColor: {
+      default: colorVars['--color-background-surface'],
+      [stylex.when.ancestor(':hover', indicatorScope)]: {
+        '@media (hover: hover)': `color-mix(in srgb, ${colorVars['--color-background-surface']}, ${colorVars['--color-tint-hover']} 5%)`,
+      },
+    },
+  },
+  checked: {
+    borderColor: {
+      default: colorVars['--color-accent'],
+      [stylex.when.ancestor(':hover', indicatorScope)]: {
+        '@media (hover: hover)': `color-mix(in srgb, ${colorVars['--color-accent']}, ${colorVars['--color-tint-hover']} 15%)`,
+      },
+    },
+    backgroundColor: {
+      default: colorVars['--color-accent'],
+      [stylex.when.ancestor(':hover', indicatorScope)]: {
+        '@media (hover: hover)': `color-mix(in srgb, ${colorVars['--color-accent']}, ${colorVars['--color-tint-hover']} 15%)`,
+      },
+    },
+  },
+  disabled: {
+    opacity: 0.5,
+    borderColor: {
+      default: colorVars['--color-border'],
+      [stylex.when.ancestor(':hover', indicatorScope)]: {
+        '@media (hover: hover)': colorVars['--color-border'],
+      },
+    },
+  },
+  disabledUnchecked: {
+    backgroundColor: {
+      default: colorVars['--color-background-muted'],
+      [stylex.when.ancestor(':hover', indicatorScope)]: {
+        '@media (hover: hover)': colorVars['--color-background-muted'],
+      },
+    },
+  },
+  dot: {
+    borderRadius: radiusVars['--radius-full'],
+    backgroundColor: {
+      default: colorVars['--color-on-accent'],
+      // Forced colors (Windows High Contrast) strips painted backgrounds,
+      // which would make the selected dot invisible — checked and unchecked
+      // radios would look identical. CanvasText keeps the dot perceivable on
+      // the Canvas circle fill (WCAG 1.4.11).
+      '@media (forced-colors: active)': 'CanvasText',
+    },
+  },
+});
+
+const circleSizeStyles = stylex.create({
+  sm: {
+    width: 20,
+    height: 20,
+  },
+  md: {
+    width: 24,
+    height: 24,
+  },
+});
+
+const dotSizeStyles = stylex.create({
+  sm: {
+    width: 8,
+    height: 8,
+  },
+  md: {
+    width: 10,
+    height: 10,
+  },
+});
+
+/**
+ * The default radio visual: a circle with a filled inner dot when selected.
+ *
+ * Decorative and non-interactive — it renders `aria-hidden` and owns no input,
+ * role, or focus behavior. Themes replace it wholesale through
+ * `defineTheme({indicators: {radio: MyRadio}})`, or restyle it through the
+ * `radio` / `radio-dot` theme targets like any other component.
+ *
+ * Unlike an icon, a radio draws in *both* states — an empty circle when
+ * unchecked. That is what makes it usable as a selection indicator in
+ * components whose default is "a checkmark when selected, nothing otherwise".
+ *
+ * @example
+ * ```
+ * <RadioIndicator state="checked" size="md" />
+ * ```
+ */
+export function RadioIndicator({
+  state,
+  size = 'md',
+  isDisabled = false,
+  children,
+  ref,
+  className,
+  style,
+  xstyle,
+  ...rest
+}: IndicatorProps<'singleSelection'>) {
+  // A radio has no partial state; anything other than unchecked reads as
+  // selected.
+  const isChecked = state !== 'unchecked';
+
+  return (
+    <span
+      // `{...rest}` first, own contract after. TypeScript cannot reject a
+      // hyphenated JSX attribute (see IndicatorProps), so attribute order is
+      // what actually keeps a caller from un-hiding a decorative element —
+      // rubric P3, "owned aria-* set after {...rest}".
+      {...rest}
+      ref={ref}
+      aria-hidden="true"
+      {...mergeProps(
+        themeProps(
+          'radio-indicator',
+          {
+            size,
+            checked: isChecked ? 'checked' : null,
+            disabled: isDisabled ? 'disabled' : null,
+          },
+          // `radio` was the target before indicators existed; themes styling
+          // it keep working until the next major.
+          {legacyNames: ['radio']},
+        ),
+        stylex.props(
+          styles.circle,
+          circleSizeStyles[size],
+          isChecked ? styles.checked : styles.unchecked,
+          isDisabled && styles.disabled,
+          isDisabled && !isChecked && styles.disabledUnchecked,
+          xstyle,
+        ),
+        className,
+        style,
+      )}>
+      {isRenderable(children)
+        ? children
+        : isChecked && (
+            <span
+              {...mergeProps(
+                themeProps(
+                  'radio-indicator-dot',
+                  {size},
+                  {legacyNames: ['radio-dot']},
+                ),
+                stylex.props(styles.dot, dotSizeStyles[size]),
+              )}
+            />
+          )}
+    </span>
+  );
+}
+
+RadioIndicator.displayName = 'RadioIndicator';

package/src/Indicator/index.ts

@@ -0,0 +1,45 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file index.ts
+ * @input None (re-export barrel)
+ * @output Public indicator surface: components, registry, hook, types
+ * @position Entry point for the stateful control-visual layer
+ *
+ * Indicators are the componentized form of stateful control visuals — the
+ * checkbox box, the radio circle, the mark on a chosen option. They are
+ * decorative: the owning component keeps the role, state, and focus behavior,
+ * while the indicator turns state into a picture.
+ *
+ * That makes them themeable through CSS targets like any other component, and
+ * replaceable wholesale by name through `defineTheme({indicators})` — replace
+ * `check` and every single-selection mark in the app follows.
+ */
+
+export {CheckboxIndicator} from './CheckboxIndicator';
+export {CheckIndicator} from './CheckIndicator';
+export {RadioIndicator} from './RadioIndicator';
+
+// Registry (RSC-compatible, no 'use client')
+export {defaultIndicators, getIndicator} from './indicatorRegistry';
+export type {
+  CoreIndicatorName,
+  IndicatorRegistrySource,
+} from './indicatorRegistry';
+
+export {useIndicator} from './useIndicator';
+
+export {indicatorScope} from './indicator.markers.stylex';
+
+export type {
+  IndicatorComponent,
+  IndicatorFamily,
+  IndicatorFamilyMap,
+  IndicatorMap,
+  IndicatorName,
+  IndicatorNameOfFamily,
+  IndicatorProps,
+  IndicatorRegistry,
+  IndicatorSize,
+  IndicatorState,
+} from './types';

package/src/Indicator/indicator.markers.stylex.ts

@@ -0,0 +1,19 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import * as stylex from '@stylexjs/stylex';
+
+/**
+ * Scoped marker for indicator ancestor selectors.
+ *
+ * An owner (CheckboxInput's row, RadioListItem's row) applies this marker to
+ * the element whose hover and focus should drive the indicator's appearance.
+ * The indicator reads it through `stylex.when.ancestor()`, so interaction
+ * state stays in CSS instead of being threaded through React props — and
+ * owners that should *not* tint their indicator on hover (decorative menu
+ * markers, listbox options) simply don't apply the marker.
+ *
+ * Owners apply it only while enabled, so disabled controls get no hover
+ * feedback.
+ */
+export const indicatorScope: ReturnType<typeof stylex.defineMarker> =
+  stylex.defineMarker();