@yahoo/uds-create-config 2.44.0 → 3.0.0

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

@@ -0,0 +1,355 @@
+import { Ref } from "../../framework/utils/refs.js";
+import { EntityClass } from "../../framework/defineEntity.js";
+import { Config } from "../../framework/Config.js";
+import { StylePropValue } from "../system/StyleProperty.js";
+import { z } from "zod";
+
+//#region src/entities/native/NativeStyleProperty.d.ts
+/** One React Native style key, as RN's own types declare them. */
+declare const rnStyleKey: z.ZodEnum<{
+  filter: "filter";
+  transform: "transform";
+  position: "position";
+  end: "end";
+  start: "start";
+  bottom: "bottom";
+  left: "left";
+  right: "right";
+  top: "top";
+  color: "color";
+  inset: "inset";
+  flex: "flex";
+  cursor: "cursor";
+  direction: "direction";
+  display: "display";
+  gap: "gap";
+  height: "height";
+  isolation: "isolation";
+  margin: "margin";
+  opacity: "opacity";
+  overflow: "overflow";
+  padding: "padding";
+  width: "width";
+  alignContent: "alignContent";
+  alignItems: "alignItems";
+  alignSelf: "alignSelf";
+  aspectRatio: "aspectRatio";
+  backfaceVisibility: "backfaceVisibility";
+  backgroundColor: "backgroundColor";
+  borderBlockColor: "borderBlockColor";
+  borderBlockEndColor: "borderBlockEndColor";
+  borderBlockStartColor: "borderBlockStartColor";
+  borderBottomColor: "borderBottomColor";
+  borderBottomEndRadius: "borderBottomEndRadius";
+  borderBottomLeftRadius: "borderBottomLeftRadius";
+  borderBottomRightRadius: "borderBottomRightRadius";
+  borderBottomStartRadius: "borderBottomStartRadius";
+  borderBottomWidth: "borderBottomWidth";
+  borderColor: "borderColor";
+  borderCurve: "borderCurve";
+  borderEndColor: "borderEndColor";
+  borderEndEndRadius: "borderEndEndRadius";
+  borderEndStartRadius: "borderEndStartRadius";
+  borderEndWidth: "borderEndWidth";
+  borderLeftColor: "borderLeftColor";
+  borderLeftWidth: "borderLeftWidth";
+  borderRadius: "borderRadius";
+  borderRightColor: "borderRightColor";
+  borderRightWidth: "borderRightWidth";
+  borderStartColor: "borderStartColor";
+  borderStartEndRadius: "borderStartEndRadius";
+  borderStartStartRadius: "borderStartStartRadius";
+  borderStartWidth: "borderStartWidth";
+  borderStyle: "borderStyle";
+  borderTopColor: "borderTopColor";
+  borderTopEndRadius: "borderTopEndRadius";
+  borderTopLeftRadius: "borderTopLeftRadius";
+  borderTopRightRadius: "borderTopRightRadius";
+  borderTopStartRadius: "borderTopStartRadius";
+  borderTopWidth: "borderTopWidth";
+  borderWidth: "borderWidth";
+  boxShadow: "boxShadow";
+  boxSizing: "boxSizing";
+  columnGap: "columnGap";
+  elevation: "elevation";
+  experimental_backgroundImage: "experimental_backgroundImage";
+  experimental_backgroundPosition: "experimental_backgroundPosition";
+  experimental_backgroundRepeat: "experimental_backgroundRepeat";
+  experimental_backgroundSize: "experimental_backgroundSize";
+  flexBasis: "flexBasis";
+  flexDirection: "flexDirection";
+  flexGrow: "flexGrow";
+  flexShrink: "flexShrink";
+  flexWrap: "flexWrap";
+  fontFamily: "fontFamily";
+  fontSize: "fontSize";
+  fontStyle: "fontStyle";
+  fontVariant: "fontVariant";
+  fontWeight: "fontWeight";
+  includeFontPadding: "includeFontPadding";
+  insetBlock: "insetBlock";
+  insetBlockEnd: "insetBlockEnd";
+  insetBlockStart: "insetBlockStart";
+  insetInline: "insetInline";
+  insetInlineEnd: "insetInlineEnd";
+  insetInlineStart: "insetInlineStart";
+  justifyContent: "justifyContent";
+  letterSpacing: "letterSpacing";
+  lineHeight: "lineHeight";
+  marginBlock: "marginBlock";
+  marginBlockEnd: "marginBlockEnd";
+  marginBlockStart: "marginBlockStart";
+  marginBottom: "marginBottom";
+  marginEnd: "marginEnd";
+  marginHorizontal: "marginHorizontal";
+  marginInline: "marginInline";
+  marginInlineEnd: "marginInlineEnd";
+  marginInlineStart: "marginInlineStart";
+  marginLeft: "marginLeft";
+  marginRight: "marginRight";
+  marginStart: "marginStart";
+  marginTop: "marginTop";
+  marginVertical: "marginVertical";
+  maxHeight: "maxHeight";
+  maxWidth: "maxWidth";
+  minHeight: "minHeight";
+  minWidth: "minWidth";
+  mixBlendMode: "mixBlendMode";
+  objectFit: "objectFit";
+  outlineColor: "outlineColor";
+  outlineOffset: "outlineOffset";
+  outlineStyle: "outlineStyle";
+  outlineWidth: "outlineWidth";
+  overlayColor: "overlayColor";
+  paddingBlock: "paddingBlock";
+  paddingBlockEnd: "paddingBlockEnd";
+  paddingBlockStart: "paddingBlockStart";
+  paddingBottom: "paddingBottom";
+  paddingEnd: "paddingEnd";
+  paddingHorizontal: "paddingHorizontal";
+  paddingInline: "paddingInline";
+  paddingInlineEnd: "paddingInlineEnd";
+  paddingInlineStart: "paddingInlineStart";
+  paddingLeft: "paddingLeft";
+  paddingRight: "paddingRight";
+  paddingStart: "paddingStart";
+  paddingTop: "paddingTop";
+  paddingVertical: "paddingVertical";
+  pointerEvents: "pointerEvents";
+  resizeMode: "resizeMode";
+  rotation: "rotation";
+  rowGap: "rowGap";
+  scaleX: "scaleX";
+  scaleY: "scaleY";
+  shadowColor: "shadowColor";
+  shadowOffset: "shadowOffset";
+  shadowOpacity: "shadowOpacity";
+  shadowRadius: "shadowRadius";
+  textAlign: "textAlign";
+  textAlignVertical: "textAlignVertical";
+  textDecorationColor: "textDecorationColor";
+  textDecorationLine: "textDecorationLine";
+  textDecorationStyle: "textDecorationStyle";
+  textShadowColor: "textShadowColor";
+  textShadowOffset: "textShadowOffset";
+  textShadowRadius: "textShadowRadius";
+  textTransform: "textTransform";
+  tintColor: "tintColor";
+  transformMatrix: "transformMatrix";
+  transformOrigin: "transformOrigin";
+  translateX: "translateX";
+  translateY: "translateY";
+  userSelect: "userSelect";
+  verticalAlign: "verticalAlign";
+  writingDirection: "writingDirection";
+  zIndex: "zIndex";
+}>;
+declare const NativeStyleProperty: EntityClass<z.ZodObject<Omit<{
+  properties: z.ZodArray<z.ZodString>;
+  values: z.ZodOptional<z.ZodArray<z.ZodType<StylePropValue, unknown, z.core.$ZodTypeInternals<StylePropValue, unknown>>>>;
+  responsive: z.ZodDefault<z.ZodBoolean>;
+  classPrefix: z.ZodOptional<z.ZodString>;
+  arbitrary: z.ZodDefault<z.ZodBoolean>;
+  negates: z.ZodDefault<z.ZodBoolean>;
+  opacityOf: z.ZodOptional<z.ZodLazy<z.ZodType<Ref, unknown, z.core.$ZodTypeInternals<Ref, unknown>>>>;
+}, "values" | "properties" | "classPrefix"> & {
+  properties: z.ZodArray<z.ZodPipe<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>, z.ZodEnum<{
+    filter: "filter";
+    transform: "transform";
+    position: "position";
+    end: "end";
+    start: "start";
+    bottom: "bottom";
+    left: "left";
+    right: "right";
+    top: "top";
+    color: "color";
+    inset: "inset";
+    flex: "flex";
+    cursor: "cursor";
+    direction: "direction";
+    display: "display";
+    gap: "gap";
+    height: "height";
+    isolation: "isolation";
+    margin: "margin";
+    opacity: "opacity";
+    overflow: "overflow";
+    padding: "padding";
+    width: "width";
+    alignContent: "alignContent";
+    alignItems: "alignItems";
+    alignSelf: "alignSelf";
+    aspectRatio: "aspectRatio";
+    backfaceVisibility: "backfaceVisibility";
+    backgroundColor: "backgroundColor";
+    borderBlockColor: "borderBlockColor";
+    borderBlockEndColor: "borderBlockEndColor";
+    borderBlockStartColor: "borderBlockStartColor";
+    borderBottomColor: "borderBottomColor";
+    borderBottomEndRadius: "borderBottomEndRadius";
+    borderBottomLeftRadius: "borderBottomLeftRadius";
+    borderBottomRightRadius: "borderBottomRightRadius";
+    borderBottomStartRadius: "borderBottomStartRadius";
+    borderBottomWidth: "borderBottomWidth";
+    borderColor: "borderColor";
+    borderCurve: "borderCurve";
+    borderEndColor: "borderEndColor";
+    borderEndEndRadius: "borderEndEndRadius";
+    borderEndStartRadius: "borderEndStartRadius";
+    borderEndWidth: "borderEndWidth";
+    borderLeftColor: "borderLeftColor";
+    borderLeftWidth: "borderLeftWidth";
+    borderRadius: "borderRadius";
+    borderRightColor: "borderRightColor";
+    borderRightWidth: "borderRightWidth";
+    borderStartColor: "borderStartColor";
+    borderStartEndRadius: "borderStartEndRadius";
+    borderStartStartRadius: "borderStartStartRadius";
+    borderStartWidth: "borderStartWidth";
+    borderStyle: "borderStyle";
+    borderTopColor: "borderTopColor";
+    borderTopEndRadius: "borderTopEndRadius";
+    borderTopLeftRadius: "borderTopLeftRadius";
+    borderTopRightRadius: "borderTopRightRadius";
+    borderTopStartRadius: "borderTopStartRadius";
+    borderTopWidth: "borderTopWidth";
+    borderWidth: "borderWidth";
+    boxShadow: "boxShadow";
+    boxSizing: "boxSizing";
+    columnGap: "columnGap";
+    elevation: "elevation";
+    experimental_backgroundImage: "experimental_backgroundImage";
+    experimental_backgroundPosition: "experimental_backgroundPosition";
+    experimental_backgroundRepeat: "experimental_backgroundRepeat";
+    experimental_backgroundSize: "experimental_backgroundSize";
+    flexBasis: "flexBasis";
+    flexDirection: "flexDirection";
+    flexGrow: "flexGrow";
+    flexShrink: "flexShrink";
+    flexWrap: "flexWrap";
+    fontFamily: "fontFamily";
+    fontSize: "fontSize";
+    fontStyle: "fontStyle";
+    fontVariant: "fontVariant";
+    fontWeight: "fontWeight";
+    includeFontPadding: "includeFontPadding";
+    insetBlock: "insetBlock";
+    insetBlockEnd: "insetBlockEnd";
+    insetBlockStart: "insetBlockStart";
+    insetInline: "insetInline";
+    insetInlineEnd: "insetInlineEnd";
+    insetInlineStart: "insetInlineStart";
+    justifyContent: "justifyContent";
+    letterSpacing: "letterSpacing";
+    lineHeight: "lineHeight";
+    marginBlock: "marginBlock";
+    marginBlockEnd: "marginBlockEnd";
+    marginBlockStart: "marginBlockStart";
+    marginBottom: "marginBottom";
+    marginEnd: "marginEnd";
+    marginHorizontal: "marginHorizontal";
+    marginInline: "marginInline";
+    marginInlineEnd: "marginInlineEnd";
+    marginInlineStart: "marginInlineStart";
+    marginLeft: "marginLeft";
+    marginRight: "marginRight";
+    marginStart: "marginStart";
+    marginTop: "marginTop";
+    marginVertical: "marginVertical";
+    maxHeight: "maxHeight";
+    maxWidth: "maxWidth";
+    minHeight: "minHeight";
+    minWidth: "minWidth";
+    mixBlendMode: "mixBlendMode";
+    objectFit: "objectFit";
+    outlineColor: "outlineColor";
+    outlineOffset: "outlineOffset";
+    outlineStyle: "outlineStyle";
+    outlineWidth: "outlineWidth";
+    overlayColor: "overlayColor";
+    paddingBlock: "paddingBlock";
+    paddingBlockEnd: "paddingBlockEnd";
+    paddingBlockStart: "paddingBlockStart";
+    paddingBottom: "paddingBottom";
+    paddingEnd: "paddingEnd";
+    paddingHorizontal: "paddingHorizontal";
+    paddingInline: "paddingInline";
+    paddingInlineEnd: "paddingInlineEnd";
+    paddingInlineStart: "paddingInlineStart";
+    paddingLeft: "paddingLeft";
+    paddingRight: "paddingRight";
+    paddingStart: "paddingStart";
+    paddingTop: "paddingTop";
+    paddingVertical: "paddingVertical";
+    pointerEvents: "pointerEvents";
+    resizeMode: "resizeMode";
+    rotation: "rotation";
+    rowGap: "rowGap";
+    scaleX: "scaleX";
+    scaleY: "scaleY";
+    shadowColor: "shadowColor";
+    shadowOffset: "shadowOffset";
+    shadowOpacity: "shadowOpacity";
+    shadowRadius: "shadowRadius";
+    textAlign: "textAlign";
+    textAlignVertical: "textAlignVertical";
+    textDecorationColor: "textDecorationColor";
+    textDecorationLine: "textDecorationLine";
+    textDecorationStyle: "textDecorationStyle";
+    textShadowColor: "textShadowColor";
+    textShadowOffset: "textShadowOffset";
+    textShadowRadius: "textShadowRadius";
+    textTransform: "textTransform";
+    tintColor: "tintColor";
+    transformMatrix: "transformMatrix";
+    transformOrigin: "transformOrigin";
+    translateX: "translateX";
+    translateY: "translateY";
+    userSelect: "userSelect";
+    verticalAlign: "verticalAlign";
+    writingDirection: "writingDirection";
+    zIndex: "zIndex";
+  }>>>;
+  values: z.ZodOptional<z.ZodArray<z.ZodType<StylePropValue, unknown, z.core.$ZodTypeInternals<StylePropValue, unknown>>>>;
+}, z.core.$strip>, z.ZodObject<Omit<Record<never, never>, never> & {}, z.core.$strip>, "style-property", {
+  readonly rename: {
+    readonly to: z.ZodString;
+  };
+  readonly create: {
+    readonly path: z.ZodString;
+    readonly description: `Create a style property \u2014 the prop a component exposes for one CSS effect. \`path\` is the prop's JSX name, camelCase (\`borderRadius\`), never a CSS name; the CSS goes in \`properties\`. \`values\` is a ref to a token GROUP (\`${string}\`), which offers every token in it and keeps the prop in step with modes and edits; \`{ "alias": "brand", "value": ${string} }\` offers one token under a name of the prop's own; a literal (\`"row"\`, \`{ "alias": "full", "value": "9999px" }\`) is for a keyword the system has no token for. Restating a token's value as a literal instead of referencing it is refused.`;
+    readonly example: ({
+      config
+    }: {
+      config: Config;
+      kind: string;
+      path: string;
+    }) => {
+      path: string;
+      data: Record<string, unknown>;
+    } | undefined;
+  };
+}, Record<never, never>, false>;
+//#endregion
+export { NativeStyleProperty, rnStyleKey };

package/dist/entities/native/NativeStyleProperty.js

@@ -0,0 +1,28 @@
+import { StyleProperty, stylePropValueSchema } from "../system/StyleProperty.js";
+import { RN_STYLE_KEYS } from "../../react-native/style-keys.generated.js";
+import { z } from "zod";
+//#region src/entities/native/NativeStyleProperty.ts
+/**
+* The native variant of `StyleProperty`. A property names a React Native style key, validated
+* against RN's own vocabulary (`react-native/style-keys.generated.ts`, generated from its type declarations) after a
+* mechanical camel-case pass — so `'background-color'` authors fine and stores as
+* `'backgroundColor'`, while `'grid-template-columns'` is refused by the platform instead of
+* silently emitted into a theme nothing reads.
+*
+* Camel-casing is the only transform, deliberately: a mapping table (`margin-inline` →
+* `marginHorizontal`) would be our judgment, hand-maintained — the native catalog authors native
+* names directly. `classPrefix` is removed: it names emitted CSS classes, and native emits none.
+*/
+const camelize = (property) => property.replace(/-([a-z])/g, (_, letter) => letter.toUpperCase());
+/** One React Native style key, as RN's own types declare them. */
+const rnStyleKey = z.enum(RN_STYLE_KEYS);
+const NativeStyleProperty = StyleProperty.extend({
+	entityName: "NativeStyleProperty",
+	fields: {
+		properties: z.array(z.string().transform(camelize).pipe(rnStyleKey)),
+		values: z.array(stylePropValueSchema()).optional(),
+		classPrefix: null
+	}
+});
+//#endregion
+export { NativeStyleProperty, rnStyleKey };

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

@@ -0,0 +1,31 @@
+import { Ref } from "../../framework/utils/refs.js";
+import { SubEntityClass } from "../../framework/defineSubEntity.js";
+import { EntityClass } from "../../framework/defineEntity.js";
+import { DerivedColor, Gradient } from "../system/color.js";
+import { OverrideCondition } from "../system/Token.js";
+import { z } from "zod";
+
+//#region src/entities/native/NativeToken.d.ts
+declare const nativeTokenValue: z.ZodType<number | boolean | string | Ref | DerivedColor>;
+declare const NativeToken: EntityClass<z.ZodObject<Omit<{
+  value: z.ZodType<string | number | Ref | DerivedColor | Gradient, unknown, z.core.$ZodTypeInternals<string | number | Ref | DerivedColor | Gradient, unknown>>;
+  type: z.ZodOptional<z.ZodString>;
+  overrides: z.ZodOptional<SubEntityClass<z.ZodObject<{
+    on: z.ZodType<OverrideCondition, unknown, z.core.$ZodTypeInternals<OverrideCondition, unknown>>;
+    value: z.ZodType<string | number | Ref | DerivedColor | Gradient, unknown, z.core.$ZodTypeInternals<string | number | Ref | DerivedColor | Gradient, unknown>>;
+  }, z.core.$strip>>>;
+}, "value" | "overrides"> & {
+  value: z.ZodType<string | number | boolean | Ref | DerivedColor, unknown, z.core.$ZodTypeInternals<string | number | boolean | Ref | DerivedColor, unknown>>;
+  overrides: z.ZodOptional<SubEntityClass<z.ZodObject<{
+    on: z.ZodType<OverrideCondition, unknown, z.core.$ZodTypeInternals<OverrideCondition, unknown>>;
+    value: z.ZodType<string | number | boolean | Ref | DerivedColor, unknown, z.core.$ZodTypeInternals<string | number | boolean | Ref | DerivedColor, unknown>>;
+  }, z.core.$strip>>>;
+}, z.core.$strip>, z.ZodObject<Omit<{
+  cssPrefix: z.ZodOptional<z.ZodString>;
+}, "cssPrefix"> & {}, z.core.$strip>, "token", {
+  readonly create: {
+    readonly description: `Create a token at \`<group>/<name>\` \u2014 \`data.value\` is the CSS value. The first path segment is its group, and a style property takes a whole group as one ref (\`${string}\`), so put the tokens one prop should offer in one group rather than listing values on the prop.`;
+  };
+}, Record<never, never>, false>;
+//#endregion
+export { NativeToken, nativeTokenValue };

package/dist/entities/native/NativeToken.js

@@ -0,0 +1,49 @@
+import { derivedColor } from "../system/color.js";
+import { Font } from "../system/Font.js";
+import { Token, defineOverride } from "../system/Token.js";
+import { z } from "zod";
+//#region src/entities/native/NativeToken.ts
+/**
+* The native variant of `Token` — same kind, native validation. A value is something React Native
+* can hold: a number (points, opacity, duration), a boolean, a unit string RN itself understands
+* (`'45deg'`, `'50%'`, a hex color, `'transparent'`), an alias to another token, a font-family
+* ref, or a derived color (`mix()`/`alpha()` resolve to a concrete color, so they carry). What
+* deliberately does not validate is web's open string arm — `'1rem'`, `calc(…)`, `'50vh'` mean
+* nothing off the web, and refusing them here is the platform model: the config is the platform,
+* so a native config cannot hold a web value.
+*
+* The `Override` sub-entity is swapped in the same motion (`extend` refuses a half-swap), so a
+* dark-mode override obeys the same value domain as the base value. Inheriting web's Override
+* "for free" would have quietly accepted `'1rem'` under a modifier.
+*/
+/** The string forms native accepts — each one a shape React Native itself parses. Deliberately no
+*  bare `z.string()` arm: that is exactly where every web-ism would leak through. Widen only with
+*  evidence from a real system's port. */
+const nativeTokenString = z.union([
+	z.templateLiteral([z.number(), "deg"]),
+	z.templateLiteral([z.number(), "%"]),
+	z.string().regex(/^#(?:[0-9a-fA-F]{3,4}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$/),
+	z.literal("transparent"),
+	z.literal("none")
+]);
+const nativeTokenValue = z.union([
+	z.number(),
+	z.boolean(),
+	nativeTokenString,
+	Token,
+	Font,
+	derivedColor
+]);
+/** `Token`'s Override over the native value domain: the same condition and the same derived key. */
+const NativeOverride = defineOverride(nativeTokenValue);
+const NativeToken = Token.extend({
+	entityName: "NativeToken",
+	fields: {
+		value: nativeTokenValue,
+		overrides: NativeOverride.optional()
+	},
+	subEntities: { overrides: NativeOverride },
+	groupFields: { cssPrefix: null }
+});
+//#endregion
+export { NativeToken, nativeTokenValue };

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

@@ -0,0 +1,34 @@
+import { EntityClass } from "../../framework/defineEntity.js";
+import { z } from "zod";
+
+//#region src/entities/system/CanvasRole.d.ts
+/**
+ * The roles a canvas has a tool for — the vocabulary a design system fills in.
+ *
+ * This is the set of tools an editor offers, and each one is a SLOT: a role a config leaves
+ * unregistered has no entries, and its tool is disabled rather than falling back to a guess. So
+ * naming a role here offers the slot without asserting anything fills it, and what fills it is
+ * never a name the editor chose — it is whichever component the config pointed at.
+ *
+ * The names live here, with the entity, because the entity is what they are names OF. They were
+ * previously kept in `@yahoo/uds-create-platform-types` as a hand-maintained copy, annotated as
+ * one ("mirrors `@yahoo/uds-create-config`'s `CanvasRole` union without importing it") — a second
+ * source of truth wearing a comment admitting it.
+ */
+declare const CANVAS_ROLES: readonly ["frame", "text", "image"];
+type CanvasRoleName = (typeof CANVAS_ROLES)[number];
+declare const CanvasRole: EntityClass<z.ZodObject<{
+  entries: z.ZodArray<z.ZodObject<{
+    component: z.ZodObject<{
+      __ref: z.ZodString;
+    }, z.core.$strip>;
+    default: z.ZodOptional<z.ZodBoolean>;
+    defaultProps: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+  }, z.core.$strip>>;
+}, z.core.$strip>, z.ZodObject<Record<never, never>, z.core.$strip>, "canvas-role", {
+  readonly create: {
+    readonly description: `Register a canvas insert tool for this system. \`path\` is the role, one of ${string}; \`data.entries\` names the components that tool inserts, one marked \`default\`. A system whose roles are unregistered has those canvas tools disabled, so register \`frame\` and \`text\` once a layout primitive and a text primitive exist.`;
+  };
+}, Record<never, never>, false>;
+//#endregion
+export { CANVAS_ROLES, CanvasRole, CanvasRoleName };

package/dist/entities/system/CanvasRole.js

@@ -0,0 +1,45 @@
+import { defineEntity } from "../../framework/defineEntity.js";
+import { Component } from "./Component.js";
+import { z } from "zod";
+//#region src/entities/system/CanvasRole.ts
+/**
+* `CanvasRole` — the config-v2 form of old config's `registerCanvasRoles`: maps a canvas INSERT
+* TOOL (a role, keyed by the entity path — `frame`, `text`, …) to the components that tool inserts,
+* each with an optional default flag + default props. A SYSTEM entity; each entry references a
+* system `Component` by ref (so `collectRefs` harvests the canvas-role → component edge for free).
+*
+*   system.register(CanvasRole, {
+*     frame: { entries: [{ component: Component.ref('Box'), default: true, defaultProps: {…} },
+*                        { component: Component.ref('HStack') }] },
+*     text:  { entries: [{ component: Component.ref('Text') }] },
+*   });
+*/
+/**
+* The roles a canvas has a tool for — the vocabulary a design system fills in.
+*
+* This is the set of tools an editor offers, and each one is a SLOT: a role a config leaves
+* unregistered has no entries, and its tool is disabled rather than falling back to a guess. So
+* naming a role here offers the slot without asserting anything fills it, and what fills it is
+* never a name the editor chose — it is whichever component the config pointed at.
+*
+* The names live here, with the entity, because the entity is what they are names OF. They were
+* previously kept in `@yahoo/uds-create-platform-types` as a hand-maintained copy, annotated as
+* one ("mirrors `@yahoo/uds-create-config`'s `CanvasRole` union without importing it") — a second
+* source of truth wearing a comment admitting it.
+*/
+const CANVAS_ROLES = [
+	"frame",
+	"text",
+	"image"
+];
+const CanvasRole = defineEntity({
+	kind: "canvas-role",
+	fields: z.object({ entries: z.array(z.object({
+		component: Component.describe("The component this tool inserts, as a ref: `{ \"__ref\": \"component:<path>\" }`."),
+		default: z.boolean().optional().describe("The entry the tool inserts when none is chosen; mark one."),
+		defaultProps: z.record(z.string(), z.unknown()).optional().describe("Props the inserted component starts with, keyed by prop name.")
+	})).describe(`The components a canvas insert tool draws with. The entity's path is the tool: one of ${CANVAS_ROLES.map((role) => `\`${role}\``).join(", ")}. A role with no entity registered has its tool disabled.`) }),
+	schemas: { create: { description: `Register a canvas insert tool for this system. \`path\` is the role, one of ${CANVAS_ROLES.map((role) => `\`${role}\``).join(", ")}; \`data.entries\` names the components that tool inserts, one marked \`default\`. A system whose roles are unregistered has those canvas tools disabled, so register \`frame\` and \`text\` once a layout primitive and a text primitive exist.` } }
+});
+//#endregion
+export { CANVAS_ROLES, CanvasRole };