@vectojs/markdown 0.14.0 → 0.16.0

package/dist/theme.d.ts

@@ -0,0 +1,179 @@
+/**
+ * Color, typography and spacing tokens for `@vectojs/markdown`.
+ *
+ * Split out of `Markdown.ts` so `CodeBlock` and the inline renderer can take a
+ * theme without importing the whole component, which would make the module
+ * graph cyclic. See `forge/decisions/file-decomposition-2026-08.md`.
+ */
+/**
+ * Color, typography and spacing theme for Markdown rendering.
+ *
+ * The shape is deliberately **flat**, not a nested token tree. Every key is
+ * optional and merged over {@link DEFAULT_THEME} by a single spread, so adding a
+ * key is backward compatible and a caller may override exactly one value
+ * without restating a group. A nested `{ colors: {...}, spacing: {...} }` shape
+ * would need a deep merge and would break every existing caller.
+ *
+ * Sizes and spacing are **numbers in px**, not CSS strings, because the values
+ * are consumed by canvas layout arithmetic rather than by a stylesheet.
+ */
+export interface MarkdownTheme {
+    /** Body text color. */
+    textColor?: string;
+    /** Heading text color. */
+    headingColor?: string;
+    /** Code text color (inline + block). */
+    codeColor?: string;
+    /** Code block background color. */
+    codeBgColor?: string;
+    /** Blockquote border/accent color. */
+    quoteBorderColor?: string;
+    /**
+     * Blockquote text color. Defaults to {@link MarkdownTheme.textColor} so
+     * blockquote body text matches surrounding prose unless overridden.
+     */
+    quoteTextColor?: string;
+    /** Horizontal-rule color. */
+    hrColor?: string;
+    /** Table background color. */
+    tableBgColor?: string;
+    /** Table header background color. */
+    tableHeaderBgColor?: string;
+    /** Link text color. */
+    linkColor?: string;
+    /**
+     * Color of a footnote reference marker and of the label on its definition.
+     *
+     * Defaults to {@link MarkdownTheme.linkColor} so a marker reads as a
+     * cross-reference in whatever palette the caller supplied, rather than being
+     * pinned to the stock accent. Derived in {@link resolveTheme}, so overriding
+     * only `linkColor` recolours footnote markers too.
+     *
+     * A marker is deliberately **not** a link: it carries no `href`, so it is
+     * neither underlined nor routed to `onLinkClick`. There is no destination to
+     * give it — the definition is a sibling block in the same document, not a URL —
+     * and synthesising one (`'#fn-1'`) would hand a consumer's click handler a
+     * string it would try to open as a page.
+     */
+    footnoteColor?: string;
+    /**
+     * Color for TeX source shown verbatim when a formula could not be typeset.
+     * Deliberately distinct from body text so an untypeset formula is visible as
+     * a failure rather than reading as prose.
+     */
+    mathFallbackColor?: string;
+    /** Code-block keyword color. */
+    syntaxKeywordColor?: string;
+    /** Code-block string-literal color. */
+    syntaxStringColor?: string;
+    /** Code-block comment color. */
+    syntaxCommentColor?: string;
+    /** Code-block numeric-literal color. */
+    syntaxNumberColor?: string;
+    /** Body font. */
+    bodyFont?: string;
+    /** Monospace font for code. */
+    codeFont?: string;
+    /** Base font size in px. */
+    fontSize?: number;
+    /**
+     * Font sizes in px for heading depths 1-6. A shorter array is padded by
+     * repeating its last entry; depths past the end clamp to the last entry.
+     */
+    headingSizes?: readonly number[];
+    /** Code-block font size in px. */
+    codeFontSize?: number;
+    /**
+     * Table cell font size in px.
+     *
+     * Left `undefined` by default and **derived** as `fontSize - 2` (clamped to
+     * at least 1) rather than defaulted to a literal, because that is how it was
+     * hardcoded before it became a key: a caller who raises only `fontSize` must
+     * keep getting a proportionally larger table, which a fixed default would
+     * silently break.
+     */
+    tableFontSize?: number;
+    /**
+     * Size of a footnote reference marker, as a multiple of the size of the run it
+     * sits in.
+     *
+     * Relative rather than absolute so a marker in a heading scales with the
+     * heading, exactly as inline math and inline images do. Smaller than the
+     * surrounding prose is the whole visual signal that `[1]` is a reference and
+     * not literal text, since {@link TextStyle} has no baseline shift and a raised
+     * superscript is therefore not expressible — see `markdown-footnote.ts`.
+     */
+    footnoteMarkerScale?: number;
+    /** Code-block line height in px. */
+    codeLineHeight?: number;
+    /**
+     * Line height in px for body text drawn through the plain-`Text` fallback
+     * path (an unrecognised block token that still carries `text`).
+     */
+    bodyLineHeight?: number;
+    /** Vertical gap in px between top-level blocks. */
+    blockGap?: number;
+    /** Inner padding in px of a code block. */
+    codePadding?: number;
+    /** Corner radius in px of a code block. */
+    codeRadius?: number;
+    /** Vertical gap in px between list items. */
+    listGap?: number;
+    /** Vertical gap in px between blocks inside one multi-block list item. */
+    listItemGap?: number;
+    /** Left indent in px of a blockquote's contents. */
+    quoteIndent?: number;
+    /** Width in px of a blockquote's accent border. */
+    quoteBorderWidth?: number;
+    /** Vertical gap in px between blocks inside a blockquote. */
+    quoteInnerGap?: number;
+    /** Corner radius in px of an image. */
+    imageRadius?: number;
+    /**
+     * Height of an image that renders *inline*, as a multiple of the run's font
+     * size.
+     *
+     * Applies only where an image shares a line with text — a heading or a table
+     * cell. An image that is its own block (the ordinary `![alt](url)` paragraph)
+     * still renders at its natural size capped to the available width, and ignores
+     * this.
+     *
+     * A cap rather than the natural size, because an inline object's box is fixed
+     * when the span is collected while the natural size is known only after the
+     * decode, and because a 512px logo written into an `h1` would otherwise tower
+     * over its own heading. The width follows the natural aspect ratio, so a wide
+     * badge stays wide. `1.15` keeps a square icon a little shorter than the line it
+     * sits on, which is where a cap-height glyph puts its own ink.
+     */
+    inlineImageScale?: number;
+}
+/**
+ * Resolved defaults. Every key of {@link MarkdownTheme} has an entry here, so a
+ * resolved theme is `Required<MarkdownTheme>` and no consumer needs a fallback.
+ *
+ * Two entries are placeholders that {@link resolveTheme} overwrites when the
+ * caller did not set them: `quoteTextColor` (follows `textColor`) and
+ * `tableFontSize` (derived from `fontSize`). They still carry a literal so this
+ * object satisfies `Required<MarkdownTheme>`; read {@link resolveTheme} for the
+ * value a caller actually gets.
+ */
+export declare const DEFAULT_THEME: Required<MarkdownTheme>;
+/**
+ * Merge a caller's partial theme over {@link DEFAULT_THEME}.
+ *
+ * `tableFontSize` is **derived** from the resolved `fontSize` when the caller
+ * did not set it explicitly, so raising only `fontSize` still scales tables.
+ * A plain spread cannot express that: `DEFAULT_THEME` has to satisfy
+ * `Required<MarkdownTheme>`, so its literal would always win over the
+ * derivation.
+ */
+export declare function resolveTheme(theme?: MarkdownTheme): Required<MarkdownTheme>;
+/**
+ * Font size in px for a 1-based heading depth, clamping past the end of
+ * `headingSizes` and tolerating a short or empty array.
+ *
+ * Extracted so the heading renderer and any caller inspecting the scale agree;
+ * an inline `sizes[Math.min(depth - 1, 5)]` silently yields `undefined` for a
+ * theme that supplied fewer than six sizes.
+ */
+export declare function headingSize(theme: Required<MarkdownTheme>, depth: number): number;

package/package.json

@@ -1,14 +1,15 @@
 {
   "name": "@vectojs/markdown",
-  "version": "0.14.0",
+  "version": "0.16.0",
   "publishConfig": {
     "access": "public"
   },
-  "description": "Canvas-native Markdown (and TeX math) rendering for VectoJS: a Markdown entity plus CodeBlock, built on @vectojs/ui components with marked + MathJax.",
+  "description": "Canvas-native Markdown (and TeX math) rendering for VectoJS: a Markdown entity plus CodeBlock, built on @vectojs/ui components with marked + @vectojs/tex.",
   "keywords": [
     "markdown",
     "marked",
-    "mathjax",
+    "tex",
+    "latex",
     "canvas",
     "vectojs",
     "typescript"
@@ -38,13 +39,13 @@
     "dist"
   ],
   "scripts": {
-    "build": "(cd ../ui && bun run build) && node scripts/build-worker.js && tsup src/index.ts --format cjs,esm --clean && tsc -p tsconfig.build.json",
+    "build": "(cd ../ui && bun run build) && (cd ../tex && bun run build) && node scripts/build-worker.js && tsup src/index.ts --format cjs,esm --clean && tsc -p tsconfig.build.json",
     "test": "vitest run",
-    "test:e2e": "bun e2e/blockquote-layout.e2e.ts && bun e2e/stream-controller.e2e.ts && bun e2e/lazy-math.e2e.ts && bun e2e/paragraph-image-repaint.e2e.ts && bun e2e/selection-fidelity.e2e.ts && bun e2e/code-atlas-dpr.e2e.ts && bun e2e/set-max-width.e2e.ts && bun e2e/block-affordances.e2e.ts"
+    "test:e2e": "bun e2e/blockquote-layout.e2e.ts && bun e2e/stream-controller.e2e.ts && bun e2e/lazy-math.e2e.ts && bun e2e/paragraph-image-repaint.e2e.ts && bun e2e/inline-image.e2e.ts && bun e2e/selection-fidelity.e2e.ts && bun e2e/code-atlas-dpr.e2e.ts && bun e2e/set-max-width.e2e.ts && bun e2e/block-affordances.e2e.ts"
   },
   "dependencies": {
-    "marked": "^18.0.7",
-    "mathjax-full": "^3.2.2"
+    "@vectojs/tex": "^0.1.0",
+    "marked": "^18.0.7"
   },
   "peerDependencies": {
     "@vectojs/core": ">=1.25.0 <2.0.0",