From 8690f994c3231ca8b6d374378cf9d925f2ca68b8 Mon Sep 17 00:00:00 2001 From: Manuel Cillero Date: Fri, 9 Oct 2026 00:59:43 +0200 Subject: [PATCH] =?UTF-8?q?=E2=99=BF=EF=B8=8F=20(form):=20Enlaza=20ayuda?= =?UTF-8?q?=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#"