situs-kit 0.2.0 → 0.2.2

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 Surya Aditya
+Copyright (c) 2026 Surya Aditya
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,19 +1,309 @@
-# situs-kit
+# Situs Toolkit
 
 A zero-dependency creative developer toolkit
 
-## Install
+- [SplitText](#splittext)
+- [SmoothScroll](#smoothscroll)
+- [Ticker](#ticker)
 
-```bash
-npm install situs-kit
+---
+
+# SplitText
+
+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[]
+```
+
+## Constructor
+
+```ts
+new SplitText(
+  element: HTMLElement | HTMLElement[] | ArrayLike<HTMLElement> | string,
+  options?: SplitTextOptions
+)
+```
+
+The `element` parameter accepts:
+
+- A CSS selector string (e.g. `"#my-text"`, `".my-class"`)
+- A single `HTMLElement`
+- An array or array-like collection of `HTMLElement`s (creates sub-instances, aggregating results)
+
+## 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` | `SplitType \| SplitType[]` | `["chars", "words", "lines"]` | Split granularity |
+| `tag` | `string` | `"span"` | Wrapper element tag |
+| `mask` | `boolean \| SplitType[]` | `false` | Create overflow-hidden wrappers. `true` masks all requested types; array masks only specified types |
+| `resize` | `boolean` | `true` | Auto-reflow lines on window resize (only applies when lines are split) |
+| `style` | `object` | — | Inline styles per split type (`chars`, `words`, `lines`, `mask`) |
+| `class` | `object` | — | CSS classes per split type (`chars`, `words`, `lines`, `mask`) |
+
+### Types
+
+```ts
+type SplitType = "chars" | "words" | "lines"
+
+type SplitTypeOption =
+  | SplitType
+  | ["chars"]
+  | ["words"]
+  | ["lines"]
+  | ["chars", "words"]
+  | ["chars", "lines"]
+  | ["words", "lines"]
+  | ["chars", "words", "lines"]
+```
+
+## Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `dom` | `HTMLElement \| HTMLElement[]` | The original element(s) |
+| `chars` | `HTMLElement[]` | Character wrapper elements |
+| `words` | `HTMLElement[]` | Word wrapper elements |
+| `lines` | `HTMLElement[]` | Line wrapper elements |
+| `masks` | `{ chars: HTMLElement[], words: HTMLElement[], lines: HTMLElement[] }` | Mask wrapper elements per split type |
+
+## Methods
+
+### `reflow()`
+
+Recalculate line groupings without re-splitting characters or words. Called automatically on resize when `resize: true`. Does nothing if lines weren't requested in `type`.
+
+```ts
+split.reflow();
 ```
 
-## Modules
+### `revert()`
+
+Restore the element to its original HTML. Clears all `chars`, `words`, `lines`, and `masks` arrays. Calls `destroy()` internally.
+
+```ts
+split.revert();
+```
+
+### `destroy()`
+
+Remove resize observers and cancel pending animation frames. Called automatically by `revert()`. Safe to call multiple times.
+
+```ts
+split.destroy();
+```
+
+## Data Attributes
+
+Split elements include data attributes for CSS targeting:
+
+```css
+[data-char] { display: inline-block; }
+[data-word] { display: inline-block; }
+[data-line] { display: block; }
+```
+
+Mask elements use:
+
+- `data-maskChar`
+- `data-maskWord`
+- `data-maskLine`
+
+## HTML Preservation
+
+Inline elements like `<a>`, `<em>`, `<strong>`, `<u>`, `<i>`, `<b>`, `<ins>`, `<s>`, `<strike>`, and `<del>` are preserved and cloned around split elements.
+
+Opaque elements like `<div>`, `<span>`, `<svg>`, `<img>`, `<br>`, `<canvas>`, `<video>`, `<audio>`, `<iframe>`, `<input>`, `<textarea>`, `<select>`, `<button>`, `<picture>`, and `<figure>` are treated as atomic 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. You can specify which split levels to mask:
+
+```ts
+// mask only lines
+const split = new SplitText("#text", {
+  type: ["words", "lines"],
+  mask: ["lines"],
+});
+
+split.masks.lines;  // HTMLElement[] - overflow:hidden wrappers
+
+// mask all split types
+const split2 = new SplitText("#text", {
+  type: ["chars", "words", "lines"],
+  mask: true,
+});
+```
+
+## Multi-Element Support
+
+When passing multiple elements (via selector, array, or array-like), SplitText creates sub-instances and aggregates all results into the top-level `chars`, `words`, `lines`, and `masks` arrays.
+
+```ts
+const split = new SplitText(".my-text");
+
+// chars/words/lines contain elements from all matched elements
+split.chars;  // HTMLElement[] from all .my-text elements
+```
+
+## Additional Behaviors
+
+- **Letter spacing**: Automatically applied to character elements when the parent has `letter-spacing` set
+- **Text indent**: Preserved on the first line
+
+---
+
+# SmoothScroll
+
+Smooth scroll with frame-rate independent damping. Intercepts wheel for smooth interpolation, uses native scroll for touch/mobile.
+
+## Usage
+
+```ts
+import { SmoothScroll } from "situs-kit/smooth-scroll";
+
+const scroll = new SmoothScroll();
+```
+
+### Options
+
+```ts
+const scroll = new SmoothScroll({
+  wrapper: "#scroll-box",    // window | HTMLElement | string (default: window)
+  direction: "vertical",      // "vertical" | "horizontal"
+  duration: 800,               // global to() duration in ms (0 = use damp)
+  ease: 0.09,                  // number → damp factor, function → tween ease (default: 0.09)
+  prevent: true,   // stop wheel propagation (default: true for elements, false for window)
+});
+```
+
+## Scroll State
+
+```ts
+const { current, target, velocity, direction, max, scrolling } = scroll.scroll;
+```
+
+> **Note:** `scroll` returns a shared object that is mutated each frame. Destructure or copy the values if you need to compare across frames.
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `current` | `number` | Current interpolated position |
+| `target` | `number` | Target position |
+| `velocity` | `number` | Pixels moved since last frame |
+| `direction` | `1 \| -1` | 1 = forward, -1 = backward |
+| `max` | `number` | Maximum scroll value |
+| `scrolling` | `boolean` | Whether currently scrolling |
+
+## Methods
+
+### `to(target, options?)`
+
+```ts
+scroll.to(500);
+scroll.to("#section-2", { offset: -100 });
+scroll.to(element, { duration: 1000 });
+scroll.to(0, { immediate: true });
+```
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `offset` | `number` | Pixel offset added to target |
+| `duration` | `number` | Animation duration in ms (defaults to constructor `duration`) |
+| `ease` | `number \| (t: number) => number` | Number → damp factor, function → tween ease curve |
+| `immediate` | `boolean` | Jump instantly |
+| `onComplete` | `() => void` | Callback when scroll completes |
+
+### `start()` / `stop()`
+
+Resume or pause scroll listening and the animation loop.
+
+### `destroy()`
+
+Full cleanup — removes listeners, stops the ticker, clears events.
+
+## Events
+
+```ts
+scroll.on("scroll", ({ current, target, velocity, direction, max }) => {});
+scroll.off("scroll", callback);
+```
+
+## Window vs Element Mode
+
+Both modes use the same scroll-jacking approach: wheel is intercepted for smooth damping, touch and programmatic scrolls sync via native `scroll` events.
+
+**Window** (default) — drives scroll via `window.scrollTo()`.
+
+**Element** — pass a `wrapper` to enable. Drives scroll via `scrollTop`/`scrollLeft`. The wrapper element should have `overflow: auto` or `overflow: scroll`.
+
+---
+
+# Ticker
+
+Shared singleton RAF loop. Used internally by SmoothScroll.
+
+## Usage
+
+```ts
+import { Ticker, getDeltaFrame } from "situs-kit/ticker";
+
+const off = Ticker.add((elapsed) => {
+  const df = getDeltaFrame(); // 1.0 = 60fps frame
+  object.x += speed * df;
+});
+
+off(); // unsubscribe
+```
+
+## API
+
+### `Ticker.add(callback): () => void`
+
+Add a callback to the loop. Returns an unsubscribe function. The callback receives `elapsed` (ms since added).
+
+### `Ticker.remove(callback): void`
 
-- [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
+Remove a callback by reference.
 
-## License
+### `getDeltaFrame(): number`
 
-MIT
+Normalized delta frame. `1.0` at 60fps, `2.0` at 30fps, `0.5` at 120fps.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "situs-kit",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "A creative developer helper library",
   "license": "MIT",
   "module": "./dist/index.js",
@@ -26,8 +26,7 @@
     }
   },
   "files": [
-    "dist",
-    "docs"
+    "dist"
   ],
   "scripts": {
     "build": "bun build.ts && bunx tsc -p tsconfig.build.json",

package/docs/smooth-scroll.md

@@ -1,82 +0,0 @@
-# SmoothScroll
-
-Smooth scroll with frame-rate independent damping. Intercepts wheel for smooth interpolation, uses native scroll for touch/mobile.
-
-## Usage
-
-```ts
-import { SmoothScroll } from "situs-kit/smooth-scroll";
-
-const scroll = new SmoothScroll();
-```
-
-### Options
-
-```ts
-const scroll = new SmoothScroll({
-  wrapper: "#scroll-box",    // window | HTMLElement | string (default: window)
-  direction: "vertical",      // "vertical" | "horizontal"
-  duration: 800,               // global to() duration in ms (0 = use damp)
-  ease: 0.09,                  // number → damp factor, function → tween ease (default: 0.09)
-  prevent: true,   // stop wheel propagation (default: true for elements, false for window)
-});
-```
-
-## Scroll State
-
-```ts
-const { current, target, velocity, direction, max, scrolling } = scroll.scroll;
-```
-
-> **Note:** `scroll` returns a shared object that is mutated each frame. Destructure or copy the values if you need to compare across frames.
-
-| Property | Type | Description |
-|----------|------|-------------|
-| `current` | `number` | Current interpolated position |
-| `target` | `number` | Target position |
-| `velocity` | `number` | Pixels moved since last frame |
-| `direction` | `1 \| -1` | 1 = forward, -1 = backward |
-| `max` | `number` | Maximum scroll value |
-| `scrolling` | `boolean` | Whether currently scrolling |
-
-## Methods
-
-### `to(target, options?)`
-
-```ts
-scroll.to(500);
-scroll.to("#section-2", { offset: -100 });
-scroll.to(element, { duration: 1000 });
-scroll.to(0, { immediate: true });
-```
-
-| Option | Type | Description |
-|--------|------|-------------|
-| `offset` | `number` | Pixel offset added to target |
-| `duration` | `number` | Animation duration in ms (defaults to constructor `duration`) |
-| `ease` | `number \| (t: number) => number` | Number → damp factor, function → tween ease curve |
-| `immediate` | `boolean` | Jump instantly |
-| `onComplete` | `() => void` | Callback when scroll completes |
-
-### `start()` / `stop()`
-
-Resume or pause scroll listening and the animation loop.
-
-### `destroy()`
-
-Full cleanup — removes listeners, stops the ticker, clears events.
-
-## Events
-
-```ts
-scroll.on("scroll", ({ current, target, velocity, direction, max }) => {});
-scroll.off("scroll", callback);
-```
-
-## Window vs Element Mode
-
-Both modes use the same scroll-jacking approach: wheel is intercepted for smooth damping, touch and programmatic scrolls sync via native `scroll` events.
-
-**Window** (default) — drives scroll via `window.scrollTo()`.
-
-**Element** — pass a `wrapper` to enable. Drives scroll via `scrollTop`/`scrollLeft`. The wrapper element should have `overflow: auto` or `overflow: scroll`.

package/docs/split-text.md

@@ -1,181 +0,0 @@
-# SplitText
-
-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[]
-```
-
-## Constructor
-
-```ts
-new SplitText(
-  element: HTMLElement | HTMLElement[] | ArrayLike<HTMLElement> | string,
-  options?: SplitTextOptions
-)
-```
-
-The `element` parameter accepts:
-
-- A CSS selector string (e.g. `"#my-text"`, `".my-class"`)
-- A single `HTMLElement`
-- An array or array-like collection of `HTMLElement`s (creates sub-instances, aggregating results)
-
-## 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` | `SplitType \| SplitType[]` | `["chars", "words", "lines"]` | Split granularity |
-| `tag` | `string` | `"span"` | Wrapper element tag |
-| `mask` | `boolean \| SplitType[]` | `false` | Create overflow-hidden wrappers. `true` masks all requested types; array masks only specified types |
-| `resize` | `boolean` | `true` | Auto-reflow lines on window resize (only applies when lines are split) |
-| `style` | `object` | — | Inline styles per split type (`chars`, `words`, `lines`, `mask`) |
-| `class` | `object` | — | CSS classes per split type (`chars`, `words`, `lines`, `mask`) |
-
-### Types
-
-```ts
-type SplitType = "chars" | "words" | "lines"
-
-type SplitTypeOption =
-  | SplitType
-  | ["chars"]
-  | ["words"]
-  | ["lines"]
-  | ["chars", "words"]
-  | ["chars", "lines"]
-  | ["words", "lines"]
-  | ["chars", "words", "lines"]
-```
-
-## Properties
-
-| Property | Type | Description |
-|----------|------|-------------|
-| `dom` | `HTMLElement \| HTMLElement[]` | The original element(s) |
-| `chars` | `HTMLElement[]` | Character wrapper elements |
-| `words` | `HTMLElement[]` | Word wrapper elements |
-| `lines` | `HTMLElement[]` | Line wrapper elements |
-| `masks` | `{ chars: HTMLElement[], words: HTMLElement[], lines: HTMLElement[] }` | Mask wrapper elements per split type |
-
-## Methods
-
-### `reflow()`
-
-Recalculate line groupings without re-splitting characters or words. Called automatically on resize when `resize: true`. Does nothing if lines weren't requested in `type`.
-
-```ts
-split.reflow();
-```
-
-### `revert()`
-
-Restore the element to its original HTML. Clears all `chars`, `words`, `lines`, and `masks` arrays. Calls `destroy()` internally.
-
-```ts
-split.revert();
-```
-
-### `destroy()`
-
-Remove resize observers and cancel pending animation frames. Called automatically by `revert()`. Safe to call multiple times.
-
-```ts
-split.destroy();
-```
-
-## Data Attributes
-
-Split elements include data attributes for CSS targeting:
-
-```css
-[data-char] { display: inline-block; }
-[data-word] { display: inline-block; }
-[data-line] { display: block; }
-```
-
-Mask elements use:
-
-- `data-maskChar`
-- `data-maskWord`
-- `data-maskLine`
-
-## HTML Preservation
-
-Inline elements like `<a>`, `<em>`, `<strong>`, `<u>`, `<i>`, `<b>`, `<ins>`, `<s>`, `<strike>`, and `<del>` are preserved and cloned around split elements.
-
-Opaque elements like `<div>`, `<span>`, `<svg>`, `<img>`, `<br>`, `<canvas>`, `<video>`, `<audio>`, `<iframe>`, `<input>`, `<textarea>`, `<select>`, `<button>`, `<picture>`, and `<figure>` are treated as atomic 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. You can specify which split levels to mask:
-
-```ts
-// mask only lines
-const split = new SplitText("#text", {
-  type: ["words", "lines"],
-  mask: ["lines"],
-});
-
-split.masks.lines;  // HTMLElement[] - overflow:hidden wrappers
-
-// mask all split types
-const split2 = new SplitText("#text", {
-  type: ["chars", "words", "lines"],
-  mask: true,
-});
-```
-
-## Multi-Element Support
-
-When passing multiple elements (via selector, array, or array-like), SplitText creates sub-instances and aggregates all results into the top-level `chars`, `words`, `lines`, and `masks` arrays.
-
-```ts
-const split = new SplitText(".my-text");
-
-// chars/words/lines contain elements from all matched elements
-split.chars;  // HTMLElement[] from all .my-text elements
-```
-
-## Additional Behaviors
-
-- **Letter spacing**: Automatically applied to character elements when the parent has `letter-spacing` set
-- **Text indent**: Preserved on the first line

package/docs/ticker.md

@@ -1,30 +0,0 @@
-# Ticker
-
-Shared singleton RAF loop. Used internally by SmoothScroll.
-
-## Usage
-
-```ts
-import { Ticker, getDeltaFrame } from "situs-kit/ticker";
-
-const off = Ticker.add((elapsed) => {
-  const df = getDeltaFrame(); // 1.0 = 60fps frame
-  object.x += speed * df;
-});
-
-off(); // unsubscribe
-```
-
-## API
-
-### `Ticker.add(callback): () => void`
-
-Add a callback to the loop. Returns an unsubscribe function. The callback receives `elapsed` (ms since added).
-
-### `Ticker.remove(callback): void`
-
-Remove a callback by reference.
-
-### `getDeltaFrame(): number`
-
-Normalized delta frame. `1.0` at 60fps, `2.0` at 30fps, `0.5` at 120fps.