@graupl/graupl 1.0.0-beta.1 → 1.0.0-beta.10

package/packages/core/src/scss/mixins/_utility.scss

@@ -0,0 +1,185 @@
+// @graupl/core utility mixins.
+//
+// Mixins to help generate utility classes.
+
+@use "./screen";
+@use "./container";
+@use "./state";
+@use "./theme";
+@use "../functions/important";
+@use "../functions/utility";
+@use "../defaults" as root-defaults;
+@use "sass:string";
+
+/// Insert a map of properties and values into a utility class.
+///
+/// @param {Map} $map
+///   The map of properties and values to apply to the selector.
+/// @param {Boolean} $important
+///   A flag to determine if the important flag should be added.
+@mixin _insert($map, $important: null) {
+  @each $prop, $value in $map {
+    // Do not attempt to insert important values inside of custom properties.
+    @if string.slice($prop, 1, 2) != "--" {
+      #{$prop}: important.insert(#{$value}, $override: $important);
+    } @else {
+      #{$prop}: #{$value};
+    }
+  }
+
+  // Allow for custom overrides and additional styles.
+  @content;
+}
+
+/// Handles wrapping utilities with a conditional state.
+///
+/// @param {?string} $state
+///   The state to wrap.
+@mixin _handle-state($state: null) {
+  @if $state {
+    @include state.state($state) {
+      @content;
+    }
+  } @else {
+    @content;
+  }
+}
+
+/// Handles wrapping utilities with a conditional screen.
+///
+/// @param {?string} $screen
+///   The screen to wrap.
+@mixin _handle-screen($screen: null) {
+  @if $screen {
+    @include screen.up($screen) {
+      @content;
+    }
+  } @else {
+    @content;
+  }
+}
+
+/// Handles wrapping utilities with a conditional container.
+///
+/// @param {?string} $container
+///   The container to wrap.
+@mixin _handle-container($container: null) {
+  @if $container {
+    @include container.up($container) {
+      @content;
+    }
+  } @else {
+    @content;
+  }
+}
+
+/// Handles wrapping utilities with a conditional theme.
+///
+/// @param {?string} $theme
+///   The theme mode to wrap.
+@mixin _handle-theme($theme: null) {
+  @if $theme {
+    @include theme.theme($theme) {
+      @content;
+    }
+  } @else {
+    @content;
+  }
+}
+
+/// Create a utility class with a list of properties and a single value.
+///
+/// @param {string}      $selector
+///   The selector to apply the utility class to.
+/// @param {string|List} $property
+///   The property/properties to apply to the selector.
+/// @param {string}      $value
+///   The value to apply to the property/properties.
+/// @param {?Boolean}     $important
+///   A flag to determine if the important flag should be added.
+/// @param {?string}     $screen
+///   The screen to apply the utility class to.
+/// @param {?string}     $theme
+///   The theme mode to apply the utility class to.
+/// @param {?string}     $state
+///   The state to apply the utility class to.
+@mixin create(
+  $selector,
+  $property,
+  $value,
+  $important: null,
+  $screen: null,
+  $theme: null,
+  $state: null,
+  $container: null
+) {
+  $map: utility.convert-property-values-to-map($property, $value);
+
+  @include create-mapped(
+    $selector,
+    $map,
+    $important: $important,
+    $screen: $screen,
+    $theme: $theme,
+    $state: $state,
+    $container: $container
+  ) {
+    @content;
+  }
+}
+
+/// Create a utility class with a map of properties and values.
+///
+/// @param {string}  $selector
+///   The selector to apply the utility class to.
+/// @param {Map}     $map
+///   The map of properties and values to apply to the selector.
+/// @param {?Boolean} $important
+///   A flag to determine if the important flag should be added.
+/// @param {?string} $screen
+///   The screen to apply the utility class to.
+/// @param {?string} $theme
+///   The theme mode to apply the utility class to.
+/// @param {?string} $state
+///   The state to apply the utility class to.
+@mixin create-mapped(
+  $selector,
+  $map,
+  $important: null,
+  $screen: null,
+  $theme: null,
+  $state: null,
+  $container: null
+) {
+  @include _handle-theme($theme) {
+    #{$selector} {
+      @if $screen or $container {
+        @if $screen {
+          @include _handle-screen($screen) {
+            @include _handle-state($state) {
+              @include _insert($map, $important) {
+                @content;
+              }
+            }
+          }
+        }
+
+        @if $container {
+          @include _handle-container($container) {
+            @include _handle-state($state) {
+              @include _insert($map, $important) {
+                @content;
+              }
+            }
+          }
+        }
+      } @else {
+        @include _handle-state($state) {
+          @include _insert($map, $important) {
+            @content;
+          }
+        }
+      }
+    }
+  }
+}

package/packages/core/src/scss/mixins/_visually-hidden.scss

@@ -0,0 +1,30 @@
+// @graupl/core visually hidden mixins.
+
+@use "../functions/important";
+
+/// Apply the visually hidden utility.
+///
+/// @param {Boolean} $important
+///   A flag to determine if the important flag should be added.
+@mixin apply($important: true) {
+  position: important.insert(absolute, $override: $important);
+  width: important.insert(1px, $override: $important);
+  height: important.insert(1px, $override: $important);
+  margin: important.insert(-1px, $override: $important);
+  padding: important.insert(0, $override: $important);
+  overflow: important.insert(hidden, $override: $important);
+  clip: important.insert(rect(0, 0, 0, 0), $override: $important);
+  border: important.insert(0, $override: $important);
+  white-space: important.insert(nowrap, $override: $important);
+  clip-path: important.insert(inset(50%), $override: $important);
+}
+
+/// Apply the visually hidden utility to not-focussed elements.
+///
+/// @param {Boolean} $important
+///   A flag to determine if the important flag should be added.
+@mixin focusable($important: true) {
+  &:not(:focus, :focus-within) {
+    @include apply($important);
+  }
+}

package/packages/core/src/scss/state/_index.scss

@@ -0,0 +1,3 @@
+// @graupl/core state styles.
+
+@forward "focus";

package/{src → packages/core/src}/scss/state/focus/_defaults.scss

@@ -1,4 +1,4 @@
-// @graupl/graupl focus state default values.
+// @graupl/core focus state default values.
 //
 // Generally, these should not be used directly when styling components unless a static value is needed.
 // They are mainly used to provide class selectors, fallbacks for custom properties, or loop values.
@@ -7,4 +7,3 @@
 // Those should be defined as custom properties in the `_variables.scss` file.
 
 $focus-outline-style: dotted !default;
-$focus-box-shadow-style: inset !default;

package/packages/core/src/scss/state/focus/_index.scss

@@ -0,0 +1,42 @@
+// @graupl/core focus state styles.
+//
+// This module provides the styles for Graupl's focus state.
+//
+// The focus state is applied to an element when it is focused by the user.
+//
+// The following classes are generated by default:
+// - `.focus`: The focus state class.
+//
+// The following custom properties control the generated classes:
+// - `--graupl-focus-width`: The width of the focus outline.
+// - `--graupl-focus-outline-color`: The color of the focus outline.
+// - `--graupl-focus-outline-width`: The width of the focus outline.
+// - `--graupl-focus-outline-style`: The style of the focus outline.
+// - `--graupl-focus-outline-offset`: The offset of the focus outline.
+// - `--graupl-focus-box-shadow-color`: The color of the focus box shadow.
+// - `--graupl-focus-box-shadow-style`: The style of the focus box shadow.
+// - `--graupl-focus-box-shadow`: The box shadow of the focus state.
+//
+// The following variables control the generated classes:
+// - `$focus-outline-style`: The style of the focus outline.
+// - `$focus-box-shadow-style`: The style of the focus box shadow.
+//
+// Note: This focus styles are also applied to the `:focus-visible` pseudo-class by default.
+//
+// @example
+//   <button class="focus">Focus</button>
+
+@use "variables" as *;
+@use "../../mixins/layer" as *;
+@use "mixins" as *;
+@use "../../defaults" as root-defaults;
+@use "sass:map";
+
+@include layer(state) {
+  @each $state in map.get(root-defaults.$state-selectors, focus) {
+    // e.g. *.focus or *:focus-visible
+    *#{$state} {
+      @include apply-focus;
+    }
+  }
+}

package/packages/core/src/scss/state/focus/_mixins.scss

@@ -0,0 +1,13 @@
+// @graupl/core focus state mixins.
+
+@use "variables" as *;
+@use "../../defaults" as root-defaults;
+@use "sass:map";
+
+/// Applies the focus state.
+@mixin apply-focus() {
+  border-color: $focus-border-color;
+  outline: $focus-outline;
+  outline-offset: $focus-outline-offset;
+  box-shadow: $focus-box-shadow;
+}

package/{src → packages/core/src}/scss/state/focus/_variables.scss

@@ -1,4 +1,4 @@
-// @graupl/graupl focus state variables.
+// @graupl/core focus state variables.
 //
 // These values are to be used to directly style components and provide a
 // cleaner way to reference custom properties.
@@ -6,7 +6,7 @@
 @use "../../variables" as root-variables;
 @use "defaults";
 @use "../../defaults" as root-defaults;
-@use "../../functions/theme";
+@use "../../theme/color/variables" as color;
 
 $focus-width: var(
   --#{root-defaults.$prefix}focus-width,
@@ -14,7 +14,7 @@ $focus-width: var(
 );
 $focus-outline-color: var(
   --#{root-defaults.$prefix}focus-outline-color,
-  #{theme.get(primary, 900)}
+  #{color.$color}
 );
 $focus-outline-width: var(
   --#{root-defaults.$prefix}focus-outline-width,
@@ -24,21 +24,27 @@ $focus-outline-style: var(
   --#{root-defaults.$prefix}focus-outline-style,
   #{defaults.$focus-outline-style}
 );
+$focus-outline: var(
+  --#{root-defaults.$prefix}focus-outline,
+  #{$focus-outline-width} #{$focus-outline-style} #{$focus-outline-color}
+);
 $focus-outline-offset: var(
   --#{root-defaults.$prefix}focus-outline-offset,
   calc(-1 * #{$focus-outline-width})
 );
 $focus-box-shadow-color: var(
   --#{root-defaults.$prefix}focus-box-shadow-color,
-  #{theme.get(primary, 100)}
+  #{color.$background}
 );
-$focus-box-shadow-style: var(
-  --#{root-defaults.$prefix}focus-box-shadow-style,
-  #{defaults.$focus-box-shadow-style}
+$focus-border-color: var(
+  --#{root-defaults.$prefix}focus-border-color,
+  #{color.$background}
 );
 $focus-box-shadow: var(
   --#{root-defaults.$prefix}focus-box-shadow,
-  #{$focus-width $focus-width} 0 0 #{$focus-box-shadow-style}
-    #{$focus-box-shadow-color},
-  0 0 0 #{$focus-width} #{$focus-box-shadow-style} #{$focus-box-shadow-color}
+  0 0 0 #{$focus-width} inset #{$focus-box-shadow-color}
+);
+$focus-box-shadow-bordered: var(
+  --#{root-defaults.$prefix}focus-box-shadow-bordered,
+  0 0 0 #{$focus-width} #{$focus-box-shadow-color}
 );

package/{src → packages/core/src}/scss/theme/_index.scss

@@ -1,4 +1,4 @@
-// @graupl/graupl theme styles.
+// @graupl/core theme styles.
 
 @forward "color";
 @forward "typography";

package/{src → packages/core/src}/scss/theme/color/_defaults.scss

@@ -1,4 +1,4 @@
-// @graupl/graupl color theme default values.
+// @graupl/core color theme default values.
 //
 // Generally, these should not be used directly when styling components unless a static value is needed.
 // They are mainly used to provide class selectors, fallbacks for custom properties, or loop values.

package/{src → packages/core/src}/scss/theme/color/_index.scss

@@ -1,11 +1,11 @@
-// @graupl/graupl color theme styles.
+// @graupl/core color theme styles.
 
-@use "variables" as *;
+@use "../../defaults" as root-defaults;
 @use "../../mixins/layer" as *;
+@use "../../mixins/theme";
 @use "defaults";
-@use "../../defaults" as root-defaults;
 @use "sass:map";
-@use "../../functions/theme";
+@use "variables" as *;
 
 @include layer(theme) {
   :root {
@@ -29,7 +29,7 @@
 
   // Generate the available theme properties.
   @each $theme-name, $theme in $themes {
-    #{defaults.$theme-selector-prefix}#{$theme-name}#{defaults.$theme-selector-suffix} {
+    @include theme.theme($theme-name) {
       @each $color, $map in $theme {
         @each $shade, $value in $map {
           --#{root-defaults.$prefix}theme-active--#{$color}--#{$shade}: #{$value};

package/{src → packages/core/src}/scss/theme/color/_variables.scss

@@ -1,4 +1,4 @@
-// @graupl/graupl color theme variables.
+// @graupl/core color theme variables.
 //
 // These values are to be used to directly style components and provide a
 // cleaner way to reference custom properties.
@@ -127,3 +127,7 @@ $root-background: var(--#{root-defaults.$prefix}root-background);
     #{map.get(map.get(map.get($themes, active), primary), 100)}
   );
 }
+
+$color: var(--#{root-defaults.$prefix}color, #{$root-color});
+$background: var(--#{root-defaults.$prefix}background, #{$root-background});
+$border-color: var(--#{root-defaults.$prefix}border-color, #{$color});

package/{src → packages/core/src}/scss/theme/typography/_defaults.scss

@@ -1,4 +1,4 @@
-// @graupl/graupl typography theme default values.
+// @graupl/core typography theme default values.
 //
 // Generally, these should not be used directly when styling components unless a static value is needed.
 // They are mainly used to provide class selectors, fallbacks for custom properties, or loop values.

package/{src → packages/core/src}/scss/theme/typography/_index.scss

@@ -1,4 +1,4 @@
-// @graupl/graupl typography theme styles.
+// @graupl/core typography theme styles.
 
 @use "variables" as *;
 @use "../../mixins/layer" as *;
@@ -50,24 +50,28 @@
   }
 
   body {
+    color: $body-color;
     font-size: $body-font-size;
     font-weight: $body-font-weight;
     line-height: $body-line-height;
   }
 
   p {
+    color: $paragraph-color;
     font-size: $paragraph-font-size;
     font-weight: $paragraph-font-weight;
     line-height: $paragraph-line-height;
   }
 
   small {
+    color: $small-color;
     font-size: $small-font-size;
     font-weight: $small-font-weight;
     line-height: $small-line-height;
   }
 
   h1 {
+    color: $h1-color;
     font-family: $h1-font-family;
     font-size: $h1-font-size;
     font-weight: $h1-font-weight;
@@ -75,6 +79,7 @@
   }
 
   h2 {
+    color: $h2-color;
     font-family: $h2-font-family;
     font-size: $h2-font-size;
     font-weight: $h2-font-weight;
@@ -82,6 +87,7 @@
   }
 
   h3 {
+    color: $h3-color;
     font-family: $h3-font-family;
     font-size: $h3-font-size;
     font-weight: $h3-font-weight;
@@ -89,6 +95,7 @@
   }
 
   h4 {
+    color: $h4-color;
     font-family: $h4-font-family;
     font-size: $h4-font-size;
     font-weight: $h4-font-weight;
@@ -96,6 +103,7 @@
   }
 
   h5 {
+    color: $h5-color;
     font-family: $h5-font-family;
     font-size: $h5-font-size;
     font-weight: $h5-font-weight;
@@ -103,6 +111,7 @@
   }
 
   h6 {
+    color: $h6-color;
     font-family: $h6-font-family;
     font-size: $h6-font-size;
     font-weight: $h6-font-weight;

package/{src → packages/core/src}/scss/theme/typography/_variables.scss

@@ -1,11 +1,12 @@
-// @graupl/graupl typography theme variables.
+// @graupl/core typography theme variables.
 //
 // These values are to be used to directly style components and provide a
 // cleaner way to reference custom properties.
 
-@use "defaults";
 @use "../../defaults" as root-defaults;
 @use "../../variables" as root-variables;
+@use "../color/variables" as color-variables;
+@use "defaults";
 @use "sass:map";
 
 // Font properties.
@@ -64,6 +65,10 @@ $body-font-weight: var(
   --#{root-defaults.$prefix}body-font-weight,
   #{map.get($font-weights, normal)}
 );
+$body-color: var(
+  --#{root-defaults.$prefix}body-color,
+  #{color-variables.$color}
+);
 $paragraph-font-size: var(
   --#{root-defaults.$prefix}paragraph-font-size,
   #{$body-font-size}
@@ -80,6 +85,10 @@ $paragraph-font-weight: var(
   --#{root-defaults.$prefix}paragraph-font-weight,
   #{$body-font-weight}
 );
+$paragraph-color: var(
+  --#{root-defaults.$prefix}paragraph-color,
+  #{$body-color}
+);
 $small-font-size: var(
   --#{root-defaults.$prefix}small-font-size,
   #{map.get($font-sizes, sm)}
@@ -96,6 +105,7 @@ $small-font-weight: var(
   --#{root-defaults.$prefix}small-font-weight,
   #{$body-font-weight}
 );
+$small-color: var(--#{root-defaults.$prefix}small-color, #{$body-color});
 
 // Headings properties.
 $heading-font-family: var(
@@ -115,6 +125,7 @@ $heading-font-weight: var(
   --#{root-defaults.$prefix}heading-font-weight,
   #{$font-weight-bold}
 );
+$heading-color: var(--#{root-defaults.$prefix}heading-color, #{$body-color});
 
 // H1 properties.
 $h1-font-size: var(
@@ -134,6 +145,7 @@ $h1-font-weight: var(
   --#{root-defaults.$prefix}h1-font-weight,
   $heading-font-weight
 );
+$h1-color: var(--#{root-defaults.$prefix}h1-color, #{$heading-color});
 
 // H2 properties.
 $h2-font-size: var(
@@ -153,6 +165,7 @@ $h2-font-weight: var(
   --#{root-defaults.$prefix}h2-font-weight,
   $heading-font-weight
 );
+$h2-color: var(--#{root-defaults.$prefix}h2-color, #{$heading-color});
 
 // H3 properties.
 $h3-font-size: var(
@@ -172,6 +185,7 @@ $h3-font-weight: var(
   --#{root-defaults.$prefix}h3-font-weight,
   $heading-font-weight
 );
+$h3-color: var(--#{root-defaults.$prefix}h3-color, #{$heading-color});
 
 // H4 properties.
 $h4-font-size: var(
@@ -191,6 +205,7 @@ $h4-font-weight: var(
   --#{root-defaults.$prefix}h4-font-weight,
   $heading-font-weight
 );
+$h4-color: var(--#{root-defaults.$prefix}h4-color, #{$heading-color});
 
 // H5 properties.
 $h5-font-size: var(
@@ -210,6 +225,7 @@ $h5-font-weight: var(
   --#{root-defaults.$prefix}h5-font-weight,
   $heading-font-weight
 );
+$h5-color: var(--#{root-defaults.$prefix}h5-color, #{$heading-color});
 
 // H6 properties.
 $h6-font-size: var(
@@ -229,3 +245,4 @@ $h6-font-weight: var(
   --#{root-defaults.$prefix}h6-font-weight,
   $heading-font-weight
 );
+$h6-color: var(--#{root-defaults.$prefix}h6-color, #{$heading-color});

package/{src → packages/core/src}/scss/utilities/_index.scss

@@ -1,9 +1,13 @@
-// @graupl/graupl utilities styles.
+// @graupl/core utilities styles.
 
 @forward "alignment";
+@forward "background";
+@forward "border";
 @forward "color";
+@forward "container";
 @forward "display";
 @forward "flex";
+@forward "gradient";
 @forward "height";
 @forward "inset";
 @forward "justification";
@@ -14,4 +18,6 @@
 @forward "spacing";
 @forward "typography";
 @forward "visibility";
+@forward "visually-hidden";
 @forward "width";
+@forward "z-index";

package/packages/core/src/scss/utilities/_template/_defaults.scss

@@ -0,0 +1,41 @@
+// @graupl/core [_template] utilities default values.
+//
+// Generally, these should not be used directly when styling components unless a static value is needed.
+// They are mainly used to provide class selectors, fallbacks for custom properties, or loop values.
+//
+// They should not be used to define direct property values (i.e. font-size, color, etc.).
+// Those should be defined as custom properties in the `_variables.scss` file.
+
+@use "../../defaults" as root-defaults;
+@use "sass:map";
+
+// Utility modifiers.
+$selector-base: root-defaults.$utility-selector-base !default;
+$use-important: root-defaults.$use-important !default;
+$screen-aware: false !default;
+$theme-aware: false !default;
+$state-aware: false !default;
+$container-aware: false !default;
+$screen-aware-separator: root-defaults.$utility-screen-aware-separator !default;
+$theme-aware-separator: root-defaults.$utility-theme-aware-separator !default;
+$state-aware-separator: root-defaults.$utility-state-aware-separator !default;
+$container-aware-separator: root-defaults.$utility-container-aware-separator !default;
+$screen-aware-selector-prefix: root-defaults.$utility-screen-aware-selector-prefix !default;
+$theme-aware-selector-prefix: root-defaults.$utility-theme-aware-selector-prefix !default;
+$state-aware-selector-prefix: root-defaults.$utility-state-aware-selector-prefix !default;
+$container-aware-selector-prefix: root-defaults.$utility-container-aware-selector-prefix !default;
+
+// _Template properties.
+//
+// Remember when defining properties to make sure the defaults can be customized.
+// This can be done by using variables for class names, or by defining base properties and merging them with custom properties provided by the user.
+//
+// Remember to replace references like [_template], or other placeholder content with appropriate descriptions!
+
+$template-selector-prefix: "template-" !default;
+$base-template-properties: ();
+$custom-template-properties: () !default;
+$template-properties: map.merge(
+  $base-template-properties,
+  $custom-template-properties
+);