@ulu/frontend 0.0.23 → 0.1.0-beta.1

package/js/ui/tooltip.js

@@ -1,85 +1,286 @@
 /**
  * @module ui/tooltip
  */
-// =============================================================================
-// Tooltip
-// =============================================================================
 
-// Version:         1.0.1
+import { getName as getEventName } from "../events/index.js";
+import { createFloatingUi } from "../utils/floating-ui.js";
+import { createElementFromHtml } from "@ulu/utils/browser/dom.js";
+import { logError } from "../utils/class-logger.js";
+import { getDatasetOptionalJson } from "../utils/dom.js";
+import { newId, ensureId } from "../utils/id.js";
 
-// Description:     Adds a single tooltip div to bottom of document to be used to 
-//                  show text/simple markup of mouse hover or focus
+const attrs = {
+  trigger: "data-ulu-tooltip",
+  init: "data-ulu-init",
+  body: "data-ulu-tooltip-display-body",
+  arrow: "data-ulu-tooltip-arrow"
+};
+const attrSelector = key => `[${ attrs[key] }]`;
+const attrSelectorInitial = key => `${ attrSelector(key) }:not([${ attrs.init }])`;
+/**
+ * Initialize default popover
+ */
+export function init() {
+  document.addEventListener(getEventName("pageModified"), setup);
+  setup();
+}
+
+/**
+ * Query all popovers on current page and set them up
+ * - Use this manually if needed
+ * - Won't setup a popover more than once
+ */
+export function setup() {
+  const triggers = document.querySelectorAll(attrSelectorInitial("trigger"));
+  triggers.forEach(setupTrigger);
+}
 
-import { logError } from "../utils/logger.js";
-import { createPopper } from '@popperjs/core';
+export function setupTrigger(trigger) {
+  const passed = getDatasetOptionalJson(trigger, "uluTooltip");
+  const options = typeof passed === "object" ? passed : {};
+  if (typeof passed === "string") {
+    options.content = passed;
+  }
+  return new Tooltip({ trigger }, options);
+}
 
-const ATTR_DESC = "aria-describedby";
-const popperOptions = {
-  placement: "auto",
-  strategy: 'fixed',
-  modifiers: [
-    { 
-      name: 'eventListeners', 
-      enabled: false 
+/**
+ * Tooltip
+ * - Provides basic tooltip functionality
+ * - Uses floating UI for positioning
+ */
+export class Tooltip {
+  /**
+   * Defaults options
+   */
+  static defaults = {
+    /**
+     * Should the tooltip and content be linked accessibly
+     * - Note tooltips can only apply to interactive elements! (ie button, input, role="...", etc)
+     * @type {Boolean}
+     */
+    accessible: true,
+    /**
+     * String/markup to insert into tooltip display
+     * @type {String}
+     */
+    content: null,
+    openClass: "is-active",
+    contentClass: "",
+    isHtml: false,
+    /**
+     * Pull content from pre-existing content on page 
+     * @type {String|Node}
+     */
+    fromElement: null,
+    /**
+     * If used on a link that is an anchor link it will display the content of the anchor like fromElement
+     */
+    fromAnchor: false,
+    /**
+     * Move the content to the bottom of the document
+     * @type {Boolean}
+     */
+    endOfDocument: true,
+    /**
+     * Events to show tooltip on
+     * @type {Array.<String>}
+     */    
+    showEvents: ["pointerenter", "focus"],
+    /**
+     * Events to hide tooltip on
+     * @type {Array.<String>}
+     */
+    hideEvents: ["pointerleave", "blur"],
+    /**
+     * Delay when using the directive
+     * @type {Number}
+     */
+    delay: 500,
+    /**
+     * Template for the content display
+     */
+    template(_config) {
+      return `
+        <div class="popover popover--tooltip">
+          <div class="popover__inner" ${ attrs.body }>
+          </div>
+          <span class="popover__arrow" data-ulu-tooltip-arrow></span>
+        </div>
+      `;
     },
-    {
-      name: 'preventOverflow',
-      enabled: true,
-      options: {
-        mainAxis: true
+    /**
+     * Callback when tooltip is shown or hidden
+     * @type {Function}
+     */
+    onChange(_ctx) {
+      // do something
+    }
+  };
+  static defaultFloatingOptions = {
+    // strategy: "fixed"
+  };
+  constructor(elements, userOptions, floatingOptions) {
+    const { trigger } = elements;
+    if (!trigger) {
+      logError(this, "missing required trigger");
+      return;
+    }
+    this.options = Object.assign({}, Tooltip.defaults, userOptions);
+    this.floatingOptions = Object.assign({}, Tooltip.defaultFloatingOptions, floatingOptions);
+    this.elements = { ...elements };
+    this.handlers = {};
+    this.isOpen = false;
+    ensureId(trigger);
+    this.setup();
+  }
+  setup() {
+    this.createContentElement();
+    this.attachHandlers();
+    this.setupAccessibility();
+  }
+  setupAccessibility() {
+    const { trigger, content } = this.elements;
+    const { accessible } = this.options;
+    if (!accessible) return;
+    trigger.setAttribute("aria-describedby", content.id);
+  }
+  destroy() {
+    this.destroyHandlers();
+    this.destroyDisplay();
+  }
+  getInnerContent() {
+    const { fromElement, content, isHtml, fromAnchor } = this.options;
+    if (content) {
+      return content;
+    } else if (fromElement || fromAnchor) {
+      const element = fromAnchor ? this.getAnchorElement() : document.querySelector(fromElement);
+      if (element) {
+        return isHtml ? element.innerHTML : element.innerText;
+      } else {
+        return "";
       }
-    },
-    // Arrow
-    {
-      name: 'offset',
-      options: {
-        offset: [ 0, 10 ],
-      },
+    } else {
+      logError(this, "Could not resolve inner content");
     }
-  ]
-};
-
-export default class Tooltip {
-  static defaults = {
-    namespace: "Tooltip",
-    describedBy: false,
-    arrowSize: 10,
-    classes: []
-  }
-  constructor(context, markup, config) {
-    if (!context) {
-      logError(this, 'Missing context element');
+  }
+  getAnchorElement() {
+    const { trigger } = this.elements;
+    const { href } = trigger;
+    const id = href ? href.split("#")[1] : null;
+    const element = id ? document.getElementById(id) : null;
+    if (!element) {
+      console.error("Unable to get 'fromAnchor' element", trigger);
     }
-    this.options = Object.assign({}, Tooltip.defaults, config);
-    this.context = context;
-    this.element = this.create(markup);
-    createPopper(context, this.element, popperOptions);
-  }
-  create(markup) {
-    const { namespace } = this.options;
-    const element = document.createElement("div");
-
-    element.id = namespace + "--" + Date.now();
-    element.innerHTML = markup;
-    element.classList.add(namespace);
-    element.classList.add(...this.options.classes);
-
-    const arrow = document.createElement("div");
-    arrow.setAttribute("data-popper-arrow", "");
+    return element;
+  }
+  createContentElement() {
+    const { options } = this;
+    const content = createElementFromHtml(options.template(options));
+    const body = content.querySelector(attrSelector("body"));
+    const innerContent = this.getInnerContent();
+    if (options.isHtml) {
+      body.innerHTML = innerContent;
+    } else {
+      body.textContent = innerContent;
+    }
+    content.id = newId();
+    if (options.contentClass) {
+      content.classList.add(options.contentClass);
+    }
+    
+    this.elements.content = content;
+    this.elements.contentArrow = content.querySelector(attrSelector("arrow"));
+    document.body.appendChild(content);
+  }
+  attachHandlers() {
+    const { trigger } = this.elements;
+    const { showEvents, hideEvents, delay } = this.options;
+    let tid = null;
+  
+    const onShow = (event) => { 
+      if (tid) return;
+      tid = setTimeout(() => {
+        this.show(event);
+        clearTimeout(tid);
+      }, delay);
+    };
 
-    if (this.options.describedBy) {
-      this.context.setAttribute(ATTR_DESC, element.id);
+    const onHide = (event) => { 
+      if (tid) {
+        clearTimeout(tid);
+        tid = null;
+      }
+      this.hide(event);
+    };
+    const onDocumentKeydown = (event) => {
+      if (event.key === "Escape") {
+        this.hide(event);
+      }
+    };
+    showEvents.forEach(name => {
+      trigger.addEventListener(name, onShow);
+    });
+    hideEvents.forEach(name => {
+      trigger.addEventListener(name, onHide);
+    });
+    document.addEventListener("keydown", onDocumentKeydown);
+    this.handlers = { onShow, onHide, onDocumentKeydown };
+  }
+  destroyHandlers() {
+    const { trigger } = this;
+    const { onShow, onHide, onDocumentKeydown } = this.handlers;
+    const { showEvents, hideEvents } = this.options;
+    if (onShow) {
+      showEvents.forEach(name => {
+        trigger.removeEventListener(name, onShow);
+      });
+    }
+    if (onHide) {
+      hideEvents.forEach(name => {
+        trigger.removeEventListener(name, onHide);
+      });
+    }
+    if (onDocumentKeydown) {
+      document.removeEventListener("keydown", onDocumentKeydown);
     }
-    this.inPage = true;
-    element.appendChild(arrow);
-    return document.body.appendChild(element);
   }
-  destroy() {
-    if (this.inPage) {
-      document.body.removeChild(this.element);
+  setState(isOpen, event) {
+    const ctx = { 
+      instance: this, 
+      isOpen, 
+      event 
+    };
+    const { trigger, content } = this.elements;
+    const { openClass } = this.options;
+    const setClass = el => el.classList[isOpen ? "add" : "remove"](openClass);
+    // trigger.setAttribute("aria-expanded", isOpen ? "true" : "false");
+    setClass(trigger);
+    setClass(content);
+    this.isOpen = isOpen;
+    this.options.onChange(ctx);
+    trigger.dispatchEvent(this.createEvent("change", ctx));
+    this.destroyFloatingInstance();
+    if (isOpen) {
+      this.createFloatingInstance();
     }
-    if (this.options.describedBy) {
-      this.context.removeAttribute(ATTR_DESC);
+  }
+  createEvent(name, detail) {
+    return new CustomEvent(getEventName("tooltip:" + name), { detail });
+  }
+  createFloatingInstance() {
+    this.floatingCleanup = createFloatingUi(this.elements, this.floatingOptions);
+  }
+  destroyFloatingInstance() {
+    if (this.floatingCleanup) {
+      this.floatingCleanup(); 
+      this.floatingCleanup = null;
     }
   }
+  show(event) {
+    this.setState(true, event);
+  }
+  hide(event) {
+    this.setState(false, event);
+  }
 }

package/js/utils/{logger.js → class-logger.js}

@@ -1,6 +1,7 @@
 /**
- * @module utils/logger
+ * @module utils/class-logger
  */
+
 // Goal: minimzing console conditions for nessasary production log statements
 
 /**
@@ -18,17 +19,17 @@ const hasConsole = "console" in window;
 // If no context output only if config (global) debug is enabled
 function allow(context) {
   return hasConsole && config.debug && (context?.debug || context == null);
-};
+}
 function getName(context) {
   return typeof context === "object" && context?.constructor?.name;
-};
+}
 function output(method, context, messages) {
   const label = getName(context) || "Logger";
   console[method](label, ...messages);
   if (config.outputContext) {
-    console.log('Context:\n', context);
+    console.log("Context:\n", context);
   }
-};
+}
 
 /**
  * Changes to make to configuration

package/js/utils/dom.js

@@ -0,0 +1,122 @@
+/**
+ * @module utils/dom
+ */
+
+
+export const regexJsonString = /^[{\[][\s\S]*[}\]]$/;
+
+/**
+ * Get an elements JSON dataset value
+ * @param {Node} element 
+ * @param {String} key key in dataset object for element
+ * @returns {Object} Empty object or JSON object from dataset
+ */
+export function getDatasetJson(element, key) {
+  const passed = element.dataset[key];
+  try {
+    return JSON.parse(passed);
+  } catch (error) {
+    console.error(`Error getting JSON from dataset (${ key }) -- "${ passed }"\n`, element, error);
+    return {};
+  }
+}
+
+/**
+ * Get an elements JSON dataset value that could potentially just be a single string
+ * - If JSON it will return the object else it will return the value directly
+ * @param {Node} element 
+ * @param {String} key key in dataset object for element
+ * @returns {Object|String} JSON object or current dataset value (string or empty string if no value)
+ */
+export function getDatasetOptionalJson(element, key) {
+  const passed = element.dataset[key];
+  if (passed && regexJsonString.test(passed.trim())) {
+    return getDatasetJson(element, key);
+  } else {
+    return passed;
+  }
+}
+
+/**
+ * Check if a pointer event x/y was outside an elements bounding box
+ */
+export function wasClickOutside(element, event) {
+  const rect = element.getBoundingClientRect();
+  return (event.clientY < rect.top || // above
+    event.clientY > rect.top + rect.height || // below
+    event.clientX < rect.left || // left side
+    event.clientX > rect.left + rect.width); // right side
+}
+
+
+/**
+ *   Sets up the positional classes that would come from the equal
+ *   height module. Needs to be rerun by user when layout changes
+ *   or new instances are added to the screen
+ *   - Used for gutter crops
+ *   - Used for rule placement
+ *   - **Devs** Remember that default classes should match sass defaults
+ *   @param {Node} parent  The grid parent <data-grid="">
+ *   @param {Object} classes Override the default equal heights classes
+ */
+export function setPositionClasses(parent, classes = { 
+  columnFirst: 'position-column-first', 
+  columnLast: 'position-column-last', 
+  rowFirst: 'position-row-first', 
+  rowLast: 'position-row-last' 
+}) {  
+  const children = [...parent.children];
+  const rows = [];
+  let lastY;
+  // Check element against last
+  // If they don't match it's a new row create a new array
+  // Then push into the last array in the rows array
+  children.forEach((child) => {
+    const y = child.getBoundingClientRect().y;
+    if (lastY !== y) rows.push([]);
+    rows[rows.length - 1].push(child);
+    lastY = y;
+    child.classList.remove(...Object.values(classes)); // Remove previously set classes
+  });
+  // Apply Classes
+  rows.forEach((row, index) => {
+    if (index === 0) 
+      row.forEach(child => child.classList.add(classes.rowFirst));
+    if (index == rows.length - 1) 
+      row.forEach(child => child.classList.add(classes.rowLast));
+
+    row.forEach((child, childIndex) => {
+      if (childIndex === 0) 
+        child.classList.add(classes.columnFirst);
+      if (childIndex == row.length - 1) 
+        child.classList.add(classes.columnLast);
+    });
+  });
+}
+
+/**
+ * Resolve a target to Element
+ * @param {String|Node} target The selector or node/element
+ * @param {Object} context [document] The context to query possible selectors from
+ */
+export function getElement(target, context = document) {
+  if (typeof target === "string") {
+    return context.querySelector(target);
+  } else if (target instanceof Element) {
+    return target;
+  } else {
+    console.warn("Unable to getElement()", target);
+    return null;
+  }
+} 
+
+/**
+ * Sets a CSS custom property equal to the scrollbar width
+ * @param {Node} element The element that is the child of a scrollabel container
+ * @param {Node} container The container that can be scrolled
+ * @param {Stirng} propName Custom property to set
+ */
+export function addScrollbarProperty(element = document.body, container = window, propName = "--ulu-scrollbar-width") {
+  const scrollbarWidth = container.innerWidth - element.clientWidth;
+  element.style.setProperty(propName, `${ scrollbarWidth }px`);
+}

package/js/utils/file-save.js

@@ -0,0 +1,67 @@
+/**
+ * @module utils/file-save
+ */
+
+/**
+ * Options
+ * @typedef {Object} FileSaveOptions
+ * @property {String} filename Filename for blob when creating a link (ie createLink) [default "filesave-file.txt"]
+ * @property {String} type Filename for blob when creating a link (ie createLink) [default "text/plain;charset=utf-8"]
+ */
+  
+
+/**
+ * Simple script that is useful for testing
+ * - Make a file 
+ * - Create a URL to it
+ * - Gives utility function to create a link to the file (for front end)
+ * - Gives method to destroy the file when no longer needed
+ * - User can redefine the program by passing options object matching props.     
+ * Limited to new browsers that support Blob(), also user preferences or type of browser may limit access to Blob functionality                        
+ */
+export class FileSave {
+  static defaults = {
+    filename: "filesave-file.txt",
+    type: "text/plain;charset=utf-8"
+  }
+  /**
+   * @param {*} data Data to put in blob file
+   * @param {FileSaveOptions} options Options for file, see defaults (ie. type, filename)
+   */
+  constructor(data, options) {
+    this.options = Object.assign({}, FileSave.defaults, options);
+    this.data = data;
+    this.blob = new Blob([data], { type: this.options.type });
+    this.url = URL.createObjectURL(this.blob);
+  }
+  /**
+   * Remove the blob url 
+   */
+  destroy() {
+    return URL.revokeObjectURL(this.url);
+  }
+  /**
+   * Get the blob url
+   */
+  getUrl() {
+    return this.url;
+  }
+  /**
+   * Create link element with blob as href
+   * @param {String} text The text to put in the link
+   */
+  createLink(text) {
+    const link = document.createElement('a');
+    const textNode = document.createTextNode(text);
+    link.setAttribute('download', this.options.filename);
+    link.setAttribute('href', this.url);
+    link.appendChild(textNode);
+    return link;
+  }
+  /**
+   * Check for Compatibility (optional, implement on user side)
+   */
+  static isBrowserSupported() {
+    return "FileReader" in window;
+  }
+}

package/js/utils/floating-ui.js

@@ -0,0 +1,83 @@
+/**
+ * @module utils/floating-ui
+ */
+
+import { 
+  computePosition,
+  autoUpdate,
+  offset,
+  inline,
+  flip,
+  shift,
+  arrow,
+} from "@floating-ui/dom";
+
+export const defaults = {
+  strategy: "absolute",
+  placement: "bottom",
+  inline: false,
+  offset: {
+    mainAxis: 16
+  },
+  shift: true,
+  flip: true,
+  arrow: true, // Options for arrow (not element)
+};
+
+/**
+ * 
+ * @param {Object} elements Elements (trigger, content, and optionally contentArrow)
+ * @param {*} options Configuration options for floatingUi
+ * @returns {Function} floating cleanup function call when no longer needed
+ */
+export function createFloatingUi(elements, config) {
+  const options = Object.assign({}, defaults, config);
+  const { placement, strategy } = options;
+  const { trigger, content, contentArrow } = elements;
+  
+  return autoUpdate(trigger, content, () => {
+    computePosition(trigger, content, {
+      placement,
+      strategy,
+      middleware: [
+        ...addPlugin(inline, options.inline),
+        ...addPlugin(offset, options.offset),
+        ...addPlugin(flip, options.flip),
+        ...addPlugin(shift, options.shift),
+        ...addPlugin(arrow, contentArrow && options.arrow, { element: contentArrow }),
+      ]
+    }).then(data => {
+      const { x, y, middlewareData, placement } = data;
+      const arrowPos = middlewareData.arrow;
+
+      // Update computed styles for the content (popover container)
+      Object.assign(content.style, { 
+        left: `${ x }px`, 
+        top: `${ y }px` 
+      });
+
+      // Update placement attribute (used by arrow for theming)
+      content.setAttribute("data-placement", placement);
+
+      // If arrow was enabled, add it's computed styles
+      if (arrowPos) {
+        Object.assign(contentArrow.style, {
+          // position: "absolute",
+          left: arrowPos?.x != null ? `${ arrowPos.x }px` : "",
+          top: arrowPos?.y != null ? `${ arrowPos.y }px` : "",
+        });
+      }
+    });
+  });
+}
+
+function addPlugin(plugin, option, overrides = {}) {
+  if (!option) {
+    return [];
+  // If object add it as options, else just enable without options
+  } else if (typeof option === "object") {
+    return [plugin({ ...option,  ...overrides })];
+  } else {
+    return [plugin(overrides)];
+  }
+}

package/js/utils/id.js

@@ -0,0 +1,22 @@
+/**
+ * @module utils/id
+ */
+
+let idCount = 0;
+
+/**
+ * Create new uid
+ */
+export function newId() {
+  return `ulu-uid-${ ++idCount }`;
+}
+
+/**
+ * Sets an ID if element doesn't have one vie newUid
+ * @param {Node} element Element to make sure has an id
+ */
+export function ensureId(element) {
+  if (!element.id) {
+    element.id = newId();
+  }
+}

package/js/utils/index.js

@@ -0,0 +1,7 @@
+export * as classLogger from "./class-logger.js";
+export * as dom from "./dom.js";
+export * as floatingUi from "./floating-ui.js";
+export * as id from "./id.js";
+export * as index from "./index.js";
+export * as pauseYoutubeVideo from "./pause-youtube-video.js";
+export * as fileSave from "./file-save.js";

package/js/{helpers → utils}/pause-youtube-video.js

@@ -1,5 +1,5 @@
 /**
- * @module helpers/pause-youtube-video
+ * @module utils/pause-youtube-video
  */
 
 // Version:         1.0.4