@mastors/core 1.1.0

package/scss/functions/_vars.scss

@@ -0,0 +1,49 @@
+// functions/_vars.scss
+// vars() — reference any design token as a CSS custom property by name.
+// ─────────────────────────────────────────────────────────────
+// All Mastors tokens are emitted as --mastors-{name} custom properties
+// by the token layer. This function wraps that convention so downstream
+// consumers never have to hard-code the --mastors- prefix themselves,
+// and so token references remain refactor-safe if the prefix ever changes.
+// Usage:
+//   color:            vars(accent);            → var(--mastors-accent)
+//   background-color: vars(surface-raised);    → var(--mastors-surface-raised)
+//   box-shadow:       vars(shadow-lg);         → var(--mastors-shadow-lg)
+// With a CSS fallback (passed through verbatim):
+//   color: vars(accent, #3b82f6);             → var(--mastors-accent, #3b82f6)
+//   gap:   vars(spacing-4, 1rem);             → var(--mastors-spacing-4, 1rem)
+// Composing with other functions is fine — Sass evaluates eagerly:
+//   transition: opacity vars(duration-200) vars(ease-out);
+// ─────────────────────────────────────────────────────────────
+
+@use "sass:meta";
+@use "sass:string";
+@use "../variables/global" as g;
+
+// Internal: the custom-property namespace prefix.
+// Mirrors the --mastors- prefix used by the token emitter.
+// Kept as a private variable so it only needs to change here.
+$-namespace: "mastors" !default;
+
+/// Return a CSS var() expression for a design token by name.
+///
+/// @param  {String} $token    - token name, without the --mastors- prefix
+/// @param  {*}      $fallback - optional CSS fallback value (default: null)
+/// @return {String} var(--mastors-{$token}) or var(--mastors-{$token}, {$fallback})
+///
+/// @example scss
+///   .btn { color: vars(accent); }
+///   // → .btn { color: var(--mastors-accent); }
+///
+/// @example scss
+///   .card { box-shadow: vars(shadow-md, 0 2px 8px rgb(0 0 0 / .1)); }
+///   // → .card { box-shadow: var(--mastors-shadow-md, 0 2px 8px rgb(0 0 0 / .1)); }
+@function vars($token, $fallback: null) {
+  $prop: "--#{$-namespace}-#{$token}";
+
+  @if not $fallback {
+    @return var(#{$prop});
+  } @else {
+    @return var(#{$prop}, #{$fallback});
+  }
+}

package/scss/generators/_class-generator.scss

@@ -0,0 +1,83 @@
+// generators/_class-generator.scss
+// Core mixin engine for generating utility class output.
+// ─────────────────────────────────────────────────────────────
+
+@use "sass:map";
+@use "sass:meta";
+@use "sass:string";
+@use "../config/settings" as cfg;
+@use "../config/flags";
+@use "../variables/breakpoints" as bpvars;
+
+/// Core utility class generator engine.
+@mixin generate-utilities($utilities) {
+  $cls-prefix: cfg.config("prefix");
+  $use-important: cfg.config("important");
+
+  // ── Pass 1: base (unprefixed) classes ──────────────────────
+  @each $name, $config in $utilities {
+    $prop: map.get($config, property);
+    $values: map.get($config, values);
+    $prefix: map.get($config, prefix);
+
+    @each $suffix, $value in $values {
+      $class-name: "#{$cls-prefix}#{$suffix}";
+      @if $prefix {
+        $class-name: "#{$cls-prefix}#{$prefix}-#{$suffix}";
+      }
+      .#{$class-name} {
+        @if $use-important {
+          #{$prop}: $value !important;
+        } @else {
+          #{$prop}: $value;
+        }
+      }
+    }
+  }
+
+  // ── Pass 2: responsive variants (.sm\:, .md\:, …) ─────────
+  @if flags.$enable-responsive {
+    @each $bp-key, $bp-value in bpvars.$breakpoints {
+      @if $bp-value != 0 {
+        @media (min-width: #{$bp-value}) {
+          @each $name, $config in $utilities {
+            @if map.get($config, responsive) == true {
+              $prop: map.get($config, property);
+              $values: map.get($config, values);
+              $prefix: map.get($config, prefix);
+
+              @each $suffix, $value in $values {
+                $class: null;
+                @if $prefix {
+                  $class: "#{$cls-prefix}#{$prefix}-#{$suffix}";
+                } @else {
+                  $class: "#{$cls-prefix}#{$suffix}";
+                }
+
+                // Escape numeric-leading breakpoint keys (e.g. "2xl" → "\32 xl")
+                $first: string.slice("#{$bp-key}", 1, 1);
+                $rest: string.slice("#{$bp-key}", 2);
+                $safe-bp: null;
+                @if $first == "0" or $first == "1" or $first == "2" or $first == "3" or
+                    $first == "4" or $first == "5" or $first == "6" or $first == "7" or
+                    $first == "8" or $first == "9" {
+                  $safe-bp: "\\3#{$first} #{$rest}";
+                } @else {
+                  $safe-bp: "#{$bp-key}";
+                }
+
+                @at-root .#{$safe-bp}\:#{$class} {
+                  @if $use-important {
+                    #{$prop}: $value !important;
+                  } @else {
+                    #{$prop}: $value;
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/scss/generators/_custom-property-generator.scss

@@ -0,0 +1,29 @@
+// generators/_custom-property-generator.scss
+// Emits CSS custom properties from SCSS token maps.
+// ─────────────────────────────────────────────────────────────
+
+@use "sass:map";
+@use "sass:meta";
+@use "sass:string";
+
+/// Emit CSS custom properties from a token map onto a selector
+/// @param {Map}    $map      - token map (key → value)
+/// @param {String} $prefix   - custom property prefix (e.g. "mastors-color-primary")
+@mixin emit-custom-properties($map, $prefix) {
+  @each $key, $value in $map {
+    --#{$prefix}-#{$key}: #{$value};
+  }
+}
+
+/// Recursively emit nested token maps (e.g. color palette with scales)
+/// @param {Map}    $map      - nested map
+/// @param {String} $prefix   - base prefix (e.g. "mastors-color")
+@mixin emit-nested-custom-properties($map, $prefix) {
+  @each $key, $value in $map {
+    @if meta.type-of($value) == map {
+      @include emit-nested-custom-properties($value, "#{$prefix}-#{$key}");
+    } @else {
+      --#{$prefix}-#{$key}: #{$value};
+    }
+  }
+}

package/scss/generators/_index.scss

@@ -0,0 +1,6 @@
+// generators/_index.scss
+// ─────────────────────────────────────────────────────────────
+
+@forward "class-generator";
+@forward "custom-property-generator";
+@forward "responsive-generator";

package/scss/generators/_responsive-generator.scss

@@ -0,0 +1,28 @@
+// generators/_responsive-generator.scss
+// Responsive variant delegation — forwards to the canonical engine.
+// ─────────────────────────────────────────────────────────────
+
+// NOTE: Responsive class generation is now handled directly inside
+// generate-utilities() in _class-generator.scss (Pass 2).
+// This file previously contained a generate-responsive() mixin that
+// accepted @content blocks but never emitted any CSS itself, making it
+// a silent no-op. That stub has been removed to prevent confusion.
+// — If you need to run the responsive engine standalone (e.g. from a
+//   sub-package that builds its own $utilities map independently of
+//   generate-utilities), use the engine mixin directly:
+//     @use "@mastors/core/scss/responsive/engine" as engine;
+//     @include engine.run($my-utilities);
+// — For the standard case, simply pass your $utilities map to
+//   generate-utilities() and set responsive: true on any entry that
+//   needs breakpoint variants — the responsive pass runs automatically.
+
+@use "../responsive/engine" as engine;
+@use "sass:map";
+
+/// Thin wrapper that delegates to engine.run().
+/// Prefer calling engine.run() directly for clarity.
+/// Kept here only for backward compatibility with sub-packages that
+/// previously @use'd this file.
+@mixin generate-responsive($utilities) {
+  @include engine.run($utilities);
+}

package/scss/helpers/_clearfix.scss

@@ -0,0 +1,9 @@
+// helpers/_clearfix.scss
+// Clearfix helper for legacy float layouts.
+// ─────────────────────────────────────────────────────────────
+
+.clearfix::after {
+  content: "";
+  display: table;
+  clear: both;
+}

package/scss/helpers/_index.scss

@@ -0,0 +1,7 @@
+// helpers/_index.scss
+// ─────────────────────────────────────────────────────────────
+
+@forward "clearfix";
+@forward "visually-hidden";
+@forward "truncate";
+@forward "ratio";

package/scss/helpers/_ratio.scss

@@ -0,0 +1,22 @@
+// helpers/_ratio.scss
+// Aspect ratio helpers.
+// ─────────────────────────────────────────────────────────────
+
+@use "sass:math";
+
+// Aspect ratio helpers using the native aspect-ratio property
+
+$-ratios: (
+  "auto":    auto,
+  "square":  math.div(1, 1),
+  "video":   math.div(16, 9),
+  "portrait": math.div(3, 4),
+  "wide":    math.div(21, 9),
+  "golden":  math.div(1.618, 1),
+) !default;
+
+@each $name, $ratio in $-ratios {
+  .ratio-#{$name} {
+    aspect-ratio: $ratio;
+  }
+}

package/scss/helpers/_truncate.scss

@@ -0,0 +1,25 @@
+// helpers/_truncate.scss
+// Text truncation and overflow helpers.
+// ─────────────────────────────────────────────────────────────
+
+// Single-line truncation
+.truncate {
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+// Multi-line clamp helpers (.line-clamp-{n})
+@each $n in 1, 2, 3, 4, 5, 6 {
+  .line-clamp-#{$n} {
+    display: -webkit-box;
+    -webkit-line-clamp: $n;
+    -webkit-box-orient: vertical;
+    overflow: hidden;
+  }
+}
+
+// Break long words
+.break-words  { overflow-wrap: break-word; word-break: break-word; }
+.break-all    { word-break: break-all; }
+.break-keep   { word-break: keep-all; }

package/scss/helpers/_visually-hidden.scss

@@ -0,0 +1,39 @@
+// helpers/_visually-hidden.scss
+// Visually hides content while keeping it accessible to screen readers.
+// ─────────────────────────────────────────────────────────────
+// The canonical implementation lives in accessibility/_screen-reader.scss
+// (.sr-only / .not-sr-only — the modern standard class names).
+// This file provides the legacy aliases (.visually-hidden, .vh,
+// .visually-hidden-focusable) that map onto the same rules, so existing
+// codebases using either naming convention continue to work without
+// duplicating any declarations.
+
+@use "../accessibility/screen-reader" as *;
+
+// Legacy aliases — extend the canonical sr-only rules
+// so no extra CSS is emitted; both class names share one rule block.
+.visually-hidden,
+.vh {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  margin: -1px;
+  overflow: hidden;
+  clip: rect(0, 0, 0, 0);
+  white-space: nowrap;
+  border-width: 0;
+}
+
+// Undo visually-hidden when focused (e.g. skip links)
+.visually-hidden-focusable:not(:focus):not(:focus-within) {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  margin: -1px;
+  overflow: hidden;
+  clip: rect(0, 0, 0, 0);
+  white-space: nowrap;
+  border-width: 0;
+}

package/scss/index.scss

@@ -0,0 +1,41 @@
+// @mastors/core — scss/index.scss
+// ─────────────────────────────────────────────────────────────
+// Main entry point for @mastors/core.
+// Import order is intentional — do not reorder without reason.
+// ─────────────────────────────────────────────────────────────
+
+// 1. Config & Settings (no output)
+@use "config/settings"  as *;
+@use "config/flags"     as *;
+
+// 2. Abstracts (no output)
+@use "abstracts/index"  as *;
+
+// 3. Variables & Tokens (no output)
+@use "variables/index"  as *;
+@use "tokens/index"     as *;
+
+// 4. Functions (no output)
+@use "functions/index"  as *;
+
+// 5. Mixins (no output)
+@use "mixins/index"     as *;
+
+// 6. Base & Reset (outputs CSS)
+@use "base/index"       as base;
+
+// 7. Themes (outputs CSS custom properties)
+@use "themes/index"     as themes;
+
+// 8. Semantic layer (outputs CSS)
+@use "semantic/index"   as semantic;
+
+// 9. Responsive engine (outputs CSS)
+@use "responsive/index" as responsive;
+
+// 10. Helpers & Utilities
+@use "helpers/index"    as helpers;
+@use "utilities/index"  as utilities;
+
+// 11. Accessibility
+@use "accessibility/index" as accessibility;

package/scss/mixins/_breakpoint.scss

@@ -0,0 +1,33 @@
+// mixins/_breakpoint.scss
+// Responsive breakpoint mixin and variant helpers.
+// ─────────────────────────────────────────────────────────────
+
+@use "sass:map";
+@use "../variables/breakpoints" as bpvars;
+
+/// Emit styles at and above a named breakpoint (mobile-first)
+/// @param {String} $bp - breakpoint key (sm, md, lg, xl, 2xl)
+@mixin bp($bp) {
+  $value: map.get(bpvars.$breakpoints, $bp);
+  @if not $value {
+    @error "bp(): unknown breakpoint '#{$bp}'. Available: #{map.keys(bpvars.$breakpoints)}";
+  }
+  @if $value == 0 {
+    @content;
+  } @else {
+    @media (min-width: #{$value}) { @content; }
+  }
+}
+
+// Alias
+@mixin respond-to($bp)      { @include bp($bp) { @content; } }
+@mixin breakpoint-up($bp)   { @include bp($bp) { @content; } }
+
+/// Emit styles below a named breakpoint
+@mixin breakpoint-down($bp) {
+  $value: map.get(bpvars.$breakpoints, $bp);
+  @if not $value {
+    @error "breakpoint-down(): unknown breakpoint '#{$bp}'";
+  }
+  @media (max-width: #{$value - 0.02px}) { @content; }
+}

package/scss/mixins/_container.scss

@@ -0,0 +1,20 @@
+// mixins/_container.scss
+// Responsive container width / max-width / padding mixin.
+// ─────────────────────────────────────────────────────────────
+
+@use "sass:map";
+@use "../variables/container" as cvars;
+@use "./breakpoint" as bp;
+
+/// Responsive container with max-width and horizontal padding
+@mixin container {
+  width: 100%;
+  margin-inline: auto;
+  padding-inline: cvars.$container-padding-x;
+
+  @each $bp-key, $max-w in cvars.$container-max-widths {
+    @include bp.bp($bp-key) {
+      max-width: $max-w;
+    }
+  }
+}

package/scss/mixins/_elevation.scss

@@ -0,0 +1,12 @@
+// mixins/_elevation.scss
+// Box shadow / elevation scale mixin.
+// ─────────────────────────────────────────────────────────────
+
+@use "sass:map";
+@use "../tokens/shadows" as sh;
+
+/// Apply a shadow elevation level
+/// @param {String} $level - shadow key (xs, sm, md, lg, xl, 2xl, inner, none)
+@mixin elevation($level: "md") {
+  box-shadow: sh.shadow($level);
+}

package/scss/mixins/_index.scss

@@ -0,0 +1,9 @@
+// mixins/_index.scss
+// ─────────────────────────────────────────────────────────────
+
+@forward "breakpoint";
+@forward "theme";
+@forward "elevation";
+@forward "transition";
+@forward "pseudo";
+@forward "container";

package/scss/mixins/_pseudo.scss

@@ -0,0 +1,13 @@
+// mixins/_pseudo.scss
+// ::before / ::after pseudo-element helper mixins.
+// ─────────────────────────────────────────────────────────────
+
+/// Generate a pseudo-element (::before / ::after)
+/// @param {String} $display  - display value (default: block)
+/// @param {String} $pos      - position value (default: absolute)
+/// @param {String} $content  - content value (default: "")
+@mixin pseudo($display: block, $pos: absolute, $content: "") {
+  content: $content;
+  display: $display;
+  position: $pos;
+}

package/scss/mixins/_theme.scss

@@ -0,0 +1,31 @@
+// mixins/_theme.scss
+// Theme-switching mixins (light/dark/custom).
+// ─────────────────────────────────────────────────────────────
+
+@use "../config/settings" as cfg;
+
+/// Apply styles inside the dark-mode context (class or media strategy)
+@mixin dark-mode {
+  @if cfg.config("dark-mode") == "class" {
+    .dark & { @content; }
+    [data-theme="dark"] & { @content; }
+  } @else {
+    @media (prefers-color-scheme: dark) { @content; }
+  }
+}
+
+/// Apply styles inside the light-mode context
+@mixin light-mode {
+  @if cfg.config("dark-mode") == "class" {
+    .light & { @content; }
+    [data-theme="light"] & { @content; }
+  } @else {
+    @media (prefers-color-scheme: light) { @content; }
+  }
+}
+
+/// Apply styles under a named theme class on :root/html
+/// Usage: @include theme("ocean") { color: ...; }
+@mixin theme($name) {
+  [data-theme="#{$name}"] & { @content; }
+}

package/scss/mixins/_transition.scss

@@ -0,0 +1,20 @@
+// mixins/_transition.scss
+// Transition helpers using token-driven durations and easings.
+// ─────────────────────────────────────────────────────────────
+
+@use "sass:list";
+@use "../tokens/transitions" as tr;
+
+/// Emit a transition using named token durations and easings
+/// @param {List} $properties  - CSS properties to transition (default: all)
+/// @param {String} $duration  - duration token key (default: "200")
+/// @param {String} $easing    - easing token key (default: "in-out")
+@mixin transition($properties: (all), $duration: "200", $easing: "in-out") {
+  $dur: tr.duration($duration);
+  $ease: tr.easing($easing);
+  $transitions: ();
+  @each $prop in $properties {
+    $transitions: list.append($transitions, #{$prop} #{$dur} #{$ease}, comma);
+  }
+  transition: $transitions;
+}

package/scss/responsive/_container-queries.scss

@@ -0,0 +1,31 @@
+// responsive/_container-queries.scss
+// CSS container query helpers (@container).
+// ─────────────────────────────────────────────────────────────
+
+// Container query helpers
+// Requires elements to have a containment context set:
+//   .cq-inline  { container-type: inline-size; }
+//   .cq-size    { container-type: size; }
+//   .cq-normal  { container-type: normal; }
+
+.cq-inline  { container-type: inline-size; }
+.cq-size    { container-type: size; }
+.cq-normal  { container-type: normal; }
+
+// Named container helper
+// Usage: <div class="cq-inline" style="container-name: card">...
+// or use data attribute: [data-container] { container-type: inline-size; }
+[data-container] {
+  container-type: inline-size;
+}
+
+// Mixin for inline container queries in component SCSS
+// @use "@mastors/core/api" as m;
+// @include m.cq(40rem) { ... }
+@mixin cq($min-width, $name: null) {
+  @if $name {
+    @container #{$name} (min-width: #{$min-width}) { @content; }
+  } @else {
+    @container (min-width: #{$min-width}) { @content; }
+  }
+}

package/scss/responsive/_engine.scss

@@ -0,0 +1,65 @@
+// responsive/_engine.scss
+// Core responsive variant generation engine.
+// ─────────────────────────────────────────────────────────────
+
+@use "sass:map";
+@use "../variables/breakpoints" as bpvars;
+@use "../config/flags";
+
+// Responsive engine — generates breakpoint-prefixed variants
+// of any utility that declares responsive: true.
+// Class pattern:  .{bp}\:{utility}
+// Example output: .sm\:hidden, .md\:flex, .lg\:gap-8
+// Sub-packages pass their $utilities map here via @include engine.run()
+// so the engine iterates breakpoints and re-emits the classes.
+
+@use "sass:string";
+
+@mixin run($utilities) {
+  @if flags.$enable-responsive {
+    @each $bp-key, $bp-value in bpvars.$breakpoints {
+      // Skip xs — no prefix, already emitted as base classes
+      @if $bp-value != 0 {
+        @media (min-width: #{$bp-value}) {
+          @each $name, $config in $utilities {
+            @if map.get($config, responsive) == true {
+              $prop: map.get($config, property);
+              $values: map.get($config, values);
+              $prefix: map.get($config, prefix);
+
+              @each $suffix, $value in $values {
+                $class: null;
+                @if $prefix {
+                  $class: "#{$prefix}-#{$suffix}";
+                } @else {
+                  $class: "#{$suffix}";
+                }
+
+                // CSS class names cannot start with a digit.
+                // When the breakpoint key begins with a number (e.g. "2xl"),
+                // escape it using the CSS identifier-escape syntax: \3X  (space after hex).
+                $first: string.slice("#{$bp-key}", 1, 1);
+                $rest: string.slice("#{$bp-key}", 2);
+                $safe-bp: null;
+                @if $first == "0" or $first == "1" or $first == "2" or $first == "3" or
+                    $first == "4" or $first == "5" or $first == "6" or $first == "7" or
+                    $first == "8" or $first == "9" {
+                  // \3X  is the CSS escape for the digit (space terminates the escape)
+                  $safe-bp: "\\3#{$first} #{$rest}";
+                } @else {
+                  $safe-bp: "#{$bp-key}";
+                }
+
+                // Use #{} interpolation so Sass emits the selector verbatim
+                // without re-parsing the leading backslash as a Sass identifier.
+                @at-root .#{$safe-bp}\:#{$class} {
+                  #{$prop}: $value;
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/scss/responsive/_fluid-type.scss

@@ -0,0 +1,40 @@
+// responsive/_fluid-type.scss
+// Fluid / clamp()-based responsive typography scale.
+// ─────────────────────────────────────────────────────────────
+
+@use "sass:math";
+@use "../functions/math" as mathfn;
+
+// Fluid type scale — font sizes that scale smoothly between two viewport widths.
+// Uses clamp() so no media queries are needed.
+// Usage in component SCSS:
+//   @use "@mastors/core/api" as m;
+//   font-size: m.fluid-type(1rem, 1.5rem);
+
+/// Fluid type mixin: applies a clamp()-based fluid font-size
+/// @param {Number} $min-size  - minimum font size (rem)
+/// @param {Number} $max-size  - maximum font size (rem)
+/// @param {Number} $min-vw    - viewport at which min applies (px, default 320px)
+/// @param {Number} $max-vw    - viewport at which max applies (px, default 1280px)
+@mixin apply-fluid-type($min-size, $max-size, $min-vw: 320px, $max-vw: 1280px) {
+  font-size: mathfn.fluid($min-size, $max-size, $min-vw, $max-vw);
+}
+
+/// Fluid type function — for direct use in property values
+/// @return {String} clamp() expression
+@function fluid-type($min-size, $max-size, $min-vw: 320px, $max-vw: 1280px) {
+  @return mathfn.fluid($min-size, $max-size, $min-vw, $max-vw);
+}
+
+// Predefined fluid heading scale (opt-in)
+// Include with: @use "@mastors/core/scss/responsive/fluid-type" as ft;
+//               @include ft.fluid-scale();
+@mixin fluid-scale {
+  h1 { @include apply-fluid-type(2rem,    3.75rem); }
+  h2 { @include apply-fluid-type(1.5rem,  3rem); }
+  h3 { @include apply-fluid-type(1.25rem, 2.25rem); }
+  h4 { @include apply-fluid-type(1.125rem, 1.875rem); }
+  h5 { @include apply-fluid-type(1rem,    1.5rem); }
+  h6 { @include apply-fluid-type(0.875rem, 1.25rem); }
+  p  { @include apply-fluid-type(0.875rem, 1.125rem); }
+}

package/scss/responsive/_index.scss

@@ -0,0 +1,6 @@
+// responsive/_index.scss
+// ─────────────────────────────────────────────────────────────
+
+@forward "engine";
+@forward "container-queries";
+@forward "fluid-type";