Skip to content

[#25] Added 'hiddenTextSelector' and 'labelFilter' to clean visually hidden text out of labels. - #28

Merged
AlexSkrypnyk merged 3 commits into
mainfrom
feature/25-hidden-text
Nov 16, 2026
Merged

AlexSkrypnyk merged 3 commits into
mainfrom
feature/25-hidden-text

Conversation

@AlexSkrypnyk

@AlexSkrypnyk AlexSkrypnyk commented Nov 16, 2026 •

Copy link
Copy Markdown
Member

Closes #25

Summary

Sites get 2 ways to clean the labels in link_text, group_title, subgroup_title and field_label. The hiddenTextSelector setting drops whole elements, such as CivicTheme's .ct-visually-hidden suffix, and it works from drupalSettings.axel. The labelFilter(label, element) setting rewrites each label's text. Because drupalSettings can't hold a function, both integrations also read it from window.axelLabelFilter.

Screen-reader-only text was always part of the label. On a CivicTheme site, every external link sent link_text: Docs(Opens in a new tab/window), so the same CTA split into 2 report rows depending on its target. 3 icon-only social links all sent (Opens in a new tab/window) and collapsed into 1 row, even though each had a title.

Both settings are off by default, so nothing changes until a site sets one. When the selector or the filter leaves a label empty, it falls back to aria-label, then title (fields stop at aria-label), then the full text with the hidden elements kept. An icon button named only by a visually hidden Close, a visually hidden <label> or Drupal's visually hidden menu <h2> keeps the label it sends today. A filter that throws, throws a non-Error or returns a non-string logs to the console and leaves the label unchanged, so the event still goes out. Form controls stay out of every label on every pass, so the privacy guarantees are unchanged.

Before / After

<a href="https://github.com/" title="GitHub" target="_blank">
  <svg aria-hidden="true"/><span class="ct-visually-hidden">(Opens in a new tab/window)</span>
</a>

BEFORE: getLabel(el)
│
├─ getText(el)                        skips aria-hidden, select, textarea
│    └─▶ "(Opens in a new tab/window)"
└─▶ link_text: "(Opens in a new tab/window)"    aria-label and title never read

AFTER: getLabel(el, axel.labelOptions), hiddenTextSelector: '.ct-visually-hidden'
│
├─ getText(el, hiddenTextSelector)    also skips the matching span
│    └─▶ ""
├─ labelFilter("", el)                via axel.filterLabel(); a failure keeps the label
│    └─▶ ""
├─ aria-label ─▶ none
├─ title ──────▶ "GitHub"
└─▶ link_text: "GitHub"               the full text is tried only when all of the above are empty

Changes

Label building (src/core/dom.js)

  • getText(node, hiddenSelector) returns '' for an element matching the selector.
  • getTextLabel(node, element, fallback, { hiddenSelector, filter }) holds the fallback order once: filtered text without hidden elements, then fallback, then the filtered full text when a selector is set.
  • getLabel(element, options) uses it with aria-label || title as the fallback. An input button's value goes through the filter too.
  • collapseWhitespace() replaces the 2 inline copies of the whitespace regex.

Core (src/core/core.js)

  • DEFAULT_SETTINGS adds hiddenTextSelector: '' and labelFilter: null.
  • The constructor throws when labelFilter isn't a function, like it does for collectors, and builds labelOptions once for every label helper.
  • filterLabel(label, element) runs the filter and keeps the label when it throws or returns a non-string. It logs error?.message ?? error, so a thrown null can't break the event.

Event types

  • click.js passes axel.labelOptions to getLabel() for link_text and through getGroupTitle() for both titles.
  • field-complete.js: getFieldLabel() uses getTextLabel() with the field's aria-label as the fallback, and passes the field to the filter.

Integrations

  • drupal.js sets labelFilter from window.axelLabelFilter.
  • standalone.js prefers window.axelSettings.labelFilter, then window.axelLabelFilter.

Tests

  • tests/fixtures/cases.html adds case-click-hidden-text and case-field-hidden-text. They show that hidden text stays in the label by default, across link suffixes, icon links with title or aria-label, an icon button, group and subgroup titles and field labels.
  • click.test.js and field-complete.test.js cover:
    • Each fallback step with hiddenTextSelector.
    • The issue's own regex as a labelFilter, where icon links fall back to their title.
    • The filter on an input button's value.
    • Both settings together, where the filter runs on the text without hidden elements and then on the full text.
  • core.test.js covers the filter arguments, a non-function filter at construction, and a filter that throws, throws null, returns a number or returns nothing.
  • drupal.test.js and standalone.test.js cover window.axelLabelFilter, and the settings filter winning on a plain page.

Docs

  • README.md adds a "Label filter" section with the CivicTheme regex example. It also adds both settings to the Settings table, updates the link_text, field_label and group title rules, and lists window.axelLabelFilter under Security. link_text is no longer described as "visible" text, since visually hidden text is part of it by default.
  • docs/architecture/README.md covers getTextLabel(), filterLabel(), labelOptions and the integrations reading window.axelLabelFilter.

Decisions

  • Both options from the issue. The selector covers the common case without code and works in drupalSettings. The filter covers text a selector can't reach, such as a suffix inside the same text node.
  • Empty defaults. case-click-nested already reports Read more: Spring sale from a .visually-hidden span, so some sites rely on hidden context text. Defaulting to .visually-hidden, .sr-only would change their reports.
  • No CivicTheme class in the Drupal integration. The library stays free of theme class names, so a CivicTheme site sets .ct-visually-hidden or a filter itself.
  • Full-text fallback. The issue asks for aria-label, then title. The extra last step means the selector never empties a label that has text today.
  • The filter skips aria-label and title. The page author wrote those as names, so they go out as they are.

@AlexSkrypnyk AlexSkrypnyk added the A1 Worker 1 label Nov 16, 2026
@coderabbitai

coderabbitai Bot commented Nov 16, 2026 •

Copy link
Copy Markdown

Warning

Review limit reached

  • Run on-demand review

This review includes 14 billable files and costs up to $3.50.

  • Ask an admin to make reviews automatic

Open in CodeRabbit

Reviews can continue after your included limit without a manual trigger. An admin must approve usage-based billing.

Or wait 36 minutes for your next included review.

Check out review usage here.

View limit details

Limit details: You’ve used the included review currently available. Your 91 included PR review attempts over the past 7 days set your current allowance at 1 review per hour.

Learn how review limits work.

Review configuration:

Run configuration

  • Source mode: Auto
  • Repository: Unavailable
  • Branch: Unavailable
  • File: No configuration file from this repository applied
  • Commit: Unavailable
  • Layers: Organization UI
  • Review profile: ASSERTIVE
  • Plan: Team
  • Run ID: 3feaea24-8712-4ebd-ac36-99b6b38022aa
Commits

Reviewing files that changed from the base of the PR and between 8b900c5 and efd93da.

Files selected for processing: 14

  • README.md
  • docs/architecture/README.md
  • src/core/core.js
  • src/core/dom.js
  • src/core/event-types/click.js
  • src/core/event-types/field-complete.js
  • src/integrations/drupal.js
  • src/integrations/standalone.js
  • tests/core/core.test.js
  • tests/core/event-types/click.test.js
  • tests/core/event-types/field-complete.test.js
  • tests/fixtures/cases.html
  • tests/integrations/drupal.test.js
  • tests/integrations/standalone.test.js
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

@AlexSkrypnyk AlexSkrypnyk added the Needs review Pull request needs a review from assigned developers label Nov 16, 2026
@AlexSkrypnyk
AlexSkrypnyk force-pushed the feature/25-hidden-text branch from 50b54b0 to efd93da Compare November 16, 2026 09:39
@AlexSkrypnyk AlexSkrypnyk changed the title [#25] Added the 'hiddenTextSelector' setting to leave visually hidden text out of labels. [#25] Added 'hiddenTextSelector' and 'labelFilter' to clean visually hidden text out of labels. Nov 16, 2026
@AlexSkrypnyk
AlexSkrypnyk merged commit fbee9ce into main Nov 16, 2026
7 checks passed
@AlexSkrypnyk
AlexSkrypnyk deleted the feature/25-hidden-text branch November 16, 2026 09:44
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

A1 Worker 1 Needs review Pull request needs a review from assigned developers

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Let sites drop visually hidden text from 'link_text' and other labels

1 participant