@tristan2828/ui-foundation 3.15.0 → 3.16.1

package/conventions/docs/add-an-entity.md

@@ -104,7 +104,11 @@ is a filled-in example while the Widgets demo is still here).
    its "List" column, toolbar filters from its "Filter" column, form fields
    and labels from its field table, and field types by pattern (a
    `reference` field copies Category's searchable combobox, a
-   `single choice` copies Status's select, a `date-time` copies
+   `single choice` copies Status's select — each option shows its label,
+   never its wire value, from one `Record<value, label>`
+   (`WIDGET_STATUS_LABELS`) read by the options, the trigger (through
+   `<SelectValue>`'s children, which otherwise shows the raw value), the
+   toolbar filter and every badge — a `date-time` copies
    Available From's date picker, a `yes/no` copies In Stock — a `Switch`
    (`@tristan2828/ui-foundation/ui/switch`) in a horizontal `Field` with
    its label beside it on the form, cell pattern 12 (the word Yes/No) in

package/conventions/docs/cell-patterns.md

@@ -741,7 +741,10 @@ const price = editInPlace({
   Its keys: Ctrl/Cmd+K adds or edits a link (web and email addresses
   only), Ctrl/Cmd+Shift+Enter ticks the task item the caret is in, and
   Markdown pasted as plain text arrives formatted. Ctrl/Cmd+Enter stays
-  the save.
+  the save. A formatting toolbar sits above the text (bold to link, each
+  button naming its shortcut); it's part of the field, so moving to it
+  doesn't save. `toolbar={false}` leaves it out where a value is short
+  and the shortcuts are enough.
 - **The save is the single-field save** (`useRecordUpdate` with
   `optimistic: false, toastOnError: false`, the entity's
   `useEdit<Entity>Field`), `mutateAsync` of one field's PATCH.

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

@@ -30,7 +30,8 @@ One or two sentences: what one record is, and who uses the screens.
     `date-time`, `email`, `yes/no` (a boolean that is always yes or no:
     say its default and the filter's three labels, e.g. Any stock /
     In stock / Out of stock), `single choice` (list the options, in display
-    order; see the note below if it is *optional*), `multi choice` (list
+    order, with a label for any whose wire value isn't fit to show, as for
+    a multi choice; see the note below if it is *optional*), `multi choice` (list
     the options, with a label for any whose wire value isn't fit to show,
     e.g. `quick_win` (Quick win); any number can be picked —
     chips on the form, badges in the table, an any-of filter), `reference`

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

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

@@ -1,4 +1,4 @@
-import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } 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
@@ -22,6 +22,8 @@ import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-run
 //   in. Ctrl/Cmd+Enter stays the field's save.
 // - A placeholder in an empty document, and a count of the Markdown's
 //   length as it nears `maxLength`.
+// - A fixed toolbar above the text (rich-text-toolbar.tsx), unless
+//   `toolbar={false}`.
 import { useEffect, useId, useRef, useState } from 'react';
 import { defaultValueCtx, Editor, editorViewCtx, editorViewOptionsCtx, parserCtx, remarkStringifyOptionsCtx, rootCtx, schemaCtx, serializerCtx, } from '@milkdown/kit/core';
 import { history } from '@milkdown/kit/plugin/history';
@@ -38,6 +40,8 @@ import { Input } from '../ui/input.js';
 import { Popover, PopoverContent } from '../ui/popover.js';
 import { linkHref } from '../../lib/link-href.js';
 import { MarkdownMergeError, markdownStyle, mergeMarkdown } from '../../lib/markdown-merge.js';
+import { toggleFormat } from './rich-text-formats.js';
+import { RichTextToolbar } from './rich-text-toolbar.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;
@@ -178,11 +182,15 @@ function applyLink(view, target, href) {
     }
     view.dispatch(tr.scrollIntoView());
 }
-export default function MilkdownEditor({ id, defaultValue, onChange, onProblem, readOnly = false, autoFocus = false, placeholder, maxLength, className, 'aria-label': ariaLabel, 'aria-labelledby': ariaLabelledBy, 'aria-describedby': ariaDescribedBy, 'aria-invalid': ariaInvalid, }) {
+export default function MilkdownEditor({ id, defaultValue, onChange, onProblem, readOnly = false, autoFocus = false, placeholder, maxLength, toolbar = true, className, 'aria-label': ariaLabel, 'aria-labelledby': ariaLabelledBy, 'aria-describedby': ariaDescribedBy, 'aria-invalid': ariaInvalid, }) {
     const rootRef = useRef(null);
     const editorRef = useRef(null);
     const [linkBox, setLinkBox] = useState(null);
     const [length, setLength] = useState(defaultValue.length);
+    // The editor's state after each change, for the toolbar's pressed buttons.
+    const [editorState, setEditorState] = useState(null);
+    // Opens the link box: made with the editor, used by the toolbar's Link.
+    const openLinkRef = useRef(() => { });
     // The latest props, for the editor's callbacks, which are set up once.
     const latest = useRef({ onChange, onProblem, readOnly, placeholder });
     useEffect(() => {
@@ -190,6 +198,9 @@ export default function MilkdownEditor({ id, defaultValue, onChange, onProblem,
     });
     const ids = useId();
     const counterId = `${ids}-count`;
+    // The editable element's id: the app's, or one of its own, so the
+    // toolbar can name what it controls.
+    const editableId = id ?? `${ids}-text`;
     // The count shows from 80% of the limit: below that it's noise.
     const showCount = maxLength !== undefined && length >= maxLength * 0.8;
     const describedBy = [ariaDescribedBy, showCount ? counterId : undefined].filter(Boolean).join(' ');
@@ -198,8 +209,7 @@ export default function MilkdownEditor({ id, defaultValue, onChange, onProblem,
         'aria-readonly': String(readOnly),
         class: 'outline-none',
     };
-    if (id)
-        attributes.id = id;
+    attributes.id = editableId;
     if (ariaLabel)
         attributes['aria-label'] = ariaLabel;
     if (ariaLabelledBy)
@@ -239,6 +249,7 @@ export default function MilkdownEditor({ id, defaultValue, onChange, onProblem,
         const changes = $prose(() => new Plugin({
             view: () => ({
                 update: (view, previous) => {
+                    setEditorState(view.state);
                     if (!view.state.doc.eq(previous.doc))
                         emit();
                 },
@@ -261,6 +272,7 @@ export default function MilkdownEditor({ id, defaultValue, onChange, onProblem,
                 },
             });
         };
+        openLinkRef.current = openLink;
         // Paste, copy, the editor's own keys and the placeholder.
         const input = $prose((ctx) => new Plugin({
             props: {
@@ -348,6 +360,7 @@ export default function MilkdownEditor({ id, defaultValue, onChange, onProblem,
             }
             editorRef.current = editor;
             baseline = editor.action(getMarkdown());
+            setEditorState(editor.action((ctx) => ctx.get(editorViewCtx).state));
             if (autoFocus)
                 editor.action((ctx) => ctx.get(editorViewCtx).focus());
         });
@@ -373,18 +386,33 @@ export default function MilkdownEditor({ id, defaultValue, onChange, onProblem,
             view.setProps({ editable: () => !readOnly, attributes: JSON.parse(attributesKey) });
         });
     }, [readOnly, attributesKey]);
+    // A toolbar button: its format on the selection, then focus back in the
+    // text (Link opens the link box instead, which gives it back on close).
+    const runFormat = (format) => {
+        editorRef.current?.action((ctx) => {
+            const view = ctx.get(editorViewCtx);
+            if (format === 'link') {
+                openLinkRef.current(view);
+                return;
+            }
+            toggleFormat(view.state, view.dispatch, format);
+            view.focus();
+        });
+    };
     const closeLink = () => {
         setLinkBox(null);
         editorRef.current?.action((ctx) => ctx.get(editorViewCtx).focus());
     };
-    return (_jsxs(_Fragment, { children: [_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', 
-                // The placeholder, in an empty document only (a decoration).
-                '[&_p[data-placeholder]]:before:pointer-events-none [&_p[data-placeholder]]:before:float-left [&_p[data-placeholder]]:before:h-0 [&_p[data-placeholder]]:before:text-muted-foreground [&_p[data-placeholder]]:before:content-[attr(data-placeholder)]', className) }), showCount && (_jsx("p", { id: counterId, "data-slot": "rich-text-editor-count", className: cn('text-right type-caption tabular-nums', length > maxLength ? 'text-destructive-text' : 'text-muted-foreground'), children: length > maxLength
+    return (_jsxs(_Fragment, { children: [_jsxs("div", { "data-slot": "rich-text-editor", className: cn('flex w-full min-w-0 flex-col rounded-lg border border-input bg-transparent type-body text-foreground break-words transition-[border-color,box-shadow]', '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', className), children: [toolbar && (_jsx(RichTextToolbar, { state: editorState, readOnly: readOnly, controls: editableId, onFormat: runFormat })), _jsx("div", { ref: rootRef, className: cn('min-h-24 px-2.5 py-2', 
+                        // Read-only text is muted; the toolbar's buttons say so by being disabled.
+                        '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', 
+                        // The placeholder, in an empty document only (a decoration).
+                        '[&_p[data-placeholder]]:before:pointer-events-none [&_p[data-placeholder]]:before:float-left [&_p[data-placeholder]]:before:h-0 [&_p[data-placeholder]]:before:text-muted-foreground [&_p[data-placeholder]]:before:content-[attr(data-placeholder)]') })] }), showCount && (_jsx("p", { id: counterId, "data-slot": "rich-text-editor-count", className: cn('text-right type-caption tabular-nums', length > maxLength ? 'text-destructive-text' : 'text-muted-foreground'), children: length > maxLength
                     ? `${(length - maxLength).toLocaleString()} characters over the limit of ${maxLength.toLocaleString()}`
                     : `${length.toLocaleString()} of ${maxLength.toLocaleString()} characters` })), _jsx(Popover, { open: linkBox !== null, onOpenChange: (open) => !open && closeLink(), children: linkBox && (_jsx(LinkForm, { box: linkBox, onApply: (href) => {
                         const editor = editorRef.current;

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

@@ -18,6 +18,12 @@ export type RichTextEditorProps = {
      * Typing isn't stopped: the form's schema still refuses a save over it.
      */
     maxLength?: number;
+    /**
+     * The formatting toolbar above the text (bold, headings, lists, link, …),
+     * each button with its shortcut. On by default; `false` leaves the text
+     * alone, its shortcuts still working.
+     */
+    toolbar?: boolean;
     className?: string;
     /** The field's label. A rich-text area must have one: this, or `aria-labelledby`. */
     'aria-label'?: string;

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

@@ -21,5 +21,5 @@ 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 }) }));
+    return (_jsx(Suspense, { fallback: _jsxs("div", { "data-slot": "rich-text-editor", "data-state": "loading", className: cn('flex w-full flex-col rounded-lg border border-input', props.className), children: [props.toolbar !== false && _jsx("div", { className: "h-9 border-b border-input" }), _jsxs("div", { className: "flex min-h-24 flex-col gap-2 px-2.5 py-2", 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/rich-text-formats.d.ts

@@ -0,0 +1,12 @@
+import type { EditorState, Transaction } from '@milkdown/kit/prose/state';
+export type FormatId = 'bold' | 'italic' | 'strike' | 'code' | 'heading' | 'subheading' | 'bullets' | 'numbers' | 'tasks' | 'quote' | 'codeBlock' | 'link';
+type Dispatch = (tr: Transaction) => void;
+/** Whether a format is on where the caret is. */
+export declare function formatOn(state: EditorState, id: FormatId): boolean;
+/**
+ * Turns a format on, or off when it's already on, where the caret is.
+ * Returns false when it can't apply there. `link` isn't run here: the
+ * toolbar opens the link box for it.
+ */
+export declare function toggleFormat(state: EditorState, dispatch: Dispatch, id: FormatId): boolean;
+export {};

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

@@ -0,0 +1,125 @@
+// What the rich-text editor's toolbar can do: each format, whether it's on
+// where the caret (or the selection) is, and how to turn it on or off.
+// Plain ProseMirror commands over Milkdown's schema (commonmark + gfm), so
+// a toolbar press is one undo step, the same as its keyboard shortcut.
+import { lift, setBlockType, toggleMark, wrapIn } from '@milkdown/kit/prose/commands';
+import { liftListItem, wrapInList } from '@milkdown/kit/prose/schema-list';
+const MARKS = {
+    bold: 'strong',
+    italic: 'emphasis',
+    strike: 'strike_through',
+    code: 'inlineCode',
+    link: 'link',
+};
+function markOn(state, type) {
+    const { from, to, empty, $from } = state.selection;
+    if (empty)
+        return Boolean(type.isInSet(state.storedMarks ?? $from.marks()));
+    return state.doc.rangeHasMark(from, to, type);
+}
+// The innermost ancestor of the caret matching `test`, and its position.
+function ancestor(state, test) {
+    const { $from } = state.selection;
+    for (let depth = $from.depth; depth > 0; depth--) {
+        const node = $from.node(depth);
+        if (test(node))
+            return { node, pos: $from.before(depth) };
+    }
+    return null;
+}
+const isList = (node) => node.type.name === 'bullet_list' || node.type.name === 'ordered_list';
+/** Whether a format is on where the caret is. */
+export function formatOn(state, id) {
+    const { schema } = state;
+    const mark = MARKS[id];
+    if (mark)
+        return markOn(state, schema.marks[mark]);
+    const parent = state.selection.$from.parent;
+    switch (id) {
+        case 'heading':
+        case 'subheading':
+            return parent.type.name === 'heading' && parent.attrs.level === (id === 'heading' ? 1 : 2);
+        case 'codeBlock':
+            return parent.type.name === 'code_block';
+        case 'quote':
+            return ancestor(state, (node) => node.type.name === 'blockquote') !== null;
+        default: {
+            const list = ancestor(state, isList);
+            const item = ancestor(state, (node) => node.type.name === 'list_item');
+            if (!list || !item)
+                return false;
+            const task = item.node.attrs.checked != null;
+            if (id === 'tasks')
+                return task;
+            if (id === 'numbers')
+                return list.node.type.name === 'ordered_list';
+            return list.node.type.name === 'bullet_list' && !task;
+        }
+    }
+}
+// The list the caret is in, turned into `type`, every item a task item or
+// none (`checked`: false for a task, null for not).
+function convertList(tr, type, checked) {
+    const $from = tr.selection.$from;
+    for (let depth = $from.depth; depth > 0; depth--) {
+        const node = $from.node(depth);
+        if (!isList(node))
+            continue;
+        const pos = $from.before(depth);
+        tr.setNodeMarkup(pos, type);
+        node.forEach((item, offset) => {
+            const itemPos = pos + 1 + offset;
+            const keep = checked === false && item.attrs.checked != null ? item.attrs.checked : checked;
+            tr.setNodeMarkup(itemPos, undefined, {
+                ...item.attrs,
+                checked: keep,
+                listType: type.name === 'ordered_list' ? 'ordered' : 'bullet',
+            });
+        });
+        return tr;
+    }
+    return tr;
+}
+/**
+ * Turns a format on, or off when it's already on, where the caret is.
+ * Returns false when it can't apply there. `link` isn't run here: the
+ * toolbar opens the link box for it.
+ */
+export function toggleFormat(state, dispatch, id) {
+    const { schema } = state;
+    const mark = MARKS[id];
+    if (mark && id !== 'link')
+        return toggleMark(schema.marks[mark])(state, dispatch);
+    const on = formatOn(state, id);
+    const paragraph = schema.nodes.paragraph;
+    switch (id) {
+        case 'heading':
+        case 'subheading':
+            return on
+                ? setBlockType(paragraph)(state, dispatch)
+                : setBlockType(schema.nodes.heading, { level: id === 'heading' ? 1 : 2 })(state, dispatch);
+        case 'codeBlock':
+            return on ? setBlockType(paragraph)(state, dispatch) : setBlockType(schema.nodes.code_block)(state, dispatch);
+        case 'quote':
+            return on ? lift(state, dispatch) : wrapIn(schema.nodes.blockquote)(state, dispatch);
+        case 'bullets':
+        case 'numbers':
+        case 'tasks': {
+            if (on)
+                return liftListItem(schema.nodes.list_item)(state, dispatch);
+            const type = id === 'numbers' ? schema.nodes.ordered_list : schema.nodes.bullet_list;
+            const checked = id === 'tasks' ? false : null;
+            if (ancestor(state, isList)) {
+                dispatch(convertList(state.tr, type, checked));
+                return true;
+            }
+            let wrapped = null;
+            if (!wrapInList(type)(state, (tr) => (wrapped = tr)))
+                return false;
+            dispatch(convertList(wrapped, type, checked));
+            return true;
+        }
+        default:
+            return false;
+    }
+}

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

@@ -0,0 +1,12 @@
+import type { EditorState } from '@milkdown/kit/prose/state';
+import { type FormatId } from './rich-text-formats.js';
+export interface RichTextToolbarProps {
+    /** The editor's state now, to show which formats are on. Null until it's made. */
+    state: EditorState | null;
+    readOnly: boolean;
+    /** The editable element's id, for `aria-controls`. */
+    controls?: string;
+    /** A button pressed: run the format on the editor and give it focus back. */
+    onFormat: (id: FormatId) => void;
+}
+export declare function RichTextToolbar({ state, readOnly, controls, onFormat }: RichTextToolbarProps): import("react").JSX.Element;

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

@@ -0,0 +1,98 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// The rich-text editor's fixed toolbar: one row of pressed/not-pressed
+// buttons above the text, each a format and its keyboard shortcut.
+//
+// - One tab stop (ARIA's toolbar pattern): Tab reaches the last button
+//   used, the arrow keys, Home and End move along the row.
+// - A press acts on the editor's selection and gives focus back to the
+//   text; a mouse press never takes focus from it, so the selection stays.
+// - Each button says whether its format is on where the caret is
+//   (`aria-pressed`), and names its shortcut (`aria-keyshortcuts`, and the
+//   tooltip).
+// - Read-only (while a save is in flight), every button is disabled.
+import { BoldIcon, CodeIcon, Heading1Icon, Heading2Icon, ItalicIcon, LinkIcon, ListChecksIcon, ListIcon, ListOrderedIcon, SquareCodeIcon, StrikethroughIcon, TextQuoteIcon, } from 'lucide-react';
+import { Fragment, useRef, useState } from 'react';
+import { Separator } from '../ui/separator.js';
+import { Toggle } from '../ui/toggle.js';
+import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from '../ui/tooltip.js';
+import { formatOn } from './rich-text-formats.js';
+const GROUPS = [
+    [
+        { id: 'bold', label: 'Bold', icon: BoldIcon, keys: 'Mod+B' },
+        { id: 'italic', label: 'Italic', icon: ItalicIcon, keys: 'Mod+I' },
+        { id: 'strike', label: 'Strikethrough', icon: StrikethroughIcon, keys: 'Mod+Alt+X' },
+        { id: 'code', label: 'Code', icon: CodeIcon, keys: 'Mod+E' },
+    ],
+    [
+        { id: 'heading', label: 'Heading', icon: Heading1Icon, keys: 'Mod+Alt+1' },
+        { id: 'subheading', label: 'Subheading', icon: Heading2Icon, keys: 'Mod+Alt+2' },
+    ],
+    [
+        { id: 'bullets', label: 'Bulleted list', icon: ListIcon, keys: 'Mod+Alt+8' },
+        { id: 'numbers', label: 'Numbered list', icon: ListOrderedIcon, keys: 'Mod+Alt+7' },
+        { id: 'tasks', label: 'Task list', icon: ListChecksIcon, hint: 'tick an item: Mod+Shift+Enter' },
+    ],
+    [
+        { id: 'quote', label: 'Quote', icon: TextQuoteIcon, keys: 'Mod+Shift+B' },
+        { id: 'codeBlock', label: 'Code block', icon: SquareCodeIcon, keys: 'Mod+Alt+C' },
+    ],
+    [{ id: 'link', label: 'Link', icon: LinkIcon, keys: 'Mod+K' }],
+];
+const ITEMS = GROUPS.flat();
+function isApple() {
+    return typeof navigator !== 'undefined' && /Mac|iPhone|iPad/.test(navigator.platform || navigator.userAgent);
+}
+// `aria-keyshortcuts` names real keys: Meta on Apple, Control elsewhere.
+function ariaKeys(keys, apple) {
+    return keys.replace('Mod', apple ? 'Meta' : 'Control');
+}
+// What a person reads: ⌘⌥X on Apple, Ctrl+Alt+X elsewhere.
+function shownKeys(keys, apple) {
+    if (!apple)
+        return keys.replace('Mod', 'Ctrl');
+    const symbols = { Mod: '⌘', Alt: '⌥', Shift: '⇧', Enter: '↵' };
+    return keys
+        .split('+')
+        .map((part) => symbols[part] ?? part)
+        .join('');
+}
+export function RichTextToolbar({ state, readOnly, controls, onFormat }) {
+    const apple = isApple();
+    const buttons = useRef([]);
+    // The one button Tab reaches: the last one used.
+    const [current, setCurrent] = useState(0);
+    const move = (index) => {
+        const next = (index + ITEMS.length) % ITEMS.length;
+        setCurrent(next);
+        buttons.current[next]?.focus();
+    };
+    const onKeyDown = (event) => {
+        const keys = {
+            ArrowRight: () => move(current + 1),
+            ArrowLeft: () => move(current - 1),
+            Home: () => move(0),
+            End: () => move(ITEMS.length - 1),
+        };
+        const action = keys[event.key];
+        if (!action || event.metaKey || event.ctrlKey || event.altKey)
+            return;
+        event.preventDefault();
+        action();
+    };
+    return (_jsx(TooltipProvider, { delay: 400, children: _jsx("div", { role: "toolbar", "aria-label": "Formatting", "aria-controls": controls, "data-slot": "rich-text-toolbar", className: "flex flex-wrap items-center gap-0.5 border-b border-input px-1 py-1", onKeyDown: onKeyDown, children: GROUPS.map((group, groupIndex) => (_jsxs(Fragment, { children: [groupIndex > 0 && _jsx(Separator, { orientation: "vertical", className: "mx-1 h-5 self-center" }), group.map((item) => {
+                        const index = ITEMS.indexOf(item);
+                        const Icon = item.icon;
+                        const tip = [
+                            item.label,
+                            item.keys && `(${shownKeys(item.keys, apple)})`,
+                            item.hint && `· ${item.hint.replace(/Mod\+Shift\+Enter/, shownKeys('Mod+Shift+Enter', apple))}`,
+                        ]
+                            .filter(Boolean)
+                            .join(' ');
+                        return (_jsxs(Tooltip, { children: [_jsx(TooltipTrigger, { render: _jsx(Toggle, { ref: (element) => {
+                                            buttons.current[index] = element;
+                                        }, size: "icon-sm", "aria-label": item.label, "aria-keyshortcuts": item.keys ? ariaKeys(item.keys, apple) : undefined, pressed: state ? formatOn(state, item.id) : false, disabled: readOnly, tabIndex: index === current ? 0 : -1, className: "aria-pressed:bg-muted aria-pressed:text-foreground", 
+                                        // A mouse press keeps focus, and the selection, in the text.
+                                        onMouseDown: (event) => event.preventDefault(), onFocus: () => setCurrent(index), onPressedChange: () => onFormat(item.id) }), children: _jsx(Icon, {}) }), _jsx(TooltipContent, { children: tip })] }, item.id));
+                    })] }, groupIndex))) }) }));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tristan2828/ui-foundation",
-  "version": "3.15.0",
+  "version": "3.16.1",
   "description": "Shared UI foundation for contract-first, database-backed React apps: shadcn primitives, DataTable/EntityForm composites, auth, the gateway error seam, design tokens, lint rules and the AI playbook.",
   "license": "MIT",
   "repository": {