@wilshop/dashboard 3.5.2

package/src/lib/framework/extension-api/logic/login.ts

@@ -0,0 +1,17 @@
+import { globalRegistry } from '../../registry/global-registry.js';
+import { DashboardLoginExtensions } from '../types/login.js';
+
+export function registerLoginExtensions(loginExtensions?: DashboardLoginExtensions) {
+    if (!loginExtensions) {
+        return;
+    }
+
+    const registryKey = 'loginExtensions';
+
+    globalRegistry.set(registryKey, (oldValue: DashboardLoginExtensions) => {
+        return {
+            ...oldValue,
+            ...loginExtensions,
+        };
+    });
+}

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

@@ -0,0 +1,41 @@
+import { addNavMenuItem, addNavMenuSection, NavMenuItem } from '../../nav-menu/nav-menu-extensions.js';
+import { registerRoute } from '../../page/page-api.js';
+import { DashboardNavSectionDefinition, DashboardRouteDefinition } from '../types/navigation.js';
+
+export function registerNavigationExtensions(
+    navSections?: DashboardNavSectionDefinition[],
+    routes?: DashboardRouteDefinition[],
+) {
+    if (navSections) {
+        for (const section of navSections) {
+            addNavMenuSection({
+                ...section,
+                placement: section.placement ?? 'top',
+                order: section.order ?? 999,
+                items: [],
+            });
+        }
+    }
+
+    if (routes) {
+        for (const route of routes) {
+            if (route.navMenuItem) {
+                // Add the nav menu item
+                const item: NavMenuItem = {
+                    url: route.navMenuItem.url ?? route.path,
+                    id: route.navMenuItem.id ?? route.path,
+                    title: route.navMenuItem.title ?? route.path,
+                    order: route.navMenuItem.order,
+                    requiresPermission: route.navMenuItem.requiresPermission,
+                    icon: route.navMenuItem.icon,
+                    placement: route.navMenuItem.placement,
+                };
+                addNavMenuItem(item, route.navMenuItem.sectionId);
+            }
+            if (route.path) {
+                // Configure a list page
+                registerRoute(route);
+            }
+        }
+    }
+}

package/src/lib/framework/extension-api/logic/widgets.ts

@@ -0,0 +1,10 @@
+import { registerDashboardWidget } from '../../dashboard-widget/widget-extensions.js';
+import { DashboardWidgetDefinition } from '../types/index.js';
+
+export function registerWidgetExtensions(widgets?: DashboardWidgetDefinition[]) {
+    if (widgets) {
+        for (const widget of widgets) {
+            registerDashboardWidget(widget);
+        }
+    }
+}

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

@@ -0,0 +1,59 @@
+export type AlertSeverity = 'info' | 'warning' | 'error';
+
+/**
+ * @description
+ * Allows you to define custom alerts that can be displayed in the dashboard.
+ *
+ * @docsCategory extensions-api
+ * @docsPage Alerts
+ * @since 3.3.0
+ */
+export interface DashboardAlertDefinition<TResponse = any> {
+    /**
+     * @description
+     * A unique identifier for the alert.
+     */
+    id: string;
+    /**
+     * @description
+     * The title of the alert. Can be a string or a function that returns a string based on the response data.
+     */
+    title: string | ((data: TResponse) => string);
+    /**
+     * @description
+     * The description of the alert. Can be a string or a function that returns a string based on the response data.
+     */
+    description?: string | ((data: TResponse) => string);
+    /**
+     * @description
+     * The severity level of the alert.
+     */
+    severity: AlertSeverity | ((data: TResponse) => AlertSeverity);
+    /**
+     * @description
+     * A function that checks the condition and returns the response data.
+     */
+    check: () => Promise<TResponse> | TResponse;
+    /**
+     * @description
+     * A function that determines whether the alert should be rendered based on the response data.
+     */
+    shouldShow: (data: TResponse) => boolean;
+    /**
+     * @description
+     * The interval in milliseconds to recheck the condition.
+     */
+    recheckInterval?: number;
+    /**
+     * @description
+     * Optional actions that can be performed when the alert is shown.
+     *
+     * The `onClick()` handler will receive the data returned by the `check` function,
+     * as well as a `dismiss()` function that can be used to immediately dismiss the
+     * current alert.
+     */
+    actions?: Array<{
+        label: string;
+        onClick: (args: { data: TResponse; dismiss: () => void }) => void | Promise<any>;
+    }>;
+}

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

@@ -0,0 +1,159 @@
+import { DataDisplayComponent } from '@/vdb/framework/component-registry/component-registry.js';
+import { Table } from '@tanstack/react-table';
+import { CellContext } from '@tanstack/table-core';
+import { DocumentNode } from 'graphql';
+import React from 'react';
+
+export type DataTableDisplayComponent = DataDisplayComponent<CellContext<any, any>>;
+
+/**
+ * @description
+ * Allows you to define custom display components for specific columns in data tables.
+ * The pageId is already defined in the data table extension, so only the column name is needed.
+ *
+ * @docsCategory extensions-api
+ * @docsPage DataTable
+ * @since 3.4.0
+ */
+export interface DashboardDataTableDisplayComponent {
+    /**
+     * @description
+     * The name of the column where this display component should be used.
+     */
+    column: string;
+    /**
+     * @description
+     * The React component that will be rendered as the display.
+     * It should accept `value` and other standard display props.
+     */
+    component: DataTableDisplayComponent;
+}
+
+export type BulkActionContext<Item extends { id: string } & Record<string, any>> = {
+    selection: Item[];
+    table: Table<Item>;
+};
+
+export type BulkActionComponent<Item extends { id: string } & Record<string, any>> = React.FunctionComponent<
+    BulkActionContext<Item>
+>;
+
+/**
+ * @description
+ * A bulk action is a component that will be rendered in the bulk actions dropdown.
+ *
+ * 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 = {
+    /**
+     * @description
+     * Optional order number to control the position of this bulk action in the dropdown.
+     * A larger number will appear lower in the list.
+     */
+    order?: number;
+    /**
+     * @description
+     * The React component that will be rendered as the bulk action item.
+     */
+    component: BulkActionComponent<any>;
+};
+
+/**
+ * @description
+ * This allows you to customize aspects of existing data tables in the dashboard.
+ *
+ * @docsCategory extensions-api
+ * @docsPage DataTables
+ * @since 3.4.0
+ */
+export interface DashboardDataTableExtensionDefinition {
+    /**
+     * @description
+     * The ID of the page where the data table is located, e.g. `'product-list'`, `'order-list'`.
+     */
+    pageId: string;
+    /**
+     * @description
+     * The ID of the data table block. Defaults to `'list-table'`, which is the default blockId
+     * for the standard list pages. However, some other pages may use a different blockId,
+     * such as `'product-variants-table'` on the `'product-detail'` page.
+     */
+    blockId?: string;
+    /**
+     * @description
+     * An array of additional bulk actions that will be available on the data table.
+     */
+    bulkActions?: BulkAction[];
+    /**
+     * @description
+     * Allows you to extend the list document for the data table.
+     */
+    extendListDocument?: string | DocumentNode | (() => DocumentNode | string);
+    /**
+     * @description
+     * Custom display components for specific columns in the data table.
+     */
+    displayComponents?: DashboardDataTableDisplayComponent[];
+}

package/src/lib/framework/extension-api/types/detail-forms.ts

@@ -0,0 +1,58 @@
+import { DashboardFormComponent } from '@/vdb/framework/form-engine/form-engine-types.js';
+import { DocumentNode } from 'graphql';
+
+/**
+ * @description
+ * Allows you to define custom input components for specific fields in detail forms.
+ * The pageId is already defined in the detail form extension, so only the blockId and field are needed.
+ *
+ * @docsCategory extensions-api
+ * @docsPage DetailForms
+ * @since 3.4.0
+ */
+export interface DashboardDetailFormInputComponent {
+    /**
+     * @description
+     * The ID of the block where this input component should be used.
+     */
+    blockId: string;
+    /**
+     * @description
+     * The name of the field where this input component should be used.
+     */
+    field: string;
+    /**
+     * @description
+     * The React component that will be rendered as the input.
+     * It should accept `value`, `onChange`, and other standard input props.
+     */
+    component: DashboardFormComponent;
+}
+
+/**
+ * @description
+ * Allows you to extend existing detail forms (e.g. on the product detail or customer detail pages)
+ * with custom GraphQL queries, input components, and display components.
+ *
+ * @since 3.4.0
+ * @docsPage DetailForms
+ * @docsCategory extensions-api
+ */
+export interface DashboardDetailFormExtensionDefinition {
+    /**
+     * @description
+     * The ID of the page where the detail form is located, e.g. `'product-detail'`, `'order-detail'`.
+     */
+    pageId: string;
+    /**
+     * @description
+     * Extends the GraphQL query used to fetch data for the detail page, allowing you to add additional
+     * fields that can be used by custom input or display components.
+     */
+    extendDetailDocument?: string | DocumentNode | (() => DocumentNode | string);
+    /**
+     * @description
+     * Custom input components for specific fields in the detail form.
+     */
+    inputs?: DashboardDetailFormInputComponent[];
+}

package/src/lib/framework/extension-api/types/form-components.ts

@@ -0,0 +1,41 @@
+import { DashboardFormComponent } from '@/vdb/framework/form-engine/form-engine-types.js';
+
+/**
+ * @description
+ * Allows you to define custom form components for custom fields in the dashboard.
+ *
+ * @docsCategory extensions-api
+ * @docsPage FormComponents
+ * @since 3.4.0
+ */
+export interface DashboardCustomFormComponent {
+    /**
+     * @description
+     * A unique identifier for the custom form component. It is a good practice to namespace
+     * these IDs to avoid naming collisions, for example `"my-plugin.markdown-editor"`.
+     */
+    id: string;
+    /**
+     * @description
+     * The React component that will be rendered as the custom form input.
+     */
+    component: DashboardFormComponent;
+}
+
+/**
+ * @description
+ * Interface for registering custom field components in the dashboard.
+ * For input and display components, use the co-located approach with detailForms.
+ *
+ * @docsCategory extensions-api
+ * @docsPage FormComponents
+ * @since 3.4.0
+ */
+export interface DashboardCustomFormComponents {
+    /**
+     * @description
+     * Custom form components for custom fields. These are used when rendering
+     * custom fields in forms.
+     */
+    customFields?: DashboardCustomFormComponent[];
+}

package/src/lib/framework/extension-api/types/history-entries.ts

@@ -0,0 +1,120 @@
+import React from 'react';
+
+import { CustomerHistoryCustomerDetail } from '../../../../app/routes/_authenticated/_customers/components/customer-history/customer-history-types.js';
+import { OrderHistoryOrderDetail } from '../../../../app/routes/_authenticated/_orders/components/order-history/order-history-types.js';
+
+/**
+ * @description
+ * This object contains the information about the history entry.
+ *
+ * @docsCategory extensions-api
+ * @docsPage HistoryEntries
+ * @since 3.4.3
+ */
+export interface HistoryEntryItem {
+    id: string;
+    /**
+     * @description
+     * The `HistoryEntryType`, such as `ORDER_STATE_TRANSITION`.
+     */
+    type: string;
+    createdAt: string;
+    /**
+     * @description
+     * Whether this entry is visible to customers via the Shop API
+     */
+    isPublic: boolean;
+    /**
+     * @description
+     * If an Administrator created this entry, their details will
+     * be available here.
+     */
+    administrator?: {
+        id: string;
+        firstName: string;
+        lastName: string;
+    } | null;
+    /**
+     * @description
+     * The entry payload data. This will be an object, which is different
+     * for each type of history entry.
+     *
+     * For example, the `CUSTOMER_ADDED_TO_GROUP` data looks like this:
+     * ```json
+     * {
+     *   groupName: 'Some Group',
+     * }
+     * ```
+     *
+     * and the `ORDER_STATE_TRANSITION` data looks like this:
+     * ```json
+     * {
+     *   from: 'ArrangingPayment',
+     *   to: 'PaymentSettled',
+     * }
+     * ```
+     */
+    data: any;
+}
+
+/**
+ * @description
+ * A definition of a custom component that will be used to render the given
+ * type of history entry.
+ *
+ * @example
+ * ```tsx
+ * import { defineDashboardExtension, HistoryEntry } from '\@vendure/dashboard';
+ * import { IdCard } from 'lucide-react';
+ *
+ * defineDashboardExtension({
+ *     historyEntries: [
+ *         {
+ *             type: 'CUSTOMER_TAX_ID_APPROVAL',
+ *             component: ({ entry, entity }) => {
+ *                 return (
+ *                     <HistoryEntry
+ *                         entry={entry}
+ *                         title={'Tax ID verified'}
+ *                         timelineIconClassName={'bg-success text-success-foreground'}
+ *                         timelineIcon={<IdCard />}
+ *                     >
+ *                         <div className="text-xs">Approval reference: {entry.data.ref}</div>
+ *                     </HistoryEntry>
+ *                 );
+ *             },
+ *         },
+ *     ],
+ *  });
+ *  ```
+ *
+ * @docsCategory extensions-api
+ * @docsPage HistoryEntries
+ * @since 3.4.3
+ * @docsWeight 0
+ */
+export interface DashboardHistoryEntryComponent {
+    /**
+     * @description
+     * The `type` should correspond to a valid `HistoryEntryType`, such as
+     *
+     * - `CUSTOMER_REGISTERED`
+     * - `ORDER_STATE_TRANSITION`
+     * - some custom type - see the {@link HistoryService} docs for a guide on
+     *   how to define custom history entry types.
+     */
+    type: string;
+    /**
+     * @description
+     * The component which is used to render the timeline entry. It should use the
+     * {@link HistoryEntry} component and pass the appropriate props to configure
+     * how it will be displayed.
+     *
+     * The `entity` prop will be a subset of the Order object for Order history entries,
+     * or a subset of the Customer object for customer history entries.
+     */
+    component: React.ComponentType<{
+        entry: HistoryEntryItem;
+        entity: OrderHistoryOrderDetail | CustomerHistoryCustomerDetail;
+    }>;
+}

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

@@ -0,0 +1,10 @@
+// Re-export all domain-specific types
+export * from './alerts.js';
+export * from './data-table.js';
+export * from './detail-forms.js';
+export * from './form-components.js';
+export * from './history-entries.js';
+export * from './layout.js';
+export * from './login.js';
+export * from './navigation.js';
+export * from './widgets.js';

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

@@ -0,0 +1,141 @@
+import type React from 'react';
+
+import { PageContextValue } from '../../layout-engine/page-provider.js';
+
+/**
+ * @description
+ * Allows you to define custom action bar items for any page in the dashboard, which is the
+ * top bar that normally contains the main call-to-action buttons such as "update" or "create".
+ *
+ * This API also allows you to specify dropdown menu items, which when defined, will appear in
+ * a context menu to the very right of the ActionBar.
+ *
+ * @docsCategory extensions-api
+ * @docsPage ActionBar
+ * @since 3.3.0
+ */
+export interface DashboardActionBarItem {
+    /**
+     * @description
+     * The ID of the page where the action bar item should be displayed.
+     */
+    pageId: string;
+    /**
+     * @description
+     * A React component that will be rendered in the action bar. Typically, you would use
+     * the default Shadcn `<Button>` component.
+     */
+    component: React.FunctionComponent<{ context: PageContextValue }>;
+    /**
+     * @description
+     * The type of action bar item to display. Defaults to `button`.
+     * The 'dropdown' type is used to display the action bar item as a dropdown menu item.
+     *
+     * When using the dropdown type, use a suitable [dropdown item](https://ui.shadcn.com/docs/components/dropdown-menu)
+     * component, such as:
+     *
+     * ```tsx
+     * import { DropdownMenuItem } from '\@vendure/dashboard';
+     *
+     * // ...
+     *
+     * {
+     *   component: () => <DropdownMenuItem>My Item</DropdownMenuItem>
+     * }
+     * ```
+     *
+     * @default 'button'
+     */
+    type?: 'button' | 'dropdown';
+    /**
+     * @description
+     * Any permissions that are required to display this action bar item.
+     */
+    requiresPermission?: string | string[];
+}
+
+/**
+ * @description
+ * The relative position of a PageBlock. This is determined by finding an existing
+ * block, and then specifying whether your custom block should come before, after,
+ * or completely replace that block.
+ *
+ * @docsCategory extensions-api
+ * @docsPage page-blocks
+ * @since 3.3.0
+ */
+export type PageBlockPosition = { blockId: string; order: 'before' | 'after' | 'replace' };
+
+/**
+ * @description
+ * The location of a page block in the dashboard. The location can be found by turning on
+ * "developer mode" in the dashboard user menu (bottom left corner) and then
+ * clicking the `< />` icon when hovering over a page block.
+ *
+ * @docsCategory extensions-api
+ * @docsPage page-blocks
+ * @since 3.3.0
+ */
+export type PageBlockLocation = {
+    pageId: string;
+    position: PageBlockPosition;
+    column: 'main' | 'side' | 'full';
+};
+
+/**
+ * @description
+ * This allows you to insert a custom component into a specific location
+ * on any page in the dashboard.
+ *
+ * @docsCategory extensions-api
+ * @docsPage page-blocks
+ * @docsWeight 0
+ * @since 3.3.0
+ */
+export interface DashboardPageBlockDefinition {
+    /**
+     * @description
+     * An ID for the page block. Should be unique at least
+     * to the page in which it appears.
+     */
+    id: string;
+    /**
+     * @description
+     * An optional title for the page block
+     */
+    title?: React.ReactNode;
+    /**
+     * @description
+     * The location of the page block. It specifies the pageId, and then the
+     * relative location compared to another existing block.
+     */
+    location: PageBlockLocation;
+    /**
+     * @description
+     * The component to be rendered inside the page block.
+     */
+    component?: React.FunctionComponent<{ context: PageContextValue }>;
+    /**
+     * @description
+     * Control whether to render the page block depending on your custom
+     * logic.
+     *
+     * This can also be used to disable any built-in blocks you
+     * do not need to display.
+     *
+     * If you need to query aspects about the current context not immediately
+     * provided in the `PageContextValue`, you can also use hooks such as
+     * `useChannel` in this function.
+     *
+     * @since 3.5.0
+     */
+    shouldRender?: (context: PageContextValue) => boolean;
+    /**
+     * @description
+     * If provided, the logged-in user must have one or more of the specified
+     * permissions in order for the block to render.
+     *
+     * For more advanced control over rendering, use the `shouldRender` function.
+     */
+    requiresPermission?: string | string[];
+}