@mercurjs/docs 2.3.7 → 2.3.8-canary.1

package/content/platform/offer/reference/workflows.mdx

@@ -12,7 +12,7 @@ This reference lists the workflows for the Offer domain. Import them from
 | Workflow | Input | Purpose |
 | --- | --- | --- |
 | `createOffersWorkflow` | `{ offers[], additional_data? }` | Create offers with prices, inventory, and links |
-| `updateOffersWorkflow` | `{ offers[], additional_data? }` | Update offer rows and rewrite their price ladders |
+| `updateOffersWorkflow` | `{ offers[], updated_by?, additional_data? }` | Update offer rows and rewrite their price ladders |
 | `deleteOffersWorkflow` | `{ ids[], additional_data? }` | Delete offers |
 | `batchOfferInventoryItemsWorkflow` | `{ offer_id, create?, update?, delete?, additional_data? }` | Add, update, and detach an offer's inventory-item links |
 
@@ -24,9 +24,37 @@ Each workflow exposes hooks so you can extend it without forking:
 | --- | --- |
 | `createOffersWorkflow` | `validate`, `offersCreated` |
 | `updateOffersWorkflow` | `validate`, `offersUpdated` |
+| `upsertOfferPricesWorkflow` | `offerPricesUpserted` |
 | `deleteOffersWorkflow` | `offersDeleted` |
 | `batchOfferInventoryItemsWorkflow` | `validate`, `offerInventoryItemsBatched` |
 
+### Hook payloads
+
+| Hook | Payload |
+| --- | --- |
+| `offersCreated` | `{ offers: OfferDTO[], additional_data? }` — each offer carries `created_by` and its `prices` |
+| `offersUpdated` | `{ offers: OfferDTO[], previous_offers: OfferDTO[], updated_by?, additional_data? }` — `previous_offers` is the row state before the write |
+| `offerPricesUpserted` | `{ offers: Array<{ offer_id, previous_prices: OfferPriceDTO[], prices: OfferPriceDTO[], created: string[], updated: string[], deleted: string[] }>, updated_by: string \| null }` |
+| `offersDeleted` | `{ ids: string[], offers: OfferDTO[], additional_data? }` — `offers` is a snapshot taken before deletion, including `prices` |
+
+`updated_by` is the authenticated actor id. Vendor routes fill it from the session; pass it yourself when running `updateOffersWorkflow` or `upsertOfferPricesWorkflow` directly.
+
+In `offerPricesUpserted`, `previous_prices` and `prices` are the offer's ladder before and after the write (`amount`, `currency_code`, `min_quantity`, `max_quantity`, `price_rules`). `created` and `deleted` hold the price ids added and removed; `updated` holds the ids rewritten in place whose amount, quantity bounds, or rules actually changed — an unchanged row resent with its id is not listed. The hook also fires when `updateOffersWorkflow` runs the price upsert for you, so a single handler on `upsertOfferPricesWorkflow` covers both entry points. Prices are hard-deleted and Medusa's pricing events carry ids only, so these payloads (and the `offersDeleted` snapshot) are the only place the previous values can be read.
+
+```ts
+import { upsertOfferPricesWorkflow } from "@mercurjs/core/workflows"
+import { StepResponse } from "@medusajs/framework/workflows-sdk"
+
+upsertOfferPricesWorkflow.hooks.offerPricesUpserted(
+  async ({ offers, updated_by }, { container }) => {
+    for (const { offer_id, previous_prices, prices, updated } of offers) {
+      // record a price-history entry for every id in `updated`
+    }
+    return new StepResponse(undefined)
+  }
+)
+```
+
 ## Behavior notes
 
 - **Prices** are written on the master variant's shared price set, each row scoped by an `offer_id` `PriceRule`. On update, supplying `prices` replaces the ladder with the given rows; omitting it leaves prices untouched.

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

@@ -134,6 +134,60 @@ Each field is a `CustomFormField`.
   onto the product's `metadata`.
 </Warning>
 
+## Customize the onboarding wizard
+
+The vendor onboarding wizard is the `onboarding` form zone of the `seller` model. Each step is a `tab`. Use the same `forms` entries to add fields to a step, add a step, remove a step, or reorder the steps.
+
+```tsx apps/vendor/src/custom-fields/seller.tsx
+import { defineCustomFieldsConfig } from "@mercurjs/dashboard-sdk"
+import { createFormHelper } from "@mercurjs/dashboard-shared"
+
+const form = createFormHelper()
+
+export default defineCustomFieldsConfig({
+  model: "seller",
+  forms: [
+    // Add fields to a built-in step
+    { zone: "onboarding", tab: "address", fields: { region_note: form.define({ validation: form.string().optional() }) } },
+    // An unknown tab becomes a new step
+    {
+      zone: "onboarding",
+      tab: "documents",
+      label: "Documents",
+      rank: 25,
+      optional: true,
+      fields: {
+        vat_document_url: form.define({ validation: form.string().url(), label: "VAT document URL" }),
+      },
+    },
+    // Remove a built-in step
+    { zone: "onboarding", tab: "company", disabled: true },
+  ],
+})
+```
+
+| Option     | Type      | Description                                                                                       |
+| ---------- | --------- | ------------------------------------------------------------------------------------------------- |
+| `label`    | `string`  | Step heading. Set it on every new step.                                                           |
+| `rank`     | `number`  | Sort position. New steps without a rank go last. Also reorders a built-in step.                   |
+| `optional` | `boolean` | Shows a **Skip** button. Set `false` on a built-in step to hide its Skip button.                  |
+| `disabled` | `true`    | Removes a built-in step. Takes no `fields`. The `store` step can't be removed.                    |
+
+The built-in steps and their defaults:
+
+| Step      | `rank` | `optional` |
+| --------- | ------ | ---------- |
+| `store`   | 10     | `false`    |
+| `address` | 20     | `true`     |
+| `company` | 30     | `true`     |
+| `payment` | 40     | `true`     |
+
+The last step's button reads **Finish** and creates the seller. Values from every step's custom fields are merged into one `additional_data` object on `POST /vendor/sellers`, which reaches the `sellerAccountCreated` hook of `createSellerAccountWorkflow`. A skipped step contributes nothing, even if its fields are required.
+
+<Note>
+  Always set `tab` on an onboarding entry. An entry without a `tab` renders its fields on every step.
+</Note>
+
 ## Extend detail sections
 
 Add, replace, or remove fields on a detail section, and add actions to its
@@ -238,6 +292,36 @@ built-in ones.
   the field list. The `link` declaration drives it.
 </Warning>
 
+## Combine configs from plugins and your app
+
+Every config for a model applies in order: installed plugins first, then your
+app's `src/custom-fields/` files. A later config sees everything earlier configs
+added, not only the built-ins, so your app can change what a plugin contributed.
+
+| Contribution          | Matched by | A later config with the same id/key                                        |
+| --------------------- | ---------- | -------------------------------------------------------------------------- |
+| `list.columns`        | `id`       | Replaces the column in place. Hide it with `columnVisibility: { id: false }`. |
+| `list.filters`        | `key`      | Replaces the filter in place, or drops it with `remove: true`.              |
+| `displays[].fields`   | `id`       | Replaces the field in place, or drops it with `component: null`.            |
+| `forms[].fields`      | field name | Replaces the field, including its `zone` and `tab`.                         |
+| `columnVisibility`    | column id  | Overrides the earlier value for that column.                                |
+| `columnOrder`         | n/a        | Replaces the earlier order.                                                 |
+
+`link`, `bulkActions`, display `actions`, `activity`, and `actionLocks` add up
+across configs.
+
+```tsx
+// src/custom-fields/product-brand.tsx: rework the plugin's "brand" column
+export default defineCustomFieldsConfig({
+  model: "product",
+  link: "brand",
+  list: {
+    columns: [{ id: "brand", header: "Maker", component: ({ row }) => row.brand?.name }],
+    filters: [{ key: "brand_id", remove: true }],
+  },
+})
+```
+
 ## Fetch linked module data
 
 Declare `link` to fetch a module link alongside the entity. Its data rides on the

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

@@ -12,6 +12,10 @@ The vendor store-setup and onboarding surface is a widget zone, `seller.setup`,
   **Three layers, one flow.** The panel, a `seller.setup` widget, renders and collects. The vendor seller route carries the value through `additional_data` with no core schema change. A `sellersUpdated` workflow hook persists it. Each layer is additive: nothing built-in is replaced.
 </Info>
 
+<Tip>
+  To change the onboarding wizard itself (fields on any step, new steps, removed or reordered steps), use `forms` entries with `zone: "onboarding"`. See [Customize the onboarding wizard](/references/panel-extensions/custom-fields#customize-the-onboarding-wizard).
+</Tip>
+
 ## What you build
 
 A "Tax ID" prompt on the vendor store-setup surface. The vendor types a VAT number. It rides `additional_data` to `POST /vendor/sellers/:id`, and a workflow hook stores it durably through the [Custom Fields module](/rc/resources/customization/custom-fields).

package/package.json

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