@forgebook/nuxt 0.0.0-stage → 0.2.0

package/dist/src/app/data.js

@@ -0,0 +1,155 @@
+/**
+ * Nuxt's data fetching in a catalogue: `useAsyncData`, its lazy form, `refreshNuxtData`, `clearNuxtData` and
+ * `useNuxtData`. `useFetch` is written on it (`fetch.ts`).
+ *
+ * @remarks
+ * A story gives the data of a key (`parameters.nuxt.data`) and the composable returns it without calling its handler,
+ * as Nuxt returns the payload the server sent. Without it the handler runs. The calls of one key share their data, as
+ * Nuxt's do; a key that is a ref follows it, each value with its own data. A call without a key gets the one the plugin
+ * writes for its place in the code, as Nuxt's compiler does.
+ *
+ * On the server (a generated server test) no handler runs, since no server is there to answer: the story's data is
+ * drawn, or nothing.
+ *
+ * What is returned is Nuxt 4's: `data` and `error` are `undefined` until there is one, and the result can be awaited,
+ * at once for a lazy call. `server`, `dedupe` and `deep` change nothing in the page, where everything runs.
+ *
+ * Internal: the code the plugin writes imports it (`#imports`, `#app`, `#components`); a story or a component imports
+ * Nuxt's names as in the app, never this module, whose exports may change in any release.
+ *
+ * @module
+ */
+import { computed, getCurrentScope, isRef, onScopeDispose, watch } from "vue";
+import { entryOf, startRun, waitedRun } from "../asyncDataRun.js";
+import { useNuxtStore } from "../nuxtStore.js";
+/**
+ * A call read as Nuxt reads it: `(key, handler, options)`, or `(handler, options)` under the key the plugin wrote last
+ * for its place in the code, or a key of its own.
+ *
+ * @param store - the story's store, for a key of its own.
+ * @param first - the key, or the handler.
+ * @param second - the handler, the options, or the plugin's key.
+ * @param third - the options, or the plugin's key.
+ */
+const readCall = (store, first, second, third) => {
+    if (typeof first !== "function")
+        return {
+            key: first,
+            handler: typeof second === "function" ? second : undefined,
+            options: typeof third === "object" ? third : {}
+        };
+    const placeKey = typeof second === "string" ? second : third;
+    return {
+        key: typeof placeKey === "string" ? placeKey : store.nextKey("data"),
+        handler: first,
+        options: typeof second === "object" ? second : {}
+    };
+};
+export function useAsyncData(first, second, third) {
+    const store = useNuxtStore();
+    const { key, handler, options } = readCall(store, first, second, third);
+    const keyNow = () => (isRef(key) ? key.value : key);
+    const entryNow = () => entryOf(store, keyNow(), () => options.default?.());
+    const start = () => startRun(store, entryNow(), keyNow(), handler, options);
+    const firstEntry = entryNow();
+    firstEntry.refresh ??= start;
+    const started = options.immediate === false ? Promise.resolve() : waitedRun(firstEntry, start);
+    const sources = options.watch === false ? [] : [...(options.watch ?? []), ...(isRef(key) ? [key] : [])];
+    if (sources.length > 0) {
+        const stop = watch(sources, () => {
+            void start();
+        });
+        if (getCurrentScope() !== undefined)
+            onScopeDispose(stop);
+    }
+    const asyncData = {
+        data: computed({
+            get: () => entryNow().data.value,
+            set: (value) => {
+                entryNow().data.value = value;
+            }
+        }),
+        pending: computed(() => entryNow().status.value === "pending"),
+        status: computed({
+            get: () => entryNow().status.value,
+            set: (value) => {
+                entryNow().status.value = value;
+            }
+        }),
+        error: computed({
+            get: () => entryNow().error.value,
+            set: (value) => {
+                entryNow().error.value = value;
+            }
+        }),
+        refresh: start,
+        execute: start,
+        clear: () => clearEntry(entryNow())
+    };
+    // a lazy call does not hold what awaits it, as Nuxt's lazy fetch does not hold navigation
+    const awaited = options.lazy === true ? Promise.resolve() : started;
+    return Object.assign(awaited.then(() => asyncData), asyncData);
+}
+/**
+ * `useAsyncData` that does not hold what awaits it.
+ *
+ * @param key - the key.
+ * @param handler - what fetches the data.
+ * @param options - its options.
+ */
+export const useLazyAsyncData = (key, handler, options = {}) => useAsyncData(key, handler, { ...options, lazy: true });
+/**
+ * Empties an entry, as before its first run: its data back to its default.
+ *
+ * @param entry - the entry.
+ */
+const clearEntry = (entry) => {
+    entry.runId += 1;
+    entry.controller?.abort();
+    entry.data.value = entry.defaultData();
+    entry.error.value = undefined;
+    entry.status.value = "idle";
+};
+/**
+ * The keys a function for every key takes: the ones given, or all.
+ *
+ * @param store - the story's store.
+ * @param keys - a key, keys, or none.
+ */
+const keysOf = (store, keys) => {
+    if (keys === undefined)
+        return [...store.asyncData.keys()];
+    return typeof keys === "string" ? [keys] : keys;
+};
+/**
+ * Runs the handlers of keys again.
+ *
+ * @param keys - a key, keys, or none for all.
+ */
+export const refreshNuxtData = async (keys) => {
+    const store = useNuxtStore();
+    await Promise.all(keysOf(store, keys).map((key) => store.asyncData.get(key)?.refresh?.()));
+};
+/**
+ * Empties the data of keys, back to each one's default.
+ *
+ * @param keys - a key, keys, or none for all.
+ */
+export const clearNuxtData = (keys) => {
+    const store = useNuxtStore();
+    for (const key of keysOf(store, keys)) {
+        const entry = store.asyncData.get(key);
+        if (entry !== undefined)
+            clearEntry(entry);
+    }
+};
+/**
+ * The data of a key another call fetched.
+ *
+ * @param key - the key.
+ */
+export const useNuxtData = (key) => {
+    const store = useNuxtStore();
+    const given = Object.hasOwn(store.storyData, key) ? store.storyData[key] : undefined;
+    return { data: entryOf(store, key, () => given).data };
+};

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

@@ -0,0 +1,30 @@
+/**
+ * Nuxt's `define…` helpers in a catalogue: each returns what it is given, as Nuxt's do once its compiler has read them,
+ * so a component, a plugin or the app config written with one loads as it is.
+ *
+ * Internal: the code the plugin writes imports it (`#imports`, `#app`, `#components`); a story or a component imports
+ * Nuxt's names as in the app, never this module, whose exports may change in any release.
+ *
+ * @module
+ */
+import { defineComponent } from "vue";
+/** A component written with Nuxt's helper: Vue's `defineComponent`, since its `asyncData` option is Nuxt 2's. */
+export declare const defineNuxtComponent: typeof defineComponent;
+/**
+ * A plugin: the plugin itself, since a story runs none.
+ *
+ * @param plugin - the plugin.
+ */
+export declare const defineNuxtPlugin: <TPlugin>(plugin: TPlugin) => TPlugin;
+/**
+ * A payload plugin: the plugin itself, since a story runs none.
+ *
+ * @param plugin - the plugin.
+ */
+export declare const definePayloadPlugin: <TPlugin>(plugin: TPlugin) => TPlugin;
+/**
+ * The app config, as `app.config.ts` writes it: the config itself.
+ *
+ * @param config - the config.
+ */
+export declare const defineAppConfig: <TConfig>(config: TConfig) => TConfig;

package/dist/src/app/define.js

@@ -0,0 +1,30 @@
+/**
+ * Nuxt's `define…` helpers in a catalogue: each returns what it is given, as Nuxt's do once its compiler has read them,
+ * so a component, a plugin or the app config written with one loads as it is.
+ *
+ * Internal: the code the plugin writes imports it (`#imports`, `#app`, `#components`); a story or a component imports
+ * Nuxt's names as in the app, never this module, whose exports may change in any release.
+ *
+ * @module
+ */
+import { defineComponent } from "vue";
+/** A component written with Nuxt's helper: Vue's `defineComponent`, since its `asyncData` option is Nuxt 2's. */
+export const defineNuxtComponent = defineComponent;
+/**
+ * A plugin: the plugin itself, since a story runs none.
+ *
+ * @param plugin - the plugin.
+ */
+export const defineNuxtPlugin = (plugin) => plugin;
+/**
+ * A payload plugin: the plugin itself, since a story runs none.
+ *
+ * @param plugin - the plugin.
+ */
+export const definePayloadPlugin = (plugin) => plugin;
+/**
+ * The app config, as `app.config.ts` writes it: the config itself.
+ *
+ * @param config - the config.
+ */
+export const defineAppConfig = (config) => config;

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

@@ -0,0 +1,43 @@
+/**
+ * Nuxt's error composables in a catalogue: `createError` and `isNuxtError` as Nuxt's, and the error `showError` sets and
+ * `useError` returns, kept in the story's store instead of replacing a page with Nuxt's error page.
+ *
+ * @remarks
+ * `showError` is recorded among the story's events, so a story shows what its component would have shown the user.
+ *
+ * Internal: the code the plugin writes imports it (`#imports`, `#app`, `#components`); a story or a component imports
+ * Nuxt's names as in the app, never this module, whose exports may change in any release.
+ *
+ * @module
+ */
+import type { Ref } from "vue";
+import { type NuxtError, type NuxtErrorInput } from "../nuxtError.ts";
+/**
+ * An error as Nuxt makes it: from a message, Nuxt's fields, or another error.
+ *
+ * @param input - the message, the fields or the error.
+ */
+export declare const createError: (input: string | NuxtErrorInput | Error) => NuxtError;
+/**
+ * Whether a value is an error Nuxt made.
+ *
+ * @param value - the value.
+ */
+export declare const isNuxtError: (value: unknown) => value is NuxtError;
+/** The error `showError` set, if any. */
+export declare const useError: () => Ref<NuxtError | undefined>;
+/**
+ * Shows an error, as Nuxt's error page would: the story's `useError` returns it, and the call is recorded.
+ *
+ * @param input - the message, the fields or the error.
+ * @returns the error.
+ */
+export declare const showError: (input: string | NuxtErrorInput | Error) => NuxtError;
+/**
+ * Clears the error, and goes where `redirect` says.
+ *
+ * @param options - where to go after.
+ */
+export declare const clearError: (options?: {
+    readonly redirect?: string;
+}) => Promise<void>;

package/dist/src/app/errors.js

@@ -0,0 +1,41 @@
+import { createError as createNuxtError, isNuxtError as isError } from "../nuxtError.js";
+import { useNuxtStore } from "../nuxtStore.js";
+/**
+ * An error as Nuxt makes it: from a message, Nuxt's fields, or another error.
+ *
+ * @param input - the message, the fields or the error.
+ */
+export const createError = (input) => createNuxtError(input);
+/**
+ * Whether a value is an error Nuxt made.
+ *
+ * @param value - the value.
+ */
+export const isNuxtError = (value) => isError(value);
+/** The error `showError` set, if any. */
+export const useError = () => useNuxtStore().error;
+/**
+ * Shows an error, as Nuxt's error page would: the story's `useError` returns it, and the call is recorded.
+ *
+ * @param input - the message, the fields or the error.
+ * @returns the error.
+ */
+export const showError = (input) => {
+    const store = useNuxtStore();
+    const error = createNuxtError(input);
+    store.error.value = error;
+    store.record("showError", [error.statusCode, error.message]);
+    return error;
+};
+/**
+ * Clears the error, and goes where `redirect` says.
+ *
+ * @param options - where to go after.
+ */
+export const clearError = async (options = {}) => {
+    const store = useNuxtStore();
+    store.error.value = undefined;
+    store.record("clearError", options.redirect === undefined ? [] : [options.redirect]);
+    if (options.redirect !== undefined)
+        await store.move(options.redirect, true);
+};

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

@@ -0,0 +1,63 @@
+/**
+ * Nuxt's `useFetch`, its lazy form and `$fetch` in a catalogue: `useAsyncData` with the story's `$fetch`.
+ *
+ * @remarks
+ * Its key is the request as it is made, so a story can write it: the URL with its query, the method before it when not
+ * GET, the body after it when there is one (`/api/products?page=2`, `POST /api/cart {"id":1}`). Nuxt's own key is a
+ * hash of the same, which a story could not write. Its URL, query, body and method may be refs or getters: a change
+ * makes another key, and another request, as in Nuxt, unless `watch: false`. Without the story's data for the key, the
+ * request goes out, and the catalogue's MSW handlers answer it.
+ *
+ * Internal: the code the plugin writes imports it (`#imports`, `#app`, `#components`); a story or a component imports
+ * Nuxt's names as in the app, never this module, whose exports may change in any release.
+ *
+ * @module
+ */
+import { type MaybeRefOrGetter } from "vue";
+import { type FetchQuery, type StoryFetchOptions } from "../storyFetch.ts";
+import { type AsyncData, type AsyncDataOptions } from "./data.ts";
+/** What `useFetch` takes: the request's options, each of which may follow a ref, and `useAsyncData`'s. */
+export type UseFetchOptions<TResult> = AsyncDataOptions<TResult> & Pick<StoryFetchOptions, "baseURL" | "responseType"> & {
+    /** The key the data is shared and given under; the request as it is made by default. */
+    readonly key?: string;
+    /** The request's method; GET by default. */
+    readonly method?: MaybeRefOrGetter<string>;
+    /** The search params, by name; each value may be a ref too. */
+    readonly query?: MaybeRefOrGetter<FetchQuery>;
+    /** `query`'s other name. */
+    readonly params?: MaybeRefOrGetter<FetchQuery>;
+    /** The body: an object or an array is sent as JSON. */
+    readonly body?: MaybeRefOrGetter<unknown>;
+    /** The headers. */
+    readonly headers?: MaybeRefOrGetter<HeadersInit>;
+};
+/**
+ * The key of a request: the URL with its query, the method before it when not GET, the body after it.
+ *
+ * @param method - the method, in capitals.
+ * @param url - the URL.
+ * @param query - the search params.
+ * @param body - the body, if any.
+ */
+export declare const fetchKey: (method: string, url: string, query: FetchQuery, body: unknown) => string;
+/**
+ * Fetches a URL, as `useAsyncData` with `$fetch`: the story's data for its key when it gives some, else the request.
+ *
+ * @param url - the URL, or a ref or getter that gives it.
+ * @param options - the request's options and `useAsyncData`'s.
+ */
+export declare const useFetch: <TResult = unknown>(url: MaybeRefOrGetter<string>, options?: UseFetchOptions<TResult>) => AsyncData<TResult> & Promise<AsyncData<TResult>>;
+/**
+ * `useFetch` that does not hold what awaits it.
+ *
+ * @param url - the URL.
+ * @param options - its options.
+ */
+export declare const useLazyFetch: <TResult = unknown>(url: MaybeRefOrGetter<string>, options?: UseFetchOptions<TResult>) => AsyncData<TResult> & Promise<AsyncData<TResult>>;
+/**
+ * Fetches a URL, as Nuxt's `$fetch` (ofetch), with the app's base path.
+ *
+ * @param request - the URL.
+ * @param options - the request's options.
+ */
+export declare const $fetch: <TResult = unknown>(request: string, options?: StoryFetchOptions) => Promise<TResult>;

package/dist/src/app/fetch.js

@@ -0,0 +1,73 @@
+/**
+ * Nuxt's `useFetch`, its lazy form and `$fetch` in a catalogue: `useAsyncData` with the story's `$fetch`.
+ *
+ * @remarks
+ * Its key is the request as it is made, so a story can write it: the URL with its query, the method before it when not
+ * GET, the body after it when there is one (`/api/products?page=2`, `POST /api/cart {"id":1}`). Nuxt's own key is a
+ * hash of the same, which a story could not write. Its URL, query, body and method may be refs or getters: a change
+ * makes another key, and another request, as in Nuxt, unless `watch: false`. Without the story's data for the key, the
+ * request goes out, and the catalogue's MSW handlers answer it.
+ *
+ * Internal: the code the plugin writes imports it (`#imports`, `#app`, `#components`); a story or a component imports
+ * Nuxt's names as in the app, never this module, whose exports may change in any release.
+ *
+ * @module
+ */
+import { computed, toValue } from "vue";
+import { useNuxtStore } from "../nuxtStore.js";
+import { withSearch } from "../storyFetch.js";
+import { useAsyncData } from "./data.js";
+/**
+ * A query whose values may be refs, read now.
+ *
+ * @param query - the query, or what gives it.
+ */
+const queryNow = (query) => Object.fromEntries(Object.entries(toValue(query) ?? {}).map(([name, value]) => [name, toValue(value)]));
+/**
+ * The key of a request: the URL with its query, the method before it when not GET, the body after it.
+ *
+ * @param method - the method, in capitals.
+ * @param url - the URL.
+ * @param query - the search params.
+ * @param body - the body, if any.
+ */
+export const fetchKey = (method, url, query, body) => `${method === "GET" ? "" : `${method} `}${withSearch(url, query)}${body === undefined ? "" : ` ${JSON.stringify(body)}`}`;
+/**
+ * Fetches a URL, as `useAsyncData` with `$fetch`: the story's data for its key when it gives some, else the request.
+ *
+ * @param url - the URL, or a ref or getter that gives it.
+ * @param options - the request's options and `useAsyncData`'s.
+ */
+export const useFetch = (url, options = {}) => {
+    const store = useNuxtStore();
+    const method = () => (toValue(options.method) ?? "GET").toUpperCase();
+    const query = () => queryNow(options.query ?? options.params);
+    const key = computed(() => options.key ?? fetchKey(method(), toValue(url), query(), toValue(options.body)));
+    const headers = toValue(options.headers);
+    return useAsyncData(key, (_app, { signal }) => {
+        const body = toValue(options.body);
+        return store.fetch(toValue(url), {
+            method: method(),
+            query: query(),
+            signal,
+            ...(body === undefined ? {} : { body }),
+            ...(headers === undefined ? {} : { headers }),
+            ...(options.baseURL === undefined ? {} : { baseURL: options.baseURL }),
+            ...(options.responseType === undefined ? {} : { responseType: options.responseType })
+        });
+    }, options);
+};
+/**
+ * `useFetch` that does not hold what awaits it.
+ *
+ * @param url - the URL.
+ * @param options - its options.
+ */
+export const useLazyFetch = (url, options = {}) => useFetch(url, { ...options, lazy: true });
+/**
+ * Fetches a URL, as Nuxt's `$fetch` (ofetch), with the app's base path.
+ *
+ * @param request - the URL.
+ * @param options - the request's options.
+ */
+export const $fetch = (request, options) => useNuxtStore().fetch(request, options);

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

@@ -0,0 +1,28 @@
+/**
+ * Nuxt's head composables in a catalogue: `useHead`, `useSeoMeta` and their server and safe forms take what a
+ * component sets and leave the frame's document alone, since the frame's head is the catalogue's.
+ *
+ * Internal: the code the plugin writes imports it (`#imports`, `#app`, `#components`); a story or a component imports
+ * Nuxt's names as in the app, never this module, whose exports may change in any release.
+ *
+ * @module
+ */
+/** What a head composable returns: what changes the entry, and what removes it; neither has anything to do. */
+export type HeadEntry = {
+    /** Changes what the entry set. */
+    readonly patch: (input: unknown) => void;
+    /** Removes the entry. */
+    readonly dispose: () => void;
+};
+/** Sets the page's head: the frame's head is the catalogue's, so nothing changes. */
+export declare const useHead: () => HeadEntry;
+/** Sets the page's head from values it escapes: nothing changes in a story. */
+export declare const useHeadSafe: () => HeadEntry;
+/** Sets the page's meta tags: nothing changes in a story. */
+export declare const useSeoMeta: () => HeadEntry;
+/** Sets the head on the server only: nothing, in the page. */
+export declare const useServerHead: () => HeadEntry;
+/** Sets the head on the server only, from values it escapes: nothing, in the page. */
+export declare const useServerHeadSafe: () => HeadEntry;
+/** Sets the meta tags on the server only: nothing, in the page. */
+export declare const useServerSeoMeta: () => HeadEntry;

package/dist/src/app/head.js

@@ -0,0 +1,23 @@
+/**
+ * Nuxt's head composables in a catalogue: `useHead`, `useSeoMeta` and their server and safe forms take what a
+ * component sets and leave the frame's document alone, since the frame's head is the catalogue's.
+ *
+ * Internal: the code the plugin writes imports it (`#imports`, `#app`, `#components`); a story or a component imports
+ * Nuxt's names as in the app, never this module, whose exports may change in any release.
+ *
+ * @module
+ */
+/** An entry with nothing to change or remove. */
+const ENTRY = { patch: () => undefined, dispose: () => undefined };
+/** Sets the page's head: the frame's head is the catalogue's, so nothing changes. */
+export const useHead = () => ENTRY;
+/** Sets the page's head from values it escapes: nothing changes in a story. */
+export const useHeadSafe = () => ENTRY;
+/** Sets the page's meta tags: nothing changes in a story. */
+export const useSeoMeta = () => ENTRY;
+/** Sets the head on the server only: nothing, in the page. */
+export const useServerHead = () => ENTRY;
+/** Sets the head on the server only, from values it escapes: nothing, in the page. */
+export const useServerHeadSafe = () => ENTRY;
+/** Sets the meta tags on the server only: nothing, in the page. */
+export const useServerSeoMeta = () => ENTRY;

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

@@ -0,0 +1,69 @@
+import type { RouteLocationNormalizedLoaded, RouteLocationRaw, Router } from "vue-router";
+/** What `navigateTo` takes besides where to go. */
+export type NavigateToOptions = {
+    /** Whether it replaces the history's entry instead of adding one. */
+    readonly replace?: boolean;
+    /** The HTTP status of a redirect on the server: no effect in a story. */
+    readonly redirectCode?: number;
+    /** Whether the location is outside the app, which Nuxt requires for another origin. */
+    readonly external?: boolean;
+    /** Opens the location in a new window, as `window.open` would, with its target and features. */
+    readonly open?: {
+        readonly target?: string;
+        readonly windowFeatures?: Readonly<Record<string, unknown>>;
+    };
+};
+/**
+ * The story's route, which follows its router: vue-router's `useRoute` in a component's setup, the router's current
+ * route elsewhere, as Nuxt's falls back to its app's.
+ */
+export declare const useRoute: () => RouteLocationNormalizedLoaded;
+/** The story's router: vue-router's own, its moves recorded. */
+export declare const useRouter: () => Router;
+/**
+ * Goes somewhere, as Nuxt's `navigateTo`: inside the app the story's router moves; another origin, or a new window, is
+ * recorded and left alone, so the story's frame stays where it is.
+ *
+ * @param to - where to go: a path, or a location.
+ * @param options - whether it replaces, whether it is external, whether it opens a window.
+ * @returns what the router's move returns; nothing for a navigation the story does not make.
+ * @throws a navigation to another origin without `external: true`, as Nuxt throws it.
+ */
+export declare const navigateTo: (to: RouteLocationRaw | undefined | null, options?: NavigateToOptions) => Promise<unknown>;
+/**
+ * Stops a navigation from a route middleware: there is none in a story, so it returns `false`, as a middleware's
+ * `return false` does.
+ */
+export declare const abortNavigation: () => false;
+/**
+ * A route middleware, as Nuxt defines one: the function itself, since a story runs no middleware.
+ *
+ * @param middleware - the middleware.
+ */
+export declare const defineNuxtRouteMiddleware: <TMiddleware>(middleware: TMiddleware) => TMiddleware;
+/** Adds a route middleware: none runs in a story, so it does nothing. */
+export declare const addRouteMiddleware: () => void;
+/** A page's meta: read by Nuxt when it builds its routes, never at run time, so it does nothing in a story. */
+export declare const definePageMeta: () => void;
+/**
+ * A route's rules, as Nuxt 4 reads them at build time: nothing at run time.
+ */
+export declare const defineRouteRules: () => void;
+/**
+ * Sets the page's layout: a story has no layout, so the call is recorded.
+ *
+ * @param layout - the layout's name.
+ */
+export declare const setPageLayout: (layout: string) => void;
+/** Preloads a route's components: there is nothing to load in a story. */
+export declare const preloadRouteComponents: () => Promise<void>;
+/** Preloads components by name: they load when a story draws them. */
+export declare const preloadComponents: () => Promise<void>;
+/** Prefetches components by name: they load when a story draws them. */
+export declare const prefetchComponents: () => Promise<void>;
+/**
+ * Reloads the app: recorded, since reloading the frame would start the story over.
+ *
+ * @param options - Nuxt's options (`path`, `force`, `persistState`).
+ */
+export declare const reloadNuxtApp: (options?: Readonly<Record<string, unknown>>) => void;

package/dist/src/app/router.js

@@ -0,0 +1,93 @@
+/**
+ * Nuxt's router composables in a catalogue: `useRoute` and `useRouter` are vue-router's own, on the story's router;
+ * `navigateTo` moves it, and records where an external or new-window navigation would have gone instead of leaving the
+ * story's frame.
+ *
+ * @remarks
+ * What Nuxt does with a page (its meta, its layout, its middleware, preloading its code) has no page to act on in a
+ * story, so those functions take their arguments and do nothing, and a story's component is drawn as it is.
+ *
+ * Internal: the code the plugin writes imports it (`#imports`, `#app`, `#components`); a story or a component imports
+ * Nuxt's names as in the app, never this module, whose exports may change in any release.
+ *
+ * @module
+ */
+import { hasInjectionContext } from "vue";
+import { useRoute as useVueRoute } from "vue-router";
+import { useNuxtStore } from "../nuxtStore.js";
+/** Whether an address names another origin, or a protocol other than the web's. */
+const isExternal = (to) => typeof to === "string" && (/^[a-z][a-z\d+.-]*:/i.test(to) || to.startsWith("//"));
+/**
+ * The story's route, which follows its router: vue-router's `useRoute` in a component's setup, the router's current
+ * route elsewhere, as Nuxt's falls back to its app's.
+ */
+export const useRoute = () => hasInjectionContext() ? useVueRoute() : useNuxtStore().router.currentRoute.value;
+/** The story's router: vue-router's own, its moves recorded. */
+export const useRouter = () => useNuxtStore().router;
+/**
+ * Goes somewhere, as Nuxt's `navigateTo`: inside the app the story's router moves; another origin, or a new window, is
+ * recorded and left alone, so the story's frame stays where it is.
+ *
+ * @param to - where to go: a path, or a location.
+ * @param options - whether it replaces, whether it is external, whether it opens a window.
+ * @returns what the router's move returns; nothing for a navigation the story does not make.
+ * @throws a navigation to another origin without `external: true`, as Nuxt throws it.
+ */
+export const navigateTo = async (to, options = {}) => {
+    const store = useNuxtStore();
+    const target = to ?? "/";
+    const path = typeof target === "string" ? target : store.router.resolve(target).fullPath;
+    const flags = {
+        ...(options.replace === true ? { replace: true } : {}),
+        ...(options.external === true ? { external: true } : {}),
+        ...(options.open === undefined ? {} : { open: true })
+    };
+    store.record("navigateTo", Object.keys(flags).length === 0 ? [path] : [path, flags]);
+    // a new window, or a navigation that leaves the app (a full page load), would leave the story's frame
+    if (options.open !== undefined || options.external === true)
+        return undefined;
+    if (isExternal(target))
+        throw new Error("Navigating to an external URL is not allowed by default. Use `navigateTo(url, { external: true })`.");
+    return store.move(target, options.replace === true);
+};
+/**
+ * Stops a navigation from a route middleware: there is none in a story, so it returns `false`, as a middleware's
+ * `return false` does.
+ */
+export const abortNavigation = () => false;
+/**
+ * A route middleware, as Nuxt defines one: the function itself, since a story runs no middleware.
+ *
+ * @param middleware - the middleware.
+ */
+export const defineNuxtRouteMiddleware = (middleware) => middleware;
+/** Adds a route middleware: none runs in a story, so it does nothing. */
+export const addRouteMiddleware = () => undefined;
+/** A page's meta: read by Nuxt when it builds its routes, never at run time, so it does nothing in a story. */
+export const definePageMeta = () => undefined;
+/**
+ * A route's rules, as Nuxt 4 reads them at build time: nothing at run time.
+ */
+export const defineRouteRules = () => undefined;
+/**
+ * Sets the page's layout: a story has no layout, so the call is recorded.
+ *
+ * @param layout - the layout's name.
+ */
+export const setPageLayout = (layout) => {
+    useNuxtStore().record("setPageLayout", [layout]);
+};
+/** Preloads a route's components: there is nothing to load in a story. */
+export const preloadRouteComponents = async () => undefined;
+/** Preloads components by name: they load when a story draws them. */
+export const preloadComponents = async () => undefined;
+/** Prefetches components by name: they load when a story draws them. */
+export const prefetchComponents = async () => undefined;
+/**
+ * Reloads the app: recorded, since reloading the frame would start the story over.
+ *
+ * @param options - Nuxt's options (`path`, `force`, `persistState`).
+ */
+export const reloadNuxtApp = (options = {}) => {
+    useNuxtStore().record("reloadNuxtApp", [options]);
+};