@xom11/whiteboard 0.6.4 → 0.7.0

package/dist/index.d.mts

@@ -1,9 +1,19 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
-import { NonDeletedExcalidrawElement, ExcalidrawElement } from '@excalidraw/excalidraw/element/types';
+import { NonDeletedExcalidrawElement } from '@excalidraw/excalidraw/element/types';
 export { ExcalidrawElement, NonDeletedExcalidrawElement } from '@excalidraw/excalidraw/element/types';
 import { AppState, BinaryFiles } from '@excalidraw/excalidraw/types';
 export { AppState, BinaryFiles } from '@excalidraw/excalidraw/types';
-import { ReactNode, ForwardRefExoticComponent, RefAttributes } from 'react';
+import { S as StampType } from './types-CinstD7T.mjs';
+export { B as BaseStampCustomData } from './types-CinstD7T.mjs';
+import { GeometryCustomData } from './geometry-2d.mjs';
+export { geometryStamp, isGeometryCustomData } from './geometry-2d.mjs';
+import { LatexCustomData } from './latex.mjs';
+export { isLatexCustomData, latexStamp } from './latex.mjs';
+import { Geometry3DCustomData } from './geometry-3d.mjs';
+export { geometry3dStamp, isGeometry3DCustomData } from './geometry-3d.mjs';
+import { Graph2DCustomData } from './graph-2d.mjs';
+export { graph2dStamp, isGraph2DCustomData } from './graph-2d.mjs';
+import 'react';
 
 interface SyncableAppState {
     viewBackgroundColor: string;
@@ -18,156 +28,27 @@ interface ExcalidrawSceneSnapshot {
     appState: SyncableAppState;
 }
 
+/** Stamp ổn định, sẵn sàng production. */
+declare const STABLE_STAMPS: ReadonlyArray<StampType>;
+/** Stamp experimental — chưa ổn định cho production. Consumer phải opt-in. */
+declare const EXPERIMENTAL_STAMPS: ReadonlyArray<StampType>;
+/** Tất cả stamp (stable + experimental). Dùng khi consumer muốn full feature. */
+declare const ALL_STAMPS: ReadonlyArray<StampType>;
 /**
- * Kết quả trả về từ `restoreFileFromCustomData`. Chứa đủ thông tin để
- * consumer gọi `api.addFiles(...)`.
- */
-interface RestoredStampFile {
-    fileId: string;
-    dataURL: string;
-    mimeType: 'image/svg+xml' | 'image/png';
-}
-/**
- * Tối thiểu mọi custom data của stamp cần có. Các stamp cụ thể (geometry,
- * latex, ...) extend interface này với fields riêng.
- */
-interface BaseStampCustomData {
-    kind: string;
-    version: number;
-}
-/**
- * Props mà mỗi StampHost nhận từ Whiteboard. Host component tự
- * quản lý state nội bộ (panel ref, undo stack, displayMode...) — main view
- * chỉ điều phối show/hide.
- */
-interface StampHostProps {
-    api: any;
-    /**
-     * Element đang re-edit (double-click) hoặc null nếu đang tạo mới.
-     * Host tự parse customData để load state ban đầu.
-     */
-    editingElement: {
-        id: string;
-        customData: unknown;
-    } | null;
-    /** Đóng stamp panel (gọi sau khi insert hoặc khi user huỷ). */
-    onClose: () => void;
-    /** Dark theme flag. */
-    isDark: boolean;
-}
-/**
- * Imperative API mà main view truy cập qua ref:
- *   - tryInsert(): khi user click ra ngoài → auto-commit nếu valid.
- *     Trả về true nếu chèn thành công, false nếu chưa có nội dung.
- *   - hasContent(): có nội dung để chèn không.
- */
-interface StampHostHandle {
-    tryInsert(): boolean;
-    hasContent(): boolean;
-}
-type StampHostComponent = ForwardRefExoticComponent<StampHostProps & RefAttributes<StampHostHandle>>;
-/**
- * Định nghĩa 1 loại stamp. Mỗi stamp khai báo:
- *   - kind: unique string (khớp với customData.kind)
- *   - phím tắt + UI toolbar
- *   - cách nhận biết customData thuộc về stamp này (matchesCustomData)
- *   - cách re-render SVG từ customData (cho restore sau reload)
- *   - Host component: bọc trọn editor + left panel + insert logic
- *
- * Main view dispatch generic: `<stamp.Host ... />` — không cần biết kind.
- */
-interface StampType {
-    /** Unique kind. VD: 'geometry', 'latex'. Phải khớp với customData.kind. */
-    kind: string;
-    /** Phím tắt mở/đóng stamp (lowercase, 1 ký tự). VD: 'g', 'l'. */
-    shortcutKey: string;
-    /** Chữ hiển thị overlay góc dưới nút toolbar (e.g. "G"). */
-    toolbarLabel: string;
-    /** Tooltip + aria-label của nút toolbar. */
-    toolbarTitle: string;
-    /** Icon SVG (ReactNode) trong nút toolbar. */
-    toolbarIcon: ReactNode;
-    /** Test data-testid cho nút toolbar (optional). */
-    toolbarTestId?: string;
-    /** Type guard: customData có thuộc về stamp này không. */
-    matchesCustomData(data: unknown): boolean;
-    /**
-     * Re-render SVG từ customData. Dùng khi restore math-stamp file sau reload
-     * page (Excalidraw không persist binary file payload, chỉ giữ fileId trong
-     * element). SVG render với light palette (nét đậm) — Excalidraw tự đảo
-     * màu trong dark mode qua CSS filter.
-     */
-    renderSvgFromCustomData(data: unknown): Promise<string>;
-    /**
-     * Regenerate file SVG/PNG cho element thuộc stamp này khi reload từ persisted
-     * snapshot. Trả về `RestoredStampFile` để consumer gọi `api.addFiles`, hoặc
-     * `null` nếu element không cần file (vd stamp chỉ là text overlay).
-     *
-     * Khi method này có mặt, `restoreMissingStampFiles` sẽ ưu tiên gọi method
-     * này thay vì dùng `renderSvgFromCustomData`. Stamp tự chịu trách nhiệm lấy
-     * `fileId` từ element và render file.
-     */
-    restoreFileFromCustomData?: (element: ExcalidrawElement) => Promise<RestoredStampFile | null>;
-    /**
-     * Host component bọc toàn bộ UI editing (panel + left panel + insert
-     * handler). Whiteboard mount Host khi activeStamp khớp kind.
-     */
-    Host: StampHostComponent;
-}
-
-interface GeometryCustomData extends BaseStampCustomData {
-    kind: 'geometry';
-    version: 1;
-    jsonState: string;
-    svgWidth: number;
-    svgHeight: number;
-}
-declare function isGeometryCustomData(data: unknown): data is GeometryCustomData;
-declare const geometryStamp: StampType;
-
-interface LatexCustomData extends BaseStampCustomData {
-    kind: 'latex';
-    version: 1;
-    src: string;
-    displayMode: boolean;
-}
-declare function isLatexCustomData(data: unknown): data is LatexCustomData;
-declare const latexStamp: StampType;
-
-interface Geometry3DCustomData extends BaseStampCustomData {
-    kind: 'geometry3d';
-    version: 1;
-    jsonState: string;
-    svgWidth: number;
-    svgHeight: number;
-}
-declare function isGeometry3DCustomData(data: unknown): data is Geometry3DCustomData;
-
-declare const geometry3dStamp: StampType;
-
-interface Graph2DCustomData extends BaseStampCustomData {
-    kind: 'graph2d';
-    version: 1;
-    jsonState: string;
-    svgWidth: number;
-    svgHeight: number;
-}
-declare function isGraph2DCustomData(data: unknown): data is Graph2DCustomData;
-declare const graph2dStamp: StampType;
-
-/**
- * Set stamp mặc định dùng trong Whiteboard. Consumer có thể
- * truyền custom array để bật/tắt từng stamp hoặc đăng ký stamp mới.
+ * Set stamp mặc định cho Whiteboard. v0.7.0 trở đi = STABLE_STAMPS.
+ * Consumer muốn experimental: `<Whiteboard stamps={ALL_STAMPS} />` hoặc
+ * `[...DEFAULT_STAMPS, geometry3dStamp]`.
  *
  * Để thêm 1 stamp mới (vd chart):
- *   1. Tạo `src/stamp/registry/chart.tsx` với StampType object.
- *   2. Add vào DEFAULT_STAMPS ở dưới, HOẶC consumer truyền
- *      `<Whiteboard stamps={[...DEFAULT_STAMPS, chartStamp]} />`.
+ *   1. Tạo `src/stamps/chart/index.tsx` export `chartStamp: StampType`.
+ *   2. Import + add vào STABLE_STAMPS (production-ready) hoặc
+ *      EXPERIMENTAL_STAMPS (chưa ổn định) ở file này.
+ *   3. Re-export `chartStamp` từ `src/stamps/index.ts` + `src/index.ts`.
  */
 declare const DEFAULT_STAMPS: ReadonlyArray<StampType>;
 /** Tìm stamp tương ứng với customData của element. null nếu không match. */
 declare function findStampForCustomData(data: unknown, stamps?: ReadonlyArray<StampType>): StampType | null;
-/** isMathStamp version dựa trên registry — replace logic hardcode trong types.ts. */
+/** isMathStamp version dựa trên registry. */
 declare function isStampElement<T extends {
     customData?: unknown;
 }>(element: T, stamps?: ReadonlyArray<StampType>): boolean;
@@ -225,4 +106,4 @@ declare function restoreMissingStampFiles(api: any, elements: readonly ElementLi
 
 type StampCustomData = GeometryCustomData | LatexCustomData | Geometry3DCustomData | Graph2DCustomData;
 
-export { type BaseStampCustomData, DEFAULT_STAMPS, type ExcalidrawSceneSnapshot, type Geometry3DCustomData, type GeometryCustomData, type Graph2DCustomData, type LatexCustomData, type StampCustomData, type StampType, type SyncableAppState, Whiteboard, type WhiteboardProps, findStampForCustomData, geometry3dStamp, geometryStamp, graph2dStamp, isGeometry3DCustomData, isGeometryCustomData, isGraph2DCustomData, isLatexCustomData, isStampElement, latexStamp, pickSyncableAppState, restoreMissingStampFiles };
+export { ALL_STAMPS, DEFAULT_STAMPS, EXPERIMENTAL_STAMPS, type ExcalidrawSceneSnapshot, Geometry3DCustomData, GeometryCustomData, Graph2DCustomData, LatexCustomData, STABLE_STAMPS, type StampCustomData, StampType, type SyncableAppState, Whiteboard, type WhiteboardProps, findStampForCustomData, isStampElement, pickSyncableAppState, restoreMissingStampFiles };

package/dist/index.d.ts

@@ -1,9 +1,19 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
-import { NonDeletedExcalidrawElement, ExcalidrawElement } from '@excalidraw/excalidraw/element/types';
+import { NonDeletedExcalidrawElement } from '@excalidraw/excalidraw/element/types';
 export { ExcalidrawElement, NonDeletedExcalidrawElement } from '@excalidraw/excalidraw/element/types';
 import { AppState, BinaryFiles } from '@excalidraw/excalidraw/types';
 export { AppState, BinaryFiles } from '@excalidraw/excalidraw/types';
-import { ReactNode, ForwardRefExoticComponent, RefAttributes } from 'react';
+import { S as StampType } from './types-CinstD7T.js';
+export { B as BaseStampCustomData } from './types-CinstD7T.js';
+import { GeometryCustomData } from './geometry-2d.js';
+export { geometryStamp, isGeometryCustomData } from './geometry-2d.js';
+import { LatexCustomData } from './latex.js';
+export { isLatexCustomData, latexStamp } from './latex.js';
+import { Geometry3DCustomData } from './geometry-3d.js';
+export { geometry3dStamp, isGeometry3DCustomData } from './geometry-3d.js';
+import { Graph2DCustomData } from './graph-2d.js';
+export { graph2dStamp, isGraph2DCustomData } from './graph-2d.js';
+import 'react';
 
 interface SyncableAppState {
     viewBackgroundColor: string;
@@ -18,156 +28,27 @@ interface ExcalidrawSceneSnapshot {
     appState: SyncableAppState;
 }
 
+/** Stamp ổn định, sẵn sàng production. */
+declare const STABLE_STAMPS: ReadonlyArray<StampType>;
+/** Stamp experimental — chưa ổn định cho production. Consumer phải opt-in. */
+declare const EXPERIMENTAL_STAMPS: ReadonlyArray<StampType>;
+/** Tất cả stamp (stable + experimental). Dùng khi consumer muốn full feature. */
+declare const ALL_STAMPS: ReadonlyArray<StampType>;
 /**
- * Kết quả trả về từ `restoreFileFromCustomData`. Chứa đủ thông tin để
- * consumer gọi `api.addFiles(...)`.
- */
-interface RestoredStampFile {
-    fileId: string;
-    dataURL: string;
-    mimeType: 'image/svg+xml' | 'image/png';
-}
-/**
- * Tối thiểu mọi custom data của stamp cần có. Các stamp cụ thể (geometry,
- * latex, ...) extend interface này với fields riêng.
- */
-interface BaseStampCustomData {
-    kind: string;
-    version: number;
-}
-/**
- * Props mà mỗi StampHost nhận từ Whiteboard. Host component tự
- * quản lý state nội bộ (panel ref, undo stack, displayMode...) — main view
- * chỉ điều phối show/hide.
- */
-interface StampHostProps {
-    api: any;
-    /**
-     * Element đang re-edit (double-click) hoặc null nếu đang tạo mới.
-     * Host tự parse customData để load state ban đầu.
-     */
-    editingElement: {
-        id: string;
-        customData: unknown;
-    } | null;
-    /** Đóng stamp panel (gọi sau khi insert hoặc khi user huỷ). */
-    onClose: () => void;
-    /** Dark theme flag. */
-    isDark: boolean;
-}
-/**
- * Imperative API mà main view truy cập qua ref:
- *   - tryInsert(): khi user click ra ngoài → auto-commit nếu valid.
- *     Trả về true nếu chèn thành công, false nếu chưa có nội dung.
- *   - hasContent(): có nội dung để chèn không.
- */
-interface StampHostHandle {
-    tryInsert(): boolean;
-    hasContent(): boolean;
-}
-type StampHostComponent = ForwardRefExoticComponent<StampHostProps & RefAttributes<StampHostHandle>>;
-/**
- * Định nghĩa 1 loại stamp. Mỗi stamp khai báo:
- *   - kind: unique string (khớp với customData.kind)
- *   - phím tắt + UI toolbar
- *   - cách nhận biết customData thuộc về stamp này (matchesCustomData)
- *   - cách re-render SVG từ customData (cho restore sau reload)
- *   - Host component: bọc trọn editor + left panel + insert logic
- *
- * Main view dispatch generic: `<stamp.Host ... />` — không cần biết kind.
- */
-interface StampType {
-    /** Unique kind. VD: 'geometry', 'latex'. Phải khớp với customData.kind. */
-    kind: string;
-    /** Phím tắt mở/đóng stamp (lowercase, 1 ký tự). VD: 'g', 'l'. */
-    shortcutKey: string;
-    /** Chữ hiển thị overlay góc dưới nút toolbar (e.g. "G"). */
-    toolbarLabel: string;
-    /** Tooltip + aria-label của nút toolbar. */
-    toolbarTitle: string;
-    /** Icon SVG (ReactNode) trong nút toolbar. */
-    toolbarIcon: ReactNode;
-    /** Test data-testid cho nút toolbar (optional). */
-    toolbarTestId?: string;
-    /** Type guard: customData có thuộc về stamp này không. */
-    matchesCustomData(data: unknown): boolean;
-    /**
-     * Re-render SVG từ customData. Dùng khi restore math-stamp file sau reload
-     * page (Excalidraw không persist binary file payload, chỉ giữ fileId trong
-     * element). SVG render với light palette (nét đậm) — Excalidraw tự đảo
-     * màu trong dark mode qua CSS filter.
-     */
-    renderSvgFromCustomData(data: unknown): Promise<string>;
-    /**
-     * Regenerate file SVG/PNG cho element thuộc stamp này khi reload từ persisted
-     * snapshot. Trả về `RestoredStampFile` để consumer gọi `api.addFiles`, hoặc
-     * `null` nếu element không cần file (vd stamp chỉ là text overlay).
-     *
-     * Khi method này có mặt, `restoreMissingStampFiles` sẽ ưu tiên gọi method
-     * này thay vì dùng `renderSvgFromCustomData`. Stamp tự chịu trách nhiệm lấy
-     * `fileId` từ element và render file.
-     */
-    restoreFileFromCustomData?: (element: ExcalidrawElement) => Promise<RestoredStampFile | null>;
-    /**
-     * Host component bọc toàn bộ UI editing (panel + left panel + insert
-     * handler). Whiteboard mount Host khi activeStamp khớp kind.
-     */
-    Host: StampHostComponent;
-}
-
-interface GeometryCustomData extends BaseStampCustomData {
-    kind: 'geometry';
-    version: 1;
-    jsonState: string;
-    svgWidth: number;
-    svgHeight: number;
-}
-declare function isGeometryCustomData(data: unknown): data is GeometryCustomData;
-declare const geometryStamp: StampType;
-
-interface LatexCustomData extends BaseStampCustomData {
-    kind: 'latex';
-    version: 1;
-    src: string;
-    displayMode: boolean;
-}
-declare function isLatexCustomData(data: unknown): data is LatexCustomData;
-declare const latexStamp: StampType;
-
-interface Geometry3DCustomData extends BaseStampCustomData {
-    kind: 'geometry3d';
-    version: 1;
-    jsonState: string;
-    svgWidth: number;
-    svgHeight: number;
-}
-declare function isGeometry3DCustomData(data: unknown): data is Geometry3DCustomData;
-
-declare const geometry3dStamp: StampType;
-
-interface Graph2DCustomData extends BaseStampCustomData {
-    kind: 'graph2d';
-    version: 1;
-    jsonState: string;
-    svgWidth: number;
-    svgHeight: number;
-}
-declare function isGraph2DCustomData(data: unknown): data is Graph2DCustomData;
-declare const graph2dStamp: StampType;
-
-/**
- * Set stamp mặc định dùng trong Whiteboard. Consumer có thể
- * truyền custom array để bật/tắt từng stamp hoặc đăng ký stamp mới.
+ * Set stamp mặc định cho Whiteboard. v0.7.0 trở đi = STABLE_STAMPS.
+ * Consumer muốn experimental: `<Whiteboard stamps={ALL_STAMPS} />` hoặc
+ * `[...DEFAULT_STAMPS, geometry3dStamp]`.
  *
  * Để thêm 1 stamp mới (vd chart):
- *   1. Tạo `src/stamp/registry/chart.tsx` với StampType object.
- *   2. Add vào DEFAULT_STAMPS ở dưới, HOẶC consumer truyền
- *      `<Whiteboard stamps={[...DEFAULT_STAMPS, chartStamp]} />`.
+ *   1. Tạo `src/stamps/chart/index.tsx` export `chartStamp: StampType`.
+ *   2. Import + add vào STABLE_STAMPS (production-ready) hoặc
+ *      EXPERIMENTAL_STAMPS (chưa ổn định) ở file này.
+ *   3. Re-export `chartStamp` từ `src/stamps/index.ts` + `src/index.ts`.
  */
 declare const DEFAULT_STAMPS: ReadonlyArray<StampType>;
 /** Tìm stamp tương ứng với customData của element. null nếu không match. */
 declare function findStampForCustomData(data: unknown, stamps?: ReadonlyArray<StampType>): StampType | null;
-/** isMathStamp version dựa trên registry — replace logic hardcode trong types.ts. */
+/** isMathStamp version dựa trên registry. */
 declare function isStampElement<T extends {
     customData?: unknown;
 }>(element: T, stamps?: ReadonlyArray<StampType>): boolean;
@@ -225,4 +106,4 @@ declare function restoreMissingStampFiles(api: any, elements: readonly ElementLi
 
 type StampCustomData = GeometryCustomData | LatexCustomData | Geometry3DCustomData | Graph2DCustomData;
 
-export { type BaseStampCustomData, DEFAULT_STAMPS, type ExcalidrawSceneSnapshot, type Geometry3DCustomData, type GeometryCustomData, type Graph2DCustomData, type LatexCustomData, type StampCustomData, type StampType, type SyncableAppState, Whiteboard, type WhiteboardProps, findStampForCustomData, geometry3dStamp, geometryStamp, graph2dStamp, isGeometry3DCustomData, isGeometryCustomData, isGraph2DCustomData, isLatexCustomData, isStampElement, latexStamp, pickSyncableAppState, restoreMissingStampFiles };
+export { ALL_STAMPS, DEFAULT_STAMPS, EXPERIMENTAL_STAMPS, type ExcalidrawSceneSnapshot, Geometry3DCustomData, GeometryCustomData, Graph2DCustomData, LatexCustomData, STABLE_STAMPS, type StampCustomData, StampType, type SyncableAppState, Whiteboard, type WhiteboardProps, findStampForCustomData, isStampElement, pickSyncableAppState, restoreMissingStampFiles };