@riebeckite/plugin-garden-explorer 0.0.13 → 0.0.15

package/README.md

@@ -1,28 +1,59 @@
 # @riebeckite/plugin-garden-explorer
 
-Interactive note garden explorer: a graph, search box, tag/folder filters, and
-note details in a single page.
+Interactive note garden explorer: a local/global content graph, search box,
+tag/folder filters, and note details in a single page.
 
 [日本語](./README_ja.md)
 
 ## Overview
 
-`gardenExplorer()` provides an interactive `GardenExplorer` component with three
-panels:
+`gardenExplorerPlugin()` provides an interactive `GardenExplorer` component with
+three panels:
 
-- **Explorer** — search box plus tag and folder filter chips (with counts) and
-  a filtered note list
-- **Graph** — an interactive radial SVG graph of notes and internal links with
-  zoom (`+`/`−`/wheel), pan (drag), and reset
+- **Explorer** — search box plus optional tag and folder filter chips (with
+  counts) and a filtered note list
+- **Graph** — an SVG graph of published notes and internal links with local and
+  global modes, force or radial layout, hover neighbor emphasis, node drag,
+  wheel/button zoom, canvas pan, reset, and click-to-open navigation
 - **Details** — the selected note's links, tags, excerpt, and related notes
 
 Selection state is mirrored to the URL query (`?note=`, `?tag=`, `?folder=`),
 so the view is shareable and the filter list adapts to the current selection.
 
-`getGardenExplorerData()` builds the note set from published entries, including
-headings, a plain-text body (truncated to 4,000 chars), tags, folders, outgoing
-links, and backlinks. Its client-side note search and radial graph layout are
-self-contained, so this plugin does not require the search plugin.
+`getGardenExplorerData()` builds the note set from `manifest.discoverableEntries`
+and `manifest.graph`, including headings, a plain-text body (truncated to 4,000
+chars), tags, folders, outgoing links, and backlinks. The graph only contains
+published/discoverable notes and resolved note links, so unpublished, excluded,
+or missing pages do not appear as graph nodes.
+
+The note list in the Explorer panel shows the first 80 filtered notes for UI
+performance. The Global Graph uses all filtered notes. If a URL-selected note
+falls outside the first 80, it is preserved in the Global Graph.
+
+## Local and global graph
+
+- **Local graph** starts at the selected note and shows neighbors up to `depth`
+  hops. The default is `depth: 1`, matching the common Obsidian/Quartz model of
+  direct backlinks and outgoing links. Use `depth: 0` to show only the selected
+  note.
+- **Global graph** shows all currently filtered public notes and their published
+  internal links.
+
+This is intentionally close to Obsidian's exploration model, but it uses
+Riebeckite's Page System, public manifest, permalinks, and content graph instead
+of rescanning the vault in the browser.
+
+## Layouts
+
+- **Force layout** (`layout: "force"`, default) uses a small deterministic
+  built-in simulation: repulsion, link distance, centering, damping, and bounded
+  stabilization. It adds no large dependency. With large graphs (>300 nodes) the
+  force layout computation becomes noticeable; a warning is shown in the toolbar.
+  For large Global Graphs, consider using the radial layout. Above 500 nodes,
+  explicit user approval is required before the force layout runs.
+- **Radial layout** (`layout: "radial"`) keeps the existing Riebeckite radial
+  layout available for compact or deterministic presentations. It runs in
+  near-linear time and handles thousands of nodes instantly.
 
 ## Usage
 
@@ -36,6 +67,23 @@ export default defineConfig({
 });
 ```
 
+With configuration:
+
+```ts
+plugins: [
+  gardenExplorerPlugin({
+    layout: "force",
+    depth: 1,
+    showTags: true,
+    showFolders: false,
+    nodeSize: 1,
+    linkDistance: 84,
+    repulsion: 1800,
+    showLabels: true,
+  }),
+];
+```
+
 `gardenExplorerPlugin()` registers the `/explore` page type and bundles
 `style.css` and its client hydrator into the app. A catch-all route using
 `resolveRiebeckiteRoute()` and `pluginPageSsgParams()` renders and emits it;
@@ -58,14 +106,16 @@ const data = getGardenExplorerData({
   manifest,
   config,
   resolveTitle: getArticleTitle,
+  options: { layout: "radial", depth: 2 },
 });
 
 // ...in a site-owned component
 return <GardenExplorer data={data} />;
 ```
 
-The component is client-side interactive and expects `window` to be available
-in the browser.
+The component is client-side interactive and expects `window` to be available in
+the browser. The server-rendered fallback still exposes the surrounding
+explorer/detail structure and links in semantic lists.
 
 ## Data
 
@@ -76,18 +126,21 @@ in the browser.
 - `edges` — note-to-note graph edges between published notes
 - `tags` — tag counts, most frequent first
 - `folders` — folder counts, alphabetical; root-level notes are `"Root"`
+- `options` — resolved graph options used by the hydrated component
 
 ## Exports
 
-- `gardenExplorerPlugin()` — plugin factory
+- `gardenExplorerPlugin(options?)` — plugin factory
 - `GardenExplorer` — interactive explorer component (default export of
   `components/garden-explorer.tsx`)
-- `getGardenExplorerData({ manifest, config, resolveTitle })` — builds the
-  explorer dataset
+- `getGardenExplorerData({ manifest, config, resolveTitle, options? })` — builds
+  the explorer dataset
 - Types: `GardenExplorerData`, `GardenExplorerEdge`, `GardenExplorerFolder`,
-  `GardenExplorerNote`, `GardenExplorerTag`
+  `GardenExplorerGraphLayout`, `GardenExplorerGraphMode`, `GardenExplorerNote`,
+  `GardenExplorerOptions`, `GardenExplorerPluginOptions`, `GardenExplorerTag`
 
 ## See also
 
-- [Plugin guide](../../../docs/en/reference/plugin-api.md)
+- [Plugin guide](../../../docs/en/docs/reference/plugin-api.md)
 - [`@riebeckite/plugin-local-graph`](../local-graph/README.md)
+

package/README_ja.md

@@ -1,6 +1,6 @@
 # @riebeckite/plugin-garden-explorer
 
-ノートの一覧、検索、タグ・フォルダーによる絞り込み、リンクグラフを一画面にまとめる探索画面です。公開済みのノートだけを対象にするため、そのまま公開サイトの `/explore` などに置けます。
+ノート一覧、検索、タグ・フォルダーによる絞り込み、Local / Global Graph、詳細パネルを一画面にまとめる探索 UI です。公開済みのノートだけを対象にするため、そのまま公開サイトの `/explore` などに置けます。
 
 [English](./README.md)
 
@@ -8,12 +8,28 @@
 
 `gardenExplorerPlugin()` は、次の三つの領域を持つ `GardenExplorer` コンポーネントとスタイルを提供します。
 
-- **一覧**: キーワード検索、タグとフォルダーのフィルター、該当ノートの一覧
-- **グラフ**: ノートと内部リンクを表示する放射状 SVG グラフ。ズーム、ドラッグ、リセットに対応
+- **一覧**: キーワード検索、任意表示のタグ・フォルダーフィルター、該当ノートの一覧
+- **グラフ**: 公開ノートと内部リンクを表示する SVG グラフ。Local / Global の切り替え、force / radial layout、hover 時の隣接ノート強調、ノード drag、wheel / button zoom、canvas pan、reset、クリックで記事へ移動に対応
 - **詳細**: 選択したノートのリンク、タグ、抜粋、関連ノート
 
 選択状態は `?note=`、`?tag=`、`?folder=` として URL に反映されます。表示中の状態をそのまま共有できます。
 
+`getGardenExplorerData()` は `manifest.discoverableEntries` と `manifest.graph` から表示データを作ります。見出し、本文テキストの先頭 4,000 文字、タグ、フォルダー、送信リンク、被リンクを含みます。Graph のノードは公開・発見可能なページと解決済み note link だけなので、未公開・除外・存在しないページは表示されません。
+
+Explorer パネルのノート一覧は、UI 性能のため先頭 80 件に制限して表示します。Global Graph は絞り込み後の全ノートを使用します。URL で選択されたノートが先頭 80 件の外にある場合、Global Graph で保持されます。
+
+## Local Graph と Global Graph
+
+- **Local Graph** は選択中のノートを起点に、`depth` で指定した hop 数までの隣接ノートを表示します。既定値は `depth: 1` で、Obsidian / Quartz と同じく直接の outgoing link と backlink を見る用途に合わせています。`depth: 0` では選択中のノートだけを表示します。
+- **Global Graph** は現在の検索・タグ・フォルダー条件で絞り込まれた公開ノート全体と、その公開内部リンクを表示します。
+
+操作感は Obsidian の Graph View に寄せていますが、Vault をブラウザ側で再探索するのではなく、Riebeckite の Page System、public manifest、permalink、Content Graph をそのまま使います。
+
+## Layout
+
+- **Force layout**（`layout: "force"`、既定）: 小さな組み込み実装で repulsion、link distance、centering、damping、安定化を行います。重い依存は追加していません。大きなグラフ（300 ノード以上）では force layout の計算時間が目立つようになり、ツールバーに警告が表示されます。大きな Global Graph には radial layout の使用を推奨します。500 ノード以上では、ユーザーの明示的な承認なしに force layout は実行されません。
+- **Radial layout**（`layout: "radial"`）: 既存の Riebeckite の放射状 layout を使います。コンパクトで決定的な見た目にしたい場合に使えます。近似線形時間で動作し、数千ノードでも瞬時に描画できます。
+
 ## 設定してページに配置する
 
 ```ts
@@ -26,15 +42,26 @@ export default defineConfig({
 });
 ```
 
-`gardenExplorerPlugin()` は `/explore` の Page Type、スタイル、クライアント側の
-hydrator を登録します。
-`resolveRiebeckiteRoute()` と `pluginPageSsgParams()` を使う共通 catch-all route
-が表示と SSG を担当するため、Plugin 固有の route は不要です。
-ページはまずサーバーで描画し、読み込み後に登録済みの client entry がグラフ、
-フィルター、URL 状態を hydration します。
+設定例:
+
+```ts
+plugins: [
+  gardenExplorerPlugin({
+    layout: "force",
+    depth: 1,
+    showTags: true,
+    showFolders: false,
+    nodeSize: 1,
+    linkDistance: 84,
+    repulsion: 1800,
+    showLabels: true,
+  }),
+];
+```
+
+`gardenExplorerPlugin()` は `/explore` の Page Type、スタイル、クライアント側の hydrator を登録します。`resolveRiebeckiteRoute()` と `pluginPageSsgParams()` を使う共通 catch-all route が表示と SSG を担当するため、Plugin 固有の route は不要です。ページはまずサーバーで描画し、読み込み後に登録済みの client entry がグラフ、フィルター、URL 状態を hydration します。
 
-コンポーネントを別の site-owned component に埋め込む場合だけ、manifest から
-表示用データを作って渡します。
+コンポーネントを別の site-owned component に埋め込む場合だけ、manifest から表示用データを作って渡します。
 
 ```tsx
 import GardenExplorer, {
@@ -46,12 +73,13 @@ const data = getGardenExplorerData({
   manifest,
   config,
   resolveTitle: getArticleTitle,
+  options: { layout: "radial", depth: 2 },
 });
 
 return <GardenExplorer data={data} />;
 ```
 
-`GardenExplorer` はブラウザで操作するクライアントコンポーネントです。サーバーで描画するだけの場所には置かず、クライアント側で動作するルートに配置してください。
+`GardenExplorer` はブラウザで操作するクライアントコンポーネントです。サーバー描画時にも周辺の一覧・詳細パネルは semantic なリンク一覧として読める構造を残します。
 
 ## データに含まれる範囲
 
@@ -61,17 +89,19 @@ return <GardenExplorer data={data} />;
 - `edges`: 公開ノート間のグラフの辺
 - `tags`: 件数の多い順のタグ
 - `folders`: 名前順のフォルダー。ルート直下のノートは `Root`
+- `options`: hydration 後の component が使う解決済み graph 設定
 
 探索画面の検索はプラグイン内で完結しており、`@riebeckite/plugin-search` は不要です。
 
 ## 主なエクスポート
 
-- `gardenExplorerPlugin()`: プラグインを作成する
+- `gardenExplorerPlugin(options?)`: プラグインを作成する
 - `GardenExplorer`: 探索画面のコンポーネント
-- `getGardenExplorerData({ manifest, config, resolveTitle })`: 表示データを構築する
-- 型: `GardenExplorerData`、`GardenExplorerEdge`、`GardenExplorerFolder`、`GardenExplorerNote`、`GardenExplorerTag`
+- `getGardenExplorerData({ manifest, config, resolveTitle, options? })`: 表示データを構築する
+- 型: `GardenExplorerData`、`GardenExplorerEdge`、`GardenExplorerFolder`、`GardenExplorerGraphLayout`、`GardenExplorerGraphMode`、`GardenExplorerNote`、`GardenExplorerOptions`、`GardenExplorerPluginOptions`、`GardenExplorerTag`
 
 ## 関連資料
 
-- [プラグインシステム](../../../docs/ja/reference/plugin-api.md)
+- [プラグインシステム](../../../docs/ja/docs/reference/plugin-api.md)
 - [`@riebeckite/plugin-local-graph`](../local-graph/README_ja.md)
+