@mastors/core 1.1.0

package/scss/abstracts/_maps.scss

@@ -0,0 +1,9 @@
+// abstracts/_maps.scss
+// Shared SCSS maps used across the Mastors ecosystem.
+// ─────────────────────────────────────────────────────────────
+// INTENTIONAL STUB — this file is reserved for shared utility maps that
+// do not belong in tokens/ or variables/. It is deliberately empty at v1.0.
+// Add maps here when they are:
+//   - Consumed by 3+ unrelated files across packages
+//   - Not a design token (those live in tokens/)
+//   - Not a layout variable (those live in variables/)

package/scss/abstracts/_placeholders.scss

@@ -0,0 +1,7 @@
+// abstracts/_placeholders.scss
+// Shared silent SCSS placeholder selectors (%placeholder).
+// ─────────────────────────────────────────────────────────────
+
+// Package-scoped placeholders live in their own partials (e.g. helpers/_visually-hidden.scss).
+// Add cross-cutting placeholders here when they are shared by 3+ unrelated files.
+

package/scss/accessibility/_focus.scss

@@ -0,0 +1,21 @@
+// accessibility/_focus.scss
+// Focus ring and keyboard navigation styles.
+// ─────────────────────────────────────────────────────────────
+
+// Focus ring — respects browser defaults, enhances with custom ring.
+// Custom property --mastors-color-primary-500 is emitted by base/_root.scss
+// via the nested emit-nested-custom-properties() generator, which produces
+// --mastors-color-primary-{shade} for every shade in $color-tokens.
+// The hardcoded fallback #3b82f6 (primary-500) fires only in environments
+// where @mastors/core's :root block has not been loaded (e.g. partial imports).
+
+:focus-visible {
+  outline: 2px solid var(--mastors-color-primary-500, #3b82f6);
+  outline-offset: 2px;
+  border-radius: 2px;
+}
+
+// Remove focus ring for mouse users
+:focus:not(:focus-visible) {
+  outline: none;
+}

package/scss/accessibility/_index.scss

@@ -0,0 +1,7 @@
+// accessibility/_index.scss
+// ─────────────────────────────────────────────────────────────
+
+@forward "focus";
+@forward "motion";
+@forward "screen-reader";
+@forward "print";

package/scss/accessibility/_motion.scss

@@ -0,0 +1,14 @@
+// accessibility/_motion.scss
+// Reduced motion preferences and safe animation overrides.
+// ─────────────────────────────────────────────────────────────
+
+// Respect user motion preferences — disable animations for users who request it.
+
+@media (prefers-reduced-motion: reduce) {
+  *, *::before, *::after {
+    animation-duration:        0.01ms !important;
+    animation-iteration-count: 1      !important;
+    transition-duration:       0.01ms !important;
+    scroll-behavior:           auto   !important;
+  }
+}

package/scss/accessibility/_print.scss

@@ -0,0 +1,52 @@
+// accessibility/_print.scss
+// Print-specific utilities and media query helpers.
+// ─────────────────────────────────────────────────────────────
+
+// Hide from print
+.print\:hidden {
+  @media print { display: none !important; }
+}
+
+// Show only in print
+.screen\:hidden {
+  @media not print { display: none !important; }
+}
+
+@media print {
+  // Avoid page breaks inside these elements by default
+  .print\:break-inside-avoid {
+    break-inside: avoid;
+    page-break-inside: avoid;
+  }
+
+  // Force page break before
+  .print\:break-before {
+    break-before: page;
+    page-break-before: always;
+  }
+
+  // Force page break after
+  .print\:break-after {
+    break-after: page;
+    page-break-after: always;
+  }
+
+  // Print-safe color override (ensure text is black on white)
+  .print\:text-black  { color: #000 !important; }
+  .print\:bg-white    { background: #fff !important; }
+  .print\:border-none { border: none !important; }
+  .print\:shadow-none { box-shadow: none !important; }
+
+  // Expand truncated links for print readers
+  a[href]::after {
+    content: " (" attr(href) ")";
+    font-size: 0.75em;
+    color: #555;
+  }
+
+  // Don't expand hash or JS links
+  a[href^="#"]::after,
+  a[href^="javascript:"]::after {
+    content: "";
+  }
+}

package/scss/accessibility/_screen-reader.scss

@@ -0,0 +1,31 @@
+// accessibility/_screen-reader.scss
+// Screen-reader-only utility — canonical single source of truth.
+// ─────────────────────────────────────────────────────────────
+// .sr-only / .not-sr-only are the primary class names (modern standard).
+// Legacy aliases (.visually-hidden, .vh, .visually-hidden-focusable)
+// are provided in helpers/_visually-hidden.scss and share these rules.
+
+// Screen reader only — visually hidden but announced by screen readers
+.sr-only {
+  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 sr-only — make visible again
+.not-sr-only {
+  position: static;
+  width: auto;
+  height: auto;
+  padding: 0;
+  margin: 0;
+  overflow: visible;
+  clip: auto;
+  white-space: normal;
+}

package/scss/api/_index.scss

@@ -0,0 +1,14 @@
+// api/_index.scss
+// Public SCSS API — the surface that downstream packages @use.
+// ─────────────────────────────────────────────────────────────
+// Consumers: @use "@mastors/core/api" as m;
+// This file exposes only what is intended to be public API.
+// Internal implementation files are NOT forwarded here.
+// ─────────────────────────────────────────────────────────────
+
+@forward "../functions/index";
+@forward "../mixins/index";
+@forward "../tokens/index";
+@forward "../variables/index";
+@forward "../config/index";
+@forward "../responsive/container-queries";

package/scss/base/_box-sizing.scss

@@ -0,0 +1,6 @@
+// base/_box-sizing.scss
+// INTENTIONALLY EMPTY — box-sizing: border-box is declared in _reset.scss.
+// This file is retained as a named slot so downstream packages and build
+// tooling that reference the path continue to resolve without error.
+// Do not add declarations here.
+// ─────────────────────────────────────────────────────────────

package/scss/base/_index.scss

@@ -0,0 +1,7 @@
+// base/_index.scss
+// ─────────────────────────────────────────────────────────────
+
+@forward "reset";
+@forward "root";
+@forward "box-sizing";
+@forward "typography-base";

package/scss/base/_reset.scss

@@ -0,0 +1,59 @@
+// base/_reset.scss
+// Modern CSS reset / normalization layer.
+// ─────────────────────────────────────────────────────────────
+
+// Modern CSS reset — opinionated, minimal, predictable.
+
+*, *::before, *::after {
+  box-sizing: border-box;
+}
+
+* {
+  margin: 0;
+  padding: 0;
+}
+
+html {
+  text-size-adjust: 100%;
+  tab-size: 4;
+  scroll-behavior: smooth;
+}
+
+body {
+  line-height: inherit;
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+}
+
+img, picture, video, canvas, svg {
+  display: block;
+  max-width: 100%;
+}
+
+input, button, textarea, select {
+  font: inherit;
+}
+
+p, h1, h2, h3, h4, h5, h6 {
+  overflow-wrap: break-word;
+}
+
+ol, ul {
+  list-style: none;
+}
+
+a {
+  color: inherit;
+  text-decoration: inherit;
+}
+
+table {
+  border-collapse: collapse;
+  border-spacing: 0;
+}
+
+button, [role="button"] {
+  cursor: pointer;
+}
+
+[hidden] { display: none !important; }

package/scss/base/_root.scss

@@ -0,0 +1,43 @@
+// base/_root.scss
+// :root CSS custom property declarations.
+// ─────────────────────────────────────────────────────────────
+
+@use "../tokens/color"      as ct;
+@use "../tokens/spacing"    as sp;
+@use "../tokens/typography" as ty;
+@use "../tokens/shadows"    as sh;
+@use "../tokens/radii"      as ra;
+@use "../tokens/transitions" as tr;
+@use "../tokens/z-index"    as zi;
+@use "../tokens/opacity"    as op;
+@use "../generators/custom-property-generator" as gen;
+
+:root {
+  // Color tokens — nested emit (primary-50, primary-100 …)
+  @include gen.emit-nested-custom-properties(ct.$color-tokens, "mastors-color");
+
+  // Spacing
+  @include gen.emit-custom-properties(sp.$spacing-tokens, "mastors-spacing");
+
+  // Typography
+  @include gen.emit-custom-properties(ty.$font-size-tokens,       "mastors-font-size");
+  @include gen.emit-custom-properties(ty.$font-weight-tokens,     "mastors-font-weight");
+  @include gen.emit-custom-properties(ty.$line-height-tokens,     "mastors-leading");
+  @include gen.emit-custom-properties(ty.$letter-spacing-tokens,  "mastors-tracking");
+
+  // Radii
+  @include gen.emit-custom-properties(ra.$radius-tokens, "mastors-radius");
+
+  // Shadows
+  @include gen.emit-custom-properties(sh.$shadow-tokens, "mastors-shadow");
+
+  // Transitions
+  @include gen.emit-custom-properties(tr.$duration-tokens, "mastors-duration");
+  @include gen.emit-custom-properties(tr.$easing-tokens,   "mastors-easing");
+
+  // Z-index
+  @include gen.emit-custom-properties(zi.$z-index-tokens, "mastors-z");
+
+  // Opacity
+  @include gen.emit-custom-properties(op.$opacity-tokens, "mastors-opacity");
+}

package/scss/base/_typography-base.scss

@@ -0,0 +1,40 @@
+// base/_typography-base.scss
+// Base element typography (html, body, headings, p, a, etc.)
+// ─────────────────────────────────────────────────────────────
+
+@use "../variables/global"  as vars;
+@use "../tokens/typography" as ty;
+
+html {
+  font-size: vars.$base-font-size;
+  line-height: vars.$base-line-height;
+  font-family: vars.$base-font-family;
+  color: var(--mastors-text);
+  background-color: var(--mastors-bg);
+}
+
+body {
+  font-size: ty.font-size("base");
+  font-weight: ty.font-weight("normal");
+}
+
+h1, h2, h3, h4, h5, h6 {
+  font-weight: ty.font-weight("semibold");
+  line-height: ty.line-height("tight");
+}
+
+h1 { font-size: ty.font-size("4xl"); }
+h2 { font-size: ty.font-size("3xl"); }
+h3 { font-size: ty.font-size("2xl"); }
+h4 { font-size: ty.font-size("xl"); }
+h5 { font-size: ty.font-size("lg"); }
+h6 { font-size: ty.font-size("base"); }
+
+p  { line-height: ty.line-height("relaxed"); }
+
+small { font-size: ty.font-size("sm"); }
+
+code, kbd, samp, pre {
+  font-family: ty.font-family("mono");
+  font-size: ty.font-size("sm");
+}

package/scss/config/_flags.scss

@@ -0,0 +1,13 @@
+// config/_flags.scss
+// Boolean feature flags to tree-shake generated output.
+// ─────────────────────────────────────────────────────────────
+
+$enable-flexer: true !default;
+$enable-gridder: true !default;
+$enable-typography: true !default;
+$enable-themes: true !default;
+$enable-animator: true !default;
+$enable-responsive: true !default;
+$enable-utilities: true !default;
+$enable-helpers: true !default;
+$enable-a11y: true !default;

package/scss/config/_index.scss

@@ -0,0 +1,12 @@
+// config/_index.scss
+// Public config surface — forward both partials so downstream
+// consumers can reach flags and settings via the public API.
+// ─────────────────────────────────────────────────────────────
+// Usage (downstream):
+//   @use "@mastors/core/api" as m;
+//   $dark: m.$enable-themes;          // from flags
+//   $pfx:  m.config("prefix");        // from settings
+// ─────────────────────────────────────────────────────────────
+
+@forward "settings";
+@forward "flags";

package/scss/config/_settings.scss

@@ -0,0 +1,18 @@
+// config/_settings.scss
+// Master feature flags and global configuration map.
+// ─────────────────────────────────────────────────────────────
+
+// @use must come before everything else
+@use "sass:map";
+
+$mastors-config: (
+  "prefix":       "",
+  "important":    false,
+  "dark-mode":    "class",
+  "rtl":          false,
+) !default;
+
+// Convenience accessors
+@function config($key) {
+  @return map.get($mastors-config, $key);
+}

package/scss/functions/_color.scss

@@ -0,0 +1,66 @@
+// functions/_color.scss
+// Color manipulation and derivation functions.
+// ─────────────────────────────────────────────────────────────
+
+@use "sass:color";
+@use "sass:list";
+@use "sass:math";
+@use "../tokens/color" as ct;
+
+/// Mix a color with white
+@function tint($c, $pct: 10%) {
+  @return color.mix(white, $c, $pct);
+}
+
+/// Mix a color with black
+@function shade($c, $pct: 10%) {
+  @return color.mix(black, $c, $pct);
+}
+
+/// Adjust a color's alpha channel
+@function alpha($c, $a) {
+  @return color.adjust($c, $alpha: $a - 1);
+}
+
+/// Return black or white for maximum contrast against $bg.
+@function contrast($bg, $light: white, $dark: black) {
+  $luminance: 0.2126 * color.channel($bg, "red",   $space: rgb) / 255
+            + 0.7152 * color.channel($bg, "green", $space: rgb) / 255
+            + 0.0722 * color.channel($bg, "blue",  $space: rgb) / 255;
+  @if $luminance > 0.35 {
+    @return $dark;
+  } @else {
+    @return $light;
+  }
+}
+
+/// Quick palette accessor — shorthand for ct.color()
+@function palette($name, $shade: null) {
+  @return ct.color($name, $shade);
+}
+
+/// Emit a color as rgb() with optional opacity.
+@function rgb-color($name, $shade, $opacity: 1) {
+  $c: ct.color($name, $shade);
+  @if $opacity == 1 { @return $c; }
+  $r: color.channel($c, "red",   $space: rgb);
+  $g: color.channel($c, "green", $space: rgb);
+  $b: color.channel($c, "blue",  $space: rgb);
+  @return rgb($r $g $b / $opacity);
+}
+
+/// Create a stepped tint/shade ramp on the fly.
+@function color-ramp($base, $steps: 5, $dir: "tint") {
+  $result: ();
+  @for $i from 1 through $steps {
+    $pct: math.div($i * 100%, $steps + 1);
+    $step: null;
+    @if $dir == "tint" {
+      $step: tint($base, $pct);
+    } @else {
+      $step: shade($base, $pct);
+    }
+    $result: list.append($result, $step, comma);
+  }
+  @return $result;
+}

package/scss/functions/_em.scss

@@ -0,0 +1,28 @@
+// functions/_em.scss
+// px → em conversion function.
+// ─────────────────────────────────────────────────────────────
+
+@use "sass:math";
+@use "../variables/global" as vars;
+
+/// Convert px to em relative to a given context
+/// @param {Number} $px - pixel value
+/// @param {Number} $context - context font size in px (default: base)
+/// @return {Number} em value
+@function em($px, $context: vars.$base-font-size) {
+  $base: null;
+  @if math.compatible($px, 1px) {
+    $base: math.div($px, 1px);
+  } @else {
+    $base: $px;
+  }
+
+  $ctx: null;
+  @if math.compatible($context, 1px) {
+    $ctx: math.div($context, 1px);
+  } @else {
+    $ctx: $context;
+  }
+
+  @return math.div($base, $ctx) * 1em;
+}

package/scss/functions/_index.scss

@@ -0,0 +1,15 @@
+// functions/_index.scss
+// ─────────────────────────────────────────────────────────────
+// NOTE: _vars.scss is intentionally NOT forwarded here.
+// _string.scss already defines vars() and vars-or().
+// _vars.scss defines a single-token vars($token, $fallback) variant
+// under a different signature — forwarding both causes a "two modules
+// define vars" conflict. Consumers who need the _vars.scss variant
+// should @use it directly.
+
+@forward "color";
+@forward "math";
+@forward "string";
+@forward "map-helpers";
+@forward "rem";
+@forward "em";

package/scss/functions/_map-helpers.scss

@@ -0,0 +1,29 @@
+// functions/_map-helpers.scss
+// Deep map access, merge, and utility functions.
+// ─────────────────────────────────────────────────────────────
+
+@use "sass:map";
+@use "sass:list";
+@use "sass:meta";
+
+/// Deep map get — map.get() for nested maps
+/// Usage: map-deep-get($map, "key1", "key2")
+@function map-deep-get($map, $keys...) {
+  $result: $map;
+  @each $key in $keys {
+    @if meta.type-of($result) != map {
+      @error "map-deep-get: expected a map at key '#{$key}', got #{meta.type-of($result)}";
+    }
+    $result: map.get($result, $key);
+  }
+  @return $result;
+}
+
+/// Merge multiple maps into one (shallow)
+@function map-collect($maps...) {
+  $result: ();
+  @each $m in $maps {
+    $result: map.merge($result, $m);
+  }
+  @return $result;
+}

package/scss/functions/_math.scss

@@ -0,0 +1,40 @@
+// functions/_math.scss
+// Math utility functions (clamp, fluid scaling, etc.)
+// ─────────────────────────────────────────────────────────────
+
+@use "sass:math";
+
+/// Clamp a value between min and max
+@function clamp-value($min, $val, $max) {
+  @return clamp(#{$min}, #{$val}, #{$max});
+}
+
+/// Fluid value: scales linearly between two sizes across two viewport widths
+/// @param {Number} $min-val   - minimum output value (rem)
+/// @param {Number} $max-val   - maximum output value (rem)
+/// @param {Number} $min-vw    - viewport at which minimum applies (px)
+/// @param {Number} $max-vw    - viewport at which maximum applies (px)
+@function fluid($min-val, $max-val, $min-vw: 320px, $max-vw: 1280px) {
+  $slope: math.div($max-val - $min-val, $max-vw - $min-vw);
+  $intercept: $min-val - $slope * $min-vw;
+  @return clamp(#{$min-val}, #{$slope * 100vw} + #{$intercept}, #{$max-val});
+}
+
+/// Strip the unit from a number: strip-unit(16px) → 16
+@function strip-unit($number) {
+  @return math.div($number, ($number * 0 + 1));
+}
+
+/// Round to N decimal places: round-to(3.14159, 2) → 3.14
+@function round-to($number, $decimals: 2) {
+  $n: math.pow(10, $decimals);
+  @return math.div(math.round($number * $n), $n);
+}
+
+/// Linear interpolation between two values
+/// @param {Number} $a    - start value
+/// @param {Number} $b    - end value
+/// @param {Number} $t    - interpolation factor (0–1)
+@function lerp($a, $b, $t) {
+  @return $a + ($b - $a) * $t;
+}

package/scss/functions/_rem.scss

@@ -0,0 +1,27 @@
+// functions/_rem.scss
+// px → rem conversion function.
+// ─────────────────────────────────────────────────────────────
+
+@use "sass:math";
+@use "../variables/global" as vars;
+
+/// Convert px to rem using the base font size
+/// @param {Number} $px - pixel value (unitless or px)
+/// @return {Number} rem value
+@function rem($px) {
+  $base: 0;
+  @if math.compatible($px, 1px) {
+    $base: math.div($px, 1px);
+  } @else {
+    $base: $px;
+  }
+
+  $root: 0;
+  @if math.compatible(vars.$base-font-size, 1px) {
+    $root: math.div(vars.$base-font-size, 1px);
+  } @else {
+    $root: vars.$base-font-size;
+  }
+
+  @return math.div($base, $root) * 1rem;
+}

package/scss/functions/_string.scss

@@ -0,0 +1,57 @@
+// functions/_string.scss
+// String manipulation functions.
+// ─────────────────────────────────────────────────────────────
+
+@use "sass:string";
+@use "sass:list";
+
+/// Replace all occurrences of $search in $string with $replace
+@function str-replace($string, $search, $replace: "") {
+  $index: string.index($string, $search);
+  @if $index {
+    @return string.slice($string, 1, $index - 1)
+          + $replace
+          + str-replace(string.slice($string, $index + string.length($search)), $search, $replace);
+  }
+  @return $string;
+}
+
+/// Convert any value to a string
+@function to-string($value) {
+  @return #{$value};
+}
+
+/// Reference any design token as a CSS custom property (var()).
+/// Builds the --mastors-{category}-{keys...} expression at zero runtime cost.
+///
+/// Usage:
+///   color:              vars(color, primary, 500);  → var(--mastors-color-primary-500)
+///   padding:            vars(spacing, 4);           → var(--mastors-spacing-4)
+///   border-radius:      vars(radius, lg);           → var(--mastors-radius-lg)
+///   transition-duration:vars(duration, 200);        → var(--mastors-duration-200)
+///   z-index:            vars(z, modal);             → var(--mastors-z-modal)
+///   box-shadow:         vars(shadow, md);           → var(--mastors-shadow-md)
+///
+/// @param {String} $category - Token category prefix (color, spacing, radius…)
+/// @param {ArgList} $keys    - One or more path segments
+/// @return {String}          - CSS var() expression
+@function vars($category, $keys...) {
+  $prop: "--mastors-#{$category}";
+  @each $key in $keys {
+    $prop: "#{$prop}-#{$key}";
+  }
+  @return var(#{$prop});
+}
+
+/// vars() with a fallback value.
+/// Usage: color: vars-or(color, #3b82f6, primary, 500);
+/// @param {String} $category - Token category prefix
+/// @param {*}     $fallback  - Fallback value if custom property is not set
+/// @param {ArgList} $keys    - Path segments
+@function vars-or($category, $fallback, $keys...) {
+  $prop: "--mastors-#{$category}";
+  @each $key in $keys {
+    $prop: "#{$prop}-#{$key}";
+  }
+  @return var(#{$prop}, #{$fallback});
+}