docs: move css part docs inline

Author: bennypowers

.changeset/cold-tools-follow.md

@@ -0,0 +1,6 @@
+---
+"@patternfly/elements": patch
+---
+
+Use inline slot documentation instead of JSDoc
+  

elements/pf-accordion/pf-accordion-header.ts

@@ -30,14 +30,6 @@ export class PfAccordionHeaderChangeEvent extends Event {
 
 /**
  * Accordion Header
- * @csspart text - inline element containing the heading text or slotted heading content
- * @csspart accents - container for accents within the header
- * @csspart icon - caret icon
- * @slot
- *       We expect the light DOM of the pf-accordion-header to be a heading level tag (h1, h2, h3, h4, h5, h6)
- * @slot accents
- *       These elements will appear inline with the accordion header, between the header and the chevron
- *       (or after the chevron and header in disclosure mode).
  * @fires {AccordionHeaderChangeEvent} change - when the open panels change
  * @cssprop     {<color>} [--pf-c-accordion__toggle--Color=var(--pf-global--Color--100, #151515)]
  *              Sets the font color for the accordion header.
@@ -136,12 +128,21 @@ export class PfAccordionHeader extends LitElement {
               class="toggle"
               @click="${this.#onClick}"
               aria-expanded="${String(!!this.expanded) as 'true' | 'false'}">
+        <!-- summary: inline element containing the heading text or slotted heading content -->
         <span part="text">${headingText ?? html`
+          <!-- summary: A heading level tag (h1, h2, h3, h4, h5, h6) -->
           <slot></slot>`}
         </span>
+        <!-- summary: container for accents within the header -->
         <span part="accents" ?hidden="${this.#slots.isEmpty('accents')}">
+          <!-- summary: Header accent elements like tag or icon
+               description: |
+                 These elements will appear inline with the accordion header,
+                 between the header and the chevron
+                 (or after the chevron and header in disclosure mode). -->
           <slot name="accents"></slot>
         </span>
+        <!-- summary: caret icon -->
         <pf-icon part="icon"
                  class="icon"
                  size="lg"

elements/pf-back-to-top/pf-back-to-top.ts

@@ -14,7 +14,6 @@ import styles from './pf-back-to-top.css';
  * The **back to top** component is a shortcut that allows users to quickly navigate to the top of a lengthy content page.
  * @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
  * @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)]
@@ -109,7 +108,11 @@ export class PfBackToTop extends LitElement {
 
     if (this.href) {
       return html`
-        <a href="${this.href}" ?hidden="${!this.#visible}" part="trigger" aria-label="${ifDefined(this.#ariaLabel)}">
+        <!-- The \`<a>\` or \`<pf-button>\` element -->
+        <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. -->
@@ -119,6 +122,7 @@ export class PfBackToTop extends LitElement {
       `;
     } else {
       return html`
+        <!-- The \`<a>\` or \`<pf-button>\` element -->
         <pf-button
             icon="${ifDefined(this.icon)}"
             icon-set="${ifDefined(this.iconSet)}"

elements/pf-banner/pf-banner.ts

@@ -35,7 +35,6 @@ export type BannerVariant = (
  * @cssprop {<color>} [--pf-c-banner--m-warning--BackgroundColor=#f0ab00]
  * @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
  */
 @customElement('pf-banner')
 export class PfBanner extends LitElement {
@@ -63,6 +62,7 @@ export class PfBanner extends LitElement {
     const { variant, icon } = this;
     const hasIcon = !!icon || this.#slots.hasSlotted('icon');
     return html`
+      <!-- The container of the banner -->
       <div id="container" part="container"
             class=${classMap({ hasIcon, [variant ?? '']: !!variant })}>
         <!-- Contains the labels's icon, e.g. web-icon-alert-success. -->

elements/pf-card/pf-card.ts

@@ -15,9 +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
- * @csspart header - The container for *header* content
- * @csspart body - The container for *body* content
- * @csspart footer - The container for *footer* content
  * @cssprop {<color>} [--pf-c-card--BackgroundColor=#ffffff]
  * @cssprop {<color>} [--pf-c-card--BoxShadow=0 0.0625rem 0.125rem 0 rgba(3, 3, 3, 0.12), 0 0 0.125rem 0 rgba(3, 3, 3, 0.06)]
  * @cssprop {<color>} [--pf-c-card--size-compact__body--FontSize=.875rem]
@@ -74,24 +71,40 @@ export class PfCard extends LitElement {
   render(): TemplateResult<1> {
     return html`
       <article>
+        <!-- summary: The container for *header* content -->
         <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. -->
+          <!-- summary: When included, defines the contents of a card.
+               description: |
+                 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. -->
+          <!-- summary: Communicates the title of a card if it's not included in the header.
+               description: |
+                 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>
+        <!-- summary: The container for *body* content -->
         <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. -->
+          <!-- summary: Body. Provides details about the item.
+               description: |
+                 A card body can include any combination of static text and/or active content.
+          -->
           <slot></slot>
         </div>
+        <!-- summary: The container for *footer* content -->
         <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. -->
+          <!-- summary: Contains external links, actions, or static text at the bottom of a card. -->
           <slot name="footer"></slot>
         </footer>
       </article>

elements/pf-chip/pf-chip.ts

@@ -18,7 +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
- * @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)]
  * @cssprop [--pf-c-chip--PaddingBottom=var(--pf-global--spacer--xs, 0.25rem)]
@@ -64,13 +63,15 @@ export class PfChip extends LitElement {
   render(): TemplateResult<1> {
     return this.overflowChip ? html`
       <button id="outer">
+        <!-- container for chip text -->
         <span part="text">
           <!-- chip text -->
           <slot></slot>
         </span>
       </button>
     ` : html`
       <div id="outer">
+        <!-- container for chip text -->
         <span id="chip-text" part="text">
           <!-- chip text -->
           <slot></slot>

elements/pf-dropdown/pf-dropdown.ts

@@ -32,7 +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
- * @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
  * @cssprop {<length>} [--pf-c-dropdown__menu--ZIndex=200] Dropdown z-index
@@ -116,6 +115,7 @@ export class PfDropdown extends LitElement {
             @focusout="${this.#onMenuFocusout}"
             @keydown="${this.#onMenuKeydown}"
             @click="${this.#onSelect}">
+        <!-- The dropdown menu wrapper -->
         <pf-dropdown-menu id="menu" part="menu" ?disabled="${disabled}">
           <!-- Must contain one or more \`<pf-dropdown-item>\` or \`<pf-dropdown-group>\` -->
           <slot></slot>

elements/pf-icon/pf-icon.ts

@@ -39,7 +39,6 @@ export class IconResolveError extends ErrorEvent {
  * @alias Icon
  * @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
  * @cssprop {<length>} --pf-icon--size - size of the icon
  */
 @customElement('pf-icon')
@@ -203,8 +202,13 @@ export class PfIcon extends LitElement {
   render(): TemplateResult<1> {
     const content = this.content ?? '';
     return html`
-      <div id="container" aria-hidden="true">${content}<span part="fallback"
-          ?hidden=${!!content}><!-- Slotted content is used as a fallback in case the icon doesn't load --><slot></slot>
+      <div id="container" aria-hidden="true">${content}<!--
+         summary: Container for the fallback (i.e. slotted) content
+        -->
+        <span part="fallback"
+          ?hidden=${!!content}><!--
+           summary: Slotted content is used as a fallback in case the icon doesn't load
+        --><slot></slot>
         </span>
       </div>
     `;

elements/pf-label/pf-label.ts

@@ -69,8 +69,6 @@ export class LabelCloseEvent extends Event {
  * @cssprop {<color>} [--pf-c-label--m-orange__icon--Color=#ec7a08]
  * @cssprop {<color>} [--pf-c-label--m-red__icon--Color=#c9190b]
  * @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
  * @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]
@@ -137,14 +135,19 @@ export class PfLabel extends LitElement {
               truncated,
               [variant ?? '']: !!variant,
               [color ?? '']: !!color })}">
-        <!-- Contains the labels's icon, e.g. web-icon-alert-success. -->
+        <!-- slot:
+               summary: Contains the labels's icon, e.g. web-icon-alert-success.
+             part:
+               summary: container for the label icon
+        -->
         <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. -->
+        <!-- summary: Must contain the text for the label. -->
         <slot id="text"></slot>
+        <!-- summary: container for removable labels' close button -->
         <span part="close-button" ?hidden=${!this.removable}>
           <pf-button plain
                      @click="${this.#onClickClose}"

elements/pf-modal/pf-modal.ts

@@ -41,13 +41,6 @@ export class ModalOpenEvent extends ComposedEvent {
  * @alias Modal
  * @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
- * @csspart dialog - The dialog element
- * @csspart content - The container for the dialog content
- * @csspart header - The container for the optional dialog header
- * @csspart description - The container for the optional dialog description in the header
- * @csspart close-button - The modal's close button
- * @csspart footer - Actions footer container
  * @cssprop {<length>} [--pf-c-modal-box--ZIndex=500]
  * @cssprop {<length>} [--pf-c-modal-box--Width=calc(100 - 2rem)] - Width of the modal
  * @cssprop {<length>} [--pf-c-modal-box--MaxWidth=calc(100 - 2rem)] - Max width of the modal
@@ -122,7 +115,9 @@ export class PfModal extends LitElement implements HTMLDialogElement {
 
     return html`
       <section ?hidden=${!this.open}>
+        <!-- summary: The modal overlay which lies under the dialog and above the page body -->
         <div id="overlay" part="overlay" ?hidden=${!this.open}></div>
+        <!-- summary: The dialog element -->
         <div id="dialog"
             part="dialog"
             tabindex="0"
@@ -131,21 +126,34 @@ export class PfModal extends LitElement implements HTMLDialogElement {
             aria-label=${ifDefined(headerLabel)}
             ?hidden="${!this.open}">
           <div id="container">
+            <!-- summary: The container for the dialog content -->
             <div id="content" part="content" class=${classMap({ hasHeader, hasDescription, hasFooter })}>
+              <!-- summary: The container for the optional dialog header -->
               <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). -->
+                <!-- summary: Heading tag
+                     description: |
+                       The header is an optional slot that appears at the top of the modal window.
+                       It should be a heading tag (h2-h6). -->
                 <slot name="header"></slot>
+                <!-- summary: The container for the optional dialog description in the header -->
                 <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. -->
+              <!--
+                summary: Modal dialog content
+                description: |
+                  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>
+              <!-- summary: Actions footer container -->
               <footer ?hidden=${!hasFooter} part="footer">
-                <!-- Optional footer content. Good place to put action buttons. -->
+                <!-- summary: Optional footer content. Good place to put action buttons. -->
                 <slot name="footer"></slot>
               </footer>
             </div>
+            <!-- summary: The modal's close button -->
             <button id="close-button"
                 part="close-button"
                 aria-label="Close dialog"