Merge pull request #100 from amir78729/feat/banner-jsdoc

docs: add JSDoc to `banner` component

Author: amir78729

src/banner/banner.stories.ts

@@ -1,10 +1,10 @@
-import { html, TemplateResult } from "lit";
-import "./index.js";
-import "../button/index.js";
+import { html, TemplateResult } from 'lit';
+import './index.js';
+import '../button/index.js';
 
 export default {
-  title: "Banner",
-  component: "tap-banner",
+  title: 'Banner',
+  component: 'tap-banner',
   argTypes: {},
 };
 
@@ -28,19 +28,19 @@ const Template: Story<ArgTypes> = ({}: ArgTypes) => html`
   </tap-banner>
 
   <tap-banner
-variant="hero"
+    variant="hero"
     heading="با ۱۶۳۰، تلفنی تپسی بگیر"
     description="درخواست خودرو بدون نیاز به اینترنت"
     image="https://able-media.tapsi.cab/statics/N31LNC95J6MCPIYB0D.jpg"
     background-color="rgb(255, 213, 194)"
     text-color="rgb(66, 46, 40)"
   >
-    <tap-button size="small" slot="extra" >majid</tap-button>
+    <tap-button size="small" slot="extra">majid</tap-button>
     <tap-button size="small">دریافت تخفیف</tap-button>
   </tap-banner>
-<br />
+  <br />
   <tap-banner
-variant="hero"
+    variant="hero"
     heading="با ۱۶۳۰، تلفنی تپسی بگیر"
     description="درخواست خودرو بدون نیاز به اینترنت"
     image="https://able-media.tapsi.cab/statics/N31LNC95J6MCPIYB0D.jpg"

src/banner/banner.style.ts

@@ -1,4 +1,4 @@
-import { css } from "lit";
+import { css } from 'lit';
 
 export default css`
   :host {
@@ -36,17 +36,16 @@ export default css`
 
   .banner h4 {
     color: var(--tap-banner-color-content);
-    font-family: var(--tap-sys-typography-headline-xs-font);
+    font-family: var(--tap-sys-typography-headline-xs-font, --tap-sys-font-family);
     line-height: var(--tap-sys-typography-headline-xs-height);
     font-size: var(--tap-sys-typography-headline-xs-size);
     font-weight: var(--tap-sys-typography-headline-xs-weight);
-    margin: 0;
-    margin-bottom: var(--tap-sys-spacing-3);
+    margin: 0 0 var(--tap-sys-spacing-3);
   }
 
   .banner p {
     color: var(--tap-banner-color-content);
-    font-family: var(--tap-sys-typography-body-xs-font);
+    font-family: var(--tap-sys-typography-body-xs-font, --tap-sys-font-family);
     line-height: var(--tap-sys-typography-body-xs-height);
     font-size: var(--tap-sys-typography-body-xs-size);
     font-weight: var(--tap-sys-typography-body-xs-weight);

src/banner/banner.ts

@@ -1,33 +1,33 @@
-import { LitElement, PropertyValues, html, nothing } from "lit";
-import { property } from "lit/decorators.js";
-import { classMap } from "lit/directives/class-map.js";
+import { LitElement, PropertyValues, html, nothing } from 'lit';
+import { property } from 'lit/decorators.js';
+import { classMap } from 'lit/directives/class-map.js';
 
 export class Banner extends LitElement {
   @property() heading?: string;
   @property() description?: string;
   @property() image?: string;
-  @property({ type: Boolean, attribute: "full-width" }) fullWidth = false;
-  @property() variant: "default" | "hero" = "default";
-  @property({ attribute: "background-color" }) backgroundColor?: string;
-  @property({ attribute: "text-color" }) textColor?: string;
+  @property({ type: Boolean, attribute: 'full-width' }) fullWidth = false;
+  @property() variant: 'default' | 'hero' = 'default';
+  @property({ attribute: 'background-color' }) backgroundColor?: string;
+  @property({ attribute: 'text-color' }) textColor?: string;
   // @property() loading?: boolean;
 
   protected updated(changed: PropertyValues): void {
-    if (changed.has("backgroundColor") && !!this.backgroundColor) {
+    if (changed.has('backgroundColor') && !!this.backgroundColor) {
       this.style.setProperty(
-        "--tap-banner-color-surface",
-        this.backgroundColor
+        '--tap-banner-color-surface',
+        this.backgroundColor,
       );
     }
 
-    if (changed.has("textColor") && !!this.textColor) {
-      this.style.setProperty("--tap-banner-color-content", this.textColor);
+    if (changed.has('textColor') && !!this.textColor) {
+      this.style.setProperty('--tap-banner-color-content', this.textColor);
     }
 
-    if (changed.has("image") && !!this.image) {
+    if (changed.has('image') && !!this.image) {
       this.style.setProperty(
-        "--tap-banner-background-image",
-        `url(${this.image})`
+        '--tap-banner-background-image',
+        `url(${this.image})`,
       );
     }
   }
@@ -38,10 +38,10 @@ export class Banner extends LitElement {
         role="banner"
         class=${classMap({
           banner: true,
-          hero: this.variant === "hero",
+          hero: this.variant === 'hero',
         })}
       >
-        ${this.variant === "hero"
+        ${this.variant === 'hero'
           ? html`
               <div class="extra">
                 <slot name="extra"></slot>

src/banner/index.ts

@@ -1,14 +1,62 @@
-import { customElement } from "lit/decorators.js";
-import { Banner } from "./banner.js";
-import styles from "./banner.style.js";
+import { customElement } from 'lit/decorators.js';
+import { Banner } from './banner.js';
+import styles from './banner.style.js';
 
-@customElement("tap-banner")
+/**
+ * ### Example
+ *
+ * ##### Simple
+ *
+ * ```html
+ * <tap-banner heading="Welcome!" description="This is a banner."></tap-banner>
+ * ```
+ *
+ * ##### Hero Variant
+ *
+ * ```html
+ * <tap-banner variant="hero" heading="Hero Banner" description="This is a hero banner."></tap-banner>
+ * ```
+ *
+ * @summary Display a banner with optional heading, description, and action slot.
+ *
+ * @prop {`string`} [`heading`] - The heading text to display in the banner.
+ * @prop {`string`} [`description`] - The description text to display in the banner.
+ * @prop {`string`} [`image`] - The URL of the background image to display in the banner.
+ * @prop {`boolean`} [`full-width`=`false`] - Whether the banner should take the full width of its container.
+ * @prop {`'default'` \| `'hero'`} [`variant`=`'default'`] - The variant style of the banner.
+ * @prop {`string`} [`background-color`] - The background color of the banner.
+ * @prop {`string`} [`textColor`] - The text color of the banner.
+ *
+ * @csspart `banner` - The main banner element.
+ * @csspart `content` - The content container inside the banner.
+ * @csspart `action` - The action container inside the banner.
+ * @csspart `extra` - The extra slot container inside the hero variant.
+ *
+ * @cssprop [`--tap-sys-spacing-6`] - Spacing around the banner content.
+ * @cssprop [`--tap-banner-color-surface`] - Background color of the banner.
+ * @cssprop [`--tap-sys-radius-4`] - Border radius of the banner.
+ * @cssprop [`--tap-banner-background-image`] - Background image of the banner.
+ * @cssprop [`--tap-sys-spacing-4`] - Margin around the banner.
+ * @cssprop [`--tap-banner-color-content`] - Text color of the banner.
+ * @cssprop [`--tap-sys-typography-headline-xs-font`=`--tap-sys-font-family`] - Font family for the heading text.
+ * @cssprop [`--tap-sys-typography-headline-xs-height`] - Line height for the heading text.
+ * @cssprop [`--tap-sys-typography-headline-xs-size`] - Font size for the heading text.
+ * @cssprop [`--tap-sys-typography-headline-xs-weight`] - Font weight for the heading text.
+ * @cssprop [`--tap-sys-spacing-3`] - Margin below the heading text.
+ * @cssprop [`--tap-sys-typography-body-xs-font`] - Font family for the description text.
+ * @cssprop [`--tap-sys-typography-body-xs-height`] - Line height for the description text.
+ * @cssprop [`--tap-sys-typography-body-xs-size`] - Font size for the description text.
+ * @cssprop [`--tap-sys-typography-body-xs-weight`] - Font weight for the description text.
+ * @cssprop [`--tap-sys-spacing-5`] - Margin above the action slot.
+ * @cssprop [`--tap-sys-spacing-8`] - Minimum height of the extra slot in the hero variant.
+ */
+@customElement('tap-banner')
 export class TapBanner extends Banner {
   static readonly styles = [styles];
 }
 
 declare global {
   interface HTMLElementTagNameMap {
-    "tap-banner": TapBanner;
+    'tap-banner': TapBanner;
   }
 }