@tiaforge-ui/sinter 0.1.0 → 0.3.0

package/dist/runtime/store.js

@@ -12,13 +12,27 @@ export function clean(obj) {
             out[k] = obj[k];
     return out;
 }
+/** One collator per locale: constructing one is costly in some engines. */
+const collators = new Map();
+const collator = (l = '') => collators.get(l) ?? (collators.set(l, new Intl.Collator(l || undefined, { numeric: true })), collators.get(l));
 export function createResource(name, o) {
     const meta = { loading: false, error: null, loadedAt: null, pending: 0, total: null };
     const coll = !!o.key, field = o.order?.replace(/^-/, ''), dir = o.order?.[0] == '-' ? -1 : 1;
     const subs = new Set();
     const prep = (x) => (o.prep ? o.prep(x) : x);
-    let base = new Map(), single = null, total = null;
+    /** base items in arrival order, and each key's arrival number (ties in `order` keep arrival order) */
+    let base = new Map(), seq = new Map(), next = 0;
+    let single = null, total = null;
     let layers = [], lastLayer = 0;
+    /**
+     * The base in display order, the locale it was sorted for, and the keys written since, with
+     * their value before the first write. Reads patch it instead of sorting
+     * again. Arrays handed out are never changed afterwards.
+     */
+    let sorted = null, sortedFor, touched = new Map();
+    /** Optimistic layers applied over the base: changed keys (null: removed), keys they add (arrival numbers), removals counted for `total`. */
+    let over = null;
+    /** what readers see; rebuilt on the first read after a change */
     let view = null;
     let journal = null, loads = 0;
     const keyOf = (x) => typeof x == 'string' ? x : (o.key ?? []).map((f) => {
@@ -29,71 +43,171 @@ export function createResource(name, o) {
     const merge = (cur, op) => op.op == 'upsert' ? prep(op.item)
         : op.op == 'remove' ? null
             : cur && prep({ ...cur, ...clean(op.fields) });
-    /** Applies one op to a keyed map; counts removals of present items. */
-    const applyTo = (m, op, removed) => {
-        const k = op.op == 'upsert' ? keyOf(op.item) : op.key, v = merge(m.get(k), op);
-        if (v)
-            m.set(k, v);
-        else if (m.delete(k) && removed)
-            removed.n++;
+    /** Applies one op to the base. */
+    const apply = (op) => {
+        if (!coll)
+            return void (single = merge(single, op));
+        const k = op.op == 'upsert' ? keyOf(op.item) : op.key, cur = base.get(k), v = merge(cur, op);
+        if (sorted && !touched.has(k))
+            touched.set(k, cur);
+        if (v) {
+            if (!cur)
+                seq.set(k, next++);
+            base.set(k, v);
+        }
+        else if (cur) {
+            base.delete(k);
+            seq.delete(k);
+        }
     };
-    const changed = (what = 'data') => {
+    /** By `order` (none: all equal, so arrival order decides). */
+    const compare = (a, b) => {
+        if (!field)
+            return 0;
+        const x = a[field], y = b[field];
+        if (x == null || y == null)
+            return +(x == null) - +(y == null);
+        return dir * (typeof x == 'string' && typeof y == 'string' ? collator(sortedFor).compare(x, y) : +(x > y) - +(x < y));
+    };
+    /** A sorted copy of `list` without the `drop` items and with the `add` items (each with its arrival number). */
+    function patch(list, drop, add, arrival) {
+        const out = list.slice();
+        /** the first index whose item does not sort before `v` (with arrival number `n`, after its ties) */
+        const find = (v, n) => {
+            let lo = 0, hi = out.length;
+            while (lo < hi) {
+                const mid = (lo + hi) >> 1, c = compare(out[mid], v) || (n == null ? 0 : arrival(keyOf(out[mid])) - n);
+                c < 0 ? (lo = mid + 1) : (hi = mid);
+            }
+            return lo;
+        };
+        for (const v of drop) {
+            // among its ties, by identity; an item whose order field was changed in place is found by a scan
+            let i = find(v);
+            while (out[i] !== v && i < out.length && !compare(out[i], v))
+                i++;
+            out.splice(out[i] === v ? i : out.indexOf(v), 1);
+        }
+        for (const [v, n] of add)
+            out.splice(find(v, n), 0, v);
+        return out;
+    }
+    /** The base in display order. */
+    function baseList() {
+        const locale = o.locale?.();
+        if (sorted && locale === sortedFor && touched.size <= 64) {
+            if (touched.size) {
+                const drop = [], add = [];
+                for (const [k, old] of touched) {
+                    if (old)
+                        drop.push(old);
+                    const v = base.get(k);
+                    if (v)
+                        add.push([v, seq.get(k)]);
+                }
+                sorted = patch(sorted, drop, add, (k) => seq.get(k));
+            }
+        }
+        else {
+            sortedFor = locale;
+            // a stable sort of the Map's arrival order
+            sorted = [...base.values()].sort(compare);
+        }
+        touched = new Map();
+        return sorted;
+    }
+    /** Recomputes the layers' effect and `meta.total` after any change; marks `meta` if the total changed. */
+    function sync() {
+        over = null;
+        if (layers.length) {
+            const m = new Map(), add = new Map();
+            let removed = 0, n = next, s = single;
+            for (const l of layers)
+                for (const op of l.ops) {
+                    if (!coll) {
+                        s = merge(s, op);
+                        continue;
+                    }
+                    const k = op.op == 'upsert' ? keyOf(op.item) : op.key, cur = m.has(k) ? m.get(k) : base.get(k), v = merge(cur, op);
+                    if (v) {
+                        if (!cur)
+                            add.set(k, n++);
+                        m.set(k, v);
+                    }
+                    else {
+                        if (cur)
+                            removed++;
+                        m.set(k, null);
+                        add.delete(k);
+                    }
+                }
+            over = { m, add, removed, s };
+        }
+        const t = total == null ? null : Math.max(0, total - (over?.removed ?? 0));
+        if (meta.total !== t) {
+            meta.total = t;
+            r.onDirty('meta');
+        }
+    }
+    /** A data change: readers rebuild their view; `meta` too when the pending count changed. */
+    const changed = (pending) => {
         view = null;
+        sync();
         r.onDirty('data');
-        if (what == 'meta')
+        if (pending) {
+            meta.pending = layers.length;
             r.onDirty('meta');
+        }
     };
     function visible() {
         if (view)
             return view;
-        let t = total, m = base, s = single;
-        const removed = { n: 0 };
-        for (const l of layers)
-            for (const op of l.ops)
-                coll ? (m == base && (m = new Map(base)), applyTo(m, op, removed)) : (s = merge(s, op));
-        if (t != null)
-            t = Math.max(0, t - removed.n);
-        const l = [...m.values()];
-        if (field) {
-            const c = new Intl.Collator(o.locale?.(), { numeric: true });
-            l.sort((a, b) => {
-                const x = a[field], y = b[field];
-                if (x == null || y == null)
-                    return +(x == null) - +(y == null);
-                return dir * (typeof x == 'string' && typeof y == 'string' ? c.compare(x, y) : +(x > y) - +(x < y));
-            });
-        }
-        view = { l: Object.freeze(l), m, s };
-        if (meta.total !== t) {
-            meta.total = t;
-            r.onDirty('meta');
+        if (!coll)
+            return (view = { l: [], get: () => undefined, s: over ? over.s : single });
+        let l = baseList(), get = (k) => base.get(k);
+        if (over) {
+            const { m, add } = over, drop = [], put = [], at = (k) => add.get(k) ?? seq.get(k);
+            for (const [k, v] of m) {
+                const b = base.get(k);
+                if (b)
+                    drop.push(b);
+                if (v)
+                    put.push([v, at(k)]);
+            }
+            l = patch(l, drop, put, at);
+            get = (k) => (m.has(k) ? m.get(k) ?? undefined : base.get(k));
         }
-        return view;
+        // dev builds freeze what expressions see; the compiler refuses writes to resources (SN205)
+        return (view = { l: o.freeze ? Object.freeze(l.slice()) : l, get, s: null });
     }
     function write(op) {
         if (r.recording)
             return void r.recording.push(op);
         journal?.push(op);
-        coll ? applyTo(base, op) : (single = merge(single, op));
+        apply(op);
         changed();
         for (const f of subs)
             f({ resource: name, ...op });
     }
     const r = {
         name, meta, key: o.key, isCollection: coll, keyOf, recording: null, loader: null, onDirty() { },
-        get: (k) => (coll ? visible().m.get(keyOf(k)) : visible().s ?? undefined),
+        get: (k) => (coll ? visible().get(keyOf(k)) : visible().s ?? undefined),
         has: (k) => r.get(k) !== undefined,
         all: () => visible().l,
         value: () => (coll ? visible().l : visible().s),
         replace(items) {
             if (coll) {
                 base = new Map();
+                seq = new Map();
+                sorted = null;
+                touched = new Map();
                 for (const x of Array.isArray(items) ? items : []) {
                     const k = keyOf(x);
                     if (base.has(k))
                         o.warn?.(13, name, k);
                     base.delete(k);
                     base.set(k, prep(x));
+                    seq.set(k, next++);
                 }
             }
             else
@@ -105,7 +219,7 @@ export function createResource(name, o) {
         upsert: (item) => write({ op: 'upsert', item }),
         patch: (k, fields) => write({ op: 'patch', key: keyOf(k), fields }),
         remove: (k) => write({ op: 'remove', key: keyOf(k) }),
-        refetch: () => r.loader?.refetch() ?? Promise.resolve(),
+        refetch: (hint) => r.loader?.refetch(hint) ?? Promise.resolve(),
         subscribe: (fn) => (subs.add(fn), () => subs.delete(fn)),
         startLoad() {
             loads++;
@@ -119,23 +233,22 @@ export function createResource(name, o) {
             if (!loaded || !ops.length)
                 return;
             for (const op of ops)
-                coll ? applyTo(base, op) : (single = merge(single, op));
+                apply(op);
             changed();
         },
         addLayer(ops) {
             layers.push({ id: ++lastLayer, ops });
-            meta.pending = layers.length;
-            changed('meta');
+            changed(true);
             return lastLayer;
         },
         dropLayer(id) {
             const n = layers.length;
             layers = layers.filter((l) => l.id != id);
-            meta.pending = layers.length;
             if (n != layers.length)
-                changed('meta');
+                changed(true);
         },
-        setTotal(t) { total = t; changed(); },
+        /** the total changes `meta` only: bindings that read the items do not re-run */
+        setTotal(t) { total = t; sync(); },
         base: () => ({ items: coll ? [...base.values()] : single, total }),
     };
     return r;

package/dist/sse.js

@@ -45,10 +45,13 @@ class Connection {
     everOpen = false;
     url;
     fed;
+    /** where `src` and the events' expressions are evaluated: the enclosing state's scope, or the page */
+    base;
     constructor(app, def) {
         this.app = app;
         this.def = def;
-        this.url = app.url(def.src, app.page);
+        this.base = app.scopeOf(def.scope ?? -1);
+        this.url = app.url(def.src, this.base);
         this.fed = [...new Set(def.events.map((e) => e.resource))];
     }
     start() {
@@ -116,7 +119,7 @@ class Connection {
             status = (await this.app.req.raw(config.sessionProbe)).status;
         }
         catch (e) {
-            status = e instanceof SinterError ? e.status : 0;
+            status = e instanceof SinterError ? e.status ?? 0 : 0;
         }
         if (this.closed || this.hidden)
             return;
@@ -139,7 +142,7 @@ class Connection {
     }
     apply(def, payload) {
         const app = this.app;
-        const scope = Object.create(app.page);
+        const scope = Object.create(this.base);
         scope.$p = payload && typeof payload === 'object' ? payload : {};
         const r = app.resource(def.resource);
         try {
@@ -148,13 +151,13 @@ class Connection {
             const paginated = !!app.ir.resources.find((x) => x.name === def.resource)?.paginate;
             switch (def.op) {
                 case 'refetch':
-                    void r.refetch();
+                    void r.refetch(scope.$p);
                     return;
                 case 'upsert': {
                     const item = def.item != null ? app.fns[def.item](scope) : payload;
                     if (item == null || typeof item !== 'object') {
                         if (def.fallback === 'refetch')
-                            void r.refetch();
+                            void r.refetch(scope.$p);
                         return;
                     }
                     if (paginated && !r.has(item)) {

package/dist/testing/index.d.ts

@@ -44,6 +44,8 @@ export interface RenderOptions {
     now?: number | Date;
     /** helper functions, and namespaces as objects of functions */
     helpers?: Record<string, unknown>;
+    /** action functions for `data-sn-call` and `<sn-resource call>`, and namespaces as objects of functions */
+    actions?: Record<string, unknown>;
     /** partials for `<sn-include>`, by path relative to the page */
     files?: Record<string, string>;
     /** localStorage and sessionStorage (default: empty ones); pass the previous page's to test what carries over */

package/dist/testing/index.js

@@ -11,9 +11,11 @@ import cache from '../cache.js';
 import dev from '../dev.js';
 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 };
+const FEATURES = { dev, sse, optimistic, paginate, persist, cache, each, listbox };
 function isResponseSpec(v) {
     if (!v || typeof v !== 'object' || Array.isArray(v))
         return false;
@@ -172,9 +174,17 @@ export async function render(html, options = {}) {
         else if (v && typeof v === 'object')
             manifest.namespaces[k] = { module: k, members: Object.keys(v) };
     }
+    const actions = options.actions ?? {};
+    const actionManifest = { module: 'actions', names: [], namespaces: {} };
+    for (const [k, v] of Object.entries(actions)) {
+        if (typeof v === 'function')
+            actionManifest.names.push(k);
+        else if (v && typeof v === 'object')
+            actionManifest.namespaces[k] = { module: k, members: Object.keys(v) };
+    }
     const files = options.files ?? {};
     const parts = compileParts(html, {
-        file: PAGE, root: '/test', dev: true, helpers: manifest, moduleSrc: 'about:blank',
+        file: PAGE, root: '/test', dev: true, helpers: manifest, actions: actionManifest, moduleSrc: 'about:blank',
         readFile: (p) => {
             const rel = p.startsWith('/test/') ? p.slice('/test/'.length) : p;
             const hit = files[rel] ?? files[`./${rel}`] ?? files[p];
@@ -203,6 +213,11 @@ export async function render(html, options = {}) {
             values.push(helpers[ns][m]);
         }
     }
+    for (const c of parts.calls) {
+        const [a, b] = c.split('.');
+        names.push(`$a$${c.replace('.', '$')}`);
+        values.push(b === undefined ? actions[a] : actions[a][b]);
+    }
     // eslint-disable-next-line no-new-func -- tests only; pages load a compiled module
     const fns = new Function(...names, `"use strict"; return [\n${parts.fns.join(',\n')}\n];`)(...values);
     // the page

package/dist/vite.js

@@ -51,7 +51,7 @@ export default function sinter(options = {}) {
                 return;
             const { check } = await import('./check/index.js');
             const p = project(root, options);
-            const r = check({ root, units: [...units.values()], helpers: p.helpers, types: p.types, openapi: p.openapi });
+            const r = check({ root, units: [...units.values()], helpers: p.helpers, actions: p.actions, types: p.types, openapi: p.openapi });
             units.clear();
             if (r.diagnostics.length)
                 this.error(`sinter check: ${r.diagnostics.length} type error(s)\n${r.diagnostics.map(formatDiagnostic).join('\n')}`);
@@ -66,7 +66,7 @@ export default function sinter(options = {}) {
                 if (p.diagnostics.length)
                     throw new Error(`sinter: ${p.diagnostics.map(formatDiagnostic).join('\n')}`);
                 const out = compile(html, {
-                    file, root, dev, helpers: p.helpers, moduleSrc, config: p.config, readFile: p.readFile,
+                    file, root, dev, helpers: p.helpers, actions: p.actions, moduleSrc, config: p.config, readFile: p.readFile,
                     check: !!options.typecheck && !dev, openapi: p.openapi,
                 });
                 if (out.check)
@@ -75,6 +75,8 @@ export default function sinter(options = {}) {
                     watch(f);
                 if (p.helpersFile)
                     watch(p.helpersFile);
+                if (p.actionsFile)
+                    watch(p.actionsFile);
                 const errors = out.diagnostics.filter((d) => d.severity === 'error');
                 for (const d of out.diagnostics)
                     if (d.severity === 'warning')

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:
@@ -148,7 +158,7 @@ Error, for example:
 
 > `$meta.contacts.loadng` is not a status field. Did you mean `loading`?
 
-`$meta.<resource>` has a fixed set of fields: `loading`, `error`, `loadedAt`, `pending`, `total`, and with `paginate` also `page`, `pages`, `from`, `to`, `hasPrev`, `hasNext`.
+`$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.
 
@@ -156,11 +166,11 @@ Error, for example:
 
 Error, for example:
 
-> keyset pagination cannot jump to a page number. Use `paginate="offset"`
+> keyset pagination cannot jump to a page number. Add `offset-param` if the server also accepts an offset, or use `paginate="offset"`
 
-Keyset (cursor) pagination only knows the next and previous page, so `page('name', 7)` has nothing to jump to.
+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:** Use `paginate="offset"` if the API supports offsets, or only step with `next`, `prev` and `first`.
+**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 include-not-found
 
@@ -202,6 +212,26 @@ 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:
+
+> `pgp.decrpyt` is not exported by the actions module. Did you mean `pgp.decrypt`?
+
+`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 parse-error
 
 Error, for example:
@@ -250,7 +280,7 @@ Warning, for example:
 
 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 unknown-query-param
 

package/html-custom-data.json

@@ -11,6 +11,12 @@
         {
           "name": "src"
         },
+        {
+          "name": "call"
+        },
+        {
+          "name": "each"
+        },
         {
           "name": "key"
         },
@@ -41,9 +47,15 @@
         {
           "name": "direction-param"
         },
+        {
+          "name": "direction-values"
+        },
         {
           "name": "page-param"
         },
+        {
+          "name": "offset-param"
+        },
         {
           "name": "type"
         },
@@ -106,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)"
@@ -150,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)"
@@ -174,6 +194,10 @@
       "name": "data-sn-delete",
       "description": "DELETE action (URL template)"
     },
+    {
+      "name": "data-sn-call",
+      "description": "local action: calls a function from the actions module, e.g. pgp.decrypt(msg) (action call)"
+    },
     {
       "name": "data-sn-body",
       "description": "JSON request body; overrides form serialization (value expression)"
@@ -184,7 +208,7 @@
     },
     {
       "name": "data-sn-debounce",
-      "description": "delays the trigger, resets on each event (milliseconds)"
+      "description": "delays the trigger, resets on each event; without a method, delays the element's data-sn-on-* handlers (milliseconds)"
     },
     {
       "name": "data-sn-concurrency",
@@ -200,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",
@@ -229,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"
     }
   ]
 }