@astryxdesign/core 0.3.0 → 0.4.0-canary.058f476

package/src/Icon/Icon.doc.mjs

@@ -55,7 +55,7 @@ export const docs = {
     description: 'Icons are small visual symbols that represent actions, objects, or concepts. They improve scannability and reinforce meaning alongside text. Supports both direct SVG components and semantic icon names that adapt to the active theme.',
     bestPractices: [
       { guidance: true, description: 'Use semantic icon names when available; they adapt to theme changes automatically.' },
-      { guidance: true, description: "Libraries can augment the icon map with their own keys: registerIcons({'richtext:bold': <MyIcon />}) accepts arbitrary extension keys (not just the built-in IconName set). Resolve them with getExtendedIcon(key, fallback), which prefers a theme-registered icon and falls back to a bundled default — the seam that makes library-shipped icons theme-overridable." },
+      { guidance: true, description: "Override icons through the theme, not globally: defineTheme({icons: {close: <XMarkIcon />}}) scopes the swap to the active <Theme>, and extends shallow-merges it into derived themes. registerIcons() mutates a process-wide registry and warns in dev, so keep it for app bootstrap rather than making it a library's theming seam." },
       { guidance: true, description: 'Pair icons with text labels for accessibility; icon-only elements need an accessible label.' },
       { guidance: true, description: 'For a meaningful standalone icon (no adjacent text), give it an accessible name via the `label` prop: it sets role="img" + aria-label and unhides the icon.' },
       { guidance: true, description: 'Use color tokens for icon colors, not hardcoded hex values.' },
@@ -133,6 +133,7 @@ export const docsDense = {
     description: 'Icons are small visual symbols that represent actions, objects, or concepts. They improve scannability and reinforce meaning alongside text. Supports both direct SVG components and semantic icon names that adapt to the active theme.',
     bestPractices: [
       { guidance: true, description: 'Use semantic icon names when available; they adapt to theme changes automatically.' },
+      { guidance: true, description: "Override icons via theme, not globally: defineTheme({icons: {close: <XMarkIcon />}}) scopes the swap to the active <Theme>; extends shallow-merges into derived themes. registerIcons() mutates a global registry and warns in dev: app bootstrap only, not a library theming seam." },
       { guidance: true, description: 'Pair icons with text labels for accessibility; icon-only elements need an accessible label.' },
       { guidance: true, description: 'For a meaningful standalone icon (no adjacent text), set an accessible name via `label`: sets role="img" + aria-label, unhides icon.' },
       { guidance: true, description: 'Use color tokens for icon colors, not hardcoded hex values.' },

package/src/Icon/globalIconRegistry.tsx

@@ -110,12 +110,12 @@ function getThemeIconOverrides(
  * ```
  *
  * Libraries may also register their own extension keys (any string), so a
- * theme can override them the same way it overrides built-in icons:
+ * theme can override them the same way it overrides built-in icons. A library
+ * that ships its own icons registers them by key, then resolves with
+ * `getIcon('richtext:bold')`.
  * @example
  * ```
- * // In a library that ships its own icons:
  * registerIcons({ 'richtext:bold': <MyBoldIcon /> });
- * // resolve with getIcon('richtext:bold')
  * ```
  */
 export function registerIcons(
@@ -191,9 +191,10 @@ export function getIcon(
  * override the key via {@link registerIcons} without the library having to
  * widen the core {@link IconName} union.
  *
+ * The `fallback` is the library default, overridable by a theme registering the
+ * same key (for example `'richtext:bold'`).
  * @example
  * ```
- * // Library default, overridable by a theme registering 'richtext:bold':
  * getExtendedIcon('richtext:bold', <BoldGlyph />)
  * ```
  */

package/src/Indicator/CheckIndicator.tsx

@@ -0,0 +1,174 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file CheckIndicator.tsx
+ * @input Indicator state props
+ * @output Exports CheckIndicator — the default single-selection mark
+ * @position Decorative check visual used wherever "this one is chosen" is
+ *           marked without a control: selector options, menu rows
+ *
+ * This is the indicator a product replaces to change what "chosen" looks like.
+ * `defineTheme({indicators: {check: RadioIndicator}})` turns every
+ * single-selection mark into a radio, in one line, without any component
+ * knowing it happened.
+ *
+ * It draws NOTHING when unchecked, which is what makes it the default: a
+ * listbox should not show an empty box beside every row. A replacement is free
+ * to draw in both states — a radio does — and hosting components render the
+ * indicator unconditionally so that works.
+ *
+ * Unlike the checkbox and radio indicators, this one renders no chrome of its
+ * own: it IS the glyph. Two consequences, both deliberate:
+ *
+ *   - It renders `<Icon>` directly rather than wrapping one, so the class the
+ *     host passes (`selector-check`, say) lands on the same element as
+ *     `astryx-icon` — one element carrying the mark and its theme target, per
+ *     the wrapper reduction in #4838/#4846.
+ *   - It adds NO theme target of its own. `astryx-checkbox` and `astryx-radio`
+ *     exist because those indicators draw chrome that needs styling; a check
+ *     is an icon, and `astryx-icon` plus the host's target already reach it.
+ */
+
+import * as stylex from '@stylexjs/stylex';
+import type {SVGProps} from 'react';
+import {Icon} from '../Icon/Icon';
+import {colorVars} from '../theme/tokens.stylex';
+import {isRenderable, mergeProps} from '../utils';
+import type {IndicatorProps} from './types';
+
+/** The check glyph matches the control sizes the indicator families share. */
+const iconSizeForIndicator = {
+  sm: 'sm',
+  md: 'sm',
+} as const;
+
+const styles = stylex.create({
+  // The children slot stands where the glyph would, so swapping a Spinner in
+  // for the mark does not move the row. 1rem is Icon's `sm` box, which is what
+  // `iconSizeForIndicator` resolves to at both indicator sizes.
+  slot: {
+    display: 'inline-flex',
+    alignItems: 'center',
+    justifyContent: 'center',
+    flexShrink: 0,
+    width: '1rem',
+    height: '1rem',
+  },
+  // Foreground for an inherit-shade Spinner, matching what the glyph would
+  // have painted. The sibling indicators set `color` on their chrome for the
+  // same reason.
+  enabled: {color: colorVars['--color-accent']},
+  // The same token Icon's `color="disabled"` resolves to, so the busy and the
+  // glyph paths read identically when the owner is disabled.
+  disabled: {color: colorVars['--color-icon-disabled']},
+});
+
+/**
+ * The default single-selection mark: a checkmark when chosen, nothing when not.
+ *
+ * Decorative and non-interactive — it renders `aria-hidden` and owns no role,
+ * state, or focus behavior; the option or row that hosts it keeps all of that.
+ *
+ * @example
+ * ```
+ * <CheckIndicator state={isSelected ? 'checked' : 'unchecked'} size="sm" />
+ * ```
+ *
+ * Swap every single-selection mark for a radio:
+ *
+ * @example
+ * ```
+ * import {RadioIndicator} from '@astryxdesign/core/Indicator';
+ * defineTheme({name: 'brand', indicators: {check: RadioIndicator}});
+ * ```
+ */
+export function CheckIndicator({
+  state,
+  size = 'md',
+  isDisabled = false,
+  children,
+  ref,
+  className,
+  style,
+  xstyle,
+  ...rest
+}: IndicatorProps<'singleSelection'>) {
+  const isChecked = state === 'checked';
+
+  // `children` (a pending Spinner, say) replaces the mark but keeps the
+  // indicator's place, matching the other indicators' contract. It is checked
+  // BEFORE `state`: a host passes a busy visual through in whatever state the
+  // row happens to be in, and an unchecked listbox row is the common one.
+  //
+  // `isRenderable`, not `children != null`: the idiom a host actually writes is
+  // `children={isBusy && <Spinner/>}`, which passes `false` when it is not
+  // busy. `false` is non-null, so a null check takes this branch, renders
+  // nothing inside it, and DELETES the mark on a chosen row (#4893).
+  //
+  // There is no glyph to hang the caller's props on in this branch, so they go
+  // on a span — every one of them, so a `data-testid`, an `id`, a handler or
+  // an `xstyle` behaves the same whether or not children are present.
+  if (isRenderable(children)) {
+    return (
+      <span
+        // Spread first, as on the glyph path below, so the indicator's own
+        // contract (aria-hidden, and the styling it composes) outranks any
+        // same-named attribute a caller passed through. The type omits the
+        // a11y props, but TypeScript cannot reject a hyphenated JSX attribute,
+        // so order is the part that actually holds.
+        {...rest}
+        ref={ref}
+        aria-hidden="true"
+        {...mergeProps(
+          stylex.props(
+            styles.slot,
+            isDisabled ? styles.disabled : styles.enabled,
+            xstyle,
+          ),
+          className,
+          style,
+        )}>
+        {children}
+      </span>
+    );
+  }
+
+  // Nothing to draw, and no box to reserve: an unmarked row keeps the layout
+  // it would have without this indicator.
+  if (!isChecked) {
+    return null;
+  }
+
+  return (
+    <Icon
+      // Spread first so the indicator's own contract (below) wins over any
+      // same-named DOM attribute a caller passed through.
+      //
+      // An indicator declares span props (BaseProps<HTMLSpanElement>) while
+      // Icon declares SVG ones, so the handler types differ nominally. For a
+      // registry icon the element that actually receives these IS a span
+      // (IconFromRegistry renders one), so forwarding them is correct at
+      // runtime; the cast only reconciles the two declarations.
+      {...(rest as Omit<SVGProps<SVGSVGElement>, 'color' | 'ref'>)}
+      // After the spread, deliberately. Icon puts its own a11y defaults BEFORE
+      // `{...props}` as a documented escape hatch (Icon.tsx), which is right
+      // for an icon and wrong for an indicator — this one is decorative by
+      // contract, so it re-asserts it here rather than inheriting the hatch.
+      aria-hidden="true"
+      icon="check"
+      size={iconSizeForIndicator[size]}
+      color={isDisabled ? 'disabled' : 'accent'}
+      // The focus ring rides in through xstyle (composed at resolution), but
+      // never paints here: it only activates under an owner's indicatorScope
+      // marker, and a listbox row that marks selection takes focus itself
+      // rather than marking its indicator.
+      xstyle={xstyle}
+      // Icon merges className/style with its own rather than shadowing them,
+      // so the host's theme target composes with `astryx-icon`.
+      className={className}
+      style={style}
+    />
+  );
+}
+
+CheckIndicator.displayName = 'CheckIndicator';

package/src/Indicator/CheckboxIndicator.tsx

@@ -0,0 +1,257 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file CheckboxIndicator.tsx
+ * @input Indicator state props
+ * @output Exports CheckboxIndicator — the default checkbox selection visual
+ * @position Decorative checkbox visual shared by CheckboxInput, CheckboxList,
+ *           and decorative menu markers
+ */
+
+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({
+  box: {
+    boxSizing: 'border-box',
+    display: 'flex',
+    alignItems: 'center',
+    justifyContent: 'center',
+    flexShrink: 0,
+    borderWidth: borderVars['--border-width'],
+    borderStyle: 'solid',
+    borderRadius: radiusVars['--radius-inner'],
+    transitionProperty: 'background-color, border-color',
+    transitionDuration: {
+      default: durationVars['--duration-fast'],
+      '@media (prefers-reduced-motion: reduce)': '0s',
+    },
+    transitionTimingFunction: easeVars['--ease-standard'],
+  },
+  // State-dependent colors with ancestor hover behavior
+  unchecked: {
+    // Foreground for the inherit-shade loading spinner (reads currentColor):
+    // brand accent on the light surface fill.
+    color: colorVars['--color-accent'],
+    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: {
+    // Foreground for the inherit-shade loading spinner (reads currentColor):
+    // on-accent color against the accent fill.
+    color: colorVars['--color-on-accent'],
+    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'],
+      },
+    },
+  },
+  checkmark: {
+    display: 'none',
+    color: {
+      default: colorVars['--color-on-accent'],
+      // Forced colors (Windows High Contrast) does not reliably force an SVG
+      // stroke painted with currentColor, so the check stays the same white as
+      // the flattened (Canvas) box fill — a white check on a white box.
+      // CanvasText keeps it perceivable on the Canvas box, matching the
+      // indeterminate mark (WCAG 1.4.11).
+      '@media (forced-colors: active)': 'CanvasText',
+    },
+  },
+  checkmarkVisible: {
+    display: 'block',
+  },
+  indeterminateMark: {
+    display: 'none',
+    backgroundColor: {
+      default: colorVars['--color-on-accent'],
+      // Forced colors (Windows High Contrast) strips painted backgrounds,
+      // which would make the indeterminate bar invisible; CanvasText keeps it
+      // perceivable on the Canvas box fill (WCAG 1.4.11). The checkmark carries
+      // the matching CanvasText treatment on its own style.
+      '@media (forced-colors: active)': 'CanvasText',
+    },
+    borderRadius: radiusVars['--radius-full'],
+  },
+  indeterminateMarkVisible: {
+    display: 'block',
+  },
+});
+
+const boxSizeStyles = stylex.create({
+  sm: {
+    width: 20,
+    height: 20,
+  },
+  md: {
+    width: 24,
+    height: 24,
+  },
+});
+
+const checkmarkSizeStyles = stylex.create({
+  sm: {
+    width: 12,
+    height: 12,
+  },
+  md: {
+    width: 14,
+    height: 14,
+  },
+});
+
+const indeterminateSizeStyles = stylex.create({
+  sm: {
+    width: 10,
+    height: 2,
+  },
+  md: {
+    width: 12,
+    height: 2,
+  },
+});
+
+/**
+ * The default checkbox visual: a square box with a checkmark or an
+ * indeterminate bar.
+ *
+ * Decorative and non-interactive — it renders `aria-hidden` and owns no input,
+ * role, or focus behavior. The focus ring lives on the owner's control wrapper
+ * (see CheckboxInput), so a theme that replaces this component keeps a visible
+ * focus indicator for free. Themes replace it wholesale through
+ * `defineTheme({indicators: {checkbox: MyCheckbox}})`, or restyle it through
+ * the `checkbox` theme target like any other component.
+ *
+ * @example
+ * ```
+ * <CheckboxIndicator state="indeterminate" size="sm" />
+ * ```
+ */
+export function CheckboxIndicator({
+  state,
+  size = 'md',
+  isDisabled = false,
+  children,
+  ref,
+  className,
+  style,
+  xstyle,
+  ...rest
+}: IndicatorProps<'multiSelection'>) {
+  const isChecked = state === 'checked';
+  const isIndeterminate = state === 'indeterminate';
+  const isCheckedOrIndeterminate = isChecked || isIndeterminate;
+
+  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(
+          'checkbox-indicator',
+          {
+            size,
+            checked: isChecked
+              ? 'checked'
+              : isIndeterminate
+                ? 'indeterminate'
+                : null,
+            disabled: isDisabled ? 'disabled' : null,
+          },
+          // `checkbox` was the target before indicators existed; themes
+          // styling it keep working until the next major.
+          {legacyNames: ['checkbox']},
+        ),
+        stylex.props(
+          styles.box,
+          boxSizeStyles[size],
+          isCheckedOrIndeterminate ? styles.checked : styles.unchecked,
+          isDisabled && styles.disabled,
+          isDisabled && !isCheckedOrIndeterminate && styles.disabledUnchecked,
+          xstyle,
+        ),
+        className,
+        style,
+      )}>
+      {isRenderable(children) ? (
+        children
+      ) : (
+        <>
+          <svg
+            viewBox="0 0 10 10"
+            {...stylex.props(
+              styles.checkmark,
+              checkmarkSizeStyles[size],
+              isChecked && styles.checkmarkVisible,
+            )}>
+            <path
+              d="M8.5 2.5L4 7.5L1.5 5"
+              stroke="currentColor"
+              strokeWidth="1.5"
+              fill="none"
+              strokeLinecap="round"
+              strokeLinejoin="round"
+            />
+          </svg>
+          <span
+            {...stylex.props(
+              styles.indeterminateMark,
+              indeterminateSizeStyles[size],
+              isIndeterminate && styles.indeterminateMarkVisible,
+            )}
+          />
+        </>
+      )}
+    </span>
+  );
+}
+
+CheckboxIndicator.displayName = 'CheckboxIndicator';