diff --git a/src/core/theme.rs b/src/core/theme.rs index d741cf8..d67a445 100644 --- a/src/core/theme.rs +++ b/src/core/theme.rs @@ -1,6 +1,24 @@ //! API para añadir y gestionar nuevos temas. +//! +//! En `PageTop` un tema es la *piel* de la aplicación, decide cómo se muestra cada documento HTML, +//! especialmente las páginas de contenido ([`Page`](crate::response::page::Page)), sin alterar la +//! lógica interna de sus componentes. +//! +//! Un tema **declara las regiones** (*cabecera*, *barra lateral*, *pie*, etc.) que estarán +//! disponibles para colocar contenido. Los temas son responsables últimos de los estilos, +//! tipografías, espaciados y cualquier otro detalle visual o de comportamiento (como animaciones, +//! *scripts* de interfaz, etc.). +//! +//! Es una extensión más (implementando [`ExtensionTrait`](crate::core::extension::ExtensionTrait)). +//! Se instala, activa y declara dependencias igual que el resto de extensiones; y se señala a sí +//! misma como tema (implementando [`theme()`](crate::core::extension::ExtensionTrait::theme) +//! y [`ThemeTrait`]). mod definition; pub use definition::{ThemeRef, ThemeTrait}; +mod regions; +pub(crate) use regions::ChildrenInRegions; +pub use regions::InRegion; + pub(crate) mod all; diff --git a/src/core/theme/definition.rs b/src/core/theme/definition.rs index e32ac48..6f1e54a 100644 --- a/src/core/theme/definition.rs +++ b/src/core/theme/definition.rs @@ -1,4 +1,5 @@ use crate::core::extension::ExtensionTrait; +use crate::locale::L10n; /// Representa una referencia a un tema. /// @@ -27,4 +28,8 @@ pub type ThemeRef = &'static dyn ThemeTrait; /// /// impl ThemeTrait for MyTheme {} /// ``` -pub trait ThemeTrait: ExtensionTrait + Send + Sync {} +pub trait ThemeTrait: ExtensionTrait + Send + Sync { + fn regions(&self) -> Vec<(&'static str, L10n)> { + vec![("content", L10n::l("content"))] + } +} diff --git a/src/core/theme/regions.rs b/src/core/theme/regions.rs new file mode 100644 index 0000000..5beee25 --- /dev/null +++ b/src/core/theme/regions.rs @@ -0,0 +1,111 @@ +use crate::core::component::{Child, ChildOp, Children}; +use crate::core::theme::ThemeRef; +use crate::{builder_fn, AutoDefault, UniqueId}; + +use parking_lot::RwLock; + +use std::collections::HashMap; +use std::sync::LazyLock; + +static THEME_REGIONS: LazyLock>> = + LazyLock::new(|| RwLock::new(HashMap::new())); + +static COMMON_REGIONS: LazyLock> = + LazyLock::new(|| RwLock::new(ChildrenInRegions::default())); + +// Estructura interna para mantener los componentes de cada región dada. +#[derive(AutoDefault)] +pub struct ChildrenInRegions(HashMap<&'static str, Children>); + +impl ChildrenInRegions { + pub fn new() -> Self { + ChildrenInRegions::default() + } + + pub fn with(region_id: &'static str, child: Child) -> Self { + ChildrenInRegions::default().with_in_region(region_id, ChildOp::Add(child)) + } + + #[builder_fn] + pub fn with_in_region(mut self, region_id: &'static str, op: ChildOp) -> Self { + if let Some(region) = self.0.get_mut(region_id) { + region.alter_child(op); + } else { + self.0.insert(region_id, Children::new().with_child(op)); + } + self + } + + pub fn all_in_region(&self, theme: ThemeRef, region_id: &str) -> Children { + let common = COMMON_REGIONS.read(); + if let Some(r) = THEME_REGIONS.read().get(&theme.type_id()) { + Children::merge(&[ + common.0.get(region_id), + self.0.get(region_id), + r.0.get(region_id), + ]) + } else { + Children::merge(&[common.0.get(region_id), self.0.get(region_id)]) + } + } +} + +/// Permite añadir componentes a regiones globales o regiones de temas concretos. +/// +/// Dada una región, según la variante seleccionada, se le podrán añadir ([`add()`](Self::add)) +/// componentes que se mantendrán durante la ejecución de la aplicación. +/// +/// Estas estructuras de componentes se renderizarán automáticamente al procesar los documentos HTML +/// que las usan, como las páginas de contenido ([`Page`](crate::response::page::Page)), por +/// ejemplo. +pub enum InRegion { + /// Representa la región por defecto en la que se pueden añadir componentes. + Content, + /// Representa la región con el nombre del argumento. + Named(&'static str), + /// Representa la región con el nombre y del tema especificado en los argumentos. + OfTheme(&'static str, ThemeRef), +} + +impl InRegion { + /// Permite añadir un componente en la región de la variante seleccionada. + /// + /// # Ejemplo + /// + /// ```rust + /// use pagetop::prelude::*; + /// + /// // Banner global, en la región por defecto de cualquier página. + /// InRegion::Content.add(Child::with(Html::with( + /// html! { ("🎉 ¡Bienvenido!") } + /// ))); + /// + /// // Texto en la región "sidebar". + /// InRegion::Named("sidebar").add(Child::with(Html::with( + /// html! { ("Publicidad") } + /// ))); + /// ``` + pub fn add(&self, child: Child) -> &Self { + match self { + InRegion::Content => { + COMMON_REGIONS + .write() + .alter_in_region("region-content", ChildOp::Add(child)); + } + InRegion::Named(name) => { + COMMON_REGIONS + .write() + .alter_in_region(name, ChildOp::Add(child)); + } + InRegion::OfTheme(region, theme) => { + let mut regions = THEME_REGIONS.write(); + if let Some(r) = regions.get_mut(&theme.type_id()) { + r.alter_in_region(region, ChildOp::Add(child)); + } else { + regions.insert(theme.type_id(), ChildrenInRegions::with(region, child)); + } + } + } + self + } +} diff --git a/src/locale/en-US/theme.ftl b/src/locale/en-US/theme.ftl new file mode 100644 index 0000000..fd7f228 --- /dev/null +++ b/src/locale/en-US/theme.ftl @@ -0,0 +1 @@ +content = Content diff --git a/src/locale/es-ES/theme.ftl b/src/locale/es-ES/theme.ftl new file mode 100644 index 0000000..c2026c6 --- /dev/null +++ b/src/locale/es-ES/theme.ftl @@ -0,0 +1 @@ +content = Contenido