@tiaforge-ui/sinter 0.1.0 → 0.2.0

package/dist/compiler/compile.js

@@ -1,6 +1,7 @@
 // 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';
@@ -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,6 +54,7 @@ class Compiler {
             ns.set(k, new Set(v.members));
         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(),
         };
     }
@@ -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'].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;
@@ -251,6 +343,8 @@ 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;
@@ -352,6 +446,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;
@@ -408,6 +505,17 @@ 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);
+        }
         for (const a of sn) {
             if (!a.name.startsWith('data-sn-on-'))
                 continue;
@@ -418,16 +526,19 @@ class Compiler {
             }
             const r = this.expr(el, a.name, scope, { mode: 'handler', magic: ['$event'] });
             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, ...(handlerDebounce > 0 ? { ms: handlerDebounce } : {}) }));
         }
-        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 +587,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 +606,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) ?? '';
@@ -541,7 +655,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,7 +663,7 @@ 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;
     }
@@ -649,7 +763,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 +792,19 @@ 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 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 } } : {}),
         };
         this.actions.push(def);
         node.b.push(binding({ k: 'on', n: trigger, x: this.actions.length - 1 }));
@@ -803,10 +923,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 = { loops: [...ctx.scope.loops, loop], states: ctx.scope.states };
+                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 +1002,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 +1040,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 +1060,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 +1123,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 +1155,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 +1194,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

@@ -71,13 +71,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 +99,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.',
     },
+    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 +127,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`?',

package/dist/compiler/diagnostics.d.ts

@@ -36,6 +36,7 @@ export declare const CODES: {
     readonly SN306: 'include-cycle';
     readonly SN307: 'openapi-invalid';
     readonly SN308: 'unknown-schema-field';
+    readonly SN310: 'unknown-action';
     readonly SN401: 'parse-error';
     readonly SN501: 'unused-resource';
     readonly SN502: 'non-reactive-value';

package/dist/compiler/diagnostics.js

@@ -19,6 +19,7 @@ export const CODES = {
     SN306: 'include-cycle',
     SN307: 'openapi-invalid',
     SN308: 'unknown-schema-field',
+    SN310: 'unknown-action',
     SN401: 'parse-error',
     SN501: 'unused-resource',
     SN502: 'non-reactive-value',

package/dist/compiler/expr.d.ts

@@ -24,6 +24,8 @@ export interface ResourceInfo {
     key: string[] | null;
     paginate: string | null;
     used: boolean;
+    /** keyset with `offset-param`: `page(name, n)` and `$meta.<name>.page` are available */
+    jumps?: boolean;
 }
 export interface Scope {
     loops: LoopEntry[];
@@ -32,6 +34,8 @@ export interface Scope {
 export interface PageInfo {
     resources: Map<string, ResourceInfo>;
     helpers: Set<string>;
+    /** action functions and namespaces: only `data-sn-call` and `<sn-resource call>` may name them */
+    actions?: Set<string>;
     namespaces: Map<string, Set<string>>;
     /** imports used by emitted code */
     usedHelpers: Set<string>;
@@ -46,6 +50,8 @@ export interface ExprOptions {
     magic?: string[];
     /** free identifiers resolve to fields of `$.$p` (sn-event, cursor) */
     payload?: boolean;
+    /** with `payload`: state names in scope resolve to the state first (`<sn-event>`) */
+    payloadState?: boolean;
     /** parse as `{...}` object literal; returns its entries */
     object?: 'literal-keys' | 'any-keys' | 'state';
     report: (code: Code, message: string, offset: number, hint?: string) => void;
@@ -73,6 +79,8 @@ export interface ExprResult {
     ast: Node | null;
     /** names resolved to payload fields (`payload` mode) */
     payloadNames?: string[];
+    /** state names read where the payload is the scope (they shadow payload fields of the same name) */
+    payloadStates?: string[];
 }
 export declare const ALL_MAGIC: string[];
 export declare const STORE_FNS: string[];

package/dist/compiler/expr.js

@@ -50,6 +50,7 @@ export function analyze(src, scope, page, opts) {
     let usesIndex = false;
     let ok = true;
     const payloadNames = new Set();
+    const payloadStates = new Set();
     const mode = opts.mode;
     const magicAllowed = new Set([...EVERYWHERE_MAGIC, ...(opts.magic ?? [])]);
     const report = (code, message, offset, hint) => {
@@ -117,6 +118,14 @@ export function analyze(src, scope, page, opts) {
             report('SN201', `\`${name}\` is not defined.${didYouMean(name, ALL_MAGIC)}`, offset);
             return null;
         }
+        if (opts.payload && opts.payloadState) {
+            for (let i = scope.states.length - 1; i >= 0; i--) {
+                if (scope.states[i].names.has(name)) {
+                    payloadStates.add(name);
+                    return { kind: 'state', sid: scope.states[i].sid };
+                }
+            }
+        }
         if (!opts.payload) {
             for (let i = scope.loops.length - 1; i >= 0; i--) {
                 if (scope.loops[i].name === name)
@@ -148,6 +157,10 @@ export function analyze(src, scope, page, opts) {
             payloadNames.add(name);
             return { kind: 'payload' };
         }
+        if (page.actions?.has(name)) {
+            report('SN203', `\`${name}\` is an action: actions run through \`data-sn-call\` or \`<sn-resource call>\`, not inside expressions`, offset);
+            return null;
+        }
         if (BROWSER.has(name)) {
             report('SN202', `\`${name}\` is a browser API; expressions may use JavaScript, not the browser. Use an island`, offset);
             return null;
@@ -278,8 +291,8 @@ export function analyze(src, scope, page, opts) {
                 else if (PAGE_FIELDS.includes(field) && !r.paginate) {
                     report('SN303', `\`$meta.${rname}.${field}\` is a pagination field, but \`${rname}\` has no \`paginate\``, n.start);
                 }
-                else if (field === 'page' && r.paginate !== 'offset') {
-                    report('SN303', `\`$meta.${rname}.page\` exists only with \`paginate="offset"\``, n.start);
+                else if (field === 'page' && r.paginate !== 'offset' && !r.jumps) {
+                    report('SN303', `\`$meta.${rname}.page\` exists only with \`paginate="offset"\`, or \`paginate="keyset"\` with \`offset-param\``, n.start);
                 }
             }
         }
@@ -572,8 +585,10 @@ export function analyze(src, scope, page, opts) {
                     report('SN303', `\`${first.value}\` has no \`paginate\`; \`page()\` needs a paginated resource`, n.start);
                 const target = n.arguments[1];
                 const named = target?.type === 'Literal' && typeof target.value === 'string' ? target.value : null;
-                if (r.paginate && r.paginate !== 'offset' && (!named)) {
-                    report('SN304', 'keyset pagination cannot jump to a page number. Use `paginate="offset"`', target?.start ?? n.start);
+                if (r.paginate && r.paginate !== 'offset' && !named && !(r.paginate === 'keyset' && r.jumps)) {
+                    report('SN304', r.paginate === 'keyset'
+                        ? 'keyset pagination cannot jump to a page number. Add `offset-param` if the server also accepts an offset, or use `paginate="offset"`'
+                        : 'keyset pagination cannot jump to a page number. Use `paginate="offset"`', target?.start ?? n.start);
                 }
                 else if (r.paginate === 'append' && named && named !== 'next') {
                     report('SN304', '`append` pagination only supports `page(…, \'next\')`', target.start);
@@ -827,7 +842,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() } : {}) };
+    return { ok, code, 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/index.d.ts

@@ -8,10 +8,11 @@ export { compileParts };
 export declare const PACKAGE = "@tiaforge-ui/sinter";
 /** Compiles annotated HTML into a rewritten page and its page module. Pure and deterministic. */
 export declare function compile(html: string, options: CompileOptions): CompileResult;
-export declare function pageModule(parts: CompiledParts, options: Pick<CompileOptions, 'helpers' | 'dev' | 'config'>): string;
+export declare function pageModule(parts: CompiledParts, options: Pick<CompileOptions, 'helpers' | 'dev' | 'config' | 'actions'>): string;
 /**
  * Reads a helpers module's export names statically. `export * as m from './x.js'`
- * becomes a namespace whose members are read from `x.js` the same way.
+ * becomes a namespace whose members are read from `x.js` the same way. `export * from './y.js'`
+ * re-exports (e.g. paraglide's message index) are followed, relative paths only.
  */
 export declare function readHelperManifest(source: string, options: {
     module: string;