@umbraci/jsmind 0.9.13 → 0.10.1

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@umbraci/jsmind",
-    "version": "0.9.13",
+    "version": "0.10.1",
     "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

@@ -222,8 +222,27 @@ 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.
+     *
+     * **Field Names Support**: This method now supports custom field names configured via `options.fieldNames`.
+     * You can use your own property names (e.g., 'name' instead of 'topic', 'key' instead of 'id').
+     *
+     * @example
+     * // Using standard field names
+     * jm.add_nodes('parent_id', [
+     *     { id: 'node1', topic: 'Node 1', children: [...] }
+     * ]);
+     *
+     * @example
+     * // Using custom field names (requires fieldNames configuration)
+     * var jm = new jsMind({
+     *     fieldNames: { id: 'key', topic: 'name', children: 'items' }
+     * });
+     * jm.add_nodes('parent_id', [
+     *     { key: 'node1', name: 'Node 1', items: [...] }
+     * ]);
+     *
      * @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, [key: string]: any}>} 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. Field names can be customized via options.fieldNames.
      * @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<{
@@ -236,14 +255,16 @@ declare class jsMind {
     }>): Array<import("./jsmind.node.js").Node | null>;
     /**
      * Recursively add nodes using existing format processors.
+     * Supports custom field names via options.fieldNames configuration.
      * @private
      * @param {import('./jsmind.node.js').Node} parent_node
-     * @param {object} node_data
+     * @param {object} node_data - Node data object with standard or custom field names
      * @returns {Array<import('./jsmind.node.js').Node|null>}
      */
     private _add_nodes_recursive;
     /**
      * Count expected nodes recursively.
+     * Supports custom field names via options.fieldNames configuration.
      * @private
      * @param {Array} nodes_data
      * @returns {number}

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

@@ -1,22 +1,40 @@
 /**
  * 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?: FlattenOptions): Map<string, FlatNode>;
 /**
- * Compute diff between two snapshots
+ * 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
+ * // 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
@@ -30,8 +48,17 @@ export function flatten(tree: NodeTreeFormat | NodeTreeData, opts?: FlattenOptio
  * console.log(result.movedAndModified); // Nodes that were both moved and modified
  *
  * @example
- * // Custom fields
- * const result = diff(snapshot1, snapshot2, { fields: ['id', 'topic'] });
+ * // 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?: DiffOptions): DiffResult;
 export type NodeTreeFormat = {
@@ -218,9 +245,21 @@ export type DiffResult = {
 };
 export type FlattenOptions = {
     /**
-     * - Array of field names to include. Defaults to ['topic', 'data', 'id']
+     * - 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
      */
@@ -228,9 +267,25 @@ export type FlattenOptions = {
 };
 export type DiffOptions = {
     /**
-     * - Array of field names to compare. Defaults to ['topic', 'data', 'id']
+     * - 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
      */

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)
  */