@ulu/frontend 0.1.0-beta.3 → 0.1.0-beta.31

package/js/ui/theme-toggle.js

@@ -1,129 +1,370 @@
-// Progressive Enhancement turns select elements into accessible autocomplete fields
+/**
+ * @module ui/theme-toggle
+ */
 
-// import { getName } from "@ulu/frontend/js/events/index.js";
 import { getName } from "../events/index.js";
+import { getDatasetJson, 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",
+/**
+ * Default data attributes
+ */
+export const attrs = {
+  init: "data-ulu-theme-toggle-init",
+  toggle: "data-ulu-theme-toggle",
+  toggleIcon: "data-ulu-theme-toggle-icon",
+  toggleLabel: "data-ulu-theme-toggle-label",
+  toggleRemote: "data-ulu-theme-toggle-remote",
+  state: "data-ulu-theme-toggle-state",
 };
 
+// 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));
+const queryRemotes = group => document.querySelectorAll(
+  `[${ attrs.toggleRemote }="${ group }"]`
+);
+const queryRemotesInitial = group => document.querySelectorAll(
+  `[${ attrs.toggleRemote }="${ group }"]:not([${ attrs.init }])`
+);
+const debugLog = (...msgs) => console.log("Theme Toggle:", ...msgs);
+const requiredToggleProps = ["target"];
+const checkToggleProps = hasRequiredProps(requiredToggleProps);
+const when = (cond, fn) => cond ? fn() : null; // Consider adding as util 
 
-// @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",
+/**
+ * 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());
+  document.addEventListener(getName("pageModified"), setup);
   setup();
 }
 
-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);
+/**
+ * Query and setup all 
+ */
+export function setup() {
+  queryAllInitial("toggle").forEach(setupToggle);
+}
+
+/**
+ * Sets up a single toggle
+ * @param {HTMLElement} toggle A toggle to be setup
+ */
+export function setupToggle(toggle, passedOptions) {
+  const elementOptions = getDatasetJson(toggle, "uluThemeToggle");
+  const options = Object.assign({}, defaults, passedOptions, elementOptions);
+
+  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);
+  toggle.setAttribute(attrs.init, "");
+
+  // 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);
+      remote.setAttribute(attrs.init, "");
     });
-  });
-  // 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(attrs.init, "");
+    });
+  }
+
+  /**
+   * Function to cleanup listeners and remove init attributes
+   */
+  function destroy() {
+    toggle.removeEventListener("click", onToggleClick);
+    toggle.removeAttribute(attrs.init, "");
+    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) {
+    debugLog("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(attrs.state, 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(attrSelector("toggleLabel"));
+    const icon = element.querySelector(attrSelector("toggleIcon"));
+    if (label) {
+      label.textContent = theme.label;
+    }
+    if (icon) {
+      icon.classList.remove(...otherIconClasses);
+      icon.classList.add(...resolveClasses(theme.iconClass));
+    }
+    element.setAttribute(attrs.state, 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) {
+    debugLog("Preference Saved:", saved);
+    debugLog("Media Query Preference:", mediaQueryPreference);
+    debugLog("Initial State:", initialState);
   }
-  body.classList.remove(oldTheme);
-  body.classList.add(newTheme);
-  localStorage.setItem("data-theme", newTheme);
-  currentTheme = newTheme;
-  changeIcons();
+
+  if (!resolved) {
+    console.error("Failed to resolve initial theme (pass 'initialState' to options)");
+  }
+  
+  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/utils/dom.js

@@ -98,6 +98,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,11 +106,52 @@ 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

package/js/utils/font-awesome.js

@@ -0,0 +1,18 @@
+/**
+ * @module settings
+ * @description Utility module for setting up Font Awesome
+ */
+
+import { updateSettings } from "../settings.js";
+
+/**
+ * Sets icon settings to Font Awesome icons
+ */
+export function configureIcons() {
+  updateSettings({
+    iconClassClose: "fas fa-xmark",
+    iconClassDragX: "fas fa-solid fa-grip-lines-vertical",
+    iconClassPrevious: "fas fa-solid fa-chevron-left",
+    iconClassNext: "fas fa-solid fa-chevron-right"
+  });
+}

package/js/utils/index.js

@@ -4,4 +4,5 @@ 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";
+export * as fileSave from "./file-save.js";
+export * as fontAwesome from "./font-awesome.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ulu/frontend",
-  "version": "0.1.0-beta.3", 
+  "version": "0.1.0-beta.31",
   "description": "Modular Sass Theming Library",
   "browser": "js/index.js",
   "main": "index.js",
@@ -30,7 +30,9 @@
     "docs:build:prod": "IS_PRODUCTION=true npx @11ty/eleventy --config=docs.eleventy.js",
     "docs:assets": "vite --config docs.vite.config.js --force",
     "docs:assets:build": "vite build --config docs.vite.config.js",
-    "docs:assets:build:prod": "IS_PRODUCTION=true vite build --config docs.vite.config.js"
+    "docs:assets:build:prod": "IS_PRODUCTION=true vite build --config docs.vite.config.js",
+    "deploy": "npm run build && npm run types && npm run docs:build:prod && npm run docs:assets:build:prod",
+    "deploy:docs": "npm run docs:build:prod && npm run docs:assets:build:prod"
   },
   "repository": {
     "type": "git",
@@ -66,6 +68,7 @@
     "@ulu/vitepress-auto-menus": "^0.0.3",
     "@ulu/vitepress-sassdoc": "^0.0.9",
     "algoliasearch": "^4.23.3",
+    "autoprefixer": "^10.4.16",
     "chokidar": "^3.6.0",
     "eleventy-plugin-nesting-toc": "^1.3.0",
     "fs-extra": "^11.2.0",
@@ -78,14 +81,14 @@
     "sass-embedded": "^1.81.0",
     "sharp": "^0.33.4",
     "svgo": "^3.3.2",
+    "twig": "^1.17.1",
     "typescript": "^5.3.3",
-    "autoprefixer": "^10.4.16",
     "vite": "^5.4.11"
   },
   "dependencies": {
-    "@ulu/utils": "^0.0.17",
+    "@floating-ui/dom": "^1.6.5",
+    "@ulu/utils": "^0.0.20",
     "ally.js": "^1.4.1",
-    "aria-tablist": "^1.2.2",
-    "@floating-ui/dom": "^1.6.5"
+    "aria-tablist": "^1.2.2"
   }
 }

package/scss/_color.scss

@@ -23,10 +23,17 @@ $palette: (
   "type-tertiary"           : rgb(157, 157, 157),
   "headline"                : inherit,
   "background"              : white,
+  "background-gray"         : #F7F8F7,
   "focus"                   : blue,
-  "error"                   : red,
-  "warning"                 : orange,
   "accent"                  : orange,
+  "info"                    : #00bde3,
+  "success"                 : #00a91c,
+  "warning"                 : #ffbe2e,  
+  "danger"                  : #d54309,  
+  "info-background"         : #e7f6f8,
+  "success-background"      : #ecf3ec,
+  "warning-background"      : #faf3d1,
+  "danger-background"       : #f4e3db,
   "selected"                : green,
   "box-shadow"              : rgba(0, 0, 0, 0.349),
   "box-shadow-hover"        : rgba(0, 0, 0, 0.5),

package/scss/_layout.scss

@@ -215,10 +215,7 @@ $containers: (
   $breakpoints: map.get($container, "breakpoints");
   
   $width: map.get($container, "width");
-  // @debug $specific-breakpoint;
-  // @if $specific-breakpoint {
-  //   @debug $container;
-  // }
+
   @if ($width == null) {
     $width: 100%;
   }