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

package/packages/core/src/scss/utilities/position/_index.scss

@@ -0,0 +1,178 @@
+// @graupl/core position utilities styles.
+//
+// This file generates the position utility classes provided by Graupl.
+//
+// The following classes are generated by default:
+// - `.position-static`: Sets the position property to `static`.
+// - `.position-fixed`: Sets the position property to `fixed`.
+// - `.position-absolute`: Sets the position property to `absolute`.
+// - `.position-relative`: Sets the position property to `relative`.
+// - `.position-sticky`: Sets the position property to `sticky`.
+//
+// The following custom properties control the generated classes:
+// - N/A.
+//
+// The following variables control the generated classes:
+// - `$selector-base`: The base selector for the utility classes.
+// - `$use-important`: A flag to determine if the `!important` flag should be added to the utility classes.
+// - `$screen-aware`: A flag to generate screen-aware utility classes.
+// - `$theme-aware`: A flag to generate theme-aware utility classes.
+// - `$state-aware`: A flag to generate state-aware utility classes.
+// - `$container-aware`: A flag to generate container-aware utility classes.
+// - `$screen-aware-separator`: The separator for screen-aware utility classes.
+// - `$theme-aware-separator`: The separator for theme-aware utility classes.
+// - `$state-aware-separator`: The separator for state-aware utility classes.
+// - `$container-aware-separator`: The separator for container-aware utility classes.
+// - `$screen-aware-selector-prefix`: The prefix for screen-aware utility classes.
+// - `$theme-aware-selector-prefix`: The prefix for theme-aware utility classes.
+// - `$state-aware-selector-prefix`: The prefix for state-aware utility classes.
+// - `$container-aware-selector-prefix`: The prefix for container-aware utility classes.
+// - `$position-selector-prefix`: The prefix for the position utility classes.
+// - `$base-position-properties`: The base properties and values for the position utility classes.
+// - `$custom-position-properties`: The custom properties and values for the position utility classes.
+// - `$position-properties`: The combined properties and values for the position utility classes.
+//
+// Generating responsive utility classes can be done by setting `$screen-aware`, `$theme-aware`, or `$state-aware` to `true`.
+// By default, only screen-aware utility classes are generated.
+//
+// When set to true, screen-aware utility classes will be generated for each screen size in the following pattern:
+// - `.{screen-prefix}{screen-name}:{prefix}{value}`
+//
+// e.g. `.md:position-static` will set the `position` property to `static` on screens equal to or larger than the `md` breakpoint.
+//
+// When set to true, theme-aware utility classes will be generated for each theme in the following pattern:
+// - `.{theme-prefix}{theme-name}:{prefix}{value}`
+//
+// e.g. `.dark:position-static` will set the `position` property to `static` when the `dark` theme is active.
+//
+// When set to true, state-aware utility classes will be generated for each state in the following pattern:
+// - `.{state-prefix}{state-name}:{prefix}{value}`
+//
+// e.g. `.hover:position-static` will set the `position` property to `static` when the element is hovered.
+//
+// When set to true, container-aware utility classes will be generated for each container in the following pattern:
+// - `.{container-prefix}{container-name}:{prefix}{value}`
+//
+// e.g. `.cq:md:position-static` will set the `position` property to `static` when the parent container is larger than the `md` breakpoint.
+//
+// @example
+//   <div class="position-static">This is a static position element.</div>
+//
+// @example
+//   <div class="position-fixed md:position-absolute">This element will be `position: fixed` unless the screen size is `md` or larger.</div>
+
+@use "../../defaults" as root-defaults;
+@use "../../mixins/layer" as *;
+@use "../../mixins/utility";
+@use "../../theme/color/variables" as color;
+@use "defaults";
+@use "sass:map";
+@use "variables" as *;
+
+@include layer(utilities) {
+  // `.`
+  $selector-prefix: defaults.$selector-base;
+
+  // For each position property, create a utility class.
+  @each $name, $property in defaults.$position-properties {
+    // e.g. `.position-static` or `.position-fixed`
+    $selector: #{$selector-prefix}#{defaults.$position-selector-prefix}#{$name};
+
+    @include utility.create(
+      $selector,
+      position,
+      $property,
+      $important: defaults.$use-important
+    );
+  }
+
+  // Generate screen-aware utilities.
+  @if defaults.$screen-aware and root-defaults.$screen-aware-utilities {
+    @each $screen-name in map.keys(root-defaults.$screen-sizes) {
+      // e.g. `.md:` or `.lg:`
+      $selector-prefix: #{defaults.$selector-base}#{defaults.$screen-aware-selector-prefix}#{$screen-name}#{defaults.$screen-aware-separator};
+
+      // For each position property, create a utility class.
+      @each $name, $property in defaults.$position-properties {
+        // e.g. `.md:position-static` or `.lg:position-fixed`
+        $selector: #{$selector-prefix}#{defaults.$position-selector-prefix}#{$name};
+
+        @include utility.create(
+          $selector,
+          position,
+          $property,
+          $important: defaults.$use-important,
+          $screen: $screen-name
+        );
+      }
+    }
+  }
+
+  // Generate theme-aware utilities.
+  @if defaults.$theme-aware and root-defaults.$theme-aware-utilities {
+    @each $theme-name, $colors in color.$themes {
+      @if $theme-name != active {
+        // e.g. `.dark:` or `.light:`
+        $selector-prefix: #{defaults.$selector-base}#{defaults.$theme-aware-selector-prefix}#{$theme-name}#{defaults.$theme-aware-separator};
+
+        // For each position property, create a utility class.
+        @each $name, $property in defaults.$position-properties {
+          // e.g. `.dark:position-static` or `.light:position-fixed`
+          $selector: #{$selector-prefix}#{defaults.$position-selector-prefix}#{$name};
+
+          @include utility.create(
+            $selector,
+            position,
+            $property,
+            $important: defaults.$use-important,
+            $theme: $theme-name
+          );
+        }
+      }
+    }
+  }
+
+  // Generate state-aware utilities.
+  @if defaults.$state-aware and root-defaults.$state-aware-utilities {
+    @each $state-name, $value in root-defaults.$state-selectors {
+      // e.g. `.hover:` or `.focus:`
+      $selector-prefix: #{defaults.$selector-base}#{defaults.$state-aware-selector-prefix}#{$state-name}#{defaults.$state-aware-separator};
+
+      // For each position property, create a utility class.
+      @each $name, $property in defaults.$position-properties {
+        // e.g. `.hover:position-static` or `.focus:position-fixed`
+        $selector: #{$selector-prefix}#{defaults.$position-selector-prefix}#{$name};
+
+        @include utility.create(
+          $selector,
+          position,
+          $property,
+          $important: defaults.$use-important,
+          $state: $state-name
+        );
+      }
+    }
+  }
+
+  // Generate container-aware utilities.
+  @if defaults.$container-aware and root-defaults.$container-aware-utilities {
+    @each $container-name in map.keys(root-defaults.$container-sizes) {
+      // e.g. `.md:` or `.lg:`
+      $selector-prefix: #{defaults.$selector-base}#{defaults.$container-aware-selector-prefix}#{$container-name}#{defaults.$container-aware-separator};
+
+      // For each position property, create a utility class.
+      @each $name, $property in defaults.$position-properties {
+        // e.g. `.md:position-static` or `.lg:position-fixed`
+        $selector: #{$selector-prefix}#{defaults.$position-selector-prefix}#{$name};
+
+        @include utility.create(
+          $selector,
+          position,
+          $property,
+          $important: defaults.$use-important,
+          $container: $container-name
+        );
+      }
+    }
+  }
+}

package/{src/scss/utilities/height → packages/core/src/scss/utilities/position}/_variables.scss

@@ -1,4 +1,4 @@
-// @graupl/graupl height utilities variables.
+// @graupl/core position utilities variables.
 //
 // These values are to be used to directly style components and provide a
 // cleaner way to reference custom properties.

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

@@ -0,0 +1,42 @@
+// @graupl/core ratio 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: true !default;
+$theme-aware: false !default;
+$state-aware: false !default;
+$container-aware: true !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;
+
+// Ratio utilities.
+$ratio-selector: "ratio" !default;
+$ratio-variant-selector-prefix: "" !default;
+$force-ratio-selector: "force-ratio" !default;
+$base-ratios: (
+  "one-by-one": 100%,
+  "two-by-one": 50%,
+  "four-by-three": 75%,
+  "four-by-one": 25%,
+  "sixteen-by-nine": calc(9 / 16 * 100%),
+  "three-by-two": calc(2 / 3 * 100%),
+  "eight-by-five": calc(5 / 8 * 100%),
+);
+$custom-ratios: () !default;
+$ratios: map.merge($base-ratios, $custom-ratios);

package/packages/core/src/scss/utilities/ratio/_index.scss

@@ -0,0 +1,188 @@
+// @graupl/core ratio utilities styles.
+//
+// This file generates the ratio utility classes provided by Graupl.
+//
+// The following classes are generated by default:
+// - `.ratio`: Applies the default ratio styles.
+// - `.force-ratio`: Ensures child elements maintain the aspect ratio.
+// - `.one-by-one`: Applies a 1:1 aspect ratio.
+// - `.two-by-one`: Applies a 2:1 aspect ratio.
+// - `.four-by-three`: Applies a 4:3 aspect ratio.
+// - `.four-by-one`: Applies a 4:1 aspect ratio.
+// - `.sixteen-by-nine`: Applies a 16:9 aspect ratio.
+// - `.three-by-two`: Applies a 3:2 aspect ratio.
+// - `.eight-by-five`: Applies a 8:5 aspect ratio.
+//
+// The following custom properties control the generated classes:
+// - `--graupl-ratio`: The aspect ratio value.
+//
+// The following variables control the generated classes:
+// - `$selector-base`: The base selector for the utility classes.
+// - `$use-important`: A flag to determine if the `!important` flag should be added to the utility classes.
+// - `$screen-aware`: A flag to generate screen-aware utility classes.
+// - `$theme-aware`: A flag to generate theme-aware utility classes.
+// - `$state-aware`: A flag to generate state-aware utility classes.
+// - `$container-aware`: A flag to generate container-aware utility classes.
+// - `$screen-aware-separator`: The separator for screen-aware utility classes.
+// - `$theme-aware-separator`: The separator for theme-aware utility classes.
+// - `$state-aware-separator`: The separator for state-aware utility classes.
+// - `$container-aware-separator`: The separator for container-aware utility classes.
+// - `$screen-aware-selector-prefix`: The prefix for screen-aware utility classes.
+// - `$theme-aware-selector-prefix`: The prefix for theme-aware utility classes.
+// - `$state-aware-selector-prefix`: The prefix for state-aware utility classes.
+// - `$container-aware-selector-prefix`: The prefix for container-aware utility classes.
+// - `$ratio-selector`: The base selector for the ratio utility classes.
+// - `$ratio-variant-selector-prefix`: The prefix for the ratio variant utility classes.
+// - `$force-ratio-selector`: The selector for the force ratio utility class.
+// - `$base-ratios`: The base properties and values for the aspect ratio utility classes.
+// - `$custom-ratios`: The custom properties and values for the aspect ratio utility classes.
+// - `$ratios`: The combined properties and values for the aspect ratio utility classes.
+//
+// Generating responsive utility classes can be done by setting `$screen-aware`, `$theme-aware`, or `$state-aware` to `true`.
+// By default, only screen-aware utility classes are generated.
+//
+// When set to true, screen-aware utility classes will be generated for each screen size in the following pattern:
+// - `.{screen-prefix}{screen-name}:{prefix}{value}`
+//
+// e.g. `.sm:one-by-one` will set the aspect ratio to 1:1 on screens equal to or larger than the `sm` breakpoint.
+//
+// When set to true, theme-aware utility classes will be generated for each theme in the following pattern:
+// - `.{theme-prefix}{theme-name}:{prefix}{value}`
+//
+// e.g. `.dark:one-by-one` will set the aspect ratio to 1:1 when the `dark` theme is active.
+//
+// When set to true, state-aware utility classes will be generated for each state in the following pattern:
+// - `.{state-prefix}{state-name}:{prefix}{value}`
+//
+// e.g. `.hover:one-by-one` will set the aspect ratio to 1:1 when the element is hovered.
+//
+// When set to true, container-aware utility classes will be generated for each container in the following pattern:
+// - `.{container-prefix}{container-name}:{prefix}{value}`
+//
+// e.g. `.cq:md:one-by-one` will set the aspect ratio to 1:1 when the parent container is larger than the `md` breakpoint.
+//
+// @example
+//   <div class="ratio ratio-one-by-one">
+//     <img src="image.jpg" alt="Image" class="force-ratio">
+//   </div>
+//
+// @example
+//   <div class="ratio ratio-two-by-one md:ratio-one-by-one">
+//     <img src="image.jpg" alt="Image" class="force-ratio">
+//   </div>
+
+@use "../../defaults" as root-defaults;
+@use "../../functions/important";
+@use "../../mixins/container";
+@use "../../mixins/layer" as *;
+@use "../../mixins/screen";
+@use "../../mixins/state";
+@use "../../mixins/theme";
+@use "../../mixins/utility";
+@use "../../theme/color/variables" as color;
+@use "defaults";
+@use "sass:map";
+@use "variables" as *;
+
+@include layer(utilities) {
+  // `.`
+  $selector-prefix: defaults.$selector-base;
+
+  // `.ratio`
+  #{$selector-prefix}#{defaults.$ratio-selector} {
+    position: important.insert(relative, $override: defaults.$use-important);
+    width: important.insert(100%, $override: defaults.$use-important);
+
+    &::before {
+      content: "";
+      display: important.insert(block, $override: defaults.$use-important);
+      padding-top: important.insert($ratio, $override: defaults.$use-important);
+    }
+
+    // `.force-ratio`
+    .#{defaults.$force-ratio-selector} {
+      position: important.insert(absolute, $override: defaults.$use-important);
+      inset: important.insert(0, $override: defaults.$use-important);
+      width: important.insert(100%, $override: defaults.$use-important);
+      height: important.insert(100%, $override: defaults.$use-important);
+      object-fit: important.insert(cover, $override: defaults.$use-important);
+    }
+  }
+
+  @each $ratio-selector, $value in defaults.$ratios {
+    // e.g. `.ratio-one-by-one` or `.ratio-two-by-one`
+    #{$selector-prefix}#{defaults.$ratio-variant-selector-prefix}#{$ratio-selector} {
+      --#{root-defaults.$prefix}ratio: #{$value};
+    }
+  }
+
+  // Generate screen-aware utilities.
+  @if defaults.$screen-aware and root-defaults.$screen-aware-utilities {
+    @each $screen-name in map.keys(root-defaults.$screen-sizes) {
+      // e.g. `.md:` or `.lg:`
+      $selector-prefix: #{defaults.$selector-base}#{defaults.$screen-aware-selector-prefix}#{$screen-name}#{defaults.$screen-aware-separator};
+
+      @each $ratio-selector, $value in defaults.$ratios {
+        @include screen.up($screen-name) {
+          // e.g. `.md:ratio-one-by-one` or `.lg:ratio-two-by-one`
+          #{$selector-prefix}#{defaults.$ratio-variant-selector-prefix}#{$ratio-selector} {
+            --#{root-defaults.$prefix}ratio: #{$value};
+          }
+        }
+      }
+    }
+  }
+
+  // Generate theme-aware utilities.
+  @if defaults.$theme-aware and root-defaults.$theme-aware-utilities {
+    @each $theme-name, $colors in color.$themes {
+      @if $theme-name != active {
+        // e.g. `.dark:` or `.light:`
+        $selector-prefix: #{defaults.$selector-base}#{defaults.$theme-aware-selector-prefix}#{$theme-name}#{defaults.$theme-aware-separator};
+
+        @each $ratio-selector, $value in defaults.$ratios {
+          @include theme.theme($theme-name) {
+            // e.g. `.dark:ratio-one-by-one` or `.light:ratio-two-by-one
+            #{$selector-prefix}#{defaults.$ratio-variant-selector-prefix}#{$ratio-selector} {
+              --#{root-defaults.$prefix}ratio: #{$value};
+            }
+          }
+        }
+      }
+    }
+  }
+
+  // Generate state-aware utilities.
+  @if defaults.$state-aware and root-defaults.$state-aware-utilities {
+    @each $state-name, $value in root-defaults.$state-selectors {
+      // e.g. `.hover:` or `.focus:`
+      $selector-prefix: #{defaults.$selector-base}#{defaults.$state-aware-selector-prefix}#{$state-name}#{defaults.$state-aware-separator};
+
+      @each $ratio-selector, $ratio-value in defaults.$ratios {
+        // e.g. `.hover:ratio-one-by-one` or `.focus:ratio-two-by-one
+        #{$selector-prefix}#{defaults.$ratio-variant-selector-prefix}#{$ratio-selector} {
+          @include state.state($state-name) {
+            --#{root-defaults.$prefix}ratio: #{$ratio-value};
+          }
+        }
+      }
+    }
+  }
+
+  // Generate container-aware utilities.
+  @if defaults.$container-aware and root-defaults.$container-aware-utilities {
+    @each $container-name in map.keys(root-defaults.$container-sizes) {
+      // e.g. `.md:` or `.lg:`
+      $selector-prefix: #{defaults.$selector-base}#{defaults.$container-aware-selector-prefix}#{$container-name}#{defaults.$container-aware-separator};
+
+      @each $ratio-selector, $value in defaults.$ratios {
+        @include container.up($container-name) {
+          // e.g. `.md:ratio-one-by-one` or `.lg:ratio-two-by-one`
+          #{$selector-prefix}#{defaults.$ratio-variant-selector-prefix}#{$ratio-selector} {
+            --#{root-defaults.$prefix}ratio: #{$value};
+          }
+        }
+      }
+    }
+  }
+}

package/{src → packages/core/src}/scss/utilities/ratio/_variables.scss

@@ -1,4 +1,4 @@
-// @graupl/graupl ratio utilities variables.
+// @graupl/core ratio utilities variables.
 //
 // These values are to be used to directly style components and provide a
 // cleaner way to reference custom properties.

package/{src → packages/core/src}/scss/utilities/spacing/_defaults.scss

@@ -1,4 +1,4 @@
-// @graupl/graupl spacing utilities default values.
+// @graupl/core spacing 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.
@@ -6,8 +6,26 @@
 // 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: true !default;
+$theme-aware: false !default;
+$state-aware: false !default;
+$container-aware: true !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;
+
+// Spacing properties.
 $base-spacing-properties: (
   g: gap,
   rg: row-gap,
@@ -44,6 +62,3 @@ $spacing-properties: map.merge(
   $base-spacing-properties,
   $custom-spacing-properties
 );
-
-// Responsive utility flag.
-$responsive: true !default;