slot-text 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Daniel Belyi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,156 @@
+# slot-text
+
+Dependency-free text roll animation for tiny, tactile UI labels.
+
+![slot-text usage card](./assets/usage.svg)
+
+## Install
+
+```bash
+npm install slot-text
+```
+
+## Use
+
+### Vanilla
+
+```ts
+import "slot-text/style.css";
+import { slotText, chromatic } from "slot-text";
+
+const label = slotText(document.querySelector("#copy")!, "Copy");
+
+label.set("Copied", {
+  direction: "up",
+  color: chromatic(),
+});
+```
+
+### 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,
+      }}
+    />
+  );
+}
+```
+
+### 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" />
+</template>
+```
+
+## API
+
+Vanilla controller:
+
+```ts
+const label = slotText(element, "Copy", options);
+
+label.set("Copied");
+label.set("Copy", { direction: "down" });
+label.destroy();
+```
+
+Framework components:
+
+```ts
+import { SlotText as ReactSlotText } from "slot-text/react";
+import { SlotText as VueSlotText } from "slot-text/vue";
+```
+
+Low-level helpers:
+
+```ts
+import {
+  buildSlotText,
+  animateSlotText,
+  chromatic,
+} from "slot-text";
+```
+
+## Options
+
+```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;
+};
+```
+
+Defaults are tuned for a soft, springy roll:
+
+```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,
+}
+```
+
+## Example
+
+```html
+<button>
+  <span id="copy-label"></span>
+</button>
+
+<script type="module">
+  import "slot-text/style.css";
+  import { slotText } from "slot-text";
+
+  const label = slotText(document.querySelector("#copy-label"), "Copy");
+
+  document.querySelector("button").addEventListener("click", () => {
+    label.set("Copied", { direction: "up", skipUnchanged: false });
+    window.setTimeout(() => label.set("Copy"), 1400);
+  });
+</script>
+```
+
+## 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.
+- Import the CSS once before using the animation.

package/assets/usage.svg

@@ -0,0 +1,32 @@
+<svg width="920" height="520" viewBox="0 0 920 520" fill="none" xmlns="http://www.w3.org/2000/svg" role="img" aria-labelledby="title desc">
+  <title id="title">slot-text usage example</title>
+  <desc id="desc">A visual code card showing how to import and use slot-text.</desc>
+  <rect width="920" height="520" rx="28" fill="#0E1116"/>
+  <rect x="34" y="34" width="852" height="452" rx="18" fill="#151A22" stroke="#2A3342"/>
+  <circle cx="66" cy="66" r="7" fill="#FF6B6B"/>
+  <circle cx="90" cy="66" r="7" fill="#FFD166"/>
+  <circle cx="114" cy="66" r="7" fill="#5CD85C"/>
+  <text x="58" y="118" fill="#7D8A9B" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" font-size="18">npm install slot-text</text>
+  <rect x="58" y="146" width="804" height="272" rx="14" fill="#0B0F14" stroke="#252D3A"/>
+  <text x="86" y="194" fill="#7D8A9B" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" font-size="18">import</text>
+  <text x="159" y="194" fill="#F5D76E" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" font-size="18">"slot-text/style.css"</text>
+  <text x="379" y="194" fill="#B9C4D0" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" font-size="18">;</text>
+  <text x="86" y="232" fill="#7D8A9B" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" font-size="18">import</text>
+  <text x="159" y="232" fill="#B9C4D0" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" font-size="18"> { slotText, chromatic } </text>
+  <text x="437" y="232" fill="#7D8A9B" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" font-size="18">from</text>
+  <text x="492" y="232" fill="#F5D76E" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" font-size="18"> "slot-text"</text>
+  <text x="625" y="232" fill="#B9C4D0" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" font-size="18">;</text>
+  <text x="86" y="294" fill="#7D8A9B" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" font-size="18">const</text>
+  <text x="148" y="294" fill="#8ED3FF" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" font-size="18"> label</text>
+  <text x="225" y="294" fill="#B9C4D0" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" font-size="18"> = slotText(copyEl, </text>
+  <text x="431" y="294" fill="#F5D76E" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" font-size="18">"Copy"</text>
+  <text x="499" y="294" fill="#B9C4D0" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" font-size="18">);</text>
+  <text x="86" y="356" fill="#8ED3FF" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" font-size="18">label</text>
+  <text x="142" y="356" fill="#B9C4D0" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" font-size="18">.set(</text>
+  <text x="203" y="356" fill="#F5D76E" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" font-size="18">"Copied"</text>
+  <text x="289" y="356" fill="#B9C4D0" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" font-size="18">, { direction: </text>
+  <text x="467" y="356" fill="#F5D76E" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" font-size="18">"up"</text>
+  <text x="516" y="356" fill="#B9C4D0" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" font-size="18">, color: chromatic() });</text>
+  <rect x="58" y="438" width="160" height="34" rx="17" fill="#EAF2FF"/>
+  <text x="82" y="461" fill="#0E1116" font-family="Inter, ui-sans-serif, system-ui, sans-serif" font-size="16" font-weight="700">Copy → Copied</text>
+</svg>

package/dist/index.d.ts

@@ -0,0 +1,17 @@
+export { animateSlotText, buildSlotText, chromatic, clearSlotText, type ChromaticOptions, type SlotOptions, } from "./slotText";
+import { type SlotOptions } from "./slotText";
+export interface SlotTextController {
+    readonly element: HTMLElement;
+    readonly value: string;
+    set(text: string, options?: SlotOptions): void;
+    destroy(): void;
+}
+/**
+ * Create a text-roll controller for one element.
+ *
+ * Import `slot-text/style.css` once in your app, then call:
+ *
+ *   const label = slotText(buttonLabel, "Copy");
+ *   label.set("Copied", { direction: "up" });
+ */
+export declare function slotText(element: HTMLElement, initialText: string, options?: SlotOptions): SlotTextController;

package/dist/index.js

@@ -0,0 +1,27 @@
+export { animateSlotText, buildSlotText, chromatic, clearSlotText, } from "./slotText";
+import { animateSlotText, buildSlotText, clearSlotText, } from "./slotText";
+/**
+ * Create a text-roll controller for one element.
+ *
+ * Import `slot-text/style.css` once in your app, then call:
+ *
+ *   const label = slotText(buttonLabel, "Copy");
+ *   label.set("Copied", { direction: "up" });
+ */
+export function slotText(element, initialText, options = {}) {
+    let value = initialText;
+    buildSlotText(element, initialText);
+    return {
+        element,
+        get value() {
+            return value;
+        },
+        set(text, nextOptions = {}) {
+            value = text;
+            animateSlotText(element, text, { ...options, ...nextOptions });
+        },
+        destroy() {
+            clearSlotText(element, value);
+        },
+    };
+}

package/dist/react.d.ts

@@ -0,0 +1,7 @@
+import { type HTMLAttributes } from "react";
+import { type SlotOptions } from "./slotText";
+export interface SlotTextProps extends Omit<HTMLAttributes<HTMLSpanElement>, "children"> {
+    text: string;
+    options?: SlotOptions;
+}
+export declare const SlotText: import("react").ForwardRefExoticComponent<SlotTextProps & import("react").RefAttributes<HTMLSpanElement>>;

package/dist/react.js

@@ -0,0 +1,40 @@
+import { createElement, forwardRef, useEffect, useImperativeHandle, useRef, } from "react";
+import { animateSlotText, buildSlotText, clearSlotText, } from "./slotText";
+export const SlotText = forwardRef(({ text, options, "aria-label": ariaLabel, ...props }, forwardedRef) => {
+    const elementRef = useRef(null);
+    const mountedRef = useRef(false);
+    const firstTextEffectRef = useRef(true);
+    const optionsRef = useRef(options);
+    useImperativeHandle(forwardedRef, () => elementRef.current, []);
+    useEffect(() => {
+        optionsRef.current = options;
+    }, [options]);
+    useEffect(() => {
+        const element = elementRef.current;
+        if (!element)
+            return;
+        buildSlotText(element, text);
+        mountedRef.current = true;
+        return () => {
+            clearSlotText(element);
+            mountedRef.current = false;
+            firstTextEffectRef.current = true;
+        };
+    }, []);
+    useEffect(() => {
+        const element = elementRef.current;
+        if (!element || !mountedRef.current)
+            return;
+        if (firstTextEffectRef.current) {
+            firstTextEffectRef.current = false;
+            return;
+        }
+        animateSlotText(element, text, optionsRef.current);
+    }, [text]);
+    return createElement("span", {
+        ...props,
+        "aria-label": ariaLabel ?? text,
+        ref: elementRef,
+    });
+});
+SlotText.displayName = "SlotText";

package/dist/slotText.d.ts

@@ -0,0 +1,64 @@
+/**
+ * slotText - a dependency-free "text roll" animation.
+ *
+ * Adapted from motion-primitives' TextRoll (vertical-slide variant): each
+ * character sits in its own clipped cell and changes by sliding. The new
+ * glyph enters from one side while the old glyph slides out the other, with
+ * the incoming glyph chasing the outgoing one by a stagger step. Pure
+ * transform/transition, GPU-composited, with a springy overshoot easing, so
+ * every letter lands with a little bounce.
+ *
+ *   buildSlotText(el, "Copy");                       // initialise
+ *   animateSlotText(el, "Copied", { direction: "up" }); // animate to new text
+ */
+export interface SlotOptions {
+    /** "down" rolls glyphs downward (enter from top); "up" rolls upward. */
+    direction?: "up" | "down";
+    /** Per-character stagger in ms (default 45). */
+    stagger?: number;
+    /** Slide duration per character in ms (default 300). */
+    duration?: number;
+    /** How long the incoming glyph trails the outgoing one, in ms (default 50). */
+    exitOffset?: number;
+    /** Easing — defaults to a springy, overshooting "back" curve. */
+    easing?: string;
+    /**
+     * Per-letter personality: 0 = every glyph lands identically, 1 = lots of
+     * individual variation in speed and a little tilt-wobble as each settles.
+     * Default 0.6.
+     */
+    bounce?: number;
+    /**
+     * Chromatic flash: each incoming glyph rolls in tinted, then fades to its
+     * resting color once it lands. Pass a single CSS color for a flat tint, or a
+     * function `(index, total) => color` to give every glyph its own hue. That's
+     * what produces the spectrum/rainbow sweep across the line. Omit for no flash.
+     */
+    color?: string | ((index: number, total: number) => string);
+    /** How long the chromatic tint takes to fade back to rest, in ms (default 280). */
+    colorFade?: number;
+    /**
+     * Keep characters that are identical at the same index static. Ideal for
+     * short aligned labels (Copy to Copied). Turn off when the shared parts of the
+     * two strings are misaligned (different lengths) so the whole line rolls
+     * uniformly instead of leaving stray letters frozen.
+     */
+    skipUnchanged?: boolean;
+}
+export interface ChromaticOptions {
+    from?: number;
+    spread?: number;
+    saturation?: number;
+    lightness?: number;
+}
+/**
+ * Build a `color` function that sweeps the hue across the line, giving every
+ * glyph its own color so the roll lands as a chromatic spectrum.
+ *
+ *   animateSlotText(el, txt, { color: chromatic() });            // full rainbow
+ *   animateSlotText(el, txt, { color: chromatic({ from: 18 }) }); // start gold
+ */
+export declare function chromatic({ from, spread, saturation, lightness, }?: ChromaticOptions): (index: number, total: number) => string;
+export declare function buildSlotText(container: HTMLElement, text: string): void;
+export declare function animateSlotText(container: HTMLElement, toText: string, options?: SlotOptions): void;
+export declare function clearSlotText(container: HTMLElement, text?: string): void;

package/dist/slotText.js

@@ -0,0 +1,186 @@
+/**
+ * slotText - a dependency-free "text roll" animation.
+ *
+ * Adapted from motion-primitives' TextRoll (vertical-slide variant): each
+ * character sits in its own clipped cell and changes by sliding. The new
+ * glyph enters from one side while the old glyph slides out the other, with
+ * the incoming glyph chasing the outgoing one by a stagger step. Pure
+ * transform/transition, GPU-composited, with a springy overshoot easing, so
+ * every letter lands with a little bounce.
+ *
+ *   buildSlotText(el, "Copy");                       // initialise
+ *   animateSlotText(el, "Copied", { direction: "up" }); // animate to new text
+ */
+const DEFAULTS = {
+    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,
+};
+const NBSP = "\u00A0";
+const glyph = (char) => (char === " " ? NBSP : char);
+/**
+ * Build a `color` function that sweeps the hue across the line, giving every
+ * glyph its own color so the roll lands as a chromatic spectrum.
+ *
+ *   animateSlotText(el, txt, { color: chromatic() });            // full rainbow
+ *   animateSlotText(el, txt, { color: chromatic({ from: 18 }) }); // start gold
+ */
+export function chromatic({ from = 0, spread = 320, saturation = 92, lightness = 60, } = {}) {
+    return (index, total) => {
+        const t = total <= 1 ? 0 : index / (total - 1);
+        return `hsl(${(from + t * spread) % 360} ${saturation}% ${lightness}%)`;
+    };
+}
+const states = new WeakMap();
+/** Cancel any running animation on a container and snap it to its target text. */
+function settle(container) {
+    const state = states.get(container);
+    if (!state)
+        return;
+    state.timers.forEach((t) => window.clearTimeout(t));
+    states.delete(container);
+    // Rebuild a pristine DOM at the text the interrupted roll was heading toward,
+    // so the next animation starts from a clean, non-overlapping baseline.
+    buildSlotText(container, state.target);
+}
+function makeFace(char) {
+    const face = document.createElement("span");
+    face.className = "char-face";
+    face.textContent = glyph(char);
+    return face;
+}
+function buildSlot(char) {
+    const slot = document.createElement("span");
+    slot.className = "char-slot";
+    slot.dataset.char = char;
+    // Invisible sizer keeps the cell exactly the width/height of its glyph, so
+    // the absolutely-positioned animating faces never reflow the line.
+    const sizer = document.createElement("span");
+    sizer.className = "char-sizer";
+    sizer.textContent = glyph(char);
+    slot.append(sizer, makeFace(char));
+    return slot;
+}
+export function buildSlotText(container, text) {
+    container.classList.add("slot-text");
+    container.replaceChildren(...Array.from(text, buildSlot));
+}
+export function animateSlotText(container, toText, options = {}) {
+    const { direction, stagger, duration, exitOffset, easing, bounce, color, colorFade, skipUnchanged, } = {
+        ...DEFAULTS,
+        ...options,
+    };
+    // Interrupt: if a previous roll is still running, fast-forward it to its
+    // target and tear down its timers before we start fresh. This is what kills
+    // the "switch bun→npm mid-animation" glitch.
+    settle(container);
+    // First run / empty container → just build it.
+    if (!container.querySelector(".char-slot")) {
+        buildSlotText(container, toText);
+        return;
+    }
+    const slots = Array.from(container.querySelectorAll(".char-slot"));
+    const fromText = slots.map((s) => s.dataset.char ?? "").join("");
+    const maxLen = Math.max(fromText.length, toText.length);
+    // Whole-pixel slide distance = one cell height, so glyphs clip cleanly.
+    // If layout has not produced dimensions yet, fall back to line-height/font-size
+    // so the text still rolls instead of swapping in place.
+    const sample = slots.find((s) => (s.dataset.char ?? "") !== "") ?? slots[0];
+    const cs = getComputedStyle(container);
+    const H = Math.round(sample?.getBoundingClientRect().height ||
+        sample?.offsetHeight ||
+        container.getBoundingClientRect().height ||
+        parseFloat(cs.lineHeight) ||
+        0) || Math.round(parseFloat(cs.fontSize) * 1.3) || 18;
+    // Resting color to settle the chromatic flash back to.
+    const restColor = color ? cs.color : "";
+    // Pre-create any extra cells up front so the row never reflows mid-roll.
+    for (let i = slots.length; i < maxLen; i++) {
+        const slot = buildSlot("");
+        container.appendChild(slot);
+        slots.push(slot);
+    }
+    const timers = [];
+    const state = { timers, target: toText };
+    states.set(container, state);
+    // down: new enters from above (-H to 0), old exits below (0 to +H)
+    // up:   new enters from below (+H to 0), old exits above (0 to -H)
+    const outY = direction === "down" ? H : -H;
+    const inStart = direction === "down" ? -H : H;
+    // A tiny deterministic-feeling jitter in [-1, 1] per character. Scaled by
+    // `bounce` it gives each glyph its own speed and a little tilt-wobble, so the
+    // line does not land as one rigid block. Every letter has some personality.
+    const wobble = (i, salt) => {
+        const n = Math.sin((i + 1) * 12.9898 + salt * 78.233) * 43758.5453;
+        return (n - Math.floor(n)) * 2 - 1;
+    };
+    // Track the slowest letter so the safety-net snap waits for everyone.
+    let maxEnd = 0;
+    for (let i = 0; i < maxLen; i++) {
+        const fromChar = fromText[i] || "";
+        const toChar = toText[i] || "";
+        if (fromChar === toChar && (skipUnchanged || fromChar === ""))
+            continue;
+        const slot = slots[i];
+        const sizer = slot.querySelector(".char-sizer");
+        const oldFace = slot.querySelector(".char-face");
+        sizer.textContent = glyph(toChar); // resize the cell to the new glyph
+        const tint = typeof color === "function" ? color(i, maxLen) : color;
+        // Per-letter personality: vary the speed, the stagger and a starting tilt
+        // that springs back to upright as the glyph settles.
+        const d = Math.round(duration * (1 + bounce * 0.45 * wobble(i, 1)));
+        const base = Math.round(i * stagger * (1 + bounce * 0.25 * wobble(i, 2)));
+        const tilt = (bounce * 9 * wobble(i, 3)).toFixed(2);
+        const rollTrans = `transform ${d}ms ${easing}`;
+        const trans = color ? `${rollTrans}, color ${colorFade}ms linear ${d}ms` : rollTrans;
+        const newFace = makeFace(toChar);
+        newFace.style.transformOrigin = "50% 50%";
+        newFace.style.transform = `translateY(${inStart}px) rotate(${tilt}deg)`;
+        if (tint)
+            newFace.style.color = tint;
+        slot.appendChild(newFace);
+        void slot.offsetWidth; // commit start transforms
+        maxEnd = Math.max(maxEnd, base + exitOffset + d + (color ? colorFade : 0));
+        // Outgoing glyph slides away first (with its own little counter-tilt).
+        if (oldFace) {
+            timers.push(window.setTimeout(() => {
+                oldFace.style.transition = rollTrans;
+                oldFace.style.transform = `translateY(${outY}px) rotate(${-Number(tilt)}deg)`;
+            }, base));
+        }
+        // Incoming glyph chases it in (and, if tinted, fades to rest afterwards).
+        timers.push(window.setTimeout(() => {
+            newFace.style.transition = trans;
+            newFace.style.transform = "translateY(0) rotate(0deg)";
+            if (color)
+                newFace.style.color = restColor;
+            const done = (e) => {
+                if (e.propertyName !== "transform")
+                    return; // ignore the colour fade
+                newFace.removeEventListener("transitionend", done);
+                slot.dataset.char = toChar;
+                slot.querySelectorAll(".char-face").forEach((f) => {
+                    if (f !== newFace)
+                        f.remove();
+                });
+            };
+            newFace.addEventListener("transitionend", done);
+        }, base + exitOffset));
+    }
+    // Safety net: snap to a pristine DOM once the slowest letter has settled.
+    const total = maxEnd + 80;
+    timers.push(window.setTimeout(() => {
+        states.delete(container);
+        buildSlotText(container, toText);
+    }, total));
+}
+export function clearSlotText(container, text = "") {
+    settle(container);
+    container.classList.remove("slot-text");
+    container.textContent = text;
+}

package/dist/vue.d.ts

@@ -0,0 +1,25 @@
+import { type PropType } from "vue";
+import { type SlotOptions } from "./slotText";
+export declare const SlotText: import("vue").DefineComponent<import("vue").ExtractPropTypes<{
+    text: {
+        type: StringConstructor;
+        required: true;
+    };
+    options: {
+        type: PropType<SlotOptions>;
+        default: undefined;
+    };
+}>, () => import("vue").VNode<import("vue").RendererNode, import("vue").RendererElement, {
+    [key: string]: any;
+}>, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<import("vue").ExtractPropTypes<{
+    text: {
+        type: StringConstructor;
+        required: true;
+    };
+    options: {
+        type: PropType<SlotOptions>;
+        default: undefined;
+    };
+}>> & Readonly<{}>, {
+    options: SlotOptions;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;

package/dist/vue.js

@@ -0,0 +1,42 @@
+import { defineComponent, h, onBeforeUnmount, onMounted, ref, watch, } from "vue";
+import { animateSlotText, buildSlotText, clearSlotText, } from "./slotText";
+export const SlotText = defineComponent({
+    name: "SlotText",
+    inheritAttrs: false,
+    props: {
+        text: {
+            type: String,
+            required: true,
+        },
+        options: {
+            type: Object,
+            default: undefined,
+        },
+    },
+    setup(props, { attrs }) {
+        const element = ref(null);
+        let mounted = false;
+        onMounted(() => {
+            if (!element.value)
+                return;
+            buildSlotText(element.value, props.text);
+            mounted = true;
+        });
+        watch(() => props.text, (text) => {
+            if (!element.value || !mounted)
+                return;
+            animateSlotText(element.value, text, props.options);
+        });
+        onBeforeUnmount(() => {
+            if (!element.value)
+                return;
+            clearSlotText(element.value);
+            mounted = false;
+        });
+        return () => h("span", {
+            ...attrs,
+            "aria-label": attrs["aria-label"] ?? props.text,
+            ref: element,
+        });
+    },
+});

package/examples/basic/index.html

@@ -0,0 +1,52 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>slot-text example</title>
+    <link rel="stylesheet" href="../../style.css" />
+    <style>
+      body {
+        min-height: 100vh;
+        margin: 0;
+        display: grid;
+        place-items: center;
+        font: 600 18px/1.2 ui-sans-serif, system-ui, sans-serif;
+        background: #0e1116;
+        color: #edf2f7;
+      }
+
+      button {
+        border: 1px solid #2a3342;
+        border-radius: 10px;
+        padding: 12px 18px;
+        background: #151a22;
+        color: inherit;
+        font: inherit;
+        cursor: pointer;
+      }
+    </style>
+  </head>
+  <body>
+    <button type="button"><span id="copy-label"></span></button>
+
+    <script type="module">
+      import { slotText, chromatic } from "../../dist/index.js";
+
+      const button = document.querySelector("button");
+      const label = slotText(document.querySelector("#copy-label"), "Copy");
+
+      button.addEventListener("click", () => {
+        label.set("Copied", {
+          direction: "up",
+          skipUnchanged: false,
+          color: chromatic({ from: 190 }),
+        });
+
+        window.setTimeout(() => {
+          label.set("Copy", { direction: "down", skipUnchanged: false });
+        }, 1400);
+      });
+    </script>
+  </body>
+</html>

package/examples/react.tsx

@@ -0,0 +1,27 @@
+import "slot-text/style.css";
+import { useState } from "react";
+import { chromatic } from "slot-text";
+import { SlotText } from "slot-text/react";
+
+export function CopyButton() {
+  const [copied, setCopied] = useState(false);
+
+  return (
+    <button
+      type="button"
+      onClick={() => {
+        setCopied(true);
+        window.setTimeout(() => setCopied(false), 1400);
+      }}
+    >
+      <SlotText
+        text={copied ? "Copied" : "Copy"}
+        options={{
+          direction: copied ? "up" : "down",
+          skipUnchanged: false,
+          color: copied ? chromatic({ from: 190 }) : undefined,
+        }}
+      />
+    </button>
+  );
+}

package/examples/vue.vue

@@ -0,0 +1,28 @@
+<script setup lang="ts">
+import "slot-text/style.css";
+import { ref } from "vue";
+import { chromatic } from "slot-text";
+import { SlotText } from "slot-text/vue";
+
+const copied = ref(false);
+
+function copy() {
+  copied.value = true;
+  window.setTimeout(() => {
+    copied.value = false;
+  }, 1400);
+}
+</script>
+
+<template>
+  <button type="button" @click="copy">
+    <SlotText
+      :text="copied ? 'Copied' : 'Copy'"
+      :options="{
+        direction: copied ? 'up' : 'down',
+        skipUnchanged: false,
+        color: copied ? chromatic({ from: 190 }) : undefined,
+      }"
+    />
+  </button>
+</template>

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "slot-text",
+  "version": "0.1.0",
+  "description": "Dependency-free text roll animation for tiny, tactile UI labels.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Daniel Belyi",
+  "sideEffects": [
+    "./style.css"
+  ],
+  "files": [
+    "assets",
+    "dist",
+    "examples",
+    "style.css",
+    "README.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./react": {
+      "types": "./dist/react.d.ts",
+      "import": "./dist/react.js"
+    },
+    "./vue": {
+      "types": "./dist/vue.d.ts",
+      "import": "./dist/vue.js"
+    },
+    "./style.css": "./style.css"
+  },
+  "types": "./dist/index.d.ts",
+  "peerDependencies": {
+    "react": ">=18 <20",
+    "vue": ">=3.4 <4"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    },
+    "vue": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "check": "tsc -p tsconfig.json --noEmit",
+    "pack:check": "npm pack --dry-run"
+  },
+  "devDependencies": {
+    "@types/react": "^19.2.17",
+    "react": "^19.2.7",
+    "typescript": "^5.8.3",
+    "vue": "^3.5.35"
+  }
+}

package/style.css

@@ -0,0 +1,28 @@
+.slot-text {
+  display: inline-flex;
+  white-space: pre;
+}
+
+.char-slot {
+  position: relative;
+  display: inline-flex;
+  justify-content: center;
+  overflow: hidden;
+  line-height: 1.3;
+  vertical-align: bottom;
+}
+
+.char-sizer {
+  visibility: hidden;
+  white-space: pre;
+}
+
+.char-face {
+  position: absolute;
+  inset: 0;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  white-space: pre;
+  will-change: transform;
+}