lightview 1.8.2 → 2.0.1

package/docs/api/enhance.html

@@ -0,0 +1,225 @@
+<!-- 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>Enhance</h1>
+        <p>
+            The <code>enhance()</code> function lets you add Lightview's reactivity to existing HTML elements.
+            Perfect for progressive enhancement - start with plain HTML and add interactivity where needed.
+        </p>
+
+        <h2>Why Enhance?</h2>
+        <p>
+            Sometimes you have existing HTML - maybe from a CMS, a server-rendered template, or just plain HTML.
+            Rather than rebuilding everything with Lightview elements, <code>enhance()</code> lets you
+            incrementally add reactivity to what's already there.
+        </p>
+
+        <h2>Basic Usage</h2>
+        <pre><code>const { signal, enhance } = Lightview;
+
+// Select an existing element and make it reactive
+const counter = signal(0);
+enhance('#my-element', {
+    innerText: () => `Count: ${counter.value}`
+});
+
+// Now when counter changes, the element updates automatically!</code></pre>
+
+        <h2>Syntax</h2>
+        <pre><code>enhance(selectorOrNode, options)
+
+// selectorOrNode: CSS selector string or DOM element
+// options: { innerText?, innerHTML?, ...attributes }
+
+// Returns: Lightview element wrapper (or null if not found)</code></pre>
+
+        <h2>Live Example: Basic Enhancement</h2>
+        <pre><script>
+            examplify(document.currentScript.nextElementSibling, {
+                at: document.currentScript.parentElement,
+                scripts: ['/lightview.js'],
+                type: 'module',
+                minHeight: 180,
+                html: `<!-- This HTML exists in the page before enhancement -->
+<div id="greeting-card" style="padding: 1rem; background: #f8f9fa; border-radius: 8px; border: 1px solid #dee2e6;">
+    <h3 id="greeting-title">Welcome!</h3>
+    <p id="greeting-message">Enter your name below</p>
+    <input id="name-input" type="text" placeholder="Your name..." style="width: 100%; padding: 0.5rem; margin: 0.5rem 0; border: 1px solid #ccc; border-radius: 4px;">
+    <button id="reset-btn" style="padding: 0.5rem 1rem; background: #6c757d; color: white; border: none; border-radius: 4px; cursor: pointer;">Reset</button>
+</div>`
+            });
+        </script><code contenteditable="true">const { signal, enhance } = Lightview;
+
+const name = signal('');
+
+// Enhance the input field
+enhance('#name-input', {
+    oninput: (e) => name.value = e.target.value,
+    value: () => name.value
+});
+
+// Enhance the greeting title
+enhance('#greeting-title', {
+    innerText: () => name.value ? `Hello, ${name.value}!` : 'Welcome!'
+});
+
+// Enhance the greeting message
+enhance('#greeting-message', {
+    innerText: () => name.value 
+        ? `Nice to meet you, ${name.value}!` 
+        : 'Enter your name below',
+    style: () => name.value 
+        ? 'color: #28a745; font-weight: 500;'
+        : 'color: #6c757d;'
+});
+
+// Enhance the reset button
+enhance('#reset-btn', {
+    onclick: () => name.value = '',
+    disabled: () => !name.value,
+    style: () => `padding: 0.5rem 1rem; background: ${name.value ? '#dc3545' : '#6c757d'}; color: white; border: none; border-radius: 4px; cursor: ${name.value ? 'pointer' : 'not-allowed'}; opacity: ${name.value ? 1 : 0.5};`
+});</code></pre>
+
+        <h2>Options</h2>
+
+        <h3>innerText</h3>
+        <p>Replace the text content of an element. Can be static or reactive:</p>
+        <pre><code>// Static text
+enhance('#greeting', { innerText: 'Hello World' });
+
+// Reactive text - updates when signal changes
+const name = signal('Alice');
+enhance('#greeting', { innerText: () => `Hello ${name.value}` });</code></pre>
+
+        <h3>innerHTML</h3>
+        <p>Replace the HTML content. Use with caution - only with trusted content:</p>
+        <pre><code>const html = signal('<strong>Bold text</strong>');
+enhance('#content', { innerHTML: () => html.value });</code></pre>
+
+        <h3>Attributes</h3>
+        <p>Any other properties in options are treated as attributes. These can also be reactive:</p>
+        <pre><code>const isDisabled = signal(false);
+const theme = signal('light');
+
+enhance('#my-button', {
+    disabled: () => isDisabled.value,
+    class: () => `btn btn-${theme.value}`,
+    'data-active': () => !isDisabled.value
+});</code></pre>
+
+        <h2>Live Example: Reactive Attributes</h2>
+        <pre><script>
+            examplify(document.currentScript.nextElementSibling, {
+                at: document.currentScript.parentElement,
+                scripts: ['/lightview.js', '/lightview-x.js'],
+                type: 'module',
+                maxHeight: 50,
+                html: `
+<span id="attr-demo">
+    <button id="toggle-btn">Enable/Disable</button>
+    <button id="target-btn">Target Button</button>
+</span>`
+            });
+        </script><code contenteditable="true">const { signal, enhance, tags } = Lightview;
+const { div } = tags;
+
+const disabled = signal(false);
+
+enhance('#toggle-btn', {
+    onclick: () => disabled.value = !disabled.value,
+    innerText: () => disabled.value ? 'Enable' : 'Disable'
+});
+
+enhance('#target-btn', {
+    disabled: () => disabled.value,
+    style: () => `opacity: ${disabled.value ? 0.5 : 1}; cursor: ${disabled.value ? 'not-allowed' : 'pointer'};`
+});</code></pre>
+
+        <h2>Progressive Enhancement Pattern</h2>
+        <p>
+            Start with semantic HTML that works without JavaScript, then enhance with Lightview:
+        </p>
+        <pre><code><!-- server-rendered HTML -->
+&lt;div id="user-info"&gt;
+    &lt;h2&gt;Guest&lt;/h2&gt;
+    &lt;p&gt;Please log in&lt;/p&gt;
+&lt;/div&gt;
+
+&lt;script&gt;
+    // Enhancement kicks in when JS loads
+    const { signal, enhance } = Lightview;
+    const user = signal(null);
+
+    // Fetch user data
+    fetch('/api/user').then(r => r.json()).then(data => {
+        user.value = data;
+    });
+
+    // Enhance the existing markup
+    enhance('#user-info h2', {
+        innerText: () => user.value?.name ?? 'Guest'
+    });
+
+    enhance('#user-info p', {
+        innerText: () => user.value
+            ? `Welcome back, ${user.value.name}!`
+            : 'Please log in'
+    });
+</script></code></pre>
+
+        <h2>Return Value</h2>
+        <p>
+            <code>enhance()</code> returns a Lightview element wrapper with a <code>domEl</code> property
+            pointing to the actual DOM node. This lets you further manipulate it:
+        </p>
+        <pre><code>const el = enhance('#my-div', { class: 'enhanced' });
+
+// Access the wrapped element
+if (el) {
+    console.log(el.domEl);  // The actual DOM node
+    el.attributes.id = 'new-id';  // Update attributes reactively
+}</code></pre>
+
+        <h2>Tips & Patterns</h2>
+
+        <h3>Enhance Multiple Elements</h3>
+        <pre><code>// Enhance a list of elements
+document.querySelectorAll('.counter').forEach(el => {
+    const count = signal(0);
+    enhance(el, {
+        innerText: () => count.value,
+        onclick: () => count.value++
+    });
+});</code></pre>
+
+        <h3>Reusing Elements</h3>
+        <p>If you call <code>enhance()</code> on an already-enhanced element, it merges the new options:</p>
+        <pre><code>// First enhancement
+enhance('#btn', { innerText: 'Click me' });
+
+// Second enhancement - adds to the first
+enhance('#btn', { onclick: "alert('clicked')" });
+
+// Result: &lt;button onclick="alert('clicked')">Click me</button&gt;</code></pre>
+
+        <h3>When to Use</h3>
+        <ul>
+            <li><strong>Use enhance():</strong> When you have existing HTML (server-rendered, CMS, etc.)</li>
+            <li><strong>Use element/tags:</strong> When building new UI from scratch in JavaScript</li>
+            <li><strong>Mix both:</strong> Enhance static structure, build dynamic parts with tags</li>
+        </ul>
+
+
+    </main>
+</div>

package/docs/api/hypermedia.html

@@ -0,0 +1,165 @@
+<!-- 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>Hypermedia</h1>
+        <p>
+            HTMX vibes, built right in. Load HTML fragments, fetch vDOM/Object DOM, clone templates - all with the
+            <code>src</code>
+            attribute.
+            <em>Requires lightview-x.js</em>
+        </p>
+
+        <h2>Fetching HTML</h2>
+        <p>
+            Point <code>src</code> at an HTML file and Lightview loads it as children:
+        </p>
+        <pre><code>const { tags } = Lightview;
+const { div, header, main } = tags;
+
+// Load HTML partials
+const app = div(
+    header({ src: '/partials/nav.html' }),
+    main({ src: '/partials/content.html' })
+);
+
+// The HTML is fetched, parsed, and made reactive automatically!</code></pre>
+
+        <h2>Fetching vDOM & Object DOM</h2>
+        <p>
+            Files with <code>.vdom</code> or <code>.odom</code> extensions are parsed as JSON and converted to elements:
+        </p>
+        <pre><code>// /api/cards.vdom
+[
+    { "tag": "div", "attributes": { "class": "card" }, "children": ["Card 1"] },
+    { "tag": "div", "attributes": { "class": "card" }, "children": ["Card 2"] }
+]
+
+// Load vDOM
+div({ src: '/api/cards.vdom' })</code></pre>
+
+        <h2>Cloning DOM Elements</h2>
+        <p>
+            Use CSS selectors to clone existing elements:
+        </p>
+        <pre><code>// Clone a template
+div({ src: '#my-template' })
+
+// Clone multiple elements
+div({ src: '.card-template' })</code></pre>
+        <pre><code>&lt;!-- Hidden template in HTML --&gt;
+&lt;template id="my-template"&gt;
+    &lt;div class="modal"&gt;
+        &lt;h2&gt;Modal Title&lt;/h2&gt;
+        &lt;p&gt;Modal content here&lt;/p&gt;
+    &lt;/div&gt;
+&lt;/template&gt;</code></pre>
+
+        <h2>Interactive href & Navigation</h2>
+        <p>
+            Add <code>href</code> to any element to make it interactive. The behavior depends on the <code>target</code>
+            attribute:
+        </p>
+
+        <h3>1. Self-Loading (Default)</h3>
+        <p>If no target is specified, clicking sets the element's own <code>src</code> to the <code>href</code> value:
+        </p>
+        <pre><code>// Loads content into itself on click
+button({ href: '/partials/data.html' }, 'Load Data')</code></pre>
+
+        <h3>2. Browser Navigation</h3>
+        <p>Use standard underscore targets for window navigation:</p>
+        <pre><code>// Opens new tab
+button({ href: 'https://example.com', target: '_blank' }, 'Open External')
+
+// Navigates current page
+div({ href: '/home', target: '_self' }, 'Go Home')</code></pre>
+
+        <h3>3. Targeting Other Elements</h3>
+        <p>Use a CSS selector as the target to load content into other elements:</p>
+        <pre><code>// Loads content into element with id="main"
+button({ href: '/pages/about.html', target: '#main' }, 'Load About Page')
+
+div({ id: 'main' }) // Content appears here</code></pre>
+
+        <h3>4. Positioning Content</h3>
+        <p>Control where content is inserted using the <code>location</code> attribute or a target suffix.</p>
+        <p><strong>Supported locations:</strong> <code>innerhtml</code> (default), <code>outerhtml</code>,
+            <code>beforebegin</code>, <code>afterbegin</code>, <code>beforeend</code>, <code>afterend</code>,
+            <code>shadow</code>.
+        </p>
+
+        <pre><code>// Option A: Suffix syntax for href (Target Selector:Location)
+button({ 
+    href: '/partials/item.html', 
+    target: '#list:beforeend' // Append to list
+}, 'Add Item')
+
+// Option B: Explicit attribute on target for src
+div({ 
+    src: '/partials/banner.html', 
+    location: 'afterbegin' 
+})</code></pre>
+
+        <p><strong>Smart Replacement:</strong> Lightview tracks inserted content. Fetching the same content to the same
+            location is a no-op. Fetching different content replaces the previous content at that specific location.</p>
+
+        <h2>HTML Template Literals</h2>
+        <p>
+            External HTML can reference named signals or state with template syntax:
+        </p>
+        <pre><code>// main.js - Register named signals and state
+const count = signal(0, 'count');
+const userName = signal('Guest', 'userName');
+const userPrefs = state({ theme: 'dark', lang: 'en' }, 'userPrefs');
+
+// Load template that uses them
+div({ src: '/partials/dashboard.html' })</code></pre>
+        <pre><code>&lt;!-- /partials/dashboard.html --&gt;
+&lt;div class="dashboard"&gt;
+    &lt;h1&gt;Welcome, ${signal.get('userName').value}!&lt;/h1&gt;
+    &lt;p&gt;You have ${signal.get('count').value} notifications.&lt;/p&gt;
+    &lt;p&gt;Theme: ${state.get('userPrefs').theme}&lt;/p&gt;
+&lt;/div&gt;</code></pre>
+
+        <h2>Shadow DOM</h2>
+        <p>
+            Load content into shadow DOM for style isolation using <code>location="shadow"</code> or the
+            <code>:shadow</code> suffix:
+        </p>
+        <pre><code>// Option A: location attribute
+div({ src: '/components/widget.html', location: 'shadow' })
+
+// Option B: target suffix
+button({ href: '/components/widget.html', target: '#container:shadow' }, 'Load Widget')</code></pre>
+
+        <h2>Building HTMX-style Apps</h2>
+        <p>
+            Combine <code>src</code> and <code>href</code> for hypermedia-driven UIs:
+        </p>
+        <pre><code>const { tags } = Lightview;
+const { div, nav, button, main } = tags;
+
+const app = div({ class: 'app' },
+    nav({ class: 'sidebar' },
+        button({ href: '/pages/dashboard.html' }, '📊 Dashboard'),
+        button({ href: '/pages/settings.html' }, '⚙️ Settings'),
+        button({ href: '/pages/profile.html' }, '👤 Profile')
+    ),
+    main({ 
+        id: 'content',
+        src: '/pages/dashboard.html'  // Initial content
+    })
+);
+
+
+    </main>
+</div>

package/docs/api/index.html

@@ -0,0 +1,178 @@
+<!-- SEO-friendly SPA Shim -->
+<script src="/lightview-router.js"></script>
+<script>
+    if (window.LightviewRouter) {
+        LightviewRouter.base('/index.html');
+    }
+</script>
+
+</script>
+
+<div class="docs-layout">
+    <aside class="docs-sidebar" src="./nav.html"></aside>
+
+    <main class="docs-content">
+        <h1>API Reference</h1>
+        <p>
+            Lightview provides a small but powerful API. Everything you need, nothing you don't.
+            <em>Keep it light, remember?</em>
+        </p>
+
+        <h2>Lightview Overview</h2>
+
+        <table class="api-table">
+            <thead>
+                <tr>
+                    <th>Function</th>
+                    <th>Description</th>
+                </tr>
+            </thead>
+            <tbody>
+                <tr>
+                    <td><a
+                            href="./signals.html"><code>signal(value, optionsOrName?)</code></a><br><code>signal.get(name)</code>
+                    </td>
+                    <td>Create reactive state that triggers updates when changed. Optional name or options object allows
+                        global access and persistence.
+                    </td>
+                </tr>
+                <tr>
+                    <td><a href="./computed.html"><code>computed(fn)</code></a></td>
+                    <td>Derive values from signals automatically</td>
+                </tr>
+                <tr>
+                    <td><a href="./effects.html"><code>effect(fn)</code></a></td>
+                    <td>Run side effects when dependencies change</td>
+                </tr>
+                <tr>
+                    <td><a href="./elements.html"><code>tags.*</code></a></td>
+                    <td>Shorthand element creators (div, span, button, etc.)</td>
+                </tr>
+                <tr>
+                    <td><code>$(selector)</code></td>
+                    <td>Query the DOM and return a native element enhanced with a <code>.content(node, location?)</code>
+                        method.
+                        The <code>location</code> can be <code>'inner'</code> (default), <code>'outer'</code>,
+                        <code>'shadow'</code>,
+                        <code>'beforebegin'</code>, <code>'afterbegin'</code>, <code>'beforeend'</code>, or
+                        <code>'afterend'</code>.
+                        The <code>node</code> argument is polymorphic and can be a real DOM node, a virtual node (vDOM),
+                        Object DOM, or an array of these.
+                    </td>
+                </tr>
+                <tr>
+                    <td><a href="./enhance.html"><code>enhance(selector, options)</code></a></td>
+                    <td>Add reactivity to existing DOM elements. Perfect for progressive enhancement of traditional HTML
+                        pages.</td>
+                </tr>
+            </tbody>
+        </table>
+
+        <h2>Lightview X Overview</h2>
+        <p>
+            Lightview X automatically enhances the core Lightview instance when loaded, adding hypermedia capabilities,
+            template literal support, and deep reactive state. Object DOM syntax is now always available in core
+            Lightview.
+        </p>
+
+        <table class="api-table">
+            <thead>
+                <tr>
+                    <th>Feature / Function</th>
+                    <th>Description</th>
+                </tr>
+            </thead>
+            <tbody>
+                <tr>
+                    <td><a
+                            href="./state.html"><code>state(obj, optionsOrName?)</code></a><br><code>state.get(name)</code>
+                    </td>
+                    <td>Create deep reactive state for complex objects/arrays. Optional name or options object allows
+                        global access and persistence.</td>
+                </tr>
+                <tr>
+                    <td><code>registerStyleSheet(id, css)</code></td>
+                    <td>Register a named stylesheet for use in Shadow DOM components. Can take a CSS string, a URL, or a
+                        selector to a <code>&lt;style&gt;</code> tag.</td>
+                </tr>
+                <tr>
+                    <td><code>registerThemeSheet(url)</code></td>
+                    <td>Register a global theme stylesheet that is automatically applied to all Shadow DOM components.
+                    </td>
+                </tr>
+                <tr>
+                    <td><a href="./hypermedia.html"><code>src="..."</code></a></td>
+                    <td>Attribute to automatically fetch HTML or JSON representing HTML and inject it into the element.
+                    </td>
+                </tr>
+                <tr>
+                    <td><a href="./hypermedia.html"><code>href="..."</code></a></td>
+                    <td>Attribute for SPA navigation and src injection on any element. Supports targeting content
+                        before, at the start of, and the end of or after other elements via CSS selectors.</td>
+                </tr>
+                <tr>
+                    <td>
+                        <code>&lt;div&gt;${signal.get('count').value}&lt;/div&gt;</code><br><code>&lt;span&gt;${state.get('user').name}&lt;/span&gt;</code>
+                    </td>
+                    <td>Syntax support for using signals and state directly inside string templates in HTML or JSON
+                        representation of HTML.</td>
+                </tr>
+            </tbody>
+        </table>
+
+        <h2>Using Lightview</h2>
+        <pre><code>&lt;!-- Core only --&gt;
+&lt;script src="lightview.js"&gt;&lt;/script&gt;
+
+&lt;!-- Full power --&gt;
+&lt;script src="lightview.js"&gt;&lt;/script&gt;
+&lt;script src="lightview-x.js"&gt;&lt;/script&gt;</code></pre>
+        <pre><code>// Destructure what you need from the global instances
+const { signal, computed, effect, element, tags, $, enhance } = Lightview;
+const { state } = LightviewX; // Deep state (lightview-x)</code></pre>
+
+
+
+        <h2>Core Modules</h2>
+
+        <div class="feature-grid" style="margin-top: 1.5rem;">
+            <a href="./signals" class="feature-card" style="text-decoration: none; color: inherit;">
+                <h3 class="feature-title">Signals</h3>
+                <p class="feature-description">
+                    The foundation. Reactive primitives that make everything tick.
+                </p>
+            </a>
+            <a href="./computed" class="feature-card" style="text-decoration: none; color: inherit;">
+                <h3 class="feature-title">Computed</h3>
+                <p class="feature-description">
+                    Derived state. Values that update themselves.
+                </p>
+            </a>
+            <a href="./effects" class="feature-card" style="text-decoration: none; color: inherit;">
+                <h3 class="feature-title">Effects</h3>
+                <p class="feature-description">
+                    Side effects. Do things when state changes.
+                </p>
+            </a>
+            <a href="./elements" class="feature-card" style="text-decoration: none; color: inherit;">
+                <h3 class="feature-title">Elements</h3>
+                <p class="feature-description">
+                    Three ways to build UI, tag functions, vDOM, and Object DOM. Pick your favorite.
+                </p>
+            </a>
+            <a href="./enhance" class="feature-card" style="text-decoration: none; color: inherit;">
+                <h3 class="feature-title">Enhance</h3>
+                <p class="feature-description">
+                    Add reactivity to existing HTML. Progressive enhancement made easy.
+                </p>
+            </a>
+            <a href="./hypermedia.html" class="feature-card" style="text-decoration: none; color: inherit;">
+                <h3 class="feature-title">Hypermedia</h3>
+                <p class="feature-description">
+                    Fetch content with src. HTMX vibes, built in.
+                </p>
+            </a>
+        </div>
+
+    </main>
+</div>

package/docs/api/nav.html

@@ -0,0 +1,18 @@
+<nav class="docs-nav">
+    <div class="docs-nav-section">
+        <div class="docs-nav-title">Reactivity</div>
+        <a href="./signals.html" class="docs-nav-link">Signals</a>
+        <a href="./computed.html" class="docs-nav-link">Computed</a>
+        <a href="./effects.html" class="docs-nav-link">Effects</a>
+        <a href="./enhance.html" class="docs-nav-link">Enhance</a>
+    </div>
+    <div class="docs-nav-section">
+        <div class="docs-nav-title">Lightview X</div>
+        <a href="./state.html" class="docs-nav-link">State (Deep Reactivity)</a>
+        <a href="./hypermedia.html" class="docs-nav-link">Hypermedia</a>
+        <div class="docs-nav-section">
+            <div class="docs-nav-title">Elements</div>
+            <a href="./elements.html" class="docs-nav-link">Creating Elements</a>
+        </div>
+    </div>
+</nav>