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

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>