lightview 1.8.2 → 2.0.0

package/docs/api/computed.html

@@ -0,0 +1,184 @@
+<!-- SEO-friendly SPA Shim -->
+<script src="/lightview-router.js"></script>
+<script>
+    if (window.LightviewRouter) {
+        LightviewRouter.base('/index.html');
+    }
+</script>
+
+<div class="docs-layout">
+    <aside class="docs-sidebar" src="./nav.html"></aside>
+
+    <main class="docs-content">
+        <h1>Computed</h1>
+        <p>
+            Computed values are derived from signals. They update automatically when their dependencies change.
+            Think of them as formulas that always stay in sync.
+        </p>
+
+        <h2>Basic Usage</h2>
+        <pre><code>const { signal, computed } = Lightview;
+
+const count = signal(10);
+const doubled = computed(() => count.value * 2);
+
+console.log(doubled.value);  // 20
+
+count.value = 5;
+console.log(doubled.value);  // 10 (automatically updated!)</code></pre>
+
+        <h2>Chaining Computed Values</h2>
+        <p>Computed values can depend on other computed values:</p>
+        <pre><code>const price = signal(100);
+const quantity = signal(2);
+const taxRate = signal(0.1);
+
+const subtotal = computed(() => price.value * quantity.value);
+const tax = computed(() => subtotal.value * taxRate.value);
+const total = computed(() => subtotal.value + tax.value);
+
+console.log(total.value);  // 220</code></pre>
+
+        <h2>Reading Computed Values</h2>
+        <pre><code>// Same as signals - two ways to read
+console.log(doubled.value);  // Property access
+console.log(doubled());      // Function call</code></pre>
+
+        <h2>In the UI</h2>
+        <p>
+            Computed values work seamlessly in your UI, just like signals:
+        </p>
+
+        <div class="code-example">
+            <div class="code-example-preview" id="computed-demo"></div>
+            <div class="code-example-code">
+                <pre><code>const price = signal(100);
+const quantity = signal(1);
+const total = computed(() => price.value * quantity.value);
+
+div(
+    p(() => `Price: $${price.value}`),
+    p(() => `Quantity: ${quantity.value}`),
+    p(() => `Total: $${total.value}`),
+    button({ onclick: () => quantity.value++ }, 'Add One')
+)</code></pre>
+            </div>
+        </div>
+
+        <h2>When to Use Computed</h2>
+        <ul>
+            <li><strong>Derived values</strong> — Calculations based on other state</li>
+            <li><strong>Formatting</strong> — Display formatting (dates, currency, etc.)</li>
+            <li><strong>Filtering/Sorting</strong> — Processed lists from raw data</li>
+            <li><strong>Validation</strong> — Form validity based on field values</li>
+        </ul>
+
+        <h3>Example: Filtered List</h3>
+        <pre><code>const todos = signal([
+    { text: 'Learn Lightview', done: true },
+    { text: 'Build something cool', done: false },
+    { text: 'Ship it', done: false }
+]);
+
+const filter = signal('all');  // 'all', 'active', 'done'
+
+const filteredTodos = computed(() => {
+    const list = todos.value;
+    switch (filter.value) {
+        case 'active': return list.filter(t => !t.done);
+        case 'done': return list.filter(t => t.done);
+        default: return list;
+    }
+});</code></pre>
+
+        <h3>Example: Form Validation</h3>
+        <pre><code>const email = signal('');
+const password = signal('');
+
+const isEmailValid = computed(() => 
+    /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email.value)
+);
+
+const isPasswordValid = computed(() => 
+    password.value.length >= 8
+);
+
+const canSubmit = computed(() => 
+    isEmailValid.value && isPasswordValid.value
+);
+
+button({ disabled: () => !canSubmit.value }, 'Submit')</code></pre>
+
+        <h2>Computed vs Effect</h2>
+        <p>
+            Both react to changes, but serve different purposes:
+        </p>
+        <table class="api-table">
+            <thead>
+                <tr>
+                    <th>Computed</th>
+                    <th>Effect</th>
+                </tr>
+            </thead>
+            <tbody>
+                <tr>
+                    <td>Returns a value</td>
+                    <td>Doesn't return anything useful</td>
+                </tr>
+                <tr>
+                    <td>Pure (no side effects)</td>
+                    <td>For side effects</td>
+                </tr>
+                <tr>
+                    <td>Lazy (computed when read)</td>
+                    <td>Eager (runs immediately)</td>
+                </tr>
+                <tr>
+                    <td>Use in UI for derived data</td>
+                    <td>Use for logging, storage, API calls</td>
+                </tr>
+            </tbody>
+        </table>
+    </main>
+</div>
+
+<script>
+    (function () {
+        const { signal, computed, tags } = Lightview;
+        const { div, p, button, span } = tags;
+
+        const price = signal(100);
+        const quantity = signal(1);
+        const total = computed(() => price.value * quantity.value);
+
+        const demo = div({ style: 'padding: 0.5rem;' },
+            div({ style: 'display: grid; gap: 0.5rem; margin-bottom: 1rem;' },
+                p({ style: 'margin: 0;' },
+                    span({ style: 'color: var(--site-text-secondary);' }, 'Price: '),
+                    span(() => `$${price.value}`)
+                ),
+                p({ style: 'margin: 0;' },
+                    span({ style: 'color: var(--site-text-secondary);' }, 'Quantity: '),
+                    span(() => quantity.value)
+                ),
+                p({ style: 'margin: 0; font-weight: 600; font-size: 1.125rem;' },
+                    span({ style: 'color: var(--site-text-secondary);' }, 'Total: '),
+                    span({ style: 'color: var(--site-primary);' }, () => `$${total.value}`)
+                )
+            ),
+            div({ style: 'display: flex; gap: 0.5rem;' },
+                button({
+                    onclick: () => quantity.value = Math.max(1, quantity.value - 1),
+                    style: 'padding: 0.5rem 1rem; cursor: pointer; border: 1px solid var(--site-border); background: var(--site-surface); border-radius: 6px;'
+                }, '−'),
+                button({
+                    onclick: () => quantity.value++,
+                    style: 'padding: 0.5rem 1rem; cursor: pointer; border: 1px solid var(--site-border); background: var(--site-surface); border-radius: 6px;'
+                }, '+')
+            )
+        );
+
+        const container = document.getElementById('computed-demo');
+        if (container) container.appendChild(demo.domEl);
+    })();
+</script>

package/docs/api/effects.html

@@ -0,0 +1,173 @@
+<!-- SEO-friendly SPA Shim -->
+<script src="/lightview-router.js"></script>
+<script>
+    if (window.LightviewRouter) {
+        LightviewRouter.base('/index.html');
+    }
+</script>
+
+<div class="docs-layout">
+    <aside class="docs-sidebar" src="./nav.html"></aside>
+    <main class="docs-content">
+        <h1>Effects</h1>
+        <p>
+            Effects let you run side effects when reactive state changes.
+            Logging, DOM manipulation, API calls—anything that needs to happen <em>because</em> something changed.
+        </p>
+
+        <h2>Basic Usage</h2>
+        <pre><code>const { signal, effect } = Lightview;
+
+const count = signal(0);
+
+// This runs immediately, then re-runs when count changes
+effect(() => {
+    console.log('Count is now:', count.value);
+});
+
+count.value = 1;  // Logs: "Count is now: 1"
+count.value = 2;  // Logs: "Count is now: 2"</code></pre>
+
+        <h2>Automatic Dependency Tracking</h2>
+        <p>
+            Effects automatically track which signals they read. No need to declare dependencies—Lightview figures it
+            out:
+        </p>
+        <pre><code>const firstName = signal('Alice');
+const lastName = signal('Smith');
+const showFull = signal(true);
+
+effect(() => {
+    if (showFull.value) {
+        // Tracks firstName, lastName, and showFull
+        console.log(`${firstName.value} ${lastName.value}`);
+    } else {
+        // Only tracks firstName and showFull
+        console.log(firstName.value);
+    }
+});</code></pre>
+
+        <h2>Stopping Effects</h2>
+        <p>
+            Effects return a stop function:
+        </p>
+        <pre><code>const count = signal(0);
+
+const stop = effect(() => {
+    console.log('Count:', count.value);
+});
+
+count.value = 1;  // Logs
+count.value = 2;  // Logs
+
+stop();  // Stop the effect
+
+count.value = 3;  // Nothing logged</code></pre>
+
+        <h2>Common Patterns</h2>
+
+        <h3>Syncing to External Systems</h3>
+        <pre><code>const theme = signal('light');
+
+effect(() => {
+    document.body.setAttribute('data-theme', theme.value);
+});</code></pre>
+
+        <h3>Local Storage Persistence</h3>
+        <pre><code>const settings = signal(
+    JSON.parse(localStorage.getItem('settings')) || {}
+);
+
+effect(() => {
+    localStorage.setItem('settings', JSON.stringify(settings.value));
+});</code></pre>
+
+        <h3>API Calls</h3>
+        <pre><code>const userId = signal(1);
+const userData = signal(null);
+
+effect(async () => {
+    const id = userId.value;
+    const response = await fetch(`/api/users/${id}`);
+    userData.value = await response.json();
+});</code></pre>
+
+        <h2>Effects vs Computed</h2>
+        <table class="api-table">
+            <thead>
+                <tr>
+                    <th>Use Case</th>
+                    <th>Use This</th>
+                </tr>
+            </thead>
+            <tbody>
+                <tr>
+                    <td>Derive a value from signals</td>
+                    <td><code>computed()</code></td>
+                </tr>
+                <tr>
+                    <td>Side effects (logging, API calls, DOM)</td>
+                    <td><code>effect()</code></td>
+                </tr>
+                <tr>
+                    <td>Value needed in UI</td>
+                    <td><code>computed()</code></td>
+                </tr>
+                <tr>
+                    <td>Just need to "do something"</td>
+                    <td><code>effect()</code></td>
+                </tr>
+            </tbody>
+        </table>
+
+        <div class="code-example">
+            <div class="code-example-preview" id="effect-demo"></div>
+            <div class="code-example-code">
+                <pre><code>const name = signal('World');
+const log = signal([]);
+
+effect(() => {
+    log.value = [...log.value, `Hello, ${name.value}!`].slice(-5);
+});
+
+// Change name to see the effect in action</code></pre>
+            </div>
+        </div>
+    </main>
+</div>
+
+<script>
+    (function () {
+        const { signal, effect, tags } = Lightview;
+        const { div, p, input, ul, li, label } = tags;
+
+        const name = signal('World');
+        const log = signal([]);
+
+        effect(() => {
+            const entry = `${new Date().toLocaleTimeString()} - Hello, ${name.value}!`;
+            log.value = [...log.value, entry].slice(-5);
+        });
+
+        const demo = div({ style: 'padding: 0.5rem;' },
+            div({ style: 'margin-bottom: 1rem;' },
+                label({ style: 'display: block; margin-bottom: 0.25rem; font-size: 0.875rem; color: var(--site-text-secondary);' }, 'Change name to trigger effect:'),
+                input({
+                    type: 'text',
+                    value: name.value,
+                    oninput: (e) => name.value = e.target.value,
+                    style: 'padding: 0.5rem; border: 1px solid var(--site-border); border-radius: 4px; width: 200px;'
+                })
+            ),
+            div(
+                p({ style: 'font-size: 0.875rem; color: var(--site-text-secondary); margin: 0 0 0.5rem;' }, 'Effect log (last 5):'),
+                ul({ style: 'margin: 0; padding-left: 1.25rem; font-family: var(--site-font-mono); font-size: 0.8125rem;' },
+                    () => log.value.map(entry => li(entry))
+                )
+            )
+        );
+
+        const container = document.getElementById('effect-demo');
+        if (container) container.appendChild(demo.domEl);
+    })();
+</script>

package/docs/api/elements.html

@@ -0,0 +1,180 @@
+<!-- SEO-friendly SPA Shim -->
+<script src="/lightview-router.js"></script>
+<script>
+    if (window.LightviewRouter) {
+        LightviewRouter.base('/index.html');
+    }
+</script>
+
+<link rel="stylesheet" href="../components/index.css">
+
+<div class="docs-layout">
+    <aside class="docs-sidebar" src="./nav.html"></aside>
+
+    <main class="docs-content">
+        <h1>Creating Elements</h1>
+        <p>
+            Lightview gives you three ways to build UI. Pick your favorite - or mix and match.
+            They all use the same reactive system under the hood.
+        </p>
+        <h2>Comparison</h2>
+        <table class="api-table">
+            <thead>
+                <tr>
+                    <th>Style</th>
+                    <th>Pros</th>
+                    <th>Cons</th>
+                </tr>
+            </thead>
+            <tbody>
+                <tr>
+                    <td><strong>Tagged API</strong></td>
+                    <td>Most concise, natural to write</td>
+                    <td>Requires destructuring</td>
+                </tr>
+                <tr>
+                    <td><strong>vDOM</strong></td>
+                    <td>JSON serializable, easy to validate</td>
+                    <td>Most verbose</td>
+                </tr>
+                <tr>
+                    <td><strong>Object DOM</strong></td>
+                    <td>Compact JSON, clean templates</td>
+                    <td>Harder to validate than explicit vDOM</td>
+                </tr>
+            </tbody>
+        </table>
+        <!-- Tabs -->
+        <script>
+            window.switchSyntaxTab = (tabId) => {
+                const tabs = ['tagged', 'vdom', 'object'];
+                tabs.forEach(t => {
+                    const tabEl = document.getElementById(`tab-btn-${t}`);
+                    const contentEl = document.getElementById(`syntax-${t}`);
+                    if (t === tabId) {
+                        tabEl.classList.add('syntax-tab-active');
+                        contentEl.style.display = 'block';
+                    } else {
+                        tabEl.classList.remove('syntax-tab-active');
+                        contentEl.style.display = 'none';
+                    }
+                });
+            };
+        </script>
+        <div role="tablist" class="syntax-tabs" style="margin-bottom: 1rem;">
+            <button id="tab-btn-tagged" role="tab" class="syntax-tab syntax-tab-active"
+                onclick="switchSyntaxTab('tagged')">Tagged API</button>
+            <button id="tab-btn-vdom" role="tab" class="syntax-tab" onclick="switchSyntaxTab('vdom')">vDOM</button>
+            <button id="tab-btn-object" role="tab" class="syntax-tab" onclick="switchSyntaxTab('object')">Object
+                DOM</button>
+        </div>
+
+        <!-- Tagged Syntax -->
+        <div id="syntax-tagged">
+            <pre><script>
+                examplify(document.currentScript.nextElementSibling, {
+                    at: document.currentScript.parentElement,
+                    scripts: ['/lightview.js', '/lightview-x.js'],
+                    type: 'module',
+                    minHeight: 120
+                });
+            </script><code contenteditable="true">const { signal, tags, $ } = Lightview;
+const { div, h1, p, button } = tags;
+const count = signal(0);
+const app = div({ class: 'container' },
+    h1('Hello Lightview'),
+    p(() => `Count: ${count.value}`),
+    button({ onclick: () => count.value++ }, 'Click me')
+);
+$('#example').content(app);</code></pre>
+        </div>
+
+        <!-- vDOM Syntax -->
+        <div id="syntax-vdom" style="display: none;">
+            <pre><script>
+                examplify(document.currentScript.nextElementSibling, {
+                    at: document.currentScript.parentElement,
+                    scripts: ['/lightview.js', '/lightview-x.js'],
+                    type: 'module',
+                    minHeight: 120
+                });
+            </script><code contenteditable="true">const { signal, element, $ } = Lightview;
+const count = signal(0);
+const app = { tag:'div', attributes: { class: 'container' }, children: [
+    { tag: 'h1', attributes: {}, children: ['Hello Lightview'] },
+    { tag: 'p', attributes: {}, children: [() => `Count: ${count.value}`] },
+    { tag: 'button', attributes: { onclick: () => count.value++ }, children: ['Click me'] }
+]};
+$('#example').content(app);</code></pre>
+        </div>
+
+        <!-- Object DOM Syntax -->
+        <div id="syntax-object" style="display: none;">
+            <pre><script>
+                examplify(document.currentScript.nextElementSibling, {
+                    at: document.currentScript.parentElement,
+                    scripts: ['/lightview.js', '/lightview-x.js'],
+                    type: 'module',
+                    minHeight: 120
+                });
+            </script><code contenteditable="true">const { signal, tags, $ } = Lightview;
+const { div } = tags;
+const count = signal(0);
+const app = { div: { class: 'container', children: [
+    { h1: { children: ['Hello Lightview'] } },
+    { p: { children: [() => `Count: ${count.value}`] } },
+    { button: { onclick: () => count.value++, children: ['Click me'] } }
+]}};
+$('#example').content(app);</code></pre>
+        </div>
+
+        <h2>Attributes & Events</h2>
+        <p>
+            Pass attributes as the first argument (Tagged API) or in the attributes object (others):
+        </p>
+        <pre><code>// Standard attributes
+div({ 
+    id: 'my-div',
+    class: 'container active',
+    style: 'color: red;',
+    'data-value': '42'
+})
+
+// Reactive attributes - use functions!
+div({
+    class: () => isActive.value ? 'active' : 'inactive',
+    style: () => `opacity: ${visible.value ? 1 : 0}`,
+    disabled: () => isLoading.value
+})
+
+// Event handlers - use "on" prefix
+button({
+    onclick: (e) => handleClick(e),
+    onmouseenter: () => setHovered(true),
+    onmouseleave: () => setHovered(false)
+})</code></pre>
+
+        <h2>Children</h2>
+        <p>
+            Children can be strings, numbers, elements, arrays, or functions:
+        </p>
+        <pre><code>div(
+    'Static text',                          // String
+    42,                                     // Number (converted to string)
+    span('Nested element'),                 // Element
+    () => `Dynamic: ${value.value}`,        // Reactive function
+    () => items.value.map(i => li(i.name)), // Reactive list
+    condition && span('Conditional')        // Conditional (falsy = not rendered)
+)</code></pre>
+
+        <h2>The domEl Property</h2>
+        <p>
+            Every Lightview element has a <code>domEl</code> property - the actual DOM node:
+        </p>
+        <pre><code>const myDiv = div({ class: 'box' }, 'Hello');
+
+// Access the real DOM element
+document.body.appendChild(myDiv.domEl);
+
+// You can also manipulate it directly
+myDiv.domEl.classList.add('another-class');</code></pre>