jails-js 6.9.8 → 6.9.9

package/ai/recipes.md

@@ -0,0 +1,393 @@
+# Recipes
+
+## Counter
+
+Explanation: minimal local state update with delegated events and `html-inner`.
+
+```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]', add)
+    on('click', '[data-subtract]', subtract)
+  })
+
+  const add = () => {
+    state.set(s => {
+      s.counter += 1
+    })
+  }
+
+  const subtract = () => {
+    state.set(s => {
+      s.counter -= 1
+    })
+  }
+}
+
+export const model = {
+  counter: 0
+}
+```
+
+Rendering explanation: `html-inner="counter"` replaces fallback `0` after mount and updates after each `state.set()`.
+
+Performance notes: one listener per event type at the component root; no per-button rebinding.
+
+Common mistakes: omitting `state` from controller helpers; reading DOM text as source of truth instead of state.
+
+## Loading and Error States
+
+```html
+<app-users>
+  <p html-if="loading">Loading</p>
+  <p html-if="error">{{ error.message }}</p>
+  <ul html-if="!loading && !error">
+    <li html-for="user in users">{{ user.name }}</li>
+  </ul>
+</app-users>
+```
+
+```ts
+export default function appUsers({ main, state, dependencies }) {
+  const { http } = dependencies
+
+  main(() => {
+    load()
+  })
+
+  const load = () => {
+    state.set({ loading: true, error: null })
+    http.get('/users')
+      .then(users => state.set({ users, loading: false }))
+      .catch(error => state.set({ error, loading: false }))
+  }
+}
+
+export const model = {
+  users: [],
+  loading: false,
+  error: null
+}
+```
+
+Rendering explanation: mutually exclusive `html-if` regions create/remove the visible branch.
+
+Performance notes: fetch never runs from the template. The loop only renders when not loading and without error.
+
+Common mistakes: storing formatted error strings only; keep the original error if handlers need it.
+
+## Modal
+
+```html
+<app-modal>
+  <button data-open>Open</button>
+  <section html-if="open" role="dialog" aria-modal="true">
+    <h2>{{ title }}</h2>
+    <button data-close>Close</button>
+  </section>
+</app-modal>
+```
+
+```ts
+export default function appModal({ main, on, state }) {
+  main(() => {
+    on('click', '[data-open]', () => state.set({ open: true }))
+    on('click', '[data-close]', () => state.set({ open: false }))
+  })
+}
+
+export const model = {
+  open: false,
+  title: 'Dialog'
+}
+```
+
+Rendering explanation: modal DOM is created only when `open` is truthy and removed when false.
+
+Performance notes: fine for small dialogs. For heavy dialog content that should preserve input state, use CSS visibility or place form controls under `html-static` as appropriate.
+
+Common mistakes: expecting internal form values to persist across `html-if` removal.
+
+## Tabs
+
+```html
+<app-tabs>
+  <nav>
+    <button data-tab="profile" html-class="activeTab === 'profile' ? 'active' : ''">Profile</button>
+    <button data-tab="billing" html-class="activeTab === 'billing' ? 'active' : ''">Billing</button>
+  </nav>
+  <section html-if="activeTab === 'profile'">Profile content</section>
+  <section html-if="activeTab === 'billing'">Billing content</section>
+</app-tabs>
+```
+
+```ts
+export default function appTabs({ main, on, state }) {
+  main(() => {
+    on('click', '[data-tab]', select)
+  })
+
+  const select = e => {
+    state.set({ activeTab: e.delegateTarget.dataset.tab })
+  }
+}
+
+export const model = {
+  activeTab: 'profile'
+}
+```
+
+Rendering explanation: button classes and panel branches derive from one state property.
+
+Performance notes: no listener per tab panel. Avoid rendering large inactive panels repeatedly.
+
+Common mistakes: reading `event.target.dataset.tab`; nested elements can make `event.target` wrong. Use `delegateTarget`.
+
+## Accordion
+
+```html
+<app-accordion>
+  <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>
+</app-accordion>
+```
+
+```ts
+export default function appAccordion({ main, on, state }) {
+  main(() => {
+    on('click', '[data-toggle]', toggle)
+  })
+
+  const toggle = e => {
+    const index = Number(e.delegateTarget.dataset.index)
+    state.set(s => {
+      s.openIndex = s.openIndex === index ? -1 : index
+    })
+  }
+}
+
+export const model = {
+  openIndex: -1,
+  items: []
+}
+```
+
+Rendering explanation: each repeated item receives `$index`; only matching content branch renders.
+
+Performance notes: for long accordions, do not put heavy widgets inside every body unless guarded or static.
+
+Common mistakes: not converting dataset strings to numbers.
+
+## Fetch API With Service Dependency
+
+```ts
+// main.ts
+register('app-posts', appPosts, { http })
+```
+
+```ts
+export default function appPosts({ main, state, dependencies }) {
+  const { http } = dependencies
+
+  main(() => {
+    load()
+  })
+
+  const load = async () => {
+    state.set({ loading: true })
+    const posts = await http.get('/posts')
+    state.set({ posts, loading: false })
+  }
+}
+
+export const model = {
+  posts: [],
+  loading: false
+}
+```
+
+Rendering explanation: state changes drive any `html-if` and `html-for` bound to `loading` and `posts`.
+
+Performance notes: dependency injection keeps generic components free of unused service code.
+
+Common mistakes: importing app services inside reusable library components.
+
+## Optimistic Updates
+
+```ts
+export default function appTodos({ main, on, state, dependencies }) {
+  const { todosApi } = dependencies
+
+  main(() => {
+    on('click', '[data-toggle]', toggle)
+  })
+
+  const toggle = async e => {
+    const id = e.delegateTarget.dataset.id
+    const previous = state.get().todos
+    const todos = previous.map(todo =>
+      todo.id === id ? { ...todo, done: !todo.done } : todo
+    )
+    await state.set({ todos })
+
+    try {
+      await todosApi.toggle(id)
+    } catch (error) {
+      state.set({ todos: previous, error })
+    }
+  }
+}
+```
+
+Rendering explanation: UI updates before the API resolves; rollback restores previous state on failure.
+
+Performance notes: clone changed collections instead of mutating external references.
+
+Common mistakes: losing the previous state snapshot before the optimistic write.
+
+## Nested Templates
+
+```html
+<app-page>
+  <h1>Server-rendered heading</h1>
+  <template>
+    <section html-if="user">
+      Welcome, {{ user.name }}
+    </section>
+  </template>
+</app-page>
+```
+
+Rendering explanation: native `<template>` prevents unresolved mustache markers from flashing before data exists.
+
+Performance notes: use this for correctness of first paint; it is not a substitute for limiting render work.
+
+Common mistakes: hiding content that should be visible at first paint.
+
+## Debounced Input
+
+```html
+<app-search>
+  <input type="search" html-static>
+  <p html-if="loading">Searching</p>
+  <ul>
+    <li html-for="item in results">{{ item.label }}</li>
+  </ul>
+</app-search>
+```
+
+```ts
+export default function appSearch({ main, on, state, dependencies }) {
+  const { search } = dependencies
+  let timer
+
+  main(() => {
+    on('input', 'input[type=search]', schedule)
+  })
+
+  const schedule = e => {
+    const query = e.delegateTarget.value
+    clearTimeout(timer)
+    timer = setTimeout(() => run(query), 250)
+  }
+
+  const run = async query => {
+    state.set({ loading: true })
+    const results = await search(query)
+    state.set({ results, loading: false })
+  }
+}
+
+export const model = {
+  results: [],
+  loading: false
+}
+```
+
+Rendering explanation: input value is browser-owned through `html-static`; search results are Jails-owned state.
+
+Performance notes: debounce avoids one network request and render per keystroke.
+
+Common mistakes: binding input value to state when no other render logic needs it.
+
+## Intersection Observer Lazy Rendering
+
+```ts
+export default function lazyPanel({ main, elm, state, unmount }) {
+  let observer
+
+  main(() => {
+    observer = new IntersectionObserver(entries => {
+      if (entries.some(entry => entry.isIntersecting)) {
+        state.set({ visible: true })
+        observer.disconnect()
+      }
+    })
+    observer.observe(elm)
+  })
+
+  unmount(() => {
+    if (observer) observer.disconnect()
+  })
+}
+
+export const model = {
+  visible: false
+}
+```
+
+```html
+<lazy-panel>
+  <section html-if="visible">Expensive content</section>
+</lazy-panel>
+```
+
+Rendering explanation: expensive content is not created until the component enters the viewport.
+
+Performance notes: cleanup prevents observers from retaining detached elements.
+
+Common mistakes: forgetting `unmount()`.
+
+## Virtual List Boundary
+
+```html
+<app-virtual-list>
+  <div class="virtual-list" html-static></div>
+  <p>Total: {{ total }}</p>
+</app-virtual-list>
+```
+
+```ts
+export default function appVirtualList({ main, elm, state, dependencies }) {
+  const { createVirtualList } = dependencies
+  const target = elm.querySelector('.virtual-list')
+  let list
+
+  main(() => {
+    list = createVirtualList(target, {
+      onCountChange: total => state.set({ total })
+    })
+  })
+}
+
+export const model = {
+  total: 0
+}
+```
+
+Rendering explanation: the virtual list library owns its DOM; Jails renders surrounding counters/state.
+
+Performance notes: `html-static` prevents Jails diffing a large, imperatively managed list.
+
+Common mistakes: putting `html-for` inside a virtualized area managed by another library.
+

package/package.json

@@ -1,24 +1,39 @@
 {
 	"name": "jails-js",
-	"version": "6.9.8",
+	"version": "6.9.9",
 	"description": "Jails - Elegant and Minimalistic Javascript Application Library",
 	"module": "./dist/index.js",
 	"main": "./dist/jails.js",
+	"types": "./types.d.ts",
 	"exports": {
+
 		"./html": {
 			"types": "./types.d.ts",
 			"import": "./html.js",
 			"require": "./html.js"
 		},
+
 		".": {
 			"types": "./types.d.ts",
 			"import": "./dist/index.js",
 			"require": "./dist/jails.js"
 		},
+
 		"./internal": {
 			"types": "./types.d.ts",
 			"default": "./types.d.ts"
-		}
+		},
+
+		"./ai/*": "./ai-docs/*",
+		"./schemas/*": "./ai-docs/schemas/*",
+		"./canonical/*": "./ai-docs/canonical/*"
+	},
+
+	"ai": {
+		"entry": "./ai-docs/LLM.md",
+		"schemas": "./ai-docs/schemas",
+		"examples": "./ai-docs/canonical",
+		"training": "./ai-docs/training/training.jsonl"
 	},
 	"scripts": {
 		"dev": "vite build --watch",
@@ -27,28 +42,35 @@
 		"publish-beta": "yarn build && npm version prerelease --preid=beta && npm publish --tag beta",
 		"test": "echo \"Error: no test specified\" && exit 1"
 	},
+
 	"repository": {
 		"type": "git",
 		"url": "git+https://github.com/jails-org/Jails.git"
 	},
+
 	"keywords": [
 		"Jails",
 		"Javascript",
 		"Component",
 		"Micro-Library"
 	],
+
 	"author": "javiani",
 	"license": "MIT",
+
 	"bugs": {
 		"url": "https://github.com/jails-org/Jails/issues"
 	},
+
 	"homepage": "https://github.com/jails-org/Jails",
+
 	"devDependencies": {
 		"@types/node": "^22.10.10",
 		"terser": "^5.37.0",
 		"typescript": "^5.7.3",
 		"vite": "^6.0.11"
 	},
+
 	"dependencies": {
 		"idiomorph": "^0.7.4"
 	}

package/readme.md

@@ -1,13 +1,16 @@
-<p align="center">
-  <img width="200" src="https://github.com/user-attachments/assets/8b4dbfb9-f05e-4b83-8d42-8847038a97e2" alt="Jails" />
-</p>
 
-<h1 align="center">Jails</h1>
 
-<h3 align="center">An Elegant and Minimalistic<br /> Web Components Micro-Framework</h3>
+<p align="center" height="100">
+  <img width="250"  alt="Jails - A minimalistic Micro Framework" src="https://github.com/user-attachments/assets/5e2eee1a-5f8f-4eed-abba-7422a5258245" />
+  
+</p>
+
+<h1 align="center">An Elegant and Minimalistic<br /> Micro-Framework</h3>
 
 <div align="center">
-  <table align="center" border="0">
+  <br />
+    <br />
+  <table width="100%" align="center" border="0">
     <tr><td align="center">🏝 Built for <br/><a href="https://www.patterns.dev/posts/islands-architecture/" target="_blank">Island Architecture</a></td</tr>
     <td align="center">ƛ Inspired by <br/><a href="https://guide.elm-lang.org/architecture/" target="_blank">Elm Architecture</a></td>
     <td align="center">🔗 Ready for <br/><a href="https://htmx.org/essays/hypermedia-driven-applications" target="_blank">hypermedia applications</a></td></tr>
@@ -28,9 +31,19 @@
 The JavaScript ecosystem, including browsers and tools, has undergone significant evolution over the years. However, it's evident that many of the complexities introduced by frameworks today may not be essential for the majority of web applications. The prevailing trend in modern app development seems to prioritize expertise in frameworks over mastery of the language itself, often leading to a sense of being confined within the framework ecosystem.
 
 Jails was designed to be:
-- **Decoupled** - Backend-agnostic, our solution seamlessly integrates with any backend framework or programming language. It refrains from importing styles and ensures a clean demarcation by avoiding mixing HTML within the codebase.
-- **Lightweight** - Lightweight, weighing in at just around 5kb when gzipped. It enhances your application's performance by progressively lightening the load, separating HTML from your JavaScript code. This practice results in smaller bundles and a more streamlined application.
-- **Interoperable** - It seamlessly integrates and functions alongside any other vanilla UI or behavioral libraries. You no longer need to wait for a specific Jails Chart.js library to be available; simply integrate it into your application hassle-free.
+
+<table width="100%" align="center" border="0">
+    <tr>
+      <th>🧩 Decoupled</th>
+      <th>⚡️ Lightweight</th>
+      <th>📦 Interoperable</th>
+    </tr>
+    <tr>
+      <td align="center">Backend-agnostic, our solution seamlessly integrates with any backend framework or back-end programming language.</td>
+      <td align="center">Lightweight, just around 5kb when gzipped. It enhances your application's performance by progressively, separating HTML from your JavaScript code. </td>
+      <td align="center">It seamlessly integrates and functions alongside any other vanilla UI or behavioral libraries. </td>
+    </tr>    
+</table>
 
 <br clear="all" />
 <br />

package/tsconfig.json

@@ -2,7 +2,6 @@
   "compilerOptions": {
 		"declaration": true,
     "emitDeclarationOnly": true,
-    "outDir": "dist",
     /* Visit https://aka.ms/tsconfig to read more about this file */
 
     /* Projects */

package/types.d.ts

@@ -9,7 +9,7 @@ export declare const templateConfig: (options: any) => void;
 export declare const register: (name: string, module: any, dependencies?: any) => void
 export declare const start: (target?: HTMLElement) => void;
 export declare const subscribe:( subject: string, callback: (data:any) => void ) => Function
-export declare const publish: ( subject: string, data :any ) => void
+export declare const publish: ( subject: string, data ?:any ) => void
 
 export type Component = {
 
@@ -24,11 +24,11 @@ export type Component = {
 		getRaw() : any
 	}
 
-	effect( callback: ( state: any ) => Promise<any> | void )
+	effect( callback: ( state: any ) => Promise<any> | void ): void
 
 	main( mainArgs: ( t: Component ) => void ): void
 
-	publish( name: string, value: any ) : void
+	publish( name: string, value?: any ) : void
 
 	subscribe( name: string, value: Function ) : Function