[62708] Implementing ARIA live regions to communicate contextual changes (opf#17920)

* check if there is a screen reader active on page load

* hide the flat picker for screen readers

* make the banner focusable

* change the focus color in banner

* change disabled to readonly input fields

* change replace_via_turbo_stream to add a message to it

* add live region of github to out project

* add a method to send the aria message

* make it possible to pass the attributes

* pass type of aria live region to front-end based on the action

* remove focused field from date picker

* focus on tabs when there is no banner

* Revert "remove focused field from date picker"

This reverts commit ab5e306.

* focus on the first element when opening the dialog

* remove auto-focus

* undo changes for adding a message

* add a new input method for adding a date and select today as a date

* remove label and name from form input

* change readonly to disabled

* undo changes for date-form

* delete dateform file

* add aria-live for fields in date pickr

* add a turbo stream to the component to load the messages for aria live regions

* undo changes for check f there is an active screen reader

* use settimeout instead of add event listener, so turbo frame also can be used hare

* undo changes for text with link form input

* remove text with link form input

* add documentation for aria-live region

* add an example for using current method in relation creation

* add aria live region in date-pickr dialog

* add some delay for polite messages to make sure it is caught

* send a message to be gotten by screen reader in date picker while changing inputs

* remove aria-live form inputs in date pickr

* show update message after any change in inputs of date picker

* fix rubocup errors in relation controller

* fix rubocup errors in datepicker controller

* fix eslint error

* update docs

* add some details to the aria live doc

* remove test for aria-live on inputs of date pickr

* remove unnecessary live region polite for date picker

* Update lookbook/docs/patterns/18-aria-live.md.erb

Co-authored-by: Henriette Darge <h.darge@openproject.com>

* Update lookbook/docs/patterns/18-aria-live.md.erb

Co-authored-by: Henriette Darge <h.darge@openproject.com>

* fix comment in preview controller

* remove role: alert

* set correct value for target

* move aria turbo stream below live region

* add missing spaces and a better headline for js handling turbo aria action

* move the exception of modals and dialogs to the end of doc file

* Update lookbook/docs/patterns/accessibility/18-aria-live.md.erb

Co-authored-by: Alexander Brandon Coles <a.coles@openproject.com>

* Update frontend/src/turbo/aria-stream-action.ts

Co-authored-by: Alexander Brandon Coles <a.coles@openproject.com>

* Update lookbook/docs/patterns/accessibility/18-aria-live.md.erb

Co-authored-by: Alexander Brandon Coles <a.coles@openproject.com>

* Update app/controllers/work_packages/date_picker_controller.rb

Co-authored-by: Alexander Brandon Coles <a.coles@openproject.com>

* Update lookbook/docs/patterns/accessibility/18-aria-live.md.erb

Co-authored-by: Alexander Brandon Coles <a.coles@openproject.com>

* Update app/controllers/concerns/op_turbo/component_stream.rb

Co-authored-by: Alexander Brandon Coles <a.coles@openproject.com>

* Update app/controllers/work_packages/date_picker_controller.rb

Co-authored-by: Alexander Brandon Coles <a.coles@openproject.com>

* Update app/controllers/work_packages/date_picker_controller.rb

Co-authored-by: Alexander Brandon Coles <a.coles@openproject.com>

* Update lookbook/docs/patterns/accessibility/18-aria-live.md.erb

Co-authored-by: Alexander Brandon Coles <a.coles@openproject.com>

* Update lookbook/docs/patterns/accessibility/18-aria-live.md.erb

Co-authored-by: Alexander Brandon Coles <a.coles@openproject.com>

* Update lookbook/docs/patterns/accessibility/18-aria-live.md.erb

Co-authored-by: Alexander Brandon Coles <a.coles@openproject.com>

* Update lookbook/docs/patterns/accessibility/18-aria-live.md.erb

Co-authored-by: Alexander Brandon Coles <a.coles@openproject.com>

* change parameter in update_inputs_aria_live_message string

* change type to politeness

* Update lookbook/docs/patterns/accessibility/18-aria-live.md.erb

Co-authored-by: Alexander Brandon Coles <a.coles@openproject.com>

* set delay for polite updates

* use delay in relations tab update and date pickr update

* remove the usage of aria live region update message in relations tab, since we should handle update message here in another way

* use assistive technology instead of screen reader only

* change the stream action to live region

* change the aria action to live region

* remove alert role

* change the string in away that if there is no value for start date, finish date or duration, it shouldn't be part of the string

* remove aria-live from input text fields

* test for updated message in date pickr

* undo changes for relations updates

* check if message is null then return

* add more delay for updating data in date picker

* fix test for adding more delay for updating data in date picker

---------

Co-authored-by: Henriette Darge <h.darge@openproject.com>
Co-authored-by: Alexander Brandon Coles <a.coles@openproject.com>

Author: 3 people

app/components/concerns/op_turbo/streamable.rb

@@ -45,7 +45,7 @@ def wrapper_key
     end
 
     included do
-      def render_as_turbo_stream(view_context:, action: :update, method: nil)
+      def render_as_turbo_stream(view_context:, action: :update, method: nil, **attributes)
         case action
         when :update, *INLINE_ACTIONS
           @inner_html_only = true
@@ -73,7 +73,8 @@ def render_as_turbo_stream(view_context:, action: :update, method: nil)
           action:,
           method:,
           target: wrapper_key,
-          template:
+          template:,
+          **attributes
         ).render_in(view_context)
       end
 

app/components/work_packages/date_picker/date_form_component.rb

@@ -211,10 +211,7 @@ def default_field_options(name)
           data[:focus] = "true"
         end
 
-        {
-          data: data,
-          aria: { live: :polite, atomic: true }
-        }
+        { data: data }
       end
 
       def single_date_field_button_link(focused_field)

app/components/work_packages/date_picker/dialog_content_component.html.erb

@@ -1,5 +1,11 @@
 <%=
   content_tag("turbo-frame", id: "wp-datepicker-dialog--content") do
+%>
+  <live-region></live-region>
+  <% if @live_region_message %>
+    <%= render OpTurbo::StreamComponent.new(action: :liveRegion, message: @live_region_message, politeness: "polite", delay: "500", target: nil) %>
+  <% end %>
+  <%=
     component_wrapper(
       data: { "application-target": "dynamic",
               controller: "work-packages--date-picker--preview",
@@ -99,5 +105,5 @@
         end
       end
     end
-  end
-%>
+  %>
+<% end %>

app/components/work_packages/date_picker/dialog_content_component.rb

@@ -46,6 +46,7 @@ def initialize(work_package:,
                      focused_field: :start_date,
                      triggering_field: nil,
                      touched_field_map: {},
+                     live_region_message: "",
                      date_mode: nil)
         super
 
@@ -55,6 +56,7 @@ def initialize(work_package:,
         @triggering_field = triggering_field
         @touched_field_map = touched_field_map
         @date_mode = date_mode
+        @live_region_message = live_region_message
       end
 
       private

app/controllers/concerns/op_turbo/component_stream.rb

@@ -83,6 +83,12 @@ def render_error_flash_message_via_turbo_stream(**)
       render_flash_message_via_turbo_stream(**, scheme: :danger, icon: :stop)
     end
 
+    def render_live_region_update_message(message:, politeness: "polite", delay: nil)
+      turbo_streams << OpTurbo::StreamComponent
+        .new(action: :liveRegion, message:, politeness:, delay:, target: nil)
+        .render_in(view_context)
+    end
+
     def render_flash_message_via_turbo_stream(message:, component: OpPrimer::FlashComponent, **)
       instance = component.new(**).with_content(message)
       turbo_streams << instance.render_as_turbo_stream(view_context:, action: :flash)

app/controllers/work_packages/date_picker_controller.rb

@@ -157,7 +157,33 @@ def datepicker_modal_component
                                                          focused_field:,
                                                          triggering_field: params[:triggering_field],
                                                          touched_field_map:,
-                                                         date_mode:)
+                                                         date_mode:,
+                                                         live_region_message:)
+  end
+
+  def live_region_message
+    message_parts = [
+      "Scheduling mode: #{scheduling_label}",
+      working_days_label
+    ]
+
+    message_parts << "Start date: #{@work_package.start_date}" if @work_package.start_date.present?
+    message_parts << "Finish date: #{@work_package.due_date}" if @work_package.due_date.present?
+    message_parts << "Duration: #{@work_package.duration} days" if @work_package.duration.present?
+
+    I18n.t(
+      "work_packages.datepicker_modal.update_inputs_aria_live_message",
+      message: message_parts.join(", ")
+    )
+  end
+
+  def working_days_label
+    I18n.t("activerecord.attributes.work_package.include_non_working_days.#{@work_package.ignore_non_working_days}")
+  end
+
+  def scheduling_label
+    mode = @work_package.schedule_manually ? "manual" : "automatic"
+    I18n.t("work_packages.datepicker_modal.mode.#{mode}")
   end
 
   def focused_field

app/views/layouts/base.html.erb

@@ -59,6 +59,10 @@ See COPYRIGHT and LICENSE files for more details.
 </noscript>
 <opce-toasts-container></opce-toasts-container>
 <opce-modal-overlay></opce-modal-overlay>
+<live-region>
+  <div id="polite" aria-live="polite" aria-atomic="true" class="hidden-for-sighted"></div>
+  <div id="assertive" aria-live="assertive" aria-atomic="true" class="hidden-for-sighted"></div>
+</live-region>
 <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? %>

config/locales/en.yml

@@ -752,6 +752,7 @@ en:
         automatic: "Automatic"
         manual: "Manual"
       show_relations: "Show relations"
+      update_inputs_aria_live_message: "Date picker updated. %{message}"
       tabs:
         aria_label: "Datepicker tabs"
         children: "Children"

frontend/package-lock.json

@@ -105,6 +105,7 @@
     "@openproject/primer-view-components": "^0.66.2",
     "@openproject/reactivestates": "^3.0.1",
     "@primer/css": "^21.5.0",
+    "@primer/live-region-element": "^0.8.0",
     "@primer/primitives": "^9.1.2",
     "@primer/view-components": "npm:@openproject/primer-view-components@^0.66.2",
     "@types/hotwired__turbo": "^8.0.1",

frontend/package.json

@@ -353,7 +353,7 @@ export default class PreviewController extends DialogPreviewController {
     }
   }
 
-  // called from inputs defined in the date_picker/date_form.rb
+  // called from inputs defined in the date_picker/date_form_component.rb
   onHighlightField(e:Event) {
     const fieldToHighlight = e.target as HTMLInputElement;
     if (fieldToHighlight) {

frontend/src/stimulus/controllers/dynamic/work-packages/date-picker/preview.controller.ts

@@ -0,0 +1,21 @@
+import { StreamActions, StreamElement } from '@hotwired/turbo';
+import { announce } from '@primer/live-region-element';
+
+export function registerLiveRegionStreamAction() {
+  StreamActions.liveRegion = function liveRegionStreamAction(this:StreamElement) {
+    const message = this.getAttribute('message');
+    if (!message) return;
+    const politeness = this.getAttribute('politeness') || 'polite';
+    const delay = parseInt(this.getAttribute('delay') ?? '0', 10);
+    if (politeness === 'assertive') {
+      void announce(message, {
+        politeness: 'assertive',
+      });
+    } else {
+      void announce(message, {
+        politeness: 'polite',
+        delayMs: delay,
+      });
+    }
+  };
+}

frontend/src/turbo/live-region-stream-action.ts

@@ -4,6 +4,7 @@ import TurboPower from 'turbo_power';
 import { registerDialogStreamAction } from './dialog-stream-action';
 import { addTurboEventListeners } from './turbo-event-listeners';
 import { registerFlashStreamAction } from './flash-stream-action';
+import { registerLiveRegionStreamAction } from './live-region-stream-action';
 import { registerInputCaptionStreamAction } from './input-caption-stream-action';
 import { addTurboGlobalListeners } from './turbo-global-listeners';
 import { applyTurboNavigationPatch } from './turbo-navigation-patch';
@@ -30,6 +31,7 @@ addTurboEventListeners();
 addTurboGlobalListeners();
 registerDialogStreamAction();
 registerFlashStreamAction();
+registerLiveRegionStreamAction();
 registerInputCaptionStreamAction();
 
 // Apply navigational patch

frontend/src/turbo/setup.ts

@@ -0,0 +1,97 @@
+## What are ARIA Live Regions?
+ARIA Live Regions are a crucial accessibility feature that allow assistive technologies to announce dynamic content updates without requiring user focus changes.
+
+### ARIA Live Attributes
+ARIA Live Regions rely on specific attributes to control how updates are announced:
+- `aria-live="polite"`: Announces updates when the user is idle.
+- `aria-live="assertive"`: Announces updates immediately, interrupting the user.
+- `aria-atomic="true"`: Ensures the entire content of the region is read when it changes.
+
+## Implementing ARIA Live Regions in Primer
+The Primer project provides a custom element (Web Component) to ease working with ARIA Live Regions.
+We have decided to use a single global ARIA live region in `base.html` to ensure live regions are present in the DOM before updates occur. This approach is better than having multiple live regions because it ensures that announcements are delivered in a clear and consistent manner. By centralizing updates, we avoid potential conflicts between overlapping live regions and provide a more seamless experience for screen reader users.
+
+### Live Region in `base.html`
+```html
+<live-region>
+  <div id="polite" aria-live="polite" aria-atomic="true" class="hidden-for-sighted"></div>
+  <div id="assertive" aria-live="assertive" aria-atomic="true" class="hidden-for-sighted"></div>
+</live-region>
+```
+
+The `@primer/live-region-element` package provides methods to trigger announcements programmatically:
+
+```ts
+import { announce } from '@primer/live-region-element';
+
+announce('Example polite message', { politeness: 'polite' });
+```
+
+### Using Turbo Streams to Trigger ARIA Live Updates
+To use it in a Rails Turbo response, and send updates to the assistive technology after any action, we created a new Turbo stream component that triggers an liveRegion action:
+
+```ruby
+OpTurbo::StreamComponent.new(action: :liveRegion, message: "Form submission successful!", politeness: "polite", role: "status", target: nil)
+```
+
+- This creates a **Turbo Stream update** with:
+  - `action: :liveRegion` → Calls the `liveRegion` action defined in `live-region-stream-action.ts`
+  - `message: "Form submission successful!"` → The text to be announced to user
+  - `politeness: "polite"` → Ensures the message is read when the user is idle
+  - `target: nil` → Ensures the update isn't inserted into the DOM but is handled as an announcement
+
+### How to Trigger an ARIA Update from the Controller
+You can trigger a assistive technology announcement from your Rails controller by calling the provided `render_live_region_update_message` helper:
+
+```ruby
+render_live_region_update_message(
+  message: "A relation is added",
+  politeness: "polite"
+)
+```
+
+This helper internally renders a Turbo Stream using the liveRegion action to announce the message via ARIA live regions.
+For reference only — you do not need to define this yourself.
+Here is the internal implementation of `render_live_region_update_message`:
+
+```ruby
+    def render_live_region_update_message(message:, politeness:)
+      turbo_streams << OpTurbo::StreamComponent.new(action: :liveRegion, message:, politeness:, target: nil).render_in(view_context)
+    end
+```
+
+### How to Trigger an ARIA Update from a Turbo Frame
+If you're using a Turbo Frame and want to announce dynamic content changes to assistive technologies, you can embed a Turbo Stream using the `liveRegion` action directly inside the frame.
+
+```erb
+<%= content_tag("turbo-frame", id: "frame-id") do %>
+....
+  <%= render OpTurbo::StreamComponent.new(
+    action: :liveRegion,
+    message: "Update!!",
+    politeness: "polite",
+    target: nil
+  ) %>
+<% end %>
+
+```
+
+### How ARIA Live Messages Are Delivered via Turbo Streams
+The `registerLiveRegionStreamAction` method defines a custom Turbo Stream action called `liveRegion`. When triggered, it announces a message (using ARIA live regions) to assistive technologies, with a tone of either `"polite"` or `"assertive"`, depending on the `politeness` attribute in the stream element.
+
+```ts
+<%= render file: "frontend/src/turbo/live-region-stream-action.ts" %>
+```
+
+## Live Regions in Dialogs and Modals
+There is an important exception to our use of the global ARIA Live Region in `base.html`.
+
+When a modal or dialog is open, screen readers often restrict focus and reading context to the content inside the dialog. In this case, live regions outside the dialog (such as those defined in `base.html`) become inaccessible to the screen reader.
+
+To ensure that announcements are still read aloud in this situation, we should include a live-region component within the dialog itself, like what we have implemented for primerized date picker.
+
+```erb
+  <live-region>
+  </live-region>
+  <%= render OpTurbo::StreamComponent.new(action: :liveRegion, message: "Date picker is updated.", politeness: "polite", target: nil) %>
+```

lookbook/docs/patterns/accessibility/18-aria-live.md.erb

@@ -50,9 +50,9 @@
       let(:schedule_manually) { true }
 
       it "shows the date form" do
-        expect(dialog_content).to have_field(I18n.t("attributes.start_date"), aria: { live: :polite })
-        expect(dialog_content).to have_field(I18n.t("attributes.due_date"), aria: { live: :polite })
-        expect(dialog_content).to have_field(WorkPackage.human_attribute_name("duration"), aria: { live: :polite })
+        expect(dialog_content).to have_field(I18n.t("attributes.start_date"))
+        expect(dialog_content).to have_field(I18n.t("attributes.due_date"))
+        expect(dialog_content).to have_field(WorkPackage.human_attribute_name("duration"))
       end
 
       it "has an enabled save button" do