znode-plugin 0.1.4 → 0.1.6

package/README.md

@@ -218,7 +218,7 @@ export default function setup(host: IBrowserHost): IBrowserPlugin {
 ```
 
 **Slots:** `layout.header`, `layout.footer`, `header.search`, `product.card`, `product.image`, `product.variants`,
-`product.addToCart`, `product.layout`, `productList.layout`, `addToCart.notification`, `login.form`,
+`product.addToCart`, `product.layout`, `product.basicInfo`, `productList.layout`, `addToCart.notification`, `login.form`,
 `checkout.address`, `checkout.shippingOptions`. Server slots (in `server.tsx`): `layout.root`, `login.layout`, `login.page`.
 
 ### Add a page-builder widget
@@ -291,6 +291,9 @@ Run them with `npm run <name>` inside a project (the scripts call `znode … .`)
 | `npm run link-store -- <store repo>` | `znode link-store <repo> .` | connect the store's types |
 | | `npx znode install <zip> [pluginsDir]` | install a released zip into a store's plugin folder |
 | | `npx znode create <theme\|plugin\|widget\|content> <name>` | a minimal starter of another kind |
+| | `npx znode eject` | list the store components a package can take over (each has a slot that hands the component over) |
+| | `npx znode add-slot <Component> <area.name> [--dry-run] [--file <store file>]` | add a slot around a store component that has none, in the **linked store's source** (not the theme, never `.next`): a `Runtime<Component>` wrapper in `packages/extensions/src/slots/RuntimeAddedSlots.tsx`, the component's export wrapped with `withRuntimeWrapper`, the slot added to the store's slot list and docs, the module registry regenerated. Refuses server components (`async`, server-only imports): a slot is filled in the browser. Nothing is committed: review the diff in the store, commit it there, rebuild the webstore, then `npx znode eject <Component>`. `add slot` (with a space) works too |
+| | `npx znode eject <Name> [--force]` | `<Name>` is the component or its slot (`ProductBasicInfo` or `product.basicInfo`). Copy the store's component into `src/components/<Name>.tsx` (imports turned into store aliases, runtime wrapper removed) and register it in `src/browser.tsx` under its slot; prints any npm package the copy needs. The copy is yours: store fixes no longer reach it |
 
 The plugin folder is taken from: the command's argument, else the `RUNTIME_PLUGINS_DIR` environment variable, else
 `znode.local.json`.

package/lib/next-imports.mjs

@@ -56,36 +56,88 @@ const MODULES = {
 // the server-only functions a browser part may not need, and the hooks a server part cannot call, stay importable:
 // the store's module for that side decides (a hook in a server part fails as it would in a Next.js server component)
 
-// The store's own modules a browser part may import by the store's path, so a theme's own component (a copy of the
-// store's, say) keeps the store's imports instead of re-creating them: relative paths become "@znode/..." paths (the
-// store publishes them: packages/extensions/src/client/store-modules.ts; keep the two lists the same). Types for
-// package authors: sdk/store-modules.d.ts. Kinds: component (rendered by the store's React), function, object (its
-// properties read when used, its methods bound to it).
-const STORE_MODULES = {
-  lodash: { debounce: "function" },
-  "next-intl": { useTranslations: "function" },
-  "@znode/logger": { logClient: "object" },
-  "@znode/logger/server": { AREA: "object" },
-  "@znode/constants/settings": { SETTINGS: "object" },
-  "@znode/constants/user-activity-event": { USER_ACTIVITY_EVENT: "object" },
-  "@znode/utils/common": { getValidatedRedirectPath: "function" },
-  "@znode/base-components/components/common/icons": { LoadingSpinner: "component", SearchIcon: "component", ZIcons: "component" },
-  "@znode/base-components/components/common/button/Button": { default: "component" },
-  "@znode/base-components/components/common/input/Input": { default: "component" },
-  "@znode/base-components/components/common/image": { CustomImage: "component" },
-  "@znode/base-components/http-request": {
-    getHydratedSuggestionSearch: "function",
-    getHydratedTypeaheadSearchContent: "function",
-    getSearchRedirectURL: "function",
-    userActivityLog: "function",
-  },
-  "@znode/base-components/components/layout-components/header/barcode-scanner/BarcodeScanner": { BarcodeScanner: "component" },
-  "@znode/base-components/components/layout-components/header/search/Search": { DynamicVoiceSearch: "component" },
-  "@znode/base-components/components/layout-components/header/search-box": { SearchBox: "component" },
-  "@znode/base-components/components/layout-components/header/search-box/TypeaheadSearch": { TypeaheadSearch: "component" },
-  "@znode/base-components/components/layout-components/header/search-box/HydratedSearchList": { HydratedSearchList: "component" },
-};
-Object.assign(MODULES, STORE_MODULES);
+// The store's own modules a browser part may import by the store's path (Generated Store Module Registry): any
+// @znode/... import the package's tsconfig.store.json resolves to a store file the store's registry has (its
+// packages/extensions/store-module-registry.json, generated by scripts/gen-store-module-registry.mjs from the store's
+// source: its client modules), and the npm packages the store shares (lodash, next-intl). Each becomes a stand-in that
+// reads the store's module, which the store loads before the package's bundle (the build lists the keys in the
+// package's znode-package.json as storeImports). No list here: what the store has is what a package can use.
+const SHARED_PACKAGES = new Set(["lodash", "next-intl"]);
+const STORE = "store:";
+
+const STORE_FILE = "\0znode-store-file:";
+const asFile = (base) =>
+  [base, `${base}.ts`, `${base}.tsx`, path.join(base, "index.ts"), path.join(base, "index.tsx")].find((file) => fs.existsSync(file) && fs.statSync(file).isFile());
+const keyOfFile = (file, store) => path.relative(store.root, file).split(path.sep).join("/").replace(/\.(tsx?|jsx?)$/, "").replace(/\/index$/, "");
+
+// an import, with the package's tsconfig.store.json paths (or relative to a store file), to the store's file
+function storeFile(source, store, from) {
+  if (from && source.startsWith(".")) return asFile(path.resolve(path.dirname(from), source));
+  for (const [alias, [target]] of Object.entries(store.paths)) {
+    if (alias.endsWith("/*")) {
+      const prefix = alias.slice(0, -1);
+      if (source.startsWith(prefix)) return asFile(path.join(store.root, target.replace("*", source.slice(prefix.length))));
+    } else if (source === alias) return asFile(path.join(store.root, target));
+  }
+  return null;
+}
+
+// that file's registry key (its path from the store root without extension or /index, as the store's generator writes it)
+function storeKey(source, store) {
+  if (SHARED_PACKAGES.has(source)) return source;
+  const file = storeFile(source, store);
+  return file ? keyOfFile(file, store) : null;
+}
+
+// the store file that defines an exported name, following the barrels (export * from, export { a as b } from): a
+// theme's import { CustomImage } from ".../common/image" is loaded from common/image/CustomImage.tsx alone, not the whole
+// barrel, whose other files may be server-only (the store's own bundler drops those for a static named import)
+function definingFile(file, name, store, seen = new Set()) {
+  if (!file || seen.has(`${file}#${name}`)) return null;
+  seen.add(`${file}#${name}`);
+  const source = fs.readFileSync(file, "utf8");
+  const escaped = name.replace(/\$/g, "\\$");
+  if (name === "default" ? /export\s+default\b/.test(source) : new RegExp(`export\\s+(?:declare\\s+)?(?:async\\s+)?(?:const|let|var|function\\*?|class|enum)\\s+${escaped}\\b`).test(source)) return file;
+  for (const match of source.matchAll(/export\s*\{([^}]*)\}\s*(?:from\s*["']([^"']+)["'])?/g)) {
+    for (const part of match[1].split(",").map((item) => item.trim()).filter(Boolean)) {
+      const [inner, outer = inner] = part.replace(/^type\s+/, "").split(/\s+as\s+/).map((item) => item.trim());
+      if (outer !== name) continue;
+      return match[2] ? definingFile(storeFile(match[2], store, file), inner, store, seen) : file;
+    }
+  }
+  for (const match of source.matchAll(/export\s*\*\s*from\s*["']([^"']+)["']/g)) {
+    const found = definingFile(storeFile(match[1], store, file), name, store, seen);
+    if (found) return found;
+  }
+  return null;
+}
+
+// a package module's named imports from the store, split by the store file that defines each name
+function splitStoreImports(code, store) {
+  return code.replace(/import\s*\{([^}]*)\}\s*from\s*["'](@znode\/[^"']+)["'];?/g, (whole, names, source) => {
+    const barrel = storeFile(source, store);
+    if (!barrel) return whole;
+    const byFile = new Map();
+    for (const part of names.split(",").map((item) => item.trim()).filter(Boolean)) {
+      const [name] = part.split(/\s+as\s+/).map((item) => item.trim());
+      const file = definingFile(barrel, name, store) || barrel;
+      if (!byFile.has(file)) byFile.set(file, []);
+      byFile.get(file).push(part);
+    }
+    return [...byFile].map(([file, parts]) => `import { ${parts.join(", ")} } from ${JSON.stringify(STORE_FILE + keyOfFile(file, store))};`).join("\n");
+  });
+}
+
+// the stand-in for a store module: the store's module itself (loaded before the bundle), its names as rollup's
+// synthetic named exports; a name missing on the module is read from its default (an npm CommonJS package)
+function storeStandIn(key) {
+  return [
+    `const loaded = (globalThis.__znodeNextClient || {})[${JSON.stringify(key)}];`,
+    `if (!loaded) throw new Error(${JSON.stringify(`"${key}" was not loaded by the store: the package needs a store with the Generated Store Module Registry`)});`,
+    `export const __store = new Proxy(loaded, { get: (module, name) => (name in module ? module[name] : module.default?.[name]) });`,
+    `export default loaded.default;`,
+  ].join("\n");
+}
 
 // react's values, the same in every React 19 build and never read from the store at load
 const VALUES = {
@@ -267,30 +319,42 @@ async function transformFonts(code, id, context) {
  * The rollup plugin. part: "server" | "browser"; prefix: "<name>-<version>"; outDir: dist; fonts: collects what
  * next/font/google built (files, css), which the build adds to the package's assets and stylesheet.
  */
-export function znodeNext({ part, prefix, outDir, fonts }) {
+export function znodeNext({ part, prefix, outDir, fonts, store, storeImports = [] }) {
   return {
     name: "znode-next",
     resolveId(source) {
-      if (STORE_MODULES[source] && part === "server") {
-        this.error(`"${source}" is a store module for browser parts (src/browser.tsx), not server parts`);
-      }
       if (MODULES[source]) return VIRTUAL + source;
+      if (SHARED_PACKAGES.has(source) || source.startsWith("@znode/") || source.startsWith(STORE_FILE)) {
+        if (part === "server") this.error(`"${source}" is a store module for browser parts (src/browser.tsx), not server parts`);
+        if (!store) this.error(`"${source}" is a store module: connect the store first (npm run link-store -- <store repo>), which writes tsconfig.store.json`);
+        if (!store.registry) this.error(`"${source}": the store at ${store.root} has no packages/extensions/store-module-registry.json (run node scripts/gen-store-module-registry.mjs there, or update the store)`);
+        // a named import was split to the file that defines it (transform); a default or namespace import is the module
+        const key = source.startsWith(STORE_FILE) ? source.slice(STORE_FILE.length) : storeKey(source, store);
+        if (!key) this.error(`"${source}" is not a store module (no file for it under the store's tsconfig paths)`);
+        if (!store.registry.has(key)) {
+          this.error(`"${source}" (${key}) is not in the store's module registry: it is server-only, or the store's registry is older than this file (regenerate it: node scripts/gen-store-module-registry.mjs in the store repo)`);
+        }
+        if (!storeImports.includes(key)) storeImports.push(key);
+        return VIRTUAL + STORE + key;
+      }
       if (source === FONT_MODULE) return null;
       if (source === "next" || source.startsWith("next/")) {
-        this.error(`"${source}" is not available to packages. Supported: ${[...Object.keys(MODULES), FONT_MODULE].filter((id) => !STORE_MODULES[id]).join(", ")}`);
-      }
-      if (source.startsWith("@znode/")) {
-        this.error(`"${source}" is not available to packages. Store components a package can import: ${Object.keys(STORE_MODULES).join(", ")}`);
+        this.error(`"${source}" is not available to packages. Supported: ${[...Object.keys(MODULES), FONT_MODULE].join(", ")}`);
       }
       return null;
     },
     load(id) {
-      return id.startsWith(VIRTUAL) ? standIn(id.slice(VIRTUAL.length), part) : null;
+      if (!id.startsWith(VIRTUAL)) return null;
+      const name = id.slice(VIRTUAL.length);
+      if (name.startsWith(STORE)) return { code: storeStandIn(name.slice(STORE.length)), syntheticNamedExports: "__store" };
+      return standIn(name, part);
     },
     async transform(code, id) {
       if (id.startsWith(VIRTUAL)) return null;
-      const output = await transformFonts(code, id, { prefix, outDir, fonts });
-      return output === null ? null : { code: output, map: null };
+      const split = part === "browser" && store && /from\s*["']@znode\//.test(code) ? splitStoreImports(code, store) : code;
+      const output = await transformFonts(split, id, { prefix, outDir, fonts });
+      if (output === null) return split === code ? null : { code: split, map: null };
+      return { code: output, map: null };
     },
   };
 }