docs: migrate jsdoc

.stylelintrc.yml

@@ -51,7 +51,7 @@ rules:
   '@stylistic/string-quotes': single
   '@stylistic/selector-combinator-space-after': always
   '@stylistic/selector-combinator-space-before': always
-  '@stylistic/function-parentheses-newline-inside': never-multi-line
+  '@stylistic/function-parentheses-newline-inside': null
   '@stylistic/function-comma-newline-after': always-multi-line
   '@stylistic/indentation':
     - 2

docs/_includes/layouts/pages/element.11ty.ts

@@ -391,8 +391,8 @@ export default class ElementsPage extends Renderer<Context> {
                 ${(await Promise.all(slots.map(async slot => html`
                 <tr>
                   <td><code>${slot.name}</code></td>
-                  <td>${await this.#innerMD(slot.description)}</td>
                   <td>${await this.#innerMD(slot.summary)}</td>
+                  <td>${await this.#innerMD(slot.description)}</td>
                 </tr>`))).join('')}
               </tbody>
             </table>
@@ -652,8 +652,8 @@ export default class ElementsPage extends Renderer<Context> {
                 ${(await Promise.all(parts.map(async part => html`
                 <tr>
                   <td><code>${part.name}</code></td>
-                  <td>${await this.#innerMD(part.description)}</td>
                   <td>${await this.#innerMD(part.summary)}</td>
+                  <td>${await this.#innerMD(part.description)}</td>
                 </tr>`))).join('')}
               </tbody>
             </table>

elements/rh-accordion/rh-accordion.ts

@@ -51,7 +51,6 @@ export class AccordionCollapseEvent extends ComposedEvent {
  *
  * @fires {AccordionExpandEvent} expand - when a panel expands
  * @fires {AccordionCollapseEvent} collapse - when a panel collapses
- * @slot - Place the `rh-accordion-header` and `rh-accordion-panel` elements here.
  * @attr  [accents=inline] Position accents in the header either inline or bottom
  */
 @customElement('rh-accordion')
@@ -150,7 +149,9 @@ export class RhAccordion extends LitElement {
     const expanded = this.#expanded;
     return html`
       <div id="container"
-           class="${classMap({ large, expanded })}"><slot></slot></div>
+           class="${classMap({ large, expanded })}"><!--
+        Place the \`rh-accordion-header\` and \`rh-accordion-panel\` elements here.
+        --><slot></slot></div>
     `;
   }
 

elements/rh-alert/rh-alert.ts

@@ -64,11 +64,6 @@ const toasts = new Set<Required<ToastOptions>>();
  * @alias alert
  *
  * @fires {AlertCloseEvent} close - when the dismissable alert closes
- *
- * @slot         - Provide a description for the alert message
- * @slot header  - Provide a header for the alert message.
- * @slot actions - Provide actions that the user can take for the alert
- *
  */
 @customElement('rh-alert')
 @themable
@@ -209,6 +204,7 @@ export class RhAlert extends LitElement {
     // eslint-disable-next-line lit-a11y/click-events-have-key-events
     const footer = html`<footer class="${classMap({ hasActions })}"
                   @click="${this.#onActionsClick}">
+            <!-- Provide actions that the user can take for the alert -->
             <slot name="actions"></slot>
           </footer>`;
     return html`
@@ -228,6 +224,7 @@ export class RhAlert extends LitElement {
         <div id="middle-column">
           <header ?hidden="${!_isServer && this.#slots.isEmpty('header')}">
             <div id="header">
+              <!-- Provide a header for the alert message. -->
               <slot name="header"></slot>
             </div>${!this.dismissable && this.variant !== 'toast' ? '' : html`
             <div id="header-actions">
@@ -239,6 +236,7 @@ export class RhAlert extends LitElement {
             </div>`}
           </header>
           <div id="description">
+            <!-- Provide a description for the alert message -->
             <slot></slot>
           </div>
           ${footer}

elements/rh-announcement/rh-announcement.ts

@@ -25,20 +25,9 @@ export class AnnouncementCloseEvent extends Event {
  *
  * @alias announcement
  *
- * @slot    image
- *          If this slot is used, we expect an image tag with a width and height set.
- *          An icon, svg, or use of the icon component are also valid in this region.
- * @slot    Any content that is not designated for the header or footer slot, will go to this slot.
- * @slot    cta
- *          If this slot is used, we expect a rh-cta component.
  * @fires   {AnnouncementCloseEvent} close
  *          When a user clicks the close/dismiss button on an announcement.
- * @csspart row
- *          The row for the banner. Contains the image and content divs.
- * @csspart image
- *          The image for the banner. Contains the image slot.
  */
-
 @customElement('rh-announcement')
 @colorPalettes
 @themable
@@ -76,17 +65,25 @@ export class RhAnnouncement extends LitElement {
               'block-start': imagePosBlockStart,
               'empty': this.#slots.isEmpty(null),
             })}">
+        <!-- The row for the banner. Contains the image and content divs. -->
         <div id="row" part="row">
+          <!-- The image for the banner. Contains the image slot. -->
           <div id="image"
                part="image"
                class="${classMap({ empty: !this.#slots.hasSlotted('image') })}">
+            <!--
+              If this slot is used, we expect an image tag with a width and height set.
+              An icon, svg, or use of the icon component are also valid in this region.
+            -->
             <slot name="image"></slot>
           </div>
           <div id="content">
             <div id="body" class="${classMap({ empty: this.#slots.isEmpty(null) })}">
+              <!-- Any content that is not designated for the header or footer slot, will go to this slot. -->
               <slot></slot>
             </div>
             <div id="cta" class="${classMap({ empty: !this.#slots.hasSlotted('cta') })}">
+              <!-- If this slot is used, we expect a rh-cta component. -->
               <slot name="cta"></slot>
             </div>
           </div>

elements/rh-audio-player/rh-audio-player-about.ts

@@ -13,12 +13,6 @@ import { HeadingLevelContextConsumer } from '../../lib/context/headings/consumer
 
 /**
  * Audio Player About Panel
- * @slot heading - custom heading for panel
- * @slot - panel content
- * @slot profile - `<rh-avatar>` for attribution
- * @csspart heading - panel heading
- * @csspart body - panel body
- * @csspart profile - panel profile / avatar
  */
 @customElement('rh-audio-player-about')
 export class RhAudioPlayerAbout extends LitElement {
@@ -45,7 +39,9 @@ export class RhAudioPlayerAbout extends LitElement {
     const heading = this.#headings.wrap(mediatitle ?? '');
 
     return html`
+      <!-- panel heading -->
       <rh-audio-player-scrolling-text-overflow id="title" part="heading">
+        <!-- custom heading for panel -->
         <slot name="heading">${label}</slot>
       </rh-audio-player-scrolling-text-overflow>${!mediatitle ? `` : !mediaseries ? heading : html`
       <hgroup class="media-info" part="heading">${!mediaseries ? '' : html`
@@ -56,7 +52,16 @@ export class RhAudioPlayerAbout extends LitElement {
           ${heading}
         </rh-audio-player-scrolling-text-overflow>
       </hgroup>`}
-      <div part="body" ?hidden="${!hasContent}" tabindex=0><slot></slot></div>
+      <!-- panel body -->
+      <div part="body" ?hidden="${!hasContent}" tabindex=0><!-- panel content --><slot></slot></div>
+      <!--
+        part:
+          description: |
+            panel profile / avatar
+        slot:
+          description: |
+            \`<rh-avatar>\` for attribution
+      -->
       <slot part="profile" name="profile"></slot>`;
   }
 

elements/rh-audio-player/rh-audio-player-range-styles.css

@@ -48,7 +48,8 @@ input[type='range'] {
   --_interactive-color: var(--rh-color-border-interactive);
   --_accent-color: var(--rh-color-accent-brand);
   --_outline: var(--rh-border-width-md, 2px) solid var(--_interactive-color);
-  --_thumb-color: var(--rh-audio-player-range-thumb-color, var(--_accent-color));
+  --_thumb-color: /** color of time and volume range slider thumb */
+    var(--rh-audio-player-range-thumb-color, var(--_accent-color));
   --_progress-color: var(--rh-audio-player-range-progress-color, var(--_accent-color));
 
   &:focus {

elements/rh-audio-player/rh-audio-player-scrolling-text-overflow.css

@@ -19,6 +19,7 @@
   flex: 1 0 auto;
   overflow-y: visible;
 
+  /** color of fade effect (should match background) */
   --_fade-color:
     light-dark(var(--rh-audio-player-scrolling-text-overflow-background-color,
       var(--rh-color-surface-lightest, #ffffff)),

elements/rh-audio-player/rh-audio-player-scrolling-text-overflow.ts

@@ -8,16 +8,12 @@ import styles from './rh-audio-player-scrolling-text-overflow.css';
 
 /**
  * Audio Player Scrolling Text Overflow
- * @slot - inline text to scroll if wider than host
- * @cssprop [--rh-audio-player-scrolling-text-overflow-background-color=var(--rh-color-surface-lightest, #ffffff)]
- *          color of fade effect (should match background)
  */
 @customElement('rh-audio-player-scrolling-text-overflow')
 @themable
 export class RhAudioPlayerScrollingTextOverflow extends LitElement {
   static readonly styles = [styles];
 
-
   #scrolling = false;
 
   #style?: CSSStyleDeclaration;
@@ -42,18 +38,21 @@ export class RhAudioPlayerScrollingTextOverflow extends LitElement {
   }
 
   render() {
-    const { direction } = this.#style ?? {};
+    const direction = this.#style?.direction ?? 'auto';
+    const scrolling = this.#scrolling;
+    const scrollable = this.#isScrollable;
     return html`
       <div id="outer"
-           class="${classMap({ [direction || 'auto']: true })}"
+           class="${classMap({ [direction]: true })}"
            @mouseover=${this.startScrolling}
            @mouseout=${this.stopScrolling}
            @focus=${this.startScrolling}
            @blur=${this.stopScrolling}>
         <div id="inner">
-          <slot class="${this.#scrolling ? 'scrolling' : ''} ${this.#isScrollable ? 'scrollable' : ''}"></slot>
-        </div>
-        ${this.#isScrollable ? html`<span id="fade"></span>` : ''}
+          <!-- inline text to scroll if wider than host -->
+          <slot class="${classMap({ scrolling, scrollable })}"></slot>
+        </div>${!scrollable ? '' : html`
+        <span id="fade"></span>`}
       </div>`;
   }
 

elements/rh-audio-player/rh-audio-player-subscribe.ts

@@ -13,12 +13,6 @@ import styles from './rh-audio-player-subscribe.css';
 
 /**
  * Audio Player Subscribe Panel
- * @slot heading - custom heading for panel
- * @slot - panel content
- * @slot link - link to subscribe to podcast
- * @csspart heading - scrolling text overflow
- * @csspart body - body content slot
- * @csspart links - subscribe links
  */
 @customElement('rh-audio-player-subscribe')
 export class RhAudioPlayerSubscribe extends LitElement {
@@ -36,10 +30,17 @@ export class RhAudioPlayerSubscribe extends LitElement {
 
   override render() {
     return html`
+      <!-- scrolling text overflow -->
       <rh-audio-player-scrolling-text-overflow part="heading">
+        <!-- custom heading for panel -->
         <slot name="heading">${this.#headings.wrap(this.menuLabel)}</slot>
       </rh-audio-player-scrolling-text-overflow>
+      <!-- panel content -->
       <slot part="body" ?hidden="${this.#slots.isEmpty(null)}"></slot>
+      <!-- slot:
+             summary: link to subscribe to podcast
+           part:
+             summary: subscribe links -->
       <slot name="link" part="links"></slot>`;
   }
 

elements/rh-audio-player/rh-audio-player.css

@@ -37,13 +37,18 @@ button {
   --_about-mediatitle-display: none;
   --_about-heading-display: flex;
   --_box-shadow: light-dark(var(--rh-box-shadow-md, 0 4px 6px 1px rgba(21, 21, 21, 0.25)), none);
-  --_secondary-opacity: var(--rh-audio-player-secondary-opacity, 1);
+  --_secondary-opacity: /** player secondary opacity used for partially faded elements - */
+    var(--rh-audio-player-secondary-opacity, 1);
   --_text-color: var(--rh-audio-player-text-color, var(--rh-color-text-primary));
-  --_border-color: var(--rh-color-border-subtle);
+  --_border-color: /** color of player border - */
+    var(--rh-color-border-subtle);
   --_surface-color:
-    light-dark(var(--rh-audio-player-background-color, var(--rh-color-surface-lightest, #ffffff)),
-      var(--rh-audio-player-background-color, var(--rh-color-surface-darkest, #151515)));
-  --_secondary-text-color:
+    light-dark(
+        /** color of player background - */
+        var(--rh-audio-player-background-color, var(--rh-color-surface-lightest, #ffffff)),
+        var(--rh-audio-player-background-color, var(--rh-color-surface-darkest, #151515))
+      );
+  --_secondary-text-color: /** player secondary text color - */
     var(--rh-audio-player-secondary-text-color,
       var(--rh-color-text-secondary));
   --_static-border-color: var(--rh-color-border-subtle);
@@ -58,9 +63,17 @@ button {
   --_static-surface-focus-color:
     light-dark(var(--rh-color-surface-light, #e0e0e0),
       var(--rh-color-surface-dark, #383838));
+
+  /** padding top on tooltips - */
   --rh-tooltip-content-padding-block-start: var(--rh-space-md, 8px);
+
+  /** padding bottom on tooltips - */
   --rh-tooltip-content-padding-block-end: var(--rh-space-md, 8px);
+
+  /** padding left on tooltips - */
   --rh-tooltip-content-padding-inline-start: var(--rh-space-md, 8px);
+
+  /** padding right on tooltips - */
   --rh-tooltip-content-padding-inline-end: var(--rh-space-md, 8px);
   --rh-audio-player-scrolling-text-overflow-background-color: var(--_surface-color);