@astryxdesign/core 0.7.5-canary.dae1747 → 0.7.5-canary.dc5a8cf

package/dist/Icon/Icon.d.ts

@@ -1,6 +1,7 @@
 /**
  * @file Icon.tsx
- * @input Uses ReactSVGProps, icon components or semantic icon names
+ * @input Uses ReactSVGProps, icon components or semantic icon names, and an
+ *   optional IconVariant request
  * @output Exports Icon component, IconProps, IconColor, IconSize, IconType types
  * @position Core implementation; consumed by index.ts, tested by Icon.test.tsx
  *
@@ -9,7 +10,8 @@
  *   directly with and spread SVG props.
  * - String mode: Pass a semantic name (e.g. 'close', 'chevronDown') — resolved from the
  *   theme's icon registry (or built-in fallback SVGs) and wrapped in a styled span.
- *   A function registry entry receives `{size}`, the size resolved by ORD1.
+ *   A function registry entry receives `{size, variant}`: the size resolved by
+ *   ORD1 and the requested variant when the entry can receive it.
  *
  * Both modes size the glyph from the `icon` target's private size vars
  * (`iconSizeStyles` in IconSize.stylex.ts, `registrySizeStyles` below), so a
@@ -27,6 +29,7 @@ import React, { type ComponentType, type SVGProps } from 'react';
 import * as stylex from '@stylexjs/stylex';
 import type { StyleXStyles } from '@stylexjs/stylex';
 import type { IconName, NamespacedIconName } from './globalIconRegistry.js';
+import type { IconVariant } from './index.js';
 import { type IconSize } from './IconSize.stylex.js';
 export type { IconSize } from './IconSize.stylex.js';
 declare const colorStyles: Readonly<{
@@ -131,6 +134,23 @@ export interface IconProps extends Omit<SVGProps<SVGSVGElement>, 'ref' | 'color'
      * by an owning Astryx component for its icon slot, then falls back to 'md'.
      */
     size?: IconSize;
+    /**
+     * Requests the active theme's alternate artwork for a semantic icon name,
+     * such as `'filled'`. Names come from the augmentable `IconVariantMap`.
+     *
+     * The theme's icon entry receives the variant only when the active theme
+     * lists it in `iconVariants` and, for an entry a theme supplied, the theme
+     * that defined the entry lists it too. Otherwise the entry receives
+     * `undefined` and draws its normal artwork. An icon component passed
+     * directly renders as given and never receives `variant`, and `variant` is
+     * never written to the DOM or reflected on the `icon` theming target.
+     *
+     * @example
+     * ```
+     * <Icon icon="info" variant="filled" />
+     * ```
+     */
+    variant?: IconVariant;
     /**
      * Accessible name for the icon. Set this only when the icon is MEANINGFUL on
      * its own — a standalone status glyph or an icon-only indicator with no
@@ -183,7 +203,7 @@ export interface IconProps extends Omit<SVGProps<SVGSVGElement>, 'ref' | 'color'
  * <Icon icon="close" size="md" color="primary" />
  * ```
  */
-export declare function Icon({ icon, color, size: sizeProp, label, ref, className, style, xstyle, ...props }: IconProps): React.JSX.Element;
+export declare function Icon({ icon, color, size: sizeProp, variant, label, ref, className, style, xstyle, ...props }: IconProps): React.JSX.Element;
 export declare namespace Icon {
     var displayName: string;
 }

package/dist/Icon/Icon.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Icon.d.ts","sourceRoot":"","sources":["../../src/Icon/Icon.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,KAAK,EAAE,EAAC,KAAK,aAAa,EAAE,KAAK,QAAQ,EAAC,MAAM,OAAO,CAAC;AAC/D,OAAO,KAAK,MAAM,MAAM,kBAAkB,CAAC;AAC3C,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,kBAAkB,CAAC;AAInD,OAAO,KAAK,EAAC,QAAQ,EAAE,kBAAkB,EAAC,MAAM,sBAAsB,CAAC;AAIvE,OAAO,EAAiB,KAAK,QAAQ,EAAC,MAAM,mBAAmB,CAAC;AAEhE,YAAY,EAAC,QAAQ,EAAC,MAAM,mBAAmB,CAAC;AAiDhD,QAAA,MAAM,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA8Df,CAAC;AAMH,MAAM,MAAM,SAAS,GAAG,MAAM,OAAO,WAAW,CAAC;AAEjD;;;GAGG;AACH,MAAM,MAAM,QAAQ,GAAG,aAAa,CAAC,QAAQ,CAAC,aAAa,CAAC,CAAC,CAAC;AAE9D;;;GAGG;AACH,MAAM,WAAW,SAAU,SAAQ,IAAI,CACrC,QAAQ,CAAC,aAAa,CAAC,EACvB,KAAK,GAAG,OAAO,CAChB;IACC,wCAAwC;IACxC,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC;IAC/B;;;;;;OAMG;IACH,IAAI,EAAE,QAAQ,GAAG,QAAQ,GAAG,kBAAkB,CAAC;IAC/C;;;OAGG;IACH,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB;;;;;;;;;;;;OAYG;IACH,IAAI,CAAC,EAAE,QAAQ,CAAC;IAChB;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,EAAE,YAAY,CAAC;CACvB;AAyBD;;;;;;;GAOG;AACH,wBAAgB,IAAI,CAAC,EACnB,IAAI,EACJ,KAAiB,EACjB,IAAI,EAAE,QAAQ,EACd,KAAK,EACL,GAAG,EACH,SAAS,EACT,KAAK,EACL,MAAM,EACN,GAAG,KAAK,EACT,EAAE,SAAS,qBAkDX;yBA5De,IAAI;;;AAqIpB;;;;;;GAMG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,KAAK,CAAC,SAAS,GAAG,QAAQ,EAChC,KAAK,CAAC,EAAE;IAAC,IAAI,CAAC,EAAE,QAAQ,CAAC;IAAC,KAAK,CAAC,EAAE,SAAS,CAAA;CAAC,GAC3C,KAAK,CAAC,SAAS,CAYjB"}
+{"version":3,"file":"Icon.d.ts","sourceRoot":"","sources":["../../src/Icon/Icon.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,KAAK,EAAE,EAAC,KAAK,aAAa,EAAE,KAAK,QAAQ,EAAC,MAAM,OAAO,CAAC;AAC/D,OAAO,KAAK,MAAM,MAAM,kBAAkB,CAAC;AAC3C,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,kBAAkB,CAAC;AAInD,OAAO,KAAK,EAAC,QAAQ,EAAE,kBAAkB,EAAC,MAAM,sBAAsB,CAAC;AACvE,OAAO,KAAK,EAAC,WAAW,EAAC,MAAM,SAAS,CAAC;AAIzC,OAAO,EAAiB,KAAK,QAAQ,EAAC,MAAM,mBAAmB,CAAC;AAEhE,YAAY,EAAC,QAAQ,EAAC,MAAM,mBAAmB,CAAC;AAiDhD,QAAA,MAAM,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA8Df,CAAC;AAMH,MAAM,MAAM,SAAS,GAAG,MAAM,OAAO,WAAW,CAAC;AAEjD;;;GAGG;AACH,MAAM,MAAM,QAAQ,GAAG,aAAa,CAAC,QAAQ,CAAC,aAAa,CAAC,CAAC,CAAC;AAE9D;;;GAGG;AACH,MAAM,WAAW,SAAU,SAAQ,IAAI,CACrC,QAAQ,CAAC,aAAa,CAAC,EACvB,KAAK,GAAG,OAAO,CAChB;IACC,wCAAwC;IACxC,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC;IAC/B;;;;;;OAMG;IACH,IAAI,EAAE,QAAQ,GAAG,QAAQ,GAAG,kBAAkB,CAAC;IAC/C;;;OAGG;IACH,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB;;;;;;;;;;;;OAYG;IACH,IAAI,CAAC,EAAE,QAAQ,CAAC;IAChB;;;;;;;;;;;;;;;OAeG;IACH,OAAO,CAAC,EAAE,WAAW,CAAC;IACtB;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,EAAE,YAAY,CAAC;CACvB;AAyBD;;;;;;;GAOG;AACH,wBAAgB,IAAI,CAAC,EACnB,IAAI,EACJ,KAAiB,EACjB,IAAI,EAAE,QAAQ,EACd,OAAO,EACP,KAAK,EACL,GAAG,EACH,SAAS,EACT,KAAK,EACL,MAAM,EACN,GAAG,KAAK,EACT,EAAE,SAAS,qBAoDX;yBA/De,IAAI;;;AA2IpB;;;;;;GAMG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,KAAK,CAAC,SAAS,GAAG,QAAQ,EAChC,KAAK,CAAC,EAAE;IAAC,IAAI,CAAC,EAAE,QAAQ,CAAC;IAAC,KAAK,CAAC,EAAE,SAAS,CAAA;CAAC,GAC3C,KAAK,CAAC,SAAS,CAYjB"}

package/dist/Icon/Icon.js

@@ -4,7 +4,8 @@
 
 /**
  * @file Icon.tsx
- * @input Uses ReactSVGProps, icon components or semantic icon names
+ * @input Uses ReactSVGProps, icon components or semantic icon names, and an
+ *   optional IconVariant request
  * @output Exports Icon component, IconProps, IconColor, IconSize, IconType types
  * @position Core implementation; consumed by index.ts, tested by Icon.test.tsx
  *
@@ -13,7 +14,8 @@
  *   directly with and spread SVG props.
  * - String mode: Pass a semantic name (e.g. 'close', 'chevronDown') — resolved from the
  *   theme's icon registry (or built-in fallback SVGs) and wrapped in a styled span.
- *   A function registry entry receives `{size}`, the size resolved by ORD1.
+ *   A function registry entry receives `{size, variant}`: the size resolved by
+ *   ORD1 and the requested variant when the entry can receive it.
  *
  * Both modes size the glyph from the `icon` target's private size vars
  * (`iconSizeStyles` in IconSize.stylex.ts, `registrySizeStyles` below), so a
@@ -222,6 +224,7 @@ export function Icon({
   icon,
   color = 'inherit',
   size: sizeProp,
+  variant,
   label,
   ref,
   className,
@@ -240,6 +243,7 @@ export function Icon({
       name: icon,
       color: color,
       size: size,
+      variant: variant,
       a11yProps: a11yProps,
       className: className,
       style: style,
@@ -248,7 +252,8 @@ export function Icon({
     });
   }
 
-  // Component mode: render SVG component directly with ref forwarding
+  // Component mode: render SVG component directly with ref forwarding. A
+  // supplied component never receives `variant`; it was destructured above.
   const IconComponent = icon;
   return /*#__PURE__*/_jsx(IconComponent, {
     ref: ref
@@ -275,12 +280,14 @@ Icon.displayName = 'Icon';
  * and renders it in a styled span with proper sizing.
  *
  * Extracted as a separate component so the registry is only read when the
- * icon prop is a string. A function entry receives the resolved size.
+ * icon prop is a string. A function entry receives the resolved size and the
+ * requested variant when the entry can receive it.
  */
 function IconFromRegistry({
   name,
   color,
   size,
+  variant,
   a11yProps,
   className,
   style,
@@ -289,7 +296,8 @@ function IconFromRegistry({
 }) {
   const themeName = useThemeName();
   const resolvedIcon = resolveIcon(name, themeName, {
-    size
+    size,
+    variant
   });
   if (resolvedIcon == null) {
     return null;

package/dist/Icon/globalIconRegistry.d.ts

@@ -14,7 +14,9 @@
  * {@link IconRequest}. Resolution picks one source — theme entry, then
  * process-wide registration, then built-in default; a nullish static entry
  * falls through — and a selected function's result is final. `Icon` passes
- * its resolved size; the public reads below pass `{size: 'md'}`.
+ * its resolved size and a variant the entry can receive (listed by the active
+ * theme and, for a theme entry, by the theme that defined it), otherwise
+ * `undefined`; the public reads below pass `{size: 'md'}`.
  */
 import type { ReactNode } from 'react';
 import type { IconSize } from './IconSize.stylex.js';
@@ -89,10 +91,11 @@ export type IconEntry<Variant extends string = IconVariant> = ReactNode | ((requ
 export type IconRegistrySource = DefinedTheme | string | null | undefined;
 /**
  * Resolve a key for an Icon request. `Icon` is the caller: it passes the size
- * it resolved. Public reads use {@link getIcon} instead.
+ * it resolved and the variant it was asked for. Public reads use
+ * {@link getIcon} instead.
  * @internal
  */
-export declare function resolveIcon(name: ExtendedIconName, source: IconRegistrySource, request: IconRequest<never>): ReactNode;
+export declare function resolveIcon(name: ExtendedIconName, source: IconRegistrySource, request: IconRequest<string>): ReactNode;
 /**
  * Register icons at the module level. Works in both server and client
  * environments. Call once at app initialization (e.g. root layout).

package/dist/Icon/globalIconRegistry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"globalIconRegistry.d.ts","sourceRoot":"","sources":["../../src/Icon/globalIconRegistry.tsx"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,OAAO,CAAC;AAErC,OAAO,KAAK,EAAC,QAAQ,EAAC,MAAM,mBAAmB,CAAC;AAChD,OAAO,KAAK,EAAC,WAAW,EAAC,MAAM,SAAS,CAAC;AACzC,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,sBAAsB,CAAC;AAQvD;;;;;GAKG;AAEH,MAAM,MAAM,QAAQ,GAChB,OAAO,GACP,aAAa,GACb,aAAa,GACb,cAAc,GACd,cAAc,GACd,eAAe,GACf,OAAO,GACP,SAAS,GACT,OAAO,GACP,SAAS,GACT,MAAM,GACN,UAAU,GACV,OAAO,GACP,cAAc,GACd,MAAM,GACN,gBAAgB,GAChB,QAAQ,GACR,QAAQ,GACR,SAAS,GACT,WAAW,GACX,cAAc,GACd,QAAQ,GACR,UAAU,GACV,aAAa,GACb,MAAM,GACN,aAAa,GACb,QAAQ,GACR,MAAM,GACN,YAAY,CAAC;AAEjB;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,kBAAkB,GAAG,GAAG,MAAM,IAAI,MAAM,EAAE,CAAC;AAEvD;;;;;;;;GAQG;AACH,MAAM,MAAM,gBAAgB,GAAG,QAAQ,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;AAExD;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC;AAEvD;;;;;;;GAOG;AACH,MAAM,MAAM,WAAW,CAAC,OAAO,SAAS,MAAM,GAAG,WAAW,IAAI,QAAQ,CAAC;IACvE,IAAI,EAAE,QAAQ,CAAC;IACf,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB,CAAC,CAAC;AAEH;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,MAAM,SAAS,CAAC,OAAO,SAAS,MAAM,GAAG,WAAW,IACxD,SAAS,GAAG,CAAC,CAAC,OAAO,EAAE,WAAW,CAAC,OAAO,CAAC,KAAK,SAAS,CAAC,CAAC;AAQ7D,MAAM,MAAM,kBAAkB,GAAG,YAAY,GAAG,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;AAgE1E;;;;GAIG;AACH,wBAAgB,WAAW,CACzB,IAAI,EAAE,gBAAgB,EACtB,MAAM,EAAE,kBAAkB,EAC1B,OAAO,EAAE,WAAW,CAAC,KAAK,CAAC,GAC1B,SAAS,CAEX;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,aAAa,CAC3B,KAAK,EAAE,OAAO,CAAC,MAAM,CAAC,gBAAgB,EAAE,SAAS,CAAC,CAAC,GAClD,IAAI,CAON;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAC7B,MAAM,CAAC,EAAE,kBAAkB,GAC1B,QAAQ,CAAC,MAAM,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC,CAsBvC;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,OAAO,CACrB,IAAI,EAAE,gBAAgB,EACtB,MAAM,CAAC,EAAE,kBAAkB,GAC1B,SAAS,CAEX;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,gBAAgB,EACtB,QAAQ,CAAC,EAAE,SAAS,EACpB,MAAM,CAAC,EAAE,kBAAkB,GAC1B,SAAS,CAKX;AAED;;;GAGG;AACH,wBAAgB,UAAU,IAAI,IAAI,CAEjC"}
+{"version":3,"file":"globalIconRegistry.d.ts","sourceRoot":"","sources":["../../src/Icon/globalIconRegistry.tsx"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,OAAO,CAAC;AAErC,OAAO,KAAK,EAAC,QAAQ,EAAC,MAAM,mBAAmB,CAAC;AAChD,OAAO,KAAK,EAAC,WAAW,EAAC,MAAM,SAAS,CAAC;AACzC,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,sBAAsB,CAAC;AAQvD;;;;;GAKG;AAEH,MAAM,MAAM,QAAQ,GAChB,OAAO,GACP,aAAa,GACb,aAAa,GACb,cAAc,GACd,cAAc,GACd,eAAe,GACf,OAAO,GACP,SAAS,GACT,OAAO,GACP,SAAS,GACT,MAAM,GACN,UAAU,GACV,OAAO,GACP,cAAc,GACd,MAAM,GACN,gBAAgB,GAChB,QAAQ,GACR,QAAQ,GACR,SAAS,GACT,WAAW,GACX,cAAc,GACd,QAAQ,GACR,UAAU,GACV,aAAa,GACb,MAAM,GACN,aAAa,GACb,QAAQ,GACR,MAAM,GACN,YAAY,CAAC;AAEjB;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,kBAAkB,GAAG,GAAG,MAAM,IAAI,MAAM,EAAE,CAAC;AAEvD;;;;;;;;GAQG;AACH,MAAM,MAAM,gBAAgB,GAAG,QAAQ,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;AAExD;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC;AAEvD;;;;;;;GAOG;AACH,MAAM,MAAM,WAAW,CAAC,OAAO,SAAS,MAAM,GAAG,WAAW,IAAI,QAAQ,CAAC;IACvE,IAAI,EAAE,QAAQ,CAAC;IACf,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB,CAAC,CAAC;AAEH;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,MAAM,SAAS,CAAC,OAAO,SAAS,MAAM,GAAG,WAAW,IACxD,SAAS,GAAG,CAAC,CAAC,OAAO,EAAE,WAAW,CAAC,OAAO,CAAC,KAAK,SAAS,CAAC,CAAC;AAQ7D,MAAM,MAAM,kBAAkB,GAAG,YAAY,GAAG,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;AA4G1E;;;;;GAKG;AACH,wBAAgB,WAAW,CACzB,IAAI,EAAE,gBAAgB,EACtB,MAAM,EAAE,kBAAkB,EAC1B,OAAO,EAAE,WAAW,CAAC,MAAM,CAAC,GAC3B,SAAS,CAEX;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,aAAa,CAC3B,KAAK,EAAE,OAAO,CAAC,MAAM,CAAC,gBAAgB,EAAE,SAAS,CAAC,CAAC,GAClD,IAAI,CAON;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAC7B,MAAM,CAAC,EAAE,kBAAkB,GAC1B,QAAQ,CAAC,MAAM,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC,CAsBvC;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,OAAO,CACrB,IAAI,EAAE,gBAAgB,EACtB,MAAM,CAAC,EAAE,kBAAkB,GAC1B,SAAS,CAEX;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,gBAAgB,EACtB,QAAQ,CAAC,EAAE,SAAS,EACpB,MAAM,CAAC,EAAE,kBAAkB,GAC1B,SAAS,CAKX;AAED;;;GAGG;AACH,wBAAgB,UAAU,IAAI,IAAI,CAEjC"}

package/dist/Icon/globalIconRegistry.js

@@ -16,7 +16,9 @@
  * {@link IconRequest}. Resolution picks one source — theme entry, then
  * process-wide registration, then built-in default; a nullish static entry
  * falls through — and a selected function's result is final. `Icon` passes
- * its resolved size; the public reads below pass `{size: 'md'}`.
+ * its resolved size and a variant the entry can receive (listed by the active
+ * theme and, for a theme entry, by the theme that defined it), otherwise
+ * `undefined`; the public reads below pass `{size: 'md'}`.
  */
 
 import { defaultIcons } from "./defaultIcons.js";
@@ -116,38 +118,92 @@ let globalRegistry = {};
 function isNamespacedKey(name) {
   return name.includes(':');
 }
+function getTheme(source) {
+  return typeof source === 'string' ? getRegisteredTheme(source) : source ?? null;
+}
 
 /**
  * The theme's icon entries, functions included. A theme from `defineTheme`
  * keeps them in `__icons` when any entry is a function (its public `icons`
  * is the node view); otherwise `icons` already holds them.
  */
-function getThemeIconEntries(source) {
-  const theme = typeof source === 'string' ? getRegisteredTheme(source) : source;
+function getThemeIconEntries(theme) {
   if (theme == null) {
     return null;
   }
   return theme.__icons ?? theme.icons ?? null;
 }
 
+/**
+ * The selected entry, with every variant list a requested variant must be in
+ * for the entry to receive it. No lists: the entry receives no variant.
+ */
+
 /**
  * Pick the one source that answers `name`: the theme entry, then the
  * process-wide registration, then the built-in default, then `fallback`. A
  * nullish static entry falls through; a function is returned as-is, because
  * its result is final.
+ *
+ * A theme entry may receive a variant listed by the active theme and by the
+ * theme that defined the entry (an inherited entry keeps its defining
+ * theme's list). A process-wide registration may receive a variant the
+ * active theme lists.
  */
 function selectIconEntry(name, source, fallback) {
-  return getThemeIconEntries(source)?.[name] ?? globalRegistry[name] ?? defaultIcons[name] ?? fallback;
+  const theme = getTheme(source);
+  const activeVariants = theme?.iconVariants;
+  const themeEntry = getThemeIconEntries(theme)?.[name];
+  if (theme != null && themeEntry != null) {
+    const definingVariants = theme.__iconEntryVariants != null && Object.hasOwn(theme.__iconEntryVariants, name) ? theme.__iconEntryVariants[name] : activeVariants;
+    return {
+      entry: themeEntry,
+      variantLists: [activeVariants, definingVariants]
+    };
+  }
+  const globalEntry = globalRegistry[name];
+  if (globalEntry != null) {
+    return {
+      entry: globalEntry,
+      variantLists: [activeVariants]
+    };
+  }
+  return {
+    entry: defaultIcons[name] ?? fallback,
+    variantLists: []
+  };
 }
 
-/** Read an entry for a request: call a function, return a node as-is. */
-function readIconEntry(entry, request) {
-  return typeof entry === 'function' ? entry(request) : entry;
+/**
+ * Read a selected entry for a request: call a function, return a node as-is.
+ * The function receives the requested variant only when every list of the
+ * selection contains it; otherwise it receives `undefined`.
+ */
+function readIconEntry({
+  entry,
+  variantLists
+}, {
+  size,
+  variant
+}) {
+  if (typeof entry !== 'function') {
+    return entry;
+  }
+  const receivable = variant !== undefined && variantLists.length > 0 && variantLists.every(list => list?.includes(variant) === true);
+  // A receivable variant is one the entry's theme lists, which is the type
+  // the entry was written against.
+  return entry(receivable ? {
+    size,
+    variant
+  } : {
+    size
+  });
 }
 
 /**
  * Resolve a key for an Icon request. `Icon` is the caller: it passes the size
- * it resolved. Public reads use {@link getIcon} instead.
+ * it resolved and the variant it was asked for. Public reads use
+ * {@link getIcon} instead.
  * @internal
  */
 export function resolveIcon(name, source, request) {
@@ -211,7 +267,7 @@ export function getIconRegistry(source) {
   // resolved via getIcon/getExtendedIcon and intentionally kept out of the
   // typed IconRegistry snapshot.
   const names = new Set(Object.keys(defaultIcons));
-  for (const name of Object.keys(getThemeIconEntries(source) ?? {})) {
+  for (const name of Object.keys(getThemeIconEntries(getTheme(source)) ?? {})) {
     names.add(name);
   }
   for (const name of names) {

package/dist/motion/animatedLayout.d.ts

@@ -80,6 +80,81 @@ export declare function holdLayoutExit(handle: AnimatedLayout | null | undefined
  * mid-exit.
  */
 export declare function releaseLayoutExit(element: HTMLElement): void;
+/**
+ * Old content held as one transient copy while new content enters in its
+ * place (`spec:AST-105` FR8): inert, hidden from assistive technology, and
+ * removed when the swap ends (`architecture:component-style-authoring` INV7).
+ */
+export interface LayoutSwap {
+    readonly area: Element;
+    readonly copy: HTMLElement;
+    /** Where the old content showed, in viewport coordinates. */
+    readonly rect: DOMRect;
+}
+/** How far a ridden element has moved since the swap began. */
+export interface LayoutRide {
+    readonly x: number;
+    readonly y: number;
+}
+/**
+ * How a swap plays, as frames over its progress (0 → 1) and, with
+ * `rideWith`, the ridden element's travel so far.
+ */
+export interface LayoutSwapMotion {
+    /** The box the copy is laid out in, over the old content's place. */
+    readonly host: Element;
+    /** The copy's frames while it travels. */
+    readonly copy: (p: number, ride: LayoutRide) => Keyframe;
+    /** Its text's opacity, on its own curve, when that differs from the copy's. */
+    readonly copyText?: (p: number) => number;
+    /** The copy paints above its neighbours, in the background it shows. */
+    readonly isOpaque?: boolean;
+    /**
+     * An element the glide moves, such as the column the old content sat in.
+     * Every part plays over its glide, frame by frame, and is told how far it
+     * has moved; the copy rides it unless `isCopyMoved` is false. Without a
+     * glide (it lands silently) the ride is the whole `travel` at once (its
+     * old place less its new).
+     */
+    readonly rideWith?: {
+        readonly element: Element;
+        readonly travel: LayoutRide;
+        readonly isCopyMoved?: boolean;
+    };
+    /** Called once when the swap ends, however it ends. */
+    readonly onEnd?: () => void;
+    /** Elements the page already renders, entering with the swap. */
+    readonly incoming: ReadonlyArray<{
+        readonly element: Element;
+        readonly frames: (p: number, ride: LayoutRide) => Keyframe;
+    }>;
+}
+/**
+ * Before a change commits: hold `element`'s old content as one transient copy
+ * (`spec:AST-105` FR8). With `isVisiblePart`, the copy is the element's
+ * visible part, its content scrolled as it was (a scroll container). Returns
+ * null without a handle, outside its area, under an immediate change, or for
+ * content too large to copy.
+ */
+export declare function holdLayoutSwap(handle: AnimatedLayout | null | undefined, element: HTMLElement, { isVisiblePart }?: {
+    isVisiblePart?: boolean;
+}): LayoutSwap | null;
+/**
+ * After the change commits, before paint: the copy leaves while the incoming
+ * elements enter, on FR4's one motion, every part started on the same
+ * timeline time. Under Reduce Motion with a coarse pointer, only opacity
+ * changes (`design:reduced-motion` DR2). Returns what ends the swap at once;
+ * it also ends when its motion does, and the copy is removed.
+ */
+export declare function playLayoutSwap(swap: LayoutSwap, how: LayoutSwapMotion): () => void;
+/**
+ * After a change commits, before paint: elements the page already renders
+ * play frames over the change's progress on FR4's one motion, with no copy,
+ * such as a surface reaching over a gap a glide opens. Under Reduce Motion
+ * with a coarse pointer, only opacity changes; under an immediate change,
+ * nothing plays. Returns what ends them at once.
+ */
+export declare function playLayoutFrames(handle: AnimatedLayout | null | undefined, parts: LayoutSwapMotion['incoming']): () => void;
 /**
  * A disclosure's indicator (its chevron) turns on the same motion as the
  * glide: its CSS transition takes the spring as a `linear()` easing, and an

package/dist/motion/animatedLayout.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"animatedLayout.d.ts","sourceRoot":"","sources":["../../src/motion/animatedLayout.ts"],"names":[],"mappings":"AAmEA,sDAAsD;AACtD,KAAK,YAAY,GACb;IAAC,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,cAAc,CAAA;CAAC,GAC5D;IACE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB,GACD;IAAC,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAA;CAAC,CAAC;AAE/B,yEAAyE;AACzE,UAAU,cAAc;IACtB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,gDAAgD;IAChD,SAAS,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;CAC9B;AAmLD,QAAA,MAAM,IAAI,eAAuC,CAAC;AAElD;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,CAAC,IAAI,CAAC,EAAE,MAAM,OAAO,GAAG,IAAI,CAAC;CACvC;AAED,6EAA6E;AAC7E,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,MAAM,OAAO,GAAG,IAAI,GACzB,cAAc,CAKhB;AA6SD,KAAK,MAAM,GAAG;IAAC,QAAQ,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAAA;CAAC,GAAG,CAAC,MAAM,OAAO,GAAG,IAAI,CAAC,CAAC;AAM1E,MAAM,WAAW,YAAY;IAC3B,uEAAuE;IACvE,aAAa,IAAI,IAAI,CAAC;IACtB;;;;OAIG;IACH,OAAO,IAAI,OAAO,CAAC;CACpB;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,cAAc,GAAG,IAAI,GAAG,SAAS,EACzC,MAAM,EAAE,MAAM,GACb,YAAY,CAqCd;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,cAAc,GAAG,IAAI,GAAG,SAAS,EACzC,OAAO,EAAE,OAAO,GACf,IAAI,CA8BN;AA2JD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,cAAc,CAC5B,MAAM,EAAE,cAAc,GAAG,IAAI,GAAG,SAAS,EACzC,OAAO,EAAE,WAAW,EACpB,IAAI,EAAE,MAAM,IAAI,GACf,OAAO,CAoFT;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,WAAW,GAAG,IAAI,CAkB5D;AAED;;;;;;GAMG;AACH,wBAAgB,2BAA2B,CACzC,MAAM,EAAE,cAAc,GAAG,IAAI,GAAG,SAAS,EACzC,OAAO,EAAE,WAAW,GAAG,UAAU,GAAG,IAAI,GACvC,IAAI,CAwBN;AAED,gEAAgE;AAChE,wBAAgB,eAAe,CAAC,IAAI,EAAE,OAAO,GAAG,YAAY,CAE3D"}
+{"version":3,"file":"animatedLayout.d.ts","sourceRoot":"","sources":["../../src/motion/animatedLayout.ts"],"names":[],"mappings":"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"}