@ultimat3/ui 22.14.0 → 23.0.0

package/src/tokens/_mixins.scss

@@ -4,15 +4,22 @@
 
 @use 'sass:list';
 @use 'sass:map';
+@use 'sass:string';
 @use 'breakpoints';
 @use 'colors';
 @use 'motion';
 @use 'radius';
 @use 'space';
+@use 'stroke';
 @use 'typography';
+@use 'units';
 
 /// Keyboard-only focus, drawn from the accent role so it themes automatically.
-@mixin focus-ring($role: 'accent', $width: 2px, $offset: 2px) {
+@mixin focus-ring(
+  $role: 'accent',
+  $width: stroke.stroke(thick),
+  $offset: stroke.stroke(thick)
+) {
   &:focus-visible {
     outline: $width solid colors.role($role);
     outline-offset: $offset;
@@ -81,13 +88,54 @@
   container-name: $name;
 }
 
-/// Viewport breakpoint, min-width only. Named rungs, never a raw px value.
+// --- Viewport breakpoints ----------------------------------------------------
+// Three intents over ONE map, so a rung is defined in one place: at and above (`respond-to`),
+// below (`respond-down`), and from one rung up to the next (`respond-between`). Prefer a container
+// query to any of them — reach here only when the layout depends on the viewport itself.
+
+/// What a max-width arm stops short of its rung by. `max-width: 768px` and `min-width: 768px` both
+/// match at exactly 768px, which is how one rule ends up applying in two ranges at once; 0.02px is
+/// below any width a browser reports and above the rounding that would collapse it.
+$-under: 0.02px;
+
+/// A rung's width. Compared as TEXT as well as by value: `2xl` in a map is the number 2 with the
+/// unit `xl`, so the string `'2xl'` every stylesheet writes is a different key to `map.get`.
+@function -rung($bp, $mixin) {
+  @each $name, $width in breakpoints.$breakpoints {
+    @if '#{$name}' == '#{$bp}' {
+      @return $width;
+    }
+  }
+  @error string.unquote('X_TOKEN_UNKNOWN: #{$mixin}("#{$bp}") — that breakpoint is not in $breakpoints. fix: use one of #{map.keys(breakpoints.$breakpoints)}');
+}
+
+/// At a rung and wider. Named rungs, never a raw px value.
 @mixin respond-to($bp) {
-  @if not map.has-key(breakpoints.$breakpoints, $bp) {
-    @error 'X_TOKEN_UNKNOWN: breakpoint "#{$bp}" is not in $breakpoints. fix: add it to src/tokens/_breakpoints.scss';
+  @media (min-width: -rung($bp, 'respond-to')) {
+    @content;
+  }
+}
+
+/// Narrower than a rung — the complement of `respond-to` on the same rung, with no shared pixel.
+@mixin respond-down($bp) {
+  @media (max-width: (-rung($bp, 'respond-down') - $-under)) {
+    @content;
+  }
+}
+
+/// From `$from` up to, and not including, `$to`.
+@mixin respond-between($from, $to) {
+  $min: -rung($from, 'respond-between');
+  $max: -rung($to, 'respond-between');
+
+  @if $min == $max {
+    @error string.unquote('X_UI_INVALID_VALUE: respond-between("#{$from}", "#{$to}") is an empty range — both ends are #{$min}. fix: write respond-to("#{$from}"), or name a higher rung as $to');
+  }
+  @if $min > $max {
+    @error string.unquote('X_UI_INVALID_VALUE: respond-between("#{$from}", "#{$to}") is reversed — #{$min} is not below #{$max}. fix: write respond-between("#{$to}", "#{$from}")');
   }
 
-  @media (min-width: map.get(breakpoints.$breakpoints, $bp)) {
+  @media (min-width: $min) and (max-width: ($max - $-under)) {
     @content;
   }
 }
@@ -156,8 +204,8 @@
   scrollbar-color: colors.role($thumb) colors.role($track);
 
   &::-webkit-scrollbar {
-    width: 10px;
-    height: 10px;
+    width: units.rem(10px);
+    height: units.rem(10px);
   }
 
   &::-webkit-scrollbar-track {
@@ -165,7 +213,7 @@
   }
 
   &::-webkit-scrollbar-thumb {
-    border: 2px solid transparent;
+    border: stroke.stroke(thick) solid transparent;
     border-radius: radius.radius(pill);
     background: colors.role($thumb);
     background-clip: content-box;

package/src/tokens/_motion.scss

@@ -16,6 +16,10 @@ $easing: (
   spring: cubic-bezier(0.34, 1.56, 0.64, 1),
 );
 
+/// What reduced motion collapses every duration to. Never `0`: an animation that takes no time
+/// fires no `animationend`, and a component waiting on that event waits forever.
+$still: 0.01ms;
+
 @mixin emit {
   :root {
     @each $name, $value in $duration {

package/src/tokens/_stroke.scss

@@ -0,0 +1,20 @@
+// Line weights: a border, an outline, a focus ring, an indicator. px on purpose — a line that
+// grew with the reader's text size would be a different design at 200% zoom, not a bigger one.
+
+$stroke: (
+  hairline: 1px,
+  thick: 2px,
+  heavy: 3px,
+);
+
+@mixin emit {
+  :root {
+    @each $name, $value in $stroke {
+      --stroke-#{$name}: #{$value};
+    }
+  }
+}
+
+@function stroke($name) {
+  @return var(--stroke-#{$name});
+}

package/src/tokens/_units.scss

@@ -0,0 +1,47 @@
+// Computed lengths: px → rem, and one fluid `clamp()` between two viewport widths. Functions only —
+// nothing here emits CSS. The scale maps restate a constant; these compute a value from one.
+
+@use 'sass:math';
+@use 'sass:meta';
+@use 'sass:string';
+
+/// The one conversion both functions read, so `fluid(16px, 32px)` and `rem(16px)` cannot disagree
+/// about what a px is — and so a refusal names the function the author actually called.
+@function -to-rem($value, $root, $caller, $example) {
+  @if meta.type-of($value) != 'number' or not (math.is-unitless($value) or math.unit($value) == 'px' or math.unit($value) == 'rem') {
+    @error string.unquote('X_UI_INVALID_VALUE: #{$caller}() expected px, rem or a unitless px count — got `#{meta.inspect($value)}`. fix: pass a px length, e.g. #{$example}');
+  }
+  @if math.is-unitless($value) {
+    @return math.div($value * 1px, $root) * 1rem;
+  }
+  @if math.unit($value) == 'rem' {
+    @return $value;
+  }
+  @return math.div($value, $root) * 1rem;
+}
+
+/// px → rem against the root size. Lengths are rem so a layout holds at 200% text zoom; a unit
+/// that cannot be converted is a build error rather than a size that is subtly off.
+@function rem($value, $root: 16px) {
+  @return -to-rem($value, $root, 'rem', 'rem(24px)');
+}
+
+/// One `clamp()` with a real slope and intercept: `$min` at a viewport `$from` wide, `$max` at
+/// `$to`, linear between and held outside. Type and space then scale with the viewport instead of
+/// stepping at a breakpoint. `$min` above `$max` is a size that shrinks, and is legal.
+@function fluid($min, $max, $from: 20rem, $to: 80rem) {
+  $min: -to-rem($min, 16px, 'fluid', 'fluid(16px, 32px)');
+  $max: -to-rem($max, 16px, 'fluid', 'fluid(16px, 32px)');
+  $from: -to-rem($from, 16px, 'fluid', 'fluid(16px, 32px)');
+  $to: -to-rem($to, 16px, 'fluid', 'fluid(16px, 32px)');
+
+  @if $from >= $to {
+    @error string.unquote('X_UI_INVALID_VALUE: fluid() needs $from below $to — got `#{$from}` and `#{$to}`. fix: pass the narrower viewport first, e.g. fluid(1rem, 2rem, 20rem, 80rem)');
+  }
+
+  $slope: math.div($max - $min, $to - $from);
+  $intercept: $min - $slope * $from;
+  // `clamp(MIN, VAL, MAX)` with MIN above MAX answers MIN at every width, so the bounds are
+  // ordered here rather than trusted to be.
+  @return clamp(math.min($min, $max), $intercept + $slope * 100vw, math.max($min, $max));
+}

package/src/tokens/reset.scss

@@ -115,8 +115,8 @@
 
 // Themed keyboard focus for anything the component layer forgot.
 :where(:focus-visible) {
-  outline: 2px solid t.role('accent');
-  outline-offset: 2px;
+  outline: t.stroke(thick) solid t.role('accent');
+  outline-offset: t.stroke(thick);
 }
 
 :where(:focus:not(:focus-visible)) {
@@ -153,9 +153,9 @@ html:has(dialog:modal) {
   *,
   *::before,
   *::after {
-    animation-duration: 0.01ms !important;
+    animation-duration: t.$still !important;
     animation-iteration-count: 1 !important;
-    transition-duration: 0.01ms !important;
+    transition-duration: t.$still !important;
     scroll-behavior: auto !important;
   }
 }

package/src/tokens/theme.scss

@@ -7,6 +7,7 @@
 @use 'radius';
 @use 'shadow';
 @use 'space';
+@use 'stroke';
 @use 'typography';
 @use 'z';
 
@@ -14,6 +15,7 @@
 @include shadow.emit;
 @include space.emit;
 @include radius.emit;
+@include stroke.emit;
 @include typography.emit;
 @include motion.emit;
 @include z.emit;

package/src/tokens/tokens.ts

@@ -119,6 +119,12 @@ export const radiusTokens = {
 
 export type RadiusName = keyof typeof radiusTokens;
 
+export const strokeTokens = {
+  hairline: '1px',
+  thick: '2px',
+  heavy: '3px',
+} as const;
+
 export const zTokens = {
   base: '0',
   raised: '10',