@ulu/frontend 0.1.0-beta.99 → 0.2.0-beta.10

package/lib/js/utils/index.js

@@ -0,0 +1,63 @@
+/**
+ * @module utils
+ * @description
+ * Public API for the utility modules.
+ *
+ * This file re-exports the internal implementations from the `utils` directory
+ * with new names where appropriate, defining the public-facing API for the
+ * library bundle.
+ *
+ * For internal library usage, import directly from the specific file within
+ * the `utils` directory (e.g., `import { ... } from './dom.js'`).
+ *
+ * @internal
+ *
+ * Naming Convention
+ * To ensure tree-shaking works correctly while avoiding name collisions in the
+ * final library, the following naming convention is used for re-exporting:
+ *
+ * 1. Generic Names: Functions with highly generic names (e.g., `log`, `set`, `defaults`)
+ *    MUST be prefixed with a name derived from their module to prevent conflicts.
+ *    Example: `export { log as classLoggerLog } from "./class-logger.js";`
+ *
+ * 2. Descriptive Names: Functions with specific, descriptive names that are unlikely
+ *    to cause conflicts (e.g., `newId`, `createFloatingUi`, `configureIcons`)
+ *    can be re-exported directly without a prefix for better readability.
+ *    Example: `export { newId } from "./id.js";`
+ */
+
+export {
+  set as classLoggerSet,
+  log as classLoggerLog,
+  logWarning as classLoggerLogWarning,
+  logError as classLoggerLogError
+} from "./class-logger.js";
+
+export {
+  dataAttributeToDatasetKey,
+  setPositionClasses,
+  resolveClasses
+} from "./dom.js";
+
+export { 
+  FileSave 
+} from "./file-save.js";
+
+export {
+  defaults as floatingUiDefaults,
+  createFloatingUi
+} from "./floating-ui.js";
+
+export { 
+  configureIcons as fontAwesomeConfigureIcons
+} from "./font-awesome.js";
+
+export {
+  newId,
+  ensureId
+} from "./id.js";
+
+export {
+  pauseVideos as youtubePauseVideos,
+  prepVideos as youtubePrepVideos
+} from "./pause-youtube-video.js";

package/{scss → lib/scss}/_breakpoint.scss

@@ -72,7 +72,7 @@ $sizes: (
 /// @example scss {compile} Example usage
 ///   .test-get-sizes {
 ///     $sizes: ulu.breakpoint-get-sizes();
-///     height: map.get($sizes, "medium");
+///     content: map.get($sizes, "medium");
 ///   }
 /// @return {Map} Map of breakpoints (equivalent to $sizes)
 
@@ -85,7 +85,7 @@ $sizes: (
 /// @compiler
 /// @example scss {compile} Example usage
 ///   .test-get-size {
-///     height: ulu.breakpoint-get-size("medium");
+///     content: ulu.breakpoint-get-size("medium");
 ///   }
 /// @return {Number} The sizes value
 
@@ -98,8 +98,8 @@ $sizes: (
 /// @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");
+///     content: ulu.breakpoint-get-size-value("medium", true);
+///     content: ulu.breakpoint-get-size-value("medium");
 ///   }
 /// @return {Number} The value for the given size
 

package/{scss → lib/scss}/_button.scss

@@ -84,6 +84,7 @@ $config: (
   "transition-enabled":      true,
   "transition-duration":     200ms,
   "transition-properties":   (border-color, background-color, color, box-shadow),
+  "button-icon-offset":      true,
 ) !default;
   
 /// Button sizes

package/{scss → lib/scss}/_color.scss

@@ -16,44 +16,48 @@
 /// @type map  
 
 $palette: (
-  "black"                   : black,
-  "white"                   : white,
-  "type"                    : black,
-  "type-secondary"          : rgb(82, 82, 82),
-  "type-tertiary"           : rgb(125, 125, 125),
-  "type-disabled"           : rgb(160, 160, 160),
-  "headline"                : inherit,
-  "background"              : white,
-  "background-gray"         : #fafafa,
-  "focus"                   : blue,
-  "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),
-  "rule"                    : gray,
-  "rule-light"              : lightgray,
-  "link"                    : blue,
-  "link-hover"              : darkblue,
-  "link-active"             : darkblue,
-  "link-visited"            : purple,
-  "bullet"                  : inherit,
-  "control"                 : white,
-  "control-hover"           : white,
-  "control-active"          : white,
-  "control-border"          : purple,
-  "control-border-hover"    : blue,
-  "control-border-active"   : orange,
-  "control-background"      : purple,
-  "control-background-hover": blue,
-  "control-background-active": orange,
+  "black":                      black,
+  "white":                      white,
+  "type":                       black,
+  "type-secondary":             rgb(82, 82, 82),
+  "type-tertiary":              rgb(125, 125, 125),
+  "type-disabled":              rgb(160, 160, 160),
+  "headline":                   inherit,
+  "background":                 white,
+  "focus":                      blue,
+  "accent":                     orange,
+  "info":                       #00bde3,
+  "success":                    #00a91c,
+  "warning":                    #ffbe2e,
+  "danger":                     #d54309,
+  "info-background":            #e7f6f8,
+  "success-background":         #ecf3ec,
+  "warning-background":         #faf3d1,
+  "danger-background":          #f4e3db,
+  // Used for background of elements that are placeholder or that have no value (think charts)
+  "placeholder-background":     #e2e2e2,
+  "placeholder-background-alt": #bababa,
+  "selected":                   green,
+  "box-shadow":                 rgba(0, 0, 0, 0.349),
+  "box-shadow-hover":           rgba(0, 0, 0, 0.5),
+  "rule":                       gray,
+  "rule-light":                 lightgray,
+  "link":                       blue,
+  "link-hover":                 darkblue,
+  "link-active":                darkblue,
+  "link-visited":               purple,
+  "bullet":                     inherit,
+  "control":                    white,
+  "control-hover":              white,
+  "control-active":             white,
+  "control-border":             purple,
+  "control-border-hover":       blue,
+  "control-border-active":      orange,
+  "control-background":         purple,
+  "control-background-hover":   blue,
+  "control-background-active":  orange,
+  // Like accent indicator like things in ui (progress, etc)
+  "indicator" :                 #5050ab, 
 ) !default;
 
 /// Pairs of background-color and color definitions

package/{scss → lib/scss}/_element.scss

@@ -70,7 +70,8 @@ $config: (
   "ul-list-style-type-2":             circle,
   "ul-list-style-type-3":             square,
   "cap-color" :                       "accent",
-  "cap-size" :                        5px
+  "cap-size" :                        5px,
+  "icon-centered-vertical-offset" :   0.02em,
 ) !default;
 
 /// Rule style map, redefine defaults or add to
@@ -412,4 +413,14 @@ $rule-margins: (
   &:focus:not(:focus-visible) {
     outline: none;
   }
-}
+}
+
+/// Remove default details arrow from the summary element
+@mixin summary-remove-marker() {
+  list-style: none; // Remove the default arrow (old safari?)
+  &::-webkit-details-marker,
+  &::marker {
+    display: none;
+    content: "";
+  }
+}

package/{scss → lib/scss}/_typography.scss

@@ -35,6 +35,7 @@
 /// @prop {Number} line-height-dense [1.3] Default dense line height
 /// @prop {Number} line-height-densest [1.1]
 /// @prop {Number} line-height-spaced [1.75]
+/// @prop {CssUnit} space-size [0.38em] The size of a space for the site's typography (used when creating faux spaces, like for .flow-inline utility)
 
 $config: (
   "letter-spacing-uppercase": 0.04em,
@@ -61,6 +62,7 @@ $config: (
   "max-width":                60em,
   "max-width-large":          75em,
   "max-width-small":          45em,
+  "space-size":               0.38em
 ) !default;
 
 /// Change modules $config
@@ -304,6 +306,19 @@ $sizes: get-default-sizes() !default;
   font-size: calc(#{ $font-size } + #{ $amount });
 }
 
+
+/// Output an optional typography size
+/// - If $name is not a string (ie. null, etc) no size will be output
+/// - If the size is not defined no size will be output
+/// @param {*} $name Size name
+/// @param {*} $args... All args are passed as-is to size() mixin
+
+@mixin optional-size($name, $changes: false, $only-font-size: null) {
+  @if (meta.type-of($name) == "string" and has-size($name)) {
+    @include size($name, $changes, $only-font-size);
+  }
+}
+
 /// Print a typography size (font-size, line-height)
 /// @param {String} $nameOrMap Name to retrieve from sizes map or a unique size map that follows the API
 /// @param {Map} $changes Modifications to be merged into size before output

package/lib/scss/components/_accordion.scss

@@ -0,0 +1,268 @@
+////
+/// @group accordion
+/// Outputs accordion component stylesheet, which can be used with <details> or custom disclosure components
+////
+
+@use "sass:map";
+@use "sass:meta";
+@use "sass:math";
+
+@use "../selector";
+@use "../utils";
+@use "../color";
+@use "../typography";
+@use "../element";
+
+
+// Used for function fallback
+$-fallbacks: (
+  "border-radius" : (
+    "function" : meta.get-function("get", false, "element"),
+    "property" : "border-radius"
+  ),
+);
+
+/// Module Settings
+/// @type Map
+/// @prop {Color}  background-color  [background] This is the background color of the accordion before it is expanded.
+/// @prop {Color}  background-color-open  [white] This is the background color of the accordion when it is expanded. This will change the background color of the accordion's summary as well as the details.
+/// @prop {String} border-color ["rule-light"] The color of the accordion border.
+/// @prop {Boolean|Number} border-radius  [true] This applies a rounding of edges for the accordion. If there are multiple accordions in a stack, this will only apply to the top of the first accordion and the bottom of the last accordion.
+/// @prop {Dimension} border-width  [1px] The width of the borders of the accordions.
+/// @prop {CssValue} box-shadow  [none] Adds a box shadow to accordion container.
+/// @prop {Dimension} margin  [(1.5em 0)] This is the margin above and below the accordion. Multiple Accordions will stack. See margin-between below.
+/// @prop {Dimension} margin-between  [0] This adds a margin between adjacent accordions. By default, accordions do not have any net margin between each other.
+/// @prop {Dimension} padding-x  [1.5em] Singular value for the left and right padding.
+/// @prop {Dimension} padding-y  [1.5em] Singular value for the top and bottom padding.
+/// @prop {Color} icon-background-color  [transparent] The background color of the icon.
+/// @prop {Color} icon-background-color-hover  [transparent] The background color of the icon when hovered or focused.
+/// @prop {Number} icon-border-radius  [50%] The border-radius of the icon.
+/// @prop {String} icon-color  [link] Color of the icon. This uses color.scss, so the value of this option should be a color variable from color.scss.
+/// @prop {String} icon-color-hover  [link-hover] Color of the icon when hovered or focused on. This uses color.scss, so the value of this options should be a color variable from color.scss.
+/// @prop {Dimension} icon-font-size  [1em] The font-size of the icon.
+/// @prop {Dimension} icon-margin [1em] The margin to the left of the icon.
+/// @prop {Dimension} icon-size  [auto] The size of the icon. Used as the base in the flex property.
+/// @prop {Dimension} icon-stroke-width [0.15em] The stroke width of the icon.
+/// @prop {Color} summary-background-color  [#f6f6f6] The background color for the summary (toggle button) of the accordion.
+/// @prop {Color} summary-background-color-hover [null] The background color for the summary (toggle button) of the accordion when hovered.
+/// @prop {Color} summary-color  [null] The color of the text in the accordion summary.
+/// @prop {Color} summary-color-hover  [null] The color of the text in the accordion summary when hovering or focusing on it.
+/// @prop {Dimension} summary-line-height  [null] Adjusts the line height of the summary element.
+/// @prop {Dimension} summary-padding-y  [1em] The vertical padding of the summary.
+/// @prop {String|Boolean} summary-type-size  ["large"] The typography size of the text in the accordion summary. Can be a boolean to disable.
+/// @prop {Boolean} summary-border-enabled [true] Whether the summary has a border when the accordion is open.
+/// @prop {Color} summary-border-color [rule-light] The color of the summary border.
+/// @prop {Dimension} summary-border-width [1px] The width of the summary border.
+/// @prop {Dimension} transparent-content-padding [(0.25em 0)] The padding of the content area for transparent accordions.
+/// @prop {Dimension} borderless-margin-between  [0.5em] Margin between accordions when using no-border modifier.
+/// @prop {String} active-selector ['.is-active'] The selector used for the active state of a non-<details> accordion.
+
+$config: (
+  "background-color":               "background",
+  "background-color-open":          white,
+  "border-color":                   "rule-light",
+  "border-radius":                  true,
+  "border-width":                   1px,
+  "box-shadow":                     none,
+  "margin":                         (1.5em 0),
+  "margin-between":                 0,
+  "padding-x":                      1.25em,
+  "padding-y":                      1.25em,
+  "icon-background-color":          transparent,
+  "icon-background-color-hover":    transparent,
+  "icon-border-radius":             50%,
+  "icon-color":                     "link",
+  "icon-color-hover":               "link-hover",
+  "icon-font-size":                 1em,
+  "icon-margin":                    1em,
+  "icon-size":                      auto,
+  "icon-stroke-width":              0.15em,
+  "summary-background-color":       #f6f6f6,
+  "summary-color":                  null,
+  "summary-background-color-hover": null,
+  "summary-color-hover":            null,
+  "summary-line-height":            null,
+  "summary-padding-y":              1em,
+  "summary-type-size":              false,
+  "summary-border-enabled":         true,
+  "summary-border-color":           "rule-light",
+  "summary-border-width":           1px,
+  "transparent-content-padding":    (1em 0),
+  "borderless-margin-between":      0.5em,
+  "active-selector":                ".is-active"
+) !default;
+
+/// Change modules $config
+/// @param {Map} $changes Map of changes
+/// @example scss
+///   @include ulu.component-accordion-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-accordion-get("property");
+
+@function get($name) {
+  $value: utils.require-map-get($config, $name, "accordion [config]");
+  @return utils.function-fallback($name, $value, $-fallbacks);
+}
+
+/// Prints component styles
+/// @demo accordion
+/// @example scss
+///  @include ulu.component-accordion-styles();
+
+@mixin styles {
+  $prefix: selector.class("accordion");
+  $active-selector: get("active-selector");
+  $padding-x: get("padding-x");
+  $border: get("border-width") solid color.get(get("border-color"));
+
+  // When not one of our custom classed details components
+  #{ $prefix } {
+    position: relative; // For pushing to the top when in accordion groups
+    padding: 0;
+    margin: get("margin");
+    border: $border;
+    background-color: color.get(get("background-color"));
+    box-shadow: get("box-shadow");
+    border-radius: get("border-radius");
+
+    // Sibling before sets the gap
+    & + #{ $prefix } {
+      margin-top: 0;
+    }
+
+    // If no space get rid of border radiuses
+    @if (get("margin-between") == 0) {
+      &:has(+ #{ $prefix }) {
+        border-bottom-left-radius: 0;
+        border-bottom-right-radius: 0;
+        margin-bottom: 0;
+      }
+      & + #{ $prefix } {
+        border-top-left-radius: 0;
+        border-top-right-radius: 0;
+        margin-top: -(get("border-width")); // Pull border over top
+      }
+    } @else {
+      &:has(+ #{ $prefix }) {
+        margin-bottom: get("margin-between");
+      }
+    }
+    
+    &[open], 
+    &#{ $active-selector }  {
+      background-color: color.get(get("background-color-open"));
+      z-index: 2; // Above other details/accordions
+      > #{ $prefix }__summary {
+        border-bottom-left-radius: 0;
+        border-bottom-right-radius: 0; 
+
+        @if (get("summary-border-enabled")) {
+          &::after {
+            content: "";
+            position: absolute;
+            top: 100%;
+            left: 0;
+            right: 0;
+            height: get("summary-border-width");
+            background-color: color.get(get("summary-border-color"));
+          }
+        }
+      }
+    }
+  }
+  #{ $prefix }__summary {
+    position: relative; // For pseudo border (done this way for animations)
+    display: flex;
+    width: 100%; // For <button>
+    background-color: color.get(get("summary-background-color"));
+    color: color.get(get("summary-color"));
+    line-height: get("summary-line-height");
+    padding: get("summary-padding-y") $padding-x;
+    border-radius: get("border-radius");
+    font-weight: bold;
+    cursor: pointer;
+    align-items: center;
+
+    @include typography.optional-size(get("summary-type-size"), $only-font-size: true);
+    @include element.summary-remove-marker;
+    &:hover,
+    &:focus {
+      background-color: color.get(get("summary-background-color-hover"));
+      color: color.get(get("summary-color-hover"));
+      #{ $prefix }__icon {
+        background-color: color.get(get("icon-background-color-hover"));
+        color: color.get(get("icon-color-hover"));
+      }
+    }
+  }
+  #{ $prefix }__icon {
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    flex: 0 0 get("icon-size");
+    color: color.get(get("icon-color"));
+    margin-left: auto;
+    padding-left: get("icon-margin");
+    background-color: color.get(get("icon-background-color"));
+    border-radius: get("icon-border-radius");
+    width: get("icon-size");
+    height: get("icon-size");
+    font-size: get("icon-font-size");
+    line-height: 1;
+  }
+  #{ $prefix }__content {
+    padding: get("padding-y") $padding-x;
+    border-bottom-left-radius: get("border-radius");
+    border-bottom-right-radius: get("border-radius");
+  }
+  #{ $prefix }--transparent {
+    border-left: none;
+    border-right: none;
+    background-color: transparent !important;
+    border-radius: 0;
+
+    // Transparent always collapses space
+    @if (get("margin-between") != 0) {
+      &:has(+ #{ $prefix }) {
+        margin-bottom: 0;
+      }
+      & + #{ $prefix } {
+        margin-top: -(get("border-width")); // Pull border over top
+      }
+    }
+    > #{ $prefix }__summary,
+    > #{ $prefix }__content {
+      padding-left: 0;
+      padding-right: 0;
+      background-color: transparent;
+      border: none !important;
+      border-radius: 0 !important;
+    }
+    > #{ $prefix }__content {
+      padding: get("transparent-content-padding");
+    }
+  }
+  #{ $prefix }--borderless {
+    border: none;
+    &:has(+ #{ $prefix }) {
+      margin-bottom: 0;
+    }
+    & + #{ $prefix }--borderless {
+      margin-top: calc(get("borderless-margin-between") - get("border-width"));
+    }
+    &[open],
+    &#{ $active-selector } {
+      & > #{ $prefix }__summary {
+        border-radius: get("border-radius");
+        border-bottom: none;
+      }
+    }
+  }
+}

package/{scss → lib/scss}/components/_basic-hero.scss

@@ -32,7 +32,7 @@ $-fallbacks: (
 /// @prop {Color} background-color ["color-hero-background"] Background color of the hero
 
 $config: (
-  "background-color" : "background-gray",
+  "background-color" : #fafafa,
   "padding-top": 3rem,
   "padding-bottom" : 2rem,
   "gap" : (4rem 2rem),

package/lib/scss/components/_breadcrumb.scss

@@ -0,0 +1,110 @@
+////
+/// @group breadcrumb
+/// Breadcrumb trail list layout
+////
+
+@use "sass:map";
+@use "sass:math";
+@use "sass:meta";
+
+@use "../selector";
+@use "../utils";
+@use "../color";
+@use "../typography";
+
+
+// Used for function fallback
+$-fallbacks: (
+  "line-height" : (
+    "function" : meta.get-function("get", false, "typography"),
+    "property" : "line-height-densest"
+  ),
+);
+
+/// Module Settings
+/// @type Map
+/// @prop {List} margin [(0 0 1.25em 0)] Margin for component
+/// @prop {CssUnit} row-gap [0.35em] Gap when breadcrumbs wrap
+/// @prop {Color} color ["type-tertiary"] Base color (links inherit this)
+/// @prop {Color} color-hover ["link-hover"] Color for link hover
+/// @prop {CssUnit} line-height [true] Line height, defaults to typography line-height-densest
+/// @prop {CssUnit} item-max-width [15em] Max length of item text
+/// @prop {Color} separator-color [null] Optional color to apply to separator
+/// @prop {Number} separator-opacity [0.7] Optional opacity for separator
+/// @prop {List} separator-margin [(0 0.5em)] Separator margin
+
+$config: (
+  "row-gap":              0.5em,
+  "margin" :              (0 0 1.25em 0),
+  "color":                 "type-tertiary",
+  "color-hover":           "link-hover",
+  "line-height":           true,
+  "item-max-width":        15em,
+  "separator-margin":      (0 0.5em),
+  "separator-color":       null,
+  "separator-opacity":     0.7,
+) !default;
+
+/// Change modules $config
+/// @param {Map} $changes Map of changes
+/// @example scss
+///   @include ulu.component-breadcrumb-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-breadcrumb-get("property");
+
+@function get($name) {
+  $value: utils.require-map-get($config, $name, "breadcrumb [config]");
+  @return utils.function-fallback($name, $value, $-fallbacks);
+}
+
+/// Prints component styles
+/// @demo breadcrumb
+/// @example scss
+///  @include ulu.component-breadcrumb-styles();
+
+@mixin styles {
+  $prefix: selector.class("breadcrumb");
+  
+  #{ $prefix } {
+    color: color.get(get("color"));
+    margin: get("margin");
+    line-height: get("line-height");
+  }
+  #{ $prefix }__list {
+    display: flex;
+    align-items: center;
+    flex-wrap: wrap;
+    gap: get("row-gap") 0;
+  }
+  #{ $prefix }__item {
+    display: flex;
+    align-items: center;
+  }
+  #{ $prefix }__link,
+  #{ $prefix }__current {
+    white-space: nowrap;
+    overflow: hidden;
+    max-width: get("item-max-width");
+    text-overflow: ellipsis;
+  }
+  #{ $prefix }__link {
+    color: inherit;
+    text-decoration: none;
+    &:hover,
+    &:focus {
+      color: color.get(get("color-hover"));
+    }
+  }
+  #{ $prefix }__separator {
+    margin: get("separator-margin");
+    color: color.get(get("separator-color"));
+    opacity: get("separator-opacity");
+  }
+}