@astryxdesign/core 0.3.0 → 0.4.0-canary.41f53a0

package/dist/Indicator/RadioIndicator.js

@@ -0,0 +1,137 @@
+// 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 "../theme/tokens.stylex.js";
+import { borderVars, colorVars, durationVars, easeVars, radiusVars } from "../theme/tokens.stylex.js";
+import { isRenderable, mergeProps, themeProps } from "../utils/index.js";
+import "./indicator.markers.stylex.js";
+import { indicatorScope } from "./indicator.markers.stylex.js";
+import { jsx as _jsx } from "react/jsx-runtime";
+const styles = {
+  circle: {
+    kB7OPa: "x9f619",
+    k1xSpc: "x78zum5",
+    kGNEyG: "x6s0dn4",
+    kjj79g: "xl56j7k",
+    kmuXW: "x2lah0s",
+    kMzoRj: "x1litavf",
+    ksu8eU: "x1y0btm7",
+    kaIpWk: "xjspbzw",
+    k1ekBW: "xts7igz",
+    kIyJzY: "xuedmi6 x12w9bfk",
+    kAMwcw: "xlr8y92",
+    $$css: true
+  },
+  unchecked: {
+    kVAM5u: "xvy26l8 xilc7fp",
+    kWkggS: "x10xzikg xeultfy",
+    $$css: true
+  },
+  checked: {
+    kVAM5u: "xad5do x1ozl1p1",
+    kWkggS: "x1ewilqj x17srpfb",
+    $$css: true
+  },
+  disabled: {
+    kSiTet: "xbyyjgo",
+    kVAM5u: "x14i3s5s x61roa7",
+    $$css: true
+  },
+  disabledUnchecked: {
+    kWkggS: "xwmxj5m xqxnq6d",
+    $$css: true
+  },
+  dot: {
+    kaIpWk: "xjspbzw",
+    kWkggS: "x1azo05 xwvh9j7",
+    $$css: true
+  }
+};
+const circleSizeStyles = {
+  sm: {
+    kzqmXN: "xw4jnvo",
+    kZKoxP: "x1qx5ct2",
+    $$css: true
+  },
+  md: {
+    kzqmXN: "xvy4d1p",
+    kZKoxP: "xxk0z11",
+    $$css: true
+  }
+};
+const dotSizeStyles = {
+  sm: {
+    kzqmXN: "x1xc55vz",
+    kZKoxP: "xdk7pt",
+    $$css: true
+  },
+  md: {
+    kzqmXN: "x1fsd2vl",
+    kZKoxP: "x170jfvy",
+    $$css: true
+  }
+};
+
+/**
+ * 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
+}) {
+  // A radio has no partial state; anything other than unchecked reads as
+  // selected.
+  const isChecked = state !== 'unchecked';
+  return /*#__PURE__*/_jsx("span", {
+    ...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),
+    children: isRenderable(children) ? children : isChecked && /*#__PURE__*/_jsx("span", {
+      ...mergeProps(themeProps('radio-indicator-dot', {
+        size
+      }, {
+        legacyNames: ['radio-dot']
+      }), stylex.props(styles.dot, dotSizeStyles[size]))
+    })
+  });
+}
+RadioIndicator.displayName = 'RadioIndicator';

package/dist/Indicator/index.d.ts

@@ -0,0 +1,24 @@
+/**
+ * @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';
+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, IndicatorPosition, IndicatorProps, IndicatorRegistry, IndicatorSize, IndicatorState, } from './types';
+//# sourceMappingURL=index.d.ts.map

package/dist/Indicator/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/Indicator/index.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAC,iBAAiB,EAAC,MAAM,qBAAqB,CAAC;AACtD,OAAO,EAAC,cAAc,EAAC,MAAM,kBAAkB,CAAC;AAChD,OAAO,EAAC,cAAc,EAAC,MAAM,kBAAkB,CAAC;AAGhD,OAAO,EAAC,iBAAiB,EAAE,YAAY,EAAC,MAAM,qBAAqB,CAAC;AACpE,YAAY,EACV,iBAAiB,EACjB,uBAAuB,GACxB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EAAC,YAAY,EAAC,MAAM,gBAAgB,CAAC;AAE5C,OAAO,EAAC,cAAc,EAAC,MAAM,4BAA4B,CAAC;AAE1D,YAAY,EACV,kBAAkB,EAClB,eAAe,EACf,kBAAkB,EAClB,YAAY,EACZ,aAAa,EACb,qBAAqB,EACrB,iBAAiB,EACjB,cAAc,EACd,iBAAiB,EACjB,aAAa,EACb,cAAc,GACf,MAAM,SAAS,CAAC"}

package/dist/Indicator/index.js

@@ -0,0 +1,26 @@
+// 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.js";
+export { CheckIndicator } from "./CheckIndicator.js";
+export { RadioIndicator } from "./RadioIndicator.js";
+
+// Registry (RSC-compatible, no 'use client')
+export { defaultIndicators, getIndicator } from "./indicatorRegistry.js";
+export { useIndicator } from "./useIndicator.js";
+export { indicatorScope } from "./indicator.markers.stylex.js";

package/dist/Indicator/indicator.markers.stylex.d.ts

@@ -0,0 +1,16 @@
+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 declare const indicatorScope: ReturnType<typeof stylex.defineMarker>;
+//# sourceMappingURL=indicator.markers.stylex.d.ts.map

package/dist/Indicator/indicator.markers.stylex.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"indicator.markers.stylex.d.ts","sourceRoot":"","sources":["../../src/Indicator/indicator.markers.stylex.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,MAAM,MAAM,kBAAkB,CAAC;AAE3C;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,cAAc,EAAE,UAAU,CAAC,OAAO,MAAM,CAAC,YAAY,CAC3C,CAAC"}

package/dist/Indicator/indicator.markers.stylex.js

@@ -0,0 +1,21 @@
+// 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 = {
+  x1odsvnm: "x1odsvnm",
+  $$css: true
+};

package/dist/Indicator/indicatorRegistry.d.ts

@@ -0,0 +1,71 @@
+/**
+ * @file indicatorRegistry.ts
+ * @input Theme source and indicator name
+ * @output Exports the default indicator map and getIndicator resolution
+ * @position Server-safe indicator resolver; no 'use client' so it is
+ *           importable from RSC
+ *
+ * Two name spaces meet here, and keeping them apart is the whole design:
+ *
+ *   - {@link CoreIndicatorName} — the indicators Astryx itself ships. Closed,
+ *     and every one of them has a default, so resolving one always yields a
+ *     component.
+ *   - {@link IndicatorName} — every indicator name that exists, including the
+ *     ones other packages add by augmenting `IndicatorMap`. Open, and core has
+ *     no default for a name it has never heard of.
+ *
+ * `getIndicator` is overloaded along that seam: a core name resolves to a
+ * component, an augmented name resolves to a component *or* `undefined`, and
+ * the caller has to say what to do about it. Typing the map as total over the
+ * open union instead — which is what shipped in #4712 — made the compiler
+ * promise a component for `getIndicator('brand-star')` and hand back
+ * `undefined` at runtime.
+ */
+import type { DefinedTheme } from '../theme/defineTheme';
+import type { IndicatorComponent, IndicatorMap, IndicatorName } from './types';
+/**
+ * The indicator names Astryx ships a default for.
+ *
+ * Written out rather than derived from {@link IndicatorMap}, because that
+ * interface is open to augmentation and this set is not: it is exactly what is
+ * in {@link defaultIndicators} below. `indicatorRegistry.test.tsx` pins the two
+ * together in both directions.
+ */
+export type CoreIndicatorName = 'check' | 'checkbox' | 'radio';
+/**
+ * The indicators Astryx ships. A theme's `indicators` entries override these
+ * by name.
+ *
+ * Typed per family (rather than as one widened component type) so a default
+ * declared here has to accept the states its family passes — the same rule
+ * {@link IndicatorRegistry} holds replacements to.
+ */
+export declare const defaultIndicators: {
+    [N in CoreIndicatorName]: IndicatorComponent<IndicatorMap[N]>;
+};
+export type IndicatorRegistrySource = DefinedTheme | string | null | undefined;
+/**
+ * Resolve an indicator component by name, preferring the theme's override and
+ * falling back to the built-in indicator.
+ *
+ * Works in both server and client environments. Client components should use
+ * the {@link useIndicator} hook, which resolves against the nearest `<Theme>`.
+ *
+ * @example
+ * ```
+ * const Radio = getIndicator('radio', themeName);
+ * <Radio state="checked" />
+ * ```
+ *
+ * For a name contributed by augmentation there is no built-in to fall back to,
+ * so the result is `undefined` unless a theme supplies one — the package that
+ * added the name owns its default:
+ *
+ * @example
+ * ```
+ * const Star = getIndicator('brand-star', themeName) ?? BrandStar;
+ * ```
+ */
+export declare function getIndicator<N extends CoreIndicatorName>(name: N, source?: IndicatorRegistrySource): IndicatorComponent<IndicatorMap[N]>;
+export declare function getIndicator<N extends IndicatorName>(name: N, source?: IndicatorRegistrySource): IndicatorComponent<IndicatorMap[N]> | undefined;
+//# sourceMappingURL=indicatorRegistry.d.ts.map

package/dist/Indicator/indicatorRegistry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"indicatorRegistry.d.ts","sourceRoot":"","sources":["../../src/Indicator/indicatorRegistry.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,sBAAsB,CAAC;AAKvD,OAAO,KAAK,EACV,kBAAkB,EAClB,YAAY,EACZ,aAAa,EAEd,MAAM,SAAS,CAAC;AAEjB;;;;;;;GAOG;AACH,MAAM,MAAM,iBAAiB,GAAG,OAAO,GAAG,UAAU,GAAG,OAAO,CAAC;AAE/D;;;;;;;GAOG;AACH,eAAO,MAAM,iBAAiB,EAAE;KAC7B,CAAC,IAAI,iBAAiB,GAAG,kBAAkB,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;CAK9D,CAAC;AAEF,MAAM,MAAM,uBAAuB,GAAG,YAAY,GAAG,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;AAe/E;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,iBAAiB,EACtD,IAAI,EAAE,CAAC,EACP,MAAM,CAAC,EAAE,uBAAuB,GAC/B,kBAAkB,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC;AACvC,wBAAgB,YAAY,CAAC,CAAC,SAAS,aAAa,EAClD,IAAI,EAAE,CAAC,EACP,MAAM,CAAC,EAAE,uBAAuB,GAC/B,kBAAkB,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC"}

package/dist/Indicator/indicatorRegistry.js

@@ -0,0 +1,93 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file indicatorRegistry.ts
+ * @input Theme source and indicator name
+ * @output Exports the default indicator map and getIndicator resolution
+ * @position Server-safe indicator resolver; no 'use client' so it is
+ *           importable from RSC
+ *
+ * Two name spaces meet here, and keeping them apart is the whole design:
+ *
+ *   - {@link CoreIndicatorName} — the indicators Astryx itself ships. Closed,
+ *     and every one of them has a default, so resolving one always yields a
+ *     component.
+ *   - {@link IndicatorName} — every indicator name that exists, including the
+ *     ones other packages add by augmenting `IndicatorMap`. Open, and core has
+ *     no default for a name it has never heard of.
+ *
+ * `getIndicator` is overloaded along that seam: a core name resolves to a
+ * component, an augmented name resolves to a component *or* `undefined`, and
+ * the caller has to say what to do about it. Typing the map as total over the
+ * open union instead — which is what shipped in #4712 — made the compiler
+ * promise a component for `getIndicator('brand-star')` and hand back
+ * `undefined` at runtime.
+ */
+
+import { getRegisteredTheme } from "../theme/themeRegistry.js";
+import { CheckboxIndicator } from "./CheckboxIndicator.js";
+import { CheckIndicator } from "./CheckIndicator.js";
+import { RadioIndicator } from "./RadioIndicator.js";
+
+/**
+ * The indicator names Astryx ships a default for.
+ *
+ * Written out rather than derived from {@link IndicatorMap}, because that
+ * interface is open to augmentation and this set is not: it is exactly what is
+ * in {@link defaultIndicators} below. `indicatorRegistry.test.tsx` pins the two
+ * together in both directions.
+ */
+
+/**
+ * The indicators Astryx ships. A theme's `indicators` entries override these
+ * by name.
+ *
+ * Typed per family (rather than as one widened component type) so a default
+ * declared here has to accept the states its family passes — the same rule
+ * {@link IndicatorRegistry} holds replacements to.
+ */
+export const defaultIndicators = {
+  check: CheckIndicator,
+  checkbox: CheckboxIndicator,
+  radio: RadioIndicator
+};
+function getTheme(source) {
+  if (source == null) {
+    return null;
+  }
+  return typeof source === 'string' ? getRegisteredTheme(source) : source;
+}
+function getThemeIndicators(source) {
+  return getTheme(source)?.indicators ?? null;
+}
+
+/**
+ * Resolve an indicator component by name, preferring the theme's override and
+ * falling back to the built-in indicator.
+ *
+ * Works in both server and client environments. Client components should use
+ * the {@link useIndicator} hook, which resolves against the nearest `<Theme>`.
+ *
+ * @example
+ * ```
+ * const Radio = getIndicator('radio', themeName);
+ * <Radio state="checked" />
+ * ```
+ *
+ * For a name contributed by augmentation there is no built-in to fall back to,
+ * so the result is `undefined` unless a theme supplies one — the package that
+ * added the name owns its default:
+ *
+ * @example
+ * ```
+ * const Star = getIndicator('brand-star', themeName) ?? BrandStar;
+ * ```
+ */
+
+export function getIndicator(name, source) {
+  const override = getThemeIndicators(source)?.[name];
+  return override ??
+  // `name` may be an augmented one, which this map has no entry for — hence
+  // the `| undefined` the overloads expose to those callers.
+  defaultIndicators[name];
+}

package/dist/Indicator/types.d.ts

@@ -0,0 +1,177 @@
+/**
+ * @file types.ts
+ * @input None (pure type definitions)
+ * @output The indicator contract: families, states, props, names, registry
+ * @position Type foundation for stateful control visuals
+ *
+ * An **indicator** is a decorative visual that expresses a piece of component
+ * state: the box a checkbox draws, the circle a radio draws, the mark on a
+ * chosen list option. The owning component keeps the input, role, accessible
+ * name, focus, and keyboard behavior; the indicator turns state into a picture.
+ *
+ * Componentizing them buys three things a theme could not otherwise have:
+ *
+ *   1. **Theme it** — an indicator renders stable `astryx-*` class targets, so
+ *      `defineTheme({components})` restyles it like any other component, in one
+ *      place rather than per host component.
+ *   2. **Swizzle it** — `astryx swizzle <Name>` copies the source to own.
+ *   3. **Replace it** — `defineTheme({indicators})` swaps in another component
+ *      by name, and every component that renders that indicator follows. A
+ *      product that wants radio visuals for single selection replaces `check`.
+ *
+ * Indicators come in **families**, and a family fixes the state space. That is
+ * what lets one mechanism serve semantics as different as "is this option
+ * chosen" and "are several of these chosen" without either pretending to be
+ * the other, and without a shared enum that would typecheck `indeterminate` on
+ * a radio.
+ *
+ * Each family's vocabulary is the one the accessibility layer already uses, so
+ * a component passing state down says the same word its ARIA attribute says.
+ * Sharing one enum across families was measured and rejected (#4831): it
+ * produced call sites reading `aria-expanded={isOpen}` beside
+ * `state={isOpen ? 'on' : 'off'}`.
+ */
+import type { ComponentType, ReactNode, Ref } from 'react';
+import type { BaseProps } from '../BaseProps';
+/**
+ * The indicator families, each mapped to the states it can express.
+ *
+ * Single and multi selection are separate families because their state spaces
+ * genuinely differ: `aria-checked` is `true|false` for a radio and
+ * `true|false|mixed` for a checkbox. Keeping them apart is what makes a
+ * replacement type-checkable — a checkbox visual cannot stand in where only
+ * two states are ever passed, and a radio cannot be asked to draw a partial
+ * state it has no picture for.
+ *
+ * Adding a family is additive: declare it here, then declare indicators of
+ * that family in {@link IndicatorMap}. Packages outside core can contribute
+ * families through module augmentation.
+ */
+export interface IndicatorFamilyMap {
+    /** Is this one thing chosen? Radios, and the mark on a selected option. */
+    singleSelection: 'unchecked' | 'checked';
+    /** Which of these are chosen? Checkboxes, including the partial state. */
+    multiSelection: 'unchecked' | 'checked' | 'indeterminate';
+}
+export type IndicatorFamily = keyof IndicatorFamilyMap & string;
+/** The states an indicator of family `F` can be asked to draw. */
+export type IndicatorState<F extends IndicatorFamily = IndicatorFamily> = IndicatorFamilyMap[F];
+/** Indicator size scale — matches the control sizes of the owning inputs. */
+export type IndicatorSize = 'sm' | 'md';
+/**
+ * Which edge of its row an indicator sits on.
+ *
+ * Logical, not physical: `start` is the left edge in LTR and the right edge in
+ * RTL. Owned by the host component, not by the indicator — an indicator draws a
+ * picture and has no say in where the row puts it — which is why this is a prop
+ * on the components that lay out rows rather than part of
+ * {@link IndicatorProps}.
+ */
+export type IndicatorPosition = 'start' | 'end';
+/**
+ * Props every indicator accepts.
+ *
+ * Indicators are **decorative**: they render `aria-hidden` visuals and own no
+ * role, focus, keyboard handling, or state. The component that renders one
+ * (CheckboxInput, RadioListItem, a listbox option) keeps all of that. An
+ * indicator's only job is to turn `state` into a picture.
+ *
+ * The a11y props are omitted from this interface rather than left to
+ * convention: un-hiding an indicator has it announced next to the control that
+ * owns the accessible name — the same thing said twice (#4918). A replacement
+ * that genuinely needs announcing is not an indicator; name the owning control.
+ *
+ * `tabIndex` is omitted for the same reason, one step on: the element is
+ * unconditionally `aria-hidden`, so a tab stop on it is a focusable node inside
+ * a hidden subtree. Measured with axe in real Chromium: 0 `aria-hidden-focus`
+ * violations becomes 1 the moment it is forwarded.
+ *
+ * The omission is only half enforceable, and it is worth knowing which half.
+ * TypeScript exempts JSX attribute names that are not valid JS identifiers from
+ * excess-property checking, so a LITERAL `role=` is a compile error while
+ * `aria-hidden` and `aria-label` are not — and a spread (`{...props}`, the
+ * ordinary host idiom) bypasses the check for every member, `role` included.
+ * Measured, not assumed. So the components also emit their own `aria-hidden`
+ * AFTER `{...rest}` and drop a forwarded `tabIndex`: that ordering, not the
+ * type, is what enforces the contract. Nothing else is stripped — a forwarded
+ * `aria-label` still reaches the DOM, inert inside an `aria-hidden` subtree.
+ *
+ * Interaction state is deliberately *not* a prop. Hover and focus reach an
+ * indicator through the CSS ancestor marker ({@link indicatorScope}) applied
+ * by its owner, so a row hover tints the control without anyone threading a
+ * boolean through React — and an owner that should not tint its indicator
+ * simply does not apply the marker.
+ */
+export interface IndicatorProps<F extends IndicatorFamily = IndicatorFamily> extends Omit<BaseProps<HTMLSpanElement>, 'aria-hidden' | 'role' | 'aria-label' | 'aria-labelledby' | 'tabIndex'> {
+    /** Ref forwarded to the indicator's root element. */
+    ref?: Ref<HTMLSpanElement>;
+    /** Which state to draw. The state space is fixed by the family. */
+    state: IndicatorState<F>;
+    /**
+     * Control size.
+     * @default 'md'
+     */
+    size?: IndicatorSize;
+    /**
+     * Whether the owning control is disabled. Purely visual — the owner still
+     * owns the actual disabled semantics.
+     * @default false
+     */
+    isDisabled?: boolean;
+    /**
+     * Content rendered inside the indicator chrome *instead of* the state mark.
+     * CheckboxInput uses this to show a loading Spinner inside the box while a
+     * change action is pending.
+     */
+    children?: ReactNode;
+}
+/** An indicator is any component accepting {@link IndicatorProps} of its family. */
+export type IndicatorComponent<F extends IndicatorFamily = IndicatorFamily> = ComponentType<IndicatorProps<F>>;
+/**
+ * The named indicators a theme can replace, each mapped to its family.
+ *
+ * The name is what a theme addresses, and what every component renders
+ * through — so replacing `check` reaches every single-selection mark at once,
+ * which is the point.
+ *
+ * Packages outside core can contribute their own through module augmentation.
+ * Core ships no default for a name it does not know, so the package that adds
+ * the name owns its default — `getIndicator`/`useIndicator` return
+ * `| undefined` for it, and the call site supplies the fallback:
+ *
+ * ```ts
+ * declare module '@astryxdesign/core/Indicator' {
+ *   interface IndicatorMap {
+ *     'brand-star': 'singleSelection';
+ *   }
+ * }
+ *
+ * const Star = useIndicator('brand-star') ?? BrandStar;
+ * ```
+ */
+export interface IndicatorMap {
+    /** The mark on a chosen option — a checkmark by default. */
+    check: 'singleSelection';
+    /** The filled circle of a radio control. */
+    radio: 'singleSelection';
+    /** The box of a checkbox control, including its partial state. */
+    checkbox: 'multiSelection';
+}
+export type IndicatorName = keyof IndicatorMap & string;
+/** The indicator names belonging to family `F`. */
+export type IndicatorNameOfFamily<F extends IndicatorFamily> = {
+    [N in IndicatorName]: IndicatorMap[N] extends F ? N : never;
+}[IndicatorName];
+/**
+ * Theme-provided indicator overrides, keyed by indicator name.
+ *
+ * Family-checked: each entry must accept the state space of that indicator's
+ * family, so a replacement cannot be written against the wrong states. A
+ * `check` replacement that only handles `collapsed`/`expanded`, or a `radio`
+ * replacement expecting `indeterminate`, is a type error rather than a
+ * runtime surprise.
+ */
+export type IndicatorRegistry = {
+    [N in IndicatorName]?: IndicatorComponent<IndicatorMap[N]>;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/Indicator/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/Indicator/types.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,OAAO,KAAK,EAAC,aAAa,EAAE,SAAS,EAAE,GAAG,EAAC,MAAM,OAAO,CAAC;AACzD,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAE5C;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,kBAAkB;IACjC,2EAA2E;IAC3E,eAAe,EAAE,WAAW,GAAG,SAAS,CAAC;IACzC,0EAA0E;IAC1E,cAAc,EAAE,WAAW,GAAG,SAAS,GAAG,eAAe,CAAC;CAC3D;AAED,MAAM,MAAM,eAAe,GAAG,MAAM,kBAAkB,GAAG,MAAM,CAAC;AAEhE,kEAAkE;AAClE,MAAM,MAAM,cAAc,CAAC,CAAC,SAAS,eAAe,GAAG,eAAe,IACpE,kBAAkB,CAAC,CAAC,CAAC,CAAC;AAExB,6EAA6E;AAC7E,MAAM,MAAM,aAAa,GAAG,IAAI,GAAG,IAAI,CAAC;AAExC;;;;;;;;GAQG;AACH,MAAM,MAAM,iBAAiB,GAAG,OAAO,GAAG,KAAK,CAAC;AAEhD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,MAAM,WAAW,cAAc,CAC7B,CAAC,SAAS,eAAe,GAAG,eAAe,CAC3C,SAAQ,IAAI,CACZ,SAAS,CAAC,eAAe,CAAC,EAC1B,aAAa,GAAG,MAAM,GAAG,YAAY,GAAG,iBAAiB,GAAG,UAAU,CACvE;IACC,qDAAqD;IACrD,GAAG,CAAC,EAAE,GAAG,CAAC,eAAe,CAAC,CAAC;IAC3B,mEAAmE;IACnE,KAAK,EAAE,cAAc,CAAC,CAAC,CAAC,CAAC;IACzB;;;OAGG;IACH,IAAI,CAAC,EAAE,aAAa,CAAC;IACrB;;;;OAIG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,SAAS,CAAC;CACtB;AAED,oFAAoF;AACpF,MAAM,MAAM,kBAAkB,CAAC,CAAC,SAAS,eAAe,GAAG,eAAe,IACxE,aAAa,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,CAAC;AAEnC;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,WAAW,YAAY;IAC3B,4DAA4D;IAC5D,KAAK,EAAE,iBAAiB,CAAC;IACzB,4CAA4C;IAC5C,KAAK,EAAE,iBAAiB,CAAC;IACzB,kEAAkE;IAClE,QAAQ,EAAE,gBAAgB,CAAC;CAC5B;AAED,MAAM,MAAM,aAAa,GAAG,MAAM,YAAY,GAAG,MAAM,CAAC;AAExD,mDAAmD;AACnD,MAAM,MAAM,qBAAqB,CAAC,CAAC,SAAS,eAAe,IAAI;KAC5D,CAAC,IAAI,aAAa,GAAG,YAAY,CAAC,CAAC,CAAC,SAAS,CAAC,GAAG,CAAC,GAAG,KAAK;CAC5D,CAAC,aAAa,CAAC,CAAC;AAEjB;;;;;;;;GAQG;AACH,MAAM,MAAM,iBAAiB,GAAG;KAC7B,CAAC,IAAI,aAAa,CAAC,CAAC,EAAE,kBAAkB,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;CAC3D,CAAC"}

package/dist/Indicator/types.js

@@ -0,0 +1 @@
+export {};

package/dist/Indicator/useIndicator.d.ts

@@ -0,0 +1,18 @@
+import { type CoreIndicatorName } from './indicatorRegistry';
+import type { IndicatorComponent, IndicatorMap, IndicatorName } from './types';
+/**
+ * Resolve an indicator component from the nearest `<Theme>`.
+ *
+ * A core indicator always resolves. A name contributed by augmentation
+ * resolves only if a theme supplies it, so that overload returns
+ * `| undefined` — see {@link getIndicator}.
+ *
+ * @example
+ * ```
+ * const Checkbox = useIndicator('checkbox');
+ * return <Checkbox state={isChecked ? 'checked' : 'unchecked'} size={size} />;
+ * ```
+ */
+export declare function useIndicator<N extends CoreIndicatorName>(name: N): IndicatorComponent<IndicatorMap[N]>;
+export declare function useIndicator<N extends IndicatorName>(name: N): IndicatorComponent<IndicatorMap[N]> | undefined;
+//# sourceMappingURL=useIndicator.d.ts.map

package/dist/Indicator/useIndicator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useIndicator.d.ts","sourceRoot":"","sources":["../../src/Indicator/useIndicator.ts"],"names":[],"mappings":"AAYA,OAAO,EAAe,KAAK,iBAAiB,EAAC,MAAM,qBAAqB,CAAC;AACzE,OAAO,KAAK,EAAC,kBAAkB,EAAE,YAAY,EAAE,aAAa,EAAC,MAAM,SAAS,CAAC;AAE7E;;;;;;;;;;;;GAYG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,iBAAiB,EACtD,IAAI,EAAE,CAAC,GACN,kBAAkB,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC;AACvC,wBAAgB,YAAY,CAAC,CAAC,SAAS,aAAa,EAClD,IAAI,EAAE,CAAC,GACN,kBAAkB,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC"}

package/dist/Indicator/useIndicator.js

@@ -0,0 +1,30 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file useIndicator.ts
+ * @input Indicator name
+ * @output Exports useIndicator hook for theme-aware indicator components
+ * @position Client hook used by controls that render a selection visual
+ */
+import { useThemeName } from "../theme/useTheme.js";
+import { getIndicator } from "./indicatorRegistry.js";
+
+/**
+ * Resolve an indicator component from the nearest `<Theme>`.
+ *
+ * A core indicator always resolves. A name contributed by augmentation
+ * resolves only if a theme supplies it, so that overload returns
+ * `| undefined` — see {@link getIndicator}.
+ *
+ * @example
+ * ```
+ * const Checkbox = useIndicator('checkbox');
+ * return <Checkbox state={isChecked ? 'checked' : 'unchecked'} size={size} />;
+ * ```
+ */
+
+export function useIndicator(name) {
+  return getIndicator(name, useThemeName());
+}

package/dist/Item/Item.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Item.d.ts","sourceRoot":"","sources":["../../src/Item/Item.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAS,KAAK,SAAS,EAAC,MAAM,OAAO,CAAC;AAU7C,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAY5C,MAAM,MAAM,SAAS,GAAG,QAAQ,GAAG,OAAO,CAAC;AAC3C,MAAM,MAAM,WAAW,GAAG,SAAS,GAAG,UAAU,GAAG,UAAU,CAAC;AAE9D,MAAM,WAAW,SAAU,SAAQ,SAAS,CAAC,WAAW,CAAC;IACvD,yCAAyC;IACzC,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;IAE7B;;;OAGG;IACH,EAAE,CAAC,EAAE,KAAK,GAAG,IAAI,GAAG,MAAM,CAAC;IAE3B;;;OAGG;IACH,MAAM,CAAC,EAAE,SAAS,CAAC;IAEnB;;;OAGG;IACH,YAAY,CAAC,EAAE,SAAS,CAAC;IAEzB;;;OAGG;IACH,KAAK,EAAE,SAAS,CAAC;IAEjB;;OAEG;IACH,WAAW,CAAC,EAAE,SAAS,CAAC;IAExB;;;OAGG;IACH,UAAU,CAAC,EAAE,SAAS,CAAC;IAEvB;;;OAGG;IACH,KAAK,CAAC,EAAE,SAAS,CAAC;IAElB;;;;OAIG;IACH,OAAO,CAAC,EAAE,WAAW,CAAC;IAEtB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;;OAGG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAE1B;;OAEG;IACH,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,CAAC,UAAU,KAAK,IAAI,CAAC;IAE5C;;;;;;;;;;;OAWG;IACH,cAAc,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC;IAErD;;OAEG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd;;OAEG;IACH,MAAM,CAAC,EAAE,QAAQ,GAAG,OAAO,CAAC;IAE5B;;;OAGG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IAEb;;;OAGG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IAExB;;;;;;;;OAQG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IAErB;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IAErB;;OAEG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AA0KD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,IAAI,CAAC,EACnB,EAAE,EAAE,SAAiB,EACrB,MAAM,EACN,YAAY,EACZ,KAAK,EACL,WAAW,EACX,UAAU,EACV,KAAgB,EAChB,OAAoB,EACpB,UAAU,EACV,gBAAgB,EAChB,OAAO,EACP,cAAc,EACd,IAAI,EACJ,MAAM,EAAE,eAAe,EACvB,GAAG,EAAE,YAAY,EACjB,aAAqB,EACrB,UAAkB,EAClB,UAAkB,EAClB,MAAM,EACN,SAAS,EACT,KAAK,EACL,GAAG,EACH,IAAI,EACJ,GAAG,SAAS,EACb,EAAE,SAAS,+BA4MX;yBArOe,IAAI"}
+{"version":3,"file":"Item.d.ts","sourceRoot":"","sources":["../../src/Item/Item.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAS,KAAK,SAAS,EAAC,MAAM,OAAO,CAAC;AAU7C,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAa5C,MAAM,MAAM,SAAS,GAAG,QAAQ,GAAG,OAAO,CAAC;AAC3C,MAAM,MAAM,WAAW,GAAG,SAAS,GAAG,UAAU,GAAG,UAAU,CAAC;AAE9D,MAAM,WAAW,SAAU,SAAQ,SAAS,CAAC,WAAW,CAAC;IACvD,yCAAyC;IACzC,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;IAE7B;;;OAGG;IACH,EAAE,CAAC,EAAE,KAAK,GAAG,IAAI,GAAG,MAAM,CAAC;IAE3B;;;OAGG;IACH,MAAM,CAAC,EAAE,SAAS,CAAC;IAEnB;;;OAGG;IACH,YAAY,CAAC,EAAE,SAAS,CAAC;IAEzB;;;OAGG;IACH,KAAK,EAAE,SAAS,CAAC;IAEjB;;OAEG;IACH,WAAW,CAAC,EAAE,SAAS,CAAC;IAExB;;;OAGG;IACH,UAAU,CAAC,EAAE,SAAS,CAAC;IAEvB;;;OAGG;IACH,KAAK,CAAC,EAAE,SAAS,CAAC;IAElB;;;;OAIG;IACH,OAAO,CAAC,EAAE,WAAW,CAAC;IAEtB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;;OAGG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAE1B;;OAEG;IACH,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,CAAC,UAAU,KAAK,IAAI,CAAC;IAE5C;;;;;;;;;;;OAWG;IACH,cAAc,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC;IAErD;;OAEG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd;;OAEG;IACH,MAAM,CAAC,EAAE,QAAQ,GAAG,OAAO,CAAC;IAE5B;;;OAGG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IAEb;;;OAGG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IAExB;;;;;;;;OAQG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IAErB;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IAErB;;OAEG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAmKD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,IAAI,CAAC,EACnB,EAAE,EAAE,SAAiB,EACrB,MAAM,EACN,YAAY,EACZ,KAAK,EACL,WAAW,EACX,UAAU,EACV,KAAgB,EAChB,OAAoB,EACpB,UAAU,EACV,gBAAgB,EAChB,OAAO,EACP,cAAc,EACd,IAAI,EACJ,MAAM,EAAE,eAAe,EACvB,GAAG,EAAE,YAAY,EACjB,aAAqB,EACrB,UAAkB,EAClB,UAAkB,EAClB,MAAM,EACN,SAAS,EACT,KAAK,EACL,GAAG,EACH,IAAI,EACJ,GAAG,SAAS,EACb,EAAE,SAAS,+BA2MX;yBApOe,IAAI"}