@zerotal/flow 1.3.0 → 1.5.0

package/src/Component.ts

@@ -16,6 +16,7 @@ import {
   getModelableProps,
 } from "./decorators.ts";
 import { _renderFlowPage } from "./jsx-runtime.ts";
+import { getStreamStore, queueStream } from "./streaming.ts";
 import { RuleBuilder, runValidationAsync } from "@zerotal/validator";
 import type { Schema, FieldRuleDefinition } from "@zerotal/validator";
 import type { ValidateBuilder } from "./decorators.ts";
@@ -28,6 +29,7 @@ import type { Compose } from "./mixins.ts";
 import { _validateEventPayload } from "./events.ts";
 import type { FlowEvents, EventName, EventArgs } from "./events.ts";
 import { route, request, safeRedirectPath, HttpContext } from "@zerotal/core";
+import type { RouteParamValues, RouteParamsArg, RouteTarget } from "@zerotal/core";
 
 /**
  * Convert the validator's one-message-per-field result (`Record<string, string>`) into
@@ -135,6 +137,99 @@ function _attrJson(s: string): string {
   return s.replace(/&/g, "&amp;").replace(/'/g, "&#39;").replace(/</g, "&lt;");
 }
 
+// ── Keyless child identity ───────────────────────────────────────────────────
+
+/** JSON with object keys in a stable order, so `{a,b}` and `{b,a}` hash alike. */
+function _stableJson(value: unknown): string {
+  if (value === null || typeof value !== "object") return JSON.stringify(value) ?? "null";
+  if (Array.isArray(value)) return `[${value.map(_stableJson).join(",")}]`;
+  const entries = Object.keys(value as Record<string, unknown>)
+    .sort()
+    .map((k) => `${JSON.stringify(k)}:${_stableJson((value as Record<string, unknown>)[k])}`);
+  return `{${entries.join(",")}}`;
+}
+
+/**
+ * FNV-1a, 32-bit, as fixed-width hex.
+ *
+ * Fixed width is the point: the occurrence counter is appended straight after
+ * it, so a variable-length hash would make `<hash>1` and `<hash>10` ambiguous.
+ * Not cryptographic — a collision costs two children sharing an id, the same
+ * cost as the occurrence index they replace.
+ */
+function _fnv1a(input: string): string {
+  let hash = 0x811c9dc5;
+  for (let i = 0; i < input.length; i++) {
+    hash ^= input.charCodeAt(i);
+    hash = Math.imul(hash, 0x01000193) >>> 0;
+  }
+  return hash.toString(16).padStart(8, "0");
+}
+
+function _isProduction(): boolean {
+  return (Bun.env["APP_ENV"] ?? Bun.env["NODE_ENV"]) === "production";
+}
+
+/** Classes already warned about, so a hundred-row list logs once. */
+const _warnedKeyless = new Set<string>();
+
+function _warnKeylessChild(className: string): void {
+  if (_warnedKeyless.has(className)) return;
+  _warnedKeyless.add(className);
+  console.warn(
+    `[Zerotal Flow] <${className}> is rendered more than once with identical props and no \`key\`. ` +
+      `Two children with the same id share one island: the second inherits the first's DOM and ` +
+      `state. Pass a key tied to the row's own identity — child(${className}, { key: item.id }).`,
+  );
+}
+
+/** Reset the once-per-class warning set. Tests. @internal */
+export function _resetKeylessWarnings(): void {
+  _warnedKeyless.clear();
+}
+
+/**
+ * The id suffix for a child rendered without an explicit `key`.
+ *
+ * `<hash of the seed props><occurrence within that hash>`. The hash is a fixed
+ * eight characters so the counter appended after it is unambiguous, and it is
+ * computed from the props that *identify* the child rather than the ones that
+ * update it — @reactive and @modelable props exist to change without remounting,
+ * and folding them in would trade a shifted-list bug for a child that resets on
+ * every parent update.
+ *
+ * A module function rather than a method: `Component` is extended by mixins that
+ * export anonymous classes, and a `private` member on one of those is a
+ * declaration error (TS4094).
+ *
+ * @internal
+ */
+function _autoChildKey(
+  childIds: readonly string[],
+  base: string,
+  props: Record<string, unknown>,
+  reactiveKeys: ReadonlySet<string>,
+  modelableKeys: ReadonlySet<string>,
+  className: string,
+): string {
+  const identity: Record<string, unknown> = {};
+  for (const key of Object.keys(props)) {
+    if (reactiveKeys.has(key) || modelableKeys.has(key)) continue;
+    identity[key] = props[key];
+  }
+
+  const hash = _fnv1a(_stableJson(identity));
+  const prefix = `${base}${hash}`;
+  const occurrence = childIds.filter((id) => id.startsWith(prefix)).length;
+
+  // Only the genuinely ambiguous case warns. A keyless child whose props differ
+  // from its siblings is now content-addressed and safe, so warning there would
+  // be noise; two siblings the framework cannot tell apart is the residual risk.
+  if (occurrence > 0 && !_isProduction()) _warnKeylessChild(className);
+
+  return `${hash}${occurrence}`;
+}
+
 // ── Internal effect bags ──────────────────────────────────────────────────────
 
 /**
@@ -564,7 +659,7 @@ export abstract class Component {
    * HTTP render and every subsequent WebSocket round-trip — after state is restored
    * (round-trips) or `@url`/`@session` seeded (initial), but before `onMount()` /
    * `onHydrate()`, property updates, and the action. Use for setup that must run on
-   * every request. (Livewire `boot()`.) Receives the route {@link HttpContext} — note that on
+   * every request. Receives the route {@link HttpContext} — note that on
    * WebSocket round-trips the URL is the stored route pattern, so raw `ctx.params` are
    * only populated on the initial GET; prefer `onMount()` for reading bound models.
    *
@@ -576,7 +671,7 @@ export abstract class Component {
    * Called at the beginning of every SUBSEQUENT (WebSocket) request, right after the
    * component is rebuilt from its snapshot — never on the initial render (use
    * `onMount()` for that). Ideal for re-deriving non-persisted/protected state from
-   * restored properties. (Livewire `hydrate()`.)
+   * restored properties.
    *
    * @category Lifecycle
    */
@@ -585,7 +680,6 @@ export abstract class Component {
   /**
    * Called at the END of every request, just before the component is serialised into
    * its snapshot. Use to normalise state back into a serialisable shape.
-   * (Livewire `dehydrate()`.)
    *
    * @category Lifecycle
    */
@@ -595,7 +689,7 @@ export abstract class Component {
    * Called BEFORE a client-driven property update is applied (a `value`/`checked`
    * input or `$flow.$set`). Throw to reject the update. Only fires for writable
    * (`@expose`) properties. For a single property, define `onUpdating<Prop>(value, key?)`
-   * — e.g. `onUpdatingEmail()`. (Livewire `updating()`.)
+   * — e.g. `onUpdatingEmail()`.
    *
    * @param prop  the property about to change
    * @param value the incoming value
@@ -608,7 +702,7 @@ export abstract class Component {
   /**
    * Called AFTER a client-driven property update is applied. For a single property,
    * define `onUpdated<Prop>(value, key?)` — e.g. `onUpdatedUsername()` to normalise a
-   * value such as lower-casing. (Livewire `updated()`.)
+   * value such as lower-casing.
    *
    * @category Lifecycle
    */
@@ -616,14 +710,14 @@ export abstract class Component {
   async onUpdated(_prop: string, _value: unknown, _key?: string): Promise<void> {}
 
   /**
-   * Called BEFORE `render()` runs. (Livewire `rendering()`.)
+   * Called BEFORE `render()` runs.
    *
    * @category Lifecycle
    */
   async onRendering(): Promise<void> {}
 
   /**
-   * Called AFTER `render()` produces this component's HTML. (Livewire `rendered()`.)
+   * Called AFTER `render()` produces this component's HTML.
    * @param html the rendered HTML for this component
    * @category Lifecycle
    */
@@ -633,7 +727,7 @@ export abstract class Component {
   /**
    * Called when an action throws an unhandled error. Flow catches the error and
    * still re-renders; override to customise (log, swallow, re-flash). The default
-   * flashes the message. (Livewire `exception()`.)
+   * flashes the message.
    *
    * @param error  the error thrown by the action.
    * @category Errors
@@ -831,6 +925,9 @@ export abstract class Component {
   redirect(url: string, status?: number): RedirectFlash {
     this._redirectUrl = url;
     this._redirectStatus = status ?? null;
+    // Two `this` scopes meet here: the builder methods chain on the builder while
+    // flashing through the component, so the alias is load-bearing.
+    // eslint-disable-next-line @typescript-eslint/no-this-alias
     const self = this;
     const builder: RedirectFlash = {
       with(message: string, level: FlashLevel) {
@@ -854,32 +951,37 @@ export abstract class Component {
   }
 
   /**
-   * Redirect to a named route, mirroring Livewire's `redirectRoute('profile', ['id' => 1])`.
-   * Route params fill `:segment` placeholders; any extra keys become query-string params.
+   * Redirect to a named route.
+   *
+   * Params fill `:segment` placeholders — one key per segment, no more: a key
+   * the pattern has no segment for throws rather than becoming a query param.
    *
    * @example
    * return this.redirectRoute("profile", { id: 1 }).withSuccess("Saved.");
-   * this.redirectRoute("posts.show", { slug: "hello", ref: "email" }); // /posts/hello?ref=email
+   * // With a query string, build the URL first:
+   * this.redirect(route("posts.show", { slug: "hello" }, { ref: "email" }));
    *
    * @param name    The route name registered with `.name(...)`.
-   * @param params  Route + query params.
+   * @param params  One value per `:param` in the route's pattern.
    * @param status  Optional HTTP-style status (advisory — the client navigates regardless).
    * @returns a {@link RedirectFlash} builder for chaining a flash onto the redirect.
    * @category Navigation & redirects
    */
-  redirectRoute(
-    name: string,
-    params: Record<string, string | number> = {},
+  redirectRoute<N extends RouteTarget>(
+    name: N,
+    params?: RouteParamsArg<N>,
     status?: number,
   ): RedirectFlash {
-    return this.redirect(route(name, params), status);
+    // Values in `RouteParams<N>` are route param values by construction; `N` is
+    // still a type variable here, so the compiler cannot see through to say so.
+    return this.redirect(route.dynamic(name, params as RouteParamValues), status);
   }
 
   /**
-   * Redirect the user back to where they were headed before being intercepted — Livewire's
-   * `redirectIntended('/default/url')`. Reads (and clears) the `intended_url` stored in the
-   * session by `AuthMiddleware`, falling back to `fallback` when none is stored or the stored
-   * URL is cross-origin (open-redirect guard).
+   * Redirect the user back to where they were headed before being intercepted. Reads
+   * (and clears) the `intended_url` stored in the session by `AuthMiddleware`, falling
+   * back to `fallback` when none is stored or the stored URL is cross-origin
+   * (open-redirect guard).
    *
    * @example
    * if (await Auth.attempt(creds)) return this.redirectIntended("/dashboard");
@@ -1041,8 +1143,8 @@ export abstract class Component {
   }
 
   /**
-   * @internal Real-time validation of a SINGLE field against its `@validate` rule (Livewire's
-   * live validation). Sets or clears `this._errors[field]` without throwing, so it can run on
+   * @internal Real-time validation of a SINGLE field against its `@validate` rule.
+   * Sets or clears `this._errors[field]` without throwing, so it can run on
    * every client update. No-op for fields without a `@validate` rule.
    */
   async _validateField(field: string): Promise<void> {
@@ -1115,7 +1217,7 @@ export abstract class Component {
 
   /**
    * Dispatch an event ONLY to components of a given class name (skips all others
-   * listening for the same event). Mirrors Livewire's `dispatch()->to(...)`.
+   * listening for the same event).
    *
    * @example
    * this.dispatchTo('Dashboard', 'post-created', { id: post.id });
@@ -1134,7 +1236,6 @@ export abstract class Component {
 
   /**
    * Dispatch an event only to THIS component (it won't bubble to others).
-   * Mirrors Livewire's `dispatch()->self()`.
    *
    * @example
    * this.dispatchSelf('refresh');
@@ -1280,14 +1381,24 @@ export abstract class Component {
    *
    * Children are islands: a parent re-render does NOT re-render existing
    * children (their DOM and state are preserved on the client), and a child
-   * update never touches the parent. Use `key` when embedding the same
-   * component class multiple times (e.g. in a loop).
+   * update never touches the parent.
+   *
+   * **Pass a `key` for anything rendered in a loop.** Without one the id is
+   * derived from the child's seed props, which is stable enough that a row
+   * keeps its island when the list shifts — but two siblings the props cannot
+   * tell apart still share an id, and sharing an id means sharing DOM and
+   * state. A key tied to the row's own identity (`key: item.id`) removes the
+   * question. Keys are sanitised to `[a-zA-Z0-9_-]`, so `a.b` and `ab` collide.
    *
    * `props` are assigned to the child instance before `onMount()` runs.
    *
    * Pass `lazy: true` to use IntersectionObserver — `onMount()` is deferred
    * until the placeholder enters the viewport.
    * Pass `defer: true` to load immediately after page paint (no intersection check).
+   * Pass `stream: true` to render the placeholder now and the real markup later
+   * on the *same* response — no second round trip. Use it for content that is
+   * definitely needed and merely slow; `lazy`/`defer` are for content that may
+   * never be needed at all.
    *
    * @example
    * override async render() {
@@ -1296,13 +1407,14 @@ export abstract class Component {
    *     <StatsWidget />
    *     <CounterWidget key="a" step={5} />
    *     <SlowWidget lazy />
+   *     <SalesReport stream />
    *   </div>;
    * }
    *
    * @param ChildClass  the child Component class to embed.
    * @param opts        `key` disambiguates repeated instances; `props` seed the child before
-   *                    `onMount()`; `lazy`/`defer` render a placeholder first; `slots` pass named
-   *                    slot HTML.
+   *                    `onMount()`; `lazy`/`defer`/`stream` render a placeholder first; `slots`
+   *                    pass named slot HTML.
    * @returns the child's rendered {@link HtmlNode} (root or placeholder).
    * @category Rendering
    */
@@ -1313,17 +1425,46 @@ export abstract class Component {
       props?: Partial<C>;
       lazy?: boolean;
       defer?: boolean;
+      /** Render the placeholder now, the real markup later on the same response. */
+      stream?: boolean;
       /** Named slot HTML (`name → html`, default slot keyed `"default"`), rendered by the parent. */
       slots?: Record<string, string>;
     } = {},
   ): Promise<HtmlNode> {
     const name = ChildClass.name;
     const base = `${this._flowId}-${name.toLowerCase()}-`;
-    // Deterministic id: explicit key, or occurrence index within this render.
+
+    // ── Reactive / modelable bindings (Tier 1) ───────────────────────────────
+    // `data-flow-props` carries the current value of each @reactive prop so the
+    // client can detect a parent-pushed change and re-render the child. For each
+    // @modelable prop, `data-flow-model` maps the child prop → the parent property
+    // it syncs back to (resolved by value identity against the parent's props).
+    const childProto = (ChildClass as { prototype: object }).prototype;
+    const reactiveKeys = getReactiveProps(childProto);
+    const modelableKeys = getModelableProps(childProto);
+    const givenProps = (opts.props ?? {}) as Record<string, unknown>;
+
+    // Deterministic id: an explicit key, or the child's seed props plus an
+    // occurrence counter.
+    //
+    // A bare occurrence index is *positional* identity, and position is not
+    // identity: remove the first item of a list and every row below it inherits
+    // the id its neighbour had. Because a hydrated parent emits an already-known
+    // child as an empty stub — on the understanding that the client morph will
+    // recognise the pairing — every row then adopts the previous row's live DOM,
+    // and the last one is left blank. Nothing warns, and no server-side test can
+    // see it: SSR and `FlowTest` render the full child every time.
+    //
+    // Folding the seed props into the id makes the pairing content-addressed, so
+    // a shifted row simply fails to match and is rendered in full — re-mounted
+    // rather than crossed with its neighbour. @reactive and @modelable props are
+    // excluded deliberately: those exist to change without remounting the child,
+    // and hashing them would trade this bug for a child that resets on every
+    // update. The counter still disambiguates genuinely identical siblings.
     const keyPart =
       opts.key !== undefined
         ? String(opts.key).replace(/[^a-zA-Z0-9_-]/g, "")
-        : String(this._childIds.filter((id) => id.startsWith(base)).length);
+        : _autoChildKey(this._childIds, base, givenProps, reactiveKeys, modelableKeys, name);
     const childId = `${base}${keyPart}`;
 
     this._childIds.push(childId);
@@ -1333,15 +1474,6 @@ export abstract class Component {
     const { registerComponent } = await import("./registry.ts");
     registerComponent(ChildClass as never, this._flowPath);
 
-    // ── Reactive / modelable bindings (Tier 1) ───────────────────────────────
-    // `data-flow-props` carries the current value of each @reactive prop so the
-    // client can detect a parent-pushed change and re-render the child. For each
-    // @modelable prop, `data-flow-model` maps the child prop → the parent property
-    // it syncs back to (resolved by value identity against the parent's props).
-    const childProto = (ChildClass as { prototype: object }).prototype;
-    const reactiveKeys = getReactiveProps(childProto);
-    const modelableKeys = getModelableProps(childProto);
-    const givenProps = (opts.props ?? {}) as Record<string, unknown>;
     let bindAttrs = "";
     if (reactiveKeys.size) {
       const propsObj: Record<string, unknown> = {};
@@ -1371,7 +1503,7 @@ export abstract class Component {
 
     // Parent re-render over WS: children that already exist client-side are
     // emitted as stubs — the client morph skips nested roots, so the child's live
-    // DOM and state are preserved (Livewire pattern). The stub still carries
+    // DOM and state are preserved. The stub still carries
     // data-flow-props so reactive/modelable updates reach the existing child.
     if (this._isHydrated && this._prevChildIds.includes(childId)) {
       return {
@@ -1410,6 +1542,47 @@ export abstract class Component {
       };
     }
 
+    // Streamed: paint the placeholder now and queue the real render to be
+    // appended to this same response once the shell has been flushed. Only
+    // possible during an initial GET — a WS patch has no open response to append
+    // to, so `getStreamStore()` is undefined there and this falls through to the
+    // ordinary inline render below.
+    const streamStore = opts.stream ? getStreamStore() : undefined;
+    if (streamStore) {
+      const childPage = new ChildClass();
+      childPage._flowId = childId;
+      childPage._flowPath = this._flowPath;
+      if (opts.slots) childPage._flowSlots = opts.slots;
+      if (opts.props) {
+        for (const [k, v] of Object.entries(opts.props)) {
+          if (!k.startsWith("_")) (childPage as Record<string, unknown>)[k] = v;
+        }
+      }
+
+      queueStream({
+        childId,
+        render: async () => {
+          const streamCtx = HttpContext.tryGet();
+          await childPage.onBoot(streamCtx);
+          await childPage.onMount(streamCtx);
+          const inner = await _renderFlowPage(childPage, () => childPage.render());
+          await childPage.onDehydrate();
+          const snap = dehydrate(childPage, { id: childId, name, path: this._flowPath });
+          return (
+            inner +
+            `<script type="application/json" id="flow-state-${childId}">${toScriptJson(snap)}</script>`
+          );
+        },
+      });
+
+      return {
+        html:
+          `<div data-flow-root x-data="{}" data-flow-id="${childId}" data-flow-name="${name}" data-flow-streaming${bindAttrs}>` +
+          `${childPage.placeholder().html}` +
+          `</div>`,
+      };
+    }
+
     // Initial render (SSR) or a child newly added by this update: full render.
     const childPage = new ChildClass();
     childPage._flowId = childId;
@@ -1526,7 +1699,7 @@ export abstract class Component {
     this.$set(key, value);
     await this._emitUpdateHook("onUpdated", key, value, arrayKey);
 
-    // Real-time validation (Livewire-style): if this field carries a `@validate` rule, validate
+    // Real-time validation: if this field carries a `@validate` rule, validate
     // just it now and set/clear its error. The changed value reaches here from `flow:model.live` /
     // `.blur` syncs (and dirty-field batches), so errors appear/clear as the user edits — the
     // refreshed `_errors` bag is sent to the client in this round-trip's patch. Never throws.