@forgebook/nuxt 0.0.0-stage → 0.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ensiria
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,122 @@
-# Temporary Holding Version
+# @forgebook/nuxt
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Nuxt for [Forgebook](https://www.npmjs.com/package/forgebook): a Nuxt project's components drawn outside Nuxt, with what
+they use of it. Their auto-imports, the `~` and `@` aliases, `#imports`, `#app` and `#components`, Nuxt's router
+through `useRoute`, `navigateTo` and `NuxtLink`, `useFetch` and `useAsyncData`, `useState`, `useCookie`,
+`useRuntimeConfig` and `useAppConfig`. It is [`@forgebook/vue`](https://www.npmjs.com/package/@forgebook/vue) with a
+Vite plugin and a story's own Nuxt.
+
+**Requirements:** Nuxt 3 or 4 · Vue 3.5 · vue-router 4.5 or 5 (Nuxt's) · `forgebook` · Vite 8 · React in the project, for
+the catalogue's own interface (the frames that draw your components load none) ·
+[MIT licence](https://github.com/ensiria/forgebook/blob/develop/packages/nuxt/LICENSE)
+
+```sh
+npm install --save-dev forgebook @forgebook/nuxt react react-dom
+```
+
+The catalogue's configuration, in the Nuxt project's folder, names it as its framework:
+
+```ts
+// forgebook.config.ts
+import { nuxt } from "@forgebook/nuxt/vite";
+import { defineConfig } from "forgebook";
+
+export default defineConfig({
+  framework: nuxt(),
+  title: "My components",
+  stories: ["app/components/**/*.stories.ts"]
+});
+```
+
+and the stories take their types from it. A story says where its component is and what Nuxt would have given it, under
+`parameters.nuxt`:
+
+```ts
+import type { Meta, Story } from "@forgebook/nuxt";
+
+import BlogPost from "./BlogPost.vue"; // `useRoute()`, `useAsyncData(`post-${slug}`, …)`, `<BaseBadge>`
+
+export default {
+  title: "Blog/BlogPost",
+  component: BlogPost,
+  parameters: { nuxt: { route: { name: "blog-slug", params: { slug: "hello" } } } }
+} satisfies Meta<typeof BlogPost>;
+
+// what `useAsyncData` returns for its key, without calling its handler
+export const Published: Story<typeof BlogPost> = {
+  parameters: {
+    nuxt: { route: "/blog/hello", data: { "post-hello": { title: "Hello", status: "published" } } }
+  }
+};
+```
+
+| `parameters.nuxt` | What it sets |
+|---|---|
+| `route` | Where the story starts: a path (`/blog/hello?tab=1`), or a location by path (`{ path, query, hash }`) or by a page's name (`{ name: "blog-slug", params: { slug: "hello" } }`); `/` by default |
+| `data` | What `useAsyncData` and `useFetch` return, by key, without calling their handler. `useFetch`'s key is the request as it is made, unless it is given one: its URL with its query (`/api/products?page=2`), the method before it when not GET, the body after it (`POST /api/cart {"id":1}`) |
+| `state` | What `useState` starts with, by key |
+| `cookies` | What `useCookie` reads, by name |
+| `runtimeConfig.public` | The runtime config's public values, over the project's |
+| `appConfig` | The app config, over the project's |
+
+A story's `nuxt` replaces the meta's whole, as every parameter does: a story that adds `data` writes its `route` too.
+Without `data` for a key, the handler runs, and a request goes out: the catalogue's
+[MSW handlers](https://github.com/ensiria/forgebook/blob/develop/packages/forgebook/README.md) answer it. A play reads
+where the story went, and what it called, with `storyNuxt()`:
+
+```ts
+import { storyNuxt } from "@forgebook/nuxt/story";
+
+export const GoesToAbout: Story<typeof SiteNav> = {
+  play: async ({ canvas, userEvent }) => {
+    await userEvent.click(canvas.getByRole("link", { name: "About" }));
+    await canvas.findByText("On /about");
+    if (storyNuxt().route.path !== "/about") throw new Error("Not on /about");
+  }
+};
+```
+
+| Import | What it is |
+|---|---|
+| `@forgebook/nuxt` | `Meta`, `Story`, `Preview`: Vue's story types, with `parameters.nuxt` |
+| `@forgebook/nuxt/vite` | `nuxt()`, the framework adapter of `forgebook.config.ts`: Vue's plugin and this package's |
+| `@forgebook/nuxt/story` | `storyNuxt()`: the story's route, its calls to Nuxt, its state, cookies and data |
+| `@forgebook/nuxt/renderer` | `nuxtRenderer`, for the generated server tests (`storyServerTests(source, { renderer: nuxtRenderer })`) |
+
+`@forgebook/nuxt/app/*`, `@forgebook/nuxt/project` and `@forgebook/nuxt/code` are internal: the code the plugin
+writes and the catalogue's pages import them, so they may change in any release. A component imports Nuxt's names as it
+does in the app (auto-imported, or from `#imports`).
+
+## What a component gets
+
+The plugin reads `nuxt.config` (with `defineNuxtConfig` given as Nuxt gives it) and the project's folders, and does what
+Nuxt's build does for a component's code:
+
+- **Auto-imports**: Vue's API, the files of `composables/`, `utils/` and `shared/utils/` (and `imports.dirs`), and
+  Nuxt's composables, through unimport, the library Nuxt uses. `#imports` and `#app` export them too.
+- **Components**: the files of `components/` (or the folders `components` names), named as Nuxt names them
+  (`components/base/Button.vue` is `BaseButton`), their `Lazy` forms, and Nuxt's own (`NuxtLink`, `ClientOnly`,
+  `DevOnly`, `NuxtLayout`, `NuxtErrorBoundary`, and `NuxtImg`, drawn as a plain image). `#components` exports them.
+- **Aliases**: `~` and `@` (the sources' folder, `app/` in Nuxt 4's layout), `~~` and `@@` (the project's), `#shared`,
+  `assets`, `public` and the config's `alias`.
+- **The router**: vue-router's own, on a memory history, with a route for each file of `pages/` (named as Nuxt names
+  them) and one for any other path. A link moves it, `useRoute` follows, and the frame's address never changes. Each
+  move and each `navigateTo` is listed among the story's events; a link out of the app is recorded, not followed.
+- **The config**: `useRuntimeConfig()` returns the runtime config's `public` part, its `NUXT_PUBLIC_` variables over it,
+  and `app`; its private keys never reach the page. `useAppConfig()` returns `nuxt.config`'s `appConfig` and
+  `app.config.ts`, merged. The style sheets of `css` load in every frame. `import.meta.client` is `true`.
+
+What Nuxt does on its server has no server to run on: `useRequestHeaders` returns none, `useHead` and `useSeoMeta`
+leave the frame's head alone, `definePageMeta` and route middleware do nothing, and `showError` keeps the error for
+`useError` instead of drawing Nuxt's error page. The generated server tests run no `useAsyncData` handler: they draw
+the story's `data`, or nothing.
+
+Nuxt's own build is not run, so the work of a Nuxt module or plugin is not done: a component that needs what one
+provides (a Pinia store, i18n) gets it from a decorator, and a module's components and composables are not
+auto-imported. `#build/…` modules are Nuxt's build's own and fail by name. Nuxt layers (`extends`) and
+`definePageMeta`'s `path` and `name` are not read. A Nuxt function this package does not stand in for is not given: a
+file that uses one fails on it by name.
+
+`forgebook init --from storybook` reads a project set up with `@storybook-vue/nuxt` (what Nuxt's Storybook module
+writes), and says what a story sets differently. The rest of what Forgebook does is
+[Forgebook's README](https://github.com/ensiria/forgebook/blob/develop/packages/forgebook/README.md).

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

@@ -0,0 +1,119 @@
+/**
+ * Nuxt's built-in components in a catalogue: `NuxtLink` on vue-router's `RouterLink`, `ClientOnly`, `DevOnly`,
+ * `NuxtLayout`, `NuxtErrorBoundary`, and those with nothing to draw in a story (`NuxtPage`, `NuxtLoadingIndicator`,
+ * `NuxtRouteAnnouncer`). `NuxtImg` and `NuxtPicture`, which `@nuxt/image` adds, draw the image as it is, since there is
+ * no image server.
+ *
+ * @remarks
+ * A link inside the app moves the story's router, as Nuxt's does. A link outside it (another origin, `external`, a
+ * target other than `_self`) is drawn as Nuxt draws it, and its click is recorded instead of followed, so the story's
+ * frame stays where 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 { type Component } from "vue";
+import { type RouteLocationRaw } from "vue-router";
+/** What `NuxtLink` takes. */
+export type NuxtLinkProps = {
+    /** Where it goes: a path, a location, or an address outside the app. */
+    readonly to?: RouteLocationRaw;
+    /** `to`'s other name. */
+    readonly href?: RouteLocationRaw;
+    /** Whether the address is outside the app. */
+    readonly external?: boolean;
+    /** The anchor's target. */
+    readonly target?: string;
+    /** The anchor's `rel`; `noopener noreferrer` for an external link by default. */
+    readonly rel?: string;
+    /** Whether an external link gets no `rel`. */
+    readonly noRel?: boolean;
+    /** Whether it replaces the history's entry. */
+    readonly replace?: boolean;
+    /** The class of a link to the current route or one of its parents. */
+    readonly activeClass?: string;
+    /** The class of a link to the current route. */
+    readonly exactActiveClass?: string;
+    /** The `aria-current` of a link to the current route. */
+    readonly ariaCurrentValue?: "page" | "step" | "location" | "date" | "time" | "true" | "false";
+    /** Whether the default slot draws the link itself. */
+    readonly custom?: boolean;
+    /** Whether it prefetches: no effect in a story. */
+    readonly prefetch?: boolean;
+    /** Whether it does not prefetch: no effect in a story. */
+    readonly noPrefetch?: boolean;
+};
+/** A link, inside the app or outside it, as Nuxt's `NuxtLink`. */
+export declare const NuxtLink: import("vue").DefineSetupFnComponent<NuxtLinkProps, import("vue").EmitsOptions, {}, NuxtLinkProps & ({
+    [x: `on${Capitalize<string>}`]: ((...args: any[]) => any) | undefined;
+} | {
+    [x: `on${Capitalize<string>}`]: ((...args: never) => any) | undefined;
+}), import("vue").PublicProps>;
+/** What `ClientOnly` takes. */
+export type ClientOnlyProps = {
+    /** The text drawn before it is mounted. */
+    readonly fallback?: string;
+    /** The element the fallback text is drawn in; `span` by default. */
+    readonly fallbackTag?: string;
+    /** `fallback`'s other name. */
+    readonly placeholder?: string;
+    /** `fallbackTag`'s other name. */
+    readonly placeholderTag?: string;
+};
+/** Draws its content once mounted in the page, and its fallback before (on the server), as Nuxt's. */
+export declare const ClientOnly: import("vue").DefineSetupFnComponent<ClientOnlyProps, import("vue").EmitsOptions, {}, ClientOnlyProps & ({
+    [x: `on${Capitalize<string>}`]: ((...args: any[]) => any) | undefined;
+} | {
+    [x: `on${Capitalize<string>}`]: ((...args: never) => any) | undefined;
+}), import("vue").PublicProps>;
+/** Draws its content in development, which a catalogue is. */
+export declare const DevOnly: import("vue").DefineSetupFnComponent<Record<string, never>, import("vue").EmitsOptions, {}, Record<string, never> & ({
+    [x: `on${Capitalize<string>}`]: ((...args: any[]) => any) | undefined;
+} | {
+    [x: `on${Capitalize<string>}`]: ((...args: never) => any) | undefined;
+}), import("vue").PublicProps>;
+/** A layout: a story has none, so its content is drawn as it is. */
+export declare const NuxtLayout: import("vue").DefineSetupFnComponent<{
+    readonly name?: string;
+    readonly fallback?: string;
+}, import("vue").EmitsOptions, {}, {
+    readonly name?: string;
+    readonly fallback?: string;
+} & ({
+    [x: `on${Capitalize<string>}`]: ((...args: any[]) => any) | undefined;
+} | {
+    [x: `on${Capitalize<string>}`]: ((...args: never) => any) | undefined;
+}), import("vue").PublicProps>;
+/** Catches what its content throws, and draws its `error` slot instead, with what clears it. */
+export declare const NuxtErrorBoundary: import("vue").DefineSetupFnComponent<Record<string, never>, "error"[], {}, Record<string, never> & {
+    onError?: (...args: any[]) => any;
+}, import("vue").PublicProps>;
+/** The page of the route: a story draws its own component, not a page. */
+export declare const NuxtPage: Component;
+/** The bar shown while a page loads: none loads in a story. */
+export declare const NuxtLoadingIndicator: Component;
+/** What tells a screen reader the page changed: no page changes in a story. */
+export declare const NuxtRouteAnnouncer: Component;
+/** What `NuxtImg` takes: the image's attributes. */
+export type NuxtImgProps = {
+    /** The image's address. */
+    readonly src?: string;
+    /** Its text alternative. */
+    readonly alt?: string;
+    /** Its width. */
+    readonly width?: string | number;
+    /** Its height. */
+    readonly height?: string | number;
+    /** How it loads. */
+    readonly loading?: "lazy" | "eager";
+    /** Its sizes. */
+    readonly sizes?: string;
+};
+/** `@nuxt/image`'s image, drawn as it is: there is no image server to resize it. */
+export declare const NuxtImg: import("vue").DefineSetupFnComponent<NuxtImgProps, {}, {}, NuxtImgProps & {}, import("vue").PublicProps>;
+/** `@nuxt/image`'s picture, drawn as one image: there is no image server to give the other formats. */
+export declare const NuxtPicture: import("vue").DefineSetupFnComponent<NuxtImgProps, {}, {}, NuxtImgProps & {}, import("vue").PublicProps>;
+/** The components Nuxt registers itself, by name: what a story's template finds without importing them. */
+export declare const BUILT_IN_COMPONENTS: Readonly<Record<string, Component>>;

package/dist/src/app/components.js

@@ -0,0 +1,196 @@
+/**
+ * Nuxt's built-in components in a catalogue: `NuxtLink` on vue-router's `RouterLink`, `ClientOnly`, `DevOnly`,
+ * `NuxtLayout`, `NuxtErrorBoundary`, and those with nothing to draw in a story (`NuxtPage`, `NuxtLoadingIndicator`,
+ * `NuxtRouteAnnouncer`). `NuxtImg` and `NuxtPicture`, which `@nuxt/image` adds, draw the image as it is, since there is
+ * no image server.
+ *
+ * @remarks
+ * A link inside the app moves the story's router, as Nuxt's does. A link outside it (another origin, `external`, a
+ * target other than `_self`) is drawn as Nuxt draws it, and its click is recorded instead of followed, so the story's
+ * frame stays where 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, h, onErrorCaptured, onMounted, ref } from "vue";
+import { RouterLink } from "vue-router";
+import { useNuxtStore } from "../nuxtStore.js";
+/** Whether an address is outside the app: another origin, or a protocol other than the web's. */
+const isExternalAddress = (to) => typeof to === "string" && (/^[a-z][a-z\d+.-]*:/i.test(to) || to.startsWith("//"));
+/**
+ * Whether a link goes outside the app: `external`, another origin, or a target other than `_self`.
+ *
+ * @param props - the link's props.
+ * @param to - where it goes.
+ */
+const isLinkExternal = (props, to) => props.external === true ||
+    isExternalAddress(to) ||
+    (props.target !== undefined && props.target !== "_self");
+/**
+ * The props `RouterLink` gets from `NuxtLink`'s.
+ *
+ * @param props - the link's props.
+ * @param to - where it goes.
+ */
+const routerLinkProps = (props, to) => ({
+    to,
+    replace: props.replace === true,
+    custom: props.custom === true,
+    ...(props.activeClass === undefined ? {} : { activeClass: props.activeClass }),
+    ...(props.exactActiveClass === undefined ? {} : { exactActiveClass: props.exactActiveClass }),
+    ...(props.ariaCurrentValue === undefined ? {} : { ariaCurrentValue: props.ariaCurrentValue })
+});
+/**
+ * Whether a click would open a link in another tab or window: a modifier key held, or a button other than the first.
+ *
+ * @param event - the click.
+ */
+const isOtherWindowClick = (event) => event.metaKey || event.ctrlKey || event.shiftKey || event.altKey || event.button !== 0;
+/**
+ * What a link does with a click the story's frame must not follow: one that would open another tab (for a link inside
+ * the app, the catalogue's own page at that path), and any click on a link out of the app. The click is recorded among
+ * the story's events instead.
+ *
+ * @param href - where the link goes.
+ * @param isExternal - whether it goes out of the app, so even a plain click stays.
+ * @param record - records a call.
+ */
+const keptClicks = (href, isExternal, record) => {
+    const keep = (event) => {
+        event.preventDefault();
+        record("navigateTo", [href, isOtherWindowClick(event) ? { open: true } : { external: true }]);
+    };
+    return {
+        onClick: (event) => {
+            if (isExternal || isOtherWindowClick(event))
+                keep(event);
+        },
+        onAuxclick: keep
+    };
+};
+/**
+ * A link outside the app, drawn as Nuxt draws it, its click recorded instead of followed.
+ *
+ * @param props - the link's props.
+ * @param href - where it goes.
+ * @param slots - its slots.
+ * @param record - records a call.
+ */
+const externalLink = (props, href, slots, record) => {
+    const rel = props.noRel === true ? undefined : (props.rel ?? "noopener noreferrer");
+    const clicks = keptClicks(href, true, record);
+    if (props.custom === true)
+        return h("span", { style: "display: contents" }, slots["default"]?.({
+            href,
+            navigate: clicks.onClick,
+            rel,
+            target: props.target,
+            isExternal: true,
+            isActive: false
+        }));
+    return h("a", { href, rel, target: props.target, ...clicks }, slots["default"]?.());
+};
+/** A link, inside the app or outside it, as Nuxt's `NuxtLink`. */
+export const NuxtLink = defineComponent((props, { slots }) => {
+    const store = useNuxtStore();
+    return () => {
+        const to = props.to ?? props.href ?? "";
+        const isExternal = isLinkExternal(props, to);
+        const href = typeof to === "string" && isExternal ? to : store.router.resolve(to).href;
+        if (isExternal)
+            return externalLink(props, href, slots, store.record);
+        // a click RouterLink leaves to the browser (another tab) is kept: it would open the catalogue at that path
+        const clicks = props.custom === true ? {} : keptClicks(href, false, store.record);
+        return h(RouterLink, { ...routerLinkProps(props, to), ...clicks }, slots);
+    };
+}, {
+    name: "NuxtLink",
+    props: {
+        to: { type: null, required: false },
+        href: { type: null, required: false },
+        external: { type: Boolean, default: false },
+        target: { type: String, required: false },
+        rel: { type: String, required: false },
+        noRel: { type: Boolean, default: false },
+        replace: { type: Boolean, default: false },
+        activeClass: { type: String, required: false },
+        exactActiveClass: { type: String, required: false },
+        ariaCurrentValue: { type: null, required: false },
+        custom: { type: Boolean, default: false },
+        prefetch: { type: Boolean, default: undefined },
+        noPrefetch: { type: Boolean, default: false }
+    }
+});
+/** Draws its content once mounted in the page, and its fallback before (on the server), as Nuxt's. */
+export const ClientOnly = defineComponent((props, { slots }) => {
+    const isMounted = ref(false);
+    onMounted(() => {
+        isMounted.value = true;
+    });
+    return () => {
+        if (isMounted.value)
+            return slots["default"]?.() ?? null;
+        const fallback = slots["fallback"] ?? slots["placeholder"];
+        if (fallback !== undefined)
+            return fallback();
+        const text = props.fallback ?? props.placeholder;
+        return text === undefined ? null : h(props.fallbackTag ?? props.placeholderTag ?? "span", text);
+    };
+}, { name: "ClientOnly", props: ["fallback", "fallbackTag", "placeholder", "placeholderTag"] });
+/** Draws its content in development, which a catalogue is. */
+export const DevOnly = defineComponent((_props, { slots }) => () => slots["default"]?.() ?? null, { name: "DevOnly" });
+/** A layout: a story has none, so its content is drawn as it is. */
+export const NuxtLayout = defineComponent((_props, { slots }) => () => slots["default"]?.() ?? null, { name: "NuxtLayout", props: ["name", "fallback"] });
+/** Catches what its content throws, and draws its `error` slot instead, with what clears it. */
+export const NuxtErrorBoundary = defineComponent((_props, { slots, emit }) => {
+    const error = ref(null);
+    onErrorCaptured((caught) => {
+        error.value = caught;
+        emit("error", caught);
+        return false;
+    });
+    const clearError = () => {
+        error.value = null;
+    };
+    return () => (error.value === null ? slots["default"]?.() : slots["error"]?.({ error, clearError })) ?? null;
+}, { name: "NuxtErrorBoundary", emits: ["error"] });
+/**
+ * A component with nothing to draw in a story.
+ *
+ * @param name - its name.
+ */
+const nothing = (name) => defineComponent(() => () => null, { name, props: [] });
+/** The page of the route: a story draws its own component, not a page. */
+export const NuxtPage = nothing("NuxtPage");
+/** The bar shown while a page loads: none loads in a story. */
+export const NuxtLoadingIndicator = nothing("NuxtLoadingIndicator");
+/** What tells a screen reader the page changed: no page changes in a story. */
+export const NuxtRouteAnnouncer = nothing("NuxtRouteAnnouncer");
+/**
+ * The image's attributes, as `NuxtImg` gives them: what has no value left out.
+ *
+ * @param props - the props.
+ */
+const imageAttributes = (props) => Object.fromEntries(Object.entries(props).filter(([, value]) => value !== undefined));
+/** `@nuxt/image`'s image, drawn as it is: there is no image server to resize it. */
+export const NuxtImg = defineComponent((props) => () => h("img", imageAttributes(props)), {
+    name: "NuxtImg",
+    props: ["src", "alt", "width", "height", "loading", "sizes"]
+});
+/** `@nuxt/image`'s picture, drawn as one image: there is no image server to give the other formats. */
+export const NuxtPicture = defineComponent((props) => () => h("picture", [h("img", imageAttributes(props))]), { name: "NuxtPicture", props: ["src", "alt", "width", "height", "loading", "sizes"] });
+/** The components Nuxt registers itself, by name: what a story's template finds without importing them. */
+export const BUILT_IN_COMPONENTS = {
+    NuxtLink,
+    ClientOnly,
+    DevOnly,
+    NuxtLayout,
+    NuxtErrorBoundary,
+    NuxtPage,
+    NuxtLoadingIndicator,
+    NuxtRouteAnnouncer,
+    NuxtImg,
+    NuxtPicture
+};

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

@@ -0,0 +1,109 @@
+/**
+ * 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 { type Ref, type WatchSource } from "vue";
+import { type AsyncDataHandler } from "../asyncDataRun.ts";
+import type { NuxtError } from "../nuxtError.ts";
+import { type AsyncDataStatus } from "../nuxtStore.ts";
+/** What `useAsyncData` returns: its data, where it stands, and what runs it again. */
+export type AsyncData<TData> = {
+    /** What the handler returned (transformed and picked), or the story's data for the key. */
+    readonly data: Ref<TData | undefined>;
+    /** Whether the handler is running. */
+    readonly pending: Readonly<Ref<boolean>>;
+    /** Where it stands. */
+    readonly status: Ref<AsyncDataStatus>;
+    /** What the handler threw. */
+    readonly error: Ref<NuxtError | undefined>;
+    /** Runs the handler again. */
+    readonly refresh: () => Promise<void>;
+    /** Runs the handler again: `refresh`'s other name. */
+    readonly execute: () => Promise<void>;
+    /** Empties the data and the error, as before the first run. */
+    readonly clear: () => void;
+};
+/** What `useAsyncData` takes besides its key and handler. */
+export type AsyncDataOptions<TResult> = {
+    /** Whether the server waits for it: no effect in a story. */
+    readonly server?: boolean;
+    /** Whether what awaits it waits for the data; `false` by default. */
+    readonly lazy?: boolean;
+    /** Whether it runs at once; `true` by default. */
+    readonly immediate?: boolean;
+    /** The data before the handler returns, and after a failure. */
+    readonly default?: () => unknown;
+    /** Changes what the handler returned. */
+    readonly transform?: (input: TResult) => unknown;
+    /** The keys of the result kept; all by default. */
+    readonly pick?: readonly string[];
+    /** What runs the handler again when it changes; `false` follows nothing, a key that is a ref included. */
+    readonly watch?: readonly WatchSource[] | false;
+    /** Whether a second call waits for the first (`"defer"`) or starts over (`"cancel"`): no effect in a story. */
+    readonly dedupe?: "cancel" | "defer";
+    /** Whether the data is deep reactive: no effect in a story. */
+    readonly deep?: boolean;
+};
+/** A key: a text, or a ref whose value is the key of the moment. */
+export type AsyncDataKey = string | Readonly<Ref<string>>;
+/**
+ * Fetches data once for a key, shared by every call with the key: the story's data for it when the story gives some,
+ * else what the handler returns.
+ *
+ * @param key - the key, or a ref whose value is the key.
+ * @param handler - what fetches the data.
+ * @param options - its options.
+ */
+export declare function useAsyncData<TResult>(key: AsyncDataKey, handler: AsyncDataHandler<TResult>, options?: AsyncDataOptions<TResult>): AsyncData<TResult> & Promise<AsyncData<TResult>>;
+/**
+ * Fetches data, under the key of its place in the code.
+ *
+ * @param handler - what fetches the data.
+ * @param options - its options.
+ */
+export declare function useAsyncData<TResult>(handler: AsyncDataHandler<TResult>, options?: AsyncDataOptions<TResult>): AsyncData<TResult> & Promise<AsyncData<TResult>>;
+/**
+ * `useAsyncData` that does not hold what awaits it.
+ *
+ * @param key - the key.
+ * @param handler - what fetches the data.
+ * @param options - its options.
+ */
+export declare const useLazyAsyncData: <TResult>(key: AsyncDataKey, handler: AsyncDataHandler<TResult>, options?: AsyncDataOptions<TResult>) => AsyncData<TResult> & Promise<AsyncData<TResult>>;
+/**
+ * Runs the handlers of keys again.
+ *
+ * @param keys - a key, keys, or none for all.
+ */
+export declare const refreshNuxtData: (keys?: string | readonly string[]) => Promise<void>;
+/**
+ * Empties the data of keys, back to each one's default.
+ *
+ * @param keys - a key, keys, or none for all.
+ */
+export declare const clearNuxtData: (keys?: string | readonly string[]) => void;
+/**
+ * The data of a key another call fetched.
+ *
+ * @param key - the key.
+ */
+export declare const useNuxtData: (key: string) => {
+    readonly data: Ref<unknown>;
+};