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

package/NOTICE

@@ -10,3 +10,7 @@ The Oriel name and logo are not covered by that license; see 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,28 +22,52 @@ 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.
 
 ## 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>
+```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>
+    )
+  }
+}
 ```
 
-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
+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
@@ -56,6 +79,8 @@ request can still send anything, so an action checks what it is given, as a cont
 `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>
@@ -65,22 +90,22 @@ The browser's confirm dialog shows the message (an empty `o:confirm` asks "Are y
 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.
+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
+```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() {
@@ -98,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
 
@@ -107,7 +205,7 @@ 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
 
@@ -120,10 +218,29 @@ Screen readers announce a status region (`role="status"`) when its text changes.
 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>
+```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,
@@ -134,13 +251,15 @@ 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;
@@ -109,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;
@@ -119,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. */
@@ -152,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. */
@@ -194,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
@@ -216,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
@@ -236,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;
@@ -287,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[];
@@ -322,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).
@@ -349,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 };