better-table 1.0.0

package/dist/components/BetterTable/types.d.ts

@@ -0,0 +1,236 @@
+import { ReactNode, CSSProperties } from 'react';
+/**
+ * Tipo base para los datos de la tabla
+ * Permite extensión con tipos específicos del usuario
+ */
+export type TableData = Record<string, unknown>;
+/**
+ * Configuración de columna con tipado genérico
+ */
+export interface Column<T extends TableData = TableData> {
+    /** Identificador único de la columna */
+    id: string;
+    /** Key para acceder al dato (soporta dot notation: 'user.profile.name') */
+    accessor: keyof T | string;
+    /** Texto visible en el header */
+    header: string;
+    /** Tipo de dato para filtrado y renderizado */
+    type?: "string" | "number" | "boolean" | "date" | "custom";
+    /** Render personalizado de celda */
+    cell?: (value: unknown, row: T, rowIndex: number) => ReactNode;
+    /** Render personalizado de header */
+    headerCell?: (column: Column<T>) => ReactNode;
+    /** ¿Columna ordenable? */
+    sortable?: boolean;
+    /** ¿Columna filtrable? */
+    filterable?: boolean;
+    /** Ancho de columna */
+    width?: string | number;
+    /** Alineación del contenido */
+    align?: "left" | "center" | "right";
+    /** Columna oculta */
+    hidden?: boolean;
+}
+/**
+ * Acción de fila individual
+ */
+export interface RowAction<T extends TableData = TableData> {
+    /** Identificador único */
+    id: string;
+    /** Etiqueta de la acción */
+    label: string;
+    /** Icono (string, emoji, o componente) */
+    icon?: ReactNode;
+    /** Modo de ejecución */
+    mode: "callback" | "modal" | "link";
+    /** Callback cuando mode='callback' */
+    onClick?: (row: T, rowIndex: number) => void;
+    /** Componente para modal cuando mode='modal' */
+    modalContent?: React.ComponentType<{
+        data: T;
+        onClose: () => void;
+    }>;
+    /** URL cuando mode='link' */
+    href?: string | ((row: T) => string);
+    /** ¿Mostrar acción condicionalmente? */
+    visible?: (row: T) => boolean;
+    /** ¿Deshabilitar acción condicionalmente? */
+    disabled?: (row: T) => boolean;
+    /** Variante visual */
+    variant?: "default" | "primary" | "danger" | "ghost";
+}
+/**
+ * Acción global (toolbar)
+ */
+export interface GlobalAction<T extends TableData = TableData> {
+    /** Identificador único */
+    id: string;
+    /** Etiqueta del botón */
+    label: string;
+    /** Icono */
+    icon?: ReactNode;
+    /** Callback de ejecución */
+    onClick: (selectedRows: T[], allData: T[]) => void;
+    /** ¿Requiere selección de filas? */
+    requiresSelection?: boolean;
+    /** Variante visual */
+    variant?: "default" | "primary" | "danger";
+}
+/**
+ * Configuración de paginación
+ */
+export interface PaginationConfig {
+    /** Página actual (controlado) */
+    page?: number;
+    /** Items por página */
+    pageSize?: number;
+    /** Opciones de tamaño de página */
+    pageSizeOptions?: number[];
+    /** Total de items (para paginación del servidor) */
+    totalItems?: number;
+    /** Mostrar selector de tamaño de página */
+    showSizeChanger?: boolean;
+    /** Mostrar salto a página */
+    showQuickJumper?: boolean;
+}
+/**
+ * Estado de ordenamiento
+ */
+export interface SortState {
+    columnId: string | null;
+    direction: "asc" | "desc";
+}
+/**
+ * Estado de filtros
+ */
+export interface FilterState {
+    [columnId: string]: string | number | boolean | null;
+}
+/**
+ * Personalización de estilos
+ */
+export interface TableClassNames {
+    /** Clase CSS del contenedor */
+    container?: string;
+    /** Clase CSS de la tabla */
+    table?: string;
+    /** Clase CSS del header */
+    header?: string;
+    /** Clase CSS del body */
+    body?: string;
+    /** Clase CSS de filas */
+    row?: string;
+    /** Clase CSS de celdas */
+    cell?: string;
+    /** Clase CSS de la paginación */
+    pagination?: string;
+    /** Clase CSS del toolbar */
+    toolbar?: string;
+}
+/**
+ * Textos personalizables (i18n)
+ */
+export interface TableLocale {
+    search?: string;
+    searchPlaceholder?: string;
+    noData?: string;
+    loading?: string;
+    page?: string;
+    of?: string;
+    items?: string;
+    selected?: string;
+    rowsPerPage?: string;
+    actions?: string;
+    sortAsc?: string;
+    sortDesc?: string;
+    filterBy?: string;
+    clearFilters?: string;
+    selectAll?: string;
+    deselectAll?: string;
+}
+/**
+ * Locale por defecto
+ */
+export declare const defaultLocale: TableLocale;
+/**
+ * Props principales del componente BetterTable
+ */
+export interface BetterTableProps<T extends TableData = TableData> {
+    /** Array de datos a mostrar */
+    data: T[];
+    /** Configuración de columnas */
+    columns: Column<T>[];
+    /** Key único para identificar filas (default: 'id') */
+    rowKey?: keyof T | ((row: T, index: number) => string);
+    /** Acciones por fila */
+    rowActions?: RowAction<T>[];
+    /** Acciones globales (toolbar) */
+    globalActions?: GlobalAction<T>[];
+    /** Configuración de paginación (false para desactivar) */
+    pagination?: PaginationConfig | false;
+    /** Callback de cambio de página */
+    onPageChange?: (page: number, pageSize: number) => void;
+    /** Estado de ordenamiento (controlado) */
+    sort?: SortState;
+    /** Callback de cambio de ordenamiento */
+    onSortChange?: (sort: SortState) => void;
+    /** Estado de filtros (controlado) */
+    filters?: FilterState;
+    /** Callback de cambio de filtros */
+    onFilterChange?: (filters: FilterState) => void;
+    /** Mostrar barra de búsqueda */
+    searchable?: boolean;
+    /** Valor de búsqueda (controlado) */
+    searchValue?: string;
+    /** Callback de cambio de búsqueda */
+    onSearchChange?: (value: string) => void;
+    /** Columnas en las que buscar (default: todas) */
+    searchColumns?: string[];
+    /** Habilitar selección de filas */
+    selectable?: boolean;
+    /** Filas seleccionadas (controlado) */
+    selectedRows?: T[];
+    /** Callback de cambio de selección */
+    onSelectionChange?: (selectedRows: T[]) => void;
+    /** Modo de selección */
+    selectionMode?: "single" | "multiple";
+    /** Estado de carga */
+    loading?: boolean;
+    /** Componente de loading personalizado */
+    loadingComponent?: ReactNode;
+    /** Componente de estado vacío personalizado */
+    emptyComponent?: ReactNode;
+    /** Clases CSS personalizadas */
+    classNames?: TableClassNames;
+    /** Estilos inline personalizados */
+    styles?: {
+        container?: CSSProperties;
+        table?: CSSProperties;
+        header?: CSSProperties;
+        body?: CSSProperties;
+        row?: CSSProperties;
+        cell?: CSSProperties;
+    };
+    /** Textos personalizados */
+    locale?: TableLocale;
+    /** Header fijo al hacer scroll */
+    stickyHeader?: boolean;
+    /** Altura máxima (activa scroll interno) */
+    maxHeight?: string | number;
+    /** Mostrar bordes */
+    bordered?: boolean;
+    /** Filas con rayas alternas */
+    striped?: boolean;
+    /** Hover en filas */
+    hoverable?: boolean;
+    /** Tamaño de la tabla */
+    size?: "small" | "medium" | "large";
+    /** Callback al hacer click en una fila */
+    onRowClick?: (row: T, rowIndex: number) => void;
+    /** Callback al hacer doble click en una fila */
+    onRowDoubleClick?: (row: T, rowIndex: number) => void;
+    /** Descripción de la tabla para screen readers */
+    ariaLabel?: string;
+    /** ID del elemento que describe la tabla */
+    ariaDescribedBy?: string;
+}

package/dist/components/BetterTable/utils/filterData.d.ts

@@ -0,0 +1,18 @@
+import { TableData, Column, FilterState } from '../types';
+/**
+ * Filtra un array de datos basado en múltiples filtros de columna
+ * @param data - Array de datos a filtrar
+ * @param filters - Estado de filtros por columna
+ * @param columns - Configuración de columnas
+ * @returns Array filtrado (nueva referencia)
+ */
+export declare function filterData<T extends TableData>(data: T[], filters: FilterState, columns: Column<T>[]): T[];
+/**
+ * Realiza una búsqueda global en los datos
+ * @param data - Array de datos
+ * @param searchValue - Valor a buscar
+ * @param columns - Columnas en las que buscar
+ * @param searchColumnIds - IDs de columnas específicas (opcional)
+ * @returns Array filtrado
+ */
+export declare function searchData<T extends TableData>(data: T[], searchValue: string, columns: Column<T>[], searchColumnIds?: string[]): T[];

package/dist/components/BetterTable/utils/getValueFromPath.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Accede a propiedades anidadas de un objeto usando dot notation
+ * @param obj - Objeto del cual extraer el valor
+ * @param path - Ruta al valor (e.g., 'user.profile.name')
+ * @returns El valor encontrado o undefined
+ */
+export declare function getValueFromPath<T = unknown>(obj: Record<string, unknown>, path: string): T | undefined;

package/dist/components/BetterTable/utils/index.d.ts

@@ -0,0 +1,3 @@
+export { getValueFromPath } from './getValueFromPath';
+export { sortData } from './sortData';
+export { filterData, searchData } from './filterData';

package/dist/components/BetterTable/utils/sortData.d.ts

@@ -0,0 +1,9 @@
+import { TableData } from '../types';
+/**
+ * Ordena un array de datos por una columna específica
+ * @param data - Array de datos a ordenar
+ * @param columnId - ID/accessor de la columna
+ * @param direction - Dirección del ordenamiento
+ * @returns Array ordenado (nueva referencia)
+ */
+export declare function sortData<T extends TableData>(data: T[], columnId: string, direction: "asc" | "desc"): T[];

package/dist/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * @juanb/better-table
+ * A modern, flexible, and fully typed React data table component
+ *
+ * @packageDocumentation
+ */
+export { BetterTable } from './components/BetterTable';
+export { defaultLocale } from './components/BetterTable/types';
+export type { BetterTableProps, Column, RowAction, GlobalAction, PaginationConfig, SortState, FilterState, TableClassNames, TableLocale, TableData, } from './components/BetterTable/types';
+export { useTableSort } from './components/BetterTable/hooks/useTableSort';
+export { useTableFilter } from './components/BetterTable/hooks/useTableFilter';
+export { useTablePagination } from './components/BetterTable/hooks/useTablePagination';
+export { useTableSelection } from './components/BetterTable/hooks/useTableSelection';
+export { useTableSearch } from './components/BetterTable/hooks/useTableSearch';
+export { useTableContext, TableProvider, } from './components/BetterTable/context';
+export type { TableContextValue } from './components/BetterTable/context';
+export { getValueFromPath } from './components/BetterTable/utils/getValueFromPath';
+export { sortData } from './components/BetterTable/utils/sortData';
+export { filterData, searchData, } from './components/BetterTable/utils/filterData';

package/dist/styles.cjs

@@ -0,0 +1,2 @@
+"use strict";
+//# sourceMappingURL=styles.cjs.map

package/dist/styles.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"styles.cjs","sources":[],"sourcesContent":[],"names":[],"mappings":""}

package/dist/styles.js

@@ -0,0 +1,2 @@
+
+//# sourceMappingURL=styles.js.map

package/dist/styles.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"styles.js","sources":[],"sourcesContent":[],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,99 @@
+{
+  "name": "better-table",
+  "version": "1.0.0",
+  "description": "A modern, flexible, and fully typed React data table component",
+  "author": "Juan Puca",
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "./dist/better-table.cjs.js",
+  "module": "./dist/better-table.es.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/better-table.es.js"
+      },
+      "require": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/better-table.cjs.js"
+      }
+    },
+    "./styles.css": "./dist/styles.css"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": [
+    "**/*.css"
+  ],
+  "keywords": [
+    "react",
+    "table",
+    "data-table",
+    "datagrid",
+    "typescript",
+    "sorting",
+    "filtering",
+    "pagination",
+    "selection"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jrodrigopuca/BetterTable.git"
+  },
+  "bugs": {
+    "url": "https://github.com/jrodrigopuca/BetterTable/issues"
+  },
+  "homepage": "https://github.com/jrodrigopuca/BetterTable#readme",
+  "peerDependencies": {
+    "react": ">=18.0.0",
+    "react-dom": ">=18.0.0"
+  },
+  "dependencies": {
+    "clsx": "^2.1.1"
+  },
+  "devDependencies": {
+    "@testing-library/jest-dom": "^6.6.3",
+    "@testing-library/react": "^16.1.0",
+    "@testing-library/user-event": "^14.5.2",
+    "@types/node": "^22.10.5",
+    "@types/react": "^19.0.6",
+    "@types/react-dom": "^19.0.2",
+    "@vitejs/plugin-react": "^4.7.0",
+    "@vitest/coverage-v8": "^4.0.0",
+    "@vitest/ui": "^4.0.18",
+    "jsdom": "^27.0.1",
+    "react": "^19.2.4",
+    "react-dom": "^19.2.4",
+    "typescript": "^5.7.3",
+    "vite": "^6.0.5",
+    "vite-plugin-dts": "^4.5.0",
+    "vitest": "^4.0.18"
+  },
+  "scripts": {
+    "dev": "vite --config demo/vite.config.ts",
+    "build": "vite build",
+    "build:types": "tsc -p tsconfig.build.json",
+    "preview": "vite preview",
+    "test": "vitest --config vitest.config.ts",
+    "test:run": "vitest run --config vitest.config.ts",
+    "test:coverage": "vitest run --coverage --config vitest.config.ts",
+    "lint": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "browserslist": {
+    "production": [
+      ">0.2%",
+      "not dead",
+      "not op_mini all"
+    ],
+    "development": [
+      "last 1 chrome version",
+      "last 1 firefox version",
+      "last 1 safari version"
+    ]
+  }
+}