@splunk/react-ui 5.7.0 → 5.8.0

package/docs-llm/Text Area.md

@@ -0,0 +1,253 @@
+# Text Area
+
+## Overview
+
+
+> Image: Illustration of Text Area component.
+
+
+<Message appearance="fill" type="info">
+    <div>All data entry components should be wrapped in a <Link to="ControlGroup">Control Group</Link> to provide a label, error states, and help or error text, ensuring an accessible experience for all users.</div>
+</Message>
+
+## When to use this component
+- You need to capture multiline plain text, such as comments or descriptions
+- You want to ask users an open-ended question, such as "Do you have any feedback?"
+- When information cannot be predicted with a set of predefined options
+
+## When to use another component
+- If you need to capture single line plain text, use Text
+- If you need to secure data, information, or a profile, use `Text` with `type="password"`
+- When it's easier for users to select from a list options, use `Select` or `Multiselect`
+
+```mermaid
+graph TD
+    accDescr: Decision tree that guides on when to use the TextArea component or something else
+    A(Need to secure data?) -- No --- B(Need to capture multiple lines?)
+    B -- No --- C(Text)
+    B -- Yes --- D(Text Area)
+    A -- Yes --- E("Text type='password'")
+```
+
+### Check out
+- [Control Group][1]
+- [Multiselect][2]
+- [Select][3]
+- [Text][4]
+
+## Behaviors
+
+### Min and Max rows
+Text area will grow and shrink vertically based on the defined minimum and maximum number of rows. The default minimum is set to 2 rows, maximum rows is 8. When the content exceeds the max number of rows, Text Area will add a scroll bar.
+
+> Image: Three text areas demonstrating dynamic resizing: the first with 2 rows as the minimum, the second with 8 rows as the maximum, and the third showing a scrollbar when content exceeds 8 rows.
+
+
+## Usage
+
+### Placeholders
+Placeholder text presents a number of visual and cognitive issues; it is best to avoid using it.
+Placeholder does not replace a label. [Splunk Style Guide placeholder guidelines][5]
+
+> Image: Comparison of two text areas labeled 
+
+
+### Text Area width
+Don't extend Text Area across the entire width of a screen. To maintain usability and readability, ensure a width that doesn't exceeded 80 characters.
+
+> Image: Two text areas labeled 
+
+
+### Clear Text area
+The suggested way to support a clear content action is a button with clear label and an icon placed outside of Text Area. Avoid placing the clear action inside Text area.
+
+> Image: Two Text Areas examples labeled 
+
+
+### Text Area resize
+Add a [resize][6] handle to provide user the ability to make Text Area size fit there needs.
+
+> Image: Text Area example with heart eyes emoji labeled 
+
+
+
+## Content guidelines
+
+### Labels
+Labels are required. Keep Text Area labels brief and use sentence-style capitalization.
+
+> Image: Two Text Area examples with labels demonstrating best practices: the first example with heart eyes emoji is labeled 
+
+
+[1]: ./ControlGroup
+[2]: ./Multiselect
+[3]: ./Select
+[4]: ./Text
+[5]: https://docs.splunk.com/Documentation/StyleGuide/drafts/StyleGuide/UIGuidelines#Placeholder_text
+[6]: ./Resize
+
+## Examples
+
+
+### Controlled
+
+Text Area requires a value prop and an onChange callback to update the value prop for most use cases.
+
+```typescript
+import React, { useState } from 'react';
+
+import TextArea, { TextAreaChangeHandler } from '@splunk/react-ui/TextArea';
+
+
+const Basic = () => {
+    const [text, setText] = useState('');
+    const handleChange: TextAreaChangeHandler = (e, { value }) => {
+        setText(value);
+    };
+
+    return <TextArea value={text} onChange={handleChange} />;
+};
+
+export default Basic;
+```
+
+
+
+### Uncontrolled
+
+Alternatively, Text Area can be uncontrolled and optionally provided a defaultValue. The onChange callback still fires. The value prop cannot be set or updated externally.
+
+```typescript
+import React from 'react';
+
+import TextArea from '@splunk/react-ui/TextArea';
+
+
+function Uncontrolled() {
+    return <TextArea defaultValue="Hello" />;
+}
+
+export default Uncontrolled;
+```
+
+
+
+### Inline
+
+Passing inline will create an inline element and the input will be its default size.
+
+```typescript
+import React, { useState } from 'react';
+
+import TextArea, { TextAreaChangeHandler } from '@splunk/react-ui/TextArea';
+
+
+const Inline = () => {
+    const [text, setText] = useState('Hello');
+    const handleChange: TextAreaChangeHandler = (e, { value }) => {
+        setText(value);
+    };
+
+    return <TextArea inline value={text} onChange={handleChange} />;
+};
+
+export default Inline;
+```
+
+
+
+### Disabled
+
+```typescript
+import React from 'react';
+
+import TextArea from '@splunk/react-ui/TextArea';
+
+
+const Disabled = () => <TextArea style={{ width: '250px' }} disabled />;
+
+export default Disabled;
+```
+
+
+
+### Error
+
+Setting error will highlight the field.
+
+```typescript
+import React, { useState } from 'react';
+
+import TextArea, { TextAreaChangeHandler } from '@splunk/react-ui/TextArea';
+
+
+const Error = () => {
+    const [text, setText] = useState('invalid');
+    const handleChange: TextAreaChangeHandler = (e, { value }) => {
+        setText(value);
+    };
+
+    return <TextArea style={{ width: '250px' }} error value={text} onChange={handleChange} />;
+};
+
+export default Error;
+```
+
+
+
+
+## API
+
+
+### TextArea API
+
+Note: TextArea places role and aria props onto the input. All other props are placed on the wrapper.
+
+#### Props
+
+| Name | Type | Required | Default | Description |
+|------|------|------|------|------|
+| append | boolean | no | false | Append removes rounded borders and the border from the right side. |
+| autoCapitalize | string | no |  | Control the browser's automatic capitalization functionality. Note: Doesn't apply to physical keyboard input. Examples: 'on', 'off', 'sentences', 'words, 'characters'. |
+| autoComplete | string | no |  | Control the browser's autofill functionality. See [the specification](https://html.spec.whatwg.org/multipage/form-control-infrastructure.html#autofilling-form-controls:-the-autocomplete-attribute) for details. Examples: 'on', 'off', 'cc-name', 'shipping street-address'. |
+| autoCorrect | string | no |  | Set the input's autocorrect attribute. Only supported by Safari. See also `spellCheck`. |
+| autoFocus | boolean | no | false | Specify that the input should request focus when mounted. |
+| children | React.ReactNode | no |  |  |
+| defaultValue | string | no |  | Set this property instead of value to make value uncontrolled. |
+| describedBy | string | no |  | The id of the description. When placed in a ControlGroup, this is automatically set to the ControlGroup's help component. |
+| disabled | boolean | no | false | Determines whether or not the input is editable. |
+| elementRef | React.Ref<HTMLDivElement> | no |  | A React ref which is set to the DOM element when the component mounts, and null when it unmounts. |
+| endAdornment | React.ReactNode | no |  | Adornment after the input. |
+| error | boolean | no | false | Highlight the field as having an error. The border will turn red. |
+| inline | boolean | no | false | When false, display as inline-block with the default width. |
+| inputId | string | no |  | An id for the input, which may be necessary for accessibility, such as for aria attributes. |
+| inputRef | React.Ref<HTMLTextAreaElement> | no |  | A React ref which is set to the input element when the component mounts and null when it unmounts. |
+| labelledBy | string | no |  | The id of the label. When placed in a ControlGroup, this is automatically set to the ControlGroup's label. |
+| maxLength | number | no |  | Set the input's maxlength attribute. |
+| name | string | no |  | The name is returned with onChange events, which can be used to identify the control when multiple controls share an onChange callback. |
+| onBlur | TextAreaBlurHandler | no |  | A callback for when the input loses focus. |
+| onChange | TextAreaChangeHandler | no |  | This is equivalent to onInput which is called on keydown, paste, and so on. If value is set, this callback is required. This must set the value prop to retain the change. |
+| onFocus | TextAreaFocusHandler | no |  | A callback for when the input takes focus. |
+| onInputClick | React.MouseEventHandler<HTMLTextAreaElement> | no |  | A callback for when the user clicks the textbox. This will only trigger when the textbox itself is clicked and will not trigger for other parts of the component, such as nodes added via "startAdornment" or "endAdornment" props. If you want to handle all click events, pass the "onClick" prop, which will be attached to `TextArea`'s root element. |
+| onKeyDown | React.KeyboardEventHandler<HTMLTextAreaElement> | no |  | A keydown callback can be used to prevent a certain input by utilizing the event argument. |
+| onSelect | React.ReactEventHandler<HTMLTextAreaElement> | no |  | A callback for when the text selection or cursor position changes. |
+| prepend | boolean | no | false | Prepend removes rounded borders from the left side. |
+| rowsMax | number | no | 8 | Maximum number of rows to display |
+| rowsMin | number | no | 2 | Minimum number of rows to display |
+| spellCheck | boolean | no |  | Control the browser's spelling and grammar checking functionality. |
+| startAdornment | React.ReactNode | no |  | Adornment in front of the input. |
+| tabIndex | number | no | 0 |  |
+| value | string | no |  | The contents of the input. Setting this value makes the property controlled. A callback is required. |
+
+#### Types
+
+| Name | Type | Description |
+|------|------|------|
+| TextAreaBlurHandler | (     event: React.FocusEvent<HTMLTextAreaElement>,     data: {         name?: string;         value: string;     } ) => void |  |
+| TextAreaChangeHandler | (     event: React.ChangeEvent<HTMLTextAreaElement>,     data: {         name?: string;         value: string;     } ) => void |  |
+| TextAreaFocusHandler | (     event: React.FocusEvent<HTMLTextAreaElement>,     data: {         name?: string;         value: string;     } ) => void |  |
+
+
+
+
+

package/docs-llm/Text.md

@@ -0,0 +1,339 @@
+# Text
+
+## Overview
+
+
+> Image: Illustration of a text input
+
+
+<Message appearance="fill" type="info">
+    <div>All data entry components should be wrapped in a <Link to="ControlGroup">Control Group</Link> to provide a label, error states, and help or error text, ensuring an accessible experience for all users.</div>
+</Message>
+
+## When to use this component
+- When single line plain text is needed.
+- When information cannot be predicted with a set of predefined options.
+- When you need to secure data, information, or a profile, use `type="password"`.
+
+## When to use another component
+- If you need to capture multiline plain text, such as a comment or description, use `Text Area`.
+- If you need to resize the input or validate character count, use `Text Area` or the `Resize` utility.
+
+```mermaid
+graph TD
+    accDescr: Decision tree that guides on when to use the Text component or something else
+    A(Need to secure data?) -- No --- B(Need to capture multiple lines?)
+    B -- No --- C(Text)
+    B -- Yes --- D(Text Area)
+    A -- Yes --- E("type='password'")
+```
+
+### Check out
+- [Control Group][1]
+- [Text Area][2]
+- [Resize][3]
+
+## Usage
+
+### Placeholders
+Since placeholder text presents a number of visual and cognitive issues, it is best to avoid using it.
+Placeholder does not replace a label. [Splunk Style Guide placeholder guidelines][4]
+> Image: Examples of using placeholder text in the Text component. The first example with heart eyes emoji has a Text component labeled 
+
+
+### Text width
+Adjust the width to accommodate the anticipated input length, ensuring it is sufficiently wide to support the longest expected values. Avoid extending `Text` across the entire width of large screens to maintain usability and readability.
+> Image: Examples of Text component widths. The first example with heart eyes emoji has a Text component labeled 
+
+
+## Content guidelines
+
+### Labels
+Labels are required, keep Text labels brief and use sentence-style capitalization.
+> Image: Example of keeping Text component labels brief. The first example with heart eyes emoji has a Text component labeled 
+
+
+[1]: ./ControlGroup
+[2]: ./TextArea
+[3]: ./Resize
+[4]: https://docs.splunk.com/Documentation/StyleGuide/drafts/StyleGuide/UIGuidelines#Placeholder_text
+
+## Examples
+
+
+### Controlled
+
+Text requires a value prop and an onChange callback to update the value prop for most use cases.
+
+```typescript
+import React, { useState } from 'react';
+
+import Text, { TextChangeHandler } from '@splunk/react-ui/Text';
+
+
+const Basic = () => {
+    const [value, setValue] = useState<string | undefined>('');
+
+    const handleChange: TextChangeHandler = (e, { value: newValue }) => {
+        setValue(newValue);
+    };
+
+    return <Text canClear value={value} onChange={handleChange} />;
+};
+
+export default Basic;
+```
+
+
+
+### Uncontrolled
+
+Alternatively, Text can be uncontrolled and optionally provided a defaultValue. The onChange callback still fires. The value prop cannot be set or updated externally.
+
+```typescript
+import React from 'react';
+
+import Text from '@splunk/react-ui/Text';
+
+
+function Uncontrolled() {
+    return <Text defaultValue="Hello" canClear />;
+}
+
+export default Uncontrolled;
+```
+
+
+
+### Inline
+
+Passing inline will create an inline element and the input will be its default size.
+
+```typescript
+import React, { useState } from 'react';
+
+import Text, { TextChangeHandler } from '@splunk/react-ui/Text';
+
+
+const Inline = () => {
+    const [value, setValue] = useState<string | undefined>('');
+
+    const handleChange: TextChangeHandler = (e, { value: newValue }) => {
+        setValue(newValue);
+    };
+
+    return <Text inline value={value} onChange={handleChange} />;
+};
+
+export default Inline;
+```
+
+
+
+### Dimmed
+
+If you absolutely need to disable a Text use a dimmed Text. When the disabled prop is set to "dimmed", the Text does not respond to events but can still receive focus to ensure users can navigate to the Text when using assistive technologies. This also sets aria-disabled to true.
+
+```typescript
+import React from 'react';
+
+import Text from '@splunk/react-ui/Text';
+
+
+const Dimmed = () => <Text disabled="dimmed" defaultValue="This cannot be edited." inline />;
+
+export default Dimmed;
+```
+
+
+
+### Disabled
+
+Disabled cannot accept an input or become focused.
+
+```typescript
+import React from 'react';
+
+import Text from '@splunk/react-ui/Text';
+
+
+const Disabled = () => <Text disabled defaultValue="This cannot be edited." inline />;
+
+export default Disabled;
+```
+
+
+
+### Error
+
+Setting error will highlight the field.
+
+```typescript
+import React, { useState } from 'react';
+
+import Text, { TextChangeHandler } from '@splunk/react-ui/Text';
+
+
+const Error = () => {
+    const [value, setValue] = useState<string | undefined>('invalid');
+
+    const handleChange: TextChangeHandler = (e, { value: newValue }) => {
+        setValue(newValue);
+    };
+
+    return <Text error inline value={value} onChange={handleChange} />;
+};
+
+export default Error;
+```
+
+
+
+### Password
+
+The Text control also supports a password input type and visibility toggle independently of each other.
+
+```typescript
+import React, { useState } from 'react';
+
+import Text, { TextChangeHandler } from '@splunk/react-ui/Text';
+
+
+const Password = () => {
+    const [value, setValue] = useState<string | undefined>('password123');
+
+    const handleChange: TextChangeHandler = (e, { value: newValue }) => {
+        setValue(newValue);
+    };
+
+    return (
+        <>
+            <Text inline type="password" value={value} onChange={handleChange} />
+
+            <br />
+            <br />
+
+            <Text inline passwordVisibilityToggle defaultValue="password123" onChange={() => {}} />
+        </>
+    );
+};
+
+export default Password;
+```
+
+
+
+### StyledButton
+
+```typescript
+import React from 'react';
+
+import styled from 'styled-components';
+
+import LinesThree from '@splunk/react-icons/LinesThree';
+import Magnifier from '@splunk/react-icons/Magnifier';
+import PaperFolded from '@splunk/react-icons/PaperFolded';
+import Portrait from '@splunk/react-icons/Portrait';
+import Button from '@splunk/react-ui/Button';
+import Text from '@splunk/react-ui/Text';
+
+const StyledButton = styled(Button)`
+    min-width: 24px;
+    min-height: 24px;
+    margin: 4px;
+`;
+
+
+const CustomizedIcon = () => (
+    <>
+        <Text defaultValue="" inline startAdornment={<div>$</div>} endAdornment={<div>.00</div>} />
+        <br />
+        <br />
+        <Text
+            defaultValue=""
+            startAdornment={
+                <div style={{ display: 'flex', alignItems: 'center' }}>
+                    <Portrait variant="filled" />
+                </div>
+            }
+            inline
+        />
+        <br />
+        <br />
+        <Text
+            defaultValue=""
+            endAdornment={
+                <>
+                    <StyledButton appearance="secondary" icon={<Magnifier />} />
+                    <span>|</span>
+                    <StyledButton appearance="secondary" icon={<PaperFolded />} />
+                </>
+            }
+            inline
+            startAdornment={<StyledButton appearance="secondary" icon={<LinesThree />} />}
+        />
+    </>
+);
+
+export default CustomizedIcon;
+```
+
+
+
+
+## API
+
+
+### Text API
+
+Note: Text places role and aria props onto the input. All other props are placed on the wrapper.
+
+#### Props
+
+| Name | Type | Required | Default | Description |
+|------|------|------|------|------|
+| append | boolean | no | false | Append removes rounded borders and the border from the right side. |
+| autoCapitalize | string | no |  | Control the browser's automatic capitalization functionality. Note: Doesn't apply to physical keyboard input. Examples: 'on', 'off', 'sentences', 'words, 'characters'. |
+| autoComplete | string | no |  | Control the browser's autofill functionality. See [the specification](https://html.spec.whatwg.org/multipage/form-control-infrastructure.html#autofilling-form-controls:-the-autocomplete-attribute) for details. Examples: 'on', 'off', 'cc-name', 'shipping street-address'. |
+| autoCorrect | string | no |  | Set the input's autocorrect attribute. Only supported by Safari. See also `spellCheck`. |
+| autoFocus | boolean | no | false | Specify that the input should request focus when mounted. |
+| canClear | boolean | no | false | Include an "X" button to clear the value. If `passwordVisibilityToggle` is `true`, this prop is ignored. |
+| children | React.ReactNode | no |  |  |
+| defaultValue | string | no |  | Set this property instead of value to make value uncontrolled. |
+| describedBy | string | no |  | The id of the description. When placed in a ControlGroup, this is automatically set to the ControlGroup's help component. |
+| disabled | boolean \| 'dimmed' | no | false | Determines whether or not the input is editable. If set to `"dimmed"`, the menu item does not respond to events but can still receive focus, and `aria-disabled` is set to `true`. |
+| elementRef | React.Ref<HTMLDivElement> | no |  | A React ref which is set to the DOM element when the component mounts, and null when it unmounts. |
+| endAdornment | React.ReactNode | no |  | Adornment after the input. |
+| error | boolean | no | false | Highlight the field as having an error. The border and text will turn red. |
+| inline | boolean | no | false | When false, display as inline-block with the default width. |
+| inputId | string | no |  | An id for the input, which may be necessary for accessibility, such as for aria attributes. |
+| inputRef | React.Ref<HTMLInputElement> | no |  | A React ref which is set to the input element when the component mounts and null when it unmounts. |
+| labelledBy | string | no |  | The id of the label. When placed in a ControlGroup, this is automatically set to the ControlGroup's label. |
+| maxLength | number | no |  | Set the input's maxlength attribute. |
+| name | string | no |  | The name is returned with onChange events, which can be used to identify the control when multiple controls share an onChange callback. |
+| onBlur | TextBlurHandler | no |  | A callback for when the input loses focus. |
+| onChange | TextChangeHandler | no |  | This is equivalent to onInput which is called on keydown, paste, and so on. If value is set, this callback is required. This must set the value prop to retain the change. |
+| onClick | React.MouseEventHandler<HTMLInputElement> | no |  | A callback for when the user clicks the textbox. This will only trigger when the textbox itself is clicked and will not trigger for other parts of the component, such as the clear button or nodes added via "startAdornment" or "endAdornment" props. |
+| onFocus | TextFocusHandler | no |  | A callback for when the input takes focus. |
+| onKeyDown | React.KeyboardEventHandler<HTMLInputElement> | no |  | A keydown callback can be used to prevent a certain input by utilizing the event argument. |
+| onSelect | React.ReactEventHandler<HTMLInputElement> | no |  | A callback for when the text selection or cursor position changes. |
+| passwordVisibilityToggle | boolean | no | false | Allow password visibility to be toggled with an icon button. If this is enabled, `type` prop will be ignored. |
+| prepend | boolean | no | false | Prepend removes rounded borders from the left side. |
+| spellCheck | boolean | no |  | Control the browser's spelling and grammar checking functionality. |
+| startAdornment | React.ReactNode | no |  | Adornment in front of the input. |
+| tabIndex | number | no | 0 |  |
+| type | string | no | 'text' | Type of the `input` element. It should be [a valid HTML5 input type](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#Form_%3Cinput%3E_types). @default 'text' |
+| value | string | no |  | The contents of the input. Setting this value makes the property controlled. A callback is required. |
+
+#### Types
+
+| Name | Type | Description |
+|------|------|------|
+| TextBlurHandler | (     event: React.FocusEvent<HTMLInputElement>,     data: {         name?: string;         value: string;     } ) => void |  |
+| TextChangeHandler | (     event: React.ChangeEvent<HTMLInputElement> \| React.MouseEvent<HTMLSpanElement>,     data: {         name?: string;         value: string;     } ) => void |  |
+| TextFocusHandler | (     event: React.FocusEvent<HTMLInputElement>,     data: {         name?: string;         value: string;     } ) => void |  |
+
+
+
+
+