@wilshop/dashboard 3.5.2

package/src/lib/framework/layout-engine/custom-form-page.stories.tsx

@@ -0,0 +1,344 @@
+import { FormFieldWrapper } from '@/vdb/components/shared/form-field-wrapper.js';
+import { Button } from '@/vdb/components/ui/button.js';
+import { Input } from '@/vdb/components/ui/input.js';
+import { Textarea } from '@/vdb/components/ui/textarea.js';
+import { graphql } from '@/vdb/graphql/graphql.js';
+import { Trans } from '@lingui/react/macro';
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { RouterContextProvider } from '@tanstack/react-router';
+import { useForm } from 'react-hook-form';
+import { createDemoRoute } from '../../../../.storybook/providers.js';
+import {
+    DetailFormGrid,
+    Page,
+    PageActionBar,
+    PageActionBarRight,
+    PageBlock,
+    PageLayout,
+    PageTitle,
+} from './page-layout.js';
+
+// Sample GraphQL query for a product detail
+const productFragment = graphql(`
+    fragment ProductDetailForForm on Product {
+        id
+        createdAt
+        updatedAt
+        name
+        slug
+        description
+        enabled
+    }
+`);
+
+const productQuery = graphql(
+    `
+        query ProductForCustomForm($id: ID!) {
+            product(id: $id) {
+                ...ProductDetailForForm
+            }
+        }
+    `,
+    [productFragment],
+);
+
+interface ProductFormData {
+    name: string;
+    slug: string;
+    description: string;
+    enabled: boolean;
+}
+
+const meta = {
+    title: 'Layout/Custom Form Page',
+    parameters: {
+        layout: 'fullscreen',
+    },
+    tags: ['autodocs'],
+} satisfies Meta;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+/**
+ * This example shows how to create a custom form page using FormFieldWrapper
+ * with a product entity. This pattern is useful when you want full control over
+ * the form layout instead of using the automated DetailPage component.
+ */
+export const ProductCustomForm: Story = {
+    render: () => {
+        const { route, router } = createDemoRoute();
+        const form = useForm<ProductFormData>({
+            defaultValues: {
+                name: 'Wireless Headphones',
+                slug: 'wireless-headphones',
+                description: 'High-quality wireless headphones with active noise cancellation.',
+                enabled: true,
+            },
+        });
+
+        const onSubmit = (data: ProductFormData) => {
+            console.log('Form submitted:', data);
+            // In a real app, you would call your update mutation here
+        };
+
+        return (
+            <RouterContextProvider router={router}>
+                <Page
+                    pageId="product-custom-detail"
+                    form={form}
+                    submitHandler={form.handleSubmit(onSubmit)}
+                    entity={{
+                        id: '1',
+                        createdAt: '2024-01-01T00:00:00.000Z',
+                        updatedAt: '2024-01-15T00:00:00.000Z',
+                    }}
+                >
+                    <PageTitle>
+                        <Trans>Product: Wireless Headphones</Trans>
+                    </PageTitle>
+                    <PageActionBar>
+                        <PageActionBarRight>
+                            <Button type="submit" disabled={!form.formState.isDirty}>
+                                <Trans>Save Changes</Trans>
+                            </Button>
+                        </PageActionBarRight>
+                    </PageActionBar>
+                    <PageLayout>
+                        <PageBlock
+                            column="main"
+                            blockId="product-details"
+                            title={<Trans>Product Details</Trans>}
+                            description={<Trans>Basic information about the product</Trans>}
+                        >
+                            <DetailFormGrid>
+                                <FormFieldWrapper
+                                    control={form.control}
+                                    name="name"
+                                    label={<Trans>Product Name</Trans>}
+                                    description={<Trans>The display name of the product</Trans>}
+                                    render={({ field }) => <Input {...field} />}
+                                />
+                                <FormFieldWrapper
+                                    control={form.control}
+                                    name="slug"
+                                    label={<Trans>Slug</Trans>}
+                                    description={<Trans>URL-friendly identifier</Trans>}
+                                    render={({ field }) => <Input {...field} />}
+                                />
+                            </DetailFormGrid>
+                            <FormFieldWrapper
+                                control={form.control}
+                                name="description"
+                                label={<Trans>Description</Trans>}
+                                render={({ field }) => <Textarea {...field} rows={4} />}
+                            />
+                        </PageBlock>
+                        <PageBlock column="side" blockId="product-status" title={<Trans>Status</Trans>}>
+                            <FormFieldWrapper
+                                control={form.control}
+                                name="enabled"
+                                label={<Trans>Enabled</Trans>}
+                                description={<Trans>Whether this product is active</Trans>}
+                                render={({ field }) => (
+                                    <div className="flex items-center">
+                                        <input
+                                            type="checkbox"
+                                            checked={field.value}
+                                            onChange={field.onChange}
+                                            className="mr-2"
+                                        />
+                                        <span className="text-sm">
+                                            {field.value ? (
+                                                <Trans>Product is enabled</Trans>
+                                            ) : (
+                                                <Trans>Product is disabled</Trans>
+                                            )}
+                                        </span>
+                                    </div>
+                                )}
+                            />
+                        </PageBlock>
+                    </PageLayout>
+                </Page>
+            </RouterContextProvider>
+        );
+    },
+};
+
+/**
+ * This example shows a more complex form with multiple blocks and varied form fields.
+ */
+export const ComplexCustomForm: Story = {
+    render: () => {
+        const { route, router } = createDemoRoute();
+        const form = useForm({
+            defaultValues: {
+                // Basic Info
+                name: 'Premium Laptop',
+                slug: 'premium-laptop',
+                sku: 'LAPTOP-001',
+                // Pricing
+                price: 1299.99,
+                salePrice: null,
+                costPrice: 899.0,
+                // Inventory
+                stockOnHand: 50,
+                trackInventory: true,
+                // Details
+                description: 'High-performance laptop for professionals',
+                shortDescription: 'Professional laptop',
+                // SEO
+                metaTitle: '',
+                metaDescription: '',
+            },
+        });
+
+        const onSubmit = (data: any) => {
+            console.log('Form submitted:', data);
+        };
+
+        return (
+            <RouterContextProvider router={router}>
+                <Page
+                    pageId="product-complex-detail"
+                    form={form}
+                    submitHandler={form.handleSubmit(onSubmit)}
+                    entity={{ id: '2', createdAt: '2024-01-01', updatedAt: '2024-01-15' }}
+                >
+                    <PageTitle>
+                        <Trans>Product: Premium Laptop</Trans>
+                    </PageTitle>
+                    <PageActionBar>
+                        <PageActionBarRight>
+                            <Button variant="outline" type="button">
+                                <Trans>Cancel</Trans>
+                            </Button>
+                            <Button type="submit" disabled={!form.formState.isDirty}>
+                                <Trans>Save Changes</Trans>
+                            </Button>
+                        </PageActionBarRight>
+                    </PageActionBar>
+                    <PageLayout>
+                        <PageBlock
+                            column="main"
+                            blockId="basic-info"
+                            title={<Trans>Basic Information</Trans>}
+                        >
+                            <DetailFormGrid>
+                                <FormFieldWrapper
+                                    control={form.control}
+                                    name="name"
+                                    label={<Trans>Product Name</Trans>}
+                                    render={({ field }) => <Input {...field} />}
+                                />
+                                <FormFieldWrapper
+                                    control={form.control}
+                                    name="sku"
+                                    label={<Trans>SKU</Trans>}
+                                    render={({ field }) => <Input {...field} />}
+                                />
+                                <FormFieldWrapper
+                                    control={form.control}
+                                    name="slug"
+                                    label={<Trans>Slug</Trans>}
+                                    render={({ field }) => <Input {...field} />}
+                                />
+                            </DetailFormGrid>
+                        </PageBlock>
+
+                        <PageBlock column="main" blockId="description" title={<Trans>Description</Trans>}>
+                            <FormFieldWrapper
+                                control={form.control}
+                                name="shortDescription"
+                                label={<Trans>Short Description</Trans>}
+                                render={({ field }) => <Input {...field} />}
+                            />
+                            <FormFieldWrapper
+                                control={form.control}
+                                name="description"
+                                label={<Trans>Full Description</Trans>}
+                                render={({ field }) => <Textarea {...field} rows={6} />}
+                            />
+                        </PageBlock>
+
+                        <PageBlock column="main" blockId="pricing" title={<Trans>Pricing</Trans>}>
+                            <DetailFormGrid>
+                                <FormFieldWrapper
+                                    control={form.control}
+                                    name="price"
+                                    label={<Trans>Price</Trans>}
+                                    render={({ field }) => <Input {...field} type="number" step="0.01" />}
+                                />
+                                <FormFieldWrapper
+                                    control={form.control}
+                                    name="salePrice"
+                                    label={<Trans>Sale Price</Trans>}
+                                    description={<Trans>Optional discounted price</Trans>}
+                                    render={({ field }) => (
+                                        <Input
+                                            {...field}
+                                            type="number"
+                                            step="0.01"
+                                            value={field.value ?? ''}
+                                        />
+                                    )}
+                                />
+                                <FormFieldWrapper
+                                    control={form.control}
+                                    name="costPrice"
+                                    label={<Trans>Cost Price</Trans>}
+                                    description={<Trans>Your cost for this product</Trans>}
+                                    render={({ field }) => <Input {...field} type="number" step="0.01" />}
+                                />
+                            </DetailFormGrid>
+                        </PageBlock>
+
+                        <PageBlock column="side" blockId="inventory" title={<Trans>Inventory</Trans>}>
+                            <div className="space-y-4">
+                                <FormFieldWrapper
+                                    control={form.control}
+                                    name="trackInventory"
+                                    label={<Trans>Track Inventory</Trans>}
+                                    render={({ field }) => (
+                                        <div className="flex items-center">
+                                            <input
+                                                type="checkbox"
+                                                checked={field.value}
+                                                onChange={field.onChange}
+                                                className="mr-2"
+                                            />
+                                        </div>
+                                    )}
+                                />
+                                <FormFieldWrapper
+                                    control={form.control}
+                                    name="stockOnHand"
+                                    label={<Trans>Stock on Hand</Trans>}
+                                    render={({ field }) => <Input {...field} type="number" />}
+                                />
+                            </div>
+                        </PageBlock>
+
+                        <PageBlock column="side" blockId="seo" title={<Trans>SEO</Trans>}>
+                            <div className="space-y-4">
+                                <FormFieldWrapper
+                                    control={form.control}
+                                    name="metaTitle"
+                                    label={<Trans>Meta Title</Trans>}
+                                    render={({ field }) => <Input {...field} />}
+                                />
+                                <FormFieldWrapper
+                                    control={form.control}
+                                    name="metaDescription"
+                                    label={<Trans>Meta Description</Trans>}
+                                    render={({ field }) => <Textarea {...field} rows={3} />}
+                                />
+                            </div>
+                        </PageBlock>
+                    </PageLayout>
+                </Page>
+            </RouterContextProvider>
+        );
+    },
+};

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

@@ -0,0 +1,24 @@
+import { Button } from '@/vdb/components/ui/button.js';
+import { cn } from '@/vdb/lib/utils.js';
+import { CodeXmlIcon } 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>
+        );
+    },
+);

package/src/lib/framework/layout-engine/layout-extensions.ts

@@ -0,0 +1,27 @@
+import { DashboardActionBarItem, DashboardPageBlockDefinition } from '../extension-api/types/layout.js';
+import { globalRegistry } from '../registry/global-registry.js';
+
+globalRegistry.register('dashboardActionBarItemRegistry', new Map<string, DashboardActionBarItem[]>());
+globalRegistry.register('dashboardPageBlockRegistry', new Map<string, DashboardPageBlockDefinition[]>());
+
+export function registerDashboardActionBarItem(item: DashboardActionBarItem) {
+    globalRegistry.set('dashboardActionBarItemRegistry', map => {
+        map.set(item.pageId, [...(map.get(item.pageId) ?? []), item]);
+        return map;
+    });
+}
+
+export function getDashboardActionBarItems(pageId: string) {
+    return globalRegistry.get('dashboardActionBarItemRegistry').get(pageId) ?? [];
+}
+
+export function registerDashboardPageBlock(block: DashboardPageBlockDefinition) {
+    globalRegistry.set('dashboardPageBlockRegistry', map => {
+        map.set(block.location.pageId, [...(map.get(block.location.pageId) ?? []), block]);
+        return map;
+    });
+}
+
+export function getDashboardPageBlocks(pageId: string) {
+    return globalRegistry.get('dashboardPageBlockRegistry').get(pageId) ?? [];
+}

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

@@ -0,0 +1,122 @@
+import { CopyableText } from '@/vdb/components/shared/copyable-text.js';
+import { Popover, PopoverContent, PopoverTrigger } from '@/vdb/components/ui/popover.js';
+import { usePageBlock } from '@/vdb/hooks/use-page-block.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
+let globalHoveredId: string | null = null;
+const hoverListeners: Set<(id: string | null) => void> = new Set();
+
+const setGlobalHoveredId = (id: string | null) => {
+    globalHoveredId = id;
+    hoverListeners.forEach(listener => listener(id));
+};
+
+export interface LocationWrapperProps {
+    children: React.ReactNode;
+    identifier?: string;
+}
+
+export function LocationWrapper({ children, identifier }: Readonly<LocationWrapperProps>) {
+    const page = usePage();
+    const pageBlock = usePageBlock({ optional: true });
+    const { settings } = useUserSettings();
+    const [isPopoverOpen, setIsPopoverOpen] = useState(false);
+    const blockId = pageBlock?.blockId ?? null;
+    const isPageWrapper = !blockId;
+
+    const [hoveredId, setHoveredId] = useState<string | null>(globalHoveredId);
+    const id = `${page.pageId}-${blockId ?? 'page'}-${identifier ?? ''}`;
+    const isHovered = hoveredId === id;
+
+    // Subscribe to global hover changes
+    useEffect(() => {
+        const listener = (newHoveredId: string | null) => {
+            setHoveredId(newHoveredId);
+        };
+        hoverListeners.add(listener);
+        return () => {
+            hoverListeners.delete(listener);
+        };
+    }, []);
+
+    const setHoverId = (id: string | null) => {
+        setGlobalHoveredId(id);
+    };
+
+    const handleMouseEnter = () => {
+        // Set this element as hovered
+        setHoverId(id);
+    };
+
+    const handleMouseLeave = () => {
+        // If we're at the top level (page wrapper), go to null
+        // If we're at block level, go to page level
+        // If we're at identifier level, go to block level
+        if (isPageWrapper) {
+            setHoverId(null);
+        } else if (blockId && !identifier) {
+            // Block level - go to page level
+            setHoverId(`${page.pageId}-page-`);
+        } else if (identifier) {
+            // Identifier level - go to block level
+            setHoverId(`${page.pageId}-${blockId}-`);
+        }
+    };
+
+    if (settings.devMode) {
+        const pageId = page.pageId;
+        return (
+            <div
+                className={cn(
+                    `ring-2 transition-all ring-offset-4 ring-offset-background delay-50 relative`,
+                    isHovered || isPopoverOpen ? 'ring-dev-mode' : 'ring-transparent',
+                    isPageWrapper ? 'ring-offset-8' : '',
+                    identifier ? 'rounded-md' : 'rounded',
+                )}
+                onMouseEnter={handleMouseEnter}
+                onMouseLeave={handleMouseLeave}
+            >
+                <div
+                    className={`absolute top-1 right-1 transition-all delay-50 z-10 ${isHovered || isPopoverOpen ? 'visible' : 'invisible'}`}
+                >
+                    <Popover open={isPopoverOpen} onOpenChange={setIsPopoverOpen}>
+                        <PopoverTrigger asChild>
+                            <DevModeButton />
+                        </PopoverTrigger>
+                        <PopoverContent className="w-48 p-3">
+                            <div className="space-y-2">
+                                <div className="space-y-1">
+                                    {pageId && (
+                                        <div className="text-xs">
+                                            <div className="text-muted-foreground mb-0.5">pageId</div>
+                                            <CopyableText text={pageId} />
+                                        </div>
+                                    )}
+                                    {blockId && (
+                                        <div className="text-xs">
+                                            <div className="text-muted-foreground mb-0.5">blockId</div>
+                                            <CopyableText text={blockId} />
+                                        </div>
+                                    )}
+                                    {identifier && (
+                                        <div className="text-xs">
+                                            <div className="text-muted-foreground mb-0.5">identifier</div>
+                                            <CopyableText text={identifier} />
+                                        </div>
+                                    )}
+                                </div>
+                            </div>
+                        </PopoverContent>
+                    </Popover>
+                </div>
+                {children}
+            </div>
+        );
+    }
+    return children;
+}

package/src/lib/framework/layout-engine/page-block-provider.tsx

@@ -0,0 +1,6 @@
+import { PageBlockProps } from '@/vdb/framework/layout-engine/page-layout.js';
+import { createContext } from 'react';
+
+export type PageBlockContextValue = Pick<PageBlockProps, 'blockId' | 'column' | 'title' | 'description'>;
+
+export const PageBlockContext = createContext<PageBlockContextValue | undefined>(undefined);

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',
+        ]);
+    });
+});