@splunk/react-ui 5.7.1 → 5.8.0

package/docs-llm/Form Rows.md

@@ -0,0 +1,374 @@
+# Form Rows
+
+## Examples
+
+
+### Basic
+
+```typescript
+import React, { Component } from 'react';
+
+import FormRows, {
+    FormRowsRequestMoveHandler,
+    RowRequestRemoveHandler,
+} from '@splunk/react-ui/FormRows';
+import Text from '@splunk/react-ui/Text';
+import { createDOMID } from '@splunk/ui-utils/id';
+
+
+class Basic extends Component<object, { items: React.ReactElement[] }> {
+    constructor(props: object) {
+        super(props);
+
+        const items = [
+            <FormRows.Row index={0} key="0" onRequestRemove={this.handleRequestRemove}>
+                <Text defaultValue="Just another" />
+            </FormRows.Row>,
+            <FormRows.Row index={1} key="1" onRequestRemove={this.handleRequestRemove}>
+                <Text defaultValue="Row in the form" />
+            </FormRows.Row>,
+        ];
+        this.state = {
+            items,
+        };
+    }
+
+    handleRequestAdd = () => {
+        this.setState((state) => ({
+            items: FormRows.addRow(
+                <FormRows.Row
+                    index={state.items.length}
+                    key={createDOMID()}
+                    onRequestRemove={this.handleRequestRemove}
+                >
+                    <Text />
+                </FormRows.Row>,
+                state.items
+            ),
+        }));
+    };
+
+    handleRequestMove: FormRowsRequestMoveHandler = ({ fromIndex, toIndex }) => {
+        this.setState((state) => ({
+            items: FormRows.moveRow(fromIndex, toIndex, state.items),
+        }));
+    };
+
+    handleRequestRemove: RowRequestRemoveHandler = (e, { index }) => {
+        this.setState((state) => ({
+            items: FormRows.removeRow(index, state.items),
+        }));
+    };
+
+    render() {
+        return (
+            <FormRows
+                onRequestAdd={this.handleRequestAdd}
+                onRequestMove={this.handleRequestMove}
+                style={{ width: 300 }}
+            >
+                {this.state.items}
+            </FormRows>
+        );
+    }
+}
+
+export default Basic;
+```
+
+
+
+### Custom Add Menu
+
+The 'Add row' button can be replaced with a button, multiple buttons, or any other content you want to show below the Form Rows.
+
+```typescript
+import React, { Component } from 'react';
+
+import FormRows, {
+    FormRowsRequestMoveHandler,
+    RowRequestRemoveHandler,
+} from '@splunk/react-ui/FormRows';
+import Number from '@splunk/react-ui/Number';
+import Select, { SelectChangeHandler } from '@splunk/react-ui/Select';
+import Slider from '@splunk/react-ui/Slider';
+import Text from '@splunk/react-ui/Text';
+import { createDOMID } from '@splunk/ui-utils/id';
+
+
+class Menu extends Component<object, { items: React.ReactElement[] }> {
+    constructor(props: object) {
+        super(props);
+
+        this.state = {
+            items: [],
+        };
+    }
+
+    handleRequestAdd: SelectChangeHandler = (e, data) => {
+        let element: React.ReactElement;
+        const { value } = data;
+        switch (value) {
+            case '1':
+                element = <Text />;
+                break;
+            case '2':
+                element = <Slider defaultValue={3} />;
+                break;
+            case '3':
+                element = <Number />;
+                break;
+            default:
+                break;
+        }
+        this.setState((state) => ({
+            items: FormRows.addRow(
+                <FormRows.Row
+                    index={state.items.length}
+                    key={createDOMID()}
+                    onRequestRemove={this.handleRequestRemove}
+                >
+                    {element}
+                </FormRows.Row>,
+                state.items
+            ),
+        }));
+    };
+
+    handleRequestMove: FormRowsRequestMoveHandler = ({ fromIndex, toIndex }) => {
+        this.setState((state) => ({
+            items: FormRows.moveRow(fromIndex, toIndex, state.items),
+        }));
+    };
+
+    handleRequestRemove: RowRequestRemoveHandler = (e, { index }) => {
+        this.setState((state) => ({
+            items: FormRows.removeRow(index, state.items),
+        }));
+    };
+
+    render() {
+        const formMenu = (
+            <Select
+                appearance="default"
+                onChange={this.handleRequestAdd}
+                placeholder="Add"
+                value={0}
+            >
+                <Select.Option label="Text" value="1" />
+                <Select.Option label="Slider" value="2" />
+                <Select.Option label="Number" value="3" />
+            </Select>
+        );
+
+        return (
+            <FormRows onRequestMove={this.handleRequestMove} menu={formMenu}>
+                {this.state.items}
+            </FormRows>
+        );
+    }
+}
+
+export default Menu;
+```
+
+
+
+### spanStyle
+
+```typescript
+import React, { Component } from 'react';
+
+import FormRows, {
+    FormRowsRequestMoveHandler,
+    RowRequestRemoveHandler,
+} from '@splunk/react-ui/FormRows';
+import Text from '@splunk/react-ui/Text';
+import { createDOMID } from '@splunk/ui-utils/id';
+
+const spanStyle: React.CSSProperties = {
+    alignSelf: 'center',
+};
+
+class Header extends Component<object, { items: React.ReactElement[] }> {
+    constructor(props: object) {
+        super(props);
+
+        const items = [
+            <FormRows.Row index={0} key="uniqueRowUno" onRequestRemove={this.handleRequestRemove}>
+                <Text defaultValue="sourceip" />
+                <span style={spanStyle}>=</span>
+                <Text defaultValue="192.168.1.1" />
+            </FormRows.Row>,
+            <FormRows.Row index={1} key="uniqueRowDos" onRequestRemove={this.handleRequestRemove}>
+                <Text defaultValue="uid" />
+                <span style={spanStyle}>=</span>
+                <Text defaultValue="johndoe" />
+            </FormRows.Row>,
+        ];
+        this.state = {
+            items,
+        };
+    }
+
+    handleRequestAdd = () => {
+        this.setState((state) => ({
+            items: FormRows.addRow(
+                <FormRows.Row
+                    index={state.items.length}
+                    key={createDOMID()}
+                    onRequestRemove={this.handleRequestRemove}
+                >
+                    <Text describedBy="header-key" />
+                    <span style={spanStyle}>=</span>
+                    <Text describedBy="header-value" />
+                </FormRows.Row>,
+                state.items
+            ),
+        }));
+    };
+
+    handleRequestMove: FormRowsRequestMoveHandler = ({ fromIndex, toIndex }) => {
+        this.setState((state) => ({
+            items: FormRows.moveRow(fromIndex, toIndex, state.items),
+        }));
+    };
+
+    handleRequestRemove: RowRequestRemoveHandler = (e, { index }) => {
+        this.setState((state) => ({
+            items: FormRows.removeRow(index, state.items),
+        }));
+    };
+
+    render() {
+        const header = (
+            <div>
+                <span
+                    style={{
+                        display: 'inline-block',
+                        width: 172,
+                    }}
+                    id="header-key"
+                >
+                    Key
+                </span>
+                <span style={{ display: 'inline-block' }} id="header-value">
+                    Value
+                </span>
+            </div>
+        );
+        return (
+            <FormRows
+                addLabel="Add input"
+                header={header}
+                onRequestAdd={this.handleRequestAdd}
+                onRequestMove={this.handleRequestMove}
+                style={{ width: 400 }}
+            >
+                {this.state.items}
+            </FormRows>
+        );
+    }
+}
+
+export default Header;
+```
+
+
+
+### Reorder only
+
+The add and delete functionality can be removed by not including the onRequestAdd handler on Form Rows and the onRequestRemove handler on Row. The functionality of reordering Rows will still remain intact. If users can add, they should be able to delete as well.
+
+```typescript
+import React, { Component } from 'react';
+
+import FormRows, { FormRowsRequestMoveHandler } from '@splunk/react-ui/FormRows';
+import Text from '@splunk/react-ui/Text';
+
+
+class ReorderOnly extends Component<object, { items: React.ReactElement[] }> {
+    constructor(props: object) {
+        super(props);
+
+        const items = [
+            <FormRows.Row index={0} key="0">
+                <Text inline defaultValue="You can move me" />
+            </FormRows.Row>,
+            <FormRows.Row index={1} key="1">
+                <Text inline defaultValue="But you can't Add/Remove me" />
+            </FormRows.Row>,
+        ];
+        this.state = {
+            items,
+        };
+    }
+
+    handleRequestMove: FormRowsRequestMoveHandler = ({ fromIndex, toIndex }) => {
+        this.setState((state) => ({
+            items: FormRows.moveRow(fromIndex, toIndex, state.items),
+        }));
+    };
+
+    render() {
+        return (
+            <FormRows onRequestMove={this.handleRequestMove} style={{ width: 300 }}>
+                {this.state.items}
+            </FormRows>
+        );
+    }
+}
+
+export default ReorderOnly;
+```
+
+
+
+
+## API
+
+
+### FormRows API
+
+#### Props
+
+| Name | Type | Required | Default | Description |
+|------|------|------|------|------|
+| addLabel | string | no | _('Add row') | Label on the Add row button. Ignored when menu prop is defined. |
+| disabled | boolean | no |  | Disable the Add row button, the Remove button and the sort/drag action. |
+| elementRef | React.Ref<HTMLDivElement> | no |  | A React ref which is set to the DOM element when the component mounts, and null when it unmounts. |
+| header | React.ReactNode | no |  | Header for the rows. |
+| menu | React.ReactNode | no |  | Replaces Add row button with custom content or controls. |
+| onRequestAdd | React.MouseEventHandler<HTMLButtonElement \| HTMLAnchorElement> | no |  | Callback when the Add row button is clicked. If `onRequestAdd` is defined, 'onRequestRemove' should be defined in `<FormRows.Row>`. Neither should be defined for a reorder-only variant of `<FormRows>`. |
+| onRequestMove | FormRowsRequestMoveHandler | no |  | Callback when sort action completes. Omit this to make rows unsortable. |
+
+#### Types
+
+| Name | Type | Description |
+|------|------|------|
+| FormRowsRequestMoveHandler | (data: { fromIndex: number; toIndex: number }) => void |  |
+
+
+
+### FormRows.Row API
+
+#### Props
+
+| Name | Type | Required | Default | Description |
+|------|------|------|------|------|
+| children | React.ReactNode | no |  |  |
+| elementRef | React.Ref<HTMLDivElement> | no |  | A React ref which is set to the DOM element when the component mounts and null when it unmounts. |
+| index | number | no |  | Index of the row. This is required if the rows are sortable. |
+| onRequestRemove | RowRequestRemoveHandler | no |  | Callback when Remove button is clicked. |
+| value | React.ReactNode | no |  | The contents of Row |
+
+#### Types
+
+| Name | Type | Description |
+|------|------|------|
+| RowRequestRemoveHandler | (     event: React.MouseEvent<HTMLButtonElement>,     data: { index: number } ) => void |  |
+
+
+
+
+

package/docs-llm/Heading.md

@@ -0,0 +1,179 @@
+# Heading
+
+## Overview
+
+
+> Image: Illustration of a Heading component.
+
+
+
+## When to use this component
+- To establish clear visual rhythm and hierarchical distinction between sections of content
+
+## When to use another component
+- If interaction is needed between sections, components such as `Collapsible Panel` or `Tab Bar` provide a structured pattern for interacting with the content contained within.
+
+```mermaid
+graph TD
+    accDescr: Decision tree that guides on when to use the Heading component or something else
+    A(Does the content need a structured and interactive experience?) -- No --- B(Heading)
+    A -- Yes --- C(Collapsible Panel or Tab Bar)
+```
+
+### Check out
+- [Collapsible Panel][1]
+- [Tab Bar][2]
+- [Typography][3]
+
+## Usage
+
+### Use only one `<h1>` tag
+The `<h1>` tag represents the most important idea of a page. Each page should have only one `<h1>` tag to help both search engines and users quickly understand the page.
+> Image: Examples display two sections each with a heading and paragraph. In the first example with heart eyes emoji, the first section has an h1 tag while the second section has an h2 tag. In the second example with grimacing emoji both sections have the h1 tag.
+
+
+### Do not skip heading levels
+Headings must follow a linear order without skipping levels.
+
+> Image: Examples display three sections each with a heading and paragraph. In the first example with heart eyes emoji, the headings in the three sections follow the tag order of h1, h2, and h3. In the second example with grimacing emoji, there is no h2 tag, resulting in three sections having h1, h3, and h4 tag, respectively.
+
+
+### Customized visual style
+The `variant` prop can be used to customize the visual style while still following the semantic structure.
+
+> Image: Example display three sections each with a heading and paragraph. The headings follow the tag order of h1, h2, and h3, but are styled title 2, title 3, and title 4.
+
+
+### Follow the level hierarchy
+The heading hierarchy is meaningful. Ordering headings according to the levels makes a page easy to scan.
+> Image: Examples display three sections each with a heading and paragraph. In the first example with heart eyes emoji, the headings in the three sections follow the tag order of h1, h2, and h3. In the second example with grimacing emoji, the heading hierachy is not followed, with the three sections having h1, h3, and h2 tag, respectively.
+
+
+
+## Content guidelines
+- Follow writing best practices outlined in the [UI text style guidelines][4]
+
+[1]: ./CollapsiblePanel
+[2]: ./TabBar
+[3]: ./Typography
+[4]: https://docs.splunk.com/Documentation/StyleGuide/current/StyleGuide/UIGuidelines
+
+## Examples
+
+
+### content
+
+```typescript
+import React from 'react';
+
+import Heading from '@splunk/react-ui/Heading';
+import P from '@splunk/react-ui/Paragraph';
+import Prose from '@splunk/react-ui/Prose';
+
+const content = `Splunk Inc. is an American software company based in San Francisco, California, that
+produces software for searching, monitoring, and analyzing machine-generated data
+via a web-style interface.`;
+
+
+function Basic() {
+    return (
+        <Prose>
+            <Heading level={1}>Heading 1</Heading>
+            <P>{content}</P>
+            <Heading level={2}>Heading 2 </Heading>
+            <P>{content}</P>
+            <Heading level={3}>Heading 3</Heading>
+            <P>{content}</P>
+            <Heading level={4}>Heading 4</Heading>
+            <P>{content}</P>
+            <Heading level={5}>Heading 5</Heading>
+            <P>{content}</P>
+            <Heading level={6}>Heading 6</Heading>
+            <P>{content}</P>
+        </Prose>
+    );
+}
+
+export default Basic;
+```
+
+
+
+### Variant
+
+The level prop determines the <hX> HTML tag and has an associated default typography mixin style. To override this default styling, the variant prop can be used to specify a typography mixin style. For instance, it is possible for a variant to have title1 styling and be a <h2> tag as in the below example.
+
+```typescript
+import React from 'react';
+
+import Heading from '@splunk/react-ui/Heading';
+import P from '@splunk/react-ui/Paragraph';
+import Prose from '@splunk/react-ui/Prose';
+
+
+function Variant() {
+    return (
+        <Prose>
+            <Heading level={2} variant="title1">
+                Heading 1
+            </Heading>
+            <P>
+                Splunk Inc. is an American software company based in San Francisco, California, that
+                produces software for searching, monitoring, and analyzing machine-generated data
+                via a web-style interface.
+            </P>
+        </Prose>
+    );
+}
+
+export default Variant;
+```
+
+
+
+
+## API
+
+
+### Heading API
+
+#### Props
+
+| Name | Type | Required | Default | Description |
+|------|------|------|------|------|
+| children | React.ReactNode | yes |  |  |
+| elementRef | React.Ref<HTMLHeadingElement> | no |  | A React ref which is set to the DOM element when the component mounts and null when it unmounts. |
+| level | 1 \| 2 \| 3 \| 4 \| 5 \| 6 | yes |  | Corresponds to the respective `<hX>` HTML tags and `typography(titleX)` `@splunk/themes` typography variant. Styles will be set corresponding to level if variant is not provided: e.g. `level=3` will default to using `title3` from `mixins`. |
+| variant | TypographyTitleVariant | no |  | Styles the component based on typography mixin title preset styles. If a variant is not provided, styles will be set corresponding to level: e.g. `level=3` will default to using `title3` from `mixins`. |
+
+
+
+
+
+## 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]
+
+## Content
+- Headings within the Splunk product portfolio **SHOULD** follow:
+    - H1 = Splunk
+    - H2 = application name
+    - H3 = page title
+    - H4+ = page specific content
+- **MUST** use a linear order of headings. Do not jump from 1, 3, 5, subtitles. Instead, use 1, 2, 3, etc. Screen readers allow users to navigate by headings, so headings are an effective way to bypass blocks of content. [SC 2.4.1][3]
+
+## States
+-  Headers cannot be disabled
+
+## Implementation
+- **SHOULD** use h-tags to ensure they are not buried under divs, boxes, etc.. This makes headers easier to pick up with screen readers, making information esier to find. 
+
+[1]: https://www.w3.org/TR/WCAG21/#contrast-minimum
+[2]: https://www.w3.org/TR/WCAG21/#contrast-enhanced
+[3]: https://www.w3.org/TR/WCAG21/#bypass-blocks
+
+

package/docs-llm/Image.md

@@ -0,0 +1,109 @@
+# Image
+
+## Overview
+
+
+> Image: Illustration of an Image component.
+
+
+## When to use this component
+- To allow users to upload one or more images.
+- Use to present visual information that enhances understanding.
+- To offer immediate feedback on image file selection and validation.
+
+## When to use another component
+- If the user needs to upload a file that is not an image, use the File component instead.
+- If the user needs to provide information that is not an image, use the appropriate data entry components instead.
+
+### Check out
+- [File][1]
+
+## Usage
+
+### Supported file types
+When possible, display a clear support message showcasing what types of image file types are supported for upload. 
+
+> Image: In the first example with a heart eyes emoji, the image component includes a supporting message providing further context on what image file types are accepted. In the second example with a grimacing emoji, no supporting message is included in the image component.
+
+
+### Error messaging
+Provide specific and clear information about the cause of an error, guiding the user on how to resolve it.
+
+> Image: In the first example with a heart eyes emoji, the user is given context on the cause and resolution of the error. In the second example with a grimacing emoji, no further context is provided.
+
+
+## Content
+
+### Be concise
+Ensure all text and messaging, including labels and helper text, are brief and to the point. 
+
+> Image: In the first example with a heart eyes emoji, the text and messaging are brief and to the point. In the second example with a grimacing emoji the text and messaging are wordy.
+
+
+[1]: ./File
+
+## Examples
+
+
+### Basic
+
+```typescript
+/* eslint-disable no-console */
+
+import React from 'react';
+
+import Image, { ImageImageChangeHandler } from '@splunk/react-ui/Image';
+
+
+function Basic() {
+    const handleOnImageChange: ImageImageChangeHandler = ({ filename, imageDataURI }) => {
+        console.log(
+            `Image selected: ${filename}, ${
+                imageDataURI !== null ? `${imageDataURI.slice(0, 50)}...` : null
+            }`
+        );
+    };
+
+    return (
+        <div style={{ maxWidth: 300 }}>
+            <Image onImageChange={handleOnImageChange} />
+        </div>
+    );
+}
+
+export default Basic;
+```
+
+
+
+
+## API
+
+
+### Image API
+
+Image provides the ability to accept image files and present a preview of the image.
+
+#### Props
+
+| Name | Type | Required | Default | Description |
+|------|------|------|------|------|
+| allowExtensions | string[] | no | ['gif', 'jpeg', 'jpg', 'png'] | Specify the allowed image extensions. Should be an array of image extensions, e.g., ['gif', 'jpg', 'png']. |
+| defaultFilename | string | no |  | The default file name of the selected image. In order to render selected image preview, need to set valid defaultFilename (end with allowed image extensions, e.g., 'default.png') and defaultImageDataURI at the same time. |
+| defaultImageDataURI | string | no |  | The default selected image data (as data URI). Need to set with defaultFilename at the same time. |
+| disabled | boolean | no |  | Prevents user from selecting or dropping images. |
+| dropAnywhere | boolean | no |  | Image can be dropped anywhere on the page. |
+| 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 |  | Show the component in an error state. |
+| onImageChange | ImageImageChangeHandler | no |  | A callback for when the image changes. The function is passed an object containing two keys: `filename` and `imageDataURI`. Both are `null` if the image was removed. |
+
+#### Types
+
+| Name | Type | Description |
+|------|------|------|
+| ImageImageChangeHandler | (data: {     filename: string \| null;     imageDataURI: string \| null; }) => void |  |
+
+
+
+
+