@tristan2828/ui-foundation 4.60.0 → 4.61.1

package/README.md

@@ -18,7 +18,7 @@ than installing this by hand:
 
 | Import | What |
 |---|---|
-| `@tristan2828/ui-foundation` | `AppShell`, `DataTable`, `EntityView` (with `EditableValue`, `editInPlace`), `EntityForm`, `Markdown` (with `countTasks`, `toggleTaskAt`), `RichTextEditor`, `ErrorState`, `MultiChoice`, `MultiReference`, `ListEditor`, `PasswordInput`, `RouteErrorBoundary`, `FoundationProviders`, `DataEnvironmentBanner`, `LoginRoute`, `RegisterRoute`, `useAuth`, `useTableUrlState`, `useRecordUpdate`, `useDebouncedValue`, `createQueryClient`, `cn`; types `Page`, `AppError`, `QuerySpec`. For timed screens (`docs/foundation/timed-screens.md`): `SessionView`, `useSessionClock`, `useWakeLock`, `useMuted`, `usePrefersReducedMotion`, and the audio cues `unlockAudio`, `chime`, `sequence`, `cancelCues`, `onCuesRecovered`, `cuesInSync`, `keepAudioAlive`, `say`, `hush`, `vibrate`, `canVibrate`. For reminders (`docs/foundation/reminders.md`): `AllowReminders`, `usePushPermission`. For a record opened in a dialog over its list (`docs/foundation/add-an-entity.md`): `RecordDialogRoute`, `RecordLink`, `useOpenRecord`, `useRecordDialog`, `recordDialogState` |
+| `@tristan2828/ui-foundation` | `AppShell`, `DataTable`, `EntityView` (with `EditableValue`, `editInPlace`, printing its notes and `usePrinting`), `EntityForm`, `Markdown` (with `countTasks`, `toggleTaskAt`), `RichTextEditor`, `ErrorState`, `MultiChoice`, `MultiReference`, `ListEditor`, `PasswordInput`, `RouteErrorBoundary`, `FoundationProviders`, `DataEnvironmentBanner`, `LoginRoute`, `RegisterRoute`, `useAuth`, `useTableUrlState`, `useRecordUpdate`, `useDebouncedValue`, `createQueryClient`, `cn`; types `Page`, `AppError`, `QuerySpec`. For timed screens (`docs/foundation/timed-screens.md`): `SessionView`, `useSessionClock`, `useWakeLock`, `useMuted`, `usePrefersReducedMotion`, and the audio cues `unlockAudio`, `chime`, `sequence`, `cancelCues`, `onCuesRecovered`, `cuesInSync`, `keepAudioAlive`, `say`, `hush`, `vibrate`, `canVibrate`. For reminders (`docs/foundation/reminders.md`): `AllowReminders`, `usePushPermission`. For a record opened in a dialog over its list (`docs/foundation/add-an-entity.md`): `RecordDialogRoute`, `RecordLink`, `useOpenRecord`, `useRecordDialog`, `recordDialogState` |
 | `@tristan2828/ui-foundation/ui/<name>` | shadcn primitives: badge, button, calendar, card, checkbox, combobox, dialog, empty, field, input, input-group, label, popover, select, separator, sheet, sidebar, skeleton, sonner, spinner, switch, table, textarea, tooltip |
 | `@tristan2828/ui-foundation/gateway` | `safeFetch`, `toAppError`, `networkError` — for an app's `src/api/gateway/` only |
 | `@tristan2828/ui-foundation/mocks` | MSW: `authHandlers`, `environmentHandlers`, `resetMockAuth`, `getMockCurrentUser`, `MOCK_USER`, `exposeMswForE2E` |

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

@@ -4,22 +4,22 @@
 ## Index
 
 - [The reference files](#the-reference-files) · lines 38–60
-- [Before anything: the entity plan](#before-anything-the-entity-plan) · lines 62–731
+- [Before anything: the entity plan](#before-anything-the-entity-plan) · lines 62–743
   - Step 1: Add `<Entity>` to `openapi.yaml` · lines 100–107
   - Step 2: `npm run gen:api` · lines 108–109
   - Step 3: Add gateway tests in `tests/gateway/<entity>.test.ts`, derived from the spec · lines 110–121
   - Step 4: Add MSW handlers in `src/mocks/<entity>.ts` · lines 122–131
   - Step 5: Add a gateway module in `src/api/gateway/<entity>.ts` · lines 132–136
-  - Step 6: Copy the reference files, one for one, not just the two screens · lines 137–620
-  - Step 7: Register routes · lines 621–634
-  - Step 8: Add Playwright specs for all three screens · lines 635–713
-  - Step 9: Register the nav entry and route names · lines 714–728
-  - Step 10: `npm run verify`. · lines 729–731
-- [Opening a record over its list](#opening-a-record-over-its-list) · lines 733–789
-- [What not to copy](#what-not-to-copy) · lines 791–817
-- [After a commit, in the backend](#after-a-commit-in-the-backend) · lines 819–836
-- [Deleting](#deleting) · lines 838–867
-- [Fields only a script writes](#fields-only-a-script-writes) · lines 869–890
+  - Step 6: Copy the reference files, one for one, not just the two screens · lines 137–632
+  - Step 7: Register routes · lines 633–646
+  - Step 8: Add Playwright specs for all three screens · lines 647–725
+  - Step 9: Register the nav entry and route names · lines 726–740
+  - Step 10: `npm run verify`. · lines 741–743
+- [Opening a record over its list](#opening-a-record-over-its-list) · lines 745–801
+- [What not to copy](#what-not-to-copy) · lines 803–829
+- [After a commit, in the backend](#after-a-commit-in-the-backend) · lines 831–848
+- [Deleting](#deleting) · lines 850–879
+- [Fields only a script writes](#fields-only-a-script-writes) · lines 881–902
 
 <!-- /index -->
 
@@ -495,6 +495,18 @@ is a filled-in example while the Widgets demo is still here).
      (`useEdit<Entity>Field`). Without the prop the boxes are pictures
      and the text stays read-only. A list's "2/5" column counts them
      with `countTasks(text)` (`{ done, total }`; `total` 0 for none).
+   - **Notes worth taking on paper** (a visit's prep and questions, a
+     guide, a checklist to tick by hand): mark each of those sections
+     `print: true`. The header gets a Print notes button (`printLabel`
+     renames it) that prints the marked sections alone, under the title
+     and subtitle: no rail, no shell, no buttons, light paper in either
+     theme, headings and bullets as written, nothing folded, tables
+     ruled with room in their empty cells. `print: { answerSpace: true }`
+     also leaves space under each item of the section's numbered lists,
+     for questions answered by hand. A section's own content that should
+     print differently (a list of sub-items as plain text) reads
+     `usePrinting()`, true in the printed copy. The browser's own print
+     (Ctrl+P) still prints the whole page.
    - **Quick actions: only the fields the plan's `Quick actions` line
      names**, each a control that saves on its own (cell pattern 17,
      `widget-quick-actions.tsx`). A `yes/no` is a

package/dist/components/app/entity-view-print.d.ts

@@ -0,0 +1,24 @@
+import { type ReactNode } from 'react';
+/** What a section marked to print gives the printed copy. */
+export type EntityViewPrintSection = {
+    title: string;
+    /** The section's content, or its fields as label/value rows. */
+    content?: ReactNode;
+    fields?: {
+        label: string;
+        value: ReactNode;
+    }[];
+    emptyLabel?: string;
+    answerSpace: boolean;
+};
+/**
+ * The header's Print notes button and, while it prints, the printed copy.
+ * The copy mounts, then the browser's print dialog opens on it; it goes
+ * when the dialog closes (`afterprint`).
+ */
+export declare function PrintNotes({ label, title, subtitle, sections, }: {
+    label: string;
+    title?: string;
+    subtitle?: ReactNode;
+    sections: EntityViewPrintSection[];
+}): import("react").JSX.Element;

package/dist/components/app/entity-view-print.js

@@ -0,0 +1,51 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+// A record's notes on paper: EntityView's Print notes button and the copy
+// it prints. Sections marked `print` (the long text: details, prep,
+// questions) are printed under the record's title and subtitle, and
+// nothing else: no sidebar, no header bar, no rail, no buttons.
+//
+// The copy is rendered only while printing, into <body> (a portal, so it
+// sits beside the app rather than inside its layout), and styles/index.css
+// "Printed notes" hides everything else on paper and keeps it light even
+// in the dark theme. On screen it never shows. Its content is each
+// section's own markup, read-only (PrintingContext): <Markdown> prints
+// whole, unfolded, with tables ruled and room in their empty cells to
+// write. A section marked `print: { answerSpace: true }` leaves space
+// under each item of its numbered lists, for questions answered by hand.
+//
+// The browser's own print (Ctrl+P) still prints the page as it is; only
+// the button prints the notes alone.
+import { useEffect, useState } from 'react';
+import { createPortal } from 'react-dom';
+import { PrinterIcon } from 'lucide-react';
+import { Button } from '../ui/button.js';
+import { PrintingContext } from './print-context.js';
+function isEmpty(value) {
+    return value === null || value === undefined || value === false || value === '' || (Array.isArray(value) && value.length === 0);
+}
+function PrintedSection({ section }) {
+    return (_jsxs("section", { "data-answer-space": section.answerSpace ? '' : undefined, className: "flex flex-col gap-3", children: [_jsx("h2", { className: "border-b border-border pb-1 type-label tracking-[0.08em] text-muted-foreground uppercase", children: section.title }), section.fields ? (_jsx("dl", { className: "grid grid-cols-[auto_1fr] gap-x-6 gap-y-1 type-body", children: section.fields.map((field) => (_jsxs("div", { className: "contents", children: [_jsx("dt", { className: "type-label text-muted-foreground", children: field.label }), _jsx("dd", { className: "min-w-0 break-words text-foreground", children: isEmpty(field.value) ? '—' : field.value })] }, field.label))) })) : (_jsx("div", { className: "min-w-0 type-body break-words text-foreground", children: isEmpty(section.content) ? _jsx("span", { className: "text-muted-foreground", children: section.emptyLabel ?? 'Not set' }) : section.content }))] }));
+}
+function PrintedNotes({ title, subtitle, sections }) {
+    return createPortal(_jsx(PrintingContext.Provider, { value: true, children: _jsxs("article", { "data-print-notes": "", "data-slot": "entity-view-print", className: "hidden flex-col gap-6 bg-background text-foreground print:flex", children: [_jsxs("header", { className: "flex flex-col gap-1", children: [_jsx("h1", { className: "type-heading-1 break-words", children: title }), subtitle && _jsx("div", { className: "type-body break-words text-muted-foreground", children: subtitle })] }), sections.map((section) => (_jsx(PrintedSection, { section: section }, section.title)))] }) }), document.body);
+}
+/**
+ * The header's Print notes button and, while it prints, the printed copy.
+ * The copy mounts, then the browser's print dialog opens on it; it goes
+ * when the dialog closes (`afterprint`).
+ */
+export function PrintNotes({ label, title, subtitle, sections, }) {
+    // How many times it's been pressed since the copy last went: a press
+    // while one is up (a browser that never said the dialog closed) prints
+    // it again rather than doing nothing.
+    const [printing, setPrinting] = useState(0);
+    useEffect(() => {
+        if (printing === 0)
+            return;
+        const done = () => setPrinting(0);
+        window.addEventListener('afterprint', done);
+        window.print();
+        return () => window.removeEventListener('afterprint', done);
+    }, [printing]);
+    return (_jsxs(_Fragment, { children: [_jsxs(Button, { variant: "outline", onClick: () => setPrinting((count) => count + 1), children: [_jsx(PrinterIcon, {}), label] }), printing > 0 && _jsx(PrintedNotes, { title: title, subtitle: subtitle, sections: sections })] }));
+}

package/dist/components/app/entity-view.d.ts

@@ -44,6 +44,17 @@ export type EntityViewSection = ({
      * long text and long lists. The `column` layout ignores it.
      */
     placement?: EntityViewPlacement;
+    /**
+     * The section is part of the record's printed notes: marking any one
+     * adds a Print notes button to the header, which prints the marked
+     * sections alone (their content as shown, read-only, nothing folded)
+     * under the title and subtitle. `{ answerSpace: true }` also leaves
+     * room under each item of the section's numbered lists, to write an
+     * answer by hand (a visit's questions).
+     */
+    print?: boolean | {
+        answerSpace?: boolean;
+    };
 };
 export type EntityViewPlacement = 'main' | 'rail';
 /**
@@ -115,6 +126,8 @@ export type EntityViewProps = {
      * ignores it.
      */
     mobileOrder?: EntityViewMobileOrder;
+    /** The Print notes button's words, when a section is marked `print`. Defaults to "Print notes". */
+    printLabel?: string;
     /** The rail's landmark name (its `<aside>`). Defaults to the title + " details". */
     railLabel?: string;
     isLoading: boolean;
@@ -127,4 +140,4 @@ export type EntityViewProps = {
         label: string;
     };
 };
-export declare function EntityView({ title, documentTitle, titleEdit, subtitle, badges, actions, notice, strip, sections, footer, layout, mobileOrder, railLabel, isLoading, error, onRetry, back, }: EntityViewProps): import("react").JSX.Element;
+export declare function EntityView({ title, documentTitle, titleEdit, subtitle, badges, actions, notice, strip, sections, footer, layout, mobileOrder, railLabel, printLabel, isLoading, error, onRetry, back, }: EntityViewProps): import("react").JSX.Element;

package/dist/components/app/entity-view.js

@@ -40,6 +40,11 @@ import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-run
 // to the dialog's bar (Open full page, Close), and not found's way out
 // closes the dialog.
 //
+// Printing the notes (entity-view-print.tsx): sections marked `print`
+// (the long text: details, prep, questions) give the header a Print notes
+// button, which prints those sections alone under the title and
+// subtitle, with no rail, shell or buttons, on light paper.
+//
 // Two layouts. `column` (the default): every section in one column capped
 // at max-w-4xl. `rail`, for a record with long content: the page takes the
 // content area's whole width, sections placed `rail` go in a narrow column
@@ -60,6 +65,7 @@ import { Card, CardContent, CardHeader } from '../ui/card.js';
 import { Empty, EmptyContent, EmptyDescription, EmptyHeader, EmptyMedia, EmptyTitle, } from '../ui/empty.js';
 import { Skeleton } from '../ui/skeleton.js';
 import { useDocumentTitle } from '../../hooks/use-document-title.js';
+import { PrintNotes } from './entity-view-print.js';
 import { EditInPlaceContext } from './edit-in-place.js';
 import { EditInPlaceStore } from './edit-in-place-store.js';
 import { EditableList } from './editable-list.js';
@@ -153,7 +159,7 @@ function Rail({ label, sections }) {
     const [ref, fits] = useFitsWindow();
     return (_jsx("aside", { ref: ref, "aria-label": label, "data-fits": fits ? '' : undefined, className: cn(RAIL_LAYOUT.rail, RAIL_LAYOUT.sticky, 'flex min-w-0 flex-col gap-6'), children: sections.map((section) => (_jsx(ViewSection, { section: section, inRail: true }, section.title))) }));
 }
-export function EntityView({ title, documentTitle, titleEdit, subtitle, badges, actions, notice, strip, sections, footer, layout = 'column', mobileOrder = 'rail-first', railLabel, isLoading, error, onRetry, back, }) {
+export function EntityView({ title, documentTitle, titleEdit, subtitle, badges, actions, notice, strip, sections, footer, layout = 'column', mobileOrder = 'rail-first', railLabel, printLabel = 'Print notes', isLoading, error, onRetry, back, }) {
     // Editing in place: one store per view, and the leave-page prompt only
     // while a field is open (or one is always editable).
     const [store] = useState(() => new EditInPlaceStore());
@@ -171,8 +177,16 @@ export function EntityView({ title, documentTitle, titleEdit, subtitle, badges,
         return _jsx(ErrorState, { error: error, onRetry: onRetry });
     if (isLoading)
         return _jsx(EntityViewSkeleton, { layout: layout, mobileOrder: mobileOrder });
+    const printSections = sections
+        .filter((section) => section.print)
+        .map((section) => ({
+        title: section.title,
+        ...('fields' in section ? { fields: section.fields } : { content: section.content, emptyLabel: section.emptyLabel }),
+        answerSpace: typeof section.print === 'object' && section.print.answerSpace === true,
+    }));
+    const printButton = printSections.length > 0 && (_jsx(PrintNotes, { label: printLabel, title: title, subtitle: subtitle, sections: printSections }));
     const railSections = sections.filter((section) => section.placement === 'rail');
     const mainSections = sections.filter((section) => section.placement !== 'rail');
     const main = (_jsx("div", { className: cn(RAIL_LAYOUT.main, railSections.length === 0 && RAIL_LAYOUT.mainAlone), children: mainSections.map((section) => (_jsx(ViewSection, { section: section }, section.title))) }));
-    return (_jsx(EditInPlaceContext.Provider, { value: store, children: _jsxs("div", { className: layout === 'rail' ? RAIL_LAYOUT.page : 'flex max-w-4xl flex-col gap-6', "data-state": "success", "data-layout": layout, children: [editing && _jsx(LeaveGuard, { store: store }), !dialog && _jsx(BackLink, { back: back }), _jsxs("header", { className: "flex flex-col gap-3 sm:flex-row sm:items-start sm:justify-between", children: [_jsxs("div", { className: "flex min-w-0 flex-1 flex-col gap-2", children: [_jsx("h1", { id: dialog?.titleId, className: "type-page-title break-words text-foreground", children: titleEdit ? (_jsx(EditableValue, { label: titleEdit.label, edit: titleEdit, layout: "inline", className: "w-full", children: title })) : (title) }), subtitle && (_jsx("div", { "data-slot": "entity-view-subtitle", className: "type-body break-words text-muted-foreground", children: subtitle })), badges && _jsx("div", { className: "flex flex-wrap items-center gap-1.5", children: badges })] }), actions && _jsx("div", { className: "flex shrink-0 flex-wrap items-center gap-2", children: actions })] }), _jsx("div", { role: "status", "data-slot": "entity-view-notice", className: "empty:hidden", children: notice }), strip && _jsx("div", { "data-slot": "entity-view-strip", children: strip }), layout === 'rail' ? (_jsxs("div", { className: RAIL_LAYOUT.columns, children: [mobileOrder === 'main-first' && main, railSections.length > 0 && (_jsx(Rail, { label: railLabel ?? `${title ?? 'Record'} details`, sections: railSections })), mobileOrder === 'rail-first' && main] })) : (sections.map((section) => _jsx(ViewSection, { section: section }, section.title))), footer && (_jsx("footer", { "data-slot": "entity-view-footer", className: "type-caption text-muted-foreground", children: footer }))] }) }));
+    return (_jsx(EditInPlaceContext.Provider, { value: store, children: _jsxs("div", { className: layout === 'rail' ? RAIL_LAYOUT.page : 'flex max-w-4xl flex-col gap-6', "data-state": "success", "data-layout": layout, children: [editing && _jsx(LeaveGuard, { store: store }), !dialog && _jsx(BackLink, { back: back }), _jsxs("header", { className: "flex flex-col gap-3 sm:flex-row sm:items-start sm:justify-between", children: [_jsxs("div", { className: "flex min-w-0 flex-1 flex-col gap-2", children: [_jsx("h1", { id: dialog?.titleId, className: "type-page-title break-words text-foreground", children: titleEdit ? (_jsx(EditableValue, { label: titleEdit.label, edit: titleEdit, layout: "inline", className: "w-full", children: title })) : (title) }), subtitle && (_jsx("div", { "data-slot": "entity-view-subtitle", className: "type-body break-words text-muted-foreground", children: subtitle })), badges && _jsx("div", { className: "flex flex-wrap items-center gap-1.5", children: badges })] }), (actions || printButton) && (_jsxs("div", { className: "flex shrink-0 flex-wrap items-center gap-2", children: [printButton, actions] }))] }), _jsx("div", { role: "status", "data-slot": "entity-view-notice", className: "empty:hidden", children: notice }), strip && _jsx("div", { "data-slot": "entity-view-strip", children: strip }), layout === 'rail' ? (_jsxs("div", { className: RAIL_LAYOUT.columns, children: [mobileOrder === 'main-first' && main, railSections.length > 0 && (_jsx(Rail, { label: railLabel ?? `${title ?? 'Record'} details`, sections: railSections })), mobileOrder === 'rail-first' && main] })) : (sections.map((section) => _jsx(ViewSection, { section: section }, section.title))), footer && (_jsx("footer", { "data-slot": "entity-view-footer", className: "type-caption text-muted-foreground", children: footer }))] }) }));
 }

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

@@ -46,4 +46,4 @@ export type MarkdownProps = {
     onTasksChange?: (markdown: string) => void | Promise<unknown>;
     className?: string;
 } & Omit<ComponentProps<'div'>, 'children'>;
-export declare function Markdown({ children, headingLevel, headingFrom, foldKey: foldKeyProp, foldable, onTasksChange, className, ...rest }: MarkdownProps): import("react").JSX.Element;
+export declare function Markdown({ children, headingLevel, headingFrom, foldKey: foldKeyProp, foldable, onTasksChange: onTasksChangeProp, className, ...rest }: MarkdownProps): import("react").JSX.Element;

package/dist/components/app/markdown.js

@@ -45,6 +45,9 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 // this device under the key and shared with an editor or NotesOutline
 // given the same one. The text itself is never changed.
 //
+// Printed (EntityView's Print notes, PrintingContext), it's the whole
+// text: nothing folded, no fold buttons, task boxes as glyphs.
+//
 // A task item (`- [ ] to do`, `- [x] done`) shows its box as a glyph
 // with its state in words: read-only text has nothing to tick. With
 // `onTasksChange`, each box is a real checkbox, named for its item's
@@ -65,6 +68,7 @@ import { isHighlightColor, remarkHighlights } from '../../lib/markdown-highlight
 import { toggleTaskAt } from '../../lib/markdown-tasks.js';
 import { textTopHeading } from '../../lib/markdown-top-heading.js';
 import { CALLOUT_BOX, CALLOUT_LOOK, DEFAULT_HEADING_LEVEL, FOLD_BUTTON, FOLD_HEADING, headingBand, headingClass, headingTag, PROSE, PROSE_INSET, } from './prose-look.js';
+import { usePrinting } from './print-context.js';
 import { headerTexts, TABLE_SCROLL_FOCUS, watchTableScroll } from './prose-table-scroll.js';
 const REMARK_PLUGINS = [remarkGfm, remarkCallouts, remarkHighlights];
 const HIGHLIGHT_WASH = {
@@ -232,8 +236,12 @@ function componentsFor(top, textTop) {
     }
     return components;
 }
-export function Markdown({ children, headingLevel = DEFAULT_HEADING_LEVEL, headingFrom = 'hash', foldKey: foldKeyProp, foldable = true, onTasksChange, className, ...rest }) {
-    const foldKey = foldable ? foldKeyProp : undefined;
+export function Markdown({ children, headingLevel = DEFAULT_HEADING_LEVEL, headingFrom = 'hash', foldKey: foldKeyProp, foldable = true, onTasksChange: onTasksChangeProp, className, ...rest }) {
+    // On paper (EntityView's Print notes): every heading plain and open,
+    // every task box a picture.
+    const printing = usePrinting();
+    const onTasksChange = printing ? undefined : onTasksChangeProp;
+    const foldKey = foldable && !printing ? foldKeyProp : undefined;
     const textTop = useMemo(() => (headingFrom === 'text' ? textTopHeading(children) : 1), [headingFrom, children]);
     const components = useMemo(() => componentsFor(headingLevel, textTop), [headingLevel, textTop]);
     const [folded, setFolded] = useFolds(foldKey);

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

@@ -814,8 +814,9 @@ export default function MilkdownEditor({ id, defaultValue, onChange, onProblem,
                 void editor.destroy();
             root.replaceChildren();
         };
-        // Made once per mount: later changes to defaultValue are ignored, as
-        // with any uncontrolled input. Attributes and read-only follow below.
+        // Made once per mount. A new defaultValue the editor didn't report
+        // remounts it (RichTextEditor's key), so it isn't read here.
+        // Attributes and read-only follow below.
         // eslint-disable-next-line react-hooks/exhaustive-deps
     }, []);
     // Read-only and the ARIA attributes follow their props.

package/dist/components/app/print-context.d.ts

@@ -0,0 +1,3 @@
+export declare const PrintingContext: import("react").Context<boolean>;
+/** True inside a printed copy of a record's notes. */
+export declare function usePrinting(): boolean;

package/dist/components/app/print-context.js

@@ -0,0 +1,10 @@
+// Whether what's rendering is a printed copy (EntityView's Print notes,
+// entity-view-print.tsx). Content that has a screen-only side reads it:
+// <Markdown> keeps its headings plain and unfolded and its task boxes as
+// pictures, since paper has nothing to click.
+import { createContext, useContext } from 'react';
+export const PrintingContext = createContext(false);
+/** True inside a printed copy of a record's notes. */
+export function usePrinting() {
+    return useContext(PrintingContext);
+}

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

@@ -3,7 +3,11 @@ import type { HeadingFrom, HeadingLevel } from './prose-look.js';
 export type RichTextEditorProps = {
     /** The editable element's id, for a label's `htmlFor` or a test. */
     id?: string;
-    /** The Markdown it opens with. Read once, when it mounts (uncontrolled). */
+    /**
+     * The Markdown it opens with. A later value the editor didn't report
+     * (a record loaded after it mounted, a reset) replaces the text; the
+     * value it reported, passed back, changes nothing.
+     */
     defaultValue: string;
     /** The Markdown to save, after every edit: untouched blocks as originally written. */
     onChange: (markdown: string) => void;

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

@@ -26,13 +26,41 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 // With `foldKey`, the text folds by its headings (NotesOutline lists them
 // beside it), the Markdown untouched.
 //
+// `defaultValue` is read when it mounts, then followed: a new value the
+// editor didn't report itself (a form's loaded record arriving after the
+// editor, a reset) replaces the text, as if it opened with it. Its own
+// edits, coming back as the value, change nothing, so the caret stays
+// where it is. A caller that never feeds `onChange` back keeps its text.
+//
 // 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.
-import { lazy, Suspense } from 'react';
+import { lazy, Suspense, useState } from 'react';
 import { cn } from 'cn';
 import { Skeleton } from '../ui/skeleton.js';
 const MilkdownEditor = lazy(() => import('./milkdown-editor.js'));
+// When the editor opens again: each time `defaultValue` changes to
+// Markdown it didn't report. Adjusted while rendering (React's "storing
+// information from previous renders"), so the new text never shows a
+// frame late.
+function useOpenings(defaultValue) {
+    const [seen, setSeen] = useState(defaultValue);
+    const [reported, setReported] = useState(defaultValue);
+    const [opening, setOpening] = useState(0);
+    if (defaultValue !== seen) {
+        setSeen(defaultValue);
+        if (defaultValue !== reported) {
+            setReported(defaultValue);
+            setOpening(opening + 1);
+        }
+    }
+    return { opening, report: setReported };
+}
 export function RichTextEditor(props) {
-    return (_jsx(Suspense, { fallback: _jsxs("div", { "data-slot": "rich-text-editor", "data-state": "loading", className: cn('flex w-full flex-col', !props.inline && 'rounded-lg border border-input', props.className), children: [(props.toolbar ?? true) === true && _jsx("div", { className: "h-9 border-b border-input" }), _jsxs("div", { className: cn('flex flex-col gap-2', props.inline ? 'py-0.5' : 'min-h-24 px-2.5 py-2'), children: [_jsx(Skeleton, { className: "h-4 w-3/4" }), _jsx(Skeleton, { className: "h-4 w-1/2" })] })] }), children: _jsx(MilkdownEditor, { ...props, foldKey: props.foldable === false ? undefined : props.foldKey }) }));
+    const { opening, report } = useOpenings(props.defaultValue);
+    const { onChange } = props;
+    return (_jsx(Suspense, { fallback: _jsxs("div", { "data-slot": "rich-text-editor", "data-state": "loading", className: cn('flex w-full flex-col', !props.inline && 'rounded-lg border border-input', props.className), children: [(props.toolbar ?? true) === true && _jsx("div", { className: "h-9 border-b border-input" }), _jsxs("div", { className: cn('flex flex-col gap-2', props.inline ? 'py-0.5' : 'min-h-24 px-2.5 py-2'), children: [_jsx(Skeleton, { className: "h-4 w-3/4" }), _jsx(Skeleton, { className: "h-4 w-1/2" })] })] }), children: _jsx(MilkdownEditor, { ...props, onChange: (markdown) => {
+                report(markdown);
+                onChange(markdown);
+            }, foldKey: props.foldable === false ? undefined : props.foldKey }, opening) }));
 }

package/dist/index.d.ts

@@ -13,6 +13,7 @@ export { byDay, type ByDayOptions } from './lib/group-by-day.js';
 export { EntityForm, type EntityFormProps } from './components/app/entity-form.js';
 export { KeyStats, type KeyStat, type KeyStatsProps } from './components/app/key-stats.js';
 export { EntityView, type EntityViewField, type EntityViewLayout, type EntityViewMobileOrder, type EntityViewPlacement, type EntityViewProps, type EntityViewSection, } from './components/app/entity-view.js';
+export { usePrinting } from './components/app/print-context.js';
 export { RecordDialogRoute, RecordLink, type RecordDialogRouteProps, type RecordLinkProps, } from './components/app/record-dialog.js';
 export { recordDialogState, useOpenRecord, useRecordDialog, type RecordDialogBackground, type RecordDialogContextValue, type RecordDialogState, } from './components/app/record-dialog-context.js';
 export { editInPlace, type EditControlProps, type EditInPlace, type EditInPlaceList, type EditInPlaceListOptions, type EditInPlaceOptions, type EditKind, type EditListAddProps, type EditListItemProps, } from './components/app/edit-in-place.js';

package/dist/index.js

@@ -17,6 +17,7 @@ export { byDay } from './lib/group-by-day.js';
 export { EntityForm } from './components/app/entity-form.js';
 export { KeyStats } from './components/app/key-stats.js';
 export { EntityView, } from './components/app/entity-view.js';
+export { usePrinting } from './components/app/print-context.js';
 export { RecordDialogRoute, RecordLink, } from './components/app/record-dialog.js';
 export { recordDialogState, useOpenRecord, useRecordDialog, } from './components/app/record-dialog-context.js';
 export { editInPlace, } from './components/app/edit-in-place.js';

package/package.json

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

package/styles/index.css

@@ -158,3 +158,84 @@
     @apply font-sans;
     }
 }
+
+/* Printed notes (EntityView's Print notes, src/components/app/entity-view-print.tsx).
+   While its copy is in <body>, paper shows that copy alone: the app beside
+   it (shell, header, rail, dialogs) is left off, and the copy is in the
+   light theme's colours even when the screen is dark. Its buttons (edit
+   pencils, move and remove) are left off too: paper has nothing to press.
+   Tables are ruled all round, never cut off at the scroll box's edge, and
+   their cells tall enough to write in; a heading stays with what follows
+   it; a section marked answerSpace leaves room under each numbered item. */
+@media print {
+  body:has(> [data-print-notes]) > :not([data-print-notes]) {
+    display: none !important;
+  }
+  :root:has(> body > [data-print-notes]) {
+    --background: var(--white);
+    --foreground: var(--black);
+    --card: var(--white);
+    --card-foreground: var(--black);
+    --popover: var(--white);
+    --popover-foreground: var(--black);
+    --primary: var(--gray-950);
+    --primary-foreground: var(--gray-50);
+    --secondary: var(--gray-100);
+    --secondary-foreground: var(--gray-950);
+    --muted: var(--gray-100);
+    --muted-foreground: var(--gray-500);
+    --accent: var(--gray-100);
+    --accent-foreground: var(--gray-950);
+    --destructive-text: var(--red-700);
+    --success-text: var(--green-800);
+    --warning-text: var(--amber-800);
+    --info-text: var(--blue-800);
+    --link: var(--blue-700);
+    --highlight-amber: oklch(0.9 0.1 75);
+    --highlight-yellow: oklch(0.94 0.13 100);
+    --highlight-green: oklch(0.9 0.1 150);
+    --highlight-red: oklch(0.89 0.07 25);
+    --rule: var(--gray-400);
+    --heading-band: var(--gray-200);
+    --heading-bar: var(--blue-700);
+    --table-stripe: var(--white);
+    --border: var(--gray-400);
+    --input: var(--gray-200);
+    color-scheme: light;
+    background: var(--white);
+  }
+  [data-print-notes] button {
+    display: none !important;
+  }
+  [data-print-notes] :is(h1, h2, h3, h4, h5, h6) {
+    break-after: avoid;
+  }
+  [data-print-notes] [data-slot="table-container"] {
+    /* Not w-full: the text's inset margins would push its right edge
+       off the paper. */
+    width: auto;
+    overflow: visible;
+    border: 0;
+    border-radius: 0;
+  }
+  [data-print-notes] table {
+    border-collapse: collapse;
+  }
+  [data-print-notes] tr {
+    break-inside: avoid;
+  }
+  [data-print-notes] :is(th, td) {
+    border: 1px solid var(--border);
+    background: var(--white);
+  }
+  [data-print-notes] td {
+    height: 2.5rem;
+  }
+  [data-print-notes] [data-answer-space] ol > li {
+    padding-bottom: 5rem;
+    break-inside: avoid;
+  }
+  [data-print-notes] [data-answer-space] li ol > li {
+    padding-bottom: 0;
+  }
+}