@tristan2828/ui-foundation 3.11.0 → 3.13.0

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

@@ -0,0 +1,221 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+// The rich-text editor behind RichTextEditor, loaded only when one opens
+// (rich-text-editor.tsx imports this lazily): Milkdown, a ProseMirror
+// editor whose Markdown goes in and out through remark, the same parser
+// <Markdown> renders with. Why Milkdown, and what it costs:
+// docs/ARCHITECTURE.md "Decisions".
+//
+// What this file adds to Milkdown's own presets:
+// - Saves go through mergeMarkdown: an untouched document, and every block
+//   the person didn't change, saves back as originally written.
+// - No HTML in, ever. The preset's "preserve empty line" plugin is left
+//   out: it writes an empty paragraph as a raw `<br />`. Raw HTML already
+//   in the text shows as its characters (an uneditable chip, Milkdown's
+//   html node), and HTML pasted as such a chip becomes plain text.
+// - Headings render from <h3>, like <Markdown>: the page owns <h1> and
+//   <h2>. A task-list item renders a real checkbox that toggles it.
+// - Edited blocks are written in the document's own bullet and rule marks.
+import { useEffect, useRef } from 'react';
+import { defaultValueCtx, Editor, editorViewCtx, editorViewOptionsCtx, remarkStringifyOptionsCtx, rootCtx, } from '@milkdown/kit/core';
+import { history } from '@milkdown/kit/plugin/history';
+import { commands, inputRules, keymap, markInputRules, plugins, remarkPreserveEmptyLinePlugin, schema, } from '@milkdown/kit/preset/commonmark';
+import { gfm } from '@milkdown/kit/preset/gfm';
+import { Fragment, Slice } from '@milkdown/kit/prose/model';
+import { Plugin } from '@milkdown/kit/prose/state';
+import { $prose, getMarkdown } from '@milkdown/kit/utils';
+import { cn } from 'cn';
+import { MarkdownMergeError, markdownStyle, mergeMarkdown } from '../../lib/markdown-merge.js';
+// The commonmark preset, minus the plugin that writes `<br />`. A $remark
+// plugin is a pair (its options and the plugin), spread into `plugins`.
+const LEFT_OUT = remarkPreserveEmptyLinePlugin;
+const COMMONMARK = [
+    ...schema,
+    ...inputRules,
+    ...markInputRules,
+    ...commands,
+    ...keymap,
+    ...plugins.filter((plugin) => !LEFT_OUT.includes(plugin)),
+];
+// Raw HTML pasted in as Milkdown's html chip becomes the plain text it
+// shows, so a paste can never add markup to the Markdown.
+function htmlToText(fragment) {
+    const nodes = [];
+    fragment.forEach((node) => {
+        if (node.type.name === 'html') {
+            const value = String(node.attrs.value ?? '');
+            if (value)
+                nodes.push(node.type.schema.text(value));
+        }
+        else {
+            nodes.push(node.copy(htmlToText(node.content)));
+        }
+    });
+    return Fragment.fromArray(nodes);
+}
+function headingView(node) {
+    const dom = document.createElement(`h${Math.min(Number(node.attrs.level) + 2, 6)}`);
+    return {
+        dom,
+        contentDOM: dom,
+        update: (next) => next.type === node.type && next.attrs.level === node.attrs.level,
+    };
+}
+// A task-list item: its checkbox toggles `checked`. Any other list item
+// renders as Milkdown's own.
+function taskItemView(node, view, getPos) {
+    const dom = document.createElement('li');
+    const box = document.createElement('input');
+    box.type = 'checkbox';
+    box.contentEditable = 'false';
+    box.tabIndex = -1;
+    box.setAttribute('aria-label', 'Done');
+    const contentDOM = document.createElement('div');
+    dom.append(box, contentDOM);
+    dom.dataset.itemType = 'task';
+    let current = node;
+    const render = () => {
+        box.checked = Boolean(current.attrs.checked);
+        dom.dataset.checked = String(Boolean(current.attrs.checked));
+    };
+    render();
+    box.addEventListener('mousedown', (event) => event.preventDefault());
+    // The browser's own toggle is left to happen (cancelling a checkbox's
+    // click puts its old state back after this handler), and the document
+    // follows it.
+    box.addEventListener('click', () => {
+        const pos = getPos();
+        if (pos === undefined || !view.editable)
+            return;
+        view.dispatch(view.state.tr.setNodeMarkup(pos, undefined, { ...current.attrs, checked: !current.attrs.checked }));
+    });
+    return {
+        dom,
+        contentDOM,
+        update: (next) => {
+            if (next.type !== current.type || next.attrs.checked == null)
+                return false;
+            current = next;
+            render();
+            return true;
+        },
+        stopEvent: (event) => event.target === box,
+        ignoreMutation: (mutation) => mutation.target === box,
+    };
+}
+export default function MilkdownEditor({ id, defaultValue, onChange, onProblem, readOnly = false, autoFocus = false, className, 'aria-label': ariaLabel, 'aria-labelledby': ariaLabelledBy, 'aria-describedby': ariaDescribedBy, 'aria-invalid': ariaInvalid, }) {
+    const rootRef = useRef(null);
+    const editorRef = useRef(null);
+    // The latest props, for the editor's callbacks, which are set up once.
+    const latest = useRef({ onChange, onProblem, readOnly });
+    useEffect(() => {
+        latest.current = { onChange, onProblem, readOnly };
+    });
+    const attributes = {
+        'aria-multiline': 'true',
+        'aria-readonly': String(readOnly),
+        class: 'outline-none',
+    };
+    if (id)
+        attributes.id = id;
+    if (ariaLabel)
+        attributes['aria-label'] = ariaLabel;
+    if (ariaLabelledBy)
+        attributes['aria-labelledby'] = ariaLabelledBy;
+    if (ariaDescribedBy)
+        attributes['aria-describedby'] = ariaDescribedBy;
+    if (ariaInvalid)
+        attributes['aria-invalid'] = 'true';
+    const attributesKey = JSON.stringify(attributes);
+    // The editor is made once, from the Markdown it opened with.
+    useEffect(() => {
+        const root = rootRef.current;
+        if (!root)
+            return;
+        const original = defaultValue;
+        let baseline = null;
+        let cancelled = false;
+        const emit = () => {
+            const editor = editorRef.current;
+            if (!editor || baseline === null)
+                return;
+            const current = editor.action(getMarkdown());
+            try {
+                const merged = mergeMarkdown(original, baseline, current);
+                latest.current.onProblem?.(null);
+                latest.current.onChange(merged);
+            }
+            catch (error) {
+                if (!(error instanceof MarkdownMergeError))
+                    throw error;
+                latest.current.onProblem?.(error.message);
+            }
+        };
+        const changes = $prose(() => new Plugin({
+            view: () => ({
+                update: (view, previous) => {
+                    if (!view.state.doc.eq(previous.doc))
+                        emit();
+                },
+            }),
+            props: {
+                transformPasted: (slice) => new Slice(htmlToText(slice.content), slice.openStart, slice.openEnd),
+            },
+        }));
+        const make = Editor.make()
+            .config((ctx) => {
+            ctx.set(rootCtx, root);
+            ctx.set(defaultValueCtx, original);
+            ctx.update(remarkStringifyOptionsCtx, (options) => ({ ...options, ...markdownStyle(original) }));
+            ctx.update(editorViewOptionsCtx, (options) => ({
+                ...options,
+                editable: () => !latest.current.readOnly,
+                attributes,
+                nodeViews: {
+                    heading: headingView,
+                    list_item: (node, view, getPos) => node.attrs.checked == null ? undefined : taskItemView(node, view, getPos),
+                },
+            }));
+        })
+            .use(COMMONMARK)
+            .use(gfm)
+            .use(history)
+            .use(changes);
+        void make.create().then((editor) => {
+            if (cancelled) {
+                void editor.destroy();
+                return;
+            }
+            editorRef.current = editor;
+            baseline = editor.action(getMarkdown());
+            if (autoFocus)
+                editor.action((ctx) => ctx.get(editorViewCtx).focus());
+        });
+        return () => {
+            cancelled = true;
+            const editor = editorRef.current;
+            editorRef.current = null;
+            if (editor)
+                void editor.destroy();
+            root.replaceChildren();
+        };
+        // Made once per mount: later changes to defaultValue are ignored, as
+        // with any uncontrolled input. Attributes and read-only follow below.
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, []);
+    // Read-only and the ARIA attributes follow their props.
+    useEffect(() => {
+        const editor = editorRef.current;
+        if (!editor)
+            return;
+        editor.action((ctx) => {
+            const view = ctx.get(editorViewCtx);
+            view.setProps({ editable: () => !readOnly, attributes: JSON.parse(attributesKey) });
+        });
+    }, [readOnly, attributesKey]);
+    return (_jsx("div", { ref: rootRef, "data-slot": "rich-text-editor", className: cn('min-h-24 w-full min-w-0 rounded-lg border border-input bg-transparent px-2.5 py-2 type-body text-foreground break-words transition-colors', 'focus-within:border-ring focus-within:ring-3 focus-within:ring-ring/50 dark:bg-input/30', 'has-[[aria-invalid=true]]:border-destructive has-[[aria-invalid=true]]:ring-destructive/20', 'has-[[aria-readonly=true]]:text-muted-foreground', 
+        // The same type roles <Markdown> uses, so text reads the same
+        // being edited as being read.
+        '[&_.ProseMirror]:flex [&_.ProseMirror]:min-h-20 [&_.ProseMirror]:flex-col [&_.ProseMirror]:gap-3', '[&_h3]:type-section-title [&_h4]:type-section-title [&_h5]:type-label [&_h6]:type-label', '[&_ul]:flex [&_ul]:list-disc [&_ul]:flex-col [&_ul]:gap-1 [&_ul]:pl-6', '[&_ol]:flex [&_ol]:list-decimal [&_ol]:flex-col [&_ol]:gap-1 [&_ol]:pl-6', '[&_li[data-item-type=task]]:-ml-6 [&_li[data-item-type=task]]:flex [&_li[data-item-type=task]]:list-none [&_li[data-item-type=task]]:items-start [&_li[data-item-type=task]]:gap-2', '[&_li[data-item-type=task]>input]:mt-1 [&_li[data-item-type=task]>input]:size-4 [&_li[data-item-type=task]>input]:accent-primary', '[&_a]:text-primary [&_a]:underline [&_a]:underline-offset-4', '[&_blockquote]:border-l-2 [&_blockquote]:border-border [&_blockquote]:pl-4 [&_blockquote]:text-muted-foreground', '[&_pre]:overflow-x-auto [&_pre]:rounded-lg [&_pre]:bg-muted [&_pre]:p-3 [&_pre]:font-mono', '[&_:not(pre)>code]:rounded [&_:not(pre)>code]:bg-muted [&_:not(pre)>code]:px-1 [&_:not(pre)>code]:font-mono', '[&_hr]:border-border', '[&_table]:w-full [&_table]:border-collapse [&_td]:border [&_td]:border-border [&_td]:px-2 [&_td]:py-1 [&_th]:border [&_th]:border-border [&_th]:px-2 [&_th]:py-1 [&_th]:text-left [&_th]:type-label', 
+        // Raw HTML from the text: shown as its characters, never as markup.
+        '[&_span[data-type=html]]:rounded [&_span[data-type=html]]:bg-muted [&_span[data-type=html]]:px-1 [&_span[data-type=html]]:font-mono [&_span[data-type=html]]:text-foreground', className) }));
+}

package/dist/components/app/multi-reference.d.ts

@@ -1,5 +1,5 @@
 import * as React from 'react';
-export declare function MultiReference<Id extends string | number>({ options, value, onValueChange, getLabel, onSearchChange, id, placeholder, emptyText, 'aria-label': ariaLabel, 'aria-invalid': ariaInvalid, className, }: {
+export declare function MultiReference<Id extends string | number>({ options, value, onValueChange, getLabel, onSearchChange, id, placeholder, emptyText, 'aria-label': ariaLabel, 'aria-invalid': ariaInvalid, 'aria-describedby': ariaDescribedBy, readOnly, className, }: {
     /** The records the current search returned, in display order. */
     options: readonly {
         id: Id;
@@ -23,5 +23,9 @@ export declare function MultiReference<Id extends string | number>({ options, va
     /** For use without a visible label (e.g. a table toolbar filter). */
     'aria-label'?: string;
     'aria-invalid'?: boolean;
+    /** The id of a line under the control (an error, a saving status). */
+    'aria-describedby'?: string;
+    /** Shown, not changeable: editing in place, while the save is in flight. */
+    readOnly?: boolean;
     className?: string;
 }): React.JSX.Element;

package/dist/components/app/multi-reference.js

@@ -17,11 +17,11 @@ import * as React from 'react';
 import { Combobox, ComboboxChip, ComboboxChips, ComboboxChipsInput, ComboboxContent, ComboboxEmpty, ComboboxItem, ComboboxList, ComboboxValue, useComboboxAnchor, } from '../ui/combobox.js';
 /** Shown on a chip whose name hasn't loaded yet, instead of a bare id. */
 const PENDING_LABEL = '…';
-export function MultiReference({ options, value, onValueChange, getLabel, onSearchChange, id, placeholder, emptyText = 'No matches.', 'aria-label': ariaLabel, 'aria-invalid': ariaInvalid, className, }) {
+export function MultiReference({ options, value, onValueChange, getLabel, onSearchChange, id, placeholder, emptyText = 'No matches.', 'aria-label': ariaLabel, 'aria-invalid': ariaInvalid, 'aria-describedby': ariaDescribedBy, readOnly = false, className, }) {
     const anchor = useComboboxAnchor();
     const label = (option) => getLabel(option) ?? PENDING_LABEL;
     return (_jsxs(Combobox, { multiple: true, autoHighlight: true, 
         // Ids, not {id,label} objects: Base UI compares items to the value
         // with Object.is, so the items must have the value's own shape.
-        items: options.map((option) => option.id), value: value, onValueChange: (next) => onValueChange(next), onInputValueChange: onSearchChange, itemToStringLabel: label, filter: null, children: [_jsx(ComboboxChips, { ref: anchor, className: className, children: _jsx(ComboboxValue, { children: (selected) => (_jsxs(React.Fragment, { children: [selected.map((option) => (_jsx(ComboboxChip, { children: label(option) }, option))), _jsx(ComboboxChipsInput, { id: id, "aria-label": ariaLabel, "aria-invalid": ariaInvalid, placeholder: selected.length === 0 ? placeholder : undefined })] })) }) }), _jsxs(ComboboxContent, { anchor: anchor, children: [_jsx(ComboboxEmpty, { children: emptyText }), _jsx(ComboboxList, { children: (option) => (_jsx(ComboboxItem, { value: option, children: label(option) }, option)) })] })] }));
+        items: options.map((option) => option.id), value: value, onValueChange: (next) => onValueChange(next), onInputValueChange: onSearchChange, itemToStringLabel: label, filter: null, readOnly: readOnly, children: [_jsx(ComboboxChips, { ref: anchor, className: className, children: _jsx(ComboboxValue, { children: (selected) => (_jsxs(React.Fragment, { children: [selected.map((option) => (_jsx(ComboboxChip, { children: label(option) }, option))), _jsx(ComboboxChipsInput, { id: id, "aria-label": ariaLabel, "aria-invalid": ariaInvalid, "aria-describedby": ariaDescribedBy, placeholder: selected.length === 0 ? placeholder : undefined })] })) }) }), _jsxs(ComboboxContent, { anchor: anchor, children: [_jsx(ComboboxEmpty, { children: emptyText }), _jsx(ComboboxList, { children: (option) => (_jsx(ComboboxItem, { value: option, children: label(option) }, option)) })] })] }));
 }

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

@@ -0,0 +1,20 @@
+export type RichTextEditorProps = {
+    /** The editable element's id, for a label's `htmlFor` or a test. */
+    id?: string;
+    /** The Markdown it opens with. Read once, when it mounts (uncontrolled). */
+    defaultValue: string;
+    /** The Markdown to save, after every edit: untouched blocks as originally written. */
+    onChange: (markdown: string) => void;
+    /** Why the edit can't be saved as it stands, or `null` once it can. */
+    onProblem?: (message: string | null) => void;
+    /** Shown but not editable (while a save is in flight). */
+    readOnly?: boolean;
+    autoFocus?: boolean;
+    className?: string;
+    /** The field's label. A rich-text area must have one: this, or `aria-labelledby`. */
+    'aria-label'?: string;
+    'aria-labelledby'?: string;
+    'aria-describedby'?: string;
+    'aria-invalid'?: boolean;
+};
+export declare function RichTextEditor(props: RichTextEditorProps): import("react").JSX.Element;

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

@@ -0,0 +1,25 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// Long text written as Markdown, edited as formatted text where it's read
+// (Notion-style), not as Markdown syntax in a textarea. The control for a
+// `long text` field marked Markdown, on the form and in place on the view.
+//
+// It stays Markdown: it opens from Markdown and reports Markdown. Opening
+// and saving round-trip exactly: an untouched document comes back byte for
+// byte, and an edited one keeps every block the person didn't change as it
+// was written (src/lib/markdown-merge.ts). If an edit can't be saved
+// without rewriting another block, `onProblem` says so and `onChange`
+// isn't called: the draft stays on screen, nothing is saved in its place.
+//
+// Raw HTML in the text shows as its characters, as <Markdown> shows it,
+// and nothing pasted or typed can add markup.
+//
+// The editor (Milkdown) is loaded on first use, so a page that only reads
+// Markdown never downloads it. Until it arrives, a placeholder the size of
+// the field shows.
+import { lazy, Suspense } from 'react';
+import { cn } from 'cn';
+import { Skeleton } from '../ui/skeleton.js';
+const MilkdownEditor = lazy(() => import('./milkdown-editor.js'));
+export function RichTextEditor(props) {
+    return (_jsx(Suspense, { fallback: _jsxs("div", { "data-slot": "rich-text-editor", "data-state": "loading", className: cn('flex min-h-24 w-full flex-col gap-2 rounded-lg border border-input px-2.5 py-2', props.className), children: [_jsx(Skeleton, { className: "h-4 w-3/4" }), _jsx(Skeleton, { className: "h-4 w-1/2" })] }), children: _jsx(MilkdownEditor, { ...props }) }));
+}

package/dist/components/ui/field.js

@@ -13,7 +13,7 @@ function FieldLegend({ className, variant = "legend", ...props }) {
 function FieldGroup({ className, ...props }) {
     return (_jsx("div", { "data-slot": "field-group", className: cn("group/field-group @container/field-group flex w-full flex-col gap-5 data-[slot=checkbox-group]:gap-3 *:data-[slot=field-group]:gap-4", className), ...props }));
 }
-const fieldVariants = cva("group/field flex w-full gap-2 data-[invalid=true]:text-destructive", {
+const fieldVariants = cva("group/field flex w-full gap-2 data-[invalid=true]:text-destructive-text", {
     variants: {
         orientation: {
             vertical: "flex-col *:w-full [&>.sr-only]:w-auto",
@@ -62,6 +62,6 @@ function FieldError({ className, children, errors, ...props }) {
     if (!content) {
         return null;
     }
-    return (_jsx("div", { role: "alert", "data-slot": "field-error", className: cn("text-sm font-normal text-destructive", className), ...props, children: content }));
+    return (_jsx("div", { role: "alert", "data-slot": "field-error", className: cn("text-sm font-normal text-destructive-text", className), ...props, children: content }));
 }
 export { Field, FieldLabel, FieldDescription, FieldError, FieldGroup, FieldLegend, FieldSeparator, FieldSet, FieldContent, FieldTitle, };

package/dist/hooks/use-record-update.d.ts

@@ -0,0 +1,71 @@
+import { type MutationOptions, type QueryClient, type QueryKey } from '@tanstack/react-query';
+import type { AppError } from '../api/contracts.js';
+type RecordId = string | number;
+/**
+ * What one save changes: the fields to send (`{ status: 'done' }`), or a
+ * function building them from the record (`(task) => ({ checklist: ... })`).
+ * Use the function when the new value depends on the current one, like a
+ * whole list with one item changed: it is applied to the record on screen
+ * at once, and again to the server's latest record when the request is
+ * sent, so a change made while another is saving builds on it.
+ */
+export type RecordChange<TRecord, TUpdate> = TUpdate | ((record: TRecord) => TUpdate);
+export type RecordUpdateOptions<TRecord extends {
+    id: RecordId;
+}, TUpdate extends Partial<TRecord>> = {
+    /** The record's id: list items with this id are the ones updated. */
+    id: TRecord['id'];
+    /** The record's detail query key, the one its view reads. */
+    detailKey: QueryKey;
+    /** The prefix every list query of the entity starts with; each holds a `Page<TRecord>`. */
+    listsKey: QueryKey;
+    /** The gateway's PATCH: sends `update`, resolves with the saved record, rejects with an `AppError`. */
+    update: (id: TRecord['id'], update: TUpdate) => Promise<TRecord>;
+    /** What a refusal's toast calls the record: "Couldn't update <name>: <reason>". */
+    name: (record: TRecord) => string;
+    /**
+     * Show the change before the server answers (default `true`, a quick
+     * action). `false` for editing in place: the value shows as saved only
+     * once it is, and until then the field holds it.
+     */
+    optimistic?: boolean;
+    /**
+     * Toast a refusal (default `true`). `false` when the control shows the
+     * reason itself (editing in place): `mutateAsync` rejects with the
+     * `AppError`, and `refusalReason` words it.
+     */
+    toastOnError?: boolean;
+};
+type Entry<TRecord, TUpdate> = {
+    change: RecordChange<TRecord, TUpdate>;
+    optimistic: boolean;
+};
+/**
+ * Why a save was refused, in the server's words: for a 422, the message
+ * on a field the save sent (the first field error otherwise), else the
+ * `AppError`'s message.
+ */
+export declare function refusalReason(error: AppError, sent?: object): string;
+/**
+ * The mutation options behind `useRecordUpdate`, for a given QueryClient.
+ * Exported for tests and for code outside React; screens use the hook.
+ */
+export declare function recordUpdateMutationOptions<TRecord extends {
+    id: RecordId;
+}, TUpdate extends Partial<TRecord>>(queryClient: QueryClient, { id, detailKey, listsKey, update, name, optimistic, toastOnError }: RecordUpdateOptions<TRecord, TUpdate>): MutationOptions<TRecord, AppError, RecordChange<TRecord, TUpdate>, {
+    entry: Entry<TRecord, TUpdate>;
+}>;
+/**
+ * Saves a record's fields on their own, optimistically, wherever the
+ * record is cached (see the top of this file). Call it once per control,
+ * with the entity's query keys and its gateway PATCH, then
+ * `mutate({ field: value })` or `mutate((record) => ({ field: ... }))`.
+ * `isPending` is that control's own save in flight. A refusal rolls back
+ * and shows a toast by itself.
+ */
+export declare function useRecordUpdate<TRecord extends {
+    id: RecordId;
+}, TUpdate extends Partial<TRecord>>(options: RecordUpdateOptions<TRecord, TUpdate>): import("@tanstack/react-query").UseMutationResult<TRecord, AppError, RecordChange<TRecord, TUpdate>, {
+    entry: Entry<TRecord, TUpdate>;
+}>;
+export {};

package/dist/hooks/use-record-update.js

@@ -0,0 +1,148 @@
+// One record's fields saved on their own, straight from the screen showing
+// them (a quick action on the view, a switch in a table row), instead of
+// through the form. A PATCH of what changed, optimistic everywhere the
+// record is cached: its detail query (what the view shows) and every list
+// page holding it. The piece any save-without-the-form reuses.
+//
+// - **Shown at once.** The change is applied to the cached record before
+//   the request goes out, so the screen moves when the user does.
+// - **The server's record wins.** When the save answers, the cache takes
+//   the record the server returned, not the one sent, so a server-side
+//   effect (a computed field, a flag one change clears) shows at once.
+// - **Rapid changes don't lose each other.** Saves of one record run one
+//   at a time (a TanStack mutation scope per record), and each request is
+//   built when it is sent, from the server's latest record. Ticking two
+//   checklist items quickly sends the whole list twice, and the second
+//   request already holds the first tick. A change can be a function of
+//   the record for exactly this: `(record) => ({ checklist: ... })`.
+// - **A refusal rolls back only itself.** The cache goes back to the
+//   server's latest record with every change still waiting re-applied on
+//   top, and a toast gives the server's reason (the field's 422 message,
+//   or the AppError's).
+// - **The lists refetch once the last save settles**, so a filter on the
+//   field drops the row once the server agrees.
+//
+// Editing in place uses the same save with `optimistic: false` and
+// `toastOnError: false`: nothing changes on screen until the server
+// agrees, and a refusal comes back to the field (`mutateAsync` rejects)
+// instead of a toast.
+import { hashKey, useMutation, useQueryClient, } from '@tanstack/react-query';
+import { toast } from 'sonner';
+const states = new WeakMap();
+function recordStates(queryClient) {
+    let map = states.get(queryClient);
+    if (!map)
+        states.set(queryClient, (map = new Map()));
+    return map;
+}
+function resolve(change, record) {
+    return typeof change === 'function' ? change(record) : change;
+}
+/**
+ * Why a save was refused, in the server's words: for a 422, the message
+ * on a field the save sent (the first field error otherwise), else the
+ * `AppError`'s message.
+ */
+export function refusalReason(error, sent) {
+    const fieldErrors = Object.entries(error.fieldErrors ?? {});
+    const fields = Object.keys(sent ?? {});
+    const onSentField = fieldErrors.find(([key]) => fields.some((field) => key === field || key.startsWith(`${field}.`)));
+    return (onSentField ?? fieldErrors[0])?.[1][0] ?? error.message;
+}
+/**
+ * The mutation options behind `useRecordUpdate`, for a given QueryClient.
+ * Exported for tests and for code outside React; screens use the hook.
+ */
+export function recordUpdateMutationOptions(queryClient, { id, detailKey, listsKey, update, name, optimistic = true, toastOnError = true }) {
+    const key = hashKey(detailKey);
+    const lists = { queryKey: listsKey };
+    const map = recordStates(queryClient);
+    // The record as the caches hold it now: the detail, else a list's copy.
+    function cached() {
+        const detail = queryClient.getQueryData(detailKey);
+        if (detail)
+            return detail;
+        for (const [, page] of queryClient.getQueriesData(lists)) {
+            const item = page?.items.find((record) => record.id === id);
+            if (item)
+                return item;
+        }
+        return undefined;
+    }
+    // Writes confirmed + pending changes to the detail (when it's cached)
+    // and to every list page holding the record.
+    function render(state) {
+        if (!state.confirmed)
+            return;
+        const shown = state.pending.reduce((record, entry) => (entry.optimistic ? { ...record, ...resolve(entry.change, record) } : record), state.confirmed);
+        queryClient.setQueryData(detailKey, (detail) => detail && shown);
+        queryClient.setQueriesData(lists, (page) => page && { ...page, items: page.items.map((record) => (record.id === id ? shown : record)) });
+    }
+    // A save has settled: drop its change and show what's left on top of
+    // the server's latest record. After the last one, refetch the lists.
+    function settle(state, entry) {
+        state.pending = state.pending.filter((pending) => pending !== entry);
+        render(state);
+        if (state.pending.length === 0) {
+            map.delete(key);
+            void queryClient.invalidateQueries(lists);
+        }
+    }
+    return {
+        // One save of this record at a time: the next waits for the last
+        // one's answer, so its request is built on the server's latest record.
+        scope: { id: `record-update:${key}` },
+        mutationFn: (change) => {
+            const confirmed = map.get(key)?.confirmed ?? cached();
+            if (!confirmed)
+                return Promise.reject(new Error('The record to update is not loaded'));
+            return update(id, resolve(change, confirmed));
+        },
+        onMutate: async (change) => {
+            let state = map.get(key);
+            if (!state)
+                map.set(key, (state = { confirmed: undefined, pending: [] }));
+            const entry = { change, optimistic };
+            state.pending.push(entry);
+            // A refetch landing now would overwrite the change on screen.
+            await Promise.all([
+                queryClient.cancelQueries({ queryKey: detailKey }),
+                queryClient.cancelQueries(lists),
+            ]);
+            // The first change of a burst: the caches still hold the server's record.
+            state.confirmed ??= cached();
+            render(state);
+            return { entry };
+        },
+        onError: (error, _change, context) => {
+            const state = map.get(key);
+            if (!state || !context)
+                return;
+            // What was sent: the change built on the record it was sent against.
+            const record = state.confirmed;
+            const sent = record && resolve(context.entry.change, record);
+            settle(state, context.entry);
+            if (toastOnError)
+                toast.error(`Couldn't update ${record ? name(record) : 'this record'}: ${refusalReason(error, sent)}`);
+        },
+        onSuccess: (saved, _change, context) => {
+            const state = map.get(key);
+            if (!state || !context)
+                return;
+            state.confirmed = saved;
+            settle(state, context.entry);
+        },
+    };
+}
+/**
+ * Saves a record's fields on their own, optimistically, wherever the
+ * record is cached (see the top of this file). Call it once per control,
+ * with the entity's query keys and its gateway PATCH, then
+ * `mutate({ field: value })` or `mutate((record) => ({ field: ... }))`.
+ * `isPending` is that control's own save in flight. A refusal rolls back
+ * and shows a toast by itself.
+ */
+export function useRecordUpdate(options) {
+    const queryClient = useQueryClient();
+    return useMutation(recordUpdateMutationOptions(queryClient, options));
+}

package/dist/index.d.ts

@@ -2,6 +2,8 @@ export { AppShell, type AppShellProps, type NavItem } from './components/app/app
 export { DataTable, type DataTableProps, type SortingState } from './components/app/data-table.js';
 export { EntityForm, type EntityFormProps } from './components/app/entity-form.js';
 export { EntityView, type EntityViewField, type EntityViewProps, type EntityViewSection, } from './components/app/entity-view.js';
+export { editInPlace, type EditControlProps, type EditInPlace, type EditInPlaceOptions, type EditKind, } from './components/app/edit-in-place.js';
+export { EditableValue, type EditableValueProps } from './components/app/editable-value.js';
 export { ErrorState } from './components/app/error-state.js';
 export { FoundationProviders } from './components/app/foundation-providers.js';
 export { Markdown, type MarkdownProps } from './components/app/markdown.js';
@@ -10,6 +12,7 @@ export { MultiChoice } from './components/app/multi-choice.js';
 export { MultiReference } from './components/app/multi-reference.js';
 export { ListEditor } from './components/app/list-editor.js';
 export { PasswordInput } from './components/app/password-input.js';
+export { RichTextEditor, type RichTextEditorProps } from './components/app/rich-text-editor.js';
 export { RouteErrorBoundary } from './components/app/route-error-boundary.js';
 export { ThemeProvider } from './components/theme-provider.js';
 export { LoginRoute, type LoginRouteProps } from './routes/login.js';
@@ -22,5 +25,6 @@ export { createQueryClient } from './api/query-client.js';
 export { useTableUrlState } from './hooks/use-table-url-state.js';
 export type { TableView, UrlChanges } from './hooks/table-url-changes.js';
 export { useDebouncedValue } from './hooks/use-debounced-value.js';
+export { useRecordUpdate, type RecordChange, type RecordUpdateOptions, } from './hooks/use-record-update.js';
 export { useIsMobile } from './hooks/use-mobile.js';
 export { cn } from './lib/utils.js';

package/dist/index.js

@@ -7,6 +7,8 @@ export { AppShell } from './components/app/app-shell.js';
 export { DataTable } from './components/app/data-table.js';
 export { EntityForm } from './components/app/entity-form.js';
 export { EntityView, } from './components/app/entity-view.js';
+export { editInPlace, } from './components/app/edit-in-place.js';
+export { EditableValue } from './components/app/editable-value.js';
 export { ErrorState } from './components/app/error-state.js';
 export { FoundationProviders } from './components/app/foundation-providers.js';
 export { Markdown } from './components/app/markdown.js';
@@ -15,6 +17,7 @@ export { MultiChoice } from './components/app/multi-choice.js';
 export { MultiReference } from './components/app/multi-reference.js';
 export { ListEditor } from './components/app/list-editor.js';
 export { PasswordInput } from './components/app/password-input.js';
+export { RichTextEditor } from './components/app/rich-text-editor.js';
 export { RouteErrorBoundary } from './components/app/route-error-boundary.js';
 export { ThemeProvider } from './components/theme-provider.js';
 // Screens outside the app shell
@@ -27,6 +30,7 @@ export { createQueryClient } from './api/query-client.js';
 // Hooks
 export { useTableUrlState } from './hooks/use-table-url-state.js';
 export { useDebouncedValue } from './hooks/use-debounced-value.js';
+export { useRecordUpdate, } from './hooks/use-record-update.js';
 export { useIsMobile } from './hooks/use-mobile.js';
 // Utilities
 export { cn } from './lib/utils.js';

package/dist/lib/markdown-merge.d.ts

@@ -0,0 +1,19 @@
+export declare class MarkdownMergeError extends Error {
+    constructor();
+}
+/**
+ * The Markdown to save: `original` with the edits that turned `baseline`
+ * (the editor's serialization as loaded) into `current` (its serialization
+ * now), every unchanged top-level block kept as `original` wrote it.
+ * Throws `MarkdownMergeError` rather than save something that means other
+ * than `current`.
+ */
+export declare function mergeMarkdown(original: string, baseline: string, current: string): string;
+/**
+ * The document's own marks, for writing a block the person edited the way
+ * the rest is written: its bullet (`-`, `*`, `+`) and its thematic break.
+ */
+export declare function markdownStyle(markdown: string): {
+    bullet: '-' | '*' | '+';
+    rule: '-' | '*' | '_';
+};