@splunk/react-ui 5.7.0 → 5.8.0

package/docs-llm/Tab Layout.md

@@ -0,0 +1,398 @@
+# Tab Layout
+
+## Examples
+
+
+### Uncontrolled
+
+```typescript
+import React from 'react';
+
+import P from '@splunk/react-ui/Paragraph';
+import TabLayout from '@splunk/react-ui/TabLayout';
+
+
+function Uncontrolled() {
+    return (
+        <TabLayout defaultActivePanelId="platform">
+            <TabLayout.Panel label="Platform" panelId="platform">
+                <P>
+                    The extensible data platform powers unified security, full-stack observability
+                    and limitless custom applications.
+                </P>
+            </TabLayout.Panel>
+            <TabLayout.Panel label="Security" panelId="security">
+                <P>
+                    Protect your business and modernize your security operations with a
+                    best-in-class data platform, advanced analytics and automated investigations and
+                    response.
+                </P>
+            </TabLayout.Panel>
+            <TabLayout.Panel label="Observability" panelId="observability">
+                <P>
+                    Solve problems in seconds with the only full-stack, analytics-powered and
+                    OpenTelemetry-native observability solution.
+                </P>
+            </TabLayout.Panel>
+        </TabLayout>
+    );
+}
+
+export default Uncontrolled;
+```
+
+
+
+### Controlled
+
+In this example, the open Panel is controlled by the parent component.
+
+```typescript
+import React, { useState } from 'react';
+
+import P from '@splunk/react-ui/Paragraph';
+import TabLayout, { TabLayoutChangeHandler } from '@splunk/react-ui/TabLayout';
+
+
+function Controlled() {
+    const [activePanelId, setActivePanelId] = useState<string | undefined>('platform');
+
+    const handleChange: TabLayoutChangeHandler = (e, { activePanelId: panelId }) => {
+        setActivePanelId(panelId);
+    };
+
+    return (
+        <TabLayout activePanelId={activePanelId} onChange={handleChange}>
+            <TabLayout.Panel label="Platform" panelId="platform">
+                <P>
+                    The extensible data platform powers unified security, full-stack observability
+                    and limitless custom applications.
+                </P>
+            </TabLayout.Panel>
+            <TabLayout.Panel label="Security" panelId="security">
+                <P>
+                    Protect your business and modernize your security operations with a
+                    best-in-class data platform, advanced analytics and automated investigations and
+                    response.
+                </P>
+            </TabLayout.Panel>
+            <TabLayout.Panel label="Observability" panelId="observability">
+                <P>
+                    Solve problems in seconds with the only full-stack, analytics-powered and
+                    OpenTelemetry-native observability solution.
+                </P>
+            </TabLayout.Panel>
+        </TabLayout>
+    );
+}
+
+export default Controlled;
+```
+
+
+
+### Auto activate
+
+In this example, switching to a tab with the keyboard automatically activates it.
+
+```typescript
+import React from 'react';
+
+import P from '@splunk/react-ui/Paragraph';
+import TabLayout from '@splunk/react-ui/TabLayout';
+
+
+function AutoActivate() {
+    return (
+        <TabLayout autoActivate defaultActivePanelId="platform">
+            <TabLayout.Panel label="Platform" panelId="platform">
+                <P>
+                    The extensible data platform powers unified security, full-stack observability
+                    and limitless custom applications.
+                </P>
+            </TabLayout.Panel>
+            <TabLayout.Panel label="Security" panelId="security">
+                <P>
+                    Protect your business and modernize your security operations with a
+                    best-in-class data platform, advanced analytics and automated investigations and
+                    response.
+                </P>
+            </TabLayout.Panel>
+            <TabLayout.Panel label="Observability" panelId="observability">
+                <P>
+                    Solve problems in seconds with the only full-stack, analytics-powered and
+                    OpenTelemetry-native observability solution.
+                </P>
+            </TabLayout.Panel>
+        </TabLayout>
+    );
+}
+
+export default AutoActivate;
+```
+
+
+
+### Icons
+
+```typescript
+import React from 'react';
+
+import ChartBarIcon from '@splunk/react-icons/ChartBar';
+import SearchIcon from '@splunk/react-icons/Magnifier';
+import TableIcon from '@splunk/react-icons/Table';
+import Heading from '@splunk/react-ui/Heading';
+import Paragraph from '@splunk/react-ui/Paragraph';
+import Prose from '@splunk/react-ui/Prose';
+import TabLayout from '@splunk/react-ui/TabLayout';
+
+
+function Icons() {
+    return (
+        <TabLayout defaultActivePanelId="search">
+            <TabLayout.Panel label="Search" panelId="search" icon={<SearchIcon />}>
+                <Prose>
+                    <Heading level={4}>Search</Heading>
+                    <Paragraph>
+                        There are six broad types for all of the search commands: distributable
+                        streaming, centralized streaming, transforming, generating, orchestrating
+                        and dataset processing.
+                    </Paragraph>
+                </Prose>
+            </TabLayout.Panel>
+            <TabLayout.Panel label="Statistics" panelId="statistics" icon={<TableIcon />}>
+                <Prose>
+                    <Heading level={4}>Statistics</Heading>
+                    <Paragraph>
+                        You can use the statistical and charting functions with the chart, stats,
+                        and timechart commands.
+                    </Paragraph>
+                </Prose>
+            </TabLayout.Panel>
+            <TabLayout.Panel
+                label="Visualizations"
+                panelId="visualizations"
+                icon={<ChartBarIcon />}
+            >
+                <Prose>
+                    <Heading level={4}>Visualizations</Heading>
+                    <Paragraph>
+                        There are many different types of visualizations available, including line
+                        charts, area charts, and bar charts to name a few.
+                    </Paragraph>
+                </Prose>
+            </TabLayout.Panel>
+        </TabLayout>
+    );
+}
+
+export default Icons;
+```
+
+
+
+### Vertical
+
+```typescript
+import React from 'react';
+
+import Heading from '@splunk/react-ui/Heading';
+import Paragraph from '@splunk/react-ui/Paragraph';
+import Prose from '@splunk/react-ui/Prose';
+import TabLayout from '@splunk/react-ui/TabLayout';
+
+
+function Vertical() {
+    return (
+        <TabLayout defaultActivePanelId="platform" layout="vertical">
+            <TabLayout.Panel label="Platform" panelId="platform">
+                <Prose>
+                    <Heading level={4}>Platform</Heading>
+                    <Paragraph>
+                        The extensible data platform powers unified security, full-stack
+                        observability and limitless custom applications.
+                    </Paragraph>
+                </Prose>
+            </TabLayout.Panel>
+            <TabLayout.Panel label="Security" panelId="security">
+                <Prose>
+                    <Heading level={4}>Security</Heading>
+                    <Paragraph>
+                        Protect your business and modernize your security operations with a
+                        best-in-class data platform, advanced analytics and automated investigations
+                        and response.
+                    </Paragraph>
+                </Prose>
+            </TabLayout.Panel>
+            <TabLayout.Panel label="Observability" panelId="observability">
+                <Prose>
+                    <Heading level={4}>Observability</Heading>
+                    <Paragraph>
+                        Solve problems in seconds with the only full-stack, analytics-powered and
+                        OpenTelemetry-native observability solution.
+                    </Paragraph>
+                </Prose>
+            </TabLayout.Panel>
+        </TabLayout>
+    );
+}
+
+export default Vertical;
+```
+
+
+
+### Vertical Icons
+
+```typescript
+import React from 'react';
+
+import ChartBarIcon from '@splunk/react-icons/ChartBar';
+import SearchIcon from '@splunk/react-icons/Magnifier';
+import TableIcon from '@splunk/react-icons/Table';
+import Heading from '@splunk/react-ui/Heading';
+import Paragraph from '@splunk/react-ui/Paragraph';
+import Prose from '@splunk/react-ui/Prose';
+import TabLayout from '@splunk/react-ui/TabLayout';
+
+
+function VerticalIcons() {
+    return (
+        <TabLayout defaultActivePanelId="search" layout="vertical">
+            <TabLayout.Panel label="Search" panelId="search" icon={<SearchIcon />}>
+                <Prose>
+                    <Heading level={4}>Search</Heading>
+                    <Paragraph>
+                        There are six broad types for all of the search commands: distributable
+                        streaming, centralized streaming, transforming, generating, orchestrating
+                        and dataset processing.
+                    </Paragraph>
+                </Prose>
+            </TabLayout.Panel>
+            <TabLayout.Panel label="Statistics" panelId="statistics" icon={<TableIcon />}>
+                <Prose>
+                    <Heading level={4}>Statistics</Heading>
+                    <Paragraph>
+                        You can use the statistical and charting functions with the chart, stats,
+                        and timechart commands.
+                    </Paragraph>
+                </Prose>
+            </TabLayout.Panel>
+            <TabLayout.Panel
+                label="Visualizations"
+                panelId="visualizations"
+                icon={<ChartBarIcon />}
+            >
+                <Prose>
+                    <Heading level={4}>Visualizations</Heading>
+                    <Paragraph>
+                        There are many different types of visualizations available, including line
+                        charts, area charts, and bar charts to name a few.
+                    </Paragraph>
+                </Prose>
+            </TabLayout.Panel>
+        </TabLayout>
+    );
+}
+
+export default VerticalIcons;
+```
+
+
+
+
+## API
+
+
+### TabLayout API
+
+The `TabLayout` is a group of managed `Panels`. Only one panel can be open at a time.
+`TabLayout` supports both the controlled and uncontrolled patterns.
+
+#### Props
+
+| Name | Type | Required | Default | Description |
+|------|------|------|------|------|
+| activePanelId | string | no |  | The `panelId` of the `TabLayout.Panel` to activate. If set, an `onChange` callback is required. |
+| autoActivate | boolean | no |  | If `true`, tabs will trigger the `onChange` callback when they receive focus. |
+| children | React.ReactNode | no |  | Must be `TabLayout.Panel`. |
+| defaultActivePanelId | string | no |  | Sets the active panel on the initial render. It must match the `panelId` of one of the child `TabLayout.Panel`s. Only use `defaultActivePanelId` when using `TabLayout` as an uncontrolled component. |
+| elementRef | React.Ref<HTMLDivElement> | no |  | A React ref which is set to the DOM element when the component mounts and null when it unmounts. |
+| iconPosition | 'above' \| 'left' | no |  | **DEPRECATED**: This prop is deprecated and will be removed in the next major version. Position of icon in `TabBar.Tab` if it has an icon. Defaults to "left". |
+| layout | 'horizontal' \| 'vertical' | no | 'horizontal' | The layout direction for tabs. |
+| maxTabWidth | number | no |  | Max width of each `TabBar.Tab` in pixels. Leave blank for auto max width. |
+| onChange | TabLayoutChangeHandler | no |  | A callback that receives the event and data (`selectedPanelId`). If activePanelId is set, this callback is required. |
+
+#### Types
+
+| Name | Type | Description |
+|------|------|------|
+| TabLayoutChangeHandler | (     event: React.MouseEvent<HTMLButtonElement> \| React.FocusEvent<HTMLButtonElement>,     data: { activePanelId?: string } ) => void |  |
+
+
+
+### TabLayout.Panel API
+
+#### Props
+
+| Name | Type | Required | Default | Description |
+|------|------|------|------|------|
+| children | React.ReactNode | no |  |  |
+| count | number | no |  | Inserts number in tab label. |
+| disabled | boolean | no | false | Prevents user from clicking the tab. |
+| elementRef | React.Ref<HTMLDivElement> | no |  | A React ref which is set to the DOM element when the component mounts and null when it unmounts. |
+| icon | React.ReactNode | no |  | See Icon documentation for more information. |
+| inset | boolean | no | true | By default, adds padding to panel content. If set to false, renders panel content without padding. |
+| label | React.ReactNode | no |  | The text shown in the button. |
+| panelId | string | yes |  | A unique `id` for this panel and used by the `TabLayout` to keep track of the open panel. |
+| tooltip | React.ReactNode | no |  | Content to show in a tooltip when the user hovers over or focuses on the tab.  Note: The tooltip will override the label for the Panel for screen readers. |
+
+
+
+
+
+## Accessibility
+
+> NOT suported by design system: tab list overflow, configurable (add, delete, reorder) tab lists
+
+## Visual Design
+- Color contrast ratio **MUST** be:
+    - &gt= 4.5:1 for normal text: 14 pt (typically 18.66px) and bold or larger [SC 1.4.3][1]
+    - &gt= 3:1 for large text: 18 pt (typically 24px) or larger [SC 1.4.3][1]
+    - &gt= 3:1 for tab bar against page background [SC 1.4.11][2]
+    - Focus State: if the focus ring has a radius of [SC 1.4.11][2]
+        - &lt 3px: &gt= 4.5.1 between button &lt&gt focus &lt&gt background
+        - &gt 3px: &gt= 3.1 button button &lt&gt focus &lt&gt background
+    - `alt=""` for decorative icons [SC 1.1.1][3]
+
+## States
+-  Color contrast guidelines do not apply to disabled tabs
+
+## Interaction Design
+- **Define Manual vs. Automatic:** Designers **MUST** specify which interaction model they want in specs for engineering. By default, Splunk Design System uses manual tabs and supports automatic tabs. 
+    - **Automatic activation:** When a user focuses on a tab, it automatically loads. This is recommended for static text and some images.
+    - **Manual activation:** A user must click the tab or use <kbd>Enter/Space</kbd> to load the content in tabs. This is recommended for dynamic content such as tables, visualizations, etc.
+- Focus state does **SHOULD NOT** cover visual design elements that illustate which tab a user is on, or that the elements are not the same color as the selected bar.
+- **MUST** have keyboard navigation [SC 2.1][4]:
+    - <kbd>Tab</kbd> and <kbd>Shift+Tab</kbd> to move into the tablist, focusing on active tab 
+
+        - A second <kbd>Tab</kbd> and <kbd>Shift+Tab</kbd> moves to the next interactive element in the sequence
+    - If the design has a tablist that runs..
+        - Horizontally: <kbd>Left</kbd> and <kbd>Right Arrow</kbd> to circle thru tabs
+        - Vertically: <kbd>Up</kbd> and <kbd>Down Arrow</kbd> to circle thru tabs
+    - disabled tabs **MUST** be skipped in navigation 
+
+## Implementation
+- Tabs **MUST** be implemented as a list so users receive correct information
+- As a fallback mechanism, this allows tabs to gracefully degrade back to a list of content
+- Tabs as part of a navigation bar **MUST** be implemented as links and use manual navigation
+- If tabs use quantifier, this number **MUST** to be announced by screen reader
+- Vertical tab bars **MUST** have `aria-orientation=vertical`
+- Observe specifications for manual or automatic activation as prescribed by the interaction model section
+
+[1]: https://www.w3.org/TR/WCAG21/#contrast-minimum
+[2]: https://www.w3.org/TR/WCAG21/#non-text-contrast
+[3]: https://www.w3.org/TR/WCAG21/#non-text-content
+[4]: https://www.w3.org/TR/WCAG21/#keyboard-accessible
+
+