@splunk/react-ui 5.7.0 → 5.8.0

package/docs-llm/Checkbox.md

@@ -0,0 +1,218 @@
+# Checkbox
+
+## Overview
+
+
+> Image: Illustration of Checkbox 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
+Checkbox lets users select one or more options from a list. Use it for simple, binary choices where multiple selections are allowed.
+
+- When users need to select multiple items independently (e.g., filter options, preferences)
+- When you want to present a list of options that aren't mutually exclusive
+- In forms where several related options can be enabled together
+
+## When to use another component
+- If selecting a single option from a set of two or more that are mutually exclusive and don't map to a boolean relationship (such as on/off) use `Radio List` or `Radio Bar`
+- If multiple options can be selected from a long list of items, use `Multiselect`
+- If there's a binary choice for enabling a setting, like on/off, true/false, enable/disable, or activate/deactivate, use `Switch` with `appearance="toggle"`
+- If there are multiple options, space conservation is important, and only one option can be selected at a time use a `Select` or `Combobox`
+
+```mermaid
+graph TD
+    accDescr: Decision tree that guides on when to use the Checkbox component or something else
+    A(Can the user select more than 1 option?)
+    A -- Yes --- B(Are there fewer than 5 options and you don't need to conserve space?)
+    B -- Yes --- C(Checkbox group)
+    B -- No --- D(Multiselect)
+    A -- No --- E("Do the options have a boolean (Ex. on/off) relationship?")
+    E -- Yes --- F(Toggle)
+    E -- No --- G(Are there fewer than 5 options and you don't need to conserve space?)
+    G -- Yes --- H(Radio List or Radio Bar)
+    G -- No --- I(Select or ComboBox)
+```
+
+### Check out
+- [RadioList][1]
+- [RadioBar][2]
+- [Multiselect][3]
+- [Switch][4]
+- [Select][5]
+- [ComboBox][6]
+
+## Usage
+
+### Group related options
+
+Present checkboxes together for related choices. Grouping improves clarity and helps users scan options quickly.
+
+> Image: The first example with heart eyes emoji shows grouped checkboxes with clear labels. The second example with grimacing emoji shows scattered checkboxes that are hard to scan.
+
+
+### Consistent labeling in groups
+
+Ensure labeling is consistent in checkbox groups so users can easily distinguish between the items.
+
+> Image: Examples of a group of three checkboxes. The checkboxes in the heart eyes example have the labels, 
+
+
+## Content
+
+### Labels
+
+Keep labels concise by using one to three words. Apply sentence-style capitalization and ensure each label clearly describes the option’s function.
+
+> Image: The first example with heart eyes emoji shows concise, clear labels. The second example with grimacing emoji shows labels that are too long or vague.
+
+
+
+[1]: ./RadioList
+[2]: ./RadioBar
+[3]: ./Multiselect
+[4]: ./Switch
+[5]: ./Select
+[6]: ./ComboBox
+
+## Examples
+
+
+### Controlled
+
+Checkbox can be controlled using the checked prop and an onChange callback.
+
+```typescript
+import React, { useState } from 'react';
+
+import Checkbox, { CheckboxChangeHandler } from '@splunk/react-ui/Checkbox';
+
+
+const Basic = () => {
+    const [checkedTandC, setCheckedTandC] = useState<boolean>(true);
+    const [checkedEmail, setCheckedEmail] = useState<boolean>(false);
+
+    const handleEmailChange: CheckboxChangeHandler = (e, { checked: newChecked }) => {
+        setCheckedEmail(newChecked);
+    };
+
+    const handleTandCChange: CheckboxChangeHandler = (e, { checked: newChecked }) => {
+        setCheckedTandC(newChecked);
+    };
+
+    return (
+        <>
+            <Checkbox checked={checkedTandC} onChange={handleTandCChange}>
+                I accept the terms and conditions
+            </Checkbox>
+            <Checkbox checked={checkedEmail} onChange={handleEmailChange}>
+                Send me email updates
+            </Checkbox>
+        </>
+    );
+};
+
+export default Basic;
+```
+
+
+
+### Uncontrolled
+
+Checkbox can also used as an uncontrolled component, using defaultChecked to set the initial checked state.
+
+```typescript
+import React from 'react';
+
+import Checkbox from '@splunk/react-ui/Checkbox';
+
+
+const Uncontrolled = () => {
+    return (
+        <>
+            <Checkbox defaultChecked>I accept the terms and conditions</Checkbox>
+            <Checkbox>Send me email updates</Checkbox>
+        </>
+    );
+};
+
+export default Uncontrolled;
+```
+
+
+
+### Disabled
+
+```typescript
+import React from 'react';
+
+import Checkbox from '@splunk/react-ui/Checkbox';
+
+
+const Disabled = () => {
+    return <Checkbox disabled>This option is disabled</Checkbox>;
+};
+
+export default Disabled;
+```
+
+
+
+### Error
+
+```typescript
+import React, { useState } from 'react';
+
+import Checkbox, { CheckboxChangeHandler } from '@splunk/react-ui/Checkbox';
+
+
+function CheckboxError() {
+    const [checked, setChecked] = useState<boolean>();
+
+    const handleChange: CheckboxChangeHandler = (e, { checked: newChecked }) => {
+        setChecked(newChecked);
+    };
+
+    return (
+        <Checkbox checked={checked} error={!checked} onChange={handleChange}>
+            I accept the terms and conditions
+        </Checkbox>
+    );
+}
+
+export default CheckboxError;
+```
+
+
+
+
+## API
+
+
+### Checkbox API
+
+#### Props
+
+| Name | Type | Required | Default | Description |
+|------|------|------|------|------|
+| checked | boolean \| 'indeterminate' | no |  | Setting this value makes the component controlled. If set, the onChange callback is required. A setting of "indeterminate" is considered unchecked for the purposes of form submission. |
+| children | React.ReactNode | no |  | The content to display inside the checkbox label. |
+| defaultChecked | boolean | no |  | Set this property instead of checked to make the component 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 |  |  |
+| 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 |  | Mark the component as having an error. |
+| inert | boolean | no |  |  |
+| 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. |
+| 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 | (     event: React.ChangeEvent<HTMLInputElement>,     data: {         checked: boolean;         name?: string;         value?: string;     } ) => void | no |  | Fires when the checked state changes. |
+| value | string | no |  | Returned by the onChange handler and submitted during form submission if the checkbox is checked. This defaults to "on" if the input is checked. |
+
+
+
+
+

package/docs-llm/Chip.md

@@ -0,0 +1,291 @@
+# Chip
+
+## Overview
+
+
+> Image: Illustration of a group of three Chips.
+
+
+## When to use this component
+- When you need to represent a large number of items in a limited amount of space. Ideal for use in list or grid format.
+
+## When to use another component
+- `Chip` is limited in hierarchical affordances, such as key-value pairs or sub categories. Using a `List` or `DefinitionList` can provide a more organized representation of a collection of items.
+- Interactivity of `Chip` is limited, `Multiselect` provides a structured experience for selecting one or more options from a set.
+- Due to the compact design, Chips can be difficult to discover. If the information represents a status change that is evoked by user action, consider including `Message` or `MessageBar`.
+
+```mermaid
+graph TD
+    accDescr: Decision tree that guides on when to use the Chip component or something else
+    A(Can each item in the group be represented with only a 1-3 word label?) -- Yes --- B(Is a robust interactive experience needed, including actions such as searching and scrolling?)
+    B -- Yes --- C(Multiselect)
+    B -- No --- D(Chip)
+    A -- No --- E(List or Definition List)
+```
+
+### Check out
+- [Button][1]
+- [Link][2]
+- [Multiselect][3]
+
+## Usage
+
+### Grouping
+A Chip works best in a group. Using a single Chip often loses the benefits of Chips, which is representing a large number of items in a limited amount of space.
+
+> Image: Example with two modals. The first modal example with heart eyes emoji has a group of three Chips. The second example with a grimacing emoji only displays a single Chip.
+
+
+### Removable Chips
+When a `Chip` is removable, it’s best to allow users to also be able to add `Chip` back.
+
+> Image: Examples of a group of two removable Chips. The example with the heart eyes includes an add button, where users can add more Chips. The second example with a grimacing emoji shows no way to add more Chips.
+
+
+### Consistent interactions
+Keep interactions consistent across the group.
+
+> Image: Examples of two Chips. The first example with heart eyes shows two removable Chips. The second example with a grimacing face shows one Chip that is removable and one Chip that isn
+
+
+### Group organization
+To improve scannability, a Chip group should flow like words in a paragraph, rather than a vertical list.
+
+> Image: Example of a group of three Chips. The first example with heart eyes shows the group aligned horizontally. The second example with a grimacing face the group aligned vertically.
+
+
+### Large groups
+When space is limited, such as in a table, the Chip group may overflow the space. A label like ‘3 more Chips’ makes this screen reader accessible. It is also important to provide a detailed view where users can view the entire Chip group.
+
+> Image: Example of Chips within a table with 3 columns; Name, Groups, which includes the Chips, and Status. In the modal with the heart eyes, there is two chips and a plus two Chip which on hover, displayed a third Chip that do not fit in the column. The modal with a grimacing face does not have the plus two Chip, resulting in the third chip running into the next column, cutting off the name of the Chip.
+
+
+## Content
+
+### Write concise labels: 1-3 words
+
+> Image: Examples of chip label length. The first example with heart eyes emoji has a chip with a label the reads 
+
+
+### Label overflow
+While one to two words (20-25 characters) is recommended for Chip labels, there might be instances when text needs to be longer. Truncation can be considered if characters go outside this limit, but make sure the Chip's content can be viewed in it's entirety with a `Tooltip`.
+
+> Image: Examples of chip label overflow. The first example with heart eyes has a chip that is hovered with a truncated label that reads 
+
+
+### Use sentence-style capitalization
+
+> Image: Examples of sentence-style for Chip labels. The first example with heart eyes emoji has a Chip with a label using sentence-style capitalization that reads 
+
+
+### Label metadata
+Ensure labeling is consistent across chips so users can easily distinguish between the list items.
+
+> Image: Examples of a group of three chips. The chips in the heart eyes example have the labels, 
+
+
+### Appropriate icons
+Use icons that relate to the labeling, enhancing comparability across the group.
+
+> Image: Examples of two chips. The first example with heart eyes shows one chip with the label, 
+
+
+### Follow color contrast guidelines
+When using custom colors, ensure you are following the WCAG guideline of a contrast ratio &gt= 4.5:1 between text and background. [SC 1.4.3][4]
+
+> Image: Examples of three chips with different custom background colours. In the first example with heart eyes, the chip labels are dark and abide by the 4.5 to 1 contrast guidelines. In the second example with the grimacing face, the chip labels are lighter and similar to the background colours, breaking the contrast guidelines.
+
+
+[1]: ./Button
+[2]: ./Link
+[3]: ./Multiselect
+[4]: https://www.w3.org/TR/WCAG21/#contrast-minimum
+
+## Examples
+
+
+### Appearance
+
+```typescript
+import React from 'react';
+
+import Chip from '@splunk/react-ui/Chip';
+import Layout from '@splunk/react-ui/Layout';
+
+
+function Appearance() {
+    return (
+        <Layout>
+            <Chip>default</Chip>
+            <Chip appearance="outline">outline</Chip>
+            <Chip appearance="info">info</Chip>
+            <Chip appearance="success">success</Chip>
+            <Chip appearance="warning">warning</Chip>
+            <Chip appearance="error">error</Chip>
+        </Layout>
+    );
+}
+
+export default Appearance;
+```
+
+
+
+### Custom colors
+
+When using custom colors, ensure you are following the WCAG guideline of a contrast ratio >= 4.5:1 between text and background.
+
+```typescript
+import React from 'react';
+
+import Chip from '@splunk/react-ui/Chip';
+import Layout from '@splunk/react-ui/Layout';
+
+
+function CustomColors() {
+    return (
+        <Layout>
+            <Chip foregroundColor="#400000" backgroundColor="#aeb6bf">
+                Chart area
+            </Chip>
+            <Chip foregroundColor="#45b39d" backgroundColor="#004444">
+                Chart area
+            </Chip>
+            <Chip foregroundColor="#4d1b7b" backgroundColor="#c79dd7">
+                Chart area
+            </Chip>
+        </Layout>
+    );
+}
+
+export default CustomColors;
+```
+
+
+
+### With icons
+
+```typescript
+import React from 'react';
+
+import ChartArea from '@splunk/react-icons/ChartArea';
+import ChartColumn from '@splunk/react-icons/ChartColumn';
+import ChartLine from '@splunk/react-icons/ChartLine';
+import Chip from '@splunk/react-ui/Chip';
+import Layout from '@splunk/react-ui/Layout';
+
+
+function Icon() {
+    return (
+        <Layout>
+            <Chip icon={<ChartArea />}>Chart area</Chip>
+            <Chip icon={<ChartColumn />}>Chart column</Chip>
+            <Chip icon={<ChartLine />}>Line chart</Chip>
+        </Layout>
+    );
+}
+
+export default Icon;
+```
+
+
+
+### Removable
+
+```typescript
+import React from 'react';
+
+import Chip from '@splunk/react-ui/Chip';
+
+
+function Removable() {
+    return <Chip onRequestRemove={() => {}}>Removable</Chip>;
+}
+
+export default Removable;
+```
+
+
+
+### Removable with non-string children
+
+The descriptive label for a Chip can be overridden by applying an aria-label attribute. This is necessary if passing children that are not of type string.
+
+```typescript
+import React from 'react';
+
+import Chip from '@splunk/react-ui/Chip';
+import Typography from '@splunk/react-ui/Typography';
+
+
+const RemovableWithNonStringChildren = () => (
+    <Chip onRequestRemove={() => {}} aria-label="Remove Bar chart">
+        <Typography as="span" variant="body">
+            Bar chart{' '}
+            <Typography as="span" variant="smallBody">
+                with custom colors
+            </Typography>
+        </Typography>
+    </Chip>
+);
+
+export default RemovableWithNonStringChildren;
+```
+
+
+
+### disabled
+
+```typescript
+import React from 'react';
+
+import Chip from '@splunk/react-ui/Chip';
+import Layout from '@splunk/react-ui/Layout';
+
+
+function Disabled() {
+    return (
+        <Layout>
+            <Chip disabled>Disabled</Chip>
+            <Chip disabled onRequestRemove={() => {}}>
+                Disabled
+            </Chip>
+        </Layout>
+    );
+}
+
+export default Disabled;
+```
+
+
+
+
+## API
+
+
+### Chip API
+
+#### Props
+
+| Name | Type | Required | Default | Description |
+|------|------|------|------|------|
+| appearance | 'info' \| 'success' \| 'warning' \| 'error' \| 'outline' | no |  | Sets the severity or type of this `Chip`. Setting this prop causes the `backgroundColor` prop to be ignored. |
+| backgroundColor | string | no |  | Changes the background color of the `Chip`. Hexadecimal colors and valid color names are allowed, such as `#ffffff` or `white`. If the `appearance` prop is set, this prop is ignored. |
+| children | React.ReactNode | yes |  |  |
+| disabled | boolean | no |  | Disables the `Chip`. |
+| elementRef | React.Ref<HTMLButtonElement \| HTMLDivElement> | no |  | A React ref which is set to the DOM element when the component mounts and null when it unmounts. |
+| foregroundColor | string | no |  | Changes the text and icon color of the `Chip`. Hexadecimal colors and valid color names are allowed, such as `#ffffff` or `white`. |
+| icon | React.ReactNode | no |  | The icon to show before the label. See the Icon component for more information. |
+| onRequestRemove | ChipRequestRemoveHandler | no |  | Includes a remove button if callback is set. |
+| value | any | no |  | Includes this value in `onRequestRemove` callbacks. |
+
+#### Types
+
+| Name | Type | Description |
+|------|------|------|
+| ChipRequestRemoveHandler | (     event: React.MouseEvent<HTMLButtonElement>,     data: { value?: any } // eslint-disable-line @typescript-eslint/no-explicit-any ) => void |  |
+
+
+
+
+

package/docs-llm/Clickable.md

@@ -0,0 +1,160 @@
+# Clickable
+
+## Examples
+
+
+### Basic
+
+```typescript
+import React from 'react';
+
+import Clickable from '@splunk/react-ui/Clickable';
+
+// eslint-disable-next-line no-alert
+
+const handleOnClick = () => window.alert('You clicked me');
+
+function Basic() {
+    return (
+        <>
+            <Clickable onClick={handleOnClick}>Alert Button</Clickable>
+            <br />
+            <br />
+            <Clickable to="Select">Link to Select component</Clickable>
+            <br />
+            <br />
+            <Clickable to="Select" disabled>
+                Disabled link to Select component
+            </Clickable>
+            <br />
+            <br />
+            <Clickable to="http://duckduckgo.com" openInNewContext>
+                External Link (new tab/window)
+            </Clickable>
+        </>
+    );
+}
+
+export default Basic;
+```
+
+
+
+### Disabled
+
+Prevents user from activating the component and adds disabled styling. If set to dimmed, the component is able to receive focus. If set to disabled, the component is unable to receive focus (as a result of setting the html disabled attribute). The default behavior when disabled={true} is "dimmed".
+
+```typescript
+import React from 'react';
+
+import Clickable from '@splunk/react-ui/Clickable';
+
+
+function Disabled() {
+    return (
+        <>
+            <Clickable to="Select" disabled>
+                Select component
+            </Clickable>
+            <br />
+            <Clickable to="Select" disabled="disabled">
+                Select component
+            </Clickable>
+        </>
+    );
+}
+
+export default Disabled;
+```
+
+
+
+### NavigationProvider
+
+```typescript
+import React from 'react';
+
+import Clickable, {
+    isInternalLink,
+    NavigationProvider,
+    NavigationProviderClickHandler,
+} from '@splunk/react-ui/Clickable';
+
+
+const handleClick: NavigationProviderClickHandler = (e, { openInNewContext, to }) => {
+    if (!openInNewContext && isInternalLink(to)) {
+        e.preventDefault();
+        window.alert(`In NavigationProvider click handler, to: ${to}`); // eslint-disable-line no-alert
+    }
+};
+
+function NavigationProviderExample() {
+    return (
+        <NavigationProvider onClick={handleClick}>
+            <Clickable to="Select">Link to Select component</Clickable>
+            <br />
+            <br />
+            <Clickable to="Select" openInNewContext>
+                Link to Select component (new tab/window)
+            </Clickable>
+            <br />
+            <br />
+            <Clickable to="http://duckduckgo.com" openInNewContext>
+                External Link (new tab/window)
+            </Clickable>
+        </NavigationProvider>
+    );
+}
+
+export default NavigationProviderExample;
+```
+
+
+
+
+## API
+
+
+### Clickable API
+
+`Clickable` renders as a `button` element, or as an `a` element if the `to` prop is set
+and the `disabled` prop is `false`. This is called link mode.
+
+#### Props
+
+| Name | Type | Required | Default | Description |
+|------|------|------|------|------|
+| children | React.ReactNode | no |  |  |
+| disabled | boolean \| 'dimmed' \| 'disabled' | no |  | Prevents user from activating the component and adds disabled styling.  If set to `dimmed`, the component is able to receive focus. If set to `disabled`, the component is unable to receive focus (as a result of setting the html `disabled` attribute).  The default behavior when `disabled={true}` is `dimmed`. |
+| elementRef | React.Ref<HTMLButtonElement \| HTMLAnchorElement> | no |  | A React ref which is set to the DOM element when the component mounts and null when it unmounts.  `HTMLAnchorElement` in link mode, `HTMLButtonElement` otherwise. |
+| navigationLabel | string | no |  | The text representation of the navigational link. This should be provided if child content is not a string.  Ignored if not in link mode. |
+| onClick | React.MouseEventHandler<HTMLButtonElement \| HTMLAnchorElement> | no |  | The onClick event handler is ignored if Ctrl or meta keys are pressed, which allows the link to open in a new context. |
+| openInNewContext | boolean | no |  | To open the link in a new window, set openInNewContext to `true`. Ignored if not in link mode. |
+| to | string | no |  | A URL for a link. If set, an `a` element is used instead of a `button` element (link mode). |
+
+
+
+### NavigationProvider API
+
+Used to provide an override for the `onClick` for links for single page applications so that
+internal links can navigate without a page reload.
+
+#### Props
+
+| Name | Type | Required | Default | Description |
+|------|------|------|------|------|
+| children | React.ReactNode | no |  |  |
+| onClick | NavigationProviderClickHandler | no |  | An `onClick` handler to use when a link is clicked if no other `onClick` handler is supplied. The function takes the event and an options argument with `to` and `openInNewContext` |
+| onLinkClick | NavigationProviderClickHandler | no |  | Triggers when a link is clicked, even if the link has its own `onClick` handler. The function takes the event and an options argument with `to` and `openInNewContext` |
+| transformUrl | (     url: string,     data: {         isInternal?: boolean;         isRootRelative?: boolean;     } ) => string | no |  | If set, all links that use the NavigationProvider's context will be transformed using this function. |
+
+#### Types
+
+| Name | Type | Description |
+|------|------|------|
+| NavigationProviderClickHandler | (     event: React.MouseEvent<HTMLAnchorElement>,     data: {         openInNewContext?: boolean;         to: string;         originalTo: string;         label?: string;     } ) => void |  |
+
+
+
+
+