Input docs to site (#2297)

Co-authored-by: Alina Visan <[email protected]>
Co-authored-by: mikearildbrown <[email protected]>
Co-authored-by: James Nash <[email protected]>

site/docs/components/input/accessibility.mdx

@@ -0,0 +1,88 @@
+---
+title: Input
+layout: DetailComponent
+sidebar:
+  exclude: true
+data:
+  $ref: ./#/data
+---
+
+- Wrap Input in a [Form Field](/salt/components/form-field) to make it accessible within a form. This will provide the field with a visible label, help text and a status message for validation feedback. More information can be found [in the W3C form instructions](https://www.w3.org/WAI/tutorials/forms/instructions/).
+
+- Text that extends beyond the visible area of Input is clipped. This behavior is common to all states, i.e., default, read-only and disabled—whether or not the input has focus. To view the text in its entirety, the user can traverse the characters using the cursor.
+
+<LivePreviewControls>
+<LivePreview componentName="input" exampleName="EmptyReadonlyMarker" >
+
+### Empty Read-only Marker
+
+For accessibility purposes, we recommend you use the `emptyReadOnlyMarker` prop to add a marker for empty read-only fields. This ensures it’s clear that for the current selection or configuration a value is not necessary.
+
+</LivePreview>
+</LivePreviewControls>
+
+### Keyboard interactions
+
+<KeyboardControls>
+<KeyboardControl keyOrCombos="Tab">
+
+- If focus is above the Input, Tab key press moves focus onto the input. The text will be highlighted. If the input area is empty, the text cursor is displayed.
+- If the input is disabled, Tab key press will skip the input.
+- If the input has focus, Tab moves focus out of the input, to next focusable component in the tab order.
+
+</KeyboardControl>
+<KeyboardControl keyOrCombos="Shift + Tab">
+
+If focused, Shift + Tab moves focus out of the component to the previous component in the tab order.
+
+</KeyboardControl>
+<KeyboardControl keyOrCombos="Enter">
+
+If an interactive adornment, e.g., a button, has focus, the element is activated.
+
+</KeyboardControl>
+<KeyboardControl keyOrCombos="Space">
+
+- When the Input area has focus, a space character is inserted at the point where the text cursor is positioned.
+- If an interactive adornment, e.g., a button, has focus, the element is activated.
+
+</KeyboardControl>
+<KeyboardControl keyOrCombos="Right Arrow">
+
+When the Input area has focus:
+
+- If text is highlighted, the highlight is removed and the text cursor is positioned at the right edge of the highlight.
+- If the text cursor is displayed, it is positioned on the alternative side of the following character. If is there is no following character, there is no effect.
+
+</KeyboardControl>
+<KeyboardControl keyOrCombos="Left Arrow">
+
+When the Input area has focus:
+
+- If text is highlighted, the highlight is removed and the text cursor is positioned at the left edge of the highlight.
+- If the text cursor is displayed, it is positioned on the alternative side of the following character. If is there is no preceding character, there is no effect.
+
+</KeyboardControl>
+<KeyboardControl keyOrCombos="Shift + Left Arrow, Shift + Right Arrow">
+
+Drags selection over text characters, one at a time.
+
+</KeyboardControl>
+<KeyboardControl keyOrCombos="Backspace">
+
+When Input area has focus and: 
+- Text is highlighted, all highlighted characters are removed. 
+- The text cursor is positioned to the right of text, the preceding character is removed.
+
+</KeyboardControl>
+<KeyboardControl keyOrCombos="Alphanumeric/Special keys">
+
+When the Input area has focus, the relevant character is inserted at the point where the text cursor is positioned.
+
+</KeyboardControl>
+<KeyboardControl keyOrCombos="Control/Command + A">
+
+Highlights all strings within the field.
+
+</KeyboardControl>
+</KeyboardControls>

site/docs/components/input/examples.mdx

@@ -0,0 +1,107 @@
+---
+title: Input
+layout: DetailComponent
+sidebar:
+  exclude: true
+data:
+  $ref: ./#/data
+---
+
+<LivePreviewControls>
+<LivePreview componentName="input" exampleName="Primary" >
+
+### Primary
+
+Input comprises value text and a focus ring. The component is initially empty and then, once it has focus, it accepts text on a single line only.
+
+The default variant for Input is "primary".
+
+</LivePreview>
+<LivePreview componentName="input" exampleName="Secondary" >
+
+### Secondary
+
+Input has a "secondary" variant.
+
+For recommendations on variant choice, see the [Forms pattern](salt/patterns/forms).
+
+</LivePreview>
+<LivePreview componentName="input" exampleName="Disabled" >
+
+### Disabled
+
+You can disable Input, with no resultant action when the user interacts with it.
+
+</LivePreview>
+<LivePreview componentName="input" exampleName="Readonly" >
+
+### Read-only
+
+You can set Input to a read-only state. The value text can’t be edited in this state, but it can be highlighted and copied.
+
+By default, the marker is set to an em dash. If your application requires a different marker it can be set via the `emptyReadOnlyMarker` prop.
+
+- Use the read-only state when the value is necessary for the users flow or current task but cannot be edited, for example, because of user permissions.
+
+</LivePreview>
+<LivePreview componentName="input" exampleName="EmptyReadonlyMarker" >
+
+### Placeholder
+
+You can use a placeholder to prompt user input if no default value is provided.
+
+- Placeholder text should never be used to provide the user with contextual help since it will be removed when the user starts typing and does not meet minimum contrast requirements. Doing so is a WCAG failure. Instead, use helper text beneath the field to provide instructions or directions which are necessary to complete the field, and reserve the placeholder text to support the help message, or provide an example of the suggested content.
+
+More information can be found [in the W3C form instructions](https://www.w3.org/WAI/tutorials/forms/instructions/).
+
+</LivePreview>
+<LivePreview componentName="input" exampleName="Spellcheck" >
+
+### Spellcheck
+
+Turn automatic spellchecking on using `inputProps`.
+
+</LivePreview>
+<LivePreview componentName="input" exampleName="StaticAdornments" >
+
+### Static adornments
+
+You can add custom adornments at the beginning or end of the Input field using the `startAdornment` and `endAdornment` props.
+
+Start adornments are typically used to describe the purpose of the field (e.g., a phone number input, or a currency), whereas end adornments are typically used to indicate a reveal of more information (e.g., using an arrow icon) or to trigger a new UI (such as a date picker).
+
+Salt [Text](/salt/components/text) and [Icons](/salt/foundations/iconography) can be used to add Salt styled alphanumeric text or symbols as adornments. Multiple start or end adornments should be wrapped in a parent container and passed to the respective prop as a single fragment. Adornments can be dynamic, with their value depending on the current state.
+
+</LivePreview>
+<LivePreview componentName="input" exampleName="ButtonAdornments" >
+
+### Button adornments
+
+You can use [Button](/salt/components/button) at the beginning or end of the Input field with the `startAdornment` and `endAdornment` props. Buttons can allow for custom interactivity within the Input field itself, or elsewhere in the app via the Input field.
+
+Ensure to make your interactive Buttons disabled or read-only should it match the state of the containing Input field.
+
+</LivePreview>
+<LivePreview componentName="input" exampleName="Validation" >
+
+### Validation
+
+Input can show validation states (warning, success, error) with the prop `validationStatus`.
+
+- Use the error state to alert the user of a critical issue that’s related to the input. This issue, which may jeopardize completion of the task, usually requires action from the user to resolve the error.
+
+- Display the warning state when you need to alert the user of a potential issue—that won’t prevent the user from continuing with the task, but may cause errors if it’s not addressed.
+
+</LivePreview>
+<LivePreview componentName="input" exampleName="TextAlignment" >
+
+### Text Alignment
+
+Text is left-aligned by default. Use the `textAlign` prop to change the alignment to “center” or “right”.
+
+- Numeric values are often displayed right aligned to make them easier to compare. However, sometimes number fields are unrelated or are mixed with text fields in a form, so left-alignment may promote better visual flow. Consider your use case when deciding on Input field alignment.
+
+You may choose to center-align an input field to bring emphasis to a value. However, this should be the exception and used sparingly.
+
+</LivePreview>
+</LivePreviewControls>

site/docs/components/input/index.mdx

@@ -0,0 +1,13 @@
+---
+title: Input
+data:
+  description: Input provides an editable field in which users can enter text and numeric values. It is best used for short freeform content and data entry.
+  sourceCodeUrl: "https://github.com/jpmorganchase/salt-ds/blob/main/packages/core/src/input/Input.tsx"
+  package:
+    name: "@salt-ds/core"
+    initialVersion: "1.8.0-rc.0"
+  alsoKnownAs: ["Text Field", "Text Box"]
+  relatedComponents: [{ name: "Multiline Input", relationship: "similarTo" }]
+  stickerSheet: ""
+layout: DetailComponent
+---

site/docs/components/input/usage.mdx

@@ -0,0 +1,29 @@
+---
+title: Input
+layout: DetailComponent
+sidebar:
+  exclude: true
+data:
+  $ref: ./#/data
+---
+
+### When to use Input
+
+- To ask a user a subjective question to which user responses will vary and the length of their answer is likely to be less than a single line.
+- To avoid misleading users, set the width to correlates to the length of the answer you’re expecting. For example, an input for a three-digit value should not be wide enough to accommodate a sentence worth of characters. See [Forms pattern](/salt/patterns/forms) for more information on layout.
+
+#### When not to use Input
+
+When the content is likely to exceed a single line. Instead, use a [Multiline Input](/salt/components/multiline-input). Input field width and height should always reflect the amount of content expected in the field.
+
+### Import
+
+To import Input from the core Salt package, use:
+
+```js
+import { Input } from "@salt-ds/core";
+```
+
+### Props
+
+<PropsTable componentName="Input" />

site/src/examples/input/ButtonAdornments.tsx

@@ -0,0 +1,109 @@
+import { ReactElement } from "react";
+import { Button, FlowLayout, Input } from "@salt-ds/core";
+import {
+  NoteIcon,
+  SendIcon,
+  FlagIcon,
+  RefreshIcon,
+  CloseIcon,
+} from "@salt-ds/icons";
+
+export const ButtonAdornments = (): ReactElement => (
+  <FlowLayout style={{ width: "266px" }}>
+    <Input
+      startAdornment={
+        <Button>
+          <NoteIcon />
+        </Button>
+      }
+      defaultValue="Value"
+    />
+    <Input
+      endAdornment={
+        <Button variant="cta">
+          <RefreshIcon />
+        </Button>
+      }
+      defaultValue="Value"
+    />
+    <Input
+      startAdornment={
+        <>
+          <Button>
+            <SendIcon />
+          </Button>
+          <Button variant="cta">
+            <FlagIcon />
+          </Button>
+        </>
+      }
+      defaultValue="Value"
+    />
+    <Input
+      endAdornment={
+        <>
+          <Button variant="secondary">
+            <CloseIcon />
+          </Button>
+          <Button variant="cta">
+            <FlagIcon />
+          </Button>
+        </>
+      }
+      defaultValue="Value"
+    />
+    <Input
+      disabled
+      endAdornment={
+        <>
+          <Button disabled>
+            <SendIcon />
+          </Button>
+          <Button disabled variant="secondary">
+            <CloseIcon />
+          </Button>
+          <Button disabled variant="cta">
+            <FlagIcon />
+          </Button>
+        </>
+      }
+      defaultValue="Value"
+    />
+    <Input
+      readOnly
+      startAdornment={
+        <>
+          <Button disabled>
+            <SendIcon />
+          </Button>
+          <Button disabled variant="secondary">
+            <CloseIcon />
+          </Button>
+          <Button disabled variant="cta">
+            <FlagIcon />
+          </Button>
+        </>
+      }
+      defaultValue="Value"
+    />
+    <Input
+      disabled
+      startAdornment={
+        <>
+          <Button disabled>
+            <CloseIcon />
+          </Button>
+          <Button disabled variant="secondary">
+            <FlagIcon />
+          </Button>
+        </>
+      }
+      endAdornment={
+        <Button variant="cta" disabled>
+          <SendIcon />
+        </Button>
+      }
+      defaultValue="Value"
+    />
+  </FlowLayout>
+);

site/src/examples/input/Disabled.tsx

@@ -0,0 +1,6 @@
+import { ReactElement } from "react";
+import { Input } from "@salt-ds/core";
+
+export const Disabled = (): ReactElement => (
+  <Input defaultValue="Value" disabled style={{ width: "256px" }} />
+);

site/src/examples/input/EmptyReadonlyMarker.tsx

@@ -0,0 +1,9 @@
+import { ReactElement } from "react";
+import { FlowLayout, Input } from "@salt-ds/core";
+
+export const EmptyReadonlyMarker = (): ReactElement => (
+  <FlowLayout style={{ width: "256px" }}>
+    <Input readOnly />
+    <Input readOnly emptyReadOnlyMarker="*" />
+  </FlowLayout>
+);

site/src/examples/input/Placeholder.tsx

@@ -0,0 +1,10 @@
+import { ReactElement } from "react";
+import { FlowLayout, Input } from "@salt-ds/core";
+
+export const Placeholder = (): ReactElement => (
+  <FlowLayout style={{ width: "256px" }}>
+    <Input placeholder={"Enter a value"} />
+    <Input disabled placeholder={"Enter a value"} />
+    <Input readOnly placeholder={"Enter a value"} />
+  </FlowLayout>
+);

site/src/examples/input/Primary.tsx

@@ -0,0 +1,6 @@
+import { ReactElement } from "react";
+import { Input } from "@salt-ds/core";
+
+export const Primary = (): ReactElement => (
+  <Input defaultValue="Value" style={{ width: "256px" }} />
+);

site/src/examples/input/Readonly.tsx

@@ -0,0 +1,6 @@
+import { ReactElement } from "react";
+import { Input } from "@salt-ds/core";
+
+export const Readonly = (): ReactElement => (
+  <Input defaultValue="Value" style={{ width: "256px" }} readOnly />
+);

site/src/examples/input/Secondary.tsx

@@ -0,0 +1,6 @@
+import { ReactElement } from "react";
+import { Input, FlowLayout } from "@salt-ds/core";
+
+export const Secondary = (): ReactElement => (
+  <Input defaultValue="Value" variant="secondary" style={{ width: "256px" }} />
+);