@tristan2828/ui-foundation 4.52.0 → 4.54.0

package/conventions/docs/design-language.md

@@ -21,7 +21,7 @@
 - [A list as cards](#a-list-as-cards) · lines 749–795
 - [Key numbers on a record](#key-numbers-on-a-record) · lines 797–819
 - [Picking at random](#picking-at-random) · lines 821–852
-- [Filling in what's missing](#filling-in-whats-missing) · lines 854–904
+- [Filling in what's missing](#filling-in-whats-missing) · lines 854–921
 
 <!-- /index -->
 
@@ -902,3 +902,20 @@ size"); the list stays where a record is edited one field at a time.
 - A refused save keeps the record and says why under the buttons, not
   in a toast. It owns its states: skeletons, `ErrorState`, and the
   empty queue, which is the good news ("Every project has a size").
+- **Other kinds of value** (4.53): `FillInInput` is the row for text,
+  long text, a number, money (the currency's symbol before it) or a date
+  (`DateField`), and `FillInSelect` for a list too long for buttons (a
+  reference to another record). Each has the label above and a
+  suggestion under it as a dashed "Use $249.00" button, never filled in
+  for the person.
+- **Fields as data:** `FillInField` takes a field as an API describes it
+  (`{ name, label, kind, choices, suggestion }`, `kind` one of choice,
+  reference, text, longText, number, money, date) and draws the row its
+  kind calls for: `FillInChoice` for up to nine choices, `FillInSelect`
+  for more, `FillInInput` for the rest. Its value is a choice's value, a
+  number for number and money, text otherwise, null for none. For a page
+  that draws records it doesn't know in advance.
+- **Records from several places:** `groups` (`{ id, label, icon,
+  progress }`) and `getGroup` name a record's source above its heading,
+  with that group's own count; with more than one group counted, each
+  one's count is listed under the bar.

package/dist/components/app/fill-in-field.d.ts

@@ -0,0 +1,65 @@
+import { type ReactNode } from 'react';
+export type FillInInputKind = 'text' | 'longText' | 'number' | 'money' | 'date';
+export interface FillInSuggestion<V> {
+    value: V;
+    /** Why it's suggested: "from similar purchases". */
+    note?: ReactNode;
+}
+export interface FillInInputProps {
+    label: string;
+    kind: FillInInputKind;
+    /** The control's text: `'YYYY-MM-DD'` for a date, a number as typed; `''` for none. */
+    value: string;
+    onChange: (value: string) => void;
+    /** Offered as a dashed "Use …" button under the control. */
+    suggestion?: FillInSuggestion<string>;
+    /** The currency of a money value, for its symbol and the suggestion. Default "USD". */
+    currency?: string;
+    locale?: string;
+    placeholder?: string;
+    className?: string;
+}
+/** One text, number, money or date field of a FillInQueue record. */
+export declare function FillInInput({ label, kind, value, onChange, suggestion, currency, locale, placeholder, className, }: FillInInputProps): import("react").JSX.Element;
+export interface FillInSelectProps<V extends string | number> {
+    label: string;
+    choices: readonly {
+        value: V;
+        label: ReactNode;
+    }[];
+    value: V | null | undefined;
+    onChange: (value: V | null) => void;
+    suggestion?: FillInSuggestion<V>;
+    /** What the trigger says with nothing picked. Default "Pick one". */
+    placeholder?: string;
+    className?: string;
+}
+/** One field of a FillInQueue record picked from a long list. */
+export declare function FillInSelect<V extends string | number>({ label, choices, value, onChange, suggestion, placeholder, className, }: FillInSelectProps<V>): import("react").JSX.Element;
+export type FillInFieldKind = 'choice' | 'reference' | FillInInputKind;
+export type FillInValue = string | number | null;
+/** A field described as data, as an API sends it. */
+export interface FillInFieldSpec {
+    name: string;
+    label: string;
+    kind: FillInFieldKind;
+    /** For `choice` and `reference`. */
+    choices?: readonly {
+        value: string | number;
+        label: string;
+    }[];
+    suggestion?: FillInSuggestion<string | number>;
+}
+export interface FillInFieldProps {
+    field: FillInFieldSpec;
+    /** The draft's value: a choice's value, a number for number and money, text for the rest; null for none. */
+    value: FillInValue | undefined;
+    onChange: (value: FillInValue) => void;
+    /** The number keys pick in this field when it's drawn as a row of choices. One per record. */
+    shortcut?: boolean;
+    currency?: string;
+    locale?: string;
+    className?: string;
+}
+/** The row a field's kind calls for: FillInChoice, FillInSelect or FillInInput. */
+export declare function FillInField({ field, value, onChange, shortcut, currency, locale, className }: FillInFieldProps): import("react").JSX.Element;

package/dist/components/app/fill-in-field.js

@@ -0,0 +1,99 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// FillInQueue's rows for values that aren't a short choice: text, a number,
+// money, a date, and a long list to pick from. Each looks like FillInChoice
+// (a label, the control, a suggestion under it) so a record mixes them.
+//
+// - FillInInput: one text, number, money or date value. The value is the
+//   control's own text (`'YYYY-MM-DD'` for a date, `''` for none); the app
+//   reads it. A suggestion is a dashed button under it ("Use $12.00"),
+//   never filled in for the person.
+// - FillInSelect: one value from a list too long for a row of buttons
+//   (a reference to another record, a long enum), as a Select.
+// - FillInField: given a field as data (`{ name, label, kind, choices }`,
+//   as an API describes it), the right row: FillInChoice for up to nine
+//   choices, FillInSelect for more, FillInInput for the rest. For a page
+//   that draws records it doesn't know in advance.
+import { useId, useState } from 'react';
+import { cn } from 'cn';
+import { DateField } from './date-field.js';
+import { FillInChoice } from './fill-in-queue.js';
+import { Button } from '../ui/button.js';
+import { Input } from '../ui/input.js';
+import { InputGroup, InputGroupAddon, InputGroupInput, InputGroupText } from '../ui/input-group.js';
+import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from '../ui/select.js';
+import { Textarea } from '../ui/textarea.js';
+import { formatPlainDate } from '../../lib/plain-date.js';
+const currencySymbol = (currency, locale) => new Intl.NumberFormat(locale, { style: 'currency', currency }).formatToParts(0).find((part) => part.type === 'currency')
+    ?.value ?? currency;
+function shown(kind, value, currency, locale) {
+    if (kind === 'date')
+        return formatPlainDate(value, { dateStyle: 'medium' }, locale);
+    const number = Number(value);
+    if (value.trim() === '' || !Number.isFinite(number))
+        return value;
+    if (kind === 'money')
+        return new Intl.NumberFormat(locale, { style: 'currency', currency }).format(number);
+    if (kind === 'number')
+        return new Intl.NumberFormat(locale).format(number);
+    return value;
+}
+/** One text, number, money or date field of a FillInQueue record. */
+export function FillInInput({ label, kind, value, onChange, suggestion, currency = 'USD', locale, placeholder, className, }) {
+    const id = useId();
+    const control = (() => {
+        switch (kind) {
+            case 'date':
+                return _jsx(DateField, { id: id, value: value, onChange: onChange, clearable: true, locale: locale });
+            case 'longText':
+                return _jsx(Textarea, { id: id, value: value, placeholder: placeholder, onChange: (event) => onChange(event.target.value) });
+            case 'money':
+                return (_jsxs(InputGroup, { children: [_jsx(InputGroupAddon, { children: _jsx(InputGroupText, { children: currencySymbol(currency, locale) }) }), _jsx(InputGroupInput, { id: id, inputMode: "decimal", value: value, placeholder: placeholder, onChange: (event) => onChange(event.target.value) })] }));
+            case 'number':
+                return (_jsx(Input, { id: id, type: "number", inputMode: "decimal", value: value, placeholder: placeholder, onChange: (event) => onChange(event.target.value) }));
+            default:
+                return _jsx(Input, { id: id, value: value, placeholder: placeholder, onChange: (event) => onChange(event.target.value) });
+        }
+    })();
+    return (_jsxs("div", { "data-slot": "fill-in-input", className: cn('flex flex-col gap-2', className), children: [_jsx("label", { htmlFor: id, className: "type-label", children: label }), control, suggestion !== undefined && suggestion.value !== '' && (_jsx(SuggestionButton, { text: shown(kind, suggestion.value, currency, locale), note: suggestion.note, used: value === suggestion.value, onUse: () => onChange(suggestion.value) }))] }));
+}
+/** One field of a FillInQueue record picked from a long list. */
+export function FillInSelect({ label, choices, value, onChange, suggestion, placeholder = 'Pick one', className, }) {
+    const id = useId();
+    const keyOf = (v) => String(v);
+    const byKey = new Map(choices.map((choice) => [keyOf(choice.value), choice]));
+    const suggested = suggestion ? byKey.get(keyOf(suggestion.value)) : undefined;
+    return (_jsxs("div", { "data-slot": "fill-in-select", className: cn('flex flex-col gap-2', className), children: [_jsx("label", { htmlFor: id, className: "type-label", children: label }), _jsxs(Select, { value: value === null || value === undefined ? null : keyOf(value), onValueChange: (next) => onChange(next === null ? null : (byKey.get(String(next))?.value ?? null)), children: [_jsx(SelectTrigger, { id: id, className: "w-full", children: _jsx(SelectValue, { placeholder: placeholder, children: (key) => (key === null ? placeholder : (byKey.get(key)?.label ?? key)) }) }), _jsx(SelectContent, { children: choices.map((choice) => (_jsx(SelectItem, { value: keyOf(choice.value), children: choice.label }, keyOf(choice.value)))) })] }), suggested !== undefined && (_jsx(SuggestionButton, { text: suggested.label, note: suggestion?.note, used: value !== null && value !== undefined && keyOf(value) === keyOf(suggested.value), onUse: () => onChange(suggested.value) }))] }));
+}
+function SuggestionButton({ text, note, used, onUse }) {
+    return (_jsxs("div", { className: "flex flex-wrap items-center gap-2", children: [_jsxs(Button, { type: "button", size: "sm", variant: "outline", disabled: used, onClick: onUse, "data-slot": "fill-in-suggestion", className: "border-dashed border-info-text", children: ["Use ", text] }), note !== undefined && note !== null && _jsxs("span", { className: "type-caption text-muted-foreground", children: ["(", note, ")"] })] }));
+}
+const isNumeric = (kind) => kind === 'number' || kind === 'money';
+const toText = (value) => (value === null || value === undefined ? '' : String(value));
+/** The row a field's kind calls for: FillInChoice, FillInSelect or FillInInput. */
+export function FillInField({ field, value, onChange, shortcut, currency, locale, className }) {
+    const { kind, label, choices = [], suggestion } = field;
+    // A number's text as typed ("1." on the way to "1.5"), kept while it
+    // still reads as the draft's value; replaced when the draft changes.
+    const [text, setText] = useState(() => toText(value));
+    const keeps = value === null || value === undefined
+        ? text.trim() === '' || !Number.isFinite(Number(text))
+        : text.trim() !== '' && Number(text) === value;
+    if (isNumeric(kind) && !keeps)
+        setText(toText(value));
+    if (kind === 'choice' || kind === 'reference') {
+        const pick = (next) => onChange(next);
+        const current = value === undefined ? null : value;
+        if (choices.length <= 9) {
+            return (_jsx(FillInChoice, { label: label, choices: choices, value: current, onChange: pick, suggestion: suggestion, shortcut: shortcut, className: className }));
+        }
+        return (_jsx(FillInSelect, { label: label, choices: choices, value: current, onChange: pick, suggestion: suggestion, className: className }));
+    }
+    const numeric = isNumeric(kind);
+    return (_jsx(FillInInput, { label: label, kind: kind, value: numeric ? text : toText(value), onChange: (next) => {
+            if (!numeric)
+                return onChange(next === '' ? null : next);
+            setText(next);
+            const number = Number(next);
+            onChange(next.trim() === '' || !Number.isFinite(number) ? null : number);
+        }, suggestion: suggestion === undefined ? undefined : { value: String(suggestion.value), note: suggestion.note }, currency: currency, locale: locale, className: className }));
+}

package/dist/components/app/fill-in-queue.d.ts

@@ -1,5 +1,6 @@
 import { type ReactNode } from 'react';
 import type { AppError } from '../../api/contracts.js';
+import type { IconComponent } from './icon-component.js';
 export interface FillInQueueProgress {
     /** Records filled so far. */
     done: number;
@@ -8,6 +9,13 @@ export interface FillInQueueProgress {
     /** The word after the count: "12 of 160 <label>". Default "filled". */
     label?: string;
 }
+export interface FillInQueueGroup {
+    id: string;
+    label: string;
+    icon?: IconComponent;
+    /** This group's own count, said beside its name on its records. */
+    progress?: Omit<FillInQueueProgress, 'label'>;
+}
 export interface FillInQueueProps<T> {
     /** The records still missing something, in order. */
     items: readonly T[];
@@ -22,6 +30,10 @@ export interface FillInQueueProps<T> {
     onSkip?: (item: T) => void;
     /** A bar and "12 of 160 filled" at the top. The app counts. */
     progress?: FillInQueueProgress;
+    /** Where records come from: named above each record's heading. */
+    groups?: readonly FillInQueueGroup[];
+    /** The id of the record's group in `groups`. */
+    getGroup?: (item: T) => string;
     /** Default "Save and next". */
     saveLabel?: string;
     /** Default "Skip". */
@@ -38,7 +50,7 @@ export interface FillInQueueProps<T> {
     onIndexChange?: (index: number, item: T) => void;
     className?: string;
 }
-export declare function FillInQueue<T>({ items, getKey, renderItem, onSave, canSave, onSkip, progress, saveLabel, skipLabel, loading, error, onRetry, empty, index: indexProp, onIndexChange, className, }: FillInQueueProps<T>): import("react").JSX.Element;
+export declare function FillInQueue<T>({ items, getKey, renderItem, onSave, canSave, onSkip, progress, groups, getGroup, saveLabel, skipLabel, loading, error, onRetry, empty, index: indexProp, onIndexChange, className, }: FillInQueueProps<T>): import("react").JSX.Element;
 export interface FillInChoiceProps<V extends string | number> {
     /** Names the row of choices. */
     label: string;

package/dist/components/app/fill-in-queue.js

@@ -21,6 +21,11 @@ import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-run
 // - Saving: the button shows it's pending; a refusal keeps the record and
 //   says why under the buttons, not in a toast.
 // - Progress: the app counts (`progress`): a bar and "12 of 160 filled".
+// - Groups: records from several sources (a module, a list) name theirs
+//   above the heading with `groups` and `getGroup`: its icon and label,
+//   and, when the group has its own `progress`, "3 of 12 filled" beside
+//   it. With more than one group counted, each one's count is listed
+//   under the bar.
 // - States: `loading` (skeletons), `error` (ErrorState, with `onRetry`),
 //   and an empty queue (`empty`, default "Nothing left to fill in").
 //
@@ -68,7 +73,7 @@ function ownsEnter(element) {
         return true;
     return (element.closest('button, a[href], summary, [role=button], [role=link], [role=combobox], [role=listbox], [role=option], [role=menu], [role=menuitem], [role=menuitemradio], [role=menuitemcheckbox], [role=switch], [role=checkbox], [role=radio], [role=tab]') !== null);
 }
-export function FillInQueue({ items, getKey, renderItem, onSave, canSave = true, onSkip, progress, saveLabel = 'Save and next', skipLabel = 'Skip', loading = false, error, onRetry, empty = 'Nothing left to fill in', index: indexProp, onIndexChange, className, }) {
+export function FillInQueue({ items, getKey, renderItem, onSave, canSave = true, onSkip, progress, groups, getGroup, saveLabel = 'Save and next', skipLabel = 'Skip', loading = false, error, onRetry, empty = 'Nothing left to fill in', index: indexProp, onIndexChange, className, }) {
     const keys = items.map(getKey);
     const [held, setHeld] = useState(() => ({
         key: indexProp !== undefined ? (keys[indexProp] ?? null) : null,
@@ -181,7 +186,8 @@ export function FillInQueue({ items, getKey, renderItem, onSave, canSave = true,
             }
         }
     };
-    const progressBar = progress && _jsx(ProgressLine, { progress: progress });
+    const counted = groups?.filter((group) => group.progress !== undefined) ?? [];
+    const progressBar = (progress || counted.length > 1) && (_jsxs("div", { className: "flex flex-col gap-1.5", children: [progress && _jsx(ProgressLine, { progress: progress }), counted.length > 1 && (_jsx("ul", { className: "flex flex-wrap gap-x-4 gap-y-1 type-caption text-muted-foreground tabular-nums", "data-slot": "fill-in-queue-groups", children: counted.map((group) => (_jsxs("li", { children: [group.label, " ", group.progress?.done, " of ", group.progress?.total] }, group.id))) }))] }));
     if (error !== undefined && error !== null && error !== false) {
         return (_jsx("div", { "data-slot": "fill-in-queue", "data-state": "error", className: className, children: isAppError(error) ? (_jsx(ErrorState, { error: error, onRetry: onRetry })) : (_jsxs(Empty, { "data-state": "error", children: [_jsxs(EmptyHeader, { children: [_jsx(EmptyTitle, { children: "Something went wrong" }), _jsx(EmptyDescription, { children: error })] }), onRetry && (_jsx(Button, { size: "sm", variant: "outline", onClick: onRetry, children: "Try again" }))] })) }));
     }
@@ -192,7 +198,13 @@ export function FillInQueue({ items, getKey, renderItem, onSave, canSave = true,
         return (_jsxs("div", { ref: rootRef, tabIndex: -1, "data-slot": "fill-in-queue", "data-state": "empty", className: cn('flex flex-col gap-6 outline-none', className), children: [progressBar, _jsx(Empty, { children: _jsx(EmptyHeader, { children: _jsx(EmptyTitle, { children: empty }) }) })] }));
     }
     const position = `Record ${index + 1} of ${items.length}`;
-    return (_jsx(ShortcutContext.Provider, { value: register, children: _jsxs("div", { ref: rootRef, tabIndex: -1, "data-slot": "fill-in-queue", "data-state": "success", onKeyDown: onKeyDown, className: cn('flex flex-col gap-6 outline-none', className), children: [_jsxs("div", { className: "flex flex-col gap-2", children: [progressBar, _jsx("p", { className: "type-caption text-muted-foreground tabular-nums", "data-slot": "fill-in-queue-position", children: position })] }), _jsxs("div", { className: "mx-auto flex w-full max-w-[40rem] flex-col gap-6", children: [_jsx("div", { ref: recordRef, role: "group", "aria-label": position, tabIndex: -1, "data-slot": "fill-in-queue-record", className: "flex flex-col gap-6 rounded-lg outline-none focus-visible:ring-[3px] focus-visible:ring-ring/50", children: renderItem(current) }, currentKey ?? undefined), _jsxs("div", { className: "flex flex-col gap-2 border-t border-border pt-4", children: [_jsxs("div", { className: "flex items-center justify-between gap-3", children: [_jsx(Button, { variant: "ghost", onClick: skip, disabled: saving, children: skipLabel }), _jsxs(Button, { onClick: () => void save(), disabled: !savable || saving, "aria-busy": saving || undefined, children: [saving && _jsx(Spinner, { "aria-hidden": "true", role: "presentation", "aria-label": undefined, "data-icon": "inline-start" }), saveLabel] })] }), saveError !== null && (_jsx("p", { role: "alert", className: "text-end type-caption text-destructive-text", children: saveError }))] })] })] }) }));
+    const groupId = getGroup?.(current);
+    const group = groupId === undefined ? undefined : groups?.find((g) => g.id === groupId);
+    return (_jsx(ShortcutContext.Provider, { value: register, children: _jsxs("div", { ref: rootRef, tabIndex: -1, "data-slot": "fill-in-queue", "data-state": "success", onKeyDown: onKeyDown, className: cn('flex flex-col gap-6 outline-none', className), children: [_jsxs("div", { className: "flex flex-col gap-2", children: [progressBar, _jsx("p", { className: "type-caption text-muted-foreground tabular-nums", "data-slot": "fill-in-queue-position", children: position })] }), _jsxs("div", { className: "mx-auto flex w-full max-w-[40rem] flex-col gap-6", children: [_jsxs("div", { ref: recordRef, role: "group", "aria-label": position, tabIndex: -1, "data-slot": "fill-in-queue-record", className: "flex flex-col gap-6 rounded-lg outline-none focus-visible:ring-[3px] focus-visible:ring-ring/50", children: [group && _jsx(GroupLine, { group: group, label: progress?.label }), renderItem(current)] }, currentKey ?? undefined), _jsxs("div", { className: "flex flex-col gap-2 border-t border-border pt-4", children: [_jsxs("div", { className: "flex items-center justify-between gap-3", children: [_jsx(Button, { variant: "ghost", onClick: skip, disabled: saving, children: skipLabel }), _jsxs(Button, { onClick: () => void save(), disabled: !savable || saving, "aria-busy": saving || undefined, children: [saving && _jsx(Spinner, { "aria-hidden": "true", role: "presentation", "aria-label": undefined, "data-icon": "inline-start" }), saveLabel] })] }), saveError !== null && (_jsx("p", { role: "alert", className: "text-end type-caption text-destructive-text", children: saveError }))] })] })] }) }));
+}
+function GroupLine({ group, label = 'filled' }) {
+    const Icon = group.icon;
+    return (_jsxs("p", { className: "-mb-4 flex items-center gap-1.5 type-caption text-muted-foreground", "data-slot": "fill-in-queue-group", children: [Icon && _jsx(Icon, { className: "size-4", "aria-hidden": "true" }), _jsx("span", { className: "font-medium", children: group.label }), group.progress && (_jsxs("span", { className: "tabular-nums", children: ["\u00B7 ", group.progress.done, " of ", group.progress.total, " ", label] }))] }));
 }
 function ProgressLine({ progress }) {
     const { done, total, label = 'filled' } = progress;

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;