@vectojs/markdown 0.16.1 → 0.18.0

package/dist/markdown-typography.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Typographic replacements: `--`/`---` to en/em dash, `...` to `…`, `(c)`/`(r)`/
+ * `(tm)` to `©`/`®`/`™`, `+-` to `±`, and repeated `!`/`,` collapsing —
+ * `markdown-it`'s `typographer: true` set, minus smart quotes (see below).
+ *
+ * Ported as a **pure text transform** rather than a new tokenizer or `marked`
+ * extension, because that is what it is upstream too: `markdown-it`'s own
+ * `replacements` rule runs as a `core` pass over already-tokenized `text`
+ * content, not a grammar rule, and every substitution here is describable the
+ * same way — a regex over a string that changes no token boundaries. Applying
+ * it as the last step before a `text`-bearing span is pushed keeps this
+ * completely orthogonal to every other inline arm: a bold/italic/code run's
+ * content transforms identically to a plain paragraph's, because it is the same
+ * function call, not a special case duplicated per arm.
+ *
+ * ## Off by default, unlike every other construct in this package
+ *
+ * `markdown-it` itself defaults `typographer` to `false`, and this mirrors
+ * that rather than picking a different default for parity's own sake: the
+ * transform is lossy (a real `--` a caller wanted to keep literal, e.g. a CLI
+ * flag or a code-adjacent range, becomes an en dash with no way back short of
+ * disabling the whole feature) and every other construct in this package
+ * (subscript, superscript, ins/mark, emoji, footnotes) is instead
+ * unconditionally-on syntax recognition with no lossy default to weigh.
+ * `theme.typographer` (default `false`) is the gate, checked once per paragraph
+ * of text collection rather than per span, so a caller who never opts in pays
+ * nothing beyond the one boolean check `collectSpans` already does today for
+ * `inherited`.
+ *
+ * ## Smart quotes are deliberately NOT ported
+ *
+ * `markdown-it`'s `smartquotes` rule curls straight quotes into `‘’“”` by
+ * walking the FULL inline-token sequence of one block with a stack that
+ * matches an opening quote to its closing partner, consulting the previous and
+ * next token's own trailing/leading character across token boundaries (see
+ * `references/markdown-it/lib/rules_core/smartquotes.mjs`'s `process_inlines`).
+ * That is not a per-span text transform — it is a second pass over
+ * `collectSpans`' entire OUTPUT array, with cross-span state (the open-quote
+ * stack) and lookback/lookahead into neighboring spans' text. Porting it here
+ * would mean walking `out` after the fact, which every call site of
+ * `collectSpans`/`applyTypography` would have to remember to do, and getting it
+ * wrong reads as a rendering defect (mismatched curly quotes) rather than a
+ * missing feature. Left unimplemented; a caller wanting curled quotes still
+ * gets straight ones, the same honest fallback every unsupported construct in
+ * this package gets.
+ */
+/**
+ * Apply typographic substitutions to one run of plain text.
+ *
+ * Order matters and mirrors `markdown-it`'s own rule (`replace_scoped` before
+ * `replace_rare`, and within the latter: `+-`, then `...`, then the
+ * `?`/`!`-adjacent ellipsis correction, then `!!!!`/`,,`, then em-dash, then
+ * en-dash):
+ *
+ * - `+-` before `...`: neither can produce the other's trigger character, so
+ *   order between them is actually inert, but matching upstream's order keeps
+ *   this auditable against it rather than needing its own independent proof.
+ * - The em-dash pass runs before the en-dash pass. `---` is three hyphens; the
+ *   en-dash patterns below both require a NON-hyphen on the dash-adjacent side
+ *   (`(?=[^-]|$)` / preceded by whitespace or a non-hyphen-non-space), so `---`
+ *   itself never matches either en-dash pattern regardless of order — but a
+ *   FOUR-hyphen run (`----`) would: the em-dash regex only consumes exactly
+ *   three of the four hyphens (`(^|[^-])---(?=[^-]|$)` requires its OWN
+ *   boundary hyphens to be non-hyphen), leaving a leftover single hyphens on
+ *   either side that the leftover isn't itself `--`. Verified empirically
+ *   against `markdown-it`'s reference implementation that `----` and `---`
+ *   both resolve to one em dash: `----` is not decomposed into em+en, and
+ *   running en-dash first would have changed that (the outer pair of the four
+ *   hyphens would each independently look like the START of a `--` run before
+ *   the em-dash pass ever saw the middle two as a `---`).
+ */
+export declare function applyTypography(text: string): string;

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.1",
+  "version": "0.18.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 && bun e2e/single-tilde-ink.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",