@tristan2828/ui-foundation 4.53.0 → 4.54.0

package/dist/components/app/markdown.d.ts

@@ -17,6 +17,15 @@ export type MarkdownProps = {
      * itself is never rewritten.
      */
     headingFrom?: HeadingFrom;
+    /**
+     * Folds the text by its headings: each heading at its top level gets a
+     * button that folds what's under it (to the next heading of its level
+     * or higher). What's folded is remembered on this device under this key
+     * (name it for the app and the record: `"my-app:task:84:notes"`), and
+     * shared with a RichTextEditor or NotesOutline given the same key. The
+     * text is never changed.
+     */
+    foldKey?: string;
     className?: string;
 } & Omit<ComponentProps<'div'>, 'children'>;
-export declare function Markdown({ children, headingLevel, headingFrom, className, ...rest }: MarkdownProps): import("react").JSX.Element;
+export declare function Markdown({ children, headingLevel, headingFrom, foldKey, className, ...rest }: MarkdownProps): import("react").JSX.Element;

package/dist/components/app/markdown.js

@@ -39,16 +39,23 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 //
 // `==words==` is highlighted words (amber, or `=={green}words==`: yellow,
 // green, red): a <mark> on the colour's wash (src/lib/markdown-highlight.ts).
-import { useEffect, useMemo, useRef } from 'react';
+//
+// With `foldKey`, each heading at the text's top level has a button before
+// it that folds its section away (src/lib/markdown-fold.ts), remembered on
+// this device under the key and shared with an editor or NotesOutline
+// given the same one. The text itself is never changed.
+import { createContext, useCallback, useContext, 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 { ChevronDownIcon, ExternalLinkIcon, SquareCheckIcon, SquareIcon } from 'lucide-react';
 import { Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from '../ui/table.js';
+import { useFolds } from '../../hooks/fold-store.js';
 import { CALLOUT_KINDS, remarkCallouts } from '../../lib/markdown-callout.js';
+import { rehypeFold, toggleFold } from '../../lib/markdown-fold.js';
 import { isHighlightColor, remarkHighlights } from '../../lib/markdown-highlight.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 { CALLOUT_BOX, CALLOUT_LOOK, DEFAULT_HEADING_LEVEL, FOLD_BUTTON, FOLD_HEADING, 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, remarkHighlights];
 const HIGHLIGHT_WASH = {
@@ -71,7 +78,7 @@ function omitNode(props) {
 // 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) {
+function NotesTable({ hidden, ...props }) {
     const boxRef = useRef(null);
     useEffect(() => {
         const box = boxRef.current;
@@ -81,14 +88,30 @@ function NotesTable(props) {
         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) }));
+    return (_jsx(Table, { ...props, containerRef: boxRef, 
+        // Folded away, the box goes with the table.
+        containerClassName: cn('rounded-lg border border-border', TABLE_SCROLL_FOCUS, hidden && 'hidden') }));
 }
+// Folds a section by its heading's id: given only with `foldKey`.
+const FoldContext = createContext(null);
 // 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.
+// level's own (`###`'s muted label) wins. With `foldKey`, a top-level one
+// (marked by rehypeFold) sits beside its fold button, the look on the two
+// together; one with nothing under it keeps the button's room, so its
+// words line up with the others'.
 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)) }));
+    return function Heading(props) {
+        const toggle = useContext(FoldContext);
+        const { 'data-fold-id': foldId, 'data-foldable': foldable, 'data-folded': folded, 'data-fold-label': label, hidden, ...rest } = omitNode(props);
+        const look = cn('text-foreground', headingClass(level));
+        const band = headingBand(level) || undefined;
+        if (!toggle || foldId === undefined)
+            return _jsx(Tag, { ...rest, hidden: hidden, "data-band": band, className: look });
+        const open = folded !== 'true';
+        return (_jsxs("div", { "data-fold-id": foldId, hidden: hidden, "data-band": band, className: cn(FOLD_HEADING, look), children: [foldable === 'true' ? (_jsx("button", { type: "button", "aria-expanded": open, "aria-label": label || 'Section', "data-slot": "fold-button", className: FOLD_BUTTON, onClick: () => toggle(foldId), children: _jsx(ChevronDownIcon, { "aria-hidden": "true", className: cn('size-4 transition-transform', !open && '-rotate-90') }) })) : (_jsx("span", { "aria-hidden": "true", className: "-ml-1 w-5 shrink-0" })), _jsx(Tag, { ...rest, className: "min-w-0 flex-1" })] }));
+    };
 }
 // Everything but the headings, which follow `headingLevel` (componentsFor).
 const COMPONENTS = {
@@ -112,7 +135,7 @@ const COMPONENTS = {
     // state in words, never a checkbox someone will try to tick.
     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: PROSE.rule }),
+    hr: ({ hidden }) => _jsx("hr", { hidden: hidden, className: PROSE.rule }),
     // Highlighted words (remarkHighlights marks them): the colour's wash.
     mark: (props) => {
         const { children, ...rest } = omitNode(props);
@@ -128,7 +151,7 @@ const COMPONENTS = {
             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] })] }));
+        return (_jsxs("div", { role: "note", "data-callout": kind, hidden: rest.hidden, 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" }),
@@ -161,8 +184,11 @@ function componentsFor(top, textTop) {
     }
     return components;
 }
-export function Markdown({ children, headingLevel = DEFAULT_HEADING_LEVEL, headingFrom = 'hash', className, ...rest }) {
+export function Markdown({ children, headingLevel = DEFAULT_HEADING_LEVEL, headingFrom = 'hash', foldKey, 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 }) }));
+    const [folded, setFolded] = useFolds(foldKey);
+    const rehypePlugins = useMemo(() => (foldKey === undefined ? [] : [[rehypeFold, { folded }]]), [foldKey, folded]);
+    const toggle = useCallback((id) => setFolded(toggleFold(folded, id)), [folded, setFolded]);
+    return (_jsx("div", { "data-slot": "markdown", "data-fold-scope": foldKey, ...rest, className: cn('flex min-w-0 flex-col gap-3 type-body text-foreground break-words', PROSE_INSET, className), children: _jsx(FoldContext.Provider, { value: foldKey === undefined ? null : toggle, children: _jsx(ReactMarkdown, { remarkPlugins: REMARK_PLUGINS, rehypePlugins: rehypePlugins, 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, headingLevel, headingFrom, 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, foldKey, 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

@@ -48,6 +48,9 @@ import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-run
 //   With `upload`, an image pasted, dropped or picked with the toolbar's
 //   Image button is uploaded through it and goes in as `![](url)`
 //   (rich-text-image-upload.ts); a refusal or a failed upload is a toast.
+// - `foldKey`: the text folds by its headings, as <Markdown> does
+//   (rich-text-fold.ts), remembered on this device and shared with
+//   NotesOutline; the document never changes.
 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';
@@ -72,7 +75,10 @@ import { calloutHandler, remarkCalloutNodes } from '../../lib/markdown-callout.j
 import { DEFAULT_HIGHLIGHT, highlightHandler, isHighlightColor, remarkHighlightNodes } from '../../lib/markdown-highlight.js';
 import { textTopHeading } from '../../lib/markdown-top-heading.js';
 import { MarkdownMergeError, markdownStyle, mergeMarkdown } from '../../lib/markdown-merge.js';
-import { DEFAULT_HEADING_LEVEL, headingBand, headingClass, headingTag } from './prose-look.js';
+import { foldStore, listenForOtherTabs } from '../../hooks/fold-store.js';
+import { toggleFold } from '../../lib/markdown-fold.js';
+import { DEFAULT_HEADING_LEVEL, FOLD_BUTTON, FOLD_HEADING, headingBand, headingClass, headingTag } from './prose-look.js';
+import { foldPlugin, foldSpecOf, setFolds } from './rich-text-fold.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';
@@ -177,16 +183,69 @@ function htmlToText(fragment) {
 }
 // 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) {
+//
+// With `foldKey` (`onFold`), it sits beside its fold button, as in
+// <Markdown>: the look on the two together, the button out of the tab
+// order (Ctrl/Cmd+Alt+[ and ] and NotesOutline are the keyboard's way),
+// kept invisible where there's nothing under the heading to fold, or the
+// heading isn't at the top level.
+function headingView(node, top, textTop, decorations, onFold) {
     const level = Number(node.attrs.level);
-    const dom = document.createElement(headingTag(level, top, textTop));
-    dom.className = headingClass(level);
+    const heading = document.createElement(headingTag(level, top, textTop));
+    const sameLevel = (next) => next.type === node.type && next.attrs.level === node.attrs.level;
+    if (!onFold) {
+        heading.className = headingClass(level);
+        if (headingBand(level))
+            heading.dataset.band = '';
+        return { dom: heading, contentDOM: heading, update: sameLevel };
+    }
+    const dom = document.createElement('div');
+    dom.className = cn(FOLD_HEADING, headingClass(level));
     if (headingBand(level))
         dom.dataset.band = '';
+    heading.className = 'min-w-0 flex-1';
+    const button = document.createElement('button');
+    button.type = 'button';
+    button.tabIndex = -1;
+    button.contentEditable = 'false';
+    button.dataset.slot = 'fold-button';
+    const chevron = document.createElementNS('http://www.w3.org/2000/svg', 'svg');
+    chevron.setAttribute('viewBox', '0 0 24 24');
+    chevron.setAttribute('aria-hidden', 'true');
+    chevron.innerHTML =
+        '<path d="m6 9 6 6 6-6" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" />';
+    button.append(chevron);
+    dom.append(button, heading);
+    let spec = null;
+    const render = (decorations) => {
+        spec = foldSpecOf(decorations);
+        button.className = cn(FOLD_BUTTON, !spec?.foldable && 'invisible');
+        chevron.setAttribute('class', cn('size-4 transition-transform', spec?.folded && '-rotate-90'));
+        button.setAttribute('aria-expanded', String(!spec?.folded));
+        button.setAttribute('aria-label', spec?.label || 'Section');
+        if (spec)
+            dom.dataset.foldId = spec.id;
+        else
+            delete dom.dataset.foldId;
+    };
+    render(decorations);
+    // A press keeps the caret where it is.
+    button.addEventListener('mousedown', (event) => event.preventDefault());
+    button.addEventListener('click', () => {
+        if (spec?.foldable)
+            onFold(spec.id);
+    });
     return {
         dom,
-        contentDOM: dom,
-        update: (next) => next.type === node.type && next.attrs.level === node.attrs.level,
+        contentDOM: heading,
+        update: (next, decorations) => {
+            if (!sameLevel(next))
+                return false;
+            render(decorations);
+            return true;
+        },
+        stopEvent: (event) => button.contains(event.target),
+        ignoreMutation: (mutation) => mutation.type !== 'selection' && !heading.contains(mutation.target),
     };
 }
 // A task-list item: its checkbox toggles `checked`. Any other list item
@@ -296,7 +355,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, headingLevel = DEFAULT_HEADING_LEVEL, headingFrom = 'hash', 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', foldKey, 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);
@@ -483,6 +542,13 @@ export default function MilkdownEditor({ id, defaultValue, onChange, onProblem,
             });
         };
         openLinkRef.current = openLink;
+        // Folding by headings, with `foldKey` (read once, when it mounts):
+        // the fold store is the state, the plugin draws it.
+        const folds = foldKey === undefined
+            ? []
+            : [$prose(() => foldPlugin({ initial: foldStore.get(foldKey), onChange: (folded) => foldStore.set(foldKey, folded) }))];
+        const onFold = foldKey === undefined ? undefined : (id) => foldStore.set(foldKey, toggleFold(foldStore.get(foldKey), id));
+        let stopFolds = () => { };
         // Paste, copy, the editor's own keys and the placeholder.
         const slashing = $prose(() => slashPlugin());
         // Images pasted or dropped, uploaded through the app's `upload`; with
@@ -693,7 +759,7 @@ export default function MilkdownEditor({ id, defaultValue, onChange, onProblem,
                 },
                 nodeViews: {
                     // The level when it mounts, as with defaultValue.
-                    heading: (node) => headingView(node, headingLevel, textTop),
+                    heading: (node, _view, _getPos, decorations) => headingView(node, headingLevel, textTop, decorations, onFold),
                     callout: (node, _view, getPos) => calloutView(node, 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),
@@ -712,7 +778,8 @@ export default function MilkdownEditor({ id, defaultValue, onChange, onProblem,
             .use(slashing)
             .use(imageUploads)
             .use(imageInput)
-            .use(input);
+            .use(input)
+            .use(folds);
         void make.create().then((editor) => {
             if (cancelled) {
                 void editor.destroy();
@@ -725,9 +792,14 @@ export default function MilkdownEditor({ id, defaultValue, onChange, onProblem,
             setEditorState(view.state);
             if (autoFocus)
                 editor.action((ctx) => ctx.get(editorViewCtx).focus());
+            if (foldKey !== undefined) {
+                listenForOtherTabs();
+                stopFolds = foldStore.subscribe(foldKey, () => view.dispatch(setFolds(view.state, foldStore.get(foldKey))));
+            }
         });
         return () => {
             cancelled = true;
+            stopFolds();
             setEditorState(null);
             setEditorView(null);
             const editor = editorRef.current;
@@ -879,7 +951,7 @@ export default function MilkdownEditor({ id, defaultValue, onChange, onProblem,
                             // Cleared, so picking the same file again still counts.
                             event.target.value = '';
                             imagesPicked(files);
-                        } })), _jsx("div", { ref: rootRef, className: cn(!inline && 'min-h-24 px-2.5 py-2', 
+                        } })), _jsx("div", { ref: rootRef, "data-fold-scope": foldKey, className: cn(!inline && 'min-h-24 px-2.5 py-2', 
                         // Full screen: the text scrolls under the toolbar, in a column to read.
                         fullScreen && 'min-h-0 flex-1 overflow-y-auto px-4 py-3 md:px-8 [&_.ProseMirror]:mx-auto [&_.ProseMirror]:w-full [&_.ProseMirror]:max-w-3xl', 
                         // Read-only text is muted; the toolbar's buttons say so by being disabled.

package/dist/components/app/notes-outline.d.ts

@@ -0,0 +1,17 @@
+export type NotesOutlineProps = {
+    /** The text whose headings are listed. */
+    markdown: string;
+    /** The `foldKey` of the <Markdown> or RichTextEditor showing the text. */
+    foldKey: string;
+    /**
+     * How many heading levels are listed, from the text's highest down: 2
+     * (the default) lists `#` and `##` in a text that starts at `#`.
+     */
+    depth?: number;
+    /** With fewer listed headings than this, the outline shows nothing. 2 by default. */
+    minHeadings?: number;
+    /** Names the outline's landmark. "Outline" by default. */
+    'aria-label'?: string;
+    className?: string;
+};
+export declare function NotesOutline({ markdown, foldKey, depth, minHeadings, 'aria-label': ariaLabel, className, }: NotesOutlineProps): import("react").JSX.Element | null;

package/dist/components/app/notes-outline.js

@@ -0,0 +1,60 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+// A long text's headings as a list to jump with, beside <Markdown> or the
+// rich-text editor given the same `foldKey`: each heading a button that
+// opens its section (and any it sits under) and brings it into view, with
+// Fold all and Open all above. The text's top-level headings, as folding
+// sees them (src/lib/markdown-fold.ts); the deepest levels are left out
+// (`depth`), so a long text's outline stays a list of its parts.
+//
+// The jump lands on the heading's fold button, so from the keyboard the
+// next Enter folds what was just opened. The outline reads the Markdown
+// it's given: beside an editor, the text as last saved.
+import { useMemo } from 'react';
+import { ChevronRightIcon } from 'lucide-react';
+import { cn } from 'cn';
+import { Button } from '../ui/button.js';
+import { useFolds } from '../../hooks/fold-store.js';
+import { usePrefersReducedMotion } from '../../hooks/use-prefers-reduced-motion.js';
+import { allFoldable, markdownFoldPlan, openTo } from '../../lib/markdown-fold.js';
+// Each level's indent, from the highest listed.
+const INDENT = ['pl-2', 'pl-6', 'pl-10', 'pl-14', 'pl-18', 'pl-22'];
+// The element showing the heading `id` in the text under `foldKey`.
+function headingElement(foldKey, id) {
+    for (const scope of document.querySelectorAll('[data-fold-scope]')) {
+        if (scope.dataset.foldScope !== foldKey)
+            continue;
+        for (const heading of scope.querySelectorAll('[data-fold-id]'))
+            if (heading.dataset.foldId === id)
+                return heading;
+    }
+    return null;
+}
+export function NotesOutline({ markdown, foldKey, depth = 2, minHeadings = 2, 'aria-label': ariaLabel = 'Outline', className, }) {
+    const [folded, setFolded] = useFolds(foldKey);
+    const reducedMotion = usePrefersReducedMotion();
+    const plan = useMemo(() => markdownFoldPlan(markdown), [markdown]);
+    const top = Math.min(...plan.headings.map((heading) => heading.level));
+    const listed = plan.headings.filter((heading) => heading.level < top + depth);
+    if (listed.length < minHeadings)
+        return null;
+    const foldable = allFoldable(plan);
+    const anyFolded = [...folded].some((id) => foldable.has(id));
+    const allFolded = [...foldable].every((id) => folded.has(id));
+    const jump = (id) => {
+        setFolded(openTo(plan, folded, id));
+        // Once the text has opened up to it.
+        requestAnimationFrame(() => {
+            const heading = headingElement(foldKey, id);
+            if (!heading)
+                return;
+            heading.scrollIntoView({ block: 'start', behavior: reducedMotion ? 'auto' : 'smooth' });
+            const button = heading.querySelector('[data-slot="fold-button"]');
+            if (button && getComputedStyle(button).visibility !== 'hidden')
+                button.focus({ preventScroll: true });
+        });
+    };
+    return (_jsxs("nav", { "aria-label": ariaLabel, "data-slot": "notes-outline", className: cn('flex min-w-0 flex-col gap-2', className), children: [_jsxs("div", { className: "flex flex-wrap gap-1", children: [_jsx(Button, { size: "xs", variant: "outline", disabled: allFolded, onClick: () => setFolded(foldable), children: "Fold all" }), _jsx(Button, { size: "xs", variant: "outline", disabled: !anyFolded, onClick: () => setFolded(new Set()), children: "Open all" })] }), _jsx("ul", { className: "flex flex-col", children: listed.map((heading) => {
+                    const isFolded = heading.foldable && folded.has(heading.id);
+                    return (_jsx("li", { children: _jsxs("button", { type: "button", onClick: () => jump(heading.id), className: cn('flex w-full min-w-0 items-center gap-1 rounded-md py-1 pr-2 text-left type-body text-foreground outline-none hover:bg-muted focus-visible:ring-3 focus-visible:ring-ring/50', INDENT[Math.min(heading.level - top, INDENT.length - 1)], heading.level > top && 'text-muted-foreground hover:text-foreground'), children: [_jsx("span", { className: "min-w-0 flex-1 truncate", children: heading.text || 'Untitled section' }), isFolded && (_jsxs(_Fragment, { children: [_jsx(ChevronRightIcon, { "aria-hidden": "true", className: "size-3.5 shrink-0 text-muted-foreground" }), _jsx("span", { className: "sr-only", children: " (folded)" })] }))] }) }, heading.id));
+                }) })] }));
+}

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

@@ -26,6 +26,14 @@ export declare const PROSE: {
     /** `---`: 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 fold button (`foldKey`), before its words, the line's height
+ * so it sits on the first line of a heading that wraps. Its chevron points
+ * down while the section shows and right while it's folded.
+ */
+export declare const FOLD_BUTTON = "-ml-1 flex h-[1lh] w-5 shrink-0 items-center justify-center rounded-sm text-muted-foreground outline-none hover:text-foreground focus-visible:ring-3 focus-visible:ring-ring/50";
+/** A heading with a fold button: the button and the words side by side, the look on both. */
+export declare const FOLD_HEADING = "flex items-start gap-1";
 /**
  * On the text's container: when it has a band (a `#` or `##`, marked
  * `data-band`, whatever element its `headingLevel` makes it), everything

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

@@ -32,6 +32,14 @@ export const PROSE = {
     /** `---`: 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 fold button (`foldKey`), before its words, the line's height
+ * so it sits on the first line of a heading that wraps. Its chevron points
+ * down while the section shows and right while it's folded.
+ */
+export const FOLD_BUTTON = '-ml-1 flex h-[1lh] w-5 shrink-0 items-center justify-center rounded-sm text-muted-foreground outline-none hover:text-foreground focus-visible:ring-3 focus-visible:ring-ring/50';
+/** A heading with a fold button: the button and the words side by side, the look on both. */
+export const FOLD_HEADING = 'flex items-start gap-1';
 /**
  * On the text's container: when it has a band (a `#` or `##`, marked
  * `data-band`, whatever element its `headingLevel` makes it), everything

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

@@ -69,6 +69,17 @@ export type RichTextEditorProps = {
      * `headingLevel` too. The Markdown saved is never rewritten.
      */
     headingFrom?: HeadingFrom;
+    /**
+     * Folds the text by its headings, as `<Markdown>`'s `foldKey` does: each
+     * heading at the text's top level has a button that folds what's under
+     * it, Ctrl/Cmd+Alt+[ folds the section the caret is in and
+     * Ctrl/Cmd+Alt+] opens the heading it's on, and the caret moving into a
+     * folded section opens it. Remembered on this device under this key,
+     * and shared with `<Markdown>` and NotesOutline given the same one.
+     * Only the view folds: the Markdown saved never changes. Read once,
+     * when it mounts.
+     */
+    foldKey?: string;
     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

@@ -23,6 +23,9 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 // Image button is uploaded through the app's own storage and goes in as
 // `![](url)`; while it uploads, a placeholder shows where it will go.
 //
+// With `foldKey`, the text folds by its headings (NotesOutline lists them
+// beside it), the Markdown untouched.
+//
 // The editor (Milkdown) is loaded on first use, so a page that only reads
 // Markdown never downloads it. Until it arrives, a placeholder the size of
 // the field shows.

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

@@ -0,0 +1,28 @@
+import type { Node as ProseNode } from '@milkdown/kit/prose/model';
+import { Plugin, PluginKey, type EditorState } from '@milkdown/kit/prose/state';
+import { Decoration, DecorationSet } from '@milkdown/kit/prose/view';
+import { type FoldPlan } from '../../lib/markdown-fold.js';
+/** What a heading's node view hears of its fold, through its node decoration's spec. */
+export type FoldSpec = {
+    id: string;
+    label: string;
+    foldable: boolean;
+    folded: boolean;
+};
+type FoldState = {
+    folded: ReadonlySet<string>;
+    plan: FoldPlan;
+    decorations: DecorationSet;
+};
+export declare const foldPluginKey: PluginKey<FoldState>;
+/** The fold plan of a document's top-level blocks. */
+export declare function docFoldPlan(doc: ProseNode, folded?: ReadonlySet<string>): FoldPlan;
+/** A heading node view's fold, from the decorations ProseMirror gives it. */
+export declare function foldSpecOf(decorations: readonly Decoration[]): FoldSpec | null;
+/** A transaction that sets what's folded, from outside the editor. */
+export declare function setFolds(state: EditorState, folded: ReadonlySet<string>): import("prosemirror-state").Transaction;
+export declare function foldPlugin(options: {
+    initial: ReadonlySet<string>;
+    onChange: (folded: ReadonlySet<string>) => void;
+}): Plugin<FoldState>;
+export {};

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

@@ -0,0 +1,130 @@
+import { Plugin, PluginKey, TextSelection } from '@milkdown/kit/prose/state';
+import { Decoration, DecorationSet } from '@milkdown/kit/prose/view';
+import { foldPlan, openAt, toggleFold } from '../../lib/markdown-fold.js';
+export const foldPluginKey = new PluginKey('fold');
+/** The fold plan of a document's top-level blocks. */
+export function docFoldPlan(doc, folded) {
+    const blocks = [];
+    doc.forEach((node) => blocks.push(node.type.name === 'heading' ? { level: Number(node.attrs.level), text: node.textContent } : null));
+    return foldPlan(blocks, folded);
+}
+function build(doc, folded) {
+    const plan = docFoldPlan(doc, folded);
+    const headings = new Map(plan.headings.map((heading) => [heading.index, heading]));
+    const decorations = [];
+    doc.forEach((node, offset, index) => {
+        const heading = headings.get(index);
+        const attrs = {};
+        if (plan.hidden.has(index))
+            attrs.hidden = '';
+        if (heading) {
+            const spec = {
+                id: heading.id,
+                label: heading.text,
+                foldable: heading.foldable,
+                folded: heading.foldable && folded.has(heading.id),
+            };
+            decorations.push(Decoration.node(offset, offset + node.nodeSize, attrs, { fold: spec }));
+        }
+        else if (attrs.hidden !== undefined) {
+            decorations.push(Decoration.node(offset, offset + node.nodeSize, attrs));
+        }
+    });
+    return { folded, plan, decorations: DecorationSet.create(doc, decorations) };
+}
+/** A heading node view's fold, from the decorations ProseMirror gives it. */
+export function foldSpecOf(decorations) {
+    for (const decoration of decorations) {
+        const spec = decoration.spec.fold;
+        if (spec)
+            return spec;
+    }
+    return null;
+}
+/** A transaction that sets what's folded, from outside the editor. */
+export function setFolds(state, folded) {
+    return state.tr.setMeta(foldPluginKey, folded).setMeta('addToHistory', false);
+}
+// The innermost foldable heading whose section (or heading) holds the
+// top-level block at `index`.
+function headingAround(plan, index) {
+    let found;
+    for (const heading of plan.headings) {
+        if (heading.foldable && heading.index <= index && index < heading.end)
+            found = heading;
+    }
+    return found;
+}
+// The caret at the end of the top-level block at `index` (a heading).
+function caretToEnd(state, index) {
+    let end = 0;
+    state.doc.forEach((node, offset, at) => {
+        if (at === index)
+            end = offset + node.nodeSize - 1;
+    });
+    return state.tr.setSelection(TextSelection.create(state.doc, end)).scrollIntoView();
+}
+export function foldPlugin(options) {
+    return new Plugin({
+        key: foldPluginKey,
+        state: {
+            init: (_config, state) => build(state.doc, options.initial),
+            apply: (tr, value, _old, state) => {
+                const next = tr.getMeta(foldPluginKey);
+                if (!next && !tr.docChanged)
+                    return value;
+                return build(state.doc, next ?? value.folded);
+            },
+        },
+        props: {
+            decorations: (state) => foldPluginKey.getState(state)?.decorations,
+            handleKeyDown: (view, event) => {
+                const mod = event.metaKey || event.ctrlKey;
+                if (!mod || !event.altKey || event.shiftKey)
+                    return false;
+                if (event.code !== 'BracketLeft' && event.code !== 'BracketRight')
+                    return false;
+                const fold = foldPluginKey.getState(view.state);
+                if (!fold)
+                    return false;
+                const index = view.state.selection.$from.index(0);
+                event.preventDefault();
+                if (event.code === 'BracketLeft') {
+                    const heading = headingAround(fold.plan, index);
+                    if (!heading || fold.folded.has(heading.id))
+                        return true;
+                    // The caret to the end of the heading, which stays in sight.
+                    view.dispatch(caretToEnd(view.state, heading.index));
+                    options.onChange(toggleFold(fold.folded, heading.id));
+                    return true;
+                }
+                const heading = fold.plan.headings.find((one) => one.index === index);
+                if (heading && fold.folded.has(heading.id))
+                    options.onChange(toggleFold(fold.folded, heading.id));
+                return true;
+            },
+        },
+        view: () => ({
+            update: (view, previous) => {
+                const fold = foldPluginKey.getState(view.state);
+                if (!fold)
+                    return;
+                const index = view.state.selection.$from.index(0);
+                if (!fold.plan.hidden.has(index))
+                    return;
+                // Folded around the caret (a fold button, the outline): the caret
+                // goes to the end of the heading that folded, which shows.
+                if (fold.folded !== foldPluginKey.getState(previous)?.folded && view.state.selection.eq(previous.selection)) {
+                    const outer = fold.plan.headings.find((heading) => fold.folded.has(heading.id) && heading.foldable && heading.index < index && index < heading.end);
+                    if (outer)
+                        queueMicrotask(() => view.dispatch(caretToEnd(view.state, outer.index)));
+                    return;
+                }
+                // The caret put in a folded section: open it (after this update,
+                // as the change comes back in a transaction of its own).
+                const opened = openAt(fold.plan, fold.folded, index);
+                queueMicrotask(() => options.onChange(opened));
+            },
+        }),
+    });
+}

package/dist/hooks/fold-store.d.ts

@@ -0,0 +1,19 @@
+type StorageLike = Pick<Storage, 'getItem' | 'setItem' | 'removeItem'>;
+export type FoldStore = {
+    /** The ids folded under `key`: the same set until it changes. */
+    get: (key: string) => ReadonlySet<string>;
+    set: (key: string, folded: ReadonlySet<string>) => void;
+    subscribe: (key: string, listener: () => void) => () => void;
+    /** Another tab changed `key` (a `storage` event): re-read it. */
+    changedElsewhere: (key: string) => void;
+};
+export declare function createFoldStore(getStorage: () => StorageLike | undefined): FoldStore;
+export declare const foldStore: FoldStore;
+export declare function listenForOtherTabs(): void;
+/**
+ * `[folded, setFolded]`: the heading ids folded under `foldKey`, shared
+ * with everything else given that key. Without a key it's plain state,
+ * forgotten with the page.
+ */
+export declare function useFolds(foldKey: string | undefined): readonly [ReadonlySet<string>, (folded: ReadonlySet<string>) => void];
+export {};

package/dist/hooks/fold-store.js

@@ -0,0 +1,93 @@
+import { useCallback, useState, useSyncExternalStore } from 'react';
+const NONE = new Set();
+function parse(stored) {
+    if (!stored)
+        return NONE;
+    try {
+        const ids = JSON.parse(stored);
+        return Array.isArray(ids) ? new Set(ids.filter((id) => typeof id === 'string')) : NONE;
+    }
+    catch {
+        return NONE;
+    }
+}
+export function createFoldStore(getStorage) {
+    // Each key's set as last read or set: one object per state, so React
+    // sees a change only when there is one.
+    const current = new Map();
+    const listeners = new Map();
+    const notify = (key) => {
+        for (const listener of listeners.get(key) ?? [])
+            listener();
+    };
+    return {
+        get(key) {
+            let folded = current.get(key);
+            if (!folded) {
+                try {
+                    folded = parse(getStorage()?.getItem(key));
+                }
+                catch {
+                    folded = NONE;
+                }
+                current.set(key, folded);
+            }
+            return folded;
+        },
+        set(key, folded) {
+            const next = new Set(folded);
+            current.set(key, next);
+            try {
+                if (next.size === 0)
+                    getStorage()?.removeItem(key);
+                else
+                    getStorage()?.setItem(key, JSON.stringify([...next]));
+            }
+            catch {
+                // Storage blocked or full: remembered in memory for this page only.
+            }
+            notify(key);
+        },
+        subscribe(key, listener) {
+            let set = listeners.get(key);
+            if (!set)
+                listeners.set(key, (set = new Set()));
+            set.add(listener);
+            return () => set.delete(listener);
+        },
+        changedElsewhere(key) {
+            if (!current.has(key))
+                return;
+            current.delete(key);
+            notify(key);
+        },
+    };
+}
+export const foldStore = createFoldStore(() => (typeof window === 'undefined' ? undefined : window.localStorage));
+let listeningForOtherTabs = false;
+export function listenForOtherTabs() {
+    if (listeningForOtherTabs || typeof window === 'undefined')
+        return;
+    listeningForOtherTabs = true;
+    window.addEventListener('storage', (event) => {
+        if (event.key !== null)
+            foldStore.changedElsewhere(event.key);
+    });
+}
+/**
+ * `[folded, setFolded]`: the heading ids folded under `foldKey`, shared
+ * with everything else given that key. Without a key it's plain state,
+ * forgotten with the page.
+ */
+export function useFolds(foldKey) {
+    const [local, setLocal] = useState(NONE);
+    const subscribe = useCallback((listener) => {
+        if (foldKey === undefined)
+            return () => { };
+        listenForOtherTabs();
+        return foldStore.subscribe(foldKey, listener);
+    }, [foldKey]);
+    const stored = useSyncExternalStore(subscribe, () => (foldKey === undefined ? NONE : foldStore.get(foldKey)), () => NONE);
+    const set = useCallback((folded) => (foldKey === undefined ? setLocal(folded) : foldStore.set(foldKey, folded)), [foldKey]);
+    return [foldKey === undefined ? local : stored, set];
+}

package/dist/index.d.ts

@@ -20,6 +20,7 @@ export { ErrorState } from './components/app/error-state.js';
 export { InlineCreate, type InlineCreateProps } from './components/app/inline-create.js';
 export { FoundationProviders } from './components/app/foundation-providers.js';
 export { Markdown, type MarkdownProps } from './components/app/markdown.js';
+export { NotesOutline, type NotesOutlineProps } from './components/app/notes-outline.js';
 export type { HeadingFrom, HeadingLevel } from './components/app/prose-look.js';
 export { MockModeBanner } from './components/app/mock-mode-banner.js';
 export { MultiChoice } from './components/app/multi-choice.js';

package/dist/index.js

@@ -24,6 +24,7 @@ export { ErrorState } from './components/app/error-state.js';
 export { InlineCreate } from './components/app/inline-create.js';
 export { FoundationProviders } from './components/app/foundation-providers.js';
 export { Markdown } from './components/app/markdown.js';
+export { NotesOutline } from './components/app/notes-outline.js';
 export { MockModeBanner } from './components/app/mock-mode-banner.js';
 export { MultiChoice } from './components/app/multi-choice.js';
 export { MultiPick } from './components/app/multi-pick.js';

package/dist/lib/markdown-fold.d.ts

@@ -0,0 +1,59 @@
+/** A top-level heading, by its level (1 for `#`) and its words. */
+export type FoldHeadingInput = {
+    level: number;
+    text: string;
+};
+/** A top-level heading as folding sees it. */
+export type FoldHeading = FoldHeadingInput & {
+    /** Its id in the fold state. */
+    id: string;
+    /** Its index among the text's top-level blocks. */
+    index: number;
+    /** It has something under it to fold. */
+    foldable: boolean;
+    /** The ids of the headings it sits under, outermost first. */
+    parents: string[];
+    /** The index of the first top-level block after its section (the text's length at the end). */
+    end: number;
+};
+/** The plan for a text's top-level blocks: which are headings, which are folded away. */
+export type FoldPlan = {
+    headings: FoldHeading[];
+    /** Indexes of the top-level blocks hidden by a folded heading. */
+    hidden: Set<number>;
+};
+/**
+ * The plan for a text whose top-level blocks are `blocks`: each one a
+ * heading (`{ level, text }`) or `null`. `folded` is the ids folded now.
+ */
+export declare function foldPlan(blocks: readonly (FoldHeadingInput | null)[], folded?: ReadonlySet<string>): FoldPlan;
+export type MdFoldNode = {
+    type: string;
+    depth?: number;
+    value?: string;
+    children?: MdFoldNode[];
+};
+/** A heading's words as the editor reads them: its text and inline code (not raw HTML, not image alt text). */
+export declare function mdText(node: MdFoldNode): string;
+/** The top-level blocks of an mdast root, as foldPlan takes them. */
+export declare function mdBlocks(root: MdFoldNode): (FoldHeadingInput | null)[];
+/** The fold plan for a Markdown text, parsed as <Markdown> and the editor parse it. */
+export declare function markdownFoldPlan(markdown: string, folded?: ReadonlySet<string>): FoldPlan;
+/** Every heading with something to fold: Fold all. */
+export declare function allFoldable(plan: FoldPlan): Set<string>;
+/** `folded` with the heading `id` and every heading it sits under opened: a jump to it. */
+export declare function openTo(plan: FoldPlan, folded: ReadonlySet<string>, id: string): Set<string>;
+/** `folded` with every heading whose section holds the top-level block at `index` opened: the caret moved into it. */
+export declare function openAt(plan: FoldPlan, folded: ReadonlySet<string>, index: number): Set<string>;
+/** `folded` with `id` turned the other way. */
+export declare function toggleFold(folded: ReadonlySet<string>, id: string): Set<string>;
+/**
+ * For <Markdown> (react-markdown's rehype plugins): marks each top-level
+ * heading with its fold id and state, and hides every top-level block a
+ * folded heading covers (`hidden`). Raw HTML at the top level, which
+ * <Markdown> shows as its characters, is hidden as a paragraph of the same
+ * characters. GFM's footnotes, gathered at the end, are never hidden.
+ */
+export declare function rehypeFold(options: {
+    folded: ReadonlySet<string>;
+}): (tree: unknown) => void;

package/dist/lib/markdown-fold.js

@@ -0,0 +1,163 @@
+// Folding a text by its headings (`foldKey` on <Markdown> and the
+// rich-text editor, and NotesOutline beside them). A heading at the top
+// level of the text folds everything after it up to the next heading of
+// its level or higher: a `##` folds its paragraphs and its `###`s, and
+// stops at the next `##` or `#`. Headings inside a quote or a callout
+// don't fold.
+//
+// Folding is the reader's, never the text's: what's folded is a set of
+// heading ids, kept on the device (src/hooks/fold-store.ts), and the
+// Markdown is never touched. A heading's id is its level and its words
+// (`2:Safety`), with `#2`, `#3` added for the second and third heading of
+// the same level and words, so the same heading gets the same id in
+// <Markdown>, in the editor and in the outline, and keeps it while the
+// text around it changes. Renaming a heading opens it.
+import remarkGfm from 'remark-gfm';
+import remarkParse from 'remark-parse';
+import { unified } from 'unified';
+function words(text) {
+    return text.replace(/\s+/g, ' ').trim();
+}
+/**
+ * The plan for a text whose top-level blocks are `blocks`: each one a
+ * heading (`{ level, text }`) or `null`. `folded` is the ids folded now.
+ */
+export function foldPlan(blocks, folded = new Set()) {
+    const headings = [];
+    const hidden = new Set();
+    const seen = new Map();
+    // The headings the current block sits under, outermost first.
+    const open = [];
+    blocks.forEach((block, index) => {
+        if (block)
+            while (open.length > 0 && open[open.length - 1].level >= block.level)
+                open.pop().end = index;
+        if (open.some((heading) => folded.has(heading.id)))
+            hidden.add(index);
+        // Anything after a heading, before one of its level or higher, is its section.
+        if (open.length > 0)
+            open[open.length - 1].foldable = true;
+        if (!block)
+            return;
+        const text = words(block.text);
+        const base = `${block.level}:${text}`;
+        const count = (seen.get(base) ?? 0) + 1;
+        seen.set(base, count);
+        const heading = {
+            level: block.level,
+            text,
+            id: count === 1 ? base : `${base}#${count}`,
+            index,
+            foldable: false,
+            parents: open.map((one) => one.id),
+            end: blocks.length,
+        };
+        headings.push(heading);
+        open.push(heading);
+    });
+    return { headings, hidden };
+}
+/** A heading's words as the editor reads them: its text and inline code (not raw HTML, not image alt text). */
+export function mdText(node) {
+    if (node.type === 'text' || node.type === 'inlineCode')
+        return node.value ?? '';
+    if (node.type === 'break')
+        return ' ';
+    return (node.children ?? []).map(mdText).join('');
+}
+/** The top-level blocks of an mdast root, as foldPlan takes them. */
+export function mdBlocks(root) {
+    return (root.children ?? []).map((node) => node.type === 'heading' && node.depth ? { level: node.depth, text: mdText(node) } : null);
+}
+const parser = unified().use(remarkParse).use(remarkGfm);
+/** The fold plan for a Markdown text, parsed as <Markdown> and the editor parse it. */
+export function markdownFoldPlan(markdown, folded) {
+    return foldPlan(mdBlocks(parser.parse(markdown)), folded);
+}
+/** Every heading with something to fold: Fold all. */
+export function allFoldable(plan) {
+    return new Set(plan.headings.filter((heading) => heading.foldable).map((heading) => heading.id));
+}
+/** `folded` with the heading `id` and every heading it sits under opened: a jump to it. */
+export function openTo(plan, folded, id) {
+    const heading = plan.headings.find((one) => one.id === id);
+    const next = new Set(folded);
+    if (!heading)
+        return next;
+    for (const parent of heading.parents)
+        next.delete(parent);
+    return next;
+}
+/** `folded` with every heading whose section holds the top-level block at `index` opened: the caret moved into it. */
+export function openAt(plan, folded, index) {
+    const next = new Set(folded);
+    for (const heading of plan.headings)
+        if (heading.index < index && index < heading.end)
+            next.delete(heading.id);
+    return next;
+}
+/** `folded` with `id` turned the other way. */
+export function toggleFold(folded, id) {
+    const next = new Set(folded);
+    if (next.has(id))
+        next.delete(id);
+    else
+        next.add(id);
+    return next;
+}
+function hastText(node) {
+    if (node.type === 'text')
+        return node.value ?? '';
+    if (node.type === 'element' && node.tagName === 'br')
+        return ' ';
+    if (node.type !== 'element')
+        return '';
+    return (node.children ?? []).map(hastText).join('');
+}
+const HEADING = /^h([1-6])$/;
+/**
+ * For <Markdown> (react-markdown's rehype plugins): marks each top-level
+ * heading with its fold id and state, and hides every top-level block a
+ * folded heading covers (`hidden`). Raw HTML at the top level, which
+ * <Markdown> shows as its characters, is hidden as a paragraph of the same
+ * characters. GFM's footnotes, gathered at the end, are never hidden.
+ */
+export function rehypeFold(options) {
+    return (tree) => {
+        const root = tree;
+        const children = root.children ?? [];
+        // The blocks: the root's elements and raw HTML; the line breaks between them aren't.
+        const at = [];
+        children.forEach((node, index) => {
+            if (node.type === 'element' || node.type === 'raw')
+                at.push(index);
+        });
+        const blocks = at.map((index) => {
+            const node = children[index];
+            const level = node.type === 'element' ? HEADING.exec(node.tagName ?? '')?.[1] : undefined;
+            return level ? { level: Number(level), text: hastText(node) } : null;
+        });
+        const plan = foldPlan(blocks, options.folded);
+        for (const heading of plan.headings) {
+            const node = children[at[heading.index]];
+            node.properties = {
+                ...node.properties,
+                dataFoldId: heading.id,
+                dataFoldLabel: heading.text,
+                dataFoldable: String(heading.foldable),
+                dataFolded: String(heading.foldable && options.folded.has(heading.id)),
+            };
+        }
+        for (const block of plan.hidden) {
+            const index = at[block];
+            let node = children[index];
+            if (node.properties?.dataFootnotes !== undefined)
+                continue;
+            if (node.type === 'raw') {
+                node = { type: 'element', tagName: 'p', properties: {}, children: [{ type: 'text', value: node.value ?? '' }] };
+                children[index] = node;
+            }
+            node.properties = { ...node.properties, hidden: true };
+        }
+    };
+}

package/package.json

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