@splunk/react-ui 5.7.1 → 5.8.0

package/docs-llm/Radio List.md

@@ -0,0 +1,350 @@
+# Radio List
+
+## Overview
+
+
+> Image: Illustration of a Radio List component.
+
+
+## When to use this component
+- To select a single option from a set of two or more that are mutually exclusive.
+- Exposing all available options would benefits the user.
+
+## When to use another component
+- The options a user has are opposing states (e.g. on/off, before/after). Use a Switch instead.
+- More than one option can be selected; use a Checkbox or Multiselect component.
+- Visual indicators (like icons for Radio Bar) help the user find an option faster.
+- Options can be collapsed; use Select or Combo Box  to conserve space.
+
+```mermaid
+graph TD
+    accDescr: Decision tree that guides on when to use the RadioList component or something else
+    A(Are there fewer than 8 options?) -- Yes --- B("Do the options have long labels or you don't need to conserve vertical space?")
+    B -- Yes --- C(Radio List)
+    B -- No --- D(Radio Bar)
+    A -- No --- E(Select or Combo Box)
+```
+
+### Check out
+- [Switch][1]
+- [Multiselect][2]
+- [Select][3]
+- [Radio Bar][4]
+- [Combo Box][5]
+
+## Behaviors
+
+### Customization
+Child elements, like a text input, can be included if necessary.
+
+> Image: Image of a Radio List with the label, 
+
+
+## Usage
+
+### Always include a label
+> Image: Examples of a Radio List with the three options, 
+
+
+### Make options distinct
+Users should be able to easily differentiate between options.
+> Image: Examples of mutual exclusivity: The first example with the heart eyes emoji shows a Radio List with the options, 
+
+
+### List options in a logical order
+Order your list of options in a way that will make the most sense. Possible orders include:
+- Most likely to least likely to be selected
+- Simplest to most complex operation
+- Least to most risk
+
+> Image: Examples of a Radio List with label 
+
+
+### Default option
+An option must be selected at all times. If you need an unselected state, add a "None" option.
+
+> Image: Examples of a Radio List with label 
+
+
+
+## Content
+
+### Avoid punctuation and articles (“the”, “an”, “a”)
+Be descriptive, not instructional. If the selection needs more explanation, use help text.
+
+> Image: Examples of label punctuation: The first example with the heart eyes emoji shows a Radio List with the label, 
+
+
+### Keep descriptions concise
+Descriptions should be text only and short enough that bullet points aren't needed. If more detail is needed, move the description outside of the radio list.
+
+> Image: Examples of description length: The first example with the heart eyes emoji shows a Radio List with label 
+
+
+[1]: ./Switch
+[2]: ./Multiselect
+[3]: ./Select
+[4]: ./RadioBar
+[5]: ./ComboBox
+
+## Examples
+
+
+### Controlled
+
+Radio List requires a value prop and an onChange callback to update the value prop for most use cases.
+
+```typescript
+import React, { useState } from 'react';
+
+import RadioList, { RadioListChangeHandler, RadioListValueTypes } from '@splunk/react-ui/RadioList';
+
+
+function Basic() {
+    const [value, setValue] = useState<RadioListValueTypes>(2);
+
+    const handleChange: RadioListChangeHandler = (e, { value: radioValue }) => {
+        setValue(radioValue);
+    };
+
+    return (
+        <RadioList value={value} onChange={handleChange}>
+            <RadioList.Option value={1}>One</RadioList.Option>
+            <RadioList.Option value={2}>Two</RadioList.Option>
+            <RadioList.Option value={3}>Three three three</RadioList.Option>
+            <RadioList.Option disabled value={4}>
+                Four
+            </RadioList.Option>
+        </RadioList>
+    );
+}
+
+export default Basic;
+```
+
+
+
+### Uncontrolled
+
+Alternately, Radio List 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 RadioList from '@splunk/react-ui/RadioList';
+
+
+function Uncontrolled() {
+    return (
+        <RadioList defaultValue={2}>
+            <RadioList.Option value={1}>One</RadioList.Option>
+            <RadioList.Option value={2}>Two</RadioList.Option>
+            <RadioList.Option value={3}>Three three three</RadioList.Option>
+            <RadioList.Option value={4}>Four</RadioList.Option>
+        </RadioList>
+    );
+}
+
+export default Uncontrolled;
+```
+
+
+
+### Disabled
+
+```typescript
+import React, { useState } from 'react';
+
+import RadioList, { RadioListChangeHandler, RadioListValueTypes } from '@splunk/react-ui/RadioList';
+
+
+function Disabled() {
+    const [value, setValue] = useState<RadioListValueTypes>(2);
+
+    const handleChange: RadioListChangeHandler = (e, { value: radioValue }) => {
+        setValue(radioValue);
+    };
+
+    return (
+        <RadioList value={value} disabled onChange={handleChange}>
+            <RadioList.Option value={1}>One</RadioList.Option>
+            <RadioList.Option value={2}>Two</RadioList.Option>
+            <RadioList.Option value={3}>Three three three</RadioList.Option>
+            <RadioList.Option disabled value={4}>
+                Four
+            </RadioList.Option>
+        </RadioList>
+    );
+}
+
+export default Disabled;
+```
+
+
+
+### Error
+
+```typescript
+import React, { useState } from 'react';
+
+import RadioList, { RadioListChangeHandler, RadioListValueTypes } from '@splunk/react-ui/RadioList';
+
+
+function RadioListError() {
+    const [value, setValue] = useState<RadioListValueTypes>(2);
+
+    const handleChange: RadioListChangeHandler = (e, { value: radioValue }) => {
+        setValue(radioValue);
+    };
+
+    return (
+        <RadioList value={value} onChange={handleChange} error>
+            <RadioList.Option value={1}>One</RadioList.Option>
+            <RadioList.Option value={2}>Two</RadioList.Option>
+            <RadioList.Option value={3}>Three three three</RadioList.Option>
+            <RadioList.Option value={4}>Four</RadioList.Option>
+        </RadioList>
+    );
+}
+
+export default RadioListError;
+```
+
+
+
+### Description
+
+```typescript
+import React from 'react';
+
+import RadioList from '@splunk/react-ui/RadioList';
+
+
+function Description() {
+    return (
+        <RadioList defaultValue={2}>
+            <RadioList.Option value={1} description="This is the first option.">
+                One
+            </RadioList.Option>
+            <RadioList.Option value={2} description="This is the second option.">
+                Two
+            </RadioList.Option>
+            <RadioList.Option value={3} description="This is the third option.">
+                Three three three
+            </RadioList.Option>
+            <RadioList.Option value={4} description="This is the fourth option.">
+                Four
+            </RadioList.Option>
+        </RadioList>
+    );
+}
+
+export default Description;
+```
+
+
+
+
+## API
+
+
+### RadioList API
+
+#### Props
+
+| Name | Type | Required | Default | Description |
+|------|------|------|------|------|
+| children | React.ReactNode | no |  | `children` should be `RadioList.Option`s. |
+| defaultValue | number \| string \| boolean \| Record<string, unknown> \| symbol | no |  | Set this property instead of value to make value uncontrolled. |
+| direction | 'column' \| 'row' | no |  | **DEPRECATED**: This prop is deprecated and will be removed in the next major version. Changes the layout of the RadioList. |
+| disabled | boolean | no | false |  |
+| 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 | false | Highlight the field as having an error. The buttons and labels will turn red. |
+| 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. A randomly generated name is used if one is not provided. |
+| onChange | RadioListChangeHandler | no |  | A callback to receive the change events. If value is set, this callback is required. This must set the value prop to retain the change. |
+| value | number \| string \| boolean \| Record<string, unknown> \| symbol | no |  | The current selected value.  Setting this value makes the property controlled. A callback is required. |
+
+#### Types
+
+| Name | Type | Description |
+|------|------|------|
+| RadioListChangeHandler | (     event: React.ChangeEvent<HTMLInputElement>,     data: { name?: string; value: RadioListValueTypes } ) => void |  |
+
+
+
+### RadioList.Option API
+
+#### Props
+
+| Name | Type | Required | Default | Description |
+|------|------|------|------|------|
+| children | React.ReactNode | no |  |  |
+| description | string | no |  | Additional information to explain the option. |
+| disabled | boolean | no | false |  |
+| error | boolean | no | false |  |
+| id | string | no |  |  |
+| onChange | RadioListChangeHandler | no |  |  |
+| value | RadioListValueTypes | yes |  | The selectable value. If this matches the ControlRadioList value, the item is selected. |
+
+
+
+
+
+## Accessibility
+
+## Visual Design
+
+- Color contrast ratio **MUST** be:
+    - &gt=4.5:1 for...[SC 1.4.3][1]
+        - Label text to page-background (all states)
+    - &gt=3:1 for...[SC 1.4.11][2]
+        - Circle to toggle-background-color (selected)
+        - Toggle-background-color to page-background (selected)
+        - Border to page-background (unselected)
+    - Focus State: if the focus ring has a radius of [SC 1.4.11][2]
+        - &lt 3px: &gt=4.5.1 between button &lt&gt focus &lt&gt background
+        - &gt 3px: &gt=3.1 between button &lt&gt focus &lt&gt background
+
+## States
+
+- Color contrast rules do not apply to disabled radio buttons
+
+## Interaction Model
+
+### Focus management
+- For radio groups not in a toolbar (most cases), keyboard navigation **MUST** have [SC 2.1][3]
+    - <kbd>Tab</kbd> and <kbd>Shift</kbd>+<kbd>Tab</kbd> to move focus into and out of the radio group.
+        When focus moves into a radio group : 
+
+        - If a radio button is checked, focus is set on the checked button.
+        - If none of the radio buttons are checked, focus is set on the first radio button in the group.
+    - <kbd>Space</kbd> to check the focused radio button if it is not already checked.
+    - <kbd>Right/Down Arrow</kbd> to move focus to the next radio button in the group, uncheck the
+        previously focused button, and check the newly focused button. If focus is on the last button,
+        focus moves to the first button.
+    - <kbd>Left/Up Arrow</kbd> to move focus to the previous radio button in the group, uncheck the
+        previously focused button, and check the newly focused button. If focus is on the first button,
+        focus moves to the last button.
+- For Radio Group inside a toolbar, consult [WAI-ARIA][4]
+
+## Implementation
+
+- Every radio button **MUST** have...[SC 4.1.2][5]
+    - label (name)--visible label referenced by `aria-labelledby`, or a label specified with aria-label
+    - `"radio"` role
+    - `"checked"` or `"unchecked"` (value)
+    - `aria-checked` set to either `"true"` (checked) or `"false"` (unchecked)
+- A group of radio buttons **MUST** ...
+    - be contained in or owned by an element with the role radiogroup.
+    - have a visible label referenced by `aria-labelledby` or has a label specified with aria-label
+- If elements providing additonal information about either the radio group or each radio button are present, those elements **MUST** be labeled using one of the following:
+    - the `aria-describedby` property
+    - radiogroup element
+    - radio element
+
+[1]: https://www.w3.org/TR/WCAG21/#contrast-minimum
+[2]: https://www.w3.org/TR/WCAG21/#non-text-contrast
+[3]: https://www.w3.org/TR/WCAG21/#keyboard-accessible
+[4]: https://www.w3.org/TR/wai-aria-practices-1.1/#for-radio-group-contained-in-a-toolbar
+[5]: https://www.w3.org/TR/WCAG21/#name-role-value
+

package/docs-llm/Resize.md

@@ -0,0 +1,362 @@
+# Resize
+
+## Examples
+
+
+### Basic
+
+The onRequestResize handler must handle any desired constraints on size.
+
+```typescript
+import React, { useState } from 'react';
+
+import Resize, { ResizeRequestResizeHandler } from '@splunk/react-ui/Resize';
+
+
+function Basic() {
+    const [state, setState] = useState({
+        height: 200,
+        width: 400,
+    });
+
+    const onRequestResize: ResizeRequestResizeHandler = (e, { height, width }) => {
+        const constrainedHeight = Math.min(Math.max(height, 100), 400);
+        const constrainedWidth = Math.min(Math.max(width, 300), 600);
+        setState({ height: constrainedHeight, width: constrainedWidth });
+    };
+
+    return (
+        <Resize
+            resizeHandles={['se']}
+            onRequestResize={onRequestResize}
+            style={{
+                height: state.height,
+                width: state.width,
+                padding: 20,
+                border: '1px solid #ccc',
+            }}
+        >
+            I am content.
+        </Resize>
+    );
+}
+
+export default Basic;
+```
+
+
+
+### Appearance
+
+Resize handles can be placed on any edge or corner. Note that margin cannot be overridden when using the "border" appearance.
+
+```typescript
+import React, { useState } from 'react';
+
+import Multiselect, { MultiselectChangeHandler } from '@splunk/react-ui/Multiselect';
+import RadioBar, { RadioBarChangeHandler } from '@splunk/react-ui/RadioBar';
+import Resize, { ResizeDirection, ResizeRequestResizeHandler } from '@splunk/react-ui/Resize';
+import { useSplunkTheme } from '@splunk/themes';
+
+interface State {
+    appearance: 'border' | 'overlay' | 'separator';
+    height: number;
+    resizeHandles: ResizeDirection[];
+    showHandles: 'always' | 'on-hover';
+    width: number;
+}
+
+
+function Appearance() {
+    const [state, setState] = useState<State>({
+        height: 200,
+        width: 200,
+        appearance: 'border',
+        showHandles: 'always',
+        resizeHandles: ['nw', 'n', 'ne', 'w', 'e', 'sw', 's', 'se'],
+    });
+
+    const onRequestResize: ResizeRequestResizeHandler = (e, { height, width }) => {
+        setState({ ...state, height, width });
+    };
+
+    const onChangeAppearance: RadioBarChangeHandler = (e, { value }) => {
+        setState({ ...state, appearance: value });
+    };
+
+    const onChangeShowHandles: RadioBarChangeHandler = (e, { value }) => {
+        setState({ ...state, showHandles: value });
+    };
+
+    const onChangeHandles: MultiselectChangeHandler = (e, { values }) => {
+        setState({ ...state, resizeHandles: values as ResizeDirection[] });
+    };
+
+    const { spacingSmall, spacingXLarge } = useSplunkTheme();
+
+    return (
+        <div>
+            <div
+                style={{
+                    marginBottom: spacingXLarge,
+                    display: 'flex',
+                    gap: spacingSmall,
+                }}
+            >
+                <RadioBar onChange={onChangeAppearance} value={state.appearance}>
+                    <RadioBar.Option value="overlay" label="overlay" />
+                    <RadioBar.Option value="border" label="border" />
+                    <RadioBar.Option value="separator" label="separator" />
+                </RadioBar>
+                <RadioBar onChange={onChangeShowHandles} value={state.showHandles}>
+                    <RadioBar.Option value="always" label="always" />
+                    <RadioBar.Option value="on-hover" label="on-hover" />
+                </RadioBar>
+                <Multiselect onChange={onChangeHandles} values={state.resizeHandles}>
+                    <Multiselect.Option value="n" label="n" />
+                    <Multiselect.Option value="ne" label="ne" />
+                    <Multiselect.Option value="e" label="e" />
+                    <Multiselect.Option value="se" label="se" />
+                    <Multiselect.Option value="s" label="s" />
+                    <Multiselect.Option value="sw" label="sw" />
+                    <Multiselect.Option value="w" label="w" />
+                    <Multiselect.Option value="nw" label="nw" />
+                </Multiselect>
+            </div>
+            <div
+                style={{
+                    border: '1px solid #d6d6d6',
+                    display: 'inline-block',
+                }}
+            >
+                <Resize
+                    resizeHandles={state.resizeHandles}
+                    onRequestResize={onRequestResize}
+                    appearance={state.appearance}
+                    showHandles={state.showHandles}
+                    style={{
+                        height: state.height,
+                        width: state.width,
+                    }}
+                >
+                    <div
+                        style={{
+                            left: '50%',
+                            top: '50%',
+                            transform: 'translate(-50%, -50%)',
+                            position: 'absolute',
+                            textAlign: 'center',
+                        }}
+                    >
+                        I am content.
+                    </div>
+                </Resize>
+            </div>
+        </div>
+    );
+}
+
+export default Appearance;
+```
+
+
+
+### Sizing outer
+
+Resize does not dictate how it is sized. In this example, styles are placed on an outer container.
+
+```typescript
+import React, { useState } from 'react';
+
+import Resize, { ResizeRequestResizeHandler } from '@splunk/react-ui/Resize';
+
+
+function SizingOuter() {
+    const [state, setState] = useState({
+        height: 200,
+        width: 200,
+    });
+    const onRequestResize: ResizeRequestResizeHandler = (e, { height, width }) => {
+        setState({ height, width });
+    };
+
+    return (
+        <div // Width and height on outer container
+            style={{
+                height: state.height,
+                width: state.width,
+                border: '1px solid #ccc',
+                backgroundColor: 'rgba(128, 128, 128, 0.2)',
+                position: 'relative',
+            }}
+        >
+            <Resize
+                resizeHandles={['se']}
+                onRequestResize={onRequestResize}
+                style={{
+                    position: 'absolute',
+                    top: 0,
+                    right: 0,
+                    bottom: 0,
+                    left: 0,
+                    padding: 20,
+                }}
+            >
+                Width and height on outer container
+            </Resize>
+        </div>
+    );
+}
+
+export default SizingOuter;
+```
+
+
+
+### Sizing inner
+
+In this example, styles are placed on the inner content.
+
+```typescript
+import React, { useState } from 'react';
+
+import Resize, { ResizeRequestResizeHandler } from '@splunk/react-ui/Resize';
+
+
+function SizingInner() {
+    const [state, setState] = useState({
+        height: 200,
+        width: 200,
+    });
+
+    const onRequestResize: ResizeRequestResizeHandler = (e, { height, width }) => {
+        setState({ height: height - 2, width: width - 2 }); // border adjustment
+    };
+
+    return (
+        <Resize // Width and height on inner container
+            resizeHandles={['se']}
+            onRequestResize={onRequestResize}
+            style={{
+                border: '1px solid #ccc',
+                display: 'inline-block',
+            }}
+        >
+            <div
+                style={{
+                    width: state.width,
+                    height: state.height,
+                    backgroundColor: 'rgba(128, 128, 128, 0.2)',
+                    padding: 20,
+                    boxSizing: 'border-box',
+                }}
+            >
+                Width and height on inner container
+            </div>
+        </Resize>
+    );
+}
+
+export default SizingInner;
+```
+
+
+
+### Percentage
+
+Sizes don't need to be defined in pixels or with height and width styles. Here, flex-basis is calculated as a percentage.
+
+```typescript
+import React, { useRef, useState } from 'react';
+
+import Resize, { ResizeRequestResizeHandler } from '@splunk/react-ui/Resize';
+
+
+function Percentage() {
+    const el = useRef<HTMLDivElement | null>(null);
+
+    const [percentage, setPercentage] = useState(50);
+
+    const onRequestResize: ResizeRequestResizeHandler = (e, { width }) => {
+        if (el.current) {
+            const calculatedPercentage = Math.max((width / el.current.clientWidth) * 100);
+            const percentageValue = Math.min(Math.max(calculatedPercentage, 10), 90);
+
+            setPercentage(percentageValue);
+        }
+    };
+
+    return (
+        <div
+            ref={el}
+            style={{
+                minHeight: 100,
+                display: 'flex',
+            }}
+        >
+            <Resize
+                resizeHandles={['e']}
+                onRequestResize={onRequestResize}
+                appearance="separator"
+                style={{
+                    flexBasis: `${percentage}%`,
+                    backgroundColor: 'rgba(128, 128, 128, 0.2)',
+                }}
+            >
+                <div
+                    style={{
+                        padding: 20,
+                    }}
+                >
+                    Left side
+                </div>
+            </Resize>
+            <div
+                style={{
+                    flexGrow: 1,
+                    backgroundColor: 'rgba(128, 200, 128, 0.2)',
+                    padding: 20,
+                }}
+            >
+                Right side
+            </div>
+        </div>
+    );
+}
+
+export default Percentage;
+```
+
+
+
+
+## API
+
+
+### Resize API
+
+Resize is a utility container with drag handles for resizing.
+
+#### Props
+
+| Name | Type | Required | Default | Description |
+|------|------|------|------|------|
+| appearance | 'border' \| 'overlay' \| 'separator' | no | 'overlay' | The appearance of the resize handles. Note: When appearance is 'separator', active full length borders will only appear for 'n', 's', 'e', or 'w' `resizeHandles`. |
+| children | React.ReactNode | no |  |  |
+| elementRef | React.Ref<HTMLDivElement> | no |  | A React ref which is set to the DOM element when the component mounts and null when it unmounts. |
+| keyIncrement | number | no | 10 | When focused on a resize handle, the arrow keys will adjust the height or width by this amount with each press. |
+| onRequestResize | ResizeRequestResizeHandler | yes |  | A callback which is passed the event and an object with the requested height and width. |
+| resizeHandles | ResizeDirection[] | yes |  | An array of resize handles placements. |
+| showHandles | 'always' \| 'on-hover' | no | 'always' | The appearance of the resize handles. |
+
+#### Types
+
+| Name | Type | Description |
+|------|------|------|
+| ResizeDirection | 'nw' \| 'n' \| 'ne' \| 'w' \| 'e' \| 'sw' \| 's' \| 'se' |  |
+| ResizeRequestResizeHandler | (     event: MouseEvent \| React.KeyboardEvent<HTMLButtonElement>,     data: { height: number; width: number } ) => void |  |
+
+
+
+
+