@mercurjs/docs 2.2.1 → 2.3.0-canary.1

package/content/references/configuration.mdx

@@ -3,7 +3,9 @@ title: "Configuration"
 description: "withMercur() options, environment variables, and provider configuration."
 ---
 
-Mercur is configured through the standard Medusa config file. `withMercur()` wraps `defineConfig()` and wires the marketplace layer in — you pass it the same shape you would pass to Medusa, plus one Mercur-specific field.
+Mercur is configured through the standard Medusa config file.
+
+`withMercur()` wraps `defineConfig()` and wires the marketplace layer in. You pass it the same shape you would pass to Medusa, plus one Mercur-specific field.
 
 ## withMercur()
 
@@ -39,7 +41,7 @@ The option surface is Medusa's `InputConfigWithArrayModules` extended with:
 
 | Option | Type | Purpose |
 | --- | --- | --- |
-| `projectConfig.http.vendorCors` | `string` | CORS origins for the Vendor API (`/vendor/*`) — the only Mercur-specific option |
+| `projectConfig.http.vendorCors` | `string` | CORS origins for the Vendor API (`/vendor/*`). The only Mercur-specific option |
 
 ### What withMercur applies
 
@@ -47,10 +49,10 @@ The option surface is Medusa's `InputConfigWithArrayModules` extended with:
 | --- | --- |
 | Registers the core plugin | Appends `@mercurjs/core` to `plugins` unless already present |
 | Registers RBAC | Appends the `@medusajs/medusa/rbac` module and forces `featureFlags.rbac = true`, so vendor role scoping works out of the box |
-| Disables the Medusa admin | `admin.disable` defaults to `true` — Mercur ships its own dashboards |
+| Disables the Medusa admin | `admin.disable` defaults to `true`, since Mercur ships its own dashboards |
 | Adjusts core middlewares | Replaces the Medusa middlewares that Mercur overrides (e.g. collections with media) |
 
-Everything you pass is otherwise forwarded to `defineConfig()` unchanged, so any valid Medusa configuration remains valid here.
+Everything else you pass is forwarded to `defineConfig()` unchanged, so any valid Medusa configuration stays valid here.
 
 ## Environment variables
 
@@ -58,16 +60,16 @@ The starter (`apps/api` and projects created with `create-mercur-app`) reads:
 
 | Variable | Purpose | Default |
 | --- | --- | --- |
-| `DATABASE_URL` | Postgres connection string | — (required) |
+| `DATABASE_URL` | Postgres connection string | Required |
 | `REDIS_URL` | Redis for cache, event bus, workflow engine, locking | `redis://localhost:6379` |
-| `STORE_CORS` | Storefront CORS origins | — (required) |
-| `ADMIN_CORS` | Admin panel CORS origins | — (required) |
-| `VENDOR_CORS` | Vendor panel CORS origins | — (required) |
-| `AUTH_CORS` | Auth endpoint CORS origins | — (required) |
+| `STORE_CORS` | Storefront CORS origins | Required |
+| `ADMIN_CORS` | Admin panel CORS origins | Required |
+| `VENDOR_CORS` | Vendor panel CORS origins | Required |
+| `AUTH_CORS` | Auth endpoint CORS origins | Required |
 | `JWT_SECRET` | JWT signing secret | `supersecret` (change in production) |
 | `COOKIE_SECRET` | Cookie signing secret | `supersecret` (change in production) |
 | `FILE_BACKEND_URL` | Public origin baked into uploaded file URLs | `http://localhost:9000/static` |
-| `MERCUR_VENDOR_URL` | Vendor dashboard base URL used in member invite links | `""` — can also be set via the seller module's `vendor_url` option |
+| `MERCUR_VENDOR_URL` | Vendor dashboard base URL used in member invite links | `""`; can also be set via the seller module's `vendor_url` option |
 | `NODE_ENV` | Environment selection | `development` |
 
 ## Dashboard modules
@@ -118,38 +120,19 @@ Register `@mercurjs/payout-stripe-connect` as a provider of the payout module:
 
 | Option | Type | Default | Purpose |
 | --- | --- | --- | --- |
-| `apiKey` | `string` | — (required) | Stripe secret key |
-| `webhookSecret` | `string` | — (required) | Verifies incoming Stripe webhook signatures |
+| `apiKey` | `string` | Required | Stripe secret key |
+| `webhookSecret` | `string` | Required | Verifies incoming Stripe webhook signatures |
 | `accountValidation.detailsSubmitted` | `boolean` | `true` | Require onboarding details submitted before the account is active |
 | `accountValidation.chargesEnabled` | `boolean` | `true` | Require charges enabled |
 | `accountValidation.payoutsEnabled` | `boolean` | `true` | Require payouts enabled |
 | `accountValidation.noOutstandingRequirements` | `boolean` | `true` | Treat pending Stripe requirements as `restricted` |
 | `accountValidation.requiredCapabilities` | `string[]` | `[]` | Stripe capabilities that must be `active` |
 
-The payout module itself also accepts scheduling options (`authorizationWindowMs`, `sellerActionWindowMs`, `captureSafetyBufferMs`, `requiredFulfillmentStatus`) — see the [Payout module reference](/rc/references/modules/payout#module-options).
-
-## Search provider
-
-The search module needs no configuration — when no provider is given, the built-in in-memory Orama provider registers automatically. To use a custom provider:
-
-```ts
-{
-  resolve: "@mercurjs/core/modules/search",
-  options: {
-    provider: {
-      resolve: "./src/providers/my-search-provider",
-      id: "my-search",
-      options: { /* provider options */ },
-    },
-  },
-}
-```
-
-The provider must extend `AbstractSearchProvider` — see the [Search module reference](/rc/references/modules/search#provider-contract).
+The payout module itself also accepts scheduling options (`authorizationWindowMs`, `sellerActionWindowMs`, `captureSafetyBufferMs`, `requiredFulfillmentStatus`). See the [Payout module](/platform/payout/overview).
 
 ## Next steps
 
 <CardGroup cols={2}>
-  <Card title="Installation" href="/rc/learn/installation" />
+  <Card title="Installation" href="/learn/introduction" />
   <Card title="Stripe Connect integration" href="/rc/resources/integrations/stripe-connect" />
 </CardGroup>

package/content/references/overview.mdx

@@ -1,80 +1,62 @@
 ---
-title: "References"
-description: "Technical references for Mercur's modules, HTTP APIs, workflows, and configuration."
+title: "Reference"
+sidebarTitle: "Overview"
+description: "Technical reference for Mercur's HTTP APIs, panel extensions, and configuration."
 ---
 
-This section is the technical contract of the Mercur core plugin. Where the [Learn](/rc/learn/introduction) tab explains concepts, these pages document the exact surface: data models and their fields, module links, service methods, HTTP routes, workflow names, and configuration options.
-
-## Modules
-
-Every marketplace capability ships as a Medusa module inside `@mercurjs/core`. Each reference covers the module's data models, enums, links to Medusa core entities, service methods, and options.
-
-<CardGroup cols={3}>
-  <Card title="Seller" href="/rc/references/modules/seller">
-    Sellers, members, invites, and order groups.
-  </Card>
-  <Card title="Commission" href="/rc/references/modules/commission">
-    Commission rates, rules, and per-order commission lines.
-  </Card>
-  <Card title="Payout" href="/rc/references/modules/payout">
-    Payout accounts, onboarding, payouts, and the provider interface.
-  </Card>
-  <Card title="Offer" href="/rc/references/modules/offer">
-    Per-seller listings binding a variant to SKU, price, and inventory.
-  </Card>
-  <Card title="Product Attribute" href="/rc/references/modules/product-attribute">
-    Configurable attributes, values, and variant axes on native product options.
-  </Card>
-  <Card title="Product Edit" href="/rc/references/modules/product-edit">
-    Product change requests and the approval queue.
-  </Card>
-  <Card title="Media" href="/rc/references/modules/media">
-    Image galleries, thumbnails, banners, and icons for categories and collections.
-  </Card>
-  <Card title="Search" href="/rc/references/modules/search">
-    Provider-agnostic search with the built-in Orama provider.
-  </Card>
-  <Card title="Custom Fields" href="/rc/references/modules/custom-fields">
-    Extra columns on any entity without a custom module.
-  </Card>
-</CardGroup>
+This section is the technical contract of the Mercur core plugin. The
+[Learn](/learn/introduction) tab explains concepts and the
+[Platform](/platform/store/overview) tab documents each domain's data models,
+workflows, service, and events. These pages cover the HTTP APIs, the panel
+extension helpers, and configuration.
 
 ## HTTP API
 
-Mercur extends the Medusa server with three route surfaces. Start with the conventions page — authentication, seller scoping, and pagination work the same way across all of them.
+Mercur extends the Medusa server with three route surfaces. Start with the
+conventions page: authentication, seller scoping, and pagination work the same
+way across all of them.
 
 <CardGroup cols={2}>
-  <Card title="API conventions" href="/rc/references/api/conventions">
+  <Card title="API conventions" href="/references/api/conventions">
     Authentication, seller scoping, pagination, field selection, and webhooks.
   </Card>
-  <Card title="Admin API" href="/rc/references/api/admin">
+  <Card title="Admin API" href="/references/api/admin">
     Operator routes under <code>/admin/*</code>.
   </Card>
-  <Card title="Vendor API" href="/rc/references/api/vendor">
+  <Card title="Vendor API" href="/references/api/vendor">
     Seller-scoped routes under <code>/vendor/*</code>.
   </Card>
-  <Card title="Store API" href="/rc/references/api/store">
+  <Card title="Store API" href="/references/api/store">
     Storefront routes under <code>/store/*</code>.
   </Card>
 </CardGroup>
 
-## Panel extension API
+## Panel extensions
 
-The file-based helpers for extending the admin and vendor panels without forking.
+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.
+<CardGroup cols={2}>
+  <Card title="Overview" href="/references/panel-extensions/overview">
+    Typed targets, persistence, and how the helpers fit together.
+  </Card>
+  <Card title="Widgets" href="/references/panel-extensions/widgets">
+    <code>defineWidgetConfig</code>: zones, config, and component props.
+  </Card>
+  <Card title="Custom Fields" href="/references/panel-extensions/custom-fields">
+    <code>defineCustomFieldsConfig</code>: forms, displays, and list columns.
+  </Card>
+  <Card title="Create a new page" href="/references/panel-extensions/create-page">
+    <code>defineNavigationConfig</code> and <code>createFormHelper</code>.
   </Card>
 </CardGroup>
 
-## Workflows and configuration
+## Configuration
 
 <CardGroup cols={2}>
-  <Card title="Workflows" href="/rc/references/workflows">
-    Every workflow exported by <code>@mercurjs/core</code>, grouped by domain.
-  </Card>
-  <Card title="Configuration" href="/rc/references/configuration">
+  <Card title="Configuration" href="/references/configuration">
     <code>withMercur()</code>, environment variables, and provider options.
   </Card>
+  <Card title="Platform modules" href="/platform/store/overview">
+    Data models, workflows, service, and events for each domain.
+  </Card>
 </CardGroup>

package/content/references/panel-extensions/create-page.mdx

@@ -0,0 +1,194 @@
+---
+title: "Create a new page"
+sidebarTitle: "Create new page"
+description: "Add a page to the admin or vendor panel with file-based routing, then register it in the sidebar."
+---
+
+A page is a React component mounted at a route. Pages are file-based. You drop a
+`page.tsx` under a panel's `src/routes/` folder and the SDK registers it at build
+time, the same way [Next.js](https://nextjs.org) and [Remix](https://remix.run)
+map folders to routes.
+
+This guide walks through creating a page, then documents the routing conventions,
+the sidebar config, and the `defineNavigationConfig` and `createFormHelper`
+helpers.
+
+## Create a page
+
+<Steps>
+  <Step title="Add a page file">
+    Create `page.tsx` in a new folder under `src/routes/`. The folder path becomes
+    the URL, so this file mounts at `/erp-sync`.
+
+    ```tsx apps/vendor/src/routes/erp-sync/page.tsx
+    const ErpSyncPage = () => {
+      return <div>ERP sync</div>
+    }
+
+    export default ErpSyncPage
+    ```
+
+    The default export is the only required part. Only files named `page` register
+    as routes, so you can co-locate a `loader.ts` or components in the same folder.
+  </Step>
+
+  <Step title="Add it to the sidebar">
+    A page has no sidebar entry until it exports a `config` with a `label`. The
+    config is a plain object.
+
+    ```tsx apps/vendor/src/routes/erp-sync/page.tsx
+    import { ArrowsPointingOut } from "@medusajs/icons"
+
+    export const config = {
+      label: "ERP sync",
+      icon: ArrowsPointingOut,
+    }
+    ```
+  </Step>
+
+  <Step title="Run the panel">
+    Start the panel and open the route. The page renders and its sidebar entry
+    appears.
+
+    ```bash Terminal
+    bun run dev
+    ```
+
+    The vendor panel runs on `http://localhost:7001` and the admin panel on
+    `http://localhost:7000`.
+  </Step>
+</Steps>
+
+## Route paths
+
+Folder and file names map to path segments. Wrap a segment in brackets or
+parentheses to make it dynamic or optional.
+
+| Folder segment | Route path   | Description                                          |
+| -------------- | ------------ | ---------------------------------------------------- |
+| `products`     | `/products`  | Static segment.                                      |
+| `[id]`         | `/:id`       | Dynamic parameter.                                   |
+| `[[id]]`       | `/:id?`      | Optional dynamic parameter.                          |
+| `[*]`          | `/*`         | Splat. Matches the rest of the path.                 |
+| `[[*]]`        | `/*?`        | Optional splat.                                      |
+| `(preview)`    | `/preview?`  | Optional static segment.                             |
+| `@modal`       | nested route | Parallel segment. Renders inside its parent's route. |
+
+Read a dynamic segment with React Router's `useParams()`. A file at
+`src/routes/orders/[id]/page.tsx` mounts at `/orders/:id`.
+
+## Where the page mounts
+
+The route path and the page's `config.public` flag decide which layout wraps the
+page.
+
+| Layout   | When                                            | Example route                                     |
+| -------- | ----------------------------------------------- | ------------------------------------------------- |
+| Main     | Default. Any protected route.                   | `src/routes/erp-sync/page.tsx`                    |
+| Settings | Route path starts with `/settings/`.            | `src/routes/settings/erp/page.tsx`               |
+| Public   | `config.public` is `true`. Renders before auth. | `src/routes/status/page.tsx` with `config.public` |
+
+Main and settings routes render inside the authenticated shell. Public routes
+render on their own, so use them for pages a signed-out user must reach.
+
+## Sidebar config
+
+The `config` object controls the page's sidebar entry.
+
+| Field           | Type                       | Description                                                     |
+| --------------- | -------------------------- | -------------------------------------------------------------- |
+| `label`         | `string`                   | Sidebar label. A page with no `label` has no sidebar entry.    |
+| `icon`          | `ComponentType` (optional) | Sidebar icon, from `@medusajs/icons`.                          |
+| `rank`          | `number` (optional)        | Order among sibling items. Lower ranks first.                  |
+| `nested`        | `string` (optional)        | Parent item id to nest this entry under.                       |
+| `translationNs` | `string` (optional)        | i18n namespace used to resolve `label` as a translation key.   |
+| `public`        | `boolean` (optional)       | Render the route before authentication under the public layout. |
+
+<Note>
+  A page can exist without a sidebar entry. Omit `label` when the route is reached
+  from a link or a widget rather than the sidebar.
+</Note>
+
+## Load data for a page
+
+Export a `loader` to fetch data before the component renders, and a `handle` to
+attach route metadata such as a breadcrumb. Both are React Router route options,
+picked up as named exports.
+
+```tsx apps/vendor/src/routes/erp-sync/page.tsx
+import type { LoaderFunction } from "react-router-dom"
+
+export const loader: LoaderFunction = async () => {
+  return { syncedAt: new Date().toISOString() }
+}
+
+export const handle = {
+  breadcrumb: () => "ERP sync",
+}
+```
+
+Read the loader's result with `useLoaderData()` inside the component.
+
+## Reshape built-in navigation
+
+Use `defineNavigationConfig` to reorder, hide, relabel, or re-parent built-in
+sidebar items. It lives in a single host-owned file, `src/_navigation.ts`. Blocks
+cannot contribute navigation 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" },
+  ],
+})
+```
+
+Each entry is a `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. The route may still be reachable directly.             |
+| `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. |
+
+Navigation overrides reshape existing items only. To add a new item, register a
+page with a `config.label` as shown above.
+
+## Type a page's forms
+
+`createFormHelper<T>()` returns Medusa's Zod surface for describing field
+validation and value types. Import it from `@mercurjs/dashboard-shared`.
+
+```ts
+import { createFormHelper } from "@mercurjs/dashboard-shared"
+
+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, and field ids exist.
+The Zod `validation` types the value. See [Custom Fields](/references/panel-extensions/custom-fields)
+for where `form.define` fields are attached.
+
+## Next steps
+
+<CardGroup cols={2}>
+  <Card title="Widgets" href="/references/panel-extensions/widgets">
+    Render a component in a slot on an existing page.
+  </Card>
+  <Card title="Custom Fields" href="/references/panel-extensions/custom-fields">
+    Add fields, section rows, and list columns to a built-in model.
+  </Card>
+</CardGroup>

package/content/references/panel-extensions/custom-fields.mdx

@@ -0,0 +1,256 @@
+---
+title: "Custom Fields"
+sidebarTitle: "Custom Fields"
+description: "Add fields, detail rows, section actions, and list columns to a built-in model."
+---
+
+Custom fields extend a built-in model's forms, detail sections, and list table
+without forking the page. You add a field to the create and edit forms, a row to
+the detail view, an action to a section menu, or a column to the list.
+
+You write one file per model under `src/custom-fields/` and default-export a
+`defineCustomFieldsConfig`. The config targets a model, optionally fetches linked
+module data alongside it, and describes what to add to each surface.
+
+## Add a custom field
+
+<Steps>
+  <Step title="Create a custom-fields file">
+    Create a file under `src/custom-fields/` and default-export
+    `defineCustomFieldsConfig` with the model you want to extend. Start with
+    `product`.
+
+    ```tsx apps/vendor/src/custom-fields/product.tsx
+    import { defineCustomFieldsConfig } from "@mercurjs/dashboard-sdk"
+
+    export default defineCustomFieldsConfig({
+      model: "product",
+    })
+    ```
+  </Step>
+
+  <Step title="Describe the field with `createFormHelper`">
+    Import `createFormHelper` from `@mercurjs/dashboard-shared` and turn a Zod
+    schema into an input type and validation. The Zod schema drives both the
+    default input and the validation.
+
+    ```tsx apps/vendor/src/custom-fields/product.tsx
+    import { createFormHelper } from "@mercurjs/dashboard-shared"
+
+    type ProductWithMeta = { metadata?: Record<string, unknown> }
+    const form = createFormHelper<ProductWithMeta>()
+    ```
+  </Step>
+
+  <Step title="Add the field to a form">
+    Add the field to a built-in form zone and tab. This injects an `ERP ID` field
+    into the product edit form.
+
+    ```tsx apps/vendor/src/custom-fields/product.tsx
+    export default defineCustomFieldsConfig({
+      model: "product",
+      forms: [
+        {
+          zone: "edit",
+          tab: "general",
+          fields: {
+            erp_id: form.define({
+              validation: form.string().nullish(),
+              defaultValue: (data) => (data?.metadata?.erp_id as string) ?? "",
+              label: "ERP ID",
+              placeholder: "ERP-000",
+            }),
+          },
+        },
+      ],
+    })
+    ```
+  </Step>
+
+  <Step title="Run the panel">
+    Start the panel and open the product edit form. The field renders in its tab.
+
+    ```bash Terminal
+    bun run dev
+    ```
+
+    For `product`, values submit under `additional_data` and persist onto the
+    product's `metadata`. See [Persistence](#persistence) for other models.
+  </Step>
+</Steps>
+
+## Configuration
+
+`defineCustomFieldsConfig` takes one object.
+
+| Field      | Type                   | Description                                                                                          |
+| ---------- | ---------------------- | --------------------------------------------------------------------------------------------------- |
+| `model`    | `CustomFieldModel`     | Target model. Start with `"product"`. Typed against `CustomFieldsRegistry`.                          |
+| `link`     | `string \| string[]`   | Module link or links fetched alongside the entity. Their data is available to columns and displays. |
+| `forms`    | `CustomFormEntry[]`    | Fields injected into built-in create, edit, and onboarding forms.                                   |
+| `displays` | `CustomDisplayEntry[]` | Field replace, remove, or add, plus `ActionMenu` actions on detail sections.                        |
+| `list`     | `CustomListExtension`  | Columns, bulk actions, filters, and view defaults on the model's list table.                        |
+
+## Add fields to a form
+
+Inject fields into a built-in create, edit, or onboarding form.
+
+```tsx
+forms: [
+  {
+    zone: "edit",         // "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(),
+        defaultValue: (data) => (data?.metadata?.erp_id as string) ?? "",
+        label: "ERP ID",
+        description: "External system identifier",
+        placeholder: "ERP-000",
+        component: MyErpInput,
+      }),
+    },
+  },
+]
+```
+
+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>
+  **A form-field `component` receives no props.** It renders as `<Component />`
+  inside the field's `additional_data.<field>` React Hook Form context. Read and
+  write the value with `useFormContext()` or `useController()`, and render through
+  the `Form.Field` and `Form.Item` chain. Do not use a raw `Controller`. Values
+  live in form state under `additional_data`. For `product`, custom fields persist
+  onto the product's `metadata`.
+</Warning>
+
+## Extend detail sections
+
+Add, replace, or remove fields on a detail section, and add actions to its
+`ActionMenu`.
+
+```tsx
+displays: [
+  {
+    zone: "general", // an existing detail section id
+    fields: [
+      { id: "erp_id", component: ErpRow },             // ADD (unknown id -> new row)
+      { id: "status", component: BrandedStatusBadge }, // REPLACE a built-in field
+      { 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, which autocompletes, to replace or remove. Any other string adds a new row. |
+| `component` | `ComponentType<{ data? }> \| null` | Render component, or `null` to remove a built-in field.                                |
+
+A display `component` receives the loaded detail entity as `data`, including any
+`link`ed module data. If the config declares `link: "brand"`, read it off
+`data.brand`.
+
+```tsx
+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`. |
+
+## Extend the list table
+
+Override or add columns, register bulk actions and filters, and set view defaults
+on the model's 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 or remove list filters */],
+  viewDefaults: {
+    columnVisibility: { created_at: false },
+    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. Receives the full `row` and the cell `value`.        |
+
+<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>
+  **The vendor product list is field-constrained.** It must use the curated fields
+  from `useProductTableQuery`. The SDK merges `link` fetches with the `+` and `-`
+  convention, never bare fields, or the list returns a 500. You never hand-write
+  the field list. The `link` declaration drives it.
+</Warning>
+
+## Fetch linked module data
+
+Declare `link` to fetch a module link alongside the entity. Its data rides on the
+`data` passed to displays and on the `row` passed to columns.
+
+```tsx
+export default defineCustomFieldsConfig({
+  model: "product",
+  link: "brand", // string | string[]
+  displays: [/* read data.brand here */],
+  list: {/* read row.brand here */},
+})
+```
+
+## Persistence
+
+<Warning>
+  **The MVP is a UI surface only.** Custom fields render, validate, and display
+  through the built-in forms, sections, and tables. There is no generic core-side
+  write path. For `product`, values submit under `additional_data` and persist
+  onto `metadata`. To store data for other models, wire your own route or
+  workflow, or use the backend
+  [Custom Fields module](/rc/resources/customization/custom-fields).
+</Warning>
+
+## Next steps
+
+<CardGroup cols={2}>
+  <Card title="Widgets" href="/references/panel-extensions/widgets">
+    Render a component in a slot on an existing page.
+  </Card>
+  <Card title="Create a new page" href="/references/panel-extensions/create-page">
+    Add a route with file-based routing and register it in the sidebar.
+  </Card>
+</CardGroup>