@yahoo/uds-create-config 5.64.3 → 5.66.0

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

@@ -0,0 +1,97 @@
+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. */
+type MatchedValue = string | number | boolean;
+interface PropMappingRule {
+  /** The stored values the rule matches, every one of them. */
+  readonly when: Readonly<Record<string, MatchedValue>>;
+  /** The props it writes. */
+  readonly set?: Readonly<Record<string, unknown>>;
+  /** The props it removes. */
+  readonly unset?: readonly string[];
+}
+interface PropMapping {
+  /** The component whose instances it rewrites, as a path. */
+  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;
+  /** Where the bag sits in the element: `props`, `props._hover`, `props.layerProps.action`. */
+  readonly at: string;
+  /** The props the rules disagreed on. */
+  readonly props: readonly string[];
+}
+interface PropMappingResult {
+  readonly spec: RewritableSpec;
+  /** How many bags changed. Zero means the same spec object comes back, by identity. */
+  readonly changed: number;
+  readonly conflicts: readonly PropMappingConflict[];
+}
+/**
+ * Why `after` can't take what the mapping writes, one reason per prop or value, or none when it can.
+ * Checked before anything is applied, so a mapping that names a prop the component doesn't have
+ * is refused rather than written into every instance.
+ */
+declare function propMappingErrors(config: Config, mapping: PropMapping): string[];
+/**
+ * The spec with the mapping applied to every bag of the mapped component's props. `config` is the
+ * one the spec is being brought up to, which is what says which layers render the component.
+ *
+ * Returns the same spec object when nothing moved. Check the mapping with {@link propMappingErrors}
+ * 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 { MappedInstance, MappedProps, MatchedValue, PropMapping, PropMappingConflict, PropMappingResult, PropMappingRule, applyPropMapping, mapComponentProps, onlyMapsProps, propMappingErrors, propMappingRuleSchema, propMappingRulesSchema, propMappingsIn };

package/dist/spec/prop-mapping.js

@@ -0,0 +1,255 @@
+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
+* `[…]` literal is the style property's to accept, and a value that isn't a string isn't checked.
+*/
+function valueRefusal(config, component, prop, value) {
+	if (typeof value !== "string" || value.startsWith("[")) return void 0;
+	if (prop.kind === "variant" || prop.kind === "slot") return prop.values && !prop.values.includes(value) ? `"${value}", which isn't one of its values (${prop.values.join(", ")})` : void 0;
+	const declaration = resolveComponentProps(config, component)[prop.name];
+	const domain = declaration ? propValueDomain(config, declaration) : null;
+	return domain && !domain.accepts(value) ? `"${value}", which isn't one of its values (${domain.leaves.slice(0, 12).join(", ")}${domain.leaves.length > 12 ? ", …" : ""})` : void 0;
+}
+/**
+* Why `after` can't take what the mapping writes, one reason per prop or value, or none when it can.
+* Checked before anything is applied, so a mapping that names a prop the component doesn't have
+* is refused rather than written into every instance.
+*/
+function propMappingErrors(config, mapping) {
+	if (!config.resolve("component", mapping.component)) return [`No component "${mapping.component}"`];
+	const errors = [];
+	mapping.rules.forEach((rule, i) => {
+		if (Object.keys(rule.when).length === 0) errors.push(`Rule ${i + 1} matches every instance: name what it matches in \`when\``);
+		for (const [name, value] of Object.entries(rule.set ?? {})) {
+			const prop = surfaceProp(config, mapping.component, name);
+			if (!prop) {
+				errors.push(`Rule ${i + 1} sets "${name}", which ${mapping.component} doesn't have`);
+				continue;
+			}
+			const refusal = valueRefusal(config, mapping.component, prop, value);
+			if (refusal) errors.push(`Rule ${i + 1} sets ${name} to ${refusal}`);
+		}
+	});
+	return errors;
+}
+/** The rules applied to one bag of the mapped component's props, as stored. */
+function mapBag(bag, rules) {
+	const matched = rules.filter((rule) => Object.entries(rule.when).every(([name, value]) => name in bag && bag[name] === value));
+	if (matched.length === 0) return { kind: "same" };
+	const writes = /* @__PURE__ */ new Map();
+	const removes = /* @__PURE__ */ new Set();
+	const disagreed = /* @__PURE__ */ new Set();
+	for (const rule of matched) {
+		for (const [name, value] of Object.entries(rule.set ?? {})) {
+			if (writes.has(name) && writes.get(name) !== value) disagreed.add(name);
+			writes.set(name, value);
+		}
+		for (const name of rule.unset ?? []) removes.add(name);
+	}
+	if (disagreed.size > 0) return {
+		kind: "conflict",
+		props: [...disagreed]
+	};
+	const next = {};
+	for (const [name, value] of Object.entries(bag)) if (writes.has(name)) {
+		next[name] = writes.get(name);
+		writes.delete(name);
+	} else if (!removes.has(name)) next[name] = value;
+	for (const [name, value] of writes) next[name] = value;
+	return Object.keys(next).length === Object.keys(bag).length && Object.entries(next).every(([name, value]) => bag[name] === value) ? { kind: "same" } : {
+		kind: "changed",
+		bag: next
+	};
+}
+/**
+* A props bag on `component`, with the mapping applied to it when it's the mapped component's, and
+* to the modifier blocks and layer overrides inside it either way. `undefined` when nothing moved.
+*/
+function mapProps(walk, component, props, at) {
+	let next;
+	if (component === walk.mapping.component) {
+		const outcome = mapBag(props, walk.mapping.rules);
+		if (outcome.kind === "conflict") walk.conflicts.push({
+			element: walk.element,
+			at,
+			props: outcome.props
+		});
+		else if (outcome.kind === "changed") {
+			next = outcome.bag;
+			walk.changed++;
+		}
+	}
+	for (const [key, value] of Object.entries(next ?? props)) {
+		let rewritten;
+		if (key === "layerProps") rewritten = component ? mapLayerProps(walk, component, value, `${at}.${key}`) : void 0;
+		else {
+			const block = modifierBlock(walk.config, key, value, []);
+			rewritten = block ? mapProps(walk, component, block, `${at}.${key}`) : void 0;
+		}
+		if (!rewritten) continue;
+		next ??= { ...props };
+		next[key] = rewritten;
+	}
+	return next;
+}
+/** A `layerProps` map: each bag belongs to what its layer renders, which may be the mapped component. */
+function mapLayerProps(walk, component, layerProps, at) {
+	const bags = nestedBag(layerProps);
+	if (!bags) return void 0;
+	let next;
+	for (const [layer, value] of Object.entries(bags)) {
+		const bag = nestedBag(value);
+		if (!bag) continue;
+		const rewritten = mapProps(walk, layerComponent(walk.config, component, layer), bag, `${at}.${layer}`);
+		if (!rewritten) continue;
+		next ??= { ...bags };
+		next[layer] = rewritten;
+	}
+	return next;
+}
+/**
+* The component an element names, as a path: `undefined` for an intrinsic tag or another kind. A
+* stored type may carry the source it was placed through (`component:actions/Button@bridge`), and
+* names the same path either way.
+*/
+function componentOf(type) {
+	if (typeof type !== "string") return void 0;
+	if (!type.includes(":")) return pathOf(`component:${type}`);
+	return kindOf(type) === "component" ? pathOf(type) : void 0;
+}
+/**
+* The spec with the mapping applied to every bag of the mapped component's props. `config` is the
+* one the spec is being brought up to, which is what says which layers render the component.
+*
+* Returns the same spec object when nothing moved. Check the mapping with {@link propMappingErrors}
+* first: this applies what it's given.
+*/
+function applyPropMapping(config, spec, mapping) {
+	let elements;
+	let changed = 0;
+	const conflicts = [];
+	for (const [key, element] of Object.entries(spec.elements ?? {})) {
+		if (!element?.props) continue;
+		const walk = {
+			config,
+			mapping,
+			element: key,
+			conflicts,
+			changed: 0
+		};
+		const props = mapProps(walk, componentOf(element.type), element.props, "props");
+		if (!props) continue;
+		elements ??= { ...spec.elements };
+		elements[key] = {
+			...element,
+			props
+		};
+		changed += walk.changed;
+	}
+	return elements ? {
+		spec: {
+			...spec,
+			elements
+		},
+		changed,
+		conflicts
+	} : {
+		spec,
+		changed: 0,
+		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, mapComponentProps, onlyMapsProps, propMappingErrors, propMappingRuleSchema, propMappingRulesSchema, propMappingsIn };

package/dist/spec/rewrite-refs.js

@@ -246,8 +246,12 @@ function scopeFor(config, component) {
 /** The scope one `layerProps` entry's bag belongs to — the element the named layer renders. */
 function layerScope(config, scope, layer) {
 	if (!scope.component) return INTRINSIC;
-	const element = Component.get(config, scope.component)?.layers?.[layer];
-	return scopeFor(config, isRef(element) ? pathOf(element.__ref) : void 0);
+	return scopeFor(config, layerComponent(config, scope.component, layer));
+}
+/** The component a layer of `component` renders, or `undefined` for a raw tag or an unknown layer. */
+function layerComponent(config, component, layer) {
+	const element = Component.get(config, component)?.layers?.[layer];
+	return isRef(element) ? pathOf(element.__ref) : void 0;
 }
 /** Rename a KEY inside a props bag, preserving insertion order — order is meaning in a stored document. */
 function withRenamedKey(props, from, to) {
@@ -350,7 +354,7 @@ function rewriteProps(config, scope, props, rename, batch) {
 	let next = rewriteOwnEntries(config, scope, props, rename);
 	for (const [key, value] of Object.entries(next ?? props)) {
 		let rewritten;
-		if (key === LAYER_PROPS) rewritten = rewriteLayerProps(config, scope, value, rename, batch);
+		if (key === "layerProps") rewritten = rewriteLayerProps(config, scope, value, rename, batch);
 		else {
 			const block = modifierBlock(config, key, value, batch);
 			rewritten = block ? rewriteProps(config, scope, block, rename, batch) : void 0;
@@ -452,4 +456,4 @@ function rewriteSpecRefs(config, spec, renames) {
 	};
 }
 //#endregion
-export { composeRenames, documentRenamesFromPatches, documentRenamesFromSource, rewriteSpecRefs, styleNumberReadingRenames };
+export { LAYER_PROPS, composeRenames, documentRenamesFromPatches, documentRenamesFromSource, layerComponent, modifierBlock, nestedBag, rewriteSpecRefs, styleNumberReadingRenames };