@vectojs/markdown 0.18.2 → 0.19.0

package/dist/markdown-code.d.ts

@@ -2,6 +2,32 @@ import { type ContentProjection, type ContentProjectionHint, GlyphRasterAtlas, t
 import { UIComponent } from '@vectojs/ui';
 import { type MarkdownThemePresetName } from './markdown-presets';
 import type { MarkdownTheme } from './theme';
+/**
+ * Languages this build can highlight, for an app that wants to check before
+ * rendering. A language appears here when it has syntax, keywords, or both.
+ */
+export declare function highlightedLanguages(): string[];
+/** Optional behaviour for {@link CodeBlock}. */
+export interface CodeBlockOptions {
+    /**
+     * Draw a header band across the top of the block showing the language name.
+     *
+     * Off by default, and the default is not merely conservative: the band costs
+     * vertical space in every block of a document, and a label is worth that only
+     * where a document actually mixes languages. A single-language page gets the
+     * same word repeated down its length.
+     *
+     * Turning it on also RESERVES that space, which is what makes the block's
+     * own affordance controls stop overlapping the first line of code — measured
+     * before this existed: the controls occupied y 8-32 while line one occupied
+     * y 18-42, a 14px overlap in the default theme.
+     *
+     * The reserved height keeps `height` a pure function of line count (the
+     * invariant {@link CodeBlock.setWidth} documents); it only changes the
+     * constant term.
+     */
+    showLanguage?: boolean;
+}
 /**
  * A single self-rendering entity for fenced code blocks.
  *
@@ -10,6 +36,14 @@ import type { MarkdownTheme } from './theme';
  */
 export declare class CodeBlock extends UIComponent {
     private lines;
+    /**
+     * Lexical state ENTERING each line, index-aligned with {@link lines}.
+     *
+     * Entering rather than leaving, so a streamed append can resume tokenizing at
+     * the prefix-reuse boundary by reading one entry instead of re-scanning the
+     * document for an unclosed block comment.
+     */
+    private lineCarry;
     private grid;
     /** Raw (unhighlighted) lines of the last build, for prefix reuse in buildLines. */
     private rawLines;
@@ -17,6 +51,19 @@ export declare class CodeBlock extends UIComponent {
     private source;
     /** Bumped by {@link buildLines} and {@link setSelectable}; read by `Scene`. */
     private contentEpoch;
+    /**
+     * Horizontal scroll offset in local px, always in `[0, maxScrollX]`.
+     *
+     * Code does not wrap, so a line wider than the box would otherwise have an
+     * unreachable tail. This offset is subtracted from BOTH the painted cell x and
+     * the projected line x in the same frame — never one without the other, or the
+     * DOM selection carriers detach from the glyphs they are supposed to cover
+     * (the defect class `5cf7119` and `ee1de6f` fixed on the vertical axis).
+     */
+    private scrollXValue;
+    /** Memoized widest prepared line, keyed by the grid identity it came from. */
+    private contentWidthGrid;
+    private contentWidthValue;
     private lang;
     private theme;
     /**
@@ -28,6 +75,10 @@ export declare class CodeBlock extends UIComponent {
     private pad;
     private codeFont;
     selectable: boolean;
+    /** Whether the language header band is drawn. See {@link CodeBlockOptions.showLanguage}. */
+    private showLanguage;
+    /** Font of the header label, resolved once from the theme. */
+    private langFont;
     /**
      * @param theme Any subset of {@link MarkdownTheme}, or the name of a built-in
      *   preset (see {@link MarkdownThemePresetName}). Accepting a partial theme
@@ -39,7 +90,70 @@ export declare class CodeBlock extends UIComponent {
      *   be constructed directly with a preset name without going through
      *   `Markdown`.
      */
-    constructor(code: string, lang: string, maxWidth: number, theme: MarkdownThemePresetName | MarkdownTheme, selectable?: boolean);
+    constructor(code: string, lang: string, maxWidth: number, theme: MarkdownThemePresetName | MarkdownTheme, selectable?: boolean, options?: CodeBlockOptions);
+    /**
+     * The language name shown in the header, or `''` when there is nothing to show.
+     *
+     * Normalized exactly as the highlighter normalizes its lookup key, so the label
+     * and the colouring can never disagree about which language this is: a fence
+     * may be written ` ```Bash ` or carry attributes (` ```ts title="a.ts" `), and
+     * the label has to be the language, not the raw info string.
+     *
+     * Lowercased for the same reason `streamdown` lowercases its own
+     * (`lib/code-block/header.tsx:15`): the fence's capitalization is incidental,
+     * and a document mixing ` ```JS ` with ` ```js ` should not render two
+     * different-looking labels for one language.
+     */
+    private languageLabel;
+    /**
+     * Height in px of the header band, or `0` when it is off.
+     *
+     * The label sits in a band of its own rather than floating over the code,
+     * because a translucent overlay above real glyphs is unreadable at small sizes
+     * and would fight the horizontal scroll: the code slides under it, so any text
+     * drawn on top would collide with a different token every frame.
+     */
+    private headerHeight;
+    /**
+     * Local y of the first line of code.
+     *
+     * Everything that positions a row — the painter, the projection, the grid's
+     * own origin — goes through this, so the header offset cannot be applied to
+     * one and forgotten on another. That class of mismatch is exactly what
+     * detaches selection carriers from the glyphs they cover.
+     */
+    private contentTop;
+    /**
+     * Current horizontal scroll offset in local px, clamped to what the content
+     * currently allows.
+     *
+     * Clamped on READ, not only on write, because `setWidth()` may shrink the box
+     * after a scroll and is contractually forbidden from rebuilding anything. Both
+     * the painter and the projection read through here, which is what keeps the
+     * glyphs and the selection carriers on the same offset within a frame.
+     */
+    get scrollX(): number;
+    /**
+     * Widest line's overflow past the padded box, i.e. the maximum useful
+     * {@link scrollX}. `0` when every line already fits.
+     */
+    get maxScrollX(): number;
+    /**
+     * Widest prepared line, memoized against the grid that produced it.
+     *
+     * Read by {@link scrollX}, which both `render()` and `getContentProjection()`
+     * call every synced frame, so an O(lines) scan here would be an O(document) cost
+     * per frame on a long block — the exact shape the per-line projection window
+     * exists to avoid. The grid is rebuilt only when the content changes, so the
+     * cache key is identity of the grid object.
+     */
+    private contentWidth;
+    /**
+     * Scroll horizontally to `x`, clamped to `[0, maxScrollX]`.
+     *
+     * @returns `this` for chaining.
+     */
+    setScrollX(x: number): this;
     /** Re-parse code content (e.g. for live editing). */
     setCode(code: string, lang?: string): this;
     /** Enable or disable browser-native selection for this code block. */
@@ -51,9 +165,13 @@ export declare class CodeBlock extends UIComponent {
      * Deliberately does **not** rebuild the grid or the highlight, because code does
      * not reflow: lines are placed on a fixed monospace grid at `col × cellWidth` and
      * a long line overflows rather than wrapping, so `height` is a function of line
-     * *count* alone. The width only sizes the rounded background. Anything that would
-     * change the glyph geometry — the source, the language, the font — goes through
-     * {@link setCode} and invalidates the grid there.
+     * *count* alone. The width sizes the rounded background and the clip. Anything
+     * that would change the glyph geometry — the source, the language, the font —
+     * goes through {@link setCode} and invalidates the grid there.
+     *
+     * A narrower box can leave {@link scrollX} past the new end of travel. That is
+     * resolved by clamping on read rather than by adjusting anything here, so this
+     * method keeps costing nothing.
      *
      * @returns `this` for chaining.
      */
@@ -70,10 +188,23 @@ export declare class CodeBlock extends UIComponent {
      *
      * The last previously-seen line is deliberately NOT reused: a chunk usually
      * lands mid-line, so that line's text (and therefore its tokenization) changes.
+     *
+     * Prefix reuse survives multi-line constructs because {@link lineCarry} records
+     * the state ENTERING each line, so resuming at the reuse boundary needs no
+     * rescan: a carried state is a pure function of the preceding text, and that
+     * text is byte-identical over the reused prefix by construction.
      */
     private buildLines;
     private ensureGrid;
-    /** Code blocks are decorative — not interactive. */
+    /**
+     * Not hit-testable, and deliberately still not `interactive`, even though the
+     * block now consumes wheel events to scroll.
+     *
+     * The wheel arrives from the content-projection div rather than from canvas
+     * hit-testing, so no a11y shadow node is needed. Creating one would place a
+     * `pointer-events: auto` element above the transparent text mirror and swallow
+     * the mousedown that starts a native drag-selection.
+     */
     isPointInside(): boolean;
     render(r: IRenderer): void;
 }

package/dist/theme.d.ts

@@ -121,6 +121,17 @@ export interface MarkdownTheme {
     syntaxCommentColor?: string;
     /** Code-block numeric-literal color. */
     syntaxNumberColor?: string;
+    /**
+     * Color of the language name in a code block's header band.
+     *
+     * Derived from {@link syntaxCommentColor} in {@link resolveTheme} when the
+     * caller does not set it. A comment is the one token class already defined as
+     * "present but subordinate to the code", which is exactly the label's role, so
+     * a theme that tuned its comment color for a given background has already
+     * answered this question. A literal default would ignore that and read wrong on
+     * every light preset.
+     */
+    codeLangColor?: string;
     /**
      * Enable `markdown-it`-style typographic substitutions: `--`/`---` to en/em
      * dash, `...` to an ellipsis, `(c)`/`(r)`/`(tm)` to their symbols, `+-` to
@@ -147,6 +158,16 @@ export interface MarkdownTheme {
     headingSizes?: readonly number[];
     /** Code-block font size in px. */
     codeFontSize?: number;
+    /**
+     * Font size in px of the language name in a code block's header band.
+     *
+     * Left `undefined` by default and **derived** as `codeFontSize - 3` (clamped
+     * to at least 1), following {@link tableFontSize}'s precedent: the label is
+     * chrome around the code, so a caller who raises only `codeFontSize` should
+     * get a proportionally larger label rather than one that stays put and
+     * gradually looks detached from the block it belongs to.
+     */
+    codeLangFontSize?: number;
     /**
      * Table cell font size in px.
      *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vectojs/markdown",
-  "version": "0.18.2",
+  "version": "0.19.0",
   "publishConfig": {
     "access": "public"
   },
@@ -48,7 +48,7 @@
     "marked": "^18.0.7"
   },
   "peerDependencies": {
-    "@vectojs/core": ">=1.25.0 <2.0.0",
+    "@vectojs/core": ">=1.34.0 <2.0.0",
     "@vectojs/ui": ">=2.6.0 <3.0.0"
   },
   "devDependencies": {