@mercurjs/docs 2.2.0-canary.45 → 2.2.0-canary.47

package/content/references/overview.mdx

@@ -58,6 +58,16 @@ Mercur extends the Medusa server with three route surfaces. Start with the conve
   </Card>
 </CardGroup>
 
+## Panel extension API
+
+The file-based helpers for extending the admin and vendor panels without forking.
+
+<CardGroup cols={1}>
+  <Card title="Panel Extension API" href="/rc/references/panel-extension-api">
+    <code>defineWidgetConfig</code>, <code>defineNavigationConfig</code>, <code>defineCustomFieldsConfig</code>, and <code>createFormHelper</code> — config shapes and the exact props passed to every component you supply.
+  </Card>
+</CardGroup>
+
 ## Workflows and configuration
 
 <CardGroup cols={2}>

package/content/references/panel-extension-api.mdx

@@ -0,0 +1,337 @@
+---
+title: "Panel Extension API"
+description: "The file-based helpers for extending the admin and vendor panels — defineWidgetConfig, defineNavigationConfig, defineCustomFieldsConfig, createFormHelper — and the exact props passed to every component you supply."
+---
+
+This is the technical contract for the panel extension API.
+Where the [Extend forms and tables](/rc/resources/tutorials/extend-forms-and-tables),
+[Add a widget](/rc/resources/tutorials/add-a-widget), and
+[Customize navigation](/rc/resources/tutorials/customize-navigation) tutorials
+walk through *building* an extension, this page documents the exact config shape
+of each helper and — most importantly — **the props each `component` you pass in
+receives at render time**.
+
+<Info>
+  **Separate apps, no `surface` field.** Admin (`@mercurjs/admin`, port 7000) and
+  vendor (`@mercurjs/vendor`, port 7001) are separate Vite apps. A file dropped
+  under a panel's `src/` targets *that* panel — the folder you author in *is* the
+  surface. The helpers are the same in both; import them from
+  `@mercurjs/dashboard-sdk` (config helpers) and `@mercurjs/dashboard-shared`
+  (`createFormHelper`).
+</Info>
+
+## Typed targets (register once)
+
+Zone ids, nav item ids, models, and built-in field ids are typed per panel from a
+generated `extension-targets.d.ts`. Reference it once per host app so every
+extension file type-checks with no per-file import:
+
+```typescript apps/vendor/src/extension-targets.d.ts
+/// <reference types="@mercurjs/vendor/extension-targets" />
+```
+
+```typescript apps/admin-test/src/extension-targets.d.ts
+/// <reference types="@mercurjs/admin/extension-targets" />
+```
+
+A wrong `zone`, `model`, or nav `id` fails `tsc` (`bun run lint`) rather than
+silently no-op'ing at runtime.
+
+---
+
+## `defineWidgetConfig`
+
+A widget is a React component attached to a named zone on a built-in page. The
+placement (`before | after | replace`) is the last segment of the zone id.
+
+```tsx apps/vendor/src/widgets/product-list-banner.tsx
+import { defineWidgetConfig } from "@mercurjs/dashboard-sdk"
+
+export const config = defineWidgetConfig({
+  zone: "product.list.before", // WidgetZoneId — <domain>.<view>[.<slot>].<before|after|replace>
+})
+
+export default ProductListBanner
+```
+
+### Config
+
+| Field  | Type                            | Description                                                                 |
+| ------ | ------------------------------- | --------------------------------------------------------------------------- |
+| `zone` | `WidgetZoneId \| WidgetZoneId[]` | Target zone(s). Placement is the suffix. Multiple widgets stack in order.    |
+| `id`   | `string` (optional)             | Stable id; derived from the file path at build time when omitted.           |
+
+### Component props
+
+The widget component receives a single prop:
+
+| Prop   | Type      | Description                                                                                |
+| ------ | --------- | ----------------------------------------------------------------------------------------- |
+| `data` | `unknown` | The zone's contextual entity — e.g. the loaded product on a `product.detail.*` zone. Undefined on list/public zones that have no single entity. |
+
+```tsx
+const ProductDetailNote = ({ data }: { data?: HttpTypes.AdminProduct }) => (
+  <Container>{data?.title}</Container>
+)
+```
+
+<Note>
+  The public `login.logo` / `login.before` / `login.after` zones render before
+  authentication and receive no `data`.
+</Note>
+
+---
+
+## `defineNavigationConfig`
+
+Reorder, hide, relabel, or re-parent **built-in** sidebar items. Single
+host-owned file — blocks cannot contribute nav overrides.
+
+```ts apps/vendor/src/_navigation.ts
+import { defineNavigationConfig } from "@mercurjs/dashboard-sdk"
+
+export default defineNavigationConfig({
+  items: [
+    { id: "orders", rank: 0 },
+    { id: "price-lists", hidden: true },
+    { id: "payouts", label: "settlements" },
+    { id: "categories", nested: null, rank: 1 },
+    { id: "campaigns", nested: "orders" },
+  ],
+})
+```
+
+### `NavItemOverride`
+
+| Field    | Type                       | Description                                                                    |
+| -------- | -------------------------- | ------------------------------------------------------------------------------ |
+| `id`     | `NavItemId`                | Built-in item to override (top-level or nested). Typed against the panel registry. |
+| `rank`   | `number` (optional)        | Order within the item's parent (or among top-level items).                     |
+| `hidden` | `boolean` (optional)       | Remove from the sidebar (route may still be directly reachable).               |
+| `label`  | `string` (optional)        | i18n key or literal replacing the item's label.                                |
+| `icon`   | `ComponentType` (optional) | Icon component replacing the item's icon (from `@medusajs/icons`).             |
+| `nested` | `NavParentId \| null` (optional) | Re-parent under a built-in parent id; `null` promotes a nested item to top level. |
+
+There is no `component` prop here — navigation overrides reshape existing items
+only.
+
+---
+
+## `defineCustomFieldsConfig`
+
+The model-scoped surface. One file per model adds form fields, section displays,
+section actions, and list-table columns. Import
+`createFormHelper` from `@mercurjs/dashboard-shared` to turn 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",
+  link: "brand", // string | string[] — module link(s) fetched alongside the entity
+  forms: [/* ... */],
+  displays: [/* ... */],
+  list: {/* ... */},
+})
+```
+
+### Top-level config
+
+| Field      | Type                     | Description                                                              |
+| ---------- | ------------------------ | ------------------------------------------------------------------------ |
+| `model`    | `CustomFieldModel`       | Target model (start with `"product"`). Typed against `CustomFieldsRegistry`. |
+| `link`     | `string \| string[]`     | Module link(s) fetched alongside the entity; their data is available to columns and displays via the `+link.*` fetch. |
+| `forms`    | `CustomFormEntry[]`      | Fields injected into built-in create/edit/onboarding forms.              |
+| `displays` | `CustomDisplayEntry[]`   | Field replace/remove/add + `ActionMenu` actions on detail sections.      |
+| `list`     | `CustomListExtension`    | Columns, bulk actions, filters, view defaults on the model's list table. |
+
+### `forms[]` — form fields
+
+```tsx
+forms: [
+  {
+    zone: "edit",         // CustomFormZone — "create" | "edit" | "organize" | "attributes" | "onboarding"
+    tab: "general",       // TabbedForm tab id, or wizard step id for zone: "onboarding"
+    fields: {
+      erp_id: form.define({
+        validation: form.string().nullish(), // Zod → input type + validation
+        defaultValue: (data) => (data?.metadata?.erp_id as string) ?? "",
+        label: "ERP ID",
+        description: "External system identifier",
+        placeholder: "ERP-000",
+        component: MyErpInput, // optional custom render
+      }),
+    },
+  },
+]
+```
+
+Each field is a `CustomFormField`:
+
+| Field          | Type                                     | Description                                                       |
+| -------------- | ---------------------------------------- | ----------------------------------------------------------------- |
+| `validation`   | Zod schema                               | Drives both the default input type and validation.                |
+| `defaultValue` | `unknown \| ((data) => unknown)`         | Static value or a resolver from the loaded entity.                |
+| `label`        | `string` (optional)                      | Field label.                                                      |
+| `description`  | `string` (optional)                      | Help text below the input.                                        |
+| `placeholder`  | `string` (optional)                      | Input placeholder.                                                |
+| `component`    | `ComponentType` (optional)               | Custom render; falls back to a default input for the Zod type.    |
+
+<Warning>
+  **Form-field `component` receives no props.** It is rendered as `<Component />`
+  inside the field's `additional_data.<field>` React Hook Form context. Read and
+  write the value with RHF's `useFormContext()` / `useController()`, and render
+  through the mandated `Form.Field → Form.Item` chain — do not use a raw
+  `Controller`. Values live in form state under `additional_data`; in the MVP,
+  `product` custom fields persist onto the product's `metadata`.
+</Warning>
+
+### `displays[]` — detail sections
+
+```tsx
+displays: [
+  {
+    zone: "general", // CustomFieldsRegistry displayZones — an existing detail section id
+    fields: [
+      { id: "erp_id", component: ErpRow },           // ADD (unknown id → new read-only row)
+      { id: "status", component: BrandedStatusBadge }, // REPLACE a built-in field's render
+      { id: "created_by", component: null },           // REMOVE a built-in field
+    ],
+    actions: [
+      { rank: 0, component: SyncErpAction },            // add to the section's ActionMenu
+    ],
+  },
+]
+```
+
+`fields[]` is `CustomDisplayField`:
+
+| Field       | Type                                    | Description                                                                            |
+| ----------- | --------------------------------------- | -------------------------------------------------------------------------------------- |
+| `id`        | `displayFieldIds \| (string & {})`      | Built-in field id (autocompletes) → replace/remove; any other string → add a new row.  |
+| `component` | `ComponentType<{ data? }> \| null`      | Render component, or `null` to remove a built-in field.                                |
+
+**Display field `component` props:**
+
+| Prop   | Type      | Description                        |
+| ------ | --------- | ---------------------------------- |
+| `data` | `unknown` | The loaded detail entity, **including any `link`ed module data**. If the config declares `link: "brand"`, read it off `data.brand` here. |
+
+```tsx
+// with `link: "brand"` on the config, the linked module data rides on `data`
+const BrandRow = ({ data }: { data?: { brand?: { name: string } } }) => (
+  <Text>{data?.brand?.name}</Text>
+)
+```
+
+`actions[]` is `SectionAction` (the same shape as list `bulkActions`):
+
+| Field       | Type                            | Description                                                       |
+| ----------- | ------------------------------- | ----------------------------------------------------------------- |
+| `rank`      | `number` (optional)             | Position within the section's `ActionMenu`.                       |
+| `component` | `ComponentType<{ data? }>`      | Owns its own label, icon, group placement, and `onClick`.         |
+
+**Section-action `component` props:**
+
+| Prop   | Type      | Description                                                              |
+| ------ | --------- | ----------------------------------------------------------------------- |
+| `data` | `unknown` | The loaded detail entity, **including any `link`ed module data** (e.g. `data.brand`). |
+
+### `list` — list table
+
+```tsx
+list: {
+  columns: [
+    { id: "title", component: ({ value }) => <strong>{value}</strong> }, // override a cell
+    { id: "brand_name", header: "Brand", component: ({ row }) => row.brand?.name }, // add (from link)
+  ],
+  bulkActions: [{ rank: 0, component: ArchiveBulkAction }],
+  filters: [/* add / remove list filters */],
+  viewDefaults: {
+    columnVisibility: { created_at: false }, // hide a column
+    columnOrder: ["title", "sku", "erp_id"],
+  },
+}
+```
+
+`columns[]` is `CustomColumn`:
+
+| Field       | Type                                       | Description                                              |
+| ----------- | ------------------------------------------ | -------------------------------------------------------- |
+| `id`        | `string`                                   | Column id — matches a built-in column to override, or adds a new one. |
+| `header`    | `string` (optional)                        | Column header text (for added columns).                 |
+| `component` | `ComponentType<{ row?, value? }>` (optional) | Cell renderer.                                          |
+
+**Column `component` props:**
+
+| Prop    | Type      | Description                                               |
+| ------- | --------- | -------------------------------------------------------- |
+| `row`   | `unknown` | The full row entity (including `link`ed module data).    |
+| `value` | `unknown` | The cell value for this column id, when derivable.       |
+
+`bulkActions[]` is `SectionAction` (`{ rank?, component }`, component props `{ data? }`).
+
+<Note>
+  **Bulk-action rendering is deferred in the MVP.** `bulkActions` are accepted and
+  surfaced by the config but not yet mounted into the list toolbar.
+</Note>
+
+<Warning>
+  **Vendor product list is field-constrained.** The vendor `product` list must use
+  the curated fields from `useProductTableQuery` — the SDK merges `link` fetches
+  with the `+`/`-` convention, never bare fields, or the list 500s. You never
+  hand-write the field list; the `link` declaration drives it.
+</Warning>
+
+---
+
+## `createFormHelper`
+
+`createFormHelper<T>()` returns Medusa's zod surface for describing field
+validation and value types:
+
+```ts
+const form = createFormHelper<ProductWithMeta>()
+
+form.define({ validation, defaultValue?, label?, description?, placeholder?, component? })
+form.string() / form.number() / form.boolean() / form.date()
+form.array() / form.object() / form.null() / form.nullable() / form.coerce
+```
+
+The generated registry types the **target** (which zone/tab/field ids exist); the
+Zod `validation` types the **value**. The two compose — codegen types the address,
+Zod types the payload.
+
+---
+
+## Persistence
+
+<Warning>
+  **The MVP is a UI surface only.** Custom fields render, validate, and display
+  through the built-in forms/sections/tables — there is no generic core-side write
+  path. For `product`, values are submitted under `additional_data` and persisted
+  onto `metadata`. To store data for other models, wire your own route/workflow or
+  use the backend [Custom Fields module](/rc/resources/customization/custom-fields).
+</Warning>
+
+## Related
+
+<CardGroup cols={2}>
+  <Card title="Extend forms and tables" href="/rc/resources/tutorials/extend-forms-and-tables">
+    Step-by-step build with `defineCustomFieldsConfig`.
+  </Card>
+  <Card title="Add a widget" href="/rc/resources/tutorials/add-a-widget">
+    Inject a component into a zone.
+  </Card>
+  <Card title="Customize navigation" href="/rc/resources/tutorials/customize-navigation">
+    Reorder and hide sidebar items.
+  </Card>
+  <Card title="Custom Fields module" href="/rc/references/modules/custom-fields">
+    The backend storage layer.
+  </Card>
+</CardGroup>

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

@@ -70,7 +70,7 @@ Zones mounted today in the **vendor portal**:
 | Zone | Where it renders |
 |------|------------------|
 | `product.list.before` / `.after` | Vendor product list page |
-| `store.setup.before` / `.after` | The store-setup / onboarding surface (dashboard home + store settings), passed the `seller` as `data` |
+| `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) |
 

package/content/resources/tutorials/extend-onboarding.mdx

@@ -3,10 +3,10 @@ title: "Extend the onboarding flow"
 description: "Add a field to the vendor store-setup surface, submit it through additional_data, and persist it durably from a workflow hook — end to end, without forking."
 ---
 
-The vendor **store-setup / onboarding** surface is a widget zone (`store.setup`) that renders the full `seller` object as its `data`. That makes onboarding a full extension seam: drop a widget to add UI, carry the new value to the API on the built-in seller routes through `additional_data`, and persist it from a workflow hook — the same three layers you'd wire in plain Medusa, kept intact by Mercur.
+The vendor **store-setup / onboarding** surface is a widget zone (`seller.setup`) that renders the full `seller` object as its `data`. That makes onboarding a full extension seam: drop a widget to add UI, carry the new value to the API on the built-in seller routes through `additional_data`, and persist it from a workflow hook — the same three layers you'd wire in plain Medusa, kept intact by Mercur.
 
 <Info>
-  **Three layers, one flow.** The panel (a `store.setup` widget) *renders and collects*. The vendor seller route *carries* the value through `additional_data` — no core schema change. A `sellersUpdated` workflow hook *persists* it. Each layer is additive: nothing built-in is replaced.
+  **Three layers, one flow.** The panel (a `seller.setup` widget) *renders and collects*. The vendor seller route *carries* the value through `additional_data` — no core schema change. A `sellersUpdated` workflow hook *persists* it. Each layer is additive: nothing built-in is replaced.
 </Info>
 
 ## What you'll build
@@ -21,13 +21,13 @@ Widget zones are typed ids the vendor panel generates from its own pages and shi
 /// <reference types="@mercurjs/vendor/extension-targets" />
 ```
 
-With it present, `store.setup` autocompletes and an invalid zone fails `tsc` instead of silently doing nothing.
+With it present, `seller.setup` autocompletes and an invalid zone fails `tsc` instead of silently doing nothing.
 
 ## 1 — Render on the onboarding surface
 
 <Steps>
   <Step title="Add the store-setup widget">
-    Drop a file under `src/widgets/`. Export the component as the **default** and a `config` with `zone: "store.setup.before"`. The zone hands your component the `seller` as `data`:
+    Drop a file under `src/widgets/`. Export the component as the **default** and a `config` with `zone: "seller.setup.before"`. The zone hands your component the `seller` as `data`:
 
     ```tsx apps/vendor/src/widgets/tax-id-setup.tsx
     import "@mercurjs/vendor/extension-targets"
@@ -40,7 +40,7 @@ With it present, `store.setup` autocompletes and an invalid zone fails `tsc` ins
     import { client } from "../lib/client"
 
     export const config = defineWidgetConfig({
-      zone: "store.setup.before",
+      zone: "seller.setup.before",
     })
 
     const TaxIdSetup = ({ data: seller }: { data?: SellerDTO }) => {
@@ -94,14 +94,14 @@ With it present, `store.setup` autocompletes and an invalid zone fails `tsc` ins
     ```
   </Step>
   <Step title="Understand where it renders">
-    `store.setup` is hosted in two places, both passing the same `seller` as `data`:
+    `seller.setup` is hosted in two places, both passing the same `seller` as `data`:
 
     | Host | When it shows |
     |------|---------------|
     | The vendor shell (above the page outlet) | On top-level routes — the dashboard "home" onboarding banner |
     | The store settings detail page | Always, above the store status banner |
 
-    A single widget file covers both. Multiple `store.setup.before` / `.after` widgets stack in registration order.
+    A single widget file covers both. Multiple `seller.setup.before` / `.after` widgets stack in registration order.
   </Step>
 </Steps>
 
@@ -203,7 +203,7 @@ That is the whole "wiring" step: your `{ tax_id }` payload arrives in the workfl
 ## How the layers connect
 
 ```
-store.setup widget  →  client.vendor.sellers.$id.mutate({ additional_data })
+seller.setup widget  →  client.vendor.sellers.$id.mutate({ additional_data })
         │
         ▼
 POST /vendor/sellers/:id  →  updateSellersWorkflow({ update, additional_data })

package/content/resources/tutorials/store-setup-checklist.mdx

@@ -0,0 +1,214 @@
+---
+title: "Build a store-setup checklist"
+description: "Render an onboarding progress checklist on the vendor store-setup surface with a seller.setup widget — the seller is handed to you as data, no fetching required."
+---
+
+The vendor **store-setup / onboarding** surface is a widget zone (`seller.setup`)
+that renders the full `seller` object as its `data`. That makes it the perfect
+seam for an onboarding **checklist**: derive completion from the seller you're
+handed, show what's left, and link each step to the page that completes it — all
+from a single widget file, with nothing fetched and nothing forked.
+
+<Info>
+  **This is the pattern the built-in store-setup card uses.** The shipped
+  "Complete store profile" card is itself a `seller.setup` widget that reads the
+  `seller` and renders a progress list. This tutorial rebuilds it so you can
+  shape your own onboarding steps.
+</Info>
+
+## What you'll build
+
+A collapsible progress card on the store-setup surface that checks four parts of
+the seller profile (details, address, company, payment), draws a progress bar,
+and routes the vendor to the settings page for each incomplete step. When every
+step is done, the card removes itself.
+
+## Register the typed targets (once)
+
+Widget zones are typed ids the vendor panel generates from its own pages and
+ships as `@mercurjs/vendor/extension-targets`. Reference them once so `seller.setup`
+autocompletes and a wrong zone fails `tsc`:
+
+```typescript apps/vendor/src/extension-targets.d.ts
+/// <reference types="@mercurjs/vendor/extension-targets" />
+```
+
+## Build the checklist widget
+
+<Steps>
+  <Step title="Derive the steps from the seller">
+    The `data` prop is the full `SellerDTO`. Compute each step's `completed` flag
+    from it — no request needed. Give every step a `path` to the settings page
+    that finishes it:
+
+    ```tsx apps/vendor/src/widgets/store-setup-checklist.tsx
+    import "@mercurjs/vendor/extension-targets"
+    import { SellerDTO } from "@mercurjs/types"
+
+    type ProfileStep = {
+      key: string
+      label: string
+      completed: boolean
+      path: string
+    }
+
+    function getProfileSteps(seller: SellerDTO): ProfileStep[] {
+      const hasStoreDetails = !!(seller.name && seller.email && seller.description)
+      const hasAddress = !!(
+        seller.address?.address_1 &&
+        seller.address?.city &&
+        seller.address?.country_code
+      )
+      const hasCompanyDetails = !!seller.professional_details?.corporate_name
+      const hasPaymentDetails = !!(
+        seller.payment_details?.holder_name &&
+        seller.payment_details?.country_code
+      )
+
+      return [
+        { key: "store_details", label: "Add store details", completed: hasStoreDetails, path: "/settings/store/edit" },
+        { key: "address", label: "Add address", completed: hasAddress, path: "/settings/store/address" },
+        { key: "company_details", label: "Add company details", completed: hasCompanyDetails, path: "/settings/store/professional-details" },
+        { key: "payment_details", label: "Add payment details", completed: hasPaymentDetails, path: "/settings/store/payment-details" },
+      ]
+    }
+    ```
+
+  </Step>
+  <Step title="Render the collapsible progress card">
+    Use `@medusajs/ui` primitives and `@medusajs/icons` only. Draw a progress bar
+    from the completed ratio, list each step with a status icon, and navigate on
+    click. Return `null` when everything is done so the card disappears:
+
+    ```tsx apps/vendor/src/widgets/store-setup-checklist.tsx
+    import { useMemo, useState } from "react"
+    import { useNavigate } from "react-router-dom"
+    import { Container, Text, clx } from "@medusajs/ui"
+    import { CheckCircleSolid, TriangleDownMini, CircleDottedLine } from "@medusajs/icons"
+    import { Collapsible as RadixCollapsible } from "radix-ui"
+
+    const StoreSetupChecklist = ({ data: seller }: { data?: SellerDTO }) => {
+      const navigate = useNavigate()
+      const [open, setOpen] = useState(true)
+
+      const steps = useMemo(
+        () => (seller ? getProfileSteps(seller) : []),
+        [seller]
+      )
+
+      if (!seller) {
+        return null
+      }
+
+      const completedCount = steps.filter((s) => s.completed).length
+      const totalCount = steps.length
+      const progressPercent = (completedCount / totalCount) * 100
+
+      if (completedCount === totalCount) {
+        return null
+      }
+
+      return (
+        <RadixCollapsible.Root open={open} onOpenChange={setOpen}>
+          <Container className="overflow-hidden p-0">
+            <div
+              className="h-1 bg-ui-tag-green-icon transition-all duration-500"
+              style={{ width: `${progressPercent}%` }}
+            />
+            <div className="p-6">
+              <RadixCollapsible.Trigger asChild>
+                <button className="flex w-full items-center justify-between">
+                  <Text size="large" weight="plus" leading="compact">
+                    Complete store profile
+                  </Text>
+                  <TriangleDownMini
+                    className={clx(
+                      "text-ui-fg-muted transition-transform duration-200",
+                      !open && "-rotate-90"
+                    )}
+                  />
+                </button>
+              </RadixCollapsible.Trigger>
+
+              <RadixCollapsible.Content>
+                <div className="mt-4 flex flex-col gap-y-3">
+                  {steps.map((step) => (
+                    <button
+                      key={step.key}
+                      className="flex items-center gap-x-3 text-left"
+                      onClick={() => !step.completed && navigate(step.path)}
+                      disabled={step.completed}
+                    >
+                      {step.completed ? (
+                        <CheckCircleSolid className="text-ui-tag-green-icon shrink-0" />
+                      ) : (
+                        <CircleDottedLine className="text-ui-fg-muted shrink-0" />
+                      )}
+                      <Text size="small" leading="compact" className="text-ui-fg-base">
+                        {step.label}
+                      </Text>
+                    </button>
+                  ))}
+                </div>
+              </RadixCollapsible.Content>
+            </div>
+          </Container>
+        </RadixCollapsible.Root>
+      )
+    }
+    ```
+
+  </Step>
+  <Step title="Attach it to the store-setup zone">
+    Export the component as the **default** and a `config` with a `seller.setup`
+    zone. `before` renders it above the built-in card; use `after` to place it
+    below:
+
+    ```tsx apps/vendor/src/widgets/store-setup-checklist.tsx
+    import { defineWidgetConfig } from "@mercurjs/dashboard-sdk"
+
+    export const config = defineWidgetConfig({
+      zone: "seller.setup.before",
+    })
+
+    export default StoreSetupChecklist
+    ```
+
+  </Step>
+</Steps>
+
+## Where it renders
+
+`seller.setup` is hosted in two places, both passing the same `seller` as `data`:
+
+| Host                                     | When it shows                                                |
+| ---------------------------------------- | ------------------------------------------------------------ |
+| The vendor shell (above the page outlet) | On top-level routes — the dashboard "home" onboarding banner |
+| The store settings detail page           | Always, above the store status banner                        |
+
+A single widget file covers both. Multiple `seller.setup.before` / `.after`
+widgets stack in registration order, so your checklist and the built-in card can
+coexist — or hide the built-in one by rendering your own and letting theirs
+complete.
+
+<Note>
+  **No data fetching.** Because the zone hands you the resolved `seller`, the
+  widget is pure render — you never call the SDK. To *collect and persist* a new
+  onboarding value (e.g. a Tax ID) rather than just link to existing pages, see
+  [Extend the onboarding flow](/rc/resources/tutorials/extend-onboarding), which
+  carries a value through `additional_data` to a workflow hook.
+</Note>
+
+## Next steps
+
+<CardGroup cols={2}>
+  <Card
+    title="Extend the onboarding flow"
+    href="/rc/resources/tutorials/extend-onboarding"
+  >
+    Collect a new value and persist it through a workflow hook.
+  </Card>
+  <Card title="Add a widget" href="/rc/resources/tutorials/add-a-widget">
+    The full widget model and the published zone registry.
+  </Card>
+</CardGroup>

package/llms.txt

@@ -50,6 +50,7 @@ package (`node_modules/@mercurjs/docs/`).
 - [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.
 - [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.
+- [Build a store-setup checklist](content/resources/tutorials/store-setup-checklist.mdx) — Render an onboarding progress checklist on the vendor store-setup surface with a seller.setup widget — the seller is handed to you as data, no fetching required.
 
 ## Tools — CLI, API client, dashboard SDK
 
@@ -215,6 +216,7 @@ package (`node_modules/@mercurjs/docs/`).
 - [Search module](content/references/modules/search.mdx) — The provider-agnostic search module, its document shapes, and the provider contract.
 - [Seller module](content/references/modules/seller.mdx) — Data models, links, and service methods for the Seller module.
 - [References](content/references/overview.mdx) — Technical references for Mercur's modules, HTTP APIs, workflows, and configuration.
+- [Panel Extension API](content/references/panel-extension-api.mdx) — The file-based helpers for extending the admin and vendor panels — defineWidgetConfig, defineNavigationConfig, defineCustomFieldsConfig, createFormHelper — and the exact props passed to every component you supply.
 - [addSellerShippingMethodToCartWorkflow](content/references/workflows/cart/add-seller-shipping-method-to-cart.mdx) — Add shipping methods to a cart, replacing only the same seller's existing methods.
 - [completeCartWithSplitOrdersWorkflow](content/references/workflows/cart/complete-cart-with-split-orders.mdx) — Complete a multi-seller cart by splitting it into per-seller orders under an order group.
 - [listSellerShippingOptionsForCartWorkflow](content/references/workflows/cart/list-seller-shipping-options-for-cart.mdx) — List available shipping options for a cart, grouped by seller.

package/package.json

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