@zerotal/flow 1.3.0 → 1.5.0

package/src/jsx-runtime.ts

@@ -59,6 +59,7 @@ interface FlowDirectives {
 
   navigate?: boolean;
   navigateHover?: boolean;
+  navigatePreserveScroll?: boolean;
   current?: string;
   currentExact?: boolean;
   currentStrict?: boolean;
@@ -162,6 +163,9 @@ interface FlowDirectives {
   [key: `flow:${string}`]: any;
 }
 
+// TypeScript resolves JSX element/attribute types by looking up a JSX namespace —
+// there is no module-shaped way to provide it.
+// eslint-disable-next-line @typescript-eslint/no-namespace
 export namespace JSX {
   export type Element = HtmlNode;
 
@@ -183,6 +187,12 @@ export namespace JSX {
     lazy?: boolean;
     /** Mount a child component right after the first paint (non-blocking). */
     defer?: boolean;
+    /**
+     * Render a child component's placeholder now and its real markup later on the
+     * same response — no second round trip. For content that is definitely needed
+     * and merely slow; use `lazy`/`defer` for content that may never be needed.
+     */
+    stream?: boolean;
     /**
      * Named slot content for a child component: `slots={{ header: <h2>…</h2>, footer: … }}`.
      * The child places each with `this.slot("header")`; its plain children are the default slot.
@@ -265,9 +275,25 @@ function escapeAttr(s: string): string {
 // (e.g. two simultaneous GET requests each awaiting DB calls) cannot
 // cross-contaminate their page reference or child-thunk lists.
 
+/**
+ * How a failed child render is rendered instead of propagating.
+ *
+ * Installed by `<ErrorBoundary>` onto the thunks whose tokens appear in its
+ * children — see `_protectThunks`.
+ */
+export interface _ThunkBoundary {
+  fallback: (error: unknown) => string;
+}
+
+interface _Thunk {
+  token: string;
+  run: () => Promise<HtmlNode>;
+  boundary?: _ThunkBoundary;
+}
+
 interface _RenderCtx {
   page: Record<string, unknown>;
-  thunks: Array<{ token: string; run: () => Promise<HtmlNode> }>;
+  thunks: _Thunk[];
   seq: number;
   /**
    * Per-render random suffix on the child-placeholder token.
@@ -437,9 +463,17 @@ export async function _renderFlowPage(
       try {
         const node = await render();
         let html = node.html;
-        for (const { token, run } of ctx.thunks) {
-          const childNode = await run();
-          html = html.split(token).join(childNode.html);
+        for (const { token, run, boundary } of ctx.thunks) {
+          let childHtml: string;
+          try {
+            childHtml = (await run()).html;
+          } catch (error) {
+            // Unprotected children still take the page down — a boundary is the
+            // opt-in, and swallowing errors by default would hide real bugs.
+            if (!boundary) throw error;
+            childHtml = boundary.fallback(error);
+          }
+          html = html.split(token).join(childHtml);
         }
         return html;
       } finally {
@@ -704,6 +738,10 @@ const PULSE_PROP_MAP: Record<string, string> = {
   dirtyTarget: "flow:target",
   navigate: "flow:navigate",
   navigateHover: "flow:navigate.hover",
+  // One word on purpose: toFlowHtmlAttr() rewrites every `-` in a flow: attribute
+  // to a `.`, so a hyphenated modifier would reach the DOM under a different name
+  // here than the compiler emits.
+  navigatePreserveScroll: "flow:navigate.preserve",
   current: "flow:current",
   currentExact: "flow:current.exact",
   currentStrict: "flow:current.strict",
@@ -754,6 +792,42 @@ function toFlowHtmlAttr(k: string): string {
   return "flow:" + local.replace(/-/g, ".");
 }
 
+/**
+ * Render a JSX child to its HTML string, escaping anything that is not already
+ * an {@link HtmlNode}.
+ *
+ * @internal Exported for built-in components that need their children as markup
+ * before the wrapper element is built — `<ErrorBoundary>` inspects the result
+ * for child tokens, `<SectionContent>` publishes it elsewhere entirely.
+ */
+export function _renderChild(child: unknown): string {
+  return renderChild(child);
+}
+
+/**
+ * Route failures of the child components in `html` through `fallback`.
+ *
+ * `jsx()` has already queued a thunk for every `<Component />` encountered while
+ * building `html`, but none of them have run yet — they resolve after the parent
+ * render finishes. Matching on the tokens embedded in `html` is therefore enough
+ * to say which pending children sit inside this boundary, without the boundary
+ * needing to be told about them.
+ *
+ * A thunk already claimed by an inner boundary keeps it, so the nearest boundary
+ * wins.
+ *
+ * @internal
+ */
+export function _protectThunks(html: string, fallback: (error: unknown) => string): void {
+  const ctx = _getRenderCtx();
+  if (!ctx) return;
+  for (const thunk of ctx.thunks) {
+    if (thunk.boundary === undefined && html.includes(thunk.token)) {
+      thunk.boundary = { fallback };
+    }
+  }
+}
+
 function renderChild(child: unknown): string {
   if (child === null || child === undefined || child === false) return "";
   if (child === true) return "";
@@ -877,6 +951,7 @@ export function jsx(
                 slots?: Record<string, string>;
                 lazy?: boolean;
                 defer?: boolean;
+                stream?: boolean;
               },
             ): Promise<HtmlNode>;
           }
@@ -897,6 +972,7 @@ export function jsx(
         slots: _namedSlots,
         lazy: _lazy,
         defer: _defer,
+        stream: _stream,
         ...componentProps
       } = p;
       const slots: Record<string, string> = {};
@@ -919,6 +995,7 @@ export function jsx(
             props: componentProps,
             ...(_lazy ? { lazy: true } : {}),
             ...(_defer ? { defer: true } : {}),
+            ...(_stream ? { stream: true } : {}),
             ...(Object.keys(slots).length ? { slots } : {}),
           }),
       });
@@ -1011,7 +1088,7 @@ export function jsx(
       // Emitted as flow:{event} so the bridge detects the $flow prefix and
       // evaluates it via Alpine instead of sending a WebSocket action.
       if (typeof target === "function" && !target.name && k.startsWith("on")) {
-        const body = _clientExprFromFn(target as Function);
+        const body = _clientExprFromFn(target);
         const event = k.slice(2).toLowerCase();
         const base = `flow:${event}`;
         const attr = modifiers ? `${base}.${modifiers}` : base;
@@ -1154,8 +1231,14 @@ export function jsx(
       continue;
     }
 
-    let htmlKey = PULSE_PROP_MAP[k] || k;
-    htmlKey = toFlowHtmlAttr(htmlKey);
+    // A mapped value is the attribute name the compiler emits and the bridge queries
+    // for, so it goes out verbatim. Running it through toFlowHtmlAttr() rewrote the
+    // hyphen in `flow:focus-error` to a dot, and the runtime path then emitted an
+    // attribute nothing listens for: `focusOnError` worked on a compiled page and did
+    // nothing at all on one that fell back to the runtime, with no error either way.
+    // The kebab→dot rewrite is for hand-written `flow:*` attributes only.
+    const mapped = PULSE_PROP_MAP[k];
+    const htmlKey = mapped ?? toFlowHtmlAttr(k);
 
     // Special object formatting for `confirm={{ message, title?, confirm?, cancel?,
     // variant?, danger?, icon?, prompt? }}`. The bare {message} and {message,prompt}

package/src/pagination.ts

@@ -128,8 +128,7 @@ export function paginate<T>(items: T[], page = 1, perPage = 15): Paginator<T> {
 
 // ── Pagination mixin ──────────────────────────────────────────────────────────
 //
-// The TypeScript equivalent of Livewire's `WithPagination` trait: compose it onto a
-// component to add a URL-synced `page` plus page-navigation methods (`nextPage`,
+// A mixin: compose it onto a component to add a URL-synced `page` plus page-navigation methods (`nextPage`,
 // `previousPage`, `gotoPage`, `resetPage`), WITHOUT putting any of that on
 // the base Component.
 //
@@ -147,12 +146,12 @@ export function paginate<T>(items: T[], page = 1, perPage = 15): Paginator<T> {
 // applied here register on the mixin's prototype, which the component's prototype-chain
 // walk already traverses — so it "just works".
 //
-// Named paginators (Livewire's `pageName`): every nav method accepts an optional page
+// Named paginators: every nav method accepts an optional page
 // name so a single page can drive more than one independent paginator —
 // `this.nextPage("invoices")`, `Invoice.paginate(10, undefined, "invoices")`. The default
 // paginator ("page") is the URL-synced one; named paginators live in the snapshot.
 //
-// Optional update hooks fire around a page change, mirroring Livewire — define any of
+// Optional update hooks fire around a page change — define any of
 // `updatingPage(page, name)` / `updatedPage(page, name)` (default paginator) or the
 // generic `updatingPaginators(page, name)` / `updatedPaginators(page, name)`.
 
@@ -174,8 +173,7 @@ interface PaginationHooks {
 const DEFAULT_PAGE = "page";
 
 /**
- * Component mixin that adds URL-synced pagination state and navigation actions —
- * flow's equivalent of Livewire's `WithPagination` trait.
+ * Component mixin that adds URL-synced pagination state and navigation actions.
  *
  * @remarks
  * Composing this onto a component adds:
@@ -221,7 +219,7 @@ export function Pagination<TBase extends AbstractComponentCtor>(Base: TBase) {
     /** Current page of the default paginator, synced to the `?page=` query string. */
     @expose @url page = 1;
 
-    /** Current page of each NAMED paginator (Livewire `pageName`), keyed by name. Snapshot-only. */
+    /** Current page of each NAMED paginator, keyed by name. Snapshot-only. */
     @expose paginators: Record<string, number> = {};
 
     /**

package/src/provider/FlowProvider.ts

@@ -97,7 +97,7 @@ export function _runtimeJs(): string | null {
   return _runtimeBundle;
 }
 
-// ── Rate limiter for HMAC failures (Livewire pattern) ─────────────────────────
+// ── Rate limiter for HMAC failures ───────────────────────────────────────────
 
 const _checksumFailures = new Map<string, { count: number; since: number }>();
 const CHECKSUM_MAX = 10;
@@ -260,7 +260,7 @@ async function _handleFlowMessage(ws: FlowBunWs, raw: string, deps: FlowWsDeps):
   // with no user at all, so every action on an authenticated page is rejected
   // as somebody else's.
 
-  // ── Persistent middleware (Livewire-style) ──────────────────────────────────
+  // ── Persistent middleware ───────────────────────────────────────────────────
   const pagePath = frame.snapshot.memo.path;
   const middleware = [
     ...deps.globalMiddleware().filter(_isPersistentMiddleware),
@@ -785,7 +785,7 @@ async function _dispatchFrame(
     ws.send(JSON.stringify({ type: "flash", component: canonicalId, ...f }));
   }
 
-  // Dispatch cross-component events (to/self targeting mirrors Livewire's dispatch()->to()/->self()).
+  // Dispatch cross-component events (to/self targeting).
   for (const event of effects.events) {
     ws.send(
       JSON.stringify({
@@ -922,10 +922,9 @@ export class FlowProvider extends ServiceProvider {
   }
 
   /**
-   * Global middleware re-applied on every WebSocket update (Livewire-style
-   * persistent middleware). Matched against the app's global pipeline by
-   * class reference or class name. Route middleware always re-runs and does
-   * not need to be listed here.
+   * Global middleware re-applied on every WebSocket update. Matched against the
+   * app's global pipeline by class reference or class name. Route middleware
+   * always re-runs and does not need to be listed here.
    */
   static persistentMiddleware: (string | MiddlewareClass)[] = [...DEFAULT_PERSISTENT_MIDDLEWARE];
 
@@ -966,6 +965,11 @@ export class FlowProvider extends ServiceProvider {
     this._applyPersistentMiddlewareConfig();
     Router.macro("flow", flowRoute);
 
+    // Declared here rather than alongside the handlers below, because the handlers are
+    // only wired in the web runtime and `bun zt doctor --url=…` runs in a console one.
+    // The socket is the whole application, so a CLI that cannot name it cannot check it.
+    this.app.declareWebSocketPath("/__flow/ws");
+
     registerFileRouteResolver(({ urlPath, module, middleware, name, filePath }) => {
       const PageClass = _findPageExport(module);
       if (!PageClass) return false;
@@ -1244,8 +1248,13 @@ export class FlowProvider extends ServiceProvider {
 
     if (!cssExists && !jsExists) return;
 
-    const { registerDevBuildHook, buildCssBundle, buildJsBundle } =
-      await import("@zerotal/core/dev");
+    const {
+      registerDevBuildHook,
+      buildCssBundle,
+      buildJsBundle,
+      isDevOrchestrated,
+      bootBuildDecision,
+    } = await import("@zerotal/core/dev");
 
     // Combined hook — DevOrchestrator calls this on any frontend file change.
     // Registered under Flow's own name so it sits alongside, rather than on
@@ -1256,16 +1265,40 @@ export class FlowProvider extends ServiceProvider {
       const results = await Promise.all([
         cssExists
           ? buildCssBundle(cssEntry, cssOutdir, false)
-          : Promise.resolve({ success: true, logs: [] as unknown[] }),
+          : Promise.resolve({ success: true, logs: [] as unknown[], skipped: true }),
         jsExists
           ? buildJsBundle(jsEntry, jsOutdir, false)
-          : Promise.resolve({ success: true, logs: [] as unknown[] }),
+          : Promise.resolve({ success: true, logs: [] as unknown[], skipped: true }),
       ]);
       const failed = results.flatMap((r) => (r.success ? [] : (r.logs ?? [])));
-      return { success: failed.length === 0, logs: failed };
+      return {
+        success: failed.length === 0,
+        logs: failed,
+        // A bundle with no entry point counts as skipped: it did no work either.
+        skipped: results.every((r) => r.skipped === true),
+      };
     });
 
-    // Build once at startup so assets are ready before the first request.
+    // Build once at startup so assets are ready before the first request —
+    // except under `serve --dev`, where the orchestrator owns builds and has
+    // already run the hook above before this process could serve anything.
+    // Without this guard a Flow app built its bundles three times per boot (once
+    // here in the orchestrator process, once in the orchestrator's own initial
+    // build, once here again in the spawned worker) and twice per backend save.
+    if (isDevOrchestrated()) return;
+
+    // Nor in a production deployment whose output directory is read-only: those assets
+    // were built at deploy time, and rebuilding them is what turns a hardened systemd
+    // unit into a restart loop. See @zerotal/core/dev/bootBuild.ts.
+    const decision = await bootBuildDecision(
+      [...(cssExists ? [cssOutdir] : []), ...(jsExists ? [jsOutdir] : [])],
+      config.safe<string>("app.env", Bun.env["APP_ENV"] ?? "development"),
+    );
+    if (!decision.build) {
+      console.info(`[Flow] ${decision.reason}`);
+      return;
+    }
+
     const [cssResult, jsResult] = await Promise.all([
       cssExists
         ? buildCssBundle(cssEntry, cssOutdir, false)