@tiaforge-ui/sinter 0.1.0 → 0.3.0

package/llms.txt

@@ -7,6 +7,7 @@ Package: @tiaforge-ui/sinter. Every directive is a `data-sn-*` attribute or an `
 ## Attributes
 
 - `data-sn-state` (object literal): declares local reactive state for the element and its subtree
+- `data-sn-let` (object literal {name: expression}): derived names for the element and its subtree, computed where they are read; later names may use earlier ones
 - `data-sn-text` (value expression): sets textContent; never HTML
 - `data-sn-attr` (object literal {href: …}): literal keys; null/false removes, true sets empty; URL values are checked
 - `data-sn-class` (object literal {unread: …}): toggles each class
@@ -18,26 +19,31 @@ Package: @tiaforge-ui/sinter. Every directive is a `data-sn-*` attribute or an `
 - `data-sn-key` (value expression): row identity; defaults to the resource key or object identity
 - `data-sn-if` (value expression): renders a <template> while truthy
 - `data-sn-else`: on a <template> directly after an if template
+- `data-sn-listbox` (id of the suggestion list, or empty): on a text input: arrow keys mark a [role=option] of that list (empty: the nearest [role=listbox] around the input), Enter or Tab clicks it, Escape fires `dismiss`
 - `data-sn-persist` (storage key): persists the model or state in localStorage under sn:
 - `data-sn-get` (URL template): GET action; latest wins
 - `data-sn-post` (URL template): POST action
 - `data-sn-put` (URL template): PUT action
 - `data-sn-patch` (URL template): PATCH action
 - `data-sn-delete` (URL template): DELETE action
+- `data-sn-call` (action call): local action: calls a function from the actions module, e.g. pgp.decrypt(msg)
 - `data-sn-body` (value expression): JSON request body; overrides form serialization
 - `data-sn-trigger` (DOM event name): overrides the default trigger
-- `data-sn-debounce` (milliseconds): delays the trigger, resets on each event
+- `data-sn-debounce` (milliseconds): delays the trigger, resets on each event; without a method, delays the element's data-sn-on-* handlers
 - `data-sn-concurrency` (block | queue | latest): mutations only; default block for forms, queue otherwise
 - `data-sn-optimistic` (handler expression): patch/upsert/remove calls applied before the request, rolled back on failure
 - `data-sn-then` (handler expression): runs after a 2xx response; $result = parsed body
-- `data-sn-catch` (handler expression): runs after an error; $error = {status, body, message}
+- `data-sn-catch` (handler expression): runs after an error; $error = {status, body, message, detail}
+- `data-sn-confirm` (value expression): asks this question before the action runs (configure({ confirm }), window.confirm by default); no question when falsy
+- `data-sn-encoding` (json | form): form: the body (data-sn-body, arrays as repeated keys, or the form) goes as application/x-www-form-urlencoded
 - `data-sn-path` (URL patterns /a/:b …): on <html>: the path shapes this page is served for; `:name` segments appear read-only in $url
 - `data-sn-data` (resource name): on <script type="application/json"> in <head>: initial data for a resource
 - `data-sn-on-<event>` (handler expression): plain event handler, no request; e.g. data-sn-on-click
+- `data-sn-debounce-<event>` (milliseconds): delays only that event's data-sn-on-<event> handler (it runs with the last event); e.g. data-sn-debounce-input
 
 ## Elements
 
-- `<sn-resource>` `name`, `src`, `key`, `items`, `total`, `order`, `when`, `paginate`, `page-size`, `size-param`, `cursor`, `direction-param`, `page-param`, `type`, `cache`: a named, page-wide cache of server data; `cache` (or `cache="10m"`) shows the data from the last page load at once, then revalidates
+- `<sn-resource>` `name`, `src`, `call`, `each`, `key`, `items`, `total`, `order`, `when`, `paginate`, `page-size`, `size-param`, `cursor`, `direction-param`, `direction-values`, `page-param`, `offset-param`, `type`, `cache`: a named, page-wide cache of server data; `cache` (or `cache="10m"`) shows the data from the last page load at once, then revalidates
 - `<sn-sync>` `src`: one server event stream
 - `<sn-event>` `name`, `resource`, `op`, `item`, `set`, `when`, `fallback`, `type`: maps one server event to a change message; child of <sn-sync>
 - `<sn-include>` `src`: inlines a partial at build time
@@ -59,11 +65,11 @@ Package: @tiaforge-ui/sinter. Every directive is a `data-sn-*` attribute or an `
 
 ## Store functions
 
-`refresh()`, `upsert()`, `patch()`, `remove()`, `page()`, `close()`, `reset()`, `emit()`: `refresh('name')`, `upsert('name', item)`, `patch('name', item, {…})`, `remove('name', item)`, `page('name', 'next' | 'prev' | 'first' | 'last' | n)`, `close()` the nearest dialog, `reset()` the nearest form, `emit('event', detail)`.
+`refresh()`, `upsert()`, `patch()`, `remove()`, `page()`, `showModal()`, `close()`, `reset()`, `emit()`: `refresh('name')`, `upsert('name', item)`, `patch('name', item, {…})`, `remove('name', item)`, `page('name', 'next' | 'prev' | 'first' | 'last' | n)`, `showModal('id')` opens a dialog by its literal id, `close()` the nearest dialog or `close('id')` that one, `reset()` the nearest form, `emit('event', detail)`.
 
 ## Diagnostics
 
-`SN101 unknown-attribute`, `SN102 wrong-element`, `SN103 missing-key`, `SN104 unsupported-model`, `SN201 unknown-identifier`, `SN202 forbidden-global`, `SN203 side-effect`, `SN204 optimistic-scope`, `SN205 resource-mutation`, `SN206 unknown-namespace-member`, `SN207 unsafe-sink`, `SN208 type-error`, `SN301 unknown-resource`, `SN302 duplicate-resource`, `SN303 unknown-meta-field`, `SN304 keyset-jump`, `SN305 include-not-found`, `SN306 include-cycle`, `SN307 openapi-invalid`, `SN308 unknown-schema-field`, `SN401 parse-error`, `SN501 unused-resource`, `SN502 non-reactive-value`, `SN503 data-bound-id`, `SN504 untyped-resource`, `SN505 unknown-query-param`, `SN506 untyped-event`.
+`SN101 unknown-attribute`, `SN102 wrong-element`, `SN103 missing-key`, `SN104 unsupported-model`, `SN201 unknown-identifier`, `SN202 forbidden-global`, `SN203 side-effect`, `SN204 optimistic-scope`, `SN205 resource-mutation`, `SN206 unknown-namespace-member`, `SN207 unsafe-sink`, `SN208 type-error`, `SN209 name-conflict`, `SN301 unknown-resource`, `SN302 duplicate-resource`, `SN303 unknown-meta-field`, `SN304 keyset-jump`, `SN305 include-not-found`, `SN306 include-cycle`, `SN307 openapi-invalid`, `SN308 unknown-schema-field`, `SN309 unknown-dialog`, `SN310 unknown-action`, `SN401 parse-error`, `SN501 unused-resource`, `SN502 non-reactive-value`, `SN503 data-bound-id`, `SN504 untyped-resource`, `SN505 unknown-query-param`, `SN506 untyped-event`.
 
 ## Recipes
 
@@ -502,6 +508,106 @@ test('the next page load shows the cached list while it revalidates', async () =
 });
 ```
 
+### Local actions: hash a file, then upload it
+
+```html
+<section data-sn-state="{ file: null, url: '', error: '' }">
+  <sn-resource name="digest" call="sha256(file)" when="file"></sn-resource>
+
+  <input type="file" data-sn-on-change="file = $el.files[0] ?? null; url = ''">
+  <p data-sn-show="$meta.digest.loading">Hashing…</p>
+  <code data-sn-text="digest"></code>
+
+  <button data-sn-call="upload(file, digest)" data-sn-attr="{disabled: !digest}"
+          data-sn-then="url = $result.url; error = ''" data-sn-catch="error = $error.message">Upload</button>
+  <a data-sn-show="url" data-sn-attr="{href: url}">Uploaded</a>
+  <p role="alert" data-sn-text="error"></p>
+</section>
+```
+
+```js
+// src/sinter.actions.js: functions pages call with data-sn-call and <sn-resource call>.
+// The last argument is sinter's context; with JSDoc types, `sinter check` checks the calls.
+/** @import { CallContext } from '@tiaforge-ui/sinter' */
+
+/**
+ * The file's SHA-256 as hex; choosing another file aborts the running hash through ctx.signal.
+ * @param {File} file
+ * @param {CallContext} ctx
+ * @returns {Promise<string>}
+ */
+export async function sha256(file, ctx) {
+  const bytes = await file.arrayBuffer();
+  ctx.signal.throwIfAborted();
+  const hash = await crypto.subtle.digest('SHA-256', bytes);
+  return [...new Uint8Array(hash)].map((b) => b.toString(16).padStart(2, '0')).join('');
+}
+
+/**
+ * ctx.request goes through the app's middleware (headers, 401 handling, allowed origins).
+ * @param {File} file
+ * @param {string} digest
+ * @param {CallContext} ctx
+ * @returns {Promise<{ url: string }>}
+ */
+export async function upload(file, digest, ctx) {
+  const form = new FormData();
+  form.append('file', file);
+  form.append('sha256', digest);
+  return /** @type {Promise<{ url: string }>} */ (ctx.request('/api/uploads', { method: 'POST', body: form }));
+}
+```
+
+```ts
+import { expect, test } from 'vitest';
+import { checkPage } from '@tiaforge-ui/sinter/check';
+import { render, mockRequests } from '@tiaforge-ui/sinter/testing';
+import * as actions from './local-actions.actions.js';
+import source from './local-actions.actions.js?raw';
+import page from './local-actions.html?raw';
+
+const DIGEST = 'ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad'; // sha256('abc')
+
+function choose(input: HTMLInputElement, file: File) {
+  Object.defineProperty(input, 'files', { value: [file], configurable: true });
+  input.dispatchEvent(new Event('change', { bubbles: true }));
+}
+
+test('hashes the chosen file, then uploads it with its digest', async () => {
+  const requests = mockRequests({ 'POST /api/uploads': { url: '/files/1' } });
+  const { root, settle } = await render(page, { actions, requests });
+  const button = root.querySelector('button')!;
+  expect(button.disabled).toBe(true);
+
+  choose(root.querySelector('input')!, new File(['abc'], 'abc.txt'));
+  await settle();
+  expect(root.querySelector('code')!.textContent).toBe(DIGEST);
+  expect(button.disabled).toBe(false);
+
+  button.click();
+  await settle();
+  expect((requests.calls[0]!.body as FormData).get('sha256')).toBe(DIGEST);
+  expect(root.querySelector('a')!.getAttribute('href')).toBe('/files/1');
+});
+
+test('a failed upload shows the server message', async () => {
+  const requests = mockRequests({ 'POST /api/uploads': { status: 413, body: { message: 'File too large' } } });
+  const { root, settle } = await render(page, { actions, requests });
+  choose(root.querySelector('input')!, new File(['abc'], 'abc.txt'));
+  await settle();
+  root.querySelector('button')!.click();
+  await settle();
+  expect(root.querySelector('[role=alert]')!.textContent).toBe('File too large');
+});
+
+test('sinter check: arguments are checked against the actions', () => {
+  const files = { 'src/sinter.actions.js': source };
+  expect(checkPage(page, { files })).toEqual([]);
+  const [d] = checkPage(page.replace('upload(file, digest)', 'upload(file)'), { files });
+  expect([d!.code, d!.message]).toEqual(['SN208', expect.stringContaining("is not assignable to type '[file: File, digest: string]'")]);
+});
+```
+
 ## Type checking
 
 `npx sinter check` type-checks every expression with the project's TypeScript (pages and options come from the Vite config). `sinter({ typecheck: true })` runs it in `vite build`.
@@ -525,7 +631,7 @@ Each open EventSource holds one HTTP connection, and HTTP/1.1 allows 6 per origi
 
 Write a test next to the markup. `@tiaforge-ui/sinter/testing` compiles the page with the real compiler and mounts it:
 
-- `render(html, { requests, streams, url, locale, now, helpers, files, storage, session })` → `{ root, app, flush, settle, advance, navigations, window }`. Pass one `memoryStorage()` as `session` to two renders to test what carries over between page loads (the `cache` attribute).
+- `render(html, { requests, streams, url, locale, now, helpers, actions, files, storage, session })` → `{ root, app, flush, settle, advance, navigations, window }`. Pass one `memoryStorage()` as `session` to two renders to test what carries over between page loads (the `cache` attribute).
 - `mockRequests({ 'GET /api/x': json | {status, body} | (call) => … })`: records `calls`; responses are held until `settle()`; an unmatched request fails the test and lists the routes.
 - `mockStream()`: `emit(name, payload)`, `drop()`, `connected`. A stream URL with no mock uses the transport from `configure({ transport })`, so a custom transport can be tested over a fake connection (see the SignalR recipe).
 - `flush()` runs the scheduler (optimistic changes are visible), `settle()` finishes requests, queues and debounces, `advance(ms)` moves sinter's clock.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tiaforge-ui/sinter",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Bind JSON APIs to plain HTML: keyed resources, SSE sync, template bindings and optimistic mutations, compiled at build time.",
   "license": "MIT",
   "author": "Tia Heinrich",
@@ -36,7 +36,9 @@
     "./ws": "./dist/ws.js",
     "./optimistic": "./dist/optimistic.js",
     "./paginate": "./dist/paginate.js",
+    "./each": "./dist/each.js",
     "./persist": "./dist/persist.js",
+    "./listbox": "./dist/listbox.js",
     "./cache": "./dist/cache.js",
     "./compiler": "./dist/compiler/index.js",
     "./vite": "./dist/vite.js",
@@ -57,11 +59,14 @@
     "build": "tsc -p tsconfig.build.json",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "test": "vitest run",
+    "bench": "vitest run --config bench/runtime/vitest.config.ts",
     "size": "npm run build && node scripts/size.mjs",
     "docs": "UPDATE_DOCS=1 vitest run test/docs.test.ts",
+    "release": "node scripts/release.mjs",
     "prepublishOnly": "rm -rf dist && npm run build && npm test"
   },
   "dependencies": {
+    "@sveltejs/acorn-typescript": "^1.0.13",
     "acorn": "^8.19.0",
     "acorn-walk": "^8.3.5",
     "parse5": "^8.1.0",