@splunk/react-ui 5.7.0 → 5.8.0

package/docs-llm/Progress.md

@@ -0,0 +1,141 @@
+# Progress
+
+## Overview
+
+
+> Image: Illustration of a Progress component.
+
+
+## When to use this component
+- When users need feedback on the status of an ongoing task.
+- To show the length of a process and track its progression toward completion.
+- When the process is complex and has a long wait time.
+- When the percentage of the completed process can be determined.
+- To convey that data is being requested, transferred, or processed.
+
+## When to use another component
+- For short wait times, use a Wait Spinner.
+- For related tasks that need to be completed in a linear sequence, use a Step Bar.
+
+```mermaid
+graph TD
+    accDescr: Decision tree that guides on when to use the Progress component or something else
+    A(Is the task expected to take less than a few seconds?) -- Yes --- B(Wait Spinner)
+    A -- No --- C(Are the tasks sequential and related?)
+    C -- Yes --- D(Step Bar)
+    C -- No --- E(Progress)
+```
+
+### Check out
+- [Wait Spinner][1]
+- [Step Bar][2]
+
+## Usage
+
+### Grouping
+Display overall progress of a group rather than the progress of each item in the group.
+
+> Image: Example showing grouping of content while using the progress component. The first example with the heart eyes emoji displays the progress component at the top of the page, loading for all the contents on the page, whereas the second example with the grimacing emoji displays the progress component loading for all content sections individually.
+
+
+### Labels
+Labels should always be placed below the progress bar contained in a tooltip for accessibility. Avoid placing text inside the progress bar, this could cause clutter and poor text readability.
+
+> Image: Example showing how labels should appear while using the progress component. The first example with the heart eyes emoji displays the context label (percentage complete) inside a tool tip under the progress component, whereas the second example with the grimacing emoji displays the context label inside the progress component.
+
+
+### Screen real estate
+Avoid using the progress component in small spaces such as within a button.
+
+> Image: Example showing appropriate screen realestate for the progress component. The first example with the heart eyes emoji displays the progress component at the top of the screen, taking up a good amount of screen real estate, whereas the second example with the grimacing emoji displays the progress component cramped inside a button component.
+
+
+### Quantifiable processes
+Use a progress bar for processes that can be quantified, such as displaying a percentage (e.g., file upload). Avoid using it for stepped progress determined by user actions.
+
+> Image: Example showing what processes the label component should be used for. The first example with the heart eyes emoji displays the progress component used to showcase upload time within a table, whereas the second example with the grimacing emoji displays the progress component used to determine a user
+
+
+[1]: ./WaitSpinner
+[2]: ./StepBar
+
+## Examples
+
+
+### Basic
+
+```typescript
+import React, { useState, useEffect } from 'react';
+
+import Progress from '@splunk/react-ui/Progress';
+
+
+function Example() {
+    const [percentage, setPercentage] = useState(0);
+
+    useEffect(() => {
+        const timer = window.setInterval(() => {
+            setPercentage((currentPercentage) => {
+                if (currentPercentage >= 100) {
+                    return 0;
+                }
+                return currentPercentage + 5;
+            });
+        }, 1000);
+        return () => {
+            window.clearInterval(timer);
+        };
+    }, []);
+
+    return <Progress percentage={percentage} tooltip={`${percentage}% uploaded`} />;
+}
+
+export default Example;
+```
+
+
+
+### Type
+
+```typescript
+import React from 'react';
+
+import Progress from '@splunk/react-ui/Progress';
+
+
+function Type() {
+    return (
+        <>
+            <Progress type="info" percentage={30} />
+            <br />
+            <Progress type="success" percentage={60} />
+            <br />
+            <Progress type="error" percentage={100} />
+        </>
+    );
+}
+
+export default Type;
+```
+
+
+
+
+## API
+
+
+### Progress API
+
+#### Props
+
+| Name | Type | Required | Default | Description |
+|------|------|------|------|------|
+| elementRef | React.Ref<HTMLDivElement> | no |  | A React ref which is set to the DOM element when the component mounts and null when it unmounts. |
+| percentage | number | no |  | The percentage complete. If unset, no progress bar is shown. Percentage must be a number from 0-100. |
+| tooltip | React.ReactNode | no |  | Tooltip defaults to the percentage complete. |
+| type | 'info' \| 'success' \| 'error' | no | 'info' | Sets the appearance of the `Progress` component.  Note: `success` and `error` types are not animated. |
+
+
+
+
+

package/docs-llm/Radio Bar.md

@@ -0,0 +1,303 @@
+# Radio Bar
+
+## Overview
+
+
+> Image: Illustration of a Radio Bar component.
+
+
+## When to use this component
+- For quick selection within a form. Use only if there are less than 8 options that are simple and straightforward.
+- As a filter for related content (e.g. filter messages by “All”, “Read”, and “Unread”).
+- Useful to switch between alternate views of the same set of data in the same context. (e.g. list view, grid view, or map view).
+- If additional visual affordances and adornments, such as icons, can provide separation between options.
+
+## When to use another component
+- If vertical space is not a concern or the options labels are long, use Radio List.
+- For binary selections like “on/off”, “yes/no”, “true/false”, consider using a Switch - Toggle.
+- Use Tab Bar to change the entire display of different sets of data, as a form of navigation.
+
+```mermaid
+graph TD
+    accDescr: Decision tree that guides on when to use the RadioBar component or something else
+    A(Are users selecting an option in the context of a form?) -- Yes --- B(Are there fewer than 8 options?)
+    B -- Yes --- C(Do the options have long labels or you don't need to conserve vertical space?)
+    C -- Yes --- D(Radio List)
+    C -- No --- E(Radio Bar)
+    B -- No --- F(Select or Combo Box)
+    A -- No --- G(Do the options work as a form of navigation or switch between completely different content?)
+    G -- Yes --- H(Tabs)
+    G -- No --- I(Radio Bar)
+```
+
+### Check out
+- [Radio List][1]
+- [Switch][2]
+- [Tab Bar][3]
+- [Select][4]
+- [Combo Box][5]
+
+## Usage
+
+### Inutitive icons
+Use icon-only variants when the icons are intuitive and easy to understand.
+
+> Image: Examples of a icon-only Radio Bar with two options. In the first example with heart eyes emojis, the icons are intutive 
+
+
+### Radio Bar as a menu bar
+Radio Bar can be used outside the context of a form and behave like a menu `role="menubar"`. When used in this context, ensure the options are straightforward and mutually exclusive.
+
+> Image: Examples of a Radio Bar with two options. In the first example with heart eyes emojis, the options are 
+
+
+## Content
+
+### Be concise
+Keep option labels short and concise to prevent text wrapping. Use sentence-case capitalization and avoid punctuation and articles (“the”, “an”, “a”).
+
+> Image: Examples of a Radio Bar with two options. In the first example with heart eyes emojis, the options are 
+
+
+[1]: ./RadioList
+[2]: ./Switch
+[3]: ./TabBar
+[4]: ./Select
+[5]: ./ComboBox
+
+## Examples
+
+
+### Controlled
+
+```typescript
+import React, { useState } from 'react';
+
+import RadioBar, { RadioBarChangeHandler } from '@splunk/react-ui/RadioBar';
+
+
+function Basic() {
+    const [value, setValue] = useState(3);
+
+    const handleChange: RadioBarChangeHandler = (e, { value: radioValue }) => {
+        setValue(radioValue);
+    };
+
+    return (
+        <RadioBar onChange={handleChange} value={value} style={{ width: 500 }}>
+            <RadioBar.Option value={1} label="one" />
+            <RadioBar.Option value={2} label="two" />
+            <RadioBar.Option value={3} label="threethreethree" />
+            <RadioBar.Option value={4} label="four" />
+        </RadioBar>
+    );
+}
+
+export default Basic;
+```
+
+
+
+### Uncontrolled
+
+```typescript
+import React from 'react';
+
+import RadioBar from '@splunk/react-ui/RadioBar';
+
+
+function Uncontrolled() {
+    return (
+        <RadioBar defaultValue={2} style={{ width: 500 }}>
+            <RadioBar.Option value={1} label="one" />
+            <RadioBar.Option value={2} label="two" />
+            <RadioBar.Option value={3} label="threethreethree" />
+            <RadioBar.Option value={4} label="four" />
+        </RadioBar>
+    );
+}
+
+export default Uncontrolled;
+```
+
+
+
+### Error
+
+```typescript
+import React from 'react';
+
+import RadioBar from '@splunk/react-ui/RadioBar';
+
+
+function RadioBarError() {
+    return (
+        <RadioBar defaultValue={2} style={{ width: 500 }} error>
+            <RadioBar.Option value={1} label="one" />
+            <RadioBar.Option value={2} label="two" />
+            <RadioBar.Option value={3} label="threethreethree" />
+            <RadioBar.Option value={4} label="four" />
+        </RadioBar>
+    );
+}
+
+export default RadioBarError;
+```
+
+
+
+### Disabled
+
+Either the entire RadioBar or individual Options can be disabled using the disabled prop. When set on the RadioBar, this overrides any individual Option disabled states.
+
+```typescript
+import React from 'react';
+
+import RadioBar from '@splunk/react-ui/RadioBar';
+
+
+function Disabled() {
+    return (
+        <RadioBar defaultValue={2} disabled style={{ width: 500 }}>
+            <RadioBar.Option value={1} label="one" />
+            <RadioBar.Option value={2} label="two" />
+            <RadioBar.Option value={3} label="threethreethree" />
+            <RadioBar.Option value={4} label="four" />
+        </RadioBar>
+    );
+}
+
+export default Disabled;
+```
+
+
+
+### Adornments using `aria-*` attributes
+
+```typescript
+import React from 'react';
+
+import styled from 'styled-components';
+
+import ChartArea from '@splunk/react-icons/ChartArea';
+import ChartBubble from '@splunk/react-icons/ChartBubble';
+import ChartLine from '@splunk/react-icons/ChartLine';
+import Plus from '@splunk/react-icons/Plus';
+import Chip from '@splunk/react-ui/Chip';
+import RadioBar from '@splunk/react-ui/RadioBar';
+import { mixins, variables } from '@splunk/themes';
+
+const StyledNewChip = styled(Chip)`
+    ${mixins.typography('smallBody', { weight: 'bold' })}
+    background-color: ${variables.notificationColorInfoWeak};
+    height: calc(${variables.inputHeight} - ${variables.spacingMedium});
+`;
+
+
+function AdornmentAriaExamples() {
+    return (
+        <RadioBar defaultValue={3} style={{ width: 800 }}>
+            <RadioBar.Option value={1} label="Option one" endAdornment={<ChartLine />} />
+            <RadioBar.Option value={2} label="Option two" startAdornment={<ChartBubble />} />
+
+            <RadioBar.Option
+                value={3}
+                label="Option three"
+                aria-describedby="new"
+                endAdornment={<StyledNewChip id="new">New</StyledNewChip>}
+            />
+
+            <RadioBar.Option
+                value={4}
+                label="Option four"
+                startAdornment={<Plus />}
+                endAdornment={<ChartArea />}
+            />
+        </RadioBar>
+    );
+}
+
+export default AdornmentAriaExamples;
+```
+
+
+
+### menubar
+
+Radio Bar can be used outside of a form context to behave like a menu bar by setting role="menubar"
+
+```typescript
+import React, { useState } from 'react';
+
+import RadioBar, { RadioBarChangeHandler } from '@splunk/react-ui/RadioBar';
+
+
+function MenuBar() {
+    const [value, setValue] = useState('ts');
+
+    const handleChange: RadioBarChangeHandler = (e, { value: radioValue }) => {
+        setValue(radioValue);
+    };
+
+    return (
+        <RadioBar role="menubar" onChange={handleChange} value={value}>
+            <RadioBar.Option value="ts" label="Typescript" />
+            <RadioBar.Option value="js" label="Javascript" />
+        </RadioBar>
+    );
+}
+
+export default MenuBar;
+```
+
+
+
+
+## API
+
+
+### RadioBar API
+
+RadioBar is a form control that provides the ability to select one option out of a group.
+
+#### Props
+
+| Name | Type | Required | Default | Description |
+|------|------|------|------|------|
+| children | React.ReactNode | no |  | `children` should be `RadioBar.Option`. |
+| defaultValue | string \| number \| boolean | no |  | The default value. Only applicable if this is an uncontrolled component. Otherwise, use the value prop. |
+| 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 | Disable all options in the RadioBar. This will override the disabled prop on any individual Option. |
+| elementRef | React.Ref<HTMLDivElement> | no |  | A React ref which is set to the DOM element when the component mounts, and null when it unmounts. |
+| error | boolean | no |  | Highlight the field as having an error. The buttons will turn red. |
+| inline | boolean | no |  |  |
+| labelledBy | string | no |  | The id of the label. When placed in a ControlGroup, this is automatically set to the ControlGroup's label. |
+| 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. |
+| onChange | RadioBarChangeHandler | no |  | A callback that receives the new value. |
+| role | 'radiogroup' \| 'menubar' | no | 'radiogroup' | The role of the RadioBar. The children Options' `role` will be set to `radio` or `menuitemradio` respectively. |
+| value | string \| number \| boolean | no |  | The currently selected value. Only applicable if this is a controlled component. |
+
+#### Types
+
+| Name | Type | Description |
+|------|------|------|
+| RadioBarChangeHandler | (     e: React.MouseEvent<HTMLButtonElement \| HTMLAnchorElement> \| React.KeyboardEvent<HTMLElement>,     data: {         label?: string;         name?: string;         value: any; // eslint-disable-line @typescript-eslint/no-explicit-any     } ) => void |  |
+
+
+
+### RadioBar.Option API
+
+#### Props
+
+| Name | Type | Required | Default | Description |
+|------|------|------|------|------|
+| disabled | boolean | no |  | Add a disabled attribute and prevent clicking. |
+| endAdornment | React.ReactNode | no |  | Adornment after the label. |
+| label | string | no |  | The text shown on the button. |
+| startAdornment | React.ReactNode | no |  | Adornment in front of the label. |
+| value | any | yes |  | The value of the `Option`. |
+
+
+
+
+