@getaster/elements 0.3.5 → 0.4.0

package/dist/dialog/dialog.d.ts

@@ -1,20 +1,48 @@
 import { AsterElement, type View } from "../base/element.ts";
 /**
- * A modal dialog over a native `<dialog>`: the rest of the page is inert,
- * focus goes in on open and returns to the opener on close, and Escape or
- * a click on the backdrop closes it. One dialog morphs between views
- * (`showView`) rather than stacking modals.
+ * A dialog over a native `<dialog>`: modal by default, so the rest of the
+ * page is inert and focus stays inside; non-modal with `modal = false`, where
+ * the page stays usable. One dialog morphs between views (`showView`)
+ * rather than stacking dialogs. Escape and a backdrop press dismiss it unless
+ * the host turns those off.
  */
 export declare class Dialog extends AsterElement {
     #private;
     /** The dialog's contents; usually a template reading the current view. */
     get content(): View;
     set content(v: View);
-    /** The id of the element that names the dialog. */
+    /** The id of the element that names the dialog. It wins over `title`. */
     get labelledBy(): string | undefined;
     set labelledBy(v: string | undefined);
+    /** The dialog's title, as text. Setting it shows a header unless `header` is false. Default `""`. */
+    get title(): string;
+    set title(v: string);
+    /** Whether the header bar is drawn. Default: shown when `title` is set. */
+    get header(): boolean | undefined;
+    set header(v: boolean | undefined);
+    /** The footer contents, shown below the content when set. */
+    get footer(): View;
+    set footer(v: View);
+    /** Whether the header carries a Close control. Default `false`. */
+    get showCloseButton(): boolean | undefined;
+    set showCloseButton(v: boolean | undefined);
+    /** Whether the dialog is modal. Default `true`; non-modal leaves the page usable. */
+    get modal(): boolean;
+    set modal(v: boolean);
+    /** Whether Escape closes the dialog. Default `true`. */
+    get dismissOnEscape(): boolean;
+    set dismissOnEscape(v: boolean);
+    /** Whether a press on the backdrop closes a modal dialog. Default `true`. */
+    get dismissOnBackdrop(): boolean;
+    set dismissOnBackdrop(v: boolean);
+    /**
+     * Where focus goes on open: the first focusable element (default), the
+     * dialog itself, nowhere, or a function returning the element to focus.
+     */
+    get initialFocus(): "first" | "dialog" | "none" | (() => HTMLElement | null) | undefined;
+    set initialFocus(v: "first" | "dialog" | "none" | (() => HTMLElement | null) | undefined);
     get open(): boolean;
-    /** Opens modally. `focus` is the element to focus inside; otherwise the first focusable. */
+    /** Opens the dialog. `focus` is still accepted and wins over `initialFocus`. */
     show(opener?: HTMLElement | null, focus?: () => HTMLElement | null): void;
     close(): void;
     /** Changes view in place: the panel morphs, then the new content inks in. */

package/dist/dialog/dialog.js

@@ -1,15 +1,27 @@
 import { html, nothing } from "lit-html";
-import { AsterElement, define } from "../base/element.js";
+import { AsterElement, define, uid } from "../base/element.js";
 import { morph } from "../motion.js";
+import { dialogCloseShown, dialogHeaderShown } from "./config.js";
+const FOCUSABLE = "a[href], button, input, select, textarea, [tabindex]";
 /**
- * A modal dialog over a native `<dialog>`: the rest of the page is inert,
- * focus goes in on open and returns to the opener on close, and Escape or
- * a click on the backdrop closes it. One dialog morphs between views
- * (`showView`) rather than stacking modals.
+ * A dialog over a native `<dialog>`: modal by default, so the rest of the
+ * page is inert and focus stays inside; non-modal with `modal = false`, where
+ * the page stays usable. One dialog morphs between views (`showView`)
+ * rather than stacking dialogs. Escape and a backdrop press dismiss it unless
+ * the host turns those off.
  */
 export class Dialog extends AsterElement {
     #content = this.prop(nothing);
     #label = this.prop(undefined);
+    #title = this.prop("");
+    #header = this.prop(undefined);
+    #footer = this.prop(nothing);
+    #showClose = this.prop(undefined);
+    #modal = this.prop(true);
+    #dismissOnEscape = this.prop(true);
+    #dismissOnBackdrop = this.prop(true);
+    #initialFocus = this.prop(undefined);
+    #id = uid("aster-dialog");
     #opener = null;
     /** The dialog's contents; usually a template reading the current view. */
     get content() {
@@ -18,26 +30,98 @@ export class Dialog extends AsterElement {
     set content(v) {
         this.#content.value = v;
     }
-    /** The id of the element that names the dialog. */
+    /** The id of the element that names the dialog. It wins over `title`. */
     get labelledBy() {
         return this.#label.value;
     }
     set labelledBy(v) {
         this.#label.value = v;
     }
+    /** The dialog's title, as text. Setting it shows a header unless `header` is false. Default `""`. */
+    get title() {
+        return this.#title.value;
+    }
+    set title(v) {
+        if (typeof v !== "string")
+            throw new TypeError("title must be a string");
+        this.#title.value = v;
+    }
+    /** Whether the header bar is drawn. Default: shown when `title` is set. */
+    get header() {
+        return this.#header.value;
+    }
+    set header(v) {
+        if (v !== undefined && typeof v !== "boolean")
+            throw new TypeError("header must be a boolean");
+        this.#header.value = v;
+    }
+    /** The footer contents, shown below the content when set. */
+    get footer() {
+        return this.#footer.value;
+    }
+    set footer(v) {
+        this.#footer.value = v;
+    }
+    /** Whether the header carries a Close control. Default `false`. */
+    get showCloseButton() {
+        return this.#showClose.value;
+    }
+    set showCloseButton(v) {
+        if (v !== undefined && typeof v !== "boolean")
+            throw new TypeError("showCloseButton must be a boolean");
+        this.#showClose.value = v;
+    }
+    /** Whether the dialog is modal. Default `true`; non-modal leaves the page usable. */
+    get modal() {
+        return this.#modal.value;
+    }
+    set modal(v) {
+        if (typeof v !== "boolean")
+            throw new TypeError("modal must be a boolean");
+        this.#modal.value = v;
+    }
+    /** Whether Escape closes the dialog. Default `true`. */
+    get dismissOnEscape() {
+        return this.#dismissOnEscape.value;
+    }
+    set dismissOnEscape(v) {
+        this.#dismissOnEscape.value = v !== false;
+    }
+    /** Whether a press on the backdrop closes a modal dialog. Default `true`. */
+    get dismissOnBackdrop() {
+        return this.#dismissOnBackdrop.value;
+    }
+    set dismissOnBackdrop(v) {
+        this.#dismissOnBackdrop.value = v !== false;
+    }
+    /**
+     * Where focus goes on open: the first focusable element (default), the
+     * dialog itself, nowhere, or a function returning the element to focus.
+     */
+    get initialFocus() {
+        return this.#initialFocus.value;
+    }
+    set initialFocus(v) {
+        if (v !== undefined && v !== "first" && v !== "dialog" && v !== "none" && typeof v !== "function") {
+            throw new TypeError('initialFocus must be "first", "dialog", "none" or a function');
+        }
+        this.#initialFocus.value = v;
+    }
     get open() {
         return this.#dialog()?.open ?? false;
     }
-    /** Opens modally. `focus` is the element to focus inside; otherwise the first focusable. */
+    /** Opens the dialog. `focus` is still accepted and wins over `initialFocus`. */
     show(opener = document.activeElement, focus) {
         const dialog = this.#dialog();
         if (!dialog || dialog.open)
             return;
+        const previous = document.activeElement instanceof HTMLElement ? document.activeElement : null;
         this.#opener = opener;
-        dialog.showModal();
-        const target = focus?.();
-        if (target)
-            target.focus();
+        if (this.#modal.value)
+            dialog.showModal();
+        else
+            dialog.show();
+        this.#focusInitial(focus?.(), previous);
     }
     close() {
         const dialog = this.#dialog();
@@ -50,12 +134,62 @@ export class Dialog extends AsterElement {
         morph(change);
     }
     render() {
-        return html `<dialog class="aster-dialog" aria-labelledby=${this.#label.value ?? nothing}
+        const title = this.#title.value;
+        const header = dialogHeaderShown(title, this.#header.value);
+        const close = dialogCloseShown(header, this.#showClose.value);
+        const titleId = `${this.#id}-title`;
+        const labelledBy = this.#label.value ?? (header && title ? titleId : undefined);
+        return html `<dialog class="aster-dialog" aria-labelledby=${labelledBy ?? nothing}
+      aria-label=${labelledBy ? nothing : title || nothing} tabindex="-1"
       @close=${() => this.#closed()}
-      @click=${(e) => e.target === e.currentTarget && this.close()}>
-      <div class="aster-dialog-panel">${this.#content.value}</div>
+      @cancel=${(e) => {
+            e.preventDefault();
+            if (this.#dismissOnEscape.peek())
+                this.close();
+        }}
+      @keydown=${(e) => {
+            if (e.key !== "Escape" || e.defaultPrevented)
+                return;
+            e.preventDefault();
+            e.stopPropagation();
+            if (this.#dismissOnEscape.value)
+                this.close();
+        }}
+      @click=${(e) => e.target === e.currentTarget && this.#dismissOnBackdrop.value && this.close()}>
+      <div class="aster-dialog-panel">
+        ${header ? html `<div class="aster-dialog-head">
+          ${title ? html `<h2 class="aster-dialog-title" id=${titleId}>${title}</h2>` : nothing}
+          ${close ? html `<button type="button" class="aster-dialog-close" aria-label="Close"
+            @click=${() => this.close()}><svg viewBox="0 0 16 16" aria-hidden="true"><path d="M4 4l8 8M12 4l-8 8"/></svg></button>` : nothing}
+        </div>` : nothing}
+        ${this.#content.value}
+        ${this.#footer.value === nothing ? nothing : html `<div class="aster-dialog-footer">${this.#footer.value}</div>`}
+      </div>
     </dialog>`;
     }
+    /** An explicit function wins, then a configured policy; otherwise the native focus steps stand. */
+    #focusInitial(explicit, previous) {
+        const dialog = this.#dialog();
+        if (!dialog || (!explicit && this.#initialFocus.peek() === undefined))
+            return;
+        const target = explicit ?? this.#policyTarget(dialog, previous);
+        target?.focus();
+    }
+    #policyTarget(dialog, previous) {
+        const mode = this.#initialFocus.peek();
+        if (typeof mode === "function")
+            return mode() ?? undefined;
+        switch (mode) {
+            case "none":
+                // A modal dialog must contain focus; otherwise restore what was focused before show().
+                return this.#modal.peek() ? dialog : (previous?.isConnected && !dialog.contains(previous) ? previous : undefined);
+            case "dialog":
+                return dialog;
+            case "first":
+            case undefined:
+                return dialog.querySelector("[autofocus]") ?? [...dialog.querySelectorAll(FOCUSABLE)].find(isFocusable) ?? dialog;
+        }
+    }
     #closed() {
         const opener = this.#opener;
         this.#opener = null;
@@ -67,4 +201,7 @@ export class Dialog extends AsterElement {
         return this.querySelector("dialog");
     }
 }
+function isFocusable(element) {
+    return element.tabIndex >= 0 && !element.hasAttribute("disabled") && element.getAttribute("aria-disabled") !== "true";
+}
 define("aster-dialog", Dialog);

package/dist/field/bound-field.d.ts

@@ -1,5 +1,7 @@
 import type { EditModel, Field as FieldMeta, FieldState, Value } from "@getaster/data";
 import { AsterElement, type View } from "../base/element.ts";
+/** When a bound field revalidates its own value. */
+export type ValidateOn = "submit" | "change" | "exit";
 /** What a control needs to render itself inside a bound field. */
 export interface ControlContext {
     readonly id: string;
@@ -7,7 +9,7 @@ export interface ControlContext {
     readonly meta: FieldMeta | undefined;
     readonly value: Value | undefined;
     readonly state: FieldState;
-    /** `aria-describedby` for the control: the error, then the read-only reason. */
+    /** `aria-describedby` for the control: its error, hint, reasons and pending note. */
     readonly describedBy: string | undefined;
     readonly invalid: boolean;
     readonly label: string;
@@ -43,6 +45,20 @@ export declare abstract class BoundField extends AsterElement {
      */
     get sharedReasons(): ReadonlyMap<string, string>;
     set sharedReasons(v: ReadonlyMap<string, string>);
+    /** Help text under the control, in addition to the label. */
+    get hint(): string;
+    set hint(v: string);
+    /** Whether to draw the error under the control. Default `true`; the control still reports `aria-invalid`. */
+    get showErrors(): boolean;
+    set showErrors(v: boolean);
+    /**
+     * When the field revalidates itself: only when the host validates
+     * (`"submit"`, the default), after every edit (`"change"`), or when focus
+     * leaves it (`"exit"`).
+     */
+    get validateOn(): ValidateOn;
+    set validateOn(v: ValidateOn);
+    connectedCallback(): void;
     protected abstract control(c: ControlContext): View;
     /** Control-specific validation supplements the model's errors. */
     protected validation(_meta: FieldMeta | undefined, _value: Value | undefined): string | undefined;

package/dist/field/bound-field.js

@@ -21,6 +21,9 @@ export class BoundField extends AsterElement {
     #label = this.prop("");
     #labelled = this.prop(false);
     #shared = this.prop(new Map());
+    #hint = this.prop("");
+    #showErrors = this.prop(true);
+    #validateOn = this.prop("submit");
     #uid = uid("aster-field");
     get model() {
         return this.#model.value;
@@ -58,6 +61,47 @@ export class BoundField extends AsterElement {
     set sharedReasons(v) {
         this.#shared.value = v;
     }
+    /** Help text under the control, in addition to the label. */
+    get hint() {
+        return this.#hint.value;
+    }
+    set hint(v) {
+        this.#hint.value = v;
+    }
+    /** Whether to draw the error under the control. Default `true`; the control still reports `aria-invalid`. */
+    get showErrors() {
+        return this.#showErrors.value;
+    }
+    set showErrors(v) {
+        this.#showErrors.value = v;
+    }
+    /**
+     * When the field revalidates itself: only when the host validates
+     * (`"submit"`, the default), after every edit (`"change"`), or when focus
+     * leaves it (`"exit"`).
+     */
+    get validateOn() {
+        return this.#validateOn.value;
+    }
+    set validateOn(v) {
+        if (v !== "submit" && v !== "change" && v !== "exit")
+            throw new TypeError('validateOn must be "submit", "change" or "exit"');
+        this.#validateOn.value = v;
+    }
+    connectedCallback() {
+        super.connectedCallback();
+        this.listen(this, "focusout", (event) => {
+            if (this.#validateOn.peek() !== "exit")
+                return;
+            const next = event.relatedTarget;
+            if (next instanceof Node && this.contains(next))
+                return;
+            const model = this.#model.peek();
+            const name = this.#field.peek();
+            if (model?.type.field(name))
+                model.validateField(name);
+        });
+    }
     /** Control-specific validation supplements the model's errors. */
     validation(_meta, _value) { return undefined; }
     /** The frame and anything beside it; a subclass can wrap the control. */
@@ -76,7 +120,13 @@ export class BoundField extends AsterElement {
     </label>`;
     }
     write(value) {
-        this.#model.peek()?.set(this.#field.peek(), value);
+        const model = this.#model.peek();
+        if (!model)
+            return;
+        const name = this.#field.peek();
+        model.set(name, value);
+        if (this.#validateOn.peek() === "change")
+            model.validateField(name);
     }
     render() {
         const model = this.#model.value;
@@ -89,10 +139,17 @@ export class BoundField extends AsterElement {
         const hidden = model?.hidden.value.has(name) ?? false;
         const error = model?.errors.value[name]?.[0] ?? this.validation(meta, model?.values.value[name]);
         const pending = model && meta ? model.pending(name).value : false;
+        const hint = this.#hint.value;
+        const showErrors = this.#showErrors.value;
         const reason = state.readOnly ? state.reasons.readOnly : undefined;
-        const sharedId = reason === undefined ? undefined : this.#shared.value.get(reason);
-        const errorId = `${this.#uid}-error`;
-        const reasonId = sharedId ?? `${this.#uid}-reason`;
+        const disabledReason = state.enabled ? undefined : state.reasons.enabled;
+        const sharedId = (text) => (text === undefined ? undefined : this.#shared.value.get(text));
+        const hintId = hint ? `${this.#uid}-hint` : undefined;
+        const errorId = showErrors && error ? `${this.#uid}-error` : undefined;
+        const reasonShared = sharedId(reason);
+        const disabledShared = sharedId(disabledReason);
+        const reasonId = reason ? reasonShared ?? `${this.#uid}-reason` : undefined;
+        const disabledId = disabledReason ? disabledShared ?? `${this.#uid}-disabled` : undefined;
         const pendingId = `${this.#uid}-pending`;
         const suggestedId = `${this.#uid}-suggested`;
         const suggested = !hidden && !state.readOnly && (model?.derived(name).value ?? false);
@@ -106,12 +163,14 @@ export class BoundField extends AsterElement {
             meta,
             value: model?.values.value[name],
             state,
-            describedBy: [error ? errorId : "", reason ? reasonId : "", changed ? pendingId : "", suggested ? suggestedId : ""].filter(Boolean).join(" ") || undefined,
+            describedBy: [errorId ?? "", hintId ?? "", reasonId ?? "", disabledId ?? "", changed ? pendingId : "", suggested ? suggestedId : ""].filter(Boolean).join(" ") || undefined,
             invalid: error !== undefined,
             label,
         };
+        this.setAttribute("data-field", name);
         this.toggleAttribute("data-pending", pending);
         this.toggleAttribute("data-readonly", state.readOnly);
+        this.toggleAttribute("data-disabled", !state.enabled);
         this.toggleAttribute("data-value-hidden", hidden);
         this.toggleAttribute("data-suggested", suggested);
         const was = this.describe(meta, model?.baseline.value[name]) || "empty";
@@ -131,9 +190,11 @@ export class BoundField extends AsterElement {
           </div>`
             : nothing}
       ${hidden ? this.#hiddenValue(c) : this.row(c)}
+      ${hint && hintId ? html `<p class="aster-hint" id=${hintId}>${hint}</p>` : nothing}
       ${suggested ? html `<p class="aster-hint" id=${suggestedId}>Suggested value</p>` : nothing}
       ${changed ? html `<span class="aster-sr-only" id=${pendingId}>${pendingText}</span>` : nothing}
-      ${reason && !sharedId ? html `<p class="aster-hint" id=${reasonId}>${reason}</p>` : nothing}
-      ${error ? html `<p class="aster-error" id=${errorId} role="alert">${error}</p>` : nothing}`;
+      ${reason && reasonId && !reasonShared ? html `<p class="aster-hint" id=${reasonId}>${reason}</p>` : nothing}
+      ${disabledReason && disabledId && !disabledShared ? html `<p class="aster-hint" id=${disabledId}>${disabledReason}</p>` : nothing}
+      ${showErrors && error && errorId ? html `<p class="aster-error" id=${errorId} role="alert">${error}</p>` : nothing}`;
     }
 }

package/dist/field/check.js

@@ -16,6 +16,7 @@ export class Check extends BoundField {
         aria-label=${this.labelled ? nothing : c.label}
         aria-readonly=${c.state.readOnly ? "true" : nothing}
         aria-required=${c.state.required ? "true" : nothing}
+        ?disabled=${!c.state.enabled}
         @click=${(e) => c.state.readOnly && e.preventDefault()}
         aria-invalid=${c.invalid ? "true" : nothing}
         aria-describedby=${c.describedBy ?? nothing}

package/dist/field/field.js

@@ -64,7 +64,7 @@ export class Field extends BoundField {
         const kind = inputKind(c.meta);
         return inputView({ id: c.id, value: text, type: kind.type, keyboard: this.#keyboard.value || kind.inputmode || "",
             ...(this.labelled ? {} : { label: c.label }), placeholder: this.#placeholder.value, readOnly, required: c.state.required,
-            invalid: c.invalid, ...(c.describedBy ? { describedBy: c.describedBy } : {}), ...(isProse(c.meta) ? { rows: 2 } : {}),
+            disabled: !c.state.enabled, invalid: c.invalid, ...(c.describedBy ? { describedBy: c.describedBy } : {}), ...(isProse(c.meta) ? { rows: 2 } : {}),
             input: (text) => this.write(parseInput(c.meta, text)) });
     }
 }

package/dist/field/input.d.ts

@@ -8,6 +8,7 @@ export declare function inputView(p: {
     readonly keyboard?: string;
     readonly placeholder?: string;
     readonly readOnly?: boolean;
+    readonly disabled?: boolean;
     readonly required?: boolean;
     readonly invalid?: boolean;
     readonly describedBy?: string;

package/dist/field/input.js

@@ -4,12 +4,12 @@ import { live } from "lit-html/directives/live.js";
 export function inputView(p) {
     return html `<label class=${p.rows ? "aster-field aster-field-prose" : "aster-field"} data-ring-owner>
     ${p.rows ? html `<textarea id=${p.id ?? nothing} rows=${p.rows} .value=${live(p.value)}
-      aria-label=${p.label ?? nothing} placeholder=${p.placeholder || nothing} ?readonly=${p.readOnly}
+      aria-label=${p.label ?? nothing} placeholder=${p.placeholder || nothing} ?readonly=${p.readOnly} ?disabled=${p.disabled}
       aria-required=${p.required ? "true" : nothing} aria-invalid=${p.invalid ? "true" : nothing}
       aria-describedby=${p.describedBy ?? nothing}
       @input=${(e) => p.input(e.target.value)}></textarea>`
         : html `<input id=${p.id ?? nothing} type=${p.type ?? "text"} inputmode=${p.keyboard || nothing} .value=${live(p.value)}
-        aria-label=${p.label ?? nothing} placeholder=${p.placeholder || nothing} ?readonly=${p.readOnly}
+        aria-label=${p.label ?? nothing} placeholder=${p.placeholder || nothing} ?readonly=${p.readOnly} ?disabled=${p.disabled}
         aria-required=${p.required ? "true" : nothing} aria-invalid=${p.invalid ? "true" : nothing}
         aria-describedby=${p.describedBy ?? nothing} autocomplete="off" spellcheck="false"
         @focus=${(e) => p.readOnly && e.target.select()}

package/dist/field/number-field.js

@@ -152,7 +152,7 @@ export class NumberField extends BoundField {
       <input id=${c.id} type="text" inputmode=${this.#kind(c.meta) === "integer" ? "numeric" : "decimal"}
         .value=${live(text)} aria-label=${this.labelled ? nothing : c.label} aria-describedby=${c.describedBy ?? nothing}
         aria-required=${c.state.required ? "true" : nothing} aria-invalid=${c.invalid ? "true" : nothing}
-        ?readonly=${readOnly} placeholder=${this.#placeholder.value || nothing} autocomplete="off" spellcheck="false"
+        ?readonly=${readOnly} ?disabled=${!c.state.enabled} placeholder=${this.#placeholder.value || nothing} autocomplete="off" spellcheck="false"
         @focus=${(e) => {
             this.#focused.value = true;
             if (display !== entered)
@@ -167,7 +167,7 @@ export class NumberField extends BoundField {
         }}>
       ${this.#suffix.value ? html `<span class="aster-number-affix">${this.#suffix.value}</span>` : nothing}
       ${this.#buttons.value ? html `<span class="aster-number-steps">
-        ${[-1, 1].map(d => html `<button type="button" aria-label=${`${d === 1 ? "Increase" : "Decrease"} ${c.label}`} ?disabled=${readOnly || this.#next(d, c) === undefined}
+        ${[-1, 1].map(d => html `<button type="button" aria-label=${`${d === 1 ? "Increase" : "Decrease"} ${c.label}`} ?disabled=${!c.state.enabled || readOnly || this.#next(d, c) === undefined}
           @mousedown=${(e) => { if (e.button === 0)
             e.preventDefault(); }} @click=${() => step(d)}>
           <svg viewBox="0 0 16 16" aria-hidden="true"><path d=${d === 1 ? "M3 8h10M8 3v10" : "M3 8h10"}/></svg>

package/dist/filter/filter-builder.d.ts

@@ -1,4 +1,4 @@
-import { type FilterDraft } from "@getaster/data";
+import { type FilterDraft, type Field } from "@getaster/data";
 import { AsterElement, type View } from "../base/element.ts";
 /** A standalone metadata-driven Criteria editor, with local drafts and cancellable apply/cancel events. */
 export declare class FilterBuilder extends AsterElement {
@@ -12,6 +12,12 @@ export declare class FilterBuilder extends AsterElement {
     /** A reason shown instead of editable controls. */
     get readOnlyReason(): string | undefined;
     set readOnlyReason(value: string | undefined);
+    /**
+     * The operators offered for a field, such as a page's per-field allowlist.
+     * Default: the metadata's operators, from [[staticMethod:filterOperators]].
+     */
+    get operators(): ((field: Field | undefined) => readonly string[]) | undefined;
+    set operators(value: ((field: Field | undefined) => readonly string[]) | undefined);
     focus(options?: FocusOptions): void;
     protected render(): View;
     protected updated(): void;

package/dist/filter/filter-builder.js

@@ -20,6 +20,7 @@ export class FilterBuilder extends AsterElement {
     #model = this.prop(undefined);
     #label = this.prop("Advanced filter");
     #readOnly = this.prop(undefined);
+    #operators = this.prop(undefined);
     #choices = new Map();
     #lists = new Map();
     #customRelative = signal(new Set());
@@ -41,6 +42,12 @@ export class FilterBuilder extends AsterElement {
     /** A reason shown instead of editable controls. */
     get readOnlyReason() { return this.#readOnly.value; }
     set readOnlyReason(value) { this.#readOnly.value = value; }
+    /**
+     * The operators offered for a field, such as a page's per-field allowlist.
+     * Default: the metadata's operators, from [[staticMethod:filterOperators]].
+     */
+    get operators() { return this.#operators.value; }
+    set operators(value) { this.#operators.value = value; }
     focus(options) { this.querySelector("[role=combobox], input, button")?.focus(options); }
     render() {
         const model = this.#model.value;
@@ -86,7 +93,7 @@ export class FilterBuilder extends AsterElement {
         const remove = !root ? html `<button type="button" class="aster-list-edit-action" aria-label=${`Remove ${name}`} @click=${() => this.#remove(node.id)}>Remove</button>` : nothing;
         if (node.kind === "condition") {
             const field = this.#field(type, node.field);
-            const operators = filterOperators(field);
+            const operators = this.#operators.value ? this.#operators.value(field) : filterOperators(field);
             return html `<div class="aster-filter-condition" role="group" aria-label=${name} data-clause=${node.id}>
         <div class="aster-filter-condition-fields">
           ${this.#choice(`${node.id}-field`, `${name}: field`, node.field, this.#fields(type), (field) => model.change(node.id, { field }), errorId)}

package/dist/form/controls.d.ts

@@ -1,20 +1,52 @@
-import type { Collection, EditModel } from "@getaster/data";
+import type { Collection, EditModel, Value } from "@getaster/data";
 import type { PickerOptions } from "../picker/options.ts";
 import { type TemplateResult } from "lit-html";
+import type { View } from "../base/element.ts";
+import type { ControlContext } from "../field/bound-field.ts";
 import "../date/date-field.ts";
 import "../field/check.ts";
 import "../field/field.ts";
 import "../field/number-field.ts";
 import "../picker/picker.ts";
 import "../select/select.ts";
+import "./custom-field.ts";
+import type { ValidateOn } from "./features.ts";
+/** The editors the form can be told to use for a field. */
+export type FormControlName = "text" | "number" | "date" | "check" | "select" | "picker";
+/** What a custom editor gets: the bound field's context plus a write that respects the field's state. */
+export interface FormControlContext extends ControlContext {
+    readonly write: (value: Value) => void;
+}
+/** A JavaScript-only editor renderer; composition catalogs reject it. */
+export type FormControlRender = (context: FormControlContext) => View;
+/** A typed editor override: a control name, or a renderer for a custom control. */
+export type FormControl = FormControlName | FormControlRender;
+/** What [[staticMethod:controlFor]] accepts. Only `labelled` is required. */
+export interface ControlOptions {
+    /** A foreign key's choices; when given the default control is a picker. */
+    readonly options?: Collection | PickerOptions | undefined;
+    readonly labelled: boolean;
+    readonly span?: number | undefined;
+    readonly sharedReasons?: ReadonlyMap<string, string> | undefined;
+    /** A label override; default: the field's metadata title. */
+    readonly title?: string | undefined;
+    /** Help text under the control. */
+    readonly hint?: string | undefined;
+    /** Placeholder text, for the controls that have one. */
+    readonly placeholder?: string | undefined;
+    /** A typed editor override, or a custom renderer (JavaScript only). */
+    readonly control?: FormControl | undefined;
+    /** When to revalidate the field. Default `"submit"`. */
+    readonly validateOn?: ValidateOn;
+    /** Draw the error under the field. Default `true`. */
+    readonly showErrors?: boolean;
+}
+/** The control metadata picks for a field, before any override. */
+export declare function metadataControl(model: EditModel, name: string, options: ControlOptions["options"]): FormControlName;
 /**
  * The control for one field, chosen from metadata: a foreign key with
  * `options` gives a picker, a Boolean a checkbox, allowed values a select,
- * a Date the date field, anything else a field.
+ * a Date the date field, anything else a field. `control` replaces that
+ * choice with a named editor, or with a renderer that draws its own.
  */
-export declare function controlFor(model: EditModel, name: string, opts: {
-    options?: Collection | PickerOptions | undefined;
-    labelled: boolean;
-    span?: number;
-    sharedReasons?: ReadonlyMap<string, string>;
-}): TemplateResult;
+export declare function controlFor(model: EditModel, name: string, opts: ControlOptions): TemplateResult;