@splunk/react-ui 5.7.0 → 5.8.0

package/docs-llm/Number.md

@@ -0,0 +1,298 @@
+# Number
+
+## Overview
+
+
+
+> Image: Illustration of a number component
+
+
+<Message appearance="fill" type="info">
+    <div>All data entry components should be wrapped in a <Link to="ControlGroup">Control Group</Link> to provide a label, error states, and help or error text, ensuring an accessible experience for all users.</div>
+</Message>
+
+
+
+## When to use this component
+- The user only needs to input numeric values.
+- Increasing or decreasing by small values only requires a few clicks.
+
+
+## When to use another component
+- Large value changes are expected.
+- Exact values need to be specified within a wide range.
+- Consider the `Slider` component for inputs that aren’t precise.
+- Consider `Text` or `Text Area` for inputs that are a mix of numbers and text
+- For a predetermined list of values the user can select from, use `Select`.
+
+```mermaid
+graph TD
+    accDescr: Decision tree that guides on when to use the Number component or something else
+    A(Is the input solely numerical?) -- Yes --- B(Is the number input from a predetermined range?)
+    B -- Yes --- C(Slider)
+    B -- No --- D(Is the number input from a predetermined list?)
+    D -- Yes --- E(Select)
+    D -- No --- F(Number)
+    A -- No --- G(Text/Text Area)
+```
+
+### Check out
+- [Slider][1]
+- [Text][2]
+- [Text Area] [3]
+- [Select][4]
+
+## Behaviors
+### Locale
+Number inputs can automatically convert periods to commas for decimal places based on the user's regional settings.
+
+## Usage
+### Avoid placeholder text
+Placeholder text presents a number of visual and cognitive issues; it is best to avoid using it. Placeholder does not replace a label. [Splunk Style Guide placeholder guidelines][5]
+
+> Image: Image showing a comparison between two number input fields and ways to show placeholders. The correct version on the left shows a number input field with the placeholder text displayed underneath the input field, providing clear contextual information. The incorrect version shows a number input field with the placeholder text inside the input field, which could be mistaken for user input.
+
+
+### Adjust width to support longest values
+Adjust the width to accommodate the anticipated input length, ensuring it is sufficiently wide to support the longest expected values. Avoid extending Number across the entire width of large viewports to maintain usability and readability.
+
+> Image: Image showing a comparison between two number input fields and widths based on content. The correct version of the left shows a number input field with a reasonable width that accommodates the longest expected values, ensuring a clean and efficient design. The incorrect version shows a number input field that is excessively long, wasting space and making the design look unbalanced.
+
+
+
+## Content guidelines
+
+### Use descriptive labels
+The required labels on top of the number input field should be descriptive to ensure users do not type in additional text along with the number. They should still champion brevity and use sentence-case capitalization.
+
+> Image: Image showing a comparison between two number input fields for price. The correct example includes the currency denotated in the label, while the incorrect example requires the user to enter the currency symbol inside the number input field.
+
+
+[1]: ./Slider
+[2]: ./Text
+[3]: ./TextArea
+[4]: ./Select
+[5]: https://docs.splunk.com/Documentation/StyleGuide/drafts/StyleGuide/UIGuidelines#Placeholder_text
+
+## Examples
+
+
+### Controlled
+
+Number requires a value prop and an onChange callback to update the value prop for most use cases. Set value to null.
+
+```typescript
+import React, { Component } from 'react';
+
+import Number, { NumberChangeHandler } from '@splunk/react-ui/Number';
+
+
+class Basic extends Component<object, { value?: number }> {
+    constructor(props: object) {
+        super(props);
+
+        this.state = {
+            value: undefined, // default empty
+        };
+    }
+
+    handleChange: NumberChangeHandler = (e, { value }) => {
+        this.setState({ value });
+    };
+
+    render() {
+        return <Number value={this.state.value} onChange={this.handleChange} inline />;
+    }
+}
+
+export default Basic;
+```
+
+
+
+### Uncontrolled
+
+Alternately, 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 Number from '@splunk/react-ui/Number';
+
+
+function Uncontrolled() {
+    return <Number inline />;
+}
+
+export default Uncontrolled;
+```
+
+
+
+### Limits
+
+Number accepts min, max, step, and roundTo props.
+
+```typescript
+import React, { Component } from 'react';
+
+import Number, { NumberChangeHandler } from '@splunk/react-ui/Number';
+
+
+class Limits extends Component<object, { value?: number }> {
+    constructor(props: object) {
+        super(props);
+
+        this.state = {
+            value: undefined, // default empty
+        };
+    }
+
+    handleChange: NumberChangeHandler = (e, { value }) => {
+        this.setState({ value });
+    };
+
+    render() {
+        return (
+            <Number
+                value={this.state.value}
+                max={10}
+                min={-10}
+                roundTo={1}
+                step={0.1}
+                onChange={this.handleChange}
+                inline
+            />
+        );
+    }
+}
+
+export default Limits;
+```
+
+
+
+### Locale
+
+A locale can be included which may change the decimal separator to a comma.
+
+```typescript
+import React, { Component } from 'react';
+
+import Number, { NumberChangeHandler } from '@splunk/react-ui/Number';
+
+
+class Locale extends Component<object, { value?: number }> {
+    constructor(props: object) {
+        super(props);
+
+        this.state = {
+            value: 2.4,
+        };
+    }
+
+    handleChange: NumberChangeHandler = (e, { value }) => {
+        this.setState({ value });
+    };
+
+    render() {
+        return (
+            <Number
+                locale="fr-FR"
+                step={0.15}
+                value={this.state.value}
+                onChange={this.handleChange}
+                inline
+            />
+        );
+    }
+}
+
+export default Locale;
+```
+
+
+
+### Error
+
+```typescript
+import React from 'react';
+
+import Number from '@splunk/react-ui/Number';
+
+
+function NumberError() {
+    return <Number error defaultValue={2020} inline />;
+}
+export default NumberError;
+```
+
+
+
+### Disabled
+
+```typescript
+import React from 'react';
+
+import Number from '@splunk/react-ui/Number';
+
+
+function Disabled() {
+    return <Number disabled defaultValue={2020} inline />;
+}
+
+export default Disabled;
+```
+
+
+
+
+## API
+
+
+### Number API
+
+#### Props
+
+| Name | Type | Required | Default | Description |
+|------|------|------|------|------|
+| append | boolean | no |  | Append removes the rounded borders and the border from the right side and moves the increment and decrement buttons to the left. |
+| children | React.ReactNode | no |  |  |
+| defaultValue | number | 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 if the input is editable. |
+| 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. |
+| hideStepButtons | boolean | no |  | Hides the increment and decrement step buttons if true. |
+| inline | boolean | no |  | When false, displays as inline-block with the default width. |
+| inputId | string | no |  | An id for the input, which may be necessary for accessibility, such as for aria attributes. |
+| 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. |
+| locale | string | no | 'en-US' | The locale determines the decimal separator. Supported locale formats are: `xx`, `xx-XX`, and `xx_XX`. |
+| max | number | no |  | The largest allowable value. |
+| min | number | no |  | The smallest allowable value. |
+| name | string | no |  | The name is returned with onChange events, which can be used to identify the control when multiple controls share an onChange callback. |
+| onBlur | NumberBlurHandler | no |  | A callback for when the input loses focus. |
+| onChange | NumberChangeHandler | no |  | This is equivalent to onInput which is called on keydown, paste, and so on. If value is set, this callback is required. This must set the value prop to retain the change. |
+| onClick | React.MouseEventHandler<HTMLInputElement> | no |  | A callback for when the input is clicked. This will only trigger when the textbox itself is clicked and will not trigger for other parts of the component such as the step buttons. |
+| onFocus | NumberFocusHandler | no |  | A callback for when the input takes focus. |
+| onKeyDown | React.KeyboardEventHandler<HTMLInputElement> | no |  | A keydown callback can be used to prevent a certain input by utilizing the event argument. |
+| onKeyUp | React.KeyboardEventHandler<HTMLDivElement> | no |  | A keyup callback. |
+| onSelect | React.ReactEventHandler<HTMLInputElement> | no |  | A callback for when the user selects text. |
+| prepend | boolean | no |  | Prepend removes rounded borders from the left side. This cannot be used in combination with append. |
+| roundTo | number | no | 5 | The number of decimal places for rounding. Set to zero to limit input to integers. Negative numbers are supported. For instance, -2 will round to the nearest hundred. |
+| step | number | no | 1 | The amount of increment and decrement applied by the buttons and arrow keys. |
+| value | number | no |  | The contents of the input. Setting this value makes the property controlled. A callback is required. |
+
+#### Types
+
+| Name | Type | Description |
+|------|------|------|
+| NumberBlurHandler | (     event: React.FocusEvent<HTMLInputElement>,     data: {         name?: string;         value: string;     } ) => void |  |
+| NumberChangeHandler | (     event:         \| React.ChangeEvent<HTMLInputElement>         \| React.KeyboardEvent<HTMLInputElement>         \| React.MouseEvent<HTMLAnchorElement \| HTMLButtonElement \| HTMLSpanElement>,     data: {         name?: string;         value?: number;         reason: 'input' \| 'stepButton';     } ) => void |  |
+| NumberFocusHandler | (     event: React.FocusEvent<HTMLInputElement>,     data: {         name?: string;         value: string;     } ) => void |  |
+
+
+
+
+

package/docs-llm/Paginator.md

@@ -0,0 +1,395 @@
+# Paginator
+
+## Overview
+
+
+> Image: Illustration of a Paginator component.
+
+
+## When to use this component
+- When you have a large amount of data or content that needs to be divided into smaller, more manageable chunks for users to view sequentially.
+- When you want to maintain performance and reduce load times by displaying only a subset of data at a time.
+- When users need to navigate a gallery of content, such as videos.
+
+## When to use another component
+- If you only have a small amount of data to display, such as single page content.
+
+```mermaid
+graph TD
+    accDescr: Decision tree that guides on when to use the Paginator component or something else
+    A(Does the user need to sequentially navigate a large data collection?) -- Yes --- B(Paginator)
+    A -- No --- C(Does the user prefer uninterrupted scrolling through data?)
+    C -- Yes --- D(Infinite Scroll)
+    C -- No --- E(Load More Button)
+```
+
+
+### Appearance
+
+#### Grouping variants
+Use a Paginator at the top and bottom of longer tables for improved keyboard navigation.
+
+> Image: Illustration of a data table component utilizing both the compact and default paginator. The compact Paginator is at the top of the table, right aligned, and it includes the Page Control. The default Paginator is at the bottom of the table.
+
+
+## Behaviors
+The paginator automatically indicates when users are on the first or last page by disabling the previous or next buttons as needed.
+
+> Image: Examples illustrating the disabled and enabled states as a visual indicator for navigation controls.
+
+
+## Usage
+
+### Default
+
+> Image: Example of Default Paginator, showing the first page as active.
+
+
+### Page Control
+ The Page Control is utilized only with the Compact variant of the Paginator component.
+
+> Image: Example of Page Control Paginator, with the label displaying the total page number. 
+
+
+### Page Control without a label
+Use Page Control without a label when there's a need to save space within a page.
+
+> Image: Example of Page Control Paginator, without the label. 
+
+
+### Compact
+
+> Image: Example of Compact Paginator, with the label displaying the total page number. 
+
+
+### Compact without a label
+
+> Image: Example of Compact Paginator, without the label.
+
+
+### Loading
+ Use [Wait Spinner] [1] when a page change is initiated and will only take a few seconds.
+
+> Image: Examples illustrating the Paginator with a table and a wait spinner. The first example, marked with a heart eyes emoji, displays the paginator component with the data table and a wait spinner as the user navigates to a second page. The second example, identified by a grimacing face emoji, presents the paginator component with an empty table and no spinner as the user navigates to the second page.
+
+
+### Paginator with table
+
+The Paginator can be paired with other components, such as the [Table][2], enabling users to navigate data sets in a specific order.
+
+> Image: An abstract illustration of a data table with a Paginator component.
+
+
+### Navigating galleries
+
+The Paginator can be also utilized to navigate [Card] [3] galleries and other sequential content.
+
+> Image: An abstract illustration with three cards in preview and a paginator.
+
+
+[1]: ./WaitSpinner
+[2]: ./Table
+[3]: ./Card
+
+
+## Examples
+
+
+### Basic
+
+```typescript
+import React, { useState } from 'react';
+
+import Paginator, { PaginatorChangeHandler } from '@splunk/react-ui/Paginator';
+
+
+function Basic() {
+    const [pageNum, setPageNum] = useState(3);
+
+    const handleChange: PaginatorChangeHandler = (event, { page }) => {
+        setPageNum(page);
+    };
+
+    return (
+        <Paginator
+            onChange={handleChange}
+            current={pageNum}
+            alwaysShowLastPageLink
+            totalPages={30}
+        />
+    );
+}
+
+export default Basic;
+```
+
+
+
+### Labelled
+
+When possible, a Paginator should use aria-labelledby or aria-label to provide an accessible label describing the content that is being paginated.
+
+```typescript
+import React, { useState } from 'react';
+
+import Heading from '@splunk/react-ui/Heading';
+import Paginator, { PaginatorChangeHandler } from '@splunk/react-ui/Paginator';
+import { createDOMID } from '@splunk/ui-utils/id';
+
+
+function Labelled() {
+    const [pageNum, setPageNum] = useState(3);
+
+    const handleChange: PaginatorChangeHandler = (event, { page }) => {
+        setPageNum(page);
+    };
+
+    const labelId = createDOMID('labelled');
+
+    return (
+        <>
+            <Heading level={4} id={labelId} style={{ margin: 0 }}>
+                Paginated content example
+            </Heading>
+            <Paginator
+                aria-labelledby={labelId}
+                onChange={handleChange}
+                current={pageNum}
+                alwaysShowLastPageLink
+                totalPages={30}
+            />
+        </>
+    );
+}
+
+export default Labelled;
+```
+
+
+
+### Page control
+
+A Paginator control that allows any page to be selected.
+
+```typescript
+import React, { useState } from 'react';
+
+import Paginator, { PaginatorPageControlChangeHandler } from '@splunk/react-ui/Paginator';
+
+
+function PageControl() {
+    const [pageNum, setPageNum] = useState(3);
+
+    const handleChange: PaginatorPageControlChangeHandler = (event, { page }) => {
+        setPageNum(page);
+    };
+
+    return <Paginator.PageControl onChange={handleChange} current={pageNum} totalPages={30} />;
+}
+
+export default PageControl;
+```
+
+
+
+### Custom pages
+
+Customize Paginator's pages and Prev/Next buttons with generatePageProps.
+
+```typescript
+import React, { useState } from 'react';
+
+import Paginator, {
+    PaginatorGeneratePageProps,
+    PaginatorChangeHandler,
+} from '@splunk/react-ui/Paginator';
+
+
+function CustomPages() {
+    const [currentPage, setCurrentPage] = useState<number>(3);
+
+    const handleChange: PaginatorChangeHandler = (e, { page }) => {
+        e.preventDefault();
+        setCurrentPage(page);
+    };
+
+    const generatePageProps: PaginatorGeneratePageProps = ({ page }) => {
+        return {
+            to: `#page-${page}`,
+        };
+    };
+
+    return (
+        <Paginator
+            alwaysShowLastPageLink
+            generatePageProps={generatePageProps}
+            current={currentPage}
+            onChange={handleChange}
+            totalPages={30}
+        />
+    );
+}
+
+export default CustomPages;
+```
+
+
+
+### Compact
+
+A Paginator control with buttons only.
+
+```typescript
+import React, { useState } from 'react';
+
+import Paginator, { PaginatorCompactChangeHandler } from '@splunk/react-ui/Paginator';
+
+
+function Compact() {
+    const [pageNum, setPageNum] = useState<number | undefined>(3);
+
+    const handleChange: PaginatorCompactChangeHandler = (event, { page }) => {
+        setPageNum(page);
+    };
+
+    return <Paginator.Compact current={pageNum} onChange={handleChange} totalPages={30} />;
+}
+
+export default Compact;
+```
+
+
+
+### Compact with label
+
+```typescript
+import React, { useState } from 'react';
+
+import Paginator, { PaginatorCompactChangeHandler } from '@splunk/react-ui/Paginator';
+
+
+function CompactWithLabel() {
+    const [pageNum, setPageNum] = useState<number | undefined>(3);
+
+    const handleChange: PaginatorCompactChangeHandler = (event, { page }) => {
+        setPageNum(page);
+    };
+
+    return (
+        <Paginator.Compact current={pageNum} onChange={handleChange} renderLabel totalPages={30} />
+    );
+}
+
+export default CompactWithLabel;
+```
+
+
+
+### Compact with custom label
+
+```typescript
+import React, { useState } from 'react';
+
+import Paginator, { PaginatorCompactChangeHandler } from '@splunk/react-ui/Paginator';
+
+
+function CompactCustomLabel() {
+    const [pageNum, setPageNum] = useState<number | undefined>(1);
+    const itemsPerPage = 50;
+    const totalItems = 300;
+
+    const handleChange: PaginatorCompactChangeHandler = (event, { page }) => {
+        setPageNum(page);
+    };
+
+    return (
+        <Paginator.Compact
+            current={pageNum}
+            onChange={handleChange}
+            renderLabel={({ current }) => {
+                if (current) {
+                    const pageEnd = current * itemsPerPage;
+                    const pageStart = pageEnd - itemsPerPage + 1;
+                    return `${pageStart}-${pageEnd} of ${totalItems}`;
+                }
+                return `0-${itemsPerPage} of ${totalItems}`;
+            }}
+            totalPages={totalItems / itemsPerPage}
+        />
+    );
+}
+
+export default CompactCustomLabel;
+```
+
+
+
+
+## API
+
+
+### Paginator API
+
+#### Props
+
+| Name | Type | Required | Default | Description |
+|------|------|------|------|------|
+| alwaysShowLastPageLink | boolean | no | false | Displays a link to the last page in a collection. |
+| current | number | no | 1 | Currently selected page. |
+| elementRef | React.Ref<HTMLElement> | no |  | A React ref which is set to the DOM element when the component mounts and null when it unmounts. |
+| generatePageProps | PaginatorGeneratePageProps | no |  | Passes props to Paginator's pages and Prev/Next buttons. Supports [Clickable](./Clickable) props (except for `onClick`) and global HTML attributes. `generatePageProps` will not differentiate between Prev/Next buttons and its corresponding page. For example, if page 5 is passed prop P and current is 6, the Prev button will also be passed prop P. |
+| numPageLinks | number | no | 5 | Number of pages to display. If greater than `totalPages`, `totalPages` is used instead. |
+| onChange | PaginatorChangeHandler | no |  | Callback to handle page change. |
+| totalPages | number | yes |  | The total number of pages. |
+
+#### Types
+
+| Name | Type | Description |
+|------|------|------|
+| PaginatorChangeHandler | (     event: React.MouseEvent<HTMLButtonElement>,     data: { page: number } ) => void |  |
+| PaginatorGeneratePageProps | ({     page, }: {     page: number; }) => Partial<React.ComponentProps<typeof Clickable>> &     React.ComponentProps<'a'> &     React.ComponentProps<'button'> |  |
+
+
+
+### Page Control API
+
+#### Props
+
+| Name | Type | Required | Default | Description |
+|------|------|------|------|------|
+| current | number | no | 1 | Currently selected page. |
+| elementRef | React.Ref<HTMLElement> | no |  | A React ref which is set to the DOM element when the component mounts and null when it unmounts. |
+| onChange | PaginatorPageControlChangeHandler | no |  | Callback to handle page change. |
+| totalPages | number | yes |  | The total number of pages. |
+
+#### Types
+
+| Name | Type | Description |
+|------|------|------|
+| PaginatorPageControlChangeHandler | (     event: React.MouseEvent<HTMLButtonElement> \| React.KeyboardEvent<HTMLInputElement>,     data: { page: number } ) => void |  |
+
+
+
+### Compact API
+
+#### Props
+
+| Name | Type | Required | Default | Description |
+|------|------|------|------|------|
+| current | number | no |  | The current page number. If not provided, the component will not keep track of the page number and will not provide it in the callback. |
+| elementRef | React.Ref<HTMLElement> | no |  | A React ref which is set to the DOM element when the component mounts and null when it unmounts. |
+| onChange | PaginatorCompactChangeHandler | no |  | Callback to handle page change. |
+| renderLabel | boolean \| PaginatorCompactRenderLabelCallback | no |  | If true, renders the a label for the current and total pages. Can be passed a function to render a custom label that receives an object with current and totalPages as an argument. |
+| totalPages | number | no |  | The total number of pages. If not provided, the component will operate in indeterminate mode and will not prevent the current page number from exceeding any values. |
+
+#### Types
+
+| Name | Type | Description |
+|------|------|------|
+| PaginatorCompactChangeHandler | (     event: React.MouseEvent<HTMLButtonElement> \| React.KeyboardEvent<HTMLInputElement>,     data: { direction: 'prev' \| 'next'; page?: number } ) => void |  |
+| PaginatorCompactRenderLabelCallback | (data: {     current?: number;     totalPages?: number; }) => React.ReactNode |  |
+
+
+
+
+