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

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

@@ -189,9 +189,11 @@ declare class LiveComponentManager implements LiveManager {
     update(request: LiveUpdateRequest): Promise<LiveUpdateResponse>;
     updateComponent(snapshotJson: string, updates: Record<string, unknown>, calls: Call[]): Promise<ComponentResult>;
     /**
-     * The route action of POST /oriel/live/update. Each component's update runs behind the auth middleware of the route
-     * that rendered its page (Livewire's persistent middleware): a signed-out tab gets a 401, never the action. When a
-     * middleware answers instead (a redirect), that is the response.
+     * 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. */
@@ -206,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. */
@@ -217,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;
@@ -277,10 +286,57 @@ interface PersistentMiddleware {
     readonly parameters: readonly string[];
 }
 /**
- * Livewire's persistent middleware: the route that rendered the page (the component's memo path and method) is
- * matched again, and the middleware among `persistent` (aliases) that it ran are returned, to run before an update.
- * A path no route matches has none.
+ * 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[];
 
-export { Component, type ComponentResult, Computed, CorruptComponentPayloadError, ErrorBag, InvalidLiveRequestError, Live, LiveComponentManager, LiveComponentNotFoundError, LiveError, type LiveProps, LiveServiceProvider, Locked, MethodNotCallableError, On, PERSISTENT_MIDDLEWARE, PendingEvent, type PersistentMiddleware, PropertyNotUpdatableError, TestRequestScope, Testable, UPDATE_URI, componentName, live, 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 };