From fda3cc31be3b42bece844ac84d1934413f397b49 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dan=20B=C3=BCschlen?= Date: Thu, 9 Nov 2023 17:18:00 +0100 Subject: [PATCH] docs(input): add story descriptions to the input component change @attr to @prop so that storybook displays the descriptions --- src/components/input/Input.js | 39 ++++++------ src/components/input/stories/input.stories.js | 61 ++++++++++++++++++- 2 files changed, 80 insertions(+), 20 deletions(-) diff --git a/src/components/input/Input.js b/src/components/input/Input.js index e1bcd34f..827e2f77 100644 --- a/src/components/input/Input.js +++ b/src/components/input/Input.js @@ -35,24 +35,27 @@ const VALIDATION_MESSAGES = { } /** - * @attr {boolean} disabled - Disables the input element. - * @attr {boolean} required - Marks the input element as required. - * @attr {boolean} clearable - Adds a button to clear the input element. - * @attr {string} value - The value of the input element. - * @attr {string} name - The name of the input element. - * @attr {string} label - The label of the input element. - * @attr {string} error - A custom error that is completely independent of the validity state. Useful for displaying server side errors. - * @attr {string} size - The size of the input element. - * @attr {string} icon - The icon that is displayed at the end of the input element. - * @attr {string} prefix - A prefix that relates to the value of the input (e.g. CHF). - * @attr {string} suffix - A suffix that relates to the value of the input (e.g. mm). - * @attr {string} pattern - A regular expression that the value is checked against. - * @attr {string} type - The type of the input element. - * @attr {string} min - The minimum value of the input element. - * @attr {string} max - The maximum value of the input element. - * @attr {string} minlength - The minimum length of the input element. - * @attr {string} maxlength - The maximum length of the input element. - * @attr {object} validationMessages - Custom validation messages. The key is the name of the validity state and the value is the message. + * A text input element. + * + * @prop {boolean} disabled - Disables the input element. + * @prop {boolean} required - Marks the input element as required. + * @prop {boolean} clearable - Adds a button to clear the input element. + * @prop {string} value - The value of the input element. + * @prop {string} name - The name of the input element. + * @prop {string} label - The label of the input element. + * @prop {string} error - A custom error that is completely independent of the validity state. Useful for displaying server side errors. + * @prop {string} size - The size of the input element. + * @prop {string} icon - The icon that is displayed at the end of the input element. + * @prop {string} prefix - A prefix that relates to the value of the input (e.g. CHF). + * @prop {string} suffix - A suffix that relates to the value of the input (e.g. mm). + * @prop {string} pattern - A regular expression that the value is checked against. + * @prop {string} type - The type of the input element. + * @prop {string} min - The minimum value of the input element. + * @prop {string} max - The maximum value of the input element. + * @prop {string} minlength - The minimum length of the input element. + * @prop {string} maxlength - The maximum length of the input element. + * @prop {object} validationMessages - Custom validation messages. The key is the name of the validity state and the value is the message. + * @prop {boolean} novalidate - Disables the browser's validation. * * @fires {CustomEvent} input - Dispatched when the value of the input element changes. * @fires {CustomEvent} change - Dispatched when the value of the input element changes and the input element loses focus. diff --git a/src/components/input/stories/input.stories.js b/src/components/input/stories/input.stories.js index 1e6935f5..e8b7bc7c 100644 --- a/src/components/input/stories/input.stories.js +++ b/src/components/input/stories/input.stories.js @@ -9,6 +9,7 @@ import { ICON_NAMES } from "../../icon/icon.js" export default { title: "Input", component: "leu-input", + tags: ["autodocs"], argTypes: { size: { control: { @@ -69,28 +70,59 @@ export const Regular = Template.bind({}) Regular.args = { label: "Vorname", } +Regular.parameters = { + docs: { + description: { + story: + "To render a basic input field only the `label` attribute is required. The `label` is necessary for accessibility reasons.", + }, + }, +} export const Filled = Template.bind({}) Filled.args = { label: "Name", value: "Andrea Hugentobler", } +Filled.parameters = { + docs: { + description: { + story: "To supply a value to the input field, use the `value` attribute.", + }, + }, +} export const PrefixedNumber = Template.bind({}) PrefixedNumber.args = { - label: "Preis", + label: "Preis, in CHF", prefix: "CHF", type: "number", } +PrefixedNumber.parameters = { + docs: { + description: { + story: + 'With the `prefix` attribute you can add a string that is prepended to the input field. This is useful for defining a unit of the input value. Be aware that the prefix is not included in the value of the input field. It is also hidden from screen readers. You have to add the prefix to the `label` attribute like "Preis, in CHF".', + }, + }, +} export const SuffixedNumber = Template.bind({}) SuffixedNumber.args = { - label: "Länge", + label: "Länge, in cm", suffix: "cm", type: "number", min: 90, max: 120, } +SuffixedNumber.parameters = { + docs: { + description: { + story: + 'With the `suffix` attribute you can add a string that is appended to the input field. This is useful for defining a unit of the input value. Be aware that the prefix is not included in the value of the input field. It is also hidden from screen readers. You have to add the suffix to the `label` attribute like "Länge, in cm".', + }, + }, +} export const Disabled = Template.bind({}) Disabled.args = { @@ -110,6 +142,14 @@ Clearable.args = { label: "Vorname", clearable: true, } +Clearable.parameters = { + docs: { + description: { + story: + "The `clearable` attribute adds a button to the input field that clears the value. This is useful for search fields. The button is only visible if the input field has a value. The button will also not visible if the input is invalid.", + }, + }, +} export const Search = Template.bind({}) Search.args = { @@ -117,6 +157,15 @@ Search.args = { clearable: true, size: SIZE_TYPES.SMALL, icon: "search", + novalidate: true, +} +Search.parameters = { + docs: { + description: { + story: + "The input field can also be displayed in a smaller size. Search fields or input fields inside other components (e.g. Select or Pagination) usually use this option. To display the search icon, use the `icon` attribute. With `novalidate` the validation can be disabled.", + }, + }, } export const CustomError = Template.bind({}) @@ -126,3 +175,11 @@ CustomError.args = { value: "example@domain.com", error: "Diese E-Mail Adresse wird bereits verwendet.", } +Search.parameters = { + docs: { + description: { + story: + "The input component uses the browsers native validation. If the data is sent to a server, then there it will be validated again. To display those errors, use the `error` attribute. It won't interfere with the native validation also wont be removed.", + }, + }, +}