@enigmax/primitives 0.1.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,111 @@
+# @enigmax/primitives
+
+Headless interaction primitives: the behaviour, the timing and the accessibility, with no styles of their own.
+
+**The marquee takes a speed in pixels per second, never a duration.** A lap of a looping row is as long as its content, so a duration makes the speed `content / duration` and the row runs faster every time an item is added to it. Two testimonial rows split from an odd-length array, same `--duration: 20s`, measured 53.2 px/s and 66.5 px/s and were meant to look like a pair. A provider rail on a fixed 50s duration measured 45, 67 and 87 px/s at 10, 15 and 20 items, because nobody edits the duration when they add a provider. Take a speed and derive the duration: the same rail then measured 67.0 px/s at all three counts.
+
+## Install
+
+```sh
+npm install @enigmax/primitives
+# or, to copy the source in and own it:
+enigma add marquee --copy
+```
+
+## Use it
+
+React:
+
+```tsx
+import { useMarquee } from "@enigmax/primitives/react";
+
+function LogoWall({ logos }) {
+    const { laneRef, trackRef, copies, dragging } = useMarquee({ speed: 80, hoverScale: 0.15 });
+
+    return (
+        <div ref={laneRef} style={{ cursor: dragging ? "grabbing" : "grab" }}>
+            <div ref={trackRef} style={{ display: "flex" }}>
+                {Array.from({ length: copies }, (_, copy) => (
+                    <div key={copy} aria-hidden={copy > 0} style={{ display: "flex", gap: 32 }}>
+                        {logos.map(logo => <a key={logo.id} href={logo.href}>{logo.name}</a>)}
+                    </div>
+                ))}
+            </div>
+        </div>
+    );
+}
+```
+
+Vanilla, Astro, or anything else that hands you two elements:
+
+```js
+import { createMarquee } from "@enigmax/primitives";
+
+const marquee = createMarquee(document.querySelector("[data-lane]"), document.querySelector("[data-track]"), {
+    speed: 80,
+    hoverScale: 0.15
+});
+```
+
+The core clones the track's first child to fill the lane. In React the hook reports a `copies` count instead, so React keeps ownership of the DOM.
+
+## Options
+
+| Option | Default | Meaning |
+|---|---|---|
+| `speed` | `60` | Pixels per second. Not a duration. |
+| `reverse` | `false` | Scroll towards the start. |
+| `vertical` | `false` | Scroll on the Y axis. |
+| `draggable` | `true` | Grab and throw the row. |
+| `hoverScale` | `1` | Speed multiplier while a **mouse** rests on the row. `0` pauses. |
+| `decay` | `0.12` | Fraction of the remaining velocity gap left after one second. `0.35` is draggy. |
+| `manageStyles` | `true` | Apply the styles the behaviour needs. Never theme styles. |
+
+## Why the obvious implementation is wrong
+
+Three of these cost a production bug each. They are the reason this package exists rather than a snippet.
+
+**`setPointerCapture` silently breaks every link in the row.** A pointer capture retargets the compatibility mouse events too, so the `click` of a plain press arrives on the lane instead of on the card that was pressed, and the card's link never opens. A nine-logo carousel quietly stops being nine links and nothing in the source looks wrong. This package binds `pointermove` / `pointerup` / `pointercancel` to `window`, which is all the capture was ever for - a mousedown already captures the mouse at the OS level, so a release outside the browser window still arrives.
+
+**`touch-action` decides whether a phone can scroll your page.** Without it the browser owns the horizontal swipe and the drag handlers never see it. With `none`, a visitor can no longer scroll the page by starting the gesture on the row, which on a phone is most of the width of the screen. The lane gets `pan-y` (or `pan-x` when vertical).
+
+**A hover effect that ignores `pointerType` sticks forever on touch.** A tap fires `pointerenter` too, and on touch nothing ever fires the `pointerleave` that undoes it, so a "slow down on hover" leaves the row at 15% speed for good after the first tap. Every hover path here is gated to `pointerType === "mouse"`.
+
+The rest, in short: the lap is measured from the step between two copies rather than computed from item widths; the transform is driven by one `requestAnimationFrame` loop rather than CSS keyframes, which restart on every re-author; one integrator carries cruise, hover and momentum so none of them can arrive as a cut; a drag past ~6px cancels the click in the capture phase; a right click never starts a drag; a pointer held still for ~90ms before release throws nothing; and reduced motion drops the autoplay while keeping the drag, because a drag is an answer to the pointer and not motion of the page's own accord.
+
+## Styling
+
+The primitive ships no visual styles. It sets only what the behaviour requires (`overflow`, `touch-action`, `user-select`, `will-change`, `transform`) and exposes state as data attributes for a theme to hook:
+
+```css
+[data-enigma-marquee]                        { cursor: grab; }
+[data-enigma-marquee][data-dragging]         { cursor: grabbing; }
+[data-enigma-marquee][data-hovering]         { --logo-opacity: 1; }
+[data-enigma-marquee][data-reduced-motion="true"] { /* autoplay is off */ }
+[data-enigma-marquee-track]                  { display: flex; }
+[data-enigma-marquee-copy]                   { display: flex; gap: 2rem; }
+```
+
+## Tests
+
+The suite drives a real browser and samples `new DOMMatrixReadOnly(getComputedStyle(track).transform).m41` on every animation frame, rather than asking the engine what it believes.
+
+```sh
+npm run test:install   # once, fetches Chromium
+npm test
+```
+
+| Check | Pass condition |
+|---|---|
+| Same speed at 2, 9, 11, 20 items | measured px/s equal within 1% |
+| Drag follows the pointer | a 200px swipe moves the row 200.0px |
+| Release | decays monotonically onto cruise, no sign flip |
+| Four viewport resizes | no frame moves more than one frame of cruising |
+| Drag ending on a link | 0 navigations |
+| Plain click and tap on a link | 1 navigation each |
+| Tap on touch | row does not stick at the hover speed |
+| Vertical swipe on a phone | the page still scrolls |
+| `prefers-reduced-motion` | 0.00px idle drift, drag still works |
+| Held still, then release | no fling |
+
+Two ways to fool yourself, both of which produced a false alarm while this was being written: do not measure a resize as before/after, because `setViewportSize` takes several hundred milliseconds during which the row legitimately keeps moving - sample every frame and look for a single anomalous one. And discard the first few samples, because the first rAF delta after installing the sampler is near zero and produces a meaningless px/s spike.

package/dist/chunk-5Q5TAW2N.js

@@ -0,0 +1,267 @@
+// src/core/marquee.ts
+var DEFAULT_DECAY = 0.12;
+var DRAG_THRESHOLD = 6;
+var STILL_MS = 90;
+var MAX_DT = 0.05;
+var VELOCITY_SMOOTHING = 0.6;
+var IDLE_EPSILON = 0.01;
+var DEFAULTS = {
+  speed: 60,
+  reverse: false,
+  vertical: false,
+  draggable: true,
+  hoverScale: 1,
+  decay: DEFAULT_DECAY,
+  manageStyles: true,
+  copies: "clone"
+};
+function createMarquee(lane, track, options = {}) {
+  let opts = { ...DEFAULTS, ...options };
+  let period = 0;
+  let copyCount = Math.max(2, track.children.length);
+  let offset = 0;
+  let velocity = 0;
+  let running = false;
+  let paused = false;
+  let destroyed = false;
+  let frame = 0;
+  let lastTime = 0;
+  let dragging = false;
+  let pointerId = null;
+  let lastPointer = 0;
+  let startPointer = 0;
+  let lastMoveTime = 0;
+  let maxTravel = 0;
+  let hovering = false;
+  const motionQuery = typeof window.matchMedia === "function" ? window.matchMedia("(prefers-reduced-motion: reduce)") : null;
+  let reducedMotion = motionQuery?.matches ?? false;
+  function target() {
+    if (reducedMotion || paused) return 0;
+    const cruise = opts.reverse ? -opts.speed : opts.speed;
+    return hovering ? cruise * opts.hoverScale : cruise;
+  }
+  function axisSize(element) {
+    return opts.vertical ? element.offsetHeight : element.offsetWidth;
+  }
+  function axisStart(element) {
+    return opts.vertical ? element.offsetTop : element.offsetLeft;
+  }
+  function applyStyles() {
+    if (!opts.manageStyles) return;
+    lane.style.overflow = "hidden";
+    lane.style.touchAction = opts.vertical ? "pan-x" : "pan-y";
+    lane.style.userSelect = "none";
+    lane.style.webkitUserSelect = "none";
+    track.style.willChange = "transform";
+  }
+  function render() {
+    const x = opts.vertical ? 0 : -offset;
+    const y = opts.vertical ? -offset : 0;
+    track.style.transform = `translate3d(${x}px, ${y}px, 0)`;
+  }
+  function readPeriod() {
+    const first = track.children[0];
+    const second = track.children[1];
+    if (!first) return 0;
+    if (second) {
+      const step = axisStart(second) - axisStart(first);
+      if (step > 0) return step;
+    }
+    return axisSize(first);
+  }
+  function requiredCopies(measured) {
+    if (measured <= 0) return 2;
+    return Math.max(2, Math.ceil(axisSize(lane) / measured) + 1);
+  }
+  function syncClones(count) {
+    const source = track.children[0];
+    if (!source) return;
+    while (track.children.length > count) track.removeChild(track.lastElementChild);
+    while (track.children.length < count) {
+      const clone = source.cloneNode(true);
+      clone.setAttribute("aria-hidden", "true");
+      clone.dataset.enigmaMarqueeCopy = String(track.children.length);
+      track.appendChild(clone);
+    }
+  }
+  function measure() {
+    if (destroyed) return;
+    const measured = readPeriod();
+    const needed = requiredCopies(measured);
+    const changed = measured !== period || needed !== copyCount;
+    period = measured;
+    if (needed !== copyCount) {
+      copyCount = needed;
+      if (opts.copies === "clone") syncClones(needed);
+      opts.onCopyCountChange?.(needed);
+    }
+    if (period > 0) offset = wrap(offset);
+    render();
+    if (changed) opts.onMeasure?.(period, copyCount);
+    start();
+  }
+  function wrap(value) {
+    if (period <= 0) return value;
+    return (value % period + period) % period;
+  }
+  function tick(now) {
+    frame = 0;
+    if (destroyed) return;
+    const dt = Math.min((now - lastTime) / 1e3, MAX_DT);
+    lastTime = now;
+    if (!dragging) {
+      velocity += (target() - velocity) * (1 - Math.pow(opts.decay, dt));
+      offset = wrap(offset + velocity * dt);
+    }
+    render();
+    const idle = !dragging && Math.abs(velocity) < IDLE_EPSILON && Math.abs(target()) < IDLE_EPSILON;
+    if (idle) {
+      velocity = 0;
+      running = false;
+      return;
+    }
+    frame = requestAnimationFrame(tick);
+  }
+  function start() {
+    if (destroyed || running) return;
+    running = true;
+    lastTime = performance.now();
+    frame = requestAnimationFrame(tick);
+  }
+  function pointerDelta(event) {
+    return opts.vertical ? event.clientY : event.clientX;
+  }
+  function onPointerDown(event) {
+    if (!opts.draggable || event.button > 0 || pointerId !== null) return;
+    pointerId = event.pointerId;
+    dragging = true;
+    lastPointer = pointerDelta(event);
+    startPointer = lastPointer;
+    lastMoveTime = event.timeStamp;
+    maxTravel = 0;
+    lane.dataset.dragging = "true";
+    window.addEventListener("pointermove", onPointerMove);
+    window.addEventListener("pointerup", onPointerUp);
+    window.addEventListener("pointercancel", onPointerUp);
+    start();
+  }
+  function onPointerMove(event) {
+    if (event.pointerId !== pointerId) return;
+    const position = pointerDelta(event);
+    const delta = position - lastPointer;
+    lastPointer = position;
+    const dt = Math.max((event.timeStamp - lastMoveTime) / 1e3, 1e-3);
+    lastMoveTime = event.timeStamp;
+    maxTravel = Math.max(maxTravel, Math.abs(position - startPointer));
+    offset = wrap(offset - delta);
+    const instant = -delta / dt;
+    velocity = velocity * VELOCITY_SMOOTHING + instant * (1 - VELOCITY_SMOOTHING);
+  }
+  function onPointerUp(event) {
+    if (event.pointerId !== pointerId) return;
+    pointerId = null;
+    dragging = false;
+    delete lane.dataset.dragging;
+    window.removeEventListener("pointermove", onPointerMove);
+    window.removeEventListener("pointerup", onPointerUp);
+    window.removeEventListener("pointercancel", onPointerUp);
+    if (event.timeStamp - lastMoveTime > STILL_MS) velocity = 0;
+    start();
+  }
+  function onClickCapture(event) {
+    if (maxTravel <= DRAG_THRESHOLD) return;
+    event.preventDefault();
+    event.stopPropagation();
+  }
+  function onClick(event) {
+    if (maxTravel > DRAG_THRESHOLD) return;
+    opts.onItemClick?.(event);
+  }
+  function onPointerEnter(event) {
+    if (event.pointerType !== "mouse") return;
+    hovering = true;
+    lane.dataset.hovering = "true";
+    start();
+  }
+  function onPointerLeave(event) {
+    if (event.pointerType !== "mouse") return;
+    hovering = false;
+    delete lane.dataset.hovering;
+    start();
+  }
+  function onMotionChange(event) {
+    reducedMotion = event.matches;
+    lane.dataset.reducedMotion = String(reducedMotion);
+    start();
+  }
+  const resizeObserver = typeof ResizeObserver === "function" ? new ResizeObserver(() => measure()) : null;
+  function init() {
+    applyStyles();
+    lane.dataset.enigmaMarquee = "";
+    lane.dataset.reducedMotion = String(reducedMotion);
+    track.dataset.enigmaMarqueeTrack = "";
+    for (const child of Array.from(track.children)) {
+      child.dataset.enigmaMarqueeCopy ??= "0";
+    }
+    lane.addEventListener("pointerdown", onPointerDown);
+    lane.addEventListener("pointerenter", onPointerEnter);
+    lane.addEventListener("pointerleave", onPointerLeave);
+    lane.addEventListener("click", onClickCapture, true);
+    lane.addEventListener("click", onClick);
+    motionQuery?.addEventListener("change", onMotionChange);
+    resizeObserver?.observe(lane);
+    const first = track.children[0];
+    if (first) resizeObserver?.observe(first);
+    measure();
+    void document.fonts?.ready.then(() => measure());
+  }
+  init();
+  return {
+    get offset() {
+      return offset;
+    },
+    get period() {
+      return period;
+    },
+    get copyCount() {
+      return copyCount;
+    },
+    get dragging() {
+      return dragging;
+    },
+    get reducedMotion() {
+      return reducedMotion;
+    },
+    update(next) {
+      const styleKeys = next.vertical !== void 0 || next.manageStyles !== void 0;
+      opts = { ...opts, ...next };
+      if (styleKeys) applyStyles();
+      measure();
+    },
+    measure,
+    pause() {
+      paused = true;
+      start();
+    },
+    resume() {
+      paused = false;
+      start();
+    },
+    destroy() {
+      destroyed = true;
+      if (frame) cancelAnimationFrame(frame);
+      resizeObserver?.disconnect();
+      motionQuery?.removeEventListener("change", onMotionChange);
+      lane.removeEventListener("pointerdown", onPointerDown);
+      lane.removeEventListener("pointerenter", onPointerEnter);
+      lane.removeEventListener("pointerleave", onPointerLeave);
+      lane.removeEventListener("click", onClickCapture, true);
+      lane.removeEventListener("click", onClick);
+      window.removeEventListener("pointermove", onPointerMove);
+      window.removeEventListener("pointerup", onPointerUp);
+      window.removeEventListener("pointercancel", onPointerUp);
+    }
+  };
+}
+
+export { createMarquee };

package/dist/index.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Draggable infinite marquee: the behaviour engine, with no styling of its own.
+ *
+ * The contract is a SPEED in pixels per second, never a duration. A lap of a
+ * looping row is as long as its content, so a duration makes the row run faster
+ * every time an item is added to it. See the package README.
+ *
+ * Every rule encoded here was measured in a browser, not reasoned about. The
+ * comments marked "non-negotiable" name the bug that the obvious implementation
+ * shipped with.
+ */
+interface MarqueeOptions {
+    /**
+     * Pixels per second. NOT a duration: a duration ties the speed to the item
+     * count and the row silently accelerates as content grows.
+     */
+    speed?: number;
+    /** Scroll towards the start instead of the end. */
+    reverse?: boolean;
+    /** Scroll on the Y axis instead of the X axis. */
+    vertical?: boolean;
+    /** Allow grabbing and throwing the row. */
+    draggable?: boolean;
+    /** Speed multiplier while a MOUSE rests on the row. 0 pauses it. */
+    hoverScale?: number;
+    /** Fraction of the remaining velocity gap left after one second. */
+    decay?: number;
+    /**
+     * Apply the styles the behaviour needs (overflow, touch-action, user-select,
+     * will-change, transform). Never theme styles. Turn off to own them yourself.
+     */
+    manageStyles?: boolean;
+    /**
+     * How the repeated copies get into the DOM.
+     * - "clone": the engine clones the first child of the track (vanilla, Astro).
+     * - "external": the consumer renders them and is told the count (React, Vue).
+     */
+    copies?: "clone" | "external";
+    /** Called when the required copy count changes. Required for "external". */
+    onCopyCountChange?: (count: number) => void;
+    /** Called on a click that was not the end of a drag. */
+    onItemClick?: (event: MouseEvent) => void;
+    /** Called whenever the measured lap period changes. */
+    onMeasure?: (period: number, copyCount: number) => void;
+}
+interface MarqueeInstance {
+    /** Current offset in px, normalized to [0, period). */
+    readonly offset: number;
+    /** Measured distance between two copies of the content, in px. */
+    readonly period: number;
+    /** Copies currently required to cover the lane plus one whole period. */
+    readonly copyCount: number;
+    /** True between pointerdown and pointerup while the row is being grabbed. */
+    readonly dragging: boolean;
+    /** True while the OS asks for reduced motion. Autoplay stops, drag does not. */
+    readonly reducedMotion: boolean;
+    update(options: Partial<MarqueeOptions>): void;
+    /** Re-read the lap from the DOM. Called for you on resize and on font load. */
+    measure(): void;
+    pause(): void;
+    resume(): void;
+    destroy(): void;
+}
+/**
+ * Wire a lane and its track into a draggable infinite marquee.
+ *
+ * @param lane  The clipping viewport. Receives the pointer and the click guard.
+ * @param track The moved element. Its children are the repeated copies; child 0
+ *              is the source content and must already be rendered.
+ */
+declare function createMarquee(lane: HTMLElement, track: HTMLElement, options?: MarqueeOptions): MarqueeInstance;
+
+export { type MarqueeInstance, type MarqueeOptions, createMarquee };

package/dist/index.js

@@ -0,0 +1 @@
+export { createMarquee } from './chunk-5Q5TAW2N.js';