@stackcraftmx/calcita 0.0.0-stage → 0.25.0

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

@@ -0,0 +1,107 @@
+// La raíz de la app: el ÚNICO lugar donde se conecta el framework. ToolkitProvider recibe el idioma, los textos, la zona, la
+// moneda y el router; los avisos (Toaster) se montan aquí una vez, para todas las pantallas. Aquí también se vigila si ya se
+// publicó otra versión (usePublishedBuildWatch): una pestaña abierta desde ayer, o la app anclada al inicio del iPhone, se
+// actualiza sola si estuvo fuera 15 minutos o más; si no, sale el aviso «Versión nueva» con su botón.
+//#if auth
+//
+// AccountProvider carga la sesión con el conector de la cuenta (core/accountConnector.js) y le pasa a ToolkitProvider la regla
+// de permisos de quien está dentro.
+//#endif
+//
+// Va como elemento de la ruta raíz y no afuera del router porque usa sus hooks (useNavigate, useLocation).
+//
+// Lo renderiza la app: arrow (regla de la casa).
+import {useEffect, useState} from 'react';
+import {Outlet} from 'react-router';
+import {
+//#if pwa
+    InstallPromptBanner,
+//#endif
+    Toaster,
+    ToolkitProvider,
+    usePublishedBuildWatch,
+} from '@stackcraftmx/calcita';
+//#if auth
+import {AccountProvider} from '@stackcraftmx/calcita/account';
+//#endif
+//#if i18next
+import {translateWithI18next} from '@stackcraftmx/calcita/i18next';
+//#endif
+import {reactRouterNavigation} from '@stackcraftmx/calcita/react-router';
+
+import {APP_BUILD_ID, APP_LANGUAGES, APP_NAME, BUILD_VERSION_URL, PRODUCT_CURRENCY, PRODUCT_TIME_ZONE} from '@/app/appSettings.js';
+//#if !i18next
+import {APP_TEXTS} from '@/app/appTexts.js';
+//#endif
+//#if i18next
+import {i18n} from '@/app/i18n.js';
+//#endif
+//#if auth
+import {accountConnector} from '@/core';
+//#endif
+//#if i18next
+
+// se arma una sola vez: lee de la instancia de i18next, no de una copia
+const translate = translateWithI18next(i18n);
+//#endif
+
+export const AppProviders = () => {
+    const [language, setLanguage] = useState(APP_LANGUAGES.spanish);
+    usePublishedBuildWatch({url: BUILD_VERSION_URL, buildId: APP_BUILD_ID});
+
+    // el idioma de la página, para el lector de pantalla y el corrector del navegador
+    useEffect(() => {
+        document.documentElement.lang = language;
+    }, [language]);
+//#if i18next
+
+    // primero i18next y luego la app: así la pantalla se vuelve a pintar ya con los textos del idioma nuevo
+    const changeLanguage = async (nextLanguage) => {
+        await i18n.changeLanguage(nextLanguage);
+        setLanguage(nextLanguage);
+    };
+//#endif
+
+//#if auth
+    return (
+        <AccountProvider connector={accountConnector}>
+            {(canAccess) => (
+                <ToolkitProvider language={language}
+//#if !i18next
+                                 onLanguageChange={setLanguage} texts={APP_TEXTS}
+//#endif
+//#if i18next
+                                 onLanguageChange={changeLanguage} translate={translate}
+//#endif
+                                 timeZone={PRODUCT_TIME_ZONE} currency={PRODUCT_CURRENCY} appName={APP_NAME} navigation={reactRouterNavigation}
+                                 buildId={APP_BUILD_ID} canAccess={canAccess}>
+                    <Outlet />
+                    <Toaster />
+//#if pwa
+                    <InstallPromptBanner />
+//#endif
+                </ToolkitProvider>
+            )}
+        </AccountProvider>
+    );
+//#endif
+//#if !auth
+    return (
+        <ToolkitProvider language={language}
+//#if !i18next
+                         onLanguageChange={setLanguage} texts={APP_TEXTS}
+//#endif
+//#if i18next
+                         onLanguageChange={changeLanguage} translate={translate}
+//#endif
+                         timeZone={PRODUCT_TIME_ZONE} currency={PRODUCT_CURRENCY} appName={APP_NAME} navigation={reactRouterNavigation}
+                         buildId={APP_BUILD_ID}>
+            <Outlet />
+            <Toaster />
+//#if pwa
+            <InstallPromptBanner />
+//#endif
+        </ToolkitProvider>
+    );
+//#endif
+};

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

@@ -0,0 +1,87 @@
+// El marco de las pantallas: AppLayout del framework (la barra con el logo, el menú por secciones y la cuenta) con el menú
+// compuesto con el menu.js de cada módulo.
+//
+// El menú no se escribe aquí: composeMenu descubre los menu.js de los módulos y deja solo los que se pueden ver.
+//#if auth
+//
+// Sin sesión no se entra: lleva a iniciar sesión, y de regreso a la pantalla que se quería abrir.
+//#endif
+//
+// Lo renderiza la app: arrow (regla de la casa).
+//#if auth
+import {useMemo, useState} from 'react';
+import {Navigate, Outlet, useLocation, useNavigate} from 'react-router';
+//#endif
+//#if !auth
+import {useMemo} from 'react';
+import {Outlet} from 'react-router';
+//#endif
+import {
+    AppLayout,
+//#if pwa
+    InstallAppSetting,
+//#endif
+    MENU_POSITION,
+    composeMenu,
+    useAccessChecker,
+    useToolkitTranslation,
+//#if auth
+    withRedirect,
+//#endif
+} from '@stackcraftmx/calcita';
+//#if auth
+import {useAccount} from '@stackcraftmx/calcita/account';
+//#endif
+import {useIsNavigating} from '@stackcraftmx/calcita/react-router';
+
+//#if auth
+import {APP_PATHS, AppLogo} from '@/core';
+//#endif
+//#if !auth
+import {AppLogo} from '@/core';
+//#endif
+
+// cada módulo declara su entrada en su menu.js (orden, permiso, sección, texto e ícono)
+const MENU_MODULES = import.meta.glob('@/modules/*/menu.js', {eager: true});
+
+export const AppShell = () => {
+    const {t} = useToolkitTranslation('shell');
+    const canAccess = useAccessChecker();
+    const isNavigating = useIsNavigating();
+    const menuItems = useMemo(() => composeMenu(MENU_MODULES, {canAccess}), [canAccess]);
+//#if auth
+    const {session, signOut} = useAccount();
+    const {pathname, search} = useLocation();
+    const navigate = useNavigate();
+    const [isSigningOut, setIsSigningOut] = useState(false);
+
+    // salir a propósito: a iniciar sesión sin «regresar a», y luego se cierra la sesión
+    const leave = async () => {
+        setIsSigningOut(true);
+        navigate(APP_PATHS.signIn);
+        await signOut();
+    };
+
+    // guard clause: sin sesión, a iniciar sesión con la pantalla que se quería abrir
+    if (!session) {
+        return <Navigate to={withRedirect(APP_PATHS.signIn, `${pathname}${search}`)} replace />;
+    }
+//#endif
+
+    return (
+        <AppLayout logo={<AppLogo />} brandCaption={t('caption')} menuItems={menuItems} menuPosition={MENU_POSITION.__MENU_POSITION__}
+                   isNavigating={isNavigating}
+//#if auth
+                   user={session.user} profilePath={APP_PATHS.profile} onSignOut={leave} isSigningOut={isSigningOut}
+//#endif
+//#if !darkMode
+                   showColorSchemeToggle={false}
+//#endif
+//#if pwa
+                   accountSettings={<InstallAppSetting />}
+//#endif
+        >
+            <Outlet />
+        </AppLayout>
+    );
+};

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

@@ -0,0 +1,51 @@
+// Las rutas de la app: AppProviders por fuera (conecta el framework), las pantallas sin marco (publicRoutes: entrar, «¿olvidó
+// su contraseña?») y las de cada módulo dentro del marco (AppShell).
+//
+// Las rutas no se escriben aquí: cada módulo las declara en su routes.js y se descubren solas, cada grupo con el permiso del
+// menu.js de su módulo (withAccess: quien no puede ve la página de «sin permiso»). Módulo nuevo = cero ediciones aquí.
+//
+// Cada pantalla viaja en su propio archivo (lazy): si se publicó otra versión con la pestaña abierta, withChunkRecovery
+// recarga una vez, y si una pantalla truena RouteErrorScreen dice qué pasó, con su botón para recargar.
+import {createBrowserRouter} from 'react-router';
+import {ERROR_PAGE_KIND, ErrorPage, FullPageLoader} from '@stackcraftmx/calcita';
+import {RouteErrorScreen, withAccess, withChunkRecovery} from '@stackcraftmx/calcita/react-router';
+
+import {AppProviders} from '@/app/AppProviders.jsx';
+import {AppShell} from '@/app/AppShell.jsx';
+import {APP_PATHS, ROUTER_BASENAME} from '@/core';
+
+const ROUTE_MODULES = import.meta.glob('@/modules/*/routes.js', {eager: true});
+const MENU_MODULES = import.meta.glob('@/modules/*/menu.js', {eager: true});
+
+// el grupo de rutas de cada módulo, con la regla de su menu.js (el que está junto a su routes.js)
+const moduleRouteGroups = Object.entries(ROUTE_MODULES)
+    .filter(([, routeModule]) => routeModule.routes?.length)
+    .map(([routesPath, routeModule]) => {
+        const menuModule = MENU_MODULES[routesPath.replace(/routes\.js$/, 'menu.js')];
+        return withAccess(menuModule?.access, routeModule.routes);
+    });
+
+// las pantallas sin el marco (entrar…)
+const publicRoutes = Object.values(ROUTE_MODULES).flatMap((routeModule) => routeModule.publicRoutes ?? []);
+
+export const appRouter = createBrowserRouter([
+    {
+        path: APP_PATHS.home,
+        element: <AppProviders />,
+        // lo que se ve al abrir la app directo en una pantalla, mientras se descarga (las rutas son lazy)
+        HydrateFallback: FullPageLoader,
+        ErrorBoundary: RouteErrorScreen,
+        children: withChunkRecovery([
+            ...publicRoutes,
+            {
+                element: <AppShell />,
+                children: [
+                    ...moduleRouteGroups,
+                    {path: '*', element: <ErrorPage kind={ERROR_PAGE_KIND.notFound} />},
+                ],
+            },
+        ]),
+    },
+// detrás de un proxy con prefijo (ASSET_URL), el router lo quita al leer la dirección y lo pone en cada liga: las pantallas
+// siguen escribiendo sus rutas desde la raíz ('/contacts')
+], {basename: ROUTER_BASENAME});

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

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

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

@@ -0,0 +1,15 @@
+// Todos los textos de la app: los de la barra y los de cada módulo, juntos por idioma.
+//
+// Los de los módulos se descubren solos (modules/<módulo>/*Texts.js): módulo nuevo = cero ediciones aquí.
+//
+// OJO: constante de módulo. ToolkitProvider vuelve a configurar todo cuando cambian sus textos; un objeto nuevo en cada
+// pintada lo haría en cada pintada.
+import {combineTexts} from '@/app/combineTexts.js';
+import {shellTexts} from '@/app/shellTexts.js';
+
+const MODULE_TEXT_FILES = import.meta.glob('@/modules/*/*Texts.js', {eager: true});
+
+// cada archivo de textos exporta un solo objeto {es, en}
+const moduleTexts = Object.values(MODULE_TEXT_FILES).flatMap((textFile) => Object.values(textFile));
+
+export const APP_TEXTS = combineTexts([shellTexts, ...moduleTexts]);

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

@@ -0,0 +1,31 @@
+// Junta los textos de cada módulo en el objeto `texts` que recibe ToolkitProvider: {es: {namespace: {...}}, en: {...}}.
+//
+// Cada módulo trae sus archivos de textos (*Texts.js) con su namespace. Aquí se juntan por idioma y por namespace; dos
+// archivos con el mismo namespace suman sus llaves, y si repiten una llave truena: un texto pisado en silencio saldría en
+// la pantalla equivocada.
+//
+// Funciones puras, sin React: function (regla de la casa).
+
+/**
+ * @param {Array<Record<string, Record<string, object>>>} textFiles los textos de cada archivo, por idioma
+ * @returns {Record<string, Record<string, object>>} todos los textos, por idioma y namespace
+ */
+export function combineTexts(textFiles) {
+    const combined = {};
+
+    for (const fileTexts of textFiles) {
+        for (const [language, namespaces] of Object.entries(fileTexts)) {
+            combined[language] ??= {};
+            for (const [namespace, keys] of Object.entries(namespaces)) {
+                const currentKeys = combined[language][namespace] ?? {};
+                const repeatedKey = Object.keys(keys).find((key) => Object.hasOwn(currentKeys, key));
+                if (repeatedKey) {
+                    throw new Error(`Dos archivos definen el texto «${namespace}:${repeatedKey}» en «${language}»`);
+                }
+                combined[language][namespace] = {...currentKeys, ...keys};
+            }
+        }
+    }
+
+    return combined;
+}

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

@@ -0,0 +1,19 @@
+// i18next con los textos de la app (los de cada módulo, juntos en APP_TEXTS) como sus recursos: los textos se escriben en
+// los *Texts.js de cada módulo, como siempre, y Calcita los lee de esta instancia (translateWithI18next en AppProviders).
+// Lo que la app no tenga (los textos de las tablas, de los diálogos, de las validaciones) sale de los textos de Calcita.
+import i18next from 'i18next';
+
+import {APP_LANGUAGES} from '@/app/appSettings.js';
+import {APP_TEXTS} from '@/app/appTexts.js';
+
+export const i18n = i18next.createInstance();
+
+// sin esperar: con los recursos ya en memoria (initAsync: false) queda lista al terminar init
+i18n.init({
+    resources: APP_TEXTS,
+    lng: APP_LANGUAGES.spanish,
+    fallbackLng: APP_LANGUAGES.spanish,
+    // React ya escapa lo que pinta: si i18next también, un «<» saldría como «&lt;»
+    interpolation: {escapeValue: false},
+    initAsync: false,
+});

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

@@ -0,0 +1,16 @@
+// Los textos del marco de la app (namespace shell): el renglón bajo el nombre y los títulos de las secciones del menú.
+// Un módulo elige su sección en su menu.js (sectionKey: 'shell:sections.operation').
+export const shellTexts = {
+    es: {
+        shell: {
+            caption: 'Panel de administración',
+            sections: {operation: 'Operación'},
+        },
+    },
+    en: {
+        shell: {
+            caption: 'Admin panel',
+            sections: {operation: 'Operation'},
+        },
+    },
+};

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

@@ -0,0 +1,14 @@
+// El logo de la app (public/favicon.svg) en la barra y en las pantallas de entrar: cámbielo por el suyo aquí, en un solo
+// lugar.
+//
+// Genérico, sin estado: function (regla de la casa).
+import Box from '@mui/material/Box';
+
+import {publicUrlOf} from '@/core/publicPaths.js';
+
+// el tamaño que piden la barra y la tarjeta de entrar
+const LOGO_SIZE_PIXELS = 28;
+
+export function AppLogo() {
+    return <Box component="img" src={publicUrlOf('favicon.svg')} alt="" sx={{width: LOGO_SIZE_PIXELS, height: LOGO_SIZE_PIXELS}} />;
+}

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

@@ -0,0 +1,36 @@
+// La cuenta de la app: entrar (con su segundo paso), «¿Olvidó su contraseña?», elegir una contraseña nueva, Mi perfil y su
+// seguridad ya vienen hechos en Calcita (@stackcraftmx/calcita/account). Lo ÚNICO de la app es este conector: las llamadas
+// a su backend.
+//
+//   - Sin VITE_API_URL (en .env.local): la DEMOSTRACIÓN, todo en este navegador, para trabajar sin backend.
+//   - Con VITE_API_URL: el backend de verdad. Si sigue el contrato REST de Calcita (las rutas y las respuestas están en el
+//     README de Calcita, «La cuenta completa: conectar su backend»), no hay nada más que hacer. Si alguna ruta o respuesta es
+//     distinta, se cambia solo esa función:
+//
+//       const restConnector = createRestAccountConnector(apiClient, {paths: {session: '/me'}});
+//       export const accountConnector = {...restConnector, signIn: async (credentials) => …};
+import {createRestAccountConnector} from '@stackcraftmx/calcita/account';
+import {createDemoAccountConnector} from '@stackcraftmx/calcita/account-demo';
+import QRCode from 'qrcode';
+
+import {apiClient} from '@/core/apiClient.js';
+
+/** La persona de la demostración (datos inventados): con su correo y cualquier contraseña se entra. */
+export const DEMO_USER = Object.freeze({
+    id: 'user-demo', name: 'Ana Martínez Ruiz', email: 'ana.martinez@ejemplo.com', subtitle: 'Administración', phone: '',
+});
+
+/** Sin dirección del API, la app trabaja con la demostración. */
+export const USES_DEMO_ACCOUNT = !import.meta.env.VITE_API_URL;
+
+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',
+        issuer: '__APP_TITLE__',
+        // el QR que escanea la app autenticadora
+        toQrImageUrl: (otpauthUrl) => QRCode.toDataURL(otpauthUrl, {margin: 1}),
+    })
+    : createRestAccountConnector(apiClient);

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

@@ -0,0 +1,15 @@
+// La petición de la casa para hablar con el backend de verdad (createApiClient de Calcita): manda el idioma, convierte los
+// errores en ApiError (RFC 9457) con su mensaje en el idioma de la persona y reconoce la sesión vencida, en un solo lugar.
+//
+// Hoy los *Api.js de los módulos llaman al servidor de mentira (src/fakeServer). Para conectar el de verdad, cada uno
+// cambia su llamada por una de estas, sin tocar la pantalla:
+//
+//   export const loadContacts = (signal) => apiClient.get('/contacts', {signal});
+//   export const addContact = (values) => apiClient.post('/contacts', values);
+//
+// La dirección del API sale de VITE_API_URL (en .env.local, que no se sube al repo); sin ella, /api del mismo servidor.
+import {createApiClient} from '@stackcraftmx/calcita';
+
+const DEFAULT_API_URL = '/api';
+
+export const apiClient = createApiClient({baseUrl: import.meta.env.VITE_API_URL ?? DEFAULT_API_URL});

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

@@ -0,0 +1,11 @@
+// Las rutas que conocen varios módulos (la barra, la guardia de la sesión, «Mi perfil»). Las de un solo módulo viven en su
+// routes.js.
+export const APP_PATHS = Object.freeze({
+    home: '/',
+//#if auth
+    signIn: '/sign-in',
+    forgotPassword: '/forgot-password',
+    resetPassword: '/reset-password',
+    profile: '/profile',
+//#endif
+});

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

@@ -0,0 +1,9 @@
+// La puerta de core: lo que comparten dos o más módulos. Desde afuera se importa de aquí (@/core); adentro de core, por
+// ruta. Core no importa módulos ni app/: si algo lo usan dos módulos, sube aquí.
+export {APP_PATHS} from '@/core/appPaths.js';
+export {AppLogo} from '@/core/AppLogo.jsx';
+export {ROUTER_BASENAME, publicUrlOf} from '@/core/publicPaths.js';
+export {apiClient} from '@/core/apiClient.js';
+//#if auth
+export {DEMO_USER, USES_DEMO_ACCOUNT, accountConnector} from '@/core/accountConnector.js';
+//#endif

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

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

package/cli/templates/project/src/fakeServer/networkDelay.js.tpl

@@ -0,0 +1,40 @@
+// La espera de una petición de verdad: sin ella, todo llega al instante y no se ven los estados de carga (el esqueleto de
+// la lista, el botón ocupado).
+//
+// Respeta la cancelación (AbortSignal) igual que fetch: si la pantalla se cierra a media carga y cancela su consulta, la
+// espera se corta con un AbortError.
+//
+// Funciones puras, sin React: function (regla de la casa).
+
+/** Lo que tarda una consulta normal del servidor de mentira. */
+export const NETWORK_DELAY_MILLISECONDS = 400;
+
+/**
+ * Espera como si la respuesta viniera de la red.
+ *
+ * @param {number} milliseconds
+ * @param {AbortSignal} [signal]
+ * @returns {Promise<void>} se cumple al terminar la espera; falla con AbortError si la cancelan
+ */
+export function waitLikeNetwork(milliseconds, signal) {
+    return new Promise((resolve, reject) => {
+        const abortError = () => new DOMException('La pantalla canceló la petición', 'AbortError');
+        // guard clause: ya venía cancelada
+        if (signal?.aborted) {
+            reject(abortError());
+            return;
+        }
+
+        const timer = setTimeout(() => {
+            signal?.removeEventListener('abort', cancel);
+            resolve();
+        }, milliseconds);
+
+        function cancel() {
+            clearTimeout(timer);
+            reject(abortError());
+        }
+
+        signal?.addEventListener('abort', cancel, {once: true});
+    });
+}

package/cli/templates/project/src/fakeServer/serverText.js.tpl

@@ -0,0 +1,20 @@
+// Los mensajes del servidor de mentira en el idioma de la app, como los mandaría un backend que lee el idioma de la
+// petición (Accept-Language). Cada servidor de mentira trae sus mensajes junto a su código ({es, en}): no hay una lista
+// central que todos editen.
+//
+// Funciones puras, sin React: function (regla de la casa).
+import {toolkitSettings} from '@stackcraftmx/calcita';
+
+const DEFAULT_LANGUAGE = 'es';
+
+/**
+ * Un mensaje en el idioma activo, con sus {{variables}} puestas.
+ *
+ * @param {Record<string, string>} texts el mismo mensaje en cada idioma: {es: 'Se agregó «{{name}}».', en: '…'}
+ * @param {Record<string, string|number>} [values]
+ * @returns {string}
+ */
+export function serverTextOf(texts, values = {}) {
+    const text = texts[toolkitSettings().language] ?? texts[DEFAULT_LANGUAGE];
+    return text.replace(/\{\{(\w+)\}\}/g, (placeholder, name) => String(values[name] ?? placeholder));
+}

package/cli/templates/project/src/main.jsx.tpl

@@ -0,0 +1,24 @@
+// La entrada de la app: el tema por fuera de todo y el router adentro. Lo demás del framework se conecta en AppProviders
+// (la ruta raíz), porque necesita estar dentro del router.
+import {StrictMode} from 'react';
+import {createRoot} from 'react-dom/client';
+import {RouterProvider} from 'react-router/dom';
+import CssBaseline from '@mui/material/CssBaseline';
+import {ThemeProvider} from '@mui/material/styles';
+import {buildYupLocale} from '@stackcraftmx/calcita/forms';
+
+import {appRouter} from '@/app/appRouter.jsx';
+import {appTheme} from '@/app/appTheme.js';
+
+// los mensajes de yup como llaves de texto, para que salgan en el idioma activo. Una sola vez y antes de armar el primer
+// esquema (por eso los esquemas de los formularios se arman dentro de una función y no al importar su archivo)
+buildYupLocale();
+
+createRoot(document.getElementById('root')).render(
+    <StrictMode>
+        <ThemeProvider theme={appTheme}>
+            <CssBaseline />
+            <RouterProvider router={appRouter} />
+        </ThemeProvider>
+    </StrictMode>,
+);

package/cli/templates/project/src/modules/auth/ForgotPasswordPage.jsx.tpl

@@ -0,0 +1,14 @@
+// «¿Olvidó su contraseña?»: ForgotPasswordScreen de Calcita; lo del servidor sale del conector de la cuenta.
+//
+// Lo renderiza la app: arrow (regla de la casa).
+import {ForgotPasswordScreen} from '@stackcraftmx/calcita/account';
+
+import {APP_PATHS, AppLogo} from '@/core';
+
+export const ForgotPasswordPage = () => (
+    <ForgotPasswordScreen logo={<AppLogo />} signInPath={APP_PATHS.signIn}
+//#if !darkMode
+                          showColorSchemeToggle={false}
+//#endif
+    />
+);

package/cli/templates/project/src/modules/auth/ResetPasswordPage.jsx.tpl

@@ -0,0 +1,15 @@
+// Elegir una contraseña nueva desde el enlace del correo (/reset-password?token=…): ResetPasswordScreen de Calcita; lo del
+// servidor sale del conector de la cuenta. El backend manda en el correo la liga a esta pantalla con su clave.
+//
+// Lo renderiza la app: arrow (regla de la casa).
+import {ResetPasswordScreen} from '@stackcraftmx/calcita/account';
+
+import {APP_PATHS, AppLogo} from '@/core';
+
+export const ResetPasswordPage = () => (
+    <ResetPasswordScreen logo={<AppLogo />} signInPath={APP_PATHS.signIn} forgotPasswordPath={APP_PATHS.forgotPassword}
+//#if !darkMode
+                         showColorSchemeToggle={false}
+//#endif
+    />
+);

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

@@ -0,0 +1,29 @@
+// Iniciar sesión: SignInScreen de Calcita (la contraseña y, si la cuenta tiene verificación en dos pasos, el segundo paso).
+// Lo del servidor sale del conector de la cuenta (core/accountConnector.js).
+//
+// Mientras la app use la demostración, abajo sale «Entrar con la cuenta de ejemplo»: entra sin escribir nada. Con el
+// backend de verdad (VITE_API_URL) ya no sale.
+//
+// Lo renderiza la app: arrow (regla de la casa).
+import Button from '@mui/material/Button';
+import {useToolkitTranslation} from '@stackcraftmx/calcita';
+import {SignInScreen} from '@stackcraftmx/calcita/account';
+
+import {APP_PATHS, AppLogo, DEMO_USER, USES_DEMO_ACCOUNT} from '@/core';
+
+// la demostración no revisa contraseñas: cualquiera sirve para la persona de ejemplo
+const DEMO_PASSWORD = 'demo';
+
+/** El botón de la demostración: entra por el mismo camino del formulario (y el mismo segundo paso). */
+const DemoSignInButton = ({signIn}) => {
+    const {t} = useToolkitTranslation('authScreens');
+    return <Button variant="outlined" fullWidth onClick={() => signIn({email: DEMO_USER.email, password: DEMO_PASSWORD})}>{t('demo')}</Button>;
+};
+
+export const SignInPage = () => (
+    <SignInScreen logo={<AppLogo />} forgotPasswordPath={APP_PATHS.forgotPassword}
+//#if !darkMode
+                  showColorSchemeToggle={false}
+//#endif
+                  footer={USES_DEMO_ACCOUNT ? ({signIn}) => <DemoSignInButton signIn={signIn} /> : undefined} />
+);

package/cli/templates/project/src/modules/auth/authTexts.js.tpl

@@ -0,0 +1,6 @@
+// Los textos propios de las pantallas de entrar (namespace authScreens). Los de las pantallas (títulos, campos, segundo
+// paso) ya vienen en Calcita; para cambiar uno, se escribe aquí con su misma llave en su namespace (auth, account…).
+export const authTexts = {
+    es: {authScreens: {demo: 'Entrar con la cuenta de ejemplo'}},
+    en: {authScreens: {demo: 'Sign in with the sample account'}},
+};

package/cli/templates/project/src/modules/auth/routes.js.tpl

@@ -0,0 +1,11 @@
+// Las pantallas de entrar: van FUERA del marco (publicRoutes), porque quien llega aquí todavía no tiene sesión.
+import {APP_PATHS} from '@/core';
+
+export const routes = [];
+
+// lazy: cada pantalla se descarga hasta que alguien la abre
+export const publicRoutes = [
+    {path: APP_PATHS.signIn, lazy: async () => ({Component: (await import('@/modules/auth/SignInPage.jsx')).SignInPage})},
+    {path: APP_PATHS.forgotPassword, lazy: async () => ({Component: (await import('@/modules/auth/ForgotPasswordPage.jsx')).ForgotPasswordPage})},
+    {path: APP_PATHS.resetPassword, lazy: async () => ({Component: (await import('@/modules/auth/ResetPasswordPage.jsx')).ResetPasswordPage})},
+];