@yahoo/uds-create-config 5.19.1 → 5.21.0

package/dist/configs/system.js

@@ -61,6 +61,10 @@ import { motionVariantsAndLayoutMigration } from "../migrations/20261006125609_m
 import { systemScriptsMigration } from "../migrations/20261007182932_system_scripts.js";
 import { styleNumbersNameNumericValuesMigration } from "../migrations/20261007210309_style_numbers_name_numeric_values.js";
 import { buildReactMigration } from "../migrations/20261008181849_build_react.js";
+import { cssMotionStatesMigration } from "../migrations/20261009000514_css_motion_states.js";
+import { startingStyleModifierMigration } from "../migrations/20261009022722_starting_style_modifier.js";
+import { cssMotionStrictMigration } from "../migrations/20261009181635_css_motion_strict.js";
+import { linkOverrideRefMigration } from "../migrations/20261009193004_link_override_ref.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.",
@@ -133,5 +137,9 @@ if (!registeredSchemaMigrations().has(20261006125609)) registerSchemaMigrations(
 if (!registeredSchemaMigrations().has(20261007182932)) registerSchemaMigrations(systemScriptsMigration);
 if (!registeredSchemaMigrations().has(20261007210309)) registerSchemaMigrations(styleNumbersNameNumericValuesMigration);
 if (!registeredSchemaMigrations().has(20261008181849)) registerSchemaMigrations(buildReactMigration);
+if (!registeredSchemaMigrations().has(20261009000514)) registerSchemaMigrations(cssMotionStatesMigration);
+if (!registeredSchemaMigrations().has(20261009022722)) registerSchemaMigrations(startingStyleModifierMigration);
+if (!registeredSchemaMigrations().has(20261009181635)) registerSchemaMigrations(cssMotionStrictMigration);
+if (!registeredSchemaMigrations().has(20261009193004)) registerSchemaMigrations(linkOverrideRefMigration);
 //#endregion
 export { System };

package/dist/entities/documentation/Documentation.d.ts

@@ -3,7 +3,7 @@ import { Named } from "../../framework/named.js";
 import { z } from "zod";
 
 //#region src/entities/documentation/Documentation.d.ts
-/** Knowledge Base articles are shared independently of a user's system. */
+/** A page from Create's docs site, held independently of a user's system. */
 declare const DocumentationDefinition: EntityClass<z.ZodObject<{
   title: z.ZodString;
   summary: z.ZodOptional<z.ZodString>;

package/dist/entities/system/Component.js

@@ -15,7 +15,6 @@ import { Style, addBagKeyIssues, anatomyPropValue, bagNameEdges, bagRewriteName,
 import { storedPreview } from "../../framework/preview-store.js";
 import { glyphPropsOf, propOwner, propValueDomain, refListOf, resolveComponentProps, stylePropNumberUnit, stylePropValueLeaves, validateComponentProps } from "../../framework/projections.js";
 import { carriesContent, intoName, isValueSlot, renderBoundProp, routedPropIn, routesContent } from "../../framework/prop-surface.js";
-import { inlineJsMotion } from "./Motion.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";
@@ -734,7 +733,7 @@ function buildBagFor(config, layerElement) {
 		}).optional();
 	}
 	shape.as ??= z.string().optional();
-	shape.motion = z.union([shape.motion ?? z.union([refSchema, z.string()]), inlineJsMotion], { error: "a layer's `motion` is a preset (`Motion.ref('<path>')`) or a JS preset written in place — `{ \"whileHover\": { \"scale\": 1.05 }, \"transition\": { … } }`, the fields `Motion.item` takes with `runtime: 'js'`. A CSS preset is named with `Motion.item`." }).optional();
+	for (const [key, owned] of config.layerKeys()) shape[key] = owned.schema(shape[key]).optional();
 	let bag;
 	const nested = z.lazy(() => bag).optional();
 	for (const mod of config.list("modifier")) shape[`_${mod.leaf}`] = nested;

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

@@ -1,7 +1,7 @@
 import { Ref } from "../../framework/utils/refs.js";
 import { SourceResolver, SourceState } from "../../framework/sources.js";
 import { ComputedInput } from "../../framework/registry.js";
-import { RegisteredComponentContracts, RegisteredEntities } from "../../framework/registered.js";
+import { RegisteredComponentContracts, RegisteredEntities, RegisteredMotionRuntimes } from "../../framework/registered.js";
 import { EntityClass, ItemOf } from "../../framework/defineEntity.js";
 import { PartialBodyOf } from "../../framework/defineConfig.js";
 import { Named } from "../../framework/named.js";
@@ -243,9 +243,30 @@ type PinOptions = { [A in keyof RegisteredEntities]?: Record<string, PinAdjustme
  */
 type PinOptionsInput<K extends string = string> = { [A in keyof RegisteredEntities]?: RegisteredEntities[A] extends {
   readonly kind: 'component';
-} ? { [P in K]?: PinComponentAdjustment<RegisteredEntities[A], P> } : Record<string, PinAdjustment<RegisteredEntities[A]>> };
+} ? { [P in K]?: PinComponentAdjustment<RegisteredEntities[A], P> } : RegisteredEntities[A] extends {
+  readonly kind: 'motion';
+} ? { [P in K]?: PinMotionAdjustment<RegisteredEntities[A], P> } : Record<string, PinAdjustment<RegisteredEntities[A]>> };
+/** A motion entry: an adjustment whose `runtime` is one the linked preset can be read as
+ *  ({@link RegisteredMotionRuntimes}), so a swap the conversion would refuse doesn't type. */
+type PinMotionAdjustment<E, P extends string> = {
+  override?: PinMotionBody<E, P> | KindRefOf<E>;
+  extend?: PinMotionBody<E, P>;
+  hidden?: boolean;
+};
+type PinMotionBody<E, P extends string> = Extract<StoredBodyOf<PartialBodyOf<E>>, {
+  runtime?: MotionRuntimeOf<P>;
+}>;
+/** The linked presets registered at `path`, from whichever source. */
+type LinkedMotionKey<P extends string> = Extract<keyof RegisteredMotionRuntimes, `${P}@${string}`>;
+type MotionRuntimeOf<P extends string> = [LinkedMotionKey<P>] extends [never] ? 'css' | 'js' : RegisteredMotionRuntimes[LinkedMotionKey<P>];
+/** A ref to another entity of `E`'s kind, which re-points the path to it. */
+type KindRefOf<E> = E extends {
+  readonly kind: infer K extends string;
+} ? {
+  readonly __ref: `${K}:${string}`;
+} : never;
 type PinComponentAdjustment<E, P extends string> = {
-  override?: PinComponentBody<E, P>;
+  override?: PinComponentBody<E, P> | KindRefOf<E>;
   extend?: PinComponentBody<E, P>;
   hidden?: boolean;
 };
@@ -265,7 +286,7 @@ type LinkDeclaration = '*' | Record<string, '*' | readonly string[]>;
 /** One `options` entry, checked against the kind its accessor addresses. The runtime floor — that an
  *  entry names at least one of the three — is the schema's `refine`, which reports the path. */
 type PinAdjustment<E> = {
-  override?: StoredBodyOf<PartialBodyOf<E>>;
+  override?: StoredBodyOf<PartialBodyOf<E>> | KindRefOf<E>;
   extend?: StoredBodyOf<PartialBodyOf<E>>;
   hidden?: boolean;
 };
@@ -281,6 +302,7 @@ type StoredBodyOf<Body> = 'styles' extends keyof Body ? Omit<Body, 'styles'> & {
  * the same entry, with nothing to check the bodies against yet.
  */
 interface PinDirective {
+  /** A body, or a ref that re-points the path to another entity of the same kind. */
   readonly override?: Record<string, unknown>;
   readonly extend?: Record<string, unknown>;
   readonly hidden?: boolean;
@@ -413,5 +435,23 @@ declare function suggestLinkSlug({
   name: string;
   taken: ReadonlySet<string>;
 }): string;
+/**
+ * A link's `options` entry whose `override` is a ref: the path it names reads as that entity
+ * (`'js/scale': { override: Motion.ref('css/scale') }`). `problem` says why it can't: the ref names
+ * another kind, it leads back to this path through other re-pointed paths, or, once the link's
+ * source is attached, it names nothing.
+ */
+interface LinkRedirect {
+  /** The link's slug. */
+  readonly link: string;
+  readonly accessor: string;
+  readonly path: string;
+  readonly target: string;
+  readonly problem?: 'kind' | 'cycle' | 'missing';
+}
+/** Every re-pointed path the config's links declare, with what stops each one, if anything. */
+declare function linkRedirects(config: Config): LinkRedirect[];
+/** One sentence for a re-pointed path that can't be read. */
+declare function redirectSentence(redirect: LinkRedirect): string;
 //#endregion
-export { LINK_SLUG, LINK_SLUG_MESSAGE, LinkDeclaration, LinkedSystem, LinkedSystemClass, LinkedSystemCreateInput, LinkedSystemItemInput, LinkedSystemResolver, LinkedSystemState, PinDirective, PinOptions, PinOptionsField, PinOptionsInput, ResolvedSource, Source, SourceUnavailable, borrowedGroup, borrowedItem, isLinkSlug, resolvedSource, sourceOfGroup, sourceOfItem, sourceSlugFor, sourceUnavailable, suggestLinkSlug };
+export { LINK_SLUG, LINK_SLUG_MESSAGE, LinkDeclaration, LinkRedirect, LinkedSystem, LinkedSystemClass, LinkedSystemCreateInput, LinkedSystemItemInput, LinkedSystemResolver, LinkedSystemState, PinDirective, PinOptions, PinOptionsField, PinOptionsInput, ResolvedSource, Source, SourceUnavailable, borrowedGroup, borrowedItem, isLinkSlug, linkRedirects, redirectSentence, resolvedSource, sourceOfGroup, sourceOfItem, sourceSlugFor, sourceUnavailable, suggestLinkSlug };

package/dist/entities/system/LinkedSystem.js

@@ -1,5 +1,5 @@
 import { rejectData } from "../../framework/rejection.js";
-import { isRef } from "../../framework/utils/refs.js";
+import { isRef, kindOf, pathOf, refSchema } from "../../framework/utils/refs.js";
 import { isPlainObject } from "../../framework/utils/field-path.js";
 import { pathInput } from "../../framework/schemas.js";
 import { kindBorrowable } from "../../framework/registry.js";
@@ -262,7 +262,7 @@ function exampleBorrowable(config, slug) {
 	}
 }
 const pinOptions = z.record(z.string(), z.record(z.string(), z.strictObject({
-	override: z.record(z.string(), z.unknown()).optional(),
+	override: z.union([refSchema, z.record(z.string(), z.unknown())]).optional(),
 	extend: z.record(z.string(), z.unknown()).optional(),
 	hidden: z.boolean().optional()
 }).refine((entry) => entry.override !== void 0 || entry.extend !== void 0 || entry.hidden !== void 0, { message: "An `options` entry needs `override`, `extend` or `hidden`." }))).optional().describe("Per-entity adjustments, keyed by accessor, then path, then verb.");
@@ -270,7 +270,7 @@ const LinkedSystemDefinition = defineEntity({
 	kind: "linked-system",
 	label: "Linked system",
 	labelPlural: "Linked systems",
-	invariants: (config) => config.list("linked-system").filter(({ path }) => !isLinkSlug(path)).map(({ path }) => `Link "${path}": ${LINK_SLUG_MESSAGE}`),
+	invariants: (config) => [...config.list("linked-system").filter(({ path }) => !isLinkSlug(path)).map(({ path }) => `Link "${path}": ${LINK_SLUG_MESSAGE}`), ...linkRedirects(config).filter((redirect) => redirect.problem !== void 0 && redirect.problem !== "missing").map(redirectSentence)],
 	schemas: {
 		create: { example: ({ config }) => {
 			const path = freeExampleSlug(config);
@@ -892,5 +892,56 @@ function suggestLinkSlug({ name, taken }) {
 		if (!taken.has(candidate)) return candidate;
 	}
 }
+/** Every re-pointed path the config's links declare, with what stops each one, if anything. */
+function linkRedirects(config) {
+	const kindOfAccessor = (accessor) => config.accessors()[accessor]?.kind ?? accessor;
+	const declared = [];
+	for (const link of config.list("linked-system")) {
+		const { options } = link.toJSON();
+		for (const [accessor, entries] of Object.entries(options ?? {})) for (const [path, entry] of Object.entries(entries ?? {})) {
+			const override = isPlainObject(entry) ? entry.override : void 0;
+			if (!isRef(override)) continue;
+			declared.push({
+				link: link.path,
+				accessor,
+				path,
+				target: override.__ref
+			});
+		}
+	}
+	const next = /* @__PURE__ */ new Map();
+	for (const { accessor, path, target } of declared) next.set(`${kindOfAccessor(accessor)}:${path}`, `${kindOf(target)}:${pathOf(target)}`);
+	const loops = (start) => {
+		const seen = /* @__PURE__ */ new Set();
+		for (let at = start; at !== void 0; at = next.get(at)) {
+			if (seen.has(at)) return at === start;
+			seen.add(at);
+		}
+		return false;
+	};
+	return declared.map((redirect) => {
+		const kind = kindOfAccessor(redirect.accessor);
+		if (kindOf(redirect.target) !== kind) return {
+			...redirect,
+			problem: "kind"
+		};
+		if (loops(`${kind}:${redirect.path}`)) return {
+			...redirect,
+			problem: "cycle"
+		};
+		if (config.sourceFor(redirect.link) && !config.resolveRef(redirect.target)) return {
+			...redirect,
+			problem: "missing"
+		};
+		return redirect;
+	});
+}
+/** One sentence for a re-pointed path that can't be read. */
+function redirectSentence(redirect) {
+	const at = `Link "${redirect.link}": options.${redirect.accessor}["${redirect.path}"] re-points to ${redirect.target}`;
+	if (redirect.problem === "kind") return `${at}, which is no ${redirect.accessor} entry. A path can only read as another entity of its own kind.`;
+	if (redirect.problem === "cycle") return `${at}, which leads back to it through other re-pointed paths.`;
+	return `${at}, which names nothing this config can read.`;
+}
 //#endregion
-export { LINK_SLUG, LINK_SLUG_MESSAGE, LinkedSystem, borrowedGroup, borrowedItem, isLinkSlug, resolvedSource, sourceOfGroup, sourceOfItem, sourceSlugFor, sourceUnavailable, suggestLinkSlug };
+export { LINK_SLUG, LINK_SLUG_MESSAGE, LinkedSystem, borrowedGroup, borrowedItem, isLinkSlug, linkRedirects, redirectSentence, resolvedSource, sourceOfGroup, sourceOfItem, sourceSlugFor, sourceUnavailable, suggestLinkSlug };

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

@@ -11,8 +11,10 @@ import { z } from "zod";
 declare const MODIFIER_CATEGORIES: readonly ["mode", "state"];
 type ModifierCategory = (typeof MODIFIER_CATEGORIES)[number];
 /** How a web modifier activates. A `media-query` is an at-rule the emitter wraps the block in;
- *  `selector` composes onto the element, or stands as an ancestor for a mode. */
-declare const WEB_ACTIVATIONS: readonly ["selector", "media-query", "composite"];
+ *  `selector` composes onto the element, or stands as an ancestor for a mode. `starting-style` wraps
+ *  the block in `@starting-style`: the style an element transitions from as it mounts or leaves
+ *  `display: none`. It takes no condition, so its `value` is left empty. */
+declare const WEB_ACTIVATIONS: readonly ["selector", "media-query", "composite", "starting-style"];
 type WebActivation = (typeof WEB_ACTIVATIONS)[number];
 /**
  * A modifier group's own fields.
@@ -44,6 +46,7 @@ declare const ModifierDefinition: EntityClass<z.ZodObject<{
     selector: "selector";
     composite: "composite";
     "media-query": "media-query";
+    "starting-style": "starting-style";
   }>;
   value: z.ZodUnion<readonly [z.ZodString, z.ZodLazy<CompositeClass>]>;
   media: z.ZodOptional<z.ZodString>;

package/dist/entities/system/Modifier.js

@@ -8,11 +8,14 @@ import { z } from "zod";
 *  plain modifiers that compose as fragments and that no surface treats specially. */
 const MODIFIER_CATEGORIES = ["mode", "state"];
 /** How a web modifier activates. A `media-query` is an at-rule the emitter wraps the block in;
-*  `selector` composes onto the element, or stands as an ancestor for a mode. */
+*  `selector` composes onto the element, or stands as an ancestor for a mode. `starting-style` wraps
+*  the block in `@starting-style`: the style an element transitions from as it mounts or leaves
+*  `display: none`. It takes no condition, so its `value` is left empty. */
 const WEB_ACTIVATIONS = [
 	"selector",
 	"media-query",
-	"composite"
+	"composite",
+	"starting-style"
 ];
 /** A ref to a modifier, spelled out because the kind's own class is what this is a field of. */
 const modifierRef = refTo("modifier");