@forgebook/nuxt 0.0.0-stage → 0.2.0

package/dist/src/vite/placeKeys.js

@@ -0,0 +1,117 @@
+/**
+ * The keys of a place in the code, as Nuxt's compiler writes them: `useState()`, `useAsyncData(handler)` and
+ * `callOnce(fn)` called without a key get one more argument, a key made from the file and the call's place, so every
+ * component that calls them from that place shares the value, and only those.
+ *
+ * @remarks
+ * Nuxt adds the key when the call has fewer arguments than the function takes with one, as here; the stand-ins read a
+ * text last as that key (`src/app`). `useFetch` gets none: its key is the request, which a story writes. A call to a
+ * function of the same name imported from elsewhere is left alone.
+ *
+ * @module
+ */
+import { createHash } from "node:crypto";
+import { codeLiteral } from "forgebook/code-literal";
+/** The functions keyed by their place, with the number of arguments a call has once keyed. */
+const KEYED = {
+    useState: 2,
+    useAsyncData: 3,
+    useLazyAsyncData: 3,
+    callOnce: 3
+};
+/** The modules Nuxt's names come from, besides an auto-import. */
+const NUXT_MODULE = /^(#imports|#app|nuxt\/app|@forgebook\/nuxt\/app\/.+)$/;
+/** Whether a value is a plain object. */
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/**
+ * The names a file imports from a module that is not Nuxt's: a call of one of them is not Nuxt's.
+ *
+ * @param program - the file's syntax tree.
+ */
+const foreignNames = (program) => {
+    const names = new Set();
+    const body = isRecord(program) && Array.isArray(program["body"]) ? program["body"] : [];
+    for (const statement of body)
+        for (const name of importedNames(statement))
+            names.add(name);
+    return names;
+};
+/**
+ * The names a statement imports from a module that is not Nuxt's; none for another statement.
+ *
+ * @param statement - the statement.
+ */
+const importedNames = (statement) => {
+    if (!isRecord(statement) || statement["type"] !== "ImportDeclaration")
+        return [];
+    const source = statement["source"];
+    const from = isRecord(source) && typeof source["value"] === "string" ? source["value"] : "";
+    if (NUXT_MODULE.test(from))
+        return [];
+    const specifiers = Array.isArray(statement["specifiers"]) ? statement["specifiers"] : [];
+    return specifiers.flatMap((specifier) => {
+        const local = isRecord(specifier) ? specifier["local"] : undefined;
+        return isRecord(local) && typeof local["name"] === "string" ? [local["name"]] : [];
+    });
+};
+/**
+ * The calls of a syntax tree that get a key.
+ *
+ * @param node - the tree, or a part of it.
+ * @param foreign - the names imported from elsewhere.
+ * @param found - where the calls found are added.
+ */
+const keyedCalls = (node, foreign, found) => {
+    if (Array.isArray(node)) {
+        for (const each of node)
+            keyedCalls(each, foreign, found);
+        return;
+    }
+    if (!isRecord(node))
+        return;
+    const call = keyedCall(node, foreign);
+    if (call !== undefined)
+        found.push(call);
+    for (const [field, value] of Object.entries(node))
+        if (field !== "type" && typeof value === "object")
+            keyedCalls(value, foreign, found);
+};
+/**
+ * Where a node's key goes, when it is a call of a keyed function without its key.
+ *
+ * @param node - the node.
+ * @param foreign - the names imported from elsewhere.
+ */
+const keyedCall = (node, foreign) => {
+    if (node["type"] !== "CallExpression")
+        return undefined;
+    const callee = node["callee"];
+    const name = isRecord(callee) && callee["type"] === "Identifier" ? callee["name"] : undefined;
+    const length = typeof name === "string" && !foreign.has(name) ? KEYED[name] : undefined;
+    const args = Array.isArray(node["arguments"]) ? node["arguments"] : [];
+    if (length === undefined || args.length >= length)
+        return undefined;
+    const last = args.at(-1);
+    const lastEnd = isRecord(last) ? last["end"] : undefined;
+    if (typeof lastEnd === "number")
+        return { at: lastEnd, isAfterArgument: true };
+    const end = node["end"];
+    return args.length === 0 && typeof end === "number" ? { at: end - 1, isAfterArgument: false } : undefined;
+};
+/**
+ * Gives each call to a keyed function without a key the key of its place.
+ *
+ * @param code - the file's code, changed in place.
+ * @param program - its syntax tree, whose places are the code's.
+ * @param file - the file, as the project names it, which the keys are made from.
+ * @returns whether a key was written.
+ */
+export const withPlaceKeys = (code, program, file) => {
+    const found = [];
+    keyedCalls(program, foreignNames(program), found);
+    for (const call of found) {
+        const key = `$${createHash("sha256").update(`${file}:${call.at}`).digest("base64url").slice(0, 10)}`;
+        code.appendLeft(call.at, `${call.isAfterArgument ? ", " : ""}${codeLiteral(key)}`);
+    }
+    return found.length > 0;
+};

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

@@ -0,0 +1,26 @@
+/**
+ * What a Nuxt project's code gets without importing it, and from where: Nuxt's composables and helpers from this
+ * package's stand-ins (`@forgebook/nuxt/app/…`), Vue's API, and the vue-router functions Nuxt imports for a project.
+ *
+ * @remarks
+ * The table is what `#app` exports, and with the project's own composables what `#imports` exports and what the plugin
+ * imports into a file that uses a name without importing it, as Nuxt does. A Nuxt function not in it is not given: a
+ * file that uses one fails on it by name, which says what a story lacks.
+ *
+ * @module
+ */
+/** A name a file gets without importing it, and the module that has it. */
+export type StandIn = {
+    /** The name. */
+    readonly name: string;
+    /** The module (`@forgebook/nuxt/app/router`). */
+    readonly from: string;
+};
+/** Nuxt's names, from this package's stand-ins: what `#app` exports. */
+export declare const NUXT_STAND_INS: readonly StandIn[];
+/** The vue-router functions a project's code gets without importing them. */
+export declare const ROUTER_STAND_INS: readonly StandIn[];
+/** The module of Nuxt's built-in components. */
+export declare const COMPONENTS_MODULE = "@forgebook/nuxt/app/components";
+/** Nuxt's built-in components, by name: what a template finds without importing them. */
+export declare const BUILT_IN_COMPONENT_NAMES: readonly ["NuxtLink", "ClientOnly", "DevOnly", "NuxtLayout", "NuxtErrorBoundary", "NuxtPage", "NuxtLoadingIndicator", "NuxtRouteAnnouncer", "NuxtImg", "NuxtPicture"];

package/dist/src/vite/standIns.js

@@ -0,0 +1,96 @@
+/**
+ * What a Nuxt project's code gets without importing it, and from where: Nuxt's composables and helpers from this
+ * package's stand-ins (`@forgebook/nuxt/app/…`), Vue's API, and the vue-router functions Nuxt imports for a project.
+ *
+ * @remarks
+ * The table is what `#app` exports, and with the project's own composables what `#imports` exports and what the plugin
+ * imports into a file that uses a name without importing it, as Nuxt does. A Nuxt function not in it is not given: a
+ * file that uses one fails on it by name, which says what a story lacks.
+ *
+ * @module
+ */
+/** This package's stand-ins, by module: the names each exports. */
+const STAND_INS = {
+    "@forgebook/nuxt/app/router": [
+        "useRoute",
+        "useRouter",
+        "navigateTo",
+        "abortNavigation",
+        "defineNuxtRouteMiddleware",
+        "addRouteMiddleware",
+        "definePageMeta",
+        "defineRouteRules",
+        "setPageLayout",
+        "preloadRouteComponents",
+        "preloadComponents",
+        "prefetchComponents",
+        "reloadNuxtApp"
+    ],
+    "@forgebook/nuxt/app/data": [
+        "useAsyncData",
+        "useLazyAsyncData",
+        "refreshNuxtData",
+        "clearNuxtData",
+        "useNuxtData"
+    ],
+    "@forgebook/nuxt/app/fetch": ["useFetch", "useLazyFetch", "$fetch"],
+    "@forgebook/nuxt/app/state": [
+        "useState",
+        "clearNuxtState",
+        "useCookie",
+        "refreshCookie",
+        "useRuntimeConfig",
+        "useAppConfig",
+        "updateAppConfig",
+        "useNuxtApp",
+        "tryUseNuxtApp",
+        "callOnce",
+        "onNuxtReady",
+        "useRequestHeaders",
+        "useRequestHeader",
+        "useRequestEvent",
+        "useRequestFetch",
+        "useRequestURL",
+        "isPrerendered",
+        "useLoadingIndicator"
+    ],
+    "@forgebook/nuxt/app/errors": ["createError", "isNuxtError", "useError", "showError", "clearError"],
+    "@forgebook/nuxt/app/head": [
+        "useHead",
+        "useHeadSafe",
+        "useSeoMeta",
+        "useServerHead",
+        "useServerHeadSafe",
+        "useServerSeoMeta"
+    ],
+    "@forgebook/nuxt/app/define": [
+        "defineNuxtComponent",
+        "defineNuxtPlugin",
+        "definePayloadPlugin",
+        "defineAppConfig"
+    ]
+};
+/** The vue-router functions Nuxt auto-imports besides its own `useRoute` and `useRouter`. */
+const ROUTER_IMPORTS = ["onBeforeRouteLeave", "onBeforeRouteUpdate", "useLink"];
+/** Nuxt's names, from this package's stand-ins: what `#app` exports. */
+export const NUXT_STAND_INS = Object.entries(STAND_INS).flatMap(([from, names]) => names.map((name) => ({ name, from })));
+/** The vue-router functions a project's code gets without importing them. */
+export const ROUTER_STAND_INS = ROUTER_IMPORTS.map((name) => ({
+    name,
+    from: "vue-router"
+}));
+/** The module of Nuxt's built-in components. */
+export const COMPONENTS_MODULE = "@forgebook/nuxt/app/components";
+/** Nuxt's built-in components, by name: what a template finds without importing them. */
+export const BUILT_IN_COMPONENT_NAMES = [
+    "NuxtLink",
+    "ClientOnly",
+    "DevOnly",
+    "NuxtLayout",
+    "NuxtErrorBoundary",
+    "NuxtPage",
+    "NuxtLoadingIndicator",
+    "NuxtRouteAnnouncer",
+    "NuxtImg",
+    "NuxtPicture"
+];

package/package.json

@@ -1,6 +1,121 @@
 {
   "name": "@forgebook/nuxt",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.0",
+  "description": "Forgebook for Nuxt: a Nuxt project's components drawn outside Nuxt, with its auto-imports, its aliases, its router, NuxtLink, useFetch and useAsyncData, useState and its runtime config, on Vite.",
+  "keywords": [
+    "nuxt",
+    "vue",
+    "catalogue",
+    "stories"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ensiria/forgebook.git",
+    "directory": "packages/nuxt"
+  },
+  "type": "module",
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=22.18"
+  },
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/src/stories.d.ts",
+      "default": "./dist/src/stories.js"
+    },
+    "./app/components": {
+      "types": "./dist/src/app/components.d.ts",
+      "default": "./dist/src/app/components.js"
+    },
+    "./app/data": {
+      "types": "./dist/src/app/data.d.ts",
+      "default": "./dist/src/app/data.js"
+    },
+    "./app/define": {
+      "types": "./dist/src/app/define.d.ts",
+      "default": "./dist/src/app/define.js"
+    },
+    "./app/errors": {
+      "types": "./dist/src/app/errors.d.ts",
+      "default": "./dist/src/app/errors.js"
+    },
+    "./app/fetch": {
+      "types": "./dist/src/app/fetch.d.ts",
+      "default": "./dist/src/app/fetch.js"
+    },
+    "./app/head": {
+      "types": "./dist/src/app/head.d.ts",
+      "default": "./dist/src/app/head.js"
+    },
+    "./app/router": {
+      "types": "./dist/src/app/router.d.ts",
+      "default": "./dist/src/app/router.js"
+    },
+    "./app/state": {
+      "types": "./dist/src/app/state.d.ts",
+      "default": "./dist/src/app/state.js"
+    },
+    "./code": {
+      "types": "./dist/src/storyCode.d.ts",
+      "default": "./dist/src/storyCode.js"
+    },
+    "./docs": {
+      "types": "./dist/src/vite/extractDocs.d.ts",
+      "default": "./dist/src/vite/extractDocs.js"
+    },
+    "./project": {
+      "types": "./dist/src/pageProject.d.ts",
+      "default": "./dist/src/pageProject.js"
+    },
+    "./renderer": {
+      "types": "./dist/src/renderer.d.ts",
+      "default": "./dist/src/renderer.js"
+    },
+    "./story": {
+      "types": "./dist/src/storyNuxt.d.ts",
+      "default": "./dist/src/storyNuxt.js"
+    },
+    "./vite": {
+      "types": "./dist/src/vite/nuxt.d.ts",
+      "default": "./dist/src/vite/nuxt.js"
+    }
+  },
+  "dependencies": {
+    "unimport": "7.0.2",
+    "magic-string": "1.4.5",
+    "@forgebook/story-format": "0.2.0",
+    "@forgebook/vue": "0.2.0"
+  },
+  "peerDependencies": {
+    "vite": "^8.0.0",
+    "vue": "^3.5.0",
+    "vue-router": "^4.5.0 || ^5.0.0",
+    "forgebook": "^0.2.0"
+  },
+  "devDependencies": {
+    "@types/node": "24.19.2",
+    "@vitejs/plugin-vue": "6.0.10",
+    "happy-dom": "21.0.4",
+    "vite": "8.3.5",
+    "vitest": "5.0.5",
+    "vue": "3.5.44",
+    "vue-router": "5.4.0",
+    "@forgebook/tools": "0.0.0",
+    "@forgebook/testing": "0.2.0",
+    "forgebook": "0.2.0",
+    "@forgebook/typescript-config": "0.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "package-build build",
+    "manifest": "package-build manifest",
+    "test": "vitest run",
+    "typecheck": "tsc -p src && tsc -p src/vite && tsc -p test"
+  }
 }