@yahoo/uds-create-config 5.38.0 → 5.39.0

package/dist/configs/system.js

@@ -72,6 +72,7 @@ import { linkExcludeOpMigration } from "../migrations/20261013182150_link_exclud
 import { fontFacesMigration } from "../migrations/20261013201548_font_faces.js";
 import { maxAndMinMigration } from "../migrations/20261015171036_max_and_min.js";
 import { componentStyleSetMigration } from "../migrations/20261015192819_component_style_set.js";
+import { componentElementSwapMigration } from "../migrations/20261015202345_component_element_swap.js";
 const System = defineConfig({
 	name: WEB_CONFIG_NAME,
 	description: "A design system: the values, primitives and compositions an app is built from. A ref is written `{ \"__ref\": \"<kind>:<path>\" }`, so a token is `{ \"__ref\": \"token:<group>/<name>\" }` and a token group is `{ \"__ref\": \"token:<group>\" }`. Build it in this order. Tokens first, in groups by purpose (colors, spacing, radii, type sizes), since everything else names them. Then style properties, each with `values` holding one ref to the token group whose members it accepts (`{ \"__ref\": \"token:color\" }`), so a prop takes token names rather than raw CSS; add a string keyword only for a value no token holds. A style rule's bag holds a prop's values (`\"padding\": \"4\"`, `\"bg\": \"brand\"`), never raw CSS. Then a few primitive components, one layer each, whose props are style properties (a box for layout and surface, a text for type, a pressable for interaction). Then every other component composed from those primitives: its layers name a primitive or an element, its anatomy places them (a node renders a layer, a tag or `Slot` where a slot prop's content lands; `children` is the edge list; `visible` is `{ \"$state\": \"<prop>\" }`; a prop shown in a nested layer is a `forward` route, and `$state` never sits in a node's props), and its style rules set style-property values per layer, keyed by prop values when a variant changes them. Modes (a dark mode is `{ type: \"selector\", value: \".dark\" }`) change token values through a token's `overrides`, so a component never restyles for a mode; modifiers (hover, focus, disabled) name a state, and a style rule applies under one as a `_hover` block inside a layer bag. Composites bundle style values that recur. Last, register canvas roles: the canvas draws with them, one entity per tool (`frame` for the layout primitive, `text` for the text primitive, `image`) whose entries name the components that tool inserts, and a tool whose role is unregistered is disabled. Give each component a `preview` entry under `*` so it shows content, and never write a CSS property name where a style-property name belongs.",
@@ -155,5 +156,6 @@ if (!registeredSchemaMigrations().has(20261013182150)) registerSchemaMigrations(
 if (!registeredSchemaMigrations().has(20261013201548)) registerSchemaMigrations(fontFacesMigration);
 if (!registeredSchemaMigrations().has(20261015171036)) registerSchemaMigrations(maxAndMinMigration);
 if (!registeredSchemaMigrations().has(20261015192819)) registerSchemaMigrations(componentStyleSetMigration);
+if (!registeredSchemaMigrations().has(20261015202345)) registerSchemaMigrations(componentElementSwapMigration);
 //#endregion
 export { System };

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

@@ -822,6 +822,17 @@ declare const ComponentEntity: EntityClass<z.ZodObject<{
       }, z.core.$strip>;
     }, z.core.$strip>;
   };
+  readonly 'element-swap': {
+    readonly input: z.ZodObject<{
+      path: z.ZodType<string, string | undefined, z.core.$ZodTypeInternals<string, string | undefined>>;
+      key: z.ZodString;
+      data: z.ZodObject<{
+        element: z.ZodObject<{
+          __ref: z.ZodString;
+        }, z.core.$strip>;
+      }, z.core.$strip>;
+    }, z.core.$strip>;
+  };
   readonly validate: {
     readonly input: z.ZodObject<{
       path: z.ZodType<string, string | undefined, z.core.$ZodTypeInternals<string, string | undefined>>;

package/dist/entities/system/Component.js

@@ -16,7 +16,7 @@ import { bindPreviewGlyphs, glyphMemberRefIn } from "./glyph-identity.js";
 import { Style, addBagKeyIssues, anatomyPropValue, bagNameEdges, bagRewriteName, bindBagTokens, collectBag, isPlainRecord, openBag, styleValue } from "./style-bag.js";
 import { storedPreview } from "../../framework/preview-store.js";
 import { glyphPropsOf, glyphPropsOfBody, propOwner, propValueDomain, refListOf, resolveComponentProps, stylePropNumberUnit, stylePropValueLeaves, validateComponentProps } from "../../framework/projections.js";
-import { carriesContent, intoName, isValueSlot, renderBoundProp, routedPropIn, routesContent } from "../../framework/prop-surface.js";
+import { carriesContent, intoName, isValueSlot, renderBoundProp, routedPropIn, routesContent, surfaceProps } from "../../framework/prop-surface.js";
 import { slotAnatomyPropOf, slotTargetsOf, withoutTruthyTerm } from "../../framework/render-spec.js";
 import { listSlots, namedSlots, slotHostedBy, slotOf, slotsFor } from "../../spec/slot.js";
 import { cellAt } from "../../spec/cell.js";
@@ -1407,6 +1407,20 @@ function anatomySubtreeContains(anatomy, ancestor, key) {
 	}
 	return false;
 }
+/** Whether `from`, or a component its layers render, is `to`. */
+function componentReaches({ config, from, to }) {
+	const seen = /* @__PURE__ */ new Set();
+	const queue = [from];
+	while (queue.length > 0) {
+		const current = queue.shift();
+		if (current === void 0 || seen.has(current)) continue;
+		if (current === to) return true;
+		seen.add(current);
+		const layers = (config.resolve("component", current)?.toJSON())?.layers;
+		for (const layer of Object.values(layers ?? {})) if (isRef(layer) && kindOf(layer) === "component") queue.push(pathOf(layer.__ref));
+	}
+	return false;
+}
 /** The component body as `element-move` reads it — re-resolved between writes so each step builds
 *  on the previous one's result rather than the pre-move snapshot. */
 function resolveMoveBody(config, path) {
@@ -2646,6 +2660,93 @@ subtree: z.boolean().default(true) }).optional()
 				}))]);
 			}
 		},
+		/**
+		* Swap a layer for another component, the way `node/element-swap` swaps an element on a design
+		* file: the layer renders the new component and keeps its place and the styles the new one takes.
+		* Its children stay when the new component takes child nodes. When it takes none they go, except
+		* a `Slot` node, which is where a slot prop's content lands and which the component still
+		* declares.
+		*
+		* The removals run first, so the style rules they empty are gone before the layer's own bags are
+		* pruned. A bag keeps the props the new component takes, so a `color` carries over to another
+		* text component and nothing the new one can't apply is left stored.
+		*/
+		"element-swap": {
+			input: z.object({
+				path: pathInput("component"),
+				/** The layer to swap. */
+				key: z.string(),
+				data: z.object({ 
+				/** The component the layer renders instead. */
+element: refSchema })
+			}),
+			readOnly: false,
+			label: "Swap element",
+			description: "Swap a component's layer for another component: the layer renders the new one and keeps the styles the new one takes. Its children stay when the new component takes child nodes; otherwise they go with their layers and styles, and a `Slot` node stays.",
+			scope: "item",
+			approval: "destructive",
+			title: (entity) => `Swap ${entity} element`,
+			handler: (input, config) => {
+				const path = String(input.path);
+				const key = String(input.key);
+				const element = input.data.element;
+				const body = resolveMoveBody(config, path);
+				if (!body?.layers || !(key in body.layers)) reject("NOT_FOUND", `"${path}" has no layer "${key}" to swap.`);
+				if (kindOf(element) !== "component") rejectData("A layer swaps for a component.", ["element"]);
+				const target = pathOf(element.__ref);
+				if (!config.resolve("component", target)) reject("NOT_FOUND", `There is no component "${target}" to swap to.`);
+				if (componentReaches({
+					config,
+					from: target,
+					to: path
+				})) rejectData(`"${target}" renders "${path}", so swapping it in would make "${path}" render itself.`, ["element"]);
+				const anatomy = body?.anatomy ?? {};
+				const keepsChildren = childrenPolicy(config, target) === "nodes";
+				let next = config.run((keepsChildren ? [] : anatomy[key]?.children ?? []).filter((child) => anatomy[child]?.element !== "Slot").map((child) => ({
+					kind: "component",
+					operation: "element-delete",
+					path,
+					key: child
+				})));
+				const taken = new Set(surfaceProps(next, target).map((prop) => prop.name));
+				const styles = (next.resolve("component", path)?.toJSON())?.styles;
+				for (const [condition, rule] of Object.entries(styles ?? {})) {
+					const bag = rule.layers?.[key];
+					if (!bag) continue;
+					const dropped = Object.keys(bag).filter((prop) => !taken.has(prop));
+					if (dropped.length === 0) continue;
+					const kept = Object.fromEntries(Object.entries(bag).filter(([prop]) => taken.has(prop)));
+					next = ruleStylesNothing({
+						...rule,
+						layers: {
+							...rule.layers,
+							[key]: kept
+						}
+					}) ? next.apply({
+						kind: "component",
+						operation: "sub-delete",
+						path,
+						field: "styles",
+						key: condition
+					}) : next.apply({
+						kind: "component",
+						operation: "sub-update",
+						path,
+						field: "styles",
+						key: condition,
+						data: Object.fromEntries(dropped.map((prop) => [`layers.${key}.${prop}`, null]))
+					});
+				}
+				return next.apply({
+					kind: "component",
+					operation: "sub-upsert",
+					path,
+					field: "layers",
+					key,
+					data: element
+				});
+			}
+		},
 		validate: {
 			input: z.object({
 				path: pathInput("component"),

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 = 20261015192819;
+declare const SERIALIZED_CONFIG_VERSION = 20261015202345;
 interface SerializedConfig {
   /** See {@link SERIALIZED_CONFIG_VERSION}. Always written; a stored artifact may lack it. */
   readonly version: number;

package/dist/framework/Config.js

@@ -5862,7 +5862,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 > 20261015192819) throw new SchemaVersionTooNew(claimed);
+		if (claimed > 20261015202345) 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.`);
 		const leftover = wire.options;

package/dist/framework/schema-version.d.ts

@@ -15,7 +15,7 @@ import { Patch, SerializedConfig } from "./Config.js";
  * sets this constant to its own older timestamp; the merge ref then carries a registered migration
  * newer than the constant, and the assertion fails until the author re-mints.
  */
-declare const CURRENT_SCHEMA_VERSION = 20261015192819;
+declare const CURRENT_SCHEMA_VERSION = 20261015202345;
 /** What the walkers need to see of an envelope — loose on purpose, so a typed `SerializedConfig`
  *  and a raw old-shape record both flow in without casts. */
 interface VersionStamped {

package/dist/framework/schema-version.js

@@ -13,7 +13,7 @@ import { ConfigFormatError } from "./rejection.js";
 * sets this constant to its own older timestamp; the merge ref then carries a registered migration
 * newer than the constant, and the assertion fails until the author re-mints.
 */
-const CURRENT_SCHEMA_VERSION = 20261015192819;
+const CURRENT_SCHEMA_VERSION = 20261015202345;
 /** The mint that moved `options` into the `settings` kind — restated here, rather than imported
 *  from the migration that owns it, because that migration imports this module. */
 const SETTINGS_AS_KIND_VERSION = 20260908171448;
@@ -45,7 +45,7 @@ function registerSchemaMigrations(...migrations) {
 	for (const migration of migrations) {
 		if (migration.version !== 1 && !isMintTimestamp(migration.version)) throw new Error(`Schema migration version ${migration.version} is not a mint timestamp — mint one with \`date +%Y%m%d%H%M%S\`, like a supabase migration.`);
 		if (REGISTERED.has(migration.version)) throw new Error(`A schema migration at version ${migration.version} is already registered.`);
-		if (migration.version > 20261015192819) throw new Error(`Schema migration ${migration.version} is newer than CURRENT_SCHEMA_VERSION (${CURRENT_SCHEMA_VERSION}) — a stale branch merged, or the mint forgot to bump the constant. Re-mint: set CURRENT_SCHEMA_VERSION to the newest migration version.`);
+		if (migration.version > 20261015202345) throw new Error(`Schema migration ${migration.version} is newer than CURRENT_SCHEMA_VERSION (${CURRENT_SCHEMA_VERSION}) — a stale branch merged, or the mint forgot to bump the constant. Re-mint: set CURRENT_SCHEMA_VERSION to the newest migration version.`);
 		REGISTERED.set(migration.version, migration);
 	}
 }
@@ -102,7 +102,7 @@ function pendingFor(version, target, options) {
 * Already-current input passes through untouched — same reference, so hot paths pay nothing.
 */
 function upgradeSerializedConfig(json, options) {
-	const target = options?.target ?? 20261015192819;
+	const target = options?.target ?? 20261015202345;
 	const version = detectedWireVersion(json);
 	if (version > target) throw new SchemaVersionTooNew(version, target);
 	const raw = json;
@@ -160,7 +160,7 @@ function upgradedSources(json, options) {
 * meaning under the current schema and replay skips it — reported by the caller, not swallowed here.
 */
 function upgradePatch(patch, writtenAt, options) {
-	const target = options?.target ?? 20261015192819;
+	const target = options?.target ?? 20261015202345;
 	if (writtenAt > target) throw new SchemaVersionTooNew(writtenAt, target);
 	let current = patch;
 	for (const migration of pendingFor(writtenAt, target, options)) {
@@ -179,7 +179,7 @@ function upgradePatch(patch, writtenAt, options) {
 * stamp would cause.
 */
 function upgradeDraftEntries(draft, options) {
-	const target = options?.target ?? 20261015192819;
+	const target = options?.target ?? 20261015202345;
 	const entries = [];
 	const held = [];
 	const retired = [];

package/dist/migrations/20261015202345_component_element_swap.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Additions only, so the envelope passes through as it is:
+ *
+ * - `component/element-swap` swaps a layer for another component, keeping its children when the
+ *   new component takes child nodes and the styles it takes.
+ *
+ * Deletable once no reader older than this version is in use: identity hops cost nothing to keep.
+ */
+import type { SchemaMigration } from '../framework/schema-version';
+export declare const COMPONENT_ELEMENT_SWAP_VERSION = 20261015202345;
+export declare const componentElementSwapMigration: SchemaMigration;

package/dist/migrations/20261015202345_component_element_swap.js

@@ -0,0 +1,10 @@
+//#region src/migrations/20261015202345_component_element_swap.ts
+const COMPONENT_ELEMENT_SWAP_VERSION = 20261015202345;
+const componentElementSwapMigration = {
+	version: COMPONENT_ELEMENT_SWAP_VERSION,
+	up(json) {
+		return json;
+	}
+};
+//#endregion
+export { COMPONENT_ELEMENT_SWAP_VERSION, componentElementSwapMigration };