docs: add jsdoc

Tap30 · May 28, 2024 · b17bf3c · b17bf3c
1 parent df6a4b2
commit b17bf3c
Show file tree

Hide file tree

Showing 2 changed files with 95 additions and 29 deletions.
diff --git a/src/text-field/index.ts b/src/text-field/index.ts
@@ -2,6 +2,72 @@ import { customElement } from 'lit/decorators.js';
 import { TextField } from './text-field';
 import styles from './text-field.style';
 
+/**
+ * ### Example
+ *
+ *
+ * ##### Simple
+ *
+ * ```html
+ * <tap-text-field></tap-text-field>
+ * ```
+ *
+ * ##### With Label and Placeholder
+ *
+ * ```html
+ * <tap-text-field label="Name" placeholder="Enter your name"></tap-text-field>
+ * ```
+ *
+ * @summary A text field component.
+ *
+ * @prop {`string`} [`value`=`''`] - The value of the text field.
+ * @prop {`boolean`} [`disabled`=`false`] - Indicates whether the text field is disabled.
+ * @prop {`boolean`} [`error`=`false`] - Indicates whether the text field has an error.
+ * @prop {`string`} [`caption`=`''`] - The caption text for the text field.
+ * @prop {`string`} [`label`=`''`] - The label for the text field.
+ * @prop {`string`} [`name`=`''`] - The name of the text field.
+ * @prop {`string`} [`placeholder`=`''`] - The placeholder text for the text field.
+ * @prop {`string`} [`inputmode`=`''`] - The input mode for the text field.
+ * @prop {`string`} [`type`=`''`] - The type of the text field.
+ * @prop {`string`} [`autocomplete`=`''`] - The autocomplete attribute for the text field.
+ *
+ * @csspart [`field`] - The main container for the text field.
+ * @csspart [`label`] - The label for the text field.
+ * @csspart [`container`] - The container for the input and any leading/trailing elements.
+ * @csspart [`input`] - The input element.
+ * @csspart [`caption`] - The caption for the text field.
+ *
+ * @cssprop [`--tap-font-family`=`--tap-sys-font-family`] - The font family used in the text field.
+ * @cssprop [`--tap-text-field-field-gap`=`--tap-sys-spacing-4`] - The gap between the elements in the text field.
+ * @cssprop [`--tap-text-field-label-color`=`--tap-sys-color-content-primary`] - The color of the label.
+ * @cssprop [`--tap-text-field-label-line-height`=`--tap-sys-typography-label-sm-height`] - The line height of the label.
+ * @cssprop [`--tap-text-field-label-font-size`=`--tap-sys-typography-label-sm-size`] - The font size of the label.
+ * @cssprop [`--tap-text-field-label-font-weight`=`--tap-sys-typography-label-sm-weight`] - The font weight of the label.
+ * @cssprop [`--tap-text-field-caption-color`=`--tap-sys-color-content-tertiary`] - The color of the caption.
+ * @cssprop [`--tap-text-field-caption-line-height`=`--tap-sys-typography-body-sm-height`] - The line height of the caption.
+ * @cssprop [`--tap-text-field-caption-font-size`=`--tap-sys-typography-body-sm-size`] - The font size of the caption.
+ * @cssprop [`--tap-text-field-caption-font-weight`=`--tap-sys-typography-body-sm-weight`] - The font weight of the caption.
+ * @cssprop [`--tap-text-field-container-height`=`--tap-sys-spacing-11`] - The height of the container.
+ * @cssprop [`--tap-text-field-container-padding`=`--tap-sys-spacing-6`] - The padding inside the container.
+ * @cssprop [`--tap-text-field-container-gap`=`--tap-sys-spacing-4`] - The gap between elements in the container.
+ * @cssprop [`--tap-text-field-container-background-color`=`--tap-sys-color-surface-tertiary`] - The background color of the container.
+ * @cssprop [`--tap-text-field-container-border-radius`=`--tap-sys-radius-3`] - The border radius of the container.
+ * @cssprop [`--tap-text-field-focus-background-color`=`--tap-sys-color-surface-secondary`] - The background color of the container when focused.
+ * @cssprop [`--tap-text-field-focus-border-width`=`--tap-sys-color-border-inverse-primary`] - The border width of the container when focused.
+ * @cssprop [`--tap-text-field-input-color`=`--tap-sys-color-content-primary`] - The color of the input text.
+ * @cssprop [`--tap-text-field-input-line-height`=`--tap-sys-typography-body-md-height`] - The line height of the input text.
+ * @cssprop [`--tap-text-field-input-font-size`=`--tap-sys-typography-body-md-size`] - The font size of the input text.
+ * @cssprop [`--tap-text-field-input-font-weight`=`--tap-sys-typography-body-md-weight`] - The font weight of the input text.
+ * @cssprop [`--tap-text-field-input-placeholder-color`=`--tap-sys-color-content-tertiary`] - The color of the placeholder text.
+ * @cssprop [`--tap-text-field-input-placeholder-line-height`=`--tap-sys-typography-body-md-height`] - The line height of the placeholder text.
+ * @cssprop [`--tap-text-field-input-placeholder-font-size`=`--tap-sys-typography-body-md-size`] - The font size of the placeholder text.
+ * @cssprop [`--tap-text-field-input-placeholder-font-weight`=`--tap-sys-typography-body-md-weight`] - The font weight of the placeholder text.
+ * @cssprop [`--tap-text-field-error-caption-color`=`--tap-sys-color-content-negative`] - The color of the caption when there is an error.
+ * @cssprop [`--tap-text-field-error-container-background-color`=`--tap-sys-color-surface-negative-light`] - The background color of the container when there is an error.
+ * @cssprop [`--tap-text-field-error-container-border-color`=`--tap-sys-color-border-negative`] - The border color of the container when there is an error.
+ * @cssprop [`--tap-text-field-disabled-container-background-color`=`--tap-sys-color-surface-disabled`] - The background color of the container when disabled.
+ * @cssprop [`--tap-text-field-disabled-container-color`=`--tap-sys-color-content-disabled`] - The color of the text and elements when disabled.
+ */
 @customElement('tap-text-field')
 export class TapTextField extends TextField {
   static readonly styles = [styles];

diff --git a/src/text-field/text-field.style.ts b/src/text-field/text-field.style.ts
@@ -20,74 +20,74 @@ export default css`
     font-family: var(--tap-font-family, var(--tap-sys-font-family));
     display: flex;
     flex-direction: column;
-    gap: var(--tap-textfield-field-gap, var(--tap-sys-spacing-4));
+    gap: var(--tap-text-field-field-gap, var(--tap-sys-spacing-4));
   }
 
   .label {
     color: var(
-      --tap-textfield-label-color,
+      --tap-text-field-label-color,
       var(--tap-sys-color-content-primary)
     );
     line-height: var(
-      --tap-textfield-label-line-height,
+      --tap-text-field-label-line-height,
       var(--tap-sys-typography-label-sm-height)
     );
     font-size: var(
-      --tap-textfield-label-font-size,
+      --tap-text-field-label-font-size,
       var(--tap-sys-typography-label-sm-size)
     );
     font-weight: var(
-      --tap-textfield-label-font-weight,
+      --tap-text-field-label-font-weight,
       var(--tap-sys-typography-label-sm-weight)
     );
   }
 
   .caption {
     color: var(
-      --tap-textfield-caption-color,
+      --tap-text-field-caption-color,
       var(--tap-sys-color-content-tertiary)
     );
     line-height: var(
-      --tap-textfield-caption-line-height,
+      --tap-text-field-caption-line-height,
       var(--tap-sys-typography-body-sm-height)
     );
     font-size: var(
-      --tap-textfield-caption-font-size,
+      --tap-text-field-caption-font-size,
       var(--tap-sys-typography-body-sm-size)
     );
     font-weight: var(
-      --tap-textfield-caption-font-weight,
+      --tap-text-field-caption-font-weight,
       var(--tap-sys-typography-body-sm-weight)
     );
   }
 
   .container {
     /* FIXME: height of the input is 52px but we dont have 52px in our tokens */
-    height: var(--tap-textfield-container-height, var(--tap-sys-spacing-11));
-    padding: 0 var(--tap-textfield-container-padding, var(--tap-sys-spacing-6));
+    height: var(--tap-text-field-container-height, var(--tap-sys-spacing-11));
+    padding: 0 var(--tap-text-field-container-padding, var(--tap-sys-spacing-6));
     display: flex;
     align-items: center;
     justify-content: space-between;
-    gap: var(--tap-textfield-container-gap, var(--tap-sys-spacing-4));
+    gap: var(--tap-text-field-container-gap, var(--tap-sys-spacing-4));
     background-color: var(
-      --tap-textfield-container-background-color,
+      --tap-text-field-container-background-color,
       var(--tap-sys-color-surface-tertiary)
     );
     border-radius: var(
-      --tap-textfield-container-border-radius,
+      --tap-text-field-container-border-radius,
       var(--tap-sys-radius-3)
     );
     border: 2px solid transparent;
   }
 
   .container:focus-within {
     background-color: var(
-      --tap-textfield-focus-background-color,
+      --tap-text-field-focus-background-color,
       var(--tap-sys-color-surface-secondary)
     );
     border: 2px solid
       var(
-        --tap-textfield-focus-border-width,
+        --tap-text-field-focus-border-width,
         var(--tap-sys-color-border-inverse-primary)
       );
   }
@@ -98,65 +98,65 @@ export default css`
     flex: 1;
     background-color: transparent;
     color: var(
-      --tap-textfield-input-color,
+      --tap-text-field-input-color,
       var(--tap-sys-color-content-primary)
     );
     line-height: var(
-      --tap-textfield-input-line-height,
+      --tap-text-field-input-line-height,
       var(--tap-sys-typography-body-md-height)
     );
     font-size: var(
-      --tap-textfield-input-font-size,
+      --tap-text-field-input-font-size,
       var(--tap-sys-typography-body-md-size)
     );
     font-weight: var(
-      --tap-textfield-input-font-weight,
+      --tap-text-field-input-font-weight,
       var(--tap-sys-typography-body-md-weight)
     );
     font-family: inherit;
   }
 
   .input::placeholder {
     color: var(
-      --tap-textfield-input-placeholder-color,
+      --tap-text-field-input-placeholder-color,
       var(--tap-sys-color-content-tertiary)
     );
     line-height: var(
-      --tap-textfield-input-placeholder-line-height,
+      --tap-text-field-input-placeholder-line-height,
       var(--tap-sys-typography-body-md-height)
     );
     font-size: var(
-      --tap-textfield-input-placeholder-font-size,
+      --tap-text-field-input-placeholder-font-size,
       var(--tap-sys-typography-body-md-size)
     );
     font-weight: var(
-      --tap-textfield-input-placeholder-font-weight,
+      --tap-text-field-input-placeholder-font-weight,
       var(--tap-sys-typography-body-md-weight)
     );
     font-family: inherit;
   }
 
   :host([error]) .caption {
     color: var(
-      --tap-textfield-error-caption-color,
+      --tap-text-field-error-caption-color,
       var(--tap-sys-color-content-negative)
     );
   }
 
   :host([error]) .container {
     background-color: var(
-      --tap-textfield-error-container-background-color,
+      --tap-text-field-error-container-background-color,
       var(--tap-sys-color-surface-negative-light)
     );
     border-color: var(
-      --tap-textfield-error-container-border-color,
+      --tap-text-field-error-container-border-color,
       var(--tap-sys-color-border-negative)
     );
   }
 
   :host([disabled]) .container {
     background-color: var(
-      --tap-textfield-disabled-container-background-color,
+      --tap-text-field-disabled-container-background-color,
       var(--tap-sys-color-surface-disabled)
     );
   }
@@ -166,7 +166,7 @@ export default css`
   :host([disabled]) .input,
   :host([disabled]) .input::placeholder {
     color: var(
-      --tap-textfield-disabled-container-color,
+      --tap-text-field-disabled-container-color,
       var(--tap-sys-color-content-disabled)
     );
   }