@oxyhq/services 22.9.0 → 22.10.0

package/src/ui/hooks/useSurfaceHeader.ts

@@ -0,0 +1,56 @@
+import { createContext, useContext, useLayoutEffect } from 'react';
+import type { DialogHeaderConfig } from '@oxyhq/bloom/dialog';
+
+/**
+ * The header content a mounted surface screen contributes at runtime: its
+ * (translated) title/subtitle and optional slot nodes. Back/close affordances
+ * are owned by the surface host (`SurfaceScreen`) — a screen never wires them.
+ *
+ * A `right` slot is the canonical place for a screen-state action (e.g. a Save
+ * button whose disabled/loading state reflects the form). Slot nodes MUST be
+ * referentially stable (memoize them with `useMemo`) so the header does not
+ * thrash.
+ */
+export type SurfaceHeaderContent = Pick<
+  DialogHeaderConfig,
+  'title' | 'subtitle' | 'largeTitle' | 'left' | 'right' | 'onBack'
+>;
+
+interface SurfaceHeaderContextValue {
+  setContent: (content: SurfaceHeaderContent | null) => void;
+}
+
+/**
+ * Provided by {@link ../components/SurfaceScreen}. Bridges a screen's runtime
+ * header contribution up to the host, which merges it with the back/close
+ * wiring and drives the Dialog's own nav header. `null` outside a surface (or in
+ * a headerless surface), so {@link useSurfaceHeader} is a safe no-op there.
+ */
+export const SurfaceHeaderContext = createContext<SurfaceHeaderContextValue | null>(null);
+
+/**
+ * Declare the Dialog nav header's content from within a surface screen — its
+ * title/subtitle and any action slot. Merges over nothing (the host owns
+ * back/close), replaces on change, and clears on unmount. Call it unconditionally;
+ * it is a no-op outside a header-mode surface.
+ */
+export function useSurfaceHeader(content: SurfaceHeaderContent | null | undefined): void {
+  const ctx = useContext(SurfaceHeaderContext);
+  const set = ctx?.setContent;
+  // Set synchronously in the commit's layout phase so the bar/title fill in
+  // BEFORE the browser paints — no first-frame flash of an empty bar.
+  useLayoutEffect(() => {
+    if (!set) return;
+    set(content ?? null);
+    return () => set(null);
+    // Slot nodes (`left`/`right`) are compared by identity; callers memoize them.
+  }, [
+    set,
+    content?.title,
+    content?.subtitle,
+    content?.largeTitle,
+    content?.left,
+    content?.right,
+    content?.onBack,
+  ]);
+}

package/src/ui/hooks/useSwitchableAccounts.ts

@@ -32,7 +32,7 @@ const EMPTY_SNAPSHOT: AccountDialogSnapshot = {
  * real per-account name / email / avatar / color.
  *
  * This is a thin binding over the shared `AccountDialogController` in
- * `@oxyhq/core` (the SAME headless source the {@link OxyAccountDialog} renders),
+ * `@oxyhq/core` (the SAME headless source the {@link OxyAccountDialogScreen} renders),
  * so there is ONE projection (`projectSwitchableAccounts`) and one switch path
  * (`controller.switchTo`) across the whole SDK — the local duplicate projection
  * this hook used to own has been removed. Every switch routes through

package/src/ui/navigation/__tests__/surfaceNavStack.test.ts

@@ -0,0 +1,68 @@
+import { createSurfaceNavStack } from '../surfaceNavStack';
+import { __resetSurfaceBackBridgeForTests, pushSurfaceBackHandler, __invokeTopSurfaceBackForTests } from '../surfaceBackBridge';
+
+describe('createSurfaceNavStack', () => {
+  it('starts with a single root frame', () => {
+    const stack = createSurfaceNavStack('ManageAccount', { foo: 1 });
+    expect(stack.getTop().route).toBe('ManageAccount');
+    expect(stack.getTop().props).toEqual({ foo: 1 });
+    expect(stack.canGoBack()).toBe(false);
+  });
+
+  it('navigate pushes frames and goBack pops them', () => {
+    const stack = createSurfaceNavStack('ManageAccount');
+    stack.navigate('EditProfile', { userId: 'u1' });
+    expect(stack.getTop().route).toBe('EditProfile');
+    expect(stack.canGoBack()).toBe(true);
+    expect(stack.goBack()).toBe(true);
+    expect(stack.getTop().route).toBe('ManageAccount');
+    expect(stack.goBack()).toBe(false);
+  });
+
+  it('replace swaps the top frame without growing history', () => {
+    const stack = createSurfaceNavStack('ManageAccount');
+    stack.navigate('EditProfile');
+    stack.replace('PrivacySettings');
+    expect(stack.getTop().route).toBe('PrivacySettings');
+    expect(stack.goBack()).toBe(true);
+    expect(stack.getTop().route).toBe('ManageAccount');
+  });
+
+  it('tracks wizard steps on the current frame', () => {
+    const stack = createSurfaceNavStack('EditProfile', { initialStep: 2 });
+    expect(stack.getTop().step).toBe(2);
+    expect(stack.canGoBack()).toBe(true);
+    stack.setStep(1);
+    expect(stack.getTop().step).toBe(1);
+  });
+
+  it('requestDismiss flips closing once', () => {
+    const stack = createSurfaceNavStack('ManageAccount');
+    stack.requestDismiss('done');
+    expect(stack.store.getState().closing).toBe(true);
+    expect(stack.store.getState().closeResult).toBe('done');
+    stack.requestDismiss('again');
+    expect(stack.store.getState().closeResult).toBe('done');
+  });
+});
+
+describe('pushSurfaceBackHandler', () => {
+  afterEach(() => {
+    __resetSurfaceBackBridgeForTests();
+  });
+
+  it('delegates to the topmost handler', () => {
+    const calls: string[] = [];
+    pushSurfaceBackHandler(() => {
+      calls.push('bottom');
+      return true;
+    });
+    pushSurfaceBackHandler(() => {
+      calls.push('top');
+      return true;
+    });
+
+    expect(__invokeTopSurfaceBackForTests()).toBe(true);
+    expect(calls).toEqual(['top']);
+  });
+});

package/src/ui/navigation/accountDialogManager.ts

@@ -1,10 +1,22 @@
 /**
- * Imperative controls for the unified {@link OxyAccountDialog}.
+ * Imperative, outside-React entry points for the unified `OxyAccountDialogScreen`.
+ *
+ * These delegate to the live handles the mounted `OxyProvider` registers via
+ * {@link registerAccountDialogControls}. Under the hood `open`/`close` present
+ * and dismiss the `AccountDialog` surface on the shared Bloom surface stack
+ * (`OxyContext.openAccountDialog` → `presentDetached('AccountDialog', …)`), so
+ * whether the dialog is open is owned by that stack — this module is only the
+ * thin bridge that reaches the provider's controller (which sets the dialog
+ * view) from a non-React call site.
  */
 
 import type { AccountDialogView } from '@oxyhq/core';
 
-/** Live open/close handles registered by the mounted provider. */
+/**
+ * Live open/close handles registered by the mounted provider. `open` presents
+ * the `AccountDialog` surface (and points its view); `close` dismisses it. Both
+ * are stack operations — this interface never carries visibility state.
+ */
 export interface AccountDialogControls {
   open: (view?: AccountDialogView) => void;
   close: () => void;

package/src/ui/navigation/routes.ts

@@ -43,7 +43,7 @@ export type RouteName =
     | 'Notifications' // Per-channel notification preferences
     | 'ConnectedApps' // OAuth-authorized third-party apps the user can revoke
     | 'Preferences' // General user preferences (theme, reduce-motion, etc.)
-    | 'AccountDialog'; // Unified account switcher + sign-in surface (folded OxyAccountDialog body)
+    | 'AccountDialog'; // Unified account switcher + sign-in surface (OxyAccountDialogScreen body)
 
 // Lazy screen loaders - functions that return screen components on-demand
 // This breaks the require cycle by deferring imports until screens are actually needed
@@ -88,9 +88,9 @@ const screenLoaders: Record<RouteName, () => ComponentType<BaseScreenProps>> = {
     ConnectedApps: () => require('../screens/ConnectedAppsScreen').default,
     Preferences: () => require('../screens/PreferencesScreen').default,
     // Unified account switcher + sign-in surface. Its body lives in the
-    // `OxyAccountDialog` component (folded from the standalone dialog); the
+    // `OxyAccountDialogScreen` component (folded from the standalone dialog); the
     // surface stack provides the Dialog chrome around it.
-    AccountDialog: () => require('../components/OxyAccountDialog').default,
+    AccountDialog: () => require('../components/OxyAccountDialogScreen').default,
 };
 
 // Cache loaded components to avoid re-requiring

package/src/ui/navigation/surfaceBackBridge.ts

@@ -0,0 +1,69 @@
+import { BackHandler, Platform } from 'react-native';
+
+/**
+ * Per-surface system-back handlers (Android hardware back + web Escape).
+ *
+ * Bloom's `SurfaceHost` dismisses the whole top surface on back/Escape. The SDK
+ * needs the old `BottomSheetRouter` semantics first: pop nav history, step a
+ * wizard back, then dismiss. A single global listener delegates to the topmost
+ * registered handler so stacked surfaces route correctly.
+ */
+
+export type SurfaceBackHandler = () => boolean;
+
+const handlerStack: SurfaceBackHandler[] = [];
+let androidInstalled = false;
+let escapeInstalled = false;
+
+function invokeTopHandler(): boolean {
+  const handler = handlerStack[handlerStack.length - 1];
+  return handler ? handler() : false;
+}
+
+function installAndroidHandler(): void {
+  if (androidInstalled || Platform.OS !== 'android') return;
+  androidInstalled = true;
+  BackHandler.addEventListener('hardwareBackPress', () => {
+    if (handlerStack.length === 0) return false;
+    return invokeTopHandler();
+  });
+}
+
+function installEscapeHandler(): void {
+  if (escapeInstalled || Platform.OS !== 'web') return;
+  if (typeof window === 'undefined') return;
+  escapeInstalled = true;
+  window.addEventListener(
+    'keydown',
+    (event) => {
+      if (event.key !== 'Escape' || handlerStack.length === 0) return;
+      invokeTopHandler();
+      event.stopImmediatePropagation();
+      event.preventDefault();
+    },
+    true,
+  );
+}
+
+/** Register before Bloom's `SurfaceHost` mounts so Escape capture runs first. */
+installEscapeHandler();
+
+/** Push a handler for one live surface; returns unregister. */
+export function pushSurfaceBackHandler(handler: SurfaceBackHandler): () => void {
+  handlerStack.push(handler);
+  installAndroidHandler();
+  return () => {
+    const index = handlerStack.lastIndexOf(handler);
+    if (index >= 0) handlerStack.splice(index, 1);
+  };
+}
+
+/** Test-only: invoke the top handler. */
+export function __invokeTopSurfaceBackForTests(): boolean {
+  return invokeTopHandler();
+}
+
+/** Test-only reset. */
+export function __resetSurfaceBackBridgeForTests(): void {
+  handlerStack.length = 0;
+}

package/src/ui/navigation/surfaceRegistry.ts

@@ -1,6 +1,7 @@
 import type { ReactNode } from 'react';
-import type { AccountDialogView } from '@oxyhq/core';
+import type { AccountDialogView, FileMetadata } from '@oxyhq/core';
 import type { RouteName } from './routes';
+import type { AvatarCropResult } from '../screens/AvatarCropScreen';
 
 /**
  * The SDK's typed surface registry — the contract layer the SDK stacks on top of
@@ -28,7 +29,13 @@ export interface SurfaceRegistry {
   LanguageSelector: SurfaceRoute;
   PrivacySettings: SurfaceRoute;
   SearchSettings: SurfaceRoute;
-  FileManagement: SurfaceRoute;
+  /**
+   * File picker / manager. In single-select picker mode the surface is
+   * dismissed with the picked {@link FileMetadata} (the avatar-picker promise
+   * flow); legacy callers that pass an `onSelect`/`onConfirmSelection` callback
+   * keep their callback behaviour and this result goes unread.
+   */
+  FileManagement: SurfaceRoute<Record<string, unknown>, FileMetadata>;
   HelpSupport: SurfaceRoute;
   FAQ: SurfaceRoute;
   Feedback: SurfaceRoute;
@@ -53,11 +60,12 @@ export interface SurfaceRegistry {
   CreateAccount: SurfaceRoute;
   AccountMembers: SurfaceRoute;
   AccountSettings: SurfaceRoute;
-  AvatarCrop: SurfaceRoute;
+  /** Square-crop editor. Dismissed with the cropped {@link AvatarCropResult}. */
+  AvatarCrop: SurfaceRoute<Record<string, unknown>, AvatarCropResult>;
   Notifications: SurfaceRoute;
   ConnectedApps: SurfaceRoute;
   Preferences: SurfaceRoute;
-  /** Unified account switcher + sign-in surface (folded `OxyAccountDialog` body). */
+  /** Unified account switcher + sign-in surface (folded `OxyAccountDialogScreen` body). */
   AccountDialog: SurfaceRoute<{ initialView?: AccountDialogView }>;
 }
 
@@ -99,22 +107,31 @@ export type SurfacePresentation = 'sheet' | 'center' | 'drawer' | 'fullScreen';
  * Per-route surface configuration. Merges the historical `SheetRouteConfig`
  * knobs with the new {@link SurfacePresentation}.
  *
- * NOTE: `scrollable` / `manualActivation` / `dynamicBackdrop` / `handleComponent`
- * describe the in-tree bottom-sheet's pan + scroll behaviour. On Bloom's `Dialog`
- * surface those concerns are now owned by the shared `DialogBottomSheet` (it opts
- * pure custom children OUT of its internal ScrollView and manages the pan itself),
- * so for P1 these fields are informational — reserved for a future Bloom
- * bottom-placement passthrough. `presentation` (+ `scrollable` for the picker's
- * flush layout) is what actually drives the surface today.
+ * NOTE: `scrollable` is LIVE — it is threaded through `bloomOptionsFor` onto the
+ * Bloom `Dialog` surface (`scrollable` prop), so a route that owns its own scroll
+ * container opts OUT of the Dialog's internal ScrollView. `manualActivation` /
+ * `dynamicBackdrop` / `handleComponent` remain informational — reserved for a
+ * future Bloom bottom-placement passthrough; the shared `DialogBottomSheet`
+ * currently owns pan coordination itself.
  */
 export interface SurfaceRouteConfig {
   /** Which surface hosts the route. */
   presentation: SurfacePresentation;
   /**
    * When `false`, the route owns its own scroll container (a FlatList /
-   * SectionList / VirtualizedList) and the host must not wrap it in a ScrollView.
+   * SectionList / VirtualizedList, or its own ScrollView) and the host must not
+   * wrap it in a ScrollView. Threaded onto Bloom's `Dialog` via `bloomOptionsFor`.
    */
   scrollable: boolean;
+  /**
+   * Whether the surface renders the Dialog's OWN navigation header (sticky
+   * gradient nav bar + large collapsing title over the surface's scroll content).
+   * `true` for every route screen — screens render NO header of their own and
+   * declare their title/subtitle (+ any action slot) via `useSurfaceHeader`.
+   * `false` for surfaces with their own chrome (the account dialog, the flagship
+   * full-bleed image picker).
+   */
+  header: boolean;
   /** Body-pan activation strategy — reserved (owned by Bloom's Dialog surface). */
   manualActivation: boolean;
   /** Drag-proportional backdrop dim — reserved (owned by Bloom's Dialog surface). */
@@ -127,10 +144,30 @@ export interface SurfaceRouteConfig {
 const DEFAULT_SURFACE_CONFIG: SurfaceRouteConfig = {
   presentation: 'sheet',
   scrollable: true,
+  header: true,
   manualActivation: true,
   dynamicBackdrop: true,
 };
 
+/**
+ * Routes that render NO Dialog nav header — they own their chrome:
+ * - `AvatarCrop` — its own translucent Cancel / title / Done top bar.
+ * - `PaymentGateway` — the payment surface owns its controls.
+ * - `WelcomeNewUser` — a full-bleed onboarding wizard with its own step chrome.
+ * - `Profile` — a full profile view, no nav-header chrome.
+ * (The flagship full-bleed image picker is handled separately below.)
+ *
+ * `AccountDialog` used to be here — it now uses the SHARED Dialog nav header like
+ * every other screen (its per-view title/subtitle + view-back go through
+ * `useSurfaceHeader`), so the account/sign-in surface no longer feels bespoke.
+ */
+const HEADERLESS_ROUTES: ReadonlySet<RouteName> = new Set<RouteName>([
+  'AvatarCrop',
+  'PaymentGateway',
+  'WelcomeNewUser',
+  'Profile',
+]);
+
 /**
  * Predicate matching `FileManagementScreen`'s internal `isImageOnlyPicker`
  * derivation. When the consumer restricts to image MIME types (no videos, no
@@ -152,17 +189,46 @@ const isFileManagementImageOnlyPicker = (props: Record<string, unknown>): boolea
   return blocksVideos && blocksAudio && blocksDocs;
 };
 
+/**
+ * Routes whose screen owns its OWN scroll container — a FlatList /
+ * VirtualizedList (`ConnectedApps`, `TrustLeaderboard`, `FollowersList` /
+ * `FollowingList` via `UserListScreen`) or its own vertical `ScrollView`
+ * (`FileManagement`). These MUST opt out of the Dialog's internal ScrollView
+ * (`scrollable: false`) so there is exactly ONE scroll container — otherwise a
+ * VirtualizedList nests inside a plain ScrollView (RN warning) or a nested
+ * vertical scroll-in-scroll breaks windowing. Screens with only a HORIZONTAL
+ * ScrollView (FAQ's category row, Premium's plan carousel) are NOT listed — a
+ * horizontal scroller does not conflict with the Dialog's vertical scroll.
+ */
+const OWN_SCROLL_CONTAINER_ROUTES: ReadonlySet<RouteName> = new Set<RouteName>([
+  'FileManagement',
+  'ConnectedApps',
+  'TrustLeaderboard',
+  'FollowersList',
+  'FollowingList',
+]);
+
 /**
  * Resolve the surface configuration for a route + props. Defaults to the
  * responsive sheet; the image-only FileManagement picker upgrades to a full-bleed
- * `'fullScreen'` surface that owns its own scrolling.
+ * `'fullScreen'` surface, and every route that owns its own scroll container is
+ * marked `scrollable: false`.
  */
 export const getSurfaceConfig = (
   route: RouteName,
   props: Record<string, unknown>,
 ): SurfaceRouteConfig => {
   if (route === 'FileManagement' && isFileManagementImageOnlyPicker(props)) {
-    return { ...DEFAULT_SURFACE_CONFIG, presentation: 'fullScreen', scrollable: false };
+    // The full-bleed image picker owns its own translucent top bar — no nav header.
+    return { ...DEFAULT_SURFACE_CONFIG, presentation: 'fullScreen', scrollable: false, header: false };
+  }
+  if (HEADERLESS_ROUTES.has(route)) {
+    return { ...DEFAULT_SURFACE_CONFIG, header: false };
+  }
+  if (OWN_SCROLL_CONTAINER_ROUTES.has(route)) {
+    // Own-scroller list screens keep the nav header (static, non-collapsing —
+    // there is no Dialog scroll offset to drive the large-title collapse).
+    return { ...DEFAULT_SURFACE_CONFIG, scrollable: false };
   }
   return DEFAULT_SURFACE_CONFIG;
 };

package/src/ui/navigation/surfaces.ts

@@ -36,13 +36,31 @@ const SHEET_PLACEMENT = { base: 'bottom', md: 'center' } as const;
 /** Full-bleed black canvas for the `'fullScreen'` approximation (image picker). */
 const FULLSCREEN_SURFACE_STYLE: ViewStyle = { backgroundColor: '#000000', overflow: 'hidden' };
 
+/**
+ * Every SDK screen owns its own background + content padding + scroll region
+ * (they were authored for the bare `BottomSheet`). So the shared `Dialog` must
+ * NOT add its own `contentPadding` on top (that double-pads) — it owns only the
+ * structural chrome: the surface card, the size cap (`maxHeightRatio`) and the
+ * scroll boundary. `contentPadding: 0` makes the screen's own padding the single
+ * source, matching the image-picker (`fullScreen`) surface.
+ */
+const SDK_SURFACE_CHROME = { contentPadding: 0, maxHeightRatio: 0.9 } as const;
+
 /** Map a route's presentation taxonomy onto concrete Bloom `Dialog` options. */
 function bloomOptionsFor(config: SurfaceRouteConfig): PresentOptions {
+  // Threaded onto every placement so a route that owns its own scroll container
+  // (`scrollable: false`) opts out of the Dialog's internal ScrollView.
+  const scrollable = config.scrollable;
+  // Nav-header mode marker: turns on the Dialog's OWN sticky gradient nav bar +
+  // large collapsing title over its scroll content. The title/subtitle/action
+  // slots are contributed at runtime by the mounted screen via `useSurfaceHeader`
+  // (resolved in `SurfaceScreen`), so the seed here just enables the scaffold.
+  const header = config.header ? { largeTitle: true } : undefined;
   switch (config.presentation) {
     case 'center':
-      return { placement: 'center' };
+      return { placement: 'center', scrollable, header, ...SDK_SURFACE_CHROME };
     case 'drawer':
-      return { placement: { base: 'bottom', md: 'left' } };
+      return { placement: { base: 'bottom', md: 'left' }, scrollable, header, ...SDK_SURFACE_CHROME };
     case 'fullScreen':
       // Approximate a full-screen surface with the shared `Dialog`: a tall
       // sheet / large centered card, flush content, a black canvas and
@@ -53,11 +71,12 @@ function bloomOptionsFor(config: SurfaceRouteConfig): PresentOptions {
         maxWidth: 640,
         maxHeightRatio: 0.9,
         dismissOnBackdrop: false,
+        scrollable,
         style: FULLSCREEN_SURFACE_STYLE,
         panelStyle: FULLSCREEN_SURFACE_STYLE,
       };
     default:
-      return { placement: SHEET_PLACEMENT };
+      return { placement: SHEET_PLACEMENT, scrollable, header, ...SDK_SURFACE_CHROME };
   }
 }
 
@@ -111,14 +130,23 @@ function presentInternal<K extends RouteName>(
   const bloomOpts: PresentOptions = { label: route, ...bloomOptionsFor(config), ...opts };
 
   const result = bloomSurfaces.present<SurfaceResult<K>>((surface: SurfaceControls) =>
-    createElement(SurfaceScreen, { navStack, surface, presentation: config.presentation }),
+    createElement(SurfaceScreen, {
+      navStack,
+      surface,
+      presentation: config.presentation,
+      dismissOnBackdrop: bloomOpts.dismissOnBackdrop ?? true,
+    }),
     bloomOpts,
   );
 
   const instance: SurfaceInstance<K> = {
     route,
     presentation: config.presentation,
-    navigate: (nextRoute, nextProps) => navStack.navigate(nextRoute, nextProps),
+    navigate: (nextRoute, nextProps) => {
+      const top = navStack.getTop();
+      if (top.route === nextRoute) navStack.replace(nextRoute, nextProps);
+      else navStack.navigate(nextRoute, nextProps);
+    },
     replace: (nextRoute, nextProps) => navStack.replace(nextRoute, nextProps),
     goBack: () => navStack.goBack(),
     canGoBack: () => navStack.canGoBack(),