@ulu/frontend 0.1.0-beta.11 → 0.1.0-beta.111

package/js/events/index.js

@@ -21,30 +21,31 @@ const events = {
    * - Is triggered by modules that were responsible for modifying the page
    */
   pageModified(context) {
-    context.dispatchEvent(new CustomEvent(getName("pageModified"), { bubbles: true }));
+    context.dispatchEvent(createEvent("pageModified"));
   },
   /**
    * Event called when page is resized
    */
   pageResized(context) {
-    context.dispatchEvent(new CustomEvent(getName("pageResized"), { bubbles: true }));
+    context.dispatchEvent(createEvent("pageResized"));
   },
   /**
    * Event dispatched before page print begins (teardown/restructure/hide things)
    */
   beforePrint(context) {
-    context.dispatchEvent(new CustomEvent(getName("beforePrint"), { bubbles: true }));
+    context.dispatchEvent(createEvent("beforePrint"));
   },
   /**
    * Event dispatched after page print (cleanup)
    */
   afterPrint(context) {
-    context.dispatchEvent(new CustomEvent(getName("afterPrint"), { bubbles: true }));
+    context.dispatchEvent(createEvent("afterPrint"));
   }
 };
 
 /**
- * Triggers one of our custom events
+ * Triggers one of our custom events (page/document level events)
+ * - UI components may dispatch their own events, this is just used for system wide events
  * @param {String} type Type of event to dispatch
  * @param {Node} context Element to trigger the event from
  * @example
@@ -62,6 +63,7 @@ export function dispatch(type, context) {
 
 /**
  * Namespaced event
+ * - Should be used for all ulu script/component events
  * @param {String} type Type of event to get the actual event name for
  * @returns {String}
  */
@@ -69,6 +71,16 @@ export function getName(type) {
   return "ulu:" + type;
 }
 
+/**
+ * Create ulu namespaced custom event
+ * @param {String} type Event base name (not prefixed)
+ * @param {any} data Custom data to pass with the event (will be available as `event.detail`)
+ * @param {Object} options CustomEvent options default `{ bubbles: true }`. If `detail` is also provided, it will be merged with this options object and will override the 'data' argument for this function
+ */
+export function createEvent(type, data = null, options = { bubbles: true }) {
+  return new CustomEvent(getName(type), { detail: data, ...options });
+}
+
 /**
  * Setup resize handler/dispatch
  */

package/js/index.js

@@ -5,6 +5,7 @@
 // - Will not include things that aren't used in every site (those would need to 
 //   imported manually
 
+export * as settings from "./settings.js";
 export * as events from "./events/index.js";
 export * as ui from "./ui/index.js";
 export * as utils from "./utils/index.js";

package/js/settings.js

@@ -0,0 +1,97 @@
+/**
+ * @module settings
+ * @description Manages shared configuration for the library.
+ */
+
+/**
+ * Default settings
+ * @typedef {object} Defaults
+ * @property {string} iconClassClose - The CSS class string for the close icon
+ * @property {string} iconClassDragX - The CSS class string for the drag X icon
+ * @property {string} iconClassDragBoth - The CSS class string for the dragging in both directions
+ * @property {string} iconClassPrevious - The CSS class string for the previous icon
+ * @property {string} iconClassNext - The CSS class string for the next icon
+ * @property {string} cssvarPrefix - The prefix to use for CSS custom properties
+ */
+
+/**
+ * @type {Defaults}
+ */
+const defaults = {
+  iconClassClose: "css-icon css-icon--close",
+  iconClassDragX: "css-icon css-icon--drag-x",
+  iconClassDragBoth: "css-icon css-icon--drag-both",
+  iconClassPrevious: "css-icon  css-icon--angle-left",
+  iconClassNext: "css-icon  css-icon--angle-right",
+  cssvarPrefix: "",
+};
+
+// Current configuration, initialized with defaults
+let currentSettings = { ...defaults };
+
+/**
+ * Retrieves a copy of the default settings.
+ * @returns {object} A copy of the default settings object.
+ */
+export function getDefaultSettings() {
+  return { ...defaults };
+}
+
+/**
+ * Updates multiple configuration settings.
+ * @param {object} changes An object containing the settings to update.
+ */
+export function updateSettings(changes) {
+  Object.assign(currentSettings, changes);
+}
+
+/**
+ * Retrieves a copy of the current configuration settings.
+ * @returns {object} A copy of the current settings object.
+ */
+export function getSettings() {
+  return { ...currentSettings };
+}
+
+/**
+ * Retrieves a specific configuration setting by key.
+ * @param {string} key The key of the setting to retrieve.
+ * @returns {*} The value of the setting, or undefined if not found.
+ */
+export function getSetting(key) {
+  if (!currentSettings.hasOwnProperty(key)) {
+    console.warn(`Attempted to access non-existent setting: ${key}`);
+    return undefined;
+  }
+  return currentSettings[key];
+}
+
+/**
+ * Updates a specific configuration setting.
+ * @param {string} key The key of the setting to update.
+ * @param {*} value The new value for the setting.
+ */
+export function updateSetting(key, value) {
+  currentSettings[key] = value;
+}
+
+/**
+ * Creates a wrapped string representation of a configuration setting.
+ * This function returns an object with a `toString()` method that, when called,
+ * retrieves the current value of the specified setting. This allows the setting
+ * to be used as a string literal, dynamically retrieving its value.
+ *
+ * @param {String} key The key of the setting to wrap.
+ * @param {Function} transform Optional function to transform the setting's
+ * value when its string representation is requested.
+ * @returns {Object} An object with a `toString()` method that returns the
+ * (optionally transformed) setting value as a string.
+ */
+export function wrapSettingString(key, transform) {
+  return {
+    toString() {
+      const value = getSetting(key);
+      return transform ? transform(value) : value;
+    }
+  };
+}

package/js/ui/breakpoints.js

@@ -5,8 +5,11 @@
 // Pass breakpoints from CSS to stylesheet, use this to attach behaviors on breakpoints
 import { removeArrayElement } from "@ulu/utils/array.js";
 import { getName } from "../events/index.js";
+import { wrapSettingString } from "../settings.js";
+import { getCustomProperty } from "../utils/css.js";
 import { log, logError } from "../utils/class-logger.js";
 
+const getDefaultCustomProperty = prefix => getCustomProperty(prefix, "breakpoint");
 
 // Resize Handler to update breakpoints for all instances (Called after resize finished)
 window.addEventListener(getName("pageResized"), () => {
@@ -16,25 +19,26 @@ window.addEventListener(getName("pageResized"), () => {
 /**
  * @class
  * Class that provides method for retrieving and acting on breakpoints passed
- * from CSS (using element psuedo content prop)
+ * from CSS (using element pseudo content prop)
  */
 export class BreakpointManager {
   static instances = [];
   static defaults = {
     element: document?.documentElement,
-    valueFromPsuedo: false,
+    valueFromPseudo: false,
     customProperty: "--breakpoint",
-    psuedoSelector: ':before',
+    customProperty: wrapSettingString("cssvarPrefix", getDefaultCustomProperty),
+    pseudoSelector: ':before',
     order: ["none", "small", "medium", "large"],
     debug: false
   }
   /**
-   * @param {Object} config Configruation object
+   * @param {Object} config Configuration object
    * @param {Array} config.order Array of strings that correspond to the breakpoints setup in the styles, Breakpoints from smallest to largest, defaults to [small, medium, large]
    * @param {Array} config.customProperty Property to grab breakpoint from (default is --breakpoint)
-   * @param {Array} config.valueFromPsuedo Use the legacy method of grabbing breakpoint from psuedo element, default uses custom property
-   * @param {Node} config.element The element to retrieve active breakpoint from stylesheet. (default is html) For using the old psuedo method, adjust this to document.body
-   * @param {String} config.psuedoSelector Change psuedo selector used to get the breakpoint from the psuedo's content property
+   * @param {Array} config.valueFromPseudo Use the legacy method of grabbing breakpoint from pseudo element, default uses custom property
+   * @param {Node} config.element The element to retrieve active breakpoint from stylesheet. (default is html) For using the old pseudo method, adjust this to document.body
+   * @param {String} config.pseudoSelector Change pseudo selector used to get the breakpoint from the pseudo's content property
    */
   constructor(config) {
     Object.assign(this, BreakpointManager.defaults, config);
@@ -51,9 +55,9 @@ export class BreakpointManager {
     BreakpointManager.instances.push(this);
   }
   /**
-   * Add a callback for everytime a breakpoint changes
+   * Add a callback for every time a breakpoint changes
    * - Not recommended, possibly use to watch for changes, etc
-   * - For more control use intance.at(name) with breakpoint methods
+   * - For more control use instance.at(name) with breakpoint methods
    * @param {Function} callback Function to call, passed one argument current instance which can be used to get information about breakpoints
    */
   onChange(callback) {
@@ -67,10 +71,10 @@ export class BreakpointManager {
     removeArrayElement(this.onChangeCallbacks, callback);
   }
   /**
-   * Get breakpoint from a psuedo element
+   * Get breakpoint from a pseudo element
    */
-  getBreakpointInPsuedo() {
-    return window.getComputedStyle(this.element, this.psuedoSelector).content.replace(/^"|"$/g, '');
+  getBreakpointInPseudo() {
+    return window.getComputedStyle(this.element, this.pseudoSelector).content.replace(/^"|"$/g, '');
   }
   /**
    * Get breakpoint from a custom property
@@ -82,8 +86,8 @@ export class BreakpointManager {
    * Get breakpoint from element (design note: user could override prototype)
    */
   getBreakpoint() {
-    if (this.valueFromPsuedo) {
-      return this.getBreakpointInPsuedo();
+    if (this.valueFromPseudo) {
+      return this.getBreakpointInPseudo();
     } else {
       return this.getBreakpointInProperty();
     }
@@ -97,9 +101,8 @@ export class BreakpointManager {
       logError(this, 'Unable to get current breakpoint, maybe order is incorrect? Breakpoint check skipped!');
       return;
     }
-    // console.log('name:\n', name);
     if (name === this.active) return;
-    // this.log(`current breakpoint: ${ name }`);
+    
     // Update active and cache last
     this.previous = this.active;
     this.previousIndex = this.activeIndex;

package/js/ui/collapsible.js

@@ -71,7 +71,14 @@ export class Collapsible {
     }
     this.focusoutHandler = (event) => {
       if (focusoutCloses) {
-        this.close(event);
+        // If closing on focus out we attach one-time event to 
+        // see which element is focused next (in between focusout and focusin 
+        // it's the body) so doing the logic in focusout won't work
+        document.addEventListener('focusin', () => {
+          if (!content.contains(document.activeElement)) {
+            this.close(event);
+          }
+        }, { once: true });
       }
     };
     trigger.addEventListener("click", this.clickHandler);

package/js/ui/details-group.js

@@ -0,0 +1,112 @@
+/**
+ * @module ui/details-group
+ * @description Manages groups of details (ie. onlyOneOpen at a time)
+ */
+
+import { ComponentInitializer } from "../utils/system.js";
+
+/**
+ * Dialog Component Initializer
+ */
+export const initializer = new ComponentInitializer({ 
+  type: "details-group", 
+  baseAttribute: "data-ulu-details-group" 
+});
+
+const childInitAttr = initializer.getAttribute("child-init");
+const defaults = {
+  onlyOneOpen: true,
+  childSelector: ":scope > details"
+};
+
+/**
+ * Initialize everything in document
+ * - This will only initialize elements once, it is safe to call on page changes
+ */
+export function init() {
+  initializer.init({
+    withData: true,
+    events: ["pageModified"],
+    setup({ element, data, initialize }) {
+      setupGroup(element, data);
+      initialize();
+    }
+  });
+}
+
+/**
+ * @typedef {Object} DetailsGroupInstance
+ * @property {Function} destroy A function to remove event listeners and attributes.
+ * @property {HTMLElement} element The parent element.
+ * @property {Function} setupChildren A function to initialize the child details elements.
+ */
+
+/**
+ * Sets up a single group of details elements to manage their behavior.
+ * @param {HTMLElement} element - The parent element containing the details elements.
+ * @param {Object} options - The options for this group
+ * @returns {DetailsGroupInstance}      
+ */
+export function setupGroup(element, userOptions) {
+  const options = Object.assign({}, defaults, userOptions);
+
+  // Added try because we are using querySelectorAll with :scope by default
+  // which will not work in Internet Explorer or early edge (some alt. browsers too)
+  try {
+    setupChildren();
+  } catch(error) {
+    console.error(error);
+  }
+
+  /**
+   * Queries all current children in element
+   * @ignore
+   */
+  function queryChildren() {
+    return element.querySelectorAll(options.childSelector);
+  }
+
+  /**
+   * Sets up any children not already setup in group
+   */
+  function setupChildren() {
+    queryChildren().forEach(child => {
+      if (child.hasAttribute(childInitAttr)) {
+        return;
+      } else {
+        child.setAttribute(childInitAttr, "");
+      }
+      child.addEventListener("toggle", toggleHandler);  
+    });
+  }
+  
+  /**
+   * Toggle handler for child details element
+   * - For things like one open at a time
+   * @ignore
+   */
+  function toggleHandler({ target }) {
+    if (options.onlyOneOpen) {
+      if (target.open) {
+        queryChildren().forEach(child => {
+          if (child !== target && child.open) {
+            child.open = false;
+          }
+        });
+      }
+    }
+  }
+
+  /**
+   * Function removes all handlers and init attributes
+   */
+  function destroy() {
+    queryChildren().forEach(child => {
+      child.removeEventListener("toggle", toggleHandler);
+      child.removeAttribute(childInitAttr);
+    });
+    element.removeAttribute(initializer.getAttribute("init"));
+  }
+
+  return { destroy, element, setupChildren };
+}

package/js/ui/dialog.js

@@ -3,22 +3,24 @@
  */
 
 import { getName } from "../events/index.js";
-import { getDatasetJson, wasClickOutside } from "../utils/dom.js";
+import { ComponentInitializer } from "../utils/system.js";
+import { wasClickOutside, preventScroll as setupPreventScroll } from "@ulu/utils/browser/dom.js";
 import { pauseVideos as pauseYoutubeVideos, prepVideos as prepYoutubeVideos } from "../utils/pause-youtube-video.js";
+
 /**
- * Default data attributes
+ * Base attribute for a dialog
  */
-export const attrs = {
-  init: "data-ulu-dialog-init",
-  dialog: "data-ulu-dialog",
-  trigger: "data-ulu-dialog-trigger",
-  close: "data-ulu-dialog-close",
-};
+export const baseAttribute = "data-ulu-dialog"; // Exposed for modal builder
+
+/**
+ * Dialog Component Initializer
+ */
+export const initializer = new ComponentInitializer({ type: "dialog", baseAttribute });
 
-// Utils for selecting things based on attributes
-const attrSelector = key => `[${ attrs[key] }]`;
-const attrSelectorInitial = key => `${ attrSelector(key) }:not([${ attrs.init }])`;
-const queryAllInitial = key => document.querySelectorAll(attrSelectorInitial(key));
+/**
+ * Attribute for close buttons within a dialog
+ */
+export const closeAttribute = initializer.getAttribute("close"); // Exposed for modal builder
 
 /**
  * Dialog Defaults 
@@ -42,6 +44,15 @@ export const defaults = {
    * Whether or not to pause videos when dialog closes (currently just youtube and native)
    */
   pauseVideos: true,
+  /**
+   * When open and not non-modal, the body is prevented from scrolling (defaults to true).
+   */
+  preventScroll: true,
+  /**
+   * Compensate for layout shift when preventing scroll. Which adds padding equal to scrollbars 
+   * width while dialog is open
+   */
+  preventScrollShift: true,
 };
 
 
@@ -49,7 +60,7 @@ export const defaults = {
 let currentDefaults = { ...defaults };
 
 /**
- * @param {Object} options Change options used as default for dialogs, can then be overriden by data attribute settings on element
+ * @param {Object} options Change options used as default for dialogs, can then be overridden by data attribute settings on element
  */
 export function setDefaults(options) {
   currentDefaults = Object.assign({}, currentDefaults, options);
@@ -60,35 +71,48 @@ export function setDefaults(options) {
  * - This will only initialize elements once, it is safe to call on page changes
  */
 export function init() {
-  document.addEventListener(getName("pageModified"), setup);
-  setup();
-}
-
-/**
- * Setup dialogs and triggers
- */
-export function setup() {
-  // Then setup all dialogs (including those that were built)
-  const dialogs = queryAllInitial("dialog");
-  dialogs.forEach(setupDialog);
-
-  const triggers = queryAllInitial("trigger");
-  triggers.forEach(setupTrigger);
+  // Initialize all the dialogs
+  initializer.init({
+    events: ["pageModified"],
+    withData: true,
+    setup({ element, initialize, data }) {
+      setupDialog(element, data);
+      initialize();
+    }
+  });
+
+  // Initialize all triggers (things that trigger opening a dialog)
+  initializer.init({
+    key: "trigger",
+    events: ["pageModified"],
+    withData: true,
+    setup({ element, initialize, data: dialogId }) {
+      setupTrigger(element, dialogId);
+      initialize();
+    }
+  });
 }
 
 /**
  * Setup click handlers on a trigger
- * @param {Node} trigger 
+ * @param {Node} trigger Trigger button element
+ * @param {String} dialogId The dialog's id to open
  */
-export function setupTrigger(trigger) {
+export function setupTrigger(trigger, dialogId) {
   trigger.addEventListener("click", handleTrigger);
-  trigger.setAttribute(attrs.init, "");
 
-  function handleTrigger() {
-    const id = trigger.dataset.uluDialogTrigger;
-    const dialog = document.getElementById(id);
+  function handleTrigger(event) {
+    
+    // If a link is used (not recommended) we need to prevent 
+    // the page from scrolling
+    const closestLink = event.target.closest("a");
+    if (closestLink) {
+      event.preventDefault();
+    }
+    
+    const dialog = document.getElementById(dialogId);
     if (!dialog) {
-      console.error("Could not locate dialog (id)", id);
+      console.error("Could not locate dialog (id)", dialogId);
       return;
     }
     if (dialog?.tagName?.toLowerCase() !== "dialog") {
@@ -104,23 +128,49 @@ export function setupTrigger(trigger) {
  * Setup click handlers for a dialog
  * @param {Node} dialog 
  */
-export function setupDialog(dialog) {
-  const options = getDialogOptions(dialog);
+export function setupDialog(dialog, userOptions) {
+  const options = Object.assign({}, currentDefaults, userOptions);
+  const body = document.body;
+  const { preventScrollShift: preventShift } = options;
+
+  // Stores active pointerId for resizer until after the whole pointer event series 
+  // is finished which is after the click is complete
+  let activeResizePointer;
+
+  dialog.addEventListener(getName("resizer:start"), handleResizeStart);
+  dialog.addEventListener(getName("resizer:end"), handleResizeEnd);
   dialog.addEventListener("click", handleClicks);
-  dialog.setAttribute(attrs.init, "");
+
   if (options.documentEnd) {
-    document.body.appendChild(dialog);
+    body.appendChild(dialog);
   }
   if (options.pauseVideos) {
     prepVideos(dialog);
   }
 
+  // Allow preventScroll if it is a modal dialog
+  // Caching value of overflow before setting so we don't assume what it's initial value is
+  if (!options.nonModal && options.preventScroll) {
+    // Cache restore function
+    let restoreScroll; 
+
+    // Toggle prevent scroll
+    dialog.addEventListener("toggle", (event) => {
+      const isOpen = event.newState === "open";
+      if (isOpen) {
+        restoreScroll = setupPreventScroll({ preventShift });
+      } else if (restoreScroll) {
+        restoreScroll();
+      }
+    });
+  }
+
   function handleClicks(event) {
     const { target } = event;
-    const closeFromButton = target.closest("[data-ulu-dialog-close]");
-    let closeFromOutside = options.clickOutsideCloses && 
-                           target === dialog && 
-                           wasClickOutside(dialog, event);
+    const targetIsDialog = target === dialog;
+    const closeFromButton = target.closest(initializer.attributeSelector("close"));
+    const allowCloseOutside = !activeResizePointer && options.clickOutsideCloses;
+    const closeFromOutside = allowCloseOutside && targetIsDialog && wasClickOutside(dialog, event);
     if (closeFromOutside || closeFromButton) {
       if (options.pauseVideos) {
         pauseVideos(dialog);
@@ -128,6 +178,15 @@ export function setupDialog(dialog) {
       dialog.close();
     }
   }
+  function handleResizeStart(event) {
+    activeResizePointer = event.pointerId;
+  }
+  function handleResizeEnd(event) {
+    if (activeResizePointer === event.pointerId) {
+      // next event cycle (after click/pointer events finish in current)
+      setTimeout(() => { activeResizePointer = null;}, 0);
+    }
+  }
 } 
 
 /**
@@ -136,8 +195,7 @@ export function setupDialog(dialog) {
  * @returns {Object}
  */
 export function getDialogOptions(dialog) {
-  const options = getDatasetJson(dialog, "uluDialog");
-  return Object.assign({}, currentDefaults, options);
+  return Object.assign({}, currentDefaults, initializer.getData(dialog));
 }
 
 /**
@@ -146,6 +204,7 @@ export function getDialogOptions(dialog) {
 function prepVideos(dialog) {
   prepYoutubeVideos(dialog);
 }
+
 /**
  * Prep videos to be paused for a given dialog
  */

package/js/ui/dialog.todo

@@ -1,37 +1,3 @@
-Styling:
-  ✔ Animations? @done
-  ☐ Check styling on left right
+Dialog Todos:
   ☐ Setup fullscreen option / modifier
-  ☐ Setup programmatic modal with new system
-  ☐ Resizing
-    ✔ Work out how this can work with native and click outside @done
-    ✔ Figure out how to setup icon for the resizer for all sites @done
-      * Fontawesome, or should this just be CSS so we don't need any icons for it
-      * Same for close button should we just use CSS and omit any FA requirements
-      * Or make it super easy to implement the icon only in the template (like default icon classses)
-        * Then user can choose to implement their own (via class) or use the styles that come with it
-  ☐ Prevent Browser Scroll
-  ✔ How should height work? Should a centered modal expand to it's content's height (up to the viewport height) or always be cropped and scroll (static height)? @done
-Todos:
-  ✔ How should the relationship between a dialog and it's trigger work @done
-    * Think there should be no relationship? Just triggers are triggers just attach a handler to open DOM centric way (add errors when the dialog doesn't exist)
-    * For the dialogs they should just have handlers attached for close
-      * Init should find all one's that need to be built and build them, then it should initialize them the same way as non-built dialogs
-  ✔ Support both modal and non-modal dialogs (rename)? @done
-  ✘ Divide into 4 modules @cancelled
-    1. Initializer (data-attributes)
-    2. Templater (for Drupal projects and standard modals)
-    3. Open/Close Behaviors
-    4. Programmatic Modal
-      * This is tough because its opionated towards our system in Drupal (jQuery)
-  ✔ How should this all be structured @done
-    * JS template dialogs?
-      * Pros
-        * Many users create the modals in content in CMS we don't want to make that difficult or get stuck with structure
-      * Cons
-        * Templating is in JS so dialogs don't make much sense on their own
-          * Could continue the div to dialog conversion (so modal content is inline unless JS running). Don't want to optimize too much for no js anymore anyways
-        * writing the dialog by hand makes sense for non defualt modal styles or users that have another structure but need the scripting part
-      * Solution
-        * Breakup module into two parts the underlying modal scripting (open close trigger) and (conversion modal templating [w. resizer] and as <div>)
-          * Then we can have both without any extra code and seperation
+  ☐ Prevent Browser Scroll