@kestack/kabuki 0.0.1 → 0.0.2

package/dist/routing/routing.d.ts

@@ -0,0 +1,72 @@
+import { back, backTo, cached, forward, memory, preload, push, reload, replace } from './capability/index.ts';
+import type { AnyRoute } from './capability/index.ts';
+import { NotFoundError, RedirectError } from './route/index.ts';
+import type { RedirectTo } from './route/index.ts';
+import { Link, Retry, app, define } from './router/index.ts';
+/** A Loader's failure: the place it was asked for is not found. */
+declare const notFound: () => NotFoundError;
+/** How a Redirect is sent: `permanent` is a `308` on the server rather than a `302`. */
+interface RedirectOptions {
+    readonly permanent?: boolean;
+}
+/** A URL outside the app, whole: `https://accounts.example.com/sign-in`. */
+type Href = `http://${string}` | `https://${string}`;
+/**
+ * A Loader's failure: the app goes to `route` instead, in place of the move
+ * that asked; or, given a whole URL, leaves for it. Either replaces the entry.
+ */
+declare function redirect<R extends AnyRoute>(route: R, options?: RedirectOptions): RedirectTo<R>;
+declare function redirect(href: Href, options?: RedirectOptions): RedirectTo<never>;
+/**
+ * Pages: `Page.define` says what one is, an Actor with a place in the URL,
+ * and the pages under it; `Page.build` says how it behaves, with the build
+ * of each page under it. A page is drawn with `View.make`, as any Actor is.
+ * A Loader fails with `Page.notFound()` and `Page.redirect(route or URL)`,
+ * whose Schemas are `Page.NotFound` and `Page.Redirect`.
+ */
+export declare const Page: {
+    define: <const P extends import("./route/node.ts").Fields = {}, const Q extends import("./route/node.ts").Fields = {}, D = never, M extends import("./index.ts").RenderMode | undefined = undefined, const C extends {
+        readonly [name: string]: import("./page/page.ts").AnyPageDefinition;
+    } = {}, Model = {}, State extends import("../core/index.ts").Tagged = {
+        readonly _tag: 'Single';
+    }, Msg extends import("../core/index.ts").Tagged = never, const R extends import("../core/index.ts").Requires = readonly []>(options: import("./page/page.ts").PageOptions<P, Q, D, M, C, Model, State, Msg, R>) => import("./index.ts").PageDefinition<P, Q, C, D, M, Model, State, Msg, R>;
+    build: {
+        <D extends import("./page/page.ts").AnyPageDefinition>(definition: D & ({} extends import("./page/page.ts").PageBehaviorOf<D, {}> ? unknown : never)): import("./page/page.ts").BuiltPage<D, {}>;
+        <D extends import("./page/page.ts").AnyPageDefinition, const B extends import("./page/page.ts").PageBehaviorOf<D, B>>(definition: D, behavior: B): import("./page/page.ts").BuiltPage<D, B>;
+    };
+    notFound: typeof notFound;
+    redirect: typeof redirect;
+    NotFound: typeof NotFoundError;
+    Redirect: typeof RedirectError;
+};
+export declare namespace Page {
+    /** A Loader's failure: the place is not found. */
+    type NotFound = NotFoundError;
+    /** A Loader's failure: go to another Route instead, of type `R` if said, or out of the app. */
+    type Redirect<R = any> = RedirectTo<R>;
+}
+/**
+ * The router: `Router.define` reads an app's router down from its root
+ * page's definition; `Router.app` puts it above the root page's View, as
+ * `Start.app` does; `Link` and `Retry` draw inside it; `push`, `replace`,
+ * `back`, `forward`, `backTo`, `reload` and `preload` are Commands an
+ * Update returns; `memory` is a `Loading` that runs the Loaders in place,
+ * and `cached` puts the Data cache in front of one.
+ */
+export declare const Router: {
+    define: typeof define;
+    app: typeof app;
+    Link: typeof Link;
+    Retry: typeof Retry;
+    memory: typeof memory;
+    cached: typeof cached;
+    push: typeof push;
+    replace: typeof replace;
+    back: typeof back;
+    forward: typeof forward;
+    backTo: typeof backTo;
+    reload: typeof reload;
+    preload: typeof preload;
+};
+export {};
+//# sourceMappingURL=routing.d.ts.map

package/dist/routing/routing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"routing.d.ts","sourceRoot":"","sources":["../../src/routing/routing.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,IAAI,EACJ,MAAM,EACN,MAAM,EACN,OAAO,EACP,MAAM,EACN,OAAO,EACP,IAAI,EACJ,MAAM,EACN,OAAO,EACR,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAEtD,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAChE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAE7D,mEAAmE;AACnE,QAAA,MAAM,QAAQ,qBAA4B,CAAC;AAE3C,wFAAwF;AACxF,UAAU,eAAe;IACvB,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;CAC9B;AAED,4EAA4E;AAC5E,KAAK,IAAI,GAAG,UAAU,MAAM,EAAE,GAAG,WAAW,MAAM,EAAE,CAAC;AAErD;;;GAGG;AACH,iBAAS,QAAQ,CAAC,CAAC,SAAS,QAAQ,EAClC,KAAK,EAAE,CAAC,EACR,OAAO,CAAC,EAAE,eAAe,GACxB,UAAU,CAAC,CAAC,CAAC,CAAC;AACjB,iBAAS,QAAQ,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,UAAU,CAAC,KAAK,CAAC,CAAC;AAa5E;;;;;;GAMG;AACH,eAAO,MAAM,IAAI;;;;;;;;;;;;;;CAOhB,CAAC;AAEF,MAAM,CAAC,OAAO,WAAW,IAAI,CAAC;IAC5B,kDAAkD;IAClD,KAAY,QAAQ,GAAG,aAAa,CAAC;IACrC,+FAA+F;IAC/F,KAAY,QAAQ,CAAC,CAAC,GAAG,GAAG,IAAI,UAAU,CAAC,CAAC,CAAC,CAAC;CAC/C;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,MAAM;;;;;;;;;;;;;;CAclB,CAAC"}

package/dist/routing/routing.js

@@ -0,0 +1,53 @@
+import { back, backTo, cached, forward, memory, preload, push, reload, replace, } from './capability/index.js';
+import { Page as Pages } from './page/index.js';
+import { NotFoundError, RedirectError } from './route/index.js';
+import { Link, Retry, app, define } from './router/index.js';
+/** A Loader's failure: the place it was asked for is not found. */
+const notFound = () => new NotFoundError();
+function redirect(to, options = {}) {
+    // A cast string could name a `javascript:` URL, which the browser would run.
+    if (typeof to === 'string' && !/^https?:\/\//i.test(to))
+        throw new Error(`[@kestack/kabuki/routing] a Redirect leaves only for an http or https URL, not ${to}`);
+    return new RedirectError({
+        ...(typeof to === 'string' ? { href: to } : { route: to }),
+        ...(options.permanent ? { permanent: true } : {}),
+    });
+}
+/**
+ * Pages: `Page.define` says what one is, an Actor with a place in the URL,
+ * and the pages under it; `Page.build` says how it behaves, with the build
+ * of each page under it. A page is drawn with `View.make`, as any Actor is.
+ * A Loader fails with `Page.notFound()` and `Page.redirect(route or URL)`,
+ * whose Schemas are `Page.NotFound` and `Page.Redirect`.
+ */
+export const Page = {
+    define: Pages.define,
+    build: Pages.build,
+    notFound,
+    redirect,
+    NotFound: NotFoundError,
+    Redirect: RedirectError,
+};
+/**
+ * The router: `Router.define` reads an app's router down from its root
+ * page's definition; `Router.app` puts it above the root page's View, as
+ * `Start.app` does; `Link` and `Retry` draw inside it; `push`, `replace`,
+ * `back`, `forward`, `backTo`, `reload` and `preload` are Commands an
+ * Update returns; `memory` is a `Loading` that runs the Loaders in place,
+ * and `cached` puts the Data cache in front of one.
+ */
+export const Router = {
+    define,
+    app,
+    Link,
+    Retry,
+    memory,
+    cached,
+    push,
+    replace,
+    back,
+    forward,
+    backTo,
+    reload,
+    preload,
+};

package/dist/routing/scroll/index.d.ts

@@ -0,0 +1,4 @@
+export { Scrolling, keyOf, restores, useElementScrollRestoration, } from './scroll.tsx';
+export type { HashScroll, ScrollLocation, ScrollRestorationOptions, ScrollingProps, } from './scroll.tsx';
+export { scriptFor } from './script.ts';
+//# sourceMappingURL=index.d.ts.map

package/dist/routing/scroll/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/routing/scroll/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,SAAS,EACT,KAAK,EACL,QAAQ,EACR,2BAA2B,GAC5B,MAAM,cAAc,CAAC;AACtB,YAAY,EACV,UAAU,EACV,cAAc,EACd,wBAAwB,EACxB,cAAc,GACf,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC"}

package/dist/routing/scroll/index.js

@@ -0,0 +1,2 @@
+export { Scrolling, keyOf, restores, useElementScrollRestoration, } from './scroll.js';
+export { scriptFor } from './script.js';

package/dist/routing/scroll/script.d.ts

@@ -0,0 +1,6 @@
+/**
+ * The inline script for a page: it reads the key the Router stamped on the
+ * history entry, under `state`, unless `key` names another.
+ */
+export declare const scriptFor: (state: string, key?: string) => string;
+//# sourceMappingURL=script.d.ts.map

package/dist/routing/scroll/script.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"script.d.ts","sourceRoot":"","sources":["../../../src/routing/scroll/script.ts"],"names":[],"mappings":"AAoDA;;;GAGG;AACH,eAAO,MAAM,SAAS,UAAW,MAAM,QAAQ,MAAM,WACkD,CAAC"}

package/dist/routing/scroll/script.js

@@ -0,0 +1,52 @@
+import { STORAGE } from './session.js';
+/*
+ * The script a server writes at the end of the page, run before the app
+ * hydrates, as TanStack Start's is: it puts the window and every scrolled
+ * element back where the entry left them, so a reload never paints at the
+ * top first. With nothing saved, it goes to the hash's element, or the top.
+ * It runs as a string in the page, so it uses nothing from outside itself.
+ */
+function restore(storage, state, key) {
+    let byKey;
+    try {
+        byKey = JSON.parse(sessionStorage.getItem(storage) || '{}');
+    }
+    catch {
+        return;
+    }
+    const entries = byKey?.[key || history.state?.[state] || ''];
+    let windowRestored = false;
+    for (const selector in entries) {
+        const { scrollX, scrollY } = entries[selector] ?? {};
+        if (!Number.isFinite(scrollX) || !Number.isFinite(scrollY))
+            continue;
+        if (selector === 'window') {
+            scrollTo(scrollX, scrollY);
+            windowRestored = true;
+        }
+        else {
+            try {
+                const element = document.querySelector(selector);
+                if (element) {
+                    element.scrollLeft = scrollX;
+                    element.scrollTop = scrollY;
+                }
+            }
+            catch { }
+        }
+    }
+    if (windowRestored)
+        return;
+    const hash = location.hash.slice(1);
+    if (hash) {
+        document.getElementById(decodeURIComponent(hash))?.scrollIntoView();
+        return;
+    }
+    scrollTo(0, 0);
+}
+const safe = (value) => JSON.stringify(value).replace(/</g, '\\u003c');
+/**
+ * The inline script for a page: it reads the key the Router stamped on the
+ * history entry, under `state`, unless `key` names another.
+ */
+export const scriptFor = (state, key) => `(${restore.toString()})(${safe(STORAGE)},${safe(state)}${key === undefined ? '' : `,${safe(key)}`})`;

package/dist/routing/scroll/scroll.d.ts

@@ -0,0 +1,75 @@
+import type { ReactNode } from 'react';
+import type { Position } from './selector.ts';
+/** How an element is scrolled into view, as `Element.scrollIntoView` takes it. */
+export type HashScroll = boolean | {
+    readonly behavior?: 'auto' | 'instant' | 'smooth';
+    readonly block?: 'start' | 'center' | 'end' | 'nearest';
+    readonly inline?: 'start' | 'center' | 'end' | 'nearest';
+};
+/** Where an app is, as scroll restoration reads it. */
+export interface ScrollLocation<Route = {
+    readonly _tag: string;
+}> {
+    readonly route: Route;
+    /** Its path and query, as the address writes it. */
+    readonly path: string;
+    /** The key of its history entry. */
+    readonly key: string;
+}
+/** Scroll restoration's options on `Router.app`, named as TanStack Router's. */
+export interface ScrollRestorationOptions<Route = {
+    readonly _tag: string;
+}> {
+    /** Whether it restores scroll at all, or where: off unless said. */
+    readonly scrollRestoration?: boolean | ((options: {
+        readonly route: Route;
+    }) => boolean);
+    /** What positions are kept under: the entry's key unless said, its `path` to keep one per URL. */
+    readonly getScrollRestorationKey?: (location: ScrollLocation<Route>) => string;
+    /** Elements, by selector or function, that go to the top on a move to a new entry rather than keep where they were. */
+    readonly scrollToTopSelectors?: ReadonlyArray<string | (() => Element | null | undefined)>;
+    /** How it scrolls: `instant`, `smooth` or `auto`. */
+    readonly scrollRestorationBehavior?: 'auto' | 'instant' | 'smooth';
+    /** How a hash's element is scrolled into view when a move does not say: `true` unless said. */
+    readonly defaultHashScrollIntoView?: HashScroll;
+}
+/** What the Router hands Scrolling: its options, and the move drawn. */
+export interface ScrollingProps {
+    readonly options: ScrollRestorationOptions<never>;
+    /** Where the app is drawn. */
+    readonly at: ScrollLocation;
+    /** The element on the page its entry goes to. */
+    readonly hash: string | undefined;
+    readonly move: {
+        readonly how: 'load' | 'push' | 'replace' | 'back' | 'forward';
+        readonly resetScroll?: boolean | undefined;
+        readonly hashScrollIntoView?: HashScroll | undefined;
+    };
+    /** Whether a move is held: the entry may already be the one it goes to. */
+    readonly pending: boolean;
+    /** Whether an Adapter holds the address: positions are saved for a reload. */
+    readonly attached: boolean;
+    /** Whether the Adapter has said which entry the app opened at: before, its key is not known. */
+    readonly loaded: boolean;
+    readonly children: ReactNode;
+}
+/** Whether scroll restoration is on at a Route. */
+export declare const restores: (options: ScrollRestorationOptions<never>, route: unknown) => boolean;
+/** The restoration key of a location. */
+export declare const keyOf: (options: ScrollRestorationOptions<never>, at: ScrollLocation) => string;
+/**
+ * Around the app, inside the Router: tracks what scrolls, and puts it back
+ * as every move lands.
+ */
+export declare function Scrolling(props: ScrollingProps): import("react").JSX.Element;
+/**
+ * Where an element, or the window, was scrolled on the entry drawn, as kept
+ * for it: for a list that restores itself, as a virtualized one does. Name
+ * it by its `data-scroll-restoration-id`, or hand it over.
+ */
+export declare const useElementScrollRestoration: (options: {
+    readonly id: string;
+} | {
+    readonly getElement: () => Element | Window | null | undefined;
+}) => Position | undefined;
+//# sourceMappingURL=scroll.d.ts.map

package/dist/routing/scroll/scroll.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scroll.d.ts","sourceRoot":"","sources":["../../../src/routing/scroll/scroll.tsx"],"names":[],"mappings":"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"}

package/dist/routing/scroll/scroll.js

@@ -0,0 +1,201 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, use, useLayoutEffect, useRef, useState } from 'react';
+import { useLive } from '../../react/index.js';
+import { ID, WINDOW, elementOf, selectorOf } from './selector.js';
+import * as session from './session.js';
+/** Whether scroll restoration is on at a Route. */
+export const restores = (options, route) => typeof options.scrollRestoration === 'function'
+    ? options.scrollRestoration({ route })
+    : options.scrollRestoration === true;
+/** The restoration key of a location. */
+export const keyOf = (options, at) => options.getScrollRestorationKey?.(at) ?? at.key;
+const FrameContext = createContext(undefined);
+/**
+ * Around the app, inside the Router: tracks what scrolls, and puts it back
+ * as every move lands.
+ */
+export function Scrolling(props) {
+    const live = useLive();
+    const on = restores(props.options, props.at.route);
+    const key = keyOf(props.options, props.at);
+    const latest = useRef({ props, live, on });
+    latest.current = { props, live, on };
+    const [s] = useState(() => ({
+        positions: undefined,
+        /** The restoration key drawn: through a held move, still the one before it. */
+        key,
+        /** Our own scrolling, which is not the user's. */
+        ignore: false,
+        /** The move last restored for, as one string. */
+        last: undefined,
+    }));
+    const positions = () => (s.positions ??= latest.current.props.attached ? session.read() : {});
+    const save = () => {
+        if (latest.current.props.attached && s.positions)
+            session.write(s.positions);
+    };
+    const [frame] = useState(() => ({
+        entry: (name) => positions()[s.key]?.[name],
+    }));
+    // 1. Track, and 4. save.
+    useLayoutEffect(() => {
+        const scrolled = (event) => {
+            if (s.ignore || !latest.current.live || !latest.current.on)
+                return;
+            const target = event.target;
+            const kept = (positions()[s.key] ??= {});
+            if (target === document || target === document.documentElement)
+                kept[WINDOW] = { scrollX, scrollY };
+            else if (target instanceof Element && target.isConnected)
+                kept[selectorOf(target)] = {
+                    scrollX: target.scrollLeft,
+                    scrollY: target.scrollTop,
+                };
+        };
+        const hidden = () => {
+            // The browser may put a reload back too; ours runs from what is saved.
+            history.scrollRestoration = 'auto';
+            save();
+        };
+        const shown = (event) => {
+            if (event.persisted && latest.current.on)
+                history.scrollRestoration = 'manual';
+        };
+        document.addEventListener('scroll', scrolled, {
+            capture: true,
+            passive: true,
+        });
+        addEventListener('pagehide', hidden);
+        addEventListener('pageshow', shown);
+        return () => {
+            save();
+            document.removeEventListener('scroll', scrolled, { capture: true });
+            removeEventListener('pagehide', hidden);
+            removeEventListener('pageshow', shown);
+        };
+        // oxlint-disable-next-line react-hooks/exhaustive-deps -- set up once; it reads the latest through refs.
+    }, []);
+    // Kabuki puts scroll back, not the browser, while it is on.
+    const manual = on && props.attached;
+    useLayoutEffect(() => {
+        if (!manual || !('scrollRestoration' in history))
+            return;
+        const before = history.scrollRestoration;
+        history.scrollRestoration = 'manual';
+        return () => {
+            history.scrollRestoration = before;
+        };
+    }, [manual]);
+    // 2. Carry, and 3. restore, after every move.
+    const settled = props.move.how !== 'load' || props.loaded;
+    const move = `${key} ${props.move.how} ${props.hash ?? ''} ${props.at.path}`;
+    useLayoutEffect(() => {
+        if (!live || props.pending || !settled)
+            return;
+        const from = s.key;
+        s.key = key;
+        if (s.last === move)
+            return;
+        s.last = move;
+        if (!on)
+            return;
+        const options = latest.current.props.options;
+        const { how } = props.move;
+        const reset = props.move.resetScroll !== false;
+        const hashing = how === 'push' || how === 'replace';
+        const hashScroll = props.move.hashScrollIntoView ??
+            options.defaultHashScrollIntoView ??
+            true;
+        const kept = positions();
+        let toTop;
+        const toTopElements = () => (toTop ??= new Set((options.scrollToTopSelectors ?? [])
+            .filter((selector) => selector !== WINDOW)
+            .map(elementOf)
+            .filter((element) => element !== undefined)));
+        // 2. Carry
+        const before = kept[from];
+        if (before && from !== key) {
+            const after = (kept[key] ??= {});
+            for (const name in before) {
+                if (name === WINDOW) {
+                    if (reset)
+                        continue;
+                }
+                else {
+                    const element = elementOf(name);
+                    if (!element)
+                        continue;
+                    if (reset && toTopElements().has(element))
+                        continue;
+                }
+                after[name] ??= before[name];
+            }
+        }
+        // 3. Restore
+        {
+            const behavior = options.scrollRestorationBehavior;
+            const hash = props.hash;
+            s.ignore = true;
+            try {
+                let windowRestored = false;
+                if (reset) {
+                    const skipWindow = Boolean(hash && hashScroll && hashing);
+                    const tops = hash ? undefined : new Set(toTopElements());
+                    for (const name in kept[key] ?? {}) {
+                        const { scrollX: left, scrollY: top } = kept[key][name];
+                        if (name === WINDOW) {
+                            if (skipWindow)
+                                continue;
+                            scrollTo({ top, left, ...(behavior ? { behavior } : {}) });
+                            windowRestored = true;
+                        }
+                        else {
+                            const element = elementOf(name);
+                            if (!element)
+                                continue;
+                            element.scrollLeft = left;
+                            element.scrollTop = top;
+                            tops?.delete(element);
+                        }
+                    }
+                    if (!hash) {
+                        const origin = {
+                            top: 0,
+                            left: 0,
+                            ...(behavior ? { behavior } : {}),
+                        };
+                        if (!windowRestored)
+                            scrollTo(origin);
+                        for (const element of tops ?? [])
+                            element.scrollTo(origin);
+                    }
+                }
+                if (!windowRestored && hash && hashScroll)
+                    document
+                        .getElementById(hash)
+                        ?.scrollIntoView(hashScroll === true ? undefined : hashScroll);
+            }
+            finally {
+                s.ignore = false;
+            }
+        }
+        // oxlint-disable-next-line react-hooks/exhaustive-deps -- `move` is the move, as one string.
+    }, [move, props.pending, live, settled, on]);
+    return _jsx(FrameContext, { value: frame, children: props.children });
+}
+/**
+ * Where an element, or the window, was scrolled on the entry drawn, as kept
+ * for it: for a list that restores itself, as a virtualized one does. Name
+ * it by its `data-scroll-restoration-id`, or hand it over.
+ */
+export const useElementScrollRestoration = (options) => {
+    const frame = use(FrameContext);
+    if (!frame)
+        return undefined;
+    if ('id' in options)
+        return frame.entry(`[${ID}="${options.id}"]`);
+    const element = options.getElement();
+    if (!element)
+        return undefined;
+    return frame.entry(element === window ? WINDOW : selectorOf(element));
+};

package/dist/routing/scroll/selector.d.ts

@@ -0,0 +1,14 @@
+export declare const WINDOW = "window";
+export declare const ID = "data-scroll-restoration-id";
+/** Where an element or the window was scrolled to. */
+export interface Position {
+    readonly scrollX: number;
+    readonly scrollY: number;
+}
+/** Every saved position: by restoration key, then by element. */
+export type Positions = Record<string, Record<string, Position>>;
+/** An element's name: `[data-scroll-restoration-id="list"]`, or `main:nth-child(2) > ul:nth-child(1)`. */
+export declare const selectorOf: (element: Element) => string;
+/** The element a selector, or a function, names now; none if it is gone. */
+export declare const elementOf: (selector: string | (() => Element | null | undefined)) => Element | undefined;
+//# sourceMappingURL=selector.d.ts.map

package/dist/routing/scroll/selector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"selector.d.ts","sourceRoot":"","sources":["../../../src/routing/scroll/selector.ts"],"names":[],"mappings":"AAOA,eAAO,MAAM,MAAM,WAAW,CAAC;AAC/B,eAAO,MAAM,EAAE,+BAA+B,CAAC;AAE/C,sDAAsD;AACtD,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,iEAAiE;AACjE,MAAM,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC,CAAC;AAEjE,0GAA0G;AAC1G,eAAO,MAAM,UAAU,YAAa,OAAO,KAAG,MAgB7C,CAAC;AAEF,4EAA4E;AAC5E,eAAO,MAAM,SAAS,aACV,MAAM,GAAG,CAAC,MAAM,OAAO,GAAG,IAAI,GAAG,SAAS,CAAC,KACpD,OAAO,GAAG,SAUZ,CAAC"}

package/dist/routing/scroll/selector.js

@@ -0,0 +1,40 @@
+/*
+ * How a scrolled element is named in the saved positions, as TanStack
+ * Router names it, so its inline script and the Router agree: by its
+ * `data-scroll-restoration-id`, else by its path from the document, each
+ * step its tag and its place among its siblings. The window is `window`.
+ */
+export const WINDOW = 'window';
+export const ID = 'data-scroll-restoration-id';
+/** An element's name: `[data-scroll-restoration-id="list"]`, or `main:nth-child(2) > ul:nth-child(1)`. */
+export const selectorOf = (element) => {
+    const id = element.getAttribute(ID);
+    if (id)
+        return `[${ID}="${id}"]`;
+    let selector = '';
+    let at = element;
+    let parent;
+    while ((parent = at.parentNode)) {
+        let index = 1;
+        let sibling = at;
+        while ((sibling = sibling.previousElementSibling))
+            index++;
+        const part = `${at.localName}:nth-child(${index})`;
+        selector = selector ? `${part} > ${selector}` : part;
+        if (!(parent instanceof Element))
+            break;
+        at = parent;
+    }
+    return selector;
+};
+/** The element a selector, or a function, names now; none if it is gone. */
+export const elementOf = (selector) => {
+    try {
+        return ((typeof selector === 'function'
+            ? selector()
+            : document.querySelector(selector)) ?? undefined);
+    }
+    catch {
+        return undefined;
+    }
+};

package/dist/routing/scroll/session.d.ts

@@ -0,0 +1,6 @@
+import type { Positions } from './selector.ts';
+export declare const STORAGE = "@kestack/kabuki/routing:scroll";
+/** What the last page load in this tab saved, or nothing. */
+export declare const read: () => Positions;
+export declare const write: (positions: Positions) => void;
+//# sourceMappingURL=session.d.ts.map

package/dist/routing/scroll/session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../../../src/routing/scroll/session.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAS/C,eAAO,MAAM,OAAO,mCAAmC,CAAC;AAExD,6DAA6D;AAC7D,eAAO,MAAM,IAAI,QAAO,SASvB,CAAC;AAEF,eAAO,MAAM,KAAK,cAAe,SAAS,SAIzC,CAAC"}

package/dist/routing/scroll/session.js

@@ -0,0 +1,23 @@
+/*
+ * The browser's session storage, for the positions to outlast a reload:
+ * one tab's own, copied when the tab is duplicated, empty in a new one.
+ * Read once, written when the page is hidden. Storage that is full, or
+ * missing, keeps nothing.
+ */
+export const STORAGE = '@kestack/kabuki/routing:scroll';
+/** What the last page load in this tab saved, or nothing. */
+export const read = () => {
+    try {
+        const saved = JSON.parse(globalThis.sessionStorage?.getItem(STORAGE) || '{}');
+        return saved && typeof saved === 'object' ? saved : {};
+    }
+    catch {
+        return {};
+    }
+};
+export const write = (positions) => {
+    try {
+        globalThis.sessionStorage?.setItem(STORAGE, JSON.stringify(positions));
+    }
+    catch { }
+};

package/dist/start/client/client.d.ts

@@ -0,0 +1,11 @@
+import type { Root } from 'react-dom/client';
+import type { StartApp } from '../common/index.ts';
+/** The page once hydrated: its React root, and how to draw it again with new code. */
+export interface Hydrated {
+    readonly root: Root;
+    /** Draw the page again with new code, as after a hot reload: the app carries on from its History. */
+    readonly redraw: (app: StartApp) => void;
+}
+/** Hydrates the page a server drew. */
+export declare const client: (exported: StartApp) => Promise<Hydrated>;
+//# sourceMappingURL=client.d.ts.map

package/dist/start/client/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../../src/start/client/client.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAc7C,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAmBnD,sFAAsF;AACtF,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;IACpB,qGAAqG;IACrG,QAAQ,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,QAAQ,KAAK,IAAI,CAAC;CAC1C;AAMD,uCAAuC;AACvC,eAAO,MAAM,MAAM,aAAoB,QAAQ,KAAG,OAAO,CAAC,QAAQ,CAkCjE,CAAC"}

package/dist/start/client/client.js

@@ -0,0 +1,24 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { hydrateRoot } from 'react-dom/client';
+import { Layer } from 'effect';
+import { View, toReact } from '../../react/index.js';
+import { Router } from '../../routing/index.js';
+import { browser } from '../../routing/adapter/browser/index.js';
+import { Document as Plain, PageContext, RuntimeContext, appOf, readPage, } from '../common/index.js';
+import { loading } from './rpc.js';
+/** Hydrates the page a server drew. */
+export const client = async (exported) => {
+    // 1. Read
+    const drawn = readPage(document);
+    // 2. Preload
+    await View.preload(Array.from(document.querySelectorAll('link[data-kabuki-view]'), (link) => link.getAttribute('data-kabuki-view')));
+    const page = (next) => {
+        const { app, document: Document = Plain, layer } = appOf(next);
+        const App = toReact(app.actor, app.view, Layer.mergeAll(browser(), Router.cached(app.routes, loading(app.routes)), layer ?? Layer.empty));
+        return (_jsx(PageContext, { value: drawn, children: _jsx(RuntimeContext, { value: App.useRuntime, children: _jsx(Document, { children: _jsx(App, { saved: drawn.page.saved }) }) }) }));
+    };
+    // 3. Hydrate
+    const root = hydrateRoot(document, page(exported));
+    // 4. Redraw
+    return { root, redraw: (next) => root.render(page(next)) };
+};

package/dist/start/client/index.d.ts

@@ -0,0 +1,3 @@
+export { client } from './client.tsx';
+export { loading } from './rpc.ts';
+//# sourceMappingURL=index.d.ts.map

package/dist/start/client/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/start/client/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AACtC,OAAO,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC"}

package/dist/start/client/index.js

@@ -0,0 +1,2 @@
+export { client } from './client.js';
+export { loading } from './rpc.js';