@splunk/react-ui 5.7.1 → 5.9.0

package/docs-llm/Dropdown.md

@@ -0,0 +1,472 @@
+# Dropdown
+
+## Examples
+
+
+### Dropdown
+
+A Dropdown can contain any content. The content must constrain its own width.
+
+```typescript
+import React from 'react';
+
+import Button from '@splunk/react-ui/Button';
+import Dropdown from '@splunk/react-ui/Dropdown';
+
+
+function Basic() {
+    const toggle = <Button label="Open dropdown" />;
+
+    return (
+        <Dropdown toggle={toggle} retainFocus>
+            <div style={{ padding: '20px', maxWidth: '300px' }}>
+                This is the content of the dropdown. You can customize it as needed.
+            </div>
+        </Dropdown>
+    );
+}
+
+export default Basic;
+```
+
+
+
+### Dropdown menu
+
+```typescript
+import React from 'react';
+
+import Button from '@splunk/react-ui/Button';
+import Dropdown from '@splunk/react-ui/Dropdown';
+import Menu from '@splunk/react-ui/Menu';
+
+
+function BasicMenu() {
+    const toggle = <Button label="Direction" isMenu />;
+
+    return (
+        <Dropdown toggle={toggle}>
+            <Menu style={{ width: 120 }}>
+                <Menu.Item>Up</Menu.Item>
+                <Menu.Item>Down</Menu.Item>
+                <Menu.Item>Left</Menu.Item>
+                <Menu.Item>Right</Menu.Item>
+                <Menu.Divider />
+                <Menu.Item to="n">North</Menu.Item>
+                <Menu.Item to="s">South</Menu.Item>
+                <Menu.Item to="w">West</Menu.Item>
+                <Menu.Item to="e">East</Menu.Item>
+            </Menu>
+        </Dropdown>
+    );
+}
+
+export default BasicMenu;
+```
+
+
+
+### Dropdown submenu
+
+```typescript
+import React from 'react';
+
+import ChevronLeft from '@splunk/react-icons/ChevronLeft';
+import EnterpriseChevronLeft from '@splunk/react-icons/enterprise/ChevronLeft';
+import Button from '@splunk/react-ui/Button';
+import Dropdown, { DropdownPossibleCloseReason } from '@splunk/react-ui/Dropdown';
+import Menu from '@splunk/react-ui/Menu';
+import SlidingPanels from '@splunk/react-ui/SlidingPanels';
+import { useSplunkTheme } from '@splunk/themes';
+
+
+function Submenu() {
+    const [transition, setTransition] = React.useState<'forward' | 'backward' | undefined>(
+        'forward'
+    );
+    const [activePanelId, setActivePanelId] = React.useState('one');
+
+    const goBackward = () => {
+        setActivePanelId(activePanelId === 'one' ? 'two' : 'one');
+        setTransition('backward');
+    };
+
+    const goForward = () => {
+        setActivePanelId(activePanelId === 'one' ? 'two' : 'one');
+        setTransition('forward');
+    };
+
+    const toggle = <Button isMenu />;
+    const closeReasons: DropdownPossibleCloseReason[] = [
+        'clickAway',
+        'escapeKey',
+        'offScreen',
+        'toggleClick',
+    ];
+
+    const { isEnterprise } = useSplunkTheme();
+
+    return (
+        <Dropdown closeReasons={closeReasons} toggle={toggle}>
+            <SlidingPanels activePanelId={activePanelId} transition={transition}>
+                <SlidingPanels.Panel key="one" panelId="one">
+                    <Menu style={{ width: 160 }}>
+                        <Menu.Item hasSubmenu onClick={goForward}>
+                            Category 1
+                        </Menu.Item>
+                        <Menu.Item hasSubmenu onClick={goForward}>
+                            Category 2
+                        </Menu.Item>
+                        <Menu.Item hasSubmenu onClick={goForward}>
+                            Category 3
+                        </Menu.Item>
+                        <Menu.Item hasSubmenu onClick={goForward}>
+                            Category 4
+                        </Menu.Item>
+                        <Menu.Item hasSubmenu onClick={goForward}>
+                            Category 5
+                        </Menu.Item>
+                        <Menu.Item hasSubmenu onClick={goForward}>
+                            Category 6
+                        </Menu.Item>
+                        <Menu.Item hasSubmenu onClick={goForward}>
+                            Category 7
+                        </Menu.Item>
+                        <Menu.Item hasSubmenu onClick={goForward}>
+                            Category 8
+                        </Menu.Item>
+                    </Menu>
+                </SlidingPanels.Panel>
+                <SlidingPanels.Panel key="two" panelId="two">
+                    <Menu style={{ width: 160 }}>
+                        <Menu.Item
+                            startAdornment={
+                                isEnterprise ? (
+                                    <EnterpriseChevronLeft
+                                        screenReaderText={null}
+                                        hideDefaultTooltip
+                                    />
+                                ) : (
+                                    <ChevronLeft />
+                                )
+                            }
+                            onClick={goBackward}
+                        >
+                            Back
+                        </Menu.Item>
+                        <Menu.Divider />
+                        <Menu.Item>Option 1</Menu.Item>
+                        <Menu.Item>Option 2</Menu.Item>
+                        <Menu.Item>Option 3</Menu.Item>
+                        <Menu.Item>Option 4</Menu.Item>
+                        <Menu.Item>Option 5</Menu.Item>
+                        <Menu.Item>Option 6</Menu.Item>
+                        <Menu.Item>Option 7</Menu.Item>
+                    </Menu>
+                </SlidingPanels.Panel>
+            </SlidingPanels>
+        </Dropdown>
+    );
+}
+
+export default Submenu;
+```
+
+
+
+### Dropdown scrolling menu
+
+If a Menu contains many items, you can let the Menu scroll by setting the overflowY and maxHeight style prop.
+
+```typescript
+import React from 'react';
+
+import Button from '@splunk/react-ui/Button';
+import Dropdown from '@splunk/react-ui/Dropdown';
+import Menu from '@splunk/react-ui/Menu';
+
+
+function ScrollingMenu() {
+    const toggle = <Button label="Numbers" isMenu />;
+
+    // Creates 100 menu items from 1 - 100
+    const items: React.ReactElement[] = [];
+    for (let index = 0; index < 100; index += 1) {
+        items.push(<Menu.Item key={`menu-item-${index}`}>{index + 1}</Menu.Item>);
+    }
+
+    
+    return (
+        <Dropdown toggle={toggle}>
+            {({ maxHeight }) => (
+                <Menu
+                    stopScrollPropagation
+                    style={{
+                        maxHeight: maxHeight ?? undefined,
+                        overflowY: 'auto',
+                    }}
+                >
+                    {items}
+                </Menu>
+            )}
+        </Dropdown>
+    );
+}
+
+export default ScrollingMenu;
+```
+
+
+
+### Dropdown dialog
+
+By default, a Dropdown dialog box does not close on click. Set the closeReasons prop to ignore specific actions.
+
+```typescript
+import React from 'react';
+
+import { without } from 'lodash';
+
+import Button from '@splunk/react-ui/Button';
+import ControlGroup from '@splunk/react-ui/ControlGroup';
+import Dropdown from '@splunk/react-ui/Dropdown';
+import Multiselect from '@splunk/react-ui/Multiselect';
+import Select from '@splunk/react-ui/Select';
+import Text from '@splunk/react-ui/Text';
+
+
+function Dialog() {
+    const toggle = <Button label="Open dropdown dialog" isMenu />;
+
+    const closeReasons = without(Dropdown.possibleCloseReasons, 'contentClick');
+
+    return (
+        <Dropdown toggle={toggle} retainFocus closeReasons={closeReasons}>
+            <div style={{ padding: 20, width: 300 }}>
+                <ControlGroup label="First Name">
+                    <Text />
+                </ControlGroup>
+                <ControlGroup
+                    label="Last Name"
+                    controlsLayout="fillJoin"
+                    tooltip="More information..."
+                >
+                    <Text />
+                </ControlGroup>
+                <ControlGroup label="Office">
+                    <Select defaultValue="sf">
+                        <Select.Option label="San Francisco" value="sf" />
+                        <Select.Option label="Cupertino" value="cu" />
+                    </Select>
+                </ControlGroup>
+                <ControlGroup label="Office Multiselect">
+                    <Multiselect defaultValue={['sf']}>
+                        <Multiselect.Option label="San Francisco" value="sf" />
+                        <Multiselect.Option label="Cupertino" value="cu" />
+                    </Multiselect>
+                </ControlGroup>
+            </div>
+        </Dropdown>
+    );
+}
+
+export default Dialog;
+```
+
+
+
+### Toggle with tooltip
+
+```typescript
+import React from 'react';
+
+import ArrowCounterClockwise from '@splunk/react-icons/ArrowCounterClockwise';
+import Button, { ButtonPropsBase } from '@splunk/react-ui/Button';
+import Dropdown from '@splunk/react-ui/Dropdown';
+import Menu from '@splunk/react-ui/Menu';
+import Tooltip from '@splunk/react-ui/Tooltip';
+
+const TooltipButton = React.forwardRef<HTMLButtonElement, ButtonPropsBase>(
+    ({ label, ...otherProps }, ref) => {
+        return (
+            <Tooltip content={label}>
+                <Button {...otherProps} elementRef={ref} />
+            </Tooltip>
+        );
+    }
+);
+
+
+function TooltipButtonToggle() {
+    const tooltipButtonToggle = (
+        <TooltipButton label="direction" icon={<ArrowCounterClockwise />} isMenu />
+    );
+
+    return (
+        <Dropdown toggle={tooltipButtonToggle}>
+            <Menu style={{ width: 120 }}>
+                <Menu.Item>Up</Menu.Item>
+                <Menu.Item>Down</Menu.Item>
+                <Menu.Item>Left</Menu.Item>
+                <Menu.Item>Right</Menu.Item>
+            </Menu>
+        </Dropdown>
+    );
+}
+
+export default TooltipButtonToggle;
+```
+
+
+
+### Customized scroll container
+
+By default, a Dropdown moves with the window scroll. Use Scroll Container Provider when you want a Dropdown to move within a different scroll container.
+
+```typescript
+import React, { useCallback, useState } from 'react';
+
+import Button from '@splunk/react-ui/Button';
+import Dropdown from '@splunk/react-ui/Dropdown';
+import P from '@splunk/react-ui/Paragraph';
+import { ScrollContainerProvider } from '@splunk/react-ui/ScrollContainerContext';
+
+
+function ScrollContainer() {
+    const [scrollContainer, setScrollContainer] = useState<HTMLDivElement>();
+    const scrollContainerRef = useCallback((el: HTMLDivElement) => {
+        setScrollContainer(el);
+    }, []);
+
+    const toggle = <Button label="Open dropdown in scroll container" />;
+    return (
+        <div
+            ref={scrollContainerRef}
+            style={{
+                border: '1px dashed #ccc',
+                height: '100px',
+                width: '500px',
+                margin: '20px 20px 0px 0px',
+                padding: '30px 20px 10px 20px',
+                overflow: 'scroll',
+            }}
+        >
+            <ScrollContainerProvider value={scrollContainer}>
+                <Dropdown retainFocus toggle={toggle}>
+                    <P style={{ padding: 20, maxWidth: 300 }}>
+                        This dropdown moves with the custom scroll container.
+                    </P>
+                </Dropdown>
+                <P style={{ marginTop: 20 }}>More content to demonstrate scrolling.</P>
+                <P>Additional content for demonstration.</P>
+            </ScrollContainerProvider>
+        </div>
+    );
+}
+
+export default ScrollContainer;
+```
+
+
+
+### Controlled
+
+By default, Dropdown handles its own state. If you want more granular control of the events that open or close a Dropdown, use it as a [controlled component](https://reactjs.org/docs/forms.html#controlled-components). When you use Dropdown as a controlled component, the parent component manages the state of the Dropdown. Note that either the Dropdown or its parent handles its state, never both. See the onRequestClose and onRequestOpen callbacks for hooks you can use to manage state. This examples uses toggleClick and offScreen. It receives but ignores all other close actions.
+
+```typescript
+import React, { useState } from 'react';
+
+import Button from '@splunk/react-ui/Button';
+import Dropdown, {
+    DropdownPossibleCloseReason,
+    DropdownRequestCloseHandler,
+} from '@splunk/react-ui/Dropdown';
+import Menu from '@splunk/react-ui/Menu';
+import P from '@splunk/react-ui/Paragraph';
+
+
+function ControlledDropdown() {
+    const [open, setOpen] = useState(false);
+    const [closeReason, setCloseReason] = useState<DropdownPossibleCloseReason>();
+
+    const handleRequestClose: DropdownRequestCloseHandler = ({ reason }) => {
+        setCloseReason(reason);
+        setOpen(!(reason === 'toggleClick' || reason === 'offScreen'));
+    };
+
+    const handleRequestOpen = () => {
+        setOpen(true);
+    };
+
+    const toggle = <Button label="Direction" isMenu />;
+
+    return (
+        <>
+            <P>
+                The last call to onRequestClose provided the reason:{' '}
+                {closeReason ?? 'No close requests yet'}
+            </P>
+            <Dropdown
+                open={open}
+                onRequestClose={handleRequestClose}
+                onRequestOpen={handleRequestOpen}
+                toggle={toggle}
+            >
+                <Menu style={{ width: 120 }}>
+                    <Menu.Item>Up</Menu.Item>
+                    <Menu.Item>Down</Menu.Item>
+                    <Menu.Item>Left</Menu.Item>
+                    <Menu.Item>Right</Menu.Item>
+                </Menu>
+            </Dropdown>
+        </>
+    );
+}
+
+export default ControlledDropdown;
+```
+
+
+
+
+## API
+
+
+### Dropdown API
+
+#### Props
+
+| Name | Type | Required | Default | Description |
+|------|------|------|------|------|
+| canCoverAnchor | boolean | no | true | Enables the `Dropdown` to be rendered over the toggle if there isn't enough room to render it in a direction. |
+| children | React.ReactNode \| DropdownChildrenRenderer | no |  | The content of the `Dropdown`. If a function is provided, it is invoked with an object containing `anchorHeight`, `anchorWidth`, `maxHeight`, `maxWidth`, and `placement`, and is expected to return renderable content. |
+| closeReasons | DropdownPossibleCloseReason[] | no | [     'clickAway',     'contentClick',     'escapeKey',     'offScreen',     'tabKey',     'toggleClick', ] | An array of reasons for which this `Dropdown` closes. |
+| defaultPlacement | DropdownPlacement | no | 'below' | The default placement of the `Dropdown`. It might be rendered in a different direction depending on the space available and the `repositionMode`. |
+| elementRef | React.Ref<HTMLDivElement> | no |  | A React ref which is set to the DOM element when the component mounts and null when it unmounts. |
+| focusToggleReasons | DropdownPossibleCloseReason[] | no | [     'contentClick',     'escapeKey',     'tabKey',     'toggleClick', ] | An array of reasons for which to set focus on the toggle. Only the subset of `closeReasons` is honored. When `Menu.Items` open a Modal or other dialog, it might be necessary to remove the 'contentClick' reason to allow focus to be passed to the dialog. |
+| inputId | string | no |  | An id for the input, which may be necessary for accessibility, such as for aria attributes. |
+| onRequestClose | DropdownRequestCloseHandler | no |  | A callback function invoked with a data object containing the event, if applicable, and a reason for the close request. |
+| onRequestOpen | DropdownRequestOpenHandler | no |  | A callback function invoked with a data object containing the event. |
+| open | boolean | no |  | If an open prop is provided, this component behaves as a [controlled component](https://reactjs.org/docs/forms.html#controlled-components). The consumer is responsible for handling the open/close state. If no open prop is provided, the component handles the open/close state internally. |
+| repositionMode | 'none' \| 'flip' \| 'any' | no | 'flip' | See `repositionMode` on `Popover` for details. |
+| retainFocus | boolean | no | false | Keeps focus within the Popover while open. Only use this for inputs used in a form control. Do not use this when the Dropdown contains a Menu because Menu handles its own focus. |
+| takeFocus | boolean | no | true | When true, the Popover automatically takes focus when 'open' changes to `true`. Disable this for a Popover that has shows on hover, such as a tooltip. |
+| toggle | DropdownToggleElement | yes |  | A toggle, such as a button or equivalent component that accepts `ref`, must be passed. `aria-haspopup`, `aria-expanded`, and `aria-controls` attributes are applied to the toggle to support accessibility. The result of the `ref` placed on the toggle must be an instance of `HTMLElement`. Results that are instances of class components are not supported. Also see ["Forwarding Refs"](https://reactjs.org/docs/forwarding-refs.html). |
+
+#### Types
+
+| Name | Type | Description |
+|------|------|------|
+| DropdownChildrenRenderer | (data: {     anchorHeight: number \| null;     anchorWidth: number \| null;     maxHeight: number \| null;     maxWidth: number \| null;     placement: DropdownPlacementStatus \| null;     toggleId?: string; }) => React.ReactNode |  |
+| DropdownPlacement | 'above' \| 'below' \| 'left' \| 'right' \| 'vertical' \| 'horizontal' |  |
+| DropdownPlacementStatus | 'above' \| 'below' \| 'left' \| 'right' \| 'misaligned' |  |
+| DropdownPossibleCloseReason | \| 'clickAway'     \| 'contentClick'     \| 'escapeKey'     \| 'offScreen'     \| 'tabKey'     \| 'toggleClick' |  |
+| DropdownPossibleOpenReason | 'toggleClick' \| 'toggleKeydown' |  |
+| DropdownRequestCloseHandler | (data: {     event?: React.MouseEvent<HTMLElement> \| MouseEvent \| KeyboardEvent \| TouchEvent;     reason: DropdownPossibleCloseReason; }) => void |  |
+| DropdownRequestOpenHandler | (     event: React.MouseEvent<HTMLElement> \| React.KeyboardEvent<HTMLElement>,     data: { reason: DropdownPossibleOpenReason } ) => void |  |
+| DropdownToggleElement | React.ReactElement<     React.HTMLAttributes<HTMLElement> & {         'data-test-popover-id'?: string;         'data-test'?: string;         ref?: React.Ref<HTMLElement \| null>;     } > |  |
+
+
+
+
+