dommy 0.8.0 → 0.9.0

data/lib/dommy/internal/accessible_name.rb

@@ -0,0 +1,301 @@
+# frozen_string_literal: true
+
+module Dommy
+  module Internal
+    # Computes an element's WAI-ARIA *accessible name* (the "accname"
+    # algorithm) — what WPT's `test_driver.get_computed_label` returns and
+    # Testing Library's name option matches. A focused implementation covering
+    # the common steps: aria-labelledby, aria-label, native host-language
+    # labels (<label>, alt), name-from-content for the roles that allow it, and
+    # the title fallback. Name-from-content folds in CSS `::before` / `::after`
+    # generated content (the accname algorithm requires it) — but only the text
+    # components it can resolve without rendering: quoted strings and `attr()`.
+    # `counter()` / `counters()`, bare `url()` images, and other layout-derived
+    # content contribute nothing. Embedded control values are out of scope.
+    module AccessibleName
+      # Roles whose accessible name may come from descendant content. (term /
+      # definition are nameFrom:author per ARIA, so they are NOT here.)
+      NAME_FROM_CONTENT = %w[
+        button cell checkbox columnheader comment gridcell heading
+        link menuitem menuitemcheckbox menuitemradio option radio row rowheader
+        sectionhead suggestion switch tab tooltip treeitem
+      ].freeze
+
+      # Form controls whose name can come from an associated <label>.
+      LABELABLE = %w[button input meter output progress select textarea].freeze
+
+      module_function
+
+      # The accessible name string ("" when none). ASCII whitespace runs are
+      # collapsed and the result trimmed, matching how browsers / Playwright
+      # flatten an accessible name.
+      def compute(element)
+        squish(name_of(element, [], referenced: false, allow_content: false))
+      end
+
+      # Collapse ASCII whitespace runs to single spaces and trim.
+      def squish(text)
+        text.to_s.gsub(/\s+/, " ").strip
+      end
+
+      # `referenced`: this node was reached through aria-labelledby, so it must
+      # not start a fresh labelledby traversal (prevents loops, and lets a
+      # self-reference fall through to its own aria-label/content).
+      # `allow_content`: name-from-content is permitted regardless of role (true
+      # for referenced and recursed-into nodes); at the top it is role-gated.
+      def name_of(node, visited, referenced:, allow_content:)
+        return "" unless node.respond_to?(:__dommy_backend_node__)
+
+        # 1. aria-labelledby (not when already inside a labelledby traversal).
+        unless referenced
+          labelled = labelledby_name(node, visited)
+          return labelled unless labelled.nil?
+        end
+
+        # 2. aria-label.
+        aria_label = node.get_attribute("aria-label").to_s
+        return aria_label unless aria_label.strip.empty?
+
+        # 3. Native host-language labeling.
+        native = native_name(node, visited)
+        return native unless native.nil?
+
+        # 4. Name from content (role-permitting, or when recursing). Guard
+        #    against content cycles with the visited set.
+        key = node.__dommy_backend_node__
+        if (allow_content || NAME_FROM_CONTENT.include?(node.computed_role)) && visited.none? { |v| v.equal?(key) }
+          content = content_name(node, visited + [key])
+          # Preserve whitespace-only content: a space deep in the subtree is the
+          # separator between sibling text runs ("button" + " " + "label").
+          return content unless content.empty?
+        end
+
+        # 5. Tooltip (title) fallback.
+        title = node.get_attribute("title").to_s
+        return title unless title.empty?
+
+        # 6. Placeholder — the lowest-priority name source (below the title).
+        placeholder = placeholder_fallback(node)
+        return placeholder if placeholder
+
+        ""
+      end
+
+      # aria-labelledby: join each referenced element's name. Returns nil when
+      # the attribute is absent/empty (so the caller falls through).
+      def labelledby_name(node, visited)
+        referenced_names(node, "aria-labelledby", visited)
+      end
+
+      # Join the accessible names of the elements an IDREF-list attribute
+      # (aria-labelledby / aria-describedby) points at. Returns nil when the
+      # attribute is absent/empty or resolves to nothing, so the caller falls
+      # through. Each referenced node is named with `referenced: true` (it does
+      # not restart a labelledby traversal) and `allow_content: true`.
+      def referenced_names(node, attribute, visited = [])
+        ids = node.get_attribute(attribute).to_s.split(/\s+/).reject(&:empty?)
+        return nil if ids.empty?
+
+        doc = node.respond_to?(:document) ? node.document : nil
+        return nil unless doc
+
+        parts = ids.map do |id|
+          ref = doc.get_element_by_id(id)
+          ref ? name_of(ref, visited, referenced: true, allow_content: true) : ""
+        end
+        joined = parts.join(" ").strip
+        joined.empty? ? nil : joined
+      end
+
+      # <label>/alt host-language names. Returns nil when not applicable.
+      def native_name(node, visited)
+        tag = node.tag_name.to_s.downcase
+        case tag
+        when "img", "area"
+          alt = node.get_attribute("alt")
+          alt.nil? ? nil : alt
+        when "input"
+          input_native_name(node, visited)
+        when "fieldset"
+          child_element_name(node, "legend", visited)
+        when "figure"
+          child_element_name(node, "figcaption", visited)
+        when "table"
+          child_element_name(node, "caption", visited)
+        when *LABELABLE
+          label_text(node, visited)
+        end
+      end
+
+      # The name of the first child element with the given tag (e.g. a
+      # <fieldset>'s <legend>, a <table>'s <caption>). nil when absent.
+      def child_element_name(node, tag, visited)
+        bn = node.__dommy_backend_node__
+        return nil unless bn.respond_to?(:children)
+
+        child = bn.children.find { |c| c.respond_to?(:name) && c.name.to_s.casecmp?(tag) }
+        return nil unless child
+
+        name_of(node.document.wrap_node(child), visited, referenced: false, allow_content: true)
+      end
+
+      # Input types for which the placeholder contributes the accessible name
+      # (the text-like inputs); type=number / range / date / … do not.
+      PLACEHOLDER_TYPES = %w[text search tel url email password].freeze
+
+      def input_native_name(node, visited)
+        type = node.get_attribute("type").to_s.downcase
+        return node.get_attribute("alt") || node.get_attribute("value").to_s if type == "image"
+        return node.get_attribute("value").to_s if %w[button submit reset].include?(type)
+
+        label_text(node, visited)
+      end
+
+      # The placeholder names a text-like input / textarea, but only as the
+      # lowest-priority source (below the title).
+      def placeholder_fallback(node)
+        tag = node.tag_name.to_s.downcase
+        return placeholder_name(node) if tag == "textarea"
+        return nil unless tag == "input"
+
+        type = node.get_attribute("type").to_s.downcase
+        (type.empty? || PLACEHOLDER_TYPES.include?(type)) ? placeholder_name(node) : nil
+      end
+
+      def placeholder_name(node)
+        placeholder = node.get_attribute("placeholder").to_s
+        placeholder.empty? ? nil : placeholder
+      end
+
+      # The concatenated text of the <label>s associated with a control:
+      # label[for=id] anywhere, plus an ancestor <label>. nil → no labels.
+      def label_text(node, visited)
+        labels = associated_labels(node)
+        return nil if labels.empty?
+
+        text = labels.map { |l| name_of(l, visited, referenced: false, allow_content: true) }.join(" ").strip
+        text.empty? ? nil : text
+      end
+
+      def associated_labels(node)
+        labels = []
+        id = node.get_attribute("id").to_s
+        unless id.empty?
+          doc = node.document
+          labels.concat(doc.query_selector_all("label[for='#{id}']").to_a) if doc
+        end
+        ancestor = closest_label(node)
+        labels << ancestor if ancestor && !labels.include?(ancestor)
+        labels
+      end
+
+      def closest_label(node)
+        bn = node.__dommy_backend_node__&.parent
+        while bn.respond_to?(:name)
+          return node.document.wrap_node(bn) if bn.name.to_s.casecmp?("label")
+
+          bn = bn.parent
+        end
+        nil
+      end
+
+      # Concatenate child text nodes and the names of element children, with the
+      # `::before` content prepended and `::after` content appended (accname
+      # name-from-content folds in generated content).
+      def content_name(node, visited)
+        bn = node.__dommy_backend_node__
+        return "" unless bn.respond_to?(:children)
+
+        children = bn.children.map do |child|
+          if child.respond_to?(:text?) && child.text?
+            child.text.to_s
+          elsif child.respond_to?(:element?) && child.element?
+            wrapped = node.document.wrap_node(child)
+            next "" unless wrapped
+
+            name = name_of(wrapped, visited, referenced: false, allow_content: true)
+            # Concatenate contributions directly (inline content glues:
+            # "button" + "" + "label" -> "buttonlabel"); a block-level box is
+            # padded with spaces so sibling cells / blocks separate
+            # ("Profile" + "A" -> "Profile A"). compute collapses the runs.
+            block_level?(wrapped) ? " #{name} " : name
+          else
+            ""
+          end
+        end.join
+
+        pseudo_content(node, "::before") + children + pseudo_content(node, "::after")
+      end
+
+      # Elements that generate a block-level box by the UA stylesheet — used as
+      # the fallback when no CSS layer is available to compute `display`.
+      BLOCK_TAGS = %w[
+        address article aside blockquote caption dd details div dl dt fieldset
+        figcaption figure footer form h1 h2 h3 h4 h5 h6 header hr legend li main
+        menu nav ol p pre section summary table tbody td tfoot th thead tr ul
+      ].freeze
+
+      # Whether an element generates a block-level box, so its text is separated
+      # from siblings by whitespace in name-from-content (inline boxes glue). The
+      # computed `display` decides when CSS is available (honoring author CSS);
+      # otherwise the UA-default block-tag set is used so table cells / list
+      # items still separate.
+      def block_level?(element)
+        display = computed_display(element)
+        return BLOCK_TAGS.include?(element.local_name.to_s.downcase) if display.nil?
+
+        !display.start_with?("inline") && !%w[none contents].include?(display)
+      end
+
+      def computed_display(element)
+        value = Internal::CSS::Cascade.computed_style(element)["display"].to_s
+        value.empty? ? nil : value
+      rescue StandardError
+        nil
+      end
+
+      # The text contribution of a `::before` / `::after` pseudo-element's
+      # computed `content`. "" when the CSS layer is unavailable, the pseudo has
+      # no generated content (`none` / `normal`), or its content is purely
+      # non-text (counter/url/etc.).
+      def pseudo_content(node, pseudo)
+        return "" unless Internal::CSS::Parser.available?
+
+        decl = Internal::CSS::ComputedStyleDeclaration.new(node, pseudo_element: pseudo)
+        content_text(decl.get_property_value("content"), node)
+      rescue StandardError
+        ""
+      end
+
+      # Resolve a computed `content` value to its accname text. `counter()` /
+      # `counters()` are resolved first (to quoted strings); then it scans for
+      # the text-bearing components in order — quoted strings (CSS-unescaped) and
+      # `attr(name)` (read off `node`) — and ignores everything else (`none` /
+      # `normal`, `url()`, keywords). The image `/ "alt"` syntax is covered for
+      # free: its alt string matches the quoted-string branch.
+      def content_text(value, node)
+        v = value.to_s.strip
+        return "" if v.empty? || v == "none" || v == "normal"
+
+        if v.match?(/\bcounters?\(/i)
+          v = Internal::CSS::Counters.substitute(v, Internal::CSS::Cascade.counter_values(node))
+        end
+
+        text = +""
+        v.scan(/"((?:[^"\\]|\\.)*)"|'((?:[^'\\]|\\.)*)'|attr\(\s*([-\w]+)\s*\)/) do
+          dq, sq, attr = Regexp.last_match.captures
+          text << (attr ? node.get_attribute(attr).to_s : unescape_css_string(dq || sq))
+        end
+        text
+      end
+
+      # CSS string unescaping: `\HEX ` → the code point, `\<char>` → the char.
+      def unescape_css_string(str)
+        str.gsub(/\\(?:([0-9a-fA-F]{1,6})[ \t\n]?|(.))/) do
+          hex = Regexp.last_match(1)
+          hex ? [hex.to_i(16)].pack("U") : Regexp.last_match(2)
+        end
+      end
+    end
+  end
+end

data/lib/dommy/internal/aria_role.rb

@@ -0,0 +1,252 @@
+# frozen_string_literal: true
+
+module Dommy
+  module Internal
+    # Computes the WAI-ARIA *computed role* of an element — the value WPT's
+    # `test_driver.get_computed_role` returns and Testing Library's `getByRole`
+    # relies on. An explicit, valid `role` attribute wins; otherwise the implicit
+    # role is derived from the HTML element (HTML-AAM), with the common
+    # context-sensitive cases (header/footer landmarks, named section/form,
+    # input/select by type) handled. Layout- or tree-dependent subtleties
+    # (heading levels, th scope/row context) are intentionally simplified.
+    module AriaRole
+      # Abstract roles can never be a computed role; an explicit one is ignored.
+      ABSTRACT = %w[
+        command composite input landmark range roletype section sectionhead
+        select structure widget window
+      ].freeze
+
+      # Concrete ARIA 1.2 roles accepted as an explicit `role` token.
+      CONCRETE = %w[
+        alert alertdialog application article banner blockquote button caption
+        cell checkbox code columnheader combobox comment complementary
+        contentinfo definition deletion dialog directory document emphasis
+        feed figure form generic grid gridcell group heading img insertion link
+        list listbox listitem log main mark marquee math menu menubar menuitem
+        menuitemcheckbox menuitemradio meter navigation none note option
+        paragraph presentation progressbar radio radiogroup region row rowgroup
+        rowheader scrollbar search searchbox separator slider spinbutton status
+        strong subscript suggestion superscript switch tab table tablist tabpanel
+        term textbox time timer toolbar tooltip tree treegrid treeitem
+      ].freeze
+
+      # Deprecated role synonyms normalized to their canonical computed role.
+      SYNONYMS = { "directory" => "list", "image" => "img", "presentation" => "none" }.freeze
+
+      # Roles that require an author-provided accessible name; without one the
+      # token is skipped (role fallback continues to the next token, else the
+      # implicit role). Per WPT get_computed_role; note Chromium's ariaSnapshot
+      # differs for an unnamed terminal role="region"/"form" (it keeps the role).
+      NAME_REQUIRED = %w[form region].freeze
+
+      # Sectioning content under which <header>/<footer> are generic rather than
+      # banner/contentinfo landmarks.
+      SECTIONING = %w[article aside main nav section].freeze
+
+      module_function
+
+      # The computed role string, or "" when the element maps to no role.
+      def compute(element)
+        explicit_role(element) || implicit_role(element) || ""
+      end
+
+      # The heading level for a heading element: an explicit positive
+      # `aria-level`, else the `hN` tag's number, else nil. The role itself
+      # stays "heading" (level is a separate ARIA property the a11y tree emits).
+      def heading_level(element)
+        aria = element.get_attribute("aria-level").to_s
+        return aria.to_i if aria.match?(/\A\d+\z/) && aria.to_i.positive?
+
+        tag = element.local_name.to_s.downcase
+        tag.match?(/\Ah[1-6]\z/) ? tag[1].to_i : nil
+      end
+
+      def explicit_role(element)
+        raw = element.get_attribute("role").to_s.strip
+        return nil if raw.empty?
+
+        raw.split(/\s+/).each do |token|
+          role = SYNONYMS.fetch(token.downcase, token.downcase)
+          next unless CONCRETE.include?(role) && !ABSTRACT.include?(role)
+          # region / form need an author-supplied name; otherwise fall through to
+          # the next token (or the implicit role).
+          next if NAME_REQUIRED.include?(role) && !named?(element)
+          # A presentational role yields to the implicit role when the element is
+          # focusable or carries a global ARIA state/property (conflict
+          # resolution); otherwise it stands.
+          return nil if role == "none" && presentation_conflict?(element)
+
+          return role
+        end
+        nil
+      end
+
+      def implicit_role(element)
+        case element.tag_name.to_s.downcase
+        when "a", "area" then element.has_attribute?("href") ? "link" : (element.tag_name.casecmp?("a") ? "generic" : nil)
+        when "article" then "article"
+        when "aside" then "complementary"
+        when "b", "bdi", "bdo", "data", "i", "q", "samp", "small", "span", "u", "div" then "generic"
+        when "blockquote" then "blockquote"
+        when "button" then "button"
+        when "caption" then "caption"
+        when "code" then "code"
+        when "del" then "deletion"
+        when "dialog" then "dialog"
+        when "dd" then "definition"
+        when "details" then "group"
+        when "dfn" then "term"
+        when "dt" then "term"
+        when "em" then "emphasis"
+        when "fieldset" then "group"
+        when "figure" then "figure"
+        when "footer" then landmark_or_generic(element, "contentinfo")
+        when "form" then named?(element) ? "form" : "generic"
+        when "h1", "h2", "h3", "h4", "h5", "h6" then "heading"
+        when "header" then landmark_or_generic(element, "banner")
+        when "hr" then "separator"
+        when "img" then img_role(element)
+        when "input" then input_role(element)
+        when "ins" then "insertion"
+        when "li" then "listitem"
+        when "main" then "main"
+        when "mark" then "mark"
+        when "math" then "math"
+        when "menu", "ol", "ul" then "list"
+        when "meter" then "meter"
+        when "nav" then "navigation"
+        when "optgroup" then "group"
+        when "option" then "option"
+        when "output" then "status"
+        when "p" then "paragraph"
+        when "progress" then "progressbar"
+        when "search" then "search"
+        when "section" then named?(element) ? "region" : "generic"
+        when "select" then select_role(element)
+        when "strong" then "strong"
+        when "sub" then "subscript"
+        when "sup" then "superscript"
+        when "table" then "table"
+        when "tbody", "tfoot", "thead" then "rowgroup"
+        when "td" then "cell"
+        when "textarea" then "textbox"
+        when "th" then th_role(element)
+        when "time" then "time"
+        when "tr" then "row"
+        end
+      end
+
+      # --- helpers --------------------------------------------------------
+
+      def img_role(element)
+        alt = element.get_attribute("alt")
+        # An explicitly empty alt makes the image presentational. Return the
+        # canonical "none" (not its "presentation" synonym) so the accessibility
+        # tree flattens it like any other presentational node.
+        alt == "" ? "none" : "img"
+      end
+
+      # A <th> is a column or row header. An explicit `scope` wins; otherwise the
+      # auto algorithm: a header cell that borders a data cell (<td>) within its
+      # row heads that row, so it is a row header; a header cell with only header
+      # neighbors heads its column.
+      def th_role(element)
+        case element.get_attribute("scope").to_s.downcase
+        when "row", "rowgroup" then "rowheader"
+        when "col", "colgroup" then "columnheader"
+        else auto_th_role(element)
+        end
+      end
+
+      def auto_th_role(element)
+        row = element.respond_to?(:parent_element) ? element.parent_element : nil
+        return "columnheader" unless row
+
+        cells = row.children.select { |cell| %w[td th].include?(cell.local_name.to_s.downcase) }
+        index = cells.index { |cell| same_node?(cell, element) }
+        return "columnheader" unless index
+
+        previous = index.zero? ? nil : cells[index - 1]
+        neighbors = [previous, cells[index + 1]].compact
+        neighbors.any? { |cell| cell.local_name.to_s.casecmp?("td") } ? "rowheader" : "columnheader"
+      end
+
+      def same_node?(first, second)
+        first && second && first.__dommy_backend_node__ == second.__dommy_backend_node__
+      end
+
+      INPUT_ROLES = {
+        "button" => "button", "submit" => "button", "reset" => "button",
+        "image" => "button", "file" => "button", "checkbox" => "checkbox", "radio" => "radio",
+        "range" => "slider", "number" => "spinbutton", "email" => "textbox",
+        "tel" => "textbox", "text" => "textbox", "url" => "textbox", "search" => "searchbox",
+        # type=password has no ARIA role per HTML-AAM (to avoid exposing the
+        # value) but Chromium / Playwright expose it as a textbox. The
+        # date/time family and color likewise expose as a textbox.
+        "password" => "textbox", "color" => "textbox", "date" => "textbox",
+        "datetime-local" => "textbox", "month" => "textbox", "week" => "textbox",
+        "time" => "textbox"
+      }.freeze
+
+      def input_role(element)
+        type = element.get_attribute("type").to_s.downcase
+        return "textbox" if type.empty?
+
+        # type=search is searchbox only without a suggestions list; the common
+        # case has no list, so map to searchbox.
+        INPUT_ROLES[type]
+      end
+
+      def select_role(element)
+        multiple = element.has_attribute?("multiple")
+        size = element.get_attribute("size").to_s.to_i
+        multiple || size > 1 ? "listbox" : "combobox"
+      end
+
+      # <header>/<footer> are landmarks only when not scoped to sectioning
+      # content; otherwise generic.
+      def landmark_or_generic(element, landmark)
+        node = element.respond_to?(:__dommy_backend_node__) ? element.__dommy_backend_node__&.parent : nil
+        while node && node.respond_to?(:name)
+          return "generic" if SECTIONING.include?(node.name.to_s.downcase)
+
+          node = node.parent
+        end
+        landmark
+      end
+
+      def named?(element)
+        return true if present?(element.get_attribute("aria-label"))
+        return true if present?(element.get_attribute("aria-labelledby"))
+
+        present?(element.get_attribute("title"))
+      end
+
+      def present?(value)
+        !value.nil? && !value.to_s.empty?
+      end
+
+      # Presentation conflict resolution (simplified): a focusable element or one
+      # with a global ARIA attribute keeps its implicit role.
+      def presentation_conflict?(element)
+        return true if focusable?(element)
+
+        %w[aria-label aria-labelledby aria-describedby].any? { |a| present?(element.get_attribute(a)) }
+      end
+
+      # Whether the element is focusable — a tabindex, or a natively-focusable
+      # control (a/area with href, or a non-disabled form control). Native
+      # focusability matters: <a href role=presentation> is still a link.
+      def focusable?(element)
+        return true if present?(element.get_attribute("tabindex"))
+
+        case element.local_name.to_s.downcase
+        when "a", "area" then element.has_attribute?("href")
+        when "button", "select", "textarea" then !element.has_attribute?("disabled")
+        when "input" then element.get_attribute("type").to_s.downcase != "hidden" && !element.has_attribute?("disabled")
+        else false
+        end
+      end
+    end
+  end
+end

data/lib/dommy/internal/aria_snapshot.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Dommy
+  module Internal
+    # Serializes an AccessibilityTree into a Playwright-compatible ARIA snapshot
+    # (a YAML-ish indented outline). Each accessible node is a line
+    #
+    #   - <role> "<name>" [flag] [level=N]:
+    #
+    # with a trailing ":" only when it has children, 2-space indentation per
+    # depth, and significant text as `- text: "…"`. The synthetic root is not
+    # printed (a document has no top line), matching Playwright.
+    module AriaSnapshot
+      # The serialized flags, in fixed render order. A boolean flag renders only
+      # when true or "mixed"; `level` renders as `[level=N]`. `readonly` and
+      # `required` are computed (AriaState) but NOT serialized — Playwright emits
+      # neither in its snapshot — so they stay out of this list.
+      FLAG_ORDER = %i[checked disabled expanded level pressed selected].freeze
+
+      module_function
+
+      def serialize(root)
+        lines = []
+        root.children.each { |child| emit(child, 0, lines) }
+        return "" if lines.empty?
+
+        "#{lines.join("\n")}\n"
+      end
+
+      def emit(node, depth, lines)
+        indent = "  " * depth
+        if node.text?
+          lines << "#{indent}- text: #{quote(node.name)}"
+          return
+        end
+
+        header = "#{indent}- #{node.role}"
+        header += " #{quote(node.name)}" unless node.name.to_s.empty?
+        flags(node.states).each { |flag| header += " #{flag}" }
+        header += ":" unless node.children.empty?
+        lines << header
+
+        node.children.each { |child| emit(child, depth + 1, lines) }
+      end
+
+      # The bracketed flag tokens for a node's states, in FLAG_ORDER. Booleans
+      # render only when true/"mixed"; a "mixed" value renders `[flag=mixed]`.
+      def flags(states)
+        FLAG_ORDER.filter_map do |key|
+          value = states[key]
+          if key == :level
+            "[level=#{value}]" if value
+          elsif value == "mixed"
+            "[#{key}=mixed]"
+          elsif value == true
+            "[#{key}]"
+          end
+        end
+      end
+
+      def quote(text) = "\"#{text.to_s.gsub("\\", "\\\\\\\\").gsub("\"", "\\\"")}\""
+    end
+  end
+end