@splunk/react-ui 5.7.1 → 5.8.0

package/docs-llm/Color.md

@@ -0,0 +1,253 @@
+# Color
+
+## Overview
+
+
+> Image: Illustration of a Color component.
+
+
+## When to use this component
+- You need to allow users to select a specific color, such as customizing the look and feel of a dashboard, data visualization or other customizeable element.
+
+## When to use another component
+- If you have a list of predefined options consider using a Radio list or Select.
+- If you only need to capture a hex value for data-entry purposes use Text.
+
+```mermaid
+graph TD
+    accDescr: Decision tree that guides on when to use the Color component or something else
+    A(Does the user need to select or input a custom color?) -- Yes --- B(Color picker)
+    A -- No --- C(Radio List, Text, or Select)
+```
+
+### Check out
+- [Radio List][1]
+- [Select][2]
+- [Text][3]
+
+## Usage
+
+### Number of options
+#### Limit choices
+Avoid overwhelming users with too many options, this can increase cognitive load.
+
+> Image: Example laying emphasis on number of color swatch options provided to the user. The first example with the heart eyes emoji displays The color component to have 20 color swatch options, whereas the second example with the grimacing emoji displays the Color component to have too many color swatch options available. This could increase cognitive load for the user (according to Miller
+
+
+#### Too few options
+Avoid limiting users with too few color options, this can make them feel restricted and unable to fully express their preferences or align with their brand identity.
+
+> Image: Example laying emphasis on number of color swatch options provided to the user. The first example with the heart eyes emoji displays the Color component to have 20 color swatch options, whereas the second example with the grimacing emoji displays the Color component to have too few color swatch options available. This could make users feel restricted.
+
+
+### Color preview
+Showcase a live color preview of the chosen color. This provides real-time visual feedback ensuring the user is confident in their selection.
+
+> Image: Example showcasing the significance of visually displaying the selected color to the user. The first example with the heart eyes emoji displays the Color component to showcase the selected color visually, whereas the second example with the grimacing emoji displays the Color component to only display the hex value of the selected color.
+
+
+### Text preview
+When possible, set the hideInput property to false to display the input field, ensuring inclusive design with text and color affordances.
+
+> Image: Example showcasing the significance of displaying the text input field to the user. The first example with the heart eyes emoji displays the Color component to showcase the selected color with both a color swatch and a text input, whereas the second example with the grimacing emoji displays the Color component to only display the color swatch of the selected color.
+
+
+[1]: ./RadioList
+[2]: ./Select
+[3]: ./Text
+
+## Examples
+
+
+### Uncontrolled
+
+```typescript
+import React from 'react';
+
+import Color from '@splunk/react-ui/Color';
+
+
+function Uncontrolled() {
+    return <Color defaultValue="#F29BAC" />;
+}
+
+export default Uncontrolled;
+```
+
+
+
+### Controlled
+
+```typescript
+import React, { useState } from 'react';
+
+import Color, { ColorChangeHandler } from '@splunk/react-ui/Color';
+
+
+function Controlled() {
+    const [colorValue, setColorValue] = useState<string | null | undefined>('#000000');
+
+    const handleChange: ColorChangeHandler = ({ value }) => {
+        setColorValue(value);
+    };
+
+    return <Color value={colorValue} onChange={handleChange} />;
+}
+
+export default Controlled;
+```
+
+
+
+### Theme Variables
+
+Variables from @splunk/themes can be used to set Color values, such as defaultValue.
+
+```typescript
+import React from 'react';
+
+import Color, { defaultPalette } from '@splunk/react-ui/Color';
+import useSplunkTheme from '@splunk/themes/useSplunkTheme';
+
+
+export default function ThemeVariables() {
+    const { syntaxTeal } = useSplunkTheme();
+
+    const palette = [...defaultPalette, syntaxTeal];
+
+    return (
+        <div style={{ width: 170 }}>
+            <Color defaultValue={syntaxTeal} palette={palette} />
+        </div>
+    );
+}
+```
+
+
+
+### Transparent
+
+Including transparent in the palette is supported. Put this option at the start or end of the palette.
+
+```typescript
+import React from 'react';
+
+import Color, { defaultPalette } from '@splunk/react-ui/Color';
+
+
+function Transparent() {
+    return <Color defaultValue="transparent" palette={['transparent', ...defaultPalette]} />;
+}
+
+export default Transparent;
+```
+
+
+
+### N/A
+
+Including N/A in the palette is supported. Put this option at the start or end of the palette. Selecting N/A will return null.
+
+```typescript
+import React, { useState } from 'react';
+
+import Color, { ColorChangeHandler } from '@splunk/react-ui/Color';
+
+
+function Null() {
+    const [colorValue, setColorValue] = useState<string | null | undefined>(null);
+
+    const handleChange: ColorChangeHandler = ({ value }) => {
+        setColorValue(value);
+    };
+
+    return <Color value={colorValue} onChange={handleChange} />;
+}
+
+export default Null;
+```
+
+
+
+### Customized Palette
+
+Color has defaultPalette exported which can be modified.
+
+```typescript
+import React from 'react';
+
+import Color, { defaultPalette } from '@splunk/react-ui/Color';
+
+
+export default function CustomizedPalette() {
+    const customSwatches = [
+        '#53a051',
+        '#62b3b2',
+        '#4fa484',
+        '#f8be44',
+        '#5a4575',
+        '#708794',
+        '#294e70',
+        '#b6c75a',
+    ];
+    const myPalette = [...customSwatches, ...defaultPalette];
+
+    return <Color defaultValue="#4fa484" palette={myPalette} />;
+}
+```
+
+
+
+### Hide Input
+
+Color without hex value text input. The input will still appear inside the dropdown when opened.
+
+```typescript
+import React from 'react';
+
+import Color from '@splunk/react-ui/Color';
+
+
+function HideInput() {
+    return <Color hideInput defaultValue="#912344" />;
+}
+
+export default HideInput;
+```
+
+
+
+
+## API
+
+
+### Color API
+
+#### Props
+
+| Name | Type | Required | Default | Description |
+|------|------|------|------|------|
+| append | boolean | no |  | Append removes border from the right side. |
+| defaultValue | string \| null | no |  | Set this property instead of value to make 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 |  | Add a disabled attribute and prevent clicking. |
+| 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 |  | Add an error attribute. |
+| hideInput | boolean | no |  | Set this property to hide the hex value text input in the initial appearance. The input will still appear inside the dropdown when opened. |
+| 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 |  | The name is returned with onChange events, which can be used to identify the control when multiple controls share an onChange callback. |
+| onChange | ColorChangeHandler | no |  | A callback that receives the value of a newly selected color. |
+| palette | (string \| null)[] | no | defaultPalette | An array of optional color swatch values (hexadecimal or 'transparent'). The 'transparent' option should only be put at the start or end of the palette. |
+| prepend | boolean | no |  | This has no effect on the appearance at this time but is recommended to be used when a control is joined to the left. Styles may change in the future. |
+| value | string \| null | no |  | The value of the color (hexadecimal or 'transparent'). Setting this value makes the property controlled. An `onChange` callback is required. |
+
+#### Types
+
+| Name | Type | Description |
+|------|------|------|
+| ColorChangeHandler | (data: { name?: string; value?: string \| null }) => void |  |
+
+
+
+
+

package/docs-llm/Column Layout.md

@@ -0,0 +1,391 @@
+# Column Layout
+
+## Examples
+
+
+### Columns and Spans
+
+The span property can be set to vary the width of the Columns. The spans must add up to 12. The Columns are colored for this example.
+
+```typescript
+import React from 'react';
+
+import ColumnLayout from '@splunk/react-ui/ColumnLayout';
+import { useSplunkTheme } from '@splunk/themes';
+
+
+function Basic() {
+    const { syntaxBlue } = useSplunkTheme();
+    const colStyle: React.CSSProperties = {
+        border: `1px solid ${syntaxBlue}`,
+        padding: 10,
+        minHeight: 80,
+    };
+
+    return (
+        <ColumnLayout>
+            <ColumnLayout.Row>
+                <ColumnLayout.Column style={colStyle}>1</ColumnLayout.Column>
+                <ColumnLayout.Column style={colStyle}>2</ColumnLayout.Column>
+                <ColumnLayout.Column style={colStyle}>3</ColumnLayout.Column>
+                <ColumnLayout.Column style={colStyle}>4</ColumnLayout.Column>
+                <ColumnLayout.Column style={colStyle}>5</ColumnLayout.Column>
+                <ColumnLayout.Column style={colStyle}>6</ColumnLayout.Column>
+                <ColumnLayout.Column style={colStyle}>7</ColumnLayout.Column>
+                <ColumnLayout.Column style={colStyle}>8</ColumnLayout.Column>
+                <ColumnLayout.Column style={colStyle}>9</ColumnLayout.Column>
+                <ColumnLayout.Column style={colStyle}>10</ColumnLayout.Column>
+                <ColumnLayout.Column style={colStyle}>11</ColumnLayout.Column>
+                <ColumnLayout.Column style={colStyle}>12</ColumnLayout.Column>
+            </ColumnLayout.Row>
+            <ColumnLayout.Row>
+                <ColumnLayout.Column style={colStyle} span={4}>
+                    Span 4
+                </ColumnLayout.Column>
+                <ColumnLayout.Column style={colStyle} span={8}>
+                    Span 8
+                </ColumnLayout.Column>
+            </ColumnLayout.Row>
+            <ColumnLayout.Row>
+                <ColumnLayout.Column style={colStyle} span={2}>
+                    Span 2
+                </ColumnLayout.Column>
+                <ColumnLayout.Column style={colStyle} span={5}>
+                    Span 5
+                </ColumnLayout.Column>
+                <ColumnLayout.Column style={colStyle} span={5}>
+                    Span 5
+                </ColumnLayout.Column>
+            </ColumnLayout.Row>
+            <ColumnLayout.Row>
+                <ColumnLayout.Column style={colStyle} span={6}>
+                    Span 6
+                </ColumnLayout.Column>
+                <ColumnLayout.Column style={colStyle} span={3}>
+                    Span 3
+                </ColumnLayout.Column>
+                <ColumnLayout.Column style={colStyle} span={3}>
+                    Span 3
+                </ColumnLayout.Column>
+            </ColumnLayout.Row>
+        </ColumnLayout>
+    );
+}
+
+export default Basic;
+```
+
+
+
+### Gutters
+
+Column Layout spaces Rows and Columns with gutters, but these can be removed or changed.
+
+```typescript
+import React from 'react';
+
+import ColumnLayout from '@splunk/react-ui/ColumnLayout';
+import Heading from '@splunk/react-ui/Heading';
+import { useSplunkTheme } from '@splunk/themes';
+
+
+function Gutters() {
+    const { syntaxBlue } = useSplunkTheme();
+    const colStyle: React.CSSProperties = {
+        border: `1px solid ${syntaxBlue}`,
+        padding: 10,
+        minHeight: 80,
+    };
+    const headingStyle: React.CSSProperties = {
+        margin: '1.414em 0 0.4em',
+    };
+
+    return (
+        <div>
+            <Heading level={4} style={headingStyle}>
+                8px gutter
+            </Heading>
+            <ColumnLayout gutter={8}>
+                <ColumnLayout.Row>
+                    <ColumnLayout.Column span={6} style={colStyle}>
+                        1 of 2
+                    </ColumnLayout.Column>
+                    <ColumnLayout.Column span={6} style={colStyle}>
+                        2 of 2
+                    </ColumnLayout.Column>
+                </ColumnLayout.Row>
+                <ColumnLayout.Row>
+                    <ColumnLayout.Column span={4} style={colStyle}>
+                        1 of 3
+                    </ColumnLayout.Column>
+                    <ColumnLayout.Column span={4} style={colStyle}>
+                        2 of 3
+                    </ColumnLayout.Column>
+                    <ColumnLayout.Column span={4} style={colStyle}>
+                        2 of 3
+                    </ColumnLayout.Column>
+                </ColumnLayout.Row>
+            </ColumnLayout>
+            <Heading level={4} style={headingStyle}>
+                0px gutter
+            </Heading>
+            <ColumnLayout gutter={0}>
+                <ColumnLayout.Row>
+                    <ColumnLayout.Column span={6} style={colStyle}>
+                        1 of 2
+                    </ColumnLayout.Column>
+                    <ColumnLayout.Column span={6} style={colStyle}>
+                        2 of 2
+                    </ColumnLayout.Column>
+                </ColumnLayout.Row>
+                <ColumnLayout.Row>
+                    <ColumnLayout.Column span={4} style={colStyle}>
+                        1 of 3
+                    </ColumnLayout.Column>
+                    <ColumnLayout.Column span={4} style={colStyle}>
+                        2 of 3
+                    </ColumnLayout.Column>
+                    <ColumnLayout.Column span={4} style={colStyle}>
+                        2 of 3
+                    </ColumnLayout.Column>
+                </ColumnLayout.Row>
+            </ColumnLayout>
+        </div>
+    );
+}
+
+export default Gutters;
+```
+
+
+
+### Dividers
+
+Column Layout can show different types of dividers.
+
+```typescript
+import React from 'react';
+
+import ColumnLayout from '@splunk/react-ui/ColumnLayout';
+import Heading from '@splunk/react-ui/Heading';
+import { useSplunkTheme } from '@splunk/themes';
+
+
+function Dividers() {
+    const { syntaxBlue } = useSplunkTheme();
+    const colStyle: React.CSSProperties = {
+        border: `1px solid ${syntaxBlue}`,
+        padding: 10,
+        minHeight: 80,
+    };
+    const headingStyle: React.CSSProperties = {
+        margin: '1.414em 0 0.4em',
+    };
+
+    return (
+        <div>
+            <Heading level={4} style={headingStyle}>
+                Vertical dividers
+            </Heading>
+            <ColumnLayout divider="vertical">
+                <ColumnLayout.Row>
+                    <ColumnLayout.Column span={6} style={colStyle}>
+                        1 of 2
+                    </ColumnLayout.Column>
+                    <ColumnLayout.Column span={6} style={colStyle}>
+                        2 of 2
+                    </ColumnLayout.Column>
+                </ColumnLayout.Row>
+                <ColumnLayout.Row>
+                    <ColumnLayout.Column span={4} style={colStyle}>
+                        1 of 3
+                    </ColumnLayout.Column>
+                    <ColumnLayout.Column span={4} style={colStyle}>
+                        2 of 3
+                    </ColumnLayout.Column>
+                    <ColumnLayout.Column span={4} style={colStyle}>
+                        2 of 3
+                    </ColumnLayout.Column>
+                </ColumnLayout.Row>
+            </ColumnLayout>
+            <Heading level={4} style={headingStyle}>
+                Horizontal dividers
+            </Heading>
+            <ColumnLayout divider="horizontal">
+                <ColumnLayout.Row>
+                    <ColumnLayout.Column span={6} style={colStyle}>
+                        1 of 2
+                    </ColumnLayout.Column>
+                    <ColumnLayout.Column span={6} style={colStyle}>
+                        2 of 2
+                    </ColumnLayout.Column>
+                </ColumnLayout.Row>
+                <ColumnLayout.Row>
+                    <ColumnLayout.Column span={4} style={colStyle}>
+                        1 of 3
+                    </ColumnLayout.Column>
+                    <ColumnLayout.Column span={4} style={colStyle}>
+                        2 of 3
+                    </ColumnLayout.Column>
+                    <ColumnLayout.Column span={4} style={colStyle}>
+                        2 of 3
+                    </ColumnLayout.Column>
+                </ColumnLayout.Row>
+            </ColumnLayout>
+        </div>
+    );
+}
+
+export default Dividers;
+```
+
+
+
+### Align Items
+
+By default, the Columns grow vertically to fill the available space. The values for this property are the same as flexbox's align-items property.
+
+```typescript
+import React from 'react';
+
+import ColumnLayout from '@splunk/react-ui/ColumnLayout';
+import { useSplunkTheme } from '@splunk/themes';
+
+
+function AlignItems() {
+    const { syntaxBlue } = useSplunkTheme();
+    const colStyle: React.CSSProperties = { border: `1px solid ${syntaxBlue}`, padding: 10 };
+
+    return (
+        <ColumnLayout>
+            <ColumnLayout.Row alignItems="stretch">
+                <ColumnLayout.Column span={4} style={colStyle}>
+                    A short column can stretch to fill the space.
+                </ColumnLayout.Column>
+                <ColumnLayout.Column span={4} style={colStyle}>
+                    A tall
+                    <br />
+                    column defines
+                    <br />
+                    the height
+                    <br />
+                    of the row.
+                </ColumnLayout.Column>
+                <ColumnLayout.Column span={4} style={colStyle}>
+                    Another
+                    <br />
+                    column.
+                </ColumnLayout.Column>
+            </ColumnLayout.Row>
+            <ColumnLayout.Row alignItems="start">
+                <ColumnLayout.Column span={4} style={colStyle}>
+                    A short column can align to the start (top) of the row.
+                </ColumnLayout.Column>
+                <ColumnLayout.Column span={4} style={colStyle}>
+                    A tall
+                    <br />
+                    column defines
+                    <br />
+                    the height
+                    <br />
+                    of the row.
+                </ColumnLayout.Column>
+                <ColumnLayout.Column span={4} style={colStyle}>
+                    Another
+                    <br />
+                    column.
+                </ColumnLayout.Column>
+            </ColumnLayout.Row>
+            <ColumnLayout.Row alignItems="end">
+                <ColumnLayout.Column span={4} style={colStyle}>
+                    A short column can align to the end (bottom) of the row.
+                </ColumnLayout.Column>
+                <ColumnLayout.Column span={4} style={colStyle}>
+                    A tall
+                    <br />
+                    column defines
+                    <br />
+                    the height
+                    <br />
+                    of the row.
+                </ColumnLayout.Column>
+                <ColumnLayout.Column span={4} style={colStyle}>
+                    Another
+                    <br />
+                    column.
+                </ColumnLayout.Column>
+            </ColumnLayout.Row>
+            <ColumnLayout.Row alignItems="center">
+                <ColumnLayout.Column span={4} style={colStyle}>
+                    A short column can align to the center (middle) of the row.
+                </ColumnLayout.Column>
+                <ColumnLayout.Column span={4} style={colStyle}>
+                    A tall
+                    <br />
+                    column defines
+                    <br />
+                    the height
+                    <br />
+                    of the row.
+                </ColumnLayout.Column>
+                <ColumnLayout.Column span={4} style={colStyle}>
+                    Another
+                    <br />
+                    column.
+                </ColumnLayout.Column>
+            </ColumnLayout.Row>
+        </ColumnLayout>
+    );
+}
+
+export default AlignItems;
+```
+
+
+
+
+## API
+
+
+### ColumnLayout API
+
+`ColumnLayout` provides simple API for laying out content into columns. It is based on flexbox
+and has 12 columns.
+
+#### Props
+
+| Name | Type | Required | Default | Description |
+|------|------|------|------|------|
+| children | React.ReactNode | no |  | `children` must be `ColumnLayout.Row` elements. |
+| divider | 'none' \| 'vertical' \| 'horizontal' | no | 'none' | Show dividers between columns. |
+| elementRef | React.Ref<HTMLDivElement> | no |  | A React ref which is set to the DOM element when the component mounts and null when it unmounts. |
+| gutter | number | no |  | Set gutter width in pixels. This is propagated down to its `children`. |
+
+
+
+### ColumnLayout.Row API
+
+#### Props
+
+| Name | Type | Required | Default | Description |
+|------|------|------|------|------|
+| alignItems | 'start' \| 'end' \| 'center' \| 'stretch' | no | 'stretch' | Set vertical alignment of columns in a row |
+| children | React.ReactNode | no |  | `children` must be `ColumnLayout.Column` elements |
+| elementRef | React.Ref<HTMLDivElement> | no |  | A React ref which is set to the DOM element when the component mounts and null when it unmounts. |
+
+
+
+### ColumnLayout.Column 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. |
+| span | number | no | 1 | The number of columns the element spans. |
+
+
+
+
+