@vectojs/markdown 0.16.0 → 0.17.0

package/dist/theme.d.ts

@@ -62,6 +62,57 @@ export interface MarkdownTheme {
      * a failure rather than reading as prose.
      */
     mathFallbackColor?: string;
+    /**
+     * Background fill painted behind `==marked==` text (`markdown-it-mark`),
+     * consumed as {@link TextStyle.highlightColor}.
+     *
+     * A fixed default rather than derived from another theme key, unlike
+     * {@link footnoteColor}'s link-color derivation: CSS `mark`'s UA-stylesheet
+     * default (`background-color: Mark`, a yellow highlight) is not related to
+     * any other color in this theme, so there is nothing sensible to derive it
+     * from.
+     */
+    markHighlightColor?: string;
+    /**
+     * Accent/border color for a `:::kind` container, keyed by the lowercased
+     * `kind` word (`:::warning` → `containerColors.warning`).
+     *
+     * A `Record`, not one flat key per kind, because the vocabulary of kinds is
+     * open — `:::caution`, `:::success` and a project's own house style all
+     * have to resolve to *something* without a signature change here. Looked up
+     * through {@link containerColor} rather than read directly, which is what
+     * applies {@link containerDefaultColor} for a kind absent from the map (or
+     * for a bare `:::` with no kind at all).
+     *
+     * The four defaults mirror the common `note`/`tip`/`warning`/`danger`
+     * vocabulary of `markdown-it-container`/Docusaurus/mdBook admonitions;
+     * `info` aliases `note`'s color, since the two are used interchangeably
+     * across those tools and a project picking one is not expressing a second,
+     * distinct semantic.
+     */
+    containerColors?: Readonly<Record<string, string>>;
+    /**
+     * Accent/border color for a container whose `kind` is absent from
+     * {@link containerColors} — including a bare `:::` with no kind at all.
+     * Deliberately neutral (slate) rather than an error color: an unrecognised
+     * kind is a project's own vocabulary the theme does not know about, not a
+     * mistake.
+     */
+    containerDefaultColor?: string;
+    /**
+     * Background fill painted behind a `:::` container's full content area,
+     * one flat value for every kind rather than a per-kind tint.
+     *
+     * Real callout components (Docusaurus admonitions, mdBook, GitHub's own
+     * `[!NOTE]`) vary the ACCENT (border/label) by kind but keep one neutral
+     * background across all of them — the color is what signals severity, and a
+     * differently-tinted background per kind would fight the accent bar for
+     * that job rather than support it. Translucent so it composites against
+     * whatever surface a container is nested in (a container inside a
+     * blockquote inside a list), matching {@link codeBgColor}'s and
+     * {@link markHighlightColor}'s own translucent-overlay convention.
+     */
+    containerBgColor?: string;
     /** Code-block keyword color. */
     syntaxKeywordColor?: string;
     /** Code-block string-literal color. */
@@ -70,6 +121,19 @@ export interface MarkdownTheme {
     syntaxCommentColor?: string;
     /** Code-block numeric-literal color. */
     syntaxNumberColor?: string;
+    /**
+     * Enable `markdown-it`-style typographic substitutions: `--`/`---` to en/em
+     * dash, `...` to an ellipsis, `(c)`/`(r)`/`(tm)` to their symbols, `+-` to
+     * `±`, and straight quotes to curly ones (intra-run only — see
+     * {@link applyTypography}'s doc for why cross-boundary pairing is out of
+     * scope).
+     *
+     * Off by default, matching `markdown-it`'s own `typographer` option: these
+     * substitutions rewrite characters the author did not literally type, so
+     * applying them unconditionally would silently change a document's source
+     * rather than only its rendering.
+     */
+    typographer?: boolean;
     /** Body font. */
     bodyFont?: string;
     /** Monospace font for code. */
@@ -104,6 +168,47 @@ export interface MarkdownTheme {
      * superscript is therefore not expressible — see `markdown-footnote.ts`.
      */
     footnoteMarkerScale?: number;
+    /**
+     * Size of a subscript run (`H~2~O`'s `2`), as a multiple of the size of the
+     * run it sits in.
+     *
+     * Mirrors `markdown-it-sub`'s ~0.75em. Relative rather than absolute for the
+     * same reason as {@link footnoteMarkerScale}: a subscript inside a heading
+     * scales with the heading rather than reserving a body-sized glyph.
+     */
+    subscriptScale?: number;
+    /**
+     * Baseline shift for a subscript run, in em of the size of the run it sits
+     * in (the *unscaled* surrounding run, matching CSS `vertical-align: sub`,
+     * which is relative to the parent's font size rather than the subscript's
+     * own reduced one).
+     *
+     * Sign matches `TextStyle.baselineShift`: negative moves the run down. `-0.15`
+     * sits in markdown-it's ~-0.15em to -0.2em range; nothing in that range reaches
+     * the line-growth threshold at the default {@link subscriptScale}, so a lone
+     * subscript run does not grow its line (see `DEC-0001`'s degenerate case).
+     */
+    subscriptShift?: number;
+    /**
+     * Size of a superscript run (`19^th^`'s `th`), as a multiple of the size of
+     * the run it sits in. Mirrors `subscriptScale`; see that doc for why relative.
+     */
+    superscriptScale?: number;
+    /**
+     * Baseline shift for a superscript run, in em of the size of the run it sits
+     * in (the *unscaled* surrounding run — see {@link subscriptShift} for why).
+     *
+     * Positive, unlike `subscriptShift`: `TextStyle.baselineShift` is positive =
+     * up. `0.2` mirrors `subscriptShift`'s magnitude and, measured against
+     * `shiftedExtent()` at the default {@link superscriptScale}, is the largest
+     * shift that stays inside the line's existing growth slack for a lone raised
+     * run (see `DEC-0001`'s degenerate case) — `0.25` and up already force
+     * growth at this scale, which was measured directly rather than assumed:
+     * an earlier draft of this default (`0.3`, markdown-it's own superscript
+     * figure) was picked from that library's CSS without checking it against
+     * this engine's `shiftedExtent()` math, and it does force growth here.
+     */
+    superscriptShift?: number;
     /** Code-block line height in px. */
     codeLineHeight?: number;
     /**
@@ -127,6 +232,19 @@ export interface MarkdownTheme {
     quoteBorderWidth?: number;
     /** Vertical gap in px between blocks inside a blockquote. */
     quoteInnerGap?: number;
+    /**
+     * Left indent in px of a `:::` container's contents, from its accent
+     * border. Mirrors {@link quoteIndent} — a container is visually a
+     * blockquote with a label and a per-kind color, not a structurally
+     * different shape.
+     */
+    containerIndent?: number;
+    /** Width in px of a `:::` container's accent border. Mirrors {@link quoteBorderWidth}. */
+    containerBorderWidth?: number;
+    /** Vertical gap in px between blocks inside a `:::` container. Mirrors {@link quoteInnerGap}. */
+    containerInnerGap?: number;
+    /** Corner radius in px of a `:::` container's background fill. */
+    containerRadius?: number;
     /** Corner radius in px of an image. */
     imageRadius?: number;
     /**
@@ -177,3 +295,12 @@ export declare function resolveTheme(theme?: MarkdownTheme): Required<MarkdownTh
  * theme that supplied fewer than six sizes.
  */
 export declare function headingSize(theme: Required<MarkdownTheme>, depth: number): number;
+/**
+ * Accent/border color for a `:::kind` container, looked up case-insensitively
+ * (`:::Warning` and `:::warning` resolve identically — a container's `kind` is
+ * a fixed vocabulary word, not case-sensitive prose) against
+ * {@link MarkdownTheme.containerColors}. Falls back to
+ * {@link MarkdownTheme.containerDefaultColor} for a kind the map does not
+ * carry, and for a bare `:::` with no kind (`kind` is `undefined`).
+ */
+export declare function containerColor(theme: Required<MarkdownTheme>, kind: string | undefined): string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vectojs/markdown",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "publishConfig": {
     "access": "public"
   },
@@ -41,7 +41,7 @@
   "scripts": {
     "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/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"
+    "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 && bun e2e/single-tilde-ink.e2e.ts && bun e2e/superscript-ink.e2e.ts && bun e2e/ins-mark-ink.e2e.ts && bun e2e/container-ink.e2e.ts && bun e2e/abbr-ink.e2e.ts"
   },
   "dependencies": {
     "@vectojs/tex": "^0.1.0",