@vendure/dashboard 3.4.3-master-202509250229 → 3.5.0-minor-202509261210

package/src/lib/framework/document-introspection/testing-utils.ts

@@ -0,0 +1,161 @@
+export function getMockSchemaInfo() {
+    return {
+        schemaInfo: {
+            types: {
+                Query: {
+                    products: ['ProductList', false, false, true],
+                    product: ['Product', false, false, false],
+                    collection: ['Collection', false, false, false],
+                    order: ['Order', false, false, false],
+                },
+                Mutation: {
+                    updateProduct: ['Product', false, false, false],
+                    adjustDraftOrderLine: ['Order', false, false, false],
+                },
+
+                Collection: {
+                    id: ['ID', false, false, false],
+                    name: ['String', false, false, false],
+                    productVariants: ['ProductVariantList', false, false, true],
+                },
+
+                ProductVariantList: {
+                    items: ['ProductVariant', false, true, false],
+                    totalItems: ['Int', false, false, false],
+                },
+
+                Product: {
+                    channels: ['Channel', false, true, false],
+                    id: ['ID', false, false, false],
+                    createdAt: ['DateTime', false, false, false],
+                    updatedAt: ['DateTime', false, false, false],
+                    languageCode: ['LanguageCode', false, false, false],
+                    name: ['String', false, false, false],
+                    slug: ['String', false, false, false],
+                    description: ['String', false, false, false],
+                    enabled: ['Boolean', false, false, false],
+                    featuredAsset: ['Asset', true, false, false],
+                    assets: ['Asset', false, true, false],
+                    variants: ['ProductVariant', false, true, false],
+                    variantList: ['ProductVariantList', false, false, true],
+                    optionGroups: ['ProductOptionGroup', false, true, false],
+                    facetValues: ['FacetValue', false, true, false],
+                    translations: ['ProductTranslation', false, true, false],
+                    collections: ['Collection', false, true, false],
+                    reviews: ['ProductReviewList', false, false, true],
+                    reviewsHistogram: ['ProductReviewHistogramItem', false, true, false],
+                    customFields: ['ProductCustomFields', true, false, false],
+                },
+                ProductVariantPrice: {
+                    currencyCode: ['CurrencyCode', false, false, false],
+                    price: ['Money', false, false, false],
+                    customFields: ['JSON', true, false, false],
+                },
+                ProductVariant: {
+                    enabled: ['Boolean', false, false, false],
+                    trackInventory: ['GlobalFlag', false, false, false],
+                    stockOnHand: ['Int', false, false, false],
+                    stockAllocated: ['Int', false, false, false],
+                    outOfStockThreshold: ['Int', false, false, false],
+                    useGlobalOutOfStockThreshold: ['Boolean', false, false, false],
+                    prices: ['ProductVariantPrice', false, true, false],
+                    stockLevels: ['StockLevel', false, true, false],
+                    stockMovements: ['StockMovementList', false, false, false],
+                    channels: ['Channel', false, true, false],
+                    id: ['ID', false, false, false],
+                    product: ['Product', false, false, false],
+                    productId: ['ID', false, false, false],
+                    createdAt: ['DateTime', false, false, false],
+                    updatedAt: ['DateTime', false, false, false],
+                    languageCode: ['LanguageCode', false, false, false],
+                    sku: ['String', false, false, false],
+                    name: ['String', false, false, false],
+                    featuredAsset: ['Asset', true, false, false],
+                    assets: ['Asset', false, true, false],
+                    price: ['Money', false, false, false],
+                    currencyCode: ['CurrencyCode', false, false, false],
+                    priceWithTax: ['Money', false, false, false],
+                    stockLevel: ['String', false, false, false],
+                    taxRateApplied: ['TaxRate', false, false, false],
+                    taxCategory: ['TaxCategory', false, false, false],
+                    options: ['ProductOption', false, true, false],
+                    facetValues: ['FacetValue', false, true, false],
+                    translations: ['ProductVariantTranslation', false, true, false],
+                    customFields: ['JSON', true, false, false],
+                },
+                ProductCustomFields: {
+                    custom1: ['String', false, false, false],
+                },
+
+                Asset: {
+                    id: ['ID', false, false, false],
+                    createdAt: ['DateTime', false, false, false],
+                    updatedAt: ['DateTime', false, false, false],
+                    name: ['String', false, false, false],
+                    type: ['AssetType', false, false, false],
+                    fileSize: ['Int', false, false, false],
+                    mimeType: ['String', false, false, false],
+                    width: ['Int', false, false, false],
+                    height: ['Int', false, false, false],
+                    source: ['String', false, false, false],
+                    preview: ['String', false, false, false],
+                    focalPoint: ['Coordinate', true, false, false],
+                    tags: ['Tag', false, true, false],
+                    customFields: ['JSON', true, false, false],
+                },
+                ProductTranslation: {
+                    id: ['ID', false, false, false],
+                    createdAt: ['DateTime', false, false, false],
+                    updatedAt: ['DateTime', false, false, false],
+                    languageCode: ['LanguageCode', false, false, false],
+                    name: ['String', false, false, false],
+                    slug: ['String', false, false, false],
+                    description: ['String', false, false, false],
+                    customFields: ['ProductTranslationCustomFields', true, false, false],
+                },
+                ProductList: {
+                    items: ['Product', false, true, false],
+                    totalItems: ['Int', false, false, false],
+                },
+
+                ProductVariantTranslation: {
+                    id: ['ID', false, false, false],
+                    createdAt: ['DateTime', false, false, false],
+                    updatedAt: ['DateTime', false, false, false],
+                    languageCode: ['LanguageCode', false, false, false],
+                    name: ['String', false, false, false],
+                },
+                Order: {
+                    id: ['ID', false, false, false],
+                    lines: ['OrderLine', false, true, false],
+                },
+                OrderLine: {
+                    id: ['ID', false, false, false],
+                    quantity: ['Int', false, false, false],
+                },
+            },
+            inputs: {
+                UpdateProductInput: {
+                    id: ['ID', false, false, false],
+                    name: ['String', false, false, false],
+                },
+                AdjustDraftOrderLineInput: {
+                    orderLineId: ['ID', false, false, false],
+                    quantity: ['Int', false, false, false],
+                },
+            },
+            scalars: [
+                'ID',
+                'String',
+                'Int',
+                'Boolean',
+                'Float',
+                'JSON',
+                'DateTime',
+                'Upload',
+                'CurrencyCode',
+            ],
+            enums: {},
+        },
+    };
+}

package/src/lib/framework/extension-api/display-component-extensions.tsx

@@ -1,5 +1,6 @@
 import { BooleanDisplayBadge, BooleanDisplayCheckbox } from '@/vdb/components/data-display/boolean.js';
 import { DateTime } from '@/vdb/components/data-display/date-time.js';
+import { Json } from '@/vdb/components/data-display/json.js';
 import { Money } from '@/vdb/components/data-display/money.js';
 import { VendureImage } from '@/vdb/components/shared/vendure-image.js';
 import { DataDisplayComponent } from '../component-registry/component-registry.js';
@@ -17,6 +18,7 @@ displayComponents.set('vendure:booleanBadge', BooleanDisplayBadge);
 displayComponents.set('vendure:dateTime', DateTime);
 displayComponents.set('vendure:asset', AssetDisplay);
 displayComponents.set('vendure:money', Money);
+displayComponents.set('vendure:json', Json);
 
 export function getDisplayComponent(id: string): DataDisplayComponent | undefined {
     return globalRegistry.get('displayComponents').get(id);

package/src/lib/framework/extension-api/types/data-table.ts

@@ -35,12 +35,70 @@ export type BulkActionComponent<Item extends { id: string } & Record<string, any
 
 /**
  * @description
- * **Status: Developer Preview**
- *
  * A bulk action is a component that will be rendered in the bulk actions dropdown.
  *
- * @docsCategory components
- * @docsPage DataTable
+ * The component receives the following props:
+ *
+ * - `selection`: The selected row or rows
+ * - `table`: A reference to the Tanstack table instance powering the list
+ *
+ * The `table` object has
+ *
+ * @example
+ * ```tsx
+ * import { BulkActionComponent, DataTableBulkActionItem, usePaginatedList } from '\@vendure/dashboard';
+ *
+ * // This is an example of a bulk action that shows some typical
+ * // uses of the provided props
+ * export const MyBulkAction: BulkActionComponent<any> = ({ selection, table }) => {
+ *   const { refetchPaginatedList } = usePaginatedList();
+ *
+ *   const doTheAction = async () => {
+ *     // Actual logic of the action
+ *     // goes here...
+ *
+ *     // On success, we refresh the list
+ *     refetchPaginatedList();
+ *     // and un-select any selected rows in the table
+ *     table.resetRowSelection();
+ *   };
+ *
+ *  return (
+ *    <DataTableBulkActionItem
+ *      onClick={doTheAction}
+ *      label={<Trans>Delete</Trans>}
+ *      confirmationText={<Trans>Are you sure?</Trans>}
+ *      icon={Check}
+ *      className="text-destructive"
+ *    />
+ *  );
+ * }
+ * ```
+ *
+ * For the common action of deletion, we provide a ready-made helper component:
+ *
+ * @example
+ * ```tsx
+ * import { BulkActionComponent, DeleteProductsBulkAction } from '\@vendure/dashboard';
+ *
+ * // Define the BulkAction component. This one uses
+ * // a built-in wrapper for "delete" actions, which includes
+ * // a confirmation dialog.
+ * export const DeleteProductsBulkAction: BulkActionComponent<any> = ({ selection, table }) => {
+ *     return (
+ *         <DeleteBulkAction
+ *             mutationDocument={deleteProductsDocument}
+ *             entityName="products"
+ *             requiredPermissions={['DeleteCatalog', 'DeleteProduct']}
+ *             selection={selection}
+ *             table={table}
+ *         />
+ *     );
+ * };
+ * ```
+ *
+ * @docsCategory list-views
+ * @docsPage bulk-actions
  * @since 3.4.0
  */
 export type BulkAction = {

package/src/lib/framework/extension-api/types/navigation.ts

@@ -40,6 +40,22 @@ export interface DashboardRouteDefinition {
      * [loader function](https://tanstack.com/router/latest/docs/framework/react/guide/data-loading#route-loaders)
      */
     loader?: RouteOptions['loader'];
+
+    /**
+     * @description
+     * Optional search parameter validation function.
+     * The value is a Tanstack Router
+     * [validateSearch function](https://tanstack.com/router/latest/docs/framework/react/guide/search-params#search-param-validation)
+     */
+    validateSearch?: RouteOptions['validateSearch'];
+
+    /**
+     * @description
+     * Define if the route should be under the authentication context, i.e have the authenticated route
+     * as a parent.
+     * @default true
+     */
+    authenticated?: boolean;
 }
 
 /**

package/src/lib/framework/form-engine/utils.ts

@@ -19,6 +19,8 @@ import {
     StructField,
     TextCustomFieldConfig,
 } from '@/vdb/framework/form-engine/form-engine-types.js';
+import { FormEvent } from 'react';
+import { UseFormReturn } from 'react-hook-form';
 
 import { FieldInfo } from '../document-introspection/get-document-structure.js';
 
@@ -320,3 +322,35 @@ export function hasPermissionRequirement(input: ConfigurableFieldDef): boolean {
 export function isNullableField(input: ConfigurableFieldDef): boolean {
     return isCustomFieldConfig(input) && Boolean(input.nullable);
 }
+
+/**
+ * Handles nested form submission to prevent event bubbling in nested forms.
+ * This is useful when you have a form inside a dialog that's within another form.
+ *
+ * @param form - The react-hook-form instance
+ * @param onSubmit - The submit handler function
+ * @returns An event handler that prevents propagation and handles the form submission
+ *
+ * @example
+ * ```tsx
+ * const form = useForm<FormSchema>({ resolver: zodResolver(formSchema) });
+ *
+ * return (
+ *   <form onSubmit={handleNestedFormSubmit(form, (data) => {
+ *     // Handle form submission
+ *   })}>
+ *     ...
+ *   </form>
+ * );
+ * ```
+ */
+export function handleNestedFormSubmit<TFieldValues extends Record<string, any>>(
+    form: UseFormReturn<TFieldValues>,
+    onSubmit: (data: TFieldValues) => void | Promise<void>,
+) {
+    return (e: FormEvent<HTMLFormElement>) => {
+        e.preventDefault();
+        e.stopPropagation();
+        void form.handleSubmit(onSubmit)(e);
+    };
+}

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

@@ -17,7 +17,6 @@ import { ColumnFiltersState, SortingState, Table } from '@tanstack/react-table';
 import { TableOptions } from '@tanstack/table-core';
 
 import { BulkAction } from '@/vdb/framework/extension-api/types/index.js';
-import { addCustomFields } from '../document-introspection/add-custom-fields.js';
 import { FullWidthPageBlock, Page, PageActionBar, PageLayout, PageTitle } from '../layout-engine/page-layout.js';
 
 /**
@@ -34,9 +33,62 @@ export interface ListPageProps<
     V extends ListQueryOptionsShape,
     AC extends AdditionalColumns<T>,
 > {
+    /**
+     * @description
+     * A unique identifier for the list page. This is important to support
+     * customization functionality that relies on page IDs and makes your
+     * component extensible.
+     */
     pageId?: string;
+    /**
+     @description
+     * The Tanstack Router `Route` object, which will be defined in the component file.
+     */
     route: AnyRoute | (() => AnyRoute);
+    /**
+     @description
+     * The page title, which will display in the header area.
+     */
     title: string | React.ReactElement;
+    /**
+     * @description
+     * This DocumentNode of the list query, i.e. a query that fetches
+     * PaginatedList data with "items" and "totalItems", such as:
+     *
+     * @example
+     * ```tsx
+     * export const collectionListDocument = graphql(`
+     *   query CollectionList($options: CollectionListOptions) {
+     *     collections(options: $options) {
+     *       items {
+     *         id
+     *         createdAt
+     *         updatedAt
+     *         name
+     *         slug
+     *         breadcrumbs {
+     *           id
+     *           name
+     *           slug
+     *         }
+     *         children {
+     *           id
+     *           name
+     *         }
+     *         # ... etc
+     *       }
+     *       totalItems
+     *     }
+     *   }
+     * `);
+     * // ...
+     * <ListPage
+     *   pageId="collection-list"
+     *   listQuery={collectionListDocument}
+     *   // ...
+     * />
+     * ```
+     */
     listQuery: T;
     /**
      * @description
@@ -46,20 +98,255 @@ export interface ListPageProps<
      * will be added to the action column dropdown already.
      */
     deleteMutation?: TypedDocumentNode<any, { id: string }>;
+    /**
+     * @description
+     * This prop can be used to intercept and transform the list query variables before they are
+     * sent to the Admin API.
+     *
+     * This allows you to implement specific logic that differs from the standard filter/sort
+     * handling.
+     *
+     * @example
+     * ```tsx
+     * <ListPage
+     *   pageId="collection-list"
+     *   title="Collections"
+     *   listQuery={collectionListDocument}
+     *   transformVariables={input => {
+     *       const filterTerm = input.options?.filter?.name?.contains;
+     *       // If there is a filter term set
+     *       // we want to return all results. Else
+     *       // we only want top-level Collections
+     *       const isFiltering = !!filterTerm;
+     *       return {
+     *           options: {
+     *               ...input.options,
+     *               topLevelOnly: !isFiltering,
+     *           },
+     *       };
+     *   }}
+     * />
+     * ```
+     */
     transformVariables?: (variables: V) => V;
+    /**
+     * @description
+     * Allows you to customize how the search term is used in the list query options.
+     * For instance, when you want the term to filter on specific fields.
+     *
+     * @example
+     * ```tsx
+     *  <ListPage
+     *    pageId="administrator-list"
+     *    title="Administrators"
+     *    listQuery={administratorListDocument}
+     *    onSearchTermChange={searchTerm => {
+     *      return {
+     *        firstName: { contains: searchTerm },
+     *        lastName: { contains: searchTerm },
+     *        emailAddress: { contains: searchTerm },
+     *      };
+     *    }}
+     *  />
+     * @param searchTerm
+     */
     onSearchTermChange?: (searchTerm: string) => NonNullable<V['options']>['filter'];
+    /**
+     * @description
+     * Allows you to customize the rendering and other aspects of individual columns.
+     *
+     * By default, an appropriate component will be chosen to render the column data
+     * based on the data type of the field. However, in many cases you want to have
+     * more control over how the column data is rendered.
+     *
+     * @example
+     * ```tsx
+     * <ListPage
+     *   pageId="collection-list"
+     *   listQuery={collectionListDocument}
+     *   customizeColumns={{
+     *     // The key "name" matches one of the top-level fields of the
+     *     // list query type (Collection, in this example)
+     *     name: {
+     *       meta: {
+     *           // The Dashboard optimizes the list query `collectionListDocument` to
+     *           // only select field that are actually visible in the ListPage table.
+     *           // However, sometimes you want to render data from other fields, i.e.
+     *           // this column has a data dependency on the "children" and "breadcrumbs"
+     *           // fields in order to correctly render the "name" field.
+     *           // In this case, we can declare those data dependencies which means whenever
+     *           // the "name" column is visible, it will ensure the "children" and "breadcrumbs"
+     *           // fields are also selected in the query.
+     *           dependencies: ['children', 'breadcrumbs'],
+     *       },
+     *       header: 'Collection Name',
+     *       cell: ({ row }) => {
+     *         const isExpanded = row.getIsExpanded();
+     *         const hasChildren = !!row.original.children?.length;
+     *         return (
+     *           <div
+     *             style={{ marginLeft: (row.original.breadcrumbs?.length - 2) * 20 + 'px' }}
+     *             className="flex gap-2 items-center"
+     *           >
+     *             <Button
+     *               size="icon"
+     *               variant="secondary"
+     *               onClick={row.getToggleExpandedHandler()}
+     *               disabled={!hasChildren}
+     *               className={!hasChildren ? 'opacity-20' : ''}
+     *             >
+     *               {isExpanded ? <FolderOpen /> : <Folder />}
+     *             </Button>
+     *             <DetailPageButton id={row.original.id} label={row.original.name} />
+     *           </div>
+     *           );
+     *       },
+     *     },
+     * ```
+     */
     customizeColumns?: CustomizeColumnConfig<T>;
+    /**
+     * @description
+     * Allows you to define extra columns that are not related to actual fields returned in
+     * the query result.
+     *
+     * For example, in the Administrator list, we define an additional "name" column composed
+     * of the `firstName` and `lastName` fields.
+     *
+     * @example
+     * ```tsx
+     * <ListPage
+     *   pageId="administrator-list"
+     *   title="Administrators"
+     *   listQuery={administratorListDocument}
+     *   additionalColumns={{
+     *     name: {
+     *         header: 'Name',
+     *         cell: ({ row }) => (
+     *             <DetailPageButton
+     *                 id={row.original.id}
+     *                 label={`${row.original.firstName} ${row.original.lastName}`}
+     *             />
+     *         ),
+     *   },
+     * />
+     * ```
+     */
     additionalColumns?: AC;
+    /**
+     * @description
+     * Allows you to specify the default order of columns in the table. When not defined, the
+     * order of fields in the list query document will be used.
+     */
     defaultColumnOrder?: (keyof ListQueryFields<T> | keyof AC | CustomFieldKeysOfItem<ListQueryFields<T>>)[];
+    /**
+     * @description
+     * Allows you to specify the default sorting applied to the table.
+     *
+     * @example
+     * ```tsx
+     * defaultSort={[{ id: 'orderPlacedAt', desc: true }]}
+     * ```
+     */
     defaultSort?: SortingState;
+    /**
+     * @description
+     * Allows you to specify the default columns that are visible in the table.
+     * If you set them to `true`, then only those will show by default. If you set them to `false`,
+     * then _all other_ columns will be visible by default.
+     *
+     * @example
+     * ```tsx
+     *  <ListPage
+     *    pageId="country-list"
+     *    listQuery={countriesListQuery}
+     *    title="Countries"
+     *    defaultVisibility={{
+     *        name: true,
+     *        code: true,
+     *        enabled: true,
+     *    }}
+     *  />
+     *  ```
+     */
     defaultVisibility?: Partial<
         Record<keyof ListQueryFields<T> | keyof AC | CustomFieldKeysOfItem<ListQueryFields<T>>, boolean>
     >;
     children?: React.ReactNode;
+    /**
+     * @description
+     * Allows you to define pre-set filters based on an array of possible selections
+     *
+     * @example
+     * ```tsx
+     * <ListPage
+     *   pageId="payment-method-list"
+     *   listQuery={paymentMethodListQuery}
+     *   title="Payment Methods"
+     *   facetedFilters={{
+     *       enabled: {
+     *           title: 'Enabled',
+     *           options: [
+     *               { label: 'Enabled', value: true },
+     *               { label: 'Disabled', value: false },
+     *           ],
+     *       },
+     *   }}
+     * />
+     * ```
+     */
     facetedFilters?: FacetedFilterConfig<T>;
+    /**
+     * @description
+     * Allows you to specify additional "actions" that will be made available in the "actions" column.
+     * By default, the actions column includes all bulk actions defined in the `bulkActions` prop.
+     */
     rowActions?: RowAction<ListQueryFields<T>>[];
+    /**
+     * @description
+     * Allows the returned list query data to be transformed in some way. This is an advanced feature
+     * that is not often required.
+     */
     transformData?: (data: any[]) => any[];
+    /**
+     * @description
+     * Allows you to directly manipulate the Tanstack Table `TableOptions` object before the
+     * table is created. And advanced option that is not often required.
+     */
     setTableOptions?: (table: TableOptions<any>) => TableOptions<any>;
+    /**
+     * @description
+     * Bulk actions are actions that can be applied to one or more table rows, and include things like
+     *
+     * - Deleting the rows
+     * - Assigning the rows to another channel
+     * - Bulk editing some aspect of the rows
+     *
+     * See the {@link BulkAction} docs for an example of how to build the component.
+     *
+     * @example
+     * ```tsx
+     * <ListPage
+     *   pageId="product-list"
+     *   listQuery={productListDocument}
+     *   title="Products"
+     *   bulkActions={[
+     *     {
+     *       component: AssignProductsToChannelBulkAction,
+     *       order: 100,
+     *     },
+     *     {
+     *       component: RemoveProductsFromChannelBulkAction,
+     *       order: 200,
+     *     },
+     *     {
+     *       component: DeleteProductsBulkAction,
+     *       order: 300,
+     *     },
+     *   ]}
+     * />
+     * ```
+     */
     bulkActions?: BulkAction[];
     /**
      * @description
@@ -242,8 +529,6 @@ export function ListPage<
         });
     }
 
-    const listQueryWithCustomFields = addCustomFields(listQuery);
-
     return (
         <Page pageId={pageId}>
             <PageTitle>{title}</PageTitle>
@@ -251,7 +536,7 @@ export function ListPage<
             <PageLayout>
                 <FullWidthPageBlock blockId="list-table">
                     <PaginatedListDataTable
-                        listQuery={listQueryWithCustomFields}
+                        listQuery={listQuery}
                         deleteMutation={deleteMutation}
                         transformVariables={transformVariables}
                         customizeColumns={customizeColumns as any}