@enigmax/primitives 0.4.0 → 0.5.0

package/dist/{chunk-W2DRHYC2.js → chunk-2DVVWPHM.js}

@@ -11,7 +11,7 @@ var DEFAULTS = {
   reverse: false,
   vertical: false,
   draggable: true,
-  hoverScale: 1,
+  hover: "off",
   decay: DEFAULT_DECAY,
   manageStyles: true,
   copies: "clone"
@@ -37,10 +37,17 @@ function createMarquee(lane, track, options = {}) {
   let lastTouchAt = 0;
   const motionQuery = typeof window.matchMedia === "function" ? window.matchMedia("(prefers-reduced-motion: reduce)") : null;
   let reducedMotion = motionQuery?.matches ?? false;
+  function hoverTarget(cruise) {
+    const hover = opts.hover ?? "off";
+    if (hover === "off") return cruise;
+    if (hover === "pause") return 0;
+    if (typeof hover === "number") return cruise * hover;
+    return (cruise < 0 ? -1 : 1) * Math.abs(hover.speed);
+  }
   function target() {
     if (reducedMotion || paused) return 0;
     const cruise = opts.reverse ? -opts.speed : opts.speed;
-    return hovering ? cruise * opts.hoverScale : cruise;
+    return hovering ? hoverTarget(cruise) : cruise;
   }
   function axisSize(element) {
     return opts.vertical ? element.offsetHeight : element.offsetWidth;

package/dist/index.d.ts

@@ -11,6 +11,21 @@ export { F as FuseConstructor, a as FuseLike, S as SearchInstance, b as SearchMa
  * comments marked "non-negotiable" name the bug that the obvious implementation
  * shipped with.
  */
+/**
+ * What a MOUSE resting on the row does to its speed. One option covers every case, so
+ * there is no pile of booleans to reconcile:
+ *
+ * - `"off"`   ignore hover entirely (the default)
+ * - `"pause"` stop while the pointer is on it
+ * - a number  multiply the cruise speed: `0.15` crawls, `1` changes nothing, `2` doubles
+ * - `{ speed }` an ABSOLUTE speed in px/s, whatever the cruise is; direction still
+ *   follows `reverse`, so you give a magnitude and not a sign
+ *
+ * Touch never triggers any of it - see the pointerType note on the hover handler.
+ */
+type MarqueeHover = number | "off" | "pause" | {
+    speed: number;
+};
 interface MarqueeOptions {
     /**
      * Pixels per second. NOT a duration: a duration ties the speed to the item
@@ -23,8 +38,8 @@ interface MarqueeOptions {
     vertical?: boolean;
     /** Allow grabbing and throwing the row. */
     draggable?: boolean;
-    /** Speed multiplier while a MOUSE rests on the row. 0 pauses it. */
-    hoverScale?: number;
+    /** What a mouse resting on the row does to its speed. See {@link MarqueeHover}. */
+    hover?: MarqueeHover;
     /** Fraction of the remaining velocity gap left after one second. */
     decay?: number;
     /**
@@ -147,4 +162,4 @@ interface InputInstance {
  */
 declare function createInput(input: HTMLInputElement, options?: InputOptions): InputInstance;
 
-export { type InputAction, type InputActionState, type InputIcon, type InputInstance, type InputOptions, type MarqueeInstance, type MarqueeOptions, createInput, createMarquee };
+export { type InputAction, type InputActionState, type InputIcon, type InputInstance, type InputOptions, type MarqueeHover, type MarqueeInstance, type MarqueeOptions, createInput, createMarquee };

package/dist/index.js

@@ -1,2 +1,2 @@
-export { createInput, createMarquee } from './chunk-W2DRHYC2.js';
+export { createInput, createMarquee } from './chunk-2DVVWPHM.js';
 export { createSearch } from './chunk-UZFEEFMF.js';

package/dist/react/index.d.ts

@@ -1,6 +1,6 @@
 import { RefObject } from 'react';
 import { MarqueeOptions, InputOptions } from '../index.js';
-export { InputAction, InputIcon, MarqueeInstance } from '../index.js';
+export { InputAction, InputIcon, MarqueeHover, MarqueeInstance } from '../index.js';
 import { b as SearchMatch, c as SearchOptions } from '../search-CsO3L1Lw.js';
 export { F as FuseConstructor } from '../search-CsO3L1Lw.js';
 
@@ -28,7 +28,7 @@ interface UseMarqueeResult {
  * to the item count, so the row accelerates every time content is added.
  *
  * ```tsx
- * const { laneRef, trackRef, copies } = useMarquee({ speed: 80, hoverScale: 0.15 });
+ * const { laneRef, trackRef, copies } = useMarquee({ speed: 80, hover: 0.15 });
  * return (
  *     <div ref={laneRef}>
  *         <div ref={trackRef} style={{ display: "flex" }}>

package/dist/react/index.js

@@ -1,4 +1,4 @@
-import { createMarquee, createInput } from '../chunk-W2DRHYC2.js';
+import { createMarquee, createInput } from '../chunk-2DVVWPHM.js';
 import { createSearch } from '../chunk-UZFEEFMF.js';
 import { useRef, useState, useMemo, useEffect, useLayoutEffect } from 'react';
 
@@ -39,7 +39,7 @@ function useMarquee(options = {}) {
   }, []);
   useIsomorphicLayoutEffect(() => {
     instanceRef.current?.update(options);
-  }, [options.speed, options.reverse, options.vertical, options.draggable, options.hoverScale, options.decay]);
+  }, [options.speed, options.reverse, options.vertical, options.draggable, options.hover, options.decay]);
   useIsomorphicLayoutEffect(() => {
     instanceRef.current?.measure();
   }, [copies]);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@enigmax/primitives",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Headless interaction primitives: the behaviour, the timing and the accessibility of components like a draggable infinite marquee, with no styles of their own. Framework-agnostic core plus thin adapters.",
   "type": "module",
   "main": "./dist/index.js",

package/recipes/marquee.css.tsx

@@ -1,6 +1,6 @@
 import "./marquee.css";
 import type { ReactNode, Ref } from "react";
-import { useMarquee } from "@enigmax/primitives/react";
+import { useMarquee, type MarqueeHover } from "@enigmax/primitives/react";
 
 /**
  * A styled marquee, yours to edit.
@@ -12,8 +12,12 @@ export interface MarqueeProps<T> {
     items: T[];
     /** Pixels per second. Never a duration - the row would speed up as items are added. */
     speed?: number;
-    /** Speed multiplier while a mouse rests on the row. 0 pauses it. */
-    hoverScale?: number;
+    /**
+     * What a mouse resting on the row does to its speed:
+     * "off" ignores hover, "pause" stops, a number multiplies the cruise speed
+     * (0.15 crawls, 2 doubles), { speed } sets an absolute px/s.
+     */
+    hover?: MarqueeHover;
     reverse?: boolean;
     /** Fade both ends so items enter and leave instead of being cut. */
     fade?: boolean;
@@ -24,13 +28,13 @@ export interface MarqueeProps<T> {
 export function Marquee<T>({
     items,
     speed = 70,
-    hoverScale = 1,
+    hover = "off",
     reverse = false,
     fade = true,
     className = "",
     children
 }: MarqueeProps<T>) {
-    const { laneRef, trackRef, copies, dragging } = useMarquee({ speed, hoverScale, reverse });
+    const { laneRef, trackRef, copies, dragging } = useMarquee({ speed, hover, reverse });
 
     return (
         <div

package/recipes/marquee.tailwind.tsx

@@ -1,5 +1,5 @@
 import type { ReactNode, Ref } from "react";
-import { useMarquee } from "@enigmax/primitives/react";
+import { useMarquee, type MarqueeHover } from "@enigmax/primitives/react";
 
 /**
  * A styled marquee, yours to edit.
@@ -16,8 +16,12 @@ export interface MarqueeProps<T> {
     items: T[];
     /** Pixels per second. Never a duration - the row would speed up as items are added. */
     speed?: number;
-    /** Speed multiplier while a mouse rests on the row. 0 pauses it. */
-    hoverScale?: number;
+    /**
+     * What a mouse resting on the row does to its speed:
+     * "off" ignores hover, "pause" stops, a number multiplies the cruise speed
+     * (0.15 crawls, 2 doubles), { speed } sets an absolute px/s.
+     */
+    hover?: MarqueeHover;
     reverse?: boolean;
     /** Fade both ends so items enter and leave instead of being cut. */
     fade?: boolean;
@@ -28,13 +32,13 @@ export interface MarqueeProps<T> {
 export function Marquee<T>({
     items,
     speed = 70,
-    hoverScale = 1,
+    hover = "off",
     reverse = false,
     fade = true,
     className = "",
     children
 }: MarqueeProps<T>) {
-    const { laneRef, trackRef, copies, dragging } = useMarquee({ speed, hoverScale, reverse });
+    const { laneRef, trackRef, copies, dragging } = useMarquee({ speed, hover, reverse });
 
     return (
         <div

package/src/core/marquee.ts

@@ -29,6 +29,20 @@ const TOUCH_HOVER_SUPPRESS_MS = 1000;
 /** Below this the row is idle and the frame loop can stop. */
 const IDLE_EPSILON = 0.01;
 
+/**
+ * What a MOUSE resting on the row does to its speed. One option covers every case, so
+ * there is no pile of booleans to reconcile:
+ *
+ * - `"off"`   ignore hover entirely (the default)
+ * - `"pause"` stop while the pointer is on it
+ * - a number  multiply the cruise speed: `0.15` crawls, `1` changes nothing, `2` doubles
+ * - `{ speed }` an ABSOLUTE speed in px/s, whatever the cruise is; direction still
+ *   follows `reverse`, so you give a magnitude and not a sign
+ *
+ * Touch never triggers any of it - see the pointerType note on the hover handler.
+ */
+export type MarqueeHover = number | "off" | "pause" | { speed: number; };
+
 export interface MarqueeOptions {
     /**
      * Pixels per second. NOT a duration: a duration ties the speed to the item
@@ -41,8 +55,8 @@ export interface MarqueeOptions {
     vertical?: boolean;
     /** Allow grabbing and throwing the row. */
     draggable?: boolean;
-    /** Speed multiplier while a MOUSE rests on the row. 0 pauses it. */
-    hoverScale?: number;
+    /** What a mouse resting on the row does to its speed. See {@link MarqueeHover}. */
+    hover?: MarqueeHover;
     /** Fraction of the remaining velocity gap left after one second. */
     decay?: number;
     /**
@@ -94,7 +108,7 @@ const DEFAULTS: ResolvedOptions = {
     reverse: false,
     vertical: false,
     draggable: true,
-    hoverScale: 1,
+    hover: "off",
     decay: DEFAULT_DECAY,
     manageStyles: true,
     copies: "clone"
@@ -134,11 +148,21 @@ export function createMarquee(lane: HTMLElement, track: HTMLElement, options: Ma
         : null;
     let reducedMotion = motionQuery?.matches ?? false;
 
+    /** The speed a mouse on the row asks for. One option, four shapes, no flags to reconcile. */
+    function hoverTarget(cruise: number): number {
+        const hover = opts.hover ?? "off";
+        if (hover === "off") return cruise;
+        if (hover === "pause") return 0;
+        if (typeof hover === "number") return cruise * hover;
+        // An absolute speed is a magnitude: the row keeps travelling the way it was.
+        return (cruise < 0 ? -1 : 1) * Math.abs(hover.speed);
+    }
+
     /** Read live every frame, never captured: cruise, hover and reduced motion all ease. */
     function target(): number {
         if (reducedMotion || paused) return 0;
         const cruise = opts.reverse ? -opts.speed : opts.speed;
-        return hovering ? cruise * opts.hoverScale : cruise;
+        return hovering ? hoverTarget(cruise) : cruise;
     }
 
     function axisSize(element: HTMLElement): number {

package/src/index.ts

@@ -1,3 +1,3 @@
-export { createMarquee, type MarqueeOptions, type MarqueeInstance } from "@/core/marquee";
+export { createMarquee, type MarqueeOptions, type MarqueeInstance, type MarqueeHover } from "@/core/marquee";
 export { createInput, type InputOptions, type InputInstance, type InputAction, type InputIcon, type InputActionState } from "@/core/input";
 export { createSearch, type SearchOptions, type SearchInstance, type SearchMatch, type FuseConstructor, type FuseLike } from "@/core/search";

package/src/react/index.ts

@@ -1,5 +1,5 @@
 export { useMarquee, type UseMarqueeResult } from "@/react/use-marquee";
-export { type MarqueeOptions, type MarqueeInstance } from "@/core/marquee";
+export { type MarqueeOptions, type MarqueeInstance, type MarqueeHover } from "@/core/marquee";
 export { useInput, type UseInputResult } from "@/react/use-input";
 export { useSearch, type UseSearchResult } from "@/react/use-search";
 export { type InputOptions, type InputAction, type InputIcon } from "@/core/input";

package/src/react/use-marquee.ts

@@ -29,7 +29,7 @@ export interface UseMarqueeResult {
  * to the item count, so the row accelerates every time content is added.
  *
  * ```tsx
- * const { laneRef, trackRef, copies } = useMarquee({ speed: 80, hoverScale: 0.15 });
+ * const { laneRef, trackRef, copies } = useMarquee({ speed: 80, hover: 0.15 });
  * return (
  *     <div ref={laneRef}>
  *         <div ref={trackRef} style={{ display: "flex" }}>
@@ -87,7 +87,7 @@ export function useMarquee(options: MarqueeOptions = {}): UseMarqueeResult {
 
     useIsomorphicLayoutEffect(() => {
         instanceRef.current?.update(options);
-    }, [options.speed, options.reverse, options.vertical, options.draggable, options.hoverScale, options.decay]);
+    }, [options.speed, options.reverse, options.vertical, options.draggable, options.hover, options.decay]);
 
     // A copy count change means new children; the lap has to be read again.
     useIsomorphicLayoutEffect(() => {