@astryxdesign/core 0.3.0 → 0.4.0

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';

package/src/Indicator/Indicator.doc.mjs

@@ -0,0 +1,344 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
+
+export const docs = {
+  name: 'Indicator',
+  displayName: 'Indicator',
+  group: 'Indicator',
+  category: 'Data Input',
+  isHiddenFromOverview: true,
+  keywords: [
+    'indicator',
+    'checkbox',
+    'radio',
+    'control',
+    'selection',
+    'mark',
+    'tick',
+    'themeable',
+    'swap',
+  ],
+  description:
+    'Decorative control visuals: the mark on a chosen option, the box a checkbox draws, the circle a radio draws. Rendered by Selector, CheckboxInput, RadioList, and menu selection rows. Replace one by name through defineTheme({indicators}) and every component drawing it follows.',
+  components: [
+    {
+      name: 'CheckboxIndicator',
+      displayName: 'Checkbox Indicator',
+      description:
+        'The checkbox visual: a square box with a checkmark or an indeterminate bar. Decorative (aria-hidden); the owning control keeps the input, role, accessible name, focus, and keyboard behavior.',
+      props: [
+        {
+          name: 'state',
+          type: "'unchecked' | 'checked' | 'indeterminate'",
+          description:
+            'Which state to draw. An indicator draws in EVERY state: the unchecked box is an empty box, not nothing.',
+          required: true,
+        },
+        {
+          name: 'size',
+          type: "'sm' | 'md'",
+          description: 'Control size: 20px or 24px.',
+          default: "'md'",
+        },
+        {
+          name: 'isDisabled',
+          type: 'boolean',
+          description:
+            'Whether the owning control is disabled. Purely visual; the owner keeps the real disabled semantics.',
+          default: 'false',
+        },
+        {
+          name: 'children',
+          type: 'ReactNode',
+          description:
+            'Rendered inside the chrome INSTEAD of the state mark. CheckboxInput passes its loading Spinner through this while a change action is pending, so a replacement indicator must render children when they will actually draw something — `isRenderable(children)`, never `children ?? mark`, because a host writes `children={isBusy && <Spinner/>}` and `false` slips straight past a nullish check and deletes the mark.',
+        },
+      ],
+    },
+    {
+      name: 'CheckIndicator',
+      displayName: 'Check Indicator',
+      description:
+        'The mark on a chosen option: a checkmark by default, and nothing at all when unchosen, so a listbox shows no empty box beside every row. This is the indicator to replace to change what "chosen" looks like: mapping it to RadioIndicator gives every single-selection mark radio visuals, including an empty circle on unchosen rows. Unlike the checkbox and radio visuals it renders no chrome of its own (it IS the glyph), so a host\'s theme target lands on the same element as astryx-icon.',
+      props: [
+        {
+          name: 'state',
+          type: "'unchecked' | 'checked'",
+          description:
+            'Which state to draw. The default renders nothing when unchecked; a replacement may draw in both states.',
+          required: true,
+        },
+        {
+          name: 'size',
+          type: "'sm' | 'md'",
+          description: 'Control size, matching the other indicators.',
+          default: "'md'",
+        },
+        {
+          name: 'isDisabled',
+          type: 'boolean',
+          description:
+            'Whether the owning row is disabled. Purely visual; the owner keeps the real disabled semantics.',
+          default: 'false',
+        },
+        {
+          name: 'children',
+          type: 'ReactNode',
+          description:
+            'Rendered INSTEAD of the mark, in every state: a host showing a pending Spinner passes it through whether or not the row is chosen.',
+        },
+      ],
+    },
+    {
+      name: 'RadioIndicator',
+      displayName: 'Radio Indicator',
+      description:
+        'The radio visual: a circle with a filled inner dot when selected. Draws in both states; an unselected radio is an empty circle, which is what lets it stand in for a checkmark in a selection slot.',
+      props: [
+        {
+          name: 'state',
+          type: "'unchecked' | 'checked'",
+          description:
+            'Which state to draw. Radio belongs to the singleSelection family, which has no partial state.',
+          required: true,
+        },
+        {
+          name: 'size',
+          type: "'sm' | 'md'",
+          description: 'Control size: 20px or 24px.',
+          default: "'md'",
+        },
+        {
+          name: 'isDisabled',
+          type: 'boolean',
+          description:
+            'Whether the owning control is disabled. Purely visual; the owner keeps the real disabled semantics.',
+          default: 'false',
+        },
+        {
+          name: 'children',
+          type: 'ReactNode',
+          description:
+            'Rendered inside the chrome INSTEAD of the state mark.',
+        },
+      ],
+    },
+  ],
+  theming: {
+    targets: [
+      {
+        className: 'astryx-checkbox-indicator',
+        visualProps: ['size'],
+        states: ['checked', 'disabled'],
+      },
+      {
+        className: 'astryx-radio-indicator',
+        visualProps: ['size'],
+        states: ['checked', 'disabled'],
+      },
+      {className: 'astryx-radio-indicator-dot', visualProps: ['size']},
+      // Still emitted beside the names above, so themes written against them
+      // keep working. Drop in the next major.
+      {
+        className: 'astryx-checkbox',
+        visualProps: ['size'],
+        states: ['checked', 'disabled'],
+        deprecatedFor: 'checkbox-indicator',
+      },
+      {
+        className: 'astryx-radio',
+        visualProps: ['size'],
+        states: ['checked', 'disabled'],
+        deprecatedFor: 'radio-indicator',
+      },
+      {
+        className: 'astryx-radio-dot',
+        visualProps: ['size'],
+        deprecatedFor: 'radio-indicator-dot',
+      },
+    ],
+  },
+  examples: [
+    {
+      label: 'Restyle an indicator (the common path)',
+      code: `// Indicators render the same stable class targets wherever they appear, so
+// one component override reaches the form control, the menu row, and any
+// selection slot themed to use it. No indicator-specific API needed.
+defineTheme({
+  name: 'brand',
+  components: {
+    'checkbox-indicator': {
+      base: {borderRadius: 'var(--radius-full)', borderWidth: '2px'},
+      checked: {
+        backgroundColor: 'var(--color-accent)',
+        borderColor: 'var(--color-accent)',
+      },
+      'checked+disabled': {backgroundColor: 'var(--color-background-muted)'},
+    },
+    'radio-indicator': {base: {borderWidth: '2px'}},
+    'radio-indicator-dot': {base: {borderRadius: '2px'}},
+  },
+});`,
+    },
+    {
+      label: 'Replace an indicator with your own component',
+      code: `// When the shape itself is wrong, hand the theme a component. It receives
+// {state, size, isDisabled, children} and nothing else.
+//
+// Use theme tokens, never raw values — run \`npx astryx docs tokens\` for the
+// full set. Color: --color-accent, --color-on-accent, --color-border,
+// --color-border-emphasized, --color-background-surface,
+// --color-background-muted. Radius: --radius-inner, --radius-full.
+// Border width: --border-width.
+import {isRenderable} from '@astryxdesign/core/utils';
+
+function BrandCheckbox({state, size = 'md', isDisabled, children}) {
+  return (
+    <span
+      aria-hidden="true"
+      style={{
+        width: size === 'sm' ? 20 : 24,
+        height: size === 'sm' ? 20 : 24,
+        borderRadius: 'var(--radius-inner)',
+        border: 'var(--border-width) solid var(--color-border-emphasized)',
+        color: 'var(--color-accent)',
+        opacity: isDisabled ? 0.5 : 1,
+      }}>
+      {/* children first: the owner passes a loading Spinner through it.
+          isRenderable, NOT \`children ??\` — a host writes
+          children={isBusy && <Spinner/>}, and \`false\` is neither null nor
+          caught by ??, so a nullish check takes the children branch, renders
+          nothing in it, and deletes your mark on every chosen row. */}
+      {isRenderable(children)
+        ? children
+        : state === 'checked' && <StarGlyph />}
+    </span>
+  );
+}
+
+defineTheme({name: 'brand', indicators: {checkbox: BrandCheckbox}});`,
+    },
+    {
+      label: 'Use radio visuals for single selection',
+      code: `// Replacement is by NAME, so one entry reaches every component that draws
+// that indicator. Here every option in a Selector listbox draws a radio —
+// including the unselected ones, which a check mark cannot do.
+import {RadioIndicator} from '@astryxdesign/core/Indicator';
+
+defineTheme({name: 'brand', indicators: {check: RadioIndicator}});`,
+    },
+  ],
+  usage: {
+    description:
+      'Indicators are the componentized selection visuals shared by CheckboxInput, RadioList, and menu selection rows. They are decorative: the owning component keeps the input, role, accessible name, focus, and keyboard behavior, while the indicator turns state into a picture. That split is what makes them themeable: restyle one through its class targets, or replace the component outright.',
+    bestPractices: [
+      {
+        guidance: true,
+        description:
+          'Reach for component overrides first (components: {checkbox}). Replacing the component is the heavier path, for when the shape itself is wrong.',
+      },
+      {
+        guidance: true,
+        description:
+          'A replacement must render `children` when they will actually draw something: use `isRenderable(children)`, not `children != null` or `children ?? mark`. The owning control passes its loading Spinner through as `children={isBusy && <Spinner/>}`, so the value is `false` whenever it is not busy: a nullish check takes the children branch, renders nothing, and deletes your state mark on every chosen row (#4893).',
+      },
+      {
+        guidance: true,
+        description:
+          'A replacement must set aria-hidden. The owning control provides the role and accessible name; a visible indicator would be announced twice.',
+      },
+      {
+        guidance: true,
+        description:
+          'Use theme tokens for every color, radius, and border width in a replacement. Run `npx astryx docs tokens` for the set.',
+      },
+      {
+        guidance: true,
+        description:
+          'Render a single root ELEMENT, and let it keep the border-radius you want the focus ring to follow. A control whose real input is visually hidden cannot show focus on that input, so the owner paints the standard ring onto the indicator element itself at focus time (useIndicatorFocusRing), and `outline` then picks up that element\'s radius. A replacement needs no cooperation and can forget nothing: the ring is never missing (WCAG 2.4.7), it is only the wrong shape if the root has no radius of its own. Do not draw a focus ring yourself; the owner already did.',
+      },
+      {
+        guidance: false,
+        description:
+          'Thread hover or pressed state in as props. Interaction state reaches an indicator through the owner\'s CSS ancestor marker, so hovering the row tints the control with no props involved.',
+      },
+      {
+        guidance: false,
+        description:
+          'Assume you are only mounted when selected. The host renders its indicator unconditionally and passes `state`, in every state; that is what lets a replacement draw where the default draws nothing (a radio\'s empty circle on an unchosen row). Drawing nothing in a state is a decision the indicator makes, not one the host makes for it.',
+      },
+    ],
+    anatomy: [
+      {
+        name: 'Chrome',
+        required: true,
+        description:
+          'The persistent box or circle, present in every state. Carries the astryx-checkbox-indicator / astryx-radio-indicator theme target (the pre-indicator astryx-checkbox / astryx-radio names are still emitted on the same element).',
+      },
+      {
+        name: 'State mark',
+        required: false,
+        description:
+          'The checkmark, indeterminate bar, or radio dot shown inside the chrome for the current state.',
+      },
+    ],
+  },
+};
+
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
+export const docsDense = {
+  description:
+    'Decorative selection visuals: the mark on a chosen option, the checkbox box, the radio circle. Rendered by Selector/CheckboxInput/RadioList/menu rows. Replace one by name via defineTheme({indicators}) and every component drawing it follows.',
+  usage: {
+    description:
+      'Componentized selection visuals shared by CheckboxInput, RadioList, and menu rows. Decorative: the owner keeps input/role/name/focus/keyboard; the indicator turns state into a picture. That split makes them themeable: restyle via class targets or replace the component.',
+    bestPractices: [
+      { guidance: true, description: 'Prefer component overrides first (components: {checkbox}). Replacing the component is the heavier path, for when the shape itself is wrong.' },
+      { guidance: true, description: 'A replacement must render `children` when they will draw something: use `isRenderable(children)`, not `children != null` or `children ?? mark`. The owner passes a loading Spinner as `children={isBusy && <Spinner/>}`, so it is `false` when idle; a nullish check then renders nothing and deletes the mark on every chosen row (#4893).' },
+      { guidance: true, description: 'A replacement must set aria-hidden. The owner supplies role and accessible name; a visible indicator would be announced twice.' },
+      { guidance: true, description: 'Use theme tokens for every color, radius, and border width in a replacement. Run `npx astryx docs tokens` for the set.' },
+      { guidance: true, description: 'Render a single root ELEMENT with the border-radius the focus ring should follow. The owner paints the standard ring onto the indicator at focus time (useIndicatorFocusRing) and outline picks up its radius; the ring is never missing (WCAG 2.4.7), only mis-shaped if the root lacks a radius. Do not draw a focus ring yourself.' },
+      { guidance: false, description: 'Thread hover or pressed state in as props. Interaction state reaches an indicator through the owner\'s CSS ancestor marker.' },
+      { guidance: false, description: 'Assume you are only mounted when selected. The host renders the indicator unconditionally and passes `state` in every state; that is what lets a replacement draw where the default draws nothing (a radio\'s empty circle on an unchosen row).' },
+    ],
+  },
+  components: [
+    {
+      name: 'CheckboxIndicator',
+      displayName: 'Checkbox Indicator',
+      description:
+        'Checkbox visual: a square box with a checkmark or indeterminate bar. Decorative (aria-hidden); the owner keeps input/role/name/focus/keyboard.',
+      propDescriptions: {
+        state: "which state to draw. An indicator draws in EVERY state: unchecked is an empty box, not nothing.",
+        size: 'control size: 20px or 24px.',
+        isDisabled: 'whether the owner is disabled. Purely visual; the owner keeps the real disabled semantics.',
+        children: 'rendered inside the chrome INSTEAD of the state mark. CheckboxInput passes its loading Spinner through while a change action is pending, so a replacement must render children when present or the busy visual is lost.',
+      },
+    },
+    {
+      name: 'CheckIndicator',
+      displayName: 'Check Indicator',
+      description:
+        'The mark on a chosen option: a checkmark by default, nothing when unchosen. Map to RadioIndicator for radio visuals on single-selection marks. Renders no chrome of its own (it IS the glyph), so a theme target lands on the same element as astryx-icon.',
+      propDescriptions: {
+        state: 'which state to draw. The default renders nothing when unchecked; a replacement may draw in both states.',
+        size: 'control size, matching the other indicators.',
+        isDisabled: 'whether the owning row is disabled. Purely visual; the owner keeps the real disabled semantics.',
+        children: 'rendered INSTEAD of the mark, in every state; a host showing a pending Spinner passes it through whether or not the row is chosen.',
+      },
+    },
+    {
+      name: 'RadioIndicator',
+      displayName: 'Radio Indicator',
+      description:
+        'Radio visual: a circle with a filled inner dot when selected. Draws in both states; an unselected radio is an empty circle, which is what lets it stand in for a checkmark in a selection slot.',
+      propDescriptions: {
+        state: 'which state to draw. Radio belongs to the singleSelection family, which has no partial state.',
+        size: 'control size: 20px or 24px.',
+        isDisabled: 'whether the owner is disabled. Purely visual; the owner keeps the real disabled semantics.',
+        children: 'rendered inside the chrome INSTEAD of the state mark.',
+      },
+    },
+  ],
+};