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

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 playree
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.ja.md

@@ -0,0 +1,106 @@
+# markdown-design-doc-viewer-embed
+
+[![npm](https://img.shields.io/npm/v/markdown-design-doc-viewer-embed.svg)](https://www.npmjs.com/package/markdown-design-doc-viewer-embed)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/playree/markdown-design-doc-viewer/blob/main/LICENSE)
+
+[English](https://github.com/playree/markdown-design-doc-viewer/blob/main/docs/embed.md) | 日本語
+
+[Markdown 設計書ビューア](https://github.com/playree/markdown-design-doc-viewer/blob/main/README.ja.md)のビューアを、Web アプリの部品にしたものです。Markdown で書いた設計書を、VS Code 拡張のプレビューと同じようにページの要素の中に表示します。**mermaid のシーケンス図・フローチャート・ER 図・状態遷移図と処理概要を横並びにして**、矢印（ノード）と見出しを紐付け、画面のワイヤーフレームと項目の表も紐付けます。目次、front matter の設計書のヘッダ、ライト・ダークのテーマもあります。
+
+![シーケンス図の矢印にマウスを載せると右の処理概要がハイライトされ、クリックするとそこまでスクロールし、見出しにマウスを載せると矢印がハイライトされる](https://raw.githubusercontent.com/playree/markdown-design-doc-viewer/main/images/demo.ja.gif)
+
+## インストール
+
+```sh
+npm install markdown-design-doc-viewer-embed mermaid
+```
+
+図を描く [mermaid](https://www.npmjs.com/package/mermaid)（`^12.3.0`）は peer dependency です。React の部品を使うときは React と React DOM（`^19.3.1`）も要ります。ほかに使うライブラリ（markdown-it、DOMPurify、highlight.js など）は同梱しています。
+
+アプリのバンドラ（Vite、webpack、Next.js、esbuild など）で取り込む ES モジュールです。
+
+## React
+
+```tsx
+import { DesignDocViewer } from 'markdown-design-doc-viewer-embed/react';
+import 'markdown-design-doc-viewer-embed/viewer.css';
+
+export function DesignDoc({ markdown }: { markdown: string }) {
+  return <DesignDocViewer markdown={markdown} baseUrl="https://example.com/docs/" style={{ height: 600 }} />;
+}
+```
+
+- **高さが要ります。** ビューアはその高さいっぱいに広がり、中でスクロールします。
+- props は下のオプションと、要素に付ける `className`・`style` です。
+- `readFile` と `resolveResource` が変わると描画し直すので、描画のたびに変わらないようにします（`useCallback`）。ほかのコールバックは変わってもかまいません。
+- `lang` はビューアを作るときだけ読みます。変わるとビューアを作り直します。
+- `ref` で `scrollToLine(line)`・`markLine(line)` を呼べます（`DesignDocViewerHandle`）。
+- `react.js` はクライアントコンポーネント（`'use client'`）なので、Next.js のサーバーコンポーネントからも使えます。設計書はブラウザで表示します。
+
+## React を使わない場合
+
+```ts
+import { createViewer } from 'markdown-design-doc-viewer-embed';
+import 'markdown-design-doc-viewer-embed/viewer.css';
+
+const viewer = createViewer(element, { markdown, baseUrl: 'https://example.com/docs/' });
+await viewer.ready; // 図も含めて表示し終わった
+await viewer.update({ markdown: edited, theme: 'dark' }); // documentId が同じならスクロール位置を保つ
+viewer.destroy();
+```
+
+`createViewer(container, options)` は `container`（高さが要ります）の中にビューアを作ります。返す `Viewer` には次があります。
+
+| | |
+| --- | --- |
+| `ready` | 図も含めて設計書を表示し終わると解決します。 |
+| `update(options)` | オプション（`lang` 以外）を変えて描画し直します。表示し終わると解決します。 |
+| `scrollToLine(line)` | Markdown のこの行（0 始まり）が先頭に来るようにスクロールします。 |
+| `markLine(line)` | この行（0 始まり）の要素に印を付け、見えるところまでスクロールします（エディタのカーソルの行など）。 |
+| `destroy()` | ビューアを要素から取り除きます。 |
+
+## オプション
+
+| オプション | 既定値 | |
+| --- | --- | --- |
+| `markdown` | （必須） | 設計書の Markdown。 |
+| `documentId` | | 文書を見分けます。変わると別の文書として先頭から表示し、同じ間は（編集したときのように）スクロール位置を保って更新します。 |
+| `baseUrl` | | 設計書のフォルダの URL。画像とワイヤーフレームのパスをここから解決します（`readFile` がなければワイヤーフレームを `fetch` で読みます）。 |
+| `readFile` | `baseUrl` から `fetch` | `(path) => Promise<string \| undefined>`: ワイヤーフレームのファイル（HTML とそのスタイルシート）を読みます。`path` は設計書に書いたパス（設計書からの相対パス、`/` で始まればルートから）をデコードしたもの。読めなければ undefined を返します。 |
+| `resolveResource` | `baseUrl` から解決 | `(src) => string`: 設計書の画像の `src` の URL。 |
+| `lang` | ブラウザの言語 | `'en'` か `'ja'`: ビューアの文言の言語。ビューアを作るときだけ読みます。 |
+| `theme` | `'auto'` | `'light'`、`'dark'`、またはシステムに合わせる `'auto'`。 |
+| `diagramLook` | `'neo'` | 図の見た目。`'neo'` か `'classic'`（フラット）。 |
+| `splitMinWidth` | `1000` | 図と処理概要を横並びにするビューアの幅（px）。 |
+| `toc` | `true` | 右側の目次。 |
+| `limitContentWidth` | `true` | 本文の幅を制限します。 |
+| `stickyTableHeader` | `true` | 長い表のヘッダ行をスクロールしても上に固定します。 |
+| `tableTreeHighlight` | `true` | 木構造で表示した表の行の親子をハイライトします。 |
+| `frontMatter` | `true` | front matter を（設計書のヘッダ、または表として）表示します。 |
+| `headingNumbers` | `true` | 紐付いた見出しに `autonumber` の番号を表示します。 |
+| `onOpenLink` | `openLinkInNewTab` | `(href) => void`: 設計書のリンク（ビューアがスクロールする `#見出し` 以外）を開きます。既定では http(s) と mailto のリンクを新しいタブで開き、ほかは何もしません。 |
+| `onRevealLine` | | `(line) => void`: ビューアでダブルクリックした Markdown の行（0 始まり）で呼ばれます（エディタでその行を表示するなど）。ないときはダブルクリックしても何もしません。 |
+
+## スタイル
+
+`viewer.css` はビューアのスタイルで、すべてビューアの要素（`.seqnotes-viewer`）の下に効き、ライト・ダークのテーマの色も含みます。**カスケードレイヤーに入れずに**（`@import "…" layer(components)` などにせずに）そのまま読み込んでください。設計書の要素（見出し・リスト・表など）のスタイルは詳細度を持たない（`:where()`）もので、ビューアはレイヤーに入れた CSS リセット（レイヤー `base` に入る Tailwind CSS v4 の preflight など）が消すブラウザの既定のスタイルを戻します。レイヤーの外にあるので、それらに勝ちます。レイヤーの外にある、ページの要素に対するグローバルなスタイル（`h1 { … }` や、Tailwind CSS v3 の preflight・normalize.css などのリセット）はビューアの中にも効きます。
+
+## サーバーサイドレンダリング
+
+モジュールはサーバー（Next.js など）で import できます。document や window を使うのはビューアを作るときだけです。`DesignDocViewer` はビューアを effect の中、つまりブラウザで作ります。
+
+## 制約
+
+- mermaid の設定はグローバルです。ページの複数のビューアは図を順番に描き、ビューアが自分の設定で mermaid を初期化します。mermaid は自分の DOMPurify にフックを足します。
+- ワイヤーフレームの `@font-face` は、Shadow DOM の中ではフォントを読み込まないので、ページに追加します（`document.adoptedStyleSheets`）。
+- 拡大した図と脚注のポップアップは、ページ全体の上に表示します（`position: fixed`）。
+- 画像は同期で解決します（`resolveResource`）。URL から読むようにしてください。
+- リビジョンとの差分（拡張の Git の比較）は表示できません。
+
+## 書き方
+
+図に `%% @link-headings` を書くと、その後ろの見出しに紐付きます。矢印・ノードと見出しは文言、または `%% @ref` で対応付けます。記法は[書き方](https://github.com/playree/markdown-design-doc-viewer/blob/main/README.ja.md#書き方)を、画面は[ワイヤーフレーム](https://github.com/playree/markdown-design-doc-viewer/blob/main/README.ja.md#ワイヤーフレーム)を見てください。
+
+## ライセンス
+
+[MIT](https://github.com/playree/markdown-design-doc-viewer/blob/main/LICENSE)。同梱したライブラリのライセンスは ThirdPartyNotices.txt にあります。

package/README.md

@@ -1,3 +1,106 @@
-# Temporary Holding Version
+# markdown-design-doc-viewer-embed
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![npm](https://img.shields.io/npm/v/markdown-design-doc-viewer-embed.svg)](https://www.npmjs.com/package/markdown-design-doc-viewer-embed)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/playree/markdown-design-doc-viewer/blob/main/LICENSE)
+
+English | [日本語](https://github.com/playree/markdown-design-doc-viewer/blob/main/docs/embed.ja.md)
+
+The viewer of [Markdown Design Doc Viewer](https://github.com/playree/markdown-design-doc-viewer) as a component of a web app: it shows a design document written in Markdown in an element of your page, as the VS Code extension's preview does. **Mermaid sequence diagrams, flowcharts, ER diagrams and state diagrams are shown side by side with their step descriptions**, each arrow (or node) linked to its heading, and wireframes of screens linked to their item tables, with the table of contents, the document header of the front matter, and the light and dark themes.
+
+![Hovering an arrow of the sequence diagram highlights its step on the right, clicking it scrolls to the step, and hovering a heading highlights its arrow](https://raw.githubusercontent.com/playree/markdown-design-doc-viewer/main/images/demo.gif)
+
+## Install
+
+```sh
+npm install markdown-design-doc-viewer-embed mermaid
+```
+
+[mermaid](https://www.npmjs.com/package/mermaid) (`^12.3.0`) is a peer dependency (it draws the diagrams), and so are React and React DOM (`^19.3.1`) for the React component. The other libraries it uses (markdown-it, DOMPurify, highlight.js...) are bundled in it.
+
+It is made of ES modules for the bundler of your app (Vite, webpack, Next.js, esbuild...).
+
+## React
+
+```tsx
+import { DesignDocViewer } from 'markdown-design-doc-viewer-embed/react';
+import 'markdown-design-doc-viewer-embed/viewer.css';
+
+export function DesignDoc({ markdown }: { markdown: string }) {
+  return <DesignDocViewer markdown={markdown} baseUrl="https://example.com/docs/" style={{ height: 600 }} />;
+}
+```
+
+- **It needs a height**, which the viewer fills: it scrolls inside it.
+- Its props are the options below, with `className` and `style` for its element.
+- `readFile` and `resolveResource` render the document again when they change: keep them the same across renders (`useCallback`). The other callbacks may change freely.
+- `lang` is read when the viewer is created: when it changes, the viewer is created again.
+- Its `ref` has `scrollToLine(line)` and `markLine(line)` (`DesignDocViewerHandle`).
+- `react.js` is a client component (`'use client'`), which the server components of Next.js can render: it shows the document in the browser.
+
+## Without React
+
+```ts
+import { createViewer } from 'markdown-design-doc-viewer-embed';
+import 'markdown-design-doc-viewer-embed/viewer.css';
+
+const viewer = createViewer(element, { markdown, baseUrl: 'https://example.com/docs/' });
+await viewer.ready; // the document is shown, with its diagrams
+await viewer.update({ markdown: edited, theme: 'dark' }); // keeps the scrolling while documentId stays the same
+viewer.destroy();
+```
+
+`createViewer(container, options)` adds the viewer into `container`, which needs a height. The `Viewer` it returns has:
+
+| | |
+| --- | --- |
+| `ready` | Resolves once the document is shown, with its diagrams. |
+| `update(options)` | Changes some options (all but `lang`) and renders the document again. Resolves once it is shown. |
+| `scrollToLine(line)` | Scrolls the viewer so that this line (0-based) of the Markdown is at the top. |
+| `markLine(line)` | Marks the element of this line (0-based), and scrolls it into view: e.g. the line of the cursor of an editor. |
+| `destroy()` | Removes the viewer from its element. |
+
+## Options
+
+| Option | Default | |
+| --- | --- | --- |
+| `markdown` | (required) | The Markdown of the design document. |
+| `documentId` | | 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. |
+| `baseUrl` | | 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`). |
+| `readFile` | `fetch` from `baseUrl` | `(path) => Promise<string \| undefined>`: 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. Returns undefined when it cannot be read. |
+| `resolveResource` | resolved from `baseUrl` | `(src) => string`: the URL of an image `src` of the document. |
+| `lang` | that of the browser | `'en'` or `'ja'`: the language of the texts of the viewer. Only read when the viewer is created. |
+| `theme` | `'auto'` | `'light'`, `'dark'`, or those of the system (`'auto'`). |
+| `diagramLook` | `'neo'` | `'neo'` or `'classic'` (flat) diagrams. |
+| `splitMinWidth` | `1000` | The width (px) of the viewer from which the diagrams and their steps are side by side. |
+| `toc` | `true` | The table of contents at the right. |
+| `limitContentWidth` | `true` | Limits the width of the document. |
+| `stickyTableHeader` | `true` | Keeps the header row of a long table at the top while it scrolls. |
+| `tableTreeHighlight` | `true` | Highlights the parent and children of a row of a table shown as a tree. |
+| `frontMatter` | `true` | Shows the front matter (as the header of a design document, or as a table). |
+| `headingNumbers` | `true` | Shows the `autonumber` numbers on the linked headings. |
+| `onOpenLink` | `openLinkInNewTab` | `(href) => void`: 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. |
+| `onRevealLine` | | `(line) => void`: called with the line (0-based) of the Markdown double-clicked in the viewer, e.g. to show it in an editor. Without it, a double-click does nothing. |
+
+## Styles
+
+`viewer.css` has the styles of the viewer, all under its element (`.seqnotes-viewer`), with the colors of its light and dark themes. Import it as is, **not in a cascade layer** (such as `@import "…" layer(components)`): the styles of the elements of the document (headings, lists, tables...) have no specificity (`:where()`), and the viewer gives back the defaults of the browser that a CSS reset in a layer takes away (such as the preflight of Tailwind CSS v4, in its layer `base`): they win over it because they are not in a layer. The global styles of your page for elements outside a layer (`h1 { … }`, or a reset such as Tailwind CSS v3's preflight or normalize.css) still apply in the viewer.
+
+## Server-side rendering
+
+The modules can be imported on a server (Next.js, for instance): they use the document and the window only when a viewer is created. `DesignDocViewer` creates it in an effect, in the browser.
+
+## Limitations
+
+- The configuration of mermaid is global: the viewers of a page render their diagrams one after another, and the viewer initializes mermaid with its own settings. mermaid adds hooks to its DOMPurify.
+- The `@font-face` rules of wireframes are added to the page (`document.adoptedStyleSheets`), since fonts are not loaded in a shadow root otherwise.
+- The zoomed diagrams and the popups of the footnotes are over the whole page (`position: fixed`).
+- Images are resolved synchronously (`resolveResource`): read them from URLs.
+- The differences from a revision (the extension's Git comparison) are not shown.
+
+## Writing linked documents
+
+A diagram is linked to the headings after it with `%% @link-headings` in the diagram; arrows and nodes are matched with the headings by their text, or with `%% @ref`. See [Writing linked documents](https://github.com/playree/markdown-design-doc-viewer#writing-linked-documents) for the syntax, and [Wireframes](https://github.com/playree/markdown-design-doc-viewer#wireframes) for screens.
+
+## License
+
+[MIT](https://github.com/playree/markdown-design-doc-viewer/blob/main/LICENSE). The licenses of the bundled libraries are in ThirdPartyNotices.txt.