From 144127776dbbad1a2380315fd5adcfc919116dc4 Mon Sep 17 00:00:00 2001 From: Manuel Cillero Date: Thu, 8 Oct 2026 21:19:41 +0200 Subject: [PATCH 1/4] =?UTF-8?q?=E2=99=BB=EF=B8=8F=20(bootsier):=20Renombra?= =?UTF-8?q?=20traits=20de=20extensi=C3=B3n?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Los traits con los que Bootsier añade métodos a componentes del núcleo pasan de `Bootsier` a `BsExt`. SelectBootsier se confundiría con componentes como SelectLanguage. --- extensions/pagetop-bootsier/src/theme.rs | 16 ++++++++-------- extensions/pagetop-bootsier/src/theme/bs.rs | 16 ++++++++-------- .../pagetop-bootsier/src/theme/bs/badge.rs | 6 +++--- .../pagetop-bootsier/src/theme/bs/button.rs | 6 +++--- .../pagetop-bootsier/src/theme/bs/dropdown.rs | 4 ++-- extensions/pagetop-bootsier/src/theme/bs/form.rs | 6 +++--- .../pagetop-bootsier/src/theme/bs/form/input.rs | 4 ++-- .../pagetop-bootsier/src/theme/bs/form/select.rs | 4 ++-- .../src/theme/bs/form/textarea.rs | 4 ++-- extensions/pagetop-bootsier/src/theme/bs/nav.rs | 8 ++++---- .../pagetop-bootsier/src/theme/bs/navbar.rs | 2 +- .../src/theme/bs/navbar/component.rs | 4 ++-- extensions/pagetop-bootsier/tests/badge_color.rs | 2 +- src/core/theme.rs | 4 ++-- 14 files changed, 43 insertions(+), 43 deletions(-) diff --git a/extensions/pagetop-bootsier/src/theme.rs b/extensions/pagetop-bootsier/src/theme.rs index a4c64a20..5dd22b90 100644 --- a/extensions/pagetop-bootsier/src/theme.rs +++ b/extensions/pagetop-bootsier/src/theme.rs @@ -70,21 +70,21 @@ mod token; pub use token::*; #[doc(hidden)] -pub use bs::badge::BadgeBootsier; +pub use bs::badge::BadgeBsExt; #[doc(hidden)] -pub use bs::button::ButtonBootsier; +pub use bs::button::ButtonBsExt; #[doc(hidden)] -pub use bs::dropdown::DropdownBootsier; +pub use bs::dropdown::DropdownBsExt; #[doc(hidden)] -pub use bs::form::input::InputBootsier; +pub use bs::form::input::InputBsExt; #[doc(hidden)] -pub use bs::form::select::SelectBootsier; +pub use bs::form::select::SelectBsExt; #[doc(hidden)] -pub use bs::form::textarea::TextareaBootsier; +pub use bs::form::textarea::TextareaBsExt; #[doc(hidden)] -pub use bs::nav::NavBootsier; +pub use bs::nav::NavBsExt; #[doc(hidden)] -pub use bs::navbar::NavbarBootsier; +pub use bs::navbar::NavbarBsExt; // Añade la clase de un punto de corte con un prefijo y un sufijo (opcional) a la cadena de clases, // separada con un espacio de las que ya hubiera: `prefix-name-suffix`, sin `-suffix` si no hay diff --git a/extensions/pagetop-bootsier/src/theme/bs.rs b/extensions/pagetop-bootsier/src/theme/bs.rs index f829537a..79c577ee 100644 --- a/extensions/pagetop-bootsier/src/theme/bs.rs +++ b/extensions/pagetop-bootsier/src/theme/bs.rs @@ -4,7 +4,7 @@ pub(crate) mod layout; // Badge. pub(crate) mod badge; -pub use badge::{Badge, BadgeBootsier}; +pub use badge::{Badge, BadgeBsExt}; // Block. pub use pagetop::base::component::Block; @@ -20,7 +20,7 @@ pub use pagetop::base::component::breadcrumb; // Button. pub mod button; -pub use button::{Button, ButtonBootsier}; +pub use button::{Button, ButtonBsExt}; // Container. pub mod container; @@ -37,18 +37,18 @@ pub mod dropdown; #[doc(inline)] pub use dropdown::Dropdown; #[doc(inline)] -pub use dropdown::DropdownBootsier; +pub use dropdown::DropdownBsExt; // Form. pub mod form; #[doc(inline)] pub use form::Form; #[doc(inline)] -pub use form::input::InputBootsier; +pub use form::input::InputBsExt; #[doc(inline)] -pub use form::select::SelectBootsier; +pub use form::select::SelectBsExt; #[doc(inline)] -pub use form::textarea::TextareaBootsier; +pub use form::textarea::TextareaBsExt; // Image. pub mod image; @@ -63,14 +63,14 @@ pub mod nav; #[doc(inline)] pub use nav::Nav; #[doc(inline)] -pub use nav::NavBootsier; +pub use nav::NavBsExt; // Navbar. pub mod navbar; #[doc(inline)] pub use navbar::Navbar; #[doc(inline)] -pub use navbar::NavbarBootsier; +pub use navbar::NavbarBsExt; // Offcanvas. pub mod offcanvas; diff --git a/extensions/pagetop-bootsier/src/theme/bs/badge.rs b/extensions/pagetop-bootsier/src/theme/bs/badge.rs index 913ad0d3..dddd475b 100644 --- a/extensions/pagetop-bootsier/src/theme/bs/badge.rs +++ b/extensions/pagetop-bootsier/src/theme/bs/badge.rs @@ -19,14 +19,14 @@ const EXTRA_COLOR: &str = "bootsier.badge.color"; /// let badge = bs::Badge::labeled(Lc::n("Beta")).with_color(BootsierColors::Dark); /// ``` #[builder_impl] -pub trait BadgeBootsier { +pub trait BadgeBsExt { /// Fuerza un color de la paleta de Bootsier, ignorando el que le correspondería a la `Intent` /// del badge. `None` restablece el comportamiento por defecto (color derivado de la `Intent`). fn with_color(self, color: impl Into>) -> Self; } #[builder_impl] -impl BadgeBootsier for Badge { +impl BadgeBsExt for Badge { fn with_color(mut self, color: impl Into>) -> Self { match color.into() { Some(color) => self.alter_prop(PropsOp::set_extra(EXTRA_COLOR, color)), @@ -41,7 +41,7 @@ impl BadgeBootsier for Badge { pub(crate) fn setup(badge: &mut Badge) { // `Badge::setup()` (core) ya ha traducido la intención con `Theme::intent_color()`. La clase // `badge-*` que hay que localizar es siempre la derivada de la `Intent`, con independencia de - // que `BadgeBootsier::with_color()` fuerce un color distinto para el destino `text-bg-*`. + // que `BadgeBsExt::with_color()` fuerce un color distinto para el destino `text-bg-*`. let intent_color = BootsierColors::from(badge.intent()).as_str(); let color = badge .props() diff --git a/extensions/pagetop-bootsier/src/theme/bs/button.rs b/extensions/pagetop-bootsier/src/theme/bs/button.rs index 9ecd8f05..0b55298c 100644 --- a/extensions/pagetop-bootsier/src/theme/bs/button.rs +++ b/extensions/pagetop-bootsier/src/theme/bs/button.rs @@ -10,7 +10,7 @@ const EXTRA_ACTIVE: &str = "bootsier.button.active"; const EXTRA_FULL_WIDTH: &str = "bootsier.button.full_width"; const EXTRA_COLOR: &str = "bootsier.button.color"; -// **< ButtonBootsier >***************************************************************************** +// **< ButtonBsExt >******************************************************************************** /// Extensión de Bootsier para [`Button`]. /// @@ -36,7 +36,7 @@ const EXTRA_COLOR: &str = "bootsier.button.color"; /// .with_color(BootsierColors::Light); /// ``` #[builder_impl] -pub trait ButtonBootsier { +pub trait ButtonBsExt { /// Marca el botón como activo (`.active`, `aria-pressed="true"`). fn with_active(self, active: bool) -> Self; @@ -50,7 +50,7 @@ pub trait ButtonBootsier { } #[builder_impl] -impl ButtonBootsier for Button { +impl ButtonBsExt for Button { fn with_active(mut self, active: bool) -> Self { self.alter_prop(PropsOp::set_extra(EXTRA_ACTIVE, active)); self diff --git a/extensions/pagetop-bootsier/src/theme/bs/dropdown.rs b/extensions/pagetop-bootsier/src/theme/bs/dropdown.rs index f988605f..b5660a19 100644 --- a/extensions/pagetop-bootsier/src/theme/bs/dropdown.rs +++ b/extensions/pagetop-bootsier/src/theme/bs/dropdown.rs @@ -45,7 +45,7 @@ const EXTRA_MENU_POSITION: &str = "bootsier.dropdown.menu_position"; /// .with_item(bs::dropdown::Item::button(Lc::n("Sign out"))); /// ``` #[builder_impl] -pub trait DropdownBootsier { +pub trait DropdownBsExt { /// Indica si el botón del menú está integrado en un grupo de botones. fn with_button_grouped(self, grouped: bool) -> Self; @@ -68,7 +68,7 @@ pub trait DropdownBootsier { } #[builder_impl] -impl DropdownBootsier for Dropdown { +impl DropdownBsExt for Dropdown { fn with_button_grouped(mut self, grouped: bool) -> Self { self.alter_prop(PropsOp::set_extra(EXTRA_BUTTON_GROUPED, grouped)); self diff --git a/extensions/pagetop-bootsier/src/theme/bs/form.rs b/extensions/pagetop-bootsier/src/theme/bs/form.rs index 23050307..98958595 100644 --- a/extensions/pagetop-bootsier/src/theme/bs/form.rs +++ b/extensions/pagetop-bootsier/src/theme/bs/form.rs @@ -14,16 +14,16 @@ pub use pagetop::base::component::form::radio; pub mod select; #[doc(inline)] -pub use select::SelectBootsier; +pub use select::SelectBsExt; pub mod input; #[doc(inline)] -pub use input::InputBootsier; +pub use input::InputBsExt; pub mod textarea; pub use textarea::Textarea; #[doc(inline)] -pub use textarea::TextareaBootsier; +pub use textarea::TextareaBsExt; pub use pagetop::base::component::form::Number; diff --git a/extensions/pagetop-bootsier/src/theme/bs/form/input.rs b/extensions/pagetop-bootsier/src/theme/bs/form/input.rs index be6ac934..b4bc13fc 100644 --- a/extensions/pagetop-bootsier/src/theme/bs/form/input.rs +++ b/extensions/pagetop-bootsier/src/theme/bs/form/input.rs @@ -23,7 +23,7 @@ const EXTRA_FLOATING_LABEL: &str = "bootsier.form.input.floating_label"; /// .with_floating_label(true); /// ``` #[builder_impl] -pub trait InputBootsier { +pub trait InputBsExt { /// Establece si la etiqueta se muestra flotante sobre el campo. /// /// Cuando está activo, la etiqueta se superpone al campo y asciende al enfocarlo o cuando tiene @@ -33,7 +33,7 @@ pub trait InputBootsier { } #[builder_impl] -impl InputBootsier for Field { +impl InputBsExt for Field { fn with_floating_label(mut self, floating: bool) -> Self { self.alter_prop(PropsOp::set_extra(EXTRA_FLOATING_LABEL, floating)); self diff --git a/extensions/pagetop-bootsier/src/theme/bs/form/select.rs b/extensions/pagetop-bootsier/src/theme/bs/form/select.rs index 804a2bfc..d957d225 100644 --- a/extensions/pagetop-bootsier/src/theme/bs/form/select.rs +++ b/extensions/pagetop-bootsier/src/theme/bs/form/select.rs @@ -25,7 +25,7 @@ const EXTRA_FLOATING_LABEL: &str = "bootsier.form.select.floating_label"; /// .with_item(bs::form::select::Item::new("en", Lc::n("English"))); /// ``` #[builder_impl] -pub trait SelectBootsier { +pub trait SelectBsExt { /// Establece si la etiqueta se muestra flotante sobre el campo. /// /// Cuando está activo, la etiqueta se superpone al control y permanece flotante siempre que @@ -38,7 +38,7 @@ pub trait SelectBootsier { } #[builder_impl] -impl SelectBootsier for Field { +impl SelectBsExt for Field { fn with_floating_label(mut self, floating: bool) -> Self { self.alter_prop(PropsOp::set_extra(EXTRA_FLOATING_LABEL, floating)); self diff --git a/extensions/pagetop-bootsier/src/theme/bs/form/textarea.rs b/extensions/pagetop-bootsier/src/theme/bs/form/textarea.rs index fd097e55..d0766437 100644 --- a/extensions/pagetop-bootsier/src/theme/bs/form/textarea.rs +++ b/extensions/pagetop-bootsier/src/theme/bs/form/textarea.rs @@ -23,7 +23,7 @@ const EXTRA_FLOATING_LABEL: &str = "bootsier.form.textarea.floating_label"; /// .with_floating_label(true); /// ``` #[builder_impl] -pub trait TextareaBootsier { +pub trait TextareaBsExt { /// Establece si la etiqueta se muestra flotante sobre el campo. /// /// Cuando está activo, la etiqueta se superpone al área de texto y asciende al enfocarlo o @@ -36,7 +36,7 @@ pub trait TextareaBootsier { } #[builder_impl] -impl TextareaBootsier for Textarea { +impl TextareaBsExt for Textarea { fn with_floating_label(mut self, floating: bool) -> Self { self.alter_prop(PropsOp::set_extra(EXTRA_FLOATING_LABEL, floating)); self diff --git a/extensions/pagetop-bootsier/src/theme/bs/nav.rs b/extensions/pagetop-bootsier/src/theme/bs/nav.rs index 90373526..9994a490 100644 --- a/extensions/pagetop-bootsier/src/theme/bs/nav.rs +++ b/extensions/pagetop-bootsier/src/theme/bs/nav.rs @@ -19,8 +19,8 @@ pub use pagetop::base::component::nav::{Item, ItemKind}; const EXTRA_KIND: &str = "bootsier.nav.kind"; -// Marca interna (nunca expuesta en `NavBootsier`) que `theme::bs::navbar::item` fija sobre el clon -// de un `Nav` embebido en una `Navbar`, para que use `navbar-nav` en vez de `nav` como clase base. +// Marca interna (nunca expuesta en `NavBsExt`) que `theme::bs::navbar::item` fija sobre el clon de +// un `Nav` embebido en una `Navbar`, para que use `navbar-nav` en vez de `nav` como clase base. pub(crate) const EXTRA_IN_NAVBAR: &str = "bootsier.nav.in_navbar"; /// Extensión de Bootsier para [`Nav`]. @@ -47,13 +47,13 @@ pub(crate) const EXTRA_IN_NAVBAR: &str = "bootsier.nav.in_navbar"; /// .with_item(bs::nav::Item::link_disabled(Lc::n("Disabled"), "#")); /// ``` #[builder_impl] -pub trait NavBootsier { +pub trait NavBsExt { /// Cambia el estilo del menú (*Tabs*, *Pills*, *Underline* o *Default*). fn with_kind(self, kind: Kind) -> Self; } #[builder_impl] -impl NavBootsier for Nav { +impl NavBsExt for Nav { fn with_kind(mut self, kind: Kind) -> Self { self.alter_prop(PropsOp::set_extra(EXTRA_KIND, kind)); self diff --git a/extensions/pagetop-bootsier/src/theme/bs/navbar.rs b/extensions/pagetop-bootsier/src/theme/bs/navbar.rs index aae33cd5..74a67ce2 100644 --- a/extensions/pagetop-bootsier/src/theme/bs/navbar.rs +++ b/extensions/pagetop-bootsier/src/theme/bs/navbar.rs @@ -19,7 +19,7 @@ mod panel; pub use panel::Panel; mod component; -pub use component::NavbarBootsier; +pub use component::NavbarBsExt; pub(crate) use component::{render, setup}; mod item; diff --git a/extensions/pagetop-bootsier/src/theme/bs/navbar/component.rs b/extensions/pagetop-bootsier/src/theme/bs/navbar/component.rs index 07d53923..f8728e38 100644 --- a/extensions/pagetop-bootsier/src/theme/bs/navbar/component.rs +++ b/extensions/pagetop-bootsier/src/theme/bs/navbar/component.rs @@ -140,7 +140,7 @@ const EXTRA_LAYOUT: &str = "bootsier.navbar.layout"; /// )); /// ``` #[builder_impl] -pub trait NavbarBootsier { +pub trait NavbarBsExt { /// Crea una barra de navegación cuyo contenido se muestra en un panel lateral. fn offcanvas(panel: bs::navbar::Panel) -> Self; @@ -154,7 +154,7 @@ pub trait NavbarBootsier { } #[builder_impl] -impl NavbarBootsier for Navbar { +impl NavbarBsExt for Navbar { fn offcanvas(panel: bs::navbar::Panel) -> Self { let mut navbar = Self::new(); navbar.alter_prop(PropsOp::set_extra( diff --git a/extensions/pagetop-bootsier/tests/badge_color.rs b/extensions/pagetop-bootsier/tests/badge_color.rs index 1e303538..92fa1e05 100644 --- a/extensions/pagetop-bootsier/tests/badge_color.rs +++ b/extensions/pagetop-bootsier/tests/badge_color.rs @@ -1,4 +1,4 @@ -// Verifies `BadgeBootsier::with_color()`: it overrides the Bootstrap color that `Badge` would +// Verifies `BadgeBsExt::with_color()`: it overrides the Bootstrap color that `Badge` would // otherwise derive from its `Intent`, without disturbing the class that `Badge::setup()` (core) // already generated from that `Intent`. diff --git a/src/core/theme.rs b/src/core/theme.rs index c85b0fe2..43048338 100644 --- a/src/core/theme.rs +++ b/src/core/theme.rs @@ -99,8 +99,8 @@ //! [`PropsOp::set_extra()`] para consumirlos en el `setup()` vía [`Theme::setup_component()`] o //! en el `render()` vía [`Theme::render_component()`]), o aportar componentes propios. //! `pagetop-bootsier` combina las tres estrategias: reexporta `Form`/`Fieldset` sin cambios, -//! extiende `Button`/`Badge`/`Dropdown`/`Nav`/`Navbar` con sus propios traits (`ButtonBootsier`, -//! `BadgeBootsier`, etc.), y añade componentes propios como `Offcanvas`. +//! extiende `Button`/`Badge`/`Dropdown`/`Nav`/`Navbar` con sus propios traits (`ButtonBsExt`, +//! `BadgeBsExt`, etc.), y añade componentes propios como `Offcanvas`. //! //! Para forzar una plantilla completamente distinta en una página concreta, se puede llamar //! manualmente a [`with_template()`]. From fc71a077eec10335a82ad7b25f797fd029d5e3ba Mon Sep 17 00:00:00 2001 From: Manuel Cillero Date: Fri, 9 Oct 2026 00:47:26 +0200 Subject: [PATCH 2/4] =?UTF-8?q?=E2=9C=A8=20(form):=20A=C3=B1ade=20campos?= =?UTF-8?q?=20de=20fecha=20y=20hora=20por=20idioma?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Nuevo `form::date::Field` (fecha, hora y fecha y hora) que muestra el valor en el formato del idioma efectivo (dd/mm/aaaa, mm/dd/yyyy...) y no con el selector nativo, que sigue el formato del navegador. Contextual añade `parse_date()`, `parse_time()` y `parse_datetime()` para leer lo escrito. --- .../pagetop-bootsier/src/theme/bs/form.rs | 8 + src/base/component/form.rs | 2 + src/base/component/form/date.rs | 329 ++++++++++++++++++ src/core/component/context/contextual.rs | 75 +++- src/datetime.rs | 75 +++- src/datetime/input.rs | 144 ++++++++ src/locale/en-GB/datetime.ftl | 15 + src/locale/en-US/datetime.ftl | 13 + src/locale/es-ES/datetime.ftl | 13 + tests/component_form_date.rs | 117 +++++++ tests/datetime_input.rs | 151 ++++++++ 11 files changed, 940 insertions(+), 2 deletions(-) create mode 100644 src/base/component/form/date.rs create mode 100644 src/datetime/input.rs create mode 100644 src/locale/en-GB/datetime.ftl create mode 100644 tests/component_form_date.rs create mode 100644 tests/datetime_input.rs diff --git a/extensions/pagetop-bootsier/src/theme/bs/form.rs b/extensions/pagetop-bootsier/src/theme/bs/form.rs index 98958595..6f6644f9 100644 --- a/extensions/pagetop-bootsier/src/theme/bs/form.rs +++ b/extensions/pagetop-bootsier/src/theme/bs/form.rs @@ -16,6 +16,12 @@ pub mod select; #[doc(inline)] pub use select::SelectBsExt; +pub use pagetop::base::component::form::SelectLanguage; + +pub use pagetop::base::component::form::SelectTheme; + +pub use pagetop::base::component::form::SelectTimezone; + pub mod input; #[doc(inline)] pub use input::InputBsExt; @@ -25,6 +31,8 @@ pub use textarea::Textarea; #[doc(inline)] pub use textarea::TextareaBsExt; +pub use pagetop::base::component::form::date; + pub use pagetop::base::component::form::Number; pub use pagetop::base::component::form::Range; diff --git a/src/base/component/form.rs b/src/base/component/form.rs index f61ff573..2385493a 100644 --- a/src/base/component/form.rs +++ b/src/base/component/form.rs @@ -29,6 +29,8 @@ pub use select_timezone::SelectTimezone; pub mod input; +pub mod date; + mod number; pub use number::Number; diff --git a/src/base/component/form/date.rs b/src/base/component/form/date.rs new file mode 100644 index 00000000..8f888275 --- /dev/null +++ b/src/base/component/form/date.rs @@ -0,0 +1,329 @@ +//! Definiciones para crear campos de fecha y hora. + +use crate::datetime::input; +use crate::prelude::*; + +// **< Kind >*************************************************************************************** + +/// Tipo de dato de un [`form::date::Field`]. +/// +/// Se aplica al crear el campo con [`Field::date()`], [`Field::time()`] o [`Field::datetime()`]. +#[derive(AutoDefault, Clone, Copy, Debug, PartialEq)] +pub enum Kind { + /// Fecha sin hora ([`NaiveDate`]). Es el tipo por defecto. + #[default] + Date, + /// Hora del día ([`NaiveTime`]). + Time, + /// Fecha y hora de un instante ([`DateTime`](DateTime)), en la zona horaria efectiva. + DateTime, +} + +impl Kind { + // Sufijo de la clase CSS del contenedor (`form-field-date`...). + const fn as_str(&self) -> &'static str { + match self { + Kind::Date => "date", + Kind::Time => "time", + Kind::DateTime => "datetime", + } + } +} + +// Valor inicial del campo: un dato con su tipo, que se muestra con el formato del idioma, o el +// texto tal como lo escribió el usuario (para volver a mostrarlo, p. ej. si no se pudo leer). +#[derive(AutoDefault, Clone, Debug)] +enum Value { + #[default] + None, + Date(NaiveDate), + Time(NaiveTime), + DateTime(DateTime), + Text(String), +} + +// **< Field >************************************************************************************** + +/// Componente para crear un **campo de fecha, de hora o de fecha y hora**. +/// +/// Muestra el valor **con el formato del idioma efectivo** del documento, el mismo con el que se +/// muestra el resto de la página y con el que lo leen después los métodos `parse_*` de +/// [`Contextual`]. Por ejemplo, una fecha se escribe `dd/mm/aaaa` en español y `mm/dd/yyyy` en +/// inglés de Estados Unidos, y ese formato se indica en el propio campo (como texto indicativo y +/// como texto de ayuda asociado al campo). Una fecha y hora se muestra y se escribe en la **zona +/// horaria efectiva** del documento ([`Contextual::timezone()`]), normalmente la del usuario, y se +/// lee convertida a UTC. +/// +/// Es un campo de texto (`type="text"`), no un selector nativo (`type="date"`): el navegador +/// muestra los selectores nativos con el formato de **su** configuración regional, no con el del +/// idioma de la página, y la página no puede cambiarlo. +/// +/// - [`Field::date()`]: fecha sin hora ([`NaiveDate`]), p. ej. una fecha de caducidad. No se +/// convierte de zona horaria. +/// - [`Field::time()`]: hora del día ([`NaiveTime`]). +/// - [`Field::datetime()`]: fecha y hora de un instante ([`DateTime`](DateTime)). +/// +/// # Ejemplo +/// +/// ```rust,no_run +/// # use pagetop::prelude::*; +/// # fn build(expires: Option) { +/// let field = form::date::Field::date() +/// .with_name("expires") +/// .with_label(Lc::n("Expiry date")) +/// .with_date(expires) +/// .with_required(true); +/// # } +/// ``` +/// +/// El navegador envía el texto escrito, que se deserializa como `String` y se lee con +/// [`Contextual::parse_date()`], [`Contextual::parse_time()`] o [`Contextual::parse_datetime()`] +/// según el tipo de campo. Si no se puede leer, el error ([`DateInputError`]) tiene un mensaje +/// traducido, y [`with_text()`](Field::with_text) vuelve a mostrar lo que escribió el usuario: +/// +/// ```rust,no_run +/// # use pagetop::prelude::*; +/// # fn handle(cx: &Context, text: String) { +/// match cx.parse_date(&text) { +/// Ok(expires) => { /* Guardar `expires` (`Option`). */ } +/// Err(error) => { +/// let field = form::date::Field::date().with_name("expires").with_text(text); +/// let message = error.message(); // Para mostrarlo junto al formulario. +/// } +/// } +/// # } +/// ``` +#[derive(AutoDefault, Clone, Debug, Getters)] +pub struct Field { + /// Devuelve identificador, clases CSS, atributos HTML y valores extra del componente. + props: Props, + /// Devuelve el tipo de dato del campo. + #[getters(copy)] + kind: Kind, + /// Devuelve el nombre del campo. + name: AttrName, + #[getters(skip)] + value: Value, + /// Devuelve la etiqueta del campo. + label: Lc, + /// Devuelve el texto de ayuda del campo. + help_text: Lc, + /// Devuelve la configuración de autocompletado del campo; sin ella, se desactiva (`off`). + autocomplete: Option, + /// Devuelve si el campo recibe el foco automáticamente al cargar la página. + autofocus: bool, + /// Devuelve si el campo es de sólo lectura. + readonly: bool, + /// Devuelve si el campo es obligatorio. + required: bool, + /// Devuelve si el campo está deshabilitado. + disabled: bool, +} + +#[async_trait] +impl Component for Field { + fn new() -> Self { + Self::default() + } + + fn id(&self) -> Option { + self.props.get_id() + } + + fn setup(&mut self, _cx: &mut Context) { + if let Some(container_id) = self + .id() + .or_else(|| self.name().as_deref().map(|n| util::join!("edit-", n))) + { + self.alter_prop(PropsOp::ensure_id(container_id)); + } + + // Clases CSS del contenedor del campo. + self.alter_prop(PropsOp::prepend_classes(util::join!( + "form-field form-field-", + self.kind().as_str() + ))); + } + + async fn prepare(&self, cx: &mut Context) -> Result { + let container_id = self.id(); + let input_id = container_id.as_deref().map(|id| util::join!(id, "-input")); + let format_id = input_id.as_deref().map(|id| util::join!(id, "-format")); + let tz = cx.timezone(); + let value = match (self.kind(), &self.value) { + (_, Value::Text(text)) => Some(text.clone()), + (Kind::Date, Value::Date(date)) => Some(input::format_date(*date, cx)), + (Kind::Time, Value::Time(time)) => Some(input::format_time(*time, cx)), + (Kind::DateTime, Value::DateTime(dt)) => Some(input::format_datetime(*dt, cx, tz)), + _ => None, + }; + let hint = match self.kind() { + Kind::Date => input::date_hint(cx), + Kind::Time => input::time_hint(cx), + Kind::DateTime => input::datetime_hint(cx), + }; + let format = Lc::l("input_format_help").with_arg("format", hint.clone()); + // Sin autocompletado explícito se desactiva: el navegador sugeriría fechas escritas antes + // en otros formularios, que rara vez son las que se quieren introducir. + let autocomplete = self.autocomplete().unwrap_or(&form::Autocomplete::Off); + Ok(html! { + div (self.props().unpack(cx)) { + @if let Some(label) = self.label().lookup(cx) { + label for=[input_id.as_deref()] class="form-label" { + (label) + @if *self.required() { + span + class="form-required" + title=[Lc::l("field_required").lookup(cx)] + { + "*" + } + } + } + } + input + type="text" + id=[input_id.as_deref()] + class="form-control" + name=[self.name().as_deref()] + value=[value] + placeholder=(hint) + aria-describedby=[format_id.as_deref()] + autocomplete=(autocomplete) + autofocus[*self.autofocus()] + readonly[*self.readonly()] + required[*self.required()] + disabled[*self.disabled()]; + @if let Some(format) = format.lookup(cx) { + div id=[format_id.as_deref()] class="form-text" { (format) } + } + @if let Some(description) = self.help_text().lookup(cx) { + div class="form-text" { (description) } + } + } + }) + } +} + +#[builder_impl] +impl Field { + /// Crea un campo de **fecha sin hora** ([`NaiveDate`]), p. ej. una fecha de nacimiento o de + /// caducidad. Se lee con [`Contextual::parse_date()`]. + pub fn date() -> Self { + Self::default() + } + + /// Crea un campo de **hora del día** ([`NaiveTime`]). Se lee con + /// [`Contextual::parse_time()`]. + pub fn time() -> Self { + Self { + kind: Kind::Time, + ..Default::default() + } + } + + /// Crea un campo de **fecha y hora de un instante** ([`DateTime`](DateTime)), que el + /// usuario ve y escribe en su hora local. Se lee con [`Contextual::parse_datetime()`]. + pub fn datetime() -> Self { + Self { + kind: Kind::DateTime, + ..Default::default() + } + } + + // **< Field BUILDER >************************************************************************** + + /// Establece el identificador único del componente; igual a `with_prop(PropsOp::set_id(id))`. + pub fn with_id(mut self, id: impl Into) -> Self { + self.props.alter_id(id); + self + } + + /// Modifica identificador, clases CSS, atributos HTML o valores extra del componente. + pub fn with_prop(mut self, op: impl Into) -> Self { + self.props.alter_prop(op); + self + } + + /// Establece el nombre del campo (atributo `name`). + pub fn with_name(mut self, name: impl AsRef) -> Self { + self.name.alter_name(name); + self + } + + /// Establece la fecha inicial de un campo de [`Field::date()`] (`None` para dejarlo vacío). En + /// un campo de otro tipo se ignora. + pub fn with_date(mut self, date: impl Into>) -> Self { + self.value = date.into().map_or(Value::None, Value::Date); + self + } + + /// Establece la hora inicial de un campo de [`Field::time()`] (`None` para dejarlo vacío). En + /// un campo de otro tipo se ignora. + pub fn with_time(mut self, time: impl Into>) -> Self { + self.value = time.into().map_or(Value::None, Value::Time); + self + } + + /// Establece el instante inicial de un campo de [`Field::datetime()`] (`None` para dejarlo + /// vacío). Se muestra en la zona horaria efectiva del documento. En un campo de otro tipo se + /// ignora. + pub fn with_datetime(mut self, dt: impl Into>>) -> Self { + self.value = dt.into().map_or(Value::None, Value::DateTime); + self + } + + /// Establece el texto inicial tal cual, sin interpretarlo. Útil para volver a mostrar lo que + /// escribió el usuario cuando no se ha podido leer. + pub fn with_text(mut self, text: impl Into) -> Self { + self.value = Value::Text(text.into()); + self + } + + /// Establece la etiqueta visible del campo (usa [`Lc::none()`] para quitarla). + pub fn with_label(mut self, label: Lc) -> Self { + self.label = label; + self + } + + /// Establece el texto de ayuda del campo (usa [`Lc::none()`] para quitarlo). + pub fn with_help_text(mut self, help_text: Lc) -> Self { + self.help_text = help_text; + self + } + + /// Establece la configuración de autocompletado del campo (`None` para desactivarlo, que es lo + /// predeterminado). Por ejemplo, para una fecha de nacimiento: + /// `form::Autocomplete::token(form::AutofillField::Bday)`. + pub fn with_autocomplete( + mut self, + autocomplete: impl Into>, + ) -> Self { + self.autocomplete = autocomplete.into(); + self + } + + /// Establece si el campo recibe el foco automáticamente al cargar la página. + pub fn with_autofocus(mut self, autofocus: bool) -> Self { + self.autofocus = autofocus; + self + } + + /// Establece si el campo es de sólo lectura. + pub fn with_readonly(mut self, readonly: bool) -> Self { + self.readonly = readonly; + self + } + + /// Establece si el campo es obligatorio. + pub fn with_required(mut self, required: bool) -> Self { + self.required = required; + self + } + + /// Establece si el campo está deshabilitado. + pub fn with_disabled(mut self, disabled: bool) -> Self { + self.disabled = disabled; + self + } +} diff --git a/src/core/component/context/contextual.rs b/src/core/component/context/contextual.rs index 1737bd22..19e2d3e5 100644 --- a/src/core/component/context/contextual.rs +++ b/src/core/component/context/contextual.rs @@ -5,7 +5,7 @@ use crate::builder_impl; use crate::core::component::ChildOp; use crate::core::theme::{RegionRef, TemplateRef, ThemeRef}; use crate::datetime::{DateFormat, DatePrecision, RelativeFormat, TimeFormat}; -use crate::datetime::{DateTime, NaiveDate, Tz, Utc}; +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::web::HttpRequest; @@ -399,6 +399,79 @@ pub trait Contextual: LangId { precision.apply_until(date, self) } + /// Lee una fecha sin hora escrita por el usuario (p. ej. en un + /// [`form::date::Field::date()`](crate::base::component::form::date::Field::date)). + /// + /// Acepta el formato de fecha del idioma efectivo del documento (p. ej. `dd/mm/aaaa` en + /// español o `mm/dd/yyyy` en inglés de Estados Unidos), con día y mes de una o dos cifras y el + /// año siempre con cuatro, y también el formato ISO 8601 (`aaaa-mm-dd`). Es el mismo formato + /// con el que el campo muestra el valor. Una fecha sin hora no se convierte de zona horaria + /// (ver [`format_date()`](Self::format_date)). + /// + /// Devuelve `Ok(None)` si el texto está en blanco; comprobar si el campo es obligatorio queda + /// a cargo de quien llama. + /// + /// # Ejemplo + /// + /// ```rust,no_run + /// # use pagetop::prelude::*; + /// # fn read(cx: &Context, text: &str) -> Result<(), Lc> { + /// let expires: Option = cx.parse_date(text).map_err(|e| e.message())?; + /// # Ok(()) + /// # } + /// ``` + fn parse_date(&self, text: &str) -> Result, DateInputError> + where + Self: Sized, + { + crate::datetime::input::parse_date(text, self) + } + + /// Lee una hora del día escrita por el usuario (p. ej. en un + /// [`form::date::Field::time()`](crate::base::component::form::date::Field::time)). + /// + /// Acepta el formato de hora del idioma efectivo (p. ej. `hh:mm`), con la hora y los minutos de + /// una o dos cifras, y también `hh:mm` en ISO 8601. No se convierte de zona horaria: es una + /// hora civil. Devuelve `Ok(None)` si el texto está en blanco. + fn parse_time(&self, text: &str) -> Result, DateInputError> + where + Self: Sized, + { + crate::datetime::input::parse_time(text, self) + } + + /// Lee una fecha y hora escrita por el usuario en su hora local (p. ej. en un + /// [`form::date::Field::datetime()`](crate::base::component::form::date::Field::datetime)) y + /// la convierte a UTC, que es como se graban siempre los instantes. + /// + /// Acepta el formato del idioma efectivo (la fecha y la hora separadas por un espacio, p. ej. + /// `dd/mm/aaaa hh:mm`) y también ISO 8601 (`aaaa-mm-ddThh:mm`, con `T` o con un espacio entre + /// la fecha y la hora), y lo interpreta en la zona horaria efectiva del documento + /// ([`timezone()`](Self::timezone)). Devuelve `Ok(None)` si el texto está en blanco. + /// + /// En los cambios de hora: + /// + /// - Una hora que no existe, porque el reloj se adelanta (p. ej. las 02:30 del último domingo + /// de marzo en Madrid), devuelve [`DateInputError::NonexistentTime`]. + /// - Una hora que existe dos veces, porque el reloj se retrasa (p. ej. las 02:30 del último + /// domingo de octubre en Madrid), se interpreta como la primera de las dos. + /// + /// # Ejemplo + /// + /// ```rust,no_run + /// # use pagetop::prelude::*; + /// # fn read(cx: &Context, text: &str) -> Result<(), Lc> { + /// let extracted: Option> = cx.parse_datetime(text).map_err(|e| e.message())?; + /// # Ok(()) + /// # } + /// ``` + fn parse_datetime(&self, text: &str) -> Result>, DateInputError> + where + Self: Sized, + { + 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 diff --git a/src/datetime.rs b/src/datetime.rs index 89fdcb5d..7940ceb3 100644 --- a/src/datetime.rs +++ b/src/datetime.rs @@ -23,6 +23,12 @@ //! (`src/locale/{lang}/datetime.ftl`), con el mismo mecanismo que cualquier otro texto traducido de //! PageTop. //! +//! Las fechas y horas que escribe el usuario se leen en el formato del idioma efectivo (p. ej. +//! `dd/mm/aaaa` en español) y, si son instantes, en su hora local, para grabarlas en UTC. Los +//! campos de [`form::date::Field`] las muestran así, y [`Contextual::parse_date()`], +//! [`Contextual::parse_time()`] y [`Contextual::parse_datetime()`] las leen y devuelven un +//! [`DateInputError`] si no se pueden interpretar. +//! //! [`RelativeFormat`] muestra una fecha en relación al momento actual ("hace 3 años", "dentro de 5 //! días") en vez de como fecha absoluta, con el mismo mecanismo de claves Fluent, vía //! [`Contextual::format_relative()`]. @@ -33,12 +39,20 @@ //! [ISO 8601]: https://en.wikipedia.org/wiki/ISO_8601 //! [chrono]: https://docs.rs/chrono //! [chrono-tz]: https://docs.rs/chrono-tz -//! [`CurrentUser::timezone()`]: crate::auth::CurrentUser::timezone //! [`timezone_per_user`]: crate::global::App::timezone_per_user +//! [`CurrentUser::timezone()`]: crate::auth::CurrentUser::timezone +//! [`form::date::Field`]: crate::base::component::form::date::Field //! [`Contextual::format_datetime()`]: crate::core::component::Contextual::format_datetime //! [`Contextual::format_relative()`]: crate::core::component::Contextual::format_relative //! [`Contextual::format_since()`]: crate::core::component::Contextual::format_since //! [`Contextual::format_until()`]: crate::core::component::Contextual::format_until +//! [`Contextual::parse_date()`]: crate::core::component::Contextual::parse_date +//! [`Contextual::parse_time()`]: crate::core::component::Contextual::parse_time +//! [`Contextual::parse_datetime()`]: crate::core::component::Contextual::parse_datetime + +use crate::locale::Lc; + +use thiserror::Error; // Reexportado para que el resto del código y las extensiones se refieran siempre a `datetime::X`, // nunca a `chrono` directamente (mismo criterio que `Tz`/`TZ_VARIANTS` más abajo). No es todo el @@ -79,3 +93,62 @@ pub use relative::RelativeFormat; mod precision; pub use precision::DatePrecision; + +pub(crate) mod input; + +/// Errores al leer una fecha u hora escrita por el usuario. +/// +/// Los devuelven [`Contextual::parse_date()`], [`Contextual::parse_time()`] y +/// [`Contextual::parse_datetime()`]. [`message()`](Self::message) da un mensaje traducido para +/// mostrarlo junto al formulario. +/// +/// [`Contextual::parse_date()`]: crate::core::component::Contextual::parse_date +/// [`Contextual::parse_time()`]: crate::core::component::Contextual::parse_time +/// [`Contextual::parse_datetime()`]: crate::core::component::Contextual::parse_datetime +#[derive(Clone, Debug, Error, PartialEq)] +pub enum DateInputError { + /// La fecha no está escrita en el formato del idioma (`hint`, p. ej. `dd/mm/aaaa`) ni en el + /// formato ISO 8601, o no es una fecha válida (p. ej. `31/02/2026`). + #[error("invalid date, expected format {hint}")] + InvalidDate { + /// Indicación del formato esperado, en el idioma del usuario. + hint: String, + }, + /// La hora no está escrita en el formato del idioma (`hint`, p. ej. `hh:mm`) ni en el formato + /// ISO 8601, o no es una hora válida (p. ej. `25:00`). + #[error("invalid time, expected format {hint}")] + InvalidTime { + /// Indicación del formato esperado, en el idioma del usuario. + hint: String, + }, + /// La fecha y hora no está escrita en el formato del idioma (`hint`, p. ej. `dd/mm/aaaa hh:mm`) + /// ni en el formato ISO 8601, o no es una fecha y hora válida. + #[error("invalid date and time, expected format {hint}")] + InvalidDateTime { + /// Indicación del formato esperado, en el idioma del usuario. + hint: String, + }, + /// La hora no existe en la zona horaria en la que se interpreta (la efectiva del documento) + /// porque coincide con el adelanto del reloj al horario de verano (p. ej. las 02:30 del último + /// domingo de marzo en Madrid). + #[error("nonexistent local time due to a daylight saving time change")] + NonexistentTime, +} + +impl DateInputError { + /// Devuelve un mensaje traducido para el usuario, con el formato esperado si procede. + pub fn message(&self) -> Lc { + match self { + Self::InvalidDate { hint } => { + Lc::l("date_input_invalid").with_arg("format", hint.clone()) + } + Self::InvalidTime { hint } => { + Lc::l("time_input_invalid").with_arg("format", hint.clone()) + } + Self::InvalidDateTime { hint } => { + Lc::l("datetime_input_invalid").with_arg("format", hint.clone()) + } + Self::NonexistentTime => Lc::l("datetime_input_nonexistent"), + } + } +} diff --git a/src/datetime/input.rs b/src/datetime/input.rs new file mode 100644 index 00000000..22f06c63 --- /dev/null +++ b/src/datetime/input.rs @@ -0,0 +1,144 @@ +use crate::locale::{LangId, Lc}; + +use super::{DateInputError, DateTime, NaiveDate, NaiveDateTime, NaiveTime, TimeZone, Tz, Utc}; + +use chrono::LocalResult; + +// Patrones de respaldo (ISO 8601), sólo si faltase la clave Fluent del idioma (no debería ocurrir +// porque el idioma de respaldo `en-US` siempre las define). +const FALLBACK_DATE_FORMAT: &str = "%Y-%m-%d"; +const FALLBACK_TIME_FORMAT: &str = "%H:%M"; + +// Formatos ISO 8601 que se aceptan siempre, además del propio del idioma, para no rechazar un valor +// pegado de otra fuente. No hay ambigüedad posible: empiezan por el año con cuatro cifras. +const ISO_DATE: &str = "%Y-%m-%d"; +const ISO_TIME: &str = "%H:%M"; +const ISO_DATETIME: [&str; 2] = ["%Y-%m-%dT%H:%M", "%Y-%m-%d %H:%M"]; + +// Años admitidos. `chrono` acepta `%Y` con cualquier número de cifras, así que "06/10/26" se leería +// como el año 26; se rechaza para que no pase inadvertido un año escrito con dos cifras. +const YEARS: std::ops::RangeInclusive = 1000..=9999; + +// Patrón `strftime` de fecha del idioma, el mismo para mostrar y para leer (p. ej. `%d/%m/%Y`). +pub(crate) fn date_format(language: &impl LangId) -> String { + Lc::l("date_input_format") + .lookup(language) + .unwrap_or_else(|| FALLBACK_DATE_FORMAT.to_string()) +} + +// Patrón `strftime` de hora del idioma (p. ej. `%H:%M`). +pub(crate) fn time_format(language: &impl LangId) -> String { + Lc::l("time_input_format") + .lookup(language) + .unwrap_or_else(|| FALLBACK_TIME_FORMAT.to_string()) +} + +// Patrón de fecha y hora: el de fecha y el de hora separados por un espacio. +pub(crate) fn datetime_format(language: &impl LangId) -> String { + let (date, time) = (date_format(language), time_format(language)); + crate::util::join!(date, " ", time) +} + +// Indicación del formato para el usuario (p. ej. `dd/mm/aaaa`). +pub(crate) fn date_hint(language: &impl LangId) -> String { + Lc::l("date_input_hint") + .lookup(language) + .unwrap_or_else(|| "yyyy-mm-dd".to_string()) +} + +// Indicación del formato de hora para el usuario (p. ej. `hh:mm`). +pub(crate) fn time_hint(language: &impl LangId) -> String { + Lc::l("time_input_hint") + .lookup(language) + .unwrap_or_else(|| "hh:mm".to_string()) +} + +// Indicación del formato de fecha y hora para el usuario (p. ej. `dd/mm/aaaa hh:mm`). +pub(crate) fn datetime_hint(language: &impl LangId) -> String { + let (date, time) = (date_hint(language), time_hint(language)); + crate::util::join!(date, " ", time) +} + +// Lee una fecha con el formato del idioma o en ISO 8601. En blanco devuelve `None`. +pub(crate) fn parse_date( + text: &str, + language: &impl LangId, +) -> Result, DateInputError> { + let text = text.trim(); + if text.is_empty() { + return Ok(None); + } + [date_format(language).as_str(), ISO_DATE] + .into_iter() + .find_map(|format| NaiveDate::parse_from_str(text, format).ok()) + .filter(|date| YEARS.contains(&chrono::Datelike::year(date))) + .map(Some) + .ok_or_else(|| DateInputError::InvalidDate { + hint: date_hint(language), + }) +} + +// Lee una hora con el formato del idioma o en ISO 8601. En blanco devuelve `None`. +pub(crate) fn parse_time( + text: &str, + language: &impl LangId, +) -> Result, DateInputError> { + let text = text.trim(); + if text.is_empty() { + return Ok(None); + } + [time_format(language).as_str(), ISO_TIME] + .into_iter() + .find_map(|format| NaiveTime::parse_from_str(text, format).ok()) + .map(Some) + .ok_or_else(|| DateInputError::InvalidTime { + hint: time_hint(language), + }) +} + +// Lee una fecha y hora local de `tz`, con el formato del idioma o en ISO 8601, y la convierte a +// UTC. En blanco devuelve `None`. +// +// En el cambio al horario de verano hay horas que no existen en `tz` (p. ej. las 02:30 del último +// domingo de marzo en Madrid): se rechazan, porque cualquier corrección inventaría una hora que el +// usuario no ha escrito. En el cambio al horario de invierno hay horas que existen dos veces: se +// toma la primera porque el usuario no tiene forma de indicar cuál de las dos quería. +pub(crate) fn parse_datetime( + text: &str, + language: &impl LangId, + tz: Tz, +) -> Result>, DateInputError> { + let text = text.trim(); + if text.is_empty() { + return Ok(None); + } + let format = datetime_format(language); + let local = std::iter::once(format.as_str()) + .chain(ISO_DATETIME) + .find_map(|format| NaiveDateTime::parse_from_str(text, format).ok()) + .filter(|local| YEARS.contains(&chrono::Datelike::year(local))) + .ok_or_else(|| DateInputError::InvalidDateTime { + hint: datetime_hint(language), + })?; + match tz.from_local_datetime(&local) { + LocalResult::Single(dt) | LocalResult::Ambiguous(dt, _) => Ok(Some(dt.with_timezone(&Utc))), + LocalResult::None => Err(DateInputError::NonexistentTime), + } +} + +// Muestra una fecha con el formato del idioma, tal como se lee después. +pub(crate) fn format_date(date: NaiveDate, language: &impl LangId) -> String { + date.format(&date_format(language)).to_string() +} + +// Muestra una hora con el formato del idioma, tal como se lee después. +pub(crate) fn format_time(time: NaiveTime, language: &impl LangId) -> String { + time.format(&time_format(language)).to_string() +} + +// Muestra un instante en `tz` con el formato del idioma, tal como se lee después. +pub(crate) fn format_datetime(dt: DateTime, language: &impl LangId, tz: Tz) -> String { + dt.with_timezone(&tz) + .format(&datetime_format(language)) + .to_string() +} diff --git a/src/locale/en-GB/datetime.ftl b/src/locale/en-GB/datetime.ftl new file mode 100644 index 00000000..d61b6e01 --- /dev/null +++ b/src/locale/en-GB/datetime.ftl @@ -0,0 +1,15 @@ +# British English writes the day before the month. Only these keys differ from en-US; the rest +# fall back to en-US. + +# Date formats. +date_format_short = { $day }/{ $month }/{ $year_short } +date_format_medium = { $day }/{ $month }/{ $year } +date_format_long = { $day } { $month } { $year } + +# Date input (strftime pattern, see en-US). +date_input_format = %d/%m/%Y +date_input_hint = dd/mm/yyyy + +# Start/end date precision. +since_long = since { $day } { $month } { $year } +until_long = until { $day } { $month } { $year } diff --git a/src/locale/en-US/datetime.ftl b/src/locale/en-US/datetime.ftl index 4e7710a8..2590e110 100644 --- a/src/locale/en-US/datetime.ftl +++ b/src/locale/en-US/datetime.ftl @@ -8,6 +8,19 @@ time_format_short = { $hour }:{ $minute } time_format_long = { $hour }:{ $minute }:{ $second } datetime_join = { $date }, { $time } +# Date and time input. `date_input_format` and `time_input_format` are strftime patterns (%d day, +# %m month, %Y four-digit year, %H hour, %M minute), not text: they are used both to show a value +# and to read what the user types. Keep the date one in the same order as `date_format_medium`. +date_input_format = %m/%d/%Y +date_input_hint = mm/dd/yyyy +time_input_format = %H:%M +time_input_hint = hh:mm +input_format_help = Format: { $format } +date_input_invalid = Invalid date: use the format { $format }. +time_input_invalid = Invalid time: use the format { $format }. +datetime_input_invalid = Invalid date and time: use the format { $format }. +datetime_input_nonexistent = That time does not exist in your time zone: the clock moves forward for daylight saving time. + # Relative dates. relative_today = today relative_years = { $n -> diff --git a/src/locale/es-ES/datetime.ftl b/src/locale/es-ES/datetime.ftl index 76015715..f1880315 100644 --- a/src/locale/es-ES/datetime.ftl +++ b/src/locale/es-ES/datetime.ftl @@ -8,6 +8,19 @@ time_format_short = { $hour }:{ $minute } time_format_long = { $hour }:{ $minute }:{ $second } datetime_join = { $date }, { $time } +# Date and time input. `date_input_format` and `time_input_format` are strftime patterns (%d day, +# %m month, %Y four-digit year, %H hour, %M minute), not text: they are used both to show a value +# and to read what the user types. Keep the date one in the same order as `date_format_medium`. +date_input_format = %d/%m/%Y +date_input_hint = dd/mm/aaaa +time_input_format = %H:%M +time_input_hint = hh:mm +input_format_help = Formato: { $format } +date_input_invalid = Fecha no válida: usa el formato { $format }. +time_input_invalid = Hora no válida: usa el formato { $format }. +datetime_input_invalid = Fecha y hora no válidas: usa el formato { $format }. +datetime_input_nonexistent = Esa hora no existe en tu zona horaria: coincide con el adelanto del reloj al horario de verano. + # Relative dates. relative_today = hoy relative_years = { $n -> diff --git a/tests/component_form_date.rs b/tests/component_form_date.rs new file mode 100644 index 00000000..deee11cb --- /dev/null +++ b/tests/component_form_date.rs @@ -0,0 +1,117 @@ +use pagetop::prelude::*; + +fn cx(language: &str, timezone: &str) -> Context { + Context::default() + .with_langid(&Locale::resolve(language)) + .with_timezone(timezone.parse().unwrap()) +} + +#[pagetop::test] +async fn dates_are_shown_in_the_format_of_the_language() { + let date = NaiveDate::from_ymd_opt(2026, 10, 6).unwrap(); + + let mut field = form::date::Field::date() + .with_name("expires") + .with_date(date); + let html = field.render(&mut cx("es-ES", "UTC")).await.into_string(); + assert!(html.contains(r#"value="06/10/2026""#)); + assert!(html.contains(r#"placeholder="dd/mm/aaaa""#)); + assert!(html.contains("form-field form-field-date")); + + let html = field.render(&mut cx("en-US", "UTC")).await.into_string(); + assert!(html.contains(r#"value="10/06/2026""#)); + assert!(html.contains(r#"placeholder="mm/dd/yyyy""#)); +} + +#[pagetop::test] +async fn datetimes_are_shown_in_the_local_time_of_the_user() { + let dt = Utc.with_ymd_and_hms(2026, 10, 6, 12, 30, 0).unwrap(); + + let mut field = form::date::Field::datetime() + .with_name("at") + .with_datetime(dt); + let html = field + .render(&mut cx("es-ES", "Europe/Madrid")) + .await + .into_string(); + assert!(html.contains(r#"value="06/10/2026 14:30""#)); + assert!(html.contains(r#"placeholder="dd/mm/aaaa hh:mm""#)); +} + +#[pagetop::test] +async fn shown_values_are_read_back_unchanged() { + let dt = Utc.with_ymd_and_hms(2026, 10, 6, 12, 30, 0).unwrap(); + let mut cx = cx("en-US", "America/New_York"); + + let mut field = form::date::Field::datetime() + .with_name("at") + .with_datetime(dt); + let html = field.render(&mut cx).await.into_string(); + let value = html + .split(r#"value=""#) + .nth(1) + .unwrap() + .split('"') + .next() + .unwrap(); + assert_eq!(cx.parse_datetime(value), Ok(Some(dt))); +} + +#[pagetop::test] +async fn text_is_shown_as_written_and_empty_fields_have_no_value() { + let mut field = form::date::Field::time().with_name("at").with_text("25:99"); + let html = field.render(&mut cx("es-ES", "UTC")).await.into_string(); + assert!(html.contains(r#"value="25:99""#)); + assert!(html.contains("form-field form-field-time")); + + let mut empty = form::date::Field::date().with_name("expires"); + let html = empty.render(&mut cx("es-ES", "UTC")).await.into_string(); + assert!(!html.contains("value=")); +} + +#[pagetop::test] +async fn a_value_of_another_kind_is_ignored() { + let date = NaiveDate::from_ymd_opt(2026, 10, 6).unwrap(); + let mut field = form::date::Field::time().with_name("at").with_date(date); + let html = field.render(&mut cx("es-ES", "UTC")).await.into_string(); + assert!(!html.contains("value=")); +} + +// The format stays visible (and is announced by screen readers) once the placeholder is gone. +#[pagetop::test] +async fn the_format_is_also_a_help_text_linked_to_the_input() { + let mut field = form::date::Field::date().with_name("expires"); + let html = field.render(&mut cx("es-ES", "UTC")).await.into_string(); + assert!(html.contains(r#"aria-describedby="edit-expires-input-format""#)); + assert!(html.contains( + r#"
Formato: dd/mm/aaaa
"# + )); +} + +#[pagetop::test] +async fn autocomplete_is_off_unless_set() { + let mut field = form::date::Field::date().with_name("born"); + let html = field.render(&mut cx("es-ES", "UTC")).await.into_string(); + assert!(html.contains(r#"autocomplete="off""#)); + + let mut field = form::date::Field::date() + .with_name("born") + .with_autocomplete(form::Autocomplete::token(form::AutofillField::Bday)); + let html = field.render(&mut cx("es-ES", "UTC")).await.into_string(); + assert!(html.contains(r#"autocomplete="bday""#)); +} + +#[pagetop::test] +async fn required_readonly_and_disabled_are_rendered() { + let mut field = form::date::Field::date() + .with_name("expires") + .with_label(Lc::n("Expires")) + .with_required(true) + .with_readonly(true) + .with_disabled(true); + let html = field.render(&mut cx("es-ES", "UTC")).await.into_string(); + assert!(html.contains(r#"class="form-required""#)); + assert!(html.contains(" readonly")); + assert!(html.contains(" required")); + assert!(html.contains(" disabled")); +} diff --git a/tests/datetime_input.rs b/tests/datetime_input.rs new file mode 100644 index 00000000..b2cc2dd6 --- /dev/null +++ b/tests/datetime_input.rs @@ -0,0 +1,151 @@ +use pagetop::prelude::*; + +async fn setup() { + Application::new().await; +} + +fn cx(language: &str, timezone: &str) -> Context { + Context::default() + .with_langid(&Locale::resolve(language)) + .with_timezone(timezone.parse().unwrap()) +} + +fn date(y: i32, m: u32, d: u32) -> NaiveDate { + NaiveDate::from_ymd_opt(y, m, d).unwrap() +} + +fn utc(y: i32, m: u32, d: u32, h: u32, min: u32) -> DateTime { + Utc.with_ymd_and_hms(y, m, d, h, min, 0).unwrap() +} + +// **< Contextual::parse_date() >******************************************************************* + +#[pagetop::test] +async fn dates_are_read_in_the_format_of_the_language() { + setup().await; + + let es = cx("es-ES", "UTC"); + assert_eq!(es.parse_date("06/10/2026"), Ok(Some(date(2026, 10, 6)))); + assert_eq!(es.parse_date(" 6/1/2026 "), Ok(Some(date(2026, 1, 6)))); + + let en = cx("en-US", "UTC"); + assert_eq!(en.parse_date("10/06/2026"), Ok(Some(date(2026, 10, 6)))); +} + +// British English has no translations of its own except the day-first date formats; the rest falls +// back to en-US. Reading 06/10/2026 month first would silently store 10 June instead of 6 October. +#[pagetop::test] +async fn british_english_reads_and_shows_the_day_first() { + setup().await; + + let gb = cx("en-GB", "UTC"); + assert_eq!(gb.parse_date("06/10/2026"), Ok(Some(date(2026, 10, 6)))); + assert_eq!( + gb.parse_date("10/31/2026"), + Err(DateInputError::InvalidDate { + hint: "dd/mm/yyyy".to_string() + }) + ); + assert_eq!( + gb.format_date(date(2026, 10, 6), DateFormat::Medium), + "06/10/2026" + ); + assert_eq!( + gb.format_date(date(2026, 10, 6), DateFormat::Long), + "6 October 2026" + ); + assert_eq!( + Lc::l("relative_today").lookup(&gb).as_deref(), + Some("today") + ); +} + +#[pagetop::test] +async fn dates_also_accept_iso_and_blank_is_none() { + setup().await; + + let es = cx("es-ES", "UTC"); + assert_eq!(es.parse_date("2026-10-06"), Ok(Some(date(2026, 10, 6)))); + assert_eq!(es.parse_date(" "), Ok(None)); +} + +#[pagetop::test] +async fn invalid_dates_report_the_expected_format() { + setup().await; + + let es = cx("es-ES", "UTC"); + let expected = Err(DateInputError::InvalidDate { + hint: "dd/mm/aaaa".to_string(), + }); + // A two-digit year would otherwise be read as year 26. + assert_eq!(es.parse_date("06/10/26"), expected); + assert_eq!(es.parse_date("31/02/2026"), expected); + assert_eq!(es.parse_date("10/31/2026"), expected); + + let message = es.parse_date("x").unwrap_err().message(); + assert_eq!( + message.lookup(&es).as_deref(), + Some("Fecha no válida: usa el formato dd/mm/aaaa.") + ); +} + +// **< Contextual::parse_time() >******************************************************************* + +#[pagetop::test] +async fn times_are_read_with_one_or_two_digit_hours_and_minutes() { + setup().await; + + let es = cx("es-ES", "UTC"); + assert_eq!(es.parse_time("9:05"), Ok(NaiveTime::from_hms_opt(9, 5, 0))); + assert_eq!(es.parse_time("9:5"), Ok(NaiveTime::from_hms_opt(9, 5, 0))); + assert_eq!( + es.parse_time("14:30"), + Ok(NaiveTime::from_hms_opt(14, 30, 0)) + ); + assert!(matches!( + es.parse_time("25:00"), + Err(DateInputError::InvalidTime { .. }) + )); +} + +// **< Contextual::parse_datetime() >*************************************************************** + +#[pagetop::test] +async fn datetimes_are_read_in_the_local_time_of_the_user() { + setup().await; + + // Madrid is UTC+2 in October (summer time). + let es = cx("es-ES", "Europe/Madrid"); + let expected = Ok(Some(utc(2026, 10, 6, 12, 30))); + assert_eq!(es.parse_datetime("06/10/2026 14:30"), expected); + assert_eq!(es.parse_datetime("2026-10-06T14:30"), expected); + assert_eq!(es.parse_datetime("2026-10-06 14:30"), expected); + + let en = cx("en-US", "Europe/Madrid"); + assert_eq!(en.parse_datetime("10/06/2026 14:30"), expected); +} + +#[pagetop::test] +async fn nonexistent_local_times_are_rejected() { + setup().await; + + // On 2026-03-29 Madrid clocks jump from 02:00 to 03:00. + let es = cx("es-ES", "Europe/Madrid"); + assert_eq!( + es.parse_datetime("29/03/2026 02:30"), + Err(DateInputError::NonexistentTime) + ); +} + +#[pagetop::test] +async fn ambiguous_local_times_take_the_first_occurrence() { + setup().await; + + // On 2026-10-25 Madrid clocks go back from 03:00 to 02:00, so 02:30 happens twice: first at + // UTC+2 (00:30 UTC), then at UTC+1 (01:30 UTC). + let es = cx("es-ES", "Europe/Madrid"); + assert_eq!( + es.parse_datetime("25/10/2026 02:30"), + Ok(Some(utc(2026, 10, 25, 0, 30))) + ); +} From 8690f994c3231ca8b6d374378cf9d925f2ca68b8 Mon Sep 17 00:00:00 2001 From: Manuel Cillero Date: Fri, 9 Oct 2026 00:59:43 +0200 Subject: [PATCH 3/4] =?UTF-8?q?=E2=99=BF=EF=B8=8F=20(form):=20Enlaza=20ayu?= =?UTF-8?q?da=20de=20los=20campos=20a=20su=20control?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../src/theme/bs/form/input.rs | 6 +- .../src/theme/bs/form/select.rs | 6 +- .../src/theme/bs/form/textarea.rs | 6 +- .../pagetop-bootsier/tests/form_help_text.rs | 57 +++++++ src/base/component/form.rs | 3 + src/base/component/form/check.rs | 19 ++- src/base/component/form/date.rs | 19 ++- src/base/component/form/field_help.rs | 70 ++++++++ src/base/component/form/input.rs | 6 +- src/base/component/form/number.rs | 6 +- src/base/component/form/radio.rs | 19 ++- src/base/component/form/range.rs | 6 +- src/base/component/form/select.rs | 6 +- src/base/component/form/textarea.rs | 6 +- tests/component_form_help_text.rs | 150 ++++++++++++++++++ 15 files changed, 341 insertions(+), 44 deletions(-) create mode 100644 extensions/pagetop-bootsier/tests/form_help_text.rs create mode 100644 src/base/component/form/field_help.rs create mode 100644 tests/component_form_help_text.rs diff --git a/extensions/pagetop-bootsier/src/theme/bs/form/input.rs b/extensions/pagetop-bootsier/src/theme/bs/form/input.rs index b4bc13fc..20ba1839 100644 --- a/extensions/pagetop-bootsier/src/theme/bs/form/input.rs +++ b/extensions/pagetop-bootsier/src/theme/bs/form/input.rs @@ -55,6 +55,7 @@ pub(crate) fn setup(field: &mut Field) { pub(crate) fn render(field: &Field, cx: &mut Context) -> Result { let container_id = field.id(); let input_id = container_id.as_deref().map(|id| util::join!(id, "-input")); + let help = form::FieldHelp::new(field.help_text(), input_id.as_deref(), cx); let input_class = if *field.plaintext() { "form-control-plaintext" } else { @@ -99,6 +100,7 @@ pub(crate) fn render(field: &Field, cx: &mut Context) -> Result Result Result { let container_id = field.id(); let select_id = container_id.as_deref().map(|id| util::join!(id, "-select")); + let help = form::FieldHelp::new(field.help_text(), select_id.as_deref(), cx); let floating = field.props().extra_or(EXTRA_FLOATING_LABEL, false); let label = match field.label().lookup(cx) { Some(text) => html! { @@ -84,6 +85,7 @@ pub(crate) fn render(field: &Field, cx: &mut Context) -> Result Result Result Result Result String { + component + .render(&mut Context::default().with_theme(&Bootsier)) + .await + .into_string() +} + +#[pagetop::test] +async fn bootsier_fields_point_to_their_help_text() { + let help = || Lc::n("Help"); + let cases: [(String, &str); 3] = [ + ( + render( + &mut bs::form::input::Field::text() + .with_name("a") + .with_help_text(help()), + ) + .await, + "edit-a-input-help", + ), + ( + render( + &mut bs::form::select::Field::new() + .with_name("b") + .with_help_text(help()), + ) + .await, + "edit-b-select-help", + ), + ( + render( + &mut bs::form::Textarea::new() + .with_name("c") + .with_help_text(help()), + ) + .await, + "edit-c-textarea-help", + ), + ]; + for (html, id) in cases { + assert!( + html.contains(&format!(r#"aria-describedby="{id}""#)), + "{html}" + ); + assert!( + html.contains(&format!(r#"
Help
"#)), + "{html}" + ); + } +} diff --git a/src/base/component/form.rs b/src/base/component/form.rs index 2385493a..c0bb9e6f 100644 --- a/src/base/component/form.rs +++ b/src/base/component/form.rs @@ -6,6 +6,9 @@ pub use props::{Autocomplete, AutofillField, CheckboxKind, Method}; mod component; pub use component::Form; +mod field_help; +pub use field_help::FieldHelp; + mod fieldset; pub use fieldset::Fieldset; diff --git a/src/base/component/form/check.rs b/src/base/component/form/check.rs index bcd7c9c0..0ac05676 100644 --- a/src/base/component/form/check.rs +++ b/src/base/component/form/check.rs @@ -142,11 +142,20 @@ impl Component for Field { // En `setup()` se garantiza que `name` e `id` están definidos antes del renderizado. let name = self.name().as_deref().unwrap(); let container_id = self.id().unwrap(); + // El contenedor agrupa las opciones: su etiqueta y su texto de ayuda describen al grupo. + let label = self.label().lookup(cx); + let label_id = label.as_ref().map(|_| util::join!(&container_id, "-label")); + let help = form::FieldHelp::new(self.help_text(), Some(&container_id), cx); Ok(html! { - div (self.props().unpack(cx)) { - @if let Some(label) = self.label().lookup(cx) { - label class="form-label" { (label) } + div + (self.props().unpack(cx)) + role="group" + aria-labelledby=[label_id.as_deref()] + aria-describedby=[help.id()] + { + @if let Some(label) = label { + label id=[label_id.as_deref()] class="form-label" { (label) } } @let item_classes = if *self.inline() { "form-check form-check-inline" @@ -170,9 +179,7 @@ impl Component for Field { } } } - @if let Some(description) = self.help_text().lookup(cx) { - div class="form-text" { (description) } - } + (help) } }) } diff --git a/src/base/component/form/date.rs b/src/base/component/form/date.rs index 8f888275..311fdabc 100644 --- a/src/base/component/form/date.rs +++ b/src/base/component/form/date.rs @@ -148,7 +148,6 @@ impl Component for Field { async fn prepare(&self, cx: &mut Context) -> Result { let container_id = self.id(); let input_id = container_id.as_deref().map(|id| util::join!(id, "-input")); - let format_id = input_id.as_deref().map(|id| util::join!(id, "-format")); let tz = cx.timezone(); let value = match (self.kind(), &self.value) { (_, Value::Text(text)) => Some(text.clone()), @@ -163,6 +162,14 @@ impl Component for Field { Kind::DateTime => input::datetime_hint(cx), }; let format = Lc::l("input_format_help").with_arg("format", hint.clone()); + let format = form::FieldHelp::suffixed(&format, input_id.as_deref(), "-format", cx); + let help = form::FieldHelp::new(self.help_text(), input_id.as_deref(), cx); + // El formato y, si lo hay, el texto de ayuda describen el campo, en ese orden. + let described_by = util::join_pair!( + format.id().unwrap_or_default(), + " ", + help.id().unwrap_or_default() + ); // Sin autocompletado explícito se desactiva: el navegador sugeriría fechas escritas antes // en otros formularios, que rara vez son las que se quieren introducir. let autocomplete = self.autocomplete().unwrap_or(&form::Autocomplete::Off); @@ -188,18 +195,14 @@ impl Component for Field { name=[self.name().as_deref()] value=[value] placeholder=(hint) - aria-describedby=[format_id.as_deref()] + aria-describedby=[util::non_blank(&described_by)] autocomplete=(autocomplete) autofocus[*self.autofocus()] readonly[*self.readonly()] required[*self.required()] disabled[*self.disabled()]; - @if let Some(format) = format.lookup(cx) { - div id=[format_id.as_deref()] class="form-text" { (format) } - } - @if let Some(description) = self.help_text().lookup(cx) { - div class="form-text" { (description) } - } + (format) + (help) } }) } diff --git a/src/base/component/form/field_help.rs b/src/base/component/form/field_help.rs new file mode 100644 index 00000000..fa700a14 --- /dev/null +++ b/src/base/component/form/field_help.rs @@ -0,0 +1,70 @@ +use crate::prelude::*; + +/// Texto de ayuda de un campo de formulario, ya traducido, con el identificador que lo enlaza a su +/// control. +/// +/// Lo usan los campos de formulario (y los temas que pintan su propio marcado) para mostrar el +/// texto de ayuda bajo el control y enlazarlo con `aria-describedby`, de modo que los lectores de +/// pantalla lo anuncien al entrar en el campo. Se inserta en [`html!`] como cualquier otro valor: +/// genera `
...
`, o nada si no hay texto. +/// +/// # Ejemplo +/// +/// ```rust,no_run +/// # use pagetop::prelude::*; +/// # fn render(help_text: &Lc, input_id: Option<&str>, cx: &Context) -> Markup { +/// let help = form::FieldHelp::new(help_text, input_id, cx); +/// html! { +/// input type="text" id=[input_id] aria-describedby=[help.id()]; +/// (help) +/// } +/// # } +/// ``` +#[derive(Clone, Debug)] +pub struct FieldHelp { + text: Option, + id: Option, +} + +impl FieldHelp { + /// Traduce `help_text` y, si hay texto, le asigna el identificador `{anchor_id}-help`, donde + /// `anchor_id` es el identificador del control (o del contenedor, si el texto describe a un + /// grupo de controles). Sin `anchor_id` el texto se muestra igual, pero sin identificador. + pub fn new(help_text: &Lc, anchor_id: Option<&str>, language: &impl LangId) -> Self { + Self::suffixed(help_text, anchor_id, "-help", language) + } + + /// Igual que [`new()`](Self::new), pero con otro sufijo para el identificador; útil cuando un + /// mismo control tiene más de un texto que lo describe. + pub fn suffixed( + help_text: &Lc, + anchor_id: Option<&str>, + suffix: &str, + language: &impl LangId, + ) -> Self { + let text = help_text.lookup(language); + // Sin texto no hay nada que enlazar, y sin identificador del control no hay de qué derivar + // uno: en ambos casos se omite el identificador para no dejar una referencia rota. + let id = text + .as_ref() + .and(anchor_id) + .map(|anchor_id| util::join!(anchor_id, suffix)); + Self { text, id } + } + + /// Devuelve el identificador para `aria-describedby`, o `None` si no hay texto o si el control + /// no tiene identificador. + pub fn id(&self) -> Option<&str> { + self.id.as_deref() + } +} + +impl Render for FieldHelp { + fn render(&self) -> Markup { + html! { + @if let Some(text) = &self.text { + div id=[self.id()] class="form-text" { (text) } + } + } + } +} diff --git a/src/base/component/form/input.rs b/src/base/component/form/input.rs index 8da1b719..1114c4e6 100644 --- a/src/base/component/form/input.rs +++ b/src/base/component/form/input.rs @@ -220,6 +220,7 @@ impl Component for Field { async fn prepare(&self, cx: &mut Context) -> Result { let container_id = self.id(); let input_id = container_id.as_deref().map(|id| util::join!(id, "-input")); + let help = form::FieldHelp::new(self.help_text(), input_id.as_deref(), cx); let input_class = if *self.plaintext() { "form-control-plaintext" } else { @@ -251,6 +252,7 @@ impl Component for Field { input type=(self.kind()) id=[input_id.as_deref()] + aria-describedby=[help.id()] class=(input_class) name=[self.name().as_deref()] value=[self.value().as_deref()] @@ -267,9 +269,7 @@ impl Component for Field { onfocus=[strict.then_some("this.removeAttribute('readonly')")] required[*self.required()] disabled[*self.disabled()]; - @if let Some(description) = self.help_text().lookup(cx) { - div class="form-text" { (description) } - } + (help) } }) } diff --git a/src/base/component/form/number.rs b/src/base/component/form/number.rs index afe01a83..86d0f51a 100644 --- a/src/base/component/form/number.rs +++ b/src/base/component/form/number.rs @@ -85,6 +85,7 @@ impl Component for Number { async fn prepare(&self, cx: &mut Context) -> Result { let container_id = self.id(); let input_id = container_id.as_deref().map(|id| util::join!(id, "-input")); + let help = form::FieldHelp::new(self.help_text(), input_id.as_deref(), cx); Ok(html! { div (self.props().unpack(cx)) { @if let Some(label) = self.label().lookup(cx) { @@ -103,6 +104,7 @@ impl Component for Number { input type="number" id=[input_id.as_deref()] + aria-describedby=[help.id()] class="form-control" name=[self.name().as_deref()] min=[self.min()] @@ -113,9 +115,7 @@ impl Component for Number { readonly[*self.readonly()] required[*self.required()] disabled[*self.disabled()]; - @if let Some(description) = self.help_text().lookup(cx) { - div class="form-text" { (description) } - } + (help) } }) } diff --git a/src/base/component/form/radio.rs b/src/base/component/form/radio.rs index 01b92623..3d33e579 100644 --- a/src/base/component/form/radio.rs +++ b/src/base/component/form/radio.rs @@ -142,11 +142,20 @@ impl Component for Field { // En `setup()` se garantiza que `name` e `id` están definidos antes del renderizado. let name = self.name().as_deref().unwrap(); let container_id = self.id().unwrap(); + // El contenedor agrupa las opciones: su etiqueta y su texto de ayuda describen al grupo. + let label = self.label().lookup(cx); + let label_id = label.as_ref().map(|_| util::join!(&container_id, "-label")); + let help = form::FieldHelp::new(self.help_text(), Some(&container_id), cx); Ok(html! { - div (self.props().unpack(cx)) { - @if let Some(label) = self.label().lookup(cx) { - label class="form-label" { + div + (self.props().unpack(cx)) + role="group" + aria-labelledby=[label_id.as_deref()] + aria-describedby=[help.id()] + { + @if let Some(label) = label { + label id=[label_id.as_deref()] class="form-label" { (label) @if *self.required() { span @@ -187,9 +196,7 @@ impl Component for Field { } } } - @if let Some(description) = self.help_text().lookup(cx) { - div class="form-text" { (description) } - } + (help) } }) } diff --git a/src/base/component/form/range.rs b/src/base/component/form/range.rs index 4954f5ef..31389ade 100644 --- a/src/base/component/form/range.rs +++ b/src/base/component/form/range.rs @@ -82,6 +82,7 @@ impl Component for Range { async fn prepare(&self, cx: &mut Context) -> Result { let container_id = self.id(); let range_id = container_id.as_deref().map(|id| util::join!(id, "-range")); + let help = form::FieldHelp::new(self.help_text(), range_id.as_deref(), cx); Ok(html! { div (self.props().unpack(cx)) { @if let Some(label) = self.label().lookup(cx) { @@ -90,6 +91,7 @@ impl Component for Range { input type="range" id=[range_id.as_deref()] + aria-describedby=[help.id()] class="form-range" name=[self.name().as_deref()] min=[self.min()] @@ -98,9 +100,7 @@ impl Component for Range { value=[self.value()] autofocus[*self.autofocus()] disabled[*self.disabled()]; - @if let Some(description) = self.help_text().lookup(cx) { - div class="form-text" { (description) } - } + (help) } }) } diff --git a/src/base/component/form/select.rs b/src/base/component/form/select.rs index 37a2b57e..aae204a4 100644 --- a/src/base/component/form/select.rs +++ b/src/base/component/form/select.rs @@ -240,6 +240,7 @@ impl Component for Field { async fn prepare(&self, cx: &mut Context) -> Result { let container_id = self.id(); let select_id = container_id.as_deref().map(|id| util::join!(id, "-select")); + let help = form::FieldHelp::new(self.help_text(), select_id.as_deref(), cx); Ok(html! { div (self.props().unpack(cx)) { @@ -258,6 +259,7 @@ impl Component for Field { } select id=[select_id.as_deref()] + aria-describedby=[help.id()] class="form-select" name=[self.name().as_deref()] multiple[*self.multiple()] @@ -297,9 +299,7 @@ impl Component for Field { } } } - @if let Some(description) = self.help_text().lookup(cx) { - div class="form-text" { (description) } - } + (help) } }) } diff --git a/src/base/component/form/textarea.rs b/src/base/component/form/textarea.rs index 8d0b8999..1934362e 100644 --- a/src/base/component/form/textarea.rs +++ b/src/base/component/form/textarea.rs @@ -93,6 +93,7 @@ impl Component for Textarea { let textarea_id = container_id .as_deref() .map(|id| util::join!(id, "-textarea")); + let help = form::FieldHelp::new(self.help_text(), textarea_id.as_deref(), cx); Ok(html! { div (self.props().unpack(cx)) { @@ -111,6 +112,7 @@ impl Component for Textarea { } textarea id=[textarea_id.as_deref()] + aria-describedby=[help.id()] class="form-control" name=[self.name().as_deref()] rows=[self.rows()] @@ -127,9 +129,7 @@ impl Component for Textarea { (value) } } - @if let Some(description) = self.help_text().lookup(cx) { - div class="form-text" { (description) } - } + (help) } }) } diff --git a/tests/component_form_help_text.rs b/tests/component_form_help_text.rs new file mode 100644 index 00000000..02ff42a9 --- /dev/null +++ b/tests/component_form_help_text.rs @@ -0,0 +1,150 @@ +use pagetop::prelude::*; + +// The help text of a field gets an id and the control points to it with `aria-describedby`, so +// screen readers announce it when the control gets the focus. + +async fn render(component: &mut impl Component) -> String { + component + .render(&mut Context::default()) + .await + .into_string() +} + +fn help() -> Lc { + Lc::n("Help") +} + +// **< Form fields >******************************************************************************** + +#[pagetop::test] +async fn single_controls_point_to_their_help_text() { + let cases: [(String, &str); 5] = [ + ( + render( + &mut form::input::Field::text() + .with_name("a") + .with_help_text(help()), + ) + .await, + "edit-a-input-help", + ), + ( + render(&mut form::Number::new().with_name("b").with_help_text(help())).await, + "edit-b-input-help", + ), + ( + render(&mut form::Range::new().with_name("c").with_help_text(help())).await, + "edit-c-range-help", + ), + ( + render(&mut form::Textarea::new().with_name("d").with_help_text(help())).await, + "edit-d-textarea-help", + ), + ( + render( + &mut form::select::Field::new() + .with_name("e") + .with_help_text(help()), + ) + .await, + "edit-e-select-help", + ), + ]; + for (html, id) in cases { + assert!( + html.contains(&format!(r#"aria-describedby="{id}""#)), + "{html}" + ); + assert!( + html.contains(&format!(r#"
Help
"#)), + "{html}" + ); + } +} + +#[pagetop::test] +async fn without_help_text_there_is_no_aria_describedby() { + let html = render(&mut form::input::Field::text().with_name("a")).await; + assert!(!html.contains("aria-describedby"), "{html}"); +} + +#[pagetop::test] +async fn date_fields_point_to_their_format_and_their_help_text() { + let html = render( + &mut form::date::Field::date() + .with_name("f") + .with_help_text(help()), + ) + .await; + assert!(html.contains(r#"aria-describedby="edit-f-input-format edit-f-input-help""#)); + assert!(html.contains(r#"
Help
"#)); +} + +#[pagetop::test] +async fn checks_and_radios_are_labelled_groups_with_help_text() { + let check = render( + &mut form::check::Field::new() + .with_name("g") + .with_label(Lc::n("Options")) + .with_help_text(help()) + .with_item(form::check::Item::new("1", Lc::n("One"))), + ) + .await; + let radio = render( + &mut form::radio::Field::new() + .with_name("h") + .with_label(Lc::n("Choice")) + .with_help_text(help()) + .with_item(form::radio::Item::new("1", Lc::n("One"))), + ) + .await; + for (html, id) in [(check, "edit-g"), (radio, "edit-h")] { + assert!(html.contains(r#"role="group""#), "{html}"); + assert!( + html.contains(&format!(r#"aria-labelledby="{id}-label""#)), + "{html}" + ); + assert!( + html.contains(&format!(r#"aria-describedby="{id}-help""#)), + "{html}" + ); + assert!( + html.contains(&format!(r#"