manuelcillero/pagetop
manuelcillero/pagetop
1
0
Fork 0
Code Issues Pull requests 1 Projects Releases Packages Wiki Activity Actions

✨ Completa la API de temas con setup_component!

Browse source 
Elimina `action::theme` fusionando sus responsabilidades en
`action::component`. Renombra `AlterMarkup` a `TransformMarkup` y
`FnActionAlterMarkup` a `FnActionTransformMarkup`. Simplifica
`ActionKey` y mueve los tipos de función al módulo de componente.
This commit is contained in:
Manuel Cillero 2026-03-23 15:52:06 +01:00
parent 0c648fb95a
commit 04e3d5b3c2
18 changed files with 178 additions and 279 deletions
Download patch file Download diff file Expand all files Collapse all files

37
src/core/action.rs
View file

@ -14,50 +14,37 @@ mod all;
pub(crate) use all::add_action;
pub use all::dispatch_actions;
// **< actions_boxed! >*****************************************************************************
// **< actions! >***********************************************************************************
/// Facilita la implementación del método [`actions()`](crate::core::extension::Extension::actions).
///
/// Evita escribir repetidamente `Box::new(...)` para cada acción de la lista, manteniendo el código
/// más limpio.
///
/// # Ejemplos
/// # Ejemplo
///
/// Acciones de tema que ajustan un componente antes y después de renderizarlo:
///
/// ```rust,ignore
/// impl Extension for MyTheme {
/// fn actions(&self) -> Vec<ActionBox> {
/// actions_boxed![
/// action::theme::BeforeRender::<Button>::new(&Self, before_render_button),
/// action::theme::AfterRender::<Button>::new(&Self, after_render_button),
/// ]
/// }
/// }
///
/// impl Theme for MyTheme {}
///
/// fn before_render_button(c: &mut Button, cx: &mut Context) { todo!() }
/// fn after_render_button(c: &mut Button, cx: &mut Context) { todo!() }
/// ```
///
/// Acción de extensión que transforma el HTML final de un componente mediante edición de texto:
/// Extensión que ajusta un botón antes de renderizarlo y transforma su HTML final:
///
/// ```rust,ignore
/// impl Extension for MyExtension {
/// fn actions(&self) -> Vec<ActionBox> {
/// actions_boxed![
/// action::component::AlterMarkup::<Button>::new(alter_button_markup),
/// actions![
/// action::component::BeforeRender::<Button>::new(before_render_button),
/// action::component::TransformMarkup::<Button>::new(transform_button_markup),
/// ]
/// }
/// }
///
/// fn alter_button_markup(c: &mut Button, cx: &mut Context, markup: Markup) -> Markup {
/// fn before_render_button(c: &mut Button, cx: &mut Context) {
/// todo!()
/// }
///
/// fn transform_button_markup(c: &Button, cx: &mut Context, markup: Markup) -> Markup {
/// todo!()
/// }
/// ```
#[macro_export]
macro_rules! actions_boxed {
macro_rules! actions {
() => {
Vec::<ActionBox>::new()
};

2
src/core/action/all.rs
View file

@ -22,7 +22,6 @@ static ACTIONS: LazyLock<RwLock<HashMap<ActionKey, ActionsList>>> =
pub(crate) fn add_action(action: ActionBox) {
let key = ActionKey::new(
action.type_id(),
action.theme_type_id(),
action.referer_type_id(),
action.referer_id(),
);
@ -55,7 +54,6 @@ pub(crate) fn add_action(action: ActionBox) {
/// dispatch_actions(
/// &ActionKey::new(
/// UniqueId::of::<Self>(),
/// Some(cx.theme().type_id()),
/// Some(UniqueId::of::<C>()),
/// None,
/// ),

11
src/core/action/definition.rs
View file

@ -11,7 +11,6 @@ pub type ActionBox = Box<dyn ActionDispatcher>;
#[derive(Eq, PartialEq, Hash)]
pub struct ActionKey {
action_type_id: UniqueId,
theme_type_id: Option<UniqueId>,
referer_type_id: Option<UniqueId>,
referer_id: Option<String>,
}
@ -22,22 +21,19 @@ impl ActionKey {
/// Se crea con los siguientes campos:
///
/// - `action_type_id`: Tipo de la acción.
/// - `theme_type_id`: Opcional, identificador de tipo ([`UniqueId`]) del tema asociado.
/// - `referer_type_id`: Opcional, identificador de tipo ([`UniqueId`]) del componente referido.
/// - `referer_id`: Opcional, identificador de la instancia (p. ej. para asociar la acción a un
/// componente concreto).
///
/// Esta clave permitirá seleccionar las funciones a ejecutar para ese tipo de acción, con
/// filtros opcionales por tema, componente, o una instancia concreta según su identificador.
/// filtros opcionales por componente o por una instancia concreta según su identificador.
pub fn new(
action_type_id: UniqueId,
theme_type_id: Option<UniqueId>,
referer_type_id: Option<UniqueId>,
referer_id: Option<String>,
) -> Self {
ActionKey {
action_type_id,
theme_type_id,
referer_type_id,
referer_id,
}
@ -49,11 +45,6 @@ impl ActionKey {
/// Las acciones tienen que sobrescribir los métodos para el filtro que apliquen. Por defecto
/// implementa un filtro nulo.
pub trait ActionDispatcher: AnyInfo + Send + Sync {
/// Identificador de tipo ([`UniqueId`]) del tema asociado. En este caso devuelve `None`.
fn theme_type_id(&self) -> Option<UniqueId> {
None
}
/// Identificador de tipo ([`UniqueId`]) del objeto referido. En este caso devuelve `None`.
fn referer_type_id(&self) -> Option<UniqueId> {
None

40
src/core/component/definition.rs
View file

@ -75,10 +75,10 @@ pub trait Component: AnyInfo + ComponentRender + Send + Sync {
///
/// Este método forma parte del ciclo de vida de los componentes y se invoca automáticamente
/// durante el proceso de construcción del documento cuando ningún tema sobrescribe el
/// renderizado mediante [`Theme::prepare_component()`](crate::core::theme::Theme::prepare_component).
/// renderizado mediante [`Theme::handle_component()`](crate::core::theme::Theme::handle_component).
///
/// Se recomienda obtener los datos del componente a través de sus propios métodos para que los
/// temas puedan implementar [`Theme::prepare_component()`](crate::core::theme::Theme::prepare_component)
/// temas puedan implementar [`Theme::handle_component()`](crate::core::theme::Theme::handle_component)
/// sin depender de los detalles internos del componente.
///
/// Por defecto, devuelve un [`Markup`] vacío (`Ok(html! {})`).
@ -99,23 +99,17 @@ pub trait Component: AnyInfo + ComponentRender + Send + Sync {
/// contexto actual. Si no es así, devuelve un [`Markup`] vacío.
/// 2. Ejecuta [`setup_before_prepare()`](Component::setup_before_prepare) para que el componente
/// pueda ajustar su estructura interna o modificar el contexto.
/// 3. Despacha [`action::theme::BeforeRender<C>`](crate::base::action::theme::BeforeRender) para
/// permitir que el tema realice ajustes previos.
/// 4. Despacha [`action::component::BeforeRender<C>`](crate::base::action::component::BeforeRender)
/// para que otras extensiones puedan también hacer ajustes previos.
/// 5. **Prepara el renderizado del componente**:
/// - Recorre la cadena de temas llamando a
/// [`Theme::prepare_component()`](crate::core::theme::Theme::prepare_component) en cada nivel
/// (hijo → padre → abuelo…) hasta que uno devuelva `Some`.
/// - Si ningún tema lo sobrescribe, llama a
/// [`Component::prepare_component()`](Component::prepare_component) del propio componente.
/// 6. Despacha [`action::theme::AfterRender<C>`](crate::base::action::theme::AfterRender) para que
/// el tema pueda reaccionar tras el renderizado.
/// 7. Despacha [`action::component::AfterRender<C>`](crate::base::action::component::AfterRender)
/// para que otras extensiones puedan reaccionar con sus últimos ajustes.
/// 8. Despacha [`action::component::AlterMarkup<C>`](crate::base::action::component::AlterMarkup)
/// 3. Despacha [`action::component::BeforeRender<C>`](crate::base::action::component::BeforeRender)
/// para que las extensiones puedan hacer ajustes previos.
/// 4. **Prepara el renderizado del componente** recorriendo la cadena de temas (hijo → padre →
/// abuelo…) llamando a [`Theme::handle_component()`](crate::core::theme::Theme::handle_component)
/// en cada nivel hasta que uno devuelva `Some`. Si ninguno lo sobrescribe, llama a
/// [`Component::prepare_component()`](Component::prepare_component) del propio componente.
/// 5. Despacha [`action::component::AfterRender<C>`](crate::base::action::component::AfterRender)
/// para que las extensiones puedan reaccionar con sus últimos ajustes.
/// 6. Despacha [`action::component::TransformMarkup<C>`](crate::base::action::component::TransformMarkup)
/// para que las extensiones puedan modificar el HTML final antes de devolverlo.
/// 9. Devuelve el [`Markup`] resultante.
/// 7. Devuelve el [`Markup`] resultante.
impl<C: Component> ComponentRender for C {
fn render(&mut self, cx: &mut Context) -> Markup {
// Si no es renderizable, devuelve un bloque HTML vacío.
@ -126,9 +120,6 @@ impl<C: Component> ComponentRender for C {
// Configura el componente antes de preparar.
self.setup_before_prepare(cx);
// Acciones específicas del tema antes de renderizar el componente.
action::theme::BeforeRender::dispatch(self, cx);
// Acciones de las extensiones antes de renderizar el componente.
action::component::BeforeRender::dispatch(self, cx);
@ -136,7 +127,7 @@ impl<C: Component> ComponentRender for C {
let prepare = match 'resolve: {
let mut t: Option<ThemeRef> = Some(cx.theme());
while let Some(theme) = t {
if let Some(r) = theme.prepare_component(self, cx) {
if let Some(r) = theme.handle_component(self, cx) {
break 'resolve r;
}
t = theme.parent();
@ -156,13 +147,10 @@ impl<C: Component> ComponentRender for C {
}
};
// Acciones específicas del tema después de renderizar el componente.
action::theme::AfterRender::dispatch(self, cx);
// Acciones de las extensiones después de renderizar el componente.
action::component::AfterRender::dispatch(self, cx);
// Acciones de las extensiones que transforman el HTML final antes de devolverlo.
action::component::AlterMarkup::dispatch(self, cx, prepare)
action::component::TransformMarkup::dispatch(self, cx, prepare)
}
}

6
src/core/extension/definition.rs
View file

@ -2,7 +2,7 @@ use crate::core::action::ActionBox;
use crate::core::theme::ThemeRef;
use crate::core::AnyInfo;
use crate::locale::L10n;
use crate::{actions_boxed, service};
use crate::{actions, service};
/// Interfaz común que debe implementar cualquier extensión de PageTop.
///
@ -74,10 +74,10 @@ pub trait Extension: AnyInfo + Send + Sync {
/// Devuelve la lista de acciones que la extensión registra.
///
/// Estas [acciones](crate::core::action) se despachan por orden de registro o por
/// [peso](crate::Weight) (ver [`actions_boxed!`](crate::actions_boxed)), permitiendo
/// [peso](crate::Weight) (ver [`actions!`](crate::actions)), permitiendo
/// personalizar el comportamiento de la aplicación en puntos específicos.
fn actions(&self) -> Vec<ActionBox> {
actions_boxed![]
actions![]
}
/// Inicializa la extensión durante la fase de arranque de la aplicación.

82
src/core/theme.rs
View file

@ -20,7 +20,7 @@
//!
//! PageTop permite crear **temas hijo** que refinan el comportamiento de su tema padre. Un tema
//! hijo hereda automáticamente todos los métodos del padre y puede sobrescribirlos selectivamente:
//! por ejemplo, puede redefinir el renderizado de un componente con [`Theme::prepare_component()`]
//! por ejemplo, puede redefinir el renderizado de un componente con [`Theme::handle_component()`]
//! sin modificar el resto del comportamiento heredado. Un tema hijo puede ser a su vez padre de
//! otro, basta declararlo cada vez con [`Theme::parent()`].
//!
@ -208,27 +208,31 @@ impl Template for DefaultTemplate {}
// **< render_component! >**************************************************************************
/// Sobrescribe el renderizado de componentes en la implementación de
/// [`Theme::prepare_component()`](crate::core::theme::Theme::prepare_component).
/// Sobrescribe el renderizado de componentes en
/// [`Theme::handle_component()`](crate::core::theme::Theme::handle_component).
///
/// Evalúa `$component` contra cada tipo 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
/// 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 prepare_component(
/// fn handle_component(
/// &self,
/// component: &dyn Component,
/// cx: &mut Context,
/// ) -> Option<Result<Markup, ComponentError>> {
/// render_component!(component, {
/// Button => |btn| Ok(html! { button.btn.btn-primary { (btn.label()) } }),
/// Heading => |h| Ok(html! { h2.display-4 { (h.text()) } }),
/// Button => |btn| { Ok(html! { button.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.display-4 { (h.text()) } })
/// }
/// ```
#[macro_export]
macro_rules! render_component {
@ -244,6 +248,66 @@ macro_rules! render_component {
};
}
// **< setup_component! >***************************************************************************
/// Muta un componente dentro de
/// [`Theme::handle_component()`](crate::core::theme::Theme::handle_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`](crate::core::AnyCast::downcast_mut),
/// lo que permite modificar su estado. El tema puede devolver `None` tras la mutación para que otro
/// nivel de la cadena se encargue del renderizado.
///
/// # Ejemplos
///
/// Solo mutación: el tema ajusta el componente y delega el renderizado al siguiente nivel:
///
/// ```rust,ignore
/// fn handle_component(
/// &self,
/// component: &mut dyn Component,
/// cx: &mut Context,
/// ) -> Option<Result<Markup, ComponentError>> {
/// setup_component!(component, { Button => |btn| { btn.add_class("btn-primary"); } });
/// None
/// }
/// ```
///
/// Mutación y renderizado combinados: el `Button` se muta y se renderiza aquí; el `Heading` se
/// muta pero continúa la cadena para que otro nivel lo renderice:
///
/// ```rust,ignore
/// fn handle_component(
/// &self,
/// component: &mut dyn Component,
/// cx: &mut Context,
/// ) -> Option<Result<Markup, ComponentError>> {
/// setup_component!(component, {
/// Button => |btn| { btn.add_class("btn-primary"); },
/// Heading => |h| { h.add_class("display-4"); },
/// });
/// render_component!(component, {
/// Button => |btn| Ok(html! { button.btn { (btn.label()) } }),
/// })
/// }
/// ```
#[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;
}
)*
}
};
}
// **< Definitions >********************************************************************************
mod definition;

34
src/core/theme/definition.rs
View file

@ -184,30 +184,42 @@ pub trait Theme: Extension + Send + Sync {
}
}
/// Permite sobrescribir el renderizado de un componente.
/// Permite al tema intervenir en el ciclo de 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 al componente (como objeto dinámico [`Component`]) y el contexto de
/// renderizado. Devuelve:
/// Recibe una referencia mutable al componente (como objeto dinámico [`Component`]) y el
/// contexto de renderizado. Devuelve:
///
/// - `None` si este tema no sobrescribe el componente. Es la implementación por defecto. En
/// este caso se recorre la cadena de temas padre y, si ninguno lo sobrescribe, se usa
/// - `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_component()`](crate::core::component::Component::prepare_component).
/// El tema puede mutar el componente antes de devolver `None`, dejando que otro nivel de la
/// cadena se encargue del renderizado.
/// - `Some(Ok(markup))` con el HTML generado por el tema para el componente.
///
/// > **Nota para componentes en región:** los componentes registrados con `InRegion` son
/// > instancias únicas compartidas entre peticiones. Cualquier mutación realizada aquí debe
/// > ser idempotente — sobrescribir valores, nunca acumular — o el estado se corromperá a
/// > partir de la segunda petición.
/// - `Some(Err(e))` si el tema intentó renderizarlo pero falló.
///
/// La mejor manera de implementar este método es usando la macro [`render_component!`], que
/// determina el componente a renderizar y devuelve `None` si ninguno coincide:
/// Para renderizar usa [`render_component!`], que devuelve `None` si ningún tipo coincide. Para
/// mutar sin renderizar usa [`setup_component!`] y devuelve `None` explícitamente:
///
/// ```rust,ignore
/// fn prepare_component(
/// fn handle_component(
/// &self,
/// component: &dyn Component,
/// component: &mut dyn Component,
/// cx: &mut Context,
/// ) -> Option<Result<Markup, ComponentError>> {
/// // Solo mutación: ajusta el componente y deja que otro nivel lo renderice.
/// setup_component!(component, {
/// Button => |btn| { btn.add_class("btn-primary"); },
/// });
/// // O renderizado completo:
/// render_component!(component, {
/// Button => |btn| Ok(html! { button.btn.btn-primary { (btn.label()) } }),
/// Heading => |h| Ok(html! { h2.display-4 { (h.text()) } }),
@ -215,9 +227,9 @@ pub trait Theme: Extension + Send + Sync {
/// }
/// ```
#[allow(unused_variables)]
fn prepare_component(
fn handle_component(
&self,
component: &dyn Component,
component: &mut dyn Component,
cx: &mut Context,
) -> Option<Result<Markup, ComponentError>> {
None