✨ (form): Añade texto de ayuda a Checkbox

Documenta el criterio de uso de las cookies en PageTop y por qué no
requieren la aceptación del usuario.
This commit is contained in:
Manuel Cillero 2026-11-11 18:36:04 +01:00
parent e4a88b2150
commit a276a5f797
6 changed files with 138 additions and 15 deletions

View file

@ -9,7 +9,9 @@
}
.form-text {
font-size: 0.9375rem;
font-size: 0.875rem;
font-style: italic;
line-height: 1.3;
color: var(--val-color--text--muted);
}
@ -33,23 +35,37 @@ fieldset > legend {
}
.form-check {
display: flex;
display: grid;
grid-template-columns: auto 1fr;
align-items: center;
gap: 0.5rem;
gap: 0.25rem 0.5rem;
min-height: 1.5rem;
margin-bottom: 0.25rem;
}
// A single checkbox has no label above it to give it room, as the other fields do.
.form-field.form-check:not(.form-check-inline) {
margin-top: 1em;
}
.form-check-inline {
display: inline-flex;
display: inline-grid;
margin-right: 1rem;
}
.form-check-reverse {
flex-direction: row-reverse;
justify-content: flex-start;
grid-template-columns: 1fr auto;
text-align: right;
}
.form-check-reverse > .form-check-input {
grid-column: 2;
grid-row: 1;
}
// Help text goes below the label, aligned with it.
.form-check > .form-text {
grid-column: 2;
}
.form-check-reverse > .form-text {
grid-column: 1;
}
.form-check-input {
flex-shrink: 0;
cursor: pointer;
}
.form-check-label {

View file

@ -47,6 +47,8 @@ pub struct Checkbox {
name: AttrName,
/// Devuelve la etiqueta del control.
label: Lc,
/// Devuelve el texto de ayuda del control.
help_text: Lc,
/// Devuelve si el control debe estar marcado/activo por defecto.
checked: bool,
/// Devuelve si el control recibe el foco automáticamente al cargar la página.
@ -104,6 +106,7 @@ impl Component for Checkbox {
let checkbox_id = util::join!(&container_id, "-checkbox");
let label = form::parts::Label::check(self.label(), Some(&checkbox_id))
.with_required(*self.required());
let help = form::parts::Help::new(self.help_text(), Some(&checkbox_id));
let is_switch = *self.checkbox_kind() == form::CheckboxKind::Switch;
Ok(html! {
@ -118,8 +121,10 @@ impl Component for Checkbox {
checked[*self.checked()]
autofocus[*self.autofocus()]
required[*self.required()]
disabled[*self.disabled()];
disabled[*self.disabled()]
aria-describedby=[help.id()];
(label.render(cx))
(help.render(cx))
}
})
}
@ -175,6 +180,12 @@ impl Checkbox {
self
}
/// Establece el texto de ayuda del control (usa [`Lc::none()`] para quitarlo).
pub fn with_help_text(mut self, help_text: Lc) -> Self {
self.help_text = help_text;
self
}
/// Establece si el control debe aparecer marcado/activo por defecto.
pub fn with_checked(mut self, checked: bool) -> Self {
self.checked = checked;

View file

@ -41,9 +41,9 @@ struct Pending(Vec<(MessageLevel, String)>);
/// La *cookie* (`pagetop_flash`) sólo se crea cuando una respuesta usa este método; una aplicación
/// que no lo usa no envía ninguna. Es una *cookie* técnica: surge de una acción del usuario, dura
/// como mucho un minuto, se borra en cuanto se muestran los mensajes y no contiene datos que lo
/// identifiquen. Como *cookie* estrictamente necesaria para el servicio que el usuario ha pedido,
/// suele quedar exenta de consentimiento, aunque conviene declararla en la política de *cookies* de
/// la aplicación.
/// identifiquen. En España y en la Unión Europea no requiere la aceptación del usuario, aunque
/// conviene declararla en la política de *cookies* de la aplicación (ver
/// [*Cookies*](crate::web#cookies) en el módulo `web`).
///
/// El texto se muestra siempre como texto plano: el marcado que tenga una traducción aparecería
/// tal cual. Cada mensaje debe ser breve; los que no quepan en la *cookie* (unos 3,8 KB entre

View file

@ -32,6 +32,93 @@
//! conexiones HTTP sin cifrar fuera de `localhost`) se comprueban comparando `Origin` con `Host`.
//!
//! Ninguna protección frente a CSRF resiste un fallo de XSS en la propia aplicación.
//!
//! # *Cookies*
//!
//! PageTop sólo crea dos *cookies*, ambas propias (de la aplicación, no de terceros) y únicamente
//! cuando las provoca una acción del usuario:
//!
//! | *Cookie* | Para qué | Duración |
//! |------------------|----------------------------------------------------------------|-----------------------------------------------------------------|
//! | `pagetop_flash` | Mensajes para la página siguiente ([`ResponseExt`]) | Un minuto como máximo; se borra al mostrar los mensajes |
//! | `pagetop_list_*` | Filtros, orden y página de un listado ([`remember_query()`]) | La sesión del navegador; se borra al limpiar los filtros |
//!
//! Las extensiones pueden añadir las suyas; `pagetop-user`, por ejemplo, la de la sesión iniciada.
//!
//! ## Sin aceptación de *cookies*
//!
//! PageTop y sus extensiones propias (las que se publican con él, como `pagetop-user`) están
//! pensados para que una aplicación no tenga que pedir la aceptación de *cookies* sólo por usarlos.
//! Para ello, todas las *cookies* que crean cumplen los criterios que las principales normas de
//! privacidad del mundo tratan como necesarias para el servicio:
//!
//! - Son propias de la aplicación; ninguna es de terceros.
//! - Sólo existen para prestar algo que el usuario pide, y se crean por una acción suya.
//! - No identifican al usuario fuera de la aplicación ni sirven para seguirlo entre sitios. No se
//! usan para analítica, publicidad ni perfiles, y no se venden ni se comparten.
//! - Duran lo imprescindible para su función.
//!
//! Las normas que exigen consentimiento previo (las de la Unión Europea y otras de inspiración
//! europea) eximen expresamente las *cookies* necesarias para el servicio que pide el usuario. Las
//! que sólo obligan a ofrecer al usuario la posibilidad de oponerse (las de varios estados de
//! Estados Unidos, por ejemplo) se dirigen a la venta o el intercambio de datos y a la publicidad
//! dirigida, que estas *cookies* no hacen. En unas y otras, lo que sí se exige casi siempre es
//! informar: describirlas en la política de *cookies* o de privacidad de la aplicación (nombre,
//! finalidad, duración y si son propias), y la tabla anterior sirve para ello.
//!
//! La única que no queda exenta por sí sola es la de la sesión de `pagetop-user` cuando el usuario
//! marca "Recuérdame", porque se conserva aunque cierre el navegador. Pero es él quien la pide, y
//! marcar la casilla sabiendo que usa una *cookie* es ya su consentimiento. Es el criterio para
//! cualquier función que necesite una *cookie* que el usuario deba aceptar: el consentimiento se
//! pide en el propio gesto que la activa, nunca con un aviso aparte.
//!
//! La exención depende del uso: si una aplicación aprovechara estas *cookies* para otra cosa, o
//! alargara su duración, dejaría de valer. Las que añada cada aplicación (analítica, publicidad...)
//! sí suelen necesitar consentimiento.
//!
//! ## Unión Europea y España
//!
//! Es el marco más exigente y el que se ha tomado como referencia. La norma europea es una
//! directiva: no se aplica directamente, sino que cada Estado miembro (y también Islandia,
//! Liechtenstein y Noruega, del Espacio Económico Europeo) la incorpora a su propia ley, y la
//! autoridad de protección de datos de cada país publica sus propias guías, de modo que los
//! detalles pueden variar de un país a otro. Aquí se analizan la ley española y la guía de la
//! autoridad española.
//!
//! Guardar o leer información en el dispositivo del usuario exige su consentimiento previo, salvo
//! cuando es estrictamente necesario para prestar un servicio que el propio usuario ha pedido
//! (artículo 5.3 de la Directiva 2002/58/CE, la «Directiva ePrivacy», modificada por la Directiva
//! 2009/136/CE; en España, artículo 22.2 de la Ley 34/2002, de servicios de la sociedad de la
//! información, LSSI). El dictamen 04/2012 del Grupo de Trabajo del Artículo 29 sobre la exención
//! del requisito de consentimiento de las *cookies* (WP194), criterio que mantiene el Comité
//! Europeo de Protección de Datos, y la *Guía sobre el uso de las cookies* de la Agencia Española
//! de Protección de Datos (AEPD) concretan esa excepción. Entre sus ejemplos de *cookies* exentas
//! están las que recuerdan lo que el usuario ha hecho durante la sesión y las de personalización de
//! la interfaz que él mismo elige.
//!
//! Las dos de PageTop encajan en esa excepción, así que **no requieren la aceptación del usuario**
//! ni un aviso de *cookies* que la pida:
//!
//! - `pagetop_flash` completa una acción que el usuario acaba de pedir (guardar un formulario,
//! iniciar sesión...): lleva el aviso del resultado a la página siguiente y desaparece en cuanto
//! se muestra.
//! - `pagetop_list_*` es una personalización de la interfaz que el usuario activa al filtrar,
//! ordenar o paginar un listado, y dura lo que la sesión del navegador.
//!
//! El texto de un filtro puede contener datos personales (un nombre buscado), pero queda sólo en el
//! navegador de quien lo escribió. La AEPD recomienda describir también las *cookies* exentas en la
//! política de *cookies* de la aplicación.
//!
//! ## Otros países
//!
//! Fuera de la Unión Europea, los criterios anteriores se basan en lo que comparten las normas más
//! extendidas, no en un análisis país por país. Antes de desplegar en un país concreto conviene
//! contrastarlos con su normativa, que además cambia con frecuencia.
//!
//! Es el criterio de las normas y guías citadas, no un asesoramiento jurídico: en un despliegue con
//! exigencias legales concretas, el responsable del tratamiento debe confirmarlo.
//!
//! [`ResponseExt`]: crate::response::ResponseExt
use crate::{StaticFile, global};

View file

@ -73,9 +73,9 @@ const RESET_PARAM: &str = "reset";
/// código derivado de la ruta, limitada a esa ruta con `Path`), sin nada en el servidor. Es una
/// *cookie* técnica de sesión: sólo se crea cuando el usuario filtra, ordena o pagina, sólo
/// contiene los parámetros del listado y el navegador la borra al cerrarse (salvo los que restauran
/// la sesión anterior al abrirse de nuevo, que la conservan). Como *cookie* de personalización de
/// la interfaz que el propio usuario solicita, suele quedar exenta de consentimiento, aunque
/// conviene declararla en la política de *cookies* de la aplicación. Las ventanas y pestañas del
/// la sesión anterior al abrirse de nuevo, que la conservan). En España y en la Unión Europea no
/// requiere la aceptación del usuario, aunque conviene declararla en la política de *cookies* de la
/// aplicación (ver [*Cookies*](crate::web#cookies) en el módulo `web`). Las ventanas y pestañas del
/// navegador comparten el mismo estado. No se recuerda un estado de más de 1024 caracteres ni uno
/// con caracteres que una *cookie* no admite (los navegadores ya los codifican en la URL).
///

View file

@ -18,7 +18,7 @@ fn help() -> Lc {
#[pagetop::test]
async fn single_controls_point_to_their_help_text() {
let cases: [(String, &str); 5] = [
let cases: [(String, &str); 6] = [
(
render(
&mut form::input::Field::text()
@ -49,6 +49,15 @@ async fn single_controls_point_to_their_help_text() {
.await,
"edit-e-select-help",
),
(
render(
&mut form::Checkbox::check()
.with_name("g")
.with_help_text(help()),
)
.await,
"edit-g-checkbox-help",
),
];
for (html, id) in cases {
assert!(