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

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,82 @@ 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;
   }
 } 
 
 /**
- * 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 {Stirng} propName Custom property to set
+ * 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 {object} options - Configuration options.
+ * @param {HTMLElement} [options.scrollableChild=document.body] - An element that is a child of a scrollable container (used for width calculation).
+ * @param {Window|HTMLElement} [options.container=window] - The container that can be scrolled (used for width calculation).
+ * @param {HTMLElement} [options.propertyElement=document.documentElement] - The element to which the custom property will be added. Defaults to document.documentElement for :root access.
+ * @param {string} [options.propName="--ulu-scrollbar-width"] - The name of the custom property to set.
+ */
+export function addScrollbarProperty(options) {
+  const defaults = {
+    scrollableChild: document.body,
+    container: window,
+    propertyElement: document.documentElement,
+    propName: "--ulu-scrollbar-width",
+  };
+
+  const config = { ...defaults, ...options };
+  const { scrollableChild, container, propertyElement, propName } = config;
+
+  const scrollbarWidth = getScrollbarWidth(scrollableChild, container);
+  propertyElement.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 addScrollbarProperty(element = document.body, container = window, propName = "--ulu-scrollbar-width") {
-  const scrollbarWidth = container.innerWidth - element.clientWidth;
-  element.style.setProperty(propName, `${ scrollbarWidth }px`);
+export function getScrollbarWidth(element = document.body, container = window) {
+  return container.innerWidth - element.clientWidth;
 }

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/js/utils/system.js

@@ -0,0 +1,154 @@
+/**
+ * @module utils/system
+ * @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, dataAttributeToDatasetKey } from "./dom.js";
+import { getName } from "../events/index.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
+ */
+export class ComponentInitializer {
+  static defaults = {
+    type: null,
+    baseAttribute: null
+  };
+  static requiredOptions = [
+    "type",
+    "baseAttribute"
+  ];
+  static hasRequiredOptions = hasRequiredProps(
+    ComponentInitializer.requiredOptions
+  );
+
+  /**
+   * Create a new instance of ComponentInitializer
+   * @param {Object} options Options for configuring the component initializer.
+   * @param {String} options.type Type of component (used for logs).
+   * @param {String} options.baseAttribute Prefix and base attribute name (used for base attribute and further element attribute names).
+   */
+  constructor(options) {
+    if (!ComponentInitializer.hasRequiredOptions(options)) {
+      throw new Error(
+        `Missing a required options: ${ ComponentInitializer.requiredOptions.join(", ") }`
+      );
+    }
+    this.options = Object.assign({}, ComponentInitializer.defaults, options);
+    this.logTitle = `ULU: ${ this.options.type }:\n`;
+  }
+  /**
+   * Initializes the component based on the provided configuration.
+   * @param {Object} config The initialization configuration.
+   * @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 {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 
+    // event made alterations  outside of itself
+    if (config.events?.length) {
+      config.events.forEach(name => {
+        document.addEventListener(getName(name), () => this.setupElements(config));
+      });
+    }
+  }
+  /**
+   * Processes the elements based on the provided configuration.
+   * @param {object} config The initialization configuration.
+   * @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) {
+    const { setup, key, withData, context } = config;
+    const elementsWithData = this.queryAllInitial(key, withData, context);
+    elementsWithData.forEach(elementWithData => setup(elementWithData, this));
+  }
+  /**
+   * Get an attribute name
+   * @param {String} key Optional key, if no key will return baseAttribute if key will return key added to base
+   * @returns {String} String like data-ulu-dialog or data-ulu-dialog-element
+   */
+  getAttribute(key) {
+    const { baseAttribute }  = this.options;
+    return key ? `${ baseAttribute }-${ key }` : `${ baseAttribute }`;
+  }
+  /**
+   * Create an attribute selector
+   * @param {String} key Optional key (see getAttribute)
+   */
+  attributeSelector(key) {
+    return `[${ this.getAttribute(key) }]`;
+  }
+  /**
+   * Create an attribute selector for initial
+   * @return {String}
+   */  
+  attributeSelectorInitial(key) {
+    return `${ this.attributeSelector(key) }:not([${ this.getAttribute("init") }])`
+  }
+  /**
+   * Queries all main elements of a component that have not been initialized and extracts their data attributes.
+   * @param {HTMLElement} context The context to query within.
+   * @param {Boolean} withData Include dataset from element (as optional JSON)
+   * @param {Node} context Element to query elements from
+   * @returns {Array<{element: HTMLElement, data: object, initialize: Function}>} An array of objects containing the elements, their data, and convenience function initialize() which when called will set the init attribute on the element
+   */
+  queryAllInitial(key, withData, context = document) {
+    const elements = [ ...context.querySelectorAll(this.attributeSelectorInitial(key)) ];
+    return elements.map((element) => ({
+      element,
+      data: withData ? this.getData(element, key) : null,
+      initialize: () => this.initializeElement(element)
+    }));
+  }
+  /**
+   * Sets the init attribute on an element, marking it as initialized.
+   * @param {HTMLElement} element The element to initialize.
+   */
+  initializeElement(element) {
+    element.setAttribute(this.getAttribute("init"), "");
+  }
+  /**
+   * Get an elements dataset value as JSON or other value
+   * @return {*} The value of the dataset, if JSON will return object else will return string value or undefined
+   */
+  getData(element, key) {
+    const datasetKey = dataAttributeToDatasetKey(this.getAttribute(key));
+    return getDatasetOptionalJson(element, datasetKey);
+  }
+  /**
+   * Will output namespaced console logs for the given initializer
+   */
+  log(...msgs) {
+    console.log(this.logTitle, ...msgs);
+  }
+  /**
+   * Will output namespaced console warnings for the given initializer
+   */
+  warn(...msgs) {
+    console.warn(this.logTitle, ...msgs);
+  }
+  /**
+   * Will output namespaced console error for the given initializer
+   */
+  logError(...msgs) {
+    console.error(this.logTitle, ...msgs);
+  }
+}
+
+/**
+ * Class serves as a base for representing individual occurrences of a UI component, providing a consistent structure for each
+ */
+export class ComponentInstance {
+
+} 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ulu/frontend",
-  "version": "0.1.0-beta.4", 
+  "version": "0.1.0-beta.41",
   "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",
@@ -61,11 +63,12 @@
     "@11ty/eleventy-plugin-syntaxhighlight": "^5.0.0",
     "@fortawesome/fontawesome-free": "^6.5.2",
     "@ulu/markdown-output-utils": "^0.0.6",
-    "@ulu/sassdoc-to-markdown": "^0.0.15",
+    "@ulu/sassdoc-to-markdown": "^0.0.16",
     "@ulu/vite-config-cms-theme": "^0.0.10",
     "@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/_breakpoint.scss

@@ -4,6 +4,7 @@
 ////
 
 @use "sass:map";
+@use "sass:list";
 @use "utils";
 
 /// Module Settings
@@ -30,8 +31,12 @@ $config: (
 }
 
 /// Get a config option
-/// @example scss Get default breakpoint name
-///   $default: ulu.breakpoint-get("default");
+/// @compiler
+///   @use "index" as ulu;
+/// @example scss {compile} Example usage
+///   .test-get {
+///     font-size: ulu.breakpoint-get("base");
+///   }
 /// @param {Map} $name Name of property
 /// @return {*} Property Value
 
@@ -66,6 +71,14 @@ $sizes: (
 
 /// Get all breakpoint sizes
 /// @return {Map} Map of breakpoints (equivalent to $sizes)
+/// @compiler
+///   @use "index" as ulu;
+///   @use "sass:map";
+/// @example scss {compile} Example usage
+///   .test-get {
+///     $sizes: ulu.breakpoint-get-sizes();
+///     height: map.get($sizes, "medium");
+///   }
 
 @function get-sizes() {
   @return $sizes;
@@ -220,7 +233,7 @@ $sizes: (
 /// - Breakpoints always min-width (upwards) for javascript setup
 
 @mixin embed-for-scripts() {
-  &:before {
+  &::before {
     display: none;
     content: get("null-name");
     @each $size, $breakpoint in $sizes {

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/_element.scss

@@ -69,6 +69,8 @@ $config: (
   "ul-list-style-type":               disc,
   "ul-list-style-type-2":             circle,
   "ul-list-style-type-3":             square,
+  "cap-color" :                       "accent",
+  "cap-size" :                        5px
 ) !default;
 
 /// Rule style map, redefine defaults or add to
@@ -290,4 +292,93 @@ $rule-margins: (
     white-space: normal;
     width: auto;
   }
+}
+
+
+/// Layout utility to add a colored bar (cap) to an element's edge, positioned over the element and its border
+/// - You need to set position (relative, fixed) on parent
+/// @param {String} $side The side to place the cap (top, bottom, left, right)
+/// @param {Map} $options Options for the appearance of the cap
+/// @param {Color} $options.color [$config.cap-color] The color for the end cap
+/// @param {Number} $options.size [$config.cap-size] The width/height of the cap
+/// @param {Number} $options.offset [0] A positive number of the amount the cap should extend outside the box (to account for border-width) 
+/// @param {Number} $options.border-radius [null] An optional border-radius to apply to the outward-facing edges of the cap (used to match parent)
+/// @param {Boolean} $before [true] Whether or not to use the ::before element (if not uses :after)
+
+@mixin cap(
+  $side,
+  $options: (),
+  $before: true,
+) {
+  $defaults: (
+    "color" : get("cap-color"), 
+    "size" : get("cap-size"), 
+    "offset" : 0, 
+    "color-hover" : null,
+    "border-radius" : null,
+    "padding-adjust" : null,
+  );
+  $config: map.merge($defaults, $options);
+  $element: if($before, "::before", "::after");
+
+  &#{ $element } {
+    content: "";
+    position: absolute;
+    display: block;
+  }
+
+  @include cap-appearance($side, $config, $before);
+}
+
+
+
+/// Provides the appearance styles for a given cap
+/// - If an option is not provided it won't be output
+/// - This is used to update the caps styling (states, modifiers, etc)
+/// @param {String} $side The side to place the cap (top, bottom, left, right)
+/// @param {Map} $options Options for the appearance of the cap (see options from element.cap)
+/// @param {Boolean} $before Whether or not to use the ::before element (if not uses :after)
+
+@mixin cap-appearance(
+  $side,
+  $options: (),
+  $before: true
+) {
+  $element: if($before, "::before", "::after");
+  $size: map.get($options, "size");
+  $offset: map.get($options, "offset");
+  $border-radius: map.get($options, "border-radius");
+  $padding-adjust: map.get($options, "padding-adjust");
+  
+  $end: $side == "top" or $side == "bottom";
+  $position: if($offset, 0 - $offset, null);
+
+  @if ($padding-adjust and $size) {
+    padding-#{ $side }: calc($padding-adjust + $size);
+  }
+
+  &#{ $element } {
+    background-color: color.get(map.get($options, "color"));
+    #{ $side }: $position;
+
+    @if $end {
+      left: $position;
+      right: $position;
+      height: $size;
+    } @else {
+      top: $position;
+      bottom: $position;
+      width: $size;
+    }
+    
+    @if $border-radius {
+      @if $end {
+        border-#{ $side }-left-radius: $border-radius;
+        border-#{ $side }-right-radius: $border-radius;
+      } @else {
+        border-top-#{ $side }-radius: $border-radius;
+        border-bottom-#{ $side }-radius: $border-radius;
+      }
+    }
+  }
 }

package/scss/_layout.scss

@@ -7,6 +7,7 @@
 @use "sass:meta";
 @use "utils";
 @use "breakpoint";
+@use "color";
 
 /// Module Settings
 /// @type Map
@@ -215,10 +216,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%;
   }
@@ -243,14 +241,14 @@ $containers: (
 /// Prints clearfix styles
 
 @mixin clearfix() {
-  &:before,
-  &:after {
+  &::before,
+  &::after {
     content: "";
     display: table;
     flex-basis: 0; // Flexbox, clear fix for pseudo elements in Safari
     order: 1;
   }
-  &:after { 
+  &::after { 
     clear: both; 
   }
 }
@@ -267,6 +265,7 @@ $containers: (
 /// Layout utility for absolute (zero on all sides)
 /// - Probably helpful for gzip if we use this when these exact styles are needed
 ///   so they are identical for compression
+/// @param {Boolean} $set-size [false] Whether or not to use sizes to fill the space (height/width 100%) versus setting bottom and right to 0)
 @mixin absolute-fill($set-size: false) {
   position: absolute;
   top: 0;
@@ -278,4 +277,4 @@ $containers: (
     width: 100%;
     height: 100%;
   }
-}
+}