markdown-design-doc-viewer-embed 0.0.0-stage → 1.5.0

package/package.json

@@ -1,6 +1,55 @@
 {
   "name": "markdown-design-doc-viewer-embed",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.5.0",
+  "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": {
+    "type": "git",
+    "url": "git+https://github.com/playree/markdown-design-doc-viewer.git"
+  },
+  "bugs": {
+    "url": "https://github.com/playree/markdown-design-doc-viewer/issues"
+  },
+  "homepage": "https://github.com/playree/markdown-design-doc-viewer/blob/main/docs/embed.md",
+  "keywords": [
+    "markdown",
+    "mermaid",
+    "design document",
+    "viewer",
+    "react",
+    "sequence diagram",
+    "flowchart",
+    "specification",
+    "documentation",
+    "設計書"
+  ],
+  "type": "module",
+  "sideEffects": [
+    "./viewer.css"
+  ],
+  "exports": {
+    ".": {
+      "types": "./types/embed/viewer.d.ts",
+      "default": "./index.js"
+    },
+    "./react": {
+      "types": "./types/embed/react.d.ts",
+      "default": "./react.js"
+    },
+    "./viewer.css": "./viewer.css",
+    "./package.json": "./package.json"
+  },
+  "peerDependencies": {
+    "mermaid": "^12.3.0",
+    "react": "^19.3.1",
+    "react-dom": "^19.3.1"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    },
+    "react-dom": {
+      "optional": true
+    }
+  }
+}

package/react.js

@@ -0,0 +1,45 @@
+'use client';
+
+// embed/react.tsx
+import { forwardRef, useEffect, useImperativeHandle, useRef } from "react";
+import { createViewer, openLinkInNewTab } 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(() => {
+    const instance = createViewer(element.current, viewerOptions());
+    viewer.current = instance;
+    created.current = true;
+    return () => {
+      instance.destroy();
+      viewer.current = void 0;
+    };
+  }, [options.lang]);
+  const { markdown, documentId, baseUrl, readFile, resolveResource, theme, diagramLook, splitMinWidth, toc, limitContentWidth, stickyTableHeader, tableTreeHighlight, frontMatter, headingNumbers } = 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, revealing]);
+  useImperativeHandle(ref, () => ({
+    scrollToLine: (line) => viewer.current?.scrollToLine(line),
+    markLine: (line) => viewer.current?.markLine(line)
+  }));
+  return /* @__PURE__ */ jsx("div", { ref: element, className, style });
+});
+export {
+  DesignDocViewer
+};

package/types/embed/react.d.ts

@@ -0,0 +1,23 @@
+/**
+ * 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 }} />
+ *
+ * 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';
+export interface DesignDocViewerProps extends ViewerOptions {
+    className?: string;
+    style?: CSSProperties;
+}
+/** What the `ref` of a `DesignDocViewer` gives. */
+export interface DesignDocViewerHandle {
+    /** Scrolls the viewer so that this line (0-based) of the Markdown is at the top. */
+    scrollToLine(line: number): void;
+    /** Marks the element of this line (0-based), and scrolls it into view. */
+    markLine(line: number): void;
+}
+export declare const DesignDocViewer: import("react").ForwardRefExoticComponent<DesignDocViewerProps & import("react").RefAttributes<DesignDocViewerHandle>>;

package/types/embed/viewer.d.ts

@@ -0,0 +1,66 @@
+import type { DiagramLook } from '../src/shared/protocol.js';
+export type { DiagramLook };
+export interface ViewerOptions {
+    /** The Markdown of the design document. */
+    markdown: string;
+    /**
+     * Tells the documents apart: when it changes, the viewer shows another document, from its top. While it stays the
+     * same, an update keeps the scrolling, as when the document is edited.
+     */
+    documentId?: string;
+    /**
+     * The URL of the folder of the document, from which the paths of its images and wireframes are resolved (and the
+     * wireframes read with `fetch`, without `readFile`).
+     */
+    baseUrl?: string;
+    /**
+     * Reads a file of a wireframe (its HTML, or a style sheet of it), given its path as written in the document (relative
+     * to it, or to the root with a leading `/`), decoded (`%20` is a space). Returns undefined when it cannot be read.
+     */
+    readFile?: (path: string) => Promise<string | undefined>;
+    /** The URL of an image `src` of the document. By default, resolved from `baseUrl`. */
+    resolveResource?: (src: string) => string;
+    /** The language of the texts of the viewer (`en` by default, or that of the browser). Only read by `createViewer`. */
+    lang?: 'en' | 'ja';
+    /** Light or dark colors, or those of the system (`auto`, the default). */
+    theme?: 'light' | 'dark' | 'auto';
+    /** `neo` (the default) or `classic` (flat) diagrams. */
+    diagramLook?: DiagramLook;
+    /** The width (px) from which the diagrams and their steps are side by side. 1000 by default. */
+    splitMinWidth?: number;
+    /** The table of contents at the right. true by default. */
+    toc?: boolean;
+    /** Limits the width of the document. true by default. */
+    limitContentWidth?: boolean;
+    /** Keeps the header row of a long table at the top while it scrolls. true by default. */
+    stickyTableHeader?: boolean;
+    /** Highlights the parent and children of a row of a table shown as a tree. true by default. */
+    tableTreeHighlight?: boolean;
+    /** Shows the front matter (as the header of a design document, or as a table). true by default. */
+    frontMatter?: boolean;
+    /** Shows the `autonumber` numbers on the linked headings. true by default. */
+    headingNumbers?: boolean;
+    /**
+     * Opens a link of the document (other than `#heading`, which the viewer scrolls to). By default, http(s) and mailto
+     * links open in a new tab, and the others do nothing.
+     */
+    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;
+}
+export interface Viewer {
+    /** Resolves once the document is shown, with its diagrams (that of `createViewer`, or of an update made meanwhile). */
+    ready: Promise<void>;
+    /** Changes some options (all but `lang`) and renders the document again. Resolves once it is shown (or superseded). */
+    update(options: Partial<Omit<ViewerOptions, 'lang'>>): Promise<void>;
+    /** Scrolls the viewer so that this line (0-based) of the Markdown is at the top. */
+    scrollToLine(line: number): void;
+    /** Marks the element of this line (0-based), and scrolls it into view: e.g. the line of the cursor of an editor. */
+    markLine(line: number): void;
+    /** Removes the viewer from its element. */
+    destroy(): void;
+}
+/** What `onOpenLink` does by default: opens http(s) and mailto links in a new tab. */
+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;

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

@@ -0,0 +1,111 @@
+/** Messages exchanged between the extension host and the preview webview. */
+/** Look of the mermaid diagrams: mermaid's default (`neo`, with shadows), or the flat `classic` one. */
+export type DiagramLook = 'neo' | 'classic';
+/** Color theme of the preview: VS Code's (`auto`), or always light / dark. */
+export type PreviewTheme = 'auto' | 'light' | 'dark';
+/** The differences from a revision shown by an `update` (`renderDiff` in diffRender.ts). */
+export interface DiffView {
+    /** What the document is compared with, translated (e.g. the commit). */
+    label: string;
+    /** HTML of the revision's blocks that changed, by their `data-seqnotes-diff-old`. */
+    old: string[];
+    stats: {
+        added: number;
+        changed: number;
+        deleted: number;
+    };
+}
+export type ToWebview = 
+/**
+ * Render this document. With another `uri` than the previous update (another document opened in the same
+ * window, by the desktop app), the preview starts at the top, or at `fragment` (the id of a heading) when given.
+ * With `diff`, the HTML is that of `renderDiff`, and the preview shows the differences.
+ */
+{
+    type: 'update';
+    uri: string;
+    html: string;
+    splitMinWidth: number;
+    syncEditor: boolean;
+    toc: boolean;
+    diagramLook: DiagramLook;
+    theme: PreviewTheme;
+    limitContentWidth: boolean;
+    stickyTableHeader: boolean;
+    tableTreeHighlight: boolean;
+    fragment?: string;
+    diff?: DiffView;
+}
+/** Editor scrolled: align the preview so that this line is at the top. */
+ | {
+    type: 'scrollToLine';
+    line: number;
+}
+/** Editor cursor moved: mark the element for this line. */
+ | {
+    type: 'markLine';
+    line: number;
+}
+/** Render this HTML for an exported file and send it back with `exported`. With `diff`, the HTML is that of `renderDiff`. */
+ | {
+    type: 'export';
+    id: number;
+    html: string;
+    diagramLook: DiagramLook;
+    diff?: DiffView;
+};
+export type FromWebview = {
+    type: 'ready';
+}
+/** Double-click in the preview: reveal this line in the editor. */
+ | {
+    type: 'revealLine';
+    line: number;
+} | {
+    type: 'openLink';
+    href: string;
+}
+/**
+ * The rendered body of an `export` request, or why it failed. `diagramErrors` are the messages of the diagrams
+ * mermaid could not render (shown in the body in their place), `warnings` the problems found while rendering it
+ * (the selectors of the parts of the wireframes that match nothing), with their 0-based lines.
+ */
+ | {
+    type: 'exported';
+    id: number;
+    body?: string;
+    diagramErrors?: string[];
+    warnings?: {
+        line?: number;
+        message: string;
+    }[];
+    error?: string;
+}
+/** The differences shown are closed: back to the document alone. */
+ | {
+    type: 'closeDiff';
+};
+export interface WebviewState {
+    uri: string;
+    /** Width of the diagram column in percent. */
+    split?: number;
+    /** The search and the order of a list of documents (webview/indexList.ts). */
+    indexList?: IndexListState;
+}
+/** What a list of documents shows (webview/indexList.ts): kept while the list is updated. */
+export interface IndexListState {
+    query: string;
+    /**
+     * The column the rows are sorted by (its `data-seqnotes-column`: `title`, `file` or a key of the front matter),
+     * and the order; the order of the list without it.
+     */
+    sort?: {
+        column: string;
+        descending: boolean;
+    };
+}
+/**
+ * Titles (tooltips) and labels of the preview's controls, in English: the host translates them and writes them on the
+ * body as `data-seqnotes-<name>` attributes, which the webview reads (and fills in their `{0}`).
+ */
+export declare const WEBVIEW_TITLES: Record<string, string>;