native-document 1.0.92 → 1.0.93

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/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/package.json

@@ -1,11 +1,11 @@
 {
   "name": "native-document",
-  "version": "1.0.92",
+  "version": "1.0.93",
   "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"
   },

package/readme.md

@@ -10,6 +10,7 @@
 NativeDocument combines the familiarity of vanilla JavaScript with the power of modern reactivity. No compilation, no virtual DOM, just pure JavaScript with an intuitive API.
 
 ## Why NativeDocument?
+> **Note**: NativeDocument works best with a bundler (Vite, Webpack, Rollup) for tree-shaking and optimal bundle size. The CDN version includes all features
 
 ### **Instant Start**
 ```html
@@ -18,7 +19,7 @@ NativeDocument combines the familiarity of vanilla JavaScript with the power of
 
 ### **Familiar API**
 ```javascript
-import { Div, Button } from 'native-document/src/elements';
+import { Div, Button } from 'native-document/elements';
 import { Observable } from 'native-document';
 
 // CDN
@@ -29,7 +30,6 @@ const count = Observable(0);
 
 const App = Div({ class: 'app' }, [
     Div([ 'Count ', count]),
-    // OR Div(`Count ${count}`),
     Button('Increment').nd.onClick(() => count.set(count.val() + 1))
 ]);
 
@@ -74,7 +74,7 @@ yarn add native-document
 ## Quick Example
 
 ```javascript
-import { Div, Input, Button, ShowIf, ForEach } from 'native-document/src/elements'
+import { Div, Input, Button, ShowIf, ForEach } from 'native-document/elements'
 import { Observable } from 'native-document'
 
 // CDN
@@ -105,7 +105,7 @@ const TodoApp = Div({ class: 'todo-app' }, [
             Input({ type: 'checkbox', checked: todo.done }),
             `${todo.text}`,
             Button('Delete').nd.onClick(() => todos.splice(index.val(), 1))
-        ]), /*item key (string | callback) */(item) => item),
+        ]), (item) => item.id ), // Key function - use unique identifier
 
     // Empty state
     ShowIf(
@@ -122,7 +122,7 @@ document.body.appendChild(TodoApp)
 ### Observables
 Reactive data that automatically updates the DOM:
 ```javascript
-import { Div } from 'native-document/src/elements'
+import { Div } from 'native-document/elements'
 import { Observable } from 'native-document'
 
 // CDN
@@ -135,16 +135,19 @@ const greeting = Observable.computed(() => `Hello ${user.$value.name}!`, [user])
 
 document.body.appendChild(Div(greeting));
 
-// user.name = 'Fausty'; // will not work
-// user.$value = { ...user.$value, name: ' Hermes!' }; // will work
-// user.set(data => ({ ...data, name: 'Hermes!' })); // will work
+// Direct mutation won't trigger updates
+user.name = 'Fausty';
+
+// These will trigger updates:
+user.$value = { ...user.$value, name: ' Hermes!' };
+user.set(data => ({ ...data, name: 'Hermes!' }));
 user.set({ ...user.val(), name: 'Hermes!' });
 ```
 
 ### Elements
 Familiar HTML element creation with reactive bindings:
 ```javascript
-import { Div, Button } from 'native-document/src/elements'
+import { Div, Button } from 'native-document/elements'
 import { Observable } from 'native-document'
 
 // CDN
@@ -185,6 +188,30 @@ When(condition)
     .otherwise(onFalse)
 ```
 
+### List Rendering
+Efficient rendering of lists with automatic updates:
+```javascript
+import { ForEach, Div } from 'native-document/elements'
+import { Observable } from 'native-document'
+
+const items = Observable.array(['Apple', 'Banana', 'Cherry'])
+
+ForEach(items, (item, index) => 
+    Div([index, '. ', item])
+)
+
+// With object arrays - use key function
+const users = Observable.array([
+    { id: 1, name: 'Alice' },
+    { id: 2, name: 'Bob' }
+])
+
+ForEach(users, (user) => 
+    Div(user.name),
+    (user) => user.id  // Key for efficient updates
+)
+```
+
 ## Documentation
 
 - **[Getting Started](docs/getting-started.md)** - Installation and first steps
@@ -198,10 +225,17 @@ When(condition)
 - **[Lifecycle Events](docs/lifecycle-events.md)** - Lifecycle events
 - **[NDElement](docs/native-document-element.md)** - Native Document Element
 - **[Extending NDElement](docs/extending-native-document-element.md)** - Custom Methods Guide
+- **[Advanced Components](docs/advanced-components.md)** - Template caching and singleton views
 - **[Args Validation](docs/validation.md)** - Function Argument Validation
 - **[Memory Management](docs/memory-management.md)** - Memory management
 - **[Anchor](docs/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
+
 
 ## Key Features Deep Dive
 
@@ -213,6 +247,8 @@ When(condition)
 
 ### Developer Experience
 ```javascript
+import { ArgTypes } from 'native-document'
+
 // Built-in debugging
 Observable.debug.enable()
 
@@ -221,12 +257,15 @@ const createUser = (function (name, age) {
   // Auto-validates argument types
 }).args(ArgTypes.string('name'), ArgTypes.number('age'))
 
-// Error boundaries
-const AppWithBoundayError = App.errorBoundary(() => {
-    return Div('Error in the Create User component');
-})
 
-document.body.appendChild(AppWithBoundayError());
+const SafeApp = App.errorBoundary((error, { caller, args }) => {
+    return Div({ class: 'error' }, [
+        'An error occurred: ',
+        error.message
+    ])
+});
+
+document.body.appendChild(SafeApp());
 ```
 
 ## Contributing

package/src/components/$traits/HasItems.js

@@ -1,22 +1,45 @@
 import {$} from "../../../index";
 
+/**
+ * Mixin for managing a collection of items with manipulation methods
+ * @class
+ */
 export default function HasItems() {}
 
+/**
+ * Sets a dynamic observable array to store items
+ * @param {ObservableArray?} [observableArray=null] - Observable array to use, or creates a new one if null
+ * @returns {HasItems}
+ */
 HasItems.prototype.dynamic = function(observableArray = null) {
     this.$description.items = observableArray || $.array([]);
     return this;
 };
 
+/**
+ * Replaces all existing items with a new array of items
+ * @param {Array} items - Array of new items
+ * @returns {HasItems}
+ */
 HasItems.prototype.items = function(items) {
     this.$description.items.splice(0, this.$description.items.length, ...items);
     return this;
 };
 
+/**
+ * Adds an item to the collection
+ * @param {*} item - The item to add
+ * @returns {HasItems}
+ */
 HasItems.prototype.item = function(item) {
     this.$description.items.push(item);
     return this;
 };
 
+/**
+ * Clears all items from the collection
+ * @returns {HasItems}
+ */
 HasItems.prototype.clear = function() {
     const items = this.$description.items;
     if(Array.isArray(items)) {
@@ -27,11 +50,29 @@ HasItems.prototype.clear = function() {
     return this;
 };
 
+/**
+ * Removes a specific item from the collection
+ * @param {*} item - The item to remove
+ * @returns {HasItems}
+ */
 HasItems.prototype.removeItem = function(item) {
-    // TODO: implement this method
+    const items = this.$description.items;
+    if(Array.isArray(items)) {
+        const index = items.indexOf(item);
+        if(index > -1) {
+            items.splice(index, 1);
+            return this;
+        }
+    }
+    items.removeItem(item);
     return this;
 };
 
+/**
+ * Sets the render function for items
+ * @param {(element: *) => ValidChildren} renderFn - Render function to apply
+ * @returns {HasItems}
+ */
 HasItems.prototype.render = function(renderFn) {
     this.$description.render = renderFn;
     return this;

package/src/components/BaseComponent.js

@@ -1,4 +1,7 @@
-
+/**
+ *
+ * @class
+ */
 export default function BaseComponent() {
 
 }