@orioncactuscorp/ui 1.14.0 → 1.15.0

package/src/scss/foundations/atomic.scss

@@ -1,19 +1,20 @@
 @use '../mixins/breakpoint' as *;
 @use '../mixins/color' as *;
+@use '../mixins/fluid' as *;
 @use '../mixins/radius' as *;
 @use '../mixins/utils' as *;
 
 :root {
   --oc-atomic-radius-factor: 1;
   --oc-atomic-radius-max: #{oc-radius(10000px)};
-  --oc-atomic-radius-huge: #{oc-radius(fluidClamp(toRem(24), $breakpoint-md, from, toRem(64)))};
-  --oc-atomic-radius-xlarge: #{oc-radius(fluidClamp(toRem(12), $breakpoint-md, from, toRem(32)))};
-  --oc-atomic-radius-large: #{oc-radius(fluidClamp(toRem(12), $breakpoint-md, from, toRem(24)))};
-  --oc-atomic-radius-medium: #{oc-radius(fluidClamp(toRem(12), $breakpoint-md, from, toRem(16)))};
-  --oc-atomic-radius-small: #{oc-radius(fluidClamp(toRem(10), $breakpoint-md, from, toRem(12)))};
-  --oc-atomic-radius-xsmall: #{oc-radius(fluidClamp(toRem(8), $breakpoint-md, from, toRem(10)))};
-  --oc-atomic-radius-mini: #{oc-radius(fluidClamp(toRem(6), $breakpoint-md, from, toRem(8)))};
-  --oc-atomic-radius-tiny: #{oc-radius(fluidClamp(toRem(4), $breakpoint-md, from, toRem(6)))};
+  --oc-atomic-radius-huge: #{oc-radius(oc-fluid(toRem(24), toRem(64), $breakpoint-md, from))};
+  --oc-atomic-radius-xlarge: #{oc-radius(oc-fluid(toRem(12), toRem(32), $breakpoint-md, from))};
+  --oc-atomic-radius-large: #{oc-radius(oc-fluid(toRem(12), toRem(24), $breakpoint-md, from))};
+  --oc-atomic-radius-medium: #{oc-radius(oc-fluid(toRem(12), toRem(16), $breakpoint-md, from))};
+  --oc-atomic-radius-small: #{oc-radius(oc-fluid(toRem(10), toRem(12), $breakpoint-md, from))};
+  --oc-atomic-radius-xsmall: #{oc-radius(oc-fluid(toRem(8), toRem(10), $breakpoint-md, from))};
+  --oc-atomic-radius-mini: #{oc-radius(oc-fluid(toRem(6), toRem(8), $breakpoint-md, from))};
+  --oc-atomic-radius-tiny: #{oc-radius(oc-fluid(toRem(4), toRem(6), $breakpoint-md, from))};
   --oc-atomic-radius-micro: #{oc-radius(toRem(4))};
 
   --oc-atomic-width-content: 35em;

package/src/scss/index.scss

@@ -11,8 +11,10 @@
 @forward './foundations/reset';
 @forward './mixins/breakpoint';
 @forward './mixins/utils';
+@forward './mixins/fluid';
 @forward './mixins/responsive';
 @forward './mixins/color';
+@forward './mixins/gradient';
 @forward './mixins/typo';
 @forward './mixins/element';
 @forward './mixins/focus';

package/src/scss/mixins/_fluid.scss

@@ -0,0 +1,57 @@
+@use 'sass:math';
+@use 'sass:meta';
+@use './units' as *;
+
+@function _oc-fluid-px-value($value) {
+  @if meta.type-of($value) != 'number' {
+    @error 'oc-fluid() min and max values must be Sass numbers with px or rem units.';
+  }
+
+  @if math.is-unitless($value) {
+    @error 'oc-fluid() min and max values must use px or rem units.';
+  }
+
+  @if math.unit($value) == 'px' {
+    @return stripUnit($value);
+  }
+
+  @if math.unit($value) == 'rem' {
+    @return stripUnit($value) * $rem-unit;
+  }
+
+  @error 'oc-fluid() min and max values must use px or rem units.';
+}
+
+@function _oc-fluid-viewport-value($bp) {
+  @if meta.type-of($bp) != 'number' {
+    @error 'oc-fluid() $bp must be a Sass number in px or unitless form.';
+  }
+
+  @if not math.is-unitless($bp) and math.unit($bp) != 'px' {
+    @error 'oc-fluid() $bp must be a Sass number in px or unitless form.';
+  }
+
+  $bp-num: stripUnit($bp);
+
+  @if $bp-num <= 0 {
+    @error 'oc-fluid() $bp must be greater than zero.';
+  }
+
+  @return $bp-num;
+}
+
+@function oc-fluid($min, $max, $bp, $anchor: to) {
+  $min-px: _oc-fluid-px-value($min);
+  $max-px: _oc-fluid-px-value($max);
+  $basis-px: $max-px;
+
+  @if $anchor == from {
+    $basis-px: $min-px;
+  } @else if $anchor != to {
+    @error "oc-fluid() anchor must be 'from' or 'to'.";
+  }
+
+  $bp-num: _oc-fluid-viewport-value($bp);
+
+  @return clamp(#{$min}, calc(#{$basis-px} / #{$bp-num} * 100vw), #{$max});
+}

package/src/scss/mixins/_fluid.test.ts

@@ -0,0 +1,87 @@
+import { compileString } from 'sass';
+import { describe, expect, it } from 'vitest';
+
+const compileScss = (source: string) =>
+  compileString(source, {
+    loadPaths: ['src/scss/mixins'],
+    style: 'compressed',
+  }).css.replace(/:\s+/g, ':');
+
+describe('oc-fluid function', () => {
+  it('defaults to the to anchor and accepts a direct pixel viewport basis', () => {
+    const css = compileScss(`
+      @use 'fluid' as *;
+      @use 'units' as *;
+
+      .title {
+        font-size: oc-fluid(toRem(16), toRem(20), 375px);
+      }
+    `);
+
+    expect(css).toContain('.title{font-size:clamp(1rem,20/375*100vw,1.25rem)}');
+  });
+
+  it('accepts a named breakpoint value and the from anchor', () => {
+    const css = compileScss(`
+      @use 'breakpoint' as *;
+      @use 'fluid' as *;
+      @use 'units' as units;
+
+      .radius {
+        border-radius: oc-fluid(units.toRem(10), units.toRem(12), $breakpoint-md, from);
+      }
+    `);
+
+    expect(css).toContain(
+      '.radius{border-radius:clamp(0.625rem,10/768*100vw,0.75rem)}',
+    );
+  });
+
+  it('supports pixel endpoints and mixed compatible length units', () => {
+    const css = compileScss(`
+      @use 'fluid' as *;
+
+      .pixel {
+        font-size: oc-fluid(16px, 20px, 375px);
+      }
+
+      .mixed {
+        padding-block: oc-fluid(1rem, 20px, 375px);
+      }
+    `);
+
+    expect(css).toContain('.pixel{font-size:clamp(16px,20/375*100vw,20px)}');
+    expect(css).toContain(
+      '.mixed{padding-block:clamp(1rem,20/375*100vw,20px)}',
+    );
+  });
+
+  it('rejects an unknown anchor', () => {
+    expect(() =>
+      compileScss(`
+        @use 'fluid' as *;
+        @use 'units' as *;
+
+        .invalid {
+          font-size: oc-fluid(toRem(16), toRem(20), 375px, center);
+        }
+      `),
+    ).toThrow("oc-fluid() anchor must be 'from' or 'to'.");
+  });
+});
+
+describe('fluidClamp compatibility function', () => {
+  it('preserves the legacy argument order', () => {
+    const css = compileScss(`
+      @use 'utils' as *;
+
+      .legacy {
+        font-size: fluidClamp(toRem(16), 375px, to, toRem(20));
+      }
+    `);
+
+    expect(css).toContain(
+      '.legacy{font-size:clamp(1rem,20/375*100vw,1.25rem)}',
+    );
+  });
+});

package/src/scss/mixins/_gradient.scss

@@ -0,0 +1,99 @@
+@use 'sass:list';
+@use 'sass:math';
+@use 'sass:meta';
+@use 'sass:string';
+
+@function _oc-gradient-require-direction($direction) {
+  @if list.index((top, right, bottom, left), $direction) == null {
+    @error 'Unknown gradient direction: #{$direction}. Use top, right, bottom, or left.';
+  }
+
+  @return $direction;
+}
+
+@function _oc-gradient-position($start, $end, $progress) {
+  @if $progress == 0 {
+    @return $start;
+  }
+
+  @if $progress == 1 {
+    @return $end;
+  }
+
+  @return string.unquote('calc(#{$start} + (#{$end} - #{$start}) * #{$progress})');
+}
+
+@function _oc-gradient-color($from, $to, $progress) {
+  @if $progress == 0 {
+    @return $from;
+  }
+
+  @if $progress == 1 {
+    @return $to;
+  }
+
+  $from-weight: math.percentage(1 - $progress);
+
+  @return string.unquote('color-mix(in srgb, #{$from} #{$from-weight}, #{$to})');
+}
+
+@function _oc-easing-gradient-stops($from, $to, $start, $end) {
+  // Eight intervals keep smoothstep boundaries visually soft without making every generated gradient excessively large.
+  $stepCount: 8;
+  $stops: ();
+
+  @for $index from 0 through $stepCount {
+    $linear-progress: math.div($index, $stepCount);
+
+    // Smoothstep keeps the color-change velocity at both boundaries continuous.
+    $eased-progress: 3 * math.pow($linear-progress, 2) - 2 * math.pow($linear-progress, 3);
+    $color: _oc-gradient-color($from, $to, $eased-progress);
+    $position: _oc-gradient-position($start, $end, $linear-progress);
+
+    $stops: list.append($stops, $color $position, comma);
+  }
+
+  @return $stops;
+}
+
+@function oc-easing-gradient($direction, $from, $to, $start: 0%, $end: 100%) {
+  $validated-direction: _oc-gradient-require-direction($direction);
+  $stops: _oc-easing-gradient-stops($from, $to, $start, $end);
+
+  @return linear-gradient(to $validated-direction, $stops);
+}
+
+@function _oc-gradient-mask-image($direction, $start-fade-size, $end-fade-size, $content-size) {
+  $validated-direction: _oc-gradient-require-direction($direction);
+  $start-stops: _oc-easing-gradient-stops(transparent, black, 0px, $start-fade-size);
+  $end-fade-start: string.unquote('calc(#{$content-size} - #{$end-fade-size})');
+  $end-stops: _oc-easing-gradient-stops(black, transparent, $end-fade-start, $content-size);
+  $stops: list.join($start-stops, $end-stops, comma);
+
+  @return linear-gradient(to $validated-direction, $stops);
+}
+
+@mixin oc-gradient-mask($direction, $start-fade-size: 0px, $end-fade-size: 0px, $content-size: 100%) {
+  $mask: _oc-gradient-mask-image($direction, $start-fade-size, $end-fade-size, $content-size);
+
+  // stylelint-disable-next-line property-no-vendor-prefix -- Safari still needs the prefixed mask property for gradient fades.
+  -webkit-mask-image: $mask;
+  // stylelint-disable-next-line declaration-block-no-duplicate-properties -- Keep the standard property after the Safari fallback.
+  mask-image: $mask;
+}
+
+@mixin oc-gradient-mask-edges($top-fade-size: 0px, $right-fade-size: 0px, $bottom-fade-size: 0px, $left-fade-size: 0px, $inline-content-size: 100%, $block-content-size: 100%) {
+  $block-mask: _oc-gradient-mask-image(bottom, $top-fade-size, $bottom-fade-size, $block-content-size);
+  $inline-mask: _oc-gradient-mask-image(right, $left-fade-size, $right-fade-size, $inline-content-size);
+
+  // Both layers encode only black alpha, so intersection multiplies corner alpha and is order-independent.
+  $masks: $block-mask, $inline-mask;
+
+  // stylelint-disable-next-line property-no-vendor-prefix -- WebKit uses its legacy Porter-Duff keyword for mask intersection.
+  -webkit-mask-composite: source-in;
+  // stylelint-disable-next-line property-no-vendor-prefix -- Safari still needs the prefixed mask property for gradient fades.
+  -webkit-mask-image: $masks;
+  mask-composite: intersect;
+  // stylelint-disable-next-line declaration-block-no-duplicate-properties -- Keep the standard property after the Safari fallback.
+  mask-image: $masks;
+}

package/src/scss/mixins/_gradient.test.ts

@@ -0,0 +1,111 @@
+import { compileString } from 'sass';
+import { describe, expect, it } from 'vitest';
+
+function compile(source: string) {
+  return compileString(
+    `
+      @use 'gradient' as *;
+
+      ${source}
+    `,
+    {
+      loadPaths: ['src/scss/mixins'],
+      style: 'compressed',
+    },
+  ).css;
+}
+
+describe('gradient helpers', () => {
+  it.each(['top', 'right', 'bottom', 'left'] as const)(
+    'creates a smooth easing gradient toward %s',
+    direction => {
+      const css = compile(`
+        .sample {
+          background-image: oc-easing-gradient(${direction}, red, transparent);
+        }
+      `);
+
+      expect(css).toContain(`linear-gradient(to ${direction}, red 0%`);
+      expect(css).toContain(
+        'color-mix(in srgb, red 95.703125%, transparent) calc(0% + (100% - 0%) * 0.125)',
+      );
+      expect(css).toContain(
+        'color-mix(in srgb, red 50%, transparent) calc(0% + (100% - 0%) * 0.5)',
+      );
+      expect(css).toContain('transparent 100%');
+    },
+  );
+
+  it('applies a two-sided mask with variable fade and content sizes', () => {
+    const css = compile(`
+      .sample {
+        @include oc-gradient-mask(
+          right,
+          var(--example-start-fade-size),
+          var(--example-end-fade-size),
+          var(--example-content-size)
+        );
+      }
+    `);
+
+    expect(css).toContain('-webkit-mask-image:linear-gradient(to right');
+    expect(css).toContain('mask-image:linear-gradient(to right');
+    expect(css).toContain('transparent 0px');
+    expect(css).toContain('black var(--example-start-fade-size)');
+    expect(css).toContain(
+      'black calc(var(--example-content-size) - var(--example-end-fade-size))',
+    );
+    expect(css).toContain('transparent var(--example-content-size)');
+  });
+
+  it('keeps zero-length fades valid with the default mask sizes', () => {
+    const css = compile(`
+      .sample {
+        @include oc-gradient-mask(bottom);
+      }
+    `);
+
+    expect(css).toContain('linear-gradient(to bottom, transparent 0px');
+    expect(css).toContain('black 0px');
+    expect(css).toContain('black calc(100% - 0px)');
+    expect(css).toContain('transparent 100%');
+  });
+
+  it('intersects block and inline masks for four independently sized edges', () => {
+    const css = compile(`
+      .sample {
+        @include oc-gradient-mask-edges(
+          var(--example-top-fade-size),
+          var(--example-right-fade-size),
+          var(--example-bottom-fade-size),
+          var(--example-left-fade-size),
+          var(--example-inline-content-size),
+          var(--example-block-content-size)
+        );
+      }
+    `);
+
+    expect(css).toContain('-webkit-mask-composite:source-in');
+    expect(css).toContain('mask-composite:intersect');
+    expect(css).toContain('-webkit-mask-image:linear-gradient(to bottom');
+    expect(css).toContain('),linear-gradient(to right');
+    expect(css).toContain('black var(--example-top-fade-size)');
+    expect(css).toContain('black var(--example-left-fade-size)');
+    expect(css).toContain(
+      'calc(var(--example-block-content-size) - var(--example-bottom-fade-size))',
+    );
+    expect(css).toContain(
+      'calc(var(--example-inline-content-size) - var(--example-right-fade-size))',
+    );
+  });
+
+  it('rejects unsupported directions', () => {
+    expect(() =>
+      compile(`
+        .sample {
+          background-image: oc-easing-gradient(inline-start, red, blue);
+        }
+      `),
+    ).toThrow('Unknown gradient direction: inline-start');
+  });
+});

package/src/scss/mixins/_responsive.scss

@@ -4,6 +4,7 @@
 @use 'sass:meta';
 @use '../foundations/responsive.config' as *;
 @use './breakpoint' as *;
+@use './fluid' as *;
 @use './utils' as *;
 
 $oc-responsive-stop-order: (min, sm, md, lg, xl, hg);
@@ -155,7 +156,7 @@ $oc-responsive-point-order: (min-sm, min-md, min-lg, min-xl, min-hg);
   }
 
   @if $oc-responsive-mode == fluid {
-    @return fluidClamp($from, $basis, $anchor, $to);
+    @return oc-fluid($from, $to, $basis, $anchor);
   }
 
   @error "Unknown responsive mode '#{$oc-responsive-mode}'.";

package/src/scss/mixins/_typo.scss

@@ -1,6 +1,7 @@
 @use 'sass:list';
 @use 'sass:map';
 @use './breakpoint' as *;
+@use './fluid' as *;
 @use './utils' as *;
 
 @mixin typo($variant, $weight: normal) {
@@ -33,7 +34,7 @@
         $anchor: list.nth($value, 4);
       }
 
-      $clamp: fluidClamp(toRem($from), $basis, $anchor, toRem($to));
+      $clamp: oc-fluid(toRem($from), toRem($to), $basis, $anchor);
 
       @if $key == sm {
         @include respond-to(sm) {

package/src/scss/mixins/_units.scss

@@ -0,0 +1,14 @@
+@use 'sass:math';
+
+$rem-unit: 16;
+
+@function toRem($px) {
+  @return math.div($px, $rem-unit) * 1rem;
+}
+
+@function stripUnit($value) {
+  @if math.is-unitless($value) {
+    @return $value;
+  }
+  @return math.div($value, ($value * 0 + 1));
+}

package/src/scss/mixins/_utils.scss

@@ -1,26 +1,7 @@
-@use 'sass:math';
+@use './fluid' as *;
 
-$rem-unit: 16;
-
-@function toRem($px) {
-  @return math.div($px, $rem-unit) * 1rem;
-}
-
-@function stripUnit($value) {
-  @if math.is-unitless($value) {
-    @return $value;
-  }
-  @return math.div($value, ($value * 0 + 1));
-}
+@forward './units';
 
 @function fluidClamp($from, $bp, $anchor: to, $to) {
-  $basis: $to;
-  @if $anchor == from {
-    $basis: $from;
-  }
-  $basis-num: stripUnit($basis);
-  $bp-num: stripUnit($bp);
-  $basis-px: $basis-num * $rem-unit;
-
-  @return clamp(#{$from}, calc(#{$basis-px} / #{$bp-num} * 100vw), #{$to});
+  @return oc-fluid($from, $to, $bp, $anchor);
 }