@yahoo/uds-create-config 5.65.0 → 5.66.1

package/dist/configs/system.js

@@ -33,6 +33,7 @@ import { conditionalDefaultsMigration } from "../migrations/20261023152030_condi
 import { timingValueMigration } from "../migrations/20261026125912_timing_value.js";
 import { variantValuesListWithBodiesMigration } from "../migrations/20261027184442_variant_values_list_with_bodies.js";
 import { lintIgnoreMigration } from "../migrations/20261027205147_lint_ignore.js";
+import { componentMapPropsMigration } from "../migrations/20261030134149_component_map_props.js";
 import { CanvasRole } from "../entities/system/CanvasRole.js";
 import { GlobalStyle } from "../entities/system/GlobalStyle.js";
 import { Guidance } from "../entities/system/Guidance.js";
@@ -199,5 +200,6 @@ if (!registeredSchemaMigrations().has(20261023152030)) registerSchemaMigrations(
 if (!registeredSchemaMigrations().has(20261026125912)) registerSchemaMigrations(timingValueMigration);
 if (!registeredSchemaMigrations().has(20261027184442)) registerSchemaMigrations(variantValuesListWithBodiesMigration);
 if (!registeredSchemaMigrations().has(20261027205147)) registerSchemaMigrations(lintIgnoreMigration);
+if (!registeredSchemaMigrations().has(20261030134149)) registerSchemaMigrations(componentMapPropsMigration);
 //#endregion
 export { System };

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

@@ -869,6 +869,31 @@ declare const ComponentEntity: EntityClass<z.ZodObject<{
       }, z.core.$strip>;
     }, z.core.$strip>;
   };
+  readonly 'map-props': {
+    readonly input: z.ZodObject<{
+      path: z.ZodType<string, string | undefined, z.core.$ZodTypeInternals<string, string | undefined>>;
+      data: z.ZodObject<{
+        rules: z.ZodArray<z.ZodObject<{
+          when: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
+          set: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+          unset: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        }, z.core.$strip>>;
+      }, z.core.$strip>;
+    }, z.core.$strip>;
+  };
+  readonly 'map-props-plan': {
+    readonly input: z.ZodObject<{
+      path: z.ZodType<string, string | undefined, z.core.$ZodTypeInternals<string, string | undefined>>;
+      data: z.ZodObject<{
+        rules: z.ZodArray<z.ZodObject<{
+          when: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
+          set: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+          unset: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        }, z.core.$strip>>;
+        instances: z.ZodDefault<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+      }, z.core.$strip>;
+    }, z.core.$strip>;
+  };
 }, {
   /**
    * What each layer can forward, for the layers that render a component with props: every prop its

package/dist/entities/system/Component.js

@@ -24,6 +24,7 @@ import { slotAnatomyPropOf, slotTargetsOf, withoutTruthyTerm } from "../../frame
 import { listSlots, namedSlots, slotHostedBy, slotOf, slotsFor } from "../../spec/slot.js";
 import { cellAt } from "../../spec/cell.js";
 import { instanceAt } from "../../spec/instance.js";
+import { mapComponentProps, propMappingErrors, propMappingRulesSchema } from "../../spec/prop-mapping.js";
 import { forwardOptions, forwardsWrite } from "./component-forwards.js";
 import { assertComponentSourceInput } from "./component-source-fields.js";
 import { checkStyleSet, styleSetEdits } from "./component-style-set.js";
@@ -2924,6 +2925,55 @@ element: refSchema })
 				data: { props: exampleProps(config, path) }
 			}),
 			handler: (input, config) => validateComponentProps(config, String(input.path), input.data.props ?? {})
+		},
+		"map-props": {
+			input: z.object({
+				path: pathInput("component"),
+				data: z.object({ rules: propMappingRulesSchema })
+			}),
+			readOnly: false,
+			approval: "reference-change",
+			label: "Map props",
+			description: "Move a component's instances onto its props as they are now, after its API changed: `variant: 'primary'` becomes `color: 'brand', prominence: 'solid'`. It changes nothing in the config. Where it runs decides what it moves: in Create, the instances in the branch's design files; in a checkout (`uds config edit`, the local UDS MCP), the call sites in the project's source. Refuses a rule that writes a prop or value the component doesn't take. Run it with `plan: true` first: the plan says what it would move, and writes nothing.",
+			scope: "item",
+			title: (entity) => `Map ${entity} props`,
+			example: ({ config, path }) => {
+				const { data, ...rest } = exampleMapping(config, path);
+				return {
+					...rest,
+					data: { rules: data.rules }
+				};
+			},
+			handler: (input, config) => {
+				const errors = propMappingErrors(config, {
+					component: String(input.path),
+					rules: input.data.rules
+				});
+				if (errors.length > 0) rejectData(errors.join(" "));
+				return config;
+			}
+		},
+		"map-props-plan": {
+			input: z.object({
+				path: pathInput("component"),
+				data: z.object({
+					rules: propMappingRulesSchema,
+					instances: z.array(z.record(z.string(), z.unknown())).default([]).describe("Instances' props as they are stored or written: each comes back with the rules applied.")
+				})
+			}),
+			readOnly: true,
+			label: "Plan a props mapping",
+			description: "Try a mapping on some instances' props before `map-props` applies it: refuses a rule that writes a prop or value the component doesn't take, and returns each given instance's props with the rules applied. Writes nothing.",
+			scope: "item",
+			title: (entity) => `Plan mapping ${entity} props`,
+			example: ({ config, path }) => exampleMapping(config, path),
+			handler: (input, config) => {
+				const data = input.data;
+				return mapComponentProps(config, {
+					component: String(input.path),
+					rules: data.rules
+				}, data.instances ?? []);
+			}
 		}
 	},
 	invariants: (config) => [
@@ -3072,5 +3122,35 @@ function exampleProps(config, componentPath) {
 	}
 	return {};
 }
+/** A runnable `map-props-plan` example: an instance holding the first variant prop's first value, and
+*  a rule moving it onto the prop's second value (or the same one, for a prop with a single value).
+*  A component with no variant gets the other common case, dropping a prop it no longer has.
+*  `map-props` takes the same rules, without the instances. */
+function exampleMapping(config, componentPath) {
+	const instance = exampleProps(config, componentPath);
+	const [name, value] = Object.entries(instance)[0] ?? [];
+	if (name === void 0 || value === void 0) return {
+		path: componentPath,
+		data: {
+			rules: [{
+				when: { variant: "primary" },
+				unset: ["variant"]
+			}],
+			instances: [{ variant: "primary" }]
+		}
+	};
+	const decl = (config.resolve("component", componentPath)?.toJSON())?.props?.[name];
+	const next = (decl ? propValueDomain(config, decl)?.leaves ?? [] : []).find((leaf) => leaf !== value) ?? value;
+	return {
+		path: componentPath,
+		data: {
+			rules: [{
+				when: { [name]: value },
+				set: { [name]: next }
+			}],
+			instances: [instance]
+		}
+	};
+}
 //#endregion
 export { Component, SLOT_CODE_FORMS, blankComponentBody, canonicalWhen, forwardedNames, layerRef, ownValues, ownsItsValues, storedStyleRules, valueRef };

package/dist/framework/Config.d.ts

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

package/dist/framework/Config.js

@@ -10,8 +10,8 @@ import { borrowedSlug, classifyOverlay, uniteEntries } from "./source-integrity.
 import { kindBorrowable, titleCase } from "./registry.js";
 import { isGroupBody } from "./utils/group.js";
 import { authoredBag, cssVar, declaresCssVariable, pinBodyStyleNumbers, stylePropNumberUnit } from "./projections.js";
-import { isAuthoringPhantom, phantomsIn } from "./utils/authoring-phantom.js";
 import { addressOf, editOp, inputOf, opVerb } from "./config-op.js";
+import { isAuthoringPhantom, phantomsIn } from "./utils/authoring-phantom.js";
 import { configSchemas } from "./config-ops.js";
 import { isAuthored } from "./authoring.js";
 import { Entity } from "./Entity.js";
@@ -6362,7 +6362,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 > 20261027205147) throw new SchemaVersionTooNew(claimed);
+		if (claimed > 20261030134149) 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 = 20261027205147;
+declare const CURRENT_SCHEMA_VERSION = 20261030134149;
 /** 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 = 20261027205147;
+const CURRENT_SCHEMA_VERSION = 20261030134149;
 /** 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 > 20261027205147) 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 > 20261030134149) 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 ?? 20261027205147;
+	const target = options?.target ?? 20261030134149;
 	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 ?? 20261027205147;
+	const target = options?.target ?? 20261030134149;
 	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 ?? 20261027205147;
+	const target = options?.target ?? 20261030134149;
 	const entries = [];
 	const held = [];
 	const retired = [];

package/dist/index.js

@@ -60,6 +60,7 @@ import { arbitraryClassName, arbitraryNeedsClass, classLeaf, classSelector, clea
 import { ANATOMY_MARKER, MOTION_FACTORY, anatomyElementComponent, anatomyTextProp, boundElementType, componentSpec, deriveSpec, entryKeyOf, expandComponent, expandSpec, instanceSpec, layerTextProp, liveStateProps, previewSpec, propInto, propsIntoLayer, readStatePointer, resolveValue, resolveVisibility, routeOf, routesOf, slotTargetsOf, specWithResolvedVisibility, statePointerProp, valueForwardsOf, visibilityStateProps, visibilityTerms, withoutTruthyTerm, wrappedElementKey } from "./framework/render-spec.js";
 import { canvasCellAt, canvasDefaultCoordinate, cellAxes } from "./spec/cell.js";
 import { instanceHolding } from "./spec/instance.js";
+import { addressOf, editOp, inputOf, opOf, opVerb } from "./framework/config-op.js";
 import { componentSourceDerivedFields } from "./entities/system/component-source-fields.js";
 import { styleSetEdits } from "./entities/system/component-style-set.js";
 import { convertLinkedTokenValue, prepareLinkedTokenBody } from "./entities/system/linked-token-values.js";
@@ -73,7 +74,6 @@ import { glyphExportNames, glyphType, iconCategories, iconLibraries, iconLibrary
 import { glyphSourcesOf, iconResolver, nameIconsInTree } from "./capture/icon-resolver.js";
 import { PLACED_NODE_KEY, specToNodePatches } from "./entities/canvas/node-patches.js";
 import { Device } from "./entities/system/Device.js";
-import { addressOf, editOp, inputOf, opOf, opVerb } from "./framework/config-op.js";
 import { renderSignature, signatureOf } from "./framework/signature.js";
 import { authoringSignatures } from "./framework/config-ops.js";
 import { defineDerivedEntity } from "./framework/defineDerivedEntity.js";

package/dist/migrations/20261030134149_component_map_props.d.ts

@@ -0,0 +1,7 @@
+/** `component/map-props` is a new op, with `component/map-props-plan` beside it: a mapping of a
+ * component's old props onto its new ones, applied to the documents of whichever host runs it. It
+ * writes no patch, so no stored config or draft row carries it, and this is an identity hop. Retire
+ * it only when no supported artifact predates this schema. */
+import type { SchemaMigration } from '../framework/schema-version';
+export declare const COMPONENT_MAP_PROPS_VERSION = 20261030134149;
+export declare const componentMapPropsMigration: SchemaMigration;

package/dist/migrations/20261030134149_component_map_props.js

@@ -0,0 +1,8 @@
+//#region src/migrations/20261030134149_component_map_props.ts
+const COMPONENT_MAP_PROPS_VERSION = 20261030134149;
+const componentMapPropsMigration = {
+	version: COMPONENT_MAP_PROPS_VERSION,
+	up: (json) => json
+};
+//#endregion
+export { COMPONENT_MAP_PROPS_VERSION, componentMapPropsMigration };

package/dist/spec/index.d.ts

@@ -7,7 +7,7 @@ import { AcceptsChildNodes, ChildNodesClassification, ClassifyChildNodes, buildA
 import { CollapseTextLabelsResult, CollapsedTextLabel, collapseWrappedTextLabels } from "./collapse-text-labels.js";
 import { GlyphJsxForm, GlyphNodeResolver, glyphJsxForm, glyphMemberOf, jsxIdentifier, parseGlyphType } from "./glyph-jsx.js";
 import { JsxToSpecOptions, UNRESOLVED, hasUnresolvedProps, jsxToSpec, stripUnresolvedProps } from "./jsxToSpec.js";
-import { MatchedValue, PropMapping, PropMappingConflict, PropMappingResult, PropMappingRule, applyPropMapping, propMappingErrors } from "./prop-mapping.js";
+import { MappedInstance, MappedProps, MatchedValue, PropMapping, PropMappingConflict, PropMappingResult, PropMappingRule, applyPropMapping, mapComponentProps, onlyMapsProps, propMappingErrors, propMappingRuleSchema, propMappingRulesSchema, propMappingsIn } from "./prop-mapping.js";
 import { SpecToJsxOptions, SpecToJsxResult, specToJsx } from "./specToJsx.js";
 
 //#region src/spec/index.d.ts
@@ -29,4 +29,4 @@ import { SpecToJsxOptions, SpecToJsxResult, specToJsx } from "./specToJsx.js";
  *  element, without changing the rendered layer hierarchy. */
 declare const SYNTHETIC_TEXT_SLOT_PROP = "data-uds-synthetic-text-slot";
 //#endregion
-export { type AcceptsChildNodes, type Cell, type CellSlot, type ChildNodesClassification, type ClassifyChildNodes, type CollapseTextLabelsResult, type CollapsedTextLabel, type DocumentRename, type GlyphJsxForm, type GlyphNodeResolver, type GraftableElement, type GraftableSpec, type JsxToSpecOptions, type MatchedValue, type PreviewElement, type PreviewRef, type PreviewSpecNode, type PreviewValue, type PropMapping, type PropMappingConflict, type PropMappingResult, type PropMappingRule, type RewritableElement, type RewritableSpec, SYNTHETIC_TEXT_SLOT_PROP, type Slot, type SlotCell, type SpecRewrite, type SpecToJsxOptions, type SpecToJsxResult, UNRESOLVED, applyForcedModifiers, applyPropMapping, buildAcceptsChildNodes, buildClassifyChildNodes, collapseWrappedTextLabels, collectForcedModifierProps, composeRenames, documentRenamesFromPatches, documentRenamesFromSource, glyphJsxForm, glyphMemberOf, graftPreviewElements, graftSlotContent, hasPreviewElementDeep, hasUnresolvedProps, isComponentRef, isPreviewElement, isPreviewRef, jsxIdentifier, jsxToSpec, parseGlyphType, previewElementNodes, previewElementType, propMappingErrors, rewriteSpecRefs, specToJsx, stripInjectedSlots, stripUnresolvedProps, styleNumberReadingRenames, withContainerChildSlots, withEmptyNodeSlots, withRenderSlots };
+export { type AcceptsChildNodes, type Cell, type CellSlot, type ChildNodesClassification, type ClassifyChildNodes, type CollapseTextLabelsResult, type CollapsedTextLabel, type DocumentRename, type GlyphJsxForm, type GlyphNodeResolver, type GraftableElement, type GraftableSpec, type JsxToSpecOptions, type MappedInstance, type MappedProps, type MatchedValue, type PreviewElement, type PreviewRef, type PreviewSpecNode, type PreviewValue, type PropMapping, type PropMappingConflict, type PropMappingResult, type PropMappingRule, type RewritableElement, type RewritableSpec, SYNTHETIC_TEXT_SLOT_PROP, type Slot, type SlotCell, type SpecRewrite, type SpecToJsxOptions, type SpecToJsxResult, UNRESOLVED, applyForcedModifiers, applyPropMapping, buildAcceptsChildNodes, buildClassifyChildNodes, collapseWrappedTextLabels, collectForcedModifierProps, composeRenames, documentRenamesFromPatches, documentRenamesFromSource, glyphJsxForm, glyphMemberOf, graftPreviewElements, graftSlotContent, hasPreviewElementDeep, hasUnresolvedProps, isComponentRef, isPreviewElement, isPreviewRef, jsxIdentifier, jsxToSpec, mapComponentProps, onlyMapsProps, parseGlyphType, previewElementNodes, previewElementType, propMappingErrors, propMappingRuleSchema, propMappingRulesSchema, propMappingsIn, rewriteSpecRefs, specToJsx, stripInjectedSlots, stripUnresolvedProps, styleNumberReadingRenames, withContainerChildSlots, withEmptyNodeSlots, withRenderSlots };

package/dist/spec/index.js

@@ -1,11 +1,11 @@
 import { graftPreviewElements, graftSlotContent, hasPreviewElementDeep, isComponentRef, isPreviewElement, isPreviewRef, previewElementNodes, previewElementType } from "./preview-elements.js";
+import { composeRenames, documentRenamesFromPatches, documentRenamesFromSource, rewriteSpecRefs, styleNumberReadingRenames } from "./rewrite-refs.js";
+import { applyPropMapping, mapComponentProps, onlyMapsProps, propMappingErrors, propMappingRuleSchema, propMappingRulesSchema, propMappingsIn } from "./prop-mapping.js";
 import { glyphJsxForm, glyphMemberOf, jsxIdentifier, parseGlyphType } from "./glyph-jsx.js";
 import { applyForcedModifiers, collectForcedModifierProps } from "./apply-forced-modifiers.js";
 import { collapseWrappedTextLabels } from "./collapse-text-labels.js";
 import { buildAcceptsChildNodes, buildClassifyChildNodes, stripInjectedSlots, withContainerChildSlots, withEmptyNodeSlots, withRenderSlots } from "./empty-node-slots.js";
 import { UNRESOLVED, hasUnresolvedProps, jsxToSpec, stripUnresolvedProps } from "./jsxToSpec.js";
-import { composeRenames, documentRenamesFromPatches, documentRenamesFromSource, rewriteSpecRefs, styleNumberReadingRenames } from "./rewrite-refs.js";
-import { applyPropMapping, propMappingErrors } from "./prop-mapping.js";
 import { specToJsx } from "./specToJsx.js";
 //#region src/spec/index.ts
 /**
@@ -26,4 +26,4 @@ import { specToJsx } from "./specToJsx.js";
 *  element, without changing the rendered layer hierarchy. */
 const SYNTHETIC_TEXT_SLOT_PROP = "data-uds-synthetic-text-slot";
 //#endregion
-export { SYNTHETIC_TEXT_SLOT_PROP, UNRESOLVED, applyForcedModifiers, applyPropMapping, buildAcceptsChildNodes, buildClassifyChildNodes, collapseWrappedTextLabels, collectForcedModifierProps, composeRenames, documentRenamesFromPatches, documentRenamesFromSource, glyphJsxForm, glyphMemberOf, graftPreviewElements, graftSlotContent, hasPreviewElementDeep, hasUnresolvedProps, isComponentRef, isPreviewElement, isPreviewRef, jsxIdentifier, jsxToSpec, parseGlyphType, previewElementNodes, previewElementType, propMappingErrors, rewriteSpecRefs, specToJsx, stripInjectedSlots, stripUnresolvedProps, styleNumberReadingRenames, withContainerChildSlots, withEmptyNodeSlots, withRenderSlots };
+export { SYNTHETIC_TEXT_SLOT_PROP, UNRESOLVED, applyForcedModifiers, applyPropMapping, buildAcceptsChildNodes, buildClassifyChildNodes, collapseWrappedTextLabels, collectForcedModifierProps, composeRenames, documentRenamesFromPatches, documentRenamesFromSource, glyphJsxForm, glyphMemberOf, graftPreviewElements, graftSlotContent, hasPreviewElementDeep, hasUnresolvedProps, isComponentRef, isPreviewElement, isPreviewRef, jsxIdentifier, jsxToSpec, mapComponentProps, onlyMapsProps, parseGlyphType, previewElementNodes, previewElementType, propMappingErrors, propMappingRuleSchema, propMappingRulesSchema, propMappingsIn, rewriteSpecRefs, specToJsx, stripInjectedSlots, stripUnresolvedProps, styleNumberReadingRenames, withContainerChildSlots, withEmptyNodeSlots, withRenderSlots };

package/dist/spec/prop-mapping.d.ts

@@ -1,5 +1,7 @@
+import { ConfigEdit } from "../framework/config-op.js";
 import { Config } from "../framework/Config.js";
 import { RewritableSpec } from "./rewrite-refs.js";
+import { z } from "zod";
 
 //#region src/spec/prop-mapping.d.ts
 /** A stored value a rule can match: what a design file holds for a variant, string or flag. */
@@ -17,6 +19,31 @@ interface PropMapping {
   readonly component: string;
   readonly rules: readonly PropMappingRule[];
 }
+/** A rule as a tool takes it: the shape every surface that applies a mapping parses its input with. */
+declare const propMappingRuleSchema: z.ZodObject<{
+  when: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
+  set: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+  unset: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+/** The rules of a mapping, as a tool takes them. */
+declare const propMappingRulesSchema: z.ZodArray<z.ZodObject<{
+  when: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
+  set: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+  unset: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>>;
+/**
+ * The mappings a batch of edits carries, in order: each `component/map-props` op as the mapping it
+ * applies. The op changes nothing in the config, so the host that ran the batch applies these to the
+ * documents it holds once the batch lands: Create to a branch's design files, a checkout to its call
+ * sites. An op whose rules don't parse is left out; running the batch refused it already.
+ */
+declare function propMappingsIn(edits: readonly ConfigEdit[]): PropMapping[];
+/**
+ * Whether a batch is mappings alone: every edit a `component/map-props` op. Such a batch changes
+ * nothing in the config, so a read-only branch (`main`, a published version) still runs it: its
+ * design files take edits, and those are all it moves.
+ */
+declare function onlyMapsProps(edits: readonly ConfigEdit[]): boolean;
 /** A bag two matching rules wrote different values into, left as it was. */
 interface PropMappingConflict {
   readonly element: string;
@@ -45,5 +72,26 @@ declare function propMappingErrors(config: Config, mapping: PropMapping): string
  * first: this applies what it's given.
  */
 declare function applyPropMapping(config: Config, spec: RewritableSpec, mapping: PropMapping): PropMappingResult;
+/** One instance's props with a mapping tried on it. */
+interface MappedInstance {
+  readonly props: Record<string, unknown>;
+  readonly changed: boolean;
+  /** The props two matching rules wrote different values to, which leave the instance as it was. */
+  readonly conflicts: readonly string[];
+}
+type MappedProps = {
+  readonly ok: false;
+  readonly errors: readonly string[];
+} | {
+  readonly ok: true;
+  readonly instances: readonly MappedInstance[];
+};
+/**
+ * A mapping tried on some instances' props, writing nothing: the `component/map-props` op. Refused,
+ * with each reason, when the component can't take what it writes. Each bag is mapped as a design
+ * file's instance is, modifier blocks and layer overrides included, so what it returns is what
+ * applying the mapping to a document or a call site would store.
+ */
+declare function mapComponentProps(config: Config, mapping: PropMapping, instances: readonly Record<string, unknown>[]): MappedProps;
 //#endregion
-export { MatchedValue, PropMapping, PropMappingConflict, PropMappingResult, PropMappingRule, applyPropMapping, propMappingErrors };
+export { MappedInstance, MappedProps, MatchedValue, PropMapping, PropMappingConflict, PropMappingResult, PropMappingRule, applyPropMapping, mapComponentProps, onlyMapsProps, propMappingErrors, propMappingRuleSchema, propMappingRulesSchema, propMappingsIn };

package/dist/spec/prop-mapping.js

@@ -1,9 +1,67 @@
 import { kindOf, pathOf } from "../framework/utils/refs.js";
 import { propValueDomain, resolveComponentProps } from "../framework/projections.js";
 import { surfaceProp } from "../framework/prop-surface.js";
+import { editOp } from "../framework/config-op.js";
 import { layerComponent, modifierBlock, nestedBag } from "./rewrite-refs.js";
+import { z } from "zod";
 //#region src/spec/prop-mapping.ts
 /**
+* Moving what instances of a component stored onto its new API: `variant: 'brand-secondary'` →
+* `color: 'brand', prominence: 'outline'`, `size: 'xs'` → `size: 'sm'`.
+*
+* A rename carries a document across a change with one answer per name, so it can be recorded and
+* replayed (`rewrite-refs.ts`). A reshaped API has no one answer: whether `brand-secondary` is an
+* outline or a ghost is a design decision, so the mapping comes from the person (with an agent
+* proposing it) and is applied here once. Nothing stores it.
+*
+* A mapping is a list of rules for one component. Every rule's `when` is matched against the bag
+* as it was stored, and every rule that matches applies, so `variant` and `size` can be mapped by
+* separate rules and a pair of them by one rule naming both. A rule removes only what its `unset`
+* names: a prop a rule matches on may be one the new API still has.
+*
+* Positions follow the rename rewriter's: an element's own props, every modifier block nested in
+* them (`_hover: { variant: … }` is the same element's props under a condition), and each
+* `layerProps` bag whose layer renders the component.
+*/
+/** A rule as a tool takes it: the shape every surface that applies a mapping parses its input with. */
+const propMappingRuleSchema = z.object({
+	when: z.record(z.string(), z.union([
+		z.string(),
+		z.number(),
+		z.boolean()
+	])).describe("The stored values an instance must hold for the rule to apply, every one of them: { \"variant\": \"brand-secondary\" }."),
+	set: z.record(z.string(), z.unknown()).optional().describe("The props to write: { \"color\": \"brand\", \"prominence\": \"outline\" }."),
+	unset: z.array(z.string()).optional().describe("The props to remove. A prop the rule matches on stays unless it is named here, so a removed prop has to be.")
+});
+/** The rules of a mapping, as a tool takes them. */
+const propMappingRulesSchema = z.array(propMappingRuleSchema).min(1).describe("Every rule whose `when` matches an instance as stored applies to it, so separate props are mapped by separate rules, and a combination by one rule naming both.");
+/**
+* The mappings a batch of edits carries, in order: each `component/map-props` op as the mapping it
+* applies. The op changes nothing in the config, so the host that ran the batch applies these to the
+* documents it holds once the batch lands: Create to a branch's design files, a checkout to its call
+* sites. An op whose rules don't parse is left out; running the batch refused it already.
+*/
+function propMappingsIn(edits) {
+	return edits.flatMap((edit) => {
+		const { op } = editOp(edit);
+		if (op.kind !== "component" || op.operation !== "map-props") return [];
+		const rules = propMappingRulesSchema.safeParse(op.data?.rules);
+		if (!rules.success || typeof op.path !== "string") return [];
+		return [{
+			component: op.path.replace(/^component:/, ""),
+			rules: rules.data
+		}];
+	});
+}
+/**
+* Whether a batch is mappings alone: every edit a `component/map-props` op. Such a batch changes
+* nothing in the config, so a read-only branch (`main`, a published version) still runs it: its
+* design files take edits, and those are all it moves.
+*/
+function onlyMapsProps(edits) {
+	return edits.length > 0 && propMappingsIn(edits).length === edits.length;
+}
+/**
 * Why a prop can't hold `value`, or `undefined` when it can. A variant's or a slot's values come off
 * its surface, which follows a forward to the prop it routes to. Any other prop with a domain (a
 * composite, a style property) answers through its declaration, as validation does. A bracketed
@@ -165,5 +223,33 @@ function applyPropMapping(config, spec, mapping) {
 		conflicts
 	};
 }
+/**
+* A mapping tried on some instances' props, writing nothing: the `component/map-props` op. Refused,
+* with each reason, when the component can't take what it writes. Each bag is mapped as a design
+* file's instance is, modifier blocks and layer overrides included, so what it returns is what
+* applying the mapping to a document or a call site would store.
+*/
+function mapComponentProps(config, mapping, instances) {
+	const errors = propMappingErrors(config, mapping);
+	if (errors.length > 0) return {
+		ok: false,
+		errors
+	};
+	const { spec, conflicts } = applyPropMapping(config, { elements: Object.fromEntries(instances.map((props, i) => [String(i), {
+		type: `component:${mapping.component}`,
+		props
+	}])) }, mapping);
+	return {
+		ok: true,
+		instances: instances.map((props, i) => {
+			const after = spec.elements?.[String(i)]?.props ?? props;
+			return {
+				props: after,
+				changed: after !== props,
+				conflicts: conflicts.filter((conflict) => conflict.element === String(i)).flatMap((conflict) => conflict.props)
+			};
+		})
+	};
+}
 //#endregion
-export { applyPropMapping, propMappingErrors };
+export { applyPropMapping, mapComponentProps, onlyMapsProps, propMappingErrors, propMappingRuleSchema, propMappingRulesSchema, propMappingsIn };