docs: enhance story of Input and MultiInput (#896)

Lukas742 · web-flow · commit ce9b2f5b54b8 · 2020-11-03T08:24:57.000+01:00
diff --git a/packages/main/scripts/create-web-components-wrapper.mjs b/packages/main/scripts/create-web-components-wrapper.mjs
@@ -59,6 +59,25 @@ const CUSTOM_DESCRIPTION_REPLACE = {
         ''
       );
     }
+  },
+  MultiInput: {
+    children: (description) => {
+      return description.replace(
+        `<br> Example: <br><br> &lt;ui5-input show-suggestions><br> &nbsp;&nbsp;&nbsp;&nbsp;&lt;ui5-suggestion-item text="Item #1">&lt;/ui5-suggestion-item><br> &nbsp;&nbsp;&nbsp;&nbsp;&lt;ui5-suggestion-item text="Item #2">&lt;/ui5-suggestion-item><br> &lt;/ui5-input> <br> <ui5-input show-suggestions> <ui5-suggestion-item text="Item #1"></ui5-suggestion-item> <ui5-suggestion-item text="Item #2"></ui5-suggestion-item> </ui5-input> <br><br> `,
+        ''
+      );
+    },
+    tokens: (description) => {
+      return description.replace(
+        `<br> &lt;MultiInput><br> &nbsp;&nbsp;&nbsp;&nbsp;&lt;ui5-token slot="tokens" text="Token 1">&lt;/ui5-token><br> &nbsp;&nbsp;&nbsp;&nbsp;&lt;ui5-token slot="tokens" text="Token 2">&lt;/ui5-token><br> &lt;/MultiInput> <br> <br>`,
+        `<br />&lt;MultiInput tokens={
+    <br />&nbsp;&nbsp;&lt;>
+    <br />&nbsp;&nbsp;&nbsp;&nbsp;&lt;Token text="Token 1" />
+    <br />&nbsp;&nbsp;&nbsp;&nbsp;&lt;Token text="Token 2" />
+    <br />&nbsp;&nbsp;</>}
+    <br />/>`
+      );
+    }
   }
 };
 
diff --git a/packages/main/src/webComponents/Input/Input.stories.mdx b/packages/main/src/webComponents/Input/Input.stories.mdx
@@ -1,14 +1,16 @@
 import { ArgsTable, Canvas, Meta, Story } from '@storybook/addon-docs/blocks';
 import { Input } from '@ui5/webcomponents-react/lib/Input';
+import { ListItemTypes } from '@ui5/webcomponents-react/lib/ListItemTypes';
 import { InputType } from '@ui5/webcomponents-react/lib/InputType';
 import { ValueState } from '@ui5/webcomponents-react/lib/ValueState';
 import '@ui5/webcomponents-icons/dist/icons/employee.js';
+import '@ui5/webcomponents-icons/dist/icons/globe.js';
 import { Icon } from '@ui5/webcomponents-react/lib/Icon';
-import { CSSProperties } from 'react';
 import { SuggestionItem } from '@ui5/webcomponents-react/lib/SuggestionItem';
 import { createSelectArgTypes } from '@shared/stories/createSelectArgTypes';
 import { DocsHeader } from '@shared/stories/DocsHeader';
 import { DocsCommonProps } from '@shared/stories/DocsCommonProps';
+import '@ui5/webcomponents/dist/features/InputSuggestions.js';
 
 <Meta
   title="UI5 Web Components / Input"
@@ -44,3 +46,88 @@ import { DocsCommonProps } from '@shared/stories/DocsCommonProps';
 </Canvas>
 
 <ArgsTable story="." />
+
+<br />
+
+# Stories
+
+<br />
+
+## Input with customizable SuggestionItem
+
+The `SuggestionItem` represents the suggestion item of the `Input`
+
+**Note:** `SuggestionItems` will only be displayed if the required module has been imported (`import '@ui5/webcomponents/dist/features/InputSuggestions.js';`)
+and the `showSuggestions` prop is set to `true`.
+
+<Canvas>
+  <Story
+    name="with SuggestionItem"
+    args={{
+      description: 'description',
+      group: false,
+      icon: 'globe',
+      iconEnd: false,
+      image: '',
+      info: 'info',
+      infoState: ValueState.None,
+      text: 'Customizable SuggestionItem',
+      type: ListItemTypes.Active
+    }}
+    argTypes={{
+      description: { description: `Defines the description displayed right under the item text, if such is present.` },
+      group: {
+        description: `Defines the item to be displayed as a group item. <br><br> <b>Note:</b> When set, the other properties, such as <code>image</code>, <code>icon</code>, <code>description</code>, etc. will be omitted and only the <code>text</code> will be displayed.`
+      },
+      icon: {
+        description: `Defines the <code>icon</code> source URI. <br><br> <b>Note:</b> SAP-icons font provides numerous buil-in icons. To find all the available icons, see the <ui5-link target="_blank" href="https://openui5.hana.ondemand.com/test-resources/sap/m/demokit/iconExplorer/webapp/index.html" class="api-table-content-cell-link">Icon Explorer</ui5-link>.`
+      },
+      iconEnd: {
+        description: `Defines whether the <code>icon</code> should be displayed in the beginning of the item or in the end. <br><br> <b>Note:</b> If <code>image</code> is set, the <code>icon</code> would be displayed after the <code>image</code>.`
+      },
+      image: {
+        description: `Defines the <code>image</code> source URI. <br><br> <b>Note:</b> The <code>image</code> would be displayed in the beginning of the item.`
+      },
+      info: { description: `Defines the <code>info</code>, displayed in the end of the item.` },
+      infoState: {
+        description: `Defines the state of the <code>info</code>. <br><br> Available options are: <code>"None"</code> (by default), <code>"Success"</code>, <code>"Warning"</code> and <code>"Erorr"</code>.`
+      },
+      text: { description: `Defines the text of the <code>SuggestionItem</code>.` },
+      type: {
+        control: { options: ['Inactive', 'Active', 'Detail'] },
+        description: `Defines the visual indication and behavior of the item. Available options are <code>Active</code> (by default), <code>Inactive</code> and <code>Detail</code>. <br><br> <b>Note:</b> When set to <code>Active</code>, the item will provide visual response upon press and hover, while when <code>Inactive</code> or <code>Detail</code> - will not.`
+      },
+      disabled: { table: { disable: true } },
+      highlight: { table: { disable: true } },
+      maxlength: { table: { disable: true } },
+      name: { table: { disable: true } },
+      placeholder: { table: { disable: true } },
+      readonly: { table: { disable: true } },
+      required: { table: { disable: true } },
+      showSuggestions: { table: { disable: true } },
+      value: { table: { disable: true } },
+      valueState: { table: { disable: true } },
+      children: { table: { disable: true } },
+      valueStateMessage: { table: { disable: true } },
+      onChange: { table: { disable: true } },
+      onInput: { table: { disable: true } },
+      onSubmit: { table: { disable: true } },
+      onSuggestionItemPreview: { table: { disable: true } },
+      onSuggestionItemSelect: { table: { disable: true } },
+      onSuggestionScroll: { table: { disable: true } }
+    }}
+  >
+    {(args) => {
+      return (
+        <Input showSuggestions placeholder="click here to show suggestions" style={{ width: '400px' }}>
+          <SuggestionItem {...args} />
+          <SuggestionItem icon="globe" text="Argentina" />
+          <SuggestionItem icon="globe" text="Iceland" />
+          <SuggestionItem icon="globe" text="Moldova" />
+        </Input>
+      );
+    }}
+  </Story>
+</Canvas>
+
+<ArgsTable story="with SuggestionItem" />
diff --git a/packages/main/src/webComponents/Input/index.tsx b/packages/main/src/webComponents/Input/index.tsx
@@ -54,7 +54,7 @@ export interface InputPropTypes extends Omit<WithWebComponentPropTypes, 'onChang
    */
   valueState?: ValueState;
   /**
-   * Defines the <code>Input</code> suggestion items. <br><br> Example: <br><br> &lt;Input show-suggestions><br> &nbsp;&nbsp;&nbsp;&nbsp;&lt;ui5-suggestion-item text="Item #1">&lt;/ui5-suggestion-item><br> &nbsp;&nbsp;&nbsp;&nbsp;&lt;ui5-suggestion-item text="Item #2">&lt;/ui5-suggestion-item><br> &lt;/Input>  <br><br> <b>Note:</b> The suggestion would be displayed only if the <code>showSuggestions</code> property is set to <code>true</code>. <br><br> <b>Note:</b> The &lt;ui5-suggestion-item> is recommended to be used as a suggestion item. Importing the Input Suggestions Support feature: <br> <code>import "@ui5/webcomponents/dist/features/InputSuggestions.js";</code> <br> also automatically imports the &lt;ui5-suggestion-item> for your convenience.
+   * Defines the <code>Input</code> suggestion items. <br><br> Example: <br><br> &lt;Input showSuggestions><br> &nbsp;&nbsp;&nbsp;&nbsp;&lt;SuggestionItem text="Item #1">&lt;/SuggestionItem><br> &nbsp;&nbsp;&nbsp;&nbsp;&lt;SuggestionItem text="Item #2">&lt;/SuggestionItem><br> &lt;/Input>  <br><br> <b>Note:</b> The suggestion would be displayed only if the <code>showSuggestions</code> property is set to <code>true</code>. <br><br> <b>Note:</b> The &lt;SuggestionItem> is recommended to be used as a suggestion item. Importing the Input Suggestions Support feature: <br> <code>import "@ui5/webcomponents/dist/features/InputSuggestions.js";</code> <br> also automatically imports the &lt;SuggestionItem> for your convenience.
    */
   children?: ReactNode | ReactNode[];
   /**
diff --git a/packages/main/src/webComponents/MultiInput/MultiInput.stories.mdx b/packages/main/src/webComponents/MultiInput/MultiInput.stories.mdx
@@ -1,20 +1,33 @@
 import { ArgsTable, Canvas, Meta, Story } from '@storybook/addon-docs/blocks';
 import { MultiInput } from '@ui5/webcomponents-react/lib/MultiInput';
-import { Token } from '@ui5/webcomponents-react/lib/Token';
 import { InputType } from '@ui5/webcomponents-react/lib/InputType';
 import { ValueState } from '@ui5/webcomponents-react/lib/ValueState';
-import { DocsHeader } from '@shared/stories/DocsHeader';
+import '@ui5/webcomponents-icons/dist/icons/employee.js';
+import { Token } from '@ui5/webcomponents-react/lib/Token';
 import { createSelectArgTypes } from '@shared/stories/createSelectArgTypes';
+import { DocsHeader } from '@shared/stories/DocsHeader';
 import { DocsCommonProps } from '@shared/stories/DocsCommonProps';
 
 <Meta
   title="UI5 Web Components / MultiInput"
   component={MultiInput}
-  subcomponents={{ MultiInput, Token }}
+  subcomponents={{ Token }}
   argTypes={{
     ...createSelectArgTypes({ type: InputType, valueState: ValueState }),
-    tokens: null,
-    ...DocsCommonProps
+    ...DocsCommonProps,
+    tokens: { control: { disable: true } },
+    children: { control: { disable: true } },
+    icon: { control: { disable: true } },
+    valueStateMessage: { control: { disable: true } }
+  }}
+  args={{
+    type: InputType.Text,
+    valueState: ValueState.None,
+    style: { width: '400px' },
+    className: '',
+    tooltip: '',
+    slot: '',
+    ref: null
   }}
 />
 
@@ -26,7 +39,6 @@ import { DocsCommonProps } from '@shared/stories/DocsCommonProps';
       return (
         <MultiInput
           {...args}
-          style={{ width: '100%' }}
           tokens={
             <>
               <Token text="Argentina" />
@@ -50,3 +62,7 @@ import { DocsCommonProps } from '@shared/stories/DocsCommonProps';
 </Canvas>
 
 <ArgsTable story="." />
+
+## Render SuggestionItems
+
+The `MultiInput` component supports rendering `SuggestionItems`. An example on how to use them can be found [here](?path=/docs/ui5-web-components-input--with-suggestion-item#input-with-customizable-suggestionitem).
diff --git a/packages/main/src/webComponents/MultiInput/index.tsx b/packages/main/src/webComponents/MultiInput/index.tsx
@@ -58,20 +58,24 @@ export interface MultiInputPropTypes extends Omit<WithWebComponentPropTypes, 'on
    */
   valueState?: ValueState;
   /**
-   * Defines the <code>MultiInput</code> tokens. <br><br> Example: <br> &lt;MultiInput><br> &nbsp;&nbsp;&nbsp;&nbsp;&lt;ui5-token slot="tokens" text="Token 1">&lt;/ui5-token><br> &nbsp;&nbsp;&nbsp;&nbsp;&lt;ui5-token slot="tokens" text="Token 2">&lt;/ui5-token><br> &lt;/MultiInput> <br> <br>
+   * Defines the <code>MultiInput</code> tokens. <br><br> Example: <br />&lt;MultiInput tokens={
+<br />&nbsp;&nbsp;&lt;>
+<br />&nbsp;&nbsp;&nbsp;&nbsp;&lt;Token text="Token 1" />
+<br />&nbsp;&nbsp;&nbsp;&nbsp;&lt;Token text="Token 2" />
+<br />&nbsp;&nbsp;</>}
+   <br />/>
    */
   tokens?: ReactNode | ReactNode[];
   /**
-   * Defines the <code>Input</code> suggestion items. <br><br> Example: <br><br> &lt;ui5-input show-suggestions><br> &nbsp;&nbsp;&nbsp;&nbsp;&lt;ui5-suggestion-item text="Item #1">&lt;/ui5-suggestion-item><br> &nbsp;&nbsp;&nbsp;&nbsp;&lt;ui5-suggestion-item text="Item #2">&lt;/ui5-suggestion-item><br> &lt;/ui5-input> <br> <ui5-input show-suggestions> <ui5-suggestion-item text="Item #1"></ui5-suggestion-item> <ui5-suggestion-item text="Item #2"></ui5-suggestion-item> </ui5-input> <br><br> <b>Note:</b> The suggestion would be displayed only if the <code>showSuggestions</code> property is set to <code>true</code>. <br><br> <b>Note:</b> The &lt;ui5-suggestion-item> is recommended to be used as a suggestion item. Importing the Input Suggestions Support feature: <br> <code>import "@ui5/webcomponents/dist/features/InputSuggestions.js";</code> <br> also automatically imports the &lt;ui5-suggestion-item> for your convenience.
+   * Defines the <code>Input</code> suggestion items. <br><b>Note:</b> The suggestion would be displayed only if the <code>showSuggestions</code> property is set to <code>true</code>. <br><br> <b>Note:</b> The &lt;ui5-suggestion-item> is recommended to be used as a suggestion item. Importing the Input Suggestions Support feature: <br> <code>import "@ui5/webcomponents/dist/features/InputSuggestions.js";</code> <br> also automatically imports the &lt;ui5-suggestion-item> for your convenience.
    */
   children?: ReactNode | ReactNode[];
   /**
    * Defines the icon to be displayed in the <code>Input</code>.
    */
   icon?: ReactNode | ReactNode[];
   /**
-   * Defines the value state message that will be displayed as pop up under the <code>Input</code>. <br><br><br/><br/>
-   *
+   * Defines the value state message that will be displayed as pop up under the <code>Input</code>.<br/>
    * <b>Note:</b> If not specified, a default text (in the respective language) will be displayed. <br> <b>Note:</b> The <code>valueStateMessage</code> would be displayed, when the <code>Input</code> is in <code>Information</code>, <code>Warning</code> or <code>Error</code> value state. <br> <b>Note:</b> If the <code>Input</code> has <code>suggestionItems</code>, the <code>valueStateMessage</code> would be displayed as part of the same popover, if used on desktop, or dialog - on phone.
    */
   valueStateMessage?: ReactNode | ReactNode[];
@@ -82,19 +86,19 @@ export interface MultiInputPropTypes extends Omit<WithWebComponentPropTypes, 'on
   /**
    * Fired when the value help icon is pressed and F4 or ALT/OPTION + ARROW_UP/ARROW_DOWN keyboard keys are used.
    */
-  onValueHelpTrigger?: (event: CustomEvent<{}>) => void;
+  onValueHelpTrigger?: (event: CustomEvent) => void;
   /**
    * Fired when the input operation has finished by pressing Enter or on focusout.
    */
-  onChange?: (event: CustomEvent<{}>) => void;
+  onChange?: (event: CustomEvent) => void;
   /**
    * Fired when the value of the <code>Input</code> changes at each keystroke, and when a suggestion item has been selected.
    */
-  onInput?: (event: CustomEvent<{}>) => void;
+  onInput?: (event: CustomEvent) => void;
   /**
    * Fired when user presses Enter key on the <code>Input</code>. <br><br> <b>Note:</b> The event is fired independent of whether there was a change before or not. If change was performed, the event is fired after the change event. The event is also fired when an item of the select list is selected by pressing Enter.
    */
-  onSubmit?: (event: CustomEvent<{}>) => void;
+  onSubmit?: (event: CustomEvent) => void;
   /**
    * Fired when the user navigates to a suggestion item via the ARROW keys, as a preview, before the final selection.
    */
@@ -110,12 +114,10 @@ export interface MultiInputPropTypes extends Omit<WithWebComponentPropTypes, 'on
 }
 
 /**
- * <h3>Overview</h3>
- A <code>MultiInput</code> field allows the user to enter multiple values, which are displayed as <code>Token</code>.
+ *A <code>MultiInput</code> field allows the user to enter multiple values, which are displayed as <code>Token</code>.
  User can choose interaction for creating tokens. Fiori Guidelines say that user should create tokens when:
- <ul> <li>Type a value in the input and press enter or focus out the input field (<code>change</code> event is fired)</li> <li>Select a value from the suggestion list</li> (<code>suggestion-item-select</code> event is fired)
+ <ul> <li>Type a value in the input and press enter or focus out the input field (<code>onChange</code> event is fired)</li> <li>Select a value from the suggestion list (<code>onSuggestionItemSelect</code> event is fired)</li>
  </ul>
-
  * <a href="https://sap.github.io/ui5-webcomponents/playground/components/MultiInput" target="_blank">UI5 Web Components Playground</a>
  */
 const MultiInput: FC<MultiInputPropTypes> = withWebComponent<MultiInputPropTypes>(
