@usefillo/dom 0.11.0 → 0.12.0

package/dist/index.js

@@ -23,6 +23,7 @@ import {
   isFilloError,
   isLikelyDevEnv,
   isValidPartialNumberText,
+  localeForNotation,
   normalizeFormSchema,
   normalizeFormTheme,
   parseGroupedNumber,
@@ -93,11 +94,11 @@ function badgeUrl(href) {
 function inputValue(value) {
   return typeof value === "string" || typeof value === "number" ? String(value) : "";
 }
-function groupedInputValue(value, decimals) {
+function groupedInputValue(value, decimals, locale) {
   const raw = inputValue(value);
   if (raw === "") return raw;
   const n = Number(raw);
-  return Number.isFinite(n) ? formatGroupedNumber(n, { decimals }) : raw;
+  return Number.isFinite(n) ? formatGroupedNumber(n, { locale, decimals }) : raw;
 }
 function appendChildren(parent, children) {
   for (const child of children) {
@@ -126,13 +127,11 @@ function optionIcon(icon) {
   svg.appendChild(path);
   return svg;
 }
-function applyFieldAria(node, field, error, ids) {
+function applyFieldAria(node, field, error, ids, opts = {}) {
   if (error) node.setAttribute("aria-invalid", "true");
-  if (field.required) node.setAttribute("aria-required", "true");
-  const describedBy = [
-    field.description ? ids.descriptionId : null,
-    error ? ids.errorId : null
-  ].filter(Boolean).join(" ");
+  if ((opts.requiredSupported ?? true) && field.required)
+    node.setAttribute("aria-required", "true");
+  const describedBy = [field.description ? ids.descriptionId : null, error ? ids.errorId : null].filter(Boolean).join(" ");
   if (describedBy) node.setAttribute("aria-describedby", describedBy);
 }
 function bindRadioKeys(group, values, current, select) {
@@ -185,7 +184,8 @@ function shell(field, error, child, ids) {
 function textInput(type, context) {
   const field = context.field;
   const numberField = field.kind === "number" ? field : void 0;
-  const grouped = numberField?.notation === "grouped";
+  const grouped = numberField?.notation !== void 0;
+  const locale = localeForNotation(numberField?.notation);
   const formatted = grouped || Boolean(numberField?.prefix) || Boolean(numberField?.suffix);
   const input = el("input", {
     className: "fillo-input",
@@ -194,7 +194,7 @@ function textInput(type, context) {
   if (formatted) input.setAttribute("inputmode", "decimal");
   if (type === "email") input.setAttribute("autocomplete", "email");
   else if (type === "url") input.setAttribute("autocomplete", "url");
-  input.value = grouped ? groupedInputValue(context.value, numberField?.decimals) : inputValue(context.value);
+  input.value = grouped ? groupedInputValue(context.value, numberField?.decimals, locale) : inputValue(context.value);
   if (field.placeholder) input.placeholder = field.placeholder;
   if ("maxLength" in field && field.maxLength !== void 0) {
     input.maxLength = field.maxLength;
@@ -212,31 +212,31 @@ function textInput(type, context) {
     };
     if (grouped) {
       input.addEventListener("input", () => {
-        if (!isValidPartialNumberText(input.value)) return rejectEdit();
+        if (!isValidPartialNumberText(input.value, locale)) return rejectEdit();
         lastValid = input.value;
         lastCaret = input.selectionStart ?? input.value.length;
-        context.setValue(parseGroupedNumber(input.value), { render: false });
+        context.setValue(parseGroupedNumber(input.value, locale), { render: false });
       });
       input.addEventListener("change", () => {
-        if (!isValidPartialNumberText(input.value)) return rejectEdit();
+        if (!isValidPartialNumberText(input.value, locale)) return rejectEdit();
         lastValid = input.value;
-        context.setValue(parseGroupedNumber(input.value));
+        context.setValue(parseGroupedNumber(input.value, locale));
       });
       input.addEventListener("blur", () => {
         const live = context.getValue?.() ?? context.value;
-        input.value = groupedInputValue(live, numberField?.decimals);
+        input.value = groupedInputValue(live, numberField?.decimals, locale);
         lastValid = input.value;
         lastCaret = input.value.length;
       });
     } else {
       input.addEventListener("input", () => {
-        if (!isValidPartialNumberText(input.value)) return rejectEdit();
+        if (!isValidPartialNumberText(input.value, locale)) return rejectEdit();
         lastValid = input.value;
         lastCaret = input.selectionStart ?? input.value.length;
         context.setValue(input.value, { render: false });
       });
       input.addEventListener("change", () => {
-        if (!isValidPartialNumberText(input.value)) return rejectEdit();
+        if (!isValidPartialNumberText(input.value, locale)) return rejectEdit();
         lastValid = input.value;
         context.setValue(input.value);
       });
@@ -293,7 +293,10 @@ function phoneInput(context) {
     className: "fillo-phone-flag",
     attrs: { type: "button", "aria-haspopup": "listbox", "aria-expanded": "false" }
   });
-  const flagSpan = el("span", { className: "fillo-phone-flag-emoji", attrs: { "aria-hidden": "true" } });
+  const flagSpan = el("span", {
+    className: "fillo-phone-flag-emoji",
+    attrs: { "aria-hidden": "true" }
+  });
   const dialSpan = el("span", { className: "fillo-phone-dial" });
   appendChildren(flagBtn, [
     flagSpan,
@@ -449,10 +452,18 @@ function phoneInput(context) {
       matches.forEach((c, i) => {
         const li = el("li", {
           className: `fillo-phone-option${i === active ? " fillo-phone-option--active" : ""}`,
-          attrs: { id: `${listId}-opt-${i}`, role: "option", "aria-selected": String(c.iso2 === country.iso2) }
+          attrs: {
+            id: `${listId}-opt-${i}`,
+            role: "option",
+            "aria-selected": String(c.iso2 === country.iso2)
+          }
         });
         appendChildren(li, [
-          el("span", { className: "fillo-phone-flag-emoji", text: flagEmoji(c.iso2), attrs: { "aria-hidden": "true" } }),
+          el("span", {
+            className: "fillo-phone-flag-emoji",
+            text: flagEmoji(c.iso2),
+            attrs: { "aria-hidden": "true" }
+          }),
           el("span", { className: "fillo-phone-option-name", text: c.name }),
           el("span", { className: "fillo-phone-option-dial", text: `+${c.dialCode}` })
         ]);
@@ -587,7 +598,10 @@ function singleChoice(context) {
       attrs: { "data-option": option.id, "data-fillo": "option" }
     });
     label.toggleAttribute("data-selected", value === option.id);
-    const input = el("input", { className: "fillo-option-input", attrs: { type: "radio", name: context.ids.name } });
+    const input = el("input", {
+      className: "fillo-option-input",
+      attrs: { type: "radio", name: context.ids.name }
+    });
     input.checked = value === option.id;
     input.addEventListener("change", () => {
       activeOtherFields?.delete(field.id);
@@ -596,12 +610,20 @@ function singleChoice(context) {
     appendChildren(label, [
       input,
       optionIcon(option.icon),
-      el("span", { className: "fillo-option-label", text: option.label, attrs: { "data-fillo": "optionLabel" } }),
+      el("span", {
+        className: "fillo-option-label",
+        text: option.label,
+        attrs: { "data-fillo": "optionLabel" }
+      }),
       // Icon-mode hides the native input visually (CSS), so an SVG recolor
       // was the only selected-state signal — add a decorative shape signal
       // that survives forced-colors (audit P1.2; state still lives on the
       // input, this marker is non-authoritative).
-      option.icon && value === option.id ? el("span", { className: "fillo-option-check", text: "\u2713", attrs: { "aria-hidden": "true" } }) : null
+      option.icon && value === option.id ? el("span", {
+        className: "fillo-option-check",
+        text: "\u2713",
+        attrs: { "aria-hidden": "true" }
+      }) : null
     ]);
     wrap.appendChild(label);
   }
@@ -611,7 +633,10 @@ function singleChoice(context) {
       attrs: { "data-fillo": "option" }
     });
     label.toggleAttribute("data-selected", otherActive);
-    const input = el("input", { className: "fillo-option-input", attrs: { type: "radio", name: context.ids.name } });
+    const input = el("input", {
+      className: "fillo-option-input",
+      attrs: { type: "radio", name: context.ids.name }
+    });
     input.checked = otherActive;
     input.addEventListener("change", () => {
       activeOtherFields?.add(field.id);
@@ -620,7 +645,11 @@ function singleChoice(context) {
     appendChildren(label, [
       appendChildren(el("span", { className: "fillo-option-main" }), [
         input,
-        el("span", { className: "fillo-option-label", text: DEFAULT_STRINGS.other, attrs: { "data-fillo": "optionLabel" } })
+        el("span", {
+          className: "fillo-option-label",
+          text: DEFAULT_STRINGS.other,
+          attrs: { "data-fillo": "optionLabel" }
+        })
       ])
     ]);
     if (otherActive) {
@@ -660,7 +689,7 @@ function multiChoice(context) {
     className: "fillo-options",
     attrs: { role: "group", "aria-labelledby": context.ids.labelId, "data-fillo": "options" }
   });
-  applyFieldAria(wrap, field, context.error, context.ids);
+  applyFieldAria(wrap, field, context.error, context.ids, { requiredSupported: false });
   const setSelected = (next) => context.setValue(next);
   for (const option of options) {
     const label = el("label", {
@@ -672,13 +701,23 @@ function multiChoice(context) {
     input.checked = selected.includes(option.id);
     input.addEventListener("change", () => {
       const current = getSelected();
-      setSelected(input.checked ? [...current, option.id] : current.filter((id) => id !== option.id));
+      setSelected(
+        input.checked ? [...current, option.id] : current.filter((id) => id !== option.id)
+      );
     });
     appendChildren(label, [
       input,
       optionIcon(option.icon),
-      el("span", { className: "fillo-option-label", text: option.label, attrs: { "data-fillo": "optionLabel" } }),
-      option.icon && selected.includes(option.id) ? el("span", { className: "fillo-option-check", text: "\u2713", attrs: { "aria-hidden": "true" } }) : null
+      el("span", {
+        className: "fillo-option-label",
+        text: option.label,
+        attrs: { "data-fillo": "optionLabel" }
+      }),
+      option.icon && selected.includes(option.id) ? el("span", {
+        className: "fillo-option-check",
+        text: "\u2713",
+        attrs: { "aria-hidden": "true" }
+      }) : null
     ]);
     wrap.appendChild(label);
   }
@@ -704,7 +743,11 @@ function multiChoice(context) {
     appendChildren(label, [
       appendChildren(el("span", { className: "fillo-option-main" }), [
         input,
-        el("span", { className: "fillo-option-label", text: DEFAULT_STRINGS.other, attrs: { "data-fillo": "optionLabel" } })
+        el("span", {
+          className: "fillo-option-label",
+          text: DEFAULT_STRINGS.other,
+          attrs: { "data-fillo": "optionLabel" }
+        })
       ])
     ]);
     if (active) {
@@ -750,11 +793,16 @@ function dropdown(context) {
     className: "fillo-input fillo-select",
     attrs: { id: context.ids.inputId, "data-fillo": "control" }
   });
-  select.appendChild(el("option", { text: field.placeholder ?? "Choose...", attrs: { value: "" } }));
+  select.appendChild(
+    el("option", { text: field.placeholder ?? "Choose...", attrs: { value: "" } })
+  );
   for (const option of displayOptions(field)) {
     select.appendChild(el("option", { text: option.label, attrs: { value: option.id } }));
   }
-  if (field.allowOther) select.appendChild(el("option", { text: `${DEFAULT_STRINGS.other}\u2026`, attrs: { value: other } }));
+  if (field.allowOther)
+    select.appendChild(
+      el("option", { text: `${DEFAULT_STRINGS.other}\u2026`, attrs: { value: other } })
+    );
   select.value = otherActive ? other : value;
   select.addEventListener("change", () => {
     if (select.value === other) {
@@ -766,7 +814,10 @@ function dropdown(context) {
     }
   });
   applyFieldAria(select, field, context.error, context.ids);
-  appendChildren(selectWrap, [select, el("span", { className: "fillo-select-icon", attrs: { "aria-hidden": "true" } })]);
+  appendChildren(selectWrap, [
+    select,
+    el("span", { className: "fillo-select-icon", attrs: { "aria-hidden": "true" } })
+  ]);
   wrap.appendChild(selectWrap);
   if (otherActive) {
     const other2 = el("input", {
@@ -826,9 +877,10 @@ function checkbox(context) {
     appendChildren(label2, [
       copy,
       input2,
-      appendChildren(el("span", { className: "fillo-toggle-track", attrs: { "aria-hidden": "true" } }), [
-        el("span", { className: "fillo-toggle-thumb" })
-      ])
+      appendChildren(
+        el("span", { className: "fillo-toggle-track", attrs: { "aria-hidden": "true" } }),
+        [el("span", { className: "fillo-toggle-thumb" })]
+      )
     ]);
     wrap2.appendChild(label2);
     if (context.field.description)
@@ -1013,7 +1065,7 @@ function ranking(context) {
       "data-fillo": "control"
     }
   });
-  applyFieldAria(group, context.field, context.error, context.ids);
+  applyFieldAria(group, context.field, context.error, context.ids, { requiredSupported: false });
   const list = el("ol", { className: "fillo-ranking" });
   for (const [index, id] of order.entries()) {
     const option = field.options.find((item2) => item2.id === id);
@@ -1072,8 +1124,9 @@ function matrix(context) {
   const table = el("table", { className: "fillo-matrix" });
   const thead = document.createElement("thead");
   const headRow = document.createElement("tr");
-  headRow.appendChild(document.createElement("th"));
-  for (const col of field.columns) headRow.appendChild(el("th", { text: col.label, attrs: { scope: "col" } }));
+  headRow.appendChild(document.createElement("td"));
+  for (const col of field.columns)
+    headRow.appendChild(el("th", { text: col.label, attrs: { scope: "col" } }));
   thead.appendChild(headRow);
   table.appendChild(thead);
   const tbody = document.createElement("tbody");
@@ -1126,7 +1179,7 @@ function matrix(context) {
       "data-fillo": "control"
     }
   });
-  applyFieldAria(group, context.field, context.error, context.ids);
+  applyFieldAria(group, context.field, context.error, context.ids, { requiredSupported: false });
   group.appendChild(table);
   return shell(context.field, context.error, group, context.ids);
 }
@@ -1142,7 +1195,11 @@ function signature(context) {
     text: "Clear",
     attrs: { type: "button" }
   });
-  const hint = el("div", { className: "fillo-signature-hint", text: "Sign here", attrs: { "aria-hidden": "true" } });
+  const hint = el("div", {
+    className: "fillo-signature-hint",
+    text: "Sign here",
+    attrs: { "aria-hidden": "true" }
+  });
   canvas.width = 720;
   canvas.height = 220;
   const ctx = canvas.getContext("2d");
@@ -1258,29 +1315,87 @@ function fileUpload(context) {
   const field = context.field;
   if (field.kind !== "file_upload") return null;
   const internal = context;
-  const storageBlocked = internal.storageBlocked === true;
-  const input = el("input", {
-    className: "fillo-input",
-    attrs: { id: context.ids.inputId, type: "file", "data-fillo": "control" }
-  });
-  if ((field.maxFiles ?? 1) > 1) input.multiple = true;
-  if (field.accept?.length) input.accept = field.accept.join(",");
-  input.disabled = storageBlocked;
-  applyFieldAria(input, field, context.error, context.ids);
-  input.addEventListener("change", () => {
-    if (storageBlocked) return;
-    const files = Array.from(input.files ?? []);
-    input.value = "";
-    void context.uploadFiles?.(field, files);
-  });
+  const uploadDisabledReason = internal.uploadDisabledReason;
+  const canUpload = uploadDisabledReason === void 0;
+  const maxFiles = field.maxFiles ?? 1;
+  const maxMb = field.maxFileSizeMb ?? 500;
+  const done = Array.isArray(context.value) ? context.value : [];
+  const rows = internal.uploadRows ?? [];
+  const remaining = maxFiles - done.length - rows.filter((row) => row.error === void 0).length;
   const wrap = el("div");
-  wrap.appendChild(input);
-  if (storageBlocked) {
-    const hint = el("p", {
-      className: "fillo-upload-notice",
-      text: internal.storageFixUrl ? "Connect file storage to enable uploads" : DEFAULT_FIELD_STRINGS.uploadsUnavailable
+  if (remaining > 0) {
+    const input = el("input", {
+      className: "fillo-input",
+      attrs: { id: context.ids.inputId, type: "file", hidden: "" }
+    });
+    if (maxFiles > 1) input.multiple = true;
+    if (field.accept?.length) input.accept = field.accept.join(",");
+    input.disabled = !canUpload;
+    input.addEventListener("change", () => {
+      if (!canUpload) return;
+      const files = Array.from(input.files ?? []);
+      input.value = "";
+      void context.uploadFiles?.(field, files);
+    });
+    const dropzone = el("div", {
+      className: `fillo-dropzone${canUpload ? "" : " fillo-dropzone--disabled"}`,
+      attrs: {
+        role: "button",
+        tabindex: "0",
+        "aria-labelledby": context.ids.labelId,
+        "data-fillo": "control"
+      }
+    });
+    applyFieldAria(dropzone, field, context.error, context.ids, { requiredSupported: false });
+    if (!canUpload) dropzone.setAttribute("aria-disabled", "true");
+    dropzone.addEventListener("dragover", (e) => {
+      e.preventDefault();
+      dropzone.classList.add("fillo-dropzone--over");
+      dropzone.setAttribute("data-drag-over", "");
+    });
+    dropzone.addEventListener("dragleave", () => {
+      dropzone.classList.remove("fillo-dropzone--over");
+      dropzone.removeAttribute("data-drag-over");
+    });
+    dropzone.addEventListener("drop", (e) => {
+      e.preventDefault();
+      dropzone.classList.remove("fillo-dropzone--over");
+      dropzone.removeAttribute("data-drag-over");
+      if (canUpload) void context.uploadFiles?.(field, Array.from(e.dataTransfer?.files ?? []));
     });
-    if (internal.storageFixUrl) {
+    dropzone.addEventListener("click", () => {
+      if (canUpload) input.click();
+    });
+    dropzone.addEventListener("keydown", (e) => {
+      if (e.key === "Enter" || e.key === " ") {
+        e.preventDefault();
+        if (canUpload) input.click();
+      }
+    });
+    dropzone.appendChild(input);
+    if (canUpload) {
+      appendChildren(dropzone, [
+        el("span", {
+          className: "fillo-dropzone-title",
+          text: DEFAULT_FIELD_STRINGS.dropzoneTitle(maxFiles > 1)
+        }),
+        el("span", {
+          className: "fillo-dropzone-hint",
+          text: DEFAULT_FIELD_STRINGS.dropzoneHint(maxMb)
+        })
+      ]);
+    } else if (uploadDisabledReason === "render_only") {
+      dropzone.appendChild(
+        el("span", {
+          className: "fillo-dropzone-hint",
+          text: DEFAULT_FIELD_STRINGS.uploadsRenderOnly
+        })
+      );
+    } else if (internal.storageFixUrl) {
+      const hint = el("span", {
+        className: "fillo-dropzone-hint",
+        text: "Connect file storage to enable uploads"
+      });
       hint.append(" \u2014 ");
       hint.appendChild(
         el("a", {
@@ -1288,13 +1403,17 @@ function fileUpload(context) {
           attrs: { href: internal.storageFixUrl, target: "_blank", rel: "noopener noreferrer" }
         })
       );
+      dropzone.appendChild(hint);
+    } else {
+      dropzone.appendChild(
+        el("span", {
+          className: "fillo-dropzone-hint",
+          text: DEFAULT_FIELD_STRINGS.uploadsUnavailable
+        })
+      );
     }
-    wrap.appendChild(hint);
+    wrap.appendChild(dropzone);
   }
-  const done = Array.isArray(context.value) ? context.value : [];
-  const rows = internal.uploadRows ?? [];
-  const maxFiles = field.maxFiles ?? 1;
-  const remaining = maxFiles - done.length - rows.filter((row) => row.error === void 0).length;
   if (done.length > 0 || rows.length > 0) {
     const list = el("ul", { className: "fillo-files" });
     for (const file of done) {
@@ -1326,9 +1445,9 @@ function fileUpload(context) {
       });
       li.appendChild(el("span", { className: "fillo-file-name", text: row.name }));
       if (failed) {
-        li.appendChild(el("span", { className: "fillo-file-meta", text: row.error ?? "" }));
+        const actions = el("span", { className: "fillo-file-actions" });
         if (remaining > 0) {
-          li.appendChild(
+          actions.appendChild(
             fileActionBtn(
               "fillo-file-retry",
               `${DEFAULT_FIELD_STRINGS.uploadRetry} ${row.name}`,
@@ -1337,14 +1456,34 @@ function fileUpload(context) {
             )
           );
         }
-        li.appendChild(fileActionBtn("fillo-file-remove", "Dismiss", "\xD7", () => internal.uploadAction?.(row.key, "dismiss")));
+        actions.appendChild(
+          fileActionBtn(
+            "fillo-file-remove",
+            "Dismiss",
+            "\xD7",
+            () => internal.uploadAction?.(row.key, "dismiss")
+          )
+        );
+        li.appendChild(actions);
+        li.appendChild(el("span", { className: "fillo-file-error", text: row.error ?? "" }));
       } else {
         const bar = el("span", { className: "fillo-progress-bar" });
         bar.style.width = `${row.fraction * 100}%`;
         appendChildren(li, [
-          el("span", { className: "fillo-file-meta", text: `${Math.round(row.fraction * 100)}% of ${formatBytes(row.size)}` }),
-          appendChildren(el("span", { className: "fillo-progress", attrs: { "aria-hidden": "true" } }), [bar]),
-          fileActionBtn("fillo-file-remove", `Cancel ${row.name}`, "\xD7", () => internal.uploadAction?.(row.key, "cancel"))
+          el("span", {
+            className: "fillo-file-meta",
+            text: `${Math.round(row.fraction * 100)}% of ${formatBytes(row.size)}`
+          }),
+          fileActionBtn(
+            "fillo-file-remove",
+            `Cancel ${row.name}`,
+            "\xD7",
+            () => internal.uploadAction?.(row.key, "cancel")
+          ),
+          appendChildren(
+            el("span", { className: "fillo-progress", attrs: { "aria-hidden": "true" } }),
+            [bar]
+          )
         ]);
       }
       list.appendChild(li);
@@ -1596,7 +1735,7 @@ var DomFormController = class {
     return {
       form,
       formId: this.formId,
-      client: this.options.client,
+      client: this.options.renderOnly ? void 0 : this.options.client,
       data: state?.data ?? this.mutableData,
       errors: state?.errors ?? {},
       status: this.status,
@@ -1640,9 +1779,14 @@ var DomFormController = class {
   resolutionFailureCode = null;
   async resolve() {
     try {
-      this.challenge = this.options.challenge;
+      this.challenge = this.options.renderOnly ? void 0 : this.options.challenge;
       const codeForm = isCodeForm(this.options.form) ? this.options.form : null;
       if (codeForm) {
+        if (this.options.renderOnly) {
+          this.setSchema(codeForm.schema, this.options.theme ?? codeForm.theme, void 0);
+          return;
+        }
+        if (!this.options.client && this.options.formId) this.options.client = createClient();
         const client = this.options.client;
         if (client?.key) {
           this.resolveFormIdFn = async () => {
@@ -1687,12 +1831,7 @@ var DomFormController = class {
               }
               if (result.syncError) {
                 this.reportSyncNotice(
-                  new FilloError(
-                    result.syncError.message,
-                    403,
-                    void 0,
-                    result.syncError.code
-                  )
+                  new FilloError(result.syncError.message, 403, void 0, result.syncError.code)
                 );
               }
               this.resolutionFailureCode = null;
@@ -1705,8 +1844,16 @@ var DomFormController = class {
             }
           };
         }
-        if (!client?.key) {
-          this.setSchema(codeForm.schema, this.options.theme ?? codeForm.theme, this.options.formId);
+        if (!client?.key && this.options.formId) {
+          this.setSchema(
+            codeForm.schema,
+            this.options.theme ?? codeForm.theme,
+            this.options.formId
+          );
+        }
+        if (!client && !this.options.formId) {
+          this.genericUnavailable = !this.devChrome();
+          throw formTargetRequiredError();
         }
         if (client && !client.key && !this.options.formId) {
           this.reportSyncFailure(
@@ -1721,7 +1868,11 @@ var DomFormController = class {
         }
         if (!client?.key) return;
         if (this.devChrome()) {
-          this.setSchema(codeForm.schema, this.options.theme ?? codeForm.theme, this.options.formId);
+          this.setSchema(
+            codeForm.schema,
+            this.options.theme ?? codeForm.theme,
+            this.options.formId
+          );
         } else {
           this.theme = this.options.theme ?? codeForm.theme;
           this.render();
@@ -1763,19 +1914,18 @@ var DomFormController = class {
           if (result.warning) console.warn(`[fillo] ${result.warning}`);
           if (result.syncError) {
             this.reportSyncNotice(
-              new FilloError(
-                result.syncError.message,
-                403,
-                void 0,
-                result.syncError.code
-              )
+              new FilloError(result.syncError.message, 403, void 0, result.syncError.code)
             );
           }
           const connectStorage = result.warningUrl ? ` \u2014 connect storage to publish: ${result.warningUrl}` : "";
           if (result.staged) {
-            console.info(`[fillo] "${codeForm.id}" changes staged as a draft \u2014 rendering the live version until you publish them in your Fillo dashboard${connectStorage}`);
+            console.info(
+              `[fillo] "${codeForm.id}" changes staged as a draft \u2014 rendering the live version until you publish them in your Fillo dashboard${connectStorage}`
+            );
           } else if (result.status === "draft") {
-            console.info(`[fillo] "${codeForm.id}" is a draft \u2014 it renders here but won't accept responses until published${connectStorage}`);
+            console.info(
+              `[fillo] "${codeForm.id}" is a draft \u2014 it renders here but won't accept responses until published${connectStorage}`
+            );
           }
         } catch (error) {
           if (this.destroyed) return;
@@ -1785,6 +1935,15 @@ var DomFormController = class {
       }
       const schema = this.options.form && !isCodeForm(this.options.form) ? this.options.form : null;
       if (schema) {
+        if (this.options.renderOnly) {
+          this.setSchema(schema, this.options.theme, void 0);
+          return;
+        }
+        if (!this.options.formId) {
+          this.genericUnavailable = !this.devChrome();
+          throw formTargetRequiredError();
+        }
+        this.options.client ??= createClient();
         this.setSchema(schema, this.options.theme, this.options.formId);
         return;
       }
@@ -1813,7 +1972,11 @@ var DomFormController = class {
         this.render(this.fatalError);
         return;
       }
-      this.setSchema(published.schema, this.options.theme ?? published.theme ?? void 0, published.id);
+      this.setSchema(
+        published.schema,
+        this.options.theme ?? published.theme ?? void 0,
+        published.id
+      );
     } catch (error) {
       if (this.destroyed) return;
       this.handleError(toFilloError(error));
@@ -1823,31 +1986,35 @@ var DomFormController = class {
   setSchema(schema, theme, formId) {
     if (this.destroyed) return;
     const normalized = normalizeFormSchema(schema);
-    if (!normalized.ok) throw new FilloError(`This form could not be rendered: ${normalized.error}`, 422);
+    if (!normalized.ok)
+      throw new FilloError(`This form could not be rendered: ${normalized.error}`, 422);
     const normalizedSchema = normalized.schema;
     this.schema = normalizedSchema;
     this.theme = theme;
-    this.formId = formId;
+    const renderOnly = this.options.renderOnly === true;
+    this.formId = renderOnly ? void 0 : formId;
     const displayOnly = this.notOpenVariant !== null;
+    const transportDisabled = displayOnly || renderOnly;
     this.engine = coreCreateFormController({
       form: normalizedSchema,
-      formId: displayOnly ? void 0 : formId,
-      client: displayOnly ? void 0 : this.options.client,
+      formId: transportDisabled ? void 0 : formId,
+      client: transportDisabled ? void 0 : this.options.client,
       initialData: this.options.initialData,
       onChange: displayOnly ? void 0 : this.options.onChange,
-      onSubmitted: displayOnly ? void 0 : this.options.onSubmitted,
+      onSubmitted: transportDisabled ? void 0 : this.options.onSubmitted,
       getHoneypot: () => this.element.querySelector('input[name="fillo_hp_field"]')?.value ?? this.hpValue,
       surface: "default",
-      resolveFormId: displayOnly ? void 0 : this.resolveFormIdFn,
+      resolveFormId: transportDisabled ? void 0 : this.resolveFormIdFn,
+      skipValidation: renderOnly,
       // Dev chrome gets the developer-grade resolution failure (message +
       // machine code) instead of the respondent-safe "unavailable" fallback.
       verboseResolutionErrors: this.devChrome(),
-      respondent: displayOnly ? void 0 : this.options.respondent,
+      respondent: transportDisabled ? void 0 : this.options.respondent,
       // Challenge (Turnstile) — wired as react's useFilloController wires the
       // core controller: challengeRequired captured once here (forced off for
       // a not-open preview, which never submits regardless);
       // getChallengeToken/onChallengeFailed stay live via `this`.
-      challengeRequired: displayOnly ? false : Boolean(this.challenge),
+      challengeRequired: transportDisabled ? false : Boolean(this.challenge),
       getChallengeToken: () => this.challengeToken,
       onChallengeFailed: () => this.resetChallengeWidget()
     });
@@ -1866,7 +2033,7 @@ var DomFormController = class {
         this.queueRender();
       }
     });
-    if (!displayOnly) this.configureDraftFlush(normalizedSchema);
+    if (!transportDisabled) this.configureDraftFlush(normalizedSchema);
     this.phase = this.closed ? "closed" : "ready";
     this.render();
   }
@@ -1982,13 +2149,21 @@ var DomFormController = class {
    *  (it must not strand the field at permanently-full). */
   fieldActive(fieldId) {
     let n = 0;
-    for (const row of this.inFlight.values()) if (row.fieldId === fieldId && row.error === void 0) n++;
+    for (const row of this.inFlight.values())
+      if (row.fieldId === fieldId && row.error === void 0) n++;
     return n;
   }
   uploadRowsFor(fieldId) {
     const rows = [];
     for (const [key, row] of this.inFlight) {
-      if (row.fieldId === fieldId) rows.push({ key, name: row.name, size: row.size, fraction: row.fraction, error: row.error });
+      if (row.fieldId === fieldId)
+        rows.push({
+          key,
+          name: row.name,
+          size: row.size,
+          fraction: row.fraction,
+          error: row.error
+        });
     }
     return rows;
   }
@@ -2013,7 +2188,15 @@ var DomFormController = class {
   async startUpload(fieldId, file, maxFiles) {
     const key = `${file.name}-${file.size}-${Date.now()}-${Math.random().toString(36).slice(2, 7)}`;
     const controller = new AbortController();
-    this.inFlight.set(key, { fieldId, name: file.name, size: file.size, fraction: 0, file, controller, maxFiles });
+    this.inFlight.set(key, {
+      fieldId,
+      name: file.name,
+      size: file.size,
+      fraction: 0,
+      file,
+      controller,
+      maxFiles
+    });
     this.engine?.setUploading(fieldId, true);
     this.queueRender();
     try {
@@ -2124,7 +2307,8 @@ var DomFormController = class {
       this.teardownTurnstileWidget();
       this.turnstileSiteKey = siteKey;
     }
-    if (this.turnstileWidgetId !== null || this.turnstileLoadInFlight || this.challengeError) return;
+    if (this.turnstileWidgetId !== null || this.turnstileLoadInFlight || this.challengeError)
+      return;
     this.turnstileLoadInFlight = true;
     const attempt = ++this.turnstileAttempt;
     loadTurnstileScript().then(() => {
@@ -2227,7 +2411,9 @@ var DomFormController = class {
       const buttons = Array.from(
         this.element.querySelectorAll("[data-fillo-rank-opt]")
       ).filter((b) => b.getAttribute("data-fillo-rank-opt") === desc.rankOpt);
-      target = buttons.find((b) => b.getAttribute("data-fillo-rank-dir") === desc.rankDir && !b.disabled) ?? buttons.find((b) => !b.disabled) ?? null;
+      target = buttons.find(
+        (b) => b.getAttribute("data-fillo-rank-dir") === desc.rankDir && !b.disabled
+      ) ?? buttons.find((b) => !b.disabled) ?? null;
     }
     if (!target && desc.id) target = document.getElementById(desc.id);
     if (!target && desc.fieldId != null && desc.controlIndex != null && desc.controlIndex >= 0) {
@@ -2311,13 +2497,26 @@ var DomFormController = class {
     );
     this.syncErrorNotice = error;
   }
+  // A macrotask, not a microtask (ledger #4, docs/decisions/input-quality.md):
+  // a text field's blur fires "change" -> setValue -> this full-tree rebuild,
+  // and if the respondent's next action is a pointer click elsewhere (e.g. a
+  // rating star), that click is a SEPARATE, later task from the blur's — but
+  // a microtask always drains before any later task runs, including that
+  // click. A microtask-deferred rebuild still replaces the click's target
+  // node before the click is dispatched, so Chromium/WebKit never fire it at
+  // all (the click is silently swallowed — click doesn't fire when the
+  // mousedown target was detached before mouseup: w3c/uievents#141).
+  // setTimeout is the standard fix for exactly this "blur beats click" race:
+  // scheduled during the blur's own task, it reliably runs BEHIND whatever
+  // pointer/click tasks were already in flight for the same gesture, so an
+  // in-flight click lands on the pre-rebuild node first.
   queueRender() {
     if (this.renderQueued || this.destroyed) return;
     this.renderQueued = true;
-    queueMicrotask(() => {
+    setTimeout(() => {
       this.renderQueued = false;
       this.render();
-    });
+    }, 0);
   }
   render(error) {
     if (this.destroyed) return;
@@ -2344,12 +2543,16 @@ var DomFormController = class {
     }
     const activeError = error ?? this.fatalError;
     if (this.phase === "error" && activeError) {
+      const targetMessage = activeError.code === "form_target_required" && this.devChrome() ? `${activeError.message} (${activeError.code})` : null;
       const errorView = this.options.renderError?.(activeError) ?? el("div", {
         className: "fillo-form fillo-form--error",
-        text: this.genericUnavailable ? "This form is unavailable." : loadFailureMessage(activeError)
+        text: targetMessage ?? (this.genericUnavailable ? "This form is unavailable." : loadFailureMessage(activeError))
       });
       if (!errorView.hasAttribute("data-fillo")) errorView.setAttribute("data-fillo", "root");
       if (!errorView.hasAttribute("data-state")) errorView.setAttribute("data-state", "error");
+      if (activeError.code && !errorView.hasAttribute("data-error-code")) {
+        errorView.setAttribute("data-error-code", activeError.code);
+      }
       if (!errorView.hasAttribute("role")) errorView.setAttribute("role", "alert");
       themeStyle(errorView, this.theme);
       this.element.appendChild(errorView);
@@ -2361,13 +2564,16 @@ var DomFormController = class {
         attrs: { "data-fillo": "root", "data-state": "closed" }
       });
       themeStyle(closed, this.theme);
-      closed.appendChild(el("p", { className: "fillo-closed", text: "This form is no longer accepting responses." }));
+      closed.appendChild(
+        el("p", { className: "fillo-closed", text: "This form is no longer accepting responses." })
+      );
       this.element.appendChild(closed);
       return;
     }
     if (this.notOpenVariant && this.schema) {
       this.element.appendChild(this.renderNotOpen(this.notOpenVariant));
-      if (this.brandingVisible()) this.element.appendChild(poweredByEl(this.fetchedBrandLabel, this.fetchedBrandHref));
+      if (this.brandingVisible())
+        this.element.appendChild(poweredByEl(this.fetchedBrandLabel, this.fetchedBrandHref));
       return;
     }
     if (!this.schema) return;
@@ -2376,11 +2582,15 @@ var DomFormController = class {
       const state = this.engine.getState();
       const success = this.options.renderSuccess?.(api) ?? defaultSuccess(this.schema);
       success.setAttribute("data-fillo", success.getAttribute("data-fillo") ?? "root");
+      if (this.formId && !success.hasAttribute("data-fillo-form-id")) {
+        success.setAttribute("data-fillo-form-id", this.formId);
+      }
       success.setAttribute("data-state", success.getAttribute("data-state") ?? "submitted");
       if (!success.hasAttribute("tabindex")) success.setAttribute("tabindex", "-1");
       themeStyle(success, this.theme);
       this.element.appendChild(success);
-      if (this.brandingVisible()) this.element.appendChild(poweredByEl(this.fetchedBrandLabel, this.fetchedBrandHref));
+      if (this.brandingVisible())
+        this.element.appendChild(poweredByEl(this.fetchedBrandLabel, this.fetchedBrandHref));
       if (!state.restoredSubmission && !this.liveSubmissionHandled) {
         this.liveSubmissionHandled = true;
         const redirect = safeHttpUrl(this.schema.settings.redirectUrl);
@@ -2402,12 +2612,13 @@ var DomFormController = class {
           staged: this.stagedNotice,
           draft: this.draftNotice,
           warningUrl: this.syncWarningUrl,
-          noClient: !this.options.client
+          noClient: !this.options.client && !this.options.renderOnly
         })
       );
     }
     this.element.appendChild(this.renderForm());
-    if (this.brandingVisible()) this.element.appendChild(poweredByEl(this.fetchedBrandLabel, this.fetchedBrandHref));
+    if (this.brandingVisible())
+      this.element.appendChild(poweredByEl(this.fetchedBrandLabel, this.fetchedBrandHref));
     this.applyFocus(intent, captured);
   }
   /** Server-driven and not client-removable; defaults on until the server says. */
@@ -2465,6 +2676,7 @@ var DomFormController = class {
         "data-page": String(api.pageIndex + 1)
       }
     });
+    if (!displayOnly && this.formId) form.setAttribute("data-fillo-form-id", this.formId);
     form.toggleAttribute("data-last-page", api.isLastPage);
     themeStyle(form, this.theme);
     const advance = () => {
@@ -2532,7 +2744,11 @@ var DomFormController = class {
       const header = el("header", { className: "fillo-header", attrs: { "data-fillo": "header" } });
       if (api.form.title) {
         header.appendChild(
-          el("h1", { className: "fillo-title", text: api.form.title, attrs: { "data-fillo": "title" } })
+          el("h1", {
+            className: "fillo-title",
+            text: api.form.title,
+            attrs: { "data-fillo": "title" }
+          })
         );
       }
       if (api.form.description) {
@@ -2563,7 +2779,16 @@ var DomFormController = class {
     }
     content.appendChild(blocks);
     if (!displayOnly) {
-      const hp = el("input", { className: "fillo-hp", attrs: { type: "text", name: "fillo_hp_field", tabindex: "-1", autocomplete: "off", "aria-hidden": "true" } });
+      const hp = el("input", {
+        className: "fillo-hp",
+        attrs: {
+          type: "text",
+          name: "fillo_hp_field",
+          tabindex: "-1",
+          autocomplete: "off",
+          "aria-hidden": "true"
+        }
+      });
       hp.style.position = "absolute";
       hp.style.left = "-9999px";
       hp.style.top = "auto";
@@ -2599,12 +2824,19 @@ var DomFormController = class {
     }
     const submitError = api.status === "error" ? "This form can't submit right now. Please try again in a moment." : this.engine?.getState().submitError;
     if (submitError) {
-      const alert = el("p", { className: "fillo-submit-error", attrs: { role: "alert" }, text: submitError });
+      const alert = el("p", {
+        className: "fillo-submit-error",
+        attrs: { role: "alert" },
+        text: submitError
+      });
       const fixUrl = this.devChrome() && this.resolutionFailureCode === "form_not_published" && this.syncWarningCode === "storage_required" ? safeHttpUrl(this.syncWarningUrl) : null;
       if (fixUrl) {
         alert.append(" Connect storage: ");
         alert.appendChild(
-          el("a", { text: fixUrl, attrs: { href: fixUrl, target: "_blank", rel: "noopener noreferrer" } })
+          el("a", {
+            text: fixUrl,
+            attrs: { href: fixUrl, target: "_blank", rel: "noopener noreferrer" }
+          })
         );
       }
       content.appendChild(alert);
@@ -2659,7 +2891,10 @@ var DomFormController = class {
       attrs: { role: "alert", tabindex: "-1", "data-fillo": "error-summary" }
     });
     box.appendChild(
-      el("p", { className: "fillo-error-summary-title", text: DEFAULT_FIELD_STRINGS.errorSummaryTitle })
+      el("p", {
+        className: "fillo-error-summary-title",
+        text: DEFAULT_FIELD_STRINGS.errorSummaryTitle
+      })
     );
     const list = el("ul");
     for (const field of fields) {
@@ -2712,7 +2947,7 @@ var DomFormController = class {
       getValue: () => this.engine?.getState().data[block.id],
       registerOverlay: this.registerOverlay,
       uploadNotice: this.uploadNotices.get(block.id),
-      storageBlocked: this.storageBlocked(),
+      uploadDisabledReason: this.options.renderOnly ? "render_only" : this.storageBlocked() ? "storage_unavailable" : void 0,
       storageFixUrl: this.storageBlocked() && this.devChrome() ? safeHttpUrl(this.syncWarningUrl) : null,
       announce: this.announce,
       announceAlert: this.announceAlert
@@ -2738,7 +2973,10 @@ function defaultSuccess(schema) {
   appendChildren(inner, [
     el("div", { className: "fillo-success-mark", attrs: { "aria-hidden": "true" } }),
     el("h2", { className: "fillo-success-title", text: schema.settings.successTitle ?? "Thanks!" }),
-    el("p", { className: "fillo-success-message", text: schema.settings.successMessage ?? "Your response has been recorded." })
+    el("p", {
+      className: "fillo-success-message",
+      text: schema.settings.successMessage ?? "Your response has been recorded."
+    })
   ]);
   success.appendChild(inner);
   return success;
@@ -2786,7 +3024,10 @@ function devDraftEl(warningUrl) {
   if (safeUrl) {
     node.append("Connect storage to publish: ");
     node.appendChild(
-      el("a", { text: safeUrl, attrs: { href: safeUrl, target: "_blank", rel: "noopener noreferrer" } })
+      el("a", {
+        text: safeUrl,
+        attrs: { href: safeUrl, target: "_blank", rel: "noopener noreferrer" }
+      })
     );
     node.append(". ");
   }
@@ -2824,6 +3065,14 @@ function loadFailureMessage(error) {
   if (error.status === 422) return DEFAULT_STRINGS.renderFailed;
   return DEFAULT_STRINGS.loadFailed;
 }
+function formTargetRequiredError() {
+  return new FilloError(
+    "This form has no Fillo target. Pass formId with the schema, use a defineForm() value with client, or set renderOnly for a non-submitting preview.",
+    422,
+    void 0,
+    "form_target_required"
+  );
+}
 function toFilloError(error) {
   if (isFilloError(error)) return error;
   return new FilloError(error instanceof Error ? error.message : String(error), 0);
@@ -2831,7 +3080,11 @@ function toFilloError(error) {
 function renderForm(target, options) {
   const element = typeof target === "string" ? document.querySelector(target) : target;
   if (!element) throw new FilloError(`Fillo mount target not found: ${String(target)}`, 0);
-  return new DomFormController(element, { ...options, initialData: options.initialData ?? {} });
+  const internalOptions = {
+    ...options,
+    initialData: options.initialData ?? {}
+  };
+  return new DomFormController(element, internalOptions);
 }
 function createFormElement(options) {
   const host = el("div");
@@ -2849,7 +3102,7 @@ var FilloFormElement = class extends HTMLElementBase {
   mounted = false;
   mountScheduled = false;
   static get observedAttributes() {
-    return ["publishable-key", "form-id", "data-preview"];
+    return ["publishable-key", "form-id", "data-preview", "data-render-only"];
   }
   connectedCallback() {
     this.scheduleMount();
@@ -2906,6 +3159,11 @@ var FilloFormElement = class extends HTMLElementBase {
     const value = this.getAttribute("data-preview");
     return value !== null && value !== "false" && value !== "0";
   }
+  /** Explicit local-preview mode for custom-element integrations. */
+  renderOnlyAttrEnabled() {
+    const value = this.getAttribute("data-render-only");
+    return value !== null && value !== "false" && value !== "0";
+  }
   mount() {
     this.instance?.destroy();
     const key = this.getAttribute("publishable-key") ?? void 0;
@@ -2923,6 +3181,7 @@ var FilloFormElement = class extends HTMLElementBase {
       // Value-aware: frameworks stringify booleans onto data-* attributes, so
       // data-preview="false"/"0" must mean OFF, not presence-implies-on.
       preview: this.previewAttrEnabled() ? true : void 0,
+      renderOnly: this.renderOnlyAttrEnabled() ? true : void 0,
       onChange: (data) => this.dispatchEvent(new CustomEvent("fillo-change", { detail: { data } })),
       onSubmitted: (responseId, data) => this.dispatchEvent(new CustomEvent("fillo-submit", { detail: { responseId, data } })),
       onError: (error) => this.dispatchEvent(new CustomEvent("fillo-error", { detail: { error } }))