markdown-design-doc-viewer-embed 1.5.3 → 1.5.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "markdown-design-doc-viewer-embed",
-  "version": "1.5.3",
+  "version": "1.5.5",
   "description": "The viewer of Markdown Design Doc Viewer to embed in a web app (React or not): design documents in Markdown with their mermaid sequence diagrams, flowcharts, ER and state diagrams and wireframes linked to the steps after them.",
   "license": "MIT",
   "repository": {
@@ -36,6 +36,10 @@
       "types": "./types/embed/react.d.ts",
       "default": "./react.js"
     },
+    "./export": {
+      "types": "./types/embed/export.d.ts",
+      "default": "./export.js"
+    },
     "./viewer.css": "./viewer.css",
     "./package.json": "./package.json"
   },

package/react.js

@@ -2,21 +2,46 @@
 
 // embed/react.tsx
 import { forwardRef, useEffect, useImperativeHandle, useRef } from "react";
-import { createViewer, openLinkInNewTab } from "./index.js";
+import { createDesignDocList, createViewer, openLinkInNewTab, openLinkInPage } from "./index.js";
 import { jsx } from "react/jsx-runtime";
 var DesignDocViewer = forwardRef(function DesignDocViewer2({ className, style, ...options }, ref) {
   const element = useRef(null);
   const viewer = useRef(void 0);
   const created = useRef(false);
   const latest = useRef(options);
-  latest.current = options;
-  const revealing = options.onRevealLine !== void 0;
-  const viewerOptions = () => ({
-    ...latest.current,
-    onOpenLink: (href) => (latest.current.onOpenLink ?? openLinkInNewTab)(href),
-    // Only with one: without, a double-click does nothing.
-    onRevealLine: revealing ? (line) => latest.current.onRevealLine?.(line) : void 0
+  useEffect(() => {
+    latest.current = options;
   });
+  const revealing = options.onRevealLine !== void 0;
+  const closing = options.onCloseDiff !== void 0;
+  const viewerOptions = () => {
+    const o = latest.current;
+    return {
+      markdown: o.markdown,
+      documentId: o.documentId,
+      baseUrl: o.baseUrl,
+      readFile: o.readFile,
+      resolveResource: o.resolveResource,
+      lang: o.lang,
+      theme: o.theme,
+      diagramLook: o.diagramLook,
+      splitMinWidth: o.splitMinWidth,
+      toc: o.toc,
+      limitContentWidth: o.limitContentWidth,
+      stickyTableHeader: o.stickyTableHeader,
+      tableTreeHighlight: o.tableTreeHighlight,
+      frontMatter: o.frontMatter,
+      headingNumbers: o.headingNumbers,
+      messageWrapWidth: o.messageWrapWidth,
+      compareWith: o.compareWith,
+      compareLabel: o.compareLabel,
+      onOpenLink: (href) => (latest.current.onOpenLink ?? openLinkInNewTab)(href),
+      // Only with one: without, a double-click does nothing.
+      onRevealLine: o.onRevealLine !== void 0 ? (line) => latest.current.onRevealLine?.(line) : void 0,
+      // Only with one: without, the viewer closes the differences by itself.
+      onCloseDiff: o.onCloseDiff !== void 0 ? () => latest.current.onCloseDiff?.() : void 0
+    };
+  };
   useEffect(() => {
     const instance = createViewer(element.current, viewerOptions());
     viewer.current = instance;
@@ -26,20 +51,63 @@ var DesignDocViewer = forwardRef(function DesignDocViewer2({ className, style, .
       viewer.current = void 0;
     };
   }, [options.lang]);
-  const { markdown, documentId, baseUrl, readFile, resolveResource, theme, diagramLook, splitMinWidth, toc, limitContentWidth, stickyTableHeader, tableTreeHighlight, frontMatter, headingNumbers, messageWrapWidth } = options;
+  const { markdown, documentId, baseUrl, readFile, resolveResource, theme, diagramLook, splitMinWidth, toc, limitContentWidth, stickyTableHeader, tableTreeHighlight, frontMatter, headingNumbers, messageWrapWidth, compareWith, compareLabel } = options;
   useEffect(() => {
     if (created.current) {
       created.current = false;
       return;
     }
     void viewer.current?.update(viewerOptions());
-  }, [options.lang, markdown, documentId, baseUrl, readFile, resolveResource, theme, diagramLook, splitMinWidth, toc, limitContentWidth, stickyTableHeader, tableTreeHighlight, frontMatter, headingNumbers, messageWrapWidth, revealing]);
+  }, [options.lang, markdown, documentId, baseUrl, readFile, resolveResource, theme, diagramLook, splitMinWidth, toc, limitContentWidth, stickyTableHeader, tableTreeHighlight, frontMatter, headingNumbers, messageWrapWidth, compareWith, compareLabel, revealing, closing]);
   useImperativeHandle(ref, () => ({
     scrollToLine: (line) => viewer.current?.scrollToLine(line),
     markLine: (line) => viewer.current?.markLine(line)
   }));
   return /* @__PURE__ */ jsx("div", { ref: element, className, style });
 });
+function DesignDocList({ className, style, ...options }) {
+  const element = useRef(null);
+  const list = useRef(void 0);
+  const created = useRef(false);
+  const latest = useRef(options);
+  useEffect(() => {
+    latest.current = options;
+  });
+  const listOptions = () => {
+    const o = latest.current;
+    return {
+      documents: o.documents,
+      title: o.title,
+      fileLabel: o.fileLabel,
+      filterPlaceholder: o.filterPlaceholder,
+      empty: o.empty,
+      keepOrder: o.keepOrder,
+      lang: o.lang,
+      theme: o.theme,
+      limitContentWidth: o.limitContentWidth,
+      onOpenLink: (href) => (latest.current.onOpenLink ?? openLinkInPage)(href)
+    };
+  };
+  useEffect(() => {
+    const instance = createDesignDocList(element.current, listOptions());
+    list.current = instance;
+    created.current = true;
+    return () => {
+      instance.destroy();
+      list.current = void 0;
+    };
+  }, [options.lang]);
+  const { documents, title, fileLabel, filterPlaceholder, empty, keepOrder, theme, limitContentWidth } = options;
+  useEffect(() => {
+    if (created.current) {
+      created.current = false;
+      return;
+    }
+    void list.current?.update(listOptions());
+  }, [options.lang, documents, title, fileLabel, filterPlaceholder, empty, keepOrder, theme, limitContentWidth]);
+  return /* @__PURE__ */ jsx("div", { ref: element, className, style });
+}
 export {
+  DesignDocList,
   DesignDocViewer
 };

package/types/embed/designDocList.d.ts

@@ -0,0 +1,39 @@
+/**
+ * The HTML of a list of design documents embedded in a page (`createDesignDocList` of embed/viewer.ts): the list of
+ * the design documents of the extension and the desktop app (`indexBody`), of documents given by the app instead of
+ * the files of a folder.
+ */
+import type { Translate } from '../src/shared/l10n.js';
+import type { MarkdownIt } from 'markdown-it';
+/** A document of a list (`createDesignDocList`). */
+export interface DesignDocListDocument {
+    /** Its Markdown, or only its front matter: its title and the main entries of its front matter come from it. */
+    markdown: string;
+    /** The link of its title, given to `onOpenLink` when it is clicked (`#...` scrolls the list to that fragment instead). */
+    href: string;
+    /** The folder it is in, with `/` between the folders: a table and a heading for each. The top one (`''`) by default. */
+    folder?: string;
+    /** Its file name, shown next to its title (or what `fileLabel` names). */
+    file?: string;
+    /** Its title, instead of that of the Markdown (the `title` of its front matter, its first `#` heading, `file`, or `href`). */
+    title?: string;
+}
+/** The texts and order of a list. */
+export interface DesignDocListContent {
+    documents: DesignDocListDocument[];
+    /** The heading of the list. `Design Docs` by default. */
+    title?: string;
+    /** The header of the column of `file`. `File` by default. */
+    fileLabel?: string;
+    /** The placeholder of the search box. By default, it names the title, the file name and the metadata. */
+    filterPlaceholder?: string;
+    /** The text without documents. By default, that of the extension. */
+    empty?: string;
+    /**
+     * Lists the folders and the documents in the order of `documents` (a folder where its first document is) instead of
+     * by name. false by default.
+     */
+    keepOrder?: boolean;
+}
+/** The HTML of the list of `content`, with the texts translated by `t`. */
+export declare function designDocListHtml(md: MarkdownIt, content: DesignDocListContent, t: Translate): string;

package/types/embed/export.d.ts

@@ -0,0 +1,4 @@
+import { type ExportOptions } from './viewer.js';
+export type { DiagramLook, ExportOptions } from './viewer.js';
+/** The HTML file of the design document of `options`, as a string. */
+export declare function exportHtml(options: ExportOptions): Promise<string>;

package/types/embed/react.d.ts

@@ -2,13 +2,14 @@
  * The viewer of embed/viewer.ts as a React component. Its styles are embed/viewer.css, which the app imports.
  *
  *   <DesignDocViewer markdown={text} baseUrl="/docs/" style={{ height: 600 }} />
+ *   <DesignDocList documents={[{ markdown, href: '/docs/login', file: 'login.md' }]} onOpenLink={navigate} />
  *
  * It needs a height, which the viewer fills. `readFile` and `resolveResource` render the document again when they
  * change: keep them the same across renders (`useCallback`). The other callbacks may change freely.
  */
 import { type CSSProperties } from 'react';
-import { type ViewerOptions } from './viewer.js';
-export type { ViewerOptions } from './viewer.js';
+import { type DesignDocListOptions, type ViewerOptions } from './viewer.js';
+export type { DesignDocListDocument, DesignDocListOptions, ViewerOptions } from './viewer.js';
 export interface DesignDocViewerProps extends ViewerOptions {
     className?: string;
     style?: CSSProperties;
@@ -21,3 +22,13 @@ export interface DesignDocViewerHandle {
     markLine(line: number): void;
 }
 export declare const DesignDocViewer: import("react").ForwardRefExoticComponent<DesignDocViewerProps & import("react").RefAttributes<DesignDocViewerHandle>>;
+export interface DesignDocListProps extends DesignDocListOptions {
+    className?: string;
+    style?: CSSProperties;
+}
+/**
+ * The list of the design documents of createDesignDocList (embed/viewer.ts), as high as the list. `onOpenLink` may
+ * change freely; the list is shown again when the other options change (keep `documents` the same across renders
+ * while they do not change: `useMemo`).
+ */
+export declare function DesignDocList({ className, style, ...options }: DesignDocListProps): import("react").JSX.Element;

package/types/embed/viewer.d.ts

@@ -1,5 +1,7 @@
-import type { DiagramLook } from '../src/shared/protocol.js';
+import { type DiagramLook } from '../src/shared/protocol.js';
+import { type DesignDocListContent } from './designDocList.js';
 export type { DiagramLook };
+export type { DesignDocListContent, DesignDocListDocument } from './designDocList.js';
 export interface ViewerOptions {
     /** The Markdown of the design document. */
     markdown: string;
@@ -42,7 +44,7 @@ export interface ViewerOptions {
     headingNumbers?: boolean;
     /**
      * Breaks the labels of the arrows of the sequence diagrams into lines at this many characters (a full-width one
-     * counts as 2). 0 does not break them. 30 by default.
+     * counts as 2). 0 does not break them. 40 by default.
      */
     messageWrapWidth?: number;
     /**
@@ -52,6 +54,20 @@ export interface ViewerOptions {
     onOpenLink?: (href: string) => void;
     /** Called with the line (0-based) of the Markdown double-clicked in the viewer, e.g. to show it in an editor. */
     onRevealLine?: (line: number) => void;
+    /**
+     * The Markdown of another version of the document (an older one, for instance). With it, the viewer shows `markdown`
+     * with its differences from that version: the blocks added, changed (with the words changed) and deleted, the
+     * diagrams before the change, and a bar with their numbers and buttons to go from one change to the next. Without it,
+     * the document alone.
+     */
+    compareWith?: string;
+    /** What the document is compared with (e.g. `Compared with version 3 (2026-11-01)`), shown on the bar of the differences. */
+    compareLabel?: string;
+    /**
+     * Called when the bar of the differences is closed (its × button), e.g. to remove `compareWith`. Without it, the
+     * viewer shows the document alone until `compareWith` changes.
+     */
+    onCloseDiff?: () => void;
 }
 export interface Viewer {
     /** Resolves once the document is shown, with its diagrams (that of `createViewer`, or of an update made meanwhile). */
@@ -69,3 +85,43 @@ export interface Viewer {
 export declare function openLinkInNewTab(href: string): void;
 /** Shows the design document of `options` in `container`, which it fills. */
 export declare function createViewer(container: HTMLElement, options: ViewerOptions): Viewer;
+/** The options of `createDesignDocList`. */
+export interface DesignDocListOptions extends DesignDocListContent, Pick<ViewerOptions, 'theme' | 'limitContentWidth'> {
+    /** The language of the texts of the list (`en` by default, or that of the browser). Only read by `createDesignDocList`. */
+    lang?: 'en' | 'ja';
+    /** Opens the link of a title (`href` of its document). By default, goes to it in the page (`openLinkInPage`). */
+    onOpenLink?: (href: string) => void;
+}
+export interface DesignDocList {
+    /** Resolves once the list is shown. */
+    ready: Promise<void>;
+    /** Changes some options (all but `lang`) and shows the list again, keeping its search and order. */
+    update(options: Partial<Omit<DesignDocListOptions, 'lang'>>): Promise<void>;
+    /** Removes the list from its element. */
+    destroy(): void;
+}
+/**
+ * What `onOpenLink` of a list does by default: goes to the link in the page, as the links of a list are those of the
+ * app (except `javascript:`, `data:` and `vbscript:` ones).
+ */
+export declare function openLinkInPage(href: string): void;
+/**
+ * Shows the list of the design documents of `options` in `container`: a table for each folder, with the main entries
+ * of their front matter, a search box and sortable columns. Unlike a viewer, it does not scroll inside the element:
+ * it is as high as the list.
+ */
+export declare function createDesignDocList(container: HTMLElement, options: DesignDocListOptions): DesignDocList;
+/** The options of `exportHtml` (`markdown-design-doc-viewer-embed/export`). */
+export interface ExportOptions extends Pick<ViewerOptions, 'markdown' | 'baseUrl' | 'readFile' | 'diagramLook' | 'splitMinWidth' | 'toc' | 'limitContentWidth' | 'stickyTableHeader' | 'tableTreeHighlight' | 'frontMatter' | 'headingNumbers' | 'messageWrapWidth' | 'compareWith' | 'compareLabel'> {
+    /** The language of the texts of the exported file: `en`, or `ja`. That of the browser by default. */
+    lang?: 'en' | 'ja';
+    /** The title of the page when the document has none (neither `title` in its front matter nor a `#` heading). */
+    title?: string;
+    /**
+     * What an image of the document (a path, not a URL) becomes in the exported file: a data URI to embed it, or a URL to
+     * link it. It is given the `src` of the image without its query and fragment (`icons.svg` of `icons.svg#save`), which
+     * are added back to a URL. By default, resolved from `baseUrl` (or left as it is without it). When it fails, the
+     * `src` is kept.
+     */
+    resolveImage?: (path: string) => string | Promise<string>;
+}

package/types/src/shared/l10n.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Translation of the texts shown in the preview. The extension host passes `vscode.l10n.t`;
+ * the modules here do not import `vscode`, so they take the function as a parameter.
+ */
+/** Same signature as `vscode.l10n.t`: `message` is the English text, with `{0}`, `{1}`… for `args`. */
+export type Translate = (message: string, ...args: (string | number)[]) => string;
+/** Default `Translate` that keeps the English text and only fills in the arguments. */
+export declare const formatMessage: Translate;
+/** `Translate` with the translations of a bundle (l10n/bundle.l10n.<lang>.json), keeping the English text of the others. */
+export declare function translatorFor(messages: Record<string, string>): Translate;

package/viewer.css

@@ -1761,3 +1761,12 @@ del.seqnotes-diff-del {
   position: absolute;
   max-width: calc(100% - 32px);
 }
+.seqnotes-viewer.seqnotes-embedded.seqnotes-embedded-list {
+  height: auto;
+}
+.seqnotes-embedded-list > .seqnotes-viewer-scroller {
+  height: auto;
+  overflow-x: auto;
+  overflow-y: hidden;
+  padding: 2px 0;
+}