@leandrosk/dashboard 3.5.5

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

@@ -0,0 +1,108 @@
+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 '@/vdb/hooks/use-widget-filters.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 dataTypeLabel = useMemo(() => {
+        switch (dataType) {
+            case DATA_TYPES.OrderCount:
+                return t`Order Count`;
+            case DATA_TYPES.OrderTotal:
+                return t`Order Total`;
+            case DATA_TYPES.AverageOrderValue:
+                return t`Average Order Value`;
+        }
+    }, [dataType, t]);
+
+    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}
+                    dataLabel={dataTypeLabel}
+                />
+            )}
+        </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 '@/vdb/hooks/use-widget-filters.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,18 @@
+'use client';
+
+import { createContext, PropsWithChildren } from 'react';
+
+export interface DefinedDateRange {
+    from: Date;
+    to: Date;
+}
+
+export interface WidgetFilters {
+    dateRange: DefinedDateRange;
+}
+
+export const WidgetFiltersContext = createContext<WidgetFilters | undefined>(undefined);
+
+export function WidgetFiltersProvider({ children, filters }: PropsWithChildren<{ filters: WidgetFilters }>) {
+    return <WidgetFiltersContext.Provider value={filters}>{children}</WidgetFiltersContext.Provider>;
+}

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'}`;
+}

package/src/lib/framework/defaults.ts

@@ -0,0 +1,270 @@
+import { registerAlert } from '@/vdb/framework/alert/alert-extensions.js';
+import { searchIndexBufferAlert } from '@/vdb/framework/alert/search-index-buffer-alert/search-index-buffer-alert.js';
+import { setNavMenuConfig } from '@/vdb/framework/nav-menu/nav-menu-extensions.js';
+import { ChartLine, Percent, Settings2, ShoppingBag, Tags, Terminal, Users } from 'lucide-react';
+
+import { LatestOrdersWidget } from './dashboard-widget/latest-orders-widget/index.js';
+import { MetricsWidget } from './dashboard-widget/metrics-widget/index.js';
+import { OrdersSummaryWidget } from './dashboard-widget/orders-summary/index.js';
+import { registerDashboardWidget } from './dashboard-widget/widget-extensions.js';
+
+export function registerDefaults() {
+    setNavMenuConfig({
+        sections: [
+            {
+                id: 'insights',
+                title: /* i18n*/ 'Insights',
+                placement: 'top',
+                icon: ChartLine,
+                url: '/',
+                order: 100,
+            },
+            {
+                id: 'catalog',
+                title: /* i18n*/ 'Catalog',
+                icon: Tags,
+                placement: 'top',
+                order: 200,
+                items: [
+                    {
+                        id: 'products',
+                        title: /* i18n*/ 'Products',
+                        url: '/products',
+                        order: 100,
+                        requiresPermission: ['ReadProduct', 'ReadCatalog'],
+                    },
+                    {
+                        id: 'product-variants',
+                        title: /* i18n*/ 'Product Variants',
+                        url: '/product-variants',
+                        order: 200,
+                        requiresPermission: ['ReadProduct', 'ReadCatalog'],
+                    },
+                    {
+                        id: 'facets',
+                        title: /* i18n*/ 'Facets',
+                        url: '/facets',
+                        order: 300,
+                        requiresPermission: ['ReadProduct', 'ReadCatalog'],
+                    },
+                    {
+                        id: 'collections',
+                        title: /* i18n*/ 'Collections',
+                        url: '/collections',
+                        order: 400,
+                        requiresPermission: ['ReadCollection', 'ReadCatalog'],
+                    },
+                    {
+                        id: 'assets',
+                        title: /* i18n*/ 'Assets',
+                        url: '/assets',
+                        order: 500,
+                        requiresPermission: ['ReadAsset', 'ReadCatalog'],
+                    },
+                ],
+            },
+            {
+                id: 'sales',
+                title: /* i18n*/ 'Sales',
+                icon: ShoppingBag,
+                placement: 'top',
+                order: 300,
+                items: [
+                    {
+                        id: 'orders',
+                        title: /* i18n*/ 'Orders',
+                        url: '/orders',
+                        order: 100,
+                        requiresPermission: ['ReadOrder'],
+                    },
+                ],
+            },
+            {
+                id: 'customers',
+                title: /* i18n*/ 'Customers',
+                icon: Users,
+                placement: 'top',
+                order: 400,
+                items: [
+                    {
+                        id: 'customers',
+                        title: /* i18n*/ 'Customers',
+                        url: '/customers',
+                        order: 100,
+                        requiresPermission: ['ReadCustomer'],
+                    },
+                    {
+                        id: 'customer-groups',
+                        title: /* i18n*/ 'Customer Groups',
+                        url: '/customer-groups',
+                        order: 200,
+                        requiresPermission: ['ReadCustomerGroup'],
+                    },
+                ],
+            },
+            {
+                id: 'marketing',
+                title: /* i18n*/ 'Marketing',
+                icon: Percent,
+                placement: 'top',
+                order: 500,
+                items: [
+                    {
+                        id: 'promotions',
+                        title: /* i18n*/ 'Promotions',
+                        url: '/promotions',
+                        order: 100,
+                        requiresPermission: ['ReadPromotion'],
+                    },
+                ],
+            },
+            {
+                id: 'system',
+                title: /* i18n*/ 'System',
+                icon: Terminal,
+                placement: 'bottom',
+                order: 200,
+                items: [
+                    {
+                        id: 'job-queue',
+                        title: /* i18n*/ 'Job Queue',
+                        url: '/job-queue',
+                        order: 100,
+                        requiresPermission: ['ReadSystem'],
+                    },
+                    {
+                        id: 'healthchecks',
+                        title: /* i18n*/ 'Healthchecks',
+                        url: '/healthchecks',
+                        order: 200,
+                        requiresPermission: ['ReadSystem'],
+                    },
+                    {
+                        id: 'scheduled-tasks',
+                        title: /* i18n*/ 'Scheduled Tasks',
+                        url: '/scheduled-tasks',
+                        order: 300,
+                        requiresPermission: ['ReadSystem'],
+                    },
+                ],
+            },
+            {
+                id: 'settings',
+                title: /* i18n*/ 'Settings',
+                icon: Settings2,
+                placement: 'bottom',
+                order: 100,
+                items: [
+                    {
+                        id: 'sellers',
+                        title: /* i18n*/ 'Sellers',
+                        url: '/sellers',
+                        order: 100,
+                        requiresPermission: ['ReadSeller'],
+                    },
+                    {
+                        id: 'channels',
+                        title: /* i18n*/ 'Channels',
+                        url: '/channels',
+                        order: 200,
+                        requiresPermission: ['ReadChannel'],
+                    },
+                    {
+                        id: 'stock-locations',
+                        title: /* i18n*/ 'Stock Locations',
+                        url: '/stock-locations',
+                        order: 300,
+                        requiresPermission: ['ReadStockLocation'],
+                    },
+                    {
+                        id: 'administrators',
+                        title: /* i18n*/ 'Administrators',
+                        url: '/administrators',
+                        order: 400,
+                        requiresPermission: ['ReadAdministrator'],
+                    },
+                    {
+                        id: 'roles',
+                        title: /* i18n*/ 'Roles',
+                        url: '/roles',
+                        order: 500,
+                        requiresPermission: ['ReadAdministrator'],
+                    },
+                    {
+                        id: 'shipping-methods',
+                        title: /* i18n*/ 'Shipping Methods',
+                        url: '/shipping-methods',
+                        order: 600,
+                        requiresPermission: ['ReadShippingMethod'],
+                    },
+                    {
+                        id: 'payment-methods',
+                        title: /* i18n*/ 'Payment Methods',
+                        url: '/payment-methods',
+                        order: 700,
+                        requiresPermission: ['ReadPaymentMethod'],
+                    },
+                    {
+                        id: 'tax-categories',
+                        title: /* i18n*/ 'Tax Categories',
+                        url: '/tax-categories',
+                        order: 800,
+                        requiresPermission: ['ReadTaxCategory'],
+                    },
+                    {
+                        id: 'tax-rates',
+                        title: /* i18n*/ 'Tax Rates',
+                        url: '/tax-rates',
+                        order: 900,
+                        requiresPermission: ['ReadTaxRate'],
+                    },
+                    {
+                        id: 'countries',
+                        title: /* i18n*/ 'Countries',
+                        url: '/countries',
+                        order: 1000,
+                        requiresPermission: ['ReadCountry'],
+                    },
+                    {
+                        id: 'zones',
+                        title: /* i18n*/ 'Zones',
+                        url: '/zones',
+                        order: 1100,
+                        requiresPermission: ['ReadZone'],
+                    },
+                    {
+                        id: 'global-settings',
+                        title: /* i18n*/ 'Global Settings',
+                        url: '/global-settings',
+                        order: 1200,
+                        requiresPermission: ['UpdateGlobalSettings'],
+                    },
+                ],
+            },
+        ],
+    });
+
+    registerDashboardWidget({
+        id: 'metrics-widget',
+        name: /* i18n*/ 'Metrics Widget',
+        component: MetricsWidget,
+        defaultSize: { w: 12, h: 6, x: 0, y: 0 },
+        minSize: { w: 6, h: 4 },
+    });
+
+    registerDashboardWidget({
+        id: 'latest-orders-widget',
+        name: /* i18n*/ 'Latest Orders Widget',
+        component: LatestOrdersWidget,
+        defaultSize: { w: 6, h: 7, x: 0, y: 0 },
+    });
+
+    registerDashboardWidget({
+        id: 'orders-summary-widget',
+        name: /* i18n*/ 'Orders Summary Widget',
+        component: OrdersSummaryWidget,
+        defaultSize: { w: 6, h: 3, x: 6, y: 0 },
+    });
+
+    registerAlert(searchIndexBufferAlert);
+}

package/src/lib/framework/document-extension/extend-detail-form-query.ts

@@ -0,0 +1,50 @@
+import { extendDocument } from '@/vdb/framework/document-extension/extend-document.js';
+import { getDetailQueryDocuments } from '@/vdb/framework/form-engine/custom-form-component-extensions.js';
+import { DocumentNode } from 'graphql';
+
+/**
+ * @description
+ * Extends a detail page query document with any registered extensions provided by
+ * the `extendDetailDocument` function for the given page.
+ */
+export function extendDetailFormQuery<T extends DocumentNode>(
+    detailQuery: T,
+    pageId?: string,
+): {
+    extendedQuery: T;
+    errorMessage?: string | null;
+} {
+    let result: T = detailQuery;
+    let errorMessage: string | null = null;
+
+    if (!pageId) {
+        // If no pageId is provided, return the original query without any extensions
+        return { extendedQuery: detailQuery };
+    }
+
+    const detailQueryExtensions = getDetailQueryDocuments(pageId);
+
+    try {
+        result = detailQueryExtensions.reduce(
+            (acc, extension) => extendDocument(acc, extension),
+            detailQuery,
+        ) as T;
+    } catch (err) {
+        errorMessage = err instanceof Error ? err.message : String(err);
+        // Continue with the original query instead of the extended one
+        result = detailQuery;
+    }
+
+    // Store error for useEffect to handle
+    if (errorMessage) {
+        // Log the error and continue with the original query
+        // eslint-disable-next-line no-console
+        console.warn(`${errorMessage}. Continuing with original query.`, {
+            pageId,
+            extensionsCount: detailQueryExtensions.length,
+            error: errorMessage,
+        });
+    }
+
+    return { extendedQuery: result, errorMessage };
+}