@linear_non/stellar-kit 3.0.0 → 3.0.2

package/core/Application.js

@@ -110,13 +110,15 @@ export class ApplicationManager {
 
   /**
    * Initialize and activate all global systems.
-   * @param {{ isSmooth: boolean }} options
+   * @param {{ isSmooth: boolean, useExternalScroll?: boolean }} options
    * @private
    */
-  _initSystems({ isSmooth }) {
+  _initSystems({ isSmooth, useExternalScroll = false }) {
     const resize = new Resize()
     const mouse = new Mouse()
-    const scroll = new Scroll({ isSmooth: isSmooth })
+
+    // If using external scroll (Lenis, etc.), do NOT create Scroll.
+    const scroll = useExternalScroll ? null : new Scroll({ isSmooth })
     const raf = new Raf()
 
     this.systems = { resize, mouse, scroll, raf }
@@ -127,6 +129,11 @@ export class ApplicationManager {
     kitStore.raf = raf
 
     kitStore.flags.isSmooth = isSmooth
+    kitStore.flags.useExternalScroll = useExternalScroll
+
+    if (useExternalScroll) {
+      document.body.classList.add("is-external-scroll")
+    }
 
     // Phase 1: init
     Object.values(this.systems).forEach(sys => {
@@ -165,6 +172,10 @@ export class ApplicationManager {
     Object.values(this.systems).forEach(sys => {
       if (sys && typeof sys.destroy === "function") sys.destroy()
     })
+
+    kitStore.scroll = null
+    kitStore.flags.useExternalScroll = false
+
     this.initialized = false
   }
 
@@ -177,23 +188,40 @@ export class ApplicationManager {
    *   page: { element?: string, container?: string },
    *   load?: string,
    *   isSmooth?: boolean,
+   *   useExternalScroll?: boolean,
    *   dim?: { d?: number, m?: number }
    * }} config
    * @returns {Promise<typeof kitStore>}
    */
   async initialize(config) {
     if (this.initialized) return kitStore
-    if (!sniffer.isDesktop) {
-      config.isSmooth = false
-    } else if (!config.isSmooth && sniffer.isDesktop) {
-      config.isSmooth = true
+
+    const useExternalScroll = Boolean(config.useExternalScroll)
+
+    // Only apply the desktop heuristic for internal Scroll mode
+    if (!useExternalScroll) {
+      if (!sniffer.isDesktop) {
+        config.isSmooth = false
+      } else if (!config.isSmooth && sniffer.isDesktop) {
+        config.isSmooth = true
+      }
+    } else {
+      // External scroll engine usually behaves like smooth scroll
+      if (typeof config.isSmooth === "undefined") {
+        config.isSmooth = true
+      }
     }
 
     await this._waitDOM()
-    Debug.log("APP", "DOM ready with", config.isSmooth ? "smooth " : "native " + "scroll.")
+    Debug.log(
+      "APP",
+      "DOM ready with",
+      config.isSmooth ? "smooth scroll." : "native scroll.",
+      useExternalScroll ? "-- external engine" : "-- internal"
+    )
 
     this._initStore(config)
-    this._initSystems({ isSmooth: config.isSmooth })
+    this._initSystems({ isSmooth: config.isSmooth, useExternalScroll })
 
     this.initialized = true
     Debug.log("APP", "Application ready.", kitStore)
@@ -260,8 +288,6 @@ export class ApplicationManager {
     if (this.systems.raf?.setScrollTrigger) {
       this.systems.raf.setScrollTrigger()
     }
-
-    this._softResize()
   }
 
   /**
@@ -275,18 +301,6 @@ export class ApplicationManager {
     document.documentElement.style.setProperty("--mobile", m)
   }
 
-  /**
-   * Trigger a "soft resize":
-   * - Emit resize event
-   * - Refresh ScrollTrigger
-   * @private
-   */
-  _softResize() {
-    Debug.log("APP", "Soft resize triggered.")
-    emitter.emit(EVENTS.APP_SMOOTH_RESIZE)
-    ScrollTrigger.refresh()
-  }
-
   /**
    * Wait for DOM ready before execution.
    * @returns {Promise<void>}

package/core/PageEngine.js

@@ -133,19 +133,38 @@ export default class PageEngine {
   }
 
   /**
-   * Receives scroll and mouse data from Raf (APP_TICK).
-   * Packages them and forwards to Manager.tick().
+   * Receives data from global Raf (APP_TICK).
+   * In internal mode, uses {current, diff} from Scroll.js.
+   * In external mode (Lenis), calls smooth.raf() and derives scroll.
    *
    * @param {{ current: number, diff: number, mouse: EngineMouseState }} param0
    */
   tick = ({ current, diff, mouse }) => {
-    const { isResizing, isLocked } = kitStore.flags
+    const { isResizing, isLocked, useExternalScroll } = kitStore.flags
 
     if (isResizing || isLocked) return
     if (!this.manager) return
 
-    this.scroll.current = current
-    this.scroll.direction = diff > 0 ? "down" : "up"
+    let nextScroll = current
+    let delta = diff
+
+    if (useExternalScroll && this.smooth?.raf) {
+      const t = performance.now()
+      this.smooth.raf(t)
+
+      if (typeof this.smooth.scroll === "number") {
+        nextScroll = this.smooth.scroll
+      } else if (typeof this.smooth.targetScroll === "number") {
+        nextScroll = this.smooth.targetScroll
+      } else {
+        nextScroll = window.scrollY || window.pageYOffset || 0
+      }
+
+      delta = nextScroll - this.scroll.current
+    }
+
+    this.scroll.current = nextScroll
+    this.scroll.direction = delta > 0 ? "down" : "up"
 
     this.mouse.x = mouse.x
     this.mouse.y = mouse.y
@@ -163,7 +182,11 @@ export default class PageEngine {
   resize = () => {
     Debug.log("ENGINE", "Resize")
 
+    // Internal Smooth
     this.smooth?.update?.()
+    // Lenis
+    this.smooth?.resize?.()
+
     this.manager?.resize?.()
   }
 

package/events/Raf.js

@@ -1,6 +1,6 @@
 import { kitStore } from "../kitStore"
 import emitter, { EVENTS } from "./Emitter"
-import { lerp } from "../utils"
+import { Debug, lerp } from "../utils"
 import { gsap, ScrollTrigger } from "../libraries/gsap"
 
 export default class Raf {
@@ -139,6 +139,12 @@ export default class Raf {
     const { pageContent } = kitStore
     const scroller = pageContent || document.body
 
+    Debug.log(
+      "RAF",
+      "Setting ScrollTrigger scroller to:",
+      `#${scroller.id}` || `.${scroller.className}` || scroller.tagName
+    )
+
     ScrollTrigger.defaults({
       scroller,
     })

package/package.json

@@ -1,8 +1,10 @@
 {
   "name": "@linear_non/stellar-kit",
-  "version": "3.0.0",
+  "version": "3.0.2",
   "description": "Stellar frontend core for Non-Linear Studio projects.",
+  "type": "module",
   "main": "/core/index.js",
+  "sass": "./styles/index.scss",
   "exports": {
     ".": "./kitStore.js",
     "./utils": "./utils/index.js",
@@ -10,9 +12,10 @@
     "./classes": "./classes/index.js",
     "./events": "./events/index.js",
     "./plugins": "./plugins/index.js",
-    "./gsap": "./libraries/gsap/index.js"
+    "./gsap": "./libraries/gsap/index.js",
+    "./styles": "./styles/index.scss",
+    "./styles/helpers": "./styles/helpers/index.scss"
   },
-  "type": "module",
   "scripts": {
     "dev": "vite",
     "build": "vite build",
@@ -27,6 +30,7 @@
     "utils/",
     "libraries/",
     "libraries/gsap/",
+    "styles/",
     "kitStore.js",
     "index.js"
   ],

package/styles/base/reset.scss

@@ -0,0 +1,176 @@
+* {
+  margin: 0;
+  padding: 0;
+  text-rendering: optimizeLegibility;
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+  -webkit-tap-highlight-color: rgba(0, 0, 0, 0);
+}
+
+*,
+*::after,
+*::before {
+  box-sizing: border-box;
+}
+
+html,
+body,
+div,
+span,
+applet,
+object,
+iframe,
+h1,
+h2,
+h3,
+h4,
+h5,
+h6,
+p,
+blockquote,
+pre,
+a,
+abbr,
+acronym,
+address,
+big,
+cite,
+code,
+del,
+dfn,
+em,
+img,
+ins,
+kbd,
+q,
+s,
+samp,
+small,
+strike,
+strong,
+sub,
+sup,
+tt,
+var,
+b,
+u,
+i,
+center,
+dl,
+dt,
+dd,
+ol,
+ul,
+li,
+fieldset,
+form,
+label,
+legend,
+table,
+caption,
+tbody,
+tfoot,
+thead,
+tr,
+th,
+td,
+article,
+aside,
+canvas,
+details,
+embed,
+figure,
+figcaption,
+footer,
+header,
+hgroup,
+menu,
+nav,
+output,
+ruby,
+section,
+summary,
+time,
+mark,
+audio,
+video {
+  border: 0;
+  font: inherit;
+  font-size: 100%;
+  margin: 0;
+  padding: 0;
+  vertical-align: baseline;
+}
+
+article,
+aside,
+details,
+figcaption,
+figure,
+footer,
+header,
+hgroup,
+menu,
+nav,
+section {
+  display: block;
+}
+
+html {
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+  text-rendering: optimizelegibility;
+}
+
+.is-external-scroll {
+  body,
+  html {
+    position: fixed;
+    top: 0;
+    left: 0;
+    width: 100%;
+    height: 100%;
+  }
+}
+
+a {
+  color: inherit;
+  text-decoration: none;
+}
+
+button,
+input,
+textarea {
+  background: none;
+  border: none;
+  color: inherit;
+  font: inherit;
+  padding: 0;
+}
+
+button {
+  cursor: pointer;
+}
+
+ol,
+ul {
+  list-style: none;
+}
+
+blockquote,
+q {
+  quotes: none;
+}
+
+blockquote::before,
+blockquote::after,
+q::before,
+q::after {
+  content: "";
+  content: none;
+}
+
+table {
+  border-collapse: collapse;
+  border-spacing: 0;
+}

package/styles/helpers/_breakpoints.scss

@@ -0,0 +1,76 @@
+@use "sass:map";
+@use "sass:math";
+
+/*=============================================
+=  Viewport Tokens                            =
+=============================================*/
+
+$xs_start: 320px;
+$xs_end: 500px;
+$s_start: 501px;
+$s_end: 749px;
+$m_start: 750px;
+$m_end: 1024px;
+$l_start: 1025px;
+$xl_start: 1280px;
+$xxl_start: 1440px;
+$plus_start: 1600px;
+$plusx_start: 1920px;
+$plusxx_start: 2880px;
+
+/*=============================================
+=  Breakpoint Aliases                         =
+=============================================*/
+
+$breakpoints: (
+  xs: "screen and (max-width: #{$xs_end})",
+  s: "screen and (max-width: #{$s_end})",
+  "s-up": "screen and (min-width: #{$s_start})",
+  m: "screen and (max-width: #{$m_end})",
+  "m-up": "screen and (min-width: #{$m_start})",
+  "l-up": "screen and (min-width: #{$l_start})",
+  "xl-up": "screen and (min-width: #{$xl_start})",
+  "xxl-up": "screen and (min-width: #{$xxl_start})",
+  "plus-up": "screen and (min-width: #{$plus_start})",
+  "plusx-up": "screen and (min-width: #{$plusx_start})",
+  "plusxx-up": "screen and (min-width: #{$plusxx_start})",
+  landscape: "(orientation: landscape) and (min-aspect-ratio: 1920/1079)",
+);
+
+/*=============================================
+=  Media Query Mixin                          =
+=============================================*/
+/**
+ * Media query helper.
+ *
+ * Purpose:
+ *   Provides a single, central API for responsive rules.
+ *   Avoids scattering raw media queries throughout the codebase.
+ *
+ * Params:
+ *   $mq - Breakpoint alias key from $breakpoints.
+ *
+ * Usage:
+ *   .title {
+ *     font-size: 2rem;
+ *
+ *     @include media(xs) {
+ *       font-size: 1.6rem;
+ *     }
+ *
+ *     @include media("m-up") {
+ *       font-size: 2.4rem;
+ *     }
+ *   }
+ */
+@mixin media($mq) {
+  $condition: map.get($breakpoints, $mq);
+
+  @if $condition {
+    @media #{$condition} {
+      @content;
+    }
+  } @else {
+    @warn "Oops! Breakpoint `#{$mq}` does not exist in \$breakpoints.";
+  }
+}

package/styles/helpers/_line-height.scss

@@ -0,0 +1,92 @@
+@use "sass:math";
+
+/*=============================================
+=  Typography / Layout Helpers                =
+=============================================*/
+
+/**
+ * Line-height crop helper
+ *
+ * Purpose:
+ *   Visually “crops” the extra space above text caused by line-height,
+ *   so headings and large text blocks can align better to tight grids.
+ *
+ * Params:
+ *   $line-height    - The line-height value used on the element (unitless).
+ *   $capital-letter - Approximate cap-height of the font (unitless, default: 1).
+ *
+ * Usage:
+ *   .heading {
+ *     line-height: 1.2;
+ *     @include lhCrop(1.2, 0.9);
+ *   }
+ */
+@mixin lhCrop($line-height, $capital-letter: 1) {
+  &::before {
+    content: "";
+    display: block;
+    height: 0;
+    width: 0;
+    margin-top: calc((#{$capital-letter} - #{$line-height}) * 0.5em);
+  }
+}
+
+/**
+ * Desktop column width helper
+ *
+ * Purpose:
+ *   Returns a responsive width in vw based on a fixed column grid on desktop.
+ *   Uses a base column width ($colwidth) relative to $desktop width.
+ *
+ * Params:
+ *   $nr - Number of columns to span.
+ *
+ * Requirements:
+ *   - $desktop must be defined as the desktop viewport width in px.
+ *
+ * Usage:
+ *   .col-3 {
+ *     width: dCol(3);
+ *   }
+ */
+@function dCol($nr) {
+  $colwidth: 80;
+  $cols: math.div($colwidth * 100, $desktop);
+  $one: ($cols * $nr);
+  @return $one + vw;
+}
+
+/**
+ * Mobile column width helper
+ *
+ * Purpose:
+ *   Returns a responsive width in vw based on a 9-column grid on mobile,
+ *   accounting for left/right gutters.
+ *
+ * Params:
+ *   $nr - Number of columns to span.
+ *
+ * Logic:
+ *   - $colnr: number of columns (default 9).
+ *   - $gutter: side gutter in px.
+ *   - $offset: gutter converted to vw relative to $mobile.
+ *   - Total usable width = 100vw minus both side offsets.
+ *   - Column width = usable width / $colnr.
+ *
+ * Requirements:
+ *   - $mobile must be defined as the mobile viewport width in px.
+ *
+ * Usage:
+ *   .m-col-4 {
+ *     width: mCol(4);
+ *   }
+ */
+@function mCol($nr) {
+  $colnr: 9;
+  $gutter: 15;
+  $offset: math.div($gutter * 100, $mobile);
+  $vw: 100 - ($offset * 2);
+  $cols: math.div($vw, $colnr);
+  $one: ($cols * $nr);
+  @return $one + vw;
+}

package/styles/helpers/_viewport-unit.scss

@@ -0,0 +1,17 @@
+@use "sass:math";
+
+/*=============================================
+=  Viewport Unit Helpers                      =
+=============================================*/
+
+@function vh($vh) {
+  @return calc(var(--vh, 1vh) * #{$vh});
+}
+
+@function tovw($size, $device) {
+  @return math.div($size * 100, $device) + vw;
+}
+
+@function tovh($size, $height) {
+  @return math.div($size * 100, $height) + vh;
+}

package/styles/helpers/index.scss

@@ -0,0 +1,3 @@
+@import "breakpoints.scss";
+@import "line-height.scss";
+@import "viewport-unit.scss";

package/styles/index.scss

@@ -0,0 +1,4 @@
+@charset "UTF-8";
+
+@import "base/reset.scss";
+@import "helpers/index.scss";

package/index.js

@@ -1,30 +0,0 @@
-/**
- * Legacy setup functions for Stellar Kit.
- * These were previously part of Application.js but have been moved out
- */
-
-import { Mouse, Resize, Raf, Scroll } from "./events"
-import kitStore from "./kitStore"
-import { sniffer } from "./utils"
-
-export function setupKit({ isSmooth = sniffer.isDesktop, isLocked = false } = {}) {
-  kitStore.flags.isSmooth = isSmooth
-  kitStore.flags.isLocked = isLocked
-
-  kitStore.resize = new Resize()
-  kitStore.raf = new Raf()
-  kitStore.scroll = new Scroll({ isSmooth })
-  kitStore.mouse = new Mouse()
-}
-
-export function setSizes(d = kitStore.sizes.d, m = kitStore.sizes.m) {
-  // update store if values are provided
-  kitStore.sizes.d = d
-  kitStore.sizes.m = m
-
-  // set css vars
-  document.documentElement.style.setProperty("--desktop", d)
-  document.documentElement.style.setProperty("--mobile", m)
-}
-
-export { kitStore }