feat: improve TypeScript type definitions with optional parameters (#665)

* feat: improve TypeScript type definitions with optional parameters

- Convert required configuration fields to optional in JsMindRuntimeOptions
- Add support for 'visible' value in node_overflow option
- Update type definitions to match official documentation examples
- Enhance test coverage for optional parameters and new type features
- Improve API flexibility by making most options optional except container
- Update JSDoc comments to reflect optional parameter changes

* docs: fix JSDoc direction parameter types to match Direction.of() implementation

- Update direction parameter JSDoc in add_node, insert_node_before, insert_node_after, move_node functions
- Add support for numeric strings ('-1', '0', '1') and numbers (-1, 0, 1) in addition to string values
- Document that Direction.of() function supports multiple input types as shown in jsmind.common.js
- Improve API documentation accuracy and developer experience

Author: UmbraCi

.gitignore

@@ -3,3 +3,5 @@ node_modules/
 es6/*.js
 es6/*.js.map
 types/generated/
+
+.augment/

src/index.ts

@@ -5,7 +5,7 @@ export { default } from './jsmind';
 export { Node } from './jsmind.node';
 export { Mind } from './jsmind.mind';
 
-// Export strict options and meta types from generated
+// Export user-facing options type - now with proper optional fields
 export type { JsMindRuntimeOptions as JsMindOptions } from './jsmind.option';
 export type {
     MindMapMeta,

src/jsmind.js

@@ -143,7 +143,7 @@ export default class jsMind {
     }
     /**
      * Set theme name.
-     * @param {string|null} theme
+     * @param {string|null=} theme
      */
     set_theme(theme) {
         var theme_old = this.options.theme;
@@ -334,7 +334,10 @@ export default class jsMind {
         this.layout.collapse_all();
         this.view.relayout();
     }
-    /** @param {number} depth */
+    /**
+     * Expand nodes up to a specified depth level.
+     * @param {number} depth
+     */
     expand_to_depth(depth) {
         this.layout.expand_to_depth(depth);
         this.view.relayout();
@@ -412,12 +415,12 @@ export default class jsMind {
         return this.mind.get_node(node);
     }
     /**
-     * Add a node under parent.
+     * Add a new node to the mind map.
      * @param {string | import('./jsmind.node.js').Node} parent_node
      * @param {string} node_id
      * @param {string} topic
      * @param {Record<string, any>=} data
-     * @param {number=} direction
+     * @param {('left'|'center'|'right'|'-1'|'0'|'1'|number)=} direction - Direction for node placement. Supports string values ('left', 'center', 'right'), numeric strings ('-1', '0', '1'), and numbers (-1, 0, 1)
      * @returns {import('./jsmind.node.js').Node|null}
      */
     add_node(parent_node, node_id, topic, data, direction) {
@@ -452,7 +455,7 @@ export default class jsMind {
      * @param {string} node_id
      * @param {string} topic
      * @param {Record<string, any>=} data
-     * @param {number=} direction
+     * @param {('left'|'center'|'right'|'-1'|'0'|'1'|number)=} direction - Direction for node placement. Supports string values ('left', 'center', 'right'), numeric strings ('-1', '0', '1'), and numbers (-1, 0, 1)
      * @returns {import('./jsmind.node.js').Node|null}
      */
     insert_node_before(node_before, node_id, topic, data, direction) {
@@ -485,7 +488,7 @@ export default class jsMind {
      * @param {string} node_id
      * @param {string} topic
      * @param {Record<string, any>=} data
-     * @param {number=} direction
+     * @param {('left'|'center'|'right'|'-1'|'0'|'1'|number)=} direction - Direction for node placement. Supports string values ('left', 'center', 'right'), numeric strings ('-1', '0', '1'), and numbers (-1, 0, 1)
      * @returns {import('./jsmind.node.js').Node|null}
      */
     insert_node_after(node_after, node_id, topic, data, direction) {
@@ -552,7 +555,11 @@ export default class jsMind {
             return false;
         }
     }
-    /** @param {string} node_id @param {string} topic */
+    /**
+     * Update the topic (text content) of a node.
+     * @param {string} node_id
+     * @param {string} topic
+     */
     update_node(node_id, topic) {
         if (this.get_editable()) {
             if (_util.text.is_empty(topic)) {
@@ -584,9 +591,9 @@ export default class jsMind {
     /**
      * Move a node and optionally change direction.
      * @param {string} node_id
-     * @param {string=} before_id
+     * @param {string=} before_id - The ID of the node before which to place the moved node. Special values: "_first_", "_last_"
      * @param {string=} parent_id
-     * @param {number=} direction
+     * @param {('left'|'center'|'right'|'-1'|'0'|'1'|number)=} direction - Direction for node placement. Supports string values ('left', 'center', 'right'), numeric strings ('-1', '0', '1'), and numbers (-1, 0, 1). Only effective for second-level nodes (children of root). If not provided, direction will be determined automatically.
      */
     move_node(node_id, before_id, parent_id, direction) {
         if (this.get_editable()) {
@@ -648,7 +655,10 @@ export default class jsMind {
     is_node_visible(node) {
         return this.layout.is_visible(node);
     }
-    /** @param {string | import('./jsmind.node.js').Node} node */
+    /**
+     * Scroll the mind map to center the specified node.
+     * @param {string | import('./jsmind.node.js').Node} node
+     */
     scroll_node_to_center(node) {
         if (!Node.is_node(node)) {
             var the_node = this.get_node(node);
@@ -740,6 +750,7 @@ export default class jsMind {
         return n;
     }
     /**
+     * Set background and foreground colors for a node.
      * @param {string} node_id
      * @param {string=} bg_color
      * @param {string=} fg_color
@@ -763,6 +774,7 @@ export default class jsMind {
         }
     }
     /**
+     * Set font style for a node.
      * @param {string} node_id
      * @param {number=} size
      * @param {string=} weight
@@ -793,8 +805,9 @@ export default class jsMind {
         }
     }
     /**
+     * Set background image for a node.
      * @param {string} node_id
-     * @param {string} image
+     * @param {string=} image
      * @param {number=} width
      * @param {number=} height
      * @param {number=} rotation

src/jsmind.mind.js

@@ -63,7 +63,7 @@ export class Mind {
      * @param {string} node_id
      * @param {string} topic
      * @param {Record<string, any>=} data
-     * @param {number=} direction
+     * @param {('left'|'center'|'right'|'-1'|'0'|'1'|number)=} direction - Direction for node placement. Supports string values ('left', 'center', 'right'), numeric strings ('-1', '0', '1'), and numbers (-1, 0, 1)
      * @param {boolean=} expanded
      * @param {number=} idx
      * @returns {Node | null}
@@ -102,7 +102,7 @@ export class Mind {
      * @param {string} node_id
      * @param {string} topic
      * @param {Record<string, any>=} data
-     * @param {number=} direction
+     * @param {('left'|'center'|'right'|'-1'|'0'|'1'|number)=} direction - Direction for node placement. Supports string values ('left', 'center', 'right'), numeric strings ('-1', '0', '1'), and numbers (-1, 0, 1)
      * @returns {Node | null}
      */
     insert_node_before(node_before, node_id, topic, data, direction) {
@@ -144,7 +144,7 @@ export class Mind {
      * @param {string} node_id
      * @param {string} topic
      * @param {Record<string, any>=} data
-     * @param {number=} direction
+     * @param {('left'|'center'|'right'|'-1'|'0'|'1'|number)=} direction - Direction for node placement. Supports string values ('left', 'center', 'right'), numeric strings ('-1', '0', '1'), and numbers (-1, 0, 1)
      * @returns {Node | null}
      */
     insert_node_after(node_after, node_id, topic, data, direction) {
@@ -184,9 +184,9 @@ export class Mind {
     /**
      * Move a node to new parent/position.
      * @param {Node} node
-     * @param {string=} before_id
+     * @param {string=} before_id - The ID of the node before which to place the moved node. Special values: "_first_", "_last_"
      * @param {string=} parent_id
-     * @param {number=} direction
+     * @param {('left'|'center'|'right'|'-1'|'0'|'1'|number)=} direction - Direction for node placement. Supports string values ('left', 'center', 'right'), numeric strings ('-1', '0', '1'), and numbers (-1, 0, 1)
      * @returns {Node | null}
      */
     move_node(node, before_id, parent_id, direction) {
@@ -202,7 +202,7 @@ export class Mind {
     /**
      * Propagate direction to descendants.
      * @param {Node} node
-     * @param {number=} direction
+     * @param {('left'|'center'|'right'|'-1'|'0'|'1'|number)=} direction - Direction for node placement. Supports string values ('left', 'center', 'right'), numeric strings ('-1', '0', '1'), and numbers (-1, 0, 1)
      */
     _flow_node_direction(node, direction) {
         if (typeof direction === 'undefined') {
@@ -248,7 +248,7 @@ export class Mind {
      * @param {Node} node
      * @param {string} before_id
      * @param {string} parent_id
-     * @param {number=} direction
+     * @param {('left'|'center'|'right'|'-1'|'0'|'1'|number)=} direction - Direction for node placement. Supports string values ('left', 'center', 'right'), numeric strings ('-1', '0', '1'), and numbers (-1, 0, 1)
      * @returns {Node | null}
      */
     _move_node(node, before_id, parent_id, direction) {

src/jsmind.option.js

@@ -11,31 +11,31 @@ import { util } from './jsmind.util.js';
 /**
  * @typedef {{
  *  container: string|HTMLElement,
- *  editable: boolean,
- *  theme: (string|null),
- *  mode: ('full'|'side'),
- *  support_html: boolean,
- *  log_level: 'debug'|'info'|'warn'|'error'|'disable',
- *  view: {
- *    engine: 'canvas'|'svg',
- *    enable_device_pixel_ratio: boolean,
- *    hmargin: number,
- *    vmargin: number,
- *    line_width: number,
- *    line_color: string,
- *    line_style: 'curved'|'straight',
+ *  editable?: boolean,
+ *  theme?: (string|null),
+ *  mode?: ('full'|'side'),
+ *  support_html?: boolean,
+ *  log_level?: 'debug'|'info'|'warn'|'error'|'disable',
+ *  view?: {
+ *    engine?: 'canvas'|'svg',
+ *    enable_device_pixel_ratio?: boolean,
+ *    hmargin?: number,
+ *    vmargin?: number,
+ *    line_width?: number,
+ *    line_color?: string,
+ *    line_style?: 'curved'|'straight',
  *    custom_line_render?: (this: object, arg:{ ctx: CanvasRenderingContext2D|SVGPathElement, start_point:{x:number,y:number}, end_point:{x:number,y:number} })=>void,
- *    draggable: boolean,
- *    hide_scrollbars_when_draggable: boolean,
- *    node_overflow: 'hidden'|'wrap',
- *    zoom: { min:number, max:number, step:number, mask_key:number },
- *    custom_node_render: (null|((jm: import('./jsmind.js').default, ele: HTMLElement, node: import('./jsmind.node.js').Node)=>void)),
- *    expander_style: 'char'|'number'
+ *    draggable?: boolean,
+ *    hide_scrollbars_when_draggable?: boolean,
+ *    node_overflow?: 'hidden'|'wrap'|'visible',
+ *    zoom?: { min?:number, max?:number, step?:number, mask_key?:number },
+ *    custom_node_render?: (null|((jm: import('./jsmind.js').default, ele: HTMLElement, node: import('./jsmind.node.js').Node)=>void)),
+ *    expander_style?: 'char'|'number'
  *  },
- *  layout: { hspace:number, vspace:number, pspace:number, cousin_space:number },
- *  default_event_handle: { enable_mousedown_handle:boolean, enable_click_handle:boolean, enable_dblclick_handle:boolean, enable_mousewheel_handle:boolean },
- *  shortcut: { enable:boolean, handles: Record<string,(jm: import('./jsmind.js').default, e: KeyboardEvent)=>void>, mapping: Record<string, number|number[]>, id_generator?: ()=>string },
- *  plugin: Record<string, object>
+ *  layout?: { hspace?:number, vspace?:number, pspace?:number, cousin_space?:number },
+ *  default_event_handle?: { enable_mousedown_handle?:boolean, enable_click_handle?:boolean, enable_dblclick_handle?:boolean, enable_mousewheel_handle?:boolean },
+ *  shortcut?: { enable?:boolean, handles?: Record<string,(jm: import('./jsmind.js').default, e: KeyboardEvent)=>void>, mapping?: Record<string, number|number[]>, id_generator?: ()=>string },
+ *  plugin?: Record<string, object>
  * }} JsMindRuntimeOptions
  */
 /** @type {JsMindRuntimeOptions} */
@@ -99,7 +99,7 @@ const default_options = {
 
 /**
  * Merge user options with defaults. Throws if container missing.
- * @param {Partial<JsMindRuntimeOptions>} options
+ * @param {JsMindRuntimeOptions} options
  * @returns {JsMindRuntimeOptions}
  */
 export function merge_option(options) {