@vendure/dashboard 3.4.3-master-202509260228 → 3.5.0-minor-202510012036

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}

package/src/lib/framework/page/use-extended-router.tsx

@@ -1,4 +1,4 @@
-import { AnyRoute, createRoute, Router } from '@tanstack/react-router';
+import { AnyRoute, createRoute, createRouter, RouterOptions } from '@tanstack/react-router';
 import { useMemo } from 'react';
 import { ErrorPage } from '../../components/shared/error-page.js';
 import { AUTHENTICATED_ROUTE_PREFIX } from '../../constants.js';
@@ -6,63 +6,130 @@ import { useDashboardExtensions } from '../extension-api/use-dashboard-extension
 import { extensionRoutes } from './page-api.js';
 
 /**
- * Extends the TanStack Router with additional routes for each dashboard
- * extension.
+ * Creates a TanStack Router with the base route tree extended with additional
+ * routes from dashboard extensions.
  */
-export const useExtendedRouter = (router: Router<AnyRoute, any, any>) => {
+export const useExtendedRouter = (
+    baseRouteTree: AnyRoute,
+    routerOptions: Omit<RouterOptions<AnyRoute, any>, 'routeTree'>,
+) => {
     const { extensionsLoaded } = useDashboardExtensions();
 
     return useMemo(() => {
+        // Start with the base route tree
+        let routeTree = baseRouteTree;
+
+        // Only extend if extensions are loaded
         if (!extensionsLoaded) {
-            return router;
+            return createRouter({
+                ...routerOptions,
+                routeTree,
+            });
         }
 
-        const authenticatedRouteIndex = router.routeTree.children.findIndex(
+        const authenticatedRouteIndex = routeTree.children.findIndex(
             (r: AnyRoute) => r.id === AUTHENTICATED_ROUTE_PREFIX,
         );
 
         if (authenticatedRouteIndex === -1) {
-            return router;
+            // No authenticated route found, return router with base tree
+            return createRouter({
+                ...routerOptions,
+                routeTree,
+            });
         }
 
-        let authenticatedRoute: AnyRoute = router.routeTree.children[authenticatedRouteIndex];
+        let authenticatedRoute: AnyRoute = routeTree.children[authenticatedRouteIndex];
+
+        const newAuthenticatedRoutes: AnyRoute[] = [];
+        const newRootRoutes: AnyRoute[] = [];
 
-        const newRoutes: AnyRoute[] = [];
         // Create new routes for each extension
         for (const [path, config] of extensionRoutes.entries()) {
             const pathWithoutLeadingSlash = path.startsWith('/') ? path.slice(1) : path;
-            if (
-                authenticatedRoute.children.findIndex((r: AnyRoute) => r.path === pathWithoutLeadingSlash) >
-                -1
-            ) {
-                // Skip if the route already exists
-                continue;
+
+            // Check if route should be authenticated (default is true)
+            const isAuthenticated = config.authenticated !== false;
+
+            if (isAuthenticated) {
+                // Check if the route already exists under authenticated route
+                if (
+                    authenticatedRoute.children.findIndex(
+                        (r: AnyRoute) => r.path === pathWithoutLeadingSlash,
+                    ) > -1
+                ) {
+                    // Skip if the route already exists
+                    continue;
+                }
+
+                const newRoute: AnyRoute = createRoute({
+                    path: `/${pathWithoutLeadingSlash}`,
+                    getParentRoute: () => authenticatedRoute,
+                    loader: config.loader,
+                    validateSearch: config.validateSearch,
+                    component: () => config.component(newRoute),
+                    errorComponent: ({ error }) => <ErrorPage message={error.message} />,
+                });
+                newAuthenticatedRoutes.push(newRoute);
+            } else {
+                // Check if the route already exists at the root level
+                // Check both by path and by id (which includes the leading slash)
+                const routeExists =
+                    routeTree.children.some(
+                        (r: AnyRoute) =>
+                            r.path === `/${pathWithoutLeadingSlash}` ||
+                            r.path === pathWithoutLeadingSlash ||
+                            r.id === `/${pathWithoutLeadingSlash}`,
+                    ) ||
+                    newRootRoutes.some(
+                        (r: AnyRoute) =>
+                            r.path === `/${pathWithoutLeadingSlash}` ||
+                            r.id === `/${pathWithoutLeadingSlash}`,
+                    );
+
+                if (routeExists) {
+                    // Skip if the route already exists
+                    continue;
+                }
+
+                const newRoute: AnyRoute = createRoute({
+                    path: `/${pathWithoutLeadingSlash}`,
+                    getParentRoute: () => routeTree,
+                    loader: config.loader,
+                    validateSearch: config.validateSearch,
+                    component: () => config.component(newRoute),
+                    errorComponent: ({ error }) => <ErrorPage message={error.message} />,
+                });
+                newRootRoutes.push(newRoute);
             }
+        }
 
-            const newRoute: AnyRoute = createRoute({
-                path: `/${pathWithoutLeadingSlash}`,
-                getParentRoute: () => authenticatedRoute,
-                loader: config.loader,
-                component: () => config.component(newRoute),
-                errorComponent: ({ error }) => <ErrorPage message={error.message} />,
+        // Only extend the tree if we have new routes to add
+        if (newAuthenticatedRoutes.length === 0 && newRootRoutes.length === 0) {
+            return createRouter({
+                ...routerOptions,
+                routeTree,
             });
-            newRoutes.push(newRoute);
         }
 
-        const childrenWithoutAuthenticated = router.routeTree.children.filter(
+        const childrenWithoutAuthenticated = routeTree.children.filter(
             (r: AnyRoute) => r.id !== AUTHENTICATED_ROUTE_PREFIX,
         );
 
-        // Create a new router with the modified route tree
-        const newRouter = new Router({
-            routeTree: router.routeTree.addChildren([
-                ...childrenWithoutAuthenticated,
-                authenticatedRoute.addChildren([...authenticatedRoute.children, ...newRoutes]),
-            ]),
-            basepath: router.basepath,
-            defaultPreload: router.options.defaultPreload,
-            defaultPreloadDelay: router.options.defaultPreloadDelay,
+        const updatedAuthenticatedRoute = authenticatedRoute.addChildren([
+            ...authenticatedRoute.children,
+            ...newAuthenticatedRoutes,
+        ]);
+
+        const extendedRouteTree: AnyRoute = routeTree.addChildren([
+            ...childrenWithoutAuthenticated,
+            updatedAuthenticatedRoute,
+            ...newRootRoutes,
+        ]);
+
+        return createRouter({
+            ...routerOptions,
+            routeTree: extendedRouteTree,
         });
-        return newRouter;
-    }, [router, extensionsLoaded]);
+    }, [baseRouteTree, routerOptions, extensionsLoaded]);
 };

package/src/lib/graphql/api.ts

@@ -3,9 +3,13 @@ import { AwesomeGraphQLClient } from 'awesome-graphql-client';
 import { DocumentNode, print } from 'graphql';
 import { uiConfig } from 'virtual:vendure-ui-config';
 
+const host =
+    uiConfig.api.host !== 'auto'
+        ? uiConfig.api.host
+        : `${window.location.protocol}//${window.location.hostname}`;
 const API_URL =
-    (uiConfig.api.host !== "auto" ? uiConfig.api.host : `${window.location.protocol}//${window.location.hostname}`) +
-    `:${(uiConfig.api.port !== 'auto' ? uiConfig.api.port : window.location.port)}` +
+    host +
+    `:${uiConfig.api.port !== 'auto' ? uiConfig.api.port : window.location.port}` +
     `/${uiConfig.api.adminApiPath}`;
 
 export const SELECTED_CHANNEL_TOKEN_KEY = 'vendure-selected-channel-token';