@forgebook/sveltekit 0.0.0-stage → 0.2.0

package/dist/src/routeIds.d.ts

@@ -0,0 +1,44 @@
+/**
+ * SvelteKit's route ids, read as SvelteKit reads them: which route a path matches and with which params, and the path a
+ * route id gives with its params filled in.
+ *
+ * @remarks
+ * Pure: ids and paths in, matches out, so it is tested without a page. The ids are the project's own, listed from its
+ * `src/routes` by the Vite plugin, so a story's links and `goto` calls land on the route SvelteKit would choose:
+ * `/blog/[slug]` for `/blog/hello`, with `{ slug: "hello" }`. A param's matcher (`[id=integer]`) is not run, since the
+ * catalogue does not load the project's matchers: any value matches it.
+ *
+ * @module
+ */
+/** A route's params, by name: SvelteKit gives each as one text, a rest param's slashes included. */
+export type RouteParams = Readonly<Record<string, string>>;
+/** A route a path matched: its id and its params. */
+export type RouteMatch = {
+    /** The route's id (`/blog/[slug]`). */
+    readonly id: string;
+    /** The params read from the path. */
+    readonly params: RouteParams;
+};
+/**
+ * The route a path matches among a project's routes, and its params.
+ *
+ * @param routes - the project's route ids.
+ * @param pathname - the path, without the base path (`/blog/hello`).
+ * @returns the match, or none when no route matches.
+ */
+export declare const matchRoute: (routes: readonly string[], pathname: string) => RouteMatch | undefined;
+/**
+ * The path a route id gives with its params filled in, as `resolve` from `$app/paths` writes it: the layout groups
+ * left out, an optional or rest param with no value dropped with its slash.
+ *
+ * @param id - the route's id (`/blog/[slug]`).
+ * @param params - the params, by name.
+ * @returns the path (`/blog/hello`).
+ */
+export declare const filledRoute: (id: string, params: RouteParams) => string;
+/**
+ * Whether a text is a route id rather than a path: it names a param or a layout group.
+ *
+ * @param text - the text.
+ */
+export declare const isRouteId: (text: string) => boolean;

package/dist/src/routeIds.js

@@ -0,0 +1,150 @@
+/**
+ * SvelteKit's route ids, read as SvelteKit reads them: which route a path matches and with which params, and the path a
+ * route id gives with its params filled in.
+ *
+ * @remarks
+ * Pure: ids and paths in, matches out, so it is tested without a page. The ids are the project's own, listed from its
+ * `src/routes` by the Vite plugin, so a story's links and `goto` calls land on the route SvelteKit would choose:
+ * `/blog/[slug]` for `/blog/hello`, with `{ slug: "hello" }`. A param's matcher (`[id=integer]`) is not run, since the
+ * catalogue does not load the project's matchers: any value matches it.
+ *
+ * @module
+ */
+import { byRouteOrder } from "./routeOrder.js";
+/** A param in a route id: `[name]`, `[[name]]`, `[...name]`, each with an optional `=matcher`. */
+const PARAM = /\[(\[)?(\.\.\.)?([A-Za-z_$][\w$]*)(?:=[\w$]+)?\]?\]/g;
+/** A layout group, `(app)`: a folder that is not a segment of the path. */
+const GROUP = /^\(.+\)$/;
+/**
+ * The segments of a route id that are in its paths: its layout groups left out.
+ *
+ * @param id - the route's id (`/(app)/blog/[slug]`).
+ */
+const pathSegments = (id) => id.split("/").filter((segment) => segment !== "" && !GROUP.test(segment));
+/**
+ * A segment's parts: its texts and its params.
+ *
+ * @param segment - a segment of a route id (`[a]-[b]`).
+ */
+const segmentParts = (segment) => {
+    const parts = [];
+    let index = 0;
+    for (const match of segment.matchAll(PARAM)) {
+        if (match.index > index)
+            parts.push({ kind: "text", text: segment.slice(index, match.index) });
+        parts.push({
+            kind: "param",
+            name: match[3] ?? "",
+            isRest: match[2] !== undefined,
+            isOptional: match[1] !== undefined
+        });
+        index = match.index + match[0].length;
+    }
+    if (index < segment.length)
+        parts.push({ kind: "text", text: segment.slice(index) });
+    return parts;
+};
+/**
+ * A text written so a regular expression reads it as itself.
+ *
+ * @param text - the text.
+ */
+const escaped = (text) => text.replace(/[.*+?^${}()|[\]\\/]/g, "\\$&");
+/**
+ * The regular expression one segment of a route id matches, its slash included.
+ *
+ * @param parts - the segment's parts.
+ * @param names - where its params' names are added, in order.
+ */
+const segmentSource = (parts, names) => {
+    const only = parts.length === 1 ? parts[0] : undefined;
+    // a segment that is a rest or optional param alone may be absent from the path, its slash with it
+    if (only?.kind === "param" && (only.isRest || only.isOptional)) {
+        names.push(only.name);
+        return only.isRest ? "(?:/(.*))?" : "(?:/([^/]+))?";
+    }
+    const written = parts.map((part) => {
+        if (part.kind === "text")
+            return escaped(part.text);
+        names.push(part.name);
+        return part.isRest ? "(.*?)" : "([^/]+?)";
+    });
+    return `/${written.join("")}`;
+};
+/**
+ * The regular expression a route id matches paths with, and its params' names in order.
+ *
+ * @param id - the route's id.
+ */
+const routePattern = (id) => {
+    const names = [];
+    const source = pathSegments(id)
+        .map((segment) => segmentSource(segmentParts(segment), names))
+        .join("");
+    return { pattern: new RegExp(`^${source}/?$`), names };
+};
+/**
+ * A path's parts decoded, as SvelteKit decodes a param: a malformed escape left as it is.
+ *
+ * @param value - the text.
+ */
+const decoded = (value) => {
+    try {
+        return decodeURIComponent(value);
+    }
+    catch {
+        return value;
+    }
+};
+/**
+ * The route a path matches among a project's routes, and its params.
+ *
+ * @param routes - the project's route ids.
+ * @param pathname - the path, without the base path (`/blog/hello`).
+ * @returns the match, or none when no route matches.
+ */
+export const matchRoute = (routes, pathname) => {
+    for (const id of [...routes].sort(byRouteOrder)) {
+        const { pattern, names } = routePattern(id);
+        const found = pattern.exec(pathname);
+        if (found === null)
+            continue;
+        const params = {};
+        names.forEach((name, index) => {
+            params[name] = decoded(found[index + 1] ?? "");
+        });
+        return { id, params };
+    }
+    return undefined;
+};
+/**
+ * The path a route id gives with its params filled in, as `resolve` from `$app/paths` writes it: the layout groups
+ * left out, an optional or rest param with no value dropped with its slash.
+ *
+ * @param id - the route's id (`/blog/[slug]`).
+ * @param params - the params, by name.
+ * @returns the path (`/blog/hello`).
+ */
+export const filledRoute = (id, params) => {
+    const segments = pathSegments(id).flatMap((segment) => {
+        const parts = segmentParts(segment);
+        const text = parts
+            .map((part) => {
+            if (part.kind === "text")
+                return part.text;
+            // inserted as given, as SvelteKit's `resolve` does: the address the page builds from it encodes what it must
+            return params[part.name] ?? "";
+        })
+            .join("");
+        return text === "" ? [] : [text];
+    });
+    return `/${segments.join("/")}`;
+};
+/**
+ * Whether a text is a route id rather than a path: it names a param or a layout group.
+ *
+ * @param text - the text.
+ */
+export const isRouteId = (text) => text
+    .split("/")
+    .some((segment) => GROUP.test(segment) || segmentParts(segment).some((part) => part.kind === "param"));

package/dist/src/routeOrder.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The order SvelteKit tries its routes in, so a path two routes match lands on the one SvelteKit would choose.
+ *
+ * @remarks
+ * SvelteKit's own `sort_routes` (MIT), written again in this package's TypeScript: the rules are SvelteKit's to the
+ * letter, since a route chosen otherwise gives a component other params than the app would. A text segment outranks a
+ * param, a param with a matcher one without, a required param an optional one, `[...rest]/x` a plain param; a shallower
+ * path a deeper one; an optional param that is not last is left out of the comparison.
+ *
+ * @module
+ */
+/**
+ * Orders two routes, the one SvelteKit tries first first.
+ *
+ * @param first - a route id.
+ * @param second - another.
+ */
+export declare const byRouteOrder: (first: string, second: string) => number;

package/dist/src/routeOrder.js

@@ -0,0 +1,187 @@
+/**
+ * The order SvelteKit tries its routes in, so a path two routes match lands on the one SvelteKit would choose.
+ *
+ * @remarks
+ * SvelteKit's own `sort_routes` (MIT), written again in this package's TypeScript: the rules are SvelteKit's to the
+ * letter, since a route chosen otherwise gives a component other params than the app would. A text segment outranks a
+ * param, a param with a matcher one without, a required param an optional one, `[...rest]/x` a plain param; a shallower
+ * path a deeper one; an optional param that is not last is left out of the comparison.
+ *
+ * @module
+ */
+/** The part a segment past a route's end compares as. */
+const EMPTY = { type: "static", content: "", isMatched: false };
+/** A param's type, by the character after its `[`: `[[optional]]`, `[...rest]`, any other `[required]`. */
+const PARAM_TYPES = { "[": "optional", ".": "rest" };
+/** A layout group, `(app)`: a folder that is not a segment of the path. */
+const GROUP = /^\(.+\)$/;
+/**
+ * A segment's parts: a text first (empty when the segment opens with a param), then params and texts in turn.
+ *
+ * @param segment - the segment.
+ */
+const partsOf = (segment) => {
+    const parts = [];
+    let index = 0;
+    while (index <= segment.length) {
+        const start = segment.indexOf("[", index);
+        if (start === -1) {
+            parts.push({ type: "static", content: segment.slice(index), isMatched: false });
+            break;
+        }
+        parts.push({ type: "static", content: segment.slice(index, start), isMatched: false });
+        const type = PARAM_TYPES[segment[start + 1] ?? ""] ?? "required";
+        const delimiter = type === "optional" ? "]]" : "]";
+        const end = segment.indexOf(delimiter, start);
+        if (end === -1)
+            return [{ type: "static", content: segment, isMatched: false }];
+        index = end + delimiter.length;
+        const content = segment.slice(start, index);
+        parts.push({ type, content, isMatched: content.includes("=") });
+    }
+    return parts;
+};
+/**
+ * A route id's segments as the sort compares them: an optional param that is not at the end left out, groups too.
+ *
+ * @param id - the route id.
+ */
+const sortedSegments = (id) => id
+    .replace(/\[\[[^\]]+\]\](?!(?:\/\([^/]+\))*$)/g, "")
+    .slice(1)
+    .split("/")
+    .filter((segment) => segment !== "" && !GROUP.test(segment))
+    .map(partsOf);
+/**
+ * Orders two texts as SvelteKit does: by their characters, except that `foobar` outranks `foo`.
+ *
+ * @param first - a text.
+ * @param second - another.
+ */
+const byText = (first, second) => {
+    for (let index = 0;; index += 1) {
+        const a = first[index];
+        const b = second[index];
+        if (a === b) {
+            if (a === undefined)
+                return 0;
+            continue;
+        }
+        if (a === undefined)
+            return 1;
+        if (b === undefined)
+            return -1;
+        return a < b ? -1 : 1;
+    }
+};
+/**
+ * Orders two params at the same place of two routes, or none when they rank the same.
+ *
+ * @param a - the first route's param.
+ * @param b - the second's.
+ * @param nextA - the text after the first's, in its segment or the next.
+ * @param nextB - the text after the second's.
+ */
+const byParam = (a, b, nextA, nextB) => {
+    if (a.type === "rest" || b.type === "rest")
+        return byRest(a, b, nextA, nextB);
+    if (a.isMatched !== b.isMatched)
+        return a.isMatched ? -1 : 1;
+    if (a.type !== b.type) {
+        if (a.type === "required")
+            return -1;
+        if (b.type === "required")
+            return 1;
+    }
+    return undefined;
+};
+/**
+ * Orders two params at the same place when one is a rest param: `[...rest]/x` outranks a plain param, which outranks
+ * a bare `[...rest]`.
+ *
+ * @param a - the first route's param.
+ * @param b - the second's.
+ * @param nextA - the text after the first's.
+ * @param nextB - the text after the second's.
+ */
+const byRest = (a, b, nextA, nextB) => {
+    if (a.type === "rest" && b.type === "rest") {
+        if (nextA !== "" && nextB !== "")
+            return undefined;
+        if (nextA !== "")
+            return -1;
+        return nextB !== "" ? 1 : undefined;
+    }
+    if (a.type === "rest")
+        return nextA !== "" && nextB === "" ? -1 : 1;
+    return nextB !== "" && nextA === "" ? 1 : -1;
+};
+/**
+ * The text that follows a part: the next part of its segment, or the first of the next segment.
+ *
+ * @param segments - the route's segments.
+ * @param segment - the part's segment.
+ * @param part - the part.
+ */
+const nextText = (segments, segment, part) => segments[segment]?.[part + 1]?.content || segments[segment + 1]?.[0]?.content || "";
+/**
+ * Orders two segments at the same place of two routes, or none when they rank the same.
+ *
+ * @param segmentsA - the first route's segments.
+ * @param segmentsB - the second's.
+ * @param index - the segments' place.
+ */
+const bySegment = (segmentsA, segmentsB, index) => {
+    const segmentA = segmentsA[index] ?? [EMPTY];
+    const segmentB = segmentsB[index] ?? [EMPTY];
+    for (let part = 0; part < Math.max(segmentA.length, segmentB.length); part += 1) {
+        const order = byPart(segmentA[part], segmentB[part], part % 2 === 1, () => [
+            nextText(segmentsA, index, part),
+            nextText(segmentsB, index, part)
+        ]);
+        if (order !== undefined)
+            return order;
+    }
+    return undefined;
+};
+/**
+ * Orders two parts at the same place of two segments, or none when they rank the same.
+ *
+ * @param a - the first segment's part, or none past its end.
+ * @param b - the second's.
+ * @param isParam - whether the place holds params: a segment starts with a text, maybe empty, then alternates.
+ * @param nextTexts - the texts after each param.
+ */
+const byPart = (a, b, isParam, nextTexts) => {
+    if (isParam) {
+        if (a === undefined)
+            return -1;
+        if (b === undefined)
+            return 1;
+        const [nextA, nextB] = nextTexts();
+        return byParam(a, b, nextA, nextB);
+    }
+    if (a?.content === b?.content)
+        return undefined;
+    if (a === undefined || a === EMPTY)
+        return -1;
+    if (b === undefined || b === EMPTY)
+        return 1;
+    return byText(a.content, b.content);
+};
+/**
+ * Orders two routes, the one SvelteKit tries first first.
+ *
+ * @param first - a route id.
+ * @param second - another.
+ */
+export const byRouteOrder = (first, second) => {
+    const segmentsA = sortedSegments(first);
+    const segmentsB = sortedSegments(second);
+    for (let index = 0; index < Math.max(segmentsA.length, segmentsB.length); index += 1) {
+        const order = bySegment(segmentsA, segmentsB, index);
+        if (order !== undefined)
+            return order;
+    }
+    return first < second ? 1 : -1;
+};

package/dist/src/stories.d.ts

@@ -0,0 +1,48 @@
+/**
+ * The story types for a SvelteKit project: Svelte's, with the `parameters.sveltekit` a story sets its page, its data
+ * and its navigation with (`import type { Meta, Story } from "@forgebook/sveltekit"`).
+ *
+ * @remarks
+ * `navigation`, `forms` and `hrefs` are written as Storybook's SvelteKit framework writes them under
+ * `sveltekit_experimental`, which is read too, so a story moved from Storybook keeps its page; `page`, `load` and
+ * `serverData` are Forgebook's. Types only.
+ *
+ * @module
+ */
+import type { StoryParameters } from "@forgebook/story-format/csf";
+import type { AnyComponent, NoComponent, Meta as SvelteMeta, Preview as SveltePreview, Story as SvelteStory } from "@forgebook/svelte";
+import type { HrefParameter, KitActionResult, KitLoadEvent, KitPage, PageParameters, StoryLoad, SveltekitParameters } from "./kitParameters.ts";
+/** A story's SvelteKit settings (`parameters.sveltekit`). */
+export type StorySveltekit = SveltekitParameters;
+/** The page a story starts on (`parameters.sveltekit.page`). */
+export type StoryPageParameters = PageParameters;
+/** The page a story's components read, as `page` from `$app/state` gives it. */
+export type StoryKitPage = KitPage;
+/** A universal `load` a story runs (`parameters.sveltekit.load`). */
+export type StoryKitLoad = StoryLoad;
+/** What a story's `load` receives. */
+export type StoryKitLoadEvent = KitLoadEvent;
+/** An action's result, as `parameters.sveltekit.forms.result` gives it. */
+export type StoryActionResult = KitActionResult;
+/** An `hrefs` entry: a callback, or one with whether its key is a regular expression. */
+export type StoryHref = HrefParameter;
+/** A story's parameters: the catalogue's settings, and its SvelteKit ones. */
+export type SveltekitStoryParameters = StoryParameters & {
+    /** The story's page, its data and what its navigation, forms and links do. */
+    readonly sveltekit?: StorySveltekit;
+};
+/** A story file's default export: `{ title, component, parameters: { sveltekit } } satisfies Meta<typeof Nav>`. */
+export type Meta<TComponent extends AnyComponent = NoComponent> = Omit<SvelteMeta<TComponent>, "parameters"> & {
+    /** Settings for every story of the file, its page among them. */
+    readonly parameters?: SveltekitStoryParameters;
+};
+/** A story: a named export of a story file. */
+export type Story<TComponent extends AnyComponent = NoComponent> = Omit<SvelteStory<TComponent>, "parameters"> & {
+    /** Settings over the meta's, its page among them. */
+    readonly parameters?: SveltekitStoryParameters;
+};
+/** A SvelteKit catalogue's preview (`forgebook.preview.ts`): Svelte's, with a page every story starts from. */
+export type Preview = Omit<SveltePreview, "parameters"> & {
+    /** Settings every story starts from, a page among them. */
+    readonly parameters?: SveltekitStoryParameters;
+};

package/dist/src/stories.js

@@ -0,0 +1,11 @@
+/**
+ * The story types for a SvelteKit project: Svelte's, with the `parameters.sveltekit` a story sets its page, its data
+ * and its navigation with (`import type { Meta, Story } from "@forgebook/sveltekit"`).
+ *
+ * @remarks
+ * `navigation`, `forms` and `hrefs` are written as Storybook's SvelteKit framework writes them under
+ * `sveltekit_experimental`, which is read too, so a story moved from Storybook keeps its page; `page`, `load` and
+ * `serverData` are Forgebook's. Types only.
+ *
+ * @module
+ */

package/dist/src/storyCode.d.ts

@@ -0,0 +1,3 @@
+import type { StoryCodeWriter } from "forgebook/renderer";
+/** Writes a story drawn from its args as Svelte markup. */
+export declare const codeOf: StoryCodeWriter;

package/dist/src/storyCode.js

@@ -0,0 +1,9 @@
+/**
+ * The code writer of a SvelteKit catalogue: a story drawn from its args written as Svelte markup, as Svelte's catalogue
+ * writes it, under this package's name, so a catalogue needs no other Forgebook package of its own.
+ *
+ * @module
+ */
+import { codeOf as svelteCodeOf } from "@forgebook/svelte/code";
+/** Writes a story drawn from its args as Svelte markup. */
+export const codeOf = svelteCodeOf;

package/dist/src/storyPage.d.ts

@@ -0,0 +1,35 @@
+/**
+ * What a play function reads of a SvelteKit story's page: where its links and `goto` calls took it, its data and form,
+ * and the calls it made (`goto`, `invalidateAll`, `enhance`), to assert on.
+ *
+ * @example
+ * ```ts
+ * import { storyPage } from "@forgebook/sveltekit/page";
+ *
+ * export const GoesToAbout: Story<typeof Nav> = {
+ *   play: async ({ canvasElement }) => {
+ *     await userEvent.click(within(canvasElement).getByRole("link", { name: "About" }));
+ *     expect(storyPage().pathname).toBe("/about");
+ *   }
+ * };
+ * ```
+ *
+ * @module
+ */
+import type { KitPage } from "./kitParameters.ts";
+import { type KitCall } from "./kitStore.ts";
+/** A story's page as a play function reads it. */
+export type StoryPageState = Pick<KitPage, "params" | "data" | "form" | "state" | "status" | "error"> & {
+    /** The page's path, its base path included (`/blog/hello`). */
+    readonly pathname: string;
+    /** The search params, by name: the last value of a name given twice. */
+    readonly query: Readonly<Record<string, string>>;
+    /** The hash, with its `#`, or empty. */
+    readonly hash: string;
+    /** The route's id, or `null` when no route of the project matches. */
+    readonly routeId: string | null;
+    /** The calls the story made to SvelteKit, in order. */
+    readonly calls: readonly KitCall[];
+};
+/** The page of the story drawn now, and the calls it made. */
+export declare const storyPage: () => StoryPageState;

package/dist/src/storyPage.js

@@ -0,0 +1,19 @@
+import { currentStore } from "./kitStore.js";
+/** The page of the story drawn now, and the calls it made. */
+export const storyPage = () => {
+    const store = currentStore();
+    const page = store.page();
+    return {
+        pathname: page.url.pathname,
+        query: Object.fromEntries(page.url.searchParams),
+        hash: page.url.hash,
+        routeId: page.route.id,
+        params: page.params,
+        data: page.data,
+        form: page.form,
+        state: page.state,
+        status: page.status,
+        error: page.error,
+        calls: store.calls()
+    };
+};

package/dist/src/vite/envModules.d.ts

@@ -0,0 +1,67 @@
+import { type Alias } from "vite";
+/** The modules only a server may load, with what each is. */
+export declare const SERVER_ONLY: Readonly<Record<string, string>>;
+/** The public environment modules, by the name a component imports. */
+export declare const PUBLIC_ENV: readonly ["$env/static/public", "$env/dynamic/public", "$app/env/public"];
+/** A public environment module's name. */
+export type PublicEnvModule = (typeof PUBLIC_ENV)[number];
+/**
+ * A module that refuses to load in a story: it declares the names its importer asked for, so the browser links it and
+ * runs it, and its error, which says why, is the one the frame shows.
+ *
+ * @param id - the module's name, with the names it is imported with (`$app/env/private?names=TOKEN`).
+ * @param reason - the error's message.
+ */
+export declare const refusedModule: (id: string, reason: string) => string;
+/**
+ * A server-only module, refusing to load with why.
+ *
+ * @param id - the module's name, with the names it is imported with.
+ */
+export declare const serverOnlyModule: (id: string) => string;
+/**
+ * A module's code with its named imports of SvelteKit's environment and server modules naming what they import, so a
+ * module that refuses to load (`refusedModule`) can declare them.
+ *
+ * @param code - the module's code.
+ * @returns the code, or none when it imports none of those modules by name.
+ */
+export declare const namedServerImports: (code: string) => string | undefined;
+/**
+ * The environment or server module of SvelteKit a name stands for, its query left out; none for another module.
+ *
+ * @param source - an import's module.
+ */
+export declare const kitModuleName: (source: string) => string | undefined;
+/**
+ * Whether a name is a server-only module, its query left out.
+ *
+ * @param source - an import's module.
+ */
+export declare const isServerOnly: (source: string) => boolean;
+/**
+ * The variables SvelteKit 2 gives the browser: those with the public prefix, and not the private one.
+ *
+ * @param env - every variable, by name.
+ * @param publicPrefix - `env.publicPrefix` (`PUBLIC_`).
+ * @param privatePrefix - `env.privatePrefix` (empty by default).
+ */
+export declare const publicVariables: (env: Readonly<Record<string, string>>, publicPrefix: string, privatePrefix: string) => Record<string, string>;
+/**
+ * A module of named exports, one per variable: what a name JavaScript cannot export is left out.
+ *
+ * @param values - the values, by name.
+ */
+export declare const namedExports: (values: Readonly<Record<string, unknown>>) => string;
+/**
+ * The public variables a SvelteKit 3 project declares in `src/env.ts`, checked by their schemas.
+ *
+ * @param srcDir - the project's source folder (`src`).
+ * @param env - every variable, by name.
+ * @param aliases - the project's aliases.
+ * @returns the values by name, and the files read; none without an env file.
+ */
+export declare const declaredPublicVariables: (srcDir: string, env: Readonly<Record<string, string>>, aliases?: readonly Alias[]) => Promise<{
+    readonly values: Record<string, unknown>;
+    readonly file: string;
+} | undefined>;