@tristan2828/ui-foundation 4.3.1 → 4.4.0

package/conventions/docs/cell-patterns.md

@@ -656,8 +656,9 @@ A value on the record's view that turns into **the form's own control**
 where it's shown, and saves when you leave it: a title, a status, a
 price, notes, a list of linked records. Widget's view is the reference
 (`src/routes/widgets/widget-view.tsx`): Name (the title), Status (its
-header badge), Price, Description (rich text) and Extra Categories, with
-the controls in `widget-fields.tsx`, the same ones the form uses.
+header badge), Price, Description (rich text that autosaves) and Extra
+Categories, with the controls in `widget-fields.tsx`, the same ones the
+form uses.
 
 The rule behind every part of it: **nothing typed is ever lost.**
 
@@ -684,7 +685,7 @@ Save button, no Undo:
 | Kind (`editInPlace({ kind })`) | Saves on | Esc |
 |---|---|---|
 | `text`: one line | Enter, or leaving it | puts the saved value back |
-| `long-text`: notes, rich text for Markdown | Ctrl/Cmd+Enter, or leaving it (Enter is a new line) | the same |
+| `long-text`: notes, rich text for Markdown | Ctrl/Cmd+Enter, or leaving it (Enter is a new line); with `autosave`, also a pause in typing | the same; with `autosave`, saves what's left and closes |
 | `choice`: a select, a switch, a single reference | the pick (its list opens with the field, non-modal) | closes the list with nothing picked: gives up |
 | `multi`: a multi reference | leaving it, or Ctrl/Cmd+Enter (Enter picks) | closes the list first; Esc again gives up |
 
@@ -713,6 +714,53 @@ message (a 500, no answer). The control is `aria-invalid` and described
 by the reason. Nothing reverts on its own, and there's no toast. Leaving
 again retries; Esc gives up.
 
+**Long text that saves itself (`autosave: true`)**, Notion-style, so
+nobody has to click away to save notes. Opt in per field:
+`editInPlace({ kind: 'long-text', autosave: true, ... })`.
+
+- It saves about a second after typing stops, without leaving the field,
+  and at once on leaving it (a click or Tab elsewhere, Ctrl/Cmd+Enter,
+  opening another value, a link off the page).
+- **Never read-only while it saves.** Typing carries on during a save;
+  the next save waits for the one in flight and sends whatever the text
+  is by then, so saves never cross and the latest always wins.
+- Under the text, a quiet line in the muted caption tone
+  (`role="status"`): "Saving…" with a spinner while a save is in flight,
+  "Saved" with a check once nothing typed is waiting. No toast.
+- **Refused:** exactly what was typed stays, with the reason under it, as
+  above. Typing again retries after the pause; a refused draft is never
+  re-sent on its own.
+- **Esc saves what's left and closes.** Nothing reverts: what was saved a
+  second ago stays saved, so "give up" would only drop the last second.
+- Rich text that can't save without rewriting what the person didn't edit
+  (`RichTextEditor`'s `onProblem`) saves nothing; its message shows after
+  the pause, and the next good edit saves.
+- **Leaving the page** with a save still to come saves it first and goes
+  on; "Discard your changes?" shows only if that save is refused. Closing
+  the tab can't wait: it starts the save and the browser asks. Hiding the
+  page (another tab, a phone's home screen) saves too.
+
+**Always editable (`alwaysEditable: true`, implies `autosave`)**: the
+notes are the editor itself, shown at rest, with no pencil and no click
+to open, and it never closes. Ctrl/Cmd+Enter or Esc saves now and leaves
+the caret where it is. It sits beside the one open value rather than
+being it: opening another value leaves it alone. Don't give its control
+`autoFocus`. The cost: at rest the page shows the editor, not the read
+view, so a link in the notes is edited there, not followed, and the
+editor loads on every visit. Use it where the notes are what the page is
+for; elsewhere `autosave` alone keeps the read view at rest.
+
+```tsx
+description: editInPlace({
+  kind: 'long-text',
+  autosave: true,                // or alwaysEditable: true, with no autoFocus on the control
+  value: widget.description,
+  schema: widgetFormSchema.shape.description,
+  save: (description) => editField.mutateAsync({ description }),
+  control: (props) => <WidgetDescriptionEditor {...} />,
+}),
+```
+
 **Leaving the page** (a link, Back) while a value holds unsaved text asks
 "Discard your changes?" first (Keep editing / Discard); closing the tab
 asks through the browser. A link press doesn't save the field on its

package/dist/components/app/data-table.js

@@ -148,7 +148,7 @@ export function DataTable({ columns, data, total, page, pageSize, onPageChange,
     // a time, with the leave-page prompt while one is open, the same rules
     // as a record's view.
     const [store] = useState(() => new EditInPlaceStore());
-    const openField = useSyncExternalStore(store.subscribe, () => store.open, () => store.open);
+    const editing = useSyncExternalStore(store.subscribe, () => store.editing, () => store.editing);
     const pageCount = Math.max(1, Math.ceil(total / pageSize));
     // TanStack treats a column missing from this map as visible, so every
     // column gets an entry once a list is given.
@@ -229,5 +229,5 @@ export function DataTable({ columns, data, total, page, pageSize, onPageChange,
                                     }) }, headerGroup.id))) }), _jsx(TableBody, { children: table.getRowModel().rows.map((row) => (_jsx(TableRow, { className: cn(pinFirstColumn && ROW_GROUP_CLASS), children: row.getVisibleCells().map((cell, index) => (_jsx(TableCell, { className: cn(pinFirstColumn && index === 0 && PINNED_COLUMN_CLASS, pinLastColumn &&
                                             index === row.getVisibleCells().length - 1 &&
                                             PINNED_LAST_COLUMN_CLASS, cell.column.columnDef.meta?.align === 'center' && 'text-center'), children: pinFirstColumn && index === 0 ? (_jsx("div", { className: PINNED_FIRST_CONTENT_CLASS, children: flexRender(cell.column.columnDef.cell, cell.getContext()) })) : (flexRender(cell.column.columnDef.cell, cell.getContext())) }, cell.id))) }, row.id))) })] }), pinFirstColumn && isOverflowing && (_jsx("div", { ref: barRef, "aria-hidden": "true", tabIndex: -1, "data-slot": "bottom-scrollbar", className: "sticky bottom-0 z-20 h-4 overflow-x-auto border-t border-border bg-background", children: _jsx("div", { style: { width: scrollWidth, height: 1 } }) })), _jsxs("div", { className: "flex items-center justify-between", children: [_jsxs("p", { className: "type-body text-muted-foreground", children: [total === 0 ? 0 : (page - 1) * pageSize + 1, '–', Math.min(page * pageSize, total), " of ", total] }), _jsxs("div", { className: "flex items-center gap-2", children: [_jsx(Button, { variant: "outline", size: "icon-sm", "aria-label": "Previous page", disabled: page <= 1, onClick: () => onPageChange(page - 1), children: _jsx(ChevronLeftIcon, {}) }), _jsxs("span", { className: "type-body text-muted-foreground", children: ["Page ", page, " of ", pageCount] }), _jsx(Button, { variant: "outline", size: "icon-sm", "aria-label": "Next page", disabled: page >= pageCount, onClick: () => onPageChange(page + 1), children: _jsx(ChevronRightIcon, {}) })] })] })] }))] }));
-    return (_jsxs(EditInPlaceContext.Provider, { value: store, children: [openField !== null && _jsx(LeaveGuard, { store: store }), width === 'content' ? _jsx("div", { className: "@container/data-table", children: content }) : content] }));
+    return (_jsxs(EditInPlaceContext.Provider, { value: store, children: [editing && _jsx(LeaveGuard, { store: store }), width === 'content' ? _jsx("div", { className: "@container/data-table", children: content }) : content] }));
 }

package/dist/components/app/edit-in-place-store.d.ts

@@ -21,6 +21,10 @@ export type EditFieldConfig = {
     save: (value: unknown) => Promise<unknown>;
     /** Whether the draft is still the saved value. Defaults to comparing as JSON. */
     isEqual?: (a: unknown, b: unknown) => boolean;
+    /** Saves on its own a pause after each change, staying editable while it saves. */
+    autosave?: boolean;
+    /** Always open: the control is the value, with no click to open. Autosaves. */
+    alwaysEditable?: boolean;
 };
 export type EditFieldState = {
     status: 'closed';
@@ -35,6 +39,19 @@ export type OpenFieldState = {
     error: string | null;
     /** A problem the control reports itself (rich text that can't save as it stands). */
     problem: string | null;
+    /**
+     * An autosaving field's save: in flight (the control stays editable),
+     * or done with nothing typed since. Absent otherwise.
+     */
+    autosave?: 'saving' | 'saved';
+    /** Counts the times an always-editable field started over from a value saved elsewhere (`refresh`). */
+    revision?: number;
+};
+/** How long typing has to stop before an autosaving field saves. */
+export declare const AUTOSAVE_DELAY_MS = 1000;
+export type EditInPlaceStoreOptions = {
+    /** The pause before an autosave, in ms. Defaults to AUTOSAVE_DELAY_MS. */
+    autosaveDelay?: number;
 };
 /** Why a save failed, in words to show beside what was being saved. */
 export declare function messageOf(error: unknown): string;
@@ -44,22 +61,50 @@ export declare class EditInPlaceStore {
     private saving;
     private openKey;
     private listeners;
+    private readonly autosaveDelay;
+    private timers;
+    private autosaving;
+    private queued;
+    private always;
+    private holds;
+    constructor(options?: EditInPlaceStoreOptions);
     subscribe: (listener: () => void) => () => void;
     private emit;
     private set;
     /** A field joins the view. `config` is read fresh each time it's needed. */
     register(key: string, config: () => EditFieldConfig): () => void;
     state(key: string): EditFieldState;
-    /** The field that's open, if any. */
+    /** The field that's open, if any. An always-editable one never counts. */
     get open(): string | null;
+    /**
+     * Whether anything is being edited: a field open, one that always is, or
+     * a move off the page waiting for its saves (`hold`).
+     */
+    get editing(): boolean;
+    /**
+     * Keeps `editing` true until released: the leave prompt, saving on the
+     * way out, stays mounted (and its blocked move with it) even when that
+     * save closes the field.
+     */
+    hold(): () => void;
     /** Whether leaving the page now would lose something: a draft that isn't saved. */
     get dirty(): boolean;
+    /** Whether everything unsaved saves on its own, so leaving can save it first rather than ask. */
+    get savesOnLeave(): boolean;
+    private unsaved;
+    private isEqual;
+    private autosaves;
     /**
      * Opens a field. The open one, if another, is saved first: if that
      * fails it stays open and this one doesn't, and this returns false.
+     * An always-editable field is already open.
      */
     start(key: string): Promise<boolean>;
-    /** The control's value changed. Ignored while saving: the field is read-only then. */
+    /**
+     * The control's value changed. Ignored while saving: the field is
+     * read-only then. An autosaving field takes it even mid-save, and saves
+     * once typing pauses.
+     */
     change(key: string, draft: unknown): void;
     /** The control can't produce a value to save as it stands (`null` once it can). */
     report(key: string, problem: string | null): void;
@@ -67,12 +112,38 @@ export declare class EditInPlaceStore {
      * Saves the field (leaving it, Enter, a choice picked). Resolves true
      * once it's closed (saved, or unchanged), false if it stays open (the
      * schema refused it, or the save failed). `draft`, when given, is the
-     * value to save (a choice saves the moment it's picked).
+     * value to save (a choice saves the moment it's picked). An autosaving
+     * field saves what's left at once; an always-editable one stays open,
+     * and resolves true once what's on screen is saved.
      */
     commit(key: string, draft?: unknown): Promise<boolean>;
-    /** Esc: closes and shows the saved value again. Not while a save is in flight. */
+    private commitAutosaved;
+    private schedule;
+    private clearTimer;
+    /**
+     * Saves an autosaving field's latest draft now. With a save in flight,
+     * it waits behind it (one save queued, however many changes), then
+     * sends whatever the draft is by then. Resolves true once the draft it
+     * sent is saved (or there was nothing to send).
+     */
+    private flush;
+    /**
+     * Saves every autosaving field that holds something unsaved, now
+     * (leaving the page). Resolves true once nothing unsaved is left.
+     */
+    saveAll(): Promise<boolean>;
+    /**
+     * An always-editable field shows the saved value again when it changed
+     * elsewhere (another tab, the form), but only while nothing of its own
+     * is unsaved or saving. True when it did: the control starts over.
+     */
+    refresh(key: string): boolean;
+    /**
+     * Esc: closes and shows the saved value again. Not while a save is in
+     * flight, and never for an always-editable field.
+     */
     cancel(key: string): void;
-    /** Leaving the page anyway: whatever is open is dropped. */
+    /** Leaving the page anyway: whatever is open is dropped, and nothing waiting to autosave is sent. */
     discard(): void;
 }
 export {};

package/dist/components/app/edit-in-place-store.js

@@ -1,4 +1,6 @@
 import { refusalReason } from '../../hooks/use-record-update.js';
+/** How long typing has to stop before an autosaving field saves. */
+export const AUTOSAVE_DELAY_MS = 1000;
 const CLOSED = { status: 'closed' };
 const sameAsJson = (a, b) => JSON.stringify(a) === JSON.stringify(b);
 /** Why a save failed, in words to show beside what was being saved. */
@@ -15,6 +17,18 @@ export class EditInPlaceStore {
     saving = new Map();
     openKey = null;
     listeners = new Set();
+    // Autosaving fields: the pause before each save, the save in flight,
+    // the one waiting behind it, and the fields that are always open.
+    autosaveDelay;
+    timers = new Map();
+    autosaving = new Map();
+    queued = new Map();
+    always = new Set();
+    // Leaving the page, waiting for its saves: the leave prompt stays.
+    holds = 0;
+    constructor(options = {}) {
+        this.autosaveDelay = options.autosaveDelay ?? AUTOSAVE_DELAY_MS;
+    }
     subscribe = (listener) => {
         this.listeners.add(listener);
         return () => {
@@ -34,38 +48,89 @@ export class EditInPlaceStore {
     /** A field joins the view. `config` is read fresh each time it's needed. */
     register(key, config) {
         this.configs.set(key, config);
+        const { alwaysEditable, value } = config();
+        if (alwaysEditable) {
+            this.always.add(key);
+            this.set(key, { status: 'open', draft: value, initial: value, error: null, problem: null });
+        }
         return () => {
+            // A save still waiting for the pause goes now: the field is leaving,
+            // not giving up what was typed.
+            if (this.timers.has(key))
+                void this.flush(key);
             this.configs.delete(key);
             this.states.delete(key);
             if (this.openKey === key)
                 this.openKey = null;
+            if (this.always.delete(key))
+                this.emit();
         };
     }
     state(key) {
         return this.states.get(key) ?? CLOSED;
     }
-    /** The field that's open, if any. */
+    /** The field that's open, if any. An always-editable one never counts. */
     get open() {
         return this.openKey;
     }
+    /**
+     * Whether anything is being edited: a field open, one that always is, or
+     * a move off the page waiting for its saves (`hold`).
+     */
+    get editing() {
+        return this.openKey !== null || this.always.size > 0 || this.holds > 0;
+    }
+    /**
+     * Keeps `editing` true until released: the leave prompt, saving on the
+     * way out, stays mounted (and its blocked move with it) even when that
+     * save closes the field.
+     */
+    hold() {
+        this.holds += 1;
+        let released = false;
+        return () => {
+            if (released)
+                return;
+            released = true;
+            this.holds -= 1;
+            this.emit();
+        };
+    }
     /** Whether leaving the page now would lose something: a draft that isn't saved. */
     get dirty() {
-        if (this.openKey === null)
-            return false;
-        const state = this.state(this.openKey);
-        if (state.status === 'closed')
-            return false;
-        if (state.status === 'saving' || state.error !== null)
-            return true;
-        const isEqual = this.configs.get(this.openKey)?.().isEqual ?? sameAsJson;
-        return !isEqual(state.draft, state.initial);
+        return this.unsaved().length > 0;
+    }
+    /** Whether everything unsaved saves on its own, so leaving can save it first rather than ask. */
+    get savesOnLeave() {
+        return this.unsaved().every((key) => this.autosaves(key));
+    }
+    unsaved() {
+        const keys = new Set(this.always);
+        if (this.openKey !== null)
+            keys.add(this.openKey);
+        return [...keys].filter((key) => {
+            const state = this.state(key);
+            if (state.status === 'closed')
+                return false;
+            if (state.status === 'saving' || this.autosaving.has(key) || state.error !== null)
+                return true;
+            return !this.isEqual(key)(state.draft, state.initial);
+        });
+    }
+    isEqual(key) {
+        return this.configs.get(key)?.().isEqual ?? sameAsJson;
+    }
+    autosaves(key) {
+        const config = this.configs.get(key)?.();
+        return Boolean(config?.autosave || config?.alwaysEditable);
     }
     /**
      * Opens a field. The open one, if another, is saved first: if that
      * fails it stays open and this one doesn't, and this returns false.
+     * An always-editable field is already open.
      */
     async start(key) {
-        if (this.openKey === key)
+        if (this.openKey === key || this.always.has(key))
             return true;
         if (this.openKey !== null) {
             const closed = await this.commit(this.openKey);
@@ -82,12 +147,21 @@ export class EditInPlaceStore {
         this.set(key, { status: 'open', draft: config.value, initial: config.value, error: null, problem: null });
         return true;
     }
-    /** The control's value changed. Ignored while saving: the field is read-only then. */
+    /**
+     * The control's value changed. Ignored while saving: the field is
+     * read-only then. An autosaving field takes it even mid-save, and saves
+     * once typing pauses.
+     */
     change(key, draft) {
         const state = this.state(key);
         if (state.status !== 'open')
             return;
-        this.set(key, { ...state, draft });
+        if (!this.autosaves(key)) {
+            this.set(key, { ...state, draft });
+            return;
+        }
+        this.set(key, { ...state, draft, autosave: this.autosaving.has(key) ? 'saving' : undefined });
+        this.schedule(key);
     }
     /** The control can't produce a value to save as it stands (`null` once it can). */
     report(key, problem) {
@@ -95,14 +169,22 @@ export class EditInPlaceStore {
         if (state.status === 'closed' || state.problem === problem)
             return;
         this.set(key, { ...state, problem });
+        // Autosaving: after the pause, the problem shows (nothing is saved),
+        // or, once it's gone, the latest draft saves.
+        if (state.status === 'open' && this.autosaves(key))
+            this.schedule(key);
     }
     /**
      * Saves the field (leaving it, Enter, a choice picked). Resolves true
      * once it's closed (saved, or unchanged), false if it stays open (the
      * schema refused it, or the save failed). `draft`, when given, is the
-     * value to save (a choice saves the moment it's picked).
+     * value to save (a choice saves the moment it's picked). An autosaving
+     * field saves what's left at once; an always-editable one stays open,
+     * and resolves true once what's on screen is saved.
      */
     commit(key, draft) {
+        if (this.autosaves(key))
+            return this.commitAutosaved(key, draft);
         const inFlight = this.saving.get(key);
         if (inFlight)
             return inFlight;
@@ -145,16 +227,152 @@ export class EditInPlaceStore {
         this.saving.set(key, save);
         return save;
     }
-    /** Esc: closes and shows the saved value again. Not while a save is in flight. */
-    cancel(key) {
+    async commitAutosaved(key, draft) {
+        if (this.state(key).status === 'closed')
+            return true;
+        if (draft !== undefined)
+            this.change(key, draft);
+        const saved = await this.flush(key);
+        const now = this.state(key);
+        if (now.status === 'closed')
+            return true;
+        // Typed again while that save was in flight: its own save follows.
+        if (!saved || !this.isEqual(key)(now.draft, now.initial))
+            return false;
+        if (!this.always.has(key))
+            this.set(key, CLOSED);
+        return true;
+    }
+    schedule(key) {
+        this.clearTimer(key);
+        this.timers.set(key, setTimeout(() => {
+            this.timers.delete(key);
+            void this.flush(key);
+        }, this.autosaveDelay));
+    }
+    clearTimer(key) {
+        clearTimeout(this.timers.get(key));
+        this.timers.delete(key);
+    }
+    /**
+     * Saves an autosaving field's latest draft now. With a save in flight,
+     * it waits behind it (one save queued, however many changes), then
+     * sends whatever the draft is by then. Resolves true once the draft it
+     * sent is saved (or there was nothing to send).
+     */
+    flush(key) {
+        this.clearTimer(key);
+        const inFlight = this.autosaving.get(key);
+        if (inFlight) {
+            let next = this.queued.get(key);
+            if (!next) {
+                next = inFlight.promise.then((saved) => {
+                    this.queued.delete(key);
+                    // A failed save isn't sent again as it was: only something new is.
+                    const now = this.state(key);
+                    if (!saved && now.status !== 'closed' && this.isEqual(key)(now.draft, inFlight.draft))
+                        return false;
+                    return this.flush(key);
+                });
+                this.queued.set(key, next);
+            }
+            return next;
+        }
         const state = this.state(key);
         if (state.status !== 'open')
+            return Promise.resolve(state.status === 'closed');
+        const config = this.configs.get(key)?.();
+        if (!config)
+            return Promise.resolve(false);
+        if (state.problem) {
+            this.set(key, { ...state, error: state.problem });
+            return Promise.resolve(false);
+        }
+        const isEqual = config.isEqual ?? sameAsJson;
+        if (isEqual(state.draft, state.initial)) {
+            if (state.error !== null)
+                this.set(key, { ...state, error: null });
+            return Promise.resolve(true);
+        }
+        const parsed = config.schema ? config.schema.safeParse(state.draft) : { success: true, data: state.draft };
+        if (!parsed.success) {
+            this.set(key, { ...state, error: parsed.error.issues[0]?.message ?? 'Check this value.' });
+            return Promise.resolve(false);
+        }
+        const sent = state.draft;
+        this.set(key, { ...state, error: null, autosave: 'saving' });
+        const promise = config
+            .save(parsed.data)
+            .then(() => {
+            const now = this.state(key);
+            if (now.status === 'open') {
+                const status = isEqual(now.draft, sent) ? 'saved' : this.queued.has(key) ? 'saving' : undefined;
+                this.set(key, { ...now, initial: sent, error: null, autosave: status });
+            }
+            return true;
+        }, (error) => {
+            const now = this.state(key);
+            if (now.status === 'open')
+                this.set(key, { ...now, error: messageOf(error), autosave: undefined });
+            return false;
+        })
+            .finally(() => this.autosaving.delete(key));
+        this.autosaving.set(key, { promise, draft: sent });
+        return promise;
+    }
+    /**
+     * Saves every autosaving field that holds something unsaved, now
+     * (leaving the page). Resolves true once nothing unsaved is left.
+     */
+    async saveAll() {
+        const keys = this.unsaved().filter((key) => this.autosaves(key));
+        const results = await Promise.all(keys.map((key) => this.flush(key)));
+        return results.every(Boolean) && !this.dirty;
+    }
+    /**
+     * An always-editable field shows the saved value again when it changed
+     * elsewhere (another tab, the form), but only while nothing of its own
+     * is unsaved or saving. True when it did: the control starts over.
+     */
+    refresh(key) {
+        const state = this.state(key);
+        const config = this.configs.get(key)?.();
+        if (!this.always.has(key) || state.status !== 'open' || !config)
+            return false;
+        if (this.timers.has(key) || this.autosaving.has(key) || state.error !== null)
+            return false;
+        const isEqual = config.isEqual ?? sameAsJson;
+        if (!isEqual(state.draft, state.initial) || isEqual(config.value, state.initial))
+            return false;
+        const revision = (state.revision ?? 0) + 1;
+        this.set(key, { status: 'open', draft: config.value, initial: config.value, error: null, problem: null, revision });
+        return true;
+    }
+    /**
+     * Esc: closes and shows the saved value again. Not while a save is in
+     * flight, and never for an always-editable field.
+     */
+    cancel(key) {
+        const state = this.state(key);
+        if (state.status !== 'open' || this.always.has(key) || this.autosaving.has(key))
             return;
+        this.clearTimer(key);
         this.set(key, CLOSED);
     }
-    /** Leaving the page anyway: whatever is open is dropped. */
+    /** Leaving the page anyway: whatever is open is dropped, and nothing waiting to autosave is sent. */
     discard() {
-        if (this.openKey !== null)
-            this.cancel(this.openKey);
+        for (const key of [...this.timers.keys()])
+            this.clearTimer(key);
+        if (this.openKey !== null) {
+            if (this.autosaving.has(this.openKey))
+                this.set(this.openKey, CLOSED);
+            else
+                this.cancel(this.openKey);
+        }
+        for (const key of this.always) {
+            const state = this.state(key);
+            if (state.status === 'open')
+                this.set(key, { ...state, draft: state.initial, error: null, autosave: undefined });
+        }
     }
 }

package/dist/components/app/edit-in-place.d.ts

@@ -58,6 +58,8 @@ export type EditInPlace = {
     };
     save: (value: unknown) => Promise<unknown>;
     isEqual?: (a: unknown, b: unknown) => boolean;
+    autosave?: boolean;
+    alwaysEditable?: boolean;
 };
 export type EditInPlaceOptions<TDraft, TValue> = {
     kind: EditKind;
@@ -82,6 +84,22 @@ export type EditInPlaceOptions<TDraft, TValue> = {
     save: (value: TValue) => Promise<unknown>;
     /** Whether a draft is still the saved value. Defaults to comparing as JSON. */
     isEqual?: (a: TDraft, b: TDraft) => boolean;
+    /**
+     * Saves on its own, Notion-style, for long text: about a second after
+     * typing stops, and at once on leaving the field or the page. The
+     * control stays editable while it saves ("Saving…", then "Saved"), and
+     * saves never cross: the next waits for the one in flight and sends the
+     * latest draft. Esc saves and closes; nothing reverts. A refusal keeps
+     * the draft and its reason, as without it.
+     */
+    autosave?: boolean;
+    /**
+     * The control is the value: shown at rest, with no click to open (the
+     * notes are the editor). Implies `autosave`. Its control shouldn't take
+     * `autoFocus`. At rest it shows the control, not the read view: a link
+     * in rich text is edited there, not followed.
+     */
+    alwaysEditable?: boolean;
 };
 /** What a list item's fields are given while it's edited: a control's props, plus where the item is. */
 export type EditListItemProps<TItem> = EditControlProps<TItem> & {

package/dist/components/app/editable-value.d.ts

@@ -28,7 +28,12 @@ export declare function EditableField({ label, edit, children, layout, className
  * While a field holds something unsaved, leaving asks first: an in-app
  * link or Back (React Router's blocker, so the app needs a data router),
  * or closing the tab (`beforeunload`). Rendered by EntityView only while
- * a field is open, so a view nobody's editing never blocks anything.
+ * a field is being edited, so a view nobody's editing never blocks anything.
+ *
+ * When everything unsaved autosaves, an in-app move saves it first and
+ * goes on once saved, asking only if that save fails. Closing the tab
+ * can't wait, so it starts the save and asks; hiding the page (another
+ * tab, a phone's home screen) saves too.
  */
 export declare function LeaveGuard({ store }: {
     store: EditInPlaceStore;

package/dist/components/app/editable-value.js

@@ -1,4 +1,4 @@
-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";
 // A value on a record's view that turns into its form control where it's
 // shown, and saves when you leave it (cell-patterns.md "Editable value").
 // EntityView wraps every field, section and title marked `edit`; a header
@@ -11,8 +11,13 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 //   back. Unchanged closes with no request.
 // - Saving: the control stays, read-only, with "Saving…" under it, until
 //   the server agrees. Failed: it stays, with the draft and the reason.
-import { PencilIcon } from 'lucide-react';
-import { useCallback, useContext, useEffect, useId, useLayoutEffect, useRef, useSyncExternalStore } from 'react';
+// - `autosave`: it saves itself a pause after typing stops and stays
+//   editable while it does ("Saving…", then "Saved" under it). Leaving,
+//   Ctrl/Cmd+Enter and Esc save what's left now and close it.
+// - `alwaysEditable`: the control is shown at rest, with no pencil and no
+//   click to open, and never closes. Ctrl/Cmd+Enter and Esc save now.
+import { CheckIcon, PencilIcon } from 'lucide-react';
+import { useCallback, useContext, useEffect, useId, useLayoutEffect, useRef, useState, useSyncExternalStore } from 'react';
 import { useBlocker } from 'react-router';
 import { cn } from 'cn';
 import { Button } from '../ui/button.js';
@@ -20,6 +25,7 @@ import { Dialog, DialogClose, DialogContent, DialogDescription, DialogFooter, Di
 import { FieldError } from '../ui/field.js';
 import { Spinner } from '../ui/spinner.js';
 import { EditInPlaceContext } from './edit-in-place.js';
+import { escapePassedThrough } from './escape-passthrough.js';
 // What a click on the shown value must leave alone: links navigate,
 // buttons and boxes do their own thing (a list item's done box ticks it).
 const INTERACTIVE = 'a[href], button, input, select, textarea, label, [role="button"], [role="link"], [role="checkbox"], [role="switch"]';
@@ -66,10 +72,24 @@ export function EditableField({ label, edit, children, layout = 'block', classNa
     // Set by a keyboard save or Esc: the caret goes back to the edit button.
     const refocus = useRef(false);
     const blurTimer = useRef(undefined);
+    const always = Boolean(edit.alwaysEditable);
+    const autosave = always || Boolean(edit.autosave);
+    // An always-editable control starts over (it's uncontrolled: a rich-text
+    // editor reads its value once) when the value changed elsewhere while
+    // nothing of its own was unsaved and the caret wasn't in it.
+    const refresh = useCallback(() => {
+        if (!container.current?.contains(document.activeElement))
+            store.refresh(key);
+    }, [store, key]);
+    useEffect(() => {
+        if (always)
+            refresh();
+    }, [always, refresh, edit.value]);
     const isOpen = state.status !== 'closed';
     const wasOpen = useRef(false);
     useEffect(() => {
-        if (isOpen && !wasOpen.current) {
+        // Always open: the caret stays wherever the person put it.
+        if (isOpen && !wasOpen.current && !always) {
             for (const selector of FOCUS_ORDER) {
                 const target = container.current?.querySelector(selector);
                 if (target) {
@@ -86,7 +106,7 @@ export function EditableField({ label, edit, children, layout = 'block', classNa
             (editButton.current ?? triggerBox.current?.querySelector('button'))?.focus();
         }
         wasOpen.current = isOpen;
-    }, [isOpen]);
+    }, [isOpen, always]);
     useEffect(() => () => window.clearTimeout(blurTimer.current), []);
     // Whether an Esc is closing a list inside the control. Read on the way
     // down (window, capture): a picker closes its list from a document
@@ -127,20 +147,35 @@ export function EditableField({ label, edit, children, layout = 'block', classNa
             return;
         start();
     };
+    // Always editable: Ctrl/Cmd+Enter or Esc saves now, the caret staying put.
+    const saveNow = () => {
+        window.clearTimeout(blurTimer.current);
+        void store.commit(key);
+    };
     const onKeyDown = (event) => {
         if (state.status !== 'open')
             return;
         if (event.key === 'Escape') {
-            // A list open inside the control closes first; Esc again gives up.
-            if (event.defaultPrevented || escapeClosesList.current)
+            // A list open inside the control closes first; Esc again gives up
+            // (or, autosaving, saves what's left and closes: nothing reverts).
+            if ((event.defaultPrevented && !escapePassedThrough(event.nativeEvent)) || escapeClosesList.current)
                 return;
             event.preventDefault();
-            refocus.current = true;
-            cancel();
+            if (always)
+                saveNow();
+            else if (autosave)
+                commitFromKeyboard();
+            else {
+                refocus.current = true;
+                cancel();
+            }
         }
         else if (event.key === 'Enter' && (event.metaKey || event.ctrlKey)) {
             event.preventDefault();
-            commitFromKeyboard();
+            if (always)
+                saveNow();
+            else
+                commitFromKeyboard();
         }
         else if (event.key === 'Enter' && edit.kind === 'text' && !event.shiftKey && !event.altKey) {
             event.preventDefault();
@@ -149,47 +184,102 @@ export function EditableField({ label, edit, children, layout = 'block', classNa
     };
     // Leaving the field saves it. Focus moving into the control's own list
     // (a portal) still counts as inside: React sends its focus events here.
+    // An autosaving field saves on its way to a link too: leaving the page
+    // then waits for that save rather than asking.
     const onBlur = (event) => {
         window.clearTimeout(blurTimer.current);
-        if (event.relatedTarget?.closest(LEAVING))
+        if (!autosave && event.relatedTarget?.closest(LEAVING))
             return;
         blurTimer.current = window.setTimeout(() => {
-            if (store.state(key).status === 'open')
-                void store.commit(key);
+            if (store.state(key).status !== 'open')
+                return;
+            void store.commit(key).then(() => {
+                if (always)
+                    refresh();
+            });
         }, 0);
     };
     const onFocus = () => window.clearTimeout(blurTimer.current);
-    if (state.status === 'closed') {
+    if (state.status === 'closed' && !always) {
         if (trigger)
             return (_jsx("span", { ref: triggerBox, className: "contents", children: trigger(start) }));
         return (_jsxs("span", { "data-slot": "editable-value", onClick: onShownClick, className: cn('group/editable relative -mx-1.5 cursor-text items-start gap-1 rounded-md px-1.5 transition-colors hover:bg-muted has-[[data-edit]:focus-visible]:bg-muted', layout === 'block' ? 'flex w-full' : 'inline-flex max-w-full align-top', className), children: [_jsx("span", { className: "min-w-0 flex-1", children: children }), _jsx(Button, { ref: editButton, "data-edit": "", type: "button", variant: "ghost", size: "icon-xs", "aria-label": `Edit ${label}`, onClick: start, className: "shrink-0 text-muted-foreground opacity-0 group-hover/editable:opacity-100 focus-visible:opacity-100 pointer-coarse:opacity-100", children: _jsx(PencilIcon, {}) })] }));
     }
-    const saving = state.status === 'saving';
-    return (_jsxs("span", { ref: container, "data-slot": "editable-value", "data-state": saving ? 'saving' : state.error ? 'failed' : 'editing', onKeyDown: onKeyDown, onBlur: onBlur, onFocus: onFocus, className: cn('flex min-w-0 flex-col gap-1.5', layout === 'block' ? 'w-full' : 'w-fit max-w-full', className), children: [_jsx(Control, { render: edit.control, id: controlId, value: state.draft, onChange: (value) => store.change(key, value), commit: commit, cancel: cancel, disabled: saving, invalid: !saving && state.error !== null, label: label, describedBy: describedBy, onProblem: (problem) => store.report(key, problem) }), _jsx("span", { id: describedBy, className: "type-body", children: saving ? (_jsxs("span", { role: "status", className: "inline-flex items-center gap-1.5 type-caption text-muted-foreground", children: [_jsx(Spinner, { "aria-hidden": "true", className: "size-3.5" }), "Saving\u2026"] })) : (state.error && _jsx(FieldError, { className: "type-caption", children: state.error })) })] }));
+    // Always editable, before the store has it (the first render): the saved value.
+    const open = state.status === 'closed' ? { status: 'open', draft: edit.value, error: null, autosave: undefined, revision: 0 } : state;
+    const saving = open.status === 'saving';
+    const autosaving = open.autosave === 'saving';
+    return (_jsxs("span", { ref: container, "data-slot": "editable-value", "data-state": saving || autosaving ? 'saving' : open.error ? 'failed' : 'editing', onKeyDown: onKeyDown, onBlur: onBlur, onFocus: onFocus, className: cn('flex min-w-0 flex-col gap-1.5', layout === 'block' ? 'w-full' : 'w-fit max-w-full', className), children: [_jsx(Control, { render: edit.control, id: controlId, value: open.draft, onChange: (value) => store.change(key, value), commit: commit, cancel: cancel, disabled: saving, invalid: !saving && open.error !== null, label: label, describedBy: describedBy, onProblem: (problem) => store.report(key, problem) }, open.revision ?? 0), _jsx("span", { id: describedBy, className: "type-body", children: autosave ? (_jsxs(_Fragment, { children: [open.error && _jsx(FieldError, { className: "type-caption", children: open.error }), _jsx("span", { role: "status", className: "inline-flex items-center gap-1.5 type-caption text-muted-foreground", children: autosaving ? (_jsxs(_Fragment, { children: [_jsx(Spinner, { "aria-hidden": "true", className: "size-3.5" }), "Saving\u2026"] })) : (open.autosave === 'saved' &&
+                                !open.error && (_jsxs(_Fragment, { children: [_jsx(CheckIcon, { "aria-hidden": "true", className: "size-3.5" }), "Saved"] }))) })] })) : saving ? (_jsxs("span", { role: "status", className: "inline-flex items-center gap-1.5 type-caption text-muted-foreground", children: [_jsx(Spinner, { "aria-hidden": "true", className: "size-3.5" }), "Saving\u2026"] })) : (open.error && _jsx(FieldError, { className: "type-caption", children: open.error })) })] }));
 }
 /**
  * While a field holds something unsaved, leaving asks first: an in-app
  * link or Back (React Router's blocker, so the app needs a data router),
  * or closing the tab (`beforeunload`). Rendered by EntityView only while
- * a field is open, so a view nobody's editing never blocks anything.
+ * a field is being edited, so a view nobody's editing never blocks anything.
+ *
+ * When everything unsaved autosaves, an in-app move saves it first and
+ * goes on once saved, asking only if that save fails. Closing the tab
+ * can't wait, so it starts the save and asks; hiding the page (another
+ * tab, a phone's home screen) saves too.
  */
 export function LeaveGuard({ store }) {
     const dirty = useSyncExternalStore(store.subscribe, () => store.dirty, () => store.dirty);
+    const savesOnLeave = useSyncExternalStore(store.subscribe, () => store.savesOnLeave, () => store.savesOnLeave);
     const blocker = useBlocker(({ currentLocation, nextLocation }) => store.dirty && currentLocation.pathname !== nextLocation.pathname);
+    const [saveFailed, setSaveFailed] = useState(false);
+    const latestBlocker = useRef(blocker);
+    useLayoutEffect(() => {
+        latestBlocker.current = blocker;
+    });
+    useEffect(() => {
+        if (blocker.state !== 'blocked' || !store.savesOnLeave)
+            return;
+        let live = true;
+        // The save may close the field; this prompt (and the move it blocked)
+        // stays until the save is done.
+        const release = store.hold();
+        void store.saveAll().then((saved) => {
+            if (live) {
+                const current = latestBlocker.current;
+                if (saved && current.state === 'blocked')
+                    current.proceed();
+                else if (!saved)
+                    setSaveFailed(true);
+            }
+            release();
+        });
+        return () => {
+            live = false;
+        };
+    }, [blocker.state, store]);
     useEffect(() => {
         if (!dirty)
             return;
         const onBeforeUnload = (event) => {
+            void store.saveAll();
             event.preventDefault();
         };
+        const onVisibilityChange = () => {
+            if (document.visibilityState === 'hidden')
+                void store.saveAll();
+        };
         window.addEventListener('beforeunload', onBeforeUnload);
-        return () => window.removeEventListener('beforeunload', onBeforeUnload);
-    }, [dirty]);
-    return (_jsx(Dialog, { open: blocker.state === 'blocked', onOpenChange: (open) => {
-            if (!open && blocker.state === 'blocked')
+        document.addEventListener('visibilitychange', onVisibilityChange);
+        return () => {
+            window.removeEventListener('beforeunload', onBeforeUnload);
+            document.removeEventListener('visibilitychange', onVisibilityChange);
+        };
+    }, [dirty, store]);
+    return (_jsx(Dialog, { open: blocker.state === 'blocked' && (!savesOnLeave || saveFailed), onOpenChange: (open) => {
+            if (open)
+                return;
+            setSaveFailed(false);
+            if (blocker.state === 'blocked')
                 blocker.reset();
         }, children: _jsxs(DialogContent, { showCloseButton: false, "data-leave-guard": "", children: [_jsxs(DialogHeader, { children: [_jsx(DialogTitle, { children: "Discard your changes?" }), _jsx(DialogDescription, { children: "A field you're editing hasn't been saved. Leaving now loses what you typed." })] }), _jsxs(DialogFooter, { children: [_jsx(DialogClose, { render: _jsx(Button, { variant: "outline" }), children: "Keep editing" }), _jsx(Button, { variant: "destructive", onClick: () => {
                                 store.discard();
+                                setSaveFailed(false);
                                 if (blocker.state === 'blocked')
                                     blocker.proceed();
                             }, children: "Discard" })] })] }) }));

package/dist/components/app/entity-view.js

@@ -25,7 +25,9 @@ import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-run
 // header badge uses it directly. A field not marked renders exactly as
 // before. Edit, in `actions`, stays for everything else. A sub-item list
 // edits in place too (editInPlace's `list` kind, editable-list.tsx): its
-// items added, edited, moved and removed on the page.
+// items added, edited, moved and removed on the page. Long text can
+// autosave as it's typed (`autosave`), and be the editor itself, with no
+// click to open (`alwaysEditable`).
 //
 // Two layouts. `column` (the default): every section in one column capped
 // at max-w-4xl. `rail`, for a record with long content: the page takes the
@@ -136,9 +138,9 @@ function Rail({ label, sections }) {
 }
 export function EntityView({ title, titleEdit, badges, actions, sections, layout = 'column', railLabel, isLoading, error, onRetry, back, }) {
     // Editing in place: one store per view, and the leave-page prompt only
-    // while a field is open.
+    // while a field is open (or one is always editable).
     const [store] = useState(() => new EditInPlaceStore());
-    const openField = useSyncExternalStore(store.subscribe, () => store.open, () => store.open);
+    const editing = useSyncExternalStore(store.subscribe, () => store.editing, () => store.editing);
     if (error?.kind === 'notfound') {
         // A record that doesn't exist and one that belongs to another user are
         // the same plain 404, so this never says which. Retrying can't help.
@@ -150,5 +152,5 @@ export function EntityView({ title, titleEdit, badges, actions, sections, layout
         return _jsx(EntityViewSkeleton, { layout: layout });
     const railSections = sections.filter((section) => section.placement === 'rail');
     const mainSections = sections.filter((section) => section.placement !== 'rail');
-    return (_jsx(EditInPlaceContext.Provider, { value: store, children: _jsxs("div", { className: layout === 'rail' ? RAIL_LAYOUT.page : 'flex max-w-4xl flex-col gap-6', "data-state": "success", "data-layout": layout, children: [openField !== null && _jsx(LeaveGuard, { store: store }), _jsx(BackLink, { back: back }), _jsxs("header", { className: "flex flex-col gap-3 sm:flex-row sm:items-start sm:justify-between", children: [_jsxs("div", { className: "flex min-w-0 flex-1 flex-col gap-2", children: [_jsx("h1", { className: "type-page-title break-words text-foreground", children: titleEdit ? (_jsx(EditableValue, { label: titleEdit.label, edit: titleEdit, layout: "inline", className: "w-full", children: title })) : (title) }), badges && _jsx("div", { className: "flex flex-wrap items-center gap-1.5", children: badges })] }), actions && _jsx("div", { className: "flex shrink-0 flex-wrap items-center gap-2", children: actions })] }), layout === 'rail' ? (_jsxs("div", { className: RAIL_LAYOUT.columns, children: [railSections.length > 0 && (_jsx(Rail, { label: railLabel ?? `${title ?? 'Record'} details`, sections: railSections })), _jsx("div", { className: cn(RAIL_LAYOUT.main, railSections.length === 0 && RAIL_LAYOUT.mainAlone), children: mainSections.map((section) => (_jsx(ViewSection, { section: section }, section.title))) })] })) : (sections.map((section) => _jsx(ViewSection, { section: section }, section.title)))] }) }));
+    return (_jsx(EditInPlaceContext.Provider, { value: store, children: _jsxs("div", { className: layout === 'rail' ? RAIL_LAYOUT.page : 'flex max-w-4xl flex-col gap-6', "data-state": "success", "data-layout": layout, children: [editing && _jsx(LeaveGuard, { store: store }), _jsx(BackLink, { back: back }), _jsxs("header", { className: "flex flex-col gap-3 sm:flex-row sm:items-start sm:justify-between", children: [_jsxs("div", { className: "flex min-w-0 flex-1 flex-col gap-2", children: [_jsx("h1", { className: "type-page-title break-words text-foreground", children: titleEdit ? (_jsx(EditableValue, { label: titleEdit.label, edit: titleEdit, layout: "inline", className: "w-full", children: title })) : (title) }), badges && _jsx("div", { className: "flex flex-wrap items-center gap-1.5", children: badges })] }), actions && _jsx("div", { className: "flex shrink-0 flex-wrap items-center gap-2", children: actions })] }), layout === 'rail' ? (_jsxs("div", { className: RAIL_LAYOUT.columns, children: [railSections.length > 0 && (_jsx(Rail, { label: railLabel ?? `${title ?? 'Record'} details`, sections: railSections })), _jsx("div", { className: cn(RAIL_LAYOUT.main, railSections.length === 0 && RAIL_LAYOUT.mainAlone), children: mainSections.map((section) => (_jsx(ViewSection, { section: section }, section.title))) })] })) : (sections.map((section) => _jsx(ViewSection, { section: section }, section.title)))] }) }));
 }

package/dist/components/app/escape-passthrough.d.ts

@@ -0,0 +1,2 @@
+export declare function passEscapeThrough(event: Event): void;
+export declare function escapePassedThrough(event: Event): boolean;

package/dist/components/app/escape-passthrough.js

@@ -0,0 +1,13 @@
+// An Esc the rich-text editor didn't use. ProseMirror marks every Esc
+// handled (its own keydown calls preventDefault, to stop the browser's
+// default), so a field around the editor can't tell from
+// `defaultPrevented` whether a menu over the text took it. The editor
+// records the ones none of its menus did, and editing in place acts on
+// those (cell-patterns.md "Editable value": Esc gives up, or saves).
+const passedThrough = new WeakSet();
+export function passEscapeThrough(event) {
+    passedThrough.add(event);
+}
+export function escapePassedThrough(event) {
+    return passedThrough.has(event);
+}

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

@@ -55,6 +55,7 @@ import { Field, FieldError, FieldLabel } from '../ui/field.js';
 import { Input } from '../ui/input.js';
 import { Popover, PopoverContent } from '../ui/popover.js';
 import { linkHref } from '../../lib/link-href.js';
+import { passEscapeThrough } from './escape-passthrough.js';
 import { calloutHandler, remarkCalloutNodes } from '../../lib/markdown-callout.js';
 import { MarkdownMergeError, markdownStyle, mergeMarkdown } from '../../lib/markdown-merge.js';
 import { headingClass } from './prose-look.js';
@@ -477,6 +478,10 @@ export default function MilkdownEditor({ id, defaultValue, onChange, onProblem,
                         setDismissed({ from, to });
                         return true;
                     }
+                    // An Esc nothing over the text took: the field's to act on,
+                    // though ProseMirror will mark it handled.
+                    if (event.key === 'Escape')
+                        passEscapeThrough(event);
                     const mod = event.metaKey || event.ctrlKey;
                     if (mod && !event.shiftKey && !event.altKey && event.key.toLowerCase() === 'k') {
                         event.preventDefault();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tristan2828/ui-foundation",
-  "version": "4.3.1",
+  "version": "4.4.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": {