♻️ (pagetop): Unifica la interfaz de Context y Page

Toda la API de Context pasa a métodos por defecto de Contextual, que
sólo exige `context()` y `context_mut()`; Page la implementa sobre su
Context y deja de duplicar estado y métodos. Título, descripción,
metadatos y propiedades se guardan ahora en el contexto, así que un
componente puede fijarlos al renderizarse. LangId pasa a ser una
implementación general para todo lo que implemente Contextual.
This commit is contained in:
Manuel Cillero 2026-11-06 16:18:15 +01:00
parent 9afbafdefb
commit b2dfb52d93
11 changed files with 486 additions and 561 deletions

View file

@ -1,14 +1,19 @@
use super::{AssetsOp, ContextError};
use super::{AssetsOp, Context, ContextError};
use crate::auth::CurrentUser;
use crate::builder_impl;
use crate::core::component::ChildOp;
use crate::core::theme::{RegionRef, TemplateRef, ThemeRef};
use crate::core::TypeInfo;
use crate::core::component::{ChildOp, Component, MessageLevel, StatusMessage};
use crate::core::theme::{CoreRegions, RegionRef, TemplateRef, ThemeRef, default_theme};
use crate::datetime::{DateFormat, DatePrecision, RelativeFormat, TimeFormat};
use crate::datetime::{DateInputError, DateTime, NaiveDate, NaiveTime, Tz, Utc};
use crate::html::{Assets, Favicon, JavaScript, Props, PropsOp, ResponsiveStyles, StyleSheet};
use crate::locale::{LangId, Lc};
use crate::html::StyleSheet;
use crate::html::{Assets, Favicon, JavaScript, Props, PropsOp, ResponsiveStyles, RoutePath};
use crate::locale::{LangId, LanguageIdentifier, Lc, RequestLocale};
use crate::response::read_flash_messages;
use crate::web::HttpRequest;
use crate::{CowStr, builder_impl, util};
use std::any::TypeId;
// RFC 3339 con el offset de la zona horaria activa (no UTC fijo): igual en todos los idiomas, no
// es una clave Fluent. Usado sólo por `format_iso_datetime()`.
@ -16,22 +21,31 @@ const ISO_DATETIME: &str = "%Y-%m-%dT%H:%M:%S%:z";
/// Interfaz para gestionar el **contexto de renderizado** de un documento HTML.
///
/// `Contextual` extiende [`LangId`] para establecer el idioma del documento y añade métodos para:
/// Todo lo que implementa `Contextual` es también proveedor de idioma ([`LangId`]), con el idioma
/// del documento, así que puede usarse directamente en [`Lc::lookup()`] o [`Lc::using()`]. Además,
/// ofrece métodos para:
///
/// - Almacenar la **petición HTTP** de origen.
/// - Establecer el **idioma** del documento ([`with_langid()`](Self::with_langid)).
/// - Almacenar la **petición HTTP** de origen ([`with_request()`](Self::with_request)).
/// - Conocer la **identidad del usuario actual** ([`current_user()`](Self::current_user)) y la
/// **zona horaria efectiva** del documento ([`timezone()`](Self::timezone)).
/// - Seleccionar el **tema** y la **plantilla** de renderizado.
/// - Definir el **título**, la **descripción** y los **metadatos** del documento.
/// - Administrar **recursos** del documento como el icono [`Favicon`], las hojas de estilo
/// [`StyleSheet`] o los scripts [`JavaScript`], directamente o mediante una operación
/// [`AssetsOp`].
/// - Leer y mantener **parámetros dinámicos tipados** de contexto.
/// - Construir **rutas** que preserven el idioma ([`route()`](Self::route)) e **identificadores**
/// únicos ([`build_id()`](Self::build_id)).
/// - Acumular **mensajes para el usuario** ([`push_message()`](Self::push_message)).
/// - Formatear **fechas y horas** ([`format_date()`](Self::format_date),
/// [`format_time()`](Self::format_time), [`format_datetime()`](Self::format_datetime) y demás)
/// para la zona horaria e idioma del documento.
///
/// Lo implementan, típicamente, estructuras que manejan el contexto de renderizado, como
/// [`Context`](crate::core::component::Context) o [`Page`](crate::response::Page).
/// Todos los métodos actúan sobre el [`Context`] que devuelven [`context()`](Self::context) y
/// [`context_mut()`](Self::context_mut), los únicos que hay que implementar. Lo implementan
/// [`Context`] (que se devuelve a sí mismo) y [`Page`](crate::response::Page) (que devuelve el
/// suyo), así que ambos ofrecen exactamente la misma interfaz.
///
/// # Ejemplo
///
@ -49,11 +63,23 @@ const ISO_DATETIME: &str = "%Y-%m-%dT%H:%M:%S%:z";
/// }
/// ```
#[builder_impl]
pub trait Contextual: LangId {
pub trait Contextual {
/// Devuelve una referencia al contexto de renderizado.
fn context(&self) -> &Context;
/// Devuelve una referencia mutable al contexto de renderizado.
///
/// Resulta útil para pasar el contexto a funciones o componentes que lo reciben como parámetro
/// (`&mut Context`).
fn context_mut(&mut self) -> &mut Context;
// **< Contextual BUILDER >*********************************************************************
/// Establece el idioma del documento.
fn with_langid(self, language: &impl LangId) -> Self;
fn with_langid(self, language: &impl LangId) -> Self {
self.context_mut().locale.with_langid(language);
self
}
/// Fuerza la zona horaria que se utilizará para mostrar fechas y horas en el documento.
///
@ -61,7 +87,10 @@ pub trait Contextual: LangId {
/// aplicación) por otra explícita. Ver [`CurrentUser::timezone()`].
///
/// [`CurrentUser::timezone()`]: crate::auth::CurrentUser::timezone
fn with_timezone(self, tz: Tz) -> Self;
fn with_timezone(self, tz: Tz) -> Self {
self.context_mut().timezone = tz;
self
}
/// Almacena la petición HTTP de origen en el contexto.
///
@ -77,13 +106,36 @@ pub trait Contextual: LangId {
/// [`current_user()`]: Self::current_user
/// [`timezone()`]: Self::timezone
/// [`theme()`]: Self::theme
fn with_request(self, request: Option<HttpRequest>) -> Self;
fn with_request(self, request: Option<HttpRequest>) -> Self {
let cx = self.context_mut();
// Los mensajes para la página siguiente se leen una sola vez, con la primera petición (las
// páginas de error, p. ej., parten de un contexto sin petición).
if cx.request.is_none()
&& let Some(request) = &request
{
cx.messages.extend(read_flash_messages(request.headers()));
}
cx.request = request;
// Recalcula el *locale*, el usuario actual, la zona horaria y el tema según la nueva
// petición y la política de negociación configurada.
cx.locale = RequestLocale::from_request(cx.request.as_ref());
cx.current_user = Context::resolve_current_user(cx.request.as_ref());
cx.timezone = cx.current_user.timezone();
cx.theme = cx.current_user.theme().unwrap_or_else(default_theme);
self
}
/// Especifica el tema para renderizar el documento.
fn with_theme(self, theme: ThemeRef) -> Self;
fn with_theme(self, theme: ThemeRef) -> Self {
self.context_mut().theme = theme;
self
}
/// Especifica la plantilla para renderizar el documento.
fn with_template(self, template: TemplateRef) -> Self;
fn with_template(self, template: TemplateRef) -> Self {
self.context_mut().template = template;
self
}
/// Añade o modifica un parámetro dinámico del contexto.
///
@ -100,28 +152,122 @@ pub trait Contextual: LangId {
/// .with_param("title", "Hello".to_string())
/// .with_param("flags", vec!["a", "b"]);
/// ```
fn with_param<T: Send + Sync + 'static>(self, key: &'static str, value: T) -> Self;
fn with_param<T: Send + Sync + 'static>(self, key: &'static str, value: T) -> Self {
let type_name = TypeInfo::FullName.of::<T>();
self.context_mut()
.params
.insert(key, (Box::new(value), type_name));
self
}
/// Añade un recurso ([`Favicon`], [`StyleSheet`], [`JavaScript`] o
/// [`Preload`](crate::html::Preload)) directamente, o aplica una operación [`AssetsOp`] sobre
/// los recursos del contexto.
fn with_assets(self, op: impl Into<AssetsOp>) -> Self;
fn with_assets(self, op: impl Into<AssetsOp>) -> Self {
let cx = self.context_mut();
match op.into() {
// Favicon.
AssetsOp::SetFavicon(favicon) => {
cx.favicon = favicon;
}
AssetsOp::SetFaviconIfNone(icon) => {
if cx.favicon.is_none() {
cx.favicon = Some(icon);
}
}
// Preloads.
AssetsOp::AddPreload(preload) => {
cx.preloads.add(preload);
}
AssetsOp::RemovePreload(path) => {
cx.preloads.remove(path);
}
// Stylesheets.
AssetsOp::AddStyleSheet(css) => {
cx.stylesheets.add(css);
}
AssetsOp::RemoveStyleSheet(path) => {
cx.stylesheets.remove(path);
}
// Scripts JavaScript.
AssetsOp::AddJavaScript(js) => {
cx.javascripts.add(js);
}
AssetsOp::RemoveJavaScript(path) => {
cx.javascripts.remove(path);
}
// Estilos responsive.
AssetsOp::AddResponsiveStyle(breakpoint, classes, property, value) => {
cx.responsives
.add_style(breakpoint, classes, property, value);
}
AssetsOp::AddResponsiveStyles(breakpoint, classes, styles) => {
cx.responsives.add_styles(breakpoint, classes, styles);
}
}
self
}
/// Establece el título del documento como un valor traducible.
///
/// Además de usarse en el `<head>`, lo ven las plantillas y los componentes al renderizarse,
/// como el marco de las páginas del panel de administración
/// ([`AdminFrame`](crate::base::component::AdminFrame)), que lo muestra como encabezado.
fn with_title(self, title: Lc) -> Self {
self.context_mut().title = title;
self
}
/// Establece la descripción del documento como un valor traducible.
///
/// Se usa en la etiqueta `<meta name="description">` del `<head>`.
fn with_description(self, description: Lc) -> Self {
self.context_mut().description = description;
self
}
/// Añade una entrada `<meta name="..." content="...">` al `<head>`.
fn with_metadata(self, name: &'static str, content: impl Into<CowStr>) -> Self {
self.context_mut().metadata.push((name, content.into()));
self
}
/// Añade una entrada `<meta property="..." content="...">` al `<head>`.
fn with_property(self, property: &'static str, content: impl Into<CowStr>) -> Self {
self.context_mut()
.properties
.push((property, content.into()));
self
}
/// Modifica identificador, clases CSS, atributos HTML o valores extra del elemento `<body>`.
fn with_body_props(self, op: PropsOp) -> Self;
fn with_body_props(self, op: PropsOp) -> Self {
self.context_mut().body_props.alter_prop(op);
self
}
/// Añade un componente o aplica una operación [`ChildOp`] en la región por defecto del
/// documento.
fn with_child(self, op: impl Into<ChildOp>) -> Self;
fn with_child(self, op: impl Into<ChildOp>) -> Self {
self.context_mut()
.regions
.alter_child_in(&CoreRegions::Content, op.into());
self
}
/// Añade un componente o aplica una operación [`ChildOp`] en una región específica del
/// documento.
fn with_child_in(self, region: RegionRef, op: impl Into<ChildOp>) -> Self;
fn with_child_in(self, region: RegionRef, op: impl Into<ChildOp>) -> Self {
self.context_mut().regions.alter_child_in(region, op.into());
self
}
// **< Contextual GETTERS >*********************************************************************
/// Devuelve una referencia a la petición HTTP asociada, si existe.
fn request(&self) -> Option<&HttpRequest>;
fn request(&self) -> Option<&HttpRequest> {
self.context().request.as_ref()
}
/// Devuelve la identidad del usuario actual.
///
@ -141,7 +287,9 @@ pub trait Contextual: LangId {
/// page.render().await
/// }
/// ```
fn current_user(&self) -> &CurrentUser;
fn current_user(&self) -> &CurrentUser {
&self.context().current_user
}
/// Devuelve la zona horaria efectiva para mostrar fechas y horas en el documento.
///
@ -154,13 +302,19 @@ pub trait Contextual: LangId {
///
/// [`with_request()`]: Self::with_request
/// [`CurrentUser::timezone()`]: crate::auth::CurrentUser::timezone
fn timezone(&self) -> Tz;
fn timezone(&self) -> Tz {
self.context().timezone
}
/// Devuelve el tema que se usará para renderizar el documento.
fn theme(&self) -> ThemeRef;
fn theme(&self) -> ThemeRef {
self.context().theme
}
/// Devuelve la plantilla configurada para renderizar el documento.
fn template(&self) -> TemplateRef;
fn template(&self) -> TemplateRef {
self.context().template
}
/// Recupera una *referencia tipada* al parámetro solicitado.
///
@ -184,7 +338,19 @@ pub trait Contextual: LangId {
/// // Error de tipo:
/// assert!(cx.param::<String>("user_id").is_err());
/// ```
fn param<T: 'static>(&self, key: &'static str) -> Result<&T, ContextError>;
fn param<T: 'static>(&self, key: &'static str) -> Result<&T, ContextError> {
let (any, type_name) = self
.context()
.params
.get(key)
.ok_or(ContextError::ParamNotFound)?;
any.downcast_ref::<T>()
.ok_or_else(|| ContextError::ParamTypeMismatch {
key,
expected: TypeInfo::FullName.of::<T>(),
saved: type_name,
})
}
/// Devuelve el parámetro clonado o el **valor por defecto del tipo** (`T::default()`).
fn param_or_default<T: Clone + Default + 'static>(&self, key: &'static str) -> T {
@ -202,22 +368,164 @@ pub trait Contextual: LangId {
}
/// Devuelve el Favicon de los recursos del contexto.
fn favicon(&self) -> Option<&Favicon>;
fn favicon(&self) -> Option<&Favicon> {
self.context().favicon.as_ref()
}
/// Devuelve las hojas de estilo de los recursos del contexto.
fn stylesheets(&self) -> &Assets<StyleSheet>;
fn stylesheets(&self) -> &Assets<StyleSheet> {
&self.context().stylesheets
}
/// Devuelve los scripts JavaScript de los recursos del contexto.
fn javascripts(&self) -> &Assets<JavaScript>;
fn javascripts(&self) -> &Assets<JavaScript> {
&self.context().javascripts
}
/// Devuelve los estilos *responsive* acumulados en el contexto.
fn responsive_styles(&self) -> &ResponsiveStyles;
fn responsive_styles(&self) -> &ResponsiveStyles {
&self.context().responsives
}
/// Devuelve el título del documento, o [`Lc::none()`] si no tiene.
fn title(&self) -> &Lc {
&self.context().title
}
/// Devuelve la descripción del documento, o [`Lc::none()`] si no tiene.
fn description(&self) -> &Lc {
&self.context().description
}
/// Devuelve la lista de metadatos `<meta name=...>`.
fn metadata(&self) -> &[(&'static str, CowStr)] {
&self.context().metadata
}
/// Devuelve la lista de propiedades `<meta property=...>`.
fn properties(&self) -> &[(&'static str, CowStr)] {
&self.context().properties
}
/// Devuelve identificador, clases CSS, atributos HTML y valores extra del elemento `<body>`.
fn body_props(&self) -> &Props;
fn body_props(&self) -> &Props {
&self.context().body_props
}
/// Devuelve los mensajes de usuario acumulados que aún no ha mostrado ningún componente
/// [`Messages`](crate::base::component::Messages).
fn messages(&self) -> &[StatusMessage] {
&self.context().messages
}
/// Indica si hay mensajes de usuario acumulados que aún no ha mostrado ningún componente
/// [`Messages`](crate::base::component::Messages).
fn has_messages(&self) -> bool {
!self.context().messages.is_empty()
}
// **< Contextual HELPERS >*********************************************************************
/// Construye una ruta aplicada al contexto actual.
///
/// Acepta cualquier tipo convertible a [`RoutePath`] (un literal, un `String`, un `&str` de
/// cualquier vida, o un [`RoutePath`] ya construido con sus propios parámetros). Si la política
/// de negociación del idioma ([`LangNegotiation`](crate::global::LangNegotiation)) indica que
/// debe propagarse el idioma para esta petición, se añade o actualiza automáticamente el
/// parámetro de *query* `lang=...` con el identificador de idioma definido en el contexto.
///
/// Esto garantiza que los enlaces generados desde el contexto preservan la preferencia de
/// idioma del usuario durante la navegación. Si `path` **parece** una URL externa (ver
/// [`util::url_looks_external()`](crate::util::url_looks_external)), nunca se le añade `lang`.
///
/// Este método asume que ya tienes `cx` a mano en el momento de construir la ruta (dentro de
/// `prepare()`, un *handler* HTTP, etc.). Si lo que estás definiendo es un campo de componente
/// que se construye una sola vez y se reutiliza en peticiones futuras (un menú, un botón,
/// etc.), usa [`Route`](crate::core::component::Route) en su lugar (su documentación explica el
/// criterio completo para elegir entre ambos).
fn route(&self, path: impl Into<RoutePath>) -> RoutePath {
let locale = &self.context().locale;
let mut route = path.into();
if !route.is_external() && locale.needs_lang_query() {
route.alter_param("lang", locale.lang_query_value());
}
route
}
/// Construye un identificador HTML único para el tipo de componente `C`.
///
/// Toma los `segments` finales del *path* completo del tipo, los une con `-` y los convierte a
/// minúsculas, y añade un contador independiente por tipo. Por ejemplo, para `MyApp::ui::Menu`
/// con `segments = 2` devuelve `ui-menu-1` la primera vez que se invoca para ese tipo,
/// `ui-menu-2` la segunda, etc.
///
/// Con `segments = 1` se usa sólo el nombre corto del tipo. Si `segments` es `0` o supera el
/// número de segmentos del *path*, se usan todos.
///
/// Es útil para asignar identificadores cuando el componente no recibe uno explícito. El
/// contador es local a este contexto y se reinicia para cada nueva petición.
fn build_id<C: Component>(&self, segments: usize) -> String {
let path: Vec<&str> = TypeInfo::FullName.of::<C>().split("::").collect();
let segments = if segments == 0 || segments >= path.len() {
path.len()
} else {
segments
};
let count = {
let mut map = self.context().id_counters.lock();
let n = map.entry(TypeId::of::<C>()).or_insert(0);
*n += 1;
*n
};
let prefix = path[path.len() - segments..].join("-").to_lowercase();
util::join!(prefix, "-", count.to_string())
}
/// Devuelve `id` si contiene un valor, o genera uno único con [`build_id`](Self::build_id)
/// si es `None`.
fn required_id<C: Component>(&self, id: Option<String>, segments: usize) -> String {
match id {
Some(id) => id,
None => self.build_id::<C>(segments),
}
}
/// Acumula un [`StatusMessage`] en el contexto para notificar al usuario.
///
/// Pueden generarse en cualquier punto del ciclo de una petición web (handlers, renderizado,
/// lógica de negocio, etc.) que tengan acceso al contexto. Los muestra, y los retira, el primer
/// componente [`Messages`](crate::base::component::Messages) que se renderice después de
/// añadirlos: uno propio de la página, si lo hay, o el que encabeza la región
/// [`CoreRegions::Content`], que se renderiza una vez renderizado el resto del `<body>` y
/// recoge los que queden.
///
/// # Ejemplo
///
/// ```rust,no_run
/// # use pagetop::prelude::*;
/// # let mut cx = Context::default();
/// cx.push_message(MessageLevel::Warning, Lc::n("Session is not valid"));
/// ```
fn push_message(&mut self, level: MessageLevel, text: Lc) {
self.context_mut()
.messages
.push(StatusMessage::new(level, text));
}
/// Elimina un parámetro del contexto. Devuelve `true` si la clave existía y se eliminó.
///
/// # Ejemplo
///
/// ```rust
/// # use pagetop::prelude::*;
/// let mut cx = Context::default().with_param("temp", 1u8);
/// assert!(cx.remove_param("temp"));
/// assert!(!cx.remove_param("temp")); // ya no existe
/// ```
fn remove_param(&mut self, key: &'static str) -> bool {
self.context_mut().params.remove(key).is_some()
}
/// Formatea una fecha y hora completas en la zona horaria efectiva del documento
/// ([`timezone()`](Self::timezone)), combinando un [`DateFormat`] y un [`TimeFormat`]
/// independientes (posiblemente distintos entre sí, como una fecha larga con la hora corta),
@ -471,16 +779,19 @@ pub trait Contextual: LangId {
{
crate::datetime::input::parse_datetime(text, self, self.timezone())
}
/// Elimina un parámetro del contexto. Devuelve `true` si la clave existía y se eliminó.
///
/// # Ejemplo
///
/// ```rust
/// # use pagetop::prelude::*;
/// let mut cx = Context::default().with_param("temp", 1u8);
/// assert!(cx.remove_param("temp"));
/// assert!(!cx.remove_param("temp")); // ya no existe
/// ```
fn remove_param(&mut self, key: &'static str) -> bool;
}
/// Cualquier contexto de renderizado es proveedor de idioma, con el idioma del documento.
///
/// El idioma lo resuelve [`RequestLocale`], que tiene en cuenta la petición HTTP (parámetro `?lang`
/// e idioma preferido del usuario), la configuración global de idioma de la aplicación, la cabecera
/// `Accept-Language` y/o el idioma de respaldo, según la negociación indicada en
/// [`global::SETTINGS.app.lang_negotiation`].
///
/// [`global::SETTINGS.app.lang_negotiation`]: crate::global::AppSettings::lang_negotiation
impl<T: Contextual> LangId for T {
#[inline]
fn langid(&self) -> &'static LanguageIdentifier {
self.context().locale.langid()
}
}