@yahoo/uds-create-config 2.45.0 → 3.0.0

package/dist/framework/changes.js

@@ -0,0 +1,246 @@
+//#region src/framework/changes.ts
+/** The base as a config of its own — the branch with no draft applied. */
+function baseOf(config) {
+	return config.withDraft([]).config;
+}
+const str = (value) => typeof value === "string" ? value : void 0;
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/** A value inside a body, by dotted path. `undefined` past any missing step. */
+function walk(body, segments) {
+	let current = body;
+	for (const segment of segments) {
+		if (!isRecord(current)) return void 0;
+		current = current[segment];
+	}
+	return current;
+}
+/**
+* The dotted path a sub-op's member sits at. `field` is the declared path (`props/value`) and
+* `owner` the member it sits in (`size`), so the owner slots in after the first segment.
+*/
+function subFieldPath({ field, owner, key }) {
+	const [head, ...rest] = field.split("/");
+	const segments = owner ? [
+		head,
+		owner,
+		...rest
+	] : [head, ...rest];
+	if (key !== void 0) segments.push(key);
+	return segments.join(".");
+}
+/** The body a target has in a config: the resolved item, or the stored group node. */
+function bodyAt(config, kind, path, target) {
+	if (target === "group") return config.groupMeta(kind, path);
+	return config.resolve(kind, path)?.body;
+}
+/** The value a change addresses in one config — the body, or the field within it. */
+function changeValueAt({ config, change, side }) {
+	if (change.target === "order" || change.path === void 0) return side === "before" ? config.snapshot.values(change.kind).map((entity) => entity.path) : void 0;
+	const body = bodyAt(config, change.kind, change.path, change.target);
+	if (change.field === void 0) return body;
+	return walk(body, change.field.split("."));
+}
+const GROUP_OPERATIONS = new Set([
+	"group-update",
+	"group-rename",
+	"group-delete"
+]);
+/** One pending patch as a change, with its values read off `base` and `draft`. */
+function changeOf(entry, { base, draft }) {
+	const patch = entry.patch;
+	const kind = str(patch.kind) ?? "config";
+	const operation = str(patch.verb) ?? str(patch.operation) ?? "update";
+	const path = str(patch.path) ?? str(patch.input?.path);
+	const to = str(patch.to);
+	const head = {
+		id: entry.id,
+		changeset: entry.changeset,
+		kind,
+		operation
+	};
+	if (operation === "reorder" || operation === "group-reorder") return {
+		...head,
+		target: "order",
+		before: base.snapshot.values(kind).map((entity) => entity.path),
+		after: Array.isArray(patch.order) ? patch.order : void 0
+	};
+	const target = GROUP_OPERATIONS.has(operation) ? "group" : "item";
+	if (operation === "rename" || operation === "group-rename") return {
+		...head,
+		target,
+		path,
+		to,
+		before: path,
+		after: to
+	};
+	let field;
+	const declaredField = str(patch.field);
+	if (declaredField !== void 0) field = subFieldPath({
+		field: declaredField,
+		owner: str(patch.owner),
+		key: str(patch.key)
+	});
+	else if ((operation === "update" || operation === "group-update") && isRecord(patch.data)) {
+		const keys = Object.keys(patch.data);
+		if (keys.length === 1) field = keys[0];
+	}
+	const shape = {
+		kind,
+		path,
+		field,
+		target
+	};
+	return {
+		...head,
+		target,
+		path,
+		field,
+		before: changeValueAt({
+			config: base,
+			change: shape,
+			side: "before"
+		}),
+		after: changeValueAt({
+			config: draft,
+			change: shape,
+			side: "after"
+		})
+	};
+}
+/** Every pending patch of `config` as a change, in draft order. */
+function changesOf(config, base = baseOf(config)) {
+	return config.pending.map((entry) => changeOf(entry, {
+		base,
+		draft: config
+	}));
+}
+/** `path` relative to `entity`: `''` for the entity itself, else the remainder. */
+function relativeTo(entity, path) {
+	if (path === entity) return "";
+	if (path.startsWith(`${entity}/`)) return path.slice(entity.length + 1);
+	return path;
+}
+/** The last segment of a path. */
+const leafOf = (path) => path.slice(path.lastIndexOf("/") + 1);
+const quoteList = (names) => [...names].map((name) => `'${name}'`).join(", ");
+/** A collector for one phrase family: subgroups touched and leaf names touched, kept in order. */
+var Touched = class {
+	subgroups = /* @__PURE__ */ new Set();
+	leaves = /* @__PURE__ */ new Set();
+	add(relative) {
+		const slash = relative.indexOf("/");
+		if (slash === -1) this.leaves.add(relative);
+		else this.subgroups.add(relative.slice(0, slash));
+	}
+	get empty() {
+		return this.subgroups.size === 0 && this.leaves.size === 0;
+	}
+};
+/**
+* What a set of changes on one entity did, in words — the line a card carries under the entity's
+* name. `entity` is the path the changes are grouped under, which may be a prefix of what each
+* change addresses (a token group over its tokens) or the item itself (a component).
+*/
+function summarizeChanges({ config, kind, entity, changes }) {
+	const label = config.entityLabel(kind).toLowerCase();
+	const plural = config.entityLabelPlural(kind).toLowerCase();
+	const added = new Touched();
+	const adjusted = new Touched();
+	const removed = /* @__PURE__ */ new Set();
+	const renamed = [];
+	const newMembers = /* @__PURE__ */ new Map();
+	const ownFields = /* @__PURE__ */ new Set();
+	let reordered = false;
+	for (const change of changes) {
+		if (change.target === "order") {
+			reordered = true;
+			continue;
+		}
+		const relative = entity !== void 0 && change.path !== void 0 ? relativeTo(entity, change.path) : change.path ?? "";
+		switch (change.operation) {
+			case "create":
+			case "replace":
+				added.add(relative);
+				break;
+			case "group-update":
+				if (change.before === void 0) added.add(relative);
+				else adjusted.add(relative);
+				break;
+			case "sub-create":
+			case "sub-upsert": {
+				const head = change.field?.split(".")[0] ?? "";
+				const name = (config.subEntityOf(kind, head)?.label ?? head).toLowerCase();
+				newMembers.set(name, (newMembers.get(name) ?? 0) + 1);
+				break;
+			}
+			case "delete":
+			case "group-delete":
+				removed.add(relative || leafOf(change.path ?? label));
+				break;
+			case "rename":
+			case "group-rename":
+				renamed.push(`Renamed '${relative || change.path}' to '${entity !== void 0 && change.to !== void 0 ? relativeTo(entity, change.to) : change.to}'`);
+				break;
+			default: if (relative === "") {
+				const head = change.field?.split(".")[0];
+				if (head) ownFields.add(head);
+				else adjusted.add("");
+			} else adjusted.add(relative);
+		}
+	}
+	const phrases = [];
+	if (added.subgroups.size > 0) {
+		const noun = added.subgroups.size === 1 ? "subgroup" : "subgroups";
+		phrases.push(`New ${noun} ${quoteList(added.subgroups)} added`);
+	}
+	if (added.leaves.size > 0) {
+		const leaves = [...added.leaves].filter((leaf) => leaf !== "");
+		if (leaves.length > 0) {
+			const noun = leaves.length === 1 ? label : plural;
+			phrases.push(`New ${noun} ${quoteList(leaves)} added`);
+		}
+		if (added.leaves.has("")) phrases.push(`New ${label}`);
+	}
+	for (const [name, count] of newMembers) phrases.push(count === 1 ? `New ${name}` : `${count} new ${name}s`);
+	if (adjusted.subgroups.size > 0) {
+		const noun = adjusted.subgroups.size === 1 ? "subgroup" : "subgroups";
+		phrases.push(`Adjustments to ${noun} ${quoteList(adjusted.subgroups)}`);
+	}
+	{
+		const leaves = [...adjusted.leaves].filter((leaf) => leaf !== "");
+		if (leaves.length > 0) phrases.push(`Adjustments to ${quoteList(leaves)}`);
+	}
+	if (ownFields.size > 0) phrases.push(`Adjustments to ${[...ownFields].join(", ")}`);
+	else if (adjusted.leaves.has("")) phrases.push("Adjustments");
+	if (removed.size > 0) phrases.push(`Removed ${quoteList(removed)}`);
+	phrases.push(...renamed);
+	if (reordered) phrases.push(`Reordered ${plural}`);
+	return phrases.join("; ");
+}
+const count = (n, one, many) => `${n} ${n === 1 ? one : many}`;
+/**
+* A body summarized as what it contains — the cell for a created or deleted container, where the
+* body itself is too much to show. `undefined` for a value that is not a body.
+*
+* `config` is the one the body was read from, since a group's members are counted there.
+*/
+function describeBody({ config, kind, path, target, value }) {
+	if (!isRecord(value)) return void 0;
+	const label = config.entityLabel(kind).toLowerCase();
+	const plural = config.entityLabelPlural(kind).toLowerCase();
+	if (target === "group") {
+		const members = config.members(kind, path).length;
+		return `1 ${label} group with ${count(members, label, plural)}`;
+	}
+	const parts = [];
+	const subEntities = config.entityOf(kind)?.subEntities ?? {};
+	for (const [field, sub] of Object.entries(subEntities)) {
+		const members = value[field];
+		const size = isRecord(members) ? Object.keys(members).length : 0;
+		if (size === 0) continue;
+		parts.push(count(size, sub.label.toLowerCase(), sub.labelPlural.toLowerCase()));
+	}
+	return parts.length > 0 ? `1 ${label} with ${parts.join(", ")}` : `1 ${label}`;
+}
+//#endregion
+export { baseOf, changeOf, changeValueAt, changesOf, describeBody, summarizeChanges };

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

@@ -0,0 +1,260 @@
+import { Config } from "./Config.js";
+
+//#region src/framework/class-names.d.ts
+/** `HStack` → `hstack`, `AvatarItem` → `avatar-item`. A dash only between a lower/digit and an
+ *  upper, so an initialism isn't split. */
+declare function kebabComponent(name: string): string;
+/**
+ * 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.
+ */
+declare function forceStateAttribute(modifier: 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
+ * 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.
+ */
+declare function forceModeAttribute(group: string): string;
+/**
+ * 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.
+ */
+declare function forceModeAttributeOf(modePath: string): {
+  name: string;
+  value: string;
+} | undefined;
+/**
+ * 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.
+ */
+declare function forceModeProp(group: string): string;
+/** The group a spec prop forces a mode on, or `undefined` when the prop is something else. */
+declare function forceModePropGroup(key: string): string | undefined;
+/** Whether a spec prop forces a mode group, in the current spelling or the one persisted specs carry. */
+declare function isForceModeProp(key: string): boolean;
+/**
+ * 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.
+ */
+declare function forceModePropValue(props: Readonly<Record<string, unknown>> | undefined, group: string): string | undefined;
+/**
+ * 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.
+ */
+declare function forceModeProps(group: string): readonly string[];
+/**
+ * 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.
+ */
+declare function componentClassBase(config: Config, path: string): string;
+/** 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. */
+declare function componentLayerClass(config: Config, path: string, layer: string): string;
+/**
+ * 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.
+ */
+declare function ruleCondition(when: Record<string, unknown> | null | undefined): 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. */
+  readonly layer: string;
+  /** Prop → value, all of which must match for the class to apply. Empty means unconditional.
+   *  `unknown` rather than `string`: a condition on a boolean prop holds a real `true`, and the
+   *  emitted module tests it with `=== true`. */
+  readonly when: Record<string, unknown>;
+  readonly className: string;
+}
+/**
+ * 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.
+ */
+declare function componentRuleClasses(config: Config, path: string): ComponentRuleClass[];
+/**
+ * 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.
+ */
+declare function componentCompositeClasses(config: Config, path: string): ComponentRuleClass[];
+/** 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. */
+declare function motionClassName(config: Config, path: string): string;
+/**
+ * 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.
+ */
+declare function componentMotionClasses(config: Config, path: string): ComponentRuleClass[];
+/**
+ * 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.
+ */
+declare function componentPropClasses(config: Config, path: string, state?: Record<string, unknown>): Record<string, string[]>;
+/**
+ * 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.
+ */
+declare function layerCompositeProps(config: Config, path: string, state?: Record<string, unknown>): Record<string, Record<string, unknown>>;
+/**
+ * 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.
+ */
+declare function styleRuleMotionClasses(config: Config, path: string, state?: Record<string, unknown>): Record<string, string[]>;
+/**
+ * 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.
+ */
+declare function stylePropClassBase(config: Config, path: string): string;
+/**
+ * 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.
+ */
+declare function stylePropClassName(config: Config, path: string, leaf: string): string;
+/** What a prop bag amounts to once styling is taken out of it. */
+interface SplitStyleProps {
+  /** The classes the bag's style props produce, space-joined. */
+  readonly className: string;
+  /** The props that aren't styling — the element's own (`id`, `onClick`, a data attribute). */
+  readonly rest: Record<string, unknown>;
+}
+/**
+ * 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.
+ */
+declare function splitStyleProps({
+  config,
+  bag,
+  through
+}: {
+  readonly config: Config;
+  readonly bag: Record<string, unknown>;
+  /** The definitions this bag's keys resolve against, in precedence order — see
+   *  {@link stylePropertyPathFor}. `<VStack gap="4">` wears `uds-gap-y-4`. Empty for a bag with no
+   *  owning component, where a key names its own property. */
+  readonly through?: readonly (string | undefined)[];
+}): SplitStyleProps;
+/**
+ * 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.
+ */
+declare function stylePropClasses(config: Config, path: string): Map<string, string>;
+/**
+ * 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.
+ */
+declare function modifierUtilitiesUsed(config: Config): Set<string>;
+//#endregion
+export { ComponentRuleClass, SplitStyleProps, componentClassBase, componentCompositeClasses, componentLayerClass, componentMotionClasses, componentPropClasses, componentRuleClasses, forceModeAttribute, forceModeAttributeOf, forceModeProp, forceModePropGroup, forceModePropValue, forceModeProps, forceStateAttribute, isForceModeProp, kebabComponent, layerCompositeProps, modifierUtilitiesUsed, motionClassName, ruleCondition, splitStyleProps, stylePropClassBase, stylePropClassName, stylePropClasses, styleRuleMotionClasses };