@tiaforge-ui/sinter 0.2.0 → 0.3.0

package/README.md

@@ -96,7 +96,7 @@ Measurements and sources: [`docs/realworld-comparison.md`](docs/realworld-compar
   islands, which are plain custom elements.
 - You can't have a build step.
 - Your backend renders HTML, not JSON.
-- You need stability guarantees. sinter is at v0.2.
+- You need stability guarantees. sinter is at v0.3.
 
 ## Setup
 
@@ -147,12 +147,13 @@ Then write `data-sn-*` attributes in your HTML pages. Optional:
 ## Development
 
 ```sh
-npm test          # vitest (happy-dom)
+npm test          # vitest (happy-dom); CI runs typecheck, build and tests on every push (Node 22/24/26)
 npm run typecheck
 npm run build     # dist/
 npm run size      # size per page and module, with budgets
 npm run bench     # store and flush benchmarks (docs/benchmark.md)
 npm run docs      # regenerate llms.txt, html-custom-data.json (also the VS Code extension's) and docs/diagnostics.md
+npm run release -- 0.3.0   # bump versions, date the changelog, commit "Release 0.3.0", tag v0.3.0 (not pushed)
 ```
 
 License: MIT. Contributions are accepted under the Developer Certificate of Origin

package/dist/check/index.js

@@ -64,7 +64,8 @@ export function check(o) {
     const tsconfig = join(outDir, 'tsconfig.json');
     writeFileSync(tsconfig, JSON.stringify({
         compilerOptions: COMPILER_OPTIONS,
-        files: ['sinter.d.ts', ...support.openapi.map((f) => relative(outDir, f)), ...[...shadows.keys()].map((f) => relative(outDir, f).split('\\').join('/'))],
+        // the types module always, so augmentations in it (declare global, a library's import type {}) apply
+        files: ['sinter.d.ts', ...(support.types ? [relative(outDir, support.types.file).split('\\').join('/')] : []), ...support.openapi.map((f) => relative(outDir, f)), ...[...shadows.keys()].map((f) => relative(outDir, f).split('\\').join('/'))],
     }, null, 2) + '\n');
     const tsc = o.tsc ?? findTsc(o.root);
     const run = spawnSync(process.execPath, [tsc, '-p', tsconfig, '--pretty', 'false'], { encoding: 'utf8', cwd: outDir });

package/dist/check/shadow.d.ts

@@ -38,7 +38,7 @@ export declare function shadow(o: ShadowOptions): Shadow;
 /** Maps a 1-based shadow position to the HTML, or null for generated lines. */
 export declare function mapPosition(regions: Region[], line: number, col: number): CheckLoc | null;
 /** `sinter.d.ts`: the types the shadow files refer to. */
-export declare const DECLARATIONS = "// Generated by `sinter check`. Do not edit.\nexport interface Meta {\n  loading: boolean;\n  error: Err | null;\n  loadedAt: number | null;\n  pending: number;\n  total: number | null;\n  page?: number | null;\n  pages?: number | null;\n  from?: number | null;\n  to?: number | null;\n  hasPrev?: boolean;\n  hasNext?: boolean;\n}\nexport interface Err { status: number | null; body: any; message: string }\nexport interface CallContext { signal: AbortSignal; request(url: string, init?: { method?: string; body?: unknown; headers?: Record<string, string>; signal?: AbortSignal }): Promise<any>; el: Element | null }\n/** an action's parameters without its trailing context */\nexport type CallArgs<F> = F extends (...a: infer P) => any ? (P extends [...infer A, infer L] ? ([L] extends [CallContext] ? A : P) : P) : never;\nexport type Item<T> = NonNullable<T> extends readonly (infer U)[] ? U : NonNullable<T> extends Iterable<infer U> ? U : any;\nexport type El<K extends string> = K extends keyof HTMLElementTagNameMap ? HTMLElementTagNameMap[K] : HTMLElement;\nexport type Ev<K extends string> = K extends keyof HTMLElementEventMap ? HTMLElementEventMap[K] : CustomEvent;\nexport interface Store<R> {\n  refresh(name: keyof R & string): void;\n  upsert<K extends keyof R & string>(name: K, item: Item<R[K]>): void;\n  patch<K extends keyof R & string>(name: K, item: Partial<Item<R[K]>>, set: Partial<Item<R[K]>>): void;\n  remove<K extends keyof R & string>(name: K, item: Partial<Item<R[K]>>): void;\n  page(name: keyof R & string, to: 'next' | 'prev' | 'first' | 'last' | number): void;\n  close(): void;\n  reset(): void;\n  emit(event: string, detail?: unknown): void;\n}\ntype Style = 'short' | 'medium' | 'long' | 'full';\nexport function date(v: unknown, style?: Style): string;\nexport function time(v: unknown, style?: Style): string;\nexport function datetime(v: unknown, style?: Style): string;\nexport function relative(v: unknown, now?: unknown): string;\nexport function number(v: unknown, opts?: Intl.NumberFormatOptions): string;\nexport function bytes(v: unknown): string;\n";
+export declare const DECLARATIONS = "// Generated by `sinter check`. Do not edit.\nexport interface Meta {\n  loading: boolean;\n  error: Err | null;\n  loadedAt: number | null;\n  pending: number;\n  total: number | null;\n  page?: number | null;\n  pages?: number | null;\n  from?: number | null;\n  to?: number | null;\n  hasPrev?: boolean;\n  hasNext?: boolean;\n}\nexport interface Err { status: number | null; body: any; message: string; detail: string | null }\ndeclare global {\n  /**\n   * Value types for attributes bound with data-sn-attr. Empty here; a library extends it to type its own\n   * attributes, e.g. tinystyle (import type {} from '@tiaforge-ui/tinystyle/sinter' in the types module).\n   */\n  interface SinterAttributes {}\n}\n/** what data-sn-attr accepts: the keys SinterAttributes types, anything else as before */\nexport type Attrs = { [K in keyof SinterAttributes]?: SinterAttributes[K] } & Record<string, unknown>;\nexport interface CallContext { signal: AbortSignal; request(url: string, init?: { method?: string; body?: unknown; headers?: Record<string, string>; signal?: AbortSignal }): Promise<any>; el: Element | null }\n/** an action's parameters without its trailing context */\nexport type CallArgs<F> = F extends (...a: infer P) => any ? (P extends [...infer A, infer L] ? ([L] extends [CallContext] ? A : P) : P) : never;\nexport type Item<T> = NonNullable<T> extends readonly (infer U)[] ? U : NonNullable<T> extends Iterable<infer U> ? U : any;\nexport type El<K extends string> = K extends keyof HTMLElementTagNameMap ? HTMLElementTagNameMap[K] : HTMLElement;\nexport type Ev<K extends string> = K extends keyof HTMLElementEventMap ? HTMLElementEventMap[K] : CustomEvent;\nexport interface Store<R> {\n  refresh(name: keyof R & string): void;\n  upsert<K extends keyof R & string>(name: K, item: Item<R[K]>): void;\n  patch<K extends keyof R & string>(name: K, item: Partial<Item<R[K]>>, set: Partial<Item<R[K]>>): void;\n  remove<K extends keyof R & string>(name: K, item: Partial<Item<R[K]>>): void;\n  page(name: keyof R & string, to: 'next' | 'prev' | 'first' | 'last' | number): void;\n  showModal(id: string): void;\n  close(id?: string): void;\n  reset(): void;\n  emit(event: string, detail?: unknown): void;\n}\ntype Style = 'short' | 'medium' | 'long' | 'full';\nexport function date(v: unknown, style?: Style): string;\nexport function time(v: unknown, style?: Style): string;\nexport function datetime(v: unknown, style?: Style): string;\nexport function relative(v: unknown, now?: unknown): string;\nexport function number(v: unknown, opts?: Intl.NumberFormatOptions): string;\nexport function bytes(v: unknown): string;\n";
 /**
  * Maps a 1-based position in an HTML file to the shadow, or null when it is not inside an
  * expression. `lines` are the shadow's lines.

package/dist/check/shadow.js

@@ -115,7 +115,7 @@ export function shadow(o) {
             line(`} */${after}`);
             return;
         }
-        const text = t.kind === 'openapi'
+        const text = t.kind === 'decl' ? decl(t.name) : t.kind === 'openapi'
             ? schemaToTs(t.schema, (n) => `$O${t.spec}.${typeName(n)}`)
             : t.kind === 'call'
                 ? (t.args ? `${decl('CallArgs')}<typeof $A.${t.name}>` : `Awaited<ReturnType<typeof $A.${t.name}>>`)
@@ -135,6 +135,10 @@ export function shadow(o) {
                 f.names.forEach((n, k) => { at(f.locs?.[k]); line(`${n},`); });
                 line(`} = ${f.init === null ? '$any' : `$e${f.init}()`};`);
             }
+            else if (f.kind === 'let') {
+                at(f.loc);
+                line(`const ${f.name} = ${f.init === null ? '$any' : `$e${f.init}()`};`);
+            }
             else {
                 at(f.loc);
                 line(`const ${f.item} = ${f.init === null ? '$any' : `$item($e${f.init}())`};`);
@@ -233,7 +237,16 @@ export interface Meta {
   hasPrev?: boolean;
   hasNext?: boolean;
 }
-export interface Err { status: number | null; body: any; message: string }
+export interface Err { status: number | null; body: any; message: string; detail: string | null }
+declare global {
+  /**
+   * Value types for attributes bound with data-sn-attr. Empty here; a library extends it to type its own
+   * attributes, e.g. tinystyle (import type {} from '@tiaforge-ui/tinystyle/sinter' in the types module).
+   */
+  interface SinterAttributes {}
+}
+/** what data-sn-attr accepts: the keys SinterAttributes types, anything else as before */
+export type Attrs = { [K in keyof SinterAttributes]?: SinterAttributes[K] } & Record<string, unknown>;
 export interface CallContext { signal: AbortSignal; request(url: string, init?: { method?: string; body?: unknown; headers?: Record<string, string>; signal?: AbortSignal }): Promise<any>; el: Element | null }
 /** an action's parameters without its trailing context */
 export type CallArgs<F> = F extends (...a: infer P) => any ? (P extends [...infer A, infer L] ? ([L] extends [CallContext] ? A : P) : P) : never;
@@ -246,7 +259,8 @@ export interface Store<R> {
   patch<K extends keyof R & string>(name: K, item: Partial<Item<R[K]>>, set: Partial<Item<R[K]>>): void;
   remove<K extends keyof R & string>(name: K, item: Partial<Item<R[K]>>): void;
   page(name: keyof R & string, to: 'next' | 'prev' | 'first' | 'last' | number): void;
-  close(): void;
+  showModal(id: string): void;
+  close(id?: string): void;
   reset(): void;
   emit(event: string, detail?: unknown): void;
 }

package/dist/compiler/check-unit.d.ts

@@ -7,7 +7,7 @@ export interface CheckLoc {
     chain: string[];
 }
 /**
- * A scope frame: a `data-sn-state` object or a `data-sn-for` loop. `init` is the
+ * A scope frame: a `data-sn-state` object, a `data-sn-for` loop or a `data-sn-let` name. `init` is the
  * expression that creates it (the state literal, the list), or null when that
  * expression did not compile.
  */
@@ -27,6 +27,13 @@ export type CheckFrame =
     init: number | null;
     loc?: CheckLoc;
     indexLoc?: CheckLoc;
+}
+/** a `data-sn-let` name; `loc`: where the name is written */
+ | {
+    kind: 'let';
+    name: string;
+    init: number | null;
+    loc?: CheckLoc;
 };
 /** A type the checker writes for something other than a resource. */
 export type TypeRef = 
@@ -53,13 +60,18 @@ export type TypeRef =
     kind: 'call';
     name: string;
     args?: boolean;
+}
+/** a type sinter declares itself (\`Attrs\` for \`data-sn-attr\`) */
+ | {
+    kind: 'decl';
+    name: string;
 };
 export interface CheckExpr {
     src: string;
     /** `value` returns the expression; `handler` runs it as statements */
     mode: 'value' | 'handler';
     loc: CheckLoc;
-    /** frames visible here, in the order sinter resolves them last: states outer to inner, then loops outer to inner */
+    /** frames visible here, in the order sinter resolves them last: states, then loops, then lets, each outer to inner */
     frames: number[];
     /** tag of the element the expression sits on, for `$el` */
     tag: string;

package/dist/compiler/compile.js

@@ -8,7 +8,7 @@ import { ATTRIBUTES, ELEMENTS } from './vocabulary.js';
 import { matchOperation, matchResource, queryNames, walk } from './openapi.js';
 const ATTRS = ATTRIBUTES.map((a) => a.name);
 const METHODS = ['get', 'post', 'put', 'patch', 'delete'];
-const ACTION_ONLY = ['body', 'trigger', 'debounce', 'concurrency', 'optimistic', 'then', 'catch'];
+const ACTION_ONLY = ['body', 'trigger', 'debounce', 'concurrency', 'optimistic', 'then', 'catch', 'confirm', 'encoding'];
 const UNSAFE_ELEMENTS = new Set(['script', 'style', 'iframe', 'object', 'embed', 'base', 'meta', 'link', 'animate', 'set', 'animatemotion', 'animatetransform']);
 const FORM_CONTROLS = new Set(['input', 'select', 'textarea']);
 const RESOURCE_ATTRS = ELEMENTS.find((e) => e.name === 'sn-resource').attrs;
@@ -55,7 +55,7 @@ class Compiler {
         this.page = {
             resources: new Map(), helpers: new Set(opts.helpers.names), namespaces: ns,
             actions: new Set([...(opts.actions?.names ?? []), ...Object.keys(opts.actions?.namespaces ?? {})]),
-            usedHelpers: new Set(), usedNs: new Map(), usesNow: false, pathParams: new Set(),
+            usedHelpers: new Set(), usedNs: new Map(), usesNow: false, pathParams: new Set(), dialogs: new Set(),
         };
     }
     run(html) {
@@ -100,7 +100,7 @@ class Compiler {
         return {
             html: parse5.serialize(doc),
             ir, fns: this.fns,
-            features: [...(this.opts.dev ? ['dev'] : []), ...['sse', 'optimistic', 'paginate', 'persist', 'cache', 'each'].filter((f) => this.features.has(f))],
+            features: [...(this.opts.dev ? ['dev'] : []), ...['sse', 'optimistic', 'paginate', 'persist', 'cache', 'each', 'listbox'].filter((f) => this.features.has(f))],
             helpers: { user, builtin }, namespaces, calls: [...this.calls].sort(),
             diagnostics: this.diagnostics, files: [...this.files].sort(),
             ...(this.check ? { check: this.check } : {}),
@@ -321,7 +321,7 @@ class Compiler {
         // the browser merges adjacent text when it parses the output; merge now so node paths agree
         mergeText(parent);
     }
-    // ---- declarations (first pass: names only, so expressions can see every resource)
+    // ---- declarations (first pass: names only, so expressions can see every resource and dialog)
     declare(parent, inTemplate = false) {
         for (const child of parent.childNodes) {
             if (!isElement(child))
@@ -349,6 +349,11 @@ class Compiler {
                 this.resourceEls.set(name, child);
                 continue;
             }
+            if (child.tagName === 'dialog') {
+                const id = attr(child, 'id');
+                if (id)
+                    this.page.dialogs.add(id);
+            }
             this.declare(child, inTemplate);
             if (child.tagName === 'template')
                 this.declare(child.content, true);
@@ -412,7 +417,7 @@ class Compiler {
         // unknown attributes
         const known = new Set(ATTRS.map((a) => `data-sn-${a}`));
         for (const a of sn) {
-            if (known.has(a.name) || a.name.startsWith('data-sn-on-'))
+            if (known.has(a.name) || a.name.startsWith('data-sn-on-') || a.name.startsWith('data-sn-debounce-'))
                 continue;
             this.report(el, a.name, 'SN101', `\`${a.name}\` is not a sinter attribute.${didYouMean(a.name, [...known, 'data-sn-on-click'])}`, 0);
         }
@@ -466,13 +471,32 @@ class Compiler {
                     const locs = first.map((e) => this.locOf(el, 'data-sn-state', e.offset));
                     this.check.frames.push({ kind: 'state', names: [...entry.names], init: this.lastExpr, locs });
                 }
-                scope = { loops: scope.loops, states: [...scope.states, entry] };
+                this.checkNames(el, 'data-sn-state', scope, [...entry.names]);
+                scope = { ...scope, states: [...scope.states, entry] };
                 if (has('persist') && !has('model')) {
                     node.persist = get('persist');
                     this.features.add('persist');
                 }
             }
         }
+        // derived names: the element and its subtree read them like state
+        if (has('let'))
+            scope = this.lets(el, scope);
+        // a text field with suggestions: the listbox feature handles the keys (see src/listbox.ts)
+        if (has('listbox')) {
+            const list = get('listbox');
+            if (!['input', 'textarea'].includes(el.tagName))
+                this.report(el, 'data-sn-listbox', 'SN102', '`data-sn-listbox` belongs on a text `<input>` or `<textarea>`', 0);
+            else if (list && !/^[A-Za-z][\w-]*$/.test(list))
+                this.report(el, 'data-sn-listbox', 'SN401', '`data-sn-listbox` takes the literal `id` of the suggestion list, or nothing for the nearest `[role="listbox"]` around the input', 0);
+            else {
+                setAttr(el, 'role', 'combobox');
+                if (list)
+                    setAttr(el, 'aria-controls', list);
+                setAttr(el, 'aria-autocomplete', 'list');
+                this.features.add('listbox');
+            }
+        }
         const isTemplate = el.tagName === 'template';
         const valueB = (k, name) => {
             const r = this.expr(el, name, scope, { mode: 'value' });
@@ -516,6 +540,16 @@ class Compiler {
             if (!sn.some((a) => a.name.startsWith('data-sn-on-')))
                 this.report(el, 'data-sn-debounce', 'SN102', '`data-sn-debounce` needs a method attribute (`data-sn-get`, `-post`, …) or a `data-sn-on-*` handler on the same element', 0);
         }
+        // `data-sn-debounce-<event>`: only that event's handler waits
+        for (const a of sn) {
+            if (!a.name.startsWith('data-sn-debounce-'))
+                continue;
+            const event = a.name.slice('data-sn-debounce-'.length), ms = Number(a.value);
+            if (!Number.isFinite(ms) || ms < 0 || a.value.trim() === '')
+                this.report(el, a.name, 'SN401', `\`${a.name}\` takes milliseconds`, 0);
+            if (!has(`on-${event}`))
+                this.report(el, a.name, 'SN102', `\`${a.name}\` needs a \`data-sn-on-${event}\` handler on the same element`, 0);
+        }
         for (const a of sn) {
             if (!a.name.startsWith('data-sn-on-'))
                 continue;
@@ -525,8 +559,9 @@ class Compiler {
                 continue;
             }
             const r = this.expr(el, a.name, scope, { mode: 'handler', magic: ['$event'] });
+            const own = get(`debounce-${event}`), ms = own !== undefined ? Number(own) || 0 : handlerDebounce;
             if (r.ok)
-                node.b.push(binding({ k: 'on', n: event, f: this.fn(r.code), w: r.writes, ...(handlerDebounce > 0 ? { ms: handlerDebounce } : {}) }));
+                node.b.push(binding({ k: 'on', n: event, f: this.fn(r.code), w: r.writes, ...(ms > 0 ? { ms } : {}) }));
         }
         if (methods.length > 1)
             this.report(el, `data-sn-${methods[1]}`, 'SN102', 'an element can have only one method attribute', 0);
@@ -627,6 +662,61 @@ class Compiler {
         }
         return r;
     }
+    // ---- derived names
+    /**
+     * `data-sn-let="{ s: suggestions(q), n: s.length }"`: each name is a value expression, inlined
+     * where it is read; later names may use earlier ones.
+     */
+    lets(el, scope) {
+        const src = attr(el, 'data-sn-let') ?? '';
+        let obj;
+        try {
+            obj = parseExpressionAt(src, 0, { ecmaVersion: 'latest' });
+        }
+        catch (e) {
+            this.report(el, 'data-sn-let', 'SN401', e.message.replace(/ \(\d+:\d+\)$/, ''), e.pos ?? 0);
+            return scope;
+        }
+        if (obj.type !== 'ObjectExpression') {
+            this.report(el, 'data-sn-let', 'SN401', '`data-sn-let` takes an object literal: `{ name: expression, … }`', 0);
+            return scope;
+        }
+        for (const p of obj.properties) {
+            if (p.type !== 'Property' || p.computed || p.shorthand || p.key.type !== 'Identifier' || p.kind !== 'init' || p.method) {
+                this.report(el, 'data-sn-let', 'SN401', '`data-sn-let` entries are `name: expression`', p.start);
+                continue;
+            }
+            const name = p.key.name;
+            if (name.startsWith('$')) {
+                this.report(el, 'data-sn-let', 'SN401', 'names starting with `$` are reserved', p.key.start);
+                continue;
+            }
+            if (!this.checkNames(el, 'data-sn-let', scope, [name], p.key.start))
+                continue;
+            const v = p.value;
+            const r = this.expr(el, 'data-sn-let', scope, { mode: 'value' }, src.slice(v.start, v.end), v.start);
+            const entry = { name, code: r.inner, deps: r.deps, usesEl: r.usesEl, usesIndex: r.usesIndex, resource: r.resource };
+            if (this.check) {
+                this.frameOf.set(entry, this.check.frames.length);
+                this.check.frames.push({ kind: 'let', name, init: r.ok ? this.lastExpr : null, loc: this.locOf(el, 'data-sn-let', p.key.start) });
+            }
+            scope = { ...scope, lets: [...(scope.lets ?? []), entry] };
+        }
+        return scope;
+    }
+    /** A name declared here must not hide a let, or be hidden by one (SN209); false on a conflict. */
+    checkNames(el, attrName, scope, names, offset = 0) {
+        let ok = true;
+        for (const n of names) {
+            const isLet = (scope.lets ?? []).some((l) => l.name === n);
+            const other = attrName === 'data-sn-let' && (scope.loops.some((l) => l.name === n) || scope.states.some((s) => s.names.has(n)));
+            if (isLet || other) {
+                this.report(el, attrName, 'SN209', `\`${n}\` is already defined here${isLet ? ' by `data-sn-let`' : ''}; use another name`, offset);
+                ok = false;
+            }
+        }
+        return ok;
+    }
     // ---- check unit
     /** Adds type information to the expression `expr()` recorded last. */
     typeLast(info) {
@@ -647,7 +737,7 @@ class Compiler {
     }
     recordExpr(el, attrName, scope, o, src, shift, r) {
         const frames = [];
-        for (const f of [...scope.states, ...scope.loops]) {
+        for (const f of [...scope.states, ...scope.loops, ...(scope.lets ?? [])]) {
             const i = this.frameOf.get(f);
             if (i !== undefined && !frames.includes(i))
                 frames.push(i);
@@ -670,6 +760,8 @@ class Compiler {
     // ---- bindings
     attrBinding(el, node, scope) {
         const r = this.expr(el, 'data-sn-attr', scope, { mode: 'value', object: 'literal-keys' });
+        if (this.check)
+            this.typeLast({ returns: { kind: 'decl', name: 'Attrs' } });
         if (!r.entries)
             return;
         for (const e of r.entries) {
@@ -801,10 +893,18 @@ class Compiler {
         const then = fnOf('then', { mode: 'handler', magic: ['$event', '$result'] }, typed?.body != null ? { resultType: { kind: 'openapi', spec: typed.spec, schema: typed.body } }
             : call ? { resultType: { kind: 'call', name: call.name } } : undefined);
         const catch_ = fnOf('catch', { mode: 'handler', magic: ['$event', '$error'] });
+        const confirm = fnOf('confirm', { mode: 'value', magic: ['$event'] });
+        const encoding = get('encoding');
+        if (encoding !== undefined && encoding !== 'form' && encoding !== 'json')
+            this.report(el, 'data-sn-encoding', 'SN401', '`data-sn-encoding` is `json` (the default) or `form`', 0);
+        if (encoding !== undefined && method === 'call')
+            this.report(el, 'data-sn-encoding', 'SN102', '`data-sn-encoding` belongs to a method attribute; a call sends its own requests', 0);
         const def = {
             method: method.toUpperCase(), url, body: body.f, trigger, debounce, concurrency,
             optimistic: optimistic.f, then: then.f, catch: catch_.f, w: [...new Set([...then.w, ...catch_.w])].sort(), form: isForm,
             ...(call ? { call: { args: call.args, run: call.run } } : {}),
+            ...(confirm.f !== null ? { confirm: confirm.f } : {}),
+            ...(encoding === 'form' ? { enc: 'form' } : {}),
         };
         this.actions.push(def);
         node.b.push(binding({ k: 'on', n: trigger, x: this.actions.length - 1 }));
@@ -839,7 +939,8 @@ class Compiler {
                 frame.indexLoc = this.locOf(el, 'data-sn-for', value.indexOf(index, itemAt + item.length));
             this.check.frames.push(frame);
         }
-        const inner = { loops, states: scope.states };
+        this.checkNames(el, 'data-sn-for', scope, index ? [item, index] : [item]);
+        const inner = { ...scope, loops };
         t.key = null;
         t.keyFields = null;
         if (keySrc !== undefined) {
@@ -953,7 +1054,7 @@ class Compiler {
                     this.frameOf.set(loop, this.check.frames.length);
                     this.check.frames.push({ kind: 'loop', item: m[1], index: null, init: listExpr, loc: this.locOf(el, 'each', eachAttr.indexOf(m[1])) });
                 }
-                srcScope = { loops: [...ctx.scope.loops, loop], states: ctx.scope.states };
+                srcScope = { ...ctx.scope, loops: [...ctx.scope.loops, loop] };
                 if (list.ok)
                     each = { item: m[1], list: this.fn(list.code), ...(list.resource ? { of: list.resource } : {}) };
                 this.features.add('each');

package/dist/compiler/diagnostic-docs.js

@@ -59,6 +59,11 @@ export const DIAGNOSTIC_DOCS = {
         means: 'TypeScript found a type error in an expression. Reported by `sinter check`, `sinter({ typecheck: true })` and the editor integration.',
         fix: 'Fix the expression, or the type: `type` on `<sn-resource>`, the OpenAPI spec, or a JSDoc cast in `data-sn-state`.',
     },
+    SN209: {
+        example: '`s` is already defined here by `data-sn-let`; use another name',
+        means: '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.',
+        fix: 'Rename the let, or the state or loop variable.',
+    },
     SN301: {
         example: 'resource `mesages` is not declared on this page',
         means: 'A store call, `$meta` or embedded data (`data-sn-data`) names a resource that no `<sn-resource>` on the page or its partials declares.',
@@ -99,6 +104,11 @@ export const DIAGNOSTIC_DOCS = {
         means: 'The resource matched an operation in the OpenAPI spec, but its `items` or `total` path is not in the response schema.',
         fix: 'Fix the path in `items` or `total`, or the spec if the API changed.',
     },
+    SN309: {
+        example: 'no `<dialog id="compose-dialg">` on this page. Did you mean `compose-dialog`?',
+        means: '`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: {
         example: '`pgp.decrpyt` is not exported by the actions module. Did you mean `pgp.decrypt`?',
         means: '`data-sn-call` and `<sn-resource call>` name a function the actions module (`src/sinter.actions.js` or `.ts`) exports, directly or through `export * as ns`.',

package/dist/compiler/diagnostics.d.ts

@@ -28,6 +28,7 @@ export declare const CODES: {
     readonly SN206: 'unknown-namespace-member';
     readonly SN207: 'unsafe-sink';
     readonly SN208: 'type-error';
+    readonly SN209: 'name-conflict';
     readonly SN301: 'unknown-resource';
     readonly SN302: 'duplicate-resource';
     readonly SN303: 'unknown-meta-field';
@@ -36,6 +37,7 @@ export declare const CODES: {
     readonly SN306: 'include-cycle';
     readonly SN307: 'openapi-invalid';
     readonly SN308: 'unknown-schema-field';
+    readonly SN309: 'unknown-dialog';
     readonly SN310: 'unknown-action';
     readonly SN401: 'parse-error';
     readonly SN501: 'unused-resource';

package/dist/compiler/diagnostics.js

@@ -11,6 +11,7 @@ export const CODES = {
     SN206: 'unknown-namespace-member',
     SN207: 'unsafe-sink',
     SN208: 'type-error',
+    SN209: 'name-conflict',
     SN301: 'unknown-resource',
     SN302: 'duplicate-resource',
     SN303: 'unknown-meta-field',
@@ -19,6 +20,7 @@ export const CODES = {
     SN306: 'include-cycle',
     SN307: 'openapi-invalid',
     SN308: 'unknown-schema-field',
+    SN309: 'unknown-dialog',
     SN310: 'unknown-action',
     SN401: 'parse-error',
     SN501: 'unused-resource',

package/dist/compiler/expr.d.ts

@@ -19,6 +19,16 @@ export interface StateEntry {
     sid: number;
     names: Set<string>;
 }
+/** A `data-sn-let` name: a value expression inlined wherever the name is read. */
+export interface LetEntry {
+    name: string;
+    /** the compiled expression (without the `($) =>` wrapper) */
+    code: string;
+    deps: string[];
+    usesEl: boolean;
+    usesIndex: boolean;
+    resource: string | null;
+}
 export interface ResourceInfo {
     name: string;
     key: string[] | null;
@@ -30,6 +40,8 @@ export interface ResourceInfo {
 export interface Scope {
     loops: LoopEntry[];
     states: StateEntry[];
+    /** `data-sn-let` names, outer to inner */
+    lets?: LetEntry[];
 }
 export interface PageInfo {
     resources: Map<string, ResourceInfo>;
@@ -43,6 +55,8 @@ export interface PageInfo {
     usesNow: boolean;
     /** `:name` segments of the page's `data-sn-path` patterns */
     pathParams: Set<string>;
+    /** literal `id`s of the page's `<dialog>` elements, for `showModal()` and `close()` */
+    dialogs: Set<string>;
 }
 export interface ExprOptions {
     mode: Mode;
@@ -66,6 +80,8 @@ export interface ObjectEntry {
 export interface ExprResult {
     ok: boolean;
     code: string;
+    /** `code` without its `($) =>` wrapper (value expressions) */
+    inner: string;
     deps: string[];
     writes: string[];
     usesEl: boolean;

package/dist/compiler/expr.js

@@ -5,7 +5,7 @@ import * as acorn from 'acorn';
 import { didYouMean } from './diagnostics.js';
 const EVERYWHERE_MAGIC = ['$el', '$url', '$now', '$locale', '$meta'];
 export const ALL_MAGIC = ['$event', '$el', '$url', '$now', '$locale', '$result', '$error', '$meta'];
-export const STORE_FNS = ['refresh', 'upsert', 'patch', 'remove', 'page', 'close', 'reset', 'emit'];
+export const STORE_FNS = ['refresh', 'upsert', 'patch', 'remove', 'page', 'showModal', 'close', 'reset', 'emit'];
 export const BUILTIN_HELPERS = ['date', 'time', 'datetime', 'relative', 'number', 'bytes'];
 export const META_FIELDS = ['loading', 'error', 'loadedAt', 'pending', 'total', 'page', 'pages', 'from', 'to', 'hasPrev', 'hasNext'];
 const PAGE_FIELDS = ['page', 'pages', 'from', 'to', 'hasPrev', 'hasNext'];
@@ -96,7 +96,7 @@ export function analyze(src, scope, page, opts) {
         return fail();
     }
     function fail() {
-        return { ok: false, code: '() => undefined', deps: [], writes: [], usesEl: false, usesIndex: false, path: null, resource: null, ast: null };
+        return { ok: false, code: '() => undefined', inner: 'undefined', deps: [], writes: [], usesEl: false, usesIndex: false, path: null, resource: null, ast: null };
     }
     // ---- resolution
     function resolve(name, locals, offset, member) {
@@ -127,6 +127,12 @@ export function analyze(src, scope, page, opts) {
             }
         }
         if (!opts.payload) {
+            // a let cannot share a name with a loop or state in its scope (SN209), so lets resolve first
+            const lets = scope.lets ?? [];
+            for (let i = lets.length - 1; i >= 0; i--) {
+                if (lets[i].name === name)
+                    return { kind: 'let', entry: lets[i] };
+            }
             for (let i = scope.loops.length - 1; i >= 0; i--) {
                 if (scope.loops[i].name === name)
                     return { kind: 'loop', entry: scope.loops[i] };
@@ -170,7 +176,7 @@ export function analyze(src, scope, page, opts) {
             return { kind: 'payload' };
         }
         const candidates = [
-            ...scope.loops.map((l) => l.name), ...scope.states.flatMap((s) => [...s.names]),
+            ...(scope.lets ?? []).map((l) => l.name), ...scope.loops.map((l) => l.name), ...scope.states.flatMap((s) => [...s.names]),
             ...page.resources.keys(), ...page.helpers, ...page.namespaces.keys(), ...STORE_FNS, ...BUILTIN_HELPERS,
         ];
         report('SN201', `\`${name}\` is not defined here.${didYouMean(name, candidates)}`, offset);
@@ -183,6 +189,7 @@ export function analyze(src, scope, page, opts) {
             case 'global':
             case 'helper': return name;
             case 'loop': return `$.${name}`;
+            case 'let': return `(${res.entry.code})`;
             case 'state': return `$.$s${sid}.${name}`;
             case 'resource': return `$.$r.${name}`;
             case 'magic': return `$.${name}`;
@@ -202,6 +209,7 @@ export function analyze(src, scope, page, opts) {
                 return { segs: res.entry.alias ? [...res.entry.alias] : null, resource: res.entry.resource };
             case 'local':
                 return { segs: res.info.alias ? [...res.info.alias] : null, resource: res.info.resource };
+            case 'let': return { segs: null, resource: res.entry.resource };
             default: return { segs: null, resource: null };
         }
     }
@@ -315,6 +323,15 @@ export function analyze(src, scope, page, opts) {
             sid = res.sid;
         if (res.kind === 'loop' && res.entry.kind === 'index')
             usesIndex = true;
+        if (res.kind === 'let') {
+            // the inlined expression reads what the let reads
+            for (const d of res.entry.deps)
+                deps.add(d);
+            if (res.entry.usesEl)
+                usesEl = true;
+            if (res.entry.usesIndex)
+                usesIndex = true;
+        }
         const text = emitName(n.name, res, sid);
         if (text !== n.name || shorthand)
             edits.push({ start: n.start, end: n.end, text: shorthand ? `${n.name}: ${text}` : text });
@@ -472,6 +489,10 @@ export function analyze(src, scope, page, opts) {
             report('SN203', 'only state variables and their properties can be assigned', at);
             return;
         }
+        if (cp.res.kind === 'let') {
+            report('SN203', `\`${cp.root}\` is derived (\`data-sn-let\`) and cannot be assigned; assign the state it is computed from`, at);
+            return;
+        }
         if (cp.resource) {
             report('SN205', `\`${src.slice(target.start, target.end)}\` mutates a resource. Use \`patch('${cp.resource}', …, {…})\``, at, 'resources are read-only in expressions; copy with structuredClone() to edit');
             return;
@@ -570,6 +591,15 @@ export function analyze(src, scope, page, opts) {
             return;
         }
         const first = n.arguments[0];
+        if (name === 'showModal' || (name === 'close' && first)) {
+            if (!first || first.type !== 'Literal' || typeof first.value !== 'string') {
+                report('SN309', `\`${name}()\` takes the dialog's \`id\` as a string literal`, n.start);
+            }
+            else if (!page.dialogs.has(first.value)) {
+                report('SN309', `no \`<dialog id="${first.value}">\` on this page.${didYouMean(first.value, page.dialogs)}`, first.start);
+            }
+            return;
+        }
         if (['refresh', 'upsert', 'patch', 'remove', 'page'].includes(name)) {
             if (!first || first.type !== 'Literal' || typeof first.value !== 'string') {
                 report('SN301', `\`${name}()\` takes the resource name as a string literal`, n.start);
@@ -842,7 +872,7 @@ export function analyze(src, scope, page, opts) {
             }
         }
     }
-    return { ok, code, deps: [...deps].sort(), writes: [...writes].sort(), usesEl, usesIndex, entries, path, resource, ast, ...(opts.payload ? { payloadNames: [...payloadNames].sort(), payloadStates: [...payloadStates].sort() } : {}) };
+    return { ok, code, inner: out, deps: [...deps].sort(), writes: [...writes].sort(), usesEl, usesIndex, entries, path, resource, ast, ...(opts.payload ? { payloadNames: [...payloadNames].sort(), payloadStates: [...payloadStates].sort() } : {}) };
 }
 export function applyEdits(src, edits) {
     const sorted = [...edits].sort((a, b) => b.start - a.start || (b.end - b.start) - (a.end - a.start));

package/dist/compiler/vocabulary.d.ts

@@ -5,6 +5,7 @@ export interface AttrDoc {
 }
 export declare const ATTRIBUTES: AttrDoc[];
 export declare const ON_DOC: AttrDoc;
+export declare const DEBOUNCE_ON_DOC: AttrDoc;
 export declare const ELEMENTS: Array<{
     name: string;
     attrs: string[];

package/dist/compiler/vocabulary.js

@@ -2,6 +2,7 @@
 // The compiler, llms.txt and html-custom-data.json are all built from it.
 export const ATTRIBUTES = [
     { name: 'state', value: 'object literal', doc: 'declares local reactive state for the element and its subtree' },
+    { name: 'let', value: 'object literal {name: expression}', doc: 'derived names for the element and its subtree, computed where they are read; later names may use earlier ones' },
     { name: 'text', value: 'value expression', doc: 'sets textContent; never HTML' },
     { name: 'attr', value: 'object literal {href: …}', doc: 'literal keys; null/false removes, true sets empty; URL values are checked' },
     { name: 'class', value: 'object literal {unread: …}', doc: 'toggles each class' },
@@ -13,6 +14,7 @@ export const ATTRIBUTES = [
     { name: 'key', value: 'value expression', doc: 'row identity; defaults to the resource key or object identity' },
     { name: 'if', value: 'value expression', doc: 'renders a <template> while truthy' },
     { name: 'else', value: '', doc: 'on a <template> directly after an if template' },
+    { name: 'listbox', value: 'id of the suggestion list, or empty', doc: '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`' },
     { name: 'persist', value: 'storage key', doc: 'persists the model or state in localStorage under sn:' },
     { name: 'get', value: 'URL template', doc: 'GET action; latest wins' },
     { name: 'post', value: 'URL template', doc: 'POST action' },
@@ -26,11 +28,14 @@ export const ATTRIBUTES = [
     { name: 'concurrency', value: 'block | queue | latest', doc: 'mutations only; default block for forms, queue otherwise' },
     { name: 'optimistic', value: 'handler expression', doc: 'patch/upsert/remove calls applied before the request, rolled back on failure' },
     { name: 'then', value: 'handler expression', doc: 'runs after a 2xx response; $result = parsed body' },
-    { name: 'catch', value: 'handler expression', doc: 'runs after an error; $error = {status, body, message}' },
+    { name: 'catch', value: 'handler expression', doc: 'runs after an error; $error = {status, body, message, detail}' },
+    { name: 'confirm', value: 'value expression', doc: 'asks this question before the action runs (configure({ confirm }), window.confirm by default); no question when falsy' },
+    { name: 'encoding', value: 'json | form', doc: 'form: the body (data-sn-body, arrays as repeated keys, or the form) goes as application/x-www-form-urlencoded' },
     { name: 'path', value: 'URL patterns /a/:b …', doc: 'on <html>: the path shapes this page is served for; `:name` segments appear read-only in $url' },
     { name: 'data', value: 'resource name', doc: 'on <script type="application/json"> in <head>: initial data for a resource' },
 ];
 export const ON_DOC = { name: 'on-<event>', value: 'handler expression', doc: 'plain event handler, no request; e.g. data-sn-on-click' };
+export const DEBOUNCE_ON_DOC = { name: 'debounce-<event>', value: 'milliseconds', doc: 'delays only that event\'s data-sn-on-<event> handler (it runs with the last event); e.g. data-sn-debounce-input' };
 export const ELEMENTS = [
     { name: 'sn-resource', attrs: ['name', 'src', 'call', 'each', 'key', 'items', 'total', 'order', 'when', 'paginate', 'page-size', 'size-param', 'cursor', 'direction-param', 'direction-values', 'page-param', 'offset-param', 'type', 'cache'], doc: 'a named, page-wide cache of server data; `cache` (or `cache="10m"`) shows the data from the last page load at once, then revalidates' },
     { name: 'sn-sync', attrs: ['src'], doc: 'one server event stream' },

package/dist/ir.d.ts

@@ -134,6 +134,10 @@ export interface ActionDef {
     w: string[];
     /** element is a form (serialize, disable in block mode) */
     form: boolean;
+    /** `data-sn-confirm`: the question asked before the action runs (none when it is falsy) */
+    confirm?: number;
+    /** `data-sn-encoding="form"`: the body goes as application/x-www-form-urlencoded */
+    enc?: 'form';
 }
 export interface IR {
     v: 1;

package/dist/listbox.d.ts

@@ -0,0 +1,3 @@
+import type { Feature } from './runtime/app.js';
+declare const listbox: Feature;
+export default listbox;

package/dist/listbox.js

@@ -0,0 +1,66 @@
+/** the input's list: `aria-controls`, else the nearest listbox around it */
+const listOf = (input) => {
+    const id = input.getAttribute('aria-controls');
+    if (id)
+        return input.ownerDocument.getElementById(id);
+    for (let p = input.parentElement; p; p = p.parentElement) {
+        const list = p.querySelector('[role="listbox"]');
+        if (list)
+            return list;
+    }
+    return null;
+};
+const options = (input) => {
+    const list = listOf(input);
+    if (!list || list.closest('[hidden]'))
+        return [];
+    return [...list.querySelectorAll('[role="option"]')].filter((o) => !o.closest('[hidden]'));
+};
+const mark = (all, next) => {
+    for (const o of all)
+        o.setAttribute('aria-selected', String(o == next));
+    next?.scrollIntoView?.({ block: 'nearest' });
+};
+const listbox = {
+    name: 'listbox',
+    install(app) {
+        const root = app.root;
+        root.addEventListener('keydown', (e) => {
+            const input = e.target.closest?.('[role="combobox"]');
+            if (!input || e.isComposing)
+                return;
+            const all = options(input);
+            if (!all.length)
+                return;
+            const at = all.findIndex((o) => o.getAttribute('aria-selected') == 'true');
+            const key = e.key;
+            if (key == 'ArrowDown' || key == 'ArrowUp') {
+                e.preventDefault();
+                mark(all, key == 'ArrowDown' ? all[Math.min(at + 1, all.length - 1)] : at > 0 ? all[at - 1] : null);
+            }
+            else if ((key == 'Enter' && at >= 0) || (key == 'Tab' && (at >= 0 || all.length == 1))) {
+                e.preventDefault();
+                mark(all, null);
+                all[Math.max(at, 0)].click();
+            }
+            else if (key == 'Escape') {
+                e.preventDefault();
+                mark(all, null);
+                input.dispatchEvent(new CustomEvent('dismiss', { bubbles: true }));
+            }
+        });
+        root.addEventListener('input', (e) => {
+            const input = e.target.closest?.('[role="combobox"]');
+            if (input)
+                mark(options(input), null);
+        });
+        root.addEventListener('mousedown', (e) => {
+            // only in lists that belong to a combobox: keep the focus in the input
+            const option = e.target.closest?.('[role="option"]');
+            const list = option?.closest('[role="listbox"]');
+            if (list && [...root.querySelectorAll('[role="combobox"]')].some((c) => listOf(c) == list))
+                e.preventDefault();
+        });
+    },
+};
+export default listbox;

package/dist/runtime/app.d.ts

@@ -81,6 +81,8 @@ export interface App {
     readonly ir: IR;
     readonly fns: Fn[];
     readonly env: Env;
+    /** the element or document this instance is mounted on */
+    readonly root: Document | Element;
     readonly req: RequestLayer;
     /** the base scope: resources, status, magic names */
     readonly page: any;
@@ -149,4 +151,9 @@ export declare function withParams(url: string, params: Record<string, string> |
 /** Indexes (into `seq`) of a longest increasing subsequence, ignoring -1 entries. */
 export declare function lis(seq: number[]): Set<number>;
 /** Serializes a form's named controls to nested JSON, or FormData if it has a file input. */
+/**
+ * A body as form fields (`data-sn-encoding="form"`): a form's own fields, or an object's keys with
+ * arrays as repeated keys; null and undefined values are left out. Files stay multipart.
+ */
+export declare function formBody(body: unknown): URLSearchParams | FormData | null;
 export declare function serialize(form: HTMLFormElement): unknown;

package/dist/runtime/app.js

@@ -55,6 +55,8 @@ export function mount(root, o) {
     const types = new Set(), selects = new Set(), deferred = new Set();
     const listeners = new Map(), cleanups = [];
     const shared = new Map();
+    /** `showModal(id)`, `close(id)`: the dialog of this mount root with that id */
+    const dialog = (id) => [...root.querySelectorAll('dialog')].find((d) => d.id === id);
     const rootRbs = [], rootScopes = [], found = new Map();
     let dirty = [], cur = [], scheduled = false, flushing = false, round = 0;
     const res = (name) => {
@@ -90,7 +92,12 @@ export function mount(root, o) {
         }
     }
     /** a failed call: SinterErrors as they are, anything else with status null */
-    const callError = (e) => (e instanceof SinterError ? e : new SinterError(null, e, e?.message || String(e)));
+    const callError = (e) => {
+        if (e instanceof SinterError)
+            return e;
+        const detail = (e instanceof Error ? e.message : typeof e == 'string' ? e : '') || null;
+        return new SinterError(null, e, detail ?? String(e), detail);
+    };
     /** Per flush round: how dirty paths reach a template's rows (0 not, 1 only marked elements, 2 any row). */
     let rowHits = new Map();
     /**
@@ -142,7 +149,7 @@ export function mount(root, o) {
         return false;
     };
     const app = {
-        ir, fns, env, req, transport: o.transport ?? (() => undefined), ext: {},
+        ir, fns, env, req, root, transport: o.transport ?? (() => undefined), ext: {},
         beforeFlush: [], afterFlush: [], onListen: [], states: [], busy: 0,
         get isDirty() { return dirty.length > 0 || scheduled; },
         dev: false,
@@ -267,12 +274,14 @@ export function mount(root, o) {
             } };
         },
         storeFns: (el) => ({
+            showModal: (id) => { const d = dialog(id); if (d && !d.open)
+                d.showModal(); },
             refresh: (n) => res(n).refetch(),
             upsert: forward('upsert'),
             patch: forward('patch'),
             remove: forward('remove'),
             page: (n, t) => app.ext.paginate.page(n, t),
-            close: () => el?.closest('dialog')?.close(),
+            close: (id) => (id ? dialog(id) : el?.closest('dialog'))?.close(),
             reset: () => {
                 const form = el?.closest('form');
                 if (!form)
@@ -926,27 +935,42 @@ export function mount(root, o) {
                 body = fns[a.call.args](s);
             else {
                 url = app.url(a.url, s);
-                body = a.body != null ? fns[a.body](s) : a.form && !get && a.method != 'DELETE' ? serialize(rb.el) : undefined;
+                const fields = a.form && !get && a.method != 'DELETE';
+                body = a.body != null ? fns[a.body](s) : fields ? (a.enc == 'form' ? formFields(rb.el) : serialize(rb.el)) : undefined;
+                if (a.enc == 'form')
+                    body = formBody(body);
             }
         }
         catch (err) {
             return unhandled(toError(err), rb.el);
         }
-        const drop = a.optimistic != null ? app.ext.optimistic.begin(a.optimistic, s) : () => { };
-        if (get) {
-            st.c?.abort();
-            return void send(rb, a, st, url, body, drop, (st.c = new AbortController()));
-        }
-        const run = () => void send(rb, a, st, url, body, drop);
-        if (!st.n)
-            run();
-        else if (a.concurrency == 'latest') {
-            st.w ? st.w.drop() : app.busy++;
-            st.w = { run, drop };
+        // a question first: the action runs only when the user agrees
+        const question = a.confirm != null ? fns[a.confirm](s) : null;
+        if (question) {
+            const yes = config.confirm(String(question));
+            if (yes instanceof Promise)
+                return void yes.then((y) => y && go());
+            if (!yes)
+                return;
         }
-        else {
-            app.busy++;
-            st.q.push(run);
+        go();
+        function go() {
+            const drop = a.optimistic != null ? app.ext.optimistic.begin(a.optimistic, s) : () => { };
+            if (get) {
+                st.c?.abort();
+                return void send(rb, a, st, url, body, drop, (st.c = new AbortController()));
+            }
+            const run = () => void send(rb, a, st, url, body, drop);
+            if (!st.n)
+                run();
+            else if (a.concurrency == 'latest') {
+                st.w ? st.w.drop() : app.busy++;
+                st.w = { run, drop };
+            }
+            else {
+                app.busy++;
+                st.q.push(run);
+            }
         }
     }
     async function send(rb, a, st, url, body, drop, c) {
@@ -1229,6 +1253,47 @@ export function lis(seq) {
     return keep;
 }
 /** Serializes a form's named controls to nested JSON, or FormData if it has a file input. */
+/**
+ * A body as form fields (`data-sn-encoding="form"`): a form's own fields, or an object's keys with
+ * arrays as repeated keys; null and undefined values are left out. Files stay multipart.
+ */
+export function formBody(body) {
+    if (body == null)
+        return null;
+    if (body instanceof FormData) {
+        const out = new URLSearchParams();
+        for (const [k, v] of body) {
+            if (typeof v != 'string')
+                return body;
+            out.append(k, v);
+        }
+        return out;
+    }
+    if (body instanceof URLSearchParams)
+        return body;
+    const out = new URLSearchParams();
+    for (const [k, v] of Object.entries(body)) {
+        for (const x of Array.isArray(v) ? v : [v])
+            if (x != null)
+                out.append(k, typeof x == 'object' ? JSON.stringify(x) : String(x));
+    }
+    return out;
+}
+/** A form's fields as browsers submit them; with a file input, multipart. */
+function formFields(form) {
+    const out = new URLSearchParams();
+    for (const c of form.elements) {
+        if (!c.name || c.disabled || /^(submit|button|reset|image|fieldset|output)$/.test(c.type))
+            continue;
+        if (c.type == 'file')
+            return new FormData(form);
+        if ((c.type == 'checkbox' || c.type == 'radio') && !c.checked)
+            continue;
+        for (const v of c.type == 'select-multiple' ? [...c.selectedOptions].map((o) => o.value) : [c.value])
+            out.append(c.name, v);
+    }
+    return out;
+}
 export function serialize(form) {
     const controls = [...form.elements];
     if (controls.some((c) => c.type == 'file'))

package/dist/runtime/config.d.ts

@@ -13,6 +13,8 @@ export interface Config {
     origins: string[];
     /** the transport for a `<sn-sync>` stream URL; `undefined` (or no function) means EventSource */
     transport: ((url: string) => Transport | undefined) | null;
+    /** `data-sn-confirm`: asks the question; the action runs on true (window.confirm by default) */
+    confirm: (question: string) => boolean | Promise<boolean>;
     env: Env;
 }
 export declare const config: Config;
@@ -23,7 +25,12 @@ export declare function configure(options: Partial<Omit<Config, 'env'>> & {
 export declare class SinterError extends Error {
     readonly status: number | null;
     readonly body: unknown;
-    constructor(status: number | null, body: unknown, message: string);
+    readonly detail: string | null;
+    /**
+     * @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: number | null, body: unknown, message: string, detail?: string | null);
 }
 /** page-load cache entries (`cache` on `<sn-resource>`), in sessionStorage */
 export declare const CACHE_PREFIX = "sn:c:";

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/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,6 +44,10 @@ 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');
@@ -71,7 +75,8 @@ 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;
     }

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

@@ -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.
+
+**Fix:** Rename the let, or the state or loop variable.
+
 ## 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.0",
   "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": {