@vectojs/markdown 0.18.2 → 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,6 +117,22 @@ 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. */
@@ -585,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.

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';