@forgebook/sveltekit 0.0.0-stage → 0.2.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>;

package/dist/src/vite/envModules.js

@@ -0,0 +1,181 @@
+/**
+ * The modules of a SvelteKit project's environment, written for a catalogue: the public variables as SvelteKit gives
+ * them to the browser, and a module that refuses to load for every one only a server may read.
+ *
+ * @remarks
+ * SvelteKit 2 gives the variables whose name has the public prefix (`PUBLIC_`) through `$env/static/public` and
+ * `$env/dynamic/public`; SvelteKit 3 the variables `src/env.ts` declares `public`, checked by their schema, through
+ * `$app/env/public`. Nothing else of the environment reaches the page: `$env/static/private`, `$app/env/private` and
+ * `$app/server` throw as they are loaded, so a component that reads a secret fails in its frame rather than shipping it.
+ *
+ * @module
+ */
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { codeOfJson } from "forgebook/code-literal";
+import { runnerImport } from "vite";
+/** The modules only a server may load, with what each is. */
+export const SERVER_ONLY = {
+    "$env/static/private": "the private environment",
+    "$env/dynamic/private": "the private environment",
+    "$app/env/private": "the private environment",
+    "$app/server": "the server's own functions (getRequestEvent, read, the remote functions)",
+    "$service-worker": "the service worker's own module"
+};
+/** The public environment modules, by the name a component imports. */
+export const PUBLIC_ENV = ["$env/static/public", "$env/dynamic/public", "$app/env/public"];
+/** A name JavaScript takes as an export's. */
+const IDENTIFIER = /^[A-Za-z_$][\w$]*$/;
+/** The words a `const` cannot be named, which a variable or an import may still be called. */
+const RESERVED = new Set("await break case catch class const continue debugger default delete do else enum export extends false finally for function if implements import in instanceof interface let new null package private protected public return static super switch this throw true try typeof var void while with yield".split(" "));
+/** The names `src/env` may have, in the order SvelteKit 3 looks for them. */
+const ENV_FILES = ["env.ts", "env.js", "env.mts", "env.mjs"];
+/** Whether a value is a plain object. */
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/**
+ * A value written in a module: a big integer as its literal, a value JSON writes nothing for as `undefined`.
+ *
+ * @param value - the value.
+ */
+const written = (value) => {
+    if (typeof value === "bigint")
+        return `${value}n`;
+    const json = JSON.stringify(value);
+    return typeof json === "string" ? codeOfJson(json) : "undefined";
+};
+/** The query a server-only import is rewritten with, naming what it imports (`?names=SECRET,TOKEN`). */
+const NAMES_QUERY = "?names=";
+/** An import of named exports: its names and its module. */
+const NAMED_IMPORT = /import\s*(?:[\w$]+\s*,\s*)?\{([^}]*)\}\s*from\s*(["'])([^"']+)\2/g;
+/**
+ * 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 const refusedModule = (id, reason) => {
+    const [, names = ""] = id.split(NAMES_QUERY);
+    const declared = names.split(",").filter((item) => IDENTIFIER.test(item) && !RESERVED.has(item));
+    return [
+        `throw new Error(${written(reason)});`,
+        ...declared.map((item) => `export const ${item} = undefined;`),
+        "export default undefined;",
+        ""
+    ].join("\n");
+};
+/**
+ * A server-only module, refusing to load with why.
+ *
+ * @param id - the module's name, with the names it is imported with.
+ */
+export const serverOnlyModule = (id) => {
+    const name = kitModuleName(id) ?? id;
+    return refusedModule(id, `${name} is ${SERVER_ONLY[name] ?? "server code"}, which only a server may load: a component drawn in a catalogue cannot import it. Give the story what it reads through its args or its page's data.`);
+};
+/**
+ * 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 const namedServerImports = (code) => {
+    let isChanged = false;
+    const rewritten = code.replace(NAMED_IMPORT, (statement, list, quote, source) => {
+        if (kitModuleName(source) === undefined)
+            return statement;
+        isChanged = true;
+        const names = list
+            .split(",")
+            .map((item) => item
+            .trim()
+            .split(/\s+as\s+/)[0]
+            ?.replace(/^type\s+/, "") ?? "")
+            .filter((item) => item !== "");
+        return statement.replace(`${quote}${source}${quote}`, `${quote}${source}${NAMES_QUERY}${names.join(",")}${quote}`);
+    });
+    return isChanged ? rewritten : 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 const kitModuleName = (source) => {
+    const [name = source] = source.split(NAMES_QUERY);
+    return name in SERVER_ONLY || PUBLIC_ENV.some((known) => known === name) ? name : undefined;
+};
+/**
+ * Whether a name is a server-only module, its query left out.
+ *
+ * @param source - an import's module.
+ */
+export const isServerOnly = (source) => {
+    const [name = source] = source.split(NAMES_QUERY);
+    return name in SERVER_ONLY;
+};
+/**
+ * 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 const publicVariables = (env, publicPrefix, privatePrefix) => Object.fromEntries(Object.entries(env).filter(([name]) => name.startsWith(publicPrefix) && (privatePrefix === "" || !name.startsWith(privatePrefix))));
+/**
+ * A module of named exports, one per variable: what a name JavaScript cannot export is left out.
+ *
+ * @param values - the values, by name.
+ */
+export const namedExports = (values) => Object.entries(values)
+    .filter(([name]) => IDENTIFIER.test(name) && !RESERVED.has(name))
+    .map(([name, value]) => `export const ${name} = ${written(value)};\n`)
+    .join("");
+/**
+ * A value checked by a variable's schema: a function, or a Standard Schema (`zod`, `valibot`).
+ *
+ * @param schema - the variable's `schema`.
+ * @param value - the variable's text, or none.
+ * @param name - the variable's name, for the error.
+ */
+const checked = async (schema, value, name) => {
+    if (typeof schema === "function")
+        return Reflect.apply(schema, undefined, [value]);
+    const standard = isRecord(schema) ? schema["~standard"] : undefined;
+    if (!isRecord(standard) || typeof standard["validate"] !== "function") {
+        // SvelteKit wants a variable with no schema set, an empty text included
+        if (value === undefined)
+            throw new Error(`The public variable ${name} is missing: set it, or give it a schema that makes it optional`);
+        return value;
+    }
+    const result = await Reflect.apply(standard["validate"], standard, [value]);
+    if (isRecord(result) && Array.isArray(result["issues"]))
+        throw new Error(`The public variable ${name} is not valid: ${JSON.stringify(result["issues"])}`);
+    return isRecord(result) ? result["value"] : value;
+};
+/**
+ * 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 const declaredPublicVariables = async (srcDir, env, aliases = []) => {
+    const file = ENV_FILES.map((name) => join(srcDir, name)).find((path) => existsSync(path));
+    if (file === undefined)
+        return undefined;
+    // the project's aliases, as SvelteKit gives them to its env file (`$lib/…`)
+    const { module } = await runnerImport(file, {
+        configFile: false,
+        logLevel: "silent",
+        resolve: { alias: [...aliases] }
+    });
+    const variables = module["variables"];
+    const values = {};
+    for (const [name, declared] of Object.entries(isRecord(variables) ? variables : {}))
+        if (isRecord(declared) && declared["public"] === true)
+            values[name] = await checked(declared["schema"], env[name], name);
+    return { values, file };
+};

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

@@ -0,0 +1,14 @@
+import type { ExtractFileComponent, ExtractStoryComponent, StoryFileShape } from "forgebook/vite/adapter";
+/** The module a new story file imports its types from. */
+export declare const storyTypesModule = "@forgebook/sveltekit";
+/** Reads a story file's component, as Svelte's adapter reads it. */
+export declare const extractStoryComponent: ExtractStoryComponent;
+/** Reads a component a file exports, as Svelte's adapter reads it. */
+export declare const extractFileComponent: ExtractFileComponent;
+/**
+ * How a component's stories file is written, as Svelte's adapter writes it.
+ *
+ * @param name - the component's name.
+ * @param file - the component's file, absolute.
+ */
+export declare const storyFileShape: (name: string, file: string) => StoryFileShape;

package/dist/src/vite/extractDocs.js

@@ -0,0 +1,20 @@
+/**
+ * The docs module of a SvelteKit catalogue: Svelte's, since a SvelteKit project's components are Svelte components,
+ * with the story types a new story file imports being this package's (`forgebook new` writes `@forgebook/sveltekit`).
+ *
+ * @module
+ */
+import { extractFileComponent as extractSvelteFileComponent, extractStoryComponent as extractSvelteStoryComponent, storyFileShape as svelteStoryFileShape } from "@forgebook/svelte/docs";
+/** The module a new story file imports its types from. */
+export const storyTypesModule = "@forgebook/sveltekit";
+/** Reads a story file's component, as Svelte's adapter reads it. */
+export const extractStoryComponent = (storyFile) => extractSvelteStoryComponent(storyFile);
+/** Reads a component a file exports, as Svelte's adapter reads it. */
+export const extractFileComponent = (file, exportName) => extractSvelteFileComponent(file, exportName);
+/**
+ * How a component's stories file is written, as Svelte's adapter writes it.
+ *
+ * @param name - the component's name.
+ * @param file - the component's file, absolute.
+ */
+export const storyFileShape = (name, file) => svelteStoryFileShape(name, file);

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

@@ -0,0 +1,28 @@
+import { type VitePaths } from "forgebook/vite/paths";
+import { type Alias, type Plugin } from "vite";
+import { type KitAppSettings } from "../appSettings.ts";
+import type { KitProject } from "./kitProject.ts";
+/**
+ * The aliases of SvelteKit's `alias` option and of `$lib`, as SvelteKit writes them: a name for itself and what is
+ * below it, a name ending in `/*` for what is below it. Each leads to a path in Vite's form, with forward slashes on
+ * every system: what a name leads to is written after it (`$lib/site` to `<lib>/site`), so a Windows path would come
+ * out half in backslashes.
+ *
+ * @param project - the project.
+ * @param paths - the system's path functions; the running system's by default.
+ */
+export declare const projectAliases: (project: Pick<KitProject, "kit" | "dir">, paths?: VitePaths) => Alias[];
+/**
+ * The script the frame's page runs before any module: the settings the stand-ins read. Set inline in the page, so
+ * every value is a `codeLiteral`: no text in it can close the script.
+ *
+ * @param settings - the settings.
+ */
+export declare const pageScript: (settings: KitAppSettings) => string;
+/**
+ * The plugin of a SvelteKit catalogue.
+ *
+ * @param project - the project, read.
+ * @returns the plugin.
+ */
+export declare const kitPlugin: (project: KitProject) => Plugin;