Merge pull request #109 from amir78729/docs/jsdoc/progress-indicator

docs: add JSDoc to`progress-indicator` component

Author: amir78729

src/pinwheel/index.ts

@@ -1,6 +1,6 @@
-import { customElement } from "lit/decorators.js";
-import { Pinwheel } from "./pinwheel";
-import styles from "./pinwheel.style";
+import { customElement } from 'lit/decorators.js';
+import { Pinwheel } from './pinwheel';
+import styles from './pinwheel.style';
 
 /**
  * ### Example
@@ -11,34 +11,34 @@ import styles from "./pinwheel.style";
  *
  * @summary A pinwheel component for selecting items by scrolling through a list.
  *
- * @prop {Array.<string>} items - An array of strings that contains pinwheel items.
+ * @prop {`string[]`} [`items`=`[]`] - An array of strings that contains pinwheel items.
  *
- * @csspart pinwheel - The container that wraps the pinwheel component.
- * @csspart pinwheel-item - The item that rendered in pinwheel.
+ * @csspart `pinwheel` - The container that wraps the pinwheel component.
+ * @csspart `pinwheel-item` - The item that rendered in pinwheel.
  *
- * @cssprop [--tap-pinwheel-spacing-0=--tap-sys-spacing-0]
- * @cssprop [--tap-pinwheel-spacing-6=--tap-sys-spacing-6]
- * @cssprop [--tap-pinwheel-spacing-11=--tap-sys-spacing-11]
+ * @cssprop [`--tap-pinwheel-spacing-0`=`--tap-sys-spacing-0`]
+ * @cssprop [`--tap-pinwheel-spacing-6`=`--tap-sys-spacing-6`]
+ * @cssprop [`--tap-pinwheel-spacing-11`=`--tap-sys-spacing-11`]
  *
- * @cssprop [--tap-font-family=--tap-sys-font-family]
- * @cssprop [--tap-pinwheel-typography-body-md-height=--tap-sys-typography-body-md-height]
- * @cssprop [--tap-pinwheel-typography-body-md-size=--tap-sys-typography-body-md-size]
- * @cssprop [--tap-pinwheel-typography-body-md-weight=--tap-sys-typography-body-md-weight]
- * @cssprop [--tap-pinwheel-color-content-tertiary=--tap-sys-color-content-tertiary]
+ * @cssprop [`--tap-font-family`=`--tap-sys-font-family`]
+ * @cssprop [`--tap-pinwheel-typography-body-md-height`=`--tap-sys-typography-body-md-height`]
+ * @cssprop [`--tap-pinwheel-typography-body-md-size`=`--tap-sys-typography-body-md-size`]
+ * @cssprop [`--tap-pinwheel-typography-body-md-weight`=`--tap-sys-typography-body-md-weight`]
+ * @cssprop [`--tap-pinwheel-color-content-tertiary`=`--tap-sys-color-content-tertiary`]
  *
- * @cssprop [--tap-pinwheel-typography-label-md-height=--tap-sys-typography-label-md-height]
- * @cssprop [--tap-pinwheel-typography-label-md-size=--tap-sys-typography-label-md-size]
- * @cssprop [--tap-pinwheel-typography-label-md-weight=--tap-sys-typography-label-md-weight]
- * @cssprop [--tap-pinwheel-color-content-primary=--tap-sys-color-content-primary]
+ * @cssprop [`--tap-pinwheel-typography-label-md-height`=`--tap-sys-typography-label-md-height`]
+ * @cssprop [`--tap-pinwheel-typography-label-md-size`=`--tap-sys-typography-label-md-size`]
+ * @cssprop [`--tap-pinwheel-typography-label-md-weight`=`--tap-sys-typography-label-md-weight`]
+ * @cssprop [`--tap-pinwheel-color-content-primary`=`--tap-sys-color-content-primary`]
  *
  */
-@customElement("tap-pinwheel")
+@customElement('tap-pinwheel')
 export class TapPinwheel extends Pinwheel {
   static readonly styles = [styles];
 }
 
 declare global {
   interface HTMLElementTagNameMap {
-    "tap-pinwheel": TapPinwheel;
+    'tap-pinwheel': TapPinwheel;
   }
 }

src/pinwheel/pinwheel.stories.ts

@@ -1,9 +1,9 @@
-import { html, TemplateResult } from "lit";
-import "./index.js";
+import { html, TemplateResult } from 'lit';
+import './index.js';
 
 export default {
-  title: "Pinwheel",
-  component: "tap-pinwheel",
+  title: 'Pinwheel',
+  component: 'tap-pinwheel',
   argTypes: {},
 };
 
@@ -15,7 +15,17 @@ interface Story<T> {
 
 interface ArgTypes {}
 
-const items = ['عنوان ۱', 'عنوان ۲', 'عنوان ۳', 'عنوان ۴', 'عنوان ۵', 'عنوان ۶', 'عنوان ۷', 'عنوان ۸', 'عنوان ۹']
+const items = [
+  'عنوان ۱',
+  'عنوان ۲',
+  'عنوان ۳',
+  'عنوان ۴',
+  'عنوان ۵',
+  'عنوان ۶',
+  'عنوان ۷',
+  'عنوان ۸',
+  'عنوان ۹',
+];
 
 const Template: Story<ArgTypes> = ({}: ArgTypes) => html`
   <tap-pinwheel .items=${items}></tap-pinwheel>

src/pinwheel/pinwheel.style.ts

@@ -1,4 +1,4 @@
-import { css } from "lit";
+import { css } from 'lit';
 
 export default css`
   :host {
@@ -7,7 +7,7 @@ export default css`
     height: 144px;
     overflow: hidden;
     overflow-y: auto;
-    -ms-overflow-style: none;  /* IE and Edge */
+    -ms-overflow-style: none; /* IE and Edge */
     scrollbar-width: none; /* Firefox */
   }
 
@@ -17,15 +17,28 @@ export default css`
   }
 
   .pinwheel > div {
-    padding: var(--tap-pinwheel-spacing-0, var(--tap-sys-spacing-0)) var(--tap-pinwheel-spacing-6, var(--tap-sys-spacing-6));
+    padding: var(--tap-pinwheel-spacing-0, var(--tap-sys-spacing-0))
+      var(--tap-pinwheel-spacing-6, var(--tap-sys-spacing-6));
     /* FIXME: we dont have sizing tokens yet  */
     height: 48px;
     font: inherit;
     font-family: var(--tap-font-family, var(--tap-sys-font-family));
-    line-height: var(--tap-pinwheel-typography-body-md-height, var(--tap-sys-typography-body-md-height));
-    font-size: var(--tap-pinwheel-typography-body-md-size, var(--tap-sys-typography-body-md-size));
-    font-weight: var(--tap-pinwheel-typography-body-md-weight, var(--tap-sys-typography-body-md-weight));
-    color: var(--tap-pinwheel-color-content-tertiary, var(--tap-sys-color-content-tertiary));
+    line-height: var(
+      --tap-pinwheel-typography-body-md-height,
+      var(--tap-sys-typography-body-md-height)
+    );
+    font-size: var(
+      --tap-pinwheel-typography-body-md-size,
+      var(--tap-sys-typography-body-md-size)
+    );
+    font-weight: var(
+      --tap-pinwheel-typography-body-md-weight,
+      var(--tap-sys-typography-body-md-weight)
+    );
+    color: var(
+      --tap-pinwheel-color-content-tertiary,
+      var(--tap-sys-color-content-tertiary)
+    );
   }
 
   .pinwheel div:first-child {
@@ -37,9 +50,21 @@ export default css`
   }
 
   .pinwheel .active {
-    line-height: var(--tap-pinwheel-typography-label-md-height, var(--tap-sys-typography-label-md-height));
-    font-size: var(--tap-pinwheel-typography-label-md-size, var(--tap-sys-typography-label-md-size));
-    font-weight: var(--tap-pinwheel-typography-label-md-weight, var(--tap-sys-typography-label-md-weight));
-    color: var(--tap-pinwheel-color-content-primary, var(--tap-sys-color-content-primary));
+    line-height: var(
+      --tap-pinwheel-typography-label-md-height,
+      var(--tap-sys-typography-label-md-height)
+    );
+    font-size: var(
+      --tap-pinwheel-typography-label-md-size,
+      var(--tap-sys-typography-label-md-size)
+    );
+    font-weight: var(
+      --tap-pinwheel-typography-label-md-weight,
+      var(--tap-sys-typography-label-md-weight)
+    );
+    color: var(
+      --tap-pinwheel-color-content-primary,
+      var(--tap-sys-color-content-primary)
+    );
   }
 `;

src/pinwheel/pinwheel.ts

@@ -4,67 +4,70 @@ import { debounce } from '../utils/utils';
 
 export class Pinwheel extends LitElement {
   @state() private selectedIndex = 0;
-  @property({ type: Array , attribute:false}) items: Array<string> = [];
+  @property({ type: Array, attribute: false }) items: Array<string> = [];
 
   private itemHeight = 48;
 
   connectedCallback() {
     super.connectedCallback();
-    this.addEventListener('scroll', (event) => this.handleScroll(event.target as HTMLElement));
+    this.addEventListener('scroll', (event) =>
+      this.handleScroll(event.target as HTMLElement),
+    );
   }
 
   disconnectedCallback() {
-    this.removeEventListener('scroll', (event) => this.handleScroll(event.target as HTMLElement))
+    this.removeEventListener('scroll', (event) =>
+      this.handleScroll(event.target as HTMLElement),
+    );
     super.disconnectedCallback();
   }
 
   private dispatchChangeEvent = () => {
     this.dispatchEvent(
-      new CustomEvent("pinwheel-change", {
+      new CustomEvent('pinwheel-change', {
         detail: {
           selectedIndex: this.selectedIndex,
         },
         bubbles: true,
         composed: true,
-      })
+      }),
     );
-  }
+  };
 
   private handleScroll = debounce((target: HTMLElement) => {
     this.selectedIndex = Math.round(target?.scrollTop / this.itemHeight);
     if (target?.scrollTop % this.itemHeight) {
       this.scrollToActiveItem();
-    }
-    else {
+    } else {
       this.dispatchChangeEvent();
     }
   }, 100);
 
   private handleClickItem = (index: number) => {
     this.selectedIndex = index;
     this.scrollToActiveItem();
-  }
+  };
 
   private scrollToActiveItem = () => {
     const scrollTopPosition = this.selectedIndex * this.itemHeight;
-    this.scrollTo({ top: scrollTopPosition, behavior: 'smooth' })
-  }
+    this.scrollTo({ top: scrollTopPosition, behavior: 'smooth' });
+  };
 
   private renderItem = (item: string, index: number) => {
     return html`<div
       part="pinwheel-item"
-      class=${this.selectedIndex === index ? 'active': null}
-      @click='${() => this.handleClickItem(index)}'
+      class=${this.selectedIndex === index ? 'active' : null}
+      @click="${() => this.handleClickItem(index)}"
     >
       ${item}
-    </div>`
-  }
+    </div>`;
+  };
 
   render() {
     return html`
       <div class="pinwheel" part="pinwheel">
         ${this.items.map(this.renderItem)}
       </div>
-    `
+    `;
   }
 }

src/progress-indicator/index.ts

@@ -1,14 +1,37 @@
-import { customElement } from "lit/decorators.js";
-import { ProgressIndicator } from "./progress-indicator.js";
-import styles from "./progress-indicator.style.js";
+import { customElement } from 'lit/decorators.js';
+import { ProgressIndicator } from './progress-indicator.js';
+import styles from './progress-indicator.style.js';
 
-@customElement("tap-progress-indicator")
+/**
+ * ### Example
+ *
+ *
+ * ##### Simple
+ *
+ * ```html
+ * <tap-progress-indicator max="4" current="2"></tap-progress-indicator>
+ * ```
+ *
+ * @summary A progress indicator component displaying multiple steps.
+ *
+ * @prop {`number`} [`max`=`2`] - The total number of steps.
+ * @prop {`number`} [`current`=`0`] - The current step index.
+ *
+ * @csspart [`progressbar`] - The container for the progress bar.
+ * @csspart [`step`] - Each individual step in the progress bar.
+ *
+ * @cssprop [`--tap-progress-indicator-progressbar-color`=`--tap-sys-spacing-3`] - The gap between steps.
+ * @cssprop [`--tap-progress-indicator-step-height`=`--tap-sys-spacing-3`] - The height of each step.
+ * @cssprop [`--tap-progress-indicator-step-background-color`=`--tap-sys-color-surface-tertiary`] - The background color of each step.
+ * @cssprop [`--tap-progress-indicator-active-step-background-color`=`--tap-sys-color-border-inverse-primary`] - The background color of active steps.
+ */
+@customElement('tap-progress-indicator')
 export class TapProgressIndicator extends ProgressIndicator {
   static readonly styles = [styles];
 }
 
 declare global {
   interface HTMLElementTagNameMap {
-    "tap-progress-indicator": TapProgressIndicator;
+    'tap-progress-indicator': TapProgressIndicator;
   }
 }

src/progress-indicator/progress-indicator.stories.ts

@@ -1,12 +1,18 @@
-import { html, TemplateResult } from "lit";
-import "./index.js";
+import { html, TemplateResult } from 'lit';
+import './index.js';
 
 export default {
-  title: "Progress Indicator",
-  component: "tap-progress-indicator",
+  title: 'Progress Indicator',
+  component: 'tap-progress-indicator',
   argTypes: {
-    current: { control: { type: 'range', min: 1, max: 10, step: 1 }, description: 'Progress indicator current value' },
-    max: { control: { type: 'range', min: 1, max: 10, step: 1 }, description: 'Progress indicator max value' },
+    current: {
+      control: { type: 'range', min: 1, max: 10, step: 1 },
+      description: 'Progress indicator current value',
+    },
+    max: {
+      control: { type: 'range', min: 1, max: 10, step: 1 },
+      description: 'Progress indicator max value',
+    },
   },
 };
 
@@ -21,8 +27,11 @@ interface ArgTypes {
   max: number;
 }
 
-const Template: Story<ArgTypes> = ({current, max}: ArgTypes) => html`
-  <tap-progress-indicator current=${current} max=${max}></tap-progress-indicator>
+const Template: Story<ArgTypes> = ({ current, max }: ArgTypes) => html`
+  <tap-progress-indicator
+    current=${current}
+    max=${max}
+  ></tap-progress-indicator>
 `;
 
 export const ProgressIndicator = Template.bind({});

src/progress-indicator/progress-indicator.style.ts

@@ -1,4 +1,4 @@
-import { css } from "lit";
+import { css } from 'lit';
 
 export default css`
   :host {
@@ -18,17 +18,26 @@ export default css`
   .progressbar {
     display: flex;
     align-items: center;
-    gap: var(--tap-progress-indicator-progressbar-color, var(--tap-sys-spacing-3));
+    gap: var(
+      --tap-progress-indicator-progressbar-color,
+      var(--tap-sys-spacing-3)
+    );
   }
 
   .step {
     display: block;
     height: var(--tap-progress-indicator-step-height, var(--tap-sys-spacing-3));
     flex: 1;
-    background-color: var(--tap-progress-indicator-step-background-color, var(--tap-sys-color-surface-tertiary));
+    background-color: var(
+      --tap-progress-indicator-step-background-color,
+      var(--tap-sys-color-surface-tertiary)
+    );
   }
 
   .active {
-    background-color: var(--tap-progress-indicator-active-step-background-color, var(--tap-sys-color-border-inverse-primary));
+    background-color: var(
+      --tap-progress-indicator-active-step-background-color,
+      var(--tap-sys-color-border-inverse-primary)
+    );
   }
 `;

src/progress-indicator/progress-indicator.ts

@@ -1,8 +1,8 @@
-import { LitElement, html } from "lit";
-import { property, queryAll } from "lit/decorators.js";
-import { range } from "lit/directives/range.js";
-import { map } from "lit/directives/map.js";
-import { classMap } from "lit/directives/class-map.js";
+import { html, LitElement } from 'lit';
+import { property } from 'lit/decorators.js';
+import { range } from 'lit/directives/range.js';
+import { map } from 'lit/directives/map.js';
+import { classMap } from 'lit/directives/class-map.js';
 
 /**
  * @prop steps - total steps
@@ -38,7 +38,7 @@ export class ProgressIndicator extends LitElement {
                 active: index < this.current,
               })}
               part="step"
-            ></div>`
+            ></div>`,
         )}
       </div>
     `;