The complete open source platform to run your entire marketplace. Storefront, vendor panel, admin console, and integrations in one enterprise-grade platform you own.
TypeScript b2b-marketplacecomposable-commerceecommerceenterpriseheadless-commercemarketplacemedusamedusajsmulti-vendortypescript
feat(admin): let extensions add tabs to the store detail page (#1609)
Viktor Holik1985492ca707
diff --git a/apps/docs/references/panel-extensions/widgets.mdx b/apps/docs/references/panel-extensions/widgets.mdxindex f670261b5..5369942de 100644--- a/apps/docs/references/panel-extensions/widgets.mdx+++ b/apps/docs/references/panel-extensions/widgets.mdx@@ -70,6 +70,7 @@ finds it at build time. There is no manifest to edit and no route to register.| ------ | -------------------------------- | ----------------------------------------------------------------------- || `zone` | `WidgetZoneId \| WidgetZoneId[]` | The zone or zones to render in. Multiple widgets in one zone stack in registration order. || `id` | `string` (optional) | A stable id. Derived from the file path at build time when omitted. |+| `label` | `string` (optional) | The tab label, as an i18n key or a literal. Only used by [tab zones](#tabs). |## Component props@@ -93,6 +94,40 @@ const ProductDetailNote = ({ data }: { data?: HttpTypes.AdminProduct }) => (authentication and receive no `data`.</Note>+## Tabs++Some detail pages group their content into tabs. A tab zone lets a widget add a+tab of its own: the widget's `label` names the tab and its component renders as+the tab's panel. The placement decides whether the tab sits before or after the+built-in ones.++```tsx apps/admin-test/src/widgets/store-loyalty-tab.tsx+import { defineWidgetConfig } from "@mercurjs/dashboard-sdk"+import { Container, Heading } from "@medusajs/ui"+import type { SellerDTO } from "@mercurjs/types"++const StoreLoyaltyTab = ({ data }: { data?: SellerDTO }) => (+ <Container>+ <Heading level="h2">Loyalty for {data?.name}</Heading>+ </Container>+)++export const config = defineWidgetConfig({+ zone: "stores.detail.tabs.after",+ id: "loyalty",+ label: "Loyalty",+})++export default StoreLoyaltyTab+```++A widget that targets a tab zone without a `label` is not shown. `permission`+works as on any other widget and hides the tab from actors who lack it.++| Panel | Tab zone | Page |+| ----- | ------------------- | ------------------------------------------------------- |+| Admin | `stores.detail.tabs` | Store detail, next to Orders, Offers, Users and Time off. |+## Zone idsA zone id reads `<domain>.<view>.<placement>`.diff --git a/packages/admin/scripts/generate-extension-targets.ts b/packages/admin/scripts/generate-extension-targets.tsindex 74e53b643..1e7a2f4e1 100644--- a/packages/admin/scripts/generate-extension-targets.ts+++ b/packages/admin/scripts/generate-extension-targets.ts@@ -3,7 +3,8 @@* usages, so extension authors get typed target ids without a hand-maintained* list. It scans:*- * - `<WidgetZone id="…">` usages → WidgetZoneRegistry (+ placement suffixes)+ * - `<WidgetZone id="…">` usages, → WidgetZoneRegistry (+ placement suffixes)+ * `useWidgetTabs("…")` calls* - `useCoreRoutes()` `to:` literals → NavItemRegistry / NavParentRegistry* - `<FormExtensionZone model zone>` / → CustomFieldsRegistry (form/display zones)* `<DisplayExtensionZone model zone>`@@ -34,10 +35,12 @@ function walk(dir: string, out: string[] = []): string[] {function collectWidgetSlots(files: string[]): Set<string> {const slots = new Set<string>()const re = /<WidgetZone[^>]*\bid=["'`]([^"'`]+)["'`]/g+ const tabsRe = /\buseWidgetTabs\(\s*["'`]([^"'`]+)["'`]/gfor (const file of files) {const code = fs.readFileSync(file, "utf-8")let m: RegExpExecArray | nullwhile ((m = re.exec(code))) slots.add(m[1])+ while ((m = tabsRe.exec(code))) slots.add(m[1])}return slots}diff --git a/packages/admin/src/__tests__/extension-targets.spec.ts b/packages/admin/src/__tests__/extension-targets.spec.tsindex 4db7dfec9..f4ddaa01e 100644--- a/packages/admin/src/__tests__/extension-targets.spec.ts+++ b/packages/admin/src/__tests__/extension-targets.spec.ts@@ -8,7 +8,12 @@ const targets = fs.readFileSync()describe("extension targets", () => {- test.each(["topbar.before", "topbar.after"])(+ test.each([+ "topbar.before",+ "topbar.after",+ "stores.detail.tabs.before",+ "stores.detail.tabs.after",+ ])("registers the %s widget zone",(zone) => {expect(targets).toContain(`"${zone}": true`)diff --git a/packages/admin/src/extension-targets.d.ts b/packages/admin/src/extension-targets.d.tsindex ff034f991..d79b91b8d 100644--- a/packages/admin/src/extension-targets.d.ts+++ b/packages/admin/src/extension-targets.d.ts@@ -140,6 +140,8 @@ declare module "@mercurjs/dashboard-sdk" {"stores.detail.main.before": true"stores.detail.side.after": true"stores.detail.side.before": true+ "stores.detail.tabs.after": true+ "stores.detail.tabs.before": true"stores.list.after": true"stores.list.before": true"tax-regions.detail.main.after": truediff --git a/packages/admin/src/pages/stores/store-details/components/store-details.tsx b/packages/admin/src/pages/stores/store-details/components/store-details.tsxindex 4452c9c69..7d2bbe0a3 100644--- a/packages/admin/src/pages/stores/store-details/components/store-details.tsx+++ b/packages/admin/src/pages/stores/store-details/components/store-details.tsx@@ -2,7 +2,13 @@ import { ReactNode, Children, useState } from "react";import { useParams } from "react-router-dom";import { useTranslation } from "react-i18next";-import { WidgetZone, useLinkQuery, usePermissions } from "@mercurjs/dashboard-shared";+import {+ WidgetZone,+ useLinkQuery,+ usePermissions,+ useWidgetTabs,+ type WidgetTab,+} from "@mercurjs/dashboard-shared";import { TwoColumnPageSkeleton } from "../../../../components/common/skeleton";import { TwoColumnPage } from "../../../../components/layout/pages";@@ -26,9 +32,11 @@ import {StoreDetailEditButton,} from "./store-detail-header";-const TABS = ["orders", "offers", "users", "timeOff"] as const;--type Tab = (typeof TABS)[number];+type Tab = {+ id: string;+ label: string;+ content: ReactNode;+};const TabBar = ({tabs,@@ -36,18 +44,11 @@ const TabBar = ({onTabChange,}: {tabs: Tab[];- activeTab: Tab;- onTabChange: (tab: Tab) => void;+ activeTab?: string;+ onTabChange: (tab: string) => void;}) => {const { t } = useTranslation();- const labels: Record<Tab, string> = {- orders: t("orders.domain"),- users: t("users.domain"),- offers: t("offers.domain"),- timeOff: t("store.timeOff.header"),- };-return (<divrole="tablist"@@ -55,26 +56,26 @@ const TabBar = ({className="mt-1 flex flex-wrap items-center gap-x-2"data-testid="store-detail-tabs">- {tabs.map((tab) => {- const isActive = activeTab === tab;+ {tabs.map(({ id, label }) => {+ const isActive = activeTab === id;return (<button- key={tab}+ key={id}type="button"- onClick={() => onTabChange(tab)}+ onClick={() => onTabChange(id)}role="tab"aria-selected={isActive}- aria-controls={`store-detail-tab-panel-${tab}`}- id={`store-detail-tab-${tab}`}- data-testid={`store-detail-tab-${tab}`}+ aria-controls={`store-detail-tab-panel-${id}`}+ id={`store-detail-tab-${id}`}+ data-testid={`store-detail-tab-${id}`}className={`txt-compact-small-plus rounded-full px-3 py-1.5 transition-colors ${isActive? "border-ui-border-base bg-ui-bg-base shadow-borders-base text-ui-fg-base": "text-ui-fg-subtle hover:text-ui-fg-base"}`}>- {labels[tab]}+ {label}</button>);})}@@ -84,22 +85,10 @@ const TabBar = ({const Root = ({ children }: { children?: ReactNode }) => {const { id } = useParams();- const [selectedTab, setActiveTab] = useState<Tab>("orders");+ const { t } = useTranslation();+ const [selectedTab, setActiveTab] = useState("orders");const { can } = usePermissions();-- const tabs = TABS.filter((tab) => {- if (tab === "orders") {- return can("orders");- }- if (tab === "offers") {- return can("offers");- }- if (tab === "users") {- return can("members");- }- return true;- });- const activeTab = tabs.includes(selectedTab) ? selectedTab : tabs[0];+ const customTabs = useWidgetTabs("stores.detail.tabs");const query = useLinkQuery("seller", STORE_DETAIL_FIELDS);const { seller, isLoading, isError, error } = useSeller(id!, query);@@ -120,6 +109,50 @@ const Root = ({ children }: { children?: ReactNode }) => {);}+ const toTab = ({ id, label, Component }: WidgetTab): Tab => ({+ id,+ label: t(label, { defaultValue: label }),+ content: <Component data={seller} />,+ });++ const tabs: Tab[] = [+ ...customTabs.before.map(toTab),+ ...(can("orders")+ ? [+ {+ id: "orders",+ label: t("orders.domain"),+ content: <StoreOrdersSection sellerId={seller.id} />,+ },+ ]+ : []),+ ...(can("offers")+ ? [+ {+ id: "offers",+ label: t("offers.domain"),+ content: <StoreOffersSection sellerId={seller.id} />,+ },+ ]+ : []),+ ...(can("members")+ ? [+ {+ id: "users",+ label: t("users.domain"),+ content: <StoreMembersSection sellerId={seller.id} />,+ },+ ]+ : []),+ {+ id: "timeOff",+ label: t("store.timeOff.header"),+ content: <StoreConfigurationSection seller={seller} />,+ },+ ...customTabs.after.map(toTab),+ ];+ const activeTab = tabs.find((tab) => tab.id === selectedTab) ?? tabs[0];+return (<TwoColumnPage data={seller} hasOutlet data-testid="store-detail-page"><TwoColumnPage.Main>@@ -130,43 +163,15 @@ const Root = ({ children }: { children?: ReactNode }) => {<StoreRequestSection seller={seller} />)}<StoreGeneralSection seller={seller} />- <TabBar tabs={tabs} activeTab={activeTab} onTabChange={setActiveTab} />- {activeTab === "orders" && (- <div- role="tabpanel"- id="store-detail-tab-panel-orders"- aria-labelledby="store-detail-tab-orders"- >- <StoreOrdersSection sellerId={seller.id} />- </div>- )}- {activeTab === "users" && (- <div- role="tabpanel"- id="store-detail-tab-panel-users"- aria-labelledby="store-detail-tab-users"- >- <StoreMembersSection sellerId={seller.id} />- </div>- )}- {activeTab === "offers" && (- <div- role="tabpanel"- id="store-detail-tab-panel-offers"- aria-labelledby="store-detail-tab-offers"- >- <StoreOffersSection sellerId={seller.id} />- </div>- )}- {activeTab === "timeOff" && (- <div- role="tabpanel"- id="store-detail-tab-panel-timeOff"- aria-labelledby="store-detail-tab-timeOff"- >- <StoreConfigurationSection seller={seller} />- </div>- )}+ <TabBar tabs={tabs} activeTab={activeTab.id} onTabChange={setActiveTab} />+ <div+ key={activeTab.id}+ role="tabpanel"+ id={`store-detail-tab-panel-${activeTab.id}`}+ aria-labelledby={`store-detail-tab-${activeTab.id}`}+ >+ {activeTab.content}+ </div></WidgetZone></TwoColumnPage.Main><TwoColumnPage.Sidebar>diff --git a/packages/dashboard-sdk/src/__tests__/widgets.spec.ts b/packages/dashboard-sdk/src/__tests__/widgets.spec.tsnew file mode 100644index 000000000..2745c1b5e--- /dev/null+++ b/packages/dashboard-sdk/src/__tests__/widgets.spec.ts@@ -0,0 +1,51 @@+import fs from "fs"+import os from "os"+import path from "path"+import { afterEach, describe, expect, test } from "vitest"+import { collectWidgets } from "../widgets"++const tmpDirs: string[] = []++const writeWidget = (source: string) => {+ const root = fs.mkdtempSync(path.join(os.tmpdir(), "mercur-widgets-"))+ tmpDirs.push(root)+ const widgetsDir = path.join(root, "src", "widgets")+ fs.mkdirSync(widgetsDir, { recursive: true })+ fs.writeFileSync(path.join(widgetsDir, "widget.tsx"), source)+ return path.join(root, "src")+}++afterEach(() => {+ for (const dir of tmpDirs.splice(0)) {+ fs.rmSync(dir, { recursive: true, force: true })+ }+})++describe("collectWidgets", () => {+ test("carries a tab widget's label into the generated entry", () => {+ const srcDir = writeWidget(`+ export const config = defineWidgetConfig({+ zone: "stores.detail.tabs.after",+ id: "loyalty",+ label: "Loyalty",+ })+ export default () => null+ `)++ const { entries } = collectWidgets(srcDir)++ expect(entries).toHaveLength(1)+ expect(entries[0]).toContain(`zone: ["stores.detail.tabs.after"]`)+ expect(entries[0]).toContain(`widgetId: "loyalty"`)+ expect(entries[0]).toContain(`label: "Loyalty"`)+ })++ test("omits the label for a widget that declares none", () => {+ const srcDir = writeWidget(`+ export const config = defineWidgetConfig({ zone: "stores.detail.main.after" })+ export default () => null+ `)++ expect(collectWidgets(srcDir).entries[0]).not.toContain("label")+ })+})diff --git a/packages/dashboard-sdk/src/config/types.ts b/packages/dashboard-sdk/src/config/types.tsindex 42dc5e1a3..f1a1c9d8c 100644--- a/packages/dashboard-sdk/src/config/types.ts+++ b/packages/dashboard-sdk/src/config/types.ts@@ -45,6 +45,11 @@ export interface WidgetConfig {* one is enough.*/permission?: Permission | Permission[]+ /**+ * i18n key or literal naming the tab. Required for a `*.tabs.*` zone, where+ * the widget renders as a tab's panel; ignored elsewhere.+ */+ label?: string}/** Override for a single built-in navigation item. */diff --git a/packages/dashboard-sdk/src/widgets.ts b/packages/dashboard-sdk/src/widgets.tsindex 2e3f1b77a..01a43db5d 100644--- a/packages/dashboard-sdk/src/widgets.ts+++ b/packages/dashboard-sdk/src/widgets.ts@@ -23,6 +23,7 @@ import type { BuiltMercurConfig } from "./types"type WidgetInfo = {zones: string[]id?: string+ label?: stringpermissions: string[]}@@ -45,6 +46,7 @@ function readWidgetConfig(properties: any[]): WidgetInfo | null {const zones: string[] = []const permissions: string[] = []let id: string | undefined+ let label: string | undefinedfor (const prop of properties) {if (!isObjectProperty(prop)) continue@@ -57,10 +59,13 @@ function readWidgetConfig(properties: any[]): WidgetInfo | null {if (isIdentifier(prop.key, { name: "id" }) && isStringLiteral(prop.value)) {id = prop.value.value}+ if (isIdentifier(prop.key, { name: "label" }) && isStringLiteral(prop.value)) {+ label = prop.value.value+ }}if (zones.length === 0) return null- return { zones, id, permissions }+ return { zones, id, label, permissions }}function getConfigProperties(node: any): any[] | null {@@ -144,7 +149,7 @@ function parseWidgetFile(import: `import ${name} from "${importPath}"`,entry: ` { Component: ${name}, zone: ${zonesLiteral}, widgetId: ${JSON.stringify(id- )}${+ )}${info.label ? `, label: ${JSON.stringify(info.label)}` : ""}${info.permissions.length? `, permission: ${JSON.stringify(info.permissions)}`: ""diff --git a/packages/dashboard-shared/src/extensions/index.ts b/packages/dashboard-shared/src/extensions/index.tsindex 7860c28aa..bb9415ef0 100644--- a/packages/dashboard-shared/src/extensions/index.ts+++ b/packages/dashboard-shared/src/extensions/index.ts@@ -16,6 +16,7 @@ export {type ExtensionProviderProps,} from "./context"export { WidgetZone, type WidgetZoneProps } from "./widget-zone"+export { useWidgetTabs, type WidgetTab, type WidgetTabs } from "./use-widget-tabs"export { applyNavOverrides, type CoreNavItem } from "./nav"export {FormExtensionZone,diff --git a/packages/dashboard-shared/src/extensions/registry.spec.ts b/packages/dashboard-shared/src/extensions/registry.spec.tsindex 495ef842a..87c0d25d7 100644--- a/packages/dashboard-shared/src/extensions/registry.spec.ts+++ b/packages/dashboard-shared/src/extensions/registry.spec.ts@@ -10,6 +10,29 @@ const openDispute = (entity: unknown) =>: undefineddescribe("ExtensionRegistry", () => {+ test("keeps a tab widget's label and placement", () => {+ const Component = () => null+ const registry = new ExtensionRegistry({+ widgets: {+ widgets: [+ {+ Component,+ zone: ["stores.detail.tabs.after"],+ widgetId: "loyalty",+ label: "Loyalty",+ },+ { Component, zone: ["stores.detail.tabs.before"], widgetId: "kyc" },+ ],+ },+ })++ const tabs = registry.getWidgets("stores.detail.tabs")+ expect(tabs.after).toEqual([+ { Component, widgetId: "loyalty", label: "Loyalty", permission: undefined },+ ])+ expect(tabs.before.map((widget) => widget.label)).toEqual([undefined])+ })+test("action locks return undefined without configs", () => {const registry = new ExtensionRegistry()expect(registry.getActionLock("order", "return", { id: "o" })).toBeUndefined()diff --git a/packages/dashboard-shared/src/extensions/registry.ts b/packages/dashboard-shared/src/extensions/registry.tsindex 2ad8f36b5..0230e8779 100644--- a/packages/dashboard-shared/src/extensions/registry.ts+++ b/packages/dashboard-shared/src/extensions/registry.ts@@ -17,6 +17,7 @@ export type Widget = {zone: string[]widgetId: stringpermission?: Permission[]+ label?: string}export type WidgetModule = { widgets?: Widget[] }@@ -33,6 +34,7 @@ type ResolvedWidget = {Component: Widget["Component"]widgetId: stringpermission?: Permission[]+ label?: string}export type ZoneWidgets = {@@ -95,6 +97,7 @@ export class ExtensionRegistry {Component: widget.Component,widgetId: widget.widgetId,permission: widget.permission,+ label: widget.label,}entry[placement].push(resolved)}diff --git a/packages/dashboard-shared/src/extensions/use-widget-tabs.ts b/packages/dashboard-shared/src/extensions/use-widget-tabs.tsnew file mode 100644index 000000000..5b21aaca6--- /dev/null+++ b/packages/dashboard-shared/src/extensions/use-widget-tabs.ts@@ -0,0 +1,35 @@+import { useContext } from "react"+import { isPermitted } from "../permissions/permission-check"+import { PermissionsContext } from "../permissions/permissions-context"+import { useExtension } from "./context"+import type { Widget } from "./registry"++export type WidgetTab = {+ id: string+ label: string+ Component: Widget["Component"]+}++export type WidgetTabs = {+ before: WidgetTab[]+ after: WidgetTab[]+}++/**+ * Tab-bar host. Returns the widgets targeting a `*.tabs` slot as tabs to place+ * `before` and `after` the built-in ones. A widget without a `label` cannot be+ * shown as a tab and is left out.+ */+export const useWidgetTabs = (id: string): WidgetTabs => {+ const widgets = useExtension().getWidgets(id)+ const permissions = useContext(PermissionsContext)++ const toTabs = (placement: "before" | "after"): WidgetTab[] =>+ widgets[placement].flatMap(({ Component, widgetId, label, permission }) =>+ label && isPermitted(permissions, permission)+ ? [{ id: widgetId, label, Component }]+ : []+ )++ return { before: toTabs("before"), after: toTabs("after") }+}diff --git a/packages/vendor/scripts/generate-extension-targets.ts b/packages/vendor/scripts/generate-extension-targets.tsindex 74e53b643..1e7a2f4e1 100644--- a/packages/vendor/scripts/generate-extension-targets.ts+++ b/packages/vendor/scripts/generate-extension-targets.ts@@ -3,7 +3,8 @@* usages, so extension authors get typed target ids without a hand-maintained* list. It scans:*- * - `<WidgetZone id="…">` usages → WidgetZoneRegistry (+ placement suffixes)+ * - `<WidgetZone id="…">` usages, → WidgetZoneRegistry (+ placement suffixes)+ * `useWidgetTabs("…")` calls* - `useCoreRoutes()` `to:` literals → NavItemRegistry / NavParentRegistry* - `<FormExtensionZone model zone>` / → CustomFieldsRegistry (form/display zones)* `<DisplayExtensionZone model zone>`@@ -34,10 +35,12 @@ function walk(dir: string, out: string[] = []): string[] {function collectWidgetSlots(files: string[]): Set<string> {const slots = new Set<string>()const re = /<WidgetZone[^>]*\bid=["'`]([^"'`]+)["'`]/g+ const tabsRe = /\buseWidgetTabs\(\s*["'`]([^"'`]+)["'`]/gfor (const file of files) {const code = fs.readFileSync(file, "utf-8")let m: RegExpExecArray | nullwhile ((m = re.exec(code))) slots.add(m[1])+ while ((m = tabsRe.exec(code))) slots.add(m[1])}return slots}