@astryxdesign/core 0.7.5-canary.fccd771 → 0.7.5

package/dist/FileInput/FileInput.js

@@ -4,7 +4,7 @@
 
 /**
  * @file FileInput.tsx
- * @input Uses React, useId, Field, Icon, Spinner, VisuallyHidden
+ * @input Uses React, useId, Field, Icon, Spinner, VisuallyHidden, provider-bound translator
  * @output Exports FileInput component, public types, and its root/icon theme targets
  * @position Core implementation; consumed by index.ts, tested by FileInput.test.tsx
  *
@@ -34,14 +34,20 @@ import { themeProps } from "../utils/themeProps.js";
 import { useTranslator } from "../i18n/index.js";
 import { useMergedRefs } from "../hooks/useMergedRefs.js";
 import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
-function formatFileSize(bytes) {
+function formatFileSize(bytes, t) {
   if (bytes < 1024) {
-    return `${bytes} B`;
+    return t('@astryx.fileInput.fileSize.bytes', {
+      size: bytes
+    });
   }
   if (bytes < 1024 * 1024) {
-    return `${(bytes / 1024).toFixed(1)} KB`;
+    return t('@astryx.fileInput.fileSize.kilobytes', {
+      size: bytes / 1024
+    });
   }
-  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+  return t('@astryx.fileInput.fileSize.megabytes', {
+    size: bytes / (1024 * 1024)
+  });
 }
 function validateFiles(files, accept, maxSize, maxFiles, isMultiple, t) {
   const errors = [];
@@ -71,7 +77,7 @@ function validateFiles(files, accept, maxSize, maxFiles, isMultiple, t) {
       if (file.size > maxSize) {
         errors.push(t('@astryx.fileInput.errorMaxSize', {
           fileName: file.name,
-          maxSize: formatFileSize(maxSize)
+          maxSize: formatFileSize(maxSize, t)
         }));
         return false;
       }
@@ -160,15 +166,15 @@ const styles = {
 };
 const statusBorderStyles = {
   warning: {
-    kVAM5u: "x8wg1ba",
+    kVAM5u: "xrwcrn0",
     $$css: true
   },
   error: {
-    kVAM5u: "x1ofxpqo",
+    kVAM5u: "xw4o254",
     $$css: true
   },
   success: {
-    kVAM5u: "x16m2moy",
+    kVAM5u: "x1cu78b5",
     $$css: true
   }
 };
@@ -227,6 +233,7 @@ export function FileInput({
   const statusMessageID = useId();
   const requiredID = useId();
   const inputRef = useRef(null);
+  const triggerRef = useRef(null);
   const containerRef = useRef(null);
   const [isDragOver, setIsDragOver] = useState(false);
   const [validationError, setValidationError] = useState(null);
@@ -343,14 +350,16 @@ export function FileInput({
     }
     if (inputRef.current) {
       inputRef.current.value = '';
-      const targetInput = inputRef.current;
+      // Focus returns to the trigger button, the control a person operates;
+      // the native input is aria-hidden and outside the tab order.
+      const trigger = triggerRef.current;
       if (e.detail === 0) {
-        targetInput.focus();
+        trigger?.focus();
       } else {
         // Defer focus restoration past the button's unmount task so iOS Safari
         // and touch browsers don't jump the page scroll to 0 on tap.
         requestAnimationFrame(() => {
-          targetInput.focus({
+          trigger?.focus({
             preventScroll: true
           });
         });
@@ -539,6 +548,7 @@ export function FileInput({
       }), stylex.props(isDropzone ? styles.dropzone : styles.compact, isDropzone && !isDisabled && styles.dropzoneHover, isDropzone && isDragOver && styles.dropzoneActive, isDropzone && isDisabled && styles.dropzoneDisabled, !isDropzone && isDisabled && styles.compactDisabled, status && statusBorderStyles[status.type], controlXstyle), controlClassName, controlStyle),
       children: [/*#__PURE__*/_jsx(VisuallyHidden, {
         children: /*#__PURE__*/_jsx("button", {
+          ref: triggerRef,
           type: "button"
           // A disabled trigger keeps its Tab stop (spec:AST-085 FR1).
           ,

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,6 +10,13 @@
  *   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, 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
+ * theme's `width` and `height` on that target's size selector set the size's
+ * glyph dimension, including the font size 1em-based registry artwork follows.
  *
  * SYNC: When modified, update these files to stay in sync:
  * - /packages/core/src/Icon/Icon.doc.mjs (props table, features, implementation notes)
@@ -21,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<{
@@ -39,14 +48,17 @@ declare const colorStyles: Readonly<{
     readonly accent: Readonly<{
         readonly color: stylex.StyleXClassNameFor<"color", "light-dark(#0064E0, #2694FE)">;
     }>;
+    readonly info: Readonly<{
+        readonly color: stylex.StyleXClassNameFor<"color", "var(--color-text-info)">;
+    }>;
     readonly success: Readonly<{
-        readonly color: stylex.StyleXClassNameFor<"color", "light-dark(#0D8626, #0D8626)">;
+        readonly color: stylex.StyleXClassNameFor<"color", "var(--color-text-success)">;
     }>;
     readonly error: Readonly<{
-        readonly color: stylex.StyleXClassNameFor<"color", "light-dark(#E3193B, #F5394F)">;
+        readonly color: stylex.StyleXClassNameFor<"color", "var(--color-text-error)">;
     }>;
     readonly warning: Readonly<{
-        readonly color: stylex.StyleXClassNameFor<"color", "light-dark(#E9AF08, #F2C00B)">;
+        readonly color: stylex.StyleXClassNameFor<"color", "var(--color-text-warning)">;
     }>;
     readonly inherit: Readonly<{
         readonly color: stylex.StyleXClassNameFor<"color", "inherit">;
@@ -115,10 +127,30 @@ export interface IconProps extends Omit<SVGProps<SVGSVGElement>, 'ref' | 'color'
      * - 'md': 1.25rem (20px at a 16px root)
      * - 'lg': 1.5rem (24px at a 16px root)
      *
+     * A theme sets a size's glyph dimension with `width` and `height`, in `px`
+     * or `rem`, on `components.icon['size:sm']` (and the other sizes).
+     *
      * An explicit value wins. When omitted, Icon uses the nearest default supplied
      * 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
@@ -171,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;;;;;;;;;;;;;;;;;;GAkBG;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,EAGL,KAAK,QAAQ,EACd,MAAM,mBAAmB,CAAC;AAE3B,YAAY,EAAC,QAAQ,EAAC,MAAM,mBAAmB,CAAC;AAmBhD,QAAA,MAAM,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA2Df,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;;;;;;;;;OASG;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,6 +14,13 @@
  *   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, 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
+ * theme's `width` and `height` on that target's size selector set the size's
+ * glyph dimension, including the font size 1em-based registry artwork follows.
  *
  * SYNC: When modified, update these files to stay in sync:
  * - /packages/core/src/Icon/Icon.doc.mjs (props table, features, implementation notes)
@@ -26,11 +34,11 @@ import * as stylex from '@stylexjs/stylex';
 import "../theme/tokens.stylex.js";
 import { colorVars } from "../theme/tokens.stylex.js";
 import { useThemeName } from "../theme/useTheme.js";
-import { getIcon } from "./globalIconRegistry.js";
+import { resolveIcon } from "./globalIconRegistry.js";
 import { mergeProps } from "../utils/index.js";
 import { themeProps } from "../utils/themeProps.js";
 import { useIconSize } from "./IconDefaultSizeContext.js";
-import { iconBoxSizeStyles, iconSizeStyles } from "./IconSize.stylex.js";
+import { iconSizeStyles } from "./IconSize.stylex.js";
 import { jsx as _jsx } from "react/jsx-runtime";
 // =============================================================================
 // Styles
@@ -49,6 +57,40 @@ const styles = {
     $$css: true
   }
 };
+
+/**
+ * Size styles for string-based registry icons: the glyph dimensions
+ * `iconSizeStyles` reads from the `icon` target's private vars, plus a
+ * `fontSize`, because registry artwork is 1em-based. `fontSize` is the smaller
+ * side, which fits square artwork into a non-square box the way an SVG viewBox
+ * does.
+ */
+const registrySizeStyles = {
+  xsm: {
+    kzqmXN: "x13u0t82",
+    kZKoxP: "x89eeu2",
+    kGuDYH: "x1uq1jy3",
+    $$css: true
+  },
+  sm: {
+    kzqmXN: "xomy6nw",
+    kZKoxP: "x14eyxzr",
+    kGuDYH: "x1qzu985",
+    $$css: true
+  },
+  md: {
+    kzqmXN: "x1vvatio",
+    kZKoxP: "x1jxzzob",
+    kGuDYH: "xhhwgqx",
+    $$css: true
+  },
+  lg: {
+    kzqmXN: "x1gbskz6",
+    kZKoxP: "xol4r8t",
+    kGuDYH: "x14nqahd",
+    $$css: true
+  }
+};
 const colorStyles = {
   primary: {
     kMwMTN: "xtbr613",
@@ -70,16 +112,20 @@ const colorStyles = {
     kMwMTN: "xqwr325",
     $$css: true
   },
+  info: {
+    kMwMTN: "x1gc9m53",
+    $$css: true
+  },
   success: {
-    kMwMTN: "xtjic6",
+    kMwMTN: "x1vau044",
     $$css: true
   },
   error: {
-    kMwMTN: "xjt36v0",
+    kMwMTN: "xskb5cx",
     $$css: true
   },
   warning: {
-    kMwMTN: "xs3pv69",
+    kMwMTN: "x4z9hng",
     $$css: true
   },
   inherit: {
@@ -178,6 +224,7 @@ export function Icon({
   icon,
   color = 'inherit',
   size: sizeProp,
+  variant,
   label,
   ref,
   className,
@@ -196,6 +243,7 @@ export function Icon({
       name: icon,
       color: color,
       size: size,
+      variant: variant,
       a11yProps: a11yProps,
       className: className,
       style: style,
@@ -204,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
@@ -230,13 +279,15 @@ Icon.displayName = 'Icon';
  * Internal component that resolves a semantic icon name from the registry
  * and renders it in a styled span with proper sizing.
  *
- * Extracted as a separate component so getIcon is only called
- * when the icon prop is a string.
+ * 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 and the
+ * requested variant when the entry can receive it.
  */
 function IconFromRegistry({
   name,
   color,
   size,
+  variant,
   a11yProps,
   className,
   style,
@@ -244,7 +295,10 @@ function IconFromRegistry({
   spanProps
 }) {
   const themeName = useThemeName();
-  const resolvedIcon = getIcon(name, themeName);
+  const resolvedIcon = resolveIcon(name, themeName, {
+    size,
+    variant
+  });
   if (resolvedIcon == null) {
     return null;
   }
@@ -261,7 +315,7 @@ function IconFromRegistry({
     ...mergeProps(themeProps('icon', {
       size,
       color
-    }), stylex.props(styles.span, colorStyles[color], iconBoxSizeStyles[size], xstyle), className ?? undefined, style),
+    }), stylex.props(styles.span, colorStyles[color], registrySizeStyles[size], xstyle), className ?? undefined, style),
     children: resolvedIcon
   });
 }

package/dist/Icon/IconSize.stylex.d.ts

@@ -1,8 +1,13 @@
 /**
  * @file IconSize.stylex.ts
- * @input Defines the Icon size scale
+ * @input Defines the Icon size scale and reads the `icon` target's private
+ *   `--_icon-width` / `--_icon-height` vars
  * @output Exports shared Icon size types and StyleX styles
  * @position Internal Icon sizing source; consumed by Icon and icon-slot owners
+ *
+ * SYNC: When the private vars change, update Icon.tsx (registrySizeStyles),
+ * derivedVarRegistry.ts, and the `theming.vars` / `theming.derived` entries in
+ * Icon.doc.mjs.
  */
 import * as stylex from '@stylexjs/stylex';
 /**
@@ -19,25 +24,25 @@ export type IconSize = keyof typeof iconSizeValues;
 /** Size styles for direct SVG icon components. */
 export declare const iconSizeStyles: Readonly<{
     readonly xsm: Readonly<{
-        readonly width: stylex.StyleXClassNameFor<"width", "0.75rem">;
-        readonly height: stylex.StyleXClassNameFor<"height", "0.75rem">;
+        readonly width: stylex.StyleXClassNameFor<"width", "var(--_icon-width, 0.75rem)">;
+        readonly height: stylex.StyleXClassNameFor<"height", "var(--_icon-height, 0.75rem)">;
     }>;
     readonly sm: Readonly<{
-        readonly width: stylex.StyleXClassNameFor<"width", "1rem">;
-        readonly height: stylex.StyleXClassNameFor<"height", "1rem">;
+        readonly width: stylex.StyleXClassNameFor<"width", "var(--_icon-width, 1rem)">;
+        readonly height: stylex.StyleXClassNameFor<"height", "var(--_icon-height, 1rem)">;
     }>;
     readonly md: Readonly<{
-        readonly width: stylex.StyleXClassNameFor<"width", "1.25rem">;
-        readonly height: stylex.StyleXClassNameFor<"height", "1.25rem">;
+        readonly width: stylex.StyleXClassNameFor<"width", "var(--_icon-width, 1.25rem)">;
+        readonly height: stylex.StyleXClassNameFor<"height", "var(--_icon-height, 1.25rem)">;
     }>;
     readonly lg: Readonly<{
-        readonly width: stylex.StyleXClassNameFor<"width", "1.5rem">;
-        readonly height: stylex.StyleXClassNameFor<"height", "1.5rem">;
+        readonly width: stylex.StyleXClassNameFor<"width", "var(--_icon-width, 1.5rem)">;
+        readonly height: stylex.StyleXClassNameFor<"height", "var(--_icon-height, 1.5rem)">;
     }>;
 }>;
 /**
- * Size styles for icon boxes and string-based registry icons. `fontSize`
- * keeps 1em-based icons in step with the box.
+ * Size styles for component-owned icon boxes. `fontSize` keeps 1em-based icons
+ * in step with the box.
  */
 export declare const iconBoxSizeStyles: Readonly<{
     readonly xsm: Readonly<{

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

@@ -1 +1 @@
-{"version":3,"file":"IconSize.stylex.d.ts","sourceRoot":"","sources":["../../src/Icon/IconSize.stylex.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AAEH,OAAO,KAAK,MAAM,MAAM,kBAAkB,CAAC;AAE3C;;;GAGG;AACH,QAAA,MAAM,cAAc;;;;;CAKV,CAAC;AAEX,MAAM,MAAM,QAAQ,GAAG,MAAM,OAAO,cAAc,CAAC;AAEnD,kDAAkD;AAClD,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;EAiBzB,CAAC;AAEH;;;GAGG;AACH,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;EAqB5B,CAAC"}
+{"version":3,"file":"IconSize.stylex.d.ts","sourceRoot":"","sources":["../../src/Icon/IconSize.stylex.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,MAAM,MAAM,kBAAkB,CAAC;AAE3C;;;GAGG;AACH,QAAA,MAAM,cAAc;;;;;CAKV,CAAC;AAEX,MAAM,MAAM,QAAQ,GAAG,MAAM,OAAO,cAAc,CAAC;AAanD,kDAAkD;AAClD,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;EAiBzB,CAAC;AAEH;;;GAGG;AACH,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;EAqB5B,CAAC"}

package/dist/Icon/IconSize.stylex.js

@@ -2,9 +2,14 @@
 
 /**
  * @file IconSize.stylex.ts
- * @input Defines the Icon size scale
+ * @input Defines the Icon size scale and reads the `icon` target's private
+ *   `--_icon-width` / `--_icon-height` vars
  * @output Exports shared Icon size types and StyleX styles
  * @position Internal Icon sizing source; consumed by Icon and icon-slot owners
+ *
+ * SYNC: When the private vars change, update Icon.tsx (registrySizeStyles),
+ * derivedVarRegistry.ts, and the `theming.vars` / `theming.derived` entries in
+ * Icon.doc.mjs.
  */
 
 import * as stylex from '@stylexjs/stylex';
@@ -19,33 +24,44 @@ const iconSizeValues = {
   md: '1.25rem',
   lg: '1.5rem'
 };
+/*
+ * Icon's own glyph dimensions (these and the registry size styles in Icon.tsx)
+ * read private vars rather than being plain declarations. A theme writes
+ * `width`/`height` on the `icon` target's size selector
+ * (`components.icon['size:sm']`), and the derived-var registry emits them as
+ * `--_icon-width` / `--_icon-height` instead of as competing properties.
+ * Nothing else declares the dimensions, so the theme value lands however the
+ * consumer layers StyleX; with no theme value, each size falls back to its own
+ * rem value.
+ */
+
 /** Size styles for direct SVG icon components. */
 export const iconSizeStyles = {
   xsm: {
-    kzqmXN: "x1jw3ynk",
-    kZKoxP: "xvle69y",
+    kzqmXN: "x13u0t82",
+    kZKoxP: "x89eeu2",
     $$css: true
   },
   sm: {
-    kzqmXN: "xcdlrvm",
-    kZKoxP: "x1l36t39",
+    kzqmXN: "xomy6nw",
+    kZKoxP: "x14eyxzr",
     $$css: true
   },
   md: {
-    kzqmXN: "xwqq7k2",
-    kZKoxP: "xmll18r",
+    kzqmXN: "x1vvatio",
+    kZKoxP: "x1jxzzob",
     $$css: true
   },
   lg: {
-    kzqmXN: "xp8d6y2",
-    kZKoxP: "xam5rvr",
+    kzqmXN: "x1gbskz6",
+    kZKoxP: "xol4r8t",
     $$css: true
   }
 };
 
 /**
- * Size styles for icon boxes and string-based registry icons. `fontSize`
- * keeps 1em-based icons in step with the box.
+ * Size styles for component-owned icon boxes. `fontSize` keeps 1em-based icons
+ * in step with the box.
  */
 export const iconBoxSizeStyles = {
   xsm: {

package/dist/Icon/globalIconRegistry.d.ts

@@ -1,13 +1,26 @@
 /**
  * @file globalIconRegistry.tsx
- * @input None (pure module-level state)
- * @output Exports registerIcons, getIconRegistry, getIcon, resetIcons, IconName, IconRegistry
+ * @input Theme icon entries (a DefinedTheme or a registered theme name), the
+ *   process-wide registry, and built-in defaults
+ * @output Exports registerIcons, getIconRegistry, getIcon, getExtendedIcon,
+ *   resetIcons, resolveIcon (internal), IconName, IconRegistry, IconEntry,
+ *   IconRequest
  * @position Global and theme-scoped icon registry; works in server and client environments
  *
  * This module has NO 'use client' directive — it's importable from RSC.
  * Components resolve semantic icons through getIcon() or the client useIcon() hook.
+ *
+ * An entry is a React node or a pure synchronous function of an
+ * {@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 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';
+import type { IconVariant } from './index.js';
 import type { DefinedTheme } from '../theme/defineTheme.js';
 /**
  * Semantic icon names used internally by Astryx components.
@@ -43,7 +56,46 @@ export type ExtendedIconName = IconName | (string & {});
  * A complete icon registry: every semantic name mapped to a React node.
  */
 export type IconRegistry = Record<IconName, ReactNode>;
+/**
+ * What `Icon` asks a function icon entry for: the final Icon size, resolved
+ * explicit `size` → owning component's default → `'md'`, and a variant name
+ * or `undefined`.
+ *
+ * Inside `defineTheme`, `Variant` is the theme's listed `iconVariants`; a
+ * process-wide registration receives {@link IconVariant}.
+ */
+export type IconRequest<Variant extends string = IconVariant> = Readonly<{
+    size: IconSize;
+    variant?: Variant;
+}>;
+/**
+ * A theme or process-wide icon entry: a React node, or a pure synchronous
+ * function of the {@link IconRequest} that returns one.
+ *
+ * A function computes its result from the request only — no hooks, DOM or
+ * SVG measurement, browser globals, network access, mutable module state, or
+ * side effects. Once selected, its result is final: returning `null` or
+ * `undefined` renders no glyph instead of falling through to another source.
+ *
+ * @example
+ * ```
+ * defineTheme({
+ *   name: 'brand',
+ *   icons: {
+ *     info: ({size}) => <InfoIcon weight={size === 'sm' ? 'bold' : 'regular'} />,
+ *   },
+ * });
+ * ```
+ */
+export type IconEntry<Variant extends string = IconVariant> = ReactNode | ((request: IconRequest<Variant>) => ReactNode);
 export type IconRegistrySource = DefinedTheme | string | null | undefined;
+/**
+ * Resolve a key for an Icon request. `Icon` is the caller: it passes the size
+ * 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<string>): ReactNode;
 /**
  * Register icons at the module level. Works in both server and client
  * environments. Call once at app initialization (e.g. root layout).
@@ -66,8 +118,15 @@ export type IconRegistrySource = DefinedTheme | string | null | undefined;
  * ```
  * registerIcons({ 'richtext:bold': <MyBoldIcon /> });
  * ```
+ *
+ * An entry may also be a pure synchronous function of `{size, variant}`
+ * ({@link IconEntry}); `Icon` passes it the size it renders at.
+ * @example
+ * ```
+ * registerIcons({ info: ({size}) => <InfoIcon weight={size === 'sm' ? 'bold' : 'regular'} /> });
+ * ```
  */
-export declare function registerIcons(icons: Partial<Record<ExtendedIconName, ReactNode>>): void;
+export declare function registerIcons(icons: Partial<Record<ExtendedIconName, IconEntry>>): void;
 /**
  * Get a snapshot of the full icon registry, with registered icons overriding
  * built-in defaults.
@@ -75,6 +134,9 @@ export declare function registerIcons(icons: Partial<Record<ExtendedIconName, Re
  * Works in both server and client environments. Useful for tooling that needs
  * to derive valid semantic icon-name options from the same registry Icon
  * resolves against.
+ *
+ * Every value is a React node: a function entry is read at `{size: 'md'}`,
+ * exactly as {@link getIcon} reads it.
  */
 export declare function getIconRegistry(source?: IconRegistrySource): Readonly<Record<IconName, ReactNode>>;
 /**
@@ -87,6 +149,9 @@ export declare function getIconRegistry(source?: IconRegistrySource): Readonly<R
  * {@link IconName}s — useful for library-contributed icons. For a
  * caller-supplied fallback when a key isn't registered, use
  * {@link getExtendedIcon}.
+ *
+ * Returns a React node: a function entry is read at `{size: 'md'}`. Render
+ * `<Icon icon={name} />` to request another size.
  */
 export declare function getIcon(name: ExtendedIconName, source?: IconRegistrySource): ReactNode;
 /**
@@ -99,7 +164,9 @@ export declare function getIcon(name: ExtendedIconName, source?: IconRegistrySou
  * widen the core {@link IconName} union.
  *
  * The `fallback` is the library default, overridable by a theme registering the
- * same key (for example `'richtext:bold'`).
+ * same key (for example `'richtext:bold'`). A function entry is read at
+ * `{size: 'md'}`, and its result is final: a nullish result does not fall
+ * back.
  * @example
  * ```
  * getExtendedIcon('richtext:bold', <BoldGlyph />)

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

@@ -1 +1 @@
-{"version":3,"file":"globalIconRegistry.d.ts","sourceRoot":"","sources":["../../src/Icon/globalIconRegistry.tsx"],"names":[],"mappings":"AAEA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,OAAO,CAAC;AAErC,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,MAAM,MAAM,kBAAkB,GAAG,YAAY,GAAG,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;AAgC1E;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,aAAa,CAC3B,KAAK,EAAE,OAAO,CAAC,MAAM,CAAC,gBAAgB,EAAE,SAAS,CAAC,CAAC,GAClD,IAAI,CAON;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAC7B,MAAM,CAAC,EAAE,kBAAkB,GAC1B,QAAQ,CAAC,MAAM,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC,CAyBvC;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,OAAO,CACrB,IAAI,EAAE,gBAAgB,EACtB,MAAM,CAAC,EAAE,kBAAkB,GAC1B,SAAS,CAOX;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,gBAAgB,EACtB,QAAQ,CAAC,EAAE,SAAS,EACpB,MAAM,CAAC,EAAE,kBAAkB,GAC1B,SAAS,CAQX;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"}