@stackcraftmx/calcita 0.47.0 → 0.51.0

package/README.md

@@ -53,6 +53,11 @@ El proyecto trae pruebas de pantalla (`pnpm test`, Vitest con jsdom y Testing Li
 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.
 
+Y dos revisiones para antes de subir: `pnpm lint` (ESLint: una variable que no existe, «t is not defined», se caza al
+escribir) y `pnpm check:texts` (`calcita check:texts`: que cada `t('llave')` escrita tal cual exista en todos los idiomas y
+que los idiomas tengan las mismas llaves). Sirve también en un proyecto que no salió del CLI: lee `src/**/*Texts.js` y
+`src/**/texts.js`.
+
 ## Arrancar en un proyecto que ya existe
 
 ```bash
@@ -97,12 +102,42 @@ Sin nada más, todo sale en español, con la zona horaria del navegador, montos
 | `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 |
+| `onMissingText` | a quién avisarle de un texto que no existe (la pantalla enseña la llave): mandarlo a Sentry, tronar una prueba | un aviso en la consola, una vez por idioma y llave |
+| `readValidationMessage` | cómo leer los mensajes de validación de un sistema que ya existe (ver «Mensajes de error propios») | `{key}`, `{msg}`, `{message}` y texto |
 
 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.
 
+**Fuera de un componente** (una función que arma columnas, un diccionario, un aviso): `translateToolkit(namespace, llave,
+valores)` y los formatos sueltos (`formatDate`, `formatCurrency`, `formatNumber`…) usan el idioma, la zona y la moneda del
+proveedor de la raíz, ya actualizados en la misma pintada en que cambian. Así una función auxiliar no tiene que recibir `t`
+ni los formatos por parámetro:
+
+```js
+import {formatDate, translateToolkit} from '@stackcraftmx/calcita';
+
+export const columnsOf = () => [
+    textColumn({field: 'registered_at', label: translateToolkit('clients', 'columns.registered'), valueFormatter: (value) => formatDate(value)}),
+];
+```
+
+Dos cuidados: con dos proveedores (dos islas en otro idioma) los sueltos usan el de la raíz; y si la pantalla guarda el
+resultado (`useMemo(() => columnsOf(), [])`), ponga el idioma en las dependencias o se queda en el de antes.
+
+Un texto que no existe se pinta con su llave (`clients:columns.registered`) y Calcita lo avisa en la consola una vez; con
+`onMissingText` se le avisa al proyecto. Un texto opcional se pide con `defaultValue` (`t('tips.extra', {defaultValue: ''})`)
+y no avisa.
+
+Para un texto con una palabra resaltada, una sola llave con marcas y `MarkedText` (como `<Trans>` de react-i18next, sin
+i18next). No pinta HTML: solo las marcas que se nombran; lo demás sale como texto.
+
+```jsx
+// es: {home: {headline: 'Optimiza tu negocio con <highlight>financiamiento</highlight> inteligente'}}
+<MarkedText text={t('home.headline')} marks={{highlight: <Box component="strong" sx={{color: 'primary.main'}} />}} />
+```
+
 Con react-router y i18next:
 
 ```jsx
@@ -310,6 +345,23 @@ tema del proyecto y al final el `sx` que pase la pantalla. Los números se leen
 Sirve con `createToolkitTheme` y con cualquier tema de MUI (el que ya tenía un sistema, tal cual): así un sistema puede
 dejar Calcita con su propia cara, parte por parte.
 
+Además, como en MUI, cada parte con nombre se puede **cambiar por otro componente** (`slots`) o **recibir props de más**
+(`slotProps`), con el nombre de la parte de la tabla de abajo; desde la pantalla o para toda la app desde el tema:
+
+```jsx
+<RecordCard slots={{avatar: StoreAvatar}} slotProps={{titles: {component: 'header'}}} … />
+createTheme({components: {CalcitaRecordCard: {defaultProps: {slotProps: {root: {elevation: 3}}}}}});
+```
+
+`className`, `style` y `sx` de `slotProps` se suman a los de Calcita; una pieza dentro de otra igual no toma los `slots` de la
+de afuera. `TextInput` es la excepción: su `slotProps` es el del `TextField` de MUI (`input`, `htmlInput`…). Una pieza propia
+del proyecto se arma con lo mismo: `piecePart`, `usePieceProps` y `withPieceSlots`.
+
+El `sx` de la pantalla se **combina regla por regla** con el de la pieza, no la reemplaza: en la tabla,
+`gridSx={{'& .MuiDataGrid-cell': {alignItems: 'flex-start'}}}` cambia solo la alineación y la celda conserva lo demás.
+Para hacer lo mismo en un componente propio: `sx={[{p: 2}, ...sxListOf(sx)]}` (una lista de sx, como pide MUI; nunca
+`{p: 2, ...sx}`, que pierde la llave entera cuando las dos traen la misma).
+
 <details>
 <summary>Las piezas, con su nombre en el tema y sus partes</summary>
 
@@ -324,11 +376,14 @@ dejar Calcita con su propia cara, parte por parte.
 | `CalcitaAttachmentsInput` | `root`, `actions`, `button`, `list`, `fileChip`, `limits` |
 | `CalcitaAuditTrailDialog` | `description` |
 | `CalcitaAuthLayout` | `root`, `tools`, `body`, `brand`, `logo`, `brandName`, `card`, `description`, `content`, `footer` |
+| `CalcitaBackButton` | `root` |
+| `CalcitaBarActionButton` | `button`, `iconButton`, `menuItem` |
 | `CalcitaBarActions` | `group` |
 | `CalcitaBarCapsule` | `root` |
 | `CalcitaBarList` | `row`, `chart` |
 | `CalcitaBarSearch` | `field` |
 | `CalcitaCalendarHeatmap` | `header`, `toggle`, `tableArea`, `dateCell`, `valueCell`, `descriptionCell`, `gridArea`, `grid`, `monthLabel`, `week`, `dayLabel`, `cell`, `legend`, `legendLess`, `legendCell`, `legendMore` |
+| `CalcitaCatalogInput` | `field` |
 | `CalcitaCfdiSummary` | `root`, `header`, `amounts`, `concepts` |
 | `CalcitaChart` | `tableArea`, `legend`, `legendItem`, `legendLine`, `legendSwatch`, `reference`, `referenceLine` |
 | `CalcitaChartTooltip` | `root` |
@@ -340,23 +395,27 @@ dejar Calcita con su propia cara, parte por parte.
 | `CalcitaConfirmDialog` | `problem`, `actions` |
 | `CalcitaContentDialog` | `header`, `title`, `closeButton`, `body` |
 | `CalcitaCookieNotice` | `root`, `text`, `actions` |
+| `CalcitaCopyButton` | `button` |
 | `CalcitaCountdown` | `root` |
+| `CalcitaDateInput` | `picker` |
 | `CalcitaDateRangeFilter` | `chip`, `panel`, `actions` |
+| `CalcitaDateTimeInput` | `picker` |
 | `CalcitaDefinitionList` | `root`, `entry`, `label`, `value` |
 | `CalcitaDemoTotpCode` | `root`, `code` |
 | `CalcitaDetailHeader` | `root`, `titleArea`, `title`, `badges`, `actions` |
 | `CalcitaDownloadManager` | `doneIcon`, `failedIcon`, `canceledIcon`, `cancelButton`, `progress`, `cancelIcon`, `item`, `itemText`, `itemStatus`, `itemActions`, `panel`, `header`, `title`, `list` |
 | `CalcitaDownloadMenu` | `button` |
-| `CalcitaEmptyState` | `root`, `icon` |
 | `CalcitaEfirmaFields` | `root`, `certificate`, `verify` |
+| `CalcitaEmptyState` | `root`, `icon` |
 | `CalcitaErrorPage` | `root`, `actions` |
 | `CalcitaEventCalendar` | `toolbar`, `navigation`, `title`, `calendar` |
 | `CalcitaEventDetails` | `row`, `rowContent`, `titleRow`, `toneDot`, `linkRow`, `link`, `guestsTitle`, `guest`, `guestAvatar`, `guestName`, `notes`, `actions` |
+| `CalcitaFieldFrame` | `root`, `label` |
 | `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`) |
+| `CalcitaFilterDrawer` | `header`, `body`, `footer` |
 | `CalcitaFontSizeToggle` | `button` |
 | `CalcitaFormProblemAlert` | `root` |
 | `CalcitaFormRow` | `root`, `label`, `control` |
@@ -367,6 +426,7 @@ 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` |
+| `CalcitaHelpButton` | `root` |
 | `CalcitaHelpCarouselDialog` | `media`, `content`, `dots`, `actions` |
 | `CalcitaIconBadge` | `root`, `icon`, `label` |
 | `CalcitaImageInput` | `root`, `preview`, `image`, `placeholder`, `actions` |
@@ -383,32 +443,37 @@ dejar Calcita con su propia cara, parte por parte.
 | `CalcitaMetricCard` | `root`, `action`, `header`, `icon`, `label`, `value`, `caption`, `extra`, `trend` |
 | `CalcitaMobileTabBar` | `tab`, `tabIconPlaceholder`, `tabLabel`, `root`, `bar`, `minimized`, `account`, `sheetHeader` |
 | `CalcitaModalWaiting` | `root`, `title`, `body`, `text` |
+| `CalcitaMonthInput` | `picker` |
 | `CalcitaMultiSelectFilter` | `list`, `option` |
 | `CalcitaNewBuildNotice` | `floating`, `icon`, `message`, `reloadButton`, `banner` |
+| `CalcitaNumberInput` | `field` |
 | `CalcitaPageBreadcrumbs` | `root`, `link`, `current` |
 | `CalcitaPageHeader` | `root`, `subtitle`, `action` |
 | `CalcitaPageHeading` | `root`, `breadcrumbs`, `titleRow`, `title`, `actions`, `description` |
 | `CalcitaPasswordChecklist` | `title`, `list`, `item`, `hidden` |
+| `CalcitaPdfViewerDialog` | `actions`, `frame` |
 | `CalcitaPeriodRangeSelector` | `field`, `select`, `root` |
 | `CalcitaPermissionMatrix` | `permission`, `checkbox`, `group`, `groupHeader`, `groupTitle`, `grid` |
 | `CalcitaPondDropzone` | `root`, `summary`, `limits`, `actions`, `extra` |
 | `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` |
+| `CalcitaRecordCardSkeleton` | `root` |
 | `CalcitaRecoveryCodesDialog` | `codes`, `actions` |
-| `CalcitaRouteTabs` | `root`, `tab`, `badge` |
-| `CalcitaScrollableRow` | `root` |
 | `CalcitaRepeatingFields` | `root`, `row`, `rowHeader`, `rowContent`, `addButton`, `helper` |
 | `CalcitaRichTextEditor` | `root`, `toolbar`, `content`, `footer` |
 | `CalcitaRichTextView` | `root` |
+| `CalcitaRouteTabs` | `root`, `tab`, `badge` |
+| `CalcitaScrollableRow` | `root` |
 | `CalcitaSecondStepForm` | `actions` |
+| `CalcitaSecretField` | `field` |
 | `CalcitaSectionCard` | `root`, `header`, `title` |
 | `CalcitaSegmentedControl` | `root` |
 | `CalcitaSelectInput` | `option`, `optionText` |
 | `CalcitaSelectionActions` | `bar`, `count`, `clear`, `phoneCount`, `phoneActions` |
-| `CalcitaServerTable` | `toolbar`, `summary`, `customHeader`, `count`, `countRow`, `selectionNotice`, `error`, `card`, `grid`, `pagination` |
+| `CalcitaServerTable` | `cards`, `cardsPagination`, `viewToggle`, `toolbar`, `summary`, `customHeader`, `count`, `countRow`, `selectionNotice`, `error`, `card`, `grid`, `pagination` |
+| `CalcitaServerTableFilterDrawer` | `button` |
 | `CalcitaSessionsCard` | `item`, `itemIcon`, `itemHeader`, `actions` |
 | `CalcitaSettingsMenu` | `divider` |
 | `CalcitaSideMenu` | `scrollArrow`, `root`, `brand`, `brandLogo`, `brandText`, `brandName`, `brandCaption`, `railTop`, `listArea`, `list`, `section`, `sectionTitle`, `sectionTitleText`, `footer`, `railBottom` |
@@ -416,19 +481,22 @@ dejar Calcita con su propia cara, parte por parte.
 | `CalcitaSignInForm` | `footer` |
 | `CalcitaSignInScreen` | `alert` |
 | `CalcitaSortableFilterHeader` | `title`, `root`, `sortButton`, `sortIndicator`, `clearButton` |
+| `CalcitaStackedCell` | `root`, `line`, `label`, `valueRow`, `primary`, `secondary`, `note` |
 | `CalcitaStatusChip` | `root`, `dot`, `label`, `chip` |
 | `CalcitaSubmenuActionsMenu` | `badge` |
+| `CalcitaSubmitButton` | `root` |
 | `CalcitaTabBarEditor` | `root`, `header`, `title`, `list`, `itemIcon`, `footer` |
 | `CalcitaTableToggle` | `root`, `button` |
 | `CalcitaTag` | `root` |
 | `CalcitaTemplateDownloadButton` | `root` |
 | `CalcitaTermsAcceptanceDialog` | `content`, `frame`, `footer` |
 | `CalcitaTextInput` | `field` |
+| `CalcitaTimeInput` | `picker` |
 | `CalcitaTopMenu` | `link`, `root` |
 | `CalcitaTransferListInput` | `root`, `list`, `actions` |
 | `CalcitaTwoStepVerification` | `qr`, `secret`, `secretCode`, `header`, `headerTitle`, `headerText`, `menuIcon` |
 | `CalcitaWizardLayout` | `stepper`, `phoneSteps`, `actions` |
-| `CalcitaWordmark` | `root` |
+| `CalcitaWordmark` | `root`, `mode` |
 
 </details>
 
@@ -532,11 +600,16 @@ estatus, insignias, botón para abrirlo y menú «⋯»; en el cuerpo sus datos
 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
+submenús (`children`), que se abren dentro del mismo menú con «Regresar». Un renglón con `to` es una pantalla de la app: va
+con la navegación del proyecto, así el clic normal no recarga la app y Cmd/Ctrl+clic o el botón de en medio la abren en otra
+pestaña (`href` es para lo de afuera). `onClick` recibe el evento del clic.
+
+Para las secciones de un registro, `RouteTabs`: pestañas donde cada una es una dirección (se comparte la liga a una
+pestaña); por ruta (cada pestaña su página, y «atrás» regresa a la anterior) o en la consulta (`mode="query"`, `?tab=pagos`,
+con `useActiveRouteTab` para pintar el panel), con ícono, conteo y permiso por pestaña. Las de la consulta son vistas de la
+misma ficha: por omisión reemplazan la entrada del historial, así «atrás» y el `BackButton` salen de la ficha en vez de pasear
+por sus pestañas (`replace={false}` lo apaga; en las de ruta, `replace` lo prende). Las tres navegaciones de Calcita (la del
+navegador, la de `#` y la de Next) y react-router saben reemplazar. 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,
@@ -554,6 +627,42 @@ El marco avisa cuando la persona encoge el menú (`onMenuCollapse`), abre el men
 sus pestañas (`onMobileTabsChange`), para guardar esas preferencias en el servidor del proyecto si se quiere; sus textos se
 cambian con `texts`.
 
+## La tabla de servidor (`/table`)
+
+`ServerTable` pagina, filtra y ordena en el servidor (`fetchPage` recibe `{filters, sortOrders, page, pageSize}` y regresa
+`{rows, total, facets}`); con `prefix` su estado va en la dirección. Lo que piden casi todas las listas de administración
+viene listo:
+
+```jsx
+import {ACTIONS_COLUMN_FIELD, ServerTable, actionsColumn, stackedColumn, statusColumn} from '@stackcraftmx/calcita/table';
+
+const columns = [
+    actionsColumn({label: 'Acciones', actionsOf: (row) => [{key: 'open', label: 'Abrir', to: `/clientes/${row.id}`}]}),
+    stackedColumn({field: 'business_name', label: 'Empresa', entries: (row) => [row.business_name, row.rfc, row.regime]}),
+    stackedColumn({field: 'created_at', label: 'Fechas', entries: (row) => [                       // con etiqueta
+        {label: 'Alta', value: formatDate(row.created_at)}, {label: 'Último cambio', value: formatDate(row.updated_at)},
+    ]}),
+    statusColumn({field: 'status', label: 'Estado', dictionary: REGISTRATION_STATUS, t}),           // el ancho, medido
+];
+
+<ServerTable prefix="clientes" fetchPage={fetchClients} columns={columns} ariaLabel="Clientes"
+             fixedColumn={[ACTIONS_COLUMN_FIELD, 'business_name']}                               // fijas al deslizar
+             renderCard={(row) => <RecordCard title={row.business_name} … />} />                 // también en tarjetas
+```
+
+- `stackedColumn`: los datos que se leen de corrido en una celda, uno debajo del otro, los que hagan falta (el primero en
+  negritas, los demás en gris). Cada dato va solo, si el encabezado ya dice qué son, o con su etiqueta arriba
+  (`{label, value, note}`) si el encabezado nombra al grupo. Un dato vacío no se pinta, salvo el principal o uno con
+  etiqueta, que enseñan «—» (`texts={{cells: {empty: '- - -'}}}` lo cambia). Los renglones toman su alto solos;
+  `getRowHeight` también acepta `'auto'`. `StackedCell` es la misma celda para un `renderCell` propio.
+- `statusColumn`: el estatus desde su diccionario, con filtro de facetas y, con `t`, el ancho de su etiqueta más larga.
+- `actionsColumn`: el «⋯» de cada renglón en su columna, de ancho fijo.
+- `fixedColumn` acepta una lista: cada una se pega donde termina la anterior (las que no son la última llevan `width`).
+- `renderCard`: la misma lista en tarjetas, con la misma búsqueda, filtros, orden y páginas; un botón cambia de vista y con
+  `prefix` la vista va en la dirección (`?clientes_view=cards`). `view`, `defaultView`, `onViewChange` y `showViewToggle`
+  para decidirlo desde la pantalla.
+- `gridSx` se combina con los estilos de la tabla regla por regla; `gridProps` pasa lo demás al DataGrid.
+
 ## Eventos y textos de cada componente
 
 Cada componente de la casa avisa hacia afuera todo lo que pasa adentro (`onSelect`, `onChange`, `onViewChange`,
@@ -644,6 +753,29 @@ location /ventas/ {
 }
 ```
 
+Si el prefijo lo decide el servidor al servir la página (Laravel con `config('app.url')`, un proxy con su ruta), se construye
+UNA vez con archivos relativos (`ASSET_URL=./`) y la página trae `<base href="/ventas/">`: `documentBasePath()` lo lee al
+abrirla (`null` si no hay `<base>`) y el proyecto de `calcita new` ya lo usa para el router y `publicUrlOf`.
+
+## Direcciones con nombre y textos que se juntan solos
+
+Cuando una pantalla lleva a la de otro módulo (el detalle de un cliente regresa a la lista de donde salió), cada módulo
+publica sus direcciones en su archivo y un índice las junta; se piden por nombre, sin importar el otro módulo:
+
+```js
+// src/app/appPaths.js — el glob tiene que ser un texto literal: Vite lo resuelve al compilar
+export const {pathOf} = createPathIndex(import.meta.glob('@/modules/**/paths.js', {eager: true}));
+
+pathOf('admin:profile:detail', {groupId: 2, userId: 7675, tab: 'documentos'})   // '/admin/user/detail/2/7675?tab=documentos'
+```
+
+Lo que la ruta pide (`:userId`) se sustituye y lo que sobra va como consulta; un nombre que no existe o una parte que falta
+truena y dice qué sí hay. Las direcciones del API de cada módulo, igual: `createPathIndex(glob, {exportName: 'uris'})`.
+`fillPath(ruta, partes)` llena una suelta.
+
+Los textos de cada módulo se juntan con `combineTexts`: por idioma y namespace, los objetos de adentro se suman
+(`validation.fields` de dos módulos) y un texto repetido entre módulos truena en vez de pisarse.
+
 ## La petición de la casa
 
 Todo lo que habla con el servidor pasa por un cliente, armado una vez por proyecto con `fetch` del navegador (sin axios):
@@ -872,6 +1004,35 @@ 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.
 
+### Mensajes de error propios (sin tocar el esquema)
+
+Los mensajes de `buildYupLocale()` son llaves que se traducen al pintarse, y cada uno lleva **su regla y su campo**. Cuando
+el negocio pide un mensaje muy específico no hace falta tocar el esquema ni los mensajes de Calcita. El primero que exista
+gana:
+
+1. el de la pantalla, en el campo: `<FormTextField name="rfc" messages={{matches: 'El RFC lleva 12 o 13 caracteres'}} />`;
+2. el de los textos del proyecto para ese campo y esa regla, en todas las pantallas:
+   `{es: {validation: {fields: {rfc: {matches: 'El RFC lleva 12 o 13 caracteres'}}}}}` (dentro de una lista,
+   `contacts[2].email` busca `contacts.email`);
+3. el general de Calcita (o el del esquema: `.required({key: 'clientes:rfcObligatorio'})`).
+
+Los textos pueden decir el nombre del campo: `{{label}}` (el de `.label('RFC')` del esquema o, si no, la etiqueta del campo).
+
+**Un sistema que ya existe** con su propio `setLocale` de yup: Calcita entiende sola `{key, values}`, `{msg, values}` (la de
+muchos sistemas con i18next), `{message: 'texto'}`, el error entero de react-hook-form y un texto ya escrito. Para otra
+forma, una función en el proveedor; los esquemas viejos entran sin reescribirse:
+
+```jsx
+<ToolkitProvider readValidationMessage={(error) => (error?.codigo ? {key: `legado:${error.codigo}`, values: error.datos} : undefined)}>
+```
+
+Una forma que no entiende no se pinta como «[object Object]»: sale el mensaje general y se avisa en la consola. Un campo
+propio del proyecto usa lo mismo con `useValidationText({label, messages})`.
+
+Reglas listas, con su mensaje en el idioma activo: `sameAsFieldRule('password', {otherLabel: 'la contraseña'})` (confirmar
+una contraseña, una CLABE o un correo), `percentRule({max: 30})` y, en `/mexico`, `postalCodeRule()` junto a `rfcRule()`,
+`curpRule()` y `clabeRule()`.
+
 ### 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

package/cli/calcita.js

@@ -14,6 +14,7 @@ import {argv, cwd, exit, stdin, stdout} from 'node:process';
 import {parseArgs} from 'node:util';
 
 import {askQuestions} from './askQuestions.js';
+import {checkTexts} from './checkTexts.js';
 import {makeComponent} from './makeComponent.js';
 import {makeForm} from './makeForm.js';
 import {makeModule} from './makeModule.js';
@@ -33,6 +34,8 @@ const HELP = `Calcita: proyectos y esqueletos con la forma de los ejemplos.
   calcita make:form <módulo> <Formulario>    un formulario con sus reglas y sus textos
   calcita make:component <Componente>        un componente en src/core (lo usan varios módulos)
        --module <módulo>                     … o solo de un módulo
+  calcita check:texts                        revisa que cada t('llave') exista en todos los idiomas, y que los idiomas tengan
+                                             las mismas llaves (lo que si no se descubre en la pantalla)
 
 Opciones:
   -y, --yes                 sin preguntas: lo recomendado, más lo que diga cada opción
@@ -125,6 +128,17 @@ async function runMakeComponent(componentName) {
     stdout.write('\nListo.\n');
 }
 
+async function runCheckTexts() {
+    const {problems, checkedKeys, textFiles, languages} = await checkTexts({projectRoot: cwd()});
+    stdout.write(`Revisé ${checkedKeys} llaves escritas en el código contra ${textFiles.length} archivos de textos (${languages.join(', ') || 'sin idiomas'}).\n`);
+    if (problems.length === 0) {
+        stdout.write('Todo en su lugar.\n');
+        return;
+    }
+    stdout.write(`\n${problems.map((problem) => `  ✗ ${problem}`).join('\n')}\n`);
+    throw new CliError(`${problems.length} problema(s) con los textos.`);
+}
+
 const COMMANDS = Object.freeze({
     'new': runNew,
     'init': () => runNew('.'),
@@ -132,6 +146,7 @@ const COMMANDS = Object.freeze({
     'make:page': runMakePage,
     'make:form': runMakeForm,
     'make:component': runMakeComponent,
+    'check:texts': runCheckTexts,
 });
 
 try {

package/cli/checkTexts.js

@@ -0,0 +1,209 @@
+// calcita check:texts — revisa los textos del proyecto sin abrir la app:
+//   1. que cada t('llave') escrita tal cual en el código exista en todos los idiomas (con su namespace: el de
+//      useToolkitTranslation('orders') del archivo, o el que trae la llave, 'common:actions.save');
+//   2. que cada idioma tenga las mismas llaves que los demás (lo que falta en inglés se pintaría en español… o como llave).
+// Sin esto, una llave que no existe se descubre cuando alguien la ve en la pantalla («profile:tabs.documents»).
+//
+// Lo que NO revisa: las llaves armadas con una variable (t(`status.${value}`)) ni las que llevan defaultValue (son opcionales).
+// Para esas está el aviso de Calcita en la consola (onMissingText de ToolkitProvider).
+//
+// Lee los archivos de textos del proyecto (src/**/*Texts.js y src/**/texts.js: cada uno exporta {es: {...}, en: {...}}) con
+// node, así que no deben importar otros archivos; el que los junta (con import.meta.glob) se salta. Los namespaces de Calcita
+// (common, table, validation…) salen de su dist/.
+//
+// Solo node, sin dependencias (el CLI corre antes de que el proyecto tenga nada instalado): function (regla de la casa).
+// Pruebas en checkTexts.test.js.
+import {readdir, readFile} from 'node:fs/promises';
+import {join, relative} from 'node:path';
+import {pathToFileURL} from 'node:url';
+
+const SOURCE_EXTENSIONS = /\.(jsx?|tsx?)$/;
+const TEST_FILE = /\.test\.(jsx?|tsx?)$/;
+const TEXT_FILE = /(?:^|\/)(?:texts|[A-Za-z0-9]+Texts)\.js$/;
+const IGNORED_FOLDERS = new Set(['node_modules', 'dist', 'coverage', '.git']);
+// el namespace de un archivo: useToolkitTranslation('orders') o useToolkitTranslation(['orders', …])
+const NAMESPACE_CALL = /useToolkitTranslation\(\s*\[?\s*(['"])([\w-]+)\1/g;
+// una llave escrita tal cual: t('list.title') o t("common:actions.save"); con lo que sigue, para ver si trae defaultValue
+const KEY_CALL = /\bt\(\s*(['"])([^'"`$\n]+?)\1([^)]{0,200})/g;
+const PLURAL_SUFFIXES = ['', '_zero', '_one', '_two', '_few', '_many', '_other'];
+
+/**
+ * Los archivos de una carpeta y sus subcarpetas, sin node_modules ni dist.
+ *
+ * @param {string} folder
+ * @returns {Promise<string[]>}
+ */
+async function filesOf(folder) {
+    const entries = await readdir(folder, {withFileTypes: true}).catch(() => []);
+    const nested = await Promise.all(entries.map(async (entry) => {
+        const path = join(folder, entry.name);
+        if (entry.isDirectory()) {
+            return IGNORED_FOLDERS.has(entry.name) ? [] : filesOf(path);
+        }
+        return [path];
+    }));
+    return nested.flat();
+}
+
+/**
+ * Suma los textos de un archivo a los de todos (por idioma y namespace, objetos por dentro). Aquí no truena con un repetido:
+ * lo anota, para decirlo junto con lo demás.
+ */
+function addTexts(combined, fileTexts, duplicates, fileName) {
+    const mergeInto = (target, added, place) => {
+        for (const [key, value] of Object.entries(added)) {
+            const isObject = value && typeof value === 'object';
+            const keyPath = [...place.path, key];
+            if (isObject && target[key] && typeof target[key] === 'object') {
+                mergeInto(target[key], value, {...place, path: keyPath});
+            } else if (Object.hasOwn(target, key)) {
+                duplicates.push(`«${place.namespace}:${keyPath.join('.')}» en ${place.language} (otra vez en ${fileName})`);
+            } else {
+                target[key] = isObject ? structuredClone(value) : value;
+            }
+        }
+    };
+    for (const [language, namespaces] of Object.entries(fileTexts)) {
+        combined[language] ??= {};
+        for (const [namespace, keys] of Object.entries(namespaces ?? {})) {
+            combined[language][namespace] ??= {};
+            mergeInto(combined[language][namespace], keys, {language, namespace, path: []});
+        }
+    }
+}
+
+/**
+ * ¿Parece un objeto de textos? ({es: {namespace: {...}}, en: {...}}: llaves de idioma con objetos adentro)
+ *
+ * @param {unknown} value
+ * @returns {boolean}
+ */
+function looksLikeTexts(value) {
+    return Boolean(value) && typeof value === 'object' && Object.keys(value).length > 0
+        && Object.entries(value).every(([language, namespaces]) => /^[a-z]{2}(-[A-Z]{2})?$/.test(language) && namespaces && typeof namespaces === 'object');
+}
+
+/** Lo que hay en un camino con puntos ('list.title') dentro de un objeto. */
+function valueAt(object, dottedKey) {
+    return dottedKey.split('.').reduce((current, step) => (current && typeof current === 'object' ? current[step] : undefined), object);
+}
+
+/** ¿Existe la llave (o su plural) en ese namespace? */
+function hasKey(namespaceTexts, key) {
+    return PLURAL_SUFFIXES.some((suffix) => typeof valueAt(namespaceTexts, `${key}${suffix}`) === 'string');
+}
+
+/** Todas las llaves con texto de un objeto, con puntos (para comparar idiomas); los plurales cuentan como su llave base. */
+function leafKeysOf(object, prefix = '') {
+    return Object.entries(object ?? {}).flatMap(([key, value]) => {
+        const path = prefix ? `${prefix}.${key}` : key;
+        if (value && typeof value === 'object') {
+            return leafKeysOf(value, path);
+        }
+        return [path.replace(/_(zero|one|two|few|many|other)$/, '')];
+    });
+}
+
+/**
+ * Los textos de Calcita (common, table, validation…), del dist/ del paquete que corre este CLI. Sin dist/ (el repo del paquete
+ * sin construir), ninguno: las llaves de esos namespaces no se revisan.
+ *
+ * @returns {Promise<Record<string, object>>}
+ */
+async function packageTextsOf() {
+    const texts = {};
+    for (const language of ['es', 'en']) {
+        try {
+            const module = await import(new URL(`../dist/locales/${language}.js`, import.meta.url).href);
+            texts[language] = module.default ?? {};
+        } catch {
+            return {};
+        }
+    }
+    return texts;
+}
+
+/**
+ * @param {object} options
+ * @param {string} options.projectRoot la carpeta del proyecto
+ * @param {string} [options.sourceFolder] dónde está el código (por omisión src)
+ * @param {Record<string, object>} [options.packageTexts] los textos de Calcita (por omisión, los de su dist/)
+ * @returns {Promise<{problems: string[], checkedKeys: number, textFiles: string[], languages: string[]}>}
+ */
+export async function checkTexts({projectRoot, sourceFolder = 'src', packageTexts}) {
+    const sourceRoot = join(projectRoot, sourceFolder);
+    const files = await filesOf(sourceRoot);
+    const problems = [];
+
+    // 1. los textos del proyecto
+    const projectTexts = {};
+    const duplicates = [];
+    const textFiles = files.filter((file) => TEXT_FILE.test(file.replaceAll('\\', '/')));
+    const readTextFiles = [];
+    for (const file of textFiles) {
+        const fileName = relative(projectRoot, file);
+        // el que JUNTA los textos (appTexts.js, con el glob de Vite) no es un archivo de textos: se salta
+        if ((await readFile(file, 'utf8')).includes('import.meta.glob')) {
+            continue;
+        }
+        readTextFiles.push(fileName);
+        try {
+            const module = await import(pathToFileURL(file).href);
+            const exported = Object.values(module).filter(looksLikeTexts);
+            if (exported.length === 0) {
+                problems.push(`${fileName}: no exporta textos con la forma {es: {...}, en: {...}}`);
+            }
+            exported.forEach((fileTexts) => addTexts(projectTexts, fileTexts, duplicates, fileName));
+        } catch (error) {
+            problems.push(`${fileName}: no se pudo leer (${error.message.split('\n')[0]}); un archivo de textos no debe importar otros archivos`);
+        }
+    }
+    problems.push(...duplicates.map((duplicate) => `texto repetido: ${duplicate}`));
+
+    const languages = Object.keys(projectTexts);
+    // 2. que cada idioma tenga las mismas llaves
+    for (const language of languages) {
+        for (const otherLanguage of languages.filter((other) => other !== language)) {
+            for (const namespace of Object.keys(projectTexts[language])) {
+                const otherKeys = new Set(leafKeysOf(projectTexts[otherLanguage][namespace]));
+                for (const key of new Set(leafKeysOf(projectTexts[language][namespace]))) {
+                    if (!otherKeys.has(key)) {
+                        problems.push(`«${namespace}:${key}» está en ${language} y falta en ${otherLanguage}`);
+                    }
+                }
+            }
+        }
+    }
+
+    // 3. cada t('llave') escrita tal cual
+    const calcitaTexts = packageTexts ?? await packageTextsOf();
+    const textsOf = (language, namespace) => projectTexts[language]?.[namespace] ?? calcitaTexts[language]?.[namespace];
+    let checkedKeys = 0;
+    for (const file of files.filter((path) => SOURCE_EXTENSIONS.test(path) && !TEST_FILE.test(path))) {
+        const code = await readFile(file, 'utf8');
+        const fileNamespaces = [...code.matchAll(NAMESPACE_CALL)].map((match) => match[2]);
+        for (const match of code.matchAll(KEY_CALL)) {
+            const [, , key, rest] = match;
+            // con defaultValue la llave es opcional; una llave con espacios es un texto, no una llave
+            if (/defaultValue/.test(rest) || /\s/.test(key)) {
+                continue;
+            }
+            const line = code.slice(0, match.index).split('\n').length;
+            const place = `${relative(projectRoot, file)}:${line}`;
+            const [explicitNamespace, plainKey] = key.includes(':') ? key.split(':', 2) : [null, key];
+            const candidates = explicitNamespace ? [explicitNamespace] : fileNamespaces;
+            if (candidates.length === 0) {
+                continue;
+            }
+            checkedKeys += 1;
+            for (const language of languages.length > 0 ? languages : ['es']) {
+                const found = candidates.some((namespace) => hasKey(textsOf(language, namespace), plainKey));
+                if (!found) {
+                    problems.push(`${place}  «${explicitNamespace ? key : `${candidates[0]}:${key}`}» no existe en ${language}`);
+                }
+            }
+        }
+    }
+
+    return {problems, checkedKeys, textFiles: readTextFiles, languages};
+}

package/cli/packageVersions.js

@@ -7,7 +7,7 @@ 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), 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
+// (Vitest con jsdom y Testing Library), en las versiones que ya se probaron juntas con el mismo Vite 7 y React 19, y ESLint
 const VERSIONS_NOT_IN_PACKAGE = Object.freeze({
     i18next: '26.4.2',
     qrcode: '1.5.4',
@@ -16,6 +16,11 @@ const VERSIONS_NOT_IN_PACKAGE = Object.freeze({
     '@testing-library/dom': '10.4.2',
     '@testing-library/react': '16.3.3',
     '@testing-library/user-event': '14.6.7',
+    // ESLint del proyecto nuevo (pnpm lint): versiones con más de dos semanas publicadas al escogerlas (03/11/2026)
+    eslint: '10.13.0',
+    '@eslint/js': '10.0.1',
+    'eslint-plugin-react-hooks': '7.1.1',
+    globals: '17.13.0',
 });
 
 /**

package/cli/projectFiles.js

@@ -15,8 +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']);
-// las pruebas de pantalla (pnpm test): Vitest con jsdom como navegador y Testing Library para picar como una persona
+// las pruebas de pantalla (pnpm test): Vitest con jsdom como navegador y Testing Library para picar como una persona; y ESLint
+// (pnpm lint), que caza al escribir lo que si no se ve en la pantalla del cliente (una variable que no existe: «t is not defined»)
 const DEV_DEPENDENCIES = Object.freeze([
+    '@eslint/js', 'eslint', 'eslint-plugin-react-hooks', 'globals',
     '@testing-library/dom', '@testing-library/react', '@testing-library/user-event', '@vitejs/plugin-react', 'jsdom', 'vite', 'vitest',
 ]);
 
@@ -43,7 +45,7 @@ export function packageJsonOf({packageName, answers, calcitaPackage}) {
         version: '0.1.0',
         private: true,
         type: 'module',
-        scripts: {dev: 'vite', build: 'vite build', preview: 'vite preview', test: 'vitest run'},
+        scripts: {dev: 'vite', build: 'vite build', preview: 'vite preview', test: 'vitest run', lint: 'eslint .', 'check:texts': 'calcita check:texts'},
         dependencies: sortedByKey({'@stackcraftmx/calcita': `^${calcitaPackage.version}`, ...versionsOf(dependencyNames, calcitaPackage)}),
         devDependencies: sortedByKey(versionsOf([...DEV_DEPENDENCIES], calcitaPackage)),
         engines: {node: '>=22'},