@ulu/frontend 0.1.0-beta.1 → 0.1.0-beta.100

package/js/utils/dom.js

@@ -2,53 +2,17 @@
  * @module utils/dom
  */
 
-
-export const regexJsonString = /^[{\[][\s\S]*[}\]]$/;
+import { kebabToCamel } from "@ulu/utils/string.js";
 
 /**
- * Get an elements JSON dataset value
- * @param {Node} element 
- * @param {String} key key in dataset object for element
- * @returns {Object} Empty object or JSON object from dataset
+ * 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 getDatasetJson(element, key) {
-  const passed = element.dataset[key];
-  try {
-    return JSON.parse(passed);
-  } catch (error) {
-    console.error(`Error getting JSON from dataset (${ key }) -- "${ passed }"\n`, element, error);
-    return {};
-  }
+export function dataAttributeToDatasetKey(attribute) {
+  return kebabToCamel(attribute.replace(/^data-/, ""));
 }
 
-/**
- * Get an elements JSON dataset value that could potentially just be a single string
- * - If JSON it will return the object else it will return the value directly
- * @param {Node} element 
- * @param {String} key key in dataset object for element
- * @returns {Object|String} JSON object or current dataset value (string or empty string if no value)
- */
-export function getDatasetOptionalJson(element, key) {
-  const passed = element.dataset[key];
-  if (passed && regexJsonString.test(passed.trim())) {
-    return getDatasetJson(element, key);
-  } else {
-    return passed;
-  }
-}
-
-/**
- * Check if a pointer event x/y was outside an elements bounding box
- */
-export function wasClickOutside(element, event) {
-  const rect = element.getBoundingClientRect();
-  return (event.clientY < rect.top || // above
-    event.clientY > rect.top + rect.height || // below
-    event.clientX < rect.left || // left side
-    event.clientX > rect.left + rect.width); // right side
-}
-
-
 /**
  *   Sets up the positional classes that would come from the equal
  *   height module. Needs to be rerun by user when layout changes
@@ -95,28 +59,23 @@ 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
+ * 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 getElement(target, context = document) {
-  if (typeof target === "string") {
-    return context.querySelector(target);
-  } else if (target instanceof Element) {
-    return target;
+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("Unable to getElement()", target);
-    return null;
+    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
- * @param {Node} container The container that can be scrolled
- * @param {Stirng} propName Custom property to set
- */
-export function addScrollbarProperty(element = document.body, container = window, propName = "--ulu-scrollbar-width") {
-  const scrollbarWidth = container.innerWidth - element.clientWidth;
-  element.style.setProperty(propName, `${ scrollbarWidth }px`);
-}
+}

package/js/utils/font-awesome.js

@@ -0,0 +1,19 @@
+/**
+ * @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",
+    // iconClassDragBoth: "fas fa-solid fa-grip", // Not really any good icons for this (no diagonal arrows, etc)
+    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.1",
-  "description": "Modular Sass Theming Library",
+  "version": "0.1.0-beta.100",
+  "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": {
@@ -27,9 +27,12 @@
     "docs:incremental": "npx @11ty/eleventy --serve --incremental --config=docs.eleventy.js",
     "docs:nogen": "NO_DOC_GEN=true npx @11ty/eleventy --serve --incremental --config=docs.eleventy.js",
     "docs:inspect": "node --inspect-brk ./node_modules/.bin/eleventy --serve --config=docs.eleventy.js",
-    "docs:build": "npx @11ty/eleventy --config=docs.eleventy.js",
+    "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": "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",
@@ -43,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",
@@ -60,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",
@@ -77,16 +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"
-  },
-  "optionalDependencies": {
+    "@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

@@ -35,12 +35,21 @@
 - Modules use simple variable, mixins and function names relative to their module
 - Forwards will make namespacing in the overall ulu packaged module
 - **Module Prefixes:** Modules all get prefixed by parent module ie lib will transform color.set() to color-set(), adding the modules namespace for users that are importing the whole library. It also matches the core modules `map-get()` and when @used `map.get()`
+- Try to avoid "&" selector when possible?
+  - For example with 
+    - .user-scope-selector { .component-example + .component-example { // This can be wrapped externally } }
+    - .user-scope-selector { .component-example { & + & {} } } // This will incorrectly inherit the users outer selector. 
+  - Not crucial (we won't specifically design this way) but we may want to refactor in the future (at least components) so that we write selectors in a more static way so that scoping doesn't interfere
 
 ### Writing Docs
 
 - 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);
@@ -190,7 +224,7 @@ $sizes: (
 ///   @include breakpoints.fromEach($breakpoints) using ($props) {
 ///     width: map.get($props, "width");
 ///   }
-/// @param {String} $breakpoints A map with breakpoints direction will be pulled from each items "direction" property, if direction is missing and no breakpoint will wrap the code
+/// @param {String} $breakpoints A map with breakpoints direction will be pulled from each items "direction" property, if direction is missing no breakpoint will wrap the code (as convention we call the default non-breakpoint direction "default")
 /// @param {String} $options A map with options to change the behavior
 /// @param {Boolean} $options.directionRequired Require direction throw error if missing direction
 
@@ -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/_button.scss

@@ -94,7 +94,7 @@ $config: (
   
 $sizes: (
   "small" : (
-    "padding":        (0.35em 1.5em),
+    "padding":        (0.35em 1em),
     "min-width":      0,
     "icon-size":      2rem,
     "icon-font-size": 1rem
@@ -118,9 +118,9 @@ $styles: (
     "border-color" : transparent,
     "box-shadow" : none,
     "hover" : (
-      "background-color" : "white",
-      "color" : inherit,
-      "border-color" : transparent,
+      "background-color" : "control-background",
+      "color" : "control",
+      "border-color" : "control-border",
     )
   ),
   "outline" : (
@@ -129,7 +129,9 @@ $styles: (
     "border-color" : "rule-light",
     "box-shadow" : none,
     "hover" : (
-      "background-color" : "white",
+      "background-color" : "control-background",
+      "color" : "control",
+      "border-color" : "control-border",
     )
   ),
 ) !default;

package/scss/_color.scss

@@ -20,13 +20,21 @@ $palette: (
   "white"                   : white,
   "type"                    : black,
   "type-secondary"          : rgb(82, 82, 82),
-  "type-tertiary"           : rgb(157, 157, 157),
+  "type-tertiary"           : rgb(125, 125, 125),
+  "type-disabled"           : rgb(160, 160, 160),
   "headline"                : inherit,
   "background"              : white,
+  "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),
@@ -39,10 +47,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,
@@ -94,8 +102,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 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 {
@@ -171,7 +182,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}
@@ -182,7 +193,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}
@@ -193,6 +215,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