Merge pull request #3671 from grommet/search-taylor-suggestions

Search guidance suggestions

aries-site/src/examples/components/search/ClearSearchExample.js

@@ -0,0 +1,16 @@
+import React from 'react';
+import { TextInput } from 'grommet';
+import { Search as SearchIcon } from 'grommet-icons';
+
+export const ClearSearchExample = () => {
+  return (
+    <TextInput
+      aria-label="Search"
+      icon={<SearchIcon />}
+      placeholder="Search"
+      reverse
+      defaultValue="sample search term"
+      type="search"
+    />
+  );
+};

aries-site/src/examples/components/search/SearchPlaceholder.js

@@ -20,7 +20,11 @@ export const SearchPlaceholder = ({ bestPractice = true }) => {
     <Box width="medium">
       <StyledTextInput
         icon={<SearchIcon id="search-icon-placeholder" color="placeholder" />}
-        placeholder={bestPractice ? 'Search' : 'Search users...'}
+        placeholder={
+          bestPractice
+            ? 'Search'
+            : 'Search first name, last name, role, location, or status'
+        }
         reverse
         value={value}
         onChange={event => setValue(event.target.value)}

aries-site/src/examples/components/search/index.js

@@ -1,4 +1,5 @@
 export * from './SearchExample';
+export * from './ClearSearchExample';
 export * from './SearchIconPositionExample';
 export * from './SearchPlaceholder';
 export * from './SearchSimpleExample';

aries-site/src/pages/components/search.mdx

@@ -1,5 +1,6 @@
 import { BestPracticeGroup, Example } from '../../layouts';
 import {
+  ClearSearchExample,
   SearchExample,
   SearchIconPositionExample,
   SearchPlaceholder,
@@ -27,7 +28,7 @@ Many search best practices extend "behind the scenes," such as how query strings
 
 ### Placeholder
 
-Placeholder text should ideally be brief and to the point.
+Placeholder text should be brief and to the point.
 
 <BestPracticeGroup>
   <Example
@@ -43,7 +44,7 @@ Placeholder text should ideally be brief and to the point.
     height="small"
     bestPractice={{
       type: 'dont',
-      message: `Avoid lengthly placeholder text and avoid truncation.`,
+      message: `Avoid lengthly placeholder text that overflows.`,
     }}
   >
     <SearchPlaceholder bestPractice={false} />
@@ -72,17 +73,34 @@ If the search input is within a form then the placeholder should be used instead
 
 For additional detail, see [ARIA form hints](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/forms/Basic_form_hints).
 
-## Icons
+## Search icon
 
-### 'Search' icon placement
+### Placement
 
-The search icon may be placed either to the right or left of the input field. Icon position is controlled via the [reverse](https://v2.grommet.io/textinput?theme=hpe#reverse) property.
+The search icon may be placed either to the right or left of the input field. Icon position is controlled via the [reverse](#icon-position) property.
+
+Place the icon in the position that most helps people to scan the page and identify the search field. Working as a visual aid, the intention should be for the search icon to be seen first and the placeholder text second. When deciding where to place the icon, consider where the search bar is located and how the user might be scanning the page (for example, in an F shape pattern from left to right).
+
+### Interactivity
+
+The search icon is not interactive. The search may be submitted either "onChange" as the user types, "onEnter", or in some cases by clicking on an accompanying button.
+
+## Clear search control
+
+When an input has `type="search"`, many browsers will insert a native "clear" control inside the input that allows the user to clear the entire search string.
 
-Place the icon in the position that most helps people to scan the page and identify the search field. Working as a visual aid, the search icon is best seen before the placeholder 'search’ text is. When deciding where to place the icon, consider where the search bar is located and how the user might be scanning the page (for example, in an F pattern from left to right). The search icon is not itself interactive.
+The styling of this "clear" control is controlled by each browser, so it may differ visually from HPE brand colors and icons.
 
-### 'Clear search' icon
+Click into the search input to see the "clear" control.
 
-The search input uses the browser's native ’clear’ icon, which may differ visually from other HPE icons.
+<Example
+  code="https://raw.githubusercontent.com/grommet/hpe-design-system/master/aries-site/src/examples/components/search/ClearSearchExample.js"
+  docs="https://v2.grommet.io/textinput?theme=hpe#props"
+  width="medium"
+  height="auto"
+>
+  <ClearSearchExample />
+</Example>
 
 ## Variants