docs: document events in jsdoc

PiperOrigin-RevId: 581041601

checkbox/internal/checkbox.ts

@@ -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 {

chips/internal/chip.ts

@@ -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 {

chips/internal/filter-chip.ts

@@ -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;

chips/internal/input-chip.ts

@@ -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;

dialog/internal/dialog.ts

@@ -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 {

focus/internal/focus-ring.ts

@@ -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 {
   /**

iconbutton/internal/icon-button.ts

@@ -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);

labs/navigationbar/internal/navigation-bar.ts

@@ -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 {

labs/navigationdrawer/internal/navigation-drawer-modal.ts

@@ -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 {

labs/navigationdrawer/internal/navigation-drawer.ts

@@ -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 {

labs/navigationtab/internal/navigation-tab.ts

@@ -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 {

labs/segmentedbutton/internal/segmented-button.ts

@@ -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 {

labs/segmentedbuttonset/internal/segmented-button-set.ts

@@ -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 {

list/internal/listitem/list-item.ts

@@ -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 {

menu/internal/menu.ts

@@ -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 {

menu/internal/menuitem/menu-item.ts

@@ -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 {

menu/internal/submenu/sub-menu.ts

@@ -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 {
   /**

radio/internal/radio.ts

@@ -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

scripts/analyzer/update-docs.ts

@@ -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 ?? '',
     ]);
   }

select/internal/select.ts

@@ -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 {

select/internal/selectoption/select-option.ts

@@ -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 {

slider/internal/slider.ts

@@ -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 {

tabs/internal/tabs.ts

@@ -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

textfield/internal/text-field.ts

@@ -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 {