@yahoo/uds 3.156.1 → 3.157.0

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

@@ -0,0 +1,122 @@
+/*! © 2026 Yahoo, Inc. UDS v0.0.0-development */
+const require_StateAxis = require("../types/StateAxis.cjs");
+const require_canonicalizeStateKey = require("./canonicalizeStateKey.cjs");
+//#region ../automated-config/dist/utils/pseudoStateSelectors.js
+/*! © 2026 Yahoo, Inc. UDS Default Config v0.0.0-development */
+const LEGACY_STATE_ATOMS = new Set([
+	"disabled",
+	"focused",
+	"focused-keyboard"
+]);
+function isKnownStateAtom(atom) {
+	return require_StateAxis.isAtomicState(atom) || LEGACY_STATE_ATOMS.has(atom);
+}
+/**
+* Each atom selector contributes exactly (0,1,0) to specificity. The base
+* component class adds another (0,1,0), so a full rule's specificity is
+* `(0, 1 + atom-count, 0)`:
+*
+*   rest        → (0,1,0)  e.g. `.uds-input-...root`
+*   1-atom      → (0,2,0)  e.g. `.uds-input-...root:hover...`
+*   2-atom      → (0,3,0)  e.g. `.uds-input-...root:has(...):hover...`
+*   3-atom      → (0,4,0)
+*   4-atom      → (0,5,0)
+*
+* Cross-rank cascade (compound beats atom beats rest) is therefore encoded
+* in CSS class-count specificity, not source order — making the cascade-
+* cancellation feature robust to any tool that reorders rules within a
+* stylesheet. Within a rank (e.g. `:hover` vs `:focus-visible`, both
+* (0,2,0)) source order still arbitrates; the resolver computes intra-rank
+* order inline from `STATE_PRIORITY`. See {@link resolvePropertyStates}.
+*
+* Why each entry is (0,1,0):
+*
+* - `:hover` / `:active` / `:focus*` / `:visited` are single pseudo-classes,
+*   each (0,1,0).
+* - `:hover` and `:active` carry a `:where(:not(...))` blocker so the rule
+*   doesn't match when the element is also active/disabled. The outer
+*   `:where()` zeros the `:not(...)` contribution, leaving the bare pseudo-
+*   class's (0,1,0) as the only contributor.
+* - `:is(:disabled, :has(:disabled))` takes the max specificity of its
+*   args; both are (0,1,0), so the whole is (0,1,0).
+* - `:has(...)` selectors take the specificity of their arg's most specific
+*   complex selector. Arguments are pseudo-classes or attribute selectors at
+*   (0,1,0); where a form-control scope is also needed (e.g. `readonly` —
+*   non-form-control elements default to `:read-only` per spec, so a bare
+*   `:has(:read-only)` matches any container with DIV/SPAN children), the
+*   scope goes inside `:where(...)` so its (0,0,1) type-selector contribution
+*   is zeroed.
+*
+* **Consumer override ergonomics:** a plain `.my-input:hover` is (0,2,0),
+* which ties library 1-atom rules at (0,2,0); source order decides. To
+* unconditionally beat the library, consumers need (0,3,0) (e.g.
+* `.scope .my-input:hover` or `.my-input.my-input:hover`).
+*/
+const ATOMIC_SELECTORS = {
+	hover: ":hover:where(:not(:active, :disabled, :has(:disabled)))",
+	pressed: ":active:where(:not(:disabled, :has(:disabled)))",
+	disabled: ":is(:disabled, :has(:disabled))",
+	visited: ":visited",
+	focused: ":focus",
+	"focus-within": ":focus-within",
+	"focus-visible": ":focus-visible",
+	"focused-keyboard": ":focus-visible",
+	readonly: ":has(:read-only:where(input, textarea))",
+	invalid: ":has([aria-invalid=\"true\"])",
+	"placeholder-shown": ":has(:placeholder-shown)",
+	autofill: ":has(:autofill, :-webkit-autofill)"
+};
+const ATOMIC_DOCS_CLASSES = {
+	hover: "hover",
+	pressed: "active",
+	disabled: "has-disabled",
+	visited: "visited",
+	focused: "focus",
+	"focus-within": "focus-within",
+	"focus-visible": "focus-visible",
+	"focused-keyboard": "focus-visible",
+	readonly: "input-readonly",
+	invalid: "has-input-invalid",
+	"placeholder-shown": "has-input-placeholder-shown",
+	autofill: "has-input-autofill"
+};
+/**
+* Returns the CSS pseudo-selector string for a state key.
+*
+* - `'rest'`, `''`, and fully-unknown keys return `''`. An unknown atom inside
+*   an otherwise-known compound is skipped (the known atoms still contribute) —
+*   but callers only pass canonical validated keys, so that case doesn't arise
+*   in practice.
+* - Atomic keys return their entry from {@link ATOMIC_SELECTORS}.
+* - Compound keys (`'a&b'`) return the concatenation of each atomic selector
+*   in the order they appear in the key.
+*/
+function getStateSelector(stateKey) {
+	const atoms = require_canonicalizeStateKey.splitStateKey(stateKey);
+	if (atoms.length === 0) return "";
+	let selector = "";
+	for (const atom of atoms) if (isKnownStateAtom(atom)) selector += ATOMIC_SELECTORS[atom];
+	return selector;
+}
+/**
+* Returns the docs-mode class name for a state key, used to force-trigger
+* pseudo-states in docs/Storybook previews.
+*
+* - `'rest'`, `''`, and fully-unknown keys return `''`. An unknown atom inside
+*   an otherwise-known compound is skipped (the known atoms still contribute) —
+*   but callers only pass canonical validated keys, so that case doesn't arise
+*   in practice.
+* - Atomic keys return their entry from {@link ATOMIC_DOCS_CLASSES}.
+* - Compound keys join atomic docs classes with `'-and-'`.
+*/
+function getStateDocsClass(stateKey) {
+	const atoms = require_canonicalizeStateKey.splitStateKey(stateKey);
+	if (atoms.length === 0) return "";
+	const parts = [];
+	for (const atom of atoms) if (isKnownStateAtom(atom)) parts.push(ATOMIC_DOCS_CLASSES[atom]);
+	return parts.join("-and-");
+}
+//#endregion
+exports.getStateDocsClass = getStateDocsClass;
+exports.getStateSelector = getStateSelector;
+exports.isKnownStateAtom = isKnownStateAtom;

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

@@ -0,0 +1,80 @@
+
+import { AtomicState } from "../types/StateAxis.cjs";
+
+//#region ../automated-config/dist/utils/pseudoStateSelectors.d.ts
+//#region src/utils/pseudoStateSelectors.d.ts
+/**
+ * Legacy atom names accepted by the CSS generator + docs-mode map for
+ * unmigrated configs. They aren't composable through `StateAxis`, so the new
+ * resolver/StateBuilder never emit them.
+ */
+type LegacyStateAtom = 'disabled' | 'focused' | 'focused-keyboard';
+type KnownStateAtom = AtomicState | LegacyStateAtom;
+declare function isKnownStateAtom(atom: string): atom is KnownStateAtom;
+/**
+ * Each atom selector contributes exactly (0,1,0) to specificity. The base
+ * component class adds another (0,1,0), so a full rule's specificity is
+ * `(0, 1 + atom-count, 0)`:
+ *
+ *   rest        → (0,1,0)  e.g. `.uds-input-...root`
+ *   1-atom      → (0,2,0)  e.g. `.uds-input-...root:hover...`
+ *   2-atom      → (0,3,0)  e.g. `.uds-input-...root:has(...):hover...`
+ *   3-atom      → (0,4,0)
+ *   4-atom      → (0,5,0)
+ *
+ * Cross-rank cascade (compound beats atom beats rest) is therefore encoded
+ * in CSS class-count specificity, not source order — making the cascade-
+ * cancellation feature robust to any tool that reorders rules within a
+ * stylesheet. Within a rank (e.g. `:hover` vs `:focus-visible`, both
+ * (0,2,0)) source order still arbitrates; the resolver computes intra-rank
+ * order inline from `STATE_PRIORITY`. See {@link resolvePropertyStates}.
+ *
+ * Why each entry is (0,1,0):
+ *
+ * - `:hover` / `:active` / `:focus*` / `:visited` are single pseudo-classes,
+ *   each (0,1,0).
+ * - `:hover` and `:active` carry a `:where(:not(...))` blocker so the rule
+ *   doesn't match when the element is also active/disabled. The outer
+ *   `:where()` zeros the `:not(...)` contribution, leaving the bare pseudo-
+ *   class's (0,1,0) as the only contributor.
+ * - `:is(:disabled, :has(:disabled))` takes the max specificity of its
+ *   args; both are (0,1,0), so the whole is (0,1,0).
+ * - `:has(...)` selectors take the specificity of their arg's most specific
+ *   complex selector. Arguments are pseudo-classes or attribute selectors at
+ *   (0,1,0); where a form-control scope is also needed (e.g. `readonly` —
+ *   non-form-control elements default to `:read-only` per spec, so a bare
+ *   `:has(:read-only)` matches any container with DIV/SPAN children), the
+ *   scope goes inside `:where(...)` so its (0,0,1) type-selector contribution
+ *   is zeroed.
+ *
+ * **Consumer override ergonomics:** a plain `.my-input:hover` is (0,2,0),
+ * which ties library 1-atom rules at (0,2,0); source order decides. To
+ * unconditionally beat the library, consumers need (0,3,0) (e.g.
+ * `.scope .my-input:hover` or `.my-input.my-input:hover`).
+ */
+/**
+ * Returns the CSS pseudo-selector string for a state key.
+ *
+ * - `'rest'`, `''`, and fully-unknown keys return `''`. An unknown atom inside
+ *   an otherwise-known compound is skipped (the known atoms still contribute) —
+ *   but callers only pass canonical validated keys, so that case doesn't arise
+ *   in practice.
+ * - Atomic keys return their entry from {@link ATOMIC_SELECTORS}.
+ * - Compound keys (`'a&b'`) return the concatenation of each atomic selector
+ *   in the order they appear in the key.
+ */
+declare function getStateSelector(stateKey: string): string;
+/**
+ * Returns the docs-mode class name for a state key, used to force-trigger
+ * pseudo-states in docs/Storybook previews.
+ *
+ * - `'rest'`, `''`, and fully-unknown keys return `''`. An unknown atom inside
+ *   an otherwise-known compound is skipped (the known atoms still contribute) —
+ *   but callers only pass canonical validated keys, so that case doesn't arise
+ *   in practice.
+ * - Atomic keys return their entry from {@link ATOMIC_DOCS_CLASSES}.
+ * - Compound keys join atomic docs classes with `'-and-'`.
+ */
+declare function getStateDocsClass(stateKey: string): string; //#endregion
+//#endregion
+export { getStateDocsClass, getStateSelector, isKnownStateAtom };

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

@@ -0,0 +1,80 @@
+
+import { AtomicState } from "../types/StateAxis.js";
+
+//#region ../automated-config/dist/utils/pseudoStateSelectors.d.ts
+//#region src/utils/pseudoStateSelectors.d.ts
+/**
+ * Legacy atom names accepted by the CSS generator + docs-mode map for
+ * unmigrated configs. They aren't composable through `StateAxis`, so the new
+ * resolver/StateBuilder never emit them.
+ */
+type LegacyStateAtom = 'disabled' | 'focused' | 'focused-keyboard';
+type KnownStateAtom = AtomicState | LegacyStateAtom;
+declare function isKnownStateAtom(atom: string): atom is KnownStateAtom;
+/**
+ * Each atom selector contributes exactly (0,1,0) to specificity. The base
+ * component class adds another (0,1,0), so a full rule's specificity is
+ * `(0, 1 + atom-count, 0)`:
+ *
+ *   rest        → (0,1,0)  e.g. `.uds-input-...root`
+ *   1-atom      → (0,2,0)  e.g. `.uds-input-...root:hover...`
+ *   2-atom      → (0,3,0)  e.g. `.uds-input-...root:has(...):hover...`
+ *   3-atom      → (0,4,0)
+ *   4-atom      → (0,5,0)
+ *
+ * Cross-rank cascade (compound beats atom beats rest) is therefore encoded
+ * in CSS class-count specificity, not source order — making the cascade-
+ * cancellation feature robust to any tool that reorders rules within a
+ * stylesheet. Within a rank (e.g. `:hover` vs `:focus-visible`, both
+ * (0,2,0)) source order still arbitrates; the resolver computes intra-rank
+ * order inline from `STATE_PRIORITY`. See {@link resolvePropertyStates}.
+ *
+ * Why each entry is (0,1,0):
+ *
+ * - `:hover` / `:active` / `:focus*` / `:visited` are single pseudo-classes,
+ *   each (0,1,0).
+ * - `:hover` and `:active` carry a `:where(:not(...))` blocker so the rule
+ *   doesn't match when the element is also active/disabled. The outer
+ *   `:where()` zeros the `:not(...)` contribution, leaving the bare pseudo-
+ *   class's (0,1,0) as the only contributor.
+ * - `:is(:disabled, :has(:disabled))` takes the max specificity of its
+ *   args; both are (0,1,0), so the whole is (0,1,0).
+ * - `:has(...)` selectors take the specificity of their arg's most specific
+ *   complex selector. Arguments are pseudo-classes or attribute selectors at
+ *   (0,1,0); where a form-control scope is also needed (e.g. `readonly` —
+ *   non-form-control elements default to `:read-only` per spec, so a bare
+ *   `:has(:read-only)` matches any container with DIV/SPAN children), the
+ *   scope goes inside `:where(...)` so its (0,0,1) type-selector contribution
+ *   is zeroed.
+ *
+ * **Consumer override ergonomics:** a plain `.my-input:hover` is (0,2,0),
+ * which ties library 1-atom rules at (0,2,0); source order decides. To
+ * unconditionally beat the library, consumers need (0,3,0) (e.g.
+ * `.scope .my-input:hover` or `.my-input.my-input:hover`).
+ */
+/**
+ * Returns the CSS pseudo-selector string for a state key.
+ *
+ * - `'rest'`, `''`, and fully-unknown keys return `''`. An unknown atom inside
+ *   an otherwise-known compound is skipped (the known atoms still contribute) —
+ *   but callers only pass canonical validated keys, so that case doesn't arise
+ *   in practice.
+ * - Atomic keys return their entry from {@link ATOMIC_SELECTORS}.
+ * - Compound keys (`'a&b'`) return the concatenation of each atomic selector
+ *   in the order they appear in the key.
+ */
+declare function getStateSelector(stateKey: string): string;
+/**
+ * Returns the docs-mode class name for a state key, used to force-trigger
+ * pseudo-states in docs/Storybook previews.
+ *
+ * - `'rest'`, `''`, and fully-unknown keys return `''`. An unknown atom inside
+ *   an otherwise-known compound is skipped (the known atoms still contribute) —
+ *   but callers only pass canonical validated keys, so that case doesn't arise
+ *   in practice.
+ * - Atomic keys return their entry from {@link ATOMIC_DOCS_CLASSES}.
+ * - Compound keys join atomic docs classes with `'-and-'`.
+ */
+declare function getStateDocsClass(stateKey: string): string; //#endregion
+//#endregion
+export { getStateDocsClass, getStateSelector, isKnownStateAtom };

package/dist/automated-config/dist/utils/pseudoStateSelectors.js

@@ -0,0 +1,120 @@
+/*! © 2026 Yahoo, Inc. UDS v0.0.0-development */
+import { isAtomicState } from "../types/StateAxis.js";
+import { splitStateKey } from "./canonicalizeStateKey.js";
+//#region ../automated-config/dist/utils/pseudoStateSelectors.js
+/*! © 2026 Yahoo, Inc. UDS Default Config v0.0.0-development */
+const LEGACY_STATE_ATOMS = new Set([
+	"disabled",
+	"focused",
+	"focused-keyboard"
+]);
+function isKnownStateAtom(atom) {
+	return isAtomicState(atom) || LEGACY_STATE_ATOMS.has(atom);
+}
+/**
+* Each atom selector contributes exactly (0,1,0) to specificity. The base
+* component class adds another (0,1,0), so a full rule's specificity is
+* `(0, 1 + atom-count, 0)`:
+*
+*   rest        → (0,1,0)  e.g. `.uds-input-...root`
+*   1-atom      → (0,2,0)  e.g. `.uds-input-...root:hover...`
+*   2-atom      → (0,3,0)  e.g. `.uds-input-...root:has(...):hover...`
+*   3-atom      → (0,4,0)
+*   4-atom      → (0,5,0)
+*
+* Cross-rank cascade (compound beats atom beats rest) is therefore encoded
+* in CSS class-count specificity, not source order — making the cascade-
+* cancellation feature robust to any tool that reorders rules within a
+* stylesheet. Within a rank (e.g. `:hover` vs `:focus-visible`, both
+* (0,2,0)) source order still arbitrates; the resolver computes intra-rank
+* order inline from `STATE_PRIORITY`. See {@link resolvePropertyStates}.
+*
+* Why each entry is (0,1,0):
+*
+* - `:hover` / `:active` / `:focus*` / `:visited` are single pseudo-classes,
+*   each (0,1,0).
+* - `:hover` and `:active` carry a `:where(:not(...))` blocker so the rule
+*   doesn't match when the element is also active/disabled. The outer
+*   `:where()` zeros the `:not(...)` contribution, leaving the bare pseudo-
+*   class's (0,1,0) as the only contributor.
+* - `:is(:disabled, :has(:disabled))` takes the max specificity of its
+*   args; both are (0,1,0), so the whole is (0,1,0).
+* - `:has(...)` selectors take the specificity of their arg's most specific
+*   complex selector. Arguments are pseudo-classes or attribute selectors at
+*   (0,1,0); where a form-control scope is also needed (e.g. `readonly` —
+*   non-form-control elements default to `:read-only` per spec, so a bare
+*   `:has(:read-only)` matches any container with DIV/SPAN children), the
+*   scope goes inside `:where(...)` so its (0,0,1) type-selector contribution
+*   is zeroed.
+*
+* **Consumer override ergonomics:** a plain `.my-input:hover` is (0,2,0),
+* which ties library 1-atom rules at (0,2,0); source order decides. To
+* unconditionally beat the library, consumers need (0,3,0) (e.g.
+* `.scope .my-input:hover` or `.my-input.my-input:hover`).
+*/
+const ATOMIC_SELECTORS = {
+	hover: ":hover:where(:not(:active, :disabled, :has(:disabled)))",
+	pressed: ":active:where(:not(:disabled, :has(:disabled)))",
+	disabled: ":is(:disabled, :has(:disabled))",
+	visited: ":visited",
+	focused: ":focus",
+	"focus-within": ":focus-within",
+	"focus-visible": ":focus-visible",
+	"focused-keyboard": ":focus-visible",
+	readonly: ":has(:read-only:where(input, textarea))",
+	invalid: ":has([aria-invalid=\"true\"])",
+	"placeholder-shown": ":has(:placeholder-shown)",
+	autofill: ":has(:autofill, :-webkit-autofill)"
+};
+const ATOMIC_DOCS_CLASSES = {
+	hover: "hover",
+	pressed: "active",
+	disabled: "has-disabled",
+	visited: "visited",
+	focused: "focus",
+	"focus-within": "focus-within",
+	"focus-visible": "focus-visible",
+	"focused-keyboard": "focus-visible",
+	readonly: "input-readonly",
+	invalid: "has-input-invalid",
+	"placeholder-shown": "has-input-placeholder-shown",
+	autofill: "has-input-autofill"
+};
+/**
+* Returns the CSS pseudo-selector string for a state key.
+*
+* - `'rest'`, `''`, and fully-unknown keys return `''`. An unknown atom inside
+*   an otherwise-known compound is skipped (the known atoms still contribute) —
+*   but callers only pass canonical validated keys, so that case doesn't arise
+*   in practice.
+* - Atomic keys return their entry from {@link ATOMIC_SELECTORS}.
+* - Compound keys (`'a&b'`) return the concatenation of each atomic selector
+*   in the order they appear in the key.
+*/
+function getStateSelector(stateKey) {
+	const atoms = splitStateKey(stateKey);
+	if (atoms.length === 0) return "";
+	let selector = "";
+	for (const atom of atoms) if (isKnownStateAtom(atom)) selector += ATOMIC_SELECTORS[atom];
+	return selector;
+}
+/**
+* Returns the docs-mode class name for a state key, used to force-trigger
+* pseudo-states in docs/Storybook previews.
+*
+* - `'rest'`, `''`, and fully-unknown keys return `''`. An unknown atom inside
+*   an otherwise-known compound is skipped (the known atoms still contribute) —
+*   but callers only pass canonical validated keys, so that case doesn't arise
+*   in practice.
+* - Atomic keys return their entry from {@link ATOMIC_DOCS_CLASSES}.
+* - Compound keys join atomic docs classes with `'-and-'`.
+*/
+function getStateDocsClass(stateKey) {
+	const atoms = splitStateKey(stateKey);
+	if (atoms.length === 0) return "";
+	const parts = [];
+	for (const atom of atoms) if (isKnownStateAtom(atom)) parts.push(ATOMIC_DOCS_CLASSES[atom]);
+	return parts.join("-and-");
+}
+//#endregion
+export { getStateDocsClass, getStateSelector, isKnownStateAtom };

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

@@ -0,0 +1,131 @@
+/*! © 2026 Yahoo, Inc. UDS v0.0.0-development */
+const require_StateAxis = require("../types/StateAxis.cjs");
+const require_canonicalizeStateKey = require("./canonicalizeStateKey.cjs");
+//#region ../automated-config/dist/utils/resolvePropertyStates.js
+/*! © 2026 Yahoo, Inc. UDS Default Config v0.0.0-development */
+/**
+* Yields every modifier subset of size 1..maxSize, preserving input order
+* within each subset. Used by both the resolver and the docs-class
+* enumeration so the depth they support stays in lock-step.
+*
+* Generic over the element type so callers passing `ModifierAtomic[]` get
+* `Generator<readonly ModifierAtomic[]>` back — keeps the inferred type chain
+* tight enough for downstream consumers to avoid widening to `string`.
+*/
+function* modifierSubsets(modifiers, maxSize) {
+	const indices = [];
+	function* recurse(start) {
+		if (indices.length > 0) yield indices.map((i) => modifiers[i]);
+		if (indices.length === maxSize) return;
+		for (let i = start; i < modifiers.length; i++) {
+			indices.push(i);
+			yield* recurse(i + 1);
+			indices.pop();
+		}
+	}
+	yield* recurse(0);
+}
+/**
+* Yields the interactive subsets that can be simultaneously active on one
+* element, in `modifierSubsets` order. `hover` and `pressed` are mutually
+* exclusive — the `hover` selector carries `:where(:not(:active …))`, so a
+* `hover&pressed` rule could never match — so any subset containing BOTH is
+* dropped. Every other subset is kept (notably `focus-within`/`focus-visible`
+* CAN coexist with a pointer state: you can hover or press a focused element).
+*
+* `interactives` MUST already be sorted by `comparePriority`.
+*/
+function* coOccurringInteractiveSubsets(interactives) {
+	for (const subset of modifierSubsets(interactives, interactives.length)) {
+		if (subset.includes("hover") && subset.includes("pressed")) continue;
+		yield subset;
+	}
+}
+/**
+* Yields a property's atomic + compound state keys in cascade order from a
+* priority-sorted atomic set:
+*
+*   atoms (in the given order)
+*   → for each modifier subset: the pure-modifier compound (size ≥ 2) then each
+*     modifier-subset × SINGLE-interactive compound
+*   → each pure interactive-pair compound (size ≥ 2, co-occurring)
+*   → each modifier-subset × interactive-PAIR compound
+*
+* The interactive-pair compounds are APPENDED after the original keys so every
+* pre-existing key keeps its rank — `resolveSlotByCascade`'s tie-break and
+* Figma's published values for already-declared states are therefore unchanged;
+* only genuinely new co-occurring combinations (e.g. `focus-within&hover`) gain
+* a key. Each is a real declared state with its own rule, so a property whose
+* `focus-within` and `hover` resolve to different values renders the
+* per-property-correct blend at `(0, 1+atomCount, 0)` specificity in BOTH emit
+* modes — closing the only exhaustive/selective divergence (two interactives
+* co-occurring with no compound to arbitrate them). `hover&pressed` pairs are
+* never generated (they can't co-occur; see `coOccurringInteractiveSubsets`).
+*
+* `'rest'` is NOT included — callers prepend it (and decide whether to, e.g.
+* `skipRestState`). `atomics` MUST already be sorted by `comparePriority`
+* (weakest first) so the strongest atom emits last and wins on intra-rank
+* source-order ties.
+*
+* Shared by `resolvePropertyStates` (the CSS-emission source of truth) and
+* `resolveSlotByCascade`'s cascade-rank computation, so the emission order —
+* and therefore the cascade tie-break it implies — stays identical across both.
+* Change emission order here, not in either caller.
+*/
+function* atomicAndCompoundStateKeys(atomics) {
+	for (const atom of atomics) yield atom;
+	const modifiers = atomics.filter(require_StateAxis.isModifierAtomic);
+	const interactives = atomics.filter(require_StateAxis.isInteractiveAtomic);
+	for (const subset of modifierSubsets(modifiers, 3)) {
+		if (subset.length >= 2) yield require_canonicalizeStateKey.canonicalizeStateKey(subset);
+		for (const interactive of interactives) yield require_canonicalizeStateKey.canonicalizeStateKey([...subset, interactive]);
+	}
+	const interactivePairs = [...coOccurringInteractiveSubsets(interactives)].filter((subset) => subset.length >= 2);
+	for (const interactiveSubset of interactivePairs) yield require_canonicalizeStateKey.canonicalizeStateKey(interactiveSubset);
+	for (const subset of modifierSubsets(modifiers, 3)) for (const interactiveSubset of interactivePairs) yield require_canonicalizeStateKey.canonicalizeStateKey([...subset, ...interactiveSubset]);
+}
+/**
+* Returns all canonical state keys a property reacts to, in cascade order:
+*
+*   rest → atomics (sorted by global `STATE_PRIORITY`, weakest first)
+*   → 2-atom compounds → 3-atom compounds → ...
+*
+* Cross-rank ordering (atom < 2-atom compound < 3-atom compound < ...) is
+* enforced by CSS class-count specificity. Each atom selector contributes
+* (0,1,0), so a 2-atom compound at (0,3,0) strictly beats a 1-atom rule at
+* (0,2,0) — the cascade-cancellation feature is encoded in the selector
+* itself rather than rule source order.
+*
+* Intra-rank ties (which atom wins among the priority-sorted set, or which
+* 2-atom compound wins among siblings of the same size) fall through to
+* source order at the same specificity. Emission order follows the global
+* `STATE_PRIORITY` array — to change which atom wins between any two
+* simultaneously-matching atoms, reorder that array.
+*
+* Resolution sources, in order of precedence:
+*
+*   1. The new system: `layer.atomicStates` declares the atoms this layer can
+*      compose; `property.excludeAtomics` opts the property out of selected
+*      atoms. Compounds are auto-generated from the resulting set via
+*      modifier × interactive expansion.
+*   2. The legacy system: `property.pseudoStates` (no compound generation; the
+*      array is used verbatim). Used when `layer.atomicStates` is absent so
+*      unmigrated component configs continue to behave exactly as before.
+*
+* `'rest'` is always included unless the property has `skipRestState: true`.
+*/
+function resolvePropertyStates(layer, property) {
+	const states = [];
+	if (!(property.skipRestState === true)) states.push("rest");
+	if (layer.atomicStates && layer.atomicStates.length > 0) {
+		const exclude = new Set(property.excludeAtomics ?? []);
+		const atomics = [...layer.atomicStates].filter((atom) => !exclude.has(atom)).sort(require_StateAxis.comparePriority);
+		for (const stateKey of atomicAndCompoundStateKeys(atomics)) states.push(stateKey);
+		return states;
+	}
+	if (property.pseudoStates) for (const s of property.pseudoStates) states.push(s);
+	return states;
+}
+//#endregion
+exports.atomicAndCompoundStateKeys = atomicAndCompoundStateKeys;
+exports.resolvePropertyStates = resolvePropertyStates;

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

@@ -0,0 +1,49 @@
+
+import { ConfigurablePropertiesName, SelectedConfigurableProperty } from "../properties.cjs";
+import { LayerConfig, PossibleStatesWithRest } from "../types/ComponentConfig.cjs";
+
+//#region ../automated-config/dist/utils/resolvePropertyStates.d.ts
+//#region src/utils/resolvePropertyStates.d.ts
+type AnyProperty = SelectedConfigurableProperty<ConfigurablePropertiesName, string>;
+/**
+ * Yields every modifier subset of size 1..maxSize, preserving input order
+ * within each subset. Used by both the resolver and the docs-class
+ * enumeration so the depth they support stays in lock-step.
+ *
+ * Generic over the element type so callers passing `ModifierAtomic[]` get
+ * `Generator<readonly ModifierAtomic[]>` back — keeps the inferred type chain
+ * tight enough for downstream consumers to avoid widening to `string`.
+ */
+/**
+ * Returns all canonical state keys a property reacts to, in cascade order:
+ *
+ *   rest → atomics (sorted by global `STATE_PRIORITY`, weakest first)
+ *   → 2-atom compounds → 3-atom compounds → ...
+ *
+ * Cross-rank ordering (atom < 2-atom compound < 3-atom compound < ...) is
+ * enforced by CSS class-count specificity. Each atom selector contributes
+ * (0,1,0), so a 2-atom compound at (0,3,0) strictly beats a 1-atom rule at
+ * (0,2,0) — the cascade-cancellation feature is encoded in the selector
+ * itself rather than rule source order.
+ *
+ * Intra-rank ties (which atom wins among the priority-sorted set, or which
+ * 2-atom compound wins among siblings of the same size) fall through to
+ * source order at the same specificity. Emission order follows the global
+ * `STATE_PRIORITY` array — to change which atom wins between any two
+ * simultaneously-matching atoms, reorder that array.
+ *
+ * Resolution sources, in order of precedence:
+ *
+ *   1. The new system: `layer.atomicStates` declares the atoms this layer can
+ *      compose; `property.excludeAtomics` opts the property out of selected
+ *      atoms. Compounds are auto-generated from the resulting set via
+ *      modifier × interactive expansion.
+ *   2. The legacy system: `property.pseudoStates` (no compound generation; the
+ *      array is used verbatim). Used when `layer.atomicStates` is absent so
+ *      unmigrated component configs continue to behave exactly as before.
+ *
+ * `'rest'` is always included unless the property has `skipRestState: true`.
+ */
+declare function resolvePropertyStates(layer: LayerConfig, property: AnyProperty): PossibleStatesWithRest[]; //#endregion
+//#endregion
+export { resolvePropertyStates };

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

@@ -0,0 +1,49 @@
+
+import { ConfigurablePropertiesName, SelectedConfigurableProperty } from "../properties.js";
+import { LayerConfig, PossibleStatesWithRest } from "../types/ComponentConfig.js";
+
+//#region ../automated-config/dist/utils/resolvePropertyStates.d.ts
+//#region src/utils/resolvePropertyStates.d.ts
+type AnyProperty = SelectedConfigurableProperty<ConfigurablePropertiesName, string>;
+/**
+ * Yields every modifier subset of size 1..maxSize, preserving input order
+ * within each subset. Used by both the resolver and the docs-class
+ * enumeration so the depth they support stays in lock-step.
+ *
+ * Generic over the element type so callers passing `ModifierAtomic[]` get
+ * `Generator<readonly ModifierAtomic[]>` back — keeps the inferred type chain
+ * tight enough for downstream consumers to avoid widening to `string`.
+ */
+/**
+ * Returns all canonical state keys a property reacts to, in cascade order:
+ *
+ *   rest → atomics (sorted by global `STATE_PRIORITY`, weakest first)
+ *   → 2-atom compounds → 3-atom compounds → ...
+ *
+ * Cross-rank ordering (atom < 2-atom compound < 3-atom compound < ...) is
+ * enforced by CSS class-count specificity. Each atom selector contributes
+ * (0,1,0), so a 2-atom compound at (0,3,0) strictly beats a 1-atom rule at
+ * (0,2,0) — the cascade-cancellation feature is encoded in the selector
+ * itself rather than rule source order.
+ *
+ * Intra-rank ties (which atom wins among the priority-sorted set, or which
+ * 2-atom compound wins among siblings of the same size) fall through to
+ * source order at the same specificity. Emission order follows the global
+ * `STATE_PRIORITY` array — to change which atom wins between any two
+ * simultaneously-matching atoms, reorder that array.
+ *
+ * Resolution sources, in order of precedence:
+ *
+ *   1. The new system: `layer.atomicStates` declares the atoms this layer can
+ *      compose; `property.excludeAtomics` opts the property out of selected
+ *      atoms. Compounds are auto-generated from the resulting set via
+ *      modifier × interactive expansion.
+ *   2. The legacy system: `property.pseudoStates` (no compound generation; the
+ *      array is used verbatim). Used when `layer.atomicStates` is absent so
+ *      unmigrated component configs continue to behave exactly as before.
+ *
+ * `'rest'` is always included unless the property has `skipRestState: true`.
+ */
+declare function resolvePropertyStates(layer: LayerConfig, property: AnyProperty): PossibleStatesWithRest[]; //#endregion
+//#endregion
+export { resolvePropertyStates };