From f992988f795002c2814f868b6ffc988dea5d396c Mon Sep 17 00:00:00 2001
From: Ugur Saglam <106508695+ugur-vaadin@users.noreply.github.com>
Date: Tue, 1 Oct 2024 15:32:37 +0300
Subject: [PATCH] docs: add dashboard jsdocs (#7891)

* docs: add dashboard jsdocs

* docs: add attr annotations

* docs: remove defaults from custom properties

* Update packages/dashboard/src/vaadin-dashboard-layout.d.ts

Co-authored-by: Serhii Kulykov <iamkulykov@gmail.com>

* docs: add backticks to property names

* docs: replace header and inner html with text content

* docs: rename gap property to spacing

* chore: fix typo

* docs: rename header to header content

---------

Co-authored-by: Serhii Kulykov <iamkulykov@gmail.com>
---
 .../src/vaadin-dashboard-layout-mixin.d.ts    |  2 +
 .../src/vaadin-dashboard-layout-mixin.js      |  2 +
 .../src/vaadin-dashboard-layout.d.ts          | 30 +++++++++
 .../dashboard/src/vaadin-dashboard-layout.js  | 30 +++++++++
 .../src/vaadin-dashboard-section.d.ts         | 41 +++++++++++-
 .../dashboard/src/vaadin-dashboard-section.js | 42 ++++++++++++-
 .../src/vaadin-dashboard-widget.d.ts          | 48 ++++++++++++++
 .../dashboard/src/vaadin-dashboard-widget.js  | 49 +++++++++++++++
 packages/dashboard/src/vaadin-dashboard.d.ts  | 62 +++++++++++++++++++
 packages/dashboard/src/vaadin-dashboard.js    | 55 ++++++++++++++++
 10 files changed, 359 insertions(+), 2 deletions(-)

diff --git a/packages/dashboard/src/vaadin-dashboard-layout-mixin.d.ts b/packages/dashboard/src/vaadin-dashboard-layout-mixin.d.ts
index 167f257522..742a9cbbdb 100644
--- a/packages/dashboard/src/vaadin-dashboard-layout-mixin.d.ts
+++ b/packages/dashboard/src/vaadin-dashboard-layout-mixin.d.ts
@@ -21,6 +21,8 @@ export declare function DashboardLayoutMixin<T extends Constructor<HTMLElement>>
 export declare class DashboardLayoutMixinClass {
   /**
    * Whether the dashboard layout is dense.
+   *
+   * @attr {boolean} dense-layout
    */
   denseLayout: boolean;
 }
diff --git a/packages/dashboard/src/vaadin-dashboard-layout-mixin.js b/packages/dashboard/src/vaadin-dashboard-layout-mixin.js
index 88caa18f2c..94062cdc72 100644
--- a/packages/dashboard/src/vaadin-dashboard-layout-mixin.js
+++ b/packages/dashboard/src/vaadin-dashboard-layout-mixin.js
@@ -104,6 +104,8 @@ export const DashboardLayoutMixin = (superClass) =>
       return {
         /**
          * Whether the dashboard layout is dense.
+         *
+         * @attr {boolean} dense-layout
          * @type {boolean}
          */
         denseLayout: {
diff --git a/packages/dashboard/src/vaadin-dashboard-layout.d.ts b/packages/dashboard/src/vaadin-dashboard-layout.d.ts
index 090d8f743b..1a2223e521 100644
--- a/packages/dashboard/src/vaadin-dashboard-layout.d.ts
+++ b/packages/dashboard/src/vaadin-dashboard-layout.d.ts
@@ -14,6 +14,36 @@ 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` | maximum column count of the layout
+ * `--vaadin-dashboard-spacing`        | spacing between the cells of the layout
+ * `--vaadin-dashboard-col-max-count`  | maximum column count of the layout
+ *
+ * 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))) {}
 
diff --git a/packages/dashboard/src/vaadin-dashboard-layout.js b/packages/dashboard/src/vaadin-dashboard-layout.js
index 730a42dcff..eb51ecc165 100644
--- a/packages/dashboard/src/vaadin-dashboard-layout.js
+++ b/packages/dashboard/src/vaadin-dashboard-layout.js
@@ -18,6 +18,36 @@ 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` | maximum column count of the layout
+ * `--vaadin-dashboard-spacing`        | spacing between the cells of the layout
+ * `--vaadin-dashboard-col-max-count`  | maximum column count of the layout
+ *
+ * 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
diff --git a/packages/dashboard/src/vaadin-dashboard-section.d.ts b/packages/dashboard/src/vaadin-dashboard-section.d.ts
index 2836c40ab9..638ce46811 100644
--- a/packages/dashboard/src/vaadin-dashboard-section.d.ts
+++ b/packages/dashboard/src/vaadin-dashboard-section.d.ts
@@ -13,11 +13,50 @@ import { ElementMixin } from '@vaadin/component-base/src/element-mixin.js';
 import { DashboardItemMixin } from './vaadin-dashboard-item-mixin.js';
 
 /**
- * A Section component for use with the Dashboard component
+ * 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>
+ * ```
+ *
+ * ### Customization
+ *
+ * You can configure the item by using `slot` names.
+ *
+ * Slot name | Description
+ * ----------|-------------
+ * `title`   | A slot for the section title. Overrides the `sectionTitle` property.
+ *
+ * #### Example
+ *
+ * ```html
+ * <vaadin-dashboard-section>
+ *   <span slot="title">Section Title</span>
+ *   <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 state attributes are available for styling:
+ *
+ * Attribute      | Description
+ * ---------------|-------------
+ * `selected`     | Set when the item is selected.
+ * `focused`      | Set when the item is focused.
+ * `move-mode`    | Set when the item is being moved.
+ *
+ * See [Styling Components](https://vaadin.com/docs/latest/styling/styling-components) documentation.
  */
 declare class DashboardSection extends DashboardItemMixin(ControllerMixin(ElementMixin(HTMLElement))) {
   /**
    * The title of the section
+   *
+   * @attr {string} section-title
    */
   sectionTitle: string | null | undefined;
 }
diff --git a/packages/dashboard/src/vaadin-dashboard-section.js b/packages/dashboard/src/vaadin-dashboard-section.js
index e9b85421f3..502647bc14 100644
--- a/packages/dashboard/src/vaadin-dashboard-section.js
+++ b/packages/dashboard/src/vaadin-dashboard-section.js
@@ -22,6 +22,43 @@ 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>
+ * ```
+ *
+ * ### Customization
+ *
+ * You can configure the item by using `slot` names.
+ *
+ * Slot name | Description
+ * ----------|-------------
+ * `title`   | A slot for the section title. Overrides the `sectionTitle` property.
+ *
+ * #### Example
+ *
+ * ```html
+ * <vaadin-dashboard-section>
+ *   <span slot="title">Section Title</span>
+ *   <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 state attributes are available for styling:
+ *
+ * Attribute      | Description
+ * ---------------|-------------
+ * `selected`     | Set when the item is selected.
+ * `focused`      | Set when the item is focused.
+ * `move-mode`    | Set when the item is being moved.
+ *
+ * See [Styling Components](https://vaadin.com/docs/latest/styling/styling-components) documentation.
+ *
  * @customElement
  * @extends HTMLElement
  * @mixes ElementMixin
@@ -43,7 +80,7 @@ class DashboardSection extends DashboardItemMixin(ControllerMixin(ElementMixin(P
           --_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);
-          /* Dashbaord section header height */
+          /* Dashboard section header height */
           --_vaadin-dashboard-section-header-height: minmax(0, auto);
           grid-template-rows: var(--_vaadin-dashboard-section-header-height) repeat(
               auto-fill,
@@ -124,6 +161,9 @@ class DashboardSection extends DashboardItemMixin(ControllerMixin(ElementMixin(P
 
       /**
        * The title of the section
+       *
+       * @attr {string} section-title
+       * @type {string | null | undefined}
        */
       sectionTitle: {
         type: String,
diff --git a/packages/dashboard/src/vaadin-dashboard-widget.d.ts b/packages/dashboard/src/vaadin-dashboard-widget.d.ts
index fe076f434b..7b5904dc04 100644
--- a/packages/dashboard/src/vaadin-dashboard-widget.d.ts
+++ b/packages/dashboard/src/vaadin-dashboard-widget.d.ts
@@ -14,10 +14,58 @@ 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
+ * -----------------|-------------
+ * `title`          | A slot for the widget title. Overrides the `widgetTitle` property.
+ * `header-content` | A slot for the widget header content.
+ *
+ * #### Example
+ *
+ * ```html
+ * <vaadin-dashboard-widget>
+ *   <span slot="header-content">Header</span>
+ *   <span slot="title">Title</span>
+ *   <div>Content</div>
+ * </vaadin-dashboard-widget>
+ * ```
+ *
+ * ### Styling
+ *
+ * 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.
+ *
+ * See [Styling Components](https://vaadin.com/docs/latest/styling/styling-components) documentation.
  */
 declare class DashboardWidget extends DashboardItemMixin(ControllerMixin(ElementMixin(HTMLElement))) {
   /**
    * The title of the widget
+   *
+   * @attr {string} widget-title
    */
   widgetTitle: string | null | undefined;
 }
diff --git a/packages/dashboard/src/vaadin-dashboard-widget.js b/packages/dashboard/src/vaadin-dashboard-widget.js
index a14ce5d711..d114609c49 100644
--- a/packages/dashboard/src/vaadin-dashboard-widget.js
+++ b/packages/dashboard/src/vaadin-dashboard-widget.js
@@ -22,6 +22,52 @@ 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
+ * -----------------|-------------
+ * `title`          | A slot for the widget title. Overrides the `widgetTitle` property.
+ * `header-content` | A slot for the widget header content.
+ *
+ * #### Example
+ *
+ * ```html
+ * <vaadin-dashboard-widget>
+ *   <span slot="header-content">Header</span>
+ *   <span slot="title">Title</span>
+ *   <div>Content</div>
+ * </vaadin-dashboard-widget>
+ * ```
+ *
+ * ### Styling
+ *
+ * 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.
+ *
+ * See [Styling Components](https://vaadin.com/docs/latest/styling/styling-components) documentation.
+ *
  * @customElement
  * @extends HTMLElement
  * @mixes ElementMixin
@@ -129,6 +175,9 @@ class DashboardWidget extends DashboardItemMixin(ControllerMixin(ElementMixin(Po
 
       /**
        * The title of the widget.
+       *
+       * @attr {string} widget-title
+       * @type {string | null | undefined}
        */
       widgetTitle: {
         type: String,
diff --git a/packages/dashboard/src/vaadin-dashboard.d.ts b/packages/dashboard/src/vaadin-dashboard.d.ts
index 4a41da6795..b829b82b22 100644
--- a/packages/dashboard/src/vaadin-dashboard.d.ts
+++ b/packages/dashboard/src/vaadin-dashboard.d.ts
@@ -150,6 +150,68 @@ export interface DashboardI18n {
 
 /**
  * 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` | maximum column count of the dashboard
+ * `--vaadin-dashboard-spacing`        | spacing between the cells of the dashboard
+ * `--vaadin-dashboard-col-max-count`  | maximum column count of the dashboard
+ *
+ * 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.
+ *
+ * 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(HTMLElement),
diff --git a/packages/dashboard/src/vaadin-dashboard.js b/packages/dashboard/src/vaadin-dashboard.js
index d6a6decb35..379d03c940 100644
--- a/packages/dashboard/src/vaadin-dashboard.js
+++ b/packages/dashboard/src/vaadin-dashboard.js
@@ -33,6 +33,61 @@ import { WidgetResizeController } from './widget-resize-controller.js';
 /**
  * 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` | maximum column count of the dashboard
+ * `--vaadin-dashboard-spacing`        | spacing between the cells of the dashboard
+ * `--vaadin-dashboard-col-max-count`  | maximum column count of the dashboard
+ *
+ * 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.
+ *
+ * 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