@vectojs/markdown 0.13.0 → 0.14.0

package/dist/Markdown.d.ts

@@ -162,6 +162,34 @@ export interface MarkdownOptions {
     selectable?: boolean;
     /** Emit a `vecto:markdown:parse` User Timing measure. Default `false`. */
     userTiming?: boolean;
+    /**
+     * Draw copy / download controls in the top-right corner of code blocks and
+     * tables. Default `false`.
+     *
+     * Opt-in rather than on by default because it adds two focusable stops per such
+     * block to the tab order, which a document with many code fences would make
+     * tedious to navigate past, and because a reader who cannot act on a control
+     * (no clipboard permission, no filesystem) is better served by not being
+     * offered one.
+     */
+    blockAffordances?: boolean;
+    /**
+     * Writes text to the clipboard for the copy controls.
+     *
+     * Injectable because the real path (`navigator.clipboard.writeText`) is absent
+     * in jsdom and, in a browser, rejects a write that did not originate in a user
+     * gesture — so a test can only assert the payload, never the platform call.
+     * Defaults to `navigator.clipboard.writeText` when available.
+     */
+    writeClipboard?: (text: string) => void;
+    /**
+     * Saves a generated file for the download controls.
+     *
+     * Defaults to an anchor-click download that revokes its object URL. Injectable
+     * for the same reason as {@link MarkdownOptions.writeClipboard}: jsdom has no
+     * download behaviour to observe.
+     */
+    saveFile?: (filename: string, content: string, mimeType: string) => void;
 }
 /**
  * Renders Markdown content into a VectoJS entity tree using {@link marked}.
@@ -185,6 +213,18 @@ export declare class Markdown extends UIComponent {
     theme: Required<MarkdownTheme>;
     onLinkClick?: (url: string) => void;
     selectable: boolean;
+    /**
+     * Whether code blocks and tables carry copy / download controls.
+     *
+     * Read when a block entity is built, so it affects blocks rendered from here on
+     * rather than retroactively; a document does not rebuild to gain or lose an
+     * affordance.
+     */
+    blockAffordances: 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.
@@ -578,6 +618,28 @@ export declare class Markdown extends UIComponent {
      * policy for a zero-dimension source is a separate decision from notifying
      * the scene, which is the actual defect here.
      */
+    /**
+     * Wraps a block in its copy / download controls, or returns it untouched.
+     *
+     * The controls are built lazily through `make` so a document with
+     * `blockAffordances` off pays nothing — not the closures, not the measurement
+     * `BlockAffordanceButton` does in its constructor.
+     */
+    private withBlockAffordances;
+    /** Copy and download controls for one fenced code block. */
+    private codeBlockAffordances;
+    /** Copy (as Markdown) and download (as CSV) controls for one table. */
+    private tableAffordances;
+    /**
+     * Button styling for the affordances, derived from the document theme.
+     *
+     * Themed rather than hardcoded so a light-theme document does not get the dark
+     * default palette. `focusColor` is set explicitly from the theme's accent
+     * because `Button`'s default cyan is tuned for the dark palette and reads as
+     * off-brand elsewhere — while a focus ring is the one affordance a keyboard
+     * user cannot do without.
+     */
+    private affordanceButtonOptions;
     private paragraphImage;
     /** One table cell entity, shared by the render arm and the streamed-table path. */
     private tableCellRichText;

package/dist/blockAffordances.d.ts

@@ -0,0 +1,179 @@
+/**
+ * Take-away affordances for block content: copy to the clipboard, download as a
+ * file.
+ *
+ * Split out of `Markdown.ts` rather than added to it because none of this is
+ * parsing or rendering — it is serialization plus two platform primitives — and
+ * that file is already 4.8k lines.
+ *
+ * The reference implementation is `streamdown` (clone `e5deed3`,
+ * `packages/streamdown/lib/`), read and recorded in
+ * `vectojs-docs/forge/findings/upstream/README.md`. Two details of its `save()`
+ * (`lib/utils.ts:35`) are borrowed deliberately: revoking the object URL, and the
+ * UTF-8 BOM for CSV. Both are commonly omitted and each is a real defect when
+ * missing — the first leaks a blob for the document's lifetime, the second makes
+ * Excel on Windows read the file in the system ANSI codepage and corrupt every
+ * non-ASCII cell.
+ */
+import type { A11yAttributes, Entity, LayoutControlledProperty } from '@vectojs/core';
+import { Button, type ButtonOptions, UIComponent } from '@vectojs/ui';
+/** Extension for a fence info string, without the dot. `txt` when unrecognised. */
+export declare function extensionForLanguage(lang: string): string;
+/** MIME type for a downloaded code block. */
+export declare function mimeForLanguage(lang: string): string;
+/**
+ * Escapes one CSV field per RFC 4180.
+ *
+ * A field containing a comma, a quote or a newline is wrapped in quotes, and an
+ * internal quote is doubled. Anything else is returned unchanged, so the common
+ * case allocates nothing.
+ */
+export declare function escapeCsvField(value: string): string;
+/**
+ * Escapes one Markdown table cell.
+ *
+ * Backslash first, then pipe: doing it the other way escapes the backslash that
+ * the pipe escape just introduced, which is why `streamdown` documents the order
+ * at `lib/table/utils.ts:137`.
+ */
+export declare function escapeMarkdownTableCell(cell: string): string;
+/** Column alignment as `marked` reports it on a table token. */
+export type TableAlign = 'left' | 'center' | 'right' | null;
+/** Plain-text table content, extracted from the token before entities are built. */
+export interface TableContent {
+    headers: string[];
+    rows: string[][];
+    align: readonly TableAlign[];
+}
+/**
+ * Serializes a table as CSV, prefixed with a UTF-8 BOM.
+ *
+ * Rows are `\r\n`-separated per RFC 4180.
+ *
+ * The BOM lives here rather than in {@link defaultSaveFile} — where `streamdown`
+ * puts it — so that the guarantee survives a caller supplying its own
+ * `saveFile`. Excel on Windows reads a BOM-less file in the system ANSI codepage
+ * and corrupts every non-ASCII cell, and that would be a silent,
+ * locale-dependent defect for anyone who replaced only the platform primitive.
+ * A property of the CSV belongs to the CSV.
+ */
+export declare function tableToCsv(table: TableContent): string;
+/**
+ * Serializes a table back to GitHub-flavoured Markdown.
+ *
+ * The alignment row is reproduced from the token's own `align`, so a copied table
+ * re-lexes to the same alignment rather than silently becoming left-aligned.
+ */
+export declare function tableToMarkdown(table: TableContent): string;
+/** Writes text to the clipboard, where the platform offers one. */
+export declare function defaultWriteClipboard(text: string): void;
+/**
+ * Downloads generated content as a file.
+ *
+ * Mirrors `streamdown`'s `save()` in revoking the object URL once the click has
+ * been dispatched. The other borrowed detail, the UTF-8 BOM for CSV, lives in
+ * {@link tableToCsv} instead — see there for why.
+ */
+export declare function defaultSaveFile(filename: string, content: string, mimeType: string): void;
+/**
+ * A copy or download control drawn in a block's top-right corner.
+ *
+ * Extends `@vectojs/ui`'s `Button` rather than hand-rolling an a11y hotspot: that
+ * class already projects `tag: 'button'` with a label, drives its focus ring from
+ * real DOM focus/blur, and handles hover and the disabled state. The repo rule
+ * against reimplementing what a `@vectojs/*` package provides applies to
+ * affordances too, and a bespoke hotspot would have to re-earn focus-ring
+ * behaviour `Button` already has.
+ *
+ * What this adds is transient success feedback. The label changes to a
+ * confirmation for `FEEDBACK_MS` and then reverts, which is the only signal a copy
+ * gives — nothing else about the document changes, so without it a reader cannot
+ * tell a working control from a broken one.
+ */
+export declare class BlockAffordanceButton extends Button {
+    private readonly act;
+    /** How long the confirmation label stays up, in ms. */
+    static readonly FEEDBACK_MS = 1600;
+    private readonly restingLabel;
+    private readonly successLabel;
+    private feedbackTimer;
+    constructor(label: string, successLabel: string, act: () => void, opts?: ButtonOptions);
+    /**
+     * Runs the action, then shows the confirmation.
+     *
+     * The action runs first and a throw propagates: a clipboard write the browser
+     * rejected must not be reported as a success.
+     */
+    private run;
+    private setTransientLabel;
+    /**
+     * The label a reader hears is the one they see, transient confirmation
+     * included, so an AT user gets the same feedback a sighted user does.
+     */
+    getA11yAttributes(): A11yAttributes;
+    /** Clears the pending revert so a destroyed block leaves no timer behind. */
+    destroy(): void;
+}
+/**
+ * Wraps one block and positions its affordances in the top-right corner.
+ *
+ * A wrapper is necessary rather than adding the buttons to the block directly,
+ * because both candidate parents already own their children's geometry: `Stack`
+ * positions each child in flow, and `Table` recomputes `x`/`y`/`width`/`height`
+ * for every child from its column widths (`Table.ts:66`). A button added to
+ * either would be moved on the next layout. This owns only its own children's
+ * placement and delegates its size to the block, so the surrounding document
+ * lays out exactly as it did before.
+ */
+export declare class BlockWithAffordances extends UIComponent {
+    readonly block: Entity;
+    private readonly controls;
+    /** Gap between the block's edges and the controls, in px. */
+    private static readonly INSET;
+    /** Gap between adjacent controls, in px. */
+    private static readonly GAP;
+    constructor(block: Entity, controls: readonly BlockAffordanceButton[]);
+    /**
+     * Places the controls right-aligned along the block's top edge.
+     *
+     * Laid out right-to-left from the block's right edge so the first control in
+     * the list ends up leftmost, which keeps DOM order (and therefore tab order and
+     * the a11y reading order) matching the visual order.
+     */
+    private layoutAffordances;
+    /**
+     * Re-places the controls after the block's own box changed.
+     *
+     * Called by the owner when a block is resized or its content grew; the controls
+     * are anchored to the right edge, so a width change moves them.
+     */
+    refreshAffordances(): void;
+    /** The wrapper is a pass-through: its size is the block's size. */
+    getLayoutControlledProperties(): ReadonlyArray<LayoutControlledProperty>;
+    /**
+     * Projected as a group so assistive technology reports one labelled region
+     * containing the block and its controls, rather than two unrelated siblings.
+     */
+    getA11yAttributes(): A11yAttributes;
+    render(): void;
+}
+/**
+ * Extracts plain-text table content from a `marked` table token.
+ *
+ * Reads the token rather than the built `Table` entity because the entity holds
+ * `RichText` children, not strings — reconstructing cell text from spans would
+ * have to reverse the inline formatting, and the token still has the source.
+ *
+ * `cell.text` is the cell's raw inline Markdown, which is what a copy should
+ * preserve: `**bold**` copied out of a table and pasted into another Markdown
+ * document should still be bold.
+ */
+export declare function tableContentOf(token: {
+    header: ReadonlyArray<{
+        text: string;
+    }>;
+    rows: ReadonlyArray<ReadonlyArray<{
+        text: string;
+    }>>;
+    align: readonly TableAlign[];
+}): TableContent;

package/dist/index.d.ts

@@ -1,4 +1,6 @@
 export * from './Markdown';
+export { BlockAffordanceButton, BlockWithAffordances, escapeCsvField, escapeMarkdownTableCell, extensionForLanguage, mimeForLanguage, tableContentOf, tableToCsv, tableToMarkdown, } from './blockAffordances';
+export type { TableAlign, TableContent } from './blockAffordances';
 export { parseFrontMatterFields, scanFrontMatter } from './frontMatter';
 export type { FrontMatterScan } from './frontMatter';
 export type { IncompleteMarkdownMode, StreamController, StreamControllerOptions, StreamControllerState, StreamPacingOptions, } from './StreamController';