@tristan2828/ui-foundation 3.16.2 → 3.18.0

package/conventions/docs/cell-patterns.md

@@ -742,9 +742,15 @@ const price = editInPlace({
   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. 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.
+  button naming its shortcut), and a smaller one floats over selected
+  words (bold, italic, strikethrough, code, link); Alt+F10 reaches the
+  floating one, else the fixed one. Both are part of the field, so moving
+  to them doesn't save, and Esc hides the floating one before it gives up
+  the edit. "/" typed at a line's start lists the blocks the line can
+  become (headings, lists, quote, code block); typing filters, Enter or
+  Tab picks, and Esc closes the list before it gives up the edit.
+  `toolbar={false}` leaves out the toolbars and the slash menu 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/dist/components/app/milkdown-editor.js

@@ -22,7 +22,12 @@ import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } 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
+// - A fixed toolbar above the text (rich-text-toolbar.tsx), and a
+//   floating one over selected words (rich-text-floating-toolbar.tsx),
+//   unless `toolbar={false}`. Alt+F10 reaches the floating one when it
+//   shows, else the fixed one.
+// - A slash menu (rich-text-slash.ts, rich-text-slash-menu.tsx): "/" at a
+//   line's start lists the blocks it can become, also unless
 //   `toolbar={false}`.
 import { useEffect, useId, useRef, useState } from 'react';
 import { defaultValueCtx, Editor, editorViewCtx, editorViewOptionsCtx, parserCtx, remarkStringifyOptionsCtx, rootCtx, schemaCtx, serializerCtx, } from '@milkdown/kit/core';
@@ -30,7 +35,7 @@ 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 { NodeSelection, Plugin } from '@milkdown/kit/prose/state';
 import { Decoration, DecorationSet } from '@milkdown/kit/prose/view';
 import { $prose, getMarkdown } from '@milkdown/kit/utils';
 import { cn } from 'cn';
@@ -40,7 +45,10 @@ 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 { RichTextFloatingToolbar } from './rich-text-floating-toolbar.js';
 import { toggleFormat } from './rich-text-formats.js';
+import { applySlash, closeSlash, slashItems, slashOptionId, slashPlugin, slashQuery, } from './rich-text-slash.js';
+import { RichTextSlashMenu } from './rich-text-slash-menu.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`.
@@ -189,6 +197,24 @@ export default function MilkdownEditor({ id, defaultValue, onChange, onProblem,
     const [length, setLength] = useState(defaultValue.length);
     // The editor's state after each change, for the toolbar's pressed buttons.
     const [editorState, setEditorState] = useState(null);
+    const [editorView, setEditorView] = useState(null);
+    // For the floating toolbar: focus is in the text (or on the floating
+    // toolbar), the mouse is down choosing words, and the selection Esc hid
+    // it for.
+    const [focused, setFocused] = useState(false);
+    const [selecting, setSelecting] = useState(false);
+    const [dismissed, setDismissed] = useState(null);
+    const toolbarRef = useRef(null);
+    const floatingRef = useRef(null);
+    // The field's element, which the floating toolbar is placed against.
+    const [field, setField] = useState(null);
+    // Whether the floating toolbar shows, for the editor's keys (set up once).
+    const floatingOpenRef = useRef(false);
+    // The slash menu's highlighted item, for the query it was moved on (a
+    // new query starts again from the first).
+    const [slashActive, setSlashActive] = useState({ key: '', index: 0 });
+    // The open slash menu, for the editor's keys (set up once).
+    const slashMenuRef = useRef(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.
@@ -220,6 +246,23 @@ export default function MilkdownEditor({ id, defaultValue, onChange, onProblem,
         attributes['aria-invalid'] = 'true';
     if (placeholder)
         attributes['aria-placeholder'] = placeholder;
+    if (toolbar)
+        attributes['aria-keyshortcuts'] = 'Alt+F10';
+    // The slash menu: open while a "/" typed at a line's start is followed
+    // by something some block answers to, and the field has focus.
+    const slash = toolbar && !readOnly && focused && editorState ? slashQuery(editorState) : null;
+    const slashMatches = slash ? slashItems(slash.query) : [];
+    const slashOpen = slash !== null && slashMatches.length > 0;
+    const slashMenuKey = slash ? `${slash.from}:${slash.query}` : '';
+    const slashIndex = slashActive.key === slashMenuKey ? Math.min(slashActive.index, slashMatches.length - 1) : 0;
+    const slashListId = `${ids}-blocks`;
+    // The text is the combobox's input: it names the list and the
+    // highlighted item, and focus stays in it.
+    if (slashOpen) {
+        attributes['aria-autocomplete'] = 'list';
+        attributes['aria-controls'] = slashListId;
+        attributes['aria-activedescendant'] = slashOptionId(slashListId, slashIndex);
+    }
     const attributesKey = JSON.stringify(attributes);
     // The editor is made once, from the Markdown it opened with.
     useEffect(() => {
@@ -252,6 +295,9 @@ export default function MilkdownEditor({ id, defaultValue, onChange, onProblem,
                     if (cancelled)
                         return;
                     setEditorState(view.state);
+                    // Esc hides the floating toolbar for one selection only.
+                    if (view.state.selection.empty)
+                        setDismissed(null);
                     if (!view.state.doc.eq(previous.doc))
                         emit();
                 },
@@ -276,6 +322,7 @@ export default function MilkdownEditor({ id, defaultValue, onChange, onProblem,
         };
         openLinkRef.current = openLink;
         // Paste, copy, the editor's own keys and the placeholder.
+        const slashing = $prose(() => slashPlugin());
         const input = $prose((ctx) => new Plugin({
             props: {
                 // Plain text is read as Markdown, so `## Notes` or `**bold**`
@@ -310,7 +357,49 @@ export default function MilkdownEditor({ id, defaultValue, onChange, onProblem,
                         : null;
                     return doc ? ctx.get(serializerCtx)(doc) : slice.content.textBetween(0, slice.content.size, '\n\n');
                 },
+                handleDOMEvents: {
+                    focus: () => {
+                        setFocused(true);
+                        return false;
+                    },
+                    // Moving to the floating toolbar keeps it showing.
+                    blur: (_view, event) => {
+                        if (!floatingRef.current?.contains(event.relatedTarget))
+                            setFocused(false);
+                        return false;
+                    },
+                    // The floating toolbar waits for the mouse to be up: a drag
+                    // is still choosing the words.
+                    mousedown: (_view, event) => {
+                        if (event.button !== 0)
+                            return false;
+                        setDismissed(null);
+                        setSelecting(true);
+                        window.addEventListener('mouseup', () => setSelecting(false), { once: true });
+                        return false;
+                    },
+                },
                 handleKeyDown: (view, event) => {
+                    setSelecting(false);
+                    // Alt+F10: to the floating toolbar when it shows, else the
+                    // fixed one (the convention editors share).
+                    if (event.altKey && event.key === 'F10') {
+                        const bar = floatingOpenRef.current ? floatingRef.current : toolbarRef.current;
+                        const button = bar?.querySelector('button[tabindex="0"]');
+                        if (!button)
+                            return false;
+                        event.preventDefault();
+                        button.focus();
+                        return true;
+                    }
+                    // Esc hides the floating toolbar first; only the next one
+                    // reaches the field (editing in place gives up on it).
+                    if (event.key === 'Escape' && floatingOpenRef.current) {
+                        event.preventDefault();
+                        const { from, to } = view.state.selection;
+                        setDismissed({ from, to });
+                        return true;
+                    }
                     const mod = event.metaKey || event.ctrlKey;
                     if (mod && !event.shiftKey && !event.altKey && event.key.toLowerCase() === 'k') {
                         event.preventDefault();
@@ -344,6 +433,34 @@ export default function MilkdownEditor({ id, defaultValue, onChange, onProblem,
                 ...options,
                 editable: () => !latest.current.readOnly,
                 attributes,
+                // The slash menu's keys, as view props: before Milkdown's own
+                // keymap, whose Enter would split the line.
+                handleKeyDown: (view, event) => {
+                    const menu = slashMenuRef.current;
+                    if (!menu)
+                        return false;
+                    const step = event.key === 'ArrowDown' ? 1 : event.key === 'ArrowUp' ? -1 : 0;
+                    const plain = !event.metaKey && !event.ctrlKey && !event.altKey && !event.shiftKey;
+                    if (step && plain) {
+                        event.preventDefault();
+                        const count = menu.items.length;
+                        setSlashActive({ key: menu.key, index: (menu.index + step + count) % count });
+                        return true;
+                    }
+                    if ((event.key === 'Enter' || event.key === 'Tab') && plain) {
+                        event.preventDefault();
+                        applySlash(view, menu.span, menu.items[menu.index].id);
+                        return true;
+                    }
+                    // Esc closes the menu only: the field's own Esc (editing in
+                    // place gives up the edit) waits for the next one.
+                    if (event.key === 'Escape') {
+                        event.preventDefault();
+                        view.dispatch(closeSlash(view.state));
+                        return true;
+                    }
+                    return false;
+                },
                 nodeViews: {
                     heading: headingView,
                     list_item: (node, view, getPos) => node.attrs.checked == null ? undefined : taskItemView(node, view, getPos),
@@ -354,6 +471,7 @@ export default function MilkdownEditor({ id, defaultValue, onChange, onProblem,
             .use(gfm)
             .use(history)
             .use(changes)
+            .use(slashing)
             .use(input);
         void make.create().then((editor) => {
             if (cancelled) {
@@ -362,13 +480,16 @@ export default function MilkdownEditor({ id, defaultValue, onChange, onProblem,
             }
             editorRef.current = editor;
             baseline = editor.action(getMarkdown());
-            setEditorState(editor.action((ctx) => ctx.get(editorViewCtx).state));
+            const view = editor.action((ctx) => ctx.get(editorViewCtx));
+            setEditorView(view);
+            setEditorState(view.state);
             if (autoFocus)
                 editor.action((ctx) => ctx.get(editorViewCtx).focus());
         });
         return () => {
             cancelled = true;
             setEditorState(null);
+            setEditorView(null);
             const editor = editorRef.current;
             editorRef.current = null;
             if (editor)
@@ -402,11 +523,32 @@ export default function MilkdownEditor({ id, defaultValue, onChange, onProblem,
             view.focus();
         });
     };
+    // The floating toolbar: words selected, focus in the field, the mouse up,
+    // and nothing else open over the text.
+    const selection = editorState?.selection;
+    const floatingOpen = Boolean(toolbar &&
+        !readOnly &&
+        editorView &&
+        focused &&
+        !selecting &&
+        linkBox === null &&
+        selection &&
+        !selection.empty &&
+        !(selection instanceof NodeSelection) &&
+        !selection.$from.parent.type.spec.code &&
+        !(dismissed && dismissed.from === selection.from && dismissed.to === selection.to));
+    useEffect(() => {
+        floatingOpenRef.current = floatingOpen;
+    });
+    const returnToText = () => editorView?.focus();
+    useEffect(() => {
+        slashMenuRef.current = slashOpen && slash ? { key: slashMenuKey, span: slash, items: slashMatches, index: slashIndex } : null;
+    });
     const closeLink = () => {
         setLinkBox(null);
         editorRef.current?.action((ctx) => ctx.get(editorViewCtx).focus());
     };
-    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, 
+    return (_jsxs(_Fragment, { children: [_jsxs("div", { ref: setField, "data-slot": "rich-text-editor", className: cn('relative 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, { ref: toolbarRef, state: editorState, readOnly: readOnly, 
                         // Only once the editor is made: until then the editable element,
                         // and its id, aren't in the page (axe: aria-valid-attr-value).
                         controls: editorState ? editableId : undefined, onFormat: runFormat })), _jsx("div", { ref: rootRef, className: cn('min-h-24 px-2.5 py-2', 
@@ -421,7 +563,11 @@ export default function MilkdownEditor({ id, defaultValue, onChange, onProblem,
                         // 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
+                        '[&_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)]') }), slashOpen && slash && editorView && (_jsx(RichTextSlashMenu, { id: slashListId, view: editorView, at: slash.to, field: field, items: slashMatches, active: slashIndex, onHighlight: (index) => setSlashActive({ key: slashMenuKey, index }), onPick: (format) => applySlash(editorView, slash, format) })), floatingOpen && editorView && editorState && (_jsx(RichTextFloatingToolbar, { ref: floatingRef, view: editorView, state: editorState, field: field, controls: editableId, onFormat: runFormat, onDismiss: () => setDismissed({ from: editorState.selection.from, to: editorState.selection.to }), onReturn: returnToText, onBlur: (event) => {
+                            const next = event.relatedTarget;
+                            if (!editorView.dom.contains(next) && !floatingRef.current?.contains(next))
+                                setFocused(false);
+                        } }))] }), 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

@@ -19,9 +19,12 @@ export type RichTextEditorProps = {
      */
     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.
+     * The formatting toolbars: one fixed above the text (bold, headings,
+     * lists, link, …), each button with its shortcut, and one floating over
+     * selected words (bold to link). Alt+F10 reaches them from the text.
+     * With them, "/" at a line's start lists the blocks the line can become
+     * (the slash menu). On by default; `false` leaves the text alone, its
+     * shortcuts still working.
      */
     toolbar?: boolean;
     className?: string;

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

@@ -0,0 +1,25 @@
+import { type FocusEvent, type Ref } from 'react';
+import type { EditorState } from '@milkdown/kit/prose/state';
+import type { EditorView } from '@milkdown/kit/prose/view';
+import type { FormatId } from './rich-text-formats.js';
+export interface RichTextFloatingToolbarProps {
+    /** The editor, to measure the selection. */
+    view: EditorView;
+    /** The editor's state now: the selection, and which formats are on. */
+    state: EditorState;
+    /** The field's element it's placed against (positioned: `relative`). */
+    field: HTMLElement | null;
+    /** 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;
+    /** Esc: hide it until the selection changes. */
+    onDismiss: () => void;
+    /** Esc or Tab: focus back to the text. */
+    onReturn: () => void;
+    /** Focus leaving one of its buttons, for the editor to tell whether it left the field. */
+    onBlur: (event: FocusEvent) => void;
+    /** Its element, for Alt+F10 to reach it and for the editor's own blur. */
+    ref?: Ref<HTMLDivElement>;
+}
+export declare function RichTextFloatingToolbar({ view, state, field, controls, onFormat, onDismiss, onReturn, onBlur, ref, }: RichTextFloatingToolbarProps): import("react").JSX.Element;

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

@@ -0,0 +1,92 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+// The rich-text editor's floating toolbar: the formats for selected words
+// (Bold, Italic, Strikethrough, Code · Link), over the selection. The
+// fixed toolbar (rich-text-toolbar.tsx) stays; this one saves the trip up
+// to it. The editor decides when it shows (milkdown-editor.tsx):
+//
+// - While words are selected in the text and the field has focus, once
+//   the mouse is up (not while a drag is still choosing them). Not in a
+//   code block (no formats apply there), read-only, or with the link box
+//   open.
+// - Above the selection, or below it when there's no room for it inside
+//   the text (the first line), so it never covers the fixed toolbar.
+// - A mouse press never takes focus from the text, as on the fixed one.
+// - Keyboard: Alt+F10 in the text reaches it; the arrow keys, Home and
+//   End move along it (one tab stop, as on the fixed one); Esc or Tab goes
+//   back to the text, the selection kept. Esc (here or in the text) hides
+//   it until the selection changes.
+//
+// It sits inside the field's own element, placed against it, not in a
+// portal: it scrolls with the text, is part of the field for editing in
+// place and inside a dialog, and needs none of a popover's focus guards
+// (Base UI's Popover adds tabbable `aria-hidden` guards while focus is
+// outside it, which for this toolbar is always, and axe fails them).
+import { useLayoutEffect, useState } from 'react';
+import { cn } from 'cn';
+import { FormatButtons } from './rich-text-toolbar.js';
+// Its gap from the words.
+const GAP = 8;
+// The selection's box on screen: the words themselves on one line, the
+// text's width over several.
+function selectionRect(view, from, to) {
+    const size = view.state.doc.content.size;
+    const start = view.coordsAtPos(Math.min(from, size), 1);
+    const end = view.coordsAtPos(Math.min(to, size), -1);
+    const top = Math.min(start.top, end.top);
+    const bottom = Math.max(start.bottom, end.bottom);
+    if (end.top < start.bottom)
+        return new DOMRect(Math.min(start.left, end.left), top, Math.abs(end.left - start.left), bottom - top);
+    const text = view.dom.getBoundingClientRect();
+    return new DOMRect(text.left, top, text.width, bottom - top);
+}
+// Where it goes, against `field` (its positioned parent): centred over
+// the words, below them when there's no room above inside the text, and
+// never past the field's sides.
+function place(view, from, to, field, bar) {
+    const words = selectionRect(view, from, to);
+    const box = field.getBoundingClientRect();
+    const text = view.dom.getBoundingClientRect();
+    const { offsetWidth: width, offsetHeight: height } = bar;
+    const above = words.top - height - GAP >= text.top;
+    const top = above ? words.top - height - GAP : words.bottom + GAP;
+    const centre = words.left + words.width / 2 - width / 2;
+    const left = Math.max(0, Math.min(centre - box.left, box.width - width));
+    return { top: top - box.top, left, side: above ? 'top' : 'bottom' };
+}
+export function RichTextFloatingToolbar({ view, state, field, controls, onFormat, onDismiss, onReturn, onBlur, ref, }) {
+    const [bar, setBar] = useState(null);
+    const [placement, setPlacement] = useState(null);
+    const { from, to } = state.selection;
+    // Placed after each change (a mark makes the words wider), and again
+    // when the window's width reflows the text.
+    useLayoutEffect(() => {
+        if (!bar || !field)
+            return;
+        const update = () => setPlacement(place(view, from, to, field, bar));
+        update();
+        window.addEventListener('resize', update);
+        return () => window.removeEventListener('resize', update);
+    }, [view, state, from, to, field, bar]);
+    const onKeyDown = (event) => {
+        if (event.key === 'Escape') {
+            // Its own: not the field's (editing in place would give up the edit).
+            event.preventDefault();
+            event.stopPropagation();
+            onDismiss();
+            onReturn();
+        }
+        else if (event.key === 'Tab') {
+            event.preventDefault();
+            onReturn();
+        }
+    };
+    return (_jsx("div", { ref: (element) => {
+            setBar(element);
+            if (typeof ref === 'function')
+                ref(element);
+            else if (ref)
+                ref.current = element;
+        }, role: "toolbar", "aria-label": "Format selection", "aria-controls": controls, "data-slot": "rich-text-floating-toolbar", "data-side": placement?.side, style: placement ? { top: placement.top, left: placement.left } : undefined, className: cn('absolute z-50 flex items-center gap-0.5 rounded-lg bg-popover p-1 text-popover-foreground shadow-md ring-1 ring-foreground/10', 'animate-in fade-in-0 zoom-in-95 duration-100 data-[side=bottom]:slide-in-from-top-2 data-[side=top]:slide-in-from-bottom-2', 
+        // Measured before it's seen, so it never shows in the wrong place.
+        !placement && 'invisible'), onKeyDown: onKeyDown, onBlur: onBlur, children: _jsx(FormatButtons, { formats: "selection", state: state, readOnly: false, onFormat: onFormat }) }));
+}

package/dist/components/app/rich-text-format-items.d.ts

@@ -0,0 +1,12 @@
+import { type LucideIcon } from 'lucide-react';
+import type { FormatId } from './rich-text-formats.js';
+export type FormatItem = {
+    id: FormatId;
+    label: string;
+    icon: LucideIcon;
+    /** Milkdown's own shortcut, as `aria-keyshortcuts` writes it with Mod for Ctrl/Cmd. */
+    keys?: string;
+    /** More for the tooltip than the shortcut. */
+    hint?: string;
+};
+export declare const FORMAT_GROUPS: FormatItem[][];

package/dist/components/app/rich-text-format-items.js

@@ -0,0 +1,27 @@
+// The rich-text editor's formats as people see them: each one's name, icon
+// and shortcut, in the groups the fixed toolbar shows. Shared by the
+// toolbars (rich-text-toolbar.tsx) and the slash menu
+// (rich-text-slash-menu.tsx).
+import { BoldIcon, CodeIcon, Heading1Icon, Heading2Icon, ItalicIcon, LinkIcon, ListChecksIcon, ListIcon, ListOrderedIcon, SquareCodeIcon, StrikethroughIcon, TextQuoteIcon, } from 'lucide-react';
+export const FORMAT_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' }],
+];

package/dist/components/app/rich-text-slash-menu.d.ts

@@ -0,0 +1,18 @@
+import type { EditorView } from '@milkdown/kit/prose/view';
+import type { FormatItem } from './rich-text-format-items.js';
+import type { FormatId } from './rich-text-formats.js';
+export interface RichTextSlashMenuProps {
+    /** The list's id, for the text's `aria-controls`. */
+    id: string;
+    view: EditorView;
+    /** The caret: where it's placed. */
+    at: number;
+    /** The field's element it's placed against (positioned: `relative`). */
+    field: HTMLElement | null;
+    items: FormatItem[];
+    /** The highlighted item: Enter picks it. */
+    active: number;
+    onHighlight: (index: number) => void;
+    onPick: (id: FormatId) => void;
+}
+export declare function RichTextSlashMenu({ id, view, at, field, items, active, onHighlight, onPick }: RichTextSlashMenuProps): import("react").JSX.Element;

package/dist/components/app/rich-text-slash-menu.js

@@ -0,0 +1,52 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// The rich-text editor's slash menu: the blocks a paragraph can become
+// (Heading to Code block), listed under the caret after a "/" typed at a
+// line's start (rich-text-slash.ts). ARIA's combobox pattern with the
+// text as the input: focus never leaves the text. The text names this
+// list (`aria-controls`) and the highlighted item
+// (`aria-activedescendant`); the arrow keys move the highlight, Enter or
+// Tab picks, Esc closes it and leaves what was typed (milkdown-editor.tsx).
+//
+// Placed against the field's element like the floating toolbar, not in a
+// portal (rich-text-floating-toolbar.tsx says why): under the caret, or
+// over it when the window has no room below.
+import { useLayoutEffect, useState } from 'react';
+import { cn } from 'cn';
+import { slashOptionId } from './rich-text-slash.js';
+// Its gap from the caret's line.
+const GAP = 4;
+function place(view, at, field, menu) {
+    const caret = view.coordsAtPos(at);
+    const box = field.getBoundingClientRect();
+    const { offsetWidth: width, offsetHeight: height } = menu;
+    const below = caret.bottom + GAP + height <= window.innerHeight || caret.top - GAP - height < 0;
+    const top = below ? caret.bottom + GAP : caret.top - GAP - height;
+    const left = Math.max(0, Math.min(caret.left - box.left, box.width - width));
+    return { top: top - box.top, left, side: below ? 'bottom' : 'top' };
+}
+export function RichTextSlashMenu({ id, view, at, field, items, active, onHighlight, onPick }) {
+    const [menu, setMenu] = useState(null);
+    const [placement, setPlacement] = useState(null);
+    // Placed as the caret moves and the list narrows, and again when the
+    // window's size changes.
+    useLayoutEffect(() => {
+        if (!menu || !field)
+            return;
+        const update = () => setPlacement(place(view, at, field, menu));
+        update();
+        window.addEventListener('resize', update);
+        return () => window.removeEventListener('resize', update);
+    }, [view, at, field, menu, items.length]);
+    // The highlighted item stays in sight.
+    useLayoutEffect(() => {
+        menu?.querySelector(`#${CSS.escape(slashOptionId(id, active))}`)?.scrollIntoView({ block: 'nearest' });
+    }, [menu, id, active]);
+    return (_jsx("div", { ref: setMenu, id: id, role: "listbox", "aria-label": "Blocks", "data-slot": "rich-text-slash-menu", "data-side": placement?.side, style: placement ? { top: placement.top, left: placement.left } : undefined, className: cn('absolute z-50 flex max-h-72 w-56 flex-col gap-0.5 overflow-y-auto rounded-lg bg-popover p-1 text-sm text-popover-foreground shadow-md ring-1 ring-foreground/10', 'animate-in fade-in-0 zoom-in-95 duration-100 data-[side=bottom]:slide-in-from-top-2 data-[side=top]:slide-in-from-bottom-2', 
+        // Measured before it's seen, so it never shows in the wrong place.
+        !placement && 'invisible'), children: items.map((item, index) => {
+            const Icon = item.icon;
+            return (_jsxs("div", { id: slashOptionId(id, index), role: "option", "aria-selected": index === active, className: "flex cursor-default items-center gap-2 rounded-md px-2 py-1.5 select-none aria-selected:bg-muted", 
+                // A press never takes focus from the text.
+                onMouseDown: (event) => event.preventDefault(), onMouseMove: () => index !== active && onHighlight(index), onClick: () => onPick(item.id), children: [_jsx(Icon, { "aria-hidden": "true", className: "size-4 shrink-0" }), item.label] }, item.id));
+        }) }));
+}

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

@@ -0,0 +1,30 @@
+import { Plugin, type EditorState, type Transaction } from '@milkdown/kit/prose/state';
+import type { EditorView } from '@milkdown/kit/prose/view';
+import { type FormatItem } from './rich-text-format-items.js';
+import { type FormatId } from './rich-text-formats.js';
+/** Where the "/" that opened the menu is, while it's open. */
+type SlashState = {
+    from: number;
+} | null;
+/** The open menu's span in the text ("/" to the caret) and what's typed after the "/". */
+export type SlashQuery = {
+    from: number;
+    to: number;
+    query: string;
+};
+/** The open menu's span and query, or null when it's closed. */
+export declare function slashQuery(state: EditorState): SlashQuery | null;
+/** The transaction that closes the menu, leaving what was typed as text (Esc). */
+export declare function closeSlash(state: EditorState): Transaction;
+/** The id of the menu's item at `index`, for the text's `aria-activedescendant`. */
+export declare function slashOptionId(listId: string, index: number): string;
+/** The plugin: opens on a typed "/", follows the text, closes once the span stops qualifying. */
+export declare function slashPlugin(): Plugin<SlashState>;
+/** The blocks matching what's typed after the "/": in the name, or the start of a keyword. */
+export declare function slashItems(query: string): FormatItem[];
+/**
+ * Picks an item: the "/…" goes and the paragraph becomes that block, in one
+ * transaction (one undo step, which brings the "/…" back).
+ */
+export declare function applySlash(view: EditorView, span: SlashQuery, id: FormatId): void;
+export {};

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

@@ -0,0 +1,111 @@
+// The slash menu's logic: "/" typed at the start of a top-level paragraph
+// opens it, what's typed after the "/" filters it, and picking an item
+// turns the paragraph into that block, the "/…" gone. The menu itself:
+// rich-text-slash-menu.tsx; its keys and ARIA: milkdown-editor.tsx.
+//
+// Only a "/" typed there opens it: one already in the text (a path,
+// `/usr/bin`) never does, and neither does a "/" mid-line or inside a
+// list, a quote or a code block.
+import { Plugin, PluginKey } from '@milkdown/kit/prose/state';
+import { FORMAT_GROUPS } from './rich-text-format-items.js';
+import { toggleFormat } from './rich-text-formats.js';
+const slashKey = new PluginKey('rich-text-slash');
+// Longer than any item's name: past it, the person is writing, not picking.
+const MAX_QUERY = 24;
+// A top-level paragraph's start: where a "/" opens the menu.
+function atParagraphStart(state, pos) {
+    const $pos = state.doc.resolve(pos);
+    return $pos.depth === 1 && $pos.parent.type.name === 'paragraph' && $pos.parentOffset === 0;
+}
+// The menu's span, if the "/" at `from` still opens it: the caret after it
+// in the same paragraph, nothing selected, and what follows the "/" plain
+// text that doesn't start with a space.
+function queryAt(state, from) {
+    const { selection, doc } = state;
+    if (!selection.empty || from >= doc.content.size || !atParagraphStart(state, from))
+        return null;
+    const to = selection.from;
+    if (to <= from || !doc.resolve(from).sameParent(selection.$from))
+        return null;
+    const text = doc.textBetween(from, to, '\n', '\n');
+    if (!text.startsWith('/'))
+        return null;
+    const query = text.slice(1);
+    if (query.length > MAX_QUERY || /^\s|\n/.test(query))
+        return null;
+    return { from, to, query };
+}
+/** The open menu's span and query, or null when it's closed. */
+export function slashQuery(state) {
+    const open = slashKey.getState(state);
+    return open ? queryAt(state, open.from) : null;
+}
+/** The transaction that closes the menu, leaving what was typed as text (Esc). */
+export function closeSlash(state) {
+    return state.tr.setMeta(slashKey, 'close');
+}
+/** The id of the menu's item at `index`, for the text's `aria-activedescendant`. */
+export function slashOptionId(listId, index) {
+    return `${listId}-${index}`;
+}
+/** The plugin: opens on a typed "/", follows the text, closes once the span stops qualifying. */
+export function slashPlugin() {
+    return new Plugin({
+        key: slashKey,
+        state: {
+            init: () => null,
+            apply: (tr, value, _previous, next) => {
+                const meta = tr.getMeta(slashKey);
+                if (meta === 'close')
+                    return null;
+                const from = meta ? meta.from : value ? tr.mapping.map(value.from) : null;
+                // Closed for good once it stops qualifying: the caret coming back
+                // later doesn't reopen it.
+                return from !== null && queryAt(next, from) ? { from } : null;
+            },
+        },
+        props: {
+            handleTextInput: (view, from, to, text) => {
+                if (text !== '/' || from !== to || !atParagraphStart(view.state, from))
+                    return false;
+                view.dispatch(view.state.tr.insertText('/', from, to).setMeta(slashKey, { from }));
+                return true;
+            },
+        },
+    });
+}
+// What each block answers to besides its name.
+const KEYWORDS = {
+    heading: ['h1', 'title'],
+    subheading: ['h2'],
+    bullets: ['ul', 'unordered', 'bullet'],
+    numbers: ['ol', 'ordered', 'number'],
+    tasks: ['todo', 'checkbox', 'checklist'],
+    quote: ['blockquote'],
+    codeBlock: ['pre'],
+};
+// The menu's items: the blocks, in the toolbar's order.
+const BLOCKS = FORMAT_GROUPS.flat().filter((item) => KEYWORDS[item.id]);
+/** The blocks matching what's typed after the "/": in the name, or the start of a keyword. */
+export function slashItems(query) {
+    const typed = query.trim().toLowerCase();
+    if (!typed)
+        return BLOCKS;
+    return BLOCKS.filter((item) => item.label.toLowerCase().includes(typed) || KEYWORDS[item.id].some((word) => word.startsWith(typed)));
+}
+/**
+ * Picks an item: the "/…" goes and the paragraph becomes that block, in one
+ * transaction (one undo step, which brings the "/…" back).
+ */
+export function applySlash(view, span, id) {
+    const tr = view.state.tr.delete(span.from, span.to).setMeta(slashKey, 'close');
+    let formatted = null;
+    toggleFormat(view.state.apply(tr), (next) => (formatted = next), id);
+    const done = formatted;
+    if (done) {
+        for (const step of done.steps)
+            tr.step(step);
+        tr.setSelection(done.selection.getBookmark().resolve(tr.doc));
+    }
+    view.dispatch(tr.scrollIntoView());
+}

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

@@ -1,5 +1,21 @@
+import { type Ref } from 'react';
 import type { EditorState } from '@milkdown/kit/prose/state';
+import { type FormatItem } from './rich-text-format-items.js';
 import { type FormatId } from './rich-text-formats.js';
+declare const SETS: {
+    all: FormatItem[][];
+    selection: FormatItem[][];
+};
+export type FormatButtonsProps = {
+    /** Every format, or the ones for selected words. */
+    formats: keyof typeof SETS;
+    /** The editor's state now, to show which formats are on. Null until it's made. */
+    state: EditorState | null;
+    readOnly: boolean;
+    /** A button pressed: run the format on the editor and give it focus back. */
+    onFormat: (id: FormatId) => void;
+};
+export declare function FormatButtons({ formats, state, readOnly, onFormat }: FormatButtonsProps): import("react").JSX.Element;
 export interface RichTextToolbarProps {
     /** The editor's state now, to show which formats are on. Null until it's made. */
     state: EditorState | null;
@@ -8,5 +24,8 @@ export interface RichTextToolbarProps {
     controls?: string;
     /** A button pressed: run the format on the editor and give it focus back. */
     onFormat: (id: FormatId) => void;
+    /** The toolbar's element, for Alt+F10 to reach it from the text. */
+    ref?: Ref<HTMLDivElement>;
 }
-export declare function RichTextToolbar({ state, readOnly, controls, onFormat }: RichTextToolbarProps): import("react").JSX.Element;
+export declare function RichTextToolbar({ state, readOnly, controls, onFormat, ref }: RichTextToolbarProps): import("react").JSX.Element;
+export {};

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

@@ -10,35 +10,14 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 //   (`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';
+// - Alt+F10 in the text reaches it (the floating toolbar first, when it's
+//   showing: rich-text-floating-toolbar.tsx).
 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 { FORMAT_GROUPS } from './rich-text-format-items.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);
 }
@@ -56,13 +35,24 @@ function shownKeys(keys, apple) {
         .map((part) => symbols[part] ?? part)
         .join('');
 }
-export function RichTextToolbar({ state, readOnly, controls, onFormat }) {
+// Which buttons a toolbar has: every format (the fixed one), or the ones
+// that apply to selected words (the floating one).
+const SETS = {
+    all: FORMAT_GROUPS,
+    selection: [FORMAT_GROUPS[0], FORMAT_GROUPS[4]],
+};
+// A toolbar's row of buttons: one tab stop, the last one used (ARIA's
+// toolbar pattern); the arrow keys, Home and End move along the row. The
+// toolbar's element (`role="toolbar"`, its name) is the caller's.
+export function FormatButtons({ formats, state, readOnly, onFormat }) {
     const apple = isApple();
+    const groups = SETS[formats];
+    const items = groups.flat();
     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;
+        const next = (index + items.length) % items.length;
         setCurrent(next);
         buttons.current[next]?.focus();
     };
@@ -71,7 +61,7 @@ export function RichTextToolbar({ state, readOnly, controls, onFormat }) {
             ArrowRight: () => move(current + 1),
             ArrowLeft: () => move(current - 1),
             Home: () => move(0),
-            End: () => move(ITEMS.length - 1),
+            End: () => move(items.length - 1),
         };
         const action = keys[event.key];
         if (!action || event.metaKey || event.ctrlKey || event.altKey)
@@ -79,20 +69,23 @@ export function RichTextToolbar({ state, readOnly, controls, onFormat }) {
         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))) }) }));
+    return (_jsx(TooltipProvider, { delay: 400, 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), onKeyDown: onKeyDown, onPressedChange: () => onFormat(item.id) }), children: _jsx(Icon, {}) }), _jsx(TooltipContent, { children: tip })] }, item.id));
+                })] }, groupIndex))) }));
+}
+export function RichTextToolbar({ state, readOnly, controls, onFormat, ref }) {
+    return (_jsx("div", { ref: ref, 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", children: _jsx(FormatButtons, { formats: "all", state: state, readOnly: readOnly, onFormat: onFormat }) }));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tristan2828/ui-foundation",
-  "version": "3.16.2",
+  "version": "3.18.0",
   "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": {