innoboxrr-form-core 2.4.0 → 2.5.1

package/README.md

@@ -133,6 +133,38 @@ iconFor('plus')      // 'lucide:plus'
 iconFor('mdi:home')  // un nombre completo pasa tal cual
 ```
 
+## Avisos y confirmaciones
+
+Estado de toda la aplicación, fuera del framework: quien avisa —un store, el
+contrato de un modelo, la tabla— no necesita saber si detrás hay Vue o React.
+Los paquetes de componentes lo pintan con su región de avisos y su anfitrión de
+confirmaciones, que la aplicación monta una vez.
+
+```js
+import { notify, notifySuccess, notifyError, confirmAction } from 'innoboxrr-form-core'
+
+notifySuccess('Producto creado')
+notifyError('No se pudo guardar', { title: 'Producto' })
+notify({ message: 'Exportación en curso', variant: 'info', duration: 8000 })
+
+if (await confirmAction({ message: '¿Borrar el producto?', variant: 'danger' })) {
+    // …
+}
+```
+
+- Un aviso se va a los cinco segundos; **uno de peligro se queda** hasta que se
+  cierra, porque quien no lo leyó a tiempo no sabría qué falló. `duration: 0` lo
+  deja fijo.
+- No se apilan más de cinco: sale el más antiguo.
+- `confirmAction` resuelve `true` o `false`. Una pregunta nueva con otra
+  pendiente da la anterior por cancelada.
+- Sin un anfitrión montado, `confirmAction` usa `window.confirm`: una promesa que
+  no se resolviera dejaría colgada la acción que la espera.
+
+Para pintarlos desde otro sitio: `getToasts`, `onToastsChange`, `dismiss`,
+`getConfirmation`, `onConfirmationChange` y `resolveConfirmation`. `resetToasts`
+y `resetConfirmation` vacían el estado entre pruebas.
+
 ## Archivos
 
 ```js

package/index.js

@@ -1,11 +1,12 @@
 /**
  * innoboxrr-form-core
  *
- * Lo que comparten innoboxrr-form-elements y innoboxrr-react-form-elements y
- * no depende de ningun framework: el tema, la validacion de archivos y la
- * lista de zonas horarias.
+ * Lo que comparten los paquetes de interfaz innoboxrr —los componentes de Vue
+ * y de React y los dos datatables— y no depende de ningun framework: el tema,
+ * los iconos, los avisos y confirmaciones, la validacion de archivos y la lista
+ * de zonas horarias.
  *
- * Estaba duplicado en los dos paquetes, que es exactamente como dos copias
+ * Estaba duplicado en los paquetes, que es exactamente como dos copias
  * empiezan a divergir.
  */
 
@@ -27,6 +28,21 @@ export {
     setIcons,
 } from './src/icons.js'
 
+export {
+    confirmAction,
+    dismiss,
+    getConfirmation,
+    getToasts,
+    notify,
+    notifyError,
+    notifySuccess,
+    onConfirmationChange,
+    onToastsChange,
+    resetConfirmation,
+    resetToasts,
+    resolveConfirmation,
+} from './src/feedback.js'
+
 export {
     FILE_ICON,
     describeFiles,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "innoboxrr-form-core",
-  "version": "2.4.0",
+  "version": "2.5.1",
   "description": "El nucleo agnostico de la interfaz innoboxrr: tema, iconos, estilos, archivos y zonas horarias.",
   "type": "module",
   "main": "index.js",
@@ -8,6 +8,7 @@
     ".": "./index.js",
     "./theme": "./src/theme.js",
     "./icons": "./src/icons.js",
+    "./feedback": "./src/feedback.js",
     "./files": "./src/files.js",
     "./timezone": "./src/timezone.js",
     "./styles": "./styles.css",

package/src/components.css

@@ -172,6 +172,10 @@
 .fe-select,
 .fe-textarea,
 .fe-file {
+    /* Con width: 100% y padding, sin border-box el control mide más que su
+       contenedor. Una aplicación que ya pone border-box a todo no lo nota; una
+       que no, ve una barra de desplazamiento en cada drawer. */
+    box-sizing: border-box;
     width: 100%;
     min-height: var(--fe-control-height);
     padding: 0 var(--fe-control-padding-x);
@@ -271,6 +275,7 @@
 .fe-button-secondary,
 .fe-button-danger,
 .fe-button-link {
+    box-sizing: border-box;
     display: inline-flex;
     align-items: center;
     justify-content: center;
@@ -332,6 +337,7 @@
 /* Un botón que solo lleva un icono: cerrar un diálogo, abrir el menú de una
    fila. Cuadrado, para que el objetivo no dependa del ancho del glifo. */
 .fe-icon-button {
+    box-sizing: border-box;
     display: inline-flex;
     align-items: center;
     justify-content: center;
@@ -625,6 +631,7 @@
 }
 
 .fe-dialog {
+    box-sizing: border-box;
     width: min(var(--fe-dialog-width), calc(100vw - 2 * var(--fe-space-4)));
     max-height: 85vh;
     padding: 0;
@@ -694,6 +701,7 @@
 /* Un drawer es un <dialog> pegado a un borde. El formulario de crear o
    editar se abre aquí y la tabla sigue a la vista, detrás. */
 .fe-drawer {
+    box-sizing: border-box;
     width: min(var(--fe-drawer-width), 100vw);
     max-width: 100vw;
     height: 100dvh;
@@ -803,6 +811,7 @@
 }
 
 .fe-menu-item {
+    box-sizing: border-box;
     display: flex;
     align-items: center;
     gap: var(--fe-space-2);
@@ -892,6 +901,7 @@
 }
 
 .fe-command-input {
+    box-sizing: border-box;
     width: 100%;
     min-height: calc(var(--fe-control-height) * 1.4);
     padding: 0 var(--fe-space-5);
@@ -928,6 +938,7 @@
 }
 
 .fe-command-item {
+    box-sizing: border-box;
     display: flex;
     align-items: center;
     gap: var(--fe-space-3);
@@ -1168,6 +1179,14 @@
     min-height: 1.5em;
     padding: 0 var(--fe-space-1);
     margin: 0 calc(-1 * var(--fe-space-1));
+    /* Es un <button> para que se alcance con teclado, pero tiene que leerse
+       como el texto que muestra: sin el fondo, el borde ni la fuente que el
+       navegador le pone a un botón. */
+    font: inherit;
+    color: inherit;
+    text-align: left;
+    background: none;
+    border: none;
     border-radius: var(--fe-radius-sm);
     border-bottom: 1px dashed transparent;
     cursor: text;

package/src/feedback.js

@@ -0,0 +1,273 @@
+/**
+ * Avisos y confirmaciones de toda la aplicación, como estado de módulo.
+ *
+ * Hasta ahora no había forma de avisar: un formulario generado se tragaba
+ * cualquier error que no fuera de validación, la tabla solo lo escribía en la
+ * consola y la confirmación de borrar era un SweetAlert de otro paquete. Cada
+ * pieza que quisiera decir algo tendría que haber montado su propio aviso.
+ *
+ * Vive aquí, fuera de Vue y de React, por la misma razón que el tema: los dos
+ * paquetes de componentes pintan la misma cola, y quien avisa —un store, un
+ * contrato de modelo, la tabla— no tiene por qué saber qué framework hay
+ * detrás.
+ *
+ *     import { notify, confirmAction } from 'innoboxrr-form-core'
+ *
+ *     notify({ message: 'Producto creado', variant: 'success' })
+ *
+ *     if (await confirmAction({ message: '¿Borrar el producto?', variant: 'danger' })) {
+ *         // …
+ *     }
+ */
+
+/**
+ * @typedef {'info'|'success'|'warning'|'danger'} Variant
+ * @typedef {{ id: number, title: string|null, message: string, variant: Variant, duration: number }} Toast
+ * @typedef {{ id: number, title: string, message: string, confirmLabel: string, cancelLabel: string, variant: 'primary'|'danger' }} Confirmation
+ */
+
+const VARIANTS = ['info', 'success', 'warning', 'danger']
+
+const DURATION = 5000
+
+/**
+ * Más avisos a la vez no se leen: tapan la pantalla. El que sobra es el más
+ * antiguo.
+ */
+const MAX_TOASTS = 5
+
+// AVISOS
+
+/** @type {Toast[]} */
+let toasts = []
+
+let nextToast = 1
+
+/** @type {Map<number, ReturnType<typeof setTimeout>>} */
+const timers = new Map()
+
+/** @type {Set<(toasts: Toast[]) => void>} */
+const toastListeners = new Set()
+
+const emitToasts = () => toastListeners.forEach((listener) => listener(toasts))
+
+/**
+ * Muestra un aviso y devuelve su id.
+ *
+ * Un aviso de peligro no se cierra solo por defecto: quien no lo leyó a tiempo
+ * no sabría qué falló. El resto se va a los cinco segundos. `duration: 0` lo
+ * deja hasta que se cierre a mano.
+ *
+ * @param {string|{ message: string, title?: string, variant?: Variant, duration?: number }} options
+ * @returns {number}
+ */
+export function notify(options) {
+    const input = typeof options === 'string' ? { message: options } : (options ?? {})
+    const variant = VARIANTS.includes(input.variant) ? input.variant : 'info'
+    const duration = input.duration ?? (variant === 'danger' ? 0 : DURATION)
+
+    /** @type {Toast} */
+    const toast = {
+        id: nextToast++,
+        title: input.title ?? null,
+        message: String(input.message ?? ''),
+        variant,
+        duration,
+    }
+
+    // Se reemplaza el array en vez de mutarlo: React compara la instantánea
+    // por referencia y, con el mismo array, no repintaría.
+    toasts = [...toasts, toast]
+
+    while (toasts.length > MAX_TOASTS) {
+        forget(toasts[0].id)
+        toasts = toasts.slice(1)
+    }
+
+    if (duration > 0) {
+        timers.set(toast.id, setTimeout(() => dismiss(toast.id), duration))
+    }
+
+    emitToasts()
+
+    return toast.id
+}
+
+/**
+ * @param {string} message
+ * @param {{ title?: string, duration?: number }} [options]
+ */
+export function notifySuccess(message, options = {}) {
+    return notify({ ...options, message, variant: 'success' })
+}
+
+/**
+ * @param {string} message
+ * @param {{ title?: string, duration?: number }} [options]
+ */
+export function notifyError(message, options = {}) {
+    return notify({ ...options, message, variant: 'danger' })
+}
+
+/**
+ * @param {number} id
+ */
+export function dismiss(id) {
+    forget(id)
+
+    const remaining = toasts.filter((toast) => toast.id !== id)
+
+    if (remaining.length !== toasts.length) {
+        toasts = remaining
+        emitToasts()
+    }
+}
+
+/** @returns {Toast[]} */
+export function getToasts() {
+    return toasts
+}
+
+/**
+ * @param {(toasts: Toast[]) => void} listener
+ * @returns {() => void}  para dejar de escuchar
+ */
+export function onToastsChange(listener) {
+    toastListeners.add(listener)
+
+    return () => toastListeners.delete(listener)
+}
+
+/**
+ * Vacía la cola. Sobre todo para las pruebas: sin esto un aviso de una prueba
+ * aparecería en la siguiente.
+ */
+export function resetToasts() {
+    timers.forEach((timer) => clearTimeout(timer))
+    timers.clear()
+
+    toasts = []
+    nextToast = 1
+
+    emitToasts()
+}
+
+/**
+ * @param {number} id
+ */
+function forget(id) {
+    clearTimeout(timers.get(id))
+    timers.delete(id)
+}
+
+// CONFIRMACIONES
+
+/** @type {Confirmation|null} */
+let confirmation = null
+
+/** @type {((value: boolean) => void)|null} */
+let resolver = null
+
+let nextConfirmation = 1
+
+/** @type {Set<(confirmation: Confirmation|null) => void>} */
+const confirmationListeners = new Set()
+
+const emitConfirmation = () => confirmationListeners.forEach((listener) => listener(confirmation))
+
+/**
+ * Pregunta y espera la respuesta: `true` si se confirma, `false` si no.
+ *
+ * La pinta el ConfirmHostComponent que la aplicación monta una vez. Si no hay
+ * ninguno escuchando se usa `window.confirm`, que es feo pero contesta: una
+ * promesa que no se resolviera nunca dejaría colgada la acción que la espera.
+ *
+ * Una pregunta nueva con otra pendiente da la anterior por cancelada. Dos
+ * confirmaciones a la vez no tienen una respuesta clara.
+ *
+ * @param {string|{ message: string, title?: string, confirmLabel?: string, cancelLabel?: string, variant?: 'primary'|'danger' }} options
+ * @returns {Promise<boolean>}
+ */
+export function confirmAction(options) {
+    const input = typeof options === 'string' ? { message: options } : (options ?? {})
+    const message = String(input.message ?? '')
+
+    if (confirmationListeners.size === 0) {
+        const native = typeof window !== 'undefined' ? window.confirm : undefined
+
+        return Promise.resolve(typeof native === 'function' ? Boolean(native.call(window, message)) : false)
+    }
+
+    if (resolver) {
+        settle(false)
+    }
+
+    return new Promise((resolve) => {
+        resolver = resolve
+
+        confirmation = {
+            id: nextConfirmation++,
+            title: input.title ?? '¿Confirmas?',
+            message,
+            confirmLabel: input.confirmLabel ?? 'Confirmar',
+            cancelLabel: input.cancelLabel ?? 'Cancelar',
+            variant: input.variant === 'danger' ? 'danger' : 'primary',
+        }
+
+        emitConfirmation()
+    })
+}
+
+/**
+ * La respuesta a la confirmación pendiente. La llama el componente que la pinta.
+ *
+ * @param {boolean} value
+ */
+export function resolveConfirmation(value) {
+    if (resolver) {
+        settle(Boolean(value))
+    }
+}
+
+/** @returns {Confirmation|null} */
+export function getConfirmation() {
+    return confirmation
+}
+
+/**
+ * @param {(confirmation: Confirmation|null) => void} listener
+ * @returns {() => void}  para dejar de escuchar
+ */
+export function onConfirmationChange(listener) {
+    confirmationListeners.add(listener)
+
+    return () => confirmationListeners.delete(listener)
+}
+
+/**
+ * Cancela lo pendiente. Sobre todo para las pruebas.
+ */
+export function resetConfirmation() {
+    if (resolver) {
+        settle(false)
+
+        return
+    }
+
+    confirmation = null
+    emitConfirmation()
+}
+
+/**
+ * @param {boolean} value
+ */
+function settle(value) {
+    const resolve = resolver
+
+    resolver = null
+    confirmation = null
+
+    emitConfirmation()
+
+    resolve?.(value)
+}