Skip to content

Commit

Permalink
docs: add dashboard jsdocs
Browse files Browse the repository at this point in the history
  • Loading branch information
@ugur-vaadin
ugur-vaadin committed Sep 30, 2024
1 parent 462a19f commit 82975b7
Show file tree
Hide file tree
Showing 8 changed files with 348 additions and 1 deletion.
30 changes: 30 additions & 0 deletions packages/dashboard/src/vaadin-dashboard-layout.d.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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 | Default
* ----------------------------------|----------------------------------------|---------
* --vaadin-dashboard-col-min-width | minimum column width of the dashboard | 25rem
* --vaadin-dashboard-col-max-width | maximum column width of the dashboard | 1fr
* --vaadin-dashboard-row-min-height | maximum column count of the dashboard | auto
* --vaadin-dashboard-gap | gap between the cells of the dashboard | 1rem
* --vaadin-dashboard-col-max-count | maximum column count of the dashboard | number of columns
*
* 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))) {}

Expand Down
30 changes: 30 additions & 0 deletions packages/dashboard/src/vaadin-dashboard-layout.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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 | Default
* ----------------------------------|----------------------------------------|---------
* --vaadin-dashboard-col-min-width | minimum column width of the dashboard | 25rem
* --vaadin-dashboard-col-max-width | maximum column width of the dashboard | 1fr
* --vaadin-dashboard-row-min-height | maximum column count of the dashboard | auto
* --vaadin-dashboard-gap | gap between the cells of the dashboard | 1rem
* --vaadin-dashboard-col-max-count | maximum column count of the dashboard | number of columns
*
* 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
Expand Down
39 changes: 38 additions & 1 deletion packages/dashboard/src/vaadin-dashboard-section.d.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,44 @@ 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))) {
/**
Expand Down
37 changes: 37 additions & 0 deletions packages/dashboard/src/vaadin-dashboard-section.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
46 changes: 46 additions & 0 deletions packages/dashboard/src/vaadin-dashboard-widget.d.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,52 @@ 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">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` | A slot for the widget header.
*
* #### Example
*
* ```html
* <vaadin-dashboard-widget>
* <span slot="header">Header</span>
* <span slot="title">Title</span>
* <div>Content</div>
* </vaadin-dashboard-widget>
* ```
*
* ### Styling
*
* The following custom properties are available:
*
* Custom Property | Description | Default
* --------------------------------|-----------------------|---------
* --vaadin-dashboard-item-colspan | colspan of the widget | 1
* --vaadin-dashboard-item-rowspan | rowspan of the widget | 1
*
* 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))) {
/**
Expand Down
46 changes: 46 additions & 0 deletions packages/dashboard/src/vaadin-dashboard-widget.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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">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` | A slot for the widget header.
*
* #### Example
*
* ```html
* <vaadin-dashboard-widget>
* <span slot="header">Header</span>
* <span slot="title">Title</span>
* <div>Content</div>
* </vaadin-dashboard-widget>
* ```
*
* ### Styling
*
* The following custom properties are available:
*
* Custom Property | Description | Default
* --------------------------------|-----------------------|---------
* --vaadin-dashboard-item-colspan | colspan of the widget | 1
* --vaadin-dashboard-item-rowspan | rowspan of the widget | 1
*
* 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
Expand Down
64 changes: 64 additions & 0 deletions packages/dashboard/src/vaadin-dashboard.d.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -150,6 +150,70 @@ 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', header: 'Widget 1 Header', rowspan: 2 },
* { title: 'Widget 2 title', header: 'Widget 2 Header', colspan: 2 },
* {
* title: 'Section title',
* items: [{ title: 'Widget in section title', header: 'Widget in Section Header'}]
* },
* // ... more items
* ];
*
* dashboard.renderer = (root, _dashboard, { item }) => {
* if (!root.firstElementChild) {
* root.append(document.createElement('vaadin-dashboard-widget'));
* }
* root.firstElementChild.widgetTitle = item.title;
* root.firstElementChild.innerHTML = `
* <span slot="header">${item.header}</span>
* <div>Widget content</div>
* `;
* };
* ```
*
* ### Styling
*
* The following custom properties are available:
*
* Custom Property | Description | Default
* ----------------------------------|----------------------------------------|---------
* --vaadin-dashboard-col-min-width | minimum column width of the dashboard | 25rem
* --vaadin-dashboard-col-max-width | maximum column width of the dashboard | 1fr
* --vaadin-dashboard-row-min-height | maximum column count of the dashboard | auto
* --vaadin-dashboard-gap | gap between the cells of the dashboard | 1rem
* --vaadin-dashboard-col-max-count | maximum column count of the dashboard | number of columns
*
* 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),
Expand Down
Loading

0 comments on commit 82975b7

Please sign in to comment.