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

package/NOTICE

@@ -7,3 +7,6 @@ This product includes software developed by the Oriel project
 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).
+
+@orieljs/support (and @orieljs/framework, which bundles it) includes transliteration data from
+voku/portable-ascii (https://github.com/voku/portable-ascii), Copyright (C) 2019 Lars Moelleken, MIT License.

package/README.md

@@ -33,7 +33,106 @@ 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:
+## Typed actions
+
+`this.$action(method, ...arguments)` writes an action for an `o:` directive, typed against the method:
+
+```tsx
+<button type="button" o:click={this.$action(this.revokeAdmin, user.id)}>
+  Revoke admin
+</button>
+```
+
+This renders `o:click="revokeAdmin(5)"`, and when `revokeAdmin(id: number)` takes a number,
+`this.$action(this.revokeAdmin, String(user.id))` is a type error. The arguments are written as JSON, so pass ids and
+plain values (strings, numbers, booleans, `null`, arrays and plain objects): a model arrives as its attributes and a
+date as its ISO string, so pass `post.id`, not `post`. The action contains double quotes, so use it as a TSX attribute
+value, which escapes them, not inside an HTML string you write by hand. Rendering throws when the method isn't one of
+the component's actions (a hook, or a `#private` or `@Locked` method). The types check what your pages send; a crafted
+request can still send anything, so an action checks what it is given, as a controller does.
+
+## Confirming an action
+
+`o:confirm` asks before an action runs, as Livewire's `wire:confirm`:
+
+```tsx
+<button type="button" class="btn btn-danger" o:click={`delete(${tag.id})`} o:confirm="Delete this tag?">
+  Delete
+</button>
+```
+
+The browser's confirm dialog shows the message (an empty `o:confirm` asks "Are you sure?", and `\n` is a line break),
+and the action runs only when it is accepted. `o:confirm-prompt="Type DELETE to confirm|DELETE"` (`o:confirm.prompt`
+in plain HTML) asks with a prompt instead, and runs the action only when the answer is exactly the text after the `|`.
+It works on any element with an `o:` action: `o:click`, `o:submit` on a form, `o:keydown-enter`, and the others. A
+dismissed dialog stops the event, so the actions of the elements around it don't run either. `o:confirm` guards the
+actions of the element it sits on: on a form, put it on the `<form>` with the `o:submit`. A button inside a form with
+its own `o:click` needs `type="button"` or `-prevent` (`o:click-prevent`), or the browser still submits the form when
+the dialog is dismissed.
+
+## 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.
+
+## Status messages announced again
+
+Screen readers announce a status region (`role="status"`) when its text changes. When an action brings the same
+message again ("Saved" after a second save), the page doesn't change and nothing is announced. Add `o:announce` to the
+region and Live takes the message out and puts it back a moment later, so it is announced again:
+
+```tsx
+<p role="status" o:announce>
+  {this.#saved ? 'Saved' : ''}
+</p>
+```
+
+Only actions do this, and an `o:poll` that calls a method counts as one: an update that only syncs `o:model` values,
+refreshes or delivers an event leaves the region alone. Keep a status for one response (a `#private` field, or a
+flashed `status`), so that any other update clears it; a status kept in a public property is announced again by every
+action until it changes, which in a polled component is every tick. Keep an `o:announce` region to text: its children
+are taken out for 100 ms, so a button or input inside it would lose focus.
+
+## 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

@@ -74,6 +74,13 @@ declare abstract class Component {
     reset(...properties: string[]): void;
     /** Keeps the current HTML: the response carries the new state but no `html` effect. */
     skipRender(): void;
+    /**
+     * An action for an `o:` directive, typed against its method: `o:click={this.$action(this.delete, tag.id)}` writes
+     * `delete(5)`, and a string where `delete` takes a number is a type error. The arguments are written as JSON, the
+     * trailing `undefined` ones left out so the method's defaults apply. The method must be one of this component's
+     * actions (a public method of its class, not a hook and not @Locked); anything else throws while rendering.
+     */
+    $action<P extends unknown[]>(method: (...params: P) => unknown, ...params: NoInfer<P>): string;
     /** A full-page component as a route action: Route.get('/counter', Counter). Route parameters go to mount(). */
     __invoke(): Promise<unknown>;
 }
@@ -125,6 +132,9 @@ declare class Testable<C extends Component = Component> {
     assertDontSee(...values: string[]): this;
     /** Each value appears in the rendered HTML as written (not escaped). */
     assertSeeHtml(...values: string[]): this;
+    /** Each value, HTML-escaped, appears in the rendered text: the HTML with its tags stripped (Livewire's assertSeeText). */
+    assertSeeText(...values: string[]): this;
+    assertDontSeeText(...values: string[]): this;
     assertDispatched(name: string, params?: Record<string, unknown>): this;
     assertNotDispatched(name: string): this;
     /** The error bag has errors for every key given (or any error at all with no keys). */
@@ -189,9 +199,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 +218,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 +235,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 +296,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 };