@yahoo/uds-create-config 2.45.0 → 3.0.0

package/dist/framework/class-names.js

@@ -0,0 +1,630 @@
+import { isRef, kindOf, pathOf, refLeaf } from "./utils/refs.js";
+import { rootLayerOf } from "../entities/system/element.js";
+import { classPrefixOf } from "../entities/system/Settings.js";
+import { authoredValue, className, negatedCssValue, renderStyleValue, resolveComponentProps, stylePropLeafForToken, stylePropValueLeaves, stylePropertyPathFor } from "./projections.js";
+import { ruleApplies } from "./layer-styles.js";
+import { createSliceMemo } from "./memo.js";
+//#region src/framework/class-names.ts
+/**
+* What a class is CALLED — the one answer, for everything that has to agree about it.
+*
+* Three things name the same class from three directions: the stylesheet writes the rule, the
+* emitted module puts the class on an element, and the canvas — which renders a component the
+* registry has no module for by expanding its anatomy — has to derive the same string at render
+* time from the live config. v1 kept those derivations apart, and any drift between them
+* tree-shakes away a rule the app uses or puts a class on an element the sheet never styled.
+* Both failures are silent and look like "the styling just didn't apply".
+*
+* It lives in config-v2 rather than in codegen because the third caller runs in a browser: a class
+* name is a projection of the config, like a CSS var name or a token's resolved value, and nothing
+* here reads a source file.
+*/
+/** `HStack` → `hstack`, `AvatarItem` → `avatar-item`. A dash only between a lower/digit and an
+*  upper, so an initialism isn't split. */
+function kebabComponent(name) {
+	return name.replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase();
+}
+/**
+* Every attribute Create sets only to hold an element in a condition starts with this. The `create`
+* segment keeps it clear of a consumer's own `data-*` attributes, and `force` says the attribute
+* puts the element in the condition rather than describing it.
+*/
+const FORCE_ATTRIBUTE_PREFIX = "data-create-force-";
+/**
+* The attribute a surface sets to hold a modifier's state open — `data-create-force-focus-visible`.
+*
+* This is a contract between two sides that can't see each other: an editor sets the attribute on an
+* element, and a stylesheet emitted somewhere else has to match it. Every spelling derives from here,
+* including the playground's inlined copy, since a multi-word modifier (`focusVisible`) matches
+* nothing when one side skips the kebab-casing.
+*/
+function forceStateAttribute(modifier) {
+	const name = modifier.startsWith("_") ? modifier.slice(1) : modifier;
+	return `${FORCE_ATTRIBUTE_PREFIX}${kebabComponent(name.slice(name.lastIndexOf("/") + 1))}`;
+}
+/**
+* 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
+* every selector mode's own selector, so an element carrying it is in the mode whatever shape the
+* author gave the selector.
+*/
+function forceModeAttribute(group) {
+	return `${FORCE_ATTRIBUTE_PREFIX}mode-${group.toLowerCase().replaceAll("/", "-")}`;
+}
+/**
+* The attribute and value that force one mode option (`colorMode/dark` →
+* `data-create-force-mode-colormode="dark"`). A mode outside any group has none, since there is no
+* group to force.
+*/
+function forceModeAttributeOf(modePath) {
+	const slash = modePath.lastIndexOf("/");
+	if (slash <= 0) return void 0;
+	return {
+		name: forceModeAttribute(modePath.slice(0, slash)),
+		value: modePath.slice(slash + 1)
+	};
+}
+/**
+* The spec prop that forces a mode group on an element. It keeps the group's authored casing
+* (`data-create-force-mode-colorMode`), and the render wrapper spells it as
+* {@link forceModeAttribute} when it reaches the DOM.
+*/
+function forceModeProp(group) {
+	return `${FORCE_ATTRIBUTE_PREFIX}mode-${group}`;
+}
+/** Persisted specs still carry the spelling this prop had before it was namespaced. */
+const LEGACY_FORCE_MODE_PROP_PREFIX = "data-mode-";
+/** The group a spec prop forces a mode on, or `undefined` when the prop is something else. */
+function forceModePropGroup(key) {
+	const current = `${FORCE_ATTRIBUTE_PREFIX}mode-`;
+	if (key.startsWith(current)) return key.slice(current.length);
+	if (key.startsWith(LEGACY_FORCE_MODE_PROP_PREFIX)) return key.slice(10);
+}
+/** Whether a spec prop forces a mode group, in the current spelling or the one persisted specs carry. */
+function isForceModeProp(key) {
+	return forceModePropGroup(key) !== void 0;
+}
+/**
+* The option a spec's props force for one group, or `undefined`. Reads the current prop first, and
+* falls back to the legacy spelling so a design saved before the rename still forces its mode.
+*/
+function forceModePropValue(props, group) {
+	if (!props) return void 0;
+	for (const key of forceModeProps(group)) {
+		const value = props[key];
+		if (typeof value === "string" && value) return value;
+	}
+}
+/**
+* Every prop that can force one group, current spelling first. A writer clears each of them when it
+* changes the selection, so a legacy key can't keep forcing a mode the user turned off.
+*/
+function forceModeProps(group) {
+	return [forceModeProp(group), `${LEGACY_FORCE_MODE_PROP_PREFIX}${group}`];
+}
+/**
+* The class stem for a component — `uds-list-item`.
+*
+* Derived from the component's PATH, not its name, so a grouped component (`forms/Toggle`) gets a
+* stem no other group can collide with. Everything a component wears extends this stem.
+*/
+function componentClassBase(config, path) {
+	return kebabComponent(className(config, "component", path));
+}
+/** The class one layer wears unconditionally — `uds-list-item-label`. A component's defaults land on
+*  this selector at zero specificity, so nothing about it is conditional. */
+function componentLayerClass(config, path, layer) {
+	return `${componentClassBase(config, path)}-${layer}`;
+}
+/**
+* A rule's condition as it appears in a class name: `{size:'xs'}` → `size-xs`, and an empty condition
+* (an unconditional rule) → `''`.
+*
+* A class name is an IDENTIFIER, so the value is made safe for one: an unescaped `.` starts a second
+* class and `/` is not a name character at all, so a rule keyed on `size: '0.5'` emitted
+* `.uds-card-root-size-0.5` — parsed as `.uds-card-root-size-0` plus garbage, discarding the rule,
+* while the module put the literal string on the element.
+*
+* Written out rather than shared with {@link stylePropClassName}, which applies the same transform:
+* as a small module-private helper it did not survive one of the bundlers this module is compiled
+* through, and `uds build` died on `classSafe is not defined`. Two spellings of four characters is
+* the cheaper problem.
+*/
+function ruleCondition(when) {
+	return Object.entries(when ?? {}).map(([prop, value]) => `${prop}-${String(value).replaceAll("/", "-").replaceAll(".", "_").replace(/\s+/g, "-")}`).join("-");
+}
+/**
+* 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
+* ({@link componentLayerClass}), which every element already wears with nothing to test.
+*/
+function componentRuleClasses(config, path) {
+	const component = config.resolve("component", path);
+	if (!component) return [];
+	const { layers = {}, styles = {} } = component.toJSON();
+	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 condition = ruleCondition(when);
+		if (!condition) continue;
+		for (const layer of Object.keys(rule.layers ?? {})) {
+			if (!(layer in layers)) continue;
+			out.push({
+				layer,
+				when,
+				className: `${base}-${layer}-${condition}`
+			});
+		}
+	}
+	return out;
+}
+/** The MEMBER a bag value names, under the group its prop binds — the value is either the qualified
+*  ref it is stored as, or the bare leaf an older body holds. */
+function memberNamed(groupRef, value) {
+	if (isRef(value)) return pathOf(value.__ref);
+	return typeof value === "string" ? `${pathOf(groupRef)}/${value}` : void 0;
+}
+/** The same read for a value whose domain is a whole KIND rather than a group, so the ref's path is
+*  the name itself. */
+function presetNamed(value) {
+	if (isRef(value)) return pathOf(value.__ref);
+	return typeof value === "string" ? value : void 0;
+}
+/**
+* Every COMPOSITE class a component's style rules apply, with the condition each applies under.
+*
+* A composite prop names a value (`variant: 'ui6'`) whose CSS is a class rather than a set of
+* declarations, so it can't reach the element the way a style prop does. Same shape as
+* {@link componentRuleClasses} for that reason.
+*
+* This answers WHICH CLASS a rule's composite ends up as, not who applies it — the layer's receiver
+* does, out of the prop it is forwarded ({@link layerCompositeProps}). The caller is the EXTRACTOR,
+* which has to keep that class's CSS from being shaken out as unreferenced: after the forward the
+* value appears in the emitted module only as a prop string, so nothing else in the build names it.
+*
+* Unlike `componentRuleClasses`, an UNCONDITIONAL rule is included (`when` empty). That function
+* omits them because their declarations land on the layer's own zero-specificity selector — but a
+* composite contributes no declarations there, so omitting it would drop the class entirely.
+*/
+function componentCompositeClasses(config, path) {
+	const component = config.resolve("component", path);
+	if (!component) return [];
+	const { layers = {}, styles = {} } = component.toJSON();
+	const out = [];
+	for (const rule of Object.values(styles)) {
+		const when = Object.fromEntries(Object.entries(rule.when ?? {}).map(([prop, value]) => [prop, refLeaf(value)]));
+		for (const [layer, bag] of Object.entries(rule.layers ?? {})) {
+			const element = layers[layer];
+			if (!isRef(element)) continue;
+			const declared = resolveComponentProps(config, pathOf(element.__ref));
+			for (const [prop, value] of Object.entries(bag ?? {})) {
+				const bound = declared[prop]?.value;
+				if (!isRef(bound) || kindOf(bound.__ref) !== "composite") continue;
+				const target = memberNamed(bound.__ref, value);
+				if (target === void 0 || !config.resolve("composite", target)) continue;
+				out.push({
+					layer,
+					when,
+					className: className(config, "composite", target)
+				});
+			}
+		}
+	}
+	return out;
+}
+/** The class a CSS motion preset is applied by. Namespaced, so it doesn't share a space with the
+*  style-prop utilities; the `@keyframes` it runs keep their own name. */
+function motionClassName(config, path) {
+	return `${classPrefixOf(config)}-motion-${path.replaceAll("/", "-")}`;
+}
+/**
+* Every MOTION class a component's style rules apply — a layer bag naming a preset (`motion: 'spin'`).
+*
+* The same shape and the same reason as {@link componentCompositeClasses}: a CSS preset's whole
+* runtime is a class, so a layer that references one has to wear it, under whatever condition its
+* rule declares. Without this the value went nowhere — `motion` names no style property so it isn't
+* a declaration, and it IS a declared prop of the layer's element so it isn't an attribute either.
+*
+* A JS preset is skipped: it animates in the client and has no class to wear.
+*/
+function componentMotionClasses(config, path) {
+	const component = config.resolve("component", path);
+	if (!component) return [];
+	const { layers = {}, styles = {} } = component.toJSON();
+	const out = [];
+	for (const rule of Object.values(styles)) {
+		const when = Object.fromEntries(Object.entries(rule.when ?? {}).map(([prop, value]) => [prop, refLeaf(value)]));
+		for (const [layer, bag] of Object.entries(rule.layers ?? {})) {
+			const element = layers[layer];
+			if (!isRef(element)) continue;
+			const declared = resolveComponentProps(config, pathOf(element.__ref));
+			for (const [prop, value] of Object.entries(bag ?? {})) {
+				if (declared[prop]?.type !== "motion") continue;
+				const name = presetNamed(value);
+				if (name === void 0) continue;
+				const preset = config.resolve("motion", name)?.toJSON();
+				if (preset?.runtime !== "css" || !preset.keyframes) continue;
+				out.push({
+					layer,
+					when,
+					className: motionClassName(config, name)
+				});
+			}
+		}
+	}
+	return out;
+}
+/**
+* The classes a component's OWN props put on it, by layer — `variant="body"` picking
+* `textVariant/body`'s class.
+*
+* A composite is the only prop that works this way, and it has to: its whole CSS is a class, so it
+* can't ride the prop channel the way a style prop does. That makes it the one piece of an
+* instance's styling a projection can lose entirely, and losing it is what made a component look one
+* way in the component editor and another on a canvas — the expansion resolved it, the anatomy
+* projection had no route for it, and the matrix painted the cell in the wrong typography.
+*
+* So both projections read this and neither derives it. `state` is merged over the component's
+* defaults, because a value the caller didn't set has to read the default — the same rule
+* {@link layerStyles} follows.
+*
+* Keyed by layer even though today it only ever names the ROOT one, so a caller needs no opinion
+* about which layer that is: an instance's own props land where its own props land.
+*/
+function componentPropClasses(config, path, state = {}) {
+	const component = config.resolve("component", path);
+	if (!component) return {};
+	const { layers = {}, props = {}, defaultProps = {} } = component.toJSON();
+	const [root] = rootLayerOf(layers);
+	const resolved = {
+		...defaultProps,
+		...state
+	};
+	const classes = [];
+	for (const [prop, decl] of Object.entries(props)) {
+		if (decl?.type !== "composite") continue;
+		const group = isRef(decl.value) ? decl.value.__ref : void 0;
+		const value = resolved[prop];
+		if (!group) continue;
+		const target = memberNamed(group, value);
+		if (target === void 0) continue;
+		if (!config.resolve("composite", target)) continue;
+		classes.push(className(config, "composite", target));
+	}
+	return classes.length > 0 ? { [root]: classes } : {};
+}
+/**
+* The COMPOSITE a style rule sets on each layer, for one instance — forwarded to the layer as a prop.
+*
+* A composite's whole CSS is a class, so a rule's condition class (where the stylesheet hangs its
+* DECLARATIONS) cannot carry one. The route is the layer's RECEIVER: the bag key already IS that
+* receiver's own prop name — `variant` for a `Text`-backed layer, `textVariant` for an `Input`-backed
+* one, both binding the same group — so this copies the key verbatim and there is nothing to resolve.
+* `Text` turns `variant="label3"` into `uds-textVariant-label3` for itself, and always has.
+*
+* Forwarding rather than resolving is what makes a layer's styling live-editable at all: a class only
+* exists once a build has emitted the stylesheet, so an edit that makes a NEW style rule paints
+* nothing until a rebuild, while a prop json-render applies on the spot. Both projections of a
+* component read this, so neither has to know the receiver's name for the group.
+*
+* Only what the receiver DECLARES as composite-typed. A bag key it doesn't declare is an ordinary
+* prop or an attribute, and belongs to whatever channel already carries it.
+*/
+function layerCompositeProps(config, path, state = {}) {
+	const component = config.resolve("component", path);
+	if (!component) return {};
+	const { layers = {}, styles = {}, defaultProps = {} } = component.toJSON();
+	const resolved = {
+		...defaultProps,
+		...state
+	};
+	const out = {};
+	const applicable = Object.values(styles).filter((rule) => ruleApplies(rule.when, resolved)).sort((left, right) => Object.keys(left.when ?? {}).length - Object.keys(right.when ?? {}).length);
+	for (const rule of applicable) for (const [layer, bag] of Object.entries(rule.layers ?? {})) {
+		const element = layers[layer];
+		if (!isRef(element)) continue;
+		const declared = resolveComponentProps(config, pathOf(element.__ref));
+		for (const [prop, value] of Object.entries(bag ?? {})) {
+			const bound = declared[prop]?.value;
+			if (!isRef(bound) || kindOf(bound.__ref) !== "composite") continue;
+			out[layer] ??= {};
+			out[layer][prop] = authoredValue(config, prop, value);
+		}
+	}
+	return out;
+}
+/**
+* The CSS MOTION classes a style rule puts on a layer, for one instance.
+*
+* A preset's whole runtime is a class too, and a composite's route (forward it, and let the receiver
+* resolve its own prop — {@link layerCompositeProps}) does not exist for this one: `motion` is not a
+* style property, so {@link splitStyleProps} has no dispatch for it and a forwarded `motion="spin"`
+* would reach the element as an attribute and animate nothing. The emitted runtime table DOES carry
+* it — codegen adds a closed `motion` entry — which is why a component with a module needs nothing
+* here, and one expanded from the config alone needs this.
+*/
+function styleRuleMotionClasses(config, path, state = {}) {
+	const { defaultProps = {} } = config.resolve("component", path)?.toJSON() ?? {};
+	const resolved = {
+		...defaultProps,
+		...state
+	};
+	const out = {};
+	for (const rule of componentMotionClasses(config, path)) {
+		if (!ruleApplies(rule.when, resolved)) continue;
+		out[rule.layer] ??= [];
+		if (!out[rule.layer].includes(rule.className)) out[rule.layer].push(rule.className);
+	}
+	return out;
+}
+/**
+* The class-name stem for a style prop: its authored `classPrefix` when it declares one, else its
+* path — or, for an OPACITY COMPANION, its target's stem plus `-opacity`.
+*
+* An EMPTY prefix is meaningful and not the same as an absent one — `position: absolute` ships as
+* `.uds-absolute`, with no prop segment at all — so this tests for `undefined` rather than
+* falsiness.
+*
+* The companion case exists because the path fallback is wrong for one: a companion is named after
+* the prop it modulates (`bgOpacity`), so falling back to the path spells the stem in the prop's
+* camelCase (`uds-bgOpacity`) rather than the kebab every other class uses, and spells it
+* independently of the target whose fade it is. Deriving it from the PAIRING keeps the two in step —
+* renaming `bg`'s prefix moves `bg-opacity` with it — and costs a config nothing to author. Every
+* opacity prop in every config in this repo declares no prefix, which is what made this reachable.
+*/
+function stylePropClassBase(config, path) {
+	const { classPrefix, opacityOf } = config.resolve("style-property", path)?.toJSON() ?? {};
+	if (classPrefix === void 0 && opacityOf) return `${stylePropClassBase(config, pathOf(opacityOf.__ref))}-opacity`;
+	const segment = classPrefix ?? path;
+	return segment ? className(config, "style-property", segment) : classPrefixOf(config);
+}
+/**
+* The class for one authored value — `bg="primary"` → `uds-bg-primary`.
+*
+* The value is a LEAF, which is what a call site writes; an empty leaf is a boolean prop's `true`
+* arm, whose class is the bare stem (`uds-border`) because a flag names no value.
+*
+* A slash becomes a dash and a DOT an underscore, because a class name can hold neither: `.uds-p-0.5`
+* is not one selector but two (`uds-p-0` and `5`), so the rule the sheet wrote could never match the
+* element the module classed. `spacing/0.5` is a real token in a real system, which is how that
+* surfaced.
+*/
+function stylePropClassName(config, path, leaf) {
+	const base = stylePropClassBase(config, path);
+	const suffix = leaf.replaceAll("/", "-").replaceAll(".", "_").replace(/\s+/g, "-");
+	return suffix ? `${base}-${suffix}` : base;
+}
+/** An off-scale value and what it really is — `[13px]` → `13px`, else `undefined`. The brackets mark
+*  a value the system doesn't tokenize; they aren't part of it. No class can exist for one, because a
+*  class is emitted per DECLARED value and this is by definition not declared. Inside the brackets an
+*  underscore encodes a space (`[repeat(7,_36px)]` → `repeat(7, 36px)`); it must be reversed here
+*  because a CSS value with a literal underscore is invalid and the browser drops the declaration.
+*  A `url(…)` span is exempt — its underscores are part of the address, not an escape (an AI-repaired
+*  spec brackets a model-emitted `url(…)` verbatim), which is the same carve-out Tailwind makes. */
+function offScale(value) {
+	if (typeof value !== "string") return void 0;
+	return value.startsWith("[") && value.endsWith("]") ? unescapeArbitrary(value.slice(1, -1)) : void 0;
+}
+/** `_` → space, except inside `url(…)` where an underscore is literal. */
+function unescapeArbitrary(value) {
+	return value.replace(/url\([^)]*\)|_/g, (span) => span === "_" ? " " : span);
+}
+/**
+* Split a prop bag into a class string and the props that aren't styling.
+*
+* This is the same dispatch the emitted `_style-props` runtime performs, over a live config instead
+* of the table that build baked. Both exist because they run in different places — an app's module
+* has no config at runtime, and the canvas has no baked table for a component that was never built —
+* but the CLASS NAMES both produce come from {@link stylePropClassName}, so the two can't disagree
+* about what a value is called.
+*
+* An off-scale value can't be a class, so it lands in `style` on the returned rest; an explicit
+* `style` the caller passed still wins, since that's the escape hatch of last resort.
+*/
+function splitStyleProps({ config, bag, through }) {
+	const classes = [];
+	const rest = {};
+	const style = {};
+	const modifiers = new Map(config.list("modifier").map((modifier) => [`_${modifier.leaf}`, modifier.leaf]));
+	for (const [key, value] of Object.entries(bag)) {
+		const modifier = modifiers.get(key);
+		if (modifier) {
+			if (value && typeof value === "object" && !Array.isArray(value)) {
+				const inner = splitStyleProps({
+					config,
+					bag: value,
+					through
+				});
+				for (const cls of inner.className.split(" ").filter(Boolean)) classes.push(`${modifier}:${cls}`);
+			}
+			continue;
+		}
+		const name = stylePropertyPathFor({
+			config,
+			through,
+			key
+		}) ?? key;
+		const prop = config.resolve("style-property", name);
+		if (!prop) {
+			rest[key] = value;
+			continue;
+		}
+		if (value === void 0 || value === null) continue;
+		const { arbitrary, properties = [], negates } = prop.toJSON();
+		const off = arbitrary ? offScale(value) : void 0;
+		if (off !== void 0) {
+			const declared = negates ? negatedCssValue(off) : off;
+			for (const property of properties) style[reactStyleKey(property)] = declared;
+			continue;
+		}
+		if (isRef(value) && kindOf(value.__ref) === "token") {
+			const leaf = stylePropLeafForToken(config, name, pathOf(value.__ref));
+			if (leaf !== void 0) {
+				classes.push(stylePropClassName(config, name, leaf));
+				continue;
+			}
+		}
+		if (typeof value === "boolean") {
+			if (value) classes.push(stylePropClassName(config, name, ""));
+			continue;
+		}
+		if (typeof value === "object") {
+			const rendered = renderStyleValue(config, value);
+			const declared = negates ? negatedCssValue(rendered) : rendered;
+			for (const property of properties) style[reactStyleKey(property)] = declared;
+			continue;
+		}
+		classes.push(stylePropClassName(config, name, String(value)));
+	}
+	if (Object.keys(style).length > 0) {
+		const given = rest.style;
+		const explicit = {};
+		for (const [property, value] of Object.entries(given ?? {})) explicit[reactStyleKey(property)] = value;
+		rest.style = {
+			...style,
+			...explicit
+		};
+	}
+	return {
+		className: classes.join(" "),
+		rest
+	};
+}
+/**
+* A CSS property name as REACT's `style` object spells it.
+*
+* `rest.style` is handed to React, not written into a stylesheet, and React's `style` takes
+* camelCase. It does not merely tolerate the CSS spelling — it DROPS the declaration and warns. So
+* every off-scale value, computed colour and gradient on this path painted nothing, and the only
+* sign was a dev-console line among many.
+*
+* A custom property (`--uds-brand`) is passed through untouched: React writes those verbatim, and
+* camelCasing one would break the case that already worked.
+*/
+function reactStyleKey(property) {
+	if (property.startsWith("--")) return property;
+	return property.replace(/-([a-z])/g, (_, char) => char.toUpperCase());
+}
+/**
+* Every class a prop can produce, by leaf.
+*
+* Deduplicated on the leaf, keeping the FIRST: a prop may bind two token groups that share one
+* (`top` takes both `spacing` and `position`, and both declare `0`), and `stylePropValueFromLeaf`
+* resolves such a value with a `.find()` — so authored order already decides which token a leaf
+* means, and the class set follows that rather than inventing a second answer.
+*/
+function stylePropClasses(config, path) {
+	const out = /* @__PURE__ */ new Map();
+	for (const leaf of stylePropValueLeaves(config, path)) if (!out.has(leaf)) out.set(leaf, stylePropClassName(config, path, leaf));
+	return out;
+}
+/**
+* Every MODIFIER-prefixed utility class the config itself asks for — `focus:uds-border-color-brand`.
+*
+* Modifier utilities can't be emitted exhaustively: every modifier against every utility is 25 ×
+* 9,284 rules for a real system, and a sheet nobody can load is the same as no sheet. So they're
+* driven by USE, and a build takes `used` from having read the app's source files.
+*
+* Studio has no source files to read, and doesn't need any: a config STATES what it asks for. Every
+* bag it holds — a component's defaults, a preview's, each style rule's per-layer bag, each anatomy
+* node's props, a composite's bag — goes through the same {@link splitStyleProps} the runtime uses,
+* so the strings match on both sides by construction rather than by agreement. For the studio system
+* that's 86 classes against 232,100.
+*
+* WHAT THIS CANNOT SEE, stated because the gap is real: a prop set on a design-file NODE (a
+* `_hover` a user adds in the designer panel) is in the document, not the system, so no projection of
+* the system can predict it. Covering those needs the document as a second source of use.
+*/
+function modifierUtilitiesUsed(config) {
+	const used = /* @__PURE__ */ new Set();
+	const token = vocabularyToken(config);
+	const stored = config.snapshot.slice("component").items;
+	for (const component of config.list("component")) for (const cls of classesUsedBy(config, stored.get(component.path) ?? component, token, componentBags)) used.add(cls);
+	const storedComposites = config.snapshot.slice("composite").items;
+	for (const composite of config.list("composite")) for (const cls of classesUsedBy(config, storedComposites.get(composite.path) ?? composite, token, compositeBags)) used.add(cls);
+	return used;
+}
+/**
+* Every style bag a COMPONENT states it wants, each with the definitions its keys resolve against.
+*
+* Not uniform, which is the whole reason it travels with the bag. `defaultProps` and `previewProps`
+* are the component's OWN props, and nothing else has a claim. A style rule's per-layer bag and an
+* anatomy node's props are set on a LAYER'S ELEMENT, so that element answers too — after the
+* component itself, whose own declaration of a name is what that name means throughout its
+* definition.
+*/
+function componentBags(entity) {
+	const { path } = entity;
+	const { defaultProps, previewProps, styles, anatomy, layers } = entity.toJSON();
+	const bags = [{
+		bag: defaultProps,
+		through: [path]
+	}, {
+		bag: previewProps,
+		through: [path]
+	}];
+	for (const rule of Object.values(styles ?? {})) for (const [layer, bag] of Object.entries(rule?.layers ?? {})) bags.push({
+		bag,
+		through: [path, componentElementOf(layers?.[layer])]
+	});
+	for (const node of Object.values(anatomy ?? {})) bags.push({
+		bag: node?.props,
+		through: [path, componentElementOf(node?.element)]
+	});
+	return bags;
+}
+/** The component an element ref names, or `undefined` for a raw tag or a layer ref — neither of which
+*  is a component whose props could be renamed. */
+function componentElementOf(element) {
+	return isRef(element) && kindOf(element.__ref) === "component" ? pathOf(element.__ref) : void 0;
+}
+/** A composite states one bag, and it belongs to no component. */
+function compositeBags(entity) {
+	return [{ bag: entity.toJSON().styles }];
+}
+/**
+* A token object that changes when the class VOCABULARY does — the style properties, and everything
+* their value domains reach.
+*
+* `splitStyleProps` names a class by asking the config what a prop's leaves are, so a scan's answer
+* survives any edit that leaves those alone. Which is every edit to the entities being scanned.
+*/
+const vocabularyToken = createSliceMemo({
+	kinds: [
+		"style-property",
+		"token",
+		"composite",
+		"motion",
+		"icon",
+		"font"
+	],
+	compute: (_config) => ({})
+});
+const usedClassCache = /* @__PURE__ */ new WeakMap();
+/** One owner's prefixed classes, cached on (its stored entity, the vocabulary). */
+function classesUsedBy(config, stored, token, bagsOf) {
+	let byVocabulary = usedClassCache.get(stored);
+	if (!byVocabulary) {
+		byVocabulary = /* @__PURE__ */ new WeakMap();
+		usedClassCache.set(stored, byVocabulary);
+	}
+	const hit = byVocabulary.get(token);
+	if (hit) return hit;
+	const found = [];
+	for (const { bag, through } of bagsOf(stored)) {
+		if (!bag || typeof bag !== "object" || Array.isArray(bag)) continue;
+		const { className } = splitStyleProps({
+			config,
+			bag,
+			through
+		});
+		for (const cls of className.split(" ")) if (cls.includes(":")) found.push(cls);
+	}
+	byVocabulary.set(token, found);
+	return found;
+}
+//#endregion
+export { componentClassBase, componentCompositeClasses, componentLayerClass, componentMotionClasses, componentPropClasses, componentRuleClasses, forceModeAttribute, forceModeAttributeOf, forceModeProp, forceModePropGroup, forceModePropValue, forceModeProps, forceStateAttribute, isForceModeProp, kebabComponent, layerCompositeProps, modifierUtilitiesUsed, motionClassName, ruleCondition, splitStyleProps, stylePropClassBase, stylePropClassName, stylePropClasses, styleRuleMotionClasses };

package/dist/framework/coalesce.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Run an expensive side effect for the LAST value of a burst, never for the ones it superseded.
+ *
+ * Here rather than in the app because coalescing is not a property of any one derivation: one user
+ * gesture reaches a config holder several times — an edit lands optimistically, comes back as a
+ * realtime echo, then again as the pull that trues up against what the server persisted. Each landing
+ * describes the same edit, so a subscriber that recomputes per landing pays for two results nobody
+ * ever sees, on the frames the gesture is trying to respond on. That is true of every `onChange`
+ * point, so {@link runChangeHooks} owns it and a hook never writes it again.
+ *
+ * Leading-edge, not a trailing debounce: the first value is handed to `schedule` right away, so a
+ * continuous gesture (a drag that writes per tick) keeps painting instead of going dark until it
+ * stops. What coalesces is everything that arrives while a run is scheduled or in flight — those
+ * collapse into ONE follow-up run carrying the newest value.
+ *
+ * `run` may be async; a value arriving mid-run waits for it rather than overlapping, which is what
+ * keeps an older result from landing after a newer one.
+ */
+export declare function coalesceLatest<T>({ run, schedule, }: {
+    readonly run: (value: T) => void | Promise<void>;
+    /** When a queued run fires — an idle callback, a timer, immediately. */
+    readonly schedule: (fire: () => void) => void;
+}): ((value: T) => void) & {
+    cancel: () => void;
+};