From 8ddc26dae1f41c2081d7c58a70b5c403a865f00f Mon Sep 17 00:00:00 2001 From: Manuel Cillero Date: Tue, 28 Jul 2026 09:19:50 +0200 Subject: [PATCH 1/2] =?UTF-8?q?=F0=9F=93=9D=20(theme):=20Aclara=20alcance?= =?UTF-8?q?=20de=20la=20herencia=20de=20temas?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- src/core/theme.rs | 27 ++++++++++++++++++++++----- 1 file changed, 22 insertions(+), 5 deletions(-) diff --git a/src/core/theme.rs b/src/core/theme.rs index fc54e3b3..f89746d9 100644 --- a/src/core/theme.rs +++ b/src/core/theme.rs @@ -11,11 +11,28 @@ //! [`Context`](crate::core::component::Context), donde mantiene el tema activo, la plantilla //! seleccionada y los componentes asociados a cada región a renderizar. //! -//! Además, 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 a través de -//! [`Theme::handle_component()`] sin cambiar el resto del comportamiento heredado. Un tema hijo -//! puede ser a su vez padre de otro, basta declararlo cada vez con [`Theme::parent()`]. +//! # Temas hijo, herencia y componentes +//! +//! 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. +//! Esta herencia sólo determina qué implementación de sus métodos se usa cuando el tema hijo no los +//! sobrescribe (como el renderizado del `` y del ``, los recursos incorporados, el uso +//! de [`Theme::handle_component()`], las páginas de error, etc.). Un tema hijo puede ser a su vez +//! padre de otro, basta declararlo cada vez con [`Theme::parent()`]. +//! +//! Sin embargo, no dice nada sobre los componentes. Aunque un tema puede exportar su propio +//! catálogo de componentes, realmente no pertenecen como tal a ningún tema ni dependen de esa +//! cadena de herencia. Una extensión puede existir únicamente para aportar un componente genérico +//! (por ejemplo, un editor de texto enriquecido) pensado para usarse en cualquier aplicación, con +//! independencia del tema activo. Que un tema decida capturar ese componente en +//! [`Theme::handle_component()`] para adaptarlo es una decisión propia del tema, no una relación de +//! parentesco: cualquier tema de la cadena de herencia puede interceptar cualquier componente, +//! venga de la extensión que venga, sin que exista ningún vínculo de diseño previo entre ambos. +//! +//! Lo que sí es responsabilidad del tema activo es garantizar que el componente disponga de los +//! recursos que necesita para verse y comportarse correctamente: sus propios estilos y JavaScript, +//! si los aporta, o los que ofrezca el tema. El componente genera su marcado igual aunque esos +//! recursos falten, pero el resultado seguramente no lucirá ni funcionará como se espera. //! //! # Cómo crear un tema nuevo //! From c91b1cd35c548dcc6eb91c9ed2fd4dd4ef7ad53a Mon Sep 17 00:00:00 2001 From: Manuel Cillero Date: Tue, 28 Jul 2026 19:02:12 +0200 Subject: [PATCH 2/2] =?UTF-8?q?=E2=9C=A8=20(seaorm):=20A=C3=B1ade=20`flatt?= =?UTF-8?q?en=5Ftxn=5Ferr()`?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Convierte `TransactionError` a `E` para propagar el resultado de una transacción con `?` sin distinguir el origen del error. --- extensions/pagetop-seaorm/src/db.rs | 75 +++++++++++++++++++++++++++-- 1 file changed, 72 insertions(+), 3 deletions(-) diff --git a/extensions/pagetop-seaorm/src/db.rs b/extensions/pagetop-seaorm/src/db.rs index 0741fd33..712fcff3 100644 --- a/extensions/pagetop-seaorm/src/db.rs +++ b/extensions/pagetop-seaorm/src/db.rs @@ -24,12 +24,13 @@ //! //! - **Acceso**: [`DatabaseConnection`], [`dbconn`] (para obtener el pool de conexiones). //! - **Consultas**: [`EntityTrait`], [`QueryFilter`], [`QueryOrder`], [`QuerySelect`]. -//! - **Transacciones**: [`TransactionTrait`], [`DatabaseTransaction`]. +//! - **Transacciones**: [`TransactionTrait`], [`DatabaseTransaction`], [`flatten_txn_err`] +//! (para convertir [`TransactionError`] a `E`). //! - **Modelos activos**: [`ActiveModelTrait`], [`ActiveValue`] ([`ActiveValue::Set`], //! [`ActiveValue::Unchanged`], [`ActiveValue::NotSet`]). //! - **Macros de derivación**: [`DeriveEntityModel`], [`DeriveColumn`], [`DerivePrimaryKey`], //! [`DeriveRelation`], [`EnumIter`]. -//! - **Errores**: [`DbErr`]. +//! - **Errores**: [`DbErr`], [`TransactionError`]. //! - **Resultados**: [`QueryResult`] (filas sin tipar), [`ExecResult`] (INSERT/UPDATE/DELETE), //! [`Paginated`] (página de resultados). //! @@ -329,6 +330,74 @@ pub async fn fetch_one( .await } +/// Convierte el error de una transacción (`TransactionError`) al propio tipo `E`. +/// +/// [`TransactionTrait::transaction`] puede fallar de dos formas distintas: +/// [`TransactionError::Connection`] si el fallo ocurre en la propia transacción (conexión, +/// `BEGIN`/`COMMIT`/`ROLLBACK`...), o [`TransactionError::Transaction`] si el fallo es el error que +/// devolvió la clausura. `flatten_txn_err()` convierte ambos casos al mismo tipo `E` (usando +/// `From` para el primero), de modo que el resultado se pueda propagar con +/// `.map_err(flatten_txn_err)?` sin distinguir el origen del error. +/// +/// Requiere que el tipo de error propio de la aplicación implemente `From`, lo habitual con +/// `#[derive(thiserror::Error)]` y `#[from]`. +/// +/// Uso directo, en el punto donde se resuelve la transacción, sin nada más que declarar: +/// +/// ```rust,no_run +/// use pagetop_seaorm::db::*; +/// +/// async fn example() -> Result<(), DbErr> { +/// dbconn() +/// .transaction::<_, (), DbErr>(|_txn| Box::pin(async move { Ok(()) })) +/// .await +/// .map_err(flatten_txn_err) +/// } +/// ``` +/// +/// Si una aplicación hace transacciones en muchos puntos con su propio tipo de error, puede delegar +/// en `flatten_txn_err()` una sola vez mediante `impl From> for E` (legal +/// porque `E` es un tipo local de la aplicación, no genérico) y despreocuparse de `.map_err()` en +/// el resto de llamadas, propagando el error con `?` directamente: +/// +/// ```rust,no_run +/// use pagetop_seaorm::db::*; +/// +/// #[derive(Debug)] +/// struct MyError(DbErr); +/// +/// impl std::fmt::Display for MyError { +/// fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { +/// write!(f, "database error: {}", self.0) +/// } +/// } +/// +/// impl From for MyError { +/// fn from(err: DbErr) -> Self { +/// MyError(err) +/// } +/// } +/// +/// impl From> for MyError { +/// fn from(err: TransactionError) -> Self { +/// flatten_txn_err(err) +/// } +/// } +/// +/// async fn example() -> Result<(), MyError> { +/// dbconn() +/// .transaction::<_, (), MyError>(|_txn| Box::pin(async move { Ok(()) })) +/// .await?; +/// Ok(()) +/// } +/// ``` +pub fn flatten_txn_err>(err: TransactionError) -> E { + match err { + TransactionError::Connection(db_err) => db_err.into(), + TransactionError::Transaction(err) => err, + } +} + // **< Paginated / paginate >*********************************************************************** /// Página de resultados de una consulta paginada. @@ -383,7 +452,7 @@ impl Paginated { } } -/// Ejecuta una consulta paginada con el sistema de entidades y devuelve la página solicitada. +/// Ejecuta una consulta paginada con el sistema de entidades y retorna la página solicitada. /// /// Añade la metadata de paginación (`total`, `total_pages`); `page` y `per_page` se ajustan a un /// mínimo de `1`, ya que no existe la página `0` ni un tamaño de página vacío.