@tristan2828/ui-foundation 4.26.0 → 4.28.0

package/conventions/docs/add-an-entity.md

@@ -153,7 +153,8 @@ is a filled-in example while the Widgets demo is still here).
    controls named by position ("Item 2 text"), a per-item `FieldError`
    (a server 422 at `["body", "checklist", 2, "text"]` arrives as
    `fieldErrors["checklist.2.text"]` and binds to that row), and a summary
-   in the table, never the items — and a `computed` field copies
+   in the table, never the items (an item with a `reference` field
+   copies Pairings, below) — and a `computed` field copies
    Progress (`checklistState`): `readOnly` in `openapi.yaml` and absent
    from `<Entity>Create`/`<Entity>Update`, one SQL expression in the
    router that the filter and sort use (correlated `EXISTS`, or a scalar
@@ -186,6 +187,95 @@ is a filled-in example while the Widgets demo is still here).
    Select is (Storybook `app/DateField` EditInPlace). The backend column
    is a SQL `date` (`datetime.date` in the model).
 
+   **An image on a record** (a photo of it) is the stored file's id on the
+   wire (`string`, nullable), and on the form the foundation's
+   `ImageField` in a `Controller` (`z.string().nullable()`): `value` and
+   `onChange` are the id, `thumbUrl` the record's saved photo,
+   `onBusyChange` holds the submit while a file uploads (Storybook
+   `app/ImageField`). Its `upload` is the app's own, one function in the
+   gateway that sends the file to the app's endpoint and resolves to
+   `{ id, thumbUrl, url }` (the `ImageUploadResult`), rejecting with the
+   `AppError`; the same function goes to a notes field's
+   `RichTextEditor`, so pictures in its text use the same storage:
+
+   ```ts
+   // src/api/gateway/files.ts
+   export async function uploadImage(file: File): Promise<ImageUploadResult> {
+     const body = new FormData()
+     body.append('file', file)
+     const response = await safeFetch('/files', { method: 'POST', body })
+     if (response.status !== 201) throw toAppError(response.status, response.body, response.headers)
+     const { id } = response.body as components['schemas']['File']
+     return { id, thumbUrl: `/api/files/${id}/content?size=thumb`, url: `/api/files/${id}/content` }
+   }
+   ```
+
+   The types it takes default to JPEG, PNG and WebP; never add SVG or
+   HTML, which run script when served from the app's own domain. The
+   endpoint, the storage and serving the files are the app's (the
+   template has none); `<Markdown>` shows an image only from a web
+   address or a path on the site, so `url` is one of those.
+
+   **A `reference` inside a sub-record item** (a list whose items each
+   point at another entity's record) copies Pairings, Widget's
+   `pairings`: Checklist's list, with a reference in each item.
+   - *Wire:* the item carries the referenced id only, named as a
+     top-level reference is (`{ categoryId, note }`, `seriesId` for a
+     Series), never a name or a nested record. Every name, on the form
+     and on the view, comes from the other entity's lookup by id
+     (`GET /<other>?ids=…`), as for a `multi reference`; add `ids` to
+     its list endpoint if it lacks one. An optional text field beside it
+     is a required `string` that is `""` when empty (`note`), so an item
+     never holds a null. `openapi.yaml` describes the item as its own
+     schema (`WidgetPairing`), with `maxItems` on the list.
+   - *Backend:* a child table like the checklist's (`widget_pairings`:
+     `position`, and a foreign key to the referenced table, commented),
+     replaced whole on every write. Before saving, the router checks every
+     item's id in one query (`_check_item_categories_exist`): one that
+     isn't there, or, for a per-user entity, isn't this user's, is a 422 at
+     the item's own path, `["body", "pairings", 2, "categoryId"]`, never a
+     foreign-key 500. Its tests: order kept with repeats, replace and
+     clear, the note trimmed, an unknown id refused at its item on create
+     and on update with nothing saved, `null` and too many refused.
+   - *The mocks* refuse an unknown id at the same path, and trim the note.
+   - *The form's row* is one component shared with editing in place
+     (`WidgetPairingItemFields` in `widget-fields.tsx`): the referenced
+     record's combobox (`WidgetCategoryCombobox`, the form's Category
+     combobox with its own search per row, a lookup by id for the picked
+     record's name, and the picked name not counted as a search, so
+     opening the list offers every record) and the other fields, each
+     named by position ("Pairing 2 category"). On the form it sits in a
+     `Controller` over `<list>.<i>.<field>Id`, the rest `register`ed, and
+     a server 422 at that path (`fieldErrors["pairings.2.categoryId"]`)
+     binds to that row's picker. A new row starts with no pick, which the
+     schema refuses on that row ("Pick a category or remove the
+     pairing"), so a blank item is never sent.
+   - *The view* shows each item as the referenced record's name, from the
+     view's one lookup by id (add every item's id to the ids it already
+     looks up), then its other fields. The name links to the record's
+     view when that entity has one (`<Link to={`/<other>/${id}`}>`);
+     WidgetCategory has none, so Pairings shows it as plain text.
+   - *Editing in place* is `editInPlace({ kind: 'list', ... })` like
+     Checklist's (`pairings` in `widgetEdits`): `renderItem` is the
+     form's row, `renderShown` the item as the view shows it, `newItem`
+     starts with no pick. In the row, Enter in the open list picks
+     without saving; Enter in the row's text box saves the item, as does
+     leaving the row (a click on an option is still inside it), and the
+     item being added opens again after an Enter, as Checklist's does.
+   - *Specs* (copy the `pairings` tests): on the form, saved picks load
+     by name, a pick found by searching saves, a row with no pick is
+     caught on that row, and a server 422 at the item's reference binds
+     to that row's picker; on the view, the names and the sparse record's
+     not-set label; in place (`the pairings edited in place`), an item
+     added from the keyboard (search, Enter picks, Enter saves) with the
+     PATCH sending ids, an item's reference changed by a click, move and
+     remove, no pick never sent, and a refused id staying open with the
+     reason; and the in-place a11y block for a row open and refused.
+   - *Not built:* a "New …" option in the item's picker that creates the
+     referenced record inline. Create it on its own screen (or the
+     table's `InlineCreate`) first. AI chats (MCP) print an item's
+     reference as its id, not its name.
+
    **A `yes/no` marked `toggle`** copies In Stock's cell
    (`in-stock-toggle.tsx`, cell pattern 15): a `Switch` in its own
    component that PATCHes the one field through `useSaveWidgetField`, the
@@ -389,7 +479,8 @@ is a filled-in example while the Widgets demo is still here).
      shared with the form (`WidgetChecklistItemFields`), the item as the
      view shows it (its quick action, if any) as `renderShown`, the list's
      schema, and `save: (change) => edit.mutateAsync((current) => ({
-     <field>: change(current.<field>) }))`. **With no `Edit in place`
+     <field>: change(current.<field>) }))` (an item with a reference:
+     copy `pairings` in `widgetEdits`, above). **With no `Edit in place`
      line, nothing is editable in place** and none of this is copied.
      Never a computed field.
 

package/conventions/docs/cell-patterns.md

@@ -947,7 +947,11 @@ const price = editInPlace({
   `toolbar={false}` leaves out the toolbars and the slash menu where a
   value is short and the shortcuts are enough; `toolbar="floating"` keeps
   the floating one and the slash menu without the bar above (an `inline`
-  field's look).
+  field's look). Images in the text (`![alt](url)`) show; give it the
+  app's `upload` (the same one `ImageField` takes) and an image pasted,
+  dropped or picked with the toolbar's Image button is uploaded and goes
+  in as `![](url)`, a placeholder showing meanwhile (never saved), a
+  refusal or failure in a toast. No `upload`, no file handling at all.
 - **The save is the single-field save** (`useRecordUpdate` with
   `optimistic: false, toastOnError: false`, the entity's
   `useEdit<Entity>Field`), `mutateAsync` of one field's PATCH.
@@ -989,6 +993,13 @@ Checklist is the reference (`checklist` in `widgetEdits`). It's built on
   about the list (too many items) under the row being added.
 - `content` shows above the items (the done-count) and `emptyLabel` in
   place of them when there are none.
+- **An item with a reference** (Widget's Pairings, `pairings` in
+  `widgetEdits`) reads as the referenced record's name, from the view's
+  lookup by id, and its row is the form's: a combobox per row, with its
+  own search. Enter in the open list picks without saving, a click on an
+  option is still inside the row, and Enter in the row's text box or
+  leaving the row saves the item, ids only on the wire. A new item starts
+  with no pick, which the list's schema refuses on that row.
 
 ```tsx
 const checklist = editInPlace<ChecklistItem>({

package/conventions/docs/entity-plan-template.md

@@ -96,9 +96,28 @@ per list; delete the section if there are none.
 | done | Done | yes/no | yes | default no |
 
 - Item fields use the same types as the main table (`text`, `url`,
-  `yes/no`… — not another sub-record or a reference). Items have no screen
-  of their own: they're added, edited, reordered and removed on the
-  record's form, and the order is kept.
+  `yes/no`…), including a `reference` (below), but not another
+  sub-record, a `multi reference` or a `multi choice`. Items have no
+  screen of their own: they're added, edited, reordered and removed on
+  the record's form, and the order is kept.
+- **A `reference` item field** points each item at a record of another
+  entity: name it, as for a top-level reference (`seriesId` → Series).
+  Each row picks it with the same searchable combobox; the item carries
+  the referenced id only, and every name comes from the other entity's
+  lookup by id (its list endpoint must accept `ids`). Say whether it's
+  required, and whether the same record may appear in more than one
+  item. On the view each item reads as the record's name, linked to its
+  view when it has one. An optional text item field beside it is `""`
+  when empty. Widget's `pairings` is the worked example
+  (`docs/entities/widget.md`):
+
+  | Field | Label | Type | Required | Options / rules |
+  |---|---|---|---|---|
+  | categoryId | Category | reference → WidgetCategory | yes | picked from a searchable list; repeats allowed |
+  | note | Note | text | no | up to 100 chars, trimmed; empty means none |
+
+  Not supported yet: creating the referenced record from the item's
+  picker (a "New …" option); create it on its own screen first.
 
 ## List screen
 

package/dist/components/app/image-field.d.ts

@@ -0,0 +1,37 @@
+import { type ImageUpload } from '../../lib/image-file.js';
+export type ImageFieldProps = {
+    /** The main button's id (Add or Replace), for the field's `<FieldLabel htmlFor>`. */
+    id?: string;
+    /** The stored image's id, as the record keeps it, or null for none. */
+    value: string | null;
+    /**
+     * The current image's thumbnail, for a value the field didn't upload
+     * itself (the record's saved photo). After an upload the field shows
+     * the upload's own `thumbUrl`.
+     */
+    thumbUrl?: string | null;
+    /** Called with the new image's id once it's stored, or null when removed. */
+    onChange: (id: string | null) => void;
+    /** Stores one file in the app's storage and resolves to its id and thumbnail. */
+    upload: ImageUpload;
+    /** The image types taken. Defaults to JPEG, PNG and WebP (`DEFAULT_IMAGE_TYPES`). */
+    accept?: readonly string[];
+    /** The largest file taken, in bytes: a bigger one is refused before it's sent. */
+    maxSize?: number;
+    /** What the image is, in the buttons' words: "Add photo", "Replace photo". Defaults to `'photo'`. */
+    noun?: string;
+    /** The thumbnail's alt text. Defaults to "Current photo" (with `noun`). */
+    alt?: string;
+    /** The value was refused (the form's schema, the server): `aria-invalid` on the main button. */
+    invalid?: boolean;
+    /** Saving: the image shows, nothing can be changed. */
+    readOnly?: boolean;
+    /** Told when an upload starts and ends, so a form can hold its submit meanwhile. */
+    onBusyChange?: (busy: boolean) => void;
+    className?: string;
+    /** The field's name, on its group of controls: this, or `aria-labelledby` (the label's id). */
+    'aria-label'?: string;
+    'aria-labelledby'?: string;
+    'aria-describedby'?: string;
+};
+export declare function ImageField({ id, value, thumbUrl, onChange, upload, accept, maxSize, noun, alt, invalid, readOnly, onBusyChange, className, 'aria-label': ariaLabel, 'aria-labelledby': ariaLabelledBy, 'aria-describedby': ariaDescribedBy, }: ImageFieldProps): import("react").JSX.Element;

package/dist/components/app/image-field.js

@@ -0,0 +1,103 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// One image on a record (a photo of it): a thumbnail with Replace and
+// Remove, or Add photo when there's none. A form control like DateField:
+// a react-hook-form `Controller` on the form, its value what the record
+// stores, the stored file's id (or null).
+//
+// The upload is the app's (`upload`, its own storage: the package knows no
+// endpoint). A file picked uploads at once; while it does, the buttons
+// wait and say so, and the value changes only once it's stored. A file
+// the field won't take (its type, its size) is refused before it's sent,
+// and why shows under the field, as does a failed upload's reason.
+//
+// Remove only empties the field; deleting the stored file, if ever, is the
+// app's.
+import { useEffect, useId, useRef, useState } from 'react';
+import { ImageIcon, ImagePlusIcon, RefreshCwIcon, XIcon } from 'lucide-react';
+import { cn } from 'cn';
+import { Button } from '../ui/button.js';
+import { Spinner } from '../ui/spinner.js';
+import { acceptAttribute, DEFAULT_IMAGE_TYPES, imageRefusal, uploadFailure } from '../../lib/image-file.js';
+export function ImageField({ id, value, thumbUrl, onChange, upload, accept = DEFAULT_IMAGE_TYPES, maxSize, noun = 'photo', alt, invalid = false, readOnly = false, onBusyChange, className, 'aria-label': ariaLabel, 'aria-labelledby': ariaLabelledBy, 'aria-describedby': ariaDescribedBy, }) {
+    const ids = useId();
+    const errorId = `${ids}-error`;
+    const input = useRef(null);
+    const main = useRef(null);
+    const [busy, setBusy] = useState(false);
+    // Why the last file picked isn't the field's image.
+    const [problem, setProblem] = useState(null);
+    // What a screen reader hears of an upload: started, done.
+    const [status, setStatus] = useState('');
+    // The image this field uploaded, so it shows before the record has it.
+    const [uploaded, setUploaded] = useState(null);
+    // A thumbnail that didn't load shows as the image glyph instead.
+    const [broken, setBroken] = useState(null);
+    const mounted = useRef(true);
+    useEffect(() => {
+        mounted.current = true;
+        return () => {
+            mounted.current = false;
+        };
+    }, []);
+    const latestBusy = useRef(onBusyChange);
+    useEffect(() => {
+        latestBusy.current = onBusyChange;
+    });
+    const changeBusy = (next) => {
+        setBusy(next);
+        latestBusy.current?.(next);
+    };
+    const Noun = noun.charAt(0).toUpperCase() + noun.slice(1);
+    const src = value === null ? null : uploaded?.id === value ? uploaded.thumbUrl : (thumbUrl ?? null);
+    const shown = src !== null && src !== broken ? src : null;
+    const pick = async (file) => {
+        if (!file)
+            return;
+        const refusal = imageRefusal(file, { accept, maxSize });
+        setProblem(refusal);
+        if (refusal)
+            return;
+        changeBusy(true);
+        setStatus(`Uploading ${noun}…`);
+        try {
+            const result = await upload(file);
+            if (!mounted.current)
+                return;
+            setUploaded({ id: result.id, thumbUrl: result.thumbUrl });
+            setBroken(null);
+            setStatus(`${Noun} added.`);
+            onChange(result.id);
+        }
+        catch (error) {
+            if (!mounted.current)
+                return;
+            setStatus('');
+            setProblem(uploadFailure(error, noun));
+        }
+        finally {
+            if (mounted.current)
+                changeBusy(false);
+        }
+    };
+    const remove = () => {
+        setProblem(null);
+        setStatus(`${Noun} removed.`);
+        onChange(null);
+        // Remove goes with the image: focus stays in the field.
+        main.current?.focus();
+    };
+    const open = () => {
+        if (!busy && !readOnly)
+            input.current?.click();
+    };
+    const describedBy = [ariaDescribedBy, problem ? errorId : undefined].filter(Boolean).join(' ') || undefined;
+    const mainLabel = busy ? `Uploading ${noun}…` : value !== null ? `Replace ${noun}` : `Add ${noun}`;
+    return (_jsxs("div", { "data-slot": "image-field", role: "group", "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy, "aria-busy": busy || undefined, className: cn('flex flex-col gap-2', className), children: [_jsxs("div", { className: "flex items-center gap-3", children: [value !== null ? (_jsxs("div", { className: "relative size-24 shrink-0 overflow-hidden rounded-lg border border-border bg-muted", children: [shown ? (_jsx("img", { src: shown, alt: alt ?? `Current ${noun}`, className: "size-full object-cover", onError: () => setBroken(shown) })) : (_jsx("div", { role: "img", "aria-label": alt ?? `Current ${noun}`, className: "flex size-full items-center justify-center text-muted-foreground", children: _jsx(ImageIcon, { "aria-hidden": "true", className: "size-6" }) })), busy && (_jsx("div", { className: "absolute inset-0 flex items-center justify-center bg-background/70", children: _jsx(Spinner, { "aria-hidden": "true", className: "size-5 text-foreground" }) }))] })) : (_jsx("div", { "aria-hidden": "true", onClick: open, className: cn('flex size-24 shrink-0 items-center justify-center rounded-lg border-2 border-dashed border-input text-muted-foreground', !busy && !readOnly && 'cursor-pointer hover:bg-muted'), children: busy ? _jsx(Spinner, { className: "size-5" }) : _jsx(ImagePlusIcon, { className: "size-6" }) })), _jsxs("div", { className: "flex flex-wrap items-center gap-2", children: [_jsxs(Button, { ref: main, id: id, type: "button", variant: "outline", size: "sm", "aria-label": mainLabel, "aria-describedby": describedBy, "aria-invalid": invalid || undefined, disabled: busy || readOnly, 
+                                // Keeps focus through an upload, so it's where it was after.
+                                focusableWhenDisabled: true, onClick: open, children: [busy ? (_jsx(Spinner, { "aria-hidden": "true" })) : value !== null ? (_jsx(RefreshCwIcon, { "aria-hidden": "true" })) : (_jsx(ImagePlusIcon, { "aria-hidden": "true" })), busy ? 'Uploading…' : value !== null ? 'Replace' : `Add ${noun}`] }), value !== null && (_jsxs(Button, { type: "button", variant: "ghost", size: "sm", "aria-label": `Remove ${noun}`, disabled: busy || readOnly, onClick: remove, children: [_jsx(XIcon, { "aria-hidden": "true" }), "Remove"] }))] })] }), problem && (_jsx("p", { id: errorId, role: "alert", "data-slot": "image-field-error", className: "type-caption text-destructive-text", children: problem })), _jsx("span", { role: "status", className: "sr-only", children: status }), _jsx("input", { ref: input, type: "file", accept: acceptAttribute(accept), hidden: true, tabIndex: -1, onChange: (event) => {
+                    const file = event.target.files?.[0];
+                    // Cleared, so picking the same file again still counts.
+                    event.target.value = '';
+                    void pick(file);
+                } })] }));
+}

package/dist/components/app/markdown.js

@@ -61,7 +61,7 @@ const COMPONENTS = {
     code: (props) => _jsx("code", { ...omitNode(props), className: "rounded bg-muted px-1 py-0.5 font-mono text-foreground" }),
     img: (props) => {
         const { alt, ...rest } = omitNode(props);
-        return _jsx("img", { ...rest, alt: alt ?? '', loading: "lazy", className: "max-w-full rounded-md" });
+        return _jsx("img", { ...rest, alt: alt ?? '', loading: "lazy", className: "h-auto max-w-full rounded-md" });
     },
     // GFM tables use the package's own table, zebra stripes and density
     // tokens included, so a table in the notes reads like every other table.

package/dist/components/app/milkdown-editor.d.ts

@@ -1,2 +1,2 @@
 import type { RichTextEditorProps } from './rich-text-editor.js';
-export default function MilkdownEditor({ id, defaultValue, onChange, onProblem, readOnly, autoFocus, placeholder, maxLength, toolbar, inline, className, 'aria-label': ariaLabel, 'aria-labelledby': ariaLabelledBy, 'aria-describedby': ariaDescribedBy, 'aria-invalid': ariaInvalid, }: RichTextEditorProps): import("react").JSX.Element;
+export default function MilkdownEditor({ id, defaultValue, onChange, onProblem, readOnly, autoFocus, placeholder, maxLength, toolbar, inline, upload, imageAccept, imageMaxSize, className, 'aria-label': ariaLabel, 'aria-labelledby': ariaLabelledBy, 'aria-describedby': ariaDescribedBy, 'aria-invalid': ariaInvalid, }: RichTextEditorProps): import("react").JSX.Element;

package/dist/components/app/milkdown-editor.js

@@ -40,6 +40,10 @@ import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-run
 //   `toolbar={false}`.
 // - `inline`: the field drawn as the text it edits (no border, no box),
 //   for notes that are always editable where they're read.
+// - Images in the text show (`![alt](url)`), at most the field's width.
+//   With `upload`, an image pasted, dropped or picked with the toolbar's
+//   Image button is uploaded through it and goes in as `![](url)`
+//   (rich-text-image-upload.ts); a refusal or a failed upload is a toast.
 import { useEffect, useId, useRef, useState } from 'react';
 import { createPortal } from 'react-dom';
 import { defaultValueCtx, Editor, editorViewCtx, editorViewOptionsCtx, parserCtx, remarkStringifyOptionsCtx, rootCtx, schemaCtx, serializerCtx, } from '@milkdown/kit/core';
@@ -52,10 +56,12 @@ import { isInTable, TableMap } from '@milkdown/kit/prose/tables';
 import { Decoration, DecorationSet } from '@milkdown/kit/prose/view';
 import { $nodeSchema, $prose, $remark, getMarkdown } from '@milkdown/kit/utils';
 import { cn } from 'cn';
+import { toast } from 'sonner';
 import { Button } from '../ui/button.js';
 import { Field, FieldError, FieldLabel } from '../ui/field.js';
 import { Input } from '../ui/input.js';
 import { Popover, PopoverContent } from '../ui/popover.js';
+import { acceptAttribute } from '../../lib/image-file.js';
 import { linkHref, linkRefusal } from '../../lib/link-href.js';
 import { passEscapeThrough } from './escape-passthrough.js';
 import { calloutHandler, remarkCalloutNodes } from '../../lib/markdown-callout.js';
@@ -64,6 +70,7 @@ import { headingClass } from './prose-look.js';
 import { RichTextFloatingToolbar } from './rich-text-floating-toolbar.js';
 import { tableAt, toggleFormat } from './rich-text-formats.js';
 import { calloutKind, calloutView, tableView } from './rich-text-node-views.js';
+import { droppedFiles, imageUploadPlugin, pastedImages, uploadImages, uploadPlaceholders } from './rich-text-image-upload.js';
 import { handleShortcut } from './rich-text-shortcuts.js';
 import { addRowAtEnd, handleTableKey, runTableAction } from './rich-text-table.js';
 import { applySlash, closeSlash, slashItems, slashOptionId, slashPlugin, slashQuery, } from './rich-text-slash.js';
@@ -109,6 +116,12 @@ const calloutSchema = $nodeSchema('callout', () => ({
         },
     },
 }));
+function emptyImageTitles(node) {
+    if (node.type === 'image' && node.title == null)
+        node.title = '';
+    node.children?.forEach(emptyImageTitles);
+}
+const imageTitles = $remark('imageTitles', () => () => (tree) => emptyImageTitles(tree));
 // Raw HTML pasted in as Milkdown's html chip becomes the plain text it
 // shows, so a paste can never add markup to the Markdown.
 function htmlToText(fragment) {
@@ -240,7 +253,7 @@ function applyLink(view, target, href) {
     }
     view.dispatch(tr.scrollIntoView());
 }
-export default function MilkdownEditor({ id, defaultValue, onChange, onProblem, readOnly = false, autoFocus = false, placeholder, maxLength, toolbar = true, inline = false, className, 'aria-label': ariaLabel, 'aria-labelledby': ariaLabelledBy, 'aria-describedby': ariaDescribedBy, 'aria-invalid': ariaInvalid, }) {
+export default function MilkdownEditor({ id, defaultValue, onChange, onProblem, readOnly = false, autoFocus = false, placeholder, maxLength, toolbar = true, inline = false, upload, imageAccept, imageMaxSize, className, 'aria-label': ariaLabel, 'aria-labelledby': ariaLabelledBy, 'aria-describedby': ariaDescribedBy, 'aria-invalid': ariaInvalid, }) {
     const rootRef = useRef(null);
     const editorRef = useRef(null);
     const [linkBox, setLinkBox] = useState(null);
@@ -271,10 +284,12 @@ export default function MilkdownEditor({ id, defaultValue, onChange, onProblem,
     // rendered into through a portal.
     const [widgets, setWidgets] = useState([]);
     // The latest props, for the editor's callbacks, which are set up once.
-    const latest = useRef({ onChange, onProblem, readOnly, placeholder });
+    const latest = useRef({ onChange, onProblem, readOnly, placeholder, upload, imageAccept, imageMaxSize });
     useEffect(() => {
-        latest.current = { onChange, onProblem, readOnly, placeholder };
+        latest.current = { onChange, onProblem, readOnly, placeholder, upload, imageAccept, imageMaxSize };
     });
+    // The toolbar's Image button opens this file picker.
+    const imageInputRef = useRef(null);
     // The fixed bar above the text, and the menus over it (the floating
     // toolbar and the slash menu), which `'floating'` keeps on their own.
     const fixedToolbar = toolbar === true;
@@ -407,6 +422,42 @@ export default function MilkdownEditor({ id, defaultValue, onChange, onProblem,
         openLinkRef.current = openLink;
         // Paste, copy, the editor's own keys and the placeholder.
         const slashing = $prose(() => slashPlugin());
+        // Images pasted or dropped, uploaded through the app's `upload`; with
+        // none given, a paste or drop is left to the handlers after this one,
+        // as if this weren't here.
+        const imageUploads = $prose(() => imageUploadPlugin());
+        const startUploads = (view, files, at) => {
+            const { upload: send, imageAccept: accept, imageMaxSize: maxSize } = latest.current;
+            if (!send)
+                return false;
+            uploadImages(view, files, at, { upload: send, accept, maxSize, onError: (message) => toast.error(message) });
+            return true;
+        };
+        const imageInput = $prose(() => new Plugin({
+            props: {
+                handlePaste: (view, event) => {
+                    if (!latest.current.upload || !view.editable)
+                        return false;
+                    const files = pastedImages(event.clipboardData);
+                    if (files.length === 0)
+                        return false;
+                    event.preventDefault();
+                    return startUploads(view, files, null);
+                },
+                // Files from outside (a text or an image moved within the
+                // editor carries none).
+                handleDrop: (view, event, _slice, moved) => {
+                    if (moved || !latest.current.upload || !view.editable)
+                        return false;
+                    const files = droppedFiles(event.dataTransfer);
+                    if (files.length === 0)
+                        return false;
+                    event.preventDefault();
+                    const at = view.posAtCoords({ left: event.clientX, top: event.clientY })?.pos ?? view.state.selection.from;
+                    return startUploads(view, files, at);
+                },
+            },
+        }));
         const input = $prose((ctx) => new Plugin({
             props: {
                 // Plain text is read as Markdown, so `## Notes` or `**bold**`
@@ -576,9 +627,12 @@ export default function MilkdownEditor({ id, defaultValue, onChange, onProblem,
             .use(gfm)
             .use(calloutRemark)
             .use(calloutSchema)
+            .use(imageTitles)
             .use(history)
             .use(changes)
             .use(slashing)
+            .use(imageUploads)
+            .use(imageInput)
             .use(input);
         void make.create().then((editor) => {
             if (cancelled) {
@@ -617,6 +671,22 @@ export default function MilkdownEditor({ id, defaultValue, onChange, onProblem,
             view.setProps({ editable: () => !readOnly, attributes: JSON.parse(attributesKey) });
         });
     }, [readOnly, attributesKey]);
+    // The toolbar's Image button: the file picker, then each file picked
+    // uploaded in place of the selection, and focus back in the text.
+    const pickImages = () => imageInputRef.current?.click();
+    const imagesPicked = (files) => {
+        const send = latest.current.upload;
+        if (!editorView || !send || files.length === 0)
+            return;
+        uploadImages(editorView, files, null, {
+            upload: send,
+            accept: imageAccept,
+            maxSize: imageMaxSize,
+            onError: (message) => toast.error(message),
+        });
+        editorView.focus();
+    };
+    const uploading = editorState ? uploadPlaceholders(editorState).length : 0;
     // A toolbar button: its format on the selection, then focus back in the
     // text (Link opens the link box instead, which gives it back on close).
     const runFormat = (format) => {
@@ -709,7 +779,12 @@ export default function MilkdownEditor({ id, defaultValue, onChange, onProblem,
                     'rounded-lg border border-input transition-[border-color,box-shadow] focus-within:border-ring focus-within:ring-3 focus-within:ring-ring/50 dark:bg-input/30', !inline && 'has-[[aria-invalid=true]]:border-destructive has-[[aria-invalid=true]]:ring-destructive/20', className), children: [fixedToolbar && (_jsx(RichTextToolbar, { ref: toolbarRef, state: editorState, readOnly: readOnly, 
                         // Only once the editor is made: until then the editable element,
                         // and its id, aren't in the page (axe: aria-valid-attr-value).
-                        controls: editorState ? editableId : undefined, onFormat: runFormat, onTable: runTable, text: textElement })), _jsx("div", { ref: rootRef, className: cn(!inline && 'min-h-24 px-2.5 py-2', 
+                        controls: editorState ? editableId : undefined, onFormat: runFormat, onTable: runTable, onImage: upload ? pickImages : undefined, text: textElement })), upload && (_jsx("input", { ref: imageInputRef, type: "file", accept: acceptAttribute(imageAccept), multiple: true, hidden: true, tabIndex: -1, onChange: (event) => {
+                            const files = Array.from(event.target.files ?? []);
+                            // Cleared, so picking the same file again still counts.
+                            event.target.value = '';
+                            imagesPicked(files);
+                        } })), _jsx("div", { ref: rootRef, className: cn(!inline && 'min-h-24 px-2.5 py-2', 
                         // Read-only text is muted; the toolbar's buttons say so by being disabled.
                         'has-[[aria-readonly=true]]:text-muted-foreground', 
                         // The same type roles <Markdown> uses, so text reads the same
@@ -724,6 +799,10 @@ export default function MilkdownEditor({ id, defaultValue, onChange, onProblem,
                         // Headings, callouts and tables are drawn by their node views;
                         // these are the elements Milkdown draws itself.
                         '[&_a]:text-link [&_a]:underline [&_a]:decoration-link/40 [&_a]:underline-offset-4', '[&_blockquote]:border-l-2 [&_blockquote]:border-border [&_blockquote]:pl-4 [&_blockquote]:text-muted-foreground', '[&_pre]:overflow-x-auto [&_pre]:rounded-lg [&_pre]:bg-muted [&_pre]:p-3 [&_pre]:font-mono', '[&_:not(pre)>code]:rounded [&_:not(pre)>code]:bg-muted [&_:not(pre)>code]:px-1 [&_:not(pre)>code]:font-mono', '[&_hr]:my-2 [&_hr]:h-0.5 [&_hr]:rounded-full [&_hr]:border-0 [&_hr]:bg-rule', '[&_hr.ProseMirror-selectednode]:outline-2 [&_hr.ProseMirror-selectednode]:outline-offset-4 [&_hr.ProseMirror-selectednode]:outline-ring', 
+                        // An image, as <Markdown> shows it: never wider than the field.
+                        // (ProseMirror's own separator images, around an image alone on
+                        // its line, are left alone.)
+                        '[&_img[src]]:inline-block [&_img[src]]:h-auto [&_img[src]]:max-w-full [&_img[src]]:rounded-md [&_img[src]]:align-bottom', '[&_img.ProseMirror-selectednode]:outline-2 [&_img.ProseMirror-selectednode]:outline-offset-2 [&_img.ProseMirror-selectednode]:outline-ring', 
                         // A table: a header row on the muted fill, a line between every
                         // cell, cells that wrap and never shrink to nothing; selected
                         // cells (a drag across them) tinted.
@@ -743,7 +822,7 @@ export default function MilkdownEditor({ id, defaultValue, onChange, onProblem,
                             const next = event.relatedTarget;
                             if (!editorView.dom.contains(next) && !floatingRef.current?.contains(next))
                                 setFocused(false);
-                        } }))] }), showCount && (_jsx("p", { id: counterId, "data-slot": "rich-text-editor-count", className: cn('text-right type-caption tabular-nums', length > maxLength ? 'text-destructive-text' : 'text-muted-foreground'), children: length > maxLength
+                        } }))] }), upload && (_jsx("p", { role: "status", className: "sr-only", children: uploading > 0 ? `Uploading ${uploading === 1 ? 'an image' : `${uploading} images`}…` : '' })), showCount && (_jsx("p", { id: counterId, "data-slot": "rich-text-editor-count", className: cn('text-right type-caption tabular-nums', length > maxLength ? 'text-destructive-text' : 'text-muted-foreground'), children: length > maxLength
                     ? `${(length - maxLength).toLocaleString()} characters over the limit of ${maxLength.toLocaleString()}`
                     : `${length.toLocaleString()} of ${maxLength.toLocaleString()} characters` })), _jsx(Popover, { open: linkBox !== null, onOpenChange: (open) => !open && closeLink(), children: linkBox && (_jsx(LinkForm, { box: linkBox, onApply: (href) => {
                         const editor = editorRef.current;

package/dist/components/app/rich-text-editor.d.ts

@@ -1,3 +1,4 @@
+import type { ImageUpload } from '../../lib/image-file.js';
 export type RichTextEditorProps = {
     /** The editable element's id, for a label's `htmlFor` or a test. */
     id?: string;
@@ -36,6 +37,21 @@ export type RichTextEditorProps = {
      * `placeholder`, which is all an empty one shows.
      */
     inline?: boolean;
+    /**
+     * Images uploaded into the text: pasted, dropped, or picked with an
+     * Image button on the fixed toolbar. Each file goes through this (the
+     * app's own storage: the package knows no endpoint) and goes in as
+     * `![](url)`, from the result's `url`, else its `thumbUrl`. A
+     * placeholder shows where it will go while it uploads (it isn't saved);
+     * a refused file or a failed upload takes it away and says why in a
+     * toast. Without it, the editor handles no files: a paste or drop does
+     * what it always did.
+     */
+    upload?: ImageUpload;
+    /** The image types `upload` takes. Defaults to JPEG, PNG and WebP (`DEFAULT_IMAGE_TYPES`). */
+    imageAccept?: readonly string[];
+    /** The largest image `upload` takes, in bytes: a bigger one is refused before it's sent, with its size and the limit. */
+    imageMaxSize?: number;
     className?: string;
     /** The field's label. A rich-text area must have one: this, or `aria-labelledby`. */
     'aria-label'?: string;

package/dist/components/app/rich-text-editor.js

@@ -13,6 +13,11 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 // Raw HTML in the text shows as its characters, as <Markdown> shows it,
 // and nothing pasted or typed can add markup.
 //
+// Images in the text (`![alt](url)`) show, at most the field's width.
+// With `upload`, an image pasted, dropped or picked with the toolbar's
+// Image button is uploaded through the app's own storage and goes in as
+// `![](url)`; while it uploads, a placeholder shows where it will go.
+//
 // The editor (Milkdown) is loaded on first use, so a page that only reads
 // Markdown never downloads it. Until it arrives, a placeholder the size of
 // the field shows.

package/dist/components/app/rich-text-image-upload.d.ts

@@ -0,0 +1,42 @@
+import { Plugin, type EditorState, type Transaction } from '@milkdown/kit/prose/state';
+import { DecorationSet } from '@milkdown/kit/prose/view';
+import { type ImageFileRules, type ImageUpload } from '../../lib/image-file.js';
+/** The plugin that holds and draws the placeholders. */
+export declare function imageUploadPlugin(): Plugin<DecorationSet>;
+/** The uploads in flight: each placeholder's file name and where it is now, in document order. */
+export declare function uploadPlaceholders(state: EditorState): {
+    id: number;
+    name: string;
+    pos: number;
+}[];
+export type UploadTarget = {
+    readonly state: EditorState;
+    dispatch: (tr: Transaction) => void;
+    readonly isDestroyed?: boolean;
+};
+export type ImageUploadOptions = ImageFileRules & {
+    upload: ImageUpload;
+    /** A file refused before upload (its type, its size), or an upload that failed: why. */
+    onError: (message: string) => void;
+};
+/**
+ * Uploads `files` and inserts each as an image: at `at` (a drop's
+ * position), or with `at` null in place of the selection (a paste, the
+ * toolbar's button). A file refused by type or size never starts; each
+ * refusal's reason goes to `onError`. Returns whether any upload started.
+ */
+export declare function uploadImages(target: UploadTarget, files: readonly File[], at: number | null, options: ImageUploadOptions): boolean;
+type TransferLike = {
+    files?: ArrayLike<File> | null;
+    getData?: (type: string) => string;
+} | null;
+/**
+ * The files a paste uploads: its files, unless it also carries HTML with
+ * words in it. An office app copies a picture of the selection along with
+ * its text, and that paste is the text. A screenshot, or an image copied
+ * from a page (its HTML just the `<img>`), uploads.
+ */
+export declare function pastedImages(data: TransferLike): File[];
+/** The files a drop uploads: every file dropped from outside the editor. */
+export declare function droppedFiles(data: TransferLike): File[];
+export {};

package/dist/components/app/rich-text-image-upload.js

@@ -0,0 +1,174 @@
+// Images uploaded into the rich-text editor: pasted, dropped, or picked
+// from the toolbar's Image button, each sent through the app's `upload`
+// and inserted as `![](url)` where it was put. Only with `upload` given
+// (RichTextEditor's prop): without it, the editor handles none of this.
+//
+// While a file uploads, a placeholder ("Uploading photo.jpg…") shows where
+// it will go. The placeholder is a decoration, not part of the document:
+// nothing is saved for it, and an autosave mid-upload saves the text as
+// it is. It moves with the text around it, and what's typed at the caret
+// meanwhile goes after it, as if the image were already there; when the
+// upload resolves, the image goes in where it is now and the placeholder
+// goes. If the upload fails, the placeholder goes and `onError` gets the
+// reason; if the text around it was deleted meanwhile, the image is
+// dropped.
+//
+// Several files upload at once and go in in the order they came, each
+// waiting for the one before it to land or fail.
+//
+// React-free and DOM-free (but the placeholder's element, made only when
+// the view draws it), so its rules are unit tested in node
+// (tests/rich-text-image-upload.test.ts).
+import { Fragment, Slice } from '@milkdown/kit/prose/model';
+import { Plugin, PluginKey } from '@milkdown/kit/prose/state';
+import { dropPoint } from '@milkdown/kit/prose/transform';
+import { Decoration, DecorationSet } from '@milkdown/kit/prose/view';
+import { imageRefusal, uploadFailure } from '../../lib/image-file.js';
+const uploadKey = new PluginKey('rich-text-image-upload');
+// The placeholder's element: a muted chip with a spinner, never editable.
+function placeholderElement(name) {
+    const chip = document.createElement('span');
+    chip.contentEditable = 'false';
+    chip.dataset.slot = 'rich-text-image-upload';
+    chip.className =
+        'mx-0.5 inline-flex items-center gap-1.5 rounded-md bg-muted px-2 py-0.5 align-middle type-caption text-foreground';
+    const spinner = document.createElement('span');
+    spinner.setAttribute('aria-hidden', 'true');
+    spinner.className = 'inline-block size-3 animate-spin rounded-full border-2 border-current border-r-transparent';
+    chip.append(spinner, `Uploading ${name}…`);
+    return chip;
+}
+// A placeholder's decoration. `side: -1`: text typed at its spot goes
+// after it, where the image will be.
+function placeholder({ id, name, pos }) {
+    return Decoration.widget(pos, () => placeholderElement(name), { id, name, key: `upload-${id}`, side: -1 });
+}
+/** The plugin that holds and draws the placeholders. */
+export function imageUploadPlugin() {
+    return new Plugin({
+        key: uploadKey,
+        state: {
+            init: () => DecorationSet.empty,
+            apply: (tr, set) => {
+                const mapped = set.map(tr.mapping, tr.doc);
+                const action = tr.getMeta(uploadKey);
+                if (!action)
+                    return mapped;
+                if ('add' in action)
+                    return mapped.add(tr.doc, action.add.map(placeholder));
+                const id = 'remove' in action ? action.remove : action.land;
+                const rest = mapped.remove(mapped.find(undefined, undefined, (spec) => spec.id === id));
+                if ('remove' in action)
+                    return rest;
+                const at = tr.mapping.map(action.at, -1);
+                const waiting = rest.find(at, at).filter((decoration) => decoration.from === at);
+                // Made before `remove`, which empties the array it's given.
+                const moved = waiting.map((decoration) => placeholder({ ...decoration.spec, pos: action.after }));
+                return rest.remove(waiting).add(tr.doc, moved);
+            },
+        },
+        props: {
+            decorations: (state) => uploadKey.getState(state),
+        },
+    });
+}
+/** The uploads in flight: each placeholder's file name and where it is now, in document order. */
+export function uploadPlaceholders(state) {
+    const set = uploadKey.getState(state);
+    if (!set)
+        return [];
+    return set
+        .find()
+        .map((decoration) => ({ id: decoration.spec.id, name: decoration.spec.name, pos: decoration.from }))
+        .sort((a, b) => a.pos - b.pos);
+}
+function placeholderAt(state, id) {
+    return uploadPlaceholders(state).find((placeholder) => placeholder.id === id)?.pos ?? null;
+}
+function imageNode(state, src) {
+    return state.schema.nodes.image.create({ src, alt: '', title: '' });
+}
+// Where an image put at `pos` can go: `pos` itself in text, else the
+// nearest place that takes inline content (between two blocks, a new
+// paragraph there).
+function insertPoint(doc, pos, image) {
+    return dropPoint(doc, pos, new Slice(Fragment.from(image), 0, 0)) ?? pos;
+}
+let nextId = 0;
+/**
+ * Uploads `files` and inserts each as an image: at `at` (a drop's
+ * position), or with `at` null in place of the selection (a paste, the
+ * toolbar's button). A file refused by type or size never starts; each
+ * refusal's reason goes to `onError`. Returns whether any upload started.
+ */
+export function uploadImages(target, files, at, options) {
+    const accepted = [];
+    for (const file of files) {
+        const refusal = imageRefusal(file, options);
+        if (refusal)
+            options.onError(refusal);
+        else
+            accepted.push(file);
+    }
+    if (accepted.length === 0)
+        return false;
+    const tr = target.state.tr;
+    if (at === null && !tr.selection.empty)
+        tr.deleteSelection();
+    const pos = insertPoint(tr.doc, at ?? tr.selection.from, imageNode(target.state, ''));
+    const uploads = accepted.map((file) => ({ id: ++nextId, file }));
+    target.dispatch(tr.setMeta(uploadKey, { add: uploads.map(({ id, file }) => ({ id, name: file.name || 'image', pos })) }));
+    const settle = (id, outcome) => {
+        if (target.isDestroyed)
+            return;
+        const placeholder = placeholderAt(target.state, id);
+        if (placeholder === null)
+            return;
+        const next = target.state.tr;
+        if ('src' in outcome) {
+            const image = imageNode(target.state, outcome.src);
+            const where = insertPoint(next.doc, placeholder, image);
+            next.replaceWith(where, where, image);
+            next.setMeta(uploadKey, { land: id, at: placeholder, after: next.mapping.map(where, -1) + image.nodeSize });
+        }
+        else {
+            next.setMeta(uploadKey, { remove: id });
+            options.onError(uploadFailure(outcome.error));
+        }
+        target.dispatch(next);
+    };
+    // Every upload starts now; each lands after the one before it.
+    let previous = Promise.resolve();
+    for (const { id, file } of uploads) {
+        const outcome = new Promise((resolve) => resolve(options.upload(file).then((result) => ({ src: result.url ?? result.thumbUrl })))).catch((error) => ({ error }));
+        previous = previous.then(() => outcome).then((result) => settle(id, result));
+    }
+    return true;
+}
+// Whether pasted HTML has words in it, not just an image. Style and
+// script blocks and comments aren't words.
+function htmlHasText(html) {
+    const text = html
+        .replace(/<(style|script)\b[\s\S]*?<\/\1>/gi, '')
+        .replace(/<!--[\s\S]*?-->/g, '')
+        .replace(/<[^>]*>/g, '')
+        .replace(/&nbsp;|&#160;/g, ' ');
+    return text.trim().length > 0;
+}
+/**
+ * The files a paste uploads: its files, unless it also carries HTML with
+ * words in it. An office app copies a picture of the selection along with
+ * its text, and that paste is the text. A screenshot, or an image copied
+ * from a page (its HTML just the `<img>`), uploads.
+ */
+export function pastedImages(data) {
+    const files = Array.from(data?.files ?? []);
+    if (files.length === 0)
+        return [];
+    const html = data?.getData?.('text/html') ?? '';
+    return html && htmlHasText(html) ? [] : files;
+}
+/** The files a drop uploads: every file dropped from outside the editor. */
+export function droppedFiles(data) {
+    return Array.from(data?.files ?? []);
+}

package/dist/components/app/rich-text-toolbar.d.ts

@@ -17,10 +17,12 @@ export type FormatButtonsProps = {
     onFormat: (id: FormatId) => void;
     /** A Table menu item picked (only the fixed toolbar has the menu). */
     onTable?: (action: TableAction) => void;
+    /** The Image button pressed: pick images to upload. No button without it. */
+    onImage?: () => void;
     /** The editable element, for the Table menu to give focus back to. */
     text?: () => HTMLElement | null;
 };
-export declare function FormatButtons({ formats, state, readOnly, onFormat, onTable, text }: FormatButtonsProps): import("react").JSX.Element;
+export declare function FormatButtons({ formats, state, readOnly, onFormat, onTable, onImage, text }: FormatButtonsProps): import("react").JSX.Element;
 export interface RichTextToolbarProps {
     /** The editor's state now, to show which formats are on. Null until it's made. */
     state: EditorState | null;
@@ -31,10 +33,12 @@ export interface RichTextToolbarProps {
     onFormat: (id: FormatId) => void;
     /** A Table menu item picked: run it on the editor and give it focus back. */
     onTable: (action: TableAction) => void;
+    /** The Image button pressed (only when the editor uploads images). */
+    onImage?: () => void;
     /** The editable element, for the Table menu to give focus back to. */
     text: () => HTMLElement | null;
     /** The toolbar's element, for Alt+F10 to reach it from the text. */
     ref?: Ref<HTMLDivElement>;
 }
-export declare function RichTextToolbar({ state, readOnly, controls, onFormat, onTable, text, ref }: RichTextToolbarProps): import("react").JSX.Element;
+export declare function RichTextToolbar({ state, readOnly, controls, onFormat, onTable, onImage, text, ref }: RichTextToolbarProps): import("react").JSX.Element;
 export {};

package/dist/components/app/rich-text-toolbar.js

@@ -1,7 +1,8 @@
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 // The rich-text editor's fixed toolbar: one row of pressed/not-pressed
-// buttons above the text, each a format and its keyboard shortcut, and a
-// Table menu (rich-text-table-menu.tsx).
+// buttons above the text, each a format and its keyboard shortcut, a
+// Table menu (rich-text-table-menu.tsx), and, when the editor uploads
+// images, an Image button (a plain button: it opens the file picker).
 //
 // - One tab stop (ARIA's toolbar pattern): Tab reaches the last button
 //   used, the arrow keys, Home and End move along the row.
@@ -14,6 +15,8 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 // - Alt+F10 in the text reaches it (the floating toolbar first, when it's
 //   showing: rich-text-floating-toolbar.tsx).
 import { Fragment, useRef, useState } from 'react';
+import { ImageIcon } from 'lucide-react';
+import { Button } from '../ui/button.js';
 import { Separator } from '../ui/separator.js';
 import { Toggle } from '../ui/toggle.js';
 import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from '../ui/tooltip.js';
@@ -31,15 +34,18 @@ const SETS = {
 // A toolbar's row of buttons: one tab stop, the last one used (ARIA's
 // toolbar pattern); the arrow keys, Home and End move along the row. The
 // toolbar's element (`role="toolbar"`, its name) is the caller's.
-export function FormatButtons({ formats, state, readOnly, onFormat, onTable, text = () => null }) {
+export function FormatButtons({ formats, state, readOnly, onFormat, onTable, onImage, text = () => null }) {
     const apple = isApple();
     const groups = SETS[formats];
     const items = groups.flat();
+    // The Image button, last in the row, after the formats.
+    const imageIndex = onImage ? items.length : -1;
+    const count = items.length + (onImage ? 1 : 0);
     const buttons = useRef([]);
     // The one button Tab reaches: the last one used.
     const [current, setCurrent] = useState(0);
     const move = (index) => {
-        const next = (index + items.length) % items.length;
+        const next = (index + count) % count;
         setCurrent(next);
         buttons.current[next]?.focus();
     };
@@ -48,7 +54,7 @@ export function FormatButtons({ formats, state, readOnly, onFormat, onTable, tex
             ArrowRight: () => move(current + 1),
             ArrowLeft: () => move(current - 1),
             Home: () => move(0),
-            End: () => move(items.length - 1),
+            End: () => move(count - 1),
         };
         const action = keys[event.key];
         if (!action || event.metaKey || event.ctrlKey || event.altKey)
@@ -56,27 +62,29 @@ export function FormatButtons({ formats, state, readOnly, onFormat, onTable, tex
         event.preventDefault();
         action();
     };
-    return (_jsx(TooltipProvider, { delay: 400, children: groups.map((group, groupIndex) => (_jsxs(Fragment, { children: [groupIndex > 0 && _jsx(Separator, { orientation: "vertical", className: "mx-1 h-5 self-center" }), group.map((item) => {
-                    const index = items.indexOf(item);
-                    if (item.id === 'table')
-                        return (_jsx(RichTextTableMenu, { ref: (element) => {
-                                buttons.current[index] = element;
-                            }, state: state, readOnly: readOnly, tabIndex: index === current ? 0 : -1, onFocus: () => setCurrent(index), onKeyDown: onKeyDown, onInsert: () => onFormat('table'), onAction: (action) => onTable?.(action), text: text }, item.id));
-                    const Icon = item.icon;
-                    const tip = [
-                        item.label,
-                        item.keys && `(${shownKeys(item.keys, apple)})`,
-                        item.hint && `· ${item.hint.replace(/Mod\+Shift\+Enter/, shownKeys('Mod+Shift+Enter', apple))}`,
-                    ]
-                        .filter(Boolean)
-                        .join(' ');
-                    return (_jsxs(Tooltip, { children: [_jsx(TooltipTrigger, { render: _jsx(Toggle, { ref: (element) => {
-                                        buttons.current[index] = element;
-                                    }, size: "icon-sm", "aria-label": item.label, "aria-keyshortcuts": item.keys ? ariaKeys(item.keys, apple) : undefined, pressed: state ? formatOn(state, item.id) : false, disabled: readOnly, tabIndex: index === current ? 0 : -1, className: "aria-pressed:bg-muted aria-pressed:text-foreground", 
-                                    // A mouse press keeps focus, and the selection, in the text.
-                                    onMouseDown: (event) => event.preventDefault(), onFocus: () => setCurrent(index), onKeyDown: onKeyDown, onPressedChange: () => onFormat(item.id) }), children: _jsx(Icon, {}) }), _jsx(TooltipContent, { children: tip })] }, item.id));
-                })] }, groupIndex))) }));
+    return (_jsxs(TooltipProvider, { delay: 400, children: [groups.map((group, groupIndex) => (_jsxs(Fragment, { children: [groupIndex > 0 && _jsx(Separator, { orientation: "vertical", className: "mx-1 h-5 self-center" }), group.map((item) => {
+                        const index = items.indexOf(item);
+                        if (item.id === 'table')
+                            return (_jsx(RichTextTableMenu, { ref: (element) => {
+                                    buttons.current[index] = element;
+                                }, state: state, readOnly: readOnly, tabIndex: index === current ? 0 : -1, onFocus: () => setCurrent(index), onKeyDown: onKeyDown, onInsert: () => onFormat('table'), onAction: (action) => onTable?.(action), text: text }, item.id));
+                        const Icon = item.icon;
+                        const tip = [
+                            item.label,
+                            item.keys && `(${shownKeys(item.keys, apple)})`,
+                            item.hint && `· ${item.hint.replace(/Mod\+Shift\+Enter/, shownKeys('Mod+Shift+Enter', apple))}`,
+                        ]
+                            .filter(Boolean)
+                            .join(' ');
+                        return (_jsxs(Tooltip, { children: [_jsx(TooltipTrigger, { render: _jsx(Toggle, { ref: (element) => {
+                                            buttons.current[index] = element;
+                                        }, size: "icon-sm", "aria-label": item.label, "aria-keyshortcuts": item.keys ? ariaKeys(item.keys, apple) : undefined, pressed: state ? formatOn(state, item.id) : false, disabled: readOnly, tabIndex: index === current ? 0 : -1, className: "aria-pressed:bg-muted aria-pressed:text-foreground", 
+                                        // A mouse press keeps focus, and the selection, in the text.
+                                        onMouseDown: (event) => event.preventDefault(), onFocus: () => setCurrent(index), onKeyDown: onKeyDown, onPressedChange: () => onFormat(item.id) }), children: _jsx(Icon, {}) }), _jsx(TooltipContent, { children: tip })] }, item.id));
+                    })] }, groupIndex))), onImage && (_jsxs(_Fragment, { children: [_jsx(Separator, { orientation: "vertical", className: "mx-1 h-5 self-center" }), _jsxs(Tooltip, { children: [_jsx(TooltipTrigger, { render: _jsx(Button, { ref: (element) => {
+                                        buttons.current[imageIndex] = element;
+                                    }, variant: "ghost", size: "icon-sm", "aria-label": "Image", disabled: readOnly, tabIndex: imageIndex === current ? 0 : -1, onMouseDown: (event) => event.preventDefault(), onFocus: () => setCurrent(imageIndex), onKeyDown: onKeyDown, onClick: onImage }), children: _jsx(ImageIcon, {}) }), _jsx(TooltipContent, { children: "Image \u00B7 or paste or drop one" })] })] }))] }));
 }
-export function RichTextToolbar({ state, readOnly, controls, onFormat, onTable, text, ref }) {
-    return (_jsx("div", { ref: ref, role: "toolbar", "aria-label": "Formatting", "aria-controls": controls, "data-slot": "rich-text-toolbar", className: "flex flex-wrap items-center gap-0.5 border-b border-input px-1 py-1", children: _jsx(FormatButtons, { formats: "all", state: state, readOnly: readOnly, onFormat: onFormat, onTable: onTable, text: text }) }));
+export function RichTextToolbar({ state, readOnly, controls, onFormat, onTable, onImage, text, ref }) {
+    return (_jsx("div", { ref: ref, role: "toolbar", "aria-label": "Formatting", "aria-controls": controls, "data-slot": "rich-text-toolbar", className: "flex flex-wrap items-center gap-0.5 border-b border-input px-1 py-1", children: _jsx(FormatButtons, { formats: "all", state: state, readOnly: readOnly, onFormat: onFormat, onTable: onTable, onImage: onImage, text: text }) }));
 }

package/dist/index.d.ts

@@ -31,6 +31,8 @@ export { ProgressRing, type ProgressRingProps } from './components/app/progress-
 export { StepBar, type StepBarProps } from './components/app/step-bar.js';
 export { RatingStar, type RatingStarProps, type RatingStarValue } from './components/app/rating-star.js';
 export { DateField, type DateFieldProps } from './components/app/date-field.js';
+export { ImageField, type ImageFieldProps } from './components/app/image-field.js';
+export { DEFAULT_IMAGE_TYPES, type ImageUpload, type ImageUploadResult } from './lib/image-file.js';
 export { formatPlainDate, type PlainDate } from './lib/plain-date.js';
 export { ChoiceCell, LinkCell, NameCell, type ChoiceCellProps, type LinkCellProps, type NameCellProps, } from './components/app/row-edit-cells.js';
 export { WidgetCard, WidgetList, WidgetListItem, type WidgetCardProps, type WidgetListItemProps, } from './components/app/widget-card.js';

package/dist/index.js

@@ -36,6 +36,8 @@ export { ProgressRing } from './components/app/progress-ring.js';
 export { StepBar } from './components/app/step-bar.js';
 export { RatingStar } from './components/app/rating-star.js';
 export { DateField } from './components/app/date-field.js';
+export { ImageField } from './components/app/image-field.js';
+export { DEFAULT_IMAGE_TYPES } from './lib/image-file.js';
 export { formatPlainDate } from './lib/plain-date.js';
 export { ChoiceCell, LinkCell, NameCell, } from './components/app/row-edit-cells.js';
 export { WidgetCard, WidgetList, WidgetListItem, } from './components/app/widget-card.js';

package/dist/lib/image-file.d.ts

@@ -0,0 +1,37 @@
+/** What an app's upload resolves to: the stored file's id and its addresses. */
+export type ImageUploadResult = {
+    /** The stored file's id, what the record keeps (ImageField's value). */
+    id: string;
+    /** A small version for a thumbnail (ImageField shows it). */
+    thumbUrl: string;
+    /**
+     * The full-size image, for text (`![](url)` in the rich-text editor).
+     * Without it the editor inserts `thumbUrl`.
+     */
+    url?: string;
+};
+/**
+ * The app's upload: sends one file to its own storage and resolves to
+ * where it is, or rejects (an `AppError`, an `Error`: its `message` is
+ * shown).
+ */
+export type ImageUpload = (file: File) => Promise<ImageUploadResult>;
+/** The image types accepted unless a field says otherwise. */
+export declare const DEFAULT_IMAGE_TYPES: readonly string[];
+export type ImageFileRules = {
+    /** MIME types, `image/jpeg`; `image/*` for any image. Defaults to `DEFAULT_IMAGE_TYPES`. */
+    accept?: readonly string[];
+    /** The largest file accepted, in bytes. No limit when unset. */
+    maxSize?: number;
+};
+/** A size as a person reads it: "820 KB", "4.2 MB". */
+export declare function formatBytes(bytes: number): string;
+/** The `accept` attribute for a file input: `image/jpeg,image/png,image/webp`. */
+export declare function acceptAttribute(accept?: readonly string[]): string;
+/**
+ * Why a file can't be uploaded, as a sentence to show under the field, or
+ * null when it can: a type not accepted, or over the size limit.
+ */
+export declare function imageRefusal(file: Pick<File, 'type' | 'size'>, rules?: ImageFileRules): string | null;
+/** What a failed upload says: the rejection's own `message` (an `AppError`'s), else a generic sentence. */
+export declare function uploadFailure(error: unknown, noun?: string): string;

package/dist/lib/image-file.js

@@ -0,0 +1,82 @@
+// Images a person picks, pastes or drops, before they're uploaded: which
+// files are accepted, and why one isn't, in words. Shared by ImageField
+// and the rich-text editor's upload. The upload itself is the app's (an
+// `ImageUpload`): the package knows no endpoint and no storage.
+/** The image types accepted unless a field says otherwise. */
+export const DEFAULT_IMAGE_TYPES = ['image/jpeg', 'image/png', 'image/webp'];
+// How a type is named to a person: "JPEG", not "image/jpeg".
+const TYPE_NAMES = {
+    'image/jpeg': 'JPEG',
+    'image/png': 'PNG',
+    'image/webp': 'WebP',
+    'image/gif': 'GIF',
+    'image/avif': 'AVIF',
+    'image/heic': 'HEIC',
+    'image/heif': 'HEIF',
+    'image/svg+xml': 'SVG',
+    'image/bmp': 'BMP',
+    'image/tiff': 'TIFF',
+    'application/pdf': 'PDF',
+};
+function typeName(type) {
+    if (TYPE_NAMES[type])
+        return TYPE_NAMES[type];
+    if (type === 'image/*')
+        return 'image';
+    const subtype = type.split('/')[1] ?? type;
+    return subtype.replace(/^x-/, '').toUpperCase();
+}
+// "JPEG, PNG or WebP".
+function listOr(names) {
+    return names.length <= 1 ? (names[0] ?? '') : `${names.slice(0, -1).join(', ')} or ${names.at(-1)}`;
+}
+/** A size as a person reads it: "820 KB", "4.2 MB". */
+export function formatBytes(bytes) {
+    if (bytes < 1024)
+        return `${bytes} bytes`;
+    if (bytes < 1024 * 1024)
+        return `${Math.round(bytes / 1024)} KB`;
+    const mb = bytes / (1024 * 1024);
+    return `${mb < 10 ? Math.round(mb * 10) / 10 : Math.round(mb)} MB`;
+}
+function accepts(accept, type) {
+    return accept.some((allowed) => allowed === type || (allowed.endsWith('/*') && type.startsWith(allowed.slice(0, -1))));
+}
+/** The `accept` attribute for a file input: `image/jpeg,image/png,image/webp`. */
+export function acceptAttribute(accept = DEFAULT_IMAGE_TYPES) {
+    return accept.join(',');
+}
+/**
+ * Why a file can't be uploaded, as a sentence to show under the field, or
+ * null when it can: a type not accepted, or over the size limit.
+ */
+export function imageRefusal(file, rules = {}) {
+    const accept = rules.accept ?? DEFAULT_IMAGE_TYPES;
+    if (!accepts(accept, file.type)) {
+        const wanted = listOr(accept.map(typeName));
+        const choose = accept.length === 1 && accept[0] === 'image/*' ? 'Choose an image.' : `Choose a ${wanted} image.`;
+        // A type with a name people know is named; any other file that isn't
+        // an image is just that.
+        const named = TYPE_NAMES[file.type] ?? (file.type.startsWith('image/') ? typeName(file.type) : null);
+        return named ? `That file is ${article(named)} ${named}. ${choose}` : `That file isn't an image. ${choose}`;
+    }
+    if (rules.maxSize !== undefined && file.size > rules.maxSize) {
+        return `That image is ${formatBytes(file.size)}. The limit is ${formatBytes(rules.maxSize)}.`;
+    }
+    return null;
+}
+// "a GIF", "an SVG", "an HEIC": by how the name is said, letter by letter
+// when it's an acronym.
+function article(name) {
+    const spelled = /^[A-Z][A-Z0-9]+$/.test(name);
+    return (spelled ? /^[AEFHILMNORSX]/ : /^[aeiou]/i).test(name) ? 'an' : 'a';
+}
+/** What a failed upload says: the rejection's own `message` (an `AppError`'s), else a generic sentence. */
+export function uploadFailure(error, noun = 'image') {
+    if (error && typeof error === 'object' && 'message' in error) {
+        const message = error.message;
+        if (typeof message === 'string' && message.trim())
+            return message;
+    }
+    return `The ${noun} couldn't be uploaded. Try again.`;
+}

package/dist/lib/markdown-merge.js

@@ -21,7 +21,7 @@
 //   padded, marks it nested differently) and that `meaning` still misses is
 //   written as the editor shows it, as long as nothing in it is lost
 //   (`content`): no text, address or image. A block the editor drops part
-//   of (it doesn't show images) is kept as written, and the guard refuses.
+//   of (until 4.28, every image) is kept as written, and the guard refuses.
 // - Guard: the result must mean exactly what the editor shows. If it
 //   wouldn't (two blocks fusing, say), the merge throws instead of saving
 //   something else; the draft stays on screen.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tristan2828/ui-foundation",
-  "version": "4.26.0",
+  "version": "4.28.0",
   "description": "Shared UI foundation for contract-first, database-backed React apps: shadcn primitives, DataTable/EntityForm composites, auth, the gateway error seam, design tokens, lint rules and the AI playbook.",
   "license": "MIT",
   "repository": {