@symbiote-native/screen-orientation 0.0.1

package/src/core/screen-orientation.ts

@@ -0,0 +1,186 @@
+// Hand-ported from .vendors/expo/packages/expo-screen-orientation/src/ScreenOrientation.ts
+// (sdk-57). Unlike battery, upstream ScreenOrientation throws UnavailabilityError when the
+// native method is absent — same convention as packages/network/src/core/network.ts.
+import { Platform, UnavailabilityError, type EventSubscription } from 'expo-modules-core';
+import { Dimensions } from 'react-native';
+import { expoScreenOrientation, type IPlatformOrientationParam } from './native-module';
+import {
+  Orientation,
+  OrientationLock,
+  WebOrientationLock,
+  type OrientationChangeEvent,
+  type OrientationChangeListener,
+  type PlatformOrientationInfo,
+} from './types';
+
+const NATIVE_MODULE_NAME = 'ScreenOrientation';
+
+let _orientationChangeSubscribers: EventSubscription[] = [];
+let _lastOrientationLock: OrientationLock = OrientationLock.UNKNOWN;
+
+/** Locks the screen to the given orientation. */
+export async function lockAsync(orientationLock: OrientationLock): Promise<void> {
+  if (!expoScreenOrientation.lockAsync) {
+    throw new UnavailabilityError(NATIVE_MODULE_NAME, 'lockAsync');
+  }
+  const orientationLocks = Object.values(OrientationLock);
+  if (!orientationLocks.includes(orientationLock)) {
+    throw new TypeError(`Invalid Orientation Lock: ${orientationLock}`);
+  }
+  if (orientationLock === OrientationLock.OTHER) {
+    return;
+  }
+  await expoScreenOrientation.lockAsync(orientationLock);
+  _lastOrientationLock = orientationLock;
+}
+
+/** Locks the screen to a platform-specific orientation param — Android constant, iOS
+ * orientation array, or web `WebOrientationLock`. */
+export async function lockPlatformAsync(options: PlatformOrientationInfo): Promise<void> {
+  if (!expoScreenOrientation.lockPlatformAsync) {
+    throw new UnavailabilityError(NATIVE_MODULE_NAME, 'lockPlatformAsync');
+  }
+  const { screenOrientationConstantAndroid, screenOrientationArrayIOS, screenOrientationLockWeb } =
+    options;
+  let platformOrientationParam: IPlatformOrientationParam | undefined;
+  if (Platform.OS === 'android' && screenOrientationConstantAndroid) {
+    if (isNaN(screenOrientationConstantAndroid)) {
+      throw new TypeError(
+        `lockPlatformAsync Android platform: screenOrientationConstantAndroid cannot be called with ${screenOrientationConstantAndroid}`,
+      );
+    }
+    platformOrientationParam = screenOrientationConstantAndroid;
+  } else if (Platform.OS === 'ios' && screenOrientationArrayIOS) {
+    if (!Array.isArray(screenOrientationArrayIOS)) {
+      throw new TypeError(
+        `lockPlatformAsync iOS platform: screenOrientationArrayIOS cannot be called with ${screenOrientationArrayIOS}`,
+      );
+    }
+    const orientations = Object.values(Orientation);
+    for (const orientation of screenOrientationArrayIOS) {
+      if (!orientations.includes(orientation)) {
+        throw new TypeError(
+          `lockPlatformAsync iOS platform: ${orientation} is not a valid Orientation`,
+        );
+      }
+    }
+    platformOrientationParam = screenOrientationArrayIOS;
+  } else if (Platform.OS === 'web' && screenOrientationLockWeb) {
+    const webOrientationLocks = Object.values(WebOrientationLock);
+    if (!webOrientationLocks.includes(screenOrientationLockWeb)) {
+      throw new TypeError(`Invalid Web Orientation Lock: ${screenOrientationLockWeb}`);
+    }
+    platformOrientationParam = screenOrientationLockWeb;
+  }
+  if (!platformOrientationParam) {
+    throw new TypeError('lockPlatformAsync cannot be called with undefined option properties');
+  }
+  await expoScreenOrientation.lockPlatformAsync(platformOrientationParam);
+  _lastOrientationLock = OrientationLock.OTHER;
+}
+
+/** Unlocks the screen orientation back to the system default. */
+export async function unlockAsync(): Promise<void> {
+  if (!expoScreenOrientation.lockAsync) {
+    throw new UnavailabilityError(NATIVE_MODULE_NAME, 'lockAsync');
+  }
+  await expoScreenOrientation.lockAsync(OrientationLock.DEFAULT);
+}
+
+/** Gets the device's current screen orientation. */
+export async function getOrientationAsync(): Promise<Orientation> {
+  if (!expoScreenOrientation.getOrientationAsync) {
+    throw new UnavailabilityError(NATIVE_MODULE_NAME, 'getOrientationAsync');
+  }
+  return expoScreenOrientation.getOrientationAsync();
+}
+
+/** Gets the current orientation lock, falling back to the last value set via `lockAsync()`/
+ * `lockPlatformAsync()` when the native method itself isn't available. */
+export async function getOrientationLockAsync(): Promise<OrientationLock> {
+  if (!expoScreenOrientation.getOrientationLockAsync) {
+    return _lastOrientationLock;
+  }
+  return expoScreenOrientation.getOrientationLockAsync();
+}
+
+/** Gets the current orientation lock as a platform-specific value. */
+export async function getPlatformOrientationLockAsync(): Promise<PlatformOrientationInfo> {
+  const platformOrientationLock = await expoScreenOrientation.getPlatformOrientationLockAsync?.();
+  if (Platform.OS === 'android' && typeof platformOrientationLock === 'number') {
+    return { screenOrientationConstantAndroid: platformOrientationLock };
+  }
+  if (Platform.OS === 'ios' && Array.isArray(platformOrientationLock)) {
+    return { screenOrientationArrayIOS: platformOrientationLock };
+  }
+  if (Platform.OS === 'web' && typeof platformOrientationLock === 'string') {
+    return { screenOrientationLockWeb: platformOrientationLock };
+  }
+  return {};
+}
+
+/** Whether the given orientation lock is supported on this device. */
+export async function supportsOrientationLockAsync(
+  orientationLock: OrientationLock,
+): Promise<boolean> {
+  if (!expoScreenOrientation.supportsOrientationLockAsync) {
+    throw new UnavailabilityError(NATIVE_MODULE_NAME, 'supportsOrientationLockAsync');
+  }
+  const orientationLocks = Object.values(OrientationLock);
+  if (!orientationLocks.includes(orientationLock)) {
+    throw new TypeError(`Invalid Orientation Lock: ${orientationLock}`);
+  }
+  return expoScreenOrientation.supportsOrientationLockAsync(orientationLock);
+}
+
+/** Subscribes to orientation-change events. */
+export function addOrientationChangeListener(
+  listener: OrientationChangeListener,
+): EventSubscription {
+  if (typeof listener !== 'function') {
+    throw new TypeError(`addOrientationChangeListener cannot be called with ${listener}`);
+  }
+  const subscription = createDidUpdateDimensionsSubscription(listener);
+  _orientationChangeSubscribers.push(subscription);
+  return subscription;
+}
+
+/** Removes every orientation-change listener registered via `addOrientationChangeListener()`. */
+export function removeOrientationChangeListeners(): void {
+  let i = _orientationChangeSubscribers.length;
+  while (i--) {
+    _orientationChangeSubscribers[i]?.remove();
+    _orientationChangeSubscribers.pop();
+  }
+}
+
+/** Removes a single orientation-change listener's subscription. */
+export function removeOrientationChangeListener(subscription: EventSubscription): void {
+  if (!subscription || !subscription.remove) {
+    throw new TypeError('Must pass in a valid subscription');
+  }
+  subscription.remove();
+  _orientationChangeSubscribers = _orientationChangeSubscribers.filter(sub => sub !== subscription);
+}
+
+// IMPORTANT: Android doesn't emit `expoDidUpdateDimensions` — RN's own Dimensions module does,
+// so on Android we piggyback on RN's own `Dimensions.addEventListener('change', ...)` instead.
+function createDidUpdateDimensionsSubscription(
+  listener: OrientationChangeListener,
+): EventSubscription {
+  if (Platform.OS === 'web' || Platform.OS === 'ios') {
+    return expoScreenOrientation.addListener(
+      'expoDidUpdateDimensions',
+      async (update: OrientationChangeEvent) => {
+        listener(update);
+      },
+    );
+  }
+  return Dimensions.addEventListener('change', async () => {
+    const [orientationLock, orientation] = await Promise.all([
+      getOrientationLockAsync(),
+      getOrientationAsync(),
+    ]);
+    listener({ orientationInfo: { orientation }, orientationLock });
+  });
+}

package/src/core/types.ts

@@ -0,0 +1,98 @@
+// Hand-ported from .vendors/expo/packages/expo-screen-orientation/src/ScreenOrientation.types.ts
+// (sdk-57) — plain enums/data shapes, no `expo` meta-package import to swap out (same as
+// packages/network's types.ts).
+
+export enum Orientation {
+  UNKNOWN = 0,
+  PORTRAIT_UP = 1,
+  PORTRAIT_DOWN = 2,
+  LANDSCAPE_LEFT = 3,
+  LANDSCAPE_RIGHT = 4,
+}
+
+/**
+ * Values that can be passed to `lockAsync()`. `ALL`/`PORTRAIT` are invalid on devices that
+ * don't support `PORTRAIT_DOWN`.
+ */
+export enum OrientationLock {
+  /** iOS: all orientations except `PORTRAIT_DOWN`. Android: system decides. */
+  DEFAULT = 0,
+  /** All four possible orientations. */
+  ALL = 1,
+  /** Any portrait orientation. */
+  PORTRAIT = 2,
+  /** Right-side-up portrait only. */
+  PORTRAIT_UP = 3,
+  /** Upside-down portrait only. */
+  PORTRAIT_DOWN = 4,
+  /** Any landscape orientation. */
+  LANDSCAPE = 5,
+  /** Left landscape only. */
+  LANDSCAPE_LEFT = 6,
+  /** Right landscape only. */
+  LANDSCAPE_RIGHT = 7,
+  /** A platform-specific orientation — not a valid `lockAsync()` policy. */
+  OTHER = 8,
+  /** Unknown lock — not a valid `lockAsync()` policy. */
+  UNKNOWN = 9,
+}
+
+/** Each iOS device has a default set of UIKit size classes. */
+export enum SizeClassIOS {
+  UNKNOWN = 0,
+  COMPACT = 1,
+  REGULAR = 2,
+}
+
+export enum WebOrientationLock {
+  PORTRAIT_PRIMARY = 'portrait-primary',
+  PORTRAIT_SECONDARY = 'portrait-secondary',
+  PORTRAIT = 'portrait',
+  LANDSCAPE_PRIMARY = 'landscape-primary',
+  LANDSCAPE_SECONDARY = 'landscape-secondary',
+  LANDSCAPE = 'landscape',
+  ANY = 'any',
+  NATURAL = 'natural',
+  UNKNOWN = 'unknown',
+}
+
+export enum WebOrientation {
+  PORTRAIT_PRIMARY = 'portrait-primary',
+  PORTRAIT_SECONDARY = 'portrait-secondary',
+  LANDSCAPE_PRIMARY = 'landscape-primary',
+  LANDSCAPE_SECONDARY = 'landscape-secondary',
+}
+
+export type PlatformOrientationInfo = {
+  /** @platform android */
+  screenOrientationConstantAndroid?: number;
+  /** @platform ios */
+  screenOrientationArrayIOS?: Orientation[];
+  /** @platform web */
+  screenOrientationLockWeb?: WebOrientationLock;
+};
+
+export type ScreenOrientationInfo = {
+  orientation: Orientation;
+  /** @platform ios */
+  verticalSizeClass?: SizeClassIOS;
+  /** @platform ios */
+  horizontalSizeClass?: SizeClassIOS;
+};
+
+export type OrientationChangeEvent = {
+  orientationLock: OrientationLock;
+  orientationInfo: ScreenOrientationInfo;
+};
+
+export type OrientationChangeListener = (event: OrientationChangeEvent) => void;
+
+/**
+ * The shape shared by every adapter's `useScreenOrientation()` hook/composable/service — not an
+ * upstream expo-screen-orientation type (upstream ships no reactive hook of its own), defined once
+ * here so React/Vue/Angular all consume the identical shape instead of three ad-hoc declarations.
+ */
+export type ScreenOrientationState = {
+  orientation: Orientation;
+  orientationLock: OrientationLock;
+};

package/src/react/hooks/use-screen-orientation/index.ts

@@ -0,0 +1,34 @@
+// React lifecycle wiring over the framework-agnostic core (core/screen-orientation.ts). Seeds
+// the initial value with one-shot getOrientationAsync()/getOrientationLockAsync() calls before
+// the first native event fires, mirroring packages/network's useNetworkState.
+import { useEffect, useState } from 'react';
+import {
+  addOrientationChangeListener,
+  getOrientationAsync,
+  getOrientationLockAsync,
+  Orientation,
+  OrientationLock,
+  type ScreenOrientationState,
+} from '../../../core';
+
+export function useScreenOrientation(): ScreenOrientationState {
+  const [screenOrientation, setScreenOrientation] = useState<ScreenOrientationState>({
+    orientation: Orientation.UNKNOWN,
+    orientationLock: OrientationLock.UNKNOWN,
+  });
+
+  useEffect(() => {
+    Promise.all([getOrientationAsync(), getOrientationLockAsync()]).then(
+      ([orientation, orientationLock]) => setScreenOrientation({ orientation, orientationLock }),
+    );
+    const subscription = addOrientationChangeListener(event =>
+      setScreenOrientation({
+        orientation: event.orientationInfo.orientation,
+        orientationLock: event.orientationLock,
+      }),
+    );
+    return () => subscription.remove();
+  }, []);
+
+  return screenOrientation;
+}

package/src/react/hooks/use-screen-orientation/use-screen-orientation.test.tsx

@@ -0,0 +1,93 @@
+// Co-located React-driven test (ADR 0025) for useScreenOrientation. See network's
+// use-network-state.test.tsx for the shared rationale (mocks `core`, not expo-modules-core
+// internals).
+
+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 { useScreenOrientation } from './index';
+
+type IScreenOrientationState = { orientation: number; orientationLock: number };
+type IOrientationChangeEvent = {
+  orientationLock: number;
+  orientationInfo: { orientation: number };
+};
+
+const { addListener, getOrientationAsync, getOrientationLockAsync, remove } = vi.hoisted(() => {
+  const remove = vi.fn();
+  return {
+    addListener: vi.fn((_listener: (event: IOrientationChangeEvent) => void) => ({ remove })),
+    getOrientationAsync: vi.fn(async () => 1),
+    getOrientationLockAsync: vi.fn(async () => 0),
+    remove,
+  };
+});
+
+vi.mock('../../../core', () => ({
+  addOrientationChangeListener: addListener,
+  getOrientationAsync,
+  getOrientationLockAsync,
+  Orientation: { UNKNOWN: 0, PORTRAIT_UP: 1 },
+  OrientationLock: { UNKNOWN: 9, DEFAULT: 0 },
+}));
+
+const ROOT_TAG = 954;
+
+const results: IScreenOrientationState[] = [];
+
+function Probe(): ReactElement {
+  results.push(useScreenOrientation());
+  return createElement(View);
+}
+
+const fabric = installFabric();
+
+beforeEach(() => {
+  fabric.reset();
+  results.length = 0;
+  vi.clearAllMocks();
+  getOrientationAsync.mockResolvedValue(1);
+  getOrientationLockAsync.mockResolvedValue(0);
+});
+
+afterEach(() => unmount(ROOT_TAG));
+
+describe('useScreenOrientation', () => {
+  it('reports OrientationLock/Orientation UNKNOWN before the initial fetch resolves', () => {
+    mount(ROOT_TAG, createElement(Probe));
+
+    expect(results[results.length - 1]).toEqual({ orientation: 0, orientationLock: 9 });
+  });
+
+  it('reports the fetched state once the initial getOrientationAsync()/getOrientationLockAsync() resolve', async () => {
+    mount(ROOT_TAG, createElement(Probe));
+
+    await vi.waitFor(() =>
+      expect(results[results.length - 1]).toEqual({ orientation: 1, orientationLock: 0 }),
+    );
+  });
+
+  it('updates when the native listener fires', async () => {
+    mount(ROOT_TAG, createElement(Probe));
+    await vi.waitFor(() => expect(results[results.length - 1].orientation).toBe(1));
+
+    const listener = addListener.mock.calls[0][0];
+    listener({ orientationLock: 5, orientationInfo: { orientation: 3 } });
+
+    await vi.waitFor(() =>
+      expect(results[results.length - 1]).toEqual({
+        orientation: 3,
+        orientationLock: 5,
+      }),
+    );
+  });
+
+  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,26 @@
+// @symbiote-native/screen-orientation/react: the React entry over the framework-agnostic core.
+
+export { useScreenOrientation } from './hooks/use-screen-orientation';
+export {
+  lockAsync,
+  lockPlatformAsync,
+  unlockAsync,
+  getOrientationAsync,
+  getOrientationLockAsync,
+  getPlatformOrientationLockAsync,
+  supportsOrientationLockAsync,
+  addOrientationChangeListener,
+  removeOrientationChangeListeners,
+  removeOrientationChangeListener,
+  Orientation,
+  OrientationLock,
+  SizeClassIOS,
+  WebOrientationLock,
+  WebOrientation,
+  type PlatformOrientationInfo,
+  type ScreenOrientationInfo,
+  type OrientationChangeEvent,
+  type OrientationChangeListener,
+  type ScreenOrientationState,
+  type EventSubscription,
+} from '../core';

package/src/vue/composables/use-screen-orientation/index.ts

@@ -0,0 +1,42 @@
+// Vue lifecycle wiring over the framework-agnostic core (core/screen-orientation.ts). Seeds the
+// initial value with one-shot getOrientationAsync()/getOrientationLockAsync() calls before the
+// first native event fires, mirroring packages/network's useNetworkState.
+
+import { onMounted, onUnmounted, ref, type Ref } from '@vue/runtime-core';
+import {
+  addOrientationChangeListener,
+  getOrientationAsync,
+  getOrientationLockAsync,
+  Orientation,
+  OrientationLock,
+  type EventSubscription,
+  type ScreenOrientationState,
+} from '../../../core';
+
+export function useScreenOrientation(): Ref<ScreenOrientationState> {
+  const screenOrientation = ref<ScreenOrientationState>({
+    orientation: Orientation.UNKNOWN,
+    orientationLock: OrientationLock.UNKNOWN,
+  });
+  let subscription: EventSubscription | undefined;
+
+  onMounted(() => {
+    Promise.all([getOrientationAsync(), getOrientationLockAsync()]).then(
+      ([orientation, orientationLock]) => {
+        screenOrientation.value = { orientation, orientationLock };
+      },
+    );
+    subscription = addOrientationChangeListener(event => {
+      screenOrientation.value = {
+        orientation: event.orientationInfo.orientation,
+        orientationLock: event.orientationLock,
+      };
+    });
+  });
+
+  onUnmounted(() => {
+    subscription?.remove();
+  });
+
+  return screenOrientation;
+}

package/src/vue/composables/use-screen-orientation/use-screen-orientation.test.ts

@@ -0,0 +1,98 @@
+// Co-located Vue-driven test (ADR 0025) for useScreenOrientation. See network's
+// use-network-state.test.ts for the shared rationale.
+
+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 { useScreenOrientation } from './index';
+
+const ROOT_TAG = 9954;
+
+type IScreenOrientationState = { orientation: number; orientationLock: number };
+type IOrientationChangeEvent = {
+  orientationLock: number;
+  orientationInfo: { orientation: number };
+};
+type IListener = (event: IOrientationChangeEvent) => void;
+
+let registeredListener: IListener | undefined;
+const removeMock = vi.fn();
+const addListenerMock = vi.fn((listener: IListener) => {
+  registeredListener = listener;
+  return { remove: removeMock };
+});
+const getOrientationAsyncMock = vi.fn(async () => 1);
+const getOrientationLockAsyncMock = vi.fn(async () => 0);
+
+vi.mock('../../../core', () => ({
+  addOrientationChangeListener: (listener: IListener) => addListenerMock(listener),
+  getOrientationAsync: () => getOrientationAsyncMock(),
+  getOrientationLockAsync: () => getOrientationLockAsyncMock(),
+  Orientation: { UNKNOWN: 0, PORTRAIT_UP: 1 },
+  OrientationLock: { UNKNOWN: 9, DEFAULT: 0 },
+}));
+
+const fabric = installFabric();
+
+beforeEach(() => {
+  fabric.reset();
+  registeredListener = undefined;
+  addListenerMock.mockClear();
+  removeMock.mockClear();
+  getOrientationAsyncMock.mockClear();
+  getOrientationLockAsyncMock.mockClear();
+  getOrientationAsyncMock.mockResolvedValue(1);
+  getOrientationLockAsyncMock.mockResolvedValue(0);
+});
+
+afterEach(() => unmount(ROOT_TAG));
+
+function mountScreenOrientation(): Ref<IScreenOrientationState> {
+  let screenOrientation: Ref<IScreenOrientationState> | undefined;
+  mount(
+    ROOT_TAG,
+    defineComponent({
+      setup: () => {
+        screenOrientation = useScreenOrientation();
+        return () => h('symbiote-text', {}, 'screen-orientation');
+      },
+    }),
+  );
+  if (screenOrientation === undefined) {
+    throw new Error('setup() did not run');
+  }
+  return screenOrientation;
+}
+
+describe('useScreenOrientation (Vue)', () => {
+  it('starts at Orientation/OrientationLock UNKNOWN before the initial fetch resolves', () => {
+    const screenOrientation = mountScreenOrientation();
+
+    expect(screenOrientation.value).toEqual({ orientation: 0, orientationLock: 9 });
+  });
+
+  it('updates to the fetched value once getOrientationAsync()/getOrientationLockAsync() resolve', async () => {
+    const screenOrientation = mountScreenOrientation();
+
+    await vi.waitFor(() =>
+      expect(screenOrientation.value).toEqual({ orientation: 1, orientationLock: 0 }),
+    );
+  });
+
+  it('updates the ref when the native listener fires', async () => {
+    const screenOrientation = mountScreenOrientation();
+    await vi.waitFor(() => expect(screenOrientation.value.orientation).toBe(1));
+
+    registeredListener?.({ orientationLock: 5, orientationInfo: { orientation: 3 } });
+
+    expect(screenOrientation.value).toEqual({ orientation: 3, orientationLock: 5 });
+  });
+
+  it('removes the subscription on unmount', () => {
+    mountScreenOrientation();
+    unmount(ROOT_TAG);
+
+    expect(removeMock).toHaveBeenCalledTimes(1);
+  });
+});

package/src/vue/index.ts

@@ -0,0 +1,26 @@
+// @symbiote-native/screen-orientation/vue: the Vue entry over the framework-agnostic core.
+
+export { useScreenOrientation } from './composables/use-screen-orientation';
+export {
+  lockAsync,
+  lockPlatformAsync,
+  unlockAsync,
+  getOrientationAsync,
+  getOrientationLockAsync,
+  getPlatformOrientationLockAsync,
+  supportsOrientationLockAsync,
+  addOrientationChangeListener,
+  removeOrientationChangeListeners,
+  removeOrientationChangeListener,
+  Orientation,
+  OrientationLock,
+  SizeClassIOS,
+  WebOrientationLock,
+  WebOrientation,
+  type PlatformOrientationInfo,
+  type ScreenOrientationInfo,
+  type OrientationChangeEvent,
+  type OrientationChangeListener,
+  type ScreenOrientationState,
+  type EventSubscription,
+} from '../core';