@mercurjs/docs 2.2.0-rc.0 → 2.2.0-rc.2

package/content/resources/customization/extending-panels.mdx

@@ -1,32 +1,43 @@
 ---
 title: "Extending Panels"
-description: "Add pages, customize navigation, branding, and replace components in the admin and vendor panels."
+description: "Add pages, inject widgets, customize navigation, and extend forms and tables in the admin and vendor panels."
 ---
 
-Both the admin panel and vendor portal use the same SDK (`@mercurjs/dashboard-sdk`). Customization is file-based and convention-driven — you add pages by creating files, configure navigation through exports, and override components through config.
+Both the admin panel and vendor portal use the same SDK (`@mercurjs/dashboard-sdk`). Customization is **file-based and convention-driven** — you add pages, widgets, and field extensions by dropping files under `src/`, and configure navigation through a single file. Nothing is registered by hand; the SDK crawls your `src/` at build time and wires everything in.
 
 <Info>
-  **Mercur does not use Medusa's admin customization.** If you're coming from Medusa, forget `defineWidgetConfig`, `defineRouteConfig`, and widget injection zones — none of them exist here. Mercur ships its own admin **and** vendor panels, built on a shared extension framework with three mechanisms: **drop-in routes** (file-based pages that can also *replace* built-in pages), **compound-component re-composition** (every built-in page exposes its parts as slots), and **named layout overrides** (sidebar, topbar, store setup). The trade: instead of injecting widgets into fixed zones around a page Medusa controls, you compose the actual page — which is what makes a two-panel marketplace customizable without forking.
+  **Coming from Medusa?** The extension model is deliberately Medusa-shaped. The helpers you know — `defineWidgetConfig`, `defineRouteConfig`, `defineCustomFieldsConfig`, `createFormHelper` — all exist here, re-exported from `@mercurjs/dashboard-sdk` (without Medusa's `unstable_` prefix). What's different: Mercur ships **two** panels (admin *and* vendor) from one framework, so a file only ever targets the panel it lives in (there is no `surface` field), and widget zones carry a `before | after` placement suffix on the zone id. Everything is additive by default — your contribution augments the built-in page instead of replacing it.
 </Info>
 
-## Choosing your extension mechanism
+## The extension mechanisms
 
-Junior-friendly rule of thumb: **adding something new? Drop in a route. Changing something that exists? Re-compose it. Changing the frame around every page? Override a component. Sharing it across projects? Make it a block.**
+Every panel customization is **additive** — you augment a built-in page without owning it. One concern per file, discovered by the build-time crawl:
 
-| You want to… | Use | Why it's the right tool |
-|--------------|-----|------------------------|
-| Add a new screen or feature | A drop-in `page.tsx` route | New URL, auto-registered, sidebar entry via the `config` export — see [Add a page](#add-a-page) |
-| Change part of an existing page | A drop-in route **at the same path**, re-composing the page's compound slots | Your route replaces the built-in one; untouched slots keep all their behavior — see the [re-compose tutorial](/rc/resources/tutorials/recompose-a-page) |
-| Change global chrome (sidebar, topbar, store setup) | A component override in the plugin config | One component, applied everywhere its slot renders — see [Replace components](#replace-components) |
-| Reuse a feature across projects | A [block](/rc/learn/blocks) | Ships API + admin + vendor files installable with `mercurjs add` — see the [build-a-block tutorial](/rc/resources/tutorials/build-a-block) |
+- **Widgets** — inject a React component at a named zone on a built-in page (`defineWidgetConfig`).
+- **Navigation** — reorder, hide, relabel, or re-parent built-in sidebar items (`defineNavigationConfig`).
+- **Custom fields** — add validated fields to built-in forms, replace/remove/add fields in detail sections, and add columns to list tables (`defineCustomFieldsConfig` + `createFormHelper`).
+- **Pages** — add a brand-new screen with a drop-in `page.tsx` route.
 
 <Note>
-  The middle row is the one Medusa developers miss most. Because built-in pages are exported as compound components (e.g. `ProductListPage` from `@mercurjs/vendor/pages` with `Header`, `HeaderActions`, `DataTable` slots), "customize the products page" doesn't mean forking it — it means rendering it with your own composition and reusing the slots you don't change.
+  Additive tools leave the rest of the built-in page — data fetching, filters, pagination, i18n — completely intact. A widget, a nav override, or a custom field changes only the spot you target.
 </Note>
 
+## Choosing your extension mechanism
+
+Rule of thumb: **injecting UI into an existing page? Use a widget. Adding data to a form or section? Use a custom field. Reshaping the sidebar? Use the navigation file. Adding a whole new screen? Drop in a route.**
+
+| You want to… | Use | Why it's the right tool |
+|--------------|-----|------------------------|
+| Show a banner, panel, or CTA on a built-in page | A **widget** (`defineWidgetConfig`) | Renders at a named zone; the rest of the page is untouched — see [Add a widget](/rc/resources/tutorials/add-a-widget) |
+| Add a field to a built-in form, or add/replace/remove a field in a detail section | A **custom field** (`defineCustomFieldsConfig`) | Validated field wired into the existing form/section — see [Extend forms and tables](/rc/resources/tutorials/extend-forms-and-tables) |
+| Add or override a column on a built-in list table | The `list` block of a **custom field** file | Model-scoped column extension — see [Extend forms and tables](/rc/resources/tutorials/extend-forms-and-tables) |
+| Reorder / hide / relabel / re-parent sidebar items | The **navigation** file (`defineNavigationConfig`) | One host-owned `_navigation.ts` — see [Customize navigation](/rc/resources/tutorials/customize-navigation) |
+| Add a new screen or feature | A drop-in `page.tsx` route | New URL, auto-registered, sidebar entry via `config` — see [Add a page](/rc/resources/tutorials/custom-panel-page) |
+| Reuse a feature across projects | A [block](/rc/learn/blocks) | Ships API + admin + vendor files installable with `mercurjs add` |
+
 ## Set up
 
-All configuration lives in the panel app's Vite config — there is no separate config file.
+All configuration lives in the panel app's Vite config — there is no separate `mercur.config.ts`.
 
 <Steps>
   <Step title="Register the plugin">
@@ -54,8 +65,17 @@ All configuration lives in the panel app's Vite config — there is no separate
   <Step title="Pass environment values explicitly">
     The plugin doesn't read `.env` itself — load environment variables in `vite.config.ts` (e.g. with Vite's `loadEnv`) and pass them into the plugin options, as the starter template does with `backendUrl`.
   </Step>
+  <Step title="Register typed extension targets (once per panel)">
+    Widgets, navigation, and custom fields target **typed ids** (zone ids, nav item ids, model field ids) that each panel package generates from its own built-in pages and ships as `@mercurjs/{admin,vendor}/extension-targets`. Register them once so the ids resolve in every extension file, with a single ambient reference in your app's `src`:
+
+    ```typescript apps/vendor/src/extension-targets.d.ts
+    /// <reference types="@mercurjs/vendor/extension-targets" />
+    ```
+
+    (For the admin app, reference `@mercurjs/admin/extension-targets`.) With this file present, a typo in a zone, model, field, or nav id fails `tsc` instead of silently doing nothing at runtime. `create-mercur-app` ships this file already.
+  </Step>
   <Step title="Restart after config changes">
-    Options are applied at build time through virtual modules. Adding or removing routes hot-reloads automatically, but changes to the plugin options require a dev-server restart.
+    Options are applied at build time through virtual modules. Adding or removing routes, widgets, and custom-field files hot-reloads automatically, but changes to the plugin options (in `vite.config.ts`) require a dev-server restart.
   </Step>
 </Steps>
 
@@ -68,11 +88,127 @@ All configuration lives in the panel app's Vite config — there is no separate
 | `vendorUrl` | `string` | Absolute vendor portal URL including its path prefix |
 | `name` | `string` | Application name shown in the sidebar |
 | `logo` | `string` | URL to a logo image |
-| `components` | `object` | Component overrides (see [Replace components](#replace-components)) |
 | `i18n` | `object` | Internationalization settings (`{ defaultLanguage }`) |
 | `enableSellerRegistration` | `boolean` | Enable the public seller registration flow (vendor portal) |
 | `imageLimit` | `number` | Max upload size for images in bytes (default: 2 MB) |
 
+## Widgets
+
+Inject a React component at a named zone on a built-in page. Drop a file under `src/widgets/`, export the component as the default and a `config` built with `defineWidgetConfig`:
+
+```tsx src/widgets/product-list-banner.tsx
+import { defineWidgetConfig } from "@mercurjs/dashboard-sdk"
+import { Container, Text } from "@medusajs/ui"
+
+export const config = defineWidgetConfig({
+  zone: "product.list.before",
+})
+
+export default function ProductListBanner() {
+  return (
+    <Container className="mb-2">
+      <Text size="small" className="text-ui-fg-subtle">
+        Tip: bulk-import products from the Products menu.
+      </Text>
+    </Container>
+  )
+}
+```
+
+The zone id is `<domain>.<view>.<placement>`. The placement is the last segment:
+
+- `before` / `after` — stack your widget before or after the built-in content (multiple widgets stack in registration order).
+
+Zones mounted today (**vendor portal**):
+
+| Zone id | Where it renders |
+|---------|------------------|
+| `product.list.before` / `.after` | Vendor product list page |
+| `login.logo.*` / `login.before.*` / `login.after.*` | The public login screen (rendered before authentication) |
+
+The full set of valid zones is typed as `WidgetZoneId` and generated into each panel's `extension-targets.d.ts` — your editor autocompletes them, and an unknown zone fails `tsc`. Walk through it end to end in [Add a widget](/rc/resources/tutorials/add-a-widget).
+
+## Navigation
+
+Custom drop-in routes place their own sidebar item via `defineRouteConfig` (see [Add a page](#add-a-page)). To reshape the **built-in** sidebar items, author a single host-owned file, `src/_navigation.ts`:
+
+```ts src/_navigation.ts
+import { defineNavigationConfig } from "@mercurjs/dashboard-sdk"
+
+export default defineNavigationConfig({
+  items: [
+    { id: "orders", rank: 0 },              // pin to the top
+    { id: "price-lists", hidden: true },    // hide a built-in item
+    { id: "payouts", label: "Settlements" }, // relabel
+    { id: "campaigns", nested: "orders" },   // re-parent under Orders
+    { id: "categories", nested: null, rank: 1 }, // promote a nested item to top level
+  ],
+})
+```
+
+- `id` targets any built-in item — top-level routes *or* nested children — by its stable id, typed as `NavItemId`.
+- `rank` orders an item within its parent; `hidden` removes it from the sidebar; `label` / `icon` relabel it; `nested` re-parents it (`nested: null` promotes to top level, typed against `NavParentId`).
+- Navigation is a **single host-owned file** — installed blocks cannot reorder the sidebar, so it stays one source of truth. It does not change custom routes, which still place themselves via `defineRouteConfig`.
+
+Walk through it in [Customize navigation](/rc/resources/tutorials/customize-navigation).
+
+## Custom fields
+
+Add validated fields to a model's built-in create/edit forms, replace/remove/add fields in its detail sections, and add columns to its list table — all from one model-scoped file. Drop `src/custom-fields/<model>.tsx` and default-export a `defineCustomFieldsConfig`:
+
+```tsx src/custom-fields/product.tsx
+import { defineCustomFieldsConfig } from "@mercurjs/dashboard-sdk"
+import { createFormHelper } from "@mercurjs/dashboard-shared"
+import { Text } from "@medusajs/ui"
+
+const form = createFormHelper<{ metadata?: Record<string, unknown> }>()
+
+export default defineCustomFieldsConfig({
+  model: "product",
+  forms: [
+    {
+      zone: "edit",
+      fields: {
+        erp_id: form.define({
+          validation: form.string().optional(), // Zod → input type + validation
+          label: "ERP ID",
+          description: "External system identifier",
+          placeholder: "ERP-000",
+        }),
+      },
+    },
+  ],
+  displays: [
+    {
+      zone: "general",
+      fields: [
+        { id: "erp_id", component: ({ data }) => <Text className="px-6 py-4">ERP: {String(data.metadata?.erp_id ?? "-")}</Text> }, // ADD
+        { id: "subtitle", component: null },  // REMOVE a built-in field
+        { id: "handle", component: BrandedHandle }, // REPLACE a built-in field's render
+      ],
+    },
+  ],
+  list: {
+    columns: [{ id: "erp_id", header: "ERP", component: ({ row }) => String(row.metadata?.erp_id ?? "-") }],
+    viewDefaults: {
+      columnVisibility: { collection: false }, // hide a built-in column
+      columnOrder: ["product", "erp_id", "status"],
+    },
+  },
+})
+```
+
+- `forms[]` adds validated fields to a form `zone` (`create` / `edit` / `organize` / …). Input type and validation come from a Zod schema via `createFormHelper`; fields render through the standard `Form.Field` chain and participate in the existing submit + validation flow.
+- `displays[]` targets detail-page sections: keyed by field `id`, an entry **adds** a read-only row (unknown id), **replaces** a built-in field's render (matching id + `component`), or **removes** it (matching id + `component: null`).
+- `list` extends the model's list table: add/override columns by id, hide via `viewDefaults.columnVisibility`, reorder via `viewDefaults.columnOrder`.
+- Everything is typed against the panel-generated `CustomFieldsRegistry` — valid `model`, `zone`, and built-in field ids autocomplete; an invalid target fails `tsc`.
+
+<Warning>
+  **Panel custom fields vs. the Custom Fields module.** `defineCustomFieldsConfig` (this section) is a **UI** surface — it renders, validates, and displays fields in the panels. It does not create database columns. To *store* extra data on an entity, use the backend [Custom Fields module](/rc/resources/customization/custom-fields), or wire your own API route/workflow. In the MVP, panel custom fields for `product` are submitted under `additional_data` and persisted onto the product's `metadata`.
+</Warning>
+
+Full walkthrough (forms, sections, list columns): [Extend forms and tables](/rc/resources/tutorials/extend-forms-and-tables).
+
 ## Add a page
 
 <Steps>
@@ -114,7 +250,7 @@ All configuration lives in the panel app's Vite config — there is no separate
 </Steps>
 
 <Info>
-  **Matching paths replace, new paths append.** If your route's path matches a built-in page (e.g. `src/routes/products/page.tsx` → `/products`), your page **replaces** the built-in one — that's the override mechanism, no registration needed. Any other path is added alongside the built-in routes. Delete the file and the built-in page returns.
+  **Matching paths replace, new paths append.** If your route's path matches a built-in page (e.g. `src/routes/products/page.tsx` → `/products`), your page **replaces** the built-in one. Any other path is added alongside the built-in routes. Delete the file and the built-in page returns. To change *part* of a built-in page without owning it, prefer a widget or a custom field.
 </Info>
 
 ### Routing conventions
@@ -131,43 +267,6 @@ File paths map to URL routes automatically:
 | `src/routes/(settings)/page.tsx` | Route grouping | Groups routes without adding a URL segment |
 | `src/routes/dashboard/@sidebar/page.tsx` | Parallel route | Renders alongside parent |
 
-## Navigation
-
-Sidebar items are generated from pages that export a `config` with a `label`.
-
-### Ordering
-
-Use `rank` to control the order. Lower values appear higher:
-
-```tsx
-// src/routes/orders/page.tsx
-export const config: RouteConfig = {
-  label: "Orders",
-  icon: ShoppingCart,
-  rank: 1,
-}
-
-// src/routes/products/page.tsx
-export const config: RouteConfig = {
-  label: "Products",
-  icon: Tag,
-  rank: 2,
-}
-```
-
-### Nested menus
-
-Use `nested` to group pages under a parent:
-
-```tsx src/routes/settings/shipping/page.tsx
-export const config: RouteConfig = {
-  label: "Shipping",
-  nested: "/settings",
-}
-```
-
-This places "Shipping" as a child item under `/settings` in the sidebar.
-
 ## Branding
 
 Set `name` and `logo` in the plugin options to customize the sidebar header:
@@ -180,54 +279,6 @@ mercurDashboardPlugin({
 })
 ```
 
-## Replace components
-
-<Steps>
-  <Step title="Write the replacement">
-    Create the component anywhere under `src/`. It must have a default export:
-
-    ```tsx src/components/custom-topbar-actions.tsx
-    export default function CustomTopbarActions() {
-      return (
-        <div>
-          <button>Help</button>
-          <button>Notifications</button>
-        </div>
-      )
-    }
-    ```
-  </Step>
-  <Step title="Point the config at it">
-    Register it in the `components` option. Paths are relative to `src/`:
-
-    ```typescript vite.config.ts
-    mercurDashboardPlugin({
-      medusaConfigPath: '../../packages/api/medusa-config.ts',
-      name: 'My Marketplace',
-      components: {
-        MainSidebar: 'components/custom-sidebar',
-        SettingsSidebar: 'components/custom-settings-sidebar',
-        TopbarActions: 'components/custom-topbar-actions',
-      },
-    })
-    ```
-  </Step>
-  <Step title="Restart and verify">
-    Restart the dev server — your component now renders everywhere its slot appears. Remove the entry and restart to get the built-in back; the originals are never modified.
-  </Step>
-</Steps>
-
-| Component | Description |
-|-----------|-------------|
-| `MainSidebar` | Primary navigation sidebar |
-| `SettingsSidebar` | Settings section sidebar |
-| `TopbarActions` | Action buttons in the top bar |
-| `StoreSetup` | Store setup screen for new sellers (vendor portal) |
-
-<Warning>
-  These four slots are the complete list — there is no generic "replace any component" registry. If what you want to change isn't one of them, it's a page concern: [re-compose the page](/rc/resources/tutorials/recompose-a-page) instead.
-</Warning>
-
 ## Internationalization
 
 <Steps>
@@ -274,36 +325,42 @@ mercurDashboardPlugin({
 ## FAQ
 
 <AccordionGroup>
-  <Accordion title="Can I use Medusa's defineWidgetConfig or widget zones?">
-    No. The Mercur panels don't load Medusa's admin extension system — there are no widget zones to inject into. The equivalent workflows are: drop-in routes for new pages, [compound-component re-composition](/rc/resources/tutorials/recompose-a-page) for changing existing pages, and the four `components` overrides for global chrome. Backend customization (workflows, modules, subscribers) still follows standard Medusa conventions.
+  <Accordion title="Can I use Medusa's defineWidgetConfig and widget zones?">
+    Yes. `defineWidgetConfig` is re-exported from `@mercurjs/dashboard-sdk` and drives file-based widgets under `src/widgets/`. The difference from Medusa is the `before | after` placement suffix on the zone id and that each panel ships its own typed zone set. See [Add a widget](/rc/resources/tutorials/add-a-widget).
+  </Accordion>
+  <Accordion title="How do I add a field to a built-in form or detail page?">
+    Use `defineCustomFieldsConfig` in `src/custom-fields/<model>.tsx` — `forms[]` adds validated fields to create/edit forms, and `displays[]` adds/replaces/removes fields in detail sections. See [Extend forms and tables](/rc/resources/tutorials/extend-forms-and-tables).
   </Accordion>
   <Accordion title="How do I change just one part of a built-in page?">
-    Import the page from the `/pages` subpath (`@mercurjs/vendor/pages` or `@mercurjs/admin/pages`), drop a route at the same path, and re-compose its slots — keep the slots you don't change and they retain all their behavior (data fetching, filters, pagination). The [re-compose tutorial](/rc/resources/tutorials/recompose-a-page) walks through a real example.
+    For a spot inside the page (a banner, an extra field, a column), use a [widget](#widgets) or a [custom field](#custom-fields) — the rest of the page keeps all its behavior.
   </Accordion>
   <Accordion title="Why doesn't my page show up in the sidebar?">
     A sidebar item is only generated when the route file exports a `config` object with a `label`. Also check that the file is named exactly `page.tsx` (or `.ts`/`.jsx`/`.js`) under `src/routes/` and has a **default** export — files without one are skipped entirely.
   </Accordion>
+  <Accordion title="Why does my widget / custom field / nav override not type-check?">
+    Make sure the panel's typed targets are registered — a single `src/extension-targets.d.ts` with `/// <reference types="@mercurjs/vendor/extension-targets" />` (or the admin equivalent). Without it, zone/model/nav ids aren't known to TypeScript. `create-mercur-app` ships this file.
+  </Accordion>
   <Accordion title="Is there a mercur.config.ts file?">
     No — all panel configuration is passed inline to `mercurDashboardPlugin()` in `vite.config.ts`. If you've seen references to a separate config file, they're outdated.
   </Accordion>
   <Accordion title="Does this apply to both the admin panel and the vendor portal?">
-    Yes — both panels use the same SDK and the same conventions. The differences are which built-in pages exist (`@mercurjs/admin/pages` vs `@mercurjs/vendor/pages`) and a few vendor-only options like `StoreSetup` and `enableSellerRegistration`.
+    Both panels use the same SDK and conventions, and a file only targets the panel it lives in. Which built-in zones, models, and nav ids exist differs per panel (each ships its own `extension-targets.d.ts`). Today the widget zones and product custom fields are mounted in the **vendor** portal; navigation overrides work in both.
   </Accordion>
 </AccordionGroup>
 
 ## Next steps
 
 <CardGroup cols={2}>
-  <Card title="Add a custom panel page" href="/rc/resources/tutorials/custom-panel-page">
-    Hands-on: your first drop-in route, end to end.
+  <Card title="Add a widget" href="/rc/resources/tutorials/add-a-widget">
+    Inject a component at a built-in zone with `defineWidgetConfig`.
   </Card>
-  <Card title="Re-compose a built-in page" href="/rc/resources/tutorials/recompose-a-page">
-    Hands-on: override the vendor products page while keeping its table.
+  <Card title="Extend forms and tables" href="/rc/resources/tutorials/extend-forms-and-tables">
+    Add fields and columns with `defineCustomFieldsConfig`.
   </Card>
-  <Card title="Replace panel components" href="/rc/resources/tutorials/replace-panel-components">
-    Hands-on: swap the topbar actions and sidebar.
+  <Card title="Customize navigation" href="/rc/resources/tutorials/customize-navigation">
+    Reorder, hide, and re-parent sidebar items.
   </Card>
-  <Card title="Build your own block" href="/rc/resources/tutorials/build-a-block">
-    Package your customization and share it across projects.
+  <Card title="Add a custom panel page" href="/rc/resources/tutorials/custom-panel-page">
+    Your first drop-in route, end to end.
   </Card>
 </CardGroup>

package/content/resources/tutorials/add-a-widget.mdx

@@ -0,0 +1,110 @@
+---
+title: "Add a widget"
+description: "Inject a React component at a named zone on a built-in panel page with defineWidgetConfig — no forking."
+---
+
+A **widget** is a React component attached to a named zone on a built-in page. You drop one file under `src/widgets/`, and the SDK renders it at that zone while the rest of the page — its data fetching, filters, pagination — stays exactly as shipped. This is the lightest way to add UI to a page you don't own.
+
+<Info>
+  **Additive, not a replacement.** Unlike a drop-in route (which owns the whole page), a widget layers your component onto the built-in page at a documented zone. Reach for this first when you just want to *add* something to an existing screen.
+</Info>
+
+## What you'll build
+
+A tip banner above the vendor product list, rendered from a single file — with the list itself untouched.
+
+## Register the typed targets (once)
+
+Widget zones are typed ids that the vendor panel generates from its own pages and ships as `@mercurjs/vendor/extension-targets`. Register them once so the ids resolve everywhere, with a single ambient reference in your app's `src`:
+
+```typescript apps/vendor/src/extension-targets.d.ts
+/// <reference types="@mercurjs/vendor/extension-targets" />
+```
+
+Projects from `create-mercur-app` already ship this file. With it present, an invalid zone fails `tsc` instead of silently doing nothing.
+
+## Add the widget
+
+<Steps>
+  <Step title="Create the widget file">
+    Drop a file under `src/widgets/`. Export the component as the **default** and a `config` built with `defineWidgetConfig`. The `zone` names where it renders:
+
+    ```tsx apps/vendor/src/widgets/product-list-banner.tsx
+    import { defineWidgetConfig } from "@mercurjs/dashboard-sdk"
+    import { Container, Text } from "@medusajs/ui"
+
+    export const config = defineWidgetConfig({
+      zone: "product.list.before",
+    })
+
+    export default function ProductListBanner() {
+      return (
+        <Container className="mb-2">
+          <Text size="small" className="text-ui-fg-subtle">
+            Tip: bulk-import products from the Products menu.
+          </Text>
+        </Container>
+      )
+    }
+    ```
+  </Step>
+  <Step title="Understand the zone id">
+    A zone id is `<domain>.<view>.<placement>`. The last segment is the placement:
+
+    | Placement | Effect |
+    |-----------|--------|
+    | `before` | Renders before the built-in content of the zone |
+    | `after` | Renders after the built-in content |
+
+    Multiple `before` / `after` widgets on the same zone stack in registration order.
+  </Step>
+  <Step title="Reload the panel">
+    Start the project (`bun run dev`) and open the vendor portal. Widget files hot-reload — the banner appears above the product list, and the table below it works exactly as before.
+  </Step>
+</Steps>
+
+## Available zones
+
+Zones mounted today in the **vendor portal**:
+
+| Zone | Where it renders |
+|------|------------------|
+| `product.list.before` / `.after` | Vendor product list page |
+| `seller.setup.before` / `.after` | The store-setup / onboarding surface (dashboard home + store settings), passed the `seller` as `data` |
+| `login.logo.*` | The logo slot on the public login screen |
+| `login.before.*` / `login.after.*` | Around the login form (rendered before authentication) |
+
+The full, valid set is typed as `WidgetZoneId` and generated into `@mercurjs/vendor/extension-targets` from the panel's own zone hosts — let your editor autocomplete `zone:` to see every option. A zone no page renders can't be targeted and won't type-check.
+
+## Verify
+
+1. The tip banner renders above the product list.
+2. Search, filter, and paginate the list — all built-in behavior still works.
+3. Change the zone to `product.list.after` and reload — the banner moves below the list.
+4. Set `zone: "not.a.zone"` — `tsc` (`bun run lint`) fails with a "not assignable to `WidgetZoneId`" error.
+5. Delete the file — the banner disappears; nothing else changed.
+
+## FAQ
+
+<AccordionGroup>
+  <Accordion title="Can a widget target more than one zone?">
+    Yes — `zone` accepts an array (`zone: ["product.list.before", "login.after.before"]`), and the same component renders at each.
+  </Accordion>
+  <Accordion title="Can a block ship widgets?">
+    Yes. A [block](/rc/learn/blocks) can include `src/widgets/` files in its `vendor_ui` / `admin_ui` entry, and they're aggregated just like the host app's — installing the block adds the widget with no wiring.
+  </Accordion>
+  <Accordion title="Does the admin panel have widget zones too?">
+    The zone set is per panel and generated from each panel's pages. Today the mounted zones live in the vendor portal (`product.list.*`, `login.*`); the admin panel exposes navigation and product custom fields. Check `@mercurjs/admin/extension-targets` for its current zones.
+  </Accordion>
+</AccordionGroup>
+
+## Next steps
+
+<CardGroup cols={2}>
+  <Card title="Extend forms and tables" href="/rc/resources/tutorials/extend-forms-and-tables">
+    Add validated fields and columns with defineCustomFieldsConfig.
+  </Card>
+  <Card title="Extend the onboarding flow" href="/rc/resources/tutorials/extend-onboarding">
+    Add a store-setup field and persist it through a workflow hook.
+  </Card>
+</CardGroup>

package/content/resources/tutorials/add-order-detail-button.mdx

@@ -0,0 +1,113 @@
+---
+title: "Add a button to order details"
+description: "Drop a 'Copy link' button onto the vendor order detail page with a widget — no forking, no page override."
+---
+
+The order detail page is a built-in panel screen you don't own. To add a small piece of UI to it — a button, a badge, a note — you don't copy the page. You drop a **widget** at one of its zones, and the SDK renders your component there while the rest of the page keeps working exactly as shipped.
+
+This tutorial adds a **"Copy link"** button to the order summary section that copies a link to the order.
+
+<Info>
+  **Additive, not a replacement.** A widget layers your component onto a built-in page at a documented zone. Reach for it first whenever you just want to *add* something to an existing screen.
+</Info>
+
+## Add the button
+
+<Steps>
+  <Step title="Create the widget file">
+    Drop a file under `src/widgets/`. Export the component as the **default** and a `config` built with `defineWidgetConfig`. Target `orders.detail.summary.after` — your component renders in the order summary section footer and receives the loaded order as `data`.
+
+    ```tsx apps/vendor/src/widgets/order-copy-link.tsx
+    import { defineWidgetConfig } from "@mercurjs/dashboard-sdk"
+    import type { HttpTypes } from "@medusajs/types"
+    import { Button, Container, toast } from "@medusajs/ui"
+
+    export const config = defineWidgetConfig({
+      zone: "orders.detail.summary.after",
+    })
+
+    const OrderCopyLink = ({ data: order }: { data?: HttpTypes.AdminOrder }) => {
+      if (!order) return null
+
+      const orderLink = `${window.location.origin}/orders/${order.id}`
+
+      const handleCopy = async () => {
+        try {
+          await navigator.clipboard.writeText(orderLink)
+          toast.success("Link copied")
+        } catch {
+          toast.error("Couldn't copy the link")
+        }
+      }
+
+      return (
+        <Container className="flex items-center justify-end p-3">
+          <Button size="small" variant="secondary" onClick={handleCopy}>
+            Copy link
+          </Button>
+        </Container>
+      )
+    }
+
+    export default OrderCopyLink
+    ```
+  </Step>
+  <Step title="Understand the zone id">
+    A zone id is `<domain>.<view>.<slot>.<placement>`. The last segment is the placement:
+
+    | Placement | Effect |
+    |-----------|--------|
+    | `before` | Renders before the built-in content of the zone |
+    | `after` | Renders after the built-in content |
+
+    Multiple `before` / `after` widgets on the same zone stack in registration order.
+  </Step>
+  <Step title="Reload the panel">
+    Start the project (`bun run dev`) and open any order in the vendor portal. Widget files hot-reload — the "Copy link" button appears in the summary section footer, and the rest of the page is untouched.
+  </Step>
+</Steps>
+
+## Order detail zones
+
+Zones mounted on the vendor order detail page:
+
+| Zone | Where it renders |
+|------|------------------|
+| `orders.detail.summary.before` / `.after` | Inside the order summary section (around its footer) |
+| `orders.detail.main.before` / `.after` | Around the main column (summary, payment, fulfillment) |
+| `orders.detail.side.before` / `.after` | Around the sidebar (customer, activity) |
+
+Each is passed the loaded `order` as `data`. The full, valid set is typed as `WidgetZoneId` and generated from the panel's own zone hosts — let your editor autocomplete `zone:` to see every option. A zone no page renders can't be targeted and won't type-check.
+
+## Verify
+
+1. Open an order — the "Copy link" button renders in the summary section footer.
+2. Click it — the link is copied and a toast appears.
+3. Change the zone to `orders.detail.side.before` and reload — the button moves to the top of the sidebar.
+4. Set `zone: "not.a.zone"` — `tsc` (`bun run lint`) fails with a "not assignable to `WidgetZoneId`" error.
+5. Delete the file — the button disappears; nothing else changed.
+
+## FAQ
+
+<AccordionGroup>
+  <Accordion title="What can I read from the order?">
+    The zone passes the loaded order as `data` (`HttpTypes.AdminOrder`) — id, display id, totals, items, `payment_collections`, customer, and more. Build the link (or any UI) from it.
+  </Accordion>
+  <Accordion title="Can a block ship this instead of the host app?">
+    Yes. Put the same file in a [block](/rc/learn/blocks)'s `vendor_ui` entry under `src/widgets/`; installing the block adds the button with no wiring.
+  </Accordion>
+  <Accordion title="Can I render more than a button?">
+    The zone renders any React component — a badge, an action menu, a whole section. You have the full order in `data`.
+  </Accordion>
+</AccordionGroup>
+
+## Next steps
+
+<CardGroup cols={2}>
+  <Card title="Add a widget" href="/rc/resources/tutorials/add-a-widget">
+    The general widget model and the full list of zones.
+  </Card>
+  <Card title="Extend forms and tables" href="/rc/resources/tutorials/extend-forms-and-tables">
+    Add validated fields and columns with defineCustomFieldsConfig.
+  </Card>
+</CardGroup>

package/content/resources/tutorials/custom-panel-page.mdx

@@ -6,7 +6,7 @@ description: "Add a page to the vendor portal with file-based routing — the da
 Adding a page to the admin panel or vendor portal takes one file. The dashboard SDK scans `src/routes/` at build time, registers the route, and — if you export a `config` — adds it to the sidebar with a label and icon. No route table, no registration call.
 
 <Info>
-  **Adding vs changing.** This tutorial *adds* a brand-new page — the right move for new features. To *change* an existing page, don't rebuild it: drop a route at the same path and [re-compose the built-in page's slots](/rc/resources/tutorials/recompose-a-page). The [decision guide](/rc/resources/customization/extending-panels#choosing-your-extension-mechanism) compares every extension mechanism.
+  **Adding vs changing.** This tutorial *adds* a brand-new page — the right move for new features. To *change* an existing page, don't rebuild it: add a [widget](/rc/resources/tutorials/add-a-widget) or a [custom field](/rc/resources/tutorials/extend-forms-and-tables) to inject into it. The [decision guide](/rc/resources/customization/extending-panels#choosing-your-extension-mechanism) compares every extension mechanism.
 </Info>
 
 ## What you'll build
@@ -73,6 +73,6 @@ A `/reviews` page in the vendor portal with a sidebar entry — from a single fi
 ## Next steps
 
 <CardGroup cols={2}>
-  <Card title="Re-compose a built-in page" href="/rc/resources/tutorials/recompose-a-page" />
+  <Card title="Add a widget" href="/rc/resources/tutorials/add-a-widget" />
   <Card title="Add a custom API route" href="/rc/resources/tutorials/custom-api-route" />
 </CardGroup>