@monabbous/slidebox 1.1.0 → 1.2.0

package/README.md

@@ -1,6 +1,6 @@
 # Slidebox
 
-An elastic CSS switch built on a native checkbox. No JavaScript, extra elements, or runtime dependencies required.
+An elastic CSS switch built on a native checkbox. No JavaScript, extra elements, or runtime dependencies required. Add optional [experimental pointer dragging](#experimental-pointer-dragging) when you want the thumb to follow your pointer.
 
 ![Slidebox switch animation](assets/slidebox-demo.webp)
 
@@ -199,6 +199,79 @@ theme: {
 
 CSS custom properties work with every integration. Avoid setting a control both through plugin/mixin defaults and an inherited variable: a value assigned directly to the switch wins over inheritance. Use a utility or a selector targeting that switch to override it.
 
+## Experimental pointer dragging
+
+**Opt-in and experimental.** The switch works without JavaScript. This separate, dependency-free ES module adds mouse, touch, and pen dragging to a checkbox styled with Slidebox. It never initializes controls automatically. The API and gesture feel may change in future releases.
+
+Keep using your chosen CSS, Sass, Less, or Tailwind integration, then attach the enhancement **after the input is mounted**:
+
+```html
+<label>
+  <input id="notifications" class="slidebox" type="checkbox" role="switch" name="notifications">
+  Enable notifications
+</label>
+```
+
+```js
+import "@monabbous/slidebox/dist/css/slidebox.css"; // Omit for Sass, Less, or Tailwind.
+import { enhanceSlidebox } from "@monabbous/slidebox/experimental/drag.mjs";
+
+const input = document.querySelector("#notifications");
+const disableDragging = enhanceSlidebox(input, { threshold: 5 });
+
+// Before removing the input, or when disabling this experimental feature:
+// disableDragging();
+```
+
+The JavaScript and drag styles must come from the **same package version**. Sass and Less mixins also include the necessary styles, so your checkbox can use a custom class instead of `.slidebox`.
+
+### Behavior and configuration
+
+- `threshold` is the horizontal movement, in CSS pixels, required to begin dragging. Default: `5`. Must be a finite, non-negative number.
+- The thumb follows the pointer; its trailing edge stretches and relaxes using `--slidebox-deform` and `--slidebox-duration`. Set `--slidebox-deform: 0` to disable stretching. Reduced-motion preferences also disable drag stretching.
+- Releasing at or beyond the midpoint checks the input; releasing before it unchecks it. A changed state emits one bubbling `input` event followed by one bubbling `change` event. Drag movement alone does not emit either event.
+- Normal clicks, label clicks, Space-key activation, form values, and form resets remain native. A completed drag suppresses its following click to prevent a second toggle. No synthetic `click` is emitted for a drag.
+- RTL reverses the gesture direction. Disabled inputs, including those inside a disabled fieldset, cannot be dragged.
+- Vertical touch gestures remain available for scrolling, and pinch zoom remains enabled. Cancellation or lost pointer capture abandons the gesture without committing it.
+- Call the returned cleanup function to stop dragging and restore temporary styles. Cleanup can be called repeatedly. Disabling it during a drag cancels that drag.
+- Repeated calls for the same input return its existing cleanup function. To change `threshold`, clean up and initialize again.
+
+Use normal checkbox bindings in your framework. In React, for example, initialize from a ref and return cleanup from an effect:
+
+```jsx
+import { useEffect, useRef, useState } from "react";
+import { enhanceSlidebox } from "@monabbous/slidebox/experimental/drag.mjs";
+
+function Notifications() {
+  const input = useRef(null);
+  const [enabled, setEnabled] = useState(false);
+
+  useEffect(() => {
+    const element = input.current;
+    // Native listeners also receive the enhancement's programmatic change event.
+    const sync = () => setEnabled(element.checked);
+    element.addEventListener("change", sync);
+    const destroy = enhanceSlidebox(element);
+    return () => {
+      destroy();
+      element.removeEventListener("change", sync);
+    };
+  }, []);
+
+  return (
+    <label>
+      <input ref={input} className="slidebox" type="checkbox" role="switch"
+        checked={enabled} onChange={event => setEnabled(event.target.checked)} />
+      Enable notifications
+    </label>
+  );
+}
+```
+
+TypeScript declarations ship alongside `drag.mjs`. Importing the module is safe during server rendering, but calling `enhanceSlidebox()` requires a mounted checkbox in a browser supporting Pointer Events and pointer capture. Use a sufficiently wide horizontal Slidebox (width ratio greater than 1). Test touch, scrolling, and your framework's controlled-input behavior before adopting it in production; vertical switches are not supported.
+
+Try it in the playground under **03 / Experimental → Enable pointer dragging**. Reset turns the option off. The playground's glass lighting is separate and is not shipped as part of the drag module.
+
 ## Development
 
 ```sh
@@ -208,7 +281,16 @@ npm test
 npm pack --dry-run
 ```
 
-The build extracts component rules from `style.css` and generates CSS, Sass, Less, and Tailwind rules. Tests compile both mixins and the plugin with Tailwind v3 and v4. The lab itself is plain HTML/CSS/JavaScript; serve the repository with `python3 -m http.server 8080` and open `http://localhost:8080`.
+The build extracts component rules from `style.css` and generates CSS, Sass, Less, and Tailwind rules. Tests compile both mixins and the plugin with Tailwind v3 and v4, and check the drag module's lifecycle.
+
+For real-browser drag and playground checks:
+
+```sh
+npx playwright install chromium
+npm run test:browser
+```
+
+These run in Chromium; other browsers and devices still need testing. The lab itself is plain HTML/CSS/JavaScript; serve the repository with `python3 -m http.server 8080` and open `http://localhost:8080`.
 
 Releases use the manual [Publish to npm](.github/workflows/publish-npm.yml) workflow on `main`, with npm trusted publishing through the `production` environment. Choose a version bump for a new release, or enable `publish_existing_version` to retry the current version without a bump or new tag.
 

package/dist/css/slidebox.css

@@ -50,6 +50,11 @@
 .slidebox:not(:checked):active::after { --_end: calc(1 - var(--_deform)); }
 .slidebox:checked:active::after { --_start: calc(1 - var(--_deform)); }
 .slidebox:disabled { cursor: not-allowed; opacity: .5; }
+.slidebox[data-slidebox-dragging]::after {
+  margin-inline-start: calc((1em * var(--_container-width-ratio) - 1em) * max(0, var(--slidebox-drag-progress) - max(0, var(--slidebox-drag-stretch, 0))) + var(--_thumb-spacing-ratio) * .5em);
+  margin-inline-end: calc((1em * var(--_container-width-ratio) - 1em) * max(0, 1 - var(--slidebox-drag-progress) - max(0, -1 * var(--slidebox-drag-stretch, 0))) + var(--_thumb-spacing-ratio) * .5em);
+  transition: none;
+}
 @media (forced-colors: active) {
   .slidebox { --_track: Field; --_border: ButtonBorder; --_off: FieldText; --_on: Highlight; }
 }

package/experimental/drag.d.mts

@@ -0,0 +1,15 @@
+export interface SlideboxDragOptions {
+  /** Horizontal movement in CSS pixels before a drag starts. Default: 5. */
+  threshold?: number;
+}
+
+/**
+ * Experimental opt-in pointer dragging for a native checkbox styled by Slidebox.
+ * Call after mounting the input. Returns an idempotent cleanup function.
+ * Calling again for the same input returns its existing cleanup function;
+ * destroy it first to change options. Safe to import during server rendering.
+ */
+export declare function enhanceSlidebox(
+  input: HTMLInputElement,
+  options?: SlideboxDragOptions,
+): () => void;

package/experimental/drag.mjs

@@ -0,0 +1,158 @@
+const enhancements = new WeakMap();
+
+/** Opt in a native checkbox to experimental horizontal pointer dragging. */
+export function enhanceSlidebox(input, { threshold = 5 } = {}) {
+  if (input?.tagName !== "INPUT" || input.type !== "checkbox") {
+    throw new TypeError("enhanceSlidebox expects a checkbox input");
+  }
+  if (!Number.isFinite(threshold) || threshold < 0) {
+    throw new RangeError("threshold must be a non-negative number of pixels");
+  }
+  if (enhancements.has(input)) return enhancements.get(input);
+
+  const view = input.ownerDocument.defaultView;
+  if (!view?.PointerEvent || typeof input.setPointerCapture !== "function") {
+    throw new Error("Slidebox dragging requires a browser with Pointer Events and pointer capture");
+  }
+  const originalTouchAction = input.style.getPropertyValue("touch-action");
+  const originalTouchPriority = input.style.getPropertyPriority("touch-action");
+  let gesture;
+  let suppressed;
+  let suppressionTimer;
+  input.style.setProperty("touch-action", "pan-y pinch-zoom");
+
+  function disabled() { return input.matches(":disabled"); }
+  function clearSuppression() {
+    suppressed = undefined;
+    view.clearTimeout(suppressionTimer);
+  }
+  function suppressClick(id) {
+    clearSuppression();
+    suppressed = id;
+    suppressionTimer = view.setTimeout(clearSuppression, 500);
+  }
+  function finish(commit = false) {
+    if (!gesture) return;
+    const current = gesture;
+    gesture = undefined;
+    if (current.frame !== undefined) view.cancelAnimationFrame(current.frame);
+    if (current.dragging) {
+      if (current.attribute === null) input.removeAttribute("data-slidebox-dragging");
+      else input.setAttribute("data-slidebox-dragging", current.attribute);
+      if (current.progressStyle) input.style.setProperty("--slidebox-drag-progress", current.progressStyle, current.progressPriority);
+      else input.style.removeProperty("--slidebox-drag-progress");
+      if (current.stretchStyle) input.style.setProperty("--slidebox-drag-stretch", current.stretchStyle, current.stretchPriority);
+      else input.style.removeProperty("--slidebox-drag-stretch");
+      suppressClick(current.id);
+    }
+    if (input.hasPointerCapture(current.id)) input.releasePointerCapture(current.id);
+    if (commit && current.dragging && !disabled()) {
+      const checked = current.progress >= .5;
+      if (checked !== input.checked) {
+        input.checked = checked;
+        input.dispatchEvent(new view.Event("input", { bubbles: true }));
+        input.dispatchEvent(new view.Event("change", { bubbles: true }));
+      }
+    }
+  }
+  function down(event) {
+    if (gesture || disabled() || !event.isPrimary || event.button !== 0) return;
+    clearSuppression();
+    const box = input.getBoundingClientRect();
+    const travel = box.width - box.height;
+    if (travel <= 0) return;
+    const computed = view.getComputedStyle(input);
+    const deformation = Number.parseFloat(computed.getPropertyValue("--_deform")) || 0;
+    const durationValue = computed.getPropertyValue("--_duration").trim();
+    const duration = (Number.parseFloat(durationValue) || 0) * (durationValue.endsWith("ms") ? 1 : 1000);
+    gesture = {
+      id: event.pointerId, x: event.clientX, y: event.clientY, travel,
+      start: input.checked ? 1 : 0, progress: input.checked ? 1 : 0,
+      direction: computed.direction === "rtl" ? -1 : 1,
+      deform: view.matchMedia?.("(prefers-reduced-motion: reduce)").matches ? 0 : Math.max(0, Math.min(1, deformation)),
+      duration, stretch: 0,
+      attribute: input.getAttribute("data-slidebox-dragging"),
+      progressStyle: input.style.getPropertyValue("--slidebox-drag-progress"),
+      progressPriority: input.style.getPropertyPriority("--slidebox-drag-progress"),
+      stretchStyle: input.style.getPropertyValue("--slidebox-drag-stretch"),
+      stretchPriority: input.style.getPropertyPriority("--slidebox-drag-stretch"),
+      dragging: false,
+    };
+    input.setPointerCapture(event.pointerId);
+  }
+  function relax(now) {
+    if (!gesture) return;
+    const elapsed = gesture.lastFrame === undefined ? 16 : Math.max(0, now - gesture.lastFrame);
+    gesture.lastFrame = now;
+    gesture.stretch *= Math.exp(-elapsed / Math.max(16, gesture.duration * .35));
+    if (Math.abs(gesture.stretch) < .0001) gesture.stretch = 0;
+    input.style.setProperty("--slidebox-drag-stretch", String(gesture.stretch));
+    gesture.frame = gesture.stretch ? view.requestAnimationFrame(relax) : undefined;
+    if (!gesture.stretch) gesture.lastFrame = undefined;
+  }
+  function move(event) {
+    if (!gesture || event.pointerId !== gesture.id) return;
+    if (disabled()) { finish(); return; }
+    const dx = event.clientX - gesture.x;
+    const dy = event.clientY - gesture.y;
+    if (!gesture.dragging) {
+      // Leave vertical gestures to page scrolling and taps to native clicks.
+      if (Math.abs(dy) > threshold && Math.abs(dy) > Math.abs(dx)) { finish(); return; }
+      if (Math.abs(dx) <= threshold) return;
+      gesture.dragging = true;
+      input.setAttribute("data-slidebox-dragging", "");
+      input.focus({ preventScroll: true });
+    }
+    const progress = Math.max(0, Math.min(1, gesture.start + dx * gesture.direction / gesture.travel));
+    gesture.stretch = Math.max(-gesture.deform, Math.min(gesture.deform, gesture.stretch + progress - gesture.progress));
+    gesture.progress = progress;
+    input.style.setProperty("--slidebox-drag-progress", String(gesture.progress));
+    input.style.setProperty("--slidebox-drag-stretch", String(gesture.stretch));
+    if (gesture.stretch && gesture.frame === undefined) gesture.frame = view.requestAnimationFrame(relax);
+    event.preventDefault();
+  }
+  function up(event) {
+    if (!gesture || event.pointerId !== gesture.id) return;
+    move(event);
+    finish(true);
+  }
+  function cancel(event) {
+    if (gesture && event.pointerId === gesture.id) finish();
+  }
+  function click(event) {
+    // Keyboard activation has detail=0 and must retain native behavior.
+    if (suppressed === undefined || event.detail === 0) return;
+    if ("pointerId" in event && event.pointerId !== suppressed) return;
+    event.preventDefault();
+    event.stopImmediatePropagation();
+    clearSuppression();
+  }
+  function reset() { finish(); }
+  const form = input.form;
+  input.addEventListener("pointerdown", down);
+  input.addEventListener("pointermove", move);
+  input.addEventListener("pointerup", up);
+  input.addEventListener("pointercancel", cancel);
+  input.addEventListener("lostpointercapture", cancel);
+  input.addEventListener("click", click, true);
+  form?.addEventListener("reset", reset);
+
+  function destroy() {
+    finish();
+    clearSuppression();
+    input.removeEventListener("pointerdown", down);
+    input.removeEventListener("pointermove", move);
+    input.removeEventListener("pointerup", up);
+    input.removeEventListener("pointercancel", cancel);
+    input.removeEventListener("lostpointercapture", cancel);
+    input.removeEventListener("click", click, true);
+    form?.removeEventListener("reset", reset);
+    if (input.style.getPropertyValue("touch-action") === "pan-y pinch-zoom") {
+      if (originalTouchAction) input.style.setProperty("touch-action", originalTouchAction, originalTouchPriority);
+      else input.style.removeProperty("touch-action");
+    }
+    enhancements.delete(input);
+  }
+  enhancements.set(input, destroy);
+  return destroy;
+}

package/less/slidebox.less

@@ -65,6 +65,11 @@
   &:not(:checked):active::after { --_end: calc(1 - var(--_deform)); }
   &:checked:active::after { --_start: calc(1 - var(--_deform)); }
   &:disabled { cursor: not-allowed; opacity: .5; }
+  &[data-slidebox-dragging]::after {
+    margin-inline-start: ~"calc((1em * var(--_container-width-ratio) - 1em) * max(0, var(--slidebox-drag-progress) - max(0, var(--slidebox-drag-stretch, 0))) + var(--_thumb-spacing-ratio) * .5em)";
+    margin-inline-end: ~"calc((1em * var(--_container-width-ratio) - 1em) * max(0, 1 - var(--slidebox-drag-progress) - max(0, -1 * var(--slidebox-drag-stretch, 0))) + var(--_thumb-spacing-ratio) * .5em)";
+    transition: none;
+  }
   @media (forced-colors: active) {
     & { --_track: Field; --_border: ButtonBorder; --_off: FieldText; --_on: Highlight; }
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@monabbous/slidebox",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Elastic, system-color-aware CSS checkbox switch.",
   "license": "ISC",
   "style": "./dist/css/slidebox.css",
@@ -10,7 +10,8 @@
     "dist/css/slidebox.css",
     "scss/",
     "less/",
-    "tailwind/"
+    "tailwind/",
+    "experimental/"
   ],
   "publishConfig": {
     "access": "public"
@@ -34,6 +35,7 @@
   "scripts": {
     "build": "node scripts/build.mjs",
     "test": "node --test tests/*.test.mjs",
+    "test:browser": "playwright test",
     "prepack": "npm run build"
   },
   "keywords": [
@@ -47,6 +49,7 @@
     "system-colors"
   ],
   "devDependencies": {
+    "@playwright/test": "^1.64.1",
     "@tailwindcss/node": "^4.3.3",
     "less": "^4.9.1",
     "postcss": "^8.5.32",

package/scss/_mixins.scss

@@ -59,6 +59,11 @@ $defaults: () !default;
   &:not(:checked):active::after { --_end: calc(1 - var(--_deform)); }
   &:checked:active::after { --_start: calc(1 - var(--_deform)); }
   &:disabled { cursor: not-allowed; opacity: .5; }
+  &[data-slidebox-dragging]::after {
+    margin-inline-start: calc((1em * var(--_container-width-ratio) - 1em) * max(0, var(--slidebox-drag-progress) - max(0, var(--slidebox-drag-stretch, 0))) + var(--_thumb-spacing-ratio) * .5em);
+    margin-inline-end: calc((1em * var(--_container-width-ratio) - 1em) * max(0, 1 - var(--slidebox-drag-progress) - max(0, -1 * var(--slidebox-drag-stretch, 0))) + var(--_thumb-spacing-ratio) * .5em);
+    transition: none;
+  }
   @media (forced-colors: active) {
     & { --_track: Field; --_border: ButtonBorder; --_off: FieldText; --_on: Highlight; }
   }

package/tailwind/rules.json

@@ -60,6 +60,11 @@
     "cursor": "not-allowed",
     "opacity": ".5"
   },
+  "&[data-slidebox-dragging]::after": {
+    "margin-inline-start": "calc((1em * var(--_container-width-ratio) - 1em) * max(0, var(--slidebox-drag-progress) - max(0, var(--slidebox-drag-stretch, 0))) + var(--_thumb-spacing-ratio) * .5em)",
+    "margin-inline-end": "calc((1em * var(--_container-width-ratio) - 1em) * max(0, 1 - var(--slidebox-drag-progress) - max(0, -1 * var(--slidebox-drag-stretch, 0))) + var(--_thumb-spacing-ratio) * .5em)",
+    "transition": "none"
+  },
   "@media (forced-colors: active)": {
     "&": {
       "--_track": "Field",