@tristan2828/ui-foundation 3.12.0 → 3.14.0

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

@@ -25,7 +25,8 @@ One or two sentences: what one record is, and who uses the screens.
   - *Demonstrated by the Widget reference* (copied directly): `text` (one
     line), `long text` (say `Markdown` when it's written in Markdown, like
     notes or a write-up: the view renders its headings, lists, tables and
-    links, and it's never a table column), `decimal` (fixed places — say how many),
+    links, the form and editing in place edit it as formatted text, and
+    it's never a table column), `decimal` (fixed places — say how many),
     `date-time`, `email`, `yes/no` (a boolean that is always yes or no:
     say its default and the filter's three labels, e.g. Any stock /
     In stock / Out of stock), `single choice` (list the options, in display
@@ -133,18 +134,29 @@ except the quick actions, if any.
 - "Not set" labels: what an empty optional field reads as on the view
   (`dueDate`: No due date; `checklist`: No items). A field not listed here
   reads "Not set". A `yes/no` is never empty: it reads Yes or No.
-- Quick actions (optional; delete if none): the fields the view changes
-  right where they show, each saved on its own the moment it changes,
-  without the form. Every other value stays read-only. Each one is a
-  `single choice` (picked from a list, usually a badge field), a `yes/no`
-  (a switch), or a sub-records list (its yes/no item field ticked on each
-  item). Only values people change often and can change back as easily.
+- Quick actions (optional; delete if none): the values the view changes
+  with one click, each saved on its own the moment it changes, without
+  the form: a `yes/no` (a switch), or a sub-records list (its yes/no item
+  field ticked on each item). Only values people change often and can
+  change back as easily.
   Say any rule the server enforces on one (it can refuse the change) and
   any side effect (another field the server changes with it), so each
   gets a test; the view always shows the record the server returns.
 
-  Quick actions: status (the server refuses Finished while the checklist
-  has open items), checklist
+  Quick actions: checklist
+
+- Edit in place (optional; delete if none): the fields that turn into
+  their form control where the view shows them and save when you leave
+  them (cell pattern 18): the title, a badge field, a field row, a long
+  text. Single values only: text, long text, a single choice, an integer
+  or a rating, a yes/no, a single or multi reference. Never a computed
+  field or a sub-records list (those stay on the form). Every value not
+  named here, or under Quick actions, stays read-only. Say any rule the
+  server enforces on one (its refusal shows under the field) and any
+  side effect:
+
+  Edit in place: title, status (the server refuses Finished while the
+  checklist has open items), dueDate, notes
 
 ## Screens and access
 

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

@@ -0,0 +1,76 @@
+type SafeParse = (value: unknown) => {
+    success: true;
+    data: unknown;
+} | {
+    success: false;
+    error: {
+        issues: readonly {
+            message: string;
+        }[];
+    };
+};
+/** What a field needs to edit in place, read fresh on every use. */
+export type EditFieldConfig = {
+    /** The saved value, as the control holds it (the form's value for the field). */
+    value: unknown;
+    /** The form's zod schema for the field: a value it rejects never leaves the browser. */
+    schema?: {
+        safeParse: SafeParse;
+    };
+    /** Sends the value (the schema's output). Resolves once saved; rejects with an AppError. */
+    save: (value: unknown) => Promise<unknown>;
+    /** Whether the draft is still the saved value. Defaults to comparing as JSON. */
+    isEqual?: (a: unknown, b: unknown) => boolean;
+};
+export type EditFieldState = {
+    status: 'closed';
+} | OpenFieldState;
+export type OpenFieldState = {
+    status: 'open' | 'saving';
+    /** What the control shows: exactly what was typed. */
+    draft: unknown;
+    /** The saved value when the field opened. */
+    initial: unknown;
+    /** Why it can't save (the schema's or the server's words), shown under it. */
+    error: string | null;
+    /** A problem the control reports itself (rich text that can't save as it stands). */
+    problem: string | null;
+};
+export declare class EditInPlaceStore {
+    private configs;
+    private states;
+    private saving;
+    private openKey;
+    private listeners;
+    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. */
+    get open(): string | null;
+    /** Whether leaving the page now would lose something: a draft that isn't saved. */
+    get dirty(): boolean;
+    /**
+     * 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.
+     */
+    start(key: string): Promise<boolean>;
+    /** The control's value changed. Ignored while saving: the field is read-only then. */
+    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;
+    /**
+     * 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).
+     */
+    commit(key: string, draft?: unknown): Promise<boolean>;
+    /** Esc: closes and shows the saved value again. Not while a save is in flight. */
+    cancel(key: string): void;
+    /** Leaving the page anyway: whatever is open is dropped. */
+    discard(): void;
+}
+export {};

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

@@ -0,0 +1,159 @@
+import { refusalReason } from '../../hooks/use-record-update.js';
+const CLOSED = { status: 'closed' };
+const sameAsJson = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+function messageOf(error) {
+    if (error && typeof error === 'object' && 'kind' in error)
+        return refusalReason(error);
+    if (error instanceof Error)
+        return error.message;
+    return 'The save failed. Try again.';
+}
+export class EditInPlaceStore {
+    configs = new Map();
+    states = new Map();
+    saving = new Map();
+    openKey = null;
+    listeners = new Set();
+    subscribe = (listener) => {
+        this.listeners.add(listener);
+        return () => {
+            this.listeners.delete(listener);
+        };
+    };
+    emit() {
+        for (const listener of this.listeners)
+            listener();
+    }
+    set(key, state) {
+        this.states.set(key, state);
+        if (state.status === 'closed' && this.openKey === key)
+            this.openKey = null;
+        this.emit();
+    }
+    /** A field joins the view. `config` is read fresh each time it's needed. */
+    register(key, config) {
+        this.configs.set(key, config);
+        return () => {
+            this.configs.delete(key);
+            this.states.delete(key);
+            if (this.openKey === key)
+                this.openKey = null;
+        };
+    }
+    state(key) {
+        return this.states.get(key) ?? CLOSED;
+    }
+    /** The field that's open, if any. */
+    get open() {
+        return this.openKey;
+    }
+    /** 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);
+    }
+    /**
+     * 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.
+     */
+    async start(key) {
+        if (this.openKey === key)
+            return true;
+        if (this.openKey !== null) {
+            const closed = await this.commit(this.openKey);
+            if (!closed)
+                return false;
+            // Another field may have opened while that save was in flight.
+            if (this.openKey !== null && this.openKey !== key)
+                return false;
+        }
+        const config = this.configs.get(key)?.();
+        if (!config)
+            return false;
+        this.openKey = key;
+        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. */
+    change(key, draft) {
+        const state = this.state(key);
+        if (state.status !== 'open')
+            return;
+        this.set(key, { ...state, draft });
+    }
+    /** The control can't produce a value to save as it stands (`null` once it can). */
+    report(key, problem) {
+        const state = this.state(key);
+        if (state.status === 'closed' || state.problem === problem)
+            return;
+        this.set(key, { ...state, problem });
+    }
+    /**
+     * 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).
+     */
+    commit(key, draft) {
+        const inFlight = this.saving.get(key);
+        if (inFlight)
+            return inFlight;
+        let state = this.state(key);
+        if (state.status === 'closed')
+            return Promise.resolve(true);
+        if (draft !== undefined && state.status === 'open') {
+            state = { ...state, draft };
+            this.set(key, state);
+        }
+        const open = state;
+        const config = this.configs.get(key)?.();
+        if (!config)
+            return Promise.resolve(false);
+        if (open.problem) {
+            this.set(key, { ...open, error: open.problem });
+            return Promise.resolve(false);
+        }
+        const isEqual = config.isEqual ?? sameAsJson;
+        if (isEqual(open.draft, open.initial)) {
+            this.set(key, CLOSED);
+            return Promise.resolve(true);
+        }
+        const parsed = config.schema ? config.schema.safeParse(open.draft) : { success: true, data: open.draft };
+        if (!parsed.success) {
+            this.set(key, { ...open, error: parsed.error.issues[0]?.message ?? 'Check this value.' });
+            return Promise.resolve(false);
+        }
+        this.set(key, { ...open, status: 'saving', error: null });
+        const save = config
+            .save(parsed.data)
+            .then(() => {
+            this.set(key, CLOSED);
+            return true;
+        }, (error) => {
+            this.set(key, { ...open, status: 'open', error: messageOf(error) });
+            return false;
+        })
+            .finally(() => this.saving.delete(key));
+        this.saving.set(key, save);
+        return save;
+    }
+    /** Esc: closes and shows the saved value again. Not while a save is in flight. */
+    cancel(key) {
+        const state = this.state(key);
+        if (state.status !== 'open')
+            return;
+        this.set(key, CLOSED);
+    }
+    /** Leaving the page anyway: whatever is open is dropped. */
+    discard() {
+        if (this.openKey !== null)
+            this.cancel(this.openKey);
+    }
+}

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

@@ -0,0 +1,88 @@
+import { type ReactNode } from 'react';
+import type { EditInPlaceStore } from './edit-in-place-store.js';
+/** What an editable value's control is given. Spread what applies onto the form's own control. */
+export type EditControlProps<TDraft> = {
+    /** The control's id. */
+    id: string;
+    /** The draft: exactly what's been typed or picked. */
+    value: TDraft;
+    onChange: (value: TDraft) => void;
+    /**
+     * Save now. A choice calls it with the value picked (`commit(value)`):
+     * a choice saves the moment it's picked.
+     */
+    commit: (value?: TDraft) => void;
+    /** Close without saving: a list closed with nothing picked. */
+    cancel: () => void;
+    /** The save is in flight: show the draft, don't let it change. */
+    disabled: boolean;
+    /** The draft was refused; its reason is under it (`aria-describedby`). */
+    invalid: boolean;
+    /** The field's label: the control's accessible name. */
+    label: string;
+    /** The id of the line under the control (Saving…, or why it can't save). */
+    describedBy: string;
+    /** For a control that can't always produce a value to save (RichTextEditor's `onProblem`). */
+    onProblem: (message: string | null) => void;
+};
+/**
+ * How the value saves, which follows from its control:
+ * - `text`: one line. Enter saves (as does leaving it).
+ * - `long-text`: Ctrl/Cmd+Enter saves; Enter is a new line.
+ * - `choice`: one pick (a select, a switch, a single reference). Saves the
+ *   moment it's picked; its list opens with the field.
+ * - `multi`: several picks (a multi reference). Saves on leaving it, or
+ *   Ctrl/Cmd+Enter; Enter picks.
+ * Leaving the field saves every kind; Esc gives up.
+ */
+export type EditKind = 'text' | 'long-text' | 'choice' | 'multi';
+type SafeParseResult<TValue> = {
+    success: true;
+    data: TValue;
+} | {
+    success: false;
+    error: {
+        issues: readonly {
+            message: string;
+        }[];
+    };
+};
+/** A field marked editable. Make one with `editInPlace({...})`. */
+export type EditInPlace = {
+    kind: EditKind;
+    value: unknown;
+    control: (props: EditControlProps<unknown>) => ReactNode;
+    schema?: {
+        safeParse: (value: unknown) => SafeParseResult<unknown>;
+    };
+    save: (value: unknown) => Promise<unknown>;
+    isEqual?: (a: unknown, b: unknown) => boolean;
+};
+export type EditInPlaceOptions<TDraft, TValue> = {
+    kind: EditKind;
+    /** The saved value as the control holds it: what the form's control would start from. */
+    value: TDraft;
+    /** The form's own control for this field (one control per field, shared with the form). */
+    control: (props: EditControlProps<TDraft>) => ReactNode;
+    /**
+     * The form's schema for this field (`widgetFormSchema.shape.name`): a
+     * value it refuses never leaves the browser, and its message shows
+     * under the field. Its output is what `save` gets.
+     */
+    schema?: {
+        safeParse: (value: unknown) => SafeParseResult<TValue>;
+    };
+    /**
+     * Saves the value: the entity's single-field save (`useRecordUpdate`
+     * with `optimistic: false, toastOnError: false`), `mutateAsync` of the
+     * field's update. Rejects with the AppError; a 422's field error shows
+     * under the field word for word.
+     */
+    save: (value: TValue) => Promise<unknown>;
+    /** Whether a draft is still the saved value. Defaults to comparing as JSON. */
+    isEqual?: (a: TDraft, b: TDraft) => boolean;
+};
+/** Marks a field editable in place, typed end to end: draft → schema → save. */
+export declare function editInPlace<TDraft, TValue = TDraft>(options: EditInPlaceOptions<TDraft, TValue>): EditInPlace;
+export declare const EditInPlaceContext: import("react").Context<EditInPlaceStore | null>;
+export {};

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

@@ -0,0 +1,10 @@
+// Editing in place on a record's view: what a field passes to EntityView
+// (or to an EditableValue in its header) to become editable where it's
+// shown. The rules live in edit-in-place-store.ts; the markup in
+// editable-value.tsx. Design language: cell-patterns.md "Editable value".
+import { createContext } from 'react';
+/** Marks a field editable in place, typed end to end: draft → schema → save. */
+export function editInPlace(options) {
+    return options;
+}
+export const EditInPlaceContext = createContext(null);

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

@@ -0,0 +1,23 @@
+import { type ReactNode } from 'react';
+import { type EditInPlace } from './edit-in-place.js';
+import type { EditInPlaceStore } from './edit-in-place-store.js';
+export type EditableValueProps = {
+    /** The field's label: the control's accessible name, and the edit button's ("Edit Name"). */
+    label: string;
+    edit: EditInPlace;
+    /** The value as the view shows it. */
+    children: ReactNode;
+    /** `inline` in a heading or beside badges, `block` in a field row (default). */
+    layout?: 'inline' | 'block';
+    className?: string;
+};
+export declare function EditableValue({ label, edit, children, layout, className }: EditableValueProps): import("react").JSX.Element;
+/**
+ * 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.
+ */
+export declare function LeaveGuard({ store }: {
+    store: EditInPlaceStore;
+}): import("react").JSX.Element;

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

@@ -0,0 +1,176 @@
+import { jsx as _jsx, jsxs as _jsxs } 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
+// badge uses <EditableValue> itself. The rules are edit-in-place-store.ts.
+//
+// - Start: click the value (a link inside it still navigates), or tab to
+//   its edit button and press Enter. Hover and focus show it's editable.
+// - Save: leave it (click or tab elsewhere), Enter on one line,
+//   Ctrl/Cmd+Enter anywhere, or pick a choice. Esc puts the saved value
+//   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';
+import { useBlocker } from 'react-router';
+import { cn } from 'cn';
+import { Button } from '../ui/button.js';
+import { Dialog, DialogClose, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogTitle, } from '../ui/dialog.js';
+import { FieldError } from '../ui/field.js';
+import { Spinner } from '../ui/spinner.js';
+import { EditInPlaceContext } from './edit-in-place.js';
+// What a click on the shown value must leave alone: links navigate,
+// buttons do their own thing.
+const INTERACTIVE = 'a[href], button, input, select, textarea, [role="button"], [role="link"]';
+// Where the caret goes once the control shows: the first match, in this
+// order (a picker's text box before its chips' remove buttons).
+const FOCUS_ORDER = [
+    'input:not([type="hidden"]), textarea, [contenteditable="true"]',
+    '[role="combobox"], [role="switch"], button, [tabindex]:not([tabindex="-1"])',
+];
+// Focus moving here doesn't save the field: a link that leaves the page
+// (the leave prompt decides what happens to the draft) or the prompt itself.
+const LEAVING = 'a[href]:not([target="_blank"]), [data-leave-guard]';
+// The field's own control, given what it needs.
+function Control({ render, ...props }) {
+    return render(props);
+}
+function useStore() {
+    const store = useContext(EditInPlaceContext);
+    if (!store)
+        throw new Error('<EditableValue> works inside an <EntityView>, which runs editing in place.');
+    return store;
+}
+export function EditableValue({ label, edit, children, layout = 'block', className }) {
+    const store = useStore();
+    const key = useId();
+    const controlId = `${key}-control`;
+    const describedBy = `${key}-status`;
+    // The latest config, read by the store whenever it needs it.
+    const config = useRef(edit);
+    useLayoutEffect(() => {
+        config.current = edit;
+    });
+    useEffect(() => store.register(key, () => config.current), [store, key]);
+    const state = useSyncExternalStore(store.subscribe, () => store.state(key), () => store.state(key));
+    const editButton = useRef(null);
+    const container = useRef(null);
+    // Set by a keyboard save or Esc: the caret goes back to the edit button.
+    const refocus = useRef(false);
+    const blurTimer = useRef(undefined);
+    const isOpen = state.status !== 'closed';
+    const wasOpen = useRef(false);
+    useEffect(() => {
+        if (isOpen && !wasOpen.current) {
+            for (const selector of FOCUS_ORDER) {
+                const target = container.current?.querySelector(selector);
+                if (target) {
+                    target.focus();
+                    break;
+                }
+            }
+        }
+        // Closed: the caret goes back to the value's edit button after a
+        // keyboard save or Esc, or whenever closing left it nowhere (a pick
+        // from a list), so the keyboard never loses its place.
+        if (!isOpen && wasOpen.current && (refocus.current || document.activeElement === document.body)) {
+            refocus.current = false;
+            editButton.current?.focus();
+        }
+        wasOpen.current = isOpen;
+    }, [isOpen]);
+    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
+    // listener, before React sees the key, and by then it reads as closed.
+    const escapeClosesList = useRef(false);
+    useEffect(() => {
+        if (!isOpen)
+            return;
+        const onKeyDown = (event) => {
+            if (event.key !== 'Escape')
+                return;
+            escapeClosesList.current = Boolean(event.target?.closest?.('[aria-expanded="true"]'));
+        };
+        window.addEventListener('keydown', onKeyDown, true);
+        return () => window.removeEventListener('keydown', onKeyDown, true);
+    }, [isOpen]);
+    const start = useCallback(() => void store.start(key), [store, key]);
+    const commit = useCallback((value) => {
+        window.clearTimeout(blurTimer.current);
+        void store.commit(key, value);
+    }, [store, key]);
+    const cancel = useCallback(() => store.cancel(key), [store, key]);
+    const onShownClick = (event) => {
+        if (event.target.closest(INTERACTIVE))
+            return;
+        start();
+    };
+    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)
+                return;
+            event.preventDefault();
+            refocus.current = true;
+            cancel();
+        }
+        else if (event.key === 'Enter' && (event.metaKey || event.ctrlKey)) {
+            event.preventDefault();
+            refocus.current = true;
+            commit();
+        }
+        else if (event.key === 'Enter' && edit.kind === 'text' && !event.shiftKey && !event.altKey) {
+            event.preventDefault();
+            refocus.current = true;
+            commit();
+        }
+    };
+    // 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.
+    const onBlur = (event) => {
+        window.clearTimeout(blurTimer.current);
+        if (event.relatedTarget?.closest(LEAVING))
+            return;
+        blurTimer.current = window.setTimeout(() => {
+            if (store.state(key).status === 'open')
+                void store.commit(key);
+        }, 0);
+    };
+    const onFocus = () => window.clearTimeout(blurTimer.current);
+    if (state.status === 'closed') {
+        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 })) })] }));
+}
+/**
+ * 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.
+ */
+export function LeaveGuard({ store }) {
+    const dirty = useSyncExternalStore(store.subscribe, () => store.dirty, () => store.dirty);
+    const blocker = useBlocker(({ currentLocation, nextLocation }) => store.dirty && currentLocation.pathname !== nextLocation.pathname);
+    useEffect(() => {
+        if (!dirty)
+            return;
+        const onBeforeUnload = (event) => {
+            event.preventDefault();
+        };
+        window.addEventListener('beforeunload', onBeforeUnload);
+        return () => window.removeEventListener('beforeunload', onBeforeUnload);
+    }, [dirty]);
+    return (_jsx(Dialog, { open: blocker.state === 'blocked', onOpenChange: (open) => {
+            if (!open && 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();
+                                if (blocker.state === 'blocked')
+                                    blocker.proceed();
+                            }, children: "Discard" })] })] }) }));
+}

package/dist/components/app/entity-view.d.ts

@@ -1,5 +1,6 @@
 import { type ReactNode } from 'react';
 import type { AppError } from '../../api/contracts.js';
+import { type EditInPlace } from './edit-in-place.js';
 export type EntityViewField = {
     label: string;
     /**
@@ -10,6 +11,8 @@ export type EntityViewField = {
     value: ReactNode;
     /** What an empty value reads as: the plan's "not set" label. Defaults to "Not set". */
     emptyLabel?: string;
+    /** Editable in place: `editInPlace({...})`. Unmarked, the value is read-only. */
+    edit?: EditInPlace;
 };
 /**
  * A titled card on the view: either label/value rows (`fields`), or one
@@ -26,10 +29,16 @@ export type EntityViewSection = {
     title: string;
     content: ReactNode;
     emptyLabel?: string;
+    /** The block is editable in place (long text), named by the section's title. */
+    edit?: EditInPlace;
 };
 export type EntityViewProps = {
     /** The record's name or title, the page's <h1>. */
     title?: string;
+    /** The title is editable in place; `label` is the field's ("Name"). */
+    titleEdit?: EditInPlace & {
+        label: string;
+    };
     /**
      * A few status-like values beside the title, as `<Badge>`s, or as the
      * control that changes one when the plan makes it a quick action (a
@@ -49,4 +58,4 @@ export type EntityViewProps = {
         label: string;
     };
 };
-export declare function EntityView({ title, badges, actions, sections, isLoading, error, onRetry, back, }: EntityViewProps): import("react").JSX.Element;
+export declare function EntityView({ title, titleEdit, badges, actions, sections, isLoading, error, onRetry, back, }: EntityViewProps): import("react").JSX.Element;