@tristan2828/ui-foundation 3.14.0 → 3.16.0

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

@@ -197,7 +197,9 @@ is a filled-in example while the Widgets demo is still here).
      the plan edits in place** (`Edit in place`), shared by the form
      (through a `Controller`) and the view (through `editInPlace`), and
      the Markdown long text's `RichTextEditor` (on the form whether or
-     not it edits in place). Every other field's control stays inline in
+     not it edits in place), given a `placeholder` and `maxLength` (the
+     schema's limit, one constant both read, like Widget's
+     `DESCRIPTION_MAX_LENGTH`). Every other field's control stays inline in
      the form, as `widget-form.tsx`'s Category, Tags and Available From
      do. No `Edit in place` line and no Markdown long text: no fields
      file.

package/conventions/docs/cell-patterns.md

@@ -736,7 +736,15 @@ const price = editInPlace({
 - **Long text written as Markdown edits as rich text** (`RichTextEditor`):
   formatted where it's read, saved as Markdown with every block the person
   didn't touch kept exactly as written. On the form too, so it's one
-  control.
+  control. Give it a `placeholder` and the schema's limit as `maxLength`
+  (a count shows from 80% of it, in the destructive text tone once over).
+  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. 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/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, 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 } 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
@@ -15,16 +15,33 @@ import { jsx as _jsx } from "react/jsx-runtime";
 // - 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';
+// - Markdown pasted as plain text arrives formatted (still no HTML), and a
+//   copy out of the editor is Markdown.
+// - Ctrl/Cmd+K adds or edits a link (a box at the caret: web and email
+//   addresses only); Ctrl/Cmd+Shift+Enter ticks the task item the caret is
+//   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';
 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 { Decoration, DecorationSet } from '@milkdown/kit/prose/view';
 import { $prose, getMarkdown } from '@milkdown/kit/utils';
 import { cn } from 'cn';
+import { Button } from '../ui/button.js';
+import { Field, FieldError, FieldLabel } from '../ui/field.js';
+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;
@@ -102,29 +119,107 @@ function taskItemView(node, view, getPos) {
         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, }) {
+// The task-list item the caret is in, ticked or unticked. False when the
+// caret isn't in one.
+function toggleTaskItem(view) {
+    const { $from } = view.state.selection;
+    for (let depth = $from.depth; depth > 0; depth--) {
+        const node = $from.node(depth);
+        if (node.type.name === 'list_item' && node.attrs.checked != null) {
+            view.dispatch(view.state.tr.setNodeMarkup($from.before(depth), undefined, { ...node.attrs, checked: !node.attrs.checked }));
+            return true;
+        }
+    }
+    return false;
+}
+function linkTarget(state) {
+    const link = state.schema.marks.link;
+    const { from, to, empty, $from } = state.selection;
+    if (!empty) {
+        let href = '';
+        state.doc.nodesBetween(from, to, (node) => {
+            const mark = link.isInSet(node.marks);
+            if (mark && !href)
+                href = String(mark.attrs.href);
+        });
+        return { from, to, href };
+    }
+    const mark = link.isInSet($from.marks());
+    if (!mark)
+        return { from, to, href: '' };
+    const start = $from.start();
+    let target = { from, to, href: String(mark.attrs.href) };
+    let runFrom = -1;
+    $from.parent.forEach((child, offset) => {
+        const childFrom = start + offset;
+        const childTo = childFrom + child.nodeSize;
+        if (!mark.isInSet(child.marks)) {
+            runFrom = -1;
+            return;
+        }
+        if (runFrom < 0)
+            runFrom = childFrom;
+        if (runFrom <= from && from <= childTo)
+            target = { from: runFrom, to: childTo, href: target.href };
+    });
+    return target;
+}
+// Sets (or, with `href` empty, removes) the link on the target. With
+// nothing selected and no link there, the address goes in as the link's
+// own text.
+function applyLink(view, target, href) {
+    const link = view.state.schema.marks.link;
+    const tr = view.state.tr;
+    if (target.from === target.to) {
+        if (!href)
+            return;
+        tr.insertText(href, target.from).addMark(target.from, target.from + href.length, link.create({ href }));
+    }
+    else {
+        tr.removeMark(target.from, target.to, link);
+        if (href)
+            tr.addMark(target.from, target.to, link.create({ href }));
+    }
+    view.dispatch(tr.scrollIntoView());
+}
+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 });
+    const latest = useRef({ onChange, onProblem, readOnly, placeholder });
     useEffect(() => {
-        latest.current = { onChange, onProblem, readOnly };
+        latest.current = { onChange, onProblem, readOnly, placeholder };
     });
+    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(' ');
     const attributes = {
         'aria-multiline': 'true',
         'aria-readonly': String(readOnly),
         class: 'outline-none',
     };
-    if (id)
-        attributes.id = id;
+    attributes.id = editableId;
     if (ariaLabel)
         attributes['aria-label'] = ariaLabel;
     if (ariaLabelledBy)
         attributes['aria-labelledby'] = ariaLabelledBy;
-    if (ariaDescribedBy)
-        attributes['aria-describedby'] = ariaDescribedBy;
+    if (describedBy)
+        attributes['aria-describedby'] = describedBy;
     if (ariaInvalid)
         attributes['aria-invalid'] = 'true';
+    if (placeholder)
+        attributes['aria-placeholder'] = placeholder;
     const attributesKey = JSON.stringify(attributes);
     // The editor is made once, from the Markdown it opened with.
     useEffect(() => {
@@ -143,6 +238,7 @@ export default function MilkdownEditor({ id, defaultValue, onChange, onProblem,
                 const merged = mergeMarkdown(original, baseline, current);
                 latest.current.onProblem?.(null);
                 latest.current.onChange(merged);
+                setLength(merged.length);
             }
             catch (error) {
                 if (!(error instanceof MarkdownMergeError))
@@ -153,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();
                 },
@@ -161,6 +258,81 @@ export default function MilkdownEditor({ id, defaultValue, onChange, onProblem,
                 transformPasted: (slice) => new Slice(htmlToText(slice.content), slice.openStart, slice.openEnd),
             },
         }));
+        // Opens the link box at the start of what the link applies to.
+        const openLink = (view) => {
+            if (!view.editable)
+                return;
+            const target = linkTarget(view.state);
+            const point = view.coordsAtPos(target.from);
+            setLinkBox({
+                ...target,
+                anchor: {
+                    getBoundingClientRect: () => new DOMRect(point.left, point.top, 0, point.bottom - point.top),
+                    contextElement: view.dom,
+                },
+            });
+        };
+        openLinkRef.current = openLink;
+        // Paste, copy, the editor's own keys and the placeholder.
+        const input = $prose((ctx) => new Plugin({
+            props: {
+                // Plain text is read as Markdown, so `## Notes` or `**bold**`
+                // copied from another app arrives formatted; raw HTML in it
+                // still arrives as text. A paste with HTML of its own (from a
+                // web page) is ProseMirror's, through transformPasted above.
+                handlePaste: (view, event) => {
+                    const data = event.clipboardData;
+                    if (!data || !view.editable || data.getData('text/html'))
+                        return false;
+                    const text = data.getData('text/plain');
+                    if (!text || view.state.selection.$from.parent.type.spec.code)
+                        return false;
+                    const parsed = ctx.get(parserCtx)(text);
+                    if (!parsed || typeof parsed === 'string')
+                        return false;
+                    // Text with no Markdown in it (one plain paragraph) goes in
+                    // exactly as typed, spaces at its ends kept.
+                    const only = parsed.childCount === 1 ? parsed.firstChild : null;
+                    if (only?.type.name === 'paragraph' && only.childCount === 1 && only.textContent === text.trim()) {
+                        view.dispatch(view.state.tr.insertText(text).scrollIntoView());
+                        return true;
+                    }
+                    view.dispatch(view.state.tr.replaceSelection(Slice.maxOpen(htmlToText(parsed.content))).scrollIntoView());
+                    return true;
+                },
+                // A copy is Markdown, so it pastes into a plain text field
+                // (or another Markdown editor) as written.
+                clipboardTextSerializer: (slice) => {
+                    const doc = slice.content.firstChild?.isBlock
+                        ? ctx.get(schemaCtx).topNodeType.createAndFill(undefined, slice.content)
+                        : null;
+                    return doc ? ctx.get(serializerCtx)(doc) : slice.content.textBetween(0, slice.content.size, '\n\n');
+                },
+                handleKeyDown: (view, event) => {
+                    const mod = event.metaKey || event.ctrlKey;
+                    if (mod && !event.shiftKey && !event.altKey && event.key.toLowerCase() === 'k') {
+                        event.preventDefault();
+                        openLink(view);
+                        return true;
+                    }
+                    // Ctrl/Cmd+Shift+Enter in a task item ticks it, and goes no
+                    // further. Anywhere else it reaches the field, which saves.
+                    if (mod && event.shiftKey && event.key === 'Enter' && view.editable && toggleTaskItem(view)) {
+                        event.preventDefault();
+                        event.stopPropagation();
+                        return true;
+                    }
+                    return false;
+                },
+                decorations: (state) => {
+                    const text = latest.current.placeholder;
+                    const only = state.doc.childCount === 1 ? state.doc.firstChild : null;
+                    if (!text || !only || only.type.name !== 'paragraph' || only.content.size > 0)
+                        return null;
+                    return DecorationSet.create(state.doc, [Decoration.node(0, only.nodeSize, { 'data-placeholder': text })]);
+                },
+            },
+        }));
         const make = Editor.make()
             .config((ctx) => {
             ctx.set(rootCtx, root);
@@ -179,7 +351,8 @@ export default function MilkdownEditor({ id, defaultValue, onChange, onProblem,
             .use(COMMONMARK)
             .use(gfm)
             .use(history)
-            .use(changes);
+            .use(changes)
+            .use(input);
         void make.create().then((editor) => {
             if (cancelled) {
                 void editor.destroy();
@@ -187,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());
         });
@@ -212,10 +386,67 @@ export default function MilkdownEditor({ id, defaultValue, onChange, onProblem,
             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) }));
+    // 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: [_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;
+                        editor?.action((ctx) => applyLink(ctx.get(editorViewCtx), linkBox, href));
+                        closeLink();
+                    } })) })] }));
+}
+// The link box: the address, Apply, and Remove link for an existing one.
+// Enter (Ctrl/Cmd+Enter too) applies the link and stays its own: editing
+// in place listens for Ctrl/Cmd+Enter through the portal, and would save
+// the field without it. Esc is the popover's: it closes the box only.
+function LinkForm({ box, onApply }) {
+    const [typed, setTyped] = useState(box.href);
+    const [error, setError] = useState(null);
+    const inputRef = useRef(null);
+    const inputId = useId();
+    const errorId = `${inputId}-error`;
+    const apply = () => {
+        const href = linkHref(typed);
+        if (href === null) {
+            setError('Enter a web or email address, like https://example.com.');
+            return;
+        }
+        onApply(href);
+    };
+    const onKeyDown = (event) => {
+        if (event.key === 'Enter' && event.target === inputRef.current) {
+            event.preventDefault();
+            event.stopPropagation();
+            apply();
+        }
+    };
+    return (_jsxs(PopoverContent, { anchor: box.anchor, align: "start", "aria-label": box.href ? 'Edit link' : 'Add link', initialFocus: inputRef, finalFocus: false, className: "w-80", onKeyDown: onKeyDown, children: [_jsxs(Field, { "data-invalid": error ? true : undefined, children: [_jsx(FieldLabel, { htmlFor: inputId, children: "Link address" }), _jsx(Input, { ref: inputRef, id: inputId, value: typed, placeholder: "https://", autoComplete: "off", "aria-invalid": error ? true : undefined, "aria-describedby": error ? errorId : undefined, onChange: (event) => {
+                            setTyped(event.target.value);
+                            setError(null);
+                        } }), error && _jsx(FieldError, { id: errorId, children: error })] }), _jsxs("div", { className: "flex gap-2", children: [_jsx(Button, { size: "sm", onClick: apply, children: "Apply" }), box.href && (_jsx(Button, { size: "sm", variant: "outline", onClick: () => onApply(''), children: "Remove link" }))] })] }));
 }

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

@@ -10,6 +10,20 @@ export type RichTextEditorProps = {
     /** Shown but not editable (while a save is in flight). */
     readOnly?: boolean;
     autoFocus?: boolean;
+    /** Shown while the document is empty (and given to screen readers as `aria-placeholder`). */
+    placeholder?: string;
+    /**
+     * The field's limit on the saved Markdown's length. From 80% of it, a
+     * count shows under the editor, in the destructive text tone once over.
+     * 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/dist/components/ui/popover.d.ts

@@ -2,7 +2,7 @@ import * as React from "react";
 import { Popover as PopoverPrimitive } from "@base-ui/react/popover";
 declare function Popover({ ...props }: PopoverPrimitive.Root.Props): React.JSX.Element;
 declare function PopoverTrigger({ ...props }: PopoverPrimitive.Trigger.Props): React.JSX.Element;
-declare function PopoverContent({ className, align, alignOffset, side, sideOffset, ...props }: PopoverPrimitive.Popup.Props & Pick<PopoverPrimitive.Positioner.Props, "align" | "alignOffset" | "side" | "sideOffset">): React.JSX.Element;
+declare function PopoverContent({ className, align, alignOffset, side, sideOffset, anchor, ...props }: PopoverPrimitive.Popup.Props & Pick<PopoverPrimitive.Positioner.Props, "align" | "alignOffset" | "side" | "sideOffset" | "anchor">): React.JSX.Element;
 declare function PopoverHeader({ className, ...props }: React.ComponentProps<"div">): React.JSX.Element;
 declare function PopoverTitle({ className, ...props }: PopoverPrimitive.Title.Props): React.JSX.Element;
 declare function PopoverDescription({ className, ...props }: PopoverPrimitive.Description.Props): React.JSX.Element;

package/dist/components/ui/popover.js

@@ -8,8 +8,12 @@ function Popover({ ...props }) {
 function PopoverTrigger({ ...props }) {
     return _jsx(PopoverPrimitive.Trigger, { "data-slot": "popover-trigger", ...props });
 }
-function PopoverContent({ className, align = "center", alignOffset = 0, side = "bottom", sideOffset = 4, ...props }) {
-    return (_jsx(PopoverPrimitive.Portal, { children: _jsx(PopoverPrimitive.Positioner, { align: align, alignOffset: alignOffset, side: side, sideOffset: sideOffset, className: "isolate z-50", children: _jsx(PopoverPrimitive.Popup, { "data-slot": "popover-content", className: cn("z-50 flex w-72 origin-(--transform-origin) flex-col gap-2.5 rounded-lg bg-popover p-2.5 text-sm text-popover-foreground shadow-md ring-1 ring-foreground/10 outline-hidden duration-100 data-[side=bottom]:slide-in-from-top-2 data-[side=inline-end]:slide-in-from-left-2 data-[side=inline-start]:slide-in-from-right-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 data-open:animate-in data-open:fade-in-0 data-open:zoom-in-95 data-closed:animate-out data-closed:fade-out-0 data-closed:zoom-out-95", className), ...props }) }) }));
+// `anchor` is this repo's patch to the upstream primitive: a popover with
+// no trigger of its own, placed at a point (the rich-text editor's link
+// box, at the caret). A local patch: re-running `shadcn add popover` here
+// would overwrite it. Diff against upstream before taking a new version.
+function PopoverContent({ className, align = "center", alignOffset = 0, side = "bottom", sideOffset = 4, anchor, ...props }) {
+    return (_jsx(PopoverPrimitive.Portal, { children: _jsx(PopoverPrimitive.Positioner, { anchor: anchor, align: align, alignOffset: alignOffset, side: side, sideOffset: sideOffset, className: "isolate z-50", children: _jsx(PopoverPrimitive.Popup, { "data-slot": "popover-content", className: cn("z-50 flex w-72 origin-(--transform-origin) flex-col gap-2.5 rounded-lg bg-popover p-2.5 text-sm text-popover-foreground shadow-md ring-1 ring-foreground/10 outline-hidden duration-100 data-[side=bottom]:slide-in-from-top-2 data-[side=inline-end]:slide-in-from-left-2 data-[side=inline-start]:slide-in-from-right-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 data-open:animate-in data-open:fade-in-0 data-open:zoom-in-95 data-closed:animate-out data-closed:fade-out-0 data-closed:zoom-out-95", className), ...props }) }) }));
 }
 function PopoverHeader({ className, ...props }) {
     return (_jsx("div", { "data-slot": "popover-header", className: cn("flex flex-col gap-0.5 text-sm", className), ...props }));

package/dist/lib/link-href.d.ts

@@ -0,0 +1,2 @@
+/** The `href` to save, `''` to remove the link, or `null` when it's refused. */
+export declare function linkHref(typed: string): string | null;

package/dist/lib/link-href.js

@@ -0,0 +1,22 @@
+// The address a link in the rich-text editor points at, from what the
+// person typed. Web and email addresses only: a bare `example.com` becomes
+// `https://example.com` and a bare `name@example.com` a `mailto:`; a path
+// on this site (`/x`) or a heading (`#x`) is kept. Any other scheme
+// (`javascript:`, `data:`, `file:`) is refused, so a link can't run code
+// or reach a local file.
+/** The `href` to save, `''` to remove the link, or `null` when it's refused. */
+export function linkHref(typed) {
+    const value = typed.trim();
+    if (value === '')
+        return '';
+    if (/^(https?:\/\/|mailto:|tel:)/i.test(value))
+        return value;
+    // A scheme of its own (`javascript:`), not a port (`example.com:8080`).
+    if (/^[a-z][a-z0-9+.-]*:(?!\d)/i.test(value))
+        return null;
+    if (value.startsWith('/') || value.startsWith('#'))
+        return value;
+    if (/^[^\s@/]+@[^\s@/]+\.[^\s@/]+$/.test(value))
+        return `mailto:${value}`;
+    return `https://${value}`;
+}

package/package.json

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