@yahoo/uds-create-config 5.75.0 → 5.77.0

package/dist/capture/class-grammar.js

@@ -1,19 +1,59 @@
 import { isRef, pathOf } from "../framework/utils/refs.js";
 import { className, renderStyleValue, resolveComponentProps, resolveTokenValue, stylePropEntries } from "../framework/projections.js";
 import { intoName, routesContent, routesIntoText } from "../framework/prop-surface.js";
-import { componentLayerClass, componentRuleClasses, stylePropClasses } from "../framework/class-names.js";
+import { arbitraryClassName, componentLayerClass, componentRuleClasses, stylePropClasses } from "../framework/class-names.js";
 //#region src/capture/class-grammar.ts
 const VIEWPORT_UNIT = /\d(vh|vw|dvh|dvw|svh|svw|lvh|lvw|vmin|vmax)\b/;
 /** `0px` → `0`, collapsed spaces, lowercase keywords; what two spellings of one value share. */
+/** CSS properties whose value is a colour. */
+const COLOR_PROPERTY = /(^|-)(color|fill|stroke)$|^background$/;
+/** Whether an off-scale value is a colour (`#f00`, `rgb(…)`, a named colour), not a length or a number. */
+function isColorValue(value) {
+	const v = value.trim().toLowerCase();
+	if (/^(#|rgba?\(|hsla?\(|oklch\(|oklab\(|lab\(|lch\(|color\(|color-mix\()/.test(v)) return true;
+	if (/^(color|colour):/.test(v)) return true;
+	if (/^[-\d.]/.test(v) || /^(calc|min|max|clamp|var)\(/.test(v)) return false;
+	return /^[a-z]+$/.test(v) && v !== "auto" && v !== "none";
+}
 function normalizeCssValue(value) {
 	return value.trim().replace(/\s+/g, " ").replace(/(^|[\s,(])0(?:px|rem|em|%)(?=$|[\s,)])/g, "$10").toLowerCase();
 }
 function classGrammar(config) {
 	const styleProps = /* @__PURE__ */ new Map();
-	for (const entity of config.list("style-property")) for (const [leaf, cls] of stylePropClasses(config, entity.path)) if (!styleProps.has(cls)) styleProps.set(cls, {
-		path: entity.path,
-		leaf
-	});
+	const arbitraryStems = /* @__PURE__ */ new Map();
+	for (const entity of config.list("style-property")) {
+		for (const [leaf, cls] of stylePropClasses(config, entity.path)) if (!styleProps.has(cls)) styleProps.set(cls, {
+			path: entity.path,
+			leaf
+		});
+		if (entity.toJSON().arbitrary) {
+			const stem = arbitraryClassName({
+				config,
+				path: entity.path,
+				value: "[x]"
+			}).slice(0, -3);
+			arbitraryStems.set(stem, [...arbitraryStems.get(stem) ?? [], entity.path]);
+		}
+	}
+	const arbitraryMatch = (cls) => {
+		const open = cls.indexOf("[");
+		if (open <= 0) return void 0;
+		const close = cls.indexOf("]", open);
+		if (close === -1) return void 0;
+		const rest = cls.slice(close + 1);
+		if (rest !== "" && !/^\/(?:\[[^\]]+\]|[\w.-]+)$/.test(rest)) return void 0;
+		const paths = arbitraryStems.get(cls.slice(0, open)) ?? [];
+		const inner = cls.slice(open + 1, close);
+		if (!inner || paths.length === 0) return void 0;
+		return {
+			path: paths.length === 1 ? paths[0] : paths.find((each) => writesColor(each) === isColorValue(inner)) ?? paths[0],
+			leaf: `[${inner}]`
+		};
+	};
+	function writesColor(path) {
+		const { properties = [] } = config.resolve("style-property", path)?.toJSON() ?? {};
+		return properties.some((property) => COLOR_PROPERTY.test(property));
+	}
 	const composites = config.list("composite").map((entity) => ({
 		path: entity.path,
 		cls: className(config, "composite", entity.path)
@@ -126,7 +166,7 @@ function classGrammar(config) {
 		};
 	};
 	return {
-		styleProp: (cls) => styleProps.get(cls),
+		styleProp: (cls) => styleProps.get(cls) ?? arbitraryMatch(cls),
 		stylePropsFor: (cssProperty) => byCss.get(cssProperty.toLowerCase()) ?? [],
 		viewportLeaf(path, leaf) {
 			return (valuesOf(path).get(leaf) ?? []).some((v) => VIEWPORT_UNIT.test(v));

package/dist/configs/build-options.js

@@ -129,6 +129,16 @@ const buildFields = z.strictObject({
 		title: "React version",
 		description: `The React major the app this repo builds for runs. \`18\` wraps each emitted web component in \`forwardRef\`, so a call site's \`ref\` reaches its element. Unset, \`${BUILD_DEFAULTS.react}\`.`,
 		default: BUILD_DEFAULTS.react
+	}).optional(),
+	/**
+	* Whether the component modules `uds build` writes carry the component data attributes:
+	* `data-uds-component`, `data-uds-layer` and `data-uds-slot`, which Create's tools read to map an
+	* app's rendered markup back to its components. Unset, off; `uds build --debug` turns it on for
+	* one build.
+	*/
+	debug: z.boolean().meta({
+		title: "Debug",
+		description: "Have `uds build` write the component data attributes (`data-uds-component`, `data-uds-layer`, `data-uds-slot`) on the elements components render. Create's tools read them to map the app's rendered markup back to its components, such as the canvas capture rebuilding a page as components. Unset, off; `uds build --debug` turns it on for one build."
 	}).optional()
 }, { error: (issue) => issue.code === "unrecognized_keys" && issue.keys.includes("include") ? "`settings.build.include` was removed: every source file under `inputDir` now ships by default. Delete it, and list any file to keep out in `settings.build.exclude`." : void 0 });
 //#endregion

package/dist/configs/react-native-system.d.ts

@@ -42,6 +42,7 @@ declare const ReactNativeSystemDefinition: ConfigClass<{
       outputAlias: _$zod.ZodOptional<_$zod.ZodString>;
       linkedDir: _$zod.ZodOptional<_$zod.ZodString>;
       react: _$zod.ZodOptional<_$zod.ZodUnion<readonly [_$zod.ZodLiteral<18>, _$zod.ZodLiteral<19>]>>;
+      debug: _$zod.ZodOptional<_$zod.ZodBoolean>;
     }, _$zod_v4_core0.$strict>>;
     css: _$zod.ZodOptional<_$zod.ZodObject<{
       prefix: _$zod.ZodOptional<_$zod.ZodUnion<readonly [_$zod.ZodString, _$zod.ZodObject<{

package/dist/configs/system.js

@@ -39,6 +39,7 @@ import { defaultColorsMigration } from "../migrations/20261102143821_default_col
 import { linkReplaceMigration } from "../migrations/20261102185610_link_replace.js";
 import { mapPropsFromMigration } from "../migrations/20261102193912_map_props_from.js";
 import { sourcesAuthoringMigration } from "../migrations/20261103115059_sources_authoring.js";
+import { buildDebugMigration } from "../migrations/20261104151013_build_debug.js";
 import { CanvasRole } from "../entities/system/CanvasRole.js";
 import { GlobalStyle } from "../entities/system/GlobalStyle.js";
 import { Guidance } from "../entities/system/Guidance.js";
@@ -214,5 +215,6 @@ if (!registeredSchemaMigrations().has(20261102143821)) registerSchemaMigrations(
 if (!registeredSchemaMigrations().has(20261102185610)) registerSchemaMigrations(linkReplaceMigration);
 if (!registeredSchemaMigrations().has(20261102193912)) registerSchemaMigrations(mapPropsFromMigration);
 if (!registeredSchemaMigrations().has(20261103115059)) registerSchemaMigrations(sourcesAuthoringMigration);
+if (!registeredSchemaMigrations().has(20261104151013)) registerSchemaMigrations(buildDebugMigration);
 //#endregion
 export { System };

package/dist/entities/native/NativeSettings.d.ts

@@ -31,6 +31,7 @@ declare const NativeSettings: EntityClass<z.ZodObject<Omit<{
     outputAlias: z.ZodOptional<z.ZodString>;
     linkedDir: z.ZodOptional<z.ZodString>;
     react: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<18>, z.ZodLiteral<19>]>>;
+    debug: z.ZodOptional<z.ZodBoolean>;
   }, z.core.$strict>>;
   css: z.ZodOptional<z.ZodObject<{
     prefix: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{

package/dist/entities/system/Component.js

@@ -2183,7 +2183,7 @@ const ComponentEntity = defineEntity({
 			input: z.object({ path: pathInput("component") }),
 			readOnly: false,
 			label: "Create blank",
-			description: "Create an empty component at a new qualified `path`, to design on the canvas first: one `div` root layer and the node that renders it, with no props, no variants, no slot, no styles and no preview content. This is exactly what Studio's \"+\" creates. Takes only `path`. Use it for \"a new component\", \"a blank component\" or \"start a component from nothing\"; `create` is for a component whose body is already known.",
+			description: "Create an empty component at a new qualified `path`, to design on the canvas first: one `div` root layer and the node that renders it, with no props, no variants, no slot, no styles and no preview content. This is exactly what Create's \"+\" creates. Takes only `path`. Use it for \"a new component\", \"a blank component\" or \"start a component from nothing\"; `create` is for a component whose body is already known.",
 			scope: "item",
 			creates: true,
 			title: (entity) => `Create blank ${entity}`,
@@ -2202,7 +2202,7 @@ const ComponentEntity = defineEntity({
 			example: ({ config }) => forwardsCreateExample(config)
 		},
 		"sub-upsert/forwards": { description: `Set what one layer forwards, added when absent and replaced whole when present. ${FORWARDS_DESCRIPTION}` },
-		"sub-update/forwards": { description: `Replace what one layer forwards: the member is \`'*'\` or a list, so \`data\` is the whole new value. ${FORWARDS_DESCRIPTION}` },
+		"sub-update/forwards": { description: `Replace what one layer forwards: the member is a list of prop names, so \`data\` is the whole new list. ${FORWARDS_DESCRIPTION}` },
 		/**
 		* Add an element to a composition — a layer and the node that targets it, together.
 		*
@@ -2500,7 +2500,7 @@ count: z.number().int().min(1).max(50).optional() }).prefault({})
 			}),
 			readOnly: false,
 			label: "Forward layer props",
-			description: "Expose a layer's props at the component's top level (\"forward everything from the root but icon\", \"also forward width\"): `props` is `\"*\"` for every prop the layer's element takes, or a list added to what the layer forwards now, or that replaces it with `replace`; `except` leaves props out of either. A prop the element lacks, one the component declares itself, and one a sibling layer already forwards are refused. Read `component/get` for what a layer forwards now.",
+			description: "Expose a layer's props at the component's top level (\"also forward width\", \"forward onClick from the root\"): `props` is a list of prop names, added to what the layer forwards now, or replacing it with `replace`. A prop the element lacks, one the component declares itself, and one a sibling layer already forwards are refused. Read `component/get` for what a layer forwards now.",
 			scope: "item",
 			title: (entity) => `Forward ${entity} layer props`,
 			handler: (input, config) => {

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

@@ -24,6 +24,7 @@ declare const BuildSectionDefinition: SubEntityClass<z.ZodObject<{
   outputAlias: z.ZodOptional<z.ZodString>;
   linkedDir: z.ZodOptional<z.ZodString>;
   react: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<18>, z.ZodLiteral<19>]>>;
+  debug: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strict>>;
 interface BuildSectionClass extends Named<typeof BuildSectionDefinition> {}
 declare const BuildSection: BuildSectionClass;
@@ -194,6 +195,7 @@ declare const SettingsDefinition: EntityClass<z.ZodObject<{
     outputAlias: z.ZodOptional<z.ZodString>;
     linkedDir: z.ZodOptional<z.ZodString>;
     react: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<18>, z.ZodLiteral<19>]>>;
+    debug: z.ZodOptional<z.ZodBoolean>;
   }, z.core.$strict>>;
   css: z.ZodOptional<z.ZodObject<{
     prefix: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{

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

package/dist/framework/Config.js

@@ -6406,7 +6406,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 > 20261103115059) throw new SchemaVersionTooNew(claimed);
+		if (claimed > 20261104151013) 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/defineDerivedEntity.js

@@ -14,7 +14,7 @@ import { z } from "zod";
 *    non-serializable projection (a zod schema, a function). Each fn declares its own provenance.
 *
 * A derived kind self-derives on registration, sourcing from the config it's registered into;
-* `Config.register` routes it by whether the KIND is derived. See `docs/config-v2.md`.
+* `Config.register` routes it by whether the kind is derived.
 */
 /** What `extend` accepts. Checked at runtime because `extend` is shadowed: an unrecognized key is a
 *  typo, or a zod raw shape reaching this method expecting zod's `extend`. Either should say so

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 = 20261103115059;
+declare const CURRENT_SCHEMA_VERSION = 20261104151013;
 /** 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 = 20261103115059;
+const CURRENT_SCHEMA_VERSION = 20261104151013;
 /** 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 > 20261103115059) 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 > 20261104151013) 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 ?? 20261103115059;
+	const target = options?.target ?? 20261104151013;
 	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 ?? 20261103115059;
+	const target = options?.target ?? 20261104151013;
 	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 ?? 20261103115059;
+	const target = options?.target ?? 20261104151013;
 	const entries = [];
 	const held = [];
 	const retired = [];

package/dist/index.js

@@ -66,11 +66,11 @@ import { styleSetEdits } from "./entities/system/component-style-set.js";
 import { convertLinkedTokenValue, prepareLinkedTokenBody } from "./entities/system/linked-token-values.js";
 import { Token, defineOverride, overrideCondition, overrideKey, overrideKeyModifiers, overrideModifiers } from "./entities/system/Token.js";
 import { Component, SLOT_CODE_FORMS, blankComponentBody, canonicalWhen, forwardedNames, layerRef, ownValues, ownsItsValues, valueRef } from "./entities/system/Component.js";
+import { Icon, iconVariantAs } from "./entities/system/Icon.js";
+import { glyphExportNames, glyphType, iconCategories, iconLibraries, iconLibrary, iconToolLibraries, isDeclaredElementProp, librariesBoundBy, libraryHolding, memberVariantOptions, placedGlyphElement, resolveIconLibraries } from "./entities/system/icon-library.js";
 import { CapturedNode, capturedFromDom, elementFromCaptured } from "./capture/captured-tree.js";
 import { classGrammar } from "./capture/class-grammar.js";
 import { specFromCapture } from "./capture/capture-to-spec.js";
-import { Icon, iconVariantAs } from "./entities/system/Icon.js";
-import { glyphExportNames, glyphType, iconCategories, iconLibraries, iconLibrary, iconToolLibraries, isDeclaredElementProp, librariesBoundBy, libraryHolding, memberVariantOptions, placedGlyphElement, resolveIconLibraries } from "./entities/system/icon-library.js";
 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";

package/dist/migrations/20261104151013_build_debug.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Additions only, so the envelope passes through as it is:
+ *
+ * - A system's `settings.build` may name `debug`: whether the component modules `uds build` writes
+ *   carry the component data attributes.
+ */
+import type { SchemaMigration } from '../framework/schema-version';
+export declare const BUILD_DEBUG_VERSION = 20261104151013;
+export declare const buildDebugMigration: SchemaMigration;

package/dist/migrations/20261104151013_build_debug.js

@@ -0,0 +1,10 @@
+//#region src/migrations/20261104151013_build_debug.ts
+const BUILD_DEBUG_VERSION = 20261104151013;
+const buildDebugMigration = {
+	version: BUILD_DEBUG_VERSION,
+	up(json) {
+		return json;
+	}
+};
+//#endregion
+export { BUILD_DEBUG_VERSION, buildDebugMigration };