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

package/NOTICE

@@ -7,3 +7,10 @@ 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.
+
+@orieljs/notifications (and @orieljs/framework, which bundles it) includes the HTML and CSS of
+Laravel's default notification mail (laravel/framework, https://github.com/laravel/framework),
+Copyright (c) Taylor Otwell, MIT License.

package/README.md

@@ -6,8 +6,7 @@ Server-side Live components for Oriel: Livewire-style components written in TSX,
 npm install @orieljs/framework
 ```
 
-```tsx
-// app/Live/Counter.tsx
+```tsx title="app/Live/Counter.tsx"
 import { Component } from '@orieljs/framework'
 
 export default class Counter extends Component {
@@ -23,27 +22,90 @@ export default class Counter extends Component {
 }
 ```
 
-```ts
-// routes/web.ts
+```ts title="routes/web.ts"
+// @filename: app/Live/Counter.tsx
+import { Component } from '@orieljs/framework'
+export default class Counter extends Component { render() { return <p /> } }
+// ---cut---
 import { Route } from '@orieljs/framework'
 import Counter from '../app/Live/Counter'
 
 Route.get('/counter', Counter)
 ```
 
-Embed a component in any view with `<Live component={Counter} />`. In the browser, components are driven by `@orieljs/live-client`.
+Embed a component in any view with `<Live component={Counter} />`. In the browser, components are driven by `@orieljs/live-client`. Public fields are a component's state and its public methods are actions. `mount()` and `render()` may be async (`const user = await request().user<User>()`), and `await this.validate(rules)` returns the validated data, typed from the rules.
 
-## Pagination
+## Typed actions
+
+`this.$action(method, ...arguments)` writes an action for an `o:` directive, typed against the method:
+
+```tsx title="app/Live/Drafts.tsx"
+import { Component } from '@orieljs/framework'
+import { Post } from '../Models/Post'
+
+export default class Drafts extends Component {
+  async publish(id: number) {
+    const post = await Post.findOrFail(id)
+    post.published_at = new Date()
+    await post.save()
+  }
+
+  async render() {
+    const drafts = await Post.whereNull('published_at').get()
+    return (
+      <ul>
+        {drafts.map((post) => (
+          <li>
+            {post.title}
+            <button type="button" o:click={this.$action(this.publish, post.id)}>Publish</button>
+          </li>
+        ))}
+      </ul>
+    )
+  }
+}
+```
+
+For post 5 this renders `o:click="publish(5)"`, and since `publish(id: number)` takes a number,
+`this.$action(this.publish, String(post.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
+declare const tag: { id: number }
+// ---cut---
+<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. With `-once`, a dismissed
+dialog doesn't use the action up. `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 title="app/Live/Posts.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 updatedSearch() {
+    await this.resetPage()
   }
 
   async render() {
@@ -61,8 +123,81 @@ export default class Posts extends WithPagination(Component) {
 
 `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.
+`nextPage`, `previousPage`, `gotoPage(n)`, `setPage(n)` and `resetPage` move it (they are async, so await them in your
+own methods); `<Pagination>` renders them as buttons with the kits' `btn` classes. The page starts at 1 and isn't kept
+in the address bar.
+
+## File uploads
+
+```tsx title="app/Live/ProfilePhoto.tsx"
+import { Component, TemporaryUploadedFile, WithFileUploads } from '@orieljs/framework'
+
+export default class ProfilePhoto extends WithFileUploads(Component) {
+  photo: TemporaryUploadedFile | null = null
+
+  async save() {
+    const { photo } = await this.validate({ photo: 'required|image|max:1024' })
+    await photo.store('photos')
+    this.reset('photo')
+  }
+
+  render() {
+    return (
+      <form o:submit="save">
+        <input type="file" o:model="photo" />
+        {this.photo?.isPreviewable() ? <img src={this.photo.temporaryUrl()} alt="Preview" /> : null}
+        <button type="submit">Save</button>
+      </form>
+    )
+  }
+}
+```
+
+In a `WithFileUploads` component, `o:model` on a file input uploads the picked file at once, to a temporary
+directory, and sets the property to a `TemporaryUploadedFile` (an array of them with `multiple`). Validate it with the
+file rules, preview it with `temporaryUrl()` (a signed link, for images, audio and video), and `store()` it. In tests,
+`Live.test()`'s `set('photo', file)` uploads a file the same way. Every upload must also pass
+`live.temporary_file_upload.rules`, which allow 12 MB (`max:12288`), but a request body larger than
+`http.max_body_size` (8 MB, for every request) gets a 413: raise it in `config/http.ts` to accept files up to the
+rule's size.
+
+## Lazy components
+
+```tsx title="app/Live/PostCount.tsx"
+import { Component } from '@orieljs/framework'
+import { Post } from '../Models/Post'
+
+export default class PostCount extends Component {
+  static override lazy = true
+  count = 0
+
+  async mount() {
+    this.count = await Post.count()
+  }
+
+  placeholder() {
+    return <p>Counting posts…</p>
+  }
+
+  render() {
+    return <p>{this.count} posts</p>
+  }
+}
+```
+
+With `static override lazy = true`, each `<Live component={PostCount} />` (and the full page) renders the
+placeholder first and mounts the component once it scrolls into view. `lazy` on one embed makes that embed lazy,
+`lazy="on-load"` mounts it as soon as the page loads, and `lazy={false}` turns `static lazy` off. Without
+`placeholder()`, the placeholder is the `live.lazy_placeholder` view, else an empty `<div>`; it needs the same root
+element as `render()`.
+
+## Navigating
+
+`<a href="/posts" o:navigate>` shows the next page without a full reload: Live fetches it (from `mousedown`, or on
+hover with `o:navigate-hover`), merges its `<head>`, swaps the `<body>` and starts the new page's components.
+`this.redirect(url, { navigate: true })` does the same from an action. The new page's scripts run as on a full load,
+except a `<head>` script the page already has, and a `<body>` script marked `data-navigate-once` that an earlier page
+already ran.
 
 ## Middleware on updates
 
@@ -70,22 +205,61 @@ Each update re-runs the `auth`, `verified`, `guest` and `can` middleware of the
 (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`.
+updates. The list is `live.persistent_middleware`, which a `config/live.ts` of your own can set.
 
 ## 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 title="app/Live/Settings.tsx"
+import { Component } from '@orieljs/framework'
+
+export default class Settings extends Component {
+  name = ''
+  #saved = false
+
+  save() {
+    this.#saved = true
+  }
+
+  render() {
+    return (
+      <form o:submit="save">
+        <input o:model="name" aria-label="Name" />
+        <button type="submit">Save</button>
+        <p role="status" o:announce>
+          {this.#saved ? 'Saved' : ''}
+        </p>
+      </form>
+    )
+  }
+}
+```
+
+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`).
+- A DOM event whose name contains `-` can't be an `o:<event>` action, because `-` (and `.`) separate the modifiers (for example `o:model-live`).
+- `temporaryUrl()` previews don't answer range requests, which Safari needs to play a `<video>`.
+
+Documentation: https://orieljs.vercel.app/docs/live
 
 Status: early alpha. APIs will change.
 
 ## License
 
-Oriel is open-source software licensed under the Apache License 2.0 (Apache-2.0; see `LICENSE` and `NOTICE`). The Oriel name and logo are trademarks; see [`TRADEMARKS.md`](https://github.com/orieljs/framework/blob/main/TRADEMARKS.md).
+Oriel is open-source software licensed under the Apache License 2.0 (Apache-2.0; see `LICENSE` and `NOTICE`). The Oriel name and logo are trademarks; see `TRADEMARKS.md`.
 
 Website: https://orieljs.vercel.app

package/TRADEMARKS.md

@@ -0,0 +1,33 @@
+# Oriel trademark policy
+
+The Oriel code is open source under the Apache License 2.0. The **Oriel name and logo** are not: the license covers
+the code only (section 6 of the license says so), and the name and logo stay with the project. This page explains
+what you can and can't do with them. The goal is simple: people should always be able to tell what is the real Oriel
+and what isn't.
+
+## You can, without asking
+
+- Use, change, ship and sell the code, as the license allows.
+- Say that your app or package is "built with Oriel", "for Oriel" or "compatible with Oriel".
+- Name a package `oriel-<something>` or `<something>-for-oriel` when it works with Oriel, as long as it is clear that
+  it is not official (for example, don't publish it under the `@orieljs` npm scope).
+- Use the name and logo to write about Oriel, teach it, or link to it, in articles, talks, videos and courses.
+- Use the unmodified logo to point to the project, as it is (no recolouring, cropping or
+  distortion).
+
+## You can't, without written permission
+
+- Call a fork, a modified copy or a competing product "Oriel", or anything likely to be confused with it.
+- Use the name or logo as the name, logo or domain of your own product, company or service.
+- Suggest that the Oriel project made, endorses or supports your work when it doesn't.
+- Sell merchandise with the name or logo.
+
+## Forks
+
+Forks are welcome. Please give yours a different name and logo, keep the `LICENSE` and `NOTICE` files, and say that
+it is based on Oriel.
+
+## Questions
+
+Open an issue at https://github.com/orieljs/framework or email meeeet.dev@gmail.com. If you're unsure whether a use
+is fine, ask; the answer is usually yes.

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 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 { Class, RouteName, RouteArguments, Rules, InferValidatedType, MessageBag, LiveEffects, Htmlable, LiveSnapshot, LiveManager, Application, HttpRequest, LiveUpdateRequest, LiveUpdateResponse, OrielError, ErrorKind, UploadedFile, MiddlewareClass, Router } from '@orieljs/contracts';
 import { ServiceProvider } from '@orieljs/support';
 
 /** Marks Live component classes (Symbol.for, so two copies of the package agree). */
@@ -13,8 +13,11 @@ interface QueuedDispatch {
 }
 /** The validation errors of a component (Laravel's MessageBag), for render(): `this.errors.first('title')`. */
 declare class ErrorBag implements MessageBag {
+    #private;
     private readonly messages;
     constructor(messages: Record<string, string[]>);
+    /** Adds to the component's errors, as addError() does. */
+    add(key: string, message: string): void;
     has(key: string): boolean;
     first(key?: string): string | undefined;
     get(key: string): string[];
@@ -45,6 +48,13 @@ declare abstract class Component {
     static layout?: string;
     /** The page title passed to the layout as `title`. */
     static title?: string;
+    /**
+     * Livewire's #[Lazy]: every embed (and the full page) renders the placeholder first and mounts once the browser shows
+     * it. `<Live component={…} lazy={false} />` mounts one at once. The placeholder is the component's
+     * `placeholder(params)` method (TSX), else the `live.lazy_placeholder` view, else an empty `<div>`: give it the root
+     * element the component renders.
+     */
+    static lazy?: boolean;
     /** Static fallbacks for runtimes without decorators: { event: 'method' }, locked names, computed getter names. */
     static listeners?: Record<string, string>;
     static locked?: string[];
@@ -58,14 +68,19 @@ declare abstract class Component {
     redirect(url: string, options?: {
         navigate?: boolean;
     }): void;
-    redirectRoute(name: string, parameters?: unknown, options?: {
+    /**
+     * redirect() to a named route: `this.redirectRoute('posts.show', post, { navigate: true })`. Once `oriel
+     * route:types` has run, the name and the route's parameters are checked, as route()'s are.
+     */
+    redirectRoute<N extends RouteName>(name: N, ...args: RouteArguments<N, [options?: {
         navigate?: boolean;
-    }): void;
+    }]>): void;
     /**
-     * Validates the public state. On success clears the error bag and returns the validated data; on failure fills the
-     * error bag and throws (the rest of the action is skipped and the component re-renders with `errors`).
+     * Validates the public state. On success clears the error bag and returns the validated data, typed from the rules
+     * (`await this.validate({ title: 'required|string' })` is `{ title: string }`); on failure fills the error bag and
+     * throws (the rest of the action is skipped and the component re-renders with `errors`).
      */
-    validate<T = Record<string, unknown>>(rules: Rules, messages?: Record<string, string>, attributes?: Record<string, string>): Promise<T>;
+    validate<const R extends Rules>(rules: R, messages?: Record<string, string>, attributes?: Record<string, string>): Promise<InferValidatedType<R>>;
     addError(key: string, message: string): void;
     /** Clears every error, or only those of `keys`. */
     resetErrorBag(...keys: string[]): void;
@@ -74,6 +89,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>;
 }
@@ -102,7 +124,10 @@ declare class Testable<C extends Component = Component> {
     private readonly manager;
     private readonly scope;
     private constructor();
-    /** Mounts `component` with `params`, as `<Live component={…} {...params} />` would. */
+    /**
+     * Mounts `component` with `params`, as `<Live component={…} {...params} />` would. A lazy component mounts at once
+     * (Livewire's withoutLazyLoading()); `{ lazy: true }` renders its placeholder, and `call('__lazyLoad', …)` loads it.
+     */
     static create<C extends Component>(component: Class<C> | string, params?: Record<string, unknown>): Promise<Testable<C>>;
     /** The component instance after the last request. */
     instance(): C;
@@ -112,7 +137,14 @@ declare class Testable<C extends Component = Component> {
     html(): string;
     /** The effects of the last request. */
     effects(): LiveEffects;
+    /**
+     * Sets public properties through an update. A file (a FakeFile) or an array of files is uploaded as `o:model` on a
+     * file input does it: the upload rules, the temporary disk, then a TemporaryUploadedFile (or an array) in the
+     * property, or the upload's errors on it (Livewire's).
+     */
     set(path: string | Record<string, unknown>, value?: unknown): Promise<this>;
+    /** Uploads `files` into the property `name` (an array when `multiple`), as the browser's upload calls do. */
+    upload(name: string, files: readonly Blob[], multiple?: boolean): Promise<this>;
     call(method: string, ...params: unknown[]): Promise<this>;
     toggle(path: string): Promise<this>;
     /** Dispatches an event to this component, as the browser does for its listeners. */
@@ -125,6 +157,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). */
@@ -142,6 +177,11 @@ interface LiveProps {
     component: Class<Component> | string;
     /** Identifies a child inside its parent across re-renders (Livewire's :key / wire:key). */
     'o:key'?: string | number;
+    /**
+     * Renders the placeholder and mounts the component once it scrolls into view (`'on-load'`: once the page starts);
+     * `false` mounts a `static lazy` component at once.
+     */
+    lazy?: boolean | 'on-load';
     [param: string]: unknown;
 }
 /** Blade's @livewire('counter', ['count' => 3], key('c1')): the component's first render, as trusted HTML. */
@@ -184,10 +224,25 @@ declare class LiveComponentManager implements LiveManager {
     isLiveRequest(request: HttpRequest): boolean;
     /** The first render: HTML with o:id, o:snapshot and o:effects on the root element. */
     mount(component: string | Class<unknown>, params?: Record<string, unknown>, key?: string): Promise<string>;
-    mountComponent(component: string | Class<unknown>, params?: Record<string, unknown>, existing?: Component): Promise<ComponentResult>;
+    /**
+     * Mounts a component: boot(), the params into its properties, mount(params), then its first render. A lazy one
+     * (`lazy` in the params, or `static lazy`) renders its placeholder instead and mounts when the browser loads it.
+     */
+    mountComponent(component: string | Class<unknown>, embedParams?: Record<string, unknown>, existing?: Component): Promise<ComponentResult>;
+    /**
+     * A lazy component's first render (Livewire's): its placeholder, with the state it has before mount() and the mount
+     * params signed for the `__lazyLoad` call the browser makes when it shows it (`o:lazy`, or `o:lazy-on-load`).
+     */
+    private mountPlaceholder;
     /** 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 mount params and placeholder tag of a `__lazyLoad` request, or undefined for any other update. The load comes
+     * alone (no updates, no other call: the browser sends it in a request of its own) and its payload must be the one
+     * signed for this component: anything else is refused as corrupt (a 403) before the component boots.
+     */
+    private lazyLoad;
     /**
      * 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
@@ -206,7 +261,7 @@ declare class LiveComponentManager implements LiveManager {
     /** Makes every computed getter (static `computed` too) cache its value for the rest of the request. */
     private prepareComputed;
     private applyUpdate;
-    /** Runs one call from the browser: a magic action, an event, or a public method. Returns its return value. */
+    /** Runs one call from the browser: a magic action, an event, an upload call, 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. A
@@ -226,8 +281,9 @@ declare class LiveComponentManager implements LiveManager {
 declare const UPDATE_URI = "/oriel/live/update";
 /**
  * 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.
+ * registers POST /oriel/live/update (named `live.update`, in the `web` group: sessions and CSRF apply), the upload and
+ * preview routes of WithFileUploads (`live.upload-file`, `live.preview-file`), the make:live command, and the
+ * components under app/Live.
  */
 declare class LiveServiceProvider extends ServiceProvider {
     register(): void;
@@ -277,6 +333,108 @@ declare class InvalidLiveRequestError extends LiveError {
     readonly kind: ErrorKind;
     readonly status: number;
 }
+/** An upload or preview URL whose signature is missing, wrong or expired (Livewire's 401). Nothing is read or stored. */
+declare class InvalidUploadSignatureError extends LiveError {
+    readonly name: string;
+    readonly kind: ErrorKind;
+    readonly status: number;
+    constructor();
+}
+/** A preview of a temporary upload that is no longer on the disk (cleaned up, or stored and deleted). */
+declare class TemporaryFileNotFoundError extends LiveError {
+    readonly name: string;
+    readonly kind: ErrorKind;
+    readonly status: number;
+    constructor(filename: string);
+}
+/** temporaryUrl() on an upload whose type has no preview (live.temporary_file_upload.preview_mimes). */
+declare class FileNotPreviewableError extends LiveError {
+    readonly name: string;
+    constructor(extension: string);
+}
+/** The errors an upload came back with (`_uploadErrored`): the component re-renders with them on the property. */
+declare class UploadValidationError extends LiveError {
+    readonly errors: Record<string, string[]>;
+    readonly name: string;
+    readonly kind: ErrorKind;
+    readonly status: number;
+    readonly errorBag: string;
+    constructor(errors: Record<string, string[]>);
+}
+
+/**
+ * Livewire's `temporary_file_upload` settings, read from config `live.temporary_file_upload.*` (each one falls back on
+ * its own): the disk (the default filesystem disk), the directory on it, the rules every upload must pass, the upload
+ * route's middleware, the types a preview is served for, how long an upload URL lasts (minutes), and whether a finished
+ * upload removes the temporary files older than a day.
+ */
+declare const TEMPORARY_UPLOAD_DEFAULTS: {
+    disk: string | null;
+    directory: string;
+    rules: string | string[];
+    middleware: string | string[];
+    preview_mimes: string[];
+    max_upload_time: number;
+    cleanup: boolean;
+};
+/** What a temporary upload is: its stored name on the temporary disk and what the browser sent (signed with it). */
+interface TemporaryFileData {
+    /** A random 40-character name with the extension its bytes showed: `live-tmp/<filename>` on the temporary disk. */
+    filename: string;
+    /** The name the browser gave the file. */
+    name: string;
+    size: number;
+    /** The MIME type the browser claimed. */
+    type: string;
+    /** The extension of the upload's own type (its bytes, else a plain claimed extension), or ''. */
+    extension: string;
+}
+/**
+ * Livewire's TemporaryUploadedFile: a file the browser uploaded to the temporary directory before an action stores
+ * it. A WithFileUploads component's property holds one (or an array of them) once `o:model` on a file input has
+ * uploaded it: validate it like any upload (`'photo' => 'image|max:1024'`), preview it with `temporaryUrl()`, then
+ * `store()` it. It travels in the component's snapshot as its data, signed with the rest.
+ */
+declare class TemporaryUploadedFile implements UploadedFile {
+    #private;
+    readonly filename: string;
+    readonly clientName: string;
+    readonly mimeType: string;
+    readonly size: number;
+    constructor(data: TemporaryFileData);
+    /** What the snapshot carries. */
+    toData(): TemporaryFileData;
+    /** The file's path on the temporary disk. */
+    get path(): string;
+    /** The extension of the upload's own type, as FormUploadedFile's extension(): what putFile() names a stored copy by. */
+    extension(): string;
+    /** The extension of the name the browser gave the file, lower-cased ('' without one). */
+    clientExtension(): string;
+    /** A random 40-character name with extension(), as FormUploadedFile's. */
+    hashName(): string;
+    arrayBuffer(): Promise<ArrayBuffer>;
+    text(): Promise<string>;
+    /** The file's bytes from the temporary disk, opened on the first read. */
+    stream(): ReadableStream<Uint8Array>;
+    /** Stores a copy under a random name in `directory`, on `disk` (by default the temporary disk, as Livewire's). */
+    store(directory: string, disk?: string): Promise<string>;
+    storeAs(directory: string, name: string, disk?: string): Promise<string>;
+    exists(): Promise<boolean>;
+    /** Removes the temporary file (a stored copy stays). */
+    delete(): Promise<boolean>;
+    /** Whether temporaryUrl() serves this file: its type is in `live.temporary_file_upload.preview_mimes`. */
+    isPreviewable(): boolean;
+    /**
+     * A signed link to the file for `<img src>` or `<video src>` before it is stored. It lasts until the end of the hour
+     * at least 30 minutes away (Livewire's), so a re-render keeps the same link and the browser doesn't reload it.
+     */
+    temporaryUrl(): string;
+}
+
+/** Where the browser POSTs a WithFileUploads component's files (Livewire's /livewire/upload-file), named live.upload-file. */
+declare const UPLOAD_URI = "/oriel/live/upload-file";
+/** Where temporaryUrl() links lead (Livewire's /livewire/preview-file/{filename}), named live.preview-file. */
+declare const PREVIEW_URI = "/oriel/live/preview-file";
 
 /** The route middleware an update re-applies by default (config live.persistent_middleware), by alias. */
 declare const PERSISTENT_MIDDLEWARE: string[];
@@ -312,6 +470,14 @@ interface Paginated {
  */
 declare function WithPagination<TBase extends ComponentConstructor>(Base: TBase): TBase & (abstract new (...args: any[]) => Paginated);
 
+/**
+ * Livewire's WithFileUploads: `class Profile extends WithFileUploads(Component)`. A file input with `o:model="photo"`
+ * uploads the file to the temporary directory as soon as it is picked, then sets `photo` to a TemporaryUploadedFile
+ * (`<input type="file" multiple>` sets an array), through `updatingPhoto()`/`updatedPhoto()` like any update. Validate
+ * it with the file rules, preview it with `temporaryUrl()`, store it with `store()`.
+ */
+declare function WithFileUploads<TBase extends ComponentConstructor>(Base: TBase): TBase;
+
 /**
  * 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).
@@ -339,4 +505,4 @@ interface PaginationProps {
  */
 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 };
+export { Component, type ComponentResult, Computed, CorruptComponentPayloadError, ErrorBag, FileNotPreviewableError, InvalidLiveRequestError, InvalidUploadSignatureError, Live, LiveComponentManager, LiveComponentNotFoundError, LiveError, type LiveProps, LiveServiceProvider, Locked, MethodNotCallableError, On, PERSISTENT_MIDDLEWARE, PREVIEW_URI, type Paginated, Pagination, type PaginationProps, type PaginationSource, PendingEvent, type PersistentMiddleware, PropertyNotUpdatableError, TEMPORARY_UPLOAD_DEFAULTS, type TemporaryFileData, TemporaryFileNotFoundError, TemporaryUploadedFile, TestRequestScope, Testable, UPDATE_URI, UPLOAD_URI, UploadValidationError, WithFileUploads, WithPagination, componentName, live, persistentMiddleware };