@vendure/dashboard 3.2.0

package/src/lib/framework/form-engine/form-schema-tools.ts

@@ -0,0 +1,98 @@
+import {
+    FieldInfo,
+    isEnumType,
+    isScalarType,
+} from '@/framework/document-introspection/get-document-structure.js';
+import { z, ZodRawShape, ZodType, ZodTypeAny } from 'zod';
+
+export function createFormSchemaFromFields(fields: FieldInfo[]) {
+    const schemaConfig: ZodRawShape = {};
+    for (const field of fields) {
+        const isScalar = isScalarType(field.type);
+        const isEnum = isEnumType(field.type);
+        if (isScalar || isEnum) {
+            schemaConfig[field.name] = getZodTypeFromField(field);
+        } else if (field.typeInfo) {
+            let nestedType: ZodType = createFormSchemaFromFields(field.typeInfo);
+            if (field.nullable) {
+                nestedType = nestedType.optional().nullable();
+            }
+            if (field.list) {
+                nestedType = z.array(nestedType);
+            }
+            schemaConfig[field.name] = nestedType;
+        }
+    }
+    return z.object(schemaConfig);
+}
+
+export function getDefaultValuesFromFields(fields: FieldInfo[], defaultLanguageCode?: string) {
+    const defaultValues: Record<string, any> = {};
+    for (const field of fields) {
+        if (field.typeInfo) {
+            const nestedObjectDefaults = getDefaultValuesFromFields(field.typeInfo, defaultLanguageCode);
+            if (field.list) {
+                defaultValues[field.name] = [nestedObjectDefaults];
+            } else {
+                defaultValues[field.name] = nestedObjectDefaults;
+            }
+        } else {
+            defaultValues[field.name] = getDefaultValueFromField(field, defaultLanguageCode);
+        }
+    }
+    return defaultValues;
+}
+
+export function getDefaultValueFromField(field: FieldInfo, defaultLanguageCode?: string) {
+    if (field.list) {
+        return [];
+    }
+    switch (field.type) {
+        case 'String':
+        case 'DateTime':
+            return '';
+        case 'Int':
+        case 'Float':
+        case 'Money':
+            return 0;
+        case 'Boolean':
+            return false;
+        case 'ID':
+            return '';
+        case 'LanguageCode':
+            return defaultLanguageCode || 'en';
+        case 'JSON':
+            return {};
+        default: {
+            return '';
+        }
+    }
+}
+
+export function getZodTypeFromField(field: FieldInfo): ZodTypeAny {
+    let zodType: ZodType;
+    switch (field.type) {
+        case 'String':
+        case 'ID':
+        case 'DateTime':
+            zodType = z.string();
+            break;
+        case 'Int':
+        case 'Float':
+        case 'Money':
+            zodType = z.number();
+            break;
+        case 'Boolean':
+            zodType = z.boolean();
+            break;
+        default:
+            zodType = z.any();
+    }
+    if (field.list) {
+        zodType = z.array(zodType);
+    }
+    if (field.nullable) {
+        zodType = zodType.optional().nullable();
+    }
+    return zodType;
+}

package/src/lib/framework/form-engine/use-generated-form.tsx

@@ -0,0 +1,116 @@
+import { getOperationVariablesFields } from '@/framework/document-introspection/get-document-structure.js';
+import {
+    createFormSchemaFromFields,
+    getDefaultValuesFromFields,
+} from '@/framework/form-engine/form-schema-tools.js';
+import { useChannel } from '@/hooks/use-channel.js';
+import { useServerConfig } from '@/hooks/use-server-config.js';
+import type { TypedDocumentNode } from '@graphql-typed-document-node/core';
+import { zodResolver } from '@hookform/resolvers/zod';
+import { VariablesOf } from 'gql.tada';
+import { FormEvent } from 'react';
+import { useForm } from 'react-hook-form';
+
+export interface GeneratedFormOptions<
+    T extends TypedDocumentNode<any, any>,
+    VarName extends keyof VariablesOf<T> = 'input',
+    E extends Record<string, any> = Record<string, any>,
+> {
+    document?: T;
+    entity: E | null | undefined;
+    setValues: (entity: NonNullable<E>) => VariablesOf<T>[VarName];
+    onSubmit?: (values: VariablesOf<T>[VarName]) => void;
+}
+
+/**
+ * @description
+ * This hook is used to create a form from a document and an entity.
+ * It will create a form with the fields defined in the document's input type.
+ * It will also create a submit handler that will submit the form to the server.
+ *
+ */
+export function useGeneratedForm<
+    T extends TypedDocumentNode<any, any>,
+    VarName extends keyof VariablesOf<T> = 'input',
+    E extends Record<string, any> = Record<string, any>,
+>(options: GeneratedFormOptions<T, VarName, E>) {
+    const { document, entity, setValues, onSubmit } = options;
+    const { activeChannel } = useChannel();
+    const availableLanguages = useServerConfig()?.availableLanguages || [];
+    const updateFields = document ? getOperationVariablesFields(document) : [];
+    const schema = createFormSchemaFromFields(updateFields);
+    const defaultValues = getDefaultValuesFromFields(updateFields, activeChannel?.defaultLanguageCode);
+    const processedEntity = ensureTranslationsForAllLanguages(entity, availableLanguages);
+
+    const form = useForm({
+        resolver: async (values, context, options) => {
+            const result = await zodResolver(schema)(values, context, options);
+            if (Object.keys(result.errors).length > 0) {
+                console.log('Zod form validation errors:', result.errors);
+            }
+            return result;
+        },
+        defaultValues,
+        values: processedEntity ? setValues(processedEntity) : defaultValues,
+    });
+    let submitHandler = (event: FormEvent) => {
+        event.preventDefault();
+    };
+    if (onSubmit) {
+        submitHandler = (event: FormEvent) => {
+            form.handleSubmit(onSubmit)(event);
+        };
+    }
+
+    return { form, submitHandler };
+}
+
+/**
+ * Ensures that an entity with translations has entries for all available languages.
+ * If a language is missing, it creates an empty translation based on the structure of existing translations.
+ */
+function ensureTranslationsForAllLanguages<E extends Record<string, any>>(
+    entity: E | null | undefined,
+    availableLanguages: string[] = [],
+): E | null | undefined {
+    if (
+        !entity ||
+        !('translations' in entity) ||
+        !Array.isArray((entity as any).translations) ||
+        !availableLanguages.length
+    ) {
+        return entity;
+    }
+
+    // Create a deep copy of the entity to avoid mutation
+    const processedEntity = { ...entity } as any;
+    const translations = [...(processedEntity.translations || [])];
+
+    // Get existing language codes
+    const existingLanguageCodes = new Set(translations.map((t: any) => t.languageCode));
+
+    // Add missing language translations
+    for (const langCode of availableLanguages) {
+        if (!existingLanguageCodes.has(langCode)) {
+            // Find a translation to use as template for field structure
+            const template = translations[0] || {};
+            const emptyTranslation: Record<string, any> = {
+                languageCode: langCode,
+            };
+
+            // Add empty fields based on template (excluding languageCode)
+            Object.keys(template).forEach(key => {
+                if (key !== 'languageCode') {
+                    emptyTranslation[key] = '';
+                }
+            });
+
+            translations.push(emptyTranslation);
+        }
+    }
+
+    // Update the processed entity with complete translations
+    processedEntity.translations = translations;
+
+    return processedEntity as E;
+}

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

@@ -0,0 +1,30 @@
+import {
+    DashboardActionBarItem,
+    DashboardPageBlockDefinition,
+} from '../extension-api/extension-api-types.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.locationId, [...(map.get(item.locationId) ?? []), item]);
+        return map;
+    });
+}
+
+export function getDashboardActionBarItems(locationId: string) {
+    return globalRegistry.get('dashboardActionBarItemRegistry').get(locationId) ?? [];
+}
+
+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,96 @@
+import { CopyableText } from '@/components/shared/copyable-text.js';
+import { Button } from '@/components/ui/button.js';
+import { Popover, PopoverContent, PopoverTrigger } from '@/components/ui/popover.js';
+import { usePage } from '@/hooks/use-page.js';
+import { useUserSettings } from '@/hooks/use-user-settings.js';
+import { cn } from '@/lib/utils.js';
+import { Trans } from '@/lib/trans.js';
+import { CodeXmlIcon, InfoIcon } from 'lucide-react';
+import { createContext, useContext, useState } from 'react';
+
+const LocationWrapperContext = createContext<{
+    parentId: string | null;
+    hoveredId: string | null;
+    setHoveredId: ((id: string | null) => void) | null;
+}>({
+    parentId: null,
+    hoveredId: null,
+    setHoveredId: null,
+});
+
+export function LocationWrapper({ children, blockId }: { children: React.ReactNode; blockId?: string }) {
+    const page = usePage();
+    const { settings } = useUserSettings();
+    const [isPopoverOpen, setIsPopoverOpen] = useState(false);
+    const isPageWrapper = !blockId;
+
+    const [hoveredIdTopLevel, setHoveredIdTopLevel] = useState<string | null>(null);
+    const { hoveredId, setHoveredId, parentId } = useContext(LocationWrapperContext);
+    const id = `${page.pageId}-${blockId ?? 'page'}`;
+    const isHovered = hoveredId === id || hoveredIdTopLevel === id;
+
+    const setHoverId = (id: string | null) => {
+        if (setHoveredId) {
+            setHoveredId(id);
+        } else {
+            setHoveredIdTopLevel(id);
+        }
+    };
+
+    if (settings.devMode) {
+        const pageId = page.pageId;
+        return (
+            <LocationWrapperContext.Provider
+                value={{ hoveredId: hoveredIdTopLevel, setHoveredId: setHoveredIdTopLevel, parentId: id }}
+            >
+                <div
+                    className={cn(
+                        `ring-2 rounded-xl transition-all delay-50 relative`,
+                        isHovered || isPopoverOpen ? 'ring-dev-mode' : 'ring-transparent',
+                        isPageWrapper ? 'ring-inset' : '',
+                    )}
+                    onMouseEnter={() => setHoverId(id)}
+                    onMouseLeave={() => setHoverId(parentId)}
+                >
+                    <div
+                        className={`absolute top-0.5 right-0.5 transition-all delay-50 z-10 ${isHovered || isPopoverOpen ? 'visible' : 'invisible'}`}
+                    >
+                        <Popover open={isPopoverOpen} onOpenChange={setIsPopoverOpen}>
+                            <PopoverTrigger asChild>
+                                <Button variant="ghost" size="icon" className="rounded-lg">
+                                    <CodeXmlIcon className="text-dev-mode w-5 h-5" />
+                                </Button>
+                            </PopoverTrigger>
+                            <PopoverContent className="w-60">
+                                <div className="space-y-2">
+                                    <div className="flex items-center gap-2">
+                                        <InfoIcon className="h-4 w-4 text-dev-mode" />
+                                        <span className="font-medium">
+                                            <Trans>Location Details</Trans>
+                                        </span>
+                                    </div>
+                                    <div className="space-y-1.5">
+                                        {pageId && (
+                                            <div>
+                                                <div className="text-xs text-muted-foreground">pageId</div>
+                                                <CopyableText text={pageId} />
+                                            </div>
+                                        )}
+                                        {blockId && (
+                                            <div>
+                                                <div className="text-xs text-muted-foreground">blockId</div>
+                                                <CopyableText text={blockId} />
+                                            </div>
+                                        )}
+                                    </div>
+                                </div>
+                            </PopoverContent>
+                        </Popover>
+                    </div>
+                    {children}
+                </div>
+            </LocationWrapperContext.Provider>
+        );
+    }
+    return children;
+}

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

@@ -0,0 +1,272 @@
+import { CustomFieldsForm } from '@/components/shared/custom-fields-form.js';
+import { PermissionGuard } from '@/components/shared/permission-guard.js';
+import { Card, CardContent, CardDescription, CardHeader, CardTitle } from '@/components/ui/card.js';
+import { Form } from '@/components/ui/form.js';
+import { useCustomFieldConfig } from '@/hooks/use-custom-field-config.js';
+import { usePage } from '@/hooks/use-page.js';
+import { cn } from '@/lib/utils.js';
+import { useMediaQuery } from '@uidotdev/usehooks';
+import React, { ComponentProps, createContext } from 'react';
+import { Control, UseFormReturn } from 'react-hook-form';
+import { DashboardActionBarItem } from '../extension-api/extension-api-types.js';
+import { getDashboardActionBarItems, getDashboardPageBlocks } from './layout-extensions.js';
+import { LocationWrapper } from './location-wrapper.js';
+
+export interface PageProps extends ComponentProps<'div'> {
+    pageId?: string;
+    entity?: any;
+    form?: UseFormReturn<any>;
+    submitHandler?: any;
+}
+
+export const PageProvider = createContext<PageContext | undefined>(undefined);
+
+export function Page({ children, pageId, entity, form, submitHandler, ...props }: PageProps) {
+    const childArray = React.Children.toArray(children);
+
+    const pageTitle = childArray.find(child => React.isValidElement(child) && child.type === PageTitle);
+    const pageActionBar = childArray.find(
+        child => React.isValidElement(child) && child.type === PageActionBar,
+    );
+
+    const pageContent = childArray.filter(
+        child => React.isValidElement(child) && child.type !== PageTitle && child.type !== PageActionBar,
+    );
+
+    const pageHeader = (
+        <div className="flex items-center justify-between">
+            {pageTitle}
+            {pageActionBar}
+        </div>
+    );
+
+    const pageContentWithOptionalForm = form ? (
+        <Form {...form}>
+            <form onSubmit={submitHandler} className="space-y-4">
+                {pageHeader}
+                {pageContent}
+            </form>
+        </Form>
+    ) : (
+        <div className="space-y-4">
+            {pageHeader}
+            {pageContent}
+        </div>
+    );
+
+    return (
+        <PageProvider value={{ pageId, form, entity }}>
+            <LocationWrapper>
+                <div className={cn('m-4', props.className)} {...props}>
+                    {pageContentWithOptionalForm}
+                </div>
+            </LocationWrapper>
+        </PageProvider>
+    );
+}
+
+export type PageLayoutProps = {
+    children: React.ReactNode;
+    className?: string;
+};
+
+function isPageBlock(child: unknown): child is React.ReactElement<PageBlockProps> {
+    if (!child) {
+        return false;
+    }
+    if (!React.isValidElement(child)) {
+        return false;
+    }
+    const props = (child as React.ReactElement<PageBlockProps>).props;
+    const hasColumn = 'column' in props;
+    const hasBlockId = 'blockId' in props;
+    return hasColumn || hasBlockId;
+}
+
+export function PageLayout({ children, className }: PageLayoutProps) {
+    const page = usePage();
+    const isDesktop = useMediaQuery('only screen and (min-width : 769px)');
+    // Separate blocks into categories
+    const childArray: React.ReactElement<PageBlockProps>[] = [];
+    const extensionBlocks = getDashboardPageBlocks(page.pageId ?? '');
+    React.Children.forEach(children, child => {
+        if (isPageBlock(child)) {
+            childArray.push(child);
+        }
+        // check for a React Fragment
+        if (React.isValidElement(child) && child.type === React.Fragment) {
+            React.Children.forEach((child as React.ReactElement<PageBlockProps>).props.children, child => {
+                if (isPageBlock(child)) {
+                    childArray.push(child);
+                }
+            });
+        }
+    });
+
+    const finalChildArray: React.ReactElement<PageBlockProps>[] = [];
+    for (const childBlock of childArray) {
+        if (childBlock) {
+            const blockId =
+                childBlock.props.blockId ??
+                (childBlock.type === CustomFieldsPageBlock ? 'custom-fields' : undefined);
+            const extensionBlock = extensionBlocks.find(block => block.location.position.blockId === blockId);
+            if (extensionBlock) {
+                const ExtensionBlock = (
+                    <PageBlock
+                        column={extensionBlock.location.column}
+                        blockId={extensionBlock.id}
+                        title={extensionBlock.title}
+                    >
+                        {<extensionBlock.component context={page} />}
+                    </PageBlock>
+                );
+                if (extensionBlock.location.position.order === 'before') {
+                    finalChildArray.push(ExtensionBlock, childBlock);
+                } else if (extensionBlock.location.position.order === 'after') {
+                    finalChildArray.push(childBlock, ExtensionBlock);
+                } else if (extensionBlock.location.position.order === 'replace') {
+                    finalChildArray.push(ExtensionBlock);
+                }
+            } else {
+                finalChildArray.push(childBlock);
+            }
+        }
+    }
+
+    const fullWidthBlocks = finalChildArray.filter(
+        child => isPageBlock(child) && child.type === FullWidthPageBlock,
+    );
+    const mainBlocks = finalChildArray.filter(child => isPageBlock(child) && child.props.column === 'main');
+    const sideBlocks = finalChildArray.filter(child => isPageBlock(child) && child.props.column === 'side');
+
+    return (
+        <div className={cn('w-full space-y-4', className)}>
+            {isDesktop ? (
+                <div className="hidden md:grid md:grid-cols-5 lg:grid-cols-4 md:gap-4">
+                    {fullWidthBlocks.length > 0 && (
+                        <div className="md: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>
+            ) : (
+                <div className="md:hidden space-y-4">{children}</div>
+            )}
+        </div>
+    );
+}
+
+export function DetailFormGrid({ children }: { children: React.ReactNode }) {
+    return <div className="md:grid md:grid-cols-2 gap-4 items-start mb-4">{children}</div>;
+}
+
+export interface PageContext {
+    pageId?: string;
+    entity?: any;
+    form?: UseFormReturn<any>;
+}
+
+export function PageTitle({ children }: { children: React.ReactNode }) {
+    return <h1 className="text-2xl font-semibold">{children}</h1>;
+}
+
+export function PageActionBar({ children }: { children: React.ReactNode }) {
+    let childArray = React.Children.toArray(children);
+
+    const leftContent = childArray.filter(
+        child => React.isValidElement(child) && child.type === PageActionBarLeft,
+    );
+    const rightContent = childArray.filter(
+        child => React.isValidElement(child) && child.type === PageActionBarRight,
+    );
+
+    return (
+        <div className={cn('flex gap-2', leftContent.length > 0 ? 'justify-between' : 'justify-end')}>
+            {leftContent.length > 0 && <div className="flex justify-start gap-2">{leftContent}</div>}
+            {rightContent.length > 0 && <div className="flex justify-end gap-2">{rightContent}</div>}
+        </div>
+    );
+}
+
+export function PageActionBarLeft({ children }: { children: React.ReactNode }) {
+    return <div className="flex justify-start gap-2">{children}</div>;
+}
+
+export function PageActionBarRight({ children }: { children: React.ReactNode }) {
+    const page = usePage();
+    const actionBarItems = page.pageId ? getDashboardActionBarItems(page.pageId) : [];
+    return (
+        <div className="flex justify-end gap-2">
+            {actionBarItems.map((item, index) => (
+                <PageActionBarItem key={index} item={item} page={page} />
+            ))}
+            {children}
+        </div>
+    );
+}
+
+function PageActionBarItem({ item, page }: { item: DashboardActionBarItem; page: PageContext }) {
+    return (
+        <PermissionGuard requires={item.requiresPermission ?? []}>
+            <item.component context={page} />
+        </PermissionGuard>
+    );
+}
+
+export type PageBlockProps = {
+    children?: React.ReactNode;
+    /** Which column this block should appear in */
+    column: 'main' | 'side';
+    blockId?: string;
+    title?: React.ReactNode | string;
+    description?: React.ReactNode | string;
+    className?: string;
+};
+
+export function PageBlock({ children, title, description, className, blockId }: PageBlockProps) {
+    return (
+        <LocationWrapper blockId={blockId}>
+            <Card className={cn('w-full', className)}>
+                {title || description ? (
+                    <CardHeader>
+                        {title && <CardTitle>{title}</CardTitle>}
+                        {description && <CardDescription>{description}</CardDescription>}
+                    </CardHeader>
+                ) : null}
+                <CardContent className={cn(!title ? 'pt-6' : '')}>{children}</CardContent>
+            </Card>
+        </LocationWrapper>
+    );
+}
+
+export function FullWidthPageBlock({
+    children,
+    className,
+    blockId,
+}: Pick<PageBlockProps, 'children' | 'className' | 'blockId'>) {
+    return (
+        <LocationWrapper blockId={blockId}>
+            <div className={cn('w-full', className)}>{children}</div>
+        </LocationWrapper>
+    );
+}
+
+export function CustomFieldsPageBlock({
+    column,
+    entityType,
+    control,
+}: {
+    column: 'main' | 'side';
+    entityType: string;
+    control: Control<any, any>;
+}) {
+    const customFieldConfig = useCustomFieldConfig(entityType);
+    if (!customFieldConfig || customFieldConfig.length === 0) {
+        return null;
+    }
+    return (
+        <PageBlock column={column} blockId="custom-fields">
+            <CustomFieldsForm entityType={entityType} control={control} />
+        </PageBlock>
+    );
+}

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

@@ -0,0 +1,66 @@
+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';
+
+interface NavMenuBaseItem {
+    id: string;
+    title: string;
+    icon?: LucideIcon;
+    placement?: NavMenuSectionPlacement;
+}
+
+export interface NavMenuItem extends NavMenuBaseItem {
+    url: string;
+}
+
+export interface NavMenuSection extends NavMenuBaseItem {
+    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);
+        }
+    }
+}