@nuvoui/core 1.1.7 → 1.2.0

package/src/styles/utilities/_position.scss

@@ -1,106 +1,212 @@
-@use './variables' as *;
+@use '../abstracts'  as *;
+
+/**
+ * @component Position
+ * @description Controls element positioning and placement within the document flow
+ *
+ * @example
+ * <!-- Basic positioning -->
+ * <div class="relative">
+ *   <div class="absolute top-0 right-0">
+ *     Positioned in top-right corner
+ *   </div>
+ * </div>
+ * 
+ * <!-- Sticky header -->
+ * <header class="sticky top-0">
+ *   This header sticks to the top when scrolling
+ * </header>
+ * 
+ * <!-- Responsive positioning -->
+ * <div class="relative@md">
+ *   <div class="absolute@md top-2 left-2">
+ *     Only positioned on medium screens and up
+ *   </div>
+ * </div>
+ *
+ * @classes
+ * Position Types:
+ * - static: Default position, follows document flow
+ * - relative: Positioned relative to normal position
+ * - absolute: Positioned relative to nearest positioned ancestor
+ * - fixed: Positioned relative to viewport
+ * - sticky: Positioned based on scroll position
+ * 
+ * Placement:
+ * - top-{value}: Sets top position
+ * - right-{value}: Sets right position
+ * - bottom-{value}: Sets bottom position
+ * - left-{value}: Sets left position
+ * 
+ * Common values: 0, 1, 2, 3, 4, 5, 10, etc. (based on spacing scale)
+ *
+ * @responsive
+ * All position classes support responsive variants using @breakpoint suffix:
+ * - relative@md: Relative positioning on medium screens and up
+ * - top-0@lg: Zero top position on large screens
+ *
+ * @see z-index, transform
+ */
+
+
+// -----------------------------------------------
+// MIXINS
+// -----------------------------------------------
 
-// Position Mixins
+ 
+/**
+ * @mixin static
+ * @description Sets position to static (default document flow)
+ * @example
+ * .element {
+ *   @include static;
+ * }
+ */
 @mixin static {
   position: static;
 }
 
+/**
+ * @mixin relative
+ * @description Sets position to relative, creating a positioning context
+ * @example
+ * .container {
+ *   @include relative;
+ * }
+ */
 @mixin relative {
   position: relative;
 }
 
+/**
+ * @mixin absolute
+ * @description Sets position to absolute, removing from normal document flow
+ * @example
+ * .popup {
+ *   @include absolute;
+ *   top: 0;
+ *   left: 0;
+ * }
+ */
 @mixin absolute {
   position: absolute;
 }
 
+/**
+ * @mixin absolute
+ * @description Sets position to absolute, removing from normal document flow
+ * @example
+ * .popup {
+ *   @include absolute;
+ *   top: 0;
+ *   left: 0;
+ * }
+ */
 @mixin fixed {
   position: fixed;
 } 
  
+/**
+ * @mixin sticky
+ * @description Creates a sticky element that remains in view during scrolling
+ * @example
+ * .nav {
+ *   @include sticky;
+ * }
+ */
 @mixin sticky {
   position: sticky;
   z-index: 999;
   top: 0;
 } 
 
-// Position Classes
-.static {
-  @include static;
-}
-
-.relative {
-  @include relative;
-}
-
-.absolute {
-  @include absolute;
-}
-
-.fixed {
-  @include fixed;
-}
-
-.sticky {
-  @include sticky;
-}
-
-// Responsive Position Classes
-@each $breakpoint, $width in $breakpoints {
-  @media (min-width: #{$width}) {
-    .static\@#{$breakpoint} {
-      @include static;
-    }
-    .relative\@#{$breakpoint} {
-      @include relative;
-    }
-    .absolute\@#{$breakpoint} {
-      @include absolute;
-    }
-    .fixed\@#{$breakpoint} {
-      @include fixed;
-    }
-    .sticky\@#{$breakpoint} {
-      @include sticky;
-    }
-  }
-}
-
 
-// Top, Right, Bottom, Left Mixins
-@mixin top($value) {
-  top: if($value == 0, $value, $value + px);
-}
+/**
+ * @mixin top
+ * @description Sets the top position of an element
+ * @param {Number|Length} $value - Position value (in px, rem, etc.)
+ * @example
+ * .toast {
+ *   @include absolute;
+ *   @include top(1rem);
+ * }
+ */
+ @mixin top($value) {top: $value; }
+
+ /**
+  * @mixin right
+  * @description Sets the right position of an element
+  * @param {Number|Length} $value - Position value (in px, rem, etc.)
+  * @example
+  * .badge {
+  *   @include absolute;
+  *   @include right(0);
+  * }
+  */
+ @mixin right($value) {right: $value; }
+ 
+ /**
+  * @mixin bottom
+  * @description Sets the bottom position of an element
+  * @param {Number|Length} $value - Position value (in px, rem, etc.)
+  * @example
+  * .footer {
+  *   @include fixed;
+  *   @include bottom(0);
+  * }
+  */
+ @mixin bottom($value) {bottom: $value; }
+ 
+ /**
+  * @mixin left
+  * @description Sets the left position of an element
+  * @param {Number|Length} $value - Position value (in px, rem, etc.)
+  * @example
+  * .sidebar {
+  *   @include fixed;
+  *   @include left(0);
+  * }
+  */
+ @mixin left($value) {left: $value; }
 
-@mixin right($value) {
-  right: if($value == 0, $value, $value + px);
-}
 
-@mixin bottom($value) {
-  bottom: if($value == 0, $value, $value + px);
-}
 
-@mixin left($value) {
-  left: if($value == 0, $value, $value + px);
-}
+// -----------------------------------------------
+// UTILITY CLASSES
+// -----------------------------------------------
 
-// Top, Right, Bottom, Left Classes
-@each $i in $spacings {
-  .top-#{$i} {@include top($i);}
-  .right-#{$i} {@include right($i);}
-  .bottom-#{$i} {@include bottom($i);}
-  .left-#{$i} {@include left($i);}
+// Position Classes
+.static { @include static; }
+.relative { @include relative; }
+.absolute { @include absolute; }
+.fixed { @include fixed; }
+.sticky { @include sticky; }
+
+// Placement Classes
+@each $key, $value in $spacings {
+  .top-#{$key} { @include top($value); }
+  .right-#{$key} { @include right($value); }
+  .bottom-#{$key} { @include bottom($value); }
+  .left-#{$key} { @include left($value); }
 }
 
+// -----------------------------------------------
+// RESPONSIVE CLASSES
+// -----------------------------------------------
 
-// Pixel widths based on spacing scale
+// Responsive Position Classes
 @each $breakpoint, $width in $breakpoints {
   @media (min-width: #{$width}) {
-      // Generate utilities from spacing map
-      @each $i in $spacings {
-          .top-#{$i}\@#{$breakpoint} {height: if($i == 0, $i, $i + px);}
-          .right-#{$i}\@#{$breakpoint} {width: if($i == 0, $i, $i + px);}
-          .bottom-#{$i}\@#{$breakpoint} {min-width: if($i == 0, $i, $i + px);}
-          .left-#{$i}\@#{$breakpoint} {min-height: if($i == 0, $i, $i + px);}
-      }
+    .static\@#{$breakpoint} {@include static;}
+    .relative\@#{$breakpoint} {@include relative;}
+    .absolute\@#{$breakpoint} {@include absolute;}
+    .fixed\@#{$breakpoint} {@include fixed;}
+    .sticky\@#{$breakpoint} {@include sticky;}
+    @each $key, $value in $spacings {
+        .top-#{$key}\@#{$breakpoint} {@include top($value);}
+        .right-#{$key}\@#{$breakpoint} {@include right($value);}
+        .bottom-#{$key}\@#{$breakpoint} {@include bottom($value);}
+        .left-#{$key}\@#{$breakpoint} {@include left($value);}
+    }
   }
 }

package/src/styles/utilities/_shadows.scss

@@ -1,82 +1,93 @@
 // _shadows.scss
-@use 'sass:map';
-@use 'sass:math';
-@use 'sass:string';
-@use './variables' as *;
-
-
-// Shadow Variables
-$shadow-colors: (
-  'default': rgb(0 0 0 / 10%),
-  'dark': rgb(0 0 0 / 20%),
-  'darker': rgb(0 0 0 / 35%),
-  'darkest': rgb(0 0 0 / 50%),
-);
+@use "sass:map";
+@use "sass:math";
+@use "sass:string";
+@use "../abstracts" as VAR;
 
 $shadow-sizes: (
-  'sm': (
-    'x': 0,
-    'y': 1px,
-    'blur': 2px,
-    'spread': 0
+  "sm": (
+    "x": 0,
+    "y": 1px,
+    "blur": 2px,
+    "spread": 0,
+  ),
+  "md": (
+    "x": 0,
+    "y": 4px,
+    "blur": 6px,
+    "spread": -1px,
   ),
-  'md': (
-    'x': 0,
-    'y': 4px,
-    'blur': 6px,
-    'spread': -1px
+  "lg": (
+    "x": 0,
+    "y": 10px,
+    "blur": 15px,
+    "spread": -3px,
   ),
-  'lg': (
-    'x': 0,
-    'y': 10px,
-    'blur': 15px,
-    'spread': -3px
+  "xl": (
+    "x": 0,
+    "y": 20px,
+    "blur": 25px,
+    "spread": -5px,
   ),
-  'xl': (
-    'x': 0,
-    'y': 20px,
-    'blur': 25px,
-    'spread': -5px
+  "hero": (
+    "x": 0,
+    "y": 20px,
+    "blur": 25px,
+    "spread": 5px,
   ),
-  'hero': (
-    'x': 0,
-    'y': 20px,
-    'blur': 25px,
-    'spread': 5px
+  "monster": (
+    "x": 0,
+    "y": 20px,
+    "blur": 55px,
+    "spread": 20px,
   ),
-  'monster': (
-    'x': 0,
-    'y': 20px,
-    'blur': 55px,
-    'spread': 20px
-  )
 );
 
-// Shadow Mixins
+/**
+* Generates a CSS shadow string from a given size.
+*
+* @param {String} $size - The shadow size.
+* @param {String} $color - The shadow color.
+* @return {String} - The CSS shadow string.
+*/
+
 @mixin shadow-base($x, $y, $blur, $spread, $color) {
-  transition: box-shadow 0.2s ease-in-out;
   box-shadow: $x $y $blur $spread $color;
 }
 
-@mixin shadow($size: 'md', $color: 'default') {
+/**
+* Generates a CSS shadow string from a given size.
+*
+* @param {String} $size - The shadow size.
+* @param {String} $color - The shadow color.
+*/
+@mixin shadow($size: "md", $color: "default") {
+  @if not map.has-key($shadow-sizes, $size) {
+    @warn "Shadow size '#{$size}' not found in $shadow-sizes map";
+    $size: "md"; // Fallback to default
+  }
+  @if not map.has-key(VAR.$shadow-colors, $color) {
+    @warn "Shadow color '#{$color}' not found in VAR.$shadow-colors map";
+    $color: "default"; // Fallback to default
+  }
+
   $shadow: map.get($shadow-sizes, $size);
-  $shadow-color: map.get($shadow-colors, $color);
+  $shadow-color: map.get(VAR.$shadow-colors, $color);
   @include shadow-base(
-    map.get($shadow, 'x'),
-    map.get($shadow, 'y'),
-    map.get($shadow, 'blur'),
-    map.get($shadow, 'spread'),
+    map.get($shadow, "x"),
+    map.get($shadow, "y"),
+    map.get($shadow, "blur"),
+    map.get($shadow, "spread"),
     $shadow-color
   );
 }
 
-@mixin shadow-inset($size: 'md', $color: 'default') {
+@mixin shadow-inset($size: "md", $color: "default") {
   $shadow: map.get($shadow-sizes, $size);
-  $shadow-color: map.get($shadow-colors, $color);
-  
-  box-shadow: inset map.get($shadow, 'x') map.get($shadow, 'y') 
-             map.get($shadow, 'blur') map.get($shadow, 'spread') 
-             $shadow-color;
+  $shadow-color: map.get(VAR.$shadow-colors, $color);
+
+  box-shadow: inset map.get($shadow, "x") map.get($shadow, "y") map.get($shadow, "blur") map.get($shadow, "spread")
+    $shadow-color;
 }
 
 // Utility Classes
@@ -88,19 +99,135 @@ $shadow-sizes: (
   .shadow-#{$size} {
     @include shadow($size);
   }
-  
-  .shadow-#{$size}-dark {
-    @include shadow($size, 'dark');
+
+  // Shadow with color variants
+  @each $color-name, $color-value in VAR.$shadow-colors {
+    @if $color-name != "default" {
+      .shadow-#{$size}-#{$color-name} {
+        @include shadow($size, $color-name);
+      }
+    }
   }
-  
+
   .shadow-inset-#{$size} {
     @include shadow-inset($size);
   }
+
+  // Inset shadows with color variants
+  @each $color-name, $color-value in VAR.$shadow-colors {
+    @if $color-name != "default" {
+      .shadow-inset-#{$size}-#{$color-name} {
+        @include shadow-inset($size, $color-name);
+      }
+    }
+  }
+
+  // Hover shadows
+  .hover\:shadow-#{$size}:hover {
+    @include shadow($size);
+  }
+
+  // Hover shadows with color variants
+  @each $color-name, $color-value in VAR.$shadow-colors {
+    @if $color-name != "default" {
+      .hover\:shadow-#{$size}-#{$color-name}:hover {
+        @include shadow($size, $color-name);
+      }
+    }
+  }
+
+  // Focus shadows
+  .focus\:shadow-#{$size}:focus {
+    @include shadow($size);
+  }
+
+  // Focus shadows with color variants
+  @each $color-name, $color-value in VAR.$shadow-colors {
+    @if $color-name != "default" {
+      .focus\:shadow-#{$size}-#{$color-name}:focus {
+        @include shadow($size, $color-name);
+      }
+    }
+  }
+
+  // Active shadows
+  .active\:shadow-#{$size}:active {
+    @include shadow($size);
+  }
+
+  // Active shadows with color variants
+  @each $color-name, $color-value in VAR.$shadow-colors {
+    @if $color-name != "default" {
+      .active\:shadow-#{$size}-#{$color-name}:active {
+        @include shadow($size, $color-name);
+      }
+    }
+  }
+}
+
+// Responsive variants
+@each $breakpoint, $width in VAR.$breakpoints {
+  @media (min-width: #{$width}) {
+    @each $size, $values in $shadow-sizes {
+      // Regular shadows with breakpoints
+      .shadow-#{$size}\@#{$breakpoint} {
+        @include shadow($size);
+      }
+
+      // Shadows with color variants at breakpoints
+      @each $color-name, $color-value in VAR.$shadow-colors {
+        @if $color-name != "default" {
+          .shadow-#{$size}-#{$color-name}\@#{$breakpoint} {
+            @include shadow($size, $color-name);
+          }
+        }
+      }
+
+      // Hover shadows with breakpoints
+      .hover\:shadow-#{$size}\@#{$breakpoint}:hover {
+        @include shadow($size);
+      }
+
+      // Hover shadows with color variants at breakpoints
+      @each $color-name, $color-value in VAR.$shadow-colors {
+        @if $color-name != "default" {
+          .hover\:shadow-#{$size}-#{$color-name}\@#{$breakpoint}:hover {
+            @include shadow($size, $color-name);
+          }
+        }
+      }
+
+      // Focus shadows with breakpoints
+      .focus\:shadow-#{$size}\@#{$breakpoint}:focus {
+        @include shadow($size);
+      }
+
+      // Focus shadows with color variants at breakpoints
+      @each $color-name, $color-value in VAR.$shadow-colors {
+        @if $color-name != "default" {
+          .focus\:shadow-#{$size}-#{$color-name}\@#{$breakpoint}:focus {
+            @include shadow($size, $color-name);
+          }
+        }
+      }
+    }
+  }
 }
 
-// Hover variants
-.shadow-hover {
-  &:hover {
-    @include shadow('lg');
+@for $i from 1 through 5 {
+  .elevation-#{$i} {
+    @if $i == 1 {
+      @include shadow("sm");
+    } @else if $i == 2 {
+      @include shadow("md");
+    } @else if $i == 3 {
+      @include shadow("lg");
+    } @else if $i == 4 {
+      @include shadow("xl");
+    } @else if $i == 5 {
+      @include shadow("monster");
+    }
+
+    z-index: $i;
   }
-}
+}