innoboxrr-form-core 2.0.0 → 2.2.0

package/index.js

@@ -18,6 +18,15 @@ export {
     setTheme,
 } from './src/theme.js'
 
+export {
+    defaultIcons,
+    getIcon,
+    iconFor,
+    onIconChange,
+    resetIcons,
+    setIcons,
+} from './src/icons.js'
+
 export {
     FILE_ICON,
     describeFiles,

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "innoboxrr-form-core",
-  "version": "2.0.0",
+  "version": "2.2.0",
   "description": "El nucleo agnostico de los formularios innoboxrr: tema, archivos y zonas horarias.",
   "type": "module",
   "main": "index.js",
   "exports": {
     ".": "./index.js",
     "./theme": "./src/theme.js",
+    "./icons": "./src/icons.js",
     "./files": "./src/files.js",
     "./timezone": "./src/timezone.js",
     "./styles": "./styles.css",

package/src/components.css

@@ -72,6 +72,98 @@
     color: var(--fe-danger);
 }
 
+/* ============================================================
+   TOOLTIP
+   ============================================================ */
+
+/*
+ * Sin una linea de JavaScript.
+ *
+ * Los diez tooltips del ecosistema son texto plano —la ayuda de un campo,
+ * «This action is not authorized», «Buscar»—, asi que no hacen falta ni
+ * posicionamiento dinamico ni contenido rico. Antes los pintaba `uk-tooltip`,
+ * que es un componente de UIkit: para una cadena de ayuda arrastraba un
+ * framework entero.
+ *
+ *     <span data-tooltip="Texto de ayuda">…</span>
+ *     <span data-tooltip="Texto" data-tooltip-pos="right">…</span>
+ *
+ * Aparece con el raton y **tambien con el foco**, para que exista para quien
+ * navega con teclado. Un disparador que no sea enfocable de por si necesita
+ * `tabindex="0"`.
+ *
+ * Un lector de pantalla no anuncia el contenido de un `::after`: cuando el
+ * tooltip es la unica etiqueta —un icono suelto— hay que poner ademas un
+ * `aria-label` en el disparador. Es lo que hacen los componentes.
+ */
+
+[data-tooltip] {
+    position: relative;
+}
+
+[data-tooltip]::after {
+    content: attr(data-tooltip);
+    position: absolute;
+    z-index: 60;
+    bottom: calc(100% + var(--fe-space-2));
+    left: 50%;
+    transform: translateX(-50%);
+    width: max-content;
+    max-width: 16rem;
+    padding: var(--fe-space-1) var(--fe-space-2);
+    font-family: var(--fe-font);
+    font-size: var(--fe-text-xs);
+    font-weight: 400;
+    line-height: 1.4;
+    white-space: normal;
+    text-align: left;
+    color: var(--fe-text-inverse);
+    background: var(--fe-text);
+    border-radius: var(--fe-radius-sm);
+    box-shadow: var(--fe-shadow);
+    opacity: 0;
+    visibility: hidden;
+    transition: opacity var(--fe-transition), visibility var(--fe-transition);
+    pointer-events: none;
+}
+
+[data-tooltip]:hover::after,
+[data-tooltip]:focus-visible::after {
+    opacity: 1;
+    visibility: visible;
+}
+
+/* Un tooltip vacio no debe dibujar una caja negra de dos pixeles. */
+[data-tooltip='']::after {
+    content: none;
+}
+
+[data-tooltip-pos='right']::after {
+    bottom: auto;
+    top: 50%;
+    left: calc(100% + var(--fe-space-2));
+    transform: translateY(-50%);
+}
+
+[data-tooltip-pos='left']::after {
+    bottom: auto;
+    top: 50%;
+    left: auto;
+    right: calc(100% + var(--fe-space-2));
+    transform: translateY(-50%);
+}
+
+[data-tooltip-pos='bottom']::after {
+    bottom: auto;
+    top: calc(100% + var(--fe-space-2));
+}
+
+@media (prefers-reduced-motion: reduce) {
+    [data-tooltip]::after {
+        transition: none;
+    }
+}
+
 /* ============================================================
    CONTROLES
    ============================================================ */

package/src/icons.js

@@ -0,0 +1,151 @@
+/**
+ * Los iconos del ecosistema: un nombre semantico, y un mapa que decide de
+ * donde sale el dibujo.
+ *
+ * Antes hacian falta tres dependencias para pintar un icono: `uikit` ponia el
+ * componente, `@fortawesome/fontawesome-free` los glifos y
+ * `uikit-custom-icons` hacia de puente registrando los de Font Awesome dentro
+ * del registro de UIkit. Por eso `icon: 'fa-plus'` funcionaba —porque alguien
+ * escribio el puente—, y por eso dejaba de funcionar en cuanto faltaba
+ * cualquiera de las tres.
+ *
+ * Ahora el componente recibe un nombre semantico (`plus`, `download`) y este
+ * mapa dice a que icono corresponde. Los valores son nombres de Iconify
+ * (`coleccion:icono`), que son 200.000 iconos de mas de 150 colecciones bajo
+ * un solo esquema.
+ *
+ * Cambiar el aspecto de todo el proyecto es cambiar el mapa:
+ *
+ *     import { setIcons } from 'innoboxrr-form-core'
+ *
+ *     setIcons({ plus: 'lucide:plus', download: 'lucide:download' })
+ *
+ * Y un nombre de Iconify se puede pasar directo cuando haga falta uno suelto:
+ * `iconFor('mdi:home')` devuelve `mdi:home`. El mapa es para lo que se repite,
+ * no una aduana.
+ */
+
+/**
+ * @typedef {Record<string, string>} IconMap
+ */
+
+/** @type {IconMap} */
+export const defaultIcons = {
+    // ACCIONES
+    plus: 'fa6-solid:plus',
+    download: 'fa6-solid:download',
+    upload: 'fa6-solid:upload',
+    edit: 'fa6-solid:pen',
+    delete: 'fa6-solid:trash',
+    show: 'fa6-solid:eye',
+    hide: 'fa6-solid:eye-slash',
+    actions: 'fa6-solid:gears',
+    refresh: 'fa6-solid:rotate',
+    search: 'fa6-solid:magnifying-glass',
+    filter: 'fa6-solid:filter',
+
+    // ESTADO
+    help: 'fa6-solid:circle-question',
+    warning: 'fa6-solid:triangle-exclamation',
+    error: 'fa6-solid:circle-exclamation',
+    success: 'fa6-solid:circle-check',
+    info: 'fa6-solid:circle-info',
+    locked: 'fa6-solid:lock',
+
+    // NAVEGACION
+    previous: 'fa6-solid:chevron-left',
+    next: 'fa6-solid:chevron-right',
+    up: 'fa6-solid:chevron-up',
+    down: 'fa6-solid:chevron-down',
+    close: 'fa6-solid:xmark',
+
+    // OBJETOS
+    box: 'fa6-solid:box',
+    users: 'fa6-solid:users',
+    gift: 'fa6-solid:gift',
+    file: 'fa6-solid:file',
+}
+
+/** @type {IconMap} */
+let icons = { ...defaultIcons }
+
+/** @type {Set<(icons: IconMap) => void>} */
+const listeners = new Set()
+
+/**
+ * Ajusta el mapa. Se mezcla con el actual, asi que se puede cambiar un icono
+ * sin repetir los demas.
+ *
+ * @param {Partial<IconMap>} map
+ * @returns {IconMap}
+ */
+export function setIcons(map = {}) {
+    icons = { ...icons, ...map }
+
+    listeners.forEach((listener) => listener(icons))
+
+    return icons
+}
+
+/**
+ * Devuelve el mapa completo, o el icono de un nombre.
+ *
+ * @param {string} [name]
+ * @returns {IconMap|string}
+ */
+export function getIcon(name) {
+    return name === undefined ? icons : (icons[name] ?? '')
+}
+
+/**
+ * Resuelve un nombre a un icono de Iconify.
+ *
+ * Es lo que llaman los componentes. Acepta tres cosas:
+ *
+ *   - un nombre del mapa      → `plus`      → `fa6-solid:plus`
+ *   - un nombre de Iconify    → `mdi:home`  → `mdi:home`
+ *   - cualquier otra cosa     → se devuelve tal cual, para que el fallo se vea
+ *
+ * @param {string|null|undefined} name
+ * @returns {string}
+ */
+export function iconFor(name) {
+    if (! name) {
+        return ''
+    }
+
+    if (icons[name]) {
+        return icons[name]
+    }
+
+    // Ya viene con coleccion: es un nombre de Iconify y se pasa entero.
+    if (name.includes(':')) {
+        return name
+    }
+
+    return name
+}
+
+/**
+ * Vuelve a los valores de fabrica. Sobre todo para las pruebas: el mapa es
+ * estado de modulo y sin esto una prueba se filtraria a la siguiente.
+ *
+ * @returns {IconMap}
+ */
+export function resetIcons() {
+    icons = { ...defaultIcons }
+
+    listeners.forEach((listener) => listener(icons))
+
+    return icons
+}
+
+/**
+ * @param {(icons: IconMap) => void} listener
+ * @returns {() => void}  para dejar de escuchar
+ */
+export function onIconChange(listener) {
+    listeners.add(listener)
+
+    return () => listeners.delete(listener)
+}