lightview 2.4.4 → 2.5.0

package/docs/cdom.html

@@ -53,7 +53,7 @@
 
 <script>
     globalThis.switchCDOMTab = (tabId) => {
-        const tabs = ['jprx', 'jprxc', 'operators', 'embedded'];
+        const tabs = ['jprx', 'cdomc', 'operators'];
         tabs.forEach(t => {
             const btn = document.getElementById(`tab-btn-${t}`);
             const pane = document.getElementById(`pane-${t}`);
@@ -89,6 +89,20 @@
                         helper functions, and integration patterns are subject to change as we continue to evolve the
                         library. Use with caution in production environments.
                     </p>
+                    <p
+                        style="margin: 0.75rem 0 0 0; padding-top: 0.75rem; border-top: 1px solid var(--site-border); font-size: 0.95rem; opacity: 0.9;">
+                        <strong>v2.5.0 Syntax Update:</strong> Starting with Lightview v2.5.0 and JPRX v1.4.0,
+                        expressions use a new wrapper syntax:
+                        <code
+                            style="background: var(--site-bg-secondary); padding: 0.125rem 0.375rem; border-radius: 3px;">=(expr)</code>
+                        for JPRX and
+                        <code
+                            style="background: var(--site-bg-secondary); padding: 0.125rem 0.375rem; border-radius: 3px;">#(xpath)</code>
+                        for XPath.
+                        The legacy prefix-only syntax (e.g., <code
+                            style="background: var(--site-bg-secondary); padding: 0.125rem 0.375rem; border-radius: 3px;">=path</code>)
+                        will be <strong>fully deprecated after March 31, 2026</strong>.
+                    </p>
                 </div>
             </div>
         </div>
@@ -132,13 +146,14 @@ const { parseJPRX, hydrate } = globalThis.LightviewCDOM;
 const { $ } = Lightview;
 
 const cdom = `{
-    div: {
-        onmount: =state({ count: 0 }, { name: 'local', schema: 'auto', scope: $this }),
-        children: [
-            { h2: "Counter" },
-            { p: ["Count: ", =/local/count] },
-            { button: { onclick: =++/local/count, children: ["+"] } },
-            { button: { onclick: =--/local/count, children: ["-"] } }
+    "div": {
+        "id": "Counter",
+        "onmount": "=state({ count: 0 }, { name: 'local', schema: 'auto', scope: $this })",
+        "children": [
+            { "h2": "#(../../@id)" }, // XPath: text node -> h2 -> div
+            { "p": ["Count: ", "=(/local/count)"] },
+            { "button": { "onclick": "=(++/local/count)", "children": ["+"] } },
+            { "button": { "onclick": "=(--/local/count)", "children": ["-"] } }
         ]
     }
 }`;
@@ -150,14 +165,45 @@ $('#example').content(hydrate(parseJPRX(cdom)));</code></pre>
         </p>
         <ul>
             <li><code>onmount</code> — A Lightview lifecycle hook where we initialize state.</li>
+            <li><code>#../../@id</code> — An XPath expression that extracts the <code>id</code> from the grandparent
+                element.</li>
             <li><code>=state(...)</code> — An initializer that creates local reactive state.</li>
             <li><code>scope: $this</code> — Explicitly attaches the state to the current element.</li>
             <li><code>=/local/count</code> — A path that reactively displays the count value.</li>
         </ul>
+        <p style="font-size: 0.95rem; font-style: italic; color: var(--site-text-secondary);">
+            <strong>Note:</strong> In cDOM, expressions use a wrapper syntax for clarity: <code>#(xpath)</code> for
+            <strong>XPath</strong> expressions that
+            navigate and extract data from the DOM, and <code>=(expr)</code> for <strong>JPRX</strong>
+            expressions that navigate or apply functions to reactive state. Legacy syntax without parentheses is still
+            supported.
+        </p>
         <p>
-            The UI automatically updates whenever <code>count</code> changes — no manual DOM manipulation required.
+            The UI automatically updates whenever <code>count</code> changes — no manual DOM manipulation required. It
+            also uses XPath to navigate the DOM structure during construction.
         </p>
 
+        <!-- ===== ADVANTAGES ===== -->
+        <h2 id="advantages">Advantages</h2>
+        <div class="feature-grid" style="margin: 2rem 0;">
+            <div class="feature-card">
+                <h3 class="feature-title">🛡️ Enhanced Security</h3>
+                <p>
+                    cDOM strictly avoids <code>eval()</code> and direct HTML injection. By using a custom
+                    high-performance parser and a registry of pre-defined helper functions, it provides a safe sandbox
+                    for dynamic content, making it highly resistant to XSS attacks.
+                </p>
+            </div>
+            <div class="feature-card">
+                <h3 class="feature-title">🤖 LLM Friendly</h3>
+                <p>
+                    Large Language Models excel at generating structured data and formulaic expressions. cDOM's
+                    declarative nature and concise syntax make it far easier for AI to generate correct,
+                    bug-free UI components compared to traditional JavaScript-heavy frameworks.
+                </p>
+            </div>
+        </div>
+
         <!-- ===== XPATH NAVIGATION ===== -->
         <h2 id="xpath-navigation">Using XPath</h2>
         <p>
@@ -184,17 +230,20 @@ const { parseJPRX, hydrate } = globalThis.LightviewCDOM;
 const { $ } = Lightview;
 
 const cdom = `{
+    // The cdom below uses a compressed syntax. It does not require quotes 
+    // around properties or JPRX/XPath values and supports comments. 
+    // It is JSON-like, but not JSON.
     div: {
         id: "profile-container",
         class: "card",
-        "data-theme": "dark",
+        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] 
+                // 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)] 
             }}
         ]
     }
@@ -204,33 +253,12 @@ $('#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>.
+            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 ===== -->
-        <h2 id="advantages">Advantages</h2>
-        <div class="feature-grid" style="margin: 2rem 0;">
-            <div class="feature-card">
-                <h3 class="feature-title">🛡️ Enhanced Security</h3>
-                <p>
-                    cDOM strictly avoids <code>eval()</code> and direct HTML injection. By using a custom
-                    high-performance parser and a registry of pre-defined helper functions, it provides a safe sandbox
-                    for dynamic content, making it highly resistant to XSS attacks.
-                </p>
-            </div>
-            <div class="feature-card">
-                <h3 class="feature-title">🤖 LLM Friendly</h3>
-                <p>
-                    Large Language Models excel at generating structured data and formulaic expressions. cDOM's
-                    declarative nature and concise syntax make it far easier for AI to generate correct,
-                    bug-free UI components compared to traditional JavaScript-heavy frameworks.
-                </p>
-            </div>
-        </div>
-
         <!-- ===== JPRX INTRODUCTION ===== -->
         <h2 id="JPRX">JPRX (JSON Pointer Reactive eXpressions)</h2>
         <p>
@@ -239,54 +267,61 @@ $('#example').content(hydrate(parseJPRX(cdom)));</code></pre>
             with reactivity, relative paths, and helper functions.
         </p>
 
-        <h3 id="JPRX-delimiters">Delimiters</h3>
+        <h3 id="JPRX-delimiters">Expression Syntax</h3>
         <p>
-            JPRX expressions begin with a <code>=</code> delimiter:
+            JPRX expressions use a <strong>wrapper syntax</strong> for unambiguous parsing. The recommended syntax is
+            <code>=(expression)</code>:
         </p>
         <table class="api-table">
             <thead>
                 <tr>
-                    <th>Delimiter</th>
+                    <th>Syntax</th>
                     <th>Purpose</th>
                     <th>Example</th>
                 </tr>
             </thead>
             <tbody>
                 <tr>
-                    <td><code>=/</code></td>
+                    <td><code>=(/path)</code></td>
                     <td>Access a path in the global registry</td>
-                    <td><code>=/users/0/name</code></td>
+                    <td><code>=(/users/0/name)</code></td>
                 </tr>
                 <tr>
-                    <td><code>=function(</code></td>
+                    <td><code>=(function(...))</code></td>
                     <td>Call a helper function</td>
-                    <td><code>=sum(/items...price)</code></td>
+                    <td><code>=(sum(/items...price))</code></td>
+                </tr>
+                <tr>
+                    <td><code>#(xpath)</code></td>
+                    <td>XPath expression for DOM navigation</td>
+                    <td><code>#(../../@id)</code></td>
                 </tr>
             </tbody>
         </table>
         <p>
-            Once inside a JPRX expression, paths follow <strong>JSON Pointer</strong> syntax. The <code>=</code>
-            is only needed at the start of the expression for paths or function names.
+            The wrapper syntax <code>=()</code> and <code>#()</code> makes expressions unambiguous and eliminates
+            conflicts with literal strings.
+            Legacy syntax without parentheses (e.g., <code>=/path</code>) is still supported for backward compatibility.
         </p>
 
-        <h3 id="JPRX-escaping">Escaping the <code>=</code> Delimiter</h3>
+        <h3 id="JPRX-literal-strings">Literal Strings</h3>
         <p>
-            When using <strong>oDOM</strong> or <strong>vDOM</strong> (Object DOM), any string value starting with
-            <code>=</code> is interpreted as a JPRX expression. If you need a literal string that begins with
-            an equals sign (e.g., a mathematical equation or status message), you can escape it by prefixing
-            with a single quote:
+            With the new wrapper syntax, you no longer need escape sequences. Any string that doesn't match the wrapper
+            pattern
+            is treated as a literal:
         </p>
         <div class="code-block" style="margin-bottom: 1rem;">
-            <pre><code>// Interpreted as JPRX expression:
-{ "p": "=/user/name" }  // Resolves the path /user/name
+            <pre><code>// JPRX expression (wrapped):
+{ "p": "=(/user/name)" }  // Resolves the path /user/name
 
-// Escaped to produce a literal string:
-{ "p": "'=E=mc²" }      // Renders as "=E=mc²"
-{ "p": "'=42" }         // Renders as "=42"</code></pre>
+// Literal strings (no wrapper):
+{ "p": "=E=mc²" }         // Renders as "=E=mc²"
+{ "p": "=42" }            // Renders as "=42"
+{ "p": "#ff0000" }        // Renders as "#ff0000" (hex color)</code></pre>
         </div>
         <p>
-            The single-quote escape (<code>'=</code>) at the start of a string tells the parser to treat
-            the rest of the string (including the <code>=</code>) as literal content.
+            The wrapper syntax eliminates ambiguity: <code>=(expr)</code> is always an expression, while strings without
+            the wrapper pattern are always literals.
         </p>
 
         <h3 id="JPRX-anatomy">Anatomy of a Path</h3>
@@ -369,6 +404,44 @@ $('#example').content(hydrate(parseJPRX(cdom)));</code></pre>
             </tbody>
         </table>
 
+        <h3 id="JPRX-explosion">Explosion & Mapping (<code>...</code>)</h3>
+        <p>
+            The <code>...</code> operator is a powerful JPRX extension used for mapping properties from arrays and
+            spreading array elements as function arguments.
+        </p>
+
+        <h4>Mapping & Auto-Explosion: <code>path...property</code></h4>
+        <p>
+            When used between a path to an array and a property name, it acts as a shorthand for mapping. It extracts
+            the specified property from every object in the array. <strong>Inside a function call, it automatically
+                spreads (explodes) the resulting values as individual arguments.</strong>
+        </p>
+        <div class="code-block" style="margin-bottom: 1.5rem;">
+            <pre><code>// Correct: Maps 'price' and automatically spreads results as arguments to sum()
+=sum(/cart/items...price)
+
+// Mapping also works for direct display (returns an array)
+{ p: ["Prices: ", =/cart/items...price] }</code></pre>
+        </div>
+
+        <h4>Argument Spreading: <code>path...</code></h4>
+        <p>
+            When an array path is followed by a trailing <code>...</code> at the end of the path expression (and no
+            property name follows), the array elements are spread as individual arguments. Use this when you have a
+            direct reference to an array.
+        </p>
+        <div class="code-block">
+            <pre><code>// Passes each number in the array as a separate argument
+=sum(/listOfNumbers...)</code></pre>
+        </div>
+
+        <div class="warning-notice"
+            style="margin-top: 1.5rem; padding: 1rem; background: rgba(239, 68, 68, 0.1); border-left: 4px solid #ef4444; border-radius: 4px;">
+            <strong>Warning:</strong> Do not combine infix mapping with trailing dots. <code>/items...price...</code> is
+            invalid because the trailing dots are interpreted as part of the property name (looking for a property
+            literally named "price...").
+        </div>
+
         <!-- ===== COMPARISON TO EXCEL ===== -->
         <h2 id="comparison">Comparison to Excel</h2>
         <p>
@@ -536,8 +609,37 @@ $('#example').content(hydrate(parseJPRX(cdom)));</code></pre>
         <h3 id="lifecycle-state">Lifecycle State</h3>
         <p>
             In Lightview, you initialize state within the <code>onmount</code> hook. The <code>=state</code> and
-            <code>=signal</code> helpers accept an options object where you can specify a <code>scope</code>,
-            as well as <code>schema</code> requirements.
+            <code>=signal</code> helpers allow you to create reactive data that is tied to the DOM structure.
+        </p>
+
+        <h4 id="scope-resolution">Scope & Name Resolution</h4>
+        <p>
+            When JPRX encounters a name (e.g., <code>=/profile/name</code>), it doesn't just look in a global registry.
+            Instead, it performs an <strong>up-tree search</strong>:
+        </p>
+        <ol>
+            <li>It starts at the element where the expression is defined.</li>
+            <li>It looks for a registered signal or state with that name.</li>
+            <li>If not found, it moves to the parent element and repeats the search.</li>
+            <li>This continues all the way to the <code>document</code> root, finally checking the global registry if
+                needed.</li>
+        </ol>
+
+        <h4>The <code>$this</code> Placeholder</h4>
+        <p>
+            The <code>$this</code> keyword is a special placeholder that represents the <strong>current
+                element</strong>. When used in the <code>scope</code> option of <code>=state</code> or
+            <code>=signal</code>, it instructs Lightview to register the name specifically at that element's level in
+            the DOM.
+        </p>
+        <div class="code-block" style="margin-bottom: 1.5rem;">
+            <pre><code>// Scoping state to the current element creates a local namespace
+{ "onmount": "=state({ count: 0 }, { name: 'local', scope: $this })" }</code></pre>
+        </div>
+        <p>
+            This mechanism is what allows you to create <strong>reusable components</strong>. Each instance of a
+            component can have its own "local" state because the search for <code>local</code> will stop at the first
+            element it finds that has it registered—typically the root of the component instance.
         </p>
 
         <h4>Using a Registered Schema</h4>
@@ -578,10 +680,7 @@ Lightview.registerSchema('User', { name: 'string', age: 'number' });
     }
 }</code></pre>
         </div>
-        <p>
-            By scoping the state to the element, you can create multiple independent instances of components.
-            Lightview uses a high-performance <strong>up-tree search</strong> to resolve these names.
-        </p>
+
 
         <h3 id="bind-helper">Two-Way Binding ($bind)</h3>
         <p>
@@ -646,11 +745,11 @@ 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;",
-                children: ["Total: ", =currency(sum(/store/cart/items...price))]
+                children: ["Total: ", =(currency(sum(/store/cart/items...price)))]
             }}
         ]
     }
@@ -664,17 +763,15 @@ $('#example').content(hydrated);
         <!-- ===== INTERACTIVE EXAMPLE ===== -->
         <h2 id="interactive-example">Interactive Example</h2>
         <p>
-            Choose a syntax to see how the same reactive counter can be defined using standard JSON, concise JPRXC, or
+            Choose a syntax to see how the same reactive counter can be defined using standard JSON, concise cDOMC, or
             operator syntax.
         </p>
 
         <div role="tablist" class="syntax-tabs">
             <button id="tab-btn-jprx" class="syntax-tab syntax-tab-active" onclick="switchCDOMTab('jprx')">JPRX
                 (Standard)</button>
-            <button id="tab-btn-jprxc" class="syntax-tab" onclick="switchCDOMTab('jprxc')">JPRXC (Concise)</button>
+            <button id="tab-btn-cdomc" class="syntax-tab" onclick="switchCDOMTab('cdomc')">cDOMC</button>
             <button id="tab-btn-operators" class="syntax-tab" onclick="switchCDOMTab('operators')">Operators</button>
-            <button id="tab-btn-embedded" class="syntax-tab" onclick="switchCDOMTab('embedded')">Embedded
-                Signals</button>
         </div>
 
         <!-- JPRX Pane -->
@@ -690,18 +787,17 @@ $('#example').content(hydrated);
             </script><code contenteditable="true">// JPRX: Standard JSON format (strict)
 await import('/lightview-cdom.js');
 const { parseJPRX, hydrate } = globalThis.LightviewCDOM;
-const { signal, $ } = Lightview;
-
-const count = signal(0, 'count');
+const { $ } = Lightview;
 
 const cdomString = `{
     "div": {
+        onmount: "=signal(0, 'count')",
         "children": [
             { "h3": ["Standard JPRX Counter"] },
-            { "p": { "children": ["Count: ", "=/count"] }},
+            { "p": { "children": ["Count: ", "=(/count)"] }},
             { "div": { "children": [
-                { "button": { "onclick": "=decrement(/count)", "children": ["-"] } },
-                { "button": { "onclick": "=increment(/count)", "children": ["+"] } }
+                { "button": { "onclick": "=(decrement(/count))", "children": ["-"] } },
+                { "button": { "onclick": "=(increment(/count))", "children": ["+"] } }
             ]}}
         ]
     }
@@ -709,12 +805,11 @@ const cdomString = `{
 
 const hydrated = hydrate(parseJPRX(cdomString));
 $('#example').content(hydrated);
-globalThis.LightviewCDOM.activate(hydrated.domEl);
 </code></pre>
         </div>
 
-        <!-- JPRXC Pane -->
-        <div id="pane-jprxc" style="display: none;">
+        <!-- cDOMC Pane -->
+        <div id="pane-cdomc" style="display: none;">
             <pre><script>
                 examplify(document.currentScript.nextElementSibling, {
                     at: document.currentScript.parentElement,
@@ -722,21 +817,21 @@ globalThis.LightviewCDOM.activate(hydrated.domEl);
                     type: 'module',
                     height: '250px'
                 });
-            </script><code contenteditable="true">// JPRXC: Concise format (unquoted keys, comments)
+            </script><code contenteditable="true">// cDOMC: Compressed format (unquoted keys, comments)
 await import('/lightview-cdom.js');
 const { parseJPRX, hydrate } = globalThis.LightviewCDOM;
-const { signal, $ } = Lightview;
+const { $ } = ightview;
 
-const count = signal(0, 'count');
 
 const cdomString = `{
     div: {
+        onmount: =signal(0, 'count'),
         children: [
-            { h3: ["Concise Counter"] },
-            { p: { children: ["Count: ", =/count] }},
+            { h3: ["Compressed Counter"] },
+            { p: { children: ["Count: ", =(/count)] }},
             { div: { children: [
-                { button: { onclick: =decrement(/count), children: ["-"] } },
-                { button: { onclick: =increment(/count), children: ["+"] } }
+                { button: { onclick: =(decrement(/count)), children: ["-"] } },
+                { button: { onclick: =(increment(/count)), children: ["+"] } }
             ]}}
         ]
     }
@@ -760,19 +855,18 @@ globalThis.LightviewCDOM.activate(hydrated.domEl);
             </script><code contenteditable="true">// Operators: Using =++/path and =--/path
 await import('/lightview-cdom.js');
 const { parseJPRX, hydrate } = globalThis.LightviewCDOM;
-const { signal, $ } = Lightview;
-
-const count = signal(0, 'count');
+const { $ } = Lightview;
 
 const cdomString = `{
     div: {
+        onmount: =signal(0, 'count'),
         children: [
             { h3: ["Operator Counter"] },
-            { p: { children: ["Count: ", =/count] }},
+            { p: { children: ["Count: ", =(/count)] }},
             { div: { children: [
-                // Prefix operators: =-- and =++
-                { button: { onclick: =--/count, children: ["-"] } },
-                { button: { onclick: =++/count, children: ["+"] } }
+                // Prefix operators: =(--/count) and =(++/count)
+                { button: { onclick: =(--/count), children: ["-"] } },
+                { button: { onclick: =(++/count), children: ["+"] } }
             ]}}
         ]
     }
@@ -784,39 +878,6 @@ globalThis.LightviewCDOM.activate(hydrated.domEl);
 </code></pre>
         </div>
 
-        <!-- Embedded Pane -->
-        <div id="pane-embedded" style="display: none;">
-            <pre><script>
-                examplify(document.currentScript.nextElementSibling, {
-                    at: document.currentScript.parentElement,
-                    scripts: ['/lightview.js', '/lightview-x.js', '/lightview-cdom.js'],
-                    type: 'module',
-                    height: '250px'
-                });
-            </script><code contenteditable="true">// Embedded Signals: Using onmount to initialize local state
-await import('/lightview-cdom.js');
-const { parseJPRX, hydrate } = globalThis.LightviewCDOM;
-const { $ } = Lightview;
-
-const cdomString = `{
-    div: {
-        // Initialize a named signal explicitly scoped to '$this' element.
-        onmount: =signal(0, { name: 'count', scope: $this }),
-        children: [
-            { h3: ["Embedded Counter"] },
-            { p: ["Count: ", =/count] },
-            { div: { children: [
-                { button: { onclick: =--/count, children: ["-"] } },
-                { button: { onclick: =++/count, children: ["+"] } }
-            ]}}
-        ]
-    }
-}`;
-
-const hydrated = hydrate(parseJPRX(cdomString));
-$('#example').content(hydrated);
-</code></pre>
-        </div>
 
         <!-- ===== OPERATOR SYNTAX EXAMPLE ===== -->
         <h2 id="operator-syntax">Operator Syntax</h2>
@@ -938,7 +999,7 @@ LightviewCDOM.activate(document.getElementById('myApp'));</code></pre>
 
         <h3 id="api-hydrate">hydrate(object)</h3>
         <p>
-            Converts <code>$</code>-prefixed strings into reactive computed signals.
+            Converts <code>=/</code> prefixed strings into reactive computed signals.
         </p>
         <div class="code-block">
             <pre><code>const config = { title: "Dashboard", total: "=/cart/items...price" };