situs-kit 0.1.8 → 0.1.9

package/README.md

@@ -8,125 +8,11 @@ A zero-dependency creative developer toolkit
 npm install situs-kit
 ```
 
-## SplitText
+## Modules
 
-Split text into characters, words, and lines while preserving inline HTML elements like `<a>`, `<em>`, `<strong>`, and `<u>`.
-
-### Basic Usage
-
-```ts
-import { SplitText } from "situs-kit/split-text";
-
-const split = new SplitText("#my-text", {
-  type: ["chars", "words", "lines"],
-});
-
-split.chars;  // HTMLElement[]
-split.words;  // HTMLElement[]
-split.lines;  // HTMLElement[]
-```
-
-### Options
-
-```ts
-new SplitText(element, {
-  type: ["chars", "words", "lines"], // which levels to split
-  tag: "span",                        // wrapper element tag
-  mask: ["chars", "lines"],            // which levels to mask
-  resize: true,                       // auto-reflow lines on resize
-  style: {
-    chars: { color: "red" },
-    words: {},
-    lines: {},
-    mask: {},
-  },
-  class: {
-    chars: "my-char",
-    words: "my-word",
-    lines: "my-line",
-    mask: "my-mask",
-  },
-});
-```
-
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `type` | `string \| string[]` | `["chars", "words", "lines"]` | Split granularity |
-| `tag` | `string` | `"span"` | Wrapper element tag |
-| `mask` | `boolean \| SplitType[]` | `false` | Create overflow-hidden wrappers per split type |
-| `resize` | `boolean` | `true` | Auto-reflow lines on window resize |
-| `style` | `object` | — | Inline styles per split type |
-| `class` | `object` | — | CSS classes per split type |
-
-### Properties
-
-| Property | Type | Description |
-|----------|------|-------------|
-| `dom` | `HTMLElement` | The original element |
-| `chars` | `HTMLElement[]` | Character elements |
-| `words` | `HTMLElement[]` | Word elements |
-| `lines` | `HTMLElement[]` | Line elements |
-| `masks` | `{ chars, words, lines }` | Mask wrapper elements |
-
-### Methods
-
-#### `reflow()`
-
-Recalculate line groupings without re-splitting. Called automatically on resize.
-
-```ts
-split.reflow();
-```
-
-#### `revert()`
-
-Restore the element to its original HTML.
-
-```ts
-split.revert();
-```
-
-#### `destroy()`
-
-Remove resize observers and event listeners.
-
-```ts
-split.destroy();
-```
-
-### Styling with CSS
-
-Split elements have data attributes for easy targeting:
-
-```css
-[data-char] { display: inline-block; }
-[data-word] { display: inline-block; }
-[data-line] { display: block; }
-```
-
-### HTML Preservation
-
-Inline elements like `<a>`, `<em>`, `<strong>`, `<u>`, `<i>`, and `<b>` are preserved and cloned around split elements. Opaque elements like `<svg>`, `<img>`, and `<br>` are treated as single units.
-
-```html
-<!-- Input -->
-<p id="text">Hello <strong>world</strong></p>
-
-<!-- After split, <strong> wraps are preserved -->
-```
-
-### Masking
-
-Masks wrap split elements in `overflow: hidden` containers, useful for reveal animations. Like `type`, you specify which split levels to mask:
-
-```ts
-const split = new SplitText("#text", {
-  type: ["words", "lines"],
-  mask: ["lines"],           // only mask lines
-});
-
-split.masks.lines;  // HTMLElement[] - overflow:hidden wrappers
-```
+- [SplitText](./docs/split-text.md) — Split text into characters, words, and lines with HTML preservation
+- [SmoothScroll](./docs/smooth-scroll.md) — Lerp-based smooth scroll with native touch/mobile support
+- [Ticker](./docs/ticker.md) — Shared RAF loop manager for frame-synced animations
 
 ## License
 

package/dist/chunk-0t3a7kj5.js

@@ -0,0 +1,2 @@
+function R(j,k){return typeof globalThis.getComputedStyle==="function"?globalThis.getComputedStyle(j,k??null):null}var K=["whe","mou","tou","poi"];function J(j){return K.includes(j.slice(0,3))}function L(j,k){if(!k)return J(j)?{passive:!1}:!1;if(typeof k==="object"&&k.passive===void 0&&J(j))return{...k,passive:!1};return k}function M(j){if(!j)return!1;if(typeof j==="object")return j.capture??!1;return j}function V(j,k,w,B,D){let E=k==="a"?"addEventListener":"removeEventListener",G=k==="a"?L(w,D):M(D);if(typeof j==="string"){let H=Q(j);for(let z=0;z<H.length;z++)H[z][E](w,B,G)}else j[E](w,B,G)}function W(j,k){let w=k??document;return typeof w.querySelector==="function"?w.querySelector(j):null}function Q(j,k){let w=k??document;return typeof w.querySelectorAll==="function"?Array.from(w.querySelectorAll(j)):[]}
+export{R as c,V as d,W as e,Q as f};

package/dist/chunk-qjsknche.js

@@ -0,0 +1,2 @@
+var J=0,G=0;function N(){return G}var v=[],x=0,D=!0,y=0,E=!1;function H(q){if(D){let j=q-y;y=q,G=j/16.666666666666668;for(let B=x-1;B>=0;B--){let A=v[B];if(!A)continue;A.sT||=q;let I=q-A.sT;A.cb(I)}}requestAnimationFrame(H)}function K(){if(document.hidden)D=!1;else{let q=performance.now()-y;y=performance.now();for(let j=x-1;j>=0;j--)v[j].sT+=q;D=!0}}function L(){if(E)return;if(E=!0,y=performance.now(),typeof document<"u")document.addEventListener("visibilitychange",K);requestAnimationFrame(H)}var M={add(q){L();let j=J++;return v.push({id:j,cb:q,sT:0}),x++,()=>M.remove(q)},remove(q){for(let j=x-1;j>=0;j--)if(v[j].cb===q)v.splice(j,1),x--}};
+export{N as g,M as h};

package/dist/chunk-se6yyp59.js

@@ -0,0 +1,2 @@
+import{c as C,e as c,f as w}from"./chunk-0t3a7kj5.js";var I=1,x=2,K=4,_="inline-block",h="nowrap",f="baseline",u="0px",E="block",m="maskChar",g="maskWord",n="maskLine",o=/^\s+$/,l=/(\s+)/,t=",div,span,svg,img,br,hr,canvas,video,audio,iframe,input,textarea,select,button,picture,figure,",p={u:"underline",ins:"underline",s:"line-through",strike:"line-through",del:"line-through"};class a{dom;chars;words;lines;masks;_n;_k;_g;_j;_f=[];_o=new Map;_i=null;_h=0;_l=!1;_c="";_d;_e;_b;_a=null;constructor(z,F={}){let J;if(typeof z==="string"){let $=w(z);if($.length>1)J=$;else{let Q=$[0]??c(z);if(!Q)throw Error("SplitText: element not found");J=Q}}else J=z;if(Array.isArray(J)||typeof J==="object"&&J!==null&&"length"in J&&typeof J.item==="function"){let $=Array.from(J);if($.length===0)throw Error("SplitText: empty element array");this._a=$.map((Q)=>new a(Q,F)),this.dom=$,this.chars=this._a.flatMap((Q)=>Q.chars),this.words=this._a.flatMap((Q)=>Q.words),this.lines=this._a.flatMap((Q)=>Q.lines),this.masks={chars:this._a.flatMap((Q)=>Q.masks.chars),words:this._a.flatMap((Q)=>Q.masks.words),lines:this._a.flatMap((Q)=>Q.masks.lines)},this._n="",this._k=0,this._g=0,this._j="";return}let U=J;this._b=U,this.dom=U,this._n=U.innerHTML,this.chars=[],this.words=[],this.lines=[],this.masks={chars:[],words:[],lines:[]};let G=F.type?Array.isArray(F.type)?F.type:[F.type]:["chars","words","lines"],D=0;for(let $ of G)if($==="chars")D|=I;else if($==="words")D|=x;else if($==="lines")D|=K;this._k=D,this._j=F.tag??"span";let Z=0;if(F.mask===!0)Z=D;else if(Array.isArray(F.mask)){for(let $ of F.mask)if($==="chars")Z|=I;else if($==="words")Z|=x;else if($==="lines")Z|=K}if(this._g=Z,this._d=F.style,this._e=F.class,this._w(),(F.resize??!0)&&D&K)this._x()}_p(z,F){let J=document.createElement(this._j);if(z)J.dataset[z]="";if(J.style.display=_,F!==void 0)J.textContent=F;return J}_s(z,F){let J=document.createElement(this._j);if(J.dataset[F]="",J.style.overflow="hidden",J.style.display=z,this._d?.mask)Object.assign(J.style,this._d.mask);if(this._e?.mask)J.classList.add(this._e.mask);return J}_r(z,F,J,q,U){if(this._g&F){let G=this._s(J,q);return G.appendChild(z),U.push(G),G}return z}_m(z,F,J,q){if(J){let{outer:U,inner:G}=J();if(G.appendChild(F),q)this._o.set(q,U);z.appendChild(U)}else z.appendChild(F)}_q(z,F,J){if(z.style.textDecoration=F,J)z.style.textDecorationColor=J}_w(){this._l=!0;let z=this._b,F=C(z),J=F?parseFloat(F.letterSpacing)||0:0;if(this._c=F?F.textIndent:"",this._c&&this._c!==u)z.style.textIndent="0";let q=this._k,U=!!(q&I),G=!!(q&x),D=!!(q&K),Z=G||D,$=!!(this._g&I),Q=new Map,H=(M)=>{for(let N of Array.from(M.childNodes))if(N.nodeType===1){let O=N.tagName.toLowerCase();if(p[O]){let v=C(N)?.textDecorationColor;if(v)Q.set(N,v)}H(N)}};H(z);let Y=Array.from(z.childNodes),T=document.createDocumentFragment();z.replaceChildren();let k=(M,N,O,v)=>{if(M.nodeType===3){let X=(M.textContent??"").split(l);for(let j of X){if(!j)continue;if(o.test(j)){T.appendChild(document.createTextNode(j));continue}let V=Z?this._p(G?"word":""):null;if(V){if(V.style.whiteSpace=h,O&&!U)this._q(V,O,v)}if(U){let b=[...j],d=this.chars.length;for(let P=0;P<b.length;P++){let R=this._p("char",b[P]);if(J&&P<b.length-1)R.style.marginRight=`${J}px`;if(O)this._q(R,O,v);if(this.chars.push(R),this._d?.chars)Object.assign(R.style,this._d.chars);if(this._e?.chars)R.classList.add(this._e.chars);let y=$?this._r(R,I,_,m,this.masks.chars):R;if(V)V.appendChild(y)}if(!V){let P=N?N():null,R=P?P.inner:T;for(let y=d;y<this.chars.length;y++){let S=this.chars[y];R.appendChild($&&S.parentElement?.dataset?.[m]!==void 0?S.parentElement:S)}if(P)T.appendChild(P.outer)}}else if(V){if(V.textContent=j,J)V.style.letterSpacing=`${J}px`}if(V){if(G){if(this.words.push(V),this._d?.words)Object.assign(V.style,this._d.words);if(this._e?.words)V.classList.add(this._e.words)}this._f.push(V);let b=this._g&x?this._r(V,x,_,g,this.masks.words):V;this._m(T,b,N,V)}else if(!U)this._m(T,document.createTextNode(j),N)}return}if(M.nodeType!==1)return;let B=M,A=B.tagName.toLowerCase();if(t.includes(","+A+",")){let X=B.cloneNode(!0);if(O)this._q(X,O,v);let j=C(B)?.verticalAlign;if(j&&j!==f)X.style.verticalAlign=j;if(Z){let V=this._p(G?"word":"");if(V.style.whiteSpace=h,j&&j!==f)V.style.verticalAlign=j;if(V.appendChild(X),G){if(this.words.push(V),this._d?.words)Object.assign(V.style,this._d.words);if(this._e?.words)V.classList.add(this._e.words)}this._f.push(V);let b=this._g&x?this._r(V,x,_,g,this.masks.words):V;this._m(T,b,N,V)}else this._m(T,X,N);return}let r=()=>{let X=B.cloneNode(!1);if(N){let{outer:j,inner:V}=N();return V.appendChild(X),{outer:j,inner:X}}return{outer:X,inner:X}},L=p[A],i=L?O?`${O} ${L}`:L:O,s=L?Q.get(B)||v:v;for(let X of Array.from(B.childNodes))k(X,r,i,s)};for(let M of Y)k(M,null,"","");z.appendChild(T);let W=!!(this._c&&this._c!==u);if(D)this._y(W);else if(W){let M=G?this.words[0]:U?this.chars[0]:null;if(M)M.style.marginLeft=this._c,z.style.textIndent="0"}this._l=!1}_y(z){if(z&&this._f[0])this._f[0].style.marginLeft=this._c;this._t();let F=[];if(typeof document.fonts?.status==="string"&&document.fonts.status!=="loaded")F.push(document.fonts.ready);let J=this._b.querySelectorAll("img");for(let q=0;q<J.length;q++){let U=J[q];if(!U.complete)F.push(new Promise((G)=>{U.addEventListener("load",G,{once:!0}),U.addEventListener("error",G,{once:!0})}))}if(F.length){let q=this._b.offsetHeight;Promise.all(F).then(()=>{if(this._b.offsetHeight!==q)this.reflow()})}}_u(z){return this._o.get(z)??z}_t(){let z=this._f;if(!z.length)return;let F=z[0].offsetTop,J=F+z[0].offsetHeight,q=[],U=[];for(let $ of z){let Q=$.offsetTop,H=Q+$.offsetHeight;if(Q<J&&H>F)F=Math.min(F,Q),J=Math.max(J,H);else U.push(q),q=[],F=Q,J=H;q.push($)}if(q.length)U.push(q);let G=!!(this._c&&this._c!==u);if(G&&z[0])z[0].style.marginLeft="";let D=!!(this._g&K),Z=document.createDocumentFragment();for(let $=0;$<U.length;$++){let Q=U[$],H=document.createElement(this._j);if(H.dataset.line="",H.style.display=E,$===0&&G)H.style.paddingLeft=this._c;for(let Y=0;Y<Q.length;Y++){if(Y>0)H.appendChild(document.createTextNode(" "));H.appendChild(this._u(Q[Y]))}if(this.lines.push(H),this._d?.lines)Object.assign(H.style,this._d.lines);if(this._e?.lines)H.classList.add(this._e.lines);if(D){let Y=this._s(E,n);Y.appendChild(H),this.masks.lines.push(Y),Z.appendChild(Y)}else Z.appendChild(H)}this._b.replaceChildren(Z)}_x(){let z=this._b.offsetParent?this._b.offsetParent.offsetWidth:window.innerWidth,F=()=>{if(this._l)return;let q=this._b.offsetParent,U=q?q.offsetWidth:window.innerWidth;if(U===z)return;if(z=U,this._h)cancelAnimationFrame(this._h);this._h=requestAnimationFrame(()=>this.reflow())};this._i=new ResizeObserver(F);let J=this._b.offsetParent??this._b.parentElement;if(J)this._i.observe(J);else this._i.observe(this._b)}reflow(){if(this._a){this._a.forEach((F)=>F.reflow()),this._v();return}if(!(this._k&K)||this._l)return;let z=document.createDocumentFragment();for(let F=0;F<this._f.length;F++){if(F>0)z.appendChild(document.createTextNode(" "));z.appendChild(this._u(this._f[F]))}if(this._b.replaceChildren(z),this.lines.length=0,this.masks.lines.length=0,this._c&&this._c!==u&&this._f[0])this._f[0].style.marginLeft=this._c;this._t()}revert(){if(this._a){this._a.forEach((z)=>z.revert()),this._v();return}this.destroy(),this._b.innerHTML=this._n,this.chars.length=0,this.words.length=0,this._f.length=0,this._o.clear(),this.lines.length=0,this.masks.chars.length=0,this.masks.words.length=0,this.masks.lines.length=0}destroy(){if(this._a){this._a.forEach((z)=>z.destroy());return}if(this._h)cancelAnimationFrame(this._h),this._h=0;if(this._i)this._i.disconnect(),this._i=null}_v(){if(!this._a)return;this.chars.length=0,this.words.length=0,this.lines.length=0,this.masks.chars.length=0,this.masks.words.length=0,this.masks.lines.length=0;for(let z of this._a)this.chars.push(...z.chars),this.words.push(...z.words),this.lines.push(...z.lines),this.masks.chars.push(...z.masks.chars),this.masks.words.push(...z.masks.words),this.masks.lines.push(...z.masks.lines)}}
+export{a};

package/dist/chunk-xcfcqftx.js

@@ -0,0 +1,2 @@
+import{d as N,e as P}from"./chunk-0t3a7kj5.js";import{g as Z,h as Q}from"./chunk-qjsknche.js";function O(j,z,B){return Math.min(Math.max(j,z),B)}function $(j,z,B){return j+(z-j)*B}function X(j,z,B){let G=z-j;return G===0?0:O((B-j)/G,0,1)}function Y(j,z,B,G){let H=1-Math.exp(-B*G);return $(j,z,H)}var J=0.09;class y{_d;_f;_c;_x;_e;_y;_o=!1;_q=!1;_m=new Map;_a=0;_b=0;_k=0;_l=1;_p=!1;_L={current:0,target:0,velocity:0,direction:1,max:0,scrolling:!1};_g=!1;_w=0;_r=0;_E=0;_h=0;_s=null;_i=J;_j=null;_z;_A;_B;_t;constructor(j={}){let z=j.wrapper??window;this._d=typeof z==="string"?P(z)??window:z,this._f=this._d===window,this._c=(j.direction??"vertical")==="vertical",this._x=j.duration??0,this._e=j.ease??J,this._y=j.prevent??!this._f,this._z=this._H.bind(this),this._A=this._I.bind(this),this._B=this._J.bind(this),this._t=()=>this._K();let B=this._f?this._c?window.scrollY:window.scrollX:this._c?this._d.scrollTop:this._d.scrollLeft;this._a=B,this._b=B,this.start()}get scroll(){let j=this._L;return j.current=this._a,j.target=this._b,j.velocity=this._k,j.direction=this._l,j.max=this._u(),j.scrolling=this._p,j}_u(){if(this._f)return this._c?document.documentElement.scrollHeight-window.innerHeight:document.documentElement.scrollWidth-window.innerWidth;let j=this._d;return this._c?j.scrollHeight-j.clientHeight:j.scrollWidth-j.clientWidth}_v(j){return O(j,0,this._u())}on(j,z){let B=this._m.get(j);if(!B)B=new Set,this._m.set(j,B);B.add(z)}off(j,z){this._m.get(j)?.delete(z)}_D(j){let z=this._m.get(j);if(!z)return;let B=this.scroll;for(let G of z)G(B)}_n(){if(this._q)return;this._q=!0,Q.add(this._t)}_G(){if(!this._q)return;this._q=!1,Q.remove(this._t)}to(j,z={}){let B;if(typeof j==="number")B=j;else{let K=typeof j==="string"?P(j):j;if(!K)return;let M=K.getBoundingClientRect();if(this._f)B=(this._c?M.top:M.left)+this._a;else{let V=this._d.getBoundingClientRect();B=(this._c?M.top-V.top:M.left-V.left)+this._a}}if(B+=z.offset??0,B=this._v(B),z.immediate){this._a=B,this._b=B,this._g=!0,this._C(),this._D("scroll"),this._g=!1,z.onComplete?.();return}this._g=!0,this._n();let G=z.ease??this._e,H=z.duration??this._x;if(typeof G==="number")this._h=0,this._b=B,this._i=G,this._j=z.onComplete??null;else if(H>0)this._w=this._a,this._r=B,this._E=performance.now(),this._h=H,this._i=G,this._s=z.onComplete??null,this._j=null;else this._h=0,this._b=B,this._i=typeof this._e==="number"?this._e:J,this._j=z.onComplete??null}_F(j){let z=this._f?window:this._d;N(z,j,"wheel",this._z),N(z,j,"scroll",this._A,{passive:!0}),N(window,j,"keydown",this._B)}start(){if(this._o)return;this._o=!0,this._F("a")}stop(){if(!this._o)return;this._o=!1,this._F("r"),this._G()}destroy(){this.stop(),this._m.clear()}_H(j){if(j.preventDefault(),this._y)j.stopPropagation();let z=this._c?j.deltaY:j.deltaX;if(j.deltaMode===1)z*=0.833333;else if(j.deltaMode===2)z*=0.555556;this._b=this._v(this._b+z),this._h=0,this._i=typeof this._e==="number"?this._e:J,this._g=!0,this._n(),this._l=z>0?1:-1}_I(){if(this._g)return;let j=this._f?this._c?window.scrollY:window.scrollX:this._c?this._d.scrollTop:this._d.scrollLeft;this._a=j,this._b=j}_J(j){if(!this._f){let G=document.activeElement;if(G!==this._d&&!this._d.contains(G))return}let z=0,B=this._c?this._f?window.innerHeight:this._d.clientHeight:this._f?window.innerWidth:this._d.clientWidth;switch(j.key){case"ArrowDown":z=100;break;case"ArrowUp":z=-100;break;case"ArrowRight":if(!this._c)z=100;break;case"ArrowLeft":if(!this._c)z=-100;break;case" ":z=j.shiftKey?-B:B;break;case"PageDown":z=B;break;case"PageUp":z=-B;break;case"Home":this._b=0,this._h=0,this._i=typeof this._e==="number"?this._e:J,this._g=!0,this._n();return;case"End":this._b=this._u(),this._h=0,this._i=typeof this._e==="number"?this._e:J,this._g=!0,this._n();return;default:return}if(z)j.preventDefault(),this._b=this._v(this._b+z),this._h=0,this._i=typeof this._e==="number"?this._e:J,this._g=!0,this._n(),this._l=z>0?1:-1}_C(){if(this._f)if(this._c)window.scrollTo(0,this._a);else window.scrollTo(this._a,0);else{let j=this._d;if(this._c)j.scrollTop=this._a;else j.scrollLeft=this._a}}_K(){if(!this._o)return;let j=this._a,z=!1;if(this._g){if(this._h>0){let G=performance.now()-this._E,H=X(0,this._h,G),K=this._i(H);if(this._a=this._w+(this._r-this._w)*K,this._b=this._r,H>=1)this._a=this._r,this._h=0,z=!0}else{let G=this._i;if(this._a=Y(this._a,this._b,G,Z()),Math.abs(this._b-this._a)<0.5)this._a=this._b,z=!0}this._C()}this._k=this._a-j;let B=this._p;if(this._p=Math.abs(this._k)>0.01,this._k>0)this._l=1;else if(this._k<0)this._l=-1;if(this._p||B)this._D("scroll");if(z){if(this._g=!1,this._G(),this._s){let G=this._s;this._s=null,G()}if(this._j){let G=this._j;this._j=null,G()}}}}
+export{y as b};

package/dist/dom/index.d.ts

@@ -1,2 +1,75 @@
-/** Shorthand for `getComputedStyle`. Returns `null` when unavailable (e.g. SSR). */
+/**
+ * Shorthand for `getComputedStyle`.
+ * @param el - The element to compute styles for.
+ * @param pseudo - Optional pseudo-element selector (e.g. `"::before"`).
+ * @returns The computed style declaration, or `null` when unavailable (e.g. SSR).
+ */
 export declare function gCS(el: Element, pseudo?: string | null): CSSStyleDeclaration | null;
+/** A scope for DOM queries — defaults to `document` when `null` or `undefined`. */
+type Scope = Document | Element | HTMLElement | null | undefined;
+/**
+ * Shorthand DOM element getters.
+ *
+ * @example
+ * ```ts
+ * Get.i("app");           // document.getElementById("app")
+ * Get.c("card", wrapper); // wrapper.getElementsByClassName("card")
+ * Get.t("img");           // document.getElementsByTagName("img")
+ * ```
+ */
+export declare const Get: {
+    /**
+     * Get an element by its ID.
+     * @param id - The element ID (without `#`).
+     * @param scope - Optional parent scope.
+     */
+    i: (id: string, scope?: Scope) => HTMLElement;
+    /**
+     * Get elements by class name.
+     * @param className - The class name to match.
+     * @param scope - Optional parent scope.
+     */
+    c: (className: string, scope?: Scope) => HTMLElement[];
+    /**
+     * Get elements by tag name.
+     * @param tagName - The HTML tag to match.
+     * @param scope - Optional parent scope.
+     */
+    t: (tagName: string, scope?: Scope) => HTMLElement[] | HTMLCollectionOf<HTMLElement>;
+};
+type ListenerScope = Element | HTMLElement | Document | Window;
+/**
+ * Add or remove event listeners on one or more targets.
+ *
+ * Input events (`wheel`, `mouse*`, `touch*`, `pointer*`) default to
+ * `{ passive: false }` when no options are provided.
+ *
+ * @param target - A CSS selector, element, `document`, or `window`.
+ * @param action - `"a"` to add, `"r"` to remove.
+ * @param type - Event type (e.g. `"click"`, `"wheel"`).
+ * @param handler - The event handler.
+ * @param opts - Optional `AddEventListenerOptions`.
+ *
+ * @example
+ * ```ts
+ * Listen(window, "a", "scroll", onScroll, { passive: true });
+ * Listen(".card", "a", "click", onClick);
+ * Listen(el, "r", "wheel", onWheel);
+ * ```
+ */
+export declare function Listen(target: string | ListenerScope, action: "a" | "r", type: string, handler: EventListenerOrEventListenerObject | ((e: any) => void), opts?: AddEventListenerOptions): void;
+/**
+ * `querySelector` shorthand — returns a single matching element or `null`.
+ * @param selector - A CSS selector string.
+ * @param scope - Optional parent scope (defaults to `document`).
+ * @returns The first matching element, or `null`.
+ */
+export declare function qS<T extends HTMLElement = HTMLElement>(selector: string, scope?: Scope): T | null;
+/**
+ * `querySelectorAll` shorthand — returns an array of matching elements.
+ * @param selector - A CSS selector string.
+ * @param scope - Optional parent scope (defaults to `document`).
+ * @returns An array of matching elements (empty if unavailable).
+ */
+export declare function qSA<T extends HTMLElement = HTMLElement>(selector: string, scope?: Scope): T[];
+export {};

package/dist/index.d.ts

@@ -1 +1,3 @@
 export { SplitText, type SplitTextOptions, type SplitType, } from "./split-text/index.ts";
+export { SmoothScroll, type SmoothScrollOptions, type ScrollToOptions, type ScrollState, } from "./smooth-scroll/index.ts";
+export { Ticker, getDeltaFrame, type TickerCallback } from "./ticker/index.ts";

package/dist/index.js

@@ -1 +1 @@
-import{a as b}from"./chunk-8pnv9yxr.js";export{b as SplitText};
+import{a as t}from"./chunk-se6yyp59.js";import{b as p}from"./chunk-xcfcqftx.js";import"./chunk-0t3a7kj5.js";import{g as e,h as o}from"./chunk-qjsknche.js";export{e as getDeltaFrame,o as Ticker,t as SplitText,p as SmoothScroll};

package/dist/math/index.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Round a number to a given precision.
+ * @param v - The value to round.
+ * @param r - Decimal places (defaults to 2 when omitted).
+ * @returns The rounded value.
+ */
+export declare const round: (v: number, r?: number) => number;
+/**
+ * Clamp a value between a minimum and maximum.
+ * @param value - The value to clamp.
+ * @param min - Lower bound.
+ * @param max - Upper bound.
+ * @returns The clamped value.
+ */
+export declare function clamp(value: number, min: number, max: number): number;
+/**
+ * Linearly interpolate between two values.
+ * @param start - Start value (returned when `t = 0`).
+ * @param end - End value (returned when `t = 1`).
+ * @param t - Interpolation factor, typically in `[0, 1]`.
+ * @returns The interpolated value.
+ */
+export declare function lerp(start: number, end: number, t: number): number;
+/**
+ * Damp a value towards a target using an exponential ease-out.
+ * @param current - Current value.
+ * @param target - Target value.
+ * @param lambda - Damping factor (higher values = faster).
+ * @param dt - Delta time (usually in seconds).
+ * @returns The dampened value.
+ */
+/**
+ * Inverse linear interpolation — returns where `v` sits between `a` and `b` as a `[0, 1]` factor.
+ * @param a - Start value.
+ * @param b - End value.
+ * @param v - The value to map.
+ * @returns Clamped factor in `[0, 1]`.
+ */
+export declare function iLerp(a: number, b: number, v: number): number;
+export declare function damp(current: number, target: number, lambda: number, dt: number): number;

package/dist/smooth-scroll/index.d.ts

@@ -0,0 +1,83 @@
+export interface SmoothScrollOptions {
+    wrapper?: Window | HTMLElement | string;
+    direction?: "vertical" | "horizontal";
+    duration?: number;
+    ease?: number | ((t: number) => number);
+    prevent?: boolean;
+}
+export interface ScrollToOptions {
+    offset?: number;
+    duration?: number;
+    ease?: number | ((t: number) => number);
+    immediate?: boolean;
+    onComplete?: () => void;
+}
+export interface ScrollState {
+    current: number;
+    target: number;
+    velocity: number;
+    direction: 1 | -1;
+    max: number;
+    scrolling: boolean;
+}
+type EventCallback = (scroll: ScrollState) => void;
+export declare class SmoothScroll {
+    /** @internal */ _wrapper: Window | HTMLElement;
+    /** @internal */ _isW: boolean;
+    /** @internal */ _vertical: boolean;
+    /** @internal */ _duration: number;
+    /** @internal */ _ease: number | ((t: number) => number);
+    /** @internal */ _preventParent: boolean;
+    /** @internal */ _listening: boolean;
+    /** @internal */ _ticking: boolean;
+    /** @internal */ _listeners: Map<string, Set<EventCallback>>;
+    /** @internal */ _current: number;
+    /** @internal */ _target: number;
+    /** @internal */ _velocity: number;
+    /** @internal */ _dir: 1 | -1;
+    /** @internal */ _scrolling: boolean;
+    /** @internal */ _state: ScrollState;
+    /** @internal */ _driving: boolean;
+    /** @internal */ _aFrom: number;
+    /** @internal */ _aTo: number;
+    /** @internal */ _aStart: number;
+    /** @internal */ _aDur: number;
+    /** @internal */ _aCb: (() => void) | null;
+    /** @internal */ _aEase: number | ((t: number) => number);
+    /** @internal */ _aComplete: (() => void) | null;
+    /** @internal */ _onWheelBound: (e: WheelEvent) => void;
+    /** @internal */ _onScrollBound: () => void;
+    /** @internal */ _onKeyDownBound: (e: KeyboardEvent) => void;
+    /** @internal */ _tickBound: () => void;
+    constructor(options?: SmoothScrollOptions);
+    get scroll(): ScrollState;
+    /** @internal */
+    _max(): number;
+    /** @internal */
+    _clamp(v: number): number;
+    on(event: string, callback: EventCallback): void;
+    off(event: string, callback: EventCallback): void;
+    /** @internal */
+    _emit(event: string): void;
+    /** @internal — add ticker if not already ticking */
+    _startTick(): void;
+    /** @internal — remove ticker */
+    _stopTick(): void;
+    to(target: number | string | HTMLElement, options?: ScrollToOptions): void;
+    /** @internal */
+    _listen(action: "a" | "r"): void;
+    start(): void;
+    stop(): void;
+    destroy(): void;
+    /** @internal — wheel: intercepted for smooth damp */
+    _onWheel(e: WheelEvent): void;
+    /** @internal — native scroll event: sync when not driving (touch, programmatic, etc.) */
+    _onNativeScroll(): void;
+    /** @internal */
+    _onKeyDown(e: KeyboardEvent): void;
+    /** @internal */
+    _applyScroll(): void;
+    /** @internal */
+    _tick(): void;
+}
+export {};

package/dist/smooth-scroll/index.js

@@ -0,0 +1 @@
+import{b as a}from"../chunk-xcfcqftx.js";import"../chunk-0t3a7kj5.js";import"../chunk-qjsknche.js";export{a as SmoothScroll};

package/dist/split-text/index.d.ts

@@ -47,7 +47,7 @@ export declare class SplitText {
     /** @internal */ _classes: SplitTextOptions["class"];
     /** @internal */ _el: HTMLElement;
     /** @internal */ _instances: SplitText[] | null;
-    constructor(element: HTMLElement | HTMLElement[] | ArrayLike<HTMLElement> | string, options?: SplitTextOptions);
+    constructor(target: HTMLElement | HTMLElement[] | ArrayLike<HTMLElement> | string, options?: SplitTextOptions);
     /** @internal — create a styled inline-block element. */
     _makeEl(dataAttr: string, text?: string): HTMLElement;
     /** @internal — create a mask wrapper element. */

package/dist/split-text/index.js

@@ -1 +1 @@
-import{a}from"../chunk-8pnv9yxr.js";export{a as SplitText};
+import{a}from"../chunk-se6yyp59.js";import"../chunk-0t3a7kj5.js";export{a as SplitText};

package/dist/ticker/index.d.ts

@@ -0,0 +1,9 @@
+export type TickerCallback = (elapsed: number) => void;
+/**
+ * Returns the normalized delta frame (1.0 = perfect 60fps frame).
+ */
+export declare function getDeltaFrame(): number;
+export declare const Ticker: {
+    add(cb: TickerCallback): () => void;
+    remove(cb: TickerCallback): void;
+};

package/dist/ticker/index.js

@@ -0,0 +1 @@
+import{g as a,h as b}from"../chunk-qjsknche.js";export{a as getDeltaFrame,b as Ticker};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "situs-kit",
-  "version": "0.1.8",
+  "version": "0.1.9",
   "description": "A creative developer helper library",
   "license": "MIT",
   "module": "./dist/index.js",
@@ -15,6 +15,14 @@
     "./split-text": {
       "types": "./dist/split-text/index.d.ts",
       "import": "./dist/split-text/index.js"
+    },
+    "./smooth-scroll": {
+      "types": "./dist/smooth-scroll/index.d.ts",
+      "import": "./dist/smooth-scroll/index.js"
+    },
+    "./ticker": {
+      "types": "./dist/ticker/index.d.ts",
+      "import": "./dist/ticker/index.js"
     }
   },
   "files": [

package/dist/chunk-8pnv9yxr.js

@@ -1,2 +0,0 @@
-function C(q,z){return typeof globalThis.getComputedStyle==="function"?globalThis.getComputedStyle(q,z??null):null}var B=1,P=2,y=4,I="inline-block",h="nowrap",f="baseline",L="0px",g="block",E="maskChar",p="maskWord",s="maskLine",o=/^\s+$/,n=/(\s+)/,d=",div,span,svg,img,br,hr,canvas,video,audio,iframe,input,textarea,select,button,picture,figure,",r={u:"underline",ins:"underline",s:"line-through",strike:"line-through",del:"line-through"};class a{dom;chars;words;lines;masks;_n;_k;_g;_j;_f=[];_o=new Map;_i=null;_h=0;_l=!1;_c="";_d;_e;_b;_a=null;constructor(q,z={}){if(typeof q==="string"){let U=document.querySelectorAll?document.querySelectorAll(q):null;if(U&&U.length>1)q=Array.from(U);else{let V=U?U[0]:document.querySelector(q);if(!V)throw Error("SplitText: element not found");q=V}}if(Array.isArray(q)||typeof q==="object"&&q!==null&&"length"in q&&typeof q.item==="function"){let U=Array.from(q);if(U.length===0)throw Error("SplitText: empty element array");this._a=U.map((V)=>new a(V,z)),this.dom=U,this.chars=this._a.flatMap((V)=>V.chars),this.words=this._a.flatMap((V)=>V.words),this.lines=this._a.flatMap((V)=>V.lines),this.masks={chars:this._a.flatMap((V)=>V.masks.chars),words:this._a.flatMap((V)=>V.masks.words),lines:this._a.flatMap((V)=>V.masks.lines)},this._n="",this._k=0,this._g=0,this._j="";return}let $=q;this._b=$,this.dom=$,this._n=$.innerHTML,this.chars=[],this.words=[],this.lines=[],this.masks={chars:[],words:[],lines:[]};let G=z.type?Array.isArray(z.type)?z.type:[z.type]:["chars","words","lines"],Q=0;for(let U of G)if(U==="chars")Q|=B;else if(U==="words")Q|=P;else if(U==="lines")Q|=y;this._k=Q,this._j=z.tag??"span";let T=0;if(z.mask===!0)T=Q;else if(Array.isArray(z.mask)){for(let U of z.mask)if(U==="chars")T|=B;else if(U==="words")T|=P;else if(U==="lines")T|=y}if(this._g=T,this._d=z.style,this._e=z.class,this._w(),(z.resize??!0)&&Q&y)this._x()}_p(q,z){let F=document.createElement(this._j);if(q)F.dataset[q]="";if(F.style.display=I,z!==void 0)F.textContent=z;return F}_s(q,z){let F=document.createElement(this._j);if(F.dataset[z]="",F.style.overflow="hidden",F.style.display=q,this._d?.mask)Object.assign(F.style,this._d.mask);if(this._e?.mask)F.classList.add(this._e.mask);return F}_r(q,z,F,$,G){if(this._g&z){let Q=this._s(F,$);return Q.appendChild(q),G.push(Q),Q}return q}_m(q,z,F,$){if(F){let{outer:G,inner:Q}=F();if(Q.appendChild(z),$)this._o.set($,G);q.appendChild(G)}else q.appendChild(z)}_q(q,z,F){if(q.style.textDecoration=z,F)q.style.textDecorationColor=F}_w(){this._l=!0;let q=this._b,z=C(q),F=z?parseFloat(z.letterSpacing)||0:0;if(this._c=z?z.textIndent:"",this._c&&this._c!==L)q.style.textIndent="0";let $=this._k,G=!!($&B),Q=!!($&P),T=!!($&y),U=Q||T,V=!!(this._g&B),X=new Map,H=(N)=>{for(let u of Array.from(N.childNodes))if(u.nodeType===1){let R=u.tagName.toLowerCase();if(r[R]){let Y=C(u)?.textDecorationColor;if(Y)X.set(u,Y)}H(u)}};H(q);let Z=Array.from(q.childNodes),O=document.createDocumentFragment();q.replaceChildren();let k=(N,u,R,Y)=>{if(N.nodeType===3){let D=(N.textContent??"").split(n);for(let j of D){if(!j)continue;if(o.test(j)){O.appendChild(document.createTextNode(j));continue}let J=U?this._p(Q?"word":""):null;if(J){if(J.style.whiteSpace=h,R&&!G)this._q(J,R,Y)}if(G){let v=[...j],i=this.chars.length;for(let b=0;b<v.length;b++){let M=this._p("char",v[b]);if(F&&b<v.length-1)M.style.marginRight=`${F}px`;if(R)this._q(M,R,Y);if(this.chars.push(M),this._d?.chars)Object.assign(M.style,this._d.chars);if(this._e?.chars)M.classList.add(this._e.chars);let S=V?this._r(M,B,I,E,this.masks.chars):M;if(J)J.appendChild(S)}if(!J){let b=u?u():null,M=b?b.inner:O;for(let S=i;S<this.chars.length;S++){let _=this.chars[S];M.appendChild(V&&_.parentElement?.dataset?.[E]!==void 0?_.parentElement:_)}if(b)O.appendChild(b.outer)}}else if(J){if(J.textContent=j,F)J.style.letterSpacing=`${F}px`}if(J){if(Q){if(this.words.push(J),this._d?.words)Object.assign(J.style,this._d.words);if(this._e?.words)J.classList.add(this._e.words)}this._f.push(J);let v=this._g&P?this._r(J,P,I,p,this.masks.words):J;this._m(O,v,u,J)}else if(!G)this._m(O,document.createTextNode(j),u)}return}if(N.nodeType!==1)return;let x=N,W=x.tagName.toLowerCase();if(d.includes(","+W+",")){let D=x.cloneNode(!0);if(R)this._q(D,R,Y);let j=C(x)?.verticalAlign;if(j&&j!==f)D.style.verticalAlign=j;if(U){let J=this._p(Q?"word":"");if(J.style.whiteSpace=h,j&&j!==f)J.style.verticalAlign=j;if(J.appendChild(D),Q){if(this.words.push(J),this._d?.words)Object.assign(J.style,this._d.words);if(this._e?.words)J.classList.add(this._e.words)}this._f.push(J);let v=this._g&P?this._r(J,P,I,p,this.masks.words):J;this._m(O,v,u,J)}else this._m(O,D,u);return}let m=()=>{let D=x.cloneNode(!1);if(u){let{outer:j,inner:J}=u();return J.appendChild(D),{outer:j,inner:D}}return{outer:D,inner:D}},K=r[W],c=K?R?`${R} ${K}`:K:R,w=K?X.get(x)||Y:Y;for(let D of Array.from(x.childNodes))k(D,m,c,w)};for(let N of Z)k(N,null,"","");q.appendChild(O);let A=!!(this._c&&this._c!==L);if(T)this._y(A);else if(A){let N=Q?this.words[0]:G?this.chars[0]:null;if(N)N.style.marginLeft=this._c,q.style.textIndent="0"}this._l=!1}_y(q){if(q&&this._f[0])this._f[0].style.marginLeft=this._c;this._t();let z=[];if(typeof document.fonts?.status==="string"&&document.fonts.status!=="loaded")z.push(document.fonts.ready);let F=this._b.querySelectorAll("img");for(let $=0;$<F.length;$++){let G=F[$];if(!G.complete)z.push(new Promise((Q)=>{G.addEventListener("load",Q,{once:!0}),G.addEventListener("error",Q,{once:!0})}))}if(z.length){let $=this._b.offsetHeight;Promise.all(z).then(()=>{if(this._b.offsetHeight!==$)this.reflow()})}}_u(q){return this._o.get(q)??q}_t(){let q=this._f;if(!q.length)return;let z=q[0].offsetTop,F=z+q[0].offsetHeight,$=[],G=[];for(let V of q){let X=V.offsetTop,H=X+V.offsetHeight;if(X<F&&H>z)z=Math.min(z,X),F=Math.max(F,H);else G.push($),$=[],z=X,F=H;$.push(V)}if($.length)G.push($);let Q=!!(this._c&&this._c!==L);if(Q&&q[0])q[0].style.marginLeft="";let T=!!(this._g&y),U=document.createDocumentFragment();for(let V=0;V<G.length;V++){let X=G[V],H=document.createElement(this._j);if(H.dataset.line="",H.style.display=g,V===0&&Q)H.style.paddingLeft=this._c;for(let Z=0;Z<X.length;Z++){if(Z>0)H.appendChild(document.createTextNode(" "));H.appendChild(this._u(X[Z]))}if(this.lines.push(H),this._d?.lines)Object.assign(H.style,this._d.lines);if(this._e?.lines)H.classList.add(this._e.lines);if(T){let Z=this._s(g,s);Z.appendChild(H),this.masks.lines.push(Z),U.appendChild(Z)}else U.appendChild(H)}this._b.replaceChildren(U)}_x(){let q=this._b.offsetParent?this._b.offsetParent.offsetWidth:window.innerWidth,z=()=>{if(this._l)return;let $=this._b.offsetParent,G=$?$.offsetWidth:window.innerWidth;if(G===q)return;if(q=G,this._h)cancelAnimationFrame(this._h);this._h=requestAnimationFrame(()=>this.reflow())};this._i=new ResizeObserver(z);let F=this._b.offsetParent??this._b.parentElement;if(F)this._i.observe(F);else this._i.observe(this._b)}reflow(){if(this._a){this._a.forEach((z)=>z.reflow()),this._v();return}if(!(this._k&y)||this._l)return;let q=document.createDocumentFragment();for(let z=0;z<this._f.length;z++){if(z>0)q.appendChild(document.createTextNode(" "));q.appendChild(this._u(this._f[z]))}if(this._b.replaceChildren(q),this.lines.length=0,this.masks.lines.length=0,this._c&&this._c!==L&&this._f[0])this._f[0].style.marginLeft=this._c;this._t()}revert(){if(this._a){this._a.forEach((q)=>q.revert()),this._v();return}this.destroy(),this._b.innerHTML=this._n,this.chars.length=0,this.words.length=0,this._f.length=0,this._o.clear(),this.lines.length=0,this.masks.chars.length=0,this.masks.words.length=0,this.masks.lines.length=0}destroy(){if(this._a){this._a.forEach((q)=>q.destroy());return}if(this._h)cancelAnimationFrame(this._h),this._h=0;if(this._i)this._i.disconnect(),this._i=null}_v(){if(!this._a)return;this.chars.length=0,this.words.length=0,this.lines.length=0,this.masks.chars.length=0,this.masks.words.length=0,this.masks.lines.length=0;for(let q of this._a)this.chars.push(...q.chars),this.words.push(...q.words),this.lines.push(...q.lines),this.masks.chars.push(...q.masks.chars),this.masks.words.push(...q.masks.words),this.masks.lines.push(...q.masks.lines)}}
-export{a};