@ulu/frontend 0.1.0-beta.32 → 0.1.0-beta.34

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 

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.32",
+  "version": "0.1.0-beta.34",
   "description": "Modular Sass Theming Library",
   "browser": "js/index.js",
   "main": "index.js",

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
@@ -264,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;
@@ -275,4 +277,4 @@ $containers: (
     width: 100%;
     height: 100%;
   }
-}
+}

package/scss/_utils.scss

@@ -161,6 +161,16 @@ $config: (
   @return $number + string.unquote($unit);
 }
 
+/// Checks if two numbers are the same unit
+/// @param {Number} $number 
+/// @param {String} $other-number 
+/// @return {Boolean} Whether they have the same unit type
+// Could be made into multiple arguments in future if needed 
+
+@function units-match($number, $other-number) {
+  @return math.unit($number) == math.unit($other-number);
+}
+
 /// Reusable merge method 
 /// @param {Map} $original Source map 
 /// @param {Map} $changes Changes to merge into source map
@@ -661,4 +671,36 @@ $config: (
 
 @function is-odd($number) {
   @return not is-even($number);
+}
+
+/// Always returns a map
+/// @param {*} $value The value to check if is map
+/// @return {Map} The $value if it was a map, else empty map
+
+@function ensure-map($value) {
+  @return if(is-map($value), $value, ());
+}
+
+/// Returns true if edge passed is an end (top/bottom)
+/// @param {String} $edge The edge string to test
+/// @return {Boolean} Whether the edge was an end (versus side/x-axis)
+/// @throw If $edge is not a valid value (not top/bottom/left/right)
+
+@function is-end($edge) {
+  @if ($edge == "top" or $edge == "bottom") {
+    @return true;
+  } @else if ($edge == "left" or $edge == "right") {
+    @return false;
+  } @else {
+    @error "Expected side to be top/bottom/left/right, got #{ $edge }";
+  }
+}
+
+/// Returns true if edge passed is an side (left/right)
+/// @param {String} $edge The edge string to test
+/// @return {Boolean} Whether the edge was an side (versus end/y-axis)
+/// @throw If $edge is not a valid value (not top/bottom/left/right)
+
+@function is-side($edge) {
+  @return not is-end($edge);
 }

package/scss/components/_accordion.scss

@@ -120,7 +120,7 @@ $config: (
     & + & {
       $gap: -(get("margin") - get("margin-between"));
       margin-top: $gap;
-      margin-top: calc($gap - 1px);
+      margin-top: calc($gap - get("border-width"));
     }
     &[open], 
     &.is-active  {
@@ -208,7 +208,6 @@ $config: (
   }
   #{ $prefix }--no-borders {
     border: none;
-    margin-bottom: 4rem;
     &[open] > .accordion__summary {
       border-bottom: none;
     }

package/scss/components/_button-verbose.scss

@@ -48,11 +48,11 @@ $-fallbacks: (
 /// @prop {String} title-color [link] Color of the title of the button.
 /// @prop {String} title-color-hover [link-hover] Color of the title of the button when hovered or focused.
 /// @prop {Dimension} title-margin [0.5em] Margin for the button's title.
-/// @prop {Boolean} left-cap [false] Enable left cap style 
-/// @prop {Color} left-cap-color ["link"] The color for the left cap
-/// @prop {color} left-cap-color-hover ["link-hover"] The color for the left cap when the button is hovered
-/// @prop {Number} left-cap-color-hover [0.5rem] Width of the cap
-/// @prop {Number} left-cap-match-radius [true] The cap should have be rounded to match the parent's border radius
+/// @prop {Boolean} cap [false] Enable left cap style 
+/// @prop {Color} cap-side ["left"] The side that gets the cap
+/// @prop {Number} cap-match-radius [true] The cap should have be rounded to match the parent's border radius
+/// @prop {Map} cap-options The options for cap (see element.cap for options)
+/// @prop {Map} cap-options-hover The options for cap when hovered
 
 $config: (
   "background-color" : white,
@@ -69,16 +69,21 @@ $config: (
   "margin" : 1em,
   "margin-inline" : 0.75em,
   "min-width": 20rem,
-  "padding-x": 0.65em,
+  "padding-x": 0.75em,
   "padding-y": 1em,
   "title-color": "link",
   "title-margin" : 0.5em,
   "title-color-hover" : "link-hover",
-  "left-cap" : false,
-  "left-cap-color" : "link",
-  "left-cap-color-hover" : "link-hover",
-  "left-cap-width" : 0.5rem,
-  "left-cap-match-radius" : true
+  "cap" : false,
+  "cap-side" : "left",
+  "cap-match-radius" : true,
+  "cap-options" : (
+    "color" : "link",
+    "size" : 0.5rem,
+  ),
+  "cap-options-hover" : (
+    "color" : "link-hover"
+  ),
 ) !default;
 
 /// Change modules $config
@@ -112,40 +117,30 @@ $config: (
 
 @mixin styles {
   $prefix: selector.class("button-verbose");
+  $padding-x: get("padding-x");
+  $padding-y: get("padding-y");
+  $padding-right: ($padding-x * 2) + 1em;
+  $cap-side: get("cap-side");
+  $cap-defaults: (
+    "border-radius" : if(get("cap-match-radius"), get("border-radius"), 0),
+    "padding-adjust" : if(utils.is-side($cap-side), $padding-x, $padding-y)
+  );
   
   #{ $prefix } {
     text-decoration: none;
     border-radius: get("border-radius");
     box-shadow: get("box-shadow");
     line-height: get("line-height");
-    position: relative;
+    position: relative; // For cap and icon
     display: block;
     margin-bottom: get("margin");
     max-width: 100%;
     width: get("min-width");
     background-color: color.get(get("background-color"));
-    padding: get("padding-y") get("padding-x");
-    padding-right: (get("padding-x") * 2) + 1em;
+    padding: $padding-y $padding-right $padding-y $padding-x;
     color: color.get(get("color"));
     text-align: left;
-    // Add border like cap
-    @if get("left-cap") {
-      padding-left: calc(get("padding-x") + get("left-cap-width"));
-      &::after {
-        content: "";
-        display: block;
-        position: absolute;
-        top: 0;
-        bottom: 0;
-        left: 0;
-        width: get("left-cap-width");
-        background-color: color.get(get("left-cap-color"));
-        @if get("left-cap-match-radius") {
-          border-top-left-radius: get("border-radius");
-          border-bottom-left-radius: get("border-radius");
-        }
-      }
-    }
+
     &:hover {
       color: color.get(get("color-hover"));
       background-color: color.get(get("background-color-hover"));
@@ -160,9 +155,19 @@ $config: (
           color: color.get(get("icon-color-hover"));
         }
       }
-      @if (get("left-cap") and get("left-cap-color-hover")) {
-        &::after {
-          background-color: color.get(get("left-cap-color-hover"));
+    }
+    @if get("cap") {
+      @include element.cap(
+        $side: $cap-side,
+        $options: map.merge($cap-defaults, get("cap-options"))
+      );
+      @if get("cap-options-hover") {
+        &:hover,
+        &:focus {
+          @include element.cap-appearance(
+            $side: $cap-side,
+            $options: get("cap-options-hover")
+          );
         }
       }
     }
@@ -180,7 +185,7 @@ $config: (
   #{ $prefix }__icon {
     position: absolute;
     top: 50%;
-    right: get("padding-x");
+    right: $padding-x;
     transform: translateY(-50%);
     font-size: get("icon-font-size");
     color: color.get(get("icon-color"));