@tiaforge-ui/sinter 0.1.0 → 0.3.0

package/dist/ir.d.ts

@@ -8,7 +8,11 @@ export interface Paginate {
     /** keyset/append: object literal evaluated with the boundary item as `$.$p` */
     cursor: number | null;
     directionParam: string;
+    /** keyset/append: the value sent for each direction, where it differs from the direction's name */
+    directionValues?: Partial<Record<'first' | 'prev' | 'next' | 'last', string>>;
     pageParam: string;
+    /** keyset: offset parameter that lets `page(name, n)` jump; the server skips (n - 1) * size items */
+    offsetParam?: string;
 }
 export interface ResourceDef {
     name: string;
@@ -29,6 +33,14 @@ export interface ResourceDef {
     data: number | null;
     /** `cache`: the oldest cached data to show, in ms (0: any age); absent when not cached */
     cache?: number;
+    /** `call="ns.fn(args)"`: loaded from an action function instead of `src` (then empty) */
+    call?: CallDef;
+    /** `each="a in accounts"`: one request per list item (src evaluated with `item` in scope), merged into one collection */
+    each?: {
+        item: string;
+        list: number;
+        of?: string;
+    };
 }
 export interface EventDef {
     name: string;
@@ -42,6 +54,8 @@ export interface EventDef {
 export interface SyncDef {
     src: UrlTemplate;
     events: EventDef[];
+    /** index of the node (in `roots`) whose scope `src` and the events' expressions are evaluated in, -1 (or absent) for page scope */
+    scope?: number;
 }
 export type BindingKind = 'text' | 'attr' | 'class' | 'style' | 'show' | 'model' | 'prop' | 'for' | 'if' | 'else' | 'on';
 export interface Binding {
@@ -66,6 +80,8 @@ export interface Binding {
     e?: 1;
     /** the expression reads a loop index, so it re-runs when only the row's position changed */
     i?: 1;
+    /** handler on an element without a method: `data-sn-debounce` milliseconds */
+    ms?: number;
 }
 export interface NodeDef {
     /** `data-sn` id (roots) */
@@ -80,6 +96,8 @@ export interface NodeDef {
     sid?: number;
     /** persist key for the whole state object */
     persist?: string;
+    /** the element is a `<dialog>` or inside one of its block, so its bindings wait while that dialog is closed */
+    dl?: 1;
     b: Binding[];
 }
 export interface TemplateDef {
@@ -95,9 +113,16 @@ export interface TemplateDef {
     /** for: function that finds the bound elements of one cloned row: (first content node) => elements, in `nodes` order */
     find?: number;
 }
+/** a local action call: `args` evaluates the arguments (an array), `run(args, ctx)` calls the function */
+export interface CallDef {
+    args: number;
+    run: number;
+}
 export interface ActionDef {
-    method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+    /** `CALL`: `data-sn-call`, with `call` set and an empty `url` */
+    method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'CALL';
     url: UrlTemplate;
+    call?: CallDef;
     body: number | null;
     trigger: string;
     debounce: number;
@@ -109,6 +134,10 @@ export interface ActionDef {
     w: string[];
     /** element is a form (serialize, disable in block mode) */
     form: boolean;
+    /** `data-sn-confirm`: the question asked before the action runs (none when it is falsy) */
+    confirm?: number;
+    /** `data-sn-encoding="form"`: the body goes as application/x-www-form-urlencoded */
+    enc?: 'form';
 }
 export interface IR {
     v: 1;

package/dist/listbox.d.ts

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

package/dist/listbox.js

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

package/dist/lsp/typescript.js

@@ -59,7 +59,7 @@ export class TypeScriptBridge {
             this.filesChanged([support.declarations, ...support.openapi]);
         this.support = support;
         for (const [page, unit] of units) {
-            const s = shadowOf(unit, support, this.root, project.helpers);
+            const s = shadowOf(unit, support, this.root, project.helpers, project.actions);
             const prev = this.shadows.get(page);
             if (prev?.text === s.text) {
                 prev.unit = unit;

package/dist/lsp/workspace.js

@@ -48,13 +48,14 @@ export class Workspace {
         }
         const p = project(root, options);
         const inputs = new Set(VITE_CONFIGS.map((c) => join(root, c)));
-        for (const f of [p.helpersFile, p.types, ...p.openapi.map((s) => s.file)])
+        for (const f of [p.helpersFile, p.actionsFile, p.types, ...p.openapi.map((s) => s.file)])
             if (f)
                 inputs.add(f);
         for (const spec of options.openapi == null ? [] : [].concat(options.openapi))
             inputs.add(resolve(root, spec));
         for (const ext of ['.js', '.ts']) {
             inputs.add(join(root, 'src/sinter.helpers' + ext));
+            inputs.add(join(root, 'src/sinter.actions' + ext));
             inputs.add(join(root, 'src/sinter.types' + ext));
         }
         inputs.add(join(root, 'src/sinter.types.d.ts'));
@@ -166,7 +167,7 @@ export class Workspace {
             }
             try {
                 const out = compile(html, {
-                    file: page, root: state.root, dev: false, helpers: p.helpers, config: p.config, readFile, check: true, openapi: p.openapi,
+                    file: page, root: state.root, dev: false, helpers: p.helpers, actions: p.actions, config: p.config, readFile, check: true, openapi: p.openapi,
                 });
                 state.includes.set(page, out.files.map((f) => resolve(f)).filter((f) => f !== page));
                 state.diagnostics.set(page, out.diagnostics);

package/dist/paginate.js

@@ -7,14 +7,14 @@ class PagerImpl {
         this.cfg = loader.def.paginate;
         this.move = this.first();
         const m = loader.res.meta;
-        if (this.cfg.mode === 'offset')
+        if (this.cfg.mode === 'offset' || this.cfg.offsetParam)
             m.page = 1;
         Object.assign(m, { pages: null, from: null, to: null, hasPrev: false, hasNext: false });
     }
     base(dir, size = this.cfg.size) {
         const p = { [this.cfg.sizeParam]: String(size) };
         if (dir)
-            p[this.cfg.directionParam] = dir;
+            p[this.cfg.directionParam] = this.cfg.directionValues?.[dir] ?? dir;
         return p;
     }
     first() {
@@ -49,8 +49,10 @@ class PagerImpl {
             scope.$p = item;
             const c = this.loader.app.fns[this.cfg.cursor](scope);
             const out = {};
+            // like a URL template's query parameters: null and undefined fields are left out
             for (const [k, v] of Object.entries(c ?? {}))
-                out[k] = v == null ? '' : String(v);
+                if (v != null)
+                    out[k] = String(v);
             return out;
         };
         let move;
@@ -80,7 +82,16 @@ class PagerImpl {
         }
         else {
             if (typeof target === 'number') {
-                this.loader.app.warn('keyset pagination cannot jump to a page number; use paginate="offset"');
+                if (!this.cfg.offsetParam) {
+                    this.loader.app.warn('keyset pagination cannot jump to a page number; add offset-param or use paginate="offset"');
+                    return;
+                }
+                // the server skips (n - 1) pages; prev/next continue by cursor from there
+                let n = Math.max(1, Math.floor(target));
+                if (meta.pages != null)
+                    n = Math.min(n, meta.pages);
+                move = { dir: 'page', page: n, params: { [this.cfg.offsetParam]: String((n - 1) * this.cfg.size), ...this.base('first') }, from, to };
+                void this.loader.load(move);
                 return;
             }
             if (this.cfg.mode === 'append' && target !== 'next')
@@ -158,6 +169,9 @@ class PagerImpl {
                     hasPrev = full;
                 break;
         }
+        // keyset with jumps: the page that holds the last item shown (after `last`, the last page)
+        if (this.cfg.offsetParam && move.dir !== 'page')
+            meta.page = to != null ? Math.max(1, Math.ceil(to / size)) : null;
         Object.assign(meta, { pages, from, to, hasPrev, hasNext });
         this.loader.res.onDirty('meta');
     }

package/dist/project.d.ts

@@ -3,6 +3,8 @@ import type { OpenApiSpec } from './compiler/openapi.js';
 export interface ProjectOptions {
     /** helpers module, relative to the root (default `src/sinter.helpers.js`, or `.ts`) */
     helpers?: string;
+    /** actions module for `data-sn-call` and `<sn-resource call>` (default `src/sinter.actions.js`, or `.ts`) */
+    actions?: string;
     /** app configuration module imported before mount (default `src/sinter.config.js`, or `.ts`) */
     config?: string;
     /** module whose exported types `type="…"` on `<sn-resource>` may name (default `src/sinter.types.ts`, `.d.ts` or `.js`) */
@@ -15,6 +17,10 @@ export interface Project {
     helpers: HelperManifest;
     /** absolute path of the helpers module, or null */
     helpersFile: string | null;
+    /** the actions module's functions and namespaces (same shape as helpers) */
+    actions: HelperManifest;
+    /** absolute path of the actions module, or null */
+    actionsFile: string | null;
     /** root-relative URL of the config module (`/src/sinter.config.js`), or null */
     config: string | null;
     /** absolute path of the types module, or null */

package/dist/project.js

@@ -20,25 +20,28 @@ export function project(root, options = {}) {
         return readFileSync(real, 'utf8');
     };
     const url = (rel) => '/' + rel.split(sep).join('/');
-    let helpers = { module: null, names: [], namespaces: {} };
-    const helpersRel = find(options.helpers, 'src/sinter.helpers');
-    const helpersFile = helpersRel ? resolve(root, helpersRel) : null;
-    if (helpersRel && helpersFile) {
-        helpers = readHelperManifest(readFileSync(helpersFile, 'utf8'), {
-            module: url(helpersRel),
-            file: helpersFile,
-            readFile,
-            resolve: (spec, from) => {
-                if (!spec.startsWith('.'))
+    const manifest = (given, base) => {
+        const rel = find(given, base);
+        const file = rel ? resolve(root, rel) : null;
+        if (!rel || !file)
+            return [{ module: null, names: [], namespaces: {} }, null];
+        return [readHelperManifest(readFileSync(file, 'utf8'), {
+                module: url(rel),
+                file,
+                readFile,
+                resolve: (spec, from) => {
+                    if (!spec.startsWith('.'))
+                        return null;
+                    const b = resolve(dirname(from), spec);
+                    for (const q of [b, b.replace(/\.js$/, '.ts'), `${b}.js`, `${b}.ts`])
+                        if (existsSync(q))
+                            return q;
                     return null;
-                const base = resolve(dirname(from), spec);
-                for (const p of [base, base.replace(/\.js$/, '.ts'), `${base}.js`, `${base}.ts`])
-                    if (existsSync(p))
-                        return p;
-                return null;
-            },
-        });
-    }
+                },
+            }), file];
+    };
+    const [helpers, helpersFile] = manifest(options.helpers, 'src/sinter.helpers');
+    const [actions, actionsFile] = manifest(options.actions, 'src/sinter.actions');
     const configRel = find(options.config, 'src/sinter.config');
     const typesRel = find(options.types, 'src/sinter.types', ['.ts', '.d.ts', '.js']);
     const openapi = [];
@@ -70,7 +73,7 @@ export function project(root, options = {}) {
         openapi.push({ file, doc });
     }
     return {
-        root, helpers, helpersFile, readFile, openapi, diagnostics,
+        root, helpers, helpersFile, actions, actionsFile, readFile, openapi, diagnostics,
         config: configRel ? url(configRel) : null,
         types: typesRel ? resolve(root, typesRel) : null,
     };

package/dist/runtime/app.d.ts

@@ -47,18 +47,42 @@ export interface Pager {
     appends(move: unknown): boolean;
     received(items: unknown[], total: number | null, move: unknown): void;
 }
+/** The last argument of an action function (`data-sn-call`, `<sn-resource call>`). */
+export interface CallContext {
+    /** aborts when the page is hidden (pagehide) or, for a resource, when its inputs change */
+    signal: AbortSignal;
+    /** a request through the app's middleware chain (401 handling, origins, timeout) */
+    request(url: string, init?: SendInit): Promise<unknown>;
+    /** the element whose action this is; null for a resource */
+    el: Element | null;
+}
 export interface ResourceLoader {
     def: ResourceDef;
     res: Resource;
     app: App;
     pager: Pager | null;
+    /** first load (or embedded/cached data) */
+    start(): void;
+    /** `src`, `when` (or an `each` list) may have changed */
+    changed(): void;
     load(move?: unknown): Promise<void>;
-    refetch(): Promise<void>;
+    refetch(hint?: object): Promise<void>;
+    /** for feature modules: the scope `src` and `when` are evaluated in */
+    scope(): any;
+    /** for feature modules: a shared GET (concurrent loads of one URL share one request) */
+    get(url: string, signal: AbortSignal): Promise<unknown>;
+    /** for feature modules: the collection items of a response body (`items` path, checked, cleaned) */
+    items(body: unknown): any[];
+    /** for feature modules: a failed load: `$meta.error`, then the unhandled-error path */
+    failed(e: unknown): void;
+    loading(on: boolean): void;
 }
 export interface App {
     readonly ir: IR;
     readonly fns: Fn[];
     readonly env: Env;
+    /** the element or document this instance is mounted on */
+    readonly root: Document | Element;
     readonly req: RequestLayer;
     /** the base scope: resources, status, magic names */
     readonly page: any;
@@ -67,6 +91,9 @@ export interface App {
         optimistic?: {
             begin(fn: number, scope: any): () => void;
         };
+        each?: {
+            fanOut(loader: ResourceLoader): void;
+        };
         paginate?: {
             pager(loader: ResourceLoader): Pager;
             page(name: string, target: string | number): void;
@@ -108,6 +135,8 @@ export interface App {
     state<T = any>(el: Element): StateHandle<T>;
     destroy(): void;
     url(tpl: UrlTemplate, scope: any): string;
+    /** the scope of root node `i` (its state), or the page scope for -1 */
+    scopeOf(i: number): any;
     mark(path: string, scope?: any): void;
     flush(): void;
     record(change: () => void): () => void;
@@ -122,4 +151,9 @@ export declare function withParams(url: string, params: Record<string, string> |
 /** Indexes (into `seq`) of a longest increasing subsequence, ignoring -1 entries. */
 export declare function lis(seq: number[]): Set<number>;
 /** Serializes a form's named controls to nested JSON, or FormData if it has a file input. */
+/**
+ * A body as form fields (`data-sn-encoding="form"`): a form's own fields, or an object's keys with
+ * arrays as repeated keys; null and undefined values are left out. Files stay multipart.
+ */
+export declare function formBody(body: unknown): URLSearchParams | FormData | null;
 export declare function serialize(form: HTMLFormElement): unknown;