@true-tech-team/react-components 0.0.4 → 0.0.6

package/lib/components/display/List/hooks/useListFilter.d.ts

@@ -0,0 +1,6 @@
+import { UseListFilterOptions, UseListFilterReturn } from '../types';
+/**
+ * Hook for filtering list items with optional debounce
+ * Supports controlled/uncontrolled patterns and custom filter functions
+ */
+export declare function useListFilter<T extends Record<string, unknown>>({ data, searchQuery: controlledQuery, defaultSearchQuery, onSearchChange, searchFields, searchFn, debounceMs, }: UseListFilterOptions<T>): UseListFilterReturn<T>;

package/lib/components/display/List/hooks/useListGroups.d.ts

@@ -0,0 +1,6 @@
+import { UseListGroupsOptions, UseListGroupsReturn } from '../types';
+/**
+ * Hook for grouping list items with collapsible support
+ * Supports controlled/uncontrolled patterns for collapsed state
+ */
+export declare function useListGroups<T extends Record<string, unknown>>({ data, groupBy, collapsedGroups: controlledCollapsed, defaultCollapsedGroups, onCollapsedGroupsChange, }: UseListGroupsOptions<T>): UseListGroupsReturn<T>;

package/lib/components/display/List/hooks/useListKeyboardNav.d.ts

@@ -0,0 +1,6 @@
+import { UseListKeyboardNavOptions, UseListKeyboardNavReturn } from '../types';
+/**
+ * Hook for keyboard navigation in lists
+ * Supports vertical, horizontal, and grid navigation patterns
+ */
+export declare function useListKeyboardNav({ itemCount, onItemAction, onEscape, loop, orientation, columns, disabled, }: UseListKeyboardNavOptions): UseListKeyboardNavReturn;

package/lib/components/display/List/hooks/useListSelection.d.ts

@@ -0,0 +1,6 @@
+import { UseListSelectionOptions, UseListSelectionReturn } from '../types';
+/**
+ * Hook for managing list item selection
+ * Supports single and multiple selection modes with controlled/uncontrolled patterns
+ */
+export declare function useListSelection({ selectionMode, selectedKeys: controlledKeys, defaultSelectedKeys, onSelectionChange, allItemKeys, }: UseListSelectionOptions): UseListSelectionReturn;

package/lib/components/display/List/index.d.ts

@@ -0,0 +1,11 @@
+export { List, default } from './List';
+export { ListItem } from './ListItem';
+export { ListHeader } from './ListHeader';
+export { ListGroup } from './ListGroup';
+export { ListSearch } from './ListSearch';
+export { ListSkeleton } from './ListSkeleton';
+export { ListEmpty } from './ListEmpty';
+export { ListContext, useListContext, useListContextStrict } from './ListContext';
+export { useListSelection, useListExpand, useListFilter, useListKeyboardNav, useListGroups, } from './hooks';
+export type { ListProps, ListItemRenderContext, ListContextValue, SelectionMode, SelectionState, BulkAction, ItemAction, ListInfiniteScrollConfig, ListSkeletonConfig, ResponsiveColumns, UseListSelectionOptions, UseListSelectionReturn, UseListExpandOptions, UseListExpandReturn, UseListFilterOptions, UseListFilterReturn, UseListKeyboardNavOptions, UseListKeyboardNavReturn, UseListGroupsOptions, UseListGroupsReturn, ListGroup as ListGroupType, } from './types';
+export { getNestedValue, formatValue, generateItemKey, searchItems, groupItems, sortItems, } from './utils';

package/lib/components/display/List/types.d.ts

@@ -0,0 +1,485 @@
+import { ReactNode, MouseEvent, KeyboardEvent } from 'react';
+import { BaseComponentProps, ComponentSize } from '../../../types';
+export type SelectionMode = 'none' | 'single' | 'multiple';
+export interface SelectionState {
+    selectedKeys: Set<string>;
+    isAllSelected: boolean;
+    isIndeterminate: boolean;
+}
+export interface ListInfiniteScrollConfig {
+    /**
+     * Callback to load more data
+     */
+    onLoadMore: () => void;
+    /**
+     * Whether there is more data to load
+     */
+    hasMore: boolean;
+    /**
+     * Whether currently loading more data
+     * @default false
+     */
+    loading?: boolean;
+    /**
+     * Intersection observer threshold (0-1)
+     * @default 0.1
+     */
+    threshold?: number;
+    /**
+     * Root margin for intersection observer
+     * @default '100px'
+     */
+    rootMargin?: string;
+}
+export interface BulkAction<T = Record<string, unknown>> {
+    /**
+     * Unique identifier for the action
+     */
+    id: string;
+    /**
+     * Label displayed in the action button/menu
+     */
+    label: ReactNode;
+    /**
+     * Icon to display (optional)
+     */
+    icon?: ReactNode;
+    /**
+     * Action handler - receives selected items
+     */
+    onAction: (selectedItems: T[], selectedKeys: string[]) => void;
+    /**
+     * Whether action is disabled
+     */
+    disabled?: boolean | ((selectedItems: T[]) => boolean);
+    /**
+     * Variant for styling (affects button appearance)
+     * @default 'default'
+     */
+    variant?: 'default' | 'danger' | 'primary';
+}
+export interface ItemAction<T = Record<string, unknown>> {
+    /**
+     * Unique identifier for the action
+     */
+    id: string;
+    /**
+     * Label displayed in the action menu
+     */
+    label: ReactNode;
+    /**
+     * Icon to display (optional)
+     */
+    icon?: ReactNode;
+    /**
+     * Action handler - receives the item and its index
+     */
+    onAction: (item: T, index: number) => void;
+    /**
+     * Whether action is disabled
+     */
+    disabled?: boolean | ((item: T) => boolean);
+    /**
+     * Variant for styling
+     * @default 'default'
+     */
+    variant?: 'default' | 'danger';
+    /**
+     * Show divider before this action
+     * @default false
+     */
+    divider?: boolean;
+}
+export interface ListSkeletonConfig {
+    /**
+     * Enable skeleton loading state
+     * @default false
+     */
+    enabled?: boolean;
+    /**
+     * Number of skeleton rows to display
+     * @default 5
+     */
+    rows?: number;
+}
+export interface ListItemRenderContext {
+    /**
+     * Whether item is currently selected
+     */
+    isSelected: boolean;
+    /**
+     * Whether item is disabled
+     */
+    isDisabled: boolean;
+    /**
+     * Whether item has keyboard focus
+     */
+    isFocused: boolean;
+    /**
+     * Whether item is expanded
+     */
+    isExpanded: boolean;
+    /**
+     * Toggle selection for this item
+     */
+    toggleSelection: () => void;
+    /**
+     * Toggle expansion for this item
+     */
+    toggleExpand: () => void;
+    /**
+     * The item's unique key
+     */
+    itemKey: string;
+}
+export interface ResponsiveColumns {
+    sm?: number;
+    md?: number;
+    lg?: number;
+    xl?: number;
+}
+export interface ListProps<T extends Record<string, unknown> = Record<string, unknown>> extends Omit<BaseComponentProps, 'children'> {
+    /**
+     * Array of items to display
+     */
+    data: T[];
+    /**
+     * Unique key for each item. Can be a key from the item object or a function.
+     * @default 'id'
+     */
+    itemKey?: keyof T | ((item: T, index: number) => string);
+    /**
+     * Function to determine if an item is disabled
+     */
+    isItemDisabled?: (item: T, index: number) => boolean;
+    /**
+     * Custom render function for each item.
+     * If not provided, uses default rendering based on primaryTextField/secondaryTextField.
+     */
+    renderItem?: (item: T, index: number, context: ListItemRenderContext) => ReactNode;
+    /**
+     * Key from item to use as primary text (for default rendering)
+     */
+    primaryTextField?: keyof T;
+    /**
+     * Key from item to use as secondary text (for default rendering)
+     */
+    secondaryTextField?: keyof T;
+    /**
+     * Key from item to use for avatar/icon (for default rendering)
+     */
+    avatarField?: keyof T;
+    /**
+     * List size variant
+     * @default 'md'
+     */
+    size?: ComponentSize;
+    /**
+     * Visual variant
+     * @default 'default'
+     */
+    variant?: 'default' | 'bordered' | 'card' | 'flush';
+    /**
+     * Spacing between items
+     * @default 'md'
+     */
+    spacing?: 'none' | 'sm' | 'md' | 'lg';
+    /**
+     * Selection mode
+     * @default 'none'
+     */
+    selectionMode?: SelectionMode;
+    /**
+     * Selected item keys (controlled)
+     */
+    selectedKeys?: string[];
+    /**
+     * Default selected keys (uncontrolled)
+     */
+    defaultSelectedKeys?: string[];
+    /**
+     * Callback when selection changes
+     */
+    onSelectionChange?: (selectedKeys: string[]) => void;
+    /**
+     * Whether to show selection controls (checkbox/radio)
+     * @default true when selectionMode !== 'none'
+     */
+    showSelectionControls?: boolean;
+    /**
+     * Position of selection controls
+     * @default 'start'
+     */
+    selectionControlPosition?: 'start' | 'end';
+    /**
+     * Bulk actions configuration.
+     * Only shown when selectionMode is 'multiple' and items are selected.
+     */
+    bulkActions?: Array<BulkAction<T>>;
+    /**
+     * Position of bulk actions bar
+     * @default 'top'
+     */
+    bulkActionsPosition?: 'top' | 'bottom' | 'sticky-top' | 'sticky-bottom';
+    /**
+     * Custom render for bulk actions bar
+     */
+    renderBulkActions?: (selectedItems: T[], selectedKeys: string[], actions: Array<BulkAction<T>>) => ReactNode;
+    /**
+     * Actions available per item (shown in dropdown menu)
+     */
+    itemActions?: Array<ItemAction<T>>;
+    /**
+     * Position of item action button
+     * @default 'end'
+     */
+    itemActionsPosition?: 'start' | 'end';
+    /**
+     * When to show item actions
+     * @default 'hover'
+     */
+    itemActionsTrigger?: 'hover' | 'always';
+    /**
+     * Group items by a field or custom function
+     */
+    groupBy?: keyof T | ((item: T) => string);
+    /**
+     * Custom group header renderer
+     */
+    renderGroupHeader?: (groupKey: string, itemCount: number, isCollapsed: boolean) => ReactNode;
+    /**
+     * Whether groups are collapsible
+     * @default false
+     */
+    collapsibleGroups?: boolean;
+    /**
+     * Default collapsed group keys (uncontrolled)
+     */
+    defaultCollapsedGroups?: string[];
+    /**
+     * Collapsed group keys (controlled)
+     */
+    collapsedGroups?: string[];
+    /**
+     * Callback when group collapse state changes
+     */
+    onCollapsedGroupsChange?: (collapsedGroups: string[]) => void;
+    /**
+     * Render function for expanded item content
+     */
+    renderExpandedContent?: (item: T, index: number) => ReactNode;
+    /**
+     * Expanded item keys (controlled)
+     */
+    expandedKeys?: string[];
+    /**
+     * Default expanded item keys (uncontrolled)
+     */
+    defaultExpandedKeys?: string[];
+    /**
+     * Callback when expansion changes
+     */
+    onExpandChange?: (expandedKeys: string[]) => void;
+    /**
+     * How to trigger expansion
+     * @default 'icon'
+     */
+    expandTrigger?: 'click' | 'icon';
+    /**
+     * Enable built-in search
+     * @default false
+     */
+    searchable?: boolean;
+    /**
+     * Search placeholder text
+     * @default 'Search...'
+     */
+    searchPlaceholder?: string;
+    /**
+     * Fields to search (for default search behavior)
+     */
+    searchFields?: Array<keyof T>;
+    /**
+     * Custom search function
+     */
+    searchFn?: (item: T, query: string) => boolean;
+    /**
+     * Search query (controlled)
+     */
+    searchQuery?: string;
+    /**
+     * Callback when search changes
+     */
+    onSearchChange?: (query: string) => void;
+    /**
+     * Debounce delay for search in milliseconds
+     * @default 300
+     */
+    searchDebounce?: number;
+    /**
+     * Infinite scroll configuration
+     */
+    infiniteScroll?: ListInfiniteScrollConfig;
+    /**
+     * Callback when item is clicked
+     */
+    onItemClick?: (item: T, index: number, event: MouseEvent) => void;
+    /**
+     * Callback when item receives keyboard action (Enter/Space)
+     */
+    onItemAction?: (item: T, index: number, event: KeyboardEvent) => void;
+    /**
+     * Enable keyboard navigation
+     * @default true
+     */
+    keyboardNavigation?: boolean;
+    /**
+     * Loading state
+     * @default false
+     */
+    loading?: boolean;
+    /**
+     * Custom loading content
+     */
+    loadingContent?: ReactNode;
+    /**
+     * Skeleton configuration
+     */
+    skeleton?: ListSkeletonConfig;
+    /**
+     * Empty state content
+     * @default 'No items to display'
+     */
+    emptyContent?: ReactNode;
+    /**
+     * Custom empty state render
+     */
+    renderEmpty?: () => ReactNode;
+    /**
+     * Maximum height (enables scrolling)
+     */
+    maxHeight?: string | number;
+    /**
+     * Number of columns for responsive grid layout
+     * @default 1
+     */
+    columns?: number | ResponsiveColumns;
+    /**
+     * ARIA role for the list
+     * @default 'list' or 'listbox' when selectable
+     */
+    role?: 'list' | 'listbox' | 'menu' | 'grid';
+    /**
+     * ID of element that labels this list
+     */
+    'aria-labelledby'?: string;
+}
+export interface ListContextValue<T = Record<string, unknown>> {
+    data: T[];
+    filteredData: T[];
+    getItemKey: (item: T, index: number) => string;
+    isItemDisabled: (item: T, index: number) => boolean;
+    size: ComponentSize;
+    variant: 'default' | 'bordered' | 'card' | 'flush';
+    spacing: 'none' | 'sm' | 'md' | 'lg';
+    selectionMode: SelectionMode;
+    selectedKeys: Set<string>;
+    onSelectItem: (key: string, selected: boolean) => void;
+    onSelectAll: (selected: boolean) => void;
+    isAllSelected: boolean;
+    isIndeterminate: boolean;
+    showSelectionControls: boolean;
+    selectionControlPosition: 'start' | 'end';
+    expandedKeys: Set<string>;
+    onExpandItem: (key: string) => void;
+    renderExpandedContent?: (item: T, index: number) => ReactNode;
+    expandTrigger: 'click' | 'icon';
+    itemActions?: Array<ItemAction<T>>;
+    itemActionsPosition: 'start' | 'end';
+    itemActionsTrigger: 'hover' | 'always';
+    focusedIndex: number;
+    setFocusedIndex: (index: number) => void;
+    onItemClick?: (item: T, index: number, event: MouseEvent) => void;
+    onItemAction?: (item: T, index: number, event: KeyboardEvent) => void;
+    renderItem?: (item: T, index: number, context: ListItemRenderContext) => ReactNode;
+    primaryTextField?: keyof T;
+    secondaryTextField?: keyof T;
+    avatarField?: keyof T;
+    groupBy?: keyof T | ((item: T) => string);
+    collapsedGroups: Set<string>;
+    onToggleGroup: (groupKey: string) => void;
+    collapsibleGroups: boolean;
+    renderGroupHeader?: (groupKey: string, itemCount: number, isCollapsed: boolean) => ReactNode;
+    listId: string;
+}
+export interface UseListSelectionOptions {
+    selectionMode: SelectionMode;
+    selectedKeys?: string[];
+    defaultSelectedKeys?: string[];
+    onSelectionChange?: (keys: string[]) => void;
+    allItemKeys: string[];
+}
+export interface UseListSelectionReturn {
+    selectedKeys: Set<string>;
+    onSelectItem: (key: string, selected: boolean) => void;
+    onSelectAll: (selected: boolean) => void;
+    isAllSelected: boolean;
+    isIndeterminate: boolean;
+}
+export interface UseListExpandOptions {
+    expandedKeys?: string[];
+    defaultExpandedKeys?: string[];
+    onExpandChange?: (keys: string[]) => void;
+}
+export interface UseListExpandReturn {
+    expandedKeys: Set<string>;
+    onExpandItem: (key: string) => void;
+    isExpanded: (key: string) => boolean;
+}
+export interface UseListFilterOptions<T> {
+    data: T[];
+    searchQuery?: string;
+    defaultSearchQuery?: string;
+    onSearchChange?: (query: string) => void;
+    searchFields?: Array<keyof T>;
+    searchFn?: (item: T, query: string) => boolean;
+    debounceMs?: number;
+}
+export interface UseListFilterReturn<T> {
+    filteredData: T[];
+    searchQuery: string;
+    setSearchQuery: (query: string) => void;
+    isFiltering: boolean;
+}
+export interface UseListKeyboardNavOptions {
+    itemCount: number;
+    onItemAction?: (index: number) => void;
+    onEscape?: () => void;
+    loop?: boolean;
+    orientation?: 'vertical' | 'horizontal' | 'grid';
+    columns?: number;
+    disabled?: boolean;
+}
+export interface UseListKeyboardNavReturn {
+    focusedIndex: number;
+    setFocusedIndex: (index: number) => void;
+    handleKeyDown: (event: KeyboardEvent) => void;
+    getItemTabIndex: (index: number) => 0 | -1;
+}
+export interface UseListGroupsOptions<T> {
+    data: T[];
+    groupBy?: keyof T | ((item: T) => string);
+    collapsedGroups?: string[];
+    defaultCollapsedGroups?: string[];
+    onCollapsedGroupsChange?: (collapsedGroups: string[]) => void;
+}
+export interface ListGroup<T> {
+    key: string;
+    items: T[];
+}
+export interface UseListGroupsReturn<T> {
+    groups: Array<ListGroup<T>>;
+    collapsedGroups: Set<string>;
+    onToggleGroup: (groupKey: string) => void;
+    isGroupCollapsed: (groupKey: string) => boolean;
+}

package/lib/components/display/List/utils.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Utility functions for the List component
+ */
+/**
+ * Get a nested property value from an object using dot notation
+ * @param obj - The object to get the value from
+ * @param path - The path to the property (e.g., 'user.name')
+ * @returns The value at the path, or undefined if not found
+ */
+export declare function getNestedValue<T>(obj: T, path: string): unknown;
+/**
+ * Format a value for display
+ * @param value - The value to format
+ * @returns A string representation of the value
+ */
+export declare function formatValue(value: unknown): string;
+/**
+ * Generate a stable key from an item
+ * @param item - The item to generate a key for
+ * @param index - The index of the item
+ * @param keyField - Optional field to use as the key
+ * @returns A stable key string
+ */
+export declare function generateItemKey<T extends Record<string, unknown>>(item: T, index: number, keyField?: keyof T): string;
+/**
+ * Search items using a simple text match
+ * @param items - The items to search
+ * @param query - The search query
+ * @param fields - Fields to search in
+ * @returns Filtered items
+ */
+export declare function searchItems<T extends Record<string, unknown>>(items: T[], query: string, fields?: Array<keyof T>): T[];
+/**
+ * Group items by a key or function
+ * @param items - The items to group
+ * @param groupBy - The field or function to group by
+ * @returns Map of group key to items
+ */
+export declare function groupItems<T extends Record<string, unknown>>(items: T[], groupBy: keyof T | ((item: T) => string)): Map<string, T[]>;
+/**
+ * Sort items by a key
+ * @param items - The items to sort
+ * @param sortKey - The key to sort by
+ * @param direction - Sort direction ('asc' or 'desc')
+ * @returns Sorted items
+ */
+export declare function sortItems<T extends Record<string, unknown>>(items: T[], sortKey: keyof T, direction?: 'asc' | 'desc'): T[];

package/lib/components/display/OverflowText/OverflowText.d.ts

@@ -0,0 +1,81 @@
+import { default as React } from 'react';
+import { PopoverPosition } from '../../../utils/positioning';
+import { BaseComponentProps } from '../../../types';
+/**
+ * Props for the OverflowText component
+ */
+export interface OverflowTextProps extends Omit<BaseComponentProps, 'children'> {
+    /**
+     * Text content to display
+     */
+    children: string;
+    /**
+     * Maximum number of lines before truncation
+     * @default 1
+     */
+    lines?: number;
+    /**
+     * Position of the tooltip
+     * @default 'top'
+     */
+    tooltipPosition?: PopoverPosition;
+    /**
+     * Delay before showing tooltip (ms)
+     * @default 200
+     */
+    tooltipDelay?: number;
+    /**
+     * Whether to disable the tooltip (always truncate, never show full text)
+     * @default false
+     */
+    disableTooltip?: boolean;
+    /**
+     * Custom tooltip content (defaults to full text)
+     */
+    tooltipContent?: React.ReactNode;
+    /**
+     * Maximum width of the tooltip
+     * @default 300
+     */
+    tooltipMaxWidth?: number;
+    /**
+     * HTML element to render
+     * @default 'span'
+     */
+    as?: 'span' | 'p' | 'div';
+    /**
+     * Callback when text overflow state changes
+     * @param isOverflowing - Whether text is currently overflowing
+     */
+    onOverflowChange?: (isOverflowing: boolean) => void;
+}
+/**
+ * OverflowText - Text that truncates with ellipsis and shows full content in tooltip
+ *
+ * @example
+ * Single line truncation:
+ * ```tsx
+ * <OverflowText>
+ *   This is a very long text that will be truncated with ellipsis
+ * </OverflowText>
+ * ```
+ *
+ * @example
+ * Multi-line truncation:
+ * ```tsx
+ * <OverflowText lines={2}>
+ *   This is a very long text that spans multiple lines and will be
+ *   truncated after the second line with an ellipsis.
+ * </OverflowText>
+ * ```
+ *
+ * @example
+ * With custom tooltip position:
+ * ```tsx
+ * <OverflowText tooltipPosition="bottom" tooltipDelay={500}>
+ *   Hover to see the full text in a tooltip at the bottom
+ * </OverflowText>
+ * ```
+ */
+export declare const OverflowText: React.ForwardRefExoticComponent<OverflowTextProps & React.RefAttributes<HTMLElement>>;
+export default OverflowText;

package/lib/components/display/OverflowText/index.d.ts

@@ -0,0 +1,2 @@
+export { OverflowText } from './OverflowText';
+export type { OverflowTextProps } from './OverflowText';