@usefillo/dom 0.16.1 → 0.19.0

package/README.md

@@ -65,7 +65,7 @@ Or drop it in with a single script tag — the bundle exposes a global `Fillo`:
 </script>
 ```
 
-The default stylesheet follows system dark mode for unthemed embeds. Pass `theme: { colorScheme: "dark" }` or `"light"` when the host surface is known.
+The default stylesheet inherits the host page's CSS `color-scheme` and font. If your theme switch only toggles a class or data attribute, pass its resolved mode as `theme: { colorScheme: "light" | "dark" }`. Use `"auto"` only for a deliberately system-driven page. A fixed hex `background` automatically selects a readable palette unless you explicitly choose one.
 
 Every rendered part carries `data-*` state attributes (`data-selected`, `data-invalid`, …) for utility CSS, and the default stylesheet is cascade-layered so your own styles win. On Tailwind v3 or reset-heavy sites import `@usefillo/dom/styles.unlayered.css` instead. Styling contract: [fillo.so/docs/styling](https://fillo.so/docs/styling).
 

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { Field, FieldValue, FormSchema, FilloClient, ResponseData, FormStatus as FormStatus$1, FormPage, Block, FilloRespondent, CodeForm, FormTheme, ChallengeConfig, FieldKind, FilloError, FormControllerOptions, FormController } from '@usefillo/core';
+import { Field, FieldValue, FormSchema, FilloClient, ResponseData, FormStatus as FormStatus$1, FormPage, Block, FilloRespondent, CodeForm, FormTheme, ChallengeConfig, ChallengeTheme, FieldKind, FilloError, FormControllerOptions, FormController } from '@usefillo/core';
 export { CodeForm, Field, FieldKind, FieldValue, FileValue, FilloClient, FilloClientOptions, FilloError, FormController, FormControllerOptions, FormControllerState, FormSchema, FormTheme, ProvisionWorkspaceResult, ResponseData, createClient, defineForm, provisionWorkspace } from '@usefillo/core';
 
 type FormStatus = FormStatus$1 | "loading" | "closed";
@@ -59,6 +59,18 @@ interface RenderFormBaseOptions {
      * hosted page does this). Wins over anything the server delivers.
      */
     challenge?: ChallengeConfig;
+    /**
+     * Theme for the human-verification widget. Defaults to "auto" (the
+     * visitor's OS preference); apps with their own theme switch pass
+     * "light"/"dark" so the widget matches the surrounding form.
+     */
+    challengeTheme?: ChallengeTheme;
+    /**
+     * Bridge-mode visibility for the human check. "interaction-only" (default)
+     * keeps it invisible unless Cloudflare needs the visitor to act; "always"
+     * shows the classic widget box the whole time.
+     */
+    challengeAppearance?: "always" | "interaction-only";
     className?: string;
     components?: Partial<Record<FieldKind, FieldRenderer>>;
     customComponents?: Record<string, FieldRenderer>;

package/dist/index.js

@@ -1662,7 +1662,10 @@ function repeatingGroup(context) {
     removeBtn.toggleAttribute("disabled", !canRemove);
     if (!canRemove) {
       removeBtn.setAttribute("aria-disabled", "true");
-      removeBtn.setAttribute("title", `At least ${floor} ${floor === 1 ? "entry" : "entries"} required`);
+      removeBtn.setAttribute(
+        "title",
+        `At least ${floor} ${floor === 1 ? "entry" : "entries"} required`
+      );
     }
     removeBtn.addEventListener("click", () => {
       if (count <= floor) return;
@@ -1758,6 +1761,8 @@ function defaultFieldRenderer(context) {
 }
 var TURNSTILE_SCRIPT_SRC = "https://challenges.cloudflare.com/turnstile/v0/api.js?render=explicit";
 var TURNSTILE_SCRIPT_ID = "fillo-turnstile-script";
+var BRIDGE_READY_TIMEOUT_MS = 2e4;
+var CHALLENGE_CDATA_RE = /^[A-Za-z0-9_-]{1,255}$/;
 var turnstileScriptPromise = null;
 function turnstileGlobal() {
   return globalThis.turnstile;
@@ -1883,6 +1888,15 @@ var DomFormController = class {
   // Invalidated on teardown so a stale load/render callback can't land after
   // a later attempt replaced the container (or double-render into it).
   turnstileAttempt = 0;
+  // Bridge mode (challenge.bridgeUrl): the Fillo-hosted iframe that runs the
+  // widget on Fillo's OWN hostname (so the check works on any embedding
+  // domain) plus its postMessage wiring. Mutually exclusive with the direct
+  // Cloudflare-script fields above; teardownTurnstileWidget() clears both.
+  challengeFrame = null;
+  challengeFrameSrc = null;
+  challengeFrameOrigin = null;
+  challengeMessageHandler = null;
+  challengeWatchdog = null;
   // Clear-then-set (one frame apart) so an identical repeat still re-fires —
   // a same-tick ""→text write can collapse into a no-op net change for AT.
   announce = (text) => {
@@ -1958,6 +1972,8 @@ var DomFormController = class {
    *  substitutes for the explicit uploadsAvailable control state. */
   syncWarningCode;
   syncWarningUrl;
+  /** Dashboard form overview containing the Publish action — dev chrome only. */
+  syncFormUrl;
   /** Server-authoritative ability to start a new file upload. */
   uploadsAvailable;
   /** Server-authoritative per-file ceiling for the active storage lane. */
@@ -1983,6 +1999,7 @@ var DomFormController = class {
               const result = await syncCodeForm(client, codeForm, { bypassCache: true });
               this.syncWarningCode = result.warningCode;
               this.syncWarningUrl = result.warningUrl;
+              this.syncFormUrl = result.manageUrl;
               this.uploadsAvailable = result.uploadsAvailable;
               this.uploadFileSizeLimitMb = result.uploadFileSizeLimitMb;
               if (result.status === "draft") {
@@ -2083,6 +2100,7 @@ var DomFormController = class {
           this.draftNotice = result.status === "draft";
           this.syncWarningCode = result.warningCode;
           this.syncWarningUrl = result.warningUrl;
+          this.syncFormUrl = result.manageUrl;
           this.uploadsAvailable = result.uploadsAvailable;
           this.uploadFileSizeLimitMb = result.uploadFileSizeLimitMb;
           this.challenge = this.options.challenge ?? result.challenge;
@@ -2413,7 +2431,7 @@ var DomFormController = class {
     } catch (error) {
       if (this.destroyed || controller.signal.aborted) return;
       const uploadError = toFilloError(error);
-      const message = uploadError.status !== void 0 && uploadError.status >= 500 ? DEFAULT_FIELD_STRINGS.uploadUnavailable : uploadError.message || DEFAULT_FIELD_STRINGS.uploadFailed;
+      const message = uploadError.status === 0 || uploadError.status !== void 0 && uploadError.status >= 500 ? DEFAULT_FIELD_STRINGS.uploadUnavailable : DEFAULT_FIELD_STRINGS.uploadFailed;
       const row = this.inFlight.get(key);
       if (row) row.error = message;
       this.announceAlert(message);
@@ -2503,6 +2521,142 @@ var DomFormController = class {
     }
     this.overlays.clear();
   }
+  /** Route the challenge to bridge or direct mode per the server's config.
+   *  Bridge (bridgeUrl present — every current server) works on any embedding
+   *  domain; direct is the pre-bridge fallback for older self-hosted servers.
+   *  Message contract mirrors @usefillo/react's turnstile module; keep both
+   *  in sync with apps/web src/app/embed/challenge/route.ts. */
+  ensureChallengeWidget(challenge) {
+    if (challenge.bridgeUrl) this.ensureChallengeBridge(challenge.bridgeUrl);
+    else this.ensureTurnstileWidget(challenge.siteKey);
+  }
+  /** Idempotent per src: mounts the Fillo-hosted bridge iframe into the
+   *  persistent container and wires its postMessage token flow. */
+  ensureChallengeBridge(bridgeUrl) {
+    if (typeof window === "undefined") return;
+    let url;
+    try {
+      url = new URL(bridgeUrl);
+    } catch {
+      this.handleChallengeError();
+      return;
+    }
+    if (url.protocol !== "https:" && url.protocol !== "http:") {
+      this.handleChallengeError();
+      return;
+    }
+    url.searchParams.set("origin", window.location.origin);
+    url.searchParams.set("theme", this.options.challengeTheme ?? "auto");
+    if (this.formId && CHALLENGE_CDATA_RE.test(this.formId)) {
+      url.searchParams.set("cdata", this.formId);
+    }
+    url.searchParams.set(
+      "appearance",
+      (this.options.challengeAppearance ?? "interaction-only") === "interaction-only" ? "interaction-only" : "always"
+    );
+    const src = url.toString();
+    if (this.challengeFrame && this.challengeFrameSrc === src) return;
+    this.teardownTurnstileWidget();
+    const attempt = ++this.turnstileAttempt;
+    const frame = el("iframe", {
+      className: "fillo-turnstile-frame",
+      attrs: {
+        src,
+        title: "Human verification",
+        // Cloudflare's normal widget footprint; attributes so host CSS wins.
+        width: "300",
+        height: "65",
+        referrerpolicy: "no-referrer"
+      }
+    });
+    this.challengeFrame = frame;
+    this.challengeFrameSrc = src;
+    this.challengeFrameOrigin = url.origin;
+    this.turnstileContainer.appendChild(frame);
+    this.setChallengeFrameVisible(
+      (this.options.challengeAppearance ?? "interaction-only") !== "interaction-only"
+    );
+    const onMessage = (event) => {
+      if (attempt !== this.turnstileAttempt || this.destroyed) return;
+      if (event.origin !== this.challengeFrameOrigin) return;
+      if (!this.challengeFrame || event.source !== this.challengeFrame.contentWindow) return;
+      const data = event.data;
+      switch (data?.type) {
+        case "fillo:challenge:ready":
+          this.settleChallengeWatchdog();
+          break;
+        case "fillo:challenge:token":
+          this.settleChallengeWatchdog();
+          if (typeof data.token === "string" && data.token.length > 0) {
+            this.handleChallengeToken(data.token);
+          }
+          if ((this.options.challengeAppearance ?? "interaction-only") === "interaction-only") {
+            this.setChallengeFrameVisible(false);
+          }
+          break;
+        case "fillo:challenge:interactive":
+          this.setChallengeFrameVisible(true);
+          break;
+        case "fillo:challenge:interactive-done":
+          if ((this.options.challengeAppearance ?? "interaction-only") === "interaction-only") {
+            this.setChallengeFrameVisible(false);
+          }
+          break;
+        case "fillo:challenge:expired":
+          this.handleChallengeToken(void 0);
+          break;
+        case "fillo:challenge:error":
+          this.settleChallengeWatchdog();
+          this.handleChallengeToken(void 0);
+          this.handleChallengeError();
+          break;
+      }
+    };
+    this.challengeMessageHandler = onMessage;
+    window.addEventListener("message", onMessage);
+    this.challengeWatchdog = window.setTimeout(() => {
+      if (attempt !== this.turnstileAttempt || this.destroyed) return;
+      this.handleChallengeToken(void 0);
+      this.handleChallengeError();
+    }, BRIDGE_READY_TIMEOUT_MS);
+  }
+  /** Collapse/expand the bridge frame (interaction-only mode). The frame stays
+   *  mounted either way — height 0 keeps the invisible check running. */
+  setChallengeFrameVisible(visible) {
+    const frame = this.challengeFrame;
+    if (!frame) return;
+    frame.setAttribute("height", visible ? "65" : "0");
+    if (visible) {
+      frame.removeAttribute("aria-hidden");
+      frame.removeAttribute("tabindex");
+    } else {
+      frame.setAttribute("aria-hidden", "true");
+      frame.setAttribute("tabindex", "-1");
+    }
+    this.turnstileContainer.setAttribute(
+      "data-fillo-challenge-visible",
+      visible ? "true" : "false"
+    );
+  }
+  settleChallengeWatchdog() {
+    if (this.challengeWatchdog !== null && typeof window !== "undefined") {
+      window.clearTimeout(this.challengeWatchdog);
+    }
+    this.challengeWatchdog = null;
+  }
+  /** Unwire and remove the bridge frame (listener, watchdog, iframe). Safe to
+   *  call when nothing is mounted. */
+  teardownChallengeBridge() {
+    if (this.challengeMessageHandler && typeof window !== "undefined") {
+      window.removeEventListener("message", this.challengeMessageHandler);
+    }
+    this.challengeMessageHandler = null;
+    this.settleChallengeWatchdog();
+    this.challengeFrame?.remove();
+    this.challengeFrame = null;
+    this.challengeFrameSrc = null;
+    this.challengeFrameOrigin = null;
+  }
   /** Idempotent: at most one load+render per armed container (guarded by
    *  widget id / in-flight / already-failed); re-arms on a changed site key
    *  (mirrors react's effect, keyed on siteKey). */
@@ -2558,7 +2712,14 @@ var DomFormController = class {
    *  expiry, or timeout) — not a teardown, the widget stays mounted. */
   resetChallengeWidget() {
     this.challengeToken = void 0;
-    if (this.turnstileWidgetId) turnstileGlobal()?.reset(this.turnstileWidgetId);
+    if (this.challengeFrame && this.challengeFrameOrigin) {
+      this.challengeFrame.contentWindow?.postMessage(
+        { type: "fillo:challenge:reset" },
+        this.challengeFrameOrigin
+      );
+    } else if (this.turnstileWidgetId) {
+      turnstileGlobal()?.reset(this.turnstileWidgetId);
+    }
     this.queueRender();
   }
   /** Fully remove any active/pending widget (mirrors react's unmount effect):
@@ -2566,8 +2727,11 @@ var DomFormController = class {
    *  fresh container replaces the old one for a pristine next mount. Safe to
    *  call when nothing is active. */
   teardownTurnstileWidget() {
-    if (this.turnstileWidgetId === null && !this.turnstileLoadInFlight) return;
+    if (this.turnstileWidgetId === null && !this.turnstileLoadInFlight && this.challengeFrame === null) {
+      return;
+    }
     this.turnstileAttempt++;
+    this.teardownChallengeBridge();
     const api = turnstileGlobal();
     if (this.turnstileWidgetId && api) {
       try {
@@ -2835,6 +2999,7 @@ var DomFormController = class {
           staged: this.stagedNotice,
           draft: this.draftNotice,
           warningUrl: this.syncWarningUrl,
+          formUrl: this.syncFormUrl,
           noClient: !this.options.client && !this.options.renderOnly
         })
       );
@@ -3039,8 +3204,8 @@ var DomFormController = class {
         );
       }
       content.appendChild(slot);
-      this.ensureTurnstileWidget(this.challenge.siteKey);
-    } else if (this.turnstileWidgetId !== null || this.turnstileLoadInFlight) {
+      this.ensureChallengeWidget(this.challenge);
+    } else if (this.turnstileWidgetId !== null || this.turnstileLoadInFlight || this.challengeFrame !== null) {
       this.teardownTurnstileWidget();
     }
     const submitError = api.status === "error" ? "This form can't submit right now. Please try again in a moment." : this.engine?.getState().submitError;
@@ -3214,25 +3379,45 @@ function devSyncErrorEl(error) {
     attrs: { role: "alert" }
   });
 }
-function devStagedEl() {
-  return el("div", {
-    className: "fillo-devwarning",
-    text: "Code changes are staged. Local preview only. Publish in Fillo before deploying for respondents.",
-    attrs: { role: "alert" }
-  });
+function devStagedEl(formUrl) {
+  const node = el("div", { className: "fillo-devwarning", attrs: { role: "alert" } });
+  node.append(
+    "Code changes are staged, not live. This page shows your draft, while respondents still get the live version. "
+  );
+  const publishUrl = safeHttpUrl(formUrl);
+  if (publishUrl) {
+    node.appendChild(
+      el("a", {
+        text: "Review and publish in Fillo",
+        attrs: { href: publishUrl, target: "_blank", rel: "noopener noreferrer" }
+      })
+    );
+    node.append(".");
+  } else {
+    node.append("Review and publish the changes in Fillo.");
+  }
+  return node;
 }
-function devDraftEl(warningUrl) {
+function devDraftEl(warningUrl, formUrl) {
   const node = el("div", { className: "fillo-devwarning", attrs: { role: "alert" } });
   node.append(
-    "Draft form \u2014 it renders here, but it won't accept responses until you publish it in your Fillo dashboard. "
+    "Draft form preview \u2014 the form renders for local testing, but Fillo will reject the submission and save no response until you publish it. "
   );
-  const safeUrl = safeHttpUrl(warningUrl);
-  if (safeUrl) {
-    node.append("Connect storage to publish: ");
+  const storageUrl = safeHttpUrl(warningUrl);
+  const publishUrl = safeHttpUrl(formUrl);
+  if (storageUrl) {
+    node.appendChild(
+      el("a", {
+        text: "Connect storage to publish",
+        attrs: { href: storageUrl, target: "_blank", rel: "noopener noreferrer" }
+      })
+    );
+    node.append(". ");
+  } else if (publishUrl) {
     node.appendChild(
       el("a", {
-        text: safeUrl,
-        attrs: { href: safeUrl, target: "_blank", rel: "noopener noreferrer" }
+        text: "Open in Fillo to publish",
+        attrs: { href: publishUrl, target: "_blank", rel: "noopener noreferrer" }
       })
     );
     node.append(". ");
@@ -3260,8 +3445,8 @@ function devChromeEls(state) {
   if (state.preview) nodes.push(previewBadgeEl());
   if (state.devNotices === false) return nodes;
   if (state.syncError) nodes.push(devSyncErrorEl(state.syncError));
-  else if (state.staged) nodes.push(devStagedEl());
-  else if (state.draft) nodes.push(devDraftEl(state.warningUrl));
+  else if (state.staged) nodes.push(devStagedEl(state.formUrl));
+  else if (state.draft) nodes.push(devDraftEl(state.warningUrl, state.formUrl));
   else if (state.noClient) nodes.push(devNoClientEl());
   return nodes;
 }