native-document 1.0.92 → 1.0.94

package/docs/observables.md

@@ -615,10 +615,12 @@ console.log(isAdult.val()); // true
 const data = Observable("test");
 
 // Create a subscription
-const unsubscribe = data.subscribe(value => console.log(value));
+const handler = value => console.log(value);
+data.subscribe(handler);
+
 
 // Clean up manually if needed
-unsubscribe();
+data.unsubscribe('test', handler);
 
 // Complete observable cleanup
 data.cleanup(); // Removes all listeners and prevents new subscriptions
@@ -626,9 +628,6 @@ data.cleanup(); // Removes all listeners and prevents new subscriptions
 // Manual trigger (useful for forcing updates)
 data.trigger(); // Notifies all subscribers without changing the value
 
-// Get original value (useful for reset functionality)
-console.log(data.originalValue()); // Returns the initial value
-
 // Extract values from any observable structure
 const complexData = Observable.object({
     user: "John",
@@ -637,6 +636,130 @@ const complexData = Observable.object({
 console.log(Observable.value(complexData)); // Plain object with extracted values
 ```
 
+## Utility Methods
+
+### `off(value, callback?)` - Remove Watchers
+
+Remove specific value watchers created with `.on()`:
+```javascript
+const status = Observable("idle");
+
+const loadingHandler = (isActive) => console.log("Loading:", isActive);
+status.on("loading", loadingHandler);
+
+// Remove specific callback
+status.off("loading", loadingHandler);
+
+// Remove all watchers for a value
+status.off("loading");
+```
+
+### `once(predicate, callback)` - Single-Time Listener
+
+Execute callback only once when condition is met:
+```javascript
+const count = Observable(0);
+
+// Wait for specific value
+count.once(5, (value) => {
+    console.log("Reached 5!"); // Only called once
+});
+
+// With predicate function
+count.once(val => val > 10, (value) => {
+    console.log("Greater than 10!"); // Only called once
+});
+
+count.set(5); // Callback fires and unsubscribes
+count.set(5); // Callback doesn't fire again
+```
+
+### `toggle()` - Boolean Toggle
+
+Toggle boolean observables:
+```javascript
+const isVisible = Observable(false);
+
+isVisible.toggle(); // true
+isVisible.toggle(); // false
+isVisible.toggle(); // true
+
+// Useful with buttons
+Button("Toggle").nd.onClick(() => isVisible.toggle());
+```
+
+### `reset()` - Reset to Initial Value
+
+Reset observable to its initial value (requires `reset: true` config):
+```javascript
+const name = Observable("Alice", { reset: true });
+
+name.set("Bob");
+console.log(name.val()); // "Bob"
+
+name.reset();
+console.log(name.val()); // "Alice" (initial value)
+
+// With objects
+const user = Observable({ name: "Alice", age: 25 }, { reset: true });
+user.set({ name: "Bob", age: 30 });
+user.reset(); // Back to { name: "Alice", age: 25 }
+```
+
+### `equals(other)` - Value Comparison
+
+Compare observable values:
+```javascript
+const num1 = Observable(5);
+const num2 = Observable(5);
+const num3 = Observable(10);
+
+console.log(num1.equals(num2)); // true (same value)
+console.log(num1.equals(5));    // true (compare with raw value)
+console.log(num1.equals(num3)); // false
+```
+
+### `toBool()` - Boolean Conversion
+
+Convert observable value to boolean:
+```javascript
+const text = Observable("");
+console.log(text.toBool()); // false
+
+text.set("Hello");
+console.log(text.toBool()); // true
+
+// Useful for conditions
+const hasContent = text.toBool();
+```
+
+### `intercept(callback)` - Value Interception
+
+Intercept and modify values before they're set:
+```javascript
+const age = Observable(0);
+
+// Intercept sets to enforce constraints
+age.intercept((newValue, oldValue) => {
+    if (newValue < 0) return 0;
+    if (newValue > 120) return 120;
+    return newValue;
+});
+
+age.set(-5);  // Actually sets 0
+age.set(150); // Actually sets 120
+age.set(25);  // Sets 25
+
+// Practical example: sanitize input
+const username = Observable("");
+username.intercept((value) => {
+    return value.toLowerCase().trim();
+});
+
+username.set("  JohnDoe  "); 
+console.log(username.val()); // "johndoe"
+```
+
 ## Best Practices
 
 1. **Use descriptive names** for your observables
@@ -663,4 +786,10 @@ Now that you understand NativeDocument's observable, explore these advanced topi
 - **[Extending NDElement](extending-native-document-element.md)** - Custom Methods Guide
 - **[Args Validation](validation.md)** - Function Argument Validation
 - **[Memory Management](memory-management.md)** - Memory management
-- **[Anchor](anchor.md)** - Anchor
+- **[Anchor](anchor.md)** - Anchor
+
+## Utilities
+
+- **[Cache](docs/utils/cache.md)** - Lazy initialization and singleton patterns
+- **[NativeFetch](docs/utils/native-fetch.md)** - HTTP client with interceptors
+- **[Filters](docs/utils/filters.md)** - Data filtering helpers

package/docs/routing.md

@@ -817,4 +817,10 @@ Explore these related topics to build complete applications:
 - **[Extending NDElement](extending-native-document-element.md)** - Custom Methods Guide
 - **[Args Validation](validation.md)** - Function Argument Validation
 - **[Memory Management](memory-management.md)** - Memory management
-- **[Anchor](anchor.md)** - Anchor
+- **[Anchor](anchor.md)** - Anchor
+
+## Utilities
+
+- **[Cache](docs/utils/cache.md)** - Lazy initialization and singleton patterns
+- **[NativeFetch](docs/utils/native-fetch.md)** - HTTP client with interceptors
+- **[Filters](docs/utils/filters.md)** - Data filtering helpers

package/docs/state-management.md

@@ -423,4 +423,10 @@ Now that you understand state management, explore these related topics:
 - **[Extending NDElement](extending-native-document-element.md)** - Custom Methods Guide
 - **[Args Validation](validation.md)** - Function Argument Validation
 - **[Memory Management](memory-management.md)** - Memory management
-- **[Anchor](anchor.md)** - Anchor
+- **[Anchor](anchor.md)** - Anchor
+
+## Utilities
+
+- **[Cache](docs/utils/cache.md)** - Lazy initialization and singleton patterns
+- **[NativeFetch](docs/utils/native-fetch.md)** - HTTP client with interceptors
+- **[Filters](docs/utils/filters.md)** - Data filtering helpers

package/docs/validation.md

@@ -190,4 +190,11 @@ registerUser.args(
 - **[Lifecycle Events](lifecycle-events.md)** - Validate lifecycle callback arguments
 - **[NDElement](native-document-element.md)** - Native Document Element
 - **[Extending NDElement](extending-native-document-element.md)** - Custom Methods Guide
-- **[Memory Management](memory-management.md)** - Debugging memory issues with validation
+- **[Advanced Components](advanced-components.md)** - Template caching and singleton views
+- **[Memory Management](memory-management.md)** - Debugging memory issues with validation
+
+## Utilities
+
+- **[Cache](docs/utils/cache.md)** - Lazy initialization and singleton patterns
+- **[NativeFetch](docs/utils/native-fetch.md)** - HTTP client with interceptors
+- **[Filters](docs/utils/filters.md)** - Data filtering helpers

package/elements.js

@@ -1,3 +1,4 @@
+import './index.def';
 import Anchor from "./src/core/elements/anchor";
 export { createPortal } from "./src/core/elements/anchor";
 export * from './src/core/elements/index';

package/eslint.config.js

@@ -3,18 +3,18 @@ import globals from 'globals'
 
 export default [
   { ignores: ['dist'] },
+  js.configs.recommended,
   {
     files: ['**/*.{js}'],
     languageOptions: {
-      ecmaVersion: 2020,
+      ecmaVersion: 'latest',
       globals: globals.browser,
       parserOptions: {
         ecmaVersion: 'latest',
         sourceType: 'module',
       },
     },
-    plugins: {
-    },
+    plugins: {},
     rules: {
       ...js.configs.recommended.rules,
     },

package/index.def.js

@@ -0,0 +1,350 @@
+/**
+ * @fileoverview JSDoc type definitions for NativeDocument HTML elements.
+ * Provides IDE autocomplete for element attributes.
+ * Compound attribute names are listed in both their original (lowercase)
+ * and camelCase forms so both conventions trigger autocomplete.
+ */
+
+// ─────────────────────────────────────────────
+// Base types
+// ─────────────────────────────────────────────
+
+/**
+ * An ObservableItem or a raw value.
+ * @template T
+ * @typedef {import('./native-document.dev').ObservableItem | T} Observable
+ */
+
+/**
+ * A valid child — string, number, boolean, HTMLElement, DocumentFragment,
+ * ObservableItem, NDElement, or an array of those.
+ * @typedef {string|number|boolean|HTMLElement|DocumentFragment|ObservableItem|NDElement|Array} NdChild
+ */
+
+/**
+ * Reactive class binding — maps class names to observable or plain booleans.
+ * @typedef {Object.<string, Observable<boolean>|boolean>} NdClassMap
+ */
+
+/**
+ * Reactive style binding — maps CSS property names to observable or plain strings.
+ * @typedef {Object.<string, Observable<string>|string>} NdStyleMap
+ */
+
+// ─────────────────────────────────────────────
+// Shared attribute sets
+// ─────────────────────────────────────────────
+
+/**
+ * Global HTML attributes shared by all elements.
+ * @typedef {Object} GlobalAttributes
+ * @property {Observable<string>|string}             [id]               - Unique identifier
+ * @property {Observable<string>|NdClassMap|string}  [class]            - CSS classes (string or reactive map)
+ * @property {Observable<NdStyleMap>|NdStyleMap}     [style]            - Inline styles
+ * @property {string}                                [title]            - Tooltip text
+ * @property {string}                                [lang]             - Language code
+ * @property {string}                                [dir]              - Text direction: 'ltr'|'rtl'|'auto'
+ * @property {Observable<boolean>|boolean}           [hidden]           - Hide element
+ * @property {Observable<boolean>|boolean}           [draggable]        - Make element draggable
+ * @property {Observable<boolean>|boolean}           [contenteditable]  - Make content editable
+ * @property {Observable<boolean>|boolean}           [contentEditable]  - Make content editable (camelCase)
+ * @property {string}                                [tabindex]         - Tab order
+ * @property {string}                                [tabIndex]         - Tab order (camelCase)
+ * @property {string}                                [accesskey]        - Keyboard shortcut
+ * @property {string}                                [accessKey]        - Keyboard shortcut (camelCase)
+ * @property {Observable<boolean>|boolean}           [spellcheck]       - Enable spellcheck
+ * @property {Observable<boolean>|boolean}           [spellCheck]       - Enable spellcheck (camelCase)
+ * @property {string}                                [data-*]           - Custom data attributes
+ * @property {string}                                [aria-*]           - ARIA accessibility attributes
+ * @property {string}                                [role]             - ARIA role
+ */
+
+/**
+ * Attributes shared by form-related elements.
+ * @typedef {Object} SharedFormAttributes
+ * @property {string}                       [name]       - Field name
+ * @property {Observable<boolean>|boolean}  [disabled]   - Disable the field
+ * @property {Observable<boolean>|boolean}  [required]   - Mark as required
+ * @property {Observable<boolean>|boolean}  [autofocus]  - Auto-focus on page load
+ * @property {Observable<boolean>|boolean}  [autoFocus]  - Auto-focus on page load (camelCase)
+ * @property {string}                       [form]       - Associated form id
+ */
+
+// ─────────────────────────────────────────────
+// Element-specific attribute types
+// ─────────────────────────────────────────────
+
+/**
+ * @typedef {GlobalAttributes & {
+ *   src:              Observable<string>|string,
+ *   alt:              Observable<string>|string,
+ *   width:            Observable<string>|string|number,
+ *   height:           Observable<string>|string|number,
+ *   loading:          'lazy'|'eager'|'auto',
+ *   decoding:         'async'|'sync'|'auto',
+ *   srcset:           string,
+ *   srcSet:           string,
+ *   sizes:            string,
+ *   crossorigin:      'anonymous'|'use-credentials',
+ *   crossOrigin:      'anonymous'|'use-credentials',
+ *   referrerpolicy:   string,
+ *   referrerPolicy:   string,
+ *   fetchpriority:    'high'|'low'|'auto',
+ *   fetchPriority:    'high'|'low'|'auto',
+ * }} ImgAttributes
+ */
+
+/**
+ * @typedef {GlobalAttributes & {
+ *   href:             Observable<string>|string,
+ *   target:           '_blank'|'_self'|'_parent'|'_top'|string,
+ *   rel:              string,
+ *   download:         Observable<boolean>|boolean|string,
+ *   hreflang:         string,
+ *   hrefLang:         string,
+ *   type:             string,
+ *   referrerpolicy:   string,
+ *   referrerPolicy:   string,
+ * }} AnchorAttributes
+ */
+
+/**
+ * @typedef {GlobalAttributes & SharedFormAttributes & {
+ *   type:   'button'|'submit'|'reset',
+ *   value:  Observable<string>|string,
+ * }} ButtonAttributes
+ */
+
+/**
+ * @typedef {GlobalAttributes & SharedFormAttributes & {
+ *   type:           'text'|'email'|'password'|'number'|'tel'|'url'|'search'|
+ *                   'date'|'time'|'datetime-local'|'week'|'month'|
+ *                   'checkbox'|'radio'|'range'|'color'|'file'|'hidden',
+ *   value:          Observable<string>|string,
+ *   placeholder:    Observable<string>|string,
+ *   checked:        Observable<boolean>|boolean,
+ *   readonly:       Observable<boolean>|boolean,
+ *   readOnly:       Observable<boolean>|boolean,
+ *   multiple:       Observable<boolean>|boolean,
+ *   min:            Observable<string>|string|number,
+ *   max:            Observable<string>|string|number,
+ *   step:           Observable<string>|string|number,
+ *   minlength:      number,
+ *   minLength:      number,
+ *   maxlength:      number,
+ *   maxLength:      number,
+ *   pattern:        string,
+ *   accept:         string,
+ *   autocomplete:   'on'|'off'|string,
+ *   autoComplete:   'on'|'off'|string,
+ *   list:           string,
+ * }} InputAttributes
+ */
+
+/**
+ * @typedef {GlobalAttributes & SharedFormAttributes & {
+ *   value:          Observable<string>|string,
+ *   placeholder:    Observable<string>|string,
+ *   readonly:       Observable<boolean>|boolean,
+ *   readOnly:       Observable<boolean>|boolean,
+ *   rows:           number,
+ *   cols:           number,
+ *   minlength:      number,
+ *   minLength:      number,
+ *   maxlength:      number,
+ *   maxLength:      number,
+ *   wrap:           'hard'|'soft'|'off',
+ *   autocomplete:   'on'|'off'|string,
+ *   autoComplete:   'on'|'off'|string,
+ *   spellcheck:     Observable<boolean>|boolean,
+ *   spellCheck:     Observable<boolean>|boolean,
+ * }} TextAreaAttributes
+ */
+
+/**
+ * @typedef {GlobalAttributes & SharedFormAttributes & {
+ *   value:    Observable<string>|string,
+ *   multiple: Observable<boolean>|boolean,
+ *   size:     number,
+ * }} SelectAttributes
+ */
+
+/**
+ * @typedef {GlobalAttributes & {
+ *   value:    Observable<string>|string,
+ *   selected: Observable<boolean>|boolean,
+ *   disabled: Observable<boolean>|boolean,
+ * }} OptionAttributes
+ */
+
+/**
+ * @typedef {GlobalAttributes & SharedFormAttributes & {
+ *   action:       string,
+ *   method:       'get'|'post',
+ *   enctype:      'application/x-www-form-urlencoded'|'multipart/form-data'|'text/plain',
+ *   encType:      'application/x-www-form-urlencoded'|'multipart/form-data'|'text/plain',
+ *   novalidate:   Observable<boolean>|boolean,
+ *   noValidate:   Observable<boolean>|boolean,
+ *   target:       '_blank'|'_self'|'_parent'|'_top'|string,
+ *   autocomplete: 'on'|'off',
+ *   autoComplete: 'on'|'off',
+ * }} FormAttributes
+ */
+
+/**
+ * @typedef {GlobalAttributes & {
+ *   src:            Observable<string>|string,
+ *   autoplay:       Observable<boolean>|boolean,
+ *   autoPlay:       Observable<boolean>|boolean,
+ *   controls:       Observable<boolean>|boolean,
+ *   loop:           Observable<boolean>|boolean,
+ *   muted:          Observable<boolean>|boolean,
+ *   preload:        'auto'|'metadata'|'none',
+ *   width:          Observable<string>|string|number,
+ *   height:         Observable<string>|string|number,
+ *   poster:         string,
+ *   playsinline:    Observable<boolean>|boolean,
+ *   playsInline:    Observable<boolean>|boolean,
+ *   crossorigin:    'anonymous'|'use-credentials',
+ *   crossOrigin:    'anonymous'|'use-credentials',
+ * }} VideoAttributes
+ */
+
+/**
+ * @typedef {GlobalAttributes & {
+ *   src:            Observable<string>|string,
+ *   autoplay:       Observable<boolean>|boolean,
+ *   autoPlay:       Observable<boolean>|boolean,
+ *   controls:       Observable<boolean>|boolean,
+ *   loop:           Observable<boolean>|boolean,
+ *   muted:          Observable<boolean>|boolean,
+ *   preload:        'auto'|'metadata'|'none',
+ *   crossorigin:    'anonymous'|'use-credentials',
+ *   crossOrigin:    'anonymous'|'use-credentials',
+ * }} AudioAttributes
+ */
+
+/**
+ * @typedef {GlobalAttributes & {
+ *   width:  Observable<string>|string|number,
+ *   height: Observable<string>|string|number,
+ * }} CanvasAttributes
+ */
+
+/**
+ * @typedef {GlobalAttributes & {
+ *   open: Observable<boolean>|boolean,
+ * }} DetailsAttributes
+ */
+
+/**
+ * @typedef {GlobalAttributes & {
+ *   open: Observable<boolean>|boolean,
+ * }} DialogAttributes
+ */
+
+/**
+ * @typedef {GlobalAttributes & {
+ *   value: Observable<string>|string|number,
+ *   max:   number,
+ * }} ProgressAttributes
+ */
+
+/**
+ * @typedef {GlobalAttributes & {
+ *   value:   Observable<string>|string|number,
+ *   min:     number,
+ *   max:     number,
+ *   low:     number,
+ *   high:    number,
+ *   optimum: number,
+ * }} MeterAttributes
+ */
+
+/**
+ * @typedef {GlobalAttributes & {
+ *   src:   string,
+ *   type:  string,
+ *   media: string,
+ * }} SourceAttributes
+ */
+
+/**
+ * @typedef {GlobalAttributes & {
+ *   colspan:  number,
+ *   colSpan:  number,
+ *   rowspan:  number,
+ *   rowSpan:  number,
+ *   headers:  string,
+ *   scope:    'row'|'col'|'rowgroup'|'colgroup',
+ * }} ThAttributes
+ */
+
+/**
+ * @typedef {GlobalAttributes & {
+ *   colspan:  number,
+ *   colSpan:  number,
+ *   rowspan:  number,
+ *   rowSpan:  number,
+ *   headers:  string,
+ * }} TdAttributes
+ */
+
+/**
+ * @typedef {GlobalAttributes & {
+ *   for:      string,
+ *   htmlFor:  string,
+ * }} LabelAttributes
+ */
+
+/**
+ * @typedef {GlobalAttributes & {
+ *   for:   string,
+ *   form:  string,
+ *   name:  string,
+ * }} OutputAttributes
+ */
+
+/**
+ * @typedef {GlobalAttributes & {
+ *   datetime: string,
+ *   dateTime: string,
+ * }} TimeAttributes
+ */
+
+/**
+ * @typedef {GlobalAttributes & {
+ *   cite:     string,
+ *   datetime: string,
+ *   dateTime: string,
+ * }} ModAttributes
+ */
+
+/**
+ * @typedef {GlobalAttributes & {
+ *   reversed: Observable<boolean>|boolean,
+ *   start:    number,
+ *   type:     '1'|'a'|'A'|'i'|'I',
+ * }} OlAttributes
+ */
+
+/**
+ * @typedef {GlobalAttributes & {
+ *   viewBox:  string,
+ *   viewbox:  string,
+ *   xmlns:    string,
+ *   width:    Observable<string>|string|number,
+ *   height:   Observable<string>|string|number,
+ * }} SvgAttributes
+ */
+
+/**
+ * @typedef {GlobalAttributes & {
+ *   src:      string,
+ *   kind:     'subtitles'|'captions'|'descriptions'|'chapters'|'metadata',
+ *   srclang:  string,
+ *   srcLang:  string,
+ *   label:    string,
+ *   default:  Observable<boolean>|boolean,
+ * }} TrackAttributes
+ */

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "native-document",
-  "version": "1.0.92",
+  "version": "1.0.94",
   "main": "index.js",
   "type": "module",
   "scripts": {
     "build": "rollup --config rollup.config.js --watch",
-    "lint": "eslint ."
+    "lint": "eslint ./src"
   },
   "keywords": [],
   "author": "",
@@ -18,6 +18,7 @@
     "@rollup/plugin-replace": "^6.0.2",
     "@rollup/plugin-terser": "^0.4.4",
     "eslint": "^9.33.0",
+    "eslint-plugin-jsdoc": "^62.5.4",
     "magic-string": "^0.30.21",
     "rollup": "^4.53.3"
   },