@plumix/core 0.5.0 → 0.7.0

package/dist/plugin/fields/temporal.js

@@ -0,0 +1,180 @@
+var _a;
+import { isValidTemporalValue } from "../manifest.js";
+import { humanizeFieldKey } from "./builder.js";
+import { FieldConfigError } from "./errors.js";
+/**
+ * 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 class TemporalFieldBuilder {
+    #inputType;
+    #key;
+    #state;
+    constructor(inputType, key, state = {}) {
+        this.#inputType = inputType;
+        this.#key = key;
+        this.#state = state;
+    }
+    #fork(patch) {
+        return new _a(this.#inputType, this.#key, {
+            ...this.#state,
+            ...patch,
+        });
+    }
+    /** Override the derived (humanized-key) label. */
+    label(label) {
+        return this.#fork({ label });
+    }
+    /** Help text rendered under the label. */
+    description(description) {
+        return this.#fork({ description });
+    }
+    /**
+     * 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) {
+        return this.#fork({ default: value });
+    }
+    /** Mark the field required — narrows the read and stored types to non-optional. */
+    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()`. */
+    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" };
+    }
+    /**
+     * 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],
+        });
+    }
+    /** Lower bound in the field's stored ISO shape, enforced by the constraint walker. */
+    min(min) {
+        return this.#fork({ min });
+    }
+    /** Upper bound in the field's stored ISO shape, enforced by the constraint walker. */
+    max(max) {
+        return this.#fork({ max });
+    }
+    /**
+     * 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) {
+        return this.#fork({ returns: shape });
+    }
+    /**
+     * Normalising transform, applied after coercion and before
+     * persistence. Always receives the stored ISO string — the
+     * `.returns("date")` projection is read-side only.
+     */
+    sanitize(sanitize) {
+        return this.#fork({ sanitize: sanitize });
+    }
+    /**
+     * Custom validation — `true` for valid, or an i18n-able failure
+     * message (sync or async). Runs after `.sanitize()` on the stored
+     * ISO string.
+     */
+    validate(validate) {
+        return this.#fork({ validate: validate });
+    }
+    /** Compile the chain into the wire/manifest field definition. */
+    build() {
+        // A typo'd bound would otherwise silently reject every write —
+        // bounds compare lexicographically against the stored shape, so a
+        // malformed one sorts nonsensically. Fail loudly at registration.
+        for (const bound of ["min", "max"]) {
+            const value = this.#state[bound];
+            if (value !== undefined &&
+                !isValidTemporalValue(this.#inputType, value)) {
+                throw FieldConfigError.temporalBoundInvalid({
+                    fieldKey: this.#key,
+                    bound,
+                    value,
+                });
+            }
+        }
+        return {
+            ...this.#state,
+            key: this.#key,
+            label: this.#state.label ?? humanizeFieldKey(this.#key),
+            type: "string",
+            inputType: this.#inputType,
+        };
+    }
+}
+_a = TemporalFieldBuilder;
+/**
+ * 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 function date(key) {
+    return new TemporalFieldBuilder("date", key);
+}
+/**
+ * Date + time field, stored as `YYYY-MM-DDTHH:MM` (optional `:SS`) —
+ * naive local time from `<input type="datetime-local">`.
+ */
+export function datetime(key) {
+    return new TemporalFieldBuilder("datetime", key);
+}
+/**
+ * Time-only field, stored as `HH:MM` (optional `:SS`). Combine with a
+ * `date` field when both are needed.
+ */
+export function time(key) {
+    return new TemporalFieldBuilder("time", key);
+}
+//# sourceMappingURL=temporal.js.map

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

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

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

@@ -1,5 +1,4 @@
-import type { Label } from "../../i18n/label.js";
-import type { MetaBoxFieldSpan, TermReferenceMetaBoxField } from "../manifest.js";
+import { ReferenceFieldBuilder } from "./reference.js";
 /**
  * Public scope shape for the `term()` reference field. Carried on
  * the field's `referenceTarget.scope`; the term `LookupAdapter`
@@ -11,24 +10,20 @@ export interface TermFieldScope {
      * Restrict matches to these taxonomies. Required at the field
      * level — term references without a taxonomy filter would surface
      * tags + categories + custom taxonomies in one indistinct list.
+     * Seeded from the `term()` constructor argument.
      */
     readonly termTaxonomies: readonly string[];
 }
-export interface TermFieldOptions {
-    readonly key: string;
-    readonly label: Label;
-    readonly required?: boolean;
-    readonly description?: Label;
-    readonly default?: string;
-    readonly span?: MetaBoxFieldSpan;
-    readonly capability?: string;
-    readonly termTaxonomies: readonly string[];
-}
 /**
- * Build a typed `term` reference field. Storage is the bare term id;
- * reads return the resolved label/subtitle (or `null` for orphans).
+ * Build a typed `term` reference field —
+ * `term("primary", ["category"])`. The required taxonomy scope is the
+ * constructor's second argument; `.multiple()` flips to an id array.
+ *
+ * Storage is the bare term id (an id array under `.multiple()`). Reads
+ * hydrate to the term summary by default (`.returns("id")` opts back
+ * to the bare id); single reads stay optional (a target can orphan).
  * The admin renders a picker that calls the lookup RPC with
- * `{ kind: "term", scope: { termTaxonomies } }`.
+ * `{ kind: "term", scope }`.
  */
-export declare function term(options: TermFieldOptions): TermReferenceMetaBoxField;
+export declare function term<K extends string>(key: K, termTaxonomies: readonly string[]): ReferenceFieldBuilder<"term", K>;
 //# sourceMappingURL=term.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"term.d.ts","sourceRoot":"","sources":["../../../src/plugin/fields/term.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAC;AACjD,OAAO,KAAK,EACV,gBAAgB,EAChB,yBAAyB,EAC1B,MAAM,gBAAgB,CAAC;AAExB;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B;;;;OAIG;IACH,QAAQ,CAAC,cAAc,EAAE,SAAS,MAAM,EAAE,CAAC;CAC5C;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IACtB,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,cAAc,EAAE,SAAS,MAAM,EAAE,CAAC;CAC5C;AAED;;;;;GAKG;AACH,wBAAgB,IAAI,CAAC,OAAO,EAAE,gBAAgB,GAAG,yBAAyB,CAgBzE"}
+{"version":3,"file":"term.d.ts","sourceRoot":"","sources":["../../../src/plugin/fields/term.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAC;AAEvD;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B;;;;;OAKG;IACH,QAAQ,CAAC,cAAc,EAAE,SAAS,MAAM,EAAE,CAAC;CAC5C;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,IAAI,CAAC,CAAC,SAAS,MAAM,EACnC,GAAG,EAAE,CAAC,EACN,cAAc,EAAE,SAAS,MAAM,EAAE,GAChC,qBAAqB,CAAC,MAAM,EAAE,CAAC,CAAC,CAElC"}

package/dist/plugin/fields/term.js

@@ -1,24 +1,16 @@
+import { ReferenceFieldBuilder } from "./reference.js";
 /**
- * Build a typed `term` reference field. Storage is the bare term id;
- * reads return the resolved label/subtitle (or `null` for orphans).
+ * Build a typed `term` reference field —
+ * `term("primary", ["category"])`. The required taxonomy scope is the
+ * constructor's second argument; `.multiple()` flips to an id array.
+ *
+ * Storage is the bare term id (an id array under `.multiple()`). Reads
+ * hydrate to the term summary by default (`.returns("id")` opts back
+ * to the bare id); single reads stay optional (a target can orphan).
  * The admin renders a picker that calls the lookup RPC with
- * `{ kind: "term", scope: { termTaxonomies } }`.
+ * `{ kind: "term", scope }`.
  */
-export function term(options) {
-    const scope = {
-        termTaxonomies: options.termTaxonomies,
-    };
-    return {
-        key: options.key,
-        label: options.label,
-        type: "string",
-        inputType: "term",
-        referenceTarget: { kind: "term", scope },
-        required: options.required,
-        description: options.description,
-        default: options.default,
-        span: options.span,
-        capability: options.capability,
-    };
+export function term(key, termTaxonomies) {
+    return new ReferenceFieldBuilder("term", key, { termTaxonomies });
 }
 //# sourceMappingURL=term.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"term.js","sourceRoot":"","sources":["../../../src/plugin/fields/term.ts"],"names":[],"mappings":"AAgCA;;;;;GAKG;AACH,MAAM,UAAU,IAAI,CAAC,OAAyB;IAC5C,MAAM,KAAK,GAAmB;QAC5B,cAAc,EAAE,OAAO,CAAC,cAAc;KACvC,CAAC;IACF,OAAO;QACL,GAAG,EAAE,OAAO,CAAC,GAAG;QAChB,KAAK,EAAE,OAAO,CAAC,KAAK;QACpB,IAAI,EAAE,QAAQ;QACd,SAAS,EAAE,MAAM;QACjB,eAAe,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE;QACxC,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;KAC/B,CAAC;AACJ,CAAC"}
+{"version":3,"file":"term.js","sourceRoot":"","sources":["../../../src/plugin/fields/term.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAC;AAkBvD;;;;;;;;;;GAUG;AACH,MAAM,UAAU,IAAI,CAClB,GAAM,EACN,cAAiC;IAEjC,OAAO,IAAI,qBAAqB,CAAC,MAAM,EAAE,GAAG,EAAE,EAAE,cAAc,EAAE,CAAC,CAAC;AACpE,CAAC"}

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

@@ -0,0 +1,97 @@
+import type { Label } from "../../i18n/label.js";
+import type { FieldBuilder, MetaBoxFieldSpan, MetaBoxFieldValidate, ToggleMetaBoxField } from "../manifest.js";
+import type { MetaFieldCondition, MetaFieldConditionRule } from "./condition.js";
+interface ToggleFieldState {
+    readonly visibleWhen?: MetaFieldCondition;
+    readonly onText?: Label;
+    readonly offText?: Label;
+    readonly label?: Label;
+    readonly description?: Label;
+    readonly default?: boolean;
+    readonly required?: true;
+    readonly span?: MetaBoxFieldSpan;
+    readonly capability?: string;
+    readonly showInApi?: true;
+    readonly sanitize?: (value: unknown) => unknown;
+    readonly validate?: MetaBoxFieldValidate;
+}
+/**
+ * Fluent chain for the boolean switch field. Immutable — every call
+ * returns a fresh instance, so a shared base chain can be forked
+ * without aliasing. `V` is the phantom read type: `boolean |
+ * undefined` unadorned, narrowed to `boolean` by `.required()` /
+ * `.default()`. Purely type-level — nothing at runtime carries it.
+ */
+export declare class ToggleFieldBuilder<K extends string = string, V extends boolean | undefined = boolean | undefined, S extends boolean | undefined = boolean | undefined> implements FieldBuilder<ToggleMetaBoxField> {
+    #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;
+    constructor(key: K, state?: ToggleFieldState);
+    /** Label shown beside the switch while it is on. */
+    onText(onText: Label): ToggleFieldBuilder<K, V, S>;
+    /** Label shown beside the switch while it is off. */
+    offText(offText: Label): ToggleFieldBuilder<K, V, S>;
+    /** Override the derived (humanized-key) label. */
+    label(label: Label): ToggleFieldBuilder<K, V, S>;
+    /** Help text rendered under the label. */
+    description(description: Label): ToggleFieldBuilder<K, V, S>;
+    /** Admin-form prefill for unsaved keys — narrows the read type to `boolean`. */
+    default(value: boolean): ToggleFieldBuilder<K, boolean, S>;
+    /** Mark the field required — narrows the read type to `boolean`. */
+    required(): ToggleFieldBuilder<K, boolean, boolean>;
+    /**
+     * 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): ToggleFieldBuilder<K, V, S>;
+    /** Capability gate for this field — see `MetaBoxFieldBase.capability`. */
+    capability(capability: string): ToggleFieldBuilder<K, V, S>;
+    /** Opt this field's value into public REST responses (default-deny). */
+    showInApi(): ToggleFieldBuilder<K, V, S>;
+    /** Rule factory: this field's value equals `value` — pass the rule
+     *  to a dependent field's `.visibleWhen()`. */
+    is(value: boolean): MetaFieldConditionRule;
+    /** Rule factory: this field's value differs from `value`. */
+    isNot(value: boolean): 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 switch is on. */
+    isOn(): MetaFieldConditionRule;
+    /** Rule factory: the switch is off. `neq true` rather than
+     *  `eq false`, so an unset toggle (which renders as off) counts. */
+    isOff(): 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[]): ToggleFieldBuilder<K, V, S>;
+    /** Add an OR alternative — one more AND group of rules. */
+    orVisibleWhen(...rules: MetaFieldConditionRule[]): ToggleFieldBuilder<K, V, S>;
+    /** Normalising transform, applied after coercion and before persistence. */
+    sanitize(sanitize: (value: NonNullable<V>) => NonNullable<V>): ToggleFieldBuilder<K, 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>): ToggleFieldBuilder<K, V, S>;
+    /** Compile the chain into the wire/manifest field definition. */
+    build(): ToggleMetaBoxField;
+}
+/**
+ * Boolean switch field — `toggle("featured").onText("Yes").offText("No")`.
+ * Reads as `boolean | undefined`, narrowed by `.required()` /
+ * `.default()`.
+ */
+export declare function toggle<K extends string>(key: K): ToggleFieldBuilder<K>;
+export {};
+//# sourceMappingURL=toggle.d.ts.map

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

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

package/dist/plugin/fields/toggle.js

@@ -0,0 +1,135 @@
+var _a;
+import { humanizeFieldKey } from "./builder.js";
+/**
+ * Fluent chain for the boolean switch field. Immutable — every call
+ * returns a fresh instance, so a shared base chain can be forked
+ * without aliasing. `V` is the phantom read type: `boolean |
+ * undefined` unadorned, narrowed to `boolean` by `.required()` /
+ * `.default()`. Purely type-level — nothing at runtime carries it.
+ */
+export class ToggleFieldBuilder {
+    #key;
+    #state;
+    constructor(key, state = {}) {
+        this.#key = key;
+        this.#state = state;
+    }
+    #fork(patch) {
+        return new _a(this.#key, {
+            ...this.#state,
+            ...patch,
+        });
+    }
+    /** Label shown beside the switch while it is on. */
+    onText(onText) {
+        return this.#fork({ onText });
+    }
+    /** Label shown beside the switch while it is off. */
+    offText(offText) {
+        return this.#fork({ offText });
+    }
+    /** 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 the read type to `boolean`. */
+    default(value) {
+        return this.#fork({ default: value });
+    }
+    /** Mark the field required — narrows the read type to `boolean`. */
+    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()`. */
+    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 switch is on. */
+    isOn() {
+        return { key: this.#key, op: "eq", value: true };
+    }
+    /** Rule factory: the switch is off. `neq true` rather than
+     *  `eq false`, so an unset toggle (which renders as off) counts. */
+    isOff() {
+        return { key: this.#key, op: "neq", value: true };
+    }
+    /**
+     * 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. */
+    build() {
+        return {
+            ...this.#state,
+            key: this.#key,
+            label: this.#state.label ?? humanizeFieldKey(this.#key),
+            type: "boolean",
+            inputType: "toggle",
+        };
+    }
+}
+_a = ToggleFieldBuilder;
+/**
+ * Boolean switch field — `toggle("featured").onText("Yes").offText("No")`.
+ * Reads as `boolean | undefined`, narrowed by `.required()` /
+ * `.default()`.
+ */
+export function toggle(key) {
+    return new ToggleFieldBuilder(key);
+}
+//# sourceMappingURL=toggle.js.map

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

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

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

@@ -1,6 +1,5 @@
 import type { UserRole } from "../../db/schema/users.js";
-import type { Label } from "../../i18n/label.js";
-import type { MetaBoxFieldSpan, UserMetaBoxField } from "../manifest.js";
+import { ReferenceFieldBuilder } from "./reference.js";
 /**
  * Public scope shape for the `user()` reference field. Carried on
  * the field's `referenceTarget.scope`; the user `LookupAdapter`
@@ -8,36 +7,25 @@ import type { MetaBoxFieldSpan, UserMetaBoxField } from "../manifest.js";
  * read-time orphan resolution.
  */
 export interface UserFieldScope {
-    /** Restrict matches to these roles. Empty/absent → any role. */
+    /** Restrict matches to these roles. Empty/absent → any role. Set via `.roles()`. */
     readonly roles?: readonly UserRole[];
     /**
-     * Whether to surface disabled accounts. Default `false` —
-     * disabled users are usually invalid reference targets even
-     * though the row still exists.
+     * Whether to surface disabled accounts. Default `false` — disabled
+     * users are usually invalid reference targets even though the row
+     * still exists. Set via `.includeDisabled()`.
      */
     readonly includeDisabled?: boolean;
 }
-export interface UserFieldOptions {
-    readonly key: string;
-    readonly label: Label;
-    readonly required?: boolean;
-    readonly description?: Label;
-    readonly default?: string;
-    readonly span?: MetaBoxFieldSpan;
-    readonly capability?: string;
-    readonly roles?: readonly UserRole[];
-    readonly includeDisabled?: boolean;
-}
 /**
- * Build a typed `user` reference field. Storage is the bare user id
- * as a string (`"42"` → `users.id = 42`); reads return the resolved
- * user (or `null` when the target is gone or no longer matches
- * scope). The admin renders a picker that calls the lookup RPC with
- * `{ kind: "user", scope: { roles, includeDisabled } }`.
+ * Build a typed `user` reference field — `user("owner")`. Scope is
+ * optional and chained (`.roles([...])`, `.includeDisabled()`);
+ * `.multiple()` flips to an id array.
  *
- * Scope rolls the two filters (`roles`, `includeDisabled`) into the
- * builder's flat option shape — internally they're packaged into a
- * `referenceTarget.scope` object the user adapter consumes.
+ * Storage is the bare user id as a string (an id array under
+ * `.multiple()`). Reads hydrate to the user summary by default
+ * (`.returns("id")` opts back to the bare id); single reads stay
+ * optional (a target can orphan). The admin renders a picker that
+ * calls the lookup RPC with `{ kind: "user", scope }`.
  */
-export declare function user(options: UserFieldOptions): UserMetaBoxField;
+export declare function user<K extends string>(key: K): ReferenceFieldBuilder<"user", K>;
 //# sourceMappingURL=user.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"user.d.ts","sourceRoot":"","sources":["../../../src/plugin/fields/user.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AACzD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAC;AACjD,OAAO,KAAK,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAEzE;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B,gEAAgE;IAChE,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,QAAQ,EAAE,CAAC;IACrC;;;;OAIG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,CAAC;CACpC;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IACtB,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,KAAK,CAAC,EAAE,SAAS,QAAQ,EAAE,CAAC;IACrC,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,CAAC;CACpC;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,IAAI,CAAC,OAAO,EAAE,gBAAgB,GAAG,gBAAgB,CAiBhE"}
+{"version":3,"file":"user.d.ts","sourceRoot":"","sources":["../../../src/plugin/fields/user.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AACzD,OAAO,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAC;AAEvD;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B,oFAAoF;IACpF,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,QAAQ,EAAE,CAAC;IACrC;;;;OAIG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,CAAC;CACpC;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,IAAI,CAAC,CAAC,SAAS,MAAM,EACnC,GAAG,EAAE,CAAC,GACL,qBAAqB,CAAC,MAAM,EAAE,CAAC,CAAC,CAElC"}

package/dist/plugin/fields/user.js

@@ -1,30 +1,16 @@
+import { ReferenceFieldBuilder } from "./reference.js";
 /**
- * Build a typed `user` reference field. Storage is the bare user id
- * as a string (`"42"` → `users.id = 42`); reads return the resolved
- * user (or `null` when the target is gone or no longer matches
- * scope). The admin renders a picker that calls the lookup RPC with
- * `{ kind: "user", scope: { roles, includeDisabled } }`.
+ * Build a typed `user` reference field — `user("owner")`. Scope is
+ * optional and chained (`.roles([...])`, `.includeDisabled()`);
+ * `.multiple()` flips to an id array.
  *
- * Scope rolls the two filters (`roles`, `includeDisabled`) into the
- * builder's flat option shape — internally they're packaged into a
- * `referenceTarget.scope` object the user adapter consumes.
+ * Storage is the bare user id as a string (an id array under
+ * `.multiple()`). Reads hydrate to the user summary by default
+ * (`.returns("id")` opts back to the bare id); single reads stay
+ * optional (a target can orphan). The admin renders a picker that
+ * calls the lookup RPC with `{ kind: "user", scope }`.
  */
-export function user(options) {
-    const scope = {
-        roles: options.roles,
-        includeDisabled: options.includeDisabled,
-    };
-    return {
-        key: options.key,
-        label: options.label,
-        type: "string",
-        inputType: "user",
-        referenceTarget: { kind: "user", scope },
-        required: options.required,
-        description: options.description,
-        default: options.default,
-        span: options.span,
-        capability: options.capability,
-    };
+export function user(key) {
+    return new ReferenceFieldBuilder("user", key, {});
 }
 //# sourceMappingURL=user.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"user.js","sourceRoot":"","sources":["../../../src/plugin/fields/user.ts"],"names":[],"mappings":"AAiCA;;;;;;;;;;GAUG;AACH,MAAM,UAAU,IAAI,CAAC,OAAyB;IAC5C,MAAM,KAAK,GAAmB;QAC5B,KAAK,EAAE,OAAO,CAAC,KAAK;QACpB,eAAe,EAAE,OAAO,CAAC,eAAe;KACzC,CAAC;IACF,OAAO;QACL,GAAG,EAAE,OAAO,CAAC,GAAG;QAChB,KAAK,EAAE,OAAO,CAAC,KAAK;QACpB,IAAI,EAAE,QAAQ;QACd,SAAS,EAAE,MAAM;QACjB,eAAe,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE;QACxC,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;KAC/B,CAAC;AACJ,CAAC"}
+{"version":3,"file":"user.js","sourceRoot":"","sources":["../../../src/plugin/fields/user.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAC;AAmBvD;;;;;;;;;;GAUG;AACH,MAAM,UAAU,IAAI,CAClB,GAAM;IAEN,OAAO,IAAI,qBAAqB,CAAC,MAAM,EAAE,GAAG,EAAE,EAAE,CAAC,CAAC;AACpD,CAAC"}