@splunk/react-ui 5.7.1 → 5.9.0

package/docs-llm/JSON Tree.md

@@ -0,0 +1,260 @@
+# JSON Tree
+
+## Overview
+
+
+> Image: Illustration of the JSON Tree component displaying structured data in a collapsible tree format.
+
+
+## When to use this component
+- To display structured data in a collapsible tree format. 
+
+## When to use another component
+- For displaying pieces of code, command-line instructions, or technical values that need to be visually distinguished from surrounding content, consider using `Code`.
+
+### Check out:
+- [Code][1]
+
+## Behaviors
+
+### Data types
+- Values are visually distinguished by their data type (e.g., string, number, boolean, null, object, array).
+
+> Image: A display of a JSON object showing various data types like numbers, strings, booleans, null, and nested objects/arrays, with different colors indicating types.
+
+
+### Expanding content
+- Users can expand and collapse individual nodes (objects or arrays) to reveal or hide their contents. You can set the `defaultExpanded` prop to have it expanded by default.
+
+> Image: A display illustrating the expandable and collapsible nature of a JSON tree, showing a collapsed object on the left and its expanded view revealing nested structures on the right.
+
+
+### Expand all
+- `Shift + Click` or `Shift + Enter` to expand all child nodes at once.
+
+## Usage
+- The JSON Tree component accepts a JSON object or array as its primary data input.
+
+## Content
+- Use proper syntax and indentation to ensure readability and clarity.
+
+[1]: ./Code
+
+## Examples
+
+
+### obj
+
+```typescript
+import React from 'react';
+
+import JSONTree from '@splunk/react-ui/JSONTree';
+
+const obj = {
+    menu: {
+        id: 8989,
+        value: 'File',
+        property: {},
+        items: [],
+        popup: {
+            menuitem: [
+                {
+                    value: 'New',
+                    onclick: 'CreateNewDoc()',
+                },
+                {
+                    value: null,
+                    onclick: false,
+                },
+                {
+                    value: 'Close',
+                    onclick: 'CloseDoc()',
+                },
+            ],
+        },
+    },
+};
+
+
+export default function Basic() {
+    return <JSONTree json={obj} defaultExpanded />;
+}
+```
+
+
+
+### Expand Children On Shift Key
+
+```typescript
+import React from 'react';
+
+import JSONTree from '@splunk/react-ui/JSONTree';
+
+const obj = {
+    menu: {
+        id: 8989,
+        value: 'File',
+        property: {},
+        items: [],
+        popup: {
+            menuitem: [
+                {
+                    value: 'New',
+                    onclick: 'CreateNewDoc()',
+                },
+                {
+                    value: null,
+                    onclick: false,
+                },
+                {
+                    value: 'Close',
+                    onclick: 'CloseDoc()',
+                },
+            ],
+        },
+    },
+};
+
+
+export default function ExpandChildrenOnShiftKey() {
+    return <JSONTree json={obj} expandChildrenOnShiftKey />;
+}
+```
+
+
+
+### Click Events
+
+```typescript
+import React, { Component } from 'react';
+
+import DL, { Term as DT, Description as DD } from '@splunk/react-ui/DefinitionList';
+import JSONTree, {
+    JSONTreeClickValueHandler,
+    JSONTreeClickKeyHandler,
+} from '@splunk/react-ui/JSONTree';
+import P from '@splunk/react-ui/Paragraph';
+
+const json = {
+    glossary: {
+        title: 'example glossary',
+        description: [],
+        GlossDiv: {
+            title: 'S',
+            GlossList: {
+                GlossEntry: {
+                    ID: 'SGML',
+                    SortAs: 'SGML',
+                    GlossTerm: 'Standard Generalized Markup Language',
+                    Acronym: 'SGML',
+                    Abbrev: 'ISO 8879:1986',
+                    GlossDef: {
+                        para: 'Used to create markup languages such as DocBook.',
+                        GlossSeeAlso: ['GML', null, 1, true],
+                    },
+                    GlossSee: {},
+                },
+            },
+        },
+    },
+};
+
+
+class Events extends Component<
+    object,
+    { key: string; keyPath?: (string | number)[]; value: string }
+> {
+    constructor(props: object) {
+        super(props);
+        this.state = {
+            key: '',
+            value: '',
+        };
+    }
+
+    onClickJSONValue: JSONTreeClickValueHandler = (e, { key, keyPath, value }) => {
+        this.setState({ key, keyPath, value });
+    };
+
+    onClickJSONKey: JSONTreeClickKeyHandler = (e, { key, keyPath }) => {
+        this.setState({ key, keyPath, value: '' });
+    };
+
+    render() {
+        const { key, keyPath, value } = this.state;
+
+        return (
+            <div>
+                <JSONTree
+                    json={json}
+                    onClickValue={this.onClickJSONValue}
+                    onClickKey={this.onClickJSONKey}
+                />
+                <aside style={{ marginTop: 20 }} aria-live="polite" aria-relevant="text">
+                    <P>Click a key or value to see the returned data</P>
+                    <DL>
+                        {value ? (
+                            <div style={{ overflow: 'scroll' }}>
+                                <DT>Clicked value:</DT>
+                                <DD>
+                                    <code>{value}</code>
+                                </DD>
+                            </div>
+                        ) : null}
+                        {key ? (
+                            <div style={{ overflow: 'scroll', marginBottom: 10 }}>
+                                <DT>With key:</DT>
+                                <DD>
+                                    <code>{key}</code>
+                                </DD>
+                                <DT>With keyPath:</DT>
+                                <DD>
+                                    <code>{keyPath !== undefined && `[${keyPath}]`}</code>
+                                </DD>
+                            </div>
+                        ) : null}
+                    </DL>
+                </aside>
+            </div>
+        );
+    }
+}
+
+export default Events;
+```
+
+
+
+
+## API
+
+
+### JSONTree API
+
+Used to visualize a JSON string.
+
+#### Props
+
+| Name | Type | Required | Default | Description |
+|------|------|------|------|------|
+| defaultExpanded | boolean | no | false | If set to `true`, `defaultExpanded` will expand all nodes on initial render. The default is `false`, which expands only the first level of properties. |
+| elementRef | React.Ref<HTMLElement> | no |  | A React ref which is set to the DOM element when the component mounts and null when it unmounts. |
+| expandChildrenOnShiftKey | boolean | no | true | If set to `true`, using `shift + click` or `shift + enter` will expand all descendant nodes of the tree at once. A tooltip is added to the expand all / collapse all button to indicate that this feature is enabled. Defaults to `true`. |
+| indent | number | no | 4 | Number of space characters per level of indentation. |
+| json | string \| JSONElement | yes |  | The JSON string to visualize. Alternatively, this prop also accepts objects and other possible return types of `JSON.parse`. `JSONTree` doesn't perform any runtime type validation. If the passed value contains circular dependencies or types not representable in JSON like functions and symbols, the component behavior is unspecified. |
+| onClickKey | JSONTreeClickKeyHandler | no |  | Optional event handler to call if keys are clicked on. The function signature is `onClickKey({path, keyPath, value})`, where `path` is the property path , `.a.b`; and keyPath is an array of that property path, `['a', 'b']. |
+| onClickValue | JSONTreeClickValueHandler | no |  | Optional event handler to call if values are clicked on. The function signature is `onClickValue({path, keyPath, value})`, where `path` is the property path , `.a.b`; keyPath is an array of that property path, `['a', 'b']; and `value` is the value that was clicked. |
+| overflow | 'wrap' \| 'scroll' | no | 'scroll' | Handles overflow by wrapping values or by enabling scrolling. |
+
+#### Types
+
+| Name | Type | Description |
+|------|------|------|
+| JSONElement | string \| { [x: string]: JSONElement } \| number \| boolean \| null \| JSONElement[] |  |
+| JSONTreeClickKeyHandler | (     event: React.MouseEvent<HTMLButtonElement>,     data: {         key: string;         keyPath: (string \| number)[];     } ) => void |  |
+| JSONTreeClickValueHandler | (     event: React.MouseEvent<HTMLButtonElement>,     data: {         key: string;         keyPath: (string \| number)[];         value: string;     } ) => void |  |
+
+
+
+
+

package/docs-llm/Layer.md

@@ -0,0 +1,74 @@
+# Layer
+
+## Examples
+
+
+### Basic
+
+This example shows a simple overlay that can be dismissed by pressing the Escape key.
+
+```typescript
+import React, { useState } from 'react';
+
+import Button from '@splunk/react-ui/Button';
+import Layer from '@splunk/react-ui/Layer';
+
+
+function Basic() {
+    const [open, setOpen] = useState(false);
+    const handleOpen = () => setOpen(true);
+    const handleClose = () => setOpen(false);
+
+    return (
+        <>
+            <Button onClick={handleOpen} label="Open" />
+            <Layer closeReasons={['escapeKey']} open={open} onRequestClose={handleClose}>
+                <div
+                    style={{
+                        position: 'absolute',
+                        bottom: '5%',
+                        right: '5%',
+                        width: '300px',
+                        height: '100px',
+                        backgroundColor: 'crimson',
+                        borderRadius: '3px',
+                    }}
+                />
+            </Layer>
+        </>
+    );
+}
+
+export default Basic;
+```
+
+
+
+
+## API
+
+import React from 'react';
+
+import ComponentAPI from '@splunk/react-docs/ComponentAPI';
+import UtilAPI from '@splunk/react-docs/UtilAPI';
+
+import layerStackUtilDocs from '!!@splunk/jsdoc-loader!@splunk/react-ui/Layer/LayerStack';
+import allLayerDocs from '@splunk/react-ui/Layer/Layer?parseDocs';
+import allLayerStackDocs from '@splunk/react-ui/Layer/LayerStack?parseDocs';
+
+const layerDocs = allLayerDocs.find((doc) => doc.displayName === 'Layer');
+const layerStackDocs = allLayerStackDocs.find(
+    (doc) => doc.displayName === 'LayerStackGlobalProvider'
+);
+
+function DevelopSection() {
+    return [
+        <ComponentAPI docs={layerDocs} title="Layer" key="layer" />,
+        <ComponentAPI docs={layerStackDocs} title="LayerStackGlobalProvider" key="layerstack" />,
+        <UtilAPI key="layerstackutils" docs={layerStackUtilDocs} />,
+    ];
+}
+
+export default DevelopSection;
+
+

package/docs-llm/Layout.md

@@ -0,0 +1,50 @@
+# Layout
+
+## Examples
+
+
+### Basic
+
+```typescript
+import React from 'react';
+
+import Button from '@splunk/react-ui/Button';
+import Layout from '@splunk/react-ui/Layout';
+import Search from '@splunk/react-ui/Search';
+import Switch from '@splunk/react-ui/Switch';
+
+
+function Basic() {
+    return (
+        <Layout>
+            <Button label="Button" />
+            <Search inline />
+            <Switch />
+        </Layout>
+    );
+}
+
+export default Basic;
+```
+
+
+
+
+## API
+
+
+### Layout API
+
+Renders a container to layout children using standard spacing values.
+
+#### 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. |
+
+
+
+
+

package/docs-llm/Link.md

@@ -0,0 +1,318 @@
+# Link
+
+## Overview
+
+
+> Image: Illustration of a paragraph of text with a link component at the end
+
+
+## When to use this component
+- When you want to navigate users to a different page within your application
+- When you want to direct users to a location on the same page
+- When you want to navigate users to an external site
+
+## When to use another component
+- If the text is not relevant or important enough to warrant additional information, do not use a link.
+- If the content will change the data on the current page or need action from the user, use a `Button`.
+- For revealing large amounts of information, use an `Accordion` or `Collapsible panel`.
+
+```mermaid
+graph TD
+    accDescr: Decision tree that guides on when to use the Link component or something else
+    A(Is the text important enough to warrant additional information?) -- Yes --- B(Will the content change data on the current page, or need action from the user?)
+    B -- Yes --- C(Button)
+    B -- No --- D(Link)
+    A -- No --- E(Do not use a link)
+```
+
+### Check out
+- [Button][1]
+- [Accordion][2]
+- [Collapsible panel][3]
+
+## Usage
+
+### Standalone links
+Are used on their own and should not be used within or paired with other text content. Standalone links that open in a new window are exempt from this requirement as they use an icon by default.
+
+> Image: Example of correct and incorrect styles for standalone links. On the left is the correct example with a heart-eye emoji of a blue standalone link with no additional decorations or text. On the right is the incorrect example with a grimacing emoji with a standalone link with addition text next to it.
+
+
+### Limit the number of links
+Make sure each link is necessary. Using too many links can create a “sea of blue”.
+
+> Image: Example with heart eyes showing a small amount of links in a body of text next to a grimacing face example with too many link in a body of text.
+
+
+### Group links when possible
+For multiple links on the same page, grouping the links as a bulleted list or under a suitable title like “Resources”, will help users navigate.
+
+> Image: Illustration with two examples. First example with heart eyes has a group of links, the second example with a grimace has links scattered.
+
+
+### Be concise
+Keep the link text brief while still providing enough context to convey where the link takes the user.
+
+> Image: Illustration with two examples. The first example with heart eyes with brief link text that has enough context to convey where the link goes. The second example with grimace face has link text that is too long and not clear.
+
+
+## Content guidelines
+A user should never be surprised about where a link takes them. Use descriptive labels for links so users know where they’re going and what they’ll find if they select the link.
+
+- Keep the link text brief while still providing enough context to convey where the link takes the user.
+- Don’t use phrases like “click here” or “here” as link text. 
+- Links should be understandable out of context. This way, they are more informative of the destination and convenient targets for pressing.
+- Link judiciously. Too many links are a distraction.
+
+### Links that guide you to documentation
+The standard for writing the link text for links to Splunk documentation is to create a synopsis of the doc page title and add the word "documentation" at the end using this format: [doc page title synopsis] documentation
+
+For example, for a doc page with the title “Configure single sign-on with SAML” you could create a link called “SAML SSO documentation”. 
+- For more detailed guidance and examples, see the [UI text style guidelines][4] in the Splunk Style Guide.
+
+> Image: Two examples. The first with heart eyes has a modal with a link in the body with the correct formatting: Automatic UI updates documentation. The second example with a grimace has a modal with a link in the body with incorrect formatting: learn more.
+
+
+### Links in a sentence
+- When multiple links are present in a single sentence, consider grouping them for better scannability and usability. This will also make it easier for screen reader users to digest additional aria-labels associated with links.
+- Don’t link the entire sentence, only the text that describes the action or where the user goes when they select the link. If it’s a very short sentence that only describes the action, it’s okay to link the entire sentence.
+- Avoid links breaking onto a new line.
+- Don’t add links to Splunk product documentation in a sentence. Review "Links that guide you to documentation” section for more details.
+
+> Image: Guidelines is a two-column chart contrasting 
+
+
+### Standalone links
+A standalone link is a link that is not part of a sentence.
+- Use a standalone link with the external link icon for links that navigate outside of the application.
+- Don't use punctuation.
+- Don’t add links to Splunk product documentation in a sentence. Review “Links that guide you to documentation” section for more details.
+
+> Image: Guidelines for creating standalone links, which are links not part of a sentence and a chart divided into two sections labeled 
+
+
+[1]: ./Button
+[2]: ./Accordion
+[3]: ./CollapsiblePanel
+[4]: https://docs.splunk.com/Documentation/StyleGuide/current/StyleGuide/UIGuidelines#Links_to_Splunk_product_documentation
+
+## Examples
+
+
+### Basic
+
+Use the Link component instead of an <a> tag, by default it is displayed inline.
+
+```typescript
+import React from 'react';
+
+import Link from '@splunk/react-ui/Link';
+
+
+function Basic() {
+    return (
+        <>
+            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.{' '}
+            <Link to="https://www.splunk.com/en_us/products/platform.html">
+                The Splunk Platform
+            </Link>{' '}
+            allows you turn data into doing to unlock innovation, enhance security and drive
+            resilience.
+        </>
+    );
+}
+
+export default Basic;
+```
+
+
+
+### Standalone
+
+Use appearance="standalone" when using Link on its own without other text content.
+
+```typescript
+import React from 'react';
+
+import Link from '@splunk/react-ui/Link';
+
+
+function Standalone() {
+    return (
+        <Link appearance="standalone" to="https://www.splunk.com/en_us/products/observability.html">
+            Splunk Observability
+        </Link>
+    );
+}
+
+export default Standalone;
+```
+
+
+
+### New Window
+
+openInNewContext=true adds an icon and sets target to _blank. A message indicates the behavior for screen reader users. The default message, '(Opens new window)', can be customized by by passing a string to openInNewContext.
+
+```typescript
+import React from 'react';
+
+import Link from '@splunk/react-ui/Link';
+
+
+function NewWindow() {
+    return (
+        <Link
+            appearance="standalone"
+            to="https://www.splunk.com/en_us/products/observability.html"
+            openInNewContext
+        >
+            Splunk Observability
+        </Link>
+    );
+}
+
+export default NewWindow;
+```
+
+
+
+### Disabled
+
+Links can be disabled. The href is then removed from the markup.
+
+```typescript
+import React from 'react';
+
+import Link from '@splunk/react-ui/Link';
+
+
+function Disabled() {
+    return (
+        <Link
+            appearance="standalone"
+            to="https://www.splunk.com/en_us/products/observability.html"
+            disabled
+        >
+            Splunk Observability
+        </Link>
+    );
+}
+
+export default Disabled;
+```
+
+
+
+### Visited
+
+Enable visited link styling using the LinkProvider.
+
+```typescript
+import React from 'react';
+
+import Link, { LinkProvider } from '@splunk/react-ui/Link';
+
+
+const Visited = () => (
+    <LinkProvider enableVisitedStyling>
+        <p>After visiting the link below, its color will change.</p>
+        <Link to="https://www.splunk.com" openInNewContext>
+            Splunk.com
+        </Link>
+    </LinkProvider>
+);
+
+export default Visited;
+```
+
+
+
+
+## API
+
+
+### Link API
+
+`Link` is a simple method for configuring `Button` for inline links. For more complex behaviors,
+see the `Button` documentation.
+
+#### Props
+
+| Name | Type | Required | Default | Description |
+|------|------|------|------|------|
+| appearance | 'inline' \| 'standalone' | no | 'inline' | Changes the style of the link. |
+| children | React.ReactNode | no |  |  |
+| disabled | boolean | no | false | Adds an aria-disabled attribute and prevents clicking. |
+| elementRef | React.Ref<HTMLButtonElement \| HTMLAnchorElement> | no |  | A React ref which is set to the DOM element when the component mounts and null when it unmounts. |
+| onClick | React.MouseEventHandler<HTMLButtonElement \| HTMLAnchorElement> | no |  | The onClick event handler is ignored if Ctrl or meta keys are pressed, which allows the link to open in a new context. |
+| openInNewContext | boolean \| string | no | false | Open the "to" link in a new context, which is usually a new tab or window based on browser settings.  An icon and a screen reader message is added to indicate this behavior to users. The default message is "(Opens new window)"; this can be customized by passing a string instead of boolean to `openInNewContext`. |
+| to | string | no |  | The URL or path to link to. |
+
+
+
+
+
+## Accessibility
+
+A link enables a user to navigate through an app. If you are providing an action, use a [button][1].
+
+## Visual Design
+
+- **MUST** have a visual distinction beyond color, such as underline, bold, or an icon [SC 1.4.1][2]
+
+- Color contrast ratio **MUST** be, in active, hover, and selected states:
+    - &gt=4.5:1 between text and background of [SC 1.4.3][3]
+    - &gt=3:1 between button outline color to background OR icon color to background [SC 1.4.11][4]
+    - Focus State: if the focus ring has a radius of [SC 1.4.11][4]
+        - &lt 3px: &gt=4.5.1 between button &lt&gt focus &lt&gt background
+        - &gt 3px: &gt=3.1 between button &lt&gt focus &lt&gt background
+-   Visited links **SHOULD** have a different color applied that satisfies
+    color contrast guidelines
+
+- **MUST** have a visual element present for a link that opens a [SC 3.2][5]
+    - new tab or window non-HTML document (doc, excel spreedsheet, ppt, plain text, etc.)
+    - non-HTML document doc, excel spreedsheet, ppt, plain text, etc.
+    - new application
+
+## States
+
+- In-line links **SHOULD** use underline, not a focus state. This is to preserve zoom/magnification and prevent a split focus ring.
+
+- **MUST** avoid vague or generic language such as "click here" or "read more", or acronyms that are not widely know to users [SC 2.4.4][6]
+- **SHOULD** avoid linking entire sentences.
+
+## Interaction Design
+
+- **MUST** have keyboard navigation [SC 2.1][7]
+    - <kbd>Enter/Space</kbd> to execute the action for link
+    - <kbd>Tab</kbd> to move focus to next interactive element
+    - <kbd>Shift</kbd>+<kbd>Tab</kbd> to move the focus to the previous interactive element
+
+## Implementation
+
+- **MUST** have a visible focus border [SC 2.4.7][8]
+    - Exception is an in-line link, which **SHOULD** use an underline to preserve zoom/magnification and prevent a split focus ring
+- **MUST** use `<a>` element with a valid href value. In rare problematic cases, setting `role="link"` (and adding all other aspects of link functionality) may be acceptable [SC 4.1.2][9]
+- **Focus Management:** if button activation closes the containing entity or launches another
+    entity, then focus moves to the newly opened entity. If activitating a button results in the
+    control being disabled, focus should move to the next active element in the tab order.
+- **Screen reader announcements** for when a link opens a [SC 3.2][10]:
+    - new tab or window
+    - non-HTML document (doc, excel, spreadsheet, ppt, plain text, etc)
+    - new application
+
+[1]: https://splunkui.splunkeng.com/Packages/react-ui/Button
+[2]: https://www.w3.org/TR/WCAG21/#use-of-color
+[3]: https://www.w3.org/TR/WCAG21/#contrast-minimum
+[4]: https://www.w3.org/TR/WCAG21/#non-text-contrast
+[5]: https://www.w3.org/TR/WCAG20-TECHS/G201.html
+[6]: https://www.w3.org/TR/WCAG21/#link-purpose-in-context%5C
+[7]: https://www.w3.org/TR/WCAG21/#keyboard-accessible
+[8]: https://www.w3.org/TR/WCAG21/#focus-visible
+[9]: https://www.w3.org/TR/WCAG21/#name-role-value
+[10]: https://www.w3.org/TR/WCAG20-TECHS/G201.html
+
+