From 36656face6237efbe8f8ac4d247e87830b9e3a80 Mon Sep 17 00:00:00 2001 From: flxlst09 <116285506+flxlst09@users.noreply.github.com> Date: Wed, 23 Oct 2024 13:48:20 +0200 Subject: [PATCH] docs(number-input): add guidelines (#1521) Co-authored-by: Daniel Leroux --- .../docs/controls/_number-input_code.mdx | 45 ++++++++++++++++ .../controls/_number-input_styleguide.mdx | 48 +++++++++++++++++ .../docs/controls/number-input.mdx | 51 ++++--------------- 3 files changed, 103 insertions(+), 41 deletions(-) create mode 100644 packages/documentation/docs/controls/_number-input_code.mdx create mode 100644 packages/documentation/docs/controls/_number-input_styleguide.mdx diff --git a/packages/documentation/docs/controls/_number-input_code.mdx b/packages/documentation/docs/controls/_number-input_code.mdx new file mode 100644 index 0000000000..20848d1db1 --- /dev/null +++ b/packages/documentation/docs/controls/_number-input_code.mdx @@ -0,0 +1,45 @@ +import Playground from '@site/src/components/PlaygroundV3'; +import Props from '@site/docs/auto-generated/ix-number-input/props.md'; +import Events from '@site/docs/auto-generated/ix-number-input/events.md'; + +# Number field + +## Examples + +### Basic + + + +### Disabled + + + +### Label + + + +### Readonly + + + +### StepperButton + + + +### Validation + + + +## API + +### Properties + + + +### Events + + diff --git a/packages/documentation/docs/controls/_number-input_styleguide.mdx b/packages/documentation/docs/controls/_number-input_styleguide.mdx new file mode 100644 index 0000000000..eb6f118eec --- /dev/null +++ b/packages/documentation/docs/controls/_number-input_styleguide.mdx @@ -0,0 +1,48 @@ +The number input component allows users to enter and adjust numerical values. It’s commonly used in forms, calculators, and other areas where precise numerical input is required. We typically use the number input component to ensure accurate and efficient data entry. + + +![Number input overview](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Pattern-Illustrations?node-id=3805-24565&t=DtCmoFcLwhf7ke3S-4) + +1. Label +2. Required field indicator +3. Value +4. Stepper buttons +5. Input field +6. Helper or feedback text + +## Options + +- **Label**: See [form field](./forms/forms-field.md) +- **Value**: See [form field](./forms/forms-field.md) +- **Required**: See [form field](./forms/forms-field.md) +- **Helper text**: See [form field](./forms/forms-field.md) +- **Feedback text**: See [form field](./forms/forms-field.md) +- **Show text as tooltip**: See [form field](./forms/forms-field.md) +- **Placeholder**: See [form field](./forms/forms-field.md) +- **Allowed characters pattern**: Specify the allowed characters for input. We typically use this to reject invalid characters, such as decimal points, by triggering a shaking animation immediately upon value change during typing. +- **Pattern**: Define the expected input using regular expressions, such as an integer between 1 and 100. We typically use this to validate the input when the user leaves the field or clicks submit. +- **Min/Max**: Specifies the minimum and maximum values that can be entered, ensuring the input stays within the defined range. We typically use this option to prevent invalid entries and guide users towards acceptable values. +- **Show stepper buttons**: Stepper buttons are optional controls used to increment or decrement the value, suitable for small ranges with few steps. We typically use these buttons when precise adjustments are needed, such as in quantity selectors, rating systems, or form inputs requiring fine-tuned numerical values. + +## Behavior in context +- **Interaction:** Users can type a value or use stepper buttons to adjust it. We typically recommend using stepper buttons, especially for touch interactions, to enhance usability and precision. +- **Validation:** See [form field](./forms/forms-validation.md) +- **Overflow:** Numbers are truncated to fit within the input field. Ensure that the expected value is visible in the input field so it can be properly displayed. +- **Alignment:** Number inputs are always aligned to the right. + +## States +The number input has five states: default, hover, focused, disabled and read-only. +![Number input states](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Pattern-Illustrations?node-id=4097-1041&t=lGjPn4Q9U7Fa81TI-4) + +## Dos and Don’ts +- Do set appropriate min and max values to prevent invalid entries and guide user input +- Do provide clear error messages when the input value is out of the allowed range or doesn’t match the required pattern +- Do consider special cases such as zero, negative numbers, and very large numbers to ensure all possible inputs are handled correctly +- Don't specify patterns that do not align with your use case, e.g. inappropriate interval between valid values + +## Related patterns +- [Form fields](./forms/forms-field.md) +- [Validation](./forms/forms-validation.md) +- [Layout](./forms/forms-layout.md) +- [Input](./input.mdx) +- [Select](./select.mdx) diff --git a/packages/documentation/docs/controls/number-input.mdx b/packages/documentation/docs/controls/number-input.mdx index 5238cc3828..2ec24f1298 100644 --- a/packages/documentation/docs/controls/number-input.mdx +++ b/packages/documentation/docs/controls/number-input.mdx @@ -1,48 +1,17 @@ -import Playground from '@site/src/components/PlaygroundV2'; -import Props from '@site/docs/auto-generated/ix-number-input/props.md'; -import Events from '@site/docs/auto-generated/ix-number-input/events.md'; +import LinkableDocsTabs from '@site/src/components/LinkableDocsTabs'; + +import DocsUx from './_number-input_styleguide.mdx'; +import DocsCode from './_number-input_code.mdx'; import Tags from '@site/docs/auto-generated/ix-number-input/tags.md'; # Number input -## Examples - -### Basic - - - -### Disabled - - - -### Label - - - -### Readonly - - - -### StepperButton - - - -### Validation - - - -## API - -### Properties - - - -### Events +
+
- + + + +