docs(dashboard): Add docs on custom widgets

docs/docs/guides/extending-the-dashboard/customizing-pages/insights-widgets.md

@@ -0,0 +1,57 @@
+---
+title: 'Insights Page Widgets'
+---
+
+The "Insights" page can be extended with custom widgets which are used to display charts, metrics or other information that can
+be useful for administrators to see at a glance.
+
+## Example
+
+Here's an example of a custom widget:
+
+```tsx title="custom-widget.tsx"
+import { Badge, DashboardBaseWidget, useLocalFormat, useWidgetFilters } from '@vendure/dashboard';
+
+export function CustomWidget() {
+    const { dateRange } = useWidgetFilters();
+    const { formatDate } = useLocalFormat();
+    return (
+        <DashboardBaseWidget id="custom-widget" title="Custom Widget" description="This is a custom widget">
+            <div className="flex flex-wrap gap-1">
+                <span>Displaying results from</span>
+                <Badge variant="secondary">{formatDate(dateRange.from)}</Badge>
+                <span>to</span>
+                <Badge variant="secondary">{formatDate(dateRange.to)}</Badge>
+            </div>
+        </DashboardBaseWidget>
+    );
+}
+```
+
+Always wrap your custom widget in the `DashboardBaseWidget` component, which ensures that it will render correctly
+in the Insights page.
+
+Use the `useWidgetFilters()` hook to get the currently-selected date range, if your widget depends on that.
+
+Then register your widget in your dashboard entrypoint file:
+
+```tsx title="index.tsx"
+import { defineDashboardExtension } from '@vendure/dashboard';
+
+import { CustomWidget } from './custom-widget';
+
+defineDashboardExtension({
+    widgets: [
+        {
+            id: 'custom-widget',
+            name: 'Custom Widget',
+            component: CustomWidget,
+            defaultSize: { w: 3, h: 3 },
+        },
+    ],
+});
+```
+
+Your widget should now be available on the Insights page:
+
+![Custom widget](./custom-widget.webp)

docs/docs/reference/dashboard/extensions-api/data-tables.md

@@ -11,7 +11,7 @@ import MemberDescription from '@site/src/components/MemberDescription';
 
 ## DashboardDataTableExtensionDefinition
 
-<GenerationInfo sourceFile="packages/dashboard/src/lib/framework/extension-api/types/data-table.ts" sourceLine="126" packageName="@vendure/dashboard" since="3.4.0" />
+<GenerationInfo sourceFile="packages/dashboard/src/lib/framework/extension-api/types/data-table.ts" sourceLine="129" packageName="@vendure/dashboard" since="3.4.0" />
 
 This allows you to customize aspects of existing data tables in the dashboard.
 

docs/docs/reference/dashboard/hooks/use-widget-filters.md

@@ -0,0 +1,20 @@
+---
+title: "UseWidgetFilters"
+isDefaultIndex: false
+generated: true
+---
+<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
+import MemberInfo from '@site/src/components/MemberInfo';
+import GenerationInfo from '@site/src/components/GenerationInfo';
+import MemberDescription from '@site/src/components/MemberDescription';
+
+
+## useWidgetFilters
+
+<GenerationInfo sourceFile="packages/dashboard/src/lib/framework/dashboard-widget/widget-filters-context.tsx" sourceLine="29" packageName="@vendure/dashboard" since="3.5.0" />
+
+Exposes a context object for use in building Insights page widgets.
+
+```ts title="Signature"
+function useWidgetFilters(): void
+```

docs/docs/reference/dashboard/list-views/bulk-actions.md

@@ -111,7 +111,7 @@ Parameters
 
 ## BulkAction
 
-<GenerationInfo sourceFile="packages/dashboard/src/lib/framework/extension-api/types/data-table.ts" sourceLine="104" packageName="@vendure/dashboard" since="3.4.0" />
+<GenerationInfo sourceFile="packages/dashboard/src/lib/framework/extension-api/types/data-table.ts" sourceLine="107" packageName="@vendure/dashboard" since="3.4.0" />
 
 A bulk action is a component that will be rendered in the bulk actions dropdown.
 

docs/docs/reference/dashboard/list-views/data-table.md

@@ -169,7 +169,7 @@ when needed.
 
 ## DashboardDataTableDisplayComponent
 
-<GenerationInfo sourceFile="packages/dashboard/src/lib/framework/extension-api/types/data-table.ts" sourceLine="13" packageName="@vendure/dashboard" since="3.4.0" />
+<GenerationInfo sourceFile="packages/dashboard/src/lib/framework/extension-api/types/data-table.ts" sourceLine="16" packageName="@vendure/dashboard" since="3.4.0" />
 
 Allows you to define custom display components for specific columns in data tables.
 The pageId is already defined in the data table extension, so only the column name is needed.
@@ -177,7 +177,7 @@ The pageId is already defined in the data table extension, so only the column na
 ```ts title="Signature"
 interface DashboardDataTableDisplayComponent {
     column: string;
-    component: React.ComponentType<{ value: any; [key: string]: any }>;
+    component: React.ComponentType<DataDisplayComponentProps<CellContext<any, any>>>;
 }
 ```
 
@@ -190,7 +190,7 @@ interface DashboardDataTableDisplayComponent {
 The name of the column where this display component should be used.
 ### component
 
-<MemberInfo kind="property" type={`React.ComponentType&#60;{ value: any; [key: string]: any }&#62;`}   />
+<MemberInfo kind="property" type={`React.ComponentType&#60;DataDisplayComponentProps&#60;CellContext&#60;any, any&#62;&#62;&#62;`}   />
 
 The React component that will be rendered as the display.
 It should accept `value` and other standard display props.

docs/sidebars.js

@@ -161,6 +161,7 @@ const sidebars = {
                         'guides/extending-the-dashboard/customizing-pages/customizing-login-page',
                         'guides/extending-the-dashboard/customizing-pages/page-blocks',
                         'guides/extending-the-dashboard/customizing-pages/action-bar-items',
+                        'guides/extending-the-dashboard/customizing-pages/insights-widgets',
                     ],
                 },
                 {