diff --git a/src/components/controls/TextInput/README.md b/src/components/controls/TextInput/README.md index 0a0fbce8ad..fac5ccacdd 100644 --- a/src/components/controls/TextInput/README.md +++ b/src/components/controls/TextInput/README.md @@ -1,31 +1,266 @@ -| Property | Type | Default | Description | -| :----------- | :-------------------------------------------- | :-------------- | :----------------------------------------------------------------------------------------------------------------------- | -| autoComplete | `boolean \| string` | `-` | The control's `autocomplete` attribute | -| autoFocus | `boolean` | `-` | The control's `autofocus` attribute | -| className | `string` | `-` | The control's wrapper class name | -| controlProps | `React.InputHTMLAttributes` | `-` | The control's html attributes | -| controlRef | `React.Ref` | `-` | React ref provided to the control | -| defaultValue | `string` | `-` | The control's default value. Use when the component is not controlled | -| disabled | `boolean` | `false` | Indicates that the user cannot interact with the control | -| error | `boolean \| string` | `-` | Shows error state and optional message if property identified as a string | -| hasClear | `boolean` | `false` | Shows icon for clearing control's value | -| id | `string` | `-` | The control's `id` attribute | -| label | `string` | `-` | Help text rendered to the left of the input node | -| leftContent | `React.ReactNode` | `-` | User`s node rendered before label and input | -| name | `string` | `-` | The control's `name` attribute. Will be autogenerated if not specified | -| onBlur | `function` | `-` | Fires when the control lost focus. Provides focus event as an callback's argument | -| onChange | `function` | `-` | Fires when the input’s value is changed by the user. Provides change event as an callback's argument | -| onFocus | `function` | `-` | Fires when the control gets focus. Provides focus event as an callback's argument | -| onKeyDown | `function` | `-` | Fires when a key is pressed. Provides keyboard event as an callback's argument | -| onKeyUp | `function` | `-` | Fires when a key is released. Provides keyboard event as an callback's argument | -| onUpdate | `function` | `-` | Fires when the input’s value is changed by the user. Provides new value as an callback's argument | -| pin | `string` | `'round-round'` | The control's border view. `'round-round'` by default | -| placeholder | `string` | `-` | Text that appears in the control when it has no value set | -| qa | `string` | `-` | Test id attribute (`data-qa`) | -| rightContent | `React.ReactNode` | `-` | User`s node rendered after input node and clear button | -| size | `'s' \| 'm' \| 'l' \| 'xl'` | `'m'` | The control's size. `'m'` by default | -| tabIndex | `string` | `-` | The control's `tabindex` attribute | -| type | `string` | `-` | The control's type | -| value | `string` | `-` | The control's value | -| view | `'normal' \| 'clear'` | `'normal'` | The control's view. `'normal'` by default | -| note | `React.ReactNode` | `-` | An optional element displayed under the lower right corner of the control and sharing the place with the error container | + + +# TextInput + + + +```tsx +import {TextInput} from '@gravity-ui/uikit'; +``` + +## Description + +TextInput allow users to enter text into a UI. + +## Appearance + +The TextInput's appearance is controlled by the `view` and `pin` properties. + +### View + +`normal` - this is the main view of TextInput (used by default). + + + +`clear` - this view could be used in case of using custom wrapper for TextInput. + + + + + +```tsx + + +``` + + + +### Pin + +Allows you to control view of right and left edges of TextInput's border. + + + + + +```tsx + + + +``` + + + +## States + +### Disabled + +The state of the TextInput where you don't want the user to be able to interact with the component. + + + + + +```tsx + +``` + + + +### Error + +The state of the TextInput at which you want to show incorrect user input. + + + + + +```tsx + +``` + + + +## Size + +`s` – Used when standard controls are too big (tables, small cards). + +`m` – Basic size, used in most components. + +`l` – Basic controls performed in a page's header, modal windows, or pop-ups. + +`xl` – Used on promo and landing pages. + + + + + +```tsx + + + + +``` + + + +## Label + +Allows you to set the label to the left of control. + +- label occupies the leftmost position relative to the control. That is, the elements added via `leftContent` property will be located to the right. +- label can take up no more than half the width of the entire TextInput's space. + + + + + +```tsx + +``` + + + +## Additional content + +### Left content + +Allows you to add content to the left of the control. Located to the right of the label added via `label` property. + + + + + +```tsx +Left} /> +``` + + + +### Right content + +Allows you to add content to the right of the control. Located to the right of the clear button added via `hasClear` property. + + + + + +```tsx +Right} /> +``` + + + +## Properties + +| Property | Description | Type | Default | +| :----------- | :----------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------- | :-------------- | +| autoComplete | The control's `autocomplete` attribute | `boolean \| string` | | +| autoFocus | The control's `autofocus` attribute | `boolean` | | +| className | The control's wrapper class name | `string` | | +| controlProps | The control's html attributes | `React.InputHTMLAttributes` | | +| controlRef | React ref provided to the control | `React.Ref` | | +| defaultValue | The control's default value. Use when the component is not controlled | `string` | | +| disabled | Indicates that the user cannot interact with the control | `boolean` | `false` | +| error | Shows error state and optional message if property identified as a string | `boolean \| string` | | +| hasClear | Shows icon for clearing control's value | `boolean` | `false` | +| id | The control's `id` attribute | `string` | | +| label | Help text rendered to the left of the input node | `string` | | +| leftContent | User`s node rendered before label and input | `React.ReactNode` | | +| name | The control's `name` attribute. Will be autogenerated if not specified | `string` | | +| onBlur | Fires when the control lost focus. Provides focus event as an callback's argument | `function` | | +| onChange | Fires when the input’s value is changed by the user. Provides change event as an callback's argument | `function` | | +| onFocus | Fires when the control gets focus. Provides focus event as an callback's argument | `function` | | +| onKeyDown | Fires when a key is pressed. Provides keyboard event as an callback's argument | `function` | | +| onKeyUp | Fires when a key is released. Provides keyboard event as an callback's argument | `function` | | +| onUpdate | Fires when the input’s value is changed by the user. Provides new value as an callback's argument | `function` | | +| pin | The control's border view. `'round-round'` by default | `string` | `'round-round'` | +| placeholder | Text that appears in the control when it has no value set | `string` | | +| qa | Test id attribute (`data-qa`) | `string` | | +| rightContent | User`s node rendered after input node and clear button | `React.ReactNode` | | +| size | The control's size. `'m'` by default | `'s' \| 'm' \| 'l' \| 'xl'` | `'m'` | +| tabIndex | The control's `tabindex` attribute | `string` | | +| type | The control's type | `string` | | +| value | The control's value | `string` | | +| view | The control's view. `'normal'` by default | `'normal' \| 'clear'` | `'normal'` | +| note | An optional element displayed under the lower right corner of the control and sharing the place with the error container | `React.ReactNode` | |