Merge pull request #117 from amir78729/docs/jsdoc/refinement

docs: refine JSDocs

Author: amir78729

src/avatar/avatar.stories.ts

@@ -1,22 +1,22 @@
-import {html, TemplateResult} from "lit";
-import "./index.js";
+import { html, TemplateResult } from 'lit';
+import './index.js';
 
 export default {
-  title: "Avatar",
-  component: "tap-avatar",
+  title: 'Avatar',
+  component: 'tap-avatar',
   argTypes: {
     image: {
       description: 'image of the avatar',
     },
     size: {
-      control: { type: "inline-radio" },
-      options: ["xSmall", "small", "medium", "large", "xLarge"],
+      control: { type: 'inline-radio' },
+      options: ['xSmall', 'small', 'medium', 'large', 'xLarge'],
       description: 'size of the avatar',
     },
     loading: {
-      control: {type: "inline-radio" },
-      options: ["eager", "lazy"],
-    }
+      control: { type: 'inline-radio' },
+      options: ['eager', 'lazy'],
+    },
   },
 };
 
@@ -29,14 +29,16 @@ interface Story<T> {
 
 interface ArgTypes {
   image: string;
-  size: "xSmall" | "small" | "medium" | "large" | "xLarge",
-  loading: "lazy" | "eager";
+  size: 'xSmall' | 'small' | 'medium' | 'large' | 'xLarge';
+  loading: 'lazy' | 'eager';
 }
 
-const Template: Story<ArgTypes> = ({image, size, loading}: ArgTypes) => html`
+const Template: Story<ArgTypes> = ({ image, size, loading }: ArgTypes) => html`
   <tap-avatar image="https://picsum.photos/100">
     <svg fill="#666" viewBox="0 0 24 24">
-      <path d="M12 2C6.48 2 2 6.48 2 12s4.48 10 10 10 10-4.48 10-10S17.52 2 12 2m0 18c-4.41 0-8-3.59-8-8v-.03c2.31-.22 3.43-1.59 4.34-3.41.17-.35.51-.56.9-.56h5.53c.38 0 .72.21.89.55.9 1.8 1.99 3.19 4.34 3.41v.03c0 4.42-3.59 8.01-8 8.01"></path>
+      <path
+        d="M12 2C6.48 2 2 6.48 2 12s4.48 10 10 10 10-4.48 10-10S17.52 2 12 2m0 18c-4.41 0-8-3.59-8-8v-.03c2.31-.22 3.43-1.59 4.34-3.41.17-.35.51-.56.9-.56h5.53c.38 0 .72.21.89.55.9 1.8 1.99 3.19 4.34 3.41v.03c0 4.42-3.59 8.01-8 8.01"
+      ></path>
       <circle cx="9" cy="13" r="1.25"></circle>
       <circle cx="15" cy="13" r="1.25"></circle>
     </svg>

src/avatar/avatar.style.ts

@@ -1,4 +1,4 @@
-import { css } from "lit";
+import { css } from 'lit';
 
 export default css`
   :host {
@@ -16,48 +16,54 @@ export default css`
   }
 
   .avatar {
-    background-color: var(--tap-avatar-background-color, var(--tap-sys-color-surface-secondary));
-    border: 1px solid var(--tap-avatar-border-color, var(--tap-sys-color-border-primary));
+    background-color: var(
+      --tap-avatar-background-color,
+      var(--tap-sys-color-surface-secondary)
+    );
+    border: 1px solid
+      var(--tap-avatar-border-color, var(--tap-sys-color-border-primary));
     border-radius: var(--tap-avatar-border-radius, var(--tap-sys-radius-full));
     display: inline-flex;
     align-items: center;
     justify-content: center;
   }
 
-  .avatar img, .avatar .placeholder, .avatar ::slotted(svg) {
+  .avatar img,
+  .avatar .placeholder,
+  .avatar ::slotted(svg) {
     width: 100%;
     height: 100%;
     border-radius: inherit;
   }
 
-  :host([size="xxSmall"]) .avatar {
+  :host([size='xxSmall']) .avatar {
     width: var(--tap-avatar-width-xxSmall, var(--tap-sys-spacing-8));
     height: var(--tap-avatar-height-, vxxSmallar(--tap-sys-spacing-8));
   }
 
-  :host([size="xSmall"]) .avatar {
+  :host([size='xSmall']) .avatar {
     width: var(--tap-avatar-width-xSmall, var(--tap-sys-spacing-9));
     height: var(--tap-avatar-height-xSmall, var(--tap-sys-spacing-9));
   }
 
-  :host([size="small"]) .avatar {
+  :host([size='small']) .avatar {
     width: var(--tap-avatar-width-small, var(--tap-sys-spacing-10));
     height: var(--tap-avatar-height-small, var(--tap-sys-spacing-10));
   }
 
-  :host([size="medium"]) .avatar {
+  :host([size='medium']) .avatar {
     width: var(--tap-avatar-width-medium, var(--tap-sys-spacing-11));
     height: var(--tap-avatar-height-medium, var(--tap-sys-spacing-11));
   }
 
   // TODO: add to tokens
-  :host([size="large"]) .avatar {
+  :host([size='large']) .avatar {
     width: var(--tap-avatar-width-large, 56px);
     height: var(--tap-avatar-height-large, 56px);
   }
 
   // TODO: add to tokens
-  :host([size="xLarge"]) .avatar {
+  :host([size='xLarge']) .avatar {
     width: var(--tap-avatar-width-xLarge, 72px);
     height: var(--tap-avatar-height-xLarge, 72px);
   }

src/avatar/avatar.ts

@@ -1,20 +1,20 @@
-import { LitElement, PropertyValues, html } from "lit";
-import { property, state } from "lit/decorators.js";
+import { LitElement, PropertyValues, html } from 'lit';
+import { property, state } from 'lit/decorators.js';
 
 export class Avatar extends LitElement {
   @state() private hasError = false;
 
-  @property() image = "";
+  @property() image = '';
 
-  @property() label = "";
+  @property() label = '';
 
-  @property() loading: "eager" | "lazy" = "eager";
+  @property() loading: 'eager' | 'lazy' = 'eager';
 
-  @property() size: "xSmall" | "small" | "medium" | "large" | "xLarge" =
-    "medium";
+  @property() size: 'xSmall' | 'small' | 'medium' | 'large' | 'xLarge' =
+    'medium';
 
   protected updated(changed: PropertyValues) {
-    if (changed.has("image")) {
+    if (changed.has('image')) {
       this.hasError = false;
     }
   }
@@ -39,12 +39,7 @@ export class Avatar extends LitElement {
 
   render() {
     return html`
-      <div
-        role="img"
-        aria-label=${this.label}
-        part="avatar"
-        class="avatar"
-      >
+      <div role="img" aria-label=${this.label} part="avatar" class="avatar">
         ${this.image && !this.hasError
           ? this.renderImage()
           : this.renderPlaceholder()}

src/avatar/index.ts

@@ -4,8 +4,8 @@ import styles from './avatar.style.js';
 
 /**
  * ### Example
- * 
- * 
+ *
+ *
  * ##### Simple
  *
  * ```html
@@ -30,36 +30,36 @@ import styles from './avatar.style.js';
  *
  * @slot - The default slot to use when image is not present.
  *
- * @prop {string} label - A label to use to describe the avatar to assistive devices.
- * @prop {string} image - The image source to use for the avatar.
- * @prop {'eager' | 'lazy'} [loading='eager'] -  Indicates how the browser should load the image.
- * @prop {'xSmall' | 'small' | 'medium' | 'large' | 'xLarge'} [size='medium'] - The size of the avatar.
+ * @prop {`string`} [`label`=`''`] - A label to use to describe the avatar to assistive devices.
+ * @prop {`string`} [`image`=`''`] - The image source to use for the avatar.
+ * @prop {`'eager'` \| `'lazy'`} [`loading`=`'eager'`] -  Indicates how the browser should load the image.
+ * @prop {`'xSmall'` \| `'small'` \| `'medium'` \| `'large'` \| `'xLarge'`} [`size`=`'medium'`] - The size of the avatar.
  *
- * @csspart avatar - The container that wraps the avatar component.
- * @csspart placeholder - The container that wraps the avatar's placeholder.
- * @csspart image - The avatar image. Only shown when the image is present.
+ * @csspart `avatar` - The container that wraps the avatar component.
+ * @csspart `placeholder` - The container that wraps the avatar's placeholder.
+ * @csspart `image` - The avatar image. Only shown when the image is present.
  *
- * @cssprop [--tap-avatar-background-color=--tap-sys-color-surface-secondary]
- * @cssprop [--tap-avatar-border-color=--tap-sys-color-border-primary]
- * @cssprop [--tap-avatar-border-radius=--tap-sys-radius-full]
+ * @cssprop [`--tap-avatar-background-color`=`--tap-sys-color-surface-secondary`]
+ * @cssprop [`--tap-avatar-border-color`=`--tap-sys-color-border-primary`]
+ * @cssprop [`--tap-avatar-border-radius`=`--tap-sys-radius-full`]
  *
- * @cssprop [--tap-avatar-width-xxSmall=--tap-sys-spacing-8]
- * @cssprop [--tap-avatar-height-xxSmall=--tap-sys-spacing-8]
+ * @cssprop [`--tap-avatar-width-xxSmall`=`--tap-sys-spacing-8`]
+ * @cssprop [`--tap-avatar-height-xxSmall`=`--tap-sys-spacing-8`]
  *
- * @cssprop [--tap-avatar-width-xSmall=--tap-sys-spacing-9]
- * @cssprop [--tap-avatar-height-xSmall=--tap-sys-spacing-9]
+ * @cssprop [`--tap-avatar-width-xSmall`=`--tap-sys-spacing-9`]
+ * @cssprop [`--tap-avatar-height-xSmall`=`--tap-sys-spacing-9`]
  *
- * @cssprop [--tap-avatar-width-small=--tap-sys-spacing-10]
- * @cssprop [--tap-avatar-height-small=--tap-sys-spacing-10]
+ * @cssprop [`--tap-avatar-width-small`=`--tap-sys-spacing-10`]
+ * @cssprop [`--tap-avatar-height-small`=`--tap-sys-spacing-10`]
  *
- * @cssprop [--tap-avatar-width-medium=--tap-sys-spacing-11]
- * @cssprop [--tap-avatar-height-medium=--tap-sys-spacing-11]
+ * @cssprop [`--tap-avatar-width-medium`=`--tap-sys-spacing-11`]
+ * @cssprop [`--tap-avatar-height-medium`=`--tap-sys-spacing-11`]
  *
- * @cssprop [--tap-avatar-width-large=56px]
- * @cssprop [--tap-avatar-height-large=56px]
+ * @cssprop [`--tap-avatar-width-large`=`56px`]
+ * @cssprop [`--tap-avatar-height-large`=`56px`]
  *
- * @cssprop [--tap-avatar-width-xLarge=72px]
- * @cssprop [--tap-avatar-height-xLarge=72px]
+ * @cssprop [`--tap-avatar-width-xLarge`=`72px`]
+ * @cssprop [`--tap-avatar-height-xLarge`=`72px`]
  */
 @customElement('tap-avatar')
 export class TapAvatar extends Avatar {

src/badge/index.ts

@@ -28,10 +28,10 @@ import styles from './badge.style';
  *
  * @summary Display badge component with different styles and types.
  *
- * @prop {`string`\|`number`} [`value`=`""`] - The value to display inside the badge.
- * @prop {`"pill"` \| `"numeral"` \| `"dot"`} [`type`=`"pill"`] - The type of the badge.
- * @prop {`"success"` \| `"error"` \| `"info"` \| `"warning"` \| `"inverse"`} [`variant`=`"inverse"`] - The variant style of the badge.
- * @prop {`"high"` \| `"low"`} [`priority`=`"high"`] - The priority level of the badge.
+ * @prop {`string`\|`number`} [`value`=`''`] - The value to display inside the badge.
+ * @prop {`'pill'` \| `'numeral'` \| `'dot'`} [`type`=`'pill'`] - The type of the badge.
+ * @prop {`'success'` \| `'error'` \| `'info'` \| `'warning'` \| `'inverse'`} [`variant`=`'inverse'`] - The variant style of the badge.
+ * @prop {`'high'` \| `'low'`} [`priority`=`'high'`] - The priority level of the badge.
  * @prop {`boolean`} [`leadingIcon`=`false`] - Whether to show an icon before the badge value.
  *
  * @csspart `badge` - The main badge element.

src/bottom-navigation-item/index.ts

@@ -24,7 +24,7 @@ import styles from './bottom-navigation-item.style.js';
  * @slot `active-icon` - Slot for the icon when the item is active.
  * @slot - The default slot for the item label or content.
  *
- * @prop {`boolean`} `active` - Indicates whether the navigation item is active.
+ * @prop {`boolean`} [`active`=`false`] - Indicates whether the navigation item is active.
  *
  * @csspart `bottom-navigation-item` - The main container for the bottom navigation item.
  *

src/icon-button/index.ts

@@ -65,7 +65,7 @@ import { baseButtonStyles } from '../base-button';
  * @prop {`'small'` \| `'medium'` \| `'large'`} [`size`=`'medium'`] - The size of the icon button.
  * @prop {`'primary'` \| `'ghost'` \| `'naked'` \| `'elevated'` \| `'destructive'` \| `'brand'`} [`variant`=`'primary'`] - The variant style of the icon button.
  *
- * @csspart button - The button element.
+ * @csspart `button` - The button element.
  *
  * @cssprop [`--tap-font-family`=`--tap-sys-font-family`] - The font family for the button.
  * @cssprop [`--tap-sys-radius-full`] - The border radius for the button.