@ulu/frontend 0.0.3

package/trash/vue/ui/Modals/plugin.js

@@ -0,0 +1,215 @@
+// =============================================================================
+// Vue Modal Plugin
+// =============================================================================
+// 
+// Version:         1.0.2
+// 
+// Changes:         - 1.0.1 | Added rootComponent for access to app root,  
+//                            added ability to pass instance props
+//                  - 1.0.2 | Added clickOutsideCloses to Modal class (and component close condition)
+// 
+// Description:     Vue plugin that will add accessible modal features. Will only
+//                  support dialog modals (aria). Non-dialog modals will be handled
+//                  separately since they won't display as modals usually.
+// 
+// Details:         - Exposes global <modal> component
+//                  - Creates and mounts <modals> container component
+//                  - Uses a separate Vue instance for the container
+//                  - Can be configured to mount anywhere in DOM
+//                  - Has accessibility features to return focus
+//                  
+// Todo:            - Workout how multiple modals would work
+//                    - Challenge: There is only one component really
+//                    - Challenge: Will need to store info for previous modal
+//                    - Can we let the user manage this complexity?
+//                  - Maybe consider switching to use vue-portal
+//                    - https://portal-vue.linusb.org/guide/getting-started.html#multiple-portals-one-target
+//                    
+// Reference:
+//                  https://www.w3.org/TR/wai-aria-practices/examples/dialog-modal/dialog.html 
+//                  https://www.w3.org/TR/wai-aria-practices/#dialog_modal   
+//                  https://allyjs.io/tutorials/accessible-dialog.html
+//                    - In this article they mention don't bank on keydown changing the focus only  
+//                    - This article is the most accurate and complete             
+//                  https://snipcart.com/blog/vue-js-plugin  
+//                  
+// Issues:          - maintain.tabFocus is removing the focus wring in chrome (not sure why)
+//                    - Could have to do with how the browser doesn't add focus when the element 
+//                      is focused because of a click?
+//                                                  
+
+// External
+import maintain from 'ally.js/maintain/_maintain';
+import when from 'ally.js/when/_when';
+import query from 'ally.js/query/_query';
+
+// Internal
+import modalsComponent from "./components/Modals.vue";
+import modalComponent from "./components/Modal.vue";
+
+class Modals  {
+  constructor(options) {
+    // Pull out users array of modal configurations
+    // - we will pass them through the constructor below
+    // - No need for the original array
+    const modals = options.modals;
+    delete options.modals;
+
+    this.modals = {};
+    this.disabledHandler = null;
+    this.tabHandler = null;
+    this.escapeHandler = null;
+    this.rootInstance = null; // User can pass the context of their app this way
+    this.root = null;
+    Object.assign(this, options);
+    this.registerModals(modals);
+  }
+  /**
+   *   Passes user modal configuration through the Modal class 
+   *   and maps to an object/lookup table.
+   *   @param  {array} array array of modal configurations
+   */
+  registerModals(array) {
+    array.forEach((modal) => {
+      this.modals[modal.name] = new Modal(modal);
+    });
+  }
+  install(Vue, options) {
+
+    const instanceProperties = options.instanceProperties || {};
+    const self = this;
+
+    // Install the global modals component
+    Vue.component('modal', this.modalComponent);
+
+    // Create a new Vue instance to add reactivity to the
+    // data, which will allow the modal component to dynamically
+    // switch components when the user open() a modal.
+    // 
+    // User adds modal components to an object, each key is a different modal
+    // { ...options, component: vueComponent }
+    // similar to how you use the router
+    const root = new Vue({
+      // Allow the user to add instance properties (like store)
+      ...instanceProperties,
+      render: createElement => createElement(modalsComponent),
+      data: {
+        modals:     self.modals,
+        active:     null,
+        activeKey:  null,
+        rootInstance: null,
+        returnFocusTo: null
+      },
+      methods: {
+        /**
+         *   Opens a Modal
+         *   
+         *   @param  {string}     key             Key the modal was stored in "modals" object
+         *   @param  {object}     options         Object of options
+         *   - @key  {Element}    closeTo         The element that should be focused when the user exits the modal
+         *   - @key  {Function}   onOpenBefore    Callback before the modal is opened
+         *   - @key  {Function}   onOpenAfter     Callback when the modal is opened
+         *   - @key  {Function}   onCloseBefore   Callback before the modal is closed
+         *   - @key  {Function}   onCloseAfter    Callback when the modal is closed
+         *   @return {}                           Unused
+         */
+        open(key, { returnFocusTo }) {
+          this.activeKey = key;
+          this.active = this.modals[key];
+          this.returnFocusTo = returnFocusTo || null;
+        },
+        close() {
+          const { returnFocusTo, activeKey } = this;
+          if (self.disabledHandler) {
+            self.disabledHandler.disengage();
+          }
+          if (self.tabHandler) {
+            self.tabHandler.disengage();
+          }
+          if (self.escapeHandler) {
+            self.escapeHandler.disengage();
+          }
+          this.active = null;
+          this.activeKey = null;
+          switch (typeof returnFocusTo) {
+            case "string":
+              const element = document.querySelector(returnFocusTo);
+              if (element) {
+                element.focus();
+              }
+              break;
+            case "object":
+              if (returnFocusTo && returnFocusTo.focus) {
+                returnFocusTo.focus();
+              }
+              break;
+            case "function":
+              returnFocusTo(activeKey);
+              break;
+          }
+        }
+      }
+    });
+    // Then we mount the vue instance to the Document
+    // - Default we choose to add to end of body so that 
+    //   the modals are always the top layer
+    root.$mount(this.mountTo());
+    // Listen to the modal component to send an event when it's
+    // child has mounted > next tick (DOM ready)
+    root.$on("modal-mount", () => {
+      const context = root.$el;
+      // Handlers
+      this.disabledHandler = maintain.disabled({ filter: context });
+      // this.tabHandler = maintain.tabFocus({ context: context });
+      this.escapeHandler = when.key({ escape: root.close.bind(root) });
+      // Focus the First
+      let element = query.firstTabbable({
+        context: context,
+        defaultToContext: true,
+      });
+      // Check if there was a focusable element (if not use the labeledBy Element)
+      if (!element) {
+        element = context.querySelector('#' + root.active.labeledBy);
+        // Make it focusable
+        if (element && !element.hasAttribute('tabindex')) {
+          element.setAttribute('tabindex', '-1');
+        }
+      }
+      if (element) {
+        element.focus();
+      }
+    });
+    // Add a global property to all Vue Instances so they can interact with the 
+    // modal root instance for things like open and close.
+    Vue.prototype.$modals = this.root = root;
+  }
+  /**
+   *   Change where the modals container is mounted in the document
+   *   - User can define their own element in DOM to mount to returned to vm.$mount()
+   *   @return {element} Return native DOM element
+   */
+  mountTo() {
+    return document.body.appendChild(document.createElement('div'));
+  }
+  /**
+   *   Allows the user to assign their app component to a property accessible in the modal components
+   */
+  setRootInstance(rootInstance) {
+    this.root.rootInstance = rootInstance;
+  }
+}
+// Defaults (on prototype)
+Modals.prototype.modalComponent = modalComponent; // User can replace the modal template/component
+
+
+class Modal {
+  constructor(config) {
+    Object.assign(this, config);
+  }
+}
+
+// Defaults
+Modal.prototype.labeledBy = "modal__label";
+Modal.prototype.clickOutsideCloses = true;
+
+export default Modals;

package/trash/vue/ui/Modals/readme.note

@@ -0,0 +1,10 @@
+Plan:
+	- Setup like vue-router components
+	- modal container will show currentModal
+	- Like the router shows a component based on URL
+	- All modals will be setup using Vue.component()
+	- The names will be registered and displayed with modals.open(modalName)
+
+
+Packages Required:
+	"ally.js": "^1.4.1",

package/trash/vue/ui/Modals/reference/example-usage.vue

@@ -0,0 +1,27 @@
+<template>
+  <div>
+    <button @click="openModalTest">Open a modal</button>
+    <button @click="openModalTest2">Open a modal 2</button>
+  </div>
+</template>
+
+<script>
+  export default {
+    name: 'example',
+    methods: {
+      openModalTest(e) {
+        this.$modals.open('backup', {
+          returnFocusTo: e.target
+        });
+      },
+      openModalTest2(e) {
+        this.$modals.open('preferences', {
+          returnFocusTo: e.target
+        });
+      }
+    }
+  }
+</script>
+
+<style lang="scss">
+</style>

package/trash/vue/ui/Modals/reference/wcag-example/dialog.js

@@ -0,0 +1,324 @@
+/*
+*   This content is licensed according to the W3C Software License at
+*   https://www.w3.org/Consortium/Legal/2015/copyright-software-and-document
+*/
+
+var aria = aria || {};
+
+aria.Utils = aria.Utils || {};
+
+(function () {
+  /*
+   * When util functions move focus around, set this true so the focus listener
+   * can ignore the events.
+   */
+  aria.Utils.IgnoreUtilFocusChanges = false;
+
+  aria.Utils.dialogOpenClass = 'has-dialog';
+
+  /**
+   * @desc Set focus on descendant nodes until the first focusable element is
+   *       found.
+   * @param element
+   *          DOM node for which to find the first focusable descendant.
+   * @returns
+   *  true if a focusable element is found and focus is set.
+   */
+  aria.Utils.focusFirstDescendant = function (element) {
+    for (var i = 0; i < element.childNodes.length; i++) {
+      var child = element.childNodes[i];
+      if (aria.Utils.attemptFocus(child) ||
+          aria.Utils.focusFirstDescendant(child)) {
+        return true;
+      }
+    }
+    return false;
+  }; // end focusFirstDescendant
+
+  /**
+   * @desc Find the last descendant node that is focusable.
+   * @param element
+   *          DOM node for which to find the last focusable descendant.
+   * @returns
+   *  true if a focusable element is found and focus is set.
+   */
+  aria.Utils.focusLastDescendant = function (element) {
+    for (var i = element.childNodes.length - 1; i >= 0; i--) {
+      var child = element.childNodes[i];
+      if (aria.Utils.attemptFocus(child) ||
+          aria.Utils.focusLastDescendant(child)) {
+        return true;
+      }
+    }
+    return false;
+  }; // end focusLastDescendant
+
+  /**
+   * @desc Set Attempt to set focus on the current node.
+   * @param element
+   *          The node to attempt to focus on.
+   * @returns
+   *  true if element is focused.
+   */
+  aria.Utils.attemptFocus = function (element) {
+    if (!aria.Utils.isFocusable(element)) {
+      return false;
+    }
+
+    aria.Utils.IgnoreUtilFocusChanges = true;
+    try {
+      element.focus();
+    }
+    catch (e) {
+    }
+    aria.Utils.IgnoreUtilFocusChanges = false;
+    return (document.activeElement === element);
+  }; // end attemptFocus
+
+  /* Modals can open modals. Keep track of them with this array. */
+  aria.OpenDialogList = aria.OpenDialogList || new Array(0);
+
+  /**
+   * @returns the last opened dialog (the current dialog)
+   */
+  aria.getCurrentDialog = function () {
+    if (aria.OpenDialogList && aria.OpenDialogList.length) {
+      return aria.OpenDialogList[aria.OpenDialogList.length - 1];
+    }
+  };
+
+  aria.closeCurrentDialog = function () {
+    var currentDialog = aria.getCurrentDialog();
+    if (currentDialog) {
+      currentDialog.close();
+      return true;
+    }
+
+    return false;
+  };
+
+  aria.handleEscape = function (event) {
+    var key = event.which || event.keyCode;
+
+    if (key === aria.KeyCode.ESC && aria.closeCurrentDialog()) {
+      event.stopPropagation();
+    }
+  };
+
+  document.addEventListener('keyup', aria.handleEscape);
+
+  /**
+   * @constructor
+   * @desc Dialog object providing modal focus management.
+   *
+   * Assumptions: The element serving as the dialog container is present in the
+   * DOM and hidden. The dialog container has role='dialog'.
+   *
+   * @param dialogId
+   *          The ID of the element serving as the dialog container.
+   * @param focusAfterClosed
+   *          Either the DOM node or the ID of the DOM node to focus when the
+   *          dialog closes.
+   * @param focusFirst
+   *          Optional parameter containing either the DOM node or the ID of the
+   *          DOM node to focus when the dialog opens. If not specified, the
+   *          first focusable element in the dialog will receive focus.
+   */
+  aria.Dialog = function (dialogId, focusAfterClosed, focusFirst) {
+    this.dialogNode = document.getElementById(dialogId);
+    if (this.dialogNode === null) {
+      throw new Error('No element found with id="' + dialogId + '".');
+    }
+
+    var validRoles = ['dialog', 'alertdialog'];
+    var isDialog = (this.dialogNode.getAttribute('role') || '')
+      .trim()
+      .split(/\s+/g)
+      .some(function (token) {
+        return validRoles.some(function (role) {
+          return token === role;
+        });
+      });
+    if (!isDialog) {
+      throw new Error(
+        'Dialog() requires a DOM element with ARIA role of dialog or alertdialog.');
+    }
+
+    // Wrap in an individual backdrop element if one doesn't exist
+    // Native <dialog> elements use the ::backdrop pseudo-element, which
+    // works similarly.
+    var backdropClass = 'dialog-backdrop';
+    if (this.dialogNode.parentNode.classList.contains(backdropClass)) {
+      this.backdropNode = this.dialogNode.parentNode;
+    }
+    else {
+      this.backdropNode = document.createElement('div');
+      this.backdropNode.className = backdropClass;
+      this.dialogNode.parentNode.insertBefore(this.backdropNode, this.dialogNode);
+      this.backdropNode.appendChild(this.dialogNode);
+    }
+    this.backdropNode.classList.add('active');
+
+    // Disable scroll on the body element
+    document.body.classList.add(aria.Utils.dialogOpenClass);
+
+    if (typeof focusAfterClosed === 'string') {
+      this.focusAfterClosed = document.getElementById(focusAfterClosed);
+    }
+    else if (typeof focusAfterClosed === 'object') {
+      this.focusAfterClosed = focusAfterClosed;
+    }
+    else {
+      throw new Error(
+        'the focusAfterClosed parameter is required for the aria.Dialog constructor.');
+    }
+
+    if (typeof focusFirst === 'string') {
+      this.focusFirst = document.getElementById(focusFirst);
+    }
+    else if (typeof focusFirst === 'object') {
+      this.focusFirst = focusFirst;
+    }
+    else {
+      this.focusFirst = null;
+    }
+
+    // Bracket the dialog node with two invisible, focusable nodes.
+    // While this dialog is open, we use these to make sure that focus never
+    // leaves the document even if dialogNode is the first or last node.
+    var preDiv = document.createElement('div');
+    this.preNode = this.dialogNode.parentNode.insertBefore(preDiv,
+      this.dialogNode);
+    this.preNode.tabIndex = 0;
+    var postDiv = document.createElement('div');
+    this.postNode = this.dialogNode.parentNode.insertBefore(postDiv,
+      this.dialogNode.nextSibling);
+    this.postNode.tabIndex = 0;
+
+    // If this modal is opening on top of one that is already open,
+    // get rid of the document focus listener of the open dialog.
+    if (aria.OpenDialogList.length > 0) {
+      aria.getCurrentDialog().removeListeners();
+    }
+
+    this.addListeners();
+    aria.OpenDialogList.push(this);
+    this.clearDialog();
+    this.dialogNode.className = 'default_dialog'; // make visible
+
+    if (this.focusFirst) {
+      this.focusFirst.focus();
+    }
+    else {
+      aria.Utils.focusFirstDescendant(this.dialogNode);
+    }
+
+    this.lastFocus = document.activeElement;
+  }; // end Dialog constructor
+
+  aria.Dialog.prototype.clearDialog = function () {
+    Array.prototype.map.call(
+      this.dialogNode.querySelectorAll('input'),
+      function (input) {
+        input.value = '';
+      }
+    );
+  };
+
+  /**
+   * @desc
+   *  Hides the current top dialog,
+   *  removes listeners of the top dialog,
+   *  restore listeners of a parent dialog if one was open under the one that just closed,
+   *  and sets focus on the element specified for focusAfterClosed.
+   */
+  aria.Dialog.prototype.close = function () {
+    aria.OpenDialogList.pop();
+    this.removeListeners();
+    aria.Utils.remove(this.preNode);
+    aria.Utils.remove(this.postNode);
+    this.dialogNode.className = 'hidden';
+    this.backdropNode.classList.remove('active');
+    this.focusAfterClosed.focus();
+
+    // If a dialog was open underneath this one, restore its listeners.
+    if (aria.OpenDialogList.length > 0) {
+      aria.getCurrentDialog().addListeners();
+    }
+    else {
+      document.body.classList.remove(aria.Utils.dialogOpenClass);
+    }
+  }; // end close
+
+  /**
+   * @desc
+   *  Hides the current dialog and replaces it with another.
+   *
+   * @param newDialogId
+   *  ID of the dialog that will replace the currently open top dialog.
+   * @param newFocusAfterClosed
+   *  Optional ID or DOM node specifying where to place focus when the new dialog closes.
+   *  If not specified, focus will be placed on the element specified by the dialog being replaced.
+   * @param newFocusFirst
+   *  Optional ID or DOM node specifying where to place focus in the new dialog when it opens.
+   *  If not specified, the first focusable element will receive focus.
+   */
+  aria.Dialog.prototype.replace = function (newDialogId, newFocusAfterClosed,
+    newFocusFirst) {
+    var closedDialog = aria.getCurrentDialog();
+    aria.OpenDialogList.pop();
+    this.removeListeners();
+    aria.Utils.remove(this.preNode);
+    aria.Utils.remove(this.postNode);
+    this.dialogNode.className = 'hidden';
+    this.backdropNode.classList.remove('active');
+
+    var focusAfterClosed = newFocusAfterClosed || this.focusAfterClosed;
+    var dialog = new aria.Dialog(newDialogId, focusAfterClosed, newFocusFirst);
+  }; // end replace
+
+  aria.Dialog.prototype.addListeners = function () {
+    document.addEventListener('focus', this.trapFocus, true);
+  }; // end addListeners
+
+  aria.Dialog.prototype.removeListeners = function () {
+    document.removeEventListener('focus', this.trapFocus, true);
+  }; // end removeListeners
+
+  aria.Dialog.prototype.trapFocus = function (event) {
+    if (aria.Utils.IgnoreUtilFocusChanges) {
+      return;
+    }
+    var currentDialog = aria.getCurrentDialog();
+    if (currentDialog.dialogNode.contains(event.target)) {
+      currentDialog.lastFocus = event.target;
+    }
+    else {
+      aria.Utils.focusFirstDescendant(currentDialog.dialogNode);
+      if (currentDialog.lastFocus == document.activeElement) {
+        aria.Utils.focusLastDescendant(currentDialog.dialogNode);
+      }
+      currentDialog.lastFocus = document.activeElement;
+    }
+  }; // end trapFocus
+
+  window.openDialog = function (dialogId, focusAfterClosed, focusFirst) {
+    var dialog = new aria.Dialog(dialogId, focusAfterClosed, focusFirst);
+  };
+
+  window.closeDialog = function (closeButton) {
+    var topDialog = aria.getCurrentDialog();
+    if (topDialog.dialogNode.contains(closeButton)) {
+      topDialog.close();
+    }
+  }; // end closeDialog
+
+  window.replaceDialog = function (newDialogId, newFocusAfterClosed,
+    newFocusFirst) {
+    var topDialog = aria.getCurrentDialog();
+    if (topDialog.dialogNode.contains(document.activeElement)) {
+      topDialog.replace(newDialogId, newFocusAfterClosed, newFocusFirst);
+    }
+  }; // end replaceDialog
+
+}());