mirror of
https://github.com/material-components/material-web.git
synced 2024-08-17 09:30:27 +03:00
docs: document events in jsdoc
PiperOrigin-RevId: 581041601
This commit is contained in:
parent
5e0000a495
commit
2adcb1479a
@ -35,6 +35,14 @@ const checkboxBaseClass = mixinFormAssociated(
|
||||
|
||||
/**
|
||||
* A checkbox component.
|
||||
*
|
||||
*
|
||||
* @fires change {Event} The native `change` event on
|
||||
* [`<input>`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/change_event)
|
||||
* --bubbles
|
||||
* @fires input {InputEvent} The native `input` event on
|
||||
* [`<input>`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/input_event)
|
||||
* --bubbles --composed
|
||||
*/
|
||||
export class Checkbox extends checkboxBaseClass {
|
||||
static {
|
||||
|
@ -15,6 +15,8 @@ import {requestUpdateOnAriaChange} from '../../internal/aria/delegate.js';
|
||||
|
||||
/**
|
||||
* A chip component.
|
||||
*
|
||||
* @fires update-focus {Event} Dispatched when `disabled` is toggled. --bubbles
|
||||
*/
|
||||
export abstract class Chip extends LitElement {
|
||||
static {
|
||||
|
@ -17,6 +17,8 @@ import {renderRemoveButton} from './trailing-icons.js';
|
||||
|
||||
/**
|
||||
* A filter chip component.
|
||||
*
|
||||
* @fires remove {Event} Dispatched when the remove button is clicked.
|
||||
*/
|
||||
export class FilterChip extends MultiActionChip {
|
||||
@property({type: Boolean}) elevated = false;
|
||||
|
@ -14,6 +14,8 @@ import {renderRemoveButton} from './trailing-icons.js';
|
||||
|
||||
/**
|
||||
* An input chip component.
|
||||
*
|
||||
* @fires remove {Event} Dispatched when the remove button is clicked.
|
||||
*/
|
||||
export class InputChip extends MultiActionChip {
|
||||
@property({type: Boolean}) avatar = false;
|
||||
|
@ -24,12 +24,12 @@ import {
|
||||
/**
|
||||
* A dialog component.
|
||||
*
|
||||
* @fires open Dispatched when the dialog is opening before any animations.
|
||||
* @fires opened Dispatched when the dialog has opened after any animations.
|
||||
* @fires close Dispatched when the dialog is closing before any animations.
|
||||
* @fires closed Dispatched when the dialog has closed after any animations.
|
||||
* @fires cancel Dispatched when the dialog has been canceled by clicking on the
|
||||
* scrim or pressing Escape.
|
||||
* @fires open {Event} Dispatched when the dialog is opening before any animations.
|
||||
* @fires opened {Event} Dispatched when the dialog has opened after any animations.
|
||||
* @fires close {Event} Dispatched when the dialog is closing before any animations.
|
||||
* @fires closed {Event} Dispatched when the dialog has closed after any animations.
|
||||
* @fires cancel {Event} Dispatched when the dialog has been canceled by clicking
|
||||
* on the scrim or pressing Escape.
|
||||
*/
|
||||
export class Dialog extends LitElement {
|
||||
static {
|
||||
|
@ -14,13 +14,13 @@ import {
|
||||
|
||||
/**
|
||||
* Events that the focus ring listens to.
|
||||
*
|
||||
* @fires visibility-changed Fired whenever `visible` changes.
|
||||
*/
|
||||
const EVENTS = ['focusin', 'focusout', 'pointerdown'];
|
||||
|
||||
/**
|
||||
* A focus ring component.
|
||||
*
|
||||
* @fires visibility-changed {Event} Fired whenever `visible` changes.
|
||||
*/
|
||||
export class FocusRing extends LitElement implements Attachable {
|
||||
/**
|
||||
|
@ -30,7 +30,13 @@ type LinkTarget = '_blank' | '_parent' | '_self' | '_top';
|
||||
// Separate variable needed for closure.
|
||||
const iconButtonBaseClass = mixinElementInternals(LitElement);
|
||||
|
||||
// tslint:disable-next-line:enforce-comments-on-exported-symbols
|
||||
/**
|
||||
* A button for rendering icons.
|
||||
*
|
||||
* @fires input {InputEvent} Dispatched when a toggle button toggles --bubbles
|
||||
* --composed
|
||||
* @fires change {Event} Dispatched when a toggle button toggles --bubbles
|
||||
*/
|
||||
export class IconButton extends iconButtonBaseClass implements FormSubmitter {
|
||||
static {
|
||||
requestUpdateOnAriaChange(IconButton);
|
||||
|
@ -19,6 +19,9 @@ import {NavigationBarState} from './state.js';
|
||||
|
||||
/**
|
||||
* TODO(b/265346501): add docs
|
||||
*
|
||||
* @fires navigation-bar-activated {CustomEvent<tab: NavigationTab, activeIndex: number>}
|
||||
* Dispatched whenever the `activeIndex` changes. --bubbles --composed
|
||||
*/
|
||||
export class NavigationBar extends LitElement implements NavigationBarState {
|
||||
static {
|
||||
|
@ -13,6 +13,9 @@ import {requestUpdateOnAriaChange} from '../../../internal/aria/delegate.js';
|
||||
|
||||
/**
|
||||
* TODO(b/265346501): add docs
|
||||
*
|
||||
* @fires navigation-drawer-changed {CustomEvent<{opened: boolean}>}
|
||||
* Dispatched whenever the drawer opens or closes --bubbles --composed
|
||||
*/
|
||||
export class NavigationDrawerModal extends LitElement {
|
||||
static {
|
||||
|
@ -15,6 +15,9 @@ import {requestUpdateOnAriaChange} from '../../../internal/aria/delegate.js';
|
||||
|
||||
/**
|
||||
* TODO(b/265346501): add docs
|
||||
*
|
||||
* @fires navigation-drawer-changed {CustomEvent<{opened: boolean}>}
|
||||
* Dispatched whenever the drawer opens or closes --bubbles --composed
|
||||
*/
|
||||
export class NavigationDrawer extends LitElement {
|
||||
static {
|
||||
|
@ -19,6 +19,12 @@ import {NavigationTabState} from './state.js';
|
||||
|
||||
/**
|
||||
* TODO(b/265346501): add docs
|
||||
*
|
||||
* @fires navigation-tab-rendered {Event} Dispatched when the navigation tab's
|
||||
* DOM has rendered and custom element definition has loaded. --bubbles
|
||||
* --composed
|
||||
* @fires navigation-tab-interaction {CustomEvent<{state: MdNavigationTab}>}
|
||||
* Dispatched when the navigation tab has been clicked. --bubbles --composed
|
||||
*/
|
||||
export class NavigationTab extends LitElement implements NavigationTabState {
|
||||
static {
|
||||
|
@ -19,6 +19,9 @@ import {requestUpdateOnAriaChange} from '../../../internal/aria/delegate.js';
|
||||
* segmented button component. It is intended **only** for use as a child of a
|
||||
* `SementedButtonSet` component. It is **not** intended for use in any other
|
||||
* context.
|
||||
*
|
||||
* @fires segmented-button-interaction {Event} Dispatched whenever a button is
|
||||
* clicked. --bubbles --composed
|
||||
*/
|
||||
export class SegmentedButton extends LitElement {
|
||||
static {
|
||||
|
@ -15,6 +15,11 @@ import {SegmentedButton} from '../../segmentedbutton/internal/segmented-button.j
|
||||
* SegmentedButtonSet is the parent component for two or more
|
||||
* `SegmentedButton` components. **Only** `SegmentedButton` components may be
|
||||
* used as children.
|
||||
*
|
||||
* @fires segmented-button-set-selection {CustomEvent<{button: SegmentedButton, selected: boolean, index: number}>}
|
||||
* Dispatched when a button is selected programattically with the
|
||||
* `setButtonSelected` or the `toggleSelection` methods as well as on user
|
||||
* interaction. --bubbles --composed
|
||||
*/
|
||||
export class SegmentedButtonSet extends LitElement {
|
||||
static {
|
||||
|
@ -26,7 +26,8 @@ import {
|
||||
export type ListItemType = 'text' | 'button' | 'link';
|
||||
|
||||
/**
|
||||
* @fires request-activation
|
||||
* @fires request-activation {Event} Requests the list to set `tabindex=0` on
|
||||
* the item and focus it. --bubbles --composed
|
||||
*/
|
||||
export class ListItemEl extends LitElement implements ListItem {
|
||||
static {
|
||||
|
@ -84,10 +84,10 @@ function getFocusedElement(
|
||||
}
|
||||
|
||||
/**
|
||||
* @fires opening Fired before the opening animation begins
|
||||
* @fires opened Fired once the menu is open, after any animations
|
||||
* @fires closing Fired before the closing animation begins
|
||||
* @fires closed Fired once the menu is closed, after any animations
|
||||
* @fires opening {Event} Fired before the opening animation begins
|
||||
* @fires opened {Event} Fired once the menu is open, after any animations
|
||||
* @fires closing {Event} Fired before the closing animation begins
|
||||
* @fires closed {Event} Fired once the menu is closed, after any animations
|
||||
*/
|
||||
export abstract class Menu extends LitElement {
|
||||
static {
|
||||
|
@ -22,7 +22,8 @@ import {
|
||||
} from '../controllers/menuItemController.js';
|
||||
|
||||
/**
|
||||
* @fires close-menu {CloseMenuEvent}
|
||||
* @fires close-menu {CustomEvent<{initiator: SelectOption, reason: Reason, itemPath: SelectOption[]}>}
|
||||
* Closes the encapsulating menu on closable interaction. --bubbles --composed
|
||||
*/
|
||||
export class MenuItemEl extends LitElement implements MenuItem {
|
||||
static {
|
||||
|
@ -27,14 +27,14 @@ import {
|
||||
import {Corner} from '../menu.js';
|
||||
|
||||
/**
|
||||
* @fires deactivate-items Requests the parent menu to deselect other items when
|
||||
* a submenu opens
|
||||
* @fires request-activation Requests the parent make the slotted item focusable
|
||||
* and focuses the item.
|
||||
* @fires deactivate-typeahead Requests the parent menu to deactivate the
|
||||
* typeahead functionality when a submenu opens
|
||||
* @fires activate-typeahead Requests the parent menu to activate the typeahead
|
||||
* functionality when a submenu closes
|
||||
* @fires deactivate-items {Event} Requests the parent menu to deselect other
|
||||
* items when a submenu opens. --bubbles --composed
|
||||
* @fires request-activation {Event} Requests the parent make the slotted item
|
||||
* focusable and focuses the item. --bubbles --composed
|
||||
* @fires deactivate-typeahead {Event} Requests the parent menu to deactivate
|
||||
* the typeahead functionality when a submenu opens. --bubbles --composed
|
||||
* @fires activate-typeahead {Event} Requests the parent menu to activate the
|
||||
* typeahead functionality when a submenu closes. --bubbles --composed
|
||||
*/
|
||||
export class SubMenu extends LitElement {
|
||||
/**
|
||||
|
@ -36,10 +36,10 @@ const radioBaseClass = mixinFormAssociated(
|
||||
/**
|
||||
* A radio component.
|
||||
*
|
||||
* @fires input Dispatched when the value changes from user interaction.
|
||||
* --bubbles
|
||||
* @fires change Dispatched when the value changes from user interaction.
|
||||
* --bubbles --composed
|
||||
* @fires input {InputEvent} Dispatched when the value changes from user
|
||||
* interaction. --bubbles
|
||||
* @fires change {Event} Dispatched when the value changes from user
|
||||
* interaction. --bubbles --composed
|
||||
*/
|
||||
export class Radio extends radioBaseClass {
|
||||
// Unique maskId is required because of a Safari bug that fail to persist
|
||||
|
@ -357,10 +357,9 @@ function generateMethodMarkdownTable(element: MdModuleInfo): MarkdownTable {
|
||||
function generateEventsMarkdownTable(element: MdModuleInfo): MarkdownTable {
|
||||
const eventsTable = new MarkdownTable([
|
||||
'Event',
|
||||
// TODO reenable these once we update our docs to support them
|
||||
// 'Type',
|
||||
// 'Bubbles',
|
||||
// 'Composed',
|
||||
'Type',
|
||||
'[Bubbles](https://developer.mozilla.org/en-US/docs/Web/API/Event/bubbles)',
|
||||
'[Composed](https://developer.mozilla.org/en-US/docs/Web/API/Event/composed)',
|
||||
'Description',
|
||||
]);
|
||||
const eventNameOrder: string[] = [];
|
||||
@ -368,10 +367,9 @@ function generateEventsMarkdownTable(element: MdModuleInfo): MarkdownTable {
|
||||
string,
|
||||
{
|
||||
name: string;
|
||||
// TODO reenable these once we update our docs to support them
|
||||
// type?: string;
|
||||
// bubbles: boolean;
|
||||
// composed: boolean;
|
||||
type?: string;
|
||||
bubbles: boolean;
|
||||
composed: boolean;
|
||||
description?: string;
|
||||
}
|
||||
>();
|
||||
@ -382,10 +380,9 @@ function generateEventsMarkdownTable(element: MdModuleInfo): MarkdownTable {
|
||||
for (const event of currentClass.events) {
|
||||
const row = {
|
||||
name: event.name,
|
||||
// TODO reenable these once we update our docs to support them
|
||||
// type: event.type,
|
||||
// bubbles: event.bubbles,
|
||||
// composed: event.composed,
|
||||
type: event.type,
|
||||
bubbles: event.bubbles,
|
||||
composed: event.composed,
|
||||
description: event.description,
|
||||
};
|
||||
|
||||
@ -408,10 +405,9 @@ function generateEventsMarkdownTable(element: MdModuleInfo): MarkdownTable {
|
||||
const rowObj = eventToRow.get(eventName);
|
||||
eventsTable.addRow([
|
||||
`\`${rowObj.name}\``,
|
||||
// TODO reenable these once we update our docs to support them
|
||||
// `\`${rowObj.type}\`` ?? '',
|
||||
// rowObj.bubbles ? 'Yes' : 'No',
|
||||
// rowObj.composed ? 'Yes' : 'No',
|
||||
rowObj.type ? `\`${rowObj.type}\`` : '`Event`',
|
||||
rowObj.bubbles ? 'Yes' : 'No',
|
||||
rowObj.composed ? 'Yes' : 'No',
|
||||
rowObj.description ?? '',
|
||||
]);
|
||||
}
|
||||
|
@ -44,16 +44,18 @@ const VALUE = Symbol('value');
|
||||
const selectBaseClass = mixinFormAssociated(mixinElementInternals(LitElement));
|
||||
|
||||
/**
|
||||
* @fires input Fired when a selection is made by the user via mouse or keyboard
|
||||
* interaction.
|
||||
* @fires change Fired when a selection is made by the user via mouse or
|
||||
* keyboard interaction.
|
||||
* @fires opening Fired when the select's menu is about to open.
|
||||
* @fires opened Fired when the select's menu has finished animations and
|
||||
* opened.
|
||||
* @fires closing Fired when the select's menu is about to close.
|
||||
* @fires closed Fired when the select's menu has finished animations and
|
||||
* closed.
|
||||
* @fires change {Event} The native `change` event on
|
||||
* [`<input>`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/change_event)
|
||||
* --bubbles
|
||||
* @fires input {InputEvent} The native `input` event on
|
||||
* [`<input>`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/input_event)
|
||||
* --bubbles --composed
|
||||
* @fires opening {Event} Fired when the select's menu is about to open.
|
||||
* @fires opened {Event} Fired when the select's menu has finished animations
|
||||
* and opened.
|
||||
* @fires closing {Event} Fired when the select's menu is about to close.
|
||||
* @fires closed {Event} Fired when the select's menu has finished animations
|
||||
* and closed.
|
||||
*/
|
||||
export abstract class Select extends selectBaseClass {
|
||||
static {
|
||||
|
@ -18,11 +18,13 @@ import {requestUpdateOnAriaChange} from '../../../internal/aria/delegate.js';
|
||||
import {SelectOption, SelectOptionController} from './selectOptionController.js';
|
||||
|
||||
/**
|
||||
* @fires close-menu Closes the encapsulating menu on
|
||||
* @fires request-selection Requests the parent md-select to select this element
|
||||
* (and deselect others if single-selection) when `selected` changed to `true`.
|
||||
* @fires request-deselection Requests the parent md-select to deselect this
|
||||
* element when `selected` changed to `false`.
|
||||
* @fires close-menu {CustomEvent<{initiator: SelectOption, reason: Reason, itemPath: SelectOption[]}>}
|
||||
* Closes the encapsulating menu on closable interaction. --bubbles --composed
|
||||
* @fires request-selection {Event} Requests the parent md-select to select this
|
||||
* element (and deselect others if single-selection) when `selected` changed to
|
||||
* `true`. --bubbles --composed
|
||||
* @fires request-deselection {Event} Requests the parent md-select to deselect
|
||||
* this element when `selected` changed to `false`. --bubbles --composed
|
||||
*/
|
||||
export class SelectOptionEl extends LitElement implements SelectOption {
|
||||
static {
|
||||
|
@ -36,6 +36,14 @@ const sliderBaseClass = mixinFormAssociated(mixinElementInternals(LitElement));
|
||||
|
||||
/**
|
||||
* Slider component.
|
||||
*
|
||||
*
|
||||
* @fires change {Event} The native `change` event on
|
||||
* [`<input>`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/change_event)
|
||||
* --bubbles
|
||||
* @fires input {InputEvent} The native `input` event on
|
||||
* [`<input>`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/input_event)
|
||||
* --bubbles --composed
|
||||
*/
|
||||
export class Slider extends sliderBaseClass {
|
||||
static {
|
||||
|
@ -17,12 +17,12 @@ import {
|
||||
import {ANIMATE_INDICATOR, Tab} from './tab.js';
|
||||
|
||||
/**
|
||||
* @fires change Fired when the selected tab changes. The target's selected or
|
||||
* @fires change {Event} Fired when the selected tab changes. The target's selected or
|
||||
* selectedItem and previousSelected or previousSelectedItem provide information
|
||||
* about the selection change. The change event is fired when a user interaction
|
||||
* like a space/enter key or click cause a selection change. The tab selection
|
||||
* based on these actions can be cancelled by calling preventDefault on the
|
||||
* triggering `keydown` or `click` event.
|
||||
* triggering `keydown` or `click` event. --bubbles
|
||||
*
|
||||
* @example
|
||||
* // perform an action if a tab is clicked
|
||||
|
@ -70,6 +70,16 @@ const textFieldBaseClass = mixinFormAssociated(
|
||||
|
||||
/**
|
||||
* A text field component.
|
||||
*
|
||||
* @fires select {Event} The native `select` event on
|
||||
* [`<input>`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement/select_event)
|
||||
* --bubbles
|
||||
* @fires change {Event} The native `change` event on
|
||||
* [`<input>`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/change_event)
|
||||
* --bubbles
|
||||
* @fires input {InputEvent} The native `input` event on
|
||||
* [`<input>`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/input_event)
|
||||
* --bubbles --composed
|
||||
*/
|
||||
export abstract class TextField extends textFieldBaseClass {
|
||||
static {
|
||||
|
Loading…
Reference in New Issue
Block a user