mosage 0.2.0 → 0.8.0

package/src/app/lib/flow.test.ts

@@ -0,0 +1,110 @@
+import { describe, expect, it } from 'vitest';
+import { type BlockMetrics, paginateBlocks } from './flow.ts';
+
+const b = (height: number, extra: Partial<BlockMetrics> = {}): BlockMetrics => ({
+  height,
+  ...extra,
+});
+
+describe('paginateBlocks', () => {
+  it('fills a page before starting the next', () => {
+    const { pages } = paginateBlocks([b(300), b(300), b(300), b(300)], 1000);
+    expect(pages).toEqual([[0, 1, 2], [3]]);
+  });
+
+  it('keeps everything on one page when it fits', () => {
+    const { pages } = paginateBlocks([b(100), b(100)], 1000);
+    expect(pages).toEqual([[0, 1]]);
+  });
+
+  it('never leaves a heading as the last block on a page', () => {
+    // The heading fits at the bottom, but its body does not — both move.
+    const { pages } = paginateBlocks([b(400), b(400), b(60, { keepWithNext: true }), b(300)], 1000);
+    expect(pages).toEqual([
+      [0, 1],
+      [2, 3],
+    ]);
+  });
+
+  it('moves a run of stacked headings together', () => {
+    const { pages } = paginateBlocks(
+      [b(800), b(50, { keepWithNext: true }), b(50, { keepWithNext: true }), b(300)],
+      1000,
+    );
+    expect(pages).toEqual([[0], [1, 2, 3]]);
+  });
+
+  it('pulls a figure along with its caption', () => {
+    const { pages } = paginateBlocks([b(300), b(600), b(120, { keepWithPrevious: true })], 1000);
+    expect(pages).toEqual([[0], [1, 2]]);
+  });
+
+  it('honours an explicit page break', () => {
+    const { pages } = paginateBlocks([b(100), b(100, { breakBefore: true }), b(100)], 1000);
+    expect(pages).toEqual([[0], [1, 2]]);
+  });
+
+  it('gives an oversized block its own page and reports it', () => {
+    const { pages, overflowing } = paginateBlocks([b(200), b(1400), b(200)], 1000);
+    expect(pages).toEqual([[0], [1], [2]]);
+    expect(overflowing).toEqual([1]);
+  });
+
+  it('does not strand a page when every block wants to keep with the next', () => {
+    const { pages } = paginateBlocks(
+      [b(600, { keepWithNext: true }), b(600, { keepWithNext: true }), b(600)],
+      1000,
+    );
+    expect(pages).toEqual([[0], [1], [2]]);
+  });
+
+  it('returns no pages for no blocks', () => {
+    expect(paginateBlocks([], 1000)).toEqual({ pages: [], overflowing: [] });
+  });
+});
+
+describe('paginateBlocks with footnotes', () => {
+  const block = (height: number, footnoteHeight = 0): BlockMetrics => ({ height, footnoteHeight });
+
+  it('gives a page less body room when its blocks carry notes', () => {
+    // Three 300px blocks fit 1000px on their own.
+    expect(paginateBlocks([block(300), block(300), block(300)], 1000).pages).toEqual([[0, 1, 2]]);
+
+    // Add 100px of notes to the first block plus 20px of area chrome and the
+    // third no longer fits: notes print on the page their marker landed on.
+    const withNotes = paginateBlocks([block(300, 100), block(300), block(300)], 1000, {
+      footnoteOverhead: 20,
+    });
+    expect(withNotes.pages).toEqual([[0, 1], [2]]);
+  });
+
+  it('charges the area chrome once per page, not once per note', () => {
+    const blocks = [block(300, 50), block(300, 50), block(300)];
+    // 900 body + 100 notes + 20 chrome = 1020 > 1000.
+    expect(paginateBlocks(blocks, 1000, { footnoteOverhead: 20 }).pages).toEqual([[0, 1], [2]]);
+    // Without the chrome it is exactly 1000 and all three stay together.
+    expect(paginateBlocks(blocks, 1000, { footnoteOverhead: 0 }).pages).toEqual([[0, 1, 2]]);
+  });
+
+  it('recomputes the notes budget for blocks that move to the next page', () => {
+    const blocks: BlockMetrics[] = [
+      { height: 300, footnoteHeight: 100 },
+      { height: 100, keepWithNext: true },
+      { height: 700 },
+    ];
+    const result = paginateBlocks(blocks, 1000, { footnoteOverhead: 20 });
+    // The heading travels with the block it introduces, and its page's budget
+    // is recomputed without the first block's notes.
+    expect(result.pages).toEqual([[0], [1, 2]]);
+  });
+
+  it('flags a block whose own notes make it taller than a page', () => {
+    const result = paginateBlocks([block(900, 200)], 1000, { footnoteOverhead: 20 });
+    expect(result.overflowing).toEqual([0]);
+  });
+
+  it('leaves documents without notes packing exactly as before', () => {
+    const blocks = [block(400), block(400), block(400)];
+    expect(paginateBlocks(blocks, 1000, { footnoteOverhead: 20 }).pages).toEqual([[0, 1], [2]]);
+  });
+});

package/src/app/lib/flow.ts

@@ -0,0 +1,136 @@
+import { Children, type ComponentType, Fragment, isValidElement, type ReactNode } from 'react';
+import type { DocEntry, FlowSection } from './sdk';
+
+export type { DocEntry, FlowSection };
+
+/**
+ * Flattens fragments so `flow(<>…</>)` yields one block per element the author
+ * wrote, not a single block containing the whole fragment.
+ */
+function toBlocks(node: ReactNode): ReactNode[] {
+  const out: ReactNode[] = [];
+  for (const child of Children.toArray(node)) {
+    if (!isValidElement(child)) continue;
+    if (child.type === Fragment) {
+      out.push(...toBlocks((child.props as { children?: ReactNode }).children));
+      continue;
+    }
+    out.push(child);
+  }
+  return out;
+}
+
+/**
+ * Wraps continuous content so the framework paginates it, instead of the author
+ * hand-splitting sections into fixed pages. Each direct child is one atomic
+ * block — a heading, a paragraph, a table — that never straddles a page break.
+ */
+export function flow(
+  children: ReactNode,
+  opts: { footer?: ComponentType; padding?: number } = {},
+): FlowSection {
+  return { __odFlow: true, blocks: toBlocks(children), ...opts };
+}
+
+export function isFlowSection(entry: DocEntry): entry is FlowSection {
+  return typeof entry === 'object' && entry !== null && (entry as FlowSection).__odFlow === true;
+}
+
+export type BlockMetrics = {
+  height: number;
+  /** Height this block's footnotes add to the foot of whatever page it lands on. */
+  footnoteHeight?: number;
+  /** A heading must not be the last block on a page. */
+  keepWithNext?: boolean;
+  /** A caption must not open a page without the figure it belongs to. */
+  keepWithPrevious?: boolean;
+  /** Always start a new page before this block. */
+  breakBefore?: boolean;
+};
+
+export type PaginationResult = {
+  /** Block indices per page, in order. */
+  pages: number[][];
+  /** Blocks taller than one page — they stay whole and overflow. */
+  overflowing: number[];
+};
+
+export type PaginateOptions = {
+  /** Rule and padding a page's footnote area costs before its first note. */
+  footnoteOverhead?: number;
+};
+
+/**
+ * Greedy top-to-bottom packing: fill a page until the next block would cross
+ * the bottom edge, then push that block — plus anything glued to it — onto the
+ * next page. Blocks are atomic; nothing is split mid-block.
+ *
+ * Footnotes are packed from the same budget: a block that carries notes brings
+ * their height with it, because those notes print at the foot of whichever page
+ * the block lands on.
+ */
+export function paginateBlocks(
+  blocks: BlockMetrics[],
+  available: number,
+  opts: PaginateOptions = {},
+): PaginationResult {
+  const overhead = opts.footnoteOverhead ?? 0;
+  const pages: number[][] = [];
+  const overflowing: number[] = [];
+  let current: number[] = [];
+  let used = 0;
+  let notes = 0;
+
+  const heightOf = (indices: number[]) =>
+    indices.reduce((sum, index) => sum + (blocks[index]?.height ?? 0), 0);
+  const notesOf = (indices: number[]) =>
+    indices.reduce((sum, index) => sum + (blocks[index]?.footnoteHeight ?? 0), 0);
+  /** A page with no notes pays nothing; the first note also pays for the rule. */
+  const reserve = (total: number) => (total > 0 ? total + overhead : 0);
+
+  const closePage = () => {
+    if (current.length === 0) return;
+    pages.push(current);
+    current = [];
+    used = 0;
+    notes = 0;
+  };
+
+  blocks.forEach((block, index) => {
+    const own = block.footnoteHeight ?? 0;
+    if (block.height + reserve(own) > available) overflowing.push(index);
+
+    if (block.breakBefore) closePage();
+
+    if (current.length > 0 && used + block.height + reserve(notes + own) > available) {
+      // Everything glued to this block travels with it: trailing headings
+      // (keep-with-next) and, when this block is a caption, its figure.
+      let splitAt = current.length;
+      while (splitAt > 0 && blocks[current[splitAt - 1]]?.keepWithNext) splitAt--;
+      if (block.keepWithPrevious && splitAt === current.length) splitAt--;
+
+      if (splitAt > 0 && splitAt < current.length) {
+        const moved = current.slice(splitAt);
+        pages.push(current.slice(0, splitAt));
+        current = moved;
+        used = heightOf(moved);
+        notes = notesOf(moved);
+      } else {
+        closePage();
+      }
+    }
+
+    current.push(index);
+    used += block.height;
+    notes += own;
+  });
+
+  closePage();
+  return { pages, overflowing };
+}
+
+/** Blocks of the first flow section, for thumbnails that skip measurement. */
+export function firstFlowBlocks(entries: DocEntry[], limit = 12): ReactNode[] {
+  const first = entries.find(isFlowSection);
+  return first ? first.blocks.slice(0, limit) : [];
+}

package/src/app/lib/folders.ts

@@ -0,0 +1,192 @@
+import buildManifest from 'virtual:mosage/folders';
+import { useCallback, useEffect, useState } from 'react';
+import type { Folder, FolderIcon, FoldersManifest } from './sdk';
+
+const EMPTY: FoldersManifest = { folders: [], assignments: {} };
+
+async function getManifest(): Promise<FoldersManifest> {
+  // In dev the manifest is mutable, so read it live from the API — the sidebar
+  // must reflect edits immediately. A static build has no server, so it falls
+  // back to the snapshot the virtual module baked in from docs/.folders.json.
+  if (import.meta.env.DEV) {
+    const res = await fetch('/__folders');
+    if (!res.ok) throw new Error(`GET /__folders ${res.status}`);
+    const raw = (await res.json()) as Partial<FoldersManifest>;
+    return { folders: raw.folders ?? [], assignments: raw.assignments ?? {} };
+  }
+  return { folders: buildManifest.folders ?? [], assignments: buildManifest.assignments ?? {} };
+}
+
+async function expectOk(res: Response, label: string): Promise<void> {
+  if (res.ok) return;
+  let detail = `${res.status}`;
+  try {
+    const body = (await res.json()) as { error?: string };
+    if (body.error) detail = body.error;
+  } catch {}
+  throw new Error(`${label}: ${detail}`);
+}
+
+const jsonInit = (method: string, body: unknown): RequestInit => ({
+  method,
+  headers: { 'content-type': 'application/json' },
+  body: JSON.stringify(body),
+});
+
+export type UseFoldersResult = {
+  manifest: FoldersManifest;
+  loading: boolean;
+  create: (name: string, icon: FolderIcon) => Promise<Folder>;
+  update: (id: string, patch: { name?: string; icon?: FolderIcon }) => Promise<void>;
+  remove: (id: string) => Promise<void>;
+  reorder: (ids: string[]) => Promise<void>;
+  assign: (docId: string, folderId: string | null) => Promise<void>;
+  renameDoc: (docId: string, title: string) => Promise<void>;
+  duplicateDoc: (docId: string, newId?: string) => Promise<string>;
+  deleteDoc: (docId: string) => Promise<void>;
+  refresh: () => Promise<void>;
+};
+
+export function useFolders(): UseFoldersResult {
+  const [manifest, setManifest] = useState<FoldersManifest>(EMPTY);
+  const [loading, setLoading] = useState(true);
+
+  const refresh = useCallback(async () => {
+    setManifest(await getManifest());
+  }, []);
+
+  useEffect(() => {
+    let cancelled = false;
+    getManifest()
+      .then((m) => {
+        if (cancelled) return;
+        setManifest(m);
+        setLoading(false);
+      })
+      .catch(() => {
+        if (!cancelled) setLoading(false);
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, []);
+
+  useEffect(() => {
+    if (!import.meta.hot) return;
+    const handler = () => {
+      refresh().catch(() => {});
+    };
+    import.meta.hot.on('mosage:files-changed', handler);
+    return () => {
+      import.meta.hot?.off('mosage:files-changed', handler);
+    };
+  }, [refresh]);
+
+  const create = useCallback(
+    async (name: string, icon: FolderIcon) => {
+      const res = await fetch('/__folders', jsonInit('POST', { name, icon }));
+      await expectOk(res, 'Create folder failed');
+      const folder = (await res.json()) as Folder;
+      await refresh();
+      return folder;
+    },
+    [refresh],
+  );
+
+  const update = useCallback(
+    async (id: string, patch: { name?: string; icon?: FolderIcon }) => {
+      await expectOk(
+        await fetch(`/__folders/${id}`, jsonInit('PATCH', patch)),
+        'Update folder failed',
+      );
+      await refresh();
+    },
+    [refresh],
+  );
+
+  const remove = useCallback(
+    async (id: string) => {
+      await expectOk(await fetch(`/__folders/${id}`, { method: 'DELETE' }), 'Delete folder failed');
+      await refresh();
+    },
+    [refresh],
+  );
+
+  const reorder = useCallback(
+    async (ids: string[]) => {
+      const prev = manifest;
+      const byId = new Map(prev.folders.map((f) => [f.id, f]));
+      const next = ids.map((id) => byId.get(id)).filter((f): f is Folder => Boolean(f));
+      if (next.length !== prev.folders.length) return;
+      setManifest({ ...prev, folders: next });
+      try {
+        await expectOk(
+          await fetch('/__folders/reorder', jsonInit('PUT', { ids })),
+          'Reorder failed',
+        );
+      } catch (err) {
+        setManifest(prev);
+        throw err;
+      }
+    },
+    [manifest],
+  );
+
+  const assign = useCallback(
+    async (docId: string, folderId: string | null) => {
+      await expectOk(
+        await fetch('/__folders/assign', jsonInit('PUT', { docId, folderId })),
+        'Move failed',
+      );
+      await refresh();
+    },
+    [refresh],
+  );
+
+  const renameDoc = useCallback(
+    async (docId: string, title: string) => {
+      await expectOk(
+        await fetch(`/__docs/${docId}`, jsonInit('PATCH', { title })),
+        'Rename failed',
+      );
+      await refresh();
+    },
+    [refresh],
+  );
+
+  const duplicateDoc = useCallback(
+    async (docId: string, newId?: string) => {
+      const init: RequestInit =
+        newId === undefined ? { method: 'POST' } : jsonInit('POST', { newId });
+      const res = await fetch(`/__docs/${docId}/duplicate`, init);
+      await expectOk(res, 'Duplicate failed');
+      const body = (await res.json()) as { docId?: unknown };
+      await refresh();
+      if (typeof body.docId !== 'string') throw new Error('duplicate response missing docId');
+      return body.docId;
+    },
+    [refresh],
+  );
+
+  const deleteDoc = useCallback(
+    async (docId: string) => {
+      await expectOk(await fetch(`/__docs/${docId}`, { method: 'DELETE' }), 'Delete failed');
+      await refresh();
+    },
+    [refresh],
+  );
+
+  return {
+    manifest,
+    loading,
+    create,
+    update,
+    remove,
+    reorder,
+    assign,
+    renameDoc,
+    duplicateDoc,
+    deleteDoc,
+    refresh,
+  };
+}

package/src/app/lib/footnotes.test.tsx

@@ -0,0 +1,102 @@
+import { createElement, isValidElement, type ReactNode } from 'react';
+import { describe, expect, it } from 'vitest';
+import { Footnote } from '../components/footnote';
+import { extractBlockFootnotes, extractSectionFootnotes, notesForPage } from './footnotes';
+
+function childrenOf(node: ReactNode): ReactNode {
+  return isValidElement(node) ? (node.props as { children?: ReactNode }).children : undefined;
+}
+
+describe('extractBlockFootnotes', () => {
+  it('lifts a note out and leaves a marker in its place', () => {
+    const block = (
+      <p>
+        A claim
+        <Footnote>Source: Q3 billing export.</Footnote>
+        and the rest.
+      </p>
+    );
+
+    const { node, notes } = extractBlockFootnotes(block, 'fn-0-0');
+    expect(notes).toHaveLength(1);
+    expect(notes[0].id).toBe('fn-0-0-1');
+    expect(notes[0].content).toBe('Source: Q3 billing export.');
+
+    const rendered = JSON.stringify(node, (key, value) => (key === 'type' ? undefined : value));
+    expect(rendered).not.toContain('Source: Q3 billing export.');
+    expect(node).not.toBe(block);
+  });
+
+  it('honours an author id so a Ref can point at the note', () => {
+    const { notes } = extractBlockFootnotes(
+      <p>
+        x<Footnote id="billing">note</Footnote>
+      </p>,
+      'fn-0-0',
+    );
+    expect(notes[0].id).toBe('billing');
+  });
+
+  it('finds notes nested several elements deep', () => {
+    const { notes } = extractBlockFootnotes(
+      <div>
+        <ul>
+          <li>
+            one<Footnote>first</Footnote>
+          </li>
+          <li>
+            two<Footnote>second</Footnote>
+          </li>
+        </ul>
+      </div>,
+      'fn-1-2',
+    );
+    expect(notes.map((note) => note.content)).toEqual(['first', 'second']);
+    expect(notes.map((note) => note.id)).toEqual(['fn-1-2-1', 'fn-1-2-2']);
+  });
+
+  it('returns the block untouched when it has no footnotes', () => {
+    const block = <p>Nothing to lift.</p>;
+    const { node, notes } = extractBlockFootnotes(block, 'fn-0-0');
+    expect(node).toBe(block);
+    expect(notes).toEqual([]);
+  });
+
+  it('leaves a render-prop child alone rather than walking into a function', () => {
+    const block = createElement('div', null, (() => null) as unknown as ReactNode);
+    expect(extractBlockFootnotes(block, 'fn-0-0').node).toBe(block);
+  });
+
+  it('keeps surrounding text intact', () => {
+    const { node } = extractBlockFootnotes(
+      <p>
+        before<Footnote>note</Footnote>after
+      </p>,
+      'fn-0-0',
+    );
+    const children = childrenOf(node) as ReactNode[];
+    expect(children[0]).toBe('before');
+    expect(children[2]).toBe('after');
+  });
+});
+
+describe('extractSectionFootnotes', () => {
+  it('keeps notes index-aligned with their blocks', () => {
+    const prepared = extractSectionFootnotes(
+      [
+        <p key="a">plain</p>,
+        <p key="b">
+          x<Footnote>note</Footnote>
+        </p>,
+      ],
+      0,
+    );
+    expect(prepared.notesByBlock[0]).toEqual([]);
+    expect(prepared.notesByBlock[1]).toHaveLength(1);
+  });
+
+  it('collects only the notes belonging to a page', () => {
+    const notesByBlock = [[{ id: 'a', content: 'A' }], [], [{ id: 'c', content: 'C' }]];
+    expect(notesForPage(notesByBlock, [1, 2]).map((note) => note.id)).toEqual(['c']);
+  });
+});

package/src/app/lib/footnotes.ts

@@ -0,0 +1,94 @@
+import { Children, cloneElement, createElement, isValidElement, type ReactNode } from 'react';
+import { FOOTNOTE_MARKER_FLAG, FootnoteMarker } from '../components/footnote';
+
+export type ExtractedNote = { id: string; content: ReactNode };
+
+export type ExtractedBlock = {
+  /** The block with each `<Footnote>` swapped for its marker. */
+  node: ReactNode;
+  notes: ExtractedNote[];
+};
+
+/** Identified by a flag on the function, not by identity — core exists twice at runtime. */
+function isFootnoteElement(node: ReactNode): boolean {
+  if (!isValidElement(node)) return false;
+  const type = node.type as unknown;
+  if (typeof type !== 'function') return false;
+  return (type as unknown as Record<string, unknown>)[FOOTNOTE_MARKER_FLAG] === true;
+}
+
+/**
+ * Lifts the notes out of a block and leaves the markers behind.
+ *
+ * A footnote occupies space at the foot of its page, which is space the packer
+ * cannot give to body content — so the notes have to be known *before*
+ * pagination, not discovered while rendering it. Walking the block's element
+ * tree is what makes that possible, and the trade is that a `<Footnote>` has to
+ * appear in the JSX you hand to `flow()`: one hidden inside a component's own
+ * body is invisible here and stays inline.
+ */
+export function extractBlockFootnotes(node: ReactNode, idPrefix: string): ExtractedBlock {
+  const notes: ExtractedNote[] = [];
+
+  const walkChildren = (children: ReactNode): ReactNode => {
+    if (Array.isArray(children)) {
+      let changed = false;
+      const mapped = Children.map(children, (child) => {
+        const next = walk(child);
+        if (next !== child) changed = true;
+        return next;
+      });
+      return changed ? mapped : children;
+    }
+    return walk(children);
+  };
+
+  const walk = (current: ReactNode): ReactNode => {
+    if (!isValidElement(current)) return current;
+
+    if (isFootnoteElement(current)) {
+      const props = current.props as { id?: string; children?: ReactNode };
+      const id = props.id ?? `${idPrefix}-${notes.length + 1}`;
+      notes.push({ id, content: props.children });
+      return createElement(FootnoteMarker, { key: current.key ?? id, id });
+    }
+
+    const props = current.props as { children?: ReactNode };
+    // A render-prop child is a function, not a tree — there is nothing to walk.
+    if (props.children === undefined || typeof props.children === 'function') return current;
+
+    const next = walkChildren(props.children);
+    return next === props.children ? current : cloneElement(current, undefined, next);
+  };
+
+  const walked = walk(node);
+  return { node: walked, notes };
+}
+
+export type PreparedSection = {
+  blocks: ReactNode[];
+  /** Notes per block, index-aligned with `blocks`. */
+  notesByBlock: ExtractedNote[][];
+};
+
+export function extractSectionFootnotes(
+  blocks: ReactNode[],
+  sectionIndex: number,
+): PreparedSection {
+  const out: PreparedSection = { blocks: [], notesByBlock: [] };
+  blocks.forEach((block, blockIndex) => {
+    const extracted = extractBlockFootnotes(block, `fn-${sectionIndex}-${blockIndex}`);
+    out.blocks.push(extracted.node);
+    out.notesByBlock.push(extracted.notes);
+  });
+  return out;
+}
+
+export function notesForPage(
+  notesByBlock: ExtractedNote[][],
+  blockIndices: number[],
+): ExtractedNote[] {
+  const out: ExtractedNote[] = [];
+  for (const index of blockIndices) out.push(...(notesByBlock[index] ?? []));
+  return out;
+}