@tristan2828/ui-foundation 4.32.0 → 4.34.0

package/dist/components/app/markdown.js

@@ -1,11 +1,51 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// Long text written as Markdown, rendered to read: headings, lists, links,
+// tables (GitHub-flavoured), code and quotes, in the design language's
+// type roles and tokens. A record's notes on its view (EntityView) are the
+// first use.
+//
+// Safe by default, and kept that way on purpose:
+// - Raw HTML is never rendered. react-markdown escapes it, so `<b>` in the
+//   text shows as the characters `<b>`, never as markup, and nothing the
+//   author typed silently disappears. Never add rehype-raw.
+// - URLs go through react-markdown's default urlTransform, which drops
+//   `javascript:` and other unsafe protocols. A link left with no URL
+//   renders as its text.
+// - Links open in a new tab, so following one never leaves the record.
+//
+// Headings start at <h3> by default: the page owns the <h1> (the
+// record's title) and each section its <h2>, so a `# Heading` in the text
+// sits under them instead of competing with the page's own outline. Text
+// that sits elsewhere says so with `headingLevel`, the level `#` renders
+// as (2 straight under the page's <h1>), each level below it one deeper,
+// never past <h6>, so the page's outline never skips a level (axe's
+// heading-order). They look like what they are in the text, wherever they
+// sit: `#` and `##` on a tinted band, `###` a small uppercase label, and
+// the text under them lined up with the words in the band (prose-look.ts).
+//
+// A table wider than the text scrolls sideways, and while it does, its
+// box is a tab stop, named for its columns, that the arrow keys scroll
+// (prose-table-scroll.ts). Its cells wrap first, so that's only a table
+// with many columns, or a long word in one.
+//
+// An image (`![alt](url)`, one the rich-text editor uploaded) stays inside
+// the text's width, loads only as it nears the screen, and keeps its alt
+// text; with none (`![](url)`) it's decorative to a screen reader. Its
+// address goes through the same urlTransform: a web address or a path on
+// the site (`/api/files/7/content`), never `javascript:` or `data:`.
+//
+// A quote that starts `[!NOTE]` (GitHub's alert syntax) is a callout: a
+// tinted box with its kind's icon (src/lib/markdown-callout.ts).
+import { useEffect, useMemo, useRef } from 'react';
 import ReactMarkdown, {} from 'react-markdown';
 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';
 import { CALLOUT_KINDS, remarkCallouts } from '../../lib/markdown-callout.js';
-import { CALLOUT_BOX, CALLOUT_LOOK, headingClass, PROSE, PROSE_INSET } from './prose-look.js';
+import { textTopHeading } from '../../lib/markdown-top-heading.js';
+import { CALLOUT_BOX, CALLOUT_LOOK, DEFAULT_HEADING_LEVEL, headingBand, headingClass, headingTag, PROSE, PROSE_INSET, } from './prose-look.js';
+import { headerTexts, TABLE_SCROLL_FOCUS, watchTableScroll } from './prose-table-scroll.js';
 const REMARK_PLUGINS = [remarkGfm, remarkCallouts];
 function isCalloutKind(value) {
     return CALLOUT_KINDS.includes(value);
@@ -17,14 +57,31 @@ function omitNode(props) {
     delete rest.node;
     return rest;
 }
-// The text's colour first, so a level's own (`###`'s muted label) wins.
+// A GFM table in the package's own table, in its box that scrolls
+// sideways: a tab stop and a named region only while the table overflows
+// it. Watched again after each render, so a header row with new words
+// renames it.
+function NotesTable(props) {
+    const boxRef = useRef(null);
+    useEffect(() => {
+        const box = boxRef.current;
+        if (!box)
+            return;
+        const table = box.querySelector('table');
+        const region = watchTableScroll(box, table, headerTexts(table));
+        return () => region.destroy();
+    });
+    return (_jsx(Table, { ...props, containerRef: boxRef, containerClassName: cn('rounded-lg border border-border', TABLE_SCROLL_FOCUS) }));
+}
+// A heading by its Markdown level: the element the page's outline gives
+// it (headingTag), the look its level has. The text's colour first, so a
+// level's own (`###`'s muted label) wins.
+function heading(level, top, textTop) {
+    const Tag = headingTag(level, top, textTop);
+    return (props) => (_jsx(Tag, { ...omitNode(props), "data-band": headingBand(level) || undefined, className: cn('text-foreground', headingClass(level)) }));
+}
+// Everything but the headings, which follow `headingLevel` (componentsFor).
 const COMPONENTS = {
-    h1: (props) => _jsx("h3", { ...omitNode(props), className: cn('text-foreground', headingClass(1)) }),
-    h2: (props) => _jsx("h4", { ...omitNode(props), className: cn('text-foreground', headingClass(2)) }),
-    h3: (props) => _jsx("h5", { ...omitNode(props), className: cn('text-foreground', headingClass(3)) }),
-    h4: (props) => _jsx("h6", { ...omitNode(props), className: cn('text-foreground', headingClass(4)) }),
-    h5: (props) => _jsx("h6", { ...omitNode(props), className: cn('text-foreground', headingClass(5)) }),
-    h6: (props) => _jsx("h6", { ...omitNode(props), className: cn('text-foreground', headingClass(6)) }),
     a: (props) => {
         const { href, children, ...rest } = omitNode(props);
         if (!href)
@@ -65,7 +122,7 @@ 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), containerClassName: "rounded-lg border border-border" }),
+    table: (props) => _jsx(NotesTable, { ...omitNode(props) }),
     thead: (props) => _jsx(TableHeader, { ...omitNode(props), className: "bg-muted" }),
     tbody: (props) => _jsx(TableBody, { ...omitNode(props) }),
     tr: (props) => _jsx(TableRow, { ...omitNode(props) }),
@@ -74,6 +131,22 @@ const COMPONENTS = {
     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', PROSE_INSET, className), children: _jsx(ReactMarkdown, { remarkPlugins: REMARK_PLUGINS, components: COMPONENTS, children: children }) }));
+// The components for each `headingLevel` and level that takes it (`#`,
+// or the text's highest with `headingFrom="text"`), made once each.
+const BY_LEVEL = new Map();
+function componentsFor(top, textTop) {
+    const key = `${top}:${textTop}`;
+    let components = BY_LEVEL.get(key);
+    if (!components) {
+        components = { ...COMPONENTS };
+        for (const level of [1, 2, 3, 4, 5, 6])
+            components[`h${level}`] = heading(level, top, textTop);
+        BY_LEVEL.set(key, components);
+    }
+    return components;
+}
+export function Markdown({ children, headingLevel = DEFAULT_HEADING_LEVEL, headingFrom = 'hash', className, ...rest }) {
+    const textTop = useMemo(() => (headingFrom === 'text' ? textTopHeading(children) : 1), [headingFrom, children]);
+    const components = useMemo(() => componentsFor(headingLevel, textTop), [headingLevel, textTop]);
+    return (_jsx("div", { "data-slot": "markdown", ...rest, className: cn('flex min-w-0 flex-col gap-3 type-body text-foreground break-words', PROSE_INSET, className), children: _jsx(ReactMarkdown, { remarkPlugins: REMARK_PLUGINS, components: components, children: children }) }));
 }

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

@@ -1,2 +1,2 @@
 import type { RichTextEditorProps } from './rich-text-editor.js';
-export default function MilkdownEditor({ id, defaultValue, onChange, onProblem, readOnly, autoFocus, placeholder, maxLength, toolbar, inline, upload, imageAccept, imageMaxSize, 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, inline, upload, imageAccept, imageMaxSize, headingLevel, headingFrom, 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

@@ -13,11 +13,15 @@ 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>; they look like <Markdown>'s (prose-look.ts). A task-list item
-//   renders a real checkbox that toggles it.
+//   <h2>. `headingLevel` moves them to where the field sits in the page's
+//   outline, as it does <Markdown>'s; only the element moves, never the
+//   level the Markdown is saved with (a node view draws it, from the
+//   node's own level). 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
+// - Tables in a box that scrolls sideways (a tab stop the arrow keys
+//   scroll while it does: rich-text-node-views.ts), 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.
@@ -65,8 +69,9 @@ import { acceptAttribute } from '../../lib/image-file.js';
 import { linkHref, linkRefusal } from '../../lib/link-href.js';
 import { passEscapeThrough } from './escape-passthrough.js';
 import { calloutHandler, remarkCalloutNodes } from '../../lib/markdown-callout.js';
+import { textTopHeading } from '../../lib/markdown-top-heading.js';
 import { MarkdownMergeError, markdownStyle, mergeMarkdown } from '../../lib/markdown-merge.js';
-import { headingClass } from './prose-look.js';
+import { DEFAULT_HEADING_LEVEL, headingBand, headingClass, headingTag } from './prose-look.js';
 import { RichTextFloatingToolbar } from './rich-text-floating-toolbar.js';
 import { tableAt, toggleFormat } from './rich-text-formats.js';
 import { calloutKind, calloutView, tableView } from './rich-text-node-views.js';
@@ -138,10 +143,14 @@ function htmlToText(fragment) {
     });
     return Fragment.fromArray(nodes);
 }
-function headingView(node) {
+// A heading: the element `headingLevel` gives its level, the look its
+// level has. Marked as a band for PROSE_INSET (`#` and `##`).
+function headingView(node, top, textTop) {
     const level = Number(node.attrs.level);
-    const dom = document.createElement(`h${Math.min(level + 2, 6)}`);
+    const dom = document.createElement(headingTag(level, top, textTop));
     dom.className = headingClass(level);
+    if (headingBand(level))
+        dom.dataset.band = '';
     return {
         dom,
         contentDOM: dom,
@@ -253,7 +262,7 @@ function applyLink(view, target, href) {
     }
     view.dispatch(tr.scrollIntoView());
 }
-export default function MilkdownEditor({ id, defaultValue, onChange, onProblem, readOnly = false, autoFocus = false, placeholder, maxLength, toolbar = true, inline = false, upload, imageAccept, imageMaxSize, className, 'aria-label': ariaLabel, 'aria-labelledby': ariaLabelledBy, 'aria-describedby': ariaDescribedBy, 'aria-invalid': ariaInvalid, }) {
+export default function MilkdownEditor({ id, defaultValue, onChange, onProblem, readOnly = false, autoFocus = false, placeholder, maxLength, toolbar = true, inline = false, upload, imageAccept, imageMaxSize, headingLevel = DEFAULT_HEADING_LEVEL, headingFrom = 'hash', 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);
@@ -342,6 +351,8 @@ export default function MilkdownEditor({ id, defaultValue, onChange, onProblem,
         if (!root)
             return;
         const original = defaultValue;
+        // The level that takes headingLevel, read from the text it loads.
+        const textTop = headingFrom === 'text' ? textTopHeading(original) : 1;
         let baseline = null;
         let cancelled = false;
         const emit = () => {
@@ -616,9 +627,10 @@ export default function MilkdownEditor({ id, defaultValue, onChange, onProblem,
                     return mod && !event.shiftKey && !event.altKey && event.key === 'Enter' && isInTable(view.state);
                 },
                 nodeViews: {
-                    heading: headingView,
+                    // The level when it mounts, as with defaultValue.
+                    heading: (node) => headingView(node, headingLevel, textTop),
                     callout: (node, _view, getPos) => calloutView(node, getPos, registry),
-                    table: (_node, _view, getPos) => tableView(getPos, registry),
+                    table: (node, view, getPos) => tableView(node, view, getPos, registry),
                     list_item: (node, view, getPos) => node.attrs.checked == null ? undefined : taskItemView(node, view, getPos),
                 },
             }));
@@ -792,7 +804,7 @@ export default function MilkdownEditor({ id, defaultValue, onChange, onProblem,
                         '[&_.ProseMirror]:flex [&_.ProseMirror]:flex-col [&_.ProseMirror]:gap-3', 
                         // PROSE_INSET, on the editable element: with a heading's band
                         // in the text, the rest lines up with the words in it.
-                        '[&_.ProseMirror:has(>:is(h3,h4))>:not(h3,h4)]:mx-3', !inline && '[&_.ProseMirror]:min-h-20', 
+                        '[&_.ProseMirror:has(>[data-band])>:not([data-band])]:mx-3', !inline && '[&_.ProseMirror]:min-h-20', 
                         // 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', '[&_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', 

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

@@ -27,13 +27,42 @@ export declare const PROSE: {
     readonly rule: "my-2 h-0.5 rounded-full border-0 bg-rule";
 };
 /**
- * On the text's container: when it has a band (the `<h3>` or `<h4>` a `#`
- * or `##` renders as), everything else is inset by the band's 12px
- * padding, so the text lines up with the words in the band. Text with no
- * band stays flush, where the section's own text starts. A margin, so a
- * list's own indent and a table's or callout's box keep theirs.
+ * On the text's container: when it has a band (a `#` or `##`, marked
+ * `data-band`, whatever element its `headingLevel` makes it), everything
+ * else is inset by the band's 12px padding, so the text lines up with the
+ * words in the band. Text with no band stays flush, where the section's
+ * own text starts. A margin, so a list's own indent and a table's or
+ * callout's box keep theirs.
  */
-export declare const PROSE_INSET = "[&:has(>:is(h3,h4))>:not(h3,h4)]:mx-3";
+export declare const PROSE_INSET = "[&:has(>[data-band])>:not([data-band])]:mx-3";
+/**
+ * The HTML level a heading in the text can render as. `headingLevel` on
+ * <Markdown> and the editor is the one `#` renders as: where the text
+ * sits in the page's outline (2 straight under the page's <h1>, 3 under a
+ * section's <h2>, the default).
+ */
+export type HeadingLevel = 1 | 2 | 3 | 4 | 5 | 6;
+/** `#` renders as an <h3>: the page owns the <h1> and each section its <h2>. */
+export declare const DEFAULT_HEADING_LEVEL: HeadingLevel;
+/**
+ * Which heading in the text takes `headingLevel`: `'hash'` (the default),
+ * `#`, whatever the text holds; `'text'`, the text's own highest heading,
+ * so notes that start at `##` (an export from Notion, a README) put their
+ * first heading straight under the page's, not a level further down.
+ */
+export type HeadingFrom = 'hash' | 'text';
+/**
+ * The element a heading renders as, by its Markdown level (1 for `#`) and
+ * the level `#` renders as: `##` one below it, `###` two below, and so on,
+ * never past <h6>. `textTop` is the level that renders at `top` instead
+ * of `#` (`headingFrom="text"`: the text's highest), and a heading above
+ * it renders at `top` too. Only the element follows the page; the look
+ * (the band, the label) stays the Markdown level's (headingClass), so a
+ * `#` looks like a `#` wherever it sits.
+ */
+export declare function headingTag(level: number, top?: HeadingLevel, textTop?: number): `h${HeadingLevel}`;
+/** Whether a heading sits on a band (`#` and `##`): the text beside it is inset (PROSE_INSET). */
+export declare function headingBand(level: number): boolean;
 /** A heading's classes by its Markdown level (1 for `#`). */
 export declare function headingClass(level: number): string;
 export type CalloutLook = {

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

@@ -33,13 +33,34 @@ export const PROSE = {
     rule: 'my-2 h-0.5 rounded-full border-0 bg-rule',
 };
 /**
- * On the text's container: when it has a band (the `<h3>` or `<h4>` a `#`
- * or `##` renders as), everything else is inset by the band's 12px
- * padding, so the text lines up with the words in the band. Text with no
- * band stays flush, where the section's own text starts. A margin, so a
- * list's own indent and a table's or callout's box keep theirs.
+ * On the text's container: when it has a band (a `#` or `##`, marked
+ * `data-band`, whatever element its `headingLevel` makes it), everything
+ * else is inset by the band's 12px padding, so the text lines up with the
+ * words in the band. Text with no band stays flush, where the section's
+ * own text starts. A margin, so a list's own indent and a table's or
+ * callout's box keep theirs.
  */
-export const PROSE_INSET = '[&:has(>:is(h3,h4))>:not(h3,h4)]:mx-3';
+export const PROSE_INSET = '[&:has(>[data-band])>:not([data-band])]:mx-3';
+/** `#` renders as an <h3>: the page owns the <h1> and each section its <h2>. */
+export const DEFAULT_HEADING_LEVEL = 3;
+/**
+ * The element a heading renders as, by its Markdown level (1 for `#`) and
+ * the level `#` renders as: `##` one below it, `###` two below, and so on,
+ * never past <h6>. `textTop` is the level that renders at `top` instead
+ * of `#` (`headingFrom="text"`: the text's highest), and a heading above
+ * it renders at `top` too. Only the element follows the page; the look
+ * (the band, the label) stays the Markdown level's (headingClass), so a
+ * `#` looks like a `#` wherever it sits.
+ */
+export function headingTag(level, top = DEFAULT_HEADING_LEVEL, textTop = 1) {
+    const markdown = Math.max(1, Math.floor(level) || 1);
+    const below = Math.max(0, markdown - Math.max(1, Math.floor(textTop) || 1));
+    return `h${Math.min(top + below, 6)}`;
+}
+/** Whether a heading sits on a band (`#` and `##`): the text beside it is inset (PROSE_INSET). */
+export function headingBand(level) {
+    return level <= 2;
+}
 /** 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;

package/dist/components/app/prose-table-scroll.d.ts

@@ -0,0 +1,33 @@
+/** The box's focus ring, from the semantic tokens: on the box's own classes. */
+export declare const TABLE_SCROLL_FOCUS = "outline-none focus-visible:ring-3 focus-visible:ring-ring/50";
+/**
+ * The region's accessible name: "Table, scrolls sideways", then the
+ * header row's first few columns ("…: Part, Width, Depth"). Empty
+ * headers are skipped; with none, the phrase alone.
+ */
+export declare function tableScrollName(columns: readonly string[]): string;
+/** What the box needs of its element: as much as tests can fake. */
+type ScrollBox = Pick<HTMLElement, 'scrollWidth' | 'clientWidth' | 'setAttribute' | 'removeAttribute' | 'getAttribute'>;
+export type TableScrollRegion = {
+    /** The header row's texts, for the name: called again when they change (the editor's edits). */
+    setColumns: (columns: readonly string[]) => void;
+    /** Checks again whether the table overflows. The observers call it; a test can too. */
+    check: () => void;
+    /**
+     * Takes the tab stop off until `resume`, the rest kept: for a press in
+     * the editor's box, whose focus belongs to the text, not the box.
+     */
+    suspend: () => void;
+    resume: () => void;
+    /** Stops watching. The box keeps whatever it last was. */
+    destroy: () => void;
+};
+/**
+ * Watches a table's scroll box: a tab stop and a named region while the
+ * table is wider than the box, nothing while it fits. `table` is what
+ * scrolls in it (observed for its size; the box alone when absent).
+ */
+export declare function watchTableScroll(box: ScrollBox, table?: Element | null, columns?: readonly string[]): TableScrollRegion;
+/** A rendered table's header row, as texts: the header cells of its first row. */
+export declare function headerTexts(table: Element | null | undefined): string[];
+export {};

package/dist/components/app/prose-table-scroll.js

@@ -0,0 +1,87 @@
+// A table in written text, <Markdown>'s or the editor's, sits in a box
+// that scrolls sideways when the table is wider than the text. A box that
+// scrolls has to be reachable from the keyboard (axe's
+// scrollable-region-focusable), or someone without a mouse can never see
+// its right-hand columns. So, only while the table overflows, the box is
+// a tab stop and a named region: "Table, scrolls sideways", then its
+// columns, which tell two tables on a page apart (two regions with one
+// name are axe's landmark-unique) and say which table it is. With the
+// arrow keys it then scrolls. A table that fits is left alone: no tab
+// stop and no region, nothing to reach that does nothing.
+//
+// It follows the table: a ResizeObserver on the box (the text's width
+// changing) and on the table (a column added, a cell's text growing)
+// checks again each time either changes size.
+/** The box's focus ring, from the semantic tokens: on the box's own classes. */
+export const TABLE_SCROLL_FOCUS = 'outline-none focus-visible:ring-3 focus-visible:ring-ring/50';
+// The columns named in the region's name; past them, an ellipsis.
+const NAMED_COLUMNS = 3;
+/**
+ * The region's accessible name: "Table, scrolls sideways", then the
+ * header row's first few columns ("…: Part, Width, Depth"). Empty
+ * headers are skipped; with none, the phrase alone.
+ */
+export function tableScrollName(columns) {
+    const named = columns.map((column) => column.replace(/\s+/g, ' ').trim()).filter(Boolean);
+    if (named.length === 0)
+        return 'Table, scrolls sideways';
+    const shown = named.slice(0, NAMED_COLUMNS).join(', ');
+    return `Table, scrolls sideways: ${shown}${named.length > NAMED_COLUMNS ? ', …' : ''}`;
+}
+// Set only when it differs, so a check that finds nothing new writes
+// nothing (the editor reads its own DOM's mutations).
+function set(box, name, value) {
+    if (box.getAttribute(name) === value)
+        return;
+    if (value === null)
+        box.removeAttribute(name);
+    else
+        box.setAttribute(name, value);
+}
+/**
+ * Watches a table's scroll box: a tab stop and a named region while the
+ * table is wider than the box, nothing while it fits. `table` is what
+ * scrolls in it (observed for its size; the box alone when absent).
+ */
+export function watchTableScroll(box, table, columns = []) {
+    let name = tableScrollName(columns);
+    let suspended = false;
+    const check = () => {
+        // scrollWidth counts what's hidden past the right edge; the two are
+        // whole pixels, so a table that just fits measures equal.
+        const overflows = box.scrollWidth > box.clientWidth;
+        set(box, 'tabindex', overflows && !suspended ? '0' : null);
+        set(box, 'role', overflows ? 'region' : null);
+        set(box, 'aria-label', overflows ? name : null);
+    };
+    // Server rendering and tests have no ResizeObserver: one check, then
+    // whatever the box was.
+    const observer = typeof ResizeObserver === 'undefined' ? null : new ResizeObserver(check);
+    if (observer) {
+        observer.observe(box);
+        if (table)
+            observer.observe(table);
+    }
+    check();
+    return {
+        setColumns: (next) => {
+            name = tableScrollName(next);
+            check();
+        },
+        check,
+        suspend: () => {
+            suspended = true;
+            check();
+        },
+        resume: () => {
+            suspended = false;
+            check();
+        },
+        destroy: () => observer?.disconnect(),
+    };
+}
+/** A rendered table's header row, as texts: the header cells of its first row. */
+export function headerTexts(table) {
+    const row = table?.querySelector('tr');
+    return row ? Array.from(row.querySelectorAll('th'), (cell) => cell.textContent ?? '') : [];
+}

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

@@ -1,4 +1,5 @@
 import type { ImageUpload } from '../../lib/image-file.js';
+import type { HeadingFrom, HeadingLevel } from './prose-look.js';
 export type RichTextEditorProps = {
     /** The editable element's id, for a label's `htmlFor` or a test. */
     id?: string;
@@ -52,6 +53,22 @@ export type RichTextEditorProps = {
     imageAccept?: readonly string[];
     /** The largest image `upload` takes, in bytes: a bigger one is refused before it's sent, with its size and the limit. */
     imageMaxSize?: number;
+    /**
+     * The HTML level the text's `#` renders as, where the field sits in the
+     * page's outline: 2 straight under the page's <h1> (a form), 3 (the
+     * default) under a section's <h2>. `##` is one below it, `###` two
+     * below, never past <h6>, as in `<Markdown>`. Only the element changes:
+     * the look, and the Markdown saved (`#` stays `#`), don't. Read once,
+     * when it mounts.
+     */
+    headingLevel?: HeadingLevel;
+    /**
+     * Which heading takes `headingLevel`: `'hash'` (the default), `#`;
+     * `'text'`, the text's own highest when it mounts, for notes that start
+     * at `##`, as in `<Markdown>`. A heading added above it renders at
+     * `headingLevel` too. The Markdown saved is never rewritten.
+     */
+    headingFrom?: HeadingFrom;
     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

@@ -13,6 +13,11 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 // Raw HTML in the text shows as its characters, as <Markdown> shows it,
 // and nothing pasted or typed can add markup.
 //
+// Headings in the text sit under the page's outline (`headingLevel`, from
+// <h3> by default), as <Markdown>'s do. A table wider than the field
+// scrolls sideways, and while it does, its box is a tab stop the arrow
+// keys scroll.
+//
 // Images in the text (`![alt](url)`) show, at most the field's width.
 // With `upload`, an image pasted, dropped or picked with the toolbar's
 // Image button is uploaded through the app's own storage and goes in as

package/dist/components/app/rich-text-node-views.d.ts

@@ -1,5 +1,5 @@
 import type { Node as ProseNode } from '@milkdown/kit/prose/model';
-import type { NodeView } from '@milkdown/kit/prose/view';
+import type { EditorView, NodeView } from '@milkdown/kit/prose/view';
 import { type CalloutKind } from '../../lib/markdown-callout.js';
 /** A slot a node view has, for the editor to render its widget into. */
 export type Widget = {
@@ -26,6 +26,9 @@ export declare function calloutView(node: ProseNode, getPos: () => number | unde
 /**
  * A table: in a box that scrolls sideways when it's wider than the text,
  * with an "add a column" bar along its right and an "add a row" bar under
- * it (widgets), Notion's way.
+ * it (widgets), Notion's way. While it scrolls, the box is a tab stop and
+ * a region named for its columns (prose-table-scroll.ts), which the arrow
+ * keys, Home and End scroll; a click in it still puts the caret in the
+ * cell clicked.
  */
-export declare function tableView(getPos: () => number | undefined, registry: WidgetRegistry): NodeView;
+export declare function tableView(node: ProseNode, view: EditorView, getPos: () => number | undefined, registry: WidgetRegistry): NodeView;

package/dist/components/app/rich-text-node-views.js

@@ -1,6 +1,7 @@
 import { cn } from 'cn';
 import { CALLOUT_KINDS } from '../../lib/markdown-callout.js';
 import { CALLOUT_BOX, CALLOUT_LOOK } from './prose-look.js';
+import { TABLE_SCROLL_FOCUS, watchTableScroll } from './prose-table-scroll.js';
 // Each slot's key for its portal, for as long as the node view lives.
 let made = 0;
 const nextKey = () => `widget-${++made}`;
@@ -49,17 +50,55 @@ export function calloutView(node, getPos, registry) {
         destroy: () => registry.remove(icon),
     };
 }
+// A table's header row, as texts, from the node (its first row's cells).
+function columnsOf(node) {
+    const header = node.firstChild;
+    if (!header)
+        return [];
+    const columns = [];
+    header.forEach((cell) => columns.push(cell.textContent));
+    return columns;
+}
+// How far an arrow key scrolls the table's box.
+const SCROLL_STEP = 40;
+// The keys a focused table box takes: the arrow keys, Home and End scroll
+// it, as a box that isn't editable scrolls by itself, and any other plain
+// key adds nothing (the text can't be typed into from the table's frame).
+// Tab, Esc and shortcuts are left alone: Tab leaves the box, Esc and the
+// shortcuts go on to the field. True when it took the key.
+function scrollKey(box, event) {
+    if (event.ctrlKey || event.metaKey || event.altKey || event.key === 'Tab' || event.key === 'Escape')
+        return false;
+    const max = box.scrollWidth - box.clientWidth;
+    const to = {
+        ArrowLeft: box.scrollLeft - SCROLL_STEP,
+        ArrowRight: box.scrollLeft + SCROLL_STEP,
+        Home: 0,
+        End: max,
+    };
+    const target = to[event.key];
+    if (target !== undefined)
+        box.scrollLeft = Math.min(Math.max(target, 0), max);
+    event.preventDefault();
+    return true;
+}
+// How long a press keeps the box out of the tab order: until the click it
+// starts, or this long for one that never clicks (a touch that pans).
+const PRESS_MS = 1000;
 /**
  * A table: in a box that scrolls sideways when it's wider than the text,
  * with an "add a column" bar along its right and an "add a row" bar under
- * it (widgets), Notion's way.
+ * it (widgets), Notion's way. While it scrolls, the box is a tab stop and
+ * a region named for its columns (prose-table-scroll.ts), which the arrow
+ * keys, Home and End scroll; a click in it still puts the caret in the
+ * cell clicked.
  */
-export function tableView(getPos, registry) {
+export function tableView(node, view, getPos, registry) {
     const dom = document.createElement('div');
     dom.dataset.slot = 'rich-text-table';
     dom.className = 'group/table grid grid-cols-[minmax(0,1fr)_auto] gap-1';
     const scroll = document.createElement('div');
-    scroll.className = 'overflow-x-auto rounded-lg border border-border';
+    scroll.className = cn('overflow-x-auto rounded-lg border border-border', TABLE_SCROLL_FOCUS);
     const table = document.createElement('table');
     const contentDOM = document.createElement('tbody');
     table.append(contentDOM);
@@ -68,12 +107,76 @@ export function tableView(getPos, registry) {
     const row = slot('col-start-1 flex h-5');
     dom.append(scroll, column, row);
     registry.set({ type: 'table', key: nextKey(), slot: row, column, getPos });
+    const region = watchTableScroll(scroll, table, columnsOf(node));
+    // A press in the box is the text's: a click in a cell puts the caret
+    // there. The browser focuses the nearest focusable ancestor of what was
+    // pressed, which would be the box while it's a tab stop, so the box
+    // leaves the tab order from the press to its click.
+    let pressing;
+    const released = () => {
+        clearTimeout(pressing);
+        pressing = undefined;
+        document.removeEventListener('click', releasedSoon, true);
+        region.resume();
+    };
+    const releasedSoon = () => setTimeout(released);
+    const onPointerDown = (event) => {
+        if (event.target === scroll && event.pointerType === 'mouse')
+            return; // its own scrollbar
+        region.suspend();
+        clearTimeout(pressing);
+        pressing = setTimeout(released, PRESS_MS);
+        document.addEventListener('click', releasedSoon, { capture: true, once: true });
+    };
+    scroll.addEventListener('pointerdown', onPointerDown);
+    // A key pressed while the box has focus is the box's (scrollKey), never
+    // ProseMirror's. It comes one of two ways. To the box itself, when the
+    // text's selection is outside it. Or, when the browser first moves
+    // focus to the editable text around it (as it can for a box inside
+    // editable text), to the text: then the box's blur to the text marks
+    // the key that follows in the same moment as the box's, and focus goes
+    // back to it.
+    const onBoxKey = (event) => {
+        if (event.target === scroll && scrollKey(scroll, event))
+            event.stopPropagation();
+    };
+    let bounced = false;
+    const onBlur = (event) => {
+        if (event.relatedTarget !== view.dom)
+            return;
+        bounced = true;
+        setTimeout(() => (bounced = false));
+    };
+    const onKeyDown = (event) => {
+        if (!bounced)
+            return;
+        bounced = false;
+        scroll.focus({ preventScroll: true });
+        if (scrollKey(scroll, event))
+            event.stopImmediatePropagation();
+    };
+    scroll.addEventListener('keydown', onBoxKey);
+    scroll.addEventListener('blur', onBlur);
+    view.dom.addEventListener('keydown', onKeyDown, true);
     return {
         dom,
         contentDOM,
-        update: (next) => next.type.name === 'table',
+        update: (next) => {
+            if (next.type.name !== 'table')
+                return false;
+            region.setColumns(columnsOf(next));
+            return true;
+        },
         stopEvent: (event) => row.contains(event.target) || column.contains(event.target),
         ignoreMutation: outside(contentDOM),
-        destroy: () => registry.remove(row),
+        destroy: () => {
+            released();
+            region.destroy();
+            scroll.removeEventListener('pointerdown', onPointerDown);
+            scroll.removeEventListener('blur', onBlur);
+            scroll.removeEventListener('keydown', onBoxKey);
+            view.dom.removeEventListener('keydown', onKeyDown, true);
+            registry.remove(row);
+        },
     };
 }