@stackcraftmx/calcita 0.23.0 → 0.26.0

package/README.md

@@ -4,10 +4,16 @@
 transparente famoso por doblar la luz, y eso es lo que define al vidrio líquido: su lente.
 
 Arranca un proyecto sin copiar y volver a probar lo de siempre: el marco de la app con menú y permisos, tabla de servidor,
-diálogos de confirmación, avisos, descargas, formularios, formatos de número y fecha, errores RFC 9457, reportes en Excel
-y el tema con vidrio líquido, interpretado componente por componente según la guía de Apple.
+diálogos de confirmación, avisos, descargas, formularios, formatos de número y fecha, errores RFC 9457, reportes en Excel,
+la cuenta completa, mapa, calendario, tablero kanban, bandeja tipo correo y el tema con vidrio líquido, interpretado
+componente por componente según la guía de Apple.
 
-JavaScript con sus tipos generados: se usa igual desde un proyecto en TypeScript.
+JavaScript con sus tipos generados: se usa igual desde un proyecto en TypeScript. Sirve para un proyecto nuevo y también
+para meterlo por pedazos en un sistema que ya existe (ver «En un sistema que ya existe»).
+
+> **Versiones:** Calcita está hecha y probada con **MUI 7** (Material 7.3, MUI X 8), React 19 y react-router 7. MUI 9 ya
+> existe, pero cambia piezas que Calcita usa: todavía no está soportado. Con MUI 9 en el proyecto, quédese en MUI 7 por
+> ahora.
 
 ## Arrancar un proyecto con el CLI
 
@@ -47,9 +53,11 @@ El CLI nunca pisa un archivo que ya existe. Sus plantillas son los archivos tal
 
 ```bash
 pnpm add @stackcraftmx/calcita @mui/material @mui/icons-material @emotion/react @emotion/styled xstate @xstate/react sonner
+pnpm add formik yup     # solo si usa /forms o /account
 ```
 
-Con npm es igual, con `npm install` en lugar de `pnpm add`.
+Con npm es igual, con `npm install` en lugar de `pnpm add`. Desde la 0.25, formik y yup los pone el proyecto: Calcita usa
+la versión que ya tenga, no se casa con una.
 
 ```jsx
 import {ThemeProvider, createTheme} from '@mui/material/styles';
@@ -73,7 +81,8 @@ Sin nada más, todo sale en español, con la zona horaria del navegador, montos
 
 | Prop | Para qué | Por omisión |
 |---|---|---|
-| `language`, `onLanguageChange` | idioma activo (`es` o `en`) y a quién avisar cuando se cambia | `es` |
+| `language`, `onLanguageChange` | idioma activo y a quién avisar cuando se cambia | `es` |
+| `languages` | los idiomas que ofrece la app, con su nombre y su locale (`{code: 'pt', label: 'Português', locale: 'pt-BR'}`); sus traducciones van en `texts` | español e inglés |
 | `texts` | cambiar textos del paquete, por idioma: `{es: {common: {actions: {back: 'Volver'}}}}` | los del paquete |
 | `translate` | un traductor propio, por ejemplo i18next | ninguno |
 | `timeZone` | zona en que se pintan las horas | la del navegador |
@@ -82,6 +91,12 @@ Sin nada más, todo sale en español, con la zona horaria del navegador, montos
 | `navigation` | el router: `{useNavigate, useLocation, Link}` | la del navegador |
 | `canAccess` | quién ve qué (menú, rutas, botones): la regla del proyecto, normalmente `createAccessChecker(...)` | solo lo que no tiene regla |
 | `buildId` | la compilación del front que corre en la pestaña, para el aviso de versión nueva | ninguna (sin aviso) |
+| `fileTypes` | tipos de archivo propios para las descargas (su ícono y su color), además de Excel, CSV y PDF | los de la casa |
+
+Un `ToolkitProvider` dentro de otro (una parte de la app en otro idioma, una vista previa) toma del de afuera lo que no le
+digan, y lo de adentro usa el suyo: el más cercano. No le cambia nada al resto de la app. Dentro de un componente,
+`useFormatters()` da los formatos (`formatDate`, `formatCurrency`…) con el idioma, la zona y la moneda del proveedor más
+cercano; los sueltos usan los del proveedor de la raíz.
 
 Con react-router y i18next:
 
@@ -141,7 +156,7 @@ export default defineConfig({
 });
 
 // en la raíz de la app, una vez (en desarrollo no hay archivo: sin url no hace nada)
-usePublishedBuildWatch({url: import.meta.env.PROD ? '/version.json' : null});
+usePublishedBuildWatch({url: import.meta.env.PROD ? `${import.meta.env.BASE_URL}version.json` : null, buildId: import.meta.env.VITE_BUILD_ID});
 // opciones: checkEveryMinutes (5), reloadAfterHiddenMinutes (15; null = nunca recarga sola), onReload
 ```
 
@@ -153,12 +168,12 @@ Cada puerta pide solo sus librerías; un proyecto instala lo que usa.
 
 | Importar de | Trae | Pide además |
 |---|---|---|
-| `@stackcraftmx/calcita` | proveedor, diálogos, avisos, descargas, encabezados, filtros, chips, métricas, formatos, fechas, errores RFC 9457, la petición de la casa (`createApiClient`), la recuperación de versión vieja, la seguridad de la cuenta (códigos de recuperación, sesiones, bitácora) y la bandeja tipo correo (`InboxLayout`, `MessageList`, `MessageView`) | — |
+| `@stackcraftmx/calcita` | proveedor, marco de la app, diálogos, avisos, descargas, encabezados, filtros, chips, métricas, formatos (`useFormatters`), fechas, errores RFC 9457, la petición de la casa (`createApiClient`), la recuperación de versión vieja, la navegación sin router (`createBrowserNavigation`, `createHashNavigation`), la búsqueda de la barra (`BarSearch`), el menú «⋯» (`ActionsMenu`), las acciones de lo elegido (`SelectionActions`), la seguridad de la cuenta (códigos de recuperación, sesiones, bitácora) y la bandeja tipo correo (`InboxLayout`, `MessageList` con selección, `MessageView` con la conversación) | — |
 | `@stackcraftmx/calcita/table` | `ServerTable`: paginada, filtrada y ordenada en el servidor, con su estado en la URL | `@mui/x-data-grid`, `nuqs` |
-| `@stackcraftmx/calcita/forms` | campos de formik (texto, lista, número con miles, catálogo, color), formulario por pasos, aviso de arriba, errores del servidor pegados a cada campo; `Formik`, `Form` y `Yup` vienen con el paquete | — |
-| `@stackcraftmx/calcita/react-hook-form` | los mismos campos con los mismos nombres, conectados a react-hook-form, y `yupResolver` | `react-hook-form`, `@hookform/resolvers` |
+| `@stackcraftmx/calcita/forms` | campos de formik (texto, lista de una o varias opciones, número con miles, catálogo, color), formulario por pasos, aviso de arriba, errores del servidor pegados a cada campo | `formik`, `yup` |
+| `@stackcraftmx/calcita/react-hook-form` | los mismos campos con los mismos nombres, conectados a react-hook-form, su formulario por pasos y `yupResolver` | `react-hook-form`, `@hookform/resolvers` (y `yup` si valida con yup) |
 | `@stackcraftmx/calcita/date-pickers` | la fecha con el DatePicker de MUI X (`DateInput`, `FormDateField`); viaja `AAAA-MM-DD` | `@mui/x-date-pickers` 8, `dayjs` |
-| `@stackcraftmx/calcita/charts` | barras y columnas con vista de tabla | `recharts` |
+| `@stackcraftmx/calcita/charts` | barras, columnas y líneas (una serie o varias), cada una con su vista de tabla, y `ChartTooltip` para las propias | `recharts` |
 | `@stackcraftmx/calcita/timeline` | línea de tiempo por grupos | `@mui/lab` |
 | `@stackcraftmx/calcita/excel` | reporte en Excel (Resumen y Datos) y CSV | `exceljs`, que se le pasa al llamarlo |
 | `@stackcraftmx/calcita/react-router` | el adaptador de navegación | `react-router` |
@@ -168,11 +183,11 @@ Cada puerta pide solo sus librerías; un proyecto instala lo que usa.
 | `@stackcraftmx/calcita/next` | la navegación de Next.js (App Router) para ToolkitProvider; los componentes ya vienen marcados con `'use client'` y los puros sirven en el servidor | `next` |
 | `@stackcraftmx/calcita/money` | `Money`: dinero exacto en centavos enteros, con suma, resta, multiplicación, división, potencia, raíz y su formato con la moneda | — |
 | `@stackcraftmx/calcita/passkeys` | llaves de acceso (passkeys): crearlas y firmar con ellas, con los errores del navegador en palabras de la persona | `@simplewebauthn/browser` 14 |
-| `@stackcraftmx/calcita/account` | la cuenta completa: `SignInScreen` (con el segundo paso), `ForgotPasswordScreen`, `ResetPasswordScreen`, `ProfileScreen`, `AccountSecuritySection`, `AccountProvider` y `createRestAccountConnector` | `@simplewebauthn/browser` 14 |
+| `@stackcraftmx/calcita/account` | la cuenta completa: `SignInScreen` (con el segundo paso), `ForgotPasswordScreen`, `ResetPasswordScreen`, `ProfileScreen` (con campos y pestañas propias), `AccountSecuritySection`, `AccountProvider` y `createRestAccountConnector` | `@simplewebauthn/browser` 14, `formik`, `yup` |
 | `@stackcraftmx/calcita/account-demo` | `createDemoAccountConnector`: la cuenta en el navegador, sin backend (y los códigos TOTP) | — |
 | `@stackcraftmx/calcita/maps` | `MapView`: mapa con marcadores del color del tema, el elegido con su globo, se acomoda solo; en oscuro, mosaicos oscuros | `leaflet`, `react-leaflet` 5 |
-| `@stackcraftmx/calcita/calendar` | `EventCalendar`: mes, semana, día y lista, con la barra del framework; arrastrar cambia la cita y regresa si el servidor dice que no | `@fullcalendar/react`, `core`, `daygrid`, `timegrid`, `list`, `interaction` 6.1 |
-| `@stackcraftmx/calcita/kanban` | `KanbanBoard`: columnas con tope y tarjetas que se arrastran con el ratón, el dedo o el teclado; `moveCard` para ver la movida al instante | `@hello-pangea/dnd` 18 |
+| `@stackcraftmx/calcita/calendar` | `EventCalendar`: mes, semana, día y lista, con la barra del framework; arrastrar cambia la cita y regresa si el servidor dice que no. `EventDetails`: el detalle de una cita (lugar, liga de la reunión, invitados con su respuesta, recordatorio, notas) | `@fullcalendar/react`, `core`, `daygrid`, `timegrid`, `list`, `interaction` 6.1 |
+| `@stackcraftmx/calcita/kanban` | `KanbanBoard`: columnas con tope (y que se encogen, como un congelador) y tarjetas de producto (etiquetas, responsables, fecha, pendientes, terminar) que se arrastran con el ratón, el dedo o el teclado; `moveCard` para ver la movida al instante | `@hello-pangea/dnd` 18 |
 
 ## El tema
 
@@ -187,7 +202,7 @@ const theme = createToolkitTheme({colorSchemes: {light: {palette: {primary: {mai
 const theme = createToolkitTheme({components: {MuiCard: {…}}});        // se SUMA a los ajustes del framework
 ```
 
-El vidrio es la versión en CSS del Liquid Glass de Apple, poco transparente (80 %). Va en lo que flota sobre el
+El vidrio es la versión en CSS del Liquid Glass de Apple (60 % de opacidad por omisión). Va en lo que flota sobre el
 contenido y en los controles, como pide su guía:
 
 - la barra y el menú lateral, que en escritorio flotan a 8 px de la orilla;
@@ -198,8 +213,10 @@ contenido y en los controles, como pide su guía:
 - un lienzo con manchas tenues de color, para que el vidrio tenga algo que desenfocar.
 
 Las tarjetas del contenido se quedan sólidas, para que el texto largo se lea, salvo que el proyecto las pida de vidrio.
-Todo se pinta sólido si la persona pidió en su equipo «Reducir transparencia» o «Aumentar contraste». No trae refracción
-(la lupa que deforma lo de atrás): en la web solo sale con filtros que hoy funcionan nada más en Chrome.
+Todo se pinta sólido si la persona pidió en su equipo «Reducir transparencia» o «Aumentar contraste». La refracción (el
+lente que dobla lo de atrás en la orilla del vidrio) sale en Chrome y sus parientes (Edge, Brave, Arc) con
+`GlassLensFilter`, que `AppLayout` y `AuthLayout` ya ponen; Safari y Firefox no pintan ese filtro y ahí el vidrio se queda
+esmerilado.
 
 ```js
 const theme = createToolkitTheme({glass: {opacity: 0.7}});            // más transparente (0 a 1)
@@ -265,6 +282,9 @@ nombre; las demás, en «Más».
 Claro u oscuro tiene tres opciones en el menú de la cuenta: Claro, Oscuro y Automático, que sigue lo que diga el equipo y
 es lo de omisión. El botón de la barra fija claro u oscuro; Automático es la forma de volver a seguir al equipo.
 
+Una marca que es una palabra larga va en `wordmark` (a 24 px de alto, en lugar del logo cuadrado y el nombre). Una entrada
+del menú puede llevar a otro sistema (`href`) y traer su ícono ya pintado (`icon`) en lugar del componente (`Icon`).
+
 El menú no se escribe en una lista central: cada módulo trae su `menu.js` y `composeMenu` los junta, los ordena y deja
 solo los que la sesión puede ver (también dentro de los submenús).
 
@@ -296,10 +316,95 @@ const menuItems = composeMenu(import.meta.glob('@/modules/*/menu.js', {eager: tr
 En cada pantalla, `PageHeading` pone el título, la descripción y los botones, y arma las migas solo desde el menú
 (Inicio › Sección › Pantalla). `PageHeader` es el encabezado centrado de una portada y `DetailHeader` el de un registro.
 
-La misma regla protege las rutas (`withAccess(access, routes)` de `/react-router`: quien no puede ve «sin permiso») y
+La misma regla protege las rutas (`withAccess(access, routes)` de `/react-router`: quien no puede ve «sin permiso», o la
+página propia que se pase en `{fallback}`) y
 los botones (`<Can access={…}>`, `useCan`). El framework no sabe de roles: RBAC por permisos o roles y ABAC por políticas
 con nombre o reglas escritas ahí mismo, como cada proyecto las necesite. Lo que se pinta no protege nada: el backend
-vuelve a revisar cada petición. `ErrorPage` trae las pantallas de 404, 403 y 500.
+vuelve a revisar cada petición. `ErrorPage` trae las pantallas de 404, 403 y 500, y se extiende sin tocarla: botones
+propios junto a los de la casa (`extraActions`) o en su lugar (`actions`), algo debajo del texto (`children`), otro ícono y
+`onGoHome`.
+
+El marco avisa cuando la persona encoge el menú (`onMenuCollapse`), abre el menú del teléfono (`onMobileMenuChange`) o elige
+sus pestañas (`onMobileTabsChange`), para guardar esas preferencias en el servidor del proyecto si se quiere; sus textos se
+cambian con `texts`.
+
+## Eventos y textos de cada componente
+
+Cada componente de la casa avisa hacia afuera todo lo que pasa adentro (`onSelect`, `onChange`, `onViewChange`,
+`onMenuCollapse`, `onCardComplete`, `onDatesChange`…) y nunca llama un servidor propio: el proyecto decide qué hacer. Así se
+mide, se guarda una preferencia en el servidor del proyecto o se conecta un sistema viejo sin tocar Calcita.
+
+Cada texto también se cambia desde afuera: el componente recibe `texts` con la forma de su namespace en los textos del
+paquete (`src/locales/es.js`), y `ComponentTexts` los cambia para todo lo que va adentro (un módulo con su propio
+vocabulario):
+
+```jsx
+<ServerTable texts={{count: {records_one: '{{total}} pedido', records_other: '{{total}} pedidos'}}} … />
+
+<ComponentTexts namespace="table" texts={{emptyState: {title: 'Sin pedidos'}}}>
+    <OrdersModule />
+</ComponentTexts>
+```
+
+## En un sistema que ya existe
+
+Calcita entra por pedazos en un sistema hecho en PHP, JSP o .NET, sin reescribirlo: cada pedazo es una «isla» de React en
+un `<div>` de la página vieja, con su propio `ToolkitProvider`.
+
+- **Sin router:** `createHashNavigation()` pone las pantallas después del `#` (`/app.php#/ventas`): cambiar de pantalla no
+  recarga, atrás y adelante funcionan y recargar no le pide nada nuevo al servidor viejo. Con la app bajo un prefijo y sin
+  router, `createBrowserNavigation({basePath: '/portal'})`.
+- **Su tema de MUI tal cual:** Calcita lee los colores del tema, con o sin variables CSS y con el prefijo que traiga
+  (`cssVarPrefix`).
+- **Varias islas, cada una con lo suyo:** dos islas pueden ir en idiomas y monedas distintas; `useFormatters()` escribe con
+  los de su isla.
+- **Un backend que contesta a su manera:** `createApiClient({toProblem, mapResponse})` convierte sus errores a RFC 9457
+  (Laravel manda `{message, errors}`) y desenvuelve sus respuestas (`{data: …}`); `onError` recibe cada error en un lugar.
+  Una subida con avance (`uploadWithProgress`) regresa la respuesta tal cual: `apiErrorOf(response)` da el mismo `ApiError`.
+- **Su marca y su menú:** un logo ancho (`wordmark`) en lugar del cuadrado y el nombre; entradas del menú con liga a otro
+  sistema (`href`) o con un ícono ya pintado (`icon`, por ejemplo de iconify); y las ligas de la cuenta (`accountMenuItems`)
+  salen también sin sesión, detrás del engrane («Regresar al sistema»).
+- **Su `sx` gana:** lo que el proyecto pinte con `sx` les gana a los ajustes de Calcita en claro y en oscuro.
+- **Su registro:** `addLogSink` manda cada anotación también a su reporte (Sentry, Datadog, su endpoint).
+- **Si parte el código en archivos** (`manualChunks`): Calcita en el suyo. Junto con lo demás de `node_modules` arma un
+  círculo con MUI y la app truena al abrir («reading 'isValidElementType'»). Su FilePond se queda fuera para seguir bajando
+  solo donde se usa:
+
+```js
+if (id.includes('@stackcraftmx/calcita') && !id.includes('/filepond')) return 'calcita';
+```
+
+```jsx
+const hashNavigation = createHashNavigation();       // una vez, fuera de los componentes
+
+document.querySelectorAll('[data-calcita="sales"]').forEach((element) => {
+    createRoot(element).render(
+        <ThemeProvider theme={legacyTheme}>
+            <ToolkitProvider language={element.lang || 'es'} navigation={hashNavigation}>
+                <SalesOfTheDay onOpen={() => element.dispatchEvent(new CustomEvent('calcita:open-sales', {bubbles: true}))} />
+            </ToolkitProvider>
+        </ThemeProvider>,
+    );
+});
+```
+
+## Detrás de un proxy con prefijo
+
+Para publicar la app en una ruta y no en un subdominio (`miempresa.com/ventas/`), el prefijo se da una vez al construir,
+`ASSET_URL=/ventas`, la misma línea del `.env` del servidor. El proyecto que arma `calcita new` ya lo trae:
+
+1. `vite.config.js`: `base` con el prefijo; Vite se lo pone a sus archivos y a las rutas de `index.html`;
+2. el router con el mismo prefijo (`createBrowserRouter(routes, {basename})`): las pantallas siguen escribiendo sus rutas
+   desde la raíz;
+3. lo de `public/` y `version.json` con `import.meta.env.BASE_URL` (una dirección escrita desde la raíz se rompe detrás del
+   proxy) y el manifiesto con rutas relativas;
+4. el servidor: cada dirección bajo el prefijo que no sea un archivo regresa su `index.html`.
+
+```nginx
+location /ventas/ {
+    try_files $uri $uri/ /ventas/index.html;
+}
+```
 
 ## La petición de la casa
 
@@ -488,7 +593,7 @@ menú, diccionarios) no lleva marca, así que también corre en los componentes
 ## Formularios
 
 Cada campo tiene su vista suelta en la puerta principal (`TextInput`, `SelectInput`, `NumberInput`, `CatalogInput`,
-`ColorInput`; sirven sin formulario) y su conexión: a formik en `/forms` y a react-hook-form en `/react-hook-form`, con
+`ColorInput`; sirven sin formulario; `SelectInput` y `CatalogInput` aceptan varias opciones con `multiple`) y su conexión: a formik en `/forms` y a react-hook-form en `/react-hook-form`, con
 los mismos nombres. Cambiar de librería es cambiar el import.
 
 ```jsx
@@ -507,9 +612,9 @@ import {Form, Formik, FormNumberField, FormProblemAlert, FormTextField, SubmitBu
 </Formik>
 ```
 
-formik y yup vienen con el paquete: se importan de `@stackcraftmx/calcita/forms` y no de `formik` / `yup` directo (con
-otra versión en el proyecto, los campos no encontrarían el formulario). `FormWizard` parte un formulario en pasos, con
-pasos opcionales; los ejemplos traen uno completo.
+formik y yup los instala el proyecto (`pnpm add formik yup`); `Formik`, `Form` y `Yup` también se pueden importar de
+`@stackcraftmx/calcita/forms`, que es la misma copia. `FormWizard` parte un formulario en pasos, con pasos opcionales (hay
+uno para formik y otro para react-hook-form); los ejemplos traen los dos.
 
 Para que el formulario se vea como los de Apple (Ajustes, la hoja «Nuevo evento» de Calendario), los campos van dentro de
 una `FormSection`: cada uno se vuelve un renglón, con la etiqueta a la izquierda y el valor a la derecha, sin la caja de

package/cli/projectFiles.js

@@ -5,10 +5,12 @@
 import {versionsOf} from './packageVersions.js';
 import {primaryColorOf, templateFlagsOf} from './projectAnswers.js';
 
-// lo que pide toda app con Calcita: React, MUI, el router, los avisos y las máquinas de estados que usa su puerta principal
+// lo que pide toda app con Calcita: React, MUI, el router, los avisos y las máquinas de estados que usa su puerta principal, y
+// formik y yup (los mensajes de validación en español salen de /forms en main.jsx, y la cuenta usa formik). Desde la 0.25 los
+// pone el proyecto: Calcita ya no los trae adentro
 const BASE_DEPENDENCIES = Object.freeze([
-    '@emotion/react', '@emotion/styled', '@mui/icons-material', '@mui/material', '@xstate/react', 'react', 'react-dom', 'react-router',
-    'sonner', 'xstate',
+    '@emotion/react', '@emotion/styled', '@mui/icons-material', '@mui/material', '@xstate/react', 'formik', 'react', 'react-dom',
+    'react-router', 'sonner', 'xstate', 'yup',
 ]);
 const HOOK_FORM_DEPENDENCIES = Object.freeze(['@hookform/resolvers', 'react-hook-form']);
 // la cuenta: las llaves de acceso (las pide @stackcraftmx/calcita/account) y el QR de la demostración

package/cli/templates/project/README.md.tpl

@@ -42,6 +42,34 @@ src/
   validaciones) ya vienen.
 - **Imports con el alias `@/`** (= `src/`), declarado en `vite.config.js` y en `jsconfig.json`.
 
+## Publicar una versión nueva
+
+`pnpm build` deja la app en `dist/`, con `version.json` (la versión de esa compilación). La app publicada lo vuelve a leer al
+abrirla y cada tanto: si ya hay otra, se recarga sola cuando estuvo fuera 15 minutos o más (una pestaña de ayer, la app
+anclada al inicio del iPhone) y, si no, enseña el aviso «Versión nueva» con su botón. Para que funcione, el servidor no
+debe guardar `index.html` ni `version.json` (`Cache-Control: no-cache`); los archivos de `dist/assets/` sí, un año.
+
+## Detrás de un proxy con prefijo
+
+Para publicarla en una ruta y no en un subdominio (`miempresa.com/ventas/`), el prefijo se da una vez al construir:
+
+```bash
+ASSET_URL=/ventas pnpm build
+```
+
+Vite le pone el prefijo a sus archivos y a las rutas de `index.html`, el router lo quita al leer la dirección y las pantallas
+siguen escribiendo sus rutas desde la raíz (`/contacts`). Lo de `public/` se pide con `publicUrlOf('favicon.svg')`
+(`src/core/publicPaths.js`), nunca escrito desde la raíz. En el servidor, cada dirección bajo el prefijo que no sea un archivo
+regresa su `index.html`:
+
+```nginx
+location /ventas/ {
+    try_files $uri $uri/ /ventas/index.html;
+}
+```
+
+Con otro prefijo se vuelve a construir.
+
 ## Crecer la app con el CLI
 
 ```bash

package/cli/templates/project/public/manifest.webmanifest.tpl

@@ -1,17 +1,17 @@
 {
   "name": "__APP_TITLE__",
   "short_name": "__APP_TITLE__",
-  "id": "/",
-  "start_url": "/",
-  "scope": "/",
+  "id": "./",
+  "start_url": "./",
+  "scope": "./",
   "display": "standalone",
   "background_color": "#FFFFFF",
   "theme_color": "__PRIMARY_COLOR__",
   "lang": "es-MX",
   "dir": "ltr",
   "icons": [
-    {"src": "/icons/icon-192.png", "sizes": "192x192", "type": "image/png", "purpose": "any"},
-    {"src": "/icons/icon-512.png", "sizes": "512x512", "type": "image/png", "purpose": "any"},
-    {"src": "/icons/icon-512-maskable.png", "sizes": "512x512", "type": "image/png", "purpose": "maskable"}
+    {"src": "icons/icon-192.png", "sizes": "192x192", "type": "image/png", "purpose": "any"},
+    {"src": "icons/icon-512.png", "sizes": "512x512", "type": "image/png", "purpose": "any"},
+    {"src": "icons/icon-512-maskable.png", "sizes": "512x512", "type": "image/png", "purpose": "maskable"}
   ]
 }

package/cli/templates/project/src/app/AppProviders.jsx.tpl

@@ -1,5 +1,7 @@
 // La raíz de la app: el ÚNICO lugar donde se conecta el framework. ToolkitProvider recibe el idioma, los textos, la zona, la
-// moneda y el router; los avisos (Toaster) se montan aquí una vez, para todas las pantallas.
+// moneda y el router; los avisos (Toaster) se montan aquí una vez, para todas las pantallas. Aquí también se vigila si ya se
+// publicó otra versión (usePublishedBuildWatch): una pestaña abierta desde ayer, o la app anclada al inicio del iPhone, se
+// actualiza sola si estuvo fuera 15 minutos o más; si no, sale el aviso «Versión nueva» con su botón.
 //#if auth
 //
 // AccountProvider carga la sesión con el conector de la cuenta (core/accountConnector.js) y le pasa a ToolkitProvider la regla
@@ -17,6 +19,7 @@ import {
 //#endif
     Toaster,
     ToolkitProvider,
+    usePublishedBuildWatch,
 } from '@stackcraftmx/calcita';
 //#if auth
 import {AccountProvider} from '@stackcraftmx/calcita/account';
@@ -26,7 +29,7 @@ import {translateWithI18next} from '@stackcraftmx/calcita/i18next';
 //#endif
 import {reactRouterNavigation} from '@stackcraftmx/calcita/react-router';
 
-import {APP_LANGUAGES, APP_NAME, PRODUCT_CURRENCY, PRODUCT_TIME_ZONE} from '@/app/appSettings.js';
+import {APP_BUILD_ID, APP_LANGUAGES, APP_NAME, BUILD_VERSION_URL, PRODUCT_CURRENCY, PRODUCT_TIME_ZONE} from '@/app/appSettings.js';
 //#if !i18next
 import {APP_TEXTS} from '@/app/appTexts.js';
 //#endif
@@ -44,6 +47,7 @@ const translate = translateWithI18next(i18n);
 
 export const AppProviders = () => {
     const [language, setLanguage] = useState(APP_LANGUAGES.spanish);
+    usePublishedBuildWatch({url: BUILD_VERSION_URL, buildId: APP_BUILD_ID});
 
     // el idioma de la página, para el lector de pantalla y el corrector del navegador
     useEffect(() => {
@@ -70,7 +74,7 @@ export const AppProviders = () => {
                                  onLanguageChange={changeLanguage} translate={translate}
 //#endif
                                  timeZone={PRODUCT_TIME_ZONE} currency={PRODUCT_CURRENCY} appName={APP_NAME} navigation={reactRouterNavigation}
-                                 canAccess={canAccess}>
+                                 buildId={APP_BUILD_ID} canAccess={canAccess}>
                     <Outlet />
                     <Toaster />
 //#if pwa
@@ -90,7 +94,8 @@ export const AppProviders = () => {
 //#if i18next
                          onLanguageChange={changeLanguage} translate={translate}
 //#endif
-                         timeZone={PRODUCT_TIME_ZONE} currency={PRODUCT_CURRENCY} appName={APP_NAME} navigation={reactRouterNavigation}>
+                         timeZone={PRODUCT_TIME_ZONE} currency={PRODUCT_CURRENCY} appName={APP_NAME} navigation={reactRouterNavigation}
+                         buildId={APP_BUILD_ID}>
             <Outlet />
             <Toaster />
 //#if pwa

package/cli/templates/project/src/app/appRouter.jsx.tpl

@@ -12,7 +12,7 @@ import {RouteErrorScreen, withAccess, withChunkRecovery} from '@stackcraftmx/cal
 
 import {AppProviders} from '@/app/AppProviders.jsx';
 import {AppShell} from '@/app/AppShell.jsx';
-import {APP_PATHS} from '@/core';
+import {APP_PATHS, ROUTER_BASENAME} from '@/core';
 
 const ROUTE_MODULES = import.meta.glob('@/modules/*/routes.js', {eager: true});
 const MENU_MODULES = import.meta.glob('@/modules/*/menu.js', {eager: true});
@@ -46,4 +46,6 @@ export const appRouter = createBrowserRouter([
             },
         ]),
     },
-]);
+// detrás de un proxy con prefijo (ASSET_URL), el router lo quita al leer la dirección y lo pone en cada liga: las pantallas
+// siguen escribiendo sus rutas desde la raíz ('/contacts')
+], {basename: ROUTER_BASENAME});

package/cli/templates/project/src/app/appSettings.js.tpl

@@ -1,4 +1,5 @@
 // Lo que la app le pasa a ToolkitProvider y que no cambia mientras corre.
+import {publicUrlOf} from '@/core';
 
 /** El nombre de la app: en la barra y en la pestaña, después del título de cada pantalla («Contactos | __APP_TITLE__»). */
 export const APP_NAME = '__APP_TITLE__';
@@ -9,5 +10,18 @@ export const PRODUCT_TIME_ZONE = 'America/Mexico_City';
 /** La moneda de los montos (ISO 4217). */
 export const PRODUCT_CURRENCY = 'MXN';
 
+/**
+ * La versión del front que corre en esta pestaña: la pone el build (VITE_BUILD_ID, de vite.config.js, la misma que escribe
+ * en version.json). En desarrollo no hay build: queda vacía y no se compara nada.
+ */
+export const APP_BUILD_ID = import.meta.env.VITE_BUILD_ID ?? '';
+
+/**
+ * Dónde está el archivo con la versión publicada: la app lo vuelve a leer al abrirla y cada tanto (usePublishedBuildWatch).
+ * Solo en lo construido, con el prefijo si la app vive detrás de un proxy. OJO: el servidor no debe guardarlo (Cache-Control:
+ * no-cache, como el index.html).
+ */
+export const BUILD_VERSION_URL = import.meta.env.PROD ? publicUrlOf('version.json') : null;
+
 /** Los idiomas que ofrece la app; el primero es el de arranque. */
 export const APP_LANGUAGES = Object.freeze({spanish: 'es', english: 'en'});

package/cli/templates/project/src/core/AppLogo.jsx.tpl

@@ -4,9 +4,11 @@
 // Genérico, sin estado: function (regla de la casa).
 import Box from '@mui/material/Box';
 
+import {publicUrlOf} from '@/core/publicPaths.js';
+
 // el tamaño que piden la barra y la tarjeta de entrar
 const LOGO_SIZE_PIXELS = 28;
 
 export function AppLogo() {
-    return <Box component="img" src="/favicon.svg" alt="" sx={{width: LOGO_SIZE_PIXELS, height: LOGO_SIZE_PIXELS}} />;
+    return <Box component="img" src={publicUrlOf('favicon.svg')} alt="" sx={{width: LOGO_SIZE_PIXELS, height: LOGO_SIZE_PIXELS}} />;
 }

package/cli/templates/project/src/core/index.js.tpl

@@ -2,6 +2,7 @@
 // ruta. Core no importa módulos ni app/: si algo lo usan dos módulos, sube aquí.
 export {APP_PATHS} from '@/core/appPaths.js';
 export {AppLogo} from '@/core/AppLogo.jsx';
+export {ROUTER_BASENAME, publicUrlOf} from '@/core/publicPaths.js';
 export {apiClient} from '@/core/apiClient.js';
 //#if auth
 export {DEMO_USER, USES_DEMO_ACCOUNT, accountConnector} from '@/core/accountConnector.js';

package/cli/templates/project/src/core/publicPaths.js.tpl

@@ -0,0 +1,24 @@
+// Dónde vive la app: en la raíz o detrás de un proxy con prefijo (miempresa.com/ventas/, sin subdominio). El prefijo se da UNA
+// vez, al construir, con ASSET_URL=/ventas (vite.config.js), la misma línea que lleva el .env del servidor. Vite lo deja en
+// import.meta.env.BASE_URL ('/' o '/ventas/') y de aquí lo toman el router (basename), las imágenes de public/ y version.json.
+//
+// OJO: una dirección escrita a mano desde la raíz ('/favicon.svg', '/version.json') funciona en la raíz y se rompe detrás del
+// proxy: se arma con publicUrlOf.
+//
+// Funciones puras, no renderizan: function (regla de la casa).
+
+// en las pruebas de node no hay import.meta.env (es de Vite): ahí, la raíz
+const APP_BASE_URL = import.meta.env?.BASE_URL ?? '/';
+
+/** El prefijo como lo pide el router: '/ventas' (sin la diagonal del final) o '/'. */
+export const ROUTER_BASENAME = APP_BASE_URL.replace(/\/$/, '') || '/';
+
+/**
+ * La dirección de un archivo de public/ con el prefijo: 'favicon.svg' → '/ventas/favicon.svg'.
+ *
+ * @param {string} path la ruta dentro de public/, sin la diagonal del inicio
+ * @returns {string}
+ */
+export function publicUrlOf(path) {
+    return `${APP_BASE_URL}${path}`;
+}

package/cli/templates/project/vite.config.js.tpl

@@ -17,8 +17,34 @@ const SINGLE_COPY_PACKAGES = [
 // de los ~790 kB del archivo principal (medido con el proyecto recién creado). Cada pantalla va aparte (rutas lazy)
 const LARGEST_CHUNK_KILOBYTES = 1000;
 
+// Detrás de un proxy con prefijo (miempresa.com/ventas/, sin subdominio): UNA variable al construir, ASSET_URL=/ventas, la
+// misma línea que lleva el .env del servidor. Vite pide sus archivos con el prefijo, se lo pone a las rutas de index.html y lo
+// deja en import.meta.env.BASE_URL, de donde lo toman el router, las imágenes y version.json (src/core/publicPaths.js). Sin
+// ella, todo en la raíz. Con otro prefijo hay que volver a construir.
+const basePathOf = (assetUrl) => {
+    const prefix = (assetUrl ?? '').trim().replace(/^\/+|\/+$/g, '');
+    return prefix ? `/${prefix}/` : '/';
+};
+
+// La versión de esta compilación: va dentro de la app (import.meta.env.VITE_BUILD_ID → ToolkitProvider buildId) y en
+// dist/version.json, que la app publicada vuelve a leer al abrirla para saber si ya hay otra (usePublishedBuildWatch). Se
+// puede fijar desde afuera (VITE_BUILD_ID=… al construir, p. ej. el commit); si no, la hora en que se construyó
+const BUILD_ID = process.env.VITE_BUILD_ID || new Date().toISOString();
+
+function buildVersionPlugin() {
+    return {
+        name: 'build-version',
+        apply: 'build',
+        generateBundle() {
+            this.emitFile({type: 'asset', fileName: 'version.json', source: JSON.stringify({buildId: BUILD_ID})});
+        },
+    };
+}
+
 export default defineConfig({
-    plugins: [react()],
+    base: basePathOf(process.env.ASSET_URL),
+    plugins: [react(), buildVersionPlugin()],
+    define: {'import.meta.env.VITE_BUILD_ID': JSON.stringify(BUILD_ID)},
     resolve: {
         alias: {'@': fileURLToPath(new URL('./src', import.meta.url))},
         dedupe: SINGLE_COPY_PACKAGES,

package/dist/DataTable/AuditTrailTable.js

@@ -4,7 +4,7 @@ import { useToolkitTranslation } from "../toolkit/useToolkitTranslation.js";
 import ServerTable from "./ServerTable.js";
 import { FILTER_KINDS } from "./useTableState.js";
 import { labelOf, lookup } from "../dictionaries/dictionaries.js";
-import { formatDateTime } from "../formatting.js";
+import { useFormatters } from "../toolkit/useFormatters.js";
 import StatusChip from "../ui/labels/StatusChip.js";
 const AUDIT_FILTER_DEFAULTS = { event: [] };
 const AUDIT_FILTER_KINDS = { event: FILTER_KINDS.multiSelect };
@@ -17,9 +17,11 @@ function AuditTrailTable({
   ariaLabel,
   maxGridHeight = null,
   refreshToken,
-  eventSuffixOf = null
+  eventSuffixOf = null,
+  texts
 }) {
-  const { t } = useToolkitTranslation(["table", "dictionaries"]);
+  const { t } = useToolkitTranslation(["table", "dictionaries"], texts);
+  const { formatDateTime } = useFormatters();
   const columns = [
     {
       field: "occurred_at",

package/dist/DataTable/AuditTrailTable.js.map

@@ -1 +1 @@
-{"version":3,"file":"AuditTrailTable.js","sources":["../../src/DataTable/AuditTrailTable.jsx"],"sourcesContent":["// Tabla de historial de un renglón: sus eventos, paginados y filtrados EN EL SERVIDOR (regla de tablas).\n//\n// La usan AuditTrailDialog (historial en un diálogo desde una lista) y los detalles con historial a la vista (p. ej. el\n// detalle de una cuenta). Recibe QUÉ consultar (fetchPage) y CÓMO nombrar los eventos (diccionarios) por props: core no\n// conoce el API.\n//\n// Filtros y página en memoria (sin prefijo de URL): el historial vive dentro de otra pantalla y escribir en la barra de\n// direcciones ensuciaría la URL de esa pantalla.\n//\n// Contrato de fetchPage: el de ServerTable ({filters: {event: [...]}, sortOrders, page, pageSize}) →\n// {rows: [{id, event, result, occurred_at, actor: {id, name}|null, ...}], total, facets: {event: [{value, total}]}}.\n//\n// Genérico del paquete: function (regla de la casa).\nimport {useToolkitTranslation} from '@/toolkit/useToolkitTranslation.js';\n\nimport ServerTable from '@/DataTable/ServerTable.jsx';\nimport {FILTER_KINDS} from '@/DataTable/useTableState.js';\nimport {labelOf, lookup} from '@/dictionaries/dictionaries.js';\nimport {formatDateTime} from '@/formatting.js';\nimport StatusChip from '@/ui/labels/StatusChip.jsx';\n\n// OJO: constantes de módulo; objetos nuevos en cada render reinician el estado de la tabla\nconst AUDIT_FILTER_DEFAULTS = {event: []};\nconst AUDIT_FILTER_KINDS = {event: FILTER_KINDS.multiSelect};\n\n/**\n * @param {object} props\n * @param {string} props.subjectKey identifica el renglón (cambia la consulta al cambiar de renglón); '' no consulta\n * @param {(tableRequest: object, signal: AbortSignal) => Promise<{rows: Array, total: number, facets?: object}>} props.fetchPage\n * @param {Record<string, object>} props.eventDictionary\n * @param {Record<string, object>} [props.resultDictionary]\n * @param {Array<object>} [props.extraColumns] columnas del DataGrid propias del módulo (archivo, origen, motivo...)\n * @param {(row: any) => string|null} [props.eventSuffixOf] texto que va después del evento con « · » (p. ej. para\n *     quién era la descarga); null = solo el evento\n * @param {string} props.ariaLabel\n * @param {number} [props.maxGridHeight]\n * @param {unknown} [props.refreshToken] cambia para volver a consultar (después de una acción sobre el mismo renglón)\n */\nexport default function AuditTrailTable({\n    subjectKey, fetchPage, eventDictionary, resultDictionary, extraColumns = [], ariaLabel, maxGridHeight = null, refreshToken,\n    eventSuffixOf = null,\n}) {\n    const {t} = useToolkitTranslation(['table', 'dictionaries']);\n\n    const columns = [\n        {\n            field: 'occurred_at', headerName: t('table:audit.columns.occurredAt'), width: 170, sortable: false,\n            valueFormatter: (value) => (value ? formatDateTime(value) : '—'),\n        },\n        {\n            field: 'event', headerName: t('table:audit.columns.event'), flex: 1, minWidth: 230, sortable: false,\n            renderCell: ({row}) => <StatusChip variant=\"chip\" dictionary={eventDictionary} value={row.event} suffix={eventSuffixOf?.(row) ?? undefined} />,\n        },\n        ...(resultDictionary ? [{\n            field: 'result', headerName: t('table:audit.columns.result'), width: 170, sortable: false,\n            renderCell: ({row}) => <StatusChip dictionary={resultDictionary} value={row.result} />,\n        }] : []),\n        {\n            field: 'actor', headerName: t('table:audit.columns.actor'), width: 190, sortable: false,\n            // los eventos que escribe un proceso automático o la propia persona no tienen actor: se dice quién fue en palabras\n            valueGetter: (value) => value?.name ?? t('table:audit.systemActor'),\n        },\n        ...extraColumns,\n    ];\n\n    // OJO: key={subjectKey}. Sin prefijo, los filtros viven en memoria dentro de ServerTable; si el diálogo o la página\n    // siguen montados al pasar a otro renglón, el filtro de evento del renglón anterior se quedaría puesto\n    return (\n        <ServerTable\n            key={subjectKey || 'without-subject'}\n            queryKey={subjectKey ? `audit:${subjectKey}` : ''}\n            enabled={Boolean(subjectKey)}\n            fetchPage={fetchPage}\n            refreshToken={refreshToken}\n            columns={columns}\n            filterDefaults={AUDIT_FILTER_DEFAULTS}\n            filterKinds={AUDIT_FILTER_KINDS}\n            searchField={null}\n            chipConfig={[]}\n            quickFilters={[{\n                field: 'event',\n                facetKey: 'event',\n                caption: t('table:audit.eventFilterCaption'),\n                renderLabel: (eventValue) => labelOf(lookup(eventDictionary, eventValue), t),\n            }]}\n            countLabel={(total) => t('table:audit.count', {count: total})}\n            emptyLabel={t('table:audit.empty')}\n            defaultPageSize={10}\n            pageSizeOptions={[10, 25, 50]}\n            maxGridHeight={maxGridHeight}\n            ariaLabel={ariaLabel}\n        />\n    );\n}\n"],"names":[],"mappings":";;;;;;;;AAsBA,MAAM,wBAAwB,EAAC,OAAO,GAAC;AACvC,MAAM,qBAAqB,EAAC,OAAO,aAAa,YAAA;AAehD,SAAwB,gBAAgB;AAAA,EACpC;AAAA,EAAY;AAAA,EAAW;AAAA,EAAiB;AAAA,EAAkB,eAAe,CAAA;AAAA,EAAI;AAAA,EAAW,gBAAgB;AAAA,EAAM;AAAA,EAC9G,gBAAgB;AACpB,GAAG;AACC,QAAM,EAAC,EAAA,IAAK,sBAAsB,CAAC,SAAS,cAAc,CAAC;AAE3D,QAAM,UAAU;AAAA,IACZ;AAAA,MACI,OAAO;AAAA,MAAe,YAAY,EAAE,gCAAgC;AAAA,MAAG,OAAO;AAAA,MAAK,UAAU;AAAA,MAC7F,gBAAgB,CAAC,UAAW,QAAQ,eAAe,KAAK,IAAI;AAAA,IAAA;AAAA,IAEhE;AAAA,MACI,OAAO;AAAA,MAAS,YAAY,EAAE,2BAA2B;AAAA,MAAG,MAAM;AAAA,MAAG,UAAU;AAAA,MAAK,UAAU;AAAA,MAC9F,YAAY,CAAC,EAAC,UAAS,oBAAC,cAAW,SAAQ,QAAO,YAAY,iBAAiB,OAAO,IAAI,OAAO,QAAQ,gBAAgB,GAAG,KAAK,OAAA,CAAW;AAAA,IAAA;AAAA,IAEhJ,GAAI,mBAAmB,CAAC;AAAA,MACpB,OAAO;AAAA,MAAU,YAAY,EAAE,4BAA4B;AAAA,MAAG,OAAO;AAAA,MAAK,UAAU;AAAA,MACpF,YAAY,CAAC,EAAC,IAAA,MAAS,oBAAC,YAAA,EAAW,YAAY,kBAAkB,OAAO,IAAI,OAAA,CAAQ;AAAA,IAAA,CACvF,IAAI,CAAA;AAAA,IACL;AAAA,MACI,OAAO;AAAA,MAAS,YAAY,EAAE,2BAA2B;AAAA,MAAG,OAAO;AAAA,MAAK,UAAU;AAAA;AAAA,MAElF,aAAa,CAAC,UAAU,OAAO,QAAQ,EAAE,yBAAyB;AAAA,IAAA;AAAA,IAEtE,GAAG;AAAA,EAAA;AAKP,SACI;AAAA,IAAC;AAAA,IAAA;AAAA,MAEG,UAAU,aAAa,SAAS,UAAU,KAAK;AAAA,MAC/C,SAAS,QAAQ,UAAU;AAAA,MAC3B;AAAA,MACA;AAAA,MACA;AAAA,MACA,gBAAgB;AAAA,MAChB,aAAa;AAAA,MACb,aAAa;AAAA,MACb,YAAY,CAAA;AAAA,MACZ,cAAc,CAAC;AAAA,QACX,OAAO;AAAA,QACP,UAAU;AAAA,QACV,SAAS,EAAE,gCAAgC;AAAA,QAC3C,aAAa,CAAC,eAAe,QAAQ,OAAO,iBAAiB,UAAU,GAAG,CAAC;AAAA,MAAA,CAC9E;AAAA,MACD,YAAY,CAAC,UAAU,EAAE,qBAAqB,EAAC,OAAO,OAAM;AAAA,MAC5D,YAAY,EAAE,mBAAmB;AAAA,MACjC,iBAAiB;AAAA,MACjB,iBAAiB,CAAC,IAAI,IAAI,EAAE;AAAA,MAC5B;AAAA,MACA;AAAA,IAAA;AAAA,IArBK,cAAc;AAAA,EAAA;AAwB/B;"}
+{"version":3,"file":"AuditTrailTable.js","sources":["../../src/DataTable/AuditTrailTable.jsx"],"sourcesContent":["// Tabla de historial de un renglón: sus eventos, paginados y filtrados EN EL SERVIDOR (regla de tablas).\n//\n// La usan AuditTrailDialog (historial en un diálogo desde una lista) y los detalles con historial a la vista (p. ej. el\n// detalle de una cuenta). Recibe QUÉ consultar (fetchPage) y CÓMO nombrar los eventos (diccionarios) por props: core no\n// conoce el API.\n//\n// Filtros y página en memoria (sin prefijo de URL): el historial vive dentro de otra pantalla y escribir en la barra de\n// direcciones ensuciaría la URL de esa pantalla.\n//\n// Contrato de fetchPage: el de ServerTable ({filters: {event: [...]}, sortOrders, page, pageSize}) →\n// {rows: [{id, event, result, occurred_at, actor: {id, name}|null, ...}], total, facets: {event: [{value, total}]}}.\n//\n// Genérico del paquete: function (regla de la casa).\nimport {useToolkitTranslation} from '@/toolkit/useToolkitTranslation.js';\n\nimport ServerTable from '@/DataTable/ServerTable.jsx';\nimport {FILTER_KINDS} from '@/DataTable/useTableState.js';\nimport {labelOf, lookup} from '@/dictionaries/dictionaries.js';\nimport {useFormatters} from '@/toolkit/useFormatters.js';\nimport StatusChip from '@/ui/labels/StatusChip.jsx';\n\n// OJO: constantes de módulo; objetos nuevos en cada render reinician el estado de la tabla\nconst AUDIT_FILTER_DEFAULTS = {event: []};\nconst AUDIT_FILTER_KINDS = {event: FILTER_KINDS.multiSelect};\n\n/**\n * @param {object} props\n * @param {string} props.subjectKey identifica el renglón (cambia la consulta al cambiar de renglón); '' no consulta\n * @param {(tableRequest: object, signal: AbortSignal) => Promise<{rows: Array, total: number, facets?: object}>} props.fetchPage\n * @param {Record<string, object>} props.eventDictionary\n * @param {Record<string, object>} [props.resultDictionary]\n * @param {Array<object>} [props.extraColumns] columnas del DataGrid propias del módulo (archivo, origen, motivo...)\n * @param {(row: any) => string|null} [props.eventSuffixOf] texto que va después del evento con « · » (p. ej. para\n *     quién era la descarga); null = solo el evento\n * @param {string} props.ariaLabel\n * @param {number} [props.maxGridHeight]\n * @param {unknown} [props.refreshToken] cambia para volver a consultar (después de una acción sobre el mismo renglón)\n * @param {object} [props.texts] los textos que cambian, con la forma de `table` en los textos del paquete\n */\nexport default function AuditTrailTable({\n    subjectKey, fetchPage, eventDictionary, resultDictionary, extraColumns = [], ariaLabel, maxGridHeight = null, refreshToken,\n    eventSuffixOf = null, texts,\n}) {\n    const {t} = useToolkitTranslation(['table', 'dictionaries'], texts);\n    const {formatDateTime} = useFormatters();\n\n    const columns = [\n        {\n            field: 'occurred_at', headerName: t('table:audit.columns.occurredAt'), width: 170, sortable: false,\n            valueFormatter: (value) => (value ? formatDateTime(value) : '—'),\n        },\n        {\n            field: 'event', headerName: t('table:audit.columns.event'), flex: 1, minWidth: 230, sortable: false,\n            renderCell: ({row}) => <StatusChip variant=\"chip\" dictionary={eventDictionary} value={row.event} suffix={eventSuffixOf?.(row) ?? undefined} />,\n        },\n        ...(resultDictionary ? [{\n            field: 'result', headerName: t('table:audit.columns.result'), width: 170, sortable: false,\n            renderCell: ({row}) => <StatusChip dictionary={resultDictionary} value={row.result} />,\n        }] : []),\n        {\n            field: 'actor', headerName: t('table:audit.columns.actor'), width: 190, sortable: false,\n            // los eventos que escribe un proceso automático o la propia persona no tienen actor: se dice quién fue en palabras\n            valueGetter: (value) => value?.name ?? t('table:audit.systemActor'),\n        },\n        ...extraColumns,\n    ];\n\n    // OJO: key={subjectKey}. Sin prefijo, los filtros viven en memoria dentro de ServerTable; si el diálogo o la página\n    // siguen montados al pasar a otro renglón, el filtro de evento del renglón anterior se quedaría puesto\n    return (\n        <ServerTable\n            key={subjectKey || 'without-subject'}\n            queryKey={subjectKey ? `audit:${subjectKey}` : ''}\n            enabled={Boolean(subjectKey)}\n            fetchPage={fetchPage}\n            refreshToken={refreshToken}\n            columns={columns}\n            filterDefaults={AUDIT_FILTER_DEFAULTS}\n            filterKinds={AUDIT_FILTER_KINDS}\n            searchField={null}\n            chipConfig={[]}\n            quickFilters={[{\n                field: 'event',\n                facetKey: 'event',\n                caption: t('table:audit.eventFilterCaption'),\n                renderLabel: (eventValue) => labelOf(lookup(eventDictionary, eventValue), t),\n            }]}\n            countLabel={(total) => t('table:audit.count', {count: total})}\n            emptyLabel={t('table:audit.empty')}\n            defaultPageSize={10}\n            pageSizeOptions={[10, 25, 50]}\n            maxGridHeight={maxGridHeight}\n            ariaLabel={ariaLabel}\n        />\n    );\n}\n"],"names":[],"mappings":";;;;;;;;AAsBA,MAAM,wBAAwB,EAAC,OAAO,GAAC;AACvC,MAAM,qBAAqB,EAAC,OAAO,aAAa,YAAA;AAgBhD,SAAwB,gBAAgB;AAAA,EACpC;AAAA,EAAY;AAAA,EAAW;AAAA,EAAiB;AAAA,EAAkB,eAAe,CAAA;AAAA,EAAI;AAAA,EAAW,gBAAgB;AAAA,EAAM;AAAA,EAC9G,gBAAgB;AAAA,EAAM;AAC1B,GAAG;AACC,QAAM,EAAC,MAAK,sBAAsB,CAAC,SAAS,cAAc,GAAG,KAAK;AAClE,QAAM,EAAC,eAAA,IAAkB,cAAA;AAEzB,QAAM,UAAU;AAAA,IACZ;AAAA,MACI,OAAO;AAAA,MAAe,YAAY,EAAE,gCAAgC;AAAA,MAAG,OAAO;AAAA,MAAK,UAAU;AAAA,MAC7F,gBAAgB,CAAC,UAAW,QAAQ,eAAe,KAAK,IAAI;AAAA,IAAA;AAAA,IAEhE;AAAA,MACI,OAAO;AAAA,MAAS,YAAY,EAAE,2BAA2B;AAAA,MAAG,MAAM;AAAA,MAAG,UAAU;AAAA,MAAK,UAAU;AAAA,MAC9F,YAAY,CAAC,EAAC,UAAS,oBAAC,cAAW,SAAQ,QAAO,YAAY,iBAAiB,OAAO,IAAI,OAAO,QAAQ,gBAAgB,GAAG,KAAK,OAAA,CAAW;AAAA,IAAA;AAAA,IAEhJ,GAAI,mBAAmB,CAAC;AAAA,MACpB,OAAO;AAAA,MAAU,YAAY,EAAE,4BAA4B;AAAA,MAAG,OAAO;AAAA,MAAK,UAAU;AAAA,MACpF,YAAY,CAAC,EAAC,IAAA,MAAS,oBAAC,YAAA,EAAW,YAAY,kBAAkB,OAAO,IAAI,OAAA,CAAQ;AAAA,IAAA,CACvF,IAAI,CAAA;AAAA,IACL;AAAA,MACI,OAAO;AAAA,MAAS,YAAY,EAAE,2BAA2B;AAAA,MAAG,OAAO;AAAA,MAAK,UAAU;AAAA;AAAA,MAElF,aAAa,CAAC,UAAU,OAAO,QAAQ,EAAE,yBAAyB;AAAA,IAAA;AAAA,IAEtE,GAAG;AAAA,EAAA;AAKP,SACI;AAAA,IAAC;AAAA,IAAA;AAAA,MAEG,UAAU,aAAa,SAAS,UAAU,KAAK;AAAA,MAC/C,SAAS,QAAQ,UAAU;AAAA,MAC3B;AAAA,MACA;AAAA,MACA;AAAA,MACA,gBAAgB;AAAA,MAChB,aAAa;AAAA,MACb,aAAa;AAAA,MACb,YAAY,CAAA;AAAA,MACZ,cAAc,CAAC;AAAA,QACX,OAAO;AAAA,QACP,UAAU;AAAA,QACV,SAAS,EAAE,gCAAgC;AAAA,QAC3C,aAAa,CAAC,eAAe,QAAQ,OAAO,iBAAiB,UAAU,GAAG,CAAC;AAAA,MAAA,CAC9E;AAAA,MACD,YAAY,CAAC,UAAU,EAAE,qBAAqB,EAAC,OAAO,OAAM;AAAA,MAC5D,YAAY,EAAE,mBAAmB;AAAA,MACjC,iBAAiB;AAAA,MACjB,iBAAiB,CAAC,IAAI,IAAI,EAAE;AAAA,MAC5B;AAAA,MACA;AAAA,IAAA;AAAA,IArBK,cAAc;AAAA,EAAA;AAwB/B;"}

package/dist/DataTable/ColumnFilters/MultiSelectColumnFilter.js

@@ -7,10 +7,11 @@ import FormControlLabel from "@mui/material/FormControlLabel";
 import Stack from "@mui/material/Stack";
 import TextField from "@mui/material/TextField";
 import Typography from "@mui/material/Typography";
-import { formatNumber } from "../../formatting.js";
+import { useFormatters } from "../../toolkit/useFormatters.js";
 const SEARCHABLE_FROM_OPTIONS = 8;
 function MultiSelectColumnFilter({ value = [], onChange, options = [], renderOption }) {
   const { t } = useToolkitTranslation("table");
+  const { formatNumber } = useFormatters();
   const [searchText, setSearchText] = useState("");
   const toggleOption = (optionValue) => onChange(value.includes(optionValue) ? value.filter((currentValue) => currentValue !== optionValue) : [...value, optionValue]);
   const isSearchable = options.length >= SEARCHABLE_FROM_OPTIONS;

package/dist/DataTable/ColumnFilters/MultiSelectColumnFilter.js.map

@@ -1 +1 @@
-{"version":3,"file":"MultiSelectColumnFilter.js","sources":["../../../src/DataTable/ColumnFilters/MultiSelectColumnFilter.jsx"],"sourcesContent":["// Filtro de opciones de una columna.\n//\n// Dos cosas lo separan de un multi-select cualquiera:\n//   - las opciones NO salen de las filas visibles: salen de las FACETAS que el servidor calcula sobre el resultado\n//     COMPLETO (ofrecer solo lo que aparece en las primeras 25 filas convierte el filtro en adorno);\n//   - cada opción trae su conteo, que es lo que deja decidir si vale la pena filtrar.\n//\n// Desde ocho opciones aparece una caja para buscar entre ellas.\n//\n// Genérico del paquete: function (regla de la casa).\nimport {useState} from 'react';\nimport {useToolkitTranslation} from '@/toolkit/useToolkitTranslation.js';\nimport Checkbox from '@mui/material/Checkbox';\nimport FormControlLabel from '@mui/material/FormControlLabel';\nimport Stack from '@mui/material/Stack';\nimport TextField from '@mui/material/TextField';\nimport Typography from '@mui/material/Typography';\n\nimport {formatNumber} from '@/formatting.js';\n\nconst SEARCHABLE_FROM_OPTIONS = 8;\n\n/**\n * @param {object} props\n * @param {string[]} [props.value]\n * @param {(value: string[]) => void} props.onChange\n * @param {Array<{value: string, total: number}>} [props.options] faceta del servidor\n * @param {(value: string) => import('react').ReactNode} [props.renderOption] cómo se lee el valor (diccionario)\n */\nexport default function MultiSelectColumnFilter({value = [], onChange, options = [], renderOption}) {\n    const {t} = useToolkitTranslation('table');\n    const [searchText, setSearchText] = useState('');\n\n    const toggleOption = (optionValue) => onChange(value.includes(optionValue)\n        ? value.filter((currentValue) => currentValue !== optionValue)\n        : [...value, optionValue]);\n\n    const isSearchable = options.length >= SEARCHABLE_FROM_OPTIONS;\n    const visibleOptions = isSearchable && searchText\n        ? options.filter((option) => String(option.value).toLowerCase().includes(searchText.toLowerCase()))\n        : options;\n\n    return (\n        <Stack spacing={1}>\n            {isSearchable && (\n                <TextField size=\"small\" autoFocus fullWidth placeholder={t('options.searchPlaceholder')} value={searchText}\n                           onChange={(event) => setSearchText(event.target.value)} />\n            )}\n            <Stack sx={{maxHeight: 300, overflowY: 'auto'}}>\n                {options.length === 0 && (\n                    <Typography variant=\"caption\" color=\"text.secondary\">{t('options.empty')}</Typography>\n                )}\n                {options.length > 0 && visibleOptions.length === 0 && (\n                    <Typography variant=\"caption\" color=\"text.secondary\">{t('options.noMatch', {text: searchText})}</Typography>\n                )}\n                {visibleOptions.map((option) => (\n                    <FormControlLabel\n                        key={option.value}\n                        control={<Checkbox size=\"small\" checked={value.includes(option.value)} onChange={() => toggleOption(option.value)} />}\n                        label={(\n                            <Stack direction=\"row\" spacing={0.75} sx={{alignItems: 'center'}}>\n                                {renderOption ? renderOption(option.value) : <Typography variant=\"body2\">{option.value}</Typography>}\n                                <Typography variant=\"caption\" color=\"text.secondary\">{formatNumber(option.total)}</Typography>\n                            </Stack>\n                        )}\n                    />\n                ))}\n            </Stack>\n        </Stack>\n    );\n}\n"],"names":[],"mappings":";;;;;;;;;;AAoBA,MAAM,0BAA0B;AAShC,SAAwB,wBAAwB,EAAC,QAAQ,CAAA,GAAI,UAAU,UAAU,CAAA,GAAI,gBAAe;AAChG,QAAM,EAAC,EAAA,IAAK,sBAAsB,OAAO;AACzC,QAAM,CAAC,YAAY,aAAa,IAAI,SAAS,EAAE;AAE/C,QAAM,eAAe,CAAC,gBAAgB,SAAS,MAAM,SAAS,WAAW,IACnE,MAAM,OAAO,CAAC,iBAAiB,iBAAiB,WAAW,IAC3D,CAAC,GAAG,OAAO,WAAW,CAAC;AAE7B,QAAM,eAAe,QAAQ,UAAU;AACvC,QAAM,iBAAiB,gBAAgB,aACjC,QAAQ,OAAO,CAAC,WAAW,OAAO,OAAO,KAAK,EAAE,cAAc,SAAS,WAAW,YAAA,CAAa,CAAC,IAChG;AAEN,SACI,qBAAC,OAAA,EAAM,SAAS,GACX,UAAA;AAAA,IAAA,gBACG;AAAA,MAAC;AAAA,MAAA;AAAA,QAAU,MAAK;AAAA,QAAQ,WAAS;AAAA,QAAC,WAAS;AAAA,QAAC,aAAa,EAAE,2BAA2B;AAAA,QAAG,OAAO;AAAA,QACrF,UAAU,CAAC,UAAU,cAAc,MAAM,OAAO,KAAK;AAAA,MAAA;AAAA,IAAA;AAAA,IAEpE,qBAAC,SAAM,IAAI,EAAC,WAAW,KAAK,WAAW,UAClC,UAAA;AAAA,MAAA,QAAQ,WAAW,KAChB,oBAAC,YAAA,EAAW,SAAQ,WAAU,OAAM,kBAAkB,UAAA,EAAE,eAAe,EAAA,CAAE;AAAA,MAE5E,QAAQ,SAAS,KAAK,eAAe,WAAW,yBAC5C,YAAA,EAAW,SAAQ,WAAU,OAAM,kBAAkB,UAAA,EAAE,mBAAmB,EAAC,MAAM,WAAA,CAAW,GAAE;AAAA,MAElG,eAAe,IAAI,CAAC,WACjB;AAAA,QAAC;AAAA,QAAA;AAAA,UAEG,SAAS,oBAAC,UAAA,EAAS,MAAK,SAAQ,SAAS,MAAM,SAAS,OAAO,KAAK,GAAG,UAAU,MAAM,aAAa,OAAO,KAAK,GAAG;AAAA,UACnH,OACI,qBAAC,OAAA,EAAM,WAAU,OAAM,SAAS,MAAM,IAAI,EAAC,YAAY,SAAA,GAClD,UAAA;AAAA,YAAA,eAAe,aAAa,OAAO,KAAK,wBAAK,YAAA,EAAW,SAAQ,SAAS,UAAA,OAAO,MAAA,CAAM;AAAA,YACvF,oBAAC,cAAW,SAAQ,WAAU,OAAM,kBAAkB,UAAA,aAAa,OAAO,KAAK,EAAA,CAAE;AAAA,UAAA,EAAA,CACrF;AAAA,QAAA;AAAA,QANC,OAAO;AAAA,MAAA,CASnB;AAAA,IAAA,EAAA,CACL;AAAA,EAAA,GACJ;AAER;"}
+{"version":3,"file":"MultiSelectColumnFilter.js","sources":["../../../src/DataTable/ColumnFilters/MultiSelectColumnFilter.jsx"],"sourcesContent":["// Filtro de opciones de una columna.\n//\n// Dos cosas lo separan de un multi-select cualquiera:\n//   - las opciones NO salen de las filas visibles: salen de las FACETAS que el servidor calcula sobre el resultado\n//     COMPLETO (ofrecer solo lo que aparece en las primeras 25 filas convierte el filtro en adorno);\n//   - cada opción trae su conteo, que es lo que deja decidir si vale la pena filtrar.\n//\n// Desde ocho opciones aparece una caja para buscar entre ellas.\n//\n// Genérico del paquete: function (regla de la casa).\nimport {useState} from 'react';\nimport {useToolkitTranslation} from '@/toolkit/useToolkitTranslation.js';\nimport Checkbox from '@mui/material/Checkbox';\nimport FormControlLabel from '@mui/material/FormControlLabel';\nimport Stack from '@mui/material/Stack';\nimport TextField from '@mui/material/TextField';\nimport Typography from '@mui/material/Typography';\n\nimport {useFormatters} from '@/toolkit/useFormatters.js';\n\nconst SEARCHABLE_FROM_OPTIONS = 8;\n\n/**\n * @param {object} props\n * @param {string[]} [props.value]\n * @param {(value: string[]) => void} props.onChange\n * @param {Array<{value: string, total: number}>} [props.options] faceta del servidor\n * @param {(value: string) => import('react').ReactNode} [props.renderOption] cómo se lee el valor (diccionario)\n */\nexport default function MultiSelectColumnFilter({value = [], onChange, options = [], renderOption}) {\n    const {t} = useToolkitTranslation('table');\n    const {formatNumber} = useFormatters();\n    const [searchText, setSearchText] = useState('');\n\n    const toggleOption = (optionValue) => onChange(value.includes(optionValue)\n        ? value.filter((currentValue) => currentValue !== optionValue)\n        : [...value, optionValue]);\n\n    const isSearchable = options.length >= SEARCHABLE_FROM_OPTIONS;\n    const visibleOptions = isSearchable && searchText\n        ? options.filter((option) => String(option.value).toLowerCase().includes(searchText.toLowerCase()))\n        : options;\n\n    return (\n        <Stack spacing={1}>\n            {isSearchable && (\n                <TextField size=\"small\" autoFocus fullWidth placeholder={t('options.searchPlaceholder')} value={searchText}\n                           onChange={(event) => setSearchText(event.target.value)} />\n            )}\n            <Stack sx={{maxHeight: 300, overflowY: 'auto'}}>\n                {options.length === 0 && (\n                    <Typography variant=\"caption\" color=\"text.secondary\">{t('options.empty')}</Typography>\n                )}\n                {options.length > 0 && visibleOptions.length === 0 && (\n                    <Typography variant=\"caption\" color=\"text.secondary\">{t('options.noMatch', {text: searchText})}</Typography>\n                )}\n                {visibleOptions.map((option) => (\n                    <FormControlLabel\n                        key={option.value}\n                        control={<Checkbox size=\"small\" checked={value.includes(option.value)} onChange={() => toggleOption(option.value)} />}\n                        label={(\n                            <Stack direction=\"row\" spacing={0.75} sx={{alignItems: 'center'}}>\n                                {renderOption ? renderOption(option.value) : <Typography variant=\"body2\">{option.value}</Typography>}\n                                <Typography variant=\"caption\" color=\"text.secondary\">{formatNumber(option.total)}</Typography>\n                            </Stack>\n                        )}\n                    />\n                ))}\n            </Stack>\n        </Stack>\n    );\n}\n"],"names":[],"mappings":";;;;;;;;;;AAoBA,MAAM,0BAA0B;AAShC,SAAwB,wBAAwB,EAAC,QAAQ,CAAA,GAAI,UAAU,UAAU,CAAA,GAAI,gBAAe;AAChG,QAAM,EAAC,EAAA,IAAK,sBAAsB,OAAO;AACzC,QAAM,EAAC,aAAA,IAAgB,cAAA;AACvB,QAAM,CAAC,YAAY,aAAa,IAAI,SAAS,EAAE;AAE/C,QAAM,eAAe,CAAC,gBAAgB,SAAS,MAAM,SAAS,WAAW,IACnE,MAAM,OAAO,CAAC,iBAAiB,iBAAiB,WAAW,IAC3D,CAAC,GAAG,OAAO,WAAW,CAAC;AAE7B,QAAM,eAAe,QAAQ,UAAU;AACvC,QAAM,iBAAiB,gBAAgB,aACjC,QAAQ,OAAO,CAAC,WAAW,OAAO,OAAO,KAAK,EAAE,cAAc,SAAS,WAAW,YAAA,CAAa,CAAC,IAChG;AAEN,SACI,qBAAC,OAAA,EAAM,SAAS,GACX,UAAA;AAAA,IAAA,gBACG;AAAA,MAAC;AAAA,MAAA;AAAA,QAAU,MAAK;AAAA,QAAQ,WAAS;AAAA,QAAC,WAAS;AAAA,QAAC,aAAa,EAAE,2BAA2B;AAAA,QAAG,OAAO;AAAA,QACrF,UAAU,CAAC,UAAU,cAAc,MAAM,OAAO,KAAK;AAAA,MAAA;AAAA,IAAA;AAAA,IAEpE,qBAAC,SAAM,IAAI,EAAC,WAAW,KAAK,WAAW,UAClC,UAAA;AAAA,MAAA,QAAQ,WAAW,KAChB,oBAAC,YAAA,EAAW,SAAQ,WAAU,OAAM,kBAAkB,UAAA,EAAE,eAAe,EAAA,CAAE;AAAA,MAE5E,QAAQ,SAAS,KAAK,eAAe,WAAW,yBAC5C,YAAA,EAAW,SAAQ,WAAU,OAAM,kBAAkB,UAAA,EAAE,mBAAmB,EAAC,MAAM,WAAA,CAAW,GAAE;AAAA,MAElG,eAAe,IAAI,CAAC,WACjB;AAAA,QAAC;AAAA,QAAA;AAAA,UAEG,SAAS,oBAAC,UAAA,EAAS,MAAK,SAAQ,SAAS,MAAM,SAAS,OAAO,KAAK,GAAG,UAAU,MAAM,aAAa,OAAO,KAAK,GAAG;AAAA,UACnH,OACI,qBAAC,OAAA,EAAM,WAAU,OAAM,SAAS,MAAM,IAAI,EAAC,YAAY,SAAA,GAClD,UAAA;AAAA,YAAA,eAAe,aAAa,OAAO,KAAK,wBAAK,YAAA,EAAW,SAAQ,SAAS,UAAA,OAAO,MAAA,CAAM;AAAA,YACvF,oBAAC,cAAW,SAAQ,WAAU,OAAM,kBAAkB,UAAA,aAAa,OAAO,KAAK,EAAA,CAAE;AAAA,UAAA,EAAA,CACrF;AAAA,QAAA;AAAA,QANC,OAAO;AAAA,MAAA,CASnB;AAAA,IAAA,EAAA,CACL;AAAA,EAAA,GACJ;AAER;"}