@splunk/react-ui 5.7.1 → 5.9.0

package/docs-llm/Phone Number.md

@@ -0,0 +1,254 @@
+# Phone Number
+
+## Overview
+
+
+> Image: Illustration of a Phone Number component.
+
+
+<Message appearance="fill" type="info">
+    <div>All data entry components should be wrapped in a [Control Group](ControlGroup) 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
+- When collecting phone numbers from users
+- When forms or pages require a validated phone number input
+
+## When to use another component
+- If the input doesn't require formatting, a country code, or is not specifically for phone numbers, consider using Text
+
+```mermaid
+graph TD
+    accDescr: Decision tree that guides on when to use the Phone Number component or something else
+    A(Do you need to collect a phone number?) -- Yes --- B(Use Phone Number)
+    A -- No --- C(Is the input freeform text?)
+    C -- Yes --- D(Use Text)
+    C -- No --- E(Use Select)
+```
+
+### Check out
+- [Select][1]
+- [Text][2]
+
+## Behaviors
+
+### Validation
+Validates phone number format and length based on the selected country.
+Use  <Link to="ControlGroup">Control Group</Link> to display validation results.
+> Image: Example of phone number validation.
+
+
+### Locale
+Defaults the country code and formatting based on the user’s locale.
+> Image: Example of locale-based default.
+
+
+### Searchable dropdown
+Allows users to filter the country code list by typing either a country name or a dial code.
+> Image: Examples of filtering country codes in the dropdown.
+
+
+## Usage
+
+### Use clear and visible labels
+Use a visible label like “Phone Number” to clearly describe the input. Avoid using placeholder phone numbers as a substitute for labeling to maintain accessibility.
+> Image: Examples of Phone Number labeling. The first example with heart eyes shows a clearly labeled input. The second example with a grimacing face shows a placeholder used instead of a label, reducing accessibility.
+
+
+### Match input width to phone number length
+Match the width of the input to the expected phone number length. Avoid stretching the component across the full page or making it too short to view the full value at a glance.
+> Image: Examples of Phone Number input width. The first example with heart eyes shows a field sized to match a typical phone number. The second example with a grimacing face shows an overly wide field that reduces readability.
+
+
+[1]: ./Select
+[2]: ./Text
+
+
+
+## Examples
+
+
+### Controlled
+
+Phone Number requires a `value` prop and an `onChange` callback to update the value prop for most use cases.
+
+```typescript
+import React, { useState } from 'react';
+
+import PhoneNumber, { PhoneNumberChangeHandler } from '@splunk/react-ui/PhoneNumber';
+
+
+const Controlled = () => {
+    const [value, setValue] = useState('2345678910');
+
+    const handleChange: PhoneNumberChangeHandler = (e, { value: newValue }) => {
+        setValue(newValue);
+    };
+
+    return <PhoneNumber value={value} onChange={handleChange} />;
+};
+
+export default Controlled;
+```
+
+
+
+### Uncontrolled
+
+Alternatively, Phone Number 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 PhoneNumber from '@splunk/react-ui/PhoneNumber';
+
+
+function Uncontrolled() {
+    return <PhoneNumber defaultValue="2345678910" />;
+}
+
+export default Uncontrolled;
+```
+
+
+
+### Default Country
+
+Phone Number can have a different default country set.
+
+```typescript
+import React, { useState } from 'react';
+
+import PhoneNumber, { PhoneNumberChangeHandler } from '@splunk/react-ui/PhoneNumber';
+
+
+const DefaultCountry = () => {
+    const [value, setValue] = useState('2345678910');
+
+    const handleChange: PhoneNumberChangeHandler = (e, { value: newValue }) => {
+        setValue(newValue);
+    };
+
+    return <PhoneNumber defaultCountry="CA" value={value} onChange={handleChange} />;
+};
+
+export default DefaultCountry;
+```
+
+
+
+### Inline
+
+The `inline` prop will render the component inline at a consistent width with other inputs.
+
+```typescript
+import React, { useState } from 'react';
+
+import PhoneNumber, { PhoneNumberChangeHandler } from '@splunk/react-ui/PhoneNumber';
+
+
+const Inline = () => {
+    const [value, setValue] = useState('2345678910');
+
+    const handleChange: PhoneNumberChangeHandler = (e, { value: newValue }) => {
+        setValue(newValue);
+    };
+
+    return <PhoneNumber inline value={value} onChange={handleChange} />;
+};
+
+export default Inline;
+```
+
+
+
+### Error
+
+```typescript
+import React, { useState } from 'react';
+
+import PhoneNumber, { PhoneNumberChangeHandler } from '@splunk/react-ui/PhoneNumber';
+
+
+const Error = () => {
+    const [value, setValue] = useState('2345678910');
+
+    const handleChange: PhoneNumberChangeHandler = (e, { value: newValue }) => {
+        setValue(newValue);
+    };
+
+    return <PhoneNumber error value={value} onChange={handleChange} />;
+};
+
+export default Error;
+```
+
+
+
+### Disabled
+
+```typescript
+import React, { useState } from 'react';
+
+import PhoneNumber, { PhoneNumberChangeHandler } from '@splunk/react-ui/PhoneNumber';
+
+
+const Disabled = () => {
+    const [value, setValue] = useState('2345678910');
+
+    const handleChange: PhoneNumberChangeHandler = (e, { value: newValue }) => {
+        setValue(newValue);
+    };
+
+    return <PhoneNumber disabled value={value} onChange={handleChange} />;
+};
+
+export default Disabled;
+```
+
+
+
+
+## API
+
+
+### PhoneNumber API
+
+#### Props
+
+| Name | Type | Required | Default | Description |
+|------|------|------|------|------|
+| append | boolean | no |  | Append removes rounded corners and the border from the right side. |
+| canClear | boolean | no | true | Include an "X" button to clear the value. |
+| defaultCountry | string | no |  | The iso2 country code to use for the phone number input. |
+| defaultValue | string | no |  | Set this property instead of value to make the value 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 |  | Determines whether or not the input is disabled. |
+| elementRef | React.Ref<HTMLDivElement> | no |  | A React ref which is set to the DOM element when the component mounts, and null when it unmounts. |
+| error | boolean | no |  | Highlight the field as having an error. |
+| inline | boolean | no |  | When true, displays inline with a default width. |
+| inputId | string | no |  | An id for the text input. |
+| inputRef | React.Ref<HTMLInputElement> | no |  | A React ref which is set to the text 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 |  |  |
+| onBlur | PhoneNumberBlurHandler | no |  | A callback for when the input loses focus. |
+| onChange | PhoneNumberChangeHandler | no |  | Called whenever the value changes. If the value prop is set, this callback is required. |
+| onClick | React.MouseEventHandler<HTMLInputElement> | no |  | A callback for when the input is clicked. |
+| onFocus | PhoneNumberFocusHandler | no |  | A callback for when the input takes focus. |
+| onSelect | React.ReactEventHandler<HTMLInputElement> | no |  | A callback for when the user selects text. |
+| prepend | boolean | no |  | Prepend removes rounded borders from the left side. |
+| toggleRef | React.Ref<HTMLButtonElement> | no |  | A React ref which is set to the dropdown toggle when the component mounts and null when it unmounts. |
+| value | string | no |  | The contents of the input. Setting this value makes the input controlled. A callback is required. |
+
+#### Types
+
+| Name | Type | Description |
+|------|------|------|
+| PhoneNumberBlurHandler | (     event: React.FocusEvent<HTMLInputElement>,     data: {         name?: string;         value: string;         displayValue: string;         country?: string;         isPossibleNumber: boolean;         isValidNumber: boolean;         internationalFormat: string;     } ) => void |  |
+| PhoneNumberChangeHandler | (     event:         \| React.ChangeEvent<HTMLInputElement>         \| React.KeyboardEvent<HTMLInputElement>         \| React.MouseEvent<HTMLButtonElement \| HTMLSpanElement>,     data: {         name?: string;         value: string;         displayValue: string;         country?: string;         isPossibleNumber: boolean;         isValidNumber: boolean;         internationalFormat: string;     } ) => void |  |
+| PhoneNumberFocusHandler | (     event: React.FocusEvent<HTMLInputElement>,     data: {         name?: string;         value: string;         displayValue: string;         country?: string;         isPossibleNumber: boolean;         isValidNumber: boolean;         internationalFormat: string;     } ) => void |  |
+
+
+
+
+

package/docs-llm/Popover.md

@@ -0,0 +1,166 @@
+# Popover
+
+## Overview
+
+
+
+> Image: Illustration of a popover component.
+
+
+
+## When to use this component
+- Use a Popover for brief, persistent hints tied to an element.
+- To provide non-essential supporting information for specific elements on a page.
+- To provide additional interactions with the supporting information.
+
+## When to use another component
+- When you have multiple steps that the user needs to go through, implement a [Modal][2].
+- If the content is critical and should always be visible, keep the content visible on a page.
+- If the content is critical or must remain visible use [Message][4] or [Message Bar][5].
+
+```mermaid
+graph TD
+    accDescr: Decision tree that guides on when to use the Popover component or something else
+    A(Is the content secondary and shown on demand?) -- Yes --- B(Does the content include interactive elements?)
+    B -- Yes --- C(Does the user need to select an option from a list?)
+    C -- Yes --- D(Select, Multiselect, or Radio List)
+    C -- No --- E(Popover)
+    B -- No --- F(Tooltip)
+    A -- No --- G(Keep the content visible on the page)
+```
+
+### Check out
+- [Tooltip][1]
+- [Modal] [2]
+- [Dropdown][3]
+- [Message][4]
+- [Message Bar][5]
+
+## Behaviors
+
+### Interactive
+Popovers include interactive content, and must be activated on click rather than hover.
+
+ > Image: Illustration of two Popovers. The first example with heart eyes emoji shows a Popover with multiple interactive elements that is activated on click. The second example with grimacing emoji shows a Popover with multiple interactive elements that is activated on hover.
+
+
+## Usage
+
+### Limit content
+Use Popover for brief, task-related content like definitions or quick actions. Avoid long text, complex interactions, or stacking Popovers.
+
+> Image: Illustration of two Popovers. The first example with heart eyes emoji shows a Popover announcing a new feature, and a single call-to-action labeled as ‘Continue’. The second example with grimacing emoji shows two stacked Popovers with multiple interactive elements.
+
+
+### Supplemental
+Supports content that is nonessential to the primary task.
+> Image: Illustration of two Popovers. The first example with heart eyes emoji shows a Popover in a focus state with the header ‘New Feature Available’. The second example with grimacing emoji shows a Popover opening on hover with buttons and multiple steps.
+
+
+
+[1]: ./Tooltip
+[2]: ./Modal
+[3]: ./Dropdown
+[4]: ./Message
+[5]: ./MessageBar
+
+
+
+## Examples
+
+
+### Basic
+
+Click the button to view the Popover.
+
+```typescript
+import React, { useState, useCallback } from 'react';
+
+import Button from '@splunk/react-ui/Button';
+import Popover from '@splunk/react-ui/Popover';
+
+
+function Example() {
+    const [open, setOpen] = useState(false);
+    const [anchor, setAnchor] = useState<HTMLButtonElement>();
+
+    const anchorRef = useCallback((el: HTMLButtonElement) => setAnchor(el), []);
+    const handleOpen = useCallback(() => setOpen(true), []);
+    const handleRequestClose = useCallback(() => setOpen(false), []);
+
+    return (
+        <>
+            <Button onClick={handleOpen} elementRef={anchorRef} label="Click me" />
+            <Popover open={open} anchor={anchor} onRequestClose={handleRequestClose}>
+                <div style={{ padding: '20px', width: '300px' }}>
+                    This is the content of the popover. You can place any information here.
+                </div>
+            </Popover>
+        </>
+    );
+}
+
+export default Example;
+```
+
+
+
+
+## API
+
+
+### Popover API
+
+`Popover` is used to create layovers such as dropdowns, contextual menus, or tooltips. Use
+this only when the other components don't provide sufficient functionality or control. A controlled
+`Dropdown` covers use cases where you might consider using `Popover` directly.
+
+#### Props
+
+| Name | Type | Required | Default | Description |
+|------|------|------|------|------|
+| anchor | HTMLElement \| null | no |  | The element used to set the position of the `Popover`. It is required when the `Popover` is open and must be mounted. |
+| animation | boolean | no | true | If `true`, the popover applies transitions when it is added to the DOM. |
+| appearance | 'normal' \| 'inverted' \| 'none' | no | 'normal' | **DEPRECATED**: Value 'inverted' `'normal'` is the default appearance.`'none'` is a transparent box.  The 'inverted' value is deprecated and will be removed in a future major version. |
+| autoCloseWhenOffScreen | boolean | no | true | If `true`, the `Popover` hides when the anchor is scrolled off the screen. |
+| canCoverAnchor | boolean | no |  | If there isn't enough room to render the `Popover` in a direction, this option enables it to be rendered over the anchor. |
+| children | React.ReactNode \| PopoverChildrenRenderer | no |  | The content of the `Popover`. If a function is provided, it is invoked with an object containing `anchorHeight`, `anchorWidth`, `maxHeight`, `maxWidth`, and `placement`, and is expected to return renderable content. |
+| closeReasons | PopoverPossibleCloseReason[] | no | [     'clickAway',     'escapeKey',     'offScreen',     'tabKey', ] | An array of reasons for which this `Popover` should close. |
+| defaultPlacement | PopoverPlacement | no | 'below' | The default placement of the `Popover`. It might be rendered in a different direction depending upon the space available and the `repositionMode`. |
+| elementRef | React.Ref<HTMLDivElement> | no |  | A React ref which is set to the DOM element when the component mounts and null when it unmounts. |
+| hideArrow | boolean | no |  | Whether or not to hide the arrow pointing to the anchor.  The arrow is always hidden when `appearance="none"`. |
+| onRequestClose | PopoverRequestCloseHandler | no |  | Callback function fired when the popover is requested to be closed. |
+| open | boolean | no |  | If `true`, the `Popover` is visible. |
+| pointTo | { x?: number; y?: number } | no |  | Allows the `Popover` to point to and align with a different part of the anchor. The x and y values are relative to the upper left corner of the anchor.  This property overides `align`.  When positioned above or below, only `x` is used. When positioned left or right, `y` is used. |
+| repositionMode | 'none' \| 'flip' \| 'any' | no | 'flip' | If the `Popover` doesn't fit in the `defaultPlacement`, `repositionMode` determines if and how the `Popover` repositions itself to fit on the page. `none` doesn't reposition the `Popover`. It always renders in the `defaultPlacement` direction. `flip` allows the `Popover` to reposition to the opposite of the `defaultPlacement` if it can fit there and not in the `defaultPlacement`. `any` allows the `Popover` to reposition in any direction if it can fit on the page. |
+| retainFocus | boolean | no | true | Keeps focus within the `Popover` while open. |
+| splunkTheme |  | no |  |  |
+| takeFocus | boolean | no |  | When `true`, the `Popover` automatically takes focus when 'open' changes to `true`. Disable this for a `Popover` that has shows on hover, such as a tooltip. |
+
+#### Types
+
+| Name | Type | Description |
+|------|------|------|
+| PopoverChildrenRenderer | (data: {     anchorHeight: number \| null;     anchorWidth: number \| null;     maxHeight: number \| null;     maxWidth: number \| null;     placement: PopoverPlacementStatus \| null;     toggleId?: string; }) => React.ReactNode |  |
+| PopoverPlacement | 'above' \| 'below' \| 'left' \| 'right' \| 'vertical' \| 'horizontal' |  |
+| PopoverPlacementStatus | 'above' \| 'below' \| 'left' \| 'right' \| 'misaligned' |  |
+| PopoverPossibleCloseReason | 'clickAway' \| 'escapeKey' \| 'offScreen' \| 'tabKey' |  |
+| PopoverRequestCloseHandler | (data: {     event?: MouseEvent \| KeyboardEvent \| TouchEvent;     reason: PopoverPossibleCloseReason; }) => void |  |
+
+
+
+### PopoverProvider API
+
+Provides a method for controlling certain `Popover` props in components that use `Popover`.
+
+#### Props
+
+| Name | Type | Required | Default | Description |
+|------|------|------|------|------|
+| children | React.ReactNode | no |  |  |
+| hideArrow | boolean | no |  | Whether or not to hide the arrow pointing to the `Popover` anchor.  `Popover`'s `hideArrow` prop takes priority over this. |
+
+
+
+
+

package/docs-llm/Progress.md

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