@stackcraftmx/calcita 0.47.0 → 0.52.0

package/README.md

@@ -53,6 +53,14 @@ 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`; con el código en otra carpeta, `calcita check:texts --source resources/js` (un Laravel). Un archivo de
+textos puede reexportar otro con ruta relativa o con `@/` (aquí apunta a la carpeta del código, como en Vite; pide Node 22.15
+o más). Nunca da un verde falso: sin la carpeta, sin ningún archivo de textos o con uno
+que no se pudo leer, sale con problema y no compara llaves.
+
 ## Arrancar en un proyecto que ya existe
 
 ```bash
@@ -97,12 +105,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 +348,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 +379,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 +398,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 +429,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 +446,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 +484,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>
 
@@ -529,14 +600,20 @@ 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
+principal grande; abajo lo que va a todo lo ancho y «Ver detalle», que despliega más (`footerAlign` los junta a la
+izquierda o a la derecha; por omisión «Ver detalle» va en la otra orilla). 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 +631,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 +757,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):
@@ -854,6 +990,20 @@ formik y yup los instala el proyecto (`pnpm add formik yup`); `Formik`, `Form` y
 `@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 editar un registro de varios pasos (se entra a corregir un dato suelto, no a recorrer todo), el mismo `FormWizard`:
+
+```jsx
+<FormWizard steps={steps} submitLabel="Guardar cambios"
+            initialStepKey={review.stepKey}                   // abre en el paso que dice el servidor
+            orientation={WIZARD_ORIENTATION.vertical}         // un paso debajo del otro, con sus campos adentro
+            stepSelection={WIZARD_STEP_SELECTION.free}        // los títulos se pulsan: salta directo (o .checked: solo sin errores)
+            onStepChange={(stepKey) => setSearchParams({step: stepKey})} />
+```
+
+Con los títulos que se pulsan, la palomita de un paso la pone la pantalla (`steps[].completed`): «antes» ya no quiere decir
+«hecho». Al enviar, el formulario regresa al primer paso con error, como siempre. Sin estas opciones se porta igual que
+antes. `WizardLayout` suelto acepta lo mismo (`orientation`, `onStepSelect`); `skippedKeys` y `onSkip` ya no son obligatorios.
+
 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
 MUI. Son los mismos campos, sin cambiarles nada; las listas llevan su ⌃⌄ y la fecha va en una cápsula. `FormRow` es el
@@ -872,6 +1022,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,9 @@ 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)
+       --source <carpeta>                    … con el código en otra carpeta (por omisión src; en Laravel, resources/js)
 
 Opciones:
   -y, --yes                 sin preguntas: lo recomendado, más lo que diga cada opción
@@ -51,6 +55,7 @@ const {values: options, positionals} = parseArgs({
         'yes': {type: 'boolean', short: 'y'},
         'help': {type: 'boolean', short: 'h'},
         'module': {type: 'string'},
+        'source': {type: 'string'},
         'label-es': {type: 'string'},
         'label-en': {type: 'string'},
         ...ANSWER_OPTIONS,
@@ -125,6 +130,17 @@ async function runMakeComponent(componentName) {
     stdout.write('\nListo.\n');
 }
 
+async function runCheckTexts() {
+    const {problems, checkedKeys, textFiles, languages, sourceFolder} = await checkTexts({projectRoot: cwd(), sourceFolder: options.source});
+    stdout.write(`Revisé ${checkedKeys} llaves escritas en el código de ${sourceFolder}/ 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 +148,7 @@ const COMMANDS = Object.freeze({
     'make:page': runMakePage,
     'make:form': runMakeForm,
     'make:component': runMakeComponent,
+    'check:texts': runCheckTexts,
 });
 
 try {