jails-js 6.9.8 → 6.9.9

package/ai/json/recipes.json

@@ -0,0 +1,96 @@
+[
+  {
+    "name": "Counter",
+    "description": "Minimal local state update with delegated events.",
+    "examples": [
+      "<app-counter><button data-subtract>-</button><span html-inner=\"counter\">0</span><button data-add>+</button></app-counter>",
+      "state.set(s => { s.counter += 1 })"
+    ],
+    "rules": ["Define counter in model.", "Use delegated click handlers."],
+    "relatedConcepts": ["state.set", "html-inner", "on"],
+    "antiPatterns": ["Using DOM text as source of truth."],
+    "performanceNotes": "One root listener per event pattern; stable scalar update."
+  },
+  {
+    "name": "Loading and Error States",
+    "description": "Fetch data in controller and render loading/error/data branches.",
+    "examples": ["<p html-if=\"loading\">Loading</p>", "<p html-if=\"error\">{{ error.message }}</p>", "<li html-for=\"user in users\">{{ user.name }}</li>"],
+    "rules": ["Fetch in main/controller, not template.", "Keep loading, error, and data explicit in model."],
+    "relatedConcepts": ["html-if", "html-for", "dependencies"],
+    "antiPatterns": ["Side effects in directives."],
+    "performanceNotes": "Loop renders only when data branch is active if guarded by html-if."
+  },
+  {
+    "name": "Modal",
+    "description": "Toggle dialog branch with boolean state.",
+    "examples": ["<section html-if=\"open\" role=\"dialog\" aria-modal=\"true\">...</section>"],
+    "rules": ["Use state for open/closed.", "Use state.set().then() for focus after opening."],
+    "relatedConcepts": ["html-if", "state.set"],
+    "antiPatterns": ["Expecting internal input values to persist after html-if removal."],
+    "performanceNotes": "Creates/removes dialog DOM; use CSS hiding for large persistent dialogs."
+  },
+  {
+    "name": "Tabs",
+    "description": "Use one activeTab state value for buttons and panels.",
+    "examples": ["<button data-tab=\"profile\" html-class=\"activeTab === 'profile' ? 'active' : ''\">Profile</button>"],
+    "rules": ["Use delegateTarget.dataset.tab.", "Keep active state single-source."],
+    "relatedConcepts": ["html-class", "html-if", "delegateTarget"],
+    "antiPatterns": ["Reading event.target.dataset from nested elements."],
+    "performanceNotes": "Small panels can be conditionally created; large panels may need preservation strategy."
+  },
+  {
+    "name": "Accordion",
+    "description": "Use html-for plus openIndex state.",
+    "examples": ["<article html-for=\"item in items\"><button data-toggle html-data-index=\"$index\">{{ item.title }}</button><div html-if=\"openIndex === $index\">{{ item.body }}</div></article>"],
+    "rules": ["Convert dataset indexes to numbers.", "Avoid heavy content in every repeated branch."],
+    "relatedConcepts": ["html-for", "$index", "html-if"],
+    "antiPatterns": ["Nested expensive widgets in every item without lazy/static boundary."],
+    "performanceNotes": "Render cost grows with number of items and content branch size."
+  },
+  {
+    "name": "Fetch API With Service Dependency",
+    "description": "Inject HTTP service and update state from async controller logic.",
+    "examples": ["register('app-posts', appPosts, { http })", "const posts = await http.get('/posts')"],
+    "rules": ["Inject app-specific HTTP clients.", "Reflect async state through model keys."],
+    "relatedConcepts": ["dependencies", "main", "state.set"],
+    "antiPatterns": ["Hard-coded services in generic components."],
+    "performanceNotes": "Keeps unused service code out of reusable modules."
+  },
+  {
+    "name": "Optimistic Updates",
+    "description": "Update state before API confirmation and rollback on failure.",
+    "examples": ["const previous = state.get().todos", "await state.set({ todos })"],
+    "rules": ["Snapshot previous state.", "Rollback in catch."],
+    "relatedConcepts": ["state.get", "state.set"],
+    "antiPatterns": ["Mutating previous snapshot in place."],
+    "performanceNotes": "Immediate UI feedback; clone collections to avoid reference bugs."
+  },
+  {
+    "name": "Debounced Search",
+    "description": "Debounce input events and keep input browser-owned with html-static.",
+    "examples": ["<input type=\"search\" html-static>", "timer = setTimeout(() => run(query), 250)"],
+    "rules": ["Clear previous timer.", "Use html-static if state does not need every typed character."],
+    "relatedConcepts": ["html-static", "on", "state.set"],
+    "antiPatterns": ["Network request and render on every keystroke."],
+    "performanceNotes": "Reduces request frequency and render churn."
+  },
+  {
+    "name": "Intersection Observer Lazy Rendering",
+    "description": "Set visible state when component enters viewport and cleanup observer on unmount.",
+    "examples": ["<section html-if=\"visible\">Expensive content</section>", "unmount(() => observer.disconnect())"],
+    "rules": ["Disconnect observer after use.", "Cleanup in unmount."],
+    "relatedConcepts": ["html-if", "unmount"],
+    "antiPatterns": ["Observers retaining detached elements."],
+    "performanceNotes": "Defers creating expensive DOM until needed."
+  },
+  {
+    "name": "Virtual List Boundary",
+    "description": "Let a virtual list library own a static subtree while Jails owns surrounding state.",
+    "examples": ["<div class=\"virtual-list\" html-static></div>"],
+    "rules": ["Do not put html-for inside external virtualized root.", "Keep surrounding counters in Jails state."],
+    "relatedConcepts": ["html-static", "DOM ownership"],
+    "antiPatterns": ["Two renderers owning the same list DOM."],
+    "performanceNotes": "Avoids huge Jails loop renders and protects virtualizer DOM."
+  }
+]
+

package/ai/llms.txt

@@ -0,0 +1,96 @@
+# Jails
+
+## Philosophy
+
+Jails enhances existing HTML custom elements. It is not a full-page SPA runtime by default. Use SSR/SSG/CMS/static HTML for first paint, then mount small interactive islands. HTML declares rendering; JS controllers declare behavior.
+
+## Rendering Model
+
+Call `register(name, module, dependencies?)`, then `start(target?)`. `start()` scans `target || document.body` for registered custom elements and bootstraps one component instance per element. State comes from required `model` plus optional `html-model`. Optional `view(state)` returns render-only scope. Optional `template({ elm, children })` returns embedded HTML. Directives and `{{ }}` evaluate JavaScript expressions. `state.set()` updates state, triggers DOM updates, and returns a Promise resolved after update.
+
+## Core Rules
+
+- Component boundary is the custom element.
+- State is component-local by default.
+- Parent updates can pass props to children unless child calls `state.protected([...])`.
+- Use `main()` for mount-time setup.
+- Use delegated `on()` events; read `event.delegateTarget`.
+- Use `unmount()` for cleanup.
+- Use `emit()` for bubbling DOM events; use `publish/subscribe` for cross-tree global messages.
+- Use `html-static` when DOM is owned by browser/external libraries.
+
+## Directives
+
+- `html-if="expr"`: conditionally creates/removes node. Falsy branch absent from DOM.
+- `html-for="item in list"`: repeats element for arrays/objects. Provides `$index` and `$key`. Keyed diffing not documented; assume order-based.
+- `html-inner="expr"`: writes expression into element, replacing fallback content after mount.
+- `html-model="{ ... }"`: initial state from markup; overrides model props at bootstrap.
+- `html-*="expr"`: binds real attribute after stripping `html-`; boolean attrs are present truthy, removed falsy.
+- `html-static`: skips virtual DOM/diff updates for node and children.
+- `{{ expr }}`: text interpolation; delimiters configurable with `templateConfig({ tags: [...] })`.
+- `<template>`: native inert content; use to hide unresolved dynamic fragments before data exists.
+
+## Common Patterns
+
+- Progressive island: static HTML + component behavior.
+- Page-scoped state: page component owns data/loading/error.
+- Services via dependencies: `register('x', module, { http, validations })`.
+- Delegated events: `on('click', '[data-add]', add)`.
+- Static integration: third-party widget root has `html-static`.
+- Fetch flow: `main(load)`, set loading/data/error through state.
+
+## Best Practices
+
+- Keep directive expressions cheap and deterministic.
+- Derive render-only values in `view`, not persistent state.
+- Define all local state keys in `model`.
+- Use `state.set().then()` for focus/measure/animation after render.
+- Prefer DOM events over global pub/sub when components share a DOM path.
+- Keep templates flat; avoid deeply nested `html-for`.
+- Use `html-inner` fallback or `<template>` to avoid marker flash.
+- Cleanup subscriptions/observers/widgets in `unmount()`.
+
+## Anti-patterns
+
+- Side effects in directives/mustache/view.
+- Mutating Jails-managed DOM with external libraries without `html-static`.
+- One event listener per repeated item.
+- Using `event.target` instead of `delegateTarget`.
+- Treating `html-model` as reactive after mount.
+- Large serialized payloads in HTML attributes.
+- Global pub/sub for local child-parent messages.
+- Assuming keyed loop reconciliation without runtime proof.
+
+## Canonical Architecture
+
+`main.ts` registers components and starts Jails. Components export default controller and required `model`; optional `view` and `template`. Controllers coordinate events, services, and state. HTML contains custom element islands and directives. Services live outside components or are injected as dependencies.
+
+## Minimal Examples
+
+```ts
+import { register, start } from 'jails-js'
+import * as counter from './counter'
+
+register('app-counter', counter)
+start()
+```
+
+```html
+<app-counter>
+  <button data-subtract>-</button>
+  <span html-inner="counter">0</span>
+  <button data-add>+</button>
+</app-counter>
+```
+
+```ts
+export default function appCounter({ main, on, state }) {
+  main(() => {
+    on('click', '[data-add]', () => state.set(s => { s.counter += 1 }))
+    on('click', '[data-subtract]', () => state.set(s => { s.counter -= 1 }))
+  })
+}
+
+export const model = { counter: 0 }
+```
+

package/ai/overview.md

@@ -0,0 +1,45 @@
+# Jails Overview
+
+Jails is a client-side JavaScript framework for attaching behavior to existing HTML custom elements. A Jails component is an ES module registered against a custom element name. When `start()` runs, Jails scans a target DOM tree, finds registered component elements, creates one component instance per element, initializes local state from the component `model` and optional `html-model`, evaluates template directives, and binds component-scoped helpers.
+
+Jails is optimized for progressively enhanced HTML. The default assumption is that the server, static generator, CMS, or application template engine owns first paint. Jails then enhances specific islands of interactivity instead of owning the whole document as a single application tree.
+
+## Philosophy
+
+- HTML is the primary data source for UI structure.
+- JavaScript modules provide behavior, state transitions, event handling, and optional embedded templates.
+- Components are custom elements enhanced by Jails, not necessarily shadow-DOM web components.
+- Rendering is directive-driven: the DOM declares which state values affect which nodes or attributes.
+- Event handling is delegated from the component root, so child DOM can be replaced without rebinding every child listener.
+- Static regions can be excluded from diffing with `html-static` when the browser or a third-party library must own that subtree.
+
+## Rendering Philosophy
+
+Jails updates existing DOM through directives and mustache expressions. The template system evaluates expressions against the component view scope. State changes through `state.set()` schedule DOM updates and return a Promise that resolves after the update cycle.
+
+The rendering boundary is the component element. Parent state updates can flow into child component props unless a child protects specific properties with `state.protected()`. `html-static` creates a sub-boundary inside a component: Jails does not diff that node or its children after it is marked static.
+
+## Performance Philosophy
+
+- Render only islands that need client-side behavior.
+- Keep first paint server-rendered or static when possible.
+- Use event delegation to reduce listener count.
+- Use `html-static` to avoid diffing immutable or externally mutated regions.
+- Keep directive expressions cheap because they execute during template updates.
+- Avoid deeply nested reactive loops because `html-for` creates repeated DOM work.
+
+## Core Primitives
+
+- `register(name, module, dependencies?)`: associate a custom element name with a component module.
+- `start(target?)`: scan and bootstrap registered elements in `target` or `document.body`.
+- Component controller: default export function receiving helpers.
+- `model`: required exported object or function that initializes local state.
+- `view`: optional exported function that derives render-only values from state.
+- `template`: optional exported function that returns embedded HTML.
+- Directives: `html-if`, `html-for`, `html-inner`, `html-model`, `html-*`, `html-static`, and native `<template>`.
+- Helpers: `main`, `elm`, `dataset`, `query`, `dependencies`, `innerHTML`, `state`, `on`, `off`, `emit`, `trigger`, `publish`, `subscribe`, `effect`, `unmount`.
+
+## Mental Model
+
+Treat each Jails component as a DOM island with local state and delegated events. The HTML declares render dependencies; the controller declares lifecycle and behavior. State changes drive directive updates. DOM nodes inside `html-static` are owned by the browser or external libraries. Parent-child communication uses prop updates, DOM events, or global pub/sub depending on distance and direction.
+

package/ai/patterns.md

@@ -0,0 +1,182 @@
+# Architectural Patterns
+
+## Progressive Island Component
+
+Intent: make server-rendered HTML interactive without turning the page into a single JavaScript-owned application.
+
+Structure:
+
+```html
+<hello-world>
+  <h1>Hello World!</h1>
+  <button class="add">+</button>
+  <span html-inner="counter">0</span>
+</hello-world>
+```
+
+```ts
+register('hello-world', helloWorld)
+start()
+```
+
+Responsibilities: HTML owns first paint; controller owns behavior; state owns values that directives render.
+
+Why it exists: Jails targets SSR/SSG/CMS pages where most content is static and only selected areas need interactivity.
+
+Performance implications: less JavaScript and fewer hydration boundaries than full-page SPA rendering.
+
+Scalability implications: teams can add isolated components without centralizing the whole page in one app shell.
+
+## Page-Scoped Store
+
+Intent: keep mutable UI state local to the component or page island that renders it.
+
+Structure:
+
+```ts
+export const model = {
+  items: [],
+  loading: false,
+  error: null
+}
+```
+
+Responsibilities: the page component fetches data, owns loading/error states, and passes relevant props to child components through parent updates.
+
+Why it exists: Jails docs emphasize local component state and parent-to-child prop updates, not a global store.
+
+Performance implications: local updates constrain render work to the component boundary.
+
+Scalability implications: state ownership remains visible. Cross-tree communication uses pub/sub only when DOM hierarchy cannot carry the message.
+
+## Services Through Dependencies
+
+Intent: make generic components reusable across applications with app-specific services injected at registration time.
+
+Structure:
+
+```ts
+register('form-validation', formValidation, { validations, masks })
+```
+
+Responsibilities: shared service modules perform validation, HTTP, masks, or business logic; component coordinates UI events and state.
+
+Why it exists: prevents generic components from bundling every application-specific rule.
+
+Performance implications: avoids importing unused validation/business code into generic libraries.
+
+Scalability implications: supports library distribution and app-specific behavior without forking components.
+
+## Delegated Event Handling
+
+Intent: bind a small number of listeners at the component root.
+
+Structure:
+
+```ts
+main(() => {
+  on('click', '[data-remove]', remove)
+})
+```
+
+Responsibilities: use stable selectors, read `event.delegateTarget`, and keep handlers independent of child node identity.
+
+Why it exists: child nodes may be replaced by directive updates. Delegation keeps handlers active.
+
+Performance implications: avoids one listener per repeated item and reduces rebinding after render.
+
+Scalability implications: list and conditional rendering remain predictable.
+
+## Template Composition
+
+Intent: package fully featured widgets while still allowing consumer content.
+
+Structure:
+
+```ts
+export const template = ({ children }) => html`
+  <section>
+    ${children}
+    <p>Counter: {{ counter }}</p>
+  </section>
+`
+```
+
+Responsibilities: templates define embedded markup; controllers define behavior; `children` preserves caller-provided content.
+
+Why it exists: Jails supports both logic-only components and self-contained web components.
+
+Performance implications: embedded templates add client-side HTML creation, so prefer server-rendered HTML for generic page content.
+
+Scalability implications: useful for widgets such as chat, consent bars, counters, and mini-apps.
+
+## Static Third-Party Integration
+
+Intent: let external libraries mutate DOM without Jails overwriting their changes.
+
+Structure:
+
+```html
+<div class="swiper" html-static>...</div>
+```
+
+Responsibilities: external library owns the static subtree; Jails owns surrounding state and events.
+
+Why it exists: DOM-diffing renderers conflict with libraries that imperatively mutate DOM.
+
+Performance implications: Jails skips diff work for that subtree.
+
+Scalability implications: each integration has an explicit ownership boundary.
+
+## Fetch Flow
+
+Intent: perform asynchronous I/O in controller logic and reflect status through state.
+
+Structure:
+
+```ts
+export default function appList({ main, state }) {
+  main(() => {
+    load()
+  })
+
+  const load = () => {
+    state.set({ loading: true, error: null })
+    fetch('/api/items')
+      .then(r => r.json())
+      .then(items => state.set({ items, loading: false }))
+      .catch(error => state.set({ error, loading: false }))
+  }
+}
+```
+
+Responsibilities: services/fetch handle I/O; state holds loading/error/data; template renders states with directives.
+
+Why it exists: keeps templates deterministic and side-effect-free.
+
+Performance implications: avoid re-fetching in render paths.
+
+Scalability implications: cleanly separates data acquisition from DOM projection.
+
+## Parent-Child Communication
+
+Intent: communicate down through props/state updates and up through DOM events.
+
+Structure:
+
+```ts
+// child
+emit('time-elapsed', '10 seconds elapsed')
+
+// parent
+on('time-elapsed', 'child-component', handleElapsed)
+```
+
+Responsibilities: parent owns data it passes down; child emits user/domain events upward; siblings use pub/sub when no shared ancestor is practical.
+
+Why it exists: follows DOM event semantics and keeps component coupling low.
+
+Performance implications: bubbling events avoid global subscriptions for local communication.
+
+Scalability implications: choose the narrowest communication channel that reaches the recipient.
+