@yahoo/uds-create-config 5.25.2 → 5.26.0

package/dist/entities/system/defineComponent.d.ts

@@ -627,8 +627,35 @@ type DefaultsOf<P extends PropMap> = Partial<DeclaredProps<P>> & {
  * `as` clause drops exactly the named keys and keeps the rest as declared.
  */
 type Without<T, K extends PropertyKey> = string extends K ? T : { [Key in keyof T as Key extends K ? never : Key]: T[Key] };
+/** One state a component declares in `.states()` — what its render knows and a style rule keys on.
+ *  A boolean (`filled`), or a closed set of names with an optional default (`phase`). */
+type StateDecl = {
+  readonly type: 'boolean';
+} | {
+  readonly type: 'variant';
+  readonly value: readonly string[];
+  readonly default?: string;
+};
+/** A component's states, by name. */
+type StateMap = Readonly<Record<string, StateDecl>>;
+/** The value each state of `S` takes: a boolean's `true`/`false`, a variant's names. */
+type StateValues<S> = { [K in keyof S]?: S[K] extends {
+  type: 'variant';
+  value: readonly (infer V)[];
+} ? V : boolean };
+/**
+ * How a render reports its states — `const layers = states(props, { filled: value !== '' })` — and
+ * spreads the bundles it hands back: `<Box {...layers.root}>`.
+ *
+ * A pure call, not a hook, so it can sit under a condition. It takes the render's `props` (the
+ * bundles at rest, or as Studio or a test forced them) and returns the bundles BUILT FOR those
+ * states, a fresh set: every rule naming a state, a prop a rule sets on a layer, the root's
+ * `data-<name>` attribute, a portal layer and a nested instance all follow the values given. A
+ * forced value still wins over them.
+ */
+type StatesHelper<S extends StateMap, L extends LayerMap = LayerMap> = (props: Record<keyof L & string, Record<string, unknown>>, values: StateValues<S>) => Record<keyof L & string, Record<string, unknown>>;
 /** What a render receives: the generated per-layer bundle, plus the props the component declared. */
-type RenderArgs<L extends LayerMap, P extends PropMap> = {
+type RenderArgs<L extends LayerMap, P extends PropMap, S extends StateMap = Record<never, never>> = {
   readonly props: Record<keyof L & string, Record<string, unknown>>;
   /**
    * The ref the emitted module forwards to the render, for the element it chooses to attach it to.
@@ -637,7 +664,9 @@ type RenderArgs<L extends LayerMap, P extends PropMap> = {
    * `<input ref={ref}>` in another — and which element is the render's decision.
    */
   readonly ref?: Ref<any>;
-} & DeclaredProps<P, L, unknown, 'render'> & Record<string, unknown>;
+} & ([keyof S] extends [never] ? Record<never, never> : {
+  readonly states: StatesHelper<S, L>;
+}) & DeclaredProps<P, L, unknown, 'render'> & Record<string, unknown>;
 interface ComponentBuilder<L extends LayerMap, P extends PropMap,
 /** Props the RENDER takes that the config doesn't describe — React handlers, mostly (`onPress`).
  *  They're part of the component's surface but not of its data, which is why they're declared at
@@ -650,7 +679,7 @@ D = Record<never, never>,
  *  `.forwards()` so `ComponentPropsOf` can union each forwarded layer's element props — `root` is
  *  already covered structurally by {@link ElementOf}, so for a root-only forward this changes no
  *  inferred type, which is what makes replacing `inherits` a no-op at every call site. */
-F extends string = never> extends Authored {
+F extends string = never, /** The states `.states()` declared — what the render knows and reports, never a caller's prop. */S extends StateMap = Record<never, never>> extends Authored {
   /**
    * The phantom call signature — the authored value is never rendered (the build substitutes the
    * emitted module), but a call site is checked against it. Generic over the element a call site
@@ -671,7 +700,7 @@ F extends string = never> extends Authored {
   /** The authored body, readable so codegen can pair it with the render found in the source. */
   readonly body: Record<string, unknown>;
   readonly path?: string;
-  layers<const L2 extends LayerMap>(layers: L2): ComponentBuilder<L2, P, E, D, F>;
+  layers<const L2 extends LayerMap>(layers: L2): ComponentBuilder<L2, P, E, D, F, S>;
   /**
    * This component's props.
    *
@@ -680,8 +709,19 @@ F extends string = never> extends Authored {
    * provide. The callback and its `layer`/`bind` helpers are gone — they only ever split a path string
    * that the parameter's own type now checks.
    */
-  props<const P2 extends PropMap<LayerPath<L>>>(props: P2 & NoInfer<{ [K in keyof P2]: Exact<P2[K], AuthoredProp<LayerPath<L>>> }>): ComponentBuilder<L, P2, E, D, F>;
-  styles(rules: readonly StyleRuleInput<L>[]): ComponentBuilder<L, P, E, D, F>;
+  props<const P2 extends PropMap<LayerPath<L>>>(props: P2 & NoInfer<{ [K in keyof P2]: Exact<P2[K], AuthoredProp<LayerPath<L>>> }>): ComponentBuilder<L, P2, E, D, F, S>;
+  /**
+   * What the render knows that a style rule keys on — the field has a value, the image loaded, the
+   * indicator is sliding: `{ filled: { type: 'boolean' } }`, `{ phase: { type: 'variant', value:
+   * ['idle', 'sliding'], default: 'idle' } }`.
+   *
+   * Not props, so not part of the component's API: the render passes its `props` and the values it
+   * knows to `const layers = states(props, { filled })` and spreads those layers in `props`' place;
+   * a rule naming a state in `when` follows the values given. A value a caller controls is a prop;
+   * the render reports the state from it.
+   */
+  states<const S2 extends StateMap>(states: S2): ComponentBuilder<L, P, E, D, F, S2>;
+  styles(rules: readonly StyleRuleInput<L>[]): ComponentBuilder<L, P, E, D, F, S>;
   /**
    * What this component applies with nothing set.
    *
@@ -692,7 +732,7 @@ F extends string = never> extends Authored {
    * `const`, so an `as` keeps its literal type: without it `{ as: 'input' }` widens to `string` and
    * there's no tag left to resolve the element's props against.
    */
-  defaultProps<const D2 extends DefaultsOf<P>>(defaults: D2): ComponentBuilder<L, P, E, D2, F>;
+  defaultProps<const D2 extends DefaultsOf<P>>(defaults: D2): ComponentBuilder<L, P, E, D2, F, S>;
   /**
    * The layers whose element props this component ALSO exposes, keyed by layer.
    *
@@ -704,7 +744,7 @@ F extends string = never> extends Authored {
    * source FROM stored config — every keyed collection there is one call with a record literal, and a
    * second authored form would make generated source drift from what a person writes.
    */
-  forwards<const F2 extends Readonly<Partial<Record<keyof L & string, Forwarded>>>>(forwards: F2): ComponentBuilder<L, P, E, D, F | (keyof F2 & string)>;
+  forwards<const F2 extends Readonly<Partial<Record<keyof L & string, Forwarded>>>>(forwards: F2): ComponentBuilder<L, P, E, D, F | (keyof F2 & string), S>;
   /**
    * What a person is told about this component: the label a picker shows, and what it's for.
    * `guidance` is for a model composing with it, in the imperative voice of a rule; the guidance
@@ -717,7 +757,7 @@ F extends string = never> extends Authored {
     guidance?: string;
     hidden?: boolean;
     deprecated?: boolean;
-  }): ComponentBuilder<L, P, E, D, F>;
+  }): ComponentBuilder<L, P, E, D, F, S>;
   /**
    * The anatomy: which elements this component renders, in what order and nesting.
    *
@@ -726,7 +766,7 @@ F extends string = never> extends Authored {
    * it from the source and copies it verbatim, so what it returns is irrelevant; declaring it is
    * what puts it in the file.
    */
-  render<E2 = E>(fn: (args: Without<RenderArgs<L, P>, keyof E2> & E2) => unknown): ComponentBuilder<L, P, E2, D, F>;
+  render<E2 = E>(fn: (args: Without<RenderArgs<L, P, S>, keyof E2> & E2) => unknown): ComponentBuilder<L, P, E2, D, F, S>;
   /**
    * An optional browser-canvas anatomy for a native component.
    *
@@ -734,7 +774,7 @@ F extends string = never> extends Authored {
    * Use this only when the phone anatomy is a poor fit for a browser canvas (a full-screen safe-area
    * wrapper, for example). Like `render`, it is source-read build input and stores no config data.
    */
-  renderCanvas<E2 extends E = E>(fn: (args: Without<RenderArgs<L, P>, keyof E2> & E2) => unknown): ComponentBuilder<L, P, E, D, F>;
+  renderCanvas<E2 extends E = E>(fn: (args: Without<RenderArgs<L, P, S>, keyof E2> & E2) => unknown): ComponentBuilder<L, P, E, D, F, S>;
   /**
    * What a preview of this component STARTS from — the props a single tile is rendered with.
    *
@@ -755,7 +795,7 @@ F extends string = never> extends Authored {
      * so a preview can say a boolean is worth a column the way a rule would.
      */
     when?: readonly PreviewCondition<P>[];
-  }): ComponentBuilder<L, P, E, D, F>;
+  }): ComponentBuilder<L, P, E, D, F, S>;
   toStored(): Record<string, unknown>;
   assignPath(path: string): void;
 }
@@ -787,4 +827,4 @@ interface DefineComponent {
 declare function definePropsFirst<const P extends PropMap<LayerPath>>(props: P & NoInfer<{ [K in keyof P]: Exact<P[K], AuthoredProp<LayerPath>> }>): ComponentBuilder<LayerMap, P>;
 declare const defineComponent: DefineComponent;
 //#endregion
-export { AsInput, AuthoredComponent, AuthoredProp, ComponentBuilder, ComponentPropsOf, DefaultsOf, GlyphComponent, GlyphValue, LayerElement, LayerMap, PhantomCallProps, PhantomReadProps, PropCondition, PropDecl, PropMap, RegisteredMembers, RenderArgs, SlotCodeForm, SlotDecl, StyleRuleInput, defineComponent };
+export { AsInput, AuthoredComponent, AuthoredProp, ComponentBuilder, ComponentPropsOf, DefaultsOf, GlyphComponent, GlyphValue, LayerElement, LayerMap, PhantomCallProps, PhantomReadProps, PropCondition, PropDecl, PropMap, RegisteredMembers, RenderArgs, SlotCodeForm, SlotDecl, StateMap, StyleRuleInput, defineComponent };

package/dist/entities/system/defineComponent.js

@@ -15,6 +15,7 @@ function build(body) {
 		path: void 0,
 		layers: (layers) => next({ layers: withEmittedRefs(layers) }),
 		props: (props) => next({ props }),
+		states: (states) => next({ states }),
 		styles: (rules) => next({ styles: rules }),
 		defaultProps: (defaults) => next({ defaultProps: defaults }),
 		forwards: (forwards) => next({ forwards }),

package/dist/entities/system/forward-route-invariants.js

@@ -1,6 +1,6 @@
 import { isRef, pathOf } from "../../framework/utils/refs.js";
-import { isPlainRecord } from "./style-bag.js";
 import { createSliceMemo } from "../../framework/memo.js";
+import { isPlainRecord } from "./style-bag.js";
 import { stylePropEntries } from "../../framework/projections.js";
 import { forwardRoutes, intoName, routedPropIn, routesContent } from "../../framework/prop-surface.js";
 //#region src/entities/system/forward-route-invariants.ts

package/dist/entities/system/icon-domain-invariants.js

@@ -1,7 +1,7 @@
 import { isRef, kindOf, memberOf, pathOf } from "../../framework/utils/refs.js";
+import { createSliceMemo } from "../../framework/memo.js";
 import { spellValues } from "../../framework/value-domain.js";
 import { collectBag, isPlainRecord } from "./style-bag.js";
-import { createSliceMemo } from "../../framework/memo.js";
 import { glyphComponentOf, glyphLibrariesOf, memberLeaves, propValueDomain, refListOf, resolveComponentProps } from "../../framework/projections.js";
 //#region src/entities/system/icon-domain-invariants.ts
 /**

package/dist/entities/system/root-layer-invariants.js

@@ -1,5 +1,5 @@
-import { isPlainRecord } from "./style-bag.js";
 import { createSliceMemo } from "../../framework/memo.js";
+import { isPlainRecord } from "./style-bag.js";
 //#region src/entities/system/root-layer-invariants.ts
 /**
 * A component's layers include one named `root`. The name is what the anatomy's edge list starts

package/dist/entities/system/token-values.js

@@ -1,6 +1,6 @@
 import { collectRefs, kindOf, pathOf, ref, splitRef } from "../../framework/utils/refs.js";
-import { parseRootFontSize } from "../../css/root-font-size.js";
 import { createSliceMemo } from "../../framework/memo.js";
+import { parseRootFontSize } from "../../css/root-font-size.js";
 import { CSS_DEFAULTS, Settings } from "./Settings.js";
 import { cssVar, declaresCssVariable, resolveTokenValue } from "../../framework/projections.js";
 //#region src/entities/system/token-values.ts

package/dist/framework/Config.d.ts

@@ -73,7 +73,7 @@ interface RecordedSource {
  * The dense-counter `2` a short-lived scheme stamped before the chain existed reads as the mint
  * that replaced it (see `detectedWireVersion`).
  */
-declare const SERIALIZED_CONFIG_VERSION = 20261012200606;
+declare const SERIALIZED_CONFIG_VERSION = 20261013154037;
 interface SerializedConfig {
   /** See {@link SERIALIZED_CONFIG_VERSION}. Always written; a stored artifact may lack it. */
   readonly version: number;

package/dist/framework/Config.js

@@ -5749,7 +5749,7 @@ var Config = class Config {
 	*  links from the provided sources. A declared `linkedKind` with no provided source throws. */
 	hydrateFrom(stored, options) {
 		const claimed = schemaVersionOf(stored);
-		if (claimed > 20261012200606) throw new SchemaVersionTooNew(claimed);
+		if (claimed > 20261013154037) throw new SchemaVersionTooNew(claimed);
 		const wire = upgradeSerializedConfig(stored);
 		if (!Array.isArray(wire.ownedKinds) || typeof wire.items !== "object" || wire.items === null) throw new ConfigFormatError(`Config "${stored.name ?? "system-config"}" cannot be hydrated: this is not a serialized config-v2 config (no "ownedKinds"/"items"). A pre-cutover build artifact converts through the registered cutover migration — import the config type's module (e.g. \`configs/system\`) before hydrating, or port the repo once with \`uds migrate\`.`);
 		const leftover = wire.options;

package/dist/framework/class-names.d.ts

@@ -1,4 +1,5 @@
 import { Config } from "./Config.js";
+import { ComponentState, UDS_FORCE_STATES, componentStateDefaults, componentStates } from "./component-states.js";
 
 //#region src/framework/class-names.d.ts
 /** `HStack` → `hstack`, `AvatarItem` → `avatar-item`. A dash only between a lower/digit and an
@@ -13,6 +14,17 @@ declare function kebabComponent(name: string): string;
  * nothing when one side skips the kebab-casing.
  */
 declare function forceStateAttribute(modifier: string): string;
+/**
+ * The selector a forced state's stylesheet twin matches: the force attribute naming `owner`, the
+ * component whose rule it is (`[data-create-force-hover~="Button"]`).
+ *
+ * The attribute's value is the list of components forced on that element, by path. A component
+ * whose root IS another component's instance shares that element, so a bare `[attr]` lit the inner
+ * component's hover in the outer one's Hover column; naming the owner keeps each column to the
+ * component it belongs to. Without an owner (a global style, a shared utility) any forced element
+ * matches.
+ */
+declare function forceStateSelector(modifier: string, owner?: string): string;
 /**
  * The attribute that forces one mode group on an element and its subtree:
  * `data-create-force-mode-<group>="<option>"`. The group is lowercased and a nested group's slashes
@@ -75,6 +87,20 @@ declare function componentLayerClass(config: Config, path: string, layer: string
  * the cheaper problem.
  */
 declare function ruleCondition(when: Record<string, unknown> | null | undefined): string;
+/**
+ * The attribute a state rides on the root — `filled` → `data-filled`, `isLoaded` → `data-is-loaded`.
+ * A boolean is present when true and absent otherwise; a variant holds its value. The emitted module
+ * spells it with the same transform, since a stylesheet keyed on one spelling matches nothing the
+ * render wrote in another.
+ */
+declare function componentStateAttribute(name: string): string;
+/**
+ * The attributes a root carries for its states' values — `{ filled: true }` → `{ 'data-filled': '' }`.
+ * A state given no value takes its declared default; one that is false or unset carries nothing.
+ * What a projection that has the values up front (the canvas) writes, and what the emitted module's
+ * `states` helper writes from the render's.
+ */
+declare function componentStateAttributes(states: readonly ComponentState[], values: Readonly<Record<string, unknown>>): Record<string, string>;
 /** One layer's conditional class — the rule it comes from, and the props that have to hold. */
 interface ComponentRuleClass {
   /** The layer the class lands on. */
@@ -362,4 +388,4 @@ declare function modifierUtilitiesUsed(config: Config): Set<string>;
  */
 declare function splitVariants(cls: string): string[];
 //#endregion
-export { ComponentRuleClass, PickedComposite, SplitStyleProps, arbitraryClassName, arbitraryNeedsClass, classLeaf, classSelector, componentClassBase, componentCompositeClasses, componentLayerClass, componentMotionClasses, componentPropClasses, componentPropComposites, componentRuleClasses, forceModeAttribute, forceModeAttributeOf, forceModeProp, forceModePropGroup, forceModePropValue, forceModeProps, forceStateAttribute, inlineRuleComposites, isForceModeProp, kebabComponent, layerJsMotionPresets, layerRoutedProps, modifierUtilitiesUsed, motionClassName, ruleCondition, splitStyleProps, splitVariants, stylePropClassBase, stylePropClassName, stylePropClasses, stylePropOffScaleLiteral, stylePropOwnClasses, styleRuleMotionClasses };
+export { ComponentRuleClass, PickedComposite, SplitStyleProps, arbitraryClassName, arbitraryNeedsClass, classLeaf, classSelector, componentClassBase, componentCompositeClasses, componentLayerClass, componentMotionClasses, componentPropClasses, componentPropComposites, componentRuleClasses, componentStateAttribute, componentStateAttributes, forceModeAttribute, forceModeAttributeOf, forceModeProp, forceModePropGroup, forceModePropValue, forceModeProps, forceStateAttribute, forceStateSelector, inlineRuleComposites, isForceModeProp, kebabComponent, layerJsMotionPresets, layerRoutedProps, modifierUtilitiesUsed, motionClassName, ruleCondition, splitStyleProps, splitVariants, stylePropClassBase, stylePropClassName, stylePropClasses, stylePropOffScaleLiteral, stylePropOwnClasses, styleRuleMotionClasses };

package/dist/framework/class-names.js

@@ -2,6 +2,7 @@ import { isRef, kindOf, memberOf, pathOf, refLeaf, refOfKey } from "./utils/refs
 import { forwardsOf, rootLayerOf } from "../entities/system/element.js";
 import { createSliceMemo } from "./memo.js";
 import { classPrefixOf, prefixed, varPrefixOf } from "../entities/system/Settings.js";
+import "./component-states.js";
 import { storedPreview } from "./preview-store.js";
 import { authoredValue, className, isCustomPropertyKey, negatedCssValue, renderStyleValue, resolveComponentProps, stylePropEntries, stylePropLeafForToken, stylePropNumberLeaf, stylePropNumberUnit, stylePropValueLeaves, stylePropertyPathFor } from "./projections.js";
 import { inlineMotionId, isInlineMotion, jsMotionBody } from "../entities/system/motion-variants.js";
@@ -45,6 +46,31 @@ function forceStateAttribute(modifier) {
 	return `${FORCE_ATTRIBUTE_PREFIX}${kebabComponent(name.slice(name.lastIndexOf("/") + 1))}`;
 }
 /**
+* The selector a forced state's stylesheet twin matches: the force attribute naming `owner`, the
+* component whose rule it is (`[data-create-force-hover~="Button"]`).
+*
+* The attribute's value is the list of components forced on that element, by path. A component
+* whose root IS another component's instance shares that element, so a bare `[attr]` lit the inner
+* component's hover in the outer one's Hover column; naming the owner keeps each column to the
+* component it belongs to. Without an owner (a global style, a shared utility) any forced element
+* matches.
+*/
+function forceStateSelector(modifier, owner) {
+	const attribute = forceStateAttribute(modifier);
+	return owner === void 0 ? `[${attribute}]` : `[${attribute}~=${JSON.stringify(owner)}]`;
+}
+/**
+* The force attributes a pin bag asks for: one per pseudo-state pinned on (`{ _active: true }` →
+* `data-create-force-active`), each naming `owner`, the component it's forced on (see
+* {@link forceStateSelector}). A component state in the same bag (`dragging`) is the render's, not
+* the stylesheet's, so it's left out.
+*/
+function forcedModifierAttributes(pins, owner = "") {
+	const attrs = {};
+	for (const [key, value] of Object.entries(pins ?? {})) if (key.startsWith("_") && !key.includes("@") && (value === true || value === "true")) attrs[forceStateAttribute(key)] = owner;
+	return attrs;
+}
+/**
 * The attribute that forces one mode group on an element and its subtree:
 * `data-create-force-mode-<group>="<option>"`. The group is lowercased and a nested group's slashes
 * become dashes, since an attribute name can hold neither. The emitter admits this attribute beside
@@ -137,6 +163,31 @@ function ruleCondition(when) {
 	return Object.entries(when ?? {}).map(([prop, value]) => `${prop}-${String(value).replaceAll("/", "-").replaceAll(".", "_").replace(/\s+/g, "-")}`).join("-");
 }
 /**
+* The attribute a state rides on the root — `filled` → `data-filled`, `isLoaded` → `data-is-loaded`.
+* A boolean is present when true and absent otherwise; a variant holds its value. The emitted module
+* spells it with the same transform, since a stylesheet keyed on one spelling matches nothing the
+* render wrote in another.
+*/
+function componentStateAttribute(name) {
+	return `data-${kebabComponent(name)}`;
+}
+/**
+* The attributes a root carries for its states' values — `{ filled: true }` → `{ 'data-filled': '' }`.
+* A state given no value takes its declared default; one that is false or unset carries nothing.
+* What a projection that has the values up front (the canvas) writes, and what the emitted module's
+* `states` helper writes from the render's.
+*/
+function componentStateAttributes(states, values) {
+	const out = {};
+	for (const state of states) {
+		const value = values[state.name] ?? state.default;
+		if (value === void 0 || value === null || value === false) continue;
+		if (value === "false" && state.type === "boolean") continue;
+		out[componentStateAttribute(state.name)] = state.type === "boolean" ? "" : String(value);
+	}
+	return out;
+}
+/**
 * Every conditional class a component's style rules produce.
 *
 * Unconditional rules are absent by design: they land on the layer's own zero-specificity selector
@@ -171,15 +222,17 @@ function computeRuleClasses(config, path) {
 	const base = componentClassBase(config, path);
 	const out = [];
 	for (const rule of Object.values(styles)) {
-		const when = Object.fromEntries(Object.entries(rule.when ?? {}).map(([prop, value]) => [prop, refLeaf(value)]));
+		const when = Object.fromEntries(Object.entries(rule.when ?? {}).filter(([prop]) => !prop.startsWith("_")).map(([prop, value]) => [prop, refLeaf(value)]));
 		const condition = ruleCondition(when);
 		if (!condition) continue;
 		for (const layer of Object.keys(rule.layers ?? {})) {
 			if (!(layer in layers)) continue;
+			const className = `${base}-${layer}-${condition}`;
+			if (out.some((entry) => entry.className === className)) continue;
 			out.push({
 				layer,
 				when,
-				className: `${base}-${layer}-${condition}`
+				className
 			});
 		}
 	}
@@ -1024,4 +1077,4 @@ function splitVariants(cls) {
 	return segments;
 }
 //#endregion
-export { arbitraryClassName, arbitraryNeedsClass, classLeaf, classSelector, componentClassBase, componentCompositeClasses, componentLayerClass, componentMotionClasses, componentPropClasses, componentPropComposites, componentRuleClasses, forceModeAttribute, forceModeAttributeOf, forceModeProp, forceModePropGroup, forceModePropValue, forceModeProps, forceStateAttribute, inlineRuleComposites, isForceModeProp, kebabComponent, layerJsMotionPresets, layerRoutedProps, modifierUtilitiesUsed, motionClassName, ruleCondition, splitStyleProps, splitVariants, stylePropClassBase, stylePropClassName, stylePropClasses, stylePropOffScaleLiteral, stylePropOwnClasses, styleRuleMotionClasses };
+export { arbitraryClassName, arbitraryNeedsClass, classLeaf, classSelector, componentClassBase, componentCompositeClasses, componentLayerClass, componentMotionClasses, componentPropClasses, componentPropComposites, componentRuleClasses, componentStateAttribute, componentStateAttributes, forceModeAttribute, forceModeAttributeOf, forceModeProp, forceModePropGroup, forceModePropValue, forceModeProps, forceStateAttribute, forceStateSelector, forcedModifierAttributes, inlineRuleComposites, isForceModeProp, kebabComponent, layerJsMotionPresets, layerRoutedProps, modifierUtilitiesUsed, motionClassName, ruleCondition, splitStyleProps, splitVariants, stylePropClassBase, stylePropClassName, stylePropClasses, stylePropOffScaleLiteral, stylePropOwnClasses, styleRuleMotionClasses };

package/dist/framework/component-states.d.ts

@@ -0,0 +1,40 @@
+import { Config } from "./Config.js";
+
+//#region src/framework/component-states.d.ts
+/**
+ * One STATE a component declares (its `states`): what the render knows ("the field has a value",
+ * "the image loaded") and a style rule keys on. Not a prop — a caller never passes one.
+ *
+ * The render reports its states with the `states(…)` call it is handed, in its body before it reads a
+ * layer bundle; the module builds each bundle when the render first reads it, so a rule naming a
+ * state is tested like any prop, against the state's value: forced, else reported, else its rest
+ * value ({@link componentStateDefaults}). The root also carries each state as a `data-<name>`
+ * attribute ({@link componentStateAttribute}). Studio and tests force a state through the module's
+ * internal channel ({@link UDS_FORCE_STATES}), which wins over the render's value.
+ */
+interface ComponentState {
+  readonly name: string;
+  readonly type: 'boolean' | 'variant';
+  /** A variant state's names, in declared order. */
+  readonly values?: readonly string[];
+  /** The value the root carries when neither the render nor a forced value gives one — a variant
+   *  state's declared default. A boolean's rest is `false`, which is no attribute. */
+  readonly default?: string;
+}
+/**
+ * The one key a forced state reaches an emitted module under: `{ [UDS_FORCE_STATES]: { filled: true } }`.
+ * Internal on purpose: Studio's grid and canvas and a test force a state through it, and no caller's
+ * typed props mention it, so forcing a state is never part of a component's API.
+ */
+declare const UDS_FORCE_STATES = "__udsForceStates";
+/** The states a component declares, in declared order — see {@link ComponentState}. Its OWN: a
+ *  state belongs to the render that sets it, so one a layer's component declares is that layer's. */
+declare function componentStates(config: Config, path: string): readonly ComponentState[];
+/**
+ * What each of a component's states reads at rest — a boolean's `false`, a variant's declared
+ * default — which every surface lays a reported or forced value over before testing a rule. A
+ * variant state with no default has no rest value, so a rule naming one of its values waits for one.
+ */
+declare function componentStateDefaults(config: Config, path: string): Record<string, string | boolean>;
+//#endregion
+export { ComponentState, UDS_FORCE_STATES, componentStateDefaults, componentStates };

package/dist/framework/component-states.js

@@ -0,0 +1,53 @@
+import { createSliceMemo } from "./memo.js";
+//#region src/framework/component-states.ts
+/**
+* The one key a forced state reaches an emitted module under: `{ [UDS_FORCE_STATES]: { filled: true } }`.
+* Internal on purpose: Studio's grid and canvas and a test force a state through it, and no caller's
+* typed props mention it, so forcing a state is never part of a component's API.
+*/
+const UDS_FORCE_STATES = "__udsForceStates";
+/** The states a component declares, in declared order — see {@link ComponentState}. Its OWN: a
+*  state belongs to the render that sets it, so one a layer's component declares is that layer's. */
+function componentStates(config, path) {
+	const cache = statesCache(config);
+	const hit = cache.get(path);
+	if (hit) return hit;
+	const states = computeStates(config, path);
+	cache.set(path, states);
+	return states;
+}
+/** Per component slice, the states of each component asked for so far — an expansion asks once per
+*  root it paints. */
+const statesCache = createSliceMemo({
+	kinds: ["component"],
+	compute: (_config) => /* @__PURE__ */ new Map()
+});
+function computeStates(config, path) {
+	const body = config.resolve("component", path)?.toJSON();
+	if (!body?.states || typeof body.states !== "object") return [];
+	const out = [];
+	for (const [name, decl] of Object.entries(body.states)) if (decl?.type === "boolean") out.push({
+		name,
+		type: "boolean"
+	});
+	else if (decl?.type === "variant" && Array.isArray(decl.value)) out.push({
+		name,
+		type: "variant",
+		values: decl.value.map(String),
+		...typeof decl.default === "string" ? { default: decl.default } : {}
+	});
+	return out;
+}
+/**
+* What each of a component's states reads at rest — a boolean's `false`, a variant's declared
+* default — which every surface lays a reported or forced value over before testing a rule. A
+* variant state with no default has no rest value, so a rule naming one of its values waits for one.
+*/
+function componentStateDefaults(config, path) {
+	const out = {};
+	for (const state of componentStates(config, path)) if (state.type === "boolean") out[state.name] = false;
+	else if (state.default !== void 0) out[state.name] = state.default;
+	return out;
+}
+//#endregion
+export { UDS_FORCE_STATES, componentStateDefaults, componentStates };

package/dist/framework/interaction-conditions.d.ts

@@ -0,0 +1,48 @@
+import { Config } from "./Config.js";
+
+//#region src/framework/interaction-conditions.d.ts
+/** One interaction a rule keys on: the bag key, the modifier it resolves to, and whose it is. */
+interface InteractionCondition {
+  /** As written in `when`: `_hover`. */
+  readonly key: string;
+  /** The modifier's path: `state/hover`. */
+  readonly modifier: string;
+  /** The layer whose interaction it is — the root for `true`. */
+  readonly layer: string;
+}
+/** Whether `modifier` (a path or leaf) can be a rule's interaction condition. */
+declare function isInteractionModifier(config: Config, modifier: string): boolean;
+/** The `when` key an interaction modifier is written under: its leaf, `_hover`. */
+declare function interactionKey(modifier: string): string;
+/** Every interaction modifier the config declares, by path. */
+declare function interactionModifiers(config: Config): ReadonlySet<string>;
+/**
+ * A rule's condition split in two: the props and states the render tests, and the interactions the
+ * stylesheet (or, for what CSS can't do, the module's own event tracking) holds it under.
+ */
+declare function whenParts({
+  config,
+  when,
+  layers
+}: {
+  config: Config;
+  when: Readonly<Record<string, unknown>> | null | undefined; /** The component's layers, for the root an interaction's `true` names. */
+  layers?: Readonly<Record<string, unknown>>;
+}): {
+  props: Record<string, unknown>;
+  interactions: InteractionCondition[];
+};
+/** Whether `when` names any interaction — what tells the readers a rule holds only under one. */
+declare function hasInteraction(config: Config, when: Readonly<Record<string, unknown>> | null | undefined): boolean;
+/** One interaction a component's rules key on, with the selector that tells whether it holds. */
+interface ComponentInteraction extends InteractionCondition {
+  /** The modifier's own selector, without its leading `&` (`:hover`): what `element.matches` asks. */
+  readonly selector: string;
+}
+/**
+ * Every interaction a component's rules key on, once per key and layer — what a surface that renders
+ * the component from its config, with no module to track them, watches on the live element.
+ */
+declare function componentInteractions(config: Config, path: string): ComponentInteraction[];
+//#endregion
+export { ComponentInteraction, InteractionCondition, componentInteractions, hasInteraction, interactionKey, interactionModifiers, isInteractionModifier, whenParts };

package/dist/framework/interaction-conditions.js

@@ -0,0 +1,104 @@
+import { modifierCategory } from "../entities/system/modifier-axis.js";
+import { rootLayerOf } from "../entities/system/element.js";
+import { createSliceMemo } from "./memo.js";
+//#region src/framework/interaction-conditions.ts
+/**
+* A style rule's interaction conditions: `when: { _hover: true }`, "while the component is hovered".
+*
+* A rule's `when` names props and states, which the render knows. An interaction is the browser's —
+* the pointer is over an element, it is pressed, it has focus — and a rule may key on one the same
+* way, so the rule's whole reach (styles, an instance's props, content) applies while it holds. The
+* value names whose interaction it is: `true` is the component's own root, and a layer name is that
+* layer (`_hover: 'closeButton'`, "while the close button is hovered").
+*
+* Only an interaction modifier qualifies: a selector modifier that isn't a mode and names a state of
+* the element itself (`:hover`, `[aria-checked="true"]`), never a pseudo-element (`::placeholder`)
+* or a relation to another element (`[data-group]:hover &`).
+*/
+/** Whether `modifier` (a path or leaf) can be a rule's interaction condition. */
+function isInteractionModifier(config, modifier) {
+	return interactionModifiers(config).has(config.resolve("modifier", modifier)?.path ?? "");
+}
+/** The `when` key an interaction modifier is written under: its leaf, `_hover`. */
+function interactionKey(modifier) {
+	return `_${modifier.slice(modifier.lastIndexOf("/") + 1)}`;
+}
+/** Every interaction modifier the config declares, by path. */
+function interactionModifiers(config) {
+	return interactionMemo(config);
+}
+const interactionMemo = createSliceMemo({
+	kinds: ["modifier"],
+	compute: (config) => {
+		const paths = /* @__PURE__ */ new Set();
+		for (const modifier of config.list("modifier")) {
+			const { type, value } = modifier.toJSON() ?? {};
+			if (type !== "selector" || typeof value !== "string") continue;
+			if (modifierCategory(config, modifier.path) === "mode") continue;
+			const own = value.trim().replace(/^&/, "");
+			if (own.includes("::") || own.includes("&") || /\s/.test(own)) continue;
+			paths.add(modifier.path);
+		}
+		return paths;
+	}
+});
+/**
+* A rule's condition split in two: the props and states the render tests, and the interactions the
+* stylesheet (or, for what CSS can't do, the module's own event tracking) holds it under.
+*/
+function whenParts({ config, when, layers }) {
+	const props = {};
+	const interactions = [];
+	const root = layers ? rootLayerOf(layers)[0] : "root";
+	for (const [key, value] of Object.entries(when ?? {})) {
+		const modifier = key.startsWith("_") ? config.resolve("modifier", key.slice(1)) : void 0;
+		if (modifier && interactionModifiers(config).has(modifier.path)) {
+			if (value === false || value === "false" || value == null) continue;
+			interactions.push({
+				key,
+				modifier: modifier.path,
+				layer: value === true || value === "true" ? root : String(value)
+			});
+			continue;
+		}
+		props[key] = value;
+	}
+	return {
+		props,
+		interactions
+	};
+}
+/** Whether `when` names any interaction — what tells the readers a rule holds only under one. */
+function hasInteraction(config, when) {
+	return whenParts({
+		config,
+		when
+	}).interactions.length > 0;
+}
+/**
+* Every interaction a component's rules key on, once per key and layer — what a surface that renders
+* the component from its config, with no module to track them, watches on the live element.
+*/
+function componentInteractions(config, path) {
+	const body = config.resolve("component", path)?.toJSON();
+	const out = [];
+	for (const rule of Object.values(body?.styles ?? {})) {
+		const { interactions } = whenParts({
+			config,
+			when: rule.when,
+			layers: body?.layers
+		});
+		for (const interaction of interactions) {
+			if (out.some((seen) => seen.key === interaction.key && seen.layer === interaction.layer)) continue;
+			const value = (config.resolve("modifier", interaction.modifier)?.toJSON())?.value;
+			if (typeof value !== "string") continue;
+			out.push({
+				...interaction,
+				selector: value.trim().replace(/^&/, "")
+			});
+		}
+	}
+	return out;
+}
+//#endregion
+export { componentInteractions, hasInteraction, interactionKey, interactionModifiers, isInteractionModifier, whenParts };

package/dist/framework/layer-styles.d.ts

@@ -2,7 +2,11 @@ import { Config } from "./Config.js";
 
 //#region src/framework/layer-styles.d.ts
 /** Whether every prop a rule names holds the value it asks for. Compared as strings, because a
- *  condition is canonicalized into the rule's key and a variant value is a string there. */
+ *  condition is canonicalized into the rule's key and a variant value is a string there.
+ *
+ *  An interaction (`_hover`, see `interaction-conditions`) holds only when the state says it does —
+ *  `{ _hover: true }`, a surface forcing it — whichever layer the rule names: no prop bag is ever
+ *  hovered, so at rest the rule is out. */
 declare function ruleApplies(when: Record<string, unknown> | null | undefined, state: Record<string, unknown>): boolean;
 interface LayerStyleOptions {
   /**