@graupl/core 1.0.0-beta.10

package/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/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/src/scss/state/_index.scss

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

package/src/scss/state/focus/_defaults.scss

@@ -0,0 +1,9 @@
+// @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.
+//
+// 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.
+
+$focus-outline-style: dotted !default;

package/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/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/scss/state/focus/_variables.scss

@@ -0,0 +1,50 @@
+// @graupl/core focus state variables.
+//
+// These values are to be used to directly style components and provide a
+// cleaner way to reference custom properties.
+
+@use "../../variables" as root-variables;
+@use "defaults";
+@use "../../defaults" as root-defaults;
+@use "../../theme/color/variables" as color;
+
+$focus-width: var(
+  --#{root-defaults.$prefix}focus-width,
+  #{root-variables.$border-width}
+);
+$focus-outline-color: var(
+  --#{root-defaults.$prefix}focus-outline-color,
+  #{color.$color}
+);
+$focus-outline-width: var(
+  --#{root-defaults.$prefix}focus-outline-width,
+  #{$focus-width}
+);
+$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,
+  #{color.$background}
+);
+$focus-border-color: var(
+  --#{root-defaults.$prefix}focus-border-color,
+  #{color.$background}
+);
+$focus-box-shadow: var(
+  --#{root-defaults.$prefix}focus-box-shadow,
+  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/scss/theme/_index.scss

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

package/src/scss/theme/color/_defaults.scss

@@ -0,0 +1,143 @@
+// @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.
+//
+// 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 "sass:map";
+@use "sass:list";
+
+$theme-selector-prefix: "." !default;
+$theme-selector-suffix: "-mode" !default;
+
+// The site will have colours, defaulting to primary, secondary, and tertiary.
+// Each colour will have a shade mapping, defaulting to 100-900.
+// Users can add custom colours/overrides for both colours and shades.
+
+// The site will use themes, defaulting to light and dark.
+// Users can add custom themes/overrides.
+
+// Each theme will have a mapping of colours, defaulting to cover all colours and shades.
+// Users can add custom mappings/overrides.
+
+// The combinations of colours, themes, and shades will be combined into a giant map.
+// It will be sorted by theme > color > shade where each shade is derived from the mapping.
+// Users can override any part of this giant map, allowing for fine-tuned control of theme colours.
+
+// Colours.
+$default-colors: (
+  primary: (
+    100: hsl(219deg 100% 95%),
+    200: hsl(219deg 90% 80%),
+    300: hsl(219deg 80% 65%),
+    400: hsl(219deg 75% 55%),
+    500: hsl(219deg 75% 50%),
+    600: hsl(219deg 75% 45%),
+    700: hsl(219deg 80% 35%),
+    800: hsl(219deg 90% 20%),
+    900: hsl(219deg 100% 10%),
+  ),
+  secondary: (
+    100: hsl(235deg 40% 95%),
+    200: hsl(235deg 30% 80%),
+    300: hsl(235deg 20% 65%),
+    400: hsl(235deg 15% 55%),
+    500: hsl(235deg 15% 50%),
+    600: hsl(235deg 15% 45%),
+    700: hsl(235deg 20% 35%),
+    800: hsl(235deg 30% 20%),
+    900: hsl(235deg 40% 10%),
+  ),
+  tertiary: (
+    100: hsl(340deg 85% 95%),
+    200: hsl(340deg 75% 80%),
+    300: hsl(340deg 65% 65%),
+    400: hsl(340deg 60% 55%),
+    500: hsl(340deg 60% 50%),
+    600: hsl(340deg 60% 45%),
+    700: hsl(340deg 65% 35%),
+    800: hsl(340deg 75% 20%),
+    900: hsl(340deg 85% 10%),
+  ),
+);
+$custom-colors: () !default;
+$colors: map.deep-merge($default-colors, $custom-colors);
+
+// Themes.
+$default-themes: (light, dark);
+$custom-themes: () !default;
+$themes: list.join($default-themes, $custom-themes);
+$default-theme: light !default;
+
+// Theme mappings.
+$default-theme-mappings: (
+  light: (
+    100: 100,
+    200: 200,
+    300: 300,
+    400: 400,
+    500: 500,
+    600: 600,
+    700: 700,
+    800: 800,
+    900: 900,
+  ),
+  dark: (
+    100: 900,
+    200: 800,
+    300: 700,
+    400: 600,
+    500: 500,
+    600: 400,
+    700: 300,
+    800: 200,
+    900: 100,
+  ),
+);
+$custom-theme-mappings: () !default;
+$theme-mappings: map.deep-merge(
+  $default-theme-mappings,
+  $custom-theme-mappings
+);
+
+// Theme map.
+$default-theme-map: ();
+
+@each $theme in $themes {
+  $theme-map: ();
+
+  @each $color-name, $color-map in $colors {
+    $color-theme-map: ();
+
+    @each $shade, $value in $color-map {
+      $color-theme-map: map.merge(
+        $color-theme-map,
+        (
+          $shade: (
+              color: $color-name,
+              shade: map.get($theme-mappings, $theme, $shade),
+            ),
+        )
+      );
+    }
+
+    $theme-map: map.merge(
+      $theme-map,
+      (
+        $color-name: $color-theme-map,
+      )
+    );
+  }
+
+  $default-theme-map: map.merge(
+    $default-theme-map,
+    (
+      $theme: $theme-map,
+    )
+  );
+}
+
+$custom-theme-map: () !default;
+$theme-map: map.deep-merge($default-theme-map, $custom-theme-map);

package/src/scss/theme/color/_index.scss

@@ -0,0 +1,42 @@
+// @graupl/core color theme styles.
+
+@use "../../defaults" as root-defaults;
+@use "../../mixins/layer" as *;
+@use "../../mixins/theme";
+@use "defaults";
+@use "sass:map";
+@use "variables" as *;
+
+@include layer(theme) {
+  :root {
+    background: $root-background;
+    color: $root-color;
+
+    // Generate the default colour properties.
+    @each $color, $map in defaults.$colors {
+      @each $shade, $value in $map {
+        --#{root-defaults.$prefix}#{$color}--#{$shade}: #{$value};
+      }
+    }
+
+    // Generate the active theme properties.
+    @each $color, $map in map.get($themes, defaults.$default-theme) {
+      @each $shade, $value in $map {
+        --#{root-defaults.$prefix}theme-active--#{$color}--#{$shade}: #{$value};
+      }
+    }
+  }
+
+  // Generate the available theme properties.
+  @each $theme-name, $theme in $themes {
+    @include theme.theme($theme-name) {
+      @each $color, $map in $theme {
+        @each $shade, $value in $map {
+          --#{root-defaults.$prefix}theme-active--#{$color}--#{$shade}: #{$value};
+        }
+      }
+
+      color-scheme: #{$theme-name};
+    }
+  }
+}

package/src/scss/theme/color/_variables.scss

@@ -0,0 +1,133 @@
+// @graupl/core color 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 "sass:map";
+
+// A colour map of base colours and their shades.
+$colors: ();
+
+// Create a map for each colour.
+@each $color, $map in defaults.$colors {
+  // A map for the current colour.
+  $color-map: ();
+
+  @each $shade, $value in $map {
+    // Set the custom prop name and fallback value.
+    $color-property: var(
+      --#{root-defaults.$prefix}#{$color}--#{$shade},
+      $value
+    );
+
+    // Add the custom prop to the map.
+    $color-map: map.merge(
+      $color-map,
+      (
+        $shade: $color-property,
+      )
+    );
+  }
+
+  // Merge the colour map with the existing colours.
+  $colors: map.merge(
+    $colors,
+    (
+      $color: $color-map,
+    )
+  );
+}
+
+$themes: (
+  active: (),
+);
+
+// Generate all of the theme properties.
+@each $theme-name, $theme-map in defaults.$theme-map {
+  $theme: ();
+
+  @each $color-name, $map in $theme-map {
+    $color-map: ();
+
+    @each $shade, $value in $map {
+      $color-property: var(
+        --#{root-defaults.$prefix}theme-#{$theme-name}--#{$color-name}--#{$shade},
+        #{map.get($colors, map.get($value, color), map.get($value, shade))}
+      );
+      $color-map: map.merge(
+        $color-map,
+        (
+          $shade: $color-property,
+        )
+      );
+    }
+
+    $theme: map.merge(
+      $theme,
+      (
+        $color-name: $color-map,
+      )
+    );
+  }
+
+  $themes: map.merge(
+    $themes,
+    (
+      $theme-name: $theme,
+    )
+  );
+}
+
+// Generate the active theme properties.
+@each $color-name, $map in map.get($themes, defaults.$default-theme) {
+  $color-map: ();
+
+  @each $shade, $value in $map {
+    $color-property: var(
+      --#{root-defaults.$prefix}theme-active--#{$color-name}--#{$shade},
+      #{$value}
+    );
+    $color-map: map.merge(
+      $color-map,
+      (
+        $shade: $color-property,
+      )
+    );
+  }
+
+  $themes: map.merge(
+    $themes,
+    (
+      active: map.merge(
+          map.get($themes, active),
+          (
+            $color-name: $color-map,
+          )
+        ),
+    )
+  );
+}
+
+// Colour properties.
+$root-color: var(--#{root-defaults.$prefix}root-color);
+$root-background: var(--#{root-defaults.$prefix}root-background);
+
+@if map.has-key($themes, active, primary, 900) {
+  $root-color: var(
+    --#{root-defaults.$prefix}root-color,
+    #{map.get(map.get(map.get($themes, active), primary), 900)}
+  );
+}
+
+@if map.has-key($themes, active, primary, 100) {
+  $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});