@symbiote-native/sensors 0.1.0

package/src/react/hooks/use-light-sensor/index.ts

@@ -0,0 +1,21 @@
+// React lifecycle wiring over the framework-agnostic LightSensor singleton (core/) —
+// mirrors the lifecycle-bucket naming convention of adapters/react/src/hooks.
+import { useEffect, useState } from 'react';
+import { LightSensor, type ILightSensorMeasurement } from '../../../core';
+
+export function useLightSensor(updateIntervalMs?: number): ILightSensorMeasurement | null {
+  const [measurement, setMeasurement] = useState<ILightSensorMeasurement | null>(null);
+
+  useEffect(() => {
+    // Re-subscribing on interval change keeps the native update rate in sync with the
+    // caller's latest `updateIntervalMs` rather than only ever honoring the first mount's.
+    if (updateIntervalMs !== undefined) {
+      LightSensor.setUpdateInterval(updateIntervalMs);
+    }
+
+    const subscription = LightSensor.addListener(setMeasurement);
+    return () => subscription.remove();
+  }, [updateIntervalMs]);
+
+  return measurement;
+}

package/src/react/hooks/use-light-sensor/use-light-sensor.test.tsx

@@ -0,0 +1,79 @@
+// Co-located React-driven test (ADR 0025) for useLightSensor. Mocks the whole `core`
+// module rather than expo-modules-core internals — this hook's own lifecycle wiring
+// (subscribe/unsubscribe/interval) is what's under test, not the core port itself, which
+// already has its own coverage in packages/sensors/src/core/*.test.ts.
+
+import { createElement, type ReactElement } from 'react';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { mount, unmount, View } from '@symbiote-native/react';
+import { installFabric } from '@symbiote-native/test-utils';
+import { useLightSensor } from './index';
+import type { ILightSensorMeasurement } from '../../../core';
+
+const { addListener, removeAllListeners, setUpdateInterval, remove } = vi.hoisted(() => {
+  const remove = vi.fn();
+  return {
+    addListener: vi.fn((_listener: (measurement: ILightSensorMeasurement) => void) => ({ remove })),
+    removeAllListeners: vi.fn(),
+    setUpdateInterval: vi.fn(),
+    remove,
+  };
+});
+
+vi.mock('../../../core', () => ({
+  LightSensor: { addListener, removeAllListeners, setUpdateInterval },
+}));
+
+const ROOT_TAG = 902;
+
+const results: Array<ILightSensorMeasurement | null> = [];
+
+function Probe(props: { updateIntervalMs?: number }): ReactElement {
+  results.push(useLightSensor(props.updateIntervalMs));
+  return createElement(View);
+}
+
+const fabric = installFabric();
+
+beforeEach(() => {
+  fabric.reset();
+  results.length = 0;
+  vi.clearAllMocks();
+});
+
+afterEach(() => unmount(ROOT_TAG));
+
+describe('useLightSensor', () => {
+  it('reports null before any native measurement arrives', () => {
+    mount(ROOT_TAG, createElement(Probe, {}));
+
+    expect(results[results.length - 1]).toBeNull();
+  });
+
+  it('updates to the latest measurement once the native listener fires', async () => {
+    mount(ROOT_TAG, createElement(Probe, {}));
+
+    const measurement: ILightSensorMeasurement = { illuminance: 42, timestamp: 123 };
+    const listener = addListener.mock.calls[0][0];
+    listener(measurement);
+
+    // The mock invokes the listener directly, outside the engine's event dispatcher
+    // (setEventDispatcher in render.ts), which is what normally flushes a native-driven
+    // setState synchronously — so the resulting re-render lands on a later microtask here.
+    await vi.waitFor(() => expect(results[results.length - 1]).toEqual(measurement));
+  });
+
+  it('unsubscribes from the native listener on unmount', () => {
+    mount(ROOT_TAG, createElement(Probe, {}));
+
+    unmount(ROOT_TAG);
+
+    expect(remove).toHaveBeenCalledTimes(1);
+  });
+
+  it('sets the native update interval when updateIntervalMs is provided', () => {
+    mount(ROOT_TAG, createElement(Probe, { updateIntervalMs: 100 }));
+
+    expect(setUpdateInterval).toHaveBeenCalledWith(100);
+  });
+});

package/src/react/hooks/use-magnetometer/index.ts

@@ -0,0 +1,21 @@
+// React lifecycle wiring over the framework-agnostic Magnetometer singleton (core/) —
+// mirrors the lifecycle-bucket naming convention of adapters/react/src/hooks.
+import { useEffect, useState } from 'react';
+import { Magnetometer, type IMagnetometerMeasurement } from '../../../core';
+
+export function useMagnetometer(updateIntervalMs?: number): IMagnetometerMeasurement | null {
+  const [measurement, setMeasurement] = useState<IMagnetometerMeasurement | null>(null);
+
+  useEffect(() => {
+    // Re-subscribing on interval change keeps the native update rate in sync with the
+    // caller's latest `updateIntervalMs` rather than only ever honoring the first mount's.
+    if (updateIntervalMs !== undefined) {
+      Magnetometer.setUpdateInterval(updateIntervalMs);
+    }
+
+    const subscription = Magnetometer.addListener(setMeasurement);
+    return () => subscription.remove();
+  }, [updateIntervalMs]);
+
+  return measurement;
+}

package/src/react/hooks/use-magnetometer/use-magnetometer.test.tsx

@@ -0,0 +1,81 @@
+// Co-located React-driven test (ADR 0025) for useMagnetometer. Mocks the whole `core`
+// module rather than expo-modules-core internals — this hook's own lifecycle wiring
+// (subscribe/unsubscribe/interval) is what's under test, not the core port itself, which
+// already has its own coverage in packages/sensors/src/core/*.test.ts.
+
+import { createElement, type ReactElement } from 'react';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { mount, unmount, View } from '@symbiote-native/react';
+import { installFabric } from '@symbiote-native/test-utils';
+import { useMagnetometer } from './index';
+import type { IMagnetometerMeasurement } from '../../../core';
+
+const { addListener, removeAllListeners, setUpdateInterval, remove } = vi.hoisted(() => {
+  const remove = vi.fn();
+  return {
+    addListener: vi.fn((_listener: (measurement: IMagnetometerMeasurement) => void) => ({
+      remove,
+    })),
+    removeAllListeners: vi.fn(),
+    setUpdateInterval: vi.fn(),
+    remove,
+  };
+});
+
+vi.mock('../../../core', () => ({
+  Magnetometer: { addListener, removeAllListeners, setUpdateInterval },
+}));
+
+const ROOT_TAG = 902;
+
+const results: Array<IMagnetometerMeasurement | null> = [];
+
+function Probe(props: { updateIntervalMs?: number }): ReactElement {
+  results.push(useMagnetometer(props.updateIntervalMs));
+  return createElement(View);
+}
+
+const fabric = installFabric();
+
+beforeEach(() => {
+  fabric.reset();
+  results.length = 0;
+  vi.clearAllMocks();
+});
+
+afterEach(() => unmount(ROOT_TAG));
+
+describe('useMagnetometer', () => {
+  it('reports null before any native measurement arrives', () => {
+    mount(ROOT_TAG, createElement(Probe, {}));
+
+    expect(results[results.length - 1]).toBeNull();
+  });
+
+  it('updates to the latest measurement once the native listener fires', async () => {
+    mount(ROOT_TAG, createElement(Probe, {}));
+
+    const measurement: IMagnetometerMeasurement = { x: 0.1, y: 0.2, z: 0.3, timestamp: 123 };
+    const listener = addListener.mock.calls[0][0];
+    listener(measurement);
+
+    // The mock invokes the listener directly, outside the engine's event dispatcher
+    // (setEventDispatcher in render.ts), which is what normally flushes a native-driven
+    // setState synchronously — so the resulting re-render lands on a later microtask here.
+    await vi.waitFor(() => expect(results[results.length - 1]).toEqual(measurement));
+  });
+
+  it('unsubscribes from the native listener on unmount', () => {
+    mount(ROOT_TAG, createElement(Probe, {}));
+
+    unmount(ROOT_TAG);
+
+    expect(remove).toHaveBeenCalledTimes(1);
+  });
+
+  it('sets the native update interval when updateIntervalMs is provided', () => {
+    mount(ROOT_TAG, createElement(Probe, { updateIntervalMs: 100 }));
+
+    expect(setUpdateInterval).toHaveBeenCalledWith(100);
+  });
+});

package/src/react/hooks/use-magnetometer-uncalibrated/index.ts

@@ -0,0 +1,23 @@
+// React lifecycle wiring over the framework-agnostic MagnetometerUncalibrated singleton
+// (core/) — mirrors the lifecycle-bucket naming convention of adapters/react/src/hooks.
+import { useEffect, useState } from 'react';
+import { MagnetometerUncalibrated, type IMagnetometerUncalibratedMeasurement } from '../../../core';
+
+export function useMagnetometerUncalibrated(
+  updateIntervalMs?: number,
+): IMagnetometerUncalibratedMeasurement | null {
+  const [measurement, setMeasurement] = useState<IMagnetometerUncalibratedMeasurement | null>(null);
+
+  useEffect(() => {
+    // Re-subscribing on interval change keeps the native update rate in sync with the
+    // caller's latest `updateIntervalMs` rather than only ever honoring the first mount's.
+    if (updateIntervalMs !== undefined) {
+      MagnetometerUncalibrated.setUpdateInterval(updateIntervalMs);
+    }
+
+    const subscription = MagnetometerUncalibrated.addListener(setMeasurement);
+    return () => subscription.remove();
+  }, [updateIntervalMs]);
+
+  return measurement;
+}

package/src/react/hooks/use-magnetometer-uncalibrated/use-magnetometer-uncalibrated.test.tsx

@@ -0,0 +1,88 @@
+// Co-located React-driven test (ADR 0025) for useMagnetometerUncalibrated. Mocks the whole
+// `core` module rather than expo-modules-core internals — this hook's own lifecycle wiring
+// (subscribe/unsubscribe/interval) is what's under test, not the core port itself, which
+// already has its own coverage in packages/sensors/src/core/*.test.ts.
+
+import { createElement, type ReactElement } from 'react';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { mount, unmount, View } from '@symbiote-native/react';
+import { installFabric } from '@symbiote-native/test-utils';
+import { useMagnetometerUncalibrated } from './index';
+import type { IMagnetometerUncalibratedMeasurement } from '../../../core';
+
+const { addListener, removeAllListeners, setUpdateInterval, remove } = vi.hoisted(() => {
+  const remove = vi.fn();
+  return {
+    addListener: vi.fn(
+      (_listener: (measurement: IMagnetometerUncalibratedMeasurement) => void) => ({
+        remove,
+      }),
+    ),
+    removeAllListeners: vi.fn(),
+    setUpdateInterval: vi.fn(),
+    remove,
+  };
+});
+
+vi.mock('../../../core', () => ({
+  MagnetometerUncalibrated: { addListener, removeAllListeners, setUpdateInterval },
+}));
+
+const ROOT_TAG = 902;
+
+const results: Array<IMagnetometerUncalibratedMeasurement | null> = [];
+
+function Probe(props: { updateIntervalMs?: number }): ReactElement {
+  results.push(useMagnetometerUncalibrated(props.updateIntervalMs));
+  return createElement(View);
+}
+
+const fabric = installFabric();
+
+beforeEach(() => {
+  fabric.reset();
+  results.length = 0;
+  vi.clearAllMocks();
+});
+
+afterEach(() => unmount(ROOT_TAG));
+
+describe('useMagnetometerUncalibrated', () => {
+  it('reports null before any native measurement arrives', () => {
+    mount(ROOT_TAG, createElement(Probe, {}));
+
+    expect(results[results.length - 1]).toBeNull();
+  });
+
+  it('updates to the latest measurement once the native listener fires', async () => {
+    mount(ROOT_TAG, createElement(Probe, {}));
+
+    const measurement: IMagnetometerUncalibratedMeasurement = {
+      x: 0.1,
+      y: 0.2,
+      z: 0.3,
+      timestamp: 123,
+    };
+    const listener = addListener.mock.calls[0][0];
+    listener(measurement);
+
+    // The mock invokes the listener directly, outside the engine's event dispatcher
+    // (setEventDispatcher in render.ts), which is what normally flushes a native-driven
+    // setState synchronously — so the resulting re-render lands on a later microtask here.
+    await vi.waitFor(() => expect(results[results.length - 1]).toEqual(measurement));
+  });
+
+  it('unsubscribes from the native listener on unmount', () => {
+    mount(ROOT_TAG, createElement(Probe, {}));
+
+    unmount(ROOT_TAG);
+
+    expect(remove).toHaveBeenCalledTimes(1);
+  });
+
+  it('sets the native update interval when updateIntervalMs is provided', () => {
+    mount(ROOT_TAG, createElement(Probe, { updateIntervalMs: 100 }));
+
+    expect(setUpdateInterval).toHaveBeenCalledWith(100);
+  });
+});

package/src/react/hooks/use-pedometer/index.ts

@@ -0,0 +1,17 @@
+// React lifecycle wiring over the framework-agnostic watchStepCount free function (core/) —
+// mirrors the lifecycle-bucket naming convention of adapters/react/src/hooks. Unlike
+// useAccelerometer, Pedometer has no setUpdateInterval, so there is no updateIntervalMs param
+// to sync on re-render.
+import { useEffect, useState } from 'react';
+import { watchStepCount, type IPedometerResult } from '../../../core';
+
+export function usePedometer(): IPedometerResult | null {
+  const [result, setResult] = useState<IPedometerResult | null>(null);
+
+  useEffect(() => {
+    const subscription = watchStepCount(setResult);
+    return () => subscription.remove();
+  }, []);
+
+  return result;
+}

package/src/react/hooks/use-pedometer/use-pedometer.test.tsx

@@ -0,0 +1,69 @@
+// Co-located React-driven test (ADR 0025) for usePedometer. Mocks the whole `core` module
+// rather than expo-modules-core internals — this hook's own lifecycle wiring (subscribe/
+// unsubscribe) is what's under test, not the core port itself, which already has its own
+// coverage in packages/sensors/src/core/pedometer.test.ts.
+
+import { createElement, type ReactElement } from 'react';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { mount, unmount, View } from '@symbiote-native/react';
+import { installFabric } from '@symbiote-native/test-utils';
+import { usePedometer } from './index';
+import type { IPedometerResult } from '../../../core';
+
+const { watchStepCount, remove } = vi.hoisted(() => {
+  const remove = vi.fn();
+  return {
+    watchStepCount: vi.fn((_callback: (result: IPedometerResult) => void) => ({ remove })),
+    remove,
+  };
+});
+
+vi.mock('../../../core', () => ({ watchStepCount }));
+
+const ROOT_TAG = 902;
+
+const results: Array<IPedometerResult | null> = [];
+
+function Probe(): ReactElement {
+  results.push(usePedometer());
+  return createElement(View);
+}
+
+const fabric = installFabric();
+
+beforeEach(() => {
+  fabric.reset();
+  results.length = 0;
+  vi.clearAllMocks();
+});
+
+afterEach(() => unmount(ROOT_TAG));
+
+describe('usePedometer', () => {
+  it('reports null before any native step count arrives', () => {
+    mount(ROOT_TAG, createElement(Probe));
+
+    expect(results[results.length - 1]).toBeNull();
+  });
+
+  it('updates to the latest result once the native listener fires', async () => {
+    mount(ROOT_TAG, createElement(Probe));
+
+    const result: IPedometerResult = { steps: 123 };
+    const listener = watchStepCount.mock.calls[0][0];
+    listener(result);
+
+    // The mock invokes the listener directly, outside the engine's event dispatcher
+    // (setEventDispatcher in render.ts), which is what normally flushes a native-driven
+    // setState synchronously — so the resulting re-render lands on a later microtask here.
+    await vi.waitFor(() => expect(results[results.length - 1]).toEqual(result));
+  });
+
+  it('unsubscribes from the native listener on unmount', () => {
+    mount(ROOT_TAG, createElement(Probe));
+
+    unmount(ROOT_TAG);
+
+    expect(remove).toHaveBeenCalledTimes(1);
+  });
+});

package/src/react/index.ts

@@ -0,0 +1,29 @@
+// @symbiote-native/sensors/react: the React entry over the framework-agnostic core.
+// useAccelerometer wraps the Accelerometer singleton with React's own lifecycle
+// (hooks/use-accelerometer) — mirrors the lifecycle-bucket naming convention of
+// adapters/react/src/hooks (never `composables`, that's Vue's term).
+
+export { useAccelerometer } from './hooks/use-accelerometer';
+export type { IAccelerometerMeasurement } from '../core';
+export { useBarometer } from './hooks/use-barometer';
+export type { IBarometerMeasurement } from '../core';
+export { useDeviceMotion } from './hooks/use-device-motion';
+export { DeviceMotionOrientation, gravity, type IDeviceMotionMeasurement } from '../core';
+export { useGyroscope } from './hooks/use-gyroscope';
+export type { IGyroscopeMeasurement } from '../core';
+export { useLightSensor } from './hooks/use-light-sensor';
+export type { ILightSensorMeasurement } from '../core';
+export { useMagnetometer } from './hooks/use-magnetometer';
+export type { IMagnetometerMeasurement } from '../core';
+export { useMagnetometerUncalibrated } from './hooks/use-magnetometer-uncalibrated';
+export type { IMagnetometerUncalibratedMeasurement } from '../core';
+export { usePedometer } from './hooks/use-pedometer';
+export {
+  watchStepCount,
+  getStepCountAsync,
+  isAvailableAsync,
+  getPermissionsAsync,
+  requestPermissionsAsync,
+  type IPedometerResult,
+  type IPedometerUpdateCallback,
+} from '../core';

package/src/vue/composables/use-accelerometer/index.ts

@@ -0,0 +1,34 @@
+// Vue lifecycle wiring over the framework-agnostic Accelerometer singleton (core/) — mirrors
+// the lifecycle-bucket naming convention of adapters/vue/src/composables and the
+// onMounted/onUnmounted shape of use-color-scheme.ts's subscription handle. Unlike
+// use-hide-animation.ts (which takes a config getter because its consumer's config changes
+// across reactive updates), this subscribes exactly once at mount and never needs to react to
+// a later change of updateIntervalMs, so a plain numeric param is enough.
+
+import { onMounted, onUnmounted, ref, type Ref } from '@vue/runtime-core';
+import {
+  Accelerometer,
+  type EventSubscription,
+  type IAccelerometerMeasurement,
+} from '../../../core';
+
+export function useAccelerometer(updateIntervalMs?: number): Ref<IAccelerometerMeasurement | null> {
+  // A plain ref: the value is a POJO measurement, not an engine node, so no shallowRef needed.
+  const measurement = ref<IAccelerometerMeasurement | null>(null);
+  let subscription: EventSubscription | undefined;
+
+  onMounted(() => {
+    if (updateIntervalMs !== undefined) {
+      Accelerometer.setUpdateInterval(updateIntervalMs);
+    }
+    subscription = Accelerometer.addListener(next => {
+      measurement.value = next;
+    });
+  });
+
+  onUnmounted(() => {
+    subscription?.remove();
+  });
+
+  return measurement;
+}

package/src/vue/composables/use-accelerometer/use-accelerometer.test.ts

@@ -0,0 +1,96 @@
+// Co-located Vue-driven test (ADR 0025) for useAccelerometer. Mocks the whole core module
+// (never expo-modules-core internals) since this exercises composable mount/unmount lifecycle
+// timing, not any native view — there is none here, so no ViewConfig fixture is needed.
+
+import { defineComponent, h, type Ref } from '@vue/runtime-core';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { mount, unmount } from '@symbiote-native/vue';
+import { installFabric } from '@symbiote-native/test-utils';
+import type { IAccelerometerMeasurement } from '../../../core';
+import { useAccelerometer } from './index';
+
+const ROOT_TAG = 9821;
+
+type IListener = (measurement: IAccelerometerMeasurement) => void;
+
+let registeredListener: IListener | undefined;
+const removeMock = vi.fn();
+const addListenerMock = vi.fn((listener: IListener) => {
+  registeredListener = listener;
+  return { remove: removeMock };
+});
+const setUpdateIntervalMock = vi.fn();
+
+vi.mock('../../../core', () => ({
+  Accelerometer: {
+    addListener: (listener: IListener) => addListenerMock(listener),
+    removeAllListeners: vi.fn(),
+    setUpdateInterval: (intervalMs: number) => setUpdateIntervalMock(intervalMs),
+  },
+}));
+
+const fabric = installFabric();
+
+beforeEach(() => {
+  fabric.reset();
+  registeredListener = undefined;
+  addListenerMock.mockClear();
+  removeMock.mockClear();
+  setUpdateIntervalMock.mockClear();
+});
+
+afterEach(() => unmount(ROOT_TAG));
+
+function mountAccelerometer(updateIntervalMs?: number): Ref<IAccelerometerMeasurement | null> {
+  let measurement: Ref<IAccelerometerMeasurement | null> | undefined;
+  mount(
+    ROOT_TAG,
+    defineComponent({
+      setup: () => {
+        measurement = useAccelerometer(updateIntervalMs);
+        return () => h('symbiote-text', {}, 'sensor');
+      },
+    }),
+  );
+  if (measurement === undefined) {
+    throw new Error('setup() did not run');
+  }
+  return measurement;
+}
+
+describe('useAccelerometer (Vue)', () => {
+  it('starts null before any measurement arrives', () => {
+    const measurement = mountAccelerometer();
+
+    expect(measurement.value).toBeNull();
+  });
+
+  it('updates the ref when the native listener fires', () => {
+    const measurement = mountAccelerometer();
+    const reading: IAccelerometerMeasurement = { x: 0.1, y: 0.2, z: 0.9, timestamp: 123 };
+
+    registeredListener?.(reading);
+
+    expect(measurement.value).toEqual(reading);
+  });
+
+  it('removes the subscription on unmount', () => {
+    mountAccelerometer();
+    unmount(ROOT_TAG);
+
+    expect(removeMock).toHaveBeenCalledTimes(1);
+  });
+
+  it('sets the update interval once at subscribe time when provided', () => {
+    mountAccelerometer(50);
+
+    expect(setUpdateIntervalMock).toHaveBeenCalledWith(50);
+    expect(setUpdateIntervalMock).toHaveBeenCalledTimes(1);
+  });
+
+  it('does not touch the update interval when omitted', () => {
+    mountAccelerometer();
+
+    expect(setUpdateIntervalMock).not.toHaveBeenCalled();
+  });
+});

package/src/vue/composables/use-barometer/index.ts

@@ -0,0 +1,30 @@
+// Vue lifecycle wiring over the framework-agnostic Barometer singleton (core/) — mirrors
+// the lifecycle-bucket naming convention of adapters/vue/src/composables and the
+// onMounted/onUnmounted shape of use-color-scheme.ts's subscription handle. Unlike
+// use-hide-animation.ts (which takes a config getter because its consumer's config changes
+// across reactive updates), this subscribes exactly once at mount and never needs to react to
+// a later change of updateIntervalMs, so a plain numeric param is enough.
+
+import { onMounted, onUnmounted, ref, type Ref } from '@vue/runtime-core';
+import { Barometer, type EventSubscription, type IBarometerMeasurement } from '../../../core';
+
+export function useBarometer(updateIntervalMs?: number): Ref<IBarometerMeasurement | null> {
+  // A plain ref: the value is a POJO measurement, not an engine node, so no shallowRef needed.
+  const measurement = ref<IBarometerMeasurement | null>(null);
+  let subscription: EventSubscription | undefined;
+
+  onMounted(() => {
+    if (updateIntervalMs !== undefined) {
+      Barometer.setUpdateInterval(updateIntervalMs);
+    }
+    subscription = Barometer.addListener(next => {
+      measurement.value = next;
+    });
+  });
+
+  onUnmounted(() => {
+    subscription?.remove();
+  });
+
+  return measurement;
+}