fix: Daylight: documentation consistencies: add types where missing, …

…move event descriptions to above event (#1825)

components/backdrop/README.md

@@ -8,6 +8,11 @@ The `d2l-backdrop` element is a web component to display a semi-transparent back
   import '@brightspace-ui/core/components/button/button.js';
   import '@brightspace-ui/core/components/backdrop/backdrop.js';
   import '@brightspace-ui/core/components/switch/switch.js';
+
+  const backdrop = document.querySelector('d2l-backdrop');
+  document.querySelector('#target > d2l-button').addEventListener('click', () => {
+    backdrop.shown = !backdrop.shown;
+  });
 </script>
 <style>
   #target { position: relative; z-index: 1000; margin: 40px; }
@@ -17,12 +22,6 @@ The `d2l-backdrop` element is a web component to display a semi-transparent back
   <d2l-backdrop for-target="target"></d2l-backdrop>
 </div>
 <span>Background content</span>
-<script>
-  const backdrop = document.querySelector('d2l-backdrop');
-  document.querySelector('#target > d2l-button').addEventListener('click', () => {
-    backdrop.shown = !backdrop.shown;
-  });
-</script>
 ```
 
 <!-- docs: start hidden content -->

components/backdrop/backdrop.js

@@ -17,16 +17,19 @@ class Backdrop extends LitElement {
 		return {
 			/**
 			 * REQUIRED: id of the target element to display backdrop behind
+			 * @type {string}
 			 */
 			forTarget: { type: String, attribute: 'for-target' },
 
 			/**
 			 * Disables the fade-out transition while the backdrop is being hidden
+			 * @type {boolean}
 			 */
 			noAnimateHide: { type: Boolean, attribute: 'no-animate-hide' },
 
 			/**
 			 * Used to control whether the backdrop is shown
+			 * @type {boolean}
 			 */
 			shown: { type: Boolean },
 			_state: { type: String, reflect: true }

components/breadcrumbs/breadcrumbs.js

@@ -5,13 +5,14 @@ import { RtlMixin } from '../../mixins/rtl-mixin.js';
 
 /**
  * Help users understand where they are within the application, and provide useful clues about how the space is organized. They also provide a convenient navigation mechanism.
- * @slot - breadcrumb items
+ * @slot - Breadcrumb items
  */
 class Breadcrumbs extends LocalizeCoreElement(RtlMixin(LitElement)) {
 	static get properties() {
 		return {
 			/**
 			 * Renders in compact mode, displaying only the last item
+			 * @type {boolean}
 			 */
 			compact: { type: Boolean, reflect: true }
 		};

components/button/button-icon.js

@@ -37,6 +37,7 @@ class ButtonIcon extends ThemeMixin(ButtonMixin(VisibleOnAncestorMixin(RtlMixin(
 
 			/**
 			 * Indicates to display translucent (e.g., on rich backgrounds)
+			 * @type {boolean}
 			 */
 			translucent: { type: Boolean, reflect: true }
 		};

components/button/button-mixin.js

@@ -22,10 +22,12 @@ export const ButtonMixin = superclass => class extends FocusVisiblePolyfillMixin
 			autofocus: { type: Boolean, reflect: true },
 			/**
 			 * Disables the button
+			 * @type {boolean}
 			 */
 			disabled: { type: Boolean, reflect: true },
 			/**
 			 * Tooltip text when disabled
+			 * @type {string}
 			 */
 			disabledTooltip: { type: String, attribute: 'disabled-tooltip' },
 			/**

components/button/button-subtle.js

@@ -36,6 +36,7 @@ class ButtonSubtle extends ButtonMixin(RtlMixin(LitElement)) {
 
 			/**
 			 * Indicates that the icon should be rendered on right
+			 * @type {boolean}
 			 */
 			iconRight: { type: Boolean, reflect: true, attribute: 'icon-right' },
 

components/button/button.js

@@ -23,6 +23,7 @@ class Button extends ButtonMixin(LitElement) {
 
 			/**
 			 * Styles the button as a primary button
+			 * @type {boolean}
 			 */
 			primary: { type: Boolean, reflect: true }
 		};

components/button/floating-buttons.js

@@ -17,6 +17,7 @@ class FloatingButtons extends RtlMixin(LitElement) {
 		return {
 			/**
 			 * Indicates to display buttons as always floating
+			 * @type {boolean}
 			 */
 			alwaysFloat: { type: Boolean, attribute: 'always-float', reflect: true },
 			_containerMarginLeft: { attribute: false, type: String },

components/calendar/calendar.js

@@ -132,7 +132,6 @@ export function getPrevMonth(month) {
 /**
  * A component can be used to display a responsively sized calendar that allows for date selection.
  * @slot - Content displayed under the calendar (e.g., buttons)
- * @fires d2l-calendar-selected - Dispatched when a date is selected through click, space, or enter. "e.detail.date" is in ISO 8601 calendar date format ("YYYY-MM-DD").
  */
 class Calendar extends LocalizeCoreElement(RtlMixin(LitElement)) {
 
@@ -620,6 +619,7 @@ class Calendar extends LocalizeCoreElement(RtlMixin(LitElement)) {
 			composed: true,
 			detail: { date: this.selectedValue }
 		};
+		/** Dispatched when a date is selected through click, space, or enter. "e.detail.date" is in ISO 8601 calendar date format ("YYYY-MM-DD"). */
 		this.dispatchEvent(new CustomEvent('d2l-calendar-selected', eventDetails));
 	}
 

components/card/card-footer-link.js

@@ -16,30 +16,37 @@ class CardFooterLink extends RtlMixin(LitElement) {
 		return {
 			/**
 			 * Download a URL instead of navigating to it
+			 * @type {boolean}
 			 */
 			download: { type: Boolean, reflect: true },
 			/**
 			 * URL or URL fragment of the link
+			 * @type {string}
 			 */
 			href: { type: String, reflect: true },
 			/**
 			 * Indicates the human language of the linked resource; purely advisory, with no built-in functionality
+			 * @type {string}
 			 */
 			hreflang: { type: String, reflect: true },
 			/**
 			 * REQUIRED: Preset icon key (e.g. "tier1:gear"). Must be a tier 1 icon.
+			 * @type {string}
 			 */
 			icon: { type: String, reflect: true },
 			/**
 			 * Specifies the relationship of the target object to the link object
+			 * @type {string}
 			 */
 			rel: { type: String, reflect: true },
 			/**
 			 * Secondary count to display as a count bubble on the icon
+			 * @type {number}
 			 */
 			secondaryCount: { type: Number, attribute: 'secondary-count', reflect: true },
 			/**
 			 * Maximum digits to display in the secondary count. Defaults to no limit
+			 * @type {string}
 			 */
 			secondaryCountMaxDigits: { type: String, attribute: 'secondary-count-max-digits' },
 			/**
@@ -49,14 +56,17 @@ class CardFooterLink extends RtlMixin(LitElement) {
 			secondaryCountType: { type: String, attribute: 'secondary-count-type', reflect: true },
 			/**
 			 * Where to display the linked URL
+			 * @type {string}
 			 */
 			target: { type: String, reflect: true },
 			/**
 			 * REQUIRED: Accessible text for the link (not visible, gets announced when user focuses)
+			 * @type {string}
 			 */
 			text: { type: String, reflect: true },
 			/**
 			 * Specifies the media type in the form of a MIME type for the linked URL; purely advisory, with no built-in functionality
+			 * @type {string}
 			 */
 			type: { type: String, reflect: true }
 		};
@@ -108,7 +118,7 @@ class CardFooterLink extends RtlMixin(LitElement) {
 	render() {
 		const noNumber = this.secondaryCount === undefined;
 		return html`
-			<a @focus="${this._onFocus}" 
+			<a @focus="${this._onFocus}"
 				@blur="${this._onBlur}"
 				?download="${this.download}"
 				href="${ifDefined(this.href)}"
@@ -121,7 +131,7 @@ class CardFooterLink extends RtlMixin(LitElement) {
 					aria-hidden="true"
 					icon="${this.icon}"
 					max-digits="${ifDefined(this.secondaryCountMaxDigits ? this.secondaryCountMaxDigits : undefined)}"
-					number="${noNumber ? 0 : this.secondaryCount}" 
+					number="${noNumber ? 0 : this.secondaryCount}"
 					?hide-zero="${noNumber}"
 					text="${this.text}"
 					type="${this._getType()}">

components/card/card-loading-shimmer.js

@@ -11,6 +11,7 @@ class CardLoadingShimmer extends LitElement {
 		return {
 			/**
 			 * Whether the header content is being loaded
+			 * @type {boolean}
 			 */
 			loading: { type: Boolean }
 		};

components/card/card.js

@@ -21,38 +21,47 @@ class Card extends RtlMixin(LitElement) {
 		return {
 			/**
 			 * Style the card's content and footer as centered horizontally
+			 * @type {boolean}
 			 */
 			alignCenter: { type: Boolean, attribute: 'align-center', reflect: true },
 			/**
 			 * Download a URL instead of navigating to it
+			 * @type {boolean}
 			 */
 			download: { type: Boolean, reflect: true },
 			/**
 			 * Location for the primary action/navigation
+			 * @type {string}
 			 */
 			href: { type: String, reflect: true },
 			/**
 			 * Indicates the human language of the linked resource; purely advisory, with no built-in functionality
+			 * @type {string}
 			 */
 			hreflang: { type: String, reflect: true },
 			/**
 			 * Specifies the relationship of the target object to the link object
+			 * @type {string}
 			 */
 			rel: { type: String, reflect: true },
 			/**
 			 * Subtle aesthetic on non-white backgrounds
+			 * @type {boolean}
 			 */
 			subtle: { type: Boolean, reflect: true },
 			/**
 			 * Where to display the linked URL
+			 * @type {string}
 			 */
 			target: { type: String, reflect: true },
 			/**
 			 * Accessible text for the card (will be announced when AT user focuses)
+			 * @type {string}
 			 */
 			text: { type: String, reflect: true },
 			/**
 			 * Specifies the media type in the form of a MIME type for the linked URL; purely advisory, with no built-in functionality
+			 * @type {string}
 			 */
 			type: { type: String, reflect: true },
 			_active: { type: Boolean, reflect: true },

components/dialog/dialog-confirm.js

@@ -8,15 +8,14 @@ import { heading3Styles } from '../typography/styles.js';
 /**
  * A simple confirmation dialog for prompting the user. Apply the "data-dialog-action" attribute to workflow buttons to automatically close the confirm dialog with the action value.
  * @slot footer - Slot for footer content such as workflow buttons
- * @fires d2l-dialog-open - Dispatched when the dialog is opened
- * @fires d2l-dialog-close - Dispatched with the action value when the dialog is closed for any reason
  */
 class DialogConfirm extends DialogMixin(LitElement) {
 
 	static get properties() {
 		return {
 			/**
 			 * REQUIRED: The text content for the confirmation dialog
+			 * @type {string}
 			 */
 			text: { type: String }
 		};

components/dialog/dialog-fullscreen.js

@@ -16,15 +16,14 @@ const mediaQueryList = window.matchMedia('(max-width: 615px)');
  * A generic fullscreen dialog that provides a slot for arbitrary content and a "footer" slot for workflow buttons. Apply the "data-dialog-action" attribute to workflow buttons to automatically close the dialog with the action value.
  * @slot - Default slot for content inside dialog
  * @slot footer - Slot for footer content such as workflow buttons
- * @fires d2l-dialog-open - Dispatched when the dialog is opened
- * @fires d2l-dialog-close - Dispatched with the action value when the dialog is closed for any reason
  */
 class DialogFullscreen extends LocalizeCoreElement(AsyncContainerMixin(DialogMixin(LitElement))) {
 
 	static get properties() {
 		return {
 			/**
 			 * Whether to render a loading-spinner and wait for state changes via AsyncContainerMixin
+			 * @type {boolean}
 			 */
 			async: { type: Boolean },
 			_hasFooterContent: { type: Boolean, attribute: false },
@@ -45,7 +44,7 @@ class DialogFullscreen extends LocalizeCoreElement(AsyncContainerMixin(DialogMix
 			}
 
 			@media (min-width: 616px) {
-				
+
 				.d2l-dialog-header {
 					border-bottom: 1px solid var(--d2l-color-gypsum);
 					padding-bottom: 0.9rem;
@@ -72,7 +71,7 @@ class DialogFullscreen extends LocalizeCoreElement(AsyncContainerMixin(DialogMix
 				:host([dir="rtl"]) .d2l-dialog-header > div > d2l-button-icon {
 					margin: -2px 0 0 -12px;
 				}
-				
+
 				dialog.d2l-dialog-outer,
 				div.d2l-dialog-outer {
 					border-radius: 8px;
@@ -164,7 +163,7 @@ class DialogFullscreen extends LocalizeCoreElement(AsyncContainerMixin(DialogMix
 					margin-left: -13px;
 					margin-right: 15px;
 				}
-				
+
 				dialog.d2l-dialog-outer,
 				div.d2l-dialog-outer {
 					margin: 0 !important;

components/dialog/dialog-mixin.js

@@ -244,6 +244,7 @@ export const DialogMixin = superclass => class extends RtlMixin(superclass) {
 		allowBodyScroll(this._bodyScrollKey);
 		this._bodyScrollKey = null;
 		if (this._action === undefined) this._action = abortAction;
+		/** Dispatched with the action value when the dialog is closed for any reason */
 		this.dispatchEvent(new CustomEvent(
 			'd2l-dialog-close', {
 				bubbles: true,
@@ -346,6 +347,7 @@ export const DialogMixin = superclass => class extends RtlMixin(superclass) {
 			}
 
 			if (!reduceMotion) await animPromise;
+			/** Dispatched when the dialog is opened */
 			this.dispatchEvent(new CustomEvent(
 				'd2l-dialog-open', { bubbles: true, composed: true }
 			));

components/dialog/dialog.js

@@ -17,8 +17,6 @@ const mediaQueryList = window.matchMedia('(max-width: 615px), (max-height: 420px
  * A generic dialog that provides a slot for arbitrary content and a "footer" slot for workflow buttons. Apply the "data-dialog-action" attribute to workflow buttons to automatically close the dialog with the action value.
  * @slot - Default slot for content inside dialog
  * @slot footer - Slot for footer content such as workflow buttons
- * @fires d2l-dialog-open - Dispatched when the dialog is opened
- * @fires d2l-dialog-close - Dispatched with the action value when the dialog is closed for any reason
  */
 class Dialog extends LocalizeCoreElement(AsyncContainerMixin(DialogMixin(LitElement))) {
 

components/dropdown/dropdown-button-subtle.js

@@ -14,14 +14,14 @@ class DropdownButtonSubtle extends DropdownOpenerMixin(LitElement) {
 		return {
 			/**
 			 * A description to be added to the opener button for accessibility when text on button does not provide enough context
+			 * @type {string}
 			 */
 			description: { type: String },
 			/**
 			 * REQUIRED: Text for the button
+			 * @type {string}
 			 */
-			text: {
-				type: String
-			}
+			text: { type: String }
 		};
 	}
 

components/dropdown/dropdown-button.js

@@ -15,6 +15,7 @@ class DropdownButton extends DropdownOpenerMixin(RtlMixin(LitElement)) {
 		return {
 			/**
 			 * Optionally render button as primary button
+			 * @type {boolean}
 			 */
 			primary: {
 				type: Boolean,
@@ -23,6 +24,7 @@ class DropdownButton extends DropdownOpenerMixin(RtlMixin(LitElement)) {
 
 			/**
 			 * REQUIRED: Text for the button
+			 * @type {string}
 			 */
 			text: {
 				type: String