wix-style-react

As a discussion resulting from [this Issue](https://github.com/wix/wix-style-react/issues/2559)... # New API When this prop is passed, the component will have a new callback API. - The `onSelect` will behave differently. - `onManuallyInput` will NOT be called. - Paste logic will change ## Internal Actions These are internal actions which can be performed by the user: - Submit: Submits the current input value. Calls `onManuallyInput` (if non empty after triming) - Select: Selects the marked option (if there is one) - Cancel: Clears the input, and closes options. ### Tag Mode > This is not the 'mode' prop. The `mode` prop only sets the input's `read-only` attribute. - **Input** - Allow entering new tags (Suggestions) - **Select** - Only selection from a list (no new tags) ### User Actions -> Internal Actions | User Action | Tag Mode |Input State | Marked Option |Internal Action | |-----------------------------|--------|--------------|---------------|----------------| | Click on option | |* | * | Select | | Paste | Input |* | * | Submit | | Paste (TBD) | Select | Single value | * | Only paste text (no submit) | | Paste (TBD) | Select | Delimited values | * | Only paste text (no submit) | | Enter, Tab | |non-empty | exists | Select | | Enter, Delimiter, Tab | |non-empty | none | Submit | | Enter, Tab | |empty | exists | Select | | Tab | |empty | none | Step Out | | Esc | |* | * | Cancel | | COS, Blur | |* | * | Cancel , Close Options | > COS : Click Out Side ### Internal Actions | Action | Action Side-effects | |--------|----------------| | Select | Clear input | | Cancel | Clear input | | Submit | Clear input | ## Props | propName | propType | defaultValue | isRequired | description | |----------|----------|--------------|------------|-------------| | onMnuallyInput | function | | | A callback which is called when the user performs a Submit action. Submit action triggers are: "Enter", "Tab", [typing any defined delimiter], Paste action. Callback receives a single argument `Array<string>` which is a result of splitting the value by the given `delimiters` prop (and trimming each part)| | markFirstMatchingOption | boolean | false | | When true then when typing, the first matching option will be "marked", so that pressing "Enter" will select it.| | onSelect | function | | |`onSelect` will be called ONLY when a user clicks on an option from the options list. It receives an `Array<object>` of newly selected options (usually one). Each object is the original option, excluding the `value` property. (`value` property should be used for rendering the option only)| ### markFirstMatchingOption (new prop) For example, when there is an `Alabama` option, and the input contains `Alab`, the options is showing the `Alabama` option. - `markFirstMatchingOption === false` (default) : No option will be marked, "Enter" submits (calls `onManuallyInput`) the input value. (The user can navigate to the options) - `markFirstMatchingOption === true` : The first matching option is marked (like hovered), "Enter" selects it. > When `preferOption===true` then it is not possible to enter a new Tag which is a prefix of an existing option vlaue. > `markFirstMatchingOption === true` is not implemented yet. ### onSelect (Changes) Current `onSelect` argument is a mess ! The main change we want to make is that we won't try to create a tag ourselves, we just pass the originla option, and the consumer will decide how to created a tag from it. #### The Current `onSelect` Behavior |#| Original Option | Option in onSelect | |-|-----------------|--------------------| |1|`{ id: 'Alabama', value: 'Alabama', tag: { label: 'Alabama' } }` |`{ id: 'Alabama', label: 'Alabama' }` | |2|`{ id: 'Alaska', value: 'Alaska' }` | `{ id: 'Alaska', label: React.Element, theme: undefined }` | |3|`{ id: 'Arkansas', value: <span>Arkansas</span> }` | `{ id: 'Arkansas', label: React.Element, theme: undefined }` | |4|`{ id: 'California', value: 'California', code: 'CA' }` | `{ id: 'California', label: React.Element, theme: undefined }`| - Notice that in case 4, the `code` property is not available. #### The New `onSelect` Behavior We want to pass the original option, excluding the `value` prop. > The `value` prop is (should be) used ONLY for rendering the option ! The consumer doesn't need it upon selection. |#| Original Option | Option in onSelect | |-|-----------------|--------------------| |1|`{ id: 'Alabama', value: 'Alabama' }` |`{ id: 'Alabama' }` | |2|`{ id: 'Arkansas', value: <span>Arkansas</span> }` | `{ id: 'Arkansas' }` | |3|`{ id: 'California', value: 'California', code: 'CA' }` | `{ id: 'California', code: 'CA'}`| > If the consumer wants, they can put a `tag` property on the option (which is opaque to MultiSelect), and use it upon selection to add to the tags. ### Paste logic - Paste will automatically submit (call `onManuallyInput`). - Paste will automatically clear the input. ## Callback Summary ### `markFirstMatchingOption === false` |#| Options | Action | onSelect | onManuallyInput | |---|-------|----------------------|----------------|------------------| |1 | - | T&E(foo) | | [foo] | |2 | | T&E(alabama) | | [alabama] | |3 | | T&E(alab) | | [alab] | |4 | | T&E(foo) | | [foo] | |5 | - | Paste(foo) | | [foo] | |6 | | Paste(alabama) | | [alabama] | |7 | | Paste(foo) | | [foo] | |8 | | Paste(alab) | | [alab] | |9 | | Paste(alabama,alaska)| | [alabama,alaska] | |10 | | Paste(alabama,alas) | | [alabama,alas] | > Options: > - `-` means there is no options. Otherwise the options includes `[alabama,alaska]` > Actions: > - T&E: Type and press Enter ### `markFirstMatchingOption === true` |#| Options | Action | onSelect | onManuallyInput | |---|-------|----------------------|----------------|------------------| |1 | - | T&E(foo) | | [foo] | |2 | | T&E(alabama) | [{...alabama}] | | |3 | | T&E(alab) | [{...alabama}] | | |4 | | T&E(foo) | | [foo] | |5 | - | Paste(foo) | | [foo] | |6 | | Paste(alabama) | | [alabama] | |7 | | Paste(foo) | | [foo] | |8 | | Paste(alab) | | [alab] | |9 | | Paste(alabama,alaska)| | [alabama,alaska] | |10 | | Paste(alabama,alas) | | [alabama,alas] |