lightview 2.3.5 → 2.3.7

package/docs/cdom-xpath.html

@@ -0,0 +1,160 @@
+<script src="/lightview-router.js?base=/index.html"></script>
+
+<div class="docs-layout">
+    <aside class="docs-sidebar" src="/docs/cdom-nav.html"></aside>
+
+    <main class="docs-content">
+        <h1>XPath Navigation in cDOM</h1>
+        <p class="text-secondary" style="font-size: 1.125rem;">
+            Navigate and derive element properties from the existing DOM structure.
+        </p>
+
+        <div class="experimental-notice"
+            style="margin: 1.5rem 0; padding: 1.25rem; border-radius: var(--site-radius); background: var(--site-accent-light); border: 1px solid var(--site-warning); color: var(--site-text);">
+            <div style="display: flex; gap: 0.75rem; align-items: flex-start;">
+                <span style="font-size: 1.5rem;">🚨</span>
+                <div>
+                    <strong style="display: block; margin-bottom: 0.25rem; font-size: 1.1rem;">cDOM vs JPRX</strong>
+                    <p style="margin: 0; font-size: 0.95rem; opacity: 0.9;">
+                        Static XPaths are availbale to <strong>cDOM</strong> during the construction phase,
+                        whereas <strong>JPRX</strong> has an <code>xpath</code> helper that returns a computed signal.
+                        See <a href="/docs/cdom.html#helpers-dom">JPRX documentation</a> on the helper for more info
+                        about xpath and reactivity.
+                    </p>
+                </div>
+            </div>
+        </div>
+
+        <h2 id="overview">Overview</h2>
+        <p>
+            cDOM allows elements to derive their properties from the existing DOM tree. This can be done statically
+            for one-time setup or reactively for values that change over time.
+        </p>
+        <ol>
+            <li><strong>Static XPath (<code>#</code> prefix)</strong>: Available to cDOM. Evaluated once during DOM
+                construction.</li>
+            <li><strong>Reactive XPath (<code>=xpath()</code> helper)</strong>: Available to JPRX. Evaluates as an
+                expression and returns a computed signal.</li>
+        </ol>
+
+        <h2 id="static-xpath">Static XPath (<code>#</code> prefix)</h2>
+        <p>
+            Static XPath expressions are perfect for keeping your definitions <strong>DRY (Don't Repeat
+                Yourself)</strong>.
+            By referencing values like <code>id</code> or <code>class</code> from parent elements, you avoid duplicating
+            data in your cDOM structure.
+        </p>
+
+
+        <div id="xpath-live-demo" style="margin: 2rem 0;">
+            <p class="text-sm font-bold opacity-60 uppercase mb-3">Live Interactive Example</p>
+            <pre><script>
+                examplify(document.currentScript.nextElementSibling, {
+                    at: document.currentScript.parentElement,
+                    scripts: ['/lightview.js', '/lightview-x.js', '/lightview-cdom.js'],
+                    type: 'module',
+                    height: '180px',
+                    autoRun: true
+                });
+            </script><code>await import('/lightview-cdom.js');
+const { parseJPRX, hydrate } = globalThis.LightviewCDOM;
+const { $ } = Lightview;
+
+const cdom = `{
+    div: {
+        id: "profile-container",
+        class: "card",
+        "data-theme": "dark",
+        children: [
+            { h3: "User Profile" },
+            { button: { 
+                id: "7", 
+                // XPath #@id gets "7" from this button's id
+                // XPath #../@id gets "profile-container" from the parent div
+                children: ["Button ", #@id, " in section ", #../@id] 
+            }}
+        ]
+    }
+}`;
+
+$('#example').content(hydrate(parseJPRX(cdom)));</code></pre>
+        </div>
+
+        <h2 id="allowed-axes">Allowed Axes (Backward-Looking Only)</h2>
+        <p>
+            To maintain high performance and safety during construction, cDOM only allows
+            <strong>backward-looking</strong>
+            XPath axes. You can reference nodes that are already constructed (parents, ancestors, earlier siblings).
+        </p>
+        <table class="api-table">
+            <thead>
+                <tr>
+                    <th>Axis</th>
+                    <th>Result</th>
+                </tr>
+            </thead>
+            <tbody>
+                <tr>
+                    <td><code>self::</code> / <code>.</code></td>
+                    <td>The current node.</td>
+                </tr>
+                <tr>
+                    <td><code>parent::</code> / <code>..</code></td>
+                    <td>The parent element.</td>
+                </tr>
+                <tr>
+                    <td><code>ancestor::</code></td>
+                    <td>Higher-level ancestors.</td>
+                </tr>
+                <tr>
+                    <td><code>preceding-sibling::</code></td>
+                    <td>Elements that appear before the current one in the same parent.</td>
+                </tr>
+            </tbody>
+        </table>
+        <p class="text-warning">
+            <strong>Forbidden:</strong> <code>child::</code>, <code>descendant::</code>, and <code>following::</code>
+            axes are disabled as they could create infinite loops or reference nodes that do not exist yet.
+        </p>
+
+        <h2 id="reactive-xpath">Reactive XPath (<code>=xpath()</code>)</h2>
+        <p>
+            If you need an XPath expression to update reactively if attributes elsewhere in the DOM change,
+            use the <code>=xpath()</code> helper within a JPRX expression.
+        </p>
+        <div class="code-block">
+            <pre><code>{
+    div: {
+        title: "=xpath('../@data-section')",
+        class: "=concat('item ', xpath('../@theme'))"
+    }
+}</code></pre>
+        </div>
+
+        <h2 id="cdomc">Concise cDOM (cDOMC) Support</h2>
+        <p>
+            In cDOMC (the shorthand format used in <code>.cdomc</code> files), the parser is <strong>structurally
+                aware</strong>
+            of XPath expressions. You do not need to quote them even if they contain square brackets or spaces.
+        </p>
+        <div class="code-block">
+            <pre><code>// Clean unquoted syntax in .cdomc files
+{ 
+    button: { 
+        id: "7", 
+        children: [#../@id] 
+    } 
+}
+
+// Support for complex paths with predicates
+{ span: [#ancestor::div[@data-role='container']/@title] }</code></pre>
+        </div>
+
+        <h2 id="safety">Security & Safety</h2>
+        <p>
+            XPath navigation in cDOM is inherently safer than using arbitrary JavaScript for DOM traversal.
+            It provides a restricted, read-only view of the existing structural tree without the risks
+            of code injection or side effects.
+        </p>
+    </main>
+</div>

package/docs/cdom.html

@@ -108,8 +108,9 @@
         <p>
             cDOM uses <strong>JPRX (JSON Pointer Reactive eXpressions)</strong> as its expression language. JPRX
             extends <a href="https://www.rfc-editor.org/rfc/rfc6901" target="_blank">JSON Pointer (RFC 6901)</a>
-            with reactivity, relative paths, and helper functions. It also provides deep integration with
-            <a href="https://json-schema.org/" target="_blank">JSON Schema</a> (Standard Draft 7+) for
+            with reactivity, relative paths, and helper functions. cDOM also supports <strong>standard XPath</strong>
+            for powerful DOM navigation during element construction. Together with deep integration for
+            <a href="https://json-schema.org/" target="_blank">JSON Schema</a> (Standard Draft 7+), cDOM provides
             industrial-strength data validation and automatic type coercion.
         </p>
 
@@ -156,8 +157,57 @@ $('#example').content(hydrate(parseJPRX(cdom)));</code></pre>
         <p>
             The UI automatically updates whenever <code>count</code> changes — no manual DOM manipulation required.
         </p>
+
+        <!-- ===== XPATH NAVIGATION ===== -->
+        <h2 id="xpath-navigation">Using XPath</h2>
         <p>
-            The UI automatically updates whenever <code>count</code> changes — no manual DOM manipulation required.
+            cDOM allows elements to navigate and reference the DOM structure during construction using standard
+            <strong>XPath</strong>. This is strictly a <strong>cDOM feature</strong> (not JPRX) used for structural
+            navigation.
+        </p>
+        <p>
+            XPath is incredibly useful for keeping your definitions <strong>DRY (Don't Repeat Yourself)</strong> by
+            referencing existing attributes instead of repeating values.
+        </p>
+        <div id="xpath-demo">
+            <pre><script>
+                examplify(document.currentScript.nextElementSibling, {
+                    at: document.currentScript.parentElement,
+                    scripts: ['/lightview.js', '/lightview-x.js', '/lightview-cdom.js'],
+                    type: 'module',
+                    height: '180px',
+                    autoRun: true,
+                    controls: false
+                });
+            </script><code>await import('/lightview-cdom.js');
+const { parseJPRX, hydrate } = globalThis.LightviewCDOM;
+const { $ } = Lightview;
+
+const cdom = `{
+    div: {
+        id: "profile-container",
+        class: "card",
+        "data-theme": "dark",
+        children: [
+            { h3: "User Profile" },
+            { button: { 
+                id: "7", 
+                // XPath #../@id gets the "7" from this button's id
+                // XPath #../../@id gets "profile-container" from the g-parent div
+                children: ["Button ", #../@id, " in section ", #../../@id] 
+            }}
+        ]
+    }
+}`;
+
+$('#example').content(hydrate(parseJPRX(cdom)));</code></pre>
+        </div>
+        <p>
+            In the example above, the button's text is derived entirely from its own <code>id</code> and its
+            parent's <code>id</code> using <code>#../@id</code> and <code>#../../@id</code>.
+        </p>
+        <p>
+            For more details, see the <a href="/docs/cdom-xpath.html">Full XPath Documentation</a>.
         </p>
 
         <!-- ===== ADVANTAGES ===== -->
@@ -596,7 +646,7 @@ const cdomString = `{
         children: [
             { h3: "Shopping Cart" },
             { ul: { 
-                children: =map(/store/cart/items, { li: { children: [_/name, " - ", =currency(_/price)] } })
+                children: =map(/store/cart/items, { li: { children: [_/name, " - ", currency(_/price)] } })
             }},
             { p: { 
                 style: "font-weight: bold; margin-top: 1rem;",
@@ -1007,10 +1057,22 @@ const liveConfig = LightviewCDOM.hydrate(config);</code></pre>
 
         <h3 id="helpers-network">Network</h3>
         <p>HTTP requests.</p>
-        <div class="code-block">
+        <div class="code-block" style="margin-bottom: 2rem;">
             <pre><code>fetch(url, options?)
 <span id="helpers-mount"></span>mount(url, options?)</span></code></pre>
         </div>
+
+        <h3 id="helpers-dom">DOM & XPath</h3>
+        <p>Structural navigation and manipulation.</p>
+        <div class="code-block">
+            <pre><code>move(selector, location?), xpath(expression)</code></pre>
+        </div>
+        <p style="margin-top: 1rem;">
+            The <code>src</code> attribute handler is the primary mechanism for Hypermedia updates. It fetches
+            content
+            (cDOM, vDOM, or oDOM) and injects it into the DOM. If the content contains a <code>=move</code>
+            helper, it will automatically relocate itself upon mounting.
+        </p>
         <table class="api-table">
             <thead>
                 <tr>
@@ -1049,13 +1111,10 @@ const liveConfig = LightviewCDOM.hydrate(config);</code></pre>
                 </tr>
             </tbody>
         </table>
-        <p style="margin-top: 1rem;">
-            The <code>mount</code> helper is the primary mechanism for **Hypermedia updates**. It fetches content
-            (cDOM, vDOM, or oDOM) and injects it into the DOM. If the content contains a <code>=move</code>
-            helper, it will automatically relocate itself upon mounting.
+        <p class="text-xs italic opacity-70" style="margin-top: 0.5rem;">
+            <strong>xpath(expression):</strong> Returns a reactive computed signal based on the DOM structure
+            at evaluation time. Note that full MutationObserver reactivity is currently a TODO.
+            For static DOM navigation, use the <code>#</code> prefix in cDOM.
         </p>
-
-
-
     </main>
 </div>

package/functions/_middleware.js

@@ -1,13 +1,30 @@
 import { marked } from 'marked';
-import { processServerScripts } from './processServerScripts.js';
+//import { processServerScripts } from './processServerScripts.js';
 
 export const onRequest = async (context) => {
     const url = new URL(context.request.url);
     const isMd = url.pathname.endsWith('.md');
     const isHtml = url.pathname.endsWith('.html') || (url.pathname.endsWith('/') && !url.pathname.includes('.'));
+    const isCdom = url.pathname.endsWith('.cdom');
+    console.log(`[Middleware] Processing: ${url.pathname}`);
+    // Intercept requests for .cdom files to set correct Content-Type
+    if (isCdom) {
+        console.log(`[Middleware] Processing: ${url.pathname}`);
+        const response = await context.next();
+        if (response.ok) {
+            const text = await response.text();
+            return new Response(text, {
+                status: 200,
+                headers: {
+                    'content-type': 'text/plain; charset=utf-8',
+                }
+            });
+        }
+        return response;
+    }
 
     // Intercept requests for .md and .html files
-    if (isMd || isHtml) {
+    if (isMd) { // || isHtml
         console.log(`[Middleware] Processing: ${url.pathname}`);
 
         // Fetch the asset (the actual file)
@@ -23,7 +40,7 @@ export const onRequest = async (context) => {
             }
 
             // 2. Process Server-Side Scripts (runat="server")
-            processedHtml = await processServerScripts(processedHtml, context.request);
+            //processedHtml = await processServerScripts(processedHtml, context.request);
 
             return new Response(processedHtml, {
                 status: 200,

package/jprx/helpers/dom.js

@@ -0,0 +1,69 @@
+/**
+ * DOM-related JPRX helpers for navigating and querying the DOM structure.
+ */
+
+/**
+ * Registers DOM-related helpers including the xpath() helper.
+ * @param {Function} registerHelper - The helper registration function
+ */
+export const registerDOMHelpers = (registerHelper) => {
+    /**
+     * Evaluates an XPath expression against the current DOM element.
+     * Returns a computed signal that re-evaluates when observed nodes change.
+     * Only supports backward-looking axes (parent, ancestor, preceding-sibling, etc.)
+     * 
+     * @param {string} expression - The XPath expression to evaluate
+     * @param {object} context - The evaluation context (contains __node__)
+     * @returns {any} The result of the XPath evaluation
+     */
+    registerHelper('xpath', function (expression) {
+        const domNode = this; // 'this' is bound to the DOM element
+
+        if (!domNode || !(domNode instanceof Element)) {
+            console.warn('[Lightview-CDOM] xpath() called without valid DOM context');
+            return '';
+        }
+
+        // Validate the expression (no forward-looking axes)
+        const forbiddenAxes = /\b(child|descendant|following|following-sibling)::/;
+        if (forbiddenAxes.test(expression)) {
+            console.error(`[Lightview-CDOM] xpath(): Forward-looking axes not allowed: ${expression}`);
+            return '';
+        }
+
+        const hasShorthandChild = /\/[a-zA-Z]/.test(expression) && !expression.startsWith('/html');
+        if (hasShorthandChild) {
+            console.error(`[Lightview-CDOM] xpath(): Shorthand child axis (/) not allowed: ${expression}`);
+            return '';
+        }
+
+        // Get Lightview's computed function
+        const LV = globalThis.Lightview;
+        if (!LV || !LV.computed) {
+            console.warn('[Lightview-CDOM] xpath(): Lightview not available');
+            return '';
+        }
+
+        // Return a computed signal that evaluates the XPath
+        return LV.computed(() => {
+            try {
+                const result = document.evaluate(
+                    expression,
+                    domNode,
+                    null,
+                    XPathResult.STRING_TYPE,
+                    null
+                );
+
+                // TODO: Set up MutationObserver for reactivity
+                // For now, this just evaluates once
+                // Future: Observe parent/ancestor/sibling changes
+
+                return result.stringValue;
+            } catch (e) {
+                console.error(`[Lightview-CDOM] xpath() evaluation failed:`, e.message);
+                return '';
+            }
+        });
+    }, { pathAware: false });
+};

package/jprx/helpers/logic.js

@@ -6,8 +6,10 @@ export const ifHelper = (condition, thenVal, elseVal) => condition ? thenVal : e
 export const andHelper = (...args) => args.every(Boolean);
 export const orHelper = (...args) => args.some(Boolean);
 export const notHelper = (val) => !val;
-export const eqHelper = (a, b) => a === b;
-export const neqHelper = (a, b) => a !== b;
+export const eqHelper = (a, b) => a == b;
+export const strictEqHelper = (a, b) => a === b;
+export const neqHelper = (a, b) => a != b;
+export const strictNeqHelper = (a, b) => a !== b;
 
 export const registerLogicHelpers = (register) => {
     register('if', ifHelper);
@@ -18,7 +20,11 @@ export const registerLogicHelpers = (register) => {
     register('not', notHelper);
     register('!', notHelper);
     register('eq', eqHelper);
+    register('strictEq', strictEqHelper);
     register('==', eqHelper);
-    register('===', eqHelper);
+    register('===', strictEqHelper);
     register('neq', neqHelper);
+    register('strictNeq', strictNeqHelper);
+    register('!=', neqHelper);
+    register('!==', strictNeqHelper);
 };

package/jprx/index.js

@@ -19,7 +19,8 @@ export {
     resolvePathAsContext,
     resolveExpression,
     parseCDOMC,
-    parseJPRX,
+    parseCDOMC as parseJPRX,
+    parseJPRX as oldParseJPRX,
     unwrapSignal,
     getRegistry,
     BindingTarget
@@ -39,6 +40,7 @@ export { registerStatsHelpers } from './helpers/stats.js';
 export { registerStateHelpers, set } from './helpers/state.js';
 export { registerNetworkHelpers } from './helpers/network.js';
 export { registerCalcHelpers, calc } from './helpers/calc.js';
+export { registerDOMHelpers } from './helpers/dom.js';
 
 // Convenience function to register all standard helpers
 export const registerAllHelpers = (registerFn) => {

package/jprx/package.json

@@ -1,6 +1,6 @@
 {
     "name": "jprx",
-    "version": "1.2.1",
+    "version": "1.3.1",
     "description": "JSON Path Reactive eXpressions - A reactive expression language for JSON data",
     "main": "index.js",
     "type": "module",