slot-text 0.2.2 → 0.3.1

package/README.md

@@ -1,18 +1,25 @@
 # slot-text
 
-Dependency-free text roll animation for tiny, tactile UI labels.
+<p>
+  <a href="https://www.npmjs.com/package/slot-text"><img src="https://img.shields.io/npm/v/slot-text?color=cb3837&label=npm" alt="npm version"></a>
+  <img src="https://img.shields.io/badge/dependencies-zero-22c55e" alt="zero dependencies">
+  <img src="https://img.shields.io/bundlephobia/minzip/slot-text?color=8b5cf6&label=size" alt="bundle size">
+  <img src="https://img.shields.io/badge/react-✓-61dafb" alt="react">
+  <img src="https://img.shields.io/badge/vue-✓-42b883" alt="vue">
+  <img src="https://img.shields.io/badge/solid-✓-2c4f7c" alt="solid">
+  <img src="https://img.shields.io/badge/svelte-✓-ff3e00" alt="svelte">
+  <img src="https://img.shields.io/badge/typescript-✓-3178c6" alt="typescript">
+</p>
 
-![slot-text usage card](./assets/usage.svg)
+Dependency-free text roll animation for tiny, tactile UI labels.
 
-## Install
+## 📦 Install
 
 ```bash
 npm install slot-text
 ```
 
-## Use
-
-### Vanilla
+## 🚀 Quick start
 
 ```ts
 import "slot-text/style.css";
@@ -20,189 +27,143 @@ import { slotText, chromatic } from "slot-text";
 
 const label = slotText(document.querySelector("#copy")!, "Copy");
 
-label.set("Copied", {
-  direction: "up",
-  color: chromatic(),
+// the classic Copy → Copied → Copy, in one call
+label.flash("Copied", { enter: { color: chromatic() } });
+```
+
+That's it — import the CSS once, attach to an element, roll text.
+
+## 🧩 API
+
+| Method | What it does |
+| --- | --- |
+| `set(text, options?)` | Roll to new text — the text **stays** |
+| `flash(text, options?)` | Roll in, then **auto-revert** to the previous text |
+| `destroy()` | Clean up |
+
+```ts
+const label = slotText(element, "Copy", options);
+
+label.set("Copied");                  // permanent change
+label.set("Copy", { direction: "down" });
+label.flash("Copied");                // temporary — rolls back after 1.4s
+label.destroy();
+```
+
+> 💡 **`flash` is spam-safe** — repeat clicks restart the revert timer instead
+> of queuing extra rolls, and an explicit `set()` cancels any pending revert.
+
+```ts
+label.flash("Copied", {
+  revertAfter: 1400,                              // ms before rolling back
+  enter: { direction: "up", color: chromatic() }, // roll-in
+  exit: { direction: "down" },                    // roll-back
 });
 ```
 
-### React
+## ⚛️ React
 
 ```tsx
 import "slot-text/style.css";
 import { SlotText } from "slot-text/react";
 import { chromatic } from "slot-text";
 
-export function CopyLabel({ copied }: { copied: boolean }) {
-  return (
-    <SlotText
-      text={copied ? "Copied" : "Copy"}
-      options={{
-        direction: copied ? "up" : "down",
-        skipUnchanged: false,
-        color: copied ? chromatic() : undefined,
-      }}
-    />
-  );
-}
+<SlotText
+  text={copied ? "Copied" : "Copy"}
+  options={{ direction: copied ? "up" : "down", color: copied ? chromatic() : undefined }}
+/>
 ```
 
-### Vue
+## 💚 Vue
 
 ```vue
 <script setup lang="ts">
 import "slot-text/style.css";
 import { SlotText } from "slot-text/vue";
-import { chromatic } from "slot-text";
-
-const options = {
-  direction: "up",
-  skipUnchanged: false,
-  color: chromatic(),
-} as const;
 </script>
 
 <template>
-  <SlotText text="Copied" :options="options" />
+  <SlotText text="Copied" :options="{ direction: 'up' }" />
 </template>
 ```
 
-## API
-
-Vanilla controller:
-
-```ts
-const label = slotText(element, "Copy", options);
-
-label.set("Copied");
-label.set("Copy", { direction: "down" });
-label.flash("Copied"); // rolls in, then auto-reverts to "Copy"
-label.destroy();
-```
-
-`flash(text, options)` shows temporary text and rolls back automatically —
-the classic Copy → Copied → Copy button in one call. It is spam-safe: repeat
-flashes restart the revert timer instead of queuing extra rolls, and an
-explicit `set()` cancels any pending revert.
+## 🔷 Solid
 
-```ts
-label.flash("Copied", {
-  revertAfter: 1400, // ms before rolling back (default 1400)
-  enter: { direction: "up", color: chromatic() }, // roll-in options
-  exit: { direction: "down" }, // roll-back options
-});
-```
-
-Framework components:
-
-```ts
-import { SlotText as ReactSlotText } from "slot-text/react";
-import { SlotText as VueSlotText } from "slot-text/vue";
-```
+```tsx
+import "slot-text/style.css";
+import { createSignal } from "solid-js";
+import { slotText } from "slot-text/solid";
 
-Low-level helpers:
+const [label, setLabel] = createSignal("Copy");
 
-```ts
-import {
-  buildSlotText,
-  animateSlotText,
-  chromatic,
-} from "slot-text";
+<button aria-label={label()} onClick={() => setLabel("Copied")}>
+  <span use:slotText={{ text: label(), options: { direction: "up" } }} />
+</button>
 ```
 
-## Options
+## 🧡 Svelte
 
-```ts
-type SlotOptions = {
-  direction?: "up" | "down";
-  stagger?: number;
-  duration?: number;
-  exitOffset?: number;
-  easing?: string;
-  bounce?: number;
-  color?: string | ((index: number, total: number) => string);
-  colorFade?: number;
-  skipUnchanged?: boolean;
-  interrupt?: boolean;
-};
-```
-
-`interrupt: true` (default) cuts off any roll still in flight and starts
-fresh. `interrupt: false` lets the current roll finish: the latest call made
-mid-roll plays once it lands, and calls targeting the text already displayed
-are dropped — ideal for spam-prone triggers like buttons.
+```svelte
+<script lang="ts">
+  import "slot-text/style.css";
+  import { slotText } from "slot-text/svelte";
 
-Defaults are tuned for a soft, springy roll:
+  let label = "Copy";
+</script>
 
-```ts
-{
-  direction: "down",
-  stagger: 45,
-  duration: 300,
-  exitOffset: 50,
-  easing: "cubic-bezier(0.34, 1.56, 0.64, 1)",
-  bounce: 0.6,
-  colorFade: 280,
-  skipUnchanged: true,
-  interrupt: true,
-}
+<button aria-label={label} on:click={() => label = "Copied"}>
+  <span use:slotText={{ text: label, options: { direction: "up" } }}></span>
+</button>
 ```
 
-## Example
+## ⚙️ Options
 
-```html
-<button>
-  <span id="copy-label"></span>
-</button>
+| Option | Default | Description |
+| --- | --- | --- |
+| `direction` | `"down"` | Roll direction: `"up"` or `"down"` |
+| `stagger` | `45` | Delay between characters (ms) |
+| `duration` | `300` | Per-character animation time (ms) |
+| `exitOffset` | `50` | Delay before the old character exits (ms) |
+| `easing` | springy bezier | CSS easing function |
+| `bounce` | `0.6` | Overshoot amount |
+| `color` | — | Color string, or `(index, total) => string` |
+| `colorFade` | `280` | Fade back to base color (ms) |
+| `skipUnchanged` | `true` | Don't re-roll identical characters |
+| `interrupt` | `true` | See below 👇 |
 
-<script type="module">
-  import "slot-text/style.css";
-  import { slotText, chromatic } from "slot-text";
+### 🛑 `interrupt`
 
-  const label = slotText(document.querySelector("#copy-label"), "Copy");
+- `interrupt: true` *(default)* — cuts off any roll in flight, starts fresh.
+- `interrupt: false` — lets the current roll **finish**; the latest call plays
+  after it lands, duplicates are dropped. Ideal for spam-prone buttons.
 
-  document.querySelector("button").addEventListener("click", () => {
-    label.flash("Copied", {
-      enter: { direction: "up", skipUnchanged: false, color: chromatic() },
-      exit: { direction: "down", skipUnchanged: false },
-    });
-  });
-</script>
-```
+### 🌈 `chromatic()`
 
-## Font support
+Built-in rainbow color helper — pass it as `color` for a per-character hue sweep.
 
-Each character animates inside its own measured cell, sized with the exact
-font you give the element — so widths are always correct.
+## 🔤 Font support
 
-Works great with:
+Each character animates in its own measured cell using your element's exact
+font, so widths are always correct.
 
-- **Monospace fonts** — perfect fit, every cell is identical.
-- **Proportional Latin / Cyrillic / Greek fonts** (Geist, Inter, SF, …) —
-  including italics and glyphs with overhang.
+✅ **Great with:** monospace fonts, proportional Latin / Cyrillic / Greek
+(Geist, Inter, SF, …), italics, glyphs with overhang.
 
-Known tradeoffs (inherent to any per-character slot animation):
+⚠️ **Tradeoffs** (inherent to any per-character slot animation):
 
-- **Kerning is lost.** Each glyph is its own box, so pairs like `AV` or `To`
-  sit slightly looser than in plain text. Invisible at UI label sizes,
-  noticeable at large display sizes with kerning-heavy fonts.
-- **Ligatures won't form** — `fi`, `fl`, or coding ligatures stay separate.
-- **Joined scripts are unsupported.** Arabic, Devanagari and other shaping
-  scripts need contextual letterforms across the string and will render as
-  isolated forms.
-- **Complex emoji split.** Single emoji are fine (surrogate pairs are
-  handled), but ZWJ sequences (👨‍👩‍👧) and combining marks break into
-  multiple cells.
-- **Very tall display/script fonts** may clip at the vertical roll mask,
-  which is sized to `line-height: 1.3`.
+- Kerning is lost — pairs like `AV` sit slightly looser (invisible at label sizes).
+- Ligatures won't form (`fi`, `fl`, coding ligatures).
+- Joined scripts (Arabic, Devanagari) render as isolated forms.
+- ZWJ emoji sequences (👨‍👩‍👧) split into cells; single emoji are fine.
+- Very tall display fonts may clip at the roll mask (`line-height: 1.3`).
 
-In short: ideal for short Latin labels, numbers, statuses and commands — in
+**In short:** ideal for short labels, numbers, statuses and commands — in
 essentially any font you'd use for those.
 
-## Notes
+## 📝 Notes
 
-- Browser-only DOM utility.
-- Core API has no runtime dependencies.
-- React and Vue are optional peer dependencies. Plain JS users do not need them.
-- Works best on short labels, buttons, counters, and command text.
+- Browser-only DOM utility, zero runtime dependencies.
+- React, Vue, Solid, and Svelte are optional peer dependencies — plain JS users
+  don't need them.
 - Import the CSS once before using the animation.
+- Low-level helpers also exported: `buildSlotText`, `animateSlotText`, `chromatic`.

package/dist/solid.d.ts

@@ -0,0 +1,14 @@
+import { type Accessor } from "solid-js";
+import { type SlotOptions } from "./index.js";
+export interface SlotTextParams {
+    text: string;
+    options?: SlotOptions;
+}
+export declare function slotText(element: HTMLElement, accessor: Accessor<SlotTextParams>): void;
+declare module "solid-js" {
+    namespace JSX {
+        interface Directives {
+            slotText: SlotTextParams;
+        }
+    }
+}

package/dist/solid.js

@@ -0,0 +1,22 @@
+import { createRenderEffect, onCleanup } from "solid-js";
+import { slotText as createSlotText } from "./index.js";
+export function slotText(element, accessor) {
+    const initial = accessor();
+    const controller = createSlotText(element, initial.text);
+    let previousText = initial.text;
+    let isFirstRun = true;
+    createRenderEffect(() => {
+        const next = accessor();
+        if (isFirstRun) {
+            isFirstRun = false;
+            return;
+        }
+        if (next.text !== previousText) {
+            previousText = next.text;
+            controller.set(next.text, next.options);
+        }
+    });
+    onCleanup(() => {
+        controller.destroy();
+    });
+}

package/dist/svelte.d.ts

@@ -0,0 +1,9 @@
+import { type SlotOptions } from "./index.js";
+export interface SlotTextParams {
+    text: string;
+    options?: SlotOptions;
+}
+export declare function slotText(element: HTMLElement, params: SlotTextParams): {
+    update(params: SlotTextParams): void;
+    destroy(): void;
+};

package/dist/svelte.js

@@ -0,0 +1,16 @@
+import { slotText as createSlotText } from "./index.js";
+export function slotText(element, params) {
+    const controller = createSlotText(element, params.text);
+    let previousText = params.text;
+    return {
+        update(params) {
+            if (params.text === previousText)
+                return;
+            previousText = params.text;
+            controller.set(params.text, params.options);
+        },
+        destroy() {
+            controller.destroy();
+        },
+    };
+}

package/examples/env.d.ts

@@ -0,0 +1 @@
+declare module "slot-text/style.css";

package/examples/solid.tsx

@@ -0,0 +1,30 @@
+import { createSignal } from "solid-js";
+import "slot-text/style.css";
+import { chromatic } from "slot-text";
+import { slotText } from "slot-text/solid";
+
+void slotText;
+
+export function CopyButton() {
+  const [copied, setCopied] = createSignal(false);
+
+  function copy() {
+    setCopied(true);
+    window.setTimeout(() => setCopied(false), 1400);
+  }
+
+  return (
+    <button type="button" aria-label={copied() ? "Copied" : "Copy"} onClick={copy}>
+      <span
+        use:slotText={{
+          text: copied() ? "Copied" : "Copy",
+          options: {
+            direction: copied() ? "up" : "down",
+            skipUnchanged: false,
+            color: copied() ? chromatic({ from: 190 }) : undefined,
+          },
+        }}
+      />
+    </button>
+  );
+}

package/examples/svelte.svelte

@@ -0,0 +1,27 @@
+<script lang="ts">
+  import "slot-text/style.css";
+  import { chromatic } from "slot-text";
+  import { slotText } from "slot-text/svelte";
+
+  let copied = false;
+
+  function copy() {
+    copied = true;
+    window.setTimeout(() => {
+      copied = false;
+    }, 1400);
+  }
+</script>
+
+<button type="button" aria-label={copied ? "Copied" : "Copy"} on:click={copy}>
+  <span
+    use:slotText={{
+      text: copied ? "Copied" : "Copy",
+      options: {
+        direction: copied ? "up" : "down",
+        skipUnchanged: false,
+        color: copied ? chromatic({ from: 190 }) : undefined,
+      },
+    }}
+  ></span>
+</button>

package/examples/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ES2020",
+    "moduleResolution": "Bundler",
+    "lib": ["ES2020", "DOM"],
+    "strict": true,
+    "skipLibCheck": true,
+    "jsx": "preserve",
+    "jsxImportSource": "solid-js",
+    "paths": {
+      "slot-text": ["../src/index.ts"],
+      "slot-text/solid": ["../src/solid.ts"],
+      "slot-text/svelte": ["../src/svelte.ts"]
+    }
+  },
+  "include": ["env.d.ts", "solid.tsx", "*.svelte", "../src/**/*.ts"]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "slot-text",
-  "version": "0.2.2",
+  "version": "0.3.1",
   "description": "Dependency-free text roll animation for tiny, tactile UI labels.",
   "type": "module",
   "license": "MIT",
@@ -13,6 +13,7 @@
     "dist",
     "examples",
     "style.css",
+    "style.css.d.ts",
     "README.md",
     "LICENSE"
   ],
@@ -29,11 +30,24 @@
       "types": "./dist/vue.d.ts",
       "import": "./dist/vue.js"
     },
-    "./style.css": "./style.css"
+    "./solid": {
+      "types": "./dist/solid.d.ts",
+      "import": "./dist/solid.js"
+    },
+    "./svelte": {
+      "types": "./dist/svelte.d.ts",
+      "import": "./dist/svelte.js"
+    },
+    "./style.css": {
+      "types": "./style.css.d.ts",
+      "default": "./style.css"
+    }
   },
   "types": "./dist/index.d.ts",
   "peerDependencies": {
     "react": ">=18 <20",
+    "solid-js": ">=1.8 <2",
+    "svelte": ">=4 <6",
     "vue": ">=3.4 <4"
   },
   "peerDependenciesMeta": {
@@ -42,17 +56,29 @@
     },
     "vue": {
       "optional": true
+    },
+    "solid-js": {
+      "optional": true
+    },
+    "svelte": {
+      "optional": true
     }
   },
   "scripts": {
+    "prepublishOnly": "npm run build",
     "build": "tsc -p tsconfig.json",
     "check": "tsc -p tsconfig.json --noEmit",
-    "pack:check": "npm pack --dry-run"
+    "pack:check": "npm pack --dry-run",
+    "test": "vitest run"
   },
   "devDependencies": {
     "@types/react": "^19.2.17",
+    "happy-dom": "^20.10.2",
     "react": "^19.2.7",
+    "solid-js": "^1.9.13",
+    "svelte": "^5.56.3",
     "typescript": "^5.8.3",
+    "vitest": "^4.1.8",
     "vue": "^3.5.35"
   }
 }

package/style.css.d.ts

@@ -0,0 +1,2 @@
+declare const stylesheet: string;
+export default stylesheet;