znode-plugin 0.1.6 → 0.1.8

package/README.md

@@ -217,9 +217,113 @@ export default function setup(host: IBrowserHost): IBrowserPlugin {
 }
 ```
 
-**Slots:** `layout.header`, `layout.footer`, `header.search`, `product.card`, `product.image`, `product.variants`,
-`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`.
+**Which slots are there?** Ask the store you are linked to; the list is read from its source, so it is always current:
+
+```bash
+npx znode slot list            # every slot
+npx znode slots product        # only the ones matching "product"
+```
+
+```
+  Slot                Side     Hands over  Store component   Eject             In this package
+  ------------------  -------  ----------  ----------------  ----------------  ---------------
+  product.basicInfo   browser  yes         ProductBasicInfo  ProductBasicInfo  yes
+  product.card        browser  yes         ProductCard       ProductCard
+  product.layout      browser  no          ProductBasicInfo  -
+  layout.root         server   yes         app/layout        -                 yes
+  ...
+```
+
+- **Side**: `browser` slots go in `src/browser.tsx` (`slots`), `server` slots in `src/server.tsx` (`serverSlots`).
+- **Hands over**: `yes` = your component gets the store's rendering as `children` (keep, wrap or replace it); `no` = it
+  adds or lays out (e.g. `product.layout` moves the store's parts into your structure).
+- **Eject**: the store component you can copy into your package (next section). **In this package**: you already fill it.
+
+### Take over a whole store component (eject)
+
+When a slot is not enough and you want to change the component itself (its markup, its logic), copy it into your
+package. The store then renders your copy in its place; everything else stays the store's.
+
+```bash
+npx znode eject ProductBasicInfo      # or by its slot: npx znode eject product.basicInfo
+```
+
+It copies the store's file to `src/components/ProductBasicInfo.tsx` (imports turned into the store's `@znode/...`
+aliases), registers it in `src/browser.tsx` under its slot, and prints any npm package the copy needs
+(`npm install zustand@4.5.5`). Edit the copy, then `npm run build` and `npm run dev`. The copy is yours: store fixes to
+the component no longer reach it, so compare it with the store's file after a store upgrade. `npx znode eject` with no
+name lists what can be ejected.
+
+**The component has no slot yet?** `eject` offers to create one in the **base store** (the store you linked), then ejects:
+
+```
+$ npx znode eject ProductDetailsPage
+ProductDetailsPage has no slot yet, so it cannot be ejected.
+Create a slot for ProductDetailsPage in the base store now? [y/N] y
+Slot name (area.name) [product.detailsPage]: product.details
+creating slot "product.details" around ProductDetailsPage (packages/base-components/src/...) ...
+ejected ProductDetailsPage -> src/components/ProductDetailsPage.tsx
+registered "product.details": EjectedProductDetailsPage in src/browser.tsx
+```
+
+Creating a slot edits the base store's **source** (a `Runtime<Component>` wrapper in
+`packages/extensions/src/slots/RuntimeCreatedSlots.tsx`, the component's export wrapped with `withRuntimeWrapper`, the
+slot added to the store's slot list and docs). It never touches `.next` and commits nothing. Before the store renders
+your copy: review the diff in the store repo (`git diff`), commit it there through the store's own flow (it changes base
+components, so it is reviewed like any base change), and rebuild / restart the webstore.
+
+- In a script or CI (no questions): `npx znode eject ProductDetailsPage --slot product.details`.
+- Only the slot, no copy: `npx znode create-slot ProductDetailsPage product.details`; add `--dry-run` first to see
+  exactly which store files and lines it would change, without writing anything.
+- A server **component** inside base-components cannot get a slot (a browser slot is filled in the browser): it refuses
+  an `async` component or one that imports `server-only` / `next/headers` / `fs`, and says to use a client component it
+  renders instead, e.g. `ProductDetails` is a server component, so take over `ProductBasicInfo` or `ProductDetailsPage`.
+
+### Take over a whole store page
+
+A store **page** (a route, `apps/webstore/src/app/**/page.tsx`) runs on the server, so it gets a **server slot** around
+its content. Use the page's component name (its `export default function <Name>`):
+
+```
+$ npx znode eject ForgotPasswordPage
+ForgotPasswordPage has no slot yet, so it cannot be ejected.
+Create a slot for ForgotPasswordPage in the base store now? [y/N] y
+Slot name (area.name) [forgotPassword.page]:
+creating slot "forgotPassword.page" around ForgotPasswordPage (apps/webstore/src/app/[locale]/forgot-password/page.tsx) ...
+ejected ForgotPasswordPage (server slot "forgotPassword.page") -> src/server/pages/ForgotPasswordPage.tsx
+registered "forgotPassword.page": EjectedForgotPasswordPage in src/server.tsx (serverSlots)
+```
+
+In the store, the page's content is wrapped (inside its `NextIntlClientProvider`, so the page's texts still reach it):
+
+```tsx
+<NextIntlClientProvider messages={...}>
+  <RuntimeServerSlot name="forgotPassword.page">
+    <ForgotPassword />
+  </RuntimeServerSlot>
+</NextIntlClientProvider>
+```
+
+In your package you get a server component to build the page in. `children` is the store's page content:
+
+```tsx
+// src/server/pages/ForgotPasswordPage.tsx
+export async function ForgotPasswordPage(props: { children?: ReactNode }, context: IServerSlotContext) {
+  return (
+    <div className="my-forgot-page">
+      <h1>Reset your password</h1>
+      <aside>Help text, images, data fetched here (async is fine)</aside>
+      {props.children /* the store's form; leave it out to render a page of your own */}
+    </div>
+  );
+}
+```
+
+- It is not a copy of the route: the route's server code (agents, `getResourceMessages`, data) stays the store's. Your
+  component runs on the server only (async, no hooks): put interactive parts in a browser slot, e.g. change the form
+  itself with `npx znode eject ForgotPassword` (slot `account.forgotPassword`).
+- A page that already has a server slot (`login.page`, `layout.root`) is ejected straight away (`npx znode eject LoginPage`).
+- Only the slot: `npx znode create-slot ForgotPasswordPage forgotPassword.page` (`--dry-run` to preview).
 
 ### Add a page-builder widget
 
@@ -291,9 +395,10 @@ 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 slot list [<filter>] [--json]` | every slot the linked store renders, read from its source: browser or server side, whether it hands over what the store renders there (children: keep, wrap or replace it) or only adds / lays out, the store component it is around, what `eject` can copy into it, and whether this package already fills it. `npx znode slots` is the same; a filter matches slot or component names (`npx znode slots product`) |
 | | `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 |
+| | `npx znode create-slot <Component> <area.name> [--dry-run] [--file <store file>]` | create a slot around a store component that has none, in the **base store's source** (the linked store, not the theme, never `.next`): a `Runtime<Component>` wrapper in `packages/extensions/src/slots/RuntimeCreatedSlots.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 inside base-components (`async`, server-only imports): a browser slot is filled in the browser. For a **route page** (`<Component>` is its `export default function`, e.g. `ForgotPasswordPage`) it puts a **server slot** (`<RuntimeServerSlot>`) around the page's content instead, filled in `src/server.tsx` (`serverSlots`). Nothing is committed: review the diff in the store, commit it there, rebuild the webstore, then `npx znode eject <Component>`. `create slot` (with a space) works too; `add-slot` (0.1.6) still works |
+| | `npx znode eject <Name> [--force] [--slot <area.name>] [--yes]` | `<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. **No slot yet?** It asks whether to create one in the base store and for its name (suggested from the component, e.g. `ProductDetailsPage` → `product.detailsPage`), does what `create-slot` does, then ejects. `--slot <area.name>` creates it without asking (for scripts / CI); `--yes` skips the confirm only |
 
 The plugin folder is taken from: the command's argument, else the `RUNTIME_PLUGINS_DIR` environment variable, else
 `znode.local.json`.
@@ -371,6 +476,10 @@ folder after an upgrade; delete them by hand if you need the space.
 | `installed …` but still no change | the package went to another plugin folder than the running webstore reads: compare `znode.local.json` with the webstore's `RUNTIME_PLUGINS_DIR` (`apps/webstore/.env.local` or `.env`) |
 | `MISSING_MESSAGE` for your label | put browser labels under a namespace the page sends, e.g. `Common` |
 | Theme shows for you but not shoppers | expected: enable it in `plugins.json` (step 7) |
+| `<Name> cannot be ejected` | run it in a terminal and answer `y` to create the slot, or `npx znode eject <Name> --slot <area.name>`; `npx znode slot list` shows what exists |
+| `<Name> is an async server component` | a component inside base-components cannot get a slot: eject a client component it renders instead, or the route page it is on (`npx znode eject <Name>Page`) |
+| `no <Name> found` | use the component's name, or for a page its `export default function <Name>` (e.g. `ForgotPasswordPage`, not the URL); `npx znode slot list` shows what exists |
+| Ejected / new slot but the store still shows its own | the slot was created in the store's source: commit it there and rebuild / restart the webstore; check `npx znode slot list` shows it with **In this package** `yes` |
 
 ---