zeus-css 1.0.0

package/scss/foundation/core/engine/_fluid-core.scss

@@ -0,0 +1,54 @@
+// ╔══════════════════════════════════════════════════════════════╗
+// ║  ⚡ Zeus CSS — Fluid Core                                      ║
+// ║                                                               ║
+// ║  Framework internal engine and mixins for fluid core.         ║
+// ╚══════════════════════════════════════════════════════════════╝
+
+@use "sass:math";
+
+// ╔══════════════════════════════════════════════════════════════╗
+// ║  ⚙️  Zeus Fluid Core — shared engine for clamp() generation  ║
+// ║                                                              ║
+// ║  Private file — NOT part of the public API.                  ║
+// ║  Consumed by:                                                ║
+// ║    sizing.scss         → useclamp-sizing()   (px output)     ║
+// ║    typography-calc.scss → useclamp-typography() (rem output) ║
+// ║                                                              ║
+// ║  Single source of truth for:                                 ║
+// ║    · precision rounding  (round-to)                          ║
+// ║    · linear fluid formula (zeus-cqi-fluid)                   ║
+// ║                                                              ║
+// ║  Output: native clamp(min, preferred, max)                   ║
+// ║    clamp() is faster to parse than max(min()) and produces   ║
+// ║    more compact, readable compiled CSS output.               ║
+// ╚══════════════════════════════════════════════════════════════╝
+
+// ── round-to($value, $digits) ───────────────────────────────────
+// Rounds $value to $digits decimal places.
+// Prevents floating-point noise in compiled CSS output.
+//   round-to(1.041666, 3) → 1.042
+//   round-to(0.427083, 3) → 0.427
+@function round-to($value, $digits: 1) {
+  $factor: math.pow(10, $digits);
+  @return math.div(math.round($value * $factor), $factor);
+}
+
+// ── zeus-cqi-fluid($low, $high, $c-floor, $c-ceil, $unit, $accuracy) ──
+//
+// Engine for dynamic value interpolation using Container Queries.
+// Uses native clamp() for faster browser parsing and cleaner CSS output.
+//
+// Output: clamp(${low}${unit}, calc(...cqi), ${high}${unit})
+//
+@function zeus-cqi-fluid($low, $high, $c-floor, $c-ceil, $unit, $accuracy: 1, $step: 0.1) {
+  $raw-slope: math.div($high - $low, $c-ceil - $c-floor);
+  $slope-cqi: round-to($raw-slope * 100, $accuracy);
+
+  // Derive intercept using rounded slope so endpoints match $low and $high with 100% precision
+  $intercept: $low - (math.div($slope-cqi, 100) * $c-floor);
+  $intercept-px: round-to($intercept, $accuracy);
+
+  $preferred-value: round(calc(#{$intercept-px}#{$unit} + #{$slope-cqi}cqi), #{$step}#{$unit});
+
+  @return clamp(#{$low}#{$unit}, #{$preferred-value}, #{$high}#{$unit});
+}

package/scss/foundation/core/engine/animations.scss

@@ -0,0 +1,91 @@
+// ╔══════════════════════════════════════════════════════════════╗
+// ║  ⚡ Zeus CSS — Animations                                      ║
+// ║                                                               ║
+// ║  Framework internal engine and mixins for animations.         ║
+// ╚══════════════════════════════════════════════════════════════╝
+
+@use "sass:map";
+
+// ╔══════════════════════════════════════════════════════════════╗
+// ║  🎬 Zeus Animation Engine — mixins only, no top-level CSS    ║
+// ║                                                              ║
+// ║  This file is part of the zeus.scss module-only entry point  ║
+// ║  (@use "zeus" as * inside .module.scss files) and MUST NOT   ║
+// ║  emit any top-level CSS — every component consuming it would ║
+// ║  otherwise get a duplicate copy of that CSS in its own       ║
+// ║  compiled output.                                            ║
+// ║                                                              ║
+// ║  The @keyframes these mixins reference (zeus-fade-in, etc.)  ║
+// ║  are defined ONCE, globally, in:                              ║
+// ║    views/render/classes/_animations.scss                     ║
+// ║  which is only ever compiled as part of foundation.scss.      ║
+// ║  CSS @keyframes names are global page-wide identifiers, so    ║
+// ║  this works correctly even though the two files are separate.║
+// ╚══════════════════════════════════════════════════════════════╝
+
+
+// ─── MIXINS ────────────────────────────────────────────────────
+// Each mixin sets animation properties only — no @keyframes inside.
+
+// 1. Fade In
+// Usage: @include fade-in(0.5s, 0.2s);
+@mixin fade-in($duration: 0.3s, $delay: 0s, $timing: ease-in-out) {
+  opacity: 0;
+  animation: zeus-fade-in $duration $timing $delay forwards;
+}
+
+// 2. Slide In (from any direction)
+// Usage: @include slide-in(left, 0.4s);
+@mixin slide-in(
+  $direction: bottom,
+  $duration: 0.3s,
+  $delay: 0s,
+  $timing: ease-out
+) {
+  opacity: 0;
+
+  @if $direction == bottom {
+    animation: zeus-slide-in-bottom $duration $timing $delay forwards;
+  } @else if $direction == top {
+    animation: zeus-slide-in-top $duration $timing $delay forwards;
+  } @else if $direction == left {
+    animation: zeus-slide-in-left $duration $timing $delay forwards;
+  } @else if $direction == right {
+    animation: zeus-slide-in-right $duration $timing $delay forwards;
+  }
+}
+
+// 3. Scale (hover zoom)
+// Usage: @include scale(1.1, 0.3s);
+@mixin scale($scale: 1.05, $duration: 0.3s, $timing: ease-in-out) {
+  transition: transform $duration $timing;
+
+  &:hover,
+  &:focus {
+    transform: scale($scale);
+  }
+}
+
+// 4. Bounce
+// Usage: @include bounce(0.6s, infinite);
+@mixin bounce($duration: 0.8s, $iteration: 1, $delay: 0s) {
+  animation: zeus-bounce $duration ease-in-out $delay $iteration;
+}
+
+// 5. Pulse (heartbeat)
+// Usage: @include pulse(1.5s, infinite);
+@mixin pulse($duration: 1s, $iteration: infinite) {
+  animation: zeus-pulse $duration ease-in-out $iteration;
+}
+
+// 6. Rotate
+// Usage: @include rotate(360deg, 2s, linear, infinite);
+@mixin rotate($degrees: 360deg, $duration: 1s, $timing: linear, $iteration: 1) {
+  --_zeus-rotate-deg: #{$degrees};
+  animation: zeus-rotate $duration $timing $iteration;
+}
+
+// Note: the scroll-driven animation classes (.z-scroll-reveal/-tilt/-scale)
+// and ALL @keyframes (including the ones the mixins above reference) live in
+// views/render/classes/_animations.scss — see the header comment at the top
+// of this file for why.

package/scss/foundation/core/engine/buttons.scss

@@ -0,0 +1,226 @@
+// ╔══════════════════════════════════════════════════════════════╗
+// ║  ⚡ Zeus CSS — Buttons                                         ║
+// ║                                                               ║
+// ║  Framework internal engine and mixins for buttons.            ║
+// ╚══════════════════════════════════════════════════════════════╝
+
+@use "sass:map";
+@use "../buttons/variants" as *;
+@use "../design/buttons/sizes" as *;
+@use "./helpers" as *;
+@use "./sizing" as *;
+@use "./layout" as *;
+
+// ------------------------------------------------------------
+// Foundation: Base button reset & structure
+// ------------------------------------------------------------
+@mixin button-base-reset() {
+  // Layout & Display
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  box-sizing: border-box;
+
+  // Box model parameters
+  margin: 0;
+  padding: 0;
+  gap: var(--space-sm);
+
+  // Border & Outline
+  border: none;
+  border-radius: 0;
+  outline: none;
+
+  // Background & Color
+  background: none;
+  color: var(--color-text);
+
+  // Text styling attributes
+  font: var(--text-link);
+  line-height: 1;
+  text-align: center;
+  text-decoration: none;
+
+  // Interaction
+  cursor: pointer;
+  user-select: none;
+  -webkit-tap-highlight-color: transparent;
+
+  // Disabled state
+  &[disabled] {
+    opacity: 0.5;
+    pointer-events: none;
+    cursor: default;
+  }
+
+  // Remove browser defaults
+  &[type="button"],
+  &[type="reset"],
+  &[type="submit"] {
+    appearance: none;
+    -webkit-appearance: none;
+    -moz-appearance: none;
+  }
+
+  // Accessible focus
+  &:focus {
+    outline: revert;
+  }
+}
+
+// ------------------------------------------------------------
+// Layout: Standard button padding & shape
+// ------------------------------------------------------------
+@mixin button-structure() {
+  // Padding presets
+  padding: var(--space-md) var(--space-lg);
+  // gap: var(--space-sm);
+
+  //default width
+  width: fit-content;
+
+  // Border
+  border-radius: var(--border-radius-sm);
+
+  // Layout adjustments
+  align-items: center;
+  justify-content: space-between;
+
+  // Inner text flow
+  text-align: center;
+  text-decoration: none;
+}
+
+// ╔══════════════════════════════════════════════════════════════╗
+// ║  🔘 Zeus Button Engine                                       ║
+// ║                                                              ║
+// ║  Pattern: State Map → Direct Render (no intermediate fn)     ║
+// ╚══════════════════════════════════════════════════════════════╝
+
+/// Render a map of CSS properties
+@mixin _render($props) {
+  @if $props and $props != null {
+    @each $prop, $val in $props {
+      #{$prop}: #{$val};
+    }
+  }
+}
+
+/// Apply all states for a button variant
+/// Uses direct map access instead of a getter function
+@mixin button-apply-variant($variant: "primary") {
+  @if not map.has-key($button-variants, $variant) {
+    @error "[Zeus Button] Unknown variant '#{$variant}'. Available: #{map.keys($button-variants)}";
+  }
+
+  $states: map.get($button-variants, $variant);
+
+  // Default state — always present
+  @include _render(map.get($states, "default"));
+
+  // Interactive states — guard with :not([disabled])
+  $hover: map.get($states, "hover");
+  $active: map.get($states, "active");
+
+  @if $hover {
+    &:not([disabled]):hover {
+      @include _render($hover);
+    }
+  }
+
+  @if $active {
+    &:not([disabled]):active {
+      @include _render($active);
+    }
+  }
+}
+
+// ╔══════════════════════════════════════════════════════════════╗
+// ║  Public API: Complete button mixins                          ║
+// ╚══════════════════════════════════════════════════════════════╝
+@mixin btn-primary() {
+  @include button-base-reset();
+  @include button-structure();
+  @include button-apply-variant("primary");
+}
+
+@mixin btn-secondary() {
+  @include button-base-reset();
+  @include button-structure();
+  @include button-apply-variant("secondary");
+}
+
+@mixin btn-tertiary() {
+  @include button-base-reset();
+  @include button-structure();
+  @include button-apply-variant("tertiary");
+}
+
+@mixin btn-icon-only() {
+  @include button-base-reset();
+  @include box-size(md);
+
+  // Icon-specific overrides
+  padding: 0;
+  justify-content: center;
+
+  @include button-apply-variant("icon-only");
+}
+
+// ------------------------------------------------------------
+// Dynamic Button Variant Generator
+// Creates a complete button with base, structure, and variant
+// ------------------------------------------------------------
+@mixin btn-variant($variant: "primary") {
+  @include button-base-reset();
+  @include button-structure();
+  @include button-apply-variant($variant);
+}
+
+// ------------------------------------------------------------
+// Size System: Apply button size from tokens
+// Clamp by default — always fluid, no flag check
+// ------------------------------------------------------------
+@mixin btn-size($size: "md") {
+  @if not map.has-key($button-sizes, $size) {
+    @error "Invalid button size '#{$size}'. Available: #{map.keys($button-sizes)}";
+  }
+
+  $size-config: map.get($button-sizes, $size);
+
+  // Font size
+  @if map.has-key($size-config, "font") {
+    $font-config: map.get($size-config, "font");
+    $min: map.get($font-config, "floor");
+    $max: map.get($font-config, "ceil");
+    font-size: useclamp-sizing($min, $max);
+  }
+
+  // Padding Y (block axis)
+  @if map.has-key($size-config, "py") {
+    $py: map.get($size-config, "py");
+    $min: map.get($py, "floor");
+    $max: map.get($py, "ceil");
+    padding-block: useclamp-sizing($min, $max);
+  }
+
+  // Padding X (inline axis) — logical property, not left/right, so RTL
+  // layouts get the correct side without a separate override.
+  @if map.has-key($size-config, "px") {
+    $px: map.get($size-config, "px");
+    $min: map.get($px, "floor");
+    $max: map.get($px, "ceil");
+    padding-inline: useclamp-sizing($min, $max);
+  }
+
+  // Line height
+  @if map.has-key($size-config, "line-height") {
+    line-height: map.get($size-config, "line-height");
+  }
+
+  // Border radius
+  @if map.has-key($size-config, "border-radius") {
+    $radius: map.get($size-config, "border-radius");
+    border-radius: var(--border-radius-#{$radius});
+  }
+}

package/scss/foundation/core/engine/color-api.scss

@@ -0,0 +1,37 @@
+// ╔══════════════════════════════════════════════════════════════╗
+// ║  ⚡ Zeus CSS — Color Api                                       ║
+// ║                                                               ║
+// ║  Framework internal engine and mixins for color api.          ║
+// ╚══════════════════════════════════════════════════════════════╝
+
+@use "sass:map";
+@use "sass:meta";
+@use "sass:color";
+@use "../../../zeus.config" as config;
+@use "./helpers" as *;
+
+// ╔══════════════════════════════════════════════════════════════╗
+// ║  🎨 Zeus Color API — Universal Palette Mode                  ║
+// ║                                                              ║
+// ║  Usage:                                                      ║
+// ║    color("primary")              → oklch(...)                ║
+// ║    color("primary", $alpha: 0.5) → oklch(... / 0.5)          ║
+// ╚══════════════════════════════════════════════════════════════╝
+
+// Internal: flat lookup map directly from config
+$_flat-palette: config.$zeus-colors !default;
+
+/// Retrieve any color from the design palette with optional alpha
+@function color($name, $alpha: 1) {
+  $resolved: map-get-safe($_flat-palette, $name);
+
+  @if $resolved == null {
+    @error "[Zeus Color] '#{$name}' not found in palette. Available: #{map.keys($_flat-palette)}";
+  }
+
+  @if $alpha < 1 {
+    @return color.change($resolved, $alpha: $alpha);
+  }
+
+  @return $resolved;
+}

package/scss/foundation/core/engine/helpers.scss

@@ -0,0 +1,39 @@
+// ╔══════════════════════════════════════════════════════════════╗
+// ║  ⚡ Zeus CSS — Helpers                                         ║
+// ║                                                               ║
+// ║  Framework internal engine and mixins for helpers.            ║
+// ╚══════════════════════════════════════════════════════════════╝
+
+@use "sass:map";
+@use "sass:meta";
+@use "sass:string";
+
+// ============================================================
+// Helper Functions
+// ============================================================
+
+//-----------------------------------------------------------------
+// Extracts values from the provided map structure with type validation and unquoted key normalization
+@function map-get-safe($map, $key) {
+  @if meta.type-of($map) != "map" {
+    @return null;
+  }
+  // Direct key match (fast path)
+  @if map.has-key($map, $key) {
+    @return map.get($map, $key);
+  }
+
+  // Normalize both candidate key and map keys to unquoted strings and compare.
+  $needle: string.unquote("#{$key}");
+
+  @each $k in map.keys($map) {
+    $candidate: string.unquote("#{$k}");
+    @if $candidate == $needle {
+      @return map.get($map, $k);
+    }
+  }
+
+  // Not found
+  @return null;
+}
+//-----------------------------------------------------------------

package/scss/foundation/core/engine/layout.scss

@@ -0,0 +1,156 @@
+// ╔══════════════════════════════════════════════════════════════╗
+// ║  ⚡ Zeus CSS — Layout                                          ║
+// ║                                                               ║
+// ║  Framework internal engine and mixins for layout.             ║
+// ╚══════════════════════════════════════════════════════════════╝
+
+@use "sass:map";
+@use "./responsive" as *;
+@use "../design/borders/border-radius" as *;
+@use "../design/borders/border-line" as *;
+@use "../design/dimensions/sizes" as *;
+@use "../design/dimensions/spaces" as *;
+@use "./helpers" as *;
+@use "./sizing" as *;
+
+// === adaptive private mixin ===
+// CSS-Var-First: references the :root token instead of recomputing clamp()
+// inline — the computation lives once in root-generator.scss. Smaller
+// compiled CSS, and the value stays overridable at runtime via the CSS var.
+@mixin _adaptive-size($property, $var-name, $type, $map, $important: false) {
+  @if not map.has-key($map, $type) {
+    @error "Type '#{$type}' not found!";
+  }
+
+  @if $important {
+    #{$property}: var(--#{$var-name}-#{$type}) !important;
+  } @else {
+    #{$property}: var(--#{$var-name}-#{$type});
+  }
+}
+
+// - - - - - - - - - - - - - -
+
+// Applies dynamically-scaled responsive rounded corners based on predefined maps
+@mixin border-radius($type) {
+  @include _adaptive-size("border-radius", "border-radius", $type, $border-radius, false);
+}
+
+// - - - - - - - - - - - - - -
+
+// Configures responsive border thickness and strokes across viewport ranges
+@mixin border-line($type) {
+  @include _adaptive-size("border-width", "border-line", $type, $border-line, false);
+}
+
+// - - - - - - - - - - - - - -
+
+// Mixin for icon sizes through devices — always clamp()
+@mixin box-size($type) {
+  @if not map.has-key($icon-size, $type) {
+    @error "Icon size '#{$type}' not found in $icon-size map!";
+  }
+
+  width: var(--size-icon-#{$type});
+  height: var(--size-icon-#{$type});
+}
+
+// - - - - - - - - - - - - - -
+
+// Mixin for padding with optional direction — references --space-* :root token
+@mixin padding($size, $direction: null) {
+  @if not map.has-key($space, $size) {
+    @error "space size '#{$size}' not found in $space map!";
+  }
+
+  $value: var(--space-#{$size});
+
+  @if $direction == "x" or $direction == "inline" {
+    padding-inline: $value;
+  } @else if $direction == "y" or $direction == "block" {
+    padding-block: $value;
+  } @else if $direction == null {
+    padding: $value;
+  } @else {
+    padding-#{$direction}: $value;
+  }
+}
+
+// Mixin for margin with optional direction — references --space-* :root token
+@mixin margin($size, $direction: null) {
+  @if not map.has-key($space, $size) {
+    @error "space size '#{$size}' not found in $space map!";
+  }
+
+  $value: var(--space-#{$size});
+
+  @if $direction == "x" or $direction == "inline" {
+    margin-inline: $value;
+  } @else if $direction == "y" or $direction == "block" {
+    margin-block: $value;
+  } @else if $direction == null {
+    margin: $value;
+  } @else {
+    margin-#{$direction}: $value;
+  }
+}
+
+// Mixin for gap with optional direction — references --space-* :root token
+@mixin gap($size, $direction: null) {
+  @if not map.has-key($space, $size) {
+    @error "space size '#{$size}' not found in $space map!";
+  }
+
+  $value: var(--space-#{$size});
+
+  @if $direction == "x" or $direction == "column" {
+    column-gap: $value;
+  } @else if $direction == "y" or $direction == "row" {
+    row-gap: $value;
+  } @else if $direction == null {
+    gap: $value;
+  } @else {
+    @error "gap() direction must be null, 'x', 'column', 'y', or 'row'. Got: '#{$direction}'";
+  }
+}
+
+// - - - - - - - - - - - - - -
+// DEMONSTRATION & API USAGE
+// @include padding("md"); // all sides
+// @include padding("md", "top"); // top only
+// @include padding("md", "x"); // left-right
+// @include padding("md", "y"); // top-bottom
+// @include margin("lg"); // all sides
+// @include margin("2xl", "bottom"); // bottom only
+// @include gap("md"); // gap (grid & flex)
+// @include gap("lg", "x"); // column-gap only
+// @include gap("sm", "y"); // row-gap only
+// - - - - - - - - - - - - - -
+
+@mixin not-first-child() {
+  &:where(:not(:first-child)) {
+    @content;
+  }
+}
+
+@mixin not-last-child() {
+  &:where(:not(:last-child)) {
+    @content;
+  }
+}
+
+@mixin horizontal-scroll() {
+  @media only screen {
+    overflow-x: auto;
+    white-space: nowrap;
+    width: 100%;
+    @content;
+  }
+}
+
+@mixin no-horizontal-scroll() {
+  overflow-x: visible;
+  white-space: normal;
+  width: auto;
+}
+

package/scss/foundation/core/engine/responsive.scss

@@ -0,0 +1,67 @@
+// ╔══════════════════════════════════════════════════════════════╗
+// ║  ⚡ Zeus CSS — Responsive                                      ║
+// ║                                                               ║
+// ║  Framework internal engine and mixins for responsive.         ║
+// ╚══════════════════════════════════════════════════════════════╝
+
+@use "sass:map";
+@use "../design/layout/grid" as *;
+
+
+@function bp($key) {
+  @if not map.has-key($breakpoints, $key) {
+    @error "Breakpoint '#{$key}' not found in $breakpoints!";
+  }
+  @return map.get($breakpoints, $key);
+}
+
+@function _max($breakpoint) {
+  @return $breakpoint - 0.02px;   
+}
+
+// = = = = = = = = = = = = = = = =
+// Modern Parameter-Driven Responsive API
+// = = = = = = = = = = = = = = = =
+
+@mixin screen-above($breakpoint) {
+  @media screen and (min-width: #{bp($breakpoint)}) {
+    @content;
+  }
+}
+
+@mixin screen-below($breakpoint) {
+  @media screen and (max-width: #{_max(bp($breakpoint))}) {
+    @content;
+  }
+}
+
+@mixin screen-between($lower, $upper) {
+  @media screen and (min-width: #{bp($lower)}) and (max-width: #{_max(bp($upper))}) {
+    @content;
+  }
+}
+
+// ─── Exclusive Layout Exclusion (Hide) ─────────────────
+// Scopes: 'handheld', 'mobile', 'tablet', 'desktop' (all singular).
+@mixin suppress-on($scope) {
+  @if $scope == 'handheld' {
+    @media screen and (max-width: #{_max(bp(lg))}) {
+      display: none !important;
+    }
+  } @else if $scope == 'mobile' {
+    @media screen and (max-width: #{_max(bp(md))}) {
+      display: none !important;
+    }
+  } @else if $scope == 'tablet' {
+    @media screen and (min-width: #{bp(md)}) and (max-width: #{_max(bp(lg))}) {
+      display: none !important;
+    }
+  } @else if $scope == 'desktop' {
+    @media screen and (min-width: #{bp(lg)}) {
+      display: none !important;
+    }
+  } @else {
+    @error "[Zeus] suppress-on(): unknown scope '#{$scope}'. Expected 'handheld', 'mobile', 'tablet', or 'desktop'.";
+  }
+}
+