@splunk/react-ui 5.7.1 → 5.9.0

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 |  |
+
+
+
+
+

package/docs-llm/Paragraph.md

@@ -0,0 +1,148 @@
+# Paragraph
+
+## Overview
+
+
+> Image: Illustration of Paragraph component.
+
+
+## When to use this component
+- To provide a structured layout for textual sentence-style information.
+
+## When to use another component
+- If the content involves listing or numbering items, using `List` improves readability and organization.
+- If the content involves related data elements, using `Definition List` provides a structured visual representation for key-value pairs.
+
+```mermaid
+graph TD
+    accDescr: Decision tree that guides on when to use the Paragraph component or something else
+    A(Does the content involve listing items?) -- Yes --- B(List or Definition List)
+    A -- No --- C(Paragraph)
+```
+
+### Check out
+- [List][1]
+- [Definition List][2]
+
+## Usage
+
+### Break paragraphs into small chunks
+Shorter paragraphs improves readability and reduces eye fatigue.
+
+> Image: Examples of Paragraph components. In the first example with heart eyes emoji, the text is formatted into two smaller paragraphs. In the second example with grimacing emoji the text is formatted in one longer paragraph.
+
+
+### Avoid standalone paragraphs
+Paragraphs should be accompanied by a header that summarizes the content, guides the user’s attention and allows screen readers to navigate to the content.
+
+> Image: Examples of Paragraph components. In the first example with heart eyes emoji, the paragraph is accompanied by a header, while the second example with grimacing emoji is a stand alone paragraph.
+
+
+## Content guidelines
+Follow writing best practices outlined in the [UI text style guidelines][3]
+
+[1]: ./List
+[2]: ./DefinitionList
+[3]: https://docs.splunk.com/Documentation/StyleGuide/current/StyleGuide/UIGuidelines
+
+
+## Examples
+
+
+### Basic
+
+Paragraph provides default fonts, line heights, and spacing. Margins can be removed when necessary.
+
+```typescript
+import React from 'react';
+
+import Link from '@splunk/react-ui/Link';
+import P from '@splunk/react-ui/Paragraph';
+
+
+function Basic() {
+    return (
+        <>
+            <P>
+                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.
+            </P>
+            <P>
+                <Link to="https://www.splunk.com/en_us/products/platform.html" openInNewContext>
+                    The Splunk Platform
+                </Link>{' '}
+                allows you turn data into doing to unlock innovation, enhance security and drive
+                resilience.{' '}
+                <Link
+                    to="https://www.splunk.com/en_us/products/cyber-security.html"
+                    openInNewContext
+                >
+                    Splunk Security
+                </Link>{' '}
+                protects your business and modernize your security operations with a best-in-class
+                data platform, advanced analytics and automated investigations and response.{' '}
+                <Link
+                    to="https://www.splunk.com/en_us/products/observability.html"
+                    openInNewContext
+                >
+                    Splunk Observability
+                </Link>{' '}
+                solves problems in seconds with the only full-stack, analytics-powered and
+                OpenTelemetry-native observability solution.
+            </P>
+        </>
+    );
+}
+
+export default Basic;
+```
+
+
+
+
+## API
+
+
+### Paragraph API
+
+#### Props
+
+| Name | Type | Required | Default | Description |
+|------|------|------|------|------|
+| children | React.ReactNode | no |  | Generally text, but might also include `Link`s. |
+| elementRef | React.Ref<HTMLParagraphElement> | 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= 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]
+
+## States
+- Color contrast guidelines do NOT apply to disabled text
+
+## Interaction Model
+- **MUST NOT** lose content or functionality when the user adapts [SC 1.4.12][3]
+    - Line height (line spacing) to at least 1.5 times the font size;
+    - Spacing following paragraphs to at least 2 times the font size;
+    - Letter spacing (tracking) to at least 0.12 times the font size;
+    - Word spacing to at least 0.16 times the font size
+- Line spacing (leading) **MUST** be at least space-and-a-half within paragraphs, and paragraph spacing is at least 1.5 times larger than the line spacing [SC 1.4.8][4]
+
+## Implementation
+- **SHOULD** use correct [phrasing elements][5] to describe the semantics of the content
+
+[1]: https://www.w3.org/WAI/GL/UNDERSTANDING-WCAG20/visual-audio-contrast-contrast.html
+[2]: https://www.w3.org/TR/WCAG21/#contrast-enhanced
+[3]: https://www.w3.org/TR/WCAG21/#text-spacing
+[4]: https://www.w3.org/TR/WCAG21/#visual-presentation
+[5]: https://developer.mozilla.org/en-US/docs/Web/Guide/HTML/Content_categories#phrasing_content
+
+