Merge pull request #108 from amir78729/docs/jsdoc/modal

docs: add JSDoc to `modal` component

Author: amir78729

src/modal/index.ts

@@ -1,14 +1,43 @@
-import { customElement } from "lit/decorators.js";
-import { Modal } from "./modal";
-import styles from "./modal.style";
+import { customElement } from 'lit/decorators.js';
+import { Modal } from './modal';
+import styles from './modal.style';
 
-@customElement("tap-modal")
+/**
+ * ### Example
+ *
+ *
+ * ##### Simple
+ *
+ * ```html
+ * <tap-modal></tap-modal>
+ * ```
+ *
+ * ##### Open Modal
+ *
+ * ```html
+ * <tap-modal open></tap-modal>
+ * ```
+ *
+ * @summary A modal dialog component.
+ *
+ * @prop {`boolean`} [`open`=`false`] - Indicates whether the modal is open.
+ *
+ * @csspart [`overlay`] - The overlay background when the modal is open.
+ * @csspart [`dialog`] - The main container for the modal dialog.
+ *
+ * @cssprop [`--tap-dialog-color-surface-overlay`=`--tap-sys-color-surface-overlay-dark`] - The background color of the overlay.
+ * @cssprop [`--tap-dialog-color-surface-primary`=`--tap-sys-color-surface-primary`] - The background color of the modal dialog.
+ * @cssprop [`--tap-dialog-padding`=`--tap-sys-spacing-6`] - The padding inside the modal dialog.
+ * @cssprop [`--tap-dialog-radius`=`--tap-sys-radius-6`] - The border radius of the modal dialog.
+ *
+ */
+@customElement('tap-modal')
 export class TapModal extends Modal {
   static readonly styles = [styles];
 }
 
 declare global {
   interface HTMLElementTagNameMap {
-    "tap-modal": TapModal;
+    'tap-modal': TapModal;
   }
-}
+}

src/modal/modal.stories.ts

@@ -1,11 +1,11 @@
-import { html, TemplateResult } from "lit";
-import "./index.js";
+import { html, TemplateResult } from 'lit';
+import './index.js';
 
 export default {
-  title: "Modal",
-  component: "tap-modal",
+  title: 'Modal',
+  component: 'tap-modal',
   argTypes: {
-    open: { control: "boolean" },
+    open: { control: 'boolean' },
   },
 };
 

src/modal/modal.style.ts

@@ -1,4 +1,4 @@
-import { css } from "lit";
+import { css } from 'lit';
 
 // tokens
 // --tap-dialog-color-surface-overlay
@@ -31,9 +31,9 @@ export default css`
   }
   .dialog {
     position: fixed;
-    left: var(--tap-sys-spacing-6);
-    right: var(--tap-sys-spacing-6);
-    bottom: var(--tap-sys-spacing-6);
+    left: var(--tap-dialog-left, var(--tap-sys-spacing-6));
+    right: var(--tap-dialog-right, var(--tap-sys-spacing-6));
+    bottom: var(--tap-dialog-bottom, var(--tap-sys-spacing-6));
     background-color: var(
       --tap-dialog-color-surface-primary,
       var(--tap-sys-color-surface-primary)

src/modal/modal.ts

@@ -1,5 +1,5 @@
-import { LitElement, PropertyValues, html, nothing } from "lit";
-import { property, query } from "lit/decorators.js";
+import { LitElement, PropertyValues, html, nothing } from 'lit';
+import { property, query } from 'lit/decorators.js';
 
 export class Modal extends LitElement implements HTMLDialogElement {
   static readonly shadowRootOptions = {
@@ -10,13 +10,13 @@ export class Modal extends LitElement implements HTMLDialogElement {
   @property({ type: Boolean, reflect: true })
   open: boolean = false;
 
-  @query("#dialog")
+  @query('#dialog')
   private dialog?: HTMLElement | null;
 
-  @query("#overlay")
+  @query('#overlay')
   private overlay?: HTMLElement | null;
 
-  returnValue: string = "";
+  returnValue: string = '';
 
   constructor() {
     super();
@@ -27,12 +27,12 @@ export class Modal extends LitElement implements HTMLDialogElement {
 
   connectedCallback() {
     super.connectedCallback();
-    this.addEventListener("keydown", this.handleKeydown);
-    this.addEventListener("click", this.handleClick);
+    this.addEventListener('keydown', this.handleKeydown);
+    this.addEventListener('click', this.handleClick);
   }
 
   protected updated(changed: PropertyValues): void {
-    const oldValue = changed.get("open");
+    const oldValue = changed.get('open');
     const newValue = this.open;
     const openChanged = oldValue !== undefined && oldValue !== newValue;
 
@@ -41,19 +41,19 @@ export class Modal extends LitElement implements HTMLDialogElement {
         this.dialog?.focus();
 
         this.dispatchEvent(
-          new Event("open", {
+          new Event('open', {
             bubbles: true,
             composed: true,
             cancelable: true,
-          })
+          }),
         );
       } else {
         this.dispatchEvent(
-          new Event("close", {
+          new Event('close', {
             bubbles: true,
             composed: true,
             cancelable: true,
-          })
+          }),
         );
       }
     }
@@ -72,7 +72,7 @@ export class Modal extends LitElement implements HTMLDialogElement {
 
   private handleKeydown(event: KeyboardEvent) {
     // TODO: handle `Tab`, `Shift + Tab`.
-    if (["Escape", "Esc"].includes(event.key)) {
+    if (['Escape', 'Esc'].includes(event.key)) {
       this.close();
     }
   }