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

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

@@ -0,0 +1,112 @@
+import { default as React } from 'react';
+import { BaseComponentProps } from '../../../types';
+export interface ScrollAreaRef {
+    /**
+     * Scroll to specific position
+     */
+    scrollTo: (options: ScrollToOptions) => void;
+    /**
+     * Scroll to top
+     */
+    scrollToTop: (behavior?: ScrollBehavior) => void;
+    /**
+     * Scroll to bottom
+     */
+    scrollToBottom: (behavior?: ScrollBehavior) => void;
+    /**
+     * Scroll to left
+     */
+    scrollToLeft: (behavior?: ScrollBehavior) => void;
+    /**
+     * Scroll to right
+     */
+    scrollToRight: (behavior?: ScrollBehavior) => void;
+    /**
+     * Get current scroll position
+     */
+    getScrollPosition: () => {
+        scrollTop: number;
+        scrollLeft: number;
+    };
+    /**
+     * Get the viewport element
+     */
+    getElement: () => HTMLDivElement | null;
+}
+export interface ScrollAreaProps extends BaseComponentProps {
+    /**
+     * Scroll direction
+     * @default 'vertical'
+     */
+    direction?: 'vertical' | 'horizontal' | 'both';
+    /**
+     * Maximum height (enables vertical scroll)
+     */
+    maxHeight?: string | number;
+    /**
+     * Maximum width (enables horizontal scroll)
+     */
+    maxWidth?: string | number;
+    /**
+     * Whether to show shadow indicators at scroll edges
+     * @default false
+     */
+    showShadows?: boolean;
+    /**
+     * Callback when scroll position changes
+     */
+    onScroll?: (event: React.UIEvent<HTMLDivElement>) => void;
+    /**
+     * Callback when scrolled to top
+     */
+    onScrollToTop?: () => void;
+    /**
+     * Callback when scrolled to bottom
+     */
+    onScrollToBottom?: () => void;
+    /**
+     * Callback when scrolled to left edge
+     */
+    onScrollToLeft?: () => void;
+    /**
+     * Callback when scrolled to right edge
+     */
+    onScrollToRight?: () => void;
+    /**
+     * Threshold in pixels for scroll end callbacks
+     * @default 10
+     */
+    scrollEndThreshold?: number;
+    /**
+     * Content to render inside scrollable area
+     */
+    children: React.ReactNode;
+}
+/**
+ * ScrollArea component - a custom scrollbar container
+ *
+ * Provides styled scrollbars with various visibility modes and
+ * programmatic scroll control.
+ *
+ * @example
+ * Basic vertical scroll:
+ * ```tsx
+ * <ScrollArea maxHeight={300}>
+ *   <p>Long content here...</p>
+ * </ScrollArea>
+ * ```
+ *
+ * @example
+ * With scroll callbacks:
+ * ```tsx
+ * <ScrollArea
+ *   maxHeight={400}
+ *   onScrollToBottom={() => loadMore()}
+ *   showShadows
+ * >
+ *   {items.map(item => <Item key={item.id} {...item} />)}
+ * </ScrollArea>
+ * ```
+ */
+export declare const ScrollArea: React.ForwardRefExoticComponent<ScrollAreaProps & React.RefAttributes<ScrollAreaRef>>;
+export default ScrollArea;

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

@@ -0,0 +1,3 @@
+export { ScrollArea } from './ScrollArea';
+export type { ScrollAreaProps, ScrollAreaRef } from './ScrollArea';
+export { default } from './ScrollArea';

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>;

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;