@vendure/dashboard 3.2.4 → 3.3.0

package/src/lib/components/layout/prerelease-popup.tsx

@@ -11,17 +11,13 @@ export function PrereleasePopup() {
             description: (
                 <div className="space-y-2">
                     <p>
-                        This is an <span className="font-bold">alpha</span> version of our new Vendure
+                        This is a <span className="font-bold">beta</span> version of our new Vendure
                         Dashboard!
                     </p>
                     <p>
                         This release allows you to explore the new interface and functionality, but it's not
                         yet ready for production use.
                     </p>
-                    <p>
-                        If you find missing or broken functionality, you don't need to report it on GitHub at
-                        this point - we're already working on it!
-                    </p>
                 </div>
             ),
             duration: 1000 * 60,

package/src/lib/components/shared/alerts.tsx

@@ -1,19 +1,37 @@
 import { BellIcon } from 'lucide-react';
 import { Button } from '../ui/button.js';
 import { Dialog, DialogContent, DialogHeader, DialogTitle, DialogTrigger } from '../ui/dialog.js';
+import { useAlerts } from '../../framework/alert/alert-extensions.js';
+import { AlertItem } from '../../framework/alert/alert-item.js';
+import { ScrollArea } from '../ui/scroll-area.js';
+import { AlertsIndicator } from '../../framework/alert/alerts-indicator.js';
 
 export function Alerts() {
+    const { alerts } = useAlerts();
+
+    if (alerts.length === 0) {
+        return null;
+    }
+
     return (
         <Dialog>
             <DialogTrigger asChild>
-                <Button size="icon" variant="ghost">
+                <Button size="icon" variant="ghost" className="relative">
                     <BellIcon />
+                    <AlertsIndicator />
                 </Button>
             </DialogTrigger>
             <DialogContent>
                 <DialogHeader>
                     <DialogTitle>Alerts</DialogTitle>
                 </DialogHeader>
+                <ScrollArea className="max-h-[500px]">
+                    <div className="flex flex-col divide-y divide-border">
+                        {alerts.map(alert => (
+                            <AlertItem className="py-2" key={alert.id} alert={alert} />
+                        ))}
+                    </div>
+                </ScrollArea>
             </DialogContent>
         </Dialog>
     );

package/src/lib/components/shared/error-page.tsx

@@ -13,12 +13,12 @@ export interface ErrorPageProps {
  */
 export function ErrorPage({ message }: ErrorPageProps) {
     return (
-        <Page>
+        <Page pageId='error-page'>
             <PageTitle>
                 <Trans>Error</Trans>
             </PageTitle>
             <PageLayout>
-                <PageBlock column="main">
+                <PageBlock column="main" blockId='error-message'>
                     <Alert variant="destructive">
                         <AlertCircle className="h-4 w-4" />
                         <AlertTitle>Error</AlertTitle>

package/src/lib/components/shared/navigation-confirmation.tsx

@@ -1,9 +1,9 @@
-import { Trans } from "@/lib/trans.js";
-import { useBlocker } from "@tanstack/react-router";
-import { UseFormReturn } from "react-hook-form";
+import { Trans } from '@/lib/trans.js';
+import { useBlocker } from '@tanstack/react-router';
+import { UseFormReturn } from 'react-hook-form';
 
-import { Button } from "../ui/button.js";
-import { Dialog, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogTitle } from "../ui/dialog.js";
+import { Button } from '../ui/button.js';
+import { Dialog, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogTitle } from '../ui/dialog.js';
 
 export interface NavigationConfirmationProps {
     form: UseFormReturn<any>;
@@ -12,19 +12,29 @@ export interface NavigationConfirmationProps {
 /**
  * Navigation confirmation dialog that blocks navigation when the form is dirty.
  */
-export function NavigationConfirmation(props: NavigationConfirmationProps) {
+export function NavigationConfirmation(props: Readonly<NavigationConfirmationProps>) {
     const { proceed, reset, status } = useBlocker({
-        shouldBlockFn: () => props.form.formState.isDirty,
+        shouldBlockFn: (args) => {
+            // When a new entity is being created, we don't want to block navigation
+            // to the newly-created entity page.
+            const isNavigatingToNewlyCreatedEntity = args.current.fullPath === args.next.fullPath
+                && args.current.params.id === 'new' && args.next.params.id !== 'new'
+            if (isNavigatingToNewlyCreatedEntity) {
+                return false;
+            }
+            return props.form.formState.isDirty;
+        },
         withResolver: true,
         enableBeforeUnload: true,
-    })
+    });
     return (
         <Dialog open={status === 'blocked'} onOpenChange={reset}>
             <DialogContent className="sm:max-w-[425px]">
                 <DialogHeader>
                     <DialogTitle><Trans>Confirm navigation</Trans></DialogTitle>
                     <DialogDescription>
-                        <Trans>Are you sure you want to navigate away from this page? Any unsaved changes will be lost.</Trans>
+                        <Trans>Are you sure you want to navigate away from this page? Any unsaved changes will be
+                            lost.</Trans>
                     </DialogDescription>
                 </DialogHeader>
                 <DialogFooter>
@@ -35,5 +45,5 @@ export function NavigationConfirmation(props: NavigationConfirmationProps) {
                 </DialogFooter>
             </DialogContent>
         </Dialog>
-    )
+    );
 }

package/src/lib/components/shared/paginated-list-data-table.tsx

@@ -428,6 +428,7 @@ export function PaginatedListDataTable<
                 facetedFilters={facetedFilters}
                 disableViewOptions={disableViewOptions}
                 setTableOptions={setTableOptions}
+                onRefresh={refetchPaginatedList}
             />
         </PaginatedListContext.Provider>
     );

package/src/lib/framework/alert/alert-extensions.tsx

@@ -0,0 +1,31 @@
+import { useEffect } from 'react';
+import { useState } from 'react';
+import { globalRegistry } from '../registry/global-registry.js';
+import { DashboardAlertDefinition } from './types.js';
+
+globalRegistry.register('dashboardAlertRegistry', new Map<string, DashboardAlertDefinition>());
+
+export function registerAlert<TResponse>(alert: DashboardAlertDefinition<TResponse>) {
+    globalRegistry.set('dashboardAlertRegistry', map => {
+        map.set(alert.id, alert);
+        return map;
+    });
+}
+
+export function getAlertRegistry() {
+    return globalRegistry.get('dashboardAlertRegistry');
+}
+
+export function getAlert(id: string) {
+    return getAlertRegistry().get(id);
+}
+
+export function useAlerts() {
+    const [alerts, setAlerts] = useState<DashboardAlertDefinition[]>([]);
+
+    useEffect(() => {
+        setAlerts(Array.from(getAlertRegistry().values()));
+    }, []);
+
+    return { alerts };
+}

package/src/lib/framework/alert/alert-item.tsx

@@ -0,0 +1,47 @@
+import { Button } from '@/components/ui/button.js';
+import { useQuery } from '@tanstack/react-query';
+import { ComponentProps } from 'react';
+import { DashboardAlertDefinition } from './types.js';
+import { cn } from '@/lib/utils.js';
+interface AlertItemProps extends ComponentProps<'div'> {
+    alert: DashboardAlertDefinition;
+}
+
+export function AlertItem({ alert, className, ...props }: Readonly<AlertItemProps>) {
+    const { data } = useQuery({
+        queryKey: ['alert', alert.id],
+        queryFn: () => alert.check(),
+        refetchInterval: alert.recheckInterval,
+    });
+
+    const isAlertActive = alert.shouldShow?.(data);
+
+    if (!isAlertActive) {
+        return null;
+    }
+
+    return (
+        <div className={cn('flex items-center justify-between gap-1', className)} {...props}>
+            <div className="flex flex-col">
+                <span className="font-semibold">
+                    {typeof alert.title === 'string' ? alert.title : alert.title(data)}
+                </span>
+                <span className="text-sm text-muted-foreground">
+                    {typeof alert.description === 'string' ? alert.description : alert.description?.(data)}
+                </span>
+            </div>
+            <div className="flex items-center gap-1">
+                {alert.actions?.map(action => (
+                    <Button
+                        key={action.label}
+                        variant="secondary"
+                        size="sm"
+                        onClick={() => action.onClick(data)}
+                    >
+                        {action.label}
+                    </Button>
+                ))}
+            </div>
+        </div>
+    );
+}

package/src/lib/framework/alert/alerts-indicator.tsx

@@ -0,0 +1,23 @@
+import { useQueries } from '@tanstack/react-query';
+import { useAlerts } from './alert-extensions.js';
+
+export function AlertsIndicator() {
+    const { alerts } = useAlerts();
+
+    const alertsCount = useQueries({
+        queries: alerts.map(alert => ({
+            queryKey: ['alert', alert.id],
+            queryFn: () => alert.check(),
+        })),
+        combine: results => {
+            return results.filter((result, idx) => result.data && alerts[idx].shouldShow?.(result.data))
+                .length;
+        },
+    });
+
+    return (
+        <div className="absolute -right-1 -top-1 rounded-full bg-red-500 text-xs w-4 h-4 flex items-center justify-center">
+            {alertsCount}
+        </div>
+    );
+}

package/src/lib/framework/alert/types.ts

@@ -0,0 +1,13 @@
+export interface DashboardAlertDefinition<TResponse = any> {
+    id: string;
+    title: string | ((data: TResponse) => string);
+    description?: string | ((data: TResponse) => string);
+    severity: 'info' | 'warning' | 'error';
+    check: () => Promise<TResponse> | TResponse;
+    recheckInterval?: number;
+    shouldShow?: (data: TResponse) => boolean;
+    actions?: Array<{
+        label: string;
+        onClick: (data: TResponse) => void;
+    }>;
+}

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

@@ -2,6 +2,7 @@ import { Card, CardContent, CardDescription, CardHeader, CardTitle } from '@/com
 import { cn } from '@/lib/utils.js';
 import { Trans } from '@/lib/trans.js';
 import { PropsWithChildren, useRef, useEffect, useState, createContext, useContext } from 'react';
+import type React from 'react';
 
 type WidgetDimensions = {
     width: number;

package/src/lib/framework/defaults.ts

@@ -122,6 +122,11 @@ export function registerDefaults() {
                         title: 'Healthchecks',
                         url: '/healthchecks',
                     },
+                    {
+                        id: 'scheduled-tasks',
+                        title: 'Scheduled Tasks',
+                        url: '/scheduled-tasks',
+                    },
                 ],
             },
             {
@@ -216,4 +221,33 @@ export function registerDefaults() {
         component: OrdersSummaryWidget,
         defaultSize: { w: 6, h: 3, x: 6, y: 0 },
     });
+
+    // registerAlert<boolean>({
+    //     id: 'test-alert',
+    //     title: data => `Test Alert ${String(data)}`,
+    //     description: 'This is a test alert',
+    //     severity: 'info',
+    //     check: () => Promise.resolve(true),
+    //     actions: [
+    //         {
+    //             label: 'Test Action',
+    //             onClick: () => console.log('Test Action'),
+    //         },
+    //     ],
+    // });
+
+    // registerAlert<boolean>({
+    //     id: 'test-alert-2',
+    //     title: 'Test Alert 2',
+    //     description: 'This is a test alert 2',
+    //     severity: 'info',
+    //     check: () => Promise.resolve(true),
+    //     shouldShow: data => data === true,
+    //     actions: [
+    //         {
+    //             label: 'Test Action',
+    //             onClick: () => console.log('Test Action'),
+    //         },
+    //     ],
+    // });
 }

package/src/lib/framework/document-introspection/get-document-structure.ts

@@ -2,11 +2,10 @@ import type { TypedDocumentNode } from '@graphql-typed-document-node/core';
 import { VariablesOf } from 'gql.tada';
 import {
     DocumentNode,
-    OperationDefinitionNode,
     FieldNode,
     FragmentDefinitionNode,
     FragmentSpreadNode,
-    VariableDefinitionNode,
+    OperationDefinitionNode,
 } from 'graphql';
 import { DefinitionNode, NamedTypeNode, SelectionSetNode, TypeNode } from 'graphql/language/ast.js';
 import { schemaInfo } from 'virtual:admin-api-schema';

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

@@ -1,14 +1,14 @@
-import { registerDashboardWidget } from '@/framework/dashboard-widget/widget-extensions.js';
-import { DashboardExtension } from '@/framework/extension-api/extension-api-types.js';
-import { addNavMenuItem, NavMenuItem } from '@/framework/nav-menu/nav-menu-extensions.js';
-import { registerRoute } from '@/framework/page/page-api.js';
-
+import { registerDashboardWidget } from '../dashboard-widget/widget-extensions.js';
 import {
     registerDashboardActionBarItem,
     registerDashboardPageBlock,
 } from '../layout-engine/layout-extensions.js';
+import { addNavMenuItem, NavMenuItem } from '../nav-menu/nav-menu-extensions.js';
+import { registerRoute } from '../page/page-api.js';
 import { globalRegistry } from '../registry/global-registry.js';
 
+import { DashboardExtension } from './extension-api-types.js';
+
 globalRegistry.register('extensionSourceChangeCallbacks', new Set<() => void>());
 globalRegistry.register('registerDashboardExtensionCallbacks', new Set<() => void>());
 
@@ -22,6 +22,16 @@ export function executeDashboardExtensionCallbacks() {
     }
 }
 
+/**
+ * @description
+ * **Status: Developer Preview**
+ *
+ * The main entry point for extensions to the React-based dashboard.
+ *
+ *
+ * @docsCategory extensions
+ * @since 3.3.0
+ */
 export function defineDashboardExtension(extension: DashboardExtension) {
     globalRegistry.get('registerDashboardExtensionCallbacks').add(() => {
         if (extension.routes) {

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

@@ -1,9 +1,10 @@
-import { NavMenuItem } from '@/framework/nav-menu/nav-menu-extensions.js';
+import { PageContextValue } from '@/framework/layout-engine/page-provider.js';
 import { AnyRoute, RouteOptions } from '@tanstack/react-router';
-import React from 'react';
+import type React from 'react';
 
+import { DashboardAlertDefinition } from '../alert/types.js';
 import { DashboardWidgetDefinition } from '../dashboard-widget/types.js';
-import { PageContext } from '../layout-engine/page-layout.js';
+import { NavMenuItem } from '../nav-menu/nav-menu-extensions.js';
 
 export interface DashboardRouteDefinition {
     component: (route: AnyRoute) => React.ReactNode;
@@ -17,42 +18,110 @@ export interface ActionBarButtonState {
     visible: boolean;
 }
 
+/**
+ * @description
+ * **Status: Developer Preview**
+ *
+ * Allows you to define custom action bar items for any page in the dashboard.
+ *
+ * @docsCategory extensions
+ * @since 3.3.0
+ */
 export interface DashboardActionBarItem {
-    locationId: string;
-    component: React.FunctionComponent<{ context: PageContext }>;
+    /**
+     * @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.
+     */
+    component: React.FunctionComponent<{ context: PageContextValue }>;
+    /**
+     * @description
+     * Any permissions that are required to display this action bar item.
+     */
     requiresPermission?: string | string[];
 }
 
 export interface DashboardActionBarDropdownMenuItem {
     locationId: string;
-    component: React.FunctionComponent<{ context: PageContext }>;
+    component: React.FunctionComponent<{ context: PageContextValue }>;
     requiresPermission?: string | string[];
 }
 
 export type PageBlockPosition = { blockId: string; order: 'before' | 'after' | 'replace' };
 
+/**
+ * @description
+ * **Status: Developer Preview**
+ *
+ * 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
+ * @since 3.3.0
+ */
 export type PageBlockLocation = {
     pageId: string;
     position: PageBlockPosition;
     column: 'main' | 'side';
 };
 
+/**
+ * @description
+ * **Status: Developer Preview**
+ *
+ * This allows you to insert a custom component into a specific location
+ * on any page in the dashboard.
+ *
+ * @docsCategory extensions
+ * @since 3.3.0
+ */
 export interface DashboardPageBlockDefinition {
     id: string;
     title?: React.ReactNode;
     location: PageBlockLocation;
-    component: React.FunctionComponent<{ context: PageContext }>;
+    component: React.FunctionComponent<{ context: PageContextValue }>;
     requiresPermission?: string | string[];
 }
 
 /**
  * @description
- * The main entry point for a dashboard extension.
+ * **Status: Developer Preview**
+ *
  * This is used to define the routes, widgets, etc. that will be displayed in the dashboard.
+ *
+ * @docsCategory extensions
+ * @since 3.3.0
  */
 export interface DashboardExtension {
-    routes: DashboardRouteDefinition[];
-    widgets: DashboardWidgetDefinition[];
-    actionBarItems: DashboardActionBarItem[];
-    pageBlocks: DashboardPageBlockDefinition[];
+    /**
+     * @description
+     * Allows you to define custom routes such as list or detail views.
+     */
+    routes?: DashboardRouteDefinition[];
+    /**
+     * @description
+     * Allows you to define custom page blocks for any page in the dashboard.
+     */
+    pageBlocks?: DashboardPageBlockDefinition[];
+    /**
+     * @description
+     * Allows you to define custom action bar items for any page in the dashboard.
+     */
+    actionBarItems?: DashboardActionBarItem[];
+    /**
+     * @description
+     * Not yet implemented
+     */
+    alerts?: DashboardAlertDefinition[];
+    /**
+     * @description
+     * Allows you to define custom routes for the dashboard, which will render the
+     * given components and optionally also add a nav menu item.
+     */
+    widgets?: DashboardWidgetDefinition[];
 }

package/src/lib/framework/layout-engine/layout-extensions.ts

@@ -9,13 +9,13 @@ globalRegistry.register('dashboardPageBlockRegistry', new Map<string, DashboardP
 
 export function registerDashboardActionBarItem(item: DashboardActionBarItem) {
     globalRegistry.set('dashboardActionBarItemRegistry', map => {
-        map.set(item.locationId, [...(map.get(item.locationId) ?? []), item]);
+        map.set(item.pageId, [...(map.get(item.pageId) ?? []), item]);
         return map;
     });
 }
 
-export function getDashboardActionBarItems(locationId: string) {
-    return globalRegistry.get('dashboardActionBarItemRegistry').get(locationId) ?? [];
+export function getDashboardActionBarItems(pageId: string) {
+    return globalRegistry.get('dashboardActionBarItemRegistry').get(pageId) ?? [];
 }
 
 export function registerDashboardPageBlock(block: DashboardPageBlockDefinition) {