react-native-tree-multi-select 3.0.0-beta.1 → 3.0.0-beta.3

package/src/types/treeView.types.ts

@@ -14,89 +14,138 @@ import type {
 } from "@futurejj/react-native-checkbox";
 import type { DragEndEvent, DropPosition } from "./dragDrop.types";
 
+/** The tri-state value of a checkbox: checked, unchecked, or indeterminate */
 export type CheckboxValueType = boolean | "indeterminate";
 
+/** Props passed to a custom expand/collapse icon component */
 export interface ExpandIconProps {
+    /** Whether the node is currently expanded */
     isExpanded: boolean;
 }
 
+/** A single node in the tree data structure */
 export interface TreeNode<ID = string> {
+    /** Unique identifier for this node */
     id: ID;
+    /** Display name for this node */
     name: string;
+    /** Child nodes (omit or empty array for leaf nodes) */
     children?: TreeNode<ID>[];
+    /** Additional custom data fields */
     [key: string]: any;
 }
 
+/** Internal flattened representation of a tree node with its nesting level */
 export interface __FlattenedTreeNode__<ID = string> extends TreeNode<ID> {
+    /** Nesting depth of this node (0 = root level) */
     level?: number;
 }
 
-// Remove non-modifiable keys
+/** FlashList props available for customization (excludes `data` and `renderItem`) */
 export type TreeFlatListProps<ItemT = any> = Omit<
     FlashListProps<ItemT>,
     "data"
     | "renderItem"
 >;
 
+/** Props passed to a custom node row component */
 export interface NodeRowProps<ID = string> {
+    /** The tree node to render */
     node: TreeNode<ID>;
+    /** Nesting depth of this node (0 = root level) */
     level: number;
 
+    /** Current checkbox state of this node */
     checkedValue: CheckboxValueType;
+    /** Whether this node's children are currently visible */
     isExpanded: boolean;
 
+    /** Callback to toggle this node's checked state */
     onCheck: () => void;
+    /** Callback to toggle this node's expanded/collapsed state */
     onExpand: () => void;
 
+    /** Whether this node is an invalid drop target during a drag operation */
     isDragTarget?: boolean;
+    /** Whether a drag operation is currently in progress */
     isDragging?: boolean;
+    /** Whether this node is the one being dragged */
     isDraggedNode?: boolean;
 }
 
+/** Customization options for tree item appearance and behavior */
 export interface TreeItemCustomizations<ID> {
+    /** Style props for the built-in checkbox view */
     checkBoxViewStyleProps?: BuiltInCheckBoxViewStyleProps;
 
+    /** Pixels of indentation per nesting level. Default: 15 */
     indentationMultiplier?: number;
 
+    /** Custom checkbox component replacing the built-in checkbox */
     CheckboxComponent?: React.ComponentType<CheckBoxViewProps>;
+    /** Custom expand/collapse icon component */
     ExpandCollapseIconComponent?: React.ComponentType<ExpandIconProps>;
+    /** Custom touchable component wrapping the expand/collapse icon */
     ExpandCollapseTouchableComponent?: React.ComponentType<TouchableOpacityProps>;
 
+    /** Fully custom node row component replacing the entire built-in row */
     CustomNodeRowComponent?: React.ComponentType<NodeRowProps<ID>>;
 }
 
+/** Internal props for a single node in the list (extends TreeItemCustomizations) */
 export interface NodeProps<ID> extends TreeItemCustomizations<ID> {
+    /** The flattened tree node data */
     node: __FlattenedTreeNode__<ID>;
+    /** Nesting depth of this node */
     level: number;
+    /** Internal store identifier */
     storeId: string;
 
+    /** Index of this node in the flattened list */
     nodeIndex?: number;
+    /** Whether drag-and-drop is enabled */
     dragEnabled?: boolean;
+    /** Whether a drag operation is currently in progress */
     isDragging?: boolean;
+    /** Callback when a touch starts on this node (used for drag initiation) */
     onNodeTouchStart?: (
         nodeId: ID,
         pageY: number,
         locationY: number,
         nodeIndex: number
     ) => void;
+    /** Callback when a touch ends on this node */
     onNodeTouchEnd?: () => void;
+    /** Long press duration in ms to start drag */
     longPressDuration?: number;
+    /** Callback reporting this node's measured height */
     onItemLayout?: (height: number) => void;
+    /** Customizations for drag-and-drop visuals */
     dragDropCustomizations?: DragDropCustomizations<ID>;
 }
 
+/** Props for the NodeList component that renders the flattened tree */
 export interface NodeListProps<ID> extends TreeItemCustomizations<ID> {
+    /** Additional props passed to the underlying FlashList */
     treeFlashListProps?: TreeFlatListProps;
 
+    /** Ref for programmatic scroll-to-node functionality */
     scrollToNodeHandlerRef: React.RefObject<ScrollToNodeHandlerRef<ID>>;
+    /** Node ID to scroll to on initial render */
     initialScrollNodeID?: ID;
 
+    /** Internal store identifier */
     storeId: string;
 
+    /** Enable drag-and-drop reordering */
     dragEnabled?: boolean;
+    /** Callback fired after a node is dropped at a new position */
     onDragEnd?: (event: DragEndEvent<ID>) => void;
+    /** Long press duration in ms to start drag. Default: 400 */
     longPressDuration?: number;
+    /** Distance from edge (px) to trigger auto-scroll during drag. Default: 60 */
     autoScrollThreshold?: number;
+    /** Speed multiplier for auto-scroll during drag. Default: 1.0 */
     autoScrollSpeed?: number;
     /** Offset of the dragged overlay from the finger, in item-height units. Default: -1 (one item above finger) */
     dragOverlayOffset?: number;
@@ -106,18 +155,25 @@ export interface NodeListProps<ID> extends TreeItemCustomizations<ID> {
     dragDropCustomizations?: DragDropCustomizations<ID>;
 }
 
+/** Props for the TreeView component */
 export interface TreeViewProps<ID = string> extends Omit<
     NodeListProps<ID>, "storeId" | "scrollToNodeHandlerRef"
 > {
+    /** The tree data to render */
     data: TreeNode<ID>[];
 
+    /** Callback fired when checked nodes change. Receives checked and indeterminate node IDs. */
     onCheck?: (checkedIds: ID[], indeterminateIds: ID[]) => void;
+    /** Callback fired when expanded nodes change. Receives all currently expanded node IDs. */
     onExpand?: (expandedIds: ID[]) => void;
 
+    /** Node IDs that should be checked on initial render */
     preselectedIds?: ID[];
 
+    /** Node IDs that should be expanded on initial render */
     preExpandedIds?: ID[];
 
+    /** Controls whether checking a node propagates to its children and/or parents */
     selectionPropagation?: SelectionPropagation;
 
     /** Enable drag-and-drop reordering */
@@ -126,9 +182,9 @@ export interface TreeViewProps<ID = string> extends Omit<
     onDragEnd?: (event: DragEndEvent<ID>) => void;
     /** Long press duration in ms to start drag. Default: 400 */
     longPressDuration?: number;
-    /** Distance from edge (px) to trigger auto-scroll. Default: 60 */
+    /** Distance from edge (px) to trigger auto-scroll during drag. Default: 60 */
     autoScrollThreshold?: number;
-    /** Speed multiplier for auto-scroll. Default: 1.0 */
+    /** Speed multiplier for auto-scroll during drag. Default: 1.0 */
     autoScrollSpeed?: number;
     /** Offset of the dragged overlay from the finger, in item-height units. Default: -1 (one item above finger) */
     dragOverlayOffset?: number;
@@ -138,53 +194,80 @@ export interface TreeViewProps<ID = string> extends Omit<
 
 type CheckboxProps = Omit<_CheckboxProps, "onPress" | "status">;
 
+/** Props for the checkbox view component */
 export interface CheckBoxViewProps {
+    /** Current checkbox state */
     value: CheckboxValueType;
+    /** Callback when the checkbox value changes */
     onValueChange: (value: boolean) => void;
+    /** Label text displayed next to the checkbox */
     text: string;
+    /** Test ID for testing frameworks */
     testID?: string;
 }
 
+/** Style props for customizing the built-in checkbox view */
 export interface BuiltInCheckBoxViewStyleProps {
-    // Optional style modifiers
+    /** Style for the outermost container wrapping the checkbox and text */
     outermostParentViewStyle?: StyleProp<ViewStyle>;
+    /** Style for the view wrapping the checkbox itself */
     checkboxParentViewStyle?: StyleProp<ViewStyle>;
+    /** Style for the touchable area wrapping the label text */
     textTouchableStyle?: StyleProp<ViewStyle>;
 
-    // Optional checkbox and text component props
+    /** Additional props passed to the underlying Checkbox component */
     checkboxProps?: CheckboxProps;
+    /** Props passed to the label Text component */
     textProps?: TextProps;
 }
 
+/** Combined props for the built-in checkbox view (CheckBoxViewProps + style props) */
 export type BuiltInCheckBoxViewProps =
     CheckBoxViewProps
     & BuiltInCheckBoxViewStyleProps;
 
+/** Ref handle exposed by the TreeView component for imperative operations */
 export interface TreeViewRef<ID = string> {
+    /** Select (check) all nodes in the tree */
     selectAll: () => void;
+    /** Unselect (uncheck) all nodes in the tree */
     unselectAll: () => void;
 
+    /** Select all nodes that match the current search filter */
     selectAllFiltered: () => void;
+    /** Unselect all nodes that match the current search filter */
     unselectAllFiltered: () => void;
 
+    /** Expand all nodes in the tree */
     expandAll: () => void;
+    /** Collapse all nodes in the tree */
     collapseAll: () => void;
 
+    /** Expand specific nodes by their IDs */
     expandNodes: (ids: ID[]) => void;
+    /** Collapse specific nodes by their IDs */
     collapseNodes: (ids: ID[]) => void;
 
+    /** Select (check) specific nodes by their IDs */
     selectNodes: (ids: ID[]) => void;
+    /** Unselect (uncheck) specific nodes by their IDs */
     unselectNodes: (ids: ID[]) => void;
 
+    /** Set the search text and optionally specify which node fields to search */
     setSearchText: (searchText: string, searchKeys?: string[]) => void;
 
+    /** Programmatically scroll to a specific node by its ID */
     scrollToNodeID: (scrollToNodeParams: ScrollToNodeParams<ID>) => void;
 
+    /** Get a map of child node IDs to their parent node IDs */
     getChildToParentMap: () => Map<ID, ID>;
 }
 
+/** Controls how checkbox selection propagates through the tree hierarchy */
 export interface SelectionPropagation {
+    /** Whether checking a parent node automatically checks all its children. Default: true */
     toChildren?: boolean;
+    /** Whether checking all children automatically checks their parent. Default: true */
     toParents?: boolean;
 }
 
@@ -194,6 +277,10 @@ export interface SelectionPropagation {
 export interface DropIndicatorComponentProps {
     /** Whether the indicator is above, below, or inside the target node */
     position: DropPosition;
+    /** The nesting level of the target node (useful for indenting the indicator) */
+    level: number;
+    /** The indentation multiplier used for each level (pixels per level) */
+    indentationMultiplier: number;
 }
 
 /** Style props for customizing the built-in drop indicator appearance */
@@ -234,9 +321,9 @@ export interface DragDropCustomizations<ID = string> {
     dropIndicatorStyleProps?: DropIndicatorStyleProps;
     /** Style props for the drag overlay (lifted node ghost) */
     dragOverlayStyleProps?: DragOverlayStyleProps;
-    /** Fully custom drop indicator component — replaces the built-in line/highlight */
+    /** Fully custom drop indicator component - replaces the built-in line/highlight */
     CustomDropIndicatorComponent?: React.ComponentType<DropIndicatorComponentProps>;
-    /** Fully custom drag overlay component — replaces the built-in ghost node */
+    /** Fully custom drag overlay component - replaces the built-in ghost node */
     CustomDragOverlayComponent?: React.ComponentType<DragOverlayComponentProps<ID>>;
 }