lib/amd/src/local/reactive/srlogger.js

  1. // This file is part of Moodle - http://moodle.org/
  2. //
  3. // Moodle is free software: you can redistribute it and/or modify
  4. // it under the terms of the GNU General Public License as published by
  5. // the Free Software Foundation, either version 3 of the License, or
  6. // (at your option) any later version.
  7. //
  8. // Moodle is distributed in the hope that it will be useful,
  9. // but WITHOUT ANY WARRANTY; without even the implied warranty of
  10. // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  11. // GNU General Public License for more details.
  12. //
  13. // You should have received a copy of the GNU General Public License
  14. // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
  16. /**
  17.  * Screen reader-only (sr-only) reactive mutations logger class.
  18.  *
  19.  * This logger can be used by the StateManager to log mutation feedbacks and actions.
  20.  * The feedback messages logged by this logger will be rendered in a sr-only, ARIA live region.
  21.  *
  22.  * @module     core/local/reactive/srlogger
  23.  * @class      SRLogger
  24.  * @copyright  2023 Jun Pataleta <jun@moodle.com>
  25.  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  26.  */
  28. import Logger from 'core/local/reactive/logger';
  30. /**
  31.  * Logger entry structure.
  32.  *
  33.  * @typedef {object} LoggerEntry
  34.  * @property {string} feedbackMessage Feedback message.
  35.  */
  37. /**
  38.  * Screen reader-only (sr-only) reactive mutations logger class.
  39.  *
  40.  * @class SRLogger
  41.  */
  42. export default class SRLogger extends Logger {
  43.     /**
  44.      * The element ID of the ARIA live region where the logger feedback will be rendered.
  45.      *
  46.      * @type {string}
  47.      */
  48.     static liveRegionId = 'sr-logger-feedback-container';
  50.     /**
  51.      * Add a log entry.
  52.      * @param {LoggerEntry} entry Log entry.
  53.      */
  54.     add(entry) {
  55.         if (entry.feedbackMessage) {
  56.             // Fetch or create an ARIA live region that will serve as the container for the logger feedback.
  57.             let loggerFeedback = document.getElementById(SRLogger.liveRegionId);
  58.             if (!loggerFeedback) {
  59.                 loggerFeedback = document.createElement('div');
  60.                 loggerFeedback.id = SRLogger.liveRegionId;
  61.                 loggerFeedback.classList.add('sr-only');
  62.                 loggerFeedback.setAttribute('aria-live', 'polite');
  63.                 document.body.append(loggerFeedback);
  64.             }
  65.             // Set the ARIA live region's contents with the feedback.
  66.             loggerFeedback.innerHTML = entry.feedbackMessage;
  68.             // Clear the feedback message after 4 seconds to avoid the contents from being read out in case the user navigates
  69.             // to this region. This is similar to the default timeout of toast messages before disappearing from view.
  70.             setTimeout(() => {
  71.                 loggerFeedback.innerHTML = '';
  72.             }, 4000);
  73.         }
  74.     }
  75. }