innoboxrr-vue-datatable 2.2.0 → 3.0.0

package/src/table.js

@@ -0,0 +1,251 @@
+/**
+ * Lo que la tabla decide sin depender de Vue ni de React: cómo se traduce el
+ * contrato del modelo a columnas de TanStack Table, qué se pide al servidor,
+ * qué se le dice al usuario cuando algo falla y en qué se convierte cada
+ * acción.
+ *
+ * El archivo es idéntico en innoboxrr-vue-datatable y en
+ * innoboxrr-react-datatable. Es lo que hace que las dos tablas se comporten
+ * igual: si cambia aquí, cambia allí.
+ */
+
+/** Las acciones que borran se pintan en rojo aunque el modelo no lo diga. */
+const DANGER_ACTIONS = ['delete', 'forceDelete']
+
+/** La clave con la que se guardan los permisos de la barra superior. */
+export const CRUD_POLICIES = '__crud__'
+
+export const DEFAULT_LABELS = {
+    actions: 'Acciones',
+    rowActions: 'Acciones del registro',
+    refresh: 'Actualizar',
+    filters: 'Filtros',
+    selectAll: 'Seleccionar todos los de esta página',
+    selectRow: 'Seleccionar el registro',
+    selection: 'Selección',
+    selected: 'seleccionados',
+    clearSelection: 'Quitar selección',
+    empty: 'No hay resultados',
+    retry: 'Reintentar',
+    of: 'de',
+    page: 'Página',
+    previous: 'Página anterior',
+    next: 'Página siguiente',
+    forbidden: 'No tienes permiso para ver estos registros.',
+    offline: 'No se pudo conectar con el servidor.',
+    failed: 'No se pudieron cargar los registros.',
+    policiesFailed: 'No se pudieron comprobar los permisos.',
+    notAllowed: 'No tienes permiso para esta acción.',
+    actionFailed: 'No se pudo completar la acción.',
+}
+
+/**
+ * Se leía de la global `csrf_token`, que la aplicación anfitriona tenía que
+ * definir en window: el componente no se podía montar fuera de ella.
+ */
+export const csrfToken = () => globalThis.csrf_token
+    ?? globalThis.document?.querySelector('meta[name="csrf-token"]')?.getAttribute('content')
+    ?? ''
+
+/**
+ * Sustituye a `_.isEqual` de lodash, que se usaba como global sin declararla
+ * como dependencia.
+ */
+export const isEqual = (a, b) => {
+    if (a === b) {
+        return true
+    }
+
+    if (typeof a !== 'object' || typeof b !== 'object' || a === null || b === null) {
+        return false
+    }
+
+    const keysA = Object.keys(a)
+    const keysB = Object.keys(b)
+
+    return keysA.length === keysB.length && keysA.every((key) => isEqual(a[key], b[key]))
+}
+
+/**
+ * Una foto de un objeto de filtros. Comparar contra el valor anterior no sirve
+ * cuando el anfitrión muta el mismo objeto: el anterior y el nuevo son el mismo.
+ */
+export const snapshot = (value) => JSON.stringify(value ?? {})
+
+/**
+ * Se admite tanto ['name'] como [{ id: 'name' }]: el contrato nunca estuvo
+ * documentado y por ahí circulan las dos formas.
+ */
+export const hiddenColumnIds = (hideColumns = []) => hideColumns
+    .map((column) => (typeof column === 'string' ? column : column?.id))
+    .filter(Boolean)
+
+/**
+ * `dataTableHead()` del modelo, en columnas de TanStack Table. La columna
+ * original viaja en `meta.head`, que es de donde la tabla saca el parser, el
+ * componente y si el valor es HTML.
+ */
+export const columnsFrom = (head = []) => head.map((column) => ({
+    id: column.id,
+    accessorFn: (row) => row?.[column.id],
+    header: column.value,
+    enableSorting: column.sortable === true,
+    meta: { head: column },
+}))
+
+/** Solo un `false` explícito oculta una columna en TanStack Table. */
+export const visibilityFrom = (hideColumns) => Object.fromEntries(
+    hiddenColumnIds(hideColumns).map((id) => [id, false])
+)
+
+/** El orden lo decide el servidor; la tabla solo lo refleja. */
+export const sortingFrom = (orderBy, sort = {}) => (
+    orderBy ? [{ id: orderBy, desc: sort[orderBy] === 'desc' }] : []
+)
+
+/**
+ * La primera pulsación sobre una columna que el modelo no ordena por defecto
+ * la deja ascendente; las siguientes alternan.
+ */
+export const toggledSort = (sort, id) => ({ ...sort, [id]: sort[id] === 'asc' ? 'desc' : 'asc' })
+
+export const ariaSort = (column, orderBy, sort = {}) => {
+    if (column.sortable !== true) {
+        return undefined
+    }
+
+    if (column.id !== orderBy) {
+        return 'none'
+    }
+
+    return sort[column.id] === 'desc' ? 'descending' : 'ascending'
+}
+
+export const sortIcon = (column, orderBy, sort = {}) => {
+    const state = ariaSort(column, orderBy, sort)
+
+    return state === 'ascending' ? 'sortUp' : state === 'descending' ? 'sortDown' : 'sort'
+}
+
+/**
+ * Lo que espera el backend. Con orden interno, el del usuario gana a lo que
+ * traigan los filtros externos; sin él, es al revés.
+ */
+export const requestFilters = ({ formFilters = {}, externalFilters = {}, orderBy, sort = {}, page, internalSort }) => {
+    const params = { _token: csrfToken(), managed: true, except_view_any: true }
+    const order = { orderBy, orderMode: sort[orderBy] }
+
+    return internalSort
+        ? { ...params, ...formFilters, ...externalFilters, ...order, page }
+        : { ...params, ...formFilters, ...order, ...externalFilters, page }
+}
+
+export const requestConfig = (method, url, payload) => ({
+    method,
+    url,
+    data: method === 'post' ? payload : null,
+    params: method === 'get' ? payload : null,
+})
+
+/** El usuario canceló una confirmación: no es un error que haya que contar. */
+export const isCancelled = (error) => ['RequestCancelledError', 'CanceledError'].includes(error?.name)
+
+/**
+ * Qué decirle al usuario. Antes un fallo se reintentaba tres veces en silencio
+ * y un 403 dejaba la tabla vacía con «No results found», como si no hubiera
+ * registros.
+ */
+export const describeError = (error, labels = DEFAULT_LABELS, fallback = labels.failed) => {
+    const status = error?.response?.status ?? null
+
+    if (status === 403) {
+        return { status, message: labels.forbidden, retryable: false }
+    }
+
+    // Un fallo de red no trae respuesta; un error de programa, tampoco, y no
+    // es cosa de la conexión.
+    if (! error?.response) {
+        const offline = Boolean(error?.request) || error?.code === 'ERR_NETWORK' || error?.message === 'Network Error'
+
+        return { status, message: offline ? labels.offline : fallback, retryable: true }
+    }
+
+    const message = error.response.data?.message
+
+    return {
+        status,
+        message: typeof message === 'string' && message !== '' ? message : fallback,
+        retryable: true,
+    }
+}
+
+/**
+ * Marca `policy` en cada acción según lo que respondió el backend. Una acción
+ * que el modelo declara ya permitida se queda así.
+ */
+export const withPolicies = (actions = [], allowed = null) => actions.map((action) => ({
+    ...action,
+    policy: action.policy === true || allowed?.[action.id] === true,
+}))
+
+export const actionKind = (action) => {
+    if (! action.route) {
+        return 'callback'
+    }
+
+    return action.link ? 'link' : 'route'
+}
+
+export const routeTarget = (action, extraParams = {}, extraQuery = {}) => {
+    const to = action.params?.to ?? {}
+
+    return {
+        name: to.name,
+        params: { ...(to.params ?? {}), ...extraParams },
+        query: to.query ? { ...to.query, ...extraQuery } : { ...extraQuery },
+    }
+}
+
+/**
+ * Las acciones del contrato, como elementos de MenuComponent. Una acción sin
+ * permiso se ve deshabilitada y dice por qué: quien no puede tiene que saber
+ * que existe.
+ */
+export const menuItems = (actions = [], labels, run) => actions.map((action, index) => {
+    const allowed = action.policy === true
+
+    return {
+        id: action.id ?? `${action.name}-${index}`,
+        label: action.name,
+        icon: action.icon || undefined,
+        danger: action.danger ?? DANGER_ACTIONS.includes(action.id),
+        disabled: ! allowed,
+        disabledReason: allowed ? undefined : labels.notAllowed,
+        action: () => run(action),
+    }
+})
+
+/**
+ * Copia aislada de una fila, para que un parser del modelo no pueda mutar los
+ * datos de la tabla. Se hace una vez por fila y carga, no una por celda.
+ */
+export const cloneRow = (row) => JSON.parse(JSON.stringify(row ?? {}))
+
+export const cellValue = (column, row) => (
+    typeof column.parser === 'function' ? column.parser(row?.[column.id], row) : row?.[column.id]
+)
+
+/** Un componente de celda recibe el objeto que devuelve el parser, o `{ value }`. */
+export const componentProps = (value) => (
+    typeof value === 'object' && value !== null && ! Array.isArray(value) ? value : { value }
+)
+
+export const summary = (meta = {}, labels = DEFAULT_LABELS) => (
+    meta.total > 0 ? `${meta.from}–${meta.to} ${labels.of} ${meta.total}` : labels.empty
+)
+
+/**
+ * La casilla de un rango con Mayúsculas. El evento de cambio de una casilla
+ * no siempre trae la tecla; el clic, sí.
+ */
+export const isRangeEvent = (event) => Boolean(event?.shiftKey ?? event?.nativeEvent?.shiftKey)

package/src/useDataTable.js

@@ -0,0 +1,370 @@
+import { computed, onMounted, ref, shallowRef, unref, watch } from 'vue'
+import axios from 'axios'
+import {
+    columnVisibilityFeature,
+    rowSelectionFeature,
+    rowSortingFeature,
+    tableFeatures,
+    useTable,
+} from '@tanstack/vue-table'
+import { notifyError, notifySuccess } from 'innoboxrr-form-core'
+
+import * as core from './table.js'
+
+/**
+ * Solo lo que la tabla usa. El orden y la paginación los hace el servidor, así
+ * que no hay modelos de filas ordenadas ni paginadas: TanStack Table lleva el
+ * estado —qué columnas se ven, qué filas están seleccionadas, por qué columna
+ * se ordena— y la tabla pinta.
+ */
+const features = tableFeatures({ rowSortingFeature, columnVisibilityFeature, rowSelectionFeature })
+
+/**
+ * Toda la lógica de la tabla: cargar, ordenar, paginar, seleccionar y resolver
+ * permisos. Es la misma que `useDataTable` de innoboxrr-react-datatable.
+ *
+ * Está fuera del componente para poder probarla y para pintar la misma tabla
+ * de otra forma.
+ *
+ * @param {object} props  los props de DataTable (reactivos)
+ * @param {{ navigate?: (target: object) => unknown, labels?: object }} options
+ */
+export default function useDataTable(props, { navigate = null, labels = core.DEFAULT_LABELS } = {}) {
+    const text = () => unref(labels)
+
+    const head = computed(() => props.model.dataTableHead())
+    const columns = computed(() => core.columnsFrom(head.value))
+
+    const visibleHead = computed(() => {
+        const hidden = core.hiddenColumnIds(props.hideColumns)
+
+        return head.value.filter((column) => ! hidden.includes(column.id))
+    })
+
+    // Las filas llegan del servidor y se sustituyen enteras: una referencia
+    // superficial evita que Vue envuelva cada una en un proxy.
+    const rows = shallowRef([])
+    const meta = shallowRef({})
+    const links = shallowRef([])
+    const loading = ref(false)
+    const error = shallowRef(null)
+
+    const sort = ref({ ...props.model.dataTableSort() })
+    const orderBy = ref('id')
+    const page = ref(1)
+
+    /** Lo que respondió el backend de permisos, por fila y para la barra. */
+    const allowed = shallowRef({})
+
+    // A partir del primer clic en una cabecera, el orden del usuario manda
+    // sobre el que traigan los filtros externos.
+    let internalSort = false
+    let requestId = 0
+
+    const table = useTable({
+        features,
+        columns,
+        data: rows,
+        getRowId: (row, index) => String(row?.id ?? index),
+        manualSorting: true,
+        enableRowSelection: computed(() => props.selectable === true),
+        isRowRangeSelectionEvent: core.isRangeEvent,
+        state: computed(() => ({
+            columnVisibility: core.visibilityFrom(props.hideColumns),
+            sorting: core.sortingFrom(orderBy.value, sort.value),
+        })),
+    })
+
+    const selection = computed(() => table.atoms.rowSelection.get() ?? {})
+    const selectedIds = computed(() => Object.keys(selection.value).filter((id) => selection.value[id]))
+
+    /**
+     * Una copia por fila y carga, para que un parser del modelo no pueda mutar
+     * los datos de la tabla.
+     */
+    const clones = computed(() => rows.value.map(core.cloneRow))
+
+    const crudActions = computed(() => core.withPolicies(
+        props.model.crudActions(),
+        allowed.value[core.CRUD_POLICIES]
+    ))
+
+    const bulkActions = computed(() => (
+        typeof props.model.bulkActions === 'function' ? props.model.bulkActions() : []
+    ))
+
+    const rowActions = (row) => core.withPolicies(row?.actions ?? [], allowed.value[String(row?.id)])
+
+    const load = async () => {
+        const id = ++requestId
+
+        const filters = core.requestFilters({
+            formFilters: props.formFilters,
+            externalFilters: props.externalFilters,
+            orderBy: orderBy.value,
+            sort: sort.value,
+            page: page.value,
+            internalSort,
+        })
+
+        props.model.setFilters?.(filters)
+        loading.value = true
+
+        try {
+            const response = await axios(core.requestConfig(props.dataMethod, props.dataUrl, filters))
+
+            // Una respuesta que llega tarde no pisa a la de una petición
+            // posterior: quien cambia de página dos veces seguidas ve la última.
+            if (id !== requestId) {
+                return
+            }
+
+            rows.value = response.data?.data ?? []
+            meta.value = response.data?.meta ?? {}
+            links.value = response.data?.links ?? []
+            error.value = null
+
+            // Con datos nuevos los permisos se vuelven a preguntar.
+            allowed.value = {}
+        } catch (failure) {
+            if (id !== requestId) {
+                return
+            }
+
+            const described = core.describeError(failure, text())
+
+            if (described.status === 403) {
+                rows.value = []
+                meta.value = {}
+            } else if (rows.value.length > 0) {
+                // Con filas en pantalla el error no tiene sitio en la tabla:
+                // se avisa y se deja lo que había.
+                notifyError(described.message)
+            }
+
+            error.value = described
+        } finally {
+            if (id === requestId) {
+                loading.value = false
+            }
+        }
+    }
+
+    /**
+     * Varios cambios en el mismo tick —un filtro nuevo que además vuelve a la
+     * primera página— son una sola petición. Antes eran dos: el paginador
+     * tenía su propia copia de la página y la devolvía al padre.
+     */
+    let scheduled = false
+
+    const schedule = () => {
+        if (scheduled) {
+            return
+        }
+
+        scheduled = true
+
+        queueMicrotask(() => {
+            scheduled = false
+            load()
+        })
+    }
+
+    const refresh = () => load()
+
+    const clearSelection = () => table.resetRowSelection(true)
+
+    const sortColumn = (column) => {
+        if (column?.sortable !== true) {
+            return
+        }
+
+        internalSort = true
+        sort.value = core.toggledSort(sort.value, column.id)
+        orderBy.value = column.id
+    }
+
+    const updatePage = (next) => {
+        const value = Number(next)
+
+        if (Number.isInteger(value) && value >= 1) {
+            page.value = value
+        }
+    }
+
+    /**
+     * Pregunta al backend qué se puede hacer con una fila —o con la barra, sin
+     * id— antes de abrir su menú. Lo que responde se guarda hasta la próxima
+     * carga, así que abrir dos veces el mismo menú no pregunta dos veces.
+     */
+    const preparePolicies = async (id = null) => {
+        const key = id == null ? core.CRUD_POLICIES : String(id)
+
+        if (allowed.value[key]) {
+            return
+        }
+
+        try {
+            const response = await axios(core.requestConfig(props.policyMethod, props.policyUrl, {
+                _token: core.csrfToken(),
+                id,
+            }))
+
+            allowed.value = { ...allowed.value, [key]: response.data ?? {} }
+        } catch {
+            // El menú se abre igual, con todo deshabilitado: es mejor que un
+            // botón que no hace nada.
+            notifyError(text().policiesFailed)
+        }
+    }
+
+    const run = async (action) => {
+        const kind = core.actionKind(action)
+
+        if (kind === 'route') {
+            if (! navigate) {
+                notifyError(text().actionFailed)
+
+                return undefined
+            }
+
+            try {
+                await navigate(core.routeTarget(action, props.extraParams, props.extraQuery))
+            } catch (failure) {
+                // Una ruta que no existe es un error de quien declaró la
+                // acción: el usuario recibe un aviso y la consola, el detalle.
+                notifyError(text().actionFailed)
+                console.error(failure)
+            }
+
+            return undefined
+        }
+
+        if (kind === 'link') {
+            globalThis.window?.open(action.params?.link, action.params?.target ?? '_self')
+
+            return undefined
+        }
+
+        if (typeof props.model[action.callback] !== 'function') {
+            notifyError(text().actionFailed)
+
+            return undefined
+        }
+
+        try {
+            await props.model[action.callback](action.params)
+        } catch (failure) {
+            if (! core.isCancelled(failure)) {
+                notifyError(core.describeError(failure, text(), text().actionFailed).message)
+            }
+
+            return undefined
+        }
+
+        if (action.success) {
+            notifySuccess(action.success)
+        }
+
+        return load()
+    }
+
+    /**
+     * Una acción masiva recibe los ids seleccionados —también los de otras
+     * páginas— y las filas cargadas que están entre ellos.
+     */
+    const runBulk = async (action) => {
+        if (typeof props.model[action.callback] !== 'function') {
+            notifyError(text().actionFailed)
+
+            return undefined
+        }
+
+        const ids = [...selectedIds.value]
+        const loaded = table.getSelectedRowModel().rows.map((row) => row.original)
+
+        try {
+            await props.model[action.callback](ids, loaded)
+        } catch (failure) {
+            if (! core.isCancelled(failure)) {
+                notifyError(core.describeError(failure, text(), text().actionFailed).message)
+            }
+
+            return undefined
+        }
+
+        clearSelection()
+
+        if (action.success) {
+            notifySuccess(action.success)
+        }
+
+        return load()
+    }
+
+    let lastForm = core.snapshot(props.formFilters)
+    let lastExternal = core.snapshot(props.externalFilters)
+
+    // Un filtro nuevo vuelve a la primera página; uno externo no. Los dos
+    // descartan la selección, que era de otro listado.
+    watch(() => props.formFilters, (value) => {
+        const next = core.snapshot(value)
+
+        if (next === lastForm) {
+            return
+        }
+
+        lastForm = next
+        page.value = 1
+        clearSelection()
+        schedule()
+    }, { deep: true })
+
+    watch(() => props.externalFilters, (value) => {
+        const next = core.snapshot(value)
+
+        if (next === lastExternal) {
+            return
+        }
+
+        lastExternal = next
+        clearSelection()
+        schedule()
+    }, { deep: true })
+
+    watch([orderBy, sort, page], schedule)
+
+    onMounted(load)
+
+    // Lo que exponía la versión anterior, para quien lo lea desde fuera.
+    const dataTable = computed(() => ({ head: visibleHead.value, body: rows.value }))
+    const pagination = computed(() => ({ meta: meta.value, links: links.value }))
+
+    return {
+        table,
+        head,
+        visibleHead,
+        rows,
+        clones,
+        meta,
+        links,
+        loading,
+        error,
+        sort,
+        orderBy,
+        page,
+        crudActions,
+        bulkActions,
+        rowActions,
+        selectedIds,
+        dataTable,
+        pagination,
+        refresh,
+        clearSelection,
+        sortColumn,
+        updatePage,
+        preparePolicies,
+        run,
+        runBulk,
+    }
+}

package/src/useTheme.js

@@ -0,0 +1,20 @@
+import { onScopeDispose, shallowRef } from 'vue'
+import { getTheme, onThemeChange } from 'innoboxrr-form-core'
+
+/**
+ * El tema de innoboxrr-form-core, como referencia reactiva.
+ *
+ * El tema es estado de módulo, fuera de Vue: sin la suscripción, un `setTheme`
+ * con la tabla ya montada no la repintaría.
+ *
+ * @returns {import('vue').ShallowRef<Record<string, string>>}
+ */
+export default function useTheme() {
+    const theme = shallowRef(getTheme())
+
+    onScopeDispose(onThemeChange((next) => {
+        theme.value = { ...next }
+    }))
+
+    return theme
+}

package/src/components/DisabledLinkComponent.vue

@@ -1,45 +0,0 @@
-<template>
-
-	<a
-		href="#"
-		class="disabled-link block px-4 py-2 dark:hover:text-white dark:text-slate-400"
-		data-tooltip="This action is not authorized"
-		data-tooltip-pos="right">
-
-		<Icon
-			v-if="showIcon"
-			class="fe-mr-sm"
-			:icon="resolved"
-			aria-hidden="true" />
-
-		<span>{{ text }}</span>
-
-	</a>
-
-</template>
-
-<script setup>
-
-	import { computed } from 'vue'
-	import { Icon } from '@iconify/vue'
-	import { iconFor } from 'innoboxrr-form-core'
-
-	const props = defineProps({
-
-		icon: {
-			type: String,
-			default: ''
-		},
-
-		text: {
-			type: String,
-			required: true
-		}
-
-	})
-
-	const showIcon = computed(() => props.icon !== '' && props.icon != null)
-
-	const resolved = computed(() => iconFor(props.icon))
-
-</script>