feat: modular dashboards - widgets (#13683)

[RFC Here](#11862).

You can test the feature by running `pnpm dev dashboard` on this branch.

<details>
<summary>Old (obsolete) example</summary>

See the [comment
below](#13683 (comment))
explaining the change in approach we took


https://github.com/user-attachments/assets/96157f83-c5d7-4350-9f31-c014daedb2a8

</details>

### New demo


https://github.com/user-attachments/assets/6c08d8d6-c989-4845-b56f-6d3fbd30b1af

## Future Work 

The following improvements are planned but will be added in the future: 

- fields: You'll be able to define `fields` that a widget receives,
which will serve as props in the component. Why might this be useful?
Imagine a chart widget that can have a weekly, daily, or yearly view. Or
a "count" widget that shows how many documents there are in a collection
(the collection could be a field).
- A11y (EDITED): Okay, I finally went the extra mile here, and you can
reorder and resize it with the keyboard. The screen reader works,
although there's room for improvement.
- Dashboard presets: we're planning to add the ability to create and
share dashboard presets, similar to how [query
presets](https://payloadcms.com/docs/query-presets/overview) work today.
For example, you could build dashboards that adjust based on a variable,
such as a "daily, weekly, or monthly" interval. You could also create
dashboards tailored to different focus areas, like "marketing, sales, or
product."

Author: GermanJablo

.github/workflows/main.yml

@@ -233,6 +233,7 @@ jobs:
           - auth
           - auth-basic
           - bulk-edit
+          - dashboard
           - joins
           - field-error-states
           - fields-relationship
@@ -387,6 +388,7 @@ jobs:
           - auth
           - auth-basic
           - bulk-edit
+          - dashboard
           - joins
           - field-error-states
           - fields-relationship

docs/custom-components/custom-views.mdx

@@ -46,6 +46,11 @@ const config = buildConfig({
 })
 ```
 
+<Banner type="success">
+  **Note:** The dashboard is a special case, where in addition to replacing the
+  default view, [you can add widgets modularly](../custom-components/dashboard).
+</Banner>
+
 For more granular control, pass a configuration object instead. Payload exposes the following properties for each view:
 
 | Property       | Description                                                                                                                                                                         |

docs/custom-components/dashboard.mdx

@@ -0,0 +1,153 @@
+---
+title: Dashboard Widgets
+label: Dashboard
+order: 45
+desc: Create custom dashboard widgets to display data, analytics, or any other content in the Payload Admin Panel.
+keywords: dashboard, widgets, custom components, admin, React
+---
+
+<Banner type="warning">
+  This new Modular Dashboard is an experimental feature and may change in future
+  releases. Use at your own risk.
+</Banner>
+
+The Dashboard is the first page users see when they log into the Payload Admin Panel. By default, it displays cards with the collections and globals. You can customize the dashboard by adding **widgets** - modular components that can display data, analytics, or any other content.
+
+One of the coolest things about widgets is that each plugin can define its own. Some examples:
+
+- Analytics
+- Error Reporting
+- Number of documents that meet a certain filter
+- Jobs recently executed
+
+### Defining Widgets
+
+Define widgets in your Payload config using the `admin.dashboard.widgets` property:
+
+```ts
+import { buildConfig } from 'payload'
+
+export default buildConfig({
+  // ...
+  admin: {
+    dashboard: {
+      widgets: [
+        {
+          slug: 'user-stats',
+          ComponentPath: './components/UserStats.tsx#default',
+          minWidth: 'medium',
+          maxWidth: 'full',
+        },
+        {
+          slug: 'revenue-chart',
+          ComponentPath: './components/RevenueChart.tsx#default',
+          minWidth: 'small',
+        },
+      ],
+    },
+  },
+})
+```
+
+### Widget Configuration
+
+| Property           | Type          | Description                                                          |
+| ------------------ | ------------- | -------------------------------------------------------------------- |
+| `slug` \*          | `string`      | Unique identifier for the widget                                     |
+| `ComponentPath` \* | `string`      | Path to the widget component (supports `#` syntax for named exports) |
+| `minWidth`         | `WidgetWidth` | Minimum width the widget can be resized to (default: `'x-small'`)    |
+| `maxWidth`         | `WidgetWidth` | Maximum width the widget can be resized to (default: `'full'`)       |
+
+**WidgetWidth Values:** `'x-small'` \| `'small'` \| `'medium'` \| `'large'` \| `'x-large'` \| `'full'`
+
+### Creating a Widget Component
+
+Widgets are React Server Components that receive `WidgetServerProps`:
+
+```tsx
+import type { WidgetServerProps } from 'payload'
+
+export default async function UserStatsWidget({ req }: WidgetServerProps) {
+  const { payload } = req
+
+  // Fetch data server-side
+  const userCount = await payload.count({ collection: 'users' })
+
+  return (
+    <div className="card">
+      <h3>Total Users</h3>
+      <p style={{ fontSize: '32px', fontWeight: 'bold' }}>
+        {userCount.totalDocs}
+      </p>
+    </div>
+  )
+}
+```
+
+For visual consistency with the Payload UI, we recommend:
+
+1. Using the `card` class for your root element, unless you don't want it to have a background color.
+2. Using our theme variables for backgrounds and text colors. For example, use `var(--theme-elevation-0)` for backgrounds and `var(--theme-text)` for text colors.
+
+### Default Layout
+
+Control the initial dashboard layout with the `defaultLayout` property:
+
+```ts
+export default buildConfig({
+  admin: {
+    dashboard: {
+      defaultLayout: ({ req }) => {
+        // Customize layout based on user role or other factors
+        const isAdmin = req.user?.roles?.includes('admin')
+
+        return [
+          { widgetSlug: 'collections', width: 'full' },
+          { widgetSlug: 'user-stats', width: isAdmin ? 'medium' : 'full' },
+          { widgetSlug: 'revenue-chart', width: 'full' },
+        ]
+      },
+      widgets: [
+        // ... widget definitions
+      ],
+    },
+  },
+})
+```
+
+The `defaultLayout` function receives the request object and should return an array of `WidgetInstance` objects.
+
+#### WidgetInstance Type
+
+| Property        | Type          | Description                                     |
+| --------------- | ------------- | ----------------------------------------------- |
+| `widgetSlug` \* | `string`      | Slug of the widget to display                   |
+| `width`         | `WidgetWidth` | Initial width of the widget (default: minWidth) |
+
+<Banner type="success">
+  **Tip:** Users can customize their dashboard layout, which is saved to their
+  preferences. The `defaultLayout` is only used for first-time visitors or after
+  a layout reset.
+</Banner>
+
+### Built-in Widgets
+
+Payload includes a built-in `collections` widget that displays collection and global cards.
+
+If you don't define a `defaultLayout`, the collections widget will be automatically included in your dashboard.
+
+### User Customization
+
+{/* TODO: maybe a good GIF here? */}
+
+Users can customize their dashboard by:
+
+1. Clicking the dashboard dropdown in the breadcrumb
+2. Selecting "Edit Dashboard"
+3. Adding widgets via the "Add +" button
+4. Resizing widgets using the width dropdown on each widget
+5. Reordering widgets via drag-and-drop
+6. Deleting widgets using the delete button
+7. Saving changes or canceling to revert
+
+Users can also reset their dashboard to the default layout using the "Reset Layout" option.

docs/custom-components/root-components.mdx

@@ -127,6 +127,12 @@ export default function MyBeforeDashboardComponent() {
 }
 ```
 
+<Banner type="success">
+  **Note:** You can also set [Dashboard Widgets](../custom-components/dashboard)
+  in the `admin.dashboard` property, or replace the entire [Dashboard
+  View](../custom-components/dashboard) with your own.
+</Banner>
+
 ### afterDashboard
 
 Similar to `beforeDashboard`, the `afterDashboard` property allows you to inject Custom Components into the built-in Dashboard, _after_ the default dashboard contents.
@@ -156,6 +162,12 @@ export default function MyAfterDashboardComponent() {
 }
 ```
 
+<Banner type="success">
+  **Note:** You can also set [Dashboard Widgets](../custom-components/dashboard)
+  in the `admin.dashboard` property, or replace the entire [Dashboard
+  View](../custom-components/dashboard) with your own.
+</Banner>
+
 ### beforeLogin
 
 The `beforeLogin` property allows you to inject Custom Components into the built-in Login view, _before_ the default login form.

packages/next/package.json

@@ -109,6 +109,8 @@
   },
   "dependencies": {
     "@dnd-kit/core": "6.0.8",
+    "@dnd-kit/modifiers": "9.0.0",
+    "@dnd-kit/sortable": "7.0.2",
     "@payloadcms/graphql": "workspace:*",
     "@payloadcms/translations": "workspace:*",
     "@payloadcms/ui": "workspace:*",

packages/next/src/utilities/getVisibleEntities.ts

@@ -6,6 +6,8 @@ import { buildTableStateHandler } from '@payloadcms/ui/utilities/buildTableState
 import { getFolderResultsComponentAndDataHandler } from '@payloadcms/ui/utilities/getFolderResultsComponentAndData'
 import { schedulePublishHandler } from '@payloadcms/ui/utilities/schedulePublishHandler'
 
+import { getDefaultLayoutHandler } from '../views/Dashboard/Default/ModularDashboard/renderWidget/getDefaultLayoutServerFn.js'
+import { renderWidgetHandler } from '../views/Dashboard/Default/ModularDashboard/renderWidget/renderWidgetServerFn.js'
 import { renderDocumentHandler } from '../views/Document/handleServerFunction.js'
 import { renderDocumentSlotsHandler } from '../views/Document/renderDocumentSlots.js'
 import { renderListHandler } from '../views/List/handleServerFunction.js'
@@ -15,11 +17,13 @@ import { slugifyHandler } from './slugify.js'
 const baseServerFunctions: Record<string, ServerFunction<any, any>> = {
   'copy-data-from-locale': copyDataFromLocaleHandler,
   'form-state': buildFormStateHandler,
+  'get-default-layout': getDefaultLayoutHandler,
   'get-folder-results-component-and-data': getFolderResultsComponentAndDataHandler,
   'render-document': renderDocumentHandler,
   'render-document-slots': renderDocumentSlotsHandler,
   'render-field': _internal_renderFieldHandler,
   'render-list': renderListHandler,
+  'render-widget': renderWidgetHandler,
   'schedule-publish': schedulePublishHandler,
   slugify: slugifyHandler,
   'table-state': buildTableStateHandler,

packages/next/src/utilities/handleServerFunctions.ts

@@ -0,0 +1,128 @@
+'use client'
+import type { ClientWidget } from 'payload'
+
+import {
+  Button,
+  DrawerToggler,
+  ItemsDrawer,
+  type ReactSelectOption as Option,
+  ReactSelect,
+  useStepNav,
+  useTranslation,
+} from '@payloadcms/ui'
+import { useEffect, useId } from 'react'
+
+export function DashboardStepNav({
+  addWidget,
+  cancel,
+  isEditing,
+  resetLayout,
+  saveLayout,
+  setIsEditing,
+  widgets,
+}: {
+  addWidget: (slug: string) => void
+  cancel: () => void
+  isEditing: boolean
+  resetLayout: () => Promise<void>
+  saveLayout: () => Promise<void>
+  setIsEditing: (isEditing: boolean) => void
+  widgets: ClientWidget[]
+}) {
+  const { t } = useTranslation()
+  const { setStepNav } = useStepNav()
+  const uuid = useId()
+  const drawerSlug = `widgets-drawer-${uuid}`
+
+  useEffect(() => {
+    setStepNav([
+      {
+        label: (
+          <DashboardBreadcrumbDropdown
+            isEditing={isEditing}
+            onCancel={cancel}
+            onEditClick={() => setIsEditing(true)}
+            onResetLayout={resetLayout}
+            onSaveChanges={saveLayout}
+            widgetsDrawerSlug={drawerSlug}
+          />
+        ),
+      },
+    ])
+  }, [isEditing, drawerSlug, cancel, resetLayout, saveLayout, setIsEditing, setStepNav])
+
+  return (
+    <>
+      {isEditing && (
+        <ItemsDrawer
+          drawerSlug={drawerSlug}
+          items={widgets}
+          onItemClick={(widget) => addWidget(widget.slug)}
+          searchPlaceholder={t('dashboard:searchWidgets')}
+          title={t('dashboard:addWidget')}
+        />
+      )}
+    </>
+  )
+}
+
+export function DashboardBreadcrumbDropdown(props: {
+  isEditing: boolean
+  onCancel: () => void
+  onEditClick: () => void
+  onResetLayout: () => void
+  onSaveChanges: () => void
+  widgetsDrawerSlug: string
+}) {
+  const { isEditing, onCancel, onEditClick, onResetLayout, onSaveChanges, widgetsDrawerSlug } =
+    props
+  if (isEditing) {
+    return (
+      <div className="dashboard-breadcrumb-dropdown__editing">
+        <span>Editing Dashboard</span>
+        <div className="dashboard-breadcrumb-dropdown__actions">
+          <DrawerToggler className="drawer-toggler--unstyled" slug={widgetsDrawerSlug}>
+            <Button buttonStyle="pill" el="span" size="small">
+              Add +
+            </Button>
+          </DrawerToggler>
+          <Button buttonStyle="pill" onClick={onSaveChanges} size="small">
+            Save Changes
+          </Button>
+          <Button buttonStyle="pill" onClick={onCancel} size="small">
+            Cancel
+          </Button>
+        </div>
+      </div>
+    )
+  }
+
+  const options = [
+    { label: 'Edit Dashboard', value: 'edit' },
+    { label: 'Reset Layout', value: 'reset' },
+  ]
+
+  const handleChange = (selectedOption: Option | Option[]) => {
+    // Since isMulti is false, we expect a single Option
+    const option = Array.isArray(selectedOption) ? selectedOption[0] : selectedOption
+
+    if (option?.value === 'edit') {
+      onEditClick()
+    } else if (option?.value === 'reset') {
+      onResetLayout()
+    }
+  }
+
+  return (
+    <ReactSelect
+      className="dashboard-breadcrumb-select"
+      isClearable={false}
+      isSearchable={false}
+      menuIsOpen={undefined} // Let ReactSelect handle open/close
+      onChange={handleChange}
+      options={options}
+      placeholder="Dashboard"
+      value={{ label: 'Dashboard', value: 'dashboard' }}
+    />
+  )
+}