@mercurjs/docs 2.2.0-canary.40 → 2.2.0-canary.41

package/content/learn/concepts.mdx

@@ -77,7 +77,7 @@ The [Mercur CLI](/rc/tools/cli) (`@mercurjs/cli@rc`) manages your project — sc
 
 ## Dashboard SDK
 
-The [Dashboard SDK](/rc/tools/dashboard-sdk) (`@mercurjs/dashboard-sdk`) is a Vite plugin shared by the admin panel and vendor portal. It provides file-based routing, automatic navigation generation, component overrides, and i18n support.
+The [Dashboard SDK](/rc/tools/dashboard-sdk) (`@mercurjs/dashboard-sdk`) is a Vite plugin shared by the admin panel and vendor portal. It provides file-based routing, automatic navigation generation, widget and custom-field extensions, and i18n support.
 
 ## API Client
 

package/content/resources/customization/custom-fields.mdx

@@ -9,6 +9,10 @@ Custom Fields let you attach extra data to any existing Medusa entity — produc
   **Where this sits in the stack.** Custom Fields is a Mercur module (`@mercurjs/core/modules/custom-fields`) layered on top of Medusa's standard module-link system — it generates the side table, the link, and the schema for you. It's the lightest way to add data to an entity.
 </Info>
 
+<Note>
+  **This is the *data* layer — not the panel UI.** This module *stores* extra data. The panel-side `defineCustomFieldsConfig` helper (see [Extend forms and tables](/rc/resources/tutorials/extend-forms-and-tables)) *renders* fields into the built-in forms, sections, and tables. They share a name but solve different halves of the problem: use this module for storage and queryability, and the panel helper to expose the values to admins and vendors.
+</Note>
+
 ## When to use Custom Fields
 
 <Tip>
@@ -163,7 +167,7 @@ import {
     Yes — edit the `customFields` config and run `db:migrate` again; the module updates the side table's schema. Removing a field from config stops exposing it; treat destructive column changes with the same care as any schema migration.
   </Accordion>
   <Accordion title="How do vendors or admins edit these values from the panels?">
-    Through your own UI: add a page or re-compose an existing one ([extending panels](/rc/resources/customization/extending-panels)) and call an API route that uses the service's `upsert` — or compose `upsertCustomFieldsStep` into a workflow behind a [custom route](/rc/resources/tutorials/custom-api-route).
+    Through your own UI: add a page or a [panel custom field](/rc/resources/customization/extending-panels#custom-fields) and call an API route that uses the service's `upsert` — or compose `upsertCustomFieldsStep` into a workflow behind a [custom route](/rc/resources/tutorials/custom-api-route).
   </Accordion>
   <Accordion title="Can one entity have multiple custom-field records?">
     No — the side table has a unique constraint on the parent ID, enforcing one-to-one. If you need many records per parent, that's a custom module, not custom fields.

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 |
+| `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="Customize navigation" href="/rc/resources/tutorials/customize-navigation">
+    Reorder, hide, and re-parent sidebar items.
+  </Card>
+</CardGroup>
+</content>

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>

package/content/resources/tutorials/customize-navigation.mdx

@@ -0,0 +1,111 @@
+---
+title: "Customize navigation"
+description: "Reorder, hide, relabel, and re-parent built-in sidebar items with a single _navigation.ts file and defineNavigationConfig."
+---
+
+The built-in sidebar ships a fixed set of items — Orders, Products, Customers, and so on. To reshape them without replacing the whole sidebar, author one host-owned file: `src/_navigation.ts`. It reorders, hides, relabels, and re-parents **built-in** items, and it is the single source of truth for the sidebar's shape.
+
+<Info>
+  **When to use this vs. a `config` export.** New pages you add via [drop-in routes](/rc/resources/tutorials/custom-panel-page) place their own sidebar item through `defineRouteConfig({ label, rank, nested })`. `_navigation.ts` is for the items you *didn't* create — the built-in ones. The two layer cleanly: custom routes place themselves; `_navigation.ts` reshapes the built-ins.
+</Info>
+
+## What you'll build
+
+A vendor sidebar with Orders pinned to the top, Price Lists hidden, and Campaigns moved under Orders.
+
+## Register the typed targets (once)
+
+Nav item ids are typed and generated per panel. Register them once with a single ambient reference in your app's `src` (already shipped by `create-mercur-app`):
+
+```typescript apps/vendor/src/extension-targets.d.ts
+/// <reference types="@mercurjs/vendor/extension-targets" />
+```
+
+With it present, `id` and `nested` autocomplete and an unknown id fails `tsc`.
+
+## Author the navigation file
+
+<Steps>
+  <Step title="Create src/_navigation.ts">
+    The file is host-owned and underscore-prefixed. Default-export a `defineNavigationConfig` with an `items` array of overrides:
+
+    ```ts apps/vendor/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 from the sidebar
+        { id: "campaigns", nested: "orders" },  // re-parent under Orders
+      ],
+    })
+    ```
+  </Step>
+  <Step title="Know the override fields">
+    Each entry targets one built-in item by its stable `id`:
+
+    | Field | Type | Effect |
+    |-------|------|--------|
+    | `id` | `NavItemId` | **Required.** The built-in item to override (top-level or nested) |
+    | `rank` | `number` | Order within its parent (lower first) |
+    | `hidden` | `boolean` | Remove it from the sidebar |
+    | `label` | `string` | Relabel (i18n key or literal) |
+    | `icon` | `ComponentType` | Replace its icon |
+    | `nested` | `NavParentId \| null` | Re-parent under another top-level item; `null` promotes a nested item to top level |
+
+    Both `id` and `nested` are checked against the panel's generated `NavItemRegistry` / `NavParentRegistry`.
+  </Step>
+  <Step title="Reload the panel">
+    Open the vendor portal — Orders sits at the top, Price Lists is gone from the menu, and Campaigns now appears under Orders. The route for a hidden item stays reachable directly by URL unless you also remove it.
+  </Step>
+</Steps>
+
+## Common recipes
+
+```ts
+export default defineNavigationConfig({
+  items: [
+    { id: "payouts", label: "Settlements" },        // relabel
+    { id: "categories", nested: null, rank: 1 },    // promote a nested item to top level
+    { id: "collections", nested: "orders" },        // move a nested item under a different parent
+    { id: "inventory", hidden: true },              // hide a built-in
+  ],
+})
+```
+
+## Verify
+
+1. The top-level order reflects your `rank` values, with `orders` first.
+2. `price-lists` no longer appears in the sidebar.
+3. `campaigns` renders as a child under Orders.
+4. Set `id: "not-an-item"` — `bun run lint` (tsc) fails against `NavItemRegistry`.
+5. Delete `_navigation.ts` — the default sidebar returns.
+
+## FAQ
+
+<AccordionGroup>
+  <Accordion title="Can an installed block reorder the sidebar?">
+    No. Navigation is deliberately host-only — blocks can ship pages, widgets, and custom fields, but the sidebar order stays a single source of truth in your app's `_navigation.ts`.
+  </Accordion>
+  <Accordion title="What ids can I target?">
+    Any built-in item, top-level or nested, by its own id — e.g. `orders`, `products`, `categories`, `collections`, `campaigns`, `customer-groups`. Let your editor autocomplete `id:` against `NavItemId`; the full set is generated into your panel's `extension-targets.d.ts`.
+  </Accordion>
+  <Accordion title="Does this work in the admin panel too?">
+    Yes — drop `src/_navigation.ts` in the admin app and reference `@mercurjs/admin/extension-targets`. Each panel ships its own nav id set.
+  </Accordion>
+  <Accordion title="How do I add a brand-new sidebar item?">
+    That's a [drop-in route](/rc/resources/tutorials/custom-panel-page) with a `config` export — `_navigation.ts` only reshapes built-in items, it doesn't create routes.
+  </Accordion>
+</AccordionGroup>
+
+## Next steps
+
+<CardGroup cols={2}>
+  <Card title="Add a custom panel page" href="/rc/resources/tutorials/custom-panel-page">
+    Add a new screen with its own sidebar item.
+  </Card>
+  <Card title="Add a widget" href="/rc/resources/tutorials/add-a-widget">
+    Inject a component into a built-in page.
+  </Card>
+</CardGroup>
+</content>

package/content/resources/tutorials/extend-forms-and-tables.mdx

@@ -0,0 +1,189 @@
+---
+title: "Extend forms and tables"
+description: "Add validated fields to built-in forms, replace fields in detail sections, and add list columns with defineCustomFieldsConfig and createFormHelper."
+---
+
+`defineCustomFieldsConfig` is Mercur's model-scoped extension surface: from one file per model, you add validated fields to built-in create/edit forms, replace/remove/add fields in detail sections, and add columns to the list table — all wired into the built-in page, all typed against the model's generated registry.
+
+<Info>
+  **UI, not schema.** This helper is a *panel* surface — it renders, validates, and displays fields. It does not create database columns. To *store* extra data, use the backend [Custom Fields module](/rc/resources/customization/custom-fields) or 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`.
+</Info>
+
+## What you'll build
+
+An `ERP ID` field on the vendor product edit form, shown in the product's detail section and as a list-table column — from a single `src/custom-fields/product.tsx`.
+
+## Register the typed targets (once)
+
+Models, form zones, display zones, and built-in field ids are typed per panel. Register them once (shipped by `create-mercur-app`):
+
+```typescript apps/vendor/src/extension-targets.d.ts
+/// <reference types="@mercurjs/vendor/extension-targets" />
+```
+
+## Build the config
+
+<Steps>
+  <Step title="Create the model file">
+    Drop `src/custom-fields/<model>.tsx` and default-export a `defineCustomFieldsConfig`. `createFormHelper` (from `@mercurjs/dashboard-shared`) turns a Zod schema into an input type + validation:
+
+    ```tsx apps/vendor/src/custom-fields/product.tsx
+    import { defineCustomFieldsConfig } from "@mercurjs/dashboard-sdk"
+    import { createFormHelper } from "@mercurjs/dashboard-shared"
+
+    type ProductWithMeta = { metadata?: Record<string, unknown> }
+    const form = createFormHelper<ProductWithMeta>()
+
+    export default defineCustomFieldsConfig({
+      model: "product",
+      forms: [
+        {
+          zone: "edit",
+          fields: {
+            erp_id: form.define({
+              validation: form.string().optional(),
+              label: "ERP ID",
+              description: "External system identifier",
+              placeholder: "ERP-000",
+              defaultValue: (data) => (data?.metadata?.erp_id as string) ?? "",
+            }),
+          },
+        },
+      ],
+    })
+    ```
+  </Step>
+  <Step title="Add a detail-section display">
+    `displays[]` targets a detail-page section by its `zone` id. Keyed by field `id`, an entry **adds**, **replaces**, or **removes** a field:
+
+    ```tsx
+    import { Text } from "@medusajs/ui"
+
+    // ...inside defineCustomFieldsConfig:
+    displays: [
+      {
+        zone: "general",
+        fields: [
+          // ADD — an unknown id appends a new read-only row
+          {
+            id: "erp_id",
+            component: ({ data }) => (
+              <Text size="small" className="text-ui-fg-subtle px-6 py-4">
+                ERP ID: {String(data?.metadata?.erp_id ?? "-")}
+              </Text>
+            ),
+          },
+          // REMOVE — a built-in id + null hides the field
+          { id: "subtitle", component: null },
+          // REPLACE — a built-in id + component overrides its render
+          {
+            id: "handle",
+            component: ({ data }) => (
+              <Text size="small" className="text-ui-fg-subtle px-6 py-4">
+                /{(data as { handle?: string })?.handle}
+              </Text>
+            ),
+          },
+        ],
+      },
+    ],
+    ```
+
+    Built-in field ids (like `subtitle`, `handle`, `status`, `title`) autocomplete from the panel's generated `CustomFieldsRegistry`; an unknown id is treated as an added row.
+  </Step>
+  <Step title="Add a list column">
+    The `list` block extends the model's list table — add or override columns by id, hide built-in columns, and reorder:
+
+    ```tsx
+    // ...inside defineCustomFieldsConfig:
+    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"], // reorder
+      },
+    },
+    ```
+  </Step>
+  <Step title="Reload the panel">
+    Open the vendor portal. The product **edit** drawer shows the ERP ID field (validated on submit and persisted via `additional_data`), the detail **general** section shows the ERP ID row (with `subtitle` removed and `handle` re-rendered), and the product **list** shows the ERP column.
+  </Step>
+</Steps>
+
+## The `createFormHelper` surface
+
+`createFormHelper<T>()` exposes a Zod-based surface that drives both the input type and its validation:
+
+```ts
+const form = createFormHelper<T>()
+
+form.define({
+  validation: form.string().min(1),   // string | number | boolean | date | array | object | null | nullable | coerce
+  label: "…",
+  description: "…",
+  placeholder: "…",
+  defaultValue: "" | ((data) => /* derive from the entity */),
+  component,                            // optional custom render component
+})
+```
+
+Fields render through the standard `Form.Field → Form.Item` chain (never a raw `Controller`) and participate in the existing `TabbedForm` / `RouteDrawer` submit and validation flow.
+
+## Linked-module data
+
+To read data from a linked module alongside the entity, declare it with `link`; those relations are fetched with the entity and become available to columns and displays:
+
+```ts
+export default defineCustomFieldsConfig({
+  model: "product",
+  link: "brand", // or ["brand", "warranty"]
+  list: {
+    columns: [{ id: "brand_name", header: "Brand", component: ({ row }) => row.brand?.name }],
+  },
+})
+```
+
+The SDK derives the fetch query from `link` and merges it into the built-in query with the `+`/`-` convention — you never hand-write the field list.
+
+## Verify
+
+1. The ERP ID field renders in the product edit drawer and validates on submit.
+2. Saving persists the value (visible on reload) via `additional_data` → `metadata`.
+3. The detail general section shows the ERP row, hides `subtitle`, and re-renders `handle`.
+4. The product list shows the ERP column, hides `collection`, and reorders columns.
+5. Set `zone: "nope"` in `forms` — `bun run lint` (tsc) fails against the model's registry.
+
+## FAQ
+
+<AccordionGroup>
+  <Accordion title="Which models and zones are available?">
+    Today: the `product` model in the vendor portal, with form zone `edit` and display zone `general`. The valid set per panel is generated into `CustomFieldsRegistry` in `extension-targets.d.ts` — autocomplete `model` / `zone` to see what's mounted.
+  </Accordion>
+  <Accordion title="Where is the value actually stored?">
+    In the MVP, product custom fields are submitted under `additional_data` and persisted onto `product.metadata`. `defineCustomFieldsConfig` itself doesn't create a column — for durable, queryable storage model it with the backend [Custom Fields module](/rc/resources/customization/custom-fields) or a custom route/workflow.
+  </Accordion>
+  <Accordion title="Can I extend the onboarding wizard?">
+    That's the same helper with `zone: "onboarding"` and `tab` set to a wizard step id (vendor only). It's designed but not mounted in the current MVP — the runtime host exists; the wizard mount is a follow-up.
+  </Accordion>
+  <Accordion title="Can a block ship custom fields?">
+    Yes — a [block](/rc/learn/blocks) can include `src/custom-fields/` files in its `vendor_ui` / `admin_ui` entry, aggregated like the host app's.
+  </Accordion>
+</AccordionGroup>
+
+## Next steps
+
+<CardGroup cols={2}>
+  <Card title="Custom Fields module" href="/rc/resources/customization/custom-fields">
+    Persist extra data on an entity with a generated side table.
+  </Card>
+  <Card title="Add a widget" href="/rc/resources/tutorials/add-a-widget">
+    Inject a component at a built-in zone.
+  </Card>
+</CardGroup>
+</content>

package/content/resources/tutorials/import-export-products.mdx

@@ -6,7 +6,7 @@ description: "Install the product-import-export block and give vendors CSV impor
 Bulk catalog operations belong to vendors, not the operator — a seller migrating from another platform needs to bring hundreds of listings with them. The `product-import-export` block adds CSV import and export to the Vendor Portal: API routes, workflows built on Medusa's product CSV steps, and drawer UIs wired into the product list.
 
 <Info>
-  **This block is also a masterclass in Mercur's extension model.** It ships backend workflows and routes into your API package, and it overrides the vendor `/products` page by dropping a route file that [re-composes the built-in page's compound slots](/rc/resources/tutorials/recompose-a-page) — adding Import/Export buttons while keeping the stock table untouched. After installing, read its source; you own every file.
+  **This block is also a masterclass in Mercur's extension model.** It ships backend workflows and routes into your API package, and it adds Import/Export actions to the vendor products area through the panel extension surface. After installing, read its source; you own every file.
 </Info>
 
 ## What you'll build
@@ -87,8 +87,8 @@ A vendor product list with **Import** and **Export** header buttons, a working C
 ## Next steps
 
 <CardGroup cols={2}>
-  <Card title="Re-compose a built-in page" href="/rc/resources/tutorials/recompose-a-page">
-    The page-override technique this block uses, explained step by step.
+  <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="Build your own block" href="/rc/resources/tutorials/build-a-block">
     Package a feature like this one and publish it to your own registry.

package/llms.txt

@@ -30,23 +30,24 @@ package (`node_modules/@mercurjs/docs/`).
 - [Building with AI](content/resources/ai/overview.mdx) — Mercur ships version-matched docs inside your project so AI coding agents build from accurate APIs instead of stale training data.
 - [Custom Fields](content/resources/customization/custom-fields.mdx) — Extend any Medusa entity with additional fields without modifying core code.
 - [Extend a workflow](content/resources/customization/extend-a-workflow.mdx) — Inject custom logic into an existing Mercur workflow through hooks — without rewriting it.
-- [Extending Panels](content/resources/customization/extending-panels.mdx) — Add pages, customize navigation, branding, and replace components in the admin and vendor panels.
+- [Extending Panels](content/resources/customization/extending-panels.mdx) — Add pages, inject widgets, customize navigation, and extend forms and tables in the admin and vendor panels.
 - [Medusa Cloud deployment](content/resources/deployment/medusa-cloud.mdx) — Deploy Mercur — backend, admin panel, and vendor panel — on Medusa Cloud.
 - [Notifications](content/resources/integrations/notifications.mdx) — Send transactional emails and marketplace notifications with Resend.
 - [Search](content/resources/integrations/search.mdx) — Mercur's provider-agnostic search module — zero-infrastructure Orama by default, swappable for Algolia, Meilisearch, or your own provider.
 - [Stripe Connect Integration](content/resources/integrations/stripe-connect.mdx) — Set up Stripe Connect for marketplace payments and seller payouts — from Stripe Dashboard configuration to the full end-to-end payment lifecycle.
 - [Add a feature with a block](content/resources/tutorials/add-a-block.mdx) — Install the reviews block end-to-end and see it live across the admin, vendor, and storefront surfaces.
+- [Add a widget](content/resources/tutorials/add-a-widget.mdx) — Inject a React component at a named zone on a built-in panel page with defineWidgetConfig — no forking.
 - [Create attributes and variant axes](content/resources/tutorials/attributes-and-variant-axes.mdx) — Build the attribute catalog: a filterable attribute, a variant axis backed by a native product option, and an inline product-scoped axis.
 - [Build your own block](content/resources/tutorials/build-a-block.mdx) — Author a reusable feature as a block — backend, panel UI, and docs — build it into a registry, and install it into any Mercur project.
 - [Configure commissions](content/resources/tutorials/configure-commissions.mdx) — Set the global commission, add scoped rules for categories and sellers, and confirm the right rate lands on an order.
 - [Add a custom API route](content/resources/tutorials/custom-api-route.mdx) — Create a backend endpoint, regenerate the route map, and call it from a panel page with full type safety end to end.
 - [Add a custom panel page](content/resources/tutorials/custom-panel-page.mdx) — Add a page to the vendor portal with file-based routing — the dashboard SDK wires it in automatically.
+- [Customize navigation](content/resources/tutorials/customize-navigation.mdx) — Reorder, hide, relabel, and re-parent built-in sidebar items with a single _navigation.ts file and defineNavigationConfig.
+- [Extend forms and tables](content/resources/tutorials/extend-forms-and-tables.mdx) — Add validated fields to built-in forms, replace fields in detail sections, and add list columns with defineCustomFieldsConfig and createFormHelper.
 - [Build your first marketplace](content/resources/tutorials/first-marketplace.mdx) — Go end-to-end: create a project, approve a seller, list a product, place a split order, and watch a payout settle.
 - [Handle product requests](content/resources/tutorials/handle-product-requests.mdx) — Walk a vendor's product submission and a follow-up edit through the operator review pipeline — confirm, decline, or send back.
 - [Import and export products via CSV](content/resources/tutorials/import-export-products.mdx) — Install the product-import-export block and give vendors CSV import and export drawers on their product list.
 - [Work with master products and offers](content/resources/tutorials/master-products-and-offers.mdx) — Two sellers compete on one catalog entry: publish a master product, create competing offers, and read per-offer prices from the Store API.
-- [Re-compose a built-in page](content/resources/tutorials/recompose-a-page.mdx) — Override a built-in panel page by dropping a route file at the same path and re-composing its compound component slots.
-- [Replace panel components](content/resources/tutorials/replace-panel-components.mdx) — Swap the sidebar, topbar actions, or store setup screen for your own components through dashboard SDK configuration.
 - [Set up seller payouts](content/resources/tutorials/seller-payouts-stripe.mdx) — Take a seller from zero to paid: Stripe Connect onboarding, an order through fulfillment, capture, and the automated payout.
 
 ## Tools — CLI, API client, dashboard SDK

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mercurjs/docs",
-  "version": "2.2.0-canary.40",
+  "version": "2.2.0-canary.41",
   "repository": {
     "type": "git",
     "url": "https://github.com/mercurjs/mercur",

package/content/resources/tutorials/recompose-a-page.mdx

@@ -1,129 +0,0 @@
----
-title: "Re-compose a built-in page"
-description: "Override a built-in panel page by dropping a route file at the same path and re-composing its compound component slots."
----
-
-Every page in the admin and vendor panels is exported as a **compound component** — a root plus named slots like `Header`, `HeaderActions`, and `DataTable`. That means you never fork a page to change one part of it: you drop a `page.tsx` at the same route path, render the original page, and swap only the slot you care about. Everything you don't touch keeps its default behavior — data fetching, filters, pagination, i18n, all of it.
-
-<Info>
-  **This is not Medusa's widget system.** Medusa's admin lets you inject widgets into predefined zones around a page. Mercur takes a different approach: pages are React compound components you re-compose directly. There are no injection zones and no `defineWidgetConfig` — you get the actual page component and decide what renders inside it. See [Extending Panels](/rc/resources/customization/extending-panels) for the full comparison.
-</Info>
-
-## What you'll build
-
-A vendor portal `/products` page with **Import** and **Export** buttons added next to the built-in Create button — while the table, search, filters, and everything else stay exactly as shipped. This is the same technique the official `product-import-export` block uses.
-
-## Slot anatomy
-
-Built-in pages are exported from the `/pages` subpath of each panel package:
-
-```typescript
-import { ProductListPage } from "@mercurjs/vendor/pages"   // vendor portal
-import { CustomerListPage } from "@mercurjs/admin/pages"   // admin panel
-```
-
-Each list page exposes the same family of slots:
-
-| Slot | Renders |
-|------|---------|
-| `Table` | The `Container` shell holding header + table |
-| `Header` | The title/actions row |
-| `HeaderTitle` | Heading and subtitle |
-| `HeaderActions` | The action button cluster |
-| `HeaderCreateButton` | The built-in Create button |
-| `DataTable` | The wired data table — fetching, columns, filters, pagination |
-
-Detail pages expose section slots instead (e.g. `CustomerDetailPage.Main`, `CustomerDetailPage.Sidebar`, `CustomerDetailPage.MainGeneralSection`).
-
-## Override the page
-
-<Steps>
-  <Step title="Drop a route file at the same path">
-    Create the file in your vendor app at the path that matches the built-in route. `/products` maps to `src/routes/products/page.tsx`:
-
-    ```tsx apps/vendor/src/routes/products/page.tsx
-    import { Link } from "react-router-dom"
-    import { Button } from "@medusajs/ui"
-    import { ArrowDownTray, ArrowUpTray } from "@medusajs/icons"
-    import { ProductListPage } from "@mercurjs/vendor/pages"
-
-    export default function ProductsWithImportExport() {
-      return (
-        <ProductListPage>
-          <ProductListPage.Table>
-            <ProductListPage.Header>
-              <ProductListPage.HeaderTitle />
-              <ProductListPage.HeaderActions>
-                <Button size="small" variant="secondary" asChild>
-                  <Link to="import">
-                    <ArrowUpTray />
-                    Import
-                  </Link>
-                </Button>
-                <Button size="small" variant="secondary" asChild>
-                  <Link to="export">
-                    <ArrowDownTray />
-                    Export
-                  </Link>
-                </Button>
-                <ProductListPage.HeaderCreateButton />
-              </ProductListPage.HeaderActions>
-            </ProductListPage.Header>
-            <ProductListPage.DataTable />
-          </ProductListPage.Table>
-        </ProductListPage>
-      )
-    }
-    ```
-  </Step>
-  <Step title="Reuse the slots you don't change">
-    Note what happened in that file: `HeaderTitle`, `HeaderCreateButton`, and `DataTable` are the originals, rendered untouched. Only `HeaderActions` gained two buttons. You re-compose top-down — render the page, re-declare only the branch you're changing, and keep original slots for everything inside it.
-  </Step>
-  <Step title="Reload the panel">
-    The dashboard SDK picks the file up automatically (adding or removing a route file triggers a full reload in dev). Because the path matches a built-in route, **your page replaces the built-in one** — no configuration, no registration.
-  </Step>
-</Steps>
-
-<Note>
-  When a custom route's path matches a built-in route, your page replaces the built-in one. Routes at new paths are appended instead. That one rule is the entire override mechanism.
-</Note>
-
-## How defaults work
-
-If you render a compound page with **no children**, it renders its full default composition — so `<ProductListPage />` alone is identical to the built-in page. Every page root follows the pattern:
-
-```tsx
-Children.count(children) > 0 ? children : <DefaultComposition />
-```
-
-## Verify
-
-1. Run your project (`bun run dev`) and open the vendor portal.
-2. Navigate to **Products** — the list should look identical to before, plus Import and Export buttons in the header.
-3. Search, filter, and paginate the table — all built-in behavior must still work, since `DataTable` is untouched.
-4. Delete your `src/routes/products/page.tsx` and reload — the built-in page comes back. Nothing was forked.
-
-## FAQ
-
-<AccordionGroup>
-  <Accordion title="Where do I find which slots a page exposes?">
-    Import the page from `@mercurjs/vendor/pages` or `@mercurjs/admin/pages` and let your editor's autocomplete list the attached members — every slot is a static property on the page component. The naming is consistent across pages: list pages expose `Table`/`Header`/`HeaderTitle`/`HeaderActions`/`HeaderCreateButton`/`DataTable`; detail pages expose `Main`/`Sidebar` plus one property per section.
-  </Accordion>
-  <Accordion title="Can I remove a built-in element, like the Create button?">
-    Yes — re-composition is declarative. Anything you don't render doesn't appear: re-declare `HeaderActions` with only your own buttons and omit `HeaderCreateButton`.
-  </Accordion>
-  <Accordion title="What about changing the table columns?">
-    `DataTable` is a single slot — you either keep it wholesale or replace it with your own table. For a different column set, replace the slot with your own component built on the shared `DataTable`/`useDataTable` primitives from the panel package.
-  </Accordion>
-</AccordionGroup>
-
-## Next steps
-
-<CardGroup cols={2}>
-  <Card title="Replace panel components" href="/rc/resources/tutorials/replace-panel-components">
-    Swap global chrome like the sidebar or topbar instead of a single page.
-  </Card>
-  <Card title="Add a custom API route" href="/rc/resources/tutorials/custom-api-route">
-    Back your custom page with a typed endpoint of your own.
-  </Card>
-</CardGroup>

package/content/resources/tutorials/replace-panel-components.mdx

@@ -1,116 +0,0 @@
----
-title: "Replace panel components"
-description: "Swap the sidebar, topbar actions, or store setup screen for your own components through dashboard SDK configuration."
----
-
-Some customizations aren't about one page — they change the panel's global chrome. For those, the dashboard SDK exposes a small set of **named component overrides**: you point the plugin config at your own file, and the panel renders your component in place of the built-in one everywhere it appears.
-
-<Info>
-  **Choose the right tool.** A component override replaces one of four global layout slots across the whole panel. If you want to change a single page, [re-compose it](/rc/resources/tutorials/recompose-a-page) instead — and if you want to add a new screen, just [drop in a route](/rc/resources/tutorials/custom-panel-page). The decision guide in [Extending Panels](/rc/resources/customization/extending-panels#choosing-your-extension-mechanism) compares all three.
-</Info>
-
-## What you'll build
-
-A vendor portal with custom topbar actions (a help link and a status badge) and a custom main sidebar, configured entirely from `vite.config.ts`.
-
-## The available slots
-
-Exactly four layout components can be replaced:
-
-| Component | Where it renders |
-|-----------|------------------|
-| `MainSidebar` | Primary navigation sidebar on every main page |
-| `SettingsSidebar` | Sidebar of the `/settings` section |
-| `TopbarActions` | Action cluster on the right side of the top bar |
-| `StoreSetup` | The store setup screen shown to new sellers (vendor portal) |
-
-Anything else — a page, a section, a table — is customized through routes and compound components, not through overrides.
-
-## Set up the override
-
-<Steps>
-  <Step title="Write the replacement component">
-    Create the component anywhere under `src/`. It must have a **default export**:
-
-    ```tsx apps/vendor/src/components/topbar-actions.tsx
-    import { Badge, Button } from "@medusajs/ui"
-
-    export default function TopbarActions() {
-      return (
-        <div className="flex items-center gap-x-2">
-          <Badge size="2xsmall" color="green">
-            All systems operational
-          </Badge>
-          <Button size="small" variant="transparent" asChild>
-            <a href="https://help.example.com" target="_blank" rel="noreferrer">
-              Help
-            </a>
-          </Button>
-        </div>
-      )
-    }
-    ```
-  </Step>
-  <Step title="Register it in the Vite config">
-    Component overrides live in the `components` option of `mercurDashboardPlugin`, in your panel app's `vite.config.ts`. Paths are **relative to `src/`**:
-
-    ```typescript apps/vendor/vite.config.ts
-    import { defineConfig } from 'vite'
-    import react from '@vitejs/plugin-react'
-    import { mercurDashboardPlugin } from '@mercurjs/dashboard-sdk'
-
-    export default defineConfig({
-      plugins: [
-        react(),
-        mercurDashboardPlugin({
-          medusaConfigPath: '../../packages/api/medusa-config.ts',
-          components: {
-            TopbarActions: 'components/topbar-actions',
-            MainSidebar: 'components/main-sidebar',
-          },
-        }),
-      ],
-    })
-    ```
-
-    The plugin resolves each path at build time and swaps your component in through the `virtual:mercur/components` module — no runtime registration, no context providers to wire.
-  </Step>
-  <Step title="Restart the dev server">
-    Vite config changes require a restart. After it, your components render everywhere their slots appear.
-  </Step>
-</Steps>
-
-<Tip>
-  Build overrides with `@medusajs/ui` components and Medusa UI color tokens so they match the rest of the panel. The panels ship no other UI library.
-</Tip>
-
-## Verify
-
-1. Open the vendor portal — the top bar shows your badge and Help link on every page.
-2. Navigate between main pages and `/settings` — the override applies everywhere its slot renders.
-3. Remove the `components` entry and restart — the built-in components return. The originals were never modified.
-
-## FAQ
-
-<AccordionGroup>
-  <Accordion title="If I replace MainSidebar, do my custom routes still show up in the menu?">
-    Only if your sidebar renders them. A `MainSidebar` override replaces the **entire** navigation sidebar, including the auto-generated menu items from route `config` exports — read them from `virtual:mercur/menu-items` if you want to keep automatic navigation. If you only want to add or reorder items, you don't need an override at all: the `config` export on route files (with `rank` and `nested`) covers that.
-  </Accordion>
-  <Accordion title="Can I override other components, like the login page or a form?">
-    No — these four slots are the complete list. The login flow, forms, and everything page-level are customized through drop-in routes and [compound re-composition](/rc/resources/tutorials/recompose-a-page).
-  </Accordion>
-  <Accordion title="Do overrides apply to both panels?">
-    Each panel app has its own `vite.config.ts`, so overrides are configured per panel. `StoreSetup` only exists in the vendor portal; the other three slots exist in both.
-  </Accordion>
-</AccordionGroup>
-
-## Next steps
-
-<CardGroup cols={2}>
-  <Card title="Re-compose a built-in page" href="/rc/resources/tutorials/recompose-a-page">
-    Change one page's composition instead of global chrome.
-  </Card>
-  <Card title="Extending Panels" href="/rc/resources/customization/extending-panels">
-    The full reference for routes, navigation, branding, and overrides.
-  </Card>
-</CardGroup>