mosage 0.1.0 → 0.8.0

package/skills/doc-authoring/references/long-form.md

@@ -0,0 +1,131 @@
+# Footnotes, numbering, cross-references, and data
+
+Everything here shares one mechanism: the framework **scans the rendered pages**
+and fills in what only the finished layout knows. That is why none of these
+numbers are written by hand, and why they are all correct after a page is
+inserted in the middle of the document.
+
+The trade is the same one `<TableOfContents>` makes: values are empty on the
+first render pass and filled on the next. Both exporters scan their own copy
+before serializing, so a PDF never contains a blank number.
+
+## Footnotes
+
+```tsx
+import { Footnote } from 'mosage';
+
+<p style={p}>
+  Spend grew 8% quarter over quarter
+  <Footnote>Billing export, 2026-10-02. Excludes the edge tier.</Footnote>, driven
+  almost entirely by one service.
+</p>
+```
+
+- The marker is numbered by position in the document — across fixed pages and
+  flow sections alike. Insert a note anywhere and everything after it renumbers.
+- Inside a `flow()` section the note prints at the **foot of whatever page its
+  marker landed on**, and the space it takes is subtracted from that page's
+  budget before the packer decides where to break. You do not reserve anything.
+- Give a note an `id` when something needs to point at it: `<Footnote id="src-1">`.
+
+**On a fixed page, add `<Footnotes />` where the notes should print.** A fixed
+page is your layout, so the framework does not inject anything into it:
+
+```tsx
+const Cover: DocPage = () => (
+  <div style={page}>
+    <p>Q3 2026<Footnote>Covers the platform tier only.</Footnote></p>
+    <Footnotes />
+  </div>
+);
+```
+
+**Put `<Footnote>` in the JSX you hand to `flow()`.** The notes are lifted out of
+the blocks before measurement, by walking the element tree you wrote. One hidden
+inside a helper component's own body is invisible to that walk and will render
+inline instead of at the foot of the page.
+
+## Figures and tables
+
+```tsx
+import { Figure } from 'mosage';
+
+<Figure id="topology" caption="Service topology, Q3 2026">
+  <img src={diagram} alt="Service topology" style={{ width: '100%', display: 'block' }} />
+</Figure>
+```
+
+- `kind="table"` numbers it with the tables instead, and captions above rather
+  than below.
+- Content and caption are **one block**, so a flow section never separates them.
+- `caption` may carry markup; pass `captionText` as well when it does, so the
+  list of figures has plain text to print.
+
+`<ListOfFigures />` and `<ListOfTables />` build the lists, exactly like
+`<TableOfContents />` builds the contents.
+
+## Cross-references
+
+```tsx
+import { Ref } from 'mosage';
+
+<p style={p}>The shape in <Ref to="topology" /> is what the table hides.</p>
+```
+
+Renders `Figure 3`, and appends the page — `Figure 3 (p. 12)` — only when the
+target sits on another sheet. Force it either way with `showPage`.
+
+**Never write "see Figure 3 on page 12" by hand.** Both numbers move.
+
+A reference to an id nothing declares renders `[?the-id]` on the page and is
+reported by `mosage check` as an error. That is deliberate: a silent blank is
+worse than a visible hole.
+
+## What things are called
+
+Numbering is structural; the words around it are the document's own business.
+
+```tsx
+export const meta: DocMeta = {
+  title: '平台可靠度回顧',
+  labels: { figure: '圖', table: '表', onPage: '（第 {page} 頁）' },
+};
+```
+
+`footnotes` adds a heading above a page's notes; leave it empty for none.
+
+## Data
+
+```tsx
+import { DataTable } from 'mosage';
+import services from './data/services.csv';
+
+<DataTable
+  id="service-table"
+  caption="Platform tier, Q3 2026"
+  rows={services}
+  columns={[
+    { key: 'service', label: 'Service' },
+    { key: 'requests', label: 'Requests', format: 'integer' },
+    { key: 'error_rate', label: 'Errors', format: 'percent' },
+  ]}
+/>
+```
+
+- `.csv` and `.tsv` under the document resolve to an array of objects **at build
+  time**. Quoted fields, embedded commas and newlines, and CRLF all work; a
+  numeric cell becomes a number, an empty cell becomes `null`.
+- Data is never fetched at render time, and must not be: the packer measures the
+  real DOM to decide where pages break, so anything that arrives a tick later
+  arrives after the layout is decided.
+- Columns default to the keys of the first row. A column whose values are all
+  numbers aligns right and gets `tabular-nums` without being told.
+- `format`: `'integer'`, `'number'`, `'percent'`, `'text'`, or your own
+  `(value, row) => ReactNode`.
+- `caption` numbers the table and prints the caption above it; without one you
+  get a plain table.
+- `limit` prints the first N rows and says how many were left out — never
+  truncate a table silently.
+
+**Retyping numbers into JSX is the thing this replaces.** If the user has the
+data in a file, import the file.

package/skills/doc-authoring/references/pagination.md

@@ -0,0 +1,118 @@
+# Pagination — flow sections and the vertical budget
+
+A document's default export is a list of **entries**. There are two kinds, and they mix freely:
+
+| Entry | What it is | Who decides the page break |
+| --- | --- | --- |
+| `DocPage` (a component) | Exactly one sheet | You |
+| `flow(<>…</>)` | Continuous content | The framework, by measuring |
+
+**Default to `flow()` for body content.** Use fixed pages for the cover, a contents page, a section divider — anything whose layout is the point. Hand-splitting prose into fixed pages is how you end up with eleven pages that are each 60% full.
+
+## Flow sections
+
+```tsx
+import { flow, type DocEntry } from 'mosage';
+
+const Body = flow(
+  <>
+    <h1 style={h1}>1. 概觀</h1>
+    <p style={p}>…</p>
+    <Table>…</Table>
+    <p style={caption} data-od-keep-with-previous>表 1 — …</p>
+    <h2 style={h2}>1.1 細節</h2>
+    <p style={p}>…</p>
+  </>,
+  { footer: Footer },
+);
+
+export default [Cover, Contents, Body] satisfies DocEntry[];
+```
+
+- **Each direct child of the fragment is one block.** Blocks are atomic: a block never splits across a page, so a table either fits whole or moves to the next page.
+- The framework owns the page shell for flow pages — margin, background, and base typography come from the `design` const. Your blocks keep their own styles. `flow(node, { padding })` overrides the margin for that section.
+- `footer` is a component rendered on **every** page the section expands into. `useDocPageNumber()` works inside it, so a running footer needs no extra wiring.
+- Blocks are measured in the real DOM at the real page width after fonts settle, then packed greedily. Change a paragraph and the pagination re-runs on hot reload.
+
+### Keep rules
+
+| Rule | How | Default |
+| --- | --- | --- |
+| Heading never last on a page | `data-od-keep-with-next` | **on** for `h1`–`h4` |
+| Caption stays with its figure | `data-od-keep-with-previous` on the caption | off |
+| Force a new page here | `data-od-break-before` | off |
+
+Set `data-od-keep-with-next="false"` on a heading if you deliberately want it to end a page.
+
+### What flow does not do
+
+- **It never splits a block.** A 40-row table taller than one page stays whole and overflows — split it yourself into two tables with a repeated header.
+- **It does not balance pages.** Content fills top-down; the last page can be short.
+- **It does not reorder anything.** Blocks keep the order you wrote them in.
+
+## Fixed pages and the vertical budget
+
+Everything below applies to `DocPage` components — the pages you lay out yourself.
+
+```
+usable_height = page_height − 2 × margin
+```
+
+| Page | Margin | Usable height |
+| --- | --- | --- |
+| A4 portrait (1123px) | 76 | **971px** |
+| A4 portrait | 96 | 931px |
+| A4 landscape (794px) | 76 | 642px |
+| B4 portrait (1376px) | 76 | 1224px |
+| A3 portrait (1587px) | 76 | 1435px |
+
+A running footer sits inside the margin band, so it costs nothing from the budget — but leave **24px of clearance** above it, i.e. treat the budget as ~947px on A4 when a footer is present.
+
+### Estimating how many lines a paragraph takes
+
+```
+chars_per_line ≈ text_block_width / (font_size × 0.5)
+lines          = ceil(characters / chars_per_line)
+height         = lines × font_size × line_height
+```
+
+The `0.5` is the average glyph-width ratio for a humanist sans at body sizes. Use `0.52` for serif faces, `0.6` for monospace, and **`1.0` for CJK** (one character per em).
+
+On A4 with 76px margins (text block 642px) at 14px body:
+
+- Latin: `642 / (14 × 0.5)` ≈ **92 characters per line**
+- CJK: `642 / 14` ≈ **45 characters per line**
+
+A 400-character English paragraph → `ceil(400/92)` = 5 lines → `5 × 14 × 1.55` = **109px**.
+
+### Worked example — A4 content page, 76px margins, footer present (budget 947px)
+
+| Element | Height |
+| --- | --- |
+| H1 28px × 1.2 | 34px |
+| Gap | 20px |
+| Intro paragraph, 380 chars → 5 lines × 14 × 1.55 | 109px |
+| Gap | 14px |
+| H2 20px × 1.25 | 25px |
+| Gap | 12px |
+| Body paragraph, 620 chars → 7 lines | 152px |
+| Gap | 14px |
+| Table: header 28px + 6 rows × 26px | 184px |
+| Gap | 14px |
+| Caption 10px × 1.4 | 14px |
+| Gap | 24px |
+| Body paragraph, 520 chars → 6 lines | 130px |
+| **Total** | **746px ✅ fits in 947** |
+
+### Where to split a fixed page
+
+1. **At a section boundary.** A new H1 starts a new page.
+2. **Before a subsection heading.** Never leave an H2 as the last element on a page.
+3. **Between a table/figure and its surrounding prose.** Keep a caption with its table.
+4. **Mid-prose, at a paragraph boundary.** Never split a paragraph across two page components.
+
+Rules: give every page the same top edge; if a page is more than ~85% full, move its last block; if you find yourself shrinking type or margins to fit, add a page instead. **Or convert the section to `flow()` and stop doing this arithmetic.**
+
+## Landscape pages
+
+`meta.orientation` applies to the **whole document** — there is no per-page orientation. If one wide table needs landscape, either rotate it inside a portrait page (`transform: rotate(-90deg)` on a sized wrapper) or make the whole document landscape. Mixing is not supported.

package/skills/doc-authoring/references/tables-and-charts.md

@@ -0,0 +1,161 @@
+# Tables, stats, and charts
+
+Reports are mostly evidence. This file covers the three shapes evidence takes on a page.
+
+## Tables
+
+```tsx
+const Th = ({ children, align = 'left' }: { children: ReactNode; align?: 'left' | 'right' }) => (
+  <th
+    style={{
+      textAlign: align,
+      fontFamily: 'var(--od-font-heading)',
+      fontSize: 11,
+      fontWeight: 600,
+      letterSpacing: '0.04em',
+      textTransform: 'uppercase',
+      color: 'var(--od-muted)',
+      borderBottom: '1px solid var(--od-rule)',
+      padding: '0 8px 6px',
+    }}
+  >
+    {children}
+  </th>
+);
+
+const Td = ({ children, align = 'left' }: { children: ReactNode; align?: 'left' | 'right' }) => (
+  <td
+    style={{
+      textAlign: align,
+      fontSize: 12,
+      padding: '7px 8px',
+      borderBottom: '1px solid var(--od-rule)',
+      fontVariantNumeric: align === 'right' ? 'tabular-nums' : undefined,
+    }}
+  >
+    {children}
+  </td>
+);
+
+<table style={{ width: '100%', borderCollapse: 'collapse', tableLayout: 'fixed' }}>
+  <thead>
+    <tr>
+      <Th>Service</Th>
+      <Th align="right">Requests</Th>
+      <Th align="right">p99</Th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <Td>checkout-api</Td>
+      <Td align="right">18,402,111</Td>
+      <Td align="right">412 ms</Td>
+    </tr>
+  </tbody>
+</table>
+```
+
+Rules:
+
+- `borderCollapse: 'collapse'` + `tableLayout: 'fixed'`, always. Auto layout produces columns that shift when the copy changes.
+- Numbers right-aligned with `fontVariantNumeric: 'tabular-nums'`. Text left-aligned. Never center either.
+- Horizontal rules only. Vertical borders and zebra striping both add noise that print exaggerates.
+- Cell font 11–12px, row padding 6–8px → a row costs ~26–30px. Budget accordingly (`references/pagination.md`).
+- Portrait A4 tops out around **7 columns**; past that, either drop columns or transpose the table.
+- One unit per column, declared in the header (`p99 (ms)`), not repeated in every cell.
+- A caption goes **below** the table at `--od-size-caption`, muted, and must stay on the same page as the table.
+
+### Long tables
+
+Split by row groups across pages. Repeat the full header row and mark the continuation in the caption ("Table 3 (continued)"). Never let a header land on one page and its rows on the next.
+
+## Stat rows
+
+A row of 3–4 headline numbers under a section title. Define one component, instantiate it per stat — do **not** `map` over a data array (an explicit instance per stat keeps each number editable on its own):
+
+```tsx
+const Stat = ({ value, label, note }: { value: string; label: string; note?: string }) => (
+  <div style={{ flex: 1 }}>
+    <div style={{ fontFamily: 'var(--od-font-heading)', fontSize: 30, fontWeight: 650, lineHeight: 1.1 }}>
+      {value}
+    </div>
+    <div style={{ fontSize: 12, marginTop: 4 }}>{label}</div>
+    {note && <div style={{ fontSize: 10, color: 'var(--od-muted)', marginTop: 2 }}>{note}</div>}
+  </div>
+);
+
+<div style={{ display: 'flex', gap: 24, borderTop: '1px solid var(--od-rule)', paddingTop: 14 }}>
+  <Stat value="99.94%" label="Availability" note="target 99.9%" />
+  <Stat value="412 ms" label="p99 latency" note="−18% QoQ" />
+  <Stat value="$41.2k" label="Monthly spend" note="+6% QoQ" />
+</div>
+```
+
+Every stat needs a comparison (target, prior period) — a number with nothing to compare against tells the reader nothing.
+
+## Charts
+
+No chart library is available, and none is needed. Write **inline SVG** sized in absolute px:
+
+```tsx
+const Bars = () => {
+  const data = [
+    { label: 'Jan', value: 38 },
+    { label: 'Feb', value: 52 },
+    { label: 'Mar', value: 47 },
+  ];
+  const w = 642;
+  const h = 180;
+  const max = 60;
+  const gap = 12;
+  const barW = (w - gap * (data.length - 1)) / data.length;
+
+  return (
+    <svg width={w} height={h} role="img" aria-label="Monthly incidents">
+      <title>Monthly incidents</title>
+      {data.map((d, i) => {
+        const barH = (d.value / max) * (h - 24);
+        return (
+          <g key={d.label}>
+            <rect x={i * (barW + gap)} y={h - 24 - barH} width={barW} height={barH} fill="var(--od-accent)" rx={2} />
+            <text x={i * (barW + gap) + barW / 2} y={h - 8} textAnchor="middle" fontSize={10} fill="var(--od-muted)">
+              {d.label}
+            </text>
+          </g>
+        );
+      })}
+    </svg>
+  );
+};
+```
+
+Rules:
+
+- Size the SVG to the text block width (A4 @ 76px margins → 642) so it aligns with the prose.
+- Vector only. SVG stays sharp in the PDF; a rasterized chart does not.
+- Label directly on the chart — a separate legend forces the reader to look twice. If you must have a legend, put it on one line above the plot.
+- Start bar axes at zero. Truncated axes in a report are a credibility problem, not a style choice.
+- Two decimals maximum, units in the axis label or the caption.
+- `data.map` inside one SVG is fine — the "explicit instance" rule is about repeated *page elements*, not path geometry.
+- If the chart needs data the user has to supply, don't fabricate plausible numbers. Use `<ImagePlaceholder hint="Bar chart: monthly incidents, Jan–Sep, from the ops dashboard" height={180} />` and flag it at hand-off.
+
+## Callouts
+
+One box style, used sparingly (at most one or two per page):
+
+```tsx
+<div
+  style={{
+    borderLeft: '3px solid var(--od-accent)',
+    background: '#f8fafc',
+    padding: '12px 14px',
+    borderRadius: 'var(--od-radius)',
+    fontSize: 12,
+  }}
+>
+  <strong style={{ display: 'block', marginBottom: 4 }}>Recommendation</strong>
+  Move the checkout queue to its own cluster before the November peak.
+</div>
+```
+
+Reserve callouts for recommendations, risks, and definitions. A page where everything is boxed emphasizes nothing.

package/src/app/app.tsx

@@ -0,0 +1,42 @@
+import config from 'virtual:mosage/config';
+import { BrowserRouter, Link, Route, Routes } from 'react-router-dom';
+import { AssetsPage } from './routes/assets';
+import { Doc } from './routes/doc';
+import { Home } from './routes/home';
+import { HomeShell } from './routes/home-shell';
+import { ThemeDetailPage, ThemesGalleryPage } from './routes/themes';
+
+export function App() {
+  return (
+    <BrowserRouter basename={import.meta.env.BASE_URL}>
+      <Routes>
+        {config.build.showDocBrowser ? (
+          <Route element={<HomeShell />}>
+            <Route path="/" element={<Home />} />
+            <Route path="/themes" element={<ThemesGalleryPage />} />
+            <Route path="/themes/:themeId" element={<ThemeDetailPage />} />
+            <Route path="/assets" element={<AssetsPage />} />
+          </Route>
+        ) : (
+          <Route path="/" element={<NotFound />} />
+        )}
+        <Route path="/d/:docId" element={<Doc />} />
+        <Route path="*" element={<NotFound />} />
+      </Routes>
+    </BrowserRouter>
+  );
+}
+
+function NotFound() {
+  return (
+    <div className="grid h-screen place-items-center bg-background px-6 text-center text-foreground">
+      <div>
+        <p className="font-mono text-muted-foreground text-xs uppercase tracking-widest">404</p>
+        <h1 className="mt-2 font-medium text-xl tracking-tight">Nothing here</h1>
+        <Link to="/" className="mt-4 inline-block text-muted-foreground text-xs underline">
+          Back to documents
+        </Link>
+      </div>
+    </div>
+  );
+}

package/src/app/components/data-table.tsx

@@ -0,0 +1,196 @@
+import type { CSSProperties, ReactNode } from 'react';
+import { Figure } from './numbering';
+
+export type DataAlign = 'left' | 'center' | 'right';
+
+export type DataFormat =
+  | 'text'
+  | 'number'
+  | 'integer'
+  | 'percent'
+  | ((value: unknown, row: Record<string, unknown>) => ReactNode);
+
+export type DataColumn = {
+  key: string;
+  label?: ReactNode;
+  align?: DataAlign;
+  format?: DataFormat;
+  /** Column width. A number is px; `tableLayout: fixed` means these are honoured. */
+  width?: number | string;
+};
+
+export type DataTableProps = {
+  /** Rows as parsed from a `.csv`/`.tsv` import, or any array of objects. */
+  rows: Array<Record<string, unknown>>;
+  /** Columns to print, in order. Derived from the first row when omitted. */
+  columns?: Array<DataColumn | string>;
+  /** Numbers the table and prints the caption above it. */
+  caption?: ReactNode;
+  /** Stable id for `<Ref to>`. Only meaningful alongside `caption`. */
+  id?: string;
+  /** Print at most this many rows, with a note about what was left out. */
+  limit?: number;
+  /** Tighter rows, for a dense appendix table. */
+  compact?: boolean;
+  /** What an empty cell prints as. Defaults to an em dash. */
+  emptyValue?: ReactNode;
+  style?: CSSProperties;
+  className?: string;
+};
+
+function normalizeColumn(column: DataColumn | string): DataColumn {
+  return typeof column === 'string' ? { key: column } : column;
+}
+
+function isNumber(value: unknown): value is number {
+  return typeof value === 'number' && Number.isFinite(value);
+}
+
+/** A column of numbers aligns right; anything mixed stays left. */
+function inferAlign(rows: Array<Record<string, unknown>>, key: string): DataAlign {
+  let seen = 0;
+  for (const row of rows) {
+    const value = row[key];
+    if (value === null || value === undefined || value === '') continue;
+    if (!isNumber(value)) return 'left';
+    seen++;
+  }
+  return seen > 0 ? 'right' : 'left';
+}
+
+function formatValue(
+  value: unknown,
+  format: DataFormat | undefined,
+  row: Record<string, unknown>,
+  emptyValue: ReactNode,
+): ReactNode {
+  if (typeof format === 'function') return format(value, row);
+  if (value === null || value === undefined || value === '') return emptyValue;
+
+  if (isNumber(value)) {
+    if (format === 'integer') return Math.round(value).toLocaleString();
+    if (format === 'percent')
+      return `${(value * 100).toLocaleString(undefined, { maximumFractionDigits: 1 })}%`;
+    if (format === 'text') return String(value);
+    // Grouping separators are what make a column of figures readable; the
+    // fraction digits follow the data rather than padding every integer.
+    return value.toLocaleString(undefined, { maximumFractionDigits: 2 });
+  }
+
+  return String(value);
+}
+
+/**
+ * A print-shaped table from data, so the numbers in a report come from a file
+ * instead of being retyped into JSX. Alignment and grouping follow the column's
+ * contents, which is the part people get wrong by hand.
+ */
+export function DataTable({
+  rows,
+  columns,
+  caption,
+  id,
+  limit,
+  compact = false,
+  emptyValue = '—',
+  style,
+  className,
+}: DataTableProps) {
+  const resolved: DataColumn[] = (columns ?? Object.keys(rows[0] ?? {})).map(normalizeColumn);
+
+  const shown = limit !== undefined ? rows.slice(0, limit) : rows;
+  const hidden = rows.length - shown.length;
+
+  const cellPadding = compact ? '4px 8px' : '7px 8px';
+
+  const table = (
+    <table
+      className={className}
+      style={{
+        width: '100%',
+        borderCollapse: 'collapse',
+        tableLayout: 'fixed',
+        margin: 0,
+        ...style,
+      }}
+    >
+      <thead>
+        <tr>
+          {resolved.map((column) => {
+            const align = column.align ?? inferAlign(rows, column.key);
+            return (
+              <th
+                key={column.key}
+                style={{
+                  textAlign: align,
+                  width: column.width,
+                  fontFamily: 'var(--od-font-heading)',
+                  fontSize: 11,
+                  fontWeight: 600,
+                  letterSpacing: '0.04em',
+                  textTransform: 'uppercase',
+                  color: 'var(--od-muted)',
+                  borderBottom: '1px solid var(--od-rule)',
+                  padding: '0 8px 6px',
+                }}
+              >
+                {column.label ?? column.key}
+              </th>
+            );
+          })}
+        </tr>
+      </thead>
+      <tbody>
+        {shown.map((row, rowIndex) => (
+          // Rows come from a file and carry no id of their own; their position
+          // is what identifies them.
+          // biome-ignore lint/suspicious/noArrayIndexKey: row order is the row's identity here
+          <tr key={rowIndex}>
+            {resolved.map((column) => {
+              const align = column.align ?? inferAlign(rows, column.key);
+              return (
+                <td
+                  key={column.key}
+                  style={{
+                    textAlign: align,
+                    fontSize: compact ? 11 : 12,
+                    padding: cellPadding,
+                    borderBottom: '1px solid var(--od-rule)',
+                    fontVariantNumeric: align === 'right' ? 'tabular-nums' : undefined,
+                    overflowWrap: 'anywhere',
+                  }}
+                >
+                  {formatValue(row[column.key], column.format, row, emptyValue)}
+                </td>
+              );
+            })}
+          </tr>
+        ))}
+      </tbody>
+      {hidden > 0 && (
+        <tfoot>
+          <tr>
+            <td
+              colSpan={resolved.length}
+              style={{
+                fontSize: 'var(--od-size-caption)',
+                color: 'var(--od-muted)',
+                padding: '6px 8px 0',
+              }}
+            >
+              {hidden} more row{hidden === 1 ? '' : 's'} not shown
+            </td>
+          </tr>
+        </tfoot>
+      )}
+    </table>
+  );
+
+  if (!caption) return table;
+
+  return (
+    <Figure kind="table" caption={caption} {...(id !== undefined ? { id } : {})}>
+      {table}
+    </Figure>
+  );
+}