innoboxrr-form-core 2.3.0 → 2.5.0

package/README.md

@@ -1,49 +1,75 @@
 # innoboxrr-form-core
 
-Lo que comparten [`innoboxrr-form-elements`](../form-elements) (Vue) y
-[`innoboxrr-react-form-elements`](../react-form-elements) (React) y no depende
-de ningún framework.
+Lo que comparten [`innoboxrr-form-elements`](../form-elements) (Vue),
+[`innoboxrr-react-form-elements`](../react-form-elements) (React) y los dos
+datatables, y no depende de ningún framework: el tema, los iconos, las hojas de
+estilo, los archivos y las zonas horarias.
 
-Estaba duplicado en los dos paquetes, que es exactamente como dos copias
-empiezan a divergir.
+Estaba duplicado en los paquetes, que es exactamente como dos copias empiezan a
+divergir.
 
 ```
 npm i innoboxrr-form-core
 ```
 
-## Tema
+## Estilos
+
+```js
+import 'innoboxrr-form-core/styles'
+```
+
+Una sola importación trae las tres hojas: `tokens.css` (las variables),
+`layout.css` (las utilidades de maquetación) y `components.css` (los
+componentes). Nada de lo generado necesita UIkit, Tailwind ni Font Awesome.
+
+Colores, formas, densidad, capas y movimiento son variables CSS. Para cambiar el
+aspecto de todo, se redefinen:
+
+```css
+:root {
+    --fe-primary: #7c3aed;
+    --fe-radius: 10px;
+    --fe-density: 0.875;
+}
+```
 
-Antes cada componente llevaba su cadena CSS incrustada como valor por defecto
-de `customClass` —repetida en los dos paquetes— y el código que genera
-`larapack-generator` esperaba `inputClass` y `buttonClass` de un mixin global
-que la aplicación anfitriona tenía que registrar sin que nada lo dijera.
+El modo oscuro responde a la preferencia del sistema y a un `data-theme="dark"`
+en la raíz; `data-theme="light"` fuerza el claro aunque el sistema esté en
+oscuro.
 
-Ahora es un mapa de tokens que la aplicación ajusta **una vez**, al arrancar:
+## Tema
+
+Un mapa de tokens que la aplicación ajusta **una vez**, al arrancar. Cada token
+apunta a una clase del sistema propio (`fe-*`), así que el caso normal es no
+tocarlo; sirve para apuntar un token a las clases de otro sistema visual cuando
+la aplicación ya tiene el suyo:
 
 ```js
 import { setTheme } from 'innoboxrr-form-core'
 
 setTheme({
     input: 'form-control',
-    select: 'form-select',
     button: 'btn btn-primary',
 })
 ```
 
-Los tokens:
-
 | Grupo | Tokens |
 |---|---|
 | Envoltorios | `field`, `fieldInner`, `label`, `help`, `helpIcon`, `error` |
 | Controles | `input`, `select`, `textarea`, `checkbox`, `radio`, `file` |
-| Botones | `button`, `buttonSecondary`, `buttonDanger`, `buttonLink` |
-
-Los valores de fábrica son los de UIkit + Tailwind que ya usaba el ecosistema,
-así que actualizar no cambia nada de aspecto.
-
-`customClass` sigue existiendo y **reemplaza** al token, para el caso puntual.
-Antes unos controles lo reemplazaban y otros lo sumaban a una clase incrustada;
-ahora se comportan todos igual.
+| Botones | `button`, `buttonSecondary`, `buttonDanger`, `buttonLink`, `iconButton` |
+| Navegación | `breadcrumb`, `breadcrumbLink`, `breadcrumbCurrent`, `breadcrumbSeparator`, `actionMenu`, `actionMenuItem`, `actionMenuDanger`, `kbd` |
+| Superficies | `surface`, `surfaceRaised`, `toolbar`, `badge`, `badgePrimary`, `badgeSuccess`, `badgeDanger`, `badgeWarning` |
+| Esqueletos | `skeleton`, `skeletonText`, `skeletonCircle`, `skeletonBlock` |
+| Diálogos y drawers | `overlay`, `dialog`, `dialogSmall`, `dialogLarge`, `dialogHeader`, `dialogTitle`, `dialogBody`, `dialogFooter`, `drawer`, `drawerStart`, `drawerHeader`, `drawerTitle`, `drawerBody`, `drawerFooter` |
+| Menús | `menu`, `menuList`, `menuItem`, `menuItemDanger`, `menuSeparator`, `menuLabel` |
+| Paleta de comandos | `command`, `commandInput`, `commandList`, `commandGroup`, `commandItem`, `commandEmpty` |
+| Avisos | `toast`, `toastSuccess`, `toastDanger`, `toastWarning`, `toastTitle`, `toastClose`, `toastRegion` |
+| Tabla | `table`, `tableNumeric`, `tableSticky`, `tableSelect`, `tableResizer`, `tableEmpty`, `bulkBar`, `bulkCount` |
+| Edición en línea | `editable` |
+| Shell de aplicación | `shell`, `shellHeader`, `shellSidebar`, `shellMain` |
+
+`customClass` **reemplaza** al token, para el caso puntual:
 
 ```js
 import { getTheme, resetTheme, onThemeChange, classFor } from 'innoboxrr-form-core'
@@ -55,9 +81,89 @@ resetTheme()          // vuelve a fábrica (sobre todo para pruebas)
 onThemeChange(fn)     // devuelve la función para dejar de escuchar
 ```
 
-Los dos paquetes de componentes se suscriben, así que **un `setTheme` en
-caliente repinta lo que ya esté montado**: leerlo directamente no lo haría,
-porque el tema es estado de módulo, fuera del framework.
+Los paquetes de componentes se suscriben, así que **un `setTheme` en caliente
+repinta lo que ya esté montado**.
+
+## Piezas de escritorio
+
+Diálogos, drawers, menús y avisos se apoyan en lo que ya hace el navegador, sin
+librerías de interfaz: `<dialog>` con `showModal()` pone la capa superior, el
+fondo inerte, el foco atrapado, Escape para cerrar y la devolución del foco; el
+atributo `popover` pone el cierre al pulsar fuera. Estas hojas solo los dibujan.
+Los componentes de Vue y React envuelven exactamente este marcado.
+
+```html
+<dialog class="fe-drawer">
+    <header class="fe-drawer-header">
+        <h2 class="fe-drawer-title">Nuevo producto</h2>
+        <button class="fe-icon-button" aria-label="Cerrar">…</button>
+    </header>
+    <div class="fe-drawer-body">…</div>
+    <footer class="fe-drawer-footer">…</footer>
+</dialog>
+```
+
+- **Diálogo**: `fe-dialog`, con `fe-dialog-sm` o `fe-dialog-lg` para el ancho.
+- **Drawer**: `fe-drawer` a la derecha; `fe-drawer-start` lo pega a la izquierda.
+- **Paleta de comandos**: `<dialog class="fe-dialog fe-command">` con
+  `fe-command-input` y una `fe-command-list` de `fe-command-item`; el elemento
+  activo lleva `aria-selected="true"`.
+- **Avisos**: una `fe-toast-region` con `popover="manual"`, para seguir encima
+  de un drawer abierto con `showModal()`.
+- **Menús**: `fe-menu` con `popover`, colocado con Floating UI.
+- **Tabla**: `fe-table-select` para la columna de casillas, `data-selected` en
+  la fila, `fe-bulk-bar` para lo que se hace con la selección y
+  `fe-table-resizer` para cambiar el ancho de una columna.
+
+Un `<dialog>` cerrado está oculto porque el navegador le pone `display: none`;
+por eso ninguna regla fija `display` fuera del estado `[open]`. Las capas que no
+viven en la capa superior —la cabecera fija de una tabla, un overlay dibujado a
+mano, los tooltips— siguen la escala `--fe-z-*`, nunca un número suelto.
+
+## Iconos
+
+Un nombre semántico y un mapa que decide de dónde sale el dibujo. Los valores son
+nombres de Iconify (`coleccion:icono`):
+
+```js
+import { setIcons, iconFor } from 'innoboxrr-form-core'
+
+setIcons({ plus: 'lucide:plus', delete: 'lucide:trash-2' })
+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
 
@@ -76,10 +182,6 @@ hay que meter en el `FormData`.
 
 `validateFiles` es la misma función devolviendo una promesa, por compatibilidad.
 
-La vista previa de lo que no es imagen es un `data:` URI. Antes era una URL de
-`icon-library.com`: cada archivo disparaba una petición a un tercero que puede
-caerse o cambiar.
-
 ## Zonas horarias
 
 ```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,13 +1,14 @@
 {
   "name": "innoboxrr-form-core",
-  "version": "2.3.0",
-  "description": "El nucleo agnostico de los formularios innoboxrr: tema, archivos y zonas horarias.",
+  "version": "2.5.0",
+  "description": "El nucleo agnostico de la interfaz innoboxrr: tema, iconos, estilos, archivos y zonas horarias.",
   "type": "module",
   "main": "index.js",
   "exports": {
     ".": "./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",