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

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/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/references/workflows/cart/add-seller-shipping-method-to-cart.mdx

@@ -21,12 +21,16 @@ await addSellerShippingMethodToCartWorkflow(container).run({
 ## Input
 
 <ParamField body="cart_id" type="string" required>The cart to add shipping methods to.</ParamField>
-<ParamField body="options" type="object[]" required>Shipping options to add as methods.
+
+<ParamField body="options" type="object[]" required>
+  Shipping options to add as methods.
+
   <Expandable title="properties">
     <ParamField body="id" type="string" required>The shipping option ID; must have a calculated price for the cart.</ParamField>
     <ParamField body="data" type="object">Custom method data validated by the fulfillment provider.</ParamField>
   </Expandable>
 </ParamField>
+
 <ParamField body="additional_data" type="object">Custom data passed through to the workflow hooks.</ParamField>
 
 ## Result

package/content/references/workflows/commission/batch-commission-rules.mdx

@@ -23,13 +23,17 @@ const { result } = await batchCommissionRulesWorkflow(container).run({
 ## Input
 
 <ParamField body="commission_rate_id" type="string" required>The commission rate the rules belong to.</ParamField>
-<ParamField body="create" type="object[]">Rules to create.
+<ParamField body="create" type="object[]">
+  Rules to create.
+
   <Expandable title="properties">
     <ParamField body="reference" type="string" required>Entity type the rule targets (e.g. `seller`, `product_category`, `product_type`).</ParamField>
     <ParamField body="reference_id" type="string" required>ID of the referenced entity.</ParamField>
   </Expandable>
 </ParamField>
-<ParamField body="update" type="object[]">Rules to update.
+<ParamField body="update" type="object[]">
+  Rules to update.
+
   <Expandable title="properties">
     <ParamField body="id" type="string" required>The rule to update.</ParamField>
     <ParamField body="reference" type="string">New reference type.</ParamField>

package/content/references/workflows/offer/batch-offer-inventory-items.mdx

@@ -23,13 +23,17 @@ const { result } = await batchOfferInventoryItemsWorkflow(container).run({
 ## Input
 
 <ParamField body="offer_id" type="string" required>The offer whose inventory links are managed; fails if not found.</ParamField>
-<ParamField body="create" type="object[]">Links to create; the inventory items must exist and not appear in `update`/`delete`.
+<ParamField body="create" type="object[]">
+  Links to create; the inventory items must exist and not appear in `update`/`delete`.
+
   <Expandable title="properties">
     <ParamField body="inventory_item_id" type="string" required>The inventory item to link.</ParamField>
     <ParamField body="required_quantity" type="number">Units consumed per offer unit; defaults to `1`.</ParamField>
   </Expandable>
 </ParamField>
-<ParamField body="update" type="object[]">Existing links to update.
+<ParamField body="update" type="object[]">
+  Existing links to update.
+
   <Expandable title="properties">
     <ParamField body="inventory_item_id" type="string" required>The linked inventory item.</ParamField>
     <ParamField body="required_quantity" type="number" required>New units consumed per offer unit.</ParamField>

package/content/references/workflows/offer/create-offers.mdx

@@ -31,7 +31,9 @@ const { result } = await createOffersWorkflow(container).run({
 
 ## Input
 
-<ParamField body="offers" type="object[]" required>Offers to create.
+<ParamField body="offers" type="object[]" required>
+  Offers to create.
+
   <Expandable title="properties">
     <ParamField body="seller_id" type="string" required>The seller that owns the offer.</ParamField>
     <ParamField body="created_by" type="string" required>ID of the member creating the offer.</ParamField>

package/content/references/workflows/offer/update-offers.mdx

@@ -24,7 +24,9 @@ const { result } = await updateOffersWorkflow(container).run({
 
 ## Input
 
-<ParamField body="offers" type="object[]" required>Offer updates, keyed by ID.
+<ParamField body="offers" type="object[]" required>
+  Offer updates, keyed by ID.
+
   <Expandable title="properties">
     <ParamField body="id" type="string" required>The offer to update; fails if not found.</ParamField>
     <ParamField body="sku" type="string">New SKU.</ParamField>

package/content/references/workflows/order-group/get-order-groups-list.mdx

@@ -21,7 +21,9 @@ const { result } = await getOrderGroupsListWorkflow(container).run({
 ## Input
 
 <ParamField body="fields" type="string[]" required>Fields to retrieve; merged with the defaults needed for status aggregation.</ParamField>
-<ParamField body="variables" type="object">Query filters plus pagination.
+<ParamField body="variables" type="object">
+  Query filters plus pagination.
+
   <Expandable title="properties">
     <ParamField body="skip" type="number">Number of groups to skip.</ParamField>
     <ParamField body="take" type="number">Number of groups to return.</ParamField>

package/content/references/workflows/payout/process-payout-for-webhook.mdx

@@ -21,7 +21,9 @@ await processPayoutForWebhookWorkflow(container).run({
 ## Input
 
 <ParamField body="action" type="string" required>One of `account.activated`, `account.restricted`, `account.rejected`, `payout.processing`, `payout.paid`, `payout.failed`, `payout.canceled`, `not_supported`.</ParamField>
-<ParamField body="data" type="object">Event target; nothing happens when omitted.
+<ParamField body="data" type="object">
+  Event target; nothing happens when omitted.
+
   <Expandable title="properties">
     <ParamField body="id" type="string" required>The ID of the payout account (for `account.*` actions) or the payout (for `payout.*` actions).</ParamField>
   </Expandable>

package/content/references/workflows/product/confirm-products.mdx

@@ -33,6 +33,8 @@ await confirmProductsWorkflow(container).run({
   Operator-only note stored on the audit change and included in the emitted event.
 </ParamField>
 
+<ParamField body="additional_data" type="object">Custom data passed through to the workflow hooks.</ParamField>
+
 ## Result
 
 <ResponseField name="result" type="void">

package/content/references/workflows/product/reject-product.mdx

@@ -33,6 +33,8 @@ await rejectProductWorkflow(container).run({
   Actor id recorded on the audit trail entry.
 </ParamField>
 
+<ParamField body="additional_data" type="object">Custom data passed through to the workflow hooks.</ParamField>
+
 ## Result
 
 <ResponseField name="result" type="void">

package/content/references/workflows/product/request-product-change.mdx

@@ -33,6 +33,8 @@ await requestProductChangeWorkflow(container).run({
   Actor id recorded on the audit trail entry.
 </ParamField>
 
+<ParamField body="additional_data" type="object">Custom data passed through to the workflow hooks.</ParamField>
+
 ## Result
 
 <ResponseField name="result" type="void">

package/content/references/workflows/seller/approve-seller.mdx

@@ -19,6 +19,8 @@ await approveSellerWorkflow(container).run({
 
 <ParamField body="seller_id" type="string" required>Id of the seller to approve.</ParamField>
 
+<ParamField body="additional_data" type="object">Custom data passed through to the workflow hooks.</ParamField>
+
 ## Result
 
 <ResponseField name="result" type="void">Nothing is returned.</ResponseField>

package/content/references/workflows/seller/suspend-seller.mdx

@@ -20,6 +20,8 @@ await suspendSellerWorkflow(container).run({
 <ParamField body="seller_id" type="string" required>Id of the seller to suspend.</ParamField>
 <ParamField body="reason" type="string">Reason stored in `status_reason`.</ParamField>
 
+<ParamField body="additional_data" type="object">Custom data passed through to the workflow hooks.</ParamField>
+
 ## Result
 
 <ResponseField name="result" type="void">Nothing is returned.</ResponseField>

package/content/references/workflows/seller/terminate-seller.mdx

@@ -20,6 +20,8 @@ await terminateSellerWorkflow(container).run({
 <ParamField body="seller_id" type="string" required>Id of the seller to terminate.</ParamField>
 <ParamField body="reason" type="string">Reason stored in `status_reason`.</ParamField>
 
+<ParamField body="additional_data" type="object">Custom data passed through to the workflow hooks.</ParamField>
+
 ## Result
 
 <ResponseField name="result" type="void">Nothing is returned.</ResponseField>

package/content/references/workflows/seller/unsuspend-seller.mdx

@@ -19,6 +19,8 @@ await unsuspendSellerWorkflow(container).run({
 
 <ParamField body="seller_id" type="string" required>Id of the suspended seller.</ParamField>
 
+<ParamField body="additional_data" type="object">Custom data passed through to the workflow hooks.</ParamField>
+
 ## Result
 
 <ResponseField name="result" type="void">Nothing is returned.</ResponseField>

package/content/references/workflows/seller/unterminate-seller.mdx

@@ -19,6 +19,8 @@ await unterminateSellerWorkflow(container).run({
 
 <ParamField body="seller_id" type="string" required>Id of the terminated seller.</ParamField>
 
+<ParamField body="additional_data" type="object">Custom data passed through to the workflow hooks.</ParamField>
+
 ## Result
 
 <ResponseField name="result" type="void">Nothing is returned.</ResponseField>