@tristan2828/ui-foundation 3.20.1 → 3.21.0

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

@@ -275,9 +275,9 @@ is a filled-in example while the Widgets demo is still here).
      `<a target="_blank" rel="noreferrer">` with an `ExternalLinkIcon`
      and a visually hidden "(opens in a new tab)".
    - **Long text the plan marks Markdown** renders through the
-     foundation's `<Markdown>`: headings, lists, tables and links, links
-     opening in a new tab; raw HTML shows as the characters typed, never
-     as markup. The app needs no Markdown dependency of its own. Plain
+     foundation's `<Markdown>`: headings, lists, tables, callouts
+     (`> [!NOTE]`) and links, links opening in a new tab; raw HTML shows
+     as the characters typed, never as markup. The app needs no Markdown dependency of its own. Plain
      long text renders as text (`whitespace-pre-line` keeps its line
      breaks).
    - **Quick actions: only the fields the plan's `Quick actions` line

package/conventions/docs/cell-patterns.md

@@ -740,15 +740,24 @@ const price = editInPlace({
   (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
+  Markdown pasted as plain text arrives formatted. Notion's block keys
+  work: Ctrl+Shift+1 to 3 for headings, +4 tasks, +5 bullets, +6 numbers,
+  +8 a code block, +0 back to text (Cmd+Option on a Mac), and
+  Ctrl/Cmd+Shift+S strikes through. Ctrl/Cmd+Enter stays the save, in a
+  table too. A formatting toolbar sits above the text (bold to link, each
   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.
+  become (three headings, lists, quote, callout, code block, divider,
+  table); typing filters ("/warn" finds a warning callout), Enter or Tab
+  picks, and Esc closes the list before it gives up the edit. A callout
+  is GitHub's `> [!NOTE]` (note, tip, important, warning, caution), its
+  icon a menu of kinds. In a table, Tab in the last cell adds a row,
+  Enter goes down a column (and out from the last row), bars under and
+  beside it add a row or a column, and the toolbar's Table menu inserts
+  rows and columns, aligns a column and deletes.
   `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

package/conventions/docs/design-language.md

@@ -172,6 +172,28 @@ height and weight together, from tokens in the package's `styles/theme.css`:
 - A shadcn primitive keeps its own sizes (`CardTitle`, `Button`). Don't put
   a role on one: its built-in size classes would then compete with the role.
 
+### Written text (notes)
+
+Long text written as Markdown (`<Markdown>` and `RichTextEditor`) has its
+own three heading roles, so `#`, `##` and `###` in a note never look
+alike. They're for headings inside the text only, never a screen's own
+outline (that stays `type-page-title` and `type-section-title`):
+
+| Class | For | Size / weight |
+|---|---|---|
+| `type-heading-1` | `#` in a note, with a rule under it | 26px / 700 |
+| `type-heading-2` | `##` | 20px / 600 |
+| `type-heading-3` | `###` | 17px / 600 |
+
+The same text has two colour tokens of its own: `--link` (`text-link`), a
+link's colour, blue as well as underlined (5.59:1 on white, 8.90:1 on the
+dark page), and `--rule` (`bg-rule`), the 2px line a `---` divider draws,
+stronger than `--border`'s hairline. A callout (`> [!NOTE]`) is a 10% wash
+of its kind's tone behind ordinary text, with the icon in the tone's text
+shade: note `info`, tip `success`, important category slot 2, warning
+`warning`, caution `destructive`. The package draws all of it; an app
+only renders `<Markdown>` or the editor.
+
 ## Density
 
 Tables have three densities, set with `data-density` on **any ancestor**

package/dist/components/app/markdown.js

@@ -4,7 +4,12 @@ import remarkGfm from 'remark-gfm';
 import { cn } from 'cn';
 import { ExternalLinkIcon, SquareCheckIcon, SquareIcon } from 'lucide-react';
 import { Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from '../ui/table.js';
-const REMARK_PLUGINS = [remarkGfm];
+import { CALLOUT_KINDS, remarkCallouts } from '../../lib/markdown-callout.js';
+import { CALLOUT_BOX, CALLOUT_LOOK, headingClass, PROSE } from './prose-look.js';
+const REMARK_PLUGINS = [remarkGfm, remarkCallouts];
+function isCalloutKind(value) {
+    return CALLOUT_KINDS.includes(value);
+}
 // Every element react-markdown hands over carries `node` (the syntax tree
 // node). It isn't a DOM attribute, so it's dropped before spreading.
 function omitNode(props) {
@@ -13,33 +18,44 @@ function omitNode(props) {
     return rest;
 }
 const COMPONENTS = {
-    h1: (props) => _jsx("h3", { ...omitNode(props), className: "type-section-title mt-2 text-foreground" }),
-    h2: (props) => _jsx("h4", { ...omitNode(props), className: "type-section-title mt-2 text-foreground" }),
-    h3: (props) => _jsx("h5", { ...omitNode(props), className: "type-label mt-1 text-foreground" }),
-    h4: (props) => _jsx("h6", { ...omitNode(props), className: "type-label mt-1 text-foreground" }),
-    h5: (props) => _jsx("h6", { ...omitNode(props), className: "type-label mt-1 text-foreground" }),
-    h6: (props) => _jsx("h6", { ...omitNode(props), className: "type-label mt-1 text-foreground" }),
+    h1: (props) => _jsx("h3", { ...omitNode(props), className: cn(headingClass(1), 'text-foreground') }),
+    h2: (props) => _jsx("h4", { ...omitNode(props), className: cn(headingClass(2), 'text-foreground') }),
+    h3: (props) => _jsx("h5", { ...omitNode(props), className: cn(headingClass(3), 'text-foreground') }),
+    h4: (props) => _jsx("h6", { ...omitNode(props), className: cn(headingClass(4), 'text-foreground') }),
+    h5: (props) => _jsx("h6", { ...omitNode(props), className: cn(headingClass(5), 'text-foreground') }),
+    h6: (props) => _jsx("h6", { ...omitNode(props), className: cn(headingClass(6), 'text-foreground') }),
     a: (props) => {
         const { href, children, ...rest } = omitNode(props);
         if (!href)
             return _jsx("span", { children: children });
-        return (_jsxs("a", { ...rest, href: href, target: "_blank", rel: "noreferrer", className: "text-primary underline underline-offset-4 hover:text-primary/80", children: [children, _jsx(ExternalLinkIcon, { "aria-hidden": "true", className: "ml-0.5 inline size-3 align-baseline" }), _jsx("span", { className: "sr-only", children: " (opens in a new tab)" })] }));
-    },
-    ul: (props) => {
-        const { className, ...rest } = omitNode(props);
-        const isTaskList = className?.includes('contains-task-list');
-        return _jsx("ul", { ...rest, className: cn('flex flex-col gap-1', isTaskList ? 'list-none' : 'list-disc pl-6') });
+        return (_jsxs("a", { ...rest, href: href, target: "_blank", rel: "noreferrer", className: PROSE.link, children: [children, _jsx(ExternalLinkIcon, { "aria-hidden": "true", className: "ml-0.5 inline size-3 align-baseline" }), _jsx("span", { className: "sr-only", children: " (opens in a new tab)" })] }));
     },
+    // A list can mix plain and task items (`- a` then `- [ ] b` is one
+    // list): each task item drops its own bullet, the rest keep theirs. Its
+    // box is inline, so a loose list's item (its text in a <p>) lays out
+    // the same as a tight one's.
+    ul: (props) => _jsx("ul", { ...omitNode(props), className: "flex list-disc flex-col gap-1 pl-6" }),
     ol: (props) => _jsx("ol", { ...omitNode(props), className: "flex list-decimal flex-col gap-1 pl-6" }),
     li: (props) => {
         const { className, ...rest } = omitNode(props);
-        return _jsx("li", { ...rest, className: cn(className?.includes('task-list-item') && 'flex items-start gap-2') });
+        return _jsx("li", { ...rest, className: cn(className?.includes('task-list-item') && '-ml-6 list-none') });
     },
     // A GitHub task-list box (`- [x] done`). Read-only, so a glyph with its
     // state in words, never a checkbox someone will try to tick.
-    input: ({ checked }) => checked ? (_jsx(SquareCheckIcon, { role: "img", "aria-label": "Done", className: "mt-0.5 size-4 shrink-0 text-foreground" })) : (_jsx(SquareIcon, { role: "img", "aria-label": "Not done", className: "mt-0.5 size-4 shrink-0 text-muted-foreground" })),
+    input: ({ checked }) => checked ? (_jsx(SquareCheckIcon, { role: "img", "aria-label": "Done", className: "mr-2 inline-block size-4 align-[-0.1875rem] text-foreground" })) : (_jsx(SquareIcon, { role: "img", "aria-label": "Not done", className: "mr-2 inline-block size-4 align-[-0.1875rem] text-muted-foreground" })),
     blockquote: (props) => (_jsx("blockquote", { ...omitNode(props), className: "flex flex-col gap-3 border-l-2 border-border pl-4 text-muted-foreground" })),
-    hr: () => _jsx("hr", { className: "border-border" }),
+    hr: () => _jsx("hr", { className: PROSE.rule }),
+    // A callout (remarkCallouts marks it): its kind's wash and icon, named
+    // for screen readers by the kind ("Note: …").
+    div: (props) => {
+        const { children, ...rest } = omitNode(props);
+        const kind = rest['data-callout'];
+        if (!isCalloutKind(kind))
+            return _jsx("div", { ...rest, children: children });
+        const look = CALLOUT_LOOK[kind];
+        const Icon = look.icon;
+        return (_jsxs("div", { role: "note", "data-callout": kind, className: cn(CALLOUT_BOX, look.box), children: [_jsx(Icon, { "aria-hidden": "true", className: cn('mt-0.5 size-4 shrink-0', look.tint) }), _jsxs("div", { className: "flex min-w-0 flex-1 flex-col gap-2", children: [_jsxs("span", { className: "sr-only", children: [look.label, ": "] }), children] })] }));
+    },
     pre: (props) => (_jsx("pre", { ...omitNode(props), className: "overflow-x-auto rounded-lg bg-muted p-3 font-mono text-foreground [&_code]:bg-transparent [&_code]:p-0" })),
     code: (props) => _jsx("code", { ...omitNode(props), className: "rounded bg-muted px-1 py-0.5 font-mono text-foreground" }),
     img: (props) => {
@@ -48,12 +64,14 @@ const COMPONENTS = {
     },
     // GFM tables use the package's own table, zebra stripes and density
     // tokens included, so a table in the notes reads like every other table.
-    table: (props) => _jsx(Table, { ...omitNode(props) }),
-    thead: (props) => _jsx(TableHeader, { ...omitNode(props) }),
+    table: (props) => _jsx(Table, { ...omitNode(props), containerClassName: "rounded-lg border border-border" }),
+    thead: (props) => _jsx(TableHeader, { ...omitNode(props), className: "bg-muted" }),
     tbody: (props) => _jsx(TableBody, { ...omitNode(props) }),
     tr: (props) => _jsx(TableRow, { ...omitNode(props) }),
-    th: (props) => _jsx(TableHead, { ...omitNode(props) }),
-    td: (props) => _jsx(TableCell, { ...omitNode(props) }),
+    // Notes' cells wrap (a cell can hold a sentence) and have a line
+    // between columns, so a wide table still reads column by column.
+    th: (props) => _jsx(TableHead, { ...omitNode(props), className: "border-r border-border whitespace-normal last:border-r-0" }),
+    td: (props) => _jsx(TableCell, { ...omitNode(props), className: "border-r border-border whitespace-normal last:border-r-0" }),
 };
 export function Markdown({ children, className, ...rest }) {
     return (_jsx("div", { "data-slot": "markdown", ...rest, className: cn('flex min-w-0 flex-col gap-3 type-body text-foreground break-words', className), children: _jsx(ReactMarkdown, { remarkPlugins: REMARK_PLUGINS, components: COMPONENTS, children: children }) }));

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

@@ -13,13 +13,22 @@ import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-run
 //   in the text shows as its characters (an uneditable chip, Milkdown's
 //   html node), and HTML pasted as such a chip becomes plain text.
 // - Headings render from <h3>, like <Markdown>: the page owns <h1> and
-//   <h2>. A task-list item renders a real checkbox that toggles it.
+//   <h2>; they look like <Markdown>'s (prose-look.ts). A task-list item
+//   renders a real checkbox that toggles it.
+// - Callouts (`> [!NOTE]`, src/lib/markdown-callout.ts): a node of their
+//   own, drawn as <Markdown> draws them, the icon a menu of kinds.
+// - Tables in a box that scrolls sideways, with Notion's "add a row" and
+//   "add a column" bars, Tab in the last cell adding a row and Enter going
+//   down a column (rich-text-table.ts); the toolbar's Table menu does the
+//   rest.
 // - Edited blocks are written in the document's own bullet and rule marks.
 // - 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.
+//   in. Ctrl/Cmd+Enter stays the field's save, in a table too. Notion's
+//   block keys (Ctrl+Shift+1 for a heading, +5 for bullets, …:
+//   rich-text-shortcuts.ts).
 // - 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), and a
@@ -30,26 +39,34 @@ import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-run
 //   line's start lists the blocks it can become, also unless
 //   `toolbar={false}`.
 import { useEffect, useId, useRef, useState } from 'react';
+import { createPortal } from 'react-dom';
 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 { NodeSelection, Plugin } from '@milkdown/kit/prose/state';
+import { NodeSelection, Plugin, TextSelection } from '@milkdown/kit/prose/state';
+import { isInTable, TableMap } from '@milkdown/kit/prose/tables';
 import { Decoration, DecorationSet } from '@milkdown/kit/prose/view';
-import { $prose, getMarkdown } from '@milkdown/kit/utils';
+import { $nodeSchema, $prose, $remark, 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 { calloutHandler, remarkCalloutNodes } from '../../lib/markdown-callout.js';
 import { MarkdownMergeError, markdownStyle, mergeMarkdown } from '../../lib/markdown-merge.js';
+import { headingClass } from './prose-look.js';
 import { RichTextFloatingToolbar } from './rich-text-floating-toolbar.js';
-import { toggleFormat } from './rich-text-formats.js';
+import { tableAt, toggleFormat } from './rich-text-formats.js';
+import { calloutKind, calloutView, tableView } from './rich-text-node-views.js';
+import { handleShortcut } from './rich-text-shortcuts.js';
+import { addRowAtEnd, handleTableKey, runTableAction } from './rich-text-table.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';
+import { CalloutKindMenu, TableBar } from './rich-text-widgets.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;
@@ -61,6 +78,34 @@ const COMMONMARK = [
     ...keymap,
     ...plugins.filter((plugin) => !LEFT_OUT.includes(plugin)),
 ];
+// Callouts: a node of their own, read from the quote remarkCalloutNodes
+// marks and written back as one with its marker (calloutHandler).
+const calloutRemark = $remark('remarkCalloutNodes', () => remarkCalloutNodes);
+const calloutSchema = $nodeSchema('callout', () => ({
+    content: 'block+',
+    group: 'block',
+    defining: true,
+    attrs: { kind: { default: 'note' }, marker: { default: null } },
+    parseDOM: [
+        {
+            tag: 'div[data-callout]',
+            getAttrs: (dom) => ({ kind: calloutKind(dom.dataset.callout) }),
+        },
+    ],
+    toDOM: (node) => ['div', { 'data-callout': String(node.attrs.kind) }, 0],
+    parseMarkdown: {
+        match: (node) => node.type === 'callout',
+        runner: (state, node, type) => {
+            state.openNode(type, { kind: calloutKind(node.kind), marker: node.marker ?? null }).next(node.children).closeNode();
+        },
+    },
+    toMarkdown: {
+        match: (node) => node.type.name === 'callout',
+        runner: (state, node) => {
+            state.openNode('callout', undefined, { kind: node.attrs.kind, marker: node.attrs.marker }).next(node.content).closeNode();
+        },
+    },
+}));
 // Raw HTML pasted in as Milkdown's html chip becomes the plain text it
 // shows, so a paste can never add markup to the Markdown.
 function htmlToText(fragment) {
@@ -78,7 +123,9 @@ function htmlToText(fragment) {
     return Fragment.fromArray(nodes);
 }
 function headingView(node) {
-    const dom = document.createElement(`h${Math.min(Number(node.attrs.level) + 2, 6)}`);
+    const level = Number(node.attrs.level);
+    const dom = document.createElement(`h${Math.min(level + 2, 6)}`);
+    dom.className = headingClass(level);
     return {
         dom,
         contentDOM: dom,
@@ -217,6 +264,9 @@ export default function MilkdownEditor({ id, defaultValue, onChange, onProblem,
     const slashMenuRef = useRef(null);
     // Opens the link box: made with the editor, used by the toolbar's Link.
     const openLinkRef = useRef(() => { });
+    // The node views' slots (a callout's icon, a table's bars), each
+    // rendered into through a portal.
+    const [widgets, setWidgets] = useState([]);
     // The latest props, for the editor's callbacks, which are set up once.
     const latest = useRef({ onChange, onProblem, readOnly, placeholder });
     useEffect(() => {
@@ -306,6 +356,33 @@ export default function MilkdownEditor({ id, defaultValue, onChange, onProblem,
                 transformPasted: (slice) => new Slice(htmlToText(slice.content), slice.openStart, slice.openEnd),
             },
         }));
+        // The node views' slots, by slot; React hears of a change once per
+        // task, however many node views changed in it.
+        const slots = new Map();
+        let syncQueued = false;
+        const sync = () => {
+            if (syncQueued)
+                return;
+            syncQueued = true;
+            queueMicrotask(() => {
+                syncQueued = false;
+                if (!cancelled)
+                    setWidgets([...slots.values()]);
+            });
+        };
+        const registry = {
+            set: (widget) => {
+                const before = slots.get(widget.slot);
+                if (before && before.type === widget.type && (before.type !== 'callout' || before.kind === widget.kind))
+                    return;
+                slots.set(widget.slot, widget);
+                sync();
+            },
+            remove: (slot) => {
+                if (slots.delete(slot))
+                    sync();
+            },
+        };
         // Opens the link box at the start of what the link applies to.
         const openLink = (view) => {
             if (!view.editable)
@@ -428,47 +505,66 @@ export default function MilkdownEditor({ id, defaultValue, onChange, onProblem,
             .config((ctx) => {
             ctx.set(rootCtx, root);
             ctx.set(defaultValueCtx, original);
-            ctx.update(remarkStringifyOptionsCtx, (options) => ({ ...options, ...markdownStyle(original) }));
+            ctx.update(remarkStringifyOptionsCtx, (options) => ({
+                ...options,
+                ...markdownStyle(original),
+                handlers: { ...options.handlers, callout: calloutHandler },
+            }));
             ctx.update(editorViewOptionsCtx, (options) => ({
                 ...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.
+                // The slash menu's keys, the editor's own shortcuts and its table
+                // keys, as view props: before Milkdown's own keymap, whose Enter
+                // would split the line (or leave a table).
                 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 (menu) {
+                        const step = event.key === 'ArrowDown' ? 1 : event.key === 'ArrowUp' ? -1 : 0;
+                        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;
+                        }
                     }
-                    if ((event.key === 'Enter' || event.key === 'Tab') && plain) {
-                        event.preventDefault();
-                        applySlash(view, menu.span, menu.items[menu.index].id);
+                    if (!view.editable)
+                        return false;
+                    if (handleShortcut(view.state, view.dispatch, event))
                         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));
+                    if (handleTableKey(view.state, view.dispatch, event))
                         return true;
-                    }
-                    return false;
+                    // Ctrl/Cmd+Enter in a table is the field's (a save), not
+                    // Milkdown's "leave the table": taken here, so its keymap never
+                    // sees it, and left to reach the field.
+                    const mod = event.metaKey || event.ctrlKey;
+                    return mod && !event.shiftKey && !event.altKey && event.key === 'Enter' && isInTable(view.state);
                 },
                 nodeViews: {
                     heading: headingView,
+                    callout: (node, _view, getPos) => calloutView(node, getPos, registry),
+                    table: (_node, _view, getPos) => tableView(getPos, registry),
                     list_item: (node, view, getPos) => node.attrs.checked == null ? undefined : taskItemView(node, view, getPos),
                 },
             }));
         })
             .use(COMMONMARK)
             .use(gfm)
+            .use(calloutRemark)
+            .use(calloutSchema)
             .use(history)
             .use(changes)
             .use(slashing)
@@ -523,6 +619,53 @@ export default function MilkdownEditor({ id, defaultValue, onChange, onProblem,
             view.focus();
         });
     };
+    // The editable element: where a menu over the text gives focus back
+    // (ProseMirror puts the caret back where it was as it takes it).
+    const textElement = () => editorView?.dom ?? null;
+    // A Table menu item, on the caret's table (the menu gives focus back).
+    const runTable = (action) => {
+        if (editorView)
+            runTableAction(editorView.state, editorView.dispatch, action);
+    };
+    // A callout's menu: its kind changed, or the callout taken away (its
+    // blocks kept). The menu gives focus back to the text.
+    const changeCallout = (getPos, kind) => {
+        if (!editorView)
+            return;
+        const pos = getPos();
+        const node = pos === undefined ? null : editorView.state.doc.nodeAt(pos);
+        if (pos === undefined || node?.type.name !== 'callout')
+            return;
+        const tr = editorView.state.tr;
+        if (kind)
+            tr.setNodeMarkup(pos, undefined, { ...node.attrs, kind });
+        else
+            tr.replaceWith(pos, pos + node.nodeSize, node.content).setSelection(TextSelection.near(tr.doc.resolve(pos + 1)));
+        editorView.dispatch(tr);
+    };
+    // A table's bar: the caret into its last cell, then a row at its end
+    // (the caret into its first cell) or a column at its right (the caret
+    // into its header).
+    const addToTable = (getPos, side) => {
+        if (!editorView)
+            return;
+        const pos = getPos();
+        const table = pos === undefined ? null : editorView.state.doc.nodeAt(pos);
+        if (pos === undefined || table?.type.name !== 'table')
+            return;
+        const last = TextSelection.near(editorView.state.doc.resolve(pos + table.nodeSize - 1), -1);
+        editorView.dispatch(editorView.state.tr.setSelection(last));
+        if (side === 'row')
+            addRowAtEnd(editorView.state, editorView.dispatch);
+        else if (runTableAction(editorView.state, editorView.dispatch, 'columnRight')) {
+            const added = editorView.state.doc.nodeAt(pos);
+            const map = TableMap.get(added);
+            const header = TextSelection.near(editorView.state.doc.resolve(pos + 1 + map.map[map.width - 1] + 1));
+            editorView.dispatch(editorView.state.tr.setSelection(header).scrollIntoView());
+        }
+        editorView.focus();
+    };
+    const caretTable = editorState ? tableAt(editorState)?.pos : undefined;
     // The floating toolbar: words selected, focus in the field, the mouse up,
     // and nothing else open over the text.
     const selection = editorState?.selection;
@@ -551,7 +694,7 @@ export default function MilkdownEditor({ id, defaultValue, onChange, onProblem,
     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', 
+                        controls: editorState ? editableId : undefined, onFormat: runFormat, onTable: runTable, text: textElement })), _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
@@ -559,11 +702,26 @@ export default function MilkdownEditor({ id, defaultValue, onChange, onProblem,
                         '[&_.ProseMirror]:flex [&_.ProseMirror]:min-h-20 [&_.ProseMirror]:flex-col [&_.ProseMirror]:gap-3', 
                         // ProseMirror's own required style (prosemirror-view's CSS): spaces
                         // as typed, so one at the end of a line isn't kept as &nbsp;.
-                        '[&_.ProseMirror]:whitespace-pre-wrap [&_.ProseMirror]:break-words', '[&_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', 
+                        '[&_.ProseMirror]:whitespace-pre-wrap [&_.ProseMirror]:break-words', '[&_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', 
+                        // Headings, callouts and tables are drawn by their node views;
+                        // these are the elements Milkdown draws itself.
+                        '[&_a]:text-link [&_a]:underline [&_a]:decoration-link/40 [&_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]:my-2 [&_hr]:h-0.5 [&_hr]:rounded-full [&_hr]:border-0 [&_hr]:bg-rule', '[&_hr.ProseMirror-selectednode]:outline-2 [&_hr.ProseMirror-selectednode]:outline-offset-4 [&_hr.ProseMirror-selectednode]:outline-ring', 
+                        // A table: a header row on the muted fill, a line between every
+                        // cell, cells that wrap and never shrink to nothing; selected
+                        // cells (a drag across them) tinted.
+                        '[&_table]:w-full [&_table]:border-collapse', '[&_:is(td,th)]:min-w-28 [&_:is(td,th)]:border-r [&_:is(td,th)]:border-b [&_:is(td,th)]:border-border [&_:is(td,th)]:px-(--table-cell-px) [&_:is(td,th)]:py-(--table-cell-py) [&_:is(td,th)]:align-top', '[&_:is(td,th):last-child]:border-r-0 [&_tr:last-child>td]:border-b-0', '[&_th]:bg-muted [&_th]:text-left [&_th]:type-label', '[&_.selectedCell]:bg-info/15', 
                         // 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)]') }), 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) => {
+                        '[&_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)]') }), widgets.map((widget) => {
+                        if (widget.type === 'callout')
+                            return createPortal(_jsx(CalloutKindMenu, { kind: widget.kind, readOnly: readOnly, onPick: (kind) => changeCallout(widget.getPos, kind), onRemove: () => changeCallout(widget.getPos, null), text: textElement }), widget.slot, widget.key);
+                        const active = caretTable !== undefined && caretTable === widget.getPos();
+                        return [
+                            createPortal(_jsx(TableBar, { side: "row", active: active, readOnly: readOnly, onAdd: () => addToTable(widget.getPos, 'row') }), widget.slot, `${widget.key}-row`),
+                            createPortal(_jsx(TableBar, { side: "column", active: active, readOnly: readOnly, onAdd: () => addToTable(widget.getPos, 'column') }), widget.column, `${widget.key}-column`),
+                        ];
+                    }), 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);

package/dist/components/app/prose-look.d.ts

@@ -0,0 +1,32 @@
+import { type LucideIcon } from 'lucide-react';
+import type { CalloutKind } from '../../lib/markdown-callout.js';
+/**
+ * Classes for written text's own elements. No colours on the headings:
+ * <Markdown> adds the text colour, and the editor's read-only text is
+ * muted as a whole.
+ */
+export declare const PROSE: {
+    /** `#`: the largest, with a rule under it, so it reads as the top of the outline. */
+    readonly heading1: "type-heading-1 mt-4 border-b border-border pb-1.5 first:mt-0";
+    readonly heading2: "type-heading-2 mt-3 first:mt-0";
+    readonly heading3: "type-heading-3 mt-1 first:mt-0";
+    /** `####` and deeper: a label, as before. */
+    readonly heading4: "type-label mt-1 first:mt-0";
+    /** Coloured as well as underlined. */
+    readonly link: "text-link underline decoration-link/40 underline-offset-4 transition-colors hover:decoration-link";
+    /** `---`: a 2px line in the rule tone, with room around it. */
+    readonly rule: "my-2 h-0.5 rounded-full border-0 bg-rule";
+};
+/** A heading's classes by its Markdown level (1 for `#`). */
+export declare function headingClass(level: number): string;
+export type CalloutLook = {
+    label: string;
+    icon: LucideIcon;
+    /** The box's wash and border. */
+    box: string;
+    /** The icon's tint. */
+    tint: string;
+};
+export declare const CALLOUT_LOOK: Record<CalloutKind, CalloutLook>;
+/** The box every callout shares: the icon in a column, the text beside it. */
+export declare const CALLOUT_BOX = "flex gap-2.5 rounded-lg border px-3 py-2.5";

package/dist/components/app/prose-look.js

@@ -0,0 +1,48 @@
+// How written text looks, the same in <Markdown> and in the rich-text
+// editor: its headings, links and rules (PROSE), and each kind of callout
+// (src/lib/markdown-callout.ts says what one is): its name, its icon, and
+// its colours. A callout is a wash of the kind's tone behind ordinary text,
+// the icon in the tone's text shade, so the text keeps the page's
+// contrast and the icon clears 3:1 against the wash. Note is the default
+// (what "Callout" inserts).
+import { InfoIcon, LightbulbIcon, MessageSquareWarningIcon, OctagonAlertIcon, TriangleAlertIcon, } from 'lucide-react';
+/**
+ * Classes for written text's own elements. No colours on the headings:
+ * <Markdown> adds the text colour, and the editor's read-only text is
+ * muted as a whole.
+ */
+export const PROSE = {
+    /** `#`: the largest, with a rule under it, so it reads as the top of the outline. */
+    heading1: 'type-heading-1 mt-4 border-b border-border pb-1.5 first:mt-0',
+    heading2: 'type-heading-2 mt-3 first:mt-0',
+    heading3: 'type-heading-3 mt-1 first:mt-0',
+    /** `####` and deeper: a label, as before. */
+    heading4: 'type-label mt-1 first:mt-0',
+    /** Coloured as well as underlined. */
+    link: 'text-link underline decoration-link/40 underline-offset-4 transition-colors hover:decoration-link',
+    /** `---`: a 2px line in the rule tone, with room around it. */
+    rule: 'my-2 h-0.5 rounded-full border-0 bg-rule',
+};
+/** A heading's classes by its Markdown level (1 for `#`). */
+export function headingClass(level) {
+    return level === 1 ? PROSE.heading1 : level === 2 ? PROSE.heading2 : level === 3 ? PROSE.heading3 : PROSE.heading4;
+}
+export const CALLOUT_LOOK = {
+    note: { label: 'Note', icon: InfoIcon, box: 'bg-info/10 border-info/25', tint: 'text-info-text' },
+    tip: { label: 'Tip', icon: LightbulbIcon, box: 'bg-success/10 border-success/25', tint: 'text-success-text' },
+    important: {
+        label: 'Important',
+        icon: MessageSquareWarningIcon,
+        box: 'bg-category-2/10 border-category-2/25',
+        tint: 'text-category-2',
+    },
+    warning: { label: 'Warning', icon: TriangleAlertIcon, box: 'bg-warning/10 border-warning/25', tint: 'text-warning-text' },
+    caution: {
+        label: 'Caution',
+        icon: OctagonAlertIcon,
+        box: 'bg-destructive/10 border-destructive/25',
+        tint: 'text-destructive-text',
+    },
+};
+/** The box every callout shares: the icon in a column, the text beside it. */
+export const CALLOUT_BOX = 'flex gap-2.5 rounded-lg border px-3 py-2.5';

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

@@ -4,9 +4,21 @@ export type FormatItem = {
     id: FormatId;
     label: string;
     icon: LucideIcon;
-    /** Milkdown's own shortcut, as `aria-keyshortcuts` writes it with Mod for Ctrl/Cmd. */
+    /**
+     * Its shortcut, as `aria-keyshortcuts` writes it with Mod for Ctrl/Cmd,
+     * and Block for Notion's block keys (Ctrl+Shift, or Cmd+Option on a Mac).
+     */
     keys?: string;
     /** More for the tooltip than the shortcut. */
     hint?: string;
 };
 export declare const FORMAT_GROUPS: FormatItem[][];
+/** Every format by its id. */
+export declare const FORMAT_ITEMS: Map<FormatId, FormatItem>;
+/**
+ * A callout of each kind but the default, for the slash menu: "Warning
+ * callout". Not on the toolbar (its Callout makes a note).
+ */
+export declare const CALLOUT_VARIANTS: FormatItem[];
+/** Notion's block keys: the digit after Ctrl+Shift (Cmd+Option on a Mac), and its format. */
+export declare const BLOCK_KEYS: Record<string, FormatId>;