@plumix/core 0.6.0 → 0.7.0

package/dist/plugin/manifest.d.ts

@@ -11,6 +11,7 @@ import type { CustomArchiveData } from "../route/render/resolved-entry.js";
 import type { NamedTemplateChoice } from "../route/render/template-builders.js";
 import type { RegisteredTemplateDep } from "../template-deps.js";
 import type { PluginI18nSlot } from "./define.js";
+import type { MetaFieldCondition } from "./fields/condition.js";
 import type { RegisteredLookupAdapter } from "./lookup.js";
 export type { NamedTemplateChoice } from "../route/render/template-builders.js";
 export { NAMED_TEMPLATE_META_KEY } from "../route/render/template-builders.js";
@@ -236,6 +237,13 @@ export declare function manifestEntryVisibility(entry: Pick<EntryTypeManifestEnt
     readonly showInSidebar: boolean;
 };
 export type MetaScalarType = "string" | "number" | "boolean" | "json";
+/**
+ * Stored shape of a field's `.validate()` callback. Sync or async;
+ * `true` means valid, a `Label` is the failure message surfaced to the
+ * editor. The fluent chain types the parameter with the field's
+ * narrowed value type; the definition stores it broad.
+ */
+export type MetaBoxFieldValidate = (value: unknown) => true | Label | Promise<true | Label>;
 export interface MetaBoxFieldOption {
     readonly value: string;
     readonly label: Label;
@@ -255,6 +263,8 @@ export type MetaBoxFieldSpan = number | {
     readonly md?: number;
     readonly lg?: number;
 };
+export type { MetaFieldCondition, MetaFieldConditionOperator, MetaFieldConditionRule, } from "./fields/condition.js";
+export { isFieldVisible } from "./fields/condition.js";
 /**
  * Shared shape for every meta-box field variant — properties carried
  * regardless of `inputType`. Each narrowed variant of `MetaBoxField`
@@ -276,6 +286,16 @@ export interface MetaBoxFieldBase {
      * whitelisting, or normalising shape.
      */
     readonly sanitize?: (value: unknown) => unknown;
+    /**
+     * Custom validation predicate — see `MetaBoxFieldValidate`. Executed
+     * server-side by the constraint walker, after `.sanitize()` and the
+     * declarative constraints.
+     */
+    readonly validate?: MetaBoxFieldValidate;
+    /** Static adornment rendered before the input (e.g. a URL scheme). */
+    readonly prepend?: Label;
+    /** Static adornment rendered after the input (e.g. a unit suffix). */
+    readonly append?: Label;
     /** Default surfaced in the admin form when the key has no saved value. */
     readonly default?: unknown;
     /** Optional help text rendered under the label on every input type. */
@@ -303,27 +323,42 @@ export interface MetaBoxFieldBase {
      * so internal fields never leak by default. Has no effect on the admin RPC.
      */
     readonly showInApi?: boolean;
+    /**
+     * Conditional visibility — OR-of-AND rule groups addressing sibling
+     * driver fields by key, authored via the builders'
+     * `.visibleWhen()` / `.orVisibleWhen()` chains. Semantics live in
+     * `isFieldVisible`.
+     */
+    readonly visibleWhen?: MetaFieldCondition;
 }
+/** The five string-scalar input types sharing one field shape. */
+export type StringInputType = "text" | "textarea" | "email" | "url" | "password";
 /**
- * The narrowed `text` field variant produced by the `text()` builder
- * helper exported from `plumix/fields`. The builder rejects options
- * that don't apply to a text input (e.g. `min`, `step`, `options`) at
- * the type level; downstream consumers can rely on the narrowed shape
- * via the `inputType` discriminator.
+ * Shared shape of the five string scalar variants produced by the
+ * fluent builders exported from `plumix/fields` — they differ only in
+ * their `inputType` literal. Downstream consumers rely on the narrowed
+ * shape via the `inputType` discriminator.
  */
-export interface TextMetaBoxField extends MetaBoxFieldBase {
-    readonly inputType: "text";
+export interface StringMetaBoxField<I extends StringInputType = StringInputType> extends MetaBoxFieldBase {
+    readonly inputType: I;
     readonly type: "string";
     readonly placeholder?: Label;
     readonly maxLength?: number;
 }
+/** Single-line text input. */
+export type TextMetaBoxField = StringMetaBoxField<"text">;
 /** Multi-line text input. Storage shape mirrors `text`. */
-export interface TextareaMetaBoxField extends MetaBoxFieldBase {
-    readonly inputType: "textarea";
-    readonly type: "string";
-    readonly placeholder?: Label;
-    readonly maxLength?: number;
-}
+export type TextareaMetaBoxField = StringMetaBoxField<"textarea">;
+/** RFC-5322-shaped email input. */
+export type EmailMetaBoxField = StringMetaBoxField<"email">;
+/** URL input. */
+export type UrlMetaBoxField = StringMetaBoxField<"url">;
+/**
+ * Masked-input password field. Visually hides characters in the admin
+ * so values aren't shoulder-surfable in shared sessions; storage
+ * shape mirrors `text`.
+ */
+export type PasswordMetaBoxField = StringMetaBoxField<"password">;
 /** Numeric input with optional `min` / `max` / `step` bounds. */
 export interface NumberMetaBoxField extends MetaBoxFieldBase {
     readonly inputType: "number";
@@ -333,75 +368,73 @@ export interface NumberMetaBoxField extends MetaBoxFieldBase {
     readonly max?: number;
     readonly step?: number;
 }
-/** RFC-5322-shaped email input. */
-export interface EmailMetaBoxField extends MetaBoxFieldBase {
-    readonly inputType: "email";
-    readonly type: "string";
-    readonly placeholder?: Label;
-    readonly maxLength?: number;
-}
-/** URL input. */
-export interface UrlMetaBoxField extends MetaBoxFieldBase {
-    readonly inputType: "url";
-    readonly type: "string";
-    readonly placeholder?: Label;
-    readonly maxLength?: number;
-}
+/** The three temporal input types sharing one field shape. */
+export type TemporalInputType = "date" | "datetime" | "time";
 /**
- * Masked-input password field. Visually hides characters in the admin
- * so values aren't shoulder-surfable in shared sessions; storage
- * shape mirrors `text`.
+ * Shared shape of the three temporal variants produced by the fluent
+ * builders — they differ only in their `inputType` literal and the
+ * ISO shape of the stored string. `min` / `max` bounds use the same
+ * format as the stored value; the constraint walker enforces them
+ * server-side (ISO shapes compare lexicographically in temporal
+ * order).
+ *
+ * `returns: "date"` opts the field's reads into a decode-time
+ * projection: the stored ISO string is handed to consumers as a JS
+ * `Date` with its wall-clock components anchored to UTC (a `time`
+ * value anchors to 1970-01-01 UTC). Storage and the write contract
+ * stay ISO strings either way.
  */
-export interface PasswordMetaBoxField extends MetaBoxFieldBase {
-    readonly inputType: "password";
+export interface TemporalMetaBoxField<I extends TemporalInputType = TemporalInputType> extends MetaBoxFieldBase {
+    readonly inputType: I;
     readonly type: "string";
-    readonly placeholder?: Label;
-    readonly maxLength?: number;
+    readonly min?: string;
+    readonly max?: string;
+    readonly returns?: "date";
 }
+/**
+ * Format a UTC-anchored `Date` into the ISO string shape a temporal
+ * field stores (`YYYY-MM-DD`, `YYYY-MM-DDTHH:MM[:SS]`, `HH:MM[:SS]`).
+ * Seconds appear only when nonzero, mirroring what the native inputs
+ * emit. Shared by the server-side meta write encoder and the admin's
+ * input prefill so the two can't drift; callers guard invalid Dates.
+ */
+export declare function formatTemporalValue(inputType: TemporalInputType, value: Date): string;
+export declare function isTemporalInputType(inputType: string): inputType is TemporalInputType;
+/**
+ * Anchor a stored temporal string to a UTC-parseable form — `date` at
+ * UTC midnight, `time` on 1970-01-01 UTC. The single source of the
+ * anchoring rule shared by the read-side `Date` projection and the
+ * write-side validity check, which must stay exact inverses of
+ * `formatTemporalValue`.
+ */
+export declare function anchorTemporalUtc(inputType: TemporalInputType, value: string): string;
+/** Whether a string is a well-formed stored value (shape + real
+ *  wall-clock) for the given temporal input type. */
+export declare function isValidTemporalValue(inputType: TemporalInputType, value: string): boolean;
 /**
  * Date-only field. Stored as `YYYY-MM-DD` (ISO 8601 calendar date,
- * no time, no timezone). Optional `min` / `max` bounds use the same
- * format and are enforced as registration-time validation only —
- * server-side bound enforcement is deferred to a later release.
+ * no time, no timezone).
  */
-export interface DateMetaBoxField extends MetaBoxFieldBase {
-    readonly inputType: "date";
-    readonly type: "string";
-    readonly min?: string;
-    readonly max?: string;
-}
+export type DateMetaBoxField = TemporalMetaBoxField<"date">;
 /**
  * Date + time field. Stored as a partial ISO 8601 string
  * (`YYYY-MM-DDTHH:MM` with optional `:SS`) reflecting whatever the
- * author's browser produced via `<input type="datetime-local">`. A
- * future iteration may bake in the browser's timezone offset so the
- * wall-clock semantics survive cross-region reads; today's storage is
- * naive local time and consumers anchor to a timezone explicitly via
- * `parseMetaDate` + their own `Temporal.ZonedDateTime` shaping if
- * needed.
- */
-export interface DateTimeMetaBoxField extends MetaBoxFieldBase {
-    readonly inputType: "datetime";
-    readonly type: "string";
-    readonly min?: string;
-    readonly max?: string;
-}
+ * author's browser produced via `<input type="datetime-local">` —
+ * naive local time, no timezone offset baked in. Consumers who need
+ * timezone semantics anchor explicitly via `parseMetaDate` + their
+ * own `Temporal.ZonedDateTime` shaping.
+ */
+export type DateTimeMetaBoxField = TemporalMetaBoxField<"datetime">;
 /**
  * Time-only field. Stored as `HH:MM` (with optional `:SS`). No date
  * anchor, no timezone — useful for "open at 09:00" style values where
  * the calendar date is supplied separately.
  */
-export interface TimeMetaBoxField extends MetaBoxFieldBase {
-    readonly inputType: "time";
-    readonly type: "string";
-    readonly min?: string;
-    readonly max?: string;
-}
+export type TimeMetaBoxField = TemporalMetaBoxField<"time">;
 /**
  * Hex color picker. Stored as a `#xxxxxx` string (the format the
- * native `<input type="color">` produces). The builder injects a
- * default sanitizer that rejects values that don't match the hex
- * shape on write.
+ * native `<input type="color">` produces). The constraint walker
+ * rejects non-hex values (and lowercases) on write.
  */
 export interface ColorMetaBoxField extends MetaBoxFieldBase {
     readonly inputType: "color";
@@ -410,8 +443,8 @@ export interface ColorMetaBoxField extends MetaBoxFieldBase {
 /**
  * Bounded numeric slider. Renders as `<input type="range">`. `min` /
  * `max` are required so the slider has a concrete range; `step`
- * defaults to `1`. The builder injects a default sanitizer that
- * enforces the bounds on write.
+ * defaults to `1`. The constraint walker enforces the bounds on
+ * write.
  */
 export interface RangeMetaBoxField extends MetaBoxFieldBase {
     readonly inputType: "range";
@@ -420,18 +453,6 @@ export interface RangeMetaBoxField extends MetaBoxFieldBase {
     readonly max: number;
     readonly step?: number;
 }
-/**
- * Multi-value picker over a fixed option list. Storage is a JSON
- * array of option `value` strings. Renders as a toggle group in the
- * admin so authors see all options at once. The builder ships a
- * default sanitizer that rejects values outside the declared
- * options.
- */
-export interface MultiselectMetaBoxField extends MetaBoxFieldBase {
-    readonly inputType: "multiselect";
-    readonly type: "json";
-    readonly options: readonly MetaBoxFieldOption[];
-}
 /**
  * Free-form JSON value. Storage round-trips through the JSON
  * serializer so any structure that survives `JSON.stringify`
@@ -451,6 +472,14 @@ export interface JsonMetaBoxField extends MetaBoxFieldBase {
  * that calls the lookup RPC with `{ kind, scope }` — picker UI is
  * one component, target-specific knowledge lives in the adapter.
  */
+/**
+ * Read-projection opt-out carried on a reference field. `"id"` makes the
+ * field's reads yield the bare stored id(s) instead of the resolved
+ * summary — the read pipeline skips the batched hydration join (and its
+ * orphan-stripping) for that field. Storage and the write contract are
+ * unaffected. Authored via the builder's `.returns("id")`.
+ */
+export type ReferenceReadProjection = "id";
 export interface ReferenceTarget<TScope = unknown> {
     readonly kind: string;
     readonly scope?: TScope;
@@ -472,6 +501,8 @@ export interface UserMetaBoxField extends MetaBoxFieldBase {
     readonly inputType: "user";
     readonly type: "string";
     readonly referenceTarget: ReferenceTarget;
+    /** `.returns("id")`: reads yield the bare stored id, skipping the read-time hydration join. See {@link ReferenceReadProjection}. */
+    readonly returns?: ReferenceReadProjection;
 }
 /**
  * Multi user reference. Storage is a JSON array of bare user ids
@@ -484,6 +515,8 @@ export interface UserListMetaBoxField extends MetaBoxFieldBase {
     readonly inputType: "userList";
     readonly type: "json";
     readonly referenceTarget: ReferenceTarget;
+    /** `.returns("id")`: reads yield the bare stored id, skipping the read-time hydration join. See {@link ReferenceReadProjection}. */
+    readonly returns?: ReferenceReadProjection;
     /** Max items allowed in the array. Omitted = unbounded. */
     readonly max?: number;
 }
@@ -493,14 +526,15 @@ export interface UserListMetaBoxField extends MetaBoxFieldBase {
  * trashed. `referenceTarget.scope` carries `entryTypes` (the only
  * entry-type names this field accepts).
  *
- * Naming note: the `Reference` infix avoids the collision with
- * `EntryMetaBoxField` further down — the latter is the per-variant
- * Omit-distributive union for fields inside an entry meta box.
+ * Naming note: the `Reference` infix keeps the name clear of the
+ * entry-meta-box option types (`EntryMetaBoxOptions` and friends).
  */
 export interface EntryReferenceMetaBoxField extends MetaBoxFieldBase {
     readonly inputType: "entry";
     readonly type: "string";
     readonly referenceTarget: ReferenceTarget;
+    /** `.returns("id")`: reads yield the bare stored id, skipping the read-time hydration join. See {@link ReferenceReadProjection}. */
+    readonly returns?: ReferenceReadProjection;
 }
 /**
  * Multi entry reference. Storage is a JSON array of bare entry ids;
@@ -513,6 +547,8 @@ export interface EntryListMetaBoxField extends MetaBoxFieldBase {
     readonly inputType: "entryList";
     readonly type: "json";
     readonly referenceTarget: ReferenceTarget;
+    /** `.returns("id")`: reads yield the bare stored id, skipping the read-time hydration join. See {@link ReferenceReadProjection}. */
+    readonly returns?: ReferenceReadProjection;
     /** Max items allowed in the array. Omitted = unbounded. */
     readonly max?: number;
 }
@@ -526,6 +562,8 @@ export interface TermReferenceMetaBoxField extends MetaBoxFieldBase {
     readonly inputType: "term";
     readonly type: "string";
     readonly referenceTarget: ReferenceTarget;
+    /** `.returns("id")`: reads yield the bare stored id, skipping the read-time hydration join. See {@link ReferenceReadProjection}. */
+    readonly returns?: ReferenceReadProjection;
 }
 /**
  * Multi term reference. Storage is a JSON array of bare term ids;
@@ -538,6 +576,8 @@ export interface TermListMetaBoxField extends MetaBoxFieldBase {
     readonly inputType: "termList";
     readonly type: "json";
     readonly referenceTarget: ReferenceTarget;
+    /** `.returns("id")`: reads yield the bare stored id, skipping the read-time hydration join. See {@link ReferenceReadProjection}. */
+    readonly returns?: ReferenceReadProjection;
     /** Max items allowed in the array. Omitted = unbounded. */
     readonly max?: number;
 }
@@ -554,6 +594,8 @@ export interface MediaMetaBoxField extends MetaBoxFieldBase {
     readonly inputType: "media";
     readonly type: "json";
     readonly referenceTarget: ReferenceTarget;
+    /** `.returns("id")`: reads yield the bare stored id, skipping the read-time hydration join. See {@link ReferenceReadProjection}. */
+    readonly returns?: ReferenceReadProjection;
 }
 /**
  * Multi media reference. Storage is a JSON array of bare media ids;
@@ -565,6 +607,8 @@ export interface MediaListMetaBoxField extends MetaBoxFieldBase {
     readonly inputType: "mediaList";
     readonly type: "json";
     readonly referenceTarget: ReferenceTarget;
+    /** `.returns("id")`: reads yield the bare stored id, skipping the read-time hydration join. See {@link ReferenceReadProjection}. */
+    readonly returns?: ReferenceReadProjection;
     /** Max items allowed in the array. Omitted = unbounded. */
     readonly max?: number;
 }
@@ -587,8 +631,8 @@ export interface MediaListMetaBoxField extends MetaBoxFieldBase {
  * toolbar surfaces only the buttons that match the allowlist.
  *
  * Replaces the dropped `markdown` and `code` standalone field types —
- * `richtext({ nodes: ["codeBlock"] })` covers code-in-meta;
- * `richtext({ marks: ["bold","italic","link"], nodes: ["bulletList","orderedList"] })`
+ * `richtext("body").nodes(["codeBlock"])` covers code-in-meta;
+ * `richtext("body").marks(["bold","italic","link"]).nodes(["bulletList","orderedList"])`
  * covers markdown-shaped formatting.
  */
 export interface RichtextMetaBoxField extends MetaBoxFieldBase {
@@ -599,19 +643,33 @@ export interface RichtextMetaBoxField extends MetaBoxFieldBase {
     readonly blocks?: readonly string[];
 }
 /**
- * Flat list of structured rows. Each row carries the same fixed schema
+ * Admin layout for a repeater's rows. `block` (the default) stacks each
+ * row's fields vertically in a bordered card; `row` lays a single row's
+ * fields out inline on one line; `table` renders the rows as aligned
+ * table lines with a shared subfield header. A pure-UI axis — the
+ * stored value shape is identical across layouts.
+ */
+export type RepeaterLayout = "block" | "row" | "table";
+/**
+ * Width of the admin row-editor dialog. A pure-UI hint: `sm` suits a
+ * couple of narrow fields, `md` (the default) the common case, `lg` a
+ * dense multi-column row. Maps to a max-width in the admin; the stored
+ * row shape is unaffected.
+ */
+export type RepeaterDialogSize = "sm" | "md" | "lg";
+/**
+ * List of structured rows. Each row carries the same fixed schema
  * declared via `subFields`; mixed-row "flexible content" is explicitly
- * out of scope. Subfields may be any registered field type *except*
- * another repeater — nesting is rejected at registration time so v0.1
- * doesn't ship recursive UX (lift later non-breakingly if a real use
- * case appears).
+ * out of scope. Subfields may be any registered field type, including
+ * nested repeaters and groups — types recurse through arbitrarily
+ * nested rows.
  *
  * Storage rides on the `json` primitive so any JSON-serialisable row
- * shape survives the wire. The auto-injected sanitizer drops rows
- * where every subfield value is empty (`null` / `undefined` / `""`),
- * then enforces optional `min` / `max` row counts. "Empty" is strictly
+ * shape survives the wire. The constraint walker drops rows where
+ * every subfield value is empty (`null` / `undefined` / `""`), then
+ * enforces optional `min` / `max` row counts. "Empty" is strictly
  * those three: a row whose only populated subfield is `0` (number) or
- * `false` (checkbox) survives — those are real values.
+ * `false` (toggle) survives — those are real values.
  */
 export interface RepeaterMetaBoxField extends MetaBoxFieldBase {
     readonly inputType: "repeater";
@@ -619,23 +677,100 @@ export interface RepeaterMetaBoxField extends MetaBoxFieldBase {
     readonly subFields: readonly MetaBoxField[];
     readonly min?: number;
     readonly max?: number;
+    /** Custom label for the add-row button (default "Add row"). */
+    readonly addLabel?: Label;
+    /** Admin row layout — see {@link RepeaterLayout}. Defaults to `block`. */
+    readonly layout?: RepeaterLayout;
+    /**
+     * Sub-field key whose stored value labels a collapsed row. Setting it
+     * makes rows collapsible in the admin and each collapsed row shows the
+     * chosen sub-field's value as its summary.
+     */
+    readonly collapsed?: string;
+    /** Row-editor dialog width — see {@link RepeaterDialogSize}. Defaults to `md`. */
+    readonly dialogSize?: RepeaterDialogSize;
 }
-/** Single-value dropdown picker; `options` is required. */
-export interface SelectMetaBoxField extends MetaBoxFieldBase {
+/**
+ * A named group of fields stored as a nested object under the group's
+ * own key — no key-flattening. `fields` declares the members; each
+ * member may be any registered field type, including nested repeaters
+ * and further groups (types recurse). Storage rides on the `json`
+ * primitive as a plain record keyed by member field key.
+ */
+export interface GroupMetaBoxField extends MetaBoxFieldBase {
+    readonly inputType: "group";
+    readonly type: "json";
+    readonly fields: readonly MetaBoxField[];
+}
+/**
+ * Pure-UI control axis for choice fields. Maps to the admin's existing
+ * controls — dropdown, radio group, toggle-button group, checkbox
+ * list — and never changes the value shape. Cardinality restricts the
+ * legal values (`radio` is single-only, `checkboxes` multi-only); the
+ * fluent builder enforces that at compile time. Absent means the
+ * cardinality default: dropdown for single, buttons for multiple.
+ */
+export type SelectAppearance = "select" | "radio" | "buttons" | "checkboxes";
+/** Single-value choice — storage is the selected option value string. */
+export interface SingleSelectMetaBoxField extends MetaBoxFieldBase {
     readonly inputType: "select";
     readonly type: "string";
     readonly options: readonly MetaBoxFieldOption[];
+    readonly multiple?: false;
+    readonly appearance?: SelectAppearance;
 }
-/** Single-value radio group; `options` is required. */
-export interface RadioMetaBoxField extends MetaBoxFieldBase {
-    readonly inputType: "radio";
-    readonly type: "string";
+/** Multi-value choice — storage is a JSON array of option value strings. */
+export interface MultiSelectMetaBoxField extends MetaBoxFieldBase {
+    readonly inputType: "select";
+    readonly type: "json";
     readonly options: readonly MetaBoxFieldOption[];
+    readonly multiple: true;
+    /**
+     * Selection-count cap. Carried on the definition and the wire today;
+     * server-side enforcement lands with the generic constraint walker.
+     */
+    readonly max?: number;
+    readonly appearance?: SelectAppearance;
 }
-/** Boolean checkbox — storage type pinned to `boolean`. */
-export interface CheckboxMetaBoxField extends MetaBoxFieldBase {
-    readonly inputType: "checkbox";
+/**
+ * Choice field over a fixed option list. Cardinality and storage type
+ * are correlated variants — `multiple` requires `type: "json"` — so an
+ * object literal can't declare an array-emitting control over scalar
+ * storage.
+ */
+export type SelectMetaBoxField = SingleSelectMetaBoxField | MultiSelectMetaBoxField;
+/**
+ * Boolean switch — storage type pinned to `boolean`. Renders as the
+ * admin's switch control; `onText` / `offText` label the current state
+ * beside it.
+ */
+export interface ToggleMetaBoxField extends MetaBoxFieldBase {
+    readonly inputType: "toggle";
     readonly type: "boolean";
+    readonly onText?: Label;
+    readonly offText?: Label;
+}
+/**
+ * Stored value of a `link` field — a CTA-shaped destination. `url` is
+ * either an internal path (starts with `/`, produced by the admin's
+ * entry picker resolving an entry to its permalink) or an external
+ * absolute URL. `label` is the optional link text; `newTab` opts the
+ * rendered anchor into `target="_blank"`.
+ */
+export interface LinkValue {
+    readonly url: string;
+    readonly label?: string;
+    readonly newTab?: boolean;
+}
+/**
+ * CTA-style link field authored via `link()`. Storage rides on the
+ * `json` primitive as a `LinkValue`; the injected sanitizer rejects
+ * malformed shapes and URLs on write.
+ */
+export interface LinkMetaBoxField extends MetaBoxFieldBase {
+    readonly inputType: "link";
+    readonly type: "json";
+    readonly placeholder?: Label;
 }
 /**
  * Catch-all variant for any `inputType` not narrowed into a dedicated
@@ -667,7 +802,26 @@ export interface LegacyMetaBoxField extends MetaBoxFieldBase {
  * `registerFieldType` registrations and broad object-literal authoring
  * compiling unchanged.
  */
-export type MetaBoxField = TextMetaBoxField | TextareaMetaBoxField | NumberMetaBoxField | EmailMetaBoxField | UrlMetaBoxField | PasswordMetaBoxField | DateMetaBoxField | DateTimeMetaBoxField | TimeMetaBoxField | ColorMetaBoxField | RangeMetaBoxField | MultiselectMetaBoxField | JsonMetaBoxField | UserMetaBoxField | UserListMetaBoxField | EntryReferenceMetaBoxField | EntryListMetaBoxField | TermReferenceMetaBoxField | TermListMetaBoxField | MediaMetaBoxField | MediaListMetaBoxField | RichtextMetaBoxField | RepeaterMetaBoxField | SelectMetaBoxField | RadioMetaBoxField | CheckboxMetaBoxField | LegacyMetaBoxField;
+export type MetaBoxField = StringMetaBoxField | NumberMetaBoxField | TemporalMetaBoxField | ColorMetaBoxField | RangeMetaBoxField | JsonMetaBoxField | UserMetaBoxField | UserListMetaBoxField | EntryReferenceMetaBoxField | EntryListMetaBoxField | TermReferenceMetaBoxField | TermListMetaBoxField | MediaMetaBoxField | MediaListMetaBoxField | RichtextMetaBoxField | RepeaterMetaBoxField | GroupMetaBoxField | SelectMetaBoxField | ToggleMetaBoxField | LinkMetaBoxField | LegacyMetaBoxField;
+/**
+ * A fluent field builder — an immutable chain that compiles to a
+ * narrowed `MetaBoxField` variant. Chain method names (`label`,
+ * `default`, `sanitize`, …) collide with the definition's data
+ * properties, so a builder can't structurally *be* its definition;
+ * registration surfaces accept either shape and call `build()` on
+ * builders at registration time.
+ */
+export interface FieldBuilder<F extends MetaBoxField = MetaBoxField> {
+    build(): F;
+}
+/**
+ * What `fields` arrays accept on every registration surface: a fluent
+ * builder or a compiled field definition (object-literal authoring and
+ * `registerFieldType` custom fields).
+ */
+export type MetaBoxFieldInput = MetaBoxField | FieldBuilder;
+/** Compile a `fields` array down to definitions — builders build, plain definitions pass through. */
+export declare function compileMetaBoxFields(fields: readonly MetaBoxFieldInput[]): readonly MetaBoxField[];
 /**
  * Shared base for every "card of fields" registration surface — entry
  * meta boxes, term meta boxes, user meta boxes, and settings groups.
@@ -691,28 +845,17 @@ export interface MetaBoxBaseOptions {
     readonly description?: Label;
     readonly priority?: number;
     readonly capability?: string;
-    readonly fields: readonly MetaBoxField[];
+    readonly fields: readonly MetaBoxFieldInput[];
 }
-/**
- * Field shape for entry meta boxes. Drops `span` from the shared
- * `MetaBoxField` — the editor's document rail is a fixed 256px column,
- * so side-by-side layouts can't fit legibly. Compile-time signal to
- * plugin authors that spans are a page-width affordance only (term,
- * user, settings).
- *
- * `Omit<MetaBoxField, "span">` would normally distribute over the
- * union, but TS's excess-property check across a many-variant
- * distributed `Omit` gets pessimistic and starts rejecting options
- * that exist only on a subset of variants. The explicit per-variant
- * union below preserves the same shape with stable inference.
- */
-export type EntryMetaBoxField = Omit<TextMetaBoxField, "span"> | Omit<TextareaMetaBoxField, "span"> | Omit<NumberMetaBoxField, "span"> | Omit<EmailMetaBoxField, "span"> | Omit<UrlMetaBoxField, "span"> | Omit<PasswordMetaBoxField, "span"> | Omit<DateMetaBoxField, "span"> | Omit<DateTimeMetaBoxField, "span"> | Omit<TimeMetaBoxField, "span"> | Omit<ColorMetaBoxField, "span"> | Omit<RangeMetaBoxField, "span"> | Omit<MultiselectMetaBoxField, "span"> | Omit<JsonMetaBoxField, "span"> | Omit<UserMetaBoxField, "span"> | Omit<UserListMetaBoxField, "span"> | Omit<EntryReferenceMetaBoxField, "span"> | Omit<EntryListMetaBoxField, "span"> | Omit<TermReferenceMetaBoxField, "span"> | Omit<TermListMetaBoxField, "span"> | Omit<MediaMetaBoxField, "span"> | Omit<MediaListMetaBoxField, "span"> | Omit<RichtextMetaBoxField, "span"> | Omit<RepeaterMetaBoxField, "span"> | Omit<SelectMetaBoxField, "span"> | Omit<RadioMetaBoxField, "span"> | Omit<CheckboxMetaBoxField, "span"> | Omit<LegacyMetaBoxField, "span">;
 /**
  * Meta box shown on the entry editor. Scoped by `entryTypes`. Renders
  * as a collapsible section in the editor's document rail, which is
- * fixed at 256px — fields always occupy the full row.
+ * fixed at 256px — fields always occupy the full row. `span` is
+ * accepted like on every other surface but ignored at render (a
+ * universal hint narrow surfaces don't honor), and stripped from the
+ * entry wire projection.
  */
-export interface EntryMetaBoxOptions extends Omit<MetaBoxBaseOptions, "fields"> {
+export interface EntryMetaBoxOptions extends MetaBoxBaseOptions {
     /**
      * @deprecated The entry editor no longer partitions meta boxes by
      * location — every registered box renders as a collapsible section in
@@ -722,7 +865,6 @@ export interface EntryMetaBoxOptions extends Omit<MetaBoxBaseOptions, "fields">
      */
     readonly location?: "bottom" | "sidebar";
     readonly entryTypes: readonly string[];
-    readonly fields: readonly EntryMetaBoxField[];
 }
 /** Meta box shown on the termTaxonomy term edit form. Scoped by `termTaxonomies`. */
 export interface TermMetaBoxOptions extends MetaBoxBaseOptions {
@@ -769,18 +911,22 @@ export interface RegisteredTermTaxonomy extends TermTaxonomyOptions {
 export interface RegisteredEntryMetaBox extends EntryMetaBoxOptions {
     readonly id: string;
     readonly registeredBy: string | null;
+    readonly fields: readonly MetaBoxField[];
 }
 export interface RegisteredTermMetaBox extends TermMetaBoxOptions {
     readonly id: string;
     readonly registeredBy: string | null;
+    readonly fields: readonly MetaBoxField[];
 }
 export interface RegisteredUserMetaBox extends UserMetaBoxOptions {
     readonly id: string;
     readonly registeredBy: string | null;
+    readonly fields: readonly MetaBoxField[];
 }
 export interface RegisteredSettingsGroup extends SettingsGroupOptions {
     readonly name: string;
     readonly registeredBy: string | null;
+    readonly fields: readonly MetaBoxField[];
 }
 export interface RegisteredSettingsPage extends SettingsPageOptions {
     readonly name: string;
@@ -1122,6 +1268,14 @@ export declare function createPluginRegistry(): MutablePluginRegistry;
  * so "first match" is the only match.
  */
 export declare function findEntryMetaField(registry: PluginRegistry, entryType: string, key: string): MetaBoxField | undefined;
+/**
+ * Every `MetaBoxField` registered for an entry type, across all its meta
+ * boxes. Used by the publish gate to validate a promoted bag against the
+ * full schema — so a required field ABSENT from the bag is caught, not
+ * just one stored empty. Key uniqueness per (entryType, key) holds at
+ * registration, so no de-duplication is needed.
+ */
+export declare function listEntryMetaFields(registry: PluginRegistry, entryType: string): readonly MetaBoxField[];
 /**
  * Like `findEntryMetaField`, but for term meta. Scoped by termTaxonomy.
  */
@@ -1207,6 +1361,9 @@ export interface MetaBoxFieldManifestEntry {
     readonly inputType: string;
     readonly description?: Label;
     readonly required?: boolean;
+    /** Static input adornments — see `MetaBoxFieldBase.prepend` / `.append`. */
+    readonly prepend?: Label;
+    readonly append?: Label;
     readonly placeholder?: Label;
     readonly maxLength?: number;
     /**
@@ -1219,6 +1376,13 @@ export interface MetaBoxFieldManifestEntry {
     readonly max?: number | string;
     readonly step?: number;
     readonly options?: readonly MetaBoxFieldOption[];
+    /** Choice-field cardinality — `select` fields store an array when set. */
+    readonly multiple?: boolean;
+    /** Choice-field control variant — see `SelectAppearance`. */
+    readonly appearance?: SelectAppearance;
+    /** Toggle switch state labels — see `ToggleMetaBoxField`. */
+    readonly onText?: Label;
+    readonly offText?: Label;
     readonly default?: unknown;
     readonly span?: MetaBoxFieldSpan;
     /**
@@ -1237,16 +1401,31 @@ export interface MetaBoxFieldManifestEntry {
     readonly nodes?: readonly string[];
     readonly blocks?: readonly string[];
     /**
-     * Repeater subfield manifest, keyed positionally — same shape as a
-     * top-level field minus `span` (rows are full-width). Sanitize
-     * callbacks are stripped from the wire shape; the admin recurses
-     * through this list when rendering each row.
+     * Child-field manifest for the composite field types — repeater row
+     * schema and group members alike, keyed positionally, same shape as a
+     * top-level field. Children keep their `span`: the row-editor dialog and
+     * group grid lay them out on a 12-column grid that honours it. Sanitize
+     * callbacks are stripped from the wire shape; the admin recurses through
+     * this list when rendering each row / group. The renderer dispatches on
+     * `inputType` (`repeater` vs `group`) to interpret it.
      */
-    readonly subFields?: readonly EntryMetaBoxFieldManifestEntry[];
+    readonly subFields?: readonly MetaBoxFieldManifestEntry[];
+    /** Repeater add-row button label — see {@link RepeaterMetaBoxField.addLabel}. */
+    readonly addLabel?: Label;
+    /** Repeater row layout — see {@link RepeaterLayout}. */
+    readonly layout?: RepeaterLayout;
+    /** Repeater collapsed-row summary sub-field key — see {@link RepeaterMetaBoxField.collapsed}. */
+    readonly collapsed?: string;
+    /** Repeater row-editor dialog width — see {@link RepeaterDialogSize}. */
+    readonly dialogSize?: RepeaterDialogSize;
     /**
      * Capability gate for the individual field. See `MetaBoxFieldBase.capability`.
      */
     readonly capability?: string;
+    /**
+     * Conditional visibility rules. See `MetaBoxFieldBase.visibleWhen`.
+     */
+    readonly visibleWhen?: MetaFieldCondition;
 }
 /**
  * Shared base for every "card of fields" serialised entry. Each
@@ -1261,8 +1440,9 @@ export interface MetaBoxBaseManifestEntry {
     readonly fields: readonly MetaBoxFieldManifestEntry[];
 }
 /**
- * Wire-side mirror of `EntryMetaBoxField` — drops `span` from the
- * shared `MetaBoxFieldManifestEntry`. See `EntryMetaBoxField` for why.
+ * Entry-box wire field — drops `span` from the shared
+ * `MetaBoxFieldManifestEntry`. The editor rail can't honor the hint
+ * (see `EntryMetaBoxOptions`), so shipping it would just bloat the wire.
  */
 export type EntryMetaBoxFieldManifestEntry = Omit<MetaBoxFieldManifestEntry, "span">;
 export interface EntryMetaBoxManifestEntry extends Omit<MetaBoxBaseManifestEntry, "fields"> {