@vaadin/dashboard 24.6.0-alpha1

package/src/vaadin-dashboard-item-mixin.js

@@ -0,0 +1,355 @@
+/**
+ * @license
+ * Copyright (c) 2000 - 2024 Vaadin Ltd.
+ *
+ * This program is available under Vaadin Commercial License and Service Terms.
+ *
+ *
+ * See https://vaadin.com/commercial-license-and-service-terms for the full
+ * license.
+ */
+import './vaadin-dashboard-button.js';
+import { html } from 'lit';
+import { FocusTrapController } from '@vaadin/a11y-base/src/focus-trap-controller.js';
+import { ResizeMixin } from '@vaadin/component-base/src/resize-mixin.js';
+import { KeyboardController } from './keyboard-controller.js';
+import { fireMove, fireRemove, fireResize } from './vaadin-dashboard-helpers.js';
+import { dashboardWidgetAndSectionStyles } from './vaadin-dashboard-styles.js';
+
+const DEFAULT_I18N = {
+  selectWidget: 'Select widget for editing',
+  selectSection: 'Select section for editing',
+  remove: 'Remove',
+  move: 'Move',
+  moveApply: 'Apply',
+  moveForward: 'Move Forward',
+  moveBackward: 'Move Backward',
+  resize: 'Resize',
+  resizeApply: 'Apply',
+  resizeShrinkWidth: 'Shrink width',
+  resizeGrowWidth: 'Grow width',
+  resizeShrinkHeight: 'Shrink height',
+  resizeGrowHeight: 'Grow height',
+};
+
+/**
+ * Returns a new object with the default i18n values
+ */
+export function getDefaultI18n() {
+  return { ...DEFAULT_I18N };
+}
+
+/**
+ * Shared functionality between widgets and sections
+ *
+ * @polymerMixin
+ * @mixes ResizeMixin
+ */
+export const DashboardItemMixin = (superClass) =>
+  class DashboardItemMixinClass extends ResizeMixin(superClass) {
+    static get styles() {
+      return dashboardWidgetAndSectionStyles;
+    }
+
+    static get properties() {
+      return {
+        /** @protected */
+        __i18n: {
+          type: Object,
+        },
+
+        /** @private */
+        __selected: {
+          type: Boolean,
+          reflectToAttribute: true,
+          attribute: 'selected',
+          observer: '__selectedChanged',
+        },
+
+        /** @private */
+        __focused: {
+          type: Boolean,
+          reflectToAttribute: true,
+          attribute: 'focused',
+        },
+
+        /** @private */
+        __moveMode: {
+          type: Boolean,
+          reflectToAttribute: true,
+          attribute: 'move-mode',
+          observer: '__moveModeChanged',
+        },
+
+        /** @private */
+        __resizeMode: {
+          type: Boolean,
+          reflectToAttribute: true,
+          attribute: 'resize-mode',
+          observer: '__resizeModeChanged',
+        },
+      };
+    }
+
+    /** @private */
+    __renderDragHandle() {
+      return html`<vaadin-dashboard-button
+        id="drag-handle"
+        draggable="true"
+        class="drag-handle"
+        part="move-button"
+        theme="icon tertiary"
+        aria-label="${this.__i18n.move}"
+        title="${this.__i18n.move}"
+        tabindex="${this.__selected ? 0 : -1}"
+        @click="${() => this.__enterMoveMode()}"
+      >
+        <div class="icon"></div>
+      </vaadin-dashboard-button>`;
+    }
+
+    /** @private */
+    __renderRemoveButton() {
+      return html`<vaadin-dashboard-button
+        aria-label="${this.__i18n.remove}"
+        title="${this.__i18n.remove}"
+        id="remove-button"
+        part="remove-button"
+        theme="icon tertiary"
+        tabindex="${this.__selected ? 0 : -1}"
+        @click="${() => fireRemove(this)}"
+      >
+        <div class="icon"></div>
+      </vaadin-dashboard-button>`;
+    }
+
+    /** @private */
+    __renderFocusButton(i18nSelectTitleForEditingProperty) {
+      // To make the button draggable on Firefox, using a workaround from https://stackoverflow.com/a/55019027/3409629
+      return html`<label draggable="true" class="drag-handle" id="focus-button-wrapper">
+        <button
+          id="focus-button"
+          aria-label=${this.__i18n[i18nSelectTitleForEditingProperty]}
+          aria-describedby="title"
+          aria-pressed="${!!this.__selected}"
+          @click="${() => {
+            this.__selected = true;
+          }}"
+        ></button>
+      </label>`;
+    }
+
+    /** @private */
+    __renderResizeHandle() {
+      return html`<vaadin-dashboard-button
+        aria-label="${this.__i18n.resize}"
+        title="${this.__i18n.resize}"
+        id="resize-handle"
+        part="resize-button"
+        class="resize-handle"
+        theme="icon tertiary"
+        tabindex="${this.__selected ? 0 : -1}"
+        @click="${() => this.__enterResizeMode()}"
+      >
+        <div class="icon"></div>
+      </vaadin-dashboard-button>`;
+    }
+
+    /** @private */
+    __renderMoveControls() {
+      return html`<div
+        id="move-controls"
+        class="mode-controls"
+        .hidden="${!this.__moveMode}"
+        @pointerdown="${(e) => e.preventDefault()}"
+      >
+        <vaadin-dashboard-button
+          theme="primary icon"
+          aria-label="${this.__i18n.moveBackward}"
+          title="${this.__i18n.moveBackward}"
+          @click="${() => fireMove(this, -1)}"
+          id="move-backward"
+          part="move-backward-button"
+        >
+          <div class="icon"></div>
+        </vaadin-dashboard-button>
+        <vaadin-dashboard-button
+          theme="primary icon large"
+          aria-label="${this.__i18n.moveApply}"
+          title="${this.__i18n.moveApply}"
+          @click="${() => this.__exitMode(true)}"
+          id="move-apply"
+          part="move-apply-button"
+        >
+          <div class="icon"></div>
+        </vaadin-dashboard-button>
+        <vaadin-dashboard-button
+          theme="primary icon"
+          aria-label="${this.__i18n.moveForward}"
+          title="${this.__i18n.moveForward}"
+          @click="${() => fireMove(this, 1)}"
+          id="move-forward"
+          part="move-forward-button"
+        >
+          <div class="icon"></div>
+        </vaadin-dashboard-button>
+      </div>`;
+    }
+
+    /** @private */
+    __renderResizeControls() {
+      const hasMinRowHeight = getComputedStyle(this).getPropertyValue('--vaadin-dashboard-row-min-height');
+
+      return html`<div
+        id="resize-controls"
+        class="mode-controls"
+        .hidden="${!this.__resizeMode}"
+        @pointerdown="${(e) => e.preventDefault()}"
+      >
+        <vaadin-dashboard-button
+          theme="primary icon large"
+          aria-label="${this.__i18n.resizeApply}"
+          title="${this.__i18n.resizeApply}"
+          @click="${() => this.__exitMode(true)}"
+          id="resize-apply"
+          part="resize-apply-button"
+        >
+          <div class="icon"></div>
+        </vaadin-dashboard-button>
+        <vaadin-dashboard-button
+          theme="primary icon"
+          aria-label="${this.__i18n.resizeShrinkWidth}"
+          title="${this.__i18n.resizeShrinkWidth}"
+          @click="${() => fireResize(this, -1, 0)}"
+          id="resize-shrink-width"
+          part="resize-shrink-width-button"
+        >
+          <div class="icon"></div>
+        </vaadin-dashboard-button>
+        <vaadin-dashboard-button
+          theme="primary icon"
+          aria-label="${this.__i18n.resizeGrowWidth}"
+          title="${this.__i18n.resizeGrowWidth}"
+          @click="${() => fireResize(this, 1, 0)}"
+          id="resize-grow-width"
+          part="resize-grow-width-button"
+        >
+          <div class="icon"></div>
+        </vaadin-dashboard-button>
+        <vaadin-dashboard-button
+          theme="primary icon"
+          aria-label="${this.__i18n.resizeShrinkHeight}"
+          title="${this.__i18n.resizeShrinkHeight}"
+          @click="${() => fireResize(this, 0, -1)}"
+          id="resize-shrink-height"
+          part="resize-shrink-height-button"
+          .hidden="${!hasMinRowHeight}"
+        >
+          <div class="icon"></div>
+        </vaadin-dashboard-button>
+        <vaadin-dashboard-button
+          theme="primary icon"
+          aria-label="${this.__i18n.resizeGrowHeight}"
+          title="${this.__i18n.resizeGrowHeight}"
+          @click="${() => fireResize(this, 0, 1)}"
+          id="resize-grow-height"
+          part="resize-grow-height-button"
+          .hidden="${!hasMinRowHeight}"
+        >
+          <div class="icon"></div>
+        </vaadin-dashboard-button>
+      </div>`;
+    }
+
+    constructor() {
+      super();
+      this.__keyboardController = new KeyboardController(this);
+      this.__focusTrapController = new FocusTrapController(this);
+    }
+
+    /** @protected */
+    ready() {
+      super.ready();
+      this.addController(this.__keyboardController);
+      this.addController(this.__focusTrapController);
+    }
+
+    /** @private */
+    __selectedChanged(selected, oldSelected) {
+      if (!!selected === !!oldSelected) {
+        return;
+      }
+      this.dispatchEvent(new CustomEvent('item-selected-changed', { bubbles: true, detail: { value: selected } }));
+      if (selected) {
+        this.__focusTrapController.trapFocus(this.$.focustrap);
+      } else {
+        this.__focusTrapController.releaseFocus();
+      }
+    }
+
+    focus() {
+      if (this.hasAttribute('editable')) {
+        this.$['focus-button'].focus();
+      } else {
+        super.focus();
+      }
+    }
+
+    /** @private */
+    __exitMode(focus) {
+      if (this.__moveMode) {
+        this.__moveMode = false;
+        if (focus) {
+          this.$['drag-handle'].focus();
+          this.__focusTrapController.trapFocus(this.$.focustrap);
+        }
+      } else if (this.__resizeMode) {
+        this.__resizeMode = false;
+        if (focus) {
+          this.$['resize-handle'].focus();
+          this.__focusTrapController.trapFocus(this.$.focustrap);
+        }
+      }
+    }
+
+    /** @private */
+    __focusApply() {
+      if (this.__moveMode) {
+        this.$['move-apply'].focus();
+      }
+    }
+
+    /** @private */
+    __enterMoveMode() {
+      this.__selected = true;
+      this.__moveMode = true;
+      requestAnimationFrame(() => {
+        this.__focusTrapController.trapFocus(this.$['move-controls']);
+      });
+    }
+
+    /** @private */
+    __enterResizeMode() {
+      this.__selected = true;
+      this.__resizeMode = true;
+      requestAnimationFrame(() => {
+        this.__focusTrapController.trapFocus(this.$['resize-controls']);
+      });
+    }
+
+    /** @private */
+    __moveModeChanged(moveMode, oldMoveMode) {
+      if (!!moveMode === !!oldMoveMode) {
+        return;
+      }
+      this.dispatchEvent(new CustomEvent('item-move-mode-changed', { bubbles: true, detail: { value: moveMode } }));
+    }
+
+    /** @private */
+    __resizeModeChanged(resizeMode, oldResizeMode) {
+      if (!!resizeMode === !!oldResizeMode) {
+        return;
+      }
+      this.dispatchEvent(new CustomEvent('item-resize-mode-changed', { bubbles: true, detail: { value: resizeMode } }));
+    }
+  };

package/src/vaadin-dashboard-layout-mixin.d.ts

@@ -0,0 +1,28 @@
+/**
+ * @license
+ * Copyright (c) 2000 - 2024 Vaadin Ltd.
+ *
+ * This program is available under Vaadin Commercial License and Service Terms.
+ *
+ *
+ * See https://vaadin.com/commercial-license-and-service-terms for the full
+ * license.
+ */
+import type { Constructor } from '@open-wc/dedupe-mixin';
+import type { ResizeMixinClass } from '@vaadin/component-base/src/resize-mixin.js';
+
+/**
+ * A mixin to enable the dashboard layout functionality.
+ */
+export declare function DashboardLayoutMixin<T extends Constructor<HTMLElement>>(
+  base: T,
+): Constructor<DashboardLayoutMixinClass> & Constructor<ResizeMixinClass> & T;
+
+export declare class DashboardLayoutMixinClass {
+  /**
+   * Whether the dashboard layout is dense.
+   *
+   * @attr {boolean} dense-layout
+   */
+  denseLayout: boolean;
+}

package/src/vaadin-dashboard-layout-mixin.js

@@ -0,0 +1,148 @@
+/**
+ * @license
+ * Copyright (c) 2000 - 2024 Vaadin Ltd.
+ *
+ * This program is available under Vaadin Commercial License and Service Terms.
+ *
+ *
+ * See https://vaadin.com/commercial-license-and-service-terms for the full
+ * license.
+ */
+import { ResizeMixin } from '@vaadin/component-base/src/resize-mixin.js';
+import { css } from '@vaadin/vaadin-themable-mixin/vaadin-themable-mixin.js';
+
+/**
+ * A mixin to enable the dashboard layout functionality
+ *
+ * @polymerMixin
+ * @mixes ResizeMixin
+ */
+export const DashboardLayoutMixin = (superClass) =>
+  class DashboardLayoutMixinClass extends ResizeMixin(superClass) {
+    static get styles() {
+      return css`
+        :host {
+          display: block;
+          overflow: hidden;
+        }
+
+        :host([hidden]) {
+          display: none !important;
+        }
+
+        :host([dense-layout]) #grid {
+          grid-auto-flow: dense;
+        }
+
+        #grid {
+          box-sizing: border-box;
+          --_vaadin-dashboard-default-spacing: 1rem;
+          --_vaadin-dashboard-spacing: max(
+            0px,
+            var(--vaadin-dashboard-spacing, var(--_vaadin-dashboard-default-spacing))
+          );
+          padding: var(--_vaadin-dashboard-spacing);
+
+          /* Default min and max column widths */
+          --_vaadin-dashboard-default-col-min-width: 25rem;
+          --_vaadin-dashboard-default-col-max-width: 1fr;
+
+          /* Effective min and max column widths */
+          --_vaadin-dashboard-col-min-width: var(
+            --vaadin-dashboard-col-min-width,
+            var(--_vaadin-dashboard-default-col-min-width)
+          );
+          --_vaadin-dashboard-col-max-width: var(
+            --vaadin-dashboard-col-max-width,
+            var(--_vaadin-dashboard-default-col-max-width)
+          );
+
+          /* Effective max column count */
+          --_vaadin-dashboard-col-max-count: var(--vaadin-dashboard-col-max-count, var(--_vaadin-dashboard-col-count));
+
+          /* Effective column count */
+          --_vaadin-dashboard-effective-col-count: min(
+            var(--_vaadin-dashboard-col-count),
+            var(--_vaadin-dashboard-col-max-count)
+          );
+
+          /* Effective row height */
+          --_vaadin-dashboard-row-height: minmax(var(--vaadin-dashboard-row-min-height, auto), auto);
+
+          display: grid;
+          overflow: auto;
+          height: 100%;
+
+          grid-template-columns: repeat(
+            var(--_vaadin-dashboard-effective-col-count, auto-fill),
+            minmax(var(--_vaadin-dashboard-col-min-width), var(--_vaadin-dashboard-col-max-width))
+          );
+
+          grid-auto-rows: var(--_vaadin-dashboard-row-height);
+
+          gap: var(--_vaadin-dashboard-spacing);
+        }
+
+        ::slotted(*) {
+          /* The grid-column value applied to children */
+          --_vaadin-dashboard-item-column: span
+            min(
+              var(--vaadin-dashboard-item-colspan, 1),
+              var(--_vaadin-dashboard-effective-col-count, var(--_vaadin-dashboard-col-count))
+            );
+
+          grid-column: var(--_vaadin-dashboard-item-column);
+
+          /* The grid-row value applied to children */
+          --_vaadin-dashboard-item-row: span var(--vaadin-dashboard-item-rowspan, 1);
+          grid-row: var(--_vaadin-dashboard-item-row);
+        }
+      `;
+    }
+
+    static get properties() {
+      return {
+        /**
+         * Whether the dashboard layout is dense.
+         *
+         * @attr {boolean} dense-layout
+         * @type {boolean}
+         */
+        denseLayout: {
+          type: Boolean,
+          value: false,
+          reflectToAttribute: true,
+        },
+      };
+    }
+
+    /** @protected */
+    ready() {
+      super.ready();
+      // Avoid flickering on the initial render
+      this._onResize();
+    }
+
+    /**
+     * @protected
+     * @override
+     */
+    _onResize() {
+      // Update the grid width to match the host width. This is done programmatically to avoid
+      // flickering due to the asynchronous nature of ResizeObserver.
+      this.$.grid.style.width = `${this.offsetWidth}px`;
+      this.__updateColumnCount();
+    }
+
+    /**
+     * @private
+     */
+    __updateColumnCount() {
+      // Clear the previously computed column count
+      this.$.grid.style.removeProperty('--_vaadin-dashboard-col-count');
+      // Get the column count (with no colspans etc in effect)...
+      const columnCount = getComputedStyle(this.$.grid).gridTemplateColumns.split(' ').length;
+      // ...and set it as the new value
+      this.$.grid.style.setProperty('--_vaadin-dashboard-col-count', columnCount);
+    }
+  };

package/src/vaadin-dashboard-layout.d.ts

@@ -0,0 +1,56 @@
+/**
+ * @license
+ * Copyright (c) 2000 - 2024 Vaadin Ltd.
+ *
+ * This program is available under Vaadin Commercial License and Service Terms.
+ *
+ *
+ * See https://vaadin.com/commercial-license-and-service-terms for the full
+ * license.
+ */
+import { ElementMixin } from '@vaadin/component-base/src/element-mixin.js';
+import { ThemableMixin } from '@vaadin/vaadin-themable-mixin/vaadin-themable-mixin.js';
+import { DashboardLayoutMixin } from './vaadin-dashboard-layout-mixin.js';
+
+/**
+ * A responsive, grid-based dashboard layout component
+ *
+ * ```html
+ * <vaadin-dashboard-layout>
+ *   <vaadin-dashboard-widget widget-title="Widget 1"></vaadin-dashboard-widget>
+ *   <vaadin-dashboard-widget widget-title="Widget 2"></vaadin-dashboard-widget>
+ *   <vaadin-dashboard-section section-title="Section">
+ *     <vaadin-dashboard-widget widget-title="Widget in Section"></vaadin-dashboard-widget>
+ *   </vaadin-dashboard-section>
+ * </vaadin-dashboard-layout>
+ * ```
+ *
+ * ### Styling
+ *
+ * The following custom properties are available:
+ *
+ * Custom Property                     | Description
+ * ------------------------------------|-------------
+ * `--vaadin-dashboard-col-min-width`  | minimum column width of the layout
+ * `--vaadin-dashboard-col-max-width`  | maximum column width of the layout
+ * `--vaadin-dashboard-row-min-height` | minimum row height of the layout
+ * `--vaadin-dashboard-col-max-count`  | maximum column count of the layout
+ * `--vaadin-dashboard-spacing`        | spacing between child elements and space around its outer edges. Must be in length units (0 is not allowed, 0px is)
+ *
+ * The following state attributes are available for styling:
+ *
+ * Attribute      | Description
+ * ---------------|-------------
+ * `dense-layout` | Set when the dashboard is in dense mode.
+ *
+ * See [Styling Components](https://vaadin.com/docs/latest/styling/styling-components) documentation.
+ */
+declare class DashboardLayout extends DashboardLayoutMixin(ElementMixin(ThemableMixin(HTMLElement))) {}
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'vaadin-dashboard-layout': DashboardLayout;
+  }
+}
+
+export { DashboardLayout };

package/src/vaadin-dashboard-layout.js

@@ -0,0 +1,70 @@
+/**
+ * @license
+ * Copyright (c) 2000 - 2024 Vaadin Ltd.
+ *
+ * This program is available under Vaadin Commercial License and Service Terms.
+ *
+ *
+ * See https://vaadin.com/commercial-license-and-service-terms for the full
+ * license.
+ */
+import { html, LitElement } from 'lit';
+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 { ThemableMixin } from '@vaadin/vaadin-themable-mixin/vaadin-themable-mixin.js';
+import { DashboardLayoutMixin } from './vaadin-dashboard-layout-mixin.js';
+
+/**
+ * A responsive, grid-based dashboard layout component
+ *
+ * ```html
+ * <vaadin-dashboard-layout>
+ *   <vaadin-dashboard-widget widget-title="Widget 1"></vaadin-dashboard-widget>
+ *   <vaadin-dashboard-widget widget-title="Widget 2"></vaadin-dashboard-widget>
+ *   <vaadin-dashboard-section section-title="Section">
+ *     <vaadin-dashboard-widget widget-title="Widget in Section"></vaadin-dashboard-widget>
+ *   </vaadin-dashboard-section>
+ * </vaadin-dashboard-layout>
+ * ```
+ *
+ * ### Styling
+ *
+ * The following custom properties are available:
+ *
+ * Custom Property                     | Description
+ * ------------------------------------|-------------
+ * `--vaadin-dashboard-col-min-width`  | minimum column width of the layout
+ * `--vaadin-dashboard-col-max-width`  | maximum column width of the layout
+ * `--vaadin-dashboard-row-min-height` | minimum row height of the layout
+ * `--vaadin-dashboard-col-max-count`  | maximum column count of the layout
+ * `--vaadin-dashboard-spacing`        | spacing between child elements and space around its outer edges. Must be in length units (0 is not allowed, 0px is)
+ *
+ * The following state attributes are available for styling:
+ *
+ * Attribute      | Description
+ * ---------------|-------------
+ * `dense-layout` | Set when the dashboard is in dense mode.
+ *
+ * See [Styling Components](https://vaadin.com/docs/latest/styling/styling-components) documentation.
+ *
+ * @customElement
+ * @extends HTMLElement
+ * @mixes DashboardLayoutMixin
+ * @mixes ElementMixin
+ * @mixes ThemableMixin
+ */
+class DashboardLayout extends DashboardLayoutMixin(ElementMixin(ThemableMixin(PolylitMixin(LitElement)))) {
+  static get is() {
+    return 'vaadin-dashboard-layout';
+  }
+
+  /** @protected */
+  render() {
+    return html`<div id="grid"><slot></slot></div>`;
+  }
+}
+
+defineCustomElement(DashboardLayout);
+
+export { DashboardLayout };