From b17bf3c8f41c0c4d5776dea3914a64abd53594dd Mon Sep 17 00:00:00 2001 From: Amir Hossein Alibakhshi Date: Tue, 28 May 2024 16:59:00 +0330 Subject: [PATCH] docs: add jsdoc --- src/text-field/index.ts | 66 ++++++++++++++++++++++++++++++ src/text-field/text-field.style.ts | 58 +++++++++++++------------- 2 files changed, 95 insertions(+), 29 deletions(-) diff --git a/src/text-field/index.ts b/src/text-field/index.ts index 0910cdd4..4b063500 100644 --- 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 + * + * ``` + * + * ##### With Label and Placeholder + * + * ```html + * + * ``` + * + * @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 index 9045c746..57ef166b 100644 --- a/src/text-field/text-field.style.ts +++ b/src/text-field/text-field.style.ts @@ -20,61 +20,61 @@ 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; @@ -82,12 +82,12 @@ export default css` .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,19 +98,19 @@ 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; @@ -118,19 +118,19 @@ export default css` .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; @@ -138,25 +138,25 @@ export default css` :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) ); }