@tiaforge-ui/sinter 0.2.0 → 0.3.1

package/dist/runtime/config.js

@@ -2,7 +2,8 @@
 // comes only from configure() in JavaScript, never from the DOM.
 import { defaultEnv } from './env.js';
 export const config = {
-    request: [], sessionProbe: null, onError: null, locale: null, urlSchemes: [], origins: [], transport: null, env: defaultEnv,
+    request: [], sessionProbe: null, onError: null, locale: null, urlSchemes: [], origins: [], transport: null,
+    confirm: (question) => globalThis.confirm(question), env: defaultEnv,
 };
 export function configure(options) {
     const { env, ...rest } = options;
@@ -14,10 +15,16 @@ export function configure(options) {
 export class SinterError extends Error {
     status;
     body;
-    constructor(status, body, message) {
+    detail;
+    /**
+     * @param detail what went wrong in words: the server's message or text, or a thrown error's
+     *   message; null when there is none (`message` then falls back to the HTTP status)
+     */
+    constructor(status, body, message, detail = null) {
         super(message);
         this.status = status;
         this.body = body;
+        this.detail = detail;
         this.name = 'SinterError';
     }
 }

package/dist/runtime/helpers.js

@@ -44,7 +44,7 @@ export function number(v, opts) {
 const BYTE_UNITS = ['byte', 'kilobyte', 'megabyte', 'gigabyte', 'terabyte'];
 export function bytes(v) {
     let n = Number(v);
-    if (v == null || Number.isNaN(n))
+    if (v == null || v === '' || Number.isNaN(n))
         return '';
     let i = 0;
     while (Math.abs(n) >= 1024 && i < BYTE_UNITS.length - 1) {

package/dist/runtime/request.d.ts

@@ -3,7 +3,7 @@ import type { Env } from './env.js';
 export declare const TIMEOUT = 30000;
 export interface SendInit {
     method?: string;
-    /** JSON-serialized unless FormData */
+    /** JSON-serialized unless FormData or URLSearchParams (sent form-encoded) */
     body?: unknown;
     headers?: Record<string, string>;
     signal?: AbortSignal | undefined;

package/dist/runtime/request.js

@@ -44,14 +44,18 @@ export function createRequestLayer(env, chain) {
         let body = init.body;
         if (body == null || method == 'GET')
             body = undefined;
+        else if (body instanceof URLSearchParams) {
+            body = body.toString();
+            headers.set('Content-Type', 'application/x-www-form-urlencoded;charset=UTF-8');
+        }
         else if (!(body instanceof FormData)) {
             body = JSON.stringify(body);
             headers.set('Content-Type', 'application/json');
         }
         headers.has('Accept') || headers.set('Accept', 'application/json');
         // mutations outlive the page: a navigation right after a click must not cancel the write
-        // (keepalive bodies are limited to 64 KB; larger ones and uploads go without it)
-        const keepalive = method != 'GET' && method != 'HEAD' && (body == null || (typeof body == 'string' && body.length < 60_000));
+        // (keepalive bodies are limited to 64 KiB; larger ones and uploads go without it)
+        const keepalive = method != 'GET' && method != 'HEAD' && (body == null || (typeof body == 'string' && bytes(body) < 60_000));
         inflight++;
         try {
             const res = await run(new Request(target, { method, headers, body: body ?? null, credentials: 'same-origin', signal: init.signal ?? null, keepalive }));
@@ -71,12 +75,15 @@ export function createRequestLayer(env, chain) {
         const res = await raw(url, init), body = await parseBody(res);
         if (!res.ok) {
             const b = body, m = typeof body == 'string' ? body.length < 200 && body.trim() : b?.message ?? b?.error;
-            throw new SinterError(res.status, body, typeof m == 'string' && m ? m : `${res.status} ${res.statusText}`.trim());
+            const detail = typeof m == 'string' && m ? m : null;
+            throw new SinterError(res.status, body, detail ?? `${res.status} ${res.statusText}`.trim(), detail);
         }
         return body;
     }
     return { send, raw, get inflight() { return inflight; } };
 }
+/** UTF-8 size of a string; a short one cannot reach the limit (at most 3 bytes per UTF-16 unit). */
+const bytes = (s) => (s.length < 20_000 ? s.length : new TextEncoder().encode(s).length);
 /** 204 or empty → null; JSON content type → parsed; anything else → text. */
 export async function parseBody(res) {
     const text = res.status == 204 ? '' : await res.text();

package/dist/runtime/store.js

@@ -160,7 +160,8 @@ export function createResource(name, o) {
         }
     };
     function visible() {
-        if (view)
+        // a locale change re-sorts strings: a view sorted for another locale is stale
+        if (view && !(coll && field && o.locale?.() !== sortedFor))
             return view;
         if (!coll)
             return (view = { l: [], get: () => undefined, s: over ? over.s : single });

package/dist/sse.js

@@ -199,10 +199,13 @@ class Connection {
 const sse = {
     name: 'sse',
     install(app) {
-        // connect after mount has created resources and loaders
+        // connect after mount has created resources and loaders, unless the app is gone by then
+        let alive = true;
+        app.addCleanup(() => { alive = false; });
         app.env.queueMicrotask(() => {
-            for (const def of app.ir.syncs)
-                new Connection(app, def).start();
+            if (alive)
+                for (const def of app.ir.syncs)
+                    new Connection(app, def).start();
         });
     },
 };

package/dist/testing/index.js

@@ -13,8 +13,9 @@ import optimistic from '../optimistic.js';
 import paginate from '../paginate.js';
 import each from '../each.js';
 import persist from '../persist.js';
+import listbox from '../listbox.js';
 import sse from '../sse.js';
-const FEATURES = { dev, sse, optimistic, paginate, persist, cache, each };
+const FEATURES = { dev, sse, optimistic, paginate, persist, cache, each, listbox };
 function isResponseSpec(v) {
     if (!v || typeof v !== 'object' || Array.isArray(v))
         return false;

package/docs/diagnostics.md

@@ -88,7 +88,7 @@ Error, for example:
 
 > `m.is_read = true` mutates a resource. Use `patch('messages', m, {is_read: true})`
 
-Resource data is read-only in expressions: it mirrors the server, and a direct write would be lost on the next refresh or event.
+Resource data is read-only in expressions: it mirrors the server, and a direct write (an assignment, a mutating method such as `push()`, or `Object.assign()` on an item) would be lost on the next refresh or event.
 
 **Fix:** Use the `patch()` call from the message, or copy the item with `structuredClone(c)` to edit it in state.
 
@@ -108,9 +108,9 @@ Error, for example:
 
 > `onclick` cannot be bound with `data-sn-attr`; use `data-sn-on-click`
 
-The binding could run script or inject markup from data: event-handler attributes, `style`, `srcdoc`, `innerHTML`, bindings on `<script>` and similar elements, URL templates that do not start with a literal path, or persisted password fields.
+The binding could run script or inject markup from data: event-handler attributes, `style`, `srcdoc`, `innerHTML`, bindings on `<script>` and similar elements, URL templates that do not start with a literal path (or with a literal origin that lacks its `/` before a value), persisted password fields, or `constructor`, `__proto__` and `prototype` named in an expression.
 
-**Fix:** Use the safe equivalent the message names: `data-sn-on-*` for events, `data-sn-style` for styles, a literal `/path` at the start of a URL template.
+**Fix:** Use the safe equivalent the message names: `data-sn-on-*` for events, `data-sn-style` for styles, a literal `/path` (or `https://host/`) at the start of a URL template.
 
 ## SN208 type-error
 
@@ -122,6 +122,16 @@ TypeScript found a type error in an expression. Reported by `sinter check`, `sin
 
 **Fix:** Fix the expression, or the type: `type` on `<sn-resource>`, the OpenAPI spec, or a JSDoc cast in `data-sn-state`.
 
+## SN209 name-conflict
+
+Error, for example:
+
+> `s` is already defined here by `data-sn-let`; use another name
+
+A `data-sn-let` name is inlined wherever it is read, so it cannot share a name with a state variable or loop variable in its scope, or be redeclared inside it. A resource cannot take the name of a store function (`refresh`, `upsert`, `patch`, `remove`, `page`, `showModal`, `close`, `reset`, `emit`).
+
+**Fix:** Rename the let, the state or loop variable, or the resource.
+
 ## SN301 unknown-resource
 
 Error, for example:
@@ -202,6 +212,16 @@ The resource matched an operation in the OpenAPI spec, but its `items` or `total
 
 **Fix:** Fix the path in `items` or `total`, or the spec if the API changed.
 
+## SN309 unknown-dialog
+
+Error, for example:
+
+> no `<dialog id="compose-dialg">` on this page. Did you mean `compose-dialog`?
+
+`showModal(id)` and `close(id)` name a `<dialog>` by its literal `id`, which must be on the page or one of its partials.
+
+**Fix:** Fix the id, or add `id` to the `<dialog>`. `close()` without an argument closes the dialog around the element.
+
 ## SN310 unknown-action
 
 Error, for example:

package/html-custom-data.json

@@ -118,6 +118,10 @@
       "name": "data-sn-state",
       "description": "declares local reactive state for the element and its subtree (object literal)"
     },
+    {
+      "name": "data-sn-let",
+      "description": "derived names for the element and its subtree, computed where they are read; later names may use earlier ones (object literal {name: expression})"
+    },
     {
       "name": "data-sn-text",
       "description": "sets textContent; never HTML (value expression)"
@@ -162,6 +166,10 @@
       "name": "data-sn-else",
       "description": "on a <template> directly after an if template"
     },
+    {
+      "name": "data-sn-listbox",
+      "description": "on a text input: arrow keys mark a [role=option] of that list (empty: the nearest [role=listbox] around the input), Enter or Tab clicks it, Escape fires `dismiss` (id of the suggestion list, or empty)"
+    },
     {
       "name": "data-sn-persist",
       "description": "persists the model or state in localStorage under sn: (storage key)"
@@ -216,7 +224,15 @@
     },
     {
       "name": "data-sn-catch",
-      "description": "runs after an error; $error = {status, body, message} (handler expression)"
+      "description": "runs after an error; $error = {status, body, message, detail} (handler expression)"
+    },
+    {
+      "name": "data-sn-confirm",
+      "description": "asks this question before the action runs (configure({ confirm }), window.confirm by default); no question when falsy (value expression)"
+    },
+    {
+      "name": "data-sn-encoding",
+      "description": "form: the body (data-sn-body, arrays as repeated keys, or the form) goes as application/x-www-form-urlencoded (json | form)"
     },
     {
       "name": "data-sn-path",
@@ -245,6 +261,18 @@
     {
       "name": "data-sn-on-keydown",
       "description": "plain event handler, no request; e.g. data-sn-on-click"
+    },
+    {
+      "name": "data-sn-debounce-input",
+      "description": "delays only that event's data-sn-on-<event> handler (it runs with the last event); e.g. data-sn-debounce-input"
+    },
+    {
+      "name": "data-sn-debounce-keyup",
+      "description": "delays only that event's data-sn-on-<event> handler (it runs with the last event); e.g. data-sn-debounce-input"
+    },
+    {
+      "name": "data-sn-debounce-scroll",
+      "description": "delays only that event's data-sn-on-<event> handler (it runs with the last event); e.g. data-sn-debounce-input"
     }
   ]
 }

package/llms.txt

@@ -7,6 +7,7 @@ Package: @tiaforge-ui/sinter. Every directive is a `data-sn-*` attribute or an `
 ## Attributes
 
 - `data-sn-state` (object literal): declares local reactive state for the element and its subtree
+- `data-sn-let` (object literal {name: expression}): derived names for the element and its subtree, computed where they are read; later names may use earlier ones
 - `data-sn-text` (value expression): sets textContent; never HTML
 - `data-sn-attr` (object literal {href: …}): literal keys; null/false removes, true sets empty; URL values are checked
 - `data-sn-class` (object literal {unread: …}): toggles each class
@@ -18,6 +19,7 @@ Package: @tiaforge-ui/sinter. Every directive is a `data-sn-*` attribute or an `
 - `data-sn-key` (value expression): row identity; defaults to the resource key or object identity
 - `data-sn-if` (value expression): renders a <template> while truthy
 - `data-sn-else`: on a <template> directly after an if template
+- `data-sn-listbox` (id of the suggestion list, or empty): on a text input: arrow keys mark a [role=option] of that list (empty: the nearest [role=listbox] around the input), Enter or Tab clicks it, Escape fires `dismiss`
 - `data-sn-persist` (storage key): persists the model or state in localStorage under sn:
 - `data-sn-get` (URL template): GET action; latest wins
 - `data-sn-post` (URL template): POST action
@@ -31,10 +33,13 @@ Package: @tiaforge-ui/sinter. Every directive is a `data-sn-*` attribute or an `
 - `data-sn-concurrency` (block | queue | latest): mutations only; default block for forms, queue otherwise
 - `data-sn-optimistic` (handler expression): patch/upsert/remove calls applied before the request, rolled back on failure
 - `data-sn-then` (handler expression): runs after a 2xx response; $result = parsed body
-- `data-sn-catch` (handler expression): runs after an error; $error = {status, body, message}
+- `data-sn-catch` (handler expression): runs after an error; $error = {status, body, message, detail}
+- `data-sn-confirm` (value expression): asks this question before the action runs (configure({ confirm }), window.confirm by default); no question when falsy
+- `data-sn-encoding` (json | form): form: the body (data-sn-body, arrays as repeated keys, or the form) goes as application/x-www-form-urlencoded
 - `data-sn-path` (URL patterns /a/:b …): on <html>: the path shapes this page is served for; `:name` segments appear read-only in $url
 - `data-sn-data` (resource name): on <script type="application/json"> in <head>: initial data for a resource
 - `data-sn-on-<event>` (handler expression): plain event handler, no request; e.g. data-sn-on-click
+- `data-sn-debounce-<event>` (milliseconds): delays only that event's data-sn-on-<event> handler (it runs with the last event); e.g. data-sn-debounce-input
 
 ## Elements
 
@@ -60,11 +65,11 @@ Package: @tiaforge-ui/sinter. Every directive is a `data-sn-*` attribute or an `
 
 ## Store functions
 
-`refresh()`, `upsert()`, `patch()`, `remove()`, `page()`, `close()`, `reset()`, `emit()`: `refresh('name')`, `upsert('name', item)`, `patch('name', item, {…})`, `remove('name', item)`, `page('name', 'next' | 'prev' | 'first' | 'last' | n)`, `close()` the nearest dialog, `reset()` the nearest form, `emit('event', detail)`.
+`refresh()`, `upsert()`, `patch()`, `remove()`, `page()`, `showModal()`, `close()`, `reset()`, `emit()`: `refresh('name')`, `upsert('name', item)`, `patch('name', item, {…})`, `remove('name', item)`, `page('name', 'next' | 'prev' | 'first' | 'last' | n)`, `showModal('id')` opens a dialog by its literal id, `close()` the nearest dialog or `close('id')` that one, `reset()` the nearest form, `emit('event', detail)`.
 
 ## Diagnostics
 
-`SN101 unknown-attribute`, `SN102 wrong-element`, `SN103 missing-key`, `SN104 unsupported-model`, `SN201 unknown-identifier`, `SN202 forbidden-global`, `SN203 side-effect`, `SN204 optimistic-scope`, `SN205 resource-mutation`, `SN206 unknown-namespace-member`, `SN207 unsafe-sink`, `SN208 type-error`, `SN301 unknown-resource`, `SN302 duplicate-resource`, `SN303 unknown-meta-field`, `SN304 keyset-jump`, `SN305 include-not-found`, `SN306 include-cycle`, `SN307 openapi-invalid`, `SN308 unknown-schema-field`, `SN310 unknown-action`, `SN401 parse-error`, `SN501 unused-resource`, `SN502 non-reactive-value`, `SN503 data-bound-id`, `SN504 untyped-resource`, `SN505 unknown-query-param`, `SN506 untyped-event`.
+`SN101 unknown-attribute`, `SN102 wrong-element`, `SN103 missing-key`, `SN104 unsupported-model`, `SN201 unknown-identifier`, `SN202 forbidden-global`, `SN203 side-effect`, `SN204 optimistic-scope`, `SN205 resource-mutation`, `SN206 unknown-namespace-member`, `SN207 unsafe-sink`, `SN208 type-error`, `SN209 name-conflict`, `SN301 unknown-resource`, `SN302 duplicate-resource`, `SN303 unknown-meta-field`, `SN304 keyset-jump`, `SN305 include-not-found`, `SN306 include-cycle`, `SN307 openapi-invalid`, `SN308 unknown-schema-field`, `SN309 unknown-dialog`, `SN310 unknown-action`, `SN401 parse-error`, `SN501 unused-resource`, `SN502 non-reactive-value`, `SN503 data-bound-id`, `SN504 untyped-resource`, `SN505 unknown-query-param`, `SN506 untyped-event`.
 
 ## Recipes
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tiaforge-ui/sinter",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "Bind JSON APIs to plain HTML: keyed resources, SSE sync, template bindings and optimistic mutations, compiled at build time.",
   "license": "MIT",
   "author": "Tia Heinrich",
@@ -38,6 +38,7 @@
     "./paginate": "./dist/paginate.js",
     "./each": "./dist/each.js",
     "./persist": "./dist/persist.js",
+    "./listbox": "./dist/listbox.js",
     "./cache": "./dist/cache.js",
     "./compiler": "./dist/compiler/index.js",
     "./vite": "./dist/vite.js",
@@ -61,6 +62,7 @@
     "bench": "vitest run --config bench/runtime/vitest.config.ts",
     "size": "npm run build && node scripts/size.mjs",
     "docs": "UPDATE_DOCS=1 vitest run test/docs.test.ts",
+    "release": "node scripts/release.mjs",
     "prepublishOnly": "rm -rf dist && npm run build && npm test"
   },
   "dependencies": {