@symbiote-native/brightness 0.0.1

package/src/core/types.ts

@@ -0,0 +1,27 @@
+// Hand-ported from .vendors/expo/packages/expo-brightness/src/Brightness.ts (sdk-57) —
+// PermissionResponse/PermissionStatus/PermissionExpiration come straight from
+// expo-modules-core (it re-exports PermissionsInterface), never the `expo` meta-package
+// upstream itself imports them from.
+import {
+  PermissionStatus,
+  type PermissionExpiration,
+  type PermissionResponse,
+} from 'expo-modules-core';
+
+export { PermissionStatus, type PermissionExpiration, type PermissionResponse };
+
+/** Enum representing the brightness mode of the device. */
+export enum BrightnessMode {
+  /** Returned when brightness mode cannot be determined. */
+  UNKNOWN = 0,
+  /** Automatic brightness mode, tracking the ambient light sensor. */
+  AUTOMATIC = 1,
+  /** Manual brightness mode, set by the user or by `setSystemBrightnessAsync`. */
+  MANUAL = 2,
+}
+
+/** Fired when the screen brightness changes, on iOS only. */
+export type BrightnessEvent = {
+  /** The current brightness value between `0` and `1`, inclusive. */
+  brightness: number;
+};

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

@@ -0,0 +1,41 @@
+// React lifecycle wiring over the framework-agnostic core (core/brightness.ts) — auto-fetches
+// the current permission status on mount, then exposes get/request as imperative callbacks.
+// Mirrors the shape @symbiote-native/cellular's own usePermissions ships in parallel, so both
+// stay byte-for-byte consistent.
+import { useCallback, useEffect, useRef, useState } from 'react';
+import {
+  getPermissionsAsync,
+  requestPermissionsAsync,
+  type PermissionResponse,
+} from '../../../core';
+
+export function usePermissions(): [
+  PermissionResponse | null,
+  () => Promise<PermissionResponse>,
+  () => Promise<PermissionResponse>,
+] {
+  const isMounted = useRef(true);
+  const [status, setStatus] = useState<PermissionResponse | null>(null);
+
+  const getPermission = useCallback(async () => {
+    const response = await getPermissionsAsync();
+    if (isMounted.current) setStatus(response);
+    return response;
+  }, []);
+
+  const requestPermission = useCallback(async () => {
+    const response = await requestPermissionsAsync();
+    if (isMounted.current) setStatus(response);
+    return response;
+  }, []);
+
+  useEffect(() => {
+    isMounted.current = true;
+    void getPermission();
+    return () => {
+      isMounted.current = false;
+    };
+  }, [getPermission]);
+
+  return [status, requestPermission, getPermission];
+}

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

@@ -0,0 +1,100 @@
+// Co-located React-driven test (ADR 0025) for usePermissions. See battery's
+// use-battery-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 { usePermissions } from './index';
+import { PermissionStatus, type PermissionResponse } from '../../../core';
+
+const { getPermissionsAsync, requestPermissionsAsync } = vi.hoisted(() => ({
+  getPermissionsAsync: vi.fn(),
+  requestPermissionsAsync: vi.fn(),
+}));
+
+// Same enum-shaped-object mock trick packages/battery/src/react/hooks/use-battery-state's test
+// uses for BatteryState — the mock factory's runtime object stands in for the real enum
+// (imported here purely for its type), so `PermissionStatus.GRANTED` still type-checks.
+vi.mock('../../../core', () => ({
+  getPermissionsAsync,
+  requestPermissionsAsync,
+  PermissionStatus: { GRANTED: 'granted', DENIED: 'denied', UNDETERMINED: 'undetermined' },
+}));
+
+const ROOT_TAG = 953;
+
+const GRANTED: PermissionResponse = {
+  status: PermissionStatus.GRANTED,
+  granted: true,
+  canAskAgain: true,
+  expires: 'never',
+};
+const DENIED: PermissionResponse = {
+  status: PermissionStatus.DENIED,
+  granted: false,
+  canAskAgain: true,
+  expires: 'never',
+};
+
+const results: (PermissionResponse | null)[] = [];
+let latestRequest: (() => Promise<PermissionResponse>) | undefined;
+let latestGet: (() => Promise<PermissionResponse>) | undefined;
+
+function Probe(): ReactElement {
+  const [status, request, get] = usePermissions();
+  results.push(status);
+  latestRequest = request;
+  latestGet = get;
+  return createElement(View);
+}
+
+const fabric = installFabric();
+
+beforeEach(() => {
+  fabric.reset();
+  results.length = 0;
+  latestRequest = undefined;
+  latestGet = undefined;
+  vi.clearAllMocks();
+  getPermissionsAsync.mockResolvedValue(GRANTED);
+  requestPermissionsAsync.mockResolvedValue(GRANTED);
+});
+
+afterEach(() => unmount(ROOT_TAG));
+
+describe('usePermissions', () => {
+  it('starts at null before the initial fetch resolves', () => {
+    mount(ROOT_TAG, createElement(Probe));
+
+    expect(results[results.length - 1]).toBe(null);
+  });
+
+  it('fetches the permission status once on mount', async () => {
+    mount(ROOT_TAG, createElement(Probe));
+
+    await vi.waitFor(() => expect(results[results.length - 1]).toEqual(GRANTED));
+    expect(getPermissionsAsync).toHaveBeenCalledTimes(1);
+  });
+
+  it('request() delegates to requestPermissionsAsync and updates the status', async () => {
+    mount(ROOT_TAG, createElement(Probe));
+    await vi.waitFor(() => expect(results[results.length - 1]).toEqual(GRANTED));
+
+    requestPermissionsAsync.mockResolvedValueOnce(DENIED);
+    await latestRequest?.();
+
+    await vi.waitFor(() => expect(results[results.length - 1]).toEqual(DENIED));
+  });
+
+  it('get() re-fetches and updates the status', async () => {
+    mount(ROOT_TAG, createElement(Probe));
+    await vi.waitFor(() => expect(results[results.length - 1]).toEqual(GRANTED));
+
+    getPermissionsAsync.mockResolvedValueOnce(DENIED);
+    await latestGet?.();
+
+    await vi.waitFor(() => expect(results[results.length - 1]).toEqual(DENIED));
+  });
+});

package/src/react/index.ts

@@ -0,0 +1,26 @@
+// @symbiote-native/brightness/react: the React entry over the framework-agnostic core. Only the
+// permission surface gets a lifecycle hook (there is per-instance state to seed and refresh);
+// every other export is a stateless async function or one-shot listener, re-exported verbatim —
+// mirrors the lifecycle-bucket naming convention of adapters/react/src/hooks.
+
+export { usePermissions } from './hooks/use-permissions';
+export {
+  isAvailableAsync,
+  getBrightnessAsync,
+  setBrightnessAsync,
+  getSystemBrightnessAsync,
+  setSystemBrightnessAsync,
+  restoreSystemBrightnessAsync,
+  isUsingSystemBrightnessAsync,
+  getSystemBrightnessModeAsync,
+  setSystemBrightnessModeAsync,
+  getPermissionsAsync,
+  requestPermissionsAsync,
+  addBrightnessListener,
+  BrightnessMode,
+  PermissionStatus,
+  type BrightnessEvent,
+  type PermissionExpiration,
+  type PermissionResponse,
+  type EventSubscription,
+} from '../core';

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

@@ -0,0 +1,36 @@
+// Vue lifecycle wiring over the framework-agnostic core (core/brightness.ts) — auto-fetches the
+// current permission status on mount (mirrors use-battery-level's onMounted/onUnmounted style,
+// but there is no ongoing subscription to tear down here, just a one-shot get), then exposes
+// get/request as imperative callbacks.
+import { onMounted, ref, type Ref } from '@vue/runtime-core';
+import {
+  getPermissionsAsync,
+  requestPermissionsAsync,
+  type PermissionResponse,
+} from '../../../core';
+
+export function usePermissions(): {
+  status: Ref<PermissionResponse | null>;
+  request: () => Promise<PermissionResponse>;
+  get: () => Promise<PermissionResponse>;
+} {
+  const status = ref<PermissionResponse | null>(null);
+
+  const get = async () => {
+    const response = await getPermissionsAsync();
+    status.value = response;
+    return response;
+  };
+
+  const request = async () => {
+    const response = await requestPermissionsAsync();
+    status.value = response;
+    return response;
+  };
+
+  onMounted(() => {
+    void get();
+  });
+
+  return { status, request, get };
+}

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

@@ -0,0 +1,99 @@
+// Co-located Vue-driven test (ADR 0025) for usePermissions. See battery's
+// use-battery-state.test.ts for the shared rationale.
+
+import { defineComponent, h } 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 { usePermissions } from './index';
+import { PermissionStatus, type PermissionResponse } from '../../../core';
+
+const { getPermissionsAsync, requestPermissionsAsync } = vi.hoisted(() => ({
+  getPermissionsAsync: vi.fn(),
+  requestPermissionsAsync: vi.fn(),
+}));
+
+// Same enum-shaped-object mock trick packages/battery/src/vue/composables/use-battery-state's
+// test uses for BatteryState.
+vi.mock('../../../core', () => ({
+  getPermissionsAsync,
+  requestPermissionsAsync,
+  PermissionStatus: { GRANTED: 'granted', DENIED: 'denied', UNDETERMINED: 'undetermined' },
+}));
+
+const GRANTED: PermissionResponse = {
+  status: PermissionStatus.GRANTED,
+  granted: true,
+  canAskAgain: true,
+  expires: 'never',
+};
+const DENIED: PermissionResponse = {
+  status: PermissionStatus.DENIED,
+  granted: false,
+  canAskAgain: true,
+  expires: 'never',
+};
+
+const ROOT_TAG = 9953;
+const fabric = installFabric();
+
+beforeEach(() => {
+  fabric.reset();
+  vi.clearAllMocks();
+  getPermissionsAsync.mockResolvedValue(GRANTED);
+  requestPermissionsAsync.mockResolvedValue(GRANTED);
+});
+
+afterEach(() => unmount(ROOT_TAG));
+
+function mountPermissions(): ReturnType<typeof usePermissions> {
+  let result: ReturnType<typeof usePermissions> | undefined;
+  mount(
+    ROOT_TAG,
+    defineComponent({
+      setup: () => {
+        result = usePermissions();
+        return () => h('symbiote-text', {}, 'brightness');
+      },
+    }),
+  );
+  if (result === undefined) {
+    throw new Error('setup() did not run');
+  }
+  return result;
+}
+
+describe('usePermissions (Vue)', () => {
+  it('starts at null before the initial fetch resolves', () => {
+    const { status } = mountPermissions();
+
+    expect(status.value).toBe(null);
+  });
+
+  it('fetches the permission status once on mount', async () => {
+    const { status } = mountPermissions();
+
+    await vi.waitFor(() => expect(status.value).toEqual(GRANTED));
+    expect(getPermissionsAsync).toHaveBeenCalledTimes(1);
+  });
+
+  it('request() delegates to requestPermissionsAsync and updates the status', async () => {
+    const { status, request } = mountPermissions();
+    await vi.waitFor(() => expect(status.value).toEqual(GRANTED));
+
+    requestPermissionsAsync.mockResolvedValueOnce(DENIED);
+    await request();
+
+    expect(status.value).toEqual(DENIED);
+  });
+
+  it('get() re-fetches and updates the status', async () => {
+    const { status, get } = mountPermissions();
+    await vi.waitFor(() => expect(status.value).toEqual(GRANTED));
+
+    getPermissionsAsync.mockResolvedValueOnce(DENIED);
+    await get();
+
+    expect(status.value).toEqual(DENIED);
+  });
+});

package/src/vue/index.ts

@@ -0,0 +1,26 @@
+// @symbiote-native/brightness/vue: the Vue entry over the framework-agnostic core. Same
+// reasoning as the React entry — only the permission surface gets a lifecycle composable, every
+// other export is a plain re-export — mirrors the lifecycle-bucket naming convention of
+// adapters/vue/src/composables (never `hooks/`, that's React's term).
+
+export { usePermissions } from './composables/use-permissions';
+export {
+  isAvailableAsync,
+  getBrightnessAsync,
+  setBrightnessAsync,
+  getSystemBrightnessAsync,
+  setSystemBrightnessAsync,
+  restoreSystemBrightnessAsync,
+  isUsingSystemBrightnessAsync,
+  getSystemBrightnessModeAsync,
+  setSystemBrightnessModeAsync,
+  getPermissionsAsync,
+  requestPermissionsAsync,
+  addBrightnessListener,
+  BrightnessMode,
+  PermissionStatus,
+  type BrightnessEvent,
+  type PermissionExpiration,
+  type PermissionResponse,
+  type EventSubscription,
+} from '../core';