Merge pull request #466 from Infineon/459-documentation-select

Documentation: select

packages/components/src/components/select/Usage.mdx

@@ -1,12 +1,123 @@
-import { Meta  } from '@storybook/blocks';
+import SelectComboBoxStates from '../../../public-storybook/images/select/select-combo-box-states.png';
+import SelectSizes from '../../../public-storybook/images/select/select-sizes.png';
+import SelectFieldAnatomy from '../../../public-storybook/images/select/select-field-anatomy.png';
+import SelectFieldMouseInteraction from '../../../public-storybook/images/select/select-field-mouse-interaction.png';
+import SelectSingleOptionsStates from '../../../public-storybook/images/select/select-single-options-states.png';
+import SelectSingleStates from '../../../public-storybook/images/select/select-single-states.png';
+import SelectMultiPartial from '../../../public-storybook/images/select/select-multi-partial.png';
+import SelectMultiOptionsStates from '../../../public-storybook/images/select/select-multi-options-states.png';
+import SelectMultiStates from '../../../public-storybook/images/select/select-multi-states.png';
 
 <Meta title="Components/Select/Usage" />
 
 
 # Select
+The select component provides users with the ability to choose one or multiple options from a predefined list in a dropdown format. It offers different variations, including select, multi select, and combo box, to cater to various selection needs.
 
 ## Usage
 
-### Single-select
+### When to use
+- When users need to choose one or multiple options from a predefined list, using a select field.
 
-### Multi-select
+### When not to use
+- When users want to navigate to a different page or section. Use a submenu component instead.
+- If you have large datasets it can become overwhelming. Instead use filter components or paginated table lists.
+
+## Select Field
+The select field looks similar to the text field, but has an icon on the right indicating a dropdown function.
+
+### Anatomy
+<img src={SelectFieldAnatomy} alt="Select Field Anatomy" />
+
+**Label (1)**\
+Use a label to describe the purpose of the select field to the user.
+
+
+**Required field (2)**\
+Mark a select field as required when the information is necessary for the user to proceed with a specific action, such as submitting a form. It is indicated with an asterisk (*) next to the label.
+
+
+**Field (3)**\
+The container where a user can click or tap.
+
+
+ **Dropdown Arrow (4)**\
+The dropdown arrow is a visual indicator (chevron-down), that appears on the right side of the select field. It suggests to users that they can click or tap on the field to reveal the available options. 
+
+
+**Icon (5)**\
+In some scenarios it can be useful to use an icon before the placeholder.
+
+
+**Placeholder text (6)**\
+Placeholder text is the text that is displayed inside the select field before the user select any option inside the menu. Use it to provide an example or to give users an idea of the type of information they can select.
+
+
+**Optional field (7)**\
+Mark a text field as optional when the information entered into the text field is not necessary for the user to proceed with a specific action.
+
+
+**Caption text (8)**\
+Use caption text to provide additional context or information about the select field. It can be used to provide examples or instructions for selecting an option. When the dropdown menu appears, the caption text is behind it.
+
+
+### Mouse interaction
+Users can interact with the Select Field in different ways. To open the dropdown list they can either click on the visible options or on the dropdown arrow. They can also click on the reset icon to reset the entries with one click. All options in the list will be unchecked.
+<img src={SelectFieldMouseInteraction} alt="Select Field Mouse Interaction" />
+
+## Variants
+
+### Single Select
+The single select variation allows users to choose only one option from a list of choices. The selected option is displayed within the closed select field.
+
+#### States
+<img src={SelectSingleStates} alt="Select Single States" />
+
+### Multi Select
+The multi select variation enables users to select multiple options simultaneously from a list of choices. It presents a dropdown menu with checkboxes next to each option. Users can make their selections by checking the desired options. The selected options are displayed within the closed select field.
+
+#### States
+<img src={SelectMultiStates} alt="Select Multi States" />
+
+### Combo Box
+The combo box variation combines a text field with a dropdown menu. Users can select options from the dropdown or input custom values in the text field. This variation is suitable when users may need to choose from existing options or provide their own input. Only one option can be selected.
+
+#### States
+<img src={SelectComboBoxStates} alt="Select Combo Box States" />
+
+## Select Option Items
+For the select field the are only two option items for the option list available.
+
+### Single Select
+When a user can choose only one option, a single select option item is the right one. By selecting an option, it is highlighted with our brand color and checkmark icon.
+
+> The same option items are also used for the Combo Box variant.
+
+#### States
+<img src={SelectSingleOptionsStates} alt="Select Single Options States" />
+
+### Multi Select
+When a user can choose multiple options, a multi select option item is the right one. Here the user is shown a list of checkboxes that he can select.
+
+#### States
+<img src={SelectMultiOptionsStates} alt="Select Multi Options States" />
+
+#### Partial Checkbox
+In the multi-select item there are two ways to show the user a list of checkboxes. Besides the simple one, you can also show a nested list. This can be, for example, a product family that contains several products. It is important that only the nested checkbox (level 2) is shown in the select field. The root checkbox (Level 1) is only used for orientation and is not displayed in the Select Field.
+<img src={SelectMultiPartial} alt="Select Multi Partial" />
+
+**Multi Select - Level 1 (1)**\
+Users can click this checkbox to select all child checkbox options at once. Alternatively, users can select individual child checkbox options. As long as not all child checkbox options are selected, the parent checkbox is displayed as partial.
+
+
+**Multi Select - Level 2 (2)**\
+Selected child options are also displayed in the select field and separated by a comma. Only as many options are displayed as space is available. All other options are truncated with ellipsis.
+
+## Size
+There are two select field sizes: 36px and 40px. This will give you more flexibility in structuring layouts due to e.g. different button heights. It's important to maintain uniform field height while combining form elements on a single page.
+<img src={SelectSizes} alt="Select Size" />
+
+
+***
+Check out the Figma component: **[Select](https://www.figma.com/file/zPvPwPgb4EsYFXKC2nhzSG/Infineon-DDS-%7C-Main?type=design&node-id=14251-8194&mode=design&t=UQ0Dm7ueLiXMURK1-4)**
+***

packages/components/src/components/select/multi-select/Development.mdx

@@ -0,0 +1,56 @@
+import { Meta, Primary, Controls, Canvas, Story } from '@storybook/blocks';
+import * as SelectStories from './multiselect.stories';
+
+<Meta of={SelectStories} />
+
+# Single Select
+
+<Canvas of={SelectStories.Default} sourceState="shown" />
+
+<Controls />
+
+
+## Stories
+
+### Default
+<Canvas of={SelectStories.Default} sourceState="shown" />
+
+
+
+## Notes
+The Multi Select component takes an array of objects in the following format as input:
+
+```
+const options = [{
+  value: "a",
+  label: "option a",
+  selected: false,
+  children: [
+    {
+      value: "a1",
+      label: "option a1",
+      selected: false
+    },
+    {
+      value: "a2",
+      label: "option a2",
+      selected: false
+    }
+  ]
+},
+{
+  value: "b",
+  label: "option b",
+  selected: false
+},
+{
+  value: "c",
+  label: "option c",
+  selected: false
+}];
+```
+
+The ``selected`` property can be used to predefine an option as selected. 
+(``selected: true``)
+This property is only changed, when a new option is selected, as the mutli-select only allows for one selected option.
+However, the component only creates a shallow copy of the input array, so the original input array does not change.

packages/components/src/components/select/multi-select/multiselect.stories.ts

@@ -31,7 +31,7 @@ const options = [{
 
 export default {
   title: 'Components/Select/Multi Select',
-  tags: ['autodocs'],
+  // tags: ['autodocs'],
   args: {
     size: "m",
     // max: 5,