@studiometa/js-toolkit 3.9.0-beta.2 → 4.0.0-alpha.0

package/dist/services/drag.js

@@ -0,0 +1,271 @@
+import { getSharedRuntimeSlot } from "../shared-runtime.js";
+import { defaultScheduler } from "../scheduler.js";
+import { createService, perTarget } from "./service.js";
+import { INERTIA_FRAME, clampDampFactor, inertiaDecay, inertiaFinalValue, inertiaStep } from "../utils/maths.js";
+import { createServiceMixin } from "./mixin.js";
+//#region src/services/drag.ts
+/**
+* Drag lifecycle modes: `idle → start → drag → drop → inertia → stop → idle`.
+* @link https://js-toolkit-v4.studiometa.dev/api/services/useDrag.html
+*/
+const DRAG_MODES = {
+	IDLE: "idle",
+	START: "start",
+	DRAG: "drag",
+	DROP: "drop",
+	INERTIA: "inertia",
+	STOP: "stop"
+};
+/**
+* Bounds on the interval between two velocity samples, in milliseconds, and
+* the weight the newest sample carries in the average.
+*
+* The floor is half a reference frame: anything faster is coalesced moves or a
+* synthetic event sharing a millisecond with the last, and dividing by it
+* reports a speed nothing physical reached. The ceiling is where two samples
+* stop describing one continuous movement.
+*/
+const MIN_SAMPLE = INERTIA_FRAME / 2;
+const MAX_SAMPLE = 100;
+const VELOCITY_SMOOTHING = .35;
+/**
+* Every option set gets its own service, but several of them can observe one
+* target at once. Their touch-action claims therefore share one owner: one
+* service leaving must not restore the target while another still needs it.
+*/
+const touchActionOwnership = /* @__PURE__ */ getSharedRuntimeSlot("service:drag:touch-action-ownership", 1, () => /* @__PURE__ */ new WeakMap());
+function applyTouchAction(target, ownership) {
+	if (ownership.requests.has("none") || ownership.requests.has("pan-x") && ownership.requests.has("pan-y")) target.style.touchAction = "none";
+	else if (ownership.requests.has("pan-x")) target.style.touchAction = "pan-x";
+	else target.style.touchAction = "pan-y";
+}
+/** Claim the native pan directions left free by one drag axis. */
+function claimTouchAction(target, touchAction) {
+	let ownership = touchActionOwnership.get(target);
+	if (!ownership) {
+		if (getComputedStyle(target).touchAction !== "auto") return () => {};
+		ownership = {
+			previous: target.style.touchAction,
+			requests: /* @__PURE__ */ new Map()
+		};
+		touchActionOwnership.set(target, ownership);
+	}
+	ownership.requests.set(touchAction, (ownership.requests.get(touchAction) ?? 0) + 1);
+	applyTouchAction(target, ownership);
+	let isActive = true;
+	return () => {
+		if (!isActive) return;
+		isActive = false;
+		const count = ownership.requests.get(touchAction) ?? 0;
+		if (count > 1) ownership.requests.set(touchAction, count - 1);
+		else ownership.requests.delete(touchAction);
+		if (ownership.requests.size > 0) {
+			applyTouchAction(target, ownership);
+			return;
+		}
+		target.style.touchAction = ownership.previous;
+		touchActionOwnership.delete(target);
+	};
+}
+function createDragService(target, options) {
+	const axis = options.axis === "x" || options.axis === "y" ? options.axis : "both";
+	const dampFactor = clampDampFactor(options.dampFactor ?? .85);
+	const dragThreshold = options.dragThreshold ?? 10;
+	const hasInertia = options.inertia ?? true;
+	const movesX = axis !== "y";
+	const movesY = axis !== "x";
+	const touchAction = axis === "x" ? "pan-y" : axis === "y" ? "pan-x" : "none";
+	const props = {
+		mode: DRAG_MODES.IDLE,
+		x: 0,
+		y: 0,
+		deltaX: 0,
+		deltaY: 0,
+		originX: 0,
+		originY: 0,
+		distanceX: 0,
+		distanceY: 0,
+		finalX: 0,
+		finalY: 0
+	};
+	return createService({
+		props: () => props,
+		hasProps: () => props.mode !== DRAG_MODES.IDLE,
+		start(emit) {
+			/** Publishing can synchronously release the last subscriber and stop this run. */
+			let isRunning = true;
+			let unsubscribeTicks = null;
+			/** Suppress only the trusted click synthesized for the current drag. */
+			let isClickSuppressed = false;
+			/**
+			* The velocity the coast is driven by, in pixels per millisecond.
+			*
+			* Kept beside the props rather than in them: `deltaX`/`deltaY` are what
+			* the last update moved, which is a different quantity and the one a
+			* subscriber asked for.
+			*/
+			let velocityX = 0;
+			let velocityY = 0;
+			/**
+			* When the velocity was last measured, on the same clock the events
+			* carry. `0` means no sample yet.
+			*/
+			let velocityTime = 0;
+			/** Held by the pointer: the two modes a gesture is alive in. */
+			const isGrabbing = () => props.mode === DRAG_MODES.START || props.mode === DRAG_MODES.DRAG;
+			const releaseTouchAction = claimTouchAction(target, touchAction);
+			function stopInertia() {
+				unsubscribeTicks?.();
+				unsubscribeTicks = null;
+			}
+			function stop() {
+				stopInertia();
+				props.x = props.finalX;
+				props.y = props.finalY;
+				props.deltaX = 0;
+				props.deltaY = 0;
+				props.distanceX = props.x - props.originX;
+				props.distanceY = props.y - props.originY;
+				props.mode = DRAG_MODES.STOP;
+				emit(props);
+				props.mode = DRAG_MODES.IDLE;
+			}
+			/** Measure smoothed velocity per millisecond with a bounded sample interval. */
+			function measureVelocity(timeStamp, deltaX, deltaY) {
+				const elapsed = velocityTime === 0 ? INERTIA_FRAME : timeStamp - velocityTime;
+				const interval = Math.min(Math.max(elapsed, MIN_SAMPLE), MAX_SAMPLE);
+				velocityTime = timeStamp;
+				const sampleX = deltaX / interval;
+				const sampleY = deltaY / interval;
+				velocityX = velocityX * .65 + sampleX * VELOCITY_SMOOTHING;
+				velocityY = velocityY * .65 + sampleY * VELOCITY_SMOOTHING;
+			}
+			function tick({ delta }) {
+				const stepX = inertiaStep(velocityX, dampFactor, delta);
+				const stepY = inertiaStep(velocityY, dampFactor, delta);
+				const decay = inertiaDecay(dampFactor, delta);
+				props.x += stepX;
+				props.y += stepY;
+				props.deltaX = stepX;
+				props.deltaY = stepY;
+				props.distanceX = props.x - props.originX;
+				props.distanceY = props.y - props.originY;
+				velocityX *= decay;
+				velocityY *= decay;
+				props.mode = DRAG_MODES.INERTIA;
+				emit(props);
+				const remaining = Math.max(Math.abs(props.finalX - props.x), Math.abs(props.finalY - props.y));
+				if (isRunning && remaining < .1) stop();
+			}
+			function startDrag(x, y) {
+				if (isGrabbing()) return;
+				stopInertia();
+				props.x = props.originX = props.finalX = x;
+				props.y = props.originY = props.finalY = y;
+				props.deltaX = props.deltaY = 0;
+				props.distanceX = props.distanceY = 0;
+				velocityX = velocityY = 0;
+				velocityTime = 0;
+				props.mode = DRAG_MODES.START;
+				emit(props);
+				if (!isRunning) return;
+				document.addEventListener("pointermove", onPointerMove, { passive: true });
+			}
+			function drag(event) {
+				const x = movesX ? event.clientX : props.x;
+				const y = movesY ? event.clientY : props.y;
+				props.deltaX = x - props.x;
+				props.deltaY = y - props.y;
+				measureVelocity(event.timeStamp, props.deltaX, props.deltaY);
+				props.x = props.finalX = x;
+				props.y = props.finalY = y;
+				props.distanceX = props.x - props.originX;
+				props.distanceY = props.y - props.originY;
+				props.mode = DRAG_MODES.DRAG;
+				if (Math.abs(props.distanceX) > dragThreshold || Math.abs(props.distanceY) > dragThreshold) isClickSuppressed = true;
+				emit(props);
+			}
+			/** Use the ending event timestamp so velocity and idle time use one clock. */
+			function drop(timeStamp) {
+				if (!isGrabbing()) return;
+				document.removeEventListener("pointermove", onPointerMove);
+				props.mode = DRAG_MODES.DROP;
+				const idle = velocityTime === 0 ? 0 : timeStamp - velocityTime;
+				const idleDecay = inertiaDecay(dampFactor, idle);
+				velocityX *= idleDecay;
+				velocityY *= idleDecay;
+				props.finalX = inertiaFinalValue(props.x, velocityX, dampFactor);
+				props.finalY = inertiaFinalValue(props.y, velocityY, dampFactor);
+				emit(props);
+				if (!isRunning) return;
+				if (!hasInertia) {
+					stop();
+					return;
+				}
+				unsubscribeTicks = defaultScheduler.tick(tick);
+			}
+			function onPointerMove(event) {
+				const pointerEvent = event;
+				if (pointerEvent.buttons === 1) drag(pointerEvent);
+				else drop(pointerEvent.timeStamp);
+			}
+			function onPointerDown(event) {
+				const pointerEvent = event;
+				if (pointerEvent.button === 0) {
+					isClickSuppressed = false;
+					startDrag(pointerEvent.clientX, pointerEvent.clientY);
+				}
+			}
+			function onDragStart(event) {
+				event.preventDefault();
+			}
+			function onClick(event) {
+				if (!isClickSuppressed || !event.isTrusted || event.detail === 0) return;
+				event.stopImmediatePropagation();
+				event.preventDefault();
+			}
+			function onPointerUp(event) {
+				drop(event.timeStamp);
+			}
+			target.addEventListener("pointerdown", onPointerDown, { passive: true });
+			target.addEventListener("dragstart", onDragStart, { capture: true });
+			target.addEventListener("click", onClick, { capture: true });
+			window.addEventListener("pointerup", onPointerUp, { passive: true });
+			window.addEventListener("pointercancel", onPointerUp, { passive: true });
+			return () => {
+				isRunning = false;
+				isClickSuppressed = false;
+				releaseTouchAction();
+				stopInertia();
+				props.mode = DRAG_MODES.IDLE;
+				document.removeEventListener("pointermove", onPointerMove);
+				target.removeEventListener("pointerdown", onPointerDown);
+				target.removeEventListener("dragstart", onDragStart, { capture: true });
+				target.removeEventListener("click", onClick, { capture: true });
+				window.removeEventListener("pointerup", onPointerUp);
+				window.removeEventListener("pointercancel", onPointerUp);
+			};
+		}
+	});
+}
+const dragServices = /* @__PURE__ */ getSharedRuntimeSlot("service:drag", 1, () => perTarget(createDragService));
+/**
+* Use one shared drag service per target and option set.
+* @link https://js-toolkit-v4.studiometa.dev/api/services/useDrag.html
+*/
+function useDrag(target, options = {}) {
+	return dragServices(target, options);
+}
+/**
+* Subscribe `dragged()` to the drag service for each mount cycle. The root element is the default target.
+* @link https://js-toolkit-v4.studiometa.dev/api/services/mixins.html
+*/
+const withDrag = /* @__PURE__ */ createServiceMixin({
+	hook: "dragged",
+	target: (instance) => instance.$el,
+	use: (target, options) => useDrag(target, options)
+});
+//#endregion
+export { DRAG_MODES, useDrag, withDrag };
+
+//# sourceMappingURL=drag.js.map

package/dist/services/drag.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"drag.js","names":[],"sources":["../../src/services/drag.ts"],"sourcesContent":["import {\n  clampDampFactor,\n  DEFAULT_DAMP_FACTOR,\n  inertiaDecay,\n  inertiaFinalValue,\n  inertiaStep,\n  INERTIA_FRAME,\n} from '../utils/maths.js';\nimport { defaultScheduler, type TickProps } from '../scheduler.js';\nimport { getSharedRuntimeSlot } from '../shared-runtime.js';\nimport { createServiceMixin, type ServiceHandles, type ServiceMixinOptions } from './mixin.js';\nimport { createService, perTarget, type MutableProps, type Service } from './service.js';\n\n/** Anything that can be grabbed: an HTML element, or an SVG one. */\nexport type DragTarget = HTMLElement | SVGElement;\n\n/**\n * Drag lifecycle modes: `idle → start → drag → drop → inertia → stop → idle`.\n * @link https://js-toolkit-v4.studiometa.dev/api/services/useDrag.html\n */\nexport const DRAG_MODES = {\n  IDLE: 'idle',\n  START: 'start',\n  DRAG: 'drag',\n  DROP: 'drop',\n  INERTIA: 'inertia',\n  STOP: 'stop',\n} as const;\n\n/** One of {@link DRAG_MODES}. */\nexport type DragMode = (typeof DRAG_MODES)[keyof typeof DRAG_MODES];\n\n/** Drag state for both viewport axes. */\nexport interface DragProps {\n  readonly mode: DragMode;\n  /** Current position in the viewport. */\n  readonly x: number;\n  readonly y: number;\n  /** Movement since the previous update. */\n  readonly deltaX: number;\n  readonly deltaY: number;\n  /** Where the drag started. */\n  readonly originX: number;\n  readonly originY: number;\n  /** Distance from the origin to the current position. */\n  readonly distanceX: number;\n  readonly distanceY: number;\n  /** Position the inertia is heading to. */\n  readonly finalX: number;\n  readonly finalY: number;\n}\n\n/**\n * Bounds on the interval between two velocity samples, in milliseconds, and\n * the weight the newest sample carries in the average.\n *\n * The floor is half a reference frame: anything faster is coalesced moves or a\n * synthetic event sharing a millisecond with the last, and dividing by it\n * reports a speed nothing physical reached. The ceiling is where two samples\n * stop describing one continuous movement.\n */\nconst MIN_SAMPLE = INERTIA_FRAME / 2;\nconst MAX_SAMPLE = 100;\nconst VELOCITY_SMOOTHING = 0.35;\n\nexport interface DragOptions {\n  /** Which movement the drag owns. Defaults to `both`. */\n  axis?: 'x' | 'y' | 'both';\n  /** How fast the inertia decays, from `0` (none) to `1` (endless). */\n  dampFactor?: number;\n  /** Movement past which a drag stops counting as a click, in pixels. */\n  dragThreshold?: number;\n  /** Whether to coast after `drop`. Defaults to `true`. */\n  inertia?: boolean;\n}\n\ntype OwnedTouchAction = 'none' | 'pan-x' | 'pan-y';\n\ninterface TouchActionOwnership {\n  readonly previous: string;\n  readonly requests: Map<OwnedTouchAction, number>;\n}\n\n/**\n * Every option set gets its own service, but several of them can observe one\n * target at once. Their touch-action claims therefore share one owner: one\n * service leaving must not restore the target while another still needs it.\n */\nconst touchActionOwnership = /* @__PURE__ */ getSharedRuntimeSlot(\n  'service:drag:touch-action-ownership',\n  1,\n  () => new WeakMap<DragTarget, TouchActionOwnership>(),\n);\n\nfunction applyTouchAction(target: DragTarget, ownership: TouchActionOwnership): void {\n  if (\n    ownership.requests.has('none') ||\n    (ownership.requests.has('pan-x') && ownership.requests.has('pan-y'))\n  ) {\n    target.style.touchAction = 'none';\n  } else if (ownership.requests.has('pan-x')) {\n    target.style.touchAction = 'pan-x';\n  } else {\n    target.style.touchAction = 'pan-y';\n  }\n}\n\n/** Claim the native pan directions left free by one drag axis. */\nfunction claimTouchAction(target: DragTarget, touchAction: OwnedTouchAction): () => void {\n  let ownership = touchActionOwnership.get(target);\n  if (!ownership) {\n    // Do not override consumer touch-action CSS.\n    if (getComputedStyle(target).touchAction !== 'auto') {\n      return () => {};\n    }\n    ownership = {\n      previous: target.style.touchAction,\n      requests: new Map(),\n    };\n    touchActionOwnership.set(target, ownership);\n  }\n\n  ownership.requests.set(touchAction, (ownership.requests.get(touchAction) ?? 0) + 1);\n  applyTouchAction(target, ownership);\n\n  let isActive = true;\n  return () => {\n    if (!isActive) {\n      return;\n    }\n    isActive = false;\n    const count = ownership.requests.get(touchAction) ?? 0;\n    if (count > 1) {\n      ownership.requests.set(touchAction, count - 1);\n    } else {\n      ownership.requests.delete(touchAction);\n    }\n    if (ownership.requests.size > 0) {\n      applyTouchAction(target, ownership);\n      return;\n    }\n    target.style.touchAction = ownership.previous;\n    touchActionOwnership.delete(target);\n  };\n}\n\nfunction createDragService(target: DragTarget, options: DragOptions): Service<DragProps> {\n  // Normalize values shared by projection and per-tick decay.\n  const axis = options.axis === 'x' || options.axis === 'y' ? options.axis : 'both';\n  const dampFactor = clampDampFactor(options.dampFactor ?? DEFAULT_DAMP_FACTOR);\n  const dragThreshold = options.dragThreshold ?? 10;\n  const hasInertia = options.inertia ?? true;\n  const movesX = axis !== 'y';\n  const movesY = axis !== 'x';\n  const touchAction = axis === 'x' ? 'pan-y' : axis === 'y' ? 'pan-x' : 'none';\n\n  const props: MutableProps<DragProps> = {\n    mode: DRAG_MODES.IDLE,\n    x: 0,\n    y: 0,\n    deltaX: 0,\n    deltaY: 0,\n    originX: 0,\n    originY: 0,\n    distanceX: 0,\n    distanceY: 0,\n    finalX: 0,\n    finalY: 0,\n  };\n\n  return createService<DragProps>({\n    props: () => props,\n    // `idle` is not an observed gesture value.\n    hasProps: () => props.mode !== DRAG_MODES.IDLE,\n    start(emit) {\n      /** Publishing can synchronously release the last subscriber and stop this run. */\n      let isRunning = true;\n      let unsubscribeTicks: (() => void) | null = null;\n      /** Suppress only the trusted click synthesized for the current drag. */\n      let isClickSuppressed = false;\n\n      /**\n       * The velocity the coast is driven by, in pixels per millisecond.\n       *\n       * Kept beside the props rather than in them: `deltaX`/`deltaY` are what\n       * the last update moved, which is a different quantity and the one a\n       * subscriber asked for.\n       */\n      let velocityX = 0;\n      let velocityY = 0;\n      /**\n       * When the velocity was last measured, on the same clock the events\n       * carry. `0` means no sample yet.\n       */\n      let velocityTime = 0;\n\n      /** Held by the pointer: the two modes a gesture is alive in. */\n      const isGrabbing = () => props.mode === DRAG_MODES.START || props.mode === DRAG_MODES.DRAG;\n\n      // Claim required touch axes and restore the previous inline value after the final claim.\n      const releaseTouchAction = claimTouchAction(target, touchAction);\n\n      function stopInertia() {\n        unsubscribeTicks?.();\n        unsubscribeTicks = null;\n      }\n\n      function stop() {\n        stopInertia();\n        // Snap to the invariant projected destination.\n        props.x = props.finalX;\n        props.y = props.finalY;\n        props.deltaX = 0;\n        props.deltaY = 0;\n        props.distanceX = props.x - props.originX;\n        props.distanceY = props.y - props.originY;\n        props.mode = DRAG_MODES.STOP;\n        emit(props);\n        // `stop` is announced once; `idle` is what the props rest on.\n        props.mode = DRAG_MODES.IDLE;\n      }\n\n      /** Measure smoothed velocity per millisecond with a bounded sample interval. */\n      function measureVelocity(timeStamp: number, deltaX: number, deltaY: number) {\n        const elapsed = velocityTime === 0 ? INERTIA_FRAME : timeStamp - velocityTime;\n        const interval = Math.min(Math.max(elapsed, MIN_SAMPLE), MAX_SAMPLE);\n        velocityTime = timeStamp;\n        const sampleX = deltaX / interval;\n        const sampleY = deltaY / interval;\n        velocityX = velocityX * (1 - VELOCITY_SMOOTHING) + sampleX * VELOCITY_SMOOTHING;\n        velocityY = velocityY * (1 - VELOCITY_SMOOTHING) + sampleY * VELOCITY_SMOOTHING;\n      }\n\n      // Integrate inertia from elapsed frame time, not frame count.\n      function tick({ delta }: TickProps) {\n        const stepX = inertiaStep(velocityX, dampFactor, delta);\n        const stepY = inertiaStep(velocityY, dampFactor, delta);\n        const decay = inertiaDecay(dampFactor, delta);\n\n        props.x += stepX;\n        props.y += stepY;\n        props.deltaX = stepX;\n        props.deltaY = stepY;\n        props.distanceX = props.x - props.originX;\n        props.distanceY = props.y - props.originY;\n        velocityX *= decay;\n        velocityY *= decay;\n        props.mode = DRAG_MODES.INERTIA;\n        emit(props);\n\n        // Stop by remaining distance, not the last step size.\n        const remaining = Math.max(\n          Math.abs(props.finalX - props.x),\n          Math.abs(props.finalY - props.y),\n        );\n        if (isRunning && remaining < 0.1) {\n          stop();\n        }\n      }\n\n      function startDrag(x: number, y: number) {\n        if (isGrabbing()) {\n          return;\n        }\n        stopInertia();\n        props.x = props.originX = props.finalX = x;\n        props.y = props.originY = props.finalY = y;\n        props.deltaX = props.deltaY = 0;\n        props.distanceX = props.distanceY = 0;\n        velocityX = velocityY = 0;\n        velocityTime = 0;\n        props.mode = DRAG_MODES.START;\n        emit(props);\n        if (!isRunning) {\n          return;\n        }\n        document.addEventListener('pointermove', onPointerMove, { passive: true });\n      }\n\n      function drag(event: PointerEvent) {\n        const x = movesX ? event.clientX : props.x;\n        const y = movesY ? event.clientY : props.y;\n        props.deltaX = x - props.x;\n        props.deltaY = y - props.y;\n        measureVelocity(event.timeStamp, props.deltaX, props.deltaY);\n        props.x = props.finalX = x;\n        props.y = props.finalY = y;\n        props.distanceX = props.x - props.originX;\n        props.distanceY = props.y - props.originY;\n        props.mode = DRAG_MODES.DRAG;\n        if (\n          Math.abs(props.distanceX) > dragThreshold ||\n          Math.abs(props.distanceY) > dragThreshold\n        ) {\n          isClickSuppressed = true;\n        }\n        emit(props);\n      }\n\n      /** Use the ending event timestamp so velocity and idle time use one clock. */\n      function drop(timeStamp: number) {\n        if (!isGrabbing()) {\n          return;\n        }\n        document.removeEventListener('pointermove', onPointerMove);\n        props.mode = DRAG_MODES.DROP;\n        // Decay velocity over the idle interval before projection.\n        const idle = velocityTime === 0 ? 0 : timeStamp - velocityTime;\n        const idleDecay = inertiaDecay(dampFactor, idle);\n        velocityX *= idleDecay;\n        velocityY *= idleDecay;\n        props.finalX = inertiaFinalValue(props.x, velocityX, dampFactor);\n        props.finalY = inertiaFinalValue(props.y, velocityY, dampFactor);\n        emit(props);\n        // `emit()` can release the final subscriber before inertia starts.\n        if (!isRunning) {\n          return;\n        }\n        // Without inertia, finish synchronously through the same stop contract.\n        if (!hasInertia) {\n          stop();\n          return;\n        }\n        unsubscribeTicks = defaultScheduler.tick(tick);\n      }\n\n      function onPointerMove(event: Event) {\n        const pointerEvent = event as PointerEvent;\n        // End when the pointer no longer reports the primary button.\n        if (pointerEvent.buttons === 1) {\n          drag(pointerEvent);\n        } else {\n          drop(pointerEvent.timeStamp);\n        }\n      }\n\n      function onPointerDown(event: Event) {\n        const pointerEvent = event as PointerEvent;\n        if (pointerEvent.button === 0) {\n          isClickSuppressed = false;\n          startDrag(pointerEvent.clientX, pointerEvent.clientY);\n        }\n      }\n\n      function onDragStart(event: Event) {\n        // The native drag-and-drop gesture would steal the pointer.\n        event.preventDefault();\n      }\n\n      function onClick(event: Event) {\n        // Keep programmatic clicks and keyboard activation; suppress only a trusted pointer click.\n        if (!isClickSuppressed || !event.isTrusted || (event as MouseEvent).detail === 0) {\n          return;\n        }\n        // Stop activation before descendant handlers run.\n        event.stopImmediatePropagation();\n        event.preventDefault();\n      }\n\n      function onPointerUp(event: Event) {\n        drop(event.timeStamp);\n      }\n\n      target.addEventListener('pointerdown', onPointerDown, { passive: true });\n      target.addEventListener('dragstart', onDragStart, { capture: true });\n      target.addEventListener('click', onClick, { capture: true });\n      // Window listeners end a drag released outside the target.\n      window.addEventListener('pointerup', onPointerUp, { passive: true });\n      window.addEventListener('pointercancel', onPointerUp, { passive: true });\n\n      return () => {\n        isRunning = false;\n        isClickSuppressed = false;\n        releaseTouchAction();\n        stopInertia();\n        // Reset the gesture when the final subscriber leaves.\n        props.mode = DRAG_MODES.IDLE;\n        document.removeEventListener('pointermove', onPointerMove);\n        target.removeEventListener('pointerdown', onPointerDown);\n        target.removeEventListener('dragstart', onDragStart, { capture: true });\n        target.removeEventListener('click', onClick, { capture: true });\n        window.removeEventListener('pointerup', onPointerUp);\n        window.removeEventListener('pointercancel', onPointerUp);\n      };\n    },\n  });\n}\n\nconst dragServices = /* @__PURE__ */ getSharedRuntimeSlot('service:drag', 1, () =>\n  perTarget(createDragService),\n);\n\n/**\n * Use one shared drag service per target and option set.\n * @link https://js-toolkit-v4.studiometa.dev/api/services/useDrag.html\n */\nexport function useDrag(target: DragTarget, options: DragOptions = {}): Service<DragProps> {\n  return dragServices(target, options);\n}\n\n/** The method `withDrag()` subscribes for the component. */\nexport interface DragHook {\n  dragged?(props: DragProps): void;\n}\n\nexport type DragMixinOptions = DragOptions & ServiceMixinOptions<DragTarget>;\n\n/**\n * Subscribe `dragged()` to the drag service for each mount cycle. The root element is the default target.\n * @link https://js-toolkit-v4.studiometa.dev/api/services/mixins.html\n */\nexport const withDrag = /* @__PURE__ */ createServiceMixin<\n  DragHook & ServiceHandles<'dragged'>,\n  DragTarget,\n  DragOptions\n>({\n  hook: 'dragged',\n  target: (instance) => instance.$el,\n  use: (target, options) => useDrag(target, options),\n});\n"],"mappings":"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"}

package/dist/services/in-view.d.ts

@@ -0,0 +1,26 @@
+import { Service } from "./service.js";
+import { ServiceHandles, ServiceMixin, ServiceMixinOptions } from "./mixin.js";
+//#region src/services/in-view.d.ts
+interface InViewProps {
+  /** Whether the target intersects its root, as the latest entry reports it. */
+  readonly isInView: boolean;
+  /** The latest entry, or `null` until the observer first delivers one. */
+  readonly entry: IntersectionObserverEntry | null;
+}
+/**
+ * Observe intersection through one lazy service per target and observer options.
+ * @link https://js-toolkit-v4.studiometa.dev/api/services/useInView.html
+ */
+declare function useInView(target: Element, init?: IntersectionObserverInit): Service<InViewProps>;
+/** The method `withInView()` subscribes for the component. */
+interface InViewHook {
+  intersected?(props: InViewProps): void;
+}
+type InViewMixinOptions = IntersectionObserverInit & ServiceMixinOptions<Element>;
+/**
+ * Subscribe `intersected()` for each mount cycle. The root element is the default target, and immediate delivery waits for a real observer entry.
+ * @link https://js-toolkit-v4.studiometa.dev/api/services/mixins.html
+ */
+declare const withInView: ServiceMixin<InViewHook & ServiceHandles<"intersected">, Element, IntersectionObserverInit>;
+//#endregion
+export { InViewHook, InViewMixinOptions, InViewProps, useInView, withInView };

package/dist/services/in-view.js

@@ -0,0 +1,83 @@
+import { getSharedRuntimeSlot } from "../shared-runtime.js";
+import { createService, perTarget, stableKey } from "./service.js";
+import { createServiceMixin } from "./mixin.js";
+//#region src/services/in-view.ts
+/** Give each observer root a stable serializable identity. */
+function rootId(root, identity) {
+	let id = identity.ids.get(root);
+	if (!id) {
+		id = identity.nextId;
+		identity.nextId += 1;
+		identity.ids.set(root, id);
+	}
+	return id;
+}
+/** Key an init by its meaning: the root as its stable id, the rest canonically. */
+function keyOf(init, identity) {
+	const { root, ...options } = init;
+	return stableKey(root ? rootId(root, identity) : null, options);
+}
+function createInViewService(target, requestedInit) {
+	const init = {
+		...requestedInit,
+		threshold: Array.isArray(requestedInit.threshold) ? [...requestedInit.threshold] : requestedInit.threshold
+	};
+	const props = {
+		isInView: false,
+		entry: null
+	};
+	let hasEntry = false;
+	return createService({
+		props: () => props,
+		hasProps: () => hasEntry,
+		start(emit) {
+			let isActive = true;
+			const observer = new IntersectionObserver((entries) => {
+				if (!isActive) return;
+				const entry = entries.findLast((candidate) => candidate.target === target);
+				if (!entry) return;
+				props.isInView = entry.isIntersecting;
+				props.entry = entry;
+				hasEntry = true;
+				emit(props);
+			}, init);
+			observer.observe(target);
+			return () => {
+				isActive = false;
+				observer.disconnect();
+				hasEntry = false;
+			};
+		}
+	});
+}
+const inViewState = /* @__PURE__ */ getSharedRuntimeSlot("service:in-view", 2, () => {
+	const rootIdentity = {
+		ids: /* @__PURE__ */ new WeakMap(),
+		nextId: 1
+	};
+	return {
+		rootIdentity,
+		services: perTarget(createInViewService, (init) => keyOf(init, rootIdentity))
+	};
+});
+/**
+* Observe intersection through one lazy service per target and observer options.
+* @link https://js-toolkit-v4.studiometa.dev/api/services/useInView.html
+*/
+function useInView(target, init = {}) {
+	return inViewState.services(target, init);
+}
+/**
+* Subscribe `intersected()` for each mount cycle. The root element is the default target, and immediate delivery waits for a real observer entry.
+* @link https://js-toolkit-v4.studiometa.dev/api/services/mixins.html
+*/
+const withInView = /* @__PURE__ */ createServiceMixin({
+	hook: "intersected",
+	target: (instance) => instance.$el,
+	defaultImmediate: true,
+	use: (target, options) => useInView(target, options)
+});
+//#endregion
+export { useInView, withInView };
+
+//# sourceMappingURL=in-view.js.map

package/dist/services/in-view.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"in-view.js","names":[],"sources":["../../src/services/in-view.ts"],"sourcesContent":["import { getSharedRuntimeSlot } from '../shared-runtime.js';\nimport { createServiceMixin, type ServiceHandles, type ServiceMixinOptions } from './mixin.js';\nimport { createService, perTarget, stableKey, type MutableProps, type Service } from './service.js';\n\nexport interface InViewProps {\n  /** Whether the target intersects its root, as the latest entry reports it. */\n  readonly isInView: boolean;\n  /** The latest entry, or `null` until the observer first delivers one. */\n  readonly entry: IntersectionObserverEntry | null;\n}\n\ninterface InViewRootIdentity {\n  readonly ids: WeakMap<object, number>;\n  nextId: number;\n}\n\ninterface InViewRuntimeState {\n  readonly rootIdentity: InViewRootIdentity;\n  readonly services: (target: Element, init: IntersectionObserverInit) => Service<InViewProps>;\n}\n\n/** Give each observer root a stable serializable identity. */\nfunction rootId(root: object, identity: InViewRootIdentity): number {\n  let id = identity.ids.get(root);\n  if (!id) {\n    id = identity.nextId;\n    identity.nextId += 1;\n    identity.ids.set(root, id);\n  }\n  return id;\n}\n\n/** Key an init by its meaning: the root as its stable id, the rest canonically. */\nfunction keyOf(init: IntersectionObserverInit, identity: InViewRootIdentity): string {\n  const { root, ...options } = init;\n  return stableKey(root ? rootId(root, identity) : null, options);\n}\n\nfunction createInViewService(\n  target: Element,\n  requestedInit: IntersectionObserverInit,\n): Service<InViewProps> {\n  // Copy values so caller mutation cannot change a lazily started observation.\n  const init: IntersectionObserverInit = {\n    ...requestedInit,\n    threshold: Array.isArray(requestedInit.threshold)\n      ? [...requestedInit.threshold]\n      : requestedInit.threshold,\n  };\n  const props: MutableProps<InViewProps> = {\n    isInView: false,\n    entry: null,\n  };\n  let hasEntry = false;\n\n  return createService<InViewProps>({\n    props: () => props,\n    // No props are current before the observer's first delivery.\n    hasProps: () => hasEntry,\n    start(emit) {\n      let isActive = true;\n      const observer = new IntersectionObserver((entries) => {\n        // `disconnect()` does not cancel queued callbacks; reject callbacks from older runs.\n        if (!isActive) {\n          return;\n        }\n        // Publish only this service's target entry from the platform batch.\n        const entry = entries.findLast((candidate) => candidate.target === target);\n        if (!entry) {\n          return;\n        }\n        props.isInView = entry.isIntersecting;\n        props.entry = entry;\n        hasEntry = true;\n        emit(props);\n      }, init);\n      observer.observe(target);\n\n      return () => {\n        isActive = false;\n        observer.disconnect();\n        // A new run waits for its own first entry.\n        hasEntry = false;\n      };\n    },\n  });\n}\n\nconst inViewState = /* @__PURE__ */ getSharedRuntimeSlot<InViewRuntimeState>(\n  'service:in-view',\n  2,\n  () => {\n    const rootIdentity: InViewRootIdentity = {\n      ids: new WeakMap(),\n      nextId: 1,\n    };\n    return {\n      rootIdentity,\n      services: perTarget(createInViewService, (init) => keyOf(init, rootIdentity)),\n    };\n  },\n);\n\n/**\n * Observe intersection through one lazy service per target and observer options.\n * @link https://js-toolkit-v4.studiometa.dev/api/services/useInView.html\n */\nexport function useInView(\n  target: Element,\n  init: IntersectionObserverInit = {},\n): Service<InViewProps> {\n  return inViewState.services(target, init);\n}\n\n/** The method `withInView()` subscribes for the component. */\nexport interface InViewHook {\n  intersected?(props: InViewProps): void;\n}\n\nexport type InViewMixinOptions = IntersectionObserverInit & ServiceMixinOptions<Element>;\n\n/**\n * Subscribe `intersected()` for each mount cycle. The root element is the default target, and immediate delivery waits for a real observer entry.\n * @link https://js-toolkit-v4.studiometa.dev/api/services/mixins.html\n */\nexport const withInView = /* @__PURE__ */ createServiceMixin<\n  InViewHook & ServiceHandles<'intersected'>,\n  Element,\n  IntersectionObserverInit\n>({\n  hook: 'intersected',\n  target: (instance) => instance.$el,\n  defaultImmediate: true,\n  use: (target, options) => useInView(target, options),\n});\n"],"mappings":";;;;;AAsBA,SAAS,OAAO,MAAc,UAAsC;CAClE,IAAI,KAAK,SAAS,IAAI,IAAI,IAAI;CAC9B,IAAI,CAAC,IAAI;EACP,KAAK,SAAS;EACd,SAAS,UAAU;EACnB,SAAS,IAAI,IAAI,MAAM,EAAE;CAC3B;CACA,OAAO;AACT;;AAGA,SAAS,MAAM,MAAgC,UAAsC;CACnF,MAAM,EAAE,MAAM,GAAG,YAAY;CAC7B,OAAO,UAAU,OAAO,OAAO,MAAM,QAAQ,IAAI,MAAM,OAAO;AAChE;AAEA,SAAS,oBACP,QACA,eACsB;CAEtB,MAAM,OAAiC;EACrC,GAAG;EACH,WAAW,MAAM,QAAQ,cAAc,SAAS,IAC5C,CAAC,GAAG,cAAc,SAAS,IAC3B,cAAc;CACpB;CACA,MAAM,QAAmC;EACvC,UAAU;EACV,OAAO;CACT;CACA,IAAI,WAAW;CAEf,OAAO,cAA2B;EAChC,aAAa;EAEb,gBAAgB;EAChB,MAAM,MAAM;GACV,IAAI,WAAW;GACf,MAAM,WAAW,IAAI,sBAAsB,YAAY;IAErD,IAAI,CAAC,UACH;IAGF,MAAM,QAAQ,QAAQ,UAAU,cAAc,UAAU,WAAW,MAAM;IACzE,IAAI,CAAC,OACH;IAEF,MAAM,WAAW,MAAM;IACvB,MAAM,QAAQ;IACd,WAAW;IACX,KAAK,KAAK;GACZ,GAAG,IAAI;GACP,SAAS,QAAQ,MAAM;GAEvB,aAAa;IACX,WAAW;IACX,SAAS,WAAW;IAEpB,WAAW;GACb;EACF;CACF,CAAC;AACH;AAEA,MAAM,cAA8B,qCAClC,mBACA,SACM;CACJ,MAAM,eAAmC;EACvC,qBAAK,IAAI,QAAQ;EACjB,QAAQ;CACV;CACA,OAAO;EACL;EACA,UAAU,UAAU,sBAAsB,SAAS,MAAM,MAAM,YAAY,CAAC;CAC9E;AACF,CACF;;;;;AAMA,SAAgB,UACd,QACA,OAAiC,CAAC,GACZ;CACtB,OAAO,YAAY,SAAS,QAAQ,IAAI;AAC1C;;;;;AAaA,MAAa,aAA6B,mCAIxC;CACA,MAAM;CACN,SAAS,aAAa,SAAS;CAC/B,kBAAkB;CAClB,MAAM,QAAQ,YAAY,UAAU,QAAQ,OAAO;AACrD,CAAC"}

package/dist/services/key.d.ts

@@ -0,0 +1,70 @@
+import { Service } from "./service.js";
+import { ServiceHandles, ServiceMixin, ServiceMixinOptions } from "./mixin.js";
+//#region src/services/key.d.ts
+/** Anything a key event reaches: the document, an element, or the window. */
+type KeyTarget = Document | Element | Window;
+/**
+ * The named keys, mapped to their `KeyboardEvent.key` value.
+ *
+ * The `key` value and not the `keyCode` of v3: that property is deprecated, and
+ * its numbers were never specified, so they differ between engines and between
+ * layouts. `event.key` is the character or the named key that the platform
+ * reports.
+ */
+declare const KEYS: {
+  readonly ENTER: 'Enter';
+  readonly SPACE: ' ';
+  readonly TAB: 'Tab';
+  readonly ESC: 'Escape';
+  readonly LEFT: 'ArrowLeft';
+  readonly UP: 'ArrowUp';
+  readonly RIGHT: 'ArrowRight';
+  readonly DOWN: 'ArrowDown';
+};
+/** One of {@link KEYS}. */
+type Key = (typeof KEYS)[keyof typeof KEYS];
+/** A name of {@link KEYS}. */
+type KeyName = keyof typeof KEYS;
+/**
+ * One boolean per named key, `true` for the key the event carries.
+ *
+ * Mapped over {@link KEYS} rather than written out, so the props cannot drift
+ * from the constant they describe.
+ */
+type KeyFlags = { readonly [Name in KeyName]: boolean; };
+/**
+ * Keyboard state for the last observed event.
+ *
+ * The eight named booleans of {@link KeyFlags} are a deliberate exception to
+ * the rule that nothing derivable is a field: each one is `KEYS[name] ===
+ * event.key`, and they are kept for call-site parity with v3, where
+ * `keyed({ ESC })` is how the ported components read the keyboard.
+ */
+interface KeyProps extends KeyFlags {
+  /** The source event, or `null` before observation and after release. */
+  readonly event: KeyboardEvent | null;
+  /** How many times the same key has been pressed in a row. */
+  readonly triggered: number;
+  readonly isDown: boolean;
+  readonly isUp: boolean;
+}
+/**
+ * Use one key service per target. Defaults to the document.
+ * @link https://js-toolkit-v4.studiometa.dev/api/services/useKey.html
+ */
+declare function useKey(target?: KeyTarget): Service<KeyProps>;
+/** The method `withKey()` subscribes for the component. */
+interface KeyHook {
+  keyed?(props: KeyProps): void;
+}
+type KeyMixinOptions = ServiceMixinOptions<KeyTarget>;
+/**
+ * Subscribe `keyed()` for each mount cycle. The document is the default target,
+ * as in v3 and as `withScroll` and `withResize` do for their own page-wide
+ * source. Scope it to a region with a target:
+ * `withKey(Base, { target: (instance) => instance.$refs.wrapper })`.
+ * @link https://js-toolkit-v4.studiometa.dev/api/services/mixins.html
+ */
+declare const withKey: ServiceMixin<KeyHook & ServiceHandles<"keyed">, KeyTarget, object>;
+//#endregion
+export { KEYS, Key, KeyFlags, KeyHook, KeyMixinOptions, KeyName, KeyProps, KeyTarget, useKey, withKey };

package/dist/services/key.js

@@ -0,0 +1,92 @@
+import { getSharedRuntimeSlot } from "../shared-runtime.js";
+import { createService, perTarget } from "./service.js";
+import { createServiceMixin } from "./mixin.js";
+//#region src/services/key.ts
+/**
+* The named keys, mapped to their `KeyboardEvent.key` value.
+*
+* The `key` value and not the `keyCode` of v3: that property is deprecated, and
+* its numbers were never specified, so they differ between engines and between
+* layouts. `event.key` is the character or the named key that the platform
+* reports.
+*/
+const KEYS = {
+	ENTER: "Enter",
+	SPACE: " ",
+	TAB: "Tab",
+	ESC: "Escape",
+	LEFT: "ArrowLeft",
+	UP: "ArrowUp",
+	RIGHT: "ArrowRight",
+	DOWN: "ArrowDown"
+};
+/**
+* The resting state: nothing observed, no key held.
+*
+* One helper for both ends of a run — it builds the props at creation, and
+* `Object.assign()` writes it back over the live object at teardown, so a
+* stopped service retains no event target.
+*/
+function restingProps(names) {
+	return {
+		event: null,
+		triggered: 0,
+		isDown: false,
+		isUp: false,
+		...Object.fromEntries(names.map((name) => [name, false]))
+	};
+}
+function createKeyService(target) {
+	const names = Object.keys(KEYS);
+	const props = restingProps(names);
+	function update(event) {
+		const isDown = event.type === "keydown";
+		const isRepeat = isDown && props.isDown && props.event?.key === event.key;
+		props.triggered = isRepeat ? props.triggered + 1 : 1;
+		props.event = event;
+		props.isDown = isDown;
+		props.isUp = !isDown;
+		for (const name of names) props[name] = KEYS[name] === event.key;
+		return props;
+	}
+	return createService({
+		props: () => props,
+		hasProps: () => props.event !== null,
+		start(emit) {
+			const onKey = (event) => {
+				emit(update(event));
+			};
+			target.addEventListener("keydown", onKey);
+			target.addEventListener("keyup", onKey);
+			return () => {
+				target.removeEventListener("keydown", onKey);
+				target.removeEventListener("keyup", onKey);
+				Object.assign(props, restingProps(names));
+			};
+		}
+	});
+}
+const keyServices = /* @__PURE__ */ getSharedRuntimeSlot("service:key", 1, () => perTarget(createKeyService));
+/**
+* Use one key service per target. Defaults to the document.
+* @link https://js-toolkit-v4.studiometa.dev/api/services/useKey.html
+*/
+function useKey(target = document) {
+	return keyServices(target);
+}
+/**
+* Subscribe `keyed()` for each mount cycle. The document is the default target,
+* as in v3 and as `withScroll` and `withResize` do for their own page-wide
+* source. Scope it to a region with a target:
+* `withKey(Base, { target: (instance) => instance.$refs.wrapper })`.
+* @link https://js-toolkit-v4.studiometa.dev/api/services/mixins.html
+*/
+const withKey = /* @__PURE__ */ createServiceMixin({
+	hook: "keyed",
+	target: () => document,
+	use: (target) => useKey(target)
+});
+//#endregion
+export { KEYS, useKey, withKey };
+
+//# sourceMappingURL=key.js.map

package/dist/services/key.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"key.js","names":[],"sources":["../../src/services/key.ts"],"sourcesContent":["import { getSharedRuntimeSlot } from '../shared-runtime.js';\nimport { createServiceMixin, type ServiceHandles, type ServiceMixinOptions } from './mixin.js';\nimport { createService, perTarget, type MutableProps, type Service } from './service.js';\n\n/** Anything a key event reaches: the document, an element, or the window. */\nexport type KeyTarget = Document | Element | Window;\n\n/**\n * The named keys, mapped to their `KeyboardEvent.key` value.\n *\n * The `key` value and not the `keyCode` of v3: that property is deprecated, and\n * its numbers were never specified, so they differ between engines and between\n * layouts. `event.key` is the character or the named key that the platform\n * reports.\n */\nexport const KEYS = {\n  ENTER: 'Enter',\n  SPACE: ' ',\n  TAB: 'Tab',\n  ESC: 'Escape',\n  LEFT: 'ArrowLeft',\n  UP: 'ArrowUp',\n  RIGHT: 'ArrowRight',\n  DOWN: 'ArrowDown',\n} as const;\n\n/** One of {@link KEYS}. */\nexport type Key = (typeof KEYS)[keyof typeof KEYS];\n\n/** A name of {@link KEYS}. */\nexport type KeyName = keyof typeof KEYS;\n\n/**\n * One boolean per named key, `true` for the key the event carries.\n *\n * Mapped over {@link KEYS} rather than written out, so the props cannot drift\n * from the constant they describe.\n */\nexport type KeyFlags = { readonly [Name in KeyName]: boolean };\n\n/**\n * Keyboard state for the last observed event.\n *\n * The eight named booleans of {@link KeyFlags} are a deliberate exception to\n * the rule that nothing derivable is a field: each one is `KEYS[name] ===\n * event.key`, and they are kept for call-site parity with v3, where\n * `keyed({ ESC })` is how the ported components read the keyboard.\n */\nexport interface KeyProps extends KeyFlags {\n  /** The source event, or `null` before observation and after release. */\n  readonly event: KeyboardEvent | null;\n  /** How many times the same key has been pressed in a row. */\n  readonly triggered: number;\n  readonly isDown: boolean;\n  readonly isUp: boolean;\n}\n\n/**\n * The resting state: nothing observed, no key held.\n *\n * One helper for both ends of a run — it builds the props at creation, and\n * `Object.assign()` writes it back over the live object at teardown, so a\n * stopped service retains no event target.\n */\nfunction restingProps(names: readonly KeyName[]): MutableProps<KeyProps> {\n  return {\n    event: null,\n    triggered: 0,\n    isDown: false,\n    isUp: false,\n    ...(Object.fromEntries(names.map((name) => [name, false])) as KeyFlags),\n  };\n}\n\nfunction createKeyService(target: KeyTarget): Service<KeyProps> {\n  // The name list is derived here and closed over, not at module scope: a\n  // computed top-level expression would tie the whole service to `KEYS` for a\n  // consumer importing only the constant.\n  const names = Object.keys(KEYS) as KeyName[];\n  const props = restingProps(names);\n\n  function update(event: KeyboardEvent): KeyProps {\n    const isDown = event.type === 'keydown';\n    // A repeat is one key going down while it is already down, read from the\n    // state the new event is about to overwrite. This fixes a v3 bug: v3\n    // incremented on any two consecutive keydowns, so holding `A` and then\n    // pressing `B` reported `2`. A different key, or any keyup, restarts it.\n    const isRepeat = isDown && props.isDown && props.event?.key === event.key;\n\n    props.triggered = isRepeat ? props.triggered + 1 : 1;\n    props.event = event;\n    props.isDown = isDown;\n    props.isUp = !isDown;\n    for (const name of names) {\n      props[name] = KEYS[name] === event.key;\n    }\n\n    return props;\n  }\n\n  return createService<KeyProps>({\n    props: () => props,\n    // The resting state is not an observed value.\n    hasProps: () => props.event !== null,\n    start(emit) {\n      const onKey = (event: Event) => {\n        emit(update(event as KeyboardEvent));\n      };\n\n      // Not passive: `trapFocus()` and every keyboard shortcut a subscriber\n      // writes call `preventDefault()` on the event they are handed.\n      // No capture: a descendant that handles its own keys and stops the\n      // propagation is respected.\n      target.addEventListener('keydown', onKey);\n      target.addEventListener('keyup', onKey);\n\n      return () => {\n        target.removeEventListener('keydown', onKey);\n        target.removeEventListener('keyup', onKey);\n        // Release the event so its target subtree can be collected, and leave\n        // no key reported as held for the next run.\n        Object.assign(props, restingProps(names));\n      };\n    },\n  });\n}\n\nconst keyServices = /* @__PURE__ */ getSharedRuntimeSlot('service:key', 1, () =>\n  perTarget(createKeyService),\n);\n\n/**\n * Use one key service per target. Defaults to the document.\n * @link https://js-toolkit-v4.studiometa.dev/api/services/useKey.html\n */\nexport function useKey(target: KeyTarget = document): Service<KeyProps> {\n  return keyServices(target);\n}\n\n/** The method `withKey()` subscribes for the component. */\nexport interface KeyHook {\n  keyed?(props: KeyProps): void;\n}\n\nexport type KeyMixinOptions = ServiceMixinOptions<KeyTarget>;\n\n/**\n * Subscribe `keyed()` for each mount cycle. The document is the default target,\n * as in v3 and as `withScroll` and `withResize` do for their own page-wide\n * source. Scope it to a region with a target:\n * `withKey(Base, { target: (instance) => instance.$refs.wrapper })`.\n * @link https://js-toolkit-v4.studiometa.dev/api/services/mixins.html\n */\nexport const withKey = /* @__PURE__ */ createServiceMixin<\n  KeyHook & ServiceHandles<'keyed'>,\n  KeyTarget\n>({\n  hook: 'keyed',\n  target: () => document,\n  use: (target) => useKey(target),\n});\n"],"mappings":";;;;;;;;;;;;AAeA,MAAa,OAAO;CAClB,OAAO;CACP,OAAO;CACP,KAAK;CACL,KAAK;CACL,MAAM;CACN,IAAI;CACJ,OAAO;CACP,MAAM;AACR;;;;;;;;AAwCA,SAAS,aAAa,OAAmD;CACvE,OAAO;EACL,OAAO;EACP,WAAW;EACX,QAAQ;EACR,MAAM;EACN,GAAI,OAAO,YAAY,MAAM,KAAK,SAAS,CAAC,MAAM,KAAK,CAAC,CAAC;CAC3D;AACF;AAEA,SAAS,iBAAiB,QAAsC;CAI9D,MAAM,QAAQ,OAAO,KAAK,IAAI;CAC9B,MAAM,QAAQ,aAAa,KAAK;CAEhC,SAAS,OAAO,OAAgC;EAC9C,MAAM,SAAS,MAAM,SAAS;EAK9B,MAAM,WAAW,UAAU,MAAM,UAAU,MAAM,OAAO,QAAQ,MAAM;EAEtE,MAAM,YAAY,WAAW,MAAM,YAAY,IAAI;EACnD,MAAM,QAAQ;EACd,MAAM,SAAS;EACf,MAAM,OAAO,CAAC;EACd,KAAK,MAAM,QAAQ,OACjB,MAAM,QAAQ,KAAK,UAAU,MAAM;EAGrC,OAAO;CACT;CAEA,OAAO,cAAwB;EAC7B,aAAa;EAEb,gBAAgB,MAAM,UAAU;EAChC,MAAM,MAAM;GACV,MAAM,SAAS,UAAiB;IAC9B,KAAK,OAAO,KAAsB,CAAC;GACrC;GAMA,OAAO,iBAAiB,WAAW,KAAK;GACxC,OAAO,iBAAiB,SAAS,KAAK;GAEtC,aAAa;IACX,OAAO,oBAAoB,WAAW,KAAK;IAC3C,OAAO,oBAAoB,SAAS,KAAK;IAGzC,OAAO,OAAO,OAAO,aAAa,KAAK,CAAC;GAC1C;EACF;CACF,CAAC;AACH;AAEA,MAAM,cAA8B,qCAAqB,eAAe,SACtE,UAAU,gBAAgB,CAC5B;;;;;AAMA,SAAgB,OAAO,SAAoB,UAA6B;CACtE,OAAO,YAAY,MAAM;AAC3B;;;;;;;;AAgBA,MAAa,UAA0B,mCAGrC;CACA,MAAM;CACN,cAAc;CACd,MAAM,WAAW,OAAO,MAAM;AAChC,CAAC"}

package/dist/services/media.d.ts

@@ -0,0 +1,18 @@
+import { Service } from "./service.js";
+//#region src/services/media.d.ts
+interface MediaQueryProps {
+  /** Whether the query matches now. */
+  readonly matches: boolean;
+}
+/**
+ * Use one shared service per normalized media query.
+ * @link https://js-toolkit-v4.studiometa.dev/api/services/useMediaQuery.html
+ */
+declare function useMediaQuery(query: string): Service<MediaQueryProps>;
+/**
+ * Use the `(prefers-reduced-motion: reduce)` media-query service.
+ * @link https://js-toolkit-v4.studiometa.dev/api/services/usePrefersReducedMotion.html
+ */
+declare function usePrefersReducedMotion(): Service<MediaQueryProps>;
+//#endregion
+export { MediaQueryProps, useMediaQuery, usePrefersReducedMotion };