From 35013b36dfea5b438151aeb25cd3adf80aec25e9 Mon Sep 17 00:00:00 2001 From: Manuel Cillero Date: Fri, 12 Dec 2025 00:14:55 +0100 Subject: [PATCH] =?UTF-8?q?=E2=9C=A8=20[pagetop]=20A=C3=B1ade=20gesti?= =?UTF-8?q?=C3=B3n=20de=20rutas=20con=20par=C3=A1metros?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- Cargo.lock | 11 +- Cargo.toml | 1 + .../src/theme/dropdown/item.rs | 43 +++---- .../pagetop-bootsier/src/theme/nav/item.rs | 47 ++++---- src/core/component.rs | 35 ++++-- src/html.rs | 3 + src/html/attr_classes.rs | 7 +- src/html/route.rs | 106 ++++++++++++++++++ 8 files changed, 197 insertions(+), 56 deletions(-) create mode 100644 src/html/route.rs diff --git a/Cargo.lock b/Cargo.lock index eda0a31e..16b0fd66 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -1084,9 +1084,9 @@ dependencies = [ [[package]] name = "hashbrown" -version = "0.16.0" +version = "0.16.1" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "5419bdc4f6a9207fbeba6d11b604d481addf78ecd10c11ad51e76c2f6482748d" +checksum = "841d1cc9bed7f9236f321df977030373f4a4163ae1a7dbfe1a51a2c1a51d9100" [[package]] name = "hkdf" @@ -1290,12 +1290,12 @@ checksum = "e8a5a9a0ff0086c7a148acb942baaabeadf9504d10400b5a05645853729b9cd2" [[package]] name = "indexmap" -version = "2.11.4" +version = "2.12.1" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "4b0f83760fb341a774ed326568e19f5a863af4a952def8c39f9ab92fd95b88e5" +checksum = "0ad4bb2b565bca0645f4d68c5c9af97fba094e9791da685bf83cb5f3ce74acf2" dependencies = [ "equivalent", - "hashbrown 0.16.0", + "hashbrown 0.16.1", ] [[package]] @@ -1572,6 +1572,7 @@ dependencies = [ "figlet-rs", "fluent-templates", "getter-methods", + "indexmap", "itoa", "pagetop-aliner", "pagetop-bootsier", diff --git a/Cargo.toml b/Cargo.toml index a96620d5..a801b786 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -21,6 +21,7 @@ config = { version = "0.15", default-features = false, features = ["toml"] } figlet-rs = "0.1" getter-methods = "2.0" itoa = "1.0" +indexmap = "2.12" parking_lot = "0.12" substring = "1.4" terminal_size = "0.4" diff --git a/extensions/pagetop-bootsier/src/theme/dropdown/item.rs b/extensions/pagetop-bootsier/src/theme/dropdown/item.rs index 81f0ab08..4031078b 100644 --- a/extensions/pagetop-bootsier/src/theme/dropdown/item.rs +++ b/extensions/pagetop-bootsier/src/theme/dropdown/item.rs @@ -14,11 +14,12 @@ pub enum ItemKind { Void, /// Etiqueta sin comportamiento interactivo. Label(L10n), - /// Elemento de navegación. Opcionalmente puede abrirse en una nueva ventana y estar - /// inicialmente deshabilitado. + /// Elemento de navegación basado en una [`RoutePath`] dinámica devuelta por + /// [`FnPathByContext`]. Opcionalmente, puede abrirse en una nueva ventana y estar inicialmente + /// deshabilitado. Link { label: L10n, - path: FnPathByContext, + route: FnPathByContext, blank: bool, disabled: bool, }, @@ -40,8 +41,8 @@ pub enum ItemKind { /// visible que puede comportarse como texto, enlace, botón, encabezado o separador, según su /// [`ItemKind`]. /// -/// Permite definir identificador, clases de estilo adicionales o tipo de interacción asociada, -/// manteniendo una interfaz común para renderizar todos los elementos del menú. +/// Permite definir el identificador, las clases de estilo adicionales y el tipo de interacción +/// asociada, manteniendo una interfaz común para renderizar todos los elementos del menú. #[derive(AutoDefault, Getters)] pub struct Item { #[getters(skip)] @@ -75,13 +76,13 @@ impl Component for Item { ItemKind::Link { label, - path, + route, blank, disabled, } => { - let path = path(cx); + let route_link = route(cx); let current_path = cx.request().map(|request| request.path()); - let is_current = !*disabled && (current_path == Some(&path)); + let is_current = !*disabled && (current_path == Some(route_link.path())); let mut classes = "dropdown-item".to_string(); if is_current { @@ -91,9 +92,9 @@ impl Component for Item { classes.push_str(" disabled"); } - let href = (!disabled).then_some(path); - let target = (!disabled && *blank).then_some("_blank"); - let rel = (!disabled && *blank).then_some("noopener noreferrer"); + let href = (!*disabled).then_some(route_link); + let target = (!*disabled && *blank).then_some("_blank"); + let rel = (!*disabled && *blank).then_some("noopener noreferrer"); let aria_current = (href.is_some() && is_current).then_some("page"); let aria_disabled = disabled.then_some("true"); @@ -164,11 +165,15 @@ impl Item { } /// Crea un enlace para la navegación. - pub fn link(label: L10n, path: FnPathByContext) -> Self { + /// + /// La ruta se obtiene invocando [`FnPathByContext`], que devuelve dinámicamente una + /// [`RoutePath`] en función del [`Context`]. El enlace se marca como `active` si la ruta actual + /// del *request* coincide con la ruta de destino (devuelta por `RoutePath::path`). + pub fn link(label: L10n, route: FnPathByContext) -> Self { Item { item_kind: ItemKind::Link { label, - path, + route, blank: false, disabled: false, }, @@ -177,11 +182,11 @@ impl Item { } /// Crea un enlace deshabilitado que no permite la interacción. - pub fn link_disabled(label: L10n, path: FnPathByContext) -> Self { + pub fn link_disabled(label: L10n, route: FnPathByContext) -> Self { Item { item_kind: ItemKind::Link { label, - path, + route, blank: false, disabled: true, }, @@ -190,11 +195,11 @@ impl Item { } /// Crea un enlace que se abre en una nueva ventana o pestaña. - pub fn link_blank(label: L10n, path: FnPathByContext) -> Self { + pub fn link_blank(label: L10n, route: FnPathByContext) -> Self { Item { item_kind: ItemKind::Link { label, - path, + route, blank: true, disabled: false, }, @@ -203,11 +208,11 @@ impl Item { } /// Crea un enlace inicialmente deshabilitado que se abriría en una nueva ventana. - pub fn link_blank_disabled(label: L10n, path: FnPathByContext) -> Self { + pub fn link_blank_disabled(label: L10n, route: FnPathByContext) -> Self { Item { item_kind: ItemKind::Link { label, - path, + route, blank: true, disabled: true, }, diff --git a/extensions/pagetop-bootsier/src/theme/nav/item.rs b/extensions/pagetop-bootsier/src/theme/nav/item.rs index 192f8df8..6c42a76a 100644 --- a/extensions/pagetop-bootsier/src/theme/nav/item.rs +++ b/extensions/pagetop-bootsier/src/theme/nav/item.rs @@ -17,11 +17,12 @@ pub enum ItemKind { Void, /// Etiqueta sin comportamiento interactivo. Label(L10n), - /// Elemento de navegación. Opcionalmente puede abrirse en una nueva ventana y estar - /// inicialmente deshabilitado. + /// Elemento de navegación basado en una [`RoutePath`] dinámica devuelta por + /// [`FnPathByContext`]. Opcionalmente, puede abrirse en una nueva ventana y estar inicialmente + /// deshabilitado. Link { label: L10n, - path: FnPathByContext, + route: FnPathByContext, blank: bool, disabled: bool, }, @@ -71,10 +72,10 @@ impl ItemKind { /// Representa un **elemento individual** de un menú [`Nav`](crate::theme::Nav). /// /// Cada instancia de [`nav::Item`](crate::theme::nav::Item) se traduce en un componente visible que -/// puede comportarse como texto, enlace, botón o menú desplegable según su [`ItemKind`]. +/// puede comportarse como texto, enlace, contenido HTML o menú desplegable, según su [`ItemKind`]. /// -/// Permite definir identificador, clases de estilo adicionales o tipo de interacción asociada, -/// manteniendo una interfaz común para renderizar todos los elementos del menú. +/// Permite definir el identificador, las clases de estilo adicionales y el tipo de interacción +/// asociada, manteniendo una interfaz común para renderizar todos los elementos del menú. #[derive(AutoDefault, Getters)] pub struct Item { #[getters(skip)] @@ -112,13 +113,13 @@ impl Component for Item { ItemKind::Link { label, - path, + route, blank, disabled, } => { - let path = path(cx); + let route_link = route(cx); let current_path = cx.request().map(|request| request.path()); - let is_current = !*disabled && (current_path == Some(&path)); + let is_current = !*disabled && (current_path == Some(route_link.path())); let mut classes = "nav-link".to_string(); if is_current { @@ -128,7 +129,7 @@ impl Component for Item { classes.push_str(" disabled"); } - let href = (!*disabled).then_some(path); + let href = (!*disabled).then_some(route_link); let target = (!*disabled && *blank).then_some("_blank"); let rel = (!*disabled && *blank).then_some("noopener noreferrer"); @@ -202,11 +203,15 @@ impl Item { } /// Crea un enlace para la navegación. - pub fn link(label: L10n, path: FnPathByContext) -> Self { + /// + /// La ruta se obtiene invocando [`FnPathByContext`], que devuelve dinámicamente una + /// [`RoutePath`] en función del [`Context`]. El enlace se marca como `active` si la ruta actual + /// del *request* coincide con la ruta de destino (devuelta por `RoutePath::path`). + pub fn link(label: L10n, route: FnPathByContext) -> Self { Item { item_kind: ItemKind::Link { label, - path, + route, blank: false, disabled: false, }, @@ -215,11 +220,11 @@ impl Item { } /// Crea un enlace deshabilitado que no permite la interacción. - pub fn link_disabled(label: L10n, path: FnPathByContext) -> Self { + pub fn link_disabled(label: L10n, route: FnPathByContext) -> Self { Item { item_kind: ItemKind::Link { label, - path, + route, blank: false, disabled: true, }, @@ -228,11 +233,11 @@ impl Item { } /// Crea un enlace que se abre en una nueva ventana o pestaña. - pub fn link_blank(label: L10n, path: FnPathByContext) -> Self { + pub fn link_blank(label: L10n, route: FnPathByContext) -> Self { Item { item_kind: ItemKind::Link { label, - path, + route, blank: true, disabled: false, }, @@ -241,11 +246,11 @@ impl Item { } /// Crea un enlace inicialmente deshabilitado que se abriría en una nueva ventana. - pub fn link_blank_disabled(label: L10n, path: FnPathByContext) -> Self { + pub fn link_blank_disabled(label: L10n, route: FnPathByContext) -> Self { Item { item_kind: ItemKind::Link { label, - path, + route, blank: true, disabled: true, }, @@ -266,9 +271,9 @@ impl Item { /// Crea un elemento de navegación que contiene un menú desplegable [`Dropdown`]. /// - /// Sólo se tienen en cuenta **el título** (si no existe le asigna uno por defecto) y **la lista - /// de elementos** del [`Dropdown`]; el resto de propiedades del componente no afectarán a su - /// representación en [`Nav`]. + /// Sólo se tienen en cuenta **el título** (si no existe, se asigna uno por defecto) y **la + /// lista de elementos** del [`Dropdown`]; el resto de propiedades del componente no afectarán + /// a su representación en [`Nav`]. pub fn dropdown(menu: Dropdown) -> Self { Item { item_kind: ItemKind::Dropdown(Typed::with(menu)), diff --git a/src/core/component.rs b/src/core/component.rs index b905a495..db959cea 100644 --- a/src/core/component.rs +++ b/src/core/component.rs @@ -1,6 +1,6 @@ //! API para construir nuevos componentes. -use std::borrow::Cow; +use crate::html::RoutePath; mod definition; pub use definition::{Component, ComponentRender}; @@ -66,12 +66,31 @@ pub use context::{Context, ContextError, ContextOp, Contextual}; /// ``` pub type FnIsRenderable = fn(cx: &Context) -> bool; -/// Alias de función (*callback*) para **resolver una URL** según el contexto de renderizado. +/// Alias de función (*callback*) para **resolver una ruta URL** según el contexto de renderizado. /// -/// Se usa para generar enlaces dinámicos en función del contexto (petición, idioma, etc.). El -/// resultado se devuelve como [`Cow<'static, str>`](std::borrow::Cow), lo que permite: +/// Se usa para generar enlaces dinámicos en función del contexto (petición, idioma, parámetros, +/// etc.). El resultado se devuelve como una [`RoutePath`], que representa un *path* base junto con +/// una lista opcional de parámetros de consulta. /// -/// - Usar rutas estáticas sin asignaciones adicionales (`"/path".into()`). -/// - Construir rutas dinámicas en tiempo de ejecución (`format!(...).into()`), por ejemplo, en -/// función de parámetros almacenados en [`Context`]. -pub type FnPathByContext = fn(cx: &Context) -> Cow<'static, str>; +/// Gracias a la implementación de [`RoutePath`] puedes usar rutas estáticas sin asignaciones +/// adicionales: +/// +/// ```rust +/// # use pagetop::prelude::*; +/// # let static_path: FnPathByContext = +/// |_| "/path/to/resource".into() +/// # ; +/// ``` +/// +/// O construir rutas dinámicas en tiempo de ejecución: +/// +/// ```rust +/// # use pagetop::prelude::*; +/// # let dynamic_path: FnPathByContext = +/// |cx| RoutePath::new("/user").with_param("id", cx.param::("user_id").unwrap().to_string()) +/// # ; +/// ``` +/// +/// El componente que reciba un [`FnPathByContext`] invocará esta función durante el renderizado +/// para obtener la URL final para asignarla al atributo HTML correspondiente. +pub type FnPathByContext = fn(cx: &Context) -> RoutePath; diff --git a/src/html.rs b/src/html.rs index d94aeea8..e0725dde 100644 --- a/src/html.rs +++ b/src/html.rs @@ -5,6 +5,9 @@ use crate::AutoDefault; mod maud; pub use maud::{display, html, html_private, Escaper, Markup, PreEscaped, DOCTYPE}; +mod route; +pub use route::RoutePath; + // **< HTML DOCUMENT ASSETS >*********************************************************************** mod assets; diff --git a/src/html/attr_classes.rs b/src/html/attr_classes.rs index bb88f587..57a679bb 100644 --- a/src/html/attr_classes.rs +++ b/src/html/attr_classes.rs @@ -67,14 +67,15 @@ impl AttrClasses { } ClassesOp::Remove => { for class in classes { - self.0.retain(|c| c.ne(&class.to_string())); + self.0.retain(|c| c != class); } } ClassesOp::Replace(classes_to_replace) => { let mut pos = self.0.len(); - let replace: Vec<&str> = classes_to_replace.split_ascii_whitespace().collect(); + let replace = classes_to_replace.to_ascii_lowercase(); + let replace: Vec<&str> = replace.split_ascii_whitespace().collect(); for class in replace { - if let Some(replace_pos) = self.0.iter().position(|c| c.eq(class)) { + if let Some(replace_pos) = self.0.iter().position(|c| c == class) { self.0.remove(replace_pos); if pos > replace_pos { pos = replace_pos; diff --git a/src/html/route.rs b/src/html/route.rs new file mode 100644 index 00000000..c7dac096 --- /dev/null +++ b/src/html/route.rs @@ -0,0 +1,106 @@ +use crate::AutoDefault; + +use std::borrow::Cow; +use std::fmt; + +/// Representa una ruta como un *path* inicial más una lista opcional de parámetros. +/// +/// Modela rutas del estilo `/path/to/resource?foo=bar&debug` o `https://example.com/path?foo=bar`, +/// pensadas para usarse en atributos HTML como `href`, `action` o `src`. +/// +/// `RoutePath` no valida ni interpreta la estructura del *path*; simplemente concatena los +/// parámetros de consulta sobre el valor proporcionado. +/// +/// # Ejemplos +/// +/// ```rust +/// # use pagetop::prelude::*; +/// // Ruta relativa con parámetros y una *flag* sin valor. +/// let route = RoutePath::new("/search") +/// .with_param("q", "rust") +/// .with_param("page", "2") +/// .with_flag("debug"); +/// assert_eq!(route.to_string(), "/search?q=rust&page=2&debug"); +/// +/// // Ruta absoluta a un recurso externo. +/// let external = RoutePath::new("https://example.com/export").with_param("format", "csv"); +/// assert_eq!(external.to_string(), "https://example.com/export?format=csv"); +/// ``` +#[derive(AutoDefault)] +pub struct RoutePath { + // *Path* inicial sobre el que se añadirán los parámetros. + // + // Puede ser relativo (p. ej. `/about`) o una ruta completa (`https://example.com/about`). + // `RoutePath` no realiza ninguna validación ni normalización. + // + // Se almacena como `Cow<'static, str>` para reutilizar literales estáticos sin asignación + // adicional y, al mismo tiempo, aceptar rutas dinámicas representadas como `String`. + path: Cow<'static, str>, + + // Conjunto de parámetros asociados a la ruta. + // + // Cada clave es única y se mantiene el orden de inserción. El valor vacío se utiliza para + // representar *flags* sin valor explícito (por ejemplo `?debug`). + query: indexmap::IndexMap, +} + +impl RoutePath { + /// Crea un `RoutePath` a partir de un *path* inicial. + /// + /// Por ejemplo: `RoutePath::new("/about")`. + pub fn new(path: impl Into>) -> Self { + Self { + path: path.into(), + query: indexmap::IndexMap::new(), + } + } + + /// Añade o sustituye un parámetro `key=value`. Si la clave ya existe, el valor se sobrescribe. + pub fn with_param(mut self, key: impl Into, value: impl Into) -> Self { + self.query.insert(key.into(), value.into()); + self + } + + /// Añade o sustituye un *flag* sin valor, por ejemplo `?debug`. + pub fn with_flag(mut self, flag: impl Into) -> Self { + self.query.insert(flag.into(), String::new()); + self + } + + /// Devuelve el *path* inicial tal y como se pasó a [`RoutePath::new`], sin parámetros. + pub fn path(&self) -> &str { + &self.path + } +} + +impl fmt::Display for RoutePath { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + f.write_str(&self.path)?; + if !self.query.is_empty() { + f.write_str("?")?; + for (i, (key, value)) in self.query.iter().enumerate() { + if i > 0 { + f.write_str("&")?; + } + f.write_str(key)?; + if !value.is_empty() { + f.write_str("=")?; + f.write_str(value)?; + } + } + } + Ok(()) + } +} + +impl From<&'static str> for RoutePath { + fn from(path: &'static str) -> Self { + RoutePath::new(path) + } +} + +impl From for RoutePath { + fn from(path: String) -> Self { + RoutePath::new(path) + } +}