@astryxdesign/core 0.7.5-canary.fccd771 → 0.7.5

package/src/theme/defineTheme.ts

@@ -40,12 +40,58 @@
  */
 
 import type {ReactNode} from 'react';
-import type {IconName, NamespacedIconName} from '../Icon/globalIconRegistry';
+import type {
+  IconEntry,
+  IconName,
+  NamespacedIconName,
+} from '../Icon/globalIconRegistry';
 
 /**
  * Icon overrides a theme may declare: any built-in semantic name, plus the
- * namespaced keys components and libraries own (`'richtext:bold'`).
+ * namespaced keys components and libraries own (`'richtext:bold'`). Each entry
+ * is a React node or a pure synchronous function of `{size, variant}`, where
+ * `variant` is one of `Variant` or `undefined`.
  */
+type ThemeIconEntries<Variant extends string> = Partial<
+  Record<IconName | NamespacedIconName, IconEntry<Variant>>
+>;
+
+/**
+ * The variant names a base theme lists: exact for a theme from `defineTheme`,
+ * any string for another `DefinedTheme`, none without a base.
+ */
+type BaseThemeIconVariant<Base> = Base extends DefinedTheme
+  ? '__iconVariant' extends keyof Base
+    ? Base extends {name: string; __iconVariant?(variant: infer Variant): void}
+      ? Extract<Variant, string>
+      : string
+    : string
+  : never;
+
+/**
+ * The variant names a theme lists: its own `iconVariants` when it sets the
+ * field, otherwise the list it inherits from `extends`.
+ */
+type ThemeIconVariant<
+  IconVariants extends ReadonlyArray<string> | undefined,
+  Base,
+> = [IconVariants] extends [ReadonlyArray<infer Variant extends string>]
+  ? Variant
+  : BaseThemeIconVariant<Base>;
+
+/**
+ * The same names, as a type `defineTheme` does not infer from: only
+ * `iconVariants` and `extends` decide a theme's names, never the parameter
+ * types of its icon entry functions.
+ */
+type ThemeIconEntryVariant<
+  IconVariants extends ReadonlyArray<string> | undefined,
+  Base,
+> = [ThemeIconVariant<IconVariants, Base>][IconVariants extends unknown
+  ? 0
+  : never];
+
+/** The node-valued view of a theme's icons that public reads return. */
 type ThemeIconOverrides = Partial<
   Record<IconName | NamespacedIconName, ReactNode>
 >;
@@ -182,8 +228,18 @@ export type StyleOverrides = Record<string, string | Record<string, string>>;
  */
 export type ComponentStyleMap = Record<string, Record<string, StyleOverrides>>;
 
-/** Input to defineTheme */
-export interface DefineThemeInput {
+/**
+ * Input to defineTheme.
+ *
+ * `IconVariants` is the theme's own `iconVariants` list and `Base` its
+ * `extends` theme; together they type the `variant` an icon entry function
+ * receives. `defineTheme` infers both.
+ */
+export interface DefineThemeInput<
+  IconVariants extends ReadonlyArray<string> | undefined =
+    ReadonlyArray<string> | undefined,
+  Base extends DefinedTheme | undefined = DefinedTheme | undefined,
+> {
   /** Theme name — used for data-astryx-theme attribute and identification */
   name: string;
 
@@ -212,7 +268,7 @@ export interface DefineThemeInput {
    * });
    * ```
    */
-  extends?: DefinedTheme;
+  extends?: Base;
   /**
    * Unified typography configuration — fonts, scale, and weights.
    *
@@ -338,8 +394,45 @@ export interface DefineThemeInput {
    * ```
    */
   components?: ComponentStyleMap;
-  /** Icon registry — maps semantic icon names to React nodes */
-  icons?: ThemeIconOverrides;
+  /**
+   * Icon registry — maps semantic icon names and namespaced keys to artwork.
+   *
+   * An entry is a React node, or a pure synchronous function of
+   * `{size, variant}` that returns one. `Icon` passes the size it renders at
+   * (`'xsm' | 'sm' | 'md' | 'lg'`), so the theme can map it to its icon
+   * library's own props. A function must not use hooks, measure the DOM, read
+   * browser globals or mutable state, or have side effects. Its result is
+   * final: returning `null` draws nothing instead of falling back to a
+   * registered or built-in icon. A `null` or `undefined` node entry falls back.
+   *
+   * @example
+   * ```
+   * icons: {
+   *   close: <XMarkIcon />,
+   *   info: ({size}) => <InfoIcon weight={size === 'sm' ? 'bold' : 'regular'} />,
+   * }
+   * ```
+   *
+   * `variant` is typed as the names in `iconVariants` (or the inherited list).
+   */
+  icons?: ThemeIconEntries<ThemeIconEntryVariant<IconVariants, Base>>;
+  /**
+   * The icon variant names this theme supports, listed once for the whole
+   * theme — never per icon. Icon entry functions receive `variant` typed as
+   * these names.
+   *
+   * A theme that sets `iconVariants` replaces the list it would inherit from
+   * `extends`; a theme that omits it inherits the base's list.
+   *
+   * @example
+   * ```
+   * iconVariants: ['outline', 'filled'],
+   * icons: {
+   *   info: ({variant}) => (variant === 'filled' ? <InfoFilled /> : <InfoOutline />),
+   * },
+   * ```
+   */
+  iconVariants?: IconVariants;
   /**
    * Indicator overrides — replaces the components that draw stateful control
    * visuals with the theme's own, by name.
@@ -429,8 +522,29 @@ export interface DefinedTheme {
   localTokens?: Record<string, string>;
   /** Component style overrides */
   components?: ComponentStyleMap;
-  /** Icon registry */
+  /**
+   * Icon registry as React nodes. A function entry is read at
+   * `{size: 'md'}`; `Icon` resolves the entry at the size it renders.
+   */
   icons?: ThemeIconOverrides;
+  /**
+   * Icon entries with their functions, present when any entry is a function.
+   * Only Astryx icon resolution reads it.
+   * @internal
+   */
+  __icons?: ThemeIconEntries<never>;
+  /**
+   * The icon variant names this theme supports: its own `iconVariants`, or
+   * the list it inherited. Absent when no theme in its lineage lists any.
+   */
+  iconVariants?: ReadonlyArray<string>;
+  /**
+   * The variant list of the theme that defined each inherited function entry,
+   * kept where it differs from `iconVariants`, so the entry receives only
+   * variants its defining theme lists. Only Astryx icon resolution reads it.
+   * @internal
+   */
+  __iconEntryVariants?: Record<string, ReadonlyArray<string> | undefined>;
   /** Indicator overrides for stateful control visuals, keyed by name */
   indicators?: IndicatorRegistry;
   /** Whether this theme has been pre-compiled by theme build CLI */
@@ -470,11 +584,25 @@ export interface DefinedTheme {
   __axes?: ThemeGenerativeAxes;
 }
 
-/** A theme produced by the current defineTheme implementation. */
-export type ResolvedDefinedTheme = DefinedTheme & {
-  __adaptations: NormalizedThemeAdaptations;
-  __axes: ThemeGenerativeAxes;
-};
+/**
+ * A theme produced by the current defineTheme implementation. `IconVariant`
+ * is the names in its `iconVariants` list.
+ */
+export type ResolvedDefinedTheme<IconVariant extends string = string> =
+  DefinedTheme & {
+    __adaptations: NormalizedThemeAdaptations;
+    __axes: ThemeGenerativeAxes;
+    /**
+     * Type-only: the names in `iconVariants`, so a theme that `extends` this
+     * one types its icon entries by the list it inherits. Never set. Method
+     * syntax keeps resolved themes with different lists assignable to each
+     * other, as they were before the list existed. `astryx theme build` writes
+     * the same marker into a built theme's declaration.
+     * SYNC: packages/cli/api/theme/build/build.mjs (builtThemeType)
+     * @internal
+     */
+    __iconVariant?(variant: IconVariant): void;
+  };
 
 // =============================================================================
 // All defaults merged into a single flat map
@@ -530,7 +658,12 @@ function describeBadBase(value: unknown): string {
  * that are merged into the token map. Explicit `tokens` entries take
  * precedence over generated values.
  */
-export function defineTheme(input: DefineThemeInput): ResolvedDefinedTheme {
+export function defineTheme<
+  const IconVariants extends ReadonlyArray<string> | undefined = undefined,
+  Base extends DefinedTheme | undefined = undefined,
+>(
+  input: DefineThemeInput<IconVariants, Base>,
+): ResolvedDefinedTheme<ThemeIconVariant<IconVariants, Base>> {
   // Pre-seed from the base theme when `extends` is provided (lowest precedence).
   // A base that is not a theme is refused rather than ignored: `extends` used
   // to inherit nothing when its value was undefined, which is what a named
@@ -601,11 +734,30 @@ export function defineTheme(input: DefineThemeInput): ResolvedDefinedTheme {
     components,
   );
 
-  // Icons — input icons override base icons
-  const icons =
-    input.icons && base?.icons
-      ? {...base.icons, ...input.icons}
-      : (input.icons ?? base?.icons);
+  // Icons — input entries override base entries by key. The base's entries
+  // include its function entries, which its node-valued `icons` does not.
+  const baseIcons = base?.__icons ?? base?.icons;
+  const iconEntries =
+    input.icons && baseIcons
+      ? {...baseIcons, ...input.icons}
+      : (input.icons ?? baseIcons);
+  const icons = readThemeIconNodes(iconEntries);
+
+  // The variant list is theme-level: a list this theme sets replaces the
+  // inherited one; an omitted list is inherited.
+  const iconVariants: ReadonlyArray<string> | undefined =
+    input.iconVariants !== undefined
+      ? [...input.iconVariants]
+      : base?.iconVariants;
+
+  // An inherited function entry keeps the list of the theme that defined it,
+  // so it receives a variant only when both lists contain it.
+  const iconEntryVariants = resolveIconEntryVariants(
+    iconEntries,
+    input.icons,
+    base,
+    iconVariants,
+  );
 
   // Indicator overrides merge by name, like icons: a child theme replacing one
   // indicator keeps the ones its base replaced.
@@ -626,6 +778,11 @@ export function defineTheme(input: DefineThemeInput): ResolvedDefinedTheme {
       : {}),
     components,
     icons,
+    ...(icons !== iconEntries ? {__icons: iconEntries} : {}),
+    ...(iconVariants !== undefined ? {iconVariants} : {}),
+    ...(iconEntryVariants !== undefined
+      ? {__iconEntryVariants: iconEntryVariants}
+      : {}),
     indicators,
     __inputTokens:
       base?.__inputTokens || input.tokens
@@ -642,6 +799,61 @@ export function defineTheme(input: DefineThemeInput): ResolvedDefinedTheme {
   return theme;
 }
 
+/**
+ * For each function entry this theme inherits, the variant list of the theme
+ * that defined it, where that list is not this theme's own. Entries this theme
+ * defines use its own list, so they need no record.
+ */
+function resolveIconEntryVariants(
+  entries: ThemeIconEntries<never> | undefined,
+  ownEntries: Readonly<Record<string, unknown>> | undefined,
+  base: DefinedTheme | undefined,
+  iconVariants: ReadonlyArray<string> | undefined,
+): Record<string, ReadonlyArray<string> | undefined> | undefined {
+  if (entries == null || base == null) {
+    return undefined;
+  }
+  const baseRecord = base.__iconEntryVariants;
+  let record: Record<string, ReadonlyArray<string> | undefined> | undefined;
+  for (const [name, entry] of Object.entries(entries)) {
+    if (
+      typeof entry !== 'function' ||
+      (ownEntries != null && Object.hasOwn(ownEntries, name))
+    ) {
+      continue;
+    }
+    const definingVariants =
+      baseRecord != null && Object.hasOwn(baseRecord, name)
+        ? baseRecord[name]
+        : base.iconVariants;
+    if (definingVariants !== iconVariants) {
+      record ??= {};
+      record[name] = definingVariants;
+    }
+  }
+  return record;
+}
+
+/**
+ * The node-valued view of a theme's icon entries: each function entry read at
+ * `{size: 'md'}`. Entries without a function are returned as the same object.
+ */
+function readThemeIconNodes(
+  entries: ThemeIconEntries<never> | undefined,
+): ThemeIconOverrides | undefined {
+  if (
+    entries == null ||
+    !Object.values(entries).some(entry => typeof entry === 'function')
+  ) {
+    return entries as ThemeIconOverrides | undefined;
+  }
+  const nodes: Record<string, ReactNode> = {};
+  for (const [name, entry] of Object.entries(entries)) {
+    nodes[name] = typeof entry === 'function' ? entry({size: 'md'}) : entry;
+  }
+  return nodes as ThemeIconOverrides;
+}
+
 // =============================================================================
 // CSS generation — re-exported from ./generateThemeRules.ts
 // =============================================================================

package/src/theme/derivedVarRegistry.test.ts

@@ -86,11 +86,26 @@ const STRUCTURAL_VARS = new Set([
   // replays on pinned cells. Structural/runtime, not themeable design tokens.
   '--table-sticky-background',
   '--table-row-overlay',
+  // The width a cell's row divider draws (0 on the last row), which a pinned
+  // cell's or a detail panel's own divider reads (Table/rowDivider.ts).
+  // Private runtime plumbing, never authored by a theme.
+  '--_table-row-divider-width',
+  // A gliding row's divider, carried on the row for the glide
+  // (Table/glidingDivider.ts). Private runtime plumbing.
+  '--_table-row-glide-width',
+  '--_table-row-glide-style',
+  '--_table-row-glide-color',
+  '--_table-row-glide-offset',
   '--separator-display',
   '--astryx-section-padding',
   // Private counterpart of the public token above: one ancestor Section's
   // padding, propagated down the tree. Structural, never authored by a theme.
   '--_section-padding-propagated',
+  // Layout's middle row tells LayoutContent that a divider-less header or
+  // footer sits beside it (Layout/layoutEdges.stylex.ts). Structural, never
+  // authored by a theme.
+  '--_layout-flush-block-start',
+  '--_layout-flush-block-end',
 ]);
 
 /**
@@ -228,6 +243,7 @@ const DIR_TO_REGISTRY_KEY: Record<string, string> = {
   DropdownMenu: 'dropdown-menu',
   Field: 'field',
   HoverCard: 'hover-card',
+  Icon: 'icon',
   Item: 'item',
   NumberInput: 'number-input',
   Popover: 'popover',
@@ -292,12 +308,11 @@ const VARS_WITHOUT_DERIVED_MAPPING = new Set([
   // properties a theme author sets on the component.
   '--_thumbnail-hit-inset',
   '--_input-clear-hit-inset',
-  // The interaction overlay's fill and its transition on the ::after layer of
-  // the cards: written by the component's own hover / pressed arms (mouse
-  // `:active`, touch `data-astryx-press`), never a value a theme author sets; the
-  // overlay colours themselves are the shared interaction tokens.
+  // The interaction overlay's colour on the ::after layer of the cards:
+  // written by the component's own hover and mouse `:active` arms, never a
+  // value a theme author sets; the overlay colours themselves are the shared
+  // interaction tokens.
   '--_press-overlay',
-  '--_press-overlay-transition',
   // The touch press's paint at its current strength, declared once by the
   // shared overlay styles on the element the controller writes to and read
   // by whatever paints it. A theme sets `--color-overlay-pressed`, not this.
@@ -497,6 +512,20 @@ describe('getDerivedVars', () => {
     expect(result[0].replaces).toBe(true);
   });
 
+  it('marks icon width and height as replacing the source property', () => {
+    // spec:AST-087 FR10: the glyph reads these vars for its dimension, so a
+    // raw width/height beside them would only compete with its size styles.
+    for (const [property, varName] of [
+      ['width', '--_icon-width'],
+      ['height', '--_icon-height'],
+    ]) {
+      const result = getDerivedVars('icon', property);
+      expect(result).toHaveLength(1);
+      expect(result[0].vars).toEqual([varName]);
+      expect(result[0].replaces).toBe(true);
+    }
+  });
+
   it('marks progress-bar-mark width and height as replacing the source property', () => {
     for (const [property, varName] of [
       ['width', '--_progressbar-mark-width'],

package/src/theme/derivedVarRegistry.ts

@@ -70,6 +70,10 @@ export const derivedVarRegistry: Record<string, DerivedVarEntry[]> = {
   ],
   field: [{property: 'borderRadius', vars: ['--_field-radius']}],
   'hover-card': [{property: 'borderRadius', vars: ['--_hovercard-radius']}],
+  icon: [
+    {property: 'width', vars: ['--_icon-width'], replaces: true},
+    {property: 'height', vars: ['--_icon-height'], replaces: true},
+  ],
   item: [{property: 'paddingInline', vars: ['--_item-inset-inline']}],
   'number-input': [
     {property: 'padding', expand: 'container'},

package/src/theme/expandMotionScale.test.ts

@@ -1,5 +1,7 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
+import fs from 'node:fs';
+import path from 'node:path';
 import {describe, it, expect} from 'vitest';
 import {expandMotionScale} from './expandMotionScale';
 
@@ -126,3 +128,18 @@ describe('expandMotionScale', () => {
     expect(slow).toBeLessThan(slowMax);
   });
 });
+
+// @ts-expect-error The role-keyed theme types are not public: motion stays internal.
+import type {MotionRoleValues as _NotPublic} from '../index';
+
+describe('touch motion stays internal', () => {
+  it('exports no motion-role surface from the theme entry or the package root', () => {
+    // The package root re-exports the theme entry and nothing from motion/.
+    const read = (file: string) =>
+      fs.readFileSync(path.resolve(__dirname, file), 'utf8');
+    expect(read('../index.ts')).not.toMatch(/from '\.\/motion/);
+    expect(read('./index.ts')).not.toMatch(
+      /expandMotionRoles|motionScaleOf|MotionConfig|MotionRoleValues|MotionCurvePoints|registerMotionTable|motion\/role/,
+    );
+  });
+});

package/src/theme/extensibleAxes.test.ts

@@ -32,6 +32,11 @@
  * `TreeListVariantMap`, with a module-augmentation example in its own JSDoc,
  * while `themeProps('tree-list', {density})` never passed `variant` — so an
  * augmented variant type-checked, rendered, and could not be themed.
+ *
+ * An artwork-request axis (`ARTWORK_REQUEST_MAPS`) keeps (1) but has no
+ * styling wiring: it selects theme-supplied artwork, so its target reflects
+ * nothing and documents no visual prop (architecture:component-theming-surface
+ * INV6, INV14).
  */
 
 import {describe, it, expect} from 'vitest';
@@ -318,6 +323,20 @@ const axes = collectExtensibleAxes(files, aliases, propMaps);
 const themePropsSites = collectThemePropsSites(files);
 const docTargets = collectDocTargets(SRC_DIR);
 
+/**
+ * Maps whose axis is an artwork request, not a styling selector. Each keeps the
+ * public-map check above and is exempt from the themeProps() reflection and
+ * visualProps checks only — and must stay unreflected and undocumented as a
+ * visual prop. `Icon.variant` selects a theme's artwork; an unlisted name
+ * renders the request without a variant. `astryx theme build` keeps the same
+ * list out of component-value enrollment
+ * (packages/cli/api/theme/build/build.mjs).
+ */
+const ARTWORK_REQUEST_MAPS: ReadonlySet<string> = new Set(['IconVariantMap']);
+
+const stylingAxes = axes.filter(a => !ARTWORK_REQUEST_MAPS.has(a.mapName));
+const artworkAxes = axes.filter(a => ARTWORK_REQUEST_MAPS.has(a.mapName));
+
 /** The target a component's own name maps to, e.g. TreeList -> astryx-tree-list. */
 function ownTargets(axis: ExtensibleAxis): DocTarget[] {
   return docTargets.get(axis.dir) ?? [];
@@ -349,39 +368,65 @@ describe('extensible prop axes are reachable by a theme', () => {
     ).toEqual([]);
   });
 
-  it.each(axes.map(a => [`${a.dir}.${a.prop} (${a.mapName})`, a] as const))(
-    '%s reaches the DOM through themeProps',
-    (_label, axis) => {
-      // The axis is extensible, so a consumer can add a value we have never
-      // seen. The only way their CSS can select it is if the component
-      // reflects the prop.
-      const targets = ownTargets(axis);
-      const reflected = targets.some(t =>
-        themePropsSites.get(t.className)?.has(axis.prop),
-      );
-      expect(
-        reflected,
-        `${axis.dir} lets a theme add \`${axis.prop}\` values via ${axis.mapName}, but no ` +
-          `themeProps() call passes \`${axis.prop}\` — a custom value renders no selector, ` +
-          `so it cannot be styled. Pass it: themeProps('<target>', {${axis.prop}}).`,
-      ).toBe(true);
-    },
-  );
+  it.each(
+    stylingAxes.map(a => [`${a.dir}.${a.prop} (${a.mapName})`, a] as const),
+  )('%s reaches the DOM through themeProps', (_label, axis) => {
+    // The axis is extensible, so a consumer can add a value we have never
+    // seen. The only way their CSS can select it is if the component
+    // reflects the prop.
+    const targets = ownTargets(axis);
+    const reflected = targets.some(t =>
+      themePropsSites.get(t.className)?.has(axis.prop),
+    );
+    expect(
+      reflected,
+      `${axis.dir} lets a theme add \`${axis.prop}\` values via ${axis.mapName}, but no ` +
+        `themeProps() call passes \`${axis.prop}\` — a custom value renders no selector, ` +
+        `so it cannot be styled. Pass it: themeProps('<target>', {${axis.prop}}).`,
+    ).toBe(true);
+  });
 
-  it.each(axes.map(a => [`${a.dir}.${a.prop} (${a.mapName})`, a] as const))(
-    '%s is documented as a visual prop',
+  it.each(
+    stylingAxes.map(a => [`${a.dir}.${a.prop} (${a.mapName})`, a] as const),
+  )('%s is documented as a visual prop', (_label, axis) => {
+    // Undocumented, it is undiscoverable — and `theme build` rejects
+    // `'<target>': {'<prop>:custom': …}` as an unknown prop, because its
+    // known-prop set is built from exactly this field.
+    const targets = ownTargets(axis);
+    const documented = targets.some(t => t.visualProps.includes(axis.prop));
+    expect(
+      documented,
+      `${axis.dir} lets a theme add \`${axis.prop}\` values via ${axis.mapName}, but no ` +
+        `theming target documents \`${axis.prop}\` in visualProps — a theme author cannot ` +
+        `discover the axis, and \`astryx theme build\` warns "Unknown prop" on it.`,
+    ).toBe(true);
+  });
+});
+
+describe('artwork-request axes are exempt from styling wiring only', () => {
+  it('lists only maps that are extensible axes', () => {
+    // A stale entry would silently exempt nothing; a renamed map would leave
+    // its axis held to styling wiring it must not have.
+    expect(artworkAxes.map(a => a.mapName).sort()).toEqual(
+      [...ARTWORK_REQUEST_MAPS].sort(),
+    );
+  });
+
+  it.each(
+    artworkAxes.map(a => [`${a.dir}.${a.prop} (${a.mapName})`, a] as const),
+  )(
+    '%s is neither reflected nor documented as a visual prop',
     (_label, axis) => {
-      // Undocumented, it is undiscoverable — and `theme build` rejects
-      // `'<target>': {'<prop>:custom': …}` as an unknown prop, because its
-      // known-prop set is built from exactly this field.
+      // The axis selects artwork, so it has no styling selector.
       const targets = ownTargets(axis);
-      const documented = targets.some(t => t.visualProps.includes(axis.prop));
       expect(
-        documented,
-        `${axis.dir} lets a theme add \`${axis.prop}\` values via ${axis.mapName}, but no ` +
-          `theming target documents \`${axis.prop}\` in visualProps — a theme author cannot ` +
-          `discover the axis, and \`astryx theme build\` warns "Unknown prop" on it.`,
-      ).toBe(true);
+        targets.some(t => themePropsSites.get(t.className)?.has(axis.prop)),
+        `${axis.dir}.${axis.prop} selects artwork; no themeProps() call may reflect it.`,
+      ).toBe(false);
+      expect(
+        targets.some(t => t.visualProps.includes(axis.prop)),
+        `${axis.dir}.${axis.prop} selects artwork; no theming target may list it in visualProps.`,
+      ).toBe(false);
     },
   );
 });