@tristan2828/ui-foundation 3.12.0 → 3.13.0

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;

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 }) }));
+}