feat: dashboard keyboard interactions

dev/dashboard.html

@@ -10,7 +10,6 @@
     <style>
       vaadin-dashboard-widget {
         background-color: #f5f5f5;
-        border: 1px solid #e0e0e0;
         border-radius: 4px;
         padding: 10px;
       }
@@ -82,11 +81,13 @@
       ];
 
       dashboard.renderer = (root, _dashboard, { item }) => {
-        root.innerHTML = `
-          <vaadin-dashboard-widget widget-title="${item.title}">
-            <span slot="header">${item.header || ''}</span>
-            ${item.type === 'chart' ? '<div class="chart"></div>' : `<div class="kpi-number">${item.content}</div>`}
-          </vaadin-dashboard-widget>
+        if (!root.firstElementChild) {
+          root.append(document.createElement('vaadin-dashboard-widget'));
+        }
+        root.firstElementChild.widgetTitle = item.title;
+        root.firstElementChild.innerHTML = `
+          <span slot="header">${item.header || ''}</span>
+          ${item.type === 'chart' ? '<div class="chart"></div>' : `<div class="kpi-number">${item.content}</div>`}
         `;
       };
 

packages/dashboard/src/keyboard-controller.js

@@ -0,0 +1,91 @@
+/**
+ * @license
+ * Copyright (c) 2019 - 2024 Vaadin Ltd.
+ * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
+ */
+
+import { fireMove, fireRemove, fireResize } from './vaadin-dashboard-helpers.js';
+
+/**
+ * A controller for managing widget/section keyboard interactions.
+ */
+export class KeyboardController {
+  constructor(host) {
+    this.host = host;
+
+    host.addEventListener('focusout', (e) => this.__focusout(e));
+    host.addEventListener('focusin', (e) => this.__focusin(e));
+    host.addEventListener('keydown', (e) => this.__keydown(e));
+  }
+
+  /** @private */
+  __focusout() {
+    this.host.__focused = false;
+    this.host.__selected = false;
+  }
+
+  /** @private */
+  __focusin(e) {
+    if (e.target === this.host) {
+      this.host.__focused = true;
+    }
+  }
+
+  /** @private */
+  __keydown(e) {
+    if (e.metaKey || e.ctrlKey || !this.host.__selected) {
+      return;
+    }
+
+    if (e.key === 'Backspace' || e.key === 'Delete') {
+      this.__delete(e);
+    } else if (e.key === 'Escape') {
+      this.__escape(e);
+    } else if (e.shiftKey && e.key.startsWith('Arrow')) {
+      this.__resize(e);
+    } else if (e.key.startsWith('Arrow')) {
+      this.__move(e);
+    }
+  }
+
+  /** @private */
+  __delete(e) {
+    e.preventDefault();
+    fireRemove(this.host);
+  }
+
+  /** @private */
+  __escape(e) {
+    e.preventDefault();
+    this.host.__selected = false;
+    this.host.focus();
+  }
+
+  /** @private */
+  __resize(e) {
+    const resizeMap = {
+      ArrowRight: [document.dir === 'rtl' ? -1 : 1, 0],
+      ArrowLeft: [document.dir === 'rtl' ? 1 : -1, 0],
+      ArrowDown: [0, 1],
+      ArrowUp: [0, -1],
+    };
+    if (resizeMap[e.key]) {
+      e.preventDefault();
+      fireResize(this.host, ...resizeMap[e.key]);
+    }
+  }
+
+  /** @private */
+  __move(e) {
+    const moveMap = {
+      ArrowRight: document.dir === 'rtl' ? -1 : 1,
+      ArrowLeft: document.dir === 'rtl' ? 1 : -1,
+      ArrowDown: 1,
+      ArrowUp: -1,
+    };
+    if (moveMap[e.key]) {
+      e.preventDefault();
+      fireMove(this.host, moveMap[e.key]);
+    }
+  }
+}

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

@@ -33,3 +33,48 @@ export function getItemsArrayOfItem(item, items) {
 export function getElementItem(element) {
   return element.closest(WRAPPER_LOCAL_NAME).__item;
 }
+
+/**
+ * Dispatches a custom event to notify about a move operation.
+ *
+ * @param {HTMLElement} element
+ * @param {Number} delta
+ */
+export function fireMove(element, delta) {
+  element.dispatchEvent(
+    new CustomEvent('item-move', {
+      bubbles: true,
+      composed: true,
+      detail: { delta },
+    }),
+  );
+}
+
+/**
+ * Dispatches a custom event to notify about a resize operation.
+ *
+ * @param {HTMLElement} element
+ * @param {Number} colspanDelta
+ * @param {Number} rowspanDelta
+ */
+export function fireResize(element, colspanDelta, rowspanDelta) {
+  element.dispatchEvent(
+    new CustomEvent('item-resize', {
+      bubbles: true,
+      composed: true,
+      detail: {
+        colspanDelta,
+        rowspanDelta,
+      },
+    }),
+  );
+}
+
+/**
+ * Dispatches a custom event to notify about a remove operation.
+ *
+ * @param {HTMLElement} element
+ */
+export function fireRemove(element) {
+  element.dispatchEvent(new CustomEvent('item-remove', { bubbles: true, composed: true }));
+}

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

@@ -9,12 +9,15 @@
  * license.
  */
 import { html, LitElement } from 'lit';
+import { FocusTrapController } from '@vaadin/a11y-base/src/focus-trap-controller.js';
 import { ControllerMixin } from '@vaadin/component-base/src/controller-mixin.js';
 import { defineCustomElement } from '@vaadin/component-base/src/define.js';
 import { ElementMixin } from '@vaadin/component-base/src/element-mixin.js';
 import { PolylitMixin } from '@vaadin/component-base/src/polylit-mixin.js';
 import { css } from '@vaadin/vaadin-themable-mixin/vaadin-themable-mixin.js';
+import { KeyboardController } from './keyboard-controller.js';
 import { TitleController } from './title-controller.js';
+import { fireRemove } from './vaadin-dashboard-helpers.js';
 import { dashboardWidgetAndSectionStyles, hasWidgetWrappers } from './vaadin-dashboard-styles.js';
 
 /**
@@ -93,25 +96,54 @@ class DashboardSection extends ControllerMixin(ElementMixin(PolylitMixin(LitElem
         value: '',
         observer: '__onSectionTitleChanged',
       },
+
+      /** @private */
+      __selected: {
+        type: Boolean,
+        reflectToAttribute: true,
+        attribute: 'selected',
+        observer: '__selectedChanged',
+      },
+
+      /** @private */
+      __focused: {
+        type: Boolean,
+        reflectToAttribute: true,
+        attribute: 'focused',
+      },
     };
   }
 
   /** @protected */
   render() {
     return html`
-      <header>
-        <button id="drag-handle" draggable="true" class="drag-handle" tabindex="-1"></button>
-        <slot name="title" @slotchange="${this.__onTitleSlotChange}"></slot>
-        <button id="remove-button" tabindex="-1" @click="${() => this.__remove()}"></button>
-      </header>
+      <button
+        aria-label="Select Section Title for editing"
+        id="focus-button"
+        draggable="true"
+        class="drag-handle"
+        @click="${() => {
+          this.__selected = true;
+        }}"
+      ></button>
+
+      <div id="focustrap">
+        <header>
+          <button id="drag-handle" draggable="true" class="drag-handle" tabindex="${this.__selected ? 0 : -1}"></button>
+          <slot name="title" @slotchange="${this.__onTitleSlotChange}"></slot>
+          <button id="remove-button" tabindex="${this.__selected ? 0 : -1}" @click="${() => fireRemove(this)}"></button>
+        </header>
+      </div>
 
       <slot></slot>
     `;
   }
 
   constructor() {
     super();
+    this.__keyboardController = new KeyboardController(this);
     this.__titleController = new TitleController(this);
+    this.__focusTrapController = new FocusTrapController(this);
     this.__titleController.addEventListener('slot-content-changed', (event) => {
       const { node } = event.target;
       if (node) {
@@ -123,7 +155,9 @@ class DashboardSection extends ControllerMixin(ElementMixin(PolylitMixin(LitElem
   /** @protected */
   ready() {
     super.ready();
+    this.addController(this.__keyboardController);
     this.addController(this.__titleController);
+    this.addController(this.__focusTrapController);
 
     if (!this.hasAttribute('role')) {
       this.setAttribute('role', 'section');
@@ -136,8 +170,20 @@ class DashboardSection extends ControllerMixin(ElementMixin(PolylitMixin(LitElem
   }
 
   /** @private */
-  __remove() {
-    this.dispatchEvent(new CustomEvent('item-remove', { bubbles: true, composed: true }));
+  __selectedChanged(selected) {
+    if (selected) {
+      this.__focusTrapController.trapFocus(this.$.focustrap);
+    } else {
+      this.__focusTrapController.releaseFocus();
+    }
+  }
+
+  focus() {
+    if (this.hasAttribute('editable')) {
+      this.$['focus-button'].focus();
+    } else {
+      super.focus();
+    }
   }
 }
 

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

@@ -11,28 +11,48 @@ export const dashboardWidgetAndSectionStyles = css`
     box-sizing: border-box;
   }
 
+  :host([focused]) {
+    border: 1px solid blue;
+  }
+
+  :host([selected]) {
+    border: 4px solid red;
+  }
+
   :host([dragging]) {
-    border: 3px dashed black !important;
+    border: 3px dashed black;
   }
 
   :host([dragging]) * {
     visibility: hidden;
   }
 
   :host(:not([editable])) #drag-handle,
-  :host(:not([editable])) #remove-button {
+  :host(:not([editable])) #remove-button,
+  :host(:not([editable])) #focus-button {
     display: none;
   }
 
+  #focustrap {
+    display: contents;
+  }
+
   header {
     display: flex;
     justify-content: space-between;
     align-items: center;
   }
 
+  #focus-button {
+    position: absolute;
+    inset: 0;
+    opacity: 0;
+  }
+
   #drag-handle {
     font-size: 30px;
     cursor: grab;
+    z-index: 1;
   }
 
   #drag-handle::before {
@@ -42,9 +62,14 @@ export const dashboardWidgetAndSectionStyles = css`
   #remove-button {
     font-size: 30px;
     cursor: pointer;
+    z-index: 1;
   }
 
   #remove-button::before {
     content: '×';
   }
+
+  button:focus {
+    outline: 1px solid blue;
+  }
 `;