@bettercms-ai/types 1.39.0 → 1.41.0

package/dist/index.d.ts

@@ -25,6 +25,20 @@ declare const DOCK_ICON_NAMES: readonly ["access-denied", "activity", "add", "ad
 type DockIconName = (typeof DOCK_ICON_NAMES)[number];
 declare const DOCK_ICON_NAME_SET: ReadonlySet<string>;
 
+/** Longest `description` a choice option may carry: one line under its label (V2's longest is 71). */
+declare const OPTION_DESCRIPTION_MAX = 140;
+/**
+ * One choice of a select / multiselect / tags field or prop. Values are judged by `value` alone;
+ * `icon` (a dock icon name, bettercms://icons/dock) and `description` (one line under the label)
+ * are editor chrome. A bare string is a choice whose label is its value.
+ */
+interface ChoiceOption {
+    label: string;
+    value: string;
+    /** A `DockIconName`, typed as a string so a stored row (db `ComponentPropDef`) stays assignable. */
+    icon?: string;
+    description?: string;
+}
 /**
  * ContentModel — the structured content model (schema) for a workspace.
  * Defines which content fields are available for authors to fill in.
@@ -48,7 +62,7 @@ interface ContentModel {
  * by the API but normalized to `array` + zones on write, so stored/delivered
  * content never contains them.
  */
-type ContentModelFieldType = "text" | "richtext" | "document" | "image" | "boolean" | "number" | "select" | "reference" | "multi-reference" | "multiReference" | "array" | "date" | "datetime" | "longtext" | "slug" | "email" | "phone" | "link" | "color" | "json" | "file" | "component-ref" | "modular" | "sections" | "location" | "button" | "multiselect" | "icon";
+type ContentModelFieldType = "text" | "richtext" | "document" | "image" | "boolean" | "number" | "select" | "reference" | "multi-reference" | "multiReference" | "array" | "date" | "datetime" | "longtext" | "slug" | "email" | "phone" | "link" | "color" | "json" | "file" | "component-ref" | "modular" | "sections" | "location" | "button" | "multiselect" | "icon" | "object" | "tags" | "rating" | "code";
 type ContentModelKind = "model" | "block";
 /**
  * How a fieldset renders in the dock. ABSENT ≡ today's flat list (V2): a legacy `{id, name}`
@@ -69,6 +83,11 @@ interface UiBefore {
     position: number;
     label?: string;
     helpText?: string;
+    /** The V2 editor keys, snapshotted with the rest so a Revert restores them. */
+    helpMore?: string;
+    advanced?: boolean;
+    recommendedMax?: number;
+    openMode?: OpenMode;
 }
 /**
  * A fieldset's chrome before the first agent change over a human/derived (or unstamped) state,
@@ -82,6 +101,9 @@ interface FieldsetUiBefore {
         tab?: string;
         icon?: DockIconName;
         collapsed?: boolean;
+        collapsible?: boolean;
+        columns?: 1 | 2;
+        layout?: "stack" | "breakpoints";
     };
     /** Its index among the model's fieldsets before the agent's change; absent on older snapshots. */
     position?: number;
@@ -98,6 +120,12 @@ interface Fieldset {
     collapsed?: boolean;
     /** A group/row that sits inside this `kind:"tab"` fieldset. */
     tab?: string;
+    /** `false`: a static heading with no toggle. */
+    collapsible?: boolean;
+    /** `2`: short fields side by side. */
+    columns?: 1 | 2;
+    /** `breakpoints`: its per-screen-size `object` fields (desktop, tablet, phone; joined by `fieldsetId`) shown as ONE group with a switcher. */
+    layout?: "stack" | "breakpoints";
     uiOrigin?: UiOrigin;
     uiBefore?: FieldsetUiBefore;
 }
@@ -136,7 +164,7 @@ interface FieldConfig {
     timezone?: string;
     /** modular: SLUGS of the kind='block' models this field accepts. Non-empty. */
     blockSlugs?: string[];
-    /** modular: bounds on how many block instances the field may hold. */
+    /** modular: bounds on how many block instances the field may hold; a primitive array (itemType): how many items. */
     minItems?: number;
     maxItems?: number;
     /**
@@ -172,6 +200,19 @@ interface FieldConfig {
     zoneId?: string;
     /** Explicit migration acknowledgement while the legacy allowlist remains readable. */
     legacyResolved?: boolean;
+    /** number: a V2 numeric scale (stepped range or numeric steps, optional units and presets). */
+    scale?: NumberScale;
+    /** number: V2 `validation.min / max`, the error bounds; they win over `min` / `max` (the input's range). */
+    validation?: {
+        min?: number;
+        max?: number;
+    };
+    /** text / longtext / richtext: length in characters (richtext: its plain text). */
+    minLength?: number;
+    maxLength?: number;
+    /** text / longtext: a regex (≤ 200 characters) and the message shown when a value does not match it. */
+    pattern?: string;
+    patternMessage?: string;
     legacyMappings?: Record<string, string>;
     /**
      * image: `"icon"` marks an inline SVG icon the import derived (its value a `data:image/svg+xml`
@@ -179,8 +220,31 @@ interface FieldConfig {
      * and the field-pruning guards leave it alone: an icon is editable content, never markup to tidy.
      */
     media?: "icon";
+    /** multiselect / tags: the choices (tags: suggestions unless allowCustom is false). */
+    options?: Array<string | ChoiceOption>;
     [key: string]: unknown;
 }
+type ScaleUnit = "px" | "%" | "rem" | "em" | "vw" | "vh";
+/** A number field's `config.scale` (V2 scale.ts), numeric values only. Editor-only. */
+interface NumberScale {
+    steps: {
+        min: number;
+        max: number;
+        step?: number;
+    } | Array<{
+        value: number;
+        label?: string;
+    }>;
+    units?: ScaleUnit[];
+    defaultUnit?: ScaleUnit;
+    allowCustom?: boolean;
+    presets?: Array<{
+        label?: string;
+        value: number;
+    }>;
+}
+/** V2: how a compound field (an `object`, or an array's rows) opens when edited. Editor-only. */
+type OpenMode = "inline" | "drill" | "popover" | "dialog";
 /**
  * Where a field renders in the entry editor.
  *
@@ -213,7 +277,8 @@ type ContentModelFieldPlacement = "cover" | "title" | "excerpt" | "body" | "inli
  */
 interface ShowIfRule {
     field: string;
-    op: "eq" | "neq" | "in" | "isSet";
+    /** `notEmpty` ≡ `isSet`; `empty` passes while the source holds nothing. Neither reads `value`. */
+    op: "eq" | "neq" | "in" | "isSet" | "notEmpty" | "empty";
     value?: string | string[];
 }
 interface ShowIf {
@@ -233,9 +298,20 @@ interface ContentModelField {
      */
     unique?: boolean;
     defaultValue?: unknown;
-    options?: string[];
+    /** select: the choices (multiselect / tags keep theirs on `config.options`). */
+    options?: Array<string | ChoiceOption>;
     /** Per-type config. For `array`: either `itemType` (primitive) or `zones` (nested). */
     config?: FieldConfig | null;
+    /** `object`: its child fields. */
+    fields?: ContentModelField[];
+    /** `object` / `array`: how the value (or each row) opens when edited. */
+    openMode?: OpenMode;
+    /** Longer help behind the ⓘ next to the label. Editor-only. */
+    helpMore?: string;
+    /** Tuck into the closed "Advanced" section. Editor-only. */
+    advanced?: boolean;
+    /** A soft limit the editor warns at, never a refusal. */
+    recommendedMax?: number;
     /**
      * Which fieldset this field renders under in the schema builder. Authoring-only: it is
      * never delivered and cannot move a value — see {@link Fieldset}.
@@ -293,6 +369,8 @@ interface ContentModelFieldUi {
         subtitle?: string;
         /** Child field key whose value is the row's thumbnail. Type is not constrained. */
         media?: string;
+        /** A literal row label while the title child is empty ("Untitled question"). Not a key. */
+        fallback?: string;
     };
     /**
      * How the ITEMS of a nesting field are arranged. ABSENT ≡ `"list"` — every field stored
@@ -301,7 +379,7 @@ interface ContentModelFieldUi {
      *
      * Same placement rule as {@link ContentModelFieldUi.preview}: nesting fields only.
      */
-    layout?: "list" | "grid" | "table";
+    layout?: "list" | "grid" | "table" | "rows" | "chips" | "gallery";
     /**
      * Whether the items of a list may be dragged. ABSENT ≡ `true`, for the same reason — nothing
      * stored today carries it, and everything stored today is reorderable.
@@ -399,6 +477,74 @@ declare const SPACE_BOTTOM_TOKENS: ("section-space-none" | "section-space-small"
 /** `var(--bcms-<token>,<px>)`, or "" for anything that is not a known token (closed set). */
 declare function spaceTokenCss(token: unknown): string;
 
+/**
+ * A LINK VALUE: what a `link` field, a `link` prop and a button's `href` store.
+ *
+ * Two shapes, both valid forever:
+ *   - a plain href string ("/about", "https://example.com"), which is what every value stored
+ *     before the V2 link element holds;
+ *   - the V2 link object (dashboard kit `controls/link.tsx`, `LinkValue` after `finalizeLink`):
+ *     `{ type, href, title?, newTab?, target?, rel?, section?, ref? }`.
+ *
+ * `href` is always the final href the site renders (`mailto:`, `tel:`, `#anchor` included), so a
+ * reader that only wants a destination reads `href` and nothing else. `ref` is the id of the page
+ * or CMS item a `page` / `entry` link points at: the write path checks it exists and delivery
+ * resolves it like a reference. Keys the kit writes beside these (`pageId`, `entryId`, `assetId`,
+ * `anchor`, `email`, `subject`, `phone`, `label`) are kept as sent.
+ */
+/** A link's relation beyond a new tab's own `noopener noreferrer`. */
+declare const LINK_RELS: readonly ["nofollow", "sponsored", "ugc"];
+type LinkRel = (typeof LINK_RELS)[number];
+/**
+ * What a link points at. `section` is the kit's spelling of `anchor` (a `#fragment` on the page);
+ * both are accepted and stored as sent.
+ */
+declare const LINK_VALUE_TYPES: readonly ["url", "page", "entry", "email", "phone", "anchor", "section", "file"];
+type LinkValueType = (typeof LINK_VALUE_TYPES)[number];
+interface LinkValue {
+    type?: LinkValueType;
+    href: string;
+    title?: string;
+    newTab?: boolean;
+    /** Legacy mirror of `newTab`; must agree with it. */
+    target?: "_self" | "_blank";
+    /** Absent = a normal link (the kit's "follow" is dropped on write). */
+    rel?: LinkRel;
+    /** The `#anchor` on the target page. */
+    section?: string;
+    /** The page id (`type: "page"`) or entry id (`type: "entry"`) this link points at. */
+    ref?: string;
+}
+/** A link object (`{ href: string, … }`), as opposed to a plain href string. */
+declare function isLinkObject(value: unknown): value is LinkValue & Record<string, unknown>;
+/** A link value's destination: the string itself, or the object's `href`. Null for anything else. */
+declare function linkHref(value: unknown): string | null;
+/** The page or entry a `page` / `entry` link points at, or null. Reads `ref`, then the kit's `pageId` / `entryId`. */
+declare function linkRefOf(value: unknown): {
+    kind: "page" | "entry";
+    id: string;
+} | null;
+/** `javascript:`, `data:` and `vbscript:`, also behind the control characters a URL parser strips. */
+declare const isScriptHref: (href: string) => boolean;
+/**
+ * Why a link OBJECT is not a link value, or null when it is. The href's own grammar (which schemes,
+ * which relative forms) is the caller's rule; this refuses only what no link may be.
+ * Messages start with `link_value_invalid:` so every surface can name the refusal.
+ */
+declare function linkValueProblem(value: unknown): string | null;
+/**
+ * A link value as it is stored: a string as sent; an object with the kit's `rel: "follow"` dropped
+ * (no rel IS a normal link), `newTab` filled from a lone `target`, a page/entry link's
+ * `pageId` / `entryId` copied to `ref`, and the read-only `resolved` dropped. Never invents a destination.
+ */
+declare function normalizeLinkValue<T>(value: T): T;
+/** What an anchor for this link value carries: its href, whether it opens a new tab, and its rel. */
+declare function linkAnchorOf(value: unknown): {
+    href: string;
+    newTab: boolean;
+    rel?: LinkRel;
+} | null;
+
 declare const BUTTON_VARIANTS: readonly ["primary", "secondary", "tertiary", "brand", "dark", "light", "outline", "link"];
 type ButtonVariant = (typeof BUTTON_VARIANTS)[number];
 /** Each icon's inner SVG markup (viewBox `0 0 25 25`), by name. */
@@ -407,6 +553,34 @@ type ButtonIcon = DockIconName;
 declare const BUTTON_ICON_NAMES: readonly ["access-denied", "activity", "add", "add-circle", "add-comment", "add-document", "add-user", "api", "archive", "arrow-down", "arrow-left", "arrow-right", "arrow-top-right", "arrow-up", "asterisk", "bar-chart", "basket", "bell", "bill", "binary-document", "block-content", "block-element", "blockquote", "bold", "bolt", "book", "bookmark", "bookmark-filled", "bottle", "bug", "bulb-filled", "bulb-outline", "calendar", "case", "chart-upward", "checkmark", "checkmark-circle", "chevron-down", "chevron-left", "chevron-right", "chevron-up", "circle", "clipboard", "clipboard-image", "clock", "close", "close-circle", "code", "code-block", "cog", "collapse", "color-wheel", "comment", "component", "compose", "compose-sparkles", "confetti", "controls", "copy", "credit-card", "crop", "cube", "dashboard", "database", "desktop", "diamond", "document", "document-pdf", "document-remove", "document-sheet", "document-text", "document-video", "document-word", "document-zip", "documents", "dot", "double-chevron-down", "double-chevron-left", "double-chevron-right", "double-chevron-up", "double-quote", "download", "drag-handle", "drop", "earth-americas", "earth-globe", "edit", "ellipsis-horizontal", "ellipsis-vertical", "empty", "enter", "enter-right", "envelope", "equal", "error-filled", "error-outline", "error-screen", "expand", "eye-closed", "eye-open", "face-happy", "face-indifferent", "face-sad", "feedback", "filter", "folder", "generate", "github", "groq", "hash", "heart", "heart-filled", "help-circle", "highlight", "home", "ice-cream", "image", "image-remove", "images", "inbox", "info-filled", "info-outline", "inline", "inline-element", "insert-above", "insert-below", "italic", "joystick", "json", "launch", "leave", "lemon", "link", "link-removed", "linkedin", "list", "lock", "logo-js", "logo-ts", "marker", "marker-removed", "master-detail", "menu", "microphone", "microphone-slash", "mobile-device", "moon", "number", "ok-hand", "olist", "overage", "package", "panel-left", "panel-right", "pause", "pin", "pin-filled", "pin-removed", "play", "plug", "presentation", "progress-50", "progress-75", "projects", "publish", "read-only", "redo", "refresh", "remove", "remove-circle", "reset", "restore", "retrieve", "retry", "revert", "robot", "rocket", "schema", "search", "select", "share", "sort", "sparkle", "sparkles", "spinner", "split-horizontal", "split-vertical", "square", "stack", "stack-compact", "star", "star-filled", "stop", "strikethrough", "string", "sun", "sync", "tablet-device", "tag", "tags", "target", "task", "terminal", "text", "th-large", "th-list", "thumbs-down", "thumbs-up", "tiers", "timeline", "toggle-arrow-right", "token", "transfer", "translate", "trash", "trend-upward", "triangle-outline", "trolley", "truncate", "twitter", "ulist", "unarchive", "underline", "undo", "unknown", "unlink", "unlock", "unpublish", "upload", "user", "users", "versions", "video", "warning-filled", "warning-outline", "wrench"];
 /** A stored variant as it renders: anything off the list is Primary. */
 declare function buttonVariantOf(value: unknown): ButtonVariant;
+/**
+ * How an IMPORTED site draws one look of its Button family: the classes its own stylesheet PAINTS
+ * the look by, the `data-variant` it keys the look on when it uses one, and the paint classes of
+ * every other spelling of the same look (`also`), which a publish takes off the anchor with the rest.
+ * A look comes in sizes: `size` are the classes that size its most-used spelling and `sizeAlso`
+ * those of the others. A publish leaves a button's size classes on it and adds `size` only to a
+ * button that has none. Measured from the built site and stored on the look's button block as
+ * `props.siteLook`.
+ */
+interface ButtonSiteLook {
+    classes: string[];
+    attrs?: {
+        "data-variant"?: string;
+    };
+    also?: string[];
+    size?: string[];
+    sizeAlso?: string[];
+}
+/** A button block's `props.siteLook`, read defensively: null when it names nothing to paint with. */
+declare function buttonSiteLookOf(value: unknown): ButtonSiteLook | null;
+/**
+ * The value a `button` stores to pick one look of the project's Button family: what the site's own
+ * `data-variant` calls the look when it keys on one, the look's component slug otherwise. A
+ * publish writes it back as the anchor's `data-variant`.
+ */
+declare function buttonLookValue(slug: string, siteLook: ButtonSiteLook | null): string;
+/** Is this a value that could name a family look (or one of the fixed names)? */
+declare function isButtonLookValue(value: unknown): value is string;
 /** A stored icon as it renders: anything off the list is no icon. */
 declare function buttonIconOf(value: unknown): ButtonIcon | null;
 /** One icon as inline SVG sized to the button's text, hidden from assistive tech (the label names the button). */
@@ -418,8 +592,6 @@ type ButtonSizeName = (typeof BUTTON_SIZES)[number];
  * object. Only `label` and `href` are required; every look key is optional and absent reads as
  * today's default (Primary, medium, no arrow, no icon, same tab).
  */
-declare const LINK_RELS: readonly ["nofollow", "sponsored", "ugc"];
-type LinkRel = (typeof LINK_RELS)[number];
 /**
  * The target and rel attributes of an anchor, as one string. A new tab keeps the `noopener
  * noreferrer` pair; a link relation joins it in the SAME rel attribute, so an anchor never
@@ -428,7 +600,8 @@ type LinkRel = (typeof LINK_RELS)[number];
 declare function anchorTargetRel(newTab: boolean, rel?: unknown): string;
 interface ButtonValue {
     label: string;
-    href: string;
+    /** A plain href, or a link object (@see LinkValue) whose newTab / rel apply when the button sets none. */
+    href: string | LinkValue;
     variant?: ButtonVariant;
     size?: ButtonSizeName;
     arrow?: boolean;
@@ -438,11 +611,17 @@ interface ButtonValue {
     rel?: LinkRel;
 }
 /** A stored button value as it renders: `rel` stays optional, every other key is filled. */
-type ReadButtonValue = Required<Omit<ButtonValue, "rel">> & Pick<ButtonValue, "rel">;
+type ReadButtonValue = Required<Omit<ButtonValue, "rel" | "href">> & Pick<ButtonValue, "rel"> & {
+    href: string;
+};
 /** A stored button value as it renders: every key read through the same allow-lists as a block. */
 declare function readButtonValue(value: unknown): ReadButtonValue;
-/** Why a value is not a button, or null when it is. Look keys are checked only when present. */
-declare function buttonValueProblem(value: unknown): string | null;
+/**
+ * Why a value is not a button, or null when it is. Look keys are checked only when present.
+ * `looks` are the values that pick a look of the project's own Button family (@see
+ * buttonLookValue): a variant is one of those or one of the fixed names.
+ */
+declare function buttonValueProblem(value: unknown, looks?: ReadonlySet<string>): string | null;
 /** The look keys an instance of a Button component may override, beside its label and link. */
 declare const BUTTON_LOOK_KEYS: readonly ["variant", "size", "arrow", "icon", "newTab"];
 type ButtonLookKey = (typeof BUTTON_LOOK_KEYS)[number];
@@ -721,8 +900,11 @@ interface ImageBlock {
 interface ButtonProps {
     text: string;
     href: string;
-    /** Absent or off the list ⇒ "primary". Renders `bcms-btn-{variant}`. */
-    variant?: ButtonVariant;
+    /**
+     * One of the fixed names, which render `bcms-btn-{variant}`, or the value of a look of the
+     * project's own Button family (@see buttonLookValue). Absent ⇒ "primary".
+     */
+    variant?: ButtonVariant | (string & {});
     /** Padding + font-size step. Absent ⇒ "md", today's button. sm/lg render `bcms-btn-sm|lg`. */
     size?: "sm" | "md" | "lg";
     /** Stretch to the column's width. Absent ⇒ false. true renders `bcms-btn-full`. */
@@ -1280,14 +1462,25 @@ declare function splitButtonStyle(style: BlockStyle | undefined): {
 };
 /**
  * The style keys a PAGE FIELD takes (`pages.field_styles`, keyed by field path): its width and
- * placement, the space above and below it, and its text alignment, size and weight. A subset of
- * `BlockStyle`, so every key keeps the token set and the CSS table it already has — a field never
- * gets a second scale. 🔴 Twin: `FIELD_STYLE_KEYS` in the dashboard's fieldStyle.ts.
+ * placement, the space above and below it, its text alignment, font size and weight, and `size` — a
+ * whole element's Small / Large (a button's). Every key but `size` is a `BlockStyle` key, so it
+ * keeps the token set and the CSS table it already has — a field never gets a second scale.
+ * 🔴 Twin: `FIELD_STYLE_KEYS` in the dashboard's fieldStyle.ts.
  */
-declare const FIELD_STYLE_KEYS: readonly ["contentWidth", "contentAlign", "marginTop", "marginBottom", "align", "fontSize", "weight"];
+declare const FIELD_STYLE_KEYS: readonly ["contentWidth", "contentAlign", "marginTop", "marginBottom", "align", "fontSize", "weight", "size"];
 type FieldStyleKey = (typeof FIELD_STYLE_KEYS)[number];
+/** A field element's Small / Large. Medium is UNSET — no "md" token is ever stored. */
+type FieldSize = "sm" | "lg";
+/**
+ * `size` → the element's `zoom`, which scales the WHOLE element (padding, font, icon, border) — what
+ * Small / Large mean for a button whose CSS the site wrote. Any other value (`md` included) paints
+ * nothing. 🔴 Inlined in the convert helper (`STYLE_SIZE_ZOOM`), parity-tested against this table.
+ */
+declare const FIELD_SIZE_ZOOM: Readonly<Record<FieldSize, string>>;
 /** One field's style. */
-type FieldStyle = Pick<BlockStyle, FieldStyleKey>;
+type FieldStyle = Pick<BlockStyle, Exclude<FieldStyleKey, "size">> & {
+    size?: FieldSize;
+};
 /** A page's field styles, keyed by field path (the `data-bcms-field` address). */
 type FieldStyles = Record<string, FieldStyle>;
 /** Only the field keys of `style` (an empty object for none). */
@@ -1296,7 +1489,9 @@ declare function pickFieldStyle(style: BlockStyle | Record<string, unknown> | nu
  * A field's declarations, for its OWN element (`fieldAttrs`). Spacing, alignment, size and weight are
  * `blockStyleToCss`'s. The width is `blockStyleToInnerCss`'s column, drawn on the element itself —
  * a field has no wrapper to nest a column in — so its placement becomes left/right margins, and
- * the vertical margins the spacing set stay. `undefined` when nothing applies (no `style` at all).
+ * the vertical margins the spacing set stay. `size` (`FIELD_SIZE_ZOOM`) is LAST, so a style without
+ * it keeps the exact declarations, in the exact order, it always had. `undefined` when nothing
+ * applies (no `style` at all).
  */
 declare function fieldStyleToCss(style: BlockStyle | Record<string, unknown> | null | undefined): Record<string, string | number> | undefined;
 /**
@@ -1758,7 +1953,7 @@ type ComponentCategory = "navbar" | "footer" | "button" | "section" | "slider" |
  *
  * Order is not semantic; append rather than re-sort, so a diff stays readable.
  */
-declare const COMPONENT_PROP_TYPES: readonly ["text", "richtext", "image", "url", "boolean", "number", "select", "group", "table", "slot", "form", "link", "button", "date", "color", "file", "icon", "multiselect"];
+declare const COMPONENT_PROP_TYPES: readonly ["text", "richtext", "image", "url", "boolean", "number", "select", "group", "table", "slot", "form", "link", "button", "date", "color", "file", "icon", "multiselect", "object", "datetime", "slug", "email", "phone", "json", "location", "tags", "rating", "code", "reference", "multi-reference"];
 type ComponentPropType = (typeof COMPONENT_PROP_TYPES)[number];
 /**
  * The value a `form` prop STORES: just the id. The form itself is a Form document and stays the
@@ -1813,9 +2008,14 @@ interface ComponentPropDef {
      *   file   → `{ url, name?, size? }`, or a bare URL string
      *   icon   → a BetterCMS icon name (`DOCK_ICON_NAMES`), or an uploaded icon as an image value
      *   multiselect → a `string[]`, each one of `config.options`
-     *
-     * `reference` is absent on purpose: nothing resolves a content-entry id at component render
-     * time, so such a prop would save cleanly and render as nothing.
+     *   object → ONE `{ [childKey]: value }` keyed by `config.fields` (the V2 model-field `object`)
+     *   datetime · slug · email · phone · json · location → what the same-named model FIELD stores
+     *   tags · rating · code → what the same-named model FIELD stores (a string[], a number,
+     *            `{ language?, code }` or a string)
+     *   reference · multi-reference → what the same-named model FIELD stores: an entry id, or a
+     *            list of them (`config.contentModelId`, or `polymorphic` + `allowedModelSlugs`;
+     *            `min`/`max` on the list). Delivery and preview hydrate the ids in a page's overrides
+     *            to entries at the read's `depth`; a plain-text slot renders the entry's title.
      */
     type: ComponentPropType;
     defaultValue?: unknown;
@@ -1840,6 +2040,17 @@ interface ComponentPropDef {
      * key) hold these values. The save schema refuses a key no prop of the component declares.
      */
     showIf?: ShowIf;
+    /** V2 editor-only keys, as on a model field. @see ContentModelField.helpMore */
+    helpMore?: string;
+    advanced?: boolean;
+    recommendedMax?: number;
+    /**
+     * F1.x: a list prop's items (a table's rows) distinct; on a table sub-field, no two rows share
+     * the value. Refused (`unique_prop_scope`) on a top-level scalar: nothing to be unique across.
+     */
+    unique?: boolean;
+    /** `object` / `group` / `table`: how the value (or each row) opens when edited. */
+    openMode?: OpenMode;
     /**
      * The content-model field's `readOnly` / `lockReason` pair, as STORED MARKERS only: the
      * editor may render the prop read-only, and no write of a prop value is refused for them.
@@ -1859,16 +2070,28 @@ interface ComponentPropDef {
          * `select` / `multiselect` — the choices. Required, and a default must be one of them. `{ label, value }`
          * when the stored value is not what an author should read (a component id, for instance).
          */
-        options?: Array<string | {
-            label: string;
-            value: string;
-        }>;
-        /** `group` / `table` — the sub-shape, nestable to 3 levels. */
+        options?: Array<string | ChoiceOption>;
+        /** `group` / `table` / `object` — the sub-shape; 10 levels at most, counting the prop (MAX_FIELD_DEPTH). */
         fields?: ComponentSubField[];
-        /** `number` — bounds for the control. */
+        /** `number` — bounds for the control; `multiselect` / `tags` / `multi-reference` — how many items. */
         min?: number;
         max?: number;
         step?: number;
+        /** `number` — V2 `validation.min / max`: the error bounds, which win over `min` / `max`. */
+        validation?: {
+            min?: number;
+            max?: number;
+        };
+        /** `text` / `url` / `richtext` — length in characters (richtext: its plain text). */
+        minLength?: number;
+        maxLength?: number;
+        /** `text` / `url` — a regex (≤ 200 characters) and the message shown when it does not match. */
+        pattern?: string;
+        patternMessage?: string;
+        /** `reference` / `multi-reference` — the target model, or `polymorphic` with an allowlist of model slugs. */
+        contentModelId?: string;
+        polymorphic?: boolean;
+        allowedModelSlugs?: string[];
     } & Record<string, unknown>;
     /**
      * AUTHORING CHROME — the same object a content-model FIELD carries ({@link ContentModelFieldUi}),
@@ -1906,7 +2129,7 @@ interface PropGroup {
 type ComponentPropUi = ContentModelFieldUi & {
     group?: PropGroup;
 };
-/** One field inside a `group` prop or a `table` row. Recursive, capped at 3 levels deep. */
+/** One field inside a `group` / `object` prop or a `table` row. Recursive, 10 levels at most counting the prop (MAX_FIELD_DEPTH). */
 interface ComponentSubField {
     key: string;
     label: string;
@@ -1918,8 +2141,17 @@ interface ComponentSubField {
     helpText?: string;
     helpSource?: "auto" | "human" | "agent";
     placeholder?: string;
-    options?: string[];
-    /** CANONICAL. A nested `group`/`table`'s own sub-shape. */
+    options?: Array<string | ChoiceOption>;
+    /** The V2 editor keys, one level down. `showIf` names SIBLING sub-fields. @see ComponentPropDef */
+    helpMore?: string;
+    advanced?: boolean;
+    recommendedMax?: number;
+    /** On a table's sub-field: no two rows share the value; on a list: no item repeats. */
+    unique?: boolean;
+    openMode?: OpenMode;
+    showIf?: ShowIf;
+    ui?: ContentModelFieldUi;
+    /** CANONICAL. A nested `group`/`table`/`object`'s own sub-shape. */
     fields?: ComponentSubField[];
     /**
      * A READ-ONLY MIRROR of `options`/`fields`, in the shape `ComponentPropDef` puts them in.
@@ -1937,7 +2169,7 @@ interface ComponentSubField {
      */
     config?: {
         fields?: ComponentSubField[];
-        options?: string[];
+        options?: Array<string | ChoiceOption>;
     } & Record<string, unknown>;
 }
 /** The value a `slot` prop holds — the draft half of a `component-ref`, deliberately. */
@@ -2847,4 +3079,4 @@ declare function regionOf<E extends {
     el: E;
 }[], el: unknown): string | null;
 
-export { type AlignToken, type ApiError, type ApiKey, type ApiKeyPermission, type ApiKeyTokenType, type ArrayZoneConfig, type AssertEqual, type AuthResponse, type AuthSession, type AuthUser, BLOCK_BINDINGS, BREAKPOINTS, BUTTON_ICONS, BUTTON_ICON_NAMES, BUTTON_LOOK_KEYS, BUTTON_PLACEMENT_KEYS, BUTTON_SIZES, BUTTON_VARIANTS, type BetterCMSErrorCode, type BgToken, type BindingKind, type BlockBinding, type BlockHoverStyle, type BlockStyle, type BlockType, type ButtonBlock, type ButtonIcon, type ButtonLinkCandidate, type ButtonLookKey, type ButtonProps, type ButtonSizeName, type ButtonValue, type ButtonVariant, COMPONENT_PROP_TYPES, type CanonicalInputDefinition, type CollectionBlock, type CollectionFilter, type CollectionProps, type ColorToken, type ColumnsBlock, type ColumnsProps, type Component, type ComponentBlock, type ComponentCategory, type ComponentFormPropRef, type ComponentPropDef, type ComponentPropType, type ComponentPropUi, type ComponentProps, type ComponentSubField, type ComponentVariantGroup, type Content, type ContentBlock, type ContentEntry, type ContentModel, type ContentModelField, type ContentModelFieldType, type ContentModelFieldUi, type ContentPageResult, type ContentResponse, type ContentWidthToken, type CornerToken, DIALOG_SELECTOR, DOCK_BUDGET, DOCK_ICON_NAMES, DOCK_ICON_NAME_SET, type DeepReadonly, type DeliveredLayout, type DeliveryComponent, type DeliveryEntry, type DeliveryEntrySeo, type DeliveryList, type DeliveryPage, type DerivedLocator, type DockBudget, type DockFieldLike, type DockFieldsetLike, type DockIconName, type DockInputRef, type DockLane, type DockNode, type DockPropGroupLike, type DockScreen, type ElementLike, type ExpandedBinding, FIELD_STYLE_KEYS, FOOTER_SECTION_ID, type FieldConfig, type FieldStyle, type FieldStyleKey, type FieldStyles, type Fieldset, type FieldsetKind, type FieldsetUiBefore, type FontSizeToken, type FooterBlock, type FooterColumn, type FooterProps, type Form, type FormBlock, type FormField, type FormProps, type FormSubmission, type HeadingBlock, type HeadingProps, type ImageBlock, type ImageProps, LANDMARK_SELECTOR, LAYOUT_SECTION_ICONS, LAYOUT_SECTION_ICON_SET, LINK_RELS, type LandmarkChainElement, type LandmarkElement, type LayoutComponentItem, type LayoutDataDocument, type LayoutFieldDefinition, type LayoutFieldItem, type LayoutFieldType, type LayoutScalarFieldType, type LayoutSection, type LayoutSectionIcon, type LayoutSectionItem, type LayoutStructureDocument, type LayoutZone, type LinkRel, type LocatorGrammar, MAIN_SELECTOR, type ManagementLayoutCommand, type MediaAsset, type MediaCaptionTrack, type MediaFieldValue, NAVIGATION_SECTION_ID, type NavLink, type NavbarBlock, type NavbarProps, PAGE_CONTENT_ANCHOR_ID, type Page, type PageLayoutOverrideDataDocument, type PageLayoutOverrideDocument, type PageLayoutOverrideState, type PageLayoutOverrideStructureDocument, type PageLayoutSectionOverride, type PageLayoutSectionStructureOverride, type PageMetaJson, type PageOnlyLayoutSection, type PageSectionPlacement, type PaginatedResult, type Perspective, type PortableTextDocument, type PortableTextNode, type PropGroup, RESPONSIVE_CSS, type RadiusToken, type ReadButtonValue, type Redirect, type ReservedLayoutSection, type ResolvedLayoutNode, type RichTextBlock, type RichTextProps, SECTION_DOCTRINE, SECTION_SPACE_TOKENS, SLOT_ITEMS_CAP, SLOT_MAX_ITEMS, SPACE_BOTTOM_TOKENS, SPACE_STEP_TOKENS, type SectionBlock, type SectionProps, type SectionSpaceToken, type ShadowToken, type ShowIf, type ShowIfRule, type SignInInput, type SignUpInput, type SiteSeoDefaults, type SlideItem, type SliderBlock, type SliderProps, type SlotItem, type SlotValue, type SpaceStepToken, type SpaceToken, type SpacerBlock, type SpacerProps, type TabItem, type TabsBlock, type TabsProps, type TextBlock, type TextProps, type ThemeToken, type UiBefore, type UiOrigin, type VariantInputMapping, type VideoBlock, type VideoProps, type VisibilityWindow, type WeightToken, type WindowState, type Workspace, type ZoneField, anchorTargetRel, blockStyleToColumnCss, blockStyleToCss, blockStyleToInnerCss, buttonBlockProps, buttonIconOf, buttonIconSvg, buttonLinkPairs, buttonValueOfInstance, buttonValueProblem, buttonVariantOf, candidateRole, componentInstanceAddresses, componentPropTargetKey, derivedPairs, dockBudget, dockScreens, expandBlockBindings, fieldStyleCssText, fieldStyleToCss, formatPropsAttribute, getBlockType, headingPaintCss, hideOnAttr, inWindow, isBlock, isChromeLandmark, keyWords, landmarkRegions, locatorFor, normalizeWindow, parsePropsAttribute, pickFieldStyle, readButtonValue, readPath, regionOf, safeCssUrl, slotItems, spaceTokenCss, splitButtonStyle, usesHideOn, visibleBlocks, visibleDeliveredLayout, visibleLayoutStructure, windowState, withButtonLookProps };
+export { type AlignToken, type ApiError, type ApiKey, type ApiKeyPermission, type ApiKeyTokenType, type ArrayZoneConfig, type AssertEqual, type AuthResponse, type AuthSession, type AuthUser, BLOCK_BINDINGS, BREAKPOINTS, BUTTON_ICONS, BUTTON_ICON_NAMES, BUTTON_LOOK_KEYS, BUTTON_PLACEMENT_KEYS, BUTTON_SIZES, BUTTON_VARIANTS, type BetterCMSErrorCode, type BgToken, type BindingKind, type BlockBinding, type BlockHoverStyle, type BlockStyle, type BlockType, type ButtonBlock, type ButtonIcon, type ButtonLinkCandidate, type ButtonLookKey, type ButtonProps, type ButtonSiteLook, type ButtonSizeName, type ButtonValue, type ButtonVariant, COMPONENT_PROP_TYPES, type CanonicalInputDefinition, type ChoiceOption, type CollectionBlock, type CollectionFilter, type CollectionProps, type ColorToken, type ColumnsBlock, type ColumnsProps, type Component, type ComponentBlock, type ComponentCategory, type ComponentFormPropRef, type ComponentPropDef, type ComponentPropType, type ComponentPropUi, type ComponentProps, type ComponentSubField, type ComponentVariantGroup, type Content, type ContentBlock, type ContentEntry, type ContentModel, type ContentModelField, type ContentModelFieldType, type ContentModelFieldUi, type ContentPageResult, type ContentResponse, type ContentWidthToken, type CornerToken, DIALOG_SELECTOR, DOCK_BUDGET, DOCK_ICON_NAMES, DOCK_ICON_NAME_SET, type DeepReadonly, type DeliveredLayout, type DeliveryComponent, type DeliveryEntry, type DeliveryEntrySeo, type DeliveryList, type DeliveryPage, type DerivedLocator, type DockBudget, type DockFieldLike, type DockFieldsetLike, type DockIconName, type DockInputRef, type DockLane, type DockNode, type DockPropGroupLike, type DockScreen, type ElementLike, type ExpandedBinding, FIELD_SIZE_ZOOM, FIELD_STYLE_KEYS, FOOTER_SECTION_ID, type FieldConfig, type FieldSize, type FieldStyle, type FieldStyleKey, type FieldStyles, type Fieldset, type FieldsetKind, type FieldsetUiBefore, type FontSizeToken, type FooterBlock, type FooterColumn, type FooterProps, type Form, type FormBlock, type FormField, type FormProps, type FormSubmission, type HeadingBlock, type HeadingProps, type ImageBlock, type ImageProps, LANDMARK_SELECTOR, LAYOUT_SECTION_ICONS, LAYOUT_SECTION_ICON_SET, LINK_RELS, LINK_VALUE_TYPES, type LandmarkChainElement, type LandmarkElement, type LayoutComponentItem, type LayoutDataDocument, type LayoutFieldDefinition, type LayoutFieldItem, type LayoutFieldType, type LayoutScalarFieldType, type LayoutSection, type LayoutSectionIcon, type LayoutSectionItem, type LayoutStructureDocument, type LayoutZone, type LinkRel, type LinkValue, type LinkValueType, type LocatorGrammar, MAIN_SELECTOR, type ManagementLayoutCommand, type MediaAsset, type MediaCaptionTrack, type MediaFieldValue, NAVIGATION_SECTION_ID, type NavLink, type NavbarBlock, type NavbarProps, type NumberScale, OPTION_DESCRIPTION_MAX, type OpenMode, PAGE_CONTENT_ANCHOR_ID, type Page, type PageLayoutOverrideDataDocument, type PageLayoutOverrideDocument, type PageLayoutOverrideState, type PageLayoutOverrideStructureDocument, type PageLayoutSectionOverride, type PageLayoutSectionStructureOverride, type PageMetaJson, type PageOnlyLayoutSection, type PageSectionPlacement, type PaginatedResult, type Perspective, type PortableTextDocument, type PortableTextNode, type PropGroup, RESPONSIVE_CSS, type RadiusToken, type ReadButtonValue, type Redirect, type ReservedLayoutSection, type ResolvedLayoutNode, type RichTextBlock, type RichTextProps, SECTION_DOCTRINE, SECTION_SPACE_TOKENS, SLOT_ITEMS_CAP, SLOT_MAX_ITEMS, SPACE_BOTTOM_TOKENS, SPACE_STEP_TOKENS, type ScaleUnit, type SectionBlock, type SectionProps, type SectionSpaceToken, type ShadowToken, type ShowIf, type ShowIfRule, type SignInInput, type SignUpInput, type SiteSeoDefaults, type SlideItem, type SliderBlock, type SliderProps, type SlotItem, type SlotValue, type SpaceStepToken, type SpaceToken, type SpacerBlock, type SpacerProps, type TabItem, type TabsBlock, type TabsProps, type TextBlock, type TextProps, type ThemeToken, type UiBefore, type UiOrigin, type VariantInputMapping, type VideoBlock, type VideoProps, type VisibilityWindow, type WeightToken, type WindowState, type Workspace, type ZoneField, anchorTargetRel, blockStyleToColumnCss, blockStyleToCss, blockStyleToInnerCss, buttonBlockProps, buttonIconOf, buttonIconSvg, buttonLinkPairs, buttonLookValue, buttonSiteLookOf, buttonValueOfInstance, buttonValueProblem, buttonVariantOf, candidateRole, componentInstanceAddresses, componentPropTargetKey, derivedPairs, dockBudget, dockScreens, expandBlockBindings, fieldStyleCssText, fieldStyleToCss, formatPropsAttribute, getBlockType, headingPaintCss, hideOnAttr, inWindow, isBlock, isButtonLookValue, isChromeLandmark, isLinkObject, isScriptHref, keyWords, landmarkRegions, linkAnchorOf, linkHref, linkRefOf, linkValueProblem, locatorFor, normalizeLinkValue, normalizeWindow, parsePropsAttribute, pickFieldStyle, readButtonValue, readPath, regionOf, safeCssUrl, slotItems, spaceTokenCss, splitButtonStyle, usesHideOn, visibleBlocks, visibleDeliveredLayout, visibleLayoutStructure, windowState, withButtonLookProps };