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

package/dist/services/media.js

@@ -0,0 +1,50 @@
+import { getSharedRuntimeSlot } from "../shared-runtime.js";
+import { createService } from "./service.js";
+//#region src/services/media.ts
+/** The reduced-motion media query. */
+const REDUCED_MOTION = "(prefers-reduced-motion: reduce)";
+/** One lazy service per query string. */
+const services = /* @__PURE__ */ getSharedRuntimeSlot("service:media", 1, () => /* @__PURE__ */ new Map());
+function createMediaQueryService(query) {
+	const list = window.matchMedia(query);
+	const props = { matches: list.matches };
+	return createService({
+		props: () => {
+			props.matches = list.matches;
+			return props;
+		},
+		start(emit) {
+			const publish = () => {
+				props.matches = list.matches;
+				emit(props);
+			};
+			list.addEventListener("change", publish);
+			props.matches = list.matches;
+			return () => list.removeEventListener("change", publish);
+		}
+	});
+}
+/**
+* Use one shared service per normalized media query.
+* @link https://js-toolkit-v4.studiometa.dev/api/services/useMediaQuery.html
+*/
+function useMediaQuery(query) {
+	const key = query.trim();
+	let service = services.get(key);
+	if (!service) {
+		service = createMediaQueryService(key);
+		services.set(key, service);
+	}
+	return service;
+}
+/**
+* Use the `(prefers-reduced-motion: reduce)` media-query service.
+* @link https://js-toolkit-v4.studiometa.dev/api/services/usePrefersReducedMotion.html
+*/
+function usePrefersReducedMotion() {
+	return useMediaQuery(REDUCED_MOTION);
+}
+//#endregion
+export { useMediaQuery, usePrefersReducedMotion };
+
+//# sourceMappingURL=media.js.map

package/dist/services/media.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"media.js","names":[],"sources":["../../src/services/media.ts"],"sourcesContent":["import { getSharedRuntimeSlot } from '../shared-runtime.js';\nimport { createService, type MutableProps, type Service } from './service.js';\n\nexport interface MediaQueryProps {\n  /** Whether the query matches now. */\n  readonly matches: boolean;\n}\n\n/** The reduced-motion media query. */\nconst REDUCED_MOTION = '(prefers-reduced-motion: reduce)';\n\n/** One lazy service per query string. */\nconst services = /* @__PURE__ */ getSharedRuntimeSlot<Map<string, Service<MediaQueryProps>>>(\n  'service:media',\n  1,\n  () => new Map(),\n);\n\nfunction createMediaQueryService(query: string): Service<MediaQueryProps> {\n  // Reuse one `MediaQueryList` per query.\n  const list = window.matchMedia(query);\n  const props: MutableProps<MediaQueryProps> = { matches: list.matches };\n\n  return createService<MediaQueryProps>({\n    // Media-query state can be read without starting the service.\n    props: () => {\n      props.matches = list.matches;\n      return props;\n    },\n    start(emit) {\n      const publish = () => {\n        props.matches = list.matches;\n        emit(props);\n      };\n      // The platform emits only when the match changes.\n      list.addEventListener('change', publish);\n      props.matches = list.matches;\n      return () => list.removeEventListener('change', publish);\n    },\n  });\n}\n\n/**\n * Use one shared service per normalized media query.\n * @link https://js-toolkit-v4.studiometa.dev/api/services/useMediaQuery.html\n */\nexport function useMediaQuery(query: string): Service<MediaQueryProps> {\n  const key = query.trim();\n  let service = services.get(key);\n  if (!service) {\n    service = createMediaQueryService(key);\n    services.set(key, service);\n  }\n  return service;\n}\n\n/**\n * Use the `(prefers-reduced-motion: reduce)` media-query service.\n * @link https://js-toolkit-v4.studiometa.dev/api/services/usePrefersReducedMotion.html\n */\nexport function usePrefersReducedMotion(): Service<MediaQueryProps> {\n  return useMediaQuery(REDUCED_MOTION);\n}\n"],"mappings":";;;;AASA,MAAM,iBAAiB;;AAGvB,MAAM,WAA2B,qCAC/B,iBACA,yBACM,IAAI,IAAI,CAChB;AAEA,SAAS,wBAAwB,OAAyC;CAExE,MAAM,OAAO,OAAO,WAAW,KAAK;CACpC,MAAM,QAAuC,EAAE,SAAS,KAAK,QAAQ;CAErE,OAAO,cAA+B;EAEpC,aAAa;GACX,MAAM,UAAU,KAAK;GACrB,OAAO;EACT;EACA,MAAM,MAAM;GACV,MAAM,gBAAgB;IACpB,MAAM,UAAU,KAAK;IACrB,KAAK,KAAK;GACZ;GAEA,KAAK,iBAAiB,UAAU,OAAO;GACvC,MAAM,UAAU,KAAK;GACrB,aAAa,KAAK,oBAAoB,UAAU,OAAO;EACzD;CACF,CAAC;AACH;;;;;AAMA,SAAgB,cAAc,OAAyC;CACrE,MAAM,MAAM,MAAM,KAAK;CACvB,IAAI,UAAU,SAAS,IAAI,GAAG;CAC9B,IAAI,CAAC,SAAS;EACZ,UAAU,wBAAwB,GAAG;EACrC,SAAS,IAAI,KAAK,OAAO;CAC3B;CACA,OAAO;AACT;;;;;AAMA,SAAgB,0BAAoD;CAClE,OAAO,cAAc,cAAc;AACrC"}

package/dist/services/mixin.d.ts

@@ -0,0 +1,82 @@
+import { Base, BaseConstructor, BaseProps } from "../Base.js";
+import { Service } from "./service.js";
+import { Toggle } from "./toggle.js";
+//#region src/services/mixin.d.ts
+/**
+ * Options every service mixin accepts, on top of the ones its service takes.
+ */
+interface ServiceMixinOptions<Target, Host = Base> {
+  /**
+   * What to observe, resolved per instance when the subscription starts.
+   * Defaults to the service's own target — the window, the viewport, the
+   * component's root element.
+   *
+   * The resolver is typed against the host **as declared**, which is `Base` in
+   * `withDrag(Base, …)`: a mixin is applied while the extends clause of its
+   * class is still being evaluated, so it cannot be typed against the class
+   * being defined. A component reaching past `Base` therefore names the shape
+   * it needs — and because that is an assertion rather than a check, a
+   * resolver which comes back with nothing is reported (`service.missing-target`)
+   * instead of being passed to the service, where a default parameter would
+   * quietly observe the wrong thing.
+   */
+  target?: (instance: Host) => Target;
+  /** Do not subscribe on mount. Control the subscription through `this.$services.<hook>`. */
+  manual?: boolean;
+  /** Request current props when the subscription starts. */
+  immediate?: boolean;
+}
+/** Typed service controls keyed by hook name. Stacked mixins accumulate keys. */
+type ServiceHandles<Hook extends string> = {
+  readonly $services: { readonly [K in Hook]: Toggle; };
+};
+/**
+ * What a service declares to get a mixin.
+ */
+interface ServiceMixinDefinition<Target, Options> {
+  /** Default method name, e.g. `scrolled`. */
+  hook: string;
+  /** Default target, e.g. the window for the scroll service. */
+  target: (instance: Base) => Target;
+  /**
+   * Whether a subscription asks for current props when the caller does not
+   * choose. Most hooks wait for the next update; sources whose hook is about
+   * current state can opt in while still honouring an explicit `false`.
+   */
+  defaultImmediate?: boolean;
+  /**
+   * Service the method subscribes to, given the service half of the options.
+   *
+   * `Options` is the service's own option type, without the mixin's `target`,
+   * `manual` and `immediate`: they are stripped before the call and absent
+   * from the type, so forwarding the whole object cannot put a lifecycle
+   * choice into the service identity.
+   *
+   * Both service parameters are `unknown` here because most mixins forward
+   * whatever the hook returns without looking at it — the frame service is the
+   * one that reads it.
+   */
+  use: (target: Target, options: Options) => Service<unknown, unknown>;
+  /**
+   * Adapt a hook result when the service itself does not own it. This keeps a
+   * service-specific write convention in its definition without copying the
+   * mixin lifecycle.
+   */
+  handleResult?: (instance: Base, result: unknown) => void;
+}
+/** A service mixin used directly or as a class decorator. */
+interface ServiceMixin<Instance, Target, Options extends object = object> {
+  <T extends BaseConstructor>(BaseClass: T, options?: Options & ServiceMixinOptions<Target, InstanceType<T>>): MixedClass<T, Instance>;
+  (options?: Options & ServiceMixinOptions<Target>): <T extends BaseConstructor>(value: T, context: ClassDecoratorContext<T>) => MixedClass<T, Instance>;
+}
+/** Mixed class statics and a generic constructor that preserves component props. */
+type MixedClass<T extends BaseConstructor, Instance> = Pick<T, keyof T> & {
+  new <P extends BaseProps = BaseProps>(el: HTMLElement): InstanceType<T> & Base<P> & Instance;
+};
+/**
+ * Build a lifecycle-bound service mixin. Automatic subscriptions last for one mount cycle. Manual subscriptions also stop on unmount.
+ * @link https://js-toolkit-v4.studiometa.dev/api/services/createServiceMixin.html
+ */
+declare function createServiceMixin<Instance, Target, Options extends object = object>(definition: ServiceMixinDefinition<Target, Options>): ServiceMixin<Instance, Target, Options>;
+//#endregion
+export { MixedClass, ServiceHandles, ServiceMixin, ServiceMixinDefinition, ServiceMixinOptions, createServiceMixin };

package/dist/services/mixin.js

@@ -0,0 +1,141 @@
+import { warn } from "../diagnostics.js";
+import { toggle } from "./toggle.js";
+//#region src/services/mixin.ts
+/**
+* The keys of {@link ServiceMixinOptions}. They describe the subscription, not
+* the observation, so they belong to the mixin and never to the service.
+*/
+const MIXIN_OPTIONS = [
+	"target",
+	"manual",
+	"immediate"
+];
+/**
+* Split the service half out of what the caller wrote.
+*
+* A service is identified by the options it is handed, so a lifecycle key
+* reaching `use()` mints a service of its own: `withDrag(Base, { manual: true })`
+* bound a second drag service on the element the plain `withDrag(Base)` already
+* owned — two pointer listener sets, two window listener sets and two
+* `touch-action` claims. `Options` no longer holds those keys either, so
+* forwarding the whole object is now the correct call rather than the mistake.
+*
+* A key holding `undefined` goes with them: naming an option without a value
+* is the same request as not naming it, and the service key already reads it
+* that way.
+*/
+function serviceOptionsOf(options) {
+	const source = options;
+	const serviceOptions = {};
+	for (const key of Object.keys(source)) if (source[key] !== void 0 && !MIXIN_OPTIONS.includes(key)) serviceOptions[key] = source[key];
+	return serviceOptions;
+}
+/**
+* Build a lifecycle-bound service mixin. Automatic subscriptions last for one mount cycle. Manual subscriptions also stop on unmount.
+* @link https://js-toolkit-v4.studiometa.dev/api/services/createServiceMixin.html
+*/
+function createServiceMixin(definition) {
+	function apply(BaseClass, options) {
+		const { hook } = definition;
+		const declared = options.target;
+		const resolve = declared ?? definition.target;
+		const isManual = options.manual ?? false;
+		const serviceOptions = serviceOptionsOf(options);
+		return class extends BaseClass {
+			constructor(el) {
+				super(el);
+				const host = this;
+				const services = host.$services ??= {};
+				let pendingTarget;
+				const handle = toggle(() => {
+					const method = this[hook];
+					if (typeof method !== "function") return () => {};
+					return definition.use(pendingTarget, serviceOptions).subscribe((props) => {
+						const result = method.call(this, props);
+						if (definition.handleResult) {
+							definition.handleResult(this, result);
+							return;
+						}
+						return result;
+					}, { immediate: options.immediate ?? definition.defaultImmediate ?? false });
+				});
+				services[hook] = {
+					get isActive() {
+						return handle.isActive;
+					},
+					/**
+					* Validate before `toggle()` ever runs, so a rejected target leaves
+					* the handle exactly as inactive as one that was never started —
+					* `toggle()` has no channel for "declined", only for "subscribed" or
+					* "not yet", and a no-op cleanup would have been the first of those.
+					*/
+					start: () => {
+						const observed = resolve(this);
+						if (declared !== void 0 && (observed === void 0 || observed === null)) {
+							const instance = this;
+							warn("service.missing-target", `\`${hook}\` resolved no target on \`${instance.$config.name}\`. A resolver names a shape rather than checking it, so a renamed ref or a missing element arrives here as nothing — and a service with a default target would observe the wrong thing instead.`, {
+								component: instance.$config.name,
+								target: instance.$el
+							});
+							return;
+						}
+						pendingTarget = observed;
+						handle.start();
+					},
+					stop: handle.stop
+				};
+			}
+			/**
+			* Bind from `$mount()` rather than from `mounted()`.
+			*
+			* `mounted()` belongs to the component author. A mixin which occupied it
+			* needed every subclass to chain `super.mounted()`, and forgetting was
+			* total and silent: the subscription simply never happened, with no
+			* warning, no type error and no failing hook. `$mount()` is the
+			* framework's own method, so there is nothing left to chain.
+			*
+			* The subscription therefore starts once the whole `mounted()` has run,
+			* which is also when an `immediate` first delivery reaches a component
+			* that is fully set up. `$isMounted` is the guard, and it covers the
+			* case where there is nothing left to subscribe for: a hook, or a
+			* reversible strategy, which unmounted the instance mid-cycle.
+			*
+			* A hook which **threw** is deliberately not one of them. `#guard()`
+			* reports the failure and the cycle continues — the component stays
+			* mounted, its handlers stay bound and its option effects stay live — so
+			* withholding the subscription alone would make services the only
+			* subsystem treating a thrown `mounted()` as fatal.
+			*/
+			$mount() {
+				super.$mount();
+				if (!isManual && this.$isMounted) this.$services[hook].start();
+				return this;
+			}
+			/**
+			* Release before the cycle unwinds, so `unmounted()` sees the same
+			* stopped subscription it saw when the release was a mount cleanup.
+			*
+			* The stop is unconditional, where it once ran only for a mounted
+			* instance and `$terminate()` covered the rest. `$terminate()` is gone
+			* and `$unmount()` is the only teardown there is, so a manual
+			* subscription started outside a mount cycle would otherwise have
+			* nothing left to release it. `stop` is bound and idempotent, so an
+			* instance which never mounted pays nothing for the call — and it now
+			* releases on element removal too, which termination never did.
+			*/
+			$unmount() {
+				this.$services[hook].stop();
+				return super.$unmount();
+			}
+		};
+	}
+	return function mixin(first, second) {
+		if (typeof first === "function") return apply(first, second ?? {});
+		const options = first ?? {};
+		return (value) => apply(value, options);
+	};
+}
+//#endregion
+export { createServiceMixin };
+
+//# sourceMappingURL=mixin.js.map

package/dist/services/mixin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mixin.js","names":[],"sources":["../../src/services/mixin.ts"],"sourcesContent":["import type { Base, BaseConstructor, BaseProps } from '../Base.js';\nimport type { Service } from './service.js';\nimport { warn } from '../diagnostics.js';\nimport { toggle, type Toggle } from './toggle.js';\n\n/**\n * Options every service mixin accepts, on top of the ones its service takes.\n */\nexport interface ServiceMixinOptions<Target, Host = Base> {\n  /**\n   * What to observe, resolved per instance when the subscription starts.\n   * Defaults to the service's own target — the window, the viewport, the\n   * component's root element.\n   *\n   * The resolver is typed against the host **as declared**, which is `Base` in\n   * `withDrag(Base, …)`: a mixin is applied while the extends clause of its\n   * class is still being evaluated, so it cannot be typed against the class\n   * being defined. A component reaching past `Base` therefore names the shape\n   * it needs — and because that is an assertion rather than a check, a\n   * resolver which comes back with nothing is reported (`service.missing-target`)\n   * instead of being passed to the service, where a default parameter would\n   * quietly observe the wrong thing.\n   */\n  target?: (instance: Host) => Target;\n  /** Do not subscribe on mount. Control the subscription through `this.$services.<hook>`. */\n  manual?: boolean;\n  /** Request current props when the subscription starts. */\n  immediate?: boolean;\n}\n\n/**\n * The keys of {@link ServiceMixinOptions}. They describe the subscription, not\n * the observation, so they belong to the mixin and never to the service.\n */\nconst MIXIN_OPTIONS: readonly string[] = ['target', 'manual', 'immediate'];\n\n/**\n * Split the service half out of what the caller wrote.\n *\n * A service is identified by the options it is handed, so a lifecycle key\n * reaching `use()` mints a service of its own: `withDrag(Base, { manual: true })`\n * bound a second drag service on the element the plain `withDrag(Base)` already\n * owned — two pointer listener sets, two window listener sets and two\n * `touch-action` claims. `Options` no longer holds those keys either, so\n * forwarding the whole object is now the correct call rather than the mistake.\n *\n * A key holding `undefined` goes with them: naming an option without a value\n * is the same request as not naming it, and the service key already reads it\n * that way.\n */\nfunction serviceOptionsOf<Options extends object, Target>(\n  options: Options & ServiceMixinOptions<Target>,\n): Options {\n  const source = options as Record<string, unknown>;\n  const serviceOptions: Record<string, unknown> = {};\n  for (const key of Object.keys(source)) {\n    if (source[key] !== undefined && !MIXIN_OPTIONS.includes(key)) {\n      serviceOptions[key] = source[key];\n    }\n  }\n  return serviceOptions as Options;\n}\n\n/** Typed service controls keyed by hook name. Stacked mixins accumulate keys. */\nexport type ServiceHandles<Hook extends string> = {\n  readonly $services: { readonly [K in Hook]: Toggle };\n};\n\n/**\n * What a service declares to get a mixin.\n */\nexport interface ServiceMixinDefinition<Target, Options> {\n  /** Default method name, e.g. `scrolled`. */\n  hook: string;\n  /** Default target, e.g. the window for the scroll service. */\n  target: (instance: Base) => Target;\n  /**\n   * Whether a subscription asks for current props when the caller does not\n   * choose. Most hooks wait for the next update; sources whose hook is about\n   * current state can opt in while still honouring an explicit `false`.\n   */\n  defaultImmediate?: boolean;\n  /**\n   * Service the method subscribes to, given the service half of the options.\n   *\n   * `Options` is the service's own option type, without the mixin's `target`,\n   * `manual` and `immediate`: they are stripped before the call and absent\n   * from the type, so forwarding the whole object cannot put a lifecycle\n   * choice into the service identity.\n   *\n   * Both service parameters are `unknown` here because most mixins forward\n   * whatever the hook returns without looking at it — the frame service is the\n   * one that reads it.\n   */\n  use: (target: Target, options: Options) => Service<unknown, unknown>;\n  /**\n   * Adapt a hook result when the service itself does not own it. This keeps a\n   * service-specific write convention in its definition without copying the\n   * mixin lifecycle.\n   */\n  handleResult?: (instance: Base, result: unknown) => void;\n}\n\n/** A service mixin used directly or as a class decorator. */\nexport interface ServiceMixin<Instance, Target, Options extends object = object> {\n  <T extends BaseConstructor>(\n    BaseClass: T,\n    options?: Options & ServiceMixinOptions<Target, InstanceType<T>>,\n  ): MixedClass<T, Instance>;\n  (\n    options?: Options & ServiceMixinOptions<Target>,\n  ): <T extends BaseConstructor>(\n    value: T,\n    context: ClassDecoratorContext<T>,\n  ) => MixedClass<T, Instance>;\n}\n\n/** Mixed class statics and a generic constructor that preserves component props. */\nexport type MixedClass<T extends BaseConstructor, Instance> = Pick<T, keyof T> & {\n  new <P extends BaseProps = BaseProps>(el: HTMLElement): InstanceType<T> & Base<P> & Instance;\n};\n\n/**\n * Build a lifecycle-bound service mixin. Automatic subscriptions last for one mount cycle. Manual subscriptions also stop on unmount.\n * @link https://js-toolkit-v4.studiometa.dev/api/services/createServiceMixin.html\n */\nexport function createServiceMixin<Instance, Target, Options extends object = object>(\n  definition: ServiceMixinDefinition<Target, Options>,\n): ServiceMixin<Instance, Target, Options> {\n  type MixinOptions = Options & ServiceMixinOptions<Target>;\n\n  function apply(BaseClass: BaseConstructor, options: MixinOptions) {\n    const { hook } = definition;\n    // Only a caller's resolver can be wrong about its target: a service's own\n    // default is the contract, and `withRaf` legitimately resolves nothing.\n    const declared: ServiceMixinOptions<Target>['target'] = options.target;\n    const resolve = declared ?? definition.target;\n    const isManual = options.manual ?? false;\n    // One split per applied mixin: every instance asks for the same service.\n    const serviceOptions = serviceOptionsOf<Options, Target>(options);\n\n    return class extends BaseClass {\n      constructor(el: HTMLElement) {\n        super(el);\n        const host = this as unknown as {\n          $services?: Record<string, Toggle>;\n        };\n        // Share one handle object across stacked mixins.\n        const services = (host.$services ??= {});\n        // Set by `start()`, just below, before it ever calls `handle.start()`:\n        // the toggle's own callback trusts an already-validated target rather\n        // than resolving (and reporting) a second time.\n        let pendingTarget: Target;\n        const handle = toggle(() => {\n          const method = (this as unknown as Record<string, unknown>)[hook];\n          // Resolve the hook when subscribing because class fields initialize after `super()`.\n          if (typeof method !== 'function') {\n            return () => {};\n          }\n\n          return definition.use(pendingTarget, serviceOptions).subscribe(\n            (props) => {\n              const result = (method as (props: unknown) => unknown).call(this, props);\n              if (definition.handleResult) {\n                definition.handleResult(this, result);\n                return undefined;\n              }\n              return result;\n            },\n            { immediate: options.immediate ?? definition.defaultImmediate ?? false },\n          );\n        });\n\n        services[hook] = {\n          get isActive() {\n            return handle.isActive;\n          },\n          /**\n           * Validate before `toggle()` ever runs, so a rejected target leaves\n           * the handle exactly as inactive as one that was never started —\n           * `toggle()` has no channel for \"declined\", only for \"subscribed\" or\n           * \"not yet\", and a no-op cleanup would have been the first of those.\n           */\n          start: () => {\n            const observed: Target = resolve(this);\n            if (declared !== undefined && (observed === undefined || observed === null)) {\n              // The mixed class is built from a loose constructor type, so the\n              // instance reads as `any` in here.\n              const instance = this as unknown as Base;\n              warn(\n                'service.missing-target',\n                `\\`${hook}\\` resolved no target on \\`${instance.$config.name}\\`. A resolver names a shape rather than checking it, so a renamed ref or a missing element arrives here as nothing — and a service with a default target would observe the wrong thing instead.`,\n                { component: instance.$config.name, target: instance.$el },\n              );\n              return;\n            }\n            pendingTarget = observed;\n            handle.start();\n          },\n          stop: handle.stop,\n        };\n      }\n\n      /**\n       * Bind from `$mount()` rather than from `mounted()`.\n       *\n       * `mounted()` belongs to the component author. A mixin which occupied it\n       * needed every subclass to chain `super.mounted()`, and forgetting was\n       * total and silent: the subscription simply never happened, with no\n       * warning, no type error and no failing hook. `$mount()` is the\n       * framework's own method, so there is nothing left to chain.\n       *\n       * The subscription therefore starts once the whole `mounted()` has run,\n       * which is also when an `immediate` first delivery reaches a component\n       * that is fully set up. `$isMounted` is the guard, and it covers the\n       * case where there is nothing left to subscribe for: a hook, or a\n       * reversible strategy, which unmounted the instance mid-cycle.\n       *\n       * A hook which **threw** is deliberately not one of them. `#guard()`\n       * reports the failure and the cycle continues — the component stays\n       * mounted, its handlers stay bound and its option effects stay live — so\n       * withholding the subscription alone would make services the only\n       * subsystem treating a thrown `mounted()` as fatal.\n       */\n      $mount(): this {\n        super.$mount();\n        if (!isManual && this.$isMounted) {\n          (this as unknown as { $services: Record<string, Toggle> }).$services[hook].start();\n        }\n        return this;\n      }\n\n      /**\n       * Release before the cycle unwinds, so `unmounted()` sees the same\n       * stopped subscription it saw when the release was a mount cleanup.\n       *\n       * The stop is unconditional, where it once ran only for a mounted\n       * instance and `$terminate()` covered the rest. `$terminate()` is gone\n       * and `$unmount()` is the only teardown there is, so a manual\n       * subscription started outside a mount cycle would otherwise have\n       * nothing left to release it. `stop` is bound and idempotent, so an\n       * instance which never mounted pays nothing for the call — and it now\n       * releases on element removal too, which termination never did.\n       */\n      $unmount(): this {\n        (this as unknown as { $services: Record<string, Toggle> }).$services[hook].stop();\n        return super.$unmount();\n      }\n    };\n  }\n\n  return function mixin(first?: unknown, second?: unknown) {\n    // A class selects mixin form; other values select decorator options.\n    if (typeof first === 'function') {\n      return apply(first as BaseConstructor, (second ?? {}) as MixinOptions);\n    }\n    const options = (first ?? {}) as MixinOptions;\n    return (value: BaseConstructor) => apply(value, options);\n  } as unknown as ServiceMixin<Instance, Target, Options>;\n}\n"],"mappings":";;;;;;;AAkCA,MAAM,gBAAmC;CAAC;CAAU;CAAU;AAAW;;;;;;;;;;;;;;;AAgBzE,SAAS,iBACP,SACS;CACT,MAAM,SAAS;CACf,MAAM,iBAA0C,CAAC;CACjD,KAAK,MAAM,OAAO,OAAO,KAAK,MAAM,GAClC,IAAI,OAAO,SAAS,KAAA,KAAa,CAAC,cAAc,SAAS,GAAG,GAC1D,eAAe,OAAO,OAAO;CAGjC,OAAO;AACT;;;;;AAiEA,SAAgB,mBACd,YACyC;CAGzC,SAAS,MAAM,WAA4B,SAAuB;EAChE,MAAM,EAAE,SAAS;EAGjB,MAAM,WAAkD,QAAQ;EAChE,MAAM,UAAU,YAAY,WAAW;EACvC,MAAM,WAAW,QAAQ,UAAU;EAEnC,MAAM,iBAAiB,iBAAkC,OAAO;EAEhE,OAAO,cAAc,UAAU;GAC7B,YAAY,IAAiB;IAC3B,MAAM,EAAE;IACR,MAAM,OAAO;IAIb,MAAM,WAAY,KAAK,cAAc,CAAC;IAItC,IAAI;IACJ,MAAM,SAAS,aAAa;KAC1B,MAAM,SAAU,KAA4C;KAE5D,IAAI,OAAO,WAAW,YACpB,aAAa,CAAC;KAGhB,OAAO,WAAW,IAAI,eAAe,cAAc,CAAC,CAAC,WAClD,UAAU;MACT,MAAM,SAAU,OAAuC,KAAK,MAAM,KAAK;MACvE,IAAI,WAAW,cAAc;OAC3B,WAAW,aAAa,MAAM,MAAM;OACpC;MACF;MACA,OAAO;KACT,GACA,EAAE,WAAW,QAAQ,aAAa,WAAW,oBAAoB,MAAM,CACzE;IACF,CAAC;IAED,SAAS,QAAQ;KACf,IAAI,WAAW;MACb,OAAO,OAAO;KAChB;;;;;;;KAOA,aAAa;MACX,MAAM,WAAmB,QAAQ,IAAI;MACrC,IAAI,aAAa,KAAA,MAAc,aAAa,KAAA,KAAa,aAAa,OAAO;OAG3E,MAAM,WAAW;OACjB,KACE,0BACA,KAAK,KAAK,6BAA6B,SAAS,QAAQ,KAAK,mMAC7D;QAAE,WAAW,SAAS,QAAQ;QAAM,QAAQ,SAAS;OAAI,CAC3D;OACA;MACF;MACA,gBAAgB;MAChB,OAAO,MAAM;KACf;KACA,MAAM,OAAO;IACf;GACF;;;;;;;;;;;;;;;;;;;;;;GAuBA,SAAe;IACb,MAAM,OAAO;IACb,IAAI,CAAC,YAAY,KAAK,YACpB,KAA2D,UAAU,KAAK,CAAC,MAAM;IAEnF,OAAO;GACT;;;;;;;;;;;;;GAcA,WAAiB;IACf,KAA2D,UAAU,KAAK,CAAC,KAAK;IAChF,OAAO,MAAM,SAAS;GACxB;EACF;CACF;CAEA,OAAO,SAAS,MAAM,OAAiB,QAAkB;EAEvD,IAAI,OAAO,UAAU,YACnB,OAAO,MAAM,OAA2B,UAAU,CAAC,CAAkB;EAEvE,MAAM,UAAW,SAAS,CAAC;EAC3B,QAAQ,UAA2B,MAAM,OAAO,OAAO;CACzD;AACF"}

package/dist/services/mutation.d.ts

@@ -0,0 +1,41 @@
+import { Service } from "./service.js";
+import { ServiceHandles, ServiceMixin, ServiceMixinOptions } from "./mixin.js";
+//#region src/services/mutation.d.ts
+interface MutationProps {
+  /**
+   * The batch the observer just delivered, in observation order.
+   *
+   * It is valid for the duration of the call only: the service drops it
+   * afterwards, because a `childList` record holds the nodes it removed and
+   * retaining the last batch would keep a detached subtree alive for the life
+   * of the page. `[...records]` is how you keep one.
+   */
+  readonly records: readonly MutationRecord[];
+}
+/**
+ * Observe DOM mutations through one lazy service per target and observation.
+ *
+ * This is the general-purpose observer: any node, any `MutationObserverInit`,
+ * delivered on the platform's own timing. Two narrower tools come first.
+ * `watchAttributes(el, callback)` reports one coalesced change per attribute
+ * of one element, after component lifecycle has settled — reach for it
+ * whenever the question is "what did this attribute become". The registry's
+ * internal observer handles component discovery and declared options; nothing
+ * here replaces it, and a subscriber that needs the framework's own ordering
+ * awaits `whenDOMSettled()` from its callback.
+ * @link https://js-toolkit-v4.studiometa.dev/api/services/useMutation.html
+ */
+declare function useMutation(target: Node, init?: MutationObserverInit): Service<MutationProps>;
+/** The method `withMutation()` subscribes for the component. */
+interface MutationHook {
+  mutated?(props: MutationProps): void;
+}
+type MutationMixinOptions = MutationObserverInit & ServiceMixinOptions<Node>;
+/**
+ * Subscribe `mutated()` for each mount cycle, watching the root element's
+ * subtree unless the options name another observation.
+ * @link https://js-toolkit-v4.studiometa.dev/api/services/mixins.html
+ */
+declare const withMutation: ServiceMixin<MutationHook & ServiceHandles<"mutated">, Node, MutationObserverInit>;
+//#endregion
+export { MutationHook, MutationMixinOptions, MutationProps, useMutation, withMutation };

package/dist/services/mutation.js

@@ -0,0 +1,95 @@
+import { getSharedRuntimeSlot } from "../shared-runtime.js";
+import { createService, perTarget } from "./service.js";
+import { createServiceMixin } from "./mixin.js";
+//#region src/services/mutation.ts
+/** The resting value: a batch is an event, so there is none between deliveries. */
+const NO_RECORDS = /* @__PURE__ */ Object.freeze([]);
+/**
+* Watch the target's subtree structure when the caller names no observation.
+* Attributes of one element are `watchAttributes()`'s job, so the default is
+* the case only this service covers.
+*/
+const DEFAULT_INIT = /* @__PURE__ */ Object.freeze({
+	childList: true,
+	subtree: true
+});
+/**
+* Give observationally identical options one canonical form, so they resolve
+* to one observer whatever order or shorthand the caller wrote them in.
+*
+* The two inferences are the platform's own: `attributeOldValue` and
+* `attributeFilter` imply `attributes`, and `characterDataOldValue` implies
+* `characterData`. Contradictory options — a filter with `attributes: false` —
+* are forwarded untouched so `observe()` still rejects them.
+*
+* Property order is not this function's business: `perTarget()` sorts keys
+* before it keys anything. What is left here is the DOM contract — an omitted
+* option is `false`, a filter is a set, and the platform infers two flags.
+*/
+function resolveInit(init) {
+	const attributeFilter = init.attributeFilter && [...new Set(init.attributeFilter)].sort();
+	return {
+		childList: init.childList ?? false,
+		subtree: init.subtree ?? false,
+		attributes: init.attributes ?? (init.attributeOldValue !== void 0 || attributeFilter !== void 0),
+		attributeOldValue: init.attributeOldValue ?? false,
+		characterData: init.characterData ?? init.characterDataOldValue !== void 0,
+		characterDataOldValue: init.characterDataOldValue ?? false,
+		...attributeFilter !== void 0 && { attributeFilter }
+	};
+}
+function createMutationService(target, init) {
+	const props = { records: NO_RECORDS };
+	let isDelivering = false;
+	return createService({
+		props: () => props,
+		hasProps: () => isDelivering,
+		start(emit) {
+			let isActive = true;
+			const observer = new MutationObserver((records) => {
+				if (!isActive) return;
+				props.records = records;
+				isDelivering = true;
+				emit(props);
+				isDelivering = false;
+				props.records = NO_RECORDS;
+			});
+			observer.observe(target, init);
+			return () => {
+				isActive = false;
+				observer.disconnect();
+			};
+		}
+	});
+}
+const mutationServices = /* @__PURE__ */ getSharedRuntimeSlot("service:mutation", 1, () => perTarget(createMutationService));
+/**
+* Observe DOM mutations through one lazy service per target and observation.
+*
+* This is the general-purpose observer: any node, any `MutationObserverInit`,
+* delivered on the platform's own timing. Two narrower tools come first.
+* `watchAttributes(el, callback)` reports one coalesced change per attribute
+* of one element, after component lifecycle has settled — reach for it
+* whenever the question is "what did this attribute become". The registry's
+* internal observer handles component discovery and declared options; nothing
+* here replaces it, and a subscriber that needs the framework's own ordering
+* awaits `whenDOMSettled()` from its callback.
+* @link https://js-toolkit-v4.studiometa.dev/api/services/useMutation.html
+*/
+function useMutation(target, init = DEFAULT_INIT) {
+	return mutationServices(target, resolveInit(init));
+}
+/**
+* Subscribe `mutated()` for each mount cycle, watching the root element's
+* subtree unless the options name another observation.
+* @link https://js-toolkit-v4.studiometa.dev/api/services/mixins.html
+*/
+const withMutation = /* @__PURE__ */ createServiceMixin({
+	hook: "mutated",
+	target: (instance) => instance.$el,
+	use: (target, options) => useMutation(target, Object.keys(options).length > 0 ? options : DEFAULT_INIT)
+});
+//#endregion
+export { useMutation, withMutation };
+
+//# sourceMappingURL=mutation.js.map

package/dist/services/mutation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mutation.js","names":[],"sources":["../../src/services/mutation.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 interface MutationProps {\n  /**\n   * The batch the observer just delivered, in observation order.\n   *\n   * It is valid for the duration of the call only: the service drops it\n   * afterwards, because a `childList` record holds the nodes it removed and\n   * retaining the last batch would keep a detached subtree alive for the life\n   * of the page. `[...records]` is how you keep one.\n   */\n  readonly records: readonly MutationRecord[];\n}\n\n/** The resting value: a batch is an event, so there is none between deliveries. */\nconst NO_RECORDS: readonly MutationRecord[] = /* @__PURE__ */ Object.freeze([]);\n\n/**\n * Watch the target's subtree structure when the caller names no observation.\n * Attributes of one element are `watchAttributes()`'s job, so the default is\n * the case only this service covers.\n */\nconst DEFAULT_INIT: MutationObserverInit = /* @__PURE__ */ Object.freeze({\n  childList: true,\n  subtree: true,\n});\n\n/**\n * Give observationally identical options one canonical form, so they resolve\n * to one observer whatever order or shorthand the caller wrote them in.\n *\n * The two inferences are the platform's own: `attributeOldValue` and\n * `attributeFilter` imply `attributes`, and `characterDataOldValue` implies\n * `characterData`. Contradictory options — a filter with `attributes: false` —\n * are forwarded untouched so `observe()` still rejects them.\n *\n * Property order is not this function's business: `perTarget()` sorts keys\n * before it keys anything. What is left here is the DOM contract — an omitted\n * option is `false`, a filter is a set, and the platform infers two flags.\n */\nfunction resolveInit(init: MutationObserverInit): MutationObserverInit {\n  const attributeFilter = init.attributeFilter && [...new Set(init.attributeFilter)].sort();\n  return {\n    childList: init.childList ?? false,\n    subtree: init.subtree ?? false,\n    attributes:\n      init.attributes ?? (init.attributeOldValue !== undefined || attributeFilter !== undefined),\n    attributeOldValue: init.attributeOldValue ?? false,\n    characterData: init.characterData ?? init.characterDataOldValue !== undefined,\n    characterDataOldValue: init.characterDataOldValue ?? false,\n    ...(attributeFilter !== undefined && { attributeFilter }),\n  };\n}\n\nfunction createMutationService(target: Node, init: MutationObserverInit): Service<MutationProps> {\n  const props: MutableProps<MutationProps> = { records: NO_RECORDS };\n  let isDelivering = false;\n\n  return createService<MutationProps>({\n    props: () => props,\n    // Between two batches there is nothing current to hand over, so\n    // `{ immediate: true }` waits for a real mutation.\n    hasProps: () => isDelivering,\n    start(emit) {\n      let isActive = true;\n      const observer = new MutationObserver((records) => {\n        // A callback queued before the last subscriber left must not publish\n        // into the run that replaced it.\n        if (!isActive) {\n          return;\n        }\n        props.records = records;\n        isDelivering = true;\n        emit(props);\n        isDelivering = false;\n        props.records = NO_RECORDS;\n      });\n      observer.observe(target, init);\n\n      return () => {\n        isActive = false;\n        observer.disconnect();\n      };\n    },\n  });\n}\n\nconst mutationServices = /* @__PURE__ */ getSharedRuntimeSlot('service:mutation', 1, () =>\n  perTarget(createMutationService),\n);\n\n/**\n * Observe DOM mutations through one lazy service per target and observation.\n *\n * This is the general-purpose observer: any node, any `MutationObserverInit`,\n * delivered on the platform's own timing. Two narrower tools come first.\n * `watchAttributes(el, callback)` reports one coalesced change per attribute\n * of one element, after component lifecycle has settled — reach for it\n * whenever the question is \"what did this attribute become\". The registry's\n * internal observer handles component discovery and declared options; nothing\n * here replaces it, and a subscriber that needs the framework's own ordering\n * awaits `whenDOMSettled()` from its callback.\n * @link https://js-toolkit-v4.studiometa.dev/api/services/useMutation.html\n */\nexport function useMutation(\n  target: Node,\n  init: MutationObserverInit = DEFAULT_INIT,\n): Service<MutationProps> {\n  return mutationServices(target, resolveInit(init));\n}\n\n/** The method `withMutation()` subscribes for the component. */\nexport interface MutationHook {\n  mutated?(props: MutationProps): void;\n}\n\nexport type MutationMixinOptions = MutationObserverInit & ServiceMixinOptions<Node>;\n\n/**\n * Subscribe `mutated()` for each mount cycle, watching the root element's\n * subtree unless the options name another observation.\n * @link https://js-toolkit-v4.studiometa.dev/api/services/mixins.html\n */\nexport const withMutation = /* @__PURE__ */ createServiceMixin<\n  MutationHook & ServiceHandles<'mutated'>,\n  Node,\n  MutationObserverInit\n>({\n  hook: 'mutated',\n  target: (instance) => instance.$el,\n  // Options naming no observation — `{ manual: true }`, or nothing at all —\n  // ask for the documented default rather than for `observe(target, {})`,\n  // which the platform rejects.\n  use: (target, options) =>\n    useMutation(target, Object.keys(options).length > 0 ? options : DEFAULT_INIT),\n});\n"],"mappings":";;;;;AAiBA,MAAM,aAAwD,uBAAO,OAAO,CAAC,CAAC;;;;;;AAO9E,MAAM,eAAqD,uBAAO,OAAO;CACvE,WAAW;CACX,SAAS;AACX,CAAC;;;;;;;;;;;;;;AAeD,SAAS,YAAY,MAAkD;CACrE,MAAM,kBAAkB,KAAK,mBAAmB,CAAC,GAAG,IAAI,IAAI,KAAK,eAAe,CAAC,CAAC,CAAC,KAAK;CACxF,OAAO;EACL,WAAW,KAAK,aAAa;EAC7B,SAAS,KAAK,WAAW;EACzB,YACE,KAAK,eAAe,KAAK,sBAAsB,KAAA,KAAa,oBAAoB,KAAA;EAClF,mBAAmB,KAAK,qBAAqB;EAC7C,eAAe,KAAK,iBAAiB,KAAK,0BAA0B,KAAA;EACpE,uBAAuB,KAAK,yBAAyB;EACrD,GAAI,oBAAoB,KAAA,KAAa,EAAE,gBAAgB;CACzD;AACF;AAEA,SAAS,sBAAsB,QAAc,MAAoD;CAC/F,MAAM,QAAqC,EAAE,SAAS,WAAW;CACjE,IAAI,eAAe;CAEnB,OAAO,cAA6B;EAClC,aAAa;EAGb,gBAAgB;EAChB,MAAM,MAAM;GACV,IAAI,WAAW;GACf,MAAM,WAAW,IAAI,kBAAkB,YAAY;IAGjD,IAAI,CAAC,UACH;IAEF,MAAM,UAAU;IAChB,eAAe;IACf,KAAK,KAAK;IACV,eAAe;IACf,MAAM,UAAU;GAClB,CAAC;GACD,SAAS,QAAQ,QAAQ,IAAI;GAE7B,aAAa;IACX,WAAW;IACX,SAAS,WAAW;GACtB;EACF;CACF,CAAC;AACH;AAEA,MAAM,mBAAmC,qCAAqB,oBAAoB,SAChF,UAAU,qBAAqB,CACjC;;;;;;;;;;;;;;AAeA,SAAgB,YACd,QACA,OAA6B,cACL;CACxB,OAAO,iBAAiB,QAAQ,YAAY,IAAI,CAAC;AACnD;;;;;;AAcA,MAAa,eAA+B,mCAI1C;CACA,MAAM;CACN,SAAS,aAAa,SAAS;CAI/B,MAAM,QAAQ,YACZ,YAAY,QAAQ,OAAO,KAAK,OAAO,CAAC,CAAC,SAAS,IAAI,UAAU,YAAY;AAChF,CAAC"}

package/dist/services/pointer.d.ts

@@ -0,0 +1,49 @@
+import { Service } from "./service.js";
+import { ServiceHandles, ServiceMixin, ServiceMixinOptions } from "./mixin.js";
+//#region src/services/pointer.d.ts
+/** Pointer state for both viewport axes. */
+interface PointerProps {
+  /** The source event, or `null` before observation and after release. */
+  readonly event: PointerEvent | null;
+  readonly isDown: boolean;
+  /** Position in the viewport. */
+  readonly x: number;
+  readonly y: number;
+  /** Movement since the previous update. */
+  readonly deltaX: number;
+  readonly deltaY: number;
+  /** Viewport size. */
+  readonly maxX: number;
+  readonly maxY: number;
+  /** Position over the viewport, from `0` to `1`. */
+  readonly progressX: number;
+  readonly progressY: number;
+}
+/** Pointer state placed in a target element's box, beside the viewport one. */
+interface ElementPointerProps extends PointerProps {
+  /** Position inside the target's box, from its top-left corner. */
+  readonly relativeX: number;
+  readonly relativeY: number;
+  /** Position over the target's box, from `0` to `1` inside it and past that range outside. */
+  readonly relativeProgressX: number;
+  readonly relativeProgressY: number;
+}
+/**
+ * Use the viewport-relative pointer service.
+ * @link https://js-toolkit-v4.studiometa.dev/api/services/usePointer.html
+ */
+declare function usePointer(): Service<PointerProps>;
+/** Use one lazy service per target, adding the pointer's position inside its box. */
+declare function usePointer(target: Element): Service<ElementPointerProps>;
+/** The method `withPointer()` subscribes for the component. */
+interface PointerHook {
+  moved?(props: ElementPointerProps): void;
+}
+type PointerMixinOptions = ServiceMixinOptions<Element>;
+/**
+ * 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
+ */
+declare const withPointer: ServiceMixin<PointerHook & ServiceHandles<"moved">, Element, object>;
+//#endregion
+export { ElementPointerProps, PointerHook, PointerMixinOptions, PointerProps, usePointer, withPointer };