innoboxrr-react-datatable 2.2.0 → 3.0.0

package/README.md

@@ -1,87 +1,103 @@
 # innoboxrr-react-datatable
 
-Gemelo React de [`innoboxrr-vue-datatable`](../vue-datatable). Los mismos props,
-el mismo contrato de modelo.
+Gemelo React de [`innoboxrr-vue-datatable`](../vue-datatable): los mismos
+props, el mismo contrato de modelo y el mismo comportamiento —barra de
+acciones, filtros, orden y paginación en el servidor, selección con acciones
+masivas, permisos antes de abrir cada menú, esqueletos y errores que se ven—.
 
-El contrato vive en `resources/<framework>/src/models/<entity>/index.js`, que
-es **el mismo archivo** para Vue y para React: funciones puras y llamadas HTTP,
-sin nada de un framework de UI. Por eso las dos tablas reciben lo mismo.
+Por debajo, [TanStack Table](https://tanstack.com/table) lleva el estado de la
+tabla y `innoboxrr-react-form-elements` pone el menú, los iconos y los
+esqueletos, con el tema de `innoboxrr-form-core`.
 
 ## Instalación
 
 ```
-npm i innoboxrr-react-datatable
+npm i innoboxrr-react-datatable innoboxrr-form-core innoboxrr-react-form-elements react-router-dom
+```
+
+```js
+import 'innoboxrr-form-core/styles'
 ```
 
 ## Uso
 
 ```jsx
+import { useRef, useState } from 'react'
 import DataTable, { registerRoutes } from 'innoboxrr-react-datatable'
-import * as postModel from './models/post'
+import * as productModel from './models/product'
 
 registerRoutes({
-    AdminCreatePost: '/admin/posts/create',
-    AdminEditPost: '/admin/posts/:id/edit',
-    AdminShowPost: '/admin/posts/:id',
+    AdminCreateProduct: '/admin/products/create',
+    AdminEditProduct: '/admin/products/:id/edit',
 })
 
-<DataTable
-    dataUrl={route('api.acme.blog.post.index')}
-    policyUrl={route('api.acme.blog.post.policies')}
-    model={postModel}
-    filterForm={<FilterForm onSubmit={setFilters} />} />
+export default function Products() {
+    const table = useRef(null)
+    const [filters, setFilters] = useState({})
+
+    // Tras crear o editar en un drawer: table.current.refresh()
+
+    return (
+        <DataTable
+            ref={table}
+            dataUrl={route('api.acme.shop.product.index')}
+            dataMethod="get"
+            policyUrl={route('api.acme.shop.product.policies')}
+            policyMethod="get"
+            model={productModel}
+            formFilters={filters}
+            selectable
+            filterForm={<FilterForm onSubmit={setFilters} />} />
+    )
+}
 ```
 
+Los avisos y las confirmaciones necesitan, una vez en la aplicación,
+`ToastRegionComponent` y `ConfirmHostComponent` de
+`innoboxrr-react-form-elements`.
+
+Los props, el contrato del modelo, `bulkActions`, los permisos y lo que se ve
+mientras carga o cuando falla están descritos en el
+[README de la versión Vue](../vue-datatable/README.md): son idénticos.
+
 ## Equivalencias con la versión Vue
 
 | Vue | React |
 |---|---|
-| `<slot name="filterForm">` | prop `filterForm` (React no tiene slots con nombre) |
-| `@sortColumn`, `@actionClicked`… | props `onSortColumn`, `onActionClicked`… |
-| `defineExpose({ crudActions, dataTable, pagination })` | el hook `useDataTable`, exportado |
-| rutas con nombre de vue-router | `registerRoutes()` (ver abajo) |
-| `uk-toggle` sobre el formulario de filtros | estado del componente |
+| `<template #filterForm>` | prop `filterForm` |
+| `ref` con `defineExpose` | `ref` (React 19): `refresh()`, `clearSelection()`, `selectedIds`, `table` |
+| rutas con nombre de vue-router | `registerRoutes()` (abajo) |
+| componente de celda con `@callback` | componente de celda con `onCallback` |
 
-Todo lo demás —`dataUrl`, `dataMethod`, `model`, `policyUrl`, `policyMethod`,
-`showTopbar`, `hasActions`, `hasFilter`, `formFilters`, `externalFilters`,
-`extraParams`, `extraQuery`, `hideColumns`, `cardWrapper`, `showTableHeader`—
-se llama y significa lo mismo.
+La lógica común —columnas, petición, errores, acciones— vive en
+`src/table.js`, que es el mismo archivo en los dos paquetes.
 
 ## Rutas con nombre
 
-El contrato del modelo apunta a rutas **por nombre**:
-
-```js
-params: { to: { name: 'AdminEditPost', params: { id: 1 } } }
-```
-
-vue-router resuelve eso de fábrica; React Router 7 no tiene rutas con nombre.
-`registerRoutes({ nombre: patrón })` cierra ese hueco, y el módulo generado lo
-llama al montarse. Una ruta sin registrar **lanza**: devolver `#` escondería el
-fallo hasta que alguien hiciera clic.
+El contrato apunta a rutas **por nombre** (`params.to.name`). React Router 7 no
+las tiene, así que `registerRoutes({ nombre: patrón })` dice a qué patrón
+corresponde cada una. Una acción hacia una ruta sin registrar avisa al usuario y
+deja el detalle en la consola.
 
 ## `useDataTable`
 
-Toda la lógica —cargar, ordenar, paginar, resolver políticas— está en el hook,
-fuera del componente. Se puede probar sin montar nada y sirve para pintar la
-misma tabla de otra forma:
-
 ```jsx
-const { dataTable, pagination, sortColumn, updatePage } = useDataTable({ ... })
+import { useDataTable } from 'innoboxrr-react-datatable'
+
+const { table, rows, meta, loading, error, sortColumn, updatePage, refresh } = useDataTable({ ...props, navigate, labels })
 ```
 
-## Diferencias deliberadas
-
-- **El clon de cada fila se hace una vez por repintado**, no en una caché de
-  módulo. La versión Vue guarda los clones en un `WeakMap` global, así que un
-  `parser` que escriba en su fila envenena esa copia para el resto de la vida
-  de la página, y dos tablas que compartan objetos de fila comparten clones.
-- **La paginación no tiene estado propio.** En Vue lo tenía y se le
-  desincronizaba cuando la página cambiaba desde fuera, por ejemplo al
-  reiniciar los filtros.
-- **`ActionListComponent` es uno solo.** En Vue el bloque de acciones está
-  copiado en `DataTable.vue` y en `DataTableComponent.vue`, y las dos copias no
-  hacen lo mismo: la de dentro soporta `action.link` y la de fuera no.
+## De 2.x a 3.0
+
+- Ya no existen `ActionListComponent`, `DatatableIcon`, `NavDropdownComponent`,
+  `IconRouteComponent`, `IconLinkComponent` ni `DisabledLinkComponent`.
+- `DataTableComponent` recibe la instancia de TanStack Table en `table`;
+  `SelectPaginationComponent` sigue recibiendo `meta` y `onPageChange`.
+- Las acciones de ruta navegan desde el menú con `useNavigate`.
+- Los textos están en español y se cambian con `labels`.
+- Un fallo ya no se reintenta: se ve, y se reintenta a mano.
+- `innoboxrr-react-form-elements` pasa a ser dependencia par, y
+  `innoboxrr-form-core` sube a `^2.6`.
 
 ## Pruebas
 

package/index.js

@@ -1,10 +1,10 @@
 /**
  * Gemelo React de innoboxrr-vue-datatable.
  *
- * El export por defecto es la tabla, igual que en la version Vue. Se exponen
- * ademas el hook con la logica (por si alguien quiere pintarla de otra forma)
- * y el registro de rutas con nombre, que es lo que React Router no trae y el
- * contrato del modelo necesita.
+ * El export por defecto es la tabla, igual que en la versión Vue. Se exponen
+ * además la lógica (por si alguien quiere pintarla de otra forma), las piezas
+ * con las que está hecha y el registro de rutas con nombre, que es lo que
+ * React Router no trae y el contrato del modelo necesita.
  */
 
 import DataTable from './src/DataTable.jsx'
@@ -15,3 +15,4 @@ export { default as useDataTable } from './src/useDataTable.js'
 export { buildPath, hasRoute, registerRoutes, resetRoutes } from './src/routes.js'
 export { default as DataTableComponent } from './src/components/DataTableComponent.jsx'
 export { default as SelectPaginationComponent } from './src/components/SelectPaginationComponent.jsx'
+export { DEFAULT_LABELS } from './src/table.js'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "innoboxrr-react-datatable",
-  "version": "2.2.0",
+  "version": "3.0.0",
   "description": "Gemelo React de innoboxrr-vue-datatable: el mismo contrato de modelo, la misma tabla.",
   "type": "module",
   "main": "index.js",
@@ -37,11 +37,12 @@
     "node": ">=20"
   },
   "dependencies": {
-    "@iconify/react": "^6.0.0",
+    "@tanstack/react-table": "^9.2.4",
     "axios": "^1.7.0"
   },
   "peerDependencies": {
-    "innoboxrr-form-core": "^2.2.0",
+    "innoboxrr-form-core": "^2.6.0",
+    "innoboxrr-react-form-elements": "^3.4.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
     "react-router-dom": "^7.0.0"
@@ -51,6 +52,8 @@
     "@testing-library/react": "^16.1.0",
     "@testing-library/user-event": "^14.5.2",
     "@vitejs/plugin-react": "^5.0.0",
+    "innoboxrr-form-core": "^2.6.0",
+    "innoboxrr-react-form-elements": "^3.4.0",
     "jsdom": "^25.0.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",

package/src/DataTable.jsx

@@ -1,9 +1,14 @@
-import { useState } from 'react'
-import ActionListComponent from './components/ActionListComponent.jsx'
+import { useCallback, useId, useImperativeHandle, useMemo, useState } from 'react'
+import { useNavigate } from 'react-router-dom'
+import IconComponent from 'innoboxrr-react-form-elements/src/IconComponent.jsx'
+import MenuComponent from 'innoboxrr-react-form-elements/src/MenuComponent.jsx'
+
 import DataTableComponent from './components/DataTableComponent.jsx'
-import NavDropdownComponent from './components/NavDropdownComponent.jsx'
 import SelectPaginationComponent from './components/SelectPaginationComponent.jsx'
+import { buildPath } from './routes.js'
+import { DEFAULT_LABELS, menuItems } from './table.js'
 import useDataTable from './useDataTable.js'
+import useTheme, { joinClasses } from './useTheme.js'
 
 /**
  * Gemelo de DataTable.vue.
@@ -13,10 +18,11 @@ import useDataTable from './useDataTable.js'
  * puras y llamadas HTTP, sin nada de un framework de UI. Por eso este
  * componente recibe exactamente los mismos props que su gemelo.
  *
- * La única diferencia real: el slot `filterForm` de Vue aquí es el prop
- * `filterForm`, porque React no tiene slots con nombre.
+ * Las diferencias son de React: el slot `filterForm` es un prop, y lo que Vue
+ * expone con defineExpose —`refresh()`, `clearSelection()`— llega por `ref`.
  */
 export default function DataTable({
+    ref = null,
     dataUrl,
     dataMethod = 'post',
     model,
@@ -32,19 +38,46 @@ export default function DataTable({
     hideColumns = [],
     cardWrapper = true,
     showTableHeader = true,
+    selectable = false,
+    labels = null,
     filterForm = null,
 }) {
+    const theme = useTheme()
+    const routerNavigate = useNavigate()
+
     const [filtersOpen, setFiltersOpen] = useState(false)
+    const filtersId = useId()
+
+    const text = useMemo(() => ({ ...DEFAULT_LABELS, ...(labels ?? {}) }), [labels])
+
+    // React Router no tiene rutas con nombre: el contrato apunta a un nombre y
+    // `registerRoutes` dice a qué patrón corresponde.
+    const navigate = useCallback(
+        (target) => routerNavigate(buildPath(target.name, target.params, target.query)),
+        [routerNavigate]
+    )
 
     const {
-        dataTable,
-        pagination,
+        table,
+        visibleHead,
+        rows,
+        clones,
+        meta,
+        loading,
+        error,
+        sort,
+        orderBy,
         crudActions,
-        updateFilters,
+        bulkActions,
+        rowActions,
+        selectedIds,
+        refresh,
+        clearSelection,
         sortColumn,
         updatePage,
-        actionClicked,
-        actionButtonClicked,
+        preparePolicies,
+        run,
+        runBulk,
     } = useDataTable({
         dataUrl,
         dataMethod,
@@ -53,99 +86,135 @@ export default function DataTable({
         policyMethod,
         formFilters,
         externalFilters,
+        extraParams,
+        extraQuery,
         hideColumns,
+        selectable,
+        labels: text,
+        navigate,
     })
 
-    const dataTableComponents = typeof model.dataTableComponents === 'function'
-        ? model.dataTableComponents()
-        : {}
+    useImperativeHandle(ref, () => ({ refresh, clearSelection, selectedIds, table }), [refresh, clearSelection, selectedIds, table])
+
+    const dataTableComponents = useMemo(
+        () => (typeof model.dataTableComponents === 'function' ? model.dataTableComponents() : {}),
+        [model]
+    )
+
+    const crudItems = useMemo(() => menuItems(crudActions, text, run), [crudActions, text, run])
+    const rowItems = useCallback((row) => menuItems(rowActions(row), text, run), [rowActions, text, run])
+    const prepareCrud = useCallback(() => preparePolicies(null), [preparePolicies])
+
+    const bulkVisible = selectable && selectedIds.length > 0
+
+    const renderBar = () => {
+        // Con filas seleccionadas, la barra dice cuántas y qué hacer con ellas,
+        // en el mismo sitio que la de siempre para que la tabla no salte.
+        if (bulkVisible) {
+            return (
+                <div className={theme.bulkBar} role="region" aria-label={text.selection}>
+                    <span className={theme.bulkCount} aria-live="polite">{selectedIds.length} {text.selected}</span>
+
+                    {bulkActions.map((action) => (
+                        <button
+                            key={action.id ?? action.name}
+                            type="button"
+                            className={joinClasses(action.danger ? theme.buttonDanger : theme.buttonSecondary, 'fe-button-sm')}
+                            onClick={() => runBulk(action)}>
+                            {action.icon ? <IconComponent name={action.icon} size={14} /> : null}
+                            <span>{action.name}</span>
+                        </button>
+                    ))}
+
+                    <span className={theme.toolbarSpacer} />
+
+                    <button type="button" className={theme.buttonLink} onClick={() => clearSelection()}>
+                        {text.clearSelection}
+                    </button>
+                </div>
+            )
+        }
+
+        if (! showTopbar) {
+            return null
+        }
+
+        return (
+            <div className={theme.toolbar}>
+                {hasActions ? (
+                    <MenuComponent
+                        items={crudItems}
+                        label={text.actions}
+                        placement="bottom-start"
+                        beforeOpen={prepareCrud}
+                        renderTrigger={({ toggle, loading: busy, triggerProps }) => (
+                            <button
+                                type="button"
+                                className={theme.buttonSecondary}
+                                {...triggerProps}
+                                disabled={busy}
+                                onClick={toggle}>
+                                <IconComponent name="actions" size={14} />
+                                <span>{text.actions}</span>
+                            </button>
+                        )} />
+                ) : null}
+
+                <span className={theme.toolbarSpacer} />
+
+                <button type="button" className={theme.iconButton} aria-label={text.refresh} onClick={() => refresh()}>
+                    <IconComponent name="refresh" size={16} />
+                </button>
+
+                {hasFilter ? (
+                    <button
+                        type="button"
+                        className={theme.iconButton}
+                        aria-label={text.filters}
+                        aria-expanded={filtersOpen ? 'true' : 'false'}
+                        aria-controls={filtersId}
+                        onClick={() => setFiltersOpen((open) => ! open)}>
+                        <IconComponent name="filter" size={16} />
+                    </button>
+                ) : null}
+            </div>
+        )
+    }
 
     return (
-        <div>
-            {showTopbar ? (
-                <div>
-                    <div className="fe-container fe-container-wide pt-4">
-                        <div fe-grid="">
-                            {hasActions ? (
-                                <div className="fe-w-expand">
-                                    <button
-                                        type="button"
-                                        className="text-white bg-blue-700 hover:bg-blue-800 focus:ring-4 focus:ring-blue-300 font-medium rounded-lg text-sm px-5 py-2.5 mr-2 mb-2 dark:bg-blue-600 dark:hover:bg-blue-700 focus:outline-none dark:focus:ring-blue-800"
-                                        onClick={() => actionButtonClicked(crudActions)}>
-                                        Acciones
-                                    </button>
-
-                                    <NavDropdownComponent id="actionCrudDropdown" pos="right">
-                                        <ActionListComponent
-                                            actions={crudActions}
-                                            extraParams={extraParams}
-                                            extraQuery={extraQuery}
-                                            onActionClicked={actionClicked} />
-                                    </NavDropdownComponent>
-                                </div>
-                            ) : (
-                                <div><div className="fe-w-expand"></div></div>
-                            )}
-
-                            {hasFilter ? (
-                                <div className="fe-w-auto">
-                                    <div className="fe-grid-divider fe-children-expand fe-text-center" fe-grid="">
-                                        <div>
-                                            <button
-                                                type="button"
-                                                aria-label="Update results"
-                                                className="fe-text-right pointer"
-                                                onClick={updateFilters}>
-                                                <svg className="w-6 h-6 text-slate-800 dark:text-white" aria-hidden="true" xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 18 20">
-                                                    <path stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" strokeWidth="2" d="M16 1v5h-5M2 19v-5h5m10-4a8 8 0 0 1-14.947 3.97M1 10a8 8 0 0 1 14.947-3.97" />
-                                                </svg>
-                                            </button>
-                                        </div>
-
-                                        <div>
-                                            <button
-                                                type="button"
-                                                aria-label="Buscar"
-                                                aria-expanded={filtersOpen}
-                                                className="fe-text-right pointer"
-                                                onClick={() => setFiltersOpen((open) => ! open)}>
-                                                <svg className="w-6 h-6 text-slate-800 dark:text-white" aria-hidden="true" xmlns="http://www.w3.org/2000/svg" fill="currentColor" viewBox="0 0 20 18">
-                                                    <path d="M18.85 1.1A1.99 1.99 0 0 0 17.063 0H2.937a2 2 0 0 0-1.566 3.242L6.99 9.868 7 14a1 1 0 0 0 .4.8l4 3A1 1 0 0 0 13 17l.01-7.134 5.66-6.676a1.99 1.99 0 0 0 .18-2.09Z" />
-                                                </svg>
-                                            </button>
-                                        </div>
-                                    </div>
-                                </div>
-                            ) : null}
-                        </div>
-                    </div>
-
-                    {hasFilter ? (
-                        // El uk-toggle de la version Vue trabaja sobre el DOM
-                        // por su cuenta; en React el estado gobierna la vista.
-                        <div className="filter-form fe-card fe-card-body fe-pt-0" hidden={! filtersOpen}>
-                            {filterForm}
-                        </div>
-                    ) : null}
+        <section className={joinClasses(theme.datatable, cardWrapper && theme.surface)}>
+            {renderBar()}
+
+            {showTopbar && hasFilter ? (
+                <div id={filtersId} className={joinClasses('filter-form', theme.datatableFilters)} hidden={! filtersOpen}>
+                    {filterForm}
                 </div>
             ) : null}
 
-            <div className={`fe-container fe-container-wide${showTopbar ? ' ptb-20' : ''}`}>
-                <div className={`fe-p-sm${cardWrapper ? ' bg-white p-6 rounded-lg shadow dark:border-slate-700 dark:bg-slate-800' : ''}`}>
-                    <DataTableComponent
-                        actions={hasActions}
-                        dataTable={dataTable}
-                        extraParams={extraParams}
-                        extraQuery={extraQuery}
-                        showTableHeader={showTableHeader}
-                        dataTableComponents={dataTableComponents}
-                        onSortColumn={sortColumn}
-                        onActionButtonClicked={actionButtonClicked}
-                        onActionClicked={actionClicked} />
-
-                    <SelectPaginationComponent meta={pagination.meta} onPageChange={updatePage} />
-                </div>
-            </div>
-        </div>
+            <DataTableComponent
+                table={table}
+                head={visibleHead}
+                rows={rows}
+                clones={clones}
+                loading={loading}
+                error={error}
+                actions={hasActions}
+                selectable={selectable}
+                showTableHeader={showTableHeader}
+                dataTableComponents={dataTableComponents}
+                labels={text}
+                orderBy={orderBy}
+                sort={sort}
+                itemsFor={rowItems}
+                prepareRow={preparePolicies}
+                onSortColumn={sortColumn}
+                onRetry={refresh} />
+
+            {/* Con un error y sin filas, un «No hay resultados» en el pie
+                contradiría el motivo que ya da la tabla. */}
+            {error && rows.length === 0 ? null : (
+                <SelectPaginationComponent meta={meta} labels={text} onPageChange={updatePage} />
+            )}
+        </section>
     )
 }