@splunk/react-ui 4.46.0 → 4.47.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@splunk/react-ui",
-  "version": "4.46.0",
+  "version": "4.47.1",
   "description": "Library of React components that implement the Splunk design language",
   "license": "Apache-2.0",
   "author": "Splunk Inc.",

package/types/src/JSONTree/JSONTreeItem.d.ts

@@ -3,7 +3,10 @@ import PropTypes from 'prop-types';
 import { JSONElement } from './JSONTree';
 import { TreeItemPropsBase } from '../Tree';
 import { ComponentProps } from '../utils/types';
-export type ExpandLinkHandler = (data: {
+export type ExpandLinkRenderer = (params: {
+    onToggleExpansion: (event: React.KeyboardEvent<HTMLLIElement> | React.MouseEvent<HTMLSpanElement>, data?: {
+        treeItemId?: string;
+    }) => void;
     open: boolean;
     withTooltip: boolean;
     expandLinkRef: React.RefObject<HTMLButtonElement>;
@@ -17,15 +20,16 @@ interface JSONTreeItemPropsBase extends TreeItemPropsBase {
     indentArray?: string[];
     index: number;
     initialOpenState: boolean;
+    isRoot?: boolean;
     properties?: string[];
     propertyDataPath: string;
     propertyElement?: JSX.Element | undefined;
-    renderExpandLink?: ExpandLinkHandler;
+    renderExpandLink?: ExpandLinkRenderer;
     representation?: JSX.Element | JSX.Element[];
     value?: JSONElement;
 }
 type JSONTreeItemProps = ComponentProps<JSONTreeItemPropsBase, 'li'>;
-export declare function JSONTreeItem({ clickableKeyRef, clickableValRef, hasChildren, indentArray, index, initialOpenState, onFocus, properties, propertyDataPath, propertyElement, renderExpandLink, representation, value, ...otherProps }: JSONTreeItemProps): JSX.Element;
+export declare function JSONTreeItem({ clickableKeyRef, clickableValRef, hasChildren, indentArray, index, initialOpenState, isRoot, onFocus, properties, propertyDataPath, propertyElement, renderExpandLink, representation, value, ...otherProps }: JSONTreeItemProps): JSX.Element;
 export declare namespace JSONTreeItem {
     var propTypes: {
         clickableKeyRef: PropTypes.Requireable<object>;
@@ -34,6 +38,7 @@ export declare namespace JSONTreeItem {
         indentArray: PropTypes.Requireable<(string | null | undefined)[]>;
         index: PropTypes.Requireable<number>;
         initialOpenState: PropTypes.Requireable<boolean>;
+        isRoot: PropTypes.Requireable<boolean>;
         properties: PropTypes.Requireable<(string | null | undefined)[]>;
         propertyDataPath: PropTypes.Requireable<string>;
         propertyElement: PropTypes.Requireable<PropTypes.ReactNodeLike>;

package/types/src/JSONTree/renderTreeItems.d.ts

@@ -1,5 +1,6 @@
 import { JSONElement, JSONTreeClickKeyHandler, JSONTreeClickValueHandler } from './JSONTree';
 type RenderTreeItemsProps = {
+    baseId: string;
     defaultOpen?: boolean;
     expandChildren?: boolean | 'withShiftModifier';
     expandChildrenOnShiftKey?: boolean;
@@ -13,5 +14,5 @@ type RenderTreeItemsProps = {
     shift?: boolean;
     updateShift: ((newShift: boolean) => void) | undefined;
 };
-export declare function renderTreeItems({ defaultOpen, expandChildren, expandChildrenOnShiftKey, indent, indentLevel, obj, onClickKey, onClickValue, overflow, path, shift, updateShift, }: RenderTreeItemsProps): JSX.Element | JSX.Element[];
+export declare function renderTreeItems({ baseId, defaultOpen, expandChildren, expandChildrenOnShiftKey, indent, indentLevel, obj, onClickKey, onClickValue, overflow, path, shift, updateShift, }: RenderTreeItemsProps): JSX.Element | JSX.Element[];
 export {};

package/types/src/Tree/Item.d.ts

@@ -4,41 +4,60 @@ import { ComponentProps } from '../utils/types';
 interface TreeItemPropsBase {
     /** A unique `id` for this item and used by `Tree` to keep track of the focused item. */
     id: string;
-    /** Should contain `TreeItems`, can also include other elements to display in between tree items. */
+    /** Should contain `Tree.Item`s, can also include other elements to display in between tree items. */
     children?: React.ReactNode;
-    /** Content to show on the TreeItem. */
+    /** Content to show on the `Tree.Item`. */
     content?: React.ReactNode;
-    /** Custom indent to show before TreeItem content. */
+    /**
+     * @private Custom indent to show before `Tree.Item` content.
+     */
     customIndent?: React.ReactNode;
+    /**
+     * A React ref which is set to the DOM element when the component mounts and null when it unmounts.
+     */
+    elementRef?: React.Ref<HTMLLIElement>;
+    /**
+     * @private Used only by JSONTree - artifact from before Tree was public.
+     * Conventional `endAdornment` in all other cases would instead be just done by including the desired element in `content`.
+     * Left in for JSONTree because the need to support the endAdornment conditionally going to the end of the unordered list of children in the expanded view.
+     * This is required in JSONTree to handle closing bracket/braces but does not have a known use case for other Tree uses.
+     */
     endAdornment?: React.ReactNode;
-    labelledBy?: string;
+    /** Expansion state of the `Tree.Item`. */
+    expanded?: boolean;
     onFocus?: React.FocusEventHandler<HTMLLIElement>;
     onKeyDown?: React.KeyboardEventHandler<HTMLLIElement>;
-    onToggle?: TreeItemToggleHandler;
-    /** Default open state of the node. */
-    open?: boolean;
-    /** Toggle to pass that opens/closes the node on click. */
-    toggle?: React.ReactElement;
+    /** Called on expansion state change of the `Tree.Item` and should be used to maintain `expanded`. For proper keyboard accessibility this is required when a `Tree.Item` has children. */
+    onToggleExpansion?: TreeItemToggleExpansionHandler;
+    /** Called on selection state change of the `Tree.Item` and can be used to maintain optional external `Tree.Item` selection state. */
+    onToggleSelection?: TreeItemToggleSelectionHandler;
 }
 type TreeItemProps = ComponentProps<TreeItemPropsBase, 'li'>;
 type TreeItemClickHandler = (event: React.MouseEvent<HTMLSpanElement>, id: string) => void;
-type TreeItemKeyDownHandler = (event: React.KeyboardEvent<HTMLLIElement>, id: string, showChildren: boolean | undefined, childrenCleaned: React.ReactElement[] | undefined | null, handleToggle: TreeItemToggleHandler) => void;
-type TreeItemToggleHandler = (isOpen: boolean, event?: React.KeyboardEvent<HTMLLIElement> | React.MouseEvent<HTMLSpanElement>) => void;
-declare function Item({ id, children, content, customIndent, endAdornment, labelledBy, onFocus, onKeyDown, onToggle, open, toggle, ...otherProps }: TreeItemProps): JSX.Element;
+type TreeItemKeyDownHandler = (event: React.KeyboardEvent<HTMLLIElement>, id: string, isExpanded: boolean | undefined, childrenCleaned: React.ReactElement[] | undefined | null, handleToggleExpansion: TreeItemToggleExpansionHandler) => void;
+/** @public */
+type TreeItemToggleExpansionHandler = (event: React.KeyboardEvent<HTMLLIElement> | React.MouseEvent<HTMLSpanElement>, data?: {
+    treeItemId?: string;
+}) => void;
+/** @public */
+type TreeItemToggleSelectionHandler = (event: React.KeyboardEvent<HTMLLIElement> | React.MouseEvent<HTMLSpanElement>, data?: {
+    treeItemId?: string;
+}) => void;
+declare function Item({ id, children, content, customIndent, elementRef, endAdornment, expanded, onFocus, onKeyDown, onToggleExpansion, onToggleSelection, ...otherProps }: TreeItemProps): JSX.Element;
 declare namespace Item {
     var propTypes: {
         id: PropTypes.Requireable<string>;
         children: PropTypes.Requireable<PropTypes.ReactNodeLike>;
         content: PropTypes.Requireable<PropTypes.ReactNodeLike>;
         customIndent: PropTypes.Requireable<PropTypes.ReactNodeLike>;
+        elementRef: PropTypes.Requireable<object>;
         endAdornment: PropTypes.Requireable<PropTypes.ReactNodeLike>;
-        labelledBy: PropTypes.Requireable<string>;
+        expanded: PropTypes.Requireable<boolean>;
         onFocus: PropTypes.Requireable<(...args: any[]) => any>;
         onKeyDown: PropTypes.Requireable<(...args: any[]) => any>;
-        onToggle: PropTypes.Requireable<(...args: any[]) => any>;
-        open: PropTypes.Requireable<boolean>;
-        toggle: PropTypes.Requireable<PropTypes.ReactNodeLike>;
+        onToggleSelection: PropTypes.Requireable<(...args: any[]) => any>;
+        onToggleExpansion: PropTypes.Requireable<(...args: any[]) => any>;
     };
 }
 export default Item;
-export { TreeItemClickHandler, TreeItemKeyDownHandler, TreeItemPropsBase, TreeItemToggleHandler };
+export { TreeItemClickHandler, TreeItemKeyDownHandler, TreeItemPropsBase, TreeItemToggleExpansionHandler, TreeItemToggleSelectionHandler, };

package/types/src/Tree/Tree.d.ts

@@ -5,17 +5,25 @@ import Item from './Item';
 type RemoveNodeHandler = (id: string) => void;
 type SetNodeHandler = (id: string, path?: string) => void;
 interface TreePropsBase {
-    /** Should contain TreeItems, can also include other elements to display in between tree items. */
+    /** Should contain `Tree.Item`s, can also include other elements to display in between tree items. */
     children?: React.ReactNode;
     /** Removes default indent from list styles if set to false. */
     defaultIndent?: boolean;
+    /**
+     * A React ref which is set to the DOM element when the component mounts and null when it unmounts.
+     */
+    elementRef?: React.Ref<HTMLUListElement>;
 }
 type TreeProps = ComponentProps<TreePropsBase, 'ul'>;
-declare function Tree({ children, defaultIndent, ...otherProps }: TreeProps): JSX.Element;
+/**
+ * Used to present a hierarchical list.
+ */
+declare function Tree({ children, defaultIndent, elementRef, ...otherProps }: TreeProps): JSX.Element;
 declare namespace Tree {
     var propTypes: {
         children: PropTypes.Requireable<PropTypes.ReactNodeLike>;
         defaultIndent: PropTypes.Requireable<boolean>;
+        elementRef: PropTypes.Requireable<object>;
     };
     var Item: typeof import("./Item").default;
 }

package/types/src/Tree/docs/examples/Basic.d.ts

@@ -0,0 +1 @@
+export default function Basic(): JSX.Element;

package/types/src/Tree/docs/examples/ClickableExpansion.d.ts

@@ -0,0 +1 @@
+export default function ClickableExpansion(): JSX.Element;

package/types/src/Tree/docs/examples/ClickableExpansionWithSelection.d.ts

@@ -0,0 +1 @@
+export default function ClickableExpansionWithSelection(): JSX.Element;