@umbraci/jsmind 0.9.12 → 0.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@umbraci/jsmind",
-    "version": "0.9.12",
+    "version": "0.10.0",
     "description": "jsMind is a pure javascript library for mindmap, it base on html5 canvas. jsMind was released under BSD license, you can embed it in any project, if only you observe the license.",
     "main": "lib/jsmind.js",
     "module": "es/jsmind.js",

package/types/generated/jsmind.d.ts

@@ -223,15 +223,16 @@ declare class jsMind {
      * Add multiple nodes to the mind map with optimized performance.
      * Supports standard jsMind formats: node_tree, node_array, and freemind with nested children structure.
      * @param {string | import('./jsmind.node.js').Node} parent_node - Parent node for all new nodes
-     * @param {Array<{id: string, topic: string, data?: Record<string, any>, direction?: ('left'|'center'|'right'|'-1'|'0'|'1'|number), children?: Array}>} nodes_data - Array of node data objects with same format as add_node
+     * @param {Array<{id?: string, topic?: string, data?: Record<string, any>, direction?: ('left'|'center'|'right'|'-1'|'0'|'1'|number), children?: Array, [key: string]: any}>} nodes_data - Array of node data objects with same format as add_node
      * @returns {Array<import('./jsmind.node.js').Node|null>} Array of created nodes (flattened from all levels)
      */
     add_nodes(parent_node: string | import("./jsmind.node.js").Node, nodes_data: Array<{
-        id: string;
-        topic: string;
+        id?: string;
+        topic?: string;
         data?: Record<string, any>;
         direction?: ("left" | "center" | "right" | "-1" | "0" | "1" | number);
         children?: any[];
+        [key: string]: any;
     }>): Array<import("./jsmind.node.js").Node | null>;
     /**
      * Recursively add nodes using existing format processors.

package/types/generated/jsmind.format.d.ts

@@ -60,14 +60,20 @@ export type MindMapMeta = {
 };
 /**
  * Node tree data item
+ *
+ * Note: When using custom fieldNames configuration, the actual property names
+ * in your data may differ from these type definitions. For example, if you
+ * configure `fieldNames: { topic: 'name' }`, your data should use 'name'
+ * instead of 'topic'. The types shown here represent the default field names.
  */
 export type NodeTreeData = {
-    id: string;
-    topic: string;
+    id?: string;
+    topic?: string;
     data?: Record<string, any>;
     direction?: (number | string);
     expanded?: boolean;
     children?: NodeTreeData[];
+    [key: string]: any;
 };
 /**
  * Node tree formatted payload
@@ -79,15 +85,22 @@ export type NodeTreeFormat = {
 };
 /**
  * Node array data item
+ *
+ * Note: When using custom fieldNames configuration, the actual property names
+ * in your data may differ from these type definitions. For example, if you
+ * configure `fieldNames: { topic: 'name', parentid: 'parent' }`, your data
+ * should use 'name' and 'parent' instead of 'topic' and 'parentid'. The types
+ * shown here represent the default field names.
  */
 export type NodeArrayItem = {
-    id: string;
-    topic: string;
+    id?: string;
+    topic?: string;
     parentid?: string;
     data?: Record<string, any>;
     direction?: (number | string);
     expanded?: boolean;
     isroot?: boolean;
+    [key: string]: any;
 };
 /**
  * Node array formatted payload

package/types/generated/jsmind.option.d.ts

@@ -60,5 +60,14 @@ export type JsMindRuntimeOptions = {
         mapping?: Record<string, number | number[]>;
         id_generator?: () => string;
     };
+    fieldNames?: {
+        id?: string;
+        topic?: string;
+        children?: string;
+        parentid?: string;
+        isroot?: string;
+        direction?: string;
+        expanded?: string;
+    };
     plugin?: Record<string, object>;
 };

package/types/generated/plugins/history/history-diff.d.ts

@@ -1,55 +1,301 @@
 /**
- * Flatten a NodeTreeFormat/NodeTreeData by id
- * @param {NodeTreeFormat|NodeTreeData} tree
- * @param {{ fields?: string[], includeStructure?: boolean }=} opts
- * @returns {Record<string, any>}
+ * Flatten a tree into a Map of nodes keyed by id.
+ *
+ * Note: When using custom fieldNames, make sure to pass the correct field names in opts.fields.
+ * For example, if you configured fieldNames: { topic: 'name' }, you should pass fields: ['name', 'data', 'id'].
+ *
+ * @param {NodeTreeFormat|NodeTreeData} tree - The tree to flatten
+ * @param {FlattenOptions} [opts] - Flatten options
+ * @returns {Map<string, FlatNode>} Map of node id -> flattened node object
+ *
+ * @example
+ * // With default fieldNames
+ * const tree = { data: { id: 'root', topic: 'Root', children: [...] } };
+ * const flatMap = flatten(tree);
+ * const rootNode = flatMap.get('root'); // { id: 'root', topic: 'Root', data: {...}, _parentid: null, _order: 0 }
+ *
+ * @example
+ * // With custom fieldNames: { topic: 'name' }
+ * const tree = { data: { id: 'root', name: 'Root', children: [...] } };
+ * const flatMap = flatten(tree, { fields: ['name', 'data', 'id'] });
+ * const rootNode = flatMap.get('root'); // { id: 'root', name: 'Root', data: {...}, _parentid: null, _order: 0 }
  */
-export function flatten(tree: NodeTreeFormat | NodeTreeData, opts?: {
-    fields?: string[];
-    includeStructure?: boolean;
-} | undefined): Record<string, any>;
+export function flatten(tree: NodeTreeFormat | NodeTreeData, opts?: FlattenOptions): Map<string, FlatNode>;
 /**
- * Compute diff between two snapshots
- * @param {NodeTreeFormat|NodeTreeData} a
- * @param {NodeTreeFormat|NodeTreeData} b
- * @param {{ fields?: string[], includeStructure?: boolean, maxSize?: number }=} opts
- *   - fields: 可选。指定要参与 diff 的节点属性列表；默认比较所有属性（除 children）。与 includeStructure 组合使用时可同时比较 _parentid/_order。
- * @returns {{
- *   created: any[],
- *   updated: { id:string, before:any, after:any, changes: { key:string, before:any, after:any }[] }[],
- *   deleted: any[],
- *   truncated: boolean
- * }}
+ * Compute diff between two snapshots.
+ *
+ * Note: When using custom fieldNames, make sure to pass the correct field names in opts.fields.
+ * For example, if you configured fieldNames: { topic: 'name' }, you should pass fields: ['name', 'data', 'id'].
+ * When using jm.history.diff(), this is automatically handled for you.
+ *
+ * @param {NodeTreeFormat|NodeTreeData} a - First snapshot (before)
+ * @param {NodeTreeFormat|NodeTreeData} b - Second snapshot (after)
+ * @param {DiffOptions} [opts] - Diff options
+ * @returns {DiffResult} Diff result with created, updated, deleted nodes, and optionally categorized updates
+ *
+ * @example
+ * // Basic usage with default fieldNames
+ * const result = diff(snapshot1, snapshot2);
+ * console.log(result.created); // Newly created nodes
+ * console.log(result.updated); // Updated nodes with changes
+ * console.log(result.deleted); // Deleted nodes
+ *
+ * @example
+ * // With categorization
+ * const result = diff(snapshot1, snapshot2, { categorize: true });
+ * console.log(result.moved); // Nodes that were only moved
+ * console.log(result.modified); // Nodes that were only modified
+ * console.log(result.movedAndModified); // Nodes that were both moved and modified
+ *
+ * @example
+ * // With custom fieldNames: { topic: 'name' }
+ * const result = diff(snapshot1, snapshot2, { fields: ['name', 'data', 'id'] });
+ * // Now the diff will correctly detect changes in the 'name' field
+ *
+ * @example
+ * // Using jm.history.diff() (recommended - automatically handles fieldNames)
+ * const before = jm.get_data('node_tree');
+ * // ... make changes ...
+ * const after = jm.get_data('node_tree');
+ * const result = jm.history.diff(before, after);
+ * // fieldNames are automatically applied, no need to specify fields manually
  */
-export function diff(a: NodeTreeFormat | NodeTreeData, b: NodeTreeFormat | NodeTreeData, opts?: {
-    fields?: string[];
-    includeStructure?: boolean;
-    maxSize?: number;
-} | undefined): {
-    created: any[];
-    updated: {
-        id: string;
-        before: any;
-        after: any;
-        changes: {
-            key: string;
-            before: any;
-            after: any;
-        }[];
-    }[];
-    deleted: any[];
-    truncated: boolean;
-};
+export function diff(a: NodeTreeFormat | NodeTreeData, b: NodeTreeFormat | NodeTreeData, opts?: DiffOptions): DiffResult;
 export type NodeTreeFormat = {
     meta?: any;
     format?: "node_tree";
     data: NodeTreeData;
 };
 export type NodeTreeData = {
-    id: string;
+    id?: string;
     topic?: string;
     expanded?: boolean;
     direction?: "left" | "right";
     data?: Record<string, any>;
     children?: NodeTreeData[];
+    [key: string]: any;
+};
+export type FlatNode = {
+    /**
+     * - Node ID
+     */
+    id: string;
+    /**
+     * - Node topic/title
+     */
+    topic?: string;
+    /**
+     * - Node data
+     */
+    data?: Record<string, any>;
+    /**
+     * - Parent node ID (structure field)
+     */
+    _parentid?: string | null;
+    /**
+     * - Node order in parent's children (structure field)
+     */
+    _order?: number;
+};
+export type ChangeDetail = {
+    /**
+     * - The field name that changed
+     */
+    key: string;
+    /**
+     * - Value before change
+     */
+    before: any;
+    /**
+     * - Value after change
+     */
+    after: any;
+};
+export type UpdatedNode = {
+    /**
+     * - Node ID
+     */
+    id: string;
+    /**
+     * - Node state before change
+     */
+    before: FlatNode;
+    /**
+     * - Node state after change
+     */
+    after: FlatNode;
+    /**
+     * - Array of field changes
+     */
+    changes: ChangeDetail[];
+};
+export type MoveInfo = {
+    /**
+     * - Whether parent changed
+     */
+    parentChanged: boolean;
+    /**
+     * - Whether order changed
+     */
+    orderChanged: boolean;
+    /**
+     * - Original parent ID
+     */
+    fromParent: string | null;
+    /**
+     * - New parent ID
+     */
+    toParent: string | null;
+    /**
+     * - Original order
+     */
+    fromOrder: number;
+    /**
+     * - New order
+     */
+    toOrder: number;
+};
+export type MovedNode = {
+    /**
+     * - Node ID
+     */
+    id: string;
+    /**
+     * - Node state before move
+     */
+    before: FlatNode;
+    /**
+     * - Node state after move
+     */
+    after: FlatNode;
+    /**
+     * - Movement details
+     */
+    moveInfo: MoveInfo;
+};
+export type ModifiedNode = {
+    /**
+     * - Node ID
+     */
+    id: string;
+    /**
+     * - Node state before modification
+     */
+    before: FlatNode;
+    /**
+     * - Node state after modification
+     */
+    after: FlatNode;
+    /**
+     * - Array of field changes (excluding structure fields)
+     */
+    changes: ChangeDetail[];
+};
+export type MovedAndModifiedNode = {
+    /**
+     * - Node ID
+     */
+    id: string;
+    /**
+     * - Node state before change
+     */
+    before: FlatNode;
+    /**
+     * - Node state after change
+     */
+    after: FlatNode;
+    /**
+     * - Array of field changes (excluding structure fields)
+     */
+    changes: ChangeDetail[];
+    /**
+     * - Movement details
+     */
+    moveInfo: MoveInfo;
+};
+export type DiffResult = {
+    /**
+     * - Newly created nodes
+     */
+    created: FlatNode[];
+    /**
+     * - Updated nodes (all changes)
+     */
+    updated: UpdatedNode[];
+    /**
+     * - Deleted nodes
+     */
+    deleted: FlatNode[];
+    /**
+     * - Whether results were truncated due to maxSize
+     */
+    truncated: boolean;
+    /**
+     * - Nodes that were only moved (when categorize=true)
+     */
+    moved?: MovedNode[];
+    /**
+     * - Nodes that were only modified (when categorize=true)
+     */
+    modified?: ModifiedNode[];
+    /**
+     * - Nodes that were both moved and modified (when categorize=true)
+     */
+    movedAndModified?: MovedAndModifiedNode[];
+};
+export type FlattenOptions = {
+    /**
+     * - Array of field names to include. Defaults to ['topic', 'data', 'id'].
+     *     When using custom fieldNames (e.g., { id: 'key', topic: 'name' }), this should be
+     *     ['name', 'data', 'key'] to match the actual field names in the data.
+     */
+    fields?: string[];
+    /**
+     * - The field name to use as the node ID. Defaults to 'id'.
+     *     When using custom fieldNames (e.g., { id: 'key' }), this should be 'key'.
+     */
+    idKey?: string;
+    /**
+     * - The field name to use for children array. Defaults to 'children'.
+     *     When using custom fieldNames (e.g., { children: 'items' }), this should be 'items'.
+     */
+    childrenKey?: string;
+    /**
+     * - Whether to include _parentid and _order. Defaults to true
+     */
+    includeStructure?: boolean;
+};
+export type DiffOptions = {
+    /**
+     * - Array of field names to compare. Defaults to ['topic', 'data', 'id'].
+     *     When using custom fieldNames (e.g., { id: 'key', topic: 'name' }), this should be
+     *     ['name', 'data', 'key'] to match the actual field names in the data.
+     *     Note: When using jm.history.diff(), this is automatically handled based
+     *     on the configured fieldNames, so you don't need to specify it manually.
+     */
+    fields?: string[];
+    /**
+     * - The field name to use as the node ID. Defaults to 'id'.
+     *     When using custom fieldNames (e.g., { id: 'key' }), this should be 'key'.
+     *     Note: When using jm.history.diff(), this is automatically handled.
+     */
+    idKey?: string;
+    /**
+     * - The field name to use for children array. Defaults to 'children'.
+     *     When using custom fieldNames (e.g., { children: 'items' }), this should be 'items'.
+     *     Note: When using jm.history.diff(), this is automatically handled.
+     */
+    childrenKey?: string;
+    /**
+     * - Whether to include _parentid and _order in comparison. Defaults to true
+     */
+    includeStructure?: boolean;
+    /**
+     * - Maximum number of diff results. Defaults to 5000
+     */
+    maxSize?: number;
+    /**
+     * - Whether to categorize updates into moved/modified/movedAndModified. Defaults to false
+     */
+    categorize?: boolean;
 };

package/types/generated/plugins/history/jsmind.history.d.ts

@@ -1,5 +1,7 @@
 export default HistoryPlugin;
 export type JsMind = import("../../jsmind.js").default;
+export type DiffResult = import("./history-diff.js").DiffResult;
+export type DiffOptions = import("./history-diff.js").DiffOptions;
 /**
  * HistoryPlugin skeleton (Task 1)
  */
@@ -55,6 +57,7 @@ declare class HistoryCore {
     _pending: boolean;
     _pendingMeta: any;
     _lastSig: any;
+    _lastRootId: any;
     add(reason: string, meta: any): void;
     pause(): void;
     resume(flush?: boolean): void;