feat: add sections support to vaadin-dashboard (#7692)

dev/dashboard.html

@@ -49,43 +49,39 @@
           content: '+203%',
           type: 'kpi',
           header: '2023-2024',
-          colspan: 1,
-          rowspan: 1,
         },
         {
           title: 'Sales',
           type: 'chart',
           header: '2023-2024',
           colspan: 2,
-          rowspan: 1,
         },
         {
-          title: 'Sales closed this month',
-          content: '54 000€',
-          type: 'kpi',
-          colspan: 1,
-          rowspan: 1,
-        },
-        {
-          title: 'Just some number',
-          content: '1234',
-          type: 'kpi',
-          header: '2014-2024',
-          colspan: 1,
-          rowspan: 1,
+          title: 'Section',
+          items: [
+            {
+              title: 'Sales closed this month',
+              content: '54 000€',
+              type: 'kpi',
+            },
+            {
+              title: 'Just some number',
+              content: '1234',
+              type: 'kpi',
+              header: '2014-2024',
+            },
+          ],
         },
         {
           title: 'Activity since 2023',
           type: 'chart',
-          colspan: 1,
-          rowspan: 1,
         },
       ];
 
       dashboard.renderer = (root, _dashboard, { item }) => {
         root.innerHTML = `
           <vaadin-dashboard-widget widget-title="${item.title}">
-            <span slot="header">${item.header}</span>
+            <span slot="header">${item.header || ''}</span>
             ${item.type === 'chart' ? '<div class="chart"></div>' : `<div class="kpi-number">${item.content}</div>`}
           </vaadin-dashboard-widget>
         `;

packages/dashboard/src/vaadin-dashboard-section.js

@@ -53,6 +53,10 @@ class DashboardSection extends ControllerMixin(ElementMixin(PolylitMixin(LitElem
         grid-column: var(--_vaadin-dashboard-item-column);
       }
 
+      ::slotted(vaadin-dashboard-cell) {
+        display: contents;
+      }
+
       header {
         display: flex;
         grid-column: var(--_vaadin-dashboard-section-column);

packages/dashboard/src/vaadin-dashboard.d.ts

@@ -8,6 +8,8 @@
  * See https://vaadin.com/commercial-license-and-service-terms for the full
  * license.
  */
+import './vaadin-dashboard-widget.js';
+import './vaadin-dashboard-section.js';
 import { ElementMixin } from '@vaadin/component-base/src/element-mixin.js';
 import { DashboardLayoutMixin } from './vaadin-dashboard-layout-mixin.js';
 
@@ -18,6 +20,18 @@ export interface DashboardItem {
   colspan?: number;
 }
 
+export interface DashboardSectionItem<TItem extends DashboardItem> {
+  /**
+   * The title of the section
+   */
+  title: string | null | undefined;
+
+  /**
+   * The items of the section
+   */
+  items: TItem[];
+}
+
 export interface DashboardItemModel<TItem> {
   item: TItem;
 }
@@ -37,7 +51,7 @@ declare class Dashboard<TItem extends DashboardItem = DashboardItem> extends Das
   /**
    * An array containing the items of the dashboard
    */
-  items: TItem[];
+  items: Array<TItem | DashboardSectionItem<TItem>>;
 
   /**
    * Custom function for rendering a widget for each dashboard item.

packages/dashboard/src/vaadin-dashboard.js

@@ -9,6 +9,7 @@
  * license.
  */
 import './vaadin-dashboard-widget.js';
+import './vaadin-dashboard-section.js';
 import { html, LitElement, render } from 'lit';
 import { defineCustomElement } from '@vaadin/component-base/src/define.js';
 import { ElementMixin } from '@vaadin/component-base/src/element-mixin.js';
@@ -99,6 +100,16 @@ class Dashboard extends DashboardLayoutMixin(ElementMixin(ThemableMixin(PolylitM
   /** @private */
   __renderItemCells(items) {
     return items.map((item) => {
+      if (item.items) {
+        return html`<vaadin-dashboard-section
+          .__item="${item}"
+          .sectionTitle="${item.title || ''}"
+          .items="${item.items}"
+        >
+          ${this.__renderItemCells(item.items)}
+        </vaadin-dashboard-section>`;
+      }
+
       return html`<vaadin-dashboard-cell
         .__item="${item}"
         style="--vaadin-dashboard-item-colspan: ${item.colspan};"

packages/dashboard/test/dashboard.test.ts

@@ -109,4 +109,39 @@ describe('dashboard', () => {
       expect(getElementFromCell(dashboard, 0, 1)).to.equal(widget);
     });
   });
+
+  describe('section', () => {
+    beforeEach(async () => {
+      dashboard.items = [
+        { id: 'Item 0' },
+        { id: 'Item 1' },
+        { title: 'Section', items: [{ id: 'Item 2' }, { id: 'Item 3' }] },
+      ];
+      await nextFrame();
+    });
+
+    it('should render widgets inside a section', () => {
+      const widget = getElementFromCell(dashboard, 1, 0);
+      const section = widget?.closest('vaadin-dashboard-section');
+      expect(section).to.be.ok;
+    });
+
+    it('should render a section title', () => {
+      const widget = getElementFromCell(dashboard, 1, 0);
+      const section = widget?.closest('vaadin-dashboard-section');
+      expect(section?.sectionTitle).to.equal('Section');
+    });
+
+    it('should render a widget for each section item', () => {
+      const widget2 = getElementFromCell(dashboard, 1, 0);
+      expect(widget2).to.be.ok;
+      expect(widget2?.localName).to.equal('vaadin-dashboard-widget');
+      expect(widget2).to.have.property('widgetTitle', 'Item 2 title');
+
+      const widget3 = getElementFromCell(dashboard, 1, 1);
+      expect(widget3).to.be.ok;
+      expect(widget3?.localName).to.equal('vaadin-dashboard-widget');
+      expect(widget3).to.have.property('widgetTitle', 'Item 3 title');
+    });
+  });
 });

packages/dashboard/test/typings/dashboard.types.ts

@@ -1,7 +1,7 @@
 import type { ElementMixinClass } from '@vaadin/component-base/src/element-mixin.js';
 import { TitleController } from '../../src/title-controller.js';
 import type { DashboardLayoutMixinClass } from '../../src/vaadin-dashboard-layout-mixin.js';
-import type { Dashboard, DashboardItem, DashboardRenderer } from '../../vaadin-dashboard.js';
+import type { Dashboard, DashboardItem, DashboardRenderer, DashboardSectionItem } from '../../vaadin-dashboard.js';
 import type { DashboardLayout } from '../../vaadin-dashboard-layout.js';
 import type { DashboardSection } from '../../vaadin-dashboard-section.js';
 import type { DashboardWidget } from '../../vaadin-dashboard-widget.js';
@@ -18,15 +18,16 @@ assertType<Dashboard>(genericDashboard);
 
 assertType<ElementMixinClass>(genericDashboard);
 assertType<DashboardLayoutMixinClass>(genericDashboard);
-assertType<DashboardItem[] | null | undefined>(genericDashboard.items);
+assertType<Array<DashboardItem | DashboardSectionItem<DashboardItem>> | null | undefined>(genericDashboard.items);
 
 const narrowedDashboard = document.createElement('vaadin-dashboard') as unknown as Dashboard<TestDashboardItem>;
 assertType<Dashboard<TestDashboardItem>>(narrowedDashboard);
-assertType<TestDashboardItem[]>(narrowedDashboard.items);
+assertType<Array<TestDashboardItem | DashboardSectionItem<TestDashboardItem>>>(narrowedDashboard.items);
 assertType<DashboardRenderer<TestDashboardItem> | null | undefined>(narrowedDashboard.renderer);
-assertType<{ colspan?: number }>(narrowedDashboard.items[0]);
-
-/* DashboardLayout */
+assertType<
+  | { colspan?: number; testProperty: string }
+  | { title: string | null | undefined; items: Array<{ colspan?: number; testProperty: string }> }
+>(narrowedDashboard.items[0]);
 const layout = document.createElement('vaadin-dashboard-layout');
 assertType<DashboardLayout>(layout);