tcce-design-system 0.1.22 → 0.1.24

package/dist/tcce-design-system-components.d.ts

@@ -1,16 +1,21 @@
 import { AnchorHTMLAttributes } from 'react';
 import { ButtonHTMLAttributes } from 'react';
+import { Cell } from '@tanstack/react-table';
 import { ChangeEvent } from 'react';
 import { ClipboardEvent as ClipboardEvent_2 } from 'react';
+import { Column } from '@tanstack/react-table';
+import { ColumnDef } from '@tanstack/react-table';
 import { Component } from 'react';
 import { Context } from 'react';
+import { createColumnHelper } from '@tanstack/react-table';
 import { CSSProperties } from 'react';
-import { default as default_2 } from 'react';
 import { DetailedHTMLProps } from 'react';
 import { Dispatch } from 'react';
 import { FastOmit } from 'styled-components';
 import { ForwardRefComponent } from 'motion/react';
 import { ForwardRefExoticComponent } from 'react';
+import { Header as Header_2 } from '@tanstack/react-table';
+import { HeaderGroup } from '@tanstack/react-table';
 import { HTMLAttributeAnchorTarget } from 'react';
 import { HTMLAttributes } from 'react';
 import { HTMLMotionProps } from 'motion/react';
@@ -19,19 +24,24 @@ import { IStyledComponentBase } from 'styled-components/dist/types';
 import { JSX } from 'react/jsx-runtime';
 import { KeyboardEvent as KeyboardEvent_2 } from 'react';
 import { LabelHTMLAttributes } from 'react';
+import { MemoExoticComponent } from 'react';
 import { MouseEventHandler } from 'react';
 import { PropsWithChildren } from 'react';
 import { ReactNode } from 'react';
 import { RefAttributes } from 'react';
 import { RefObject } from 'react';
 import { RemixiconComponentType } from '@remixicon/react';
+import { Row } from '@tanstack/react-table';
 import { RuleSet } from 'styled-components';
 import { SelectHTMLAttributes } from 'react';
 import { SetStateAction } from 'react';
+import { SortingState } from '@tanstack/react-table';
 import { Substitute } from 'styled-components/dist/types';
+import { Table as TanStackTableType } from '@tanstack/react-table';
 import { TextareaHTMLAttributes } from 'react';
 import { toast } from 'sonner';
 import { ToasterProps } from 'sonner';
+import { Updater } from '@tanstack/react-table';
 
 /**
  * Valid input types supported by the FormField component
@@ -90,8 +100,6 @@ declare type BadgeSize = 'sm' | 'md' | 'lg';
  */
 declare type BadgeVariant = 'primary' | 'secondary' | 'success' | 'warning' | 'danger' | 'neutral' | 'outline';
 
-export declare const baseContentTableStyles: RuleSet<object>;
-
 export declare const baseFieldStyles: RuleSet<object>;
 
 export declare interface BaseFormFieldProps extends Omit<InputHTMLAttributes<HTMLInputElement>, 'size'> {
@@ -127,7 +135,7 @@ export declare interface BaseLabelProps extends LabelHTMLAttributes<HTMLLabelEle
  * @property {string} [title] - Optional title for accessibility.
  * @property {Variant} [variant] - Animation variant of the spinner.
  */
-declare interface BaseSpinnerProps {
+export declare interface BaseSpinnerProps {
     size?: Size;
     color?: ColorKey;
     centered?: boolean;
@@ -136,12 +144,6 @@ declare interface BaseSpinnerProps {
     variant?: Variant;
 }
 
-export declare const baseTableCellsSizes: {
-    sm: RuleSet<object>;
-    md: RuleSet<object>;
-    lg: RuleSet<object>;
-};
-
 export declare const bodyTextStyles: {
     80: RuleSet<object>;
     60: RuleSet<object>;
@@ -195,6 +197,8 @@ export declare type CardSize = 'sm' | 'md' | 'lg';
 
 export declare type CardVariant = 'elevated' | 'flat' | 'info';
 
+export declare type CellAlignment = 'left' | 'center' | 'right';
+
 export declare const Checkbox: ForwardRefExoticComponent<CheckboxProps & RefAttributes<HTMLInputElement>>;
 
 export declare const CheckboxInput: ForwardRefExoticComponent<CheckboxInputProps & RefAttributes<HTMLInputElement>>;
@@ -233,10 +237,58 @@ export declare interface CheckboxSpecificProps {
  */
 export declare const CloseOpenButton: IStyledComponentBase<"web", FastOmit<DetailedHTMLProps<ButtonHTMLAttributes<HTMLButtonElement>, HTMLButtonElement>, never>> & string;
 
-declare type ColorKey = 'primary' | 'orange' | 'white' | 'gray';
+export declare type ColorKey = 'primary' | 'orange' | 'white' | 'gray';
 
 declare type ColorKey_2 = 'primary' | 'orange' | 'white' | 'gray';
 
+export { Column }
+
+export { ColumnDef }
+
+/**
+ *
+ * Column metadata for additional configurations
+ * Includes alignment, size, sortable, filterable, truncate, variant, and width
+ */
+export declare interface ColumnMeta {
+    align?: CellAlignment;
+    size?: TableCellSize;
+    sortable?: boolean;
+    filterable?: boolean;
+    ellipsis?: boolean;
+    variant?: 'default' | 'numeric';
+    width?: string | number;
+}
+
+/**
+ * Creates URLSearchParams for backend pagination with sorting
+ * Compatible with Laravel PaginateHelper
+ *
+ * @param options - Pagination and sorting options
+ * @returns URLSearchParams ready to append to API request
+ *
+ * @example
+ * ```ts
+ * const params = createBackendParams({
+ *   sorting: [{ id: 'name', desc: false }],
+ *   perPage: 20,
+ *   genericSearch: 'john',
+ *   filters: { role: 'admin', status: 'active' }
+ * });
+ *
+ * fetch(`/api/users?${params.toString()}`);
+ * // Result: /api/users?sorts={"name":"asc"}&perPage=20&genericSearch=john&filters={"role":"admin","status":"active"}
+ * ```
+ */
+export declare function createBackendParams(options: {
+    sorting?: SortingState;
+    perPage?: number;
+    genericSearch?: string;
+    filters?: Record<string, unknown>;
+}): URLSearchParams;
+
+export { createColumnHelper }
+
 /**
  * Helper to create field configurations for common patterns
  */
@@ -515,6 +567,27 @@ export declare type FormFieldSize = 'sm' | 'md' | 'lg';
 
 export declare type FormFieldState = 'default' | 'hover' | 'focus' | 'error' | 'disabled';
 
+/**
+ * FullScreenSpinner Component
+ * Renders a full-screen spinner with an optional message.
+ * @param {FullScreenSpinnerProps} props - Props for the FullScreenSpinner component see in Spinner.types.ts .
+ * @returns JSX.Element The rendered FullScreenSpinner component.
+ */
+export declare const FullScreenSpinner: ({ message, color, variant, }: FullScreenSpinnerProps) => JSX.Element;
+
+/**
+ * Props for the FullScreenSpinner component.
+ * @interface FullScreenSpinnerProps
+ * @property {string} [message] - Optional message to display with the spinner.
+ * @property {ColorKey} [color] - Color variant of the spinner.
+ * @property {Variant} [variant] - Animation variant of the spinner.
+ */
+export declare interface FullScreenSpinnerProps {
+    message?: string;
+    color?: ColorKey;
+    variant?: Variant;
+}
+
 /**
  * Retrieves the value of a cookie by name
  * @param name - The name of the cookie to retrieve
@@ -1076,6 +1149,8 @@ export declare interface RadioSpecificProps {
     onRadioChange?: (event: ChangeEvent<HTMLInputElement>) => void;
 }
 
+export { Row }
+
 export declare const SearchInput: ({ size, leftIcon, rightIcon, iconSize, iconColor, placeholder, onSearch, className, ...props }: SearchInputProps) => JSX.Element;
 
 export declare interface SearchInputProps extends BaseInputProps {
@@ -1089,6 +1164,27 @@ export declare interface SearchSpecificProps {
     onSearch?: (value: string) => void;
 }
 
+/**
+ * SectionSpinner Component
+ * Renders a spinner suitable for section loading states with an optional message.
+ * @param {SectionSpinnerProps} props - Props for the SectionSpinner component see in Spinner.types.ts .
+ * @returns JSX.Element The rendered SectionSpinner component.
+ */
+export declare const SectionSpinner: ({ message, color, variant, }: SectionSpinnerProps) => JSX.Element;
+
+/**
+ * Props for the SectionSpinner component
+ * @interface SectionSpinnerProps
+ * @property {string} [message] - Optional message to display with the spinner.
+ * @property {ColorKey} [color] - Color variant of the spinner.
+ * @property {Variant} [variant] - Animation variant of the spinner.
+ */
+export declare interface SectionSpinnerProps {
+    message?: string;
+    color?: ColorKey;
+    variant?: Variant;
+}
+
 export declare const SelectInput: ForwardRefExoticComponent<SelectInputProps & RefAttributes<HTMLButtonElement>>;
 
 export declare interface SelectInputProps extends Omit<SelectHTMLAttributes<HTMLSelectElement>, 'size'> {
@@ -1196,7 +1292,7 @@ export declare const SidebarProvider: ({ children }: PropsWithChildren) => JSX.E
  * Animation variant options for the Spinner component.
  * typedef {('rotate' | 'sweep')} Variant
  */
-declare type Size = 'sm' | 'md' | 'lg' | 'xl';
+export declare type Size = 'sm' | 'md' | 'lg' | 'xl';
 
 export declare const sizeStyles: {
     sm: RuleSet<object>;
@@ -1321,10 +1417,71 @@ export declare const smartAnimation: {
 
 export declare type SortDirection = 'asc' | 'desc' | 'none';
 
-export declare interface SortState {
-    columnId: string | null;
-    direction: SortDirection;
-}
+export { SortingState }
+
+/**
+ * Converts SortingState to JSON string ready to send to Laravel backend
+ * This is a convenience function for API calls
+ *
+ * @param sortingState - TanStack sorting state array
+ * @returns JSON string representation of sort record
+ *
+ * @example
+ * ```ts
+ * const sortingState = [{ id: 'name', desc: false }];
+ * const sortsParam = sortingStateToJsonString(sortingState);
+ * // Result: '{"name":"asc"}'
+ *
+ * // Use in API call:
+ * fetch(`/api/users?sorts=${sortsParam}`);
+ * ```
+ */
+export declare function sortingStateToJsonString(sortingState: SortingState): string;
+
+/**
+ * Converts TanStack Table SortingState to backend-friendly record format
+ *
+ * @param sortingState - TanStack sorting state array
+ * @returns Object with field names as keys and 'asc'/'desc' as values
+ *
+ * @example
+ * ```ts
+ * const sortingState = [
+ *   { id: 'name', desc: false },
+ *   { id: 'created_at', desc: true }
+ * ];
+ *
+ * const sortRecord = sortingStateToRecord(sortingState);
+ * // Result: { name: 'asc', created_at: 'desc' }
+ * ```
+ */
+export declare function sortingStateToRecord(sortingState: SortingState): SortRecord;
+
+/**
+ * Backend sorting format - object representation
+ * Example: { name: 'asc', created_at: 'desc' }
+ */
+export declare type SortRecord = Record<string, 'asc' | 'desc'>;
+
+/**
+ * Converts backend sort record to TanStack Table SortingState
+ * Useful for initializing sorting state from backend response
+ *
+ * @param sortRecord - Object with field names and sort directions
+ * @returns TanStack sorting state array
+ *
+ * @example
+ * ```ts
+ * const sortRecord = { name: 'asc', created_at: 'desc' };
+ *
+ * const sortingState = sortRecordToSortingState(sortRecord);
+ * // Result: [
+ * //   { id: 'name', desc: false },
+ * //   { id: 'created_at', desc: true }
+ * // ]
+ * ```
+ */
+export declare function sortRecordToSortingState(sortRecord: SortRecord): SortingState;
 
 /**
  * Spinner Component
@@ -1403,117 +1560,146 @@ export declare const submenuAnimationTopDown: {
 };
 
 /**
- * Table component for rendering customizable tables with support for
- * sticky headers, sorting, and custom cell rendering.
- *
- * @param columns - Array of column definitions.
- * @param rows - Array of row data.
- * @param size - Table size variant ('sm', 'md', 'lg'). Default is 'md'.
- * @param variant - Table visual variant. Default is 'default'.
- * @param className - Optional CSS class for the table.
- * @param stickyHeader - Enables sticky table headers.
- * @param onSortChange - Callback for sort direction changes.
+ * Main Table component
+ * Uses TanStack Table v8 as headless layer
  */
 export declare const Table: {
-    ({ columns, rows, size, variant, tableWrapperClassName, tableClassName, stickyHeader, onSortChange, }: TableProps): JSX.Element;
+    <T extends Record<string, unknown>>({ data, columns, size, variant, stickyHeader, maxHeight, sorting, defaultSorting, onSortingChange, onRowClick, className, emptyMessage, enableSorting, manualSorting, isLoading, }: TableProps<T>): JSX.Element;
     displayName: string;
 };
 
+export declare const TableBody: <T extends Record<string, unknown>>({ rows }: TableBodyProps<T>) => JSX.Element;
+
+declare interface TableBodyProps<T> {
+    rows: Row<T>[];
+}
+
+export declare const TableCell: <T extends Record<string, unknown>>({ cell }: TableCellProps<T>) => JSX.Element;
+
+declare interface TableCellProps<T> {
+    cell: Cell<T, unknown>;
+}
+
+export declare type TableCellSize = 'sm' | 'md' | 'lg';
+
 /**
- * TableCell component for rendering a styled table cell with optional icons and content.
- *
- * @param {TableCellProps} props - Props for the TableCell component you can see them in @components/tables/types/table.types.ts.
- * @returns {JSX.Element} The rendered table cell.
+ * Extended ColumnDef type that includes metadata
  */
-export declare const TableCell: default_2.FC<TableCellProps>;
+export declare type TableColumnDef<T> = ColumnDef<T, unknown> & {
+    meta?: ColumnMeta;
+};
 
-export declare interface TableCellData<T = default_2.ReactNode> extends WithIconsProps {
-    content: default_2.ReactNode | T;
-    size?: TableCellSize;
-    align?: 'left' | 'center' | 'right';
-    width?: string | number;
-    truncate?: boolean;
-    variant?: 'default' | 'numeric';
-    className?: string;
+/**
+ * Table context to share state between components
+ */
+export declare interface TableContextType<T> {
+    size: TableCellSize;
+    variant: TableVariant;
+    sorting: SortingState;
+    setSorting: (state: SortingState) => void;
+    onRowClick?: (row: T) => void;
 }
 
-export declare interface TableCellProps extends default_2.HTMLAttributes<HTMLTableCellElement>, WithIconsProps {
-    children: default_2.ReactNode;
-    size?: TableCellSize;
-    align?: 'left' | 'center' | 'right';
-    width?: string | number;
-    truncate?: boolean;
-    variant?: 'default' | 'numeric';
+export declare const TableHeader: <T extends Record<string, unknown>>({ headerGroups, stickyHeader, }: TableHeadProps<T>) => JSX.Element;
+
+export declare const TableHeaderCell: <T extends Record<string, unknown>>({ header, }: TableHeaderCellProps<T>) => JSX.Element;
+
+declare interface TableHeaderCellProps<T> {
+    header: Header_2<T, unknown>;
 }
 
-export declare type TableCellSize = 'sm' | 'md' | 'lg';
+export declare const TableHeaderRow: <T extends Record<string, unknown>>({ headerGroup, }: TableHeaderRowProps<T>) => JSX.Element;
 
-export declare interface TableColumnDef<T = default_2.ReactNode> extends WithIconsProps, Omit<TableHeaderCellProps, 'children' | 'onSort'> {
-    id?: string;
-    header: default_2.ReactNode | T;
-    sortable?: boolean;
-    filterable?: boolean;
-    resizable?: boolean;
-    fixed?: 'left' | 'right';
+declare interface TableHeaderRowProps<T> {
+    headerGroup: HeaderGroup<T>;
+}
+
+declare interface TableHeadProps<T> {
+    headerGroups: HeaderGroup<T>[];
     stickyHeader?: boolean;
-    onSort?: (direction: SortDirection) => void;
 }
 
 /**
- * TableHeaderCell component for rendering a table header cell with optional sorting and icons.
  *
- * @param {TableHeaderCellProps} props - The props for the TableHeaderCell component.
- * @returns {JSX.Element} The rendered table header cell.
+ * TablePagination component for paginating table data
+ * @params TablePaginationProps
+ * @returns JSX.Element
  */
-export declare const TableHeaderCell: default_2.FC<TableHeaderCellProps>;
+export declare const TablePagination: ({ onPageChange, onPerPageChange, perPage, page, totalPages, totalRecords, rowsPerPageOptions, }: TablePaginationProps) => JSX.Element;
 
-export declare interface TableHeaderCellProps extends default_2.HTMLAttributes<HTMLTableCellElement>, WithIconsProps {
-    children: default_2.ReactNode;
-    size?: TableCellSize;
-    sortable?: boolean;
-    sortDirection?: SortDirection;
-    align?: 'left' | 'center' | 'right';
-    width?: string | number;
-    active?: boolean;
-    fixed?: 'left' | 'right';
-    onSort?: (direction: SortDirection) => void;
+/**
+ * Props for TablePagination component
+ * @prop onPageChange - Callback when page changes
+ * @prop onPerPageChange - Callback when rows per page changes
+ * @prop perPage - Current rows per page
+ * @prop page - Current active page
+ * @prop totalPages - Total number of pages
+ * @prop totalRecords - (Optional) Total number of records
+ * @prop rowsPerPageOptions - (Optional) Options for rows per page selection
+ */
+export declare interface TablePaginationProps {
+    onPageChange: (newPage: number) => void;
+    onPerPageChange: (newPerPage: number) => void;
+    perPage: number;
+    page: number;
+    totalPages: number;
+    totalRecords?: number;
+    rowsPerPageOptions?: SelectOption[];
 }
 
-export declare const tableHoverMixin: RuleSet<object>;
-
-export declare const tableIconContainerStyles: RuleSet<object>;
-
-export declare interface TableProps<T = default_2.ReactNode> {
+/**
+ * Main Table component props
+ */
+export declare interface TableProps<T = unknown> {
+    data: T[];
     columns: TableColumnDef<T>[];
-    rows: TableRowData<T>[];
     size?: TableCellSize;
     variant?: TableVariant;
-    tableWrapperClassName?: string;
-    tableClassName?: string;
+    isLoading?: boolean;
     stickyHeader?: boolean;
-    sortState?: SortState;
-    onSortChange?: (state: SortState) => void;
+    maxHeight?: string | number;
+    /**
+     * Controlled sorting state
+     * When provided, the table operates in controlled mode
+     */
+    sorting?: SortingState;
+    /**
+     * Default sorting for uncontrolled mode
+     * @default []
+     */
+    defaultSorting?: SortingState;
+    /**
+     * Callback fired when sorting changes
+     * Required for controlled mode, optional for uncontrolled
+     */
+    onSortingChange?: (state: SortingState) => void;
+    /**
+     * Enable/disable sorting functionality
+     * @default true
+     */
+    enableSorting?: boolean;
+    /**
+     * Enable manual sorting mode (sorting handled by backend)
+     * When true, the table will not sort data locally.
+     * Data must be pre-sorted by the backend and passed via the 'data' prop.
+     * The table will maintain sorting UI state and fire onSortingChange callbacks.
+     * @default false
+     */
+    manualSorting?: boolean;
+    onRowClick?: (row: T) => void;
+    className?: string;
+    emptyMessage?: ReactNode;
 }
 
-export declare const tableResponsiveMixin: RuleSet<object>;
+export declare const TableRow: MemoExoticComponent<(<T extends Record<string, unknown>>({ row, }: TableRowProps<T>) => JSX.Element)>;
 
-export declare interface TableRowData<T = default_2.ReactNode> {
-    id?: string | number;
-    cells?: TableCellData<T>[];
-    size?: TableCellSize;
-    align?: 'left' | 'center' | 'right';
-    width?: string | number;
-    truncate?: boolean;
-    variant?: 'default' | 'numeric';
-    className?: string;
+declare interface TableRowProps<T> {
+    row: Row<T>;
 }
 
 export declare type TableVariant = 'default' | 'striped';
 
-export declare const tableVariants: {
-    default: RuleSet<object>;
-    striped: RuleSet<object>;
-};
+export { TanStackTableType }
 
 export declare const TermsAndConditions: ({ isOpen, onAccept, onCancel, title, subtitle, content, bodyFooter, confirmationLabel, acceptLabel, cancelLabel, size, fullScreen, showCloseButton, closeOnBackdropClick, containerClassName, headerClassName, bodyClassName, footerClassName, initiallyConfirmed, onConfirmChange, }: TermsAndConditionsProps) => JSX.Element;
 
@@ -1640,6 +1826,67 @@ export declare interface UserProfileProps {
 
 export declare const useSidebar: () => SidebarContextValue;
 
+export declare const useTableContext: <T extends Record<string, unknown>>() => TableContextType<T>;
+
+/**
+ * Hook to manage table sorting state (controlled or uncontrolled)
+ *
+ * @example Uncontrolled mode
+ * ```tsx
+ * const { sortingState, handleSortingChange } = useTableSorting({
+ *   defaultSorting: [{ id: 'name', desc: false }],
+ *   onSortingChange: (state) => console.log(state)
+ * });
+ * ```
+ *
+ * @example Controlled mode
+ * ```tsx
+ * const [sorting, setSorting] = useState<SortingState>([]);
+ * const { sortingState, handleSortingChange } = useTableSorting({
+ *   sorting,
+ *   onSortingChange: setSorting
+ * });
+ * ```
+ */
+export declare const useTableSorting: ({ sorting: controlledSorting, defaultSorting, onSortingChange, }: UseTableSortingProps) => UseTableSortingReturn;
+
+export declare interface UseTableSortingProps {
+    /**
+     * Controlled sorting state (optional)
+     * If provided, the component operates in controlled mode
+     */
+    sorting?: SortingState;
+    /**
+     * Default sorting state for uncontrolled mode
+     * @default []
+     */
+    defaultSorting?: SortingState;
+    /**
+     * Callback fired when sorting changes
+     * Required for controlled mode, optional for uncontrolled
+     */
+    onSortingChange?: (sorting: SortingState) => void;
+}
+
+export declare interface UseTableSortingReturn {
+    /**
+     * Current sorting state (controlled or internal)
+     */
+    sortingState: SortingState;
+    /**
+     * Handler for TanStack Table's onSortingChange
+     */
+    handleSortingChange: (updater: Updater<SortingState>) => void;
+    /**
+     * Whether the component is in controlled mode
+     */
+    isControlled: boolean;
+    /**
+     * Manual setter for uncontrolled mode (useful for imperative actions)
+     */
+    setSorting: (sorting: SortingState) => void;
+}
+
 /**
  * Validates if a complete code meets certain criteria
  *
@@ -1650,7 +1897,7 @@ export declare const useSidebar: () => SidebarContextValue;
  */
 export declare const validateCode: (code: string, length: number, type?: "text" | "number") => boolean;
 
-declare type Variant = 'rotate' | 'sweep';
+export declare type Variant = 'rotate' | 'sweep';
 
 /**
  * Interfaz base para componentes que soportan iconos a la izquierda y derecha