lightview 2.3.5 → 2.3.7

package/.gemini/XPATH_IMPLEMENTATION.md

@@ -0,0 +1,186 @@
+# XPath Integration for cDOM - Implementation Summary
+
+## Overview
+XPath support has been added to cDOM, allowing developers to navigate the DOM structure during element definition. This enables referencing parent/ancestor attributes without duplication.
+
+## Features Implemented
+
+### 1. Static XPath (`#` prefix)
+- **Syntax:** `#xpath-expression`
+- **Evaluation:** Once during DOM construction (two-pass approach)
+- **Reactivity:** None - becomes a static string value
+- **Escape Sequence:** `'#` produces literal `#` string
+
+  children: ["#@aria-label"]
+}
+```
+
+**Note on Text Nodes:** Even though the XPath refers to a child of the element, it is evaluated relative to the element itself (`self::*`). This improves consistency between attributes and children, and avoids "Operation is not supported" errors in browsers when using a Text node as an XPath context.
+
+### 2. Reactive XPath (`=xpath()` helper)
+- **Syntax:** `=xpath('expression')`
+- **Evaluation:** As JPRX helper, returns computed signal
+- **Reactivity:** Re-evaluates when observed DOM changes (TODO: full MutationObserver)
+- **Composable:** Can mix with JPRX expressions
+
+**Example:**
+```javascript
+{
+  attributes: {
+    title: "=xpath('../@id')",
+    class: "=concat(xpath('../@disabled'), ' ', $/theme)"
+  }
+}
+```
+
+## Allowed XPath Axes (Backward-Only)
+✅ `self::` or `.` - current node  
+✅ `parent::` or `..` - parent node  
+✅ `ancestor::` - all ancestors  
+✅ `ancestor-or-self::`  
+✅ `preceding-sibling::` - earlier siblings  
+✅ `preceding::` - all preceding nodes  
+
+❌ `child::` - forward reference (not allowed)  
+❌ `descendant::` - forward reference (not allowed)  
+❌ `following::` - forward reference (not allowed)  
+❌ `following-sibling::` - forward reference (not allowed)  
+
+## Implementation Details
+
+### Files Modified
+
+1. **`jprx/parser.js`**
+   - Added `preprocessXPath()` function to quote unquoted `#xpath` expressions in cDOMC
+   - Handles escape sequences (`'#`)
+   - Skips quoted strings and comments
+
+2. **`src/lightview-cdom.js`**
+   - Updated `hydrate()` to detect and mark `#xpath` expressions
+   - Added `validateXPath()` to ensure no forward-looking axes
+   - Added `resolveStaticXPath()` for two-pass XPath resolution
+   - Registered `registerDOMHelpers` for reactive xpath() helper
+   - Exported `resolveStaticXPath` for global access
+
+3. **`src/lightview.js`**
+   - Updated `makeReactiveAttributes()` to handle `__xpath__` markers from hydration
+   - Updated `processChildren()` to handle XPath markers in children arrays
+   - Added call to `resolveStaticXPath()` after DOM tree construction
+
+4. **`jprx/helpers/dom.js`** (NEW)
+   - Created reactive `xpath()` helper function
+   - Returns computed signal for XPath evaluation
+   - Validates against forward-looking axes
+   - TODO: Add Mutation Observer for full reactivity
+
+5. **`jprx/index.js`**
+   - Exported `registerDOMHelpers`
+
+### Two-Pass Resolution Flow
+
+**Pass 1: Build DOM Tree**
+1. `parseCDOMC()` preprocesses input, quoting unquoted `#xpath` expressions
+2. `hydrate()` detects `#xpath` strings, marks with `{ __xpath__: 'expr', __static__: true }`
+3. `element()` creates DOM nodes
+4. `makeReactiveAttributes()` sets `data-xpath-{attrname}` markers on nodes
+5. `processChildren()` creates text nodes with `__xpathExpr` property
+6. Tree is fully constructed via `appendChild()`
+
+**Pass 2: Resolve XPath**
+7. `resolveStaticXPath()` called after tree construction
+8. Walks tree with `TreeWalker`
+9. Finds nodes with `data-xpath-*` attributes or `__xpathExpr` properties
+10. Validates XPath expressions (no forward-looking)
+11. Calls browser's `document.evaluate()` with node as context
+12. Sets resolved values and cleans up markers
+
+## Usage Examples
+
+### cDOMC (Unquoted)
+```javascript
+{
+  tag: div,
+  attributes: {
+    id: parent-div,
+    data-theme: dark
+  },
+  children: [{
+    tag: button,
+    attributes: {
+      data-parent-id: #../@id,
+      class: "=concat(xpath('../@data-theme'), '-button')"
+    },
+    children: [#@aria-label]
+  }]
+}
+```
+
+### JSON
+```javascript
+{
+  "tag": "div",
+  "attributes": {
+    "id": "parent-div",
+    "data-theme": "dark"
+  },
+  "children": [{
+    "tag": "button",
+    "attributes": {
+      "data-parent-id": "#../@id",
+      "class": "=concat(xpath('../@data-theme'), '-button')"
+    },
+    "children": ["#@aria-label"]
+  }]
+}
+```
+
+## Testing
+
+Test file created: `test-xpath.html`
+
+Open in browser to verify:
+- Static XPath in attributes
+- Parent attribute access
+- Escape sequences
+
+## Key Features
+
+1. **Unquoted XPath in cDOMC**: Fully supported through structural integration with the parser character loop.
+   - ✅ Working: `children: [#@id]`
+   - ✅ Working: `children: [#div[@id='1']]` (Complex paths with brackets now work!)
+   
+2. **Reactive xpath() helper**: Currently evaluates once via computed signal. Full reactivity with MutationObserver is TODO.
+
+3. **XPath complexity**: Works with paths like `../@id`, `../../@attr`, and predicate-based paths.
+
+4. **Consistency**: Both attributes and children evaluate XPath relative to the Element node. This avoids browser issues with Text node context and simplifies the developer's mental model.
+
+## Implementation: Structural Parser Integration
+
+Instead of a string preprocessor hack, XPath support is now integrated directly into the `parseCDOMC` word parser.
+
+- When `parseWord` encounters `#`, it enters a permissive "expression mode" (similar to `=` JPRX).
+- In this mode, it tracks nesting depth for `[]`, `{}`, and `()`.
+- It handles internal quotes within the XPath safely.
+- It only terminates the unquoted word when nesting depth is `0` and it encounters a structural cDOMC delimiter (e.g., `]`, `}`, or `,`).
+
+## Bug Fixes Applied
+
+1. **Structural Delimiters**: Fixed the issue where unquoted XPath would consume the closing bracket of its container.
+2. **Complex Paths**: Enabled support for square brackets and other structural characters within the XPath itself.
+3. **Text node context**: Fixed XPath evaluation to use the text node itself as context, not its parent element.
+
+## Next Steps
+
+1. Add MutationObserver to reactive xpath() helper for full reactivity
+2. Add comprehensive unit tests for both static and reactive XPath
+3. Document XPath support in cDOM documentation
+4. Add more examples showing different XPath axes
+5. Performance optimization for large DOMs
+
+## Lint Issues
+
+Note: The following lint warnings exist but don't affect functionality:
+- **File length**: `/mnt/c/Users/Owner/AntigravityProjects/lightview/jprx/parser.js` has 1552 lines (limit 500)
+  - This is a large parser file; could be split/refactored in the future
+- **Escape characters**: Some unnecessary escapes in regex (cosmetic issue)

package/1769196538097-package.json

@@ -0,0 +1,43 @@
+{
+  "name": "lightview",
+  "version": "2.3.7",
+  "description": "A lightweight reactive UI library with features of Bau, Juris, and HTMX",
+  "main": "lightview.js",
+  "workspaces": [
+    "jprx"
+  ],
+  "directories": {
+    "doc": "docs"
+  },
+  "scripts": {
+    "dev": "wrangler pages dev . --port 3000",
+    "preview": "npm run build && wrangler pages dev ./dist --port 8788",
+    "build": "node build-bundles.mjs && node build.js",
+    "watch": "node build-bundles.mjs && node build.js --watch --env=dev",
+    "deploy": "npm run build && wrangler pages deploy dist",
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [],
+  "author": "Simon Y. Blackwell, AnyWhichWay LLC",
+  "license": "MIT",
+  "type": "commonjs",
+  "devDependencies": {
+    "@grucloud/bau": "^0.106.0",
+    "acorn": "^8.15.0",
+    "acorn-walk": "^8.3.4",
+    "htmx.org": "^2.0.8",
+    "jsdom": "^27.4.0",
+    "juris": "^0.9.0",
+    "react": "^19.2.3",
+    "terser": "^5.24.0",
+    "vite": "^5.0.0",
+    "vitest": "^4.0.16",
+    "wrangler": "^4.54.0"
+  },
+  "dependencies": {
+    "expr-eval": "^2.0.2",
+    "jprx": "^1.3.1",
+    "linkedom": "^0.18.12",
+    "marked": "^17.0.1"
+  }
+}

package/_headers

@@ -2,3 +2,8 @@
   Access-Control-Allow-Origin: *
   Access-Control-Allow-Methods: GET, OPTIONS
   Access-Control-Allow-Headers: *
+
+/*.cdom
+  Content-Type: application/cdom
+/*.cdomc
+  Content-Type: application/cdomc

package/_routes.json

@@ -0,0 +1,7 @@
+{
+    "version": 1,
+    "include": [
+        "/*"
+    ],
+    "exclude": []
+}

package/build-bundles.mjs

@@ -102,4 +102,14 @@ if (isWatch) {
             }, 300); // 300ms debounce
         }
     });
+
+    // Also watch jprx directory for parser changes
+    watch(resolve(__dirname, 'jprx'), { recursive: true }, (event, filename) => {
+        if (filename && !filename.includes('~')) {
+            clearTimeout(debounceTimer);
+            debounceTimer = setTimeout(() => {
+                runBuilds();
+            }, 300);
+        }
+    });
 }

package/build_tmp/lightview-router.js

@@ -0,0 +1,185 @@
+(function() {
+  "use strict";
+  (() => {
+    const base = (shellPath) => {
+      if (typeof window === "undefined" || document.getElementById("content")) return;
+      const url = new URL(shellPath, globalThis.location.href);
+      url.searchParams.set("load", globalThis.location.pathname);
+      globalThis.location.href = url.toString();
+    };
+    const router = (options = {}) => {
+      const { base: base2 = "", contentEl, notFound, debug, onResponse, onStart } = options;
+      const chains = [];
+      const normalizePath = (p) => {
+        if (!p) return "/";
+        let hash = "";
+        if (p.includes("#")) {
+          [p, hash] = p.split("#");
+          hash = "#" + hash;
+        }
+        try {
+          if (p.startsWith("http") || p.startsWith("//")) p = new URL(p, globalThis.location.origin).pathname;
+        } catch (e) {
+        }
+        if (base2 && p.startsWith(base2)) p = p.slice(base2.length);
+        return (p.replace(/\/+$/, "").replace(/^([^/])/, "/$1") || "/") + hash;
+      };
+      const createMatcher = (pattern) => {
+        if (typeof pattern === "function") return pattern;
+        return (ctx) => {
+          const { path } = ctx;
+          const pathOnly = path.split("#")[0];
+          if (pattern instanceof RegExp) {
+            const m2 = pathOnly.match(pattern);
+            return m2 ? { ...ctx, match: m2 } : null;
+          }
+          if (pattern === "*" || pattern === pathOnly) return { ...ctx, wildcard: pathOnly };
+          const keys = [];
+          const regexStr = "^" + pattern.replace(/[.*+?^${}()|[\]\\]/g, "\\$&").replace(/\\\*/g, "(.*)").replace(/:([^/]+)/g, (_, k) => (keys.push(k), "([^/]+)")) + "$";
+          const m = pathOnly.match(new RegExp(regexStr));
+          if (m) {
+            const params = {};
+            keys.forEach((k, i) => params[k] = m[i + 1]);
+            return { ...ctx, params, wildcard: m[1] };
+          }
+          return null;
+        };
+      };
+      const createReplacer = (pat) => (ctx) => {
+        const [path, hash] = ctx.path.split("#");
+        return {
+          ...ctx,
+          path: pat.replace(/\*|:([^/]+)/g, (m, k) => {
+            var _a;
+            return (k ? (_a = ctx.params) == null ? void 0 : _a[k] : ctx.wildcard) || m;
+          }) + (hash ? "#" + hash : "")
+        };
+      };
+      const fetchHandler = async (ctx) => {
+        try {
+          const pathOnly = ctx.path.split("#")[0];
+          const res = await fetch(pathOnly);
+          if (res.ok) return res;
+        } catch (e) {
+          if (debug) console.error("[Router] Fetch error:", e);
+        }
+        return null;
+      };
+      const use = (...args) => {
+        const chain = args.map((arg, i) => i === 0 && typeof arg !== "function" ? createMatcher(arg) : typeof arg === "string" ? createReplacer(arg) : arg);
+        if (contentEl && !chain.some((f) => f.name === "fetchHandler" || args.some((a) => typeof a === "function"))) chain.push(fetchHandler);
+        chains.push(chain);
+        return routerInstance;
+      };
+      const route = async (raw) => {
+        let ctx = { path: normalizePath(raw), contentEl };
+        if (debug) console.log(`[Router] Routing: ${ctx.path}`);
+        for (const chain of chains) {
+          let res = ctx, failed = false;
+          for (const fn of chain) {
+            try {
+              res = await fn(res);
+              if (res instanceof Response) return res;
+              if (!res) {
+                failed = true;
+                break;
+              }
+            } catch (e) {
+              console.error("[Router] Chain error:", e);
+              failed = true;
+              break;
+            }
+          }
+          if (!failed) ctx = typeof res === "string" ? { ...ctx, path: res } : { ...ctx, ...res };
+        }
+        return notFound ? notFound(ctx) : null;
+      };
+      const handleRequest = async (path) => {
+        var _a, _b;
+        if (onStart) onStart(path);
+        const internals = (_a = globalThis.Lightview) == null ? void 0 : _a.internals;
+        const scrollMap = (_b = internals == null ? void 0 : internals.saveScrolls) == null ? void 0 : _b.call(internals);
+        const res = await route(path);
+        if (!res) return console.warn(`[Router] No route: ${path}`);
+        if (res.ok && contentEl) {
+          contentEl.innerHTML = await res.text();
+          contentEl.querySelectorAll("script").forEach((s) => {
+            const n = document.createElement("script");
+            [...s.attributes].forEach((a) => n.setAttribute(a.name, a.value));
+            n.textContent = s.textContent;
+            s.replaceWith(n);
+          });
+          if ((internals == null ? void 0 : internals.restoreScrolls) && scrollMap) {
+            internals.restoreScrolls(scrollMap);
+          }
+          const urlParts = path.split("#");
+          const hash = urlParts.length > 1 ? "#" + urlParts[1] : "";
+          if (hash) {
+            requestAnimationFrame(() => {
+              requestAnimationFrame(() => {
+                const id = hash.slice(1);
+                const target = document.getElementById(id);
+                if (target) {
+                  target.style.scrollMarginTop = "calc(var(--site-nav-height, 0px) + 2rem)";
+                  target.scrollIntoView({ behavior: "smooth", block: "start", inline: "start" });
+                }
+              });
+            });
+          }
+        }
+        if (onResponse) await onResponse(res, path);
+        return res;
+      };
+      const navigate = (path) => {
+        const p = normalizePath(path);
+        return handleRequest(base2 + p).then((r) => {
+          let dest = (r == null ? void 0 : r.url) ? new URL(r.url, globalThis.location.origin).pathname : base2 + p;
+          if (p.includes("#") && !dest.includes("#")) {
+            dest += "#" + p.split("#")[1];
+          }
+          globalThis.history.pushState({ path: dest }, "", dest);
+        }).catch((e) => console.error("[Router] Nav error:", e));
+      };
+      const start = async () => {
+        const load = new URLSearchParams(globalThis.location.search).get("load");
+        globalThis.onpopstate = (e) => {
+          var _a;
+          return handleRequest(((_a = e.state) == null ? void 0 : _a.path) || normalizePath(globalThis.location.pathname + globalThis.location.hash));
+        };
+        document.onclick = (e) => {
+          const path = e.composedPath();
+          const a = path.find((el) => {
+            var _a;
+            return el.tagName === "A" && ((_a = el.hasAttribute) == null ? void 0 : _a.call(el, "href"));
+          });
+          if (!a || a.target === "_blank" || /^(http|#|mailto|tel)/.test(a.getAttribute("href"))) return;
+          const url = new URL(a.href, document.baseURI);
+          if (url.origin === globalThis.location.origin) {
+            e.preventDefault();
+            const fullPath = url.pathname + url.search + url.hash;
+            navigate(normalizePath(fullPath));
+          }
+        };
+        const init = load || normalizePath(globalThis.location.pathname + globalThis.location.hash);
+        globalThis.history.replaceState({ path: init }, "", base2 + init);
+        return handleRequest(init).then(() => routerInstance);
+      };
+      const routerInstance = { use, navigate, start };
+      return routerInstance;
+    };
+    const LightviewRouter = { base, router };
+    if (typeof module !== "undefined" && module.exports) module.exports = LightviewRouter;
+    else if (typeof window !== "undefined") {
+      globalThis.LightviewRouter = LightviewRouter;
+      try {
+        const script = document.currentScript;
+        if (script && script.src.includes("?")) {
+          const params = new URL(script.src).searchParams;
+          const b = params.get("base");
+          if (b) LightviewRouter.base(b);
+        }
+      } catch (e) {
+      }
+    }
+  })();
+})();