@tristan2828/ui-foundation 3.12.0 → 3.14.0

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

@@ -16,9 +16,15 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 // that's where quick actions go (cell pattern 17), a value the plan marks
 // as changed straight from this page and saved on its own through
 // `useRecordUpdate`: a status picked in the header, a yes/no switch,
-// checklist items ticked in place. Everything else stays read-only, and
-// every change of more than that goes through Edit, in `actions`.
-import { useId } from 'react';
+// checklist items ticked in place.
+//
+// Editing in place (cell pattern 18): a field, a `content` section or the
+// title marked `edit` turns into its form control where it's shown, and
+// saves when you leave it. This component runs it (one field open at a
+// time, the leave-page prompt); EditableValue is each value's side, and a
+// header badge uses it directly. A field not marked renders exactly as
+// before. Edit, in `actions`, stays for everything else.
+import { useId, useState, useSyncExternalStore } from 'react';
 import { Link } from 'react-router';
 import { ArrowLeftIcon, SearchXIcon } from 'lucide-react';
 import { ErrorState } from './error-state.js';
@@ -26,6 +32,9 @@ import { Button } from '../ui/button.js';
 import { Card, CardContent, CardHeader } from '../ui/card.js';
 import { Empty, EmptyContent, EmptyDescription, EmptyHeader, EmptyMedia, EmptyTitle, } from '../ui/empty.js';
 import { Skeleton } from '../ui/skeleton.js';
+import { EditInPlaceContext } from './edit-in-place.js';
+import { EditInPlaceStore } from './edit-in-place-store.js';
+import { EditableValue, LeaveGuard } from './editable-value.js';
 const DEFAULT_EMPTY_LABEL = 'Not set';
 function isEmptyValue(value) {
     return (value === null ||
@@ -43,16 +52,20 @@ function orEmptyLabel(value, emptyLabel) {
 // Label beside value from `sm` up; below it (a phone) the label sits
 // above its value, so nothing is squeezed into a narrow second column.
 function FieldRow({ field }) {
-    return (_jsxs("div", { className: "flex flex-col gap-1 py-3 first:pt-0 last:pb-0 sm:grid sm:grid-cols-[minmax(8rem,12rem)_1fr] sm:gap-6", children: [_jsx("dt", { className: "type-label text-muted-foreground", children: field.label }), _jsx("dd", { className: "min-w-0 type-body break-words text-foreground", children: orEmptyLabel(field.value, field.emptyLabel) })] }));
+    return (_jsxs("div", { className: "flex flex-col gap-1 py-3 first:pt-0 last:pb-0 sm:grid sm:grid-cols-[minmax(8rem,12rem)_1fr] sm:gap-6", children: [_jsx("dt", { className: "type-label text-muted-foreground", children: field.label }), _jsx("dd", { className: "min-w-0 type-body break-words text-foreground", children: field.edit ? (_jsx(EditableValue, { label: field.label, edit: field.edit, children: orEmptyLabel(field.value, field.emptyLabel) })) : (orEmptyLabel(field.value, field.emptyLabel)) })] }));
 }
 function ViewSection({ section }) {
     const headingId = useId();
-    return (_jsx("section", { "aria-labelledby": headingId, children: _jsxs(Card, { children: [_jsx(CardHeader, { children: _jsx("h2", { id: headingId, className: "type-section-title text-foreground", children: section.title }) }), _jsx(CardContent, { children: 'fields' in section ? (_jsx("dl", { className: "flex flex-col divide-y divide-border", children: section.fields.map((field) => (_jsx(FieldRow, { field: field }, field.label))) })) : (_jsx("div", { className: "min-w-0 type-body break-words text-foreground", children: orEmptyLabel(section.content, section.emptyLabel) })) })] }) }));
+    return (_jsx("section", { "aria-labelledby": headingId, children: _jsxs(Card, { children: [_jsx(CardHeader, { children: _jsx("h2", { id: headingId, className: "type-section-title text-foreground", children: section.title }) }), _jsx(CardContent, { children: 'fields' in section ? (_jsx("dl", { className: "flex flex-col divide-y divide-border", children: section.fields.map((field) => (_jsx(FieldRow, { field: field }, field.label))) })) : (_jsx("div", { className: "min-w-0 type-body break-words text-foreground", children: section.edit ? (_jsx(EditableValue, { label: section.title, edit: section.edit, children: orEmptyLabel(section.content, section.emptyLabel) })) : (orEmptyLabel(section.content, section.emptyLabel)) })) })] }) }));
 }
 function EntityViewSkeleton() {
     return (_jsxs("div", { className: "flex max-w-4xl flex-col gap-6", "data-state": "loading", children: [_jsx(Skeleton, { className: "h-5 w-24" }), _jsxs("div", { className: "flex flex-col gap-2", children: [_jsx(Skeleton, { className: "h-7 w-64 max-w-full" }), _jsx(Skeleton, { className: "h-5 w-40" })] }), Array.from({ length: 2 }, (_, section) => (_jsxs(Card, { children: [_jsx(CardHeader, { children: _jsx(Skeleton, { className: "h-5 w-32" }) }), _jsx(CardContent, { className: "flex flex-col gap-4", children: Array.from({ length: 4 }, (_, row) => (_jsxs("div", { className: "flex flex-col gap-1 sm:flex-row sm:gap-6", children: [_jsx(Skeleton, { className: "h-5 w-32" }), _jsx(Skeleton, { className: "h-5 flex-1" })] }, row))) })] }, section)))] }));
 }
-export function EntityView({ title, badges, actions, sections, isLoading, error, onRetry, back, }) {
+export function EntityView({ title, titleEdit, badges, actions, sections, isLoading, error, onRetry, back, }) {
+    // Editing in place: one store per view, and the leave-page prompt only
+    // while a field is open.
+    const [store] = useState(() => new EditInPlaceStore());
+    const openField = useSyncExternalStore(store.subscribe, () => store.open, () => store.open);
     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.
@@ -62,5 +75,5 @@ export function EntityView({ title, badges, actions, sections, isLoading, error,
         return _jsx(ErrorState, { error: error, onRetry: onRetry });
     if (isLoading)
         return _jsx(EntityViewSkeleton, {});
-    return (_jsxs("div", { className: "flex max-w-4xl flex-col gap-6", "data-state": "success", children: [_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-col gap-2", children: [_jsx("h1", { className: "type-page-title break-words text-foreground", children: 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 })] }), sections.map((section) => (_jsx(ViewSection, { section: section }, section.title)))] }));
+    return (_jsx(EditInPlaceContext.Provider, { value: store, children: _jsxs("div", { className: "flex max-w-4xl flex-col gap-6", "data-state": "success", 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 })] }), sections.map((section) => (_jsx(ViewSection, { section: section }, section.title)))] }) }));
 }

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

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

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

@@ -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/app/stage-circle.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Where the record is: `0` the first stage (a dashed outline), `1`–`3` a
+ * stage under way (a quarter, a half, three quarters filled), `'complete'`
+ * the final stage (solid, with a tick), `'exit'` off the lifecycle (struck
+ * through: dropped, cancelled).
+ */
+export type StageCircleStage = 0 | 1 | 2 | 3 | 'complete' | 'exit';
+/**
+ * The tone, as text on the page (`*-text` tokens). `muted` is the default:
+ * colour only the stages that mean something (in progress `info`,
+ * complete `success`), like a tone-mapped badge (cell pattern 5).
+ */
+export type StageCircleTone = 'muted' | 'info' | 'success' | 'warning' | 'destructive';
+export interface StageCircleProps {
+    stage: StageCircleStage;
+    tone?: StageCircleTone;
+    className?: string;
+}
+/** The glyph only: put the status word beside it. Hidden from screen readers, which read the word. */
+export declare function StageCircle({ stage, tone, className }: StageCircleProps): import("react").JSX.Element;

package/dist/components/app/stage-circle.js

@@ -0,0 +1,30 @@
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+// A stage circle (cell pattern 19): where a record is in an ordered
+// lifecycle, as a small circle that fills as it moves on. It sits beside
+// the status word, which stays: the shape carries the stage in greyscale
+// and the tone only reinforces it.
+//
+// Lucide has no part-filled circle, so it's drawn here, in currentColor
+// (16×16 viewBox, the ring and fill in the tone, the tick cut out of the
+// solid circle in the page's background).
+import { cn } from 'cn';
+const TONE_CLASS = {
+    muted: 'text-muted-foreground',
+    info: 'text-info-text',
+    success: 'text-success-text',
+    warning: 'text-warning-text',
+    destructive: 'text-destructive-text',
+};
+// The filled part of a stage under way: a pie from twelve o'clock,
+// clockwise, inside the ring with a gap so it reads as filling, not as a
+// thicker ring.
+const PIE = {
+    1: 'M8 8V4.5A3.5 3.5 0 0 1 11.5 8Z',
+    2: 'M8 8V4.5A3.5 3.5 0 0 1 8 11.5Z',
+    3: 'M8 8V4.5A3.5 3.5 0 1 1 4.5 8Z',
+};
+const RING = { cx: 8, cy: 8, r: 6, strokeWidth: 1.5, className: 'fill-none stroke-current' };
+/** The glyph only: put the status word beside it. Hidden from screen readers, which read the word. */
+export function StageCircle({ stage, tone = 'muted', className }) {
+    return (_jsxs("svg", { viewBox: "0 0 16 16", "aria-hidden": "true", "data-slot": "stage-circle", "data-stage": stage, className: cn('size-4 shrink-0', TONE_CLASS[tone], className), children: [stage === 0 && _jsx("circle", { ...RING, strokeDasharray: "2.4 2.3" }), (stage === 1 || stage === 2 || stage === 3) && (_jsxs(_Fragment, { children: [_jsx("circle", { ...RING }), _jsx("path", { d: PIE[stage], className: "fill-current" })] })), stage === 'complete' && (_jsxs(_Fragment, { children: [_jsx("circle", { cx: "8", cy: "8", r: "7", className: "fill-current" }), _jsx("path", { d: "M5 8.2 7.1 10.2 11 6", className: "fill-none stroke-background", strokeWidth: "1.75", strokeLinecap: "round", strokeLinejoin: "round" })] })), stage === 'exit' && (_jsxs(_Fragment, { children: [_jsx("circle", { ...RING }), _jsx("path", { d: "M4 12 12 4", className: "fill-none stroke-current", strokeWidth: "1.5", strokeLinecap: "round" })] }))] }));
+}

package/dist/components/ui/badge.d.ts

@@ -1,7 +1,7 @@
 import { useRender } from "@base-ui/react/use-render";
 import { type VariantProps } from "class-variance-authority";
 declare const badgeVariants: (props?: ({
-    variant?: "link" | "success" | "default" | "outline" | "secondary" | "ghost" | "destructive" | "warning" | "info" | "outline-success" | "outline-warning" | "outline-info" | "outline-destructive" | "tinted-success" | "tinted-warning" | "tinted-info" | "tinted-destructive" | null | undefined;
+    variant?: "link" | "success" | "default" | "outline" | "secondary" | "ghost" | "destructive" | "info" | "warning" | "outline-success" | "outline-warning" | "outline-info" | "outline-destructive" | "tinted-success" | "tinted-warning" | "tinted-info" | "tinted-destructive" | null | undefined;
 } & import("class-variance-authority/types").ClassProp) | undefined) => string;
 declare function Badge({ className, variant, render, ...props }: useRender.ComponentProps<"span"> & VariantProps<typeof badgeVariants>): import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;
 export { Badge, badgeVariants };

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/components/ui/toggle.d.ts

@@ -0,0 +1,8 @@
+import { Toggle as TogglePrimitive } from "@base-ui/react/toggle";
+import { type VariantProps } from "class-variance-authority";
+declare const toggleVariants: (props?: ({
+    variant?: "default" | "outline" | null | undefined;
+    size?: "default" | "sm" | "lg" | "icon-xs" | "icon-sm" | null | undefined;
+} & import("class-variance-authority/types").ClassProp) | undefined) => string;
+declare function Toggle({ className, variant, size, ...props }: TogglePrimitive.Props & VariantProps<typeof toggleVariants>): import("react").JSX.Element;
+export { Toggle, toggleVariants };

package/dist/components/ui/toggle.js

@@ -0,0 +1,33 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Toggle as TogglePrimitive } from "@base-ui/react/toggle";
+import { cva } from "class-variance-authority";
+import { cn } from "cn";
+// The `icon-xs`/`icon-sm` sizes are this repo's patch to the upstream
+// primitive, matching Button's: a square toggle holding one icon, like the
+// pressed flag inside a table cell (cell pattern 15). A local patch:
+// re-running `shadcn add toggle` here would overwrite it. Diff against
+// upstream before taking a new version.
+const toggleVariants = cva("group/toggle inline-flex items-center justify-center gap-1 rounded-lg text-sm font-medium whitespace-nowrap transition-all outline-none hover:bg-muted hover:text-foreground focus-visible:border-ring focus-visible:ring-[3px] focus-visible:ring-ring/50 disabled:pointer-events-none disabled:opacity-50 aria-invalid:border-destructive aria-invalid:ring-destructive/20 aria-pressed:bg-muted data-[state=on]:bg-muted dark:aria-invalid:ring-destructive/40 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4", {
+    variants: {
+        variant: {
+            default: "bg-transparent",
+            outline: "border border-input bg-transparent hover:bg-muted",
+        },
+        size: {
+            default: "h-8 min-w-8 px-2.5 has-data-[icon=inline-end]:pr-2 has-data-[icon=inline-start]:pl-2",
+            sm: "h-7 min-w-7 rounded-[min(var(--radius-md),12px)] px-2.5 text-[0.8rem] has-data-[icon=inline-end]:pr-1.5 has-data-[icon=inline-start]:pl-1.5 [&_svg:not([class*='size-'])]:size-3.5",
+            lg: "h-9 min-w-9 px-2.5 has-data-[icon=inline-end]:pr-2 has-data-[icon=inline-start]:pl-2",
+            // 24px: the smallest target WCAG 2.2 allows (2.5.8).
+            "icon-xs": "size-6 min-w-6 rounded-[min(var(--radius-md),10px)] [&_svg:not([class*='size-'])]:size-3.5",
+            "icon-sm": "size-7 min-w-7 rounded-[min(var(--radius-md),12px)]",
+        },
+    },
+    defaultVariants: {
+        variant: "default",
+        size: "default",
+    },
+});
+function Toggle({ className, variant = "default", size = "default", ...props }) {
+    return (_jsx(TogglePrimitive, { "data-slot": "toggle", className: cn(toggleVariants({ variant, size, className })), ...props }));
+}
+export { Toggle, toggleVariants };

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

@@ -23,9 +23,22 @@ export type RecordUpdateOptions<TRecord extends {
     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
@@ -39,7 +52,7 @@ export declare function refusalReason(error: AppError, sent?: object): string;
  */
 export declare function recordUpdateMutationOptions<TRecord extends {
     id: RecordId;
-}, TUpdate extends Partial<TRecord>>(queryClient: QueryClient, { id, detailKey, listsKey, update, name }: RecordUpdateOptions<TRecord, TUpdate>): MutationOptions<TRecord, AppError, RecordChange<TRecord, TUpdate>, {
+}, 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>;
 }>;
 /**

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

@@ -21,6 +21,11 @@
 //   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();
@@ -48,7 +53,7 @@ export function refusalReason(error, sent) {
  * 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 }) {
+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);
@@ -69,7 +74,7 @@ export function recordUpdateMutationOptions(queryClient, { id, detailKey, listsK
     function render(state) {
         if (!state.confirmed)
             return;
-        const shown = state.pending.reduce((record, entry) => ({ ...record, ...resolve(entry.change, record) }), state.confirmed);
+        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)) });
     }
@@ -97,7 +102,7 @@ export function recordUpdateMutationOptions(queryClient, { id, detailKey, listsK
             let state = map.get(key);
             if (!state)
                 map.set(key, (state = { confirmed: undefined, pending: [] }));
-            const entry = { change };
+            const entry = { change, optimistic };
             state.pending.push(entry);
             // A refetch landing now would overwrite the change on screen.
             await Promise.all([
@@ -117,7 +122,8 @@ export function recordUpdateMutationOptions(queryClient, { id, detailKey, listsK
             const record = state.confirmed;
             const sent = record && resolve(context.entry.change, record);
             settle(state, context.entry);
-            toast.error(`Couldn't update ${record ? name(record) : 'this record'}: ${refusalReason(error, sent)}`);
+            if (toastOnError)
+                toast.error(`Couldn't update ${record ? name(record) : 'this record'}: ${refusalReason(error, sent)}`);
         },
         onSuccess: (saved, _change, context) => {
             const state = map.get(key);

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,7 +12,9 @@ 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 { StageCircle, type StageCircleProps, type StageCircleStage, type StageCircleTone, } from './components/app/stage-circle.js';
 export { ThemeProvider } from './components/theme-provider.js';
 export { LoginRoute, type LoginRouteProps } from './routes/login.js';
 export { RegisterRoute } from './routes/register.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,7 +17,9 @@ 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 { StageCircle, } from './components/app/stage-circle.js';
 export { ThemeProvider } from './components/theme-provider.js';
 // Screens outside the app shell
 export { LoginRoute } from './routes/login.js';