@kestack/kabuki 0.0.1 → 0.0.2

package/dist/routing/router/context.js

@@ -0,0 +1,156 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+// oxlint-disable-next-line no-restricted-imports -- the Metadata is written to the document, and a link watches its hover and its place on screen: each only an effect may do.
+import { createContext, use, useEffect, useRef } from 'react';
+import { MANAGED, tagsOf } from '../route/index.js';
+export const RouterContext = createContext(undefined);
+/** What a link says its push leaves the scroll as: `false`, as it is. */
+const RESET_SCROLL = 'data-reset-scroll';
+/** How a link says its hash's element is scrolled into view, as JSON. */
+const HASH_SCROLL = 'data-hash-scroll-into-view';
+/** What a link clicked says besides where it goes: its hash, and what its `Router.Link` said of scroll. */
+export const linkOptions = (link, url) => {
+    const hash = decodeURIComponent(url.hash.slice(1));
+    const said = link.getAttribute(HASH_SCROLL);
+    let hashScrollIntoView;
+    try {
+        hashScrollIntoView = said === null ? undefined : JSON.parse(said);
+    }
+    catch { }
+    return {
+        ...(link.getAttribute(RESET_SCROLL) === 'false'
+            ? { resetScroll: false }
+            : {}),
+        ...(hash ? { hash } : {}),
+        ...(hashScrollIntoView === undefined ? {} : { hashScrollIntoView }),
+    };
+};
+export const useDrawing = (what) => {
+    const drawing = use(RouterContext);
+    if (!drawing)
+        throw new Error(`[@kestack/kabuki/routing] ${what} is drawn outside a Router.app`);
+    return drawing;
+};
+/**
+ * Writes the Metadata to the document after every move, and when a page's
+ * data comes: the title, and every tag marked `data-kabuki`, which replace
+ * the ones marked before. Tags nobody marked are left alone, and an app
+ * routing in memory never touches the document.
+ */
+export function MetadataWriter({ metadata }) {
+    const tags = tagsOf(metadata);
+    const written = JSON.stringify([metadata.title, tags]);
+    useEffect(() => {
+        if (metadata.title !== undefined)
+            document.title = metadata.title;
+        for (const old of document.head.querySelectorAll(`[${MANAGED}]`))
+            old.remove();
+        for (const { tag, attributes } of tags) {
+            const element = document.createElement(tag);
+            for (const [name, value] of Object.entries(attributes))
+                element.setAttribute(name, value);
+            document.head.append(element);
+        }
+        // oxlint-disable-next-line react-hooks/exhaustive-deps -- `written` is the Metadata, as one string.
+    }, [written]);
+    return null;
+}
+/**
+ * A link to a Route. It draws a plain `<a href>`, so a new tab, a copied
+ * link and a crawler all see the real URL; the router catches a plain click.
+ * It asks the Router to preload where it goes, as `preload` says: each ask
+ * is one Message, so the Timeline shows it.
+ */
+export function Link({ to, preload, preloadDelay, resetScroll, hash, hashScrollIntoView, onMouseEnter, onMouseLeave, onFocus, onBlur, onTouchStart, ...rest }) {
+    const drawing = useDrawing('Router.Link');
+    const mode = preload ?? drawing.linkPreload.mode;
+    const wait = preloadDelay ?? drawing.linkPreload.delay;
+    const ref = useRef(null);
+    const timer = useRef(undefined);
+    const latest = useRef({ to, ask: drawing.preload });
+    latest.current = { to, ask: drawing.preload };
+    const href = `${drawing.href(to)}${hash ? `#${encodeURIComponent(hash)}` : ''}`;
+    useEffect(() => {
+        const link = ref.current;
+        if (mode !== 'viewport' ||
+            !link ||
+            typeof IntersectionObserver === 'undefined')
+            return;
+        const seen = new IntersectionObserver((entries) => {
+            if (!entries.some((entry) => entry.isIntersecting))
+                return;
+            seen.disconnect();
+            latest.current.ask(latest.current.to);
+        });
+        seen.observe(link);
+        return () => seen.disconnect();
+    }, [mode, href]);
+    useEffect(() => () => clearTimeout(timer.current), []);
+    const intend = () => {
+        if (mode !== 'intent')
+            return;
+        clearTimeout(timer.current);
+        timer.current = setTimeout(() => latest.current.ask(latest.current.to), wait);
+    };
+    const drop = () => clearTimeout(timer.current);
+    return (_jsx("a", { ...rest, ref: ref, href: href, ...(resetScroll === false ? { [RESET_SCROLL]: 'false' } : {}), ...(hashScrollIntoView === undefined
+            ? {}
+            : { [HASH_SCROLL]: JSON.stringify(hashScrollIntoView) }), onMouseEnter: (event) => {
+            intend();
+            onMouseEnter?.(event);
+        }, onMouseLeave: (event) => {
+            drop();
+            onMouseLeave?.(event);
+        }, onFocus: (event) => {
+            intend();
+            onFocus?.(event);
+        }, onBlur: (event) => {
+            drop();
+            onBlur?.(event);
+        }, onTouchStart: (event) => {
+            if (mode === 'intent')
+                latest.current.ask(latest.current.to);
+            onTouchStart?.(event);
+        } }));
+}
+/**
+ * The router, for a component drawn inside a `Router.app`: an address bar, a
+ * history list, a retry button. Name the app's Route,
+ * `useRouter<Route>()` with `type Route = typeof router.route.Type`, to read
+ * its Routes as that type: every Route the Router holds is one of them.
+ */
+export const useRouter = () => {
+    const drawing = useDrawing('useRouter');
+    const { entries, at, go, move, pending, metadata } = drawing;
+    const route = entries[at].route;
+    const state = {
+        route,
+        href: drawing.href(route),
+        entries,
+        at,
+        move,
+        pending,
+        metadata,
+        title: metadata.title,
+        canGoBack: at > 0,
+        canGoForward: at < entries.length - 1,
+        back: () => go(-1),
+        forward: () => go(1),
+        goTo: (to) => go(to - at),
+        reload: drawing.reload,
+        preload: drawing.preload,
+    };
+    return state;
+};
+/**
+ * A button that loads every page on screen again: for a failed page's
+ * screen, so the page whose Loader broke retries. Any other button props
+ * pass through.
+ */
+export function Retry({ onClick, type = 'button', ...rest }) {
+    const { reload } = useDrawing('Router.Retry');
+    return (_jsx("button", { ...rest, type: type, onClick: (event) => {
+            onClick?.(event);
+            if (!event.defaultPrevented)
+                reload();
+        } }));
+}

package/dist/routing/router/data.d.ts

@@ -0,0 +1,117 @@
+import { Effect, Schema } from 'effect';
+import type { AnyRoute } from '../capability/index.ts';
+import type { DataInfo, Known, Status } from '../page/index.ts';
+import type { Codec, Place } from '../route/index.ts';
+/** One place's data, as the Router holds it. */
+export interface Held {
+    /** The place's key: a place with another key is another place. */
+    readonly key: string;
+    readonly status: Status<unknown>;
+    /** How many reloads its data has seen. */
+    readonly reload: number;
+    /** What its Loader was handed, as one string: a new query loads it again. */
+    readonly for: string;
+}
+export type Holding = Readonly<Record<string, Held>>;
+/** What the Router reads of the Routes for the data of its places. */
+export interface DataRoutes<Route> {
+    readonly data: ReadonlyArray<readonly [string, Codec<unknown>]>;
+    readonly places: (of: Route) => ReadonlyArray<Place>;
+}
+/** What the Schemas of the data need of the Routes. */
+type DataSchemas = Pick<DataRoutes<never>, 'data'>;
+/** The data of the places with data, by dotted name, each with its own Schema. */
+export declare const holdingSchema: (routes: DataSchemas) => Codec<Holding>;
+/** The Router's Messages for the data of its places. */
+export declare const placeMessages: (routes: DataSchemas) => {
+    PlaceLoaded: {
+        answer: Codec<{
+            readonly name: string;
+            readonly data: unknown;
+        }>;
+        key: Schema.String;
+        stale: Schema.Boolean;
+        info: Schema.Struct<{
+            readonly render: Schema.Literals<readonly ["static", "dynamic", "client"]>;
+            readonly staleTime: Schema.NullOr<Schema.Number>;
+            readonly from: Schema.Literals<readonly ["server", "browser", "cache"]>;
+            readonly arrivedAt: Schema.Number;
+            readonly freshUntil: Schema.NullOr<Schema.Number>;
+            readonly took: Schema.NullOr<Schema.Number>;
+        }>;
+        reload: Schema.Number;
+        for: Schema.String;
+    };
+    PlaceFailed: {
+        name: Schema.String;
+        key: Schema.String;
+        reason: Schema.String;
+        notFound: Schema.Boolean;
+        reload: Schema.Number;
+        for: Schema.String;
+    };
+    PlaceRedirected: {
+        route: Schema.Struct<{
+            readonly _tag: Schema.String;
+        }>;
+    };
+    RedirectedAway: {
+        href: Schema.String;
+        id: Schema.optionalKey<Schema.Number>;
+    };
+};
+export type PlaceMessage = {
+    readonly _tag: 'PlaceLoaded';
+    readonly answer: {
+        readonly name: string;
+        readonly data: unknown;
+    };
+    readonly key: string;
+    readonly stale: boolean;
+    readonly info: DataInfo;
+    readonly reload: number;
+    readonly for: string;
+} | {
+    readonly _tag: 'PlaceFailed';
+    readonly name: string;
+    readonly key: string;
+    readonly reason: string;
+    readonly notFound: boolean;
+    readonly reload: number;
+    readonly for: string;
+} | {
+    readonly _tag: 'PlaceRedirected';
+    readonly route: AnyRoute;
+} | {
+    readonly _tag: 'RedirectedAway';
+    readonly href: string;
+    /** The held move it ends, if it came from one. */
+    readonly id?: number;
+};
+/** The data of the places with data on `route`: kept where the key is the same, else started from what is known. */
+export declare const holdingAt: <Route>(routes: DataRoutes<Route>, route: Route, before: Holding, known: Readonly<Record<string, Known>>, reload: number) => Holding;
+/** The runs of the `place` Worker: one per place on `route` whose data is due. */
+export declare const dueRuns: <Route>(routes: DataRoutes<Route>, route: Route, holding: Holding, reload: number) => ReadonlyArray<string>;
+/** Each place's status as its page sees it: data that is due is loading, behind the data shown if there is any. */
+export declare const shownOf: <Route>(routes: DataRoutes<Route>, route: Route, holding: Holding, reload: number) => Readonly<Record<string, Status<unknown>>>;
+/** The data of each place drawn with its data there, by dotted name: what the Metadata is worked out from. */
+export declare const readyOf: (shown: Readonly<Record<string, Status<unknown>>>) => Readonly<Record<string, unknown>>;
+/**
+ * Loads the data of one place, for the run `run` names, through `Loading`:
+ * with none, it stays loading. Sends what it came to.
+ */
+export declare const loadPlace: <Route>(routes: DataRoutes<Route>, run: string, self: {
+    readonly send: (message: PlaceMessage) => Effect.Effect<void>;
+    readonly get: Effect.Effect<{
+        readonly route: Route;
+        readonly holding: Holding;
+        readonly reload: number;
+    }>;
+    readonly now: Effect.Effect<number>;
+}) => Effect.Effect<void, never, never>;
+/** The data of the places once an answer for one of them came: unchanged if that place is gone. */
+export declare const settle: (holding: Holding, message: Exclude<PlaceMessage, {
+    readonly _tag: 'PlaceRedirected' | 'RedirectedAway';
+}>) => Holding;
+export {};
+//# sourceMappingURL=data.d.ts.map

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

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

package/dist/routing/router/data.js

@@ -0,0 +1,247 @@
+import { Effect, Option, Schema } from 'effect';
+import { Loading } from '../capability/index.js';
+import { DataInfoSchema, dataInfoOf, placeInfoOf, statusSchema, } from '../page/index.js';
+/*
+ * The data of every place on screen, held by the Router: one entry per
+ * place with data on the Route drawn, by dotted name. Each page is handed
+ * its own as `status`.
+ *
+ * 1. Start  as a move lands, each new place from what is known: the data
+ *           the move loaded before it landed, the server's, or the Data
+ *           cache's copy, which it shows, and loads again once stale.
+ *           Knowing nothing, Loading. A place whose key, its name and path
+ *           params, did not change keeps what it has.
+ * 2. Load   with the `place` Worker, one run per place whose data is due:
+ *           while it is loading, after a reload, on a stale copy, or when
+ *           its query changes. The data shown stays meanwhile; a loading
+ *           screen stays at least 300 ms.
+ * 3. Settle each answer into its place: Ready, or Failed, keeping data
+ *           shown when loading it again fails for the same query; a
+ *           Redirect replaces the entry, or leaves the app for a URL outside
+ *           it. An answer for a place no longer on screen is dropped.
+ */
+/** How long a page's loading screen stays at least, so it never flashes. */
+const MINIMUM = 300;
+const forOf = (place) => JSON.stringify(place.params);
+/** The data of the places with data, by dotted name, each with its own Schema. */
+export const holdingSchema = (routes) => Schema.Struct(Object.fromEntries(routes.data.map(([name, data]) => [
+    name,
+    Schema.optionalKey(Schema.Struct({
+        key: Schema.String,
+        status: statusSchema(data),
+        reload: Schema.Number,
+        for: Schema.String,
+    })),
+])));
+/** One answer for one place, with its data by its own Schema. */
+const answerSchema = (routes) => (routes.data.length === 0
+    ? Schema.Never
+    : Schema.Union(routes.data.map(([name, data]) => Schema.Struct({ name: Schema.Literal(name), data }))));
+/** The Router's Messages for the data of its places. */
+export const placeMessages = (routes) => ({
+    PlaceLoaded: {
+        answer: answerSchema(routes),
+        key: Schema.String,
+        stale: Schema.Boolean,
+        info: DataInfoSchema,
+        reload: Schema.Number,
+        for: Schema.String,
+    },
+    PlaceFailed: {
+        name: Schema.String,
+        key: Schema.String,
+        reason: Schema.String,
+        notFound: Schema.Boolean,
+        reload: Schema.Number,
+        for: Schema.String,
+    },
+    PlaceRedirected: { route: Schema.Struct({ _tag: Schema.String }) },
+    RedirectedAway: {
+        href: Schema.String,
+        id: Schema.optionalKey(Schema.Number),
+    },
+});
+// 1. Start
+/** The data of the places with data on `route`: kept where the key is the same, else started from what is known. */
+export const holdingAt = (routes, route, before, known, reload) => {
+    const out = {};
+    for (const place of routes.places(route)) {
+        if (!place.input)
+            continue;
+        const kept = before[place.name];
+        if (kept && kept.key === place.key) {
+            out[place.name] = kept;
+            continue;
+        }
+        const from = known[place.name];
+        out[place.name] = {
+            key: place.key,
+            reload,
+            for: forOf(place),
+            status: from?._tag === 'Ready'
+                ? {
+                    _tag: 'Ready',
+                    data: from.data,
+                    refreshing: from.stale,
+                    info: dataInfoOf(place, from),
+                }
+                : from?._tag === 'Failed'
+                    ? {
+                        _tag: 'Failed',
+                        reason: from.reason,
+                        notFound: from.notFound,
+                        info: placeInfoOf(place),
+                    }
+                    : { _tag: 'Loading', info: placeInfoOf(place) },
+        };
+    }
+    return out;
+};
+// 2. Load
+/** Whether a place's data is due to load, and why: the run it is loaded for, as one key. */
+const dueOf = (place, held, reload) => {
+    const asked = reload > held.reload || forOf(place) !== held.for;
+    const { status } = held;
+    if (status._tag === 'Loading' ||
+        (status._tag === 'Ready' && status.refreshing) ||
+        asked)
+        // The status is in the key, so a copy that came while it loaded, stale,
+        // is loaded again fresh: the run for a key it kept is not.
+        return `${place.name}|${held.key}|${reload}|${forOf(place)}|${status._tag}`;
+    return undefined;
+};
+/** The runs of the `place` Worker: one per place on `route` whose data is due. */
+export const dueRuns = (routes, route, holding, reload) => routes.places(route).flatMap((place) => {
+    const held = holding[place.name];
+    const due = held && dueOf(place, held, reload);
+    return due ? [due] : [];
+});
+/** Each place's status as its page sees it: data that is due is loading, behind the data shown if there is any. */
+export const shownOf = (routes, route, holding, reload) => {
+    const out = {};
+    for (const place of routes.places(route)) {
+        const held = holding[place.name];
+        if (!held)
+            continue;
+        const { status } = held;
+        out[place.name] =
+            dueOf(place, held, reload) === undefined
+                ? status
+                : status._tag === 'Ready'
+                    ? { ...status, refreshing: true }
+                    : { _tag: 'Loading', info: placeInfoOf(place) };
+    }
+    return out;
+};
+/** The data of each place drawn with its data there, by dotted name: what the Metadata is worked out from. */
+export const readyOf = (shown) => Object.fromEntries(Object.entries(shown).flatMap(([name, status]) => status._tag === 'Ready' ? [[name, status.data]] : []));
+/**
+ * Loads the data of one place, for the run `run` names, through `Loading`:
+ * with none, it stays loading. Sends what it came to.
+ */
+export const loadPlace = (routes, run, self) => Effect.gen(function* () {
+    const found = yield* Effect.serviceOption(Loading);
+    if (Option.isNone(found))
+        return;
+    const name = run.slice(0, run.indexOf('|'));
+    const { route, holding, reload } = yield* self.get;
+    const place = routes.places(route).find((each) => each.name === name);
+    const held = holding[name];
+    if (!place || !held || dueOf(place, held, reload) !== run)
+        return;
+    const shown = shownOf(routes, route, holding, reload)[name];
+    const began = yield* self.now;
+    const answers = yield* found.value.load([{ name, params: place.params }], 
+    // Data being loaded for a place that has none yet may already be on
+    // its way, or kept. Behind a stale copy it may be on its way, as a
+    // preload's: joined, never answered by the copy. A reload's is asked
+    // again, joining nothing.
+    reload > held.reload
+        ? { fresh: true }
+        : held.status._tag === 'Loading'
+            ? {}
+            : { again: true });
+    // When the answer came, before the loading screen's least time.
+    const arrived = yield* self.now;
+    if (shown?._tag === 'Loading')
+        yield* Effect.sleep(Math.max(0, began + MINIMUM - (yield* self.now)));
+    const answer = answers[name] ?? {
+        _tag: 'Broken',
+        reason: `no answer for ${name}`,
+    };
+    const stamp = { key: held.key, reload, for: forOf(place) };
+    const failed = (reason, notFound) => self.send({ _tag: 'PlaceFailed', name, reason, notFound, ...stamp });
+    switch (answer._tag) {
+        case 'Loaded': {
+            const schema = routes.data.find(([each]) => each === name)?.[1];
+            return yield* schema && !Schema.is(Schema.toType(schema))(answer.data)
+                ? failed(`the data of ${name} does not match its Schema`, false)
+                : self.send({
+                    _tag: 'PlaceLoaded',
+                    answer: { name, data: answer.data },
+                    stale: answer.stale === true,
+                    info: dataInfoOf(place, {
+                        from: answer.cached ? 'cache' : 'browser',
+                        at: answer.at ?? arrived,
+                        took: answer.cached ? null : (answer.took ?? arrived - began),
+                    }),
+                    ...stamp,
+                });
+        }
+        case 'NotFound':
+            return yield* failed('Not found', true);
+        case 'Broken':
+            return yield* failed(answer.reason, false);
+        case 'Redirect':
+            return yield* self.send(answer.href === undefined
+                ? { _tag: 'PlaceRedirected', route: answer.route }
+                : { _tag: 'RedirectedAway', href: answer.href });
+    }
+});
+// 3. Settle
+/** The data of the places once an answer for one of them came: unchanged if that place is gone. */
+export const settle = (holding, message) => {
+    const name = message._tag === 'PlaceLoaded' ? message.answer.name : message.name;
+    const held = holding[name];
+    if (!held || held.key !== message.key)
+        return holding;
+    if (message._tag === 'PlaceLoaded')
+        return {
+            ...holding,
+            [name]: {
+                key: held.key,
+                status: {
+                    _tag: 'Ready',
+                    data: message.answer.data,
+                    refreshing: message.stale,
+                    info: message.info,
+                },
+                reload: message.reload,
+                for: message.for,
+            },
+        };
+    // Loading again behind data shown, for the same query, keeps it.
+    return {
+        ...holding,
+        [name]: held.status._tag === 'Ready' && message.for === held.for
+            ? {
+                ...held,
+                status: { ...held.status, refreshing: false },
+                reload: message.reload,
+            }
+            : {
+                key: held.key,
+                status: {
+                    _tag: 'Failed',
+                    reason: message.reason,
+                    notFound: message.notFound,
+                    info: {
+                        render: held.status.info.render,
+                        staleTime: held.status.info.staleTime,
+                    },
+                },
+                reload: message.reload,
+                for: message.for,
+            },
+    };
+};

package/dist/routing/router/define.d.ts

@@ -0,0 +1,52 @@
+import type { ChildrenOf, Metadata, Redirects, RouteOf, RoutesApi, Tree } from '../route/index.ts';
+import type { AnyPageDefinition, Rootless } from '../page/index.ts';
+import type { ScrollRestorationOptions } from '../scroll/index.ts';
+/** When a link preloads the Route it goes to: on hover or focus, once it scrolls into view, or never. */
+export type Preload = 'intent' | 'viewport' | false;
+/** How the Router behaves in the browser: where it is mounted, how long a move waits, links, scroll. */
+export type RouterOptions<C, D> = {
+    /** Paths that are never a place, each with the Route it is replaced by, from the params its path names. */
+    readonly redirect?: Redirects<C, D>;
+    /** The not-found Route's Metadata, over the root page's. */
+    readonly notFound?: Metadata;
+    /** Where the app is mounted, like `/app`: every link and URL is under it. */
+    readonly base?: string;
+    /** How long a move waits for its data, in milliseconds, before it lands and its pages show they are loading: 150 unless said. */
+    readonly delay?: number;
+    /** When a `Router.Link` preloads, unless it says: `'intent'` by default. */
+    readonly preload?: Preload;
+    /** How long, in milliseconds, an `'intent'` link waits before it preloads: 50 by default. */
+    readonly preloadDelay?: number;
+    /** How long, in milliseconds, a copy in the Data cache stays fresh, for every dynamic or client page that says none: 0 unless said. */
+    readonly staleTime?: number;
+    /** How many copies the Data cache keeps, the least recently used dropped first: 50 unless said. */
+    readonly cacheSize?: number;
+} & ScrollRestorationOptions<RouteOf<C>>;
+/** What the Router reads of its definition besides the Routes. */
+export interface Rooted<G extends AnyPageDefinition> {
+    /** The root page's definition: its build is the Router's one Child. */
+    readonly root: G;
+    readonly options: {
+        readonly base: string;
+        readonly delay: number;
+        readonly preload: {
+            readonly mode: Preload;
+            readonly delay: number;
+        };
+        readonly cacheSize: number;
+        readonly scroll: ScrollRestorationOptions<never>;
+    };
+}
+/** The router of an app whose root page is `G`. */
+export type RouterDefinition<G extends AnyPageDefinition> = Tree<ChildrenOf<G>, RouteOf<ChildrenOf<G>>, {}> & RoutesApi<ChildrenOf<G>> & Rooted<G>;
+export type AnyRouterDefinition = RoutesApi<any> & Rooted<AnyPageDefinition>;
+/**
+ * The router of the app whose root page is `root`, or the page a function
+ * gives, read when the router is first used: a page whose definition and
+ * build share a module may then import the router to move the app, as long
+ * as nothing reads it while the modules load.
+ */
+export declare const define: <G extends AnyPageDefinition, const D extends Readonly<Record<string, (routes: Tree<ChildrenOf<G>, RouteOf<ChildrenOf<G>>, {}>, params: any) => RouteOf<ChildrenOf<G>>>> = {}>(root: (G & Rootless<G>) | (() => G & Rootless<G>), options?: RouterOptions<ChildrenOf<G>, D> & {
+    readonly redirect?: D & Redirects<ChildrenOf<G>, D>;
+}) => RouterDefinition<G>;
+//# sourceMappingURL=define.d.ts.map

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

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

package/dist/routing/router/define.js

@@ -0,0 +1,48 @@
+import { routesOf } from '../route/index.js';
+/** The root page's Metadata, under every place's. */
+const rootMetadata = (root) => typeof root.metadata === 'function'
+    ? root.metadata({}, undefined)
+    : root.metadata;
+/**
+ * The router of the app whose root page is `root`, or the page a function
+ * gives, read when the router is first used: a page whose definition and
+ * build share a module may then import the router to move the app, as long
+ * as nothing reads it while the modules load.
+ */
+export const define = (root, options = {}) => {
+    const make = (page) => {
+        if (page.input !== undefined)
+            throw new Error('[@kestack/kabuki/routing] the root page has no data: a Loader needs a place in the URL');
+        const metadata = rootMetadata(page);
+        const { redirect, notFound, base, delay, preload, preloadDelay, staleTime, cacheSize, ...scroll } = options;
+        return Object.assign(routesOf(page.children, {
+            ...(redirect ? { redirect } : {}),
+            ...(notFound ? { notFound } : {}),
+            ...(metadata ? { metadata } : {}),
+            ...(staleTime === undefined ? {} : { staleTime }),
+        }), {
+            root: page,
+            options: {
+                base: (base ?? '').replace(/\/$/, ''),
+                delay: delay ?? 150,
+                preload: { mode: preload ?? 'intent', delay: preloadDelay ?? 50 },
+                cacheSize: cacheSize ?? 50,
+                scroll: scroll,
+            },
+        });
+    };
+    if (typeof root !== 'function')
+        return make(root);
+    // Read the root when the router is first used, so its pages may import it.
+    let made;
+    const router = () => (made ??= make(root()));
+    return new Proxy({}, {
+        get: (_, key) => Reflect.get(router(), key),
+        has: (_, key) => Reflect.has(router(), key),
+        ownKeys: () => Reflect.ownKeys(router()),
+        getOwnPropertyDescriptor: (_, key) => {
+            const found = Reflect.getOwnPropertyDescriptor(router(), key);
+            return found && { ...found, configurable: true };
+        },
+    });
+};

package/dist/routing/router/frame.d.ts

@@ -0,0 +1,10 @@
+import type { MouseEvent, ReactNode } from 'react';
+import type { Drawing } from './context.tsx';
+export declare function Frame({ drawing, attached, root, onClick, children, }: {
+    readonly drawing: Drawing;
+    readonly attached: boolean;
+    readonly root: object;
+    readonly onClick: (event: MouseEvent) => void;
+    readonly children: ReactNode;
+}): import("react").JSX.Element;
+//# sourceMappingURL=frame.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"frame.d.ts","sourceRoot":"","sources":["../../../src/routing/router/frame.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAEnD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAQ7C,wBAAgB,KAAK,CAAC,EACpB,OAAO,EACP,QAAQ,EACR,IAAI,EACJ,OAAO,EACP,QAAQ,GACT,EAAE;IACD,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,CAAC;IAC9C,QAAQ,CAAC,QAAQ,EAAE,SAAS,CAAC;CAC9B,+BASA"}

package/dist/routing/router/frame.js

@@ -0,0 +1,10 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { MetadataWriter, RouterContext } from './context.js';
+/*
+ * What the Router draws around the app: the context links and hooks read,
+ * a catch for plain clicks on links, and, when an Adapter holds the address,
+ * the Metadata, worked out from the data of the pages drawn.
+ */
+export function Frame({ drawing, attached, root, onClick, children, }) {
+    return (_jsxs(RouterContext, { value: drawing, children: [attached && _jsx(MetadataWriter, { metadata: drawing.metadata }), _jsx("div", { ...root, style: { display: 'contents' }, onClick: onClick, children: children })] }));
+}