kakidash 0.3.1 → 0.4.0

package/README.ja.md

@@ -92,13 +92,12 @@ pnpm add kakidash
 pnpm add kakidash
 ```
 
-````typescript
+```typescript
 import { Kakidash } from 'kakidash';
 
 // コンテナ取得
 const container = document.getElementById('mindmap-container');
 
-// インスタンス化
 // インスタンス化 (オプション指定可能)
 const kakidash = new Kakidash(container, {
     locale: 'ja', // オプション: 'en' | 'ja' (デフォルト: 'en')
@@ -106,11 +105,13 @@ const kakidash = new Kakidash(container, {
     customStyles: {    // オプション: 初期のカスタムスタイル
         rootNode: { border: '2px solid red' }
     },
-    disabledCommandPaletteFeatures: ['import'] // オプション: 特定の機能を無効化
+    disabledCommandPaletteFeatures: ['import'], // オプション: 特定の機能を無効化
+    //getImage: (ref) => myImageMap[ref] // オプション: 拡大表示用にオリジナル画像を取得するコールバック
 });
 
 // 必要に応じて初期データをロードしたり、ノードを追加したりします
 kakidash.addNode(kakidash.getRootId(), 'Hello World');
+```
 
 ### 3. テーマの切り替え
 
@@ -118,9 +119,7 @@ kakidash.addNode(kakidash.getRootId(), 'Hello World');
 
 ```typescript
 kakidash.setTheme('dark'); // 'default', 'simple', 'colorful', 'dark'
-````
-
-````
+```
 
 #### B. ブラウザ直接読み込み (Script Tag / CDN)
 
@@ -209,7 +208,9 @@ kakidash.setTheme('custom');
   - `options.disabledCommandPaletteFeatures`: コマンドパレットの特定の機能を無効化 ('search' | 'icon' | 'import' | 'export')。
 - **`kakidash.addNode(parentId, topic)`**: 指定した親ノードに新しい子ノードを追加します。
 - **`kakidash.getData()`**: 現在のマインドマップデータをJSONオブジェクトとして取得します。
-- **`kakidash.loadData(data)`**: JSONデータを読み込み、マインドマップを描画します。
+- **`kakidash.loadData(data)`**: JSONデータを読み込み、マインドマップを描画します。画像埋め込み済みの旧形式データも自動移行して読み込めます。
+- **`kakidash.getImages()`**: 現在メモリ（ImageStore）に保持されているすべてのオリジナル画像を取得します。
+- **`kakidash.gcImages()`**: 使用されていない画像をメモリから削除します。
 - **`kakidash.updateGlobalStyles(styles)`**: グローバルスタイルを更新します ('custom' テーマ選択時のみ有効)。
 - **`kakidash.updateLayout(mode)`**: レイアウトモードを変更します ('Standard', 'Left', 'Right')。
 - **`kakidash.setReadOnly(boolean)`**: 読み取り専用モードを切り替えます。
@@ -391,6 +392,28 @@ board.registerCommand({
 
 登録されたコマンドはコマンドパレット（デフォルト：`m` キー）の一覧に表示されます。項目をクリックするか Enter キーを押すことで実行されます。
 
+## 画像の管理 (ハイブリッド形式)
+
+Kakidashは、大量の画像を効率的に扱うために「ハイブリッド保存方式」を採用しています。
+- **サムネイル**: 軽量な画像データ。マインドマップのJSON内に直接保存されます。
+- **オリジナル画像**: 高解像度の画像データ。JSONからは切り離され、メモリ上（`ImageStore`）で管理されます。これらはホストアプリケーション（VSCode拡張機能など）側でサイドカーフォルダ等に保存する必要があります。
+
+### 実装例: VSCode拡張機能との連携
+
+```typescript
+// 1. 保存時
+const data = kakidash.getData(); // 巨大な画像を含まない軽量なJSON
+const images = kakidash.getImages(); // { 参照ID: Base64データ } のマップ
+
+// 'data' を .kaki ファイルに、'images' を 'filename_images/' フォルダ等に保存します
+saveToDisk(data, images);
+
+// 2. 読み込み時
+const { data, images } = loadFromDisk();
+kakidash.loadData(data); // 旧形式（画像埋め込み）の場合も自動でマイグレーションされます
+// コンストラクタの getImage コールバックを通じて、読み込んだ画像をライブラリに提供します
+```
+
 ## アーキテクチャ
 
 ソフトウェアアーキテクチャの詳細や内部モジュールの依存関係については、以下を参照してください：

package/README.md

@@ -90,13 +90,12 @@ Prepare a container element (e.g., `div`) to display `kakidash`.
 pnpm add kakidash
 ```
 
-````typescript
+```typescript
 import { Kakidash } from 'kakidash';
 
 // Get container
 const container = document.getElementById('mindmap-container');
 
-// Instantiate
 // Instantiate with optional configuration
 const kakidash = new Kakidash(container, {
     locale: 'en', // Optional: 'en' | 'ja' (Default: 'en')
@@ -104,11 +103,13 @@ const kakidash = new Kakidash(container, {
     customStyles: {    // Optional: Initial custom styles
         rootNode: { border: '2px solid red' }
     },
-    disabledCommandPaletteFeatures: ['import'] // Optional: Disable specific features
+    disabledCommandPaletteFeatures: ['import'], // Optional: Disable specific features
+    //getImage: (ref) => myImageMap[ref] // Optional: Callback to fetch original images for zooming
 });
 
 // Add initial data or nodes if needed
 kakidash.addNode(kakidash.getRootId(), 'Hello World');
+```
 
 ### 3. Theme Selection
 
@@ -116,9 +117,7 @@ You can switch themes dynamically:
 
 ```typescript
 kakidash.setTheme('dark'); // 'default', 'simple', 'colorful', 'dark'
-````
-
-````
+```
 
 #### B. Browser Direct Import (Script Tag / CDN)
 
@@ -204,7 +203,9 @@ All values accept standard CSS strings.
   - `options.disabledCommandPaletteFeatures`: Features to disable in the command palette ('search' | 'icon' | 'import' | 'export').
 - **`kakidash.addNode(parentId, topic)`**: Adds a new child node to the specified parent node.
 - **`kakidash.getData()`**: Retrieves current mindmap data as a JSON object.
-- **`kakidash.loadData(data)`**: Loads JSON data and renders the mindmap.
+- **`kakidash.loadData(data)`**: Loads JSON data and renders the mindmap. Supports legacy format with embedded images.
+- **`kakidash.getImages()`**: Retrieves all original high-resolution images currently in memory.
+- **`kakidash.gcImages()`**: Cleans up unused images from memory.
 - **`kakidash.updateGlobalStyles(styles)`**: Updates global styles (only active when theme is 'custom').
 - **`kakidash.updateLayout(mode)`**: Changes layout mode ('Standard', 'Left', 'Right').
 - **`kakidash.setReadOnly(boolean)`**: Toggles read-only mode.
@@ -386,6 +387,28 @@ board.registerCommand({
 
 Registered commands will appear in the Command Palette (default key: `m`). Clicking or pressing Enter on the item will execute the handler.
 
+## Image Management (Hybrid Storage)
+
+Kakidash uses a hybrid storage approach to handle large images efficiently. 
+- **Thumbnails**: Small, low-resolution versions are stored directly in the JSON data.
+- **Originals**: High-resolution versions are kept in a separate memory store (`ImageStore`) and should be persisted by the host application (e.g., in a sidecar folder).
+
+### Example: VSCode Extension Integration
+
+```typescript
+// 1. Saving
+const data = kakidash.getData(); // JSON without large images
+const images = kakidash.getImages(); // Map of { imageRef: base64Data }
+
+// Save 'data' to .kaki file and 'images' to .kaki_images/ folder
+saveToDisk(data, images);
+
+// 2. Loading
+const { data, images } = loadFromDisk();
+kakidash.loadData(data); // Library handles migration if old format
+// Images should be provided via the getImage callback in constructor
+```
+
 ## Architecture
 
 For details on the software architecture and internal module dependencies, please refer to:

package/dist/index.d.ts

@@ -137,6 +137,8 @@ declare interface ControllerDependencies {
     fileIOService: FileIOService;
     themeService: ThemeService;
     commandBus: CommandBus;
+    imageStore: ImageStore;
+    imageProcessingService: ImageProcessingService;
     locale?: 'en' | 'ja';
     commandPaletteFeatures?: ('search' | 'icon' | 'import' | 'export')[];
 }
@@ -204,6 +206,54 @@ declare interface IdGenerator {
     generate(): string;
 }
 
+declare class ImageProcessingService {
+    /**
+     * Generates a lightweight thumbnail from a base64 image string.
+     * Uses HTML Canvas API.
+     * @param base64Data The original base64 image data
+     * @param maxWidth The maximum width for the thumbnail (default 200)
+     * @param quality Image quality for lossy formats (0 to 1, default 0.7)
+     */
+    generateThumbnail(base64Data: string, maxWidth?: number, quality?: number): Promise<ThumbnailResult>;
+    /**
+     * Calculates proportional dimensions preserving aspect ratio, constrained by maxWidth.
+     */
+    calculateDimensions(originalWidth: number, originalHeight: number, maxWidth: number): {
+        width: number;
+        height: number;
+    };
+}
+
+declare class ImageStore {
+    private images;
+    /**
+     * Adds an image to the store.
+     * @param ref The unique reference or filename of the image
+     * @param base64Data The original base64 image data
+     */
+    addImage(ref: string, base64Data: string): void;
+    /**
+     * Retrieves an image from the store.
+     * @param ref The unique reference or filename of the image
+     * @returns The base64 image data, or undefined if not found
+     */
+    getImage(ref: string): string | undefined;
+    /**
+     * Removes an image from the store.
+     * @param ref The unique reference or filename of the image
+     */
+    removeImage(ref: string): void;
+    /**
+     * Retrieves all image references currently in the store.
+     * @returns Array of references
+     */
+    getAllRefs(): string[];
+    /**
+     * Clears all images from the store.
+     */
+    clear(): void;
+}
+
 declare interface IMindMapEventBus {
     emit<K extends keyof KakidashEventMap>(event: K, payload: KakidashEventMap[K]): void;
     on<K extends keyof KakidashEventMap>(event: K, handler: (payload: KakidashEventMap[K]) => void): void;
@@ -349,6 +399,7 @@ export declare class Kakidash extends TypedEventEmitter<KakidashEventMap> {
     panBoard(dx: number, dy: number): void;
     zoomBoard(delta: number, clientX: number, clientY: number): void;
     resetZoom(): void;
+    zoomNode(nodeId: string): void;
     copyNode(nodeId: string): void;
     pasteNode(parentId: string): void;
     pasteImage(parentId: string, imageData: string, width?: number, height?: number): void;
@@ -358,6 +409,8 @@ export declare class Kakidash extends TypedEventEmitter<KakidashEventMap> {
     getLayoutMode(): LayoutMode;
     navigateNode(nodeId: string, direction: Direction): void;
     getData(): MindMapData;
+    getImages(): Record<string, string>;
+    gcImages(): void;
     loadData(data: MindMapData): void;
     getRootId(): string;
 }
@@ -526,6 +579,8 @@ declare class MindMapController {
     private searchService;
     private viewportService;
     private navigationService;
+    private imageStore;
+    private imageProcessingService;
     private anchorNodeId;
     private selectedNodeId;
     private selectedNodeIds;
@@ -541,6 +596,9 @@ declare class MindMapController {
     init(containerWidth: number, containerHeight: number): void;
     destroy(): void;
     getData(): MindMapData;
+    getImages(): Record<string, string>;
+    getImage(ref: string): string | undefined;
+    gcImages(): void;
     loadData(data: MindMapData): void;
     batch(callback: () => void): void;
     getSelectedNodeId(): string | null;
@@ -579,6 +637,7 @@ declare class MindMapController {
      * Fast path: update selection styles without full DOM rebuild.
      */
     private renderSelection;
+    zoomNode(nodeId: string): void;
     setLayoutMode(mode: LayoutMode): void;
     getLayoutMode(): LayoutMode;
     setMaxNodeWidth(width: number): void;
@@ -637,6 +696,8 @@ export declare interface MindMapNodeData {
     root?: boolean;
     isFolded?: boolean;
     parentId?: string;
+    thumbnail?: string;
+    imageRef?: string;
     image?: string;
     imageSize?: {
         width: number;
@@ -652,7 +713,7 @@ declare class MindMapService {
     private idGenerator;
     constructor(mindMap: MindMap, idGenerator: IdGenerator);
     addNode(parentId: string, topic?: string, layoutSide?: 'left' | 'right'): Node_2 | null;
-    addImageNode(parentId: string, imageData: string, width?: number, height?: number): Node_2 | null;
+    addImageNode(parentId: string, thumbnail: string, imageRef: string, width?: number, height?: number): Node_2 | null;
     removeNode(id: string): boolean;
     removeNodes(ids: string[]): boolean;
     updateNodeTopic(id: string, topic: string): boolean;
@@ -726,6 +787,8 @@ declare class Node_2 {
     style: NodeStyle;
     parentId: string | null;
     isRoot: boolean;
+    thumbnail?: string;
+    imageRef?: string;
     image?: string;
     imageSize?: {
         width: number;
@@ -733,10 +796,11 @@ declare class Node_2 {
     };
     icon?: string;
     presentation: NodePresentationData;
-    constructor(id: string, topic: string, parentId?: string | null, isRoot?: boolean, image?: string, layoutSide?: 'left' | 'right', isFolded?: boolean, icon?: string, imageSize?: {
+    constructor(id: string, topic: string, parentId?: string | null, isRoot?: boolean, image?: string, // @deprecated
+    layoutSide?: 'left' | 'right', isFolded?: boolean, icon?: string, imageSize?: {
         width: number;
         height: number;
-    }, customWidth?: number);
+    }, customWidth?: number, thumbnail?: string, imageRef?: string);
     addChild(node: Node_2): void;
     insertChild(node: Node_2, index: number): void;
     removeChild(nodeId: string): void;
@@ -780,6 +844,7 @@ declare interface Renderer {
     };
     updateSelection(selectedNodeIds: Set<string>): void;
     getNodeElement(nodeId: string): HTMLElement | undefined;
+    zoomNode(nodeId: string): void;
 }
 
 declare class SearchService {
@@ -927,6 +992,12 @@ declare interface ThemeServiceDependencies {
     eventBus: IMindMapEventBus;
 }
 
+declare interface ThumbnailResult {
+    thumbnailBase64: string;
+    width: number;
+    height: number;
+}
+
 export declare class TypedEventEmitter<EventMap extends Record<string, any>> {
     private listeners;
     on<K extends keyof EventMap>(event: K, listener: (payload: EventMap[K]) => void): void;