Skip to content

Latest commit

 

History

History
276 lines (219 loc) · 11.3 KB

AI-GUIDANCE.md

File metadata and controls

276 lines (219 loc) · 11.3 KB

Lightview AI Guidance

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.

Table of Contents

  1. Critical: Source Files vs Modules
  2. The Four UI Syntaxes
  3. Hypermedia & Lightview X
  4. JPRX & cDOM (AI-Safe Generation)
  5. Component System
  6. Routing & Navigation
  7. AI Development Strategies
  8. Deep Links & Resources

1. Critical: Source Files vs Modules

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').

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).

2. The Four UI Syntaxes

Choose the syntax that matches your goal.

A. Tagged API (Best for Logic)

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}`)
);

B. vDOM (Best for Structured Data)

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}`] }
  ]
};

C. oDOM (Best for Compact Templates)

"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"] } }
    ]
  }
};

D. Custom Elements (Best for Hybrid Apps)

Standard HTML tags powered by Lightview. Use these when enhancing an existing HTML page.

<lv-button onclick="alert('clicked')">Click Me</lv-button>

3. Hypermedia & Lightview X

Lightview X adds powerful Hypermedia capabilities to standard HTML elements.

The src and href Attributes (Hypermedia)

  • 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>
  • href: Non-standard tags (like div) with href act 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>

Advanced Fetches (data-method & data-body)

Customize HTTP requests for src and href actions.

  • data-method: Specify the HTTP verb (e.g., POST, PUT, DELETE). Defaults to GET.
  • data-body: The data to send with the request.
    • CSS Selector (Default): Grabs the data from the DOM.
      • form: Serialized as FormData.
      • input/select/textarea: Sends the current value.
      • checkbox/radio: Sends value only if checked.
      • Other elements: Sends innerText.
    • javascript:expr: Evaluates a Javascript expression (has access to state and signal).
    • json:{...}: Sends a literal JSON string (sets Content-Type: application/json).
    • text:...: Sends raw text (sets Content-Type: text/plain).
  • GET Requests: If the method is GET, the data from data-body is 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' }") via lightview-x.js.
  • Gating:
    1. Lightview.hooks.validateUrl: Intercept/block URLs.
    2. lv-before: Attribute that gates events (e.g., lv-before="click: throttle(500)" or custom functions).

Logic in Attributes (template literals)

Lightview X allows embedded ${} expressions in attributes for simple reactivity

{
  div: {
    class: "${ count.value > 10 ? 'text-red-500' : 'text-green-500' }",
    children: ["Status"]
  }
}

4. JPRX & cDOM (Safe Dynamic UI Generation For Humans and AIs)

cDOM (Computed DOM) and JPRX (JSON Reactive Expressions) allow you to build fully reactive UIs using only JSON.

Expression Syntax

  • =(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.

Name Resolution & Scoping

JPRX uses an up-tree search to find signals or states:

  1. Search starts at the element where the expression is defined.
  2. Bubbles up through parent elements looking for a registered name.
  3. 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.

The ... (Explosion) Operator

  • Infix Mapping (/path...property): Extracts property from every object in the /path array. 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)

The "Decentralized Layout" Pattern (AI Strategy)

  1. Define: Create a self-contained component with state.
  2. Move: Use =move('#target') in onmount to teleport it.
  3. 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)] } ]
  }
}

5. Component System

Built on DaisyUI and Tailwind CSS.

  • Import: import { Button } from './components/index.js';
  • Init: LightviewX.initComponents() (Shadow DOM).
  • Theming: Lightview.setTheme('dark') or localStorage.setItem('lightview-theme', 'dark').

6. Routing & Navigation

The LightviewRouter uses a pipeline (chain) architecture.

Advanced: Middleware Chains

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
);

Route Patterns

  • 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.

7. AI Development Strategies

Scenario A: "I need a full web application."

  • Strategy: Use Tagged API + lightview-router.js.
  • Output: Generate .js files.

Scenario B: "I need a dynamic dashboard widget of unknown nature at app development time."

  • Strategy: Use cDOM/JPRX.
  • Output: Stream .cdomc chunks.

Scenario C: "I need a config-driven UI."

  • Strategy: Use oDOM.
  • Output: Generate .json config files.

8. Deep Links & Resources


© 2026 AnyWhichWay LLC.