@ulu/frontend 0.1.0-beta.4 → 0.1.0-beta.40

package/js/ui/theme-toggle.js

@@ -1,129 +1,366 @@
-// Progressive Enhancement turns select elements into accessible autocomplete fields
+/**
+ * @module ui/theme-toggle
+ */
 
-// import { getName } from "@ulu/frontend/js/events/index.js";
+import { ComponentInitializer } from "../utils/system.js";
 import { getName } from "../events/index.js";
+import { getElements, resolveClasses } from "../utils/dom.js";
+import { hasRequiredProps } from "@ulu/utils/object.js";
 
-const attrs = {
-  trigger: "data-site-theme-toggle",
-  icon: "data-site-theme-toggle-icon",
-  init: "data-site-theme-toggle-init",
-};
+/**
+ * Theme Toggle Component Initializer
+ */
+export const initializer = new ComponentInitializer({ 
+  type: "theme-toggle", 
+  baseAttribute: "data-ulu-theme-toggle"
+});
 
-const attrSelector = key => `[${ attrs[key] }]`;
-const attrSelectorInitial = key => `${ attrSelector(key) }:not([${ attrs.init }])`;
-
-// @dan change to options and remove options
-// add a preferred print theme option
-export const options = {
-  darkTheme: "theme-dark",
-  lightTheme: "theme-light",
-  defaultTheme: "dark",
-  darkIcon: "fa-solid fa-moon",
-  lightIcon: "fa-solid fa-sun",
+const attrSelectorLabel = initializer.attributeSelector("label");
+const attrSelectorIcon = initializer.attributeSelector("icon");
+const attrRemote = initializer.getAttribute("remote");
+const attrInit = initializer.getAttribute("init");
+const attrState = initializer.getAttribute("state");
+
+// Utils for selecting things based on attributes
+const queryRemotes = group => document.querySelectorAll(
+  `[${ attrRemote }="${ group }"]`
+);
+const queryRemotesInitial = group => document.querySelectorAll(
+  `[${ attrRemote }="${ group }"]:not([${ attrInit }])`
+);
+const requiredToggleProps = ["target"];
+const checkToggleProps = hasRequiredProps(requiredToggleProps);
+const when = (cond, fn) => cond ? fn() : null; // Consider adding as util 
+
+/**
+ * Default Options 
+ * - Can be overridden using data-attributes
+ */
+export const defaults = {
+  /**
+   * Object of each theme that should be toggle/cycled through
+   */
+  themes: {
+    light: {
+      label: "Light",
+      value: "light",
+      iconClass: "fas fa-moon",
+      targetClass: "theme-light",
+      mediaQuery: "(prefers-color-scheme: light)"
+    },
+    dark: {
+      label: "Dark",
+      iconClass: "fas fa-sun",
+      targetClass: "theme-dark",
+      mediaQuery: "(prefers-color-scheme: dark)"
+    }
+  },
+  /**
+   * Required this is the element(s) that should be changed by a specific toggle
+   * - The element should have data-ulu-theme-toggle-target="SOME_IDENTIFIER"
+   */
+  target: "body",
+  /**
+   * Optional group to link remote toggles (toggles that follow the main one and can toggle too)
+   */
+  group: null,
+  /**
+   * Optional callback to do something when the state changes
+   */
+  onChange(_ctx) {},
+  /**
+   * The initial state for this component
+   * - May be overridden by saved preference or media query if options are enabled
+   */
+  initialState: "light",
+  /**
+   * Check the OS systems user preference via 'preferenceQuery' option
+   */
+  checkMediaQuery: false,
+  /**
+   * Will store the preference in local storage so it persists between page loads
+   */
+  savePreference: false,
+  /**
+   * The key that will be used to store the preference in local storage
+   * - This will be used as prefix in combination with group if defined
+   */
+  storagePrefix: "ulu-theme-",
+  /**
+   * Output information to console for debugging
+   */
+  debug: false
 };
 
-const body = document.querySelector("[data-site-theme]");
-let currentTheme = body.classList.contains(options.darkTheme) ? options.darkTheme : options.lightTheme;
-// used to see if machine preference differs from default theme
-const defaultThemeInverse = options.defaultTheme === "dark" ? "light" : "dark";
+
+// Current default objects (user can override these)
+let currentDefaults = { ...defaults };
+
+/**
+ * @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);
+}
 
 /**
  * Initialize everything in document
  * - This will only initialize elements once, it is safe to call on page changes
  */
 export function init() {
-  // switch to light theme for printing
-  document.addEventListener(getName("beforePrint"), () => printSetup());
-  // switch back to original theme after printing
-  document.addEventListener(getName("afterPrint"), () => printTearDown());
-  // document.addEventListener(getName("pageModified"), () => setup());
-  setup();
+  initializer.init({
+    events: ["pageModified"],
+    withData: true,
+    setup({ element, data, initialize }) {
+      setupToggle(element, data);
+      initialize();
+    }
+  });
 }
 
-export function setup(context = document) {
-  const body = context.querySelector("[data-site-theme]");
-  // Initial theme on load
-  setupTheme(body);
-  // Add toggle event listener to buttons
-  // @daniel add the init attribute
-  const elements = context.querySelectorAll(attrSelectorInitial("trigger"));
-  elements.forEach(element => {
-    element.setAttribute(attrs.init, "");
-    element.addEventListener("click", () => {
-      changeTheme(body);
+/**
+ * Sets up a single toggle
+ * @param {HTMLElement} toggle A toggle to be setup
+ */
+export function setupToggle(toggle, userOptions) {
+  const options = Object.assign({}, defaults, userOptions);
+
+  if (!checkToggleProps(options)) {
+    console.error(`Missing a required option: ${ requiredToggleProps.join(", ") }`);
+    return;
+  }
+
+  const group = options.group;
+  const ctx = { toggle, options };
+  const initialKey = resolveInitial(options);
+
+  if (!initialKey) {
+    console.error("Unable to resolve initial key");
+    return;
+  }
+  
+  setState(initialKey, ctx);
+
+  toggle.addEventListener("click", onToggleClick);
+
+  // Remotes listeners are attached initially and then we also 
+  // update them vs toggles which would be updated by the main pageModified 
+  // event in init
+  attachRemotes();
+  document.addEventListener(getName("pageModified"), attachRemotes);
+
+  /**
+   * Instance function to get the next theme in cycle
+   */
+  function toggleState(event) {
+    const targets = getElements(options.target);
+    const lastKey = targets[0].dataset.uluThemeToggleState;
+    const key = getNextThemeKey(lastKey, options);
+    if (!key) {
+      console.error("Issue getting next theme key");
+      return;
+    } 
+    setState(key, { ...ctx, event });
+  }
+
+  /**
+   * Handler for click for both toggle and remote toggles
+   */
+  function onToggleClick(event) {
+    toggleState(event);
+  }
+
+  /**
+   * Utility to attach remote handlers
+   * - Used initially and when page is modified
+   */
+  function attachRemotes() {
+    if (!group) return;
+    const remotes = queryRemotesInitial(group);
+    remotes.forEach(remote => {
+      remote.addEventListener("click", onToggleClick);
+      initializer.initializeElement(remote);
     });
-  });
-  // Initial icon setup
-  changeIcons();
+  }
+
+  /**
+   * This only cleans up remotes that are still in DOM
+   * - For ones that have been removed we don't store any references to them 
+   */
+  function cleanupRemotes() {
+    if (!group) return;
+    const remotes = queryRemotesInitial(group);
+    remotes.forEach(remote => {
+      remote.removeEventListener("click", onToggleClick);
+      remote.removeAttribute(attrInit, "");
+    });
+  }
+
+  /**
+   * Function to cleanup listeners and remove init attributes
+   */
+  function destroy() {
+    toggle.removeEventListener("click", onToggleClick);
+    toggle.removeAttribute(attrInit, "");
+    cleanupRemotes();
+    document.removeEventListener(getName("pageModified"), attachRemotes);
+  }
+
+  return { 
+    destroy, 
+    toggle, 
+    options, 
+    toggleState,
+    setState(themeKey) {
+      setState(themeKey, ctx);
+    }
+  };
 }
 
+
+
 /**
- * 
- * @param {Element} body Sets up initial theme on load based on user preference.
+ * Change the state of target/toggle
  */
-function setupTheme(body) {
-  const sitePreference = localStorage.getItem("data-theme");
-  const machinePreference = window.matchMedia && window.matchMedia(`(prefers-color-scheme: ${defaultThemeInverse})`).matches;
-  if(sitePreference && sitePreference != currentTheme){
-    // Check if local storage has site specific preference. And that preference is not the default.
-    changeTheme(body);
-  } else if (machinePreference) {
-    // Check if user system preference differs from default theme.
-    changeTheme(body);
-  } 
+function setState(key, ctx) {
+  if (!key) {
+    console.error("Missing key");
+    return;
+  }
+
+  const { toggle, options } = ctx;
+  const { themes, group } = options;
+  const elements = {
+    targets: getElements(options.target),
+    toggles: [toggle, ...(group ? queryRemotes(group) : [])]
+  };
+
+  if (!elements.targets.length || !elements.toggles.length) {
+    console.error("Issue setting state, couldn't find needed elements", elements);
+    return;
+  }
+
+  const theme = themes[key];
+  const otherThemes = getOtherThemes(key, themes);
+  const stateCtx = { 
+    ...ctx, 
+    key,
+    elements, 
+    theme, 
+    otherThemes 
+  };
+
+  if (options.debug) {
+    initializer.log("Set state context", stateCtx);
+  }
+  
+  // Prepare classes to remove
+  const otherTargetClasses = concatThemeClasses(otherThemes, "targetClass");
+  const otherIconClasses = concatThemeClasses(otherThemes, "iconClass"); 
+
+  // Update all targets
+  elements.targets.forEach(element => {
+    element.setAttribute(attrState, key);
+    element.classList.remove(...otherTargetClasses);
+    element.classList.add(...resolveClasses(theme.targetClass));
+  });
+
+  // Update all toggles and inner children
+  elements.toggles.forEach(element => {
+    const label = element.querySelector(attrSelectorLabel);
+    const icon = element.querySelector(attrSelectorIcon);
+    if (label) {
+      label.textContent = theme.label;
+    }
+    if (icon) {
+      icon.classList.remove(...otherIconClasses);
+      icon.classList.add(...resolveClasses(theme.iconClass));
+    }
+    element.setAttribute(attrState, key);
+  });
+
+  // Optional callback if user want to set other things (ie. data-theme or something)
+  if (options.onChange) {
+    options.onChange(stateCtx);
+  }
+
+  if (options.savePreference) {
+    localStorage.setItem(getStorageKey(options), key);
+  }
 }
 
 /**
- * 
- * @param {Element} body Changes the theme of the body.
+ * Function determines what the initial state is
+ * - Check OS preference, saved preference, or initialState depending on options
+ * @return {String} The resolved initial theme's key
  */
-function changeTheme(body) {
-  let newTheme;
-  let oldTheme;
-  if (body.classList.contains(options.darkTheme)) {
-    oldTheme = options.darkTheme;
-    newTheme = options.lightTheme;
-  } else if (body.classList.contains(options.lightTheme)) {
-    oldTheme = options.lightTheme;
-    newTheme = options.darkTheme;
+function resolveInitial(options) {
+  const { savePreference, checkMediaQuery, themes, initialState } = options;
+  const storageKey = getStorageKey(options);
+  const saved = when(savePreference, () => localStorage.getItem(storageKey));
+  const mediaQueryPreference = when(checkMediaQuery, () => getMatchingThemeQuery(themes));
+  const resolved = saved || mediaQueryPreference || initialState;
+
+  if (options.debug) {
+    initializer.log("Preference Saved", saved);
+    initializer.log("Media Query Preference", mediaQueryPreference);
+    initializer.log("Initial State:", initialState);
+  }
+
+  if (!resolved) {
+    initializer.logError("Failed to resolve initial theme (pass 'initialState' to options)");
   }
-  body.classList.remove(oldTheme);
-  body.classList.add(newTheme);
-  localStorage.setItem("data-theme", newTheme);
-  currentTheme = newTheme;
-  changeIcons();
+  
+  return resolved;
 }
 
 /**
- * 
- * @param {Element} body Used to check for theme.
- * @param {Element} context Used to find the icons.
+ * Check each theme for a matching media query
+ * @return {String} Matching theme key
  */
-function changeIcons(context = document) {
-  const icons = context.querySelectorAll(attrSelectorInitial("icon"));
-  icons.forEach(icon => {
-    if (currentTheme == options.lightTheme) {
-      icon.classList = options.darkIcon;
-    } else {
-      icon.classList = options.lightIcon;
+function getMatchingThemeQuery(themes) {
+  const found = Object.entries(themes).find(([_key, theme]) => {
+    if (theme.mediaQuery) {
+      return window.matchMedia(theme.mediaQuery).matches;
     }
   });
+  // Return just the key
+  return found ? found[0] : null;
 }
 
-// run on beforeprint event
-function printSetup() {
-  const body = document.querySelector("body"); 
-  if (body.classList.contains(options.darkTheme)) {
-    body.classList.remove(options.darkTheme);
-    body.classList.add(options.lightTheme);
-  }
+/**
+ * Get the next key in the themes based on the currentKey
+ */
+function getNextThemeKey(activeKey, options) {
+  const { themes } = options;
+  const keys = Object.keys(themes);
+  const index = keys.findIndex(theme => theme === activeKey);
+  // If not found return first, else calculate next index (wrapping)
+  const nextIndex = index === -1 ? 0 : (index + 1) % keys.length;
+  return keys[nextIndex];
 }
 
-// run on afterprint event
-function printTearDown() {
-  const body = document.querySelector("body"); 
-  if (!body.classList.contains(currentTheme)) {
-    body.classList.remove(options.lightTheme);
-    body.classList.add(options.darkTheme);
-  }
+/**
+ * Get all other theme object except the current
+ */
+function getOtherThemes(currentKey, themes) {
+  const all = Object.entries(themes);
+  return all.filter(([key]) => key !== currentKey).map(([_key, value]) => value);
+}
+
+/**
+ * Concatenates multiple class properties into one array
+ */
+function concatThemeClasses(themes, property) {
+  return themes.reduce((acc, theme) => {
+    return acc.concat(resolveClasses(theme[property]));
+  }, []);
+}
+
+/**
+ * Creates the storage key (either prefix or prefix with group name)
+ */
+function getStorageKey(options) {
+  const { storagePrefix, group } = options;
+  return group ? `${ storagePrefix }${ group }` : storagePrefix;
 }

package/js/ui/tooltip.js

@@ -2,46 +2,41 @@
  * @module ui/tooltip
  */
 
+import { ComponentInitializer } from "../utils/system.js";
 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";
 
-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
+ * Tooltip Component Initializer
  */
-export function init() {
-  document.addEventListener(getEventName("pageModified"), setup);
-  setup();
-}
+export const initializer = new ComponentInitializer({ 
+  type: "tooltip", 
+  baseAttribute: "data-ulu-tooltip"
+});
+
+const attrBody = initializer.getAttribute("body");
+const attrSelectorBody = initializer.attributeSelector("body");
+const attrSelectorArrow = initializer.attributeSelector("arrow");
 
 /**
- * Query all popovers on current page and set them up
- * - Use this manually if needed
- * - Won't setup a popover more than once
+ * Initialize default popover
  */
-export function setup() {
-  const triggers = document.querySelectorAll(attrSelectorInitial("trigger"));
-  triggers.forEach(setupTrigger);
-}
-
-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);
+export function init() {
+  initializer.init({
+    events: ["pageModified"],
+    withData: true,
+    setup({ element: trigger, data, initialize }) {
+      const options = typeof data === "object" ? data : {};
+      if (typeof data === "string") {
+        options.content = data;
+      }
+      initialize();
+      (new Tooltip({ trigger }, options));
+    }
+  });
 }
 
 /**
@@ -103,7 +98,7 @@ export class Tooltip {
     template(_config) {
       return `
         <div class="popover popover--tooltip">
-          <div class="popover__inner" ${ attrs.body }>
+          <div class="popover__inner" ${ attrBody }>
           </div>
           <span class="popover__arrow" data-ulu-tooltip-arrow></span>
         </div>
@@ -177,7 +172,7 @@ export class Tooltip {
   createContentElement() {
     const { options } = this;
     const content = createElementFromHtml(options.template(options));
-    const body = content.querySelector(attrSelector("body"));
+    const body = content.querySelector(attrSelectorBody);
     const innerContent = this.getInnerContent();
     if (options.isHtml) {
       body.innerHTML = innerContent;
@@ -190,7 +185,7 @@ export class Tooltip {
     }
     
     this.elements.content = content;
-    this.elements.contentArrow = content.querySelector(attrSelector("arrow"));
+    this.elements.contentArrow = content.querySelector(attrSelectorArrow);
     document.body.appendChild(content);
   }
   attachHandlers() {

package/js/utils/css.js

@@ -0,0 +1,13 @@
+/**
+ * @module utils/css
+ */
+
+/**
+ * Generates a CSS custom property name with a given prefix.
+ * @param {string} prefix The prefix to apply to the custom property name.
+ * @param {string} propertyName The base name of the custom property.
+ * @returns {string} The fully formed CSS custom property name (e.g., "--prefix-propertyName").
+ */
+export function getCustomProperty(prefix, propertyName) {
+  return `--${prefix}-${propertyName}`;
+}

package/js/utils/dom.js

@@ -5,6 +5,18 @@
 
 export const regexJsonString = /^[{\[][\s\S]*[}\]]$/;
 
+/**
+ * Converts a data attribute name to its corresponding dataset property name.
+ * @param {string} dataAttribute - The data attribute name (e.g., "data-ulu-dialog").
+ * @returns {string} - The dataset property name (e.g., "uluDialog").
+ */
+export function dataAttributeToDatasetKey(attribute) {
+  // Remove "data-" prefix then convert kebab-case to camelCase
+  return attribute
+    .replace(/^data-/, "")
+    .replace(/-([a-z])/g, (_match, letter) => letter.toUpperCase());
+}
+
 /**
  * Get an elements JSON dataset value
  * @param {Node} element 
@@ -98,6 +110,7 @@ export function setPositionClasses(parent, classes = {
  * 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
+ * @return {HTMLElement} The element or null if not found
  */
 export function getElement(target, context = document) {
   if (typeof target === "string") {
@@ -105,18 +118,70 @@ export function getElement(target, context = document) {
   } else if (target instanceof Element) {
     return target;
   } else {
-    console.warn("Unable to getElement()", target);
+    console.warn("getElement: Invalid target type (expected String/Node)", target);
     return null;
   }
 } 
 
+/**
+ * Resolve a target to Elements
+ * @param {String|Node} target The selector or node/element
+ * @param {Object} context [document] The context to query possible selectors from
+ * @return {Array} The elements or null if not found
+ */
+export function getElements(target, context = document) {
+  if (typeof target === "string") {
+    return [...context.querySelectorAll(target)];
+  } else if (target instanceof Element) {
+    return [target];
+  } else if (Array.isArray(target) || target instanceof NodeList) {
+    return [...target];
+  } else {
+    console.warn("getElement: Invalid target type (expected String/Node/Array/Node List)", target);
+    return null;
+  }
+} 
+
+/**
+ * Resolves a class input (string or array) into a consistent array of class names.
+ * @param {string|string[]} input - The class input, which can be a string, an array of strings, or any other value.
+ * @returns {string[]} An array of class names. Returns an empty array for invalid or falsy input.
+ * @example
+ * resolveClassArray("fas fa-check  my-class"); // Returns ["fas", "fa-check", "my-class"]
+ * resolveClassArray(["another-class", "yet-another-class"]); // Returns ["another-class", "yet-another-class"]
+ * resolveClassArray("single-class"); // Returns ["single-class"]
+ */
+export function resolveClasses(classes) {
+  if (typeof classes === "string") {
+    return classes.split(" ").filter(c => c !== ""); // Split and remove empty strings
+  } else if (Array.isArray(classes)) {
+    return classes;
+  } else if (!classes) {
+      return [];
+  } else {
+    console.warn("resolveClassArray: Invalid class input type.", classes);
+    return [];
+  }
+}
+
 /**
  * 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 {HTMLElement} [element=document.body] -The element that is the child of a scrollable container
+ * @param {Window|HTMLElement} [container=window] - 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;
+  const scrollbarWidth = getScrollbarWidth(element, container);
   element.style.setProperty(propName, `${ scrollbarWidth }px`);
+}
+
+/**
+ * Calculates the width of the scrollbar.
+ *
+ * @param {HTMLElement} [element=document.body] -The element that is the child of a scrollable container
+ * @param {Window|HTMLElement} [container=window] - The container that can be scrolled
+ * @returns {number} The width of the scrollbar in pixels.
+ */
+export function getScrollbarWidth(element = document.body, container = window) {
+  return container.innerWidth - element.clientWidth;
 }