@tristan2828/ui-foundation 4.52.0 → 4.54.0

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

@@ -3,7 +3,8 @@ export type { IconComponent } from './components/app/icon-component.js';
 export { Board, type BoardColumn, type BoardMoveTarget, type BoardProps } from './components/app/board.js';
 export { SpinWheel, type SpinWheelProps } from './components/app/spin-wheel.js';
 export { pickSpinWheelIndex, type SpinWheelItem } from './components/app/spin-wheel-pick.js';
-export { FillInChoice, FillInQueue, type FillInChoiceProps, type FillInQueueProgress, type FillInQueueProps, } from './components/app/fill-in-queue.js';
+export { FillInChoice, FillInQueue, type FillInChoiceProps, type FillInQueueGroup, type FillInQueueProgress, type FillInQueueProps, } from './components/app/fill-in-queue.js';
+export { FillInField, FillInInput, FillInSelect, type FillInFieldKind, type FillInFieldProps, type FillInFieldSpec, type FillInInputKind, type FillInInputProps, type FillInSelectProps, type FillInSuggestion, type FillInValue, } from './components/app/fill-in-field.js';
 export { Artwork, ArtworkTag, ArtworkToggle, type ArtworkAspect, type ArtworkProps, type ArtworkToggleProps, } from './components/app/artwork.js';
 export { CountLink, type CountLinkProps } from './components/app/count-link.js';
 export { DataTable, type DataTableCardLayout, type DataTableGrouping, type DataTableProps, type DataTableTotals, type DataTableWidth, type SortingState, } from './components/app/data-table.js';
@@ -19,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

@@ -8,6 +8,7 @@ export { Board } from './components/app/board.js';
 export { SpinWheel } from './components/app/spin-wheel.js';
 export { pickSpinWheelIndex } from './components/app/spin-wheel-pick.js';
 export { FillInChoice, FillInQueue, } from './components/app/fill-in-queue.js';
+export { FillInField, FillInInput, FillInSelect, } from './components/app/fill-in-field.js';
 export { Artwork, ArtworkTag, ArtworkToggle, } from './components/app/artwork.js';
 export { CountLink } from './components/app/count-link.js';
 export { DataTable, } from './components/app/data-table.js';
@@ -23,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 };
+        }
+    };
+}