@splunk/react-ui 5.7.1 → 5.8.0

package/docs-llm/Paragraph.md

@@ -0,0 +1,148 @@
+# Paragraph
+
+## Overview
+
+
+> Image: Illustration of Paragraph component.
+
+
+## When to use this component
+- To provide a structured layout for textual sentence-style information.
+
+## When to use another component
+- If the content involves listing or numbering items, using `List` improves readability and organization.
+- If the content involves related data elements, using `Definition List` provides a structured visual representation for key-value pairs.
+
+```mermaid
+graph TD
+    accDescr: Decision tree that guides on when to use the Paragraph component or something else
+    A(Does the content involve listing items?) -- Yes --- B(List or Definition List)
+    A -- No --- C(Paragraph)
+```
+
+### Check out
+- [List][1]
+- [Definition List][2]
+
+## Usage
+
+### Break paragraphs into small chunks
+Shorter paragraphs improves readability and reduces eye fatigue.
+
+> Image: Examples of Paragraph components. In the first example with heart eyes emoji, the text is formatted into two smaller paragraphs. In the second example with grimacing emoji the text is formatted in one longer paragraph.
+
+
+### Avoid standalone paragraphs
+Paragraphs should be accompanied by a header that summarizes the content, guides the user’s attention and allows screen readers to navigate to the content.
+
+> Image: Examples of Paragraph components. In the first example with heart eyes emoji, the paragraph is accompanied by a header, while the second example with grimacing emoji is a stand alone paragraph.
+
+
+## Content guidelines
+Follow writing best practices outlined in the [UI text style guidelines][3]
+
+[1]: ./List
+[2]: ./DefinitionList
+[3]: https://docs.splunk.com/Documentation/StyleGuide/current/StyleGuide/UIGuidelines
+
+
+## Examples
+
+
+### Basic
+
+Paragraph provides default fonts, line heights, and spacing. Margins can be removed when necessary.
+
+```typescript
+import React from 'react';
+
+import Link from '@splunk/react-ui/Link';
+import P from '@splunk/react-ui/Paragraph';
+
+
+function Basic() {
+    return (
+        <>
+            <P>
+                Use Splunk products to take advantage of one platform for all your security and
+                observability data needs. In an ever-changing world, Splunk delivers insights to
+                unlock innovation, enhance security and drive resilience.
+            </P>
+            <P>
+                <Link to="https://www.splunk.com/en_us/products/platform.html" openInNewContext>
+                    The Splunk Platform
+                </Link>{' '}
+                allows you turn data into doing to unlock innovation, enhance security and drive
+                resilience.{' '}
+                <Link
+                    to="https://www.splunk.com/en_us/products/cyber-security.html"
+                    openInNewContext
+                >
+                    Splunk Security
+                </Link>{' '}
+                protects your business and modernize your security operations with a best-in-class
+                data platform, advanced analytics and automated investigations and response.{' '}
+                <Link
+                    to="https://www.splunk.com/en_us/products/observability.html"
+                    openInNewContext
+                >
+                    Splunk Observability
+                </Link>{' '}
+                solves problems in seconds with the only full-stack, analytics-powered and
+                OpenTelemetry-native observability solution.
+            </P>
+        </>
+    );
+}
+
+export default Basic;
+```
+
+
+
+
+## API
+
+
+### Paragraph API
+
+#### Props
+
+| Name | Type | Required | Default | Description |
+|------|------|------|------|------|
+| children | React.ReactNode | no |  | Generally text, but might also include `Link`s. |
+| elementRef | React.Ref<HTMLParagraphElement> | no |  | A React ref which is set to the DOM element when the component mounts and null when it unmounts. |
+
+
+
+
+
+## Accessibility
+
+## Visual Design
+- Color contrast ratio **MUST** be [SC 1.4.3][1]
+    - &gt= 4.5:1 for normal text: 14 pt (typically 18.66px) and bold or larger
+    - &gt= 3:1 for large text: 18 pt (typically 24px) or larger
+    - For high contrast mode, ratios **MUST** be &gt=7:1 for normal text and &gt=4.5:1 for large text [SC 1.4.6][2]
+
+## States
+- Color contrast guidelines do NOT apply to disabled text
+
+## Interaction Model
+- **MUST NOT** lose content or functionality when the user adapts [SC 1.4.12][3]
+    - Line height (line spacing) to at least 1.5 times the font size;
+    - Spacing following paragraphs to at least 2 times the font size;
+    - Letter spacing (tracking) to at least 0.12 times the font size;
+    - Word spacing to at least 0.16 times the font size
+- Line spacing (leading) **MUST** be at least space-and-a-half within paragraphs, and paragraph spacing is at least 1.5 times larger than the line spacing [SC 1.4.8][4]
+
+## Implementation
+- **SHOULD** use correct [phrasing elements][5] to describe the semantics of the content
+
+[1]: https://www.w3.org/WAI/GL/UNDERSTANDING-WCAG20/visual-audio-contrast-contrast.html
+[2]: https://www.w3.org/TR/WCAG21/#contrast-enhanced
+[3]: https://www.w3.org/TR/WCAG21/#text-spacing
+[4]: https://www.w3.org/TR/WCAG21/#visual-presentation
+[5]: https://developer.mozilla.org/en-US/docs/Web/Guide/HTML/Content_categories#phrasing_content
+
+

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. |
+
+
+
+
+