@vendure/dashboard 3.2.4 → 3.3.0

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

@@ -7,13 +7,14 @@ import { usePage } from '@/hooks/use-page.js';
 import { cn } from '@/lib/utils.js';
 import { NavigationConfirmation } from '@/components/shared/navigation-confirmation.js';
 import { useMediaQuery } from '@uidotdev/usehooks';
-import React, { ComponentProps, createContext } from 'react';
+import React, { ComponentProps } 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';
+import { PageContext, PageContextValue } from '@/framework/layout-engine/page-provider.js';
 
 export interface PageProps extends ComponentProps<'div'> {
     pageId?: string;
@@ -22,18 +23,34 @@ export interface PageProps extends ComponentProps<'div'> {
     submitHandler?: any;
 }
 
-export const PageProvider = createContext<PageContext | undefined>(undefined);
-
+/**
+ * @description
+ * **Status: Developer Preview**
+ *
+ * This component should be used to wrap _all_ pages in the dashboard. It provides
+ * a consistent layout as well as a context for the slot-based PageBlock system.
+ *
+ * The typical hierarchy of a page is as follows:
+ * - `Page`
+ *  - {@link PageTitle}
+ *  - {@link PageActionBar}
+ *  - {@link PageLayout}
+ *
+ * @docsCategory components
+ * @docsPage Page
+ * @docsWeight 0
+ * @since 3.3.0
+ */
 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,
+        child => isOfType(child, PageActionBar),
     );
 
     const pageContent = childArray.filter(
-        child => React.isValidElement(child) && child.type !== PageTitle && child.type !== PageActionBar,
+        child => !isOfType(child, PageTitle) && !isOfType(child, PageActionBar),
     );
 
     const pageHeader = (
@@ -43,7 +60,48 @@ export function Page({ children, pageId, entity, form, submitHandler, ...props }
         </div>
     );
 
-    const pageContentWithOptionalForm = form ? (
+    return (
+        <PageContext.Provider value={{ pageId, form, entity }}>
+            <PageContent
+                pageHeader={pageHeader}
+                pageContent={pageContent}
+                form={form}
+                submitHandler={submitHandler}
+                className={props.className}
+                {...props}
+            />
+        </PageContext.Provider>
+    );
+}
+
+function PageContent({ pageHeader, pageContent, form, submitHandler, ...props }: {
+    pageHeader: React.ReactNode;
+    pageContent: React.ReactNode;
+    form?: UseFormReturn<any>;
+    submitHandler?: any;
+    className?: string;
+}) {
+    return (
+        <div className={cn('m-4', props.className)} {...props}>
+            <LocationWrapper>
+                <PageContentWithOptionalForm
+                    pageHeader={pageHeader}
+                    pageContent={pageContent}
+                    form={form}
+                    submitHandler={submitHandler}
+                />
+            </LocationWrapper>
+        </div>
+    );
+}
+
+export function PageContentWithOptionalForm({ form, pageHeader, pageContent, submitHandler }: {
+    form?: UseFormReturn<any>;
+    pageHeader: React.ReactNode
+    pageContent: React.ReactNode;
+    submitHandler?: any;
+}) {
+    return form ? (
         <Form {...form}>
             <NavigationConfirmation form={form} />
             <form onSubmit={submitHandler} className="space-y-4">
@@ -57,18 +115,16 @@ export function Page({ children, pageId, entity, form, submitHandler, ...props }
             {pageContent}
         </div>
     );
-
-    return (
-        <PageProvider value={{ pageId, form, entity }}>
-            <LocationWrapper>
-                <div className={cn('m-4', props.className)} {...props}>
-                    {pageContentWithOptionalForm}
-                </div>
-            </LocationWrapper>
-        </PageProvider>
-    );
 }
 
+/**
+ * @description
+ * **Status: Developer Preview**
+ *
+ * @docsCategory components
+ * @docsPage PageLayout
+ * @since 3.3.0
+ */
 export type PageLayoutProps = {
     children: React.ReactNode;
     className?: string;
@@ -87,6 +143,18 @@ function isPageBlock(child: unknown): child is React.ReactElement<PageBlockProps
     return hasColumn || hasBlockId;
 }
 
+/**
+ * @description
+ * **Status: Developer Preview**
+ *
+ * This component governs the layout of the contents of a {@link Page} component.
+ * It should contain all the {@link PageBlock} components that are to be displayed on the page.
+ *
+ * @docsCategory components
+ * @docsPage PageLayout
+ * @docsWeight 0
+ * @since 3.3.0
+ */
 export function PageLayout({ children, className }: PageLayoutProps) {
     const page = usePage();
     const isDesktop = useMediaQuery('only screen and (min-width : 769px)');
@@ -112,7 +180,7 @@ export function PageLayout({ children, className }: PageLayoutProps) {
         if (childBlock) {
             const blockId =
                 childBlock.props.blockId ??
-                (childBlock.type === CustomFieldsPageBlock ? 'custom-fields' : undefined);
+                (isOfType(childBlock, CustomFieldsPageBlock) ? 'custom-fields' : undefined);
             const extensionBlock = extensionBlocks.find(block => block.location.position.blockId === blockId);
             if (extensionBlock) {
                 const ExtensionBlock = (
@@ -138,7 +206,7 @@ export function PageLayout({ children, className }: PageLayoutProps) {
     }
 
     const fullWidthBlocks = finalChildArray.filter(
-        child => isPageBlock(child) && child.type === FullWidthPageBlock,
+        child => isPageBlock(child) && isOfType(child, FullWidthPageBlock),
     );
     const mainBlocks = finalChildArray.filter(child => isPageBlock(child) && child.props.column === 'main');
     const sideBlocks = finalChildArray.filter(child => isPageBlock(child) && child.props.column === 'side');
@@ -164,24 +232,41 @@ 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>;
-}
-
+/**
+ * @description
+ * **Status: Developer Preview**
+ *
+ * A component for displaying the title of a page. This should be used inside the {@link Page} component.
+ *
+ * @docsCategory components
+ * @docsPage PageTitle
+ * @since 3.3.0
+ */
 export function PageTitle({ children }: { children: React.ReactNode }) {
     return <h1 className="text-2xl font-semibold">{children}</h1>;
 }
 
+/**
+ * @description
+ * **Status: Developer Preview**
+ *
+ * A component for displaying the main actions for a page. This should be used inside the {@link Page} component.
+ * It should be used in conjunction with the {@link PageActionBarLeft} and {@link PageActionBarRight} components
+ * as direct children.
+ *
+ * @docsCategory components
+ * @docsPage PageActionBar
+ * @docsWeight 0
+ * @since 3.3.0
+ */
 export function PageActionBar({ children }: { children: React.ReactNode }) {
     let childArray = React.Children.toArray(children);
 
     const leftContent = childArray.filter(
-        child => React.isValidElement(child) && child.type === PageActionBarLeft,
+        child => isOfType(child, PageActionBarLeft),
     );
     const rightContent = childArray.filter(
-        child => React.isValidElement(child) && child.type === PageActionBarRight,
+        child => isOfType(child, PageActionBarRight),
     );
 
     return (
@@ -192,10 +277,26 @@ export function PageActionBar({ children }: { children: React.ReactNode }) {
     );
 }
 
+/**
+ * @description
+ * **Status: Developer Preview**
+ *
+ * @docsCategory components
+ * @docsPage PageActionBar
+ * @since 3.3.0
+ */
 export function PageActionBarLeft({ children }: { children: React.ReactNode }) {
     return <div className="flex justify-start gap-2">{children}</div>;
 }
 
+/**
+ * @description
+ * **Status: Developer Preview**
+ *
+ * @docsCategory components
+ * @docsPage PageActionBar
+ * @since 3.3.0
+ */
 export function PageActionBarRight({ children }: { children: React.ReactNode }) {
     const page = usePage();
     const actionBarItems = page.pageId ? getDashboardActionBarItems(page.pageId) : [];
@@ -209,7 +310,7 @@ export function PageActionBarRight({ children }: { children: React.ReactNode })
     );
 }
 
-function PageActionBarItem({ item, page }: { item: DashboardActionBarItem; page: PageContext }) {
+function PageActionBarItem({ item, page }: { item: DashboardActionBarItem; page: PageContextValue }) {
     return (
         <PermissionGuard requires={item.requiresPermission ?? []}>
             <item.component context={page} />
@@ -217,6 +318,14 @@ function PageActionBarItem({ item, page }: { item: DashboardActionBarItem; page:
     );
 }
 
+/**
+ * @description
+ * **Status: Developer Preview**
+ *
+ * @docsCategory components
+ * @docsPage PageBlock
+ * @since 3.3.0
+ */
 export type PageBlockProps = {
     children?: React.ReactNode;
     /** Which column this block should appear in */
@@ -227,6 +336,19 @@ export type PageBlockProps = {
     className?: string;
 };
 
+/**
+ * @description
+ * **Status: Developer Preview**
+ *
+ * A component for displaying a block of content on a page. This should be used inside the {@link PageLayout} component.
+ * It should be provided with a `column` prop to determine which column it should appear in, and a `blockId` prop
+ * to identify the block.
+ *
+ * @docsCategory components
+ * @docsPage PageBlock
+ * @docsWeight 0
+ * @since 3.3.0
+ */
 export function PageBlock({ children, title, description, className, blockId }: PageBlockProps) {
     return (
         <LocationWrapper blockId={blockId}>
@@ -243,11 +365,22 @@ export function PageBlock({ children, title, description, className, blockId }:
     );
 }
 
+/**
+ * @description
+ * **Status: Developer Preview**
+ *
+ * A component for displaying a block of content on a page that takes up the full width of the page.
+ * This should be used inside the {@link PageLayout} component.
+ *
+ * @docsCategory components
+ * @docsPage PageBlock
+ * @since 3.3.0
+ */
 export function FullWidthPageBlock({
-    children,
-    className,
-    blockId,
-}: Pick<PageBlockProps, 'children' | 'className' | 'blockId'>) {
+                                       children,
+                                       className,
+                                       blockId,
+                                   }: Pick<PageBlockProps, 'children' | 'className' | 'blockId'>) {
     return (
         <LocationWrapper blockId={blockId}>
             <div className={cn('w-full', className)}>{children}</div>
@@ -255,11 +388,21 @@ export function FullWidthPageBlock({
     );
 }
 
+/**
+ * @description
+ * **Status: Developer Preview**
+ *
+ * A component for displaying an auto-generated form for custom fields on a page.
+ *
+ * @docsCategory components
+ * @docsPage PageBlock
+ * @since 3.3.0
+ */
 export function CustomFieldsPageBlock({
-    column,
-    entityType,
-    control,
-}: {
+                                          column,
+                                          entityType,
+                                          control,
+                                      }: {
     column: 'main' | 'side';
     entityType: string;
     control: Control<any, any>;
@@ -274,3 +417,17 @@ export function CustomFieldsPageBlock({
         </PageBlock>
     );
 }
+
+/**
+ * @description
+ * This compares the type of a React component to a given type.
+ * It is safer than a simple `el === Component` check, as it also works in the context of
+ * the Vite build where the component is not the same reference.
+ */
+export function isOfType(el: unknown, type: React.FunctionComponent<any>): boolean {
+    if (React.isValidElement(el)) {
+        const elTypeName = typeof el.type === 'string' ? el.type : (el.type as React.FunctionComponent).name;
+        return elTypeName === type.name;
+    }
+    return false;
+}

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

@@ -3,19 +3,19 @@ import { Input } from '@/components/ui/input.js';
 import { useDetailPage } from '@/framework/page/use-detail-page.js';
 import { Trans } from '@/lib/trans.js';
 import type { TypedDocumentNode } from '@graphql-typed-document-node/core';
-import { AnyRoute } from '@tanstack/react-router';
+import { AnyRoute, useNavigate } from '@tanstack/react-router';
 import { ResultOf, VariablesOf } from 'gql.tada';
-
 import { DateTimeInput } from '@/components/data-input/datetime-input.js';
 import { Button } from '@/components/ui/button.js';
 import { Checkbox } from '@/components/ui/checkbox.js';
+import { NEW_ENTITY_PATH } from '@/constants.js';
 import { toast } from 'sonner';
 import { getOperationVariablesFields } from '../document-introspection/get-document-structure.js';
+
 import {
     DetailFormGrid,
     Page,
     PageActionBar,
-    PageActionBarLeft,
     PageActionBarRight,
     PageBlock,
     PageLayout,
@@ -23,21 +23,70 @@ import {
 } from '../layout-engine/page-layout.js';
 import { DetailEntityPath } from './page-types.js';
 
+/**
+ * @description
+ * **Status: Developer Preview**
+ *
+ * @docsCategory components
+ * @docsPage DetailPage
+ * @since 3.3.0
+ */
 export interface DetailPageProps<
     T extends TypedDocumentNode<any, any>,
     C extends TypedDocumentNode<any, any>,
     U extends TypedDocumentNode<any, any>,
     EntityField extends keyof ResultOf<T> = DetailEntityPath<T>,
 > {
+    /**
+     * @description
+     * A unique identifier for the page.
+     */
     pageId: string;
+    /**
+     * @description
+     * The Tanstack Router route used to navigate to this page.
+     */
     route: AnyRoute;
+    /**
+     * @description
+     * The title of the page.
+     */
     title: (entity: ResultOf<T>[EntityField]) => string;
+    /**
+     * @description
+     * The query document used to fetch the entity.
+     */
     queryDocument: T;
+    /**
+     * @description
+     * The mutation document used to create the entity.
+     */
     createDocument?: C;
+    /**
+     * @description
+     * The mutation document used to update the entity.
+     */
     updateDocument: U;
+    /**
+     * @description
+     * A function that sets the values for the update input type based on the entity.
+     */
     setValuesForUpdate: (entity: ResultOf<T>[EntityField]) => VariablesOf<U>['input'];
 }
 
+/**
+ * @description
+ * **Status: Developer Preview**
+ *
+ * Auto-generates a detail page with a form based on the provided query and mutation documents.
+ *
+ * For more control over the layout, you would use the more low-level {@link Page} component.
+ *
+ * @docsCategory components
+ * @docsPage DetailPage
+ * @docsWeight 0
+ * @since 3.3.0
+ */
 export function DetailPage<
     T extends TypedDocumentNode<any, any>,
     C extends TypedDocumentNode<any, any>,
@@ -52,6 +101,8 @@ export function DetailPage<
     title,
 }: DetailPageProps<T, C, U>) {
     const params = route.useParams();
+    const creatingNewEntity = params.id === NEW_ENTITY_PATH;
+    const navigate = useNavigate();
 
     const { form, submitHandler, entity, isPending, resetForm } = useDetailPage<any, any, any>({
         queryDocument,
@@ -59,9 +110,13 @@ export function DetailPage<
         createDocument,
         params: { id: params.id },
         setValuesForUpdate,
-        onSuccess: () => {
+        onSuccess: async (data) => {
             toast.success('Updated successfully');
             resetForm();
+            const id = (data as any).id;
+            if (creatingNewEntity && id) {
+                await navigate({ to: `../$id`, params: { id } });
+            }
         },
         onError: error => {
             toast.error('Failed to update', {
@@ -70,14 +125,12 @@ export function DetailPage<
         },
     });
 
-    const updateFields = getOperationVariablesFields(updateDocument);
+    const updateFields = getOperationVariablesFields(updateDocument, 'input');
 
     return (
         <Page pageId={pageId} form={form} submitHandler={submitHandler}>
+            <PageTitle>{title(entity)}</PageTitle>
             <PageActionBar>
-                <PageActionBarLeft>
-                    <PageTitle>{title(entity)}</PageTitle>
-                </PageActionBarLeft>
                 <PageActionBarRight>
                     <Button
                         type="submit"
@@ -114,7 +167,7 @@ export function DetailPage<
                                             case 'DateTime':
                                                 return <DateTimeInput {...field} />;
                                             case 'Boolean':
-                                                return <Checkbox {...field} />;
+                                                return <Checkbox value={field.value} onCheckedChange={field.onChange} />;
                                             case 'String':
                                             default:
                                                 return <Input {...field} />;

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

@@ -31,6 +31,14 @@ type ListQueryFields<T extends TypedDocumentNode<any, any>> = {
         : never;
 }[keyof ResultOf<T>];
 
+/**
+ * @description
+ * **Status: Developer Preview**
+ *
+ * @docsCategory components
+ * @docsPage ListPage
+ * @since 3.3.0
+ */
 export interface ListPageProps<
     T extends TypedDocumentNode<U, V>,
     U extends ListQueryShape,
@@ -56,6 +64,17 @@ export interface ListPageProps<
     setTableOptions?: (table: TableOptions<any>) => TableOptions<any>;
 }
 
+/**
+ * @description
+ * **Status: Developer Preview**
+ *
+ * Auto-generates a list page with columns generated based on the provided query document fields.
+ *
+ * @docsCategory components
+ * @docsPage ListPage
+ * @docsWeight 0
+ * @since 3.3.0
+ */
 export function ListPage<
     T extends TypedDocumentNode<U, V>,
     U extends Record<string, any> = any,

package/src/lib/framework/page/page-api.ts

@@ -1,4 +1,4 @@
-import { DashboardRouteDefinition } from '@/framework/extension-api/extension-api-types.js';
+import { DashboardRouteDefinition } from '../extension-api/extension-api-types.js';
 
 export const extensionRoutes = new Map<string, DashboardRouteDefinition>();
 

package/src/lib/framework/page/use-detail-page.ts

@@ -26,6 +26,14 @@ type RemoveNullFields<T> = {
     [K in keyof T]: RemoveNull<T[K]>;
 };
 
+/**
+ * @description
+ * **Status: Developer Preview**
+ *
+ * @docsCategory hooks
+ * @docsPage useDetailPage
+ * @since 3.3.0
+ */
 export interface DetailPageOptions<
     T extends TypedDocumentNode<any, any>,
     C extends TypedDocumentNode<any, any>,
@@ -114,6 +122,14 @@ export type DetailPageEntity<
     translations: DetailPageTranslations<T, EntityField>;
 };
 
+/**
+ * @description
+ * **Status: Developer Preview**
+ *
+ * @docsCategory hooks
+ * @docsPage useDetailPage
+ * @since 3.3.0
+ */
 export interface UseDetailPageResult<
     T extends TypedDocumentNode<any, any>,
     C extends TypedDocumentNode<any, any>,
@@ -130,8 +146,72 @@ export interface UseDetailPageResult<
 
 /**
  * @description
+ * **Status: Developer Preview**
+ *
  * This hook is used to create an entity detail page which can read
  * and update an entity.
+ *
+ * @example
+ * ```ts
+ * const { form, submitHandler, entity, isPending, resetForm } = useDetailPage({
+ *     queryDocument: paymentMethodDetailDocument,
+ *     createDocument: createPaymentMethodDocument,
+ *     updateDocument: updatePaymentMethodDocument,
+ *     setValuesForUpdate: entity => {
+ *         return {
+ *             id: entity.id,
+ *             enabled: entity.enabled,
+ *             name: entity.name,
+ *             code: entity.code,
+ *             description: entity.description,
+ *             checker: entity.checker?.code
+ *                 ? {
+ *                       code: entity.checker?.code,
+ *                       arguments: entity.checker?.args,
+ *                   }
+ *                 : null,
+ *             handler: entity.handler?.code
+ *                 ? {
+ *                       code: entity.handler?.code,
+ *                       arguments: entity.handler?.args,
+ *                   }
+ *                 : null,
+ *             translations: entity.translations.map(translation => ({
+ *                 id: translation.id,
+ *                 languageCode: translation.languageCode,
+ *                 name: translation.name,
+ *                 description: translation.description,
+ *             })),
+ *             customFields: entity.customFields,
+ *         };
+ *     },
+ *     transformCreateInput: input => {
+ *         return {
+ *             ...input,
+ *             checker: input.checker?.code ? input.checker : undefined,
+ *             handler: input.handler,
+ *         };
+ *     },
+ *     params: { id: params.id },
+ *     onSuccess: async data => {
+ *         toast.success(i18n.t('Successfully updated payment method'));
+ *         resetForm();
+ *         if (creatingNewEntity) {
+ *             await navigate({ to: `../$id`, params: { id: data.id } });
+ *         }
+ *     },
+ *     onError: err => {
+ *         toast.error(i18n.t('Failed to update payment method'), {
+ *             description: err instanceof Error ? err.message : 'Unknown error',
+ *         });
+ *     },
+ * });
+ * ```
+ *
+ * @docsCategory hooks
+ * @docsPage useDetailPage
+ * @docsWeight 0
+ * @since 3.3.0
  */
 export function useDetailPage<
     T extends TypedDocumentNode<any, any>,
@@ -178,6 +258,7 @@ export function useDetailPage<
                 onSuccess?.((data as any)[createMutationName]);
             }
         },
+        onError,
     });
 
     const updateMutation = useMutation({

package/src/lib/framework/registry/registry-types.ts

@@ -1,6 +1,9 @@
+import { DashboardAlertDefinition } from '../alert/types.js';
 import { DashboardWidgetDefinition } from '../dashboard-widget/types.js';
-import { DashboardActionBarItem } from '../extension-api/extension-api-types.js';
-import { DashboardPageBlockDefinition } from '../extension-api/extension-api-types.js';
+import {
+    DashboardActionBarItem,
+    DashboardPageBlockDefinition,
+} from '../extension-api/extension-api-types.js';
 import { NavMenuConfig } from '../nav-menu/nav-menu-extensions.js';
 
 export interface GlobalRegistryContents {
@@ -10,6 +13,7 @@ export interface GlobalRegistryContents {
     dashboardActionBarItemRegistry: Map<string, DashboardActionBarItem[]>;
     dashboardPageBlockRegistry: Map<string, DashboardPageBlockDefinition[]>;
     dashboardWidgetRegistry: Map<string, DashboardWidgetDefinition>;
+    dashboardAlertRegistry: Map<string, DashboardAlertDefinition>;
 }
 
 export type GlobalRegistryKey = keyof GlobalRegistryContents;