@stackcraftmx/calcita 0.32.1 → 0.47.0

package/README.md

@@ -49,6 +49,10 @@ pnpm exec calcita make:component OrderTotals --module purchase-orders
 El CLI nunca pisa un archivo que ya existe. Sus plantillas son los archivos tal cual (`cli/templates`), con
 `//#if pwa` … `//#endif` en lo que depende de una respuesta.
 
+El proyecto trae pruebas de pantalla (`pnpm test`, Vitest con jsdom y Testing Library): cada una abre la app completa en una
+dirección con el servidor de mentira (`openScreen` en `src/testing`) y pica como una persona. Vienen las del inicio, la de
+entrar y las del módulo de ejemplo, y `make:module` arma la de cada módulo nuevo.
+
 ## Arrancar en un proyecto que ya existe
 
 ```bash
@@ -170,10 +174,10 @@ Cada puerta pide solo sus librerías; un proyecto instala lo que usa.
 | Importar de | Trae | Pide además |
 |---|---|---|
 | `@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/table` | `ServerTable`: paginada, filtrada y ordenada en el servidor, con su estado en la URL; `ServerTableFilterDrawer`, su búsqueda en cajón | `@mui/x-data-grid`, `nuqs`, `react-window` |
 | `@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/date-pickers` | fecha, fecha con hora, hora y mes con los selectores de MUI X (`DateInput`, `DateTimeInput`, `TimeInput`, `MonthInput` y su versión de formik); cada uno viaja en texto | `@mui/x-date-pickers` 8, `dayjs` |
 | `@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 |
@@ -183,6 +187,8 @@ Cada puerta pide solo sus librerías; un proyecto instala lo que usa.
 | `@stackcraftmx/calcita/filepond` | `FileDropzone` con FilePond: el mismo uso que la de la puerta principal, más varios archivos, avance por archivo y `createPondServer` | `filepond`, `react-filepond`, `filepond-plugin-file-validate-type`, `filepond-plugin-file-validate-size` |
 | `@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/rich-text` | el editor de texto con formato (`RichTextEditor`, `FormRichTextField`) y la vista que enseña lo guardado sin dejar pasar código (`RichTextView`); viaja HTML | `@tiptap/react`, `@tiptap/pm`, `@tiptap/starter-kit`, `@tiptap/extensions`, `@tiptap/extension-text-align` (3) |
+| `@stackcraftmx/calcita/mexico` | RFC, CURP y CLABE con su dígito verificador y sus reglas de yup; la e.firma (`EfirmaFields`: el .cer leído y la llave abierta en el navegador) y la factura (`readCfdi`, `CfdiSummary`) | `jsrsasign` |
 | `@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` (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) | — |
@@ -245,6 +251,13 @@ el teléfono, con cápsulas, flotan arriba a la derecha y se quedan al bajar: la
 en un menú «⋯». Las `actions` de `PageHeading` ya suben solas, y `ServerTable` sube su búsqueda con
 `searchInBar`. «Hecho en Calcita» → «Marco y menú» lo enseña vivo.
 
+Cuando los filtros de una lista ya no caben arriba de la tabla, la búsqueda en cajón: `FilterDrawer` sale de un lado
+(`anchor`) con los campos declarados una vez (`FILTER_FIELD_KIND`: texto, una o varias opciones, catálogo, casillas, rango de
+números, de fechas, monto con operador o uno propio); lo que se cambia adentro no mueve la lista hasta «Buscar». Con
+`ServerTableFilterDrawer` en `toolbarExtra` va conectado a la tabla: botón «Filtros (N)», filtros en la dirección y un chip
+por filtro (`filterDrawerDefaultsOf`, `filterDrawerKindsOf`, `filterDrawerChipsOf`). Un monto viaja como `gte:500`
+(`comparisonOf` lo separa en el backend o en la pantalla).
+
 ```jsx
 <BarActions label="Buscar en pedidos" order={1}>
     <IconButton aria-label="Buscar" onClick={openSearch}><SearchRoundedIcon /></IconButton>
@@ -308,6 +321,7 @@ dejar Calcita con su propia cara, parte por parte.
 | `CalcitaActivityLog` | `itemIcon` |
 | `CalcitaAppearanceSettings` | `selectSection`, `section`, `sectionLabel`, `option`, `divider` |
 | `CalcitaAppLayout` | `skipLink`, `brand`, `brandLogo`, `brandText`, `brandName`, `brandCaption`, `titleArea`, `phoneTitle`, `desktopTitle`, `railBrand`, `railLogo`, `collapseButton`, `root`, `scrollEdge`, `bar`, `toolbar`, `menuButton`, `spacer`, `tools`, `progress`, `body`, `drawer`, `main`, `phoneSlot`, `content`, `phoneDrawer` |
+| `CalcitaAttachmentsInput` | `root`, `actions`, `button`, `list`, `fileChip`, `limits` |
 | `CalcitaAuditTrailDialog` | `description` |
 | `CalcitaAuthLayout` | `root`, `tools`, `body`, `brand`, `logo`, `brandName`, `card`, `description`, `content`, `footer` |
 | `CalcitaBarActions` | `group` |
@@ -315,14 +329,18 @@ dejar Calcita con su propia cara, parte por parte.
 | `CalcitaBarList` | `row`, `chart` |
 | `CalcitaBarSearch` | `field` |
 | `CalcitaCalendarHeatmap` | `header`, `toggle`, `tableArea`, `dateCell`, `valueCell`, `descriptionCell`, `gridArea`, `grid`, `monthLabel`, `week`, `dayLabel`, `cell`, `legend`, `legendLess`, `legendCell`, `legendMore` |
+| `CalcitaCfdiSummary` | `root`, `header`, `amounts`, `concepts` |
 | `CalcitaChart` | `tableArea`, `legend`, `legendItem`, `legendLine`, `legendSwatch`, `reference`, `referenceLine` |
 | `CalcitaChartTooltip` | `root` |
+| `CalcitaCheckboxGroupInput` | `root`, `selectAll`, `option` |
 | `CalcitaCollapsibleSection` | `root`, `accordion`, `summary`, `titleArea`, `collapsedTitle`, `expandedTitle`, `details` |
 | `CalcitaColorInput` | `swatch`, `nativeInput` |
 | `CalcitaColorSchemeToggle` | `button` |
 | `CalcitaColumnChart` | `chart` |
 | `CalcitaConfirmDialog` | `problem`, `actions` |
 | `CalcitaContentDialog` | `header`, `title`, `closeButton`, `body` |
+| `CalcitaCookieNotice` | `root`, `text`, `actions` |
+| `CalcitaCountdown` | `root` |
 | `CalcitaDateRangeFilter` | `chip`, `panel`, `actions` |
 | `CalcitaDefinitionList` | `root`, `entry`, `label`, `value` |
 | `CalcitaDemoTotpCode` | `root`, `code` |
@@ -330,11 +348,15 @@ dejar Calcita con su propia cara, parte por parte.
 | `CalcitaDownloadManager` | `doneIcon`, `failedIcon`, `canceledIcon`, `cancelButton`, `progress`, `cancelIcon`, `item`, `itemText`, `itemStatus`, `itemActions`, `panel`, `header`, `title`, `list` |
 | `CalcitaDownloadMenu` | `button` |
 | `CalcitaEmptyState` | `root`, `icon` |
+| `CalcitaEfirmaFields` | `root`, `certificate`, `verify` |
 | `CalcitaErrorPage` | `root`, `actions` |
 | `CalcitaEventCalendar` | `toolbar`, `navigation`, `title`, `calendar` |
 | `CalcitaEventDetails` | `row`, `rowContent`, `titleRow`, `toneDot`, `linkRow`, `link`, `guestsTitle`, `guest`, `guestAvatar`, `guestName`, `notes`, `actions` |
 | `CalcitaFileDropzone` | `root`, `fileArea`, `fileChip`, `hint`, `actions`, `limits`, `extra` |
+| `CalcitaFileInput` | `root`, `button`, `fileChip`, `empty` |
+| `CalcitaFileUploadInput` | `root`, `fileName`, `status`, `button`, `helper` |
 | `CalcitaFilterChips` | `root`, `header`, `clearButton` |
+| `CalcitaFilterDrawer` | `header`, `body`, `footer` (el panel: clase `CalcitaFilterDrawer-paper`) |
 | `CalcitaFontSizeToggle` | `button` |
 | `CalcitaFormProblemAlert` | `root` |
 | `CalcitaFormRow` | `root`, `label`, `control` |
@@ -345,6 +367,9 @@ dejar Calcita con su propia cara, parte por parte.
 | `CalcitaGroupedTimeline` | `group`, `groupHeader`, `groupButton`, `groupTitle`, `expandIcon`, `timeline`, `opposite`, `connector`, `content`, `entryTitle` |
 | `CalcitaHeaderFilter` | `button`, `badge`, `panel` |
 | `CalcitaHeaderTools` | `divider`, `root` |
+| `CalcitaHelpCarouselDialog` | `media`, `content`, `dots`, `actions` |
+| `CalcitaIconBadge` | `root`, `icon`, `label` |
+| `CalcitaImageInput` | `root`, `preview`, `image`, `placeholder`, `actions` |
 | `CalcitaInboxLayout` | `labelDot`, `folder`, `folderIcon`, `folderCount`, `root`, `folders`, `foldersHeader`, `labelsTitle`, `listPane`, `phoneTabs`, `phoneTabBadge`, `listHeader`, `list`, `detail`, `backButton` |
 | `CalcitaInstallAppSetting` | `root` |
 | `CalcitaInstallInstructions` | `steps` |
@@ -370,8 +395,14 @@ dejar Calcita con su propia cara, parte por parte.
 | `CalcitaProfileHeader` | `root`, `cover`, `body`, `avatar`, `text`, `name`, `chips`, `actions` |
 | `CalcitaProfileScreen` | `sectionTitle`, `form`, `preferences` |
 | `CalcitaQuickFilters` | `root`, `caption`, `chip`, `chipLabel`, `chipCount` |
+| `CalcitaPdfViewerDialog` | `actions`, `frame` |
+| `CalcitaRecordCard` | `root`, `header`, `avatar`, `titles`, `status`, `body`, `group`, `fact`, `highlight`, `footer`, `details` |
 | `CalcitaRecoveryCodesDialog` | `codes`, `actions` |
+| `CalcitaRouteTabs` | `root`, `tab`, `badge` |
 | `CalcitaScrollableRow` | `root` |
+| `CalcitaRepeatingFields` | `root`, `row`, `rowHeader`, `rowContent`, `addButton`, `helper` |
+| `CalcitaRichTextEditor` | `root`, `toolbar`, `content`, `footer` |
+| `CalcitaRichTextView` | `root` |
 | `CalcitaSecondStepForm` | `actions` |
 | `CalcitaSectionCard` | `root`, `header`, `title` |
 | `CalcitaSegmentedControl` | `root` |
@@ -390,8 +421,11 @@ dejar Calcita con su propia cara, parte por parte.
 | `CalcitaTabBarEditor` | `root`, `header`, `title`, `list`, `itemIcon`, `footer` |
 | `CalcitaTableToggle` | `root`, `button` |
 | `CalcitaTag` | `root` |
+| `CalcitaTemplateDownloadButton` | `root` |
+| `CalcitaTermsAcceptanceDialog` | `content`, `frame`, `footer` |
 | `CalcitaTextInput` | `field` |
 | `CalcitaTopMenu` | `link`, `root` |
+| `CalcitaTransferListInput` | `root`, `list`, `actions` |
 | `CalcitaTwoStepVerification` | `qr`, `secret`, `secretCode`, `header`, `headerTitle`, `headerText`, `menuIcon` |
 | `CalcitaWizardLayout` | `stepper`, `phoneSteps`, `actions` |
 | `CalcitaWordmark` | `root` |
@@ -488,6 +522,25 @@ 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.
+Para explicar una pantalla la primera vez que se entra, la ayuda en carrusel: `HelpCarouselDialog` (pasos con imagen o
+ilustración, título y texto; Siguiente, los puntos, las flechas o deslizando) y `useHelpCarousel({helpKey, version})`, que
+la abre sola la primera vez y por versión, hasta que se termina o se marca «No volver a mostrar» (`seen` para lo que ya sabe
+el servidor del proyecto); `HelpButton` es el «?» que la vuelve a abrir.
+
+Para listas donde una tabla se queda corta, `RecordCard`: arriba quién es (avatar con iniciales, folio, nombre) con su
+estatus, insignias, botón para abrirlo y menú «⋯»; en el cuerpo sus datos en grupos (`groups`, o `content` libre) y el dato
+principal grande; abajo lo que va a todo lo ancho y «Ver detalle», que despliega más. El orden es el que se da y nada se
+reacomoda solo: para un orden obligatorio, `trailing` pone el estatus al final y `columns` fija el ancho de cada columna.
+`RecordCardSkeleton` es su esqueleto. El menú «⋯» (`ActionsMenu`) acepta secciones, separadores, ligas, renglones propios y
+submenús (`children`), que se abren dentro del mismo menú con «Regresar».
+
+Para las secciones de un registro, `RouteTabs`: pestañas donde cada una es una dirección (se comparte la liga a una pestaña y
+«atrás» regresa a la anterior); por ruta (cada pestaña su página) o en la consulta (`mode="query"`, `?tab=pagos`, con
+`useActiveRouteTab` para pintar el panel), con ícono, conteo y permiso por pestaña. Junto al título de un registro van su
+estatus (`StatusChip`) y sus insignias (`IconBadge`): un ícono y un texto corto con el
+color de lo que significan («Envío asegurado», «Pago con tarjeta»), con borde, tenue o sin caja. Mejor desde un diccionario:
+la entrada trae su ícono (`dictionaryEntryOf(value, keyPrefix, color, {icon})`) y la insignia saca de ahí texto,
+explicación, color e ícono (`<IconBadge dictionary={PAYMENT_METHOD} value={order.payment_method} />`).
 
 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
@@ -819,6 +872,108 @@ import {FormRow, FormSection} from '@stackcraftmx/calcita';
 Los campos van directo dentro de la `FormSection` (sin Grid ni Stack en medio): la línea entre renglones se dibuja entre
 hermanos.
 
+### Campos con máscara
+
+`MaskedInput` (y `FormMaskedField` en `/forms` y `/react-hook-form`) es el campo de texto de la casa con una máscara: mientras
+se escribe se ven los separadores («555 123 4567») y al formulario llega el valor limpio («5551234567»). Pegar un número con
+otros separadores también sirve. Las de siempre vienen con nombre en `INPUT_MASK` (`phone`, `postalCode`, `clabe`, `card`,
+`rfc`, `curp`, `uuid`); una propia es un patrón donde `9` es un dígito, `A` una letra, `X` letra o dígito y `H` hexadecimal
+(`mask="AAA-9999"`). El RFC y la CURP solo se filtran y se pasan a mayúsculas mientras se escriben.
+
+```jsx
+<FormMaskedField name="phone" mask={INPUT_MASK.phone} label="Teléfono" placeholder="555 123 4567" />
+<FormMaskedField name="clabe" mask="clabe" label="CLABE" />
+```
+
+### Fechas y horas
+
+Cuatro campos en `/date-pickers`, con los selectores de MUI X. Cada uno viaja en texto con una sola forma y se ve en el
+idioma de la persona; la pantalla no convierte nada:
+
+| Campo (suelto · formik) | Para qué | Viaja |
+|---|---|---|
+| `DateInput` · `FormDateField` | una fecha de calendario (un nacimiento, una entrega) | `'2026-11-01'` |
+| `DateTimeInput` · `FormDateTimeField` | un momento que pasa una vez (un envío programado, una cita) | `'2026-11-01T18:30:00Z'`, en UTC |
+| `TimeInput` · `FormTimeField` | una hora del día sin fecha (un horario) | `'09:30'`, de 24 horas |
+| `MonthInput` · `FormMonthField` | el mes de un reporte o de un cierre | `'2026-11'` |
+
+La fecha con hora se ve en la zona del proyecto (`ToolkitProvider timeZone`) con el nombre de la zona abajo («Hora estándar
+central»), para que nadie dude en qué hora está escribiendo; `timeZone` la cambia en un solo campo (la hora de una
+sucursal) y el momento que viaja es el mismo. La hora sale de 24 horas o con a. m. y p. m. según `ToolkitProvider
+hourCycle`, y viaja igual. Lo que el selector de MUI X acepta y aquí no tiene nombre va en `pickerProps`.
+
+```jsx
+import {FormDateTimeField, FormMonthField, FormTimeField} from '@stackcraftmx/calcita/date-pickers';
+
+<FormDateTimeField name="visitAt" label="Fecha y hora" disablePast />
+<FormTimeField name="opensAt" label="Abre a las" minTime="07:00" maxTime="21:00" />
+<FormMonthField name="billingMonth" label="Se cobra en" disableFuture />
+```
+
+Con react-hook-form, el campo suelto va dentro de un `Controller` (la puerta de fechas no pide react-hook-form).
+
+Los minutos van de uno en uno (MUI X trae de 5 en 5); `minutesStep` los cambia. Para algo que se publica con
+anticipación y dura un mínimo (una promoción, una venta especial), el inicio lleva `minimumMinutesFromNow` (el mínimo se recorre
+solo con el reloj mientras la pantalla está abierta) y el fin `minDateTime={instantPlusMinutes(startsAt, 30)}`; en yup,
+las mismas reglas con su mensaje. El servidor vuelve a revisar: entre llenar el formulario y guardarlo pasa el tiempo.
+
+```jsx
+import {FormDateTimeField, instantPlusMinutes, minutesAfterRule, minutesFromNowRule} from '@stackcraftmx/calcita/date-pickers';
+
+const schema = Yup.object({
+    startsAt: Yup.string().required().test(minutesFromNowRule(5)),
+    endsAt: Yup.string().required().test(minutesAfterRule('startsAt', 30)),
+});
+
+<FormDateTimeField name="startsAt" label="Empieza" minimumMinutesFromNow={5} />
+<FormDateTimeField name="endsAt" label="Termina" minDateTime={instantPlusMinutes(values.startsAt, 30)} />
+```
+
+### Renglones que se repiten
+
+`FormRepeatingFields` (de formik y de react-hook-form, con el mismo uso) pinta una lista del formulario: cada renglón con
+su número y «Quitar», y «Agregar» al final. `minRows` (por omisión 1: con el mínimo, «Quitar» limpia el renglón) y
+`maxRows`; si un renglón se puede quitar lo decide la pantalla (`removeBlockedReason` da el motivo, `confirmRemove` pide
+confirmar uno guardado). En escritorio los campos de un renglón van lado a lado (`columns`) y en el teléfono uno debajo de
+otro. Las reglas de listas marcan el error en SU renglón:
+
+```jsx
+import {FormNumberField, FormRepeatingFields, Yup, listTotalAtMostRule, orderedInListRule, uniqueInListRule} from '@stackcraftmx/calcita/forms';
+
+const schema = Yup.object({
+    prices: Yup.array().of(Yup.object({
+        min_quantity: Yup.string().required()
+            .test(uniqueInListRule('prices', 'min_quantity'))      // «Ya está en el renglón 2»
+            .test(orderedInListRule('prices', 'min_quantity')),    // «Debe ir entre 10 (renglón 1) y 50 (renglón 3)»
+    })),
+    split: Yup.array().test(listTotalAtMostRule('amount', (values) => values.credit_limit)),  // con Money, sin floats
+});
+
+<FormRepeatingFields name="prices" label="Precios por volumen" emptyRow={{min_quantity: '', unit_price: ''}} maxRows={6}
+                     renderRow={({nameOf}) => (<>
+                         <FormNumberField name={nameOf('min_quantity')} label="Desde (piezas)" decimals={0} />
+                         <FormNumberField name={nameOf('unit_price')} label="Precio" prefix="$" />
+                     </>)} />
+```
+
+### Elegir varios
+
+Tres formas, según cuántas opciones hay, y cada una con su versión de formik y de react-hook-form:
+
+| Pieza | Para qué | Opciones de varias |
+|---|---|---|
+| `CheckboxGroupInput` · `FormCheckboxGroupField` | pocas opciones a la vista (los canales de aviso) | `selectAll`, `row`, `options[].description` |
+| `SelectInput` · `FormSelectField` con `multiple` | una lista corta (los días) | `selectAll`, `checkboxes` |
+| `CatalogInput` · `FormCatalogField` con `multiple` | un catálogo largo con buscador (los estados) | `selectAll` (con algo buscado, «Elegir los N que coinciden»), `checkboxes`, `limitTags` |
+| `TransferListInput` · `FormTransferListField` | elegir muchos viendo qué quedó de cada lado (compradores, sucursales) | `availableTitle`, `chosenTitle`, `searchable`, `listHeight` |
+
+«Elegir todos» lleva su casilla a medias cuando hay algunos elegidos y no cuenta las opciones apagadas (`disabled`). La
+lista de transferencia va fuera de una FormSection: necesita el ancho completo.
+
+Un 422 del servidor en `contacts.2.email` llega a ese renglón (`applyServerProblem`). Con formik, el error de toda la lista
+(el tope) sale cuando los renglones ya no tienen errores: formik guarda los dos en el mismo lugar; para verlo mientras se
+escribe va un resumen en vivo en `footer` con `listTotalOf`.
+
 ## Subir archivos
 
 Dos zonas para soltar archivos con el mismo uso: la de la puerta principal, con puro MUI (un archivo), y la de
@@ -835,6 +990,112 @@ import {FileDropzone, buildUploadActors, uploadMachine, uploadWithProgress} from
 `accept` acepta nombres (`'excel'`, `['pdf', 'image']`) o lo de siempre del input (`'.xlsx,.xls'`); `maxSize` va en bytes
 o con unidades (`'10 MB'`, en base 1000 como el navegador).
 
+Para otros acomodos, con las mismas reglas y los mismos avisos:
+
+| Pieza (suelta · formik y react-hook-form) | Para qué | Al formulario llega |
+|---|---|---|
+| `FileInput` · `FormFileField` | un archivo del tamaño de un campo (la constancia, el contrato) | el `File`, lo ya guardado (`{name, size}`) o `null` |
+| `AttachmentsInput` · `FormAttachmentsField` | varios, como en un correo: «Adjuntar» y un chip por archivo | la lista (nuevos y guardados) |
+| `ImageInput` · `FormImageField` | una foto con su vista previa, en círculo o recuadro | el `File`, la dirección de la guardada o `null` |
+| `TemplateDownloadButton` | «Descargar la plantilla» (un archivo fijo con `href` o su API con `request`) | — |
+
+Los cuatro cargadores aceptan `template` para poner «Descargar la plantilla» junto a su botón, y `AttachmentsInput` suma
+`maxFiles` y `maxTotalSize`. Para armar uno propio (una tarjeta, un botón en la barra) está `useFilePicker`, que da el
+input, abrir la ventana, soltar encima y la revisión con sus avisos.
+
+```jsx
+import {AttachmentsInput, FileInput} from '@stackcraftmx/calcita';
+
+<FileInput label="Constancia fiscal" value={file} onChange={setFile} accept="pdf" maxSize="2 MB"
+           template={{href: '/plantillas/constancia.pdf'}} />
+<AttachmentsInput value={files} onChange={setFiles} accept={['pdf', 'image']} maxFiles={5} maxTotalSize="10 MB" />
+```
+
+### El cargador mini: sube en cuanto se elige
+
+Los de arriba solo eligen y el archivo viaja con el formulario. `FileUploadInput` (y `FormFileUploadField` de formik y de
+react-hook-form) SUBE el archivo en cuanto se elige, en su renglón: para una lista de documentos (lo que pide una solicitud,
+el expediente de un cliente). Enseña su estado (Por cargar, Subiendo 40 %, Procesando, Cargado, No se cargó), «Cargar» que ya
+cargado dice «Sustituir», bajar el subido y quitarlo, y abajo el avance en palabras o el motivo del error. Al formulario
+llega solo el id que da el servidor (`''` mientras sube): `Yup.string().required()` pide el documento.
+
+```jsx
+import {FormFileUploadField} from '@stackcraftmx/calcita/forms';
+
+<FormFileUploadField name="identification_file_id" label="Identificación oficial" accept={['pdf', 'image']} maxSize="5 MB"
+                     upload={(file, {signal, onUploadProgress, idempotencyKey}) => documentsApi.upload(file, {signal, onUploadProgress, idempotencyKey})}
+                     download={(fileId, transferOptions) => documentsApi.download(fileId, transferOptions)} />
+```
+
+`upload` es la subida del proyecto (`uploadWithProgress`, axios o su cliente) y `idOf` dice qué guardar de la respuesta (por
+omisión `result.id`). Lo del negocio (Aprobado, Falta información) va junto al estado con `actions`, y `onStatusChange`
+dice en qué va cada renglón para contar «2 de 3 cargados».
+
+## Documentos, avisos legales y cuenta regresiva
+
+- `PdfViewerDialog`: un PDF en una ventana con el visor del navegador (sin librerías), con «Abrir en otra pestaña» y
+  «Descargar» siempre a la vista (en el iPhone el visor dentro de la página enseña solo la primera hoja). `src` es la
+  dirección o el archivo (un Blob de su API).
+- `CookieNotice`: el aviso de cookies abajo, hasta que se acepta ESA versión en el navegador; no bloquea la pantalla.
+  `useCookieConsent` para pintar uno propio.
+- `TermsAcceptanceDialog`: aceptar los términos antes de seguir; pide leerlos hasta el final, marcar la casilla y «Acepto»,
+  y no se cierra con Escape. Quién aceptó qué versión lo registra su API en `onAccept` (la ventana espera y, si falla, dice
+  el motivo).
+- `Countdown`: «02:14:30» hasta un momento, con días cuando faltan, lo que dice al llegar a cero y `onComplete`;
+  `useCountdown` da las partes para pintarla a su manera.
+
+```jsx
+<CookieNotice version="2026-11" policyHref="/legal/cookies" />
+<TermsAcceptanceDialog open={!session.terms.accepted} version={session.terms.current} onAccept={({version}) => api.acceptTerms(version)}
+                       onDecline={signOut}>
+    <TermsText />
+</TermsAcceptanceDialog>
+<Countdown until={registration.closes_at} onComplete={reloadRegistration} completedText="Cerradas" />
+```
+
+## Texto con formato
+
+`@stackcraftmx/calcita/rich-text` trae el editor con Tiptap: estilo (texto, título, subtítulo), negrita, cursiva,
+subrayado, tachado, listas, cita, código, ligas, alineación, quitar el formato y deshacer, con contador si hay `maxLength`.
+Viaja HTML; vacío es `''` (así `required()` funciona). Las ligas solo con https, http, mailto o tel (un dominio suelto se
+completa con https://). `RichTextView` enseña lo guardado pasándolo por el mismo esquema del editor: un `<script>`, un
+`onclick` o una liga `javascript:` no llegan a la página.
+
+```jsx
+import {FormRichTextField, RICH_TEXT_FEATURE, RichTextView} from '@stackcraftmx/calcita/rich-text';
+
+<FormRichTextField name="notes" label="Notas" maxLength={2000}
+                   features={[RICH_TEXT_FEATURE.bold, RICH_TEXT_FEATURE.bulletList, RICH_TEXT_FEATURE.link]} />
+<RichTextView value={order.notes} />
+```
+
+Para lo que la barra no trae: `toolbarActions` (botones propios), `onEditorReady` (el editor de Tiptap) y `extensions`
+(extensiones de Tiptap del proyecto). Pesa unos 420 kB (134 kB comprimido) y solo se baja en las pantallas que lo usan.
+
+## México: RFC, CURP, CLABE, e.firma y facturas
+
+`@stackcraftmx/calcita/mexico` trae lo que casi cualquier sistema en México pide (pide `jsrsasign` solo para abrir la llave):
+
+- `isValidRfc`, `isValidCurp`, `isValidClabe`: la forma, que la fecha exista y el dígito verificador (el del RFC, con
+  `{strict: true}`). En yup, como reglas con su mensaje: `Yup.string().test(clabeRule())`.
+- `readCfdi(xmlText)` / `readCfdiFile(file)`: la factura (CFDI 3.3 y 4.0) leída del XML, con los montos en texto para
+  `Money`; `null` si no es factura. `CfdiSummary` la enseña, con el aviso si no es para su RFC o si no está timbrada.
+- `EfirmaFields`: el .cer, el .key y la contraseña. El certificado se lee en el navegador (`readCertificate`: RFC, CURP, nombre,
+  número de certificado, vigencia) y avisa si venció o es de otro RFC. «Revisar la e.firma» abre la llave con su contraseña y
+  comprueba que es la del certificado, también en el navegador (`verifyEfirmaKey`, con jsrsasign, que se baja hasta que se
+  usa: la llave del SAT va cifrada con 3DES y el navegador no lo trae), y dice el motivo de un «no». Con `onVerifyKey` la
+  revisión la hace su API. Calcita no manda la llave a ningún lado.
+
+```jsx
+import {CfdiSummary, EfirmaFields, clabeRule, readCfdiFile} from '@stackcraftmx/calcita/mexico';
+
+const cfdi = await readCfdiFile(file);  // null si no es factura
+<CfdiSummary cfdi={cfdi} expectedReceiverRfc={company.rfc} />
+<EfirmaFields value={efirma} onChange={setEfirma} expectedRfc={company.rfc} />   {/* revisa la llave en el navegador */}
+```
+
+Revisan la forma y leen los archivos; si el RFC existe, si la factura sigue vigente y si la llave abre lo dice su servidor.
+
 ## Dinero sin problemas de decimales
 
 En JavaScript `0.1 + 0.2` da `0.30000000000000004`. `Money` guarda los montos en centavos enteros (como el Money de PHP

package/cli/packageVersions.js

@@ -5,9 +5,18 @@
 import {readFile} from 'node:fs/promises';
 
 // Lo que el paquete no usa, así que no está en sus devDependencies: i18next (su adaptador recibe la instancia del proyecto;
-// versión con más de dos semanas publicada al escogerla, pnpm espera un día antes de instalar una recién salida) y qrcode
-// (el QR de la cuenta de demostración; la misma versión que usan los ejemplos)
-const VERSIONS_NOT_IN_PACKAGE = Object.freeze({i18next: '26.4.2', qrcode: '1.5.4'});
+// versión con más de dos semanas publicada al escogerla, pnpm espera un día antes de instalar una recién salida), qrcode
+// (el QR de la cuenta de demostración; la misma versión que usan los ejemplos) y las pruebas de pantalla del proyecto
+// (Vitest con jsdom y Testing Library), en las versiones que ya se probaron juntas con el mismo Vite 7 y React 19
+const VERSIONS_NOT_IN_PACKAGE = Object.freeze({
+    i18next: '26.4.2',
+    qrcode: '1.5.4',
+    vitest: '5.0.3',
+    jsdom: '30.1.2',
+    '@testing-library/dom': '10.4.2',
+    '@testing-library/react': '16.3.3',
+    '@testing-library/user-event': '14.6.7',
+});
 
 /**
  * El package.json de Calcita (el del CLI que corre). OJO: por ruta de archivo y no con import: el CLI se publica tal cual,

package/cli/projectFiles.js

@@ -15,7 +15,10 @@ const BASE_DEPENDENCIES = Object.freeze([
 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
 const ACCOUNT_DEPENDENCIES = Object.freeze(['@simplewebauthn/browser', 'qrcode']);
-const DEV_DEPENDENCIES = Object.freeze(['@vitejs/plugin-react', 'vite']);
+// las pruebas de pantalla (pnpm test): Vitest con jsdom como navegador y Testing Library para picar como una persona
+const DEV_DEPENDENCIES = Object.freeze([
+    '@testing-library/dom', '@testing-library/react', '@testing-library/user-event', '@vitejs/plugin-react', 'jsdom', 'vite', 'vitest',
+]);
 
 /** Un objeto con sus llaves en orden alfabético (como los escribe npm). */
 const sortedByKey = (record) => Object.fromEntries(Object.entries(record).sort(([first], [second]) => first.localeCompare(second)));
@@ -40,7 +43,7 @@ export function packageJsonOf({packageName, answers, calcitaPackage}) {
         version: '0.1.0',
         private: true,
         type: 'module',
-        scripts: {dev: 'vite', build: 'vite build', preview: 'vite preview'},
+        scripts: {dev: 'vite', build: 'vite build', preview: 'vite preview', test: 'vitest run'},
         dependencies: sortedByKey({'@stackcraftmx/calcita': `^${calcitaPackage.version}`, ...versionsOf(dependencyNames, calcitaPackage)}),
         devDependencies: sortedByKey(versionsOf([...DEV_DEPENDENCIES], calcitaPackage)),
         engines: {node: '>=22'},

package/cli/templates/module/__Name__Page.test.jsx.tpl

@@ -0,0 +1,24 @@
+// La prueba de pantalla de __LABEL_ES__ (la armó el CLI de Calcita con make:module): la app completa abre en su ruta, con su
+// servidor de mentira, enseña lo que manda el servidor y agrega uno. Cámbiela junto con la pantalla.
+//
+//     pnpm test
+import {screen} from '@testing-library/react';
+import {describe, expect, it} from 'vitest';
+
+import {__NAME___PATH} from '@/modules/__name__/routes.js';
+import {openScreen} from '@/testing/openScreen.jsx';
+
+describe('__LABEL_ES__', () => {
+    it('enseña lo que manda el servidor', async () => {
+        await openScreen(__NAME___PATH);
+        expect(await screen.findByRole('heading', {name: '__LABEL_ES__'})).toBeTruthy();
+        expect(await screen.findByText('Primer ejemplo')).toBeTruthy();
+    });
+
+    it('agrega uno y sale en la lista', async () => {
+        const {user} = await openScreen(__NAME___PATH);
+        await user.type(await screen.findByRole('textbox', {name: 'Nombre'}), 'Uno nuevo');
+        await user.click(screen.getByRole('button', {name: 'Guardar'}));
+        expect(await screen.findByText('Uno nuevo')).toBeTruthy();
+    });
+});

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

@@ -31,7 +31,8 @@ src/
   app/                el único lugar donde se conecta el framework: proveedores, marco, rutas, tema y textos
   core/               lo que comparten dos o más módulos (se importa de '@/core')
   fakeServer/         el servidor de mentira: datos en memoria con la forma del API de verdad
-  modules/<módulo>/   cada módulo en su carpeta: menu.js, routes.js, sus pantallas, su *Api.js y sus *Texts.js
+  modules/<módulo>/   cada módulo en su carpeta: menu.js, routes.js, sus pantallas, su *Api.js, sus *Texts.js y sus pruebas
+  testing/            el kit de las pruebas de pantalla: abrir la app en una dirección (openScreen) y los huecos de jsdom
 ```
 
 - **Un módulo nuevo no edita nada fuera de su carpeta**: el menú, las rutas y los textos se descubren solos.
@@ -42,6 +43,18 @@ src/
   validaciones) ya vienen.
 - **Imports con el alias `@/`** (= `src/`), declarado en `vite.config.js` y en `jsconfig.json`.
 
+## Pruebas de pantalla
+
+```bash
+pnpm test
+```
+
+Cada `*.test.jsx` abre la app COMPLETA en una dirección (`openScreen`, en `src/testing`), con el servidor de mentira, y pica
+como una persona: busca lo que se ve por su papel y su nombre (`screen.findByRole('heading', {name: 'Bienvenida'})`) y da
+clic o escribe con `user`. Pasa por lo mismo que la persona (permisos, menú, textos, avisos). Vienen las del inicio y las del
+módulo de ejemplo, y `make:module` arma la de cada módulo nuevo. Corren con Vitest y jsdom (un navegador de mentira): lo que
+depende de medir o pintar se revisa en un navegador de verdad.
+
 ## 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

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

@@ -28,7 +28,8 @@ const moduleRouteGroups = Object.entries(ROUTE_MODULES)
 // las pantallas sin el marco (entrar…)
 const publicRoutes = Object.values(ROUTE_MODULES).flatMap((routeModule) => routeModule.publicRoutes ?? []);
 
-export const appRouter = createBrowserRouter([
+/** Las rutas de la app: el router del navegador (abajo) y el de memoria de las pruebas de pantalla (src/testing). */
+export const appRoutes = [
     {
         path: APP_PATHS.home,
         element: <AppProviders />,
@@ -46,6 +47,8 @@ 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});
+export const appRouter = createBrowserRouter(appRoutes, {basename: ROUTER_BASENAME});

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

@@ -20,6 +20,9 @@ export const DEMO_USER = Object.freeze({
     id: 'user-demo', name: 'Ana Martínez Ruiz', email: 'ana.martinez@ejemplo.com', subtitle: 'Administración', phone: '',
 });
 
+/** Dónde recuerda la demostración la sesión en este navegador (con el nombre de la app, para no chocar con otra). */
+export const DEMO_SESSION_STORAGE_KEY = '__APP_SLUG__:session';
+
 /** Sin dirección del API, la app trabaja con la demostración. */
 export const USES_DEMO_ACCOUNT = !import.meta.env.VITE_API_URL;
 
@@ -27,8 +30,7 @@ export const accountConnector = USES_DEMO_ACCOUNT
     ? createDemoAccountConnector({
         user: DEMO_USER,
         labels: ['Administración'],
-        // la sesión de la demostración se recuerda en este navegador, con el nombre de la app para no chocar con otra
-        storageKey: '__APP_SLUG__:session',
+        storageKey: DEMO_SESSION_STORAGE_KEY,
         issuer: '__APP_TITLE__',
         // el QR que escanea la app autenticadora
         toQrImageUrl: (otpauthUrl) => QRCode.toDataURL(otpauthUrl, {margin: 1}),

package/cli/templates/project/src/modules/auth/SignInPage.test.jsx.tpl

@@ -0,0 +1,20 @@
+// La prueba de pantalla de entrar: sin sesión, la app manda a «Iniciar sesión» y regresa a donde iba al entrar. Entra con
+// el botón de la cuenta de ejemplo (la demostración): la prueba nunca escribe una contraseña.
+//
+//     pnpm test
+import {screen} from '@testing-library/react';
+import {describe, expect, it} from 'vitest';
+
+import {openScreen} from '@/testing/openScreen.jsx';
+
+describe('entrar', () => {
+    it('sin sesión pide entrar y después abre la pantalla que se pidió', async () => {
+        const {user, router} = await openScreen('/', {signedIn: false});
+        expect(await screen.findByRole('heading', {name: 'Iniciar sesión'})).toBeTruthy();
+
+        await user.click(screen.getByRole('button', {name: 'Entrar con la cuenta de ejemplo'}));
+
+        expect(await screen.findByRole('heading', {name: 'Bienvenida'})).toBeTruthy();
+        expect(router.state.location.pathname).toBe('/');
+    });
+});

package/cli/templates/project/src/modules/home/HomePage.test.jsx.tpl

@@ -0,0 +1,16 @@
+// La prueba de pantalla del inicio: la app completa abre en «/» y enseña la bienvenida con sus primeros pasos. Es el ejemplo
+// para las demás: abrir la pantalla, buscar lo que ve la persona por su papel y su nombre, y picar como ella.
+//
+//     pnpm test
+import {screen} from '@testing-library/react';
+import {describe, expect, it} from 'vitest';
+
+import {openScreen} from '@/testing/openScreen.jsx';
+
+describe('el inicio', () => {
+    it('enseña la bienvenida y cómo seguir con el CLI', async () => {
+        await openScreen('/');
+        expect(await screen.findByRole('heading', {name: 'Bienvenida'})).toBeTruthy();
+        expect(screen.getByText('pnpm exec calcita make:module orders')).toBeTruthy();
+    });
+});

package/cli/templates/project/src/testing/browserGaps.js.tpl

@@ -0,0 +1,70 @@
+// Lo que jsdom (el navegador de mentira de las pruebas) no trae y la app sí usa.
+//
+// Cada hueco se llena con lo mínimo para que la pantalla se dibuje. Ninguna prueba depende de que esto haga algo de
+// verdad: jsdom no mide ni pinta, así que tamaños, scroll y medidas de pantalla no se prueban aquí (eso es de un navegador
+// de verdad, con Playwright).
+//
+// Funciones puras, no renderizan: function (regla de la casa).
+
+/**
+ * Los archivos que la pantalla mandó guardar (una descarga), en orden: {fileName, href}. jsdom no sabe descargar; aquí se
+ * anota el nombre para que la prueba revise qué se habría guardado.
+ */
+export const savedFiles = [];
+
+/** Observador de tamaño o de vista que nunca avisa: en jsdom todo mide 0 y no cambia. */
+class SilentObserver {
+    observe() {}
+
+    unobserve() {}
+
+    disconnect() {}
+
+    takeRecords() {
+        return [];
+    }
+}
+
+/**
+ * Consulta de medios que nunca coincide: la pantalla se dibuja como en escritorio y en modo claro.
+ *
+ * @param {string} media la consulta, p. ej. '(prefers-color-scheme: dark)'
+ * @returns {MediaQueryList}
+ */
+function neverMatchingMediaQuery(media) {
+    return {
+        matches: false,
+        media,
+        onchange: null,
+        addEventListener() {},
+        removeEventListener() {},
+        addListener() {},
+        removeListener() {},
+        dispatchEvent() {
+            return false;
+        },
+    };
+}
+
+/** Llena los huecos de jsdom. */
+export function fillBrowserGaps() {
+    window.ResizeObserver ??= SilentObserver;
+    window.IntersectionObserver ??= SilentObserver;
+    window.matchMedia ??= neverMatchingMediaQuery;
+    // ir arriba al cambiar de pantalla y llevar a la vista lo elegido
+    window.scrollTo = () => {};
+    window.HTMLElement.prototype.scrollTo ??= function scrollTo() {};
+    window.HTMLElement.prototype.scrollIntoView ??= function scrollIntoView() {};
+    // descargas y vistas previas de archivos: una dirección de mentira
+    window.URL.createObjectURL ??= () => 'blob:prueba';
+    window.URL.revokeObjectURL ??= () => {};
+    // la liga de descarga se anota en savedFiles en lugar de navegar (jsdom no navega y lo diría con un error)
+    const followLink = window.HTMLAnchorElement.prototype.click;
+    window.HTMLAnchorElement.prototype.click = function click() {
+        if (this.hasAttribute('download')) {
+            savedFiles.push({fileName: this.getAttribute('download'), href: this.href});
+            return;
+        }
+        followLink.call(this);
+    };
+}