Skip to content

The design language that makes your AI harness better at design.

JavaScript
11.6 KB
Raw Blame
//! Whether a form field has a visible label of its own, so its placeholder
//! is a hint and not the field's name (taste call r5-p30: "Report a
//! placeholder as advisory when its field has a visible label (a label
//! element, aria-labelledby text, or a text label right above the field). A
//! placeholder that is the field's only label keeps failing.").
//!
//! A label counts only where a reader sees it: HubSpot's forms keep a
//! `<label for>` on every field and hide it with `display: none`, and there
//! the placeholder is the only name the field shows. `aria-label` is never
//! visible and never counts.

use super::dom::{tag_lower, Dom, ElId};
use super::painted::painted_at_capture;
use crate::js;

/// The longest text, in characters, an unassociated element above a field
/// can hold and still read as that field's label.
pub const TEXT_LABEL_MAX_CHARS: usize = 40;
/// How far above the field, in px, such a label's bottom edge can sit.
pub const TEXT_LABEL_MAX_GAP_PX: f64 = 24.0;
/// How far the label's bottom edge can dip under the field's top edge.
const TEXT_LABEL_OVERLAP_PX: f64 = 4.0;
/// How many wrappers that hold the field first are climbed to find the
/// element before it.
const TEXT_LABEL_MAX_CLIMB: usize = 2;

/// Tags an unassociated text label is written in.
const TEXT_LABEL_TAGS: &[&str] = &["label", "span", "div", "p", "legend", "dt", "strong", "b", "small"];
/// Tags whose text is not label text, and whose subtree is not searched.
const NOT_LABEL_TEXT_TAGS: &[&str] =
    &["input", "select", "textarea", "button", "option", "script", "style", "template", "noscript"];
/// What an element cannot hold and still be a plain text label.
const CONTROL_SELECTOR: &str =
    "input, select, textarea, button, a, [role=\"button\"], [role=\"link\"], [contenteditable]";
/// Boxes the climb for a label above the field does not leave.
const LABEL_CLIMB_STOP_TAGS: &[&str] = &["form", "fieldset", "body", "html", "td", "th", "li", "tr"];

/// Whether `root` shows text of its own: it or a descendant outside any
/// control holds a non-blank text node in a box painted at capture and
/// larger than the 1px square screen-reader text is clipped to.
fn shows_text(dom: &dyn Dom, root: ElId, field: ElId) -> bool {
    let mut stack = vec![root];
    while let Some(el) = stack.pop() {
        if el == field || NOT_LABEL_TEXT_TAGS.contains(&tag_lower(dom, el).as_str()) {
            continue;
        }
        if dom.direct_text_nodes(el).iter().any(|t| !js::trim(t).is_empty()) {
            let r = dom.rect(el);
            if r.width > 1.0 && r.height > 1.0 && painted_at_capture(dom, el) {
                return true;
            }
        }
        stack.extend(dom.children(el));
    }
    false
}

fn all(dom: &dyn Dom, selector: &str) -> Vec<ElId> {
    dom.query_all(None, selector).unwrap_or_default()
}

/// A `<label for>` naming the field, or a `<label>` around it.
fn label_element(dom: &dyn Dom, field: ElId) -> bool {
    let id = dom.attr(field, "id").unwrap_or_default();
    if !id.is_empty()
        && all(dom, "label")
            .into_iter()
            .any(|l| dom.attr(l, "for").as_deref() == Some(id.as_str()) && shows_text(dom, l, field))
    {
        return true;
    }
    dom.closest(field, "label")
        .ok()
        .flatten()
        .is_some_and(|l| shows_text(dom, l, field))
}

/// Text the field's `aria-labelledby` points at.
fn labelledby_text(dom: &dyn Dom, field: ElId) -> bool {
    let Some(ids) = dom.attr(field, "aria-labelledby") else {
        return false;
    };
    let ids: Vec<&str> = ids.split_whitespace().collect();
    if ids.is_empty() {
        return false;
    }
    all(dom, "*").into_iter().any(|e| {
        e != field
            && dom.attr(e, "id").is_some_and(|id| ids.contains(&id.as_str()))
            && shows_text(dom, e, field)
    })
}

/// A short run of plain text right above the field: the element before it
/// (or before a wrapper the field comes first in), holding no control,
/// sitting over the field within [`TEXT_LABEL_MAX_GAP_PX`].
fn text_label_above(dom: &dyn Dom, field: ElId) -> bool {
    let fr = dom.rect(field);
    let mut cur = field;
    for _ in 0..=TEXT_LABEL_MAX_CLIMB {
        if let Some(prev) = dom.previous_element_sibling(cur) {
            if !TEXT_LABEL_TAGS.contains(&tag_lower(dom, prev).as_str()) {
                return false;
            }
            // A `<label for>` belongs to the field it names.
            if dom.attr(prev, "for").is_some_and(|f| !f.is_empty()) {
                return false;
            }
            let text = js::trim(&dom.text_content(prev)).split_whitespace().collect::<Vec<_>>().join(" ");
            let chars = text.chars().count();
            if chars == 0 || chars > TEXT_LABEL_MAX_CHARS {
                return false;
            }
            if !dom.query_all(Some(prev), CONTROL_SELECTOR).unwrap_or_default().is_empty() {
                return false;
            }
            let pr = dom.rect(prev);
            let gap = fr.top - (pr.top + pr.height);
            let overlaps_x = pr.left < fr.left + fr.width && fr.left < pr.left + pr.width;
            return (-TEXT_LABEL_OVERLAP_PX..=TEXT_LABEL_MAX_GAP_PX).contains(&gap)
                && overlaps_x
                && shows_text(dom, prev, field);
        }
        let Some(parent) = dom.parent(cur) else {
            return false;
        };
        if LABEL_CLIMB_STOP_TAGS.contains(&tag_lower(dom, parent).as_str()) {
            return false;
        }
        cur = parent;
    }
    false
}

/// Whether a visible label names `field` (see the module docs).
pub fn field_has_visible_label(dom: &dyn Dom, field: ElId) -> bool {
    label_element(dom, field) || labelledby_text(dom, field) || text_label_above(dom, field)
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::browser::fake_dom::FakeDom;

    fn text_el(d: &mut FakeDom, parent: ElId, tag: &str, text: &str, rect: (f64, f64, f64, f64)) -> ElId {
        let el = d.add(Some(parent), tag);
        d.add_text(el, text);
        d.set_rect(el, rect.0, rect.1, rect.2, rect.3);
        el
    }

    fn field(d: &mut FakeDom, parent: ElId, top: f64) -> ElId {
        let el = d.add(Some(parent), "input");
        d.set_rect(el, 0.0, top, 280.0, 40.0);
        el
    }

    #[test]
    fn a_label_for_the_field_counts_only_where_it_shows() {
        // superradiant.co: `<label for>` over the field.
        let mut d = FakeDom::new();
        let (_, body) = d.with_page();
        let label = text_el(&mut d, body, "label", "Organization", (0.0, 0.0, 120.0, 20.0));
        d.set_attr(label, "for", "org");
        let input = field(&mut d, body, 28.0);
        d.set_attr(input, "id", "org");
        assert!(field_has_visible_label(&d, input));

        // aisdr.com's HubSpot form: the label is there and not rendered.
        let mut d = FakeDom::new();
        let (_, body) = d.with_page();
        let label = text_el(&mut d, body, "label", "Work email", (0.0, 0.0, 0.0, 0.0));
        d.set_attr(label, "for", "email");
        d.set_style(label, "display", "none");
        let input = field(&mut d, body, 28.0);
        d.set_attr(input, "id", "email");
        assert!(!field_has_visible_label(&d, input));

        // Screen-reader text clipped to a 1px square.
        let mut d = FakeDom::new();
        let (_, body) = d.with_page();
        let label = text_el(&mut d, body, "label", "Search", (0.0, 0.0, 1.0, 1.0));
        d.set_attr(label, "for", "q");
        let input = field(&mut d, body, 28.0);
        d.set_attr(input, "id", "q");
        assert!(!field_has_visible_label(&d, input));
    }

    #[test]
    fn a_wrapping_label_and_labelledby_text_count() {
        let mut d = FakeDom::new();
        let (_, body) = d.with_page();
        let label = d.add(Some(body), "label");
        d.set_rect(label, 0.0, 0.0, 280.0, 70.0);
        text_el(&mut d, label, "span", "Your name", (0.0, 0.0, 100.0, 20.0));
        let input = field(&mut d, label, 28.0);
        assert!(field_has_visible_label(&d, input));

        // A label that wraps only the field names nothing.
        let mut d = FakeDom::new();
        let (_, body) = d.with_page();
        let label = d.add(Some(body), "label");
        d.set_rect(label, 0.0, 0.0, 280.0, 40.0);
        let input = field(&mut d, label, 0.0);
        assert!(!field_has_visible_label(&d, input));

        let mut d = FakeDom::new();
        let (_, body) = d.with_page();
        let heading = text_el(&mut d, body, "h3", "Billing address", (0.0, 0.0, 200.0, 24.0));
        d.set_attr(heading, "id", "billing");
        let spacer = d.add(Some(body), "hr");
        d.set_rect(spacer, 0.0, 30.0, 280.0, 1.0);
        let input = field(&mut d, body, 200.0);
        d.set_attr(input, "aria-labelledby", "billing");
        assert!(field_has_visible_label(&d, input));
        d.set_attr(input, "aria-labelledby", "missing");
        assert!(!field_has_visible_label(&d, input));
    }

    #[test]
    fn text_right_above_the_field_counts() {
        // pool-web-eight.vercel.app: a `<label>` with no `for`, then the field.
        let mut d = FakeDom::new();
        let (_, body) = d.with_page();
        let row = d.add(Some(body), "div");
        text_el(&mut d, row, "label", "Your Name", (0.0, 0.0, 280.0, 24.0));
        let input = field(&mut d, row, 32.0);
        assert!(field_has_visible_label(&d, input));

        // The same text, with the field in a wrapper of its own.
        let mut d = FakeDom::new();
        let (_, body) = d.with_page();
        let row = d.add(Some(body), "div");
        text_el(&mut d, row, "div", "Company", (0.0, 0.0, 280.0, 20.0));
        let wrap = d.add(Some(row), "div");
        d.set_rect(wrap, 0.0, 28.0, 280.0, 40.0);
        let input = field(&mut d, wrap, 28.0);
        assert!(field_has_visible_label(&d, input));
    }

    #[test]
    fn what_is_not_a_label_above_the_field_does_not_count() {
        // onco.cc: a paragraph of copy above a search box with `aria-label`.
        let mut d = FakeDom::new();
        let (_, body) = d.with_page();
        text_el(
            &mut d,
            body,
            "p",
            "Every technology, target, product, company and trial in oncology, linked together.",
            (0.0, 0.0, 600.0, 48.0),
        );
        let input = field(&mut d, body, 56.0);
        d.set_attr(input, "aria-label", "Search OnCo");
        assert!(!field_has_visible_label(&d, input));

        // A heading, an icon, a link, text far above, text beside the field.
        for (tag, text, rect) in [
            ("h2", "Send us a message", (0.0, 0.0, 280.0, 24.0)),
            ("svg", "", (0.0, 0.0, 16.0, 16.0)),
            ("a", "Forgot password?", (0.0, 0.0, 280.0, 20.0)),
            ("span", "Newsletter", (0.0, -200.0, 280.0, 20.0)),
            ("span", "Search", (-120.0, 40.0, 100.0, 20.0)),
        ] {
            let mut d = FakeDom::new();
            let (_, body) = d.with_page();
            let row = d.add(Some(body), "div");
            text_el(&mut d, row, tag, text, rect);
            let input = field(&mut d, row, 32.0);
            assert!(!field_has_visible_label(&d, input), "{tag} {text}");
        }

        // The first field's label does not name the second field.
        let mut d = FakeDom::new();
        let (_, body) = d.with_page();
        let row = d.add(Some(body), "div");
        let first = d.add(Some(row), "div");
        d.set_rect(first, 0.0, 0.0, 280.0, 70.0);
        text_el(&mut d, first, "label", "First name", (0.0, 0.0, 280.0, 20.0));
        field(&mut d, first, 28.0);
        let second = d.add(Some(row), "div");
        d.set_rect(second, 0.0, 78.0, 280.0, 40.0);
        let input = field(&mut d, second, 78.0);
        assert!(!field_has_visible_label(&d, input));
    }
}