@vaadin/dashboard 24.6.0-alpha1

package/src/vaadin-dashboard-widget.js

@@ -0,0 +1,271 @@
+/**
+ * @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 { css, ThemableMixin } from '@vaadin/vaadin-themable-mixin/vaadin-themable-mixin.js';
+import { SYNCHRONIZED_ATTRIBUTES, WRAPPER_LOCAL_NAME } from './vaadin-dashboard-helpers.js';
+import { DashboardItemMixin } from './vaadin-dashboard-item-mixin.js';
+import { getDefaultI18n } from './vaadin-dashboard-item-mixin.js';
+
+/**
+ * A Widget component for use with the Dashboard component
+ *
+ * ```html
+ * <vaadin-dashboard-widget widget-title="Title">
+ *   <span slot="header-content">Header</span>
+ *   <div>Content</div>
+ * </vaadin-dashboard-widget>
+ * ```
+ *
+ * ### Customization
+ *
+ * You can configure the item by using `slot` names.
+ *
+ * Slot name        | Description
+ * -----------------|-------------
+ * `header-content` | A slot for the widget header content.
+ *
+ * #### Example
+ *
+ * ```html
+ * <vaadin-dashboard-widget widget-title="Title">
+ *   <span slot="header-content">Header</span>
+ *   <div>Content</div>
+ * </vaadin-dashboard-widget>
+ * ```
+ *
+ * ### Styling
+ *
+ * The following shadow DOM parts are available for styling:
+ *
+ * Part name                     | Description
+ * ------------------------------|-------------
+ * `header`                      | The header of the widget
+ * `title`                       | The title of the widget
+ * `content`                     | The content of the widget
+ * `move-button`                 | The move button
+ * `remove-button`               | The remove button
+ * `resize-button`               | The resize button
+ * `move-backward-button`        | The move backward button when in move mode
+ * `move-forward-button`         | The move forward button when in move mode
+ * `move-apply-button`           | The apply button when in move mode
+ * `resize-shrink-width-button`  | The shrink width button when in resize mode
+ * `resize-grow-width-button`    | The grow width button when in resize mode
+ * `resize-shrink-height-button` | The shrink height button when in resize mode
+ * `resize-grow-height-button`   | The grow height button when in resize mode
+ * `resize-apply-button`         | The apply button when in resize mode
+ *
+ * The following custom properties are available:
+ *
+ * Custom Property                   | Description
+ * ----------------------------------|-------------
+ * `--vaadin-dashboard-item-colspan` | colspan of the widget
+ * `--vaadin-dashboard-item-rowspan` | rowspan of the widget
+ *
+ * The following state attributes are available for styling:
+ *
+ * Attribute      | Description
+ * ---------------|-------------
+ * `selected`     | Set when the element is selected.
+ * `focused`      | Set when the element is focused.
+ * `move-mode`    | Set when the element is being moved.
+ * `resize-mode`  | Set when the element is being resized.
+ * `resizing`     | Set when the element is being resized.
+ * `dragging`     | Set when the element is being dragged.
+ * `editable`     | Set when the element is editable.
+ * `first-child`  | Set when the element is the first child of the parent.
+ * `last-child`   | Set when the element is the last child of the parent.
+ *
+ * See [Styling Components](https://vaadin.com/docs/latest/styling/styling-components) documentation.
+ *
+ * @customElement
+ * @extends HTMLElement
+ * @mixes ElementMixin
+ * @mixes ThemableMixin
+ * @mixes DashboardItemMixin
+ */
+class DashboardWidget extends DashboardItemMixin(ElementMixin(ThemableMixin(PolylitMixin(LitElement)))) {
+  static get is() {
+    return 'vaadin-dashboard-widget';
+  }
+
+  static get styles() {
+    return [
+      css`
+        :host {
+          display: flex;
+          flex-direction: column;
+          grid-column: var(--_vaadin-dashboard-item-column);
+          grid-row: var(--_vaadin-dashboard-item-row);
+          position: relative;
+        }
+
+        :host([hidden]) {
+          display: none !important;
+        }
+
+        :host(:not([editable])) #resize-handle {
+          display: none;
+        }
+
+        #content {
+          flex: 1;
+          overflow: hidden;
+        }
+
+        #resize-handle {
+          position: absolute;
+          bottom: 0;
+          inset-inline-end: 0;
+          z-index: 1;
+          overflow: hidden;
+        }
+
+        :host([resizing])::after {
+          content: '';
+          z-index: 2;
+          position: absolute;
+          inset-inline-start: 0;
+          top: 0;
+          width: var(--_vaadin-dashboard-widget-resizer-width, 0);
+          height: var(--_vaadin-dashboard-widget-resizer-height, 0);
+          background: rgba(0, 0, 0, 0.1);
+        }
+      `,
+      super.styles,
+    ];
+  }
+
+  static get properties() {
+    return {
+      /**
+       * The object used to localize this component.
+       *
+       * To change the default localization, replace the entire
+       * `i18n` object with a custom one.
+       *
+       * The object has the following structure and default values:
+       * ```
+       * {
+       *   selectWidget: 'Select widget for editing',
+       *   remove: 'Remove',
+       *   resize: 'Resize',
+       *   resizeApply: 'Apply',
+       *   resizeShrinkWidth: 'Shrink width',
+       *   resizeGrowWidth: 'Grow width',
+       *   resizeShrinkHeight: 'Shrink height',
+       *   resizeGrowHeight: 'Grow height',
+       *   move: 'Move',
+       *   moveApply: 'Apply',
+       *   moveForward: 'Move Forward',
+       *   moveBackward: 'Move Backward',
+       * }
+       * ```
+       * @private
+       */
+      __i18n: {
+        type: Object,
+        value: () => {
+          const i18n = getDefaultI18n();
+          delete i18n.selectSection;
+          return i18n;
+        },
+      },
+
+      /**
+       * The title of the widget.
+       *
+       * @attr {string} widget-title
+       * @type {string | null | undefined}
+       */
+      widgetTitle: {
+        type: String,
+        value: '',
+        observer: '__onWidgetTitleChanged',
+      },
+
+      /* @private */
+      __nestedHeadingLevel: {
+        type: Boolean,
+        value: false,
+      },
+    };
+  }
+
+  /** @protected */
+  render() {
+    return html`
+      ${this.__renderFocusButton('selectWidget')} ${this.__renderMoveControls()} ${this.__renderResizeControls()}
+
+      <div id="focustrap">
+        <header part="header">
+          ${this.__renderDragHandle()}
+          ${this.__nestedHeadingLevel
+            ? html`<h3 id="title" part="title" .hidden=${!this.widgetTitle}>${this.widgetTitle}</h3>`
+            : html`<h2 id="title" part="title" .hidden=${!this.widgetTitle}>${this.widgetTitle}</h2>`}
+          <slot name="header-content"></slot>
+          ${this.__renderRemoveButton()}
+        </header>
+
+        ${this.__renderResizeHandle()}
+      </div>
+
+      <div id="content" part="content">
+        <slot></slot>
+      </div>
+    `;
+  }
+
+  /** @protected */
+  connectedCallback() {
+    super.connectedCallback();
+
+    const wrapper = this.closest(WRAPPER_LOCAL_NAME);
+    if (wrapper) {
+      SYNCHRONIZED_ATTRIBUTES.forEach((attr) => {
+        this.toggleAttribute(attr, !!wrapper[attr]);
+      });
+      this.__i18n = wrapper.i18n;
+    }
+
+    const undefinedAncestor = this.closest('*:not(:defined)');
+    if (undefinedAncestor) {
+      customElements.whenDefined(undefinedAncestor.localName).then(() => queueMicrotask(() => this.__updateTitle()));
+    } else {
+      this.__updateTitle();
+    }
+  }
+
+  /** @protected */
+  ready() {
+    super.ready();
+    if (!this.hasAttribute('role')) {
+      this.setAttribute('role', 'article');
+    }
+  }
+
+  /** @private */
+  __onWidgetTitleChanged() {
+    this.__updateTitle();
+  }
+
+  /** @private */
+  __updateTitle() {
+    const titleLevel = getComputedStyle(this).getPropertyValue('--_vaadin-dashboard-title-level');
+    this.__nestedHeadingLevel = titleLevel === '3';
+  }
+}
+
+defineCustomElement(DashboardWidget);
+
+export { DashboardWidget };

package/src/vaadin-dashboard.d.ts

@@ -0,0 +1,290 @@
+/**
+ * @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-widget.js';
+import './vaadin-dashboard-section.js';
+import { ElementMixin } from '@vaadin/component-base/src/element-mixin.js';
+import { ThemableMixin } from '@vaadin/vaadin-themable-mixin';
+import { DashboardLayoutMixin } from './vaadin-dashboard-layout-mixin.js';
+
+export interface DashboardItem {
+  /**
+   * The id of the item.
+   * The identifier should be unique among the dashboard items.
+   * If a unique identifier is not provided, reassigning new item instances
+   * to the dashboard while a widget is focused may cause the focus to be lost.
+   */
+  id?: unknown;
+
+  /**
+   * The column span of the item
+   */
+  colspan?: number;
+
+  /**
+   * The row span of the item
+   */
+  rowspan?: number;
+}
+
+export interface DashboardSectionItem<TItem extends DashboardItem> {
+  /**
+   * The id of the item.
+   * The identifier should be unique among the dashboard items.
+   * If a unique identifier is not provided, reassigning new item instances
+   * to the dashboard while a widget is focused may cause the focus to be lost.
+   */
+  id?: unknown;
+
+  /**
+   * The title of the section
+   */
+  title?: string | null;
+
+  /**
+   * The items of the section
+   */
+  items: TItem[];
+}
+
+export interface DashboardItemModel<TItem> {
+  item: TItem;
+}
+
+export type DashboardRenderer<TItem extends DashboardItem> = (
+  root: HTMLElement,
+  owner: Dashboard<TItem>,
+  model: DashboardItemModel<TItem>,
+) => void;
+
+/**
+ * Fired when an item was moved
+ */
+export type DashboardItemMovedEvent<TItem extends DashboardItem> = CustomEvent<{
+  item: TItem;
+
+  items: Array<TItem | DashboardSectionItem<TItem>>;
+
+  section: DashboardSectionItem<TItem> | undefined;
+}>;
+
+/**
+ * Fired when an item was resized
+ */
+export type DashboardItemResizedEvent<TItem extends DashboardItem> = CustomEvent<{
+  item: TItem;
+
+  items: Array<TItem | DashboardSectionItem<TItem>>;
+}>;
+
+/**
+ * Fired when an item was removed
+ */
+export type DashboardItemRemovedEvent<TItem extends DashboardItem> = CustomEvent<{
+  item: TItem | DashboardSectionItem<TItem>;
+
+  items: Array<TItem | DashboardSectionItem<TItem>>;
+}>;
+
+/**
+ * Fired when an item selected state changed
+ */
+export type DashboardItemSelectedChangedEvent<TItem extends DashboardItem> = CustomEvent<{
+  item: TItem;
+  value: boolean;
+}>;
+
+/**
+ * Fired when an item move mode changed
+ */
+export type DashboardItemMoveModeChangedEvent<TItem extends DashboardItem> = CustomEvent<{
+  item: TItem;
+  value: boolean;
+}>;
+
+/**
+ * Fired when an item resize mode changed
+ */
+export type DashboardItemResizeModeChangedEvent<TItem extends DashboardItem> = CustomEvent<{
+  item: TItem;
+  value: boolean;
+}>;
+
+export interface DashboardCustomEventMap<TItem extends DashboardItem> {
+  'dashboard-item-moved': DashboardItemMovedEvent<TItem>;
+
+  'dashboard-item-resized': DashboardItemResizedEvent<TItem>;
+
+  'dashboard-item-removed': DashboardItemRemovedEvent<TItem>;
+
+  'dashboard-item-selected-changed': DashboardItemSelectedChangedEvent<TItem>;
+
+  'dashboard-item-move-mode-changed': DashboardItemMoveModeChangedEvent<TItem>;
+
+  'dashboard-item-resize-mode-changed': DashboardItemResizeModeChangedEvent<TItem>;
+}
+
+export type DashboardEventMap<TItem extends DashboardItem> = DashboardCustomEventMap<TItem> & HTMLElementEventMap;
+
+export interface DashboardI18n {
+  selectWidget: string;
+  selectSection: string;
+  remove: string;
+  resize: string;
+  resizeApply: string;
+  resizeShrinkWidth: string;
+  resizeGrowWidth: string;
+  resizeShrinkHeight: string;
+  resizeGrowHeight: string;
+  move: string;
+  moveApply: string;
+  moveForward: string;
+  moveBackward: string;
+}
+
+/**
+ * A responsive, grid-based dashboard layout component
+ *
+ * ### Quick Start
+ *
+ * Assign an array to the [`items`](#/elements/vaadin-dashboard#property-items) property.
+ * Set a renderer function to the [`renderer`](#/elements/vaadin-dashboard#property-renderer) property.
+ *
+ * The widgets and the sections will be generated and configured based on the renderer and the items provided.
+ *
+ * ```html
+ * <vaadin-dashboard></vaadin-dashboard>
+ * ```
+ *
+ * ```js
+ * const dashboard = document.querySelector('vaadin-dashboard');
+ *
+ * dashboard.items = [
+ *   { title: 'Widget 1 title', content: 'Text 1', rowspan: 2 },
+ *   { title: 'Widget 2 title', content: 'Text 2', colspan: 2 },
+ *   {
+ *     title: 'Section title',
+ *     items: [{ title: 'Widget in section title', content: 'Text 3' }]
+ *   },
+ *   // ... more items
+ * ];
+ *
+ * dashboard.renderer = (root, _dashboard, { item }) => {
+ *   const widget = root.firstElementChild || document.createElement('vaadin-dashboard-widget');
+ *   if (!root.contains(widget)) {
+ *     root.appendChild(widget);
+ *   }
+ *   widget.widgetTitle = item.title;
+ *   widget.textContent = item.content;
+ * };
+ * ```
+ *
+ * ### Styling
+ *
+ * The following custom properties are available:
+ *
+ * Custom Property                     | Description
+ * ------------------------------------|-------------
+ * `--vaadin-dashboard-col-min-width`  | minimum column width of the dashboard
+ * `--vaadin-dashboard-col-max-width`  | maximum column width of the dashboard
+ * `--vaadin-dashboard-row-min-height` | minimum row height of the dashboard
+ * `--vaadin-dashboard-col-max-count`  | maximum column count of the dashboard
+ * `--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
+ * ---------------|-------------
+ * `editable`     | Set when the dashboard is editable.
+ * `dense-layout` | Set when the dashboard is in dense mode.
+ * `item-selected`| Set when an item is selected.
+ *
+ * See [Styling Components](https://vaadin.com/docs/latest/styling/styling-components) documentation.
+ *
+ * @fires {CustomEvent} dashboard-item-moved - Fired when an item was moved
+ * @fires {CustomEvent} dashboard-item-resized - Fired when an item was resized
+ * @fires {CustomEvent} dashboard-item-removed - Fired when an item was removed
+ * @fires {CustomEvent} dashboard-item-selected-changed - Fired when an item selected state changed
+ * @fires {CustomEvent} dashboard-item-move-mode-changed - Fired when an item move mode changed
+ * @fires {CustomEvent} dashboard-item-resize-mode-changed - Fired when an item resize mode changed
+ */
+declare class Dashboard<TItem extends DashboardItem = DashboardItem> extends DashboardLayoutMixin(
+  ElementMixin(ThemableMixin(HTMLElement)),
+) {
+  /**
+   * An array containing the items of the dashboard
+   */
+  items: Array<TItem | DashboardSectionItem<TItem>>;
+
+  /**
+   * Custom function for rendering a widget for each dashboard item.
+   * Placing something else than a widget in the wrapper is not supported.
+   * Receives three arguments:
+   *
+   * - `root` The container for the widget.
+   * - `dashboard` The reference to the `<vaadin-dashboard>` element.
+   * - `model` The object with the properties related with the rendered
+   *   item, contains:
+   *   - `model.item` The item.
+   */
+  renderer: DashboardRenderer<TItem> | null | undefined;
+
+  /**
+   * Whether the dashboard is editable.
+   */
+  editable: boolean;
+
+  /**
+   * The object used to localize this component.
+   *
+   * To change the default localization, replace the entire
+   * `i18n` object with a custom one.
+   *
+   * The object has the following structure and default values:
+   * ```
+   * {
+   *   selectSection: 'Select section for editing',
+   *   selectWidget: 'Select widget for editing',
+   *   remove: 'Remove',
+   *   resize: 'Resize',
+   *   resizeApply: 'Apply',
+   *   resizeShrinkWidth: 'Shrink width',
+   *   resizeGrowWidth: 'Grow width',
+   *   resizeShrinkHeight: 'Shrink height',
+   *   resizeGrowHeight: 'Grow height',
+   *   move: 'Move',
+   *   moveApply: 'Apply',
+   *   moveForward: 'Move Forward',
+   *   moveBackward: 'Move Backward',
+   * }
+   * ```
+   */
+  i18n: DashboardI18n;
+
+  addEventListener<K extends keyof DashboardEventMap<TItem>>(
+    type: K,
+    listener: (this: Dashboard, ev: DashboardEventMap<TItem>[K]) => void,
+    options?: AddEventListenerOptions | boolean,
+  ): void;
+
+  removeEventListener<K extends keyof DashboardEventMap<TItem>>(
+    type: K,
+    listener: (this: Dashboard, ev: DashboardEventMap<TItem>[K]) => void,
+    options?: EventListenerOptions | boolean,
+  ): void;
+}
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'vaadin-dashboard': Dashboard<DashboardItem>;
+  }
+}
+
+export { Dashboard };