react-native-control-center 0.1.0

package/src/ControlCenter.ts

@@ -0,0 +1,122 @@
+import { NativeModules, NativeEventEmitter, Platform } from 'react-native';
+import { getCachedState, setCachedState, seedCache } from './stateCache';
+
+// ─────────────────────────────────────────────────────────────────────────
+//  ControlCenter — Native Module JS wrapper
+//
+//  Swift의 RNControlCenter가 발사하는 이벤트를 받고,
+//  메서드 호출(getState/setState)을 Promise로 노출한다.
+//
+//  iOS 외 플랫폼 또는 Native Module 미설치 시 모든 메서드는 no-op.
+// ─────────────────────────────────────────────────────────────────────────
+
+const RNControlCenter = NativeModules.RNControlCenter as
+  | {
+      getState(key: string): Promise<unknown>;
+      setState(key: string, value: unknown): Promise<void>;
+      // 네이티브가 모듈 등록 시점에 동기로 넘겨주는 상수.
+      // 콜드 스타트 직후에도 첫 렌더에서 바로 쓸 수 있는 초기 상태 스냅샷.
+      initialState?: Record<string, unknown>;
+    }
+  | undefined;
+
+interface ControlActionEvent {
+  id: string;
+  deepLink?: string;
+  t: number;
+}
+
+interface ControlStateChangeEvent {
+  key: string;
+  value: unknown;
+  t: number;
+}
+
+type Unsubscribe = () => void;
+
+class ControlCenterAPI {
+  private emitter: NativeEventEmitter | null;
+
+  constructor() {
+    if (Platform.OS === 'ios' && RNControlCenter) {
+      // NativeEventEmitter는 NativeModule을 받아 startObserving/stopObserving을
+      // 자동으로 호출해 준다. addListener가 첫 등록되는 순간 Swift의
+      // startObserving이 발사되고, 마지막 listener가 제거되면 stopObserving이 발사된다.
+      this.emitter = new NativeEventEmitter(NativeModules.RNControlCenter);
+
+      // 콜드 스타트 시드 — 네이티브가 넘겨준 초기 스냅샷으로 캐시를 미리 채운다.
+      seedCache(RNControlCenter.initialState);
+
+      // 모든 ControlStateChange 이벤트를 캐시에 반영하는 내부 리스너.
+      // 키별 구독(onStateChange)과 별개로, 어떤 키가 바뀌든 캐시는 항상 최신.
+      this.emitter.addListener(
+        'ControlStateChange',
+        (event: ControlStateChangeEvent) => {
+          setCachedState(event.key, event.value);
+        }
+      );
+    } else {
+      this.emitter = null;
+    }
+  }
+
+  /**
+   * 캐시된 마지막 값을 동기로 반환. 모르면 undefined.
+   * useControlState 훅이 첫 렌더 초기값으로 사용 (깜빡임 방지).
+   */
+  getCachedState<T>(key: string): T | undefined {
+    return getCachedState<T>(key);
+  }
+
+  /** 라이브러리가 현재 환경에서 실제로 동작 가능한지 (iOS + Native Module 로드됨). */
+  isAvailable(): boolean {
+    return this.emitter !== null;
+  }
+
+  /**
+   * 사용자가 제어센터의 Button을 탭했을 때 발사되는 이벤트 구독.
+   * @returns unsubscribe 함수
+   */
+  onAction(cb: (event: ControlActionEvent) => void): Unsubscribe {
+    if (!this.emitter) return () => {};
+    const sub = this.emitter.addListener('ControlAction', cb);
+    return () => sub.remove();
+  }
+
+  /**
+   * 특정 stateKey의 값이 바뀌었을 때 발사되는 이벤트 구독.
+   * Swift는 모든 키를 하나의 이벤트로 발사하므로 여기서 키 필터링.
+   * @returns unsubscribe 함수
+   */
+  onStateChange<T>(key: string, cb: (value: T) => void): Unsubscribe {
+    if (!this.emitter) return () => {};
+    const sub = this.emitter.addListener(
+      'ControlStateChange',
+      (event: ControlStateChangeEvent) => {
+        if (event.key === key) cb(event.value as T);
+      }
+    );
+    return () => sub.remove();
+  }
+
+  /** App Group UserDefaults에서 값 읽기. iOS 외에선 null. */
+  async getState<T>(key: string): Promise<T | null> {
+    if (!RNControlCenter) return null;
+    try {
+      const value = await RNControlCenter.getState(key);
+      setCachedState(key, value); // 응답을 캐시에 반영
+      return value as T;
+    } catch {
+      return null;
+    }
+  }
+
+  /** App Group UserDefaults에 값 쓰기. iOS 외에선 no-op. */
+  async setState<T>(key: string, value: T): Promise<void> {
+    setCachedState(key, value); // optimistic — 네이티브 왕복 전에 캐시 먼저 갱신
+    if (!RNControlCenter) return;
+    await RNControlCenter.setState(key, value as unknown);
+  }
+}
+
+export const ControlCenter = new ControlCenterAPI();

package/src/defineControls.ts

@@ -0,0 +1,9 @@
+import type { Control } from './types';
+
+/**
+ * 컨트롤 선언. 이 함수는 타입 헬퍼일 뿐, 런타임에 아무 동작도 하지 않습니다.
+ * 실제 처리는 빌드 타임에 AST 파싱으로 이뤄집니다.
+ */
+export function defineControls<T extends Record<string, Control>>(controls: T): T {
+  return controls;
+}

package/src/hooks.ts

@@ -0,0 +1,42 @@
+import { useState, useEffect, useCallback } from 'react';
+import { ControlCenter } from './ControlCenter';
+
+/**
+ * App Group에 저장된 control 상태에 React 친화적 접근을 제공.
+ *
+ * Week 6: 캐시 레이어로 sync 초기값 보장.
+ * 첫 렌더에서 ControlCenter의 캐시(네이티브 initialState 시드 + 직전 값)를
+ * 동기로 읽어 깜빡임을 없앤다. 캐시에 없으면 null로 시작해 getState 응답을 기다림.
+ */
+export function useControlState<T>(key: string): [T | null, (value: T) => void] {
+  const [value, setValue] = useState<T | null>(() => {
+    const cached = ControlCenter.getCachedState<T>(key);
+    return cached !== undefined ? cached : null;
+  });
+
+  // 초기값 — native에 비동기로 물어봄 (캐시가 오래됐을 수 있으니 최신값으로 보정)
+  useEffect(() => {
+    let cancelled = false;
+    ControlCenter.getState<T>(key).then((v) => {
+      if (!cancelled) setValue(v);
+    });
+    return () => {
+      cancelled = true;
+    };
+  }, [key]);
+
+  // 변경 이벤트 구독
+  useEffect(() => {
+    return ControlCenter.onStateChange<T>(key, (newVal) => setValue(newVal));
+  }, [key]);
+
+  const setter = useCallback(
+    (newVal: T) => {
+      ControlCenter.setState(key, newVal);
+      setValue(newVal); // optimistic update — 다음 이벤트가 같은 값을 다시 보내도 무해
+    },
+    [key]
+  );
+
+  return [value, setter];
+}

package/src/index.ts

@@ -0,0 +1,12 @@
+export { defineControls } from './defineControls';
+export { ControlCenter } from './ControlCenter';
+export { useControlState } from './hooks';
+export type {
+  ButtonControl,
+  ToggleControl,
+  Control,
+  SFSymbolName,
+  StrictSFSymbolName,
+  HexColor,
+} from './types';
+export type { KnownSFSymbol } from './sf-symbols';

package/src/sf-symbols.ts

@@ -0,0 +1,251 @@
+/**
+ * 자주 쓰이는 SF Symbols 큐레이션 리스트.
+ * 자동완성용 — 실제 타입은 string도 허용합니다.
+ *
+ * 전체 5000+ 심볼은 https://developer.apple.com/sf-symbols/ 참조.
+ * Xcode → SF Symbols.app 에서 원하는 심볼 이름 검색 가능.
+ */
+export type KnownSFSymbol =
+  // Actions
+  | 'square.and.pencil'
+  | 'pencil'
+  | 'pencil.circle'
+  | 'pencil.circle.fill'
+  | 'plus'
+  | 'plus.circle'
+  | 'plus.circle.fill'
+  | 'minus'
+  | 'minus.circle'
+  | 'minus.circle.fill'
+  | 'xmark'
+  | 'xmark.circle'
+  | 'xmark.circle.fill'
+  | 'checkmark'
+  | 'checkmark.circle'
+  | 'checkmark.circle.fill'
+  | 'trash'
+  | 'trash.fill'
+  // Navigation
+  | 'chevron.left'
+  | 'chevron.right'
+  | 'chevron.up'
+  | 'chevron.down'
+  | 'arrow.left'
+  | 'arrow.right'
+  | 'arrow.up'
+  | 'arrow.down'
+  | 'arrow.clockwise'
+  | 'arrow.counterclockwise'
+  // Sharing & Communication
+  | 'square.and.arrow.up'
+  | 'square.and.arrow.down'
+  | 'paperplane'
+  | 'paperplane.fill'
+  | 'envelope'
+  | 'envelope.fill'
+  | 'bubble.left'
+  | 'bubble.right'
+  | 'phone'
+  | 'phone.fill'
+  // Media
+  | 'play'
+  | 'play.fill'
+  | 'play.circle'
+  | 'play.circle.fill'
+  | 'pause'
+  | 'pause.fill'
+  | 'pause.circle'
+  | 'pause.circle.fill'
+  | 'stop'
+  | 'stop.fill'
+  | 'forward'
+  | 'forward.fill'
+  | 'backward'
+  | 'backward.fill'
+  | 'speaker'
+  | 'speaker.fill'
+  | 'speaker.slash'
+  | 'speaker.slash.fill'
+  | 'mic'
+  | 'mic.fill'
+  | 'mic.slash'
+  // System
+  | 'gear'
+  | 'gearshape'
+  | 'gearshape.fill'
+  | 'power'
+  | 'bolt'
+  | 'bolt.fill'
+  | 'bolt.slash'
+  | 'bolt.slash.fill'
+  | 'battery.100'
+  | 'battery.75'
+  | 'battery.50'
+  | 'battery.25'
+  | 'battery.0'
+  // Privacy & Security
+  | 'lock'
+  | 'lock.fill'
+  | 'lock.open'
+  | 'lock.open.fill'
+  | 'lock.shield'
+  | 'lock.shield.fill'
+  | 'key'
+  | 'key.fill'
+  | 'shield'
+  | 'shield.fill'
+  | 'shield.slash'
+  | 'eye'
+  | 'eye.fill'
+  | 'eye.slash'
+  | 'eye.slash.fill'
+  // User & Social
+  | 'person'
+  | 'person.fill'
+  | 'person.circle'
+  | 'person.circle.fill'
+  | 'person.2'
+  | 'person.2.fill'
+  | 'person.3'
+  | 'person.crop.circle'
+  | 'person.crop.circle.fill'
+  // Content
+  | 'doc'
+  | 'doc.fill'
+  | 'doc.text'
+  | 'doc.text.fill'
+  | 'note'
+  | 'note.text'
+  | 'folder'
+  | 'folder.fill'
+  | 'book'
+  | 'book.fill'
+  | 'bookmark'
+  | 'bookmark.fill'
+  | 'tag'
+  | 'tag.fill'
+  // Status
+  | 'heart'
+  | 'heart.fill'
+  | 'heart.slash'
+  | 'star'
+  | 'star.fill'
+  | 'star.slash'
+  | 'flag'
+  | 'flag.fill'
+  | 'flag.slash'
+  | 'bell'
+  | 'bell.fill'
+  | 'bell.slash'
+  | 'bell.slash.fill'
+  // Connectivity
+  | 'wifi'
+  | 'wifi.slash'
+  | 'antenna.radiowaves.left.and.right'
+  | 'airplane'
+  | 'airplayaudio'
+  | 'airplayvideo'
+  | 'network'
+  | 'globe'
+  // Location & Maps
+  | 'location'
+  | 'location.fill'
+  | 'location.slash'
+  | 'mappin'
+  | 'mappin.circle.fill'
+  | 'map'
+  | 'map.fill'
+  | 'house'
+  | 'house.fill'
+  | 'building'
+  | 'building.2'
+  // Time
+  | 'clock'
+  | 'clock.fill'
+  | 'alarm'
+  | 'alarm.fill'
+  | 'timer'
+  | 'stopwatch'
+  | 'stopwatch.fill'
+  | 'calendar'
+  | 'calendar.badge.plus'
+  | 'calendar.badge.clock'
+  // Camera & Photo
+  | 'camera'
+  | 'camera.fill'
+  | 'camera.circle'
+  | 'camera.circle.fill'
+  | 'photo'
+  | 'photo.fill'
+  | 'photo.on.rectangle'
+  | 'video'
+  | 'video.fill'
+  | 'video.slash'
+  // Payment & Shopping
+  | 'creditcard'
+  | 'creditcard.fill'
+  | 'cart'
+  | 'cart.fill'
+  | 'bag'
+  | 'bag.fill'
+  | 'dollarsign.circle'
+  | 'dollarsign.circle.fill'
+  // Search & Info
+  | 'magnifyingglass'
+  | 'magnifyingglass.circle'
+  | 'info'
+  | 'info.circle'
+  | 'info.circle.fill'
+  | 'questionmark'
+  | 'questionmark.circle'
+  | 'questionmark.circle.fill'
+  | 'exclamationmark'
+  | 'exclamationmark.circle'
+  | 'exclamationmark.triangle'
+  | 'exclamationmark.triangle.fill'
+  // Health & Fitness
+  | 'heart.text.square'
+  | 'figure.walk'
+  | 'figure.run'
+  | 'figure.stand'
+  | 'flame'
+  | 'flame.fill'
+  | 'drop'
+  | 'drop.fill'
+  | 'leaf'
+  | 'leaf.fill'
+  // Weather
+  | 'sun.max'
+  | 'sun.max.fill'
+  | 'moon'
+  | 'moon.fill'
+  | 'moon.stars'
+  | 'moon.stars.fill'
+  | 'cloud'
+  | 'cloud.fill'
+  | 'cloud.rain'
+  | 'cloud.rain.fill'
+  | 'snowflake'
+  // Home & Devices
+  | 'tv'
+  | 'tv.fill'
+  | 'lightbulb'
+  | 'lightbulb.fill'
+  | 'lightbulb.slash'
+  | 'thermometer'
+  | 'fan'
+  | 'air.conditioner.horizontal'
+  // Layouts
+  | 'rectangle.stack'
+  | 'square.stack'
+  | 'square.grid.2x2'
+  | 'square.grid.3x3'
+  | 'list.bullet'
+  | 'list.dash'
+  // Misc
+  | 'ellipsis'
+  | 'ellipsis.circle'
+  | 'line.3.horizontal'
+  | 'line.3.horizontal.decrease'
+  | 'slider.horizontal.3'
+  | 'arrow.up.arrow.down';

package/src/stateCache.ts

@@ -0,0 +1,34 @@
+// ─────────────────────────────────────────────────────────────────────────
+//  stateCache — control 상태의 동기 보관함 (Week 6)
+//
+//  getState는 Promise라 값이 "다음 tick"에 도착한다. 그 사이 UI가 null로
+//  깜빡이는 걸 막기 위해, 마지막으로 알던 값을 모듈 레벨 Map에 둔다.
+//  useControlState 훅이 첫 렌더에서 이 캐시를 동기로 읽어 바로 표시한다.
+//
+//  react-native에 의존하지 않는 순수 모듈 — 그래서 node 환경에서 단독 테스트 가능.
+// ─────────────────────────────────────────────────────────────────────────
+
+const cache = new Map<string, unknown>();
+
+/** 캐시된 마지막 값을 동기로 반환. 한 번도 본 적 없으면 undefined. */
+export function getCachedState<T>(key: string): T | undefined {
+  return cache.has(key) ? (cache.get(key) as T) : undefined;
+}
+
+/** 새 값을 캐시에 기록 (getState 응답 / setState / onStateChange 이벤트에서 호출). */
+export function setCachedState(key: string, value: unknown): void {
+  cache.set(key, value);
+}
+
+/** 네이티브 initialState 스냅샷으로 캐시를 한 번에 채움 (콜드 스타트 시드). */
+export function seedCache(initial: Record<string, unknown> | undefined): void {
+  if (!initial) return;
+  for (const key of Object.keys(initial)) {
+    cache.set(key, initial[key]);
+  }
+}
+
+/** 테스트 전용 — 캐시를 비운다. */
+export function __resetCacheForTests(): void {
+  cache.clear();
+}

package/src/types.ts

@@ -0,0 +1,36 @@
+import type { KnownSFSymbol } from './sf-symbols';
+
+export type HexColor = `#${string}`;
+
+/**
+ * 유연 모드: 큐레이션된 ~200개는 자동완성 + 그 외 문자열도 허용.
+ * TypeScript 트릭: `(string & {})` 는 자동완성을 비활성화하지 않으면서
+ * 임의 문자열을 받게 해줌.
+ */
+export type SFSymbolName = KnownSFSymbol | (string & {});
+
+/**
+ * 엄격 모드: 큐레이션 리스트에 있는 심볼만 허용.
+ * 오타/잘못된 이름 방지가 중요할 때 사용.
+ */
+export type StrictSFSymbolName = KnownSFSymbol;
+
+export interface ButtonControl {
+  type: 'button';
+  title: string;
+  icon: SFSymbolName;
+  tint?: HexColor;
+  description?: string;
+  deepLink?: string;
+}
+
+export interface ToggleControl {
+  type: 'toggle';
+  title: string;
+  icons: { on: SFSymbolName; off: SFSymbolName };
+  tint?: { on: HexColor; off: HexColor };
+  stateKey: string;
+  description?: string;
+}
+
+export type Control = ButtonControl | ToggleControl;