This document is the definitive guide for Large Language Models (LLMs) on how to effectively use the Lightview library. It covers all development workflows, particularly emphasizing correct source file usage, hypermedia patterns, and dynamic generation.
- Critical: Source Files vs Modules
- The Four UI Syntaxes
- Hypermedia & Lightview X
- JPRX & cDOM (AI-Safe Generation)
- Component System
- Routing & Navigation
- AI Development Strategies
- Deep Links & Resources
PAY CAREFUL ATTENTION TO FILE TYPES.
-
Standard Scripts (
.js): These files exist in the root and are suitable for direct browser inclusion via script tags or simple bundling.lightview.js: The core reactive engine (Signals, State, $, Effect).lightview-x.js: The "Extension" module (Hypermedia, src fetching, simple validation, vDOM/oDOM conversion).lightview-router.js: The Router implementation.lightview-cdom.js: The parser for JPRX and cDOM.
-
ES Modules (in subdirectories): Files in
jprx/,components/, etc., are ES modules.- Do not reference these directly in a generic HTML script tag without
type="module". - Do import them in your application logic files (e.g.,
import { ... } from './jprx/parser.js').
- Do not reference these directly in a generic HTML script tag without
Guidance: When helping a user set up a new project, prefer importing from the root standard scripts for simplicity, or set up a proper build.js if deep module imports are needed.
Note on Syntaxes:
- Tagged API: Supported in
lightview.js. - vDOM: Supported in
lightview.js(standard{ tag: ... }objects). - oDOM: Requires
lightview-x.js(converts{ div: ... }usage).
Choose the syntax that matches your goal.
Javascript functions representing HTML tags. Best for building applications with complex logic.
const { div, h1, button } = Lightview.tags;
const count = signal(0);
const view = div({ class: "p-4" },
h1("Counter"),
button({ onclick: () => count.value++ }, () => `Count: ${count.value}`)
);Explicit JSON structure. Use this when you need a standard, serializable format.
const view = {
tag: "div",
attributes: { class: "p-4" },
children: [
{ tag: "h1", children: ["Counter"] },
{ tag: "button", attributes: { onclick: () => count.value++ }, children: [() => `Count: ${count.value}`] }
]
};"Object DOM" uses keys as tags. It is significantly more concise. Preferred for configuration-based UIs.
const view = {
div: {
class: "p-4",
children: [
{ h1: "Counter" },
{ button: { onclick: "...", children: ["Increment"] } }
]
}
};Standard HTML tags powered by Lightview. Use these when enhancing an existing HTML page.
<lv-button onclick="alert('clicked')">Click Me</lv-button>Lightview X adds powerful Hypermedia capabilities to standard HTML elements.
src: Fetches content and replaces the element or its content.- Support:
.html,.json,.vdom,.odom,.cdom,.cdomc - Usage:
<div src="/components/user-card.vdom"></div>
- Support:
href: Non-standard tags (likediv) withhrefact as "Links".- Behavior: Clicking them fetches the content at the URL and replaces the element's
src. - Targeting: Use
target="#dest:beforeend"to direct the content elsewhere. - Usage:
<div href="/api/next-page" target="#content:beforeend">Load More</div>
- Behavior: Clicking them fetches the content at the URL and replaces the element's
Customize HTTP requests for src and href actions.
data-method: Specify the HTTP verb (e.g.,POST,PUT,DELETE). Defaults toGET.data-body: The data to send with the request.- CSS Selector (Default): Grabs the data from the DOM.
form: Serialized asFormData.input/select/textarea: Sends the currentvalue.checkbox/radio: Sendsvalueonly if checked.- Other elements: Sends
innerText.
javascript:expr: Evaluates a Javascript expression (has access tostateandsignal).json:{...}: Sends a literal JSON string (setsContent-Type: application/json).text:...: Sends raw text (setsContent-Type: text/plain).
- CSS Selector (Default): Grabs the data from the DOM.
- GET Requests: If the method is
GET, the data fromdata-bodyis automatically converted into URL Query Parameters.
Usage:
<!-- Post a form -->
<button href="/api/user/save" data-method="POST" data-body="#user-form">Save</button>
<!-- Fetch with query params from an input -->
<button href="/api/search" data-body="#search-input" target="#results">Search</button>- Template Literals: Supported in HTML, vDOM, and oDOM strings (e.g.,
class="${ val > 10 ? 'red' : 'blue' }") vialightview-x.js. - Gating:
Lightview.hooks.validateUrl: Intercept/block URLs.lv-before: Attribute that gates events (e.g.,lv-before="click: throttle(500)"or custom functions).
Lightview X allows embedded ${} expressions in attributes for simple reactivity
{
div: {
class: "${ count.value > 10 ? 'text-red-500' : 'text-green-500' }",
children: ["Status"]
}
}cDOM (Computed DOM) and JPRX (JSON Reactive Expressions) allow you to build fully reactive UIs using only JSON.
=(expr)(JPRX): Wraps reactive expressions that navigate reactive state (Signals/States). Use=(/path)for paths,=(function(...))for helpers.#(xpath)(cDOM XPath): Wraps XPath expressions that navigate the DOM tree during construction. Use#(../../@id)to navigate ancestors and access attributes.
Note: For initialization functions like state() and signal(), use =function(...) without the outer wrapper, as they execute once on mount rather than being reactive expressions.
JPRX uses an up-tree search to find signals or states:
- Search starts at the element where the expression is defined.
- Bubbles up through parent elements looking for a registered name.
- Falls back to the global registry.
The $this Placeholder:
Use { scope: $this } in =state or =signal to register data specifically at the current element's level. This is essential for creating multiple independent instances of a component.
- Infix Mapping (
/path...property): Extractspropertyfrom every object in the/patharray. Inside a function call, it automatically explodes the results into separate arguments. - Trailing Spread (
/path...): Spreads a direct array reference into individual arguments. - Warning: Never write
/path...property.... The trailing dots will be incorrectly included in the property name lookup.
| Category | Helpers |
|---|---|
| Math | add, subtract, multiply, divide, mod, pow, abs, round, ceil, floor, sqrt, negate, toPercent |
| Logic | and, or, not, if, eq, neq, gt, lt, gte, lte |
| String | join, concat, upper, lower, trim, len, split, replace, capitalize, contains |
| Array | map, filter, reduce, push, pop, sort, reverse, slice, find |
| Stats | sum, avg, min, max, median, stdev, variance |
| Data | lookup(val, searchArr, resultArr) (VLOOKUP-style) |
| State | state(val, opts), set(path, val), bind(path), increment, decrement, toggle |
| DOM | #(path) (XPath Navigation), move(target, loc) |
| Net | fetchHelper(url, opts), mount(url, opts) |
- Define: Create a self-contained component with state.
- Move: Use
=move('#target')inonmountto teleport it. - Stream: Determine the update needed, generate the
.cdomc, and let it patch itself.
/* .cdomc format */
{
div: {
id: "widget-1",
onmount: ["=state({val:0}, {name:'w1', scope:$this})", "=move('#sidebar')"],
children: [ { p: ["Val: ", =(/w1/val)] } ]
}
}Built on DaisyUI and Tailwind CSS.
- Import:
import { Button } from './components/index.js'; - Init:
LightviewX.initComponents()(Shadow DOM). - Theming:
Lightview.setTheme('dark')orlocalStorage.setItem('lightview-theme', 'dark').
The LightviewRouter uses a pipeline (chain) architecture.
You can chain multiple handlers for a single route. This is powerful for authentication or data pre-loading.
const checkAuth = async (ctx) => {
const user = await getUser();
if (!user) {
LightviewRouter.navigate('/login');
return null; // Stop chain
}
return { ...ctx, user }; // Pass data to next handler
};
router.use(
'/admin/*',
checkAuth, // 1. Guard
'/views/admin.html' // 2. Render
);- Static:
router.use('/about', 'about.html') - Wildcard:
router.use('/docs/*', handler)-> matches/docs/api/v1 - Parameters:
router.use('/users/:id', handler)->ctx.params.id - Replacement:
router.use('/blog/:slug', '/content/posts/:slug.html')-> Maps URL params to file path automatically.
Scenario A: "I need a full web application."
- Strategy: Use Tagged API + lightview-router.js.
- Output: Generate
.jsfiles.
Scenario B: "I need a dynamic dashboard widget of unknown nature at app development time."
- Strategy: Use cDOM/JPRX.
- Output: Stream
.cdomcchunks.
Scenario C: "I need a config-driven UI."
- Strategy: Use oDOM.
- Output: Generate
.jsonconfig files.
- Documentation Home: docs/index.html
- Core Logic: lightview.js and docs/api/index.html
- Extension (Hypermedia): lightview-x.js and docs/api/hypermedia.html
- Router: lightview-router.js and docs/router.html
- CDOM/JPRX Parser: lightview-cdom.js and docs/cdom.html
- Component Index: components/index.js and docs/components/index.html
- JPRX Helpers: jprx/helpers/ and docs/cdom#helpers
© 2026 AnyWhichWay LLC.