@skewedaspect/sleekspace-ui 0.7.0 → 0.8.0

package/src/styles/mixins/_responsive.scss

@@ -0,0 +1,184 @@
+//----------------------------------------------------------------------------------------------------------------------
+// Responsive Mixins
+//
+// Shared breakpoint scale and helpers for @media (viewport) and @container (component) queries.
+// Keep these aligned with --sk-bp-* in tokens/_foundation-breakpoints.scss.
+//----------------------------------------------------------------------------------------------------------------------
+
+@use 'sass:map';
+@use 'sass:math';
+@use 'sass:meta';
+
+$breakpoints: (
+    sm: 640px,
+    md: 1024px,
+    lg: 1280px,
+    xl: 1536px,
+);
+
+@function bp($size)
+{
+    @if not map.has-key($breakpoints, $size)
+    {
+        @error "Unknown breakpoint '#{$size}'. Valid: #{map.keys($breakpoints)}.";
+    }
+    @return map.get($breakpoints, $size);
+}
+
+//----------------------------------------------------------------------------------------------------------------------
+// Fluid Sizing
+//
+// `fluid-size($min, $max, $from: sm, $to: lg)` emits a `clamp()` expression that linearly
+// interpolates `$min` to `$max` as the viewport grows from `$from` to `$to`.
+//
+// - `$min` / `$max` accept `px` or `rem` lengths (rem preferred for typography so user font
+//   scaling carries through).
+// - `$from` / `$to` accept a breakpoint name (sm/md/lg/xl) or an explicit length.
+// - Output pins to the floor/ceiling outside the fluid band; it never overshoots `$min` or
+//   `$max`.
+//
+// Why this exists rather than inline `clamp()`: consistency. Consumers anchor to the same
+// breakpoint scale everywhere instead of eyeballing viewport widths, and the math for the
+// slope + intercept is done once here instead of in every stylesheet.
+//
+// Example:
+//   h1 { font-size: fluid-size(1.5rem, 3rem); }            // sm → lg (default)
+//   h2 { font-size: fluid-size(1.25rem, 2rem, md, xl); }   // md → xl
+//   .hero { padding: fluid-size(1rem, 4rem); }              // spacing works too
+//----------------------------------------------------------------------------------------------------------------------
+
+@function _fluid-resolve-vp($value)
+{
+    @if meta.type-of($value) == 'string' { @return bp($value); }
+    @return $value;
+}
+
+@function _fluid-to-px($value)
+{
+    $unit: math.unit($value);
+    @if $unit == 'px' { @return math.div($value, 1px); }
+    @if $unit == 'rem' { @return math.div($value, 1rem) * 16; }
+    @error "fluid-size expects px or rem lengths; got '#{$value}' (unit: '#{$unit}').";
+}
+
+@function fluid-size($min-size, $max-size, $from: sm, $to: lg)
+{
+    $min-px: _fluid-to-px($min-size);
+    $max-px: _fluid-to-px($max-size);
+    $from-vp-px: _fluid-to-px(_fluid-resolve-vp($from));
+    $to-vp-px: _fluid-to-px(_fluid-resolve-vp($to));
+
+    @if $to-vp-px == $from-vp-px
+    {
+        @error "fluid-size: from-viewport and to-viewport must differ (got #{$from-vp-px}px for both).";
+    }
+
+    // size = slope * viewport + intercept (all in px). 1vw = viewport / 100, so
+    // `slope * viewport` in px == `slope * 100` in vw. Output the intercept in rem so it
+    // scales with the user's base font size.
+    $slope: math.div($max-px - $min-px, $to-vp-px - $from-vp-px);
+    $intercept-rem: math.div($min-px - $slope * $from-vp-px, 16);
+    $slope-vw: $slope * 100;
+
+    @return clamp(#{$min-size}, calc(#{$intercept-rem}rem + #{$slope-vw}vw), #{$max-size});
+}
+
+//----------------------------------------------------------------------------------------------------------------------
+// Viewport Queries
+//----------------------------------------------------------------------------------------------------------------------
+
+@mixin media-up($size)
+{
+    @media (min-width: #{bp($size)})
+    {
+        @content;
+    }
+}
+
+@mixin media-down($size)
+{
+    @media (max-width: #{bp($size) - 0.02px})
+    {
+        @content;
+    }
+}
+
+//----------------------------------------------------------------------------------------------------------------------
+// Container Queries
+//
+// Caller is responsible for establishing `container-type` / `container-name` on the ancestor.
+//----------------------------------------------------------------------------------------------------------------------
+
+@mixin container-up($size, $name: null)
+{
+    @if $name
+    {
+        @container #{$name} (min-width: #{bp($size)})
+        {
+            @content;
+        }
+    }
+    @else
+    {
+        @container (min-width: #{bp($size)})
+        {
+            @content;
+        }
+    }
+}
+
+@mixin container-down($size, $name: null)
+{
+    @if $name
+    {
+        @container #{$name} (max-width: #{bp($size) - 0.02px})
+        {
+            @content;
+        }
+    }
+    @else
+    {
+        @container (max-width: #{bp($size) - 0.02px})
+        {
+            @content;
+        }
+    }
+}
+
+//----------------------------------------------------------------------------------------------------------------------
+// Input & Motion Preferences
+//----------------------------------------------------------------------------------------------------------------------
+
+@mixin touch
+{
+    @media (pointer: coarse)
+    {
+        @content;
+    }
+}
+
+@mixin fine-pointer
+{
+    @media (pointer: fine)
+    {
+        @content;
+    }
+}
+
+@mixin reduced-motion
+{
+    @media (prefers-reduced-motion: reduce)
+    {
+        @content;
+    }
+}
+
+@mixin motion-safe
+{
+    @media (prefers-reduced-motion: no-preference)
+    {
+        @content;
+    }
+}
+
+//----------------------------------------------------------------------------------------------------------------------

package/src/styles/mixins/fluidSize.test.ts

@@ -0,0 +1,149 @@
+//----------------------------------------------------------------------------------------------------------------------
+// Fluid Size Math Tests
+//
+// Compiles the `fluid-size` SCSS function against a handful of invocations and asserts the
+// emitted clamp() hits the intended anchor points. Guards against unit-conversion drift
+// (px/rem/vw) that silently flips the fluid curve.
+//----------------------------------------------------------------------------------------------------------------------
+
+import { describe, expect, it } from 'vitest';
+import { compileString } from 'sass';
+import { dirname } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+//----------------------------------------------------------------------------------------------------------------------
+
+const here = dirname(fileURLToPath(import.meta.url));
+
+function emit(call : string) : string
+{
+    const source = `
+        @use 'responsive' as *;
+
+        .t { font-size: ${ call }; }
+    `;
+    const { css } = compileString(source, {
+        loadPaths: [ here ],
+        url: pathToFileURL(`${ here }/fluidSize.test.scss`),
+    });
+    const match = css.match(/font-size:\s*([^;]+);/);
+    if(!match) { throw new Error(`No font-size in compiled output:\n${ css }`); }
+    return match[1].trim();
+}
+
+/**
+ * Parse `clamp(min, calc(intercept-rem + slope-vw), max)` into numeric parts for assertions.
+ * Keeps unit suffixes as-is on min/max since callers usually pass them in a specific unit.
+ */
+function parseClamp(expr : string) : { min : string; interceptRem : number; slopeVw : number; max : string }
+{
+    // Sass may or may not preserve the `calc()` wrapper around the preferred value, so make it
+    // optional here.
+    const match = expr.match(
+        /^clamp\(\s*([^,]+),\s*(?:calc\(\s*)?(-?[\d.]+)rem\s*\+\s*(-?[\d.]+)vw\s*\)?,\s*([^)]+)\s*\)$/
+    );
+    if(!match) { throw new Error(`Could not parse clamp expression: ${ expr }`); }
+    return {
+        min: match[1].trim(),
+        interceptRem: parseFloat(match[2]),
+        slopeVw: parseFloat(match[3]),
+        max: match[4].trim(),
+    };
+}
+
+//----------------------------------------------------------------------------------------------------------------------
+
+describe('fluid-size (SCSS)', () =>
+{
+    describe('default breakpoints (sm → lg, 640px → 1280px)', () =>
+    {
+        it('1rem → 1.5rem: 0.5rem intercept + 1.25vw slope', () =>
+        {
+            const parsed = parseClamp(emit('fluid-size(1rem, 1.5rem)'));
+            expect(parsed.min).toBe('1rem');
+            expect(parsed.max).toBe('1.5rem');
+            expect(parsed.interceptRem).toBeCloseTo(0.5, 5);
+            expect(parsed.slopeVw).toBeCloseTo(1.25, 5);
+        });
+
+        it('hits min at the from-viewport anchor (vp=640px)', () =>
+        {
+            // clamp lower bound is 1rem; verify the calc also evaluates to 1rem at vp=640.
+            // At vp=640, 1vw = 6.4px = 0.4rem. intercept(0.5) + slope(1.25) * 0.4 = 1.0rem. ✓
+            const parsed = parseClamp(emit('fluid-size(1rem, 1.5rem)'));
+            const px = (parsed.interceptRem * 16) + ((parsed.slopeVw / 100) * 640);
+            expect(px).toBeCloseTo(16, 2); // 1rem = 16px
+        });
+
+        it('hits max at the to-viewport anchor (vp=1280px)', () =>
+        {
+            const parsed = parseClamp(emit('fluid-size(1rem, 1.5rem)'));
+            const px = (parsed.interceptRem * 16) + ((parsed.slopeVw / 100) * 1280);
+            expect(px).toBeCloseTo(24, 2); // 1.5rem = 24px
+        });
+    });
+
+    describe('custom breakpoint range (md → xl, 1024px → 1536px)', () =>
+    {
+        it('1.25rem → 2rem hits both anchors', () =>
+        {
+            const parsed = parseClamp(emit('fluid-size(1.25rem, 2rem, md, xl)'));
+            const atMd = (parsed.interceptRem * 16) + ((parsed.slopeVw / 100) * 1024);
+            const atXl = (parsed.interceptRem * 16) + ((parsed.slopeVw / 100) * 1536);
+            expect(atMd).toBeCloseTo(20, 2); // 1.25rem
+            expect(atXl).toBeCloseTo(32, 2); // 2rem
+        });
+    });
+
+    describe('px inputs', () =>
+    {
+        it('accepts px sizes and preserves them in the clamp bounds', () =>
+        {
+            const parsed = parseClamp(emit('fluid-size(16px, 64px, sm, lg)'));
+            expect(parsed.min).toBe('16px');
+            expect(parsed.max).toBe('64px');
+            const atSm = (parsed.interceptRem * 16) + ((parsed.slopeVw / 100) * 640);
+            const atLg = (parsed.interceptRem * 16) + ((parsed.slopeVw / 100) * 1280);
+            expect(atSm).toBeCloseTo(16, 2);
+            expect(atLg).toBeCloseTo(64, 2);
+        });
+    });
+
+    describe('explicit viewport lengths', () =>
+    {
+        it('accepts px viewports in place of breakpoint names', () =>
+        {
+            const named = parseClamp(emit('fluid-size(1rem, 1.5rem, sm, lg)'));
+            const explicit = parseClamp(emit('fluid-size(1rem, 1.5rem, 640px, 1280px)'));
+            expect(explicit.interceptRem).toBeCloseTo(named.interceptRem, 5);
+            expect(explicit.slopeVw).toBeCloseTo(named.slopeVw, 5);
+        });
+    });
+
+    describe('edge cases', () =>
+    {
+        it('equal min and max yields zero slope', () =>
+        {
+            const parsed = parseClamp(emit('fluid-size(1rem, 1rem)'));
+            expect(parsed.slopeVw).toBeCloseTo(0, 5);
+            expect(parsed.interceptRem).toBeCloseTo(1, 5);
+        });
+
+        it('throws when from-viewport equals to-viewport', () =>
+        {
+            expect(() => emit('fluid-size(1rem, 1.5rem, 640px, 640px)')).toThrow();
+        });
+
+        it('throws on unknown breakpoint name', () =>
+        {
+            expect(() => emit('fluid-size(1rem, 1.5rem, bogus, lg)')).toThrow();
+        });
+
+        it('throws on unsupported unit', () =>
+        {
+            expect(() => emit('fluid-size(1em, 2em)')).toThrow();
+        });
+    });
+});
+
+//----------------------------------------------------------------------------------------------------------------------

package/src/styles/tokens/_foundation-breakpoints.scss

@@ -0,0 +1,26 @@
+/**
+ * Foundation Tokens - Breakpoints
+ *
+ * Single-source breakpoint scale shared between @media (viewport) and
+ * @container (component) queries. CSS custom properties are exposed for
+ * consumer visibility and JS access; SCSS-level values live in
+ * mixins/_responsive.scss and drive the media-up/container-up mixins.
+ *
+ * Scale rationale:
+ *   sm ( 640px) - phones held landscape / narrow tablets
+ *   md (1024px) - tablets / small laptop -- persistent sidebar threshold
+ *   lg (1280px) - standard laptop / desktop
+ *   xl (1536px) - large desktop / ultrawide
+ */
+
+:root
+{
+    /* ===================================================================
+     * Viewport Breakpoints
+     * =================================================================== */
+
+    --sk-bp-sm: 640px;
+    --sk-bp-md: 1024px;
+    --sk-bp-lg: 1280px;
+    --sk-bp-xl: 1536px;
+}

package/src/styles/tokens/_foundation-z-index.scss

@@ -0,0 +1,38 @@
+/**
+ * Foundation Tokens - Z-Index Stacking Scale
+ *
+ * One scale every SleekSpace component layers against so portaled content stacks in a
+ * predictable, documented order. Custom consumer layers can slot in between tokens by
+ * picking a number within the reserved gap.
+ *
+ * Reading order (bottom to top):
+ *   sticky        100 - App-shell chrome that sits above the flow (sticky navbar / footer)
+ *   drawer-scrim  900 - Dim + blur layer behind an open drawer
+ *   drawer        901 - SkPage sidebar / aside drawer
+ *   modal-scrim  1000 - Dim layer behind an open modal
+ *   modal        1001 - SkModal content -- must be above drawer so modals launched from
+ *                       inside a drawer render on top
+ *   popover      1100 - SkPopover (floating anchored surface)
+ *   dropdown     1100 - SkDropdown + SkListbox menus (same layer as popover; a menu opened
+ *                       inside a modal renders above the modal)
+ *   tooltip      1200 - SkTooltip -- higher than menus so a tooltip on a menu item stays
+ *                       visible
+ *   toast        1300 - Ephemeral top-of-stack notifications
+ */
+
+:root
+{
+    /* ===================================================================
+     * Layering Scale
+     * =================================================================== */
+
+    --sk-z-sticky: 100;
+    --sk-z-drawer-scrim: 900;
+    --sk-z-drawer: 901;
+    --sk-z-modal-scrim: 1000;
+    --sk-z-modal: 1001;
+    --sk-z-popover: 1100;
+    --sk-z-dropdown: 1100;
+    --sk-z-tooltip: 1200;
+    --sk-z-toast: 1300;
+}

package/src/styles/tokens/index.scss

@@ -25,6 +25,8 @@
 @use 'foundation-transitions';
 @use 'foundation-typography';
 @use 'foundation-scrollbar';
+@use 'foundation-breakpoints';
+@use 'foundation-z-index';
 
 /* ===================================================================
  * Semantic Tokens