@tristan2828/ui-foundation 4.27.0 → 4.29.0

package/conventions/AGENTS.md

@@ -47,7 +47,9 @@ is right. Do not disable, skip, or work around it.
 - NEVER use a raw hex value or a Tailwind palette color (`bg-blue-500`).
   Semantic tokens only: `bg-primary`, `text-muted-foreground`. (Enforced:
   the foundation's ESLint token rule; axe contrast in light and dark mode,
-  `e2e/a11y.spec.ts`.)
+  `e2e/a11y.spec.ts`.) The one exception is an app's `--brand-<name>`
+  tokens, for logos and brand marks only (`docs/foundation/design-language.md`
+  "Logos and brand marks").
 - NEVER fetch in `useEffect`. All server state goes through TanStack Query.
   (Enforced: eslint-plugin-query + the no-bare-fetch rule.)
 - NEVER read auth state outside `useAuth()`. The package exports nothing

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

@@ -187,6 +187,35 @@ 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.

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.

package/conventions/docs/design-language.md

@@ -101,6 +101,50 @@ doesn't (2.7:1). A deliberately faint icon that carries nothing on its
 own (an "empty" star beside a rating's filled ones, pattern 9) may go
 lower; say so in a comment.
 
+## Logos and brand marks
+
+An app's own logo (`AppShell`'s `logo`) and the marks of the services it
+links to (a video site's mark on "Open on …", on a `WidgetCard` about it)
+are **icon components** (`IconComponent`): sized by a `size-*` class,
+`aria-hidden` passed through to the `<svg>`, with the same props as a
+Lucide icon, so they go wherever an icon goes. Lucide has no brand logos,
+and the package ships none: an app keeps the few it needs as its own
+components (Simple Icons' paths are CC0), with no icon pack as a
+dependency.
+
+Colour them in one of two ways:
+
+- **`currentColor`** for a one-colour mark that isn't a colour of its own
+  (a black or white logo): it takes the text colour around it, so it
+  turns over with the theme. The default.
+- **A brand token** for a mark whose colour *is* the brand (a red play
+  button). Define it in the app's `src/index.css`, the same value in both
+  themes, since a logo keeps its colours, and register it so it's a
+  class:
+
+  ```css
+  :root {
+    --brand-videosite: #ff0033;
+    --brand-videosite-foreground: #ffffff;
+  }
+  @theme inline {
+    --color-brand-videosite: var(--brand-videosite);
+    --color-brand-videosite-foreground: var(--brand-videosite-foreground);
+  }
+  ```
+
+  Then `fill-brand-videosite` on the mark's shape. This is the one place
+  a raw colour value is right, and it doesn't break "semantic tokens
+  only": the token's name says what it's for. **Brand tokens paint
+  marks only**: never text, a surface, a border, a focus ring or a tone.
+  A mark is decorative (whatever it sits beside names it), so it isn't
+  held to the 3:1 above, but check it against the page in both themes;
+  where it vanishes in one, give it a `currentColor` outline or use the
+  one-colour mark there.
+
+The package's own stories show the slots with made-up marks in
+`currentColor` (`app/AppShell` With logo, `app/WidgetCard` Brand mark).
+
 ## Categorical colour
 
 Tones say good, bad or *notice this*. A value that is merely *different* from its

package/conventions/docs/timed-screens.md

@@ -7,9 +7,9 @@ package has the parts, so a screen like this is assembled, not rebuilt:
 | Part | What it does |
 |---|---|
 | `SessionView` | The whole viewport over the app shell: a modal named by its title, focus kept inside, Esc closes it. Optional real fullscreen and a held wake lock |
-| `useSessionClock` | A clock that doesn't drift, with pause and resume: `idle`, `running`, `done` |
+| `useSessionClock` | A clock that doesn't drift, with pause, resume and seek: `idle`, `running`, `done` |
 | `useWakeLock` | Keeps the screen on while a session runs (`SessionView`'s `keepAwake` uses it) |
-| `unlockAudio`, `chime`, `sequence`, `say`, `hush`, `vibrate` | Sound cues with no audio files |
+| `unlockAudio`, `chime`, `sequence`, `cancelCues`, `say`, `hush`, `vibrate` | Sound cues with no audio files, booked ahead where they must be on time |
 | `canVibrate` | Whether this browser can vibrate, to offer a Vibrate setting only where it works |
 | `useMuted` | A mute toggle remembered on this device |
 | `usePrefersReducedMotion` | Whether to swap movement for a fade |
@@ -58,7 +58,7 @@ const primary = useRef<HTMLButtonElement>(null)
 ## The clock
 
 `useSessionClock({ running?, endsAt? })` returns
-`{ elapsed, status, paused, start, pause, resume, stop }`.
+`{ elapsed, status, paused, start, startFrom, seek, pause, resume, stop }`.
 
 - `elapsed` is in milliseconds, read from `performance.now()` each
   animation frame. It is never summed from ticks, so it doesn't drift.
@@ -73,8 +73,15 @@ const primary = useRef<HTMLButtonElement>(null)
   front of it.
 - It re-renders once per frame, only while counting. Format what it shows
   from `elapsed`, never by counting renders.
-- A hidden tab draws no frames, but its time still counts. The first frame
-  back catches up, and reaches `done` if it's due.
+- A hidden tab draws no frames, but its time still counts. While hidden,
+  the clock reads the time on a slow tick instead (once a second at most),
+  enough for a countdown in the tab's title, and coming back catches up
+  exactly, reaching `done` if it's due. See "Background tabs" below.
+- `startFrom(ms)` starts a run at a given elapsed time: one resumed from
+  storage after a reload. `seek(ms)` moves a running run there, paused or
+  not, for Skip and Back; at or past `endsAt` it's `done`. A seek while
+  idle or done does nothing: use `startFrom`. Pause and resume stay exact
+  after either. Don't keep a `Date.now()` clock of your own beside it.
 
 For phases (stretch two minutes, rest thirty seconds), keep one clock for
 the whole session and work out the phase from `elapsed`. A clock per
@@ -88,10 +95,13 @@ Browsers block sound until the person has clicked or tapped. So:
   click handler itself, not in an effect after it. Every cue before that
   is dropped rather than played late. iOS also needs speech started from
   a click, and `unlockAudio()` does that too.
-- `chime({ pitch?, volume?, duration? })`: a soft sine tone, a short
+- `chime({ pitch?, volume?, duration?, at? })`: a soft sine tone, a short
   attack and a slow fade. `pitch` is in Hz (660 by default). For a
   closing pair, use `sequence([{ pitch: 660 }, { pitch: 880 }])`, 180 ms
-  apart by default.
+  apart by default. `at` (a `Date.now()` time; `sequence` takes it in its
+  options) books it ahead: see "Background tabs". Each returns a handle
+  whose `cancel()` takes back what hasn't sounded yet, and `cancelCues()`
+  takes back every booked chime.
 - `say(text)` speaks a line ("Next: stretch, 2 minutes"), cutting off any
   line still being spoken. `hush()` stops it. Call `hush()` when the
   session stops or the view closes.
@@ -112,7 +122,42 @@ Browsers block sound until the person has clicked or tapped. So:
   (`aria-pressed={muted}`) named "Mute".
 - **Cue on a change of state** in an effect that compares the previous
   state with the current one, so the cue plays once. Never play a cue
-  during render.
+  during render. A cue that must be on time while the tab is in the
+  background (a phase ending) is booked ahead instead, below.
+
+## Background tabs
+
+A timer is often left running in a tab behind another. The browser draws
+no frames there and slows its timers (Chrome to about once a minute after
+a few minutes), so anything driven by them runs late: a chime from an
+effect on a phase change sounds when the person comes back, not when the
+phase ends. Web Audio's own clock keeps time, so:
+
+- **Book the cues ahead from the run's plan.** When counting starts
+  (start, resume, the view reopened, unmuted), work out when each coming
+  cue is due from the plan and the clock's position, and book it:
+  `sequence(closingPair, { at: Date.now() + endsAt - clock.elapsed })`,
+  a `chime({ at })` for each phase boundary. They strike on time whatever
+  the page's timers do.
+- **Take them back whenever counting stops, and rebook when the run
+  moves:** `cancelCues()` on pause, on closing the view, on mute and on
+  leaving the screen (an effect's cleanup); on Skip and Back, `seek`,
+  then `cancelCues()` and book again from the new position. A chime
+  already sounding rings out. Reaching `done` takes nothing back: the
+  closing cue is sounding then.
+- **Do it in the handlers**, where you know why counting stopped, not in
+  an effect on `paused`: an effect's cleanup can't tell pause from done.
+  The Timer story (`app/SessionView`) does exactly this.
+- **Speech can't be booked.** `say()` still comes when the clock's slow
+  tick reaches the moment, so in a background tab it may be late. Keep
+  what must be on time to chimes.
+- **The tab's title** (`Focus 18:42`) can count down from `elapsed`: the
+  clock's slow tick re-renders while hidden. Set it in an effect, and put
+  the plain title back when the run ends. A tick a browser has slowed to
+  once a minute shows a coarser countdown; the time itself is never off.
+- Booked cues need `unlockAudio()` from a click, like any other. iOS
+  Safari may suspend audio in a background tab altogether; nothing in a
+  web page gets round that.
 
 ## Motion
 
@@ -162,6 +207,67 @@ test('running, paused and done', async ({ page }) => {
   `page.addInitScript(() => localStorage.setItem('my-app:routine:muted', 'true'))`.
 - **Reduced motion:** `await page.emulateMedia({ reducedMotion: 'reduce' })`.
 
+**A background tab:** set the page's visibility yourself, stop its
+animation frames, and record what's booked on a stand-in `AudioContext`:
+
+```ts
+test.beforeEach(async ({ page }) => {
+  await page.clock.install()
+  await page.addInitScript(() => {
+    let visibility: DocumentVisibilityState = 'visible'
+    Object.defineProperty(document, 'visibilityState', { get: () => visibility })
+    Object.defineProperty(document, 'hidden', { get: () => visibility === 'hidden' })
+    const booked: { pitch: number; at: number; cancelled: boolean }[] = []
+    class RecordingAudioContext {
+      state = 'running'; currentTime = 0; destination = {}
+      resume = async () => {}
+      last = { pitch: 0, at: 0, cancelled: false }
+      createOscillator() {
+        const cue = (this.last = { pitch: 0, at: 0, cancelled: false })
+        return {
+          frequency: { setValueAtTime: (hz: number) => (cue.pitch = hz) },
+          connect: (node: unknown) => node,
+          start: (at: number) => booked.push(Object.assign(cue, { at })),
+          stop: () => {},
+        }
+      }
+      createGain() {
+        const cue = this.last
+        return {
+          gain: { setValueAtTime() {}, exponentialRampToValueAtTime() {} },
+          connect: (node: unknown) => node,
+          disconnect: () => (cue.cancelled = true),
+        }
+      }
+    }
+    Object.assign(window, {
+      AudioContext: RecordingAudioContext,
+      __booked: booked,
+      __hide() {
+        visibility = 'hidden'
+        window.requestAnimationFrame = () => 0   // a hidden tab draws no frames
+        document.dispatchEvent(new Event('visibilitychange'))
+      },
+    })
+  })
+})
+
+test('the end is booked ahead, and the title counts down while hidden', async ({ page }) => {
+  await page.goto('/routine')
+  await page.getByRole('button', { name: 'Start' }).click()
+  // Seconds ahead on the audio clock: the closing pair five minutes on.
+  const booked = () => page.evaluate(() => (window as any).__booked.map((c: any) => [c.pitch, Math.round(c.at), c.cancelled]))
+  await expect.poll(booked).toContainEqual([660, 300, false])
+
+  await page.evaluate(() => (window as any).__hide())
+  await page.clock.fastForward('00:10')
+  await expect(page).toHaveTitle(/^4:50/)
+})
+```
+
+Pause, Skip and Back are asserted the same way: the earlier booking's
+`cancelled` turns true and a new one appears at the new time.
+
 **An open-ended count-up: pause the fake clock.** After
 `clock.install()` the fake clock still moves in real time between
 steps, so every reading picks up however long the machine took since the

package/dist/components/app/app-shell.d.ts

@@ -1,6 +1,7 @@
 import { type ReactNode } from 'react';
 import { type NavEntry } from './app-shell-nav.js';
 import { type AppShellVersion } from './app-shell-version.js';
+import type { IconComponent } from './icon-component.js';
 export type { NavEntry, NavItem, NavSection } from './app-shell-nav.js';
 export type { AppShellVersion } from './app-shell-version.js';
 export type AppShellProps = {
@@ -12,6 +13,14 @@ export type AppShellProps = {
      * does, with its record's title).
      */
     title: string;
+    /**
+     * The app's mark, shown before `title` at the top of the sidebar, and
+     * alone, centred, at the top of the collapsed icon rail. Drawn like an
+     * icon (`IconComponent`: sized by the shell, `aria-hidden` passed
+     * through) and decorative, since `title` names the app. Its own colours,
+     * or `currentColor` for the sidebar's text colour.
+     */
+    logo?: IconComponent;
     /**
      * The app's primary navigation, in order: pages, and labelled sections of
      * pages (`{ label, items }`, one per module, say). A nav with no sections
@@ -44,4 +53,4 @@ export type AppShellProps = {
      */
     version?: AppShellVersion;
 };
-export declare function AppShell({ title, nav, sidebarExtra, defaultSidebarOpen, version }: AppShellProps): import("react").JSX.Element;
+export declare function AppShell({ title, logo: Logo, nav, sidebarExtra, defaultSidebarOpen, version }: AppShellProps): import("react").JSX.Element;

package/dist/components/app/app-shell.js

@@ -110,7 +110,7 @@ function CollapsibleNavGroup({ group, activeTo }) {
 function AppShellSkeleton() {
     return (_jsxs("div", { className: "flex h-screen w-full gap-4 p-4", "data-state": "loading", children: [_jsx(Skeleton, { className: "h-full w-56 shrink-0" }), _jsxs("div", { className: "flex-1 space-y-4 pt-2", children: [_jsx(Skeleton, { className: "h-8 w-64" }), _jsx(Skeleton, { className: "h-40 w-full" })] })] }));
 }
-export function AppShell({ title, nav, sidebarExtra, defaultSidebarOpen = true, version }) {
+export function AppShell({ title, logo: Logo, nav, sidebarExtra, defaultSidebarOpen = true, version }) {
     const { user, status, error, retry, logout } = useAuth();
     const location = useLocation();
     const reporter = useErrorReporter();
@@ -140,7 +140,7 @@ export function AppShell({ title, nav, sidebarExtra, defaultSidebarOpen = true,
         return _jsx(Navigate, { to: "/login", replace: true, state: isLoggingOut ? undefined : { from } });
     }
     const activeTo = activeNavTo(nav, location.pathname);
-    return (_jsxs(TooltipProvider, { children: [reporter && _jsx(ReportRoutePattern, { reporter: reporter }), _jsxs(SidebarProvider, { defaultOpen: storedSidebarOpen(defaultSidebarOpen), children: [_jsx(CloseMobileSidebarOnNavigate, {}), _jsx("nav", { "aria-label": "Primary", children: _jsxs(Sidebar, { collapsible: "icon", children: [_jsx(SidebarHeader, { children: _jsx("span", { className: "px-2 text-sm font-semibold text-sidebar-foreground group-data-[collapsible=icon]:hidden", children: title }) }), _jsxs(SidebarContent, { children: [navGroups(nav).map((group, groupIndex) => group.collapsible && group.label !== undefined ? (_jsx(CollapsibleNavGroup, { group: { ...group, label: group.label }, activeTo: activeTo }, `${groupIndex}:${group.label}`)) : (_jsxs(SidebarGroup, { children: [group.label !== undefined && _jsx(SidebarGroupLabel, { children: group.label }), _jsx(SidebarGroupContent, { children: _jsx(NavMenu, { items: group.items, activeTo: activeTo }) })] }, `${groupIndex}:${group.label ?? ''}`))), sidebarExtra] }), _jsxs(SidebarFooter, { children: [version && _jsx(VersionEntry, { version: version }), _jsxs("div", { className: "flex items-center justify-between gap-2 px-2 group-data-[collapsible=icon]:justify-center group-data-[collapsible=icon]:px-0", children: [_jsx("span", { className: "truncate type-caption text-sidebar-foreground/70 group-data-[collapsible=icon]:hidden", children: user.name }), _jsx(Button, { variant: "ghost", size: "icon-sm", "aria-label": "Log out", onClick: () => {
+    return (_jsxs(TooltipProvider, { children: [reporter && _jsx(ReportRoutePattern, { reporter: reporter }), _jsxs(SidebarProvider, { defaultOpen: storedSidebarOpen(defaultSidebarOpen), children: [_jsx(CloseMobileSidebarOnNavigate, {}), _jsx("nav", { "aria-label": "Primary", children: _jsxs(Sidebar, { collapsible: "icon", children: [_jsx(SidebarHeader, { children: _jsxs("div", { className: "flex items-center gap-2 px-2 group-data-[collapsible=icon]:justify-center group-data-[collapsible=icon]:px-0", children: [Logo && (_jsx(Logo, { "aria-hidden": "true", className: "size-5 shrink-0 text-sidebar-foreground group-data-[collapsible=icon]:size-4" })), _jsx("span", { className: "truncate text-sm font-semibold text-sidebar-foreground group-data-[collapsible=icon]:hidden", children: title })] }) }), _jsxs(SidebarContent, { children: [navGroups(nav).map((group, groupIndex) => group.collapsible && group.label !== undefined ? (_jsx(CollapsibleNavGroup, { group: { ...group, label: group.label }, activeTo: activeTo }, `${groupIndex}:${group.label}`)) : (_jsxs(SidebarGroup, { children: [group.label !== undefined && _jsx(SidebarGroupLabel, { children: group.label }), _jsx(SidebarGroupContent, { children: _jsx(NavMenu, { items: group.items, activeTo: activeTo }) })] }, `${groupIndex}:${group.label ?? ''}`))), sidebarExtra] }), _jsxs(SidebarFooter, { children: [version && _jsx(VersionEntry, { version: version }), _jsxs("div", { className: "flex items-center justify-between gap-2 px-2 group-data-[collapsible=icon]:justify-center group-data-[collapsible=icon]:px-0", children: [_jsx("span", { className: "truncate type-caption text-sidebar-foreground/70 group-data-[collapsible=icon]:hidden", children: user.name }), _jsx(Button, { variant: "ghost", size: "icon-sm", "aria-label": "Log out", onClick: () => {
                                                         setIsLoggingOut(true);
                                                         // A failed request still ends the session on screen
                                                         // (AuthProvider), so this stays a deliberate logout: a

package/dist/components/app/foundation-providers.js

@@ -1,20 +1,24 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { QueryClientProvider } from '@tanstack/react-query';
-import { useState } from 'react';
+import { useEffect, useState } from 'react';
 import { createQueryClient } from '../../api/query-client.js';
 import { AuthProvider } from '../../auth/use-auth.js';
 import { MockModeBanner } from './mock-mode-banner.js';
 import { ThemeProvider } from '../theme-provider.js';
 import { ErrorReportingProvider } from '../../error-reporting/error-reporting-provider.js';
 import { resolveErrorReporting } from '../../error-reporting/reporter.js';
+import { browserStaleChunkReload } from '../../lib/stale-chunk-reload.js';
 // Everything an app's root needs around its router, in the order that
 // works: the theme outermost, the mock-mode banner above the router so it
 // shows on every route (/login included), and AuthProvider inside
 // QueryClientProvider because it queries /auth/me through TanStack Query.
 // An app's DataEnvironmentBanner goes first among the children, before its
 // router: it queries too, and shows on every route like the mock banner.
+// It also reloads the page once when a lazy chunk is gone after a deploy
+// (lib/stale-chunk-reload.ts), so no app adds its own listener.
 export function FoundationProviders({ mockMode, queryClient, errorReporting, children, }) {
     const [client] = useState(() => queryClient ?? createQueryClient());
     const reporting = resolveErrorReporting(errorReporting);
+    useEffect(() => browserStaleChunkReload().install(window), []);
     return (_jsxs(ThemeProvider, { attribute: "class", defaultTheme: "system", enableSystem: true, children: [_jsx(MockModeBanner, { active: mockMode }), _jsx(QueryClientProvider, { client: client, children: _jsx(AuthProvider, { children: reporting ? _jsx(ErrorReportingProvider, { options: reporting, children: children }) : children }) })] }));
 }

package/dist/components/app/icon-component.d.ts

@@ -0,0 +1,12 @@
+import type { ComponentType } from 'react';
+/**
+ * Anything drawn like a Lucide icon: sized by a `size-*` class, coloured
+ * through `currentColor` or its own fills, and hidden from screen readers
+ * by `aria-hidden` (which it should pass to its `<svg>`). Every
+ * `LucideIcon` is one, and so is an app's own mark (a brand logo from
+ * Simple Icons' paths, say), so a slot typed with it takes either.
+ */
+export type IconComponent = ComponentType<{
+    className?: string;
+    'aria-hidden'?: boolean | 'true' | 'false';
+}>;

package/dist/components/app/icon-component.js

@@ -0,0 +1 @@
+export {};

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;