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

package/dist/services/pointer.js

@@ -0,0 +1,167 @@
+import { getSharedRuntimeSlot } from "../shared-runtime.js";
+import { createService, perTarget } from "./service.js";
+import { createServiceMixin } from "./mixin.js";
+//#region src/services/pointer.ts
+/** Pointer event types observed by the service. */
+const EVENTS = [
+	"pointermove",
+	"pointerdown",
+	"pointerup",
+	"pointercancel"
+];
+function createPointerService() {
+	const props = {
+		event: null,
+		isDown: false,
+		x: window.innerWidth / 2,
+		y: window.innerHeight / 2,
+		deltaX: 0,
+		deltaY: 0,
+		maxX: window.innerWidth,
+		maxY: window.innerHeight,
+		progressX: .5,
+		progressY: .5
+	};
+	function update(event) {
+		const lastX = props.x;
+		const lastY = props.y;
+		props.event = event;
+		props.x = event.clientX;
+		props.y = event.clientY;
+		props.deltaX = props.x - lastX;
+		props.deltaY = props.y - lastY;
+		props.maxX = window.innerWidth;
+		props.maxY = window.innerHeight;
+		props.progressX = props.x / props.maxX;
+		props.progressY = props.y / props.maxY;
+		return props;
+	}
+	return createService({
+		props: () => props,
+		hasProps: () => props.event !== null,
+		start(emit) {
+			/** Track one pointer so other contacts cannot end its gesture. */
+			let activePointerId = null;
+			const onPointer = (event) => {
+				const pointerEvent = event;
+				const { pointerId, type } = pointerEvent;
+				if (type === "pointerdown") {
+					if (activePointerId !== null) return;
+					activePointerId = pointerId;
+				} else if (activePointerId !== null && pointerId !== activePointerId) return;
+				if (type !== "pointermove") props.isDown = type === "pointerdown";
+				if (type === "pointerup" || type === "pointercancel") activePointerId = null;
+				emit(update(pointerEvent));
+			};
+			for (const type of EVENTS) document.addEventListener(type, onPointer, {
+				passive: true,
+				capture: true
+			});
+			return () => {
+				for (const type of EVENTS) document.removeEventListener(type, onPointer, { capture: true });
+				props.event = null;
+			};
+		}
+	});
+}
+/**
+* Place the shared pointer in a target element's box.
+*
+* The maths belongs to the service rather than to each consumer, and so does
+* the layout read it needs: `getBoundingClientRect()` on every pointer event
+* would be one forced measurement per event, and a mouse reports up to 1000 of
+* them a second.
+*/
+function createElementPointerService(target) {
+	const pointer = usePointer();
+	const props = {
+		...pointer.props(),
+		relativeX: 0,
+		relativeY: 0,
+		relativeProgressX: 0,
+		relativeProgressY: 0
+	};
+	/**
+	* The target's box, kept between the events that can move it.
+	*
+	* It is held only while the service runs, because that is when the listeners
+	* which drop it are attached. The layout box is deliberately the frame of
+	* reference: a transform the consumer applies from `moved()` does not
+	* invalidate it, so a hover effect cannot feed its own output back in.
+	*/
+	let box = null;
+	let isRunning = false;
+	function measure() {
+		if (box) return box;
+		const rect = target.getBoundingClientRect();
+		if (isRunning) box = rect;
+		return rect;
+	}
+	function sync(source) {
+		props.event = source.event;
+		props.isDown = source.isDown;
+		props.x = source.x;
+		props.y = source.y;
+		props.deltaX = source.deltaX;
+		props.deltaY = source.deltaY;
+		props.maxX = source.maxX;
+		props.maxY = source.maxY;
+		props.progressX = source.progressX;
+		props.progressY = source.progressY;
+		const rect = measure();
+		props.relativeX = source.x - rect.left;
+		props.relativeY = source.y - rect.top;
+		props.relativeProgressX = rect.width === 0 ? 0 : props.relativeX / rect.width;
+		props.relativeProgressY = rect.height === 0 ? 0 : props.relativeY / rect.height;
+		return props;
+	}
+	return createService({
+		props: () => sync(pointer.props()),
+		hasProps: () => pointer.props().event !== null,
+		start(emit) {
+			isRunning = true;
+			const invalidate = () => {
+				box = null;
+			};
+			document.addEventListener("scroll", invalidate, {
+				passive: true,
+				capture: true
+			});
+			window.addEventListener("resize", invalidate, { passive: true });
+			const observer = new ResizeObserver(invalidate);
+			observer.observe(target);
+			const unsubscribe = pointer.subscribe((source) => emit(sync(source)));
+			return () => {
+				isRunning = false;
+				box = null;
+				unsubscribe();
+				observer.disconnect();
+				document.removeEventListener("scroll", invalidate, { capture: true });
+				window.removeEventListener("resize", invalidate);
+				props.event = null;
+			};
+		}
+	});
+}
+const pointerState = /* @__PURE__ */ getSharedRuntimeSlot("service:pointer", 2, () => ({
+	service: void 0,
+	services: perTarget(createElementPointerService)
+}));
+function usePointer(target) {
+	if (target) return pointerState.services(target);
+	pointerState.service ??= createPointerService();
+	return pointerState.service;
+}
+/**
+* Subscribe `moved()` to the pointer for each mount cycle. The root element is the default target, so a component reads the pointer both in the viewport and inside its own box.
+* @link https://js-toolkit-v4.studiometa.dev/api/services/mixins.html
+*/
+const withPointer = /* @__PURE__ */ createServiceMixin({
+	hook: "moved",
+	target: (instance) => instance.$el,
+	use: (target) => usePointer(target)
+});
+//#endregion
+export { usePointer, withPointer };
+
+//# sourceMappingURL=pointer.js.map

package/dist/services/pointer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pointer.js","names":[],"sources":["../../src/services/pointer.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/** Pointer state for both viewport axes. */\nexport interface PointerProps {\n  /** The source event, or `null` before observation and after release. */\n  readonly event: PointerEvent | null;\n  readonly isDown: boolean;\n  /** 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  /** Viewport size. */\n  readonly maxX: number;\n  readonly maxY: number;\n  /** Position over the viewport, from `0` to `1`. */\n  readonly progressX: number;\n  readonly progressY: number;\n}\n\n/** Pointer state placed in a target element's box, beside the viewport one. */\nexport interface ElementPointerProps extends PointerProps {\n  /** Position inside the target's box, from its top-left corner. */\n  readonly relativeX: number;\n  readonly relativeY: number;\n  /** Position over the target's box, from `0` to `1` inside it and past that range outside. */\n  readonly relativeProgressX: number;\n  readonly relativeProgressY: number;\n}\n\n/** Pointer event types observed by the service. */\nconst EVENTS = ['pointermove', 'pointerdown', 'pointerup', 'pointercancel'] as const;\n\nfunction createPointerService(): Service<PointerProps> {\n  // Use the viewport center until a pointer event is observed.\n  const x = window.innerWidth / 2;\n  const y = window.innerHeight / 2;\n  const props: MutableProps<PointerProps> = {\n    event: null,\n    isDown: false,\n    x,\n    y,\n    deltaX: 0,\n    deltaY: 0,\n    maxX: window.innerWidth,\n    maxY: window.innerHeight,\n    progressX: 0.5,\n    progressY: 0.5,\n  };\n\n  function update(event: PointerEvent): PointerProps {\n    const lastX = props.x;\n    const lastY = props.y;\n\n    props.event = event;\n    props.x = event.clientX;\n    props.y = event.clientY;\n    props.deltaX = props.x - lastX;\n    props.deltaY = props.y - lastY;\n    props.maxX = window.innerWidth;\n    props.maxY = window.innerHeight;\n    props.progressX = props.x / props.maxX;\n    props.progressY = props.y / props.maxY;\n\n    return props;\n  }\n\n  return createService<PointerProps>({\n    props: () => props,\n    // The centered initial position is not an observed value.\n    hasProps: () => props.event !== null,\n    start(emit) {\n      /** Track one pointer so other contacts cannot end its gesture. */\n      let activePointerId: number | null = null;\n\n      const onPointer = (event: Event) => {\n        const pointerEvent = event as PointerEvent;\n        const { pointerId, type } = pointerEvent;\n\n        if (type === 'pointerdown') {\n          // Ignore additional contacts during an active gesture.\n          if (activePointerId !== null) {\n            return;\n          }\n          activePointerId = pointerId;\n        } else if (activePointerId !== null && pointerId !== activePointerId) {\n          return;\n        }\n\n        // Read coordinates from every event because a touch tap can have no move event.\n        if (type !== 'pointermove') {\n          props.isDown = type === 'pointerdown';\n        }\n        if (type === 'pointerup' || type === 'pointercancel') {\n          activePointerId = null;\n        }\n        emit(update(pointerEvent));\n      };\n\n      // Capture events that descendants stop from propagating.\n      for (const type of EVENTS) {\n        document.addEventListener(type, onPointer, { passive: true, capture: true });\n      }\n\n      return () => {\n        for (const type of EVENTS) {\n          document.removeEventListener(type, onPointer, { capture: true });\n        }\n        // Release the event so its target subtree can be collected.\n        props.event = null;\n      };\n    },\n  });\n}\n\n/**\n * Place the shared pointer in a target element's box.\n *\n * The maths belongs to the service rather than to each consumer, and so does\n * the layout read it needs: `getBoundingClientRect()` on every pointer event\n * would be one forced measurement per event, and a mouse reports up to 1000 of\n * them a second.\n */\nfunction createElementPointerService(target: Element): Service<ElementPointerProps> {\n  const pointer = usePointer();\n  const props: MutableProps<ElementPointerProps> = {\n    ...pointer.props(),\n    relativeX: 0,\n    relativeY: 0,\n    relativeProgressX: 0,\n    relativeProgressY: 0,\n  };\n\n  /**\n   * The target's box, kept between the events that can move it.\n   *\n   * It is held only while the service runs, because that is when the listeners\n   * which drop it are attached. The layout box is deliberately the frame of\n   * reference: a transform the consumer applies from `moved()` does not\n   * invalidate it, so a hover effect cannot feed its own output back in.\n   */\n  let box: DOMRect | null = null;\n  let isRunning = false;\n\n  function measure(): DOMRect {\n    if (box) {\n      return box;\n    }\n    const rect = target.getBoundingClientRect();\n    if (isRunning) {\n      box = rect;\n    }\n    return rect;\n  }\n\n  function sync(source: PointerProps): ElementPointerProps {\n    props.event = source.event;\n    props.isDown = source.isDown;\n    props.x = source.x;\n    props.y = source.y;\n    props.deltaX = source.deltaX;\n    props.deltaY = source.deltaY;\n    props.maxX = source.maxX;\n    props.maxY = source.maxY;\n    props.progressX = source.progressX;\n    props.progressY = source.progressY;\n\n    const rect = measure();\n    props.relativeX = source.x - rect.left;\n    props.relativeY = source.y - rect.top;\n    // A collapsed box has no inside to be at a fraction of.\n    props.relativeProgressX = rect.width === 0 ? 0 : props.relativeX / rect.width;\n    props.relativeProgressY = rect.height === 0 ? 0 : props.relativeY / rect.height;\n\n    return props;\n  }\n\n  return createService<ElementPointerProps>({\n    // A cold read is the shared pointer's own answer, placed in the box.\n    props: () => sync(pointer.props()),\n    hasProps: () => pointer.props().event !== null,\n    start(emit) {\n      isRunning = true;\n      const invalidate = () => {\n        box = null;\n      };\n\n      // Capture reaches every scroller, the document included.\n      document.addEventListener('scroll', invalidate, { passive: true, capture: true });\n      window.addEventListener('resize', invalidate, { passive: true });\n      const observer = new ResizeObserver(invalidate);\n      observer.observe(target);\n      const unsubscribe = pointer.subscribe((source) => emit(sync(source)));\n\n      return () => {\n        isRunning = false;\n        box = null;\n        unsubscribe();\n        observer.disconnect();\n        document.removeEventListener('scroll', invalidate, { capture: true });\n        window.removeEventListener('resize', invalidate);\n        // Release the event so its target subtree can be collected.\n        props.event = null;\n      };\n    },\n  });\n}\n\ninterface PointerRuntimeState {\n  service: Service<PointerProps> | undefined;\n  readonly services: (target: Element) => Service<ElementPointerProps>;\n}\n\nconst pointerState = /* @__PURE__ */ getSharedRuntimeSlot<PointerRuntimeState>(\n  'service:pointer',\n  2,\n  () => ({\n    service: undefined,\n    services: perTarget(createElementPointerService),\n  }),\n);\n\n/**\n * Use the viewport-relative pointer service.\n * @link https://js-toolkit-v4.studiometa.dev/api/services/usePointer.html\n */\nexport function usePointer(): Service<PointerProps>;\n/** Use one lazy service per target, adding the pointer's position inside its box. */\nexport function usePointer(target: Element): Service<ElementPointerProps>;\nexport function usePointer(target?: Element): Service<PointerProps> | Service<ElementPointerProps> {\n  if (target) {\n    return pointerState.services(target);\n  }\n  pointerState.service ??= createPointerService();\n  return pointerState.service;\n}\n\n/** The method `withPointer()` subscribes for the component. */\nexport interface PointerHook {\n  moved?(props: ElementPointerProps): void;\n}\n\nexport type PointerMixinOptions = ServiceMixinOptions<Element>;\n\n/**\n * Subscribe `moved()` to the pointer for each mount cycle. The root element is the default target, so a component reads the pointer both in the viewport and inside its own box.\n * @link https://js-toolkit-v4.studiometa.dev/api/services/mixins.html\n */\nexport const withPointer = /* @__PURE__ */ createServiceMixin<\n  PointerHook & ServiceHandles<'moved'>,\n  Element\n>({\n  hook: 'moved',\n  target: (instance) => instance.$el,\n  use: (target) => usePointer(target),\n});\n"],"mappings":"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"}

package/dist/services/raf.d.ts

@@ -0,0 +1,27 @@
+import { TickProps } from "../scheduler.js";
+import { Service } from "./service.js";
+import { ServiceHandles, ServiceMixin, ServiceMixinOptions } from "./mixin.js";
+//#region src/services/raf.d.ts
+/** Scheduler tick props. */
+type RafProps = TickProps;
+/** A function run in the same frame's write phase. */
+type RafRender = (props: RafProps) => void;
+/** The frame service. Callbacks can return a write-phase function. */
+type RafService = Service<RafProps, void | RafRender>;
+/**
+ * Use the scheduler-backed frame service. Returned functions run in the write phase.
+ * @link https://js-toolkit-v4.studiometa.dev/api/services/useRaf.html
+ */
+declare function useRaf(): RafService;
+/** The method `withRaf()` subscribes for the component. */
+interface RafHook {
+  ticked?(props: RafProps): void | RafRender;
+}
+type RafMixinOptions = ServiceMixinOptions<void>;
+/**
+ * Subscribe `ticked()` to the frame service for each mount cycle.
+ * @link https://js-toolkit-v4.studiometa.dev/api/services/mixins.html
+ */
+declare const withRaf: ServiceMixin<RafHook & ServiceHandles<"ticked">, void, object>;
+//#endregion
+export { RafHook, RafMixinOptions, RafProps, RafRender, RafService, useRaf, withRaf };

package/dist/services/raf.js

@@ -0,0 +1,70 @@
+import { getSharedRuntimeSlot } from "../shared-runtime.js";
+import { defaultScheduler } from "../scheduler.js";
+import { createService } from "./service.js";
+import { createServiceMixin } from "./mixin.js";
+//#region src/services/raf.ts
+function createRafService() {
+	let props = {
+		time: performance.now(),
+		delta: 1e3 / 60
+	};
+	const renders = [];
+	const service = createService({
+		props: () => props,
+		hasProps: () => false,
+		start(emit) {
+			return defaultScheduler.tick((tickProps) => {
+				props = tickProps;
+				defaultScheduler.read(() => {
+					renders.length = 0;
+					emit(tickProps);
+					if (renders.length > 0) {
+						const batch = [...renders];
+						renders.length = 0;
+						defaultScheduler.write(() => {
+							for (const render of batch) render();
+						});
+					}
+				});
+			});
+		}
+	});
+	return {
+		props: () => service.props(),
+		subscribe(callback, options) {
+			let isSubscribed = true;
+			const unsubscribe = service.subscribe((tickProps) => {
+				const render = callback(tickProps);
+				if (typeof render === "function") renders.push(() => {
+					if (isSubscribed) render(tickProps);
+				});
+			}, options);
+			return () => {
+				isSubscribed = false;
+				unsubscribe();
+			};
+		}
+	};
+}
+const rafState = /* @__PURE__ */ getSharedRuntimeSlot("service:raf", 1, () => ({ service: void 0 }));
+/**
+* Use the scheduler-backed frame service. Returned functions run in the write phase.
+* @link https://js-toolkit-v4.studiometa.dev/api/services/useRaf.html
+*/
+function useRaf() {
+	rafState.service ??= createRafService();
+	return rafState.service;
+}
+/**
+* Subscribe `ticked()` to the frame service for each mount cycle.
+* @link https://js-toolkit-v4.studiometa.dev/api/services/mixins.html
+*/
+const withRaf = /* @__PURE__ */ createServiceMixin({
+	hook: "ticked",
+	target: () => void 0,
+	use: () => useRaf()
+});
+//#endregion
+export { useRaf, withRaf };
+
+//# sourceMappingURL=raf.js.map

package/dist/services/raf.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"raf.js","names":[],"sources":["../../src/services/raf.ts"],"sourcesContent":["import { defaultScheduler, type TickProps } from '../scheduler.js';\nimport { getSharedRuntimeSlot } from '../shared-runtime.js';\nimport { createServiceMixin, type ServiceHandles, type ServiceMixinOptions } from './mixin.js';\nimport { createService, type Service } from './service.js';\n\n/** Scheduler tick props. */\nexport type RafProps = TickProps;\n\n/** A function run in the same frame's write phase. */\nexport type RafRender = (props: RafProps) => void;\n\n/** The frame service. Callbacks can return a write-phase function. */\nexport type RafService = Service<RafProps, void | RafRender>;\n\nfunction createRafService(): RafService {\n  // Keep the initial delta in the scheduler's documented range.\n  let props: RafProps = { time: performance.now(), delta: 1000 / 60 };\n  // Track subscription state so removal between read and write cancels its render.\n  const renders: Array<() => void> = [];\n\n  const service = createService<RafProps>({\n    props: () => props,\n    // Frame props are current only during a tick.\n    hasProps: () => false,\n    start(emit) {\n      return defaultScheduler.tick((tickProps) => {\n        props = tickProps;\n        // Run all subscriber reads before their returned writes.\n        defaultScheduler.read(() => {\n          renders.length = 0;\n          emit(tickProps);\n          if (renders.length > 0) {\n            const batch = [...renders];\n            renders.length = 0;\n            defaultScheduler.write(() => {\n              for (const render of batch) {\n                render();\n              }\n            });\n          }\n        });\n      });\n    },\n  });\n\n  return {\n    props: () => service.props(),\n    subscribe(callback, options) {\n      // Do not write after the subscription is released.\n      let isSubscribed = true;\n      const unsubscribe = service.subscribe((tickProps) => {\n        const render = callback(tickProps);\n        if (typeof render === 'function') {\n          renders.push(() => {\n            if (isSubscribed) {\n              render(tickProps);\n            }\n          });\n        }\n      }, options);\n      return () => {\n        isSubscribed = false;\n        unsubscribe();\n      };\n    },\n  };\n}\n\nconst rafState = /* @__PURE__ */ getSharedRuntimeSlot<{\n  service: RafService | undefined;\n}>('service:raf', 1, () => ({ service: undefined }));\n\n/**\n * Use the scheduler-backed frame service. Returned functions run in the write phase.\n * @link https://js-toolkit-v4.studiometa.dev/api/services/useRaf.html\n */\nexport function useRaf(): RafService {\n  rafState.service ??= createRafService();\n  return rafState.service;\n}\n\n/** The method `withRaf()` subscribes for the component. */\nexport interface RafHook {\n  ticked?(props: RafProps): void | RafRender;\n}\n\nexport type RafMixinOptions = ServiceMixinOptions<void>;\n\n/**\n * Subscribe `ticked()` to the frame service for each mount cycle.\n * @link https://js-toolkit-v4.studiometa.dev/api/services/mixins.html\n */\nexport const withRaf = /* @__PURE__ */ createServiceMixin<RafHook & ServiceHandles<'ticked'>, void>(\n  {\n    hook: 'ticked',\n    target: () => undefined,\n    use: () => useRaf(),\n  },\n);\n"],"mappings":";;;;;AAcA,SAAS,mBAA+B;CAEtC,IAAI,QAAkB;EAAE,MAAM,YAAY,IAAI;EAAG,OAAO,MAAO;CAAG;CAElE,MAAM,UAA6B,CAAC;CAEpC,MAAM,UAAU,cAAwB;EACtC,aAAa;EAEb,gBAAgB;EAChB,MAAM,MAAM;GACV,OAAO,iBAAiB,MAAM,cAAc;IAC1C,QAAQ;IAER,iBAAiB,WAAW;KAC1B,QAAQ,SAAS;KACjB,KAAK,SAAS;KACd,IAAI,QAAQ,SAAS,GAAG;MACtB,MAAM,QAAQ,CAAC,GAAG,OAAO;MACzB,QAAQ,SAAS;MACjB,iBAAiB,YAAY;OAC3B,KAAK,MAAM,UAAU,OACnB,OAAO;MAEX,CAAC;KACH;IACF,CAAC;GACH,CAAC;EACH;CACF,CAAC;CAED,OAAO;EACL,aAAa,QAAQ,MAAM;EAC3B,UAAU,UAAU,SAAS;GAE3B,IAAI,eAAe;GACnB,MAAM,cAAc,QAAQ,WAAW,cAAc;IACnD,MAAM,SAAS,SAAS,SAAS;IACjC,IAAI,OAAO,WAAW,YACpB,QAAQ,WAAW;KACjB,IAAI,cACF,OAAO,SAAS;IAEpB,CAAC;GAEL,GAAG,OAAO;GACV,aAAa;IACX,eAAe;IACf,YAAY;GACd;EACF;CACF;AACF;AAEA,MAAM,WAA2B,qCAE9B,eAAe,UAAU,EAAE,SAAS,KAAA,EAAU,EAAE;;;;;AAMnD,SAAgB,SAAqB;CACnC,SAAS,YAAY,iBAAiB;CACtC,OAAO,SAAS;AAClB;;;;;AAaA,MAAa,UAA0B,mCACrC;CACE,MAAM;CACN,cAAc,KAAA;CACd,WAAW,OAAO;AACpB,CACF"}

package/dist/services/resize.d.ts

@@ -0,0 +1,38 @@
+import { Service } from "./service.js";
+import { ServiceHandles, ServiceMixin, ServiceMixinOptions } from "./mixin.js";
+//#region src/services/resize.d.ts
+type ResizeOrientation = 'square' | 'landscape' | 'portrait';
+interface ResizeProps {
+  readonly width: number;
+  readonly height: number;
+  /**
+   * Width over height, `0` for an element with no height — a collapsed
+   * element has no ratio, and `Infinity` or `NaN` propagate through every
+   * calculation a subscriber does with it.
+   */
+  readonly ratio: number;
+  readonly orientation: ResizeOrientation;
+}
+/**
+ * Use one resize service per element. Defaults to the document element.
+ * @link https://js-toolkit-v4.studiometa.dev/api/services/useResize.html
+ */
+declare function useResize(target?: Element): Service<ResizeProps>;
+/**
+ * Use the resize service for the viewport — `useResize()` named, the way
+ * VueUse splits `useElementSize(el)` from `useWindowSize()`.
+ * @link https://js-toolkit-v4.studiometa.dev/api/services/useWindowSize.html
+ */
+declare function useWindowSize(): Service<ResizeProps>;
+/** The method `withResize()` subscribes for the component. */
+interface ResizeHook {
+  resized?(props: ResizeProps): void;
+}
+type ResizeMixinOptions = ServiceMixinOptions<Element>;
+/**
+ * Subscribe `resized()` for each mount cycle. The document element is the default target.
+ * @link https://js-toolkit-v4.studiometa.dev/api/services/mixins.html
+ */
+declare const withResize: ServiceMixin<ResizeHook & ServiceHandles<"resized">, Element, object>;
+//#endregion
+export { ResizeHook, ResizeMixinOptions, ResizeOrientation, ResizeProps, useResize, useWindowSize, withResize };

package/dist/services/resize.js

@@ -0,0 +1,82 @@
+import { getSharedRuntimeSlot } from "../shared-runtime.js";
+import { createService, perTarget } from "./service.js";
+import { createServiceMixin } from "./mixin.js";
+//#region src/services/resize.ts
+/**
+* Read from the two dimensions rather than from the ratio, so a collapsed
+* element is still described by the side it is wider on.
+*/
+function orientationFor(width, height) {
+	if (width > height) return "landscape";
+	if (width < height) return "portrait";
+	return "square";
+}
+function ratioFor(width, height) {
+	return height === 0 ? 0 : width / height;
+}
+function createResizeService(target) {
+	const props = {
+		width: target.clientWidth,
+		height: target.clientHeight,
+		ratio: ratioFor(target.clientWidth, target.clientHeight),
+		orientation: orientationFor(target.clientWidth, target.clientHeight)
+	};
+	function update() {
+		props.width = target.clientWidth;
+		props.height = target.clientHeight;
+		props.ratio = ratioFor(props.width, props.height);
+		props.orientation = orientationFor(props.width, props.height);
+		return props;
+	}
+	return createService({
+		props: () => props,
+		start(emit) {
+			update();
+			const observer = new ResizeObserver(() => {
+				const { width, height } = props;
+				update();
+				if (props.width === width && props.height === height) return;
+				emit(props);
+			});
+			observer.observe(target);
+			const isViewport = target === document.documentElement;
+			const publish = () => {
+				emit(update());
+			};
+			if (isViewport) window.addEventListener("resize", publish, { passive: true });
+			return () => {
+				observer.disconnect();
+				if (isViewport) window.removeEventListener("resize", publish);
+			};
+		}
+	});
+}
+const resizeServices = /* @__PURE__ */ getSharedRuntimeSlot("service:resize", 1, () => perTarget(createResizeService));
+/**
+* Use one resize service per element. Defaults to the document element.
+* @link https://js-toolkit-v4.studiometa.dev/api/services/useResize.html
+*/
+function useResize(target = document.documentElement) {
+	return resizeServices(target);
+}
+/**
+* Use the resize service for the viewport — `useResize()` named, the way
+* VueUse splits `useElementSize(el)` from `useWindowSize()`.
+* @link https://js-toolkit-v4.studiometa.dev/api/services/useWindowSize.html
+*/
+function useWindowSize() {
+	return resizeServices(document.documentElement);
+}
+/**
+* Subscribe `resized()` for each mount cycle. The document element is the default target.
+* @link https://js-toolkit-v4.studiometa.dev/api/services/mixins.html
+*/
+const withResize = /* @__PURE__ */ createServiceMixin({
+	hook: "resized",
+	target: () => document.documentElement,
+	use: (target) => useResize(target)
+});
+//#endregion
+export { useResize, useWindowSize, withResize };
+
+//# sourceMappingURL=resize.js.map

package/dist/services/resize.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resize.js","names":[],"sources":["../../src/services/resize.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\nexport type ResizeOrientation = 'square' | 'landscape' | 'portrait';\n\nexport interface ResizeProps {\n  readonly width: number;\n  readonly height: number;\n  /**\n   * Width over height, `0` for an element with no height — a collapsed\n   * element has no ratio, and `Infinity` or `NaN` propagate through every\n   * calculation a subscriber does with it.\n   */\n  readonly ratio: number;\n  readonly orientation: ResizeOrientation;\n}\n\n/**\n * Read from the two dimensions rather than from the ratio, so a collapsed\n * element is still described by the side it is wider on.\n */\nfunction orientationFor(width: number, height: number): ResizeOrientation {\n  if (width > height) return 'landscape';\n  if (width < height) return 'portrait';\n  return 'square';\n}\n\nfunction ratioFor(width: number, height: number): number {\n  return height === 0 ? 0 : width / height;\n}\n\nfunction createResizeService(target: Element): Service<ResizeProps> {\n  const props: MutableProps<ResizeProps> = {\n    width: target.clientWidth,\n    height: target.clientHeight,\n    ratio: ratioFor(target.clientWidth, target.clientHeight),\n    orientation: orientationFor(target.clientWidth, target.clientHeight),\n  };\n\n  function update(): ResizeProps {\n    // `clientWidth` and `clientHeight` exclude classic scrollbars.\n    props.width = target.clientWidth;\n    props.height = target.clientHeight;\n    props.ratio = ratioFor(props.width, props.height);\n    props.orientation = orientationFor(props.width, props.height);\n    return props;\n  }\n\n  return createService<ResizeProps>({\n    props: () => props,\n    start(emit) {\n      // Refresh props before immediate delivery on each run.\n      update();\n\n      // ResizeObserver tracks element boxes. The window event also tracks viewport-only changes such as mobile toolbars and keyboards. Root observer updates publish only when reported viewport props change.\n      const observer = new ResizeObserver(() => {\n        const { width, height } = props;\n        update();\n        if (props.width === width && props.height === height) {\n          return;\n        }\n        emit(props);\n      });\n      observer.observe(target);\n      const isViewport = target === document.documentElement;\n      const publish = () => {\n        emit(update());\n      };\n      if (isViewport) {\n        window.addEventListener('resize', publish, { passive: true });\n      }\n\n      return () => {\n        observer.disconnect();\n        if (isViewport) {\n          window.removeEventListener('resize', publish);\n        }\n      };\n    },\n  });\n}\n\nconst resizeServices = /* @__PURE__ */ getSharedRuntimeSlot('service:resize', 1, () =>\n  perTarget(createResizeService),\n);\n\n/**\n * Use one resize service per element. Defaults to the document element.\n * @link https://js-toolkit-v4.studiometa.dev/api/services/useResize.html\n */\nexport function useResize(target: Element = document.documentElement): Service<ResizeProps> {\n  return resizeServices(target);\n}\n\n/**\n * Use the resize service for the viewport — `useResize()` named, the way\n * VueUse splits `useElementSize(el)` from `useWindowSize()`.\n * @link https://js-toolkit-v4.studiometa.dev/api/services/useWindowSize.html\n */\nexport function useWindowSize(): Service<ResizeProps> {\n  return resizeServices(document.documentElement);\n}\n\n/** The method `withResize()` subscribes for the component. */\nexport interface ResizeHook {\n  resized?(props: ResizeProps): void;\n}\n\nexport type ResizeMixinOptions = ServiceMixinOptions<Element>;\n\n/**\n * Subscribe `resized()` for each mount cycle. The document element is the default target.\n * @link https://js-toolkit-v4.studiometa.dev/api/services/mixins.html\n */\nexport const withResize = /* @__PURE__ */ createServiceMixin<\n  ResizeHook & ServiceHandles<'resized'>,\n  Element\n>({\n  hook: 'resized',\n  target: () => document.documentElement,\n  use: (target) => useResize(target),\n});\n"],"mappings":";;;;;;;;AAsBA,SAAS,eAAe,OAAe,QAAmC;CACxE,IAAI,QAAQ,QAAQ,OAAO;CAC3B,IAAI,QAAQ,QAAQ,OAAO;CAC3B,OAAO;AACT;AAEA,SAAS,SAAS,OAAe,QAAwB;CACvD,OAAO,WAAW,IAAI,IAAI,QAAQ;AACpC;AAEA,SAAS,oBAAoB,QAAuC;CAClE,MAAM,QAAmC;EACvC,OAAO,OAAO;EACd,QAAQ,OAAO;EACf,OAAO,SAAS,OAAO,aAAa,OAAO,YAAY;EACvD,aAAa,eAAe,OAAO,aAAa,OAAO,YAAY;CACrE;CAEA,SAAS,SAAsB;EAE7B,MAAM,QAAQ,OAAO;EACrB,MAAM,SAAS,OAAO;EACtB,MAAM,QAAQ,SAAS,MAAM,OAAO,MAAM,MAAM;EAChD,MAAM,cAAc,eAAe,MAAM,OAAO,MAAM,MAAM;EAC5D,OAAO;CACT;CAEA,OAAO,cAA2B;EAChC,aAAa;EACb,MAAM,MAAM;GAEV,OAAO;GAGP,MAAM,WAAW,IAAI,qBAAqB;IACxC,MAAM,EAAE,OAAO,WAAW;IAC1B,OAAO;IACP,IAAI,MAAM,UAAU,SAAS,MAAM,WAAW,QAC5C;IAEF,KAAK,KAAK;GACZ,CAAC;GACD,SAAS,QAAQ,MAAM;GACvB,MAAM,aAAa,WAAW,SAAS;GACvC,MAAM,gBAAgB;IACpB,KAAK,OAAO,CAAC;GACf;GACA,IAAI,YACF,OAAO,iBAAiB,UAAU,SAAS,EAAE,SAAS,KAAK,CAAC;GAG9D,aAAa;IACX,SAAS,WAAW;IACpB,IAAI,YACF,OAAO,oBAAoB,UAAU,OAAO;GAEhD;EACF;CACF,CAAC;AACH;AAEA,MAAM,iBAAiC,qCAAqB,kBAAkB,SAC5E,UAAU,mBAAmB,CAC/B;;;;;AAMA,SAAgB,UAAU,SAAkB,SAAS,iBAAuC;CAC1F,OAAO,eAAe,MAAM;AAC9B;;;;;;AAOA,SAAgB,gBAAsC;CACpD,OAAO,eAAe,SAAS,eAAe;AAChD;;;;;AAaA,MAAa,aAA6B,mCAGxC;CACA,MAAM;CACN,cAAc,SAAS;CACvB,MAAM,WAAW,UAAU,MAAM;AACnC,CAAC"}

package/dist/services/scroll-progress-offset.d.ts

@@ -0,0 +1,17 @@
+//#region src/services/scroll-progress-offset.d.ts
+/** One element or viewport edge token. */
+type OffsetValue = string | number;
+/** The start pair and end pair in `"<target> <viewport> / <target> <viewport>"`. */
+type NormalizedOffset = [[OffsetValue, OffsetValue], [OffsetValue, OffsetValue]];
+/** Parse the two target/viewport edge pairs. */
+declare function normalizeOffset(offsets: string): NormalizedOffset;
+/** Resolve one edge token against a box. */
+declare function getEdgeWithOffset(start: number, size: number, offset: OffsetValue): number;
+interface AxisRect {
+  position: number;
+  size: number;
+}
+/** Get the scroll positions where one axis starts and ends. */
+declare function getEdges(target: AxisRect, viewport: AxisRect, offset: NormalizedOffset): [number, number];
+//#endregion
+export { AxisRect, NormalizedOffset, OffsetValue, getEdgeWithOffset, getEdges, normalizeOffset };

package/dist/services/scroll-progress-offset.js

@@ -0,0 +1,35 @@
+//#region src/services/scroll-progress-offset.ts
+const NAMED = {
+	start: 0,
+	center: .5,
+	end: 1
+};
+const VIEWPORT_UNITS = {
+	vh: () => window.innerHeight,
+	vw: () => window.innerWidth,
+	vmin: () => Math.min(window.innerWidth, window.innerHeight),
+	vmax: () => Math.max(window.innerWidth, window.innerHeight)
+};
+/** Parse the two target/viewport edge pairs. */
+function normalizeOffset(offsets) {
+	return offsets.split("/").map((offset) => offset.trim().split(" ").slice(0, 2));
+}
+/** Resolve one edge token against a box. */
+function getEdgeWithOffset(start, size, offset) {
+	if (typeof offset === "number") return start + size * offset;
+	if (offset in NAMED) return start + size * NAMED[offset];
+	if (offset.endsWith("%")) return start + size * Number.parseFloat(offset) / 100;
+	const value = Number.parseFloat(offset);
+	if (Number.isNaN(value)) return start;
+	if (offset.endsWith("px")) return start + value;
+	for (const [unit, size100] of Object.entries(VIEWPORT_UNITS)) if (offset.endsWith(unit)) return start + value * size100() / 100;
+	return start + size * value;
+}
+/** Get the scroll positions where one axis starts and ends. */
+function getEdges(target, viewport, offset) {
+	return [getEdgeWithOffset(target.position, target.size, offset[0][0]) - getEdgeWithOffset(0, viewport.size, offset[0][1]), getEdgeWithOffset(target.position, target.size, offset[1][0]) - getEdgeWithOffset(0, viewport.size, offset[1][1])];
+}
+//#endregion
+export { getEdgeWithOffset, getEdges, normalizeOffset };
+
+//# sourceMappingURL=scroll-progress-offset.js.map

package/dist/services/scroll-progress-offset.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scroll-progress-offset.js","names":[],"sources":["../../src/services/scroll-progress-offset.ts"],"sourcesContent":["/** One element or viewport edge token. */\nexport type OffsetValue = string | number;\n\n/** The start pair and end pair in `\"<target> <viewport> / <target> <viewport>\"`. */\nexport type NormalizedOffset = [[OffsetValue, OffsetValue], [OffsetValue, OffsetValue]];\n\nconst NAMED: Record<string, number> = { start: 0, center: 0.5, end: 1 };\n\nconst VIEWPORT_UNITS: Record<string, () => number> = {\n  vh: () => window.innerHeight,\n  vw: () => window.innerWidth,\n  vmin: () => Math.min(window.innerWidth, window.innerHeight),\n  vmax: () => Math.max(window.innerWidth, window.innerHeight),\n};\n\n/** Parse the two target/viewport edge pairs. */\nexport function normalizeOffset(offsets: string): NormalizedOffset {\n  return offsets\n    .split('/')\n    .map((offset) => offset.trim().split(' ').slice(0, 2)) as NormalizedOffset;\n}\n\n/** Resolve one edge token against a box. */\nexport function getEdgeWithOffset(start: number, size: number, offset: OffsetValue): number {\n  if (typeof offset === 'number') {\n    return start + size * offset;\n  }\n\n  if (offset in NAMED) {\n    return start + size * NAMED[offset];\n  }\n\n  if (offset.endsWith('%')) {\n    return start + (size * Number.parseFloat(offset)) / 100;\n  }\n\n  const value = Number.parseFloat(offset);\n  if (Number.isNaN(value)) {\n    return start;\n  }\n\n  if (offset.endsWith('px')) {\n    return start + value;\n  }\n\n  for (const [unit, size100] of Object.entries(VIEWPORT_UNITS)) {\n    if (offset.endsWith(unit)) {\n      return start + (value * size100()) / 100;\n    }\n  }\n\n  return start + size * value;\n}\n\nexport interface AxisRect {\n  position: number;\n  size: number;\n}\n\n/** Get the scroll positions where one axis starts and ends. */\nexport function getEdges(\n  target: AxisRect,\n  viewport: AxisRect,\n  offset: NormalizedOffset,\n): [number, number] {\n  const start =\n    getEdgeWithOffset(target.position, target.size, offset[0][0]) -\n    getEdgeWithOffset(0, viewport.size, offset[0][1]);\n  const end =\n    getEdgeWithOffset(target.position, target.size, offset[1][0]) -\n    getEdgeWithOffset(0, viewport.size, offset[1][1]);\n  return [start, end];\n}\n"],"mappings":";AAMA,MAAM,QAAgC;CAAE,OAAO;CAAG,QAAQ;CAAK,KAAK;AAAE;AAEtE,MAAM,iBAA+C;CACnD,UAAU,OAAO;CACjB,UAAU,OAAO;CACjB,YAAY,KAAK,IAAI,OAAO,YAAY,OAAO,WAAW;CAC1D,YAAY,KAAK,IAAI,OAAO,YAAY,OAAO,WAAW;AAC5D;;AAGA,SAAgB,gBAAgB,SAAmC;CACjE,OAAO,QACJ,MAAM,GAAG,CAAC,CACV,KAAK,WAAW,OAAO,KAAK,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC;AACzD;;AAGA,SAAgB,kBAAkB,OAAe,MAAc,QAA6B;CAC1F,IAAI,OAAO,WAAW,UACpB,OAAO,QAAQ,OAAO;CAGxB,IAAI,UAAU,OACZ,OAAO,QAAQ,OAAO,MAAM;CAG9B,IAAI,OAAO,SAAS,GAAG,GACrB,OAAO,QAAS,OAAO,OAAO,WAAW,MAAM,IAAK;CAGtD,MAAM,QAAQ,OAAO,WAAW,MAAM;CACtC,IAAI,OAAO,MAAM,KAAK,GACpB,OAAO;CAGT,IAAI,OAAO,SAAS,IAAI,GACtB,OAAO,QAAQ;CAGjB,KAAK,MAAM,CAAC,MAAM,YAAY,OAAO,QAAQ,cAAc,GACzD,IAAI,OAAO,SAAS,IAAI,GACtB,OAAO,QAAS,QAAQ,QAAQ,IAAK;CAIzC,OAAO,QAAQ,OAAO;AACxB;;AAQA,SAAgB,SACd,QACA,UACA,QACkB;CAOlB,OAAO,CALL,kBAAkB,OAAO,UAAU,OAAO,MAAM,OAAO,EAAE,CAAC,EAAE,IAC5D,kBAAkB,GAAG,SAAS,MAAM,OAAO,EAAE,CAAC,EAAE,GAEhD,kBAAkB,OAAO,UAAU,OAAO,MAAM,OAAO,EAAE,CAAC,EAAE,IAC5D,kBAAkB,GAAG,SAAS,MAAM,OAAO,EAAE,CAAC,EAAE,CAChC;AACpB"}

package/dist/services/scroll-progress.d.ts

@@ -0,0 +1,41 @@
+import { Service } from "./service.js";
+import { ServiceHandles, ServiceMixin, ServiceMixinOptions } from "./mixin.js";
+//#region src/services/scroll-progress.d.ts
+interface ScrollProgressOptions {
+  /** Two target/viewport edge pairs: `"start end / end start"` by default. */
+  offset?: string;
+}
+/** The target's element-through-viewport position and progress on both axes. */
+interface ScrollProgressProps {
+  readonly startX: number;
+  readonly startY: number;
+  readonly endX: number;
+  readonly endY: number;
+  readonly currentX: number;
+  readonly currentY: number;
+  readonly progressX: number;
+  readonly progressY: number;
+}
+/** A DOM mutation returned by `scrolledInView()`, run in the write phase. */
+type ScrollProgressRender = () => void;
+/** The method `withScrollProgress()` subscribes for the component. */
+interface ScrollProgressHook {
+  scrolledInView?(props: ScrollProgressProps): void | ScrollProgressRender;
+}
+type ScrollProgressMixinOptions = ScrollProgressOptions & ServiceMixinOptions<Element>;
+/**
+ * Observe an element's progress through the viewport on both axes.
+ *
+ * The service is lazy and shared by target plus resolved offset. It measures
+ * geometry in the scheduler's read phase and releases its observers and shared
+ * source subscriptions with its last subscriber.
+ * @link https://js-toolkit-v4.studiometa.dev/api/services/useScrollProgress.html
+ */
+declare function useScrollProgress(target: Element, { offset }?: ScrollProgressOptions): Service<ScrollProgressProps>;
+/**
+ * Subscribe `scrolledInView()` to raw viewport progress for each mount cycle. Returned mutations run through the instance write lane.
+ * @link https://js-toolkit-v4.studiometa.dev/api/services/mixins.html
+ */
+declare const withScrollProgress: ServiceMixin<ScrollProgressHook & ServiceHandles<"scrolledInView">, Element, ScrollProgressOptions>;
+//#endregion
+export { ScrollProgressHook, ScrollProgressMixinOptions, ScrollProgressOptions, ScrollProgressProps, ScrollProgressRender, useScrollProgress, withScrollProgress };