@ulu/frontend 0.1.0-beta.99 → 0.2.0-beta.10

package/{js/utils/system.js → lib/js/core/component.js}

@@ -1,12 +1,12 @@
 /**
- * @module utils/system
+ * @module core/component
  * @description Core classes and mechanisms that define how UI components are created and managed within the library
  */
 
 import { hasRequiredProps } from "@ulu/utils/object.js";
 import { getDatasetOptionalJson } from "@ulu/utils/browser/dom.js";
-import { dataAttributeToDatasetKey } from "./dom.js";
-import { getName } from "../events/index.js";
+import { dataAttributeToDatasetKey } from "../utils/dom.js";
+import { getCoreEventName } from "./events.js";
 
 /**
  * Class serves as a utility for UI modules, handling the selection of elements and the initialization of corresponding component instances, ensuring consistent setup within the module
@@ -45,18 +45,20 @@ export class ComponentInitializer {
    * @param {Function} config.setup The setup function to call for each element.
    * @param {String} config.key [null] The optional key to use with attribute selector.
    * @param {Boolean} config.withData [null] Whether to retrieve element data.
-   * @param {Array} config.events [null] Ulu events that should call setup when dispatched (ie. pageModified, pageResized)
-   * @param {Boolean} config.onPageResized [null] Whether to bind event listener for page resize end
+   * @param {Array} config.coreEvents [null] An array of core event names (e.g., 'pageModified') that should trigger a re-initialization.
    * @param {HTMLElement} config.context [document] The context to query within.
    */
   init(config) {
     this.setupElements(config);
     // Attach Handler to reinitialize if page is updated
-    // Specifically checking entire document incase element that dispatched 
+    // Specifically checking entire document in case element that dispatched 
     // event made alterations  outside of itself
-    if (config.events?.length) {
-      config.events.forEach(name => {
-        document.addEventListener(getName(name), () => this.setupElements(config));
+    if (config.coreEvents?.length) {
+      config.coreEvents.forEach(name => {
+        const eventName = getCoreEventName(name);
+        if (eventName) {
+          document.addEventListener(eventName, () => this.setupElements(config));
+        }
       });
     }
   }
@@ -66,7 +68,6 @@ export class ComponentInitializer {
    * @param {function} config.setup The setup function to call for each element.
    * @param {string} config.key The optional key to use with attribute selector.
    * @param {boolean} config.withData [false] Whether to retrieve element data.
-   * @param {boolean} config.onPageModified [true] Whether to bind event listener for page modifications.
    * @param {HTMLElement} config.context [document] The context to query within.
    */
   setupElements(config) {
@@ -150,6 +151,6 @@ export class ComponentInitializer {
 /**
  * Class serves as a base for representing individual occurrences of a UI component, providing a consistent structure for each
  */
-export class ComponentInstance {
+// export class ComponentInstance {
 
-} 
+// } 

package/lib/js/core/events.js

@@ -0,0 +1,98 @@
+/**
+ * @module core/events
+ * @description Internal implementation of global event handling.
+ */
+
+import { debounce } from "@ulu/utils/performance.js";
+import { isBrowser } from "@ulu/utils/browser/dom.js";
+
+// Setup global document events
+if (isBrowser()) {
+  initResize();
+  initPrint();
+}
+
+/**
+ * Event object - called on dispatch
+ */
+const events = {
+  pageModified(context) {
+    context.dispatchEvent(createUluEvent("pageModified"));
+  },
+  pageResized(context) {
+    context.dispatchEvent(createUluEvent("pageResized"));
+  },
+  beforePrint(context) {
+    context.dispatchEvent(createUluEvent("beforePrint"));
+  },
+  afterPrint(context) {
+    context.dispatchEvent(createUluEvent("afterPrint"));
+  }
+};
+
+const eventKeys = Object.keys(events);
+
+/**
+ * Triggers one of the predefined core lifecycle events.
+ * @param {String} type Type of core event to dispatch.
+ * @param {Node} context Element to trigger the event from.
+ */
+export function dispatchCoreEvent(type, context) {
+  if (events[type]) {
+    events[type](context);
+  } else {
+    console.warn(`Unable to dispatch non-core event: ${type}`);
+  }
+}
+
+/**
+ * A general-purpose utility to get a ULU-namespaced event name.
+ * @param {String} type The base name for the event.
+ * @returns {String} The `ulu:` prefixed event name.
+ */
+export function getUluEventName(type) {
+  return "ulu:" + type;
+}
+
+/**
+ * Safely gets the full namespaced name for a predefined core event.
+ * @param {String} type The base name of the core event (e.g., 'pageModified').
+ * @returns {String|null} The full event name if valid, otherwise null.
+ */
+export function getCoreEventName(type) {
+  if (eventKeys.includes(type)) {
+    return getUluEventName(type);
+  }
+  console.warn(`'${type}' is not a valid core event type.`);
+  return null;
+}
+
+/**
+ * A general-purpose utility to create a ULU-namespaced CustomEvent.
+ * @param {String} type Event base name.
+ * @param {any} data Custom data to pass with the event.
+ * @param {Object} options CustomEvent options.
+ * @returns {CustomEvent}
+ */
+export function createUluEvent(type, data = null, options = { bubbles: true }) {
+  return new CustomEvent(getUluEventName(type), { detail: data, ...options });
+}
+
+/**
+ * Setup resize handler/dispatch
+ */
+function initResize() {
+  window.addEventListener("resize", debounce(() => dispatchCoreEvent("pageResized", document), 250));
+}
+
+/**
+ * Setup print listeners
+ */
+function initPrint() {
+  window.addEventListener("beforeprint", () => {
+    dispatchCoreEvent("beforePrint", document);
+  });
+  window.addEventListener("afterprint", () => {
+    dispatchCoreEvent("afterPrint", document);
+  }); 
+}

package/lib/js/core/index.js

@@ -0,0 +1,34 @@
+/**
+ * @module core
+ * @description
+ * Public API for the core modules.
+ *
+ * This file re-exports the internal implementations from the `core` directory
+ * with new names where appropriate, defining the public-facing API for the
+ * library bundle.
+ *
+ * For internal library usage, import directly from the specific file within
+ * the `core` directory (e.g., `import { ... } from './settings.js'`).
+ */
+
+export {
+  dispatchCoreEvent,
+  getCoreEventName,
+  getUluEventName,
+  createUluEvent
+} from './events.js';
+
+export {
+  getDefaultSettings,
+  updateSettings,
+  getSettings,
+  getSetting,
+  updateSetting,
+  wrapSettingString
+} from './settings.js';
+
+export {
+  ComponentInitializer
+} from './component.js';
+
+

package/{js → lib/js/core}/settings.js

@@ -1,6 +1,6 @@
 /**
- * @module settings
- * @description Manages shared configuration for the library.
+ * @module core/settings
+ * @description Internal implementation for managing shared configuration.
  */
 
 /**
@@ -94,4 +94,4 @@ export function wrapSettingString(key, transform) {
       return transform ? transform(value) : value;
     }
   };
-}
+}

package/lib/js/exports.md

@@ -0,0 +1,126 @@
+# Exports Map
+
+## Example Import
+
+All JavaScript modules are exported from the main `@ulu/frontend` package entry point.
+
+**Example Usage:**
+```javascript
+import { dialogInit, Slider, updateSettings } from '@ulu/frontend';
+
+// Update a library setting
+updateSettings({ cssvarPrefix: "my-app" });
+
+// Initialize all dialogs
+dialogInit();
+
+// Create a new slider
+const slider = new Slider(...);
+```
+
+## Exports Map
+
+### Core Modules
+
+These exports originate from the `lib/js/core/` directory and provide the foundational, cross-cutting logic for the library.
+
+- `ComponentInitializer`
+- `createUluEvent`
+- `dispatchCoreEvent`
+- `getCoreEventName`
+- `getDefaultSettings`
+- `getSettings`
+- `getSetting`
+- `getUluEventName`
+- `updateSetting`
+- `updateSettings`
+- `wrapSettingString`
+
+### UI Modules
+
+These exports originate from the `lib/js/ui/` directory.
+
+- `BreakpointManager`
+- `Collapsible`
+- `detailsGroupInit`
+- `detailsGroupInitializer`
+- `detailsGroupSetupGroup`
+- `dialogBaseAttribute`
+- `dialogCloseAttribute`
+- `dialogDefaults`
+- `dialogGetDialogOptions`
+- `dialogInit`
+- `dialogInitializer`
+- `dialogSetDefaults`
+- `dialogSetupDialog`
+- `dialogSetupTrigger`
+- `Flipcard`
+- `flipcardInit`
+- `flipcardInitializer`
+- `gridInit`
+- `gridInitializer`
+- `modalBuilderBuildModal`
+- `modalBuilderDefaults`
+- `modalBuilderInit`
+- `modalBuilderInitializer`
+- `modalBuilderSetDefaults`
+- `OverflowScroller`
+- `overflowScrollerCreatePager`
+- `pageInit`
+- `Popover`
+- `popoverGetContentByTrigger`
+- `popoverInit`
+- `popoverInitializer`
+- `popoverInstances`
+- `popoverResolve`
+- `printDetailsAttrs`
+- `printDetailsInit`
+- `printInit`
+- `proxyClickAttachHandlers`
+- `proxyClickDefaults`
+- `proxyClickInit`
+- `proxyClickInitializer`
+- `proxyClickSetDefaults`
+- `proxyClickSetupProxy`
+- `Resizer`
+- `scrollSliderInit`
+- `scrollSliderInitializer`
+- `Scrollpoint`
+- `scrollpointInit`
+- `scrollpointInitializer`
+- `Slider`
+- `sliderInit`
+- `sliderInitializer`
+- `sliderSetupSlider`
+- `tabsInit`
+- `tabsInitializer`
+- `tabsInstances`
+- `tabsSetup`
+- `themeToggleDefaults`
+- `themeToggleInit`
+- `themeToggleInitializer`
+- `themeToggleSetDefaults`
+- `themeToggleSetupToggle`
+- `Tooltip`
+- `tooltipInit`
+- `tooltipInitializer`
+
+### Utility Modules
+
+These exports originate from the `lib/js/utils/` directory.
+
+- `classLoggerLog`
+- `classLoggerLogError`
+- `classLoggerLogWarning`
+- `classLoggerSet`
+- `fontAwesomeConfigureIcons`
+- `createFloatingUi`
+- `dataAttributeToDatasetKey`
+- `ensureId`
+- `FileSave`
+- `floatingUiDefaults`
+- `newId`
+- `resolveClasses`
+- `setPositionClasses`
+- `youtubePauseVideos`
+- `youtubePrepVideos`

package/lib/js/index.js

@@ -0,0 +1,7 @@
+// Re-export all flattened, prefixed modules from the library.
+// This serves as the main entry point for the tree-shakable ESM bundle.
+
+export * from "./core/index.js";
+export * from "./ui/index.js";
+export * from "./utils/index.js";
+

package/{js → lib/js}/ui/breakpoints.js

@@ -4,18 +4,14 @@
 
 // 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 { isBrowser } from "@ulu/utils/browser/dom.js";
+import { getCoreEventName } from "../core/events.js";
+import { wrapSettingString } from "../core/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"), () => {
-  BreakpointManager.instances.forEach(i => i.update());
-});
-
 /**
  * @class
  * Class that provides method for retrieving and acting on breakpoints passed
@@ -23,6 +19,17 @@ window.addEventListener(getName("pageResized"), () => {
  */
 export class BreakpointManager {
   static instances = [];
+  static globalsInitialized = false;
+
+  static _initializeGlobals() {
+    if (BreakpointManager.globalsInitialized || !isBrowser()) {
+      return;
+    }
+    window.addEventListener(getCoreEventName("pageResized"), () => {
+      BreakpointManager.instances.forEach(i => i.update());
+    });
+    BreakpointManager.globalsInitialized = true;
+  }
   static defaults = {
     element: document?.documentElement,
     valueFromPseudo: false,
@@ -41,6 +48,7 @@ export class BreakpointManager {
    * @param {String} config.pseudoSelector Change pseudo selector used to get the breakpoint from the pseudo's content property
    */
   constructor(config) {
+    BreakpointManager._initializeGlobals();
     Object.assign(this, BreakpointManager.defaults, config);
     this.active = null;
     this.previous = null;
@@ -110,28 +118,23 @@ export class BreakpointManager {
     const index = this.order.indexOf(name);
     this.active = name;
     this.activeIndex = index;
-    const activeBreakpoint = this.at(this.active);
-    // Get arrays of breakpoints based on the order array
-    const mapBreakpoints = n => this.at(n);
-    // From breakpoint to end (highest)
-    const max = this.order.slice(index).map(mapBreakpoints);
-    const notMax = this.order.slice(0, index).map(mapBreakpoints);
-    // From start up to this breakpoint
-    const min = this.order.slice(0, index + 1).map(mapBreakpoints);
-    const notMin = this.order.slice(index + 1).map(mapBreakpoints);
-    const notOnly = this.order.slice().map(mapBreakpoints);
-    notOnly.splice(index, 1);
-    
-    log(this, 'max:', max.map(b => b.name).join());
-    log(this, 'min:', min.map(b => b.name).join());
-    
-    max.forEach(b => b._setDirection('max', true));
-    min.forEach(b => b._setDirection('min', true));
-    activeBreakpoint._setDirection('only', true);
+    // const activeBreakpoint = this.at(this.active);
+
+    // For each breakpoint, set its directional status based on the active index.
+    // This ensures the JS methods match the SCSS mixin behavior.
+    this.order.forEach((bpName, bpIndex) => {
+      const bp = this.breakpoints[bpName];
+      const activeIndex = this.activeIndex;
+
+      // at(NAME).min() is active if active breakpoint is >= NAME.
+      bp._setDirection('min', bpIndex <= activeIndex);
+
+      // at(NAME).max() is active if active breakpoint is < NAME.
+      bp._setDirection('max', bpIndex > activeIndex);
 
-    notMax.forEach(b => b._setDirection('max', false));
-    notMin.forEach(b => b._setDirection('min', false));
-    notOnly.forEach(b => b._setDirection('only', false));
+      // at(NAME).only() is active if active breakpoint is == NAME.
+      bp._setDirection('only', bpIndex === activeIndex);
+    });
 
     // Set direction (extra info if needed)
     if (this.previousIndex !== null) {
@@ -246,18 +249,16 @@ class Breakpoint {
     this.directions[direction].change(active);
   }
   /**
-   * Attach handler to be executed from the breakpoint and to all breakpoints below.
-   * - If the browser resizes from a breakpoint below this breakpoint, 
-   *   and above the breakpoint name specified, this handler will fire
+   * Attach handler to be executed from the breakpoint and to all breakpoints below (inclusive).
+   * This corresponds to a `max-width` media query in SCSS.
    * @param {Function} handler Handler to be executed
    */    
   max(handler) {
     this.directions.max.add(handler);
   }
   /**
-   * Attach handler to be executed from the breakpoint and to all breakpoints below.
-   * - If the browser resizes from a breakpoint above this breakpoint, 
-   *   and below the breakpoint name specified, this handler will fire
+   * Attach handler to be executed from the breakpoint and to all breakpoints above (inclusive).
+   * This corresponds to a `min-width` media query in SCSS.
    * @param {Function} handler Handler to be executed
    */  
   min(handler) {
@@ -277,7 +278,11 @@ class Breakpoint {
    */      
   remove(handler, direction) {
     const directions = direction ? [ direction ] : ['max', 'min', 'only'];
-    directions.forEach(d => d.remove(handler));
+    directions.forEach(d => {
+      if (this.directions[d]) {
+        this.directions[d].remove(handler);
+      }
+    });
   }
   
   log(...msg) {

package/{js → lib/js}/ui/collapsible.js

@@ -2,7 +2,7 @@
  * @module ui/collapsible
  */
 
-import { getName as getEventName } from "../events/index.js";
+import { getUluEventName } from "../core/events.js";
 import { log, logError } from "../utils/class-logger.js";
 import { ensureId } from "../utils/id.js";
 
@@ -110,7 +110,7 @@ export class Collapsible {
     this.setState(startOpen);
   }
   createEvent(name, detail) {
-    return new CustomEvent(getEventName("collapsible:" + name), { detail });
+    return new CustomEvent(getUluEventName("collapsible:" + name), { detail });
   }
   setState(isOpen, event) {
     const ctx = { 

package/{js → lib/js}/ui/details-group.js

@@ -3,7 +3,7 @@
  * @description Manages groups of details (ie. onlyOneOpen at a time)
  */
 
-import { ComponentInitializer } from "../utils/system.js";
+import { ComponentInitializer } from "../core/component.js";
 
 /**
  * Dialog Component Initializer
@@ -26,7 +26,7 @@ const defaults = {
 export function init() {
   initializer.init({
     withData: true,
-    events: ["pageModified"],
+    coreEvents: ["pageModified"],
     setup({ element, data, initialize }) {
       setupGroup(element, data);
       initialize();

package/{js → lib/js}/ui/dialog.js

@@ -2,8 +2,8 @@
  * @module ui/dialog
  */
 
-import { getName } from "../events/index.js";
-import { ComponentInitializer } from "../utils/system.js";
+import { getUluEventName } from "../core/events.js";
+import { ComponentInitializer } from "../core/component.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";
 
@@ -73,7 +73,7 @@ export function setDefaults(options) {
 export function init() {
   // Initialize all the dialogs
   initializer.init({
-    events: ["pageModified"],
+    coreEvents: ["pageModified"],
     withData: true,
     setup({ element, initialize, data }) {
       setupDialog(element, data);
@@ -84,7 +84,7 @@ export function init() {
   // Initialize all triggers (things that trigger opening a dialog)
   initializer.init({
     key: "trigger",
-    events: ["pageModified"],
+    coreEvents: ["pageModified"],
     withData: true,
     setup({ element, initialize, data: dialogId }) {
       setupTrigger(element, dialogId);
@@ -137,8 +137,8 @@ export function setupDialog(dialog, userOptions) {
   // 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(getUluEventName("resizer:start"), handleResizeStart);
+  dialog.addEventListener(getUluEventName("resizer:end"), handleResizeEnd);
   dialog.addEventListener("click", handleClicks);
 
   if (options.documentEnd) {

package/{js → lib/js}/ui/flipcard.js

@@ -2,7 +2,7 @@
  * @module ui/flipcard
  */
 
-import { ComponentInitializer } from "../utils/system.js";
+import { ComponentInitializer } from "../core/component.js";
 import { trimWhitespace } from "@ulu/utils/string.js";
 import { log, logError } from "../utils/class-logger.js";
 
@@ -20,7 +20,7 @@ export const initializer = new ComponentInitializer({
 export function init() {
   initializer.init({
     withData: true,
-    events: ["pageModified"],
+    coreEvents: ["pageModified"],
     setup({ element, data, initialize }) {
       const options = Object.assign({}, data);
       const front = element.querySelector(initializer.attributeSelector("front"));

package/{js → lib/js}/ui/grid.js

@@ -2,7 +2,7 @@
  * @module ui/grid
  */
 
-import { ComponentInitializer } from "../utils/system.js";
+import { ComponentInitializer } from "../core/component.js";
 import { setPositionClasses } from "../utils/dom.js";
 
 /**
@@ -19,7 +19,7 @@ export const initializer = new ComponentInitializer({
  */
 export function init(classes) {
   initializer.init({
-    events: ["pageModified", "pageResized"],
+    coreEvents: ["pageModified", "pageResized"],
     setup({ element, initialize }) {
       setPositionClasses(element, classes);
       initialize();