@ternkit/tern 0.0.0-stage → 0.3.1

package/dist/runtime/router.svelte.js

@@ -0,0 +1,388 @@
+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 { 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();
+/** 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 ?? Date.now();
+    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;
+    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 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
+    }, '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) {
+    const path = url.pathname.replace(/\/$/, '');
+    return `${path}/__data.json${url.search}`;
+}
+async function fetchPayload(url) {
+    try {
+        const res = await fetch(dataURL(url), {
+            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) {
+    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 = Date.now()), ternState: $state.snapshot(opts.state ?? {}) }, '', url);
+        scrollToHash(url.hash);
+        return;
+    }
+    const from = current();
+    setNavigating({ from, to: { url, params: null, route: { id: null } }, type });
+    const payload = await (opts.invalidateAll ? undefined : takePreload(url)) ?? (await fetchPayload(url));
+    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 }, type, redirects + 1);
+    }
+    if (type !== 'popstate')
+        saveScroll(); // popstate saved before historyIndex changed
+    const state = opts.state ?? (type === 'popstate' ? history.state?.ternState ?? {} : {});
+    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 = Date.now();
+            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();
+    }
+}
+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 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
+    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 });
+    addEventListener('popstate', (event) => {
+        const index = event.state?.ternIndex;
+        if (index == null)
+            return;
+        saveScroll();
+        historyIndex = index;
+        void navigate(new URL(location.href), { state: event.state?.ternState ?? {} }, 'popstate', 0, index);
+    });
+    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;
+}

package/dist/runtime/types.d.ts

@@ -0,0 +1,91 @@
+import type { Component } from 'svelte';
+/** A lazily imported Svelte component module. */
+export type ComponentLoader = () => Promise<{
+    default: Component<any>;
+}>;
+export interface LayoutEntry {
+    dir: string;
+    component: ComponentLoader | null;
+    hasLoad: boolean;
+}
+export interface ErrorEntry {
+    /** How many of the route's layouts wrap this error page. */
+    layouts: number;
+    component: ComponentLoader;
+}
+export interface RouteEntry {
+    layouts: number[];
+    page: ComponentLoader;
+    hasLoad: boolean;
+    errors: ErrorEntry[];
+}
+/** The client manifest generated by `tern gen` in .tern/generated/manifest.js. */
+export interface ClientManifest {
+    layouts: LayoutEntry[];
+    routes: Record<string, RouteEntry>;
+    fallback: {
+        layouts: number[];
+        errors: ErrorEntry[];
+    };
+}
+/** What the server sends for a page, inline or from __data.json. */
+export interface Payload {
+    type: 'data' | 'error' | 'redirect' | 'success' | 'failure';
+    route?: string;
+    params?: Record<string, string>;
+    status: number;
+    nodes?: (Record<string, unknown> | null)[];
+    failed?: number;
+    error?: {
+        message: string;
+    };
+    location?: string;
+    data?: unknown;
+    form?: unknown;
+    hasForm?: boolean;
+}
+/** The result of submitting a form action with `use:enhance`. */
+export type ActionResult<Success = Record<string, unknown>, Failure = Record<string, unknown>> = {
+    type: 'success';
+    status: number;
+    data?: Success;
+} | {
+    type: 'failure';
+    status: number;
+    data?: Failure;
+} | {
+    type: 'redirect';
+    status: number;
+    location: string;
+} | {
+    type: 'error';
+    status: number;
+    error: {
+        message: string;
+    };
+};
+export interface NavigationTarget {
+    url: URL;
+    params: Record<string, string> | null;
+    route: {
+        id: string | null;
+    };
+}
+export type NavigationType = 'enter' | 'link' | 'goto' | 'popstate' | 'form';
+export interface Navigation {
+    from: NavigationTarget | null;
+    to: NavigationTarget | null;
+    type: NavigationType;
+}
+export interface GotoOptions {
+    /** Replace the current history entry instead of adding one. */
+    replaceState?: boolean;
+    /** Keep the scroll position instead of scrolling to the top. */
+    noScroll?: boolean;
+    /** Keep focus on the currently focused element. */
+    keepFocus?: boolean;
+    /** Rerun every load, even for the current URL. */
+    invalidateAll?: boolean;
+    /** State to store in the history entry, available as page.state. */
+    state?: Record<string, unknown>;
+}

package/dist/runtime/types.js

@@ -0,0 +1 @@
+export {};