@splunk/react-ui 5.7.1 → 5.8.0

package/docs-llm/Accordion.md

@@ -0,0 +1,267 @@
+# Accordion
+
+## Overview
+
+
+
+> Image: Illustration of a group of accordion components with the second accordion expanded to show its content.
+
+
+## When to use this component
+
+<Message appearance="fill" type="warning">
+    <Message.Title>
+         <strong>Use Collapsible Panel</strong>
+         <p>Collapsible Panel supports expanding a single or multiple panels.
+         It is suggested to use <Link to="./CollapsiblePanel">Collapsible Panel</Link> as Accordion is deprecated and will be removed in a future major version.</p>
+    </Message.Title>
+</Message>
+
+- When you have a large amount of non-essential content to show, and want to allow people to have control over the content visibility
+- When you want to progressively disclose information or provide step-by-step guidance
+- When you want to group related content and optimize space and information density
+- When you are showing content on a small screen to reduce scrolling
+
+## When to use another component
+- If you need to expand a single or multiple panels at a time, use `Collapsible Panel`.
+- If there are only one or two sections, it is better to display the content without requiring user interaction.
+- If the content is critical and should always be visible, use a `list` or display the content without requiring user interaction.
+- For information that needs to be viewed, grouped, or compared across categories use a `Table`.
+- For large amounts of categorical content or for content that is not well-suited for organizing into sections, consider displaying this information using `Tab Bar`.
+
+```mermaid
+graph TD
+    accDescr: Decision tree that guides on when to use the Accordion component or something else
+    A(Is it critical content that should always be visible?) -- Yes --- B(List)
+    A -- No --- C(Is there a lot of content?)
+    C -- Yes --- D(Tab)
+    C -- No --- E(Accordion - suggested to use Collapsible Panel)
+```
+
+### Check out
+- [Collapsible Panel][1]
+- [List][2]
+- [Table][3]
+- [Tab bar][4]
+
+## Usage
+
+### Limit content
+Avoid filling accordions with lots of content. Instead, use small, digestible chunks for the user.
+
+> Image: Heart eye example with digestible amount of content next to a grimacing face example of an accordion with to much content
+
+
+### Order panels logically
+When your accordion panels need to be read in a specific order, order panels logically.
+
+> Image: Heart eye example with accordions label in sequential order 1 - 4 next to a grimacing face example where the accordions are out of order 2, 1, 4, 3
+
+
+## Content guidelines
+
+### Panel title:
+- Write a concise title that describes the associated body content so the user can decide whether to read the body content.
+- Use sentence-style capitalization and capitalize the first word and proper nouns only.
+- Don’t use punctuation such as periods, commas, or exclamation marks.
+
+### Panel body:
+- If you have a lot of content, split body content into paragraphs to create smaller chunks that are easier to read.
+- Write in complete sentences with end punctuation.
+
+
+[1]: ./CollapsiblePanel
+[2]: ./List
+[3]: ./Table
+[4]: ./TabBar
+
+## Examples
+
+
+### Controlled
+
+```typescript
+import React, { useState } from 'react';
+
+import Accordion, { AccordionChangeHandler } from '@splunk/react-ui/Accordion';
+import P from '@splunk/react-ui/Paragraph';
+
+
+function Controlled() {
+    const [openPanelId, setOpenPanelId] = useState<string | number | undefined>(2);
+
+    const handleChange: AccordionChangeHandler = (e, { panelId: panelValue }) => {
+        setOpenPanelId(panelValue);
+    };
+
+    return (
+        <Accordion openPanelId={openPanelId} onChange={handleChange}>
+            <Accordion.Panel panelId={1} title="Panel 1">
+                <P>
+                    This is the content of Panel 1. Here is some more information. Additional
+                    details can be placed here.
+                </P>
+            </Accordion.Panel>
+            <Accordion.Panel panelId={2} title="Panel 2">
+                <P>This is the content of Panel 2.</P>
+            </Accordion.Panel>
+            <Accordion.Panel panelId={3} title="Panel 3">
+                <P>This is the content of Panel 3. More information for Panel 3.</P>
+            </Accordion.Panel>
+        </Accordion>
+    );
+}
+
+export default Controlled;
+```
+
+
+
+### Uncontrolled
+
+```typescript
+import React from 'react';
+
+import Accordion from '@splunk/react-ui/Accordion';
+import P from '@splunk/react-ui/Paragraph';
+
+
+function Uncontrolled() {
+    return (
+        <Accordion defaultOpenPanelId={2}>
+            <Accordion.Panel panelId={1} title="Panel 1">
+                <P>
+                    This is the content of Panel 1. Here is some more information. Additional
+                    details can be placed here.
+                </P>
+            </Accordion.Panel>
+            <Accordion.Panel panelId={2} title="Panel 2">
+                <P>This is the content of Panel 2.</P>
+            </Accordion.Panel>
+            <Accordion.Panel panelId={3} title="Panel 3">
+                <P>This is the content of Panel 3. More information for Panel 3.</P>
+            </Accordion.Panel>
+        </Accordion>
+    );
+}
+
+export default Uncontrolled;
+```
+
+
+
+### Inset
+
+inset adds padding to the Accordion Panel. This can be set on the Accordion, or individual Panels. Individual Panels can override inset from their parent Accordion.
+
+```typescript
+import React, { useState } from 'react';
+
+import Accordion, { AccordionChangeHandler } from '@splunk/react-ui/Accordion';
+import P from '@splunk/react-ui/Paragraph';
+
+
+const Inset = () => {
+    const [openPanelId, setOpenPanelId] = useState<string | number | undefined>(1);
+
+    const handleChange: AccordionChangeHandler = (e, data) => {
+        setOpenPanelId(data.panelId);
+    };
+
+    return (
+        <Accordion openPanelId={openPanelId} onChange={handleChange}>
+            <Accordion.Panel panelId={1} title="Inset true (default)" inset>
+                <P>This panel has inset enabled. Content is padded.</P>
+            </Accordion.Panel>
+            <Accordion.Panel panelId={2} title="Inset false" inset={false}>
+                <P>This panel has inset disabled. Content is flush with the edges.</P>
+            </Accordion.Panel>
+        </Accordion>
+    );
+};
+
+export default Inset;
+```
+
+
+
+
+## API
+
+
+### Accordion API
+
+@deprecated
+Accordion has been deprecated and will be removed in a future major version. Use Collapsible Panel's SingleOpenPanelGroup API instead.
+
+#### Props
+
+| Name | Type | Required | Default | Description |
+|------|------|------|------|------|
+| children | React.ReactNode | no |  | Must be `Accordion.Panel`. |
+| defaultOpenPanelId | string \| number | no |  | Sets the panel to expand on the initial render. Use only when using `Accordion` as an uncontrolled component. Must match the `panelId` of one of the `Accordion.Panel` children. |
+| elementRef | React.Ref<HTMLDivElement> | no |  | A React ref which is set to the DOM element when the component mounts and null when it unmounts. |
+| inset | boolean | no | true | Inset Accordions have padding for content to the panels |
+| onChange | AccordionChangeHandler | no |  | Invoked on a change of the open panel. Callback is passed data, such as the `panelId` of the `Accordion.Panel` that originated the expand request. `panelId` is `undefined` when the open panel is collapsed. |
+| openPanelId | string \| number | no |  | Indicates the `panelId` of the currently expanded `Accordion.Panel`. Use only when using `Accordion` as a controlled component. |
+
+#### Types
+
+| Name | Type | Description |
+|------|------|------|
+| AccordionChangeHandler | (     event: React.MouseEvent<HTMLButtonElement>,     data: {         event: React.MouseEvent<HTMLButtonElement>;         panelId?: string \| number;         reason: 'toggleClick';     } ) => void |  |
+
+
+
+### Accordion.Panel API
+
+`Accordion.Panel` operates as a container component for content in an `Accordion`.
+
+#### Props
+
+| Name | Type | Required | Default | Description |
+|------|------|------|------|------|
+| description | string | no |  | Displays right-aligned text in the title bar of the panel. |
+| elementRef | React.Ref<HTMLDivElement> | no |  | A React ref which is set to the DOM element when the component mounts and null when it unmounts. |
+| inset | boolean | no |  | When `true` renders the Panel with padding. When `false` render the Panel without padding. |
+| panelId | string \| number | no |  | Identifies the unique `id` for a panel. `Accordion` uses 'panelID' to track the expanded panel. |
+| title | React.ReactNode | yes |  | Displays the the name of the panel in its title bar. |
+
+
+
+
+
+## Accessibility
+
+## Visual Design
+- Color contrast ratio **MUST** be:
+    - &gt= 4.5:1 for normal text: 14 pt (typically 18.66px) and bold or larger [SC 1.4.3][1]
+    - &gt= 3:1 for large text: 18 pt (typically 24px) or larger [SC 1.4.3][1]
+    - &gt= 3:1 for arrow icon against accordion header background [SC 1.4.11][2]
+    - 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 button button &lt&gt focus &lt&gt background
+
+## Content
+- Accordion titles **SHOULD** be between 60-80 characters; any more can lose a user's attention or negatively impact neurodivergent users 
+
+## States
+- Color contrast does not apply to a disabled accordion 
+
+## Interaction Design
+- **MUST** have keyboard navigation [SC 2.1][3]
+    - <kbd>Tab</kbd> and <kbd>Shift</kbd>+<kbd>Tab</kbd> to move through accordion headers OR when open, any interactive elements within the accordion
+    - <kbd>Space</kbd> and <kbd>Enter</kbd> to collapse or expand the accordion header when focused. In addition, any interactive elements within the accordion that are focused
+
+## Implementation
+- Accordion header(summary) **MUST** be kept in the parent/trigger attribute, while all details are kept in the child attribute
+- Screen reader **MUST** announce when accordion is focused [SC 4.1.2][4]
+    - Header title
+    - Announcement should be made when user successfully closes or expands accordion
+
+[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/WCAG21/#name-role-value
+
+

package/docs-llm/Anchor Menu.md

@@ -0,0 +1,115 @@
+# Anchor Menu
+
+## Overview
+
+
+> Image: Illustration of an Anchor Menu.
+
+
+## When to use this component
+
+- When you have long-form content with multiple sections that users need to navigate within a single page.
+- For providing a table of contents or outline view of page content.
+
+## When to use another component
+
+- For switching between different content views, use [`TabBar`] [1]
+
+```mermaid
+graph TD
+    accDescr: Decision tree that guides on when to use the Anchor Menu component or something else
+    A(Need to split content on the same page?) -- Yes --- B(Is the content hierarchically or thematically related?)
+    A -- No --- G(Use standard page layout)
+    B -- Yes --- C(Do you want to provide a high-level view of the page’s structure and content and quickly navigate to a section?)
+    B -- No --- D(Tab Bar)
+
+    C -- Yes --- E(Anchor Menu)
+    C -- No --- F(Sections without Anchor Menu)
+```
+
+### Check out
+- [TabBar] [1]
+
+## Behavior 
+
+### Appearance
+
+#### Show the current page
+Indicate where a user is within the navigational hierarchy. Pass the `itemId` to the `activeItemId` prop to set the currently active item to show users which page they have navigated to.
+
+> Image: Examples of Anchor Menu active state highlighting. The first example with heart eyes emoji shows proper use of activeItemId to clearly indicate the current page section. The second example with grimacing emoji shows unclear active state indication that doesn
+
+
+#### Spine
+You can hide the side border spine. This is useful when the `AnchorMenu` is placed inside a container with its own border.
+
+> Image: Examples of Anchor Menu spine border treatment, one with the spine border and the other without.
+
+
+### Scrolling behavior
+Clicking a menu link scrolls to the corresponding content section and updates the active indicator. The menu remains visible and updates the current location as users scroll through the page.
+
+> Image: Example of Anchor Menu scrolling behavior. The example shows the Anchor Menu sticking to the top of the page as the content scrolls down.
+
+
+## Usage
+
+### Nesting
+Use [`CollapsiblePanel`] [2] to group `AnchorMenu` links. Limit grouping to 1 level to maintain usability and prevent overwhelming users.
+
+> Image: Examples of Anchor Menu nesting with Collapsible Panels.
+
+
+### Links
+Only use `AnchorMenu` to help users navigate within the same page. Don't use them to navigate to different pages.
+
+> Image: Examples of Anchor Menu link usage. The first example with heart eyes emoji shows proper same-page navigation with anchor links to content sections. The second example with grimacing emoji shows incorrect use for cross-page navigation that breaks user expectations.
+
+
+[1]: ./TabBar
+[2]: ./CollapsiblePanel
+
+## Examples
+
+import React from 'react';
+
+import DocExample from '@splunk/react-docs/DocExample';
+import ExamplesPage from '@splunk/react-docs/ExamplesPage';
+
+const examples = require.context('./examples/');
+const examplesRaw = require.context('./examples/?prepareExamples');
+
+function ExamplesSection() {
+    return (
+        <ExamplesPage>
+            <DocExample
+                key="Basic"
+                code={examplesRaw('./Basic')}
+                example={examples('./Basic').default}
+            />
+        </ExamplesPage>
+    );
+}
+
+export default ExamplesSection;
+
+
+## API
+
+
+### AnchorMenu API
+
+#### Props
+
+| Name | Type | Required | Default | Description |
+|------|------|------|------|------|
+| activeItemId | string | no |  | The `itemId` prop of the currently active item. |
+| children | React.ReactNode | no |  |  |
+| elementRef | React.Ref<HTMLElement> | no |  | A React ref which is set to the DOM element when the component mounts and null when it unmounts. |
+| hideSpine | boolean | no |  | Hides the side border spine. Useful when the AnchorMenu is placed inside a container with its own border. |
+| label | string \| null | no | _('On this page:') | Label text to display above the menu items. Set to `null` to disable the label. |
+
+
+
+
+

package/docs-llm/Anchor.md

@@ -0,0 +1,54 @@
+# Anchor
+
+## Examples
+
+
+### Basic
+
+`Anchor` can be added to any `Heading` level.
+
+```typescript
+import React from 'react';
+
+import Anchor from '@splunk/react-ui/Anchor';
+import Heading from '@splunk/react-ui/Heading';
+import P from '@splunk/react-ui/Paragraph';
+import Prose from '@splunk/react-ui/Prose';
+
+
+function Basic() {
+    return (
+        <Prose>
+            <Heading level={1}>
+                <Anchor name="Heading 1">Heading 1</Anchor>
+            </Heading>
+            <P>This is the content below Heading 1.</P>
+        </Prose>
+    );
+}
+
+export default Basic;
+```
+
+
+
+
+## API
+
+
+### Anchor API
+
+`Anchor` is a utility component used to add a fragment link to an element.
+
+#### Props
+
+| Name | Type | Required | Default | Description |
+|------|------|------|------|------|
+| children | React.ReactNode | no |  |  |
+| elementRef | React.Ref<HTMLAnchorElement> | no |  | A React ref which is set to the DOM element when the component mounts and null when it unmounts. |
+| name | string | yes |  | The name to give to the anchor for the URL fragment. |
+
+
+
+
+

package/docs-llm/AnimationToggle.md

@@ -0,0 +1,254 @@
+# AnimationToggle
+
+## Examples
+
+
+### Controlling animation via a provider
+
+Shows how to control animation using an AnimationToggleProvider. This can be used to disable animation for most components included in this library.
+
+```typescript
+import React, { Component } from 'react';
+
+import { AnimationToggleProvider } from '@splunk/react-ui/AnimationToggle';
+import Button from '@splunk/react-ui/Button';
+import Switch from '@splunk/react-ui/Switch';
+import TransitionOpen from '@splunk/react-ui/TransitionOpen';
+
+
+class Provider extends Component<object, { animatedTransitions: boolean; open: boolean }> {
+    constructor(props: object) {
+        super(props);
+        this.state = {
+            open: false,
+            animatedTransitions: false,
+        };
+    }
+
+    handleButtonClick = () => {
+        this.setState((state) => ({ open: !state.open }));
+    };
+
+    handleSwitchClick = () => {
+        this.setState((state) => ({ animatedTransitions: !state.animatedTransitions }));
+    };
+
+    render() {
+        const style: React.CSSProperties = {
+            border: '1px solid black',
+            marginTop: 10,
+            textAlign: 'center',
+            width: 150,
+        };
+        return (
+            <div>
+                <Switch onClick={this.handleSwitchClick} selected={this.state.animatedTransitions}>
+                    Animation enabled
+                </Switch>
+                <AnimationToggleProvider enabled={this.state.animatedTransitions}>
+                    <Button onClick={this.handleButtonClick}>Click me!</Button>
+                    <TransitionOpen animation="expandHeight" open={this.state.open}>
+                        <div style={style}>
+                            <p>Hello world</p>
+                            <p>Hello world</p>
+                            <p>Hello world</p>
+                            <p>Hello world</p>
+                            <p>Hello world</p>
+                        </div>
+                    </TransitionOpen>
+                </AnimationToggleProvider>
+            </div>
+        );
+    }
+}
+
+export default Provider;
+```
+
+
+
+### Offering animation control with a hook
+
+Shows how to use the useAnimationToggle hook to render different content based on current animation settings.
+
+```typescript
+import React, { useState } from 'react';
+
+import { AnimationToggleProvider, useAnimationToggle } from '@splunk/react-ui/AnimationToggle';
+import P from '@splunk/react-ui/Paragraph';
+import Switch from '@splunk/react-ui/Switch';
+
+
+function Content() {
+    const animationToggle = useAnimationToggle();
+    const MessageComponent = animationToggle === 'on' ? 'b' : 'span';
+    const message = animationToggle === 'on' ? 'Enabled' : 'Disabled';
+    return <MessageComponent>{message}</MessageComponent>;
+}
+
+function ToggleHook() {
+    const [animatedTransitions, setAnimatedTransitions] = useState(false);
+    const handleSwitchClick = () => {
+        setAnimatedTransitions((state) => !state);
+    };
+
+    return (
+        <P>
+            <Switch onClick={handleSwitchClick} selected={animatedTransitions}>
+                Animation enabled
+            </Switch>
+            <AnimationToggleProvider enabled={animatedTransitions}>
+                <Content />
+            </AnimationToggleProvider>
+        </P>
+    );
+}
+
+export default ToggleHook;
+```
+
+
+
+### Offering animation control with a component
+
+Shows how to use the Animation Toggle component to render different content based on current animation settings.
+
+```typescript
+import React, { Component } from 'react';
+
+import AnimationToggle, { AnimationToggleProvider } from '@splunk/react-ui/AnimationToggle';
+import P from '@splunk/react-ui/Paragraph';
+import Switch from '@splunk/react-ui/Switch';
+
+
+class ToggleComponent extends Component<object, { animatedTransitions: boolean }> {
+    constructor(props: object) {
+        super(props);
+        this.state = {
+            animatedTransitions: false,
+        };
+    }
+
+    handleSwitchClick = () => {
+        this.setState((state) => ({ animatedTransitions: !state.animatedTransitions }));
+    };
+
+    render() {
+        return (
+            <P>
+                <Switch onClick={this.handleSwitchClick} selected={this.state.animatedTransitions}>
+                    Animation enabled
+                </Switch>
+                <AnimationToggleProvider enabled={this.state.animatedTransitions}>
+                    <AnimationToggle on={<b>Enabled</b>} off={<span>Disabled</span>} />
+                </AnimationToggleProvider>
+            </P>
+        );
+    }
+}
+
+export default ToggleComponent;
+```
+
+
+
+### Support reduced motion with a hook
+
+Shows how to use the useAnimationToggle hook to offer an alternative when the user prefers reduced motion. If reduced motion is preferred but animations are disabled useAnimationToggle returns 'off'.
+
+```typescript
+import React from 'react';
+
+import { useAnimationToggle } from '@splunk/react-ui/AnimationToggle';
+import List from '@splunk/react-ui/List';
+import P from '@splunk/react-ui/Paragraph';
+
+
+const ReducedMotionHook = () => {
+    const animationToggle = useAnimationToggle();
+    // TODO: Once Prose component is finished, use Prose to add left padding and margin back to List (SUI-5554)
+    return (
+        <article>
+            <P>To reduce animation on macOS:</P>
+            <List ordered>
+                <List.Item>Go to &quot;System Preferences&quot;</List.Item>
+                <List.Item>Choose &quot;Accessibility&quot;</List.Item>
+                <List.Item>Select &quot;Display&quot;</List.Item>
+                <List.Item>Check &quot;Reduce motion&quot;</List.Item>
+            </List>
+            <P>
+                Animation currently:{' '}
+                <b>
+                    {animationToggle === 'on' && 'On'}
+                    {animationToggle === 'off' && 'Off'}
+                    {animationToggle === 'reduced' && 'Reduced'}
+                </b>
+            </P>
+        </article>
+    );
+};
+
+export default ReducedMotionHook;
+```
+
+
+
+### Support reduced motion with a component
+
+Shows how to use the Animation Toggle component to offer an alternative when the user prefers reduced motion. If reduced motion is preferred but animations are disabled or no reduced motion alternative is set, Animation Toggle considers animations to be disabled.
+
+```typescript
+import React from 'react';
+
+import AnimationToggle from '@splunk/react-ui/AnimationToggle';
+import P from '@splunk/react-ui/Paragraph';
+
+
+const ReducedMotionComponent = () => (
+    <P>
+        Animation currently:{' '}
+        <AnimationToggle on={<b>On</b>} off={<b>Off</b>} reduced={<b>Reduced</b>} />
+    </P>
+);
+
+export default ReducedMotionComponent;
+```
+
+
+
+
+## API
+
+import React from 'react';
+
+import ComponentAPI from '@splunk/react-docs/ComponentAPI';
+import UtilAPI from '@splunk/react-docs/UtilAPI';
+
+import animationToggleContextDocs from '!!@splunk/jsdoc-loader!@splunk/react-ui/AnimationToggle/AnimationToggleContext';
+import useAnimationToggleDocs from '!!@splunk/jsdoc-loader!@splunk/react-ui/AnimationToggle/useAnimationToggle';
+import allAnimationToggleDocs from '@splunk/react-ui/AnimationToggle/AnimationToggle?parseDocs';
+import allAnimationToggleProviderDocs from '@splunk/react-ui/AnimationToggle/AnimationToggleProvider?parseDocs';
+
+const animationToggleDocs = allAnimationToggleDocs.find(
+    (doc) => doc.displayName === 'AnimationToggle'
+);
+const animationToggleProviderDocs = allAnimationToggleProviderDocs.find(
+    (doc) => doc.displayName === 'AnimationToggleProvider'
+);
+
+function DevelopSection() {
+    return [
+        <ComponentAPI
+            title="AnimationToggleProvider"
+            key="AnimationToggleProvider"
+            docs={animationToggleProviderDocs}
+        />,
+        <ComponentAPI title="AnimationToggle" key="AnimationToggle" docs={animationToggleDocs} />,
+        <UtilAPI key="UseAnimationToggleDocs" docs={useAnimationToggleDocs} />,
+        <UtilAPI key="AnimationToggleContextDocs" docs={animationToggleContextDocs} />,
+    ];
+}
+
+export default DevelopSection;
+
+