@vendure/docs 0.0.0-202601161541

package/docs/guides/extending-the-dashboard/customizing-pages/action-bar-items.md

@@ -0,0 +1,272 @@
+---
+title: 'Action Bar Items'
+---
+
+The Action Bar is the bar at the top of the page where you can add
+buttons and other actions.
+
+:::info
+All available options are documented in the [DashboardActionBarItem reference](/reference/dashboard/extensions-api/action-bar#dashboardactionbaritem)
+:::
+
+## Basic Action Bar Item
+
+Here's a simple example of adding a button to the action bar:
+
+```tsx title="src/plugins/my-plugin/dashboard/index.tsx"
+import { Button, defineDashboardExtension } from '@vendure/dashboard';
+import { useState } from 'react';
+
+defineDashboardExtension({
+    actionBarItems: [
+        {
+            pageId: 'product-detail',
+            component: ({ context }) => {
+                const [count, setCount] = useState(0);
+                return (
+                    <Button type="button" variant="secondary" onClick={() => setCount(x => x + 1)}>
+                        Counter: {count}
+                    </Button>
+                );
+            },
+        },
+    ],
+});
+```
+
+![Action bar button](action-bar-button.webp)
+
+## Context Data
+
+The `context` prop provides access to:
+
+- **`entity`**: The current entity being viewed/edited (e.g., Product, Customer, etc.)
+- **`form`**: The React Hook Form instance for the current page (if applicable)
+- **`route`**: Route information and parameters
+
+## Dropdown Menu
+
+You can also define dropdown menu items for the Action Bar. This is useful for secondary actions that are needed
+less often by administrators.
+
+Make sure to always wrap these in the `DropdownMenuItem` component for consistent styling.
+
+```tsx
+import { DropdownMenuItem, defineDashboardExtension } from '@vendure/dashboard';
+import { useState } from 'react';
+
+defineDashboardExtension({
+    actionBarItems: [
+        {
+            pageId: 'product-list',
+            type: 'dropdown',
+            component: () => <DropdownMenuItem variant="default">My Item</DropdownMenuItem>
+        }
+    ],
+});
+```
+
+![Action bar dropdown](action-bar-dropdown.webp)
+
+## Practical Examples
+
+### Export Button
+
+```tsx title="src/plugins/my-plugin/dashboard/index.tsx"
+import { Button, defineDashboardExtension } from '@vendure/dashboard';
+import { DownloadIcon } from 'lucide-react';
+
+defineDashboardExtension({
+    actionBarItems: [
+        {
+            pageId: 'product-detail',
+            component: ({ context }) => {
+                const product = context.entity;
+
+                const handleExport = async () => {
+                    // Export product data
+                    const data = JSON.stringify(product, null, 2);
+                    const blob = new Blob([data], { type: 'application/json' });
+                    const url = URL.createObjectURL(blob);
+
+                    const a = document.createElement('a');
+                    a.href = url;
+                    a.download = `product-${product.id}.json`;
+                    a.click();
+
+                    URL.revokeObjectURL(url);
+                };
+
+                return (
+                    <Button variant="outline" onClick={handleExport} disabled={!product}>
+                        <DownloadIcon className="mr-2 h-4 w-4" />
+                        Export
+                    </Button>
+                );
+            },
+        },
+    ],
+});
+```
+
+### Sync Button with Loading State
+
+```tsx title="src/plugins/my-plugin/dashboard/index.tsx"
+import { Button, defineDashboardExtension } from '@vendure/dashboard';
+import { RefreshCwIcon } from 'lucide-react';
+import { useState } from 'react';
+import { toast } from 'sonner';
+
+defineDashboardExtension({
+    actionBarItems: [
+        {
+            pageId: 'product-detail',
+            component: ({ context }) => {
+                const [isSyncing, setIsSyncing] = useState(false);
+                const product = context.entity;
+
+                const handleSync = async () => {
+                    if (!product) return;
+
+                    setIsSyncing(true);
+                    try {
+                        // Simulate API call to external system
+                        await fetch(`/api/sync-product/${product.id}`, {
+                            method: 'POST',
+                        });
+                        toast.success('Product synced successfully');
+                    } catch (error) {
+                        toast.error('Failed to sync product');
+                    } finally {
+                        setIsSyncing(false);
+                    }
+                };
+
+                return (
+                    <Button variant="outline" onClick={handleSync} disabled={!product || isSyncing}>
+                        <RefreshCwIcon className={`mr-2 h-4 w-4 ${isSyncing ? 'animate-spin' : ''}`} />
+                        {isSyncing ? 'Syncing...' : 'Sync to ERP'}
+                    </Button>
+                );
+            },
+        },
+    ],
+});
+```
+
+### Conditional Action Bar Items
+
+You can conditionally show action bar items based on the entity or user permissions:
+
+```tsx title="src/plugins/my-plugin/dashboard/index.tsx"
+import { Button, defineDashboardExtension, PermissionGuard } from '@vendure/dashboard';
+import { SendIcon } from 'lucide-react';
+
+defineDashboardExtension({
+    actionBarItems: [
+        {
+            pageId: 'customer-detail',
+            component: ({ context }) => {
+                const customer = context.entity;
+
+                // Only show for customers with email addresses
+                if (!customer?.emailAddress) {
+                    return null;
+                }
+
+                const handleSendEmail = () => {
+                    // Open email composer or trigger email send
+                    console.log('Sending email to:', customer.emailAddress);
+                };
+
+                return (
+                    <PermissionGuard requires={['UpdateCustomer']}>
+                        <Button variant="outline" onClick={handleSendEmail}>
+                            <SendIcon className="mr-2 h-4 w-4" />
+                            Send Email
+                        </Button>
+                    </PermissionGuard>
+                );
+            },
+        },
+    ],
+});
+```
+
+## Multiple Action Bar Items
+
+You can add multiple action bar items to the same page:
+
+```tsx title="src/plugins/my-plugin/dashboard/index.tsx"
+import { Button, defineDashboardExtension } from '@vendure/dashboard';
+import { DownloadIcon, RefreshCwIcon, SendIcon } from 'lucide-react';
+
+defineDashboardExtension({
+    actionBarItems: [
+        {
+            pageId: 'product-detail',
+            component: ({ context }) => (
+                <Button variant="outline">
+                    <DownloadIcon className="mr-2 h-4 w-4" />
+                    Export
+                </Button>
+            ),
+        },
+        {
+            pageId: 'product-detail',
+            component: ({ context }) => (
+                <Button variant="outline">
+                    <RefreshCwIcon className="mr-2 h-4 w-4" />
+                    Sync
+                </Button>
+            ),
+        },
+        {
+            pageId: 'product-detail',
+            component: ({ context }) => (
+                <Button variant="outline">
+                    <SendIcon className="mr-2 h-4 w-4" />
+                    Share
+                </Button>
+            ),
+        },
+    ],
+});
+```
+
+## Available Button Variants
+
+The dashboard provides several button variants you can use:
+
+- `default` - Primary button style
+- `secondary` - Secondary button style
+- `outline` - Outlined button style
+- `ghost` - Minimal button style
+- `destructive` - For destructive actions (delete, etc.)
+
+```tsx
+<Button variant="default">Primary</Button>
+<Button variant="secondary">Secondary</Button>
+<Button variant="outline">Outline</Button>
+<Button variant="ghost">Ghost</Button>
+<Button variant="destructive">Delete</Button>
+```
+
+## Best Practices
+
+1. **Use appropriate icons**: Icons help users quickly understand the action
+2. **Provide loading states**: Show loading indicators for async operations
+3. **Handle errors gracefully**: Use toast notifications for feedback
+4. **Consider permissions**: Use `PermissionGuard` for actions that require specific permissions
+5. **Keep labels concise**: Use short, descriptive labels for buttons
+6. **Group related actions**: Consider the order and grouping of multiple action items
+7. **Test thoroughly**: Verify your actions work correctly across different entity states
+
+## Finding Page IDs
+
+To find the `pageId` for your action bar items:
+
+1. Enable [Dev Mode](/guides/extending-the-dashboard/extending-overview/#dev-mode) in the dashboard
+2. Navigate to the page where you want to add your action
+3. The page ID will be shown in the dev mode overlay
+4. Use this ID in your action bar item configuration

package/docs/guides/extending-the-dashboard/customizing-pages/customizing-detail-pages.md

@@ -0,0 +1,129 @@
+---
+title: 'Customizing Detail Pages'
+---
+
+Using the [DashboardDetailFormExtensionDefinition](/reference/dashboard/extensions-api/detail-forms#dashboarddetailformextensiondefinition) you can
+customize any existing detail page in the Dashboard.
+
+## Custom form inputs
+
+You can replace any of the default form inputs with your own components using the `inputs` property.
+
+Let's say you want to replace the default HTML description editor with a markdown editor component:
+
+```tsx title="index.tsx"
+import { defineDashboardExtension } from '@vendure/dashboard';
+
+import { MarkdownEditor } from './markdown-editor';
+
+defineDashboardExtension({
+    detailForms: [
+        {
+            pageId: 'product-detail',
+            inputs: [
+                {
+                    blockId: 'main-form',
+                    field: 'description',
+                    component: MarkdownEditor,
+                },
+            ],
+        },
+    ],
+});
+```
+
+To learn how to build custom form components, see the [Custom Form Elements guide](/guides/extending-the-dashboard/custom-form-components/).
+
+## Extending the detail query
+
+You might want to extend the GraphQL query used to fetch the data for the detail page. For example, to include new
+fields that your plugin has defined so that you can render them in [custom page blocks](/guides/extending-the-dashboard/customizing-pages/page-blocks).
+
+```tsx title="index.tsx"
+import { defineDashboardExtension } from '@vendure/dashboard';
+
+defineDashboardExtension({
+    detailForms: [
+        {
+            pageId: 'product-detail',
+            extendDetailDocument: `
+          query {
+              product(id: $id) {
+                  relatedProducts {
+                      id
+                      name
+                      featuredAsset {
+                        id
+                        preview
+                      }
+                  }
+              }
+          }
+      `,
+        },
+    ],
+});
+```
+
+## Interacting with the detail page form
+
+Sometimes you want to define a [page block](./page-blocks.md) that needs to interact with the detail page's form:
+
+- To take some action when the form is submitted
+- To mark the form as dirty from inside your page block
+
+These advanced use-cases can be achieved by using the `useFormContext` hook from `react-hook-form`.
+
+### Reacting to form submission
+
+Here's how you can use the `formState` to react to a form submission:
+
+```tsx
+import { useEffect } from 'react';
+import { useFormContext } from 'react-hook-form';
+
+export function MyPageBlock() {
+    const { formState: { isSubmitSuccessful } } = useFormContext();
+
+    useEffect(() => {
+        if (isSubmitSuccessful) {
+            console.log('The detail page form was submitted');
+        }
+    }, [isSubmitSuccessful]);
+}
+```
+
+### Setting the form as dirty
+
+Let's say you have a page block that interacts with a custom mutation to set some
+data related to a Product. You want to fire your custom mutation when the form is submitted -
+this is done using the pattern above.
+
+However, you need to somehow signal to the form that it is now dirty and can be save, even though
+no property of the Product itself may have changed.
+
+Here's a work-around to allow this:
+
+```tsx
+import { useEffect } from 'react';
+import { useFormContext } from 'react-hook-form';
+import { Button } from '@vendure/dashboard';
+
+export function MyPageBlock() {
+    const { register } = useFormContext();
+
+    useEffect(() => {
+        // We register a "fake" field on the form that we only use
+        // to track the dirty state of this page block component
+        register('my-page-block-dirty-tracker')
+    }, [register]);
+    
+    return (
+        <Button onClick={() => {
+            // We set that "fake" field to a random value to mark the whole
+            // form as dirty, so the "save" button becomes enabled.
+            setValue('dirty-tracker', Math.random(), { shouldDirty: true });
+        }}>Set dirty</Button>
+    );
+}
+```

package/docs/guides/extending-the-dashboard/customizing-pages/customizing-list-pages.md

@@ -0,0 +1,93 @@
+---
+title: 'Customizing List Pages'
+---
+
+Using the [DashboardDataTableExtensionDefinition](/reference/dashboard/extensions-api/data-tables#dashboarddatatableextensiondefinition) you can
+customize any existing data table in the Dashboard.
+
+## Custom table cell components
+
+You can define your own custom components to render specific table cells:
+
+```tsx title="index.tsx"
+import { defineDashboardExtension } from '@vendure/dashboard';
+
+defineDashboardExtension({
+  dataTables: [{
+      pageId: 'product-list',
+      displayComponents: [
+          {
+              column: 'slug',
+              // The component will be passed the cell's `value`,
+              // as well as all the other objects in the Tanstack Table
+              // `CellContext` object.
+              component: ({ value, cell, row, table }) => {
+                  return (
+                      <a href={`https://storefront.com/products/${value}`} target="_blank">
+                          {value}
+                      </a>
+                  );
+              },
+          },
+      ],
+  }]
+});
+```
+
+## Bulk actions
+
+You can define bulk actions on the selected table items. The bulk action component should use
+[DataTableBulkActionItem](/reference/dashboard/list-views/bulk-actions#datatablebulkactionitem).
+
+```tsx title="index.tsx"
+import { defineDashboardExtension, DataTableBulkActionItem } from '@vendure/dashboard';
+import { InfoIcon } from 'lucide-react';
+
+defineDashboardExtension({
+  dataTables: [{
+      pageId: 'product-list',
+      bulkActions: [
+          {
+              component: props => (
+                  <DataTableBulkActionItem
+                      onClick={() => {
+                          console.log('Selection:', props.selection);
+                          toast.message(`There are ${props.selection.length} selected items`);
+                      }}
+                      label="My Custom Action"
+                      icon={InfoIcon}
+                  />
+              ),
+          },
+      ],
+  }]
+});
+```
+
+## Extending the list query
+
+The GraphQL queries used by list views can be extended using the `extendListDocument` property, and passing 
+the additional fields you want to fetch:
+
+```tsx title="index.tsx"
+import { defineDashboardExtension, DataTableBulkActionItem } from '@vendure/dashboard';
+import { InfoIcon } from 'lucide-react';
+
+defineDashboardExtension({
+  dataTables: [{
+      pageId: 'product-list',
+      extendListDocument: `
+          query {
+              products {
+                  items {
+                      optionGroups {
+                          id
+                          name
+                      }
+                  }
+              }
+          }
+      `,
+  }]
+});
+```

package/docs/guides/extending-the-dashboard/customizing-pages/customizing-login-page.md

@@ -0,0 +1,66 @@
+---
+title: 'Customizing the Login Page'
+---
+
+The login page can be customized with your own logo and messaging, as well as things like SSO login buttons.
+
+Reference documentation can be found at [DashboardLoginExtensions](/reference/dashboard/extensions-api/login#dashboardloginextensions).
+
+## Login page extension points
+
+```tsx title="index.tsx"
+import { defineDashboardExtension } from '@vendure/dashboard';
+
+import { useSsoLogin } from './use-sso-login';
+
+defineDashboardExtension({
+    login: {
+        logo: {
+            component: () => <div className="text-3xl text-muted-foreground">My Logo</div>,
+        },
+        beforeForm: {
+            component: () => <div className="text-muted-foreground">Welcome to My Brand</div>,
+        },
+        afterForm: {
+            component: () => {
+                const { handleLogin } = useSsoLogin();
+                return (
+                    <div>
+                        <Button variant="secondary" className="w-full" onClick={handleLogin}>
+                            Login with SSO
+                        </Button>
+                    </div>
+                );
+            },
+        },
+    },
+});
+```
+
+This will result in a login page like this:
+
+![Login page](./login-page.webp)
+
+## Fully custom login pages
+
+If you need even more control over the login page, you can also create an
+[unauthenticated route](/guides/extending-the-dashboard/navigation/#unauthenticated-routes) with a completely
+custom layout.
+
+```tsx title="index.tsx"
+import { defineDashboardExtension } from '@vendure/dashboard';
+
+defineDashboardExtension({
+    routes: [
+        {
+            path: '/custom-login',
+            component: () => (
+                <div className="flex h-screen items-center justify-center text-2xl">
+                    This custom login page
+                </div>
+            ),
+            authenticated: false,
+        },
+    ],
+});
+```

package/docs/guides/extending-the-dashboard/customizing-pages/history-entries.md

@@ -0,0 +1,43 @@
+---
+title: 'History Entries'
+---
+
+The Customer and Order detail pages have a special history timeline, which show a summary of all significant changes and
+activity relating to that customer or order.
+
+History entries are defined by [DashboardHistoryEntryComponent](/reference/dashboard/extensions-api/history-entries#dashboardhistoryentrycomponent),
+and the component should be wrapped in [HistoryEntry](/reference/dashboard/extensions-api/history-entries#historyentry).
+
+## Example
+
+Following the backend example of a custom history entry given in the [HistoryService docs](/reference/typescript-api/services/history-service),
+we can define a corresponding component to render this entry in the customer history timeline:
+
+```tsx
+import { defineDashboardExtension, HistoryEntry } from '@vendure/dashboard';
+import { IdCard } from 'lucide-react';
+
+defineDashboardExtension({
+    historyEntries: [
+        {
+            type: 'CUSTOMER_TAX_ID_VERIFICATION',
+            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>
+                );
+            },
+        },
+    ],
+});
+```
+
+This will then appear in the customer history timeline:
+
+![History entry](./history-entry.webp)

package/docs/guides/extending-the-dashboard/customizing-pages/index.md

@@ -0,0 +1,10 @@
+---
+title: 'Customizing Pages'
+---
+
+Existing pages in the Dashboard can be customized in many ways:
+
+- [Action bar buttons](/guides/extending-the-dashboard/customizing-pages/action-bar-items) can be added to the top of the page
+- [Page blocks](/guides/extending-the-dashboard/customizing-pages/page-blocks) can be added at any position, and existing page blocks can be replaced or removed.
+- [Extend list pages](/guides/extending-the-dashboard/customizing-pages/customizing-list-pages) with custom components, data and bulk actions
+- [Extend detail pages](/guides/extending-the-dashboard/customizing-pages/customizing-detail-pages) with custom components and data

package/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)