@forgebook/sveltekit 0.0.0-stage → 0.2.0

package/dist/src/app/navigation.js

@@ -0,0 +1,147 @@
+/**
+ * `$app/navigation` in a catalogue: `goto` and a link move the story's page (its address, route, params and data),
+ * the navigation callbacks run as in the app, and every call is listed among the story's events.
+ *
+ * @remarks
+ * A story that gives a callback of its own (`parameters.sveltekit.navigation.goto`, as Storybook's SvelteKit names it)
+ * has it called with the call's arguments too. The frame's address and history are never touched: they name the story.
+ *
+ * @module
+ */
+import { onMount } from "svelte";
+import { currentStore } from "../kitStore.js";
+/**
+ * Records a call and hands it to the story's own callback, when it gives one.
+ *
+ * @param store - the story's page.
+ * @param name - the function's name.
+ * @param values - what it was called with.
+ */
+const called = (store, name, values) => {
+    store.record(name, values);
+    const callback = store.kit.navigation[name];
+    if (typeof callback === "function")
+        Reflect.apply(callback, undefined, values);
+};
+/**
+ * Goes to an address, as a story's page: its route, params and data follow, the navigation callbacks run.
+ *
+ * @param url - where to go, from the page's address.
+ * @param options - the new page's state; the page's data is loaded again at every move.
+ * @returns resolves once the page moved; rejects for an address outside the app, as SvelteKit does.
+ */
+export const goto = async (url, options) => {
+    const store = currentStore();
+    called(store, "goto", options === undefined ? [String(url)] : [String(url), options]);
+    const read = options ?? {};
+    const moved = await store.navigate("goto", url, read.state === undefined ? {} : { state: read.state });
+    if (!moved && new URL(url, store.page().url).origin !== store.page().url.origin)
+        throw new Error(`goto cannot go to an address outside the app (${String(url)}): use window.location instead`);
+};
+/**
+ * Loads the page's data again, as when something it depends on changed.
+ *
+ * @param resource - what changed: an address, a dependency's name, or a test of an address.
+ */
+export const invalidate = async (resource) => {
+    const store = currentStore();
+    called(store, "invalidate", [typeof resource === "function" ? "(url) => …" : String(resource)]);
+    await store.reload();
+};
+/** Loads the page's data again (SvelteKit 2). */
+export const invalidateAll = async () => {
+    const store = currentStore();
+    called(store, "invalidateAll", []);
+    await store.reload();
+};
+/** Loads the page's data again, keeping its state (SvelteKit 3). */
+export const refreshAll = async () => {
+    const store = currentStore();
+    called(store, "refreshAll", []);
+    await store.reload();
+};
+/**
+ * Loads an address's data without going there.
+ *
+ * @param href - the address.
+ */
+export const preloadData = async (href) => {
+    const store = currentStore();
+    called(store, "preloadData", [href]);
+    try {
+        return { type: "loaded", status: 200, data: await store.dataAt(href) };
+    }
+    catch (error) {
+        return { type: "error", error };
+    }
+};
+/**
+ * Loads a route's code: a story's code is loaded already.
+ *
+ * @param pathnames - the routes.
+ */
+export const preloadCode = async (...pathnames) => {
+    called(currentStore(), "preloadCode", pathnames);
+    await Promise.resolve();
+};
+/**
+ * Sets the page's state without a navigation (shallow routing).
+ *
+ * @param url - the address the state belongs to; recorded.
+ * @param state - the page's new state.
+ */
+export const pushState = (url, state) => {
+    const store = currentStore();
+    called(store, "pushState", [String(url), state]);
+    store.setPage({ state });
+};
+/**
+ * Replaces the page's state without a navigation (shallow routing).
+ *
+ * @param url - the address the state belongs to; recorded.
+ * @param state - the page's new state.
+ */
+export const replaceState = (url, state) => {
+    const store = currentStore();
+    called(store, "replaceState", [String(url), state]);
+    store.setPage({ state });
+};
+/** Leaves the scroll as it is after a navigation: a story's page never scrolls on its own. */
+export const disableScrollHandling = () => undefined;
+/**
+ * Captures and restores a component's state across the history (SvelteKit 3): a story's history is its own, so there
+ * is nothing to restore.
+ */
+export const snapshot = () => undefined;
+/**
+ * Runs a callback when the component is drawn, with the page's first navigation, and after every navigation of the
+ * story's page. Called while a component is set up.
+ *
+ * @param callback - the callback.
+ */
+export const afterNavigate = (callback) => {
+    const store = currentStore();
+    onMount(() => {
+        callback(store.enter());
+        return store.afterNavigate(callback);
+    });
+};
+/**
+ * Runs a callback before every navigation of the story's page, which it may cancel. Called while a component is set up.
+ *
+ * @param callback - the callback.
+ */
+export const beforeNavigate = (callback) => {
+    const store = currentStore();
+    onMount(() => store.beforeNavigate(callback));
+};
+/**
+ * Runs a callback as every navigation of the story's page starts; a function it returns runs once it is done. Called
+ * while a component is set up.
+ *
+ * @param callback - the callback.
+ */
+export const onNavigate = (callback) => {
+    const store = currentStore();
+    onMount(() => store.onNavigate(callback));
+};

package/dist/src/app/paths.d.ts

@@ -0,0 +1,32 @@
+import { type RouteMatch, type RouteParams } from "../routeIds.ts";
+/** What SvelteKit puts before every path of the app (`paths.base`); empty by default. */
+export declare const base: string;
+/** Where the static files are served from (`paths.assets`), or the base path. */
+export declare const assets: string;
+/**
+ * The address of a static file.
+ *
+ * @param file - the file, from the `static` folder (`favicon.png`).
+ */
+export declare const asset: (file: string) => string;
+/**
+ * A route id or a path written as the app's path: a route's params filled in, the base path before it.
+ *
+ * @param target - a route id (`/blog/[slug]`) or a path, with a search or a hash.
+ * @param params - the route's params.
+ */
+export declare const resolve: (target: string, params?: RouteParams) => string;
+/**
+ * A route id written as the app's path (SvelteKit 2).
+ *
+ * @param id - the route id.
+ * @param params - its params.
+ */
+export declare const resolveRoute: (id: string, params?: RouteParams) => string;
+/**
+ * The project's route an address matches, with its params.
+ *
+ * @param url - the address, or a path.
+ * @returns the route, or `null` when none matches.
+ */
+export declare const match: (url: URL | string) => Promise<RouteMatch | null>;

package/dist/src/app/paths.js

@@ -0,0 +1,56 @@
+/**
+ * `$app/paths` in a catalogue: the project's base path and assets' path, and the paths SvelteKit writes from them, for
+ * SvelteKit 2 (`base`, `assets`, `resolveRoute`) and 3 (`asset`, `resolve`, `match`).
+ *
+ * @module
+ */
+import { appSettings, pageRouteIds } from "../appSettings.js";
+import { PAGE_ORIGIN, routePath } from "../kitParameters.js";
+import { filledRoute, isRouteId, matchRoute } from "../routeIds.js";
+/** What SvelteKit puts before every path of the app (`paths.base`); empty by default. */
+export const base = appSettings().base;
+/** Where the static files are served from (`paths.assets`), or the base path. */
+export const assets = appSettings().assets === "" ? appSettings().base : appSettings().assets;
+/**
+ * A path with one leading slash, as a base path is joined to it.
+ *
+ * @param path - a path, with or without its leading slash (SvelteKit 3 writes none).
+ */
+const rooted = (path) => (path.startsWith("/") ? path : `/${path}`);
+/**
+ * The address of a static file.
+ *
+ * @param file - the file, from the `static` folder (`favicon.png`).
+ */
+export const asset = (file) => `${assets}${rooted(file)}`;
+/**
+ * A route id or a path written as the app's path: a route's params filled in, the base path before it.
+ *
+ * @param target - a route id (`/blog/[slug]`) or a path, with a search or a hash.
+ * @param params - the route's params.
+ */
+export const resolve = (target, params = {}) => {
+    const end = target.search(/[?#]/);
+    const path = end === -1 ? target : target.slice(0, end);
+    const rest = end === -1 ? "" : target.slice(end);
+    const filled = isRouteId(path) ? filledRoute(path, params) : rooted(path);
+    return `${base}${filled}${rest}`;
+};
+/**
+ * A route id written as the app's path (SvelteKit 2).
+ *
+ * @param id - the route id.
+ * @param params - its params.
+ */
+export const resolveRoute = (id, params = {}) => resolve(id, params);
+/**
+ * The project's route an address matches, with its params.
+ *
+ * @param url - the address, or a path.
+ * @returns the route, or `null` when none matches.
+ */
+export const match = async (url) => {
+    await Promise.resolve();
+    const address = new URL(url, PAGE_ORIGIN);
+    return matchRoute(pageRouteIds(), routePath(address.pathname, base)) ?? null;
+};

package/dist/src/app/state.d.ts

@@ -0,0 +1,27 @@
+/**
+ * `$app/state` in a catalogue: the page, the navigation under way and whether a new version is out, read from the
+ * story's page (`parameters.sveltekit`) and followed by Svelte as SvelteKit's own are.
+ *
+ * @remarks
+ * Each field is read when it is read, from the frame's current story, so a component reading `page.url.pathname`
+ * in its markup follows a link the story clicked.
+ *
+ * @module
+ */
+import type { KitNavigation, KitPage } from "../kitParameters.ts";
+/** The page, as `page` from `$app/state` gives it. */
+export declare const page: KitPage;
+/** The navigation under way, as `navigating` from `$app/state` gives it: every field `null` when there is none. */
+export declare const navigating: {
+    readonly from: KitNavigation["from"] | null;
+    readonly to: KitNavigation["to"] | null;
+    readonly type: KitNavigation["type"] | null;
+    readonly willUnload: boolean | null;
+    readonly delta: number | null;
+    readonly complete: Promise<void> | null;
+};
+/** Whether a new version of the app is out: the story's `updated`. */
+export declare const updated: {
+    readonly current: boolean;
+    check: () => Promise<boolean>;
+};

package/dist/src/app/state.js

@@ -0,0 +1,60 @@
+import { currentStore } from "../kitStore.js";
+/** The page, as `page` from `$app/state` gives it. */
+export const page = {
+    get url() {
+        return currentStore().page().url;
+    },
+    get params() {
+        return currentStore().page().params;
+    },
+    get route() {
+        return currentStore().page().route;
+    },
+    get status() {
+        return currentStore().page().status;
+    },
+    get error() {
+        return currentStore().page().error;
+    },
+    get data() {
+        return currentStore().page().data;
+    },
+    get state() {
+        return currentStore().page().state;
+    },
+    get form() {
+        return currentStore().page().form;
+    }
+};
+/** The navigation under way, as `navigating` from `$app/state` gives it: every field `null` when there is none. */
+export const navigating = {
+    get from() {
+        return currentStore().navigating()?.from ?? null;
+    },
+    get to() {
+        return currentStore().navigating()?.to ?? null;
+    },
+    get type() {
+        return currentStore().navigating()?.type ?? null;
+    },
+    get willUnload() {
+        return currentStore().navigating()?.willUnload ?? null;
+    },
+    get delta() {
+        return currentStore().navigating()?.delta ?? null;
+    },
+    get complete() {
+        return currentStore().navigating()?.complete ?? null;
+    }
+};
+/** Whether a new version of the app is out: the story's `updated`. */
+export const updated = {
+    get current() {
+        return currentStore().updated();
+    },
+    check: () => {
+        const store = currentStore();
+        store.record("updated.check", []);
+        return Promise.resolve(store.updated());
+    }
+};

package/dist/src/app/stores.d.ts

@@ -0,0 +1,31 @@
+/**
+ * `$app/stores` in a catalogue, for a project on SvelteKit 2: the page, the navigation and the version as Svelte stores,
+ * over the same story page as `$app/state`.
+ *
+ * @remarks
+ * SvelteKit 3 removed the module; a project on SvelteKit 2 still imports it, so the catalogue gives it either way.
+ *
+ * @module
+ */
+import type { KitNavigation, KitPage } from "../kitParameters.ts";
+/** A store a component subscribes to with `$name`. */
+export type Readable<TValue> = {
+    /** Calls `run` with the value now and at each change; returns what stops it. */
+    readonly subscribe: (run: (value: TValue) => void) => () => void;
+};
+/** The page, as `$page` reads it. */
+export declare const page: Readable<KitPage>;
+/** The navigation under way, or `null`, as `$navigating` reads it. */
+export declare const navigating: Readable<Partial<KitNavigation> | null>;
+/** Whether a new version is out, as `$updated` reads it; `updated.check()` resolves with the same. */
+export declare const updated: Readable<boolean> & {
+    readonly check: () => Promise<boolean>;
+};
+/** The three stores, as `getStores()` returns them. */
+export declare const getStores: () => {
+    readonly page: Readable<KitPage>;
+    readonly navigating: Readable<Partial<KitNavigation> | null>;
+    readonly updated: Readable<boolean> & {
+        readonly check: () => Promise<boolean>;
+    };
+};

package/dist/src/app/stores.js

@@ -0,0 +1,36 @@
+import { currentStore } from "../kitStore.js";
+/**
+ * A store over a value of the story's page.
+ *
+ * @param read - reads the value from the frame's current story.
+ */
+const readable = (read) => ({
+    subscribe: (run) => {
+        const store = currentStore();
+        let last = read();
+        run(last);
+        // the page changes alone, the navigation alone: each store runs only for its own value
+        return store.subscribe(() => {
+            const value = read();
+            if (value === last)
+                return;
+            last = value;
+            run(value);
+        });
+    }
+});
+/** The page, as `$page` reads it. */
+export const page = readable(() => currentStore().page());
+/** The navigation under way, or `null`, as `$navigating` reads it. */
+export const navigating = readable(() => currentStore().navigating());
+/** Whether a new version is out, as `$updated` reads it; `updated.check()` resolves with the same. */
+export const updated = {
+    ...readable(() => currentStore().updated()),
+    check: () => {
+        const store = currentStore();
+        store.record("updated.check", []);
+        return Promise.resolve(store.updated());
+    }
+};
+/** The three stores, as `getStores()` returns them. */
+export const getStores = () => ({ page, navigating, updated });

package/dist/src/appSettings.d.ts

@@ -0,0 +1,44 @@
+/**
+ * What the SvelteKit project gives the page: its base path, its assets' path, its version and its routes, read by the
+ * Vite plugin and written in the frame's page before any module runs.
+ *
+ * @remarks
+ * Written in the page, not compiled into a module, so a stand-in pre-bundled by Vite reads the same values as the
+ * project's own code. A server render has no page: there the plugin writes the same settings into the code it
+ * compiles (`SETTINGS_CONSTANT`). Only what SvelteKit itself sends to the browser is there: no environment variable
+ * (the public ones are modules of their own, `$env/static/public` and `$app/env/public`).
+ *
+ * @module
+ */
+/** The key the frame's page writes the settings under, on `globalThis`. */
+export declare const APP_SETTINGS_KEY = "forgebook.sveltekit.app";
+/** The name the plugin replaces with the settings in the code it compiles (Vite's `define`), for a server render. */
+export declare const SETTINGS_CONSTANT = "__FORGEBOOK_SVELTEKIT_SETTINGS__";
+/** A route of the project, as `$app/manifest` lists it. */
+export type AppRoute = {
+    /** The route's id (`/blog/[slug]`). */
+    readonly id: string;
+    /** Whether it has a page (`+page.svelte`). */
+    readonly page: boolean;
+    /** Whether it has an endpoint (`+server.ts`). */
+    readonly endpoint: boolean;
+};
+/** What the project's configuration and folders give the page. */
+export type KitAppSettings = {
+    /** `paths.base`: what SvelteKit puts before every path of the app (`/docs`); empty by default. */
+    readonly base: string;
+    /** `paths.assets`: where the static files are served from, an absolute URL; empty for the base path. */
+    readonly assets: string;
+    /** `version.name`, as `$app/env` gives it. */
+    readonly version: string;
+    /** The project's routes, from `src/routes`. */
+    readonly routes: readonly AppRoute[];
+    /** The project's static files, from `static`, as paths without their leading slash. */
+    readonly staticFiles: readonly string[];
+};
+/** The settings of a page the plugin did not write (a test's): no base path, no routes. */
+export declare const NO_SETTINGS: KitAppSettings;
+/** The settings the frame's page holds, or those the plugin compiled in. */
+export declare const appSettings: () => KitAppSettings;
+/** The ids of the project's routes that have a page: where a link or `goto` can land. */
+export declare const pageRouteIds: () => string[];

package/dist/src/appSettings.js

@@ -0,0 +1,55 @@
+/**
+ * What the SvelteKit project gives the page: its base path, its assets' path, its version and its routes, read by the
+ * Vite plugin and written in the frame's page before any module runs.
+ *
+ * @remarks
+ * Written in the page, not compiled into a module, so a stand-in pre-bundled by Vite reads the same values as the
+ * project's own code. A server render has no page: there the plugin writes the same settings into the code it
+ * compiles (`SETTINGS_CONSTANT`). Only what SvelteKit itself sends to the browser is there: no environment variable
+ * (the public ones are modules of their own, `$env/static/public` and `$app/env/public`).
+ *
+ * @module
+ */
+/** The key the frame's page writes the settings under, on `globalThis`. */
+export const APP_SETTINGS_KEY = "forgebook.sveltekit.app";
+/** The name the plugin replaces with the settings in the code it compiles (Vite's `define`), for a server render. */
+export const SETTINGS_CONSTANT = "__FORGEBOOK_SVELTEKIT_SETTINGS__";
+/** The settings of a page the plugin did not write (a test's): no base path, no routes. */
+export const NO_SETTINGS = { base: "", assets: "", version: "", routes: [], staticFiles: [] };
+/** Whether a value is a plain object. */
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/**
+ * A text read from the settings, or empty.
+ *
+ * @param value - the value.
+ */
+const textOf = (value) => (typeof value === "string" ? value : "");
+/**
+ * A route read from the settings, or none.
+ *
+ * @param value - the value.
+ */
+const routeOf = (value) => isRecord(value) && typeof value["id"] === "string"
+    ? [{ id: value["id"], page: value["page"] === true, endpoint: value["endpoint"] === true }]
+    : [];
+/** The settings the frame's page holds, or those the plugin compiled in. */
+export const appSettings = () => {
+    const inPage = Reflect.get(globalThis, Symbol.for(APP_SETTINGS_KEY));
+    const settings = inPage === undefined && typeof __FORGEBOOK_SVELTEKIT_SETTINGS__ !== "undefined"
+        ? __FORGEBOOK_SVELTEKIT_SETTINGS__
+        : inPage;
+    if (!isRecord(settings))
+        return NO_SETTINGS;
+    const { routes, staticFiles } = settings;
+    return {
+        base: textOf(settings["base"]),
+        assets: textOf(settings["assets"]),
+        version: textOf(settings["version"]),
+        routes: Array.isArray(routes) ? routes.flatMap(routeOf) : [],
+        staticFiles: Array.isArray(staticFiles) ? staticFiles.filter((file) => typeof file === "string") : []
+    };
+};
+/** The ids of the project's routes that have a page: where a link or `goto` can land. */
+export const pageRouteIds = () => appSettings()
+    .routes.filter((route) => route.page)
+    .map((route) => route.id);