@zerotal/flow 1.8.1 → 1.10.0

package/src/client/enhance.ts

@@ -0,0 +1,205 @@
+// ── @zerotal/flow plain-form enhancement bundle ─────────────────────────────────
+//
+// The entry point for the second Bun.build() in FlowProvider.onBooting(). It
+// produces /__flow/enhance.js.
+//
+// **Deliberately separate from the runtime bundle, and deliberately tiny.** The
+// whole point of this feature is a page with *no Flow component on it* — an
+// ordinary server-rendered form, on a route that is not `Router.flow`. Such a page
+// is never served `/__flow/runtime.js`, so there is no script to hook into; and
+// pulling Alpine and the WebSocket bridge onto a page with no component to drive
+// would be paying the entire framework's client cost for a submit handler.
+//
+// **This file exports nothing, and must not.** It is loaded as a classic script,
+// where a trailing `export` statement is a SyntaxError that discards the whole
+// bundle — silently, because the forms then post natively and the page still
+// works. The decisions worth testing live in `enhanceSupport.ts`, which Bun inlines
+// back in at build time.
+//
+// ## The contract
+//
+//   <form method="post" action="/subscribe" data-enhance>
+//
+// The form posts through `fetch`, and the matching form in the response replaces
+// this one in place. Validation errors then appear where they belong and the rest
+// of the page is untouched — no flash, no scroll loss, no re-render of a page that
+// did not change.
+//
+// Everything about it degrades:
+//
+//   - **No JavaScript is an ordinary post.** `data-enhance` is additive on a form
+//     that already has `method` and `action`, so the no-JS path is not a fallback
+//     that was written and might rot — it is the form itself, unmodified. If that
+//     is ever not free, the word "enhancement" is doing no work.
+//   - **A network failure re-submits natively.** The difference between a bad
+//     connection being slow and a bad connection losing what somebody typed.
+//   - **A redirect is followed**, its document swapped in and `pushState`d, so the
+//     address bar agrees with the page.
+
+import { ATTR, BUSY_ATTR, matchIn, sameUrl, targetFor } from "./enhanceSupport.ts";
+
+/**
+ * Move focus back to where it was before the swap.
+ *
+ * Replacing a subtree destroys the focused element, and a form that reports "this
+ * field is required" having just taken the cursor away from that field is worse
+ * than one that did not enhance at all. Matched by `name`, which survives a
+ * re-render in a way a DOM node cannot.
+ */
+function restoreFocus(root: Element, name: string | null, start: number | null): void {
+  if (!name) return;
+  const next = root.querySelector<HTMLInputElement>(`[name="${CSS.escape(name)}"]`);
+  if (!next) return;
+  next.focus();
+  if (start === null) return;
+  try {
+    next.setSelectionRange(start, start);
+  } catch {
+    // Not a text-like control (checkbox, select, file) — focus alone is the job.
+  }
+}
+
+/**
+ * Submit the form the way the browser would have, with the enhancement out of the
+ * way so this handler does not catch its own fallback.
+ */
+function nativeSubmit(form: HTMLFormElement, submitter: HTMLElement | null): void {
+  form.removeAttribute(ATTR);
+  if (submitter && "click" in submitter) {
+    // Through the submitter, so a named button still contributes its value.
+    submitter.click();
+    return;
+  }
+  form.submit();
+}
+
+/**
+ * Handle one enhanced submission.
+ *
+ * Throws nothing: every failure path either falls back to a native submit or
+ * leaves the page exactly as it was.
+ */
+async function submitEnhanced(form: HTMLFormElement, submitter: HTMLElement | null): Promise<void> {
+  const method = (form.getAttribute("method") || "get").toUpperCase();
+  const action = form.getAttribute("action") || window.location.href;
+
+  // `new FormData(form, submitter)` includes the button that was actually pressed,
+  // which is how `<button name="intent" value="delete">` tells the server which one.
+  const data = new FormData(form, submitter as HTMLButtonElement | null);
+
+  let url = action;
+  let body: FormData | null = data;
+  if (method === "GET") {
+    // A GET form carries its fields in the query string, not a body.
+    const query = new URLSearchParams();
+    for (const [key, value] of data.entries()) {
+      if (typeof value === "string") query.append(key, value);
+    }
+    const separator = action.includes("?") ? "&" : "?";
+    url = query.toString() ? `${action}${separator}${query}` : action;
+    body = null;
+  }
+
+  const target = targetFor(form, document, (selector) =>
+    console.warn(`[flow] data-enhance-target="${selector}" matched nothing; replacing the form.`),
+  );
+
+  const active = document.activeElement as HTMLInputElement | null;
+  const focusedName = active && form.contains(active) ? active.getAttribute("name") : null;
+  const caret = (() => {
+    try {
+      return active?.selectionStart ?? null;
+    } catch {
+      return null;
+    }
+  })();
+
+  form.setAttribute(BUSY_ATTR, "");
+
+  let response: Response;
+  let html: string;
+  try {
+    response = await fetch(url, {
+      method,
+      ...(body ? { body } : {}),
+      credentials: "same-origin",
+      redirect: "follow",
+      headers: { "X-Flow-Enhance": "1", Accept: "text/html" },
+    });
+    html = await response.text();
+  } catch {
+    // The network, not the server. Hand the submission back to the browser, which
+    // shows its own error and — crucially — has not lost the form data.
+    form.removeAttribute(BUSY_ATTR);
+    nativeSubmit(form, submitter);
+    return;
+  }
+
+  const parsed = new DOMParser().parseFromString(html, "text/html");
+
+  // `fetch` followed the redirect for us, so a changed URL means the server sent us
+  // somewhere. Swap the whole document and record the move, or the address bar
+  // keeps claiming we are on the page that did the posting.
+  if (response.redirected || !sameUrl(response.url, url, window.location.href)) {
+    document.documentElement.replaceWith(document.importNode(parsed.documentElement, true));
+    window.history.pushState({}, "", response.url);
+    window.dispatchEvent(new CustomEvent("flow:enhanced", { detail: { navigated: true } }));
+    return;
+  }
+
+  const replacement = matchIn(parsed, document, form, target);
+  if (!replacement) {
+    // The response has no counterpart for what we were going to replace — the page
+    // changed shape. Guessing would put arbitrary markup somewhere arbitrary; a
+    // full navigation is the honest answer.
+    window.location.href = response.url || url;
+    return;
+  }
+
+  const adopted = document.importNode(replacement, true);
+  target.replaceWith(adopted);
+  adopted.removeAttribute(BUSY_ATTR);
+  restoreFocus(adopted, focusedName, caret);
+  window.dispatchEvent(
+    new CustomEvent("flow:enhanced", { detail: { navigated: false, status: response.status } }),
+  );
+}
+
+/**
+ * One delegated listener on the document, for every enhanced form that exists now
+ * or is added later.
+ *
+ * Delegation rather than per-form binding because the swap above replaces forms
+ * with fresh nodes: anything bound directly would be discarded by the first
+ * successful submission, and the second one would post natively for no visible
+ * reason.
+ */
+function install(): void {
+  document.addEventListener(
+    "submit",
+    (event) => {
+      const form = (event.target as HTMLElement | null)?.closest?.(`form[${ATTR}]`) as
+        HTMLFormElement | null | undefined;
+      if (!form) return;
+      // Let a default-prevented submit stay prevented; another handler owns it.
+      if (event.defaultPrevented) return;
+      // An explicit opt-out on a form that carries the attribute for styling.
+      if (form.getAttribute(ATTR) === "false") return;
+      // A submission already in flight: drop the second rather than racing two
+      // responses into the same target.
+      if (form.hasAttribute(BUSY_ATTR)) {
+        event.preventDefault();
+        return;
+      }
+
+      event.preventDefault();
+      void submitEnhanced(form, (event as SubmitEvent).submitter);
+    },
+    // Bubble phase: a component's own handler gets to preventDefault first.
+    false,
+  );
+}
+
+if (typeof document !== "undefined") {
+  install();
+}

package/src/client/enhanceSupport.ts

@@ -0,0 +1,99 @@
+/**
+ * The parts of the plain-form enhancement that are decisions rather than effects.
+ *
+ * Split out of `enhance.ts` for a reason worth recording. That file is served as a
+ * **classic script** — `<script src="/__flow/enhance.js" defer>` on pages that have
+ * no module loader and no framework on them. A bundle ending in an `export`
+ * statement is a `SyntaxError` in that position, and the browser discards the whole
+ * file. It does so *silently*: the forms fall back to native posts and the page
+ * still works, so the enhancement is simply absent on exactly the pages it was
+ * added for, with nothing in the console to say why.
+ *
+ * So the entry exports nothing, and everything worth asserting on lives here, where
+ * a test can import it. Bun inlines this back into the bundle at build time, so the
+ * split costs the browser nothing.
+ *
+ * @module
+ */
+
+/** Marks a form as enhanced. */
+export const ATTR = "data-enhance";
+
+/** Overrides what gets replaced: any CSS selector. */
+export const TARGET_ATTR = "data-enhance-target";
+
+/** Set on a form while its submission is in flight, for styling and re-entry guards. */
+export const BUSY_ATTR = "data-enhance-busy";
+
+/**
+ * Whether two URLs name the same place, resolved against the document.
+ *
+ * Both sides are resolved before comparing, because one of them is whatever the
+ * author wrote in `action` — usually relative — and the other is `response.url`,
+ * which `fetch` always reports absolute. Comparing them raw would call every
+ * ordinary submission a redirect.
+ */
+export function sameUrl(a: string, b: string, baseHref: string): boolean {
+  if (!a || !b) return false;
+  try {
+    return new URL(a, baseHref).href === new URL(b, baseHref).href;
+  } catch {
+    return a === b;
+  }
+}
+
+/**
+ * Where a form's response should be written.
+ *
+ * The form itself by default. That is the useful default because it is what makes
+ * validation errors land where the person is looking without the page author
+ * naming anything — and because the form is the one element guaranteed to exist in
+ * the response, given the server just re-rendered it.
+ *
+ * @param onMissing - Called when `data-enhance-target` matches nothing.
+ */
+export function targetFor(
+  form: HTMLFormElement,
+  root: ParentNode,
+  onMissing: (selector: string) => void,
+): Element {
+  const selector = form.getAttribute(TARGET_ATTR);
+  if (!selector) return form;
+  const found = root.querySelector(selector);
+  if (found) return found;
+  // A selector matching nothing is an authoring mistake. Swapping the form instead
+  // is both harmless and visible: the page still works and the console says why it
+  // did not do what was asked.
+  onMissing(selector);
+  return form;
+}
+
+/**
+ * Find, in a freshly parsed response document, the element corresponding to
+ * `target` in the live one.
+ *
+ * Identity is by `id` when there is one, then by the selector the author gave, then
+ * — for a bare `<form data-enhance>` — by position among the enhanced forms on the
+ * page. The positional fallback is what lets the simplest possible usage work with
+ * no attributes at all, and it is why `id` is tried first: two forms that change
+ * order between renders would otherwise swap content.
+ */
+export function matchIn(
+  doc: Document,
+  live: ParentNode,
+  form: HTMLFormElement,
+  target: Element,
+): Element | null {
+  if (target.id) {
+    const byId = doc.getElementById(target.id);
+    if (byId) return byId;
+  }
+
+  const selector = form.getAttribute(TARGET_ATTR);
+  if (selector) return doc.querySelector(selector);
+
+  const forms = Array.from(live.querySelectorAll(`form[${ATTR}]`));
+  const index = forms.indexOf(form);
+  const candidates = doc.querySelectorAll(`form[${ATTR}]`);
+  return index >= 0 ? (candidates[index] ?? null) : (candidates[0] ?? null);
+}

package/src/client/url.ts

@@ -11,9 +11,9 @@ export interface CurrentUrlOptions {
    * `null`, `undefined`, or `""` removes the param; anything else is stringified
    * and set. Params not listed here are preserved.
    */
-  query?: Record<string, unknown>;
+  query?: Record<string, unknown> | undefined;
   /** Replace the URL hash. `""` clears it; omit to leave the hash untouched. */
-  hash?: string;
+  hash?: string | undefined;
 }
 
 /**

package/src/compiler/helpers.ts

@@ -13,13 +13,21 @@
  * @packageDocumentation
  */
 
-/** Escape a value for safe injection as HTML text content. */
+/**
+ * Escape a value for safe injection as HTML text content.
+ *
+ * @internal
+ */
 export function __esc(v: unknown): string {
   if (v == null || v === false || v === true) return "";
   return String(v).replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
 }
 
-/** Escape a value for safe injection inside an HTML attribute (double-quoted). */
+/**
+ * Escape a value for safe injection inside an HTML attribute (double-quoted).
+ *
+ * @internal
+ */
 export function __escAttr(v: unknown): string {
   if (v == null) return "";
   return String(v).replace(/&/g, "&amp;").replace(/"/g, "&quot;");

package/src/config.ts

@@ -23,7 +23,11 @@ export interface FlowConfigShape {
   persistentMiddleware: (string | MiddlewareClass)[];
 }
 
-/** Global middleware re-run on every WebSocket action unless overridden. */
+/**
+ * Global middleware re-run on every WebSocket action unless overridden.
+ *
+ * @internal
+ */
 export const DEFAULT_PERSISTENT_MIDDLEWARE: (string | MiddlewareClass)[] = [
   "SessionMiddleware",
   "PersistUserMiddleware",

package/src/decorators.ts

@@ -732,6 +732,8 @@ export function resolvePresenceChannel(channel: PresenceChannel, instance: objec
  * component instance to compute a per-instance name (for dynamic rooms).
  *
  * @category Realtime
+ *
+ * @internal
  */
 export type SharedChannel = string | ((self: Record<string, any>) => string);
 
@@ -1066,9 +1068,9 @@ export function resolveListeners(
  */
 export interface UrlOptions {
   /** Override the URL query parameter name. Defaults to the property name. */
-  as?: string;
+  as?: string | undefined;
   /** Push a new history entry or replace the current one. Defaults to `'replace'`. */
-  history?: "push" | "replace";
+  history?: "push" | "replace" | undefined;
 }
 
 type UrlDecorator = (value: unknown, context: ClassFieldDecoratorContext) => void;
@@ -1194,13 +1196,13 @@ function _paramDecorator(source: ParamSource): ParamDecorator {
 /** Options for {@link session}. */
 export interface SessionOptions {
   /** Session key to read and write. Defaults to the property's own name. */
-  key?: string;
+  key?: string | undefined;
   /**
    * Namespace the key to this component (`flow:<Component>:<key>`), so the value belongs to
    * this page alone and cannot collide with another component's field of the same name.
    * Default: `false` — the key is the session's own.
    */
-  scoped?: boolean;
+  scoped?: boolean | undefined;
 }
 
 type SessionDecorator = (value: unknown, context: ClassFieldDecoratorContext) => void;

package/src/durable.ts

@@ -66,6 +66,8 @@ interface DurableConfig {
  * `@zerotal/cache`/Redis) via {@link setDurableStore} to also survive redeploys.
  * Methods may be sync or async; a swapped store is responsible for its own TTL
  * eviction (the `ttlMs` hint is passed to {@link DurableStore.set | set}).
+ *
+ * @internal
  */
 export interface DurableStore {
   /** Fetch a stored snapshot by key, or `undefined` if absent/expired. */
@@ -130,6 +132,8 @@ export function setDurableStore(store: DurableStore): void {
  * inspects persisted snapshots directly.
  *
  * @returns The current {@link DurableStore}.
+ *
+ * @internal
  */
 export function getDurableStore(): DurableStore {
   return _store;

package/src/enhanceTag.ts

@@ -0,0 +1,36 @@
+/**
+ * The one line an app's layout needs for `<form data-enhance>` to work.
+ *
+ * A helper rather than a documented string, for the reason a sibling feature
+ * already learned the hard way: a resource nothing links is a resource nobody
+ * discovers is missing. A page whose layout forgot the tag does not fail — the
+ * forms simply post the way they always did, and the enhancement is silently
+ * absent on exactly the pages it was added for.
+ *
+ * @module
+ */
+
+/** The path `FlowProvider` serves the enhancement bundle at. */
+export const FLOW_ENHANCE_PATH = "/__flow/enhance.js";
+
+/**
+ * A `<script>` tag loading the plain-form enhancement.
+ *
+ * Put it in the layout that renders your non-Flow pages. Flow pages already get
+ * `/__flow/runtime.js`, which does not include this — the two are separate because
+ * the enhancement exists for pages that have no Flow component to run a runtime.
+ *
+ * `defer` so it never blocks the parse, and the listener is delegated on
+ * `document`, so a form that appears later is picked up without re-running
+ * anything.
+ *
+ * @example
+ * ```tsx
+ * <head>
+ *   {flowEnhanceTag()}
+ * </head>
+ * ```
+ */
+export function flowEnhanceTag(): string {
+  return `<script src="${FLOW_ENHANCE_PATH}" defer></script>`;
+}

package/src/index.ts

@@ -74,6 +74,7 @@ export type {
 // `class PostsPage extends Component.using(Pagination, …)`.
 export type { Constructor, Mixin, Compose } from "./mixins.ts";
 export { Layout } from "./Layout.ts";
+export { flowEnhanceTag, FLOW_ENHANCE_PATH } from "./enhanceTag.ts";
 export { Form, registerForm } from "./Form.ts";
 // Global client store — app-wide, client-only reactive UI state, read in JSX as
 // `$flow.$store.*`. `defineStore` declares its initial shape at app start; augment

package/src/provider/FlowProvider.ts

@@ -99,6 +99,17 @@ export function _devErrorInfo(error: unknown, action: string): DevErrorInfo {
 
 let _runtimeBundle: string | null = null;
 
+/**
+ * The `/__flow/enhance.js` bundle — the standalone plain-form enhancement.
+ *
+ * Separate from the runtime bundle on purpose. `/__flow/runtime.js` is injected
+ * only by `Router.flow` routes, and the whole point of `<form data-enhance>` is a
+ * page with no Flow component on it, which is therefore never served that script.
+ * It is also tiny and dependency-free, so an app that wants a form not to flash
+ * does not pay for Alpine and a WebSocket bridge to get it.
+ */
+let _enhanceBundle: string | null = null;
+
 /**
  * CSP-safe mode flag (no 'unsafe-eval'). Set `flow.cspSafe` in `config/flow.ts`,
  * or the ZT_FLOW_CSP_SAFE / APP_CSP_SAFE env flag when there is no config file.
@@ -113,6 +124,51 @@ export function _runtimeJs(): string | null {
   return _runtimeBundle;
 }
 
+/** @internal — the built plain-form enhancement bundle, or null when it failed to build. */
+export function _enhanceJs(): string | null {
+  return _enhanceBundle;
+}
+
+/** In-flight build, so concurrent first requests share one rather than racing. */
+let _enhanceBuild: Promise<string | null> | null = null;
+
+/**
+ * Build the enhancement bundle once, on first request.
+ *
+ * No CSP variant: it has no expression evaluator to swap, because it evaluates
+ * nothing — it reads attributes and calls `fetch`.
+ *
+ * @internal
+ */
+async function _buildEnhanceBundle(): Promise<string | null> {
+  if (_enhanceBundle) return _enhanceBundle;
+  // Cache the promise, not the result — two requests arriving together would
+  // otherwise both bundle.
+  _enhanceBuild ??= (async () => {
+    try {
+      const entry = fileURLToPath(new URL("../client/enhance.ts", import.meta.url));
+      const result = await Bun.build({
+        entrypoints: [entry],
+        target: "browser",
+        minify: isProdLike(deployEnv()),
+        format: "esm",
+      });
+      if (result.success && result.outputs.length > 0) {
+        _enhanceBundle = await result.outputs[0]!.text();
+        return _enhanceBundle;
+      }
+      console.warn("[Flow] Enhancement bundle build failed:", result.logs);
+    } catch (e) {
+      console.warn("[Flow] Could not build enhancement bundle:", e);
+    }
+    // A failed build is not cached: the next request tries again, which is right
+    // for a dev-time transient and harmless for a real one.
+    _enhanceBuild = null;
+    return null;
+  })();
+  return _enhanceBuild;
+}
+
 // ── Rate limiter for HMAC failures ───────────────────────────────────────────
 
 const _checksumFailures = new Map<string, { count: number; since: number }>();
@@ -1029,6 +1085,38 @@ export class FlowProvider extends ServiceProvider {
       console.warn("[Flow] Could not build client bundle:", e);
     }
 
+    // Serve the plain-form enhancement bundle. Deliberately cacheable, unlike the
+    // runtime: it carries no per-app route table, so there is nothing in it that can
+    // go stale between deploys of the same framework version.
+    //
+    // Built on first request rather than at boot. Most apps never serve a page that
+    // uses `<form data-enhance>` — it is for the pages Flow does not otherwise touch
+    // — so building it at boot spends time on an artefact nobody asks for, in every
+    // process, including every test that boots a provider.
+    Router.get(
+      "/__flow/enhance.js",
+      class FlowEnhanceHandler {
+        async handle(http: HttpContext): Promise<void> {
+          const bundle = await _buildEnhanceBundle();
+          if (!bundle) {
+            http.response = new Response("// Flow enhancement unavailable", {
+              status: 503,
+              headers: { "Content-Type": "text/javascript; charset=utf-8" },
+            });
+            return;
+          }
+          http.response = new Response(bundle, {
+            status: 200,
+            headers: {
+              "Content-Type": "text/javascript; charset=utf-8",
+              "Cache-Control": "public, max-age=3600",
+            },
+          });
+        }
+      },
+      "handle",
+    );
+
     // Serve the client-side runtime bundle
     Router.get(
       "/__flow/runtime.js",
@@ -1371,6 +1459,8 @@ let _activeConnections = 0;
  * Number of currently-open Flow (reactive SSR) WebSocket connections.
  * @returns The live count of open `/__flow/ws` connections.
  * @category Connections
+ *
+ * @internal
  */
 export function flowActiveConnections(): number {
   return _activeConnections;
@@ -1379,6 +1469,8 @@ export function flowActiveConnections(): number {
 /**
  * One currently-open Flow WebSocket client, enriched as actions identify the user.
  * @category Connections
+ *
+ * @internal
  */
 export interface FlowConnection {
   id: string;
@@ -1397,6 +1489,8 @@ const _connections = new Map<string, FlowConnection>();
  * Snapshot of currently-connected Flow clients (most-recently-active first).
  * @returns An array of {@link FlowConnection}, sorted by `lastActivityAt` descending.
  * @category Connections
+ *
+ * @internal
  */
 export function flowConnections(): FlowConnection[] {
   return [..._connections.values()].sort((a, b) => b.lastActivityAt - a.lastActivityAt);

package/src/registry.ts

@@ -56,6 +56,8 @@ export function _getPageEntries(): Map<string, PageEntry> {
  * // In a ServiceProvider's boot method:
  * registerComponent(CounterWidget);
  * ```
+ *
+ * @internal
  */
 export function registerComponent(PageClass: typeof Component, path = ""): void {
   if (!_pages.has(PageClass.name)) registerPage(path, PageClass);
@@ -103,6 +105,8 @@ export { getRenderlessMethods };
  * A Component constructor plus the optional static metadata a page class may declare
  * (`title`, `head`, `models`, `layout`). Used when resolving file-route page exports and
  * when auto-registering associated model classes.
+ *
+ * @internal
  */
 export interface PageClassWithMeta {
   new (): Component;

package/src/shared.ts

@@ -35,6 +35,8 @@ export const SHARED_EVENT = "flow:shared";
  * The default is an in-process {@link MemorySharedStore}; swap a distributed
  * implementation (e.g. Redis-backed) via {@link setSharedStore} to converge
  * across processes. Implement all three methods synchronously.
+ *
+ * @internal
  */
 export interface SharedStore {
   /** Read the current value for a `channel::prop` key, or `undefined` if unset. */
@@ -93,6 +95,8 @@ export function setSharedStore(store: SharedStore): void {
  *   @expose increment() { this.count++; } // written back + broadcast on commit
  * }
  * ```
+ *
+ * @internal
  */
 export function getSharedStore(): SharedStore {
   return _store;