From 83a44ba924fb20065f0bb62fc2a09a7aaec391bc Mon Sep 17 00:00:00 2001
From: Andreas Awouters <andreas.awouters@atmire.com>
Date: Mon, 16 Sep 2024 15:46:07 +0200
Subject: [PATCH] 118220: Add live-region service and component

---
 config/config.example.yml                     |  16 ++-
 .../live-region/live-region.component.html    |   3 +
 .../live-region/live-region.component.scss    |  13 ++
 .../live-region/live-region.component.ts      |  25 ++++
 .../shared/live-region/live-region.config.ts  |   9 ++
 .../shared/live-region/live-region.service.ts | 118 ++++++++++++++++++
 src/app/shared/shared.module.ts               |   4 +-
 src/config/app-config.interface.ts            |   2 +
 src/config/default-app-config.ts              |   7 ++
 src/environments/environment.test.ts          |   7 +-
 src/styles/_custom_variables.scss             |   1 +
 11 files changed, 202 insertions(+), 3 deletions(-)
 create mode 100644 src/app/shared/live-region/live-region.component.html
 create mode 100644 src/app/shared/live-region/live-region.component.scss
 create mode 100644 src/app/shared/live-region/live-region.component.ts
 create mode 100644 src/app/shared/live-region/live-region.config.ts
 create mode 100644 src/app/shared/live-region/live-region.service.ts

diff --git a/config/config.example.yml b/config/config.example.yml
index ea38303fa3..58eb6ff33d 100644
--- a/config/config.example.yml
+++ b/config/config.example.yml
@@ -379,4 +379,18 @@ vocabularies:
 # Default collection/community sorting order at Advanced search, Create/update community and collection when there are not a query. 
 comcolSelectionSort:
   sortField: 'dc.title'
-  sortDirection: 'ASC'
\ No newline at end of file
+  sortDirection: 'ASC'
+
+# Live Region configuration
+# Live Region as defined by w3c, https://www.w3.org/TR/wai-aria-1.1/#terms:
+# Live regions are perceivable regions of a web page that are typically updated as a
+# result of an external event when user focus may be elsewhere.
+#
+# The DSpace live region is a component present at the bottom of all pages that is invisible by default, but is useful
+# for screen readers. Any message pushed to the live region will be announced by the screen reader. These messages
+# usually contain information about changes on the page that might not be in focus.
+liveRegion:
+  # The duration after which messages disappear from the live region in milliseconds
+  messageTimeOutDurationMs: 30000
+  # The visibility of the live region. Setting this to true is only useful for debugging purposes.
+  isVisible: false
diff --git a/src/app/shared/live-region/live-region.component.html b/src/app/shared/live-region/live-region.component.html
new file mode 100644
index 0000000000..a48f3ad52e
--- /dev/null
+++ b/src/app/shared/live-region/live-region.component.html
@@ -0,0 +1,3 @@
+<div class="live-region" [ngClass]="{'visually-hidden': !isVisible }" aria-live="assertive" role="log" aria-relevant="additions" aria-atomic="true">
+  <div class="live-region-message" *ngFor="let message of (messages$ | async)">{{ message }}</div>
+</div>
diff --git a/src/app/shared/live-region/live-region.component.scss b/src/app/shared/live-region/live-region.component.scss
new file mode 100644
index 0000000000..69844a93e1
--- /dev/null
+++ b/src/app/shared/live-region/live-region.component.scss
@@ -0,0 +1,13 @@
+.live-region {
+  position: fixed;
+  bottom: 0;
+  left: 0;
+  right: 0;
+  padding-left: 60px;
+  height: 90px;
+  line-height: 18px;
+  color: var(--bs-white);
+  background-color: var(--bs-dark);
+  opacity: 0.94;
+  z-index: var(--ds-live-region-z-index);
+}
diff --git a/src/app/shared/live-region/live-region.component.ts b/src/app/shared/live-region/live-region.component.ts
new file mode 100644
index 0000000000..d7bd5eb806
--- /dev/null
+++ b/src/app/shared/live-region/live-region.component.ts
@@ -0,0 +1,25 @@
+import { Component, OnInit } from '@angular/core';
+import { LiveRegionService } from './live-region.service';
+import { Observable } from 'rxjs';
+
+@Component({
+  selector: `ds-live-region`,
+  templateUrl: './live-region.component.html',
+  styleUrls: ['./live-region.component.scss'],
+})
+export class LiveRegionComponent implements OnInit {
+
+  protected isVisible: boolean;
+
+  protected messages$: Observable<string[]>;
+
+  constructor(
+    protected liveRegionService: LiveRegionService,
+  ) {
+  }
+
+  ngOnInit() {
+    this.isVisible = this.liveRegionService.getLiveRegionVisibility();
+    this.messages$ = this.liveRegionService.getMessages$();
+  }
+}
diff --git a/src/app/shared/live-region/live-region.config.ts b/src/app/shared/live-region/live-region.config.ts
new file mode 100644
index 0000000000..e545bfd254
--- /dev/null
+++ b/src/app/shared/live-region/live-region.config.ts
@@ -0,0 +1,9 @@
+import { Config } from '../../../config/config.interface';
+
+/**
+ * Configuration interface used by the LiveRegionService
+ */
+export class LiveRegionConfig implements Config {
+  messageTimeOutDurationMs: number;
+  isVisible: boolean;
+}
diff --git a/src/app/shared/live-region/live-region.service.ts b/src/app/shared/live-region/live-region.service.ts
new file mode 100644
index 0000000000..482d1ca1bb
--- /dev/null
+++ b/src/app/shared/live-region/live-region.service.ts
@@ -0,0 +1,118 @@
+import { Injectable } from '@angular/core';
+import { BehaviorSubject } from 'rxjs';
+import { environment } from '../../../environments/environment';
+
+@Injectable({
+  providedIn: 'root',
+})
+export class LiveRegionService {
+
+  /**
+   * The duration after which the messages disappear in milliseconds
+   * @protected
+   */
+  protected messageTimeOutDurationMs: number = environment.liveRegion.messageTimeOutDurationMs;
+
+  /**
+   * Array containing the messages that should be shown in the live region
+   * @protected
+   */
+  protected messages: string[] = [];
+
+  /**
+   * BehaviorSubject emitting the array with messages every time the array updates
+   * @protected
+   */
+  protected messages$: BehaviorSubject<string[]> = new BehaviorSubject([]);
+
+  /**
+   * Whether the live region should be visible
+   * @protected
+   */
+  protected liveRegionIsVisible: boolean = environment.liveRegion.isVisible;
+
+  /**
+   * Returns a copy of the array with the current live region messages
+   */
+  getMessages() {
+    return [...this.messages];
+  }
+
+  /**
+   * Returns the BehaviorSubject emitting the array with messages every time the array updates
+   */
+  getMessages$() {
+    return this.messages$;
+  }
+
+  /**
+   * Adds a message to the live-region messages array
+   * @param message
+   */
+  addMessage(message: string) {
+    this.messages.push(message);
+    this.emitCurrentMessages();
+
+    // Clear the message once the timeOut has passed
+    setTimeout(() => this.pop(), this.messageTimeOutDurationMs);
+  }
+
+  /**
+   * Clears the live-region messages array
+   */
+  clear() {
+    this.messages = [];
+    this.emitCurrentMessages();
+  }
+
+  /**
+   * Removes the longest living message from the array.
+   * @protected
+   */
+  protected pop() {
+    if (this.messages.length > 0) {
+      this.messages.shift();
+      this.emitCurrentMessages();
+    }
+  }
+
+  /**
+   * Makes the messages$ BehaviorSubject emit the current messages array
+   * @protected
+   */
+  protected emitCurrentMessages() {
+    this.messages$.next(this.getMessages());
+  }
+
+  /**
+   * Returns a boolean specifying whether the live region should be visible.
+   * Returns 'true' if the region should be visible and false otherwise.
+   */
+  getLiveRegionVisibility(): boolean {
+    return this.liveRegionIsVisible;
+  }
+
+  /**
+   * Sets the visibility of the live region.
+   * Setting this to true will make the live region visible which is useful for debugging purposes.
+   * @param isVisible
+   */
+  setLiveRegionVisibility(isVisible: boolean) {
+    this.liveRegionIsVisible = isVisible;
+  }
+
+  /**
+   * Gets the current message timeOut duration in milliseconds
+   */
+  getMessageTimeOutMs(): number {
+    return this.messageTimeOutDurationMs;
+  }
+
+  /**
+   * Sets the message timeOut duration
+   * @param timeOutMs the message timeOut duration in milliseconds
+   */
+  setMessageTimeOutMs(timeOutMs: number) {
+    this.messageTimeOutDurationMs = timeOutMs;
+  }
+}
diff --git a/src/app/shared/shared.module.ts b/src/app/shared/shared.module.ts
index 0f7871f7f9..db5b778722 100644
--- a/src/app/shared/shared.module.ts
+++ b/src/app/shared/shared.module.ts
@@ -284,6 +284,7 @@ import {
 } from '../item-page/simple/field-components/specific-field/title/themed-item-page-field.component';
 import { BitstreamListItemComponent } from './object-list/bitstream-list-item/bitstream-list-item.component';
 import { NgxPaginationModule } from 'ngx-pagination';
+import { LiveRegionComponent } from './live-region/live-region.component';
 
 const MODULES = [
   CommonModule,
@@ -465,7 +466,8 @@ const ENTRY_COMPONENTS = [
   AdvancedClaimedTaskActionRatingComponent,
   EpersonGroupListComponent,
   EpersonSearchBoxComponent,
-  GroupSearchBoxComponent
+  GroupSearchBoxComponent,
+  LiveRegionComponent,
 ];
 
 const PROVIDERS = [
diff --git a/src/config/app-config.interface.ts b/src/config/app-config.interface.ts
index 84a30549a7..aa3033ecec 100644
--- a/src/config/app-config.interface.ts
+++ b/src/config/app-config.interface.ts
@@ -22,6 +22,7 @@ import { HomeConfig } from './homepage-config.interface';
 import { MarkdownConfig } from './markdown-config.interface';
 import { FilterVocabularyConfig } from './filter-vocabulary-config';
 import { DiscoverySortConfig } from './discovery-sort.config';
+import { LiveRegionConfig } from '../app/shared/live-region/live-region.config';
 
 interface AppConfig extends Config {
   ui: UIServerConfig;
@@ -48,6 +49,7 @@ interface AppConfig extends Config {
   markdown: MarkdownConfig;
   vocabularies: FilterVocabularyConfig[];
   comcolSelectionSort: DiscoverySortConfig;
+  liveRegion: LiveRegionConfig;
 }
 
 /**
diff --git a/src/config/default-app-config.ts b/src/config/default-app-config.ts
index a6e9e092e4..1c0f88cf47 100644
--- a/src/config/default-app-config.ts
+++ b/src/config/default-app-config.ts
@@ -22,6 +22,7 @@ import { HomeConfig } from './homepage-config.interface';
 import { MarkdownConfig } from './markdown-config.interface';
 import { FilterVocabularyConfig } from './filter-vocabulary-config';
 import { DiscoverySortConfig } from './discovery-sort.config';
+import { LiveRegionConfig } from '../app/shared/live-region/live-region.config';
 
 export class DefaultAppConfig implements AppConfig {
   production = false;
@@ -432,4 +433,10 @@ export class DefaultAppConfig implements AppConfig {
     sortField:'dc.title',
     sortDirection:'ASC',
   };
+
+  // Live Region configuration, used by the LiveRegionService
+  liveRegion: LiveRegionConfig = {
+    messageTimeOutDurationMs: 30000,
+    isVisible: false,
+  };
 }
diff --git a/src/environments/environment.test.ts b/src/environments/environment.test.ts
index cb9d2c7130..498799a454 100644
--- a/src/environments/environment.test.ts
+++ b/src/environments/environment.test.ts
@@ -313,5 +313,10 @@ export const environment: BuildConfig = {
       vocabulary: 'srsc',
       enabled: true
     }
-  ]
+  ],
+
+  liveRegion: {
+    messageTimeOutDurationMs: 30000,
+    isVisible: false,
+  },
 };
diff --git a/src/styles/_custom_variables.scss b/src/styles/_custom_variables.scss
index ddf490c7a7..09267d15ae 100644
--- a/src/styles/_custom_variables.scss
+++ b/src/styles/_custom_variables.scss
@@ -13,6 +13,7 @@
   --ds-login-logo-width:72px;
   --ds-submission-header-z-index: 1001;
   --ds-submission-footer-z-index: 999;
+  --ds-live-region-z-index: 1030;
 
   --ds-main-z-index: 1;
   --ds-nav-z-index: 10;