slot-text 0.1.1 → 0.2.2

package/README.md

@@ -76,9 +76,23 @@ 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.
+
+```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
@@ -109,9 +123,15 @@ type SlotOptions = {
   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.
+
 Defaults are tuned for a soft, springy roll:
 
 ```ts
@@ -124,6 +144,7 @@ Defaults are tuned for a soft, springy roll:
   bounce: 0.6,
   colorFade: 280,
   skipUnchanged: true,
+  interrupt: true,
 }
 ```
 
@@ -136,13 +157,15 @@ Defaults are tuned for a soft, springy roll:
 
 <script type="module">
   import "slot-text/style.css";
-  import { slotText } from "slot-text";
+  import { slotText, chromatic } 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);
+    label.flash("Copied", {
+      enter: { direction: "up", skipUnchanged: false, color: chromatic() },
+      exit: { direction: "down", skipUnchanged: false },
+    });
   });
 </script>
 ```

package/dist/index.d.ts

@@ -1,9 +1,25 @@
-export { animateSlotText, buildSlotText, chromatic, clearSlotText, type ChromaticOptions, type SlotOptions, } from "./slotText";
-import { type SlotOptions } from "./slotText";
+export { animateSlotText, buildSlotText, chromatic, clearSlotText, type ChromaticOptions, type SlotOptions, } from "./slotText.js";
+import { type SlotOptions } from "./slotText.js";
+export interface FlashOptions {
+    /** How long the flash text stays before rolling back, in ms (default 1400). */
+    revertAfter?: number;
+    /** Roll options for the flash text rolling in. */
+    enter?: SlotOptions;
+    /** Roll options for the original text rolling back. */
+    exit?: SlotOptions;
+}
 export interface SlotTextController {
     readonly element: HTMLElement;
+    /** The text currently displayed (the flash text while a flash is showing). */
     readonly value: string;
+    /** Roll to new text. Cancels any pending flash revert. */
     set(text: string, options?: SlotOptions): void;
+    /**
+     * Roll to temporary text, then roll back automatically — the classic
+     * Copy → Copied → Copy button in one call. Spam-safe: repeat flashes restart
+     * the revert timer instead of queuing extra rolls.
+     */
+    flash(text: string, options?: FlashOptions): void;
     destroy(): void;
 }
 /**
@@ -13,5 +29,6 @@ export interface SlotTextController {
  *
  *   const label = slotText(buttonLabel, "Copy");
  *   label.set("Copied", { direction: "up" });
+ *   label.flash("Copied", { revertAfter: 1400 }); // auto-reverts to "Copy"
  */
 export declare function slotText(element: HTMLElement, initialText: string, options?: SlotOptions): SlotTextController;

package/dist/index.js

@@ -1,5 +1,5 @@
-export { animateSlotText, buildSlotText, chromatic, clearSlotText, } from "./slotText";
-import { animateSlotText, buildSlotText, clearSlotText, } from "./slotText";
+export { animateSlotText, buildSlotText, chromatic, clearSlotText, } from "./slotText.js";
+import { animateSlotText, buildSlotText, clearSlotText, } from "./slotText.js";
 /**
  * Create a text-roll controller for one element.
  *
@@ -7,9 +7,12 @@ import { animateSlotText, buildSlotText, clearSlotText, } from "./slotText";
  *
  *   const label = slotText(buttonLabel, "Copy");
  *   label.set("Copied", { direction: "up" });
+ *   label.flash("Copied", { revertAfter: 1400 }); // auto-reverts to "Copy"
  */
 export function slotText(element, initialText, options = {}) {
     let value = initialText;
+    let revertTimeout;
+    let restingText;
     buildSlotText(element, initialText);
     return {
         element,
@@ -17,10 +20,42 @@ export function slotText(element, initialText, options = {}) {
             return value;
         },
         set(text, nextOptions = {}) {
+            // An explicit set wins over a pending flash revert.
+            clearTimeout(revertTimeout);
+            restingText = undefined;
             value = text;
             animateSlotText(element, text, { ...options, ...nextOptions });
         },
+        flash(text, { revertAfter = 1400, enter, exit } = {}) {
+            // Capture the resting text only on the first flash of a burst, so a
+            // flash-during-flash still reverts to the original label.
+            if (restingText === undefined) {
+                restingText = value;
+            }
+            // Flashes default to non-interrupting rolls: spam-friendly, no mid-roll
+            // cutoffs. Callers can still override via `enter`/`exit`.
+            value = text;
+            animateSlotText(element, text, {
+                ...options,
+                interrupt: false,
+                ...enter,
+            });
+            // Restart the revert timer: one revert per burst, after the last flash.
+            clearTimeout(revertTimeout);
+            revertTimeout = window.setTimeout(() => {
+                const back = restingText;
+                restingText = undefined;
+                revertTimeout = undefined;
+                value = back;
+                animateSlotText(element, back, {
+                    ...options,
+                    interrupt: false,
+                    ...exit,
+                });
+            }, revertAfter);
+        },
         destroy() {
+            clearTimeout(revertTimeout);
             clearSlotText(element, value);
         },
     };

package/dist/react.d.ts

@@ -1,5 +1,5 @@
 import { type HTMLAttributes } from "react";
-import { type SlotOptions } from "./slotText";
+import { type SlotOptions } from "./slotText.js";
 export interface SlotTextProps extends Omit<HTMLAttributes<HTMLSpanElement>, "children"> {
     text: string;
     options?: SlotOptions;

package/dist/react.js

@@ -1,5 +1,5 @@
 import { createElement, forwardRef, useEffect, useImperativeHandle, useRef, } from "react";
-import { animateSlotText, buildSlotText, clearSlotText, } from "./slotText";
+import { animateSlotText, buildSlotText, clearSlotText, } from "./slotText.js";
 export const SlotText = forwardRef(({ text, options, "aria-label": ariaLabel, ...props }, forwardedRef) => {
     const elementRef = useRef(null);
     const mountedRef = useRef(false);

package/dist/slotText.d.ts

@@ -44,6 +44,13 @@ export interface SlotOptions {
      * uniformly instead of leaving stray letters frozen.
      */
     skipUnchanged?: boolean;
+    /**
+     * true (default): a new call interrupts any roll in flight, snapping it to
+     * its target before starting fresh. false: the current roll finishes and the
+     * latest call made mid-roll plays after it lands; calls targeting the text
+     * already displayed are dropped. Ideal for spam-prone triggers like buttons.
+     */
+    interrupt?: boolean;
 }
 export interface ChromaticOptions {
     from?: number;

package/dist/slotText.js

@@ -20,6 +20,7 @@ const DEFAULTS = {
     bounce: 0.6,
     colorFade: 280,
     skipUnchanged: true,
+    interrupt: true,
 };
 const NBSP = "\u00A0";
 const glyph = (char) => (char === " " ? NBSP : char);
@@ -71,10 +72,20 @@ export function buildSlotText(container, text) {
     container.replaceChildren(...Array.from(text, buildSlot));
 }
 export function animateSlotText(container, toText, options = {}) {
-    const { direction, stagger, duration, exitOffset, easing, bounce, color, colorFade, skipUnchanged, } = {
+    const { direction, stagger, duration, exitOffset, easing, bounce, color, colorFade, skipUnchanged, interrupt, } = {
         ...DEFAULTS,
         ...options,
     };
+    // Non-interrupting mode: if a roll is already in flight, let it finish and
+    // remember this request instead. Only the latest request survives, so spam
+    // taps coalesce into a single follow-up roll once the current one lands.
+    const running = states.get(container);
+    if (running && !interrupt) {
+        if (toText !== running.target) {
+            running.pending = { text: toText, options };
+        }
+        return;
+    }
     // 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.
@@ -86,6 +97,10 @@ export function animateSlotText(container, toText, options = {}) {
     }
     const slots = Array.from(container.querySelectorAll(".char-slot"));
     const fromText = slots.map((s) => s.dataset.char ?? "").join("");
+    // Non-interrupting mode also drops rolls to the text already on screen, so
+    // repeated triggers do not visibly re-roll an unchanged label.
+    if (!interrupt && fromText === toText)
+        return;
     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
@@ -98,7 +113,9 @@ export function animateSlotText(container, toText, options = {}) {
         sample?.offsetHeight ||
         container.getBoundingClientRect().height ||
         parseFloat(cs.lineHeight) ||
-        0) || Math.ceil(parseFloat(cs.fontSize) * 1.3) || 18;
+        0) ||
+        Math.ceil(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.
@@ -160,7 +177,9 @@ export function animateSlotText(container, toText, options = {}) {
         const base = Math.round(staggerIndex * stagger * (1 + bounce * 0.25 * wobble(i, 2)));
         const tilt = (bounce * 5 * wobble(i, 3)).toFixed(2);
         const rollTrans = `transform ${d}ms ${easing}`;
-        const trans = color ? `${rollTrans}, color ${colorFade}ms linear ${d}ms` : rollTrans;
+        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)`;
@@ -228,10 +247,16 @@ export function animateSlotText(container, toText, options = {}) {
         }, base + exitOffset));
     }
     // Safety net: snap to a pristine DOM once the slowest letter has settled.
+    // If a non-interrupting call was deferred mid-roll, replay it now — it runs
+    // as a fresh roll from this clean baseline.
     const total = maxEnd + 80;
     timers.push(window.setTimeout(() => {
+        const pending = state.pending;
         states.delete(container);
         buildSlotText(container, toText);
+        if (pending) {
+            animateSlotText(container, pending.text, pending.options);
+        }
     }, total));
 }
 export function clearSlotText(container, text = "") {

package/dist/vue.d.ts

@@ -1,5 +1,5 @@
 import { type PropType } from "vue";
-import { type SlotOptions } from "./slotText";
+import { type SlotOptions } from "./slotText.js";
 export declare const SlotText: import("vue").DefineComponent<import("vue").ExtractPropTypes<{
     text: {
         type: StringConstructor;

package/dist/vue.js

@@ -1,5 +1,5 @@
 import { defineComponent, h, onBeforeUnmount, onMounted, ref, watch, } from "vue";
-import { animateSlotText, buildSlotText, clearSlotText, } from "./slotText";
+import { animateSlotText, buildSlotText, clearSlotText, } from "./slotText.js";
 export const SlotText = defineComponent({
     name: "SlotText",
     inheritAttrs: false,

package/examples/basic/index.html

@@ -37,15 +37,18 @@
       const label = slotText(document.querySelector("#copy-label"), "Copy");
 
       button.addEventListener("click", () => {
-        label.set("Copied", {
-          direction: "up",
-          skipUnchanged: false,
-          color: chromatic({ from: 190 }),
+        label.flash("Copied", {
+          enter: {
+            direction: "up",
+            skipUnchanged: false,
+            color: chromatic({ from: 190 }),
+          },
+          exit: {
+            direction: "down",
+            skipUnchanged: false,
+            color: chromatic({ from: 190 }),
+          },
         });
-
-        window.setTimeout(() => {
-          label.set("Copy", { direction: "down", skipUnchanged: false });
-        }, 1400);
       });
     </script>
   </body>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "slot-text",
-  "version": "0.1.1",
+  "version": "0.2.2",
   "description": "Dependency-free text roll animation for tiny, tactile UI labels.",
   "type": "module",
   "license": "MIT",

package/style.css

@@ -6,6 +6,11 @@
 .char-slot {
   position: relative;
   display: inline-flex;
+  /* Cells must never flex-shrink. When a cell's overflow stops being visible
+     (e.g. .is-resizing), its automatic minimum size drops to 0, and a
+     width-constrained line would crush those cells into overlapping slivers
+     instead of letting the row overflow like it does at rest. */
+  flex: none;
   justify-content: center;
   /* Clip only vertically: the roll needs a top/bottom mask, but glyph side
      bearings, kerning overhang and the settle tilt must stay visible so