@plumix/core 0.5.0 → 0.7.0

package/dist/plugin/fields/select.d.ts

@@ -1,20 +1,160 @@
 import type { Label } from "../../i18n/label.js";
-import type { MetaBoxFieldOption, MetaBoxFieldSpan, SelectMetaBoxField } from "../manifest.js";
-export interface SelectFieldOptions {
-    readonly key: string;
-    readonly label: Label;
+import type { FieldBuilder, MetaBoxFieldOption, MetaBoxFieldSpan, MetaBoxFieldValidate, MultiSelectMetaBoxField, SelectAppearance, SelectMetaBoxField, SingleSelectMetaBoxField } from "../manifest.js";
+import type { MetaFieldCondition, MetaFieldConditionRule } from "./condition.js";
+/**
+ * An option passed to `.options()` — either the full `{ value, label }`
+ * shape or a string shorthand whose label derives from the humanized
+ * value (`"videoHero"` → "Video hero").
+ */
+export type SelectOptionInput = string | MetaBoxFieldOption;
+/** Literal value union inferred from an `.options()` array. */
+type OptionValue<T extends SelectOptionInput> = T extends string ? T : T extends MetaBoxFieldOption ? T["value"] : never;
+/** Appearances legal for the given cardinality — radio and the dropdown
+ *  are single-only, checkboxes multi-only, buttons works on both. */
+type AppearanceFor<Multiple extends boolean> = Multiple extends true ? "buttons" | "checkboxes" : "select" | "radio" | "buttons";
+interface SelectFieldState {
+    readonly visibleWhen?: MetaFieldCondition;
     readonly options: readonly MetaBoxFieldOption[];
-    readonly required?: boolean;
+    readonly multiple?: true;
+    readonly max?: number;
+    readonly appearance?: SelectAppearance;
+    readonly label?: Label;
     readonly description?: Label;
-    readonly default?: string;
+    readonly default?: string | readonly string[];
+    readonly required?: true;
     readonly span?: MetaBoxFieldSpan;
     readonly capability?: string;
+    readonly showInApi?: true;
     readonly sanitize?: (value: unknown) => unknown;
+    readonly validate?: MetaBoxFieldValidate;
+}
+/**
+ * Entry point of the `select()` chain — only `.options()` is available
+ * until the option list is declared, so a choice field without choices
+ * can't reach `build()` (registration surfaces require a `build`
+ * method).
+ */
+export declare class SelectFieldSeed<K extends string = string> {
+    #private;
+    constructor(key: K);
+    /** Declare the option list — infers the value literal union. */
+    options<const Options extends readonly SelectOptionInput[]>(options: Options): SelectFieldBuilder<OptionValue<Options[number]>, K>;
+}
+/**
+ * Fluent chain for choice fields. Immutable — every call returns a
+ * fresh instance, so a shared base chain can be forked without
+ * aliasing.
+ *
+ * Type parameters are the declaration's compile-time state: `O` is the
+ * option literal union inferred by `.options()`; `Multiple` is the
+ * cardinality (`.multiple()` flips it and the stored shape); `A` is
+ * the chosen appearance, tracked so cardinality-illegal combinations
+ * (radio + multiple) fail to compile in either call order; `V` is the
+ * phantom read type — `O | undefined` unadorned, an array after
+ * `.multiple()`, narrowed by `.required()` / `.default()`. All purely
+ * type-level — nothing at runtime carries them.
+ */
+export declare class SelectFieldBuilder<O extends string, K extends string = string, Multiple extends boolean = false, A extends SelectAppearance | undefined = undefined, V = O | undefined, S = O | undefined> implements FieldBuilder<SelectMetaBoxField> {
+    #private;
+    /** Phantom literal key of the field — type-level only, never assigned. */
+    readonly _key: K;
+    /** Phantom read type of the field — type-level only, never assigned. */
+    readonly _value: V;
+    /** Phantom stored shape — `.required()` narrows it (write-enforced);
+     *  `.default()` does not (defaults apply at decode time). */
+    readonly _stored: S;
+    /** Phantom cardinality/appearance markers backing the compile-time
+     *  gating of `.multiple()`, `.max()`, and `.appearance()`. */
+    readonly _multiple: Multiple;
+    readonly _appearance: A;
+    constructor(key: string, state: SelectFieldState);
+    /**
+     * Store an array of selected option values instead of a single one
+     * (`type` flips to `json`). A type-level gate keeps it legal:
+     * declare cardinality right after `.options()` — before `.default()`
+     * / `.required()` narrow the value — and never after a single-only
+     * `.appearance()` (`"select"` / `"radio"`).
+     */
+    multiple(this: undefined extends V ? SelectFieldBuilder<O, K, false, "buttons" | undefined, V, S> : never): SelectFieldBuilder<O, K, true, A, readonly O[] | undefined, readonly O[] | undefined>;
+    /**
+     * Cap the selection count — multi-value fields only. Carried on the
+     * definition and the wire today; server-side enforcement lands with
+     * the generic constraint walker.
+     */
+    max(this: SelectFieldBuilder<O, K, true, A, V, S>, max: number): SelectFieldBuilder<O, K, true, A, V, S>;
+    /**
+     * Pick the admin control rendering the option list — the pure-UI
+     * axis; the value shape never changes. Single-value fields accept
+     * `"select"` (dropdown, the default), `"radio"`, and `"buttons"`;
+     * multi-value fields accept `"buttons"` (the default) and
+     * `"checkboxes"`.
+     */
+    appearance<A2 extends AppearanceFor<Multiple>>(appearance: A2): SelectFieldBuilder<O, K, Multiple, A2, V, S>;
+    /** Override the derived (humanized-key) label. */
+    label(label: Label): SelectFieldBuilder<O, K, Multiple, A, V, S>;
+    /** Help text rendered under the label. */
+    description(description: Label): SelectFieldBuilder<O, K, Multiple, A, V, S>;
+    /** Admin-form prefill for unsaved keys — narrows away `undefined`. */
+    default(value: Multiple extends true ? readonly O[] : O): SelectFieldBuilder<O, K, Multiple, A, NonNullable<V>, S>;
+    /** Mark the field required — narrows away `undefined`. */
+    required(): SelectFieldBuilder<O, K, Multiple, A, NonNullable<V>, NonNullable<S>>;
+    /**
+     * Column span within the box's 12-column grid — a universal layout
+     * hint; surfaces that can't honor it (the entry editor rail) ignore it.
+     */
+    span(span: MetaBoxFieldSpan): SelectFieldBuilder<O, K, Multiple, A, V, S>;
+    /** Capability gate for this field — see `MetaBoxFieldBase.capability`. */
+    capability(capability: string): SelectFieldBuilder<O, K, Multiple, A, V, S>;
+    /** Opt this field's value into public REST responses (default-deny). */
+    showInApi(): SelectFieldBuilder<O, K, Multiple, A, V, S>;
+    /** Rule factory: this field's value equals `value` — pass the rule
+     *  to a dependent field's `.visibleWhen()`. The comparand is typed
+     *  by the chain's cardinality: one option value, or the exact
+     *  selection array after `.multiple()`. */
+    is(value: NonNullable<S>): MetaFieldConditionRule;
+    /** Rule factory: this field's value differs from `value`. */
+    isNot(value: NonNullable<S>): MetaFieldConditionRule;
+    /** Rule factory: this field has no value (unset or cleared). */
+    isEmpty(): MetaFieldConditionRule;
+    /** Rule factory: this field has a value. */
+    isNotEmpty(): MetaFieldConditionRule;
+    /** Rule factory: the selection includes `value` — multi-value only. */
+    contains(this: SelectFieldBuilder<O, K, true, A, V, S>, value: O): MetaFieldConditionRule;
+    /** Rule factory: the selection does not include `value` — multi-value only. */
+    notContains(this: SelectFieldBuilder<O, K, true, A, V, S>, value: O): MetaFieldConditionRule;
+    /** Rule factory: more than `count` options selected — multi-value only. */
+    countGt(this: SelectFieldBuilder<O, K, true, A, V, S>, count: number): MetaFieldConditionRule;
+    /** Rule factory: fewer than `count` options selected — multi-value only. */
+    countLt(this: SelectFieldBuilder<O, K, true, A, V, S>, count: number): MetaFieldConditionRule;
+    /**
+     * Show this field only when every rule passes (one AND group) —
+     * rules come from sibling fields' condition factories. Replaces any
+     * previously declared condition; `.orVisibleWhen()` adds
+     * alternatives.
+     */
+    visibleWhen(...rules: MetaFieldConditionRule[]): SelectFieldBuilder<O, K, Multiple, A, V, S>;
+    /** Add an OR alternative — one more AND group of rules. */
+    orVisibleWhen(...rules: MetaFieldConditionRule[]): SelectFieldBuilder<O, K, Multiple, A, V, S>;
+    /** Normalising transform, applied after coercion and before persistence. */
+    sanitize(sanitize: (value: NonNullable<V>) => NonNullable<V>): SelectFieldBuilder<O, K, Multiple, A, V, S>;
+    /**
+     * Custom validation — `true` for valid, or an i18n-able failure
+     * message (sync or async). Runs after `.sanitize()` and the
+     * declarative constraints.
+     */
+    validate(validate: (value: NonNullable<V>) => true | Label | Promise<true | Label>): SelectFieldBuilder<O, K, Multiple, A, V, S>;
+    /** Compile the chain into the wire/manifest field definition —
+     *  the `multiple`/`type`-correlated variant matching the chain's
+     *  cardinality. */
+    build(): Multiple extends true ? MultiSelectMetaBoxField : SingleSelectMetaBoxField;
 }
 /**
- * Build a typed `select` meta-box field. `options` is required — the
- * builder enforces this at the type level so a dropdown without choices
- * fails to compile.
+ * Choice field over a fixed option list —
+ * `select("size").options(["s", "m", "l"])`. Single-value by default;
+ * `.multiple()` stores an array, `.appearance()` picks the admin
+ * control. The option list is required: only `.options()` is available
+ * on the bare constructor.
  */
-export declare function select(options: SelectFieldOptions): SelectMetaBoxField;
+export declare function select<K extends string>(key: K): SelectFieldSeed<K>;
+export {};
 //# sourceMappingURL=select.d.ts.map

package/dist/plugin/fields/select.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"select.d.ts","sourceRoot":"","sources":["../../../src/plugin/fields/select.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAC;AACjD,OAAO,KAAK,EACV,kBAAkB,EAClB,gBAAgB,EAChB,kBAAkB,EACnB,MAAM,gBAAgB,CAAC;AAExB,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,SAAS,kBAAkB,EAAE,CAAC;IAChD,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,WAAW,CAAC,EAAE,KAAK,CAAC;IAC7B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,CAAC,EAAE,gBAAgB,CAAC;IACjC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC;CACjD;AAED;;;;GAIG;AACH,wBAAgB,MAAM,CAAC,OAAO,EAAE,kBAAkB,GAAG,kBAAkB,CActE"}
+{"version":3,"file":"select.d.ts","sourceRoot":"","sources":["../../../src/plugin/fields/select.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAC;AACjD,OAAO,KAAK,EACV,YAAY,EACZ,kBAAkB,EAClB,gBAAgB,EAChB,oBAAoB,EACpB,uBAAuB,EACvB,gBAAgB,EAChB,kBAAkB,EAClB,wBAAwB,EACzB,MAAM,gBAAgB,CAAC;AACxB,OAAO,KAAK,EACV,kBAAkB,EAClB,sBAAsB,EACvB,MAAM,gBAAgB,CAAC;AAGxB;;;;GAIG;AACH,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG,kBAAkB,CAAC;AAE5D,+DAA+D;AAC/D,KAAK,WAAW,CAAC,CAAC,SAAS,iBAAiB,IAAI,CAAC,SAAS,MAAM,GAC5D,CAAC,GACD,CAAC,SAAS,kBAAkB,GAC1B,CAAC,CAAC,OAAO,CAAC,GACV,KAAK,CAAC;AAEZ;qEACqE;AACrE,KAAK,aAAa,CAAC,QAAQ,SAAS,OAAO,IAAI,QAAQ,SAAS,IAAI,GAChE,SAAS,GAAG,YAAY,GACxB,QAAQ,GAAG,OAAO,GAAG,SAAS,CAAC;AAEnC,UAAU,gBAAgB;IACxB,QAAQ,CAAC,WAAW,CAAC,EAAE,kBAAkB,CAAC;IAC1C,QAAQ,CAAC,OAAO,EAAE,SAAS,kBAAkB,EAAE,CAAC;IAChD,QAAQ,CAAC,QAAQ,CAAC,EAAE,IAAI,CAAC;IACzB,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,UAAU,CAAC,EAAE,gBAAgB,CAAC;IACvC,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC;IACvB,QAAQ,CAAC,WAAW,CAAC,EAAE,KAAK,CAAC;IAC7B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAAC;IAC9C,QAAQ,CAAC,QAAQ,CAAC,EAAE,IAAI,CAAC;IACzB,QAAQ,CAAC,IAAI,CAAC,EAAE,gBAAgB,CAAC;IACjC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,SAAS,CAAC,EAAE,IAAI,CAAC;IAC1B,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC;IAChD,QAAQ,CAAC,QAAQ,CAAC,EAAE,oBAAoB,CAAC;CAC1C;AAED;;;;;GAKG;AACH,qBAAa,eAAe,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM;;gBAGxC,GAAG,EAAE,CAAC;IAIlB,gEAAgE;IAChE,OAAO,CAAC,KAAK,CAAC,OAAO,SAAS,SAAS,iBAAiB,EAAE,EACxD,OAAO,EAAE,OAAO,GACf,kBAAkB,CAAC,WAAW,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC;CASvD;AAED;;;;;;;;;;;;;GAaG;AACH,qBAAa,kBAAkB,CAC7B,CAAC,SAAS,MAAM,EAChB,CAAC,SAAS,MAAM,GAAG,MAAM,EACzB,QAAQ,SAAS,OAAO,GAAG,KAAK,EAChC,CAAC,SAAS,gBAAgB,GAAG,SAAS,GAAG,SAAS,EAClD,CAAC,GAAG,CAAC,GAAG,SAAS,EACjB,CAAC,GAAG,CAAC,GAAG,SAAS,CACjB,YAAW,YAAY,CAAC,kBAAkB,CAAC;;IAC3C,0EAA0E;IAC1E,SAAiB,IAAI,EAAE,CAAC,CAAC;IACzB,wEAAwE;IACxE,SAAiB,MAAM,EAAE,CAAC,CAAC;IAC3B;iEAC6D;IAC7D,SAAiB,OAAO,EAAE,CAAC,CAAC;IAC5B;kEAC8D;IAC9D,SAAiB,SAAS,EAAE,QAAQ,CAAC;IACrC,SAAiB,WAAW,EAAE,CAAC,CAAC;gBAKpB,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,gBAAgB;IAmBhD;;;;;;OAMG;IACH,QAAQ,CAKN,IAAI,EAAE,SAAS,SAAS,CAAC,GACrB,kBAAkB,CAAC,CAAC,EAAE,CAAC,EAAE,KAAK,EAAE,SAAS,GAAG,SAAS,EAAE,CAAC,EAAE,CAAC,CAAC,GAC5D,KAAK,GACR,kBAAkB,CACnB,CAAC,EACD,CAAC,EACD,IAAI,EACJ,CAAC,EACD,SAAS,CAAC,EAAE,GAAG,SAAS,EACxB,SAAS,CAAC,EAAE,GAAG,SAAS,CACzB;IAYD;;;;OAIG;IACH,GAAG,CACD,IAAI,EAAE,kBAAkB,CAAC,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAC7C,GAAG,EAAE,MAAM,GACV,kBAAkB,CAAC,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;IAI1C;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,SAAS,aAAa,CAAC,QAAQ,CAAC,EAC3C,UAAU,EAAE,EAAE,GACb,kBAAkB,CAAC,CAAC,EAAE,CAAC,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,CAAC;IAI/C,kDAAkD;IAClD,KAAK,CAAC,KAAK,EAAE,KAAK,GAAG,kBAAkB,CAAC,CAAC,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;IAIhE,0CAA0C;IAC1C,WAAW,CAAC,WAAW,EAAE,KAAK,GAAG,kBAAkB,CAAC,CAAC,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;IAI5E,sEAAsE;IACtE,OAAO,CACL,KAAK,EAAE,QAAQ,SAAS,IAAI,GAAG,SAAS,CAAC,EAAE,GAAG,CAAC,GAC9C,kBAAkB,CAAC,CAAC,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,WAAW,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IAI3D,0DAA0D;IAC1D,QAAQ,IAAI,kBAAkB,CAC5B,CAAC,EACD,CAAC,EACD,QAAQ,EACR,CAAC,EACD,WAAW,CAAC,CAAC,CAAC,EACd,WAAW,CAAC,CAAC,CAAC,CACf;IAMD;;;OAGG;IACH,IAAI,CAAC,IAAI,EAAE,gBAAgB,GAAG,kBAAkB,CAAC,CAAC,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;IAIzE,0EAA0E;IAC1E,UAAU,CAAC,UAAU,EAAE,MAAM,GAAG,kBAAkB,CAAC,CAAC,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;IAI3E,wEAAwE;IACxE,SAAS,IAAI,kBAAkB,CAAC,CAAC,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;IAIxD;;;+CAG2C;IAC3C,EAAE,CAAC,KAAK,EAAE,WAAW,CAAC,CAAC,CAAC,GAAG,sBAAsB;IAIjD,6DAA6D;IAC7D,KAAK,CAAC,KAAK,EAAE,WAAW,CAAC,CAAC,CAAC,GAAG,sBAAsB;IAIpD,gEAAgE;IAChE,OAAO,IAAI,sBAAsB;IAIjC,4CAA4C;IAC5C,UAAU,IAAI,sBAAsB;IAIpC,uEAAuE;IACvE,QAAQ,CACN,IAAI,EAAE,kBAAkB,CAAC,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAC7C,KAAK,EAAE,CAAC,GACP,sBAAsB;IAIzB,+EAA+E;IAC/E,WAAW,CACT,IAAI,EAAE,kBAAkB,CAAC,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAC7C,KAAK,EAAE,CAAC,GACP,sBAAsB;IAIzB,2EAA2E;IAC3E,OAAO,CACL,IAAI,EAAE,kBAAkB,CAAC,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAC7C,KAAK,EAAE,MAAM,GACZ,sBAAsB;IAIzB,4EAA4E;IAC5E,OAAO,CACL,IAAI,EAAE,kBAAkB,CAAC,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAC7C,KAAK,EAAE,MAAM,GACZ,sBAAsB;IAIzB;;;;;OAKG;IACH,WAAW,CACT,GAAG,KAAK,EAAE,sBAAsB,EAAE,GACjC,kBAAkB,CAAC,CAAC,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;IAI9C,2DAA2D;IAC3D,aAAa,CACX,GAAG,KAAK,EAAE,sBAAsB,EAAE,GACjC,kBAAkB,CAAC,CAAC,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;IAM9C,4EAA4E;IAC5E,QAAQ,CACN,QAAQ,EAAE,CAAC,KAAK,EAAE,WAAW,CAAC,CAAC,CAAC,KAAK,WAAW,CAAC,CAAC,CAAC,GAClD,kBAAkB,CAAC,CAAC,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;IAI9C;;;;OAIG;IACH,QAAQ,CACN,QAAQ,EAAE,CAAC,KAAK,EAAE,WAAW,CAAC,CAAC,CAAC,KAAK,IAAI,GAAG,KAAK,GAAG,OAAO,CAAC,IAAI,GAAG,KAAK,CAAC,GACxE,kBAAkB,CAAC,CAAC,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;IAI9C;;uBAEmB;IACnB,KAAK,IAAI,QAAQ,SAAS,IAAI,GAC1B,uBAAuB,GACvB,wBAAwB;CAoB7B;AAED;;;;;;GAMG;AACH,wBAAgB,MAAM,CAAC,CAAC,SAAS,MAAM,EAAE,GAAG,EAAE,CAAC,GAAG,eAAe,CAAC,CAAC,CAAC,CAEnE"}

package/dist/plugin/fields/select.js

@@ -1,21 +1,209 @@
+var _a;
+import { humanizeFieldKey } from "./builder.js";
 /**
- * Build a typed `select` meta-box field. `options` is required — the
- * builder enforces this at the type level so a dropdown without choices
- * fails to compile.
+ * Entry point of the `select()` chain — only `.options()` is available
+ * until the option list is declared, so a choice field without choices
+ * can't reach `build()` (registration surfaces require a `build`
+ * method).
  */
-export function select(options) {
-    return {
-        key: options.key,
-        label: options.label,
-        type: "string",
-        inputType: "select",
-        options: options.options,
-        required: options.required,
-        description: options.description,
-        default: options.default,
-        span: options.span,
-        capability: options.capability,
-        sanitize: options.sanitize,
-    };
+export class SelectFieldSeed {
+    #key;
+    constructor(key) {
+        this.#key = key;
+    }
+    /** Declare the option list — infers the value literal union. */
+    options(options) {
+        return new SelectFieldBuilder(this.#key, {
+            options: options.map((opt) => typeof opt === "string"
+                ? { value: opt, label: humanizeFieldKey(opt) }
+                : opt),
+        });
+    }
+}
+/**
+ * Fluent chain for choice fields. Immutable — every call returns a
+ * fresh instance, so a shared base chain can be forked without
+ * aliasing.
+ *
+ * Type parameters are the declaration's compile-time state: `O` is the
+ * option literal union inferred by `.options()`; `Multiple` is the
+ * cardinality (`.multiple()` flips it and the stored shape); `A` is
+ * the chosen appearance, tracked so cardinality-illegal combinations
+ * (radio + multiple) fail to compile in either call order; `V` is the
+ * phantom read type — `O | undefined` unadorned, an array after
+ * `.multiple()`, narrowed by `.required()` / `.default()`. All purely
+ * type-level — nothing at runtime carries them.
+ */
+export class SelectFieldBuilder {
+    #key;
+    #state;
+    constructor(key, state) {
+        this.#key = key;
+        this.#state = state;
+    }
+    #fork(patch) {
+        return new _a(this.#key, {
+            ...this.#state,
+            ...patch,
+        });
+    }
+    /**
+     * Store an array of selected option values instead of a single one
+     * (`type` flips to `json`). A type-level gate keeps it legal:
+     * declare cardinality right after `.options()` — before `.default()`
+     * / `.required()` narrow the value — and never after a single-only
+     * `.appearance()` (`"select"` / `"radio"`).
+     */
+    multiple() {
+        // The conditional this-type erases the class shape inside the body;
+        // restore it to reach the private #fork.
+        const self = this;
+        return self.#fork({ multiple: true });
+    }
+    /**
+     * Cap the selection count — multi-value fields only. Carried on the
+     * definition and the wire today; server-side enforcement lands with
+     * the generic constraint walker.
+     */
+    max(max) {
+        return this.#fork({ max });
+    }
+    /**
+     * Pick the admin control rendering the option list — the pure-UI
+     * axis; the value shape never changes. Single-value fields accept
+     * `"select"` (dropdown, the default), `"radio"`, and `"buttons"`;
+     * multi-value fields accept `"buttons"` (the default) and
+     * `"checkboxes"`.
+     */
+    appearance(appearance) {
+        return this.#fork({ appearance });
+    }
+    /** Override the derived (humanized-key) label. */
+    label(label) {
+        return this.#fork({ label });
+    }
+    /** Help text rendered under the label. */
+    description(description) {
+        return this.#fork({ description });
+    }
+    /** Admin-form prefill for unsaved keys — narrows away `undefined`. */
+    default(value) {
+        return this.#fork({ default: value });
+    }
+    /** Mark the field required — narrows away `undefined`. */
+    required() {
+        return this.#fork({
+            required: true,
+        });
+    }
+    /**
+     * Column span within the box's 12-column grid — a universal layout
+     * hint; surfaces that can't honor it (the entry editor rail) ignore it.
+     */
+    span(span) {
+        return this.#fork({ span });
+    }
+    /** Capability gate for this field — see `MetaBoxFieldBase.capability`. */
+    capability(capability) {
+        return this.#fork({ capability });
+    }
+    /** Opt this field's value into public REST responses (default-deny). */
+    showInApi() {
+        return this.#fork({ showInApi: true });
+    }
+    /** Rule factory: this field's value equals `value` — pass the rule
+     *  to a dependent field's `.visibleWhen()`. The comparand is typed
+     *  by the chain's cardinality: one option value, or the exact
+     *  selection array after `.multiple()`. */
+    is(value) {
+        return { key: this.#key, op: "eq", value };
+    }
+    /** Rule factory: this field's value differs from `value`. */
+    isNot(value) {
+        return { key: this.#key, op: "neq", value };
+    }
+    /** Rule factory: this field has no value (unset or cleared). */
+    isEmpty() {
+        return { key: this.#key, op: "empty" };
+    }
+    /** Rule factory: this field has a value. */
+    isNotEmpty() {
+        return { key: this.#key, op: "not_empty" };
+    }
+    /** Rule factory: the selection includes `value` — multi-value only. */
+    contains(value) {
+        return { key: this.#key, op: "contains", value };
+    }
+    /** Rule factory: the selection does not include `value` — multi-value only. */
+    notContains(value) {
+        return { key: this.#key, op: "not_contains", value };
+    }
+    /** Rule factory: more than `count` options selected — multi-value only. */
+    countGt(count) {
+        return { key: this.#key, op: "count_gt", value: count };
+    }
+    /** Rule factory: fewer than `count` options selected — multi-value only. */
+    countLt(count) {
+        return { key: this.#key, op: "count_lt", value: count };
+    }
+    /**
+     * Show this field only when every rule passes (one AND group) —
+     * rules come from sibling fields' condition factories. Replaces any
+     * previously declared condition; `.orVisibleWhen()` adds
+     * alternatives.
+     */
+    visibleWhen(...rules) {
+        return this.#fork({ visibleWhen: [rules] });
+    }
+    /** Add an OR alternative — one more AND group of rules. */
+    orVisibleWhen(...rules) {
+        return this.#fork({
+            visibleWhen: [...(this.#state.visibleWhen ?? []), rules],
+        });
+    }
+    /** Normalising transform, applied after coercion and before persistence. */
+    sanitize(sanitize) {
+        return this.#fork({ sanitize: sanitize });
+    }
+    /**
+     * Custom validation — `true` for valid, or an i18n-able failure
+     * message (sync or async). Runs after `.sanitize()` and the
+     * declarative constraints.
+     */
+    validate(validate) {
+        return this.#fork({ validate: validate });
+    }
+    /** Compile the chain into the wire/manifest field definition —
+     *  the `multiple`/`type`-correlated variant matching the chain's
+     *  cardinality. */
+    build() {
+        const { multiple, ...state } = this.#state;
+        // Option membership, de-dupe, and `.max()` selection counts are
+        // enforced server-side by the constraint walker.
+        const common = {
+            ...state,
+            key: this.#key,
+            label: state.label ?? humanizeFieldKey(this.#key),
+            inputType: "select",
+        };
+        // Branch so each arm satisfies its correlated `multiple`/`type`
+        // variant; the cast collapses the runtime union onto the
+        // `Multiple`-conditional return, which TS can't correlate itself.
+        const field = multiple
+            ? { ...common, type: "json", multiple: true }
+            : { ...common, type: "string" };
+        return field;
+    }
+}
+_a = SelectFieldBuilder;
+/**
+ * Choice field over a fixed option list —
+ * `select("size").options(["s", "m", "l"])`. Single-value by default;
+ * `.multiple()` stores an array, `.appearance()` picks the admin
+ * control. The option list is required: only `.options()` is available
+ * on the bare constructor.
+ */
+export function select(key) {
+    return new SelectFieldSeed(key);
 }
 //# sourceMappingURL=select.js.map

package/dist/plugin/fields/select.js.map

@@ -1 +1 @@
-{"version":3,"file":"select.js","sourceRoot":"","sources":["../../../src/plugin/fields/select.ts"],"names":[],"mappings":"AAmBA;;;;GAIG;AACH,MAAM,UAAU,MAAM,CAAC,OAA2B;IAChD,OAAO;QACL,GAAG,EAAE,OAAO,CAAC,GAAG;QAChB,KAAK,EAAE,OAAO,CAAC,KAAK;QACpB,IAAI,EAAE,QAAQ;QACd,SAAS,EAAE,QAAQ;QACnB,OAAO,EAAE,OAAO,CAAC,OAAO;QACxB,QAAQ,EAAE,OAAO,CAAC,QAAQ;QAC1B,WAAW,EAAE,OAAO,CAAC,WAAW;QAChC,OAAO,EAAE,OAAO,CAAC,OAAO;QACxB,IAAI,EAAE,OAAO,CAAC,IAAI;QAClB,UAAU,EAAE,OAAO,CAAC,UAAU;QAC9B,QAAQ,EAAE,OAAO,CAAC,QAAQ;KAC3B,CAAC;AACJ,CAAC"}
+{"version":3,"file":"select.js","sourceRoot":"","sources":["../../../src/plugin/fields/select.ts"],"names":[],"mappings":"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"}

package/dist/plugin/fields/sub-fields.d.ts

@@ -0,0 +1,12 @@
+import type { MetaBoxField } from "../manifest.js";
+import type { SubFieldContainer } from "./errors.js";
+/**
+ * Validate the child fields of a composite field (`repeater` / `group`)
+ * at registration: key shape, prototype-pollution guard, uniqueness,
+ * and the not-yet-implemented nested-condition rejection. Nested
+ * repeaters and groups are permitted — each composite validates its own
+ * immediate children, so arbitrarily deep nesting is covered as each
+ * builder is constructed.
+ */
+export declare function assertSubFields(container: SubFieldContainer, containerKey: string, subFields: readonly MetaBoxField[]): void;
+//# sourceMappingURL=sub-fields.d.ts.map

package/dist/plugin/fields/sub-fields.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sub-fields.d.ts","sourceRoot":"","sources":["../../../src/plugin/fields/sub-fields.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AACnD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAmBrD;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAC7B,SAAS,EAAE,iBAAiB,EAC5B,YAAY,EAAE,MAAM,EACpB,SAAS,EAAE,SAAS,YAAY,EAAE,GACjC,IAAI,CAqCN"}

package/dist/plugin/fields/sub-fields.js

@@ -0,0 +1,62 @@
+import { FieldConfigError } from "./errors.js";
+// Mirrors `META_FIELD_KEY_RE` in plugin/validation/meta-box-fields.ts.
+// The top-level registrar validates field keys against this regex but
+// doesn't recurse into composite children, so repeater / group enforce
+// it locally — guards row/member-object shape and protects against
+// duplicate-key clobber.
+const SUBFIELD_KEY_RE = /^[a-zA-Z0-9_:-]+$/;
+// `__proto__` / `constructor` / `prototype` match the key regex but
+// writing them into a fresh object literal mutates the prototype chain.
+// Reject at registration regardless of regex pass.
+const FORBIDDEN_SUBFIELD_KEYS = new Set([
+    "__proto__",
+    "constructor",
+    "prototype",
+]);
+/**
+ * Validate the child fields of a composite field (`repeater` / `group`)
+ * at registration: key shape, prototype-pollution guard, uniqueness,
+ * and the not-yet-implemented nested-condition rejection. Nested
+ * repeaters and groups are permitted — each composite validates its own
+ * immediate children, so arbitrarily deep nesting is covered as each
+ * builder is constructed.
+ */
+export function assertSubFields(container, containerKey, subFields) {
+    const seen = new Set();
+    for (const sf of subFields) {
+        if (FORBIDDEN_SUBFIELD_KEYS.has(sf.key)) {
+            throw FieldConfigError.subFieldKeyForbidden({
+                container,
+                containerKey,
+                subFieldKey: sf.key,
+            });
+        }
+        if (!SUBFIELD_KEY_RE.test(sf.key)) {
+            throw FieldConfigError.subFieldKeyInvalid({
+                container,
+                containerKey,
+                subFieldKey: sf.key,
+                pattern: SUBFIELD_KEY_RE.source,
+            });
+        }
+        if (seen.has(sf.key)) {
+            throw FieldConfigError.subFieldDuplicate({
+                container,
+                containerKey,
+                subFieldKey: sf.key,
+            });
+        }
+        // Nested conditions aren't wired: the admin evaluator and the write
+        // pipeline both read driver values from the top-level box scope, so
+        // a row/member `visibleWhen` would register a silent no-op.
+        if (sf.visibleWhen !== undefined) {
+            throw FieldConfigError.subFieldCondition({
+                container,
+                containerKey,
+                subFieldKey: sf.key,
+            });
+        }
+        seen.add(sf.key);
+    }
+}
+//# sourceMappingURL=sub-fields.js.map

package/dist/plugin/fields/sub-fields.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sub-fields.js","sourceRoot":"","sources":["../../../src/plugin/fields/sub-fields.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAE/C,uEAAuE;AACvE,sEAAsE;AACtE,uEAAuE;AACvE,mEAAmE;AACnE,yBAAyB;AACzB,MAAM,eAAe,GAAG,mBAAmB,CAAC;AAE5C,oEAAoE;AACpE,wEAAwE;AACxE,mDAAmD;AACnD,MAAM,uBAAuB,GAAwB,IAAI,GAAG,CAAC;IAC3D,WAAW;IACX,aAAa;IACb,WAAW;CACZ,CAAC,CAAC;AAEH;;;;;;;GAOG;AACH,MAAM,UAAU,eAAe,CAC7B,SAA4B,EAC5B,YAAoB,EACpB,SAAkC;IAElC,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,KAAK,MAAM,EAAE,IAAI,SAAS,EAAE,CAAC;QAC3B,IAAI,uBAAuB,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC;YACxC,MAAM,gBAAgB,CAAC,oBAAoB,CAAC;gBAC1C,SAAS;gBACT,YAAY;gBACZ,WAAW,EAAE,EAAE,CAAC,GAAG;aACpB,CAAC,CAAC;QACL,CAAC;QACD,IAAI,CAAC,eAAe,CAAC,IAAI,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC;YAClC,MAAM,gBAAgB,CAAC,kBAAkB,CAAC;gBACxC,SAAS;gBACT,YAAY;gBACZ,WAAW,EAAE,EAAE,CAAC,GAAG;gBACnB,OAAO,EAAE,eAAe,CAAC,MAAM;aAChC,CAAC,CAAC;QACL,CAAC;QACD,IAAI,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC;YACrB,MAAM,gBAAgB,CAAC,iBAAiB,CAAC;gBACvC,SAAS;gBACT,YAAY;gBACZ,WAAW,EAAE,EAAE,CAAC,GAAG;aACpB,CAAC,CAAC;QACL,CAAC;QACD,oEAAoE;QACpE,oEAAoE;QACpE,4DAA4D;QAC5D,IAAI,EAAE,CAAC,WAAW,KAAK,SAAS,EAAE,CAAC;YACjC,MAAM,gBAAgB,CAAC,iBAAiB,CAAC;gBACvC,SAAS;gBACT,YAAY;gBACZ,WAAW,EAAE,EAAE,CAAC,GAAG;aACpB,CAAC,CAAC;QACL,CAAC;QACD,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC;IACnB,CAAC;AACH,CAAC"}

package/dist/plugin/fields/temporal.d.ts

@@ -0,0 +1,124 @@
+import type { Label } from "../../i18n/label.js";
+import type { FieldBuilder, MetaBoxFieldSpan, MetaBoxFieldValidate, TemporalInputType, TemporalMetaBoxField } from "../manifest.js";
+import type { MetaFieldCondition, MetaFieldConditionRule } from "./condition.js";
+export type { TemporalInputType } from "../manifest.js";
+/** Read type after `.returns("date")` — optionality carries over from `V`. */
+type ProjectedDate<V> = undefined extends V ? Date | undefined : Date;
+interface TemporalFieldState {
+    readonly visibleWhen?: MetaFieldCondition;
+    readonly label?: Label;
+    readonly description?: Label;
+    readonly default?: string;
+    readonly required?: true;
+    readonly span?: MetaBoxFieldSpan;
+    readonly capability?: string;
+    readonly showInApi?: true;
+    readonly min?: string;
+    readonly max?: string;
+    readonly returns?: "date";
+    readonly sanitize?: (value: unknown) => unknown;
+    readonly validate?: MetaBoxFieldValidate;
+}
+/**
+ * Fluent chain for the temporal fields (`date`, `datetime`, `time`).
+ * Storage is always the ISO-shaped string the native input produces —
+ * the phantom stored shape `S` stays a string even when
+ * `.returns("date")` projects the read type `V` to a JS `Date` at
+ * decode time. `.sanitize()` / `.validate()` run on the write side,
+ * so their callbacks always see the stored string regardless of the
+ * read projection.
+ */
+export declare class TemporalFieldBuilder<Input extends TemporalInputType = TemporalInputType, K extends string = string, V extends string | Date | undefined = string | undefined, S extends string | undefined = string | undefined> implements FieldBuilder<TemporalMetaBoxField<Input>> {
+    #private;
+    /** Phantom literal key of the field — type-level only, never assigned. */
+    readonly _key: K;
+    /** Phantom read type of the field — type-level only, never assigned. */
+    readonly _value: V;
+    /** Phantom stored shape of the field — type-level only, never assigned. */
+    readonly _stored: S;
+    constructor(inputType: Input, key: string, state?: TemporalFieldState);
+    /** Override the derived (humanized-key) label. */
+    label(label: Label): TemporalFieldBuilder<Input, K, V, S>;
+    /** Help text rendered under the label. */
+    description(description: Label): TemporalFieldBuilder<Input, K, V, S>;
+    /**
+     * Default for absent keys — an ISO string in the field's stored
+     * shape, applied at read decode (and seeded into the admin form).
+     * Narrows the read type to non-optional; the stored shape stays
+     * optional.
+     */
+    default(value: string): TemporalFieldBuilder<Input, K, NonNullable<V>, S>;
+    /** Mark the field required — narrows the read and stored types to non-optional. */
+    required(): TemporalFieldBuilder<Input, K, NonNullable<V>, string>;
+    /**
+     * Column span within the box's 12-column grid — a universal layout
+     * hint; surfaces that can't honor it (the entry editor rail) ignore it.
+     */
+    span(span: MetaBoxFieldSpan): TemporalFieldBuilder<Input, K, V, S>;
+    /** Capability gate for this field — see `MetaBoxFieldBase.capability`. */
+    capability(capability: string): TemporalFieldBuilder<Input, K, V, S>;
+    /** Opt this field's value into public REST responses (default-deny). */
+    showInApi(): TemporalFieldBuilder<Input, K, V, S>;
+    /** Rule factory: this field's value equals `value` — pass the rule
+     *  to a dependent field's `.visibleWhen()`. */
+    is(value: string): MetaFieldConditionRule;
+    /** Rule factory: this field's value differs from `value`. */
+    isNot(value: string): MetaFieldConditionRule;
+    /** Rule factory: this field has no value (unset or cleared). */
+    isEmpty(): MetaFieldConditionRule;
+    /** Rule factory: this field has a value. */
+    isNotEmpty(): MetaFieldConditionRule;
+    /**
+     * Show this field only when every rule passes (one AND group) —
+     * rules come from sibling fields' condition factories. Replaces any
+     * previously declared condition; `.orVisibleWhen()` adds
+     * alternatives.
+     */
+    visibleWhen(...rules: MetaFieldConditionRule[]): TemporalFieldBuilder<Input, K, V, S>;
+    /** Add an OR alternative — one more AND group of rules. */
+    orVisibleWhen(...rules: MetaFieldConditionRule[]): TemporalFieldBuilder<Input, K, V, S>;
+    /** Lower bound in the field's stored ISO shape, enforced by the constraint walker. */
+    min(min: string): TemporalFieldBuilder<Input, K, V, S>;
+    /** Upper bound in the field's stored ISO shape, enforced by the constraint walker. */
+    max(max: string): TemporalFieldBuilder<Input, K, V, S>;
+    /**
+     * Project reads to a JS `Date` at decode time — the read type
+     * follows; storage remains the ISO string. Wall-clock components
+     * anchor to UTC (`date` at UTC midnight, `time` on 1970-01-01 UTC)
+     * so they survive any server/browser timezone split — read them
+     * back with `getUTC*` or `timeZone: "UTC"` formatting. `Date`
+     * values written back encode from UTC components symmetrically.
+     */
+    returns(shape: "date"): TemporalFieldBuilder<Input, K, ProjectedDate<V>, S>;
+    /**
+     * Normalising transform, applied after coercion and before
+     * persistence. Always receives the stored ISO string — the
+     * `.returns("date")` projection is read-side only.
+     */
+    sanitize(sanitize: (value: string) => string): TemporalFieldBuilder<Input, K, V, S>;
+    /**
+     * Custom validation — `true` for valid, or an i18n-able failure
+     * message (sync or async). Runs after `.sanitize()` on the stored
+     * ISO string.
+     */
+    validate(validate: (value: string) => true | Label | Promise<true | Label>): TemporalFieldBuilder<Input, K, V, S>;
+    /** Compile the chain into the wire/manifest field definition. */
+    build(): TemporalMetaBoxField<Input>;
+}
+/**
+ * Date-only field, stored as `YYYY-MM-DD`. Renders as a native
+ * `<input type="date">` in the admin. `.returns("date")` reads a JS
+ * `Date` instead of the ISO string.
+ */
+export declare function date<K extends string>(key: K): TemporalFieldBuilder<"date", K>;
+/**
+ * Date + time field, stored as `YYYY-MM-DDTHH:MM` (optional `:SS`) —
+ * naive local time from `<input type="datetime-local">`.
+ */
+export declare function datetime<K extends string>(key: K): TemporalFieldBuilder<"datetime", K>;
+/**
+ * Time-only field, stored as `HH:MM` (optional `:SS`). Combine with a
+ * `date` field when both are needed.
+ */
+export declare function time<K extends string>(key: K): TemporalFieldBuilder<"time", K>;
+//# sourceMappingURL=temporal.d.ts.map

package/dist/plugin/fields/temporal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"temporal.d.ts","sourceRoot":"","sources":["../../../src/plugin/fields/temporal.ts"],"names":[],"mappings":"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"}