@ternkit/tern 1.2.1 → 1.3.0

package/dist/goscript/index.svelte.d.ts

@@ -1,3 +1,5 @@
+import { applyPatch, type PatchOp } from './patch.js';
+export { applyPatch, type PatchOp };
 type Instance = {
     call(name: string, args: string): string | null;
     destroy(): void;
@@ -30,9 +32,38 @@ export declare function useGo(id: string, initial: Record<string, unknown>, runt
 declare global {
     var __tern_live_initial: ((id: string, props: string) => string) | undefined;
 }
-export interface LiveComponent extends GoComponent {
+/** A Func of a live component, as the markup sees it. */
+export interface LiveFunc<A extends unknown[] = unknown[], R = unknown> {
+    (...args: A): Promise<R>;
+    /** Whether a call is waiting for the server. */
+    readonly pending: boolean;
+    /** The last call's error message (from goscript.Fail), or null. */
+    readonly error: string | null;
+    /** Calls the Func, showing values for these state names until it returns. */
+    optimistic(values: Record<string, unknown>, ...args: A): Promise<R>;
+    /** A version that waits until calls stop for ms (default 200), for input events. */
+    debounce(ms?: number): (...args: A) => void;
+}
+export interface LiveComponent<S extends Record<string, unknown> = Record<string, unknown>> extends GoComponent {
+    readonly state: S;
     /** The server-rendered state, embedded in the page for hydration. */
     readonly stateScript: string;
+    /** Whether the page is connected to the server. */
+    readonly connected: boolean;
+    /** Whether any call is waiting for the server. */
+    readonly pending: boolean;
+    /** Why the component failed to mount (such as goscript Reject's message), or null. */
+    readonly error: string | null;
+    /** Whether the state has arrived; the markup renders once it has. */
+    readonly loaded: boolean;
+    /** Everything the parent passed, such as children snippets and onevent handlers. */
+    readonly props: Record<string, any>;
+    /** Bindable state: bind:value={live.bind.name} for a State declared with goscript.Bind. */
+    readonly bind: S;
+    /** Sets a State declared with goscript.Bind; the page shows value at once. */
+    set<K extends keyof S & string>(name: K, value: S[K]): Promise<void>;
+    /** The Func named name. */
+    fn<A extends unknown[] = unknown[], R = unknown>(name: string): LiveFunc<A, R>;
 }
 /**
  * Mounts a live Go component; code generated from <script lang="go" live>
@@ -41,4 +72,3 @@ export interface LiveComponent extends GoComponent {
  * /_tern/live, where its Go instance runs.
  */
 export declare function useLive(id: string, uid: string, props: () => Record<string, unknown>): LiveComponent;
-export {};

package/dist/goscript/index.svelte.js

@@ -1,7 +1,10 @@
 // The browser side of the experimental <script lang="go">: loads the app's
 // Go WebAssembly module once, mounts a Go instance per component, and keeps
 // the values Go publishes in Svelte state. See docs/experimental-go-script.md.
+import { untrack } from 'svelte';
 import { getBase } from '../runtime/base.js';
+import { applyPatch } from './patch.js';
+export { applyPatch };
 let loading = null;
 function load(runtime, wasm) {
     loading ??= (async () => {
@@ -65,6 +68,87 @@ export function useGo(id, initial, runtime, wasm, props) {
         }
     };
 }
+function clone(v) {
+    return v === undefined ? v : JSON.parse(JSON.stringify(v));
+}
+/** The browser side of one live component instance. */
+class LiveInstance {
+    id;
+    props;
+    /** What the markup shows: the server's values, or optimistic ones while a call is pending. */
+    state;
+    /** The server's values, as last sent. */
+    #server;
+    #holds = new Map();
+    calls = new Map();
+    pendingCalls = $state({});
+    errors = $state({});
+    error = $state(null);
+    /** Whether the component has its state: from the server render, or the first message. */
+    loaded = $state(false);
+    mounted = false;
+    constructor(id, props, initial) {
+        this.id = id;
+        this.props = props;
+        const { __tern_error: error, ...values } = initial ?? {};
+        this.state = $state(clone(values));
+        this.#server = clone(values);
+        this.loaded = initial !== null;
+        if (typeof error === 'string')
+            this.error = error;
+    }
+    apply(m) {
+        this.loaded = true;
+        for (const [name, v] of Object.entries(m.set ?? {})) {
+            this.#server[name] = clone(v);
+            if (!this.#holds.has(name))
+                this.state[name] = v;
+        }
+        for (const [name, ops] of Object.entries(m.patch ?? {})) {
+            this.#server[name] = applyPatch(this.#server[name], clone(ops));
+            if (!this.#holds.has(name))
+                this.state[name] = applyPatch(this.state[name], ops);
+        }
+    }
+    /** Shows value for name until the operation holding it settles. */
+    hold(name, value) {
+        this.#holds.set(name, (this.#holds.get(name) ?? 0) + 1);
+        this.state[name] = value;
+    }
+    release(names) {
+        for (const name of names) {
+            const n = (this.#holds.get(name) ?? 1) - 1;
+            if (n > 0) {
+                this.#holds.set(name, n);
+                continue;
+            }
+            this.#holds.delete(name);
+            this.state[name] = clone(this.#server[name]);
+        }
+    }
+    begin(seq, call) {
+        this.calls.set(seq, call);
+        this.pendingCalls[call.name] = (this.pendingCalls[call.name] ?? 0) + 1;
+    }
+    settle(seq, value, error) {
+        const call = this.calls.get(seq);
+        if (!call)
+            return;
+        this.calls.delete(seq);
+        this.pendingCalls[call.name] = (this.pendingCalls[call.name] ?? 1) - 1;
+        this.release(call.holds);
+        this.errors[call.name] = error ?? null;
+        if (error)
+            call.reject(new Error(error));
+        else
+            call.resolve(value);
+    }
+    /** The values to restore after reconnecting to a new server process. */
+    snapshot() {
+        return $state.snapshot(this.state);
+    }
+}
+const status = $state({ connected: false });
 class LiveConnection {
     #ws = null;
     #refs = new Map();
@@ -76,6 +160,12 @@ class LiveConnection {
     constructor(url) {
         this.#url = url;
     }
+    #mountMessage(ref, r) {
+        const props = untrack(() => r.props());
+        // After a reconnect, the server has forgotten the instance: values
+        // declared with Bind or Restore come back from what the page shows.
+        return JSON.stringify({ op: 'mount', ref, id: r.id, props, restore: r.mounted ? r.snapshot() : undefined });
+    }
     #connect() {
         const u = new URL(this.#url, location.href);
         u.protocol = u.protocol === 'https:' ? 'wss:' : 'ws:';
@@ -83,40 +173,71 @@ class LiveConnection {
         this.#ws = ws;
         ws.onopen = () => {
             this.#attempt = 0;
-            // After a reconnect, the server has forgotten every instance.
-            for (const [ref, r] of this.#refs)
-                ws.send(JSON.stringify({ op: 'mount', ref, id: r.id, props: r.props() }));
-            for (const m of this.#queue.splice(0))
-                ws.send(m);
+            status.connected = true;
+            for (const [ref, r] of this.#refs) {
+                ws.send(this.#mountMessage(ref, r));
+                r.mounted = true;
+            }
+            for (const m of this.#queue.splice(0)) {
+                if (m.ref !== undefined && !this.#refs.has(m.ref))
+                    continue;
+                ws.send(m.data);
+                if (m.seq !== undefined)
+                    this.#markSent(m.ref, m.seq);
+            }
         };
         ws.onmessage = (e) => {
             const m = JSON.parse(e.data);
             const r = this.#refs.get(m.ref);
             if (!r)
                 return;
-            if (m.op === 'state' && m.name)
-                r.state[m.name] = m.value;
-            else if (m.op === 'result') {
-                r.pending.get(m.seq)?.(m.error ? Promise.reject(new Error(m.error)) : m.value);
-                r.pending.delete(m.seq);
+            if (m.op === 'state')
+                r.apply(m);
+            else if (m.op === 'result')
+                r.settle(m.seq, m.value, m.error);
+            else if (m.op === 'event') {
+                const handler = untrack(() => r.props())['on' + m.name];
+                if (typeof handler === 'function')
+                    handler(m.value);
             }
-            else if (m.op === 'error')
+            else if (m.op === 'error') {
+                r.error = m.error ?? 'error';
+                r.loaded = true;
                 console.error(`[tern] live component ${r.id}: ${m.error}`);
+            }
         };
         ws.onclose = () => {
-            this.#ws = null;
+            if (this.#ws === ws)
+                this.#ws = null;
+            status.connected = false;
+            // Calls that reached the old connection have no answer coming.
+            for (const r of this.#refs.values()) {
+                for (const [seq, call] of r.calls)
+                    if (call.sent)
+                        r.settle(seq, undefined, 'connection lost');
+            }
             if (this.#refs.size === 0)
                 return;
-            const delay = Math.min(10_000, 300 * 2 ** this.#attempt++);
-            setTimeout(() => this.#refs.size && this.#connect(), delay);
+            const delay = Math.min(10_000, 250 * 2 ** this.#attempt++) * (0.75 + Math.random() / 2);
+            setTimeout(() => this.#refs.size && !this.#ws && this.#connect(), delay);
         };
     }
+    #markSent(ref, seq) {
+        const call = this.#refs.get(ref)?.calls.get(seq);
+        if (call)
+            call.sent = true;
+    }
     #send(m) {
         const data = JSON.stringify(m);
-        if (this.#ws?.readyState === WebSocket.OPEN)
+        const seq = m.seq;
+        const ref = m.ref;
+        if (this.#ws?.readyState === WebSocket.OPEN) {
             this.#ws.send(data);
+            if (seq !== undefined)
+                this.#markSent(ref, seq);
+        }
         else {
-            this.#queue.push(data);
+            this.#queue.push({ data, seq, ref });
             if (!this.#ws)
                 this.#connect();
         }
@@ -124,7 +245,12 @@ class LiveConnection {
     mount(r) {
         const ref = this.#nextRef++;
         this.#refs.set(ref, r);
-        this.#send({ op: 'mount', ref, id: r.id, props: r.props() });
+        if (this.#ws?.readyState === WebSocket.OPEN) {
+            this.#ws.send(this.#mountMessage(ref, r));
+            r.mounted = true;
+        }
+        else if (!this.#ws)
+            this.#connect();
         return ref;
     }
     unmount(ref) {
@@ -132,19 +258,44 @@ class LiveConnection {
         if (this.#ws?.readyState === WebSocket.OPEN)
             this.#ws.send(JSON.stringify({ op: 'unmount', ref }));
         if (this.#refs.size === 0) {
-            this.#ws?.close(1000);
+            const ws = this.#ws;
             this.#ws = null;
+            this.#queue = [];
+            ws?.close(1000);
         }
     }
-    call(ref, name, args) {
+    props(ref, props) {
+        this.#send({ op: 'props', ref, props });
+    }
+    call(ref, name, args, optimistic) {
         const r = this.#refs.get(ref);
         if (!r)
-            return Promise.resolve(undefined);
+            return Promise.reject(new Error('not mounted'));
         const seq = this.#seq++;
-        return new Promise((resolve) => {
-            r.pending.set(seq, resolve);
-            this.#send({ op: 'call', ref, seq, name, args });
+        const holds = Object.keys(optimistic ?? {});
+        for (const k of holds)
+            r.hold(k, optimistic[k]);
+        const p = new Promise((resolve, reject) => {
+            r.begin(seq, { resolve, reject, name, holds, sent: false });
         });
+        this.#send({ op: 'call', ref, seq, name, args });
+        // The error is also in fn.error; don't report unawaited calls as
+        // unhandled rejections.
+        p.catch(() => { });
+        return p;
+    }
+    set(ref, name, value) {
+        const r = this.#refs.get(ref);
+        if (!r)
+            return Promise.reject(new Error('not mounted'));
+        const seq = this.#seq++;
+        r.hold(name, value);
+        const p = new Promise((resolve, reject) => {
+            r.begin(seq, { resolve, reject, name: '$set:' + name, holds: [name], sent: false });
+        });
+        this.#send({ op: 'set', ref, seq, name, value: $state.snapshot(value) });
+        p.catch(() => { });
+        return p;
     }
 }
 let connection = null;
@@ -159,7 +310,9 @@ function escapeJSON(s) {
  */
 export function useLive(id, uid, props) {
     const elementID = `tern-live-${uid}`;
-    let initial = {};
+    // After a client-side navigation there is no server-rendered state: the
+    // markup waits for the first message (see the preprocessor).
+    let initial = null;
     let stateScript = '';
     if (typeof window === 'undefined') {
         const raw = globalThis.__tern_live_initial?.(id, JSON.stringify(props())) ?? '{}';
@@ -173,14 +326,13 @@ export function useLive(id, uid, props) {
             stateScript = el.outerHTML;
         }
     }
-    const state = $state(initial);
+    const inst = new LiveInstance(id, props, initial);
     let ref = 0;
     let ready = $state(false);
     if (typeof window !== 'undefined') {
         $effect(() => {
             connection ??= new LiveConnection(`${getBase()}/_tern/live`);
-            const live = { id, props, state, pending: new Map() };
-            ref = connection.mount(live);
+            ref = connection.mount(inst);
             ready = true;
             return () => {
                 connection?.unmount(ref);
@@ -188,17 +340,91 @@ export function useLive(id, uid, props) {
                 ready = false;
             };
         });
+        // New props from the parent go to the server without remounting.
+        let sent = JSON.stringify(untrack(props));
+        $effect(() => {
+            const next = JSON.stringify(props());
+            if (next !== sent && ref) {
+                sent = next;
+                connection.props(ref, JSON.parse(next));
+            }
+        });
     }
+    const call = (name, args, optimistic) => {
+        if (!ref || !connection)
+            return Promise.reject(new Error('not mounted'));
+        return connection.call(ref, name, args.map(toArg), optimistic);
+    };
+    const funcs = new Map();
+    const fn = (name) => {
+        let f = funcs.get(name);
+        if (f)
+            return f;
+        const debounced = new Map();
+        f = Object.assign((...args) => call(name, args), {
+            optimistic: (values, ...args) => call(name, args, values),
+            debounce: (ms = 200) => {
+                let d = debounced.get(ms);
+                if (!d) {
+                    let timer;
+                    d = (...args) => {
+                        const converted = args.map(toArg); // read input values now
+                        clearTimeout(timer);
+                        timer = setTimeout(() => void call(name, converted), ms);
+                    };
+                    debounced.set(ms, d);
+                }
+                return d;
+            }
+        });
+        Object.defineProperties(f, {
+            pending: { get: () => (inst.pendingCalls[name] ?? 0) > 0 },
+            error: { get: () => inst.errors[name] ?? null }
+        });
+        funcs.set(name, f);
+        return f;
+    };
+    const set = (name, value) => {
+        if (!ref || !connection) {
+            inst.state[name] = value;
+            return Promise.resolve();
+        }
+        return connection.set(ref, name, value).then(() => undefined);
+    };
+    const bind = new Proxy({}, {
+        get: (_, name) => (typeof name === 'string' ? inst.state[name] : undefined),
+        set: (_, name, value) => {
+            if (typeof name === 'string')
+                void set(name, value);
+            return true;
+        }
+    });
     return {
-        state,
+        state: inst.state,
         stateScript,
+        bind,
+        fn: fn,
+        set: set,
         get ready() {
             return ready;
         },
+        get props() {
+            return props();
+        },
+        get connected() {
+            return status.connected;
+        },
+        get pending() {
+            return Object.values(inst.pendingCalls).some((n) => n > 0);
+        },
+        get error() {
+            return inst.error;
+        },
+        get loaded() {
+            return inst.loaded;
+        },
         call(name, ...args) {
-            if (!ref || !connection)
-                return undefined;
-            return connection.call(ref, name, args.map(toArg));
+            return call(name, args);
         }
     };
 }

package/dist/goscript/patch.d.ts

@@ -0,0 +1,6 @@
+type Key = string | number;
+/** One patch operation from the server. */
+export type PatchOp = ['s', Key[], unknown] | ['d', Key[]] | ['a', Key[], number, number, unknown[]];
+/** Applies a patch to root and returns the new root. */
+export declare function applyPatch(root: unknown, ops: PatchOp[]): unknown;
+export {};

package/dist/goscript/patch.js

@@ -0,0 +1,25 @@
+// Applying the patches live components send; see internal/jsondiff.
+/** Applies a patch to root and returns the new root. */
+export function applyPatch(root, ops) {
+    for (const op of ops) {
+        const path = op[1];
+        if (path.length === 0) {
+            if (op[0] === 's')
+                root = op[2];
+            else if (op[0] === 'a')
+                root.splice(op[2], op[3], ...op[4]);
+            continue;
+        }
+        let parent = root;
+        for (const k of path.slice(0, -1))
+            parent = parent[k];
+        const last = path[path.length - 1];
+        if (op[0] === 's')
+            parent[last] = op[2];
+        else if (op[0] === 'd')
+            delete parent[last];
+        else
+            parent[last].splice(op[2], op[3], ...op[4]);
+    }
+    return root;
+}

package/dist/index.d.ts

@@ -28,4 +28,4 @@ export type { MessageKey } from './runtime/i18n.svelte.js';
 export interface Messages {
 }
 /** The version of the Tern client runtime. */
-export declare const VERSION = "1.2.1";
+export declare const VERSION = "1.3.0";

package/dist/index.js

@@ -16,4 +16,4 @@ export { stream, socket, EventStreamState, SocketState } from './runtime/realtim
 export { default as Image } from './image/Image.svelte';
 export { t, i18n, setLocale } from './runtime/i18n.svelte.js';
 /** The version of the Tern client runtime. */
-export const VERSION = '1.2.1';
+export const VERSION = '1.3.0';

package/dist/ui/Accordion.svelte

@@ -0,0 +1,84 @@
+<script lang="ts">
+	import type { Snippet } from 'svelte';
+
+	type Item = { id: string; title: string };
+	type Props = {
+		items: Item[];
+		/** The open items' ids; bind it. */
+		open?: string[];
+		/** Let several items be open at once. */
+		multiple?: boolean;
+		/** The heading level of the item titles, to fit the page's outline. */
+		level?: 2 | 3 | 4 | 5 | 6;
+		class?: string;
+		/** Renders an item's content. */
+		content: Snippet<[string]>;
+	};
+	let { items, open = $bindable([]), multiple = false, level = 3, class: klass = '', content }: Props = $props();
+	const uid = $props.id();
+
+	function toggle(id: string) {
+		if (open.includes(id)) open = open.filter((x) => x !== id);
+		else open = multiple ? [...open, id] : [id];
+	}
+</script>
+
+<div class="tern-accordion {klass}">
+	{#each items as item (item.id)}
+		{@const expanded = open.includes(item.id)}
+		<div class="item">
+			<div role="heading" aria-level={level}>
+				<button type="button" id="tern-acc-{uid}-{item.id}" aria-expanded={expanded} aria-controls="tern-acc-{uid}-{item.id}-panel" onclick={() => toggle(item.id)}>
+					{item.title}
+					<svg aria-hidden="true" viewBox="0 0 16 16" width="16" height="16"><path d="M4 6l4 4 4-4" fill="none" stroke="currentColor" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round" /></svg>
+				</button>
+			</div>
+			<div class="panel" role="region" id="tern-acc-{uid}-{item.id}-panel" aria-labelledby="tern-acc-{uid}-{item.id}" hidden={!expanded}>
+				{#if expanded}{@render content(item.id)}{/if}
+			</div>
+		</div>
+	{/each}
+</div>
+
+<style>
+	.tern-accordion {
+		border-top: 1px solid var(--tern-border);
+	}
+	.item {
+		border-bottom: 1px solid var(--tern-border);
+	}
+	button {
+		display: flex;
+		width: 100%;
+		align-items: center;
+		justify-content: space-between;
+		gap: 1rem;
+		padding: 0.85rem 0.25rem;
+		border: 0;
+		background: transparent;
+		font: inherit;
+		font-size: 0.9375rem;
+		font-weight: 550;
+		color: var(--tern-fg);
+		text-align: start;
+		cursor: pointer;
+	}
+	button:focus-visible {
+		outline: 2px solid var(--tern-ring);
+		outline-offset: -2px;
+		border-radius: var(--tern-radius-sm);
+	}
+	svg {
+		flex: none;
+		color: var(--tern-muted);
+		transition: rotate var(--tern-duration);
+	}
+	[aria-expanded='true'] svg {
+		rotate: 180deg;
+	}
+	.panel {
+		padding: 0 0.25rem 1rem;
+		color: var(--tern-muted);
+		font-size: 0.875rem;
+	}
+</style>

package/dist/ui/Accordion.svelte.d.ts

@@ -0,0 +1,20 @@
+import type { Snippet } from 'svelte';
+type Item = {
+    id: string;
+    title: string;
+};
+type Props = {
+    items: Item[];
+    /** The open items' ids; bind it. */
+    open?: string[];
+    /** Let several items be open at once. */
+    multiple?: boolean;
+    /** The heading level of the item titles, to fit the page's outline. */
+    level?: 2 | 3 | 4 | 5 | 6;
+    class?: string;
+    /** Renders an item's content. */
+    content: Snippet<[string]>;
+};
+declare const Accordion: import("svelte").Component<Props, {}, "open">;
+type Accordion = ReturnType<typeof Accordion>;
+export default Accordion;

package/dist/ui/Alert.svelte

@@ -0,0 +1,76 @@
+<script lang="ts">
+	import type { Snippet } from 'svelte';
+
+	type Props = {
+		tone?: 'info' | 'success' | 'warning' | 'danger';
+		title?: string;
+		/** Announce it when it appears: true for messages shown in response to something, false for ones on the page from the start. */
+		live?: boolean;
+		class?: string;
+		children?: Snippet;
+	};
+	let { tone = 'info', title, live = false, class: klass = '', children }: Props = $props();
+	const role = $derived(live ? (tone === 'danger' || tone === 'warning' ? 'alert' : 'status') : undefined);
+	const icons = {
+		info: 'M8 7v4M8 5h.01',
+		success: 'M5 8.5l2 2 4-4.5',
+		warning: 'M8 5v3.5M8 11h.01',
+		danger: 'M6 6l4 4M10 6l-4 4'
+	};
+</script>
+
+<div class="tern-alert {tone} {klass}" {role}>
+	<svg class="icon" viewBox="0 0 16 16" width="18" height="18" aria-hidden="true">
+		<circle cx="8" cy="8" r="6.5" fill="none" stroke="currentColor" stroke-width="1.4" />
+		<path d={icons[tone]} fill="none" stroke="currentColor" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round" />
+	</svg>
+	<div class="text">
+		{#if title}<p class="title">{title}</p>{/if}
+		{#if children}<div class="body">{@render children()}</div>{/if}
+	</div>
+</div>
+
+<style>
+	.tern-alert {
+		display: flex;
+		gap: 0.7rem;
+		padding: 0.85rem 1rem;
+		border-radius: var(--tern-radius);
+		border: 1px solid;
+		font-size: 0.875rem;
+	}
+	.icon {
+		flex: none;
+		margin-top: 0.05rem;
+	}
+	.title {
+		margin: 0;
+		font-weight: 650;
+	}
+	.body {
+		color: var(--tern-fg);
+	}
+	.title + .body {
+		margin-top: 0.2rem;
+	}
+	.info {
+		background: var(--tern-accent-soft);
+		border-color: color-mix(in oklch, var(--tern-accent) 30%, transparent);
+		color: var(--tern-accent);
+	}
+	.success {
+		background: var(--tern-success-soft);
+		border-color: color-mix(in oklch, var(--tern-success) 30%, transparent);
+		color: color-mix(in oklch, var(--tern-success) 80%, var(--tern-fg));
+	}
+	.warning {
+		background: var(--tern-warning-soft);
+		border-color: color-mix(in oklch, var(--tern-warning) 35%, transparent);
+		color: color-mix(in oklch, var(--tern-warning) 55%, var(--tern-fg));
+	}
+	.danger {
+		background: var(--tern-danger-soft);
+		border-color: color-mix(in oklch, var(--tern-danger) 30%, transparent);
+		color: color-mix(in oklch, var(--tern-danger) 85%, var(--tern-fg));
+	}
+</style>

package/dist/ui/Alert.svelte.d.ts

@@ -0,0 +1,12 @@
+import type { Snippet } from 'svelte';
+type Props = {
+    tone?: 'info' | 'success' | 'warning' | 'danger';
+    title?: string;
+    /** Announce it when it appears: true for messages shown in response to something, false for ones on the page from the start. */
+    live?: boolean;
+    class?: string;
+    children?: Snippet;
+};
+declare const Alert: import("svelte").Component<Props, {}, "">;
+type Alert = ReturnType<typeof Alert>;
+export default Alert;