@yahoo/uds-create-config 4.49.1 → 4.50.1

package/dist/entities/system/Composite.js

@@ -15,7 +15,7 @@ const Composite = defineEntity({
 	kind: "composite",
 	label: "Composite style",
 	labelPlural: "Composite styles",
-	fields: z.object({ styles: Style }),
+	fields: z.object({ styles: Style.describe("The style values the composite bundles. Each declaration is a member, so an editor writes one key at a time.") }),
 	subEntities: { styles: Style },
 	nameEdges: bagNameEdges(compositeBags),
 	styleBags: compositeBags,

package/dist/entities/system/Device.js

@@ -3,9 +3,9 @@ import { z } from "zod";
 const Device = defineEntity({
 	kind: "device",
 	fields: z.object({
-		width: z.number(),
-		height: z.number(),
-		name: z.string().optional()
+		width: z.number().describe("The viewport width a preview renders at."),
+		height: z.number().describe("The viewport height a preview renders at."),
+		name: z.string().optional().describe("The name the device picker shows.")
 	})
 });
 //#endregion

package/dist/entities/system/Font.js

@@ -20,11 +20,11 @@ const Font = defineEntity({
 	labelPlural: "Fonts",
 	fields: z.strictObject({
 		/** The CSS-facing family name (`'YA Sans'`) — required; a family without one can't be used. */
-		fontFamily: z.string(),
+		fontFamily: z.string().describe("The CSS family name, such as `'YA Sans'`."),
 		/** One entry per font file. */
-		files: FontFile.optional(),
+		files: FontFile.optional().describe("One entry per font file, keyed by any name (`'400-normal'`)."),
 		/** Families to fall back to after this one, for a `font-family` stack. */
-		fallbackStack: z.array(z.string()).optional(),
+		fallbackStack: z.array(z.string()).optional().describe("Families to fall back to, in order."),
 		/**
 		* A CSS custom property the HOST publishes the loaded face's family under — `next/font`'s
 		* `variable` option (`--uds-font-family-inter`), or any loader that hands the page a variable
@@ -33,11 +33,11 @@ const Font = defineEntity({
 		* is how a token can be `Font.ref(…)` to such a family and still render the host's face, whose
 		* real family name (`__Inter_a1b2c3`) nothing in a config can know.
 		*/
-		variable: z.string().regex(/^--[A-Za-z0-9_-]+$/, "a CSS custom property name: `--name`").optional(),
+		variable: z.string().regex(/^--[A-Za-z0-9_-]+$/, "a CSS custom property name: `--name`").optional().describe("A CSS custom property the host publishes the loaded face under, such as `next/font`'s `variable`. Must look like `--name`."),
 		/** Set explicitly; otherwise inferred from a file declaring a weight RANGE. */
-		isVariableFont: z.boolean().optional()
+		isVariableFont: z.boolean().optional().describe("Set explicitly, or inferred from a file that declares a weight range.")
 	}),
-	groupFields: z.strictObject({ version: z.string().optional() }),
+	groupFields: z.strictObject({ version: z.string().optional().describe("The version of the family the group ships.") }),
 	subEntities: { files: FontFile }
 });
 /**

package/dist/entities/system/GlobalStyle.js

@@ -32,15 +32,15 @@ const GlobalStyle = defineEntity({
 	labelPlural: "Global styles",
 	fields: z.strictObject({
 		/** What the rule applies to — `html, body`, `@keyframes bounce`, `.prompt-editor p`. */
-		selector: z.string(),
+		selector: z.string().describe("What the rule applies to: `html, body`, `@keyframes bounce`, `.prompt-editor p`."),
 		/** Property → value, camelCase as it's authored; a nested record is a nested rule. */
-		declarations: z.record(z.string(), declared),
+		declarations: z.record(z.string(), declared).describe("Property to value, in camelCase. A nested record is a nested rule, for an at-rule or grouped selector."),
 		/**
 		* Every declaration in the rule, nested ones included, is emitted `!important`. The sheet is
 		* layered and a third party's stylesheet (React Flow, CodeMirror's injected theme) is not, so a
 		* rule meant to beat one has to say so; the flag lets it while its values stay refs.
 		*/
-		important: z.boolean().optional()
+		important: z.boolean().optional().describe("Emit every declaration `!important`, to beat a third party's unlayered stylesheet.")
 	})
 });
 /**

package/dist/entities/system/Guidance.js

@@ -14,7 +14,7 @@ const Guidance = defineEntity({
 	kind: "guidance",
 	label: "Guidance",
 	labelPlural: "Guidance",
-	fields: z.object({ text: z.array(z.union([z.string(), refSchema])) }),
+	fields: z.object({ text: z.array(z.union([z.string(), refSchema])).describe("The rule, as prose runs and `@mention` refs to tokens or components.") }),
 	groupFields: z.strictObject({
 		/** Display name for the topic; falls back to the group's own path segment. */
 		label: z.string().optional(),
@@ -24,7 +24,7 @@ const Guidance = defineEntity({
 		* Which AI lanes this topic is fed to. Absent means every lane. An empty array is a topic
 		* turned off everywhere, which is what unchecking the last box stores.
 		*/
-		appliesTo: z.array(z.enum(GUIDANCE_LANES)).optional()
+		appliesTo: z.array(z.enum(GUIDANCE_LANES)).optional().describe("The lanes the topic reaches. Unset means every lane.")
 	})
 });
 /** Nothing up the chain scoped anything, so the rules reach every surface. */

package/dist/entities/system/Icon.js

@@ -26,22 +26,22 @@ const Icon = defineEntity({
 		/** The package the glyphs come from — a REF to the `Package` item, which owns the module
 		*  specifier (its path) and the pinned version. A generated module imports the glyphs it renders
 		*  from it, and a render that imports a member of it is placing a glyph of this set. */
-		package: Package.optional(),
+		package: Package.optional().describe("The npm package the set comes from."),
 		/** Where member metadata comes from and how to read it — `{ from, format }`. The build resolves
 		*  the source and bakes each member's fields; see `icon-metadata.ts`. */
-		metadata: iconMetadataDeclaration.optional(),
+		metadata: iconMetadataDeclaration.optional().describe("Catalogue metadata read from the package."),
 		/** Named sizes the set ships (`sm: 16`).
 		*  @deprecated How a glyph is sized is the icon tool's component's business: the icon tool's component declares its own `size` and `variant` props, and every surface reads those. TODO: remove with a migration once no surface reads the library's copy. */
-		sizes: z.record(z.string(), z.number()).optional(),
+		sizes: z.record(z.string(), z.number()).optional().describe("Deprecated. The icon tool's component declares its own `size` and `variant` props."),
 		/** Weights/styles the set ships (`regular`, `fill`).
 		*  @deprecated Which styles a glyph takes is the icon tool's component's business: the icon tool's component declares its own `size` and `variant` props, and every surface reads those. TODO: remove with a migration once no surface reads the library's copy. */
-		variants: z.array(z.string()).optional(),
+		variants: z.array(z.string()).optional().describe("Deprecated. The icon tool's component declares its own `size` and `variant` props."),
 		/** How a variant reaches the glyph; see {@link iconVariantAs}. Absent, a variant is dropped at
 		*  render.
 		*  @deprecated Only the framework's raw-draw path read it; the icon tool's component passes a
 		*  variant the way its package wants, and a set whose styles are separate exports lists them as
 		*  members. TODO: remove with `sizes` and `variants`. */
-		variantAs: iconVariantAs.optional()
+		variantAs: iconVariantAs.optional().describe("Deprecated. The icon tool's component passes a variant the way its package wants.")
 	}),
 	groupComputed: {
 		/** The glyphs the set ships, by leaf name. */

package/dist/entities/system/LinkedSystem.js

@@ -246,7 +246,7 @@ const pinOptions = z.record(z.string(), z.record(z.string(), z.strictObject({
 	override: 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();
+}).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.");
 const LinkedSystemDefinition = defineEntity({
 	kind: "linked-system",
 	label: "Linked system",
@@ -503,7 +503,7 @@ const LinkedSystemDefinition = defineEntity({
 		* ignores `version`: a repo-local link tracks whatever the sibling currently is, which is the point
 		* in a monorepo, and a built artifact carries no `systemId` or `version` to pin against.
 		*/
-		configPath: z.string().min(1).optional(),
+		configPath: z.string().min(1).optional().describe("The sibling config this link reads, as a path to its `uds.config.ts`. Wins for resolution when set."),
 		/**
 		* What this system draws from that source — a standing declaration, and the thing the build turns
 		* into rows.
@@ -544,7 +544,7 @@ const LinkedSystemDefinition = defineEntity({
 		* kind says which it is (`EntityKind.linkable`). Nothing is subtracted: a pin and a `file` aren't
 		* borrowable, so no borrow of one exists for this to cover.
 		*/
-		link: z.union([z.literal("*"), z.record(z.string(), z.union([z.literal("*"), z.array(z.string().min(1)).min(1)]))]).optional(),
+		link: z.union([z.literal("*"), z.record(z.string(), z.union([z.literal("*"), z.array(z.string().min(1)).min(1)]))]).optional().describe("What this system draws from the source, standing: `'*'` for everything, or a record by kind."),
 		/**
 		* What this system does to individual entities of the source, keyed by accessor, then by the path
 		* the source spells, then by verb.
@@ -604,7 +604,7 @@ const LinkedSystemDefinition = defineEntity({
 		* and the lockfile already decide it, so a second copy here would be a version nobody resolves
 		* against. `version` stays observed for this origin, as it is for a sibling.
 		*/
-		package: z.string().min(1).optional(),
+		package: z.string().min(1).optional().describe("An npm package that ships a built system."),
 		/**
 		* The source's database id — durable identity, which survives a rename on their side.
 		*
@@ -613,9 +613,9 @@ const LinkedSystemDefinition = defineEntity({
 		* So push derives it for a `configPath` link and writes it into the artifact, and nothing local asks
 		* an author to hand-type an unverifiable id.
 		*/
-		systemId: z.string().min(1).optional(),
+		systemId: z.string().min(1).optional().describe("The source's durable id in Create. Push fills it for a repo-local link."),
 		/** Display only, never identity: what to call this source in the UI. Defaults to the slug. */
-		name: z.string().optional(),
+		name: z.string().optional().describe("Display only. Defaults to the slug."),
 		/**
 		* The exact published version every ref through this link resolves against.
 		*
@@ -623,7 +623,7 @@ const LinkedSystemDefinition = defineEntity({
 		* at push time so Studio can say which version it saw, and the local build still tracks current
 		* state. Read as a pin, a repo-local link would go stale the moment the sibling moved.
 		*/
-		version: z.string().regex(EXACT_VERSION, "A link is pinned to an exact version (2.4.0), not a range").optional()
+		version: z.string().regex(EXACT_VERSION, "A link is pinned to an exact version (2.4.0), not a range").optional().describe("An exact version (`2.4.0`), never a range.")
 	}),
 	computed: { 
 	/**

package/dist/entities/system/Modifier.js

@@ -29,14 +29,14 @@ const modifierRef = refTo("modifier");
 * is the base values and no option is default.
 */
 const modifierGroupFields = z.object({
-	type: z.enum(MODIFIER_CATEGORIES).optional(),
-	default: modifierRef.optional()
+	type: z.enum(MODIFIER_CATEGORIES).optional().describe("Makes the group a mode or a state axis. A group with no type is a plain folder."),
+	default: modifierRef.optional().describe("The option a viewer starts in. The native theme reads it.")
 });
 const Modifier = defineEntity({
 	kind: "modifier",
 	fields: z.object({
-		type: z.enum(WEB_ACTIVATIONS),
-		value: z.union([z.string(), z.lazy(() => Composite)])
+		type: z.enum(WEB_ACTIVATIONS).describe("How the modifier activates, such as `selector` or `media`."),
+		value: z.union([z.string(), z.lazy(() => Composite)]).describe("The selector or query it activates on, or a composite ref.")
 	}).check((ctx) => {
 		const { type, value } = ctx.value;
 		const wantsRef = type === "composite";

package/dist/entities/system/Motion.js

@@ -15,28 +15,29 @@ import { z } from "zod";
 * lost `whileHover`/`whileTap`/`drag` on the way in and animated nothing.
 */
 const gesture = z.record(z.string(), z.unknown()).optional();
+const RUNTIME = "Which runtime plays the preset, and so which fields apply.";
 const CssMotion = z.strictObject({
-	runtime: z.literal("css"),
-	keyframes: z.record(z.string(), z.record(z.string(), z.unknown())),
-	duration: z.string().optional(),
-	delay: z.string().optional(),
-	timingFunction: z.string().optional(),
-	iterationCount: z.union([z.string(), z.number()]).optional(),
-	direction: z.string().optional(),
-	fillMode: z.string().optional()
+	runtime: z.literal("css").describe(RUNTIME),
+	keyframes: z.record(z.string(), z.record(z.string(), z.unknown())).describe("The CSS keyframes, keyed by offset (`from`, `50%`, `to`)."),
+	duration: z.string().optional().describe("The CSS `animation-duration`, such as `'4s'`."),
+	delay: z.string().optional().describe("The CSS `animation-delay`."),
+	timingFunction: z.string().optional().describe("The CSS `animation-timing-function`."),
+	iterationCount: z.union([z.string(), z.number()]).optional().describe("The CSS `animation-iteration-count`, or `'infinite'`."),
+	direction: z.string().optional().describe("The CSS `animation-direction`."),
+	fillMode: z.string().optional().describe("The CSS `animation-fill-mode`.")
 });
 const JsMotion = z.strictObject({
-	runtime: z.literal("js"),
-	initial: gesture,
-	animate: gesture,
-	transition: gesture,
-	whileHover: gesture,
-	whileTap: gesture,
-	whileFocus: gesture,
-	whileDrag: gesture,
-	drag: z.union([z.boolean(), z.string()]).optional(),
-	dragConstraints: z.record(z.string(), z.number()).optional(),
-	dragElastic: z.number().optional()
+	runtime: z.literal("js").describe(RUNTIME),
+	initial: gesture.describe("The starting values, as `motion/react` reads them."),
+	animate: gesture.describe("The values to animate to."),
+	transition: gesture.describe("How the animation moves, such as a spring."),
+	whileHover: gesture.describe("Values held while the element is hovered."),
+	whileTap: gesture.describe("Values held while the element is pressed."),
+	whileFocus: gesture.describe("Values held while the element has focus."),
+	whileDrag: gesture.describe("Values held while the element is dragged."),
+	drag: z.union([z.boolean(), z.string()]).optional().describe("Whether, and along which axis, the element can be dragged."),
+	dragConstraints: z.record(z.string(), z.number()).optional().describe("The box a drag stays within."),
+	dragElastic: z.number().optional().describe("How far past its constraints a drag can stretch.")
 });
 const Motion = defineEntity({
 	kind: "motion",

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

@@ -48,9 +48,10 @@ interface PackageExportClass extends Named<typeof PackageExportDefinition> {}
  * makes the portable config the source of truth for consumer install requirements.
  *
  * Ordinary component authoring does not maintain this graph: the build derives modules and exports
- * from the source it walked. A human may still author one — to carry a label, or to pin a `version` —
- * and build collection updates rather than replaces it, so that metadata survives. What authoring
- * cannot do is choose the path.
+ * from the source it walked. A human may still author one, to carry a label or a description, and
+ * build collection updates rather than replaces it, so that metadata survives. `version` is always
+ * the installed package's, which the build writes over an authored one. What authoring cannot do is
+ * choose the path.
  */
 declare const PackageDefinition: EntityClass<z.ZodObject<{
   version: z.ZodOptional<z.ZodString>;

package/dist/entities/system/Package.js

@@ -18,10 +18,10 @@ const Package = defineEntity({
 	fields: z.strictObject({
 		/** Pinned at build from the package's own `package.json`, like an icon library's already is.
 		*  Read from the PACKAGE (`motion`), since that is what has a manifest — a subpath has none. */
-		version: z.string().optional(),
+		version: z.string().optional().describe("The pinned version, read at build from the package's manifest."),
 		/** The exports a render placed in JSX. Absent for a module nothing names by export: a runtime
 		*  dependency, or a catalogue read for its data. */
-		exports: PackageExport.optional()
+		exports: PackageExport.optional().describe("The exports a render placed in JSX, each keyed by the name the target spells (`View`, `default`, `Animated.View`).")
 	}),
 	subEntities: { exports: PackageExport }
 });

package/dist/entities/system/StyleProperty.js

@@ -368,7 +368,7 @@ const styleFields = ({ config, body, linked } = {}) => z.object({
 		body,
 		linked
 	}).optional().describe("What the prop accepts. A ref to a token GROUP (`{ \"__ref\": \"token:color\" }`) makes every member a value, named by its path under the group, and is how a prop takes tokens; a string or number is a keyword; `{ \"alias\": \"full\", \"value\": \"9999px\" }` names a literal; `{ \"alias\": \"brand\", \"value\": { \"__ref\": \"token:color/green\" } }` names one token under another name. One group ref usually replaces listing tokens one by one."),
-	responsive: z.boolean().default(false),
+	responsive: z.boolean().default(false).describe("Whether the prop takes responsive values. Defaults to `false`."),
 	/**
 	* The class-name segment this prop contributes — `borderStyle` emits `.uds-border-style-solid`,
 	* and a prop whose values are already self-describing sets `''` so `position: absolute` emits
@@ -378,8 +378,8 @@ const styleFields = ({ config, body, linked } = {}) => z.object({
 	* decision, and the same decision decides the class a consumer's markup already ships. Defaults
 	* to the prop's own path, which is the common case.
 	*/
-	classPrefix: z.string().optional(),
-	arbitrary: z.boolean().default(false),
+	classPrefix: z.string().optional().describe("The class-name segment the prop contributes. Defaults to the prop's own path; `''` for self-describing values."),
+	arbitrary: z.boolean().default(false).describe("Whether the prop also accepts a bracketed literal such as `[13px]`. Defaults to `false`."),
 	/**
 	* The prop applies the NEGATION of its value — `offsetX="3"` paints `margin-inline: calc(var(…) *
 	* -1)`.
@@ -395,7 +395,7 @@ const styleFields = ({ config, body, linked } = {}) => z.object({
 	* name conventionally spells it (`-mx`), but a name is not a rule — reading the leading dash as
 	* one would make a rename silently change what a prop paints.
 	*/
-	negates: z.boolean().default(false),
+	negates: z.boolean().default(false).describe("Apply the negation of the value, so one scale works in both directions. Defaults to `false`."),
 	/**
 	* The style prop whose alpha this one controls — `bgOpacity` is the opacity of `bg`.
 	*
@@ -409,7 +409,7 @@ const styleFields = ({ config, body, linked } = {}) => z.object({
 	* instead of an implied name. Such a prop sets no CSS property of its own, hence an empty
 	* `properties`: it modulates its target rather than declaring anything.
 	*/
-	opacityOf: z.lazy(() => StyleProperty).optional()
+	opacityOf: z.lazy(() => StyleProperty).optional().describe("The style property whose alpha this one controls, as `bgOpacity` does for `bg`.")
 });
 /** `path` if no style property holds it, else the first free numbered variant of it. */
 function freePath(config, path) {

package/dist/entities/system/Token.js

@@ -117,11 +117,11 @@ const Override = defineOverride(tokenValue);
 const TokenEntity = defineEntity({
 	kind: "token",
 	fields: z.object({
-		value: tokenValue,
-		type: z.string().optional(),
-		overrides: Override.optional()
+		value: tokenValue.describe("The base value: a literal, a ref to another token, or a composed value such as a gradient."),
+		type: z.string().optional().describe("The CSS value type, when the value alone does not say it."),
+		overrides: Override.optional().describe("Per-mode values, keyed by the condition they apply under.")
 	}),
-	groupFields: z.object({ cssPrefix: z.string().optional() }),
+	groupFields: z.object({ cssPrefix: z.string().optional().describe("The prefix the group emits its custom properties under. Local to the config that holds the group.") }),
 	localGroupFields: ["cssPrefix"],
 	subEntities: { overrides: Override },
 	schemas: { create: { description: `Create a token at \`<group>/<name>\` — \`data.value\` is the CSS value. The first path segment is its group, and a style property takes a whole group as one ref (\`${JSON.stringify(ref("token", "<group>"))}\`), so put the tokens one prop should offer in one group rather than listing values on the prop.` } }

package/dist/entities/system/icon-metadata.js

@@ -28,20 +28,20 @@ const iconMemberMetadata = z.strictObject({
 	/** Grouping, PLURAL — every real catalogue lets a glyph belong to several (most of Phosphor's
 	*  do), or none. Stored RAW as the source spells them (`'health & wellness'`); casing and
 	*  which one a section heading shows are display policy, not stored facts. */
-	categories: z.array(z.string().min(1)).optional(),
+	categories: z.array(z.string().min(1)).optional().describe("Groupings, stored as the catalogue spells them. A glyph can be in several."),
 	/** Search terms beyond the name. Order carries no meaning; a reorder is not an edit. */
-	tags: z.array(z.string()).optional(),
+	tags: z.array(z.string()).optional().describe("Search terms beyond the name."),
 	/** The glyph's code point in a font-backed set — what a native glyphmap reads. */
-	codepoint: z.number().optional(),
+	codepoint: z.number().optional().describe("The code point in a font-backed set."),
 	/** The subset of the set's `variants` this glyph ships, for a ragged set (Tabler draws `filled`
 	*  for a third of its glyphs). Absent means every variant the set declares. */
-	variants: z.array(z.string().min(1)).optional(),
+	variants: z.array(z.string().min(1)).optional().describe("The styles this glyph ships, for a set where not every glyph has every style."),
 	/** Variants whose glyph paints a literal white fill by design (a "knockout" meant for dark or
 	*  branded surfaces) rather than `currentColor`. Such a glyph is invisible on a light surface,
 	*  so pickers and catalogs preview these variants on a dark one. Rendering is untouched — the
 	*  field is presentation advice for browsing UIs, and member-owned like the set's `variants`:
 	*  only a source that knows its own knockouts can flag them. */
-	knockoutVariants: z.array(z.string().min(1)).optional()
+	knockoutVariants: z.array(z.string().min(1)).optional().describe("Styles that paint a literal white fill, which pickers preview on a dark surface.")
 });
 /**
 * The `metadata` group field: where a set's member facts come from (`from`, a ref to the source's

package/dist/framework/utils/field-schema.js

@@ -66,8 +66,13 @@ function partializeShape(shape, keep) {
 			continue;
 		}
 		let inner = field;
-		while (inner instanceof z.ZodOptional || inner instanceof z.ZodDefault) inner = inner.unwrap();
-		out[key] = inner.nullable().optional();
+		let description = inner.description;
+		while (inner instanceof z.ZodOptional || inner instanceof z.ZodDefault) {
+			inner = inner.unwrap();
+			description ??= inner.description;
+		}
+		const delta = inner.nullable().optional();
+		out[key] = description ? delta.describe(description) : delta;
 	}
 	return out;
 }