@vectojs/markdown 0.18.1 → 0.19.0

package/dist/Markdown.d.ts

@@ -2,7 +2,8 @@ import { Entity, type DevtoolsDescriptor, IRenderer } from '@vectojs/core';
 import { type Token } from 'marked';
 import { type StreamController, type StreamControllerOptions } from './StreamController';
 export { isMathJaxReady, MathBlock, preloadMathJax } from './markdown-math';
-export { CodeBlock, codeAtlas, codeAtlasStats } from './markdown-code';
+export { CodeBlock, codeAtlas, codeAtlasStats, highlightedLanguages } from './markdown-code';
+export type { CodeBlockOptions } from './markdown-code';
 import { type MarkdownThemePresetName } from './markdown-presets';
 import { type MarkdownTheme } from './theme';
 export type { MarkdownTheme } from './theme';
@@ -11,6 +12,7 @@ export { isPresetName, PRESET_THEMES, resolvePresetTheme } from './markdown-pres
 export { registerFencedBlockRenderer, unregisterFencedBlockRenderer, hasFencedBlockRenderer, isFencedBlockRendererReady, ensureFencedBlockRenderer, renderFencedBlock, } from './markdown-fenced-registry';
 export type { FencedBlockRenderer, FencedBlockRendererSpec, FencedBlockRenderOptions, } from './markdown-fenced-registry';
 import { Stack, UIComponent } from '@vectojs/ui';
+import { type BlockAffordanceConfig, type ResolvedBlockAffordanceConfig } from './blockAffordances';
 export interface MarkdownOptions {
     maxWidth?: number;
     /**
@@ -37,6 +39,33 @@ export interface MarkdownOptions {
      * offered one.
      */
     blockAffordances?: boolean;
+    /**
+     * Which affordance controls a block gets, and what they are called.
+     *
+     * Defaults to copy + download on both code blocks and tables, i.e. exactly what
+     * `blockAffordances: true` produced before this existed. Set it to narrow the
+     * set (`{ download: false }` for copy-only blocks) or to relabel a control for a
+     * non-English document — the labels are user-visible text and are also what a
+     * screen reader announces, so they cannot stay hardcoded English.
+     *
+     * Separate from {@link blockAffordances} rather than folded into it, because the
+     * two answer different questions: whether a reader is offered controls at all,
+     * and which ones. Keeping the boolean means the common case stays a boolean.
+     */
+    affordances?: BlockAffordanceConfig;
+    /**
+     * Show the fence's language in a header band at the top-left of each code
+     * block. Default `false`.
+     *
+     * Worth turning on for a document that mixes languages, where the label tells a
+     * reader what they are looking at. A single-language page gets the same word
+     * repeated down its length, which is why it is opt-in.
+     *
+     * It also reserves vertical space at the top of the block, which is what stops
+     * {@link blockAffordances} controls from overlapping the first line of code —
+     * so a document using both wants this on.
+     */
+    showCodeLanguage?: boolean;
     /**
      * Writes text to the clipboard for the copy controls.
      *
@@ -88,20 +117,62 @@ export declare class Markdown extends UIComponent {
      * affordance.
      */
     blockAffordances: boolean;
+    /**
+     * Which controls a block carries and what they are called, with defaults
+     * applied.
+     *
+     * Resolved once in the constructor rather than per block: the defaults are
+     * fixed, and re-deriving them for every code fence in a long document would
+     * repeat the same six `??` fallbacks for no benefit.
+     */
+    affordanceConfig: ResolvedBlockAffordanceConfig;
+    /**
+     * Whether code blocks show their language in a header band.
+     *
+     * Read when a block entity is built, exactly like {@link blockAffordances}, so
+     * it affects blocks rendered from here on rather than retroactively.
+     */
+    showCodeLanguage: boolean;
     /** Clipboard writer used by the copy controls. */
     writeClipboard: (text: string) => void;
     /** File saver used by the download controls. */
     saveFile: (filename: string, content: string, mimeType: string) => void;
     private activeBlockMetrics;
     /**
-     * Called after a streamed append has re-laid-out the document.
+     * Called after this entity's own `width`/`height` changed because the document
+     * was re-laid-out. **This is the hook to wire up when a host has to move or
+     * resize anything positioned below the document.**
+     *
+     * Fires from three paths, all of which republish `width`/`height` from
+     * `content`:
+     *
+     * - a streamed append (`updateTokens`),
+     * - a width change ({@link setMaxWidth}),
+     * - a paragraph image whose decoded bitmap corrected the guessed aspect ratio
+     *   (`reflowAfterImageResize`) — the guess is a flat 16:10, so this one fires
+     *   on essentially every document containing an image, and a host that misses
+     *   it leaves every block below the image overlapping it.
+     *
+     * It does **not** fire from `setContent()`, which replaces the whole document
+     * and is a call the host already made, so this is a re-layout signal rather
+     * than a complete size signal.
+     *
+     * A `VirtualList` needs none of this to track a streaming row: it re-reads
+     * `height` on every mounted row each frame, so it sees this entity grow without
+     * being told. Prefer that where it applies. Reach for this callback when the
+     * host owns absolute positions of its own — a page that stacks navigation, a
+     * footer and a scroll height under the document has to recompute them here.
      *
-     * Not required for a `VirtualList` to track a streaming row's height: the list
-     * re-reads `height` on every mounted row each frame, so it sees this entity grow
-     * without being told. Prefer that over wiring this up — it fires from the append
-     * path only, **not** from `setContent()`, so it is not a complete size signal.
+     * There is no `onHeightChanged`. That name has been assigned by real callers
+     * through an `as unknown as` cast, which compiles, silences the type error and
+     * then never fires; if a layout callback appears dead, check the name first.
      */
     onLayoutUpdated?: () => void;
+    /**
+     * Latch for the miswired-hook warning, so a streaming document warns once
+     * rather than on every chunk.
+     */
+    private hasWarnedLayoutHookName;
     /**
      * The document's BODY text — everything after any front matter block.
      *
@@ -559,9 +630,9 @@ export declare class Markdown extends UIComponent {
      * `BlockAffordanceButton` does in its constructor.
      */
     private withBlockAffordances;
-    /** Copy and download controls for one fenced code block. */
+    /** Copy and download controls for one fenced code block, per {@link affordanceConfig}. */
     private codeBlockAffordances;
-    /** Copy (as Markdown) and download (as CSV) controls for one table. */
+    /** Copy (as Markdown) and download (as CSV) controls for one table, per {@link affordanceConfig}. */
     private tableAffordances;
     /**
      * Button styling for the affordances, derived from the document theme.
@@ -596,6 +667,23 @@ export declare class Markdown extends UIComponent {
      * level sees a freshly-sized child before it positions anything.
      */
     private reflowAfterImageResize;
+    /**
+     * Publish a completed re-layout to the host.
+     *
+     * Every path that republishes `width`/`height` from `content` ends here rather
+     * than calling {@link onLayoutUpdated} directly, so the misuse check below is
+     * reached however the re-layout was triggered.
+     *
+     * The check exists because the failure it catches is silent and was found in
+     * production, not in review. A host wired its reflow to `onHeightChanged` — a
+     * name this class has never had — through an `as unknown as` cast. The cast
+     * satisfied the compiler, the callback never fired, and every post containing
+     * an image stayed laid out against the guessed 16:10 aspect ratio with a stale
+     * document scroll height. Nothing in the type system, the tests or the console
+     * said anything. A property that is *only ever assigned* has no read site to
+     * fail, so the one place that can notice is the moment we would have called it.
+     */
+    private notifyLayoutUpdated;
     /**
      * Re-derive one `MarkdownContainer`'s cached box from its children.
      *

package/dist/blockAffordances.d.ts

@@ -75,6 +75,66 @@ export declare function defaultWriteClipboard(text: string): void;
  * {@link tableToCsv} instead — see there for why.
  */
 export declare function defaultSaveFile(filename: string, content: string, mimeType: string): void;
+/**
+ * Which take-away controls a block carries, and what they are called.
+ *
+ * Two separate axes, deliberately. WHICH controls appear is an interaction and
+ * accessibility decision — each one is a focus stop in every code block of the
+ * document, so a reader who only ever copies should be able to drop the download
+ * without also having to restate its label. WHAT they are called is a
+ * localization decision, and a consumer rendering a Chinese document needs the
+ * labels in Chinese regardless of which controls they kept.
+ *
+ * Every field is optional and every default matches the labels these controls
+ * shipped with, so an existing `blockAffordances: true` caller is unaffected.
+ */
+export interface BlockAffordanceConfig {
+    /**
+     * Show the copy-to-clipboard control. Default `true`.
+     *
+     * Copy rather than download is the one kept by default when a caller disables
+     * the other: it is the action a reader takes on a code snippet, and it needs no
+     * filesystem.
+     */
+    copy?: boolean;
+    /** Show the download-as-file control. Default `true`. */
+    download?: boolean;
+    /**
+     * Labels, for localization or for a house style that says "Copy" rather than
+     * "Copy code".
+     *
+     * The success labels are separate strings rather than derived, because no
+     * derivation survives translation: "Copied" is not a suffix or a tense rule
+     * that holds across languages.
+     */
+    labels?: {
+        /** Resting label of the code-block copy control. Default `'Copy code'`. */
+        copyCode?: string;
+        /** Resting label of the code-block download control. Default `'Download code'`. */
+        downloadCode?: string;
+        /** Resting label of the table copy control. Default `'Copy table'`. */
+        copyTable?: string;
+        /** Resting label of the table download control. Default `'Download table'`. */
+        downloadTable?: string;
+        /** Confirmation shown after a successful copy. Default `'Copied'`. */
+        copied?: string;
+        /** Confirmation shown after a successful download. Default `'Saved'`. */
+        saved?: string;
+    };
+}
+/** Resolved {@link BlockAffordanceConfig}, with every default applied. */
+export interface ResolvedBlockAffordanceConfig {
+    copy: boolean;
+    download: boolean;
+    labels: Required<NonNullable<BlockAffordanceConfig['labels']>>;
+}
+/**
+ * Apply {@link BlockAffordanceConfig} defaults.
+ *
+ * Exported so a consumer building controls by hand resolves them the same way the
+ * document does, rather than re-deriving a second set of defaults that can drift.
+ */
+export declare function resolveBlockAffordanceConfig(config?: BlockAffordanceConfig): ResolvedBlockAffordanceConfig;
 /**
  * A copy or download control drawn in a block's top-right corner.
  *

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 export * from './Markdown';
-export { BlockAffordanceButton, BlockWithAffordances, escapeCsvField, escapeMarkdownTableCell, extensionForLanguage, mimeForLanguage, tableContentOf, tableToCsv, tableToMarkdown, } from './blockAffordances';
-export type { TableAlign, TableContent } from './blockAffordances';
+export { BlockAffordanceButton, BlockWithAffordances, escapeCsvField, escapeMarkdownTableCell, extensionForLanguage, mimeForLanguage, resolveBlockAffordanceConfig, tableContentOf, tableToCsv, tableToMarkdown, } from './blockAffordances';
+export type { BlockAffordanceConfig, ResolvedBlockAffordanceConfig, TableAlign, TableContent, } from './blockAffordances';
 export { footnoteMarker } from './markdown-footnote';
 export type { FootnoteDefToken, FootnoteRefToken } from './markdown-footnote';
 export { parseFrontMatterFields, scanFrontMatter } from './frontMatter';