Skip to content

OpenProject is the leading open source project management software for product, project and portfolio management. A powerful Jira alternative with agile planning, issue tracking, roadmaps, Gantt charts, time tracking, collaboration features, and more. Available on premises or in the cloud. ⭐ Star us on GitHub

[65606] Inform users on screen-readers that links will open in a new tab (ARIA-describedby) (#20371)

Behrokh Satarnejad1846e1686f54
diff --git a/app/helpers/application_helper.rb b/app/helpers/application_helper.rb
index 4a7043a6735..80fdade24e2 100644
--- a/app/helpers/application_helper.rb
+++ b/app/helpers/application_helper.rb
@@ -303,7 +303,7 @@ module ApplicationHelper
def body_data_attributes(local_assigns)
{
- controller: "application auto-theme-switcher hover-card-trigger beforeunload",
+ controller: "application auto-theme-switcher hover-card-trigger beforeunload external-links",
relative_url_root: root_path,
overflowing_identifier: ".__overflowing_body",
rendered_at: Time.zone.now.iso8601,
diff --git a/app/views/layouts/base.html.erb b/app/views/layouts/base.html.erb
index 12a70d6c470..c45f13efb87 100644
--- a/app/views/layouts/base.html.erb
+++ b/app/views/layouts/base.html.erb
@@ -63,6 +63,7 @@ See COPYRIGHT and LICENSE files for more details.
<div id="polite" aria-live="polite" aria-atomic="true" class="sr-only"></div>
<div id="assertive" aria-live="assertive" aria-atomic="true" class="sr-only"></div>
</live-region>
+<span id="open-blank-target-link-description" class="sr-only"><%= I18n.t("open_link_in_a_new_tab") %></span>
<opce-spot-drop-modal-portal></opce-spot-drop-modal-portal>
<% main_menu = render_main_menu(local_assigns.fetch(:menu_name, nil), @project) %>
<% side_displayed = content_for?(:sidebar) || content_for?(:main_menu) || !main_menu.blank? %>
diff --git a/config/locales/en.yml b/config/locales/en.yml
index 46349099b06..d8cb22f457f 100644
--- a/config/locales/en.yml
+++ b/config/locales/en.yml
@@ -4505,6 +4505,7 @@ en:
text_access_token_hint: "Access tokens allow you to grant external applications access to resources in OpenProject."
text_analyze: "Further analyze: %{subject}"
text_are_you_sure: "Are you sure?"
+ open_link_in_a_new_tab: "Open link in a new tab"
text_are_you_sure_continue: "Are you sure you want to continue?"
text_are_you_sure_with_children: "Delete work package and all child work packages?"
text_are_you_sure_with_project_custom_fields: "Deleting this attribute will also delete its values in all projects. Are you sure you want to do this?"
diff --git a/frontend/src/stimulus/controllers/external-links.controller.ts b/frontend/src/stimulus/controllers/external-links.controller.ts
new file mode 100644
index 00000000000..fafcdfe22c4
--- /dev/null
+++ b/frontend/src/stimulus/controllers/external-links.controller.ts
@@ -0,0 +1,89 @@
+//-- copyright
+// OpenProject is an open source project management software.
+// Copyright (C) the OpenProject GmbH
+//
+// This program is free software; you can redistribute it and/or
+// modify it under the terms of the GNU General Public License version 3.
+//
+// OpenProject is a fork of ChiliProject, which is a fork of Redmine. The copyright follows:
+// Copyright (C) 2006-2013 Jean-Philippe Lang
+// Copyright (C) 2010-2013 the ChiliProject Team
+//
+// This program is free software; you can redistribute it and/or
+// modify it under the terms of the GNU General Public License
+// as published by the Free Software Foundation; either version 2
+// of the License, or (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with this program; if not, write to the Free Software
+// Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
+//
+// See COPYRIGHT and LICENSE files for more details.
+//++
+
+import { ApplicationController } from 'stimulus-use';
+import { useMutation } from 'stimulus-use';
+
+const BLANK_LINK_QUERY = 'a[target="_blank"]';
+const BLANK_LINK_DESCRIPTION_ID = 'open-blank-target-link-description';
+
+const isElement = (node:Node):node is Element => node.nodeType === Node.ELEMENT_NODE;
+const isBlankLink = (elem:Element):elem is HTMLAnchorElement => elem.matches(BLANK_LINK_QUERY);
+
+/**
+ * Observes all external links and sets their ARIA `describedby` attribute to
+ * {BLANK_LINK_DESCRIPTION_ID} - this element should exist in the DOM and
+ * provide localized text content along the lines of "Open link in a new tab".
+ *
+ * The goal is to make users of Assistive Technology aware that they may have to
+ * switch tabs on clicking a link.
+ *
+ * We consider links with a `target` attribute set to "_blank" as "external".
+ */
+export default class ExternalLinksController extends ApplicationController {
+ connect() {
+ useMutation(this, { attributes: true, childList: true, subtree: true, attributeFilter: ['target'] });
+
+ // initial pass
+ document.querySelectorAll(BLANK_LINK_QUERY).forEach(applyLinkDescription);
+ }
+
+ mutate(mutations:MutationRecord[]) {
+ mutations.forEach((mutation) => {
+ mutation.addedNodes.forEach((node) => {
+ if (isElement(node)) {
+ // added element itself is a blank link
+ if (isBlankLink(node)) {
+ applyLinkDescription(node);
+ }
+ // added sub-trees
+ node.querySelectorAll(BLANK_LINK_QUERY).forEach(applyLinkDescription);
+ }
+ });
+
+ // attribute changes
+ if (
+ mutation.type === 'attributes' &&
+ mutation.attributeName === 'target' &&
+ isElement(mutation.target) &&
+ isBlankLink(mutation.target)
+ ) {
+ applyLinkDescription(mutation.target);
+ }
+ });
+ }
+}
+
+function applyLinkDescription(link:HTMLAnchorElement) {
+ const existingValue = link.getAttribute('aria-describedby');
+ if (!existingValue) {
+ link.setAttribute('aria-describedby', BLANK_LINK_DESCRIPTION_ID);
+ } else if (!existingValue.split(/\s+/).includes(BLANK_LINK_DESCRIPTION_ID)) {
+ link.setAttribute('aria-describedby', existingValue + ' ' + BLANK_LINK_DESCRIPTION_ID);
+ }
+}
diff --git a/frontend/src/stimulus/setup.ts b/frontend/src/stimulus/setup.ts
index 3565ee7662a..174b3260c37 100644
--- a/frontend/src/stimulus/setup.ts
+++ b/frontend/src/stimulus/setup.ts
@@ -30,6 +30,7 @@ import AutoThemeSwitcher from './controllers/auto-theme-switcher.controller';
import { OpenProjectStimulusApplication } from 'core-stimulus/openproject-stimulus-application';
import { Application } from '@hotwired/stimulus';
import { BeforeunloadController } from './controllers/beforeunload.controller';
+import ExternalLinksController from './controllers/external-links.controller';
declare global {
interface Window {
@@ -65,6 +66,7 @@ OpenProjectStimulusApplication.preregister('work-packages--activities-tab--stems
OpenProjectStimulusApplication.preregister('work-packages--activities-tab--editor', EditorController);
OpenProjectStimulusApplication.preregister('beforeunload', BeforeunloadController);
OpenProjectStimulusApplication.preregister('auto-theme-switcher', AutoThemeSwitcher);
+OpenProjectStimulusApplication.preregister('external-links', ExternalLinksController);
const instance = OpenProjectStimulusApplication.start();
window.Stimulus = instance;
diff --git a/lookbook/docs/patterns/04-links.md.erb b/lookbook/docs/patterns/04-links.md.erb
index cd6449cc686..39c2389649f 100644
--- a/lookbook/docs/patterns/04-links.md.erb
+++ b/lookbook/docs/patterns/04-links.md.erb
@@ -12,8 +12,8 @@ There are **two exceptions** where links may open in a new tab (`target="_blank"
When a link opens in a new tab, the following must be implemented:
-* An **`aria-label`** must be added to inform screen reader users that the link opens in a new tab (e.g., `"Opens in a new tab"`).
* The link must be followed by the `link-external` icon to visually indicate that a new tab will open.
+* Note: the link needs an accessible hint that it is opened in a new tab. This is done automatically, for details have a look at [accessibility guidelines](./accessibility/blank_target_links)
# Inline Link Styling
diff --git a/lookbook/docs/patterns/accessibility/19-blank-target-links.md.erb b/lookbook/docs/patterns/accessibility/19-blank-target-links.md.erb
new file mode 100644
index 00000000000..74b32208bb0
--- /dev/null
+++ b/lookbook/docs/patterns/accessibility/19-blank-target-links.md.erb
@@ -0,0 +1,31 @@
+Links that open in a new browser tab or window (`target="_blank"`) can be confusing for users, especially for those using assistive technologies. To ensure accessibility, we need to provide clear context so that all users understand that the link will open in a new tab.
+
+## Why `_blank` Links Need Accessible Hints
+
+- Users may lose track of their current page if a link opens in a new tab unexpectedly.
+- Screen reader users may not be aware of the new tab unless it is explicitly communicated.
+- Providing a description improves usability and ensures compliance with WCAG guidelines.
+
+---
+
+## Recommended Attributes
+
+To make `_blank` links accessible, we rely on:
+
+- **`aria-describedby`**: Points to a hidden element describing the new tab behavior.
+- **`aria-label`** *(optional)*: Can include context about the link and new tab behavior.
+- **`title`** *(optional)*: Provides a tooltip for sighted users.
+
+---
+
+## Technical notes
+
+We implemented a stimulus controller called `external-links` which automatically applies an `aria-describedby` attribute to all links that set `target='_blank'`. Therefore, we included a single hidden element in the `base.html` which all `_blank` links can reference:
+
+```erb
+<span id="open-blank-target-link-description" class="sr-only">
+ <%= I18n.t("open_link_in_a_new_tab") %>
+</span>
+```
+
+By that all external links automatically read out to the screen reader users that they open a new tab.
diff --git a/spec/features/a11y/external_links_spec.rb b/spec/features/a11y/external_links_spec.rb
new file mode 100644
index 00000000000..363d427c925
--- /dev/null
+++ b/spec/features/a11y/external_links_spec.rb
@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+#-- copyright
+# OpenProject is an open source project management software.
+# Copyright (C) the OpenProject GmbH
+#
+# This program is free software; you can redistribute it and/or
+# modify it under the terms of the GNU General Public License version 3.
+#
+# OpenProject is a fork of ChiliProject, which is a fork of Redmine. The copyright follows:
+# Copyright (C) 2006-2013 Jean-Philippe Lang
+# Copyright (C) 2010-2013 the ChiliProject Team
+#
+# This program is free software; you can redistribute it and/or
+# modify it under the terms of the GNU General Public License
+# as published by the Free Software Foundation; either version 2
+# of the License, or (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, write to the Free Software
+# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
+#
+# See COPYRIGHT and LICENSE files for more details.
+#++
+
+require "rails_helper"
+
+RSpec.describe "External links", :js do
+ let(:user) { create(:user) }
+
+ before do
+ login_as user
+ end
+
+ it "sets ARIA describedby on external links" do
+ visit "/"
+
+ expect(page).to have_link target: "_blank", described_by: "Open link in a new tab"
+ expect(page.all(:link, target: "_blank")).to all match_selector(:link, described_by: "Open link in a new tab")
+ end
+end