innoboxrr-vue-datatable 2.3.0 → 3.0.0

package/README.md

@@ -1,198 +1,160 @@
+# innoboxrr-vue-datatable
 
-# InnoboxRR Vue DataTable
+Un listado de administración para Vue 3 sobre el contrato de modelo de
+LaraPack: barra de acciones, filtros, orden y paginación en el servidor,
+selección de filas con acciones masivas, permisos resueltos antes de abrir cada
+menú, esqueletos mientras carga y errores que se ven.
 
-**InnoboxRR Vue DataTable** es un paquete avanzado para manejar tablas de datos en aplicaciones Vue 3, con soporte para filtros, ordenación, paginación, personalización de columnas y componentes dinámicos. Este README incluye instrucciones detalladas para configurar tanto el entorno Vue como los archivos de configuración necesarios.
+Por debajo, [TanStack Table](https://tanstack.com/table) lleva el estado de la
+tabla —columnas visibles, orden, selección— y los componentes de
+`innoboxrr-form-elements` ponen el menú, los iconos y los esqueletos, con el
+tema de `innoboxrr-form-core`.
 
----
-
-## Índice
-
-1. [Instalación](#instalación)
-2. [Configuración en Vue](#configuración-en-vue)
-3. [Archivo de Configuración](#archivo-de-configuración)
-4. [Uso de DataTable](#uso-de-datatable)
-5. [Personalización](#personalización)
-6. [CRUD y Políticas](#crud-y-políticas)
-7. [Ejemplo Completo](#ejemplo-completo)
-
----
+Su gemelo es [`innoboxrr-react-datatable`](../react-datatable): los mismos
+props, el mismo modelo, el mismo comportamiento.
 
 ## Instalación
 
-### Paso 1: Instalar el paquete
-
-```bash
-npm install innoboxrr-vue-datatable innoboxrr-http-request
 ```
-
----
-
-## Configuración en Vue
-
-1. **Registrar el paquete:**
-
-```javascript
-// main.js
-import { createApp } from 'vue';
-import App from './App.vue';
-import DataTable from 'innoboxrr-vue-datatable';
-
-const app = createApp(App);
-app.component('DataTable', DataTable);
-app.mount('#app');
+npm i innoboxrr-vue-datatable innoboxrr-form-core innoboxrr-form-elements vue-router
 ```
 
-2. **Registrar los componentes globales necesarios:**
-
-```javascript
-// main.js
-import ClipboardInput from './components/ClipboardInput.vue';
-
-app.component('ClipboardInput', ClipboardInput);
-```
-
----
-
-## Archivo de Configuración
-
-Crea un archivo de configuración, por ejemplo, `dataTableConfig.js`, para centralizar la lógica asociada a tus tablas y modelos.
-
-```javascript
-import makeHttpRequest from 'innoboxrr-http-request';
-import ClipboardInput from '@components/ClipboardInput.vue';
-
-export const API_ROUTE_PREFIX = 'api.example.';
-export const CSRF_TOKEN = document.querySelector('meta[name="csrf-token"]').getAttribute('content');
-
-export let filters = {};
-
-export const strings = {
-  crudActions: {
-    create: { name: 'Create', icon: 'fa-plus' },
-    export: { name: 'Export', icon: 'fa-download' },
-  },
-};
-
-export const setFilters = (newFilters = {}) => {
-  filters = { ...filters, ...newFilters };
-  return filters;
-};
-
-export const getFilters = () => filters;
-
-export const crudActions = () => [
-  {
-    id: 'create',
-    name: strings.crudActions.create.name,
-    callback: 'createModel',
-    icon: strings.crudActions.create.icon,
-    route: true,
-    params: { to: { name: 'CreateExample', params: {} } },
-  },
-];
-
-export const dataTableComponents = () => ({
-  ClipboardInput,
-});
-
-export const dataTableHead = () => [
-  { id: 'id', value: 'ID', sortable: true },
-  { id: 'name', value: 'Name', sortable: true },
-  { id: 'description', value: 'Description', sortable: false },
-  { id: 'link', value: 'Link', component: 'ClipboardInput', parser: (value) => ({ value }) },
-];
-
-export const dataTableSort = () => ({
-  id: 'asc',
-  name: 'asc',
-});
-
-export const indexModel = (filters = {}) =>
-  makeHttpRequest('get', route(API_ROUTE_PREFIX + 'index'), { _token: CSRF_TOKEN, ...filters });
-
-export const createModel = (data) =>
-  makeHttpRequest('post', route(API_ROUTE_PREFIX + 'create'), { _token: CSRF_TOKEN, ...data });
+```js
+import 'innoboxrr-form-core/styles'
 ```
 
----
-
-## Uso de DataTable
+## Uso
 
 ```vue
 <template>
-  <data-table
-    title="Example Table"
-    :data-url="dataUrl"
-    data-method="get"
-    :model="model"
-    :external-filters="externalFilters"
-    :form-filters="formFilters"
-    :extra-params="extraParams"
-    :hide-columns="hideColumns"
-    :has-actions="true"
-    :has-filter="true"
-  >
-    <template v-slot:filterForm>
-      <filter-form @submit="updateFormFilters" />
-    </template>
-  </data-table>
+    <DataTable
+        ref="table"
+        :data-url="route('api.acme.shop.product.index')"
+        data-method="get"
+        :policy-url="route('api.acme.shop.product.policies')"
+        policy-method="get"
+        :model="model"
+        :form-filters="filters"
+        selectable>
+        <template #filterForm>
+            <FilterForm @submit="filters = $event" />
+        </template>
+    </DataTable>
+
+    <!-- Una vez en la aplicación, para los avisos y las confirmaciones. -->
+    <ToastRegionComponent />
+    <ConfirmHostComponent />
 </template>
 
-<script>
-import DataTable from 'innoboxrr-vue-datatable';
-import FilterForm from './FilterForm.vue';
-import * as model from './dataTableConfig';
-
-export default {
-  components: { DataTable, FilterForm },
-  data() {
-    return {
-      dataUrl: '/api/example',
-      model,
-      externalFilters: {},
-      formFilters: {},
-      extraParams: {},
-      hideColumns: [],
-    };
-  },
-  methods: {
-    updateFormFilters(filters) {
-      this.formFilters = filters;
-    },
-  },
-};
+<script setup>
+    import { ref } from 'vue'
+    import DataTable from 'innoboxrr-vue-datatable'
+    import * as model from './models/product'
+
+    const table = ref(null)
+    const filters = ref({})
+
+    // Tras crear o editar en un drawer: table.value.refresh()
 </script>
 ```
 
----
+## Props
 
-## Personalización
+| Prop | Por defecto | |
+|---|---|---|
+| `dataUrl`, `policyUrl` | — | Obligatorias. |
+| `dataMethod`, `policyMethod` | `'post'` | `get` manda `params`; `post`, `data`. |
+| `model` | — | El contrato del modelo (abajo). |
+| `formFilters` | `{}` | Un cambio vuelve a la primera página. |
+| `externalFilters` | `{}` | Un cambio recarga sin cambiar de página. |
+| `extraParams`, `extraQuery` | `{}` | Se suman a las rutas de las acciones. |
+| `hideColumns` | `[]` | Ids, como `'name'` o `{ id: 'name' }`. |
+| `selectable` | `false` | Casillas y barra de acciones masivas. |
+| `showTopbar`, `hasActions`, `hasFilter`, `showTableHeader`, `cardWrapper` | `true` | |
+| `labels` | `{}` | Textos; se mezclan con `DEFAULT_LABELS`. |
 
-1. **Cabezeras de tabla (dataTableHead):**
-   Define las columnas de la tabla en el archivo de configuración.
-   
-2. **Filtros externos e internos:**
-   Usa `formFilters` para los filtros internos y `externalFilters` para filtros definidos fuera del componente.
+Por `ref`: `refresh()`, `clearSelection()`, `selectedIds` y la instancia de
+TanStack Table en `table`.
 
-3. **Componentes personalizados:**
-   Registra componentes como `ClipboardInput` para columnas dinámicas.
+## El contrato del modelo
 
----
+Es **el mismo archivo** para Vue y para React: funciones puras y llamadas HTTP.
 
-## CRUD y Políticas
+```js
+export const crudActions = () => [
+    { id: 'create', name: 'Crear', icon: 'plus', route: true, policy: false,
+      params: { to: { name: 'AdminCreateProduct', params: {} } } },
+    { id: 'export', name: 'Exportar', icon: 'download', route: false, policy: false,
+      callback: 'exportModel', params: {}, success: 'Exportación en cola' },
+]
 
-1. **Definir acciones CRUD (crudActions):**
-   Asigna iconos, nombres y rutas a las acciones.
+export const dataTableHead = () => [
+    { id: 'id', value: 'ID', sortable: true, numeric: true },
+    { id: 'price', value: 'Precio', sortable: true, numeric: true, parser: (value, row) => `$${value}` },
+    { id: 'status', value: 'Estado', html: true, parser: (value) => `<b>${value}</b>` },
+    { id: 'link', value: 'Enlace', component: 'CopyLink', callback: (payload, row) => {} },
+]
+
+export const dataTableSort = () => ({ id: 'asc' })
+export const setFilters = (filters) => filters
+
+// Opcionales
+export const dataTableComponents = () => ({ CopyLink })
+export const bulkActions = () => [
+    { id: 'delete', name: 'Borrar', icon: 'delete', callback: 'bulkDelete', danger: true },
+]
+export const bulkDelete = (ids, rows) => { /* … */ }
+```
 
-2. **Petición de datos:**
-   Usa funciones como `indexModel` y `createModel` para interactuar con el backend.
+- **Acciones.** `route: true` navega a `params.to` con vue-router;
+  `route: true, link: true` abre `params.link`; `route: false` llama a
+  `model[callback](params)` y recarga. Cada fila trae las suyas en `actions`.
+- **Permisos.** Antes de abrir un menú se pregunta a `policyUrl` con el `id` de
+  la fila (o `null` para la barra) y se espera la respuesta: un
+  `{ edit: true }` habilita esa acción. Lo que no está permitido se ve
+  deshabilitado y dice por qué. La respuesta se guarda hasta la próxima carga.
+- **Parsers.** Reciben una copia de la fila: mutarla no cambia los datos.
+- **Acciones masivas.** Reciben los ids seleccionados —también los de otras
+  páginas— y las filas cargadas que están entre ellos.
+- **Confirmaciones.** Si un callback rechaza con un `RequestCancelledError`
+  (lo que lanza `innoboxrr-http-request` cuando se cancela la confirmación), la
+  tabla no avisa ni recarga.
+
+## Qué se ve
+
+- **Cargando.** La primera carga pinta la forma de las filas; las siguientes
+  atenúan las que hay (`aria-busy`).
+- **Errores.** Sin filas, el motivo va en la tabla: «No tienes permiso» para un
+  403, y «Reintentar» para lo demás. Con filas en pantalla, un aviso. No hay
+  reintentos silenciosos.
+- **Orden.** Un botón en cada cabecera ordenable, con `aria-sort`.
+- **Una petición por cambio.** Un filtro nuevo en la página 3 es una sola
+  petición a la página 1, y una respuesta que llega tarde no pisa a la última.
+
+## `useDataTable`
+
+La lógica, sin la vista:
+
+```js
+import { useDataTable } from 'innoboxrr-vue-datatable'
+
+const { table, rows, meta, loading, error, sortColumn, updatePage, refresh } = useDataTable(props, { navigate, labels })
+```
 
-3. **Políticas:**
-   Integra validaciones de acceso por políticas usando rutas predefinidas.
+## De 2.x a 3.0
 
----
+- Ya no existen `NavDropdownComponent`, `IconRouteComponent`,
+  `IconLinkComponent`, `DisabledLinkComponent` ni `PaginationComponent`: el menú
+  es `MenuComponent` de `innoboxrr-form-elements`.
+- Las acciones de ruta se ejecutan desde el menú con `router.push`, no con un
+  `<router-link>`.
+- Los textos están en español y se cambian con `labels`.
+- Un fallo ya no se reintenta tres veces: se ve, y se reintenta a mano.
+- `innoboxrr-form-elements` pasa a ser dependencia par, y `innoboxrr-form-core`
+  sube a `^2.6`, que trae las clases del listado.
 
-## Ejemplo Completo
+## Pruebas
 
-Revisa la sección de ejemplos en los apartados anteriores. 
-Para más información, consulta la [documentación oficial del paquete](https://github.com/innoboxrr/vue-datatable).
+```
+npm test
+```

package/index.js

@@ -1,3 +1,14 @@
-import DataTable from './src/DataTable.vue';
+/**
+ * El export por defecto es la tabla, igual que en innoboxrr-react-datatable.
+ * Se exponen además la lógica, por si alguien quiere pintarla de otra forma,
+ * y las piezas con las que está hecha.
+ */
 
-export default DataTable;
+import DataTable from './src/DataTable.vue'
+
+export default DataTable
+
+export { default as useDataTable } from './src/useDataTable.js'
+export { default as DataTableComponent } from './src/components/DataTableComponent.vue'
+export { default as SelectPaginationComponent } from './src/components/SelectPaginationComponent.vue'
+export { DEFAULT_LABELS } from './src/table.js'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "innoboxrr-vue-datatable",
-  "version": "2.3.0",
+  "version": "3.0.0",
   "description": "Datatable para vue3",
   "main": "index.js",
   "scripts": {
@@ -40,18 +40,20 @@
     "*.vue"
   ],
   "peerDependencies": {
-    "innoboxrr-form-core": "^2.3.0",
+    "innoboxrr-form-core": "^2.6.0",
+    "innoboxrr-form-elements": "^6.4.0",
     "vue": "^3.5.0",
     "vue-router": "^4.5.0"
   },
   "dependencies": {
-    "@floating-ui/dom": "^1.8.0",
-    "@iconify/vue": "^5.0.0",
+    "@tanstack/vue-table": "^9.2.4",
     "axios": "^1.7.0"
   },
   "devDependencies": {
     "@vitejs/plugin-vue": "^6.0.0",
     "@vue/test-utils": "^2.4.6",
+    "innoboxrr-form-core": "^2.6.0",
+    "innoboxrr-form-elements": "^6.4.0",
     "jsdom": "^25.0.0",
     "vite": "^7.1.0",
     "vitest": "^3.0.0",