@zerotal/flow 1.0.0

package/src/Form.ts

@@ -0,0 +1,189 @@
+// A Form bundles related fields + their validation rules + reset/fill helpers into
+// a reusable class, mounted on a component as a single @expose property:
+//
+//   class LoginForm extends Form {
+//     email = '';
+//     password = '';
+//     rules(v: RuleBuilder) {
+//       return { email: v.string().email(), password: v.string().min(8) };
+//     }
+//   }
+//
+//   class LoginPage extends Component {
+//     @expose form = new LoginForm();
+//     @expose async submit() {
+//       this.validate(this.form);          // validates form.data() against form.rules
+//       await Auth.attempt(this.form.data());
+//     }
+//   }
+//
+// Validation uses the built-in @zerotal/validator (its fluent RuleBuilder schema).
+// Bind fields with `value={this.form.email}` (compiled to flow:model="form.email").
+// Forms round-trip through a synthesizer so the class + methods survive hydration.
+
+import { ValidationError } from "./validation.ts";
+import { registerSynth } from "./synths/index.ts";
+import { RuleBuilder, runValidation } from "@zerotal/validator";
+import type { FieldRule, Schema } from "@zerotal/validator";
+
+/** Registry of Form subclasses by name, used to reconstruct forms on hydration. */
+const _formClasses = new Map<string, new () => Form>();
+
+/** Register a Form subclass so it can be rebuilt from a snapshot. Called automatically. */
+export function registerForm(FormClass: new () => Form): void {
+  _formClasses.set(FormClass.name, FormClass);
+}
+
+const _RESERVED = new Set(["rules"]);
+
+/**
+ * A reusable bundle of related form fields, their validation rules, and fill/reset helpers,
+ * mounted on a {@link Component} as a single `@expose` property.
+ *
+ * @remarks
+ * Declare fields as plain instance properties and their validation in {@link rules} (built with
+ * `@zerotal/validator`'s fluent {@link RuleBuilder}). Bind inputs with `value={this.form.email}`
+ * (the compiler rewrites it to `flow:model="form.email"`). Validate either from the component
+ * (`this.validate(this.form)`) or directly ({@link validate}); both share the same engine and
+ * error shape. A Form round-trips through a synthesizer, so its class and methods survive
+ * hydration — the subclass must be imported (instantiated at least once) on the server.
+ *
+ * @example
+ * ```tsx
+ * import { Component, expose, Form } from "@zerotal/flow";
+ * import type { RuleBuilder } from "@zerotal/validator";
+ *
+ * class LoginForm extends Form {
+ *   email = "";
+ *   password = "";
+ *   rules(v: RuleBuilder) {
+ *     return { email: v.string().email(), password: v.string().min(8) };
+ *   }
+ * }
+ *
+ * class LoginPage extends Component {
+ *   @expose form = new LoginForm();
+ *
+ *   @expose async submit() {
+ *     this.validate(this.form);        // throws + re-renders with errors on failure
+ *     await Auth.attempt(this.form.data());
+ *   }
+ *
+ *   override async render() {
+ *     return (
+ *       <form data-flow-root flow:submit="submit">
+ *         <input value={this.form.email} />
+ *         <input type="password" value={this.form.password} />
+ *         <button>Log in</button>
+ *       </form>
+ *     );
+ *   }
+ * }
+ * ```
+ */
+export abstract class Form {
+  /** Duck-type marker (avoids cross-module instanceof / import cycles). */
+  readonly __isFlowForm = true as const;
+
+  constructor() {
+    // Auto-register so the synth can reconstruct this subclass on hydration.
+    registerForm(this.constructor as new () => Form);
+  }
+
+  /**
+   * Validation schema, built with the @zerotal/validator RuleBuilder. Override in
+   * the subclass; fields are required by default.
+   *
+   * @example
+   * rules(v: RuleBuilder) {
+   *   return { email: v.string().email(), age: v.number().min(18).optional() };
+   * }
+   */
+
+  rules(_v: RuleBuilder): Record<string, FieldRule> {
+    return {};
+  }
+
+  /** The form's field values — own enumerable data props (excludes rules/methods/_*). */
+  data(): Record<string, unknown> {
+    const out: Record<string, unknown> = {};
+    for (const [k, v] of Object.entries(this)) {
+      if (_RESERVED.has(k) || k.startsWith("_") || typeof v === "function") continue;
+      out[k] = v;
+    }
+    return out;
+  }
+
+  /** Assign matching fields from a plain object (unknown keys ignored). */
+  fill(values: Record<string, unknown>): this {
+    for (const [k, v] of Object.entries(values)) {
+      if (_RESERVED.has(k) || k.startsWith("_")) continue;
+      if (Object.prototype.hasOwnProperty.call(this, k)) {
+        (this as Record<string, unknown>)[k] = v;
+      }
+    }
+    return this;
+  }
+
+  /** Reset fields to their declared defaults — all of them, or just the named ones. */
+  reset(...fields: string[]): this {
+    const fresh = new (this.constructor as new () => this)();
+    const keys = fields.length ? fields : Object.keys(this.data());
+    for (const k of keys) {
+      (this as Record<string, unknown>)[k] = (fresh as Record<string, unknown>)[k];
+    }
+    return this;
+  }
+
+  /**
+   * @internal Run the @zerotal/validator schema against the current data, returning
+   * a field → messages map (empty when valid). Used by `validate()` and by
+   * `Component.validate(form)` so both share the same engine + error shape.
+   */
+  _validateToErrors(): Record<string, string[]> {
+    const factory = this.rules(new RuleBuilder());
+    const schema: Schema = {};
+    for (const [field, rule] of Object.entries(factory)) schema[field] = rule._def;
+
+    const result = runValidation(schema, this.data());
+    if (result.success) return {};
+
+    // Zerotal errors are one message per field; Flow's bag is field → messages[].
+    const out: Record<string, string[]> = {};
+    for (const [field, msg] of Object.entries(result.errors)) out[field] = [msg];
+    return out;
+  }
+
+  /**
+   * Validate the form against its {@link rules} (via `@zerotal/validator`).
+   *
+   * @returns the form's {@link data} on success.
+   * @throws {ValidationError} on failure — the framework catches it and re-renders with errors.
+   */
+  validate(): Record<string, unknown> {
+    const errors = this._validateToErrors();
+    if (Object.keys(errors).length > 0) throw new ValidationError(errors);
+    return this.data();
+  }
+}
+
+// Serialize a Form to its field values + class name; rebuild the right subclass on hydrate.
+registerSynth({
+  key: "form",
+  match: (v): v is Form =>
+    typeof v === "object" && v !== null && (v as { __isFlowForm?: unknown }).__isFlowForm === true,
+  dehydrate(form: Form, meta) {
+    meta["form"] = form.constructor.name;
+    return form.data();
+  },
+  hydrate(data, meta) {
+    const name = meta["form"] as string;
+    const FormClass = _formClasses.get(name);
+    if (!FormClass) {
+      throw new Error(
+        `[Flow] Unknown Form class "${name}". Ensure it is imported (instantiated at least once) on the server.`,
+      );
+    }
+    return new FormClass().fill(data as Record<string, unknown>);
+  },
+});

package/src/Layout.ts

@@ -0,0 +1,47 @@
+import type { HtmlNode } from "./jsx-runtime.ts";
+
+/**
+ * Base class for Flow page layouts — persistent shell UI wrapped around page content.
+ *
+ * @remarks
+ * A layout wraps page content with shell UI (nav, sidebars, footers) that outlives page
+ * navigation. On `flow:navigate`, pages that share the same layout class only swap their
+ * `[data-flow-root]` content; the layout shell stays mounted and is never re-rendered or
+ * re-sent over the socket. Attach one with `static layout = AppLayout` on a {@link Component}
+ * (or override {@link Component.layout} for the JSX-native form).
+ *
+ * @example
+ * ```tsx
+ * export class AppLayout extends Layout {
+ *   static head = `<link rel="stylesheet" href="/app.css">`;
+ *
+ *   render(slot: HtmlNode) {
+ *     return (
+ *       <div>
+ *         <nav>
+ *           <a href="/dashboard" flow:navigate>Dashboard</a>
+ *         </nav>
+ *         <main>{slot}</main>
+ *       </div>
+ *     );
+ *   }
+ * }
+ *
+ * export class DashboardPage extends Component {
+ *   static layout = AppLayout;
+ * }
+ * ```
+ */
+export abstract class Layout {
+  /** Extra HTML injected into `<head>` (stylesheets, fonts, global meta tags). */
+  static head?: string;
+
+  /**
+   * Render the layout shell around a page.
+   *
+   * @param slot  the page's pre-rendered `[data-flow-root]` component node. Place it with
+   *   `{slot}` in JSX — its HTML is emitted verbatim without escaping.
+   * @returns the shell markup wrapping `slot`.
+   */
+  abstract render(slot: HtmlNode): HtmlNode | Promise<HtmlNode>;
+}

package/src/augment.ts

@@ -0,0 +1,94 @@
+import type { PageClassWithMeta } from "./registry.ts";
+import type { MiddlewareClass, RouteRegistration } from "@zerotal/core";
+import type { FlowStore } from "./store.ts";
+
+// Augment the core RouterMacros interface so Router.flow() is fully typed.
+declare module "@zerotal/core" {
+  interface RouterMacros {
+    /**
+     * Register a Flow Component as a GET route.
+     *
+     * Middleware runs on the initial page load AND is re-applied on every
+     * WebSocket update (persistent middleware).
+     *
+     * @example
+     * Router.flow('/dashboard', Dashboard);
+     * Router.flow('/admin', AdminPage, [RequireAuthMiddleware]);
+     */
+    flow(
+      path: string,
+      PageClass: PageClassWithMeta,
+      middleware?: MiddlewareClass[],
+    ): RouteRegistration;
+  }
+}
+
+/**
+ * $flow — the client runtime object, available directly in JSX client expressions
+ * (event handlers, attribute bindings, text children) and `this.client()` scripts.
+ *
+ * It is the single home for all client-only magics, so the component class itself stays
+ * clean. The rule: `this.name` is always YOUR member (state/action); `$flow.name` is always a
+ * framework helper. You write the helpers BARE (`$flow.set`, `$flow.store`, `$flow.parent`) and
+ * the AOT compiler rewrites each to its canonical `$`-form (`$flow.$set`, …) for the runtime.
+ *
+ *   $flow.set("open", true)           write + sync an @expose property
+ *   $flow.toggle("open")              toggle + sync a boolean @expose property
+ *   $flow.store.ui.dark               the global client store (typed by FlowStore)
+ *   $flow.parent.save()               call an action / read state on the parent
+ *   onClick={this.save}              dispatch YOUR server action `save`
+ */
+declare global {
+  var $flow: {
+    // Reactive property reads/writes ($flow.count) and dynamic action calls. `any` because this
+    // object mixes dynamic members with the typed helpers below; the index signature can't be
+    // narrower than both.
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    [member: string]: any;
+
+    // Component identity (always $-prefixed — no bare form)
+    readonly $el: HTMLElement;
+    readonly $id: string;
+    readonly $name: string;
+
+    // Re-render
+    refresh(): void;
+    commit(): void;
+
+    // Property helpers
+    get(prop: string): unknown;
+    set(prop: string, value: unknown): void;
+    toggle(prop: string): void;
+
+    // Explicit method call
+    call(method: string, ...args: unknown[]): void;
+
+    // Cross-component events
+    dispatch(event: string, data?: Record<string, unknown>): void;
+    dispatchTo(component: string, event: string, data?: Record<string, unknown>): void;
+    dispatchSelf(event: string, data?: Record<string, unknown>): void;
+    on(event: string, fn: (detail: unknown) => void): void;
+
+    // Watch reactive property changes after server patches
+    watch(prop: string, fn: (newVal: unknown, oldVal: unknown) => void): void;
+
+    // Call actions on / read state from the parent component
+    readonly parent: Record<string, ((...args: unknown[]) => void) & unknown>;
+
+    // Global client store — app-wide, client-only reactive UI state (typed by FlowStore).
+    readonly store: FlowStore;
+
+    // Presence whispers (ephemeral peer state; never touches the server/DB)
+    whisper(event: string, data: unknown): void;
+    onWhisper(event: string, fn: (data: unknown) => void): void;
+
+    // Stop this component's running @task
+    cancel(): void;
+
+    // Optimistic list mutations (reconciled when the next action lands)
+    appendOptimistic<T>(prop: string, item: T): void;
+    removeOptimistic<T>(prop: string, match: (item: T) => boolean): void;
+  };
+}
+
+export {};

package/src/client/FlowClientError.ts

@@ -0,0 +1,12 @@
+// Client-safe base error for Flow's browser runtime.
+//
+// This module is bundled into the CSP-safe client runtime, so it deliberately
+// extends the native `Error` rather than `@zerotal/core`'s `ZerotalError`: pulling
+// the server framework into the browser bundle is exactly what the CSP-safe runtime
+// must avoid. Client-side Flow errors extend this class for a consistent base.
+export class FlowClientError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = this.constructor.name;
+  }
+}

package/src/client/FlowComponent.ts

@@ -0,0 +1,96 @@
+// ── Client-side component state model ────────────────────────────────────────
+//
+// Mirrors Livewire v3's three-copy state model:
+//   canonical  — last confirmed server state (used for diffing)
+//   ephemeral  — current local state (may have unsent mutations from flow:model)
+//   reactive   — Alpine.reactive(ephemeral) — what DOM expressions read
+//
+// When a server patch arrives, we diff canonical vs. new to determine what
+// changed and patch reactive in-place — preserving Alpine reactivity subscriptions
+// instead of wholesale replacement.
+
+import type { Snapshot, SnapshotData } from "../types.ts";
+
+export type ReactiveProxy = Record<string, unknown>;
+
+/** Extract plain JS values from snapshot data (strip synth meta). */
+function extractValues(data: SnapshotData): Record<string, unknown> {
+  const result: Record<string, unknown> = {};
+  for (const [key, [val]] of Object.entries(data)) {
+    result[key] = val;
+  }
+  return result;
+}
+
+function deepClone<T>(v: T): T {
+  return JSON.parse(JSON.stringify(v)) as T;
+}
+
+/** Recursively diff old/new and patch reactive in-place. */
+function diffAndPatch(
+  oldVal: Record<string, unknown>,
+  newVal: Record<string, unknown>,
+  reactive: Record<string, unknown>,
+): void {
+  for (const [k, next] of Object.entries(newVal)) {
+    if (JSON.stringify(oldVal[k]) !== JSON.stringify(next)) {
+      // Deep-clone objects so that reactive mutations (from user input via flow:model)
+      // do not alias back into canonical/snapshot, which share the same references
+      // via extractValues. Without cloning, typing in a flow:model input would corrupt
+      // comp.snapshot.data causing the HMAC to fail on the next server call.
+      reactive[k] = typeof next === "object" && next !== null ? deepClone(next) : next;
+    }
+  }
+  // Remove keys that no longer exist
+  for (const k of Object.keys(oldVal)) {
+    if (!(k in newVal)) {
+      delete reactive[k];
+    }
+  }
+}
+
+export class FlowComponent {
+  readonly id: string;
+  readonly name: string;
+  readonly rootEl: HTMLElement;
+
+  canonical: Record<string, unknown>;
+  ephemeral: Record<string, unknown>;
+  reactive: ReactiveProxy;
+
+  snapshot: Snapshot;
+
+  constructor(rootEl: HTMLElement, snapshot: Snapshot) {
+    this.id = snapshot.memo.id;
+    this.name = snapshot.memo.name;
+    this.rootEl = rootEl;
+    this.snapshot = snapshot;
+
+    this.canonical = extractValues(snapshot.data);
+    this.ephemeral = deepClone(this.canonical);
+
+    // Alpine.reactive is available globally once Alpine starts
+    this.reactive = (
+      window as unknown as { Alpine: { reactive(o: object): ReactiveProxy } }
+    ).Alpine.reactive(this.ephemeral);
+  }
+
+  /** Apply a server patch: update snapshot, diff-patch reactive, update script tag. */
+  mergeServerPatch(newSnapshot: Snapshot): void {
+    const newCanonical = extractValues(newSnapshot.data);
+    // Compare the current reactive state (not just canonical) so that lazy
+    // flow:model fields that diverged during typing are corrected when the
+    // server returns the authoritative value (e.g., clearing draft after add()).
+    // Using a plain-object snapshot avoids mutating the comparison source
+    // while diffAndPatch iterates it for key-removal.
+    const reactiveSnapshot = { ...this.reactive } as Record<string, unknown>;
+    diffAndPatch(reactiveSnapshot, newCanonical, this.reactive);
+    this.canonical = newCanonical;
+    this.ephemeral = deepClone(newCanonical);
+    this.snapshot = newSnapshot;
+
+    // Keep the embedded <script id="flow-state-*"> in sync
+    const script = document.getElementById(`flow-state-${this.id}`);
+    if (script) script.textContent = JSON.stringify(newSnapshot);
+  }
+}

package/src/client/alpinejs-morph.d.ts

@@ -0,0 +1,5 @@
+declare module '@alpinejs/morph' {
+  import type Alpine from 'alpinejs';
+  const morph: (Alpine: typeof Alpine) => void;
+  export default morph;
+}