jails-js 6.9.7 → 6.9.9

package/ai/anti-patterns.md

@@ -0,0 +1,102 @@
+# Anti-patterns
+
+## Side effects in template expressions
+
+Why harmful: directive and mustache expressions are render logic. Side effects can run repeatedly and unpredictably during updates.
+
+Symptoms: duplicate requests, counters changing during render, inconsistent DOM.
+
+Performance impact: unnecessary I/O or CPU work on every update.
+
+Recommended alternative: move side effects into controller functions called from `main()` or event handlers.
+
+## Deeply nested `html-for`
+
+Why harmful: repeated loops multiply DOM creation and update work.
+
+Symptoms: slow state updates, input lag, large DOM trees.
+
+Performance impact: O(n*m) or worse render work depending on nesting and directives.
+
+Recommended alternative: flatten data, paginate, virtualize, or make heavy regions static/external.
+
+## Mutating Jails-managed DOM with third-party libraries
+
+Why harmful: Jails may diff the same subtree and overwrite external mutations.
+
+Symptoms: widgets reset after state updates, duplicated nodes, lost event state.
+
+Performance impact: unnecessary reconciliation and library reinitialization.
+
+Recommended alternative: put the external library subtree under `html-static`.
+
+## Assuming `state.set()` updates DOM synchronously
+
+Why harmful: docs expose a Promise specifically for after-update work.
+
+Symptoms: focus/measure code reads old nodes or missing new nodes.
+
+Performance impact: repeated layout work or failed retries.
+
+Recommended alternative: use `state.set(...).then(...)`.
+
+## Using `event.target` in delegated handlers
+
+Why harmful: the real event target may be a child inside the selected element.
+
+Symptoms: missing `dataset`, wrong element updates, brittle DOM traversal.
+
+Performance impact: extra defensive queries.
+
+Recommended alternative: use `event.delegateTarget`.
+
+## Global pub/sub for local parent-child communication
+
+Why harmful: global channels hide ownership and make event flow harder to trace.
+
+Symptoms: unrelated components reacting to events, forgotten unsubscriptions.
+
+Performance impact: unnecessary global fan-out.
+
+Recommended alternative: use `emit()` and delegated `on()` for DOM-reachable communication.
+
+## Storing browser-owned input values in state unnecessarily
+
+Why harmful: every keystroke can trigger state updates and DOM reconciliation.
+
+Symptoms: cursor jumps, overwritten user input, excessive renders.
+
+Performance impact: high-frequency input renders.
+
+Recommended alternative: use normal inputs or `html-static` and read values on submit/input handlers.
+
+## Giant embedded `template` functions
+
+Why harmful: large string templates mix structure, rendering rules, and business assumptions.
+
+Symptoms: difficult review, duplicated markup, hard-to-test components.
+
+Performance impact: more client-side HTML generation where server-rendered HTML may be cheaper.
+
+Recommended alternative: use logic-featured components with external HTML, or split template fragments.
+
+## Undeclared state shape
+
+Why harmful: missing model keys make templates and controllers less inferable.
+
+Symptoms: `undefined` render output, inconsistent initial branches.
+
+Performance impact: extra defensive conditions and update churn.
+
+Recommended alternative: define all local state keys in `model`.
+
+## Expensive derived values stored as persistent state
+
+Why harmful: render-only values clutter state and can become stale.
+
+Symptoms: duplicated fields such as `counter` and `counterLabel` falling out of sync.
+
+Performance impact: extra state writes.
+
+Recommended alternative: use pure `view(state)` for render-only derivations.
+

package/ai/api.md

@@ -0,0 +1,388 @@
+# Public API
+
+## `register(name, module, dependencies?)`
+
+Signature:
+
+```ts
+register(name: string, module: Module, dependencies?: object): void
+```
+
+Parameters:
+
+- `name`: custom element tag name, for example `'app-counter'`.
+- `module`: component module namespace, usually `import * as appCounter from './components/app-counter'`.
+- `dependencies`: optional object injected into component helpers as `dependencies`.
+
+Return value: not documented.
+
+Side effects: stores the association between the custom element name and component module.
+
+Lifecycle implications: must run before `start()` for components that should bootstrap during that scan.
+
+Example:
+
+```ts
+import { register, start } from 'jails-js'
+import http from './shared/http'
+import * as myComponent from './components/my-component'
+
+register('my-component', myComponent, { http })
+start()
+```
+
+Related APIs: `start`, `dependencies`.
+
+## `start(target?)`
+
+Signature:
+
+```ts
+start(target?: HTMLElement): void
+```
+
+Parameters:
+
+- `target`: optional root element to scan. Defaults to `document.body`.
+
+Return value: not documented.
+
+Side effects: scans for registered custom elements and starts their bootstrap process.
+
+Lifecycle implications: safe to call multiple times, but docs advise avoiding unnecessary calls.
+
+Example:
+
+```ts
+register('hello-world', helloWorld)
+start()
+```
+
+Related APIs: `register`.
+
+## `templateConfig(options)`
+
+Signature:
+
+```ts
+jails.templateConfig({ tags: [open: string, close: string] }): void
+```
+
+Parameters:
+
+- `tags`: two-string array for mustache delimiters.
+
+Return value: not documented.
+
+Side effects: changes global template delimiters from default `{{` and `}}`.
+
+Lifecycle implications: call before templates are processed.
+
+Example:
+
+```ts
+jails.templateConfig({ tags: ['@{', '}'] })
+```
+
+Related APIs: mustache interpolation.
+
+## `publish(name, data?)`
+
+Signature:
+
+```ts
+publish(name: string, data?: any): void
+```
+
+Parameters:
+
+- `name`: global event name.
+- `data`: optional payload.
+
+Side effects: notifies subscribers globally.
+
+Lifecycle implications: useful for components in different DOM trees.
+
+Example:
+
+```ts
+publish('my-component:fetched', data)
+```
+
+Related APIs: `subscribe`, component helper `publish`.
+
+## `subscribe(name, fn)`
+
+Signature:
+
+```ts
+subscribe(name: string, fn: Function): Function
+```
+
+Parameters:
+
+- `name`: global event name.
+- `fn`: callback receiving published data.
+
+Return value: unsubscribe function.
+
+Side effects: registers a global subscription.
+
+Lifecycle implications: call returned function in `unmount()` when subscription lifetime is tied to a component.
+
+Example:
+
+```ts
+const unsubscribe = subscribe('my-component:fetched', data => {
+  console.log(data)
+})
+```
+
+Related APIs: `publish`, `unmount`.
+
+## `html`
+
+Signature:
+
+```ts
+html(strings: TemplateStringsArray, ...values: any[]): string
+```
+
+Parameters: template string parts and interpolated values.
+
+Return value: HTML string for template composition.
+
+Side effects: none documented.
+
+Example:
+
+```ts
+import { html } from 'jails-js/html'
+
+export const template = ({ children }) => html`
+  <section>
+    ${children}
+    <p>{{ counter }}</p>
+  </section>
+`
+```
+
+Related APIs: `template`, `attributes`.
+
+## `attributes`
+
+Signature:
+
+```ts
+attributes(values: Record<string, any>): string
+```
+
+Parameters:
+
+- object of attributes to serialize into template HTML.
+
+Return value: attribute string.
+
+Example:
+
+```ts
+import { attributes } from 'jails-js/html'
+
+html`<button ${attributes({ id: 'my-button-id' })}>+</button>`
+```
+
+Related APIs: `html`, `template`.
+
+# Component Module Exports
+
+## Default controller
+
+Signature:
+
+```ts
+export default function componentName(helpers: Component): void | Promise<void>
+```
+
+Async controllers are supported. Code after `await` does not run until the awaited Promise resolves.
+
+Side effects: registers lifecycle callbacks, event handlers, external widgets, subscriptions, and state transitions.
+
+## `model`
+
+Signature:
+
+```ts
+export const model: Model = {}
+export const model = ({ elm, initialState, dependencies }): Model => ({})
+```
+
+Return value: initial local state object.
+
+Side effects: should be none.
+
+## `view`
+
+Signature:
+
+```ts
+export const view: View = (state: any) => any
+```
+
+Return value: render scope object.
+
+Side effects: should be none.
+
+## `template`
+
+Signature:
+
+```ts
+export const template: Template = ({ elm, children }) => string
+```
+
+Return value: HTML string inserted/rendered for the component.
+
+# Component Helpers
+
+## `main(fn)`
+
+```ts
+main(fn: Function): void
+```
+
+Registers the entry-point callback for code that should run after the component is mounted.
+
+## `elm`
+
+```ts
+elm: HTMLElement
+```
+
+Reference to the component custom element.
+
+## `dataset(key)` / `dataset(target, key)`
+
+```ts
+dataset(key: string): any
+dataset(target: HTMLElement, key: string): any
+```
+
+Parses a `data-*` value from the component or target child.
+
+## `query(cssSelector)`
+
+```ts
+query(cssSelector: string): Array<Promise<HTMLElement>>
+```
+
+Finds child Jails components that may not be ready yet. Each result resolves when the component is available with public methods.
+
+## `dependencies`
+
+```ts
+dependencies: Record<string, any>
+```
+
+Dependencies object supplied by `register()`.
+
+## `innerHTML(html)` / `innerHTML(target, html)`
+
+```ts
+innerHTML(html: string): void
+innerHTML(target: HTMLElement, html: string): void
+```
+
+Updates a target with an HTML string using DOM diffing.
+
+## `state.set(newprops)` / `state.set(mutator)`
+
+```ts
+state.set(newprops: object): Promise<object>
+state.set((currentState: object) => void): Promise<object>
+```
+
+Updates local state. Object form merges specified properties. Function form receives current state for mutation. Promise resolves after DOM updates and can be used as next-tick behavior.
+
+## `state.get()`
+
+```ts
+state.get(): object
+```
+
+Returns the current state object.
+
+## `state.protected(props)`
+
+```ts
+state.protected(props: Array<string>): void
+```
+
+Prevents listed child component props from being overwritten by parent updates.
+
+## `on(event, selector?, callback)`
+
+```ts
+on(event: string, cssSelector: string, callback: Function): void
+on(event: string, callback: Function): void
+on(attributePattern: string, cssSelector: string, callback: Function): void
+```
+
+Registers component-scoped delegated events. Attribute-change syntax uses patterns such as `on('[src]', 'iframe', callback)`. Delegated event objects include `delegateTarget`.
+
+## `off(event, callback)`
+
+```ts
+off(event: string, callback: Function): void
+```
+
+Removes an event listener.
+
+## `emit(event, data?)`
+
+```ts
+emit(event: string, data?: any): void
+```
+
+Emits a bubbling DOM CustomEvent from the component.
+
+## `trigger(event, data?)` / `trigger(event, selector, data?)`
+
+```ts
+trigger(event: string, data?: object): void
+trigger(event: string, selector: string, data?: object): void
+```
+
+Triggers an event or custom event from the component or a child matched by selector.
+
+## `publish(event, data?)`
+
+```ts
+publish(event: string, data?: any): void
+```
+
+Publishes a global pub/sub event.
+
+## `subscribe(event, callback)`
+
+```ts
+subscribe(event: string, callback: Function): Function
+```
+
+Subscribes globally and returns an unsubscribe function.
+
+## `effect(callback)`
+
+```ts
+effect(callback: Function): void | Promise<any>
+```
+
+Registers a sync or async function that receives parent props when parent updates occur. The callback may override or compose props.
+
+## `unmount(callback)`
+
+```ts
+unmount(callback: Function): void
+```
+
+Registers cleanup to run when the component element is detached from DOM.
+

package/ai/architecture.md

@@ -0,0 +1,79 @@
+# Architecture
+
+## Runtime Shape
+
+Jails is a singleton API. Applications register component modules globally, then call `start()` to scan a DOM subtree. The framework is intended to be used once per page, not as multiple framework instances.
+
+## Rendering Pipeline
+
+1. Application imports component modules.
+2. Application calls `register(name, module, dependencies?)`.
+3. Application calls `start(target?)`.
+4. Jails scans `target` or `document.body` for registered custom elements.
+5. For each element, Jails builds component state from `model` and `html-model`.
+6. If a `template` export exists, Jails can generate embedded HTML using `{ elm, children }`.
+7. Jails evaluates template directives and mustache expressions against the render scope.
+8. Controller `main()` callbacks run after mount.
+9. Later `state.set()` calls update state and trigger template updates.
+
+## Update Flow
+
+State updates go through `state.set()`. Object form changes only specified properties. Function form receives the current state and can mutate it. The method returns a Promise that resolves after DOM updates; use that Promise for next-tick work such as measuring updated DOM or starting animations.
+
+`view(state)` runs as a render-scope transform. Values returned from `view` are intended for HTML only and do not become persistent state unless stored explicitly through `state.set()`.
+
+Parent state changes can update child component props by default. A child can call `state.protected(['propName'])` to prevent selected props from being overwritten by parent updates.
+
+## DOM Ownership
+
+The component element is the main rendering boundary. Jails owns directive-managed DOM inside that boundary. The browser owns normal form behavior unless the component state overwrites it. Third-party libraries may own subtrees marked with `html-static`.
+
+Ownership rules:
+
+- Jails-owned: nodes/attributes/text controlled by directives and mustache expressions.
+- Browser-owned: native input value persistence when inputs are not re-rendered, especially with `html-static`.
+- External-library-owned: widgets initialized by controller code inside `html-static` subtrees.
+- Parent-owned: props passed down to children unless protected by child state.
+
+## Event System
+
+`on()` registers delegated listeners at the component root. The selector argument identifies child elements. The event object is augmented with `delegateTarget`, which is the element that matched the selector. This is safer than `event.target`, which may be a nested element.
+
+DOM events and custom events bubble. `emit()` sends CustomEvents upward to parents and siblings reachable by bubbling. `trigger()` programmatically dispatches events from the component or a selected child. `publish()` and `subscribe()` provide global pub/sub for components in different DOM trees.
+
+Attribute changes can be observed with `on('[src]', 'iframe', callback)` and similar patterns. The callback receives `{ target, value, attribute }`.
+
+## Template System
+
+Directives and mustache expressions evaluate JavaScript expressions. Default interpolation delimiters are `{{` and `}}`; `templateConfig()` can change them when a server renderer uses the same delimiters.
+
+`html-if` controls conditional node existence. `html-for` repeats nodes for arrays or objects and provides `$index` and `$key`. `html-inner` writes expression results into an element. `html-*` maps expression values to real attributes. `html-static` skips diffing for a node and its children. Native `<template>` hides unresolved dynamic fragments from first paint.
+
+## Rendering Boundaries
+
+Primary boundary: each registered custom element instance.
+
+Nested boundary: child components receive parent props but have their own controller, state, lifecycle, and event root.
+
+Static boundary: `html-static` excludes a subtree from Jails updates.
+
+Conditional boundary: `html-if` may remove an entire subtree, causing child component detach and cleanup.
+
+Loop boundary: `html-for` creates repeated instances of the directive element. The docs do not specify keyed reconciliation; assume position-based behavior.
+
+## Store Interactions
+
+Jails documents component-local state rather than a centralized store. Use local state for UI ownership. Use parent props for downward data. Use DOM events for upward communication. Use pub/sub only for components in separate trees.
+
+## Service Interactions
+
+Services can be imported directly or injected through `register()` dependencies. Injection is preferred for reusable components whose behavior depends on application-specific rules, for example form validations and masks.
+
+## SSR and SSG Implications
+
+Jails is designed to enhance already rendered HTML, so it fits SSR and SSG. Server-rendered HTML appears before JavaScript loads. Directives then activate after `start()`. For shared SSR templates, export template functions separately and render them through the server framework. For fully featured components, export a `template` from the component module.
+
+## Hydration Behavior
+
+The docs describe progressive enhancement rather than React-style full hydration. Jails scans existing DOM and applies behavior/directives. It does not require JavaScript to render the whole page on the server. Use native `<template>` or `html-inner` fallback content to avoid visible unresolved markers during first paint.
+