@astryxdesign/core 0.7.5-canary.fccd771 → 0.7.5

package/dist/theme/declarationBoundary.js

@@ -49,7 +49,25 @@ function isNameChar(ch) {
 
 /** CSS Syntax §3.3 preprocessing, for scanning only; emitted bytes stay intact. */
 function preprocess(input) {
-  return input.replace(/\r\n?|\f/g, '\n').replace(/\0/g, '\uFFFD');
+  const normalized = input.replace(/\r\n?|\f/g, '\n').replace(/\0/g, '\uFFFD');
+  let output = '';
+  for (let index = 0; index < normalized.length; index++) {
+    const code = normalized.charCodeAt(index);
+    if (code >= 0xd800 && code <= 0xdbff) {
+      const next = normalized.charCodeAt(index + 1);
+      if (next >= 0xdc00 && next <= 0xdfff) {
+        output += normalized[index] + normalized[index + 1];
+        index++;
+      } else {
+        output += '\uFFFD';
+      }
+    } else if (code >= 0xdc00 && code <= 0xdfff) {
+      output += '\uFFFD';
+    } else {
+      output += normalized[index];
+    }
+  }
+  return output;
 }
 
 /** Non-printable code points make an unquoted url() a bad-url token. */
@@ -318,6 +336,251 @@ export function checkDeclarationValue(input) {
   }
   return null;
 }
+function skipWhitespaceAndComments(input, start) {
+  let index = start;
+  for (;;) {
+    while (index < input.length && isWhitespace(input[index])) {
+      index++;
+    }
+    if (input[index] !== '/' || input[index + 1] !== '*') {
+      return index;
+    }
+    const close = input.indexOf('*/', index + 2);
+    if (close === -1) {
+      return input.length;
+    }
+    index = close + 2;
+  }
+}
+function varReferenceAt(input, openParen) {
+  const start = skipWhitespaceAndComments(input, openParen + 1);
+  if (!startsIdent(input, start)) {
+    return null;
+  }
+  const token = consumeIdent(input, start);
+  if (!token.name.startsWith('--')) {
+    return null;
+  }
+  const end = skipWhitespaceAndComments(input, token.end);
+  return input[end] === ',' || input[end] === ')' ? token.name : null;
+}
+function startsNumber(input, position) {
+  const first = input[position];
+  const second = input[position + 1];
+  const third = input[position + 2];
+  if (first === '+' || first === '-') {
+    return /^[0-9]$/.test(second ?? '') || second === '.' && /^[0-9]$/.test(third ?? '');
+  }
+  return /^[0-9]$/.test(first ?? '') || first === '.' && /^[0-9]$/.test(second ?? '');
+}
+function consumeNumber(input, position) {
+  let index = position;
+  if (input[index] === '+' || input[index] === '-') {
+    index++;
+  }
+  while (/^[0-9]$/.test(input[index] ?? '')) {
+    index++;
+  }
+  if (input[index] === '.' && /^[0-9]$/.test(input[index + 1] ?? '')) {
+    index += 2;
+    while (/^[0-9]$/.test(input[index] ?? '')) {
+      index++;
+    }
+  }
+  if ((input[index] === 'e' || input[index] === 'E') && (/^[0-9]$/.test(input[index + 1] ?? '') || (input[index + 1] === '+' || input[index + 1] === '-') && /^[0-9]$/.test(input[index + 2] ?? ''))) {
+    index++;
+    if (input[index] === '+' || input[index] === '-') {
+      index++;
+    }
+    while (/^[0-9]$/.test(input[index] ?? '')) {
+      index++;
+    }
+  }
+  return index;
+}
+const DECLARATION_ANALYSIS_CACHE = new Map();
+const MAX_DECLARATION_ANALYSIS_CACHE = 4096;
+
+/**
+ * Analyze one accepted declaration value using the same CSS tokenization rules
+ * as the declaration-boundary check.
+ */
+export function analyzeDeclarationValue(input) {
+  const cached = DECLARATION_ANALYSIS_CACHE.get(input);
+  if (cached !== undefined) {
+    return cached;
+  }
+  const reason = checkDeclarationValue(input);
+  if (reason !== null) {
+    const analysis = {
+      reason,
+      references: [],
+      important: false,
+      singleVarReference: null
+    };
+    if (DECLARATION_ANALYSIS_CACHE.size >= MAX_DECLARATION_ANALYSIS_CACHE) {
+      DECLARATION_ANALYSIS_CACHE.clear();
+    }
+    DECLARATION_ANALYSIS_CACHE.set(input, analysis);
+    return analysis;
+  }
+  const value = preprocess(input);
+  const references = [];
+  const open = [];
+  const topLevelTokens = [];
+  const firstTopLevelTokens = [];
+  let topLevelTokenCount = 0;
+  const recordTopLevel = token => {
+    if (open.length === 0) {
+      topLevelTokenCount++;
+      if (firstTopLevelTokens.length === 0) {
+        firstTopLevelTokens.push(token);
+      }
+      topLevelTokens.push(token);
+      if (topLevelTokens.length > 2) {
+        topLevelTokens.shift();
+      }
+    }
+  };
+  let index = 0;
+  while (index < value.length) {
+    const character = value[index];
+    if (isWhitespace(character)) {
+      index++;
+      continue;
+    }
+    if (character === '/' && value[index + 1] === '*') {
+      index = value.indexOf('*/', index + 2) + 2;
+      continue;
+    }
+    if (character === '"' || character === "'") {
+      recordTopLevel({
+        type: 'other',
+        value: character
+      });
+      const string = consumeString(value, index);
+      index = 'end' in string ? string.end : value.length;
+      continue;
+    }
+    if (character === '#') {
+      const nameStart = index + 1;
+      if (isNameChar(value[nameStart]) || isValidEscape(value, nameStart)) {
+        recordTopLevel({
+          type: 'other',
+          value: '#'
+        });
+        index = consumeIdent(value, nameStart).end;
+        continue;
+      }
+    }
+    if (character === '@' && startsIdent(value, index + 1)) {
+      recordTopLevel({
+        type: 'other',
+        value: '@'
+      });
+      index = consumeIdent(value, index + 1).end;
+      continue;
+    }
+    if (startsNumber(value, index)) {
+      recordTopLevel({
+        type: 'other',
+        value: character
+      });
+      index = consumeNumber(value, index);
+      if (startsIdent(value, index)) {
+        index = consumeIdent(value, index).end;
+      } else if (value[index] === '%') {
+        index++;
+      }
+      continue;
+    }
+    if (startsIdent(value, index)) {
+      const ident = consumeIdent(value, index);
+      index = ident.end;
+      const isFunction = value[index] === '(';
+      const reference = isFunction && ident.name.toLowerCase() === 'var' ? varReferenceAt(value, index) : null;
+      recordTopLevel(reference !== null ? {
+        type: 'var-function',
+        value: ident.name,
+        reference
+      } : {
+        type: isFunction ? 'other' : 'ident',
+        value: ident.name
+      });
+      if (isFunction) {
+        if (reference !== null) {
+          references.push(reference);
+        }
+        if (ident.name.toLowerCase() === 'url') {
+          let body = index + 1;
+          while (body < value.length && isWhitespace(value[body])) {
+            body++;
+          }
+          if (value[body] !== '"' && value[body] !== "'") {
+            const url = consumeUrl(value, body);
+            index = 'end' in url ? url.end : value.length;
+            continue;
+          }
+        }
+        open.push(')');
+        index++;
+      }
+      continue;
+    }
+    if (character === '(' || character === '[' || character === '{') {
+      recordTopLevel({
+        type: 'other',
+        value: character
+      });
+      open.push(CLOSER[character]);
+      index++;
+      continue;
+    }
+    if (character === ')' || character === ']' || character === '}') {
+      open.pop();
+      index++;
+      continue;
+    }
+    if (character === '!') {
+      recordTopLevel({
+        type: 'delim',
+        value: character
+      });
+    } else {
+      recordTopLevel({
+        type: 'other',
+        value: character
+      });
+    }
+    index++;
+  }
+  const previousTopLevel = topLevelTokens.at(-2);
+  const lastTopLevel = topLevelTokens.at(-1);
+  const important = previousTopLevel?.type === 'delim' && previousTopLevel.value === '!' && lastTopLevel?.type === 'ident' && lastTopLevel.value.toLowerCase() === 'important';
+  const firstTopLevelToken = firstTopLevelTokens[0];
+  const singleVarReference = topLevelTokenCount - (important ? 2 : 0) === 1 && firstTopLevelToken?.type === 'var-function' ? firstTopLevelToken.reference ?? null : null;
+  const analysis = {
+    reason: null,
+    references,
+    important,
+    singleVarReference
+  };
+  if (DECLARATION_ANALYSIS_CACHE.size >= MAX_DECLARATION_ANALYSIS_CACHE) {
+    DECLARATION_ANALYSIS_CACHE.clear();
+  }
+  DECLARATION_ANALYSIS_CACHE.set(input, analysis);
+  return analysis;
+}
+
+/** The browser-canonical spelling of one valid declaration name. */
+export function canonicalizeDeclarationName(input) {
+  const name = preprocess(input);
+  if (name.length === 0 || !startsIdent(name, 0)) {
+    return null;
+  }
+  const ident = consumeIdent(name, 0);
+  return ident.end === name.length ? ident.name : null;
+}
 
 /**
  * Why `name` cannot be emitted as a declaration's property name, or `null`

package/dist/theme/defineTheme.d.ts

@@ -37,11 +37,34 @@
  * - /packages/cli/assets/docs/theme.doc.mjs (`astryx docs theme`)
  */
 import type { ReactNode } from 'react';
-import type { IconName, NamespacedIconName } from '../Icon/globalIconRegistry.js';
+import type { IconEntry, IconName, NamespacedIconName } from '../Icon/globalIconRegistry.js';
 /**
  * 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>>;
 import type { IndicatorRegistry } from '../Indicator/types.js';
 import type { TypographyConfig } from './types.js';
@@ -122,8 +145,14 @@ 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;
     /**
@@ -151,7 +180,7 @@ export interface DefineThemeInput {
      * });
      * ```
      */
-    extends?: DefinedTheme;
+    extends?: Base;
     /**
      * Unified typography configuration — fonts, scale, and weights.
      *
@@ -277,8 +306,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.
@@ -367,8 +433,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 */
@@ -407,10 +494,23 @@ export interface DefinedTheme {
     /** Effective root generative-axis metadata used to resolve child rules. @internal */
     __axes?: ThemeGenerativeAxes;
 }
-/** A theme produced by the current defineTheme implementation. */
-export type ResolvedDefinedTheme = DefinedTheme & {
+/**
+ * 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 Astryx token defaults as a flat map. Useful for resolving full token sets. */
 export declare const tokenDefaults: Record<string, string>;
@@ -424,7 +524,7 @@ export declare const tokenDefaults: Record<string, string>;
  * that are merged into the token map. Explicit `tokens` entries take
  * precedence over generated values.
  */
-export declare function defineTheme(input: DefineThemeInput): ResolvedDefinedTheme;
+export declare function defineTheme<const IconVariants extends ReadonlyArray<string> | undefined = undefined, Base extends DefinedTheme | undefined = undefined>(input: DefineThemeInput<IconVariants, Base>): ResolvedDefinedTheme<ThemeIconVariant<IconVariants, Base>>;
 export { generateThemeRules, generateThemeRulesSplit, generateOnMediaCSS, generateAdaptationCSS, generateThemeCSS, type ThemeRulesSplit, type ThemeCSSOutput, } from './generateThemeRules.js';
 /** Check if a theme object was created with defineTheme */
 export declare function isDefinedTheme(theme: unknown): theme is DefinedTheme;

package/dist/theme/defineTheme.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"defineTheme.d.ts","sourceRoot":"","sources":["../../src/theme/defineTheme.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"defineTheme.d.ts","sourceRoot":"","sources":["../../src/theme/defineTheme.ts"],"names":[],"mappings":"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"}

package/dist/theme/defineTheme.js

@@ -41,9 +41,29 @@
 
 /**
  * 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`.
  */
 
+/**
+ * The variant names a base theme lists: exact for a theme from `defineTheme`,
+ * any string for another `DefinedTheme`, none without a base.
+ */
+
+/**
+ * The variant names a theme lists: its own `iconVariants` when it sets the
+ * field, otherwise the list it inherits from `extends`.
+ */
+
+/**
+ * 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.
+ */
+
+/** The node-valued view of a theme's icons that public reads return. */
+
 import { resolveOnMedia } from "./onMediaTokens.js";
 import { colorDefaults, spacingDefaults, sizeDefaults, borderDefaults, focusDefaults, radiusDefaults, shadowDefaults, durationDefaults, easeDefaults, typographyDefaults, textSizeDefaults, fontWeightDefaults, typeScaleDefaults } from "./tokens.stylex.js";
 import { resolveThemeValues } from "./resolveThemeValues.js";
@@ -125,11 +145,20 @@ import { resolveLocalTokenContract } from "./localTokens.js";
  * ```
  */
 
-/** Input to defineTheme */
+/**
+ * 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.
+ */
 
 /** A defined theme — ready to pass to <Theme> */
 
-/** A theme produced by the current defineTheme implementation. */
+/**
+ * A theme produced by the current defineTheme implementation. `IconVariant`
+ * is the names in its `iconVariants` list.
+ */
 
 // =============================================================================
 // All defaults merged into a single flat map
@@ -238,11 +267,22 @@ export function defineTheme(input) {
   const __adaptations = normalizeThemeAdaptations(input.name, base?.__adaptations, input.adaptations);
   const __adaptationRules = resolveThemeAdaptationRules(input.name, __adaptations, __axes, tokens, localTokenContract?.localTokens, components);
 
-  // Icons — input icons override base icons
-  const icons = input.icons && base?.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 ?? base?.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 = 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.
@@ -260,6 +300,15 @@ export function defineTheme(input) {
     } : {}),
     components,
     icons,
+    ...(icons !== iconEntries ? {
+      __icons: iconEntries
+    } : {}),
+    ...(iconVariants !== undefined ? {
+      iconVariants
+    } : {}),
+    ...(iconEntryVariants !== undefined ? {
+      __iconEntryVariants: iconEntryVariants
+    } : {}),
     indicators,
     __inputTokens: base?.__inputTokens || input.tokens ? {
       ...base?.__inputTokens,
@@ -275,6 +324,47 @@ export function defineTheme(input) {
   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, ownEntries, base, iconVariants) {
+  if (entries == null || base == null) {
+    return undefined;
+  }
+  const baseRecord = base.__iconEntryVariants;
+  let record;
+  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) {
+  if (entries == null || !Object.values(entries).some(entry => typeof entry === 'function')) {
+    return entries;
+  }
+  const nodes = {};
+  for (const [name, entry] of Object.entries(entries)) {
+    nodes[name] = typeof entry === 'function' ? entry({
+      size: 'md'
+    }) : entry;
+  }
+  return nodes;
+}
+
 // =============================================================================
 // CSS generation — re-exported from ./generateThemeRules.ts
 // =============================================================================

package/dist/theme/derivedVarRegistry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"derivedVarRegistry.d.ts","sourceRoot":"","sources":["../../src/theme/derivedVarRegistry.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;GAgBG;AAEH,MAAM,WAAW,eAAe;IAC9B,2EAA2E;IAC3E,QAAQ,EAAE,MAAM,CAAC;IACjB,2EAA2E;IAC3E,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,iFAAiF;IACjF,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED;;;;;;GAMG;AACH,eAAO,MAAM,kBAAkB,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,EAAE,CAkDhE,CAAC;AAEF,wBAAgB,cAAc,CAC5B,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,GACf,eAAe,EAAE,CAMnB"}
+{"version":3,"file":"derivedVarRegistry.d.ts","sourceRoot":"","sources":["../../src/theme/derivedVarRegistry.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;GAgBG;AAEH,MAAM,WAAW,eAAe;IAC9B,2EAA2E;IAC3E,QAAQ,EAAE,MAAM,CAAC;IACjB,2EAA2E;IAC3E,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,iFAAiF;IACjF,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED;;;;;;GAMG;AACH,eAAO,MAAM,kBAAkB,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,EAAE,CAsDhE,CAAC;AAEF,wBAAgB,cAAc,CAC5B,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,GACf,eAAe,EAAE,CAMnB"}

package/dist/theme/derivedVarRegistry.js

@@ -89,6 +89,15 @@ export const derivedVarRegistry = {
     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']

package/dist/theme/generateThemeRules.d.ts

@@ -2,8 +2,9 @@
  * @file Theme CSS generation utilities
  *
  * Shared logic for generating CSS rules from a resolved theme definition,
- * including one component-leaf lowering path for root, adaptation, and
- * media-surface values plus condition-correct Heading weight precedence guards.
+ * including source-scoped semantic role defaults and one component-leaf lowering
+ * path for root, adaptation, and media-surface values plus condition-correct
+ * Heading weight precedence guards.
  * Built adaptation metadata resolves against the same root component defaults
  * as defineTheme, so scale-only rules do not reset authored component styles.
  * Used by both the runtime path (Theme injects <style>) and the build
@@ -23,6 +24,7 @@
  * @position packages/core/src/theme/generateThemeRules.ts
  */
 import type { ComponentStyleMap, DefinedTheme } from './defineTheme.js';
+import { type ResolvedThemeAdaptationRule } from './themeAdaptations.js';
 /**
  * Structured output from generateThemeRulesSplit.
  * Separates prose element defaults from component/token overrides
@@ -51,6 +53,8 @@ export interface ThemeCSSOutput {
      */
     component: string;
 }
+/** Root status roles a theme leaves unset: INV17-derived values and INV16 aliases. */
+export declare function generatedScopedStatusRoleDefaults(tokens: Record<string, string>, localTokens?: Record<string, string>, rules?: ReadonlyArray<ResolvedThemeAdaptationRule>): [string, string][];
 /**
  * Generate the intermediary CSS rules for a theme.
  *