diff --git a/extensions/pagetop-bootsier/src/theme/bs/form/input.rs b/extensions/pagetop-bootsier/src/theme/bs/form/input.rs index 20ba1839..160d6558 100644 --- a/extensions/pagetop-bootsier/src/theme/bs/form/input.rs +++ b/extensions/pagetop-bootsier/src/theme/bs/form/input.rs @@ -55,7 +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 help = form::parts::Help::new(field.help_text(), input_id.as_deref()); let input_class = if *field.plaintext() { "form-control-plaintext" } else { @@ -77,26 +77,12 @@ pub(crate) fn render(field: &Field, cx: &mut Context) -> Result html! { - label for=[input_id.as_deref()] class="form-label" { - (text) - @if *field.required() { - span - class="form-required" - title=[Lc::l("field_required").lookup(cx)] - { - "*" - } - } - } - }, - None => html! {}, - }; + let label = form::parts::Label::new(field.label(), input_id.as_deref()) + .with_required(*field.required()); Ok(html! { div (field.props().unpack(cx)) { - @if !floating { (label) } + @if !floating { (label.render(cx)) } input type=(field.kind()) id=[input_id.as_deref()] @@ -117,8 +103,8 @@ pub(crate) fn render(field: &Field, cx: &mut Context) -> 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 help = form::parts::Help::new(field.help_text(), select_id.as_deref()); let floating = field.props().extra_or(EXTRA_FLOATING_LABEL, false); - let label = match field.label().lookup(cx) { - Some(text) => html! { - label for=[select_id.as_deref()] class="form-label" { - (text) - @if *field.required() { - span - class="form-required" - title=[Lc::l("field_required").lookup(cx)] - { - "*" - } - } - } - }, - None => html! {}, - }; + let label = form::parts::Label::new(field.label(), select_id.as_deref()) + .with_required(*field.required()); Ok(html! { div (field.props().unpack(cx)) { - @if !floating { (label) } + @if !floating { (label.render(cx)) } select id=[select_id.as_deref()] aria-describedby=[help.id()] @@ -125,8 +111,8 @@ pub(crate) fn render(field: &Field, cx: &mut Context) -> Result Result Result html! { - label for=[textarea_id.as_deref()] class="form-label" { - (text) - @if *field.required() { - span - class="form-required" - title=[Lc::l("field_required").lookup(cx)] - { - "*" - } - } - } - }, - None => html! {}, - }; + let label = form::parts::Label::new(field.label(), textarea_id.as_deref()) + .with_required(*field.required()); Ok(html! { div (field.props().unpack(cx)) { - @if !floating { (label) } + @if !floating { (label.render(cx)) } textarea id=[textarea_id.as_deref()] aria-describedby=[help.id()] @@ -106,8 +92,8 @@ pub(crate) fn render(field: &Textarea, cx: &mut Context) -> Result 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); + let format = form::parts::Help::suffixed(&format, input_id.as_deref(), "-format"); + let help = form::parts::Help::new(self.help_text(), input_id.as_deref()); + let label = form::parts::Label::new(self.label(), input_id.as_deref()) + .with_required(*self.required()); // 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(), @@ -175,19 +177,7 @@ impl Component for Field { 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)] - { - "*" - } - } - } - } + (label.render(cx)) input type="text" id=[input_id.as_deref()] @@ -201,8 +191,8 @@ impl Component for Field { readonly[*self.readonly()] required[*self.required()] disabled[*self.disabled()]; - (format) - (help) + (format.render(cx)) + (help.render(cx)) } }) } diff --git a/src/base/component/form/field_help.rs b/src/base/component/form/field_help.rs deleted file mode 100644 index fa700a14..00000000 --- a/src/base/component/form/field_help.rs +++ /dev/null @@ -1,70 +0,0 @@ -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 1114c4e6..a1570941 100644 --- a/src/base/component/form/input.rs +++ b/src/base/component/form/input.rs @@ -220,7 +220,9 @@ 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 help = form::parts::Help::new(self.help_text(), input_id.as_deref()); + let label = form::parts::Label::new(self.label(), input_id.as_deref()) + .with_required(*self.required()); let input_class = if *self.plaintext() { "form-control-plaintext" } else { @@ -236,19 +238,7 @@ impl Component for Field { 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)] - { - "*" - } - } - } - } + (label.render(cx)) input type=(self.kind()) id=[input_id.as_deref()] @@ -269,7 +259,7 @@ impl Component for Field { onfocus=[strict.then_some("this.removeAttribute('readonly')")] required[*self.required()] disabled[*self.disabled()]; - (help) + (help.render(cx)) } }) } diff --git a/src/base/component/form/number.rs b/src/base/component/form/number.rs index 86d0f51a..3bb5c28a 100644 --- a/src/base/component/form/number.rs +++ b/src/base/component/form/number.rs @@ -85,22 +85,12 @@ 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); + let help = form::parts::Help::new(self.help_text(), input_id.as_deref()); + let label = form::parts::Label::new(self.label(), input_id.as_deref()) + .with_required(*self.required()); 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)] - { - "*" - } - } - } - } + (label.render(cx)) input type="number" id=[input_id.as_deref()] @@ -115,7 +105,7 @@ impl Component for Number { readonly[*self.readonly()] required[*self.required()] disabled[*self.disabled()]; - (help) + (help.render(cx)) } }) } diff --git a/src/base/component/form/parts.rs b/src/base/component/form/parts.rs new file mode 100644 index 00000000..2aa8dfb4 --- /dev/null +++ b/src/base/component/form/parts.rs @@ -0,0 +1,123 @@ +//! Piezas de marcado compartidas por los campos de formulario. +//! +//! [`form::parts::Label`](Label) (la etiqueta del campo, más la marca opcional de campo +//! obligatorio) y [`form::parts::Help`](Help) (el texto de ayuda) generan marcado común para los +//! principales campos de formularios, y quedan disponibles para los temas que puedan necesitarlos. +//! +//! **No son componentes**. Se crean dentro de `prepare()` (o del renderizado de un tema) a partir +//! de los textos del campo, y se insertan en [`html!`] con su método `render()`, que los traduce al +//! idioma del contexto. +//! +//! # Accesibilidad +//! +//! Es uno de sus puntos fuertes. Permiten aplicar de forma uniforme las relaciones que las pautas +//! [WCAG 2.2] exigen en los formularios desde el nivel A, con atributos [WAI-ARIA] cuando HTML no +//! basta: +//! +//! - **Cada etiqueta queda asociada a su control** con `for` o, en un grupo de controles, al +//! contenedor del grupo, que la enlaza con `aria-labelledby`. Así el control o el grupo quedan +//! con un nombre accesible. +//! - **El texto de ayuda queda asociado al control** (o al contenedor del grupo) con +//! `aria-describedby`, de modo que las tecnologías de apoyo suelen anunciarlo como descripción. +//! - **No dejan referencias rotas**. Sin texto, o sin identificador al que enlazar, no se genera la +//! relación. +//! +//! La marca de obligatorio (`*`) es texto de la etiqueta. Que el campo es obligatorio lo determina +//! el atributo `required` del propio control, que pone cada componente, igual que el `role="group"` +//! del contenedor de un grupo. Los atributos `aria-describedby` y `aria-labelledby` también los +//! escribe el componente, con los identificadores que dan [`Help::id()`] y [`Label::id()`]. +//! +//! [WCAG 2.2]: https://www.w3.org/TR/WCAG22/ +//! [WAI-ARIA]: https://www.w3.org/TR/wai-aria-1.2/ +//! +//! # En un tema +//! +//! Un tema que renderice su propio marcado de un campo (con `render_component()`) puede: +//! +//! - **Reutilizarlas**, que es lo recomendable. Basta con añadir `aria-describedby=[help.id()]` al +//! control (y `aria-labelledby=[label.id()]` al contenedor de un grupo) para conservar los +//! enlaces de accesibilidad. Las piezas sirven aunque el tema cambie el orden de los elementos +//! (p. ej. la etiqueta detrás del control, para una etiqueta flotante) o use otras clases +//! (`with_class()` de cada pieza). +//! - **Reimplementar el marcado por completo**, si necesita otro distinto. En ese caso se +//! recomienda mantener los enlaces de accesibilidad: la etiqueta asociada al control con `for` +//! (o, en un grupo de controles, al contenedor con `aria-labelledby`) y el texto de ayuda +//! asociado con `aria-describedby`. +//! +//! # Ejemplo +//! +//! Un control con su etiqueta, marcado como obligatorio, y su texto de ayuda: +//! +//! ```rust +//! # use pagetop::prelude::*; +//! # let cx = Context::default().with_langid(&Locale::resolve("en-US")); +//! let (name, hint) = (Lc::n("Name"), Lc::n("As on your ID card.")); +//! let label = form::parts::Label::new(&name, Some("edit-name-input")).with_required(true); +//! let help = form::parts::Help::new(&hint, Some("edit-name-input")); +//! let markup = html! { +//! (label.render(&cx)) +//! input type="text" id="edit-name-input" aria-describedby=[help.id()]; +//! (help.render(&cx)) +//! }; +//! # assert_eq!(markup.into_string(), concat!( +//! # r#""#, +//! # r#""#, +//! # r#"
As on your ID card.
"#, +//! # )); +//! ``` +//! +//! genera: +//! +//! ```html +//! +//! +//!
As on your ID card.
+//! ``` +//! +//! Un grupo de controles (casillas o botones de opción), cuyo contenedor enlaza la etiqueta y el +//! texto de ayuda del grupo: +//! +//! ```rust +//! # use pagetop::prelude::*; +//! # let cx = Context::default().with_langid(&Locale::resolve("en-US")); +//! let (name, hint) = (Lc::n("Notifications"), Lc::n("Choose one or more.")); +//! let label = form::parts::Label::group(&name, "edit-notify"); +//! let help = form::parts::Help::new(&hint, Some("edit-notify")); +//! let markup = html! { +//! div id="edit-notify" role="group" +//! aria-labelledby=[label.id()] aria-describedby=[help.id()] +//! { +//! (label.render(&cx)) +//! // Aquí, las casillas o los botones de opción del grupo. +//! (help.render(&cx)) +//! } +//! }; +//! # assert_eq!(markup.into_string(), concat!( +//! # r#"
"#, +//! # r#""#, +//! # r#"
Choose one or more.
"#, +//! # )); +//! ``` +//! +//! genera: +//! +//! ```html +//!
+//! +//! +//!
Choose one or more.
+//!
+//! ``` +//! +//! [`html!`]: crate::html::html + +mod help; +pub use help::Help; + +mod label; +pub use label::Label; diff --git a/src/base/component/form/parts/help.rs b/src/base/component/form/parts/help.rs new file mode 100644 index 00000000..c33c39b2 --- /dev/null +++ b/src/base/component/form/parts/help.rs @@ -0,0 +1,87 @@ +use crate::prelude::*; + +/// Texto de ayuda de un campo de formulario. +/// +/// Muestra el texto de ayuda de un control (o de un grupo de controles), con un identificador para +/// que el control (o el contenedor del grupo) lo enlace con `aria-describedby`, de modo que las +/// tecnologías de apoyo suelen anunciarlo al entrar en el campo. Se renderiza con +/// [`render()`](Self::render), que genera un `
`, o nada si el texto es [`Lc::none()`]. La +/// clase predeterminada (`form-text`) puede cambiarse con [`with_class()`](Self::with_class). +/// +/// Se puede crear con: +/// +/// - [`new()`](Self::new): para el texto de ayuda de un control, con el identificador +/// `{anchor_id}-help`. +/// - [`suffixed()`](Self::suffixed): para otro texto que describa al mismo control, con otro sufijo +/// en el identificador. +/// +/// # Ejemplo +/// +/// ```rust,no_run +/// # use pagetop::prelude::*; +/// # fn render(help_text: &Lc, input_id: Option<&str>, cx: &Context) -> Markup { +/// let help = form::parts::Help::new(help_text, input_id); +/// html! { +/// input type="text" id=[input_id] aria-describedby=[help.id()]; +/// (help.render(cx)) +/// } +/// # } +/// ``` +#[derive(Clone, Debug)] +pub struct Help<'a> { + text: &'a Lc, + id: Option, + class: CowStr, +} + +impl<'a> Help<'a> { + /// Texto de ayuda `help_text` con 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: &'a Lc, anchor_id: Option<&str>) -> Self { + Self::suffixed(help_text, anchor_id, "-help") + } + + /// Igual que [`new()`](Self::new), pero con otro sufijo para el identificador, que se añade tal + /// cual (p. ej. `-format` da `{anchor_id}-format`). Es útil cuando un mismo control tiene más + /// de un texto que lo describe: cada uno necesita un sufijo distinto, y el control los enlaza + /// todos en `aria-describedby`, separados por espacios. + pub fn suffixed(help_text: &'a Lc, anchor_id: Option<&str>, suffix: &str) -> Self { + // 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 = anchor_id + .filter(|_| !help_text.is_none()) + .map(|anchor_id| util::join!(anchor_id, suffix)); + Self { + text: help_text, + id, + class: CowStr::Borrowed("form-text"), + } + } + + /// Devuelve el identificador para `aria-describedby`, o `None` si el texto es [`Lc::none()`] o + /// si no se indicó `anchor_id`. + pub fn id(&self) -> Option<&str> { + self.id.as_deref() + } + + /// Renderiza el texto de ayuda traducido al idioma del contexto. + pub fn render(&self, cx: &Context) -> Markup { + // Se genera el elemento aunque falte la traducción, para que `id()` no quede sin destino. + html! { + @if !self.text.is_none() { + div id=[self.id()] class=(self.class) { (self.text.lookup(cx).unwrap_or_default()) } + } + } + } +} + +#[builder_impl] +impl<'a> Help<'a> { + /// Sustituye la clase del texto de ayuda (por defecto, `form-text`) por otra u otras, separadas + /// por espacios; útil para un tema cuyo marcado use otras clases. + pub fn with_class(mut self, class: impl Into) -> Self { + self.class = class.into(); + self + } +} diff --git a/src/base/component/form/parts/label.rs b/src/base/component/form/parts/label.rs new file mode 100644 index 00000000..22539af1 --- /dev/null +++ b/src/base/component/form/parts/label.rs @@ -0,0 +1,119 @@ +use crate::prelude::*; + +/// Etiqueta de un campo de formulario, con la marca opcional de campo obligatorio. +/// +/// Muestra la etiqueta del campo y, si es obligatorio ([`with_required()`](Self::with_required)), +/// le añade un asterisco con un texto emergente traducido (`field_required`). Se renderiza con +/// [`render()`](Self::render), que genera un `