caspian-utils 0.1.16 → 0.1.17

package/dist/docs/pulsepoint.md

@@ -418,10 +418,10 @@ Global helpers exposed through the `pp` singleton and also merged into the compo
 Notes:
 
 - The global `pp` singleton auto-mounts once the runtime is loaded and the DOM is ready. Manual `pp.mount()` is still safe because it short-circuits after the first mount.
-- `pp.state` setters accept either a value or an updater function.
-- `pp.effect` and `pp.layoutEffect` are cleanup-style hooks. They may return only a synchronous cleanup function; returning a promise warns and is ignored, so start async work inside the effect instead.
-- A function used through `pp-ref` may return a synchronous cleanup function. PulsePoint runs it when that callback ref is replaced or detached; callbacks that do not return cleanup retain the legacy `callback(null)` detach behavior.
-- `pp.portal(ref)` defaults to `document.body` when no target is provided.
+- `pp.state` setters accept either a value or an updater function.
+- `pp.effect` and `pp.layoutEffect` are cleanup-style hooks. They may return only a synchronous cleanup function; returning a promise warns and is ignored, so start async work inside the effect instead.
+- A function used through `pp-ref` may return a synchronous cleanup function. PulsePoint runs it when that callback ref is replaced or detached; callbacks that do not return cleanup retain the legacy `callback(null)` detach behavior.
+- `pp.portal(ref)` defaults to `document.body` when no target is provided.
 - Older docs may call the RPC helper `pp.fetchFunction()`. In the current bundled runtime the implemented global API is `pp.rpc()`.
 - Keep template-facing bindings at the top level so the AST-based exporter can see them.
 - For predictable code generation, prefer passing an explicit dependency array to `pp.effect`, `pp.layoutEffect`, `pp.memo`, and `pp.callback`.
@@ -586,22 +586,23 @@ Nested components:
 - Nested roots that contain their own `script` block are masked during parent template compilation.
 - Scriptless nested component roots are not fully masked during parent template compilation in the current source. Avoid generating child-local interpolations inside a nested root unless that child has its own `script` block.
 
-## Template expressions and attributes
-
-- Use `{expression}` in text nodes and attribute values.
-- Follow HTML-first attribute naming. Native event attributes are lowercase DOM event attributes (`onclick`, `oninput`, `onsubmit`). Every other attribute on a component boundary is a prop: kebab-case names become camel-cased only inside `pp.props` (`selected-value` becomes `selectedValue`, `open-change` becomes `openChange`, and `on-open-change` becomes `onOpenChange`). A function prop does not need an `on-` prefix; that prefix is only an API naming convention. Use `on-click` when a component intentionally exposes an `onClick` prop, because lowercase `onclick` is reserved for the native DOM event on the boundary element.
-- Pure bindings like `value="{count}"` are evaluated as expressions.
+## Template expressions and attributes
+
+- Use `{expression}` in text nodes and attribute values.
+- Follow HTML-first attribute naming. Native event attributes are lowercase DOM event attributes (`onclick`, `oninput`, `onsubmit`). Every other attribute on a component boundary is a prop: kebab-case names become camel-cased only inside `pp.props` (`selected-value` becomes `selectedValue`, `open-change` becomes `openChange`, and `on-open-change` becomes `onOpenChange`). A function prop does not need an `on-` prefix; that prefix is only an API naming convention. Use `on-click` when a component intentionally exposes an `onClick` prop, because lowercase `onclick` is reserved for the native DOM event on the boundary element.
+- Pure bindings like `value="{count}"` are evaluated as expressions.
 - For dynamic inline styles in authored templates, prefer `pp-style="{styleText}"` over `style="{styleText}"` so HTML/CSS tooling does not parse the brace expression as raw CSS.
 - `pp-style` is an authoring alias. The compiler rewrites it to a native `style` attribute in rendered output.
 - If the same element already has a static `style` attribute, `pp-style` is merged into that `style` value during compilation.
 - Mixed text like `class="card {isActive ? 'active' : ''}"` is supported.
-- Arrays in template expressions are joined without commas.
-- `null`, `undefined`, and boolean expression results render as an empty string in text output.
-- Plain objects, functions, and symbols are invalid template children; the runtime warns and omits them instead of rendering accidental strings such as `[object Object]`.
+- Arrays in template expressions are joined without commas.
+- `null`, `undefined`, and boolean expression results render as an empty string in text output.
+- Plain objects, functions, and symbols are invalid template children; the runtime warns and omits them instead of rendering accidental strings such as `[object Object]`.
 - Supported boolean attributes are normalized so truthy values emit the bare attribute and falsy values remove it.
+- Boolean expressions bound to string-valued attributes such as `aria-pressed`, `aria-expanded`, and `data-*` serialize as the literal strings `"true"` and `"false"`, including on nested component boundaries.
 - `<textarea value="{draft}"></textarea>` is normalized into textarea content.
 - Use `pp-spread="{...attrs}"` to spread an object expression into attributes.
-- `pp-spread` omits nullish values, omits known HTML boolean attributes when their value is `false`, emits them bare when `true`, preserves string-valued `aria-*`/`data-*` booleans, and escapes `&`, `"`, and `<` in emitted attribute values.
+- `pp-spread` omits nullish values, omits known HTML boolean attributes when their value is `false`, emits them bare when `true`, preserves string-valued `aria-*`/`data-*` booleans, and escapes `&`, `"`, and `<` in emitted attribute values.
 - Use plain `key` for keyed diffing. `pp-key` is not implemented.
 
 Example:
@@ -632,23 +633,23 @@ The render pipeline wraps each top-level `pp-component` root in an inert `<templ
 - Do not add per-tag workarounds to dodge first-paint validation (static-path `hidden` toggles instead of binding `d`, `data-*` URL holders, `hidden`-gated `<img src>`, or an SSR-resolved initial value). The deferral removes the whole class at once.
 - `pp-style` and the `<input>`/`<select>`/`checked`/`defaultvalue`/`<textarea>` value rewrites still apply — but for different reasons that deferral does not replace: authoring-source tooling (`style="{...}"` breaks HTML/CSS linters) and attribute-vs-property correctness for controlled form fields.
 
-## Refs
-
-- Refs are for imperative element access. Do not use `pp-ref` as the default way to read normal form input values on submit; prefer the form's `onsubmit` event plus `Object.fromEntries(new FormData(event.currentTarget).entries())`.
-- `pp-ref` works on native elements and on `x-*` component tags. On a component tag it resolves in the parent's scope and binds to the component's concrete root DOM element, so `<x-input pp-ref="{nameInput}" />` exposes the rendered `<input>` without a wrapper or `querySelector(...)`.
-- Use the bare-name form, such as `pp-ref="nameInput"`, when the ref object or callback is already available under that name in scope. The runtime resolves this form by scope lookup.
-- Use the brace-expression form, such as `pp-ref="{nameInput}"`, `pp-ref="{registerRef(id)}"`, or `pp-ref="{el => setNode(el)}"`, when the compiler should capture an expression. This is the preferred general form for component tags and dynamic or callback expressions.
-- `pp.ref(null)` is the normal way to create a ref object.
-- Callback refs and `{ current }` refs are both supported.
-- Captured brace-form refs are compiled into an internal `data-pp-ref` token and rebound after render.
-- Component refs are attached before layout effects and passive effects run, and detach with `null` (or a callback's returned synchronous cleanup) when the owning element unmounts.
-- A composition component whose root is another `x-*` component forwards the ref through Caspian's layout-neutral component hosts to the eventual concrete DOM root.
-- Plain `pp-ref` bindings are preserved across rerenders, including no-op rerenders that skip DOM diffing.
+## Refs
+
+- Refs are for imperative element access. Do not use `pp-ref` as the default way to read normal form input values on submit; prefer the form's `onsubmit` event plus `Object.fromEntries(new FormData(event.currentTarget).entries())`.
+- `pp-ref` works on native elements and on `x-*` component tags. On a component tag it resolves in the parent's scope and binds to the component's concrete root DOM element, so `<x-input pp-ref="{nameInput}" />` exposes the rendered `<input>` without a wrapper or `querySelector(...)`.
+- Use the bare-name form, such as `pp-ref="nameInput"`, when the ref object or callback is already available under that name in scope. The runtime resolves this form by scope lookup.
+- Use the brace-expression form, such as `pp-ref="{nameInput}"`, `pp-ref="{registerRef(id)}"`, or `pp-ref="{el => setNode(el)}"`, when the compiler should capture an expression. This is the preferred general form for component tags and dynamic or callback expressions.
+- `pp.ref(null)` is the normal way to create a ref object.
+- Callback refs and `{ current }` refs are both supported.
+- Captured brace-form refs are compiled into an internal `data-pp-ref` token and rebound after render.
+- Component refs are attached before layout effects and passive effects run, and detach with `null` (or a callback's returned synchronous cleanup) when the owning element unmounts.
+- A composition component whose root is another `x-*` component forwards the ref through Caspian's layout-neutral component hosts to the eventual concrete DOM root.
+- Plain `pp-ref` bindings are preserved across rerenders, including no-op rerenders that skip DOM diffing.
 - Ref callbacks may be called with `null` during cleanup.
 - The runtime generates `data-pp-ref` internally. Do not author it.
 - Do not author `pp-event-owner`, `pp-owner`, or `pp-dynamic-*` attributes by hand.
 
-Example:
+Example:
 
 ```html
 <div>
@@ -658,29 +659,29 @@ Example:
   <script>
     const nameInput = pp.ref(null);
   </script>
-</div>
-```
-
-Component example:
-
-```html
-<div>
-  <x-input pp-ref="{nameInput}" name="name" />
-  <button onclick="nameInput.current?.focus()">Focus</button>
-
-  <script>
-    const nameInput = pp.ref(null);
-  </script>
-</div>
-```
+</div>
+```
+
+Component example:
+
+```html
+<div>
+  <x-input pp-ref="{nameInput}" name="name" />
+  <button onclick="nameInput.current?.focus()">Focus</button>
+
+  <script>
+    const nameInput = pp.ref(null);
+  </script>
+</div>
+```
 
 ## Lists and keyed diffing
 
 - Use `pp-for` only on `<template>`.
 - Supported forms are `item in items` and `(item, index) in items`.
-- Collections may be arrays or synchronous iterables such as `Set`, `Map`, typed arrays, strings, and generators. Non-null non-iterable values warn and render as empty lists.
+- Collections may be arrays or synchronous iterables such as `Set`, `Map`, typed arrays, strings, and generators. Non-null non-iterable values warn and render as empty lists.
 - Loop content can contain interpolations, events, refs, and nested components.
-- Event handlers inside loops capture each rendered item, so later collection changes do not retarget an existing row handler.
+- Event handlers inside loops capture each rendered item, so later collection changes do not retarget an existing row handler.
 - Use stable unique `key` values on repeated sibling elements.
 - Duplicate keys trigger warnings and reduce diff quality.
 - Keyed reconciliation preserves DOM identity across reorders and insertions.
@@ -737,9 +738,9 @@ Example:
 - Push navigation resets window scroll to the top.
 - Saved history-entry scroll state is used during history traversal instead of relying only on the live DOM scroll at the time the user clicks Back or Forward.
 - Unmarked scrollable containers may keep their outgoing scroll on push navigation so shared shells such as sidebars, rails, and docs nav panes stay stable across child-route changes.
-- `pp-reset-scroll="true"` on a scroll container opts that container into reset-on-navigation behavior. Use it on the main content pane of a grouped shell when page content should start at the top on each child-route navigation.
-- `pp-scroll-key="stable-name"` gives a scroll container a stable restoration identity. Prefer it when an element has no stable `id`, or when its classes or position can change between routes.
-- `body[pp-reset-scroll="true"]` is the global override for routes that should reset window scroll and every scrollable element.
+- `pp-reset-scroll="true"` on a scroll container opts that container into reset-on-navigation behavior. Use it on the main content pane of a grouped shell when page content should start at the top on each child-route navigation.
+- `pp-scroll-key="stable-name"` gives a scroll container a stable restoration identity. Prefer it when an element has no stable `id`, or when its classes or position can change between routes.
+- `body[pp-reset-scroll="true"]` is the global override for routes that should reset window scroll and every scrollable element.
 - Navigation dispatches `pp:navigation:start`, `pp:navigation:complete`, and `pp:navigation:error` events on `document`.
 
 RPC notes:
@@ -881,9 +882,9 @@ These are current runtime caveats that matter for authors and AI tools:
 - Caspian already injects `pp-component` and rewrites owned scripts to `type="text/pp"` during render.
 - Nested roots without their own `script[type="text/pp"]` block are not fully isolated during parent template compilation.
 - The global `pp` singleton auto-mounts on DOM ready, and `pp.mount()` is idempotent.
-- `pp.effect` and `pp.layoutEffect` are cleanup-style hooks. Their callbacks are not promise-aware.
-- Callback refs may return synchronous cleanup functions, which run instead of a later `callback(null)` detach call.
-- `pp.context()` resolves through ancestor components, not the current component's own pending providers.
+- `pp.effect` and `pp.layoutEffect` are cleanup-style hooks. Their callbacks are not promise-aware.
+- Callback refs may return synchronous cleanup functions, which run instead of a later `callback(null)` detach call.
+- `pp.context()` resolves through ancestor components, not the current component's own pending providers.
 - `pp.provideContext` is not part of the current runtime API. Use an HTML-first lowercase provider tag such as `<themecontext.provider>`.
 - `pp.portal()` preserves logical ancestry through the registry, so context and prop refresh behavior continue to work through portaled descendants.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "caspian-utils",
-  "version": "0.1.16",
+  "version": "0.1.17",
   "description": "Caspian tooling",
   "main": "index.js",
   "scripts": {