@q9labsai/chalk-react-native 4.0.0

package/src/callkit/resolve-space-callkit-options.test.ts

@@ -0,0 +1,68 @@
+import { describe, expect, it } from "vitest";
+import { resolveSpaceCallKitOptions } from "./resolve-space-callkit-options";
+
+describe("resolveSpaceCallKitOptions", () => {
+  it("returns null when CallKit is disabled", () => {
+    expect(
+      resolveSpaceCallKitOptions({
+        callKit: false,
+        hasVideo: true,
+        spaceId: "space-123",
+        spaceName: "Design Review",
+      }),
+    ).toBeNull();
+  });
+
+  it("fills sensible defaults for enabled Spaces", () => {
+    expect(
+      resolveSpaceCallKitOptions({
+        callKit: true,
+        hasVideo: true,
+        spaceId: "space-123",
+        spaceName: "Design Review",
+      }),
+    ).toEqual({
+      appName: "Chalk",
+      displayName: "Design Review",
+      handle: "space-123",
+      handleType: "generic",
+      hasVideo: true,
+      includesCallsInRecents: false,
+      maximumCallGroups: 1,
+      maximumCallsPerCallGroup: 1,
+      iconTemplateImageName: undefined,
+      ringtoneSound: undefined,
+    });
+  });
+
+  it("prefers explicit overrides from the caller", () => {
+    expect(
+      resolveSpaceCallKitOptions({
+        callKit: {
+          appName: "Chalk Meet",
+          displayName: "Board Space",
+          handle: "board-space",
+          handleType: "emailAddress",
+          hasVideo: false,
+          includesCallsInRecents: true,
+          maximumCallGroups: 2,
+          maximumCallsPerCallGroup: 3,
+          ringtoneSound: "ring.caf",
+        },
+        hasVideo: true,
+        spaceId: "space-123",
+      }),
+    ).toEqual({
+      appName: "Chalk Meet",
+      displayName: "Board Space",
+      handle: "board-space",
+      handleType: "emailAddress",
+      hasVideo: false,
+      includesCallsInRecents: true,
+      maximumCallGroups: 2,
+      maximumCallsPerCallGroup: 3,
+      iconTemplateImageName: undefined,
+      ringtoneSound: "ring.caf",
+    });
+  });
+});

package/src/callkit/resolve-space-callkit-options.ts

@@ -0,0 +1,34 @@
+import type { CallKitCallOptions, CallKitConfiguration, CallKitHandleType } from "./callkit";
+
+export interface SpaceCallKitOptions extends CallKitConfiguration {
+  displayName?: string;
+  enabled?: boolean;
+  handle?: string;
+  handleType?: CallKitHandleType;
+  hasVideo?: boolean;
+}
+
+export interface ResolvedSpaceCallKitOptions extends CallKitConfiguration, Pick<CallKitCallOptions, "displayName" | "handle" | "handleType" | "hasVideo"> {}
+
+export function resolveSpaceCallKitOptions({ callKit, hasVideo, spaceId, spaceName }: { callKit?: SpaceCallKitOptions | boolean; hasVideo: boolean; spaceId: string; spaceName?: string }): ResolvedSpaceCallKitOptions | null {
+  if (!callKit || (typeof callKit === "object" && callKit.enabled === false)) {
+    return null;
+  }
+
+  const options = typeof callKit === "object" ? callKit : {};
+  const fallbackDisplayName = spaceName?.trim() || spaceId;
+  const fallbackHandle = spaceId;
+
+  return {
+    appName: options.appName?.trim() || "Chalk",
+    displayName: options.displayName?.trim() || fallbackDisplayName,
+    handle: options.handle?.trim() || fallbackHandle,
+    handleType: options.handleType ?? "generic",
+    hasVideo: options.hasVideo ?? hasVideo,
+    iconTemplateImageName: options.iconTemplateImageName?.trim() || undefined,
+    includesCallsInRecents: options.includesCallsInRecents ?? false,
+    maximumCallGroups: options.maximumCallGroups ?? 1,
+    maximumCallsPerCallGroup: options.maximumCallsPerCallGroup ?? 1,
+    ringtoneSound: options.ringtoneSound?.trim() || undefined,
+  };
+}

package/src/client.test.ts

@@ -0,0 +1,12 @@
+import type { GetAccess, SpaceClient } from "@q9labsai/chalk-client";
+import { expectTypeOf, test } from "vitest";
+
+import type { NativeSpaceClientOptions } from "./client";
+
+test("the native client subpath exposes the advanced-construction contract", () => {
+  expectTypeOf<NativeSpaceClientOptions>().toMatchTypeOf<{
+    readonly space: string;
+    readonly getAccess: GetAccess;
+  }>();
+  expectTypeOf<typeof import("./client").createNativeSpaceClient>().returns.toEqualTypeOf<SpaceClient>();
+});

package/src/client.ts

@@ -0,0 +1,7 @@
+/**
+ * Native implementation seam for advanced construction. The turnkey root
+ * remains `Chalk`; applications that need direct lifecycle ownership can
+ * create the React Native SpaceClient through this explicit subpath.
+ */
+export { createNativeSpaceClient } from "./space-client/create-native-space-client";
+export type { NativeSpaceClientOptions } from "./space-client/create-native-space-client";

package/src/clipboard-store.ts

@@ -0,0 +1,108 @@
+import type { ClipboardReader } from "./clipboard";
+
+export interface ClipboardAppStateSubscription {
+  remove(): void;
+}
+
+export interface ClipboardTextStoreOptions {
+  clipboard: ClipboardReader;
+  shouldReadClipboard: boolean;
+  subscribeToAppState(listener: (nextState: string) => void): ClipboardAppStateSubscription;
+}
+
+export interface ClipboardTextStore {
+  readonly clipboard: ClipboardReader;
+  readonly shouldReadClipboard: boolean;
+  getSnapshot(): string | null;
+  subscribe(listener: () => void): () => void;
+}
+
+export function createClipboardTextStore({ clipboard, shouldReadClipboard, subscribeToAppState }: ClipboardTextStoreOptions): ClipboardTextStore {
+  let snapshot: string | null = null;
+  let active = false;
+  let requestId = 0;
+  let appStateSubscription: ClipboardAppStateSubscription | null = null;
+  const listeners = new Set<() => void>();
+
+  const publish = (nextSnapshot: string | null, request: number) => {
+    if (!active || request !== requestId || nextSnapshot === snapshot) {
+      return;
+    }
+
+    snapshot = nextSnapshot;
+    for (const listener of listeners) {
+      listener();
+    }
+  };
+
+  const refresh = async () => {
+    if (!active) {
+      return;
+    }
+
+    const request = ++requestId;
+    if (!shouldReadClipboard) {
+      publish(null, request);
+      return;
+    }
+
+    try {
+      const hasString = await clipboard.hasStringAsync();
+      if (!hasString) {
+        publish(null, request);
+        return;
+      }
+
+      const nextClipboardText = await clipboard.getStringAsync();
+      publish(nextClipboardText || null, request);
+    } catch {
+      publish(null, request);
+    }
+  };
+
+  const start = () => {
+    if (active) {
+      return;
+    }
+
+    active = true;
+    void refresh();
+    if (shouldReadClipboard) {
+      appStateSubscription = subscribeToAppState((nextState) => {
+        if (nextState === "active") {
+          void refresh();
+        }
+      });
+    }
+  };
+
+  const stop = () => {
+    if (!active) {
+      return;
+    }
+
+    active = false;
+    requestId += 1;
+    appStateSubscription?.remove();
+    appStateSubscription = null;
+  };
+
+  return {
+    clipboard,
+    shouldReadClipboard,
+    getSnapshot: () => snapshot,
+    subscribe: (listener) => {
+      listeners.add(listener);
+      if (listeners.size === 1) {
+        start();
+      }
+
+      return () => {
+        listeners.delete(listener);
+        if (listeners.size === 0) {
+          stop();
+        }
+      };
+    },
+  };
+}

package/src/clipboard.test.ts

@@ -0,0 +1,79 @@
+import { describe, expect, it, vi } from "vitest";
+import { createClipboardTextStore } from "./clipboard-store";
+
+vi.mock("react-native", () => ({
+  AppState: { addEventListener: vi.fn(() => ({ remove: vi.fn() })) },
+  NativeModules: { ChalkRuntimeInfo: { isSimulator: false } },
+  Platform: { OS: "ios" },
+}));
+
+describe("clipboard invite suggestion hook", () => {
+  it("exposes the extracted clipboard suggestion hook", async () => {
+    const { useClipboardInviteSuggestion } = await import("./clipboard");
+
+    expect(typeof useClipboardInviteSuggestion).toBe("function");
+  });
+});
+
+describe("createClipboardTextStore", () => {
+  it("refreshes on subscription and active app-state events, then stops after unsubscribe", async () => {
+    let appStateListener: ((nextState: string) => void) | undefined;
+    const removeAppStateListener = vi.fn();
+    const clipboard = {
+      hasStringAsync: vi.fn().mockResolvedValue(true),
+      getStringAsync: vi.fn().mockResolvedValue("chalk invite"),
+    };
+    const store = createClipboardTextStore({
+      clipboard,
+      shouldReadClipboard: true,
+      subscribeToAppState: (listener) => {
+        appStateListener = listener;
+        return { remove: removeAppStateListener };
+      },
+    });
+    const listener = vi.fn();
+
+    const unsubscribe = store.subscribe(listener);
+    await Promise.resolve();
+    await Promise.resolve();
+
+    expect(store.getSnapshot()).toBe("chalk invite");
+    expect(listener).toHaveBeenCalledOnce();
+
+    appStateListener?.("active");
+    await Promise.resolve();
+    await Promise.resolve();
+
+    expect(clipboard.hasStringAsync).toHaveBeenCalledTimes(2);
+
+    unsubscribe();
+    expect(removeAppStateListener).toHaveBeenCalledOnce();
+    appStateListener?.("active");
+    await Promise.resolve();
+    await Promise.resolve();
+
+    expect(clipboard.hasStringAsync).toHaveBeenCalledTimes(2);
+  });
+
+  it("does not read the clipboard when the platform policy disables automatic reads", async () => {
+    const clipboard = {
+      hasStringAsync: vi.fn(),
+      getStringAsync: vi.fn(),
+    };
+    const subscribeToAppState = vi.fn();
+    const store = createClipboardTextStore({
+      clipboard,
+      shouldReadClipboard: false,
+      subscribeToAppState,
+    });
+
+    const unsubscribe = store.subscribe(vi.fn());
+    await Promise.resolve();
+
+    expect(store.getSnapshot()).toBeNull();
+    expect(clipboard.hasStringAsync).not.toHaveBeenCalled();
+    expect(subscribeToAppState).not.toHaveBeenCalled();
+
+    unsubscribe();
+  });
+});

package/src/clipboard.ts

@@ -0,0 +1,36 @@
+import { useRef, useSyncExternalStore } from "react";
+import { AppState, NativeModules, Platform } from "react-native";
+import { shouldAutoReadClipboard } from "./runtime";
+import { createClipboardTextStore, type ClipboardTextStore } from "./clipboard-store";
+
+export interface ClipboardReader {
+  hasStringAsync(): Promise<boolean>;
+  getStringAsync(): Promise<string>;
+}
+
+export interface UseClipboardInviteSuggestionOptions {
+  clipboard: ClipboardReader;
+  getSuggestion: (clipboardText: string | null | undefined, currentInput: string) => string | null;
+}
+
+export function useClipboardInviteSuggestion(currentInput: string, { clipboard, getSuggestion }: UseClipboardInviteSuggestionOptions): string | null {
+  const runtimeInfo: unknown = NativeModules.ChalkRuntimeInfo;
+  const isIosSimulator = typeof runtimeInfo === "object" && runtimeInfo !== null && "isSimulator" in runtimeInfo && runtimeInfo.isSimulator === true;
+  const shouldReadClipboard = shouldAutoReadClipboard({
+    platform: Platform.OS,
+    isSimulator: isIosSimulator,
+  });
+  const clipboardStoreRef = useRef<ClipboardTextStore | null>(null);
+  const currentStore = clipboardStoreRef.current;
+  const clipboardStore =
+    currentStore !== null && currentStore.clipboard === clipboard && currentStore.shouldReadClipboard === shouldReadClipboard
+      ? currentStore
+      : (clipboardStoreRef.current = createClipboardTextStore({
+          clipboard,
+          shouldReadClipboard,
+          subscribeToAppState: (listener) => AppState.addEventListener("change", listener),
+        }));
+  const clipboardText = useSyncExternalStore(clipboardStore.subscribe, clipboardStore.getSnapshot, clipboardStore.getSnapshot);
+
+  return getSuggestion(clipboardText, currentInput);
+}

package/src/components/Chalk.test.tsx

@@ -0,0 +1,213 @@
+// @vitest-environment happy-dom
+import type { SpaceClient, SpaceSnapshot } from "@q9labsai/chalk-client";
+import { createRequire } from "node:module";
+import { join } from "node:path";
+import type { ReactNode } from "react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+const testingLibrary = createRequire(import.meta.url)(join(process.cwd(), "../react/node_modules", "@testing-library/react")) as {
+  readonly act: (callback: () => void | Promise<void>) => void | Promise<void>;
+  readonly cleanup: () => void;
+  readonly render: (element: ReactNode) => { readonly container: HTMLElement; readonly unmount: () => void; readonly rerender: (element: ReactNode) => void };
+};
+const { act, cleanup, render } = testingLibrary;
+
+const nativeClientFactory = vi.hoisted(() => vi.fn());
+
+vi.mock("react-native", () => ({
+  StyleSheet: { create: <T,>(styles: T) => styles },
+  View: ({ children }: { readonly children?: ReactNode }) => children,
+  Text: ({ children }: { readonly children?: ReactNode }) => children,
+  Pressable: ({ children }: { readonly children?: ReactNode }) => children,
+}));
+vi.mock("../space-client/create-native-space-client", () => ({ createNativeSpaceClient: nativeClientFactory }));
+vi.mock("./SpaceView", () => ({ SpaceView: () => <div data-testid="space" /> }));
+vi.mock("./Entrance", () => ({ Entrance: () => <div data-testid="entrance" /> }));
+
+import { Chalk } from "./Chalk";
+
+afterEach(() => {
+  cleanup();
+  nativeClientFactory.mockReset();
+});
+
+describe("Chalk", () => {
+  it("fires joined and left only for the specified connection transitions", () => {
+    const client = createClient("joining");
+    const onJoined = vi.fn();
+    const onLeft = vi.fn();
+    render(<Chalk client={client.client} entrance={false} onJoined={onJoined} onLeft={onLeft} />);
+
+    act(() => client.setStatus("live"));
+    act(() => client.setStatus("reconnecting"));
+    act(() => client.setStatus("live"));
+    act(() => client.setStatus("left"));
+
+    expect(onJoined).toHaveBeenCalledTimes(1);
+    expect(onLeft).toHaveBeenCalledTimes(1);
+  });
+
+  it("does not fire joined for an already-live supplied client", () => {
+    const client = createClient("live");
+    const onJoined = vi.fn();
+    render(<Chalk client={client.client} entrance={false} onJoined={onJoined} />);
+
+    expect(onJoined).not.toHaveBeenCalled();
+  });
+
+  it("forwards canonical client events and cleans their subscriptions up", () => {
+    const client = createClient("live");
+    const handlers = new Map<string, (event: unknown) => void>();
+    const unsubscribe = vi.fn();
+    const eventClient = client.client as { on: (event: string, handler: unknown) => () => void };
+    eventClient.on = vi.fn((event, handler) => {
+      handlers.set(event, handler as (event: unknown) => void);
+      return unsubscribe;
+    });
+    const onError = vi.fn();
+    const view = render(<Chalk client={client.client} onEpisodeEnded={vi.fn()} onError={onError} onParticipantJoined={vi.fn()} onParticipantLeft={vi.fn()} onScreenShareStarted={vi.fn()} onScreenShareStopped={vi.fn()} />);
+
+    const error = { error: { code: "client.internal_error", message: "test", recoverable: true } };
+    handlers.get("error")?.(error);
+    expect(onError).toHaveBeenCalledWith(error);
+
+    view.unmount();
+    expect(unsubscribe).toHaveBeenCalledTimes(6);
+  });
+
+  it("leaves an owned client before disposing it on unmount", async () => {
+    const client = createClient("joining");
+    let resolveLeave: (() => void) | undefined;
+    client.client.leave = vi.fn(
+      () =>
+        new Promise<void>((resolve) => {
+          resolveLeave = resolve;
+        }),
+    );
+    nativeClientFactory.mockReturnValue(client.client);
+
+    const view = render(<Chalk entrance={false} getAccess={vi.fn()} space="space-1" />);
+    view.unmount();
+
+    expect(client.client.leave).toHaveBeenCalledTimes(1);
+    expect(client.client.dispose).not.toHaveBeenCalled();
+    await act(async () => resolveLeave?.());
+    expect(client.client.dispose).toHaveBeenCalledTimes(1);
+  });
+
+  it("keeps an owned SpaceClient when getAccess changes identity and uses the latest callback", async () => {
+    const client = createClient("idle");
+    const firstAccess = vi.fn(async () => ({ token: "first" }));
+    const latestAccess = vi.fn(async () => ({ token: "latest" }));
+    nativeClientFactory.mockReturnValue(client.client);
+
+    const view = render(<Chalk entrance getAccess={firstAccess} space="space-1" />);
+    view.rerender(<Chalk entrance getAccess={latestAccess} space="space-1" />);
+
+    expect(nativeClientFactory).toHaveBeenCalledTimes(1);
+    const access = nativeClientFactory.mock.calls[0]?.[0].getAccess as (input: unknown) => Promise<unknown>;
+    await expect(access({})).resolves.toEqual({ token: "latest" });
+    expect(firstAccess).not.toHaveBeenCalled();
+    expect(latestAccess).toHaveBeenCalledTimes(1);
+  });
+
+  it("omits an absent display name when joining without Entrance", async () => {
+    const client = createClient("idle");
+    render(<Chalk client={client.client} entrance={false} />);
+
+    await act(async () => undefined);
+    expect(client.client.join).toHaveBeenCalledWith({ microphone: true, camera: true });
+  });
+
+  it("retries automatic join when an owned client is replaced for a new Space", async () => {
+    const first = createClient("idle");
+    const replacement = createClient("idle");
+    nativeClientFactory.mockReturnValueOnce(first.client).mockReturnValueOnce(replacement.client);
+
+    const view = render(<Chalk entrance={false} getAccess={vi.fn()} space="space-1" />);
+    await act(async () => undefined);
+    expect(first.client.join).toHaveBeenCalledWith({ microphone: true, camera: true });
+
+    view.rerender(<Chalk entrance={false} getAccess={vi.fn()} space="space-2" />);
+    await act(async () => undefined);
+
+    expect(nativeClientFactory).toHaveBeenCalledTimes(2);
+    expect(replacement.client.join).toHaveBeenCalledWith({ microphone: true, camera: true });
+  });
+
+  it("treats a replacement client's initial failure as an Entrance failure", () => {
+    const first = createClient("live");
+    const replacement = createClient("failed");
+    nativeClientFactory.mockReturnValueOnce(first.client).mockReturnValueOnce(replacement.client);
+
+    const view = render(<Chalk entrance getAccess={vi.fn()} space="space-1" />);
+    view.rerender(<Chalk entrance getAccess={vi.fn()} space="space-2" />);
+
+    expect(view.container.querySelector('[data-testid="entrance"]')).not.toBeNull();
+  });
+
+  it("keeps the active Space visible during reconnecting and never after left", () => {
+    const client = createClient("live");
+    const view = render(<Chalk client={client.client} />);
+
+    expect(view.container.querySelector('[data-testid="space"]')).not.toBeNull();
+    act(() => client.setStatus("reconnecting"));
+    expect(view.container.querySelector('[data-testid="space"]')).not.toBeNull();
+    act(() => client.setStatus("left"));
+    expect(view.container.querySelector('[data-testid="space"]')).toBeNull();
+    expect(view.container.textContent).toContain("You have left this Space.");
+  });
+});
+
+function createClient(status: SpaceSnapshot["connection"]["status"]): { readonly client: SpaceClient; readonly setStatus: (nextStatus: SpaceSnapshot["connection"]["status"]) => void } {
+  let snapshot = createSnapshot(status);
+  const listeners = new Set<() => void>();
+  const client = {
+    getSnapshot: () => snapshot,
+    subscribe: (listener: () => void) => {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+    on: vi.fn(() => () => undefined),
+    join: vi.fn(async () => undefined),
+    leave: vi.fn(async () => undefined),
+    dispose: vi.fn(),
+    endEpisode: vi.fn(async () => undefined),
+    media: {},
+    chat: {},
+    participants: {},
+    reactions: {},
+    whiteboard: {},
+  } as unknown as SpaceClient;
+  return {
+    client,
+    setStatus(nextStatus) {
+      snapshot = { ...snapshot, connection: { ...snapshot.connection, status: nextStatus } };
+      listeners.forEach((listener) => listener());
+    },
+  };
+}
+
+function createSnapshot(status: SpaceSnapshot["connection"]["status"]): SpaceSnapshot {
+  const capabilities = [] as const;
+  return {
+    connection: { status, episode: null, lastError: null },
+    self: { participantId: null, displayName: null, role: null, capabilities, handRaised: false, can: () => false },
+    participants: { roster: [], admissionQueue: [] },
+    media: {
+      devices: { microphones: [], cameras: [], speakers: [] },
+      selection: { microphone: null, camera: null, speaker: null },
+      local: {
+        microphone: { source: "microphone", state: "disabled", track: null },
+        camera: { source: "camera", state: "disabled", track: null },
+        screen: { source: "screen", state: "disabled", track: null },
+      },
+      remote: [],
+      screenShare: { source: "screen", state: "disabled", track: null },
+      incomingRequests: [],
+    },
+    chat: { status: "idle", messages: [], pendingSends: [], readReceipts: [], unreadCount: 0, pagination: { cursor: null, hasOlder: false, historyTruncated: false }, lastError: null },
+    reactions: { active: [] },
+    whiteboard: { open: false, engine: { status: "unsubscribed", sceneId: null, revision: null, error: null } },
+  };
+}