smsmslib 1.0.59 → 1.0.65

package/javascr/av_controller/AvControllerState_t.js

@@ -9,7 +9,7 @@
  * pattern, facilitating synchronization between the media element and 
  * its associated UI components.
  *
- * @module src/av_controller/AvControllerState_t
+ * @module javascr/av_controller/AvControllerState_t
  */
 
 

package/javascr/av_controller/HtmlControl_t.js

@@ -8,7 +8,7 @@
  * observer linked to a specific DOM element and 
  * ensures the UI is revealed only when the media state is initialized.
  *
- * @module src/HtmlControl_t
+ * @module javascr/av_controller/HtmlControl_t
  */
 
 

package/javascr/av_controller/HtmlMedia_t.js

@@ -7,7 +7,7 @@
  * observer for HTMLMediaElements (e.g., <video> or <audio>). It facilitates 
  * bidirectional synchronization: 
  *
- * @module src/av_controller/HtmlMedia_t
+ * @module javascr/av_controller/HtmlMedia_t
  */
 
 /** ---------------------------------------------------------------------------

package/javascr/av_controller/HtmlPlay_t.js

@@ -8,7 +8,7 @@
  * the button's visual state with the application's playback state and handles 
  * user toggle interactions.
  *
- * @module src/HtmlPlay_t
+ * @module javascr/av_controller/HtmlPlay_t
  */
 
 /** ---------------------------------------------------------------------------

package/javascr/av_controller/HtmlSkipForward_t.js

@@ -7,7 +7,7 @@
  * observer for a skip-forward control. It handles user interactions to 
  * instantly move the media playback position to the end of the seekable range.
  *
- * @module src/HtmlSkipForward_t
+ * @module javascr/av_controller/HtmlSkipForward_t
  */
 
 /** ---------------------------------------------------------------------------

package/javascr/av_controller/HtmlSkipRewind_t.js

@@ -7,7 +7,7 @@
  * observer for a skip-rewind control. It handles user interactions to 
  * instantly move the media playback position to the start of the seekable range.
  *
- * @module src/HtmlSkipRewind_t
+ * @module javascr/av_controller/HtmlSkipRewind_t
  */
 
 /** ---------------------------------------------------------------------------

package/javascr/av_controller/HtmlTimerDigit_t.js

@@ -11,7 +11,7 @@
  * The logic includes both initial state synchronization and real-time updates 
  * triggered by media playback events.
  *
- * @module src/av_controller/HtmlTimerDigit_t
+ * @module javascr/av_controller/HtmlTimerDigit_t
  */
 
 /** ---------------------------------------------------------------------------

package/javascr/av_controller/HtmlTimerFrame_t.js

@@ -8,7 +8,7 @@
  * actual rendered width of the progress bar's frame and synchronize that 
  * measurement with the shared application state.
  *
- * @module src/av_controller/HtmlTimerFrame_t
+ * @module javascr/av_controller/HtmlTimerFrame_t
  * --------------------------------------------------------------------------- */
 
 /** ---------------------------------------------------------------------------

package/javascr/av_controller/av_controller.js

@@ -5,7 +5,7 @@
  * This module provides high-level controller functions to manage the creation, 
  * initialization, and disposal of `Subject_t`. 
  *
- * @module src/av_controller/av_controller
+ * @module javascr/av_controller/av_controller
  * --------------------------------------------------------------------------- */
  
 /** ---------------------------------------------------------------------------

package/javascr/av_controller/index.js

@@ -2,7 +2,7 @@
  * @file
  * Entry point for the av_controller module.
  *
- * @module src/av_controller/index
+ * @module javascr/av_controller/index
  */
 
 export * from "./AvControllerState_t.js";

package/javascr/index.js

@@ -2,7 +2,7 @@
  * @file
  * Entry point for the javascr module.
  *
- * @module smsmslib/javascr/index
+ * @module javascr/index
  */
 
 export * from "./system/index.js";

package/javascr/system/App_t.js

@@ -2,7 +2,7 @@
  * @file App_t.js
  * @brief Application root class providing a central access point for state management.
  *
- * @module src/App_t
+ * @module javascr/system/App_t
  * --------------------------------------------------------------------------- */
 
 /** ---------------------------------------------------------------------------

package/javascr/system/HtmlElement_t.js

@@ -8,7 +8,7 @@
  * JavaScript objects and their corresponding HTML elements, providing a 
  * structured way to manage DOM nodes as observer instances.
  *
- * @module src/HtmlElement_t
+ * @module javascr/system/HtmlElement_t
  */
 
 /** ---------------------------------------------------------------------------

package/javascr/system/Observer_t.js

@@ -7,7 +7,7 @@
  * should override these methods to implement specific behaviors, such as 
  * updating DOM elements or handling application-level events.
  *
- * @module src/Observer_t
+ * @module javascr/system/Observer_t
  * --------------------------------------------------------------------------- */
 
 /**

package/javascr/system/SubjectSet_t.js

@@ -7,7 +7,7 @@
  * to organize various data domains (e.g., user profiles, settings, state) 
  * under unique keys and provides mechanisms for collective operations.
  *
- * @module src/SubjectSet_t
+ * @module javascr/system/SubjectSet_t
  * --------------------------------------------------------------------------- */
 
 /** ---------------------------------------------------------------------------

package/javascr/system/Subject_t.js

@@ -18,7 +18,7 @@
  * via `data_get()`, editing it, and then explicitly calling `observer_update()` 
  * to trigger observer synchronization.
  *
- * @module src/Subject_t
+ * @module javascr/system/Subject_t
  * --------------------------------------------------------------------------- */
 
 /** ---------------------------------------------------------------------------

package/javascr/system/array.js

@@ -3,7 +3,7 @@
  * Provides core utility functions for **safe inspection and property modification** 
  * of Array instances.
  *
- * @module src/array
+ * @module javascr/system/array
  */
 
 /** ---------------------------------------------------------------------------

package/javascr/system/arrayconcat.js

@@ -3,7 +3,7 @@
  * Provides utility functions for **safely merging and concatenating** 
  * Array instances.
  *
- * @module src/arrayconcat
+ * @module javascr/system/arrayconcat
  */
 
 /** ---------------------------------------------------------------------------

package/javascr/system/arraynew.js

@@ -3,7 +3,7 @@
  * Provides utility functions for **creating and initializing** Array instances
  * safely.
  *
- * @module src/arraynew
+ * @module javascr/system/arraynew
  */
 
 /** ---------------------------------------------------------------------------

package/javascr/system/arraypush.js

@@ -3,7 +3,7 @@
  * Provides utility functions for **safely adding elements** to the end of 
  * Array instances.
  *
- * @module src/arraypush
+ * @module javascr/system/arraypush
  */
 
 

package/javascr/system/arraysplice.js

@@ -3,7 +3,7 @@
  * Provides utility functions for **safely modifying array contents** through 
  * splicing, removal, and replacement.
  *
- * @module src/arraysplice
+ * @module javascr/system/arraysplice
  */
 
 /** ---------------------------------------------------------------------------

package/javascr/system/document.js

@@ -2,7 +2,7 @@
  * @file
  * Utility functions for safe DOM document access and element selection.
  *
- * @module src/system/document
+ * @module javascr/system/document
  */
 
 /** ---------------------------------------------------------------------------

package/javascr/system/html.js

@@ -2,7 +2,7 @@
  * @file
  * Utility functions for accessing the HTML root element.
  *
- * @module src/system/html
+ * @module javascr/system/html
  */
 
 /** ---------------------------------------------------------------------------

package/javascr/system/index.js

@@ -2,7 +2,7 @@
  * @file
  * Entry point for the system module.
  *
- * @module src/system/index
+ * @module javascr/system/index
  */
 
 export * from "./App_t.js";

package/javascr/system/matnew.js

@@ -1,7 +1,8 @@
- /**
+/**
  * @file
+ * Provides functionality for creating multi-dimensional arrays (matrices).
  *
- * @module src/matnew
+ * @module javascr/system/matnew
  */
 
 /** ---------------------------------------------------------------------------
@@ -21,6 +22,24 @@ from "./array.js";
  * Functions.
  * --------------------------------------------------------------------------- */
 
+/**
+ * Creates a multi-dimensional array (matrix) with specified dimensions.
+ * This function constructs a nested array structure based on the provided 
+ * dimension arguments. 
+ *
+ * @param {...number} ai_dim [in]
+ * A variable number of arguments defining the size of each dimension.
+ * For example, `sj_mat_new(2, 3)` creates a 2x3 matrix. All arguments 
+ * must be positive integers.
+ *
+ * @returns {Array | null}
+ * A new multi-dimensional array initialized with 0 at the deepest level. 
+ * Returns `null` if any dimension is invalid or if allocation fails.
+ *
+ * @see mat_new_init
+ * @see mat_new_push
+ * @see mat_new_pop
+ */
 export function sj_mat_new(...ai_dim)
 {
   let   a_mat    = null;
@@ -48,6 +67,20 @@ export function sj_mat_new(...ai_dim)
 }
 
 
+/**
+ * Validates matrix dimensions and initializes the root array.
+ * This function ensures that `ai_dim` contains only positive integers.
+ * If valid, it creates and returns the first-order (root) array.
+ *
+ * @param {number[]} ai_dim [in]
+ * An array where `ai_dim[n]` represents the size of the n-th order dimension.
+ * Must contain at least one element, and all elements must be positive integers.
+ *
+ * @returns {Array | null}
+ * A new empty array for the first dimension if validation passes. 
+ * Returns `null` if `ai_dim` is empty, contains invalid dimensions, 
+ * or if array allocation fails.
+ */
 function mat_new_init(ai_dim)
 {
   let a_mat = null;
@@ -67,6 +100,22 @@ function mat_new_init(ai_dim)
 }
 
 
+/**
+ * Creates a new empty array for a deeper dimension and pushes the current 
+ * array `a_mat` onto the stack.
+ *
+ * @param {Array<Array>} aa_stack [in/out]
+ * A stack used to store parent array references as the construction
+ * moves to deeper dimensions.
+ *
+ * @param {Array} a_mat [in]
+ * The current array level that will now act as a parent to the 
+ * newly created array.
+ *
+ * @returns {Array | null}
+ * The newly created array instance (the new current level). 
+ * Returns `null` if array creation or pushing fails.
+ */
 function mat_new_push(aa_stack, a_mat)
 {
   const a_push = sj_array_new(0, 0);
@@ -90,6 +139,27 @@ function mat_new_push(aa_stack, a_mat)
 }
 
 
+/**
+ * Pops the stack to find the next available parent level after a_mat
+ * has been fully populated.
+ *
+ * This function repeatedly executes `a_mat = aa_stack.pop()` until the 
+ * condition `a_mat.length < ai_dim[aa_stack.length]` is met, ensuring 
+ * the returned array has space for the next element at its specific depth.
+ *
+ * @param {Array<Array>} aa_stack [in/out]
+ * A stack containing references to the parent arrays of `a_mat`.
+ *
+ * @param {Array} a_mat [in]
+ * The current array level having been populated.
+ *
+ * @param {number[]} ai_dim [in]
+ * An array where `ai_dim[n]` represents the size of the n-th order dimension.
+ *
+ * @returns {Array}
+ * The parent array of `a_mat` that has available capacity.
+ * Returns `a_mat` as is if no popping was necessary.
+ */
 function mat_new_pop(aa_stack, a_mat, ai_dim)
 {
   let a_mat_now = a_mat;

package/javascr/system/set.js

@@ -3,7 +3,7 @@
  * Set utility functions.
  * Provides helper functions for creating and managing Set objects.
  *
- * @module src/set
+ * @module javascr/system/set
  */
 
 /** ---------------------------------------------------------------------------

package/javascr/system/type.js

@@ -6,7 +6,7 @@
  * This module provides comprehensive and reliable functions for type determination,
  * going beyond the limitations of the standard 'typeof' operator.
  *
- * @module src/type
+ * @module javascr/system/type
  */
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "smsmslib",
-  "version": "1.0.59",
+  "version": "1.0.65",
   "description": "Reusable functions for me.",
   "files": [
     "javascr/**/*.js",
@@ -19,6 +19,6 @@
   "author": "",
   "license": "ISC",
   "dependencies": {
-    "smsmslib": "^1.0.59"
+    "smsmslib": "^1.0.65"
   }
 }

package/react/index.js

@@ -2,7 +2,7 @@
  * @file
  * Entry point for the react module.
  *
- * @module smsmslib/react/index
+ * @module react/index
  */
 
 export * from "../javascr/index.js";

package/react/system/index.js

@@ -2,7 +2,7 @@
  * @file
  * Entry point for the react/system module.
  *
- * @module smsmslib/react/system/index
+ * @module react/system/index
  */
 
 export * from "./useeffect.js";