native-document 1.0.15 → 1.0.16-8.2

package/src/core/utils/helpers.js

@@ -0,0 +1,144 @@
+import Validator from './validator';
+
+/**
+ * Calls a function with the given arguments and optional context.
+ *
+ * @internal
+ * @param {Function} fn - Function to invoke
+ * @param {Array} args - Arguments to pass
+ * @param {Object|null} [context] - `this` context, or null to call without binding
+ */
+const invoke = function(fn, args, context) {
+    if(context) {
+        fn.apply(context, args);
+    } else {
+        fn(...args);
+    }
+};
+/**
+ *
+ * @param {Function} fn
+ * @param {number} delay
+ * @param {{leading?:Boolean, trailing?:Boolean, debounce?:Boolean, check: Function}}options
+ * @returns {(function(...[*]): void)|*}
+ */
+export const debounce = function(fn, delay, options = {}) {
+    let timer = null;
+    let lastArgs = null;
+
+    return  function(...args) {
+        const context = options.context === true ? this : null;
+        let scopeDelay = delay;
+        if(options.check) {
+            const response = options.check(...args);
+            if(typeof response === 'number') {
+                scopeDelay = response;
+            }
+        }
+        lastArgs = args;
+
+        // debounce mode: reset the timer for each call
+        clearTimeout(timer);
+        timer = setTimeout(() => invoke(fn, lastArgs, context), delay);
+    };
+};
+
+export const nextTick = function(fn) {
+    let pending = false;
+    return function(...args) {
+        if (pending) return;
+        pending = true;
+
+        Promise.resolve().then(() => {
+            fn.apply(this, args);
+            pending = false;
+        });
+    };
+};
+
+
+/**
+ * Returns the unique key for a given item, used by ForEach and ForEachArray for DOM diffing.
+ * Resolution order:
+ * 1. If key is a function: calls key(item, defaultKey)
+ * 2. If key is a string: reads item[key] (unwrapping observables)
+ * 3. Otherwise: returns item value or defaultKey
+ *
+ * @param {*} item - The item to extract a key from
+ * @param {string|number} defaultKey - Fallback key (usually the array index)
+ * @param {string|Function|null} key - Key property name or custom key function
+ * @returns {string|number} The resolved unique key
+ */
+export const getKey = (item, defaultKey, key) => {
+    if (Validator.isString(key)) {
+        const val = Validator.isObservable(item) ? item.val() : item;
+        const result = val?.[key];
+        return Validator.isObservable(result) ? result.val() : (result ?? defaultKey);
+    }
+
+    if (Validator.isFunction(key)) {
+        return key(item, defaultKey);
+    }
+
+    const val = Validator.isObservable(item) ? item.val() : item;
+    return val ?? defaultKey;
+};
+
+/**
+ * Trims all leading and trailing occurrences of char from str.
+ *
+ * @param {string} str - String to trim
+ * @param {string} char - Character to remove from both ends
+ * @returns {string} Trimmed string
+ * @example
+ * trim('/foo/bar/', '/'); // 'foo/bar'
+ */
+export const trim = function(str, char) {
+    return str.replace(new RegExp(`^[${char}]+|[${char}]+$`, 'g'), '');
+};
+
+/**
+ * Deep clones a value. Uses structuredClone when available.
+ * Handles: primitives, Dates, Arrays, plain Objects.
+ * Observables are kept by reference (not cloned); onObservableFound is called for each.
+ *
+ * @param {*} value - Value to clone
+ * @param {((observable: ObservableItem) => void)?} [onObservableFound] - Called for each observable encountered
+ * @returns {*} Deep clone of the value
+ */
+export const deepClone = (value, onObservableFound) => {
+    try {
+        if(window.structuredClone !== undefined) {
+            return window.structuredClone(value);
+        }
+    } catch (e){}
+
+    if (value === null || typeof value !== 'object') {
+        return value;
+    }
+
+    // Dates
+    if (value instanceof Date) {
+        return new Date(value.getTime());
+    }
+
+    // Arrays
+    if (Array.isArray(value)) {
+        return value.map(item => deepClone(item));
+    }
+
+    // Observables - keep the référence
+    if (Validator.isObservable(value)) {
+        onObservableFound && onObservableFound(value);
+        return value;
+    }
+
+    // Objects
+    const cloned = {};
+    for (const key in value) {
+        if (Object.hasOwn(value, key)) {
+            cloned[key] = deepClone(value[key]);
+        }
+    }
+    return cloned;
+};

package/src/core/utils/localstorage.js

@@ -0,0 +1,57 @@
+import NativeDocumentError from '../errors/NativeDocumentError';
+
+export const LocalStorage = {
+    getJson(key) {
+        const value = localStorage.getItem(key);
+        try {
+            return JSON.parse(value);
+        } catch (e) {
+            throw new NativeDocumentError('invalid_json:'+key);
+        }
+    },
+    getNumber(key) {
+        return Number(this.get(key));
+    },
+    getBool(key) {
+        const value = this.get(key);
+        return value === 'true' || value === '1';
+    },
+    setJson(key, value) {
+        localStorage.setItem(key, JSON.stringify(value));
+    },
+    setBool(key, value) {
+        localStorage.setItem(key, value ? 'true' : 'false');
+    },
+    get(key, defaultValue = null) {
+        return localStorage.getItem(key) || defaultValue;
+    },
+    set(key, value) {
+        return localStorage.setItem(key, value);
+    },
+    remove(key) {
+        localStorage.removeItem(key);
+    },
+    has(key) {
+        return localStorage.getItem(key) != null;
+    },
+};
+
+export const $getFromStorage = (key, value) => {
+    if(!LocalStorage.has(key)) {
+        return value;
+    }
+    switch (typeof value) {
+    case 'object': return LocalStorage.getJson(key) ?? value;
+    case 'boolean': return LocalStorage.getBool(key) ?? value;
+    case 'number': return LocalStorage.getNumber(key) ?? value;
+    default: return LocalStorage.get(key, value) ?? value;
+    }
+};
+
+export const $saveToStorage = (value) => {
+    switch (typeof value) {
+    case 'object': return LocalStorage.setJson;
+    case 'boolean': return LocalStorage.setBool;
+    default: return LocalStorage.set;
+    }
+};

package/src/core/utils/memoize.js

@@ -0,0 +1,115 @@
+
+
+/**
+ * Wraps a function so it executes at most once.
+ * Later calls return the cached result without re-executing the function.
+ *
+ * @template T
+ * @param {(...args: any[]) => T} fn - Function to wrap
+ * @returns {(...args: any[]) => T} Memoized function
+ * @example
+ * const init = once(() => expensiveSetup());
+ * init(); // runs setup
+ * init(); // returns cached result
+ */
+export const once = (fn) => {
+    let result = null;
+    return (...args) => {
+        if(result != null) {
+            return result;
+        }
+        result = fn(...args);
+        return result;
+    };
+};
+
+/**
+ * Creates a lazy proxy that calls fn() once on first property access,
+ * then returns properties from the cached result for all later accesses.
+ *
+ * @template T
+ * @param {() => T} fn - Factory function to call once
+ * @returns {T} Proxy to the lazily created object
+ * @example
+ * const store = autoOnce(() => createExpensiveStore());
+ * store.count; // triggers createExpensiveStore() on first access
+ * store.name; // uses a cached result
+ */
+export const autoOnce = (fn) => {
+    let target = null;
+    return new Proxy({}, {
+        get: (_, key) => {
+            if(target) {
+                return target[key];
+            }
+            target = fn();
+            return target[key];
+        },
+    });
+};
+
+/**
+ * Wraps a function with key-based memoization.
+ * The first argument is used as the cache key; later arguments are passed to fn.
+ *
+ * @template T
+ * @param {(...args: any[]) => T} fn - Function to memoize
+ * @returns {(key: any, ...args: any[]) => T} Memoized function
+ * @example
+ * const getUser = memoize((id) => fetchUser(id));
+ * getUser('user-1', 1); // fetches
+ * getUser('user-1', 1); // returns cached
+ */
+export const memoize = (fn) => {
+    const cache = new Map();
+    return (...args) => {
+        const [key, ...rest] = args;
+        const cached = cache.get(key);
+        if(cached) {
+            return cached;
+        }
+        const result = fn(...rest);
+        cache.set(key, result);
+        return result;
+    };
+};
+
+/**
+ * Creates a proxy where each property access memorizes the result of calling fn with the property key.
+ * If fn accepts arguments (fn.length > 0), the proxy returns a memoized function instead.
+ *
+ * @template T
+ * @param {((key: string|symbol, ...args?: any[]) => T)} fn - Factory function
+ * @returns {Record<string|symbol, T>} Proxy with per-key memoized results
+ * @example
+ * // fn with no args — result memoized by key
+ * const icons = autoMemoize((name) => loadIcon(name));
+ * icons.home; // calls loadIcon('home'), caches result
+ * icons.home; // returns cached
+ *
+ * // fn with args — returns a memoized function per key
+ * const formatters = autoMemoize((locale, value) => format(value, locale));
+ * formatters.fr('hello'); // calls format('hello', 'fr'), caches under 'fr'
+ */
+export const autoMemoize = (fn) => {
+    const cache = new Map();
+    return new Proxy({}, {
+        get: (_, key) => {
+            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;
+                };
+            }
+            const result = fn(key);
+            cache.set(key, result);
+            return result;
+        },
+    });
+};

package/src/core/utils/plugins-manager.js

@@ -0,0 +1,81 @@
+import DebugManager from './debug-manager';
+
+let PluginsManager = null;
+
+if(process.env.NODE_ENV === 'development') {
+    PluginsManager = (function() {
+
+        const $plugins = new Map();
+        const $pluginByEvents = new Map();
+
+        return {
+            list() {
+                return $pluginByEvents;
+            },
+            add(plugin, name){
+                if (!plugin || typeof plugin !== 'object') {
+                    throw new Error(`Plugin ${name} must be an object`);
+                }
+                name = name || plugin.name;
+                if (!name || typeof name !== 'string') {
+                    throw new Error('Please, provide a valid plugin name');
+                }
+                if($plugins.has(name)) {
+                    return;
+                }
+
+                plugin.$name = name;
+                $plugins.set(name ,plugin);
+                if(typeof plugin?.init === 'function') {
+                    plugin.init();
+                }
+                for(const methodName in plugin) {
+                    if(/^on[A-Z]/.test(methodName)) {
+                        const eventName = methodName.replace(/^on/, '');
+                        if(!$pluginByEvents.has(eventName)) {
+                            $pluginByEvents.set(eventName, new Set());
+                        }
+                        $pluginByEvents.get(eventName).add(plugin);
+                    }
+                }
+            },
+            remove(pluginName){
+                if(!$plugins.has(pluginName)) {
+                    return;
+                }
+                const plugin = $plugins.get(pluginName);
+                if(typeof plugin.cleanup === 'function') {
+                    plugin.cleanup();
+                }
+                for(const [name, sets] of $pluginByEvents.entries() ) {
+                    if(sets.has(plugin)) {
+                        sets.delete(plugin);
+                    }
+                    if(sets.size === 0) {
+                        $pluginByEvents.delete(name);
+                    }
+                }
+                $plugins.delete(pluginName);
+            },
+            emit(eventName, ...data) {
+                if(!$pluginByEvents.has(eventName)) {
+                    return;
+                }
+                const plugins = $pluginByEvents.get(eventName);
+
+                for(const plugin of plugins) {
+                    const callback = plugin['on'+eventName];
+                    if(typeof callback === 'function') {
+                        try{
+                            callback.call(plugin, ...data);
+                        } catch (error) {
+                            DebugManager.error('Plugin Manager', `Error in plugin ${plugin.$name} for event ${eventName}`, error);
+                        }
+                    }
+                }
+            },
+        };
+    }());
+}
+
+export default PluginsManager;

package/src/core/utils/property-accumulator.js

@@ -0,0 +1,72 @@
+import Validator from './validator';
+
+export const cssPropertyAccumulator = function(initialValue = {}) {
+    const data = Validator.isString(initialValue) ? initialValue.split(';').filter(Boolean) : initialValue;
+
+    return {
+        add(key, value) {
+            if(Array.isArray(data)) {
+                data.push(key+':  '+value);
+                return;
+            }
+            if(Validator.isObject(key)) {
+                value = key;
+                for(const property in value) {
+                    data[property] = value[property];
+                }
+                return;
+            }
+            data[key] = value;
+        },
+        value() {
+            if(Array.isArray(data)) {
+                return data.join(';').concat(';');
+            }
+            return { ...data };
+        },
+    };
+};
+
+export const classPropertyAccumulator = function(initialValue = []) {
+    let data = Validator.isString(initialValue) ? initialValue.split(' ').filter(Boolean) : initialValue;
+
+    return {
+        add(key, value = true) {
+            if(Validator.isJson(key)) {
+                for(const property in key) {
+                    if(key[property]) {
+                        data[property] = key[property];
+                    }
+                }
+                return;
+            }
+            if(value != null || key.__$Observable) {
+                if(Array.isArray(data)) {
+                    data = data.reduce((acc, item) => {
+                        acc[item] = true;
+                        return acc;
+                    }, {});
+                }
+                if(key.__$Observable) {
+                    const uniqueId = `obs-${Math.random().toString(36).substr(2, 9)}`;
+                    data[uniqueId] = key;
+                }
+                else {
+                    data[key] = value;
+                }
+                return;
+            }
+            if(Array.isArray(data)) {
+                data.push(key);
+                return;
+            }
+            data[key] = value;
+        },
+        value() {
+            if(Array.isArray(data)) {
+                return data.join(' ');
+            }
+            return { ...data };
+        },
+    };
+};

package/src/core/utils/prototypes.js

@@ -0,0 +1,44 @@
+import {withValidation} from './args-types.js';
+
+
+DocumentFragment.prototype.__IS_FRAGMENT = true;
+
+/**
+ * Wraps a function with argument validation based on an ArgTypes schema.
+ * Throws an ArgTypesError if the arguments don't match the schema.
+ *
+ * @param {...ArgType} args - ArgType descriptors defining expected argument types
+ * @returns {Function} Wrapped function that validates its arguments before executing
+ * @example
+ * function greet(name, age) { ... }
+ * const safeGreet = greet.args(ArgTypes.string('name'), ArgTypes.number('age'));
+ * safeGreet('John', 25); // OK
+ * safeGreet('John', 'old'); // throws ArgTypesError
+ */
+Function.prototype.args = function(...args) {
+    return withValidation(this, args);
+};
+
+
+/**
+ * Wraps a function with a try/catch error boundary.
+ * If the function throws, the callback is called with the error and context instead.
+ *
+ * @param {(error: Error, context: { caller: Function, args: any[] }) => *} callback - Error handler
+ * @returns {Function} Wrapped function with error boundary
+ * @example
+ * const safeRender = render.errorBoundary((err, { args }) => {
+ *   console.error('Render failed:', err.message);
+ *   return Div({}, 'Error');
+ * });
+ */
+Function.prototype.errorBoundary = function(callback) {
+    const handler = (...args)  => {
+        try {
+            return this.apply(this, args);
+        } catch(e) {
+            return callback(e, {caller: handler, args: args });
+        }
+    };
+    return handler;
+};