Merge pull request #115 from amir78729/docs/jsdoc/toast

docs: add JSDoc to `toast` component
Tap30 · May 28, 2024 · 26ee838 · 26ee838
2 parents 0d4817e + 997c232
commit 26ee838
Show file tree

Hide file tree

Showing 4 changed files with 233 additions and 76 deletions.
diff --git a/src/toast/index.ts b/src/toast/index.ts
@@ -1,15 +1,64 @@
-import { customElement } from "lit/decorators.js";
-import { Toast } from "./toast";
-import styles from "./toast.style";
-import { LitElement, html } from "lit";
+import { customElement } from 'lit/decorators.js';
+import { Toast } from './toast';
+import styles from './toast.style';
 
-@customElement("tap-toast")
+/**
+ * ### Example
+ *
+ *
+ * ##### Simple
+ *
+ * ```html
+ * <tap-toast>Message</tap-toast>
+ * ```
+ *
+ * ##### Success Variant
+ *
+ * ```html
+ * <tap-toast variant="success">Success message</tap-toast>
+ * ```
+ *
+ * ##### With Dismiss Button
+ *
+ * ```html
+ * <tap-toast show-dismiss-button>Message with dismiss</tap-toast>
+ * ```
+ *
+ * @summary A toast notification component.
+ *
+ * @prop {`boolean`} [`show-dismiss-button`=`false`] - Indicates whether to show the dismiss button.
+ * @prop {`'success'` \| `'error'` \| `'info'` \| `'warning'` \| `'inverse'`} [`variant`=`'inverse'`] - The variant of the toast notification. Defaults to `inverse`.
+ *
+ * @csspart [`toast`] - The main container for the toast notification.
+ * @csspart [`icon`] - The container for the icon.
+ * @csspart [`message`] - The container for the message.
+ * @csspart [`dismiss`] - The container for the dismiss button.
+ *
+ * @cssprop [`--tap-toast-vertical-padding`=`--tap-sys-spacing-5`] - The vertical padding inside the toast.
+ * @cssprop [`--tap-toast-horizontal-padding`=`--tap-sys-spacing-5`] - The horizontal padding inside the toast.
+ * @cssprop [`--tap-toast-background-color-default`=`--tap-sys-color-surface-inverse-secondary`] - The default background color of the toast.
+ * @cssprop [`--tap-toast-color-default`=`--tap-sys-color-content-on-inverse`] - The default text color of the toast.
+ * @cssprop [`--tap-toast-background-color-success`=`--tap-sys-color-surface-positive`] - The background color of the success variant.
+ * @cssprop [`--tap-toast-color-success`=`--tap-sys-color-content-on-inverse`] - The text color of the success variant.
+ * @cssprop [`--tap-toast-background-color-error`=`--tap-sys-color-surface-negative`] - The background color of the error variant.
+ * @cssprop [`--tap-toast-color-error`=`--tap-sys-color-content-on-inverse`] - The text color of the error variant.
+ * @cssprop [`--tap-toast-background-color-info`=`--tap-sys-color-surface-accent`] - The background color of the info variant.
+ * @cssprop [`--tap-toast-color-info`=`--tap-sys-color-content-on-inverse`] - The text color of the info variant.
+ * @cssprop [`--tap-toast-background-color-warning`=`--tap-sys-color-surface-warning`] - The background color of the warning variant.
+ * @cssprop [`--tap-toast-color-warning`=`--tap-sys-color-content-primary`] - The text color of the warning variant.
+ * @cssprop [`--tap-toast-background-color-inverse`=`--tap-sys-color-surface-inverse-secondary`] - The background color of the inverse variant.
+ * @cssprop [`--tap-toast-color-inverse`=`--tap-sys-color-content-on-inverse`] - The text color of the inverse variant.
+ * @cssprop [`--tap-toast-dismiss-color`=`'inherit'`] - The color of the dismiss button.
+ * @cssprop [`--tap-toast-dismiss-background-color`=`transparent`] - The background color of the dismiss button.
+ *
+ */
+@customElement('tap-toast')
 export class TapToast extends Toast {
   static readonly styles = [styles];
 }
 
 declare global {
   interface HTMLElementTagNameMap {
-    "tap-toast": TapToast;
+    'tap-toast': TapToast;
   }
 }
diff --git a/src/toast/toast.stories.ts b/src/toast/toast.stories.ts
@@ -1,26 +1,32 @@
-import {html, TemplateResult} from "lit";
-import "./index.js";
-import "../button";
+import { html, TemplateResult } from 'lit';
+import './index.js';
+import '../button';
 
-const toastVariants: string[] = ["success", "error", "info", "inverse", "warning"]
+const toastVariants: string[] = [
+  'success',
+  'error',
+  'info',
+  'inverse',
+  'warning',
+];
 
 export default {
-  title: "Toast",
-  component: "tap-toast",
+  title: 'Toast',
+  component: 'tap-toast',
   argTypes: {
     toastContent: {
-      control: "text",
-      description: "Toast Content",
+      control: 'text',
+      description: 'Toast Content',
     },
     variant: {
       options: toastVariants,
-      control: { type: "inline-radio" },
-      description: "The toast variant",
+      control: { type: 'inline-radio' },
+      description: 'The toast variant',
       defaultValue: `"inverse"`,
     },
     showDismissButton: {
-      description: "Should the Dismiss button be visible?",
-      control: { type: "boolean" },
+      description: 'Should the Dismiss button be visible?',
+      control: { type: 'boolean' },
       defaultValue: false,
     },
   },
@@ -33,22 +39,21 @@ interface Story<T> {
 }
 
 const defaultProps = {
-  toastContent: "toast text goes here!",
+  toastContent: 'toast text goes here!',
   showDismissButton: false,
 };
 
 interface ArgTypes {
-  toastContent: string,
-  variant?: 'success' | 'error' | 'info' | 'warning' | 'inverse',
-  showDismissButton?: boolean,
+  toastContent: string;
+  variant?: 'success' | 'error' | 'info' | 'warning' | 'inverse';
+  showDismissButton?: boolean;
 }
 
 const Template: Story<ArgTypes> = ({
   variant,
   toastContent,
   showDismissButton,
 }) => {
-
   document.addEventListener('DOMContentLoaded', () => {
     const toastElement = document.getElementById('toast-story');
     toastElement?.addEventListener('dismiss', () => {
@@ -69,22 +74,22 @@ const Template: Story<ArgTypes> = ({
 
 const VariantTemplate: Story<{}> = () => {
   return html`
-    ${toastVariants.map((variant) => html`
-      <tap-toast variant=${variant}>${variant}</tap-toast>
-    `)}
+    ${toastVariants.map(
+      (variant) => html` <tap-toast variant=${variant}>${variant}</tap-toast> `,
+    )}
   `;
 };
 
 export const Simple = Template.bind({});
 Simple.args = {
-  toastContent: "a simple toast",
+  toastContent: 'a simple toast',
 };
 
 export const Variants = VariantTemplate.bind({});
 Variants.args = {};
 
 export const DismissButton = Template.bind({});
 DismissButton.args = {
-  toastContent: "A toast with dismiss button",
+  toastContent: 'A toast with dismiss button',
   showDismissButton: true,
 };
diff --git a/src/toast/toast.style.ts b/src/toast/toast.style.ts
@@ -1,4 +1,4 @@
-import { css } from "lit";
+import { css } from 'lit';
 
 export default css`
   :host {
@@ -37,9 +37,16 @@ export default css`
     width: 100%;
     font-family: var(--tap-font-family, var(--tap-sys-font-family));
     border-radius: 999px;
-    padding: var(--tap-toast-vertical-padding, var(--tap-sys-spacing-5)) var(--tap-toast-horizontal-padding, var(--tap-sys-spacing-5));
-    background-color: var(--tap-toast-background-color-default, var(--tap-sys-color-surface-inverse-secondary));
-    color: var(--tap-toast-color-default, var(--tap-sys-color-content-on-inverse));
+    padding: var(--tap-toast-vertical-padding, var(--tap-sys-spacing-5))
+      var(--tap-toast-horizontal-padding, var(--tap-sys-spacing-5));
+    background-color: var(
+      --tap-toast-background-color-default,
+      var(--tap-sys-color-surface-inverse-secondary)
+    );
+    color: var(
+      --tap-toast-color-default,
+      var(--tap-sys-color-content-on-inverse)
+    );
   }
 
   :host .icon {
@@ -48,24 +55,48 @@ export default css`
     justify-content: center;
   }
 
-  :host([variant="success"]) .toast {
-    background-color: var(--tap-toast-background-color-success, var(--tap-sys-color-surface-positive));
-    color: var(--tap-toast-color-success, var(--tap-sys-color-content-on-inverse));
+  :host([variant='success']) .toast {
+    background-color: var(
+      --tap-toast-background-color-success,
+      var(--tap-sys-color-surface-positive)
+    );
+    color: var(
+      --tap-toast-color-success,
+      var(--tap-sys-color-content-on-inverse)
+    );
   }
-  :host([variant="error"]) .toast {
-    background-color: var(--tap-toast-background-color-error, var(--tap-sys-color-surface-negative));
-    color: var(--tap-toast-color-error, var(--tap-sys-color-content-on-inverse));
+  :host([variant='error']) .toast {
+    background-color: var(
+      --tap-toast-background-color-error,
+      var(--tap-sys-color-surface-negative)
+    );
+    color: var(
+      --tap-toast-color-error,
+      var(--tap-sys-color-content-on-inverse)
+    );
   }
-  :host([variant="info"]) .toast {
-    background-color: var(--tap-toast-background-color-info, var(--tap-sys-color-surface-accent));
+  :host([variant='info']) .toast {
+    background-color: var(
+      --tap-toast-background-color-info,
+      var(--tap-sys-color-surface-accent)
+    );
     color: var(--tap-toast-color-info, var(--tap-sys-color-content-on-inverse));
   }
-  :host([variant="inverse"]) .toast {
-    background-color: var(--tap-toast-background-color-inverse, var(--tap-sys-color-surface-inverse-secondary));
-    color: var(--tap-toast-color-inverse, var(--tap-sys-color-content-on-inverse));
+  :host([variant='inverse']) .toast {
+    background-color: var(
+      --tap-toast-background-color-inverse,
+      var(--tap-sys-color-surface-inverse-secondary)
+    );
+    color: var(
+      --tap-toast-color-inverse,
+      var(--tap-sys-color-content-on-inverse)
+    );
   }
-  :host([variant="warning"]) .toast {
-    background-color: var(--tap-toast-background-color-warning, var(--tap-sys-color-surface-warning));
+  :host([variant='warning']) .toast {
+    background-color: var(
+      --tap-toast-background-color-warning,
+      var(--tap-sys-color-surface-warning)
+    );
     color: var(--tap-toast-color-warning, var(--tap-sys-color-content-primary));
   }
 
@@ -95,4 +126,3 @@ export default css`
     gap: inherit;
   }
 `;
-