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

package/src/lib/framework/form-engine/value-transformers.ts

@@ -29,9 +29,16 @@ export const nativeValueTransformer: ValueTransformer = {
  */
 export const jsonStringValueTransformer: ValueTransformer = {
     parse: (value: string, fieldDef: ConfigurableFieldDef) => {
-        if (!value) {
+        if (value === undefined) {
             return getDefaultValue(fieldDef);
         }
+        // This case arises often when the administrator is actively editing
+        // values and clears out the input. At that point, we don't want to suddenly
+        // switch to the default value otherwise it results in poor UX, e.g. pressing
+        // backspace to delete a number would result in `0` suddenly appearing as the value.
+        if (value === '') {
+            return value;
+        }
 
         try {
             // For JSON string mode, parse the string to get the native value

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/page-layout.tsx

@@ -119,12 +119,12 @@ export function Page({ children, pageId, entity, form, submitHandler, ...props }
 }
 
 function PageContent({
-                         pageHeader,
-                         pageContent,
-                         form,
-                         submitHandler,
-                         ...props
-                     }: {
+    pageHeader,
+    pageContent,
+    form,
+    submitHandler,
+    ...props
+}: {
     pageHeader: React.ReactNode;
     pageContent: React.ReactNode;
     form?: UseFormReturn<any>;
@@ -146,11 +146,11 @@ function PageContent({
 }
 
 export function PageContentWithOptionalForm({
-                                                form,
-                                                pageHeader,
-                                                pageContent,
-                                                submitHandler,
-                                            }: {
+    form,
+    pageHeader,
+    pageContent,
+    submitHandler,
+}: {
     form?: UseFormReturn<any>;
     pageHeader: React.ReactNode;
     pageContent: React.ReactNode;
@@ -235,22 +235,32 @@ export function PageLayout({ children, className }: Readonly<PageLayoutProps>) {
                 childBlock.props.blockId ??
                 (isOfType(childBlock, CustomFieldsPageBlock) ? 'custom-fields' : undefined);
             const extensionBlock = extensionBlocks.find(block => block.location.position.blockId === blockId);
+
             if (extensionBlock) {
-                const ExtensionBlock = (
-                    <PageBlock
-                        key={childBlock.key}
-                        column={extensionBlock.location.column}
-                        blockId={extensionBlock.id}
-                        title={extensionBlock.title}
-                    >
-                        {<extensionBlock.component context={page} />}
-                    </PageBlock>
-                );
+                let extensionBlockShouldRender = true;
+                if (typeof extensionBlock?.shouldRender === 'function') {
+                    extensionBlockShouldRender = extensionBlock.shouldRender(page);
+                }
+                const ExtensionBlock =
+                    extensionBlock.component && extensionBlockShouldRender ? (
+                        <PageBlock
+                            key={childBlock.key}
+                            column={extensionBlock.location.column}
+                            blockId={extensionBlock.id}
+                            title={extensionBlock.title}
+                        >
+                            {<extensionBlock.component context={page} />}
+                        </PageBlock>
+                    ) : undefined;
                 if (extensionBlock.location.position.order === 'before') {
-                    finalChildArray.push(ExtensionBlock, childBlock);
+                    finalChildArray.push(...[ExtensionBlock, childBlock].filter(x => !!x));
                 } else if (extensionBlock.location.position.order === 'after') {
-                    finalChildArray.push(childBlock, ExtensionBlock);
-                } else if (extensionBlock.location.position.order === 'replace') {
+                    finalChildArray.push(...[childBlock, ExtensionBlock].filter(x => !!x));
+                } else if (
+                    extensionBlock.location.position.order === 'replace' &&
+                    extensionBlockShouldRender &&
+                    ExtensionBlock
+                ) {
                     finalChildArray.push(ExtensionBlock);
                 }
             } else {
@@ -266,17 +276,17 @@ export function PageLayout({ children, className }: Readonly<PageLayoutProps>) {
     const sideBlocks = finalChildArray.filter(child => isPageBlock(child) && child.props.column === 'side');
 
     return (
-        <div className={cn('w-full space-y-4', className)}>
+        <div className={cn('w-full space-y-4', className, '@container/layout')}>
             {isDesktop ? (
-                <div className="hidden md:grid md:grid-cols-5 lg:grid-cols-4 md:gap-4">
+                <div className="grid grid-cols-1 gap-4 @3xl/layout:grid-cols-4">
                     {fullWidthBlocks.length > 0 && (
-                        <div className="md:col-span-5 space-y-4">{fullWidthBlocks}</div>
+                        <div className="@md/layout:col-span-5 space-y-4">{fullWidthBlocks}</div>
                     )}
-                    <div className="md:col-span-3 space-y-4">{mainBlocks}</div>
-                    <div className="md:col-span-2 lg:col-span-1 space-y-4">{sideBlocks}</div>
+                    <div className="@3xl/layout:col-span-3 space-y-4">{mainBlocks}</div>
+                    <div className="@3xl/layout:col-span-1 space-y-4">{sideBlocks}</div>
                 </div>
             ) : (
-                <div className="md:hidden space-y-4">{children}</div>
+                <div className="space-y-4">{children}</div>
             )}
         </div>
     );
@@ -425,9 +435,9 @@ function EntityInfoDropdown({ entity }: Readonly<{ entity: any }>) {
  * @since 3.3.0
  */
 export function PageActionBarRight({
-                                       children,
-                                       dropdownMenuItems,
-                                   }: Readonly<{
+    children,
+    dropdownMenuItems,
+}: Readonly<{
     children: React.ReactNode;
     dropdownMenuItems?: InlineDropdownItem[];
 }>) {
@@ -458,9 +468,9 @@ export function PageActionBarRight({
 }
 
 function PageActionBarItem({
-                               item,
-                               page,
-                           }: Readonly<{ item: DashboardActionBarItem; page: PageContextValue }>) {
+    item,
+    page,
+}: Readonly<{ item: DashboardActionBarItem; page: PageContextValue }>) {
     return (
         <PermissionGuard requires={item.requiresPermission ?? []}>
             <item.component context={page} />
@@ -469,9 +479,9 @@ function PageActionBarItem({
 }
 
 function PageActionBarDropdown({
-                                   items,
-                                   page,
-                               }: Readonly<{ items: DashboardActionBarItem[]; page: PageContextValue }>) {
+    items,
+    page,
+}: Readonly<{ items: DashboardActionBarItem[]; page: PageContextValue }>) {
     return (
         <DropdownMenu>
             <DropdownMenuTrigger asChild>
@@ -550,13 +560,13 @@ export type PageBlockProps = {
  * @since 3.3.0
  */
 export function PageBlock({
-                              children,
-                              title,
-                              description,
-                              className,
-                              blockId,
-                              column,
-                          }: Readonly<PageBlockProps>) {
+    children,
+    title,
+    description,
+    className,
+    blockId,
+    column,
+}: Readonly<PageBlockProps>) {
     const contextValue = useMemo(
         () => ({
             blockId,
@@ -569,14 +579,16 @@ export function PageBlock({
     return (
         <PageBlockContext.Provider value={contextValue}>
             <LocationWrapper>
-                <Card className={cn('@container  w-full', className)}>
+                <Card className={cn('@container  w-full', className, 'animate-in fade-in duration-300')}>
                     {title || description ? (
                         <CardHeader>
                             {title && <CardTitle>{title}</CardTitle>}
                             {description && <CardDescription>{description}</CardDescription>}
                         </CardHeader>
                     ) : null}
-                    <CardContent className={cn(!title ? 'pt-6' : '')}>{children}</CardContent>
+                    <CardContent className={cn(!title ? 'pt-6' : '', 'overflow-auto')}>
+                        {children}
+                    </CardContent>
                 </Card>
             </LocationWrapper>
         </PageBlockContext.Provider>
@@ -595,15 +607,15 @@ export function PageBlock({
  * @since 3.3.0
  */
 export function FullWidthPageBlock({
-                                       children,
-                                       className,
-                                       blockId,
-                                   }: Readonly<Pick<PageBlockProps, 'children' | 'className' | 'blockId'>>) {
+    children,
+    className,
+    blockId,
+}: Readonly<Pick<PageBlockProps, 'children' | 'className' | 'blockId'>>) {
     const contextValue = useMemo(() => ({ blockId, column: 'main' as const }), [blockId]);
     return (
         <PageBlockContext.Provider value={contextValue}>
             <LocationWrapper>
-                <div className={cn('w-full', className)}>{children}</div>
+                <div className={cn('w-full', className, 'animate-in fade-in duration-300')}>{children}</div>
             </LocationWrapper>
         </PageBlockContext.Provider>
     );
@@ -625,10 +637,10 @@ export function FullWidthPageBlock({
  * @since 3.3.0
  */
 export function CustomFieldsPageBlock({
-                                          column,
-                                          entityType,
-                                          control,
-                                      }: Readonly<{
+    column,
+    entityType,
+    control,
+}: Readonly<{
     column: 'main' | 'side';
     entityType: string;
     control: Control<any, any>;