@yahoo/uds-create-config 3.0.10 → 3.2.0

package/dist/migrations/2.0.0/v1-artifact.d.ts

@@ -1,5 +1,6 @@
 import { CopyPlan } from "../../entities/system/copy-plan.js";
-import { Ref } from "../../framework/utils/refs.js";
+import { ExtendableRef, Ref } from "../../framework/utils/refs.js";
+import { CreateInput } from "../../framework/utils/field-schema.js";
 import { DerivedEntityClass } from "../../framework/defineDerivedEntity.js";
 import { SubEntityClass } from "../../framework/defineSubEntity.js";
 import { ComponentContractOf, PathOf } from "../../framework/registered.js";
@@ -471,7 +472,7 @@ declare function loadV1Artifact(studio: V1Artifact, options?: LoadV1Options): Co
         }, _$zod_v4_core0.$strip>>;
         export: _$zod.ZodOptional<_$zod.ZodString>;
       }, _$zod_v4_core0.$strict>;
-      readonly description: "Create a component at a new qualified `path`. When its complete body is known, include all layers, anatomy, props, defaults, and styles in this one operation. `data.layers` maps each stable layer name to the element it renders and must include `root` — a tag for a primitive (`{ \"layers\": { \"root\": \"div\" } }`), and for anything built on top, a ref to a primitive (`{ \"root\": { \"__ref\": \"component:Box\" }, \"label\": { \"__ref\": \"component:Text\" } }`), which is what lets the layer take that primitive's style props. A primitive exposes style props as `{ \"type\": \"styleProperty\", \"value\": { \"__ref\": \"style-property:bg\" } }` and declares `children: { \"type\": \"slot\", \"text\": true }` when it holds content — without the slot, nothing nested inside it renders. A composed component exposes a layer's props at its own top level through `forwards`, keyed by layer: `{ \"forwards\": { \"root\": \"*\" } }` passes every prop the root's element takes (so `<Button width=\"full\">` reaches the root's `width`), and a list of member refs (`[{ \"__ref\": \"component:Box#props/width\" }]`, each naming the component that declares the prop) passes only those. A prop a layer already exposes is forwarded, never redeclared in `props`; a `props` entry of `{ \"type\": \"forward\" }` is the reverse route, one of this component's props into a layer's. `anatomy` is the tree the build would read off a render: each node renders a layer (`{ \"__ref\": \"layer:<name>\" }`), an intrinsic tag, or `Slot` (`{ \"element\": \"Slot\", \"props\": { \"name\": \"children\" } }`, where a slot prop's content lands — but a declared slot fills `root` by default, so a primitive still declares its `children` slot prop yet needs no `Slot` node or `children` entry for it, and a `Slot` node is only for landing that content in a nested layer); `children` lists sibling node keys from the `root` node, never a prop name; `text` is a fixed string; `visible` is a condition on a prop (`{ \"$state\": \"<prop>\" }`, or with `eq`); content shown in a nested layer is a route, `children: { \"type\": \"forward\", \"target\": \"label/children\" }`. `$state` appears only in `visible` and in an `element` a prop chooses, never as a prop value. A glyph is a node of its own, `{ \"element\": { \"__ref\": \"icon:<library>/<Name>\" } }`, listed in the `children` of the layer node that holds it, never a prop value. Text a prop supplies to a text layer is never a node either: declare the prop `{ \"type\": \"forward\", \"target\": \"<layer>/children\" }` and the layer shows it; a `Slot` node goes only under a layer that takes nodes. A style rule is `\"styles\": { \"*\": { \"when\": null, \"layers\": { \"root\": { \"bg\": \"surface\" } } } }`, keyed by a name, with each layer's bag under `layers`. A composed component carries its own styles: give it an unconditional (`\"*\"`) rule that lays out and surfaces it through the system's style properties — spacing, alignment and gap on the container, a background and color where it has one — rather than leaning on the bare primitives, which paint flat. Style a layer only with the style props the primitive it renders exposes, set to the values those props accept: `component/get` on the primitive lists both, so read it and choose from that rather than reaching for a CSS name or value the system has no style property for. Set `previewProps` (or `defaultProps`) so the component previews with content; a root that takes children renders empty otherwise. A style rule's layer bag is keyed by style-prop name (`fontWeight`, `color`), never by CSS property name, and each value is one of that prop's values.";
+      readonly description: "Create a component at a new qualified `path`. For a component with nothing in it yet, one to design on the canvas before it has props or variants, use `create-blank` with only a `path` instead of authoring a minimal body here. When its complete body is known, include all layers, anatomy, props, defaults, and styles in this one operation. `data.layers` maps each stable layer name to the element it renders and must include `root` — a tag for a primitive (`{ \"layers\": { \"root\": \"div\" } }`), and for anything built on top, a ref to a primitive (`{ \"root\": { \"__ref\": \"component:Box\" }, \"label\": { \"__ref\": \"component:Text\" } }`), which is what lets the layer take that primitive's style props. A primitive exposes style props as `{ \"type\": \"styleProperty\", \"value\": { \"__ref\": \"style-property:bg\" } }` and declares `children: { \"type\": \"slot\", \"text\": true }` when it holds content — without the slot, nothing nested inside it renders. A composed component exposes a layer's props at its own top level through `forwards`, keyed by layer: `{ \"forwards\": { \"root\": \"*\" } }` passes every prop the root's element takes (so `<Button width=\"full\">` reaches the root's `width`), and a list of member refs (`[{ \"__ref\": \"component:Box#props/width\" }]`, each naming the component that declares the prop) passes only those. A prop a layer already exposes is forwarded, never redeclared in `props`; a `props` entry of `{ \"type\": \"forward\" }` is the reverse route, one of this component's props into a layer's. `anatomy` is the tree the build would read off a render: each node renders a layer (`{ \"__ref\": \"layer:<name>\" }`), an intrinsic tag, or `Slot` (`{ \"element\": \"Slot\", \"props\": { \"name\": \"children\" } }`, where a slot prop's content lands — but a declared slot fills `root` by default, so a primitive still declares its `children` slot prop yet needs no `Slot` node or `children` entry for it, and a `Slot` node is only for landing that content in a nested layer); `children` lists sibling node keys from the `root` node, never a prop name; `text` is a fixed string; `visible` is a condition on a prop (`{ \"$state\": \"<prop>\" }`, or with `eq`); content shown in a nested layer is a route, `children: { \"type\": \"forward\", \"target\": \"label/children\" }`. `$state` appears only in `visible` and in an `element` a prop chooses, never as a prop value. A glyph is a node of its own, `{ \"element\": { \"__ref\": \"icon:<library>/<Name>\" } }`, listed in the `children` of the layer node that holds it, never a prop value. Text a prop supplies to a text layer is never a node either: declare the prop `{ \"type\": \"forward\", \"target\": \"<layer>/children\" }` and the layer shows it; a `Slot` node goes only under a layer that takes nodes. A style rule is `\"styles\": { \"*\": { \"when\": null, \"layers\": { \"root\": { \"bg\": \"surface\" } } } }`, keyed by a name, with each layer's bag under `layers`. A composed component carries its own styles: give it an unconditional (`\"*\"`) rule that lays out and surfaces it through the system's style properties — spacing, alignment and gap on the container, a background and color where it has one — rather than leaning on the bare primitives, which paint flat. Style a layer only with the style props the primitive it renders exposes, set to the values those props accept: `component/get` on the primitive lists both, so read it and choose from that rather than reaching for a CSS name or value the system has no style property for. Set `previewProps` (or `defaultProps`) so the component previews with content; a root that takes children renders empty otherwise. A style rule's layer bag is keyed by style-prop name (`fontWeight`, `color`), never by CSS property name, and each value is one of that prop's values.";
       readonly example: ({
         config
       }: {
@@ -483,6 +484,27 @@ declare function loadV1Artifact(studio: V1Artifact, options?: LoadV1Options): Co
         data: Record<string, unknown>;
       };
     };
+    readonly 'create-blank': {
+      readonly input: _$zod.ZodObject<{
+        path: _$zod.ZodType<string, string | undefined, _$zod_v4_core0.$ZodTypeInternals<string, string | undefined>>;
+      }, _$zod_v4_core0.$strip>;
+      readonly readOnly: false;
+      readonly label: "Create blank";
+      readonly 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.";
+      readonly scope: "item";
+      readonly creates: true;
+      readonly title: (entity: string) => string;
+      readonly example: ({
+        config
+      }: {
+        config: Config;
+        kind: string;
+        path: string;
+      }) => {
+        path: string;
+      };
+      readonly handler: (input: Record<string, unknown>, config: Config) => Config;
+    };
     readonly 'sub-create/anatomy': {
       readonly description: "Add one anatomy node (`key` + `data`) to a component. In a batch, create child nodes before a parent whose `children` or `slots` names them; each referenced node must already exist when this operation runs.";
     };
@@ -1012,7 +1034,7 @@ declare function loadV1Artifact(studio: V1Artifact, options?: LoadV1Options): Co
       __ref: _$zod.ZodString;
     }, _$zod_v4_core0.$strip>>;
   }, _$zod_v4_core0.$strip>, "modifier", Record<never, never>, Record<never, never>, false>;
-  styleProps: EntityClass<_$zod.ZodObject<{
+  styleProps: Omit<EntityClass<_$zod.ZodObject<{
     properties: _$zod.ZodArray<_$zod.ZodString>;
     values: _$zod.ZodOptional<_$zod.ZodArray<_$zod.ZodType<StylePropValue, unknown, _$zod_v4_core0.$ZodTypeInternals<StylePropValue, unknown>>>>;
     responsive: _$zod.ZodDefault<_$zod.ZodBoolean>;
@@ -1038,7 +1060,19 @@ declare function loadV1Artifact(studio: V1Artifact, options?: LoadV1Options): Co
         data: Record<string, unknown>;
       } | undefined;
     };
-  }, Record<never, never>, false>;
+  }, Record<never, never>, false>, "ref"> & {
+    ref<const Path extends PathOf<"style-property">>(path: Path): ReturnType<(path: string) => ExtendableRef<Partial<CreateInput<_$zod.ZodObject<{
+      properties: _$zod.ZodArray<_$zod.ZodString>;
+      values: _$zod.ZodOptional<_$zod.ZodArray<_$zod.ZodType<StylePropValue, unknown, _$zod_v4_core0.$ZodTypeInternals<StylePropValue, unknown>>>>;
+      responsive: _$zod.ZodDefault<_$zod.ZodBoolean>;
+      classPrefix: _$zod.ZodOptional<_$zod.ZodString>;
+      arbitrary: _$zod.ZodDefault<_$zod.ZodBoolean>;
+      negates: _$zod.ZodDefault<_$zod.ZodBoolean>;
+      opacityOf: _$zod.ZodOptional<_$zod.ZodLazy<_$zod.ZodType<Ref, unknown, _$zod_v4_core0.$ZodTypeInternals<Ref, unknown>>>>;
+    }, _$zod_v4_core0.$strip>>>>> & {
+      readonly __ref: `style-property:${Path}`;
+    };
+  };
   composites: EntityClass<_$zod.ZodObject<{
     styles: SubEntityClass<_$zod.ZodType<StyleValue, unknown, _$zod_v4_core0.$ZodTypeInternals<StyleValue, unknown>>>;
   }, _$zod_v4_core0.$strip>, _$zod.ZodObject<Record<never, never>, _$zod_v4_core0.$strip>, "composite", Record<never, never>, Record<never, never>, false>;

package/dist/migrations/20260914155048_component_create_blank_op.d.ts

@@ -0,0 +1,13 @@
+/**
+ * An additive fence: the `component` kind gains the op `create-blank`, so the operation catalogue's
+ * fingerprint moves. No stored byte changes — the op is stored as the ordinary `component/create`
+ * patch it delegates to.
+ *
+ * Identity, so a stamp below this version means "does not know `create-blank`" and one at it means
+ * the catalogue is understood.
+ *
+ * Deletable once no stored config artifact is below this version.
+ */
+import type { SchemaMigration } from '../framework/schema-version';
+export declare const COMPONENT_CREATE_BLANK_OP_VERSION = 20260914155048;
+export declare const componentCreateBlankOpMigration: SchemaMigration;

package/dist/migrations/20260914155048_component_create_blank_op.js

@@ -0,0 +1,8 @@
+//#region src/migrations/20260914155048_component_create_blank_op.ts
+const COMPONENT_CREATE_BLANK_OP_VERSION = 20260914155048;
+const componentCreateBlankOpMigration = {
+	version: COMPONENT_CREATE_BLANK_OP_VERSION,
+	up: (json) => json
+};
+//#endregion
+export { COMPONENT_CREATE_BLANK_OP_VERSION, componentCreateBlankOpMigration };