@yahoo/uds 3.156.2 → 3.157.1

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 };

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

@@ -0,0 +1,84 @@
+/*! © 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
+export { INTERACTIVE_ATOMICS, MAX_MODIFIERS_PER_COMPOUND, MODIFIER_ATOMICS, comparePriority, isAtomicState, isInteractiveAtomic, isModifierAtomic };

package/dist/automated-config/dist/utils/buildConfigSchema.cjs

@@ -1,10 +1,78 @@
 /*! © 2026 Yahoo, Inc. UDS v0.0.0-development */
 const require_componentStatePseudoStates = require("./componentStatePseudoStates.cjs");
 const require_generateSchemaKey = require("./generateSchemaKey.cjs");
+const require_resolvePropertyStates = require("./resolvePropertyStates.cjs");
 const require_variantConfigGuards = require("./variantConfigGuards.cjs");
 const require_util = require("../../../fixtures/src/util.cjs");
 //#region ../automated-config/dist/utils/buildConfigSchema.js
 /*! © 2026 Yahoo, Inc. UDS Default Config v0.0.0-development */
+/**
+* Builds the per-state schema entries for one property on one variant option.
+* Each state slot (rest, hover, invalid&hover, ...) gets the property's
+* default value as a starting point so the Configurator UI has something to
+* render before users tweak.
+*
+* Per-state CSS emission depends on the emit mode (`exhaustive` by default,
+* `selective` opt-in) and on the `isEnabled` flag this builder writes:
+*   - `rest` always emits in both modes (no flag needed; CSS gen treats rest
+*     as enabled).
+*   - Under EXHAUSTIVE (the default) on `atomicStates` layers, every declared
+*     non-rest state emits a rule regardless of `isEnabled`; its value is
+*     cascade-resolved (see `resolveSlotByCascade`), so there are no gaps.
+*     `isEnabled` there only selects which value a state resolves to, not
+*     whether it emits.
+*   - Under SELECTIVE (and legacy `pseudoStates`) emission, non-rest slots
+*     emit only when `isEnabled === true`.
+*   - `skipRestState` properties have no rest fallback, so every populated
+*     state slot must emit; we set `isEnabled: true` on each.
+*   - Otherwise, auto-populated non-rest slots ship with no flag — under
+*     selective they're off until a designer enables them via the
+*     configurator's per-property checkbox (which sets or clears this flag
+*     through the setter); under exhaustive they still emit via the cascade.
+*/
+function buildPropertyStateMap(layer, property, variantOption, excludedStates = []) {
+	const stateMap = {};
+	const excluded = new Set(excludedStates);
+	const states = require_resolvePropertyStates.resolvePropertyStates(layer, property);
+	const fixtureType = findFixtureType(property, variantOption);
+	const value = property.defaults[variantOption];
+	const skipRestState = property.skipRestState === true;
+	const isTextVariant = propertyVariesOnlyAtRest(property);
+	for (const state of states) {
+		if (excluded.has(state)) continue;
+		if (isTextVariant && state !== "rest") continue;
+		stateMap[state] = skipRestState ? {
+			type: fixtureType,
+			valueType: "alias",
+			value,
+			isEnabled: true
+		} : {
+			type: fixtureType,
+			valueType: "alias",
+			value
+		};
+	}
+	return stateMap;
+}
+/**
+* Whether a property's non-rest slots are stored SPARSELY — never pre-populated
+* by the schema builder, only persisted when a designer authors an explicit
+* per-state override (resolved via the cascade otherwise). `textVariant` is the
+* only such property today: its non-rest "Emphasized" overrides are created
+* lazily in the configurator rather than seeded for every state.
+*
+* Consulted by the schema builder ({@link buildPropertyStateMap}) to keep the
+* stored config compact. CSS emission does NOT special-case these properties:
+* exhaustive emission walks every declared state and resolves each through the
+* cascade (`resolveSlotByCascade`), so an authored non-rest override emits a
+* rule that renders while unauthored states resolve back to rest.
+*/
+function propertyVariesOnlyAtRest(property) {
+	return property.name === "textVariant";
+}
+function isOptionalInDefaultSchema(property) {
+	return property.optionalInDefaultSchema === true;
+}
 /** Resolves the fixture type by finding which value set contains the given value */
 function findFixtureTypeForValue(property, value) {
 	const index = property.values.findIndex((arr) => arr.includes(value));
@@ -17,13 +85,30 @@ function findFixtureTypeForValue(property, value) {
 function findFixtureType(property, variantKey) {
 	return findFixtureTypeForValue(property, property.defaults[variantKey]);
 }
-function appendPseudoStateVariables(variableObject, propertyKey, property, variantOption, excludedPseudoStates = []) {
-	if (!property.pseudoStates) return;
-	for (const pseudoState of require_componentStatePseudoStates.filterPseudoStatesByExclusion(property.pseudoStates, excludedPseudoStates)) variableObject[propertyKey][pseudoState] = {
-		type: findFixtureType(property, variantOption),
-		valueType: "alias",
-		value: property.defaults[variantOption]
-	};
+/**
+* Walk a set of layers and emit schema entries keyed by layer (no
+* component-state segment). Shared between `VariantConfigWithProperties` and
+* the optional top-level `layers` field on `VariantConfigWithComponentStates`.
+*/
+function emitUniversalLayerSchema(result, layers, variantKey, variantOption, subComponentName) {
+	for (const layerKey in layers) {
+		const layer = layers[layerKey];
+		const schemaKey = require_generateSchemaKey.generateSchemaKey({
+			variantKey,
+			variantValue: variantOption,
+			layer: layerKey,
+			subComponentName
+		});
+		result.variables[schemaKey] = {};
+		for (const propertyKey in layer.properties) {
+			const property = layer.properties[propertyKey];
+			if (isOptionalInDefaultSchema(property)) continue;
+			result.variables[schemaKey] = {
+				...result.variables[schemaKey],
+				[propertyKey]: buildPropertyStateMap(layer, property, variantOption)
+			};
+		}
+	}
 }
 /** Builds component schema from ComponentConfig at runtime */
 function buildConfigSchema(config) {
@@ -35,6 +120,7 @@ function buildConfigSchema(config) {
 	for (const variantKey in config.variants) {
 		const variantConfig = config.variants[variantKey];
 		for (const variantOption of variantConfig.options) if (require_variantConfigGuards.isVariantConfigWithComponentStates(variantConfig)) {
+			if (variantConfig.layers) emitUniversalLayerSchema(result, variantConfig.layers, variantKey, variantOption);
 			const componentStates = variantConfig.componentStates;
 			for (const componentStateKey in componentStates) {
 				const componentState = componentStates[componentStateKey];
@@ -50,16 +136,10 @@ function buildConfigSchema(config) {
 					result.variables[schemaKey] = {};
 					for (const propertyKey in layer.properties) {
 						const property = layer.properties[propertyKey];
-						const variableObject = { [propertyKey]: {} };
-						if (property?.skipRestState !== true) variableObject[propertyKey] = { rest: {
-							type: findFixtureType(property, variantOption),
-							valueType: "alias",
-							value: property.defaults[variantOption]
-						} };
-						appendPseudoStateVariables(variableObject, propertyKey, property, variantOption, require_componentStatePseudoStates.getExcludedPseudoStatesForComponentStateOption(componentState, componentStateOption));
+						if (isOptionalInDefaultSchema(property)) continue;
 						result.variables[schemaKey] = {
 							...result.variables[schemaKey],
-							...variableObject
+							[propertyKey]: buildPropertyStateMap(layer, property, variantOption, require_componentStatePseudoStates.getExcludedPseudoStatesForComponentStateOption(componentState, componentStateOption))
 						};
 					}
 				}
@@ -70,43 +150,17 @@ function buildConfigSchema(config) {
 				result.variables[variantSchemaKey] = result.variables[variantSchemaKey] ?? {};
 				for (const propertyKey in variantConfig.variantProperties) {
 					const property = variantConfig.variantProperties[propertyKey];
-					const variableObject = { [propertyKey]: {} };
-					if (property?.skipRestState !== true) variableObject[propertyKey] = { rest: {
-						type: findFixtureType(property, variantOption),
-						valueType: "alias",
-						value: property.defaults[variantOption]
-					} };
-					appendPseudoStateVariables(variableObject, propertyKey, property, variantOption);
+					if (isOptionalInDefaultSchema(property)) continue;
 					result.variables[variantSchemaKey] = {
 						...result.variables[variantSchemaKey],
-						...variableObject
-					};
-				}
-			}
-			const layers = variantConfig.layers;
-			for (const layerKey in layers) {
-				const layer = layers[layerKey];
-				const schemaKey = require_generateSchemaKey.generateSchemaKey({
-					variantKey,
-					variantValue: variantOption,
-					layer: layerKey
-				});
-				result.variables[schemaKey] = {};
-				for (const propertyKey in layer.properties) {
-					const property = layer.properties[propertyKey];
-					const variableObject = { [propertyKey]: {} };
-					if (property?.skipRestState !== true) variableObject[propertyKey] = { rest: {
-						type: findFixtureType(property, variantOption),
-						valueType: "alias",
-						value: property.defaults[variantOption]
-					} };
-					appendPseudoStateVariables(variableObject, propertyKey, property, variantOption);
-					result.variables[schemaKey] = {
-						...result.variables[schemaKey],
-						...variableObject
+						[propertyKey]: buildPropertyStateMap({
+							label: "",
+							properties: {}
+						}, property, variantOption)
 					};
 				}
 			}
+			emitUniversalLayerSchema(result, variantConfig.layers, variantKey, variantOption);
 		}
 	}
 	if (config.subComponents) {
@@ -115,6 +169,7 @@ function buildConfigSchema(config) {
 			const variantConfig = subComponents[subComponentKey].variants[variantKey];
 			result.defaults[variantKey] = variantConfig.default;
 			for (const variantOption of variantConfig.options) if (require_variantConfigGuards.isVariantConfigWithComponentStates(variantConfig)) {
+				if (variantConfig.layers) emitUniversalLayerSchema(result, variantConfig.layers, variantKey, variantOption, subComponentKey);
 				const componentStates = variantConfig.componentStates;
 				for (const componentStateKey in componentStates) {
 					const componentState = componentStates[componentStateKey];
@@ -131,47 +186,15 @@ function buildConfigSchema(config) {
 						result.variables[schemaKey] = {};
 						for (const propertyKey in layer.properties) {
 							const property = layer.properties[propertyKey];
-							const variableObject = { [propertyKey]: {} };
-							if (property?.skipRestState !== true) variableObject[propertyKey] = { rest: {
-								type: findFixtureType(property, variantOption),
-								valueType: "alias",
-								value: property.defaults[variantOption]
-							} };
-							appendPseudoStateVariables(variableObject, propertyKey, property, variantOption, require_componentStatePseudoStates.getExcludedPseudoStatesForComponentStateOption(componentState, componentStateOption));
+							if (isOptionalInDefaultSchema(property)) continue;
 							result.variables[schemaKey] = {
 								...result.variables[schemaKey],
-								...variableObject
+								[propertyKey]: buildPropertyStateMap(layer, property, variantOption, require_componentStatePseudoStates.getExcludedPseudoStatesForComponentStateOption(componentState, componentStateOption))
 							};
 						}
 					}
 				}
-			} else if (require_variantConfigGuards.isVariantConfigWithProperties(variantConfig)) {
-				const layers = variantConfig.layers;
-				for (const layerKey in layers) {
-					const layer = layers[layerKey];
-					const schemaKey = require_generateSchemaKey.generateSchemaKey({
-						variantKey,
-						variantValue: variantOption,
-						layer: layerKey,
-						subComponentName: subComponentKey
-					});
-					result.variables[schemaKey] = {};
-					for (const propertyKey in layer.properties) {
-						const property = layer.properties[propertyKey];
-						const variableObject = { [propertyKey]: {} };
-						if (property?.skipRestState !== true) variableObject[propertyKey] = { rest: {
-							type: findFixtureType(property, variantOption),
-							valueType: "alias",
-							value: property.defaults[variantOption]
-						} };
-						appendPseudoStateVariables(variableObject, propertyKey, property, variantOption);
-						result.variables[schemaKey] = {
-							...result.variables[schemaKey],
-							...variableObject
-						};
-					}
-				}
-			}
+			} else if (require_variantConfigGuards.isVariantConfigWithProperties(variantConfig)) emitUniversalLayerSchema(result, variantConfig.layers, variantKey, variantOption, subComponentKey);
 		}
 	}
 	return result;

package/dist/automated-config/dist/utils/buildConfigSchema.d.cts

@@ -1,27 +1,54 @@
 
+import { AtomicState } from "../types/StateAxis.cjs";
 import { BannerInnerShadowOption, ElevationAlias, ShadowVariant, ShadowVariantConfig, ShadowVariantWithInvert } from "../../../types/dist/index.cjs";
 import { ArbitraryFixtures, InferArbitraryType } from "../../../fixtures/dist/index.cjs";
+import { ConfigurablePropertiesName, SelectedConfigurableProperty } from "../properties.cjs";
 import { AllPossibleProperties, ComponentConfig, ComponentStateConfig, LayerConfig, PossibleStates, VariantConfig, VariantConfigWithComponentStates, VariantConfigWithProperties } from "../types/ComponentConfig.cjs";
 import { SchemaStateValue } from "../types/ConfigSchema.cjs";
-import { ConfigurablePropertiesName, SelectedConfigurableProperty } from "../properties.cjs";
 import { OmitIndexSignature, SimplifyDeep, UnionToIntersection, WritableDeep } from "type-fest";
 
 //#region ../automated-config/dist/utils/buildConfigSchema.d.ts
-//#region src/utils/buildConfigSchema.d.ts
+type OptionalInDefaultSchemaPropKeys<Props extends Record<string, SelectedConfigurableProperty<ConfigurablePropertiesName, string>>> = { [K in keyof Props]: Props[K] extends {
+  optionalInDefaultSchema: true;
+} ? K : never }[keyof Props];
+type RequiredInDefaultSchemaPropKeys<Props extends Record<string, SelectedConfigurableProperty<ConfigurablePropertiesName, string>>> = { [K in keyof Props]: Props[K] extends {
+  optionalInDefaultSchema: true;
+} ? never : K }[keyof Props];
+type InferredLayerPropertyMap<Props extends Record<string, SelectedConfigurableProperty<ConfigurablePropertiesName, string>>, Layer> = { [PropKey in RequiredInDefaultSchemaPropKeys<Props>]: InferredPropertyStates<Props[PropKey], Layer> } & { [PropKey in OptionalInDefaultSchemaPropKeys<Props>]?: InferredPropertyStates<Props[PropKey], Layer> };
 /** Infers default option values from all component variants */
 type InferredDefaults<C extends ComponentConfig> = (C['variants'] extends NonNullable<ComponentConfig['variants']> ? { [VarKey in keyof C['variants']]: C['variants'][VarKey]['options'][number] } : {}) & (C['subComponents'] extends NonNullable<ComponentConfig['subComponents']> ? UnionToIntersection<{ [SubCompKey in keyof C['subComponents']]: { [VarKey in keyof C['subComponents'][SubCompKey]['variants']]: C['subComponents'][SubCompKey]['variants'][VarKey]['options'][number] } }[keyof C['subComponents']]> : {});
 /** Infers type-safe schema value structure for a configurable property */
 type InferredPropertySchema<Prop extends SelectedConfigurableProperty<ConfigurablePropertiesName, string>> = {
   type: Prop['typeOfFixture'][number];
-  valueType: 'alias' | 'custom';
+  valueType: 'alias' | 'custom'; /** See SchemaStateValue.isEnabled — opt-in flag for non-rest CSS emission. */
+  isEnabled?: boolean;
   value: Prop['name'] extends 'shadow' ? ShadowVariant | ShadowVariantConfig | ElevationAlias : Prop['name'] extends 'insetShadow' ? ShadowVariantWithInvert | ShadowVariantConfig : Prop['name'] extends 'bannerInnerShadow' ? BannerInnerShadowOption : Prop['values'][number][number] | (Extract<Prop['typeOfFixture'][number], ArbitraryFixtures> extends never ? never : InferArbitraryType<Extract<Prop['typeOfFixture'][number], ArbitraryFixtures>>);
 };
-/** Infers state-to-schema mappings for a property (rest, hover, pressed, focus, etc.) */
-type InferredPropertyStates<Prop extends SelectedConfigurableProperty<ConfigurablePropertiesName, string>> = (Prop['skipRestState'] extends true ? {} : {
+/**
+ * Infers state-to-schema mappings for a property: rest plus every state the
+ * resolver will produce. Sources are additive:
+ *
+ *   - Per-property `pseudoStates` (legacy).
+ *   - Per-layer `atomicStates` (new). Each declared atom yields a required
+ *     entry; auto-generated compounds (modifier × interactive, modifier ×
+ *     modifier × interactive, etc.) yield optional entries because the resolver
+ *     skips incompatible pairs. Marking compounds optional lets the data —
+ *     which contains exactly the canonical, non-skipped subset — satisfy the
+ *     wider type.
+ *
+ * `textVariant` is special-cased: only `rest` is required. Non-rest slots are
+ * optional because the configurator only stores them when the designer
+ * explicitly enables a per-state override; otherwise they're absent and the
+ * value resolves via the CSS cascade. See `buildPropertyStateMap` for the
+ * runtime mirror of this typing.
+ */
+type InferredPropertyStates<Prop extends SelectedConfigurableProperty<ConfigurablePropertiesName, string>, Layer = unknown> = (Prop['skipRestState'] extends true ? {} : {
   rest: InferredPropertySchema<Prop>;
-}) & (Prop extends {
+}) & (Layer extends {
+  atomicStates: infer AS extends readonly AtomicState[];
+} ? { [K in AS[number]]?: InferredPropertySchema<Prop> } & { [K in `${string}&${string}`]?: InferredPropertySchema<Prop> } : Prop extends {
   pseudoStates: infer PS extends PossibleStates[];
-} ? { [K in PS[number]]: InferredPropertySchema<Prop> } : {});
+} ? Prop['name'] extends 'textVariant' ? { [K in PS[number]]?: InferredPropertySchema<Prop> } : { [K in PS[number]]: InferredPropertySchema<Prop> } : {});
 type GetExcludedPseudoStatesForOption<StateConfig extends ComponentStateConfig, StateOption extends string> = StateConfig extends {
   excludePseudoStatesForOptions?: infer Exclusions extends Partial<Record<string, readonly PossibleStates[]>>;
 } ? StateOption extends keyof Exclusions ? Exclusions[StateOption] : undefined : undefined;
@@ -30,22 +57,24 @@ type InferredPropertyStatesForOption<Prop extends SelectedConfigurableProperty<C
   rest: InferredPropertySchema<Prop>;
 }) & (Prop extends {
   pseudoStates: infer PS extends PossibleStates[];
-} ? { [K in Exclude<PS[number], ExcludedPseudoStates extends readonly PossibleStates[] ? ExcludedPseudoStates[number] : never>]: InferredPropertySchema<Prop> } : {});
+} ? Prop['name'] extends 'textVariant' ? { [K in Exclude<PS[number], ExcludedPseudoStates extends readonly PossibleStates[] ? ExcludedPseudoStates[number] : never>]?: InferredPropertySchema<Prop> } : { [K in Exclude<PS[number], ExcludedPseudoStates extends readonly PossibleStates[] ? ExcludedPseudoStates[number] : never>]: InferredPropertySchema<Prop> } : {});
 /** Infers property-to-states mappings for a layer's properties */
 type InferredLayerProperties<Layer> = Layer extends LayerConfig ? Layer extends {
   properties: infer Props extends LayerConfig['properties'];
-} ? { [PropKey in keyof Props]: InferredPropertyStates<Props[PropKey]> } : {} : {};
+} ? InferredLayerPropertyMap<Props, Layer> : {} : {};
 type InferredLayerPropertiesForOption<Layer, ExcludedPseudoStates extends readonly PossibleStates[] | undefined> = Layer extends LayerConfig ? Layer extends {
   properties: infer Props extends LayerConfig['properties'];
-} ? { [PropKey in keyof Props]: InferredPropertyStatesForOption<Props[PropKey], ExcludedPseudoStates> } : {} : {};
+} ? { [PropKey in RequiredInDefaultSchemaPropKeys<Props>]: InferredPropertyStatesForOption<Props[PropKey], ExcludedPseudoStates> } & { [PropKey in OptionalInDefaultSchemaPropKeys<Props>]?: InferredPropertyStatesForOption<Props[PropKey], ExcludedPseudoStates> } : {} : {};
 /** Generates schema key → properties mappings for a variant's layers or component states */
 type InferredSchemaMap<VarKey extends string, VarConfig extends VariantConfig, LayersOrStates extends NonNullable<VariantConfigWithComponentStates['componentStates']> | NonNullable<VariantConfigWithProperties['layers']>, Prefix extends string = ''> = LayersOrStates extends NonNullable<VariantConfigWithComponentStates['componentStates']> ? UnionToIntersection<{ [StateKey in keyof OmitIndexSignature<LayersOrStates>]: UnionToIntersection<{ [StateOption in LayersOrStates[StateKey]['options'][number]]: { [LayerKey in keyof OmitIndexSignature<LayersOrStates[StateKey]['layers']> as `${Prefix}${VarKey}/${VarConfig['options'][number]}/${StateKey & string}/${StateOption}/${LayerKey & string}`]: InferredLayerPropertiesForOption<LayersOrStates[StateKey]['layers'][LayerKey], GetExcludedPseudoStatesForOption<LayersOrStates[StateKey], StateOption>> } }[LayersOrStates[StateKey]['options'][number]]> }[keyof OmitIndexSignature<LayersOrStates>]> : { [LayerKey in keyof OmitIndexSignature<LayersOrStates> as `${Prefix}${VarKey}/${VarConfig['options'][number]}/${LayerKey & string}`]: InferredLayerProperties<LayersOrStates[LayerKey]> };
-type InferredVariantLevelProperties<Props extends Record<string, SelectedConfigurableProperty<ConfigurablePropertiesName, string>>> = { [PropKey in keyof Props]: InferredPropertyStates<Props[PropKey]> };
+type InferredVariantLevelProperties<Props extends Record<string, SelectedConfigurableProperty<ConfigurablePropertiesName, string>>> = { [PropKey in RequiredInDefaultSchemaPropKeys<Props>]: InferredPropertyStates<Props[PropKey]> } & { [PropKey in OptionalInDefaultSchemaPropKeys<Props>]?: InferredPropertyStates<Props[PropKey]> };
 type InferredVariantPropertiesMap<VarKey extends string, VarConfig extends VariantConfigWithProperties, Prefix extends string = ''> = VarConfig extends {
   variantProperties: infer Props extends Record<string, SelectedConfigurableProperty<ConfigurablePropertiesName, string>>;
 } ? { [Option in VarConfig['options'][number] as `${Prefix}${VarKey}/${Option}`]: InferredVariantLevelProperties<Props> } : {};
 /** Routes to appropriate schema map generator based on variant configuration type */
-type InferredVariablesFilter<VarKey extends string, VarConfig extends VariantConfig, Prefix extends string = ''> = VarConfig extends VariantConfigWithComponentStates ? InferredSchemaMap<VarKey, VarConfig, VarConfig['componentStates'], Prefix> : VarConfig extends VariantConfigWithProperties ? InferredSchemaMap<VarKey, VarConfig, VarConfig['layers'], Prefix> & InferredVariantPropertiesMap<VarKey, VarConfig, Prefix> : {};
+type InferredVariablesFilter<VarKey extends string, VarConfig extends VariantConfig, Prefix extends string = ''> = VarConfig extends VariantConfigWithComponentStates ? InferredSchemaMap<VarKey, VarConfig, VarConfig['componentStates'], Prefix> & (VarConfig extends {
+  layers: infer L;
+} ? L extends NonNullable<VariantConfigWithProperties['layers']> ? InferredSchemaMap<VarKey, VarConfig, L, Prefix> : {} : {}) : VarConfig extends VariantConfigWithProperties ? InferredSchemaMap<VarKey, VarConfig, VarConfig['layers'], Prefix> & InferredVariantPropertiesMap<VarKey, VarConfig, Prefix> : {};
 /** Collects all schema mappings from component variants and subComponents */
 type InferredVariables<C extends ComponentConfig> = (C['variants'] extends NonNullable<ComponentConfig['variants']> ? UnionToIntersection<{ [VarKey in keyof C['variants']]: InferredVariablesFilter<VarKey & string, C['variants'][VarKey]> }[keyof C['variants']]> : {}) & (C['subComponents'] extends NonNullable<ComponentConfig['subComponents']> ? UnionToIntersection<{ [SubCompKey in keyof C['subComponents']]: UnionToIntersection<{ [VarKey in keyof C['subComponents'][SubCompKey]['variants']]: InferredVariablesFilter<VarKey & string, C['subComponents'][SubCompKey]['variants'][VarKey], `${SubCompKey & string}/`> }[keyof C['subComponents'][SubCompKey]['variants']]> }[keyof C['subComponents']]> : {});
 /** Component schema with inferred defaults and variable schema mappings */

package/dist/automated-config/dist/utils/buildConfigSchema.d.ts

@@ -1,27 +1,54 @@
 
+import { AtomicState } from "../types/StateAxis.js";
 import { BannerInnerShadowOption, ElevationAlias, ShadowVariant, ShadowVariantConfig, ShadowVariantWithInvert } from "../../../types/dist/index.js";
 import { ArbitraryFixtures, InferArbitraryType } from "../../../fixtures/dist/index.js";
+import { ConfigurablePropertiesName, SelectedConfigurableProperty } from "../properties.js";
 import { AllPossibleProperties, ComponentConfig, ComponentStateConfig, LayerConfig, PossibleStates, VariantConfig, VariantConfigWithComponentStates, VariantConfigWithProperties } from "../types/ComponentConfig.js";
 import { SchemaStateValue } from "../types/ConfigSchema.js";
-import { ConfigurablePropertiesName, SelectedConfigurableProperty } from "../properties.js";
 import { OmitIndexSignature, SimplifyDeep, UnionToIntersection, WritableDeep } from "type-fest";
 
 //#region ../automated-config/dist/utils/buildConfigSchema.d.ts
-//#region src/utils/buildConfigSchema.d.ts
+type OptionalInDefaultSchemaPropKeys<Props extends Record<string, SelectedConfigurableProperty<ConfigurablePropertiesName, string>>> = { [K in keyof Props]: Props[K] extends {
+  optionalInDefaultSchema: true;
+} ? K : never }[keyof Props];
+type RequiredInDefaultSchemaPropKeys<Props extends Record<string, SelectedConfigurableProperty<ConfigurablePropertiesName, string>>> = { [K in keyof Props]: Props[K] extends {
+  optionalInDefaultSchema: true;
+} ? never : K }[keyof Props];
+type InferredLayerPropertyMap<Props extends Record<string, SelectedConfigurableProperty<ConfigurablePropertiesName, string>>, Layer> = { [PropKey in RequiredInDefaultSchemaPropKeys<Props>]: InferredPropertyStates<Props[PropKey], Layer> } & { [PropKey in OptionalInDefaultSchemaPropKeys<Props>]?: InferredPropertyStates<Props[PropKey], Layer> };
 /** Infers default option values from all component variants */
 type InferredDefaults<C extends ComponentConfig> = (C['variants'] extends NonNullable<ComponentConfig['variants']> ? { [VarKey in keyof C['variants']]: C['variants'][VarKey]['options'][number] } : {}) & (C['subComponents'] extends NonNullable<ComponentConfig['subComponents']> ? UnionToIntersection<{ [SubCompKey in keyof C['subComponents']]: { [VarKey in keyof C['subComponents'][SubCompKey]['variants']]: C['subComponents'][SubCompKey]['variants'][VarKey]['options'][number] } }[keyof C['subComponents']]> : {});
 /** Infers type-safe schema value structure for a configurable property */
 type InferredPropertySchema<Prop extends SelectedConfigurableProperty<ConfigurablePropertiesName, string>> = {
   type: Prop['typeOfFixture'][number];
-  valueType: 'alias' | 'custom';
+  valueType: 'alias' | 'custom'; /** See SchemaStateValue.isEnabled — opt-in flag for non-rest CSS emission. */
+  isEnabled?: boolean;
   value: Prop['name'] extends 'shadow' ? ShadowVariant | ShadowVariantConfig | ElevationAlias : Prop['name'] extends 'insetShadow' ? ShadowVariantWithInvert | ShadowVariantConfig : Prop['name'] extends 'bannerInnerShadow' ? BannerInnerShadowOption : Prop['values'][number][number] | (Extract<Prop['typeOfFixture'][number], ArbitraryFixtures> extends never ? never : InferArbitraryType<Extract<Prop['typeOfFixture'][number], ArbitraryFixtures>>);
 };
-/** Infers state-to-schema mappings for a property (rest, hover, pressed, focus, etc.) */
-type InferredPropertyStates<Prop extends SelectedConfigurableProperty<ConfigurablePropertiesName, string>> = (Prop['skipRestState'] extends true ? {} : {
+/**
+ * Infers state-to-schema mappings for a property: rest plus every state the
+ * resolver will produce. Sources are additive:
+ *
+ *   - Per-property `pseudoStates` (legacy).
+ *   - Per-layer `atomicStates` (new). Each declared atom yields a required
+ *     entry; auto-generated compounds (modifier × interactive, modifier ×
+ *     modifier × interactive, etc.) yield optional entries because the resolver
+ *     skips incompatible pairs. Marking compounds optional lets the data —
+ *     which contains exactly the canonical, non-skipped subset — satisfy the
+ *     wider type.
+ *
+ * `textVariant` is special-cased: only `rest` is required. Non-rest slots are
+ * optional because the configurator only stores them when the designer
+ * explicitly enables a per-state override; otherwise they're absent and the
+ * value resolves via the CSS cascade. See `buildPropertyStateMap` for the
+ * runtime mirror of this typing.
+ */
+type InferredPropertyStates<Prop extends SelectedConfigurableProperty<ConfigurablePropertiesName, string>, Layer = unknown> = (Prop['skipRestState'] extends true ? {} : {
   rest: InferredPropertySchema<Prop>;
-}) & (Prop extends {
+}) & (Layer extends {
+  atomicStates: infer AS extends readonly AtomicState[];
+} ? { [K in AS[number]]?: InferredPropertySchema<Prop> } & { [K in `${string}&${string}`]?: InferredPropertySchema<Prop> } : Prop extends {
   pseudoStates: infer PS extends PossibleStates[];
-} ? { [K in PS[number]]: InferredPropertySchema<Prop> } : {});
+} ? Prop['name'] extends 'textVariant' ? { [K in PS[number]]?: InferredPropertySchema<Prop> } : { [K in PS[number]]: InferredPropertySchema<Prop> } : {});
 type GetExcludedPseudoStatesForOption<StateConfig extends ComponentStateConfig, StateOption extends string> = StateConfig extends {
   excludePseudoStatesForOptions?: infer Exclusions extends Partial<Record<string, readonly PossibleStates[]>>;
 } ? StateOption extends keyof Exclusions ? Exclusions[StateOption] : undefined : undefined;
@@ -30,22 +57,24 @@ type InferredPropertyStatesForOption<Prop extends SelectedConfigurableProperty<C
   rest: InferredPropertySchema<Prop>;
 }) & (Prop extends {
   pseudoStates: infer PS extends PossibleStates[];
-} ? { [K in Exclude<PS[number], ExcludedPseudoStates extends readonly PossibleStates[] ? ExcludedPseudoStates[number] : never>]: InferredPropertySchema<Prop> } : {});
+} ? Prop['name'] extends 'textVariant' ? { [K in Exclude<PS[number], ExcludedPseudoStates extends readonly PossibleStates[] ? ExcludedPseudoStates[number] : never>]?: InferredPropertySchema<Prop> } : { [K in Exclude<PS[number], ExcludedPseudoStates extends readonly PossibleStates[] ? ExcludedPseudoStates[number] : never>]: InferredPropertySchema<Prop> } : {});
 /** Infers property-to-states mappings for a layer's properties */
 type InferredLayerProperties<Layer> = Layer extends LayerConfig ? Layer extends {
   properties: infer Props extends LayerConfig['properties'];
-} ? { [PropKey in keyof Props]: InferredPropertyStates<Props[PropKey]> } : {} : {};
+} ? InferredLayerPropertyMap<Props, Layer> : {} : {};
 type InferredLayerPropertiesForOption<Layer, ExcludedPseudoStates extends readonly PossibleStates[] | undefined> = Layer extends LayerConfig ? Layer extends {
   properties: infer Props extends LayerConfig['properties'];
-} ? { [PropKey in keyof Props]: InferredPropertyStatesForOption<Props[PropKey], ExcludedPseudoStates> } : {} : {};
+} ? { [PropKey in RequiredInDefaultSchemaPropKeys<Props>]: InferredPropertyStatesForOption<Props[PropKey], ExcludedPseudoStates> } & { [PropKey in OptionalInDefaultSchemaPropKeys<Props>]?: InferredPropertyStatesForOption<Props[PropKey], ExcludedPseudoStates> } : {} : {};
 /** Generates schema key → properties mappings for a variant's layers or component states */
 type InferredSchemaMap<VarKey extends string, VarConfig extends VariantConfig, LayersOrStates extends NonNullable<VariantConfigWithComponentStates['componentStates']> | NonNullable<VariantConfigWithProperties['layers']>, Prefix extends string = ''> = LayersOrStates extends NonNullable<VariantConfigWithComponentStates['componentStates']> ? UnionToIntersection<{ [StateKey in keyof OmitIndexSignature<LayersOrStates>]: UnionToIntersection<{ [StateOption in LayersOrStates[StateKey]['options'][number]]: { [LayerKey in keyof OmitIndexSignature<LayersOrStates[StateKey]['layers']> as `${Prefix}${VarKey}/${VarConfig['options'][number]}/${StateKey & string}/${StateOption}/${LayerKey & string}`]: InferredLayerPropertiesForOption<LayersOrStates[StateKey]['layers'][LayerKey], GetExcludedPseudoStatesForOption<LayersOrStates[StateKey], StateOption>> } }[LayersOrStates[StateKey]['options'][number]]> }[keyof OmitIndexSignature<LayersOrStates>]> : { [LayerKey in keyof OmitIndexSignature<LayersOrStates> as `${Prefix}${VarKey}/${VarConfig['options'][number]}/${LayerKey & string}`]: InferredLayerProperties<LayersOrStates[LayerKey]> };
-type InferredVariantLevelProperties<Props extends Record<string, SelectedConfigurableProperty<ConfigurablePropertiesName, string>>> = { [PropKey in keyof Props]: InferredPropertyStates<Props[PropKey]> };
+type InferredVariantLevelProperties<Props extends Record<string, SelectedConfigurableProperty<ConfigurablePropertiesName, string>>> = { [PropKey in RequiredInDefaultSchemaPropKeys<Props>]: InferredPropertyStates<Props[PropKey]> } & { [PropKey in OptionalInDefaultSchemaPropKeys<Props>]?: InferredPropertyStates<Props[PropKey]> };
 type InferredVariantPropertiesMap<VarKey extends string, VarConfig extends VariantConfigWithProperties, Prefix extends string = ''> = VarConfig extends {
   variantProperties: infer Props extends Record<string, SelectedConfigurableProperty<ConfigurablePropertiesName, string>>;
 } ? { [Option in VarConfig['options'][number] as `${Prefix}${VarKey}/${Option}`]: InferredVariantLevelProperties<Props> } : {};
 /** Routes to appropriate schema map generator based on variant configuration type */
-type InferredVariablesFilter<VarKey extends string, VarConfig extends VariantConfig, Prefix extends string = ''> = VarConfig extends VariantConfigWithComponentStates ? InferredSchemaMap<VarKey, VarConfig, VarConfig['componentStates'], Prefix> : VarConfig extends VariantConfigWithProperties ? InferredSchemaMap<VarKey, VarConfig, VarConfig['layers'], Prefix> & InferredVariantPropertiesMap<VarKey, VarConfig, Prefix> : {};
+type InferredVariablesFilter<VarKey extends string, VarConfig extends VariantConfig, Prefix extends string = ''> = VarConfig extends VariantConfigWithComponentStates ? InferredSchemaMap<VarKey, VarConfig, VarConfig['componentStates'], Prefix> & (VarConfig extends {
+  layers: infer L;
+} ? L extends NonNullable<VariantConfigWithProperties['layers']> ? InferredSchemaMap<VarKey, VarConfig, L, Prefix> : {} : {}) : VarConfig extends VariantConfigWithProperties ? InferredSchemaMap<VarKey, VarConfig, VarConfig['layers'], Prefix> & InferredVariantPropertiesMap<VarKey, VarConfig, Prefix> : {};
 /** Collects all schema mappings from component variants and subComponents */
 type InferredVariables<C extends ComponentConfig> = (C['variants'] extends NonNullable<ComponentConfig['variants']> ? UnionToIntersection<{ [VarKey in keyof C['variants']]: InferredVariablesFilter<VarKey & string, C['variants'][VarKey]> }[keyof C['variants']]> : {}) & (C['subComponents'] extends NonNullable<ComponentConfig['subComponents']> ? UnionToIntersection<{ [SubCompKey in keyof C['subComponents']]: UnionToIntersection<{ [VarKey in keyof C['subComponents'][SubCompKey]['variants']]: InferredVariablesFilter<VarKey & string, C['subComponents'][SubCompKey]['variants'][VarKey], `${SubCompKey & string}/`> }[keyof C['subComponents'][SubCompKey]['variants']]> }[keyof C['subComponents']]> : {});
 /** Component schema with inferred defaults and variable schema mappings */