declarative-forms 2.0.0-alpha.0

package/dist/index.d.cts

@@ -0,0 +1,1235 @@
+/**
+ * Opt-in HTML for label/message/option content.
+ *
+ * Everything the library renders is treated as plain text by default. When you
+ * genuinely need markup — a link inside a checkbox caption, a tag badge inside a
+ * select option — wrap it in {@link html} to say so explicitly.
+ */
+declare const SAFE_HTML: unique symbol;
+/** A string the caller has explicitly marked as trusted HTML. */
+declare class SafeHtml {
+    readonly value: string;
+    /** Brand used by {@link isSafeHtml} so instances survive duplicated module copies. */
+    readonly [SAFE_HTML] = true;
+    constructor(value: string);
+    toString(): string;
+}
+declare function isSafeHtml(value: unknown): value is SafeHtml;
+/** Escape a string for interpolation into an HTML context. */
+declare function escapeHtml(value: unknown): string;
+/**
+ * Mark content as trusted HTML.
+ *
+ * As a tagged template, interpolated values are escaped and only the literal
+ * parts are trusted — this is the form you want for anything data-driven:
+ *
+ * ```ts
+ * html`<b>${userSuppliedName}</b>`
+ * ```
+ *
+ * Called with a plain string, the whole string is trusted. Use it only for
+ * markup you control:
+ *
+ * ```ts
+ * html('<span class="dl-option-tag">Offline</span>')
+ * ```
+ */
+declare function html(raw: string): SafeHtml;
+declare function html(strings: TemplateStringsArray, ...values: unknown[]): SafeHtml;
+/** Content that is rendered as text unless explicitly wrapped in {@link html}. */
+type TextOrHtml = string | SafeHtml;
+
+/**
+ * Set an element's content from a {@link TextOrHtml}.
+ *
+ * Plain strings go through `textContent`; only values explicitly wrapped in
+ * `html()` reach `innerHTML`.
+ */
+declare function setContent(el: Element, content: TextOrHtml | null | undefined): void;
+
+/** A snapshot of a form's values. Always carries the active tab under `activeTab`. */
+type FormValues = Record<string, unknown>;
+/**
+ * Everything a descriptor callback is given.
+ *
+ * v1 passed these as a different positional argument list per callback
+ * (`isActive(formData, stack, field, parentData)` vs `tab(field)` vs
+ * `defaultValue(formData)`). One context object makes them uniform, typed, and
+ * extensible without another breaking change.
+ */
+interface FieldContext {
+    /** Current values of this form. */
+    readonly data: FormValues;
+    /** The form the field belongs to. */
+    readonly form: DeclarativeForm;
+    /** The descriptor being evaluated. */
+    readonly field: FieldDescriptor;
+    /** Values of the enclosing form, when this form is nested (array entry or sub-dialog). */
+    readonly parentData: FormValues | undefined;
+    /** Values of every form currently on the modal stack, outermost first. */
+    readonly stackData: readonly FormValues[];
+    /** True while the field is rendered inside an "edit existing array entry" dialog. */
+    readonly isEditingArrayEntry: boolean;
+}
+/** Context for `onFormChange`, which also knows what triggered the update. */
+interface FormChangeContext extends FieldContext {
+    /** The field whose input triggered this update, if any. */
+    readonly trigger: FieldHandle | undefined;
+}
+/** Context handed to a `custom` field's `render`. */
+interface RenderContext extends FieldContext {
+    /** The element to render into. Owned by the field; safe to replace its children. */
+    readonly element: HTMLElement;
+    /** Re-run the form update cycle, e.g. after mutating a value from custom UI. */
+    requestUpdate(force?: boolean): void;
+    /** Set this field's value and trigger an update. */
+    setValue(value: unknown): void;
+}
+/** Context for an options loader that rejected. */
+interface OptionsErrorContext extends FieldContext {
+    readonly error: unknown;
+}
+/** A message to surface on a field's tooltip. */
+interface FieldMessage {
+    level: 'info' | 'warning' | 'error';
+    text: string;
+}
+/** A value that may be provided directly, or computed from the form context. */
+type Reactive<T> = T | ((ctx: FieldContext) => T);
+/** A tab name, or several — a field may appear in more than one tab. */
+type TabSpec = string | readonly string[];
+interface TooltipDescriptor {
+    text: TextOrHtml;
+    /** Render the tooltip marker inside the input rather than next to the label. */
+    inInput?: boolean;
+}
+/**
+ * A select option.
+ *
+ * - `'JavaScript'` — value and label are the same
+ * - `{ value: 'js', label: 'JavaScript' }`
+ * - `{ value: 'js', label: 'JavaScript', displayWhenSelected: 'Lang: JS' }`
+ */
+type SelectOption = string | {
+    value: string;
+    label: TextOrHtml;
+    /** Shown in the closed input / multi-select tag instead of `label`. */
+    displayWhenSelected?: string;
+};
+/** Properties shared by every field kind. */
+interface BaseFieldDescriptor {
+    /** Key this field's value appears under in `getValues()`. Must be unique per form. */
+    name: string;
+    /** Label text. Omit to render the field without a label (adds `.withoutLabel`). */
+    displayName?: TextOrHtml;
+    /** Extra class names for the field wrapper, space separated. */
+    className?: string;
+    /** Tab(s) this field belongs to. */
+    tab?: Reactive<TabSpec | undefined>;
+    /** Help marker rendered next to the label, or inside the input. */
+    tooltip?: TextOrHtml | TooltipDescriptor;
+    /** Return false to hide the field and drop it from `getValues()`. */
+    isActive?: (ctx: FieldContext) => boolean;
+    /** Called on every form update, after values settle. */
+    onFormChange?: (ctx: FormChangeContext) => void;
+    /** Names of fields whose change should re-run this field's async work. */
+    reloadOnChangeOf?: readonly string[];
+    /** Initial value, or a function of the form context. */
+    defaultValue?: Reactive<unknown>;
+}
+interface TextFieldDescriptor extends BaseFieldDescriptor {
+    kind?: 'text';
+    /** Maps to the `type` attribute — `'text'`, `'password'`, `'number'`, `'email'`, … */
+    type?: string;
+    placeholder?: Reactive<string | undefined>;
+    /** Maps to the `autocomplete` attribute. Defaults to off at the form level. */
+    autocomplete?: string;
+}
+interface TextAreaFieldDescriptor extends BaseFieldDescriptor {
+    kind: 'textarea';
+    placeholder?: Reactive<string | undefined>;
+    /** When false (the default), Enter confirms the dialog instead of inserting a newline. */
+    allowNewlines?: boolean;
+}
+interface SelectFieldDescriptor extends BaseFieldDescriptor {
+    kind: 'select';
+    /** Options, or a sync/async function of the form context. */
+    options: Reactive<readonly SelectOption[] | Promise<readonly SelectOption[]> | undefined>;
+    /** Allow selecting several options. The value becomes a `string[]`. */
+    multiple?: boolean;
+    placeholder?: Reactive<string | undefined>;
+    /** Turn a rejected `options` promise into a tooltip message. */
+    onOptionsError?: (ctx: OptionsErrorContext) => FieldMessage | undefined;
+}
+interface CheckboxFieldDescriptor extends BaseFieldDescriptor {
+    kind: 'checkbox';
+    /** Caption rendered next to the box. Wrap in `html()` for links. */
+    label: TextOrHtml;
+}
+interface MessageFieldDescriptor extends BaseFieldDescriptor {
+    kind: 'message';
+    /** Static text, or a function of the form context. Wrap in `html()` for markup. */
+    message: Reactive<TextOrHtml>;
+}
+interface FileFieldDescriptor extends BaseFieldDescriptor {
+    kind: 'file';
+    /** Maps to the `accept` attribute, e.g. `'image/png, image/jpeg'`. */
+    accept?: string;
+}
+interface ComputedFieldDescriptor extends BaseFieldDescriptor {
+    kind: 'computed';
+    /** Derives the value. May be async; runs before the form is confirmed. */
+    compute: (ctx: FieldContext) => unknown;
+}
+interface CardsFieldDescriptor extends BaseFieldDescriptor {
+    kind: 'cards';
+    cards: readonly {
+        value: string;
+        content: TextOrHtml;
+    }[];
+}
+interface CustomFieldDescriptor extends BaseFieldDescriptor {
+    kind: 'custom';
+    /** Render into `ctx.element`. Called on mount and on every form update. */
+    render: (ctx: RenderContext) => void;
+}
+interface ArrayFieldDescriptor extends BaseFieldDescriptor {
+    kind: 'array';
+    /** Field descriptors for one entry. */
+    of: readonly FieldDescriptor[];
+    /** Label for the add button. Defaults to `'Add'`. */
+    newButtonLabel?: string;
+    /** One-line summary of an entry. Defaults to joining its non-empty string values. */
+    renderEntry?: (entry: FormValues) => TextOrHtml;
+    /** Gate the entry dialog's confirm button. */
+    isValidRecord?: (entry: FormValues, ctx: FieldContext) => boolean | Promise<boolean>;
+    /** Adjust the entry fields when editing an existing entry rather than adding one. */
+    mapFieldsOnEdit?: (fields: readonly FieldDescriptor[], entry: FormValues) => readonly FieldDescriptor[];
+    /** Entries offered as opt-in checkboxes above the list. */
+    suggested?: Reactive<readonly FormValues[] | undefined>;
+    /** Called after an entry is added, edited or removed. */
+    onChange?: (values: FormValues) => void;
+}
+/** Any built-in field. */
+type FieldDescriptor = TextFieldDescriptor | TextAreaFieldDescriptor | SelectFieldDescriptor | CheckboxFieldDescriptor | MessageFieldDescriptor | FileFieldDescriptor | ComputedFieldDescriptor | CardsFieldDescriptor | CustomFieldDescriptor | ArrayFieldDescriptor;
+/** The `kind` discriminant of a built-in field. */
+type FieldKind = NonNullable<FieldDescriptor['kind']>;
+
+/**
+ * Pluggable tooltip backend.
+ *
+ * v1 hard-depended on tippy.js (and transitively @popperjs/core). The default
+ * implementation here is native and dependency-free; pass your own provider to
+ * `new DeclarativeForm({ tooltipProvider })` to restore tippy or use any other
+ * library.
+ */
+interface TooltipProvider {
+    /**
+     * Attach a tooltip to `element` showing `content` (an HTML string).
+     * Called again with new content when the tooltip text changes.
+     */
+    attach(element: HTMLElement, content: string): void;
+    /** Detach the tooltip from `element` and release any resources. */
+    detach(element: HTMLElement): void;
+}
+
+/** Predicate context for button state, mirroring {@link FieldContext}. */
+interface ButtonContext {
+    readonly data: FormValues;
+    readonly parentData: FormValues | undefined;
+    readonly stackData: readonly FormValues[];
+}
+interface ButtonDescriptor {
+    /** Invoked with the form values when the button is pressed. May be async. */
+    action?: (values: FormValues) => unknown;
+    /**
+     * DOM id for the button element.
+     *
+     * Required for `isActive` / `isVisible` to be wired up — a button without an
+     * id is rendered but never state-managed.
+     */
+    id?: string;
+    /** Extra class names, space separated. `'secondary'` is styled by the default CSS. */
+    class?: string;
+    /** Enable/disable the button. Async predicates are supported. */
+    isActive?: (ctx: ButtonContext) => boolean | Promise<boolean>;
+    /** Show/hide the button. */
+    isVisible?: (ctx: ButtonContext) => boolean | Promise<boolean>;
+    /** Run `action` without closing the dialog — for wizard "Next"/"Back" buttons. */
+    doNotCloseModal?: boolean;
+}
+/** Buttons keyed by their visible label. */
+type ButtonMap = Record<string, ButtonDescriptor>;
+interface DeclarativeFormOptions {
+    fields: readonly FieldDescriptor[];
+    /**
+     * Buttons for the dialog's lower bar, keyed by label.
+     * Defaults to a single `OK` button running {@link onConfirm}.
+     */
+    buttons?: ButtonMap;
+    /** Label for the default confirm button. Ignored when `buttons` is given. */
+    confirmLabel?: string;
+    /** Run when the dialog is confirmed. May be async. */
+    onConfirm?: (values: FormValues) => unknown;
+    /**
+     * Run when the dialog is dismissed via Esc or the close button.
+     * Omit to make the dialog non-dismissable — no close button is rendered.
+     */
+    onCancel?: () => void;
+    /** Extra class names added to the inner `<form>` element. */
+    classNames?: readonly string[];
+    /** Persist a picked file and resolve to the URL to store as the field's value. */
+    persistFile?: (file: File) => Promise<URL | string>;
+    /** Swap the tooltip implementation. Defaults to a native, zero-dependency one. */
+    tooltipProvider?: TooltipProvider;
+}
+interface OpenInModalOptions {
+    /** Class names added to the inner `.modal` element. */
+    classNames?: readonly string[];
+    /** Class names added to the outer `.dl-modal` wrapper. */
+    wrapperClassNames?: readonly string[];
+}
+
+/**
+ * Per-form unique DOM ids.
+ *
+ * v1 gave checkboxes ids like `field-0`, which collided between any two forms on
+ * the page — and always collided between a parent form and its array sub-form.
+ * Scoping the counter per form makes `label[for]` reliable, which is what the
+ * accessibility work builds on.
+ */
+declare class IdGenerator {
+    private readonly prefix;
+    private counter;
+    constructor(prefix?: string);
+    /** A unique id, e.g. `dlf3-field-2`. */
+    next(kind?: string): string;
+    /** A stable id derived from a name, e.g. `dlf3-control-email`. */
+    for(kind: string, name: string): string;
+}
+
+/**
+ * Owns the tooltip markers of one form.
+ *
+ * v1 looked markers up with `document.querySelector('#dl-form-field-wrapper-for-…')`,
+ * so two forms with a same-named field fought over each other's tooltips. This
+ * keeps its own registry, keyed by field name.
+ */
+declare class TooltipController {
+    private readonly markers;
+    private readonly provider;
+    constructor(provider?: TooltipProvider);
+    /**
+     * Create the `<span class="dl-tooltip">?</span>` marker for a field.
+     *
+     * Registered by field name so `setTooltip(name, …)` can find it later. The
+     * `data-tippy-content` attribute is retained from v1 as the content store.
+     */
+    createMarker(content: TextOrHtml): HTMLElement;
+    /** Associate a marker with a field name. Called by the form after mounting. */
+    register(fieldName: string, marker: HTMLElement | undefined): void;
+    /**
+     * Replace a field's tooltip text, icon and state class.
+     *
+     * A field without a tooltip is a silent no-op, matching v1.
+     */
+    set(fieldName: string, text: string, icon?: string, className?: string): void;
+    setSuccess(fieldName: string, text: string): void;
+    setWarning(fieldName: string, text: string): void;
+    setError(fieldName: string, text: string): void;
+    setLoading(fieldName: string, text: string): void;
+    /** Apply a `{ level, text }` message from an options loader. */
+    setMessage(fieldName: string, level: 'info' | 'warning' | 'error', text: string): void;
+    /** Restore a field's original tooltip text and `?` icon. */
+    reset(fieldName: string): void;
+    resetAll(fieldNames: Iterable<string>): void;
+    destroy(): void;
+}
+
+/**
+ * Tracks the form's in-flight async work.
+ *
+ * v1 pushed every promise onto a `this.allPromises` array that was never
+ * cleared, so each `Promise.allSettled(allPromises)` re-awaited the entire
+ * history of the form and the array grew without bound. This tracks only what
+ * is actually pending, and hands out generation tokens so a slow async result
+ * from an earlier keystroke cannot overwrite a newer one.
+ */
+declare class UpdateScheduler {
+    private pending;
+    private generations;
+    /** Register async work and drop it from the set once it settles. */
+    track<T>(work: Promise<T>): Promise<T>;
+    /** Number of currently in-flight operations. Test/diagnostics only. */
+    get pendingCount(): number;
+    /**
+     * Resolve once nothing is in flight.
+     *
+     * Loops because settling one batch may schedule another (an options load
+     * whose completion triggers a dependent field's reload).
+     */
+    whenSettled(): Promise<void>;
+    /**
+     * Claim the next generation for `key` and return a predicate that reports
+     * whether that claim is still the newest.
+     *
+     * ```ts
+     * const isCurrent = scheduler.claim(`options:${field.name}`);
+     * const values = await load();
+     * if (!isCurrent()) return; // a newer load superseded this one
+     * ```
+     */
+    claim(key: string): () => boolean;
+    /** Invalidate every outstanding claim and forget all pending work. */
+    reset(): void;
+}
+
+/**
+ * The slice of the owning form a field is allowed to see.
+ *
+ * Fields depend on this narrow interface rather than on `DeclarativeForm`
+ * itself, which keeps the dependency one-directional and makes fields testable
+ * against a stub.
+ */
+interface FormContext {
+    readonly ids: IdGenerator;
+    readonly tooltips: TooltipController;
+    readonly scheduler: UpdateScheduler;
+    /** Values of the enclosing form, when this form is nested. */
+    readonly parentData: FormValues | undefined;
+    /** Values of every form on the modal stack, outermost first. */
+    readonly stackData: readonly FormValues[];
+    /** True while this form is an "edit existing array entry" dialog. */
+    readonly isEditingArrayEntry: boolean;
+    /** Build the context object passed to a descriptor callback. */
+    contextFor(descriptor: FieldDescriptor): FieldContext;
+    /** Re-run the update cycle because `source` changed. */
+    requestUpdate(source: FieldHandle | undefined, force?: boolean): void;
+    /** Persist a picked file, returning the URL to store as the value. */
+    persistFile(file: File): Promise<string>;
+    /**
+     * Build a nested form that knows this form as its parent.
+     *
+     * Lets `ArrayField` open entry dialogs without importing `DeclarativeForm`,
+     * keeping the field layer free of a cycle back into the core.
+     */
+    createSubForm(options: SubFormOptions): SubForm;
+}
+interface SubFormOptions {
+    fields: readonly FieldDescriptor[];
+    classNames?: readonly string[];
+    buttons: ButtonMap;
+    /** Mark the dialog as editing an existing array entry. */
+    isEditingArrayEntry?: boolean;
+}
+/** The slice of a nested form its opener needs. */
+interface SubForm {
+    openInModal(): HTMLElement;
+    getValues(): FormValues;
+}
+
+/**
+ * The imperative handle consumers get from `form.field(name)`.
+ *
+ * Replaces v1's `descriptor.domElement`, which the library wrote back onto the
+ * caller's own object.
+ */
+interface FieldHandle {
+    readonly name: string;
+    /** The control element — an `<input>`, `<textarea>`, `<dl-select>`, … */
+    readonly element: HTMLElement;
+    /** The `.dl-form-field-wrapper` containing label, tooltip and control. */
+    readonly wrapper: HTMLElement;
+    getValue(): unknown;
+    setValue(value: unknown): void;
+    focus(): void;
+    /** Show a loading state, where the field kind supports one. */
+    setLoading(loading: boolean): void;
+}
+/**
+ * Base class for every field kind.
+ *
+ * Subclasses implement {@link createControl} plus the value accessors; the base
+ * class owns the wrapper, label, tooltip marker and active state — i.e. all the
+ * parts of the frozen DOM contract that are the same for every kind.
+ */
+declare abstract class Field<D extends BaseFieldDescriptor = FieldDescriptor> implements FieldHandle {
+    readonly descriptor: D;
+    protected readonly context: FormContext;
+    readonly wrapper: HTMLElement;
+    protected label: HTMLLabelElement | undefined;
+    /** The `.dl-tooltip` marker, when this field declares a tooltip. */
+    tooltipMarker: HTMLElement | undefined;
+    private control;
+    private active;
+    constructor(descriptor: D, context: FormContext);
+    /**
+     * Build the control and the surrounding label/tooltip.
+     *
+     * Deliberately separate from the constructor: subclass field initializers run
+     * *after* `super()` under ES2022 class-field semantics, so anything
+     * `createControl` assigned would be reset to `undefined` if it ran from the
+     * base constructor. {@link FieldRegistry} calls this immediately after
+     * construction.
+     */
+    build(): this;
+    /** The control element — an `<input>`, `<textarea>`, `<dl-select>`, … */
+    get element(): HTMLElement;
+    get name(): string;
+    /** Extra class the kind contributes to its wrapper, e.g. `dl-select-wrapper`. */
+    protected get wrapperExtraClass(): string | undefined;
+    /**
+     * Whether this kind holds a value at all.
+     *
+     * `message` fields are presentational and stay out of `getValues()`.
+     */
+    get contributesValue(): boolean;
+    /** Build the control element. Called once, from {@link build}. */
+    protected abstract createControl(): HTMLElement;
+    abstract getValue(): unknown;
+    abstract setValue(value: unknown): void;
+    focus(): void;
+    setLoading(_loading: boolean): void;
+    /** Ask the owning form to recompute values and re-run the update cycle. */
+    protected requestUpdate(force?: boolean): void;
+    /** Resolve a value that may have been given as a function of the form context. */
+    protected resolve<T>(value: Reactive<T> | undefined): T | undefined;
+    isActive(): boolean;
+    setActive(active: boolean): void;
+    /** Show or hide the field because of the currently selected tab. */
+    setInTab(inTab: boolean): void;
+    /** Tabs this field currently belongs to. */
+    tabs(): string[];
+    /**
+     * Apply the default value. Awaited during form initialisation.
+     *
+     * A `defaultValue` function may return a promise, so the result is always
+     * resolved before being applied.
+     */
+    applyDefaultValue(): Promise<void>;
+    /**
+     * Hook for setup that cannot happen in {@link build} — loading select
+     * options, or a first render that needs the form context. May be synchronous.
+     */
+    initialize(): void | Promise<void>;
+    /**
+     * Called on every form update, after values have settled.
+     *
+     * @param triggerName name of the field whose input started this update
+     */
+    onFormUpdate(_ctx: FormChangeContext, _triggerName: string | undefined): void;
+    destroy(): void;
+    private applyTabClasses;
+    /**
+     * Tab classes are stamped on at construction time, before the form has any
+     * values, so only a statically declared `tab` can contribute one.
+     */
+    private tabsFromStaticDescriptor;
+    private createLabel;
+    /**
+     * The id `label[for]` should target.
+     *
+     * Defaults to giving the control element an id; kinds whose control is a
+     * wrapper (checkbox, cards, file) override this to point at the real input.
+     */
+    protected controlIdForLabel(): string;
+    private createTooltipMarker;
+    /** Convenience for subclasses that render simple text content. */
+    protected setContent: typeof setContent;
+}
+
+/** Constructs a field from its descriptor. */
+type FieldConstructor = new (descriptor: never, context: FormContext) => Field<never>;
+/**
+ * Maps a descriptor's `kind` to the class that implements it.
+ *
+ * This replaces v1's ten-branch `if/else`, and makes the set of field kinds
+ * extensible: register your own class and it becomes usable in any descriptor.
+ */
+declare class FieldRegistry {
+    private readonly kinds;
+    constructor(entries?: Iterable<[string, FieldConstructor]>);
+    register(kind: string, ctor: FieldConstructor): this;
+    has(kind: string): boolean;
+    /** A copy, so callers can add kinds without mutating the shared default. */
+    clone(): FieldRegistry;
+    create(descriptor: FieldDescriptor, context: FormContext): Field;
+}
+/** The built-in field kinds. */
+declare const defaultFieldRegistry: FieldRegistry;
+
+type InputSubscriber = (values: FormValues) => void;
+/**
+ * Change detection and input subscribers for one form.
+ *
+ * Tracks two baselines — one including the active tab and one excluding it — so
+ * that switching tabs can be treated as a change or not depending on the caller.
+ */
+declare class FormModel {
+    private last;
+    private lastWithoutTab;
+    private readonly subscribers;
+    /**
+     * Report whether `values` differ from the last seen snapshot, and adopt it as
+     * the new baseline.
+     *
+     * @param includeTab compare `activeTab` as well as the field values
+     */
+    hasChanged(values: FormValues, includeTab?: boolean): boolean;
+    subscribe(subscriber: InputSubscriber): () => void;
+    notify(values: FormValues): void;
+    /** Forget the baseline so the next comparison reports a change. */
+    reset(): void;
+}
+
+/** What the stack needs from a form on it. */
+interface StackableDialog {
+    getValues(): FormValues;
+    hide(): void;
+    show(): void;
+    /** Re-apply the active tab after being revealed again. */
+    refreshTabs(): void;
+    /** Handle Esc. No-op when the dialog is not dismissable. */
+    requestCancel(): void;
+    /** Handle Enter. Only called when the dialog has exactly one button. */
+    requestConfirm(event: KeyboardEvent): void;
+    /** Number of buttons in the lower bar. */
+    readonly buttonCount: number;
+}
+/**
+ * The stack of open modal dialogs.
+ *
+ * v1 kept this in a module-level `var` and registered its `keydown` handler as
+ * an import side effect, which ran even in Node and could not be torn down.
+ * Here the listener is attached when the first dialog opens and removed when
+ * the last one closes, so importing the library does nothing observable.
+ */
+declare class ModalStack {
+    private readonly dialogs;
+    private listening;
+    get size(): number;
+    /** Values of every dialog on the stack, outermost first. */
+    values(): FormValues[];
+    /** The dialog currently on top, if any. */
+    get top(): StackableDialog | undefined;
+    push(dialog: StackableDialog): void;
+    /** Remove a dialog and reveal whatever it was covering. */
+    remove(dialog: StackableDialog): void;
+    contains(dialog: StackableDialog): boolean;
+    private readonly onKeyDown;
+    private startListening;
+    private stopListening;
+}
+/** The stack shared by all forms that do not opt into their own. */
+declare const globalModalStack: ModalStack;
+
+/** Options only used when a form is created as a child of another. */
+interface InternalOptions {
+    parent?: DeclarativeForm;
+    stack?: ModalStack;
+    registry?: FieldRegistry;
+    isEditingArrayEntry?: boolean;
+}
+/**
+ * A declarative form dialog.
+ *
+ * ```ts
+ * const form = new DeclarativeForm({
+ *   fields: [
+ *     { name: 'title', displayName: 'Title' },
+ *     { name: 'lang', kind: 'select', displayName: 'Language',
+ *       options: [{ value: 'en', label: 'English' }] },
+ *   ],
+ *   onConfirm: (values) => console.log(values),
+ *   onCancel: () => {},
+ * });
+ *
+ * form.openInModal();
+ * ```
+ */
+declare class DeclarativeForm implements SubForm, StackableDialog {
+    /** The `.dl-form` wrapper containing the `<form>`. */
+    readonly dom: HTMLElement;
+    /** The `<form>` element the fields are rendered into. */
+    readonly formElement: HTMLFormElement;
+    private readonly options;
+    private readonly registry;
+    private readonly stack;
+    private readonly parent;
+    private readonly fieldList;
+    private readonly fieldsByName;
+    private readonly model;
+    private readonly scheduler;
+    private readonly ids;
+    private readonly tooltips;
+    private readonly tabBar;
+    private readonly buttonBar;
+    private view;
+    private readonly editingArrayEntry;
+    private embedded;
+    private ready;
+    constructor(options: DeclarativeFormOptions, internal?: InternalOptions);
+    private resolveButtons;
+    private buildFields;
+    private initialize;
+    /** Resolves once initial options and default values have been applied. */
+    whenReady(): Promise<void>;
+    private createFieldContext;
+    private contextFor;
+    private createSubForm;
+    private persistFile;
+    /**
+     * Current values, keyed by field name.
+     *
+     * Inactive fields (`isActive` returned false) are omitted. The active tab is
+     * always included under `activeTab`.
+     */
+    getValues(): FormValues;
+    /** Imperative handle for a field, or `undefined` if there is no such field. */
+    field(name: string): FieldHandle | undefined;
+    /** Every field handle, in declaration order. */
+    get fields(): readonly FieldHandle[];
+    /** Notified whenever the form's values change. Returns an unsubscribe function. */
+    subscribeOnInput(subscriber: InputSubscriber): () => void;
+    /**
+     * Recompute derived state: field visibility, tabs, reactive content and
+     * button predicates.
+     *
+     * @param source the field whose input triggered this update
+     * @param force run even when nothing changed
+     * @param includeTab treat a tab switch as a change
+     */
+    update(source?: FieldHandle, force?: boolean, includeTab?: boolean): Promise<void>;
+    private buttonContext;
+    /** Recompute every `computed` field. Runs before a button action fires. */
+    updateComputedFields(): Promise<void>;
+    /** Tabs in declaration order, keeping only those with at least one active field. */
+    private renderTabs;
+    /**
+     * Switch tabs.
+     *
+     * Called with no argument, it re-applies the current tab — useful after a
+     * nested dialog closes and the fields underneath need re-syncing.
+     */
+    setActiveTab(tab?: string): void;
+    private applyActiveTab;
+    /** Re-apply the active tab. Called by the stack when this dialog is revealed. */
+    refreshTabs(): void;
+    /**
+     * Open the form as a modal dialog.
+     *
+     * Returns the outer `.dl-modal` element.
+     */
+    openInModal(options?: OpenInModalOptions): HTMLElement;
+    /** Render the form inline, inside `host`, instead of as a floating dialog. */
+    appendInElement(host: HTMLElement, options?: OpenInModalOptions): HTMLElement;
+    private ensureView;
+    /** The outer `.dl-modal` element, once the form has been displayed. */
+    get modalElement(): HTMLElement | undefined;
+    hide(): void;
+    show(): void;
+    /** The form's HTML, for tests and snapshots. */
+    getHTML(): string;
+    get buttonCount(): number;
+    /**
+     * Run the confirm action and close.
+     *
+     * @param action defaults to the form's `onConfirm`
+     */
+    close(action?: ButtonDescriptor['action']): Promise<void>;
+    /** Dismiss the dialog. A no-op when the form has no `onCancel`. */
+    cancel(): void;
+    /** Close without running any callback. */
+    remove(): void;
+    /** Release tooltips and listeners. Call when discarding an embedded form. */
+    destroy(): void;
+    private teardownView;
+    requestCancel(): void;
+    /**
+     * Enter pressed while this dialog is on top.
+     *
+     * Inside a textarea that allows newlines, Enter inserts one. Otherwise it
+     * confirms — unless the confirm button is disabled.
+     */
+    requestConfirm(event: KeyboardEvent): void;
+    setTooltip(fieldName: string, text: string, icon?: string, className?: string): void;
+    setTooltipSuccess(fieldName: string, text: string): void;
+    setTooltipWarning(fieldName: string, text: string): void;
+    setTooltipError(fieldName: string, text: string): void;
+    setTooltipLoading(fieldName: string, text: string): void;
+    resetTooltip(fieldName: string): void;
+    resetTooltips(fieldNames: Iterable<string>): void;
+}
+
+/**
+ * A repeating list of sub-records, each edited in its own nested dialog.
+ *
+ * v1 implemented this by overwriting the caller's `field.render` with a closure
+ * that also owned the suggestion checkboxes and the add/edit/delete buttons.
+ * Here the entries, the accepted suggestions and the DOM are all state on the
+ * field, and the entry dialogs are built through `context.createSubForm`.
+ */
+declare class ArrayField extends Field<ArrayFieldDescriptor> {
+    private entries;
+    /** Suggestions the user ticked, kept with their index so they can be un-ticked. */
+    private acceptedSuggestions;
+    protected createControl(): HTMLElement;
+    initialize(): void;
+    getValue(): FormValues[];
+    setValue(value: unknown): void;
+    onFormUpdate(_ctx: FormChangeContext): void;
+    private render;
+    private renderSuggestions;
+    private renderEntry;
+    private renderAddButton;
+    /** Default summary: every non-empty string value, comma separated. */
+    private entrySummary;
+    /** Open the add dialog, or the edit dialog when `index` is given. */
+    private openEntryDialog;
+    /** Seed each field with the entry's current value, then apply `mapFieldsOnEdit`. */
+    private editFields;
+    private validateEntry;
+    private notifyChange;
+}
+
+/**
+ * A row of clickable option cards — a richer alternative to a select when there
+ * are few options and each needs a description or an icon.
+ *
+ * v1 called this `detailedOptions`.
+ */
+declare class CardsField extends Field<CardsFieldDescriptor> {
+    private value;
+    protected createControl(): HTMLElement;
+    getValue(): string;
+    setValue(value: unknown): void;
+    private select;
+}
+
+/**
+ * A checkbox with a caption.
+ *
+ * The control is a `<span class="check">` wrapping the input and its caption —
+ * part of the frozen DOM contract, since `.dl-form form .check input` and
+ * `.check label` are styled by the default stylesheet and by consumers.
+ */
+declare class CheckboxField extends Field<CheckboxFieldDescriptor> {
+    private input;
+    protected createControl(): HTMLElement;
+    /** The outer `displayName` label points at the real input, not the wrapper. */
+    protected controlIdForLabel(): string;
+    getValue(): boolean;
+    setValue(value: unknown): void;
+}
+
+/**
+ * A value derived from the rest of the form.
+ *
+ * Rendered as a hidden input (which adds `.dl-form-hidden-field` to the wrapper)
+ * and recomputed before the dialog is confirmed. The computed value lives on the
+ * field rather than in the DOM, so it is not limited to strings.
+ */
+declare class ComputedField extends Field<ComputedFieldDescriptor> {
+    private value;
+    protected createControl(): HTMLElement;
+    getValue(): unknown;
+    setValue(value: unknown): void;
+    /** Recompute. Awaited by `updateComputedFields()` before a button action runs. */
+    recompute(): Promise<void>;
+}
+
+/**
+ * An escape hatch: you render the content, the form manages the value.
+ *
+ * `render` is called on mount and again on every form update. v1 injected
+ * `setValue` and `onChange` onto the DOM element; both now arrive on the render
+ * context instead, so the element stays a plain `HTMLElement`.
+ */
+declare class CustomField extends Field<CustomFieldDescriptor> {
+    private value;
+    protected createControl(): HTMLElement;
+    getValue(): unknown;
+    setValue(value: unknown): void;
+    initialize(): void;
+    onFormUpdate(_ctx: FormChangeContext): void;
+    private render;
+    private renderContext;
+}
+
+/**
+ * A file picker with an image preview.
+ *
+ * The field's value is the URL returned by the form's `persistFile` hook, not
+ * the `File` itself — the dialog stores a reference, the app decides where the
+ * bytes go.
+ */
+declare class FileField extends Field<FileFieldDescriptor> {
+    private input;
+    private preview;
+    private url;
+    protected createControl(): HTMLElement;
+    protected controlIdForLabel(): string;
+    getValue(): string;
+    setValue(value: unknown): void;
+    setLoading(loading: boolean): void;
+    private handlePick;
+    /**
+     * Surface an upload failure.
+     *
+     * Dispatches a cancelable `dl-error` event on the field so the app can show
+     * its own message; if nothing calls `preventDefault()`, the error is logged
+     * rather than vanishing. Throwing here would only produce an unhandled
+     * rejection, since this runs from an event handler.
+     */
+    private reportError;
+    private clearPreview;
+    private renderPreview;
+}
+
+/**
+ * A presentational paragraph. Holds no value and never appears in `getValues()`.
+ */
+declare class MessageField extends Field<MessageFieldDescriptor> {
+    protected createControl(): HTMLElement;
+    get contributesValue(): boolean;
+    getValue(): undefined;
+    setValue(): void;
+    onFormUpdate(_ctx: FormChangeContext): void;
+}
+
+/** A `<dl-select>` combobox, single or multiple. */
+declare class SelectField extends Field<SelectFieldDescriptor> {
+    private select;
+    protected get wrapperExtraClass(): string;
+    protected createControl(): HTMLElement;
+    initialize(): Promise<void>;
+    getValue(): string | string[];
+    setValue(value: unknown): void;
+    setLoading(loading: boolean): void;
+    onFormUpdate(_ctx: FormChangeContext, triggerName: string | undefined): void;
+    /**
+     * Populate the options.
+     *
+     * Each load claims a generation token; if a newer load starts while this one
+     * is still in flight, the stale result is dropped instead of clobbering the
+     * fresher options. v1 had no such guard, so a slow response from an earlier
+     * keystroke could repopulate the select with outdated values.
+     */
+    private loadOptions;
+    private createOption;
+    private reportOptionsError;
+}
+
+/** A multi-line `<textarea>`. */
+declare class TextAreaField extends Field<TextAreaFieldDescriptor> {
+    private textarea;
+    protected createControl(): HTMLElement;
+    /** Whether Enter inserts a newline rather than confirming the dialog. */
+    get allowsNewlines(): boolean;
+    getValue(): string;
+    setValue(value: unknown): void;
+    onFormUpdate(_ctx: FormChangeContext): void;
+}
+
+/** The fallback kind: a single-line `<input>`. */
+declare class TextField extends Field<TextFieldDescriptor> {
+    private input;
+    protected createControl(): HTMLElement;
+    getValue(): string;
+    setValue(value: unknown): void;
+    onFormUpdate(_ctx: FormChangeContext): void;
+}
+
+/**
+ * Base class for the custom elements.
+ *
+ * `class X extends HTMLElement` is evaluated as soon as the module loads, which
+ * throws outright in Node — breaking any server-rendered or prerendered app
+ * that so much as imports the package. Falling back to an empty class keeps the
+ * module importable; the stand-in is never instantiated, because custom
+ * elements are only registered when `customElements` exists.
+ */
+declare const CustomElementBase: typeof HTMLElement;
+/**
+ * An option inside a {@link DlSelect}.
+ *
+ * v1 never registered this element, leaving it an `HTMLUnknownElement`.
+ * Registering it gives it a stable prototype and somewhere to hang the option
+ * semantics the accessibility work needs.
+ */
+declare class DlOption extends CustomElementBase {
+    /** The value this option contributes, falling back to its text. */
+    get optionValue(): string;
+    /** Text shown once selected, which may differ from the option's own label. */
+    get displayText(): string;
+}
+/**
+ * A filterable combobox that supports async options and multi-select.
+ *
+ * Deliberately light-DOM: consumers style its internals (`.input-wrapper`,
+ * `.options-wrapper`, `dl-option`) and the options popup is reparented to
+ * `document.body` while open so it can escape a scrolling container.
+ */
+declare class DlSelect extends CustomElementBase {
+    readonly optionsWrapper: HTMLDivElement;
+    readonly inputWrapper: HTMLSpanElement;
+    readonly noMatchesHint: HTMLSpanElement;
+    readonly selectedContainer: HTMLSpanElement;
+    readonly inputField: HTMLInputElement;
+    readonly arrow: SVGSVGElement;
+    multiple: boolean;
+    isLoading: boolean;
+    private initialized;
+    private loadingTimeouts;
+    private loadingStartedAt;
+    private pendingValue;
+    private selectedOption;
+    private focusedOption;
+    private repositionListener;
+    private scrollTargets;
+    constructor();
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    /** Move any author-provided `<dl-option>` children into the popup. */
+    private mount;
+    private adoptOption;
+    addOption(option: DlOption | HTMLElement): void;
+    removeAllOptions(): void;
+    /** All options currently in the popup. */
+    get options(): DlOption[];
+    /**
+     * Enter the loading state.
+     *
+     * The skeleton only appears after a short delay, so options that resolve
+     * quickly never flash one. Repeated calls are safe.
+     */
+    setLoadingStatus(): void;
+    unsetLoadingStatus(): void;
+    getValue(): string | string[] | undefined;
+    setValue(value: unknown): void;
+    /**
+     * Find an option by its `value` attribute, falling back to its text.
+     *
+     * v1 concatenated the value straight into an attribute selector, which threw
+     * on any value containing a quote or a backslash.
+     */
+    private findOption;
+    private selectOption;
+    private deselectOption;
+    /** Mark every option carrying this value, since duplicates are allowed. */
+    private markSelected;
+    private createTag;
+    private tagFor;
+    private emitChange;
+    filterOptions(query: string): void;
+    private visibleOptions;
+    private clearFocusedOption;
+    private focusOption;
+    private step;
+    private readonly onKeyDown;
+    private get placeholderText();
+    private updatePlaceholder;
+    /** Open the popup. Named `open` because `focus()` is `HTMLElement`'s. */
+    open(): void;
+    close(): void;
+    private reposition;
+    private attachRepositionListeners;
+    private detachRepositionListeners;
+}
+/**
+ * Register `<dl-select>` and `<dl-option>`.
+ *
+ * Idempotent, and a no-op outside a browser. Called automatically whenever a
+ * form builds a select field.
+ */
+declare function defineDlSelect(): void;
+declare global {
+    interface HTMLElementTagNameMap {
+        'dl-select': DlSelect;
+        'dl-option': DlOption;
+    }
+}
+
+/**
+ * Structural styles for `<dl-select>`.
+ *
+ * These live in JS rather than in the shipped stylesheet because the component
+ * does not work without them — the options popup is absolutely positioned and
+ * toggled through these rules. Everything here is themable through the `--dl-*`
+ * custom properties, and the form/modal chrome ships separately as
+ * `declarative-forms/styles.css`.
+ *
+ * v1 appended this on `window.load` as an import side effect, which broke SSR
+ * and leaked between tests. It is now injected lazily, the first time a
+ * `<dl-select>` is actually connected to a document.
+ */
+declare const DL_SELECT_STYLES = "\n@keyframes dl-placeholder-shimmer {\n    0% { background-position: -468px 0 }\n    100% { background-position: 468px 0 }\n}\n\ndl-select {\n    display: block;\n    position: relative;\n    font-weight: 300;\n    font-family: var(--dl-font-family, 'Rubik');\n    --dl-select-input-width: 370px;\n}\n\ndl-select .input-wrapper {\n    display: inline-block;\n    border-width: 2px;\n    border-style: solid;\n    border-color: var(--dl-line-color, #ddd);\n    background-color: var(--dl-options-background, #fff);\n    color: var(--dl-options-text-color, #545454);\n    border-radius: 4px;\n}\n\ndl-select.dl-focused .input-wrapper {\n    border-color: var(--dl-focused-line-color, #bbb);\n}\n\ndl-select.dl-focused .input-wrapper svg {\n    border-left: 1px solid var(--dl-focused-line-color, #bbb);\n    fill: var(--dl-focused-line-color, #bbb);\n}\n\ndl-select .input-wrapper input {\n    width: var(--dl-select-input-width);\n    color: var(--dl-options-text-color, #545454);\n    outline-width: 0;\n    margin-top: 2px;\n    padding: 6px;\n    font-size: var(--dl-font-size, 0.9em);\n    font-family: var(--dl-font-family, 'Rubik');\n    font-weight: 300;\n    border: 0;\n    border-radius: 4px;\n    float: left;\n    cursor: pointer;\n    box-sizing: content-box;\n    background: transparent;\n}\n\ndl-select .input-wrapper input::placeholder {\n    color: var(--dl-options-inactive-text-color, #545454);\n}\n\ndl-select .input-wrapper svg {\n    width: 20px;\n    height: 20px;\n    margin-top: var(--dl-drop-down-icon-margin-top, 5px);\n    margin-right: 4px;\n    padding-left: 4px;\n    fill: var(--dl-line-color, #ddd);\n    float: right;\n    border-left: 1px solid var(--dl-line-color, #ddd);\n    cursor: pointer;\n}\n\n.options-wrapper {\n    position: absolute;\n    left: 0;\n    top: 20px;\n    font-size: var(--dl-font-size, 0.9em);\n    width: 100%;\n    max-height: 230px;\n    overflow-y: auto;\n    overflow-x: hidden;\n    box-shadow: 0 0 10px -2px rgba(0, 0, 0, 0.4);\n    z-index: 100;\n    background-color: var(--dl-options-background, #fff);\n    font-family: var(--dl-font-family, 'Rubik');\n    border-top: 1px solid var(--dl-focused-line-color, #bbb);\n    border-bottom: 1px solid var(--dl-focused-line-color, #bbb);\n    border-radius: 4px;\n}\n\n.options-wrapper dl-option {\n    display: block;\n    border-left: 1px solid var(--dl-focused-line-color, #bbb);\n    border-right: 1px solid var(--dl-focused-line-color, #bbb);\n    cursor: pointer;\n    padding-top: var(--dl-options-padding-top, 5px);\n    padding-right: var(--dl-options-padding-right, 5px);\n    padding-bottom: var(--dl-options-padding-bottom, 5px);\n    padding-left: var(--dl-options-padding-left, 5px);\n    color: var(--dl-options-text-color, #545454);\n    background-color: var(--dl-options-background, #fff);\n}\n\n.options-wrapper dl-option[selected=\"true\"] {\n    opacity: 0.5;\n    cursor: not-allowed;\n}\n\n.options-wrapper dl-option:hover,\n.options-wrapper dl-option.dl-focused {\n    background-color: var(--dl-options-option-hover-color, rgba(224, 240, 227, 0.4));\n}\n\n.options-wrapper .noMatchesHint {\n    border-left: 1px solid var(--dl-focused-line-color, #bbb);\n    border-right: 1px solid var(--dl-focused-line-color, #bbb);\n    padding: 5px;\n    font-style: italic;\n    color: var(--dl-options-text-color, #545454);\n}\n\ndl-select .dl-option-tag {\n    float: right;\n    border: 1px solid #888;\n    font-size: 0.8em;\n    padding: 2px;\n    font-family: 'Source Code Pro', monospace;\n    border-radius: 2px;\n    margin-top: -1px;\n}\n\ndl-select .dl-option-tag:last-child {\n    margin-right: 10px;\n}\n\n.dl-select-no-options-available svg path { display: none; }\n.dl-select-no-options-available svg { border-left: none !important; }\n\n.dl-select-loading svg,\n.dl-select-no-options-available svg,\n.dl-select-loading input,\n.dl-select-no-options-available input {\n    pointer-events: none;\n}\n\n.dl-select-loading .input-wrapper {\n    animation: dl-placeholder-shimmer 1.25s linear infinite forwards;\n    background: linear-gradient(\n        to right,\n        var(--dl-select-loading-col1, #eee) 10%,\n        var(--dl-select-loading-col2, #ddd) 18%,\n        var(--dl-select-loading-col1, #eee) 33%\n    );\n    background-size: 800px 104px;\n    position: relative;\n    width: 412px;\n}\n\n.dl-select-loading input { opacity: 0; }\n\n.dl-field-one-third input,\n.dl-field-two-third input {\n    --dl-select-input-width: 127px;\n}\n\nbody.dark-theme dl-select {\n    --dl-select-loading-col1: #282727;\n    --dl-select-loading-col2: #505656;\n}\n";
+/**
+ * Inject the `<dl-select>` styles once per document.
+ *
+ * Safe to call repeatedly and safe to call before `document.body` exists.
+ */
+declare function injectStyles(): void;
+
+interface ButtonBarCallbacks {
+    /** Resolve once all pending form work has settled. */
+    whenSettled(): Promise<void>;
+    /** Recompute `computed` fields before an action runs. */
+    updateComputedFields(): Promise<void>;
+    getValues(): Record<string, unknown>;
+    /** Run the action and close the dialog. */
+    closeWith(action: ButtonDescriptor['action']): Promise<void>;
+}
+/**
+ * The dialog's lower bar.
+ *
+ * Buttons are real `<button type="button">` elements rather than v1's
+ * `<div class="btn">`. They keep the `.btn` class, so every existing stylesheet
+ * still matches, and the shipped CSS normalises the font so the change is not
+ * visible — but they are now focusable and operable from the keyboard.
+ */
+declare class ButtonBar {
+    private readonly config;
+    private readonly callbacks;
+    readonly element: HTMLElement;
+    private readonly buttons;
+    constructor(config: ButtonMap, callbacks: ButtonBarCallbacks);
+    get count(): number;
+    /** The first button — the one Enter activates. */
+    get primary(): HTMLElement | undefined;
+    /** Whether the primary button is currently disabled. */
+    get primaryDisabled(): boolean;
+    private createButton;
+    private activate;
+    /**
+     * Re-evaluate every `isActive` / `isVisible` predicate.
+     *
+     * Buttons without an `id` are skipped, matching v1 — an id is what opts a
+     * button into state management.
+     */
+    refresh(ctx: ButtonContext): Promise<void>;
+    /**
+     * Apply a predicate result.
+     *
+     * A synchronous predicate is applied immediately. v1 always set the button
+     * disabled first and cleared it in a `.then()`, which made every button flash
+     * disabled on every keystroke and let a well-timed click be dropped.
+     */
+    private applyPredicate;
+    /** The configured buttons, for callers that want to invoke an action directly. */
+    get descriptors(): ButtonMap;
+}
+
+/**
+ * The dialog's tab strip.
+ *
+ * v1 resolved tabs with `document.querySelector('.dl-tab-btn.active')`, so two
+ * open forms fought over each other's active tab. This owns its buttons and
+ * never queries the document.
+ *
+ * The rendered shape is part of the frozen contract: `.dl-tab-btn` elements are
+ * direct, clickable siblings inside `.tabWrapper`, each carrying the tab label
+ * with whitespace stripped as a class (`'Find Citation'` → `.FindCitation`), and
+ * a `seen` class once visited.
+ */
+declare class TabBar {
+    private readonly onSelect;
+    readonly element: HTMLElement;
+    private buttons;
+    private seen;
+    private active;
+    constructor(onSelect: (tab: string) => void);
+    get activeTab(): string | undefined;
+    /** Rebuild the strip from the tabs that currently have at least one visible field. */
+    render(tabs: readonly string[]): void;
+    /**
+     * Mark a tab active.
+     *
+     * Selecting a tab that is not currently rendered is a no-op rather than an
+     * error — a tab can disappear when the fields in it all become inactive.
+     */
+    select(tab: string): boolean;
+    get tabs(): string[];
+    get isEmpty(): boolean;
+}
+
+interface ModalViewOptions {
+    tabBar: TabBar;
+    buttonBar: ButtonBar;
+    /** Render a close button. Omit for a dialog that cannot be dismissed. */
+    onCancel?: () => void;
+}
+/**
+ * The modal chrome.
+ *
+ * ```html
+ * <div class="dl-modal">
+ *   <div class="modal">
+ *     <div class="up-bar"><button class="cancelBtn secondary"></button></div>
+ *     <div class="tabWrapper">…</div>
+ *     <div class="modal-content">…the form…</div>
+ *     <div class="low-bar">…buttons…</div>
+ *   </div>
+ * </div>
+ * ```
+ *
+ * Every one of these class names is overridden by at least one consumer, so the
+ * structure is fixed. The upper bar is always present but only carries the
+ * `up-bar` class when the dialog is dismissable — a v1 quirk that consumer CSS
+ * relies on to reserve (or not reserve) the header strip.
+ */
+declare class ModalView {
+    readonly wrapper: HTMLElement;
+    readonly modal: HTMLElement;
+    readonly content: HTMLElement;
+    readonly upBar: HTMLElement;
+    constructor(options: ModalViewOptions);
+    /** Attach to the document body. Used by `openInModal`. */
+    mount(): void;
+    setVisible(visible: boolean): void;
+    hide(): void;
+    show(): void;
+    /**
+     * Record how many dialogs this one was opened on top of.
+     *
+     * A stacked dialog inherits a backdrop that is already on screen: the dialog
+     * below is hidden in the same frame this one appears. Fading this backdrop in
+     * would leave the page uncovered for the length of the animation, so themes
+     * suppress it on the `dl-modal-stacked` class. The depth also goes on the
+     * wrapper as `--dl-stack-depth`, so a theme can show how deep the stack is.
+     */
+    setStackDepth(depth: number): void;
+    /** Mark the dialog as embedded rather than floating. */
+    setEmbedded(): void;
+    addModalClasses(names: readonly string[] | undefined): void;
+    addWrapperClasses(names: readonly string[] | undefined): void;
+    remove(): void;
+}
+
+/**
+ * Zero-dependency tooltip.
+ *
+ * Renders a positioned bubble on hover and on focus, placed to the right of the
+ * trigger and flipped to the left when it would overflow the viewport. Content
+ * is an HTML string because tooltip text has always supported markup; callers
+ * mark it with `html()` at the descriptor level.
+ */
+declare class NativeTooltipProvider implements TooltipProvider {
+    private readonly attachments;
+    attach(element: HTMLElement, content: string): void;
+    detach(element: HTMLElement): void;
+    private show;
+    private hide;
+    private position;
+}
+
+/**
+ * Structural equality for form data snapshots.
+ *
+ * Replaces the `@react-hookz/deep-equal` dependency. Scoped to what form values
+ * can actually be: primitives, plain objects, arrays, `Date`, and `File`/`Blob`
+ * (compared by identity, since their contents are not cheaply comparable).
+ */
+declare function deepEqual(a: unknown, b: unknown): boolean;
+
+export { ArrayField, type ArrayFieldDescriptor, type BaseFieldDescriptor, ButtonBar, type ButtonContext, type ButtonDescriptor, type ButtonMap, CardsField, type CardsFieldDescriptor, CheckboxField, type CheckboxFieldDescriptor, ComputedField, type ComputedFieldDescriptor, CustomField, type CustomFieldDescriptor, DL_SELECT_STYLES, DeclarativeForm, type DeclarativeFormOptions, DlOption, DlSelect, Field, type FieldConstructor, type FieldContext, type FieldDescriptor, type FieldHandle, type FieldKind, type FieldMessage, FieldRegistry, FileField, type FileFieldDescriptor, type FormChangeContext, type FormContext, FormModel, type FormValues, IdGenerator, MessageField, type MessageFieldDescriptor, ModalStack, ModalView, NativeTooltipProvider, type OpenInModalOptions, type OptionsErrorContext, type Reactive, type RenderContext, SafeHtml, SelectField, type SelectFieldDescriptor, type SelectOption, type StackableDialog, type SubForm, type SubFormOptions, TabBar, type TabSpec, TextAreaField, type TextAreaFieldDescriptor, TextField, type TextFieldDescriptor, type TextOrHtml, TooltipController, type TooltipDescriptor, type TooltipProvider, UpdateScheduler, deepEqual, defaultFieldRegistry, defineDlSelect, escapeHtml, globalModalStack, html, injectStyles, isSafeHtml };