native-document 1.0.91 → 1.0.93

package/src/core/elements/control/show-if.js

@@ -5,12 +5,18 @@ import Anchor from "../../elements/anchor";
 import {ElementCreator} from "../../wrappers/ElementCreator";
 
 /**
- * Show the element if the condition is true
+ * Conditionally shows an element based on an observable condition.
+ * The element is mounted/unmounted from the DOM as the condition changes.
  *
- * @param {ObservableItem|ObservableChecker} condition
- * @param {*} child
- * @param {{comment?: string|null, shouldKeepInCache?: Boolean}} configs
- * @returns {DocumentFragment}
+ * @param {ObservableItem<boolean>|ObservableChecker<boolean>|ObservableWhen} condition - Observable condition to watch
+ * @param {ValidChild} child - Element or content to show/hide
+ * @param {Object} [options={}] - Configuration options
+ * @param {string|null} [options.comment=null] - Comment for debugging
+ * @param {boolean} [options.shouldKeepInCache=true] - Whether to cache the element when hidden
+ * @returns {AnchorDocumentFragment} Anchor fragment managing the conditional content
+ * @example
+ * const isVisible = Observable(false);
+ * ShowIf(isVisible, Div({}, 'Hello World'));
  */
 export const ShowIf = function(condition, child, { comment = null, shouldKeepInCache = true} = {}) {
     if(!(Validator.isObservable(condition)) && !Validator.isObservableWhenResult(condition)) {
@@ -47,11 +53,18 @@ export const ShowIf = function(condition, child, { comment = null, shouldKeepInC
 }
 
 /**
- * Hide the element if the condition is true
- * @param {ObservableItem|ObservableChecker} condition
- * @param child
- * @param {{comment?: string|null, shouldKeepInCache?: Boolean}} configs
- * @returns {DocumentFragment}
+ * Conditionally hides an element when the observable condition is true.
+ * Inverse of ShowIf - element is shown when condition is false.
+ *
+ * @param {ObservableItem<boolean>|ObservableChecker<boolean>} condition - Observable condition to watch
+ * @param {ValidChild} child - Element or content to show/hide
+ * @param {Object} [configs] - Configuration options
+ * @param {string|null} [configs.comment] - Comment for debugging
+ * @param {boolean} [configs.shouldKeepInCache] - Whether to cache element when hidden
+ * @returns {AnchorDocumentFragment} Anchor fragment managing the conditional content
+ * @example
+ * const hasError = Observable(false);
+ * HideIf(hasError, Div({}, 'Content'));
  */
 export const HideIf = function(condition, child, configs) {
     const hideCondition = Observable(!condition.val());
@@ -61,12 +74,15 @@ export const HideIf = function(condition, child, configs) {
 }
 
 /**
- * Hide the element if the condition is false
+ * Conditionally hides an element when the observable condition is false.
+ * Same as ShowIf - element is shown when condition is true.
  *
- * @param {ObservableItem|ObservableChecker} condition
- * @param {*} child
- * @param {{comment?: string|null, shouldKeepInCache?: Boolean}} configs
- * @returns {DocumentFragment}
+ * @param {ObservableItem<boolean>|ObservableChecker<boolean>|ObservableWhen} condition - Observable condition to watch
+ * @param {ValidChild} child - Element or content to show/hide
+ * @param {Object} [configs] - Configuration options
+ * @param {string|null} [configs.comment] - Comment for debugging
+ * @param {boolean} [configs.shouldKeepInCache] - Whether to cache element when hidden
+ * @returns {AnchorDocumentFragment} Anchor fragment managing the conditional content
  */
 export const HideIfNot = function(condition, child, configs) {
     return ShowIf(condition, child, configs);

package/src/core/elements/control/show-when.js

@@ -2,6 +2,29 @@ import Validator from "../../utils/validator.js";
 import NativeDocumentError from "../../errors/NativeDocumentError.js";
 import {ShowIf} from "./show-if.js";
 
+/**
+ * Shows content when an observable equals a specific value.
+ * Can be called with 2 or 3 arguments.
+ *
+ * @overload
+ * @param {ObservableWhen} observerWhenResult - Result from observable.when(value)
+ * @param {ValidChild} view - Content to show when condition matches
+ * @returns {AnchorDocumentFragment}
+ *
+ * @overload
+ * @param {ObservableItem} observer - Observable to watch
+ * @param {*} target - Value to match
+ * @param {ValidChild} view - Content to show when observable equals target
+ * @returns {AnchorDocumentFragment}
+ *
+ * @example
+ * // 2 arguments
+ * const status = Observable('idle');
+ * ShowWhen(status.when('loading'), LoadingSpinner());
+ *
+ * // 3 arguments
+ * ShowWhen(status, 'loading', LoadingSpinner());
+ */
 export const ShowWhen = function() {
     if(arguments.length === 2) {
         const [observer, target] = arguments;

package/src/core/elements/control/switch.js

@@ -6,11 +6,24 @@ import {ElementCreator} from "../../wrappers/ElementCreator";
 
 
 /**
+ * Displays different content based on the current value of an observable.
+ * Like a switch statement for UI - shows the content corresponding to current value.
  *
- * @param {ObservableItem|ObservableChecker} $condition
- * @param {{[key]: *}} values
- * @param {Boolean} shouldKeepInCache
- * @returns {DocumentFragment}
+ * @param {ObservableItem|ObservableChecker} $condition - Observable to watch
+ * @param {Object<string|number, ValidChild>} values - Map of values to their corresponding content
+ * @param {boolean} [shouldKeepInCache=true] - Whether to cache rendered views
+ * @returns {AnchorDocumentFragment & {add: Function, remove: Function}} Fragment with dynamic methods
+ * @example
+ * const status = Observable('idle');
+ * const view = Match(status, {
+ *   idle: Div({}, 'Ready'),
+ *   loading: Div({}, 'Loading...'),
+ *   error: Div({}, 'Error occurred')
+ * });
+ *
+ * // Dynamic addition
+ * view.add('success', Div({}, 'Success!'));
+ * view.remove('idle');
  */
 export const Match = function($condition, values, shouldKeepInCache = true) {
 
@@ -67,11 +80,19 @@ export const Match = function($condition, values, shouldKeepInCache = true) {
 
 
 /**
+ * Displays one of two views based on a boolean observable condition.
+ * Simplified version of Match for true/false cases.
  *
- * @param {ObservableItem|ObservableChecker} $condition
- * @param {*} onTrue
- * @param {*} onFalse
- * @returns {DocumentFragment}
+ * @param {ObservableItem<boolean>|ObservableChecker<boolean>} $condition - Boolean observable to watch
+ * @param {ValidChild} onTrue - Content to show when condition is true
+ * @param {ValidChild} onFalse - Content to show when condition is false
+ * @returns {AnchorDocumentFragment} Fragment managing the conditional content
+ * @example
+ * const isLoggedIn = Observable(false);
+ * Switch(isLoggedIn,
+ *   Div({}, 'Welcome back!'),
+ *   Div({}, 'Please login')
+ * );
  */
 export const Switch = function ($condition, onTrue, onFalse) {
     if(!Validator.isObservable($condition)) {
@@ -85,9 +106,15 @@ export const Switch = function ($condition, onTrue, onFalse) {
 }
 
 /**
+ * Provides a fluent API for conditional rendering with show/otherwise pattern.
  *
- * @param {ObservableItem|ObservableChecker} $condition
- * @returns {{show: Function, otherwise: (((*) => {}):DocumentFragment)}
+ * @param {ObservableItem<boolean>|ObservableChecker<boolean>} $condition - Boolean observable to watch
+ * @returns {{show: Function, otherwise: Function}} Object with fluent methods
+ * @example
+ * const isLoading = Observable(false);
+ * When(isLoading)
+ *   .show(LoadingSpinner())
+ *   .otherwise(Content());
  */
 export const When = function($condition) {
     if(!Validator.isObservable($condition)) {
@@ -105,6 +132,9 @@ export const When = function($condition) {
         otherwise(onFalse) {
             $onFalse = onFalse;
             return Switch($condition, $onTrue, $onFalse);
+        },
+        toNdElement() {
+            return Switch($condition, $onTrue, $onFalse);
         }
     }
 }

package/src/core/utils/cache.js

@@ -0,0 +1,5 @@
+import { once as _once, autoMemoize, autoOnce } from "./memoize.js";
+
+export const once = fn => autoOnce(fn);
+export const singleton = fn => _once(fn);
+export const memoize = fn => autoMemoize(fn);

package/src/core/utils/memoize.js

@@ -3,9 +3,10 @@
 export const once = (fn) => {
     let result = null;
     return (...args) => {
-        if(result === null) {
-            result = fn(...args);
+        if(result) {
+            return result;
         }
+        result = fn(...args);
         return result;
     };
 };
@@ -14,9 +15,10 @@ export const autoOnce = (fn) => {
     let target = null;
     return new Proxy({}, {
         get: (_, key) => {
-            if(target === null) {
-                target = fn();
+            if(target) {
+                return target[key];
             }
+            target = fn();
             return target[key];
         }
     });
@@ -26,10 +28,13 @@ export const memoize = (fn) => {
     const cache = new Map();
     return (...args) => {
         const [key, ...rest] = args;
-        if(!cache.has(key)) {
-            cache.set(key, fn(...rest));
+        const cached = cache.get(key);
+        if(cached) {
+            return cached;
         }
-        return cache.get(key);
+        const result = fn(...rest);
+        cache.set(key, result);
+        return result;
     };
 };
 
@@ -37,17 +42,21 @@ export const autoMemoize = (fn) => {
     const cache = new Map();
     return new Proxy({}, {
         get: (_, key) => {
-            if(!cache.has(key)) {
-                if(fn.length > 0) {
-                    return (...args) => {
-                        const result = fn(...args);
-                        cache.set(key, result);
-                        return result;
-                    }
+            const cached = cache.get(key);
+            if(cached) {
+                return cached;
+            }
+
+            if(fn.length > 0) {
+                return (...args) => {
+                    const result = fn(...args, key);
+                    cache.set(key, result);
+                    return result;
                 }
-                cache.set(key, fn());
             }
-            return cache.get(key);
+            const result = fn(key);
+            cache.set(key, result);
+            return result;
         }
     });
 };

package/src/core/utils/prototypes.js

@@ -27,13 +27,14 @@ Function.prototype.cached = function(...args) {
 };
 
 Function.prototype.errorBoundary = function(callback) {
-    return (...args)  => {
+    const handler = (...args)  => {
         try {
             return this.apply(this, args);
         } catch(e) {
-            return callback(e);
+            return callback(e, {caller: handler, args: args });
         }
     };
+    return handler;
 };
 
 String.prototype.use = function(args) {

package/src/core/wrappers/AttributesWrapper.js

@@ -17,7 +17,7 @@ export function bindClassAttribute(element, data) {
             continue;
         }
         if(value.__$isObservableWhen) {
-            element.classes.toggle(className, value.isMath());
+            element.classes.toggle(className, value.isActive());
             value.subscribe((shouldAdd) => element.classes.toggle(className, shouldAdd));
             continue;
         }

package/src/core/wrappers/NDElement.js

@@ -103,12 +103,35 @@ NDElement.prototype.closedShadow = function(style = null) {
     return this.shadow('closed', style);
 };
 
+/**
+ * Attaches a template binding to the element by hydrating it with the specified method.
+ *
+ * @param {string} methodName - Name of the hydration method to call
+ * @param {BindingHydrator} bindingHydrator - Template binding with $hydrate method
+ * @returns {HTMLElement} The underlying HTML element
+ * @example
+ * const onClick = $binder.attach((event, data) => console.log(data));
+ * element.nd.attach('onClick', onClick);
+ */
 NDElement.prototype.attach = function(methodName, bindingHydrator) {
     bindingHydrator.$hydrate(this.$element, methodName);
     return this.$element;
 };
 
-
+/**
+ * Extends the current NDElement instance with custom methods.
+ * Methods are bound to the instance and available for chaining.
+ *
+ * @param {Object} methods - Object containing method definitions
+ * @returns {this} The NDElement instance with added methods for chaining
+ * @example
+ * element.nd.with({
+ *   highlight() {
+ *     this.$element.style.background = 'yellow';
+ *     return this;
+ *   }
+ * }).highlight().onClick(() => console.log('Clicked'));
+ */
 NDElement.prototype.with = function(methods) {
     if (!methods || typeof methods !== 'object') {
         throw new NativeDocumentError('extend() requires an object of methods');
@@ -139,6 +162,23 @@ NDElement.prototype.with = function(methods) {
     return this;
 }
 
+/**
+ * Extends the NDElement prototype with new methods available to all NDElement instances.
+ * Use this to add global methods to all NDElements.
+ *
+ * @param {Object} methods - Object containing method definitions to add to prototype
+ * @returns {typeof NDElement} The NDElement constructor
+ * @throws {NativeDocumentError} If methods is not an object or contains non-function values
+ * @example
+ * NDElement.extend({
+ *   fadeIn() {
+ *     this.$element.style.opacity = '1';
+ *     return this;
+ *   }
+ * });
+ * // Now all NDElements have .fadeIn() method
+ * Div().nd.fadeIn();
+ */
 NDElement.extend = function(methods) {
     if (!methods || typeof methods !== 'object') {
         throw new NativeDocumentError('NDElement.extend() requires an object of methods');

package/src/core/wrappers/NdPrototype.js

@@ -38,6 +38,10 @@ EVENTS_WITH_STOP.forEach(eventSourceName => {
         _stop(this.$element, eventName, callback);
         return this;
     };
+    NDElement.prototype['onPreventStop'+eventSourceName] = function(callback = null) {
+        _preventStop(this.$element, eventName, callback);
+        return this;
+    };
 });
 
 EVENTS_WITH_PREVENT.forEach(eventSourceName => {

package/src/core/wrappers/TemplateCloner.js

@@ -65,7 +65,12 @@ const bindAttachMethods = function(node, bindDingData, data) {
 
 const applyBindingTreePath = (root, target, data, path) => {
     if(path.fn) {
-        path.fn(data, target, root);
+        if(typeof path.fn === 'string') {
+            ElementCreator.bindTextNode(target, data[0][path.fn]);
+        }
+        else {
+            path.fn(data, target, root);
+        }
     }
     if(path.children) {
         for(let i = 0, length = path.children.length; i < length; i++) {
@@ -91,15 +96,16 @@ export function TemplateCloner($fn) {
             if(bindDingData && bindDingData.value) {
                 currentPath.fn = bindDingData.value;
                 const textNode = node.cloneNode();
+                if(typeof bindDingData.value === 'string') {
+                    ElementCreator.bindTextNode(textNode, data[0][bindDingData.value]);
+                    return textNode;
+                }
                 bindDingData.value(data, textNode);
                 return textNode;
             }
             return node.cloneNode(true);
         }
-        const nodeCloned = node.cloneNode(node.fullCloneNode);
-        if(node.fullCloneNode) {
-            return nodeCloned;
-        }
+        const nodeCloned = node.cloneNode();
         if(bindDingData) {
             bindAttributes(nodeCloned, bindDingData, data);
             bindAttachMethods(nodeCloned, bindDingData, data);
@@ -164,12 +170,9 @@ export function TemplateCloner($fn) {
     }
     this.value = (callbackOrProperty) => {
         if(typeof callbackOrProperty !== 'function') {
-            return createBinding(function(data, textNode) {
-                const firstArgument = data[0];
-                ElementCreator.bindTextNode(textNode, firstArgument[callbackOrProperty]);
-            }, 'value');
+            return createBinding(callbackOrProperty, 'value');
         }
-        return createBinding(function(data, textNode) {
+        return createBinding((data, textNode) => {
             ElementCreator.bindTextNode(textNode, callbackOrProperty(...data));
         }, 'value');
     };

package/src/core/wrappers/prototypes/bind-class-extensions.js

@@ -9,7 +9,7 @@ ObservableItem.prototype.bindNdClass = function(element, className) {
 };
 
 ObservableWhen.prototype.bindNdClass = function(element, className) {
-    element.classes.toggle(className, this.isMath());
+    element.classes.toggle(className, this.isMatch());
     this.subscribe((shouldAdd) => element.classes.toggle(className, shouldAdd));
 };
 

package/src/core/wrappers/prototypes/nd-element-extensions.js

@@ -4,6 +4,7 @@ import TemplateBinding from "../TemplateBinding";
 import {ElementCreator} from "../ElementCreator";
 import PluginsManager from "../../utils/plugins-manager";
 import Validator from "../../utils/validator";
+import ObservableChecker from "../../data/ObservableChecker";
 
 String.prototype.toNdElement = function () {
     const formattedChild = this.resolveObservableTemplate ? this.resolveObservableTemplate() : this;
@@ -33,6 +34,8 @@ ObservableItem.prototype.toNdElement = function () {
     return ElementCreator.createObservableNode(null, this);
 };
 
+ObservableChecker.prototype.toNdElement = ObservableItem.prototype.toNdElement;
+
 NDElement.prototype.toNdElement = function () {
     return this.$element ?? this.$build?.() ?? this.build?.() ?? null;
 };

package/src/router/Route.js

@@ -5,11 +5,16 @@ export const RouteParamPatterns = {
 };
 
 /**
+ * Creates a new Route instance.
  *
- * @param {string} $path
- * @param {Function} $component
- * @param {{name:?string, middlewares:Function[], shouldRebuild:Boolean, with: Object }}$options
- * @class
+ * @param {string} $path - URL pattern with optional parameters (e.g., '/user/{id:number}')
+ * @param {Function} $component - Component function that returns HTMLElement or DocumentFragment
+ * @param {Object} [$options={}] - Route configuration options
+ * @param {string} [$options.name] - Unique name for the route (used for navigation)
+ * @param {Function[]} [$options.middlewares] - Array of middleware functions
+ * @param {boolean} [$options.shouldRebuild] - Whether to rebuild component on each navigation
+ * @param {Object} [$options.with] - Custom parameter validation patterns
+ * @param {Function} [$options.layout] - Layout component wrapper function
  */
 export function Route($path, $component, $options = {}) {
 

package/src/router/Router.js

@@ -14,7 +14,7 @@ export const DEFAULT_ROUTER_NAME = 'default';
 /**
  *
  * @param {{mode: 'memory'|'history'|'hash'}} $options
- * @constructor
+ * @class
  */
 export default function Router($options = {}) {
 
@@ -72,11 +72,20 @@ export default function Router($options = {}) {
     };
 
     /**
+     * Groups routes under a common path prefix with shared options.
      *
-     * @param {string} suffix
-     * @param {{ middlewares: Function[], name: string}} options
-     * @param {Function} callback
-     * @returns {this}
+     * @param {string} suffix - Path prefix to prepend to all routes in the group
+     * @param {Object} options - Group configuration options
+     * @param {Function[]} [options.middlewares] - Middlewares applied to all routes in group
+     * @param {string} [options.name] - Name prefix for all routes in group
+     * @param {Function} [options.layout] - Layout component for all routes in group
+     * @param {Function} callback - Function that defines routes within the group
+     * @returns {this} Router instance for chaining
+     * @example
+     * router.group('/admin', { middlewares: [authMiddleware], layout: AdminLayout }, () => {
+     *   router.add('/users', UsersPage, { name: 'users' });
+     *   router.add('/settings', SettingsPage, { name: 'settings' });
+     * });
      */
     this.group = function(suffix, options, callback) {
         if(!Validator.isFunction(callback)) {
@@ -194,14 +203,24 @@ export default function Router($options = {}) {
 Router.routers = {};
 
 /**
+ * Creates and initializes a new router instance.
  *
- * @param {{mode: 'memory'|'history'|'hash', name?:string, entry?: string}} options
- * @param {Function} callback
- * @param {Element} container
+ * @param {Object} options - Router configuration
+ * @param {'memory'|'history'|'hash'} options.mode - Routing mode
+ * @param {string} [options.name] - Router name for multi-router apps
+ * @param {string} [options.entry] - Initial route path
+ * @param {Function} callback - Setup function that receives the router instance
+ * @returns {Router} The configured router instance with mount() method
+ * @example
+ * const router = Router.create({ mode: 'history' }, (r) => {
+ *   r.add('/home', HomePage, { name: 'home' });
+ *   r.add('/about', AboutPage, { name: 'about' });
+ * });
+ * router.mount('#app');
  */
 Router.create = function(options, callback) {
     if(!Validator.isFunction(callback)) {
-        DebugManager.error('Router', 'Callback must be a function', e);
+        DebugManager.error('Router', 'Callback must be a function');
         throw new RouterError('Callback must be a function');
     }
     const router = new Router(options);

package/src/router/errors/RouterError.js

@@ -5,5 +5,4 @@ export default class RouterError extends Error {
         super(message);
         this.context = context;
     }
-
 }

package/types/control-flow.d.ts

@@ -12,7 +12,10 @@ export interface HideIfFunction {
 }
 
 export interface MatchFunction {
-    <T extends string | number>(condition: ObservableItem<T> | ObservableChecker<T>, values: Record<T, ValidChild>, shouldKeepInCache?: boolean): DocumentFragment;
+    <T extends string | number>(condition: ObservableItem<T> | ObservableChecker<T>, values: Record<T, ValidChild>, shouldKeepInCache?: boolean): DocumentFragment & {
+        add(key: T, child: ValidChild, shouldFocusOn?: boolean): void;
+        remove(key: T): void;
+    };
 }
 
 export interface SwitchFunction {
@@ -30,14 +33,14 @@ export interface WhenFunction {
 export interface ForEachFunction {
     <T>(data: T[] | Record<string, T> | ObservableItem<T[]> | ObservableItem<Record<string, T>>,
         callback: (item: T, index?: ObservableItem<number>) => ValidChild,
-        key?: string | ((item: T, defaultKey: string | number) => string),
-        configs?: { shouldKeepItemsInCache: boolean, isParentUniqueChild: boolean,  }): DocumentFragment,
+        key?: string | ((item: T, defaultKey: string | number) => string | number),
+        options?: { shouldKeepItemsInCache: boolean, isParentUniqueChild: boolean,  }): DocumentFragment,
 }
 
 export interface ForEachArrayFunction {
     <T>(data: ObservableArray<T>,
         callback: (item: T, index?: ObservableItem<number>) => ValidChild,
-        configs?: { pushDelay?: (items: T[]) => number, isParentUniqueChild: boolean, shouldKeepItemsInCache?: boolean }): DocumentFragment;
+        configs?: { isParentUniqueChild: boolean, shouldKeepItemsInCache?: boolean }): DocumentFragment;
 }
 
 export interface HideIfNotFunction {
@@ -45,8 +48,8 @@ export interface HideIfNotFunction {
 }
 
 
-export function ShowWhen(observer: ObservableWhen, target: any): ReturnType<typeof ShowIf>;
-export function ShowWhen(observer: ObservableWhen, target: any, view: any): ReturnType<typeof ShowIf>;
+export function ShowWhen(observerWhenResult: ObservableWhen, view: ValidChild): ReturnType<typeof ShowIf>;
+export function ShowWhen(observer: ObservableItem, target: any, view: ValidChild): ReturnType<typeof ShowIf>;
 
 // Control Flow Components
 export declare const ShowIf: ShowIfFunction;

package/types/elements.d.ts

@@ -130,12 +130,15 @@ export declare type AnchorDocumentFragment = DocumentFragment & {
     clear: ()  => void;
     remove: ()  => void;
     removeChildren: ()  => void;
-    insertBefore: (child: ValidChild, before: HTMLElement|Comment)  => void;
+    insertBefore: (child: ValidChild, before: HTMLElement|Comment|null)  => void;
     replaceContent: (child: ValidChild)  => void;
-    appendElement: (child: ValidChild, before: HTMLElement) => void;
-    getByIndex: (index: number) => HTMLElement;
+    setContent: (child: ValidChild)  => void;
+    appendElement: (child: ValidChild, before: HTMLElement|Comment|null) => void;
+    append: (...args: ValidChild[]) => void;
+    getByIndex: (index: number) => HTMLElement|null;
     endElement: () => Comment;
     startElement: () => Comment;
+    removeWithAnchors: () => void;
 };
 
 // Anchor

package/types/filters/index.d.ts

@@ -0,0 +1,4 @@
+export * from './types';
+export * from './dates';
+export * from './standard';
+export * from './strings';