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..6f6644f9 100644 --- a/extensions/pagetop-bootsier/src/theme/bs/form.rs +++ b/extensions/pagetop-bootsier/src/theme/bs/form.rs @@ -14,16 +14,24 @@ pub use pagetop::base::component::form::radio; pub mod select; #[doc(inline)] -pub use select::SelectBootsier; +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::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::date; 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..160d6558 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 @@ -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::parts::Help::new(field.help_text(), input_id.as_deref()); let input_class = if *field.plaintext() { "form-control-plaintext" } else { @@ -76,29 +77,16 @@ 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()] + aria-describedby=[help.id()] class=(input_class) name=[field.name().as_deref()] value=[field.value().as_deref()] @@ -115,10 +103,8 @@ pub(crate) fn render(field: &Field, cx: &mut Context) -> Result Self { self.alter_prop(PropsOp::set_extra(EXTRA_FLOATING_LABEL, floating)); self @@ -62,28 +62,16 @@ pub(crate) fn setup(field: &mut Field) { pub(crate) fn render(field: &Field, cx: &mut Context) -> Result { let container_id = field.id(); let select_id = container_id.as_deref().map(|id| util::join!(id, "-select")); + 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()] class="form-select" name=[field.name().as_deref()] multiple[*field.multiple()] @@ -123,10 +111,8 @@ pub(crate) fn render(field: &Field, cx: &mut Context) -> Result Self { self.alter_prop(PropsOp::set_extra(EXTRA_FLOATING_LABEL, floating)); self @@ -61,6 +61,7 @@ pub(crate) fn render(field: &Textarea, cx: &mut Context) -> 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()] class="form-control" name=[field.name().as_deref()] rows=[field.rows()] @@ -104,10 +92,8 @@ pub(crate) fn render(field: &Textarea, cx: &mut Context) -> Result 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/extensions/pagetop-bootsier/tests/form_help_text.rs b/extensions/pagetop-bootsier/tests/form_help_text.rs new file mode 100644 index 00000000..7d75854e --- /dev/null +++ b/extensions/pagetop-bootsier/tests/form_help_text.rs @@ -0,0 +1,57 @@ +// Bootsier renders its own markup for text inputs, selects and textareas: the help text must stay +// linked to the control with `aria-describedby`, as in the core components. + +use pagetop::prelude::*; +use pagetop_bootsier::Bootsier; +use pagetop_bootsier::theme::*; + +async fn render(component: &mut impl Component) -> 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 f61ff573..950bb0ae 100644 --- a/src/base/component/form.rs +++ b/src/base/component/form.rs @@ -6,6 +6,8 @@ pub use props::{Autocomplete, AutofillField, CheckboxKind, Method}; mod component; pub use component::Form; +pub mod parts; + mod fieldset; pub use fieldset::Fieldset; @@ -29,6 +31,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/check.rs b/src/base/component/form/check.rs index bcd7c9c0..5a915eab 100644 --- a/src/base/component/form/check.rs +++ b/src/base/component/form/check.rs @@ -142,12 +142,18 @@ 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 = form::parts::Label::group(self.label(), &container_id); + let help = form::parts::Help::new(self.help_text(), Some(&container_id)); 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()] + aria-describedby=[help.id()] + { + (label.render(cx)) @let item_classes = if *self.inline() { "form-check form-check-inline" } else { @@ -170,9 +176,7 @@ impl Component for Field { } } } - @if let Some(description) = self.help_text().lookup(cx) { - div class="form-text" { (description) } - } + (help.render(cx)) } }) } diff --git a/src/base/component/form/checkbox.rs b/src/base/component/form/checkbox.rs index 37733cf4..12bd0466 100644 --- a/src/base/component/form/checkbox.rs +++ b/src/base/component/form/checkbox.rs @@ -102,6 +102,8 @@ impl Component for Checkbox { let container_id = self.id().unwrap(); let checkbox_id = util::join!(&container_id, "-checkbox"); + let label = form::parts::Label::check(self.label(), Some(&checkbox_id)) + .with_required(*self.required()); let is_switch = *self.checkbox_kind() == form::CheckboxKind::Switch; Ok(html! { @@ -117,19 +119,7 @@ impl Component for Checkbox { autofocus[*self.autofocus()] required[*self.required()] disabled[*self.disabled()]; - @if let Some(label) = self.label().lookup(cx) { - label class="form-check-label" for=(&checkbox_id) { - (label) - @if *self.required() { - span - class="form-required" - title=[Lc::l("field_required").lookup(cx)] - { - "*" - } - } - } - } + (label.render(cx)) } }) } diff --git a/src/base/component/form/date.rs b/src/base/component/form/date.rs new file mode 100644 index 00000000..95627456 --- /dev/null +++ b/src/base/component/form/date.rs @@ -0,0 +1,322 @@ +//! 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 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()); + 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(), + " ", + 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); + Ok(html! { + div (self.props().unpack(cx)) { + (label.render(cx)) + input + type="text" + id=[input_id.as_deref()] + class="form-control" + name=[self.name().as_deref()] + value=[value] + placeholder=(hint) + aria-describedby=[util::non_blank(&described_by)] + autocomplete=(autocomplete) + autofocus[*self.autofocus()] + readonly[*self.readonly()] + required[*self.required()] + disabled[*self.disabled()]; + (format.render(cx)) + (help.render(cx)) + } + }) + } +} + +#[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/base/component/form/input.rs b/src/base/component/form/input.rs index 8da1b719..a1570941 100644 --- a/src/base/component/form/input.rs +++ b/src/base/component/form/input.rs @@ -220,6 +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::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 { @@ -235,22 +238,11 @@ 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()] + aria-describedby=[help.id()] class=(input_class) name=[self.name().as_deref()] value=[self.value().as_deref()] @@ -267,9 +259,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.render(cx)) } }) } diff --git a/src/base/component/form/number.rs b/src/base/component/form/number.rs index afe01a83..3bb5c28a 100644 --- a/src/base/component/form/number.rs +++ b/src/base/component/form/number.rs @@ -85,24 +85,16 @@ 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::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()] + aria-describedby=[help.id()] class="form-control" name=[self.name().as_deref()] min=[self.min()] @@ -113,9 +105,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.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 `