Skip to content

Commit

Permalink
docs: add dashboard jsdocs (#7891)
Browse files Browse the repository at this point in the history 
* 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 <[email protected]>

* 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 <[email protected]>
  • Loading branch information
@ugur-vaadin @web-padawan
ugur-vaadin and web-padawan authored Oct 1, 2024
1 parent 3bc42b4 commit f992988
Show file tree
Hide file tree
Showing 10 changed files with 359 additions and 2 deletions.
2 changes: 2 additions & 0 deletions packages/dashboard/src/vaadin-dashboard-layout-mixin.d.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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;
}
2 changes: 2 additions & 0 deletions packages/dashboard/src/vaadin-dashboard-layout-mixin.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -104,6 +104,8 @@ export const DashboardLayoutMixin = (superClass) =>
return {
/**
* Whether the dashboard layout is dense.
*
* @attr {boolean} dense-layout
* @type {boolean}
*/
denseLayout: {
Expand Down
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
* ----------------------------------- |-------------
* `--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))) {}

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
* ----------------------------------- |-------------
* `--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
Expand Down
41 changes: 40 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,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;
}
Expand Down
42 changes: 41 additions & 1 deletion 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 All @@ -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,
Expand Down Expand Up @@ -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,
Expand Down
48 changes: 48 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,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;
}
Expand Down
49 changes: 49 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-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
Expand Down Expand Up @@ -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,
Expand Down
62 changes: 62 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,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),
Expand Down
Loading

0 comments on commit f992988

Please sign in to comment.