@vendure/dashboard 3.5.0-minor-202510031341 → 3.5.0-minor-202510161257

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

@@ -7,17 +7,46 @@ export type NavMenuSectionPlacement = 'top' | 'bottom';
 
 /**
  * @description
- * The base configuration for navigation items and sections of the main app nav bar.
+ * Defines an items in the navigation menu.
  *
  * @docsCategory extensions-api
  * @docsPage Navigation
  * @since 3.4.0
  */
-interface NavMenuBaseItem {
+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
@@ -27,23 +56,7 @@ interface NavMenuBaseItem {
     requiresPermission?: string | string[];
 }
 
-/**
- * @description
- * Defines an items in the navigation menu.
- *
- * @docsCategory extensions-api
- * @docsPage Navigation
- * @since 3.4.0
- */
-export interface NavMenuItem extends NavMenuBaseItem {
-    /**
-     * @description
-     * The url of the route which this nav item links to.
-     */
-    url: string;
-}
-
-export interface NavMenuSection extends NavMenuBaseItem {
+export interface NavMenuSection extends Omit<NavMenuItem, 'url'> {
     defaultOpen?: boolean;
     items?: NavMenuItem[];
 }

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

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

@@ -5,8 +5,8 @@ import { Checkbox } from '@/vdb/components/ui/checkbox.js';
 import { Input } from '@/vdb/components/ui/input.js';
 import { NEW_ENTITY_PATH } from '@/vdb/constants.js';
 import { useDetailPage } from '@/vdb/framework/page/use-detail-page.js';
-import { Trans } from '@lingui/react/macro';
 import type { TypedDocumentNode } from '@graphql-typed-document-node/core';
+import { Trans } from '@lingui/react/macro';
 import { AnyRoute, useNavigate } from '@tanstack/react-router';
 import { ResultOf, VariablesOf } from 'gql.tada';
 import { toast } from 'sonner';
@@ -16,6 +16,7 @@ import {
     getOperationVariablesFields,
 } from '../document-introspection/get-document-structure.js';
 
+import { NumberInput } from '@/vdb/components/data-input/number-input.js';
 import { TranslatableFormFieldWrapper } from '@/vdb/components/shared/translatable-form-field.js';
 import { FormControl } from '@/vdb/components/ui/form.js';
 import { ControllerRenderProps, FieldPath, FieldValues } from 'react-hook-form';
@@ -108,11 +109,7 @@ function FieldInputRenderer<
         case 'Float':
             return (
                 <FormControl>
-                    <Input
-                        type="number"
-                        value={field.value}
-                        onChange={e => field.onChange(e.target.valueAsNumber)}
-                    />
+                    <NumberInput {...field} />
                 </FormControl>
             );
         case 'DateTime':
@@ -152,15 +149,15 @@ export function DetailPage<
     C extends TypedDocumentNode<any, any>,
     U extends TypedDocumentNode<any, any>,
 >({
-      pageId,
-      route,
-      entityName: passedEntityName,
-      queryDocument,
-      createDocument,
-      updateDocument,
-      setValuesForUpdate,
-      title,
-  }: DetailPageProps<T, C, U>) {
+    pageId,
+    route,
+    entityName: passedEntityName,
+    queryDocument,
+    createDocument,
+    updateDocument,
+    setValuesForUpdate,
+    title,
+}: DetailPageProps<T, C, U>) {
     const params = route.useParams();
     const creatingNewEntity = params.id === NEW_ENTITY_PATH;
     const navigate = useNavigate();