native-document 1.0.92 → 1.0.93

package/docs/conditional-rendering.md

@@ -102,6 +102,89 @@ HideIf(condition, content)
 ShowIf(condition.check(val => !val), content)
 ```
 
+## ShowWhen - Observable Value Matching
+
+`ShowWhen` is a specialized conditional function that shows content when an Observable matches a specific value. It's particularly useful for state machines and enum-based conditions.
+
+### Basic Usage
+```javascript
+const status = Observable('idle');
+
+// Show content when status equals 'loading'
+const loadingIndicator = ShowWhen(status, 'loading', 
+    Div({ class: 'spinner' }, 'Loading...')
+);
+
+// Show content when status equals 'success'
+const successMessage = ShowWhen(status, 'success',
+    Div({ class: 'success' }, '✅ Success!')
+);
+```
+
+### Two Syntax Options
+
+**Option 1: Three arguments (Observable, value, content)**
+```javascript
+const theme = Observable('light');
+
+ShowWhen(theme, 'dark', 
+    Div({ class: 'dark-mode-indicator' }, '🌙 Dark Mode')
+);
+```
+
+**Option 2: Two arguments (ObservableWhen result, content)**
+```javascript
+const theme = Observable('light');
+const isDark = theme.when('dark'); // Returns ObservableWhen
+
+ShowWhen(isDark,
+    Div({ class: 'dark-mode-indicator' }, '🌙 Dark Mode')
+);
+```
+
+### Practical Example: Status-Based UI
+```javascript
+const connectionStatus = Observable('disconnected');
+
+const StatusIndicator = Div({ class: 'status-bar' }, [
+    ShowWhen(connectionStatus, 'connecting',
+        Span({ class: 'status connecting' }, '🔄 Connecting...')
+    ),
+    ShowWhen(connectionStatus, 'connected',
+        Span({ class: 'status connected' }, '✅ Connected')
+    ),
+    ShowWhen(connectionStatus, 'disconnected',
+        Span({ class: 'status disconnected' }, '❌ Disconnected')
+    ),
+    ShowWhen(connectionStatus, 'error',
+        Span({ class: 'status error' }, '⚠️ Connection Error')
+    )
+]);
+
+// Update status
+setTimeout(() => connectionStatus.set('connecting'), 1000);
+setTimeout(() => connectionStatus.set('connected'), 3000);
+```
+
+Both can handle multiple states, but they serve different purposes:
+```javascript
+const phase = Observable('loading');
+
+// ShowWhen: Multiple independent conditions
+Div([
+    ShowWhen(phase, 'loading', LoadingSpinner()),
+    ShowWhen(phase, 'success', SuccessMessage()),
+    ShowWhen(phase, 'error', ErrorMessage())
+]);
+
+// Match: Single content area that switches
+Match(phase, {
+    loading: LoadingSpinner(),
+    success: SuccessMessage(),
+    error: ErrorMessage()
+});
+```
+
 ## Switch - Binary Content Switching
 
 `Switch` efficiently toggles between exactly two pieces of content based on a boolean condition:
@@ -627,6 +710,13 @@ Now that you understand conditional rendering, explore these related topics:
 - **[Lifecycle Events](lifecycle-events.md)** - Lifecycle events
 - **[NDElement](native-document-element.md)** - Native Document Element
 - **[Extending NDElement](extending-native-document-element.md)** - Custom Methods Guide
+- **[Advanced Components](advanced-components.md)** - Template caching and singleton views
 - **[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/core-concepts.md

@@ -376,7 +376,7 @@ function Header() {
     const user = Store.use('user');
     const theme = Store.use('theme');
     
-    return Div({ class: `theme-${theme}` }, [
+    return Div({ class: theme.check(t => `theme-${t}`) }, [
         ShowIf(user.check(u => u.isLoggedIn),
             Div(['Welcome, ', user.$value.name])
         )
@@ -512,6 +512,13 @@ Now that you understand NativeDocument's core concepts, explore these advanced t
 - **[Lifecycle Events](lifecycle-events.md)** - Lifecycle events
 - **[NDElement](native-document-element.md)** - Native Document Element
 - **[Extending NDElement](extending-native-document-element.md)** - Custom Methods Guide
+- **[Advanced Components](advanced-components.md)** - Template caching and singleton views
 - **[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/elements.md

@@ -66,7 +66,7 @@ const theme = Observable("dark");
 const greeting = Div({
   class: theme, // Updates when theme changes
   hidden: isVisible.check(val => !val) // Hide when isVisible is false
-}, `Hello ${userName}!`); // Reactive text content
+}, ['Hello ', userName, '!']); // Reactive text content
 
 // Reactive styles
 const box = Div({
@@ -142,6 +142,63 @@ const form = Form()
   });
 ```
 
+## Advanced Element Composition
+
+### Extending Elements with Custom Methods
+
+Use `.nd.with()` to add custom methods to elements:
+```javascript
+const customButton = Button("Click me")
+    .nd.with({
+        highlight() {
+            this.$element.style.backgroundColor = 'yellow';
+            return this;
+        },
+        resetStyle() {
+            this.$element.style.backgroundColor = '';
+            return this;
+        }
+    })
+    .highlight();
+
+// Chain custom methods
+customButton.resetStyle().highlight();
+```
+
+### Class and Style Accumulators
+
+Build classes and styles programmatically:
+```javascript
+import { classPropertyAccumulator, cssPropertyAccumulator } from 'native-document';
+
+// Class accumulator
+const classes = classPropertyAccumulator(['btn']);
+classes.add('primary');
+classes.add('large');
+
+const button = Button({ class: classes.value() }, "Submit");
+// Result: class="btn primary large"
+
+// Or with object
+const classObj = classPropertyAccumulator({ btn: true });
+classObj.add('primary', true);
+classObj.add('disabled', false);
+console.log(classObj.value()); // { btn: true, primary: true, disabled: false }
+
+// CSS accumulator
+const styles = cssPropertyAccumulator({ color: 'red' });
+styles.add('font-size', '16px');
+styles.add('margin', '10px');
+
+const element = Div({ style: styles.value() }, "Styled content");
+// Result: style="color: red; font-size: 16px; margin: 10px"
+
+// Or with array
+const styleArr = cssPropertyAccumulator('color: red; font-size: 16px');
+styleArr.add('margin', '10px');
+console.log(styleArr.value()); // "color: red; font-size: 16px; margin: 10px;"
+```
+
 ## Form Elements and Two-Way Binding
 
 ```javascript
@@ -214,6 +271,34 @@ const widget = Div("Widget")
         unmounted: element => console.log("Widget unmounted")
     });
 ```
+## Manual DOM Manipulation
+
+### Unmounting Children
+
+Remove all children from an element:
+```javascript
+const container = Div([
+    P("Child 1"),
+    P("Child 2"),
+    P("Child 3")
+]);
+
+// Remove all children
+container.nd.unmountChildren();
+// container is now empty but still in DOM
+```
+
+### Removing Elements
+
+Remove an element from the DOM:
+```javascript
+const element = Div("Content");
+document.body.appendChild(element.nd.node());
+
+// Remove from DOM
+element.nd.remove();
+// Element is detached from DOM
+```
 
 ## Element References
 
@@ -231,6 +316,37 @@ const app = Div([
 ]);
 ```
 
+## Shadow DOM
+
+NativeDocument supports Shadow DOM for encapsulated components:
+```javascript
+// Open shadow DOM (inspectable)
+const widget = Div("Widget content")
+    .nd.openShadow(`
+            :host {
+                display: block;
+                padding: 20px;
+                background: #f0f0f0;
+            }
+            p { color: blue; }
+        
+    `);
+
+// Closed shadow DOM (private)
+const privateWidget = Div("Private content")
+    .nd.closedShadow(`
+            p { color: red; }
+        
+    `);
+
+// Manual shadow DOM with mode
+const customWidget = Div("Custom")
+    .nd.shadow('open', `
+            /* Scoped styles */
+        
+    `);
+```
+
 ## Practical Example: Simple Button with Event
 
 ```javascript
@@ -281,6 +397,8 @@ const validateForm = () => {
 
     Observable.update(errors, newErrors);
 
+    errors.set(newErrors);
+
     return Object.values(newErrors).every(error => error === "");
 };
 
@@ -382,6 +500,13 @@ Now that you understand NativeDocument's elements, explore these advanced topics
 - **[Lifecycle Events](lifecycle-events.md)** - Lifecycle events
 - **[NDElement](native-document-element.md)** - Native Document Element
 - **[Extending NDElement](extending-native-document-element.md)** - Custom Methods Guide
+- **[Advanced Components](advanced-components.md)** - Template caching and singleton views
 - **[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/extending-native-document-element.md

@@ -265,4 +265,10 @@ Explore these related topics to build complete applications:
 
 - **[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