@orieljs/live 0.1.0-alpha.3 → 0.1.0-alpha.5

package/NOTICE

@@ -0,0 +1,9 @@
+Oriel
+Copyright 2026 meeeet-dev and Oriel contributors
+
+This product includes software developed by the Oriel project
+(https://orieljs.vercel.app, https://github.com/orieljs).
+
+Oriel is licensed under the Apache License, Version 2.0 (see LICENSE).
+The Oriel name and logo are not covered by that license; see TRADEMARKS.md
+(https://github.com/orieljs/framework/blob/main/TRADEMARKS.md).

package/README.md

@@ -33,7 +33,51 @@ Route.get('/counter', Counter)
 
 Embed a component in any view with `<Live component={Counter} />`. In the browser, components are driven by `@orieljs/live-client`.
 
-Known limitations:
+## Pagination
+
+```tsx
+import { Component, Pagination, WithPagination } from '@orieljs/framework'
+import { Post } from '../Models/Post'
+
+export default class Posts extends WithPagination(Component) {
+  search = ''
+
+  updatedSearch() {
+    this.resetPage()
+  }
+
+  async render() {
+    const posts = await Post.whereLike('title', `%${this.search}%`).latest().paginate(10)
+    return (
+      <div>
+        <input o:model-live="search" aria-label="Search" />
+        {posts.items().map((post) => <p>{post.title}</p>)}
+        <Pagination paginator={posts} class="flex gap-2" />
+      </div>
+    )
+  }
+}
+```
+
+`paginate()` in the component (in `render()`, in `mount()`, in actions and the update hooks, or in a `@Computed`
+getter any of them reads) shows the component's `page`, and its links are built on the page's URL. The actions
+`nextPage`, `previousPage`, `gotoPage(n)`, `setPage(n)` and `resetPage` move it; `<Pagination>` renders them as
+buttons with the kits' `btn` classes. The page starts at 1 and isn't kept in the address bar.
+
+## Middleware on updates
+
+Each update re-runs the `auth`, `verified`, `guest` and `can` middleware of the route that rendered the page
+(Livewire's persistent middleware), with that route's parameters bound again, so `can:update,post` sees the post. A
+signed-out tab gets a 401 and a user who lost the ability a 403, before the component's actions run. On a page behind
+one of these middleware, a model deleted since the page rendered gets a 404 too; a page with none binds nothing on
+updates. The list is `live.persistent_middleware` in `config/live.ts`.
+
+## Flash data in updates
+
+A status an action flashes (`session().flash('status', 'Saved.')`) shows in that update's response only, unless the
+action redirects or navigates: then it is there on the next page. Component state is unaffected.
+
+## Known limitations
 
 - `o:navigate` does not run scripts in the new page.
 - A DOM event whose name contains `-` can't be written as `o:<event>` in TSX, because modifiers are `-` segments (for example `o:model-live`).

package/dist/index.d.ts

@@ -1,4 +1,5 @@
-import { Class, Rules, MessageBag, LiveEffects, Htmlable, LiveSnapshot, LiveManager, Application, HttpRequest, LiveUpdateRequest, LiveUpdateResponse, OrielError, ErrorKind } from '@orieljs/contracts';
+import * as _orieljs_contracts from '@orieljs/contracts';
+import { Class, Rules, MessageBag, LiveEffects, Htmlable, LiveSnapshot, LiveManager, Application, HttpRequest, LiveUpdateRequest, LiveUpdateResponse, OrielError, ErrorKind, MiddlewareClass, Router } from '@orieljs/contracts';
 import { ServiceProvider } from '@orieljs/support';
 
 /** Marks Live component classes (Symbol.for, so two copies of the package agree). */
@@ -84,13 +85,22 @@ declare function Locked(_target: unknown, context: ClassFieldDecoratorContext |
 /** @Computed: a getter cached for the rest of the request, never part of the component's state. */
 declare function Computed<T>(getter: (this: object) => T, context: ClassGetterDecoratorContext): (this: object) => T;
 
+/**
+ * Runs Live.test()'s mount and each update. The testing package binds one for every test, so they run in a request
+ * scope like the test's HTTP requests (a request, the carried session, actingAs users) and what they change carries
+ * on to the next request. Without one they run in the current scope.
+ */
+type TestRequestScope = <T>(run: () => Promise<T>) => Promise<T>;
+declare const TestRequestScope: _orieljs_contracts.Token<TestRequestScope>;
 /**
  * Livewire's Livewire::test(): drives one component through the real mount → snapshot → checksum → update pipeline
- * (no HTTP). Actions are async (`await counter.call('increment')`); assertions are sync and return `this`.
+ * (no HTTP), inside the test's request scope. Actions are async (`await counter.call('increment')`); assertions are
+ * sync and return `this`.
  */
 declare class Testable<C extends Component = Component> {
     #private;
     private readonly manager;
+    private readonly scope;
     private constructor();
     /** Mounts `component` with `params`, as `<Live component={…} {...params} />` would. */
     static create<C extends Component>(component: Class<C> | string, params?: Record<string, unknown>): Promise<Testable<C>>;
@@ -178,8 +188,14 @@ declare class LiveComponentManager implements LiveManager {
     /** Applies each component's updates and calls, re-renders it and returns its new snapshot and effects. */
     update(request: LiveUpdateRequest): Promise<LiveUpdateResponse>;
     updateComponent(snapshotJson: string, updates: Record<string, unknown>, calls: Call[]): Promise<ComponentResult>;
-    /** The route action of POST /oriel/live/update. */
-    handle(request: HttpRequest): Promise<LiveUpdateResponse>;
+    /**
+     * The route action of POST /oriel/live/update. Each component's update runs behind the persistent middleware of the
+     * route that rendered its page (Livewire's): `auth`, `verified`, `guest` and `can`, with the page route's parameters
+     * bound again. A signed-out tab gets a 401, a revoked ability a 403 and a deleted model a 404, before the component
+     * hydrates. When a middleware answers instead (a redirect), that is the response. A key first flashed during the
+     * update shows in this response only, unless the update redirects.
+     */
+    handle(request: HttpRequest): Promise<LiveUpdateResponse | Response>;
     /** A full-page component (Route.get('/counter', Counter)): mounted with the route parameters, inside the layout. */
     page(component: Component): Promise<unknown>;
     /** Parses and checks a snapshot: a bad checksum throws before anything is hydrated. */
@@ -192,8 +208,14 @@ declare class LiveComponentManager implements LiveManager {
     private applyUpdate;
     /** Runs one call from the browser: a magic action, an event, or a public method. Returns its return value. */
     private call;
-    /** Renders the component (rendering/rendered hooks, nested children tracked) and checks for a single root. */
+    /**
+     * Renders the component (rendering/rendered hooks, nested children tracked) and checks for a single root. A
+     * WithPagination component's page and page URL are what paginate() reads while it renders, as in its mount() and in
+     * its update's hooks and actions.
+     */
     private render;
+    /** The absolute URL of the page a memo path belongs to, on the current request's origin ('/' + path without one). */
+    private pageUrl;
     /** Dispatches, redirects: the effects every response carries. */
     private effects;
     /** dehydrate() hook, then the state as snapshot data, the error bag, and the checksum over both. */
@@ -203,8 +225,9 @@ declare class LiveComponentManager implements LiveManager {
 /** The URI the client runtime posts updates to. */
 declare const UPDATE_URI = "/oriel/live/update";
 /**
- * Binds the LiveManager, merges the `live` config, registers POST /oriel/live/update (named `live.update`, in the `web`
- * group: sessions and CSRF apply), the make:live command, and the components under app/Live.
+ * Binds the LiveManager and the PaginationState that WithPagination components answer, merges the `live` config,
+ * registers POST /oriel/live/update (named `live.update`, in the `web` group: sessions and CSRF apply), the make:live
+ * command, and the components under app/Live.
  */
 declare class LiveServiceProvider extends ServiceProvider {
     register(): void;
@@ -255,4 +278,65 @@ declare class InvalidLiveRequestError extends LiveError {
     readonly status: number;
 }
 
-export { Component, type ComponentResult, Computed, CorruptComponentPayloadError, ErrorBag, InvalidLiveRequestError, Live, LiveComponentManager, LiveComponentNotFoundError, LiveError, type LiveProps, LiveServiceProvider, Locked, MethodNotCallableError, On, PendingEvent, PropertyNotUpdatableError, Testable, UPDATE_URI, componentName, live };
+/** The route middleware an update re-applies by default (config live.persistent_middleware), by alias. */
+declare const PERSISTENT_MIDDLEWARE: string[];
+/** A route middleware after alias and group expansion: 'auth:web' → { cls: Authenticate, parameters: ['web'] }. */
+interface PersistentMiddleware {
+    readonly cls: MiddlewareClass;
+    readonly parameters: readonly string[];
+}
+/**
+ * Livewire's persistent middleware: the middleware among `persistent` (aliases) that the page route (the component's
+ * memo path and method) ran, in the order an update runs them. A path no route matches has none.
+ */
+declare function persistentMiddleware(router: Router, persistent: readonly string[], method: string, path: string): PersistentMiddleware[];
+
+type ComponentConstructor = abstract new (...args: any[]) => Component;
+/** What WithPagination() adds to a component: its page and the actions that move it. */
+interface Paginated {
+    /** The current page. The browser may set it; Live reads it as a page number. */
+    page: number;
+    nextPage(): Promise<void>;
+    previousPage(): Promise<void>;
+    gotoPage(page: number | string): Promise<void>;
+    resetPage(): Promise<void>;
+    setPage(page: number | string): Promise<void>;
+}
+/**
+ * Livewire's WithPagination: `class Posts extends WithPagination(Component)`. The public `page` (1 to start; there
+ * is no address-bar sync) is what `paginate()` shows in the component (in `render()`, `mount()`, `hydrate()`, the
+ * update hooks and actions, or in a `@Computed` getter any of them reads), and its page links are built on the
+ * page's URL. The actions move it: `o:click="nextPage"`, `previousPage`, `gotoPage(3)`, `setPage(3)`,
+ * `resetPage` (call it from `updatedSearch()` so a new search starts on page 1). `updatingPage(page)` and
+ * `updatedPage(page)` run around every change. One paginator per component: other page names read the request.
+ */
+declare function WithPagination<TBase extends ComponentConstructor>(Base: TBase): TBase & (abstract new (...args: any[]) => Paginated);
+
+/**
+ * What <Pagination> reads from a paginator. Structural, since Live can't import Database: paginate()'s
+ * LengthAwarePaginator (with lastPage(), so page buttons) and simplePaginate()'s Paginator (Previous and Next only).
+ */
+interface PaginationSource {
+    currentPage(): number;
+    lastPage?(): number;
+    hasMorePages(): boolean;
+    onFirstPage(): boolean;
+    /** Page buttons on each side of the current one (the paginator's onEachSide(), 3 by default). */
+    readonly onEachSideCount?: number;
+    /** Not cursorPaginate(): its pages are cursors, which a component's page number can't follow. */
+    readonly nextCursor?: never;
+}
+interface PaginationProps {
+    paginator: PaginationSource;
+    /** Classes for the <nav>, such as its layout ("flex gap-2"); in your file, so Tailwind generates them. */
+    class?: string;
+}
+/**
+ * Livewire's pagination links for a WithPagination component: `<Pagination paginator={posts} />` in render(). A
+ * <nav aria-label="Pagination"> with « Previous, the page buttons and Next » as Live actions (previousPage,
+ * gotoPage(n), nextPage), the current page marked aria-current="page", the ends disabled, the kits' theme classes
+ * (btn, btn-secondary). Nothing when everything fits on one page. The address bar is left alone.
+ */
+declare function Pagination({ paginator, class: className }: PaginationProps): Htmlable;
+
+export { Component, type ComponentResult, Computed, CorruptComponentPayloadError, ErrorBag, InvalidLiveRequestError, Live, LiveComponentManager, LiveComponentNotFoundError, LiveError, type LiveProps, LiveServiceProvider, Locked, MethodNotCallableError, On, PERSISTENT_MIDDLEWARE, type Paginated, Pagination, type PaginationProps, type PaginationSource, PendingEvent, type PersistentMiddleware, PropertyNotUpdatableError, TestRequestScope, Testable, UPDATE_URI, WithPagination, componentName, live, persistentMiddleware };