@ternkit/tern 0.0.0-stage → 0.4.0

package/dist/runtime/router.svelte.js

@@ -0,0 +1,506 @@
+import { hydrate, mount, tick } from 'svelte';
+import DefaultError from './DefaultError.svelte';
+import Passthrough from './Passthrough.svelte';
+import Root from './Root.svelte';
+import { DeferredScope, readStreamed, revive } from './deferred.js';
+import { runAfter, runBefore, runOn } from './navigation.js';
+import { plan } from './select.js';
+import { applyPayloadToPage, page, setNavigating } from './state.svelte.js';
+const MAX_REDIRECTS = 20;
+const PRELOAD_TTL = 10_000;
+const SCROLL_KEY = 'tern:scroll';
+let manifest;
+let started = false;
+let token = 0;
+let historyIndex = 0;
+let nodes = [];
+let layoutCount = 0;
+let scrollPositions = {};
+let announcer = null;
+const props = $state({
+    components: [],
+    data: [],
+    form: null
+});
+const preloads = new Map();
+const held = new Map();
+const invalidated = new Set();
+let ignoreNextPop = false;
+/** Marks invalidate() reloads, which are not navigations: no hooks, no navigating state. */
+const RELOAD = Symbol('reload');
+/** Starts the client. Called by the generated entry module. */
+export async function start(m) {
+    manifest = m;
+    const el = document.getElementById('__tern_data');
+    const target = document.getElementById('tern-root');
+    if (!el || !target) {
+        throw new Error('Tern: the page is missing its data or mount point; check that src/app.html contains %tern.head% and %tern.body%');
+    }
+    try {
+        scrollPositions = JSON.parse(sessionStorage.getItem(SCROLL_KEY) ?? '{}');
+    }
+    catch {
+        scrollPositions = {};
+    }
+    historyIndex = history.state?.ternIndex ?? 0;
+    if (history.state?.ternIndex == null) {
+        history.replaceState({ ...history.state, ternIndex: historyIndex, ternState: {} }, '');
+    }
+    history.scrollRestoration = 'manual';
+    const url = new URL(location.href);
+    const payload = JSON.parse(el.textContent ?? '{}');
+    // Deferred values stream in as inline scripts calling __tern_resolve.
+    const w = window;
+    const scope = new DeferredScope();
+    payload.nodes = revive(payload.nodes, (id) => scope.promise(id));
+    for (const chunk of Object.values(w.__tern_d ?? {}))
+        scope.settle(chunk);
+    w.__tern_on = (chunk) => scope.settle(chunk);
+    await render(payload, url, history.state?.ternState ?? {}, token);
+    if (target.hasAttribute('data-tern-ssr')) {
+        hydrate(Root, { target, props });
+    }
+    else {
+        mount(Root, { target, props });
+    }
+    started = true;
+    await tick();
+    runAfter({ from: null, to: current(), type: 'enter' });
+    const saved = scrollPositions[historyIndex];
+    if (saved) {
+        scrollTo(saved.x, saved.y);
+    }
+    else if (url.hash) {
+        scrollToHash(url.hash);
+    }
+    listen();
+}
+/** Navigates to href, which may be relative to the current URL. */
+export async function goto(href, opts = {}) {
+    if (!started) {
+        throw new Error('Tern: goto() was called before the app started');
+    }
+    const url = new URL(href, location.href);
+    if (url.origin !== location.origin) {
+        location.href = url.href;
+        return;
+    }
+    await navigate(url, opts, 'goto', 0);
+}
+/**
+ * Reruns the loads that depend on key, as declared with ctx.Depends(key)
+ * in Go, plus the current page's load.
+ */
+export function invalidate(key) {
+    invalidated.add(key);
+    preloads.clear();
+    return navigate(new URL(location.href), {
+        replaceState: true,
+        noScroll: true,
+        keepFocus: true,
+        state: page.state,
+        [RELOAD]: true
+    }, 'goto', 0);
+}
+/** Reruns every load for the current page. */
+export function invalidateAll() {
+    return navigate(new URL(location.href), {
+        replaceState: true,
+        noScroll: true,
+        keepFocus: true,
+        invalidateAll: true,
+        state: page.state,
+        [RELOAD]: true
+    }, 'goto', 0);
+}
+/**
+ * Loads the data and code for a URL so a later navigation to it is instant.
+ * Tern does this automatically for links; see data-tern-preload.
+ */
+export function preloadData(href) {
+    const url = new URL(href, location.href);
+    const key = url.pathname + url.search;
+    const hit = preloads.get(key);
+    if (hit && Date.now() - hit.at < PRELOAD_TTL) {
+        return hit.promise;
+    }
+    const promise = fetchPayload(url).then(async (p) => {
+        if (p?.type === 'data' && p.route) {
+            await loadRoute(p.route).catch(() => { });
+        }
+        return p;
+    });
+    preloads.set(key, { at: Date.now(), promise });
+    return promise;
+}
+/** Applies a form action result to the page, as `use:enhance` does. */
+export async function applyAction(result) {
+    switch (result.type) {
+        case 'success':
+        case 'failure':
+            page.status = result.status;
+            setForm(result.data ?? null);
+            return;
+        case 'redirect':
+            await goto(result.location, { invalidateAll: true });
+            return;
+        case 'error':
+            await render({
+                type: 'error',
+                route: page.route.id ?? undefined,
+                params: page.params,
+                status: result.status,
+                error: result.error,
+                nodes: nodes.slice(0, layoutCount),
+                failed: layoutCount
+            }, page.url, page.state, token);
+    }
+}
+function setForm(form) {
+    page.form = form;
+    props.form = form;
+}
+function dataURL(url, reuse) {
+    const path = url.pathname.replace(/\/$/, '');
+    let target = `${path}/__data.json${url.search}`;
+    if (reuse) {
+        const here = url.pathname + url.search;
+        const entries = [];
+        for (const [i, h] of held) {
+            if (!h.uses)
+                continue; // no load: nothing to reuse
+            if (h.uses.url && h.url !== here)
+                continue;
+            if (h.uses.deps?.some((d) => invalidated.has(d)))
+                continue;
+            const p = {};
+            for (const name of h.uses.params ?? [])
+                p[name] = h.params[name] ?? '';
+            entries.push({ i, p });
+        }
+        if (entries.length) {
+            target += (url.search ? '&' : '?') + 'x-tern-reuse=' + encodeURIComponent(JSON.stringify(entries));
+        }
+    }
+    return target;
+}
+async function fetchPayload(url, reuse = true) {
+    try {
+        const res = await fetch(dataURL(url, reuse), {
+            headers: { accept: 'application/json' },
+            credentials: 'same-origin'
+        });
+        if (!res.ok || !res.headers.get('content-type')?.includes('application/json')) {
+            return null;
+        }
+        return await readStreamed(res);
+    }
+    catch {
+        return null;
+    }
+}
+function takePreload(url) {
+    const key = url.pathname + url.search;
+    const hit = preloads.get(key);
+    preloads.delete(key);
+    if (hit && Date.now() - hit.at < PRELOAD_TTL) {
+        return hit.promise;
+    }
+    return undefined;
+}
+async function navigate(url, opts, type, redirects, popIndex, fromIndex) {
+    const id = ++token;
+    // A change of hash alone is a scroll, not a navigation.
+    if (type !== 'popstate' && !opts.invalidateAll && url.hash && samePage(url)) {
+        saveScroll();
+        history.pushState({ ternIndex: (historyIndex = historyIndex + 1), ternState: $state.snapshot(opts.state ?? {}) }, '', url);
+        scrollToHash(url.hash);
+        return;
+    }
+    const from = current();
+    const nav = { from, to: { url, params: null, route: { id: null } }, type };
+    const reload = opts[RELOAD] === true;
+    if (!reload && !runBefore(nav, false)) {
+        if (type === 'popstate' && popIndex != null && fromIndex != null) {
+            // The browser already moved; move back to where we were.
+            ignoreNextPop = true;
+            historyIndex = fromIndex;
+            history.go(fromIndex - popIndex);
+        }
+        return;
+    }
+    if (!reload)
+        setNavigating(nav);
+    const payload = await (opts.invalidateAll ? undefined : takePreload(url)) ?? (await fetchPayload(url, !opts.invalidateAll));
+    if (id !== token)
+        return;
+    if (!payload) {
+        location.href = url.href; // not a page, or the server is unreachable
+        return;
+    }
+    if (payload.type === 'redirect' && payload.location) {
+        const next = new URL(payload.location, url);
+        if (redirects >= MAX_REDIRECTS || next.origin !== location.origin) {
+            location.href = next.href;
+            return;
+        }
+        return navigate(next, { ...opts, replaceState: true, [RELOAD]: false }, type, redirects + 1);
+    }
+    if (type !== 'popstate')
+        saveScroll(); // popstate saved before historyIndex changed
+    const state = opts.state ?? (type === 'popstate' ? history.state?.ternState ?? {} : {});
+    nav.to = { url, params: payload.params ?? {}, route: { id: payload.route ?? null } };
+    let finish;
+    const complete = new Promise((resolve) => (finish = resolve));
+    const cleanups = reload ? [] : await runOn(nav, complete);
+    if (id !== token)
+        return;
+    const ok = await render(payload, url, state, id);
+    if (id !== token)
+        return;
+    if (!ok) {
+        location.href = url.href;
+        return;
+    }
+    if (type !== 'popstate') {
+        // History entries must be structured-cloneable: no state proxies.
+        const entry = { ternIndex: historyIndex, ternState: $state.snapshot(state) };
+        if (opts.replaceState) {
+            history.replaceState(entry, '', url);
+        }
+        else {
+            entry.ternIndex = historyIndex = historyIndex + 1;
+            history.pushState(entry, '', url);
+        }
+    }
+    setNavigating(null);
+    await tick();
+    if (type === 'popstate') {
+        const pos = popIndex != null ? scrollPositions[popIndex] : undefined;
+        scrollTo(pos?.x ?? 0, pos?.y ?? 0);
+    }
+    else if (!opts.noScroll) {
+        if (url.hash)
+            scrollToHash(url.hash);
+        else
+            scrollTo(0, 0);
+    }
+    if (!opts.keepFocus) {
+        resetFocus();
+    }
+    invalidated.clear();
+    finish();
+    if (!reload)
+        runAfter(nav);
+    for (const fn of cleanups)
+        fn();
+}
+function samePage(url) {
+    return url.pathname === location.pathname && url.search === location.search;
+}
+function current() {
+    if (!started)
+        return null;
+    return { url: page.url, params: page.params, route: { id: page.route.id } };
+}
+async function loadLayout(i) {
+    const entry = manifest.layouts[i];
+    if (!entry?.component)
+        return Passthrough;
+    return (await entry.component()).default;
+}
+function loadRoute(id) {
+    const route = manifest.routes[id];
+    if (!route)
+        return Promise.reject(new Error(`unknown route ${id}`));
+    return Promise.all([...route.layouts.map(loadLayout), route.page().then((m) => m.default)]);
+}
+/** Renders a payload. It reports false if the payload is not a page. */
+async function render(p, url, state, id) {
+    const route = p.route ? manifest.routes[p.route] : undefined;
+    const layouts = route ? route.layouts : manifest.fallback.layouts;
+    // Fill in the layout data the server skipped because we already have it.
+    if (p.reused?.length) {
+        p.nodes = [...(p.nodes ?? [])];
+        for (const k of p.reused) {
+            const li = layouts[k];
+            p.nodes[k] = li === undefined ? null : (held.get(li)?.data ?? null);
+        }
+    }
+    const what = plan(manifest, p);
+    let components;
+    switch (what.kind) {
+        case 'not-a-page':
+            return false;
+        case 'page':
+            components = await loadRoute(what.route);
+            layoutCount = what.layouts.length;
+            break;
+        case 'error': {
+            const errors = what.route ? manifest.routes[what.route].errors : manifest.fallback.errors;
+            components = [
+                ...(await Promise.all(what.layouts.map(loadLayout))),
+                (await errors[what.errorIndex].component()).default
+            ];
+            layoutCount = what.layouts.length;
+            break;
+        }
+        case 'default-error':
+            components = [DefaultError];
+            layoutCount = 0;
+    }
+    nodes = p.nodes ?? [];
+    if (id !== token)
+        return true; // superseded; the newer navigation renders
+    if (p.type === 'data') {
+        const here = url.pathname + url.search;
+        layouts.forEach((li, k) => {
+            if (p.reused?.includes(k))
+                return;
+            held.set(li, { data: p.nodes?.[k] ?? null, uses: p.uses?.[k] ?? null, params: p.params ?? {}, url: here });
+        });
+    }
+    applyPayloadToPage(p, url, state, what.data);
+    props.components = components;
+    props.data = what.data;
+    props.form = page.form;
+    return true;
+}
+function saveScroll() {
+    scrollPositions[historyIndex] = { x: scrollX, y: scrollY };
+    try {
+        sessionStorage.setItem(SCROLL_KEY, JSON.stringify(scrollPositions));
+    }
+    catch {
+        // Storage can be full or disabled; scroll restoration is best effort.
+    }
+}
+function scrollToHash(hash) {
+    const id = decodeURIComponent(hash.slice(1));
+    const el = document.getElementById(id) ?? document.getElementsByName(id)[0];
+    if (el)
+        el.scrollIntoView();
+    else
+        scrollTo(0, 0);
+}
+/** Moves focus to the document and announces the new page to screen readers. */
+function resetFocus() {
+    const body = document.body;
+    const tabindex = body.getAttribute('tabindex');
+    body.tabIndex = -1;
+    body.focus({ preventScroll: true });
+    if (tabindex === null)
+        body.removeAttribute('tabindex');
+    else
+        body.setAttribute('tabindex', tabindex);
+    if (!announcer) {
+        announcer = document.createElement('div');
+        announcer.setAttribute('aria-live', 'assertive');
+        announcer.setAttribute('aria-atomic', 'true');
+        announcer.style.cssText =
+            'position:absolute;left:0;top:0;clip:rect(0 0 0 0);clip-path:inset(50%);overflow:hidden;white-space:nowrap;width:1px;height:1px';
+        document.body.append(announcer);
+    }
+    announcer.textContent = document.title || page.url.pathname;
+}
+function findAnchor(event) {
+    for (const el of event.composedPath()) {
+        if (el instanceof HTMLAnchorElement || el instanceof SVGAElement)
+            return el;
+    }
+    return null;
+}
+function anchorURL(a) {
+    const href = a instanceof SVGAElement ? a.href.baseVal : a.href;
+    if (!href)
+        return null;
+    const url = new URL(href, document.baseURI);
+    if (url.origin !== location.origin || !/^https?:$/.test(url.protocol))
+        return null;
+    const target = a instanceof SVGAElement ? a.target.baseVal : a.target;
+    if (target && target !== '_self')
+        return null;
+    if (a.hasAttribute('download') || (a.getAttribute('rel') ?? '').split(/\s+/).includes('external'))
+        return null;
+    if (a.closest('[data-tern-reload]:not([data-tern-reload="off"])'))
+        return null;
+    return url;
+}
+function preloadMode(a) {
+    return a.closest('[data-tern-preload]')?.getAttribute('data-tern-preload') ?? 'tap';
+}
+function listen() {
+    document.addEventListener('click', (event) => {
+        if (event.defaultPrevented || event.button !== 0 || event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) {
+            return;
+        }
+        const a = findAnchor(event);
+        const url = a && anchorURL(a);
+        if (!a || !url)
+            return;
+        event.preventDefault();
+        void navigate(url, {
+            noScroll: a.closest('[data-tern-noscroll]') !== null,
+            replaceState: a.closest('[data-tern-replacestate]') !== null || url.href === location.href
+        }, 'link', 0);
+    });
+    let hoverTimer;
+    document.addEventListener('mouseover', (event) => {
+        clearTimeout(hoverTimer);
+        const a = findAnchor(event);
+        const url = a && anchorURL(a);
+        if (!a || !url || preloadMode(a) !== 'hover' || samePage(url))
+            return;
+        hoverTimer = setTimeout(() => void preloadData(url), 20);
+    });
+    const onTap = (event) => {
+        const a = findAnchor(event);
+        const url = a && anchorURL(a);
+        if (!a || !url || preloadMode(a) === 'off' || samePage(url))
+            return;
+        void preloadData(url);
+    };
+    document.addEventListener('mousedown', onTap);
+    document.addEventListener('touchstart', onTap, { passive: true });
+    // GET forms navigate on the client, like links. POST forms are handled
+    // by use:enhance or submit normally.
+    document.addEventListener('submit', (event) => {
+        if (event.defaultPrevented)
+            return;
+        const form = event.target;
+        const submitter = event.submitter;
+        const own = HTMLFormElement.prototype.cloneNode.call(form);
+        const method = submitter?.hasAttribute('formmethod') ? submitter.formMethod : own.method;
+        const target = submitter?.getAttribute('formtarget') ?? own.target;
+        if (method !== 'get' || (target && target !== '_self') || form.closest('[data-tern-reload]:not([data-tern-reload="off"])')) {
+            return;
+        }
+        const url = new URL(submitter?.hasAttribute('formaction') ? submitter.formAction : own.action);
+        if (url.origin !== location.origin)
+            return;
+        event.preventDefault();
+        url.search = new URLSearchParams(new FormData(form, submitter)).toString();
+        const filtering = url.pathname === location.pathname;
+        void navigate(url, { keepFocus: filtering, noScroll: filtering }, 'form', 0);
+    });
+    addEventListener('beforeunload', (event) => {
+        if (!runBefore({ from: current(), to: null, type: 'leave' }, true)) {
+            event.preventDefault();
+            event.returnValue = '';
+        }
+    });
+    addEventListener('popstate', (event) => {
+        if (ignoreNextPop) {
+            ignoreNextPop = false;
+            return;
+        }
+        const index = event.state?.ternIndex;
+        if (index == null)
+            return;
+        saveScroll();
+        const fromIndex = historyIndex;
+        historyIndex = index;
+        void navigate(new URL(location.href), { state: event.state?.ternState ?? {} }, 'popstate', 0, index, fromIndex);
+    });
+    addEventListener('pagehide', saveScroll);
+}

package/dist/runtime/select.d.ts

@@ -0,0 +1,38 @@
+import type { ErrorEntry, Payload } from './types.js';
+/** The parts of a manifest that decide what renders. */
+export interface Tree<C> {
+    routes: Record<string, {
+        layouts: number[];
+        errors: {
+            layouts: number;
+        }[];
+    } & C>;
+    fallback: {
+        layouts: number[];
+        errors: {
+            layouts: number;
+        }[];
+    };
+}
+/** What to render for a payload. Shared by the server and the client so hydration matches. */
+export type Plan = {
+    kind: 'page';
+    route: string;
+    layouts: number[];
+    data: Record<string, unknown>[];
+} | {
+    kind: 'error';
+    route: string | null;
+    layouts: number[];
+    errorIndex: number;
+    data: Record<string, unknown>[];
+} | {
+    kind: 'default-error';
+    data: Record<string, unknown>[];
+} | {
+    kind: 'not-a-page';
+};
+export declare function mergeData(list: (Record<string, unknown> | null | undefined)[]): Record<string, unknown>[];
+/** The innermost error page whose layouts all loaded successfully. */
+export declare function pickErrorPage(errors: Pick<ErrorEntry, 'layouts'>[], failed: number): number;
+export declare function plan<C>(tree: Tree<C>, p: Payload): Plan;

package/dist/runtime/select.js

@@ -0,0 +1,45 @@
+export function mergeData(list) {
+    const out = [];
+    let acc = {};
+    for (const node of list) {
+        acc = { ...acc, ...(node ?? {}) };
+        out.push(acc);
+    }
+    return out;
+}
+/** The innermost error page whose layouts all loaded successfully. */
+export function pickErrorPage(errors, failed) {
+    let pick = -1;
+    errors.forEach((e, i) => {
+        if (e.layouts <= failed)
+            pick = i;
+    });
+    return pick;
+}
+export function plan(tree, p) {
+    const received = p.nodes ?? [];
+    const route = p.route ? tree.routes[p.route] : undefined;
+    if (p.type === 'data') {
+        if (!route || !p.route)
+            return { kind: 'not-a-page' };
+        return { kind: 'page', route: p.route, layouts: route.layouts, data: mergeData(received) };
+    }
+    if (p.type !== 'error' || (p.route && !route)) {
+        return { kind: 'not-a-page' }; // an endpoint, or a non-render result
+    }
+    const layouts = route ? route.layouts : tree.fallback.layouts;
+    const errors = route ? route.errors : tree.fallback.errors;
+    const index = pickErrorPage(errors, p.failed ?? 0);
+    if (index < 0) {
+        return { kind: 'default-error', data: [{}] };
+    }
+    const above = errors[index].layouts;
+    const merged = mergeData(received.slice(0, above));
+    return {
+        kind: 'error',
+        route: p.route ?? null,
+        layouts: layouts.slice(0, above),
+        errorIndex: index,
+        data: [...merged, merged[merged.length - 1] ?? {}]
+    };
+}

package/dist/runtime/state.svelte.d.ts

@@ -0,0 +1,51 @@
+import type { Navigation, Payload } from './types.js';
+declare class PageState {
+    /** The current URL. */
+    url: URL;
+    /** The current route's parameters. */
+    params: Record<string, string>;
+    /** The current route. `id` is null when no route matched. */
+    route: {
+        id: string | null;
+    };
+    /** The HTTP status of the current page. */
+    status: number;
+    /** The error being shown, or null. */
+    error: {
+        message: string;
+    } | null;
+    /** The merged data of every layout and the page. */
+    data: Record<string, unknown>;
+    /** The result of the last form action, or null. */
+    form: unknown;
+    /** State stored with the current history entry (see goto's `state`). */
+    state: Record<string, unknown>;
+}
+/**
+ * Reactive information about the current page. Read it in components or
+ * in `$derived`/`$effect`; it updates on every navigation.
+ *
+ * ```svelte
+ * <script>
+ *   import { page } from '@ternkit/tern';
+ * </script>
+ *
+ * <a href="/" aria-current={page.url.pathname === '/' ? 'page' : undefined}>Home</a>
+ * ```
+ */
+export declare const page: PageState;
+/**
+ * The navigation in progress, or `null`. Use it to show a loading
+ * indicator:
+ *
+ * ```svelte
+ * {#if navigating.current}<Spinner />{/if}
+ * ```
+ */
+export declare const navigating: {
+    readonly current: Navigation | null;
+};
+export declare function setNavigating(n: Navigation | null): void;
+/** Updates page state for a rendered payload. */
+export declare function applyPayloadToPage(p: Payload, url: URL, state: Record<string, unknown>, data: Record<string, unknown>[]): void;
+export {};

package/dist/runtime/state.svelte.js

@@ -0,0 +1,62 @@
+class PageState {
+    /** The current URL. */
+    url = $state(new URL('http://localhost/'));
+    /** The current route's parameters. */
+    params = $state({});
+    /** The current route. `id` is null when no route matched. */
+    route = $state({ id: null });
+    /** The HTTP status of the current page. */
+    status = $state(200);
+    /** The error being shown, or null. */
+    error = $state(null);
+    /** The merged data of every layout and the page. */
+    data = $state({});
+    /** The result of the last form action, or null. */
+    form = $state(null);
+    /** State stored with the current history entry (see goto's `state`). */
+    state = $state({});
+}
+/**
+ * Reactive information about the current page. Read it in components or
+ * in `$derived`/`$effect`; it updates on every navigation.
+ *
+ * ```svelte
+ * <script>
+ *   import { page } from '@ternkit/tern';
+ * </script>
+ *
+ * <a href="/" aria-current={page.url.pathname === '/' ? 'page' : undefined}>Home</a>
+ * ```
+ */
+export const page = new PageState();
+class NavigatingState {
+    current = $state(null);
+}
+const navigatingState = new NavigatingState();
+/**
+ * The navigation in progress, or `null`. Use it to show a loading
+ * indicator:
+ *
+ * ```svelte
+ * {#if navigating.current}<Spinner />{/if}
+ * ```
+ */
+export const navigating = {
+    get current() {
+        return navigatingState.current;
+    }
+};
+export function setNavigating(n) {
+    navigatingState.current = n;
+}
+/** Updates page state for a rendered payload. */
+export function applyPayloadToPage(p, url, state, data) {
+    page.url = url;
+    page.params = p.params ?? {};
+    page.route = { id: p.route ?? null };
+    page.status = p.status;
+    page.error = p.type === 'error' ? (p.error ?? { message: 'Error' }) : null;
+    page.data = data[data.length - 1] ?? {};
+    page.state = state;
+    page.form = p.hasForm ? (p.form ?? null) : null;
+}