@vendure/dashboard 3.4.3-master-202509230228 → 3.4.3-master-202509240228

package/src/lib/components/shared/history-timeline/history-timeline-with-grouping.tsx

@@ -0,0 +1,141 @@
+import { Button } from '@/vdb/components/ui/button.js';
+import { HistoryEntryItem } from '@/vdb/framework/extension-api/types/history-entries.js';
+import { getCustomHistoryEntryForType } from '@/vdb/framework/history-entry/history-entry-extensions.js';
+import { ChevronDown, ChevronUp } from 'lucide-react';
+import { ReactNode, useState } 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';
+import { HistoryTimeline } from './history-timeline.js';
+
+interface HistoryTimelineWithGroupingProps {
+    historyEntries: HistoryEntryItem[];
+    entity: OrderHistoryOrderDetail | CustomerHistoryCustomerDetail;
+    isPrimaryEvent: (entry: HistoryEntryItem) => boolean;
+    renderEntryContent: (entry: HistoryEntryItem) => ReactNode;
+    children?: ReactNode;
+}
+
+type EntryWithIndex = {
+    entry: HistoryEntryItem;
+    index: number;
+};
+
+export function HistoryTimelineWithGrouping({
+    historyEntries,
+    entity,
+    isPrimaryEvent,
+    renderEntryContent,
+    children,
+}: Readonly<HistoryTimelineWithGroupingProps>) {
+    const [expandedGroups, setExpandedGroups] = useState<Set<number>>(new Set());
+
+    // Group consecutive secondary events
+    const groupedEntries: Array<
+        | ({ type: 'primary' } & EntryWithIndex)
+        | {
+              type: 'secondary-group';
+              entries: Array<EntryWithIndex>;
+              startIndex: number;
+          }
+    > = [];
+    let currentGroup: Array<EntryWithIndex> = [];
+
+    for (let i = 0; i < historyEntries.length; i++) {
+        const entry = historyEntries[i];
+        const isSecondary = !isPrimaryEvent(entry);
+
+        if (isSecondary) {
+            currentGroup.push({ entry, index: i });
+        } else {
+            // If we have accumulated secondary events, add them as a group
+            if (currentGroup.length > 0) {
+                groupedEntries.push({
+                    type: 'secondary-group',
+                    entries: currentGroup,
+                    startIndex: currentGroup[0].index,
+                });
+                currentGroup = [];
+            }
+            // Add the primary event
+            groupedEntries.push({ type: 'primary', entry, index: i });
+        }
+    }
+
+    // Don't forget the last group if it exists
+    if (currentGroup.length > 0) {
+        groupedEntries.push({
+            type: 'secondary-group',
+            entries: currentGroup,
+            startIndex: currentGroup[0].index,
+        });
+    }
+
+    const renderEntry = (entry: HistoryEntryItem) => {
+        const CustomType = getCustomHistoryEntryForType(entry.type);
+        if (CustomType) {
+            return <CustomType entry={entry} entity={entity} />;
+        } else {
+            return renderEntryContent(entry);
+        }
+    };
+
+    const toggleGroup = (groupIndex: number) => {
+        const newExpanded = new Set(expandedGroups);
+        if (newExpanded.has(groupIndex)) {
+            newExpanded.delete(groupIndex);
+        } else {
+            newExpanded.add(groupIndex);
+        }
+        setExpandedGroups(newExpanded);
+    };
+
+    return (
+        <div className="">
+            {children && <div className="mb-4">{children}</div>}
+            <HistoryTimeline>
+                {groupedEntries.map((group, groupIndex) => {
+                    if (group.type === 'primary') {
+                        const entry = group.entry;
+                        return <div key={entry.id}>{renderEntry(entry)}</div>;
+                    } else {
+                        // Secondary group
+                        const shouldCollapse = group.entries.length > 2;
+                        const isExpanded = expandedGroups.has(groupIndex);
+                        const visibleEntries =
+                            shouldCollapse && !isExpanded ? group.entries.slice(0, 2) : group.entries;
+
+                        return (
+                            <div key={`group-${groupIndex}`}>
+                                {visibleEntries.map(({ entry }) => (
+                                    <div key={entry.id}>{renderEntry(entry)}</div>
+                                ))}
+                                {shouldCollapse && (
+                                    <div className="flex justify-center py-2">
+                                        <Button
+                                            variant="ghost"
+                                            size="sm"
+                                            onClick={() => toggleGroup(groupIndex)}
+                                            className="text-muted-foreground hover:text-foreground h-6 text-xs"
+                                        >
+                                            {isExpanded ? (
+                                                <>
+                                                    <ChevronUp className="w-3 h-3 mr-1" />
+                                                    Show less
+                                                </>
+                                            ) : (
+                                                <>
+                                                    <ChevronDown className="w-3 h-3 mr-1" />
+                                                    Show all ({group.entries.length - 2})
+                                                </>
+                                            )}
+                                        </Button>
+                                    </div>
+                                )}
+                            </div>
+                        );
+                    }
+                })}
+            </HistoryTimeline>
+        </div>
+    );
+}

package/src/lib/components/shared/history-timeline/use-history-note-editor.ts

@@ -0,0 +1,26 @@
+import { useState } from 'react';
+
+export function useHistoryNoteEditor() {
+    const [noteEditorOpen, setNoteEditorOpen] = useState(false);
+    const [noteState, setNoteState] = useState<{
+        noteId: string;
+        note: string;
+        isPrivate: boolean;
+    }>({
+        noteId: '',
+        note: '',
+        isPrivate: true,
+    });
+
+    const handleEditNote = (noteId: string, note: string, isPrivate: boolean) => {
+        setNoteState({ noteId, note, isPrivate });
+        setNoteEditorOpen(true);
+    };
+
+    return {
+        noteEditorOpen,
+        setNoteEditorOpen,
+        noteState,
+        handleEditNote,
+    };
+}

package/src/lib/framework/extension-api/define-dashboard-extension.ts

@@ -6,6 +6,7 @@ import {
     registerDataTableExtensions,
     registerDetailFormExtensions,
     registerFormComponentExtensions,
+    registerHistoryEntryComponents,
     registerLayoutExtensions,
     registerLoginExtensions,
     registerNavigationExtensions,
@@ -40,6 +41,7 @@ export function executeDashboardExtensionCallbacks() {
  * - Data tables
  * - Detail forms
  * - Login
+ * - Custom history entries
  *
  * @example
  * ```tsx
@@ -83,6 +85,9 @@ export function defineDashboardExtension(extension: DashboardExtension) {
         // Register login extensions
         registerLoginExtensions(extension.login);
 
+        // Register custom history entry components
+        registerHistoryEntryComponents(extension.historyEntries);
+
         // Execute extension source change callbacks
         const callbacks = globalRegistry.get('extensionSourceChangeCallbacks');
         if (callbacks.size) {

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

@@ -5,6 +5,7 @@ import {
     DashboardCustomFormComponents,
     DashboardDataTableExtensionDefinition,
     DashboardDetailFormExtensionDefinition,
+    DashboardHistoryEntryComponent,
     DashboardLoginExtensions,
     DashboardNavSectionDefinition,
     DashboardPageBlockDefinition,
@@ -82,4 +83,10 @@ export interface DashboardExtension {
      * Allows you to customize the login page with custom components.
      */
     login?: DashboardLoginExtensions;
+    /**
+     * @description
+     * Allows a custom component to be used to render a history entry item
+     * in the Order or Customer history lists.
+     */
+    historyEntries?: DashboardHistoryEntryComponent[];
 }

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

@@ -0,0 +1,24 @@
+import { DashboardHistoryEntryComponent } from '@/vdb/framework/extension-api/types/index.js';
+
+import { globalRegistry } from '../../registry/global-registry.js';
+
+export function registerHistoryEntryComponents(
+    historyEntryComponents: DashboardHistoryEntryComponent[] = [],
+) {
+    if (historyEntryComponents.length === 0) {
+        return;
+    }
+    globalRegistry.set('historyEntries', entryMap => {
+        for (const entry of historyEntryComponents) {
+            const existingEntry = entryMap.get(entry.type);
+            if (existingEntry) {
+                // eslint-disable-next-line no-console
+                console.warn(
+                    `The history entry type ${entry.type} already has a custom component registered (${String(existingEntry)}`,
+                );
+            }
+            entryMap.set(entry.type, entry.component);
+        }
+        return entryMap;
+    });
+}

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

@@ -3,6 +3,7 @@ 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';

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

@@ -3,6 +3,7 @@ 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';

package/src/lib/framework/history-entry/history-entry-extensions.ts

@@ -0,0 +1,11 @@
+import { DashboardHistoryEntryComponent } from '@/vdb/framework/extension-api/types/index.js';
+
+import { globalRegistry } from '../registry/global-registry.js';
+
+globalRegistry.register('historyEntries', new Map<string, DashboardHistoryEntryComponent['component']>());
+
+export function getCustomHistoryEntryForType(
+    type: string,
+): DashboardHistoryEntryComponent['component'] | undefined {
+    return globalRegistry.get('historyEntries').get(type);
+}

package/src/lib/framework/history-entry/history-entry.tsx

@@ -0,0 +1,129 @@
+import { HistoryEntryItem } from '@/vdb/framework/extension-api/types/index.js';
+import { cn } from '@/vdb/lib/utils.js';
+import React from 'react';
+import { HistoryEntryDate } from '../../components/shared/history-timeline/history-entry-date.js';
+
+/**
+ * @description
+ * The props for the {@link HistoryEntry} component.
+ *
+ * @docsCategory extensions-api
+ * @docsPage HistoryEntries
+ * @since 3.4.3
+ */
+export interface HistoryEntryProps {
+    /**
+     * @description
+     * The entry itself, which will get passed down to your custom component
+     */
+    entry: HistoryEntryItem;
+    /**
+     * @description
+     * The title of the entry
+     */
+    title: string | React.ReactNode;
+    /**
+     * @description
+     * An icon which is used to represent the entry. Note that this will only
+     * display if `isPrimary` is `true`.
+     */
+    timelineIcon?: React.ReactNode;
+    /**
+     * @description
+     * Optional tailwind classes to apply to the icon. For instance
+     *
+     * ```ts
+     * const success = 'bg-success text-success-foreground';
+     * const destructive = 'bg-danger text-danger-foreground';
+     * ```
+     */
+    timelineIconClassName?: string;
+    /**
+     * @description
+     * The name to display of "who did the action". For instance:
+     *
+     * ```ts
+     * const getActorName = (entry: HistoryEntryItem) => {
+     *     if (entry.administrator) {
+     *         return `${entry.administrator.firstName} ${entry.administrator.lastName}`;
+     *     } else if (entity?.customer) {
+     *         return `${entity.customer.firstName} ${entity.customer.lastName}`;
+     *     }
+     *     return '';
+     * };
+     * ```
+     */
+    actorName?: string;
+    children: React.ReactNode;
+    /**
+     * @description
+     * When set to `true`, the timeline entry will feature the specified icon and will not
+     * be collapsible.
+     */
+    isPrimary?: boolean;
+}
+
+/**
+ * @description
+ * A component which is used to display a history entry in the order/customer history timeline.
+ *
+ * @docsCategory extensions-api
+ * @docsPage HistoryEntries
+ * @since 3.4.3
+ */
+export function HistoryEntry({
+    entry,
+    timelineIcon,
+    timelineIconClassName,
+    actorName,
+    title,
+    children,
+    isPrimary = true,
+}: Readonly<HistoryEntryProps>) {
+    return (
+        <div key={entry.id} className="relative group">
+            <div
+                className={`flex gap-3 p-3 rounded-lg hover:bg-muted/30 transition-colors ${!isPrimary ? 'opacity-90' : ''}`}
+            >
+                <div className={cn(`relative z-10 flex-shrink-0`, isPrimary ? 'ml-0' : 'ml-2 mt-1')}>
+                    <div
+                        className={`rounded-full flex items-center justify-center ${isPrimary ? 'h-6 w-6' : 'h-2 w-2 border'} ${timelineIconClassName ?? ''}  ${isPrimary ? 'shadow-sm' : 'shadow-none'}`}
+                    >
+                        <div className={isPrimary ? 'text-current scale-80' : 'text-current scale-0'}>
+                            {timelineIcon ?? ''}
+                        </div>
+                    </div>
+                </div>
+
+                <div className="flex-1 min-w-0">
+                    <div className="flex items-start justify-between">
+                        <div className="flex-1 min-w-0">
+                            <h4
+                                className={`text-sm ${isPrimary ? 'font-medium text-foreground' : 'font-normal text-muted-foreground'}`}
+                            >
+                                {title}
+                            </h4>
+                            <div className="mt-1">{children}</div>
+                        </div>
+
+                        <div className="flex items-center gap-2 ml-4 flex-shrink-0">
+                            <div className="text-right">
+                                <HistoryEntryDate
+                                    date={entry.createdAt}
+                                    className={`text-xs cursor-help ${isPrimary ? 'text-muted-foreground' : 'text-muted-foreground/70'}`}
+                                />
+                                {actorName && (
+                                    <div
+                                        className={`text-xs ${isPrimary ? 'text-muted-foreground' : 'text-muted-foreground/70'}`}
+                                    >
+                                        {actorName}
+                                    </div>
+                                )}
+                            </div>
+                        </div>
+                    </div>
+                </div>
+            </div>
+        </div>
+    );
+}

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

@@ -1,6 +1,7 @@
 import {
     BulkAction,
     DashboardActionBarItem,
+    DashboardHistoryEntryComponent,
     DashboardLoginExtensions,
     DashboardPageBlockDefinition,
     DashboardWidgetDefinition,
@@ -26,4 +27,5 @@ export interface GlobalRegistryContents {
     listQueryDocumentRegistry: Map<string, DocumentNode[]>;
     detailQueryDocumentRegistry: Map<string, DocumentNode[]>;
     loginExtensions: DashboardLoginExtensions;
+    historyEntries: Map<string, DashboardHistoryEntryComponent['component']>;
 }

package/src/lib/index.ts

@@ -96,10 +96,10 @@ export * from './components/shared/facet-value-chip.js';
 export * from './components/shared/facet-value-selector.js';
 export * from './components/shared/form-field-wrapper.js';
 export * from './components/shared/history-timeline/history-entry-date.js';
-export * from './components/shared/history-timeline/history-entry.js';
 export * from './components/shared/history-timeline/history-note-checkbox.js';
 export * from './components/shared/history-timeline/history-note-editor.js';
 export * from './components/shared/history-timeline/history-note-input.js';
+export * from './components/shared/history-timeline/history-timeline-with-grouping.js';
 export * from './components/shared/history-timeline/history-timeline.js';
 export * from './components/shared/icon-mark.js';
 export * from './components/shared/language-selector.js';
@@ -198,6 +198,7 @@ export * from './framework/extension-api/logic/alerts.js';
 export * from './framework/extension-api/logic/data-table.js';
 export * from './framework/extension-api/logic/detail-forms.js';
 export * from './framework/extension-api/logic/form-components.js';
+export * from './framework/extension-api/logic/history-entries.js';
 export * from './framework/extension-api/logic/layout.js';
 export * from './framework/extension-api/logic/login.js';
 export * from './framework/extension-api/logic/navigation.js';
@@ -206,6 +207,7 @@ export * from './framework/extension-api/types/alerts.js';
 export * from './framework/extension-api/types/data-table.js';
 export * from './framework/extension-api/types/detail-forms.js';
 export * from './framework/extension-api/types/form-components.js';
+export * from './framework/extension-api/types/history-entries.js';
 export * from './framework/extension-api/types/layout.js';
 export * from './framework/extension-api/types/login.js';
 export * from './framework/extension-api/types/navigation.js';
@@ -222,6 +224,8 @@ export * from './framework/form-engine/overridden-form-component.js';
 export * from './framework/form-engine/use-generated-form.js';
 export * from './framework/form-engine/utils.js';
 export * from './framework/form-engine/value-transformers.js';
+export * from './framework/history-entry/history-entry-extensions.js';
+export * from './framework/history-entry/history-entry.js';
 export * from './framework/layout-engine/dev-mode-button.js';
 export * from './framework/layout-engine/layout-extensions.js';
 export * from './framework/layout-engine/location-wrapper.js';