@wilshop/dashboard 3.5.2

package/src/lib/framework/dashboard-widget/base-widget.tsx

@@ -0,0 +1,101 @@
+import { Card, CardContent, CardDescription, CardHeader, CardTitle } from '@/vdb/components/ui/card.js';
+import { DashboardBaseWidgetProps } from '@/vdb/framework/extension-api/types/index.js';
+import { cn } from '@/vdb/lib/utils.js';
+import { Trans, useLingui } from '@lingui/react/macro';
+import { createContext, useContext, useEffect, useRef, useState } from 'react';
+
+type WidgetDimensions = {
+    width: number;
+    height: number;
+};
+
+export const WidgetContentContext = createContext<WidgetDimensions>({ width: 0, height: 0 });
+
+export const useWidgetDimensions = () => {
+    const { t } = useLingui();
+    const context = useContext(WidgetContentContext);
+    if (!context) {
+        throw new Error(t`useWidgetDimensions must be used within a DashboardBaseWidget`);
+    }
+    return context;
+};
+
+/**
+ * @description
+ * A wrapper component that should be used for any custom Insights page widgets.
+ * This ensures that your custom widget has all the basic functionality needed to be
+ * correctly rendered on the Insights page.
+ *
+ * @docsCategory extensions-api
+ * @docsPage widgets
+ * @since 3.3.0
+ */
+export function DashboardBaseWidget({
+    id,
+    config,
+    children,
+    title,
+    description,
+    actions,
+}: DashboardBaseWidgetProps) {
+    const headerRef = useRef<HTMLDivElement>(null);
+    const wrapperRef = useRef<HTMLDivElement>(null);
+    const contentRef = useRef<HTMLDivElement>(null);
+    const [dimensions, setDimensions] = useState<WidgetDimensions>({ width: 0, height: 0 });
+
+    useEffect(() => {
+        const updateDimensions = () => {
+            if (wrapperRef.current && contentRef.current) {
+                const contentStyles = window.getComputedStyle(contentRef.current);
+                const paddingTop = parseFloat(contentStyles.paddingTop);
+                const paddingBottom = parseFloat(contentStyles.paddingBottom);
+                const paddingLeft = parseFloat(contentStyles.paddingLeft);
+                const paddingRight = parseFloat(contentStyles.paddingRight);
+
+                const headerHeight = headerRef.current?.offsetHeight ?? 0;
+
+                setDimensions({
+                    width: wrapperRef.current.offsetWidth - paddingLeft - paddingRight,
+                    height: wrapperRef.current.offsetHeight - paddingTop - paddingBottom - headerHeight,
+                });
+            }
+        };
+
+        updateDimensions();
+        const observer = new ResizeObserver(updateDimensions);
+        if (wrapperRef.current) {
+            observer.observe(wrapperRef.current);
+        }
+
+        return () => observer.disconnect();
+    }, []);
+
+    return (
+        <Card
+            ref={wrapperRef}
+            key={`dashboard-widget-${id}`}
+            className={cn('h-full w-full flex flex-col rounded-md', !title && 'pt-6')}
+        >
+            {title && (
+                <CardHeader
+                    ref={headerRef}
+                    className={cn(
+                        'flex flex-col lg:flex-row  items-start lg:items-center',
+                        actions ? 'justify-between' : 'justify-start',
+                    )}
+                >
+                    <div>
+                        <CardTitle>
+                            <Trans>{title}</Trans>
+                        </CardTitle>
+                        {description && <CardDescription>{description}</CardDescription>}
+                    </div>
+                    {actions && <div className="flex items-center gap-2">{actions}</div>}
+                </CardHeader>
+            )}
+            <CardContent ref={contentRef} className="grow">
+                <WidgetContentContext.Provider value={dimensions}>{children}</WidgetContentContext.Provider>
+            </CardContent>
+        </Card>
+    );
+}

package/src/lib/framework/dashboard-widget/latest-orders-widget/index.tsx

@@ -0,0 +1,152 @@
+import { PaginatedListDataTable } from '@/vdb/components/shared/paginated-list-data-table.js';
+import {
+    CustomerCell,
+    OrderMoneyCell,
+    OrderStateCell,
+} from '@/vdb/components/shared/table-cell/order-table-cell-components.js';
+import { Button } from '@/vdb/components/ui/button.js';
+import { useUserSettings } from '@/vdb/hooks/use-user-settings.js';
+import { useLingui } from '@lingui/react/macro';
+import { Link } from '@tanstack/react-router';
+import { ColumnFiltersState, SortingState } from '@tanstack/react-table';
+import { formatRelative } from 'date-fns';
+import { useEffect, useState } from 'react';
+import { DashboardBaseWidget } from '../base-widget.js';
+import { useWidgetFilters } from '../widget-filters-context.js';
+import { latestOrdersQuery } from './latest-orders-widget.graphql.js';
+
+export const WIDGET_ID = 'latest-orders-widget';
+
+export function LatestOrdersWidget() {
+    const { t } = useLingui();
+    const { dateRange } = useWidgetFilters();
+    const { setTableSettings, settings } = useUserSettings();
+    const tableSettings = settings.tableSettings?.[WIDGET_ID];
+
+    const [sorting, setSorting] = useState<SortingState>([
+        {
+            id: 'orderPlacedAt',
+            desc: true,
+        },
+    ]);
+    const [page, setPage] = useState(1);
+    const [pageSize, setPageSize] = useState(tableSettings?.pageSize ?? 10);
+    const [filters, setFilters] = useState<ColumnFiltersState>([
+        {
+            id: 'orderPlacedAt',
+            value: {
+                between: {
+                    start: dateRange.from.toISOString(),
+                    end: dateRange.to.toISOString(),
+                },
+            },
+        },
+    ]);
+
+    // Update page size if user settings change
+    useEffect(() => {
+        if (tableSettings?.pageSize !== undefined) {
+            setPageSize(tableSettings.pageSize);
+        }
+    }, [tableSettings?.pageSize]);
+
+    // Update filters when date range changes
+    useEffect(() => {
+        setFilters([
+            {
+                id: 'orderPlacedAt',
+                value: {
+                    between: {
+                        start: dateRange.from.toISOString(),
+                        end: dateRange.to.toISOString(),
+                    },
+                },
+            },
+        ]);
+    }, [dateRange]);
+
+    const defaultVisibility = {
+        code: true,
+        total: true,
+        orderPlacedAt: true,
+    };
+
+    const columnVisibility = tableSettings?.columnVisibility ?? defaultVisibility;
+
+    return (
+        <DashboardBaseWidget id={WIDGET_ID} title={t`Latest Orders`} description={t`Your latest orders`}>
+            <PaginatedListDataTable
+                page={page}
+                transformVariables={variables => ({
+                    ...variables,
+                    options: {
+                        ...variables.options,
+                        filter: {
+                            active: {
+                                eq: false,
+                            },
+                            state: {
+                                notIn: ['Cancelled', 'Draft'],
+                            },
+                            ...(variables.options?.filter ?? {}),
+                        },
+                    },
+                })}
+                customizeColumns={{
+                    code: {
+                        header: t`Code`,
+                        cell: ({ row }) => {
+                            return (
+                                <Button variant="ghost" asChild>
+                                    <Link to={`/orders/${row.original.id}`}>{row.original.code}</Link>
+                                </Button>
+                            );
+                        },
+                    },
+                    orderPlacedAt: {
+                        header: t`Placed At`,
+                        cell: ({ row }) => {
+                            return (
+                                <span className="capitalize">
+                                    {formatRelative(row.original.orderPlacedAt ?? new Date(), new Date())}
+                                </span>
+                            );
+                        },
+                    },
+                    total: {
+                        meta: {
+                            dependencies: ['currencyCode'],
+                        },
+                        header: t`Total`,
+                        cell: OrderMoneyCell,
+                    },
+                    totalWithTax: {
+                        meta: { dependencies: ['currencyCode'] },
+                        cell: OrderMoneyCell,
+                    },
+                    state: { cell: OrderStateCell },
+                    customer: { cell: CustomerCell },
+                }}
+                itemsPerPage={pageSize}
+                sorting={sorting}
+                columnFilters={filters}
+                listQuery={latestOrdersQuery}
+                defaultVisibility={columnVisibility}
+                onPageChange={(_, page, newPageSize) => {
+                    setPage(page);
+                    setPageSize(newPageSize);
+                    setTableSettings(WIDGET_ID, 'pageSize', newPageSize);
+                }}
+                onSortChange={(_, sorting) => {
+                    setSorting(sorting);
+                }}
+                onFilterChange={(_, filters) => {
+                    setFilters(filters);
+                }}
+                onColumnVisibilityChange={(_, columnVisibility) => {
+                    setTableSettings(WIDGET_ID, 'columnVisibility', columnVisibility);
+                }}
+            />
+        </DashboardBaseWidget>
+    );
+}

package/src/lib/framework/dashboard-widget/latest-orders-widget/latest-orders-widget.graphql.ts

@@ -0,0 +1,35 @@
+import { graphql } from '@/vdb/graphql/graphql.js';
+
+export const latestOrderItemFragment = graphql(`
+    fragment LatestOrderItem on Order {
+        id
+        createdAt
+        updatedAt
+        type
+        orderPlacedAt
+        code
+        state
+        total
+        totalWithTax
+        currencyCode
+        customer {
+            id
+            firstName
+            lastName
+        }
+    }
+`);
+
+export const latestOrdersQuery = graphql(
+    `
+        query GetLatestOrders($options: OrderListOptions) {
+            orders(options: $options) {
+                items {
+                    ...LatestOrderItem
+                }
+                totalItems
+            }
+        }
+    `,
+    [latestOrderItemFragment],
+);

package/src/lib/framework/dashboard-widget/metrics-widget/chart.tsx

@@ -0,0 +1,40 @@
+import { Area, AreaChart, CartesianGrid, Tooltip, XAxis, YAxis } from 'recharts';
+import { useWidgetDimensions } from '../base-widget.js';
+
+export function MetricsChart({
+    chartData,
+    formatValue,
+}: {
+    chartData: any[];
+    formatValue: (value: any) => string;
+}) {
+    const { width, height } = useWidgetDimensions();
+
+    return (
+        <AreaChart width={width} height={height} data={chartData}>
+            <defs>
+                <linearGradient id="gradientFill" x1="0" y1="0" x2="0" y2="1">
+                    <stop offset="5%" stopColor="var(--color-brand)" stopOpacity={0.9} />
+                    <stop offset="100%" stopColor="var(--color-brand)" stopOpacity={0.05} />
+                </linearGradient>
+            </defs>
+            <CartesianGrid strokeDasharray="4 4" stroke="var(--color-border)" />
+            <XAxis className="text-xs" color="var(--color-foreground)" dataKey="name" interval={2} />
+            <YAxis className="text-xs" color="var(--color-foreground)" tickFormatter={formatValue} />
+            <Tooltip
+                formatter={formatValue}
+                contentStyle={{ borderRadius: 4, padding: 4, paddingLeft: 8, paddingRight: 8 }}
+                labelStyle={{ fontSize: 12 }}
+                itemStyle={{ fontSize: 14 }}
+            />
+            <Area
+                type="monotone"
+                dataKey="sales"
+                stroke="var(--color-brand)"
+                strokeWidth={2}
+                strokeOpacity={0.8}
+                fill={'url(#gradientFill)'}
+            />
+        </AreaChart>
+    );
+}

package/src/lib/framework/dashboard-widget/metrics-widget/index.tsx

@@ -0,0 +1,96 @@
+import { Button } from '@/vdb/components/ui/button.js';
+import { Tabs, TabsList, TabsTrigger } from '@/vdb/components/ui/tabs.js';
+import { api } from '@/vdb/graphql/api.js';
+import { useChannel } from '@/vdb/hooks/use-channel.js';
+import { useLocalFormat } from '@/vdb/hooks/use-local-format.js';
+import { Trans } from '@lingui/react/macro';
+import { useLingui } from '@lingui/react/macro';
+import { useQuery } from '@tanstack/react-query';
+import { RefreshCw } from 'lucide-react';
+import { useMemo, useState } from 'react';
+import { DashboardBaseWidget } from '../base-widget.js';
+import { useWidgetFilters } from '../widget-filters-context.js';
+import { MetricsChart } from './chart.js';
+import { orderChartDataQuery } from './metrics-widget.graphql.js';
+
+enum DATA_TYPES {
+    OrderCount = 'OrderCount',
+    OrderTotal = 'OrderTotal',
+    AverageOrderValue = 'AverageOrderValue',
+}
+
+export function MetricsWidget() {
+    const { t } = useLingui();
+    const { formatDate, formatCurrency } = useLocalFormat();
+    const { activeChannel } = useChannel();
+    const { dateRange } = useWidgetFilters();
+    const [dataType, setDataType] = useState<DATA_TYPES>(DATA_TYPES.OrderTotal);
+
+    const { data, refetch, isRefetching } = useQuery({
+        queryKey: ['dashboard-order-metrics', dataType, dateRange],
+        queryFn: () => {
+            return api.query(orderChartDataQuery, {
+                types: [dataType],
+                refresh: true,
+                startDate: dateRange.from.toISOString(),
+                endDate: dateRange.to.toISOString(),
+            });
+        },
+    });
+
+    const chartData = useMemo(() => {
+        const entry = data?.dashboardMetricSummary.at(0);
+        if (!entry) {
+            return undefined;
+        }
+
+        const { type, entries } = entry;
+
+        const values = entries.map(({ label, value }: { label: string; value: number }) => ({
+            name: formatDate(label, { month: 'short', day: 'numeric' }),
+            sales: value,
+        }));
+
+        return {
+            values,
+            type,
+        };
+    }, [data, formatDate]);
+
+    return (
+        <DashboardBaseWidget
+            id="metrics-widget"
+            title={t`Metrics`}
+            description={t`Order metrics`}
+            actions={
+                <div className="flex gap-1">
+                    <Tabs defaultValue={dataType} onValueChange={value => setDataType(value as DATA_TYPES)}>
+                        <TabsList>
+                            <TabsTrigger value={DATA_TYPES.OrderCount}><Trans>Order Count</Trans></TabsTrigger>
+                            <TabsTrigger value={DATA_TYPES.OrderTotal}><Trans>Order Total</Trans></TabsTrigger>
+                            <TabsTrigger value={DATA_TYPES.AverageOrderValue}>
+                                <Trans>Average Order Value</Trans>
+                            </TabsTrigger>
+                        </TabsList>
+                    </Tabs>
+                    <Button variant={'ghost'} onClick={() => refetch()}>
+                        <RefreshCw className={isRefetching ? 'animate-rotate' : ''} />
+                    </Button>
+                </div>
+            }
+        >
+            {chartData && (
+                <MetricsChart
+                    formatValue={value => {
+                        if (dataType === DATA_TYPES.OrderCount) {
+                            return value;
+                        }
+
+                        return formatCurrency(value, activeChannel?.defaultCurrencyCode ?? 'USD', 0);
+                    }}
+                    chartData={chartData.values}
+                />
+            )}
+        </DashboardBaseWidget>
+    );
+}

package/src/lib/framework/dashboard-widget/metrics-widget/metrics-widget.graphql.ts

@@ -0,0 +1,20 @@
+import { graphql } from '@/vdb/graphql/graphql.js';
+
+export const orderChartDataQuery = graphql(`
+    query GetOrderChartData(
+        $refresh: Boolean
+        $types: [DashboardMetricType!]!
+        $startDate: DateTime!
+        $endDate: DateTime!
+    ) {
+        dashboardMetricSummary(
+            input: { types: $types, refresh: $refresh, startDate: $startDate, endDate: $endDate }
+        ) {
+            type
+            entries {
+                label
+                value
+            }
+        }
+    }
+`);

package/src/lib/framework/dashboard-widget/orders-summary/index.tsx

@@ -0,0 +1,113 @@
+import { AnimatedCurrency, AnimatedNumber } from '@/vdb/components/shared/animated-number.js';
+import { api } from '@/vdb/graphql/api.js';
+import { Trans } from '@lingui/react/macro';
+import { useLingui } from '@lingui/react/macro';
+import { useQuery } from '@tanstack/react-query';
+import { differenceInDays, subDays } from 'date-fns';
+import { useMemo } from 'react';
+import { DashboardBaseWidget } from '../base-widget.js';
+import { useWidgetFilters } from '../widget-filters-context.js';
+import { orderSummaryQuery } from './order-summary-widget.graphql.js';
+
+const WIDGET_ID = 'orders-summary-widget';
+
+interface PercentageChangeProps {
+    value: number;
+}
+
+function PercentageChange({ value }: PercentageChangeProps) {
+    const isZero = value === 0;
+    const isPositive = value > 0;
+    const colorClass = isZero ? 'text-muted-foreground' : isPositive ? 'text-success' : 'text-destructive';
+    const arrow = isZero ? null : isPositive ? '↑' : '↓';
+
+    return (
+        <p className={`text-sm ${colorClass}`}>
+            {arrow} <AnimatedNumber value={Math.abs(value)} />%
+        </p>
+    );
+}
+
+export function OrdersSummaryWidget() {
+    const { t } = useLingui();
+    const { dateRange } = useWidgetFilters();
+
+    const variables = useMemo(() => {
+        const rangeLength = differenceInDays(dateRange.to, dateRange.from) + 1;
+        // For the previous period, we go back by the same range length
+        const previousStart = subDays(dateRange.from, rangeLength);
+        const previousEnd = subDays(dateRange.to, rangeLength);
+
+        return {
+            start: dateRange.from.toISOString(),
+            end: dateRange.to.toISOString(),
+            previousStart: previousStart.toISOString(),
+            previousEnd: previousEnd.toISOString(),
+        };
+    }, [dateRange]);
+
+    const { data } = useQuery({
+        queryKey: ['orders-summary', dateRange],
+        queryFn: () =>
+            api.query(orderSummaryQuery, {
+                start: variables.start,
+                end: variables.end,
+            }),
+    });
+
+    const { data: previousData } = useQuery({
+        queryKey: ['orders-summary', 'previous', dateRange],
+        queryFn: () =>
+            api.query(orderSummaryQuery, {
+                start: variables.previousStart,
+                end: variables.previousEnd,
+            }),
+    });
+
+    const calculatePercentChange = (current: number, previous: number) => {
+        if (previous === 0) return 0;
+        return ((current - previous) / previous) * 100;
+    };
+
+    const currentTotalOrders = data?.orders.totalItems ?? 0;
+    const previousTotalOrders = previousData?.orders.totalItems ?? 0;
+    const currentRevenue = data?.orders.items.reduce((acc, order) => acc + order.totalWithTax, 0) ?? 0;
+    const previousRevenue =
+        previousData?.orders.items.reduce((acc, order) => acc + order.totalWithTax, 0) ?? 0;
+
+    const orderChange = calculatePercentChange(currentTotalOrders, previousTotalOrders);
+    const revenueChange = calculatePercentChange(currentRevenue, previousRevenue);
+
+    return (
+        <DashboardBaseWidget
+            id={WIDGET_ID}
+            title={t`Orders Summary`}
+            description={t`Your orders summary`}
+        >
+            <div className="@container h-full">
+                <div className="flex flex-col h-full @md:flex-row gap-8 items-center justify-center @md:justify-evenly text-center tabular-nums">
+                    <div className="flex flex-col lg:gap-2">
+                        <p className="lg:text-lg text-muted-foreground"><Trans>Total Orders</Trans></p>
+                        <p className="text-xl @md:text-3xl font-semibold">
+                            <AnimatedNumber
+                                animationConfig={{ mass: 0.01, stiffness: 90, damping: 3 }}
+                                value={currentTotalOrders}
+                            />
+                        </p>
+                        <PercentageChange value={orderChange} />
+                    </div>
+                    <div className="flex flex-col lg:gap-2">
+                        <p className="lg:text-lg text-muted-foreground"><Trans>Total Revenue</Trans></p>
+                        <p className="text-xl @md:text-3xl font-semibold">
+                            <AnimatedCurrency
+                                animationConfig={{ mass: 0.01, stiffness: 90, damping: 3 }}
+                                value={currentRevenue}
+                            />
+                        </p>
+                        <PercentageChange value={revenueChange} />
+                    </div>
+                </div>
+            </div>
+        </DashboardBaseWidget>
+    );
+}

package/src/lib/framework/dashboard-widget/orders-summary/order-summary-widget.graphql.ts

@@ -0,0 +1,14 @@
+import { graphql } from '@/vdb/graphql/graphql.js';
+
+export const orderSummaryQuery = graphql(`
+    query GetOrderSummary($start: DateTime!, $end: DateTime!) {
+        orders(options: { filter: { orderPlacedAt: { between: { start: $start, end: $end } } } }) {
+            totalItems
+            items {
+                id
+                totalWithTax
+                currencyCode
+            }
+        }
+    }
+`);

package/src/lib/framework/dashboard-widget/widget-extensions.tsx

@@ -0,0 +1,19 @@
+import { DashboardWidgetDefinition } from '@/vdb/framework/extension-api/types/index.js';
+import { globalRegistry } from '../registry/global-registry.js';
+
+globalRegistry.register('dashboardWidgetRegistry', new Map<string, DashboardWidgetDefinition>());
+
+export function registerDashboardWidget(widget: DashboardWidgetDefinition) {
+    globalRegistry.set('dashboardWidgetRegistry', map => {
+        map.set(widget.id, widget);
+        return map;
+    });
+}
+
+export function getDashboardWidgetRegistry() {
+    return globalRegistry.get('dashboardWidgetRegistry');
+}
+
+export function getDashboardWidget(id: string) {
+    return globalRegistry.get('dashboardWidgetRegistry').get(id);
+}

package/src/lib/framework/dashboard-widget/widget-filters-context.tsx

@@ -0,0 +1,36 @@
+'use client';
+
+import { useLingui } from '@lingui/react/macro';
+import { createContext, PropsWithChildren, useContext } from 'react';
+
+export interface DefinedDateRange {
+    from: Date;
+    to: Date;
+}
+
+export interface WidgetFilters {
+    dateRange: DefinedDateRange;
+}
+
+const WidgetFiltersContext = createContext<WidgetFilters | undefined>(undefined);
+
+export function WidgetFiltersProvider({ children, filters }: PropsWithChildren<{ filters: WidgetFilters }>) {
+    return <WidgetFiltersContext.Provider value={filters}>{children}</WidgetFiltersContext.Provider>;
+}
+
+/**
+ * @description
+ * Exposes a context object for use in building Insights page widgets.
+ *
+ * @docsCategory hooks
+ * @docsPage useWidgetFilters
+ * @since 3.5.0
+ */
+export function useWidgetFilters() {
+    const { t } = useLingui();
+    const context = useContext(WidgetFiltersContext);
+    if (context === undefined) {
+        throw new Error(t`useWidgetFilters must be used within a WidgetFiltersProvider`);
+    }
+    return context;
+}

package/src/lib/framework/data-table/data-table-extensions.ts

@@ -0,0 +1,35 @@
+import { BulkAction } from '@/vdb/framework/extension-api/types/index.js';
+import { DocumentNode } from 'graphql';
+
+import { globalRegistry } from '../registry/global-registry.js';
+
+globalRegistry.register('bulkActionsRegistry', new Map<string, BulkAction[]>());
+globalRegistry.register('listQueryDocumentRegistry', new Map<string, DocumentNode[]>());
+
+export function getBulkActions(pageId: string, blockId = 'list-table'): BulkAction[] {
+    const key = createKey(pageId, blockId);
+    return globalRegistry.get('bulkActionsRegistry').get(key) || [];
+}
+
+export function addBulkAction(pageId: string, blockId: string | undefined, action: BulkAction) {
+    const bulkActionsRegistry = globalRegistry.get('bulkActionsRegistry');
+    const key = createKey(pageId, blockId);
+    const existingActions = bulkActionsRegistry.get(key) || [];
+    bulkActionsRegistry.set(key, [...existingActions, action]);
+}
+
+export function getListQueryDocuments(pageId: string, blockId = 'list-table'): DocumentNode[] {
+    const key = createKey(pageId, blockId);
+    return globalRegistry.get('listQueryDocumentRegistry').get(key) || [];
+}
+
+export function addListQueryDocument(pageId: string, blockId: string | undefined, document: DocumentNode) {
+    const listQueryDocumentRegistry = globalRegistry.get('listQueryDocumentRegistry');
+    const key = createKey(pageId, blockId);
+    const existingDocuments = listQueryDocumentRegistry.get(key) || [];
+    listQueryDocumentRegistry.set(key, [...existingDocuments, document]);
+}
+
+function createKey(pageId: string, blockId: string | undefined): string {
+    return `${pageId}__${blockId ?? 'list-table'}`;
+}