@yahoo/uds 3.156.2 → 3.157.0

package/dist/automated-config/dist/properties.cjs

@@ -7,7 +7,7 @@ const require_index$1 = require("../../motion-tokens/dist/index.cjs");
 //#region ../automated-config/dist/properties.js
 /*! © 2026 Yahoo, Inc. UDS Default Config v0.0.0-development */
 const isInputWrapperCtx = (context) => {
-	return context.componentName === "input" && context.layer === "inputWrapper";
+	return context.componentName === "input" && (context.layer === "inputWrapper" || context.layer === "inputWrapperDynamic");
 };
 const hexToRgb = (hex) => {
 	hex = hex.replace("#", "");

package/dist/automated-config/dist/properties.d.cts

@@ -1,4 +1,5 @@
 
+import { AtomicState } from "./types/StateAxis.cjs";
 import { ShadowPreset } from "../../types/dist/index.cjs";
 import { ArbitraryFixtures, InferArbitraryType } from "../../fixtures/dist/index.cjs";
 import { AllPossibleProperties, PossibleStates } from "./types/ComponentConfig.cjs";
@@ -130,7 +131,21 @@ interface SelectedConfigurableProperty<C extends ConfigurablePropertiesName, O e
   typeOfFixture: T;
   values: V;
   skipRestState?: boolean;
+  /**
+   * Per-property pseudo state list (legacy). New components should declare
+   * atomic states at the layer level via `atomicStates` and use
+   * `excludeAtomics` here to opt out. Both paths are supported by the
+   * resolver — `resolvePropertyStates` falls back to this list when the
+   * parent layer has no `atomicStates`.
+   */
   pseudoStates?: PossibleStates[];
+  /**
+   * Atomic states the property should NOT react to, even when the parent
+   * layer's `atomicStates` includes them. Use sparingly — for properties whose
+   * visual change for a given state is meaningless (e.g., a font weight that
+   * shouldn't shift on `:placeholder-shown`).
+   */
+  excludeAtomics?: AtomicState[];
   supportsCustom?: boolean;
   layerReference?: {
     variablePath: string;

package/dist/automated-config/dist/properties.d.ts

@@ -1,4 +1,5 @@
 
+import { AtomicState } from "./types/StateAxis.js";
 import { ShadowPreset } from "../../types/dist/index.js";
 import { ArbitraryFixtures, InferArbitraryType } from "../../fixtures/dist/index.js";
 import { AllPossibleProperties, PossibleStates } from "./types/ComponentConfig.js";
@@ -130,7 +131,21 @@ interface SelectedConfigurableProperty<C extends ConfigurablePropertiesName, O e
   typeOfFixture: T;
   values: V;
   skipRestState?: boolean;
+  /**
+   * Per-property pseudo state list (legacy). New components should declare
+   * atomic states at the layer level via `atomicStates` and use
+   * `excludeAtomics` here to opt out. Both paths are supported by the
+   * resolver — `resolvePropertyStates` falls back to this list when the
+   * parent layer has no `atomicStates`.
+   */
   pseudoStates?: PossibleStates[];
+  /**
+   * Atomic states the property should NOT react to, even when the parent
+   * layer's `atomicStates` includes them. Use sparingly — for properties whose
+   * visual change for a given state is meaningless (e.g., a font weight that
+   * shouldn't shift on `:placeholder-shown`).
+   */
+  excludeAtomics?: AtomicState[];
   supportsCustom?: boolean;
   layerReference?: {
     variablePath: string;

package/dist/automated-config/dist/properties.js

@@ -7,7 +7,7 @@ import { SCALE_EFFECTS } from "../../motion-tokens/dist/index.js";
 //#region ../automated-config/dist/properties.js
 /*! © 2026 Yahoo, Inc. UDS Default Config v0.0.0-development */
 const isInputWrapperCtx = (context) => {
-	return context.componentName === "input" && context.layer === "inputWrapper";
+	return context.componentName === "input" && (context.layer === "inputWrapper" || context.layer === "inputWrapperDynamic");
 };
 const hexToRgb = (hex) => {
 	hex = hex.replace("#", "");

package/dist/automated-config/dist/types/ComponentConfig.d.cts

@@ -1,4 +1,5 @@
 
+import { AtomicState, InteractiveAtomic, ModifierAtomic } from "./StateAxis.cjs";
 import { index_d_exports } from "../../../fixtures/dist/index.cjs";
 import { ConfigurablePropertiesName, SelectedConfigurableProperty } from "../properties.cjs";
 
@@ -6,8 +7,35 @@ import { ConfigurablePropertiesName, SelectedConfigurableProperty } from "../pro
 //#region src/types/ComponentConfig.d.ts
 /** All configurable property names, excluding button-specific and elevation properties */
 type AllPossibleProperties = Exclude<keyof typeof index_d_exports, 'iconButtonSize' | 'buttonIconSvgSize' | 'buttonPalettes' | 'buttonStates'> | 'shadowVariantConfig';
-/** All possible interactive states a component can have. Compound states use & (e.g., invalid&hover) */
-type PossibleStates = 'hover' | 'pressed' | 'focused' | 'invalid' | 'focus-within' | 'focused-keyboard' | 'visited' | 'readonly' | 'disabled' | 'invalid&hover' | 'invalid&pressed';
+/**
+ * Legacy atomic state literals still in use by unmigrated configs via the
+ * per-property `pseudoStates` array. These aren't part of the new `StateAxis`
+ * taxonomy (so the resolver and StateBuilder don't auto-compose them) but
+ * configs that still ship them must continue to typecheck and the CSS
+ * generator must still resolve their selectors. Drop entries as components
+ * migrate to layer-level `atomicStates`.
+ */
+type LegacyStateLiteral = 'disabled' | 'focused' | 'focused-keyboard';
+/**
+ * All possible state keys a property can be styled for. Encoded structure
+ * matches the resolver's enumeration and the StateBuilder's depth cap: 0..3
+ * modifiers followed optionally by 1 interactive (canonical form is
+ * `'modifier1&modifier2&...&interactive'` — see `canonicalizeStateKey`).
+ *
+ * The structure-aware form catches malformed compounds at compile time —
+ * `'hover&pressed'` (two interactives) and `'foo&hover'` (unknown atom)
+ * both fail to typecheck.
+ *
+ * What the type does NOT catch:
+ *   - Unsorted modifiers (`'readonly&invalid'` typechecks; canonical form is
+ *     `'invalid&readonly'`, produced by `canonicalizeStateKey`).
+ *   - Duplicate atoms (`'invalid&invalid'` typechecks; `canonicalizeStateKey`
+ *     dedupes within a key).
+ *
+ * Legacy atoms (`disabled`, `focused`, `focused-keyboard`) are accepted as
+ * standalone keys for unmigrated configs only — they aren't composable.
+ */
+type PossibleStates = AtomicState | LegacyStateLiteral | `${ModifierAtomic}&${InteractiveAtomic}` | `${ModifierAtomic}&${ModifierAtomic}` | `${ModifierAtomic}&${ModifierAtomic}&${InteractiveAtomic}` | `${ModifierAtomic}&${ModifierAtomic}&${ModifierAtomic}` | `${ModifierAtomic}&${ModifierAtomic}&${ModifierAtomic}&${InteractiveAtomic}`;
 /** PossibleStates plus 'rest' for the default/inactive state */
 type PossibleStatesWithRest = 'rest' | PossibleStates;
 /** Configuration for a single visual layer with its properties and optional pseudo-selector */
@@ -15,6 +43,20 @@ interface LayerConfig {
   label: string;
   properties: Readonly<Record<string, SelectedConfigurableProperty<ConfigurablePropertiesName, string>>>;
   pseudoSelector?: string;
+  /**
+   * Atomic states this layer can style. Properties on the layer auto-react to
+   * each declared atom plus every auto-generated compound up to
+   * `MAX_MODIFIERS_PER_COMPOUND` modifiers (currently 3) optionally combined
+   * with one interactive — i.e. M, M&M, M&M&M, M&I, M&M&I, and M&M&M&I forms,
+   * minus pairs the browser suppresses (e.g. `disabled&hover`). Properties
+   * opt out of specific atoms via `excludeAtomics` on
+   * `createConfigurableProperty`.
+   *
+   * Layers without `atomicStates` fall back to the legacy per-property
+   * `pseudoStates` array — this lets unmigrated configs keep their behavior
+   * while components are migrated incrementally.
+   */
+  atomicStates?: AtomicState[];
 }
 /** Configuration for a specific component state with its options and layer properties */
 interface ComponentStateConfig {
@@ -22,7 +64,14 @@ interface ComponentStateConfig {
   options: readonly string[];
   /** Pseudo-states to omit for specific component state options (e.g. active/on). */
   excludePseudoStatesForOptions?: Partial<Record<string, readonly PossibleStates[]>>;
-  layers: {
+  /**
+   * @deprecated Per-state property overrides are now authored at the schema
+   * level (Configurator UI, migrations), not in source configs. Each
+   * componentState only declares its options here; CSS emission picks up
+   * per-state schema entries automatically. Retained as optional so
+   * pre-existing configs still typecheck during migration to the new shape.
+   */
+  layers?: {
     root: LayerConfig;
   } & Record<string, LayerConfig>;
 }
@@ -47,9 +96,33 @@ interface VariantConfigWithProperties<O extends string = string> extends Variant
   /** Properties scoped to the variant option (e.g. size/sm/width without a layer). */
   variantProperties?: Readonly<Record<string, SelectedConfigurableProperty<ConfigurablePropertiesName, string>>>;
 }
-/** Variant with component state definitions (hover, focus, etc.) for each option */
+/**
+ * Variant with component state definitions (hover, focus, etc.) for each option.
+ *
+ * **KNOWN GAP — multi-axis componentStates aren't fully supported end-to-end.**
+ * The type permits `componentStates: Record<string, ComponentStateConfig>` with
+ * more than one key, and the configurator's StateBuilder renders one picker
+ * row per axis, but the pipeline below the picker (schema-key generator,
+ * `buildConfigSchema`, the CSS-selector composition in `generateDeclaration`,
+ * and the configurator's write path) all assume a single axis. Adding a
+ * second axis today lets the user choose a value on it visually, but only
+ * one axis's selection survives the round-trip into the stored schema —
+ * compound combinations like `value=filled & disabled=true` can't be
+ * addressed as their own override slot. Stick to a single componentState
+ * axis per variant until this is generalized end-to-end.
+ */
 interface VariantConfigWithComponentStates<O extends string = string> extends VariantConfig<O> {
   componentStates: Readonly<Record<string, ComponentStateConfig>>;
+  /**
+   * Optional layers that apply to the variant universally, regardless of any
+   * component state. Properties declared here emit CSS at single-class
+   * specificity (0,1,0); per-state schema overrides (added at runtime by the
+   * Configurator or by data migrations) emit at compound-class specificity
+   * (0,2,0)+ and win via the cascade.
+   */
+  layers?: {
+    root: LayerConfig;
+  } & Record<string, LayerConfig>;
 }
 /** Top-level component configuration with variants and optional sub-components */
 interface ComponentConfig {

package/dist/automated-config/dist/types/ComponentConfig.d.ts

@@ -1,4 +1,5 @@
 
+import { AtomicState, InteractiveAtomic, ModifierAtomic } from "./StateAxis.js";
 import { index_d_exports } from "../../../fixtures/dist/index.js";
 import { ConfigurablePropertiesName, SelectedConfigurableProperty } from "../properties.js";
 
@@ -6,8 +7,35 @@ import { ConfigurablePropertiesName, SelectedConfigurableProperty } from "../pro
 //#region src/types/ComponentConfig.d.ts
 /** All configurable property names, excluding button-specific and elevation properties */
 type AllPossibleProperties = Exclude<keyof typeof index_d_exports, 'iconButtonSize' | 'buttonIconSvgSize' | 'buttonPalettes' | 'buttonStates'> | 'shadowVariantConfig';
-/** All possible interactive states a component can have. Compound states use & (e.g., invalid&hover) */
-type PossibleStates = 'hover' | 'pressed' | 'focused' | 'invalid' | 'focus-within' | 'focused-keyboard' | 'visited' | 'readonly' | 'disabled' | 'invalid&hover' | 'invalid&pressed';
+/**
+ * Legacy atomic state literals still in use by unmigrated configs via the
+ * per-property `pseudoStates` array. These aren't part of the new `StateAxis`
+ * taxonomy (so the resolver and StateBuilder don't auto-compose them) but
+ * configs that still ship them must continue to typecheck and the CSS
+ * generator must still resolve their selectors. Drop entries as components
+ * migrate to layer-level `atomicStates`.
+ */
+type LegacyStateLiteral = 'disabled' | 'focused' | 'focused-keyboard';
+/**
+ * All possible state keys a property can be styled for. Encoded structure
+ * matches the resolver's enumeration and the StateBuilder's depth cap: 0..3
+ * modifiers followed optionally by 1 interactive (canonical form is
+ * `'modifier1&modifier2&...&interactive'` — see `canonicalizeStateKey`).
+ *
+ * The structure-aware form catches malformed compounds at compile time —
+ * `'hover&pressed'` (two interactives) and `'foo&hover'` (unknown atom)
+ * both fail to typecheck.
+ *
+ * What the type does NOT catch:
+ *   - Unsorted modifiers (`'readonly&invalid'` typechecks; canonical form is
+ *     `'invalid&readonly'`, produced by `canonicalizeStateKey`).
+ *   - Duplicate atoms (`'invalid&invalid'` typechecks; `canonicalizeStateKey`
+ *     dedupes within a key).
+ *
+ * Legacy atoms (`disabled`, `focused`, `focused-keyboard`) are accepted as
+ * standalone keys for unmigrated configs only — they aren't composable.
+ */
+type PossibleStates = AtomicState | LegacyStateLiteral | `${ModifierAtomic}&${InteractiveAtomic}` | `${ModifierAtomic}&${ModifierAtomic}` | `${ModifierAtomic}&${ModifierAtomic}&${InteractiveAtomic}` | `${ModifierAtomic}&${ModifierAtomic}&${ModifierAtomic}` | `${ModifierAtomic}&${ModifierAtomic}&${ModifierAtomic}&${InteractiveAtomic}`;
 /** PossibleStates plus 'rest' for the default/inactive state */
 type PossibleStatesWithRest = 'rest' | PossibleStates;
 /** Configuration for a single visual layer with its properties and optional pseudo-selector */
@@ -15,6 +43,20 @@ interface LayerConfig {
   label: string;
   properties: Readonly<Record<string, SelectedConfigurableProperty<ConfigurablePropertiesName, string>>>;
   pseudoSelector?: string;
+  /**
+   * Atomic states this layer can style. Properties on the layer auto-react to
+   * each declared atom plus every auto-generated compound up to
+   * `MAX_MODIFIERS_PER_COMPOUND` modifiers (currently 3) optionally combined
+   * with one interactive — i.e. M, M&M, M&M&M, M&I, M&M&I, and M&M&M&I forms,
+   * minus pairs the browser suppresses (e.g. `disabled&hover`). Properties
+   * opt out of specific atoms via `excludeAtomics` on
+   * `createConfigurableProperty`.
+   *
+   * Layers without `atomicStates` fall back to the legacy per-property
+   * `pseudoStates` array — this lets unmigrated configs keep their behavior
+   * while components are migrated incrementally.
+   */
+  atomicStates?: AtomicState[];
 }
 /** Configuration for a specific component state with its options and layer properties */
 interface ComponentStateConfig {
@@ -22,7 +64,14 @@ interface ComponentStateConfig {
   options: readonly string[];
   /** Pseudo-states to omit for specific component state options (e.g. active/on). */
   excludePseudoStatesForOptions?: Partial<Record<string, readonly PossibleStates[]>>;
-  layers: {
+  /**
+   * @deprecated Per-state property overrides are now authored at the schema
+   * level (Configurator UI, migrations), not in source configs. Each
+   * componentState only declares its options here; CSS emission picks up
+   * per-state schema entries automatically. Retained as optional so
+   * pre-existing configs still typecheck during migration to the new shape.
+   */
+  layers?: {
     root: LayerConfig;
   } & Record<string, LayerConfig>;
 }
@@ -47,9 +96,33 @@ interface VariantConfigWithProperties<O extends string = string> extends Variant
   /** Properties scoped to the variant option (e.g. size/sm/width without a layer). */
   variantProperties?: Readonly<Record<string, SelectedConfigurableProperty<ConfigurablePropertiesName, string>>>;
 }
-/** Variant with component state definitions (hover, focus, etc.) for each option */
+/**
+ * Variant with component state definitions (hover, focus, etc.) for each option.
+ *
+ * **KNOWN GAP — multi-axis componentStates aren't fully supported end-to-end.**
+ * The type permits `componentStates: Record<string, ComponentStateConfig>` with
+ * more than one key, and the configurator's StateBuilder renders one picker
+ * row per axis, but the pipeline below the picker (schema-key generator,
+ * `buildConfigSchema`, the CSS-selector composition in `generateDeclaration`,
+ * and the configurator's write path) all assume a single axis. Adding a
+ * second axis today lets the user choose a value on it visually, but only
+ * one axis's selection survives the round-trip into the stored schema —
+ * compound combinations like `value=filled & disabled=true` can't be
+ * addressed as their own override slot. Stick to a single componentState
+ * axis per variant until this is generalized end-to-end.
+ */
 interface VariantConfigWithComponentStates<O extends string = string> extends VariantConfig<O> {
   componentStates: Readonly<Record<string, ComponentStateConfig>>;
+  /**
+   * Optional layers that apply to the variant universally, regardless of any
+   * component state. Properties declared here emit CSS at single-class
+   * specificity (0,1,0); per-state schema overrides (added at runtime by the
+   * Configurator or by data migrations) emit at compound-class specificity
+   * (0,2,0)+ and win via the cascade.
+   */
+  layers?: {
+    root: LayerConfig;
+  } & Record<string, LayerConfig>;
 }
 /** Top-level component configuration with variants and optional sub-components */
 interface ComponentConfig {

package/dist/automated-config/dist/types/ConfigSchema.d.cts

@@ -1,5 +1,5 @@
 
-import { AllPossibleProperties } from "./ComponentConfig.cjs";
+import { AllPossibleProperties, PossibleStates } from "./ComponentConfig.cjs";
 
 //#region ../automated-config/dist/types/ConfigSchema.d.ts
 //#region src/types/ConfigSchema.d.ts
@@ -8,7 +8,19 @@ type SchemaStateValue<T = unknown> = {
   type: AllPossibleProperties;
   valueType: 'alias' | 'custom';
   value: T;
+  /**
+   * Per-state opt-in flag. The CSS generator emits a rule for `rest` always
+   * and for any non-rest slot only when this is `true`. Toggling it lets a
+   * designer turn off a state's CSS without losing the value they configured
+   * — re-enabling restores the previous value. The configurator's setter
+   * manages this flag in response to the property's enable checkbox.
+   */
+  isEnabled?: boolean;
 };
 /** Map of component states to schema values. Requires 'rest', optional interactive states */
+type VariableState = {
+  rest: SchemaStateValue;
+} & { [K in PossibleStates]?: SchemaStateValue };
+/** Configuration object mapping property keys to their state-based values */
 //#endregion
-export { type SchemaStateValue };
+export { type SchemaStateValue, type VariableState };

package/dist/automated-config/dist/types/ConfigSchema.d.ts

@@ -1,5 +1,5 @@
 
-import { AllPossibleProperties } from "./ComponentConfig.js";
+import { AllPossibleProperties, PossibleStates } from "./ComponentConfig.js";
 
 //#region ../automated-config/dist/types/ConfigSchema.d.ts
 //#region src/types/ConfigSchema.d.ts
@@ -8,7 +8,19 @@ type SchemaStateValue<T = unknown> = {
   type: AllPossibleProperties;
   valueType: 'alias' | 'custom';
   value: T;
+  /**
+   * Per-state opt-in flag. The CSS generator emits a rule for `rest` always
+   * and for any non-rest slot only when this is `true`. Toggling it lets a
+   * designer turn off a state's CSS without losing the value they configured
+   * — re-enabling restores the previous value. The configurator's setter
+   * manages this flag in response to the property's enable checkbox.
+   */
+  isEnabled?: boolean;
 };
 /** Map of component states to schema values. Requires 'rest', optional interactive states */
+type VariableState = {
+  rest: SchemaStateValue;
+} & { [K in PossibleStates]?: SchemaStateValue };
+/** Configuration object mapping property keys to their state-based values */
 //#endregion
-export { type SchemaStateValue };
+export { type SchemaStateValue, type VariableState };

package/dist/automated-config/dist/types/StateAxis.cjs

@@ -0,0 +1,90 @@
+/*! © 2026 Yahoo, Inc. UDS v0.0.0-development */
+//#region ../automated-config/dist/types/StateAxis.js
+/*! © 2026 Yahoo, Inc. UDS Default Config v0.0.0-development */
+/**
+* Atomic-state taxonomy.
+*
+* Every interactive component reacts to a fixed set of "atomic" states, each
+* belonging to one axis:
+*
+* - `interactive` — pointer/keyboard focus signals. At runtime at most one of
+*   these is meaningfully "active" at a time on a given element (you can't
+*   simultaneously hover and press distinctly enough to style separately, etc.).
+*
+* - `modifier` — semantic flags that can stack independently of each other and
+*   of the interactive state. An input can be `invalid` AND `readonly` at the
+*   same time, optionally also `hover`ed.
+*
+* Compound states (`'invalid&hover'`, `'invalid&readonly&hover'`, etc.) are
+* built by listing 0..N modifiers followed by 0..1 interactive. The
+* `canonicalizeStateKey` helper enforces this ordering so that, e.g.,
+* `['hover', 'invalid']` and `['invalid', 'hover']` resolve to the same key.
+*/
+/**
+* Interactive atomics:
+*
+* - `hover`/`pressed` for pointer interaction.
+* - `focus-within` for containers that wrap a focusable child (e.g. an input
+*   wrapper).
+* - `focus-visible` for keyboard-only focus rings on focusable elements.
+*/
+const INTERACTIVE_ATOMICS = [
+	"hover",
+	"pressed",
+	"focus-within",
+	"focus-visible"
+];
+const MODIFIER_ATOMICS = [
+	"invalid",
+	"readonly",
+	"placeholder-shown",
+	"autofill",
+	"visited"
+];
+const INTERACTIVE_ATOMIC_SET = new Set(INTERACTIVE_ATOMICS);
+const MODIFIER_ATOMIC_SET = new Set(MODIFIER_ATOMICS);
+function isInteractiveAtomic(state) {
+	return INTERACTIVE_ATOMIC_SET.has(state);
+}
+function isModifierAtomic(state) {
+	return MODIFIER_ATOMIC_SET.has(state);
+}
+function isAtomicState(state) {
+	return isInteractiveAtomic(state) || isModifierAtomic(state);
+}
+/**
+* Maximum number of modifiers that may appear in a single compound state.
+* The resolver enumerates compounds up to `M^MAX_MODIFIERS_PER_COMPOUND × I`
+* (with the interactive slot optional), the docs-class enumeration matches,
+* and the StateBuilder picker prevents users from selecting more than this
+* many modifier checkboxes. Keeping all three in lock-step means there's
+* exactly one compound depth supported end-to-end.
+*/
+const MAX_MODIFIERS_PER_COMPOUND = 3;
+const STATE_PRIORITY_INDEX = new Map([
+	"visited",
+	"placeholder-shown",
+	"autofill",
+	"focus-within",
+	"focus-visible",
+	"hover",
+	"pressed",
+	"invalid",
+	"readonly"
+].map((atom, i) => [atom, i]));
+/**
+* Comparator usable with `Array.prototype.sort`. Atoms not in `STATE_PRIORITY`
+* sort to the front (weakest) — this only triggers for unknown strings; every
+* known `AtomicState` is in the priority array.
+*/
+function comparePriority(a, b) {
+	return (STATE_PRIORITY_INDEX.get(a) ?? -1) - (STATE_PRIORITY_INDEX.get(b) ?? -1);
+}
+//#endregion
+exports.INTERACTIVE_ATOMICS = INTERACTIVE_ATOMICS;
+exports.MAX_MODIFIERS_PER_COMPOUND = MAX_MODIFIERS_PER_COMPOUND;
+exports.MODIFIER_ATOMICS = MODIFIER_ATOMICS;
+exports.comparePriority = comparePriority;
+exports.isAtomicState = isAtomicState;
+exports.isInteractiveAtomic = isInteractiveAtomic;
+exports.isModifierAtomic = isModifierAtomic;

package/dist/automated-config/dist/types/StateAxis.d.cts

@@ -0,0 +1,70 @@
+
+//#region ../automated-config/dist/types/StateAxis.d.ts
+//#region src/types/StateAxis.d.ts
+/**
+ * Atomic-state taxonomy.
+ *
+ * Every interactive component reacts to a fixed set of "atomic" states, each
+ * belonging to one axis:
+ *
+ * - `interactive` — pointer/keyboard focus signals. At runtime at most one of
+ *   these is meaningfully "active" at a time on a given element (you can't
+ *   simultaneously hover and press distinctly enough to style separately, etc.).
+ *
+ * - `modifier` — semantic flags that can stack independently of each other and
+ *   of the interactive state. An input can be `invalid` AND `readonly` at the
+ *   same time, optionally also `hover`ed.
+ *
+ * Compound states (`'invalid&hover'`, `'invalid&readonly&hover'`, etc.) are
+ * built by listing 0..N modifiers followed by 0..1 interactive. The
+ * `canonicalizeStateKey` helper enforces this ordering so that, e.g.,
+ * `['hover', 'invalid']` and `['invalid', 'hover']` resolve to the same key.
+ */
+/**
+ * Interactive atomics:
+ *
+ * - `hover`/`pressed` for pointer interaction.
+ * - `focus-within` for containers that wrap a focusable child (e.g. an input
+ *   wrapper).
+ * - `focus-visible` for keyboard-only focus rings on focusable elements.
+ */
+declare const INTERACTIVE_ATOMICS: readonly ["hover", "pressed", "focus-within", "focus-visible"];
+declare const MODIFIER_ATOMICS: readonly ["invalid", "readonly", "placeholder-shown", "autofill", "visited"];
+type InteractiveAtomic = (typeof INTERACTIVE_ATOMICS)[number];
+type ModifierAtomic = (typeof MODIFIER_ATOMICS)[number];
+type AtomicState = InteractiveAtomic | ModifierAtomic;
+declare function isInteractiveAtomic(state: string): state is InteractiveAtomic;
+declare function isModifierAtomic(state: string): state is ModifierAtomic;
+declare function isAtomicState(state: string): state is AtomicState;
+/**
+ * Maximum number of modifiers that may appear in a single compound state.
+ * The resolver enumerates compounds up to `M^MAX_MODIFIERS_PER_COMPOUND × I`
+ * (with the interactive slot optional), the docs-class enumeration matches,
+ * and the StateBuilder picker prevents users from selecting more than this
+ * many modifier checkboxes. Keeping all three in lock-step means there's
+ * exactly one compound depth supported end-to-end.
+ */
+declare const MAX_MODIFIERS_PER_COMPOUND = 3;
+/**
+ * Global emission priority for the atomic taxonomy.
+ *
+ * Every atom selector contributes a uniform (0,1,0) of specificity (see
+ * `pseudoStateSelectors`), so a 2-atom compound at (0,3,0) strictly beats a
+ * 1-atom rule at (0,2,0) — cross-rank cascade is encoded in class-count
+ * specificity. Within a rank (e.g. two atoms simultaneously matching the
+ * same element) source order arbitrates: the resolver sorts a layer's
+ * `atomicStates` by index in this array, then emits in that order — meaning
+ * **later in the array = emits later = wins when multiple atoms match the
+ * same element**.
+ *
+ * The ordering is weakest → strongest. To bump an atom's priority, move it
+ * later in this array. Compound-state emission order is derived from this
+ * priority too (subset enumeration follows the modifier ordering here), so
+ * compound winners follow the same intuition.
+ *
+ * Legacy atoms (`focused`, `focused-keyboard`, `disabled`) are not in this
+ * list because they aren't part of `AtomicState`; their emission order is
+ * whatever a config's per-property `pseudoStates` array specifies.
+ */
+//#endregion
+export { type AtomicState, INTERACTIVE_ATOMICS, type InteractiveAtomic, MAX_MODIFIERS_PER_COMPOUND, MODIFIER_ATOMICS, type ModifierAtomic, isAtomicState, isInteractiveAtomic, isModifierAtomic };

package/dist/automated-config/dist/types/StateAxis.d.ts

@@ -0,0 +1,70 @@
+
+//#region ../automated-config/dist/types/StateAxis.d.ts
+//#region src/types/StateAxis.d.ts
+/**
+ * Atomic-state taxonomy.
+ *
+ * Every interactive component reacts to a fixed set of "atomic" states, each
+ * belonging to one axis:
+ *
+ * - `interactive` — pointer/keyboard focus signals. At runtime at most one of
+ *   these is meaningfully "active" at a time on a given element (you can't
+ *   simultaneously hover and press distinctly enough to style separately, etc.).
+ *
+ * - `modifier` — semantic flags that can stack independently of each other and
+ *   of the interactive state. An input can be `invalid` AND `readonly` at the
+ *   same time, optionally also `hover`ed.
+ *
+ * Compound states (`'invalid&hover'`, `'invalid&readonly&hover'`, etc.) are
+ * built by listing 0..N modifiers followed by 0..1 interactive. The
+ * `canonicalizeStateKey` helper enforces this ordering so that, e.g.,
+ * `['hover', 'invalid']` and `['invalid', 'hover']` resolve to the same key.
+ */
+/**
+ * Interactive atomics:
+ *
+ * - `hover`/`pressed` for pointer interaction.
+ * - `focus-within` for containers that wrap a focusable child (e.g. an input
+ *   wrapper).
+ * - `focus-visible` for keyboard-only focus rings on focusable elements.
+ */
+declare const INTERACTIVE_ATOMICS: readonly ["hover", "pressed", "focus-within", "focus-visible"];
+declare const MODIFIER_ATOMICS: readonly ["invalid", "readonly", "placeholder-shown", "autofill", "visited"];
+type InteractiveAtomic = (typeof INTERACTIVE_ATOMICS)[number];
+type ModifierAtomic = (typeof MODIFIER_ATOMICS)[number];
+type AtomicState = InteractiveAtomic | ModifierAtomic;
+declare function isInteractiveAtomic(state: string): state is InteractiveAtomic;
+declare function isModifierAtomic(state: string): state is ModifierAtomic;
+declare function isAtomicState(state: string): state is AtomicState;
+/**
+ * Maximum number of modifiers that may appear in a single compound state.
+ * The resolver enumerates compounds up to `M^MAX_MODIFIERS_PER_COMPOUND × I`
+ * (with the interactive slot optional), the docs-class enumeration matches,
+ * and the StateBuilder picker prevents users from selecting more than this
+ * many modifier checkboxes. Keeping all three in lock-step means there's
+ * exactly one compound depth supported end-to-end.
+ */
+declare const MAX_MODIFIERS_PER_COMPOUND = 3;
+/**
+ * Global emission priority for the atomic taxonomy.
+ *
+ * Every atom selector contributes a uniform (0,1,0) of specificity (see
+ * `pseudoStateSelectors`), so a 2-atom compound at (0,3,0) strictly beats a
+ * 1-atom rule at (0,2,0) — cross-rank cascade is encoded in class-count
+ * specificity. Within a rank (e.g. two atoms simultaneously matching the
+ * same element) source order arbitrates: the resolver sorts a layer's
+ * `atomicStates` by index in this array, then emits in that order — meaning
+ * **later in the array = emits later = wins when multiple atoms match the
+ * same element**.
+ *
+ * The ordering is weakest → strongest. To bump an atom's priority, move it
+ * later in this array. Compound-state emission order is derived from this
+ * priority too (subset enumeration follows the modifier ordering here), so
+ * compound winners follow the same intuition.
+ *
+ * Legacy atoms (`focused`, `focused-keyboard`, `disabled`) are not in this
+ * list because they aren't part of `AtomicState`; their emission order is
+ * whatever a config's per-property `pseudoStates` array specifies.
+ */
+//#endregion
+export { type AtomicState, INTERACTIVE_ATOMICS, type InteractiveAtomic, MAX_MODIFIERS_PER_COMPOUND, MODIFIER_ATOMICS, type ModifierAtomic, isAtomicState, isInteractiveAtomic, isModifierAtomic };