mosage 0.2.0 → 0.8.0

package/dist/export-Bi6nuxjT.js

@@ -0,0 +1,31 @@
+import { i as EXPORT_FORMATS } from "./cli/bin.js";
+import { i as listDocIds } from "./config-DPm1BBAb.js";
+import { i as exportDocument, r as closeRenderSession, t as cliContext } from "./context-BqsdSrAQ.js";
+import chalk from "chalk";
+//#region src/cli/export.ts
+/**
+* The Download menu without a browser window — the same render pipeline, driven
+* from a script. This is what makes a document something CI can produce on a
+* schedule rather than something a person has to click.
+*/
+async function exportDocs(docIds, opts = {}) {
+	const format = opts.format ?? "pdf";
+	if (!EXPORT_FORMATS.includes(format)) throw new Error(`Unknown format "${format}". Expected one of: ${EXPORT_FORMATS.join(", ")}`);
+	const ctx = await cliContext();
+	const targets = docIds.length > 0 ? docIds : opts.all ? await listDocIds(ctx) : [];
+	if (targets.length === 0) throw new Error("Nothing to export. Name a document id, or pass --all.");
+	try {
+		for (const docId of targets) {
+			const result = await exportDocument(ctx, docId, {
+				format,
+				...opts.outDir !== void 0 ? { outDir: opts.outDir } : {}
+			});
+			const files = result.files.join(", ");
+			process.stdout.write(`${chalk.green("✓")} ${chalk.bold(docId)} ${chalk.dim(`${result.pageCount}p`)} → ${files}\n`);
+		}
+	} finally {
+		await closeRenderSession();
+	}
+}
+//#endregion
+export { exportDocs };

package/dist/import-D2jNB07F.js

@@ -0,0 +1,25 @@
+import { a as importMarkdown, t as cliContext } from "./context-BqsdSrAQ.js";
+import chalk from "chalk";
+import path from "node:path";
+//#region src/cli/import.ts
+async function importDoc(file, opts = {}) {
+	const ctx = await cliContext();
+	const relative = path.relative(ctx.userCwd, path.resolve(ctx.userCwd, file));
+	const result = await importMarkdown(ctx, {
+		file: relative,
+		...opts.id !== void 0 ? { docId: opts.id } : {},
+		...opts.title !== void 0 ? { title: opts.title } : {},
+		...opts.subtitle !== void 0 ? { subtitle: opts.subtitle } : {},
+		...opts.author !== void 0 ? { author: opts.author } : {},
+		...opts.theme !== void 0 ? { theme: opts.theme } : {},
+		...opts.pageSize !== void 0 ? { pageSize: opts.pageSize } : {},
+		...opts.orientation !== void 0 ? { orientation: opts.orientation } : {},
+		...opts.cover !== void 0 ? { cover: opts.cover } : {},
+		...opts.contents !== void 0 ? { contents: opts.contents } : {}
+	});
+	process.stdout.write(`${chalk.green("✓")} ${chalk.bold(result.title)} → ${result.entry} ${chalk.dim(`(${result.blocks} blocks)`)}\n`);
+	if (result.assets.length > 0) process.stdout.write(chalk.dim(`  copied ${result.assets.length} asset(s)\n`));
+	for (const missing of result.missingAssets) process.stdout.write(chalk.yellow(`  ! image not found, left as written: ${missing}\n`));
+}
+//#endregion
+export { importDoc };

package/dist/index.d.ts

@@ -0,0 +1,455 @@
+import { n as MoSageConfig, t as MoSageBuildConfig } from "./config-TlTe7Ona.js";
+import { CSSProperties, ComponentType, ReactNode } from "react";
+//#region src/app/components/data-table.d.ts
+type DataAlign = 'left' | 'center' | 'right';
+type DataFormat = 'text' | 'number' | 'integer' | 'percent' | ((value: unknown, row: Record<string, unknown>) => ReactNode);
+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;
+};
+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;
+};
+/**
+ * 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.
+ */
+declare function DataTable({ rows, columns, caption, id, limit, compact, emptyValue, style, className }: DataTableProps): import("react").JSX.Element;
+//#endregion
+//#region src/app/lib/labels.d.ts
+type LabelKind = 'figure' | 'table' | 'footnote';
+type LabelEntry = {
+  /** Author-supplied id for `<Ref to>`, or a generated one. */
+  id: string;
+  kind: LabelKind;
+  /** 1-based, counted per kind across the whole document. */
+  number: number;
+  /** Caption text, for a list of figures. */
+  text: string;
+  /** 1-based page the item sits on. */
+  page: number;
+};
+/**
+ * The words wrapped around a number. Numbering is structural; what it is
+ * *called* is a document's own business — `圖 3` and `Figure 3` are the same
+ * entry. Set it once in `meta.labels`.
+ */
+type LabelVocabulary = {
+  figure: string;
+  table: string;
+  /** Heading above a page's footnotes. Empty string renders no heading. */
+  footnotes: string;
+  /** Page suffix for a cross-reference. `{page}` is replaced. */
+  onPage: string;
+};
+/** The document's numbered items of one kind, in order. Empty on the first render pass. */
+declare function useDocLabels(kind: LabelKind): LabelEntry[];
+/** One numbered item by id, once the scan has run. */
+declare function useDocLabel(id: string): LabelEntry | null;
+//#endregion
+//#region src/app/components/diagram.d.ts
+type DiagramSource = {
+  svg: string;
+  width: number;
+  height: number;
+};
+type DiagramProps = {
+  /** The compiled module from `import chart from './architecture.mmd'`. */
+  chart: DiagramSource;
+  /** Caption text. Given one, the drawing is numbered like any other figure. */
+  caption?: ReactNode;
+  captionText?: string;
+  kind?: LabelKind;
+  id?: string;
+  /**
+   * Drawn width in CSS px. Defaults to the diagram's natural size, capped to
+   * the column — a diagram wider than the text block is a layout fault, and
+   * `mosage check` would report it as one.
+   */
+  width?: number;
+  align?: 'left' | 'center';
+  style?: CSSProperties;
+  className?: string;
+};
+/**
+ * A diagram compiled from Mermaid-flavoured text at build time. The SVG is
+ * inlined rather than referenced through `<img>` so it inherits the document's
+ * theme variables — an `<img src="data:…">` would be painted in a document of
+ * its own, with none of this one's colours or faces.
+ */
+declare function Diagram({ chart, caption, captionText, kind, id, width, align, style, className }: DiagramProps): import("react").JSX.Element;
+//#endregion
+//#region src/app/components/footnote.d.ts
+type CollectedNote = {
+  id: string;
+  content: ReactNode;
+};
+type FootnoteProps = {
+  /** Stable id, so `<Ref to>` can point at the note. Generated when omitted. */
+  id?: string;
+  children?: ReactNode;
+};
+/**
+ * A note anchored to this point in the text. Inside a `flow()` section the
+ * framework lifts it to the foot of whatever page the marker lands on; on a
+ * fixed page, put a `<Footnotes />` where you want them printed.
+ */
+declare function Footnote({ id, children }: FootnoteProps): import("react").JSX.Element;
+type FootnotesProps = {
+  /** Notes to print. Omitted on a fixed page, where they are collected from it. */
+  notes?: CollectedNote[];
+  style?: CSSProperties;
+  className?: string;
+};
+declare function Footnotes({ notes, style, className }: FootnotesProps): import("react").JSX.Element | null;
+//#endregion
+//#region src/app/components/image-placeholder.d.ts
+type ImagePlaceholderProps = {
+  /** What the final image should show — the user reads this when replacing it. */
+  hint: string;
+  width?: number | string;
+  height?: number | string;
+  style?: CSSProperties;
+  className?: string;
+};
+/**
+ * Stands in for an image the user has to supply (a chart from their data, a
+ * product screenshot). Use it instead of inventing filler — never for
+ * decoration.
+ */
+declare function ImagePlaceholder({ hint, width, height, style, className }: ImagePlaceholderProps): import("react").JSX.Element;
+//#endregion
+//#region src/app/components/numbering.d.ts
+type FigureProps = {
+  /** Stable id, so `<Ref to>` can point at it. Generated when omitted. */
+  id?: string;
+  /** What the caption says after the number. */
+  caption?: ReactNode;
+  /** `figure` numbers with figures, `table` with tables. Defaults to `figure`. */
+  kind?: LabelKind;
+  /** Tables conventionally caption above, figures below. */
+  captionPosition?: 'above' | 'below';
+  /** Plain-text caption for the list of figures, when `caption` carries markup. */
+  captionText?: string;
+  style?: CSSProperties;
+  captionStyle?: CSSProperties;
+  className?: string;
+  children?: ReactNode;
+};
+/**
+ * A numbered figure or table. The number comes from a scan of the rendered
+ * pages, not from a counter in the source, so inserting a figure halfway
+ * through a document renumbers everything after it — including the references
+ * to it — without anyone editing a number.
+ *
+ * Caption and content are one block, so a `flow()` section never separates them.
+ */
+declare function Figure({ id, caption, kind, captionPosition, captionText, style, captionStyle, className, children }: FigureProps): import("react").JSX.Element;
+type RefProps = {
+  /** The `id` of a `<Figure>` or `<Footnote>`. */
+  to: string;
+  /**
+   * Append the page. `auto` (the default) adds it only when the target sits on
+   * another sheet, which is the only time a reader needs it.
+   */
+  showPage?: boolean | 'auto';
+  style?: CSSProperties;
+  className?: string;
+};
+/**
+ * A cross-reference that resolves after layout: "Figure 3", plus the page when
+ * the target is elsewhere. Never write "see Figure 3 on page 12" by hand — both
+ * numbers move.
+ */
+declare function Ref({ to, showPage, style, className }: RefProps): import("react").JSX.Element;
+type ListOfProps = {
+  kind?: LabelKind;
+  /** Show the page number column with dot leaders. Defaults to true. */
+  showPageNumbers?: boolean;
+  style?: CSSProperties;
+  className?: string;
+};
+/**
+ * The document's figures or tables as a contents list. Same lifecycle as
+ * `<TableOfContents>`: empty on the first render pass, filled once the scan has
+ * run — including before an export serializes.
+ */
+declare function ListOf({ kind, showPageNumbers, style, className }: ListOfProps): import("react").JSX.Element;
+declare function ListOfFigures(props: Omit<ListOfProps, 'kind'>): import("react").JSX.Element;
+declare function ListOfTables(props: Omit<ListOfProps, 'kind'>): import("react").JSX.Element;
+//#endregion
+//#region src/app/components/table-of-contents.d.ts
+type TableOfContentsProps = {
+  /** Deepest heading level to list. Defaults to 2 (h1 + h2). */
+  maxLevel?: number;
+  /** Show the page number column with dot leaders. Defaults to true. */
+  showPageNumbers?: boolean;
+  /** List headings that sit on the same page as the TOC itself. Defaults to false. */
+  includeOwnPage?: boolean;
+  /** Indent per heading level, in px. Defaults to 20. */
+  indent?: number;
+  style?: CSSProperties;
+  className?: string;
+};
+/**
+ * Renders the document's headings as a contents list. The outline is filled in
+ * by a DOM scan after the pages render, so this component is empty on the very
+ * first pass and populated on the next — including during PDF/HTML export,
+ * which scans before serializing.
+ */
+declare function TableOfContents({ maxLevel, showPageNumbers, includeOwnPage, indent, style, className }: TableOfContentsProps): import("react").JSX.Element;
+//#endregion
+//#region src/app/lib/design.d.ts
+type DesignPalette = {
+  bg: string;
+  text: string;
+  muted: string;
+  accent: string;
+  rule: string;
+};
+type DesignFonts = {
+  heading: string;
+  body: string;
+  mono: string;
+};
+type DesignTypeScale = {
+  title: number;
+  h1: number;
+  h2: number;
+  h3: number;
+  body: number;
+  caption: number;
+};
+type DesignSystem = {
+  palette: DesignPalette;
+  fonts: DesignFonts;
+  typeScale: DesignTypeScale;
+  /** Page margin in CSS px — the printable text block's inset from the sheet edge. */
+  margin: number;
+  /** Body line-height multiplier. Headings tighten this themselves. */
+  leading: number;
+  radius: number;
+};
+declare function designToCssVars(d: DesignSystem): Record<string, string>;
+declare function cssVarsToString(vars: Record<string, string>): string;
+declare const defaultDesign: DesignSystem;
+//#endregion
+//#region src/app/lib/sdk.d.ts
+/** The only sheets a document may be laid out on. */
+declare const PAGE_SIZE_NAMES: readonly ["A4", "B4", "A3"];
+type PageSizeName = (typeof PAGE_SIZE_NAMES)[number];
+declare const ORIENTATIONS: readonly ["portrait", "landscape"];
+type Orientation = (typeof ORIENTATIONS)[number];
+/**
+ * Portrait dimensions in CSS pixels at 96dpi — the unit authors write in —
+ * paired with the physical millimetres used when printing. Keeping both means a
+ * page laid out at 794×1123 on screen maps to a real A4 sheet with no rescaling.
+ */
+declare const PAGE_SIZES: Record<PageSizeName, {
+  width: number;
+  height: number;
+  mm: readonly [number, number];
+}>;
+declare const DEFAULT_PAGE_SIZE: PageSizeName;
+declare const DEFAULT_ORIENTATION: Orientation;
+declare function isPageSizeName(value: unknown): value is PageSizeName;
+declare function isOrientation(value: unknown): value is Orientation;
+type PageGeometry = {
+  width: number;
+  height: number;
+  /** The printed sheet in millimetres, across then down — what a Word section is sized in. */
+  mm: readonly [number, number];
+  /** Value for the `@page { size: … }` descriptor, orientation included. */
+  css: string;
+};
+type DocPage = ComponentType;
+/**
+ * A run of continuous content the framework paginates itself. Build one with
+ * `flow(...)` and put it in the page array alongside fixed pages.
+ */
+type FlowSection = {
+  readonly __odFlow: true;
+  blocks: ReactNode[];
+  /** Rendered on every page the section expands into. */
+  footer?: ComponentType;
+  /** Page padding override in px; defaults to the design's `margin`. */
+  padding?: number;
+};
+/** What a document's default export may contain: fixed pages, flow sections, or both. */
+type DocEntry = DocPage | FlowSection;
+type DocMeta = {
+  title?: string;
+  subtitle?: string;
+  author?: string;
+  pageSize?: PageSizeName;
+  orientation?: Orientation;
+  /** Id of a theme under `themes/` this document was built from. Adds a back-link. */
+  theme?: string;
+  /** ISO 8601 timestamp. Set once at scaffold time; used to sort the doc list. */
+  createdAt?: string;
+  /** What numbered items are called — `圖`/`表` instead of `Figure`/`Table`. */
+  labels?: Partial<LabelVocabulary>;
+};
+type DocModule = {
+  default: DocEntry[];
+  meta?: DocMeta;
+  design?: DesignSystem;
+};
+declare function resolvePageGeometry(meta?: DocMeta): PageGeometry;
+//#endregion
+//#region src/app/lib/flow.d.ts
+/**
+ * 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.
+ */
+declare function flow(children: ReactNode, opts?: {
+  footer?: ComponentType;
+  padding?: number;
+}): FlowSection;
+declare function isFlowSection(entry: DocEntry): entry is FlowSection;
+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;
+};
+type PaginationResult = {
+  /** Block indices per page, in order. */
+  pages: number[][];
+  /** Blocks taller than one page — they stay whole and overflow. */
+  overflowing: number[];
+};
+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.
+ */
+declare function paginateBlocks(blocks: BlockMetrics[], available: number, opts?: PaginateOptions): PaginationResult;
+//#endregion
+//#region src/app/lib/outline.d.ts
+type OutlineEntry = {
+  id: string;
+  text: string;
+  level: number;
+  /** 1-based page the heading sits on. */
+  page: number;
+};
+/**
+ * The document's headings, filled in after the pages render. Empty on the first
+ * pass — a `<TableOfContents>` renders its rows on the second, once the scan
+ * has run.
+ */
+declare function useDocOutline(): OutlineEntry[];
+//#endregion
+//#region src/app/lib/page-context.d.ts
+/** 1-based page number of the page currently rendering. `0` outside a page. */
+declare function useDocPageNumber(): number;
+/** Total page count of the document being rendered. `0` outside a page. */
+declare function useDocPageCount(): number;
+//#endregion
+//#region src/data/delimited.d.ts
+type CellValue = string | number | null;
+type DelimitedTable = {
+  columns: string[];
+  rows: Array<Record<string, CellValue>>;
+};
+type ParseOptions = {
+  /** Defaults to `,`. Tabs for `.tsv`. */
+  delimiter?: string;
+  /** Treat the first row as data and name columns `column1`, `column2`, … */
+  noHeader?: boolean;
+};
+declare function parseDelimited(text: string, opts?: ParseOptions): DelimitedTable;
+//#endregion
+//#region src/diagram/parse.d.ts
+type Direction = 'TD' | 'LR';
+type NodeShape = 'rect' | 'round' | 'stadium' | 'diamond' | 'circle';
+type DiagramNode = {
+  id: string;
+  label: string;
+  shape: NodeShape;
+};
+type EdgeStyle = 'solid' | 'dashed' | 'thick';
+type DiagramEdge = {
+  from: string;
+  to: string;
+  label: string | null;
+  style: EdgeStyle;
+  /** A `---` link draws no arrowhead. */
+  arrow: boolean;
+};
+type Diagram$1 = {
+  direction: Direction;
+  nodes: DiagramNode[];
+  edges: DiagramEdge[];
+};
+declare class DiagramSyntaxError extends Error {
+  readonly line: number;
+  constructor(message: string, line: number);
+}
+//#endregion
+//#region src/diagram/layout.d.ts
+type LayoutOptions = {
+  fontSize?: number;
+  /** Gap between consecutive ranks, along the flow direction. */
+  rankGap?: number;
+  /** Gap between siblings within a rank. */
+  nodeGap?: number;
+  maxLabelWidth?: number;
+  padding?: number;
+};
+//#endregion
+//#region src/diagram/render.d.ts
+type RenderOptions = {
+  fontSize?: number;
+  /** Suffix for the arrowhead marker ids, so two diagrams on a page cannot collide. */
+  idSuffix?: string;
+};
+//#endregion
+//#region src/diagram/index.d.ts
+type CompiledDiagram = {
+  svg: string;
+  width: number;
+  height: number;
+  /** The parsed graph, so a caller can inspect what was drawn without re-parsing. */
+  source: Diagram$1;
+};
+type CompileOptions = LayoutOptions & RenderOptions;
+/** Mermaid-flavoured text in, themed SVG out. One call, no browser. */
+declare function compileDiagram(source: string, options?: CompileOptions): CompiledDiagram;
+//#endregion
+export { type BlockMetrics, type CellValue, type CompileOptions, type CompiledDiagram, DEFAULT_ORIENTATION, DEFAULT_PAGE_SIZE, type DataAlign, type DataColumn, type DataFormat, DataTable, type DataTableProps, type DelimitedTable, type DesignFonts, type DesignPalette, type DesignSystem, type DesignTypeScale, Diagram, type DiagramProps, type DiagramSource, DiagramSyntaxError, type DocEntry, type DocMeta, type DocModule, type DocPage, Figure, type FigureProps, type FlowSection, Footnote, type FootnoteProps, Footnotes, type FootnotesProps, ImagePlaceholder, type ImagePlaceholderProps, type LabelEntry, type LabelKind, type LabelVocabulary, ListOf, ListOfFigures, type ListOfProps, ListOfTables, type MoSageBuildConfig, type MoSageConfig, ORIENTATIONS, type Orientation, type OutlineEntry, PAGE_SIZES, PAGE_SIZE_NAMES, type PageGeometry, type PageSizeName, type PaginationResult, Ref, type RefProps, TableOfContents, type TableOfContentsProps, compileDiagram, cssVarsToString, defaultDesign, designToCssVars, flow, isFlowSection, isOrientation, isPageSizeName, paginateBlocks, parseDelimited, resolvePageGeometry, useDocLabel, useDocLabels, useDocOutline, useDocPageCount, useDocPageNumber };