@volverjs/style 0.1.22 → 0.1.24-beta.1

package/src/tools/mixin-modules/_helpers.scss

@@ -0,0 +1,23 @@
+@use 'sass:meta';
+@use 'sass:string';
+
+// ============================================
+// Utility Helpers
+// ============================================
+
+// Wrap selector with :where() for zero specificity
+// @param {String|List} $selector - The selector to wrap
+// @param {Bool} $enabled - Whether to wrap in :where()
+@mixin wrap-with-where($selector, $enabled: true) {
+	@if meta.type-of($selector) == 'map' or meta.type-of($selector) == 'list' {
+		$selector: #{$selector};
+	}
+
+	@if $enabled {
+		$selector: ':where(#{string.unquote($selector)})';
+	}
+
+	#{$selector} {
+		@content;
+	}
+}

package/src/tools/mixin-modules/_index.scss

@@ -0,0 +1,25 @@
+// ============================================
+// Mixins Index
+// Re-exports all mixins for easy importing
+// ============================================
+
+// Core helpers (wrap-with-where)
+@forward 'helpers';
+
+// CSS Custom Properties (spread-map-into-props)
+@forward 'props';
+
+// CSS Attributes (spread-map-into-attrs)
+@forward 'attrs';
+
+// CSS Layers (layer, define-layers)
+@forward 'layers';
+
+// Utilities (spread-map-into-utilities)
+@forward 'utilities';
+
+// BEM structure (spread-map-into-bem, modifiers, elements, states, breakpoints, transitions)
+@forward 'bem';
+
+// Theme utilities (spread-theme-component)
+@forward 'theme';

package/src/tools/mixin-modules/_layers.scss

@@ -0,0 +1,42 @@
+// ============================================
+// CSS @layer utilities
+// ============================================
+
+// Wrap content in a CSS @layer
+// @param {String} $name - Layer name (reset, props, utilities, components, themes)
+// @param {Bool} $enabled - Whether to wrap in @layer (default: false)
+// @param {String} $prefix - Layer prefix (default: 'volver')
+@mixin layer($name, $enabled: false, $prefix: 'volver') {
+	@if $enabled {
+		/* stylelint-disable-next-line layer-name-pattern */
+		@layer #{$prefix + '.' + $name} {
+			@content;
+		}
+	} @else {
+		@content;
+	}
+}
+
+// Define layer order (call once at the start of your stylesheet)
+// This establishes the cascade priority: later layers win
+// @param {Bool} $enabled - Whether to output @layer declaration
+// @param {List} $order - Layer order list
+// @param {String} $prefix - Layer prefix
+@mixin define-layers($enabled: false, $order: (reset, props, utilities, components, themes), $prefix: 'volver') {
+	@if $enabled {
+		$layers: null;
+
+		@each $name in $order {
+			$layer-name: $prefix + '.' + $name;
+
+			@if $layers {
+				$layers: $layers + ', ' + $layer-name;
+			} @else {
+				$layers: $layer-name;
+			}
+		}
+
+		/* stylelint-disable-next-line layer-name-pattern */
+		@layer #{$layers};
+	}
+}

package/src/tools/mixin-modules/_props.scss

@@ -0,0 +1,41 @@
+@use 'sass:map';
+@use 'sass:meta';
+@use 'sass:string';
+@use '../functions' as *;
+
+// ============================================
+// CSS Custom Properties (Variables) Mixin
+// ============================================
+
+// Transform a map into a list of CSS custom properties
+// @param {Map} $map - The map to transform
+// @param {String} $prefix - Variable name prefix
+// @param {String} $old-key - Previous key for recursion
+// @param {Bool} $deep - Whether to recurse into nested maps
+@mixin spread-map-into-props($map: (), $prefix: '', $old-key: '', $deep: true) {
+	@each $key, $value in $map {
+		$name: meta.inspect($key);
+
+		@if $name == meta.inspect($old-key) {
+			$name: $prefix;
+		} @else if $prefix != '' and meta.inspect($prefix) != meta.inspect($key) {
+			$name: $prefix + '-' + $key;
+		}
+
+		// fix name
+		$name: str-replace($name, '\\/', '-');
+
+		@if string.slice(meta.inspect($key), 1, 1) != '_' and
+			string.slice(meta.inspect($key), 1, 2) != '--' and
+			string.slice(meta.inspect($key), 1, 1) != '['
+		{
+			@if meta.type-of($value) == 'map' {
+				@if $deep {
+					@include spread-map-into-props($value, $name, $key);
+				}
+			} @else {
+				#{'--' + $name}: #{$value};
+			}
+		}
+	}
+}

package/src/tools/mixin-modules/_theme.scss

@@ -0,0 +1,354 @@
+@use 'sass:map';
+@use 'sass:list';
+@use 'sass:meta';
+@use 'props' as *;
+@use 'attrs' as *;
+
+// ============================================
+// Theme component utilities
+// Generates CSS for theme overrides without @extend
+// (needed to work inside media queries)
+// ============================================
+
+// Extract values from base-map that match the keys in theme-map
+// This is used to generate light reset rules
+// @param {Map} $base-map - Original component map with light values
+// @param {Map} $theme-map - Theme override map (used to determine which keys to extract)
+// @return {Map|null} - Map with light values for keys modified in theme-map, or null if empty
+@function extract-light-values($base-map, $theme-map) {
+	$result: ();
+
+	@each $key, $value in $theme-map {
+		@if map.has-key($base-map, $key) {
+			$base-value: map.get($base-map, $key);
+
+			@if meta.type-of($value) == 'map' and meta.type-of($base-value) == 'map' {
+				// Recursively extract nested maps
+				$nested: extract-light-values($base-value, $value);
+
+				@if $nested and list.length(map.keys($nested)) > 0 {
+					$result: map.set($result, $key, $nested);
+				}
+			} @else {
+				// Direct value - use the base (light) value
+				$result: map.set($result, $key, $base-value);
+			}
+		}
+	}
+
+	// Return null if empty map
+	@if list.length(map.keys($result)) == 0 {
+		@return null;
+	}
+
+	@return $result;
+}
+
+// Apply theme overrides to a component
+// - With $use-custom-props: true  → generates CSS variables only
+// - With $use-custom-props: false → generates CSS attributes directly
+// @param {Map} $base-map - Original component map (e.g., $vv-button)
+// @param {Map} $theme-map - Theme override map (e.g., $dark-vv-button)
+// @param {String} $component-name - Component name (e.g., 'vv-button')
+// @param {Map} $bps - Breakpoints map
+// @param {Bool} $use-custom-props - Whether to use CSS custom properties
+// @param {Bool} $generate-light-reset - Auto-generate light reset from base-map (default: true)
+// @param {String} $light-reset-selector - Selector for light reset (default: '.theme.theme--light')
+@mixin spread-theme-component(
+	$base-map,
+	$theme-map,
+	$component-name,
+	$bps: (xxs: 0),
+	$use-custom-props: true,
+	$generate-light-reset: true,
+	$light-reset-selector: '.theme.theme--light'
+) {
+	// Calculate light reset map from base-map if needed
+	$light-reset-map: null;
+
+	@if $generate-light-reset {
+		$light-reset-map: extract-light-values($base-map, $theme-map);
+	}
+
+	@if $use-custom-props {
+		// Generate CSS variables only (themes override variables)
+		@include spread-map-into-props(
+			$map: $theme-map,
+			$prefix: $component-name
+		);
+
+		// Light reset with custom props
+		@if $light-reset-map and $generate-light-reset {
+			#{$light-reset-selector} {
+				@include spread-map-into-props(
+					$map: $light-reset-map,
+					$prefix: $component-name
+				);
+			}
+		}
+	} @else {
+		// Generate CSS attributes directly for theme overrides
+		$selector: '.' + $component-name;
+
+		// Block styles (base attributes, ignoring nested structures)
+		#{$selector} {
+			@include spread-map-into-attrs(
+				$map: $theme-map,
+				$prefix: $component-name,
+				$props: false,
+				$ignore: (modifier, element, state, breakpoint, transition)
+			);
+		}
+
+		// Process modifiers recursively
+		@if map.has-key($theme-map, 'modifier') {
+			@include _theme-spread-modifiers(
+				$map: map.get($theme-map, 'modifier'),
+				$prefix: $component-name,
+				$block: $selector,
+				$bps: $bps
+			);
+		}
+
+		// Process elements
+		@if map.has-key($theme-map, 'element') {
+			@include _theme-spread-elements(
+				$map: map.get($theme-map, 'element'),
+				$prefix: $component-name,
+				$block: $selector,
+				$bps: $bps
+			);
+		}
+
+		// Process states at block level
+		@if map.has-key($theme-map, 'state') {
+			@include _theme-spread-states(
+				$map: map.get($theme-map, 'state'),
+				$prefix: $component-name,
+				$block: $selector,
+				$parent-selector: $selector,
+				$bps: $bps
+			);
+		}
+
+		// Generate light reset rules if enabled
+		@if $light-reset-map and $generate-light-reset {
+			#{$light-reset-selector} {
+				@include _theme-generate-all(
+					$map: $light-reset-map,
+					$prefix: $component-name,
+					$block: $selector,
+					$bps: $bps
+				);
+			}
+		}
+	}
+}
+
+// Helper to generate all theme rules (block, modifiers, elements, states)
+@mixin _theme-generate-all($map, $prefix, $block, $bps) {
+	// Block styles
+	#{$block} {
+		@include spread-map-into-attrs(
+			$map: $map,
+			$prefix: $prefix,
+			$props: false,
+			$ignore: (modifier, element, state, breakpoint, transition)
+		);
+	}
+
+	// Process modifiers
+	@if map.has-key($map, 'modifier') {
+		@include _theme-spread-modifiers(
+			$map: map.get($map, 'modifier'),
+			$prefix: $prefix,
+			$block: $block,
+			$bps: $bps
+		);
+	}
+
+	// Process elements
+	@if map.has-key($map, 'element') {
+		@include _theme-spread-elements(
+			$map: map.get($map, 'element'),
+			$prefix: $prefix,
+			$block: $block,
+			$bps: $bps
+		);
+	}
+
+	// Process states
+	@if map.has-key($map, 'state') {
+		@include _theme-spread-states(
+			$map: map.get($map, 'state'),
+			$prefix: $prefix,
+			$block: $block,
+			$parent-selector: $block,
+			$bps: $bps
+		);
+	}
+}
+
+// ============================================
+// Private helper mixins for theme spreading
+// ============================================
+
+// Spread modifiers for theme (no @extend)
+@mixin _theme-spread-modifiers($map, $prefix, $block, $parent-selector: null, $bps: (xxs: 0)) {
+	@each $mod-name, $mod-value in $map {
+		$mod-selector: '#{$block}#{$block}--#{$mod-name}';
+
+		@if $parent-selector {
+			$mod-selector: '#{$parent-selector}#{$block}--#{$mod-name}';
+		}
+
+		// Modifier base styles
+		#{$mod-selector} {
+			@include spread-map-into-attrs(
+				$map: $mod-value,
+				$prefix: $prefix,
+				$props: false,
+				$ignore: (modifier, element, state, breakpoint)
+			);
+		}
+
+		// States inside modifier
+		@if map.has-key($mod-value, 'state') {
+			@include _theme-spread-states(
+				$map: map.get($mod-value, 'state'),
+				$prefix: $prefix,
+				$block: $block,
+				$parent-selector: $mod-selector,
+				$bps: $bps
+			);
+		}
+
+		// Elements inside modifier
+		@if map.has-key($mod-value, 'element') {
+			@include _theme-spread-elements(
+				$map: map.get($mod-value, 'element'),
+				$prefix: $prefix,
+				$block: $block,
+				$parent-selector: $mod-selector,
+				$bps: $bps
+			);
+		}
+
+		// Nested modifiers
+		@if map.has-key($mod-value, 'modifier') {
+			@include _theme-spread-modifiers(
+				$map: map.get($mod-value, 'modifier'),
+				$prefix: $prefix,
+				$block: $block,
+				$parent-selector: $mod-selector,
+				$bps: $bps
+			);
+		}
+	}
+}
+
+// Spread elements for theme (no @extend)
+@mixin _theme-spread-elements($map, $prefix, $block, $parent-selector: null, $bps: (xxs: 0)) {
+	@each $el-name, $el-value in $map {
+		$el-selector: '#{$block}__#{$el-name}';
+		$full-selector: $el-selector;
+
+		@if $parent-selector {
+			$full-selector: '#{$parent-selector} #{$el-selector}';
+		}
+
+		// Element base styles
+		#{$full-selector} {
+			@include spread-map-into-attrs(
+				$map: $el-value,
+				$prefix: $prefix,
+				$props: false,
+				$ignore: (modifier, element, state, breakpoint)
+			);
+		}
+
+		// States inside element
+		@if map.has-key($el-value, 'state') {
+			@include _theme-spread-states(
+				$map: map.get($el-value, 'state'),
+				$prefix: $prefix,
+				$block: $el-selector,
+				$parent-selector: $parent-selector,
+				$bps: $bps
+			);
+		}
+	}
+}
+
+// Spread states for theme (no @extend)
+@mixin _theme-spread-states($map, $prefix, $block, $parent-selector: null, $bps: (xxs: 0)) {
+	$state-list: (
+		active, focus, hover, focus-within, target, visited, focus-visible,
+		disabled, checked, checked-within, multiple, selected, readonly,
+		empty, placeholder-shown, dirty, valid, invalid, indeterminate,
+		first-child, last-child, open, close, determinate, pressed, current
+	);
+
+	@each $state-name, $state-value in $map {
+		@if list.index($state-list, $state-name) {
+			$base: $block;
+
+			@if $parent-selector {
+				$base: $parent-selector;
+			}
+
+			// BEM modifier style: .block--state
+			#{$base}#{$block}--#{$state-name},
+			// Class style: .block.state
+			#{$base}.#{$state-name} {
+				@include spread-map-into-attrs(
+					$map: $state-value,
+					$prefix: $prefix,
+					$props: false,
+					$ignore: (modifier, element, state, breakpoint)
+				);
+			}
+
+			// Pseudo-class style based on state type
+			@if $state-name == 'disabled' or $state-name == 'readonly' or $state-name == 'multiple' {
+				#{$base}[#{$state-name}] {
+					@include spread-map-into-attrs(
+						$map: $state-value,
+						$prefix: $prefix,
+						$props: false,
+						$ignore: (modifier, element, state, breakpoint)
+					);
+				}
+			} @else if $state-name == 'focus-visible' {
+				#{$base}:not(:active):not([disabled]):not([tabindex="-1"]):not([aria-disabled="true"]):#{$state-name} {
+					@include spread-map-into-attrs(
+						$map: $state-value,
+						$prefix: $prefix,
+						$props: false,
+						$ignore: (modifier, element, state, breakpoint)
+					);
+				}
+			} @else if $state-name != 'current' {
+				#{$base}:not([disabled]):#{$state-name} {
+					@include spread-map-into-attrs(
+						$map: $state-value,
+						$prefix: $prefix,
+						$props: false,
+						$ignore: (modifier, element, state, breakpoint)
+					);
+				}
+			}
+
+			// Elements inside state
+			@if map.has-key($state-value, 'element') {
+				@include _theme-spread-elements(
+					$map: map.get($state-value, 'element'),
+					$prefix: $prefix,
+					$block: $block,
+					$parent-selector: '#{$base}#{$block}--#{$state-name}',
+					$bps: $bps
+				);
+			}
+		}
+	}
+}

package/src/tools/mixin-modules/_utilities.scss

@@ -0,0 +1,121 @@
+@use 'sass:meta';
+@use 'sass:string';
+@use '../functions' as *;
+@use '../breakpoints' as *;
+@use 'helpers' as *;
+
+// ============================================
+// Utilities Mixin
+// Generates utility classes from maps
+// ============================================
+
+// Transform a map into a list of utility classes
+// @param {Map|List} $map - The map or list to transform
+// @param {String} $class - Base class name
+// @param {String|List} $attribute - CSS attribute(s) to set
+// @param {String} $prop - CSS custom property name
+// @param {String} $name - Name for nested recursion
+// @param {Bool} $deep - Whether to recurse into nested maps
+// @param {Map} $bps - Breakpoints map
+// @param {String} $prefix - Class prefix for breakpoints
+// @param {Bool} $zero-specificity - Whether to wrap in :where()
+@mixin spread-map-into-utilities(
+	$map: (),
+	$class: '',
+	$attribute: '',
+	$prop: '',
+	$name: '',
+	$deep: true,
+	$bps: (xxs: 0),
+	$prefix: '',
+	$zero-specificity: false
+) {
+	@if (meta.type-of($map) == 'map' or meta.type-of($map) == 'list') and $attribute != '' {
+		@each $breakpoint, $breakpoint-value in $bps {
+			@if $breakpoint-value > 0 {
+				$prefix: $breakpoint + '\\:';
+			}
+
+			@each $key, $value in $map {
+				@if $name != '' and meta.inspect($key) != meta.inspect($name) {
+					$key: #{$name}-#{meta.inspect($key)};
+				}
+
+				@if meta.type-of($value) == 'map' and $deep {
+					@include spread-map-into-utilities(
+						$map: $value,
+						$class: $class,
+						$attribute: $attribute,
+						$prop: $prop,
+						$name: $key,
+						$bps: $bps,
+						$prefix: $prefix,
+						$zero-specificity: $zero-specificity
+					);
+				} @else {
+					$default: null;
+					$class-name: $class;
+					$key: meta.inspect($key);
+					$var: $prop;
+
+					// fix class name
+					@if $class-name != $key and $prop != $key {
+						@if $class-name != '' {
+							$class-name: $class-name + '-';
+						}
+
+						$class-name: $class-name + $key;
+					}
+
+					// fix variable name
+					@if $var != '' and $var != $key {
+						$var: $var + '-' + $key;
+					}
+
+					$var: str-replace($var, '\\/', '-');
+
+					// check if value is not a map (spacing-dynamic)
+					@if meta.type-of($value) != 'map' {
+						$default: $value;
+					}
+
+					// check if map is a list
+					@if meta.type-of($map) == 'list' and (not $default or $default == '') {
+						$default: $key;
+					}
+
+					@if meta.type-of($default) == 'string' {
+						$default: string.unquote($default);
+					}
+
+					%#{$prefix}#{$class-name} {
+						@include media-breakpoint-up($breakpoint, $bps) {
+							@if meta.type-of($attribute) != 'list' {
+								$attribute: ($attribute);
+							}
+
+							@each $attr in $attribute {
+								@if $default {
+									@if $var != '' {
+										#{$attr}: var(--#{$var}, $default);
+									} @else {
+										#{$attr}: $default;
+									}
+								} @else if $var != '' {
+									#{$attr}: var(--#{$var});
+								}
+							}
+						}
+					}
+
+					@include wrap-with-where(
+						$selector: '.' + $prefix + $class-name,
+						$enabled: $zero-specificity
+					) {
+						@extend %#{$prefix}#{$class-name};
+					}
+				}
+			}
+		}
+	}
+}

package/src/utilities/backgrounds.scss

@@ -1,5 +1,6 @@
 @use '../context' as *;
 
+@include layer(utilities, $use-css-layers, $layer-prefix) {
 // background-attachment
 @include spread-map-into-utilities(
 	$map: $background-attachment,
@@ -65,3 +66,5 @@
 	$prop: gradient,
 	$zero-specificity: $zero-specificity-for-utilities
 );
+
+}

package/src/utilities/borders.scss

@@ -1,6 +1,7 @@
 @use 'sass:map';
 @use '../context' as *;
 
+@include layer(utilities, $use-css-layers, $layer-prefix) {
 // border-radius
 @include spread-map-into-utilities(
 	$map: $border-radius,
@@ -88,3 +89,5 @@
 	$bps: $breakpoints,
 	$zero-specificity: $zero-specificity-for-utilities
 );
+
+}

package/src/utilities/colors.scss

@@ -1,5 +1,6 @@
 @use '../context' as *;
 
+@include layer(utilities, $use-css-layers, $layer-prefix) {
 // background-color
 @include spread-map-into-utilities(
 	$map: $colors,
@@ -35,3 +36,5 @@
 	$prop: color,
 	$zero-specificity: $zero-specificity-for-utilities
 );
+
+}

package/src/utilities/effects.scss

@@ -1,5 +1,6 @@
 @use '../context' as *;
 
+@include layer(utilities, $use-css-layers, $layer-prefix) {
 // box shadow
 @include spread-map-into-utilities(
 	$map: $box-shadow,
@@ -31,3 +32,5 @@
 	$attribute: background-blend-mode,
 	$zero-specificity: $zero-specificity-for-utilities
 );
+
+}

package/src/utilities/filters.scss

@@ -1,5 +1,6 @@
 @use '../context' as *;
 
+@include layer(utilities, $use-css-layers, $layer-prefix) {
 // blur
 @include spread-map-into-utilities(
 	$map: $blur,
@@ -31,3 +32,5 @@
 	$attribute: backdrop-filter,
 	$zero-specificity: $zero-specificity-for-utilities
 );
+
+}

package/src/utilities/flexbox.scss

@@ -2,6 +2,7 @@
 @use 'sass:meta';
 @use '../context' as *;
 
+@include layer(utilities, $use-css-layers, $layer-prefix) {
 // flex direction
 @include spread-map-into-utilities(
 	$map: $flex-direction,
@@ -134,3 +135,5 @@
 		$zero-specificity: $zero-specificity-for-utilities
 	);
 }
+
+}

package/src/utilities/grid.scss

@@ -1,6 +1,7 @@
 @use 'sass:map';
 @use '../context' as *;
 
+@include layer(utilities, $use-css-layers, $layer-prefix) {
 // grid template columns
 @include spread-map-into-utilities(
 	$map: $grid-template-columns,
@@ -82,3 +83,5 @@
 		$zero-specificity: $zero-specificity-for-utilities
 	);
 }
+
+}