@ulu/frontend 0.1.0-beta.19 → 0.1.0-beta.20

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ulu/frontend",
-  "version": "0.1.0-beta.19", 
+  "version": "0.1.0-beta.20", 
   "description": "Modular Sass Theming Library",
   "browser": "js/index.js",
   "main": "index.js",
@@ -30,7 +30,8 @@
     "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",
+    "publish" : "npm run build && npm run types && npm run docs:build:prod && npm run docs:assets:build:prod"
   },
   "repository": {
     "type": "git",

package/scss/components/_basic-hero.scss

@@ -0,0 +1,112 @@
+////
+/// @group basic-hero
+/// Basic styling for a hero
+////
+
+@use "sass:map";
+@use "sass:math";
+@use "sass:meta";
+@use "sass:list";
+
+@use "../breakpoint";
+@use "../selector";
+@use "../utils";
+@use "../typography";
+@use "../color";
+
+// Used for function fallback
+$-fallbacks: (
+  "main-max-width" : (
+    "function" : meta.get-function("get", false, "typography"),
+    "property" : "max-width"
+  ),
+  "main-min-width" : (
+    "function" : meta.get-function("get", false, "typography"),
+    "property" : "max-width-small"
+  ),
+);
+
+/// Module Settings
+/// @type Map
+/// @prop {CssValue} text-align [center] Alignment of text within hero.
+/// @prop {Color} background-color ["color-hero-background"] Background color of the hero
+
+$config: (
+  "background-color" : "background-gray",
+  "padding-top": 3rem,
+  "padding-bottom" : 2rem,
+  "gap" : (4rem 2rem),
+  "main-max-width" : true,
+  "main-min-width" : true,
+  "media-max-width" : 20rem,
+  "media-vertical-align" : center
+) !default;
+
+/// Change modules $config
+/// @param {Map} $changes Map of changes
+/// @example scss
+///   @include ulu.component-basic-hero-set(( "property" : value ));
+
+@mixin set($changes) {
+  $config: map.merge($config, $changes) !global;
+}
+
+/// Get a config option
+/// @param {Map} $name Name of property
+/// @example scss
+///   @include ulu.component-basic-hero-get("property");
+
+@function get($name) {
+  $value: utils.require-map-get($config, $name, "basic-hero [config]");
+  @return utils.function-fallback($name, $value, $-fallbacks);
+}
+
+/// Prints component styles
+/// @example scss
+///  @include ulu.component-basic-hero-styles();
+
+@mixin styles {
+  $prefix: selector.class("basic-hero");
+
+  #{ $prefix } {
+    background-color: color.get(get("background-color")); 
+  }
+  #{ $prefix }__content {
+    display: flex;
+    align-items: stretch;
+    flex-wrap: wrap;
+    justify-content: space-between;
+    gap: get("gap"); 
+    padding-top: get("padding-top");
+    padding-bottom: get("padding-bottom");
+  }
+  #{ $prefix }__content-main {
+    $min-width: if(get("main-min-width"), get("main-min-width"), get("main-max-width"));
+    // Using max/min-width so that we don't need to add selectors to change flex-basis
+    // when centered. Using flex-basis: 0 to allow flexbox to decide the items width
+    // allows it to expand/shrink within. min(100%... Never larger than parent
+    min-width: min(100%, $min-width); 
+    max-width: get("main-max-width");
+    flex-shrink: 1;
+    flex-grow: 1;
+    flex-basis: 0;
+  }
+  #{ $prefix }__content-media {
+    display: flex;
+    align-items: center;
+    align-self: get("media-vertical-align");
+    justify-content: center;
+    flex: 0 0 auto; 
+    width: min(100%, get("media-max-width"));
+  }
+
+  // Modifiers
+  #{ $prefix }--center {
+    #{ $prefix }__content {
+      flex-direction: column;
+      flex-wrap: nowrap;
+      text-align: center;
+      align-items: center;
+    }
+  }
+}

package/scss/components/_form-theme.scss

@@ -15,8 +15,8 @@
 
 /// Module Settings
 /// @type Map
-/// @prop {} color [inherit]
-/// @prop {} color-placeholder ["type-tertiary"]
+/// @prop {CssValue} color [inherit] Color of the text of the form.
+/// @prop {CssValue} color-placeholder ["type-tertiary"] Color for the placeh
 /// @prop {} drupal [false]
 /// @prop {} error-color ["danger"]
 /// @prop {} error-highlight-color [rgb(251, 242, 242)]