@astryxdesign/core 0.3.0 → 0.4.0

package/src/Field/Field.doc.mjs

@@ -34,6 +34,7 @@ export const docs = {
         className: 'astryx-input-status-icon',
         visualProps: ['size', 'status'],
       },
+      {className: 'astryx-input-clear-icon'},
     ],
     vars: [
       {name: '--_field-radius', description: 'Border radius of input fields', default: 'var(--radius-element)', private: true},

package/src/Field/InputClearButton.test.tsx

@@ -0,0 +1,117 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file InputClearButton.test.tsx
+ * @input Uses vitest, @testing-library/react, InputClearButton, Icon, theme
+ * @output Unit tests for the shared clear-button primitive
+ * @position Testing; validates InputClearButton.tsx — the single home for the
+ *   clearable input family's clear (✕) affordance and its theme target.
+ *
+ * SYNC: When InputClearButton.tsx changes, update tests to match new behavior.
+ */
+
+import {describe, it, expect, vi} from 'vitest';
+import {render, screen, fireEvent} from '@testing-library/react';
+import {InputClearButton} from './InputClearButton';
+import {Icon} from '../Icon';
+import {defineTheme} from '../theme/defineTheme';
+import {generateThemeCSS} from '../theme/generateThemeRules';
+
+function generateThemeTestCSS(theme: Parameters<typeof generateThemeCSS>[0]) {
+  const {prose, component} = generateThemeCSS(theme);
+  return [prose, component].filter(Boolean).join('\n\n');
+}
+
+const getGlyph = (): HTMLElement => {
+  const button = screen.getByRole('button', {name: 'Clear'});
+  const icon = button.querySelector('.astryx-icon');
+  if (icon == null) {
+    throw new Error('clear glyph not found');
+  }
+  return icon as HTMLElement;
+};
+
+describe('InputClearButton', () => {
+  it('renders a real button with the given accessible label', () => {
+    render(<InputClearButton label="Clear" onClick={() => {}} />);
+    const button = screen.getByRole('button', {name: 'Clear'});
+    expect(button.tagName).toBe('BUTTON');
+  });
+
+  it('fires onClick with the native event when pressed', () => {
+    const onClick = vi.fn();
+    render(<InputClearButton label="Clear" onClick={onClick} />);
+    fireEvent.click(screen.getByRole('button', {name: 'Clear'}));
+    expect(onClick).toHaveBeenCalledTimes(1);
+    expect(onClick.mock.calls[0][0]).toBeInstanceOf(Object);
+  });
+
+  it('renders the astryx-input-clear-icon target on the glyph', () => {
+    // One canonical target on the icon element itself — so a theme restyles
+    // the clear glyph across the whole input family from a single place.
+    render(<InputClearButton label="Clear" onClick={() => {}} />);
+    const glyph = getGlyph();
+    expect(glyph).toHaveClass('astryx-input-clear-icon');
+    expect(glyph).toHaveClass('astryx-icon');
+  });
+
+  it('matches a standalone inherit/sm close icon aside from the target class', () => {
+    // The glyph is a secondary/sm close icon (matching the other field
+    // affordances — chevrons, calendar toggles, status icons); aside from the
+    // target class it is exactly that standalone Icon, so the default look is
+    // defined once here rather than per input.
+    render(<InputClearButton label="Clear" onClick={() => {}} />);
+    const glyph = getGlyph();
+
+    const {container} = render(
+      <Icon icon="close" size="sm" color="secondary" />,
+    );
+    const refIcon = container.querySelector('.astryx-icon') as HTMLElement;
+
+    const styleClasses = (el: HTMLElement) =>
+      el.className
+        .split(' ')
+        .filter(c => c !== 'astryx-input-clear-icon')
+        .sort();
+
+    expect(styleClasses(glyph)).toEqual(styleClasses(refIcon));
+  });
+
+  it('merges an extra iconClassName beside the canonical target', () => {
+    // Consumers that shipped a component-specific target before the family
+    // converged pass it through here to keep emitting it for a deprecation
+    // window.
+    render(
+      <InputClearButton
+        label="Clear"
+        onClick={() => {}}
+        iconClassName="astryx-date-input-clear-icon"
+      />,
+    );
+    const glyph = getGlyph();
+    expect(glyph).toHaveClass('astryx-input-clear-icon');
+    expect(glyph).toHaveClass('astryx-date-input-clear-icon');
+  });
+
+  it('exposes input-clear-icon so a theme reaches the glyph color, size, and hover', () => {
+    const theme = defineTheme({
+      name: 'input-clear-icon-test',
+      components: {
+        'input-clear-icon': {
+          base: {
+            width: '12px',
+            height: '12px',
+            fontSize: '12px',
+            color: 'var(--color-icon-secondary)',
+            ':hover': {color: 'var(--color-icon-primary)'},
+          },
+        },
+      },
+    });
+    const css = generateThemeTestCSS(theme);
+    expect(css).toContain('.astryx-input-clear-icon {');
+    expect(css).toContain('width: 12px');
+    expect(css).toContain('.astryx-input-clear-icon:hover {');
+    expect(css).toContain('color: var(--color-icon-primary)');
+  });
+});

package/src/Field/InputClearButton.tsx

@@ -5,14 +5,20 @@
 /**
  * @file InputClearButton.tsx
  * @input Uses React, Button, Icon
- * @output Exports InputClearButton shared clear button for input components
- * @position Shared primitive; used by Typeahead, Tokenizer, TextInput
+ * @output Exports InputClearButton, the shared clear (✕) button rendered by
+ *   every clearable input in the family.
+ * @position Shared primitive. Every input that renders a clear affordance —
+ *   TextInput, NumberInput, TimeInput, DateInput, DateTimeInput,
+ *   DateRangeInput, Selector, MultiSelector, Typeahead, Tokenizer, FileInput —
+ *   routes it through here, so the glyph is themed in one place via the
+ *   `astryx-input-clear-icon` target.
  */
 
 import type {ReactNode} from 'react';
 import * as stylex from '@stylexjs/stylex';
 import {Button} from '../Button';
 import {Icon} from '../Icon';
+import {themeProps} from '../utils/themeProps';
 
 const styles = stylex.create({
   button: {
@@ -25,19 +31,40 @@ export interface InputClearButtonProps {
   label: string;
   onClick: (e: React.MouseEvent<HTMLButtonElement>) => void;
   xstyle?: stylex.StyleXStyles;
+  /**
+   * Extra class(es) for the clear glyph itself, merged onto the shared
+   * `astryx-input-clear-icon` target. Used by inputs that shipped a
+   * component-specific clear-icon target before the family converged here
+   * (e.g. `astryx-date-input-clear-icon`) to keep emitting it for a
+   * deprecation window; new callers don't need it.
+   */
+  iconClassName?: string;
 }
 
 export function InputClearButton({
   label,
   onClick,
   xstyle,
+  iconClassName,
 }: InputClearButtonProps): ReactNode {
+  const {className: iconTargetClassName} = themeProps('input-clear-icon');
   return (
     <Button
       variant="ghost"
       size="sm"
       label={label}
-      icon={<Icon icon="close" size="sm" color="inherit" />}
+      icon={
+        <Icon
+          icon="close"
+          size="sm"
+          color="secondary"
+          className={
+            iconClassName != null
+              ? `${iconTargetClassName} ${iconClassName}`
+              : iconTargetClassName
+          }
+        />
+      }
       onClick={onClick}
       isIconOnly
       xstyle={[styles.button, xstyle]}

package/src/HoverCard/useHoverCard.tsx

@@ -15,7 +15,6 @@
 import {
   useCallback,
   useEffect,
-  useMemo,
   useRef,
   type ReactNode,
   type RefCallback,
@@ -45,18 +44,6 @@ const styles = stylex.create({
     boxShadow: shadowVars['--shadow-med'],
   },
   // Position-based margin styles
-  marginBlock: {
-    marginBlockStart: spacingVars['--spacing-1'],
-    marginBlockEnd: spacingVars['--spacing-1'],
-    marginInlineStart: 0,
-    marginInlineEnd: 0,
-  },
-  marginInline: {
-    marginBlockStart: 0,
-    marginBlockEnd: 0,
-    marginInlineStart: spacingVars['--spacing-1'],
-    marginInlineEnd: spacingVars['--spacing-1'],
-  },
   // Content wrapper for padding and mouse events.
   // `display: block` keeps the wrapper a block box even though it renders as a
   // `span` (the layer uses inline-safe phrasing markup so it is valid inside a
@@ -265,22 +252,13 @@ export function useHoverCard(options: HoverCardOptions = {}): HoverCardReturn {
     onHide,
   } = options;
 
-  // Select margin style based on placement axis
-  const marginStyle =
-    placement === 'above' || placement === 'below'
-      ? styles.marginBlock
-      : styles.marginInline;
-
   const layer = useLayer({
     mode: 'context',
     onShow,
     onHide,
   });
 
-  const popoverXstyle = useMemo(
-    () => [styles.container, marginStyle],
-    [marginStyle],
-  );
+  const popoverXstyle = styles.container;
 
   const showTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
   const hideTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
@@ -472,6 +450,7 @@ export function useHoverCard(options: HoverCardOptions = {}): HoverCardReturn {
       const renderProps = {
         placement: renderPlacement,
         alignment: props?.alignment ?? alignment,
+        offset: spacingVars['--spacing-1'],
         // A named dialog when a label is provided; otherwise a group. A group
         // may validly be unnamed, an unnamed dialog may not — and hover cards
         // are non-modal, so group is honest semantics without a name.

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