pagetop/src/core/theme/definition.rs
Manuel Cillero 70744a51a5 ✨ (auth): Añade idioma y tema preferidos al usuario
- CurrentUser pasa de enum a struct con `id` opcional (anónimo = None) y
  preferencias de idioma, zona horaria y tema validadas en `with_*()`.
- `RequestLocale` tiene en cuenta el idioma preferido del usuario, y
  Context usa su tema si lo tiene (`default_theme()` en otro caso).
- Nuevos componentes `form::SelectLanguage`, `form::SelectTheme` y
  `form::SelectTimezone`, con `Timezone::supported_by_region()` para
  listar y validar las zonas IANA ofrecidas.
2026-10-04 23:09:07 +02:00

519 lines
24 KiB
Rust

use crate::async_trait;
use crate::base::component::{Html, Intro, layout};
use crate::core::component::{ChildOp, Component, ComponentError, ComponentRender};
use crate::core::component::{Context, Contextual};
use crate::core::extension::Extension;
use crate::core::theme::{Breakpoint, BreakpointEntry, CoreRegions, Intent};
use crate::global;
use crate::html::{Markup, html};
use crate::locale::Lc;
use crate::response::Page;
use crate::web::http::StatusCode;
/// Interfaz común que debe implementar cualquier tema de PageTop.
///
/// Un tema es una [`Extension`](crate::core::extension::Extension) que define el aspecto general de
/// las páginas: cómo se renderiza el `<head>`, cómo se presenta el `<body>` usando plantillas
/// ([`TemplateName`](crate::core::theme::TemplateName)) que maquetan regiones
/// ([`RegionName`](crate::core::theme::RegionName)) y qué contenido mostrar en las páginas de
/// error. El contenido de cada región depende del [`Context`](crate::core::component::Context) y de
/// su nombre lógico.
///
/// Todos los métodos de este trait tienen una implementación por defecto, por lo que pueden
/// sobrescribirse selectivamente para crear nuevos temas con comportamientos distintos a los
/// predeterminados.
///
/// El único método **obligatorio** de `Extension` para un tema es [`theme()`](Extension::theme),
/// que debe devolver una referencia al propio tema:
///
/// ```rust,no_run
/// # use pagetop::prelude::*;
/// pub struct MyTheme;
///
/// #[async_trait]
/// impl Extension for MyTheme {
/// fn name(&self) -> Lc {
/// Lc::n("My theme")
/// }
///
/// fn description(&self) -> Lc {
/// Lc::n("A personal theme")
/// }
///
/// fn theme(&self) -> Option<ThemeRef> {
/// Some(&Self)
/// }
/// }
///
/// #[async_trait]
/// impl Theme for MyTheme {}
/// ```
#[async_trait]
pub trait Theme: Extension + Send + Sync {
/// Devuelve el tema padre del que hereda este tema, si existe.
///
/// Un tema hijo delega automáticamente todos los métodos de esta interfaz al tema padre cuando
/// no los sobrescribe.
///
/// La implementación por defecto devuelve `None` (tema sin padre).
///
/// Una referencia circular (un tema acaba siendo padre de sí mismo, directa o transitivamente)
/// no puede descartarse en tiempo de compilación. PageTop la detecta al registrar el tema y
/// aborta el arranque de la aplicación si encuentra una, para evitar bucles infinitos o
/// desbordamientos de pila al usar el tema.
fn parent(&self) -> Option<ThemeRef> {
None
}
/// Traduce un [`Breakpoint`] a su [`BreakpointEntry`] correspondiente, donde se asocia a cada
/// variante su nombre y ancho mínimo *responsive*, *mobile-first*, propios del tema.
///
/// `Breakpoint` no define ningún nombre ni ancho mínimo propios. Será cada tema el que decida
/// cómo se llama cada variante y a qué ancho corresponde (p. ej. `"768px"`) para aplicar en un
/// `@media (min-width: ...)` sin ningún cálculo adicional. La cadena vacía (`""`) en
/// `min_width` indica que la variante no representa ningún ancho mínimo y se aplica siempre.
///
/// **Temas sin puntos de corte.** Devolver `""` como ancho para una variante no la deshabilita,
/// de hecho la regla generada para ese punto de corte se sigue renderizando, pero sin incluirla
/// en un `@media` (ver [`ResponsiveStyles::render()`]). Por tanto, pasa a aplicarse siempre,
/// exactamente igual que si nunca se hubiera pedido ningún punto de corte. Un tema sin diseño
/// *responsive* puede traducir así todas las variantes a `""`; no por eso se vuelve un tema
/// "desktop-first", sino que cada punto de corte pedido pasa a aplicarse siempre, sin ninguna
/// condición de ancho.
///
/// **Temas con menos puntos de corte que variantes.** Dos variantes consecutivas que devuelvan
/// el mismo ancho no vacío se funden en la práctica: ambas generan un `@media (min-width: ...)`
/// idéntico, así que no hay forma de distinguir en CSS "a partir de `Md`" de "a partir de `Lg`"
/// si las dos resuelven, por ejemplo, a `"992px"`. Es la forma correcta de implementar menos
/// puntos de corte reales que las siete variantes de `Breakpoint`: repetir el mismo ancho en
/// las variantes consecutivas que no se quieran distinguir. Por ejemplo, un tema con tres
/// franjas reales (`Xs`, `Md`-`Lg` y `Xl`-`Xxl`-`Xxxl`) devolvería `""` para `Xs`, el mismo
/// ancho para `Md` y `Lg`, y otro ancho mayor, también repetido, para `Xl`, `Xxl` y `Xxxl`.
/// Para que el resultado siga siendo coherente, los anchos deben mantenerse no decrecientes en
/// el orden *mobile-first* (`Xs` a `Xxxl`); repetir un ancho en variantes no consecutivas, o no
/// ordenarlos de menor a mayor, produce puntos de corte confusos o contradictorios, aunque nada
/// en tiempo de compilación ni de ejecución lo impida.
///
/// Normalmente, para resolver el nombre o el ancho *responsive* de un punto de corte no se
/// llamará a este método directamente, sino que se usarán [`Breakpoint::name()`] y
/// [`Breakpoint::min_width()`], respectivamente, a través de [`Context::theme()`].
///
/// [`Breakpoint::name()`]: crate::core::theme::Breakpoint::name
/// [`Breakpoint::min_width()`]: crate::core::theme::Breakpoint::min_width
/// [`Context::theme()`]: crate::core::component::Context::theme
/// [`ResponsiveStyles::render()`]: crate::html::ResponsiveStyles::render
#[rustfmt::skip]
fn breakpoint_entry(&self, bp: Breakpoint) -> BreakpointEntry {
if let Some(parent) = self.parent() {
return parent.breakpoint_entry(bp);
}
use Breakpoint::*;
match bp {
Xs => BreakpointEntry { breakpoint: Xs, name: "xs", min_width: "" },
Sm => BreakpointEntry { breakpoint: Sm, name: "sm", min_width: "576px" },
Md => BreakpointEntry { breakpoint: Md, name: "md", min_width: "768px" },
Lg => BreakpointEntry { breakpoint: Lg, name: "lg", min_width: "992px" },
Xl => BreakpointEntry { breakpoint: Xl, name: "xl", min_width: "1200px" },
Xxl => BreakpointEntry { breakpoint: Xxl, name: "xxl", min_width: "1400px" },
Xxxl => BreakpointEntry { breakpoint: Xxxl, name: "xxxl", min_width: "1920px" },
}
}
/// Traduce una [`Intent`] al nombre de color de la paleta propia del tema.
///
/// `Intent` no define ninguna cadena propia. Cada tema decide qué nombre le corresponde a cada
/// variante en su paleta (p. ej. un tema basado en Bootstrap traduce `Severe` a `"danger"`).
/// Los componentes que generan clases CSS a partir de una `Intent` (`Button`, `Badge`,
/// `Dropdown`, etc.) no llaman a este método directamente en su `setup()`, usan mejor
/// [`Intent::color()`] como la forma más sencilla de obtener este mismo valor a través de
/// [`Context::theme()`], para que la clase resultante ya nazca en la paleta del tema activo.
///
/// La implementación por defecto devuelve el vocabulario semántico propio de PageTop
/// (`"primary"`, `"severe"`, etc.), que actúa como paleta base cuando ningún tema la
/// sobrescribe.
///
/// [`Intent::color()`]: crate::core::theme::Intent::color
/// [`Context::theme()`]: crate::core::component::Context::theme
#[rustfmt::skip]
fn intent_color(&self, intent: Intent) -> &'static str {
if let Some(parent) = self.parent() {
return parent.intent_color(intent);
}
match intent {
Intent::Primary => "primary",
Intent::Neutral => "neutral",
Intent::Info => "info",
Intent::Success => "success",
Intent::Warning => "warning",
Intent::Severe => "severe",
}
}
/// Acciones específicas del tema antes de renderizar el `<body>` de la página.
///
/// Es un buen lugar para inicializar o ajustar recursos en función del contexto de la página,
/// por ejemplo:
///
/// - Añadir metadatos o propiedades a la cabecera de la página.
/// - Preparar atributos compartidos.
/// - Registrar *assets* condicionales en el contexto.
///
/// La implementación por defecto no realiza ninguna acción.
#[allow(unused_variables)]
fn before_render_page_body(&self, page: &mut Page) {
if let Some(parent) = self.parent() {
parent.before_render_page_body(page);
}
}
/// Renderiza el contenido del `<body>` de la página.
///
/// La implementación predeterminada delega en la plantilla asociada a la página, obtenida desde
/// su [`Context`](crate::core::component::Context), para componer el `<body>` a partir de las
/// regiones.
///
/// Con la configuración por defecto, la plantilla estándar utiliza las regiones
/// [`CoreRegions::Header`](crate::core::theme::CoreRegions::Header),
/// [`CoreRegions::Aside`](crate::core::theme::CoreRegions::Aside),
/// [`CoreRegions::Content`](crate::core::theme::CoreRegions::Content) y
/// [`CoreRegions::Footer`](crate::core::theme::CoreRegions::Footer) en ese orden.
///
/// Los temas pueden sobrescribir este método para:
///
/// - Forzar una plantilla concreta en determinadas páginas.
/// - Consultar la plantilla de la página y variar la composición según su nombre.
/// - Envolver el contenido en contenedores adicionales.
/// - Implementar lógicas de composición alternativas.
#[inline]
async fn render_page_body(&self, page: &mut Page) -> Markup {
if let Some(parent) = self.parent() {
parent.render_page_body(page).await
} else {
let template = page.template();
layout::Template::of(template).render(page.context()).await
}
}
/// Acciones específicas del tema después de renderizar el `<body>` de la página.
///
/// Se invoca tras la generación del contenido del `<body>`. Es útil para:
///
/// - Ajustar o registrar recursos en función de lo que se haya renderizado.
/// - Realizar *tracing* o recopilar métricas.
/// - Aplicar ajustes finales al estado de la página antes de producir el `<head>` o la
/// respuesta final.
///
/// La implementación por defecto no realiza ninguna acción.
#[allow(unused_variables)]
fn after_render_page_body(&self, page: &mut Page) {
if let Some(parent) = self.parent() {
parent.after_render_page_body(page);
}
}
/// Renderiza el contenido del `<head>` de la página.
///
/// Aunque en una página el `<head>` se encuentra antes del `<body>`, internamente se renderiza
/// después para contar con los ajustes que hayan ido acumulando los componentes. Por ejemplo,
/// permitiría añadir un archivo de iconos sólo si se ha incluido un icono en la página.
///
/// Por defecto incluye:
///
/// - La codificación (`charset="utf-8"`).
/// - El título, usando el título de la página si existe y, en caso contrario, sólo el nombre de
/// la aplicación.
/// - La descripción (`<meta name="description">`), si está definida.
/// - La etiqueta `viewport` básica para diseño adaptable.
/// - Los metadatos (`name`/`content`) y propiedades (`property`/`content`) declarados en la
/// página.
/// - Los *assets* registrados en el contexto de la página.
///
/// Los temas pueden sobrescribir este método para añadir etiquetas adicionales (por ejemplo,
/// *favicons* personalizados, manifest, etiquetas de analítica, etc.).
async fn render_page_head(&self, page: &mut Page) -> Markup {
if let Some(parent) = self.parent() {
return parent.render_page_head(page).await;
}
let viewport = "width=device-width, initial-scale=1, shrink-to-fit=no";
html! {
meta charset="utf-8";
@if let Some(title) = page.title() {
title { (global::SETTINGS.app.name) (" | ") (title) }
} @else {
title { (global::SETTINGS.app.name) }
}
@if let Some(description) = page.description() {
meta name="description" content=(description);
}
meta name="viewport" content=(viewport);
@for (name, content) in page.metadata() {
meta name=(name) content=(content) {}
}
meta http-equiv="X-UA-Compatible" content="IE=edge";
@for (property, content) in page.properties() {
meta property=(property) content=(content) {}
}
(page.context().render_assets())
}
}
/// Permite al tema modificar un componente antes de decidir cómo renderizarlo.
///
/// Este método tiene especial utilidad en los **temas hijo** porque permite ajustar el estado
/// de un componente concreto sin modificar el resto del comportamiento heredado.
///
/// Recibe una referencia mutable al componente (como objeto dinámico [`Component`]) y el
/// contexto de renderizado. Se ejecuta en cada tema de la cadena (hijo > padre > abuelo...), en
/// ese orden, justo antes de que ese mismo nivel decida si renderiza el componente con
/// [`render_component()`](Self::render_component). La implementación por defecto no hace nada.
///
/// Usa la macro [`setup_component!`](crate::setup_component) para mutar por tipo:
///
/// ```rust,ignore
/// fn setup_component(&self, component: &mut dyn Component, cx: &mut Context) {
/// setup_component!(component, {
/// Button => |btn| { btn.add_class("btn-primary"); },
/// });
/// }
/// ```
#[allow(unused_variables)]
fn setup_component(&self, component: &mut dyn Component, cx: &mut Context) {}
/// Permite al tema sobrescribir el renderizado de un componente.
///
/// Este método tiene especial utilidad en los **temas hijo** porque permite sobrescribir el
/// renderizado que el propio componente o el tema padre ofrece para un componente concreto, sin
/// modificar el resto del comportamiento heredado.
///
/// Recibe una referencia compartida al componente (como objeto dinámico [`Component`]), ya con
/// las modificaciones de [`setup_component()`](Self::setup_component) del mismo nivel
/// aplicadas, y el contexto de renderizado. Devuelve:
///
/// - `None` si este tema no sobrescribe el renderizado. Es la implementación por defecto. El
/// sistema continúa con el siguiente tema de la cadena y, si ninguno lo sobrescribe, usa
/// [`Component::prepare()`](crate::core::component::Component::prepare).
/// - `Some(Ok(markup))` con el HTML generado por el tema para el componente.
/// - `Some(Err(e))` si el tema intentó renderizarlo pero falló.
///
/// Usa la macro [`render_component!`](crate::render_component), que devuelve `None` si ningún
/// tipo coincide:
///
/// ```rust,ignore
/// fn render_component(
/// &self,
/// component: &dyn Component,
/// cx: &mut Context,
/// ) -> Option<Result<Markup, ComponentError>> {
/// render_component!(component, {
/// Button => |btn| Ok(html! { button class="btn btn-primary" { (btn.label()) } }),
/// Heading => |h| Ok(html! { h2 class="display-4" { (h.text()) } }),
/// })
/// }
/// ```
#[allow(unused_variables)]
async fn render_component(
&self,
component: &dyn Component,
cx: &mut Context,
) -> Option<Result<Markup, ComponentError>> {
None
}
/// Contenido predefinido para la página de error "*403 - Forbidden*" (acceso denegado).
///
/// Normalmente se renderiza con la plantilla ya activa en la página (por ejemplo
/// [`CoreTemplates::Standard`](crate::core::theme::CoreTemplates::Standard)), para que el
/// usuario no pierda el contexto de navegación del sitio. Los temas pueden sobrescribir este
/// método para personalizar completamente el diseño y el contenido de la página de error.
fn error_403(&self, page: &mut Page) {
if let Some(parent) = self.parent() {
return parent.error_403(page);
}
page.alter_title(Lc::l("error403_title")).alter_child_in(
&CoreRegions::Content,
ChildOp::Prepend(
Html::with(move |cx| {
html! {
div {
h1 { (Lc::l("error403_alert").using(cx)) }
p { (Lc::l("error403_help").using(cx)) }
}
}
})
.into(),
),
);
}
/// Contenido predefinido para la página de error "*404 - Not Found*" (recurso no encontrado).
///
/// Normalmente se renderiza con la plantilla ya activa en la página (por ejemplo
/// [`CoreTemplates::Standard`](crate::core::theme::CoreTemplates::Standard)). Los temas pueden
/// sobrescribir este método para personalizar completamente el diseño y el contenido de la
/// página de error.
fn error_404(&self, page: &mut Page) {
if let Some(parent) = self.parent() {
return parent.error_404(page);
}
page.alter_title(Lc::l("error404_title")).alter_child_in(
&CoreRegions::Content,
ChildOp::Prepend(
Html::with(move |cx| {
html! {
div {
h1 { (Lc::l("error404_alert").using(cx)) }
p { (Lc::l("error404_help").using(cx)) }
}
}
})
.into(),
),
);
}
/// Permite al tema preparar y componer una página de **error fatal controlado**.
///
/// Devuelve explícitamente [`ErrorPage::BadRequest`], [`ErrorPage::InternalError`],
/// [`ErrorPage::ServiceUnavailable`] o [`ErrorPage::GatewayTimeout`], porque algo ha fallado,
/// pero el servidor sigue activo y el tema, el renderizado y el resto de componentes funcionan
/// con normalidad.
///
/// Por defecto, asigna el título al documento (`title`), se renderiza con la plantilla ya
/// activa en la página (normalmente [`CoreTemplates::Standard`]) y muestra un componente
/// [`Intro`] con el código HTTP del error (`code`) y los mensajes proporcionados (`alert` y
/// `help`) como descripción del error.
///
/// Este método no se utiliza en las implementaciones predefinidas de [`Self::error_403()`] ni
/// [`Self::error_404()`], que definen su propio contenido específico.
///
/// Tampoco cubre los **fallos catastróficos** (un `panic!` en un handler, componente o
/// plantilla). Ese caso se intercepta en una última capa que responde con un HTML mínimo y
/// autónomo, sin pasar por el tema ni por el ciclo de renderizado de componentes, porque no es
/// seguro asumir que ese ciclo sigue funcionando tras un `panic!`.
///
/// Los temas pueden sobrescribir este método para personalizar el diseño y el contenido de la
/// página de error.
///
/// [`ErrorPage::BadRequest`]: crate::response::ErrorPage::BadRequest
/// [`ErrorPage::InternalError`]: crate::response::ErrorPage::InternalError
/// [`ErrorPage::ServiceUnavailable`]: crate::response::ErrorPage::ServiceUnavailable
/// [`ErrorPage::GatewayTimeout`]: crate::response::ErrorPage::GatewayTimeout
/// [`CoreTemplates::Standard`]: crate::core::theme::CoreTemplates::Standard
fn error_fatal(&self, page: &mut Page, code: StatusCode, title: Lc, alert: Lc, help: Lc) {
if let Some(parent) = self.parent() {
return parent.error_fatal(page, code, title, alert, help);
}
page.alter_title(title).alter_child_in(
&CoreRegions::Content,
ChildOp::Prepend(
Intro::custom()
.with_title(Lc::l("error_code").with_arg("code", code.to_string()))
.with_slogan(Lc::n(code.to_string()))
.with_child(Html::with(move |cx| {
html! {
h1 { (alert.using(cx)) }
p { (help.using(cx)) }
}
}))
.into(),
),
);
}
}
/// Referencia estática a un tema.
pub type ThemeRef = &'static dyn Theme;
impl std::fmt::Debug for dyn Theme {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
f.write_str(self.short_name())
}
}
// **< setup_component! >***************************************************************************
/// Modifica un componente dentro de [`Theme::setup_component()`].
///
/// Evalúa `$component` contra cada tipo de componente listado en orden. En cuanto encuentra
/// coincidencia, ejecuta el bloque asociado y detiene la evaluación. Si ningún tipo coincide, no
/// hace nada.
///
/// Usa acceso mutable al componente mediante [`downcast_mut`], lo que permite modificar su estado.
///
/// # Ejemplo
///
/// ```rust,ignore
/// fn setup_component(&self, component: &mut dyn Component, cx: &mut Context) {
/// setup_component!(component, { Button => |btn| { btn.add_class("btn-primary"); } });
/// }
/// ```
///
/// El tipo mutado aquí puede además renderizarse en [`Theme::render_component()`] del mismo tema,
/// que se ejecuta a continuación sobre el componente ya mutado.
///
/// [`Theme::setup_component()`]: crate::core::theme::Theme::setup_component
/// [`downcast_mut`]: crate::core::AnyCast::downcast_mut
/// [`Theme::render_component()`]: crate::core::theme::Theme::render_component
#[macro_export]
macro_rules! setup_component {
($component:expr, { $($type:ty => |$var:ident| $body:expr),* $(,)? }) => {
'setup_component: {
$(
if let Some($var) = ($component).downcast_mut::<$type>() {
$body;
break 'setup_component;
}
)*
}
};
}
// **< render_component! >**************************************************************************
/// Sobrescribe el renderizado de componentes en [`Theme::render_component()`].
///
/// Evalúa `$component` contra cada tipo de componente listado en orden. En cuanto encuentra
/// coincidencia, devuelve `Some(Ok(markup))` o `Some(Err(e))` según el resultado de la expresión
/// asociada. Si ningún tipo coincide, devuelve `None` para que el sistema continúe con la cadena de
/// herencia o con el renderizado por defecto del propio componente.
///
/// # Ejemplo
///
/// ```rust,ignore
/// fn render_component(
/// &self,
/// component: &dyn Component,
/// cx: &mut Context,
/// ) -> Option<Result<Markup, ComponentError>> {
/// render_component!(component, {
/// Button => |btn| { Ok(html! { button class="btn btn-primary" { (btn.label()) } }) },
/// Heading => |h| self.render_heading(h, cx),
/// })
/// }
///
/// fn render_heading(&self, h: &Heading, cx: &mut Context) -> Result<Markup, ComponentError> {
/// Ok(html! { h2 class="display-4" { (h.text()) } })
/// }
/// ```
///
/// [`Theme::render_component()`]: crate::core::theme::Theme::render_component
#[macro_export]
macro_rules! render_component {
($component:expr, { $($type:ty => |$var:ident| $body:expr),* $(,)? }) => {
'render_component: {
$(
if let Some($var) = ($component).downcast_ref::<$type>() {
break 'render_component Some($body);
}
)*
None
}
};
}