@tap-payments/os-micro-frontend-shared 0.3.255 → 0.3.256

package/src/components/TreeDropdown/README.md

@@ -1,604 +0,0 @@
-# TreeDropdown Component
-
-A powerful, flexible tree dropdown component for React that supports hierarchical data structures with multi-select, single-select, search functionality, and customizable rendering.
-
-## Overview
-
-The `TreeDropdown` component provides a nested menu structure that can display hierarchical data in a dropdown format. It supports both single and multiple selection modes, includes built-in search capabilities, and allows for extensive customization through props and render functions.
-
-## Features
-
-- 🌳 **Hierarchical Tree Structure**: Display nested data with unlimited depth
-- ✅ **Multiple Selection Modes**: Support for both single and multiple selection
-- 🔍 **Built-in Search**: Filter tree items with debounced search — simple field matching via `getValues`, or custom matching with subtree pruning via `filterItem`
-- 🎨 **Customizable Rendering**: Custom render functions for items, headers, and footers
-- 📦 **State Management**: Automatic state management with parent-child relationship handling
-- 🎯 **Indeterminate States**: Visual indication for partially selected parent nodes
-- 🔄 **Auto-promotion**: Automatically promotes single-child nodes to reduce nesting
-- 🎭 **Icon Support**: Built-in support for icons and custom icon components
-- 📱 **Responsive**: Works with Material-UI's Popper for positioning
-- 📊 **Level-based Queries**: Get selected nodes grouped by tree level with filtering options
-
-## Installation
-
-The component is part of the shared components library. Import it as follows:
-
-```typescript
-import TreeDropdown from '@components/TreeDropdown'
-import type { TreeDropdownProps, TreeDropdownRef, TreeNode, TreeDefinition, SelectedState } from '@components/TreeDropdown'
-
-// Optional: Import GetNodesByLevelOptions if you need to type variables
-// import type { GetNodesByLevelOptions } from '@components/TreeDropdown/utils'
-```
-
-## Basic Usage
-
-```tsx
-import { useState, useRef } from 'react'
-import { Button } from '@mui/material'
-import TreeDropdown from '@components/TreeDropdown'
-import type { TreeDropdownRef, TreeDefinition } from '@components/TreeDropdown'
-
-const MyComponent = () => {
-  const [anchorEl, setAnchorEl] = useState<HTMLElement | null>(null)
-  const treeRef = useRef<TreeDropdownRef>(null)
-
-  const treeDefinition: TreeDefinition = {
-    children: [
-      {
-        id: '1',
-        label: 'Category 1',
-        children: [
-          {
-            id: '1-1',
-            label: 'Subcategory 1',
-            children: [
-              { id: '1-1-1', label: 'Item 1' },
-              { id: '1-1-2', label: 'Item 2' },
-            ],
-          },
-        ],
-      },
-    ],
-  }
-
-  return (
-    <>
-      <Button onClick={(e) => setAnchorEl(e.currentTarget)}>Open Tree</Button>
-      <TreeDropdown
-        ref={treeRef}
-        anchorEl={anchorEl}
-        treeDefinition={treeDefinition}
-        multiple={true}
-        onChange={(tree) => console.log('Selected:', tree)}
-      />
-    </>
-  )
-}
-```
-
-## Props
-
-### TreeDropdownProps
-
-| Prop                     | Type                                                                                           | Default          | Description                                                                                 |
-| ------------------------ | ---------------------------------------------------------------------------------------------- | ---------------- | ------------------------------------------------------------------------------------------- |
-| `anchorEl`               | `HTMLElement \| null`                                                                          | **Required**     | The element that the dropdown will anchor to                                                |
-| `treeDefinition`         | `TreeDefinition`                                                                               | **Required**     | The tree structure definition                                                               |
-| `onChange`               | `(tree: TreeNode[]) => void`                                                                   | `undefined`      | Callback fired when selection changes                                                       |
-| `multiple`               | `boolean`                                                                                      | `true`           | Enable multiple selection mode                                                              |
-| `placement`              | `PopperProps['placement']`                                                                     | `'bottom-start'` | Placement of the dropdown relative to anchor                                                |
-| `sx`                     | `SxProps<Theme>`                                                                               | `undefined`      | Material-UI sx prop for styling                                                             |
-| `IconComponent`          | `React.ComponentType<{ fileId: string; width?: number \| string; height?: number \| string }>` | `undefined`      | Custom component for rendering icons                                                        |
-| `exposeOnlySelectedTree` | `boolean`                                                                                      | `false`          | When `true`, `onChange` callback receives only selected branches instead of the entire tree |
-
-## Types
-
-### TreeNode
-
-The basic node structure in the tree:
-
-```typescript
-type TreeNode = {
-  id: string // Unique identifier (required)
-  label?: React.ReactNode // Display label
-  hintText?: React.ReactNode // Additional hint text below label
-  icon?: TreeNodeIcon // Icon definition
-  iconComponent?: React.ReactNode // Custom icon component
-  itemProps?: MenuItemProps // Props passed to underlying MenuItem
-  renderItem?: (params: {
-    nodeProps: TreeNode
-    checked?: boolean
-    indeterminate?: boolean
-    onSelect: (e: React.ChangeEvent<HTMLInputElement>) => void
-  }) => React.ReactNode // Custom render function
-} & TreeDefinition // Note: status is part of TreeDefinition, not directly on TreeNode
-```
-
-### TreeDefinition
-
-Configuration for the tree structure:
-
-```typescript
-type TreeDefinition = {
-  header?: React.ReactNode // Header content for this level
-  footer?: React.ReactNode // Footer content for this level
-  levelKey?: string // Unique key for this level (appears as data attribute)
-  searchProps?: {
-    getValues?: (item: TreeNode) => string[] // Simple filtering: strings to match against (case-insensitive `includes`)
-    filterItem?: (item: TreeNode, searchText: string) => TreeNode | null // Advanced: keep/drop AND reshape a node
-    onChange?: (e: React.ChangeEvent<HTMLInputElement>) => void
-    noResultsText?: React.ReactNode
-    inputProps?: InputProps
-  }
-  children?: TreeNode[] // Child nodes
-  disablePromotion?: boolean // Disable auto-promotion of single children
-  status?: SelectedState // Initial selection state for this level
-}
-```
-
-### TreeDropdownRef
-
-Methods exposed via the ref:
-
-```typescript
-type TreeDropdownRef = {
-  internalMapper: TreeMapper // Internal state mapper
-  getTree: () => TreeNode[] // Get the entire tree with current states
-  getSelectedBranches: () => TreeNode[] // Get only selected branches
-  getSelectedNodesByLevel: (options?: GetNodesByLevelOptions) => Record<number, TreeNode[]> // Get selected nodes grouped by level
-}
-```
-
-### GetNodesByLevelOptions
-
-Options for the `getSelectedNodesByLevel` method:
-
-```typescript
-type GetNodesByLevelOptions = {
-  filter?: (node: TreeNode) => boolean // Optional filter function to include/exclude nodes
-  includeChildren?: boolean // When true, includes children in the result; when false, excludes them (default: false)
-}
-```
-
-### SelectedState
-
-Enumeration of selection states:
-
-```typescript
-enum SelectedState {
-  CHECKED = 'CHECKED',
-  UNCHECKED = 'UNCHECKED',
-  INDETERMINATE = 'INDETERMINATE',
-}
-```
-
-## Usage Examples
-
-### Single Selection Mode
-
-```tsx
-<TreeDropdown
-  anchorEl={anchorEl}
-  treeDefinition={treeDefinition}
-  multiple={false}
-  onChange={(tree) => {
-    // Only one item can be selected at a time
-    console.log('Selected:', tree)
-  }}
-/>
-```
-
-### With Search
-
-A level renders a search input whenever its `searchProps` is set. Matching is driven by one of two mutually exclusive hooks:
-
-#### `getValues` — simple field matching
-
-Return the strings a node should be matched against. The component does the matching for you (case-insensitive `includes`) and keeps or drops each item unchanged.
-
-```tsx
-const treeDefinition: TreeDefinition = {
-  searchProps: {
-    getValues: (item) => [typeof item.label === 'string' ? item.label : '', typeof item.hintText === 'string' ? item.hintText : ''],
-    noResultsText: 'No items found',
-    inputProps: {
-      placeholder: 'Search items...',
-    },
-  },
-  children: [
-    /* ... */
-  ],
-}
-```
-
-#### `filterItem` — custom matching + subtree pruning
-
-Use `filterItem` when you need custom match logic, or when a match on a parent should show only the matching branches underneath it. You receive the node and the (already lowercased) search text, and return:
-
-- the node (optionally with a **modified `children`** array) to keep it, or
-- `null` to drop it.
-
-`filterItem` takes precedence over `getValues` when both are provided.
-
-```tsx
-// Keep a node if its label matches; otherwise prune its subtree down to
-// only the branches that lead to a matching leaf.
-const pruneToMatch = (node: TreeNode, text: string): TreeNode | null => {
-  if (!node.children?.length) {
-    return node.id.toLowerCase().includes(text) ? node : null
-  }
-  const children = node.children.map((c) => pruneToMatch(c, text)).filter(Boolean) as TreeNode[]
-  return children.length ? { ...node, children } : null
-}
-
-const treeDefinition: TreeDefinition = {
-  searchProps: {
-    filterItem: (item, searchText) => {
-      const label = typeof item.label === 'string' ? item.label.toLowerCase() : ''
-      if (label.includes(searchText)) return item // parent match → keep whole subtree
-      return pruneToMatch(item, searchText) // otherwise → keep only matching branches
-    },
-    noResultsText: 'No items found',
-  },
-  children: [
-    /* ... */
-  ],
-}
-```
-
-> **Tip:** When pruning, consider stripping `searchProps` from levels that no longer exceed your "show search" threshold, so a search box isn't rendered over a single remaining result.
-
-### With Headers and Footers
-
-```tsx
-const treeDefinition: TreeDefinition = {
-  header: <div>Category Header</div>,
-  footer: <div>Category Footer</div>,
-  children: [
-    {
-      id: '1',
-      label: 'Category 1',
-      header: <div>Subcategory Header</div>,
-      footer: <div>Subcategory Footer</div>,
-      children: [
-        /* ... */
-      ],
-    },
-  ],
-}
-```
-
-### With Icons
-
-```tsx
-// Using icon property
-const treeDefinition: TreeDefinition = {
-  children: [
-    {
-      id: '1',
-      label: 'Item with Icon',
-      icon: {
-        fileId: 'icon-id',
-        width: 20,
-        height: 20,
-      },
-    },
-  ],
-}
-
-// With custom IconComponent
-<TreeDropdown
-  anchorEl={anchorEl}
-  treeDefinition={treeDefinition}
-  IconComponent={({ fileId, width, height }) => (
-    <img src={`/icons/${fileId}.svg`} width={width} height={height} />
-  )}
-/>
-```
-
-### Custom Item Rendering
-
-```tsx
-const treeDefinition: TreeDefinition = {
-  children: [
-    {
-      id: '1',
-      label: 'Custom Item',
-      renderItem: ({ nodeProps, checked, indeterminate, onSelect }) => (
-        <div style={{ padding: '8px' }}>
-          <input type="checkbox" checked={checked} onChange={onSelect} />
-          <span>{nodeProps.label}</span>
-          {indeterminate && <span> (partial)</span>}
-        </div>
-      ),
-    },
-  ],
-}
-```
-
-### Using Ref Methods
-
-```tsx
-const treeRef = useRef<TreeDropdownRef>(null)
-
-// Get entire tree with current states
-const handleGetTree = () => {
-  const tree = treeRef.current?.getTree()
-  console.log('Full tree:', tree)
-}
-
-// Get only selected branches
-const handleGetSelected = () => {
-  const selected = treeRef.current?.getSelectedBranches()
-  console.log('Selected branches:', selected)
-}
-
-// Get selected nodes grouped by level
-const handleGetByLevel = () => {
-  const nodesByLevel = treeRef.current?.getSelectedNodesByLevel({
-    filter: (node) => node.status === SelectedState.CHECKED, // Only fully checked nodes
-    includeChildren: false, // Exclude children from the result
-  })
-  console.log('Nodes by level:', nodesByLevel)
-  // Result: { 0: [TreeNode, ...], 1: [TreeNode, ...], ... }
-}
-
-;<TreeDropdown ref={treeRef} anchorEl={anchorEl} treeDefinition={treeDefinition} />
-```
-
-### Get Selected Nodes by Level
-
-The `getSelectedNodesByLevel` method allows you to retrieve selected nodes grouped by their depth level in the tree:
-
-```tsx
-const treeRef = useRef<TreeDropdownRef>(null)
-
-// Get all selected nodes grouped by level
-const handleGetByLevel = () => {
-  const nodesByLevel = treeRef.current?.getSelectedNodesByLevel()
-  // Result: { 0: [TreeNode, ...], 1: [TreeNode, ...], 2: [TreeNode, ...] }
-  console.log('Level 0 nodes:', nodesByLevel?.[0])
-  console.log('Level 1 nodes:', nodesByLevel?.[1])
-}
-
-// With filtering - only get fully checked nodes
-const handleGetCheckedByLevel = () => {
-  const nodesByLevel = treeRef.current?.getSelectedNodesByLevel({
-    filter: (node) => node.status === SelectedState.CHECKED,
-  })
-  console.log('Fully checked nodes by level:', nodesByLevel)
-}
-
-// Include children in the result
-const handleGetWithChildren = () => {
-  const nodesByLevel = treeRef.current?.getSelectedNodesByLevel({
-    includeChildren: true, // Include children in each node
-  })
-  console.log('Nodes with children:', nodesByLevel)
-}
-
-// Exclude children (default behavior)
-const handleGetWithoutChildren = () => {
-  const nodesByLevel = treeRef.current?.getSelectedNodesByLevel({
-    includeChildren: false, // Exclude children (default)
-  })
-  // Each node in the result will not have its children property
-  console.log('Nodes without children:', nodesByLevel)
-}
-```
-
-**Use Cases:**
-
-- Display selected items grouped by category level
-- Validate selections at specific tree levels
-- Process selections level by level
-- Filter and transform selected data by depth
-
-### With Level Keys
-
-Level keys are useful for styling or testing specific levels:
-
-```tsx
-const treeDefinition: TreeDefinition = {
-  levelKey: 'category',
-  children: [
-    {
-      id: '1',
-      label: 'Category 1',
-      levelKey: 'subcategory',
-      children: [
-        {
-          id: '1-1',
-          label: 'Item',
-          levelKey: 'item',
-        },
-      ],
-    },
-  ],
-}
-
-// Results in data attributes:
-// <div data-level-key="category">...</div>
-// <div data-level-key="subcategory">...</div>
-// <div data-level-key="item">...</div>
-```
-
-### Pre-selected Items
-
-You can pre-select items by setting the `status` property in the `TreeDefinition`:
-
-```tsx
-import { SelectedState } from '@components/TreeDropdown'
-
-const treeDefinition: TreeDefinition = {
-  status: SelectedState.CHECKED, // Pre-select at the root level
-  children: [
-    {
-      id: '1',
-      label: 'Pre-selected Item',
-      status: SelectedState.CHECKED, // Pre-select this node
-      children: [
-        {
-          id: '1-1',
-          label: 'Child Item',
-          status: SelectedState.CHECKED, // Pre-select this child
-        },
-      ],
-    },
-  ],
-}
-```
-
-**Note**: The `status` property is part of `TreeDefinition`, so it can be set at any level of the tree hierarchy.
-
-### Expose Only Selected Tree
-
-When `exposeOnlySelectedTree` is `true`, the `onChange` callback receives only the selected branches instead of the entire tree. This is useful when you only need to work with selected items:
-
-```tsx
-// With exposeOnlySelectedTree = false (default)
-// onChange receives the entire tree with all nodes and their states
-<TreeDropdown
-  anchorEl={anchorEl}
-  treeDefinition={treeDefinition}
-  onChange={(tree) => {
-    // tree contains ALL nodes, with their selection states
-    console.log('Full tree:', tree)
-  }}
-/>
-
-// With exposeOnlySelectedTree = true
-// onChange receives only the selected branches
-<TreeDropdown
-  anchorEl={anchorEl}
-  treeDefinition={treeDefinition}
-  exposeOnlySelectedTree={true}
-  onChange={(selectedBranches) => {
-    // selectedBranches contains ONLY selected nodes and their selected children
-    // Unselected branches are filtered out
-    console.log('Selected branches only:', selectedBranches)
-  }}
-/>
-```
-
-**Note**: The `getSelectedBranches()` method on the ref always returns only selected branches, regardless of this prop setting.
-
-## Advanced Features
-
-### Auto-Promotion
-
-The component automatically promotes single-child nodes to reduce unnecessary nesting. If a node has exactly one child and that child has children, the intermediate level is skipped.
-
-To disable this behavior:
-
-```tsx
-const treeDefinition: TreeDefinition = {
-  children: [
-    {
-      id: '1',
-      label: 'Parent',
-      disablePromotion: true, // Disable promotion for this node
-      children: [
-        {
-          id: '1-1',
-          label: 'Only Child',
-          children: [
-            /* ... */
-          ],
-        },
-      ],
-    },
-  ],
-}
-```
-
-### Styling
-
-Customize the appearance using the `sx` prop:
-
-```tsx
-<TreeDropdown
-  anchorEl={anchorEl}
-  treeDefinition={treeDefinition}
-  sx={{
-    '& .MuiPopper-dropdown': {
-      width: '300px',
-      maxHeight: '400px',
-    },
-  }}
-/>
-```
-
-### Positioning
-
-Control dropdown placement:
-
-```tsx
-<TreeDropdown
-  anchorEl={anchorEl}
-  treeDefinition={treeDefinition}
-  placement="bottom-end" // Options: 'bottom-start', 'bottom-end', 'top-start', etc.
-/>
-```
-
-## Selection Behavior
-
-### Multiple Selection Mode
-
-- Clicking a checkbox toggles its state
-- Selecting a parent automatically selects all children
-- Deselecting a parent automatically deselects all children
-- Parent nodes show indeterminate state when some (but not all) children are selected
-- The `onChange` callback behavior depends on `exposeOnlySelectedTree`:
-  - When `false` (default): receives the entire tree with updated states
-  - When `true`: receives only the selected branches (unselected nodes are filtered out)
-
-### Single Selection Mode
-
-- Only one item can be selected at a time
-- Selecting a new item deselects the previously selected item
-- Selection controls only appear on leaf nodes (nodes without children)
-- Parent nodes without children can also be selected
-
-## State Management
-
-The component maintains an internal state mapper (`TreeMapper`) that tracks:
-
-- Selection status of each node (`CHECKED`, `UNCHECKED`, `INDETERMINATE`)
-- Parent-child relationships
-
-You can access this internal state via the ref:
-
-```tsx
-const internalMapper = treeRef.current?.internalMapper
-```
-
-## Best Practices
-
-1. **Unique IDs**: Ensure all node IDs are unique across the entire tree
-2. **Search Performance**: Use `getValues` efficiently - it's called for every item during filtering
-3. **Large Trees**: For very large trees, consider implementing virtualization (not currently built-in)
-4. **Accessibility**: The component uses Material-UI's MenuItem which provides basic accessibility, but consider adding ARIA labels for complex use cases
-5. **State Initialization**: Use `status` prop to initialize selection state rather than managing it externally
-6. **Debouncing**: Search is automatically debounced (300ms default), but you can customize this in the search hook if needed
-
-## Component Architecture
-
-The component is built with the following structure:
-
-- **TreeDropdown.tsx**: Main component that manages state and provides the ref API
-- **TreeNodeList**: Renders a list of tree nodes at a given level
-- **TreeNodeItem**: Individual tree node component with hover-based submenu
-- **TreeDropdownProvider**: Context provider for sharing state across the tree
-- **utils.ts**: Utility functions for tree manipulation, normalization, and selection logic
-- **hooks/useSearch.ts**: Search functionality with debouncing
-- **hooks/useTreeDropdown.ts**: Hook to access tree dropdown context
-
-## Notes
-
-- The component uses Material-UI's Popper for positioning nested menus
-- Nested menus appear on hover by default
-- Scrolling disables hover behavior temporarily to prevent menu flickering
-- The component automatically handles parent-child selection relationships
-- Search is case-insensitive by default