@solid-primitives/sensors 1.0.0-next.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2021 Solid Core Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,354 @@
+<p>
+  <img width="100%" src="https://assets.solidjs.com/banner?type=Primitives&background=tiles&project=Sensors" alt="Solid Primitives Sensors">
+</p>
+
+# @solid-primitives/sensors
+
+[![size](https://img.shields.io/badge/size-1.2_kB-blue?style=for-the-badge)](https://bundlephobia.com/package/@solid-primitives/sensors)
+[![size](https://img.shields.io/npm/v/@solid-primitives/sensors?style=for-the-badge)](https://www.npmjs.com/package/@solid-primitives/sensors)
+[![stage](https://img.shields.io/endpoint?style=for-the-badge&url=https%3A%2F%2Fraw.githubusercontent.com%2Fsolidjs-community%2Fsolid-primitives%2Fmain%2Fassets%2Fbadges%2Fstage-0.json)](https://github.com/solidjs-community/solid-primitives#contribution-process)
+[![tested with vitest](https://img.shields.io/badge/tested_with-vitest-6E9F18?style=for-the-badge&logo=vitest)](https://vitest.dev)
+
+Reactive primitives for device motion, orientation, and hardware sensors using standard browser APIs.
+
+## Installation
+
+```bash
+npm install @solid-primitives/sensors
+# or
+yarn add @solid-primitives/sensors
+# or
+pnpm add @solid-primitives/sensors
+```
+
+## Accelerometer
+
+Uses the [`DeviceMotionEvent`](https://developer.mozilla.org/en-US/docs/Web/API/DeviceMotionEvent) API.
+
+### `makeAccelerometer`
+
+Attaches a `devicemotion` event listener and calls `onChange` with the latest acceleration reading, throttled to at most once per `interval` milliseconds.
+
+```ts
+import { makeAccelerometer } from "@solid-primitives/sensors";
+
+const cleanup = makeAccelerometer(
+  acceleration => {
+    console.log(acceleration?.x, acceleration?.y, acceleration?.z);
+  },
+  { includeGravity: false, interval: 100 },
+);
+
+// Later, stop listening:
+cleanup();
+```
+
+**Options:**
+
+| Option           | Type      | Default | Description                                                                |
+| ---------------- | --------- | ------- | -------------------------------------------------------------------------- |
+| `includeGravity` | `boolean` | `false` | When `true`, uses `accelerationIncludingGravity` instead of `acceleration` |
+| `interval`       | `number`  | `100`   | Minimum milliseconds between `onChange` calls                              |
+
+**Returns:** `VoidFunction` — call to remove the event listener.
+
+### `createAccelerometer`
+
+Reactive wrapper around `makeAccelerometer`. Returns a signal accessor that starts as `undefined` and updates to the latest `DeviceMotionEventAcceleration` reading on each throttled event.
+
+```ts
+import { createAccelerometer } from "@solid-primitives/sensors";
+
+function MyComponent() {
+  const acceleration = createAccelerometer();
+  // acceleration() is AccelerometerReading | undefined
+
+  return (
+    <div>
+      X: {acceleration()?.x ?? 0}, Y: {acceleration()?.y ?? 0}, Z: {acceleration()?.z ?? 0}
+    </div>
+  );
+}
+```
+
+**Signature:**
+
+```ts
+function createAccelerometer(
+  includeGravity?: boolean, // default: false
+  interval?: number, // default: 100ms
+): Accessor<AccelerometerReading | undefined>;
+
+type AccelerometerReading = DeviceMotionEventAcceleration | null;
+```
+
+**SSR:** Returns `() => ({ x: 0, y: 0, z: 0 })` on the server — no event listeners are attached.
+
+## Gyroscope
+
+Uses the [`DeviceOrientationEvent`](https://developer.mozilla.org/en-US/docs/Web/API/DeviceOrientationEvent) API.
+
+### `makeGyroscope`
+
+Attaches a `deviceorientation` event listener and calls `onChange` with the latest orientation reading, throttled to at most once per `interval` milliseconds. `null` orientation values (common on some platforms) are coerced to `0`.
+
+```ts
+import { makeGyroscope } from "@solid-primitives/sensors";
+
+const cleanup = makeGyroscope(
+  orientation => {
+    console.log(orientation.alpha, orientation.beta, orientation.gamma);
+  },
+  { interval: 100 },
+);
+
+// Later, stop listening:
+cleanup();
+```
+
+**Options:**
+
+| Option     | Type     | Default | Description                                   |
+| ---------- | -------- | ------- | --------------------------------------------- |
+| `interval` | `number` | `100`   | Minimum milliseconds between `onChange` calls |
+
+**Returns:** `VoidFunction` — call to remove the event listener.
+
+### `createGyroscope`
+
+Reactive wrapper around `makeGyroscope`. Returns an object with reactive `alpha`, `beta`, and `gamma` getters that start at `0` and update on each throttled orientation event.
+
+```ts
+import { createGyroscope } from "@solid-primitives/sensors";
+
+function MyComponent() {
+  const orientation = createGyroscope();
+
+  return (
+    <div>
+      α: {orientation.alpha}°, β: {orientation.beta}°, γ: {orientation.gamma}°
+    </div>
+  );
+}
+```
+
+**Signature:**
+
+```ts
+function createGyroscope(
+  interval?: number, // default: 100ms
+): GyroscopeReading;
+
+type GyroscopeReading = { alpha: number; beta: number; gamma: number };
+```
+
+**SSR:** Returns `{ alpha: 0, beta: 0, gamma: 0 }` — a plain non-reactive object.
+
+## Generic Sensor API
+
+A factory pair for any [Generic Sensor API](https://developer.mozilla.org/en-US/docs/Web/API/Sensor_APIs) sensor (Chromium-based browsers). Covers `LinearAccelerationSensor`, `GravitySensor`, `AbsoluteOrientationSensor`, `RelativeOrientationSensor`, and others.
+
+### `makeSensor`
+
+Sets up any Generic Sensor API sensor and calls `onChange` with the live sensor object on each reading. Returns `null` if the sensor constructor throws (API unsupported or permission denied).
+
+```ts
+import { makeSensor } from "@solid-primitives/sensors";
+
+const cleanup = makeSensor(
+  LinearAccelerationSensor,
+  sensor => console.log(sensor.x, sensor.y, sensor.z),
+  { frequency: 60 },
+);
+
+if (cleanup) {
+  // Later, stop:
+  cleanup();
+}
+```
+
+**Signature:**
+
+```ts
+function makeSensor<T extends GenericSensor>(
+  SensorClass: { new (options?: any): T },
+  onChange: (sensor: T) => void,
+  options?: SensorOptions,
+): VoidFunction | null;
+
+type SensorOptions = { frequency?: number };
+```
+
+**Returns:** `VoidFunction` (cleanup) or `null` if unsupported.
+
+### `createSensor`
+
+Reactive wrapper around `makeSensor`. Returns an accessor that updates on **every reading event** — even if the sensor object reference is the same — because the underlying signal uses `equals: false`. Returns `undefined` until the first reading or if the sensor is unavailable.
+
+```ts
+import { createSensor } from "@solid-primitives/sensors";
+
+function MyComponent() {
+  const sensor = createSensor(LinearAccelerationSensor, { frequency: 60 });
+
+  return (
+    <Show when={sensor()}>
+      {s => <div>X: {s().x ?? 0}</div>}
+    </Show>
+  );
+}
+```
+
+**Signature:**
+
+```ts
+function createSensor<T extends GenericSensor>(
+  SensorClass: { new (options?: any): T },
+  options?: SensorOptions,
+): Accessor<T | undefined>;
+```
+
+**SSR:** Returns `() => undefined`.
+
+## Compass
+
+Uses `window.Magnetometer` from the [Generic Sensor API](https://developer.mozilla.org/en-US/docs/Web/API/Magnetometer). Chromium-based browsers only. Reports raw magnetic field strength in microteslas (µT) as `{ x, y, z }` components.
+
+### `makeCompass`
+
+```ts
+import { makeCompass } from "@solid-primitives/sensors";
+
+const cleanup = makeCompass(({ x, y, z }) => console.log(`Field: ${x}µT, ${y}µT, ${z}µT`), {
+  frequency: 10,
+  referenceFrame: "device",
+});
+
+if (cleanup) cleanup();
+```
+
+**Options:**
+
+| Option           | Type                   | Default    | Description                |
+| ---------------- | ---------------------- | ---------- | -------------------------- |
+| `frequency`      | `number`               | —          | Readings per second        |
+| `referenceFrame` | `"device" \| "screen"` | `"device"` | Coordinate reference frame |
+
+**Returns:** `VoidFunction` or `null` if `window.Magnetometer` is unavailable.
+
+### `createCompass`
+
+Returns an object with reactive `x`, `y`, `z` getters (in µT), all starting at `0`.
+
+```ts
+import { createCompass } from "@solid-primitives/sensors";
+
+function Compass() {
+  const mag = createCompass({ frequency: 10 });
+  const heading = () => Math.atan2(mag.y, mag.x) * (180 / Math.PI);
+  return <div>Heading: {heading()}°</div>;
+}
+```
+
+**Signature:**
+
+```ts
+function createCompass(options?: CompassOptions): CompassReading;
+
+type CompassOptions = { frequency?: number; referenceFrame?: "device" | "screen" };
+type CompassReading = { x: number; y: number; z: number };
+```
+
+**SSR:** Returns `{ x: 0, y: 0, z: 0 }` — a plain non-reactive object.
+
+## Battery
+
+Uses the [Battery Status API](https://developer.mozilla.org/en-US/docs/Web/API/Battery_Status_API) (`navigator.getBattery()`). Supported in Chrome/Edge; not available in Firefox or Safari.
+
+### `makeBattery`
+
+Subscribes to the Battery API and calls `onChange` immediately with the current reading, then again on every battery change event. Returns a synchronous cleanup function — safe to use with `onCleanup` even though the API initializes asynchronously.
+
+```ts
+import { makeBattery } from "@solid-primitives/sensors";
+
+const cleanup = makeBattery(({ level, charging }) => {
+  console.log(`${Math.round(level * 100)}% ${charging ? "charging" : "discharging"}`);
+});
+
+// Later:
+cleanup();
+```
+
+**Signature:**
+
+```ts
+function makeBattery(onChange: (reading: BatteryReading) => void): VoidFunction;
+
+type BatteryReading = {
+  charging: boolean;
+  chargingTime: number; // seconds until full; Infinity if not charging
+  dischargingTime: number; // seconds until empty; Infinity if charging
+  level: number; // 0.0–1.0
+};
+```
+
+**Returns:** `VoidFunction` — always (no-ops if the API is unavailable).
+
+### `createBattery`
+
+Returns a reactive accessor for battery status. Starts as `undefined` until the Battery API resolves. Subscribe to any of the four properties to track specific changes.
+
+```ts
+import { createBattery } from "@solid-primitives/sensors";
+
+function BatteryIndicator() {
+  const battery = createBattery();
+
+  return (
+    <Show when={battery()} fallback={<span>Loading battery…</span>}>
+      {b => (
+        <span>
+          {Math.round(b().level * 100)}%{b().charging ? " ⚡" : ""}
+        </span>
+      )}
+    </Show>
+  );
+}
+```
+
+**Signature:**
+
+```ts
+function createBattery(): Accessor<BatteryReading | undefined>;
+```
+
+**SSR:** Returns `() => ({ charging: false, chargingTime: 0, dischargingTime: 0, level: 1 })`.
+
+## Throttling
+
+Both `makeAccelerometer` and `makeGyroscope` throttle events using a **leading-edge** strategy: the first event in a burst fires `onChange` immediately; subsequent events within `interval` ms are dropped. The next event after the interval elapses fires again.
+
+Set `interval: 0` to disable throttling (useful in tests).
+
+Generic Sensor API primitives (`makeSensor`, `makeCompass`) use the sensor's built-in `frequency` option for rate control — no additional throttling is applied.
+
+## Types
+
+```ts
+type AccelerometerReading = DeviceMotionEventAcceleration | null;
+type GyroscopeReading = { alpha: number; beta: number; gamma: number };
+type SensorOptions = { frequency?: number };
+type CompassOptions = { frequency?: number; referenceFrame?: "device" | "screen" };
+type CompassReading = { x: number; y: number; z: number };
+type BatteryReading = {
+  charging: boolean;
+  chargingTime: number;
+  dischargingTime: number;
+  level: number;
+};
+```
+
+## Changelog
+
+See [CHANGELOG.md](./CHANGELOG.md)

package/dist/accelerometer.d.ts

@@ -0,0 +1,25 @@
+import type { Accessor } from "solid-js";
+export type AccelerometerReading = DeviceMotionEventAcceleration | null;
+/**
+ * Sets up a raw `devicemotion` event listener and returns a cleanup function.
+ * No Solid lifecycle — suitable for use outside a reactive owner.
+ *
+ * @param onChange Called on each (throttled) motion event with the acceleration reading
+ * @param options.includeGravity Use `accelerationIncludingGravity` instead of `acceleration`
+ * @param options.interval Minimum milliseconds between onChange calls (default 100)
+ * @returns Cleanup function that removes the event listener
+ */
+export declare const makeAccelerometer: (onChange: (acceleration: AccelerometerReading) => void, options?: {
+    includeGravity?: boolean;
+    interval?: number;
+}) => VoidFunction;
+/**
+ * Creates a reactive accessor for device acceleration data.
+ * Starts as `undefined` until the first motion event arrives.
+ * Registers cleanup with `onCleanup` when inside a reactive owner.
+ *
+ * @param includeGravity Use `accelerationIncludingGravity` instead of `acceleration` (default false)
+ * @param interval Minimum milliseconds between updates (default 100)
+ * @returns Accessor yielding the latest AccelerometerReading, or `undefined` before the first event
+ */
+export declare const createAccelerometer: (includeGravity?: boolean, interval?: number) => Accessor<AccelerometerReading | undefined>;

package/dist/accelerometer.js

@@ -0,0 +1,44 @@
+import { createSignal, onCleanup } from "solid-js";
+import { isServer } from "@solidjs/web";
+const OWNED_WRITE = { ownedWrite: true };
+/**
+ * Sets up a raw `devicemotion` event listener and returns a cleanup function.
+ * No Solid lifecycle — suitable for use outside a reactive owner.
+ *
+ * @param onChange Called on each (throttled) motion event with the acceleration reading
+ * @param options.includeGravity Use `accelerationIncludingGravity` instead of `acceleration`
+ * @param options.interval Minimum milliseconds between onChange calls (default 100)
+ * @returns Cleanup function that removes the event listener
+ */
+export const makeAccelerometer = (onChange, options = {}) => {
+    const { includeGravity = false, interval = 100 } = options;
+    let throttled = false;
+    const handler = (e) => {
+        if (throttled)
+            return;
+        throttled = true;
+        setTimeout(() => {
+            throttled = false;
+        }, interval);
+        onChange(includeGravity ? e.accelerationIncludingGravity : e.acceleration);
+    };
+    addEventListener("devicemotion", handler);
+    return () => removeEventListener("devicemotion", handler);
+};
+/**
+ * Creates a reactive accessor for device acceleration data.
+ * Starts as `undefined` until the first motion event arrives.
+ * Registers cleanup with `onCleanup` when inside a reactive owner.
+ *
+ * @param includeGravity Use `accelerationIncludingGravity` instead of `acceleration` (default false)
+ * @param interval Minimum milliseconds between updates (default 100)
+ * @returns Accessor yielding the latest AccelerometerReading, or `undefined` before the first event
+ */
+export const createAccelerometer = (includeGravity = false, interval = 100) => {
+    if (isServer)
+        return () => ({ x: 0, y: 0, z: 0 });
+    const [acceleration, setAcceleration] = createSignal(undefined, OWNED_WRITE);
+    const cleanup = makeAccelerometer(acc => setAcceleration(acc), { includeGravity, interval });
+    onCleanup(cleanup);
+    return acceleration;
+};

package/dist/battery.d.ts

@@ -0,0 +1,27 @@
+import type { Accessor } from "solid-js";
+export type BatteryReading = {
+    charging: boolean;
+    chargingTime: number;
+    dischargingTime: number;
+    level: number;
+};
+/**
+ * Subscribes to the Battery Status API and calls `onChange` with the current reading
+ * immediately after the API resolves, then again on every battery change event.
+ * Returns a synchronous cleanup function safe to pass to `onCleanup`.
+ * Silently no-ops if `navigator.getBattery` is unavailable.
+ *
+ * @param onChange Called with the current BatteryReading on subscribe and on each change
+ * @returns Synchronous cleanup function that removes all battery event listeners
+ */
+export declare const makeBattery: (onChange: (reading: BatteryReading) => void) => VoidFunction;
+/**
+ * Creates a reactive accessor for battery status.
+ * Starts as `undefined` until the Battery Status API resolves (async).
+ * Returns a static `() => ({ charging: false, chargingTime: 0, dischargingTime: 0, level: 1 })`
+ * on the server.
+ * Registers cleanup with `onCleanup` when inside a reactive owner.
+ *
+ * @returns Accessor yielding the current BatteryReading, or `undefined` before the API resolves
+ */
+export declare const createBattery: () => Accessor<BatteryReading | undefined>;

package/dist/battery.js

@@ -0,0 +1,58 @@
+import { createSignal, onCleanup } from "solid-js";
+import { isServer } from "@solidjs/web";
+const OWNED_WRITE = { ownedWrite: true };
+/**
+ * Subscribes to the Battery Status API and calls `onChange` with the current reading
+ * immediately after the API resolves, then again on every battery change event.
+ * Returns a synchronous cleanup function safe to pass to `onCleanup`.
+ * Silently no-ops if `navigator.getBattery` is unavailable.
+ *
+ * @param onChange Called with the current BatteryReading on subscribe and on each change
+ * @returns Synchronous cleanup function that removes all battery event listeners
+ */
+export const makeBattery = (onChange) => {
+    let disposed = false;
+    let removeFn;
+    if (typeof navigator !== "undefined" && "getBattery" in navigator) {
+        navigator.getBattery().then((battery) => {
+            if (disposed)
+                return;
+            const update = () => onChange({
+                charging: battery.charging,
+                chargingTime: battery.chargingTime,
+                dischargingTime: battery.dischargingTime,
+                level: battery.level,
+            });
+            update();
+            const events = [
+                "chargingchange",
+                "chargingtimechange",
+                "dischargingtimechange",
+                "levelchange",
+            ];
+            events.forEach(e => battery.addEventListener(e, update));
+            removeFn = () => events.forEach(e => battery.removeEventListener(e, update));
+        });
+    }
+    return () => {
+        disposed = true;
+        removeFn?.();
+    };
+};
+/**
+ * Creates a reactive accessor for battery status.
+ * Starts as `undefined` until the Battery Status API resolves (async).
+ * Returns a static `() => ({ charging: false, chargingTime: 0, dischargingTime: 0, level: 1 })`
+ * on the server.
+ * Registers cleanup with `onCleanup` when inside a reactive owner.
+ *
+ * @returns Accessor yielding the current BatteryReading, or `undefined` before the API resolves
+ */
+export const createBattery = () => {
+    if (isServer)
+        return () => ({ charging: false, chargingTime: 0, dischargingTime: 0, level: 1 });
+    const [reading, setReading] = createSignal(undefined, OWNED_WRITE);
+    const cleanup = makeBattery(r => setReading(r));
+    onCleanup(cleanup);
+    return reading;
+};

package/dist/compass.d.ts

@@ -0,0 +1,31 @@
+/** Options for `makeCompass` / `createCompass`. */
+export type CompassOptions = {
+    frequency?: number;
+    referenceFrame?: "device" | "screen";
+};
+/** Raw magnetometer reading in microteslas (µT), as returned by `makeCompass` / `createCompass`. */
+export type CompassReading = {
+    x: number;
+    y: number;
+    z: number;
+};
+/**
+ * Sets up a `Magnetometer` sensor and calls `onChange` with x/y/z readings in microteslas.
+ * Uses the Generic Sensor API (`window.Magnetometer`).
+ * Returns `null` if the Magnetometer API is unavailable or throws on construction.
+ *
+ * @param onChange Called on each reading with `{ x, y, z }` in microteslas (null coerced to 0)
+ * @param options Optional `{ frequency, referenceFrame }` passed to the Magnetometer constructor
+ * @returns Cleanup function that stops the sensor, or `null` if unsupported
+ */
+export declare const makeCompass: (onChange: (reading: CompassReading) => void, options?: CompassOptions) => VoidFunction | null;
+/**
+ * Creates a reactive object with `x`, `y`, `z` magnetometer readings in microteslas.
+ * All properties start at `0` and update on each sensor reading.
+ * Returns a non-reactive `{ x: 0, y: 0, z: 0 }` on the server.
+ * Registers cleanup with `onCleanup` when inside a reactive owner.
+ *
+ * @param options Optional `{ frequency, referenceFrame }` passed to the Magnetometer constructor
+ * @returns Reactive CompassReading object `{ x, y, z }`
+ */
+export declare const createCompass: (options?: CompassOptions) => CompassReading;

package/dist/compass.js

@@ -0,0 +1,52 @@
+import { createSignal, onCleanup } from "solid-js";
+import { isServer } from "@solidjs/web";
+import { makeSensor } from "./sensor.js";
+const OWNED_WRITE = { ownedWrite: true };
+/**
+ * Sets up a `Magnetometer` sensor and calls `onChange` with x/y/z readings in microteslas.
+ * Uses the Generic Sensor API (`window.Magnetometer`).
+ * Returns `null` if the Magnetometer API is unavailable or throws on construction.
+ *
+ * @param onChange Called on each reading with `{ x, y, z }` in microteslas (null coerced to 0)
+ * @param options Optional `{ frequency, referenceFrame }` passed to the Magnetometer constructor
+ * @returns Cleanup function that stops the sensor, or `null` if unsupported
+ */
+export const makeCompass = (onChange, options) => {
+    if (!("Magnetometer" in globalThis))
+        return null;
+    return makeSensor(globalThis.Magnetometer, s => onChange({ x: s.x ?? 0, y: s.y ?? 0, z: s.z ?? 0 }), options);
+};
+/**
+ * Creates a reactive object with `x`, `y`, `z` magnetometer readings in microteslas.
+ * All properties start at `0` and update on each sensor reading.
+ * Returns a non-reactive `{ x: 0, y: 0, z: 0 }` on the server.
+ * Registers cleanup with `onCleanup` when inside a reactive owner.
+ *
+ * @param options Optional `{ frequency, referenceFrame }` passed to the Magnetometer constructor
+ * @returns Reactive CompassReading object `{ x, y, z }`
+ */
+export const createCompass = (options) => {
+    if (isServer)
+        return { x: 0, y: 0, z: 0 };
+    const [x, setX] = createSignal(0, OWNED_WRITE);
+    const [y, setY] = createSignal(0, OWNED_WRITE);
+    const [z, setZ] = createSignal(0, OWNED_WRITE);
+    const cleanup = makeCompass(r => {
+        setX(r.x);
+        setY(r.y);
+        setZ(r.z);
+    }, options);
+    if (cleanup)
+        onCleanup(cleanup);
+    return {
+        get x() {
+            return x();
+        },
+        get y() {
+            return y();
+        },
+        get z() {
+            return z();
+        },
+    };
+};

package/dist/gyroscope.d.ts

@@ -0,0 +1,25 @@
+export type GyroscopeReading = {
+    alpha: number;
+    beta: number;
+    gamma: number;
+};
+/**
+ * Sets up a raw `deviceorientation` event listener and returns a cleanup function.
+ * No Solid lifecycle — suitable for use outside a reactive owner.
+ *
+ * @param onChange Called on each (throttled) orientation event with alpha/beta/gamma values
+ * @param options.interval Minimum milliseconds between onChange calls (default 100)
+ * @returns Cleanup function that removes the event listener
+ */
+export declare const makeGyroscope: (onChange: (orientation: GyroscopeReading) => void, options?: {
+    interval?: number;
+}) => VoidFunction;
+/**
+ * Creates a reactive object tracking device orientation (gyroscope data).
+ * Returns an object with reactive `alpha`, `beta`, and `gamma` properties.
+ * Registers cleanup with `onCleanup` when inside a reactive owner.
+ *
+ * @param interval Minimum milliseconds between updates (default 100)
+ * @returns Reactive GyroscopeReading object `{ alpha, beta, gamma }`
+ */
+export declare const createGyroscope: (interval?: number) => GyroscopeReading;

package/dist/gyroscope.js

@@ -0,0 +1,62 @@
+import { createSignal, onCleanup } from "solid-js";
+import { isServer } from "@solidjs/web";
+const OWNED_WRITE = { ownedWrite: true };
+/**
+ * Sets up a raw `deviceorientation` event listener and returns a cleanup function.
+ * No Solid lifecycle — suitable for use outside a reactive owner.
+ *
+ * @param onChange Called on each (throttled) orientation event with alpha/beta/gamma values
+ * @param options.interval Minimum milliseconds between onChange calls (default 100)
+ * @returns Cleanup function that removes the event listener
+ */
+export const makeGyroscope = (onChange, options = {}) => {
+    const { interval = 100 } = options;
+    let throttled = false;
+    const handler = (e) => {
+        if (throttled)
+            return;
+        throttled = true;
+        setTimeout(() => {
+            throttled = false;
+        }, interval);
+        onChange({
+            alpha: e.alpha ?? 0,
+            beta: e.beta ?? 0,
+            gamma: e.gamma ?? 0,
+        });
+    };
+    addEventListener("deviceorientation", handler);
+    return () => removeEventListener("deviceorientation", handler);
+};
+/**
+ * Creates a reactive object tracking device orientation (gyroscope data).
+ * Returns an object with reactive `alpha`, `beta`, and `gamma` properties.
+ * Registers cleanup with `onCleanup` when inside a reactive owner.
+ *
+ * @param interval Minimum milliseconds between updates (default 100)
+ * @returns Reactive GyroscopeReading object `{ alpha, beta, gamma }`
+ */
+export const createGyroscope = (interval = 100) => {
+    if (isServer)
+        return { alpha: 0, beta: 0, gamma: 0 };
+    const [alpha, setAlpha] = createSignal(0, OWNED_WRITE);
+    const [beta, setBeta] = createSignal(0, OWNED_WRITE);
+    const [gamma, setGamma] = createSignal(0, OWNED_WRITE);
+    const cleanup = makeGyroscope(o => {
+        setAlpha(o.alpha);
+        setBeta(o.beta);
+        setGamma(o.gamma);
+    }, { interval });
+    onCleanup(cleanup);
+    return {
+        get alpha() {
+            return alpha();
+        },
+        get beta() {
+            return beta();
+        },
+        get gamma() {
+            return gamma();
+        },
+    };
+};

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./accelerometer.js";
+export * from "./gyroscope.js";
+export * from "./sensor.js";
+export * from "./compass.js";
+export * from "./battery.js";

package/dist/index.js

@@ -0,0 +1,5 @@
+export * from "./accelerometer.js";
+export * from "./gyroscope.js";
+export * from "./sensor.js";
+export * from "./compass.js";
+export * from "./battery.js";

package/dist/sensor.d.ts

@@ -0,0 +1,43 @@
+import type { Accessor } from "solid-js";
+/** Options shared by all Generic Sensor API primitives. */
+export type SensorOptions = {
+    frequency?: number;
+};
+/**
+ * Minimal Generic Sensor API interface (not in the standard TypeScript DOM lib).
+ * Extend this to type specific sensors passed to `makeSensor` / `createSensor`.
+ */
+export interface GenericSensor extends EventTarget {
+    readonly activated: boolean;
+    readonly hasReading: boolean;
+    readonly timestamp: DOMHighResTimeStamp | undefined;
+    start(): void;
+    stop(): void;
+}
+/**
+ * Sets up any Generic Sensor API sensor and calls `onChange` on each reading.
+ * Returns a cleanup function, or `null` if the sensor constructor throws
+ * (e.g. the API is unsupported or permission was denied).
+ *
+ * @param SensorClass Any Generic Sensor API constructor (Magnetometer, LinearAccelerationSensor, etc.)
+ * @param onChange Called with the live sensor object on each reading event
+ * @param options Optional `{ frequency }` passed to the sensor constructor
+ * @returns Cleanup function that stops and removes the sensor, or `null` on failure
+ */
+export declare const makeSensor: <T extends GenericSensor>(SensorClass: {
+    new (options?: any): T;
+}, onChange: (sensor: T) => void, options?: SensorOptions) => VoidFunction | null;
+/**
+ * Creates a reactive accessor for any Generic Sensor API sensor.
+ * The accessor re-fires on every reading event (even if the sensor object reference
+ * is the same) because the underlying signal uses `equals: false`.
+ * Returns `undefined` until the first reading or if the sensor is unavailable.
+ * Returns a static `() => undefined` on the server.
+ *
+ * @param SensorClass Any Generic Sensor API constructor
+ * @param options Optional `{ frequency }` passed to the sensor constructor
+ * @returns Accessor yielding the live sensor object (updated on every reading), or `undefined`
+ */
+export declare const createSensor: <T extends GenericSensor>(SensorClass: {
+    new (options?: any): T;
+}, options?: SensorOptions) => Accessor<T | undefined>;

package/dist/sensor.js

@@ -0,0 +1,52 @@
+import { createSignal, onCleanup } from "solid-js";
+import { isServer } from "@solidjs/web";
+const OWNED_WRITE = { ownedWrite: true };
+/**
+ * Sets up any Generic Sensor API sensor and calls `onChange` on each reading.
+ * Returns a cleanup function, or `null` if the sensor constructor throws
+ * (e.g. the API is unsupported or permission was denied).
+ *
+ * @param SensorClass Any Generic Sensor API constructor (Magnetometer, LinearAccelerationSensor, etc.)
+ * @param onChange Called with the live sensor object on each reading event
+ * @param options Optional `{ frequency }` passed to the sensor constructor
+ * @returns Cleanup function that stops and removes the sensor, or `null` on failure
+ */
+export const makeSensor = (SensorClass, onChange, options) => {
+    let sensor;
+    try {
+        sensor = new SensorClass(options);
+    }
+    catch {
+        return null;
+    }
+    const handleReading = () => onChange(sensor);
+    sensor.addEventListener("reading", handleReading);
+    sensor.start();
+    return () => {
+        sensor.removeEventListener("reading", handleReading);
+        sensor.stop();
+    };
+};
+/**
+ * Creates a reactive accessor for any Generic Sensor API sensor.
+ * The accessor re-fires on every reading event (even if the sensor object reference
+ * is the same) because the underlying signal uses `equals: false`.
+ * Returns `undefined` until the first reading or if the sensor is unavailable.
+ * Returns a static `() => undefined` on the server.
+ *
+ * @param SensorClass Any Generic Sensor API constructor
+ * @param options Optional `{ frequency }` passed to the sensor constructor
+ * @returns Accessor yielding the live sensor object (updated on every reading), or `undefined`
+ */
+export const createSensor = (SensorClass, options) => {
+    if (isServer)
+        return () => undefined;
+    const [sensor, setSensor] = createSignal(undefined, {
+        ...OWNED_WRITE,
+        equals: false,
+    });
+    const cleanup = makeSensor(SensorClass, s => setSensor(s), options);
+    if (cleanup)
+        onCleanup(cleanup);
+    return sensor;
+};

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "@solid-primitives/sensors",
+  "version": "1.0.0-next.0",
+  "description": "Primitives for device sensors: accelerometer, gyroscope, compass, battery, and generic Sensor API.",
+  "author": "David Di Biase <dave@solidjs.com>",
+  "contributors": [],
+  "license": "MIT",
+  "homepage": "https://primitives.solidjs.community/package/sensors",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/solidjs-community/solid-primitives.git"
+  },
+  "bugs": {
+    "url": "https://github.com/solidjs-community/solid-primitives/issues"
+  },
+  "primitive": {
+    "name": "sensors",
+    "stage": 3,
+    "list": [
+      "makeAccelerometer",
+      "createAccelerometer",
+      "makeGyroscope",
+      "createGyroscope",
+      "makeSensor",
+      "createSensor",
+      "makeCompass",
+      "createCompass",
+      "makeBattery",
+      "createBattery"
+    ],
+    "category": "Display & Media",
+    "gzip": 1195
+  },
+  "keywords": [
+    "accelerometer",
+    "gyroscope",
+    "sensors",
+    "solid",
+    "primitives"
+  ],
+  "private": false,
+  "sideEffects": false,
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "browser": {},
+  "exports": {
+    "import": {
+      "@solid-primitives/source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "typesVersions": {},
+  "peerDependencies": {
+    "solid-js": "^2.0.0-beta.15"
+  },
+  "devDependencies": {
+    "@solidjs/web": "2.0.0-beta.15",
+    "solid-js": "2.0.0-beta.15"
+  },
+  "scripts": {
+    "dev": "node --import=@nothing-but/node-resolve-ts --experimental-transform-types ../../scripts/dev.ts",
+    "build": "node --import=@nothing-but/node-resolve-ts --experimental-transform-types ../../scripts/build.ts",
+    "vitest": "vitest -c ../../configs/vitest.config.ts",
+    "test": "pnpm run vitest",
+    "test:ssr": "pnpm run vitest --mode ssr"
+  }
+}