@vendure/dashboard 3.6.0-minor-202511061555 → 3.6.0-minor-202512161252

package/src/lib/framework/layout-engine/action-bar-item-wrapper.tsx

@@ -0,0 +1,185 @@
+import { CopyableText } from '@/vdb/components/shared/copyable-text.js';
+import { PermissionGuard } from '@/vdb/components/shared/permission-guard.js';
+import { Popover, PopoverContent, PopoverTrigger } from '@/vdb/components/ui/popover.js';
+import { usePage } from '@/vdb/hooks/use-page.js';
+import { useUserSettings } from '@/vdb/hooks/use-user-settings.js';
+import { cn } from '@/vdb/lib/utils.js';
+import React, { useEffect, useState } from 'react';
+import { DevModeButton } from './dev-mode-button.js';
+
+// Singleton state for hover tracking across all action bar items
+let globalHoveredActionBarItemId: string | null = null;
+const actionBarHoverListeners: Set<(id: string | null) => void> = new Set();
+
+const setGlobalHoveredActionBarItemId = (id: string | null) => {
+    globalHoveredActionBarItemId = id;
+    actionBarHoverListeners.forEach(listener => listener(id));
+};
+
+/**
+ * Internal component that renders the dev-mode wrapper with hover highlight and popover.
+ * Shared between ActionBarItem and ActionBarItemWrapper to eliminate duplication.
+ */
+function DevModeActionBarWrapper({
+    children,
+    itemId,
+}: Readonly<{
+    children: React.ReactNode;
+    itemId: string;
+}>) {
+    const page = usePage();
+    const [isPopoverOpen, setIsPopoverOpen] = useState(false);
+    const [hoveredId, setHoveredId] = useState<string | null>(globalHoveredActionBarItemId);
+
+    // Generate a unique tracking ID that includes the page context
+    const trackingId = `${page.pageId ?? 'unknown'}-actionbar-${itemId}`;
+    const isHovered = hoveredId === trackingId;
+
+    // Subscribe to global hover changes
+    useEffect(() => {
+        const listener = (newHoveredId: string | null) => {
+            setHoveredId(newHoveredId);
+        };
+        actionBarHoverListeners.add(listener);
+        return () => {
+            actionBarHoverListeners.delete(listener);
+        };
+    }, []);
+
+    const handleMouseEnter = () => {
+        setGlobalHoveredActionBarItemId(trackingId);
+    };
+
+    const handleMouseLeave = () => {
+        setGlobalHoveredActionBarItemId(null);
+    };
+
+    return (
+        <div
+            className={cn(
+                'ring-1 ring-transparent rounded transition-all delay-50 relative',
+                isHovered || isPopoverOpen ? 'ring-dev-mode ring-offset-1 ring-offset-background' : '',
+            )}
+            onMouseEnter={handleMouseEnter}
+            onMouseLeave={handleMouseLeave}
+        >
+            <div
+                className={cn(
+                    'absolute -top-1 -right-1 transition-all delay-50 z-10',
+                    isHovered || isPopoverOpen ? 'visible' : 'invisible',
+                )}
+            >
+                <Popover open={isPopoverOpen} onOpenChange={setIsPopoverOpen}>
+                    <PopoverTrigger asChild>
+                        <DevModeButton className="h-5 w-5 top-0 -start-4" />
+                    </PopoverTrigger>
+                    <PopoverContent className="w-40 p-2">
+                        <div className="space-y-1.5">
+                            {page.pageId && (
+                                <div className="text-xs">
+                                    <div className="text-muted-foreground mb-0.5">pageId</div>
+                                    <CopyableText text={page.pageId} />
+                                </div>
+                            )}
+                            <div className="text-xs">
+                                <div className="text-muted-foreground mb-0.5">itemId</div>
+                                <CopyableText text={itemId} />
+                            </div>
+                        </div>
+                    </PopoverContent>
+                </Popover>
+            </div>
+            {children}
+        </div>
+    );
+}
+
+/**
+ * @description
+ * Props for the ActionBarItem component.
+ *
+ * @docsCategory page-layout
+ * @docsPage PageActionBar
+ * @since 3.5.2
+ */
+export interface ActionBarItemProps {
+    /**
+     * @description
+     * The content of the action bar item, typically a Button component.
+     */
+    children: React.ReactNode;
+    /**
+     * @description
+     * A unique identifier for this action bar item. This ID is used by extensions
+     * to position their items relative to this one via `position.itemId`.
+     *
+     * Note: Extensions should use this exact `itemId` value in their `position.itemId`
+     * field to target this item.
+     */
+    itemId: string;
+    /**
+     * @description
+     * If provided, the logged-in user must have one or more of the specified
+     * permissions in order for the item to render.
+     */
+    requiresPermission?: string | string[];
+}
+
+/**
+ * @description
+ * A component for wrapping action bar items with a unique ID. This should be used inside
+ * the {@link PageActionBarRight} component. Each item is given an `itemId` which allows
+ * extensions to position their items relative to it using `position.itemId`.
+ *
+ * In developer mode, hovering over the item will show a popover with the `pageId` and `itemId`,
+ * making it easy to discover the correct IDs for extension positioning.
+ *
+ * @example
+ * ```tsx
+ * <PageActionBarRight>
+ *     <ActionBarItem itemId="save-button" requiresPermission={['UpdateProduct']}>
+ *         <Button type="submit">Save</Button>
+ *     </ActionBarItem>
+ * </PageActionBarRight>
+ * ```
+ *
+ * @docsCategory page-layout
+ * @docsPage PageActionBar
+ * @since 3.5.2
+ */
+export function ActionBarItem({ children, itemId, requiresPermission }: Readonly<ActionBarItemProps>) {
+    const { settings } = useUserSettings();
+
+    const content = requiresPermission ? (
+        <PermissionGuard requires={requiresPermission}>{children}</PermissionGuard>
+    ) : (
+        children
+    );
+
+    if (settings.devMode) {
+        return <DevModeActionBarWrapper itemId={itemId}>{content}</DevModeActionBarWrapper>;
+    }
+    return <>{content}</>;
+}
+
+/**
+ * Internal wrapper component used by PageActionBarRight to wrap extension items
+ * with dev-mode location information. Unlike ActionBarItem, this does not handle
+ * permissions (those are handled by PageActionBarItem).
+ *
+ * @internal
+ */
+export function ActionBarItemWrapper({
+    children,
+    itemId,
+}: Readonly<{
+    children: React.ReactNode;
+    itemId: string;
+}>) {
+    const { settings } = useUserSettings();
+
+    if (settings.devMode) {
+        return <DevModeActionBarWrapper itemId={itemId}>{children}</DevModeActionBarWrapper>;
+    }
+    return <>{children}</>;
+}

package/src/lib/framework/layout-engine/dev-mode-button.tsx

@@ -1,24 +1,26 @@
 import { Button } from '@/vdb/components/ui/button.js';
 import { cn } from '@/vdb/lib/utils.js';
-import { CodeXmlIcon } from 'lucide-react';
+import { Locate } from 'lucide-react';
 import { forwardRef } from 'react';
 
 export const DevModeButton = forwardRef<HTMLButtonElement, React.ComponentProps<typeof Button>>(
     (props, ref) => {
         const { className, ...rest } = props;
         return (
-            <Button
-                ref={ref}
-                variant="secondary"
-                size="icon"
-                className={cn(
-                    'h-8 w-8 rounded-full bg-dev-mode/20 hover:bg-dev-mode/30 border border-dev-mode/20 shadow-sm',
-                    className,
-                )}
-                {...rest}
-            >
-                <CodeXmlIcon className="text-dev-mode w-4 h-4" />
-            </Button>
+            <div className="relative">
+                <Button
+                    ref={ref}
+                    variant="secondary"
+                    size="icon"
+                    className={cn(
+                        'h-6 w-6 absolute z-50 rounded-md bg-background text-dev-mode/70 hover:bg-background hover:text-dev-mode border border-dev-mode shadow-sm',
+                        className,
+                    )}
+                    {...rest}
+                >
+                    <Locate className="w-4 h-4" />
+                </Button>
+            </div>
         );
     },
 );

package/src/lib/framework/layout-engine/location-wrapper.tsx

@@ -86,7 +86,9 @@ export function LocationWrapper({ children, identifier }: Readonly<LocationWrapp
                 >
                     <Popover open={isPopoverOpen} onOpenChange={setIsPopoverOpen}>
                         <PopoverTrigger asChild>
-                            <DevModeButton />
+                            <DevModeButton
+                                className={isPageWrapper ? '-top-8 -end-1 border-2' : '-top-4 -end-4'}
+                            />
                         </PopoverTrigger>
                         <PopoverContent className="w-48 p-3">
                             <div className="space-y-2">

package/src/lib/framework/layout-engine/page-layout.spec.tsx

@@ -0,0 +1,138 @@
+import React from 'react';
+import { renderToStaticMarkup } from 'react-dom/server';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { PageBlock, PageLayout } from './page-layout.js';
+import { registerDashboardPageBlock } from './layout-extensions.js';
+import { PageContext } from './page-provider.js';
+import { globalRegistry } from '../registry/global-registry.js';
+import { UserSettingsContext, type UserSettingsContextType } from '../../providers/user-settings.js';
+
+const useMediaQueryMock = vi.hoisted(() => vi.fn());
+const useCopyToClipboardMock = vi.hoisted(() => vi.fn(() => [null, vi.fn()]));
+
+vi.mock('@uidotdev/usehooks', () => ({
+    useMediaQuery: useMediaQueryMock,
+    useCopyToClipboard: useCopyToClipboardMock,
+}));
+
+function registerBlock(
+    id: string,
+    order: 'before' | 'after' | 'replace',
+    pageId = 'customer-list',
+): void {
+    registerDashboardPageBlock({
+        id,
+        title: id,
+        location: {
+            pageId,
+            column: 'main',
+            position: { blockId: 'list-table', order },
+        },
+        component: ({ context }) => <div data-testid={`page-block-${id}`}>{context.pageId}</div>,
+});
+}
+
+function renderPageLayout(children: React.ReactNode, { isDesktop = true } = {}) {
+    useMediaQueryMock.mockReturnValue(isDesktop);
+    const noop = () => undefined;
+    const contextValue = {
+        settings: {
+            displayLanguage: 'en',
+            contentLanguage: 'en',
+            theme: 'system',
+            displayUiExtensionPoints: false,
+            mainNavExpanded: true,
+            activeChannelId: '',
+            devMode: false,
+            hasSeenOnboarding: false,
+            tableSettings: {},
+        },
+        settingsStoreIsAvailable: true,
+        setDisplayLanguage: noop,
+        setDisplayLocale: noop,
+        setContentLanguage: noop,
+        setTheme: noop,
+        setDisplayUiExtensionPoints: noop,
+        setMainNavExpanded: noop,
+        setActiveChannelId: noop,
+        setDevMode: noop,
+        setHasSeenOnboarding: noop,
+        setTableSettings: () => undefined,
+        setWidgetLayout: noop,
+    } as UserSettingsContextType;
+
+    return renderToStaticMarkup(
+        <UserSettingsContext.Provider value={contextValue}>
+            <PageContext.Provider value={{ pageId: 'customer-list' }}>
+                <PageLayout>{children}</PageLayout>
+            </PageContext.Provider>
+        </UserSettingsContext.Provider>,
+    );
+}
+
+function getRenderedBlockIds(markup: string) {
+    return Array.from(markup.matchAll(/data-testid="(page-block-[^"]+)"/g)).map(match => match[1]);
+}
+
+describe('PageLayout', () => {
+    beforeEach(() => {
+        useMediaQueryMock.mockReset();
+        useCopyToClipboardMock.mockReset();
+        useCopyToClipboardMock.mockReturnValue([null, vi.fn()]);
+        const pageBlockRegistry = globalRegistry.get('dashboardPageBlockRegistry');
+        pageBlockRegistry.clear();
+    });
+
+    it('renders multiple before/after extension blocks in registration order', () => {
+        registerBlock('before-1', 'before');
+        registerBlock('before-2', 'before');
+        registerBlock('after-1', 'after');
+
+        const markup = renderPageLayout(
+            <PageBlock column="main" blockId="list-table">
+        <div data-testid="page-block-original">original</div>
+            </PageBlock>,
+        { isDesktop: true },
+    );
+
+        expect(getRenderedBlockIds(markup)).toEqual([
+            'page-block-before-1',
+            'page-block-before-2',
+            'page-block-original',
+            'page-block-after-1',
+        ]);
+    });
+
+    it('replaces original block when replacement extensions are registered', () => {
+        registerBlock('replacement-1', 'replace');
+        registerBlock('replacement-2', 'replace');
+
+        const markup = renderPageLayout(
+            <PageBlock column="main" blockId="list-table">
+        <div data-testid="page-block-original">original</div>
+            </PageBlock>,
+        { isDesktop: true },
+    );
+
+        expect(getRenderedBlockIds(markup)).toEqual(['page-block-replacement-1', 'page-block-replacement-2']);
+    });
+
+    it('renders extension blocks in mobile layout', () => {
+        registerBlock('before-mobile', 'before');
+        registerBlock('after-mobile', 'after');
+
+        const markup = renderPageLayout(
+            <PageBlock column="main" blockId="list-table">
+        <div data-testid="page-block-original">original</div>
+            </PageBlock>,
+        { isDesktop: false },
+    );
+
+        expect(getRenderedBlockIds(markup)).toEqual([
+            'page-block-before-mobile',
+            'page-block-original',
+            'page-block-after-mobile',
+        ]);
+    });
+});