@react-kino/core 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (6) hide show
  1. package/LICENSE +21 -0
  2. package/dist/index.d.mts +79 -0
  3. package/dist/index.d.ts +79 -0
  4. package/dist/index.js +1 -0
  5. package/dist/index.mjs +1 -0
  6. package/package.json +43 -0
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Bilal Tahir
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/dist/index.d.mts ADDED
@@ -0,0 +1,79 @@
1
+ /** Easing function signature: takes t in [0,1], returns value in [0,1] */
2
+ type EasingFn = (t: number) => number;
3
+ /** Configuration for a pinned scene */
4
+ interface SceneConfig {
5
+ /** scroll distance this scene spans in pixels */
6
+ duration: number;
7
+ /** offset from top of the spacer element */
8
+ offsetTop: number;
9
+ }
10
+ /** Progress data emitted by the scroll tracker */
11
+ interface ProgressData {
12
+ /** raw scroll Y position */
13
+ scrollY: number;
14
+ /** viewport height */
15
+ viewportHeight: number;
16
+ /** total document scroll height */
17
+ scrollHeight: number;
18
+ /** page-level progress 0->1 */
19
+ progress: number;
20
+ }
21
+ /** Subscriber callback for scroll updates */
22
+ type ScrollSubscriber = (data: ProgressData) => void;
23
+
24
+ /** Clamps a value between min and max (inclusive) */
25
+ declare function clamp(value: number, min: number, max: number): number;
26
+
27
+ /** Linear interpolation between a and b by factor t */
28
+ declare function lerp(a: number, b: number, t: number): number;
29
+
30
+ declare function linear(t: number): number;
31
+ declare function easeIn(t: number): number;
32
+ declare function easeOut(t: number): number;
33
+ declare function easeInOut(t: number): number;
34
+ declare function easeInCubic(t: number): number;
35
+ declare function easeOutCubic(t: number): number;
36
+ declare function easeInOutCubic(t: number): number;
37
+ declare function easeInQuart(t: number): number;
38
+ declare function easeOutQuart(t: number): number;
39
+ declare function easeInOutQuart(t: number): number;
40
+ declare const EASINGS: Record<string, EasingFn>;
41
+
42
+ declare class ScrollTracker {
43
+ private subscribers;
44
+ private rafId;
45
+ private lastScrollY;
46
+ private isRunning;
47
+ private onScroll;
48
+ constructor();
49
+ /** Subscribe to scroll updates. Returns unsubscribe function. */
50
+ subscribe(fn: ScrollSubscriber): () => void;
51
+ /** Start listening. Call this on client only (in useEffect). */
52
+ start(): void;
53
+ /** Stop listening and clean up. */
54
+ stop(): void;
55
+ private tick;
56
+ private emit;
57
+ }
58
+
59
+ /**
60
+ * Calculate scroll progress through a pinned scene (0->1).
61
+ * @param scrollY - current window.scrollY
62
+ * @param offsetTop - the spacer element's offsetTop from document top
63
+ * @param duration - the spacer's height in pixels (scroll distance of scene)
64
+ * @returns progress clamped to [0, 1]
65
+ */
66
+ declare function calcSceneProgress(scrollY: number, offsetTop: number, duration: number): number;
67
+ /**
68
+ * Parse a CSS-like duration string into pixels.
69
+ * Supports: "200vh", "300px", "2.5" (treated as vh)
70
+ * @param duration - string like "200vh" or "1500px"
71
+ * @param viewportHeight - window.innerHeight in pixels
72
+ */
73
+ declare function parseDuration(duration: string, viewportHeight: number): number;
74
+ /**
75
+ * Determine if a scene is currently active (in progress).
76
+ */
77
+ declare function isSceneActive(scrollY: number, offsetTop: number, duration: number): boolean;
78
+
79
+ export { EASINGS, type EasingFn, type ProgressData, type SceneConfig, type ScrollSubscriber, ScrollTracker, calcSceneProgress, clamp, easeIn, easeInCubic, easeInOut, easeInOutCubic, easeInOutQuart, easeInQuart, easeOut, easeOutCubic, easeOutQuart, isSceneActive, lerp, linear, parseDuration };
package/dist/index.d.ts ADDED
@@ -0,0 +1,79 @@
1
+ /** Easing function signature: takes t in [0,1], returns value in [0,1] */
2
+ type EasingFn = (t: number) => number;
3
+ /** Configuration for a pinned scene */
4
+ interface SceneConfig {
5
+ /** scroll distance this scene spans in pixels */
6
+ duration: number;
7
+ /** offset from top of the spacer element */
8
+ offsetTop: number;
9
+ }
10
+ /** Progress data emitted by the scroll tracker */
11
+ interface ProgressData {
12
+ /** raw scroll Y position */
13
+ scrollY: number;
14
+ /** viewport height */
15
+ viewportHeight: number;
16
+ /** total document scroll height */
17
+ scrollHeight: number;
18
+ /** page-level progress 0->1 */
19
+ progress: number;
20
+ }
21
+ /** Subscriber callback for scroll updates */
22
+ type ScrollSubscriber = (data: ProgressData) => void;
23
+
24
+ /** Clamps a value between min and max (inclusive) */
25
+ declare function clamp(value: number, min: number, max: number): number;
26
+
27
+ /** Linear interpolation between a and b by factor t */
28
+ declare function lerp(a: number, b: number, t: number): number;
29
+
30
+ declare function linear(t: number): number;
31
+ declare function easeIn(t: number): number;
32
+ declare function easeOut(t: number): number;
33
+ declare function easeInOut(t: number): number;
34
+ declare function easeInCubic(t: number): number;
35
+ declare function easeOutCubic(t: number): number;
36
+ declare function easeInOutCubic(t: number): number;
37
+ declare function easeInQuart(t: number): number;
38
+ declare function easeOutQuart(t: number): number;
39
+ declare function easeInOutQuart(t: number): number;
40
+ declare const EASINGS: Record<string, EasingFn>;
41
+
42
+ declare class ScrollTracker {
43
+ private subscribers;
44
+ private rafId;
45
+ private lastScrollY;
46
+ private isRunning;
47
+ private onScroll;
48
+ constructor();
49
+ /** Subscribe to scroll updates. Returns unsubscribe function. */
50
+ subscribe(fn: ScrollSubscriber): () => void;
51
+ /** Start listening. Call this on client only (in useEffect). */
52
+ start(): void;
53
+ /** Stop listening and clean up. */
54
+ stop(): void;
55
+ private tick;
56
+ private emit;
57
+ }
58
+
59
+ /**
60
+ * Calculate scroll progress through a pinned scene (0->1).
61
+ * @param scrollY - current window.scrollY
62
+ * @param offsetTop - the spacer element's offsetTop from document top
63
+ * @param duration - the spacer's height in pixels (scroll distance of scene)
64
+ * @returns progress clamped to [0, 1]
65
+ */
66
+ declare function calcSceneProgress(scrollY: number, offsetTop: number, duration: number): number;
67
+ /**
68
+ * Parse a CSS-like duration string into pixels.
69
+ * Supports: "200vh", "300px", "2.5" (treated as vh)
70
+ * @param duration - string like "200vh" or "1500px"
71
+ * @param viewportHeight - window.innerHeight in pixels
72
+ */
73
+ declare function parseDuration(duration: string, viewportHeight: number): number;
74
+ /**
75
+ * Determine if a scene is currently active (in progress).
76
+ */
77
+ declare function isSceneActive(scrollY: number, offsetTop: number, duration: number): boolean;
78
+
79
+ export { EASINGS, type EasingFn, type ProgressData, type SceneConfig, type ScrollSubscriber, ScrollTracker, calcSceneProgress, clamp, easeIn, easeInCubic, easeInOut, easeInOutCubic, easeInOutQuart, easeInQuart, easeOut, easeOutCubic, easeOutQuart, isSceneActive, lerp, linear, parseDuration };
package/dist/index.js ADDED
@@ -0,0 +1 @@
1
+ 'use strict';function i(r,e,n){return Math.min(Math.max(r,e),n)}function I(r,e,n){return r+(e-r)*n}function m(r){return r}function l(r){return r*r}function b(r){return r*(2-r)}function p(r){return r<.5?2*r*r:-1+(4-2*r)*r}function f(r){return r*r*r}function h(r){let e=r-1;return e*e*e+1}function d(r){return r<.5?4*r*r*r:1-Math.pow(-2*r+2,3)/2}function x(r){return r*r*r*r}function v(r){let e=r-1;return 1-e*e*e*e}function S(r){return r<.5?8*r*r*r*r:1-Math.pow(-2*r+2,4)/2}var E={linear:m,"ease-in":l,"ease-out":b,"ease-in-out":p,"ease-in-cubic":f,"ease-out-cubic":h,"ease-in-out-cubic":d,"ease-in-quart":x,"ease-out-quart":v,"ease-in-out-quart":S};var o=class{constructor(){this.subscribers=new Set;this.rafId=null;this.lastScrollY=-1;this.isRunning=false;this.onScroll=()=>{this.rafId===null&&(this.rafId=requestAnimationFrame(()=>this.tick()));};}subscribe(e){return this.subscribers.add(e),()=>{this.subscribers.delete(e);}}start(){this.isRunning||(this.isRunning=true,window.addEventListener("scroll",this.onScroll,{passive:true}),this.emit());}stop(){this.isRunning&&(this.isRunning=false,window.removeEventListener("scroll",this.onScroll),this.rafId!==null&&(cancelAnimationFrame(this.rafId),this.rafId=null));}tick(){this.rafId=null;let e=window.scrollY;e!==this.lastScrollY&&(this.lastScrollY=e,this.emit());}emit(){let e=window.scrollY,n=window.innerHeight,t=document.documentElement.scrollHeight,u=t-n,s=u>0?i(e/u,0,1):0,a={scrollY:e,viewportHeight:n,scrollHeight:t,progress:s};this.subscribers.forEach(c=>c(a));}};function q(r,e,n){return n<=0?0:i((r-e)/n,0,1)}function y(r,e){let n=r.trim();if(n.endsWith("px"))return parseFloat(n);if(n.endsWith("vh"))return parseFloat(n)/100*e;let t=parseFloat(n);return isNaN(t)?0:t/100*e}function A(r,e,n){return r>=e&&r<=e+n}exports.EASINGS=E;exports.ScrollTracker=o;exports.calcSceneProgress=q;exports.clamp=i;exports.easeIn=l;exports.easeInCubic=f;exports.easeInOut=p;exports.easeInOutCubic=d;exports.easeInOutQuart=S;exports.easeInQuart=x;exports.easeOut=b;exports.easeOutCubic=h;exports.easeOutQuart=v;exports.isSceneActive=A;exports.lerp=I;exports.linear=m;exports.parseDuration=y;
package/dist/index.mjs ADDED
@@ -0,0 +1 @@
1
+ function i(r,e,n){return Math.min(Math.max(r,e),n)}function I(r,e,n){return r+(e-r)*n}function m(r){return r}function l(r){return r*r}function b(r){return r*(2-r)}function p(r){return r<.5?2*r*r:-1+(4-2*r)*r}function f(r){return r*r*r}function h(r){let e=r-1;return e*e*e+1}function d(r){return r<.5?4*r*r*r:1-Math.pow(-2*r+2,3)/2}function x(r){return r*r*r*r}function v(r){let e=r-1;return 1-e*e*e*e}function S(r){return r<.5?8*r*r*r*r:1-Math.pow(-2*r+2,4)/2}var E={linear:m,"ease-in":l,"ease-out":b,"ease-in-out":p,"ease-in-cubic":f,"ease-out-cubic":h,"ease-in-out-cubic":d,"ease-in-quart":x,"ease-out-quart":v,"ease-in-out-quart":S};var o=class{constructor(){this.subscribers=new Set;this.rafId=null;this.lastScrollY=-1;this.isRunning=false;this.onScroll=()=>{this.rafId===null&&(this.rafId=requestAnimationFrame(()=>this.tick()));};}subscribe(e){return this.subscribers.add(e),()=>{this.subscribers.delete(e);}}start(){this.isRunning||(this.isRunning=true,window.addEventListener("scroll",this.onScroll,{passive:true}),this.emit());}stop(){this.isRunning&&(this.isRunning=false,window.removeEventListener("scroll",this.onScroll),this.rafId!==null&&(cancelAnimationFrame(this.rafId),this.rafId=null));}tick(){this.rafId=null;let e=window.scrollY;e!==this.lastScrollY&&(this.lastScrollY=e,this.emit());}emit(){let e=window.scrollY,n=window.innerHeight,t=document.documentElement.scrollHeight,u=t-n,s=u>0?i(e/u,0,1):0,a={scrollY:e,viewportHeight:n,scrollHeight:t,progress:s};this.subscribers.forEach(c=>c(a));}};function q(r,e,n){return n<=0?0:i((r-e)/n,0,1)}function y(r,e){let n=r.trim();if(n.endsWith("px"))return parseFloat(n);if(n.endsWith("vh"))return parseFloat(n)/100*e;let t=parseFloat(n);return isNaN(t)?0:t/100*e}function A(r,e,n){return r>=e&&r<=e+n}export{E as EASINGS,o as ScrollTracker,q as calcSceneProgress,i as clamp,l as easeIn,f as easeInCubic,p as easeInOut,d as easeInOutCubic,S as easeInOutQuart,x as easeInQuart,b as easeOut,h as easeOutCubic,v as easeOutQuart,A as isSceneActive,I as lerp,m as linear,y as parseDuration};
package/package.json ADDED
@@ -0,0 +1,43 @@
1
+ {
2
+ "name": "@react-kino/core",
3
+ "version": "0.1.0",
4
+ "description": "Framework-agnostic scroll engine powering react-kino",
5
+ "main": "./dist/index.js",
6
+ "module": "./dist/index.mjs",
7
+ "types": "./dist/index.d.ts",
8
+ "exports": {
9
+ ".": {
10
+ "types": "./dist/index.d.ts",
11
+ "import": "./dist/index.mjs",
12
+ "require": "./dist/index.js"
13
+ }
14
+ },
15
+ "files": [
16
+ "dist"
17
+ ],
18
+ "sideEffects": false,
19
+ "devDependencies": {
20
+ "tsup": "^8",
21
+ "typescript": "^5",
22
+ "vitest": "^4"
23
+ },
24
+ "author": "Bilal Tahir",
25
+ "license": "MIT",
26
+ "repository": {
27
+ "type": "git",
28
+ "url": "https://github.com/btahir/react-kino.git",
29
+ "directory": "packages/core"
30
+ },
31
+ "homepage": "https://github.com/btahir/react-kino#readme",
32
+ "bugs": {
33
+ "url": "https://github.com/btahir/react-kino/issues"
34
+ },
35
+ "scripts": {
36
+ "build": "tsup",
37
+ "dev": "tsup --watch",
38
+ "clean": "rm -rf dist",
39
+ "typecheck": "tsc --noEmit",
40
+ "test": "vitest run",
41
+ "lint": "tsc --noEmit"
42
+ }
43
+ }