Skip to content

The complete open source platform to run your entire marketplace. Storefront, vendor panel, admin console, and integrations in one enterprise-grade platform you own.

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.mdx
index 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 ids
A zone id reads `<domain>.<view>.<placement>`.
diff --git a/packages/admin/scripts/generate-extension-targets.ts b/packages/admin/scripts/generate-extension-targets.ts
index 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*["'`]([^"'`]+)["'`]/g
for (const file of files) {
const code = fs.readFileSync(file, "utf-8")
let m: RegExpExecArray | null
while ((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.ts
index 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.ts
index 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": true
diff --git a/packages/admin/src/pages/stores/store-details/components/store-details.tsx b/packages/admin/src/pages/stores/store-details/components/store-details.tsx
index 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 (
<div
role="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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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?: string
permissions: string[]
}
@@ -45,6 +46,7 @@ function readWidgetConfig(properties: any[]): WidgetInfo | null {
const zones: string[] = []
const permissions: string[] = []
let id: string | undefined
+ let label: string | undefined
for (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.ts
index 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.ts
index 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) =>
: undefined
describe("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.ts
index 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: string
permission?: Permission[]
+ label?: string
}
export type WidgetModule = { widgets?: Widget[] }
@@ -33,6 +34,7 @@ type ResolvedWidget = {
Component: Widget["Component"]
widgetId: string
permission?: 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.ts
new file mode 100644
index 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.ts
index 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*["'`]([^"'`]+)["'`]/g
for (const file of files) {
const code = fs.readFileSync(file, "utf-8")
let m: RegExpExecArray | null
while ((m = re.exec(code))) slots.add(m[1])
+ while ((m = tabsRe.exec(code))) slots.add(m[1])
}
return slots
}