@wilshop/dashboard 3.5.2

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

@@ -0,0 +1,10 @@
+import { createContext } from 'react';
+import { UseFormReturn } from 'react-hook-form';
+
+export interface PageContextValue {
+    pageId?: string;
+    entity?: any;
+    form?: UseFormReturn<any>;
+}
+
+export const PageContext = createContext<PageContextValue | undefined>(undefined);

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

@@ -0,0 +1,275 @@
+import { Button } from '@/vdb/components/ui/button.js';
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { RouterContextProvider } from '@tanstack/react-router';
+import { createDemoRoute } from '../../../../.storybook/providers.js';
+import {
+    FullWidthPageBlock,
+    Page,
+    PageActionBar,
+    PageActionBarLeft,
+    PageActionBarRight,
+    PageBlock,
+    PageLayout,
+    PageTitle,
+} from './page-layout.js';
+
+const meta = {
+    title: 'Layout/Page Layout',
+    component: Page,
+    parameters: {
+        layout: 'fullscreen',
+    },
+    tags: ['autodocs'],
+} satisfies Meta<typeof Page>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Playground: Story = {
+    render: () => {
+        const { route, router } = createDemoRoute();
+        return (
+            <RouterContextProvider router={router}>
+                <Page pageId="test-page">
+                    <PageTitle>Test Page</PageTitle>
+                    <PageLayout>
+                        <PageBlock column="main" blockId="main-stuff">
+                            This will display in the main area
+                        </PageBlock>
+                        <PageBlock column="side" blockId="side-stuff">
+                            This will display in the side area
+                        </PageBlock>
+                    </PageLayout>
+                </Page>
+            </RouterContextProvider>
+        );
+    },
+};
+
+export const WithActionBar: Story = {
+    render: () => {
+        const { route, router } = createDemoRoute();
+        return (
+            <RouterContextProvider router={router}>
+                <Page pageId="product-detail">
+                    <PageTitle>Product Details</PageTitle>
+                    <PageActionBar>
+                        <PageActionBarLeft>
+                            <Button variant="outline">Cancel</Button>
+                        </PageActionBarLeft>
+                        <PageActionBarRight>
+                            <Button>Save</Button>
+                        </PageActionBarRight>
+                    </PageActionBar>
+                    <PageLayout>
+                        <PageBlock column="main" blockId="product-info" title="Product Information">
+                            <div className="space-y-4">
+                                <div>
+                                    <label className="text-sm font-medium">Name</label>
+                                    <input
+                                        type="text"
+                                        className="w-full border rounded px-3 py-2 mt-1"
+                                        defaultValue="Wireless Headphones"
+                                    />
+                                </div>
+                                <div>
+                                    <label className="text-sm font-medium">Description</label>
+                                    <textarea
+                                        className="w-full border rounded px-3 py-2 mt-1"
+                                        rows={4}
+                                        defaultValue="High-quality wireless headphones with active noise cancellation."
+                                    />
+                                </div>
+                            </div>
+                        </PageBlock>
+                        <PageBlock column="side" blockId="product-meta" title="Metadata">
+                            <div className="space-y-3">
+                                <div>
+                                    <div className="text-sm font-medium">Status</div>
+                                    <div className="text-sm text-muted-foreground">Active</div>
+                                </div>
+                                <div>
+                                    <div className="text-sm font-medium">SKU</div>
+                                    <div className="text-sm text-muted-foreground">WH-001</div>
+                                </div>
+                                <div>
+                                    <div className="text-sm font-medium">Price</div>
+                                    <div className="text-sm text-muted-foreground">$299.00</div>
+                                </div>
+                            </div>
+                        </PageBlock>
+                    </PageLayout>
+                </Page>
+            </RouterContextProvider>
+        );
+    },
+};
+
+export const MultipleBlocks: Story = {
+    render: () => {
+        const { route, router } = createDemoRoute();
+        return (
+            <RouterContextProvider router={router}>
+                <Page pageId="complex-page">
+                    <PageTitle>Complex Page Layout</PageTitle>
+                    <PageLayout>
+                        <PageBlock
+                            column="main"
+                            blockId="block-1"
+                            title="Main Block 1"
+                            description="This is the first main block"
+                        >
+                            <p>Content for the first main block goes here.</p>
+                        </PageBlock>
+                        <PageBlock
+                            column="main"
+                            blockId="block-2"
+                            title="Main Block 2"
+                            description="This is the second main block"
+                        >
+                            <p>Content for the second main block goes here.</p>
+                        </PageBlock>
+                        <PageBlock column="side" blockId="side-1" title="Sidebar Block 1">
+                            <p>First sidebar block content.</p>
+                        </PageBlock>
+                        <PageBlock column="side" blockId="side-2" title="Sidebar Block 2">
+                            <p>Second sidebar block content.</p>
+                        </PageBlock>
+                        <PageBlock column="side" blockId="side-3" title="Sidebar Block 3">
+                            <p>Third sidebar block content.</p>
+                        </PageBlock>
+                    </PageLayout>
+                </Page>
+            </RouterContextProvider>
+        );
+    },
+};
+
+export const WithFullWidthBlock: Story = {
+    render: () => {
+        const { route, router } = createDemoRoute();
+        return (
+            <RouterContextProvider router={router}>
+                <Page pageId="dashboard-overview">
+                    <PageTitle>Dashboard Overview</PageTitle>
+                    <PageLayout>
+                        <FullWidthPageBlock blockId="stats">
+                            <div className="grid grid-cols-1 md:grid-cols-4 gap-4 p-6 bg-muted/50 rounded-lg">
+                                <div className="text-center">
+                                    <div className="text-3xl font-bold">1,234</div>
+                                    <div className="text-sm text-muted-foreground">Total Orders</div>
+                                </div>
+                                <div className="text-center">
+                                    <div className="text-3xl font-bold">$45,678</div>
+                                    <div className="text-sm text-muted-foreground">Revenue</div>
+                                </div>
+                                <div className="text-center">
+                                    <div className="text-3xl font-bold">567</div>
+                                    <div className="text-sm text-muted-foreground">Products</div>
+                                </div>
+                                <div className="text-center">
+                                    <div className="text-3xl font-bold">890</div>
+                                    <div className="text-sm text-muted-foreground">Customers</div>
+                                </div>
+                            </div>
+                        </FullWidthPageBlock>
+                        <PageBlock column="main" blockId="recent-orders" title="Recent Orders">
+                            <div className="space-y-2">
+                                {[1, 2, 3].map(i => (
+                                    <div key={i} className="flex justify-between py-2 border-b">
+                                        <span>Order #{1000 + i}</span>
+                                        <span className="text-muted-foreground">$99.00</span>
+                                    </div>
+                                ))}
+                            </div>
+                        </PageBlock>
+                        <PageBlock column="side" blockId="quick-stats" title="Quick Stats">
+                            <div className="space-y-3">
+                                <div>
+                                    <div className="text-sm font-medium">Pending Orders</div>
+                                    <div className="text-2xl font-bold">12</div>
+                                </div>
+                                <div>
+                                    <div className="text-sm font-medium">Low Stock Items</div>
+                                    <div className="text-2xl font-bold">5</div>
+                                </div>
+                            </div>
+                        </PageBlock>
+                    </PageLayout>
+                </Page>
+            </RouterContextProvider>
+        );
+    },
+};
+
+export const MinimalPage: Story = {
+    render: () => {
+        const { route, router } = createDemoRoute();
+        return (
+            <RouterContextProvider router={router}>
+                <Page pageId="simple-page">
+                    <PageTitle>Simple Page</PageTitle>
+                    <PageLayout>
+                        <PageBlock column="main" blockId="content">
+                            <p>This is a minimal page with just a title and one content block.</p>
+                        </PageBlock>
+                    </PageLayout>
+                </Page>
+            </RouterContextProvider>
+        );
+    },
+};
+
+export const WithBlockDescriptions: Story = {
+    render: () => {
+        const { route, router } = createDemoRoute();
+        return (
+            <RouterContextProvider router={router}>
+                <Page pageId="settings-page">
+                    <PageTitle>Settings</PageTitle>
+                    <PageLayout>
+                        <PageBlock
+                            column="main"
+                            blockId="general"
+                            title="General Settings"
+                            description="Configure general application settings and preferences"
+                        >
+                            <div className="space-y-4">
+                                <div className="flex items-center justify-between">
+                                    <label className="text-sm font-medium">Enable notifications</label>
+                                    <input type="checkbox" defaultChecked />
+                                </div>
+                                <div className="flex items-center justify-between">
+                                    <label className="text-sm font-medium">Dark mode</label>
+                                    <input type="checkbox" />
+                                </div>
+                            </div>
+                        </PageBlock>
+                        <PageBlock
+                            column="main"
+                            blockId="advanced"
+                            title="Advanced Settings"
+                            description="Advanced configuration options for power users"
+                        >
+                            <div className="space-y-4">
+                                <div>
+                                    <label className="text-sm font-medium">API Key</label>
+                                    <input
+                                        type="text"
+                                        className="w-full border rounded px-3 py-2 mt-1"
+                                        defaultValue="sk_test_..."
+                                    />
+                                </div>
+                            </div>
+                        </PageBlock>
+                        <PageBlock column="side" blockId="help" title="Help" description="Need assistance?">
+                            <Button variant="outline" className="w-full">
+                                View Documentation
+                            </Button>
+                        </PageBlock>
+                    </PageLayout>
+                </Page>
+            </RouterContextProvider>
+        );
+    },
+};

package/src/lib/framework/nav-menu/nav-menu-extensions.ts

@@ -0,0 +1,112 @@
+import type { LucideIcon } from 'lucide-react';
+
+import { globalRegistry } from '../registry/global-registry.js';
+
+// Define the placement options for navigation sections
+export type NavMenuSectionPlacement = 'top' | 'bottom';
+
+/**
+ * @description
+ * Defines an items in the navigation menu.
+ *
+ * @docsCategory extensions-api
+ * @docsPage Navigation
+ * @since 3.4.0
+ */
+export interface NavMenuItem {
+    /**
+     * @description
+     * A unique ID for this nav menu item
+     */
+    id: string;
+    /**
+     * @description
+     * The title that will appear in the nav menu
+     */
+    title: string;
+    /**
+     * @description
+     * The url of the route which this nav item links to.
+     */
+    url: string;
+    /**
+     * @description
+     * An optional icon component to represent the item,
+     * which should be imported from `lucide-react`.
+     */
+    icon?: LucideIcon;
+    /**
+     * @description
+     * The order is an number which allows you to control
+     * the relative position in relation to other items in the
+     * menu.
+     * A higher number appears further down the list.
+     */
+    order?: number;
+    /**
+     * Whether this item should appear in the top of bottom section
+     * of the nav menu.
+     */
+    placement?: NavMenuSectionPlacement;
+    /**
+     * @description
+     * This can be used to restrict the menu item to the given
+     * permission or permissions.
+     */
+    requiresPermission?: string | string[];
+}
+
+export interface NavMenuSection extends Omit<NavMenuItem, 'url'> {
+    defaultOpen?: boolean;
+    items?: NavMenuItem[];
+}
+
+export interface NavMenuConfig {
+    sections: Array<NavMenuSection | NavMenuItem>;
+}
+
+globalRegistry.register('navMenuConfig', { sections: [] });
+
+export function getNavMenuConfig() {
+    return globalRegistry.get('navMenuConfig');
+}
+
+export function setNavMenuConfig(config: NavMenuConfig) {
+    globalRegistry.set('navMenuConfig', oldValue => {
+        return Object.assign({}, oldValue, config);
+    });
+}
+
+export function addNavMenuItem(item: NavMenuItem, sectionId: string) {
+    const navMenuConfig = getNavMenuConfig();
+    navMenuConfig.sections = [...navMenuConfig.sections];
+    const sectionIndex = navMenuConfig.sections.findIndex(
+        (s: NavMenuSection | NavMenuItem) => s.id === sectionId,
+    );
+    if (sectionIndex !== -1) {
+        const sectionFromConfig = navMenuConfig.sections[sectionIndex];
+
+        if ('items' in sectionFromConfig) {
+            const section = {
+                ...sectionFromConfig,
+                items: [...(sectionFromConfig.items ?? [])],
+            };
+            const itemIndex = section.items.findIndex((i: NavMenuItem) => i.id === item.id);
+            if (itemIndex === -1) {
+                section.items.push(item);
+                navMenuConfig.sections.splice(sectionIndex, 1, section);
+            } else {
+                section.items.splice(itemIndex, 1, item);
+                navMenuConfig.sections.splice(sectionIndex, 1, section);
+            }
+        } else {
+            navMenuConfig.sections.splice(sectionIndex, 1, item);
+        }
+    }
+}
+
+export function addNavMenuSection(section: NavMenuSection) {
+    const navMenuConfig = getNavMenuConfig();
+    navMenuConfig.sections = [...navMenuConfig.sections];
+    navMenuConfig.sections.push(section);
+}

package/src/lib/framework/page/detail-page-route-loader.tsx

@@ -0,0 +1,67 @@
+import { NEW_ENTITY_PATH } from '@/vdb/constants.js';
+
+import { PageBreadcrumb } from '@/vdb/components/layout/generated-breadcrumbs.js';
+import { extendDetailFormQuery } from '@/vdb/framework/document-extension/extend-detail-form-query.js';
+import { TypedDocumentNode } from '@graphql-typed-document-node/core';
+import { FileBaseRouteOptions, ParsedLocation } from '@tanstack/react-router';
+import { addCustomFields } from '../document-introspection/add-custom-fields.js';
+import { getQueryName, getQueryTypeFieldInfo } from '../document-introspection/get-document-structure.js';
+import { DetailEntity } from './page-types.js';
+import { getDetailQueryOptions } from './use-detail-page.js';
+
+export interface DetailPageRouteLoaderConfig<T extends TypedDocumentNode<any, any>> {
+    /**
+     * @description
+     * The pageId is used to ensure any detail form extensions (such as extensions to
+     * the detail query document) get correctly applied at the route loader level.
+     */
+    pageId?: string;
+    queryDocument: T;
+    breadcrumb: (
+        isNew: boolean,
+        entity: DetailEntity<T>,
+        location: ParsedLocation,
+    ) => Array<PageBreadcrumb | undefined>;
+}
+
+export function detailPageRouteLoader<T extends TypedDocumentNode<any, any>>({
+    pageId,
+    queryDocument,
+    breadcrumb,
+}: DetailPageRouteLoaderConfig<T>) {
+    const loader: FileBaseRouteOptions<any, any, any>['loader'] = async ({
+        context,
+        params,
+        location,
+    }: {
+        context: any;
+        params: any;
+        location: ParsedLocation;
+    }) => {
+        if (!params.id) {
+            throw new Error('ID param is required');
+        }
+        const isNew = params.id === NEW_ENTITY_PATH;
+        const { extendedQuery: extendedQueryDocument } = extendDetailFormQuery(
+            addCustomFields(queryDocument),
+            pageId,
+        );
+        const result = isNew
+            ? null
+            : await context.queryClient.ensureQueryData(
+                  getDetailQueryOptions(extendedQueryDocument, { id: params.id }),
+                  { id: params.id },
+              );
+
+        const entityField = getQueryName(queryDocument);
+        const entityName = getQueryTypeFieldInfo(queryDocument)?.type;
+
+        if (!isNew && !result[entityField]) {
+            throw new Error(`${entityName} with the ID ${params.id} was not found`);
+        }
+        return {
+            breadcrumb: breadcrumb(isNew, result?.[entityField], location),
+        };
+    };
+    return loader;
+}

package/src/lib/framework/page/detail-page.stories.tsx

@@ -0,0 +1,151 @@
+import { graphql } from '@/vdb/graphql/graphql.js';
+import type { Meta, StoryObj } from '@storybook/react';
+import { DemoRouterProvider } from '../../../../.storybook/providers.js';
+import { DetailPage, DetailPageProps } from './detail-page.js';
+
+// Sample GraphQL query for a product detail
+const productFragment = graphql(`
+    fragment ProductDetail on Product {
+        id
+        createdAt
+        updatedAt
+        name
+        slug
+        description
+        enabled
+        featuredAsset {
+            id
+        }
+        assets {
+            id
+        }
+        facetValues {
+            id
+        }
+        translations {
+            id
+            languageCode
+            name
+            slug
+            description
+        }
+    }
+`);
+
+const productQuery = graphql(
+    `
+        query Product($id: ID!) {
+            product(id: $id) {
+                ...ProductDetail
+            }
+        }
+    `,
+    [productFragment],
+);
+
+const createProductDocument = graphql(`
+    mutation CreateProduct($input: CreateProductInput!) {
+        createProduct(input: $input) {
+            id
+            name
+            slug
+            description
+            enabled
+        }
+    }
+`);
+
+const updateProductDocument = graphql(`
+    mutation UpdateProduct($input: UpdateProductInput!) {
+        updateProduct(input: $input) {
+            id
+            name
+            slug
+            description
+            enabled
+        }
+    }
+`);
+
+function DetailPageStoryWrapper(props: Omit<DetailPageProps<any, any, any>, 'route'>) {
+    return (
+        <DemoRouterProvider
+            component={route => <DetailPage {...props} route={route} />}
+            path={'/products/$id'}
+            initialPath={'/products/1'}
+        />
+    );
+}
+
+const meta = {
+    title: 'Layout/DetailPage',
+    component: DetailPageStoryWrapper,
+    parameters: {
+        layout: 'fullscreen',
+    },
+    tags: ['autodocs'],
+    argTypes: {
+        pageId: {
+            control: 'text',
+            description: 'Unique identifier for the detail page',
+        },
+        entityName: {
+            control: 'text',
+            description: 'Name of the entity (inferred from query if not provided)',
+        },
+        title: {
+            control: false,
+            description: 'Function that returns the page title based on the entity',
+        },
+        queryDocument: {
+            control: false,
+            description: 'GraphQL query document for fetching entity data',
+        },
+        createDocument: {
+            control: false,
+            description: 'GraphQL mutation document for creating the entity',
+        },
+        updateDocument: {
+            control: false,
+            description: 'GraphQL mutation document for updating the entity',
+        },
+        setValuesForUpdate: {
+            control: false,
+            description: 'Function to map entity data to update input',
+        },
+    },
+} satisfies Meta<typeof DetailPageStoryWrapper>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+/**
+ * Basic example of a DetailPage showing a product entity.
+ * This demonstrates the minimal configuration needed to render a detail page.
+ */
+export const BasicDetail: Story = {
+    args: {
+        pageId: 'product-detail',
+        queryDocument: productQuery,
+        updateDocument: updateProductDocument,
+        title: entity => entity?.name || 'Product',
+        setValuesForUpdate: entity => ({
+            id: entity.id,
+            name: entity.name,
+            slug: entity.slug,
+            description: entity.description,
+            enabled: entity.enabled,
+            featuredAssetId: entity.featuredAsset?.id,
+            assetIds: entity.assets.map(asset => asset.id),
+            facetValueIds: entity.facetValues.map(facetValue => facetValue.id),
+            translations: entity.translations.map(translation => ({
+                id: translation.id,
+                languageCode: translation.languageCode,
+                name: translation.name,
+                slug: translation.slug,
+                description: translation.description,
+                customFields: (translation as any).customFields,
+            })),
+        }),
+    },
+};