lightview 1.8.2 → 2.0.1

package/docs/api/signals.html

@@ -0,0 +1,136 @@
+<!-- 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>Signals</h1>
+        <p>
+            Signals are the heart of Lightview's reactivity. They hold values that can change over time,
+            and automatically notify anything that depends on them.
+        </p>
+
+        <h2>Creating Signals</h2>
+        <pre><code>const { signal } = Lightview;
+
+// Create a signal with an initial value
+const count = signal(0);
+const name = signal('World');
+const items = signal([]);
+const user = signal({ name: 'Alice', age: 25 });</code></pre>
+
+        <h2>Reading Values</h2>
+        <pre><code>// Two ways to read
+console.log(count.value);  // Property access: 0
+console.log(count());      // Function call: 0
+
+// Both work identically - pick your style</code></pre>
+
+        <h2>Writing Values</h2>
+        <pre><code>// Two ways to write
+count.value = 5;           // Property assignment
+count(10);                 // Function call with argument
+
+// Both trigger reactive updates</code></pre>
+
+        <h2>Reactive UI</h2>
+        <p>
+            The magic happens when you use signals in your UI. Wrap expressions in functions to make them reactive:
+        </p>
+        <pre><code>const { signal, tags } = Lightview;
+const { div, p, button } = tags;
+
+const count = signal(0);
+
+// Static - won't update
+p(`Count: ${count.value}`)  // ❌ "Count: 0" forever
+
+// Reactive - updates automatically
+p(() => `Count: ${count.value}`)  // ✅ Updates when count changes!</code></pre>
+
+        <div class="code-example">
+            <div class="code-example-preview" id="signal-demo"></div>
+            <div class="code-example-code">
+                <pre><code>const count = signal(0);
+
+div(
+    p(() => `Count: ${count.value}`),
+    button({ onclick: () => count.value++ }, '+1')
+)</code></pre>
+            </div>
+        </div>
+
+        <h2>Named Signals</h2>
+        <p>
+            You can give signals a name for easy access across your application:
+        </p>
+        <pre><code>// Create a named signal and keep it in sessionStorage
+const count = signal(0, 'count');
+
+// Retrieve it elsewhere (even in another file)
+const sameCount = signal.get('count');
+
+// Get or create with default value
+// If ' ' exists, returns it. If not, creates it with 100.
+const score = signal.get('count', 0);</code></pre>
+
+        <h2>Stored Signals</h2>
+        <p>
+            You can store named signals in Storage objects (e.g. sessionStorage or localStorage) for persistence. It
+            will be saved any time there is a change.
+        </p>
+        <pre><code>const count = signal(0, {name:'count', storage:sessionStorage});
+
+// Retrieve it elsewhere (even in another file)
+const sameCount = signal.get('count');
+
+// Get or create with default value
+// If ' ' exists, returns it. If not, creates it with 100.
+const score = signal.get('count', {storage:sessionStorage, defaultValue:0});</code></pre>
+        <p>Note: Manually updating the value in storage will not trigger updates.</p>
+
+        <h2>Tips & Patterns</h2>
+
+        <h3>Derived State</h3>
+        <p>For values computed from signals, use <a href="./computed">computed()</a> instead:</p>
+        <pre><code>const count = signal(0);
+const doubled = computed(() => count.value * 2);  // Auto-updates</code></pre>
+
+        <h3>Objects & Arrays</h3>
+        <p>For deep reactivity on objects/arrays, consider <a href="./state">state()</a>:</p>
+        <pre><code>// Signal: only triggers on reassignment
+const items = signal([1, 2, 3]);
+items.value.push(4);        // ❌ Won't trigger update
+items.value = [...items.value, 4];  // ✅ Triggers update
+
+// State: deep reactivity
+const items = state([1, 2, 3]);
+items.push(4);              // ✅ Triggers update automatically</code></pre>
+    </main>
+</div>
+
+<script>
+    (function () {
+        const { signal, tags } = Lightview;
+        const { div, p, button } = tags;
+
+        const count = signal(0);
+
+        const demo = div({ style: 'display: flex; align-items: center; gap: 1rem;' },
+            p({ style: 'margin: 0; font-size: 1.25rem;' }, () => `Count: ${count.value}`),
+            button({
+                onclick: () => count.value++,
+                style: 'padding: 0.5rem 1rem; cursor: pointer; background: var(--site-primary); color: white; border: none; border-radius: 6px;'
+            }, '+1')
+        );
+
+        const container = document.getElementById('signal-demo');
+        if (container) container.appendChild(demo.domEl);
+    })();
+</script>

package/docs/api/state.html

@@ -0,0 +1,217 @@
+<!-- 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>State (Store)</h1>
+        <p>
+            State provides deep reactivity for objects and arrays. Unlike signals which only track reassignment,
+            state tracks nested property changes automatically.
+        </p>
+
+        <h2>The Problem with Signals + Objects</h2>
+        <pre><code>// Signals only react to reassignment
+const user = signal({ name: 'Alice', age: 25 });
+
+user.value.age = 26;           // ❌ Won't trigger updates!
+user.value = { ...user.value, age: 26 };  // ✅ Works, but verbose
+
+// Arrays have the same issue
+const items = signal([1, 2, 3]);
+items.value.push(4);           // ❌ Won't trigger updates!
+items.value = [...items.value, 4];  // ✅ Works, but tedious</code></pre>
+
+        <h2>State to the Rescue</h2>
+        <pre><code>const { state } = LightviewX;
+
+// Deep reactivity - mutations work!
+const user = state({ name: 'Alice', age: 25 });
+
+user.age = 26;                 // ✅ Triggers updates!
+user.name = 'Bob';             // ✅ Triggers updates!
+
+// Arrays just work
+const items = state([1, 2, 3]);
+items.push(4);                 // ✅ Triggers updates!
+items[0] = 10;                 // ✅ Triggers updates!
+items.sort();                  // ✅ Triggers updates!</code></pre>
+
+        <h2>Nested Objects</h2>
+        <p>State tracks changes at any depth:</p>
+        <pre><code>const app = state({
+    user: {
+        profile: {
+            name: 'Alice',
+            settings: {
+                theme: 'dark',
+                notifications: true
+            }
+        }
+    },
+    items: []
+});
+
+// All of these trigger updates:
+app.user.profile.name = 'Bob';
+app.user.profile.settings.theme = 'light';
+app.items.push({ id: 1, text: 'Hello' });</code></pre>
+
+        <h2>In the UI</h2>
+
+        <div class="code-example">
+            <div class="code-example-preview" id="state-demo"></div>
+            <div class="code-example-code">
+                <pre><code>const todos = state([
+    { text: 'Learn Lightview', done: true },
+    { text: 'Build app', done: false }
+]);
+
+div(
+    ul(() => todos.map((todo, i) => 
+        li(
+            input({ 
+                type: 'checkbox', 
+                checked: todo.done,
+                onchange: () => todos[i].done = !todos[i].done
+            }),
+            span(todo.text)
+        )
+    )),
+    button({ onclick: () => todos.push({ text: 'New', done: false }) }, 'Add')
+)</code></pre>
+            </div>
+        </div>
+
+        <h2>Array Methods</h2>
+        <p>All mutating array methods are reactive:</p>
+        <pre><code>const items = state([1, 2, 3]);
+
+items.push(4);         // Add to end
+items.pop();           // Remove from end
+items.shift();         // Remove from start
+items.unshift(0);      // Add to start
+items.splice(1, 1);    // Remove at index
+items.sort();          // Sort in place
+items.reverse();       // Reverse in place
+items.fill(0);         // Fill with value</code></pre>
+
+        <h2>Named State</h2>
+        <p>
+            Like signals, you can name state objects for global access. This is especially useful for
+            shared application state:
+        </p>
+        <pre><code>// Create named state
+const appState = state({ 
+    user: 'Guest', 
+    theme: 'dark' 
+}, 'app');
+
+// Retrieve it anywhere
+const globalState = state.get('app');
+
+// Get or create
+const settings = state.get('settings', { notifications: true });</code></pre>
+
+        <h2>Stored State</h2>
+        <p>
+            You can store named state objects in Storage objects (e.g. sessionStorage or localStorage) for persistence.
+            It will be saved any time there is a change. Objects are automatically
+            serialized to JSON and deserialized back to objects.
+        </p>
+        <pre><code>const user = state({name:'Guest', theme:'dark'}, {name:'user', storage:sessionStorage});
+
+// Retrieve it elsewhere (even in another file)
+const sameUser = state.get('user');
+
+// Get or create with default value
+// If 'user' exists, returns it. If not, creates it with default value.
+const score = state.get('user', {storage:sessionStorage, defaultValue:{name:'Guest', theme:'dark'}});</code></pre>
+        <p>Note: Manually updating the object in storage will not trigger updates.</p>
+
+        <h2>Signal vs State</h2>
+        <table class="api-table">
+            <thead>
+                <tr>
+                    <th>Use Signal</th>
+                    <th>Use State</th>
+                </tr>
+            </thead>
+            <tbody>
+                <tr>
+                    <td>Primitives (numbers, strings, bools)</td>
+                    <td>Objects with nested properties</td>
+                </tr>
+                <tr>
+                    <td>Simple objects (replace whole thing)</td>
+                    <td>Objects you'll mutate in place</td>
+                </tr>
+                <tr>
+                    <td>Arrays you'll replace</td>
+                    <td>Arrays you'll push/pop/splice</td>
+                </tr>
+                <tr>
+                    <td>Slightly better performance</td>
+                    <td>More convenient API</td>
+                </tr>
+            </tbody>
+        </table>
+
+        <h2>Pro Tip</h2>
+        <p>
+            You can mix both! Use signals for simple values and state for complex structures:
+        </p>
+        <pre><code>const isLoading = signal(false);      // Simple boolean → signal
+const error = signal(null);           // Simple value → signal
+const items = state([]);              // Array to mutate → state (from LightviewX)
+const formData = state({              // Object to mutate → state (from LightviewX)
+    name: '',
+    email: '',
+    message: ''
+});</code></pre>
+    </main>
+</div>
+
+<script>
+    (function () {
+        const { tags } = Lightview;
+        const { state } = LightviewX;
+        const { div, ul, li, input, span, button } = tags;
+
+        const todos = state([
+            { text: 'Learn Lightview', done: true },
+            { text: 'Build something', done: false }
+        ]);
+
+        const demo = div({ style: 'padding: 0.5rem;' },
+            ul({ style: 'list-style: none; padding: 0; margin: 0 0 1rem;' },
+                () => todos.map((todo, i) =>
+                    li({ style: 'display: flex; align-items: center; gap: 0.5rem; padding: 0.25rem 0;' },
+                        input({
+                            type: 'checkbox',
+                            checked: todo.done,
+                            onchange: () => todos[i].done = !todos[i].done,
+                            style: 'cursor: pointer;'
+                        }),
+                        span({
+                            style: () => `${todo.done ? 'text-decoration: line-through; opacity: 0.6;' : ''}`
+                        }, todo.text)
+                    )
+                )
+            ),
+            button({
+                onclick: () => todos.push({ text: `Task ${todos.length + 1}`, done: false }),
+                style: 'padding: 0.5rem 1rem; cursor: pointer; background: var(--site-primary); color: white; border: none; border-radius: 6px;'
+            }, '+ Add Task')
+        );
+
+        const container = document.getElementById('state-demo');
+        if (container) container.appendChild(demo.domEl);
+    })();
+</script>

package/docs/assets/images/logo-favicon.svg

@@ -0,0 +1,42 @@
+<svg width="512" height="512" viewBox="0 0 512 512" fill="none" xmlns="http://www.w3.org/2000/svg">
+  <defs>
+    <!-- Vibrant Blue/Purple Gradient -->
+    <linearGradient id="bladeGradient" x1="100" y1="100" x2="400" y2="400" gradientUnits="userSpaceOnUse">
+      <stop offset="0%" stop-color="#0ea5e9" />  <!-- Sky Blue -->
+      <stop offset="50%" stop-color="#8b5cf6" /> <!-- Violet -->
+      <stop offset="100%" stop-color="#ec4899" /> <!-- Pink/Magenta -->
+    </linearGradient>
+    
+    <!-- Glow effect for the center -->
+    <filter id="centerGlow" x="-50%" y="-50%" width="200%" height="200%">
+      <feGaussianBlur stdDeviation="15" result="blur"/>
+      <feComposite in="SourceGraphic" in2="blur" operator="over"/>
+    </filter>
+  </defs>
+
+  <!-- Group centered and scaled up by 25% -->
+  <g transform="translate(256 256) scale(1.25)">
+    
+    <!-- 8-blade Geometric Aperture -->
+    <g class="aperture-panels" stroke="none"> 
+      <path d="M0,-60 L130,-160 L180,-40 Z" fill="url(#bladeGradient)" opacity="0.9" transform="rotate(0)" />
+      <path d="M0,-60 L130,-160 L180,-40 Z" fill="url(#bladeGradient)" opacity="0.9" transform="rotate(45)" />
+      <path d="M0,-60 L130,-160 L180,-40 Z" fill="url(#bladeGradient)" opacity="0.9" transform="rotate(90)" />
+      <path d="M0,-60 L130,-160 L180,-40 Z" fill="url(#bladeGradient)" opacity="0.9" transform="rotate(135)" />
+      <path d="M0,-60 L130,-160 L180,-40 Z" fill="url(#bladeGradient)" opacity="0.9" transform="rotate(180)" />
+      <path d="M0,-60 L130,-160 L180,-40 Z" fill="url(#bladeGradient)" opacity="0.9" transform="rotate(225)" />
+      <path d="M0,-60 L130,-160 L180,-40 Z" fill="url(#bladeGradient)" opacity="0.9" transform="rotate(270)" />
+      <path d="M0,-60 L130,-160 L180,-40 Z" fill="url(#bladeGradient)" opacity="0.9" transform="rotate(315)" />
+    </g>
+    
+  </g>
+  
+  <!-- Central Pupil (needs to be grouped/transformed similarly or manually adjusted) -->
+  <!-- Since the pupil is defined by absolute coordinates cx=256 cy=256, we can just wrap it in a group with the same transform relative to the center -->
+  <g transform="translate(256 256) scale(1.25)">
+     <!-- Circle coordinates must be 0,0 relative to the group for the scale to work from center -->
+     <circle cx="0" cy="0" r="60" fill="url(#bladeGradient)" opacity="0.3" filter="url(#centerGlow)" />
+     <circle cx="0" cy="0" r="24" fill="url(#bladeGradient)" />
+  </g>
+  
+</svg>

package/docs/assets/images/logo-static.svg

@@ -0,0 +1,40 @@
+<svg width="512" height="512" viewBox="0 0 512 512" fill="none" xmlns="http://www.w3.org/2000/svg">
+  <defs>
+    <!-- Vibrant Blue/Purple Gradient -->
+    <linearGradient id="bladeGradient" x1="100" y1="100" x2="400" y2="400" gradientUnits="userSpaceOnUse">
+      <stop offset="0%" stop-color="#0ea5e9" />  <!-- Sky Blue -->
+      <stop offset="50%" stop-color="#8b5cf6" /> <!-- Violet -->
+      <stop offset="100%" stop-color="#ec4899" /> <!-- Pink/Magenta -->
+    </linearGradient>
+    
+    <!-- Glow effect for the center -->
+    <filter id="centerGlow" x="-50%" y="-50%" width="200%" height="200%">
+      <feGaussianBlur stdDeviation="15" result="blur"/>
+      <feComposite in="SourceGraphic" in2="blur" operator="over"/>
+    </filter>
+  </defs>
+
+  <!-- Group centered -->
+  <g transform="translate(256 256)">
+    
+    <!-- 8-blade Geometric Aperture -->
+    <g class="aperture-panels" stroke="none"> 
+      <path d="M0,-60 L130,-160 L180,-40 Z" fill="url(#bladeGradient)" opacity="0.9" transform="rotate(0)" />
+      <path d="M0,-60 L130,-160 L180,-40 Z" fill="url(#bladeGradient)" opacity="0.9" transform="rotate(45)" />
+      <path d="M0,-60 L130,-160 L180,-40 Z" fill="url(#bladeGradient)" opacity="0.9" transform="rotate(90)" />
+      <path d="M0,-60 L130,-160 L180,-40 Z" fill="url(#bladeGradient)" opacity="0.9" transform="rotate(135)" />
+      <path d="M0,-60 L130,-160 L180,-40 Z" fill="url(#bladeGradient)" opacity="0.9" transform="rotate(180)" />
+      <path d="M0,-60 L130,-160 L180,-40 Z" fill="url(#bladeGradient)" opacity="0.9" transform="rotate(225)" />
+      <path d="M0,-60 L130,-160 L180,-40 Z" fill="url(#bladeGradient)" opacity="0.9" transform="rotate(270)" />
+      <path d="M0,-60 L130,-160 L180,-40 Z" fill="url(#bladeGradient)" opacity="0.9" transform="rotate(315)" />
+    </g>
+    
+  </g>
+  
+  <!-- Central Pupil -->
+  <g class="hero-pupil">
+    <circle cx="256" cy="256" r="60" fill="url(#bladeGradient)" opacity="0.3" filter="url(#centerGlow)" />
+    <circle cx="256" cy="256" r="24" fill="url(#bladeGradient)" />
+  </g>
+  
+</svg>

package/docs/assets/images/logo.svg

@@ -0,0 +1,66 @@
+<svg width="512" height="512" viewBox="0 0 512 512" fill="none" xmlns="http://www.w3.org/2000/svg">
+  <defs>
+    <!-- Vibrant Blue/Purple Gradient -->
+    <linearGradient id="bladeGradient" x1="100" y1="100" x2="400" y2="400" gradientUnits="userSpaceOnUse">
+      <stop offset="0%" stop-color="#0ea5e9" />  <!-- Sky Blue -->
+      <stop offset="50%" stop-color="#8b5cf6" /> <!-- Violet -->
+      <stop offset="100%" stop-color="#ec4899" /> <!-- Pink/Magenta -->
+    </linearGradient>
+    
+    <!-- Glow effect for the center -->
+    <filter id="centerGlow" x="-50%" y="-50%" width="200%" height="200%">
+      <feGaussianBlur stdDeviation="15" result="blur"/>
+      <feComposite in="SourceGraphic" in2="blur" operator="over"/>
+    </filter>
+  </defs>
+
+  <style>
+    .aperture-panels {
+      transform-origin: 0 0;
+      animation: aperture-spin 5s ease-in-out infinite;
+    }
+
+    @keyframes aperture-spin {
+      0% { transform: rotate(0deg); }
+      5% { transform: rotate(-45deg); }
+      8% { transform: rotate(0deg); }
+      100% { transform: rotate(0deg); }
+    }
+
+    .hero-pupil {
+      transform-origin: 256px 256px;
+      animation: pupil-blink 5s ease-in-out infinite;
+    }
+
+    @keyframes pupil-blink {
+      0% { transform: scale(1); opacity: 1; }
+      5% { transform: scale(0.1); opacity: 0; }
+      8% { transform: scale(1); opacity: 1; }
+      100% { transform: scale(1); opacity: 1; }
+    }
+  </style>
+
+  <!-- Group centered -->
+  <g transform="translate(256 256)">
+    
+    <!-- 8-blade Geometric Aperture -->
+    <g class="aperture-panels" stroke="none"> 
+      <path d="M0,-60 L130,-160 L180,-40 Z" fill="url(#bladeGradient)" opacity="0.9" transform="rotate(0)" />
+      <path d="M0,-60 L130,-160 L180,-40 Z" fill="url(#bladeGradient)" opacity="0.9" transform="rotate(45)" />
+      <path d="M0,-60 L130,-160 L180,-40 Z" fill="url(#bladeGradient)" opacity="0.9" transform="rotate(90)" />
+      <path d="M0,-60 L130,-160 L180,-40 Z" fill="url(#bladeGradient)" opacity="0.9" transform="rotate(135)" />
+      <path d="M0,-60 L130,-160 L180,-40 Z" fill="url(#bladeGradient)" opacity="0.9" transform="rotate(180)" />
+      <path d="M0,-60 L130,-160 L180,-40 Z" fill="url(#bladeGradient)" opacity="0.9" transform="rotate(225)" />
+      <path d="M0,-60 L130,-160 L180,-40 Z" fill="url(#bladeGradient)" opacity="0.9" transform="rotate(270)" />
+      <path d="M0,-60 L130,-160 L180,-40 Z" fill="url(#bladeGradient)" opacity="0.9" transform="rotate(315)" />
+    </g>
+    
+  </g>
+  
+  <!-- Central Pupil -->
+  <g class="hero-pupil">
+    <circle cx="256" cy="256" r="60" fill="url(#bladeGradient)" opacity="0.3" filter="url(#centerGlow)" />
+    <circle cx="256" cy="256" r="24" fill="url(#bladeGradient)" />
+  </g>
+  
+</svg>