@zerotal/flow 1.0.0

package/src/mixins.ts

@@ -0,0 +1,199 @@
+// ── Component mixins ────────────────────────────────────────────────────────
+//
+// `ComponentWith(...)` composes any number of feature mixins on top of `Component`,
+// so a page can be broken into focused, reusable behaviours (pagination, file uploads,
+// sortable tables, …) that stack left-to-right instead of bloating one class — the
+// Flow counterpart of the ORM's `BaseModelWith(...)`:
+//
+//   // before — one class carrying every feature inline, base repeated per mixin
+//   class UsersPage extends FileUploads(Pagination(Component)) { … }
+//
+//   // after — flat, left-to-right, base baked in
+//   class UsersPage extends ComponentWith(Pagination, FileUploads) {
+//     async render() { … }   // the page only owns its own markup + state
+//   }
+//
+// A Component mixin is the canonical generic form below — note it extends an ABSTRACT
+// base and returns an `abstract class`, so it doesn't have to implement Component's
+// abstract `render()` (the final page supplies it):
+//
+//   // app/flow/mixins/file-upload.ts
+//   import { Component, expose, type Constructor } from "@zerotal/flow";
+//
+//   export function FileUpload<T extends Constructor<Component>>(Base: T) {
+//     abstract class WithUpload extends Base {
+//       @expose uploading = false;
+//       @expose async upload() { … }
+//     }
+//     return WithUpload;
+//   }
+//
+// Because each mixin returns `class extends Base`, Component's full surface (`flash()`,
+// `redirect()`, `validate()`, the `this.set`/`refresh`/… client magics, …) and every other
+// mixin's members flow through to the final page — fully type-checked. The shipped
+// `Pagination` mixin (see ./pagination.ts) is written exactly this way and composes here:
+// `ComponentWith(Pagination)`.
+//
+// Mixin `@expose`/`@locked` props register on the mixin's prototype, which sits in the page's
+// prototype chain — so they're discovered at runtime exactly like props declared on the page
+// itself (snapshot, reactivity, client writes, `@url` sync all work). Note: pages composed
+// with `ComponentWith(...)` render via the runtime path rather than the AOT compiler (which
+// only statically sees a page's own `extends Component` + locally-declared members) — the same
+// fallback complex pages already use; behaviour is identical, you just don't get the
+// ahead-of-time compile step for that page.
+
+import { Component } from "./Component.ts";
+
+/**
+ * A class constructor. Abstract-aware (`abstract new …`) so the abstract `Component` base —
+ * and mixin classes that don't yet implement `render()` — satisfy it. Use `Constructor<Component>`
+ * as a mixin's base bound to require a Component lineage.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- generic mixin base bound
+export type Constructor<T = object> = abstract new (...args: any[]) => T;
+
+/**
+ * A Component mixin: receives a base constructor and returns an extended one. Authors write
+ * the generic form so the mixin composes onto whatever base it is given:
+ *
+ *   export function FileUpload<T extends Constructor<Component>>(Base: T) {
+ *     abstract class WithUpload extends Base { … }
+ *     return WithUpload;
+ *   }
+ */
+export type Mixin<TIn extends Constructor = Constructor, TOut extends Constructor = Constructor> = (
+  Base: TIn,
+) => TOut;
+
+type Base = typeof Component;
+
+/**
+ * Compose one or more feature {@link Mixin}s onto {@link Component}, folding them left-to-right
+ * so a page can be built from focused, reusable behaviours instead of one bloated class.
+ *
+ * @remarks
+ * Each mixin receives the accumulated base and returns an extended class, so `Component`'s full
+ * surface (`flash()`, `redirect()`, `validate()`, the client magics, …) and every mixin's
+ * `@expose`/`@locked` members flow through to the final page — fully type-checked. Mixin props
+ * register on the mixin prototype, which sits in the page's prototype chain, so snapshot,
+ * reactivity, and client writes all work. Overloads cover 1–8 mixins; nest another
+ * `ComponentWith(...)` call for more. Pages composed this way render via the runtime path rather
+ * than the AOT compiler.
+ *
+ * @param mixins  mixin factories applied left-to-right (each takes the prior result as its base).
+ * @returns a class extending `Component` with every mixin's members mixed in.
+ *
+ * @example
+ * ```tsx
+ * // app/flow/mixins/pagination.ts
+ * import { Component, expose, type Constructor } from "@zerotal/flow";
+ *
+ * export function Pagination<T extends Constructor<Component>>(Base: T) {
+ *   abstract class WithPagination extends Base {
+ *     @expose page = 1;
+ *     @expose next() { this.page++; }
+ *   }
+ *   return WithPagination;
+ * }
+ *
+ * // app/flow/UsersPage.tsx
+ * class UsersPage extends ComponentWith(Pagination) {
+ *   override async render() {
+ *     return <div data-flow-root>Page {this.page}</div>;
+ *   }
+ * }
+ * ```
+ */
+export function ComponentWith<A extends Constructor>(a: (base: Base) => A): A;
+export function ComponentWith<A extends Constructor, B extends Constructor>(
+  a: (base: Base) => A,
+  b: (base: A) => B,
+): B;
+export function ComponentWith<A extends Constructor, B extends Constructor, C extends Constructor>(
+  a: (base: Base) => A,
+  b: (base: A) => B,
+  c: (base: B) => C,
+): C;
+export function ComponentWith<
+  A extends Constructor,
+  B extends Constructor,
+  C extends Constructor,
+  D extends Constructor,
+>(a: (base: Base) => A, b: (base: A) => B, c: (base: B) => C, d: (base: C) => D): D;
+export function ComponentWith<
+  A extends Constructor,
+  B extends Constructor,
+  C extends Constructor,
+  D extends Constructor,
+  E extends Constructor,
+>(
+  a: (base: Base) => A,
+  b: (base: A) => B,
+  c: (base: B) => C,
+  d: (base: C) => D,
+  e: (base: D) => E,
+): E;
+export function ComponentWith<
+  A extends Constructor,
+  B extends Constructor,
+  C extends Constructor,
+  D extends Constructor,
+  E extends Constructor,
+  F extends Constructor,
+>(
+  a: (base: Base) => A,
+  b: (base: A) => B,
+  c: (base: B) => C,
+  d: (base: C) => D,
+  e: (base: D) => E,
+  f: (base: E) => F,
+): F;
+export function ComponentWith<
+  A extends Constructor,
+  B extends Constructor,
+  C extends Constructor,
+  D extends Constructor,
+  E extends Constructor,
+  F extends Constructor,
+  G extends Constructor,
+>(
+  a: (base: Base) => A,
+  b: (base: A) => B,
+  c: (base: B) => C,
+  d: (base: C) => D,
+  e: (base: D) => E,
+  f: (base: E) => F,
+  g: (base: F) => G,
+): G;
+export function ComponentWith<
+  A extends Constructor,
+  B extends Constructor,
+  C extends Constructor,
+  D extends Constructor,
+  E extends Constructor,
+  F extends Constructor,
+  G extends Constructor,
+  H extends Constructor,
+>(
+  a: (base: Base) => A,
+  b: (base: A) => B,
+  c: (base: B) => C,
+  d: (base: C) => D,
+  e: (base: D) => E,
+  f: (base: E) => F,
+  g: (base: F) => G,
+  h: (base: G) => H,
+): H;
+
+// Implementation: fold the mixins over Component, left to right. The base param is `any` so
+// each typed overload above (whose base is the narrower `typeof Component` or a prior mixin's
+// result) stays assignable to this implementation signature.
+export function ComponentWith(
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- variadic mixin folder
+  ...mixins: Array<(base: any) => Constructor>
+): Constructor {
+  return mixins.reduce<Constructor>(
+    (acc, mixin) => mixin(acc),
+    Component as unknown as Constructor,
+  );
+}

package/src/observability.ts

@@ -0,0 +1,167 @@
+/**
+ * Flow → observer bridges. Flow emits its own realtime framework events
+ * (`WebSocketConnected` / `WebSocketDisconnected` / `FlowActionHandled`) on the
+ * core `FrameworkEvents` bus; this module forwards them to whichever observer
+ * packages are installed.
+ *
+ * A Flow action round-trips like a request, so its monitor record carries the
+ * same correlated per-request state (queries, N+1 flag, custom context) that other
+ * packages buffered against the action's HttpContext — drained here through the
+ * store's `collectRequestState`.
+ *
+ * Each observer's write surface is resolved from the container by binding key and
+ * typed through a local structural interface, so Flow depends on none of the
+ * observer packages — installing or removing an observer requires no change here.
+ */
+import { FrameworkEvents } from "@zerotal/core";
+import type { Application } from "@zerotal/core";
+import { WebSocketConnected, WebSocketDisconnected, FlowActionHandled } from "./frameworkEvents.ts";
+
+/** The subset of the monitor store this bridge calls (bound as `monitor.store`). */
+interface MonitorSink {
+  recordEvent(e: {
+    kind: string;
+    label: string;
+    status?: "ok" | "warn" | "bad" | "info";
+    route?: string | null;
+    data?: Record<string, unknown>;
+  }): void;
+  collectRequestState(ctx: object): {
+    queries: unknown[];
+    nplus: boolean;
+    context: Record<string, unknown>;
+    payload: unknown;
+  };
+}
+
+/** The subset of the devtools trace sink this bridge calls (bound as `devtools.trace`). */
+interface DevtoolsSink {
+  channel(descriptor: {
+    id: string;
+    label: string;
+    badge?: string;
+    title?: string;
+    meta?: string[];
+    warn?: string;
+    order?: number;
+  }): void;
+  record(ctx: object, channel: string, entry: Record<string, unknown>): void;
+}
+
+// Framework/asset noise the panel shouldn't chart as realtime traffic.
+const IGNORE_PREFIXES = ["/monitor", "/metrics", "/__flow", "/__zerotal", "/__dev", "/health"];
+
+/** Raw request path from an HttpContext (best-effort). */
+function _rawPath(ctx: object): string {
+  return (ctx as { url?: { pathname?: string } }).url?.pathname ?? "/";
+}
+
+/** Authenticated user identity (email → id → name), or null when unauthenticated. */
+function _ctxUser(ctx: object): string | null {
+  const u = (ctx as { user?: unknown }).user;
+  if (u == null) return null;
+  if (typeof u === "string" || typeof u === "number") return String(u);
+  if (typeof u === "object") {
+    const o = u as Record<string, unknown>;
+    const v = o.email ?? o.id ?? o.name;
+    return v != null ? String(v) : null;
+  }
+  return null;
+}
+
+/**
+ * Resolve an observer's write surface, or `undefined` when that package is not
+ * installed. The cast is confined here: each binding is declared by the package
+ * that owns it, and Flow deliberately depends on none of them.
+ */
+function _observer<T>(app: Application, binding: string): T | undefined {
+  return app.container.tryMake(binding as never) as T | undefined;
+}
+
+/**
+ * Subscribe Flow's realtime events to every installed observer. Returns a disposer
+ * that removes every subscription; call it from the Flow provider's `onStopping()`.
+ */
+export function installFlowObservability(app: Application): () => void {
+  const unsubs: Array<() => void> = [];
+
+  const store = _observer<MonitorSink>(app, "monitor.store");
+  if (store) {
+    unsubs.push(
+      FrameworkEvents.on(WebSocketConnected, () =>
+        store.recordEvent({ kind: "ws", label: "connect", status: "info" }),
+      ),
+      FrameworkEvents.on(WebSocketDisconnected, () =>
+        store.recordEvent({ kind: "ws", label: "disconnect", status: "info" }),
+      ),
+      FrameworkEvents.on(FlowActionHandled, (e) => {
+        const ctx = e.ctx;
+        // Skip the monitor panel's own components — its poll/refresh round-trips would
+        // otherwise dominate the realtime view. Draining discards their buffered state.
+        if (ctx && IGNORE_PREFIXES.some((p) => _rawPath(ctx).startsWith(p))) {
+          store.collectRequestState(ctx);
+          return;
+        }
+        // Pull the same correlated context an HTTP request gets: the user (set by
+        // re-run middleware), the client IP, and the SQL queries tied to this action.
+        const state = ctx
+          ? store.collectRequestState(ctx)
+          : { queries: [] as unknown[], nplus: false, context: {} as Record<string, unknown> };
+        store.recordEvent({
+          kind: "ws",
+          label: "action",
+          status: e.ok ? "ok" : "bad",
+          route: e.component,
+          data: {
+            component: e.component,
+            action: e.action,
+            ms: Math.round(e.durationMs),
+            ok: e.ok,
+            user: ctx ? _ctxUser(ctx) : null,
+            ip: e.ip,
+            nplus: state.nplus,
+            // Process heap at action completion — the same per-request memory proxy
+            // HTTP requests record, captured synchronously in the emit call stack.
+            memKb: Math.round(process.memoryUsage().heapUsed / 1024),
+            nQueries: state.queries.length,
+            queries: state.queries.slice(0, 25),
+            context: state.context,
+          },
+        });
+      }),
+    );
+  }
+
+  const trace = _observer<DevtoolsSink>(app, "devtools.trace");
+  if (trace) {
+    trace.channel({
+      id: "flow",
+      label: "Flow",
+      badge: "component",
+      title: "action",
+      meta: ["durationMs", "ip"],
+      warn: "failed",
+      order: 20,
+    });
+
+    unsubs.push(
+      FrameworkEvents.on(FlowActionHandled, (e) => {
+        // An action round-trips over the WebSocket against its own HttpContext,
+        // so it buffers against that context and lands on that action's trace.
+        if (!e.ctx) return;
+        if (IGNORE_PREFIXES.some((p) => _rawPath(e.ctx as object).startsWith(p))) return;
+        trace.record(e.ctx as object, "flow", {
+          component: e.component,
+          action: e.action,
+          durationMs: Math.round(e.durationMs),
+          ip: e.ip,
+          ...(e.ok ? {} : { failed: true }),
+        });
+      }),
+    );
+  }
+
+  return () => {
+    for (const unsub of unsubs) unsub();
+  };
+}

package/src/pagination.ts

@@ -0,0 +1,300 @@
+// ── In-memory pagination ──────────────────────────────────────────────────────
+//
+// Pairs with `@expose @url page` to paginate an in-memory array (filtered/derived
+// data) inside render() or onMount(). For database queries, prefer the ORM's
+// query builder `.paginate(perPage, page)` — this helper is for arrays you already
+// hold in memory. The result shape mirrors the ORM paginator for consistency.
+
+/**
+ * The result of paginating an in-memory array — one page of `data` plus the
+ * surrounding metadata a view needs to render a pager.
+ *
+ * The shape intentionally mirrors the ORM query builder's paginator, so a
+ * template can consume either interchangeably.
+ *
+ * @typeParam T - Element type of the paginated array.
+ *
+ * @example
+ * ```ts
+ * const page = paginate(posts, 2, 10);
+ * page.data;         // the 10 items on page 2
+ * page.from;         // 11
+ * page.hasMorePages; // true if a page 3 exists
+ * page.elements();   // [1, 2, 3, '...', 20]
+ * ```
+ */
+export interface Paginator<T> {
+  /**
+   * The items on the current page (a slice of the input array).
+   * @category Access
+   */
+  data: T[];
+  /**
+   * Total item count across all pages.
+   * @category Metadata
+   */
+  total: number;
+  /**
+   * Items per page (the effective, floored value; at least 1).
+   * @category Metadata
+   */
+  perPage: number;
+  /**
+   * Current page (1-based, clamped to a valid range).
+   * @category Metadata
+   */
+  page: number;
+  /**
+   * Last page number (>= 1; 1 even when there are no items).
+   * @category Metadata
+   */
+  lastPage: number;
+  /**
+   * 1-based index of the first item on this page (0 when empty).
+   * @category Metadata
+   */
+  from: number;
+  /**
+   * 1-based index of the last item on this page (0 when empty).
+   * @category Metadata
+   */
+  to: number;
+  /**
+   * True when on page 1.
+   * @category Metadata
+   */
+  onFirstPage: boolean;
+  /**
+   * True when a further page exists.
+   * @category Metadata
+   */
+  hasMorePages: boolean;
+  /**
+   * Page-number window for rendering a numbered pager, with `'...'` gaps —
+   * e.g. `[1, '...', 4, 5, 6, '...', 20]`. The first and last pages are always
+   * included.
+   *
+   * @param each - How many page links to show on each side of the current page (default `1`).
+   * @returns A list of page numbers interleaved with `'...'` for elided ranges.
+   * @category Navigation
+   */
+  elements(each?: number): (number | "...")[];
+}
+
+/**
+ * Paginate an in-memory array — the array counterpart to the ORM's
+ * `.paginate(perPage, page)`. Use this for filtered/derived data you already
+ * hold in memory (e.g. inside `render()` or `onMount()`); for database queries
+ * prefer the query builder's paginator.
+ *
+ * `page` is clamped into `[1, lastPage]` and `perPage` is floored to at least 1,
+ * so out-of-range input never throws.
+ *
+ * @typeParam T - Element type of `items`.
+ * @param items - The full, already-in-memory collection to page over.
+ * @param page - 1-based page to return (clamped; default `1`).
+ * @param perPage - Items per page (floored to >= 1; default `15`).
+ * @returns A {@link Paginator} for the requested page.
+ *
+ * @example
+ * ```ts
+ * const results = posts.filter((p) => p.published);
+ * const page = paginate(results, this.page, 10);
+ * for (const post of page.data) { ... }
+ * ```
+ */
+export function paginate<T>(items: T[], page = 1, perPage = 15): Paginator<T> {
+  const total = items.length;
+  perPage = Math.max(1, Math.floor(perPage));
+  const lastPage = Math.max(1, Math.ceil(total / perPage));
+  const currentPage = Math.min(Math.max(1, Math.floor(page) || 1), lastPage);
+  const offset = (currentPage - 1) * perPage;
+  const data = items.slice(offset, offset + perPage);
+  return {
+    data,
+    total,
+    perPage,
+    page: currentPage,
+    lastPage,
+    from: total === 0 ? 0 : offset + 1,
+    to: offset + data.length,
+    onFirstPage: currentPage <= 1,
+    hasMorePages: currentPage < lastPage,
+    elements(each = 1) {
+      return pageElements(currentPage, lastPage, each);
+    },
+  };
+}
+
+// ── 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`,
+// `previousPage`, `gotoPage`, `resetPage`), WITHOUT putting any of that on
+// the base Component.
+//
+//   class PostsPage extends ComponentWith(Pagination) {
+//     @locked posts: Post[] = [];
+//     async onMount() { this.posts = await Post.all(); }
+//     async render() {
+//       const posts = await Post.paginate(10);      // uses this.page
+//       return <div>…{p.data.map(…)}… pager with this.nextPage / ?page= links</div>;
+//     }
+//   }
+//
+// `page` is @expose + @url (in the snapshot, synced to ?page=). The nav methods are
+// @expose, so they're callable from the browser (onClick={this.nextPage}). Decorators
+// 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
+// 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
+// `updatingPage(page, name)` / `updatedPage(page, name)` (default paginator) or the
+// generic `updatingPaginators(page, name)` / `updatedPaginators(page, name)`.
+
+import { Component } from "./Component.ts";
+import { expose, url } from "./decorators.ts";
+import { setCurrentPageResolver, pageElements, type HttpContext } from "@zerotal/core";
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type AbstractComponentCtor = abstract new (...args: any[]) => Component;
+
+/** Optional, user-defined pagination lifecycle hooks (all optional). */
+interface PaginationHooks {
+  updatingPage?(page: number, pageName: string): void;
+  updatedPage?(page: number, pageName: string): void;
+  updatingPaginators?(page: number, pageName: string): void;
+  updatedPaginators?(page: number, pageName: string): void;
+}
+
+const DEFAULT_PAGE = "page";
+
+/**
+ * Component mixin that adds URL-synced pagination state and navigation actions —
+ * flow's equivalent of Livewire's `WithPagination` trait.
+ *
+ * @remarks
+ * Composing this onto a component adds:
+ * - a `page` field, `@expose`d and `@url`-synced to the `?page=` query string;
+ * - a `paginators` map holding the page of each NAMED paginator (snapshot-only),
+ *   so a single component can drive several independent pagers by passing a
+ *   `pageName` (e.g. `nextPage("invoices")`, `paginate(rows, 10, "invoices")`);
+ * - `@expose`d navigation actions callable straight from the browser:
+ *   {@link Paginated.gotoPage | gotoPage}, `resetPage`, `nextPage`,
+ *   `previousPage`;
+ * - a `paginate(items, perPage, pageName?)` helper that slices an in-memory array
+ *   at the current page.
+ *
+ * All page writes clamp to `>= 1`. Optional lifecycle hooks fire around a page
+ * change if you define them: `updatingPage`/`updatedPage` (default paginator) and
+ * the generic `updatingPaginators`/`updatedPaginators`. Call `resetPage()` when a
+ * filter or search term changes so the user isn't stranded on an empty page.
+ *
+ * @typeParam TBase - The (abstract) Component constructor being extended.
+ * @param Base - The component class to mix into.
+ * @returns A subclass of `Base` with pagination state and navigation.
+ *
+ * @example
+ * ```tsx
+ * class PostsPage extends ComponentWith(Pagination) {
+ *   @locked posts: Post[] = [];
+ *   async onMount() { this.posts = await Post.all(); }
+ *   async render() {
+ *     const posts = await Post.paginate(10); // uses this.page
+ *     return (
+ *       <div>
+ *         {p.data.map((post) => <PostCard post={post} />)}
+ *         <button onClick={this.previousPage} disabled={p.onFirstPage}>Prev</button>
+ *         <button onClick={this.nextPage} disabled={!p.hasMorePages}>Next</button>
+ *       </div>
+ *     );
+ *   }
+ * }
+ * ```
+ */
+export function Pagination<TBase extends AbstractComponentCtor>(Base: TBase) {
+  abstract class Paginated extends Base {
+    /** 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. */
+    @expose paginators: Record<string, number> = {};
+
+    /**
+     * Read the current page for a paginator (default or named).
+     * @param pageName - Named paginator; omit for the default URL-synced one.
+     * @returns The current 1-based page (>= 1).
+     * @category Access
+     */
+    pageFor(pageName: string = DEFAULT_PAGE): number {
+      if (pageName === DEFAULT_PAGE) return this.page;
+      return this.paginators[pageName] ?? 1;
+    }
+
+    /**
+     * Point database pagination at this component's page, for the rest of the request.
+     *
+     * With it, `Post.paginate(10)` inside the component returns the page the user is on —
+     * no page argument to thread through. It runs on every request because a WebSocket
+     * action carries no `?page=` for the query string to fall back on; the page lives here.
+     */
+    override async onBoot(ctx?: HttpContext): Promise<void> {
+      await super.onBoot(ctx);
+      setCurrentPageResolver((pageName) => this.pageFor(pageName));
+    }
+
+    /** Write a paginator's page (clamped to >= 1), firing the update hooks around it.
+     *  Internal — not `@expose`, so it's never callable from the client. */
+    _setPageValue(pageName: string, value: number): void {
+      const next = Math.max(1, Math.floor(Number(value)) || 1);
+      if (next === this.pageFor(pageName)) return;
+
+      const hooks = this as unknown as PaginationHooks;
+      hooks.updatingPaginators?.(next, pageName);
+      if (pageName === DEFAULT_PAGE) hooks.updatingPage?.(next, pageName);
+
+      if (pageName === DEFAULT_PAGE) this.page = next;
+      else this.paginators = { ...this.paginators, [pageName]: next };
+
+      if (pageName === DEFAULT_PAGE) hooks.updatedPage?.(next, pageName);
+      hooks.updatedPaginators?.(next, pageName);
+    }
+
+    /**
+     * Jump to a specific page (clamped to >= 1).
+     * @param p - Target 1-based page.
+     * @param pageName - Named paginator; omit for the default.
+     * @category Navigation
+     */
+    @expose gotoPage(p: number, pageName: string = DEFAULT_PAGE): void {
+      this._setPageValue(pageName, p);
+    }
+    /**
+     * Reset to page 1 — call this when filters/search change so the user isn't
+     * left on a now-empty page.
+     * @category Navigation
+     */
+    @expose resetPage(pageName: string = DEFAULT_PAGE): void {
+      this._setPageValue(pageName, 1);
+    }
+    /**
+     * Advance to the next page.
+     * @category Navigation
+     */
+    @expose nextPage(pageName: string = DEFAULT_PAGE): void {
+      this._setPageValue(pageName, this.pageFor(pageName) + 1);
+    }
+    /**
+     * Go back one page (clamped to >= 1).
+     * @category Navigation
+     */
+    @expose previousPage(pageName: string = DEFAULT_PAGE): void {
+      this._setPageValue(pageName, this.pageFor(pageName) - 1);
+    }
+  }
+  return Paginated;
+}