@tiaforge-ui/sinter 0.1.0 → 0.3.0

package/dist/compiler/compile.js

@@ -1,13 +1,14 @@
 // The compiler: one pure, deterministic function from annotated HTML to a
 // rewritten page plus its IR and function table.
 import * as parse5 from 'parse5';
+import { parseExpressionAt } from 'acorn';
 import { didYouMean, severityOf } from './diagnostics.js';
 import { analyze } from './expr.js';
 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;
@@ -23,6 +24,7 @@ class Compiler {
     diagnostics = [];
     files = new Set();
     fns = [];
+    fnIndex = new Map();
     origins = new WeakMap();
     lineStarts = new Map();
     page;
@@ -35,6 +37,8 @@ class Compiler {
     remove = [];
     embedded = new Map();
     features = new Set();
+    /** action functions called by the page (`archive`, `pgp.decrypt`) */
+    calls = new Set();
     nextId = 0;
     nextSid = 0;
     check;
@@ -50,7 +54,8 @@ class Compiler {
             ns.set(k, new Set(v.members));
         this.page = {
             resources: new Map(), helpers: new Set(opts.helpers.names), namespaces: ns,
-            usedHelpers: new Set(), usedNs: new Map(), usesNow: false, pathParams: new Set(),
+            actions: new Set([...(opts.actions?.names ?? []), ...Object.keys(opts.actions?.namespaces ?? {})]),
+            usedHelpers: new Set(), usedNs: new Map(), usesNow: false, pathParams: new Set(), dialogs: new Set(),
         };
     }
     run(html) {
@@ -95,8 +100,8 @@ class Compiler {
         return {
             html: parse5.serialize(doc),
             ir, fns: this.fns,
-            features: [...(this.opts.dev ? ['dev'] : []), ...['sse', 'optimistic', 'paginate', 'persist', 'cache'].filter((f) => this.features.has(f))],
-            helpers: { user, builtin }, namespaces,
+            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 } : {}),
         };
@@ -153,6 +158,93 @@ class Compiler {
         return i;
     }
     /** `inExpr`: the offset points into an expression; otherwise offset 0 is about the whole attribute (or element) */
+    /**
+     * `data-sn-call` / `call`: exactly one call of an actions module function, `name(args)` or
+     * `ns.name(args)`. Compiles to two table entries: the arguments as one array expression, and a
+     * runner that calls the imported function with them and the context.
+     */
+    callExpr(el, attrName, scope, deps, magic) {
+        const text = attr(el, attrName) ?? '';
+        const shape = `\`${attrName}\` is one call of an action, e.g. \`pgp.decrypt(msg)\``;
+        let ast;
+        try {
+            ast = parseExpressionAt(text, 0, { ecmaVersion: 'latest' });
+        }
+        catch (e) {
+            this.report(el, attrName, 'SN401', `\`${attrName}\`: ${e.message.replace(/ \(\d+:\d+\)$/, '')}`, e.pos ?? 0);
+            return null;
+        }
+        if (ast.type !== 'CallExpression' || ast.optional || ast.end !== text.trimEnd().length) {
+            this.report(el, attrName, 'SN401', shape, 0);
+            return null;
+        }
+        const acts = this.opts.actions ?? { module: null, names: [], namespaces: {} };
+        const callee = ast.callee;
+        const all = [...acts.names, ...Object.entries(acts.namespaces).flatMap(([ns, m]) => m.members.map((x) => `${ns}.${x}`))];
+        let name, local;
+        if (callee.type === 'Identifier') {
+            name = callee.name;
+            local = `$a$${name}`;
+            if (!acts.names.includes(name)) {
+                this.report(el, attrName, 'SN310', `\`${name}\` is not exported by the actions module.${didYouMean(name, all)}`, callee.start);
+                return null;
+            }
+        }
+        else if (callee.type === 'MemberExpression' && !callee.computed && callee.object.type === 'Identifier' && callee.property.type === 'Identifier') {
+            name = `${callee.object.name}.${callee.property.name}`;
+            local = `$a$${callee.object.name}$${callee.property.name}`;
+            if (!acts.namespaces[callee.object.name]?.members.includes(callee.property.name)) {
+                this.report(el, attrName, 'SN310', `\`${name}\` is not exported by the actions module.${didYouMean(name, all)}`, callee.start);
+                return null;
+            }
+        }
+        else {
+            this.report(el, attrName, 'SN401', shape, callee.start);
+            return null;
+        }
+        const open = text.indexOf('(', callee.end);
+        const r = this.expr(el, attrName, scope, { mode: 'value', ...(magic ? { magic } : {}) }, `[${text.slice(open + 1, ast.end - 1)}]`, open);
+        if (this.check)
+            this.typeLast({ returns: { kind: 'call', name, args: true } });
+        if (deps)
+            for (const d of r.deps)
+                deps.add(d);
+        if (!r.ok)
+            return null;
+        this.calls.add(name);
+        return { args: this.fn(r.code), run: this.fn(`($a, $c) => ${local}(...$a, $c)`), name };
+    }
+    /** `direction-values="{prev: 'backward', next: 'forward'}"`: static data, string values for known directions only */
+    directionValues(el) {
+        const text = attr(el, 'direction-values');
+        const DIRS = ['first', 'prev', 'next', 'last'];
+        const fail = (message, offset = 0) => { this.report(el, 'direction-values', 'SN401', message, offset); return null; };
+        let ast;
+        try {
+            ast = parseExpressionAt(text, 0, { ecmaVersion: 'latest' });
+        }
+        catch (e) {
+            return fail(`\`direction-values\`: ${e.message.replace(/ \(\d+:\d+\)$/, '')}`, e.pos ?? 0);
+        }
+        if (ast.type !== 'ObjectExpression' || ast.end !== text.trimEnd().length) {
+            return fail("`direction-values` is an object literal of strings, e.g. `{prev: 'backward', next: 'forward'}`");
+        }
+        const out = {};
+        for (const p of ast.properties) {
+            if (p.type !== 'Property' || p.computed || p.kind !== 'init' || p.method || p.shorthand) {
+                return fail("`direction-values` is an object literal of strings, e.g. `{prev: 'backward', next: 'forward'}`", p.start);
+            }
+            const key = p.key.type === 'Identifier' ? p.key.name : p.key.type === 'Literal' ? String(p.key.value) : '';
+            if (!DIRS.includes(key)) {
+                return fail(`\`${key}\` is not a direction; directions are \`first\`, \`prev\`, \`next\` and \`last\`.${didYouMean(key, DIRS)}`, p.key.start);
+            }
+            if (p.value.type !== 'Literal' || typeof p.value.value !== 'string') {
+                return fail(`the value for \`${key}\` must be a string literal`, p.value.start);
+            }
+            out[key] = p.value.value;
+        }
+        return out;
+    }
     report(el, attr, code, message, offset, hint, inExpr = false) {
         const origin = (el && this.origins.get(el)) || { file: this.opts.file, src: '', chain: [] };
         const base = el ? this.valueOffset(el, attr) : 0;
@@ -229,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))
@@ -251,10 +343,17 @@ class Compiler {
                 const key = attr(child, 'key');
                 const paginate = attr(child, 'paginate');
                 const info = { name, key: key ? key.split(',').map((s) => s.trim()).filter(Boolean) : null, paginate: paginate ?? null, used: false };
+                if (paginate === 'keyset' && attr(child, 'offset-param') != null)
+                    info.jumps = true;
                 this.page.resources.set(name, info);
                 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);
@@ -318,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);
         }
@@ -352,6 +451,9 @@ class Compiler {
             return null;
         }
         const node = { tag: el.tagName, p: ctx.stateIdx, b: [] };
+        const inDialog = ctx.dialog || el.tagName === 'dialog';
+        if (inDialog)
+            node.dl = 1;
         const nodeIdx = ctx.list.length;
         let scope = ctx.scope;
         let result = null;
@@ -369,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' });
@@ -408,6 +529,27 @@ class Compiler {
             this.model(el, node, scope, get('persist'));
         else if (has('persist') && !has('state'))
             this.report(el, 'data-sn-persist', 'SN102', '`data-sn-persist` needs `data-sn-model` or `data-sn-state` on the same element', 0);
+        const methods = METHODS.filter((m) => has(m));
+        const isCall = has('call');
+        // without a method, `data-sn-debounce` delays the element's own handlers
+        let handlerDebounce = 0;
+        if (!methods.length && !isCall && has('debounce')) {
+            handlerDebounce = Number(get('debounce'));
+            if (!Number.isFinite(handlerDebounce) || handlerDebounce < 0)
+                this.report(el, 'data-sn-debounce', 'SN401', '`data-sn-debounce` takes milliseconds', 0);
+            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;
@@ -417,17 +559,21 @@ 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 }));
+                node.b.push(binding({ k: 'on', n: event, f: this.fn(r.code), w: r.writes, ...(ms > 0 ? { ms } : {}) }));
         }
-        const methods = METHODS.filter((m) => has(m));
         if (methods.length > 1)
             this.report(el, `data-sn-${methods[1]}`, 'SN102', 'an element can have only one method attribute', 0);
+        if (methods.length && isCall)
+            this.report(el, 'data-sn-call', 'SN102', 'an element has one action: a method attribute or `data-sn-call`, not both', 0);
         if (methods.length)
             this.action(el, node, scope, methods[0], get);
+        else if (isCall)
+            this.action(el, node, scope, 'call', get);
         else
             for (const n of ACTION_ONLY)
-                if (has(n))
+                if (has(n) && n !== 'debounce')
                     this.report(el, `data-sn-${n}`, 'SN102', `\`data-sn-${n}\` needs a method attribute (\`data-sn-get\`, \`-post\`, …) on the same element`, 0);
         // templates
         let content = null;
@@ -476,7 +622,7 @@ class Compiler {
         }
         else {
             this.walkChildren(el, {
-                ...ctx, scope,
+                ...ctx, scope, dialog: inDialog,
                 stateIdx: node.state !== undefined && hasDirectives ? nodeIdx : ctx.stateIdx,
                 path: ctx.tid >= 0 ? [...ctx.path, index] : ctx.path,
             });
@@ -495,9 +641,12 @@ class Compiler {
         this.templates.push({ id: tid, nodes: [] });
         return tid;
     }
+    /** Index of a function in the page's table; identical code shares one entry (one compile in the engine). */
     fn(code) {
-        this.fns.push(code);
-        return this.fns.length - 1;
+        let i = this.fnIndex.get(code);
+        if (i === undefined)
+            this.fnIndex.set(code, (i = this.fns.push(code) - 1));
+        return i;
     }
     expr(el, attrName, scope, o, value, shift = 0) {
         const src = value ?? attr(el, attrName) ?? '';
@@ -513,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) {
@@ -533,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);
@@ -541,7 +745,7 @@ class Compiler {
         let event = null;
         if (attrName.startsWith('data-sn-on-'))
             event = attrName.slice('data-sn-on-'.length);
-        else if (o.mode !== 'value') {
+        else if (o.mode !== 'value' || o.magic?.includes('$event')) {
             event = attr(el, 'data-sn-trigger') ?? (el.tagName === 'form' ? 'submit' : FORM_CONTROLS.has(el.tagName) ? 'change' : 'click');
         }
         const e = {
@@ -549,13 +753,15 @@ class Compiler {
             result: attrName === 'data-sn-then', error: attrName === 'data-sn-catch',
         };
         if (o.payload)
-            e.payload = { names: r.payloadNames ?? [], type: null };
+            e.payload = { names: r.payloadNames ?? [], type: null, ...(r.payloadStates?.length ? { states: r.payloadStates } : {}) };
         this.check.exprs.push(e);
         return this.check.exprs.length - 1;
     }
     // ---- 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) {
@@ -649,7 +855,11 @@ class Compiler {
         node.b.push(b);
     }
     action(el, node, scope, method, get) {
-        const url = this.urlTemplate(el, `data-sn-${method}`, scope);
+        // arguments and body are taken when the trigger fires, so they see its event
+        const call = method === 'call' ? this.callExpr(el, 'data-sn-call', scope, undefined, ['$event']) : null;
+        if (method === 'call' && get('body') !== undefined)
+            this.report(el, 'data-sn-body', 'SN102', '`data-sn-body` belongs to a method attribute; a call takes its arguments in `data-sn-call`', 0);
+        const url = method === 'call' ? [] : this.urlTemplate(el, `data-sn-${method}`, scope);
         const tag = el.tagName;
         const isForm = tag === 'form';
         const trigger = get('trigger') ?? (isForm ? 'submit' : FORM_CONTROLS.has(tag) ? 'change' : 'click');
@@ -674,17 +884,27 @@ class Compiler {
             return { f: r.ok ? this.fn(r.code) : null, w: r.writes };
         };
         // with OpenAPI specs: the body must fit the request schema, `$result` gets the response's type
-        const op = this.check && this.opts.openapi?.length ? matchOperation(this.opts.openapi, url, method) : null;
+        const op = method !== 'call' && this.check && this.opts.openapi?.length ? matchOperation(this.opts.openapi, url, method) : null;
         const typed = op && 'spec' in op ? op : null;
-        const body = fnOf('body', { mode: 'value' }, typed?.request != null ? { returns: { kind: 'openapi', spec: typed.spec, schema: typed.request } } : undefined);
+        const body = fnOf('body', { mode: 'value', magic: ['$event'] }, typed?.request != null ? { returns: { kind: 'openapi', spec: typed.spec, schema: typed.request } } : undefined);
         const optimistic = fnOf('optimistic', { mode: 'optimistic' });
         if (optimistic.f !== null)
             this.features.add('optimistic');
-        const then = fnOf('then', { mode: 'handler', magic: ['$event', '$result'] }, typed?.body != null ? { resultType: { kind: 'openapi', spec: typed.spec, schema: typed.body } } : undefined);
+        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 }));
@@ -719,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) {
@@ -803,10 +1024,50 @@ class Compiler {
                 this.report(el, a.name, 'SN101', `\`${a.name}\` is not an attribute of \`<sn-resource>\`.${didYouMean(a.name, RESOURCE_ATTRS)}`, 0);
         }
         const info = this.page.resources.get(name);
-        if (attr(el, 'src') == null)
-            this.report(el, null, 'SN401', `resource \`${name}\` needs a \`src\``, 0);
+        const hasCall = attr(el, 'call') != null;
+        if (hasCall && attr(el, 'src') != null)
+            this.report(el, 'call', 'SN102', 'a resource loads from `src` or from `call`, not both', 0);
+        else if (!hasCall && attr(el, 'src') == null)
+            this.report(el, null, 'SN401', `resource \`${name}\` needs a \`src\` (or a \`call\`)`, 0);
+        if (hasCall) {
+            for (const a of ['paginate', 'each', 'cache']) {
+                if (attr(el, a) != null)
+                    this.report(el, a, 'SN401', `\`${a}\` does not combine with \`call\` in v0.2`, 0);
+            }
+        }
         const deps = new Set();
-        const src = this.urlTemplate(el, 'src', ctx.scope, {}, deps);
+        // `each="a in accounts"`: src is evaluated once per list item, with the item in scope
+        let each;
+        let srcScope = ctx.scope;
+        const eachAttr = attr(el, 'each');
+        if (eachAttr != null) {
+            const m = /^\s*([A-Za-z_$][\w$]*)\s+in\s+/.exec(eachAttr);
+            if (!m)
+                this.report(el, 'each', 'SN401', '`each` takes `item in list`, e.g. `a in accounts`', 0);
+            else {
+                const list = this.expr(el, 'each', ctx.scope, { mode: 'value' }, eachAttr.slice(m[0].length), m[0].length);
+                const listExpr = this.lastExpr;
+                for (const d of list.deps)
+                    deps.add(d);
+                const loop = { name: m[1], kind: 'item', alias: null, resource: list.resource };
+                if (this.check) {
+                    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 = { ...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');
+                if (!info.key)
+                    this.report(el, 'each', 'SN401', 'an `each` resource is a collection: it needs `key`, with a field that tells the sources apart', 0);
+                for (const a of ['paginate', 'total', 'cache']) {
+                    if (attr(el, a) != null)
+                        this.report(el, a, 'SN401', `\`${a}\` does not combine with \`each\`: the items come from several requests`, 0);
+                }
+            }
+        }
+        const src = hasCall ? [] : this.urlTemplate(el, 'src', srcScope, {}, deps);
+        const call = hasCall ? this.callExpr(el, 'call', ctx.scope, deps) : null;
         let when = null;
         if (attr(el, 'when') != null) {
             const r = this.expr(el, 'when', ctx.scope, { mode: 'value' });
@@ -842,10 +1103,28 @@ class Compiler {
                     mode: mode, size, sizeParam: attr(el, 'size-param') ?? 'limit', cursor,
                     directionParam: attr(el, 'direction-param') ?? 'direction', pageParam: attr(el, 'page-param') ?? 'page',
                 };
+                const offsetParam = attr(el, 'offset-param');
+                if (offsetParam != null) {
+                    if (mode !== 'keyset')
+                        this.report(el, 'offset-param', 'SN401', `\`offset-param\` applies to \`paginate="keyset"\`; ${mode === 'offset' ? 'offset pages jump with `page-param`' : 'append mode only loads more'}`, 0);
+                    else if (!/^[\w.\-\[\]]+$/.test(offsetParam))
+                        this.report(el, 'offset-param', 'SN401', '`offset-param` is a query parameter name', 0);
+                    else
+                        paginate.offsetParam = offsetParam;
+                }
+                if (attr(el, 'direction-values') != null) {
+                    if (mode === 'offset')
+                        this.report(el, 'direction-values', 'SN401', '`direction-values` applies to `paginate="keyset"` and `paginate="append"`; offset pages send `page-param`', 0);
+                    else {
+                        const values = this.directionValues(el);
+                        if (values)
+                            paginate.directionValues = values;
+                    }
+                }
                 this.features.add('paginate');
             }
         }
-        for (const a of ['page-size', 'size-param', 'cursor', 'direction-param', 'page-param']) {
+        for (const a of ['page-size', 'size-param', 'cursor', 'direction-param', 'direction-values', 'page-param', 'offset-param']) {
             if (attr(el, a) != null && !paginate && mode == null)
                 this.report(el, a, 'SN102', `\`${a}\` needs \`paginate\``, 0);
         }
@@ -862,13 +1141,16 @@ class Compiler {
         }
         const order = attr(el, 'order');
         const type = attr(el, 'type')?.trim() || null;
-        const openapi = type ? null : this.openapi(el, src, attr(el, 'items') ?? null, attr(el, 'total') ?? null);
+        const openapi = type || hasCall ? null : this.openapi(el, src, attr(el, 'items') ?? null, attr(el, 'total') ?? null);
         if (this.check) {
             const r = { name, type, loc: this.locOf(el, type ? 'type' : null), nameLoc: this.locOf(el, 'name') };
             if (openapi && 'schema' in openapi)
                 r.openapi = openapi;
+            if (call)
+                r.call = { name: call.name, items: attr(el, 'items') ?? null };
             this.check.resources.push(r);
-            if (!type && !r.openapi) {
+            // a resource fed by an action is typed by the action's result
+            if (!type && !r.openapi && !r.call) {
                 const hint = openapi && 'closest' in openapi
                     ? `no OpenAPI GET operation matches \`src\`${openapi.closest ? ` (closest path: \`${openapi.closest}\`)` : ''}; add \`type="…"\`, or \`type="any"\` to leave it unchecked`
                     : 'add `type="…"` with a type from the types module, or `type="any"` to leave it unchecked';
@@ -879,6 +1161,8 @@ class Compiler {
             name, src, key: info.key, items: attr(el, 'items') ?? null, total: attr(el, 'total') ?? null,
             order: order ? order.trim() : null, when, paginate, deps: [...deps].sort(), scope: ctx.stateIdx, data: null,
             ...(cache !== undefined ? { cache } : {}),
+            ...(each ? { each } : {}),
+            ...(call ? { call: { args: call.args, run: call.run } } : {}),
         });
     }
     /** Matches a resource against the OpenAPI specs; checks `items`, `total` and query parameter names. */
@@ -940,7 +1224,7 @@ class Compiler {
             if (ev)
                 events.push(ev);
         }
-        this.syncs.push({ src, events });
+        this.syncs.push({ src, events, ...(ctx.stateIdx >= 0 ? { scope: ctx.stateIdx } : {}) });
         this.features.add('sse');
     }
     event(el, ctx) {
@@ -972,7 +1256,7 @@ class Compiler {
         const fnOf = (n, object = false) => {
             if (attr(el, n) == null)
                 return null;
-            const r = this.expr(el, n, scope, { mode: 'value', payload: true });
+            const r = this.expr(el, n, scope, { mode: 'value', payload: true, payloadState: true });
             this.typeLast({
                 payload: payloadType,
                 ...(n === 'item' ? { returns: { kind: 'item', resource } } : n === 'set' ? { returns: { kind: 'item', resource, partial: true } } : {}),
@@ -1011,7 +1295,7 @@ class Compiler {
 const usesEl = (r) => ({ ...(r.usesEl ? { e: 1 } : {}), ...(r.usesIndex ? { i: 1 } : {}) });
 function binding(b) {
     const out = { k: b.k };
-    for (const key of ['f', 'd', 'n', 'x', 'a', 'y', 'w', 'p', 'e', 'i']) {
+    for (const key of ['f', 'd', 'n', 'x', 'a', 'y', 'w', 'p', 'e', 'i', 'ms']) {
         const v = b[key];
         if (v === undefined || (Array.isArray(v) && v.length === 0 && key !== 'd'))
             continue;

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.',
@@ -71,13 +76,13 @@ export const DIAGNOSTIC_DOCS = {
     },
     SN303: {
         example: '`$meta.contacts.loadng` is not a status field. Did you mean `loading`?',
-        means: '`$meta.<resource>` has a fixed set of fields: `loading`, `error`, `loadedAt`, `pending`, `total`, and with `paginate` also `page`, `pages`, `from`, `to`, `hasPrev`, `hasNext`.',
+        means: '`$meta.<resource>` has a fixed set of fields: `loading`, `error`, `loadedAt`, `pending`, `total`, and with `paginate` also `pages`, `from`, `to`, `hasPrev`, `hasNext`; `page` with `paginate="offset"`, or keyset with `offset-param`.',
         fix: 'Use the suggested field. A pagination field needs `paginate` on the resource.',
     },
     SN304: {
-        example: 'keyset pagination cannot jump to a page number. Use `paginate="offset"`',
-        means: 'Keyset (cursor) pagination only knows the next and previous page, so `page(\'name\', 7)` has nothing to jump to.',
-        fix: 'Use `paginate="offset"` if the API supports offsets, or only step with `next`, `prev` and `first`.',
+        example: 'keyset pagination cannot jump to a page number. Add `offset-param` if the server also accepts an offset, or use `paginate="offset"`',
+        means: 'Keyset (cursor) pagination only knows the next and previous page, so `page(\'name\', 7)` has nothing to jump to, unless the server can also skip items by offset.',
+        fix: 'If the API accepts an offset next to its cursor, add `offset-param="offset"`: the jump is sent as an offset and `prev`/`next` continue by cursor. Otherwise use `paginate="offset"`, or only step with `first`, `prev`, `next` and `last`.',
     },
     SN305: {
         example: 'partial `./partials/contact-dialg.html` not found or outside the project root',
@@ -99,6 +104,16 @@ 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`.',
+        fix: 'Use the suggested name, or export the function from the actions module.',
+    },
     SN401: {
         example: '`data-sn-for` takes `item in list` or `(item, i) in list`',
         means: 'An attribute value has the wrong form: a JavaScript syntax error (the column points inside the attribute), or a value outside what the attribute accepts, such as `paginate` or `data-sn-concurrency`.',
@@ -122,7 +137,7 @@ export const DIAGNOSTIC_DOCS = {
     SN504: {
         example: 'resource `contacts` has no type: expressions using it are not checked',
         means: 'The type checker has no type for the resource, so expressions that use it are not checked. Reported by `sinter check` only.',
-        fix: 'Add `type="Contact[]"` with a type from `src/sinter.types.ts`, configure an OpenAPI spec that matches `src`, or write `type="any"` to opt out.',
+        fix: 'Add `type="Contact[]"` with a type from `src/sinter.types.ts`, configure an OpenAPI spec that matches `src`, load it with `call` (typed by what the action returns), or write `type="any"` to opt out.',
     },
     SN505: {
         example: '`GET /articles` declares no query parameter `tagg`. Did you mean `tag`?',