@ulu/frontend 0.1.0-beta.8 → 0.1.0-beta.80

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,155 @@
+/**
+ * @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 } from "@ulu/utils/browser/dom.js";
+import { 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,7 +1,7 @@
 {
   "name": "@ulu/frontend",
-  "version": "0.1.0-beta.8", 
-  "description": "Modular Sass Theming Library",
+  "version": "0.1.0-beta.80",
+  "description": "A versatile SCSS and JavaScript component library offering configurable, accessible components and flexible integration into any project, with SCSS modules suitable for modern JS frameworks.",
   "browser": "js/index.js",
   "main": "index.js",
   "exports": {
@@ -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",
@@ -44,7 +46,18 @@
     "modules",
     "javascript",
     "framework",
-    "mixin"
+    "mixin",
+    "components",
+    "HTML",
+    "frontend framework",
+    "css",
+    "utilities",
+    "design system",
+    "toolkit",
+    "accessibility",
+    "ui",
+    "user interface",
+    "responsive design"
   ],
   "authors": {
     "name": "Joe Scherben, Informatics Studio",
@@ -61,11 +74,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 +92,15 @@
     "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.30",
     "ally.js": "^1.4.1",
     "aria-tablist": "^1.2.2",
-    "@floating-ui/dom": "^1.6.5"
+    "swipe-listener" : "^1.3.0"
   }
 }

package/scss/README.md

@@ -41,6 +41,10 @@
 - Should be written from the user's point of view
   - Use prefixes @see "Module Prefixes" in member names. This will avoid confusion about normal use case. For advanced user importing specific parts would already be familiar with this pattern. 
 
+#### Workaround for syntax highlighting bug
+
+If the syntax highlighting isn't working properly after an example, add an empty line with `///` to workaround that bug
+
 ### Ideas
 
 - How to solve the inability to use standard vars (avoid with)

package/scss/_breakpoint.scss

@@ -4,6 +4,7 @@
 ////
 
 @use "sass:map";
+@use "sass:list";
 @use "utils";
 
 /// Module Settings
@@ -30,8 +31,10 @@ $config: (
 }
 
 /// Get a config option
-/// @example scss Get default breakpoint name
-///   $default: ulu.breakpoint-get("default");
+/// @example scss {compile} Example usage
+///   .test-get {
+///     font-size: ulu.breakpoint-get("base");
+///   }
 /// @param {Map} $name Name of property
 /// @return {*} Property Value
 
@@ -65,6 +68,12 @@ $sizes: (
 }
 
 /// Get all breakpoint sizes
+/// @compiler
+/// @example scss {compile} Example usage
+///   .test-get-sizes {
+///     $sizes: ulu.breakpoint-get-sizes();
+///     height: map.get($sizes, "medium");
+///   }
 /// @return {Map} Map of breakpoints (equivalent to $sizes)
 
 @function get-sizes() {
@@ -73,14 +82,25 @@ $sizes: (
 
 /// Get a specific breakpoint's raw value/size
 /// @param {String} $size The name of the size to get
+/// @compiler
+/// @example scss {compile} Example usage
+///   .test-get-size {
+///     height: ulu.breakpoint-get-size("medium");
+///   }
 /// @return {Number} The sizes value
- 
+
 @function get-size($size) {
   @return utils.require-map-get($sizes, $size, "breakpoint size");
 }
 
 /// Get a specific breakpoint's size's value and optionally specify max to get the ending/max value for a breakpoint
 /// @param {Boolean} $max [false] Get the max value
+/// @compiler
+/// @example scss {compile} Example usage
+///   .test-get-size-value {
+///     height: ulu.breakpoint-get-size-value("medium", true);
+///     max-height: ulu.breakpoint-get-size-value("medium");
+///   }
 /// @return {Number} The value for the given size
 
 @function get-size-value($size, $max: false) {
@@ -94,6 +114,20 @@ $sizes: (
 /// Check if a specific size exist
 /// @param {String} $name The breakpoint size to check if exists
 /// @return {Boolean} 
+/// @example scss {compile} Example usage
+///   .test-exists {
+///     @if(ulu.breakpoint-exists("medium")) {
+///       @include ulu.breakpoint-min("medium") {
+///         padding: 2rem;
+///       }
+///     }
+///     // The below content doesn't print because the size doesn't exist.
+///     @if(ulu.breakpoint-exists("too-large")) {
+///       @include ulu.breakpoint-min("too-large") {
+///         padding: 20000rem;
+///       }
+///     }
+///   }
 
 @function exists($name) {
   $size: map.get($sizes, $name);
@@ -220,7 +254,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,11 +23,17 @@ $palette: (
   "type-tertiary"           : rgb(157, 157, 157),
   "headline"                : inherit,
   "background"              : white,
-  "background-gray"         : #F7F8F7,
+  "background-gray"         : #fafafa,
   "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),
@@ -40,10 +46,10 @@ $palette: (
   "bullet"                  : inherit,
   "control"                 : white,
   "control-hover"           : white,
-  "control-active"           : white,
+  "control-active"          : white,
   "control-border"          : purple,
-  "control-border-hover"       : blue,
-  "control-border-active"       : orange,
+  "control-border-hover"    : blue,
+  "control-border-active"   : orange,
   "control-background"      : purple,
   "control-background-hover": blue,
   "control-background-active": orange,
@@ -95,8 +101,11 @@ $color-classes: (
 @function get($name) {
   // Allow non lookup if the value is already a color (helps with code flow)
   @if (meta.type-of($name) == "string") {
+    $is-keyword: $name == "inherit" or $name == "transparent" or $name == "currentColor";
+    $is-cssvar: string.index($name, "var(") == 1;
+    $is-color-mix: string.index($name, "color-mix(") == 1;
     // Allow custom-properties and keyword inherit/transparent to pass through
-    @if ($name == "inherit" or $name == "transparent" or $name == "currentColor" or string.index($name, "var(") == 1) {
+    @if ($is-keyword or $is-cssvar or $is-color-mix) {
       @return $name;
     // Else look up the color from the palette
     } @else {
@@ -172,7 +181,7 @@ $color-classes: (
   color: get-context-value($name, "color");
 }
 
-/// Lighten a color using the default white by a percentage
+/// Tint (add white) a color using the default white by a percentage
 /// @param {Color, String} $color Color/palette color name to apply to tint
 /// @param {Number} $percentage Percentage
 /// @return {Color}
@@ -183,7 +192,18 @@ $color-classes: (
   @return color.mix(get("white"), get($color), $percentage);
 }
 
-/// Darken a color with the default black by a percentage
+/// Tint (add white) a color using the default white by a percentage (Using color-mix)
+/// - This only works in modern browsers (as of June 2025)
+/// - These match ulu.color-tint() and are designed to accept the same arguments with the same results
+/// @param {Color, String} $color Color or custom property to apply mix to
+/// @param {Number} $percentage Percentage
+/// @return {Color}
+
+@function css-tint($color, $percentage) {
+  @return color-mix(in srgb, get("white") $percentage, get($color) calc(100% - $percentage));
+}
+
+/// Shade (add black) a color with the default black by a percentage
 /// @param {Color, String} $color Color/palette color name to shade
 /// @param {Number} $percentage Percentage to shade
 /// @return {Color}
@@ -194,6 +214,17 @@ $color-classes: (
   @return color.mix(get("black"), get($color), $percentage);
 }
 
+/// Shade (add black) a color using the default white by a percentage (Using color-mix)
+/// - This only works in modern browsers (as of June 2025)
+/// - These match ulu.color-shade() and are designed to accept the same arguments with the same results
+/// @param {Color, String} $color Color or custom property to apply mix to
+/// @param {Number} $percentage Percentage
+/// @return {Color}
+
+@function css-shade($color, $percentage) {
+  @return color-mix(in srgb, get("black") $percentage, get($color) calc(100% - $percentage));
+}
+
 /// Prints all context styles 
 /// @param {String} $with-prop Checks the specific context for a certain prop (has to be truthy)(used for output in helper/base color modules)
 /// @example scss

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
@@ -114,9 +116,10 @@ $rule-margins: (
 
 /// Sets rule margins
 /// @param {Map} $changes Map of changes
+/// @param {String} $merge-mode Merge mode see utils.map-merge() [null|"deep"|"overwrite"]
 
-@mixin set-rule-margins($changes) {
-  $rule-margins: map.merge($rule-margins, $changes) !global;
+@mixin set-rule-margins($changes, $merge-mode: null) {
+  $rule-margins: utils.map-merge($rule-margins, $changes, $merge-mode) !global;
 }
 
 /// Get a rule style
@@ -290,4 +293,107 @@ $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;
+      }
+    }
+  }
+}
+
+/// Add backdrop-filter blur
+/// @param {CssUnit} $amount [get("backdrop-blur")] Amount to blur
+/// 
+@mixin backdrop-filter-blur($amount: get("backdrop-blur")) {
+  backdrop-filter: blur($amount);
+}
+
+/// Accessibly hide focus ring while keeping it when it's required
+@mixin focus-ring-required-only() {
+  &:focus:not(:focus-visible) {
+    outline: none;
+  }
 }

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%;
   }
-}
+}

package/scss/_units.scss

@@ -27,13 +27,14 @@ $config: (
 
 /// Update the units config
 /// @param {Map} $changes A map to merge into the color palette
+/// @param {String} $merge-mode Merge mode see utils.map-merge() [null|"deep"|"overwrite"]
 /// @example scss Setting the error and type color
 ///   @include ulu.units-set((
 ///     "default" : 1.5em
 ///   ));
 
-@mixin set($changes) {
-  $config: map.merge($config, $changes) !global;
+@mixin set($changes, $merge-mode: null) {
+  $config: utils.map-merge($config, $changes, $merge-mode) !global;
 }
 
 /// Get a unit by name (preset) or number (multiplier of base)