declarative-forms 2.0.0-alpha.0

package/dist/index.js

@@ -0,0 +1,2473 @@
+// src/util/html.ts
+var SAFE_HTML = /* @__PURE__ */ Symbol.for("declarative-forms.SafeHtml");
+var SafeHtml = class {
+  constructor(value) {
+    this.value = value;
+  }
+  value;
+  /** Brand used by {@link isSafeHtml} so instances survive duplicated module copies. */
+  [SAFE_HTML] = true;
+  toString() {
+    return this.value;
+  }
+};
+function isSafeHtml(value) {
+  return typeof value === "object" && value !== null && SAFE_HTML in value;
+}
+var ESCAPES = {
+  "&": "&",
+  "<": "&lt;",
+  ">": "&gt;",
+  '"': "&quot;",
+  "'": "&#39;"
+};
+function escapeHtml(value) {
+  return String(value).replace(/[&<>"']/g, (char) => ESCAPES[char]);
+}
+function html(stringsOrRaw, ...values) {
+  if (typeof stringsOrRaw === "string") {
+    return new SafeHtml(stringsOrRaw);
+  }
+  let out = stringsOrRaw[0] ?? "";
+  for (let i = 0; i < values.length; i++) {
+    const value = values[i];
+    out += isSafeHtml(value) ? value.value : escapeHtml(value);
+    out += stringsOrRaw[i + 1] ?? "";
+  }
+  return new SafeHtml(out);
+}
+
+// src/util/dom.ts
+function setContent(el, content) {
+  if (content == null) {
+    el.textContent = "";
+  } else if (isSafeHtml(content)) {
+    el.innerHTML = content.value;
+  } else {
+    el.textContent = content;
+  }
+}
+function contentToString(content) {
+  if (content == null) return "";
+  return isSafeHtml(content) ? content.value : content;
+}
+function createEl(tag, options = {}) {
+  const el = document.createElement(tag);
+  for (const name of options.classNames ?? []) {
+    if (name) el.classList.add(name);
+  }
+  for (const [key, value] of Object.entries(options.attrs ?? {})) {
+    if (value !== void 0) el.setAttribute(key, value);
+  }
+  if (options.content !== void 0) setContent(el, options.content);
+  return el;
+}
+function addClasses(el, classNames) {
+  if (!classNames) return;
+  for (const name of classNames.split(/\s+/)) {
+    if (name) el.classList.add(name);
+  }
+}
+function findByAttribute(root, selector, attribute, value) {
+  return [...root.querySelectorAll(selector)].filter(
+    (el) => el.getAttribute(attribute) === value
+  );
+}
+function tabClassName(tab) {
+  return tab.replace(/\s/g, "");
+}
+
+// src/fields/Field.ts
+var Field = class {
+  constructor(descriptor, context) {
+    this.descriptor = descriptor;
+    this.context = context;
+    this.wrapper = createEl("div", {
+      attrs: { id: `dl-form-field-wrapper-for-${descriptor.name}` },
+      classNames: ["dl-form-field-wrapper"]
+    });
+    this.applyTabClasses();
+  }
+  descriptor;
+  context;
+  wrapper;
+  label;
+  /** The `.dl-tooltip` marker, when this field declares a tooltip. */
+  tooltipMarker;
+  control;
+  active = true;
+  /**
+   * 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() {
+    if (this.control) return this;
+    const element = this.createControl();
+    this.control = element;
+    element.name = this.descriptor.name;
+    element.setAttribute("name", this.descriptor.name);
+    if (this.wrapperExtraClass) this.wrapper.classList.add(this.wrapperExtraClass);
+    addClasses(this.wrapper, this.descriptor.className);
+    this.label = this.createLabel();
+    this.createTooltipMarker();
+    if (element.type === "hidden") {
+      this.wrapper.classList.add("dl-form-hidden-field");
+    }
+    this.wrapper.appendChild(element);
+    return this;
+  }
+  /** The control element — an `<input>`, `<textarea>`, `<dl-select>`, … */
+  get element() {
+    if (!this.control) {
+      throw new Error("declarative-forms: field.build() must run before use.");
+    }
+    return this.control;
+  }
+  get name() {
+    return this.descriptor.name;
+  }
+  /** Extra class the kind contributes to its wrapper, e.g. `dl-select-wrapper`. */
+  get wrapperExtraClass() {
+    return void 0;
+  }
+  /**
+   * Whether this kind holds a value at all.
+   *
+   * `message` fields are presentational and stay out of `getValues()`.
+   */
+  get contributesValue() {
+    return true;
+  }
+  focus() {
+    this.element.focus?.();
+  }
+  setLoading(_loading) {
+  }
+  /** Ask the owning form to recompute values and re-run the update cycle. */
+  requestUpdate(force = false) {
+    this.context.requestUpdate(this, force);
+  }
+  /** Resolve a value that may have been given as a function of the form context. */
+  resolve(value) {
+    if (typeof value === "function") {
+      return value(
+        this.context.contextFor(this.descriptor)
+      );
+    }
+    return value;
+  }
+  isActive() {
+    return this.active;
+  }
+  setActive(active) {
+    this.active = active;
+    this.wrapper.classList.toggle("inactive", !active);
+  }
+  /** Show or hide the field because of the currently selected tab. */
+  setInTab(inTab) {
+    this.wrapper.classList.toggle("notInTab", !inTab);
+  }
+  /** Tabs this field currently belongs to. */
+  tabs() {
+    const spec = this.resolve(this.descriptor.tab);
+    if (!spec) return [];
+    return (Array.isArray(spec) ? spec : [spec]).filter(
+      (tab) => typeof tab === "string" && tab.length > 0
+    );
+  }
+  /**
+   * Apply the default value. Awaited during form initialisation.
+   *
+   * A `defaultValue` function may return a promise, so the result is always
+   * resolved before being applied.
+   */
+  async applyDefaultValue() {
+    if (this.descriptor.defaultValue === void 0) return;
+    const value = await Promise.resolve(
+      this.resolve(this.descriptor.defaultValue)
+    );
+    if (value !== void 0) this.setValue(value);
+  }
+  /**
+   * 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() {
+  }
+  /**
+   * Called on every form update, after values have settled.
+   *
+   * @param triggerName name of the field whose input started this update
+   */
+  onFormUpdate(_ctx, _triggerName) {
+  }
+  destroy() {
+    this.wrapper.remove();
+  }
+  applyTabClasses() {
+    for (const tab of this.tabsFromStaticDescriptor()) {
+      this.wrapper.classList.add(tabClassName(tab));
+    }
+  }
+  /**
+   * Tab classes are stamped on at construction time, before the form has any
+   * values, so only a statically declared `tab` can contribute one.
+   */
+  tabsFromStaticDescriptor() {
+    const spec = this.descriptor.tab;
+    if (!spec || typeof spec === "function") return [];
+    return (Array.isArray(spec) ? spec : [spec]).filter(
+      (tab) => typeof tab === "string" && tab.length > 0
+    );
+  }
+  createLabel() {
+    if (this.descriptor.displayName === void 0) {
+      this.wrapper.classList.add("withoutLabel");
+      return void 0;
+    }
+    const controlId = this.controlIdForLabel();
+    const label = createEl("label", {
+      attrs: { for: controlId },
+      content: this.descriptor.displayName
+    });
+    this.wrapper.appendChild(label);
+    return label;
+  }
+  /**
+   * 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.
+   */
+  controlIdForLabel() {
+    const id = this.context.ids.for("control", this.descriptor.name);
+    if (!this.element.id) this.element.id = id;
+    return this.element.id;
+  }
+  createTooltipMarker() {
+    const tooltip = this.descriptor.tooltip;
+    if (tooltip === void 0) return;
+    const descriptor = typeof tooltip === "object" && tooltip !== null && "text" in tooltip ? tooltip : { text: tooltip, inInput: false };
+    const marker = this.context.tooltips.createMarker(descriptor.text);
+    this.tooltipMarker = marker;
+    if (this.label && !descriptor.inInput) {
+      this.label.appendChild(marker);
+    } else {
+      marker.classList.add("dl-tooltip-in-input");
+      this.element.classList.add("dl-tooltip-inside");
+      this.wrapper.appendChild(marker);
+    }
+  }
+  /** Convenience for subclasses that render simple text content. */
+  setContent = setContent;
+};
+
+// src/fields/ComputedField.ts
+var ComputedField = class extends Field {
+  value = "";
+  createControl() {
+    const input = createEl("input");
+    input.type = "hidden";
+    return input;
+  }
+  getValue() {
+    return this.value;
+  }
+  setValue(value) {
+    this.value = value;
+  }
+  /** Recompute. Awaited by `updateComputedFields()` before a button action runs. */
+  async recompute() {
+    const ctx = this.context.contextFor(this.descriptor);
+    this.value = await this.descriptor.compute(ctx);
+  }
+};
+
+// src/util/value.ts
+function asText(value) {
+  if (value === null || value === void 0) return "";
+  if (typeof value === "string") return value;
+  if (typeof value === "number" || typeof value === "boolean" || typeof value === "bigint") {
+    return String(value);
+  }
+  try {
+    return JSON.stringify(value) ?? "";
+  } catch {
+    return "";
+  }
+}
+
+// src/fields/TextAreaField.ts
+var TextAreaField = class extends Field {
+  textarea;
+  createControl() {
+    const textarea = createEl("textarea");
+    this.textarea = textarea;
+    const placeholder = this.descriptor.placeholder;
+    if (typeof placeholder === "string") textarea.placeholder = placeholder;
+    textarea.oninput = () => this.requestUpdate();
+    textarea.onchange = textarea.oninput;
+    return textarea;
+  }
+  /** Whether Enter inserts a newline rather than confirming the dialog. */
+  get allowsNewlines() {
+    return this.descriptor.allowNewlines === true;
+  }
+  getValue() {
+    return this.textarea.value;
+  }
+  setValue(value) {
+    this.textarea.value = asText(value);
+  }
+  onFormUpdate(_ctx) {
+    if (typeof this.descriptor.placeholder === "function") {
+      this.textarea.placeholder = this.resolve(this.descriptor.placeholder) ?? "";
+    }
+  }
+};
+
+// src/fields/ArrayField.ts
+var ArrayField = class extends Field {
+  entries = [];
+  /** Suggestions the user ticked, kept with their index so they can be un-ticked. */
+  acceptedSuggestions = [];
+  createControl() {
+    return createEl("div", { classNames: ["array-of"] });
+  }
+  initialize() {
+    this.render();
+  }
+  getValue() {
+    const result = [...this.entries];
+    for (const { entry } of this.acceptedSuggestions) {
+      const encoded = JSON.stringify(entry);
+      if (!result.some((existing) => JSON.stringify(existing) === encoded)) {
+        result.push(entry);
+      }
+    }
+    return result;
+  }
+  setValue(value) {
+    this.entries = Array.isArray(value) ? [...value] : [];
+    this.render();
+  }
+  onFormUpdate(_ctx) {
+    this.render();
+  }
+  // ------------------------------------------------------------------ render
+  render() {
+    this.element.replaceChildren();
+    const suggestions = this.resolve(this.descriptor.suggested);
+    if (suggestions && suggestions.length > 0) {
+      this.element.appendChild(this.renderSuggestions(suggestions));
+    }
+    this.entries.forEach((entry, index) => {
+      this.element.appendChild(this.renderEntry(entry, index));
+    });
+    this.element.appendChild(this.renderAddButton());
+  }
+  renderSuggestions(suggestions) {
+    const container = createEl("div", {
+      classNames: ["dl-form-array-suggested-container"]
+    });
+    suggestions.forEach((suggestion, index) => {
+      const id = this.context.ids.for(
+        "suggestion",
+        `${this.descriptor.name}-${String(index)}`
+      );
+      const wrapper = createEl("span", {
+        classNames: ["check", "dl-form-array-of-suggestion"],
+        attrs: { value: "false" }
+      });
+      const checkbox = createEl("input", { attrs: { type: "checkbox", id } });
+      checkbox.checked = this.acceptedSuggestions.some((item) => item.index === index);
+      checkbox.oninput = checkbox.onchange = () => {
+        wrapper.setAttribute("value", String(checkbox.checked));
+        if (checkbox.checked) {
+          this.acceptedSuggestions.push({ entry: suggestion, index });
+        } else {
+          this.acceptedSuggestions = this.acceptedSuggestions.filter(
+            (item) => item.index !== index
+          );
+        }
+        this.requestUpdate();
+      };
+      const label = createEl("label", { attrs: { for: id } });
+      setContent(label, this.entrySummary(suggestion));
+      wrapper.appendChild(checkbox);
+      wrapper.appendChild(label);
+      container.appendChild(wrapper);
+    });
+    return container;
+  }
+  renderEntry(entry, index) {
+    const row = createEl("div", {
+      classNames: ["dl-form-array-of-entry"],
+      attrs: { "data-el-index": String(index) }
+    });
+    const summary = createEl("span");
+    setContent(summary, this.entrySummary(entry));
+    row.appendChild(summary);
+    const edit = createEl("button", {
+      classNames: ["edit-array-of-btn"],
+      attrs: { type: "button", "data-el-index": String(index) },
+      content: "Edit"
+    });
+    edit.onclick = (event) => {
+      event.preventDefault();
+      this.openEntryDialog(index);
+    };
+    const remove = createEl("button", {
+      classNames: ["delete-array-of-btn"],
+      attrs: { type: "button", "data-el-index": String(index) },
+      content: "Remove"
+    });
+    remove.onclick = (event) => {
+      event.preventDefault();
+      this.entries.splice(index, 1);
+      this.render();
+      this.notifyChange();
+      this.requestUpdate(true);
+    };
+    row.appendChild(edit);
+    row.appendChild(remove);
+    return row;
+  }
+  renderAddButton() {
+    const button = createEl("button", {
+      classNames: ["dl-form-array-of-add-entry"],
+      attrs: { type: "button" },
+      content: this.descriptor.newButtonLabel ?? "Add"
+    });
+    button.onclick = (event) => {
+      event.preventDefault();
+      this.openEntryDialog();
+    };
+    return button;
+  }
+  /** Default summary: every non-empty string value, comma separated. */
+  entrySummary(entry) {
+    if (this.descriptor.renderEntry) return this.descriptor.renderEntry(entry);
+    return Object.values(entry).filter(
+      (value) => typeof value === "string" && value.trim() !== ""
+    ).join(", ");
+  }
+  // ------------------------------------------------------------ entry dialog
+  /** Open the add dialog, or the edit dialog when `index` is given. */
+  openEntryDialog(index) {
+    const editing = index !== void 0;
+    const existing = editing ? this.entries[index] : void 0;
+    const fields = editing ? this.editFields(existing ?? {}) : this.descriptor.of;
+    const confirmId = this.context.ids.for("array-confirm", this.descriptor.name);
+    const form = this.context.createSubForm({
+      classNames: [`form-for-array-of-${this.descriptor.name}`],
+      fields,
+      isEditingArrayEntry: editing,
+      buttons: {
+        OK: {
+          id: confirmId,
+          isActive: ({ data }) => this.validateEntry(data),
+          action: (values) => {
+            if (editing && index !== void 0) this.entries[index] = values;
+            else this.entries.push(values);
+            this.render();
+            this.notifyChange();
+            this.requestUpdate(true);
+          }
+        }
+      }
+    });
+    form.openInModal();
+  }
+  /** Seed each field with the entry's current value, then apply `mapFieldsOnEdit`. */
+  editFields(entry) {
+    const seeded = this.descriptor.of.map((field) => ({
+      ...field,
+      defaultValue: entry[field.name] ?? field.defaultValue ?? ""
+    }));
+    return this.descriptor.mapFieldsOnEdit?.(seeded, entry) ?? seeded;
+  }
+  validateEntry(entry) {
+    if (!this.descriptor.isValidRecord) return true;
+    return this.descriptor.isValidRecord(entry, this.context.contextFor(this.descriptor));
+  }
+  notifyChange() {
+    const onChange = this.descriptor.onChange;
+    if (!onChange) return;
+    void this.context.scheduler.whenSettled().then(() => onChange(this.context.contextFor(this.descriptor).data));
+  }
+};
+
+// src/fields/CardsField.ts
+var CardsField = class extends Field {
+  value;
+  createControl() {
+    const container = createEl("div", { classNames: ["detailed-options"] });
+    for (const card of this.descriptor.cards) {
+      const cardEl = createEl("div", {
+        classNames: ["detailed-option"],
+        attrs: { "data-value": card.value },
+        content: card.content
+      });
+      cardEl.addEventListener("click", () => {
+        this.select(card.value);
+        this.requestUpdate();
+      });
+      container.appendChild(cardEl);
+    }
+    return container;
+  }
+  getValue() {
+    return this.value ?? "";
+  }
+  setValue(value) {
+    if (value == null) return;
+    this.select(asText(value));
+  }
+  select(value) {
+    const target = findByAttribute(
+      this.element,
+      ".detailed-option",
+      "data-value",
+      value
+    )[0];
+    if (!target) return;
+    this.value = value;
+    this.element.setAttribute("value", value);
+    for (const card of this.element.querySelectorAll(".detailed-option")) {
+      card.classList.remove("active");
+    }
+    target.classList.add("active");
+  }
+};
+
+// src/fields/CheckboxField.ts
+var CheckboxField = class extends Field {
+  input;
+  createControl() {
+    const wrapper = createEl("span", { classNames: ["check"] });
+    const inputId = this.context.ids.for("check", this.descriptor.name);
+    const input = createEl("input", { attrs: { type: "checkbox", id: inputId } });
+    this.input = input;
+    input.oninput = input.onchange = () => {
+      wrapper.setAttribute("value", String(input.checked));
+      this.requestUpdate();
+    };
+    const caption = createEl("label", {
+      attrs: { for: inputId },
+      content: this.descriptor.label
+    });
+    wrapper.appendChild(input);
+    wrapper.appendChild(caption);
+    wrapper.setAttribute("value", "false");
+    return wrapper;
+  }
+  /** The outer `displayName` label points at the real input, not the wrapper. */
+  controlIdForLabel() {
+    return this.input.id;
+  }
+  getValue() {
+    return this.input.checked;
+  }
+  setValue(value) {
+    const checked = value === "false" ? false : Boolean(value);
+    this.input.checked = checked;
+    this.element.setAttribute("value", String(checked));
+  }
+};
+
+// src/fields/CustomField.ts
+var CustomField = class extends Field {
+  value = "";
+  createControl() {
+    return createEl("p", { classNames: ["render"] });
+  }
+  getValue() {
+    return this.value;
+  }
+  setValue(value) {
+    this.value = value;
+  }
+  initialize() {
+    this.render();
+  }
+  onFormUpdate(_ctx) {
+    this.render();
+  }
+  render() {
+    this.descriptor.render(this.renderContext());
+  }
+  renderContext() {
+    const base = this.context.contextFor(this.descriptor);
+    return {
+      ...base,
+      element: this.element,
+      requestUpdate: (force = false) => this.requestUpdate(force),
+      setValue: (value) => {
+        this.value = value;
+        this.requestUpdate();
+      }
+    };
+  }
+};
+
+// src/fields/FileField.ts
+var FileField = class extends Field {
+  input;
+  preview;
+  url;
+  createControl() {
+    const container = createEl("div", { classNames: ["file-field"] });
+    const preview = createEl("div", { classNames: ["file-preview", "empty"] });
+    const input = createEl("input", { attrs: { type: "file" } });
+    this.preview = preview;
+    this.input = input;
+    if (this.descriptor.accept) input.setAttribute("accept", this.descriptor.accept);
+    input.id = this.context.ids.for("file", this.descriptor.name);
+    input.oninput = () => {
+      void this.handlePick();
+    };
+    container.appendChild(preview);
+    container.appendChild(input);
+    return container;
+  }
+  controlIdForLabel() {
+    return this.input.id;
+  }
+  getValue() {
+    return this.url ?? "";
+  }
+  setValue(value) {
+    const url = value == null || value === "" ? void 0 : asText(value);
+    this.url = url;
+    if (url) {
+      this.element.setAttribute("data-value", url);
+      this.renderPreview(url);
+    } else {
+      this.element.removeAttribute("data-value");
+      this.clearPreview();
+      this.input.value = "";
+    }
+  }
+  setLoading(loading) {
+    this.preview.classList.toggle("loading", loading);
+  }
+  async handlePick() {
+    const file = this.input.files?.[0];
+    if (!file) {
+      this.setValue(void 0);
+      this.requestUpdate();
+      return;
+    }
+    this.clearPreview();
+    this.preview.classList.remove("empty");
+    this.setLoading(true);
+    try {
+      const url = await this.context.persistFile(file);
+      this.setValue(url);
+    } catch (error) {
+      this.setValue(void 0);
+      this.reportError(error);
+    } finally {
+      this.setLoading(false);
+      this.requestUpdate();
+    }
+  }
+  /**
+   * 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.
+   */
+  reportError(error) {
+    const event = new CustomEvent("dl-error", {
+      bubbles: true,
+      cancelable: true,
+      detail: { field: this.descriptor.name, error }
+    });
+    if (this.element.dispatchEvent(event)) {
+      console.error(
+        `declarative-forms: persistFile failed for field "${this.descriptor.name}".`,
+        error
+      );
+    }
+  }
+  clearPreview() {
+    this.preview.replaceChildren();
+    this.preview.classList.add("empty");
+  }
+  renderPreview(url) {
+    this.preview.replaceChildren();
+    this.preview.classList.remove("empty");
+    const container = createEl("div", { classNames: ["file-selection-container"] });
+    const image = createEl("img", { classNames: ["file-preview"] });
+    image.src = url;
+    image.alt = "";
+    const deleteButton = createEl("button", {
+      classNames: ["file-selection-delete-btn"],
+      attrs: { type: "button", "aria-label": "Remove file" }
+    });
+    deleteButton.appendChild(
+      createEl("div", { classNames: ["file-selection-delete-btn-icon"] })
+    );
+    deleteButton.onclick = () => {
+      this.setValue(void 0);
+      this.requestUpdate();
+    };
+    container.appendChild(image);
+    container.appendChild(deleteButton);
+    this.preview.appendChild(container);
+  }
+};
+
+// src/fields/MessageField.ts
+var MessageField = class extends Field {
+  createControl() {
+    const el = createEl("p", { classNames: ["message"] });
+    setContent(el, this.resolve(this.descriptor.message) ?? "");
+    return el;
+  }
+  get contributesValue() {
+    return false;
+  }
+  getValue() {
+    return void 0;
+  }
+  setValue() {
+  }
+  onFormUpdate(_ctx) {
+    if (typeof this.descriptor.message === "function") {
+      setContent(this.element, this.resolve(this.descriptor.message) ?? "");
+    }
+  }
+};
+
+// src/components/styles.ts
+var DL_SELECT_STYLES = `
+@keyframes dl-placeholder-shimmer {
+    0% { background-position: -468px 0 }
+    100% { background-position: 468px 0 }
+}
+
+dl-select {
+    display: block;
+    position: relative;
+    font-weight: 300;
+    font-family: var(--dl-font-family, 'Rubik');
+    --dl-select-input-width: 370px;
+}
+
+dl-select .input-wrapper {
+    display: inline-block;
+    border-width: 2px;
+    border-style: solid;
+    border-color: var(--dl-line-color, #ddd);
+    background-color: var(--dl-options-background, #fff);
+    color: var(--dl-options-text-color, #545454);
+    border-radius: 4px;
+}
+
+dl-select.dl-focused .input-wrapper {
+    border-color: var(--dl-focused-line-color, #bbb);
+}
+
+dl-select.dl-focused .input-wrapper svg {
+    border-left: 1px solid var(--dl-focused-line-color, #bbb);
+    fill: var(--dl-focused-line-color, #bbb);
+}
+
+dl-select .input-wrapper input {
+    width: var(--dl-select-input-width);
+    color: var(--dl-options-text-color, #545454);
+    outline-width: 0;
+    margin-top: 2px;
+    padding: 6px;
+    font-size: var(--dl-font-size, 0.9em);
+    font-family: var(--dl-font-family, 'Rubik');
+    font-weight: 300;
+    border: 0;
+    border-radius: 4px;
+    float: left;
+    cursor: pointer;
+    box-sizing: content-box;
+    background: transparent;
+}
+
+dl-select .input-wrapper input::placeholder {
+    color: var(--dl-options-inactive-text-color, #545454);
+}
+
+dl-select .input-wrapper svg {
+    width: 20px;
+    height: 20px;
+    margin-top: var(--dl-drop-down-icon-margin-top, 5px);
+    margin-right: 4px;
+    padding-left: 4px;
+    fill: var(--dl-line-color, #ddd);
+    float: right;
+    border-left: 1px solid var(--dl-line-color, #ddd);
+    cursor: pointer;
+}
+
+.options-wrapper {
+    position: absolute;
+    left: 0;
+    top: 20px;
+    font-size: var(--dl-font-size, 0.9em);
+    width: 100%;
+    max-height: 230px;
+    overflow-y: auto;
+    overflow-x: hidden;
+    box-shadow: 0 0 10px -2px rgba(0, 0, 0, 0.4);
+    z-index: 100;
+    background-color: var(--dl-options-background, #fff);
+    font-family: var(--dl-font-family, 'Rubik');
+    border-top: 1px solid var(--dl-focused-line-color, #bbb);
+    border-bottom: 1px solid var(--dl-focused-line-color, #bbb);
+    border-radius: 4px;
+}
+
+.options-wrapper dl-option {
+    display: block;
+    border-left: 1px solid var(--dl-focused-line-color, #bbb);
+    border-right: 1px solid var(--dl-focused-line-color, #bbb);
+    cursor: pointer;
+    padding-top: var(--dl-options-padding-top, 5px);
+    padding-right: var(--dl-options-padding-right, 5px);
+    padding-bottom: var(--dl-options-padding-bottom, 5px);
+    padding-left: var(--dl-options-padding-left, 5px);
+    color: var(--dl-options-text-color, #545454);
+    background-color: var(--dl-options-background, #fff);
+}
+
+.options-wrapper dl-option[selected="true"] {
+    opacity: 0.5;
+    cursor: not-allowed;
+}
+
+.options-wrapper dl-option:hover,
+.options-wrapper dl-option.dl-focused {
+    background-color: var(--dl-options-option-hover-color, rgba(224, 240, 227, 0.4));
+}
+
+.options-wrapper .noMatchesHint {
+    border-left: 1px solid var(--dl-focused-line-color, #bbb);
+    border-right: 1px solid var(--dl-focused-line-color, #bbb);
+    padding: 5px;
+    font-style: italic;
+    color: var(--dl-options-text-color, #545454);
+}
+
+dl-select .dl-option-tag {
+    float: right;
+    border: 1px solid #888;
+    font-size: 0.8em;
+    padding: 2px;
+    font-family: 'Source Code Pro', monospace;
+    border-radius: 2px;
+    margin-top: -1px;
+}
+
+dl-select .dl-option-tag:last-child {
+    margin-right: 10px;
+}
+
+.dl-select-no-options-available svg path { display: none; }
+.dl-select-no-options-available svg { border-left: none !important; }
+
+.dl-select-loading svg,
+.dl-select-no-options-available svg,
+.dl-select-loading input,
+.dl-select-no-options-available input {
+    pointer-events: none;
+}
+
+.dl-select-loading .input-wrapper {
+    animation: dl-placeholder-shimmer 1.25s linear infinite forwards;
+    background: linear-gradient(
+        to right,
+        var(--dl-select-loading-col1, #eee) 10%,
+        var(--dl-select-loading-col2, #ddd) 18%,
+        var(--dl-select-loading-col1, #eee) 33%
+    );
+    background-size: 800px 104px;
+    position: relative;
+    width: 412px;
+}
+
+.dl-select-loading input { opacity: 0; }
+
+.dl-field-one-third input,
+.dl-field-two-third input {
+    --dl-select-input-width: 127px;
+}
+
+body.dark-theme dl-select {
+    --dl-select-loading-col1: #282727;
+    --dl-select-loading-col2: #505656;
+}
+`;
+var injected = false;
+function injectStyles() {
+  if (injected || typeof document === "undefined") return;
+  injected = true;
+  const style = document.createElement("style");
+  style.setAttribute("data-declarative-forms", "dl-select");
+  style.textContent = DL_SELECT_STYLES;
+  (document.head ?? document.documentElement).appendChild(style);
+}
+
+// src/components/DlSelect.ts
+var SVG_NS = "http://www.w3.org/2000/svg";
+var ARROW_PATH = "M4.516 7.548c0.436-0.446 1.043-0.481 1.576 0l3.908 3.747 3.908-3.747c0.533-0.481 1.141-0.446 1.574 0 0.436 0.445 0.408 1.197 0 1.615-0.406 0.418-4.695 4.502-4.695 4.502-0.217 0.223-0.502 0.335-0.787 0.335s-0.57-0.112-0.789-0.335c0 0-4.287-4.084-4.695-4.502s-0.436-1.17 0-1.615z";
+var MIN_LOADING_MS = 1500;
+var LOADING_DELAY_MS = 100;
+var CustomElementBase = typeof HTMLElement === "undefined" ? class {
+} : HTMLElement;
+var DlOption = class extends CustomElementBase {
+  /** The value this option contributes, falling back to its text. */
+  get optionValue() {
+    return this.getAttribute("value") ?? this.innerText;
+  }
+  /** Text shown once selected, which may differ from the option's own label. */
+  get displayText() {
+    return this.getAttribute("displayWhenSelected") ?? this.innerText;
+  }
+};
+var DlSelect = class extends CustomElementBase {
+  optionsWrapper;
+  inputWrapper;
+  noMatchesHint;
+  selectedContainer;
+  inputField;
+  arrow;
+  multiple = false;
+  isLoading = false;
+  initialized = false;
+  loadingTimeouts = [];
+  loadingStartedAt;
+  pendingValue;
+  selectedOption;
+  focusedOption;
+  repositionListener;
+  scrollTargets = [];
+  constructor() {
+    super();
+    this.optionsWrapper = document.createElement("div");
+    this.inputWrapper = document.createElement("span");
+    this.noMatchesHint = document.createElement("span");
+    this.selectedContainer = document.createElement("span");
+    this.inputField = document.createElement("input");
+    this.arrow = document.createElementNS(SVG_NS, "svg");
+  }
+  connectedCallback() {
+    if (this.initialized) return;
+    this.initialized = true;
+    injectStyles();
+    this.inputWrapper.classList.add("input-wrapper");
+    this.optionsWrapper.classList.add("options-wrapper");
+    this.optionsWrapper.setAttribute(
+      "data-for-dl-select",
+      this.getAttribute("name") ?? ""
+    );
+    this.selectedContainer.classList.add("selected-container");
+    this.optionsWrapper.style.display = "none";
+    this.noMatchesHint.classList.add("noMatchesHint");
+    this.noMatchesHint.textContent = "No Matches";
+    this.noMatchesHint.style.display = "none";
+    this.optionsWrapper.appendChild(this.noMatchesHint);
+    this.multiple = this.getAttribute("multiple") !== null;
+    this.inputField.placeholder = this.getAttribute("placeholder") ?? "Select ...";
+    this.inputField.onfocus = () => this.open();
+    this.inputField.onblur = () => this.close();
+    this.inputField.oninput = () => this.filterOptions(this.inputField.value);
+    const path = document.createElementNS(SVG_NS, "path");
+    path.setAttribute("d", ARROW_PATH);
+    this.arrow.appendChild(path);
+    this.arrow.onclick = () => this.inputField.focus();
+    this.classList.add("dl-select-no-options-available");
+    this.addEventListener("keydown", this.onKeyDown);
+    this.mount();
+  }
+  disconnectedCallback() {
+    this.detachRepositionListeners();
+    for (const timeout of this.loadingTimeouts) clearTimeout(timeout);
+    this.loadingTimeouts = [];
+  }
+  /** Move any author-provided `<dl-option>` children into the popup. */
+  mount() {
+    while (this.firstElementChild) {
+      this.adoptOption(this.firstElementChild);
+    }
+    this.inputWrapper.appendChild(this.selectedContainer);
+    this.inputWrapper.appendChild(this.inputField);
+    this.inputWrapper.appendChild(this.arrow);
+    this.appendChild(this.inputWrapper);
+    this.appendChild(this.optionsWrapper);
+    this.setValue(this.getValue());
+    this.updatePlaceholder();
+  }
+  adoptOption(option) {
+    option.onmousedown = () => this.selectOption(option);
+    option.onmouseover = () => this.clearFocusedOption();
+    this.optionsWrapper.appendChild(option);
+  }
+  addOption(option) {
+    this.adoptOption(option);
+    this.classList.remove("dl-select-no-options-available");
+    this.updatePlaceholder();
+  }
+  removeAllOptions() {
+    this.classList.add("dl-select-no-options-available");
+    for (const option of this.optionsWrapper.querySelectorAll("dl-option")) {
+      option.remove();
+    }
+    this.selectedOption = void 0;
+    this.updatePlaceholder();
+  }
+  /** All options currently in the popup. */
+  get options() {
+    return [...this.optionsWrapper.querySelectorAll("dl-option")];
+  }
+  // ---------------------------------------------------------------- loading
+  /**
+   * 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() {
+    this.isLoading = true;
+    this.loadingTimeouts.push(
+      setTimeout(() => {
+        this.classList.add("dl-select-loading");
+        this.optionsWrapper.remove();
+        this.loadingStartedAt = Date.now();
+      }, LOADING_DELAY_MS)
+    );
+  }
+  unsetLoadingStatus() {
+    for (const timeout of this.loadingTimeouts) clearTimeout(timeout);
+    this.loadingTimeouts = [];
+    const elapsed = this.loadingStartedAt ? Date.now() - this.loadingStartedAt : 0;
+    const delay = this.loadingStartedAt ? Math.max(0, MIN_LOADING_MS - elapsed) : 0;
+    const finish = () => {
+      this.appendChild(this.optionsWrapper);
+      this.classList.remove("dl-select-loading");
+      this.isLoading = false;
+      this.loadingStartedAt = void 0;
+      if (this.pendingValue !== void 0) {
+        const value = this.pendingValue;
+        this.pendingValue = void 0;
+        this.setValue(value);
+      }
+    };
+    if (delay === 0) finish();
+    else this.loadingTimeouts.push(setTimeout(finish, delay));
+  }
+  // ------------------------------------------------------------ value access
+  getValue() {
+    const raw = this.getAttribute("value");
+    if (raw) {
+      if (!this.multiple) return raw;
+      try {
+        return JSON.parse(raw);
+      } catch {
+        return void 0;
+      }
+    }
+    const pending = this.getAttribute("tmp-value");
+    if (!pending) return void 0;
+    if (this.multiple) {
+      try {
+        return JSON.parse(pending).filter((v) => this.findOption(v));
+      } catch {
+        return void 0;
+      }
+    }
+    return this.findOption(pending) ? pending : void 0;
+  }
+  setValue(value) {
+    if (value === void 0 || value === null || value === "") return;
+    if (this.isLoading) {
+      this.pendingValue = value;
+      return;
+    }
+    if (this.multiple) {
+      const next = (Array.isArray(value) ? value : [value]).map(asText);
+      for (const current of this.getValue() ?? []) {
+        const option2 = this.findOption(current);
+        if (option2) this.deselectOption(option2);
+      }
+      for (const entry of next) {
+        const option2 = this.findOption(entry);
+        if (option2) this.selectOption(option2);
+      }
+      return;
+    }
+    const single = asText(value);
+    this.setAttribute("tmp-value", single);
+    const option = this.findOption(single);
+    if (option) this.selectOption(option);
+  }
+  /**
+   * 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.
+   */
+  findOption(value) {
+    return this.options.find((option) => option.getAttribute("value") === value) ?? this.options.find((option) => option.innerText === value);
+  }
+  // ------------------------------------------------------------- selection
+  selectOption(option) {
+    if (!option) return;
+    const value = option.optionValue;
+    if (this.multiple) {
+      const current = this.getValue() ?? [];
+      if (current.includes(value)) return;
+      this.selectedContainer.appendChild(this.createTag(option));
+      this.markSelected(option, true);
+      this.setAttribute("value", JSON.stringify([...current, value]));
+    } else {
+      this.selectedOption = option;
+      this.inputField.value = option.displayText;
+      this.setAttribute("value", value);
+    }
+    this.emitChange();
+  }
+  deselectOption(option) {
+    const value = option.optionValue;
+    const current = this.getValue() ?? [];
+    this.tagFor(value)?.remove();
+    this.markSelected(option, false);
+    this.setAttribute("value", JSON.stringify(current.filter((v) => v !== value)));
+    this.emitChange();
+  }
+  /** Mark every option carrying this value, since duplicates are allowed. */
+  markSelected(option, selected) {
+    const attribute = option.getAttribute("value");
+    const matches = attribute ? findByAttribute(this, "dl-option", "value", attribute) : [option];
+    for (const match of matches) match.setAttribute("selected", String(selected));
+  }
+  createTag(option) {
+    const tag = document.createElement("span");
+    tag.classList.add("multiselect-tag");
+    tag.dataset["value"] = option.optionValue;
+    tag.innerText = option.displayText;
+    const removeContainer = document.createElement("span");
+    removeContainer.classList.add("dl-muliselect-selected-remove-container");
+    const remove = document.createElement("span");
+    remove.classList.add("dl-muliselect-selected-remove");
+    remove.onclick = () => this.deselectOption(option);
+    removeContainer.appendChild(remove);
+    tag.appendChild(removeContainer);
+    return tag;
+  }
+  tagFor(value) {
+    return findByAttribute(
+      this.selectedContainer,
+      ".multiselect-tag",
+      "data-value",
+      value
+    )[0];
+  }
+  emitChange() {
+    this.dispatchEvent(new CustomEvent("change", { bubbles: false, cancelable: true }));
+  }
+  // -------------------------------------------------------------- filtering
+  filterOptions(query) {
+    const terms = query.toLowerCase().split(" ").filter(Boolean);
+    let matched = false;
+    for (const option of this.options) {
+      const text = option.innerText.toLowerCase();
+      const visible = terms.length === 0 || terms.every((term) => text.includes(term));
+      option.style.display = visible ? "block" : "none";
+      matched ||= visible;
+    }
+    this.noMatchesHint.style.display = matched ? "none" : "block";
+  }
+  visibleOptions() {
+    return this.options.filter((option) => option.style.display !== "none");
+  }
+  clearFocusedOption() {
+    this.focusedOption = void 0;
+    for (const option of this.options) option.classList.remove("dl-focused");
+  }
+  focusOption(option) {
+    this.clearFocusedOption();
+    if (!option) return;
+    this.focusedOption = option;
+    option.classList.add("dl-focused");
+    option.scrollIntoView?.({ block: "nearest" });
+  }
+  step(delta) {
+    const visible = this.visibleOptions();
+    if (visible.length === 0) return;
+    const current = this.focusedOption ? visible.indexOf(this.focusedOption) : -1;
+    const next = current < 0 ? delta === 1 ? 0 : visible.length - 1 : current + delta;
+    if (next < 0 || next >= visible.length) return;
+    this.focusOption(visible[next]);
+  }
+  onKeyDown = (event) => {
+    const key = event.key;
+    if (key === "ArrowDown") this.step(1);
+    else if (key === "ArrowUp") this.step(-1);
+    else if (key === "Enter") {
+      this.selectOption(this.focusedOption);
+      this.close();
+    } else return;
+    event.preventDefault();
+    event.stopPropagation();
+  };
+  // ------------------------------------------------------------ open / close
+  get placeholderText() {
+    if (this.options.length === 0) return "No Options Available";
+    if (this.selectedOption) return this.selectedOption.innerText;
+    return this.getAttribute("placeholder") ?? "Select ...";
+  }
+  updatePlaceholder() {
+    this.inputField.placeholder = this.placeholderText;
+  }
+  /** Open the popup. Named `open` because `focus()` is `HTMLElement`'s. */
+  open() {
+    this.classList.add("dl-focused");
+    this.updatePlaceholder();
+    this.inputField.value = "";
+    this.optionsWrapper.style.display = "inline-block";
+    this.filterOptions("");
+    document.body.appendChild(this.optionsWrapper);
+    this.reposition();
+    this.attachRepositionListeners();
+  }
+  close() {
+    this.classList.remove("dl-focused");
+    this.optionsWrapper.style.display = "none";
+    this.inputField.value = this.selectedOption?.displayText ?? "";
+    this.inputField.blur();
+    this.clearFocusedOption();
+    this.appendChild(this.optionsWrapper);
+    this.detachRepositionListeners();
+  }
+  reposition() {
+    const anchor = this.inputWrapper.getBoundingClientRect();
+    const style = this.optionsWrapper.style;
+    style.position = "absolute";
+    style.top = `${anchor.bottom + window.scrollY + 2}px`;
+    style.left = `${anchor.left + window.scrollX}px`;
+    style.width = `${anchor.width}px`;
+  }
+  attachRepositionListeners() {
+    const listener = () => this.reposition();
+    this.repositionListener = listener;
+    this.scrollTargets = [];
+    for (let el = this.inputWrapper; el; el = el.parentElement) {
+      if (el.scrollHeight > el.clientHeight) {
+        el.addEventListener("scroll", listener);
+        this.scrollTargets.push(el);
+      }
+    }
+    document.addEventListener("scroll", listener);
+    window.addEventListener("resize", listener);
+    this.scrollTargets.push(document, window);
+  }
+  detachRepositionListeners() {
+    const listener = this.repositionListener;
+    if (!listener) return;
+    for (const target of this.scrollTargets) {
+      target.removeEventListener("scroll", listener);
+      target.removeEventListener("resize", listener);
+    }
+    this.scrollTargets = [];
+    this.repositionListener = void 0;
+  }
+};
+function defineDlSelect() {
+  if (typeof customElements === "undefined") return;
+  if (!customElements.get("dl-option")) customElements.define("dl-option", DlOption);
+  if (!customElements.get("dl-select")) customElements.define("dl-select", DlSelect);
+}
+
+// src/fields/SelectField.ts
+var SelectField = class extends Field {
+  select;
+  get wrapperExtraClass() {
+    return "dl-select-wrapper";
+  }
+  createControl() {
+    defineDlSelect();
+    const select = document.createElement("dl-select");
+    this.select = select;
+    if (this.descriptor.multiple) select.setAttribute("multiple", "");
+    const placeholder = this.descriptor.placeholder;
+    if (typeof placeholder === "string") select.setAttribute("placeholder", placeholder);
+    select.onchange = () => this.requestUpdate();
+    return select;
+  }
+  async initialize() {
+    await this.loadOptions();
+  }
+  getValue() {
+    const value = this.select.getValue();
+    if (value === void 0) return this.descriptor.multiple ? [] : "";
+    return value;
+  }
+  setValue(value) {
+    this.select.setValue(value);
+  }
+  setLoading(loading) {
+    if (loading) this.select.setLoadingStatus();
+    else this.select.unsetLoadingStatus();
+  }
+  onFormUpdate(_ctx, triggerName) {
+    if (typeof this.descriptor.placeholder === "function") {
+      this.select.setAttribute(
+        "placeholder",
+        this.resolve(this.descriptor.placeholder) ?? ""
+      );
+    }
+    const dependsOnTrigger = triggerName !== void 0 && this.descriptor.reloadOnChangeOf?.includes(triggerName) === true;
+    if (dependsOnTrigger && typeof this.descriptor.options === "function") {
+      void this.loadOptions({ reload: true });
+    }
+  }
+  /**
+   * 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.
+   */
+  async loadOptions(opts = {}) {
+    const isCurrent = this.context.scheduler.claim(`options:${this.descriptor.name}`);
+    const source = this.descriptor.options;
+    const requested = typeof source === "function" ? source(this.context.contextFor(this.descriptor)) : source;
+    const isAsync = requested instanceof Promise;
+    if (isAsync) this.select.setLoadingStatus();
+    try {
+      const options = await requested ?? [];
+      if (!isCurrent()) return;
+      if (opts.reload) this.context.tooltips.reset(this.descriptor.name);
+      const previous = this.select.getValue();
+      this.select.removeAllOptions();
+      for (const option of options) this.select.addOption(this.createOption(option));
+      if (isAsync) this.select.unsetLoadingStatus();
+      if (previous !== void 0) this.select.setValue(previous);
+    } catch (error) {
+      if (!isCurrent()) return;
+      if (isAsync) this.select.unsetLoadingStatus();
+      this.reportOptionsError(error);
+    }
+  }
+  createOption(option) {
+    const el = document.createElement("dl-option");
+    if (typeof option === "string") {
+      el.textContent = option;
+      return el;
+    }
+    el.setAttribute("value", option.value);
+    setContent(el, option.label);
+    if (option.displayWhenSelected) {
+      el.setAttribute("displayWhenSelected", option.displayWhenSelected);
+    }
+    return el;
+  }
+  reportOptionsError(error) {
+    const handler = this.descriptor.onOptionsError;
+    if (!handler) return;
+    const message = handler({
+      ...this.context.contextFor(this.descriptor),
+      error
+    });
+    if (message) {
+      this.context.tooltips.setMessage(this.descriptor.name, message.level, message.text);
+    }
+  }
+};
+
+// src/fields/TextField.ts
+var TextField = class extends Field {
+  input;
+  createControl() {
+    const input = createEl("input");
+    this.input = input;
+    if (this.descriptor.type) input.type = this.descriptor.type;
+    if (this.descriptor.autocomplete) {
+      input.setAttribute("autocomplete", this.descriptor.autocomplete);
+    }
+    const placeholder = this.descriptor.placeholder;
+    if (typeof placeholder === "string") input.placeholder = placeholder;
+    input.oninput = () => this.requestUpdate();
+    input.onchange = input.oninput;
+    return input;
+  }
+  getValue() {
+    return this.input.value;
+  }
+  setValue(value) {
+    this.input.value = asText(value);
+  }
+  onFormUpdate(_ctx) {
+    if (typeof this.descriptor.placeholder === "function") {
+      this.input.placeholder = this.resolve(this.descriptor.placeholder) ?? "";
+    }
+  }
+};
+
+// src/core/FieldRegistry.ts
+var FieldRegistry = class _FieldRegistry {
+  kinds = /* @__PURE__ */ new Map();
+  constructor(entries) {
+    for (const [kind, ctor] of entries ?? []) this.kinds.set(kind, ctor);
+  }
+  register(kind, ctor) {
+    this.kinds.set(kind, ctor);
+    return this;
+  }
+  has(kind) {
+    return this.kinds.has(kind);
+  }
+  /** A copy, so callers can add kinds without mutating the shared default. */
+  clone() {
+    return new _FieldRegistry(this.kinds);
+  }
+  create(descriptor, context) {
+    const kind = descriptor.kind ?? "text";
+    const Ctor = this.kinds.get(kind);
+    if (!Ctor) {
+      throw new Error(
+        `declarative-forms: unknown field kind "${kind}" on field "${descriptor.name}". Known kinds: ${[...this.kinds.keys()].sort().join(", ")}.`
+      );
+    }
+    return new Ctor(descriptor, context).build();
+  }
+};
+var defaultFieldRegistry = new FieldRegistry([
+  ["text", TextField],
+  ["textarea", TextAreaField],
+  ["select", SelectField],
+  ["checkbox", CheckboxField],
+  ["message", MessageField],
+  ["file", FileField],
+  ["computed", ComputedField],
+  ["cards", CardsField],
+  ["custom", CustomField],
+  ["array", ArrayField]
+]);
+
+// src/util/deepEqual.ts
+function deepEqual(a, b) {
+  if (Object.is(a, b)) return true;
+  if (typeof a !== "object" || typeof b !== "object" || a === null || b === null) {
+    return false;
+  }
+  if (Object.getPrototypeOf(a) !== Object.getPrototypeOf(b)) return false;
+  if (a instanceof Date) return a.getTime() === b.getTime();
+  if (typeof Blob !== "undefined" && a instanceof Blob) return false;
+  if (typeof FileList !== "undefined" && a instanceof FileList) return false;
+  if (Array.isArray(a)) {
+    const other = b;
+    if (a.length !== other.length) return false;
+    return a.every((item, i) => deepEqual(item, other[i]));
+  }
+  if (a instanceof Map) {
+    const other = b;
+    if (a.size !== other.size) return false;
+    for (const [key, value] of a) {
+      if (!other.has(key) || !deepEqual(value, other.get(key))) return false;
+    }
+    return true;
+  }
+  if (a instanceof Set) {
+    const other = b;
+    if (a.size !== other.size) return false;
+    for (const value of a) {
+      if (!other.has(value)) return false;
+    }
+    return true;
+  }
+  const left = a;
+  const right = b;
+  const aKeys = Object.keys(left);
+  if (aKeys.length !== Object.keys(right).length) return false;
+  return aKeys.every(
+    (key) => Object.prototype.hasOwnProperty.call(right, key) && deepEqual(left[key], right[key])
+  );
+}
+
+// src/core/FormModel.ts
+var FormModel = class {
+  last;
+  lastWithoutTab;
+  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, includeTab = false) {
+    const snapshot = { ...values };
+    const withoutTab = { ...values };
+    delete withoutTab["activeTab"];
+    if (this.last === void 0) {
+      this.last = snapshot;
+      this.lastWithoutTab = withoutTab;
+      return true;
+    }
+    const baseline = includeTab ? this.last : this.lastWithoutTab;
+    const candidate = includeTab ? snapshot : withoutTab;
+    if (deepEqual(baseline, candidate)) return false;
+    this.last = snapshot;
+    this.lastWithoutTab = withoutTab;
+    return true;
+  }
+  subscribe(subscriber) {
+    this.subscribers.push(subscriber);
+    return () => {
+      const index = this.subscribers.indexOf(subscriber);
+      if (index >= 0) this.subscribers.splice(index, 1);
+    };
+  }
+  notify(values) {
+    for (const subscriber of [...this.subscribers]) {
+      subscriber(values);
+    }
+  }
+  /** Forget the baseline so the next comparison reports a change. */
+  reset() {
+    this.last = void 0;
+    this.lastWithoutTab = void 0;
+  }
+};
+
+// src/core/IdGenerator.ts
+var formCounter = 0;
+var IdGenerator = class {
+  prefix;
+  counter = 0;
+  constructor(prefix) {
+    this.prefix = prefix ?? `dlf${++formCounter}`;
+  }
+  /** A unique id, e.g. `dlf3-field-2`. */
+  next(kind = "field") {
+    return `${this.prefix}-${kind}-${++this.counter}`;
+  }
+  /** A stable id derived from a name, e.g. `dlf3-control-email`. */
+  for(kind, name) {
+    return `${this.prefix}-${kind}-${name}`;
+  }
+};
+
+// src/core/UpdateScheduler.ts
+var UpdateScheduler = class {
+  pending = /* @__PURE__ */ new Set();
+  generations = /* @__PURE__ */ new Map();
+  /** Register async work and drop it from the set once it settles. */
+  track(work) {
+    this.pending.add(work);
+    const forget = () => {
+      this.pending.delete(work);
+    };
+    work.then(forget, forget);
+    return work;
+  }
+  /** Number of currently in-flight operations. Test/diagnostics only. */
+  get pendingCount() {
+    return this.pending.size;
+  }
+  /**
+   * 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).
+   */
+  async whenSettled() {
+    let guard = 0;
+    while (this.pending.size > 0) {
+      if (++guard > 100) {
+        throw new Error(
+          "declarative-forms: form updates did not settle after 100 rounds \u2014 a field callback is most likely scheduling work on every update."
+        );
+      }
+      await Promise.allSettled([...this.pending]);
+    }
+  }
+  /**
+   * 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) {
+    const generation = (this.generations.get(key) ?? 0) + 1;
+    this.generations.set(key, generation);
+    return () => this.generations.get(key) === generation;
+  }
+  /** Invalidate every outstanding claim and forget all pending work. */
+  reset() {
+    this.pending.clear();
+    for (const key of this.generations.keys()) {
+      this.generations.set(key, (this.generations.get(key) ?? 0) + 1);
+    }
+  }
+};
+
+// src/ui/ButtonBar.ts
+var ButtonBar = class {
+  constructor(config, callbacks) {
+    this.config = config;
+    this.callbacks = callbacks;
+    this.element = createEl("div", { classNames: ["low-bar"] });
+    for (const [label, descriptor] of Object.entries(config)) {
+      const button = this.createButton(label, descriptor);
+      this.buttons.push({ descriptor, element: button });
+      this.element.appendChild(button);
+    }
+  }
+  config;
+  callbacks;
+  element;
+  buttons = [];
+  get count() {
+    return this.buttons.length;
+  }
+  /** The first button — the one Enter activates. */
+  get primary() {
+    return this.buttons[0]?.element;
+  }
+  /** Whether the primary button is currently disabled. */
+  get primaryDisabled() {
+    return this.primary?.classList.contains("disabled") ?? false;
+  }
+  createButton(label, descriptor) {
+    const button = createEl("button", {
+      classNames: ["btn"],
+      attrs: { type: "button" },
+      content: label
+    });
+    if (descriptor.id) button.id = descriptor.id;
+    addClasses(button, descriptor.class);
+    button.onclick = () => {
+      void this.activate(descriptor, button);
+    };
+    return button;
+  }
+  async activate(descriptor, button) {
+    const classes = button.classList;
+    if (classes.contains("loading-btn") || classes.contains("disabled")) return;
+    classes.add("loading-btn");
+    try {
+      await this.callbacks.whenSettled();
+      if (classes.contains("disabled")) return;
+      await this.callbacks.updateComputedFields();
+      if (descriptor.doNotCloseModal) {
+        await descriptor.action?.(this.callbacks.getValues());
+      } else {
+        await this.callbacks.closeWith(descriptor.action);
+      }
+    } finally {
+      classes.remove("loading-btn");
+    }
+  }
+  /**
+   * Re-evaluate every `isActive` / `isVisible` predicate.
+   *
+   * Buttons without an `id` are skipped, matching v1 — an id is what opts a
+   * button into state management.
+   */
+  async refresh(ctx) {
+    const work = [];
+    for (const { descriptor, element } of this.buttons) {
+      if (!descriptor.id) continue;
+      if (descriptor.isActive) {
+        work.push(
+          this.applyPredicate(descriptor.isActive(ctx), (active) => {
+            element.classList.toggle("disabled", !active);
+            element.toggleAttribute("disabled", !active);
+          })
+        );
+      }
+      if (descriptor.isVisible) {
+        work.push(
+          this.applyPredicate(descriptor.isVisible(ctx), (visible) => {
+            element.classList.toggle("invisible", !visible);
+          })
+        );
+      }
+    }
+    await Promise.allSettled(work);
+  }
+  /**
+   * 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.
+   */
+  applyPredicate(result, apply) {
+    if (typeof result === "boolean") {
+      apply(result);
+      return Promise.resolve();
+    }
+    return result.then(apply);
+  }
+  /** The configured buttons, for callers that want to invoke an action directly. */
+  get descriptors() {
+    return this.config;
+  }
+};
+
+// src/ui/ModalView.ts
+var ModalView = class {
+  wrapper;
+  modal;
+  content;
+  upBar;
+  constructor(options) {
+    this.wrapper = createEl("div", { classNames: ["dl-modal"] });
+    this.wrapper.style.display = "none";
+    this.modal = createEl("div", { classNames: ["modal"] });
+    this.content = createEl("div", { classNames: ["modal-content"] });
+    this.upBar = createEl("div");
+    if (options.onCancel) {
+      this.upBar.classList.add("up-bar");
+      const cancel = createEl("button", {
+        classNames: ["cancelBtn", "secondary"],
+        attrs: { type: "button", "aria-label": "Close dialog" }
+      });
+      cancel.onclick = () => options.onCancel?.();
+      this.upBar.appendChild(cancel);
+    }
+    this.modal.appendChild(this.upBar);
+    this.modal.appendChild(options.tabBar.element);
+    this.modal.appendChild(this.content);
+    this.modal.appendChild(options.buttonBar.element);
+    this.wrapper.appendChild(this.modal);
+  }
+  /** Attach to the document body. Used by `openInModal`. */
+  mount() {
+    document.body.appendChild(this.wrapper);
+  }
+  setVisible(visible) {
+    this.wrapper.style.display = visible ? "block" : "none";
+  }
+  hide() {
+    this.wrapper.classList.add("dl-modal-hidden");
+  }
+  show() {
+    this.wrapper.classList.remove("dl-modal-hidden");
+    this.wrapper.classList.add("dl-modal-restored");
+  }
+  /**
+   * 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) {
+    this.wrapper.classList.toggle("dl-modal-stacked", depth > 0);
+    if (depth > 0) this.wrapper.style.setProperty("--dl-stack-depth", String(depth));
+    else this.wrapper.style.removeProperty("--dl-stack-depth");
+  }
+  /** Mark the dialog as embedded rather than floating. */
+  setEmbedded() {
+    this.wrapper.classList.add("noModalDialog");
+  }
+  addModalClasses(names) {
+    for (const name of names ?? []) this.modal.classList.add(name);
+  }
+  addWrapperClasses(names) {
+    for (const name of names ?? []) this.wrapper.classList.add(name);
+  }
+  remove() {
+    this.wrapper.remove();
+  }
+};
+
+// src/ui/ModalStack.ts
+var ModalStack = class {
+  dialogs = [];
+  listening = false;
+  get size() {
+    return this.dialogs.length;
+  }
+  /** Values of every dialog on the stack, outermost first. */
+  values() {
+    return this.dialogs.map((dialog) => dialog.getValues());
+  }
+  /** The dialog currently on top, if any. */
+  get top() {
+    return this.dialogs[this.dialogs.length - 1];
+  }
+  push(dialog) {
+    this.dialogs.push(dialog);
+    this.startListening();
+    if (this.dialogs.length >= 2) {
+      this.dialogs[this.dialogs.length - 2]?.hide();
+    }
+  }
+  /** Remove a dialog and reveal whatever it was covering. */
+  remove(dialog) {
+    const index = this.dialogs.indexOf(dialog);
+    if (index < 0) return;
+    this.dialogs.splice(index, 1);
+    const top = this.top;
+    if (top) {
+      top.show();
+      top.refreshTabs();
+    } else {
+      this.stopListening();
+    }
+  }
+  contains(dialog) {
+    return this.dialogs.includes(dialog);
+  }
+  onKeyDown = (event) => {
+    const top = this.top;
+    if (!top) return;
+    if (event.key === "Escape") {
+      top.requestCancel();
+    } else if (event.key === "Enter" && top.buttonCount === 1) {
+      top.requestConfirm(event);
+    }
+  };
+  startListening() {
+    if (this.listening || typeof document === "undefined") return;
+    document.addEventListener("keydown", this.onKeyDown);
+    this.listening = true;
+  }
+  stopListening() {
+    if (!this.listening) return;
+    document.removeEventListener("keydown", this.onKeyDown);
+    this.listening = false;
+  }
+};
+var globalModalStack = new ModalStack();
+
+// src/ui/TabBar.ts
+var TabBar = class {
+  constructor(onSelect) {
+    this.onSelect = onSelect;
+    this.element = createEl("div", { classNames: ["tabWrapper"] });
+  }
+  onSelect;
+  element;
+  buttons = /* @__PURE__ */ new Map();
+  seen = /* @__PURE__ */ new Set();
+  active;
+  get activeTab() {
+    return this.active;
+  }
+  /** Rebuild the strip from the tabs that currently have at least one visible field. */
+  render(tabs) {
+    this.element.replaceChildren();
+    this.buttons = /* @__PURE__ */ new Map();
+    for (const tab of tabs) {
+      const button = createEl("div", {
+        classNames: ["dl-tab-btn", tabClassName(tab), this.seen.has(tab) && "seen"],
+        content: tab
+      });
+      button.onclick = () => this.onSelect(tab);
+      this.buttons.set(tab, button);
+      this.element.appendChild(button);
+    }
+    const next = this.active && this.buttons.has(this.active) ? this.active : tabs[0];
+    if (next) this.select(next);
+    else this.active = void 0;
+  }
+  /**
+   * 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) {
+    const button = this.buttons.get(tab);
+    if (!button) return false;
+    for (const other of this.buttons.values()) other.classList.remove("active");
+    button.classList.add("active");
+    button.classList.add("seen");
+    this.seen.add(tab);
+    this.active = tab;
+    return true;
+  }
+  get tabs() {
+    return [...this.buttons.keys()];
+  }
+  get isEmpty() {
+    return this.buttons.size === 0;
+  }
+};
+
+// src/ui/tooltip/NativeTooltipProvider.ts
+var BUBBLE_CLASS = "dl-tooltip-bubble";
+var NativeTooltipProvider = class {
+  attachments = /* @__PURE__ */ new WeakMap();
+  attach(element, content) {
+    const existing = this.attachments.get(element);
+    if (existing) {
+      existing.content = content;
+      if (existing.bubble) existing.bubble.innerHTML = content;
+      return;
+    }
+    const attachment = { content, bubble: void 0, listeners: [] };
+    this.attachments.set(element, attachment);
+    const show = () => this.show(element);
+    const hide = () => this.hide(element);
+    const bind = (type, handler) => {
+      element.addEventListener(type, handler);
+      attachment.listeners.push(() => element.removeEventListener(type, handler));
+    };
+    bind("mouseenter", show);
+    bind("mouseleave", hide);
+    bind("focus", show);
+    bind("blur", hide);
+  }
+  detach(element) {
+    const attachment = this.attachments.get(element);
+    if (!attachment) return;
+    for (const remove of attachment.listeners) remove();
+    attachment.bubble?.remove();
+    this.attachments.delete(element);
+  }
+  show(element) {
+    const attachment = this.attachments.get(element);
+    if (!attachment || attachment.bubble) return;
+    const bubble = createEl("div", { classNames: [BUBBLE_CLASS] });
+    bubble.innerHTML = attachment.content;
+    bubble.setAttribute("role", "tooltip");
+    document.body.appendChild(bubble);
+    attachment.bubble = bubble;
+    this.position(element, bubble);
+  }
+  hide(element) {
+    const attachment = this.attachments.get(element);
+    if (!attachment?.bubble) return;
+    attachment.bubble.remove();
+    attachment.bubble = void 0;
+  }
+  position(element, bubble) {
+    const anchor = element.getBoundingClientRect();
+    const box = bubble.getBoundingClientRect();
+    const gap = 8;
+    let left = anchor.right + gap;
+    if (left + box.width > window.innerWidth) {
+      left = Math.max(gap, anchor.left - box.width - gap);
+    }
+    const top = anchor.top + anchor.height / 2 - box.height / 2;
+    bubble.style.left = `${left + window.scrollX}px`;
+    bubble.style.top = `${Math.max(gap, top) + window.scrollY}px`;
+  }
+};
+
+// src/ui/tooltip/TooltipController.ts
+var LEVEL_CLASS = {
+  warning: "tooltip-warning",
+  error: "tooltip-error",
+  success: "tooltip-success",
+  loading: "tooltip-loading"
+};
+var TooltipController = class {
+  markers = /* @__PURE__ */ new Map();
+  provider;
+  constructor(provider = new NativeTooltipProvider()) {
+    this.provider = provider;
+  }
+  /**
+   * 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) {
+    const text = contentToString(content);
+    const marker = createEl("span", {
+      classNames: ["dl-tooltip"],
+      attrs: {
+        "data-tippy-content": text,
+        "data-initial-tippy-content": text
+      },
+      content: "?"
+    });
+    this.provider.attach(marker, text);
+    return marker;
+  }
+  /** Associate a marker with a field name. Called by the form after mounting. */
+  register(fieldName, marker) {
+    if (marker) this.markers.set(fieldName, marker);
+  }
+  /**
+   * Replace a field's tooltip text, icon and state class.
+   *
+   * A field without a tooltip is a silent no-op, matching v1.
+   */
+  set(fieldName, text, icon = "?", className = "") {
+    const marker = this.markers.get(fieldName);
+    if (!marker) return;
+    const base = marker.classList.contains("dl-tooltip-in-input") ? "dl-tooltip dl-tooltip-in-input" : "dl-tooltip";
+    marker.className = className ? `${base} ${className}` : base;
+    marker.setAttribute("data-tippy-content", text);
+    marker.innerHTML = icon;
+    this.provider.attach(marker, text);
+  }
+  setSuccess(fieldName, text) {
+    this.set(fieldName, text, "&#10003;", LEVEL_CLASS.success);
+  }
+  setWarning(fieldName, text) {
+    this.set(fieldName, text, "!", LEVEL_CLASS.warning);
+  }
+  setError(fieldName, text) {
+    this.set(fieldName, text, "!", LEVEL_CLASS.error);
+  }
+  setLoading(fieldName, text) {
+    this.set(fieldName, text, "", LEVEL_CLASS.loading);
+  }
+  /** Apply a `{ level, text }` message from an options loader. */
+  setMessage(fieldName, level, text) {
+    if (level === "error") this.setError(fieldName, text);
+    else this.setWarning(fieldName, text);
+  }
+  /** Restore a field's original tooltip text and `?` icon. */
+  reset(fieldName) {
+    const marker = this.markers.get(fieldName);
+    if (!marker) return;
+    this.set(fieldName, marker.getAttribute("data-initial-tippy-content") ?? "", "?", "");
+  }
+  resetAll(fieldNames) {
+    for (const name of fieldNames) this.reset(name);
+  }
+  destroy() {
+    for (const marker of this.markers.values()) this.provider.detach(marker);
+    this.markers.clear();
+  }
+};
+
+// src/core/DeclarativeForm.ts
+var filePersistenceCache = /* @__PURE__ */ new WeakMap();
+var DeclarativeForm = class _DeclarativeForm {
+  /** The `.dl-form` wrapper containing the `<form>`. */
+  dom;
+  /** The `<form>` element the fields are rendered into. */
+  formElement;
+  options;
+  registry;
+  stack;
+  parent;
+  fieldList = [];
+  fieldsByName = /* @__PURE__ */ new Map();
+  model = new FormModel();
+  scheduler = new UpdateScheduler();
+  ids = new IdGenerator();
+  tooltips;
+  tabBar;
+  buttonBar;
+  view;
+  editingArrayEntry;
+  embedded = false;
+  ready;
+  constructor(options, internal = {}) {
+    this.options = options;
+    this.registry = internal.registry ?? defaultFieldRegistry;
+    this.stack = internal.stack ?? globalModalStack;
+    this.parent = internal.parent;
+    this.editingArrayEntry = internal.isEditingArrayEntry ?? false;
+    this.tooltips = new TooltipController(options.tooltipProvider);
+    this.dom = createEl("div", { classNames: ["dl-form"] });
+    this.formElement = createEl("form", { attrs: { autocomplete: "off" } });
+    for (const name of options.classNames ?? []) this.formElement.classList.add(name);
+    this.formElement.onsubmit = (event) => {
+      event.preventDefault();
+      return false;
+    };
+    this.dom.appendChild(this.formElement);
+    this.tabBar = new TabBar((tab) => this.setActiveTab(tab));
+    this.buttonBar = new ButtonBar(this.resolveButtons(), {
+      whenSettled: () => this.scheduler.whenSettled(),
+      updateComputedFields: () => this.updateComputedFields(),
+      getValues: () => this.getValues(),
+      closeWith: (action) => this.close(action)
+    });
+    this.buildFields();
+    this.ready = this.initialize();
+  }
+  // ------------------------------------------------------------------ setup
+  resolveButtons() {
+    if (this.options.buttons) return this.options.buttons;
+    return {
+      [this.options.confirmLabel ?? "OK"]: {
+        id: this.ids.for("confirm", "default"),
+        action: this.options.onConfirm
+      }
+    };
+  }
+  buildFields() {
+    const context = this.createFieldContext();
+    for (const descriptor of this.options.fields) {
+      if (this.fieldsByName.has(descriptor.name)) {
+        throw new Error(
+          `declarative-forms: duplicate field name "${descriptor.name}". Field names must be unique within a form.`
+        );
+      }
+      const field = this.registry.create(descriptor, context);
+      this.fieldList.push(field);
+      this.fieldsByName.set(descriptor.name, field);
+      this.tooltips.register(descriptor.name, field.tooltipMarker);
+      this.formElement.appendChild(field.wrapper);
+    }
+  }
+  async initialize() {
+    await Promise.allSettled(
+      this.fieldList.map(
+        (field) => this.scheduler.track(Promise.resolve(field.initialize()))
+      )
+    );
+    await Promise.allSettled(
+      this.fieldList.map((field) => this.scheduler.track(field.applyDefaultValue()))
+    );
+    await this.update();
+  }
+  /** Resolves once initial options and default values have been applied. */
+  whenReady() {
+    return this.ready.then(() => this.scheduler.whenSettled());
+  }
+  createFieldContext() {
+    return {
+      ids: this.ids,
+      tooltips: this.tooltips,
+      scheduler: this.scheduler,
+      get parentData() {
+        return void 0;
+      },
+      stackData: [],
+      isEditingArrayEntry: this.editingArrayEntry,
+      contextFor: (descriptor) => this.contextFor(descriptor),
+      requestUpdate: (source, force) => {
+        void this.update(source, force);
+      },
+      persistFile: (file) => this.persistFile(file),
+      createSubForm: (options) => this.createSubForm(options)
+    };
+  }
+  contextFor(descriptor) {
+    return {
+      data: this.getValues(),
+      form: this,
+      field: descriptor,
+      parentData: this.parent?.getValues(),
+      stackData: this.stack.values(),
+      isEditingArrayEntry: this.editingArrayEntry
+    };
+  }
+  createSubForm(options) {
+    return new _DeclarativeForm(
+      {
+        fields: options.fields,
+        classNames: options.classNames,
+        buttons: options.buttons,
+        onCancel: () => {
+        },
+        persistFile: this.options.persistFile,
+        tooltipProvider: this.options.tooltipProvider
+      },
+      {
+        parent: this,
+        stack: this.stack,
+        registry: this.registry,
+        isEditingArrayEntry: options.isEditingArrayEntry
+      }
+    );
+  }
+  async persistFile(file) {
+    const persist = this.options.persistFile;
+    if (!persist) {
+      throw new Error(
+        "declarative-forms: a file field needs a `persistFile` handler on the form to turn the picked File into a storable URL."
+      );
+    }
+    const cached = filePersistenceCache.get(file);
+    if (cached) return cached;
+    const pending = Promise.resolve(persist(file)).then(String);
+    filePersistenceCache.set(file, pending);
+    try {
+      return await pending;
+    } catch (error) {
+      filePersistenceCache.delete(file);
+      throw error;
+    }
+  }
+  // ------------------------------------------------------------------ values
+  /**
+   * Current values, keyed by field name.
+   *
+   * Inactive fields (`isActive` returned false) are omitted. The active tab is
+   * always included under `activeTab`.
+   */
+  getValues() {
+    const values = {};
+    for (const field of this.fieldList) {
+      if (!field.contributesValue || !field.isActive()) continue;
+      values[field.name] = field.getValue();
+    }
+    values["activeTab"] = this.tabBar.activeTab;
+    return values;
+  }
+  /** Imperative handle for a field, or `undefined` if there is no such field. */
+  field(name) {
+    return this.fieldsByName.get(name);
+  }
+  /** Every field handle, in declaration order. */
+  get fields() {
+    return this.fieldList;
+  }
+  /** Notified whenever the form's values change. Returns an unsubscribe function. */
+  subscribeOnInput(subscriber) {
+    return this.model.subscribe(subscriber);
+  }
+  // ------------------------------------------------------------------ update
+  /**
+   * 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
+   */
+  async update(source, force = false, includeTab = false) {
+    const values = this.getValues();
+    const changed = this.model.hasChanged(values, includeTab);
+    if (!changed && !force) return;
+    const triggerName = source?.name;
+    const activeTabs = /* @__PURE__ */ new Set();
+    for (const field of this.fieldList) {
+      const ctx = {
+        ...this.contextFor(field.descriptor),
+        data: values,
+        trigger: source
+      };
+      if (field.descriptor.isActive) {
+        const active = field.descriptor.isActive(ctx);
+        field.setActive(active);
+        if (active) for (const tab of field.tabs()) activeTabs.add(tab);
+      } else {
+        field.setActive(true);
+        for (const tab of field.tabs()) activeTabs.add(tab);
+      }
+      field.descriptor.onFormChange?.(ctx);
+      field.onFormUpdate(ctx, triggerName);
+    }
+    this.renderTabs(activeTabs);
+    await this.scheduler.whenSettled();
+    if (changed) this.model.notify(this.getValues());
+    await this.buttonBar.refresh(this.buttonContext());
+  }
+  buttonContext() {
+    return {
+      data: this.getValues(),
+      parentData: this.parent?.getValues(),
+      stackData: this.stack.values()
+    };
+  }
+  /** Recompute every `computed` field. Runs before a button action fires. */
+  async updateComputedFields() {
+    const computed = this.fieldList.filter(
+      (field) => field instanceof ComputedField
+    );
+    await Promise.allSettled(
+      computed.map((field) => this.scheduler.track(field.recompute()))
+    );
+  }
+  // -------------------------------------------------------------------- tabs
+  /** Tabs in declaration order, keeping only those with at least one active field. */
+  renderTabs(activeTabs) {
+    const ordered = [];
+    for (const field of this.fieldList) {
+      for (const tab of field.tabs()) {
+        if (activeTabs.has(tab) && !ordered.includes(tab)) ordered.push(tab);
+      }
+    }
+    this.tabBar.render(ordered);
+    this.applyActiveTab();
+  }
+  /**
+   * 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) {
+    if (tab && !this.tabBar.select(tab)) return;
+    this.applyActiveTab();
+    void this.update(void 0, true, true);
+  }
+  applyActiveTab() {
+    const active = this.tabBar.activeTab;
+    if (!active) return;
+    for (const field of this.fieldList) {
+      const tabs = field.tabs();
+      field.setInTab(tabs.length === 0 || tabs.includes(active));
+    }
+  }
+  /** Re-apply the active tab. Called by the stack when this dialog is revealed. */
+  refreshTabs() {
+    this.applyActiveTab();
+  }
+  // ----------------------------------------------------------------- display
+  /**
+   * Open the form as a modal dialog.
+   *
+   * Returns the outer `.dl-modal` element.
+   */
+  openInModal(options) {
+    this.embedded = false;
+    const view = this.ensureView();
+    view.mount();
+    view.content.appendChild(this.dom);
+    view.setStackDepth(this.stack.size);
+    view.setVisible(true);
+    view.addModalClasses(options?.classNames);
+    view.addWrapperClasses(options?.wrapperClassNames);
+    this.stack.push(this);
+    this.applyActiveTab();
+    return view.wrapper;
+  }
+  /** Render the form inline, inside `host`, instead of as a floating dialog. */
+  appendInElement(host, options) {
+    this.embedded = true;
+    const view = this.ensureView();
+    view.setEmbedded();
+    view.setVisible(true);
+    view.addWrapperClasses(options?.classNames);
+    view.content.appendChild(this.dom);
+    host.appendChild(view.wrapper);
+    void this.whenReady().then(() => this.applyActiveTab());
+    return view.wrapper;
+  }
+  ensureView() {
+    if (this.view) return this.view;
+    this.view = new ModalView({
+      tabBar: this.tabBar,
+      buttonBar: this.buttonBar,
+      onCancel: this.options.onCancel ? () => this.cancel() : void 0
+    });
+    return this.view;
+  }
+  /** The outer `.dl-modal` element, once the form has been displayed. */
+  get modalElement() {
+    return this.view?.wrapper;
+  }
+  hide() {
+    this.view?.hide();
+  }
+  show() {
+    this.view?.show();
+  }
+  /** The form's HTML, for tests and snapshots. */
+  getHTML() {
+    return this.dom.outerHTML;
+  }
+  // ---------------------------------------------------------------- lifecycle
+  get buttonCount() {
+    return this.buttonBar.count;
+  }
+  /**
+   * Run the confirm action and close.
+   *
+   * @param action defaults to the form's `onConfirm`
+   */
+  async close(action) {
+    const callback = action ?? this.options.onConfirm;
+    if (callback) await callback(this.getValues());
+    if (!this.embedded) this.teardownView();
+    this.stack.remove(this);
+  }
+  /** Dismiss the dialog. A no-op when the form has no `onCancel`. */
+  cancel() {
+    if (!this.options.onCancel) return;
+    this.teardownView();
+    this.options.onCancel();
+    this.stack.remove(this);
+  }
+  /** Close without running any callback. */
+  remove() {
+    this.teardownView();
+    this.stack.remove(this);
+  }
+  /** Release tooltips and listeners. Call when discarding an embedded form. */
+  destroy() {
+    this.remove();
+    this.tooltips.destroy();
+    this.scheduler.reset();
+    for (const field of this.fieldList) field.destroy();
+  }
+  teardownView() {
+    this.view?.remove();
+    this.view = void 0;
+  }
+  // -------------------------------------------------------- keyboard (stack)
+  requestCancel() {
+    this.cancel();
+  }
+  /**
+   * 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) {
+    const target = event.target;
+    const field = target?.getAttribute?.("name") ? this.fieldsByName.get(target.getAttribute("name")) : void 0;
+    if (field instanceof TextAreaField) {
+      if (!field.allowsNewlines) {
+        event.preventDefault();
+        event.stopPropagation();
+      }
+      return;
+    }
+    event.preventDefault();
+    event.stopPropagation();
+    if (this.buttonBar.primaryDisabled) return;
+    this.buttonBar.primary?.click();
+  }
+  // ---------------------------------------------------------------- tooltips
+  setTooltip(fieldName, text, icon, className) {
+    this.tooltips.set(fieldName, text, icon, className);
+  }
+  setTooltipSuccess(fieldName, text) {
+    this.tooltips.setSuccess(fieldName, text);
+  }
+  setTooltipWarning(fieldName, text) {
+    this.tooltips.setWarning(fieldName, text);
+  }
+  setTooltipError(fieldName, text) {
+    this.tooltips.setError(fieldName, text);
+  }
+  setTooltipLoading(fieldName, text) {
+    this.tooltips.setLoading(fieldName, text);
+  }
+  resetTooltip(fieldName) {
+    this.tooltips.reset(fieldName);
+  }
+  resetTooltips(fieldNames) {
+    this.tooltips.resetAll(fieldNames);
+  }
+};
+
+export { ArrayField, ButtonBar, CardsField, CheckboxField, ComputedField, CustomField, DL_SELECT_STYLES, DeclarativeForm, DlOption, DlSelect, Field, FieldRegistry, FileField, FormModel, IdGenerator, MessageField, ModalStack, ModalView, NativeTooltipProvider, SafeHtml, SelectField, TabBar, TextAreaField, TextField, TooltipController, UpdateScheduler, deepEqual, defaultFieldRegistry, defineDlSelect, escapeHtml, globalModalStack, html, injectStyles, isSafeHtml };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map