@vaadin/dashboard 24.6.0-alpha1

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

@@ -0,0 +1,76 @@
+/**
+ * @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';
+import { DashboardItemMixin } from './vaadin-dashboard-item-mixin.js';
+
+/**
+ * A section component for use with the Dashboard component
+ *
+ * ```html
+ * <vaadin-dashboard-section section-title="Section Title">
+ *   <vaadin-dashboard-widget widget-title="Widget 1"></vaadin-dashboard-widget>
+ *   <vaadin-dashboard-widget widget-title="Widget 2"></vaadin-dashboard-widget>
+ * </vaadin-dashboard-section>
+ * ```
+ *
+ * #### Example
+ *
+ * ```html
+ * <vaadin-dashboard-section section-title="Section title">
+ *   <vaadin-dashboard-widget widget-title="Widget 1"></vaadin-dashboard-widget>
+ *   <vaadin-dashboard-widget widget-title="Widget 2"></vaadin-dashboard-widget>
+ * </vaadin-dashboard-section>
+ * ```
+ *
+ * ### Styling
+ *
+ * The following shadow DOM parts are available for styling:
+ *
+ * Part name              | Description
+ * -----------------------|-------------
+ * `header`               | The header of the section
+ * `title`                | The title of the section
+ * `move-button`          | The move button
+ * `remove-button`        | The remove 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
+ *
+ * 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.
+ * `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.
+ */
+declare class DashboardSection extends DashboardItemMixin(ElementMixin(ThemableMixin(HTMLElement))) {
+  /**
+   * The title of the section
+   *
+   * @attr {string} section-title
+   */
+  sectionTitle: string | null | undefined;
+}
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'vaadin-dashboard-section': DashboardSection;
+  }
+}
+
+export { DashboardSection };

package/src/vaadin-dashboard-section.js

@@ -0,0 +1,203 @@
+/**
+ * @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 { DashboardItemMixin } from './vaadin-dashboard-item-mixin.js';
+import { getDefaultI18n } from './vaadin-dashboard-item-mixin.js';
+import { hasWidgetWrappers } from './vaadin-dashboard-styles.js';
+
+/**
+ * A section component for use with the Dashboard component
+ *
+ * ```html
+ * <vaadin-dashboard-section section-title="Section Title">
+ *   <vaadin-dashboard-widget widget-title="Widget 1"></vaadin-dashboard-widget>
+ *   <vaadin-dashboard-widget widget-title="Widget 2"></vaadin-dashboard-widget>
+ * </vaadin-dashboard-section>
+ * ```
+ *
+ * #### Example
+ *
+ * ```html
+ * <vaadin-dashboard-section section-title="Section title">
+ *   <vaadin-dashboard-widget widget-title="Widget 1"></vaadin-dashboard-widget>
+ *   <vaadin-dashboard-widget widget-title="Widget 2"></vaadin-dashboard-widget>
+ * </vaadin-dashboard-section>
+ * ```
+ *
+ * ### Styling
+ *
+ * The following shadow DOM parts are available for styling:
+ *
+ * Part name              | Description
+ * -----------------------|-------------
+ * `header`               | The header of the section
+ * `title`                | The title of the section
+ * `move-button`          | The move button
+ * `remove-button`        | The remove 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
+ *
+ * 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.
+ * `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 DashboardSection extends DashboardItemMixin(ElementMixin(ThemableMixin(PolylitMixin(LitElement)))) {
+  static get is() {
+    return 'vaadin-dashboard-section';
+  }
+
+  static get styles() {
+    return [
+      css`
+        :host {
+          display: grid;
+          position: relative;
+          grid-template-columns: subgrid;
+          --_vaadin-dashboard-section-column: 1 / calc(var(--_vaadin-dashboard-effective-col-count) + 1);
+          grid-column: var(--_vaadin-dashboard-section-column) !important;
+          gap: var(--_vaadin-dashboard-spacing, 1rem);
+          /* Dashboard section header height */
+          --_vaadin-dashboard-section-header-height: minmax(0, auto);
+          grid-template-rows: var(--_vaadin-dashboard-section-header-height) repeat(
+              auto-fill,
+              var(--_vaadin-dashboard-row-height)
+            );
+          grid-auto-rows: var(--_vaadin-dashboard-row-height);
+        }
+
+        :host([hidden]) {
+          display: none !important;
+        }
+
+        ::slotted(*) {
+          --_vaadin-dashboard-title-level: 3;
+          --_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);
+          --_vaadin-dashboard-item-row: span var(--vaadin-dashboard-item-rowspan, 1);
+          grid-row: var(--_vaadin-dashboard-item-row);
+        }
+
+        header {
+          grid-column: var(--_vaadin-dashboard-section-column);
+        }
+
+        :host::before {
+          z-index: 2 !important;
+        }
+      `,
+      hasWidgetWrappers,
+      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:
+       * ```
+       * {
+       *   selectSection: 'Select section for editing',
+       *   remove: 'Remove',
+       *   move: 'Move',
+       *   moveApply: 'Apply',
+       *   moveForward: 'Move Forward',
+       *   moveBackward: 'Move Backward',
+       * }
+       * ```
+       * @private
+       */
+      __i18n: {
+        type: Object,
+        value: () => {
+          const i18n = getDefaultI18n();
+          return {
+            selectSection: i18n.selectSection,
+            remove: i18n.remove,
+            move: i18n.move,
+            moveApply: i18n.moveApply,
+            moveForward: i18n.moveForward,
+            moveBackward: i18n.moveBackward,
+          };
+        },
+      },
+
+      /**
+       * The title of the section
+       *
+       * @attr {string} section-title
+       * @type {string | null | undefined}
+       */
+      sectionTitle: {
+        type: String,
+        value: '',
+      },
+    };
+  }
+
+  /** @protected */
+  render() {
+    return html`
+      ${this.__renderFocusButton('selectSection')} ${this.__renderMoveControls()}
+
+      <div id="focustrap">
+        <header part="header">
+          ${this.__renderDragHandle()}
+          <h2 id="title" part="title">${this.sectionTitle}</h2>
+          ${this.__renderRemoveButton()}
+        </header>
+      </div>
+
+      <slot></slot>
+    `;
+  }
+
+  /** @protected */
+  ready() {
+    super.ready();
+    if (!this.hasAttribute('role')) {
+      this.setAttribute('role', 'section');
+    }
+  }
+}
+
+defineCustomElement(DashboardSection);
+
+export { DashboardSection };

package/src/vaadin-dashboard-styles.js

@@ -0,0 +1,143 @@
+/**
+ * @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 { css } from '@vaadin/vaadin-themable-mixin/vaadin-themable-mixin.js';
+
+export const hasWidgetWrappers = css`
+  ::slotted(vaadin-dashboard-widget-wrapper) {
+    display: contents;
+  }
+`;
+
+export const dashboardWidgetAndSectionStyles = css`
+  :host {
+    box-sizing: border-box;
+    /* Calculates the offset by which mode buttons that by default overflow the widget edges
+    should be shifted inwards based on a custom --vaadin-dashboard-spacing value */
+    --_mode-button-spacing-offset: calc(
+      max(0px, var(--_vaadin-dashboard-default-spacing) - var(--_vaadin-dashboard-spacing))
+    );
+  }
+
+  :host([dragging]) * {
+    visibility: hidden;
+  }
+
+  :host(:not([editable])) #drag-handle,
+  :host(:not([editable])) #remove-button,
+  :host(:not([editable])) #focus-button,
+  :host(:not([editable])) #focus-button-wrapper {
+    display: none;
+  }
+
+  #focustrap {
+    display: contents;
+  }
+
+  header {
+    display: flex;
+    overflow: hidden;
+  }
+
+  vaadin-dashboard-button {
+    z-index: 1;
+  }
+
+  #focus-button-wrapper,
+  #focus-button {
+    position: absolute;
+    inset: 0;
+    opacity: 0;
+  }
+
+  #focus-button {
+    pointer-events: none;
+    padding: 0;
+    border: none;
+  }
+
+  .mode-controls {
+    position: absolute;
+    inset: 0;
+    z-index: 2;
+  }
+
+  .mode-controls[hidden] {
+    display: none;
+  }
+
+  /* Move-mode buttons */
+  #move-backward,
+  #move-forward,
+  #move-apply {
+    position: absolute;
+    top: 50%;
+  }
+
+  #move-backward {
+    inset-inline-start: 0;
+    transform: translateY(-50%);
+  }
+
+  #move-forward {
+    inset-inline-end: 0;
+    transform: translateY(-50%);
+  }
+
+  #move-apply {
+    left: 50%;
+    transform: translate(-50%, -50%);
+  }
+
+  :host([first-child]) #move-backward,
+  :host([last-child]) #move-forward {
+    display: none;
+  }
+
+  /* Resize-mode buttons */
+  #resize-shrink-width,
+  #resize-shrink-height,
+  #resize-grow-width,
+  #resize-grow-height,
+  #resize-apply {
+    position: absolute;
+  }
+
+  #resize-shrink-width {
+    inset-inline-end: calc(0px + var(--_mode-button-spacing-offset));
+    top: 50%;
+    transform: translateY(-50%);
+  }
+
+  #resize-grow-width {
+    inset-inline-start: calc(100% - var(--_mode-button-spacing-offset));
+    top: 50%;
+    transform: translateY(-50%);
+  }
+
+  #resize-shrink-height {
+    bottom: calc(0px + var(--_mode-button-spacing-offset));
+    left: 50%;
+    transform: translateX(-50%);
+  }
+
+  #resize-grow-height {
+    top: calc(100% - var(--_mode-button-spacing-offset));
+    left: 50%;
+    transform: translateX(-50%);
+  }
+
+  #resize-apply {
+    left: 50%;
+    top: 50%;
+
+    transform: translate(-50%, -50%);
+  }
+`;

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

@@ -0,0 +1,101 @@
+/**
+ * @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';
+import { DashboardItemMixin } 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.
+ */
+declare class DashboardWidget extends DashboardItemMixin(ElementMixin(ThemableMixin(HTMLElement))) {
+  /**
+   * The title of the widget
+   *
+   * @attr {string} widget-title
+   */
+  widgetTitle: string | null | undefined;
+}
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'vaadin-dashboard-widget': DashboardWidget;
+  }
+}
+
+export { DashboardWidget };