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

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

@@ -0,0 +1,16 @@
+import { SelectionMode } from '../types';
+export interface UseTableSelectionOptions {
+    selectionMode: SelectionMode;
+    selectedKeys?: string[];
+    defaultSelectedKeys?: string[];
+    onSelectionChange?: (keys: string[]) => void;
+    allRowKeys: string[];
+}
+export interface UseTableSelectionReturn {
+    selectedKeys: Set<string>;
+    onSelectRow: (key: string, selected: boolean) => void;
+    onSelectAll: (selected: boolean) => void;
+    isAllSelected: boolean;
+    isIndeterminate: boolean;
+}
+export declare function useTableSelection({ selectionMode, selectedKeys: controlledKeys, defaultSelectedKeys, onSelectionChange, allRowKeys, }: UseTableSelectionOptions): UseTableSelectionReturn;

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

@@ -0,0 +1,11 @@
+import { SortState } from '../types';
+export interface UseTableSortOptions {
+    sort?: SortState;
+    defaultSort?: SortState;
+    onSortChange?: (sort: SortState) => void;
+}
+export interface UseTableSortReturn {
+    sort: SortState;
+    onSort: (column: string) => void;
+}
+export declare function useTableSort({ sort: controlledSort, defaultSort, onSortChange, }: UseTableSortOptions): UseTableSortReturn;

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

@@ -0,0 +1,13 @@
+export { Table, default } from './Table';
+export { TableHeader } from './TableHeader';
+export { TableBody } from './TableBody';
+export { TableRow } from './TableRow';
+export { TableCell } from './TableCell';
+export { TableSkeleton } from './TableSkeleton';
+export { TableSearch } from './TableSearch';
+export type { TableSearchProps } from './TableSearch';
+export { TableContext, useTableContext, useTableContextStrict } from './TableContext';
+export type { TableProps, TableContextValue, ColumnConfig, ColumnAlign, SortState, SortDirection, SelectionMode, TablePaginationConfig, TableInfiniteScrollConfig, TableSkeletonConfig, } from './types';
+export { autoGenerateColumns, getCellValue, sortData, formatCellValue } from './utils';
+export { useTableSelection, useTableSort, useTableExpand, useInfiniteScroll, useTableFilter, } from './hooks';
+export type { UseTableSelectionOptions, UseTableSelectionReturn, UseTableSortOptions, UseTableSortReturn, UseTableExpandOptions, UseTableExpandReturn, UseInfiniteScrollOptions, UseInfiniteScrollReturn, UseTableFilterOptions, UseTableFilterReturn, } from './hooks';

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

@@ -0,0 +1,295 @@
+import { ReactNode, MouseEvent } from 'react';
+import { BaseComponentProps, ComponentSize } from '../../../types';
+export type ColumnAlign = 'left' | 'center' | 'right';
+export type SortDirection = 'asc' | 'desc' | null;
+export interface ColumnConfig<T = Record<string, unknown>> {
+    /**
+     * Data key to access row data (supports dot notation for nested properties)
+     */
+    key: keyof T | string;
+    /**
+     * Header content - string or ReactNode
+     */
+    header: ReactNode;
+    /**
+     * Column width using CSS grid template value
+     * @example 'auto', '1fr', '320px', 'minmax(100px, 1fr)'
+     * @default 'auto'
+     */
+    width?: string;
+    /**
+     * Content alignment
+     * @default auto-detected based on data type (numbers right, text left)
+     */
+    align?: ColumnAlign;
+    /**
+     * Whether column is sortable
+     * @default false
+     */
+    sortable?: boolean;
+    /**
+     * Custom render function for cell content
+     */
+    render?: (value: unknown, row: T, rowIndex: number) => ReactNode;
+    /**
+     * Whether column is sticky (for horizontal scrolling)
+     * @default false
+     */
+    sticky?: boolean;
+    /**
+     * Custom sort comparison function
+     */
+    sortFn?: (a: T, b: T, direction: 'asc' | 'desc') => number;
+}
+export interface SortState {
+    column: string | null;
+    direction: SortDirection;
+}
+export type SelectionMode = 'none' | 'single' | 'multiple';
+export interface TablePaginationConfig {
+    /**
+     * Number of items per page
+     */
+    pageSize: number;
+    /**
+     * Current page number (1-indexed)
+     */
+    currentPage: number;
+    /**
+     * Total number of items
+     */
+    totalItems: number;
+    /**
+     * Callback when page changes
+     */
+    onPageChange: (page: number) => void;
+    /**
+     * Available page size options for the select dropdown
+     * If provided, shows a page size selector
+     * @example [10, 25, 50, 100]
+     */
+    pageSizeOptions?: number[];
+    /**
+     * Callback when page size changes
+     */
+    onPageSizeChange?: (pageSize: number) => void;
+}
+export interface TableInfiniteScrollConfig {
+    /**
+     * 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;
+}
+export interface TableSkeletonConfig {
+    /**
+     * Number of skeleton rows to display
+     * @default 5
+     */
+    rows?: number;
+    /**
+     * Whether to show skeleton state
+     * @default false
+     */
+    enabled?: boolean;
+}
+export interface TableProps<T extends Record<string, unknown> = Record<string, unknown>> extends Omit<BaseComponentProps, 'children'> {
+    /**
+     * Table data array
+     */
+    data: T[];
+    /**
+     * Column configurations
+     * If not provided, columns are auto-generated from data keys
+     */
+    columns?: Array<ColumnConfig<T>>;
+    /**
+     * Unique key for each row
+     * @default 'id'
+     */
+    rowKey?: keyof T | ((row: T, index: number) => string);
+    /**
+     * Table size variant
+     * @default 'md'
+     */
+    size?: ComponentSize;
+    /**
+     * Table visual variant
+     * @default 'default'
+     */
+    variant?: 'default' | 'striped' | 'bordered';
+    /**
+     * Current sort state (controlled)
+     */
+    sort?: SortState;
+    /**
+     * Default sort state (uncontrolled)
+     */
+    defaultSort?: SortState;
+    /**
+     * Callback when sort changes
+     */
+    onSortChange?: (sort: SortState) => void;
+    /**
+     * Selection mode
+     * @default 'none'
+     */
+    selectionMode?: SelectionMode;
+    /**
+     * Selected row 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)
+     * When false, rows can still be selected by clicking but no visual control is shown
+     * @default true
+     */
+    showSelectionControls?: boolean;
+    /**
+     * Callback when row is clicked
+     */
+    onRowClick?: (row: T, index: number, event: MouseEvent) => void;
+    /**
+     * Render function for expandable content
+     * If provided, rows become expandable
+     */
+    expandedRowRender?: (row: T, index: number) => ReactNode;
+    /**
+     * Expanded row keys (controlled)
+     */
+    expandedKeys?: string[];
+    /**
+     * Default expanded keys (uncontrolled)
+     */
+    defaultExpandedKeys?: string[];
+    /**
+     * Callback when expand state changes
+     */
+    onExpandChange?: (expandedKeys: string[]) => void;
+    /**
+     * Pagination configuration
+     */
+    pagination?: TablePaginationConfig;
+    /**
+     * Infinite scroll configuration (mutually exclusive with pagination)
+     */
+    infiniteScroll?: TableInfiniteScrollConfig;
+    /**
+     * Enable built-in search
+     * @default false
+     */
+    searchable?: boolean;
+    /**
+     * Search placeholder text
+     * @default 'Search...'
+     */
+    searchPlaceholder?: string;
+    /**
+     * Fields to search (for default search behavior).
+     * If not provided, searches all column keys.
+     */
+    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;
+    /**
+     * Enable sticky header
+     * @default false
+     */
+    stickyHeader?: boolean;
+    /**
+     * Enable sticky first column
+     * @default false
+     */
+    stickyFirstColumn?: boolean;
+    /**
+     * Maximum height for scrollable table
+     */
+    maxHeight?: string | number;
+    /**
+     * Empty state content
+     * @default 'No data available'
+     */
+    emptyContent?: ReactNode;
+    /**
+     * Loading state
+     * @default false
+     */
+    loading?: boolean;
+    /**
+     * Loading indicator content
+     */
+    loadingContent?: ReactNode;
+    /**
+     * Skeleton loader configuration
+     * Shows skeleton rows instead of a spinner when loading
+     */
+    skeleton?: TableSkeletonConfig;
+    /**
+     * Caption for the table
+     */
+    caption?: string;
+    /**
+     * Whether caption is visually hidden
+     * @default false
+     */
+    captionHidden?: boolean;
+}
+export interface TableContextValue<T = Record<string, unknown>> {
+    data: T[];
+    columns: Array<ColumnConfig<T>>;
+    getRowKey: (row: T, index: number) => string;
+    size: ComponentSize;
+    variant: 'default' | 'striped' | 'bordered';
+    sort: SortState;
+    onSort: (column: string) => void;
+    selectionMode: SelectionMode;
+    selectedKeys: Set<string>;
+    onSelectRow: (key: string, selected: boolean) => void;
+    onSelectAll: (selected: boolean) => void;
+    isAllSelected: boolean;
+    isIndeterminate: boolean;
+    showSelectionControls: boolean;
+    expandedKeys: Set<string>;
+    onExpand: (key: string, expanded: boolean) => void;
+    hasExpandableRows: boolean;
+    expandedRowRender?: (row: T, index: number) => ReactNode;
+    onRowClick?: (row: T, index: number, event: MouseEvent) => void;
+    stickyHeader: boolean;
+    stickyFirstColumn: boolean;
+}

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

@@ -0,0 +1,37 @@
+import { ReactNode } from 'react';
+import { ColumnConfig, ColumnAlign, SortState } from './types';
+/**
+ * Column width validation rules:
+ * 1. All columns must have a minimum width > 0
+ * 2. Only one column can have a dynamic width (1fr) to prevent uneven column widths
+ * 3. If no width is specified, use the average size of data to calculate width
+ */
+export declare function calculateColumnWidths<T extends Record<string, unknown>>(columns: Array<ColumnConfig<T>>, data: T[]): string[];
+/**
+ * Auto-generate columns from the first data item's keys
+ */
+export declare function autoGenerateColumns<T extends Record<string, unknown>>(data: T[]): Array<ColumnConfig<T>>;
+/**
+ * Format header text from key (camelCase/snake_case -> Title Case)
+ */
+export declare function formatHeaderFromKey(key: string): string;
+/**
+ * Detect column alignment based on data type
+ */
+export declare function detectAlignment(value: unknown): ColumnAlign;
+/**
+ * Get cell value by column key (supports dot notation for nested properties)
+ */
+export declare function getCellValue<T>(row: T, key: string): unknown;
+/**
+ * Default sort comparison function
+ */
+export declare function defaultSortFn<T>(a: T, b: T, column: string, direction: 'asc' | 'desc'): number;
+/**
+ * Sort data by column
+ */
+export declare function sortData<T>(data: T[], sort: SortState, columns: Array<ColumnConfig<T>>): T[];
+/**
+ * Format cell value for display
+ */
+export declare function formatCellValue(value: unknown): ReactNode;

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

@@ -12,3 +12,4 @@ export * from './Skeleton';
 export * from './OverflowText';
 export * from './TruncatedList';
 export * from './Collapse';
+export * from './List';

package/lib/components/dnd/DndProvider/DndContext.d.ts

@@ -0,0 +1,91 @@
+/**
+ * DnD context for sharing drag state across components
+ */
+/**
+ * Data attached to a draggable item
+ */
+export interface DragData {
+    /** Unique identifier */
+    id: string;
+    /** Item type for filtering drop targets */
+    type?: string;
+    /** Index in list (for sortable) */
+    index?: number;
+    /** Additional custom data */
+    [key: string]: unknown;
+}
+/**
+ * Active drag state
+ */
+export interface ActiveDrag {
+    /** ID of the dragged item */
+    id: string;
+    /** Data attached to the dragged item */
+    data: DragData;
+    /** Element being dragged */
+    element: HTMLElement | null;
+}
+/**
+ * DnD context value
+ */
+export interface DndContextValue {
+    /** Currently active drag, null if nothing is being dragged */
+    active: ActiveDrag | null;
+    /** ID of the element currently being dragged over */
+    overId: string | null;
+    /** Data of the element currently being dragged over */
+    overData: DragData | null;
+    /** Set active drag state */
+    setActive: (active: ActiveDrag | null) => void;
+    /** Set over state */
+    setOver: (id: string | null, data: DragData | null) => void;
+    /** Register a droppable and return unregister function */
+    registerDroppable: (id: string, data: DragData) => () => void;
+    /** Get all registered droppables */
+    getDroppables: () => Map<string, DragData>;
+    /** Drag end callback */
+    onDragEnd?: (event: DragEndEvent) => void;
+}
+/**
+ * Event fired when drag ends
+ */
+export interface DragEndEvent {
+    /** The dragged item */
+    active: ActiveDrag;
+    /** The drop target, null if dropped outside */
+    over: {
+        id: string;
+        data: DragData;
+    } | null;
+}
+/**
+ * Event fired when drag starts
+ */
+export interface DragStartEvent {
+    /** The dragged item */
+    active: ActiveDrag;
+}
+/**
+ * Event fired when dragging over a droppable
+ */
+export interface DragOverEvent {
+    /** The dragged item */
+    active: ActiveDrag;
+    /** The element being dragged over */
+    over: {
+        id: string;
+        data: DragData;
+    };
+}
+/**
+ * DnD context
+ */
+export declare const DndContext: import('react').Context<DndContextValue | null>;
+/**
+ * Hook to access DnD context (throws if not in provider)
+ */
+export declare function useDndContext(): DndContextValue;
+/**
+ * Hook to access DnD context (returns null if not in provider)
+ */
+export declare function useDndContextOptional(): DndContextValue | null;

package/lib/components/dnd/DndProvider/DndProvider.d.ts

@@ -0,0 +1,37 @@
+import { default as React, ReactNode } from 'react';
+import { DragEndEvent, DragStartEvent, DragOverEvent } from './DndContext';
+import { BaseComponentProps } from '../../../types/component.types';
+export interface DndProviderProps extends Omit<BaseComponentProps, 'children'> {
+    /**
+     * Children components
+     */
+    children: ReactNode;
+    /**
+     * Callback when drag starts
+     */
+    onDragStart?: (event: DragStartEvent) => void;
+    /**
+     * Callback when dragging over a droppable
+     */
+    onDragOver?: (event: DragOverEvent) => void;
+    /**
+     * Callback when drag ends
+     */
+    onDragEnd?: (event: DragEndEvent) => void;
+    /**
+     * Callback when drag is cancelled
+     */
+    onDragCancel?: (event: DragStartEvent) => void;
+}
+/**
+ * DndProvider component that wraps the application to enable drag and drop
+ *
+ * @example
+ * ```tsx
+ * <DndProvider onDragEnd={handleDragEnd}>
+ *   <SortableList items={items} onReorder={setItems} />
+ * </DndProvider>
+ * ```
+ */
+export declare const DndProvider: React.FC<DndProviderProps>;
+export default DndProvider;

package/lib/components/dnd/DndProvider/index.d.ts

@@ -0,0 +1,3 @@
+export { DndProvider, type DndProviderProps } from './DndProvider';
+export { DndContext, useDndContext, useDndContextOptional, type DndContextValue, type ActiveDrag, type DragData, type DragEndEvent, type DragStartEvent, type DragOverEvent, } from './DndContext';
+export { default } from './DndProvider';

package/lib/components/dnd/DragHandle/DragHandle.d.ts

@@ -0,0 +1,41 @@
+import { default as React, CSSProperties } from 'react';
+import { BaseComponentProps, ExtendedComponentSize } from '../../../types/component.types';
+export interface DragHandleProps extends Omit<BaseComponentProps, 'children'>, Omit<React.HTMLAttributes<HTMLDivElement>, 'className' | 'style'> {
+    /**
+     * Size of the handle
+     * @default 'md'
+     */
+    size?: ExtendedComponentSize;
+    /**
+     * Visual variant
+     * @default 'dots'
+     */
+    variant?: 'dots' | 'lines' | 'grip';
+    /**
+     * Whether handle is disabled
+     * @default false
+     */
+    disabled?: boolean;
+    /**
+     * Accessible label
+     * @default 'Drag handle'
+     */
+    label?: string;
+    /**
+     * Custom styles
+     */
+    style?: CSSProperties;
+}
+/**
+ * DragHandle component for drag and drop interactions
+ *
+ * @example
+ * ```tsx
+ * <SortableItem>
+ *   <DragHandle {...dragHandleProps} />
+ *   <span>Item content</span>
+ * </SortableItem>
+ * ```
+ */
+export declare const DragHandle: React.ForwardRefExoticComponent<DragHandleProps & React.RefAttributes<HTMLDivElement>>;
+export default DragHandle;

package/lib/components/dnd/DragHandle/index.d.ts

@@ -0,0 +1,2 @@
+export { DragHandle, type DragHandleProps } from './DragHandle';
+export { default } from './DragHandle';

package/lib/components/dnd/DragOverlay/DragOverlay.d.ts

@@ -0,0 +1,39 @@
+import { default as React, ReactNode } from 'react';
+import { BaseComponentProps } from '../../../types/component.types';
+export interface DragOverlayProps extends Omit<BaseComponentProps, 'children'> {
+    /**
+     * Content to render in the overlay
+     * Can be a render function that receives the active drag data
+     */
+    children?: ReactNode | ((activeId: string, activeData: Record<string, unknown>) => ReactNode);
+    /**
+     * Whether to adjust position with scroll
+     * @default true
+     */
+    adjustScale?: boolean;
+    /**
+     * Drop animation duration in ms (0 to disable)
+     * @default 200
+     */
+    dropAnimationDuration?: number;
+    /**
+     * Z-index for the overlay
+     * @default 9999
+     */
+    zIndex?: number;
+}
+/**
+ * DragOverlay component that renders a visual clone during drag operations
+ *
+ * @example
+ * ```tsx
+ * <DndProvider>
+ *   <SortableList items={items} />
+ *   <DragOverlay>
+ *     {(activeId, data) => <Card>{data.title}</Card>}
+ *   </DragOverlay>
+ * </DndProvider>
+ * ```
+ */
+export declare const DragOverlay: React.FC<DragOverlayProps>;
+export default DragOverlay;

package/lib/components/dnd/DragOverlay/index.d.ts

@@ -0,0 +1,2 @@
+export { DragOverlay, type DragOverlayProps } from './DragOverlay';
+export { default } from './DragOverlay';