@acvl/mobile-components 0.0.0-stage → 0.0.2

package/src/pantallas/PantallaDeFicha.tsx

@@ -0,0 +1,115 @@
+import React from "react";
+import { ActivityIndicator, RefreshControl, ScrollView, View } from "react-native";
+import { useSafeAreaInsets } from "react-native-safe-area-context";
+import type { AccionDelEncabezado } from "../componentes/AccionesDelEncabezado";
+import BotonGrande from "../componentes/BotonGrande";
+import CabeceraEmpujada from "../componentes/CabeceraEmpujada";
+import EstadoVacio from "../componentes/EstadoVacio";
+import { crearEstilos, usePaleta } from "../tema";
+
+/** Lo que la ficha lee de un `use…Query` de RTK Query. */
+interface ConsultaDeFicha {
+    isLoading: boolean;
+    isError: boolean;
+    isFetching: boolean;
+    refetch: () => unknown;
+    error?: unknown;
+}
+
+const esNoEncontrado = (error: unknown) =>
+    typeof error === "object" && error !== null && "status" in error && error.status === 404;
+
+/**
+ * Una ficha de solo lectura (un viaje, un tracto, un cliente): la cabecera con atrás, y lo suyo en
+ * un scroll que se refresca jalando hacia abajo. Mientras carga, o si falla, lo dice en vez de
+ * pintar vacía.
+ *
+ * `children` sólo se pinta con datos: quien la usa no tiene que preguntar si ya llegaron.
+ */
+export default function PantallaDeFicha({
+    eyebrow,
+    titulo,
+    consulta,
+    hayDatos,
+    acciones,
+    estado,
+    encima,
+    children,
+}: {
+    eyebrow: string;
+    titulo: string;
+    /** El estado de la ficha bajo su título (un `Chip`); sólo con datos. */
+    estado?: React.ReactNode;
+    /** Las acciones de la ficha, en su encabezado; sólo se ofrecen con datos. */
+    acciones?: AccionDelEncabezado[];
+    /**
+     * Lo que va encima de la ficha y no dentro de su scroll: sus hojas inferiores
+     * (`HojaInferior`) y diálogos. Sólo con datos.
+     */
+    encima?: React.ReactNode;
+    consulta: ConsultaDeFicha;
+    hayDatos: boolean;
+    children: React.ReactNode;
+}) {
+    const c = usePaleta();
+    const styles = useStyles();
+    const insets = useSafeAreaInsets();
+
+    let cuerpo: React.ReactNode;
+    if (consulta.isLoading) {
+        cuerpo = <ActivityIndicator color={c.primary} size="large" style={styles.cargando} />;
+    } else if (!hayDatos) {
+        cuerpo = esNoEncontrado(consulta.error) ? (
+            <EstadoVacio
+                icono="file-hidden"
+                titulo="No existe"
+                texto="Puede que lo hayan borrado, o que no tengas permiso de verlo."
+            />
+        ) : (
+            <EstadoVacio
+                icono="cloud-off-outline"
+                titulo="No se pudo cargar"
+                texto="Revisa tu señal e intenta de nuevo."
+            >
+                <BotonGrande icono="refresh" onPress={() => consulta.refetch()}>
+                    Reintentar
+                </BotonGrande>
+            </EstadoVacio>
+        );
+    } else {
+        cuerpo = (
+            <ScrollView
+                contentContainerStyle={[styles.contenido, { paddingBottom: insets.bottom + 24 }]}
+                refreshControl={
+                    <RefreshControl
+                        refreshing={consulta.isFetching && !consulta.isLoading}
+                        onRefresh={() => consulta.refetch()}
+                        colors={[c.primary]}
+                        progressBackgroundColor={c.superficie}
+                    />
+                }
+            >
+                {children}
+            </ScrollView>
+        );
+    }
+
+    return (
+        <View style={styles.root}>
+            <CabeceraEmpujada
+                eyebrow={eyebrow}
+                titulo={titulo}
+                acciones={hayDatos ? acciones : undefined}
+                estado={hayDatos ? estado : undefined}
+            />
+            {cuerpo}
+            {hayDatos ? encima : null}
+        </View>
+    );
+}
+
+const useStyles = crearEstilos((c) => ({
+    root: { flex: 1, backgroundColor: c.fondo },
+    cargando: { marginTop: 40 },
+    contenido: { padding: 16, gap: 20 },
+}));

package/src/pantallas/PantallaDeHistorial.tsx

@@ -0,0 +1,293 @@
+import MaterialCommunityIcons from "@expo/vector-icons/MaterialCommunityIcons";
+import React from "react";
+import { ActivityIndicator, Pressable, RefreshControl, ScrollView, View } from "react-native";
+import { useSafeAreaInsets } from "react-native-safe-area-context";
+import BotonGrande from "../componentes/BotonGrande";
+import CabeceraEmpujada from "../componentes/CabeceraEmpujada";
+import EstadoVacio from "../componentes/EstadoVacio";
+import Tarjeta from "../componentes/Tarjeta";
+import { crearEstilos, renglon, tipografia, usePaleta, type Paleta } from "../tema";
+import { Text } from "../texto";
+
+/**
+ * Un movimiento de la bitácora de un registro, como lo responde cualquier endpoint `historial/`
+ * de los backends de ACV (`BaseHistorySerializer`): el registro **entero** como quedó, con quién,
+ * cuándo y qué campos cambiaron.
+ */
+export interface EventoDeHistorial {
+    /** Ya redactado por el backend: «Actualización - Concepto de Orden de envío». */
+    history_type: string;
+    /** El nombre completo de quien lo hizo; nulo si lo movió el sistema. */
+    history_user: string | null;
+    /** ISO en UTC. */
+    history_date: string;
+    /** Los que cambiaron en este paso; nulo en la creación, que no tiene contra qué compararse. */
+    campos_con_cambios: string[] | null;
+    [campo: string]: unknown;
+}
+
+/**
+ * Lo que devuelve cualquier endpoint `historial/`: la línea de tiempo, del más nuevo al más viejo,
+ * y aparte cómo se llama cada campo. Las etiquetas son además el filtro de qué se pinta: un campo
+ * sin etiqueta es de los internos de la bitácora.
+ */
+export interface Historial {
+    history: EventoDeHistorial[];
+    labels: Record<string, string>;
+}
+
+type NombreDeIcono = React.ComponentProps<typeof MaterialCommunityIcons>["name"];
+
+/**
+ * Cómo se pinta cada tipo de movimiento. El backend manda la acción ya redactada, así que el icono
+ * y el color salen del prefijo.
+ */
+const TIPOS: { prefijo: string; icono: NombreDeIcono; colores: (c: Paleta) => Colores }[] = [
+    { prefijo: "Creación", icono: "plus-circle-outline", colores: (c) => c.exito },
+    { prefijo: "Actualización", icono: "pencil-outline", colores: (c) => c.info },
+    { prefijo: "Eliminación", icono: "minus-circle-outline", colores: (c) => c.error },
+];
+type Colores = { fondo: string; tinta: string };
+
+const pintaDe = (c: Paleta, tipo: string) => {
+    const t = TIPOS.find((x) => tipo.startsWith(x.prefijo));
+    return t
+        ? { icono: t.icono, ...t.colores(c) }
+        : { icono: "history" as NombreDeIcono, fondo: c.superficieTenue, tinta: c.secondary };
+};
+
+/** Parte «Acción - Modelo» en sus dos mitades; sin guion, todo es el encabezado. */
+const partirTipo = (tipo: string) => {
+    const corte = tipo.indexOf(" - ");
+    if (corte === -1) return { accion: "", modelo: tipo };
+    return { accion: tipo.slice(0, corte), modelo: tipo.slice(corte + 3) };
+};
+
+/** El valor de un campo tal como viene de la bitácora, listo para pintarse. */
+const formatear = (valor: unknown): string => {
+    if (valor === null || valor === undefined || valor === "") return "—";
+    if (typeof valor === "boolean") return valor ? "Sí" : "No";
+    if (Array.isArray(valor)) return valor.length ? valor.join(", ") : "—";
+    if (typeof valor === "object") return JSON.stringify(valor);
+    return String(valor);
+};
+
+/** La fecha y hora del movimiento, en la hora del teléfono. */
+const fechaHora = (iso: string) => {
+    const fecha = new Date(iso);
+    return Number.isNaN(fecha.getTime())
+        ? "—"
+        : fecha.toLocaleString("es-MX", {
+              day: "2-digit",
+              month: "short",
+              year: "numeric",
+              hour: "2-digit",
+              minute: "2-digit",
+          });
+};
+
+/**
+ * Un movimiento.
+ *
+ * De entrada enseña sólo lo que cambió en ese paso: el evento trae el registro entero como quedó, y
+ * en un teléfono treinta campos por tarjeta esconden el que importa. El resto está a un toque, que
+ * es donde se va a buscar el dato que no se movió.
+ */
+export function TarjetaDeEvento({
+    evento,
+    labels,
+}: {
+    evento: EventoDeHistorial;
+    labels: Record<string, string>;
+}) {
+    const c = usePaleta();
+    const styles = useStyles();
+    const [abierto, setAbierto] = React.useState(false);
+
+    const { accion, modelo } = partirTipo(evento.history_type);
+    const pinta = pintaDe(c, evento.history_type);
+
+    // Las etiquetas mandan qué se pinta y en qué orden.
+    const campos = Object.keys(labels).filter((campo) => campo in evento);
+    const cambiados = evento.campos_con_cambios;
+    const visibles = abierto ? campos : campos.filter((campo) => cambiados?.includes(campo));
+
+    return (
+        <Tarjeta style={styles.evento}>
+            <View style={styles.cabecera}>
+                <View style={[styles.icono, { backgroundColor: pinta.fondo }]}>
+                    <MaterialCommunityIcons name={pinta.icono} size={20} color={pinta.tinta} />
+                </View>
+                <View style={styles.flex}>
+                    <Text style={styles.titulo}>{modelo}</Text>
+                    <Text style={styles.linea}>
+                        {[accion, evento.history_user || "Sistema"].filter(Boolean).join(" · ")}
+                    </Text>
+                    <Text style={styles.linea}>{fechaHora(evento.history_date)}</Text>
+                </View>
+            </View>
+
+            {/* Un arreglo vacío es «se guardó sin mover nada»; nulo es la creación, que no lista
+                cambios. */}
+            {!abierto && cambiados?.length === 0 ? (
+                <Text style={styles.sinCambios}>Sin cambios en los campos.</Text>
+            ) : null}
+
+            {visibles.map((campo) => {
+                const cambiado = Boolean(cambiados?.includes(campo));
+                return (
+                    <View key={campo} style={[styles.dato, cambiado && styles.datoCambiado]}>
+                        <Text style={[styles.etiqueta, cambiado && styles.etiquetaCambiada]}>
+                            {labels[campo]}
+                        </Text>
+                        <Text style={styles.valor}>{formatear(evento[campo])}</Text>
+                    </View>
+                );
+            })}
+
+            {campos.length > 0 ? (
+                <Pressable
+                    onPress={() => setAbierto((previo) => !previo)}
+                    accessibilityRole="button"
+                    hitSlop={8}
+                    style={({ pressed }) => [styles.alternar, pressed && styles.presionada]}
+                >
+                    <Text style={styles.alternarTexto}>
+                        {abierto
+                            ? "Ocultar campos"
+                            : cambiados?.length
+                              ? "Ver todos los campos"
+                              : "Ver los campos"}
+                    </Text>
+                    <MaterialCommunityIcons
+                        name={abierto ? "chevron-up" : "chevron-down"}
+                        size={22}
+                        color={c.primary}
+                    />
+                </Pressable>
+            ) : null}
+        </Tarjeta>
+    );
+}
+
+/** Lo que la pantalla lee de un `use…Query` de RTK Query. */
+interface ConsultaDeHistorial {
+    data?: Historial;
+    isLoading: boolean;
+    isFetching: boolean;
+    isError: boolean;
+    refetch: () => unknown;
+}
+
+/**
+ * La bitácora de un registro: quién lo movió, cuándo y qué le cambió. Es el panel de historial del
+ * portal, que allá se acopla al costado de la ficha; en el teléfono no hay costado, así que es una
+ * pantalla empujada a la que se llega desde las acciones de la ficha.
+ *
+ * Quien la usa pone la consulta (de dónde se pide, con su permiso). Conviene pedirla con
+ * `refetchOnMountOrArgChange`: se abre justo después de mover algo, y servir la caché enseñaría un
+ * historial sin el movimiento que se viene a comprobar.
+ *
+ * En varios registros el backend mezcla en una sola línea de tiempo el registro y lo que cuelga de
+ * él (una orden con sus conceptos, un embarque con su transporte); por eso cada tarjeta dice de qué
+ * registro habla.
+ */
+export default function PantallaDeHistorial({
+    eyebrow,
+    consulta,
+}: {
+    /** De qué registro es: «Recibo R-0012». */
+    eyebrow: string;
+    consulta: ConsultaDeHistorial;
+}) {
+    const c = usePaleta();
+    const styles = useStyles();
+    const insets = useSafeAreaInsets();
+    const { data, isLoading, isFetching, isError, refetch } = consulta;
+    const eventos = data?.history ?? [];
+
+    return (
+        <View style={styles.root}>
+            <CabeceraEmpujada eyebrow={eyebrow} titulo="Historial" />
+            {/* El error sólo se queda con la pantalla cuando no hay nada que enseñar: un refresco
+                que falla no debe borrar el historial que ya se estaba leyendo. */}
+            {isError && !data ? (
+                <EstadoVacio
+                    icono="cloud-off-outline"
+                    titulo="No se pudo cargar el historial"
+                    texto="Revisa tu señal e intenta de nuevo."
+                >
+                    <BotonGrande icono="refresh" modo="contorno" onPress={() => refetch()}>
+                        Reintentar
+                    </BotonGrande>
+                </EstadoVacio>
+            ) : isLoading ? (
+                <ActivityIndicator color={c.primary} style={styles.cargando} />
+            ) : (
+                <ScrollView
+                    contentContainerStyle={[
+                        styles.contenido,
+                        { paddingBottom: insets.bottom + 24 },
+                    ]}
+                    refreshControl={
+                        <RefreshControl
+                            refreshing={isFetching}
+                            onRefresh={() => refetch()}
+                            tintColor={c.primary}
+                            colors={[c.primary]}
+                            progressBackgroundColor={c.superficie}
+                        />
+                    }
+                >
+                    {eventos.length === 0 ? (
+                        <EstadoVacio icono="history" titulo="Sin movimientos registrados" />
+                    ) : (
+                        eventos.map((evento, indice) => (
+                            // El backend no da una llave por evento (mezcla modelos con ids que se
+                            // repiten); el índice sirve porque la lista se reemplaza entera.
+                            <TarjetaDeEvento
+                                key={indice}
+                                evento={evento}
+                                labels={data?.labels ?? {}}
+                            />
+                        ))
+                    )}
+                </ScrollView>
+            )}
+        </View>
+    );
+}
+
+const useStyles = crearEstilos((c) => ({
+    root: { flex: 1, backgroundColor: c.fondo },
+    cargando: { marginTop: 40 },
+    contenido: { padding: 16, gap: 12 },
+    flex: { flex: 1 },
+    evento: { gap: 10 },
+    cabecera: { flexDirection: "row", alignItems: "flex-start", gap: 12 },
+    icono: {
+        width: 36,
+        height: 36,
+        borderRadius: 18,
+        alignItems: "center",
+        justifyContent: "center",
+    },
+    titulo: { ...renglon(tipografia.cuerpo), fontWeight: "800" },
+    linea: { ...renglon(tipografia.secundario), color: c.secondary },
+    sinCambios: { ...renglon(tipografia.secundario), color: c.secondary, fontStyle: "italic" },
+    // Un campo por renglón: con la letra grande, dos columnas parten los valores a media palabra.
+    dato: { borderRadius: 10, paddingVertical: 6, paddingHorizontal: 10, gap: 2 },
+    datoCambiado: { backgroundColor: c.primaryWash },
+    etiqueta: {
+        ...renglon(tipografia.etiqueta),
+        fontWeight: "800",
+        color: c.secondary,
+        textTransform: "uppercase",
+        letterSpacing: 0.6,
+    },
+    etiquetaCambiada: { color: c.primary },
+    valor: { ...renglon(tipografia.secundario), fontWeight: "600" },
+    alternar: { flexDirection: "row", alignItems: "center", gap: 2, alignSelf: "flex-start" },
+    alternarTexto: { ...renglon(tipografia.secundario), fontWeight: "700", color: c.primary },
+    presionada: { opacity: 0.6 },
+}));

package/src/pantallas/PantallaDePerfil.tsx

@@ -0,0 +1,126 @@
+import React from "react";
+import { ScrollView, View } from "react-native";
+import { Avatar, Button, Card } from "react-native-paper";
+import { useSafeAreaInsets } from "react-native-safe-area-context";
+import CabeceraEmpujada from "../componentes/CabeceraEmpujada";
+import ContenidoDePantalla from "../componentes/ContenidoDePantalla";
+import Pestanas, { type Pestana } from "../componentes/Pestanas";
+import {
+    crearEstilos,
+    renglon,
+    tipografia,
+    usePreferenciaDeTema,
+    type PreferenciaDeTema,
+} from "../tema";
+import { Text } from "../texto";
+
+/**
+ * La apariencia: **igual que el teléfono** por omisión, o fija. Tres opciones y no un interruptor de
+ * «modo oscuro», como el del portal: con un interruptor, quien lo toca una vez ya no vuelve a seguir
+ * al teléfono.
+ */
+const APARIENCIAS: Pestana<PreferenciaDeTema>[] = [
+    { key: "sistema", label: "Teléfono", icono: "cellphone" },
+    { key: "claro", label: "Claro", icono: "white-balance-sunny" },
+    { key: "oscuro", label: "Oscuro", icono: "weather-night" },
+];
+
+/**
+ * El perfil de una app, igual en todas: quién entró, cómo se ve la app y cerrar sesión. Va
+ * empujado encima de las pestañas (lo abre el avatar del header). Necesita `ProveedorDeTema`.
+ *
+ * Lo propio de cada app va por props: quién es, qué pasa al cerrar sesión (avisar si hay envíos
+ * pendientes, confirmar) y, en `children`, lo que vaya al final (la versión instalada).
+ */
+export default function PantallaDePerfil({
+    rotulo,
+    nombre,
+    subtitulo,
+    onCerrarSesion,
+    saliendo = false,
+    children,
+}: {
+    /** Qué tipo de sesión es («Operador», «Guardia de caseta»): el rótulo de la cabecera. */
+    rotulo: string;
+    nombre?: string | null;
+    /** El usuario, el número de empleado. */
+    subtitulo?: string | null;
+    onCerrarSesion: () => void;
+    saliendo?: boolean;
+    children?: React.ReactNode;
+}) {
+    const styles = useStyles();
+    const [tema, setTema] = usePreferenciaDeTema();
+    const insets = useSafeAreaInsets();
+
+    return (
+        <View style={styles.root}>
+            <CabeceraEmpujada eyebrow={rotulo} titulo="Perfil" />
+
+            <ContenidoDePantalla paddingBottom={insets.bottom + 20}>
+                <ScrollView
+                    contentContainerStyle={styles.contenido}
+                    keyboardShouldPersistTaps="handled"
+                >
+                    <Card mode={"outlined"} style={styles.card}>
+                        {/* Paper recorta título y subtítulo a un renglón por omisión: un nombre
+                            largo con la letra al 180% se perdía. */}
+                        <Card.Title
+                            title={nombre || "N/A"}
+                            titleVariant={"titleLarge"}
+                            titleStyle={{ fontWeight: "bold" }}
+                            titleNumberOfLines={0}
+                            subtitleNumberOfLines={0}
+                            subtitleStyle={renglon(tipografia.secundario)}
+                            subtitle={subtitulo || "N/A"}
+                            subtitleVariant={"bodySmall"}
+                            left={(props) => (
+                                <Avatar.Text
+                                    {...props}
+                                    label={(nombre || "?").charAt(0).toUpperCase()}
+                                    color="#ffffff"
+                                />
+                            )}
+                        />
+                    </Card>
+
+                    <View style={styles.apariencia}>
+                        <Text style={styles.rotulo}>Apariencia</Text>
+                        <Pestanas pestanas={APARIENCIAS} activa={tema} onSelect={setTema} />
+                    </View>
+
+                    {/* El tope de ancho vive en este View y no en el Button: el Surface de
+                        Paper reparte el estilo en dos capas anidadas en iOS y `maxWidth` cae
+                        en la de adentro, que queda pegada a la izquierda. */}
+                    <View style={styles.acciones}>
+                        <Button
+                            onPress={onCerrarSesion}
+                            mode={"contained"}
+                            icon={"logout"}
+                            loading={saliendo}
+                            disabled={saliendo}
+                        >
+                            Cerrar sesión
+                        </Button>
+                    </View>
+                    {children}
+                </ScrollView>
+            </ContenidoDePantalla>
+        </View>
+    );
+}
+
+const useStyles = crearEstilos((c) => ({
+    root: { flex: 1, backgroundColor: c.fondo },
+    contenido: { gap: 20, alignItems: "center" },
+    card: { width: "100%", backgroundColor: c.superficie, borderColor: c.secondaryLighter },
+    acciones: { width: "100%", maxWidth: 300, gap: 20 },
+    apariencia: { width: "100%", gap: 8 },
+    rotulo: {
+        ...renglon(tipografia.etiqueta),
+        fontWeight: "800",
+        color: c.secondary,
+        textTransform: "uppercase",
+        letterSpacing: 0.8,
+    },
+}));

package/src/tema/ProveedorDeTema.tsx

@@ -0,0 +1,150 @@
+import { StatusBar } from "expo-status-bar";
+import React from "react";
+import { Appearance } from "react-native";
+import { configureFonts, MD3DarkTheme, MD3LightTheme, PaperProvider } from "react-native-paper";
+import { useEsOscuro, useFondoDeLaRaiz } from "./estilos";
+import { fontFamily } from "./fuentes";
+import { PALETA_CLARA, PALETA_OSCURA, type Paleta } from "./paleta";
+
+/**
+ * Cómo quiere ver la app quien la usa: **igual que el teléfono** (por omisión), o siempre clara, o
+ * siempre oscura. Es del teléfono y no de la cuenta: sobrevive al cerrar sesión.
+ */
+export type PreferenciaDeTema = "sistema" | "claro" | "oscuro";
+
+const PREFERENCIAS: readonly PreferenciaDeTema[] = ["sistema", "claro", "oscuro"];
+
+/**
+ * Dónde guarda cada app la preferencia (SecureStore, AsyncStorage…). `leer` puede devolver
+ * cualquier cosa: lo que no sea una preferencia válida cuenta como `"sistema"`.
+ */
+export interface AlmacenDelTema {
+    leer: () => Promise<string | null | undefined>;
+    guardar: (preferencia: PreferenciaDeTema) => Promise<unknown>;
+}
+
+/**
+ * Pone la preferencia **en toda la app nativa** (`Appearance.setColorScheme`), no sólo en lo que
+ * pinta React: así `useColorScheme` ya contesta la elegida, y lo nativo —un mapa de Google, el
+ * selector de fecha, la barra de estado— la sigue sin que nadie se la pase. «Igual que el teléfono»
+ * es quitar la imposición.
+ */
+const aplicar = (preferencia: PreferenciaDeTema) =>
+    Appearance.setColorScheme(
+        preferencia === "claro" ? "light" : preferencia === "oscuro" ? "dark" : "unspecified",
+    );
+
+// La escala tipográfica de Paper trae `System` en iOS y `sans-serif` en Android; en Android se
+// cambia la familia por Inter y se conservan tamaños y pesos de cada variante. Los `Text` de
+// React Native no leen el tema: esos van por `texto.tsx`.
+const fonts = fontFamily ? configureFonts({ config: { fontFamily } }) : MD3LightTheme.fonts;
+
+/**
+ * El tema de Paper de cada modo, con los colores de la paleta: los componentes de Paper (Card,
+ * Button, Avatar, Menu) no leen la paleta, leen esto.
+ */
+const temaDePaper = (base: typeof MD3LightTheme, c: Paleta) => ({
+    ...base,
+    fonts,
+    colors: {
+        ...base.colors,
+        primary: c.primary,
+        onPrimary: c.sobrePrimario,
+        primaryLight: c.primaryLight,
+        primaryLighter: c.primaryLighter,
+        primaryDark: c.primaryDark,
+
+        secondary: c.secondary,
+        secondaryLight: c.secondaryLight,
+        secondaryLighter: c.secondaryLighter,
+        secondaryDark: c.secondaryDark,
+
+        background: c.fondo,
+        surface: c.superficie,
+        onSurface: c.texto,
+        outline: c.secondaryLighter,
+        surfacePrimary: c.superficie,
+    },
+});
+
+const TEMA_CLARO = temaDePaper(MD3LightTheme, PALETA_CLARA);
+const TEMA_OSCURO = temaDePaper(MD3DarkTheme, PALETA_OSCURA);
+
+type ContextoDelTema = [PreferenciaDeTema, (preferencia: PreferenciaDeTema) => void];
+
+const Contexto = React.createContext<ContextoDelTema | null>(null);
+
+/**
+ * El tema de la app: lee la preferencia guardada, se la impone a lo nativo, y da el tema de Paper,
+ * la barra de estado y el fondo de la raíz de ahora. Va en el layout raíz, por encima de todo lo
+ * que pinta.
+ *
+ * **No pinta nada hasta leer la preferencia**: así no se asoma el claro un momento en quien eligió
+ * el oscuro. Leerla es una consulta local, no se nota.
+ */
+export function ProveedorDeTema({
+    almacen,
+    children,
+}: {
+    /** Sin almacén, la preferencia dura lo que dure la app abierta. */
+    almacen?: AlmacenDelTema;
+    children: React.ReactNode;
+}) {
+    const [preferencia, setPreferencia] = React.useState<PreferenciaDeTema | null>(
+        almacen ? null : "sistema",
+    );
+    const oscuro = useEsOscuro();
+    useFondoDeLaRaiz((oscuro ? PALETA_OSCURA : PALETA_CLARA).fondo);
+
+    React.useEffect(() => {
+        if (!almacen) return;
+        let vigente = true;
+        almacen
+            .leer()
+            .catch(() => null)
+            .then((guardada) => {
+                if (!vigente) return;
+                const valida = PREFERENCIAS.find((p) => p === guardada) ?? "sistema";
+                aplicar(valida);
+                setPreferencia(valida);
+            });
+        return () => {
+            vigente = false;
+        };
+        // Se lee una sola vez, al arrancar: un almacén nuevo en cada render no la vuelve a leer.
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, []);
+
+    const valor = React.useMemo<ContextoDelTema | null>(
+        () =>
+            preferencia === null
+                ? null
+                : [
+                      preferencia,
+                      (nueva) => {
+                          aplicar(nueva);
+                          setPreferencia(nueva);
+                          almacen?.guardar(nueva).catch(() => {});
+                      },
+                  ],
+        [preferencia, almacen],
+    );
+
+    if (!valor) return null;
+
+    return (
+        <Contexto.Provider value={valor}>
+            <PaperProvider theme={oscuro ? TEMA_OSCURO : TEMA_CLARO}>
+                <StatusBar style={oscuro ? "light" : "dark"} />
+                {children}
+            </PaperProvider>
+        </Contexto.Provider>
+    );
+}
+
+/** La preferencia del tema y cómo cambiarla (el perfil). Sólo dentro de `ProveedorDeTema`. */
+export function usePreferenciaDeTema(): ContextoDelTema {
+    const valor = React.useContext(Contexto);
+    if (!valor) throw new Error("usePreferenciaDeTema va dentro de <ProveedorDeTema>.");
+    return valor;
+}