@yahoo/uds-create-config 5.53.1 → 5.55.0

package/dist/capture/node-ops.js

@@ -1,5 +1,5 @@
-import { rejectData } from "../framework/rejection.js";
 import { pathOf } from "../framework/utils/refs.js";
+import { rejectData } from "../framework/rejection.js";
 import { pathInput } from "../framework/schemas.js";
 import { CapturedNode } from "./captured-tree.js";
 import { specFromCapture } from "./capture-to-spec.js";

package/dist/configs/system.js

@@ -29,6 +29,7 @@ import { lintSettingsMigration } from "../migrations/20261020183330_lint_setting
 import { directLayerCompositesMigration } from "../migrations/20261022124223_direct_layer_composites.js";
 import { cssContentScriptsMigration } from "../migrations/20261022152120_css_content_scripts.js";
 import { linkTypeMigration } from "../migrations/20261022184639_link_type.js";
+import { conditionalDefaultsMigration } from "../migrations/20261023152030_conditional_defaults.js";
 import { CanvasRole } from "../entities/system/CanvasRole.js";
 import { GlobalStyle } from "../entities/system/GlobalStyle.js";
 import { Guidance } from "../entities/system/Guidance.js";
@@ -191,5 +192,6 @@ if (!registeredSchemaMigrations().has(20261020183330)) {
 }
 if (!registeredSchemaMigrations().has(20261022152120)) registerSchemaMigrations(cssContentScriptsMigration);
 if (!registeredSchemaMigrations().has(20261022184639)) registerSchemaMigrations(linkTypeMigration);
+if (!registeredSchemaMigrations().has(20261023152030)) registerSchemaMigrations(conditionalDefaultsMigration);
 //#endregion
 export { System };

package/dist/entities/canvas/node-gestures.js

@@ -1,5 +1,5 @@
-import { rejectData } from "../../framework/rejection.js";
 import { pathOf, ref } from "../../framework/utils/refs.js";
+import { rejectData } from "../../framework/rejection.js";
 import { pathInput } from "../../framework/schemas.js";
 import { childrenPolicy } from "../system/element.js";
 import { surfaceProps } from "../../framework/prop-surface.js";

package/dist/entities/canvas/node-patches.js

@@ -1,5 +1,5 @@
-import { rejectData } from "../../framework/rejection.js";
 import { ref } from "../../framework/utils/refs.js";
+import { rejectData } from "../../framework/rejection.js";
 //#region src/entities/canvas/node-patches.ts
 /**
 * A spec as the node rows of one new placed node. A placed node's content is its subtree rows, one

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

@@ -9,10 +9,11 @@ import { Named } from "../../framework/named.js";
 import { PackageClass } from "./Package.js";
 import { StyleClass } from "./style-bag.js";
 import { TokenClass } from "./Token.js";
+import { StoredDefaultCondition } from "../../framework/default-conditions.js";
 import { StoredPreviewCondition } from "../../framework/preview-store.js";
 import { RepeatSpec } from "../../framework/render-spec.js";
 import { ComponentSourceInput } from "./component-source-fields.js";
-import { AsInput, DefaultsOf, LayerMap, PhantomCallProps, PhantomReadProps, PropMap, RenderArgs, StateMap, StyleRuleInput } from "./defineComponent.js";
+import { AsInput, AuthoredDefaultsOf, LayerMap, PhantomCallProps, PhantomReadProps, PropMap, RenderArgs, StateMap, StyleRuleInput } from "./defineComponent.js";
 import { listSlots, namedSlots, slotHostedBy, slotOf, slotsFor } from "../../spec/slot.js";
 import { cellAt } from "../../spec/cell.js";
 import { instanceAt } from "../../spec/instance.js";
@@ -658,6 +659,7 @@ declare const componentFields: z.ZodObject<{
   renderProps: z.ZodOptional<z.ZodArray<z.ZodString>>;
   anatomy: z.ZodOptional<AnatomyNodeClass>;
   defaultProps: z.ZodOptional<StyleClass>;
+  defaultPropsWhen: z.ZodOptional<z.ZodUnion<readonly [z.ZodPipe<z.ZodArray<z.ZodType<StoredDefaultCondition, unknown, z.core.$ZodTypeInternals<StoredDefaultCondition, unknown>>>, z.ZodTransform<Record<string, StoredDefaultCondition>, StoredDefaultCondition[]>>, SubEntityClass<z.ZodType<StoredDefaultCondition, unknown, z.core.$ZodTypeInternals<StoredDefaultCondition, unknown>>>]>>;
   preview: z.ZodOptional<z.ZodUnion<readonly [z.ZodPipe<z.ZodArray<z.ZodType<StoredPreviewCondition, unknown, z.core.$ZodTypeInternals<StoredPreviewCondition, unknown>>>, z.ZodTransform<Record<string, StoredPreviewCondition>, StoredPreviewCondition[]>>, SubEntityClass<z.ZodType<StoredPreviewCondition, unknown, z.core.$ZodTypeInternals<StoredPreviewCondition, unknown>>>]>>;
   file: z.ZodOptional<z.ZodObject<{
     __ref: z.ZodString;
@@ -699,6 +701,7 @@ declare const ComponentEntity: EntityClass<z.ZodObject<{
   renderProps: z.ZodOptional<z.ZodArray<z.ZodString>>;
   anatomy: z.ZodOptional<AnatomyNodeClass>;
   defaultProps: z.ZodOptional<StyleClass>;
+  defaultPropsWhen: z.ZodOptional<z.ZodUnion<readonly [z.ZodPipe<z.ZodArray<z.ZodType<StoredDefaultCondition, unknown, z.core.$ZodTypeInternals<StoredDefaultCondition, unknown>>>, z.ZodTransform<Record<string, StoredDefaultCondition>, StoredDefaultCondition[]>>, SubEntityClass<z.ZodType<StoredDefaultCondition, unknown, z.core.$ZodTypeInternals<StoredDefaultCondition, unknown>>>]>>;
   preview: z.ZodOptional<z.ZodUnion<readonly [z.ZodPipe<z.ZodArray<z.ZodType<StoredPreviewCondition, unknown, z.core.$ZodTypeInternals<StoredPreviewCondition, unknown>>>, z.ZodTransform<Record<string, StoredPreviewCondition>, StoredPreviewCondition[]>>, SubEntityClass<z.ZodType<StoredPreviewCondition, unknown, z.core.$ZodTypeInternals<StoredPreviewCondition, unknown>>>]>>;
   file: z.ZodOptional<z.ZodObject<{
     __ref: z.ZodString;
@@ -954,7 +957,7 @@ type ComponentReference<Contract = ComponentContractOf<string>, Path extends str
 /** An extension's `defaultProps`, checked against the props it ends up with the way
  *  `defineComponent` checks its own: a declared prop takes its values, and any other key stays open. */
 type ExtensionDefaults<Contract, Delta> = {
-  readonly defaultProps?: DefaultsOf<ResolvedProps<Contract, Delta>>;
+  readonly defaultProps?: AuthoredDefaultsOf<ResolvedProps<Contract, Delta>>;
 };
 /**
  * Two style rules with the same condition, as the one rule they are: each layer's bag merged, the

package/dist/entities/system/Component.js

@@ -1,7 +1,8 @@
 import "../../configs/platform.js";
-import { reject, rejectData } from "../../framework/rejection.js";
-import { canonicalCondition, collectRefs, isRef, kindOf, memberRef, pathOf, ref, refLeaf, refSchema, sourceOf, splitRef } from "../../framework/utils/refs.js";
 import { isPlainObject } from "../../framework/utils/field-path.js";
+import { canonicalCondition, collectRefs, isRef, kindOf, memberRef, pathOf, ref, refLeaf, refSchema, sourceOf, splitRef } from "../../framework/utils/refs.js";
+import { storedDefaultConditions } from "../../framework/default-conditions.js";
+import { reject, rejectData } from "../../framework/rejection.js";
 import { pathInput } from "../../framework/schemas.js";
 import { derivedColor, gradient, oklchColor } from "./color.js";
 import { shadowValue } from "./shadow.js";
@@ -26,6 +27,7 @@ import { instanceAt } from "../../spec/instance.js";
 import { forwardOptions, forwardsWrite } from "./component-forwards.js";
 import { assertComponentSourceInput } from "./component-source-fields.js";
 import { checkStyleSet, styleSetEdits } from "./component-style-set.js";
+import { storedDefaults } from "./conditional-defaults.js";
 import { forwardRouteInvariants, refusedRoutes } from "./forward-route-invariants.js";
 import { iconDomainInvariants } from "./icon-domain-invariants.js";
 import { rootLayerInvariants } from "./root-layer-invariants.js";
@@ -346,8 +348,16 @@ const VariantValue = defineSubEntity({
 		*  which takes its styling with it. */
 		deprecated: z.boolean().optional()
 	}),
-	namedValuesIn: ["defaultProps", "preview/*/props"],
-	orphans: ["styles", "preview"]
+	namedValuesIn: [
+		"defaultProps",
+		"preview/*/props",
+		"defaultPropsWhen/*/props"
+	],
+	orphans: [
+		"styles",
+		"preview",
+		"defaultPropsWhen"
+	]
 });
 /**
 * A variant's domain: the values it owns, a ref that delegates to whatever owns them, or a list of
@@ -557,8 +567,16 @@ const Prop = defineSubEntity({
 	namespaces: "value",
 	namesMembersOf: { when: "props" },
 	subEntities: { value: VariantValue },
-	keyedByNameIn: ["defaultProps", "preview/*/props"],
-	orphans: ["styles", "preview"]
+	keyedByNameIn: [
+		"defaultProps",
+		"preview/*/props",
+		"defaultPropsWhen/*/props"
+	],
+	orphans: [
+		"styles",
+		"preview",
+		"defaultPropsWhen"
+	]
 });
 /** {@link Prop}'s per-owner schema. Reached only through the memo in its `fields`. */
 function propSchemaFor(config, owner) {
@@ -1168,6 +1186,61 @@ const Preview = defineSubEntity({
 		});
 	}
 });
+const DEFAULT_CONDITIONS_DESCRIPTION = "Defaults that hold only under a condition on this component's other props, laid over `defaultProps` the way a style rule is over the unconditional one: a list of entries, each identified by its condition. `{ \"when\": { \"modal\": false }, \"props\": { \"includeScrim\": false } }` defaults `includeScrim` to `false` while `modal` is `false`, and to its `defaultProps` value otherwise. When several entries hold, the later one wins on the prop it sets. Both sides name the component's own variant, string, number or boolean props, a prop set here is never part of a condition, and a value the call site passes always wins. Authored as `conditionalDefault(fallback, [{ when, value }])` inside `.defaultProps`.";
+const defaultConditionShapeError = "a conditional default is `{ \"when\": { \"<prop>\": <value> }, \"props\": { \"<prop>\": <value> } }`: both name this component's own variant, string, number or boolean props (not `as`), `when` at one of their values.";
+const defaultConditionBase = z.object({
+	when: z.record(z.string(), z.unknown()),
+	props: z.record(z.string(), z.unknown())
+});
+const defaultConditionSchemas = /* @__PURE__ */ new WeakMap();
+/** The props a conditional default may set or condition on: the component's own scalar props, the
+*  ones its module binds and tests. `as` decides the element, so it never depends on another prop. */
+function conditionallyDefaultable(props) {
+	return Object.entries(props ?? {}).filter(([name, decl]) => {
+		const type = decl?.type;
+		return name !== "as" && (type === "variant" || type === "string" || type === "number" || type === "boolean");
+	});
+}
+/** Whether a conditional default sets nothing: its `props` are empty. */
+function defaultConditionSetsNothing(entry) {
+	const props = entry?.props;
+	return !props || Object.keys(props).length === 0;
+}
+const DefaultCondition = defineSubEntity({
+	name: "defaultCondition",
+	label: "Conditional default",
+	labelPlural: "Conditional defaults",
+	key: (entry) => canonicalWhen(entry?.when),
+	vacant: defaultConditionSetsNothing,
+	namesMembersOf: { when: "props" },
+	base: defaultConditionBase,
+	fields: ({ config, parent }) => {
+		const body = parent;
+		if (!config || !body) return defaultConditionBase;
+		return perOwner({
+			cache: defaultConditionSchemas,
+			config,
+			owner: body,
+			build: () => {
+				const styleField = Style.fields;
+				const when = {};
+				const props = {};
+				for (const [name, decl] of conditionallyDefaultable(body.props)) {
+					when[name] = conditionValue(name, decl, config).optional();
+					props[name] = styleField({
+						config,
+						parent: body,
+						key: name
+					}).optional();
+				}
+				return z.strictObject({
+					when: z.strictObject(when, { error: defaultConditionShapeError }).refine((value) => Object.keys(value).length > 0, { error: "a conditional default holds under a condition; an unconditional one belongs in `defaultProps`." }),
+					props: z.strictObject(props, { error: defaultConditionShapeError })
+				}, { error: defaultConditionShapeError });
+			}
+		});
+	}
+});
 /** Why a slot refuses an element, for a write the config turns away. */
 function slotRefusal({ slot, element }) {
 	const named = isRef(element) ? element.__ref : String(element);
@@ -1724,6 +1797,9 @@ const componentFields = z.strictObject({
 	renderProps: z.array(z.string()).optional().describe("Props the render reads beyond those declared, read off the source at build. Not authored: declare a prop in `props` instead."),
 	anatomy: AnatomyNode.optional().describe("The tree of what this component renders, keyed by node. Each node names what it renders (a layer, for anything a style rule reaches) and lists its `children`; the node keyed `root` is the top. A one-layer component may omit it. Anatomy read from an extension's own source file replaces the inherited tree; edits to a borrowed render merge into its tree."),
 	defaultProps: Style.optional(),
+	/** The defaults that hold only under a condition on the component's other props — see
+	*  `conditionalDefault`. */
+	defaultPropsWhen: orList(DefaultCondition).optional().describe(DEFAULT_CONDITIONS_DESCRIPTION),
 	/** What the tile and the matrix render with — see `preview({ defaultProps, when })`. Read off
 	*  `.preview()` at build, and written per cell from the matrix. */
 	preview: orList(Preview).optional().describe(PREVIEW_DESCRIPTION),
@@ -1769,6 +1845,39 @@ const componentFields = z.strictObject({
 			message: `\`${name}\` conditions on itself. \`when\` names a sibling prop and one of its values.`
 		});
 	}
+	const conditions = storedDefaultConditions(body);
+	const defaulted = new Set(Object.values(conditions).flatMap(({ props }) => Object.keys(props ?? {})));
+	const defaultable = new Set(conditionallyDefaultable(body.props).map(([name]) => name));
+	for (const [key, { when, props }] of Object.entries(conditions)) {
+		for (const [field, names] of [["when", Object.keys(when ?? {})], ["props", Object.keys(props ?? {})]]) for (const name of names) {
+			if (defaultable.has(name)) continue;
+			ctx.issues.push({
+				code: "custom",
+				input: field === "when" ? when : props,
+				path: [
+					"defaultPropsWhen",
+					key,
+					field,
+					name
+				],
+				message: `\`${name}\` isn't one of this component's own variant, string, number or boolean props, so a conditional default can't name it. ${defaultConditionShapeError}`
+			});
+		}
+		for (const name of Object.keys(when ?? {})) {
+			if (!defaulted.has(name)) continue;
+			ctx.issues.push({
+				code: "custom",
+				input: when,
+				path: [
+					"defaultPropsWhen",
+					key,
+					"when",
+					name
+				],
+				message: `\`${name}\` has a conditional default of its own, so it can't be part of a condition. Condition on the props it depends on instead.`
+			});
+		}
+	}
 	if (isPlainObject(body.states) && Object.keys(body.states).length > 0) {
 		const props = isPlainObject(body.props) ? body.props : {};
 		if (Object.hasOwn(props, "states")) ctx.issues.push({
@@ -1905,7 +2014,8 @@ const ComponentEntity = defineEntity({
 		styles: StyleRule,
 		preview: Preview,
 		anatomy: AnatomyNode,
-		defaultProps: Style
+		defaultProps: Style,
+		defaultPropsWhen: DefaultCondition
 	},
 	computed: {
 		/**
@@ -2846,7 +2956,10 @@ function componentRef(path) {
 	*/
 	const step = (delta) => {
 		assertComponentSourceInput(delta);
-		const extended = base.extend(delta);
+		const extended = base.extend({
+			...delta,
+			...storedDefaults(delta)
+		});
 		Object.defineProperty(extended, "render", {
 			enumerable: false,
 			configurable: false,

package/dist/entities/system/LinkedSystem.js

@@ -1,6 +1,6 @@
-import { rejectData } from "../../framework/rejection.js";
-import { isRef, kindOf, pathOf, refSchema } from "../../framework/utils/refs.js";
 import { isPlainObject } from "../../framework/utils/field-path.js";
+import { isRef, kindOf, pathOf, refSchema } from "../../framework/utils/refs.js";
+import { rejectData } from "../../framework/rejection.js";
 import { pathInput } from "../../framework/schemas.js";
 import { kindBorrowable } from "../../framework/registry.js";
 import { defineEntity } from "../../framework/defineEntity.js";

package/dist/entities/system/Operation.js

@@ -1,5 +1,5 @@
-import { CONFIG_OPERATION_KIND } from "../../framework/config-operation-kind.js";
 import { isPlainObject } from "../../framework/utils/field-path.js";
+import { CONFIG_OPERATION_KIND } from "../../framework/config-operation-kind.js";
 import { resolveInputSchema } from "../../framework/schemas.js";
 import { opsForKind } from "../../framework/registry.js";
 import { opOf } from "../../framework/config-op.js";

package/dist/entities/system/StyleProperty.js

@@ -158,6 +158,10 @@ const STYLE_PROP_VALUE_FORMS = {
 	})
 };
 const KINDS = Object.keys(STYLE_PROP_VALUE_FORMS);
+const CONTEXT_FREE_VALUE_FORMS = KINDS.map((kind) => ({
+	kind,
+	schema: STYLE_PROP_VALUE_FORMS[kind]()
+}));
 /** `{ numeric: true }` for an alias declared as a number. */
 function numericOf(alias) {
 	return typeof alias === "number" ? { numeric: true } : {};
@@ -262,6 +266,7 @@ function stylePropValueSchema(ctx = {}) {
 /** The form a stored entry is, or `undefined` for a value no form admits. With a config, a ref is
 *  `token` or `tokenGroup` as the config says; without one it reads as `token`. */
 function stylePropValueFormOf(entry, ctx = {}) {
+	if (ctx.config === void 0 && ctx.properties === void 0) return CONTEXT_FREE_VALUE_FORMS.find(({ schema }) => schema.safeParse(entry).success)?.kind;
 	return KINDS.find((kind) => STYLE_PROP_VALUE_FORMS[kind](ctx).safeParse(entry).success);
 }
 /** Which form a stored entry is, asked of the config that holds it. */

package/dist/entities/system/component-forwards.js

@@ -1,5 +1,5 @@
-import { reject } from "../../framework/rejection.js";
 import { isRef, kindOf, memberRef, pathOf } from "../../framework/utils/refs.js";
+import { reject } from "../../framework/rejection.js";
 import { forwardedPropName } from "./element.js";
 import { propOwner, resolveComponentProps } from "../../framework/projections.js";
 import { forwardClaims } from "../../framework/prop-surface.js";

package/dist/entities/system/component-source-fields.js

@@ -1,5 +1,5 @@
-import { rejectData } from "../../framework/rejection.js";
 import { isPlainObject } from "../../framework/utils/field-path.js";
+import { rejectData } from "../../framework/rejection.js";
 //#region src/entities/system/component-source-fields.ts
 /** Source constructors leave these facts to the render extractor and module build.
 * Stored component bodies, including Create drafts, still carry them. */

package/dist/entities/system/component-style-set.js

@@ -1,5 +1,5 @@
-import { reject } from "../../framework/rejection.js";
 import { canonicalCondition } from "../../framework/utils/refs.js";
+import { reject } from "../../framework/rejection.js";
 //#region src/entities/system/component-style-set.ts
 /** A modifier as a style bag keys it: its leaf with a leading `_`. */
 function bagKey(modifier) {

package/dist/entities/system/conditional-defaults.d.ts

@@ -0,0 +1,45 @@
+import { StoredDefaultCondition } from "../../framework/default-conditions.js";
+
+//#region src/entities/system/conditional-defaults.d.ts
+declare const CONDITIONAL_DEFAULT: unique symbol;
+/** One condition of a {@link ConditionalDefault}: the value the prop defaults to while `when` holds. */
+interface ConditionalDefaultEntry<V = unknown> {
+  readonly when: Readonly<Record<string, unknown>>;
+  readonly value: V;
+}
+/** A default chosen by the component's other props — see {@link conditionalDefault}. */
+interface ConditionalDefault<V = unknown> {
+  readonly [CONDITIONAL_DEFAULT]: true;
+  readonly fallback: V;
+  readonly entries: readonly ConditionalDefaultEntry<V>[];
+}
+/**
+ * A default that depends on the component's other props, for `.defaultProps` and
+ * `.extend({ defaultProps })` only.
+ *
+ * ```ts
+ * .defaultProps({
+ *   modal: true,
+ *   includeScrim: conditionalDefault(true, [{ when: { modal: false }, value: false }]),
+ * })
+ * ```
+ *
+ * `fallback` applies when no entry's `when` holds; when several hold, the later entry wins. A `when`
+ * is the grammar a style rule uses, over the component's own props. A value the call site passes
+ * still wins over any of it.
+ */
+declare function conditionalDefault<const V>(fallback: V, entries: readonly ConditionalDefaultEntry<V>[]): ConditionalDefault<V>;
+declare function isConditionalDefault(value: unknown): value is ConditionalDefault;
+/**
+ * Stored defaults as authored: the inverse of {@link splitConditionalDefaults}, each prop
+ * `defaultPropsWhen` names given back as a {@link conditionalDefault} over its fallback.
+ */
+declare function joinConditionalDefaults({
+  defaultProps,
+  defaultPropsWhen
+}: {
+  defaultProps: Readonly<Record<string, unknown>> | undefined;
+  defaultPropsWhen: Readonly<Record<string, StoredDefaultCondition>> | undefined;
+}): Record<string, unknown>;
+//#endregion
+export { ConditionalDefault, ConditionalDefaultEntry, conditionalDefault, isConditionalDefault, joinConditionalDefaults };

package/dist/entities/system/conditional-defaults.js

@@ -0,0 +1,142 @@
+import { isPlainObject } from "../../framework/utils/field-path.js";
+import { canonicalCondition } from "../../framework/utils/refs.js";
+//#region src/entities/system/conditional-defaults.ts
+const CONDITIONAL_DEFAULT = Symbol.for("uds.conditionalDefault");
+/**
+* A default that depends on the component's other props, for `.defaultProps` and
+* `.extend({ defaultProps })` only.
+*
+* ```ts
+* .defaultProps({
+*   modal: true,
+*   includeScrim: conditionalDefault(true, [{ when: { modal: false }, value: false }]),
+* })
+* ```
+*
+* `fallback` applies when no entry's `when` holds; when several hold, the later entry wins. A `when`
+* is the grammar a style rule uses, over the component's own props. A value the call site passes
+* still wins over any of it.
+*/
+function conditionalDefault(fallback, entries) {
+	return {
+		[CONDITIONAL_DEFAULT]: true,
+		fallback,
+		entries
+	};
+}
+function isConditionalDefault(value) {
+	return typeof value === "object" && value !== null && value[CONDITIONAL_DEFAULT] === true;
+}
+/**
+* Authored defaults as stored: each {@link conditionalDefault} leaves its fallback in `defaultProps`
+* and its entries in `defaultPropsWhen`. `defaultPropsWhen` is `undefined` when nothing was
+* conditional, so a body without one stores exactly what it did before.
+*
+* Stored by condition, every prop shares one order of conditions, while precedence is per prop. The
+* order taken keeps each prop's own; two props that order the same two conditions oppositely can't
+* share one, and are refused.
+*/
+function splitConditionalDefaults(authored) {
+	const defaultProps = {};
+	const perProp = /* @__PURE__ */ new Map();
+	for (const [prop, value] of Object.entries(authored)) {
+		if (!isConditionalDefault(value)) {
+			defaultProps[prop] = value;
+			continue;
+		}
+		if (value.fallback !== void 0) defaultProps[prop] = value.fallback;
+		const entries = /* @__PURE__ */ new Map();
+		for (const entry of value.entries) {
+			const key = canonicalCondition(entry.when);
+			entries.delete(key);
+			entries.set(key, entry);
+		}
+		perProp.set(prop, entries);
+	}
+	if (perProp.size === 0) return { defaultProps };
+	const order = conditionOrder(perProp);
+	const defaultPropsWhen = {};
+	for (const key of order) {
+		let when;
+		const props = {};
+		for (const [prop, entries] of perProp) {
+			const entry = entries.get(key);
+			if (!entry) continue;
+			when ??= { ...entry.when };
+			props[prop] = entry.value;
+		}
+		if (when) defaultPropsWhen[key] = {
+			when,
+			props
+		};
+	}
+	return {
+		defaultProps,
+		defaultPropsWhen
+	};
+}
+/**
+* `defaultProps` as stored: each `conditionalDefault` splits into its fallback, which stays in
+* `defaultProps`, and its conditions, which go to `defaultPropsWhen`. Empty for a body whose
+* defaults are all plain, so it stores what it did before.
+*/
+function storedDefaults(body) {
+	if (!isPlainObject(body.defaultProps)) return {};
+	const { defaultProps, defaultPropsWhen } = splitConditionalDefaults(body.defaultProps);
+	return defaultPropsWhen ? {
+		defaultProps,
+		defaultPropsWhen
+	} : {};
+}
+/**
+* One order of every condition that keeps each prop's own order, by first appearance where props
+* don't constrain it.
+*/
+function conditionOrder(perProp) {
+	const seen = [];
+	const after = /* @__PURE__ */ new Map();
+	for (const [prop, entries] of perProp) {
+		const keys = [...entries.keys()];
+		keys.forEach((key, at) => {
+			if (!seen.includes(key)) seen.push(key);
+			const earlier = after.get(key) ?? /* @__PURE__ */ new Map();
+			for (const before of keys.slice(0, at)) earlier.set(before, prop);
+			after.set(key, earlier);
+		});
+	}
+	for (const [key, earlier] of after) for (const [before, prop] of earlier) {
+		const other = after.get(before)?.get(key);
+		if (other === void 0) continue;
+		throw new Error(`\`${prop}\` puts \`${before}\` before \`${key}\` and \`${other}\` puts them the other way round. Conditional defaults share one order of conditions, so give both props the same order.`);
+	}
+	const order = [];
+	const placed = /* @__PURE__ */ new Set();
+	const placing = /* @__PURE__ */ new Set();
+	const place = (key) => {
+		if (placed.has(key)) return;
+		if (placing.has(key)) throw new Error(`Conditional defaults order \`${key}\` both before and after another condition across their props. They share one order of conditions, so give every prop the same order.`);
+		placing.add(key);
+		for (const before of after.get(key)?.keys() ?? []) place(before);
+		placing.delete(key);
+		placed.add(key);
+		order.push(key);
+	};
+	for (const key of seen) place(key);
+	return order;
+}
+/**
+* Stored defaults as authored: the inverse of {@link splitConditionalDefaults}, each prop
+* `defaultPropsWhen` names given back as a {@link conditionalDefault} over its fallback.
+*/
+function joinConditionalDefaults({ defaultProps, defaultPropsWhen }) {
+	const out = { ...defaultProps };
+	const entries = /* @__PURE__ */ new Map();
+	for (const { when, props } of Object.values(defaultPropsWhen ?? {})) for (const [prop, value] of Object.entries(props ?? {})) entries.set(prop, [...entries.get(prop) ?? [], {
+		when,
+		value
+	}]);
+	for (const [prop, list] of entries) out[prop] = conditionalDefault(out[prop], list);
+	return out;
+}
+//#endregion
+export { conditionalDefault, isConditionalDefault, joinConditionalDefaults, storedDefaults };

package/dist/entities/system/copy-plan.js

@@ -1,5 +1,5 @@
-import { rejectData } from "../../framework/rejection.js";
 import { MINTED, collectRefs, isMintedRow, kindOf, pathOf, rewriteRefs, sourceOf, splitRef } from "../../framework/utils/refs.js";
+import { rejectData } from "../../framework/rejection.js";
 import { kindBorrowable } from "../../framework/registry.js";
 import { File } from "./File.js";
 import { componentModuleFilePaths, componentRegistryImports } from "./component-module.js";

package/dist/entities/system/css-motion-reach.js

@@ -1,5 +1,5 @@
-import { isRef, kindOf, pathOf } from "../../framework/utils/refs.js";
 import { isPlainObject } from "../../framework/utils/field-path.js";
+import { isRef, kindOf, pathOf } from "../../framework/utils/refs.js";
 import { createSliceMemo } from "../../framework/memo.js";
 import { drawnMotionBody, drawnMotionName } from "./drawn-motion.js";
 import { convertMotion } from "./motion-convert.js";

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

@@ -3,6 +3,7 @@ import { RegisteredComponentHandles, RegisteredGroupPaths, RegisteredModifiers,
 import { Authored } from "../../framework/authoring.js";
 import { StyleValue } from "./style-bag.js";
 import { ComponentSourceInput } from "./component-source-fields.js";
+import { ConditionalDefault } from "./conditional-defaults.js";
 import { VariantValues } from "./Component.js";
 import { AllHTMLAttributes, ComponentPropsWithRef, ComponentType, ElementType, JSX, ReactElement, ReactNode, Ref } from "react";
 
@@ -663,6 +664,11 @@ type ForwardedPropsOf<L extends LayerMap, F extends string> = [NonRootForward<L,
 type DefaultsOf<P extends PropMap> = Partial<DeclaredProps<P>> & {
   [key: string]: unknown;
 };
+/** {@link DefaultsOf} as `.defaultProps` takes it: a declared prop other than `as` may also default
+ *  through {@link conditionalDefault}. */
+type AuthoredDefaultsOf<P extends PropMap> = { [K in keyof DeclaredProps<P>]?: K extends 'as' ? DeclaredProps<P>[K] : DeclaredProps<P>[K] | ConditionalDefault<DeclaredProps<P>[K]> } & {
+  [key: string]: unknown;
+};
 /**
  * `T` without the keys in `K` — `Omit` that leaves an index signature alone.
  *
@@ -778,8 +784,11 @@ F extends string = never, /** The states `.states()` declared — what the rende
    *
    * `const`, so an `as` keeps its literal type: without it `{ as: 'input' }` widens to `string` and
    * there's no tag left to resolve the element's props against.
+   *
+   * A default that depends on another prop is a `conditionalDefault`:
+   * `includeScrim: conditionalDefault(true, [{ when: { modal: false }, value: false }])`.
    */
-  defaultProps<const D2 extends DefaultsOf<P>>(defaults: D2): ComponentBuilder<L, P, E, D2, F, S>;
+  defaultProps<const D2 extends AuthoredDefaultsOf<P>>(defaults: D2): ComponentBuilder<L, P, E, D2, F, S>;
   /**
    * The layers whose element props this component ALSO exposes, keyed by layer.
    *
@@ -892,4 +901,4 @@ interface DefineComponent {
 declare function definePropsFirst<const P extends PropMap<LayerPath>>(props: P & NoInfer<{ [K in keyof P]: Exact<P[K], AuthoredProp<LayerPath>> }>): ComponentBuilder<LayerMap, P>;
 declare const defineComponent: DefineComponent;
 //#endregion
-export { AsInput, AuthoredComponent, AuthoredProp, ComponentBuilder, ComponentPropsOf, DefaultsOf, GlyphComponent, GlyphValue, LayerElement, LayerMap, LinkedHandle, PhantomCallProps, PhantomReadProps, PropCondition, PropDecl, PropMap, RegisteredMembers, RenderArgs, SlotCodeForm, SlotDecl, StateMap, StyleRuleInput, defineComponent };
+export { AsInput, AuthoredComponent, AuthoredDefaultsOf, AuthoredProp, ComponentBuilder, ComponentPropsOf, GlyphComponent, GlyphValue, LayerElement, LayerMap, LinkedHandle, PhantomCallProps, PhantomReadProps, PropCondition, PropDecl, PropMap, RegisteredMembers, RenderArgs, SlotCodeForm, SlotDecl, StateMap, StyleRuleInput, defineComponent };

package/dist/entities/system/defineComponent.js

@@ -2,6 +2,7 @@ import { canonicalCondition, isRef, kindOf, memberRef, pathOf } from "../../fram
 import { glyphIdentityOf, glyphPackageRefOf, isComponentType } from "./glyph-identity.js";
 import "../../framework/preview-store.js";
 import { assertComponentSourceInput } from "./component-source-fields.js";
+import { isConditionalDefault, storedDefaults } from "./conditional-defaults.js";
 import { Component, layerRef, storedStyleRules } from "./Component.js";
 //#region src/entities/system/defineComponent.ts
 function build(body) {
@@ -145,6 +146,7 @@ function storableElement(value) {
 */
 function storableValue(value) {
 	if (value === null) return null;
+	if (isConditionalDefault(value)) throw new Error("`conditionalDefault` is a default, so it goes in `.defaultProps` or `.extend({ defaultProps })`. A preview conditions its props with `.preview({ when: [{ when, props }] })`.");
 	const type = typeof value;
 	if (type === "string" || type === "number" || type === "boolean") return value;
 	if (isComponentType(value)) return storableComponentRef(value);
@@ -388,6 +390,7 @@ function toStored(body) {
 		if (Object.keys(keyed).length === 0) delete stored.preview;
 		else stored.preview = keyed;
 	}
+	Object.assign(stored, storedDefaults(body));
 	if (body.props && typeof body.props === "object") {
 		const props = {};
 		for (const [name, decl] of Object.entries(body.props)) props[name] = storedProp(decl, body.layers);

package/dist/entities/system/drawn-motion.d.ts

@@ -22,7 +22,8 @@ declare function drawnMotionName(config: Config, value: unknown): string | undef
 declare function drawnMotionBody(config: Config, name: string): Record<string, unknown> | undefined;
 /**
  * Every linked preset `config` plays under its pin's name: each preset a reached source holds that
- * this config's refs reach, unless the link draws it with a row of this config's own.
+ * this config's refs reach, unless the link draws it with a row of this config's own, and the preset
+ * of a nearer link's that a routed pin draws with in its place ({@link linkedDraw}).
  */
 declare function linkedMotionPresets(config: Config): readonly LinkedMotionPreset[];
 //#endregion