docs: move slot jsdoc to inline

bennypowers · bennypowers · commit 5fde074f345c · 2025-08-08T07:53:34.000+03:00
diff --git a/elements/.config/cem.yaml b/elements/.config/cem.yaml
@@ -10,5 +10,5 @@ generate:
   noDefaultExcludes: false
   demoDiscovery:
     fileGlob: '*/demo/*.html'
-    urlPattern: :tag/demo/:demo.html
+    urlPattern: ':tag/demo/:demo.html'
     urlTemplate: https://patternflyelements.org/components/{{.tag | alias | slug}}/demo/{{.demo | slug}}/
diff --git a/elements/pf-accordion/pf-accordion.ts b/elements/pf-accordion/pf-accordion.ts
@@ -40,8 +40,6 @@ export class PfAccordionCollapseEvent extends Event {
  * @alias Accordion
  * @fires {AccordionExpandEvent} expand - when a panel expands
  * @fires {AccordionCollapseEvent} collapse - when a panel collapses
- * @slot
- *       Place the `pf-accordion-header` and `pf-accordion-panel` elements here.
  * @cssprop [--pf-c-accordion--BackgroundColor=var(--pf-global--BackgroundColor--100, #fff)]
  * @cssprop [--pf-c-accordion__toggle--PaddingTop=var(--pf-global--spacer--sm, 0.5rem)]
  * @cssprop [--pf-c-accordion__toggle--PaddingRight=var(--pf-global--spacer--md, 1rem)]
@@ -186,6 +184,7 @@ export class PfAccordion extends LitElement {
 
   render(): TemplateResult<1> {
     return html`
+      <!-- Place the \`pf-accordion-header\` and \`pf-accordion-panel\` elements here. -->
       <slot></slot>
     `;
   }
diff --git a/elements/pf-back-to-top/pf-back-to-top.ts b/elements/pf-back-to-top/pf-back-to-top.ts
@@ -15,10 +15,6 @@ import styles from './pf-back-to-top.css';
  * @summary A shortcut that allows users to quickly navigate to the top of a lengthy content page.
  * @alias Back to Top
  * @csspart trigger - The `<a>` or `<pf-button>` element
- * @slot icon
- *       Contains the prefix icon to display before the link or button.
- * @slot
- *       Text to display inside the link or button.
  * @cssprop {<length>} [--pf-c-back-to-top--Right=3rem`]
  * @cssprop {<length>} [--pf-c-back-to-top--Bottom=1.5rem`]
  * @cssprop [--pf-c-back-to-top--c-button--BoxShadow=0 0.75rem 0.75rem -0.5rem rgba(3, 3, 3, 0.18)]
@@ -114,7 +110,9 @@ export class PfBackToTop extends LitElement {
     if (this.href) {
       return html`
         <a href="${this.href}" ?hidden="${!this.#visible}" part="trigger" aria-label="${ifDefined(this.#ariaLabel)}">
+          <!-- Contains the prefix icon to display before the link or button. -->
           <slot name="icon"></slot>
+          <!-- Text to display inside the link or button. -->
           <slot @slotchange="${this.#onSlotchange}"></slot>
           <pf-icon icon="angle-up" set="fas"></pf-icon>
         </a>
@@ -129,8 +127,10 @@ export class PfBackToTop extends LitElement {
             part="trigger"
             label="${ifDefined(this.#ariaLabel)}"
           >
+          <!-- Contains the prefix icon to display before the link or button. -->
           <slot name="icon" slot="icon"></slot>
           <span>
+            <!-- Text to display inside the link or button. -->
             <slot></slot>
             <pf-icon icon="angle-up" set="fas"></pf-icon>
           </span>
diff --git a/elements/pf-background-image/pf-background-image.ts b/elements/pf-background-image/pf-background-image.ts
@@ -12,7 +12,6 @@ import styles from './pf-background-image.css';
  * A **background image** allows you to place an image in the background of your page or area of a page.
  * @summary Allows users to place an image in the background of your page or area of a page.
  * @alias Background Image
- * @slot filter - Overrides the default svg filter for the background image.
  * @cssprop {<color>} [--pf-c-background-image--BackgroundColor=#151515]
  * @cssprop [--pf-c-background-image--Filter=url("#image_overlay")]
  * @cssprop --pf-c-background-image--BackgroundImage
@@ -83,6 +82,7 @@ export class PfBackgroundImage extends LitElement {
     return html`
       <div id="container" part="container" style="${styleMap(cssProps)}">
         ${!this.filter ? html`` : html`
+          <!-- Overrides the default svg filter for the background image. -->
           <slot name="filter" @slotchange=${this.#onSlotChange}>
             ${(this.#svg && this.#updated) ? this.#svg : html`
               <svg xmlns="http://www.w3.org/2000/svg" width="0" height="0">
diff --git a/elements/pf-banner/pf-banner.ts b/elements/pf-banner/pf-banner.ts
@@ -36,10 +36,6 @@ export type BannerVariant = (
  * @cssprop [--pf-c-banner--m-sticky--ZIndex=300]
  * @cssprop [--pf-c-banner--m-sticky--BoxShadow=0 0.5rem 0.5rem -0.375rem rgba(3, 3, 3, 0.18)]
  * @csspart container - The container of the banner
- * @slot icon
- *       Contains the labels's icon, e.g. web-icon-alert-success.
- * @slot
- *       Contains the text for the banner
  */
 @customElement('pf-banner')
 export class PfBanner extends LitElement {
@@ -69,9 +65,11 @@ export class PfBanner extends LitElement {
     return html`
       <div id="container" part="container"
             class=${classMap({ hasIcon, [variant ?? '']: !!variant })}>
+        <!-- Contains the labels's icon, e.g. web-icon-alert-success. -->
         <slot name="icon" part="icon">${!this.icon ? '' : html`
           <pf-icon icon="${this.icon}"></pf-icon>`}
         </slot>
+        <!-- Contains the text for the banner -->
         <slot id="text"></slot>
       </div>
     `;
diff --git a/elements/pf-card/pf-card.ts b/elements/pf-card/pf-card.ts
@@ -15,18 +15,6 @@ import style from './pf-card.css';
  * like card views, or for positioning content on a page.
  * @summary Gives a preview of information in a small layout
  * @alias Card
- * @slot header
- *       When included, defines the contents of a card. Card headers can contain images as well as
- *       the title of a card and an actions menu represented by the right-aligned kebab.
- *       In most cases, your card should include a header. The only exceptions are when cards being
- *       used as a layout element to create a white background behind other content.
- * @slot title
- *       Communicates the title of a card if it's not included in the header.
- *       If a card will be utilized as a selectable and clickable card, the title needs to be made as a linked text to trigger action and indicate interaction.
- * @slot - Body. Provides details about the item. A card body can include any combination of static
- *         text and/or active content.
- * @slot footer
- *       Contains external links, actions, or static text at the bottom of a card.
  * @csspart header - The container for *header* content
  * @csspart body - The container for *body* content
  * @csspart footer - The container for *footer* content
@@ -89,17 +77,21 @@ export class PfCard extends LitElement {
         <header id="header"
                 part="header"
                 class="${classMap({ empty: this.#slots.isEmpty('header') })}">
+          <!-- When included, defines the contents of a card. Card headers can contain images as well as the title of a card and an actions menu represented by the right-aligned kebab. In most cases, your card should include a header. The only exceptions are when cards being used as a layout element to create a white background behind other content. -->
           <slot name="header"></slot>
+          <!-- Communicates the title of a card if it's not included in the header. If a card will be utilized as a selectable and clickable card, the title needs to be made as a linked text to trigger action and indicate interaction. -->
           <slot id="title" name="title" ?hidden="${this.#slots.isEmpty('title')}"></slot>
         </header>
         <div id="body"
              part="body"
              class="${classMap({ empty: this.#slots.isEmpty(null) })}">
+          <!-- Body. Provides details about the item. A card body can include any combination of static text and/or active content. -->
           <slot></slot>
         </div>
         <footer id="footer"
                 part="footer"
                 class="${classMap({ empty: this.#slots.isEmpty('footer') })}">
+          <!-- Contains external links, actions, or static text at the bottom of a card. -->
           <slot name="footer"></slot>
         </footer>
       </article>
diff --git a/elements/pf-chip/pf-chip.ts b/elements/pf-chip/pf-chip.ts
@@ -18,8 +18,6 @@ export class PfChipRemoveEvent extends Event {
  * @alias Chip
  * @fires {ChipRemoveEvent} remove - Fires when chip is removed
  * @fires {Event} click - when close button is clicked
- * @slot
- *      chip text
  * @csspart text - container for chip text
  * @cssprop [--pf-c-chip--PaddingTop=var(--pf-global--spacer--xs, 0.25rem)]
  * @cssprop [--pf-c-chip--PaddingRight=var(--pf-global--spacer--sm, 0.5rem)]
@@ -67,12 +65,14 @@ export class PfChip extends LitElement {
     return this.overflowChip ? html`
       <button id="outer">
         <span part="text">
+          <!-- chip text -->
           <slot></slot>
         </span>
       </button>
     ` : html`
       <div id="outer">
         <span id="chip-text" part="text">
+          <!-- chip text -->
           <slot></slot>
         </span>
         <pf-button id="close-button"
diff --git a/elements/pf-clipboard-copy/pf-clipboard-copy.ts b/elements/pf-clipboard-copy/pf-clipboard-copy.ts
@@ -22,8 +22,6 @@ export class PfClipboardCopyCopiedEvent extends Event {
 /**
  * The **clipboard copy** component allows users to quickly and easily copy content to their clipboard.
  * @alias Clipboard Copy
- * @slot - Place content to copy here, or use the `value` attribute
- * @slot actions - Place additional action buttons here
  * @fires {PfClipboardCopyCopiedEvent} copy - when the text snippet is successfully copied.
  * @cssprop [--pf-c-clipboard-copy__toggle-icon--Transition=.2s ease-in 0s]
  * @cssprop [--pf-c-clipboard-copy--m-expanded__toggle-icon--Rotate=90deg]
@@ -149,6 +147,7 @@ export class PfClipboardCopy extends LitElement {
             </pf-button>
             <span slot="content">${this.#copied ? this.clickTip : this.hoverTip}</span>
           </pf-tooltip>
+          <!-- Place additional action buttons here -->
           <slot name="actions"></slot>
         </div>
         <textarea .value="${this.value}"
diff --git a/elements/pf-code-block/pf-code-block.ts b/elements/pf-code-block/pf-code-block.ts
@@ -7,13 +7,6 @@ import styles from './pf-code-block.css';
 /**
  * A **code block** is a component that contains 2 or more lines of read-only code. The code in a code block can be copied to the clipboard.
  * @alias Code Block
- * @slot code
- *       The slot to put the code in
- * @slot expandable-code
- *       The slot to put the code in that should be revealed when the "Show more" button is
- *       clicked to expand the code-block
- * @slot actions
- *       Contains the actions for the code-block. For example, copy to clipboard.
  * @attr {boolean} [expanded=false]
  *       Indicates if the code-block has been expanded
  * @cssprop {<color>} [--pf-c-code-block--BackgroundColor=#f0f0f0]
@@ -59,6 +52,7 @@ export class PfCodeBlock extends LitElement {
     return html`
       <div id="header">
         <div id="actions">
+          <!-- Contains the actions for the code-block. For example, copy to clipboard. -->
           <slot name="actions"></slot>
         </div>
       </div>
diff --git a/elements/pf-dropdown/pf-dropdown.ts b/elements/pf-dropdown/pf-dropdown.ts
@@ -32,9 +32,6 @@ export class PfDropdownSelectEvent extends Event {
  * A **dropdown** presents a menu of actions or links in a constrained space that
  * will trigger a process or navigate to a new location.
  * @alias Dropdown
- * @slot - Must contain one or more `<pf-dropdown-item>` or `<pf-dropdown-group>`
- * @slot toggle - Custom toggle button
- * @slot menu - when using a custom toggle, you must slot a `<pf-dropdown-menu>` in alongside it
  * @csspart menu - The dropdown menu wrapper
  * @cssprop {<length>} [--pf-c-dropdown__menu--PaddingTop=0.5rem] Dropdown top padding
  * @cssprop {<length>} [--pf-c-tooltip__content--PaddingRight=0.5rem] Dropdown right padding
@@ -104,6 +101,7 @@ export class PfDropdown extends LitElement {
                              [alignment ?? '']: !!alignment })}"
          style="${styleMap(styles)}"
          @slotchange="${this.#onSlotchange}">
+      <!-- Custom toggle button -->
       <slot name="toggle"
             @keydown="${this.#onButtonKeydown}"
             @click="${() => this.toggle()}">
@@ -112,12 +110,14 @@ export class PfDropdown extends LitElement {
           <pf-icon icon="caret-down" size="md"></pf-icon>
         </pf-button>
       </slot>
+      <!-- when using a custom toggle, you must slot a \`<pf-dropdown-menu>\` in alongside it -->
       <slot name="menu"
             ?hidden="${!this.expanded}"
             @focusout="${this.#onMenuFocusout}"
             @keydown="${this.#onMenuKeydown}"
             @click="${this.#onSelect}">
         <pf-dropdown-menu id="menu" part="menu" ?disabled="${disabled}">
+          <!-- Must contain one or more \`<pf-dropdown-item>\` or \`<pf-dropdown-group>\` -->
           <slot></slot>
         </pf-dropdown-menu>
       </slot>
diff --git a/elements/pf-icon/pf-icon.ts b/elements/pf-icon/pf-icon.ts
@@ -37,7 +37,6 @@ export class IconResolveError extends ErrorEvent {
  * An **icon** component is a container that allows for icons of varying dimensions to
  * seamlessly replace each other without shifting surrounding content.
  * @alias Icon
- * @slot - Slotted content is used as a fallback in case the icon doesn't load
  * @fires load - Fired when an icon is loaded and rendered
  * @fires error - Fired when an icon fails to load
  * @csspart fallback - Container for the fallback (i.e. slotted) content
@@ -205,7 +204,7 @@ export class PfIcon extends LitElement {
     const content = this.content ?? '';
     return html`
       <div id="container" aria-hidden="true">${content}<span part="fallback"
-          ?hidden=${!!content}><slot></slot>
+          ?hidden=${!!content}><!-- Slotted content is used as a fallback in case the icon doesn't load --><slot></slot>
         </span>
       </div>
     `;
diff --git a/elements/pf-jump-links/pf-jump-links.ts b/elements/pf-jump-links/pf-jump-links.ts
@@ -15,7 +15,6 @@ import style from './pf-jump-links.css';
  * **Jump links** allow users to navigate to sections within a page.
  * @alias Jump Links
  * @fires toggle - when the `expanded` disclosure widget is toggled
- * @slot - Place pf-jump-links-items here
  * @cssprop --pf-c-jump-links__list--Display
  * @cssprop --pf-c-jump-links__list--FlexDirection
  * @cssprop --pf-c-jump-links__list--PaddingTop -- padding around the list of links
@@ -129,11 +128,13 @@ export class PfJumpLinks extends LitElement {
             <span id="label">${this.label}</span>
           </summary>
           <div role="listbox" aria-labelledby="label">
+            <!-- Place pf-jump-links-items here -->
             <slot></slot>
           </div>
         </details>` : html`
         <span id="label">${this.label}</span>
         <div role="listbox" aria-labelledby="label">
+          <!-- Place pf-jump-links-items here -->
           <slot></slot>
         </div>`}
       </nav>
diff --git a/elements/pf-label/pf-label.ts b/elements/pf-label/pf-label.ts
@@ -71,10 +71,6 @@ export class LabelCloseEvent extends Event {
  * @cssprop {<color>} [--pf-c-label--m-gold__icon--Color=#f0ab00]
  * @csspart icon - container for the label icon
  * @csspart close-button - container for removable labels' close button
- * @slot icon
- *       Contains the labels's icon, e.g. web-icon-alert-success.
- * @slot
- *       Must contain the text for the label.
  * @cssprop {<length>} [--pf-c-label--m-compact--PaddingTop=0]
  * @cssprop {<length>} [--pf-c-label--m-compact--PaddingRight=0.5rem]
  * @cssprop {<length>} [--pf-c-label--m-compact--PaddingBottom=0]
@@ -141,11 +137,13 @@ export class PfLabel extends LitElement {
               truncated,
               [variant ?? '']: !!variant,
               [color ?? '']: !!color })}">
+        <!-- Contains the labels's icon, e.g. web-icon-alert-success. -->
         <slot name="icon" part="icon">
           <pf-icon ?hidden="${!icon}"
                    size="sm"
                    .icon="${this.icon || undefined as unknown as string}"></pf-icon>
         </slot>
+        <!-- Must contain the text for the label. -->
         <slot id="text"></slot>
         <span part="close-button" ?hidden=${!this.removable}>
           <pf-button plain
diff --git a/elements/pf-modal/pf-modal.ts b/elements/pf-modal/pf-modal.ts
@@ -39,9 +39,6 @@ export class ModalOpenEvent extends ComposedEvent {
  * to a new page.
  * @summary Displays information or helps a user focus on a task
  * @alias Modal
- * @slot - The default slot can contain any type of content. When the header is not present this unnamed slot appear at the top of the modal window (to the left of the close button). Otherwise it will appear beneath the header.
- * @slot header - The header is an optional slot that appears at the top of the modal window. It should be a header tag (h2-h6).
- * @slot footer - Optional footer content. Good place to put action buttons.
  * @fires {ModalOpenEvent} open - Fires when a user clicks on the trigger or manually opens a modal.
  * @fires {ModalCloseEvent} close - Fires when either a user clicks on either the close button or the overlay or manually closes a modal.
  * @csspart overlay - The modal overlay which lies under the dialog and above the page body
@@ -136,13 +133,16 @@ export class PfModal extends LitElement implements HTMLDialogElement {
           <div id="container">
             <div id="content" part="content" class=${classMap({ hasHeader, hasDescription, hasFooter })}>
               <header part="header">
+                <!-- The header is an optional slot that appears at the top of the modal window. It should be a header tag (h2-h6). -->
                 <slot name="header"></slot>
                 <div part="description" ?hidden=${!hasDescription}>
                   <slot name="description"></slot>
                 </div>
               </header>
+              <!-- The default slot can contain any type of content. When the header is not present this unnamed slot appear at the top of the modal window (to the left of the close button). Otherwise it will appear beneath the header. -->
               <slot></slot>
               <footer ?hidden=${!hasFooter} part="footer">
+                <!-- Optional footer content. Good place to put action buttons. -->
                 <slot name="footer"></slot>
               </footer>
             </div>
diff --git a/elements/pf-panel/pf-panel.ts b/elements/pf-panel/pf-panel.ts
@@ -12,9 +12,6 @@ import styles from './pf-panel.css';
  * The panel should not be confused with the [drawer](https://www.patternfly.org/v4/components/drawer/design-guidelines/)
  * component, which allows you to surface information via a collapsable container.
  * @alias Panel
- * @slot header - Place header content here
- * @slot - Place main content here
- * @slot footer - Place footer content here
  * @cssprop [--pf-c-panel--Width=auto]
  * @cssprop [--pf-c-panel--MinWidth=auto]
  * @cssprop [--pf-c-panel--MaxWidth=none]
@@ -60,11 +57,14 @@ export class PfPanel extends LitElement {
     const hasFooter = this.#slots.hasSlotted('footer');
     return html`
       <header>
+        <!-- Place header content here -->
         <slot name="header" ?hidden="${!hasHeader}"></slot>
       </header>
       <hr role="presentation" ?hidden="${!hasHeader}">
+      <!-- Place main content here -->
       <slot></slot>
       <footer>
+        <!-- Place footer content here -->
         <slot name="footer" ?hidden="${!hasFooter}"></slot>
       </footer>
     `;
diff --git a/elements/pf-popover/pf-popover.ts b/elements/pf-popover/pf-popover.ts
diff --git a/elements/pf-select/pf-select.ts b/elements/pf-select/pf-select.ts
diff --git a/elements/pf-table/pf-table.ts b/elements/pf-table/pf-table.ts
diff --git a/elements/pf-tabs/pf-tabs.ts b/elements/pf-tabs/pf-tabs.ts
diff --git a/elements/pf-tile/pf-tile.ts b/elements/pf-tile/pf-tile.ts
diff --git a/elements/pf-tooltip/pf-tooltip.ts b/elements/pf-tooltip/pf-tooltip.ts
