native-document 1.0.165 → 1.0.168

package/src/components/tooltip/types/Tooltip.d.ts

@@ -0,0 +1,65 @@
+import type { ValidChild } from '../../../../types/elements';
+import type { ObservableItem } from '../../../../types/observable';
+import type { BaseComponent } from '../../BaseComponent';
+import type { GlobalAttributes } from '../../../../types/globals';
+
+export type TooltipDescription = {
+        trigger: HTMLElement | null;
+        interaction: 'hover' | 'click' | 'focus';
+        content: ValidChild;
+        position: 'top' | 'bottom' | 'left' | 'right';
+        title: ValidChild | null;
+        isOpen: ObservableItem<boolean>;
+        offset: number;
+        shift: Record<string, number>;
+        hideDelay: number;
+        arrow: boolean;
+        interactive: boolean;
+        variant: string | null;
+        updatePositionOn: ObservableItem<unknown> | null;
+        props: GlobalAttributes;
+    };
+
+export interface TooltipInterface extends BaseComponent {
+    trigger(trigger: HTMLElement): this;
+    title(title: ValidChild): this;
+    content(content: ValidChild): this;
+    variant(variant: string): this;
+    primary(): this;
+    success(): this;
+    warning(): this;
+    danger(): this;
+    info(): this;
+    position(position: 'top' | 'bottom' | 'left' | 'right'): this;
+    atTop(): this;
+    atBottom(): this;
+    atLeft(): this;
+    atRight(): this;
+    onClicked(): this;
+    onHovered(): this;
+    onFocused(): this;
+    hideDelay(ms: number): this;
+    arrow(enabled?: boolean): this;
+    interactive(isInteractive?: boolean): this;
+    open(): this;
+    close(): this;
+    toggle(): this;
+    onOpen(handler: () => void): this;
+    onClose(handler: () => void): this;
+    render(renderFn: (desc: TooltipDescription, instance: TooltipInterface) => ValidChild): this;
+    offset(offset: number): this;
+    shift(shift: Record<string, number>): this;
+    updatePositionOn(obs: ObservableItem<unknown> | unknown): this;
+}
+
+
+export declare function Tooltip(content: ValidChild, props?: Record<string, unknown>): TooltipInterface;
+export declare namespace Tooltip {
+
+
+    function use(template: (description: TooltipDescription, instance: TooltipInterface) => ValidChild): void;
+    function preset(name: string, callback: (instance: TooltipInterface) => TooltipInterface): void;
+    function presets(presets: Record<string, (instance: TooltipInterface) => TooltipInterface>): void;
+
+
+}

package/src/core/data/MemoryManager.js

@@ -1,4 +1,4 @@
-import DebugManager from "../../core/utils/debug-manager";
+import DebugManager from '../../core/utils/debug-manager';
 
 
 const MemoryManager = (function() {
@@ -50,7 +50,7 @@ const MemoryManager = (function() {
             if (cleanedCount > 0) {
                 DebugManager.log('Memory Auto Clean', `🧹 Cleaned ${cleanedCount} orphaned observables`);
             }
-        }
+        },
     };
 }());
 

package/src/core/data/Observable.js

@@ -1,16 +1,16 @@
 import ObservableItem from './ObservableItem';
-import MemoryManager from "./MemoryManager";
-import NativeDocumentError from "../../core/errors/NativeDocumentError";
-import ObservableArray from "./ObservableArray";
-import Validator from "../utils/validator";
-import {nextTick} from "../utils/helpers";
-import PluginsManager from "../utils/plugins-manager";
-import {ObservableObject} from "./ObservableObject";
-
-import "./observable-helpers/observable.is-to";
+import MemoryManager from './MemoryManager';
+import NativeDocumentError from '../../core/errors/NativeDocumentError';
+import ObservableArray from './ObservableArray';
+import Validator from '../utils/validator';
+import {nextTick} from '../utils/helpers';
+import PluginsManager from '../utils/plugins-manager';
+import {ObservableObject} from './ObservableObject';
+
+import './observable-helpers/observable.is-to';
 import './observable-helpers/observable.prototypes';
-import ObservableResource from "./ObservableResource";
-import {Formatters} from "../utils/formatters";
+import ObservableResource from './ObservableResource';
+import {Formatters} from '../utils/formatters';
 /**
  *
  * @param {*} value
@@ -163,8 +163,8 @@ Observable.computed = function(callback, dependencies = []) {
     }
 
     dependencies.forEach(dependency => {
-        if(Validator.isProxy(dependency)) {
-            dependency.$observables.forEach((observable) => {
+        if(dependency.__$isObservableObject) {
+            dependency.observables().forEach((observable) => {
                 observable.subscribe(updatedValue);
             });
             return;
@@ -178,7 +178,7 @@ ObservableItem.computed = Observable.computed;
 
 
 Observable.init = function(initialValue, configs = null) {
-    return new ObservableObject(initialValue, configs)
+    return new ObservableObject(initialValue, configs);
 };
 
 /**
@@ -188,7 +188,7 @@ Observable.init = function(initialValue, configs = null) {
  */
 Observable.arrayOfObject = function(data) {
     return data.map(item => Observable.object(item));
-}
+};
 
 /**
  * Get the value of an observable or an object of observables.
@@ -207,9 +207,6 @@ Observable.value = function(data) {
     if(data?.__$Observable) {
         return data.val();
     }
-    if(Validator.isProxy(data)) {
-        return data.$value;
-    }
     return data;
 };
 

package/src/core/data/ObservableArray.js

@@ -1,18 +1,26 @@
-import {match} from "../utils/filters/index";
-import Validator from "../utils/validator";
-import ObservableItem from "./ObservableItem.js";
-import PluginsManager from "../utils/plugins-manager.js";
-import NativeDocumentError from "../errors/NativeDocumentError.js";
-import {nextTick} from "../utils/helpers";
+import {match} from '../utils/filters/index';
+import Validator from '../utils/validator';
+import ObservableItem from './ObservableItem.js';
+import PluginsManager from '../utils/plugins-manager.js';
+import NativeDocumentError from '../errors/NativeDocumentError.js';
+import {nextTick} from '../utils/helpers';
 
 const mutationMethods = ['push', 'pop', 'shift', 'unshift', 'reverse', 'sort', 'splice'];
 const noMutationMethods = ['map', 'forEach', 'filter', 'reduce', 'some', 'every', 'find', 'findIndex', 'concat', 'includes', 'indexOf'];
 
 /**
+ * Reactive array container extending ObservableItem.
+ * Wraps a native array and triggers reactivity on mutations (push, pop, splice, etc.).
+ * Use Observable.array() rather than instantiating directly.
  *
- * @param target
- * @param {{propagation: boolean, deep: boolean, reset: boolean}|null} configs
  * @constructor
+ * @param {Array} target - Initial array value
+ * @param {{ propagation?: boolean, deep?: boolean, reset?: boolean }|null} [configs=null] - Configuration
+ * @param {boolean} [configs.deep] - If false, nested arrays are not wrapped in ObservableArray
+ * @param {boolean} [configs.reset] - If true, stores initial value for .reset()
+ * @example
+ * const items = Observable.array([1, 2, 3]);
+ * items.push(4); // triggers reactivity
  */
 const ObservableArray = function (target, configs = null) {
     if(!Array.isArray(target)) {
@@ -33,7 +41,7 @@ ObservableArray.prototype.__$isObservableArray = true;
 Object.defineProperty(ObservableArray.prototype, 'length', {
     get() {
         return this.$currentValue.length;
-    }
+    },
 });
 
 
@@ -53,7 +61,7 @@ mutationMethods.forEach((method) => {
             const result = this.$currentValue[method].apply(this.$currentValue, argsToUse);
             this.trigger({ action: method, args: argsToUse, result });
             return result;
-        })
+        });
     };
 });
 
@@ -157,7 +165,7 @@ ObservableArray.prototype.swap = function(indexA, indexB) {
             return false;
         }
         const elementA = value[indexA];
-        const elementB = value[indexB]
+        const elementB = value[indexB];
 
         value[indexA] = elementB;
         value[indexB] = elementA;
@@ -166,6 +174,17 @@ ObservableArray.prototype.swap = function(indexA, indexB) {
     return true;
 };
 
+/**
+ * Swaps two items by reference (not by index).
+ * Finds indices of both items and delegates to .swap().
+ *
+ * @param {*} itemA - First item (by reference)
+ * @param {*} itemB - Second item (by reference)
+ * @returns {boolean} True if swap was successful
+ * @example
+ * const items = Observable.array(['a', 'b', 'c']);
+ * items.swapItems('a', 'c'); // ['c', 'b', 'a']
+ */
 ObservableArray.prototype.swapItems = function(itemA, itemB) {
     const indexA = this.$currentValue.indexOf(itemA);
     const indexB = this.$currentValue.indexOf(itemB);
@@ -173,6 +192,16 @@ ObservableArray.prototype.swapItems = function(itemA, itemB) {
     return this.swap(indexA, indexB);
 };
 
+/**
+ * Inserts an item immediately after the target item in the array.
+ *
+ * @param {*} data - Item to insert
+ * @param {*} target - Existing item after which data is inserted
+ * @returns {Array} Result of the underlying splice call
+ * @example
+ * const items = Observable.array(['a', 'c']);
+ * items.insertAfter('b', 'a'); // ['a', 'b', 'c']
+ */
 ObservableArray.prototype.insertAfter = function(data, target) {
     const targetIndex = this.$currentValue.indexOf(target);
     return this.splice(targetIndex + 1, 0, data);
@@ -216,24 +245,28 @@ ObservableArray.prototype.removeItem = function(item) {
     return this.remove(indexOfItem);
 };
 
+
 /**
- * Checks if the array is empty.
+ * Checks if the array has no elements.
+ * Semantic alias for length === 0. Different from .clear() which empties the array.
  *
- * @returns {boolean} True if array has no elements
+ * @returns {boolean} True if the array contains no elements
  * @example
  * const items = Observable.array([]);
- * items.isEmpty(); // true
+ * items.empty(); // true
  */
 ObservableArray.prototype.empty = function() {
     return this.$currentValue.length === 0;
 };
 
+
 /**
- * Triggers a populate operation with the current array, iteration count, and callback.
- * Used internally for rendering optimizations.
+ * Triggers a 'populate' operation used internally by ForEachArray for batch rendering.
+ * Not intended for direct use in application code.
  *
- * @param {number} iteration - Iteration count for rendering
- * @param {Function} callback - Callback function for rendering items
+ * @internal
+ * @param {number} iteration - Number of items to render
+ * @param {Function} callback - Render callback for each item
  */
 ObservableArray.prototype.populateAndRender = function(iteration, callback) {
     this.trigger({ action: 'populate', args: [this.$currentValue, iteration, callback] });
@@ -323,8 +356,8 @@ ObservableArray.prototype.whereSome = function(fields, filter) {
     return this.where({
         _: {
             dependencies: filter.dependencies,
-            callback: (item) => fields.some(field => filter.callback(item[field]))
-        }
+            callback: (item) => fields.some(field => filter.callback(item[field])),
+        },
     });
 };
 
@@ -346,11 +379,23 @@ ObservableArray.prototype.whereEvery = function(fields, filter) {
     return this.where({
         _: {
             dependencies: filter.dependencies,
-            callback: (item) => fields.every(field => filter.callback(item[field]))
-        }
+            callback: (item) => fields.every(field => filter.callback(item[field])),
+        },
     });
 };
 
+/**
+ * Subscribes deeply to all observable items within the array.
+ * Automatically binds and unbinds listeners as items are added or removed.
+ * Returns an unsubscribe function.
+ *
+ * @param {(value: Array) => void} callback - Called whenever any nested observable changes
+ * @returns {() => void} Unsubscribe function
+ * @example
+ * const users = Observable.array([Observable({ name: 'John' })]);
+ * const unsub = users.deepSubscribe((items) => console.log('changed', items));
+ * unsub(); // stop listening
+ */
 ObservableArray.prototype.deepSubscribe = function(callback) {
     const updatedValue = nextTick(() => callback(this.val()));
     const $listeners = new WeakMap();
@@ -382,33 +427,33 @@ ObservableArray.prototype.deepSubscribe = function(callback) {
 
     this.subscribe((items, _, operations) => {
         switch (operations?.action) {
-            case 'push':
-            case 'unshift':
-                operations.args.forEach(bindItem);
-                break;
-
-            case 'splice': {
-                const [start, deleteCount, ...newItems] = operations.args;
-                operations.result?.forEach(unbindItem);
-                newItems.forEach(bindItem);
-                break;
-            }
+        case 'push':
+        case 'unshift':
+            operations.args.forEach(bindItem);
+            break;
+
+        case 'splice': {
+            const [start, deleteCount, ...newItems] = operations.args;
+            operations.result?.forEach(unbindItem);
+            newItems.forEach(bindItem);
+            break;
+        }
 
-            case 'remove':
-                unbindItem(operations.result);
-                break;
+        case 'remove':
+            unbindItem(operations.result);
+            break;
 
-            case 'merge':
-                operations.args.forEach(bindItem);
-                break;
+        case 'merge':
+            operations.args.forEach(bindItem);
+            break;
 
-            case 'clear':
-                this.$currentValue.forEach(unbindItem);
-                break;
+        case 'clear':
+            this.$currentValue.forEach(unbindItem);
+            break;
 
-            case 'sort':
-            case 'reverse':
-                break;
+        case 'sort':
+        case 'reverse':
+            break;
         }
     });
 
@@ -417,7 +462,19 @@ ObservableArray.prototype.deepSubscribe = function(callback) {
     };
 };
 
-
+/**
+ * Keeps this array in sync with another ObservableArray.
+ * All mutations are mirrored to the target array in real time.
+ *
+ * @param {ObservableArray} targetObservable - The array to sync into
+ * @returns {() => void} Unsubscribe function to stop syncing
+ * @example
+ * const source = Observable.array([1, 2, 3]);
+ * const target = Observable.array([]);
+ * const unsync = source.sync(target);
+ * source.push(4); // target is now [1, 2, 3, 4]
+ * unsync();
+ */
 ObservableArray.prototype.sync = function(targetObservable) {
     if (!targetObservable || !targetObservable.__$isObservableArray) {
         throw new NativeDocumentError('ObservableArray.sync : target must be an ObservableArray');
@@ -439,10 +496,25 @@ ObservableArray.prototype.sync = function(targetObservable) {
     return () => this.unsubscribe(sync);
 };
 
+/**
+ * Creates a new ObservableArray with a shallow clone of the current array.
+ *
+ * @returns {ObservableArray} New independent ObservableArray with same items
+ */
 ObservableArray.prototype.clone = function() {
     return new ObservableArray(this.resolve());
 };
 
+/**
+ * Returns a derived ObservableChecker that emits true when the array has at least one item.
+ *
+ * @returns {ObservableChecker<boolean>}
+ * @example
+ * const items = Observable.array([]);
+ * items.isNotEmpty().val(); // false
+ * items.push(1);
+ * items.isNotEmpty().val(); // true
+ */
 ObservableArray.prototype.isNotEmpty = function () {
     return this.is((x) => x.length > 0);
 };

package/src/core/data/ObservableChecker.js

@@ -1,5 +1,5 @@
-import ObservableItem from "./ObservableItem";
-import PluginsManager from "../utils/plugins-manager";
+import ObservableItem from './ObservableItem';
+import PluginsManager from '../utils/plugins-manager';
 
 /**
  *