@splunk/react-ui 5.7.1 → 5.8.0

package/docs-llm/Split Button.md

@@ -0,0 +1,295 @@
+# Split Button
+
+## Overview
+
+
+> Image: Illustration of a Split Button component
+
+
+## When to use this component
+- When you have two or more actions related to the primary action that need to be consolidated and space is limited.
+
+## When to use another component
+Use a button instead of a split button in the following cases:
+- When you want to pair a primary and secondary action, for example “Save” and “Cancel”.
+- If you have only one primary action in a workflow, for example “Done”.
+- If you want to use an icon only and no visible label.
+
+```mermaid
+graph TD
+    accDescr: Decision tree that guides on when to use the SplitButton component or something else
+    A(Is there more than one similar action that needs to be consolidated?) -- Yes --- B(Split Button)
+    A -- No --- C(Button)
+```
+
+### Check out
+- [Button] [1]
+
+## Behaviors
+
+### Change label
+Labels can be dynamically swapped for actions that might be repeated.
+> Image: Split button labeled 
+
+
+## Usage
+
+### Primary action
+Place the primary action on the main button to guide the most common user intent.
+> Image: Two split button examples demonstrating primary action placement. The first example, with a heart eyes emoji, shows a Split button labeled 
+
+
+### Secondary actions
+Ensure the secondary actions in the dropdown are contextually related to the primary action.
+> Image: Two split button examples demonstrating secondary actions in the dropdown. The first example, with a heart eyes emoji, shows a Split button labeled 
+
+
+### Icons
+Always include a text label for the primary action in Split button to ensure clarity and accessibility. Icons can be used as supplementary elements but should never replace the text label.
+> Image: Two split button examples demonstrating icon usage in labels. The first example, with a heart-eyes emoji, shows a Split button labeled 
+
+
+### Multiple buttons
+Split buttons work best alone or paired with additional buttons, using more than one can create confusion.
+> Image: Two examples of split button usage. The first example, with a heart-eyes emoji, shows a single split button labeled 
+
+
+### Avoid disabling part of the component
+Avoid disabling the primary action or secondary menu.
+> Image: Two examples showing split button states. The first example, with a heart-eyes emoji, displays an enabled split button labeled 
+
+
+## Content guidelines
+- Start label with a verb when possible.
+- Avoid vague or generic language such as “click here” or “read more”; this is not helpful for screen reader users.
+- Avoid any acronyms or confusing jargon that may leave a user guessing or afraid to click on a button (SC 2.4.4).
+
+### Label should not exceed three words
+Write concise button labels: 1 or 2 words.
+> Image: Two examples showing split button label length. The first example, with a heart-eyes emoji, has a concise label, 
+
+
+### Use sentence-style capitalization
+> Image: Two examples showing split button label capitalization. The first example, with a heart-eyes emoji, uses sentence-style capitalization with the label 
+
+
+### Use precise language
+Describe the action. For example, use “Add” when using an existing object in a new context, and use “Create” when making a new object from scratch.
+> Image: Two examples showing split button label language. The first example, with a heart-eyes emoji, uses the label 
+
+
+### Label overflow
+While usage guidelines for content recommend one to two words for buttons, for internationalization there might be instances when text needs to overflow.
+> Image: Two examples demonstrate split button label overflow. The first example, with a heart-eyes emoji, shows a split button labeled 
+
+
+[1]: ./Button
+
+## Examples
+
+
+### Basic
+
+```typescript
+import React from 'react';
+
+import Layout from '@splunk/react-ui/Layout';
+import SplitButton from '@splunk/react-ui/SplitButton';
+
+
+export default function Basic() {
+    return (
+        <Layout>
+            <SplitButton>
+                <SplitButton.Item>Main action</SplitButton.Item>
+                <SplitButton.Item>Option</SplitButton.Item>
+                <SplitButton.Item>Another option</SplitButton.Item>
+            </SplitButton>
+            <SplitButton appearance="primary">
+                <SplitButton.Item>Main action</SplitButton.Item>
+                <SplitButton.Item>Option</SplitButton.Item>
+                <SplitButton.Item>Another option</SplitButton.Item>
+            </SplitButton>
+            <SplitButton appearance="destructive">
+                <SplitButton.Item>Main action</SplitButton.Item>
+                <SplitButton.Item>Option</SplitButton.Item>
+                <SplitButton.Item>Another option</SplitButton.Item>
+            </SplitButton>
+            <SplitButton appearance="destructiveSecondary">
+                <SplitButton.Item>Main action</SplitButton.Item>
+                <SplitButton.Item>Option</SplitButton.Item>
+                <SplitButton.Item>Another option</SplitButton.Item>
+            </SplitButton>
+        </Layout>
+    );
+}
+```
+
+
+
+### Disabled
+
+```typescript
+import React from 'react';
+
+import Layout from '@splunk/react-ui/Layout';
+import SplitButton from '@splunk/react-ui/SplitButton';
+
+
+export default function Disabled() {
+    return (
+        <Layout>
+            <SplitButton disabled>
+                <SplitButton.Item>Main action</SplitButton.Item>
+                <SplitButton.Item>Option</SplitButton.Item>
+                <SplitButton.Item>Another option</SplitButton.Item>
+            </SplitButton>
+            <SplitButton appearance="primary" disabled>
+                <SplitButton.Item>Main action</SplitButton.Item>
+                <SplitButton.Item>Option</SplitButton.Item>
+                <SplitButton.Item>Another option</SplitButton.Item>
+            </SplitButton>
+            <SplitButton appearance="destructive" disabled>
+                <SplitButton.Item>Main action</SplitButton.Item>
+                <SplitButton.Item>Option</SplitButton.Item>
+                <SplitButton.Item>Another option</SplitButton.Item>
+            </SplitButton>
+            <SplitButton appearance="destructiveSecondary" disabled>
+                <SplitButton.Item>Main action</SplitButton.Item>
+                <SplitButton.Item>Option</SplitButton.Item>
+                <SplitButton.Item>Another option</SplitButton.Item>
+            </SplitButton>
+        </Layout>
+    );
+}
+```
+
+
+
+### Block
+
+By default, Split Buttons exist in inline blocks. Set inline to false to make the Split Button the full width of the parent container.
+
+```typescript
+import React from 'react';
+
+import Layout from '@splunk/react-ui/Layout';
+import SplitButton from '@splunk/react-ui/SplitButton';
+
+
+export default function Block() {
+    return (
+        <Layout style={{ width: '300px', flexDirection: 'column' }}>
+            <SplitButton inline={false}>
+                <SplitButton.Item>Main action</SplitButton.Item>
+                <SplitButton.Item>Option</SplitButton.Item>
+                <SplitButton.Item>Another option</SplitButton.Item>
+            </SplitButton>
+
+            <SplitButton inline={false} appearance="primary">
+                <SplitButton.Item>Primary action</SplitButton.Item>
+                <SplitButton.Item>Option</SplitButton.Item>
+                <SplitButton.Item>Another option</SplitButton.Item>
+            </SplitButton>
+
+            <SplitButton inline={false} appearance="destructive">
+                <SplitButton.Item>Destructive action</SplitButton.Item>
+                <SplitButton.Item>Option</SplitButton.Item>
+                <SplitButton.Item>Another option</SplitButton.Item>
+            </SplitButton>
+            <SplitButton inline={false} appearance="destructiveSecondary">
+                <SplitButton.Item>Destructive secondary action</SplitButton.Item>
+                <SplitButton.Item>Option</SplitButton.Item>
+                <SplitButton.Item>Another option</SplitButton.Item>
+            </SplitButton>
+        </Layout>
+    );
+}
+```
+
+
+
+### Change Label
+
+The isMain prop can be used to change which Item appears as the main button.
+
+```typescript
+import React, { useState } from 'react';
+
+import SplitButton from '@splunk/react-ui/SplitButton';
+
+
+export default function ChangeLabel() {
+    const options = ['Create a merge commit', 'Squash and merge', 'Rebase and merge'];
+    const [selected, setSelected] = useState(0);
+
+    const handleMenuItemClick = (index: number) => {
+        setSelected(index);
+    };
+
+    return (
+        <SplitButton aria-label="PR merge actions">
+            {options.map((option, index) => {
+                return (
+                    <SplitButton.Item
+                        aria-label={option}
+                        key={option}
+                        isMain={selected === index}
+                        onClick={() => handleMenuItemClick(index)}
+                    >
+                        {option}
+                    </SplitButton.Item>
+                );
+            })}
+        </SplitButton>
+    );
+}
+```
+
+
+
+
+## API
+
+
+### SplitButton API
+
+#### Props
+
+| Name | Type | Required | Default | Description |
+|------|------|------|------|------|
+| appearance | 'default' \| 'secondary' \| 'primary' \| 'destructive' \| 'destructiveSecondary' | no | 'secondary' | **DEPRECATED**: Value 'default' Changes the style of the main button and toggle.  The `default` value is deprecated and will be removed in a future major version. |
+| children | React.ReactNode | no |  | Must be `SplitButton.Item`. By default the first child becomes the main button. The remaining children become dropdown items. |
+| disabled | boolean | no |  | Prevents main button and dropdown toggle from being clicked. |
+| elementRef | React.Ref<HTMLDivElement> | no |  | A React ref which is set to the DOM element when the component mounts and null when it unmounts. |
+| inline | boolean | no | true | Restricts the horizontal size of the button. Set `inline` to `false` to remove the right margin and stretch the button to the full width of its container. |
+| onClick | React.MouseEventHandler<HTMLDivElement> | no |  | A callback for when the main button or toggle is clicked. |
+| toggleRef | React.Ref<HTMLButtonElement \| HTMLAnchorElement> | no |  | A React ref which is set to the dropdown toggle when the component mounts and null when it unmounts. |
+
+
+
+### SplitButton.Item API
+
+An item within a `SplitButton`.
+
+#### Props
+
+| Name | Type | Required | Default | Description |
+|------|------|------|------|------|
+| children | React.ReactNode | no |  | Becomes the label. |
+| disabled | boolean | no |  | Prevents user from clicking the button. |
+| 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. |
+| icon | React.ReactNode | no |  | Applies an icon in front of the label. |
+| isMain | boolean | no |  | Becomes the main button. If no `Item`s have this prop, the first `Item` is the main button. |
+| onClick | ItemClickHandler | no |  | A callback for when an item is clicked. |
+
+#### Types
+
+| Name | Type | Description |
+|------|------|------|
+| ItemClickHandler | (     event: React.MouseEvent<HTMLAnchorElement \| HTMLButtonElement>,     data: {         action?: string;         icon?: React.ReactNode;         label?: React.ReactNode;         value?: any; // eslint-disable-line @typescript-eslint/no-explicit-any     } ) => void |  |
+
+
+
+
+

package/docs-llm/Static Content.md

@@ -0,0 +1,90 @@
+# Static Content
+
+## Examples
+
+
+### Basic
+
+Static Content renders content within a Control Group.
+
+```typescript
+import React from 'react';
+
+import ControlGroup from '@splunk/react-ui/ControlGroup';
+import StaticContent from '@splunk/react-ui/StaticContent';
+
+
+function Basic() {
+    return (
+        <ControlGroup label="StaticContent" controlsLayout="fill">
+            <StaticContent> This simply renders the child text! </StaticContent>
+        </ControlGroup>
+    );
+}
+
+export default Basic;
+```
+
+
+
+### Icons and Other Controls
+
+Static Content with other components in a Control Group.
+
+```typescript
+import React from 'react';
+
+import CylinderMulti from '@splunk/react-icons/CylinderMulti';
+import File from '@splunk/react-icons/File';
+import ControlGroup from '@splunk/react-ui/ControlGroup';
+import StaticContent from '@splunk/react-ui/StaticContent';
+import Text from '@splunk/react-ui/Text';
+
+
+function FieldValue() {
+    return (
+        <div>
+            <ControlGroup label="Product">
+                <StaticContent inline>
+                    <File />
+                </StaticContent>
+                <StaticContent inline>
+                    <CylinderMulti />
+                </StaticContent>
+            </ControlGroup>
+
+            <ControlGroup label="Cost" controlsLayout="none">
+                <Text defaultValue="20" inline />
+                <StaticContent inline>Dollars or less</StaticContent>
+            </ControlGroup>
+        </div>
+    );
+}
+
+export default FieldValue;
+```
+
+
+
+
+## API
+
+
+### StaticContent API
+
+This component is intended for use in a control group, either to display a static value or
+between two controls.
+
+#### Props
+
+| Name | Type | Required | Default | Description |
+|------|------|------|------|------|
+| 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. |
+| inline | boolean | no | false | When true, display as inline-block with auto width. |
+| labelledBy | string | no |  |  |
+
+
+
+
+

package/docs-llm/Step Bar.md

@@ -0,0 +1,292 @@
+# Step Bar
+
+## Overview
+
+
+> Image: Illustration of a Step Bar component.
+
+
+## When to use this component
+- You need to guide a user through multiple steps.
+- To display a sequence of related tasks that must be completed in a linear order.
+- When users need to track their progress, such as in long forms or troubleshooting steps.
+
+
+## When to use another component
+- For navigation between pages, use Breadcrumb instead.
+- To represent overall progress outside of a linear flow, use Progress instead.
+
+```mermaid
+graph TD
+    accDescr: Decision tree that guides on when to use the StepBar component or something else
+    A(Is the purpose to navigate between pages or sections?) -- Yes --- B(Breadcrumbs)
+    A -- No --- C(Is the task sequential and step-by-step?)
+    C -- Yes --- D(Step Bar)
+    C -- No --- E(Progress)
+```
+
+### Check out
+- [Breadcrumbs][1]
+- [Progress][2]
+
+## Behaviors
+
+### Interaction
+ Use back and next buttons to navigate to the next step. The Step Bar component is not interactive.
+
+ > Image: Example laying emphasis on the interactivity of the Step Bar component. The first example with the heart eyes emoji displays the mouse navigating the Step Bar component through the back & next buttons, whereas the second example with the grimacing emoji displays the navigating through the Step Bar component by clicking on the Step Bar component itself.
+
+
+## Usage
+
+### Content alignment
+ Content in a step should always relate to its corresponding step title.
+
+> Image: Example laying emphasis on content within a step being related to the step title. The first example with the heart eyes emoji displays review summary content under the 
+
+
+### No less than two steps
+
+> Image: Example laying emphasis on least number of steps provided. The first example with the heart eyes emoji displays 2 steps, whereas the second example with the grimacing emoji displays 1 step.
+
+
+### Step title content
+#### Provide context
+ Provide context about the contents of the step with the help of the step title.
+
+> Image: Example laying emphasis on providing context within the step title. The first example with the heart eyes emoji displays step titles that provide context to the step, whereas the second example with the grimacing emoji displays no step titles.
+
+
+#### Be concise
+ Step titles should be kept as descriptive as possible while remaining concise.
+
+> Image: Example laying emphasis on giving concise labels to the step title. The first example with the heart eyes emoji displays a concise label for the step title, whereas the second example with the grimacing emoji displays a longer, more complicated one.
+
+
+## Content
+
+### Use sentence case, not title case.
+ Only the first letter of the word should be capitalized unless it's a proper noun.
+
+ > Image: Example laying emphasis on the capitalization in the Step Bar. The first example with the heart eyes emoji displays the step title to use sentence case, whereas the second example with the grimacing emoji displays step title to use title case.
+
+
+[1]: ./Breadcrumbs
+[2]: ./Progress
+
+## Examples
+
+
+### numSteps
+
+```typescript
+import React, { useCallback, useState } from 'react';
+
+import ChevronLeft from '@splunk/react-icons/ChevronLeft';
+import ChevronRight from '@splunk/react-icons/ChevronRight';
+import Button from '@splunk/react-ui/Button';
+import Layout from '@splunk/react-ui/Layout';
+import StepBar from '@splunk/react-ui/StepBar';
+
+const numSteps = 4;
+
+
+function Basic() {
+    const [activeStepId, setActiveStepId] = useState(0);
+
+    const handlePrevious = useCallback(() => {
+        setActiveStepId(activeStepId - 1);
+    }, [activeStepId]);
+
+    const handleNext = useCallback(() => {
+        setActiveStepId(activeStepId + 1);
+    }, [activeStepId]);
+
+    return (
+        <div>
+            <StepBar activeStepId={activeStepId}>
+                <StepBar.Step>Select item</StepBar.Step>
+                <StepBar.Step>Configure required</StepBar.Step>
+                <StepBar.Step>Configure optional</StepBar.Step>
+                <StepBar.Step>Review</StepBar.Step>
+            </StepBar>
+            <br />
+            <br />
+            <Layout>
+                <Button
+                    icon={<ChevronLeft />}
+                    label="Back"
+                    appearance="default"
+                    disabled={activeStepId === 0}
+                    onClick={handlePrevious}
+                />
+                <Button
+                    label={activeStepId < numSteps - 1 ? 'Next' : 'Done'}
+                    appearance="primary"
+                    onClick={activeStepId < numSteps - 1 ? handleNext : undefined}
+                >
+                    <ChevronRight />
+                </Button>
+            </Layout>
+        </div>
+    );
+}
+
+export default Basic;
+```
+
+
+
+### numSteps
+
+```typescript
+import React, { useCallback, useState } from 'react';
+
+import ChevronLeft from '@splunk/react-icons/ChevronLeft';
+import ChevronRight from '@splunk/react-icons/ChevronRight';
+import Button from '@splunk/react-ui/Button';
+import Layout from '@splunk/react-ui/Layout';
+import StepBar from '@splunk/react-ui/StepBar';
+
+const numSteps = 4;
+
+
+function StepBarError() {
+    const [activeStepId, setActiveStepId] = useState(1);
+    const handlePrevious = useCallback(() => {
+        setActiveStepId(activeStepId - 1);
+    }, [activeStepId]);
+
+    const handleNext = useCallback(() => {
+        setActiveStepId(activeStepId + 1);
+    }, [activeStepId]);
+
+    return (
+        <div>
+            <StepBar activeStepId={activeStepId}>
+                <StepBar.Step>Select item</StepBar.Step>
+                <StepBar.Step error>Configure required</StepBar.Step>
+                <StepBar.Step>Configure optional</StepBar.Step>
+                <StepBar.Step>Review</StepBar.Step>
+            </StepBar>
+            <br />
+            <br />
+            <Layout>
+                <Button
+                    icon={<ChevronLeft />}
+                    label="Back"
+                    appearance="default"
+                    disabled={activeStepId === 0}
+                    onClick={handlePrevious}
+                />
+                <Button
+                    label={activeStepId < numSteps - 1 ? 'Next' : 'Done'}
+                    appearance="primary"
+                    onClick={activeStepId < numSteps - 1 ? handleNext : undefined}
+                    disabled={activeStepId === 1}
+                >
+                    <ChevronRight />
+                </Button>
+            </Layout>
+        </div>
+    );
+}
+
+export default StepBarError;
+```
+
+
+
+### numSteps
+
+```typescript
+import React, { useCallback, useState } from 'react';
+
+import ChevronLeft from '@splunk/react-icons/ChevronLeft';
+import ChevronRight from '@splunk/react-icons/ChevronRight';
+import Button from '@splunk/react-ui/Button';
+import Layout from '@splunk/react-ui/Layout';
+import StepBar from '@splunk/react-ui/StepBar';
+
+const numSteps = 4;
+
+
+function Vertical() {
+    const [activeStepId, setActiveStepId] = useState(0);
+
+    const handlePrevious = useCallback(() => {
+        setActiveStepId(activeStepId - 1);
+    }, [activeStepId]);
+
+    const handleNext = useCallback(() => {
+        setActiveStepId(activeStepId + 1);
+    }, [activeStepId]);
+
+    return (
+        <div>
+            <StepBar activeStepId={activeStepId} orientation="vertical" style={{ width: '250px' }}>
+                <StepBar.Step>Select item</StepBar.Step>
+                <StepBar.Step>Configure required</StepBar.Step>
+                <StepBar.Step>Configure optional</StepBar.Step>
+                <StepBar.Step>Review</StepBar.Step>
+            </StepBar>
+            <br />
+            <br />
+            <Layout>
+                <Button
+                    icon={<ChevronLeft />}
+                    label="Back"
+                    appearance="default"
+                    disabled={activeStepId === 0}
+                    onClick={handlePrevious}
+                />
+                <Button
+                    label={activeStepId < numSteps - 1 ? 'Next' : 'Done'}
+                    appearance="primary"
+                    onClick={activeStepId < numSteps - 1 ? handleNext : undefined}
+                >
+                    <ChevronRight />
+                </Button>
+            </Layout>
+        </div>
+    );
+}
+
+export default Vertical;
+```
+
+
+
+
+## API
+
+
+### StepBar API
+
+#### Props
+
+| Name | Type | Required | Default | Description |
+|------|------|------|------|------|
+| activeStepId | number | yes |  | The `stepId` of the `StepBar.Step` to activate. |
+| children | React.ReactNode | no |  | Must be `StepBar.Step`. |
+| elementRef | React.Ref<HTMLUListElement> | no |  | A React ref which is set to the DOM element when the component mounts and null when it unmounts. |
+| inline | boolean | no | false | Setting inline to true makes the Step Bar an inline element. It assumes its minimum width. |
+| orientation | 'horizontal' \| 'vertical' | no | 'horizontal' | The flow direction of steps. |
+
+
+
+### StepBar.Step API
+
+#### Props
+
+| Name | Type | Required | Default | Description |
+|------|------|------|------|------|
+| children | React.ReactNode | no |  |  |
+| elementRef | React.Ref<HTMLLIElement> | no |  | A React ref which is set to the DOM element when the component mounts and null when it unmounts. |
+| error | boolean | no | false | Displays active step with alert icon. |
+| stepId | number | no |  | A unique `id` for this step and used by the `StepBar` to keep track of the open `Step`. Defaults to a zero-based index matching the component's position in `StepBar`. |
+
+
+
+
+