@true-tech-team/react-components 0.0.5 → 0.0.7

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/Table/Table.d.ts

@@ -0,0 +1,6 @@
+import { default as React } from 'react';
+import { TableProps } from './types';
+export declare const Table: <T extends Record<string, unknown> = Record<string, unknown>>(props: TableProps<T> & {
+    ref?: React.ForwardedRef<HTMLDivElement>;
+}) => React.ReactElement;
+export default Table;

package/lib/components/display/Table/TableBody.d.ts

@@ -0,0 +1,4 @@
+export declare function TableBody(): import("react/jsx-runtime").JSX.Element;
+export declare namespace TableBody {
+    var displayName: string;
+}

package/lib/components/display/Table/TableCell.d.ts

@@ -0,0 +1,12 @@
+import { ColumnConfig } from './types';
+interface TableCellProps<T = Record<string, unknown>> {
+    column: ColumnConfig<T>;
+    row: T;
+    rowIndex: number;
+    isFirstColumn: boolean;
+}
+export declare function TableCell<T extends Record<string, unknown>>({ column, row, rowIndex, isFirstColumn, }: TableCellProps<T>): import("react/jsx-runtime").JSX.Element;
+export declare namespace TableCell {
+    var displayName: string;
+}
+export {};

package/lib/components/display/Table/TableContext.d.ts

@@ -0,0 +1,10 @@
+import { TableContextValue } from './types';
+export declare const TableContext: import('react').Context<TableContextValue<Record<string, unknown>> | null>;
+/**
+ * Hook to optionally access Table context
+ */
+export declare function useTableContext<T = Record<string, unknown>>(): TableContextValue<T> | null;
+/**
+ * Hook that throws if not within Table
+ */
+export declare function useTableContextStrict<T = Record<string, unknown>>(): TableContextValue<T>;

package/lib/components/display/Table/TableHeader.d.ts

@@ -0,0 +1,4 @@
+export declare function TableHeader(): import("react/jsx-runtime").JSX.Element;
+export declare namespace TableHeader {
+    var displayName: string;
+}

package/lib/components/display/Table/TableRow.d.ts

@@ -0,0 +1,9 @@
+interface TableRowProps<T = Record<string, unknown>> {
+    row: T;
+    rowIndex: number;
+}
+export declare function TableRow<T extends Record<string, unknown>>({ row, rowIndex, }: TableRowProps<T>): import("react/jsx-runtime").JSX.Element;
+export declare namespace TableRow {
+    var displayName: string;
+}
+export {};

package/lib/components/display/Table/TableSearch.d.ts

@@ -0,0 +1,32 @@
+export interface TableSearchProps {
+    /**
+     * Current search query
+     */
+    value: string;
+    /**
+     * Callback when search query changes
+     */
+    onChange: (value: string) => void;
+    /**
+     * Placeholder text
+     * @default 'Search...'
+     */
+    placeholder?: string;
+    /**
+     * Whether the search is currently filtering (debounce active)
+     */
+    isFiltering?: boolean;
+    /**
+     * Auto focus the input on mount
+     */
+    autoFocus?: boolean;
+    /**
+     * Callback when input is cleared
+     */
+    onClear?: () => void;
+}
+export declare function TableSearch({ value, onChange, placeholder, isFiltering, autoFocus, onClear, }: TableSearchProps): import("react/jsx-runtime").JSX.Element;
+export declare namespace TableSearch {
+    var displayName: string;
+}
+export default TableSearch;

package/lib/components/display/Table/TableSkeleton.d.ts

@@ -0,0 +1,12 @@
+import { ColumnConfig } from './types';
+interface TableSkeletonProps {
+    rows: number;
+    columns: Array<ColumnConfig<any>>;
+    hasExpandColumn?: boolean;
+    hasSelectionColumn?: boolean;
+}
+export declare function TableSkeleton({ rows, columns, hasExpandColumn, hasSelectionColumn, }: TableSkeletonProps): import("react/jsx-runtime").JSX.Element;
+export declare namespace TableSkeleton {
+    var displayName: string;
+}
+export {};

package/lib/components/display/Table/hooks/index.d.ts

@@ -0,0 +1,10 @@
+export { useTableSelection } from './useTableSelection';
+export type { UseTableSelectionOptions, UseTableSelectionReturn } from './useTableSelection';
+export { useTableSort } from './useTableSort';
+export type { UseTableSortOptions, UseTableSortReturn } from './useTableSort';
+export { useTableExpand } from './useTableExpand';
+export type { UseTableExpandOptions, UseTableExpandReturn } from './useTableExpand';
+export { useInfiniteScroll } from './useInfiniteScroll';
+export type { UseInfiniteScrollOptions, UseInfiniteScrollReturn } from './useInfiniteScroll';
+export { useTableFilter } from './useTableFilter';
+export type { UseTableFilterOptions, UseTableFilterReturn } from './useTableFilter';

package/lib/components/display/Table/hooks/useInfiniteScroll.d.ts

@@ -0,0 +1,11 @@
+export interface UseInfiniteScrollOptions {
+    onLoadMore: () => void;
+    hasMore: boolean;
+    loading?: boolean;
+    threshold?: number;
+    rootMargin?: string;
+}
+export interface UseInfiniteScrollReturn {
+    sentinelRef: React.RefObject<HTMLDivElement>;
+}
+export declare function useInfiniteScroll({ onLoadMore, hasMore, loading, threshold, rootMargin, }: UseInfiniteScrollOptions): UseInfiniteScrollReturn;

package/lib/components/display/Table/hooks/useTableExpand.d.ts

@@ -0,0 +1,10 @@
+export interface UseTableExpandOptions {
+    expandedKeys?: string[];
+    defaultExpandedKeys?: string[];
+    onExpandChange?: (keys: string[]) => void;
+}
+export interface UseTableExpandReturn {
+    expandedKeys: Set<string>;
+    onExpand: (key: string, expanded: boolean) => void;
+}
+export declare function useTableExpand({ expandedKeys: controlledKeys, defaultExpandedKeys, onExpandChange, }: UseTableExpandOptions): UseTableExpandReturn;

package/lib/components/display/Table/hooks/useTableFilter.d.ts

@@ -0,0 +1,22 @@
+import { ColumnConfig } from '../types';
+export interface UseTableFilterOptions<T> {
+    data: T[];
+    columns: Array<ColumnConfig<T>>;
+    searchQuery?: string;
+    defaultSearchQuery?: string;
+    onSearchChange?: (query: string) => void;
+    searchFields?: Array<keyof T>;
+    searchFn?: (item: T, query: string) => boolean;
+    debounceMs?: number;
+}
+export interface UseTableFilterReturn<T> {
+    filteredData: T[];
+    searchQuery: string;
+    setSearchQuery: (query: string) => void;
+    isFiltering: boolean;
+}
+/**
+ * Hook for filtering table data with optional debounce
+ * Supports controlled/uncontrolled patterns and custom filter functions
+ */
+export declare function useTableFilter<T extends Record<string, unknown>>({ data, columns, searchQuery: controlledQuery, defaultSearchQuery, onSearchChange, searchFields, searchFn, debounceMs, }: UseTableFilterOptions<T>): UseTableFilterReturn<T>;