@splunk/react-ui 5.7.1 → 5.8.0

package/docs-llm/List.md

@@ -0,0 +1,189 @@
+# List
+
+## Overview
+
+
+> Image: Illustration of a list component.
+
+
+## When to use this component
+You need to group related content vertically.
+- If your content has no specific order, use an unordered list.
+- If your content has a priority, hierarchy, or sequence between list items, use an ordered list.
+
+
+## When to use another component
+- If you need to display complex sets of data, use a data table.
+- If users need to quickly understand a direct relationship between a key-value pairs, use a definition list.
+
+```mermaid
+graph TD
+    accDescr: Decision tree that guides on when to use the List component or something else
+    A("Does your data have a clear relationship with a key (label) and value(s)?") -- Yes --- B(Definition List)
+    A -- No --- C(Is your data set complex and needs to be displayed for easy comparison or reference?)
+    C -- No --- D(Table)
+    C -- Yes --- E(List or Paragraph)
+```
+
+### Check out
+- [Definition List][1]
+- [Table][2]
+
+## Usage
+
+### Multiple items
+Lists are best at displaying multiple items. If you are displaying fewer than two items, consider how to present the information as plain text on the page.
+
+> Image: Examples of a List outlining the Benefits of Splunk ES. In the first example with heart eyes emojis, the following three benefits are outlined, 
+
+
+### Logical order
+Arrange list items in a logical way. For example, if the list is about resource use, the default order might be highest resource use to lowest. Grouping items in categories into smaller, more specific lists might be more meaningful.
+
+> Image: Examples of a List outlining server usage stats for four servers, Server A with 85% CPU usage, Server B with 70% CPU usage, Server C with 50% CPU usage, and Server D with 30% CPU usage. In the first example with heart eyes emojis, the servers are split based on their data center location and then ordered alphabetically. In the second example with grimacing emoji, the order of the list is totally random, not following any sequence.
+
+
+### Links
+Include links if they are relevant to better understanding the context of the list. If the whole list item is selectable, use a navigational or interactive component.
+
+> Image: Examples of a List with the title, 
+
+
+## Content
+Follow writing best practices for Lists outlined in the [Splunk Style Guide][3]
+
+### Be concise
+Try not to exceed 2 lines per list item and use list items that are grammatically parallel. For example, do not mix passive voice with active voice or declarative sentences (statements) with imperative sentences (direct command).
+
+> Image: Examples of List with two items outlining server installation steps. In the first example with the heart eyes emoji has a concise label, the list items are 
+
+
+[1]: ./DefinitionList
+[2]: ./Table
+[3]: https://docs.splunk.com/Documentation/StyleGuide/current/StyleGuide/Listoverview
+
+## Examples
+
+
+### Unordered List
+
+```typescript
+import React from 'react';
+
+import List from '@splunk/react-ui/List';
+
+
+function UnorderedList() {
+    return (
+        <List>
+            <List.Item>Bar Chart</List.Item>
+            <List.Item>Area Chart</List.Item>
+            <List.Item>Pie Chart</List.Item>
+        </List>
+    );
+}
+
+export default UnorderedList;
+```
+
+
+
+### Ordered List
+
+Ordered Lists use numerals by default.
+
+```typescript
+import React from 'react';
+
+import List from '@splunk/react-ui/List';
+
+
+function Ordered() {
+    return (
+        <List ordered>
+            <List.Item>First Item</List.Item>
+            <List.Item>Second Item</List.Item>
+            <List.Item>Third Item</List.Item>
+        </List>
+    );
+}
+
+export default Ordered;
+```
+
+
+
+### Customized List
+
+```typescript
+import React from 'react';
+
+import styled from 'styled-components';
+
+import List from '@splunk/react-ui/List';
+
+const StyledList = styled(List)`
+    list-style-type: lower-roman;
+`;
+
+
+function CustomizedList() {
+    return (
+        <StyledList ordered>
+            <List.Item>First Item</List.Item>
+            <List.Item>Second Item</List.Item>
+            <List.Item>Third Item</List.Item>
+        </StyledList>
+    );
+}
+
+export default CustomizedList;
+```
+
+
+
+
+## API
+
+
+### List API
+
+#### Props
+
+| Name | Type | Required | Default | Description |
+|------|------|------|------|------|
+| children | React.ReactNode | no |  |  |
+| elementRef | React.Ref<HTMLOListElement \| HTMLUListElement> | no |  | A React ref which is set to the DOM element when the component mounts and null when it unmounts.  `HTMLUListElement` if type is 'disc', `HTMLOListElement` otherwise. |
+| ordered | boolean | no |  | Sets the element as an `HTMLOListElement`  otherwise it defaults to `HTMLUListElement`. |
+
+
+
+### List.Item API
+
+A container for items of a `List`.
+
+#### Props
+
+| Name | Type | Required | Default | Description |
+|------|------|------|------|------|
+| children | React.ReactNode | no |  |  |
+| elementRef | React.Ref<HTMLLIElement> | no |  | A React ref which is set to the DOM element when the component mounts and null when it unmounts. |
+
+
+
+
+
+## Accessibility
+
+## Visual Design
+- Color contrast ratio **MUST** be [SC 1.4.3][1]:
+    - &gt= 3:1 for icon and caret (&gt) against page background 
+    - &gt= 4:5:1 for functional text against page background
+
+## Implementation
+- **MUST** use HTML semantics: `<ul>` or `<ol>` with `<li>` child elements, or `<dl>` with `<dt>` and `<dd>` child elements [SC 1.3.1][2]
+
+[1]: https://www.w3.org/TR/WCAG21/#contrast-minimum
+[2]: https://www.w3.org/TR/WCAG21/#info-and-relationships
+
+

package/docs-llm/Markdown.md

@@ -0,0 +1,179 @@
+# Markdown
+
+## Examples
+
+
+### example
+
+```typescript
+import React from 'react';
+
+import Markdown from '@splunk/react-ui/Markdown';
+
+const example = `
+# Products overview
+
+- Platform
+- Security:
+    - Splunk Enterprise Security
+    - Splunk Mission Control
+
+ * Observability
+    * Splunk Infrastructure Monitoring
+    * Splunk IT Service Intelligence
+
+## Keep your digital systems securely up and running
+Fend off threat actors. Diminish downtime. Fix issues faster. Do it all with Splunk, the key to enterprise resilience.
+
+1. Prevent major issues
+1. Absorb shocks
+1. Accelerate transformation
+
+### Sandbox
+
+    function lookAway() {
+        head.turn('left');
+    }
+
+
+Link to [Overview](Overview)
+`;
+
+
+function BasicExample() {
+    return <Markdown text={example} />;
+}
+
+export default BasicExample;
+```
+
+
+
+### I18n
+
+Combine with gettext interpolation.
+
+```typescript
+/* eslint-disable prefer-template */
+import React from 'react';
+
+import Markdown from '@splunk/react-ui/Markdown';
+import { _ } from '@splunk/ui-utils/i18n';
+
+
+function I18nExample() {
+    const text = _(
+        '### UI internationalization\n' +
+            'Translate text generated by Python code, JavaScript code, views, menus and Mako templates. Set language/locale ' +
+            'specific alternatives for static resources such as images, CSS, other media.\n\n' +
+            '[Learn more](https://www.splunk.com/en_us/search.html?q=i18n&size=n_10_n) about Splunk software translation.\n'
+    );
+    return <Markdown text={text} />;
+}
+
+export default I18nExample;
+```
+
+
+
+### render-props
+
+```typescript
+import React from 'react';
+
+import Link from '@splunk/react-ui/Link';
+import List from '@splunk/react-ui/List';
+import Markdown, { LinkRenderer, ListRenderer } from '@splunk/react-ui/Markdown';
+
+const externalURLs: Array<string> = ['https://www.google.com', 'https://www.splunk.com/'];
+
+const example = `
+### Link
+
+Internal Link to [Overview](Overview)
+
+External Link to [Splunk](https://www.splunk.com/)
+
+### List
+
+#### Solution
+
+1. Advanced threat detection
+2. Automation and Orchestration
+3. Extend visibility from on-premises to the cloud
+
+- Incident management
+- Isolate problems in cloud-native environments
+- IT modernization
+`;
+
+
+const linkRenderer: LinkRenderer = ({ title, href, children }) => {
+    const isExternal = href && externalURLs.indexOf(href) >= 0;
+
+    return (
+        <Link title={title} to={href} openInNewContext={isExternal}>
+            {children}
+        </Link>
+    );
+};
+
+const listRenderer: ListRenderer = ({ ordered, children }) => {
+    return <List ordered={ordered}>{children}</List>;
+};
+
+function RendererExample() {
+    return <Markdown text={example} linkRenderer={linkRenderer} listRenderer={listRenderer} />;
+}
+
+export default RendererExample;
+```
+
+
+
+
+## API
+
+
+### Markdown API
+
+The `Markdown` component renders the given Markdown text as a React component.
+The component prefers @splunk/react-ui components over plain HTML components. For example
+links are rendered as the `@splunk/react-ui/Link` component instead of plain `<a>` tag.
+
+#### Props
+
+| Name | Type | Required | Default | Description |
+|------|------|------|------|------|
+| blockquoteRenderer | BlockquoteRenderer | no |  | A custom blockquote renderer. The function is passed an object containing `children`. |
+| codeBlockRenderer | CodeBlockRenderer | no |  | A custom code block renderer. The function is passed an object containing `language`, and `children`. It supports the same languages as the `Code` component. |
+| codeRenderer | CodeRenderer | no |  | A custom code literal renderer. The function is passed an object containing `children`. |
+| elementRef | React.Ref<HTMLElement> | no |  | A React ref which is set to the DOM element when the component mounts and null when it unmounts. |
+| headingRenderer | HeadingRenderer \| AnchorHeadingRenderer | no |  | A custom heading renderer. The function is passed an object containing `level` from 1 to 6 and `children`. |
+| imageRenderer | ImageRenderer | no |  | A custom image renderer. The function is passed an object containing `src`, `title`, and `alt`. |
+| itemRenderer | ItemRenderer | no |  | A custom list item renderer. The function is passed an object containing `children`. |
+| linkRenderer | LinkRenderer | no |  | A custom link renderer. This is useful for single-page apps that need to handle links internally. The function is passed an object containing `href`, `title`, and `children`. |
+| listRenderer | ListRenderer | no |  | A custom list renderer. The function is passed an object containing `ordered`, `depth`, and `children`. |
+| paragraphRenderer | ParagraphRenderer | no |  | A custom paragraph renderer. The function is passed an object containing `children`. |
+| text | string | yes |  | The content to be parsed and rendered. |
+
+#### Types
+
+| Name | Type | Description |
+|------|------|------|
+| AnchorHeadingRenderer | (props: {     children: React.ReactNode[];     level: number; }) => RemarkReturn |  |
+| BlockquoteRenderer | (props: { children: React.ReactNode[] }) => RemarkReturn |  |
+| CodeBlockRenderer | (props: {     language?: string;     children: React.ReactNode[]; }) => RemarkReturn |  |
+| CodeRenderer | (props: { children: React.ReactNode[] }) => RemarkReturn |  |
+| HeadingRenderer | (props: { children: React.ReactNode[]; level: number }) => RemarkReturn |  |
+| ImageRenderer | (props: { alt?: string; src?: string; title?: string }) => RemarkReturn |  |
+| ItemRenderer | (props: { children: React.ReactNode[] }) => RemarkReturn |  |
+| LinkRenderer | (props: {     children: React.ReactNode[];     href?: string;     title?: string; }) => RemarkReturn |  |
+| ListRenderer | (props: {     children: React.ReactNode[];     depth: number;     ordered: boolean; }) => RemarkReturn |  |
+| ParagraphRenderer | (props: { children: React.ReactNode[] }) => RemarkReturn |  |
+| RemarkReturn | React.ReactElement<any, any> \| null |  |
+
+
+
+
+