native-document 1.0.92 → 1.0.94

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() {
 
 }

package/src/components/accordion/Accordion.js

@@ -1,6 +1,18 @@
 import BaseComponent from "../BaseComponent";
 import EventEmitter from "../../../src/core/utils/EventEmitter";
 
+
+/**
+ * Valid children types that can be rendered in the DOM
+ * @typedef {HTMLElement|Text|DocumentFragment|string|Array<ValidChildren>} ValidChildren
+ */
+
+/**
+ * Component for creating accordion interfaces with expandable/collapsible items
+ * @param {{ items?: Array<AccordionItem>, multiple?: boolean, variant?: string, renderContent?: (field: Accordion) => HTMLElement }} config
+ * @returns {Accordion}
+ * @class
+ */
 export default function Accordion(config = {}) {
     if (!(this instanceof Accordion)) {
         return new Accordion(config);
@@ -19,20 +31,47 @@ BaseComponent.extends(Accordion, EventEmitter);
 
 Accordion.defaultTemplate = null;
 
-Accordion.use = function(template) {};
 
+/**
+ * Sets the default template for all Accordion instances
+ * @param {{accordion: (accordion: Accordion) => ValidChildren}} template - Template object containing accordion factory function
+ */
+Accordion.use = function(template) {
+    Accordion.defaultTemplate = template.accordion;
+};
+
+/**
+ * Adds an accordion item to the collection
+ * @param {AccordionItem} accordionItem - The accordion item to add
+ * @returns {Accordion}
+ */
 Accordion.prototype.item = function(accordionItem) {
     this.$description.items.push(accordionItem);
     return this;
 };
 
+/**
+ * Sets the accordion items collection
+ * @param {Array<AccordionItem>} items - Array of accordion items
+ * @returns {Accordion}
+ */
 Accordion.prototype.items = function(items) {
     this.$description.items = items;
     return this;
 };
 
+/**
+ * Alias for item method
+ * @param {AccordionItem} accordionItem - The accordion item to add
+ * @returns {Accordion}
+ */
 Accordion.prototype.addItem = Accordion.prototype.item;
 
+/**
+ * Removes an item by its id
+ * @param {string} id - The id of the item to remove
+ * @returns {Accordion}
+ */
 Accordion.prototype.removeItemById = function(id) {
     if (this.$description.items) {
         this.$description.items = this.$description.items.filter(item => item.id !== id);
@@ -40,40 +79,77 @@ Accordion.prototype.removeItemById = function(id) {
     return this;
 };
 
-Accordion.prototype.removeItem = function(item) {
+/**
+ * Removes items matching the filter function
+ * @param {Function} filter - Filter function to determine which items to keep
+ * @returns {Accordion}
+ */
+Accordion.prototype.remove = function(filter) {
     if (this.$description.items) {
-        this.$description.items = this.$description.items.filter(item);
+        this.$description.items = this.$description.items.filter(filter);
     }
     return this;
 };
 
-
+/**
+ * Enables or disables multiple items expansion
+ * @param {boolean} [enabled=true] - Whether multiple items can be expanded simultaneously
+ * @returns {Accordion}
+ */
 Accordion.prototype.multiple = function(enabled = true) {
     this.$description.multiple = enabled;
     return this;
 };
 
+/**
+ * Sets the variant style for the accordion
+ * @param {string} name - The variant name
+ * @returns {Accordion}
+ */
 Accordion.prototype.variant = function(name) {
     this.$description.variant = name;
     return this;
 };
 
+/**
+ * Sets the accordion variant to 'bordered'
+ * @returns {Accordion}
+ */
 Accordion.prototype.bordered = function() {
     return this.variant('bordered');
 };
 
+/**
+ * Sets the accordion variant to 'separated'
+ * @returns {Accordion}
+ */
 Accordion.prototype.separated = function() {
     return this.variant('separated');
 };
 
+/**
+ * Sets the accordion variant to 'flush'
+ * @returns {Accordion}
+ */
 Accordion.prototype.flush = function() {
     return this.variant('flush');
 };
 
+/**
+ * Retrieves an accordion item by its key
+ * @param {string} key - The key of the item to retrieve
+ * @returns {AccordionItem|undefined}
+ */
 Accordion.prototype.getByKey = function(key) {
     return this.$description.items.find(item => item.key === key);
 };
 
+/**
+ * Expands or collapses an accordion item by key
+ * @param {string} key - The key of the item
+ * @param {boolean} [state=true] - Whether to expand (true) or collapse (false)
+ * @returns {Accordion}
+ */
 Accordion.prototype.expanded = function(key, state = true) {
     const item = this.getByKey(key);
     if(item) {
@@ -86,35 +162,67 @@ Accordion.prototype.expanded = function(key, state = true) {
     return this;
 };
 
+/**
+ * Expands all accordion items
+ * @returns {Accordion}
+ */
 Accordion.prototype.expandAll = function() {
     this.$description.items.forEach(item => item.expanded(true));
     return this;
 };
 
+/**
+ * Collapses all accordion items
+ * @returns {Accordion}
+ */
 Accordion.prototype.collapseAll = function() {
     this.$description.items.forEach(item => item.expanded(false));
     return this;
 };
 
+/**
+ * Checks if an accordion item is expanded
+ * @param {string} key - The key of the item to check
+ * @returns {boolean|undefined}
+ */
 Accordion.prototype.isExpanded = function(key) {
     return this.getByKey(key)?.isExpanded?.();
 };
 
+/**
+ * Registers a handler for the expand event
+ * @param {Function} handler - The event handler
+ * @returns {Accordion}
+ */
 Accordion.prototype.onExpand = function(handler) {
     this.on('expand', handler);
     return this;
 };
 
+/**
+ * Registers a handler for the collapse event
+ * @param {Function} handler - The event handler
+ * @returns {Accordion}
+ */
 Accordion.prototype.onCollapse = function(handler) {
     this.on('collapse', handler);
     return this;
 };
 
+/**
+ * Sets the content render function
+ * @param {Function} renderFn - Function to render content
+ * @returns {Accordion}
+ */
 Accordion.prototype.renderContent = function(renderFn) {
     this.$description.renderContent = renderFn;
     return this;
 };
 
+/**
+ * Builds the accordion component
+ * @private
+ */
 Accordion.prototype.$build = function() {
     // TODO: Implementation
     // this.$description.items.forEach(item => {
@@ -126,8 +234,4 @@ Accordion.prototype.$build = function() {
     //         }
     //     });
     // });
-};
-
-Accordion.prototype.toNdElement = function() {
-    return this.$build();
 };

package/src/components/accordion/AccordionItem.js

@@ -1,6 +1,11 @@
 import { $ } from '../../../index';
 import BaseComponent from "../BaseComponent";
 
+/**
+ * Represents an individual item within an Accordion component
+ * @param {{ id?: string|number, title?: string, icon?: string, collapsible?: boolean, content?: ValidChildren, renderHeader?: Function, renderContent?: Function, render?: Function, expanded?: Observable<boolean>, disabled?: boolean }} config - Configuration object
+ * @class
+ */
 export default function AccordionItem(config = {}) {
     if(!(this instanceof AccordionItem)){
         return new AccordionItem()
@@ -23,42 +28,81 @@ export default function AccordionItem(config = {}) {
 
 BaseComponent.extends(AccordionItem);
 
+/**
+ * Gets the id of the accordion item
+ * @type {string}
+ */
 Object.defineProperty(AccordionItem.prototype, 'id', {
     get() {
         this.$description.id;
     }
 });
 
+/**
+ * Sets the identifier for the accordion item
+ * @param {string|number} id - The unique identifier
+ * @returns {AccordionItem}
+ */
 AccordionItem.prototype.identifyBy = function(id) {
     this.$description.id = id;
     return this;
 };
 
+/**
+ * Sets the content of the accordion item
+ * @param {ValidChildren} content - The content to display
+ * @returns {AccordionItem}
+ */
 AccordionItem.prototype.content = function(content) {
     this.$description.content = content;
     return this;
 };
 
+/**
+ * Sets the title of the accordion item
+ * @param {ValidChildren} title
+ * @returns {AccordionItem}
+ */
 AccordionItem.prototype.title = function(title) {
     this.$description.title = title;
     return this;
 };
 
+/**
+ * Sets the icon for the accordion item
+ * @param {ValidChildren} icon - The icon identifier or element
+ * @returns {AccordionItem}
+ */
 AccordionItem.prototype.icon = function(icon) {
     this.$description.icon = icon;
     return this;
 };
 
+/**
+ * Shows or hides the expansion indicator
+ * @param {boolean} [show=true] - Whether to show the indicator
+ * @returns {AccordionItem}
+ */
 AccordionItem.prototype.showIndicator = function(show = true) {
     this.$description.showIndicator = show;
     return this;
 }
 
+/**
+ * Sets whether the item can be collapsed
+ * @param {boolean} [collapsible=true] - Whether the item is collapsible
+ * @returns {AccordionItem}
+ */
 AccordionItem.prototype.collapsible = function(collapsible = true) {
     this.$description.collapsible = collapsible;
     return this;
 };
 
+/**
+ * Expands or collapses the accordion item
+ * @param {boolean} [expanded=true] - Whether to expand the item
+ * @returns {AccordionItem}
+ */
 AccordionItem.prototype.expanded = function(expanded = true) {
     this.$description.expanded.set(expanded);
     if (this.$description.expanded.val()) {
@@ -69,51 +113,96 @@ AccordionItem.prototype.expanded = function(expanded = true) {
     return this;
 };
 
+/**
+ * Toggles the expanded state of the accordion item
+ * @returns {AccordionItem}
+ */
 AccordionItem.prototype.toggle = function() {
     return this.expanded(!this.$description.expanded.val());
 };
 
+
+/**
+ * Sets the disabled state of the accordion item
+ * @param {boolean} [disabled=true] - Whether the item is disabled
+ * @returns {AccordionItem}
+ */
 AccordionItem.prototype.disabled = function(disabled = true) {
     this.$description.disabled = disabled;
     return this;
 };
 
+/**
+ * Checks if the accordion item is currently expanded
+ * @returns {boolean}
+ */
 AccordionItem.prototype.isExpanded = function() {
     return this.$description.expanded.val();
 };
+
+/**
+ * Registers a handler for the expand event
+ * @param {Function} handler - The event handler
+ * @returns {AccordionItem}
+ */
 AccordionItem.prototype.onExpand = function(handler) {
     this.on('expand', handler );
     return this;
 };
 
+/**
+ * Registers a handler for the collapse event
+ * @param {Function} handler - The event handler
+ * @returns {AccordionItem}
+ */
 AccordionItem.prototype.onCollapse = function(handler) {
     this.on('collapse', handler);
     return this;
 };
 
+/**
+ * Sets the header render function
+ * @param {Function} renderFn - Function to render the header
+ * @returns {AccordionItem}
+ */
 AccordionItem.prototype.renderHeader = function(renderFn) {
     this.$description.renderHeader = renderFn;
     return this;
 };
 
+/**
+ * Sets the content render function
+ * @param {Function} renderFn - Function to render the content
+ * @returns {AccordionItem}
+ */
 AccordionItem.prototype.renderContent = function(renderFn) {
     this.$description.renderContent = renderFn;
 };
 
+/**
+ * Sets the indicator render function
+ * @param {Function} renderFn - Function to render the indicator
+ * @returns {AccordionItem}
+ */
 AccordionItem.prototype.renderIndicator = function(renderFn) {
     this.$description.renderIndicator = renderFn;
     return this;
 };
 
+/**
+ * Sets the render function for the entire item
+ * @param {Function} renderFn - Function to render the item
+ * @returns {AccordionItem}
+ */
 AccordionItem.prototype.render = function(renderFn) {
     this.$description.render = renderFn;
     return this;
 }
 
+/**
+ * Builds the accordion item component
+ * @private
+ */
 AccordionItem.prototype.$build = function() {
 
 };
-
-AccordionItem.prototype.toNdElement = function() {
-
-}