@oxyhq/services 22.10.0 → 22.11.0

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

@@ -44,6 +44,87 @@ describe('createSurfaceNavStack', () => {
     stack.requestDismiss('again');
     expect(stack.store.getState().closeResult).toBe('done');
   });
+
+  describe('result-bearing sub-flow (morphed-in avatar picker)', () => {
+    it('resolves with the descendant dismiss result and pops back to the caller frame', async () => {
+      const stack = createSurfaceNavStack('EditProfile');
+      const flow = stack.beginFlow('ChangeAvatar');
+      expect(stack.getTop().route).toBe('ChangeAvatar');
+      // Drill into the crop editor within the flow, then confirm.
+      stack.navigate('AvatarCrop', { imageUri: 'file:///x.jpg' });
+      stack.resolveFlowOrDismiss({ uri: 'file:///cropped.jpg' });
+      await expect(flow).resolves.toEqual({ uri: 'file:///cropped.jpg' });
+      // Popped back to the frame that started the flow — surface NOT dismissed.
+      expect(stack.getTop().route).toBe('EditProfile');
+      expect(stack.store.getState().closing).toBe(false);
+    });
+
+    it('resolves undefined when the flow entry frame is backed out of', async () => {
+      const stack = createSurfaceNavStack('EditProfile');
+      const flow = stack.beginFlow('ChangeAvatar');
+      stack.navigate('AvatarCrop');
+      expect(stack.goBack()).toBe(true); // crop -> list (still in flow)
+      expect(stack.goBack()).toBe(true); // list -> EditProfile (cancels flow)
+      await expect(flow).resolves.toBeUndefined();
+      expect(stack.getTop().route).toBe('EditProfile');
+      expect(stack.store.getState().closing).toBe(false);
+    });
+
+    it('resolveFlowOrDismiss with NO active flow dismisses the surface (cold present)', () => {
+      const stack = createSurfaceNavStack('ChangeAvatar');
+      stack.resolveFlowOrDismiss({ removed: true });
+      expect(stack.store.getState().closing).toBe(true);
+      expect(stack.store.getState().closeResult).toEqual({ removed: true });
+    });
+
+    it('abandons a pending flow (undefined) when the surface is torn down', async () => {
+      const stack = createSurfaceNavStack('EditProfile');
+      const flow = stack.beginFlow('ChangeAvatar');
+      stack.abandonActiveFlow();
+      await expect(flow).resolves.toBeUndefined();
+    });
+
+    it('NESTS flows: the inner selector resolves first, then the outer avatar flow', async () => {
+      // ChangeAvatar (outer) → "My Oxy files" FileManagement (inner) → back → crop.
+      const stack = createSurfaceNavStack('EditProfile');
+      const avatarFlow = stack.beginFlow('ChangeAvatar');
+      const fileFlow = stack.beginFlow('FileManagement');
+      expect(stack.getTop().route).toBe('FileManagement');
+      // Pick a file → inner flow resolves, pops back to ChangeAvatar (outer still open).
+      stack.resolveFlowOrDismiss({ id: 'file-1' });
+      await expect(fileFlow).resolves.toEqual({ id: 'file-1' });
+      expect(stack.getTop().route).toBe('ChangeAvatar');
+      expect(stack.store.getState().closing).toBe(false);
+      // Now drill to crop and confirm → outer flow resolves, pops to EditProfile.
+      stack.navigate('AvatarCrop');
+      stack.resolveFlowOrDismiss({ uri: 'file:///c.jpg' });
+      await expect(avatarFlow).resolves.toEqual({ uri: 'file:///c.jpg' });
+      expect(stack.getTop().route).toBe('EditProfile');
+    });
+
+    it('cancelling the inner selector returns to the outer flow, leaving it open', async () => {
+      const stack = createSurfaceNavStack('EditProfile');
+      const avatarFlow = stack.beginFlow('ChangeAvatar');
+      const fileFlow = stack.beginFlow('FileManagement');
+      expect(stack.goBack()).toBe(true); // FileManagement -> ChangeAvatar (cancels inner)
+      await expect(fileFlow).resolves.toBeUndefined();
+      expect(stack.getTop().route).toBe('ChangeAvatar');
+      // The outer avatar flow is still pending.
+      let outerSettled = false;
+      void avatarFlow.then(() => { outerSettled = true; });
+      await Promise.resolve();
+      expect(outerSettled).toBe(false);
+    });
+
+    it('tearing down the surface abandons ALL nested flows (undefined)', async () => {
+      const stack = createSurfaceNavStack('EditProfile');
+      const outer = stack.beginFlow('ChangeAvatar');
+      const inner = stack.beginFlow('FileManagement');
+      stack.abandonActiveFlow();
+      await expect(inner).resolves.toBeUndefined();
+      await expect(outer).resolves.toBeUndefined();
+    });
+  });
 });
 
 describe('pushSurfaceBackHandler', () => {

package/src/ui/navigation/accountDialogManager.ts

@@ -22,7 +22,19 @@ export interface AccountDialogControls {
   close: () => void;
 }
 
+/**
+ * Optional consumer overrides for account-dialog actions. `ProfileButton` (and
+ * similar hosts) register these while mounted so inbox/accounts can route
+ * "Manage" / "Add account" to app-local navigation instead of the SDK default.
+ */
+export interface AccountDialogConsumerHooks {
+  onNavigateManage?: () => void;
+  onAddAccount?: () => void;
+  onNavigateProfile?: () => void;
+}
+
 let controls: AccountDialogControls | null = null;
+let consumerHooks: AccountDialogConsumerHooks | null = null;
 const visibilityListeners = new Set<(visible: boolean) => void>();
 
 export function registerAccountDialogControls(next: AccountDialogControls): () => void {
@@ -34,6 +46,22 @@ export function registerAccountDialogControls(next: AccountDialogControls): () =
   };
 }
 
+/** Register app-local manage/add/profile handlers for the account dialog. */
+export function registerAccountDialogConsumerHooks(
+  next: AccountDialogConsumerHooks | null,
+): () => void {
+  consumerHooks = next;
+  return () => {
+    if (consumerHooks === next) {
+      consumerHooks = null;
+    }
+  };
+}
+
+export function getAccountDialogConsumerHooks(): AccountDialogConsumerHooks | null {
+  return consumerHooks;
+}
+
 /** Open the account dialog on `view` (default `accounts`). No-op before mount. */
 export function openAccountDialog(view?: AccountDialogView): void {
   controls?.open(view);

package/src/ui/navigation/bottomSheetManager.ts

@@ -1,6 +1,6 @@
 import type { RouteName } from './routes';
 import { isValidRoute } from './routes';
-import { getSurfacePresentation } from './surfaceRegistry';
+import { getSurfaceConfig } from './surfaceRegistry';
 import { closeAllRouteSurfaces, presentRoute, topRouteSurface } from './surfaces';
 
 /**
@@ -16,11 +16,10 @@ import { closeAllRouteSurfaces, presentRoute, topRouteSurface } from './surfaces
  */
 
 /**
- * Open a bottom-sheet route. If the top-most active surface hosts the SAME
- * presentation (the common all-sheets case) the route is drilled into it; a route
- * with a different presentation (the image picker's full-bleed surface) is
- * presented as a NEW surface on top. Opening with no active surface presents the
- * first one.
+ * Open a bottom-sheet route. By DEFAULT it drills into the top-most active
+ * surface — morphing it in place (every screen morphs). A NEW surface is stacked
+ * on top only when the target route declares `stacks` (reserved for genuine
+ * overlays — none today). Opening with no active surface presents the first one.
  *
  * `fullScreen` is accepted for signature compatibility and ignored — a route's
  * surface is now derived from its registry config, not a per-call flag.
@@ -39,7 +38,7 @@ export const showBottomSheet = (
   }
 
   const top = topRouteSurface();
-  if (top && top.presentation === getSurfacePresentation(screen, props)) {
+  if (top && !getSurfaceConfig(screen, props).stacks) {
     top.navigate(screen, props);
   } else {
     presentRoute(screen, props);

package/src/ui/navigation/routes.ts

@@ -39,7 +39,8 @@ export type RouteName =
     | 'CreateAccount' // Create a new account (organization / project / bot)
     | 'AccountMembers' // Manage an account's members (invite / roles / transfer)
     | 'AccountSettings' // Per-account profile edit + members + danger zone
-    | 'AvatarCrop' // Square-crop editor presented before avatar upload
+    | 'ChangeAvatar' // Profile-picture source list — the ONE entry into changing an avatar
+    | 'AvatarCrop' // Square-crop editor, reached by navigating within the ChangeAvatar surface
     | 'Notifications' // Per-channel notification preferences
     | 'ConnectedApps' // OAuth-authorized third-party apps the user can revoke
     | 'Preferences' // General user preferences (theme, reduce-motion, etc.)
@@ -83,6 +84,7 @@ const screenLoaders: Record<RouteName, () => ComponentType<BaseScreenProps>> = {
     CreateAccount: () => require('../screens/CreateAccountScreen').default,
     AccountMembers: () => require('../screens/AccountMembersScreen').default,
     AccountSettings: () => require('../screens/AccountSettingsScreen').default,
+    ChangeAvatar: () => require('../screens/ChangeAvatarScreen').default,
     AvatarCrop: () => require('../screens/AvatarCropScreen').default,
     Notifications: () => require('../screens/NotificationsScreen').default,
     ConnectedApps: () => require('../screens/ConnectedAppsScreen').default,

package/src/ui/navigation/surfaceNavStack.ts

@@ -48,6 +48,27 @@ export interface SurfaceNavStack {
   setStep(step: number): void;
   /** Request dismissal of the whole surface, resolving its promise with `result`. */
   requestDismiss(result?: unknown): void;
+  /**
+   * Begin a result-bearing SUB-FLOW inside this surface: push `route` as a frame
+   * and return a promise that settles when the flow finishes — a descendant's
+   * `dismiss(result)` resolves it with `result`, backing out of the flow's entry
+   * frame resolves it with `undefined` (cancelled) — popping the surface back to
+   * the frame that started the flow WITHOUT dismissing it. This is how a screen
+   * already living inside a surface (EditProfile, ManageAccount, ChangeAvatar)
+   * opens the avatar picker / media selector as a MORPH instead of a stacked
+   * surface while still awaiting its result. Flows NEST (ChangeAvatar → the "My
+   * Oxy files" selector → back), maintained as a stack.
+   */
+  beginFlow(route: RouteName, props?: Record<string, unknown>): Promise<unknown>;
+  /**
+   * Resolve the INNERMOST active sub-flow with `result` and pop back to its entry
+   * (the frame that called {@link beginFlow}), leaving the surface open. With NO
+   * active flow this falls back to {@link requestDismiss} — so a screen presented
+   * as its OWN surface still dismisses it. Wired to every screen's `dismiss` prop.
+   */
+  resolveFlowOrDismiss(result?: unknown): void;
+  /** Settle EVERY still-pending sub-flow with `undefined` (the surface is going away). */
+  abandonActiveFlow(): void;
   /** The current (top) frame. */
   getTop(): NavFrame;
 }
@@ -73,9 +94,41 @@ export function createSurfaceNavStack(
     return frames[frames.length - 1];
   };
 
+  // Result-bearing sub-flows currently running in this surface (the morphed-in
+  // avatar picker, and — NESTED within it — the "My Oxy files" media selector).
+  // A STACK: flows nest (ChangeAvatar → FileManagement → back to ChangeAvatar).
+  // Held OUTSIDE the store (resolvers are functions; flow presence must not
+  // re-render frames). Each flow's `returnLength` is the frame count BEFORE its
+  // entry frame was pushed, so settling pops back to exactly the frame that
+  // started it. `flowStack` is ordered outer → inner; the top is the innermost.
+  const flowStack: { returnLength: number; resolve: (result: unknown) => void }[] = [];
+
+  const requestDismiss = (result?: unknown): void => {
+    // Dismissing the whole surface abandons EVERY pending sub-flow — settle each
+    // promise so an awaiting caller (the avatar picker) never hangs.
+    while (flowStack.length) flowStack.pop()?.resolve(undefined);
+    if (store.getState().closing) return;
+    store.setState({ closing: true, closeResult: result });
+  };
+
+  const goBack = (): boolean => {
+    const { frames } = store.getState();
+    if (frames.length <= 1) return false;
+    const nextLength = frames.length - 1;
+    store.setState({ frames: frames.slice(0, -1) });
+    // Backing out past a sub-flow's entry frame cancels it (resolve undefined).
+    // A single pop crosses at most one boundary, but loop for safety.
+    while (flowStack.length && nextLength <= flowStack[flowStack.length - 1].returnLength) {
+      flowStack.pop()?.resolve(undefined);
+    }
+    return true;
+  };
+
   return {
     store,
     getTop,
+    requestDismiss,
+    goBack,
     navigate(nextRoute, nextProps) {
       store.setState((state) => ({ frames: [...state.frames, makeFrame(nextRoute, nextProps)] }));
     },
@@ -84,12 +137,6 @@ export function createSurfaceNavStack(
         frames: [...state.frames.slice(0, -1), makeFrame(nextRoute, nextProps)],
       }));
     },
-    goBack() {
-      const { frames } = store.getState();
-      if (frames.length <= 1) return false;
-      store.setState({ frames: frames.slice(0, -1) });
-      return true;
-    },
     canGoBack() {
       const { frames } = store.getState();
       return frames.length > 1 || (frames[frames.length - 1]?.step ?? 0) > 0;
@@ -102,9 +149,25 @@ export function createSurfaceNavStack(
         return { frames };
       });
     },
-    requestDismiss(result) {
-      if (store.getState().closing) return;
-      store.setState({ closing: true, closeResult: result });
+    beginFlow(nextRoute, nextProps) {
+      const returnLength = store.getState().frames.length;
+      store.setState((state) => ({ frames: [...state.frames, makeFrame(nextRoute, nextProps)] }));
+      return new Promise<unknown>((resolve) => {
+        flowStack.push({ returnLength, resolve });
+      });
+    },
+    resolveFlowOrDismiss(result) {
+      const flow = flowStack.pop();
+      if (!flow) {
+        // No flow → this screen owns its surface; dismiss it as before.
+        requestDismiss(result);
+        return;
+      }
+      store.setState((state) => ({ frames: state.frames.slice(0, flow.returnLength) }));
+      flow.resolve(result);
+    },
+    abandonActiveFlow() {
+      while (flowStack.length) flowStack.pop()?.resolve(undefined);
     },
   };
 }

package/src/ui/navigation/surfaceRegistry.ts

@@ -2,6 +2,7 @@ import type { ReactNode } from 'react';
 import type { AccountDialogView, FileMetadata } from '@oxyhq/core';
 import type { RouteName } from './routes';
 import type { AvatarCropResult } from '../screens/AvatarCropScreen';
+import type { AvatarRemovalResult } from '../screens/ChangeAvatarScreen';
 
 /**
  * The SDK's typed surface registry — the contract layer the SDK stacks on top of
@@ -60,7 +61,17 @@ export interface SurfaceRegistry {
   CreateAccount: SurfaceRoute;
   AccountMembers: SurfaceRoute;
   AccountSettings: SurfaceRoute;
-  /** Square-crop editor. Dismissed with the cropped {@link AvatarCropResult}. */
+  /**
+   * Profile-picture source list — the ONE entry into changing an avatar. Every
+   * source that yields an image navigates WITHIN this surface to `AvatarCrop`
+   * (so the panel morphs), and the crop's own dismissal resolves this surface.
+   * Hence the union: a confirmed crop, or the user removing their photo.
+   */
+  ChangeAvatar: SurfaceRoute<Record<string, unknown>, AvatarCropResult | AvatarRemovalResult>;
+  /**
+   * Square-crop editor. Dismissed with the cropped {@link AvatarCropResult}.
+   * Reached only by navigating within a `ChangeAvatar` surface.
+   */
   AvatarCrop: SurfaceRoute<Record<string, unknown>, AvatarCropResult>;
   Notifications: SurfaceRoute;
   ConnectedApps: SurfaceRoute;
@@ -91,15 +102,18 @@ export type SurfaceResult<K extends RouteName> = SurfaceRegistry[K]['result'];
  * How a surface renders — the SDK's presentation taxonomy. Each value maps to a
  * concrete Bloom `Dialog` placement/chrome in `surfaces.ts`:
  *
- *   - `'sheet'`      → responsive `{ base: 'bottom', md: 'center' }` (the default:
- *                      a bottom sheet on narrow viewports, a centered card on wide).
- *   - `'center'`     → a plain centered modal at every width.
+ *   - `'sheet'`      → responsive `{ base: 'bottom', md: 'center' }` (the default,
+ *                      and — since every screen morphs — the presentation of EVERY
+ *                      route today: a bottom sheet on narrow, a centered card wide).
+ *   - `'center'`     → a plain centered modal at every width. Currently unused.
  *   - `'drawer'`     → responsive `{ base: 'bottom', md: 'left' }` side drawer.
- *   - `'fullScreen'` → approximated with the shared `Dialog`: a full-height sheet /
- *                      large centered card, flush (`contentPadding: 0`) content, a
- *                      black canvas and programmatic-only dismiss (the flagship
- *                      image picker). A real Bloom `'fullScreen'` placement is a
- *                      follow-up if the approximation reads wrong on device.
+ *                      Currently unused.
+ *   - `'fullScreen'` → a flush black-canvas surface (`contentPadding: 0`,
+ *                      programmatic-only dismiss). Currently unused: the flagship
+ *                      photo picker now MORPHS in place as a `sheet` (it paints its
+ *                      own black canvas + bar inside the themed panel), so nothing
+ *                      needs a stacked full-bleed surface. Retained for a future
+ *                      route that genuinely must be full-bleed.
  */
 export type SurfacePresentation = 'sheet' | 'center' | 'drawer' | 'fullScreen';
 
@@ -123,6 +137,47 @@ export interface SurfaceRouteConfig {
    * wrap it in a ScrollView. Threaded onto Bloom's `Dialog` via `bloomOptionsFor`.
    */
   scrollable: boolean;
+  /**
+   * Whether the surface MORPHS when this route is navigated to WITHIN it — the
+   * panel animates from the outgoing frame's size to this one's instead of
+   * hard-cutting (the in-place NAV-WITHIN size animation). `true` for every
+   * ordinary route screen; a wizard step swap counts as a frame here too.
+   *
+   * Distinct from {@link stacks}: `morph` tunes the size animation of an IN-PLACE
+   * frame swap; `stacks` decides whether the frame lands in place at all or opens
+   * a new surface. A stacked surface can still morph between ITS OWN frames.
+   */
+  morph: boolean;
+  /**
+   * An EXPLICIT target size the panel MORPHS to for this route, instead of the
+   * measured natural height / the surface width. This is how an own-scroller frame
+   * (its content owns its own scroll, so the panel can't measure it) still GROWS
+   * its container to a large declared size — the panel animates UP to it on entry
+   * and back DOWN on exit while the frame's inner list scrolls within. `heightRatio`
+   * is a fraction of the viewport height (clamped there); `maxWidth` (px) widens the
+   * centered card beyond the ordinary sheet. Omit for the normal measured behaviour.
+   */
+  frameSize?: { heightRatio?: number; maxWidth?: number };
+  /**
+   * Whether navigating TO this route from INSIDE an existing surface opens a NEW
+   * stacked surface (its own backdrop + entry animation — the DEPTH axis) instead
+   * of morphing in place within the current one (the NAV-WITHIN axis).
+   *
+   * `false` (the DEFAULT) — morph in place: the route is pushed as a frame in the
+   * host surface's nav stack and the panel reshapes from the previous frame to it
+   * (size-animated per {@link morph}). Every ordinary screen. This is what makes
+   * morph the default: a drill-in navigates WITHIN unless the target opts out.
+   *
+   * `true` — the route's chrome is fundamentally incompatible with morphing into
+   * a host, so it must own its own surface: the full-bleed `fullScreen` image
+   * picker (black canvas, flush content, programmatic-only dismiss). Presented on
+   * top; dismissing it unwinds back to the surface that opened it.
+   *
+   * NOTE: the DEPTH `present` / `presentDetached` APIs ALWAYS open a new surface
+   * regardless of this flag — `stacks` only governs the in-surface drill-in
+   * (`navigate` / `showBottomSheet`) decision in `navigateWithinOrPresent`.
+   */
+  stacks: boolean;
   /**
    * Whether the surface renders the Dialog's OWN navigation header (sticky
    * gradient nav bar + large collapsing title over the surface's scroll content).
@@ -145,13 +200,14 @@ const DEFAULT_SURFACE_CONFIG: SurfaceRouteConfig = {
   presentation: 'sheet',
   scrollable: true,
   header: true,
+  morph: true,
+  stacks: false,
   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.
@@ -160,9 +216,15 @@ const DEFAULT_SURFACE_CONFIG: SurfaceRouteConfig = {
  * `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.
+ *
+ * `AvatarCrop` used to be here too, for its own translucent Cancel/title/Done
+ * bar. It is now reached ONLY by navigating within a `ChangeAvatar` surface, and
+ * the Dialog's `header` is fixed for a surface's whole life — a headerless frame
+ * inside a header-mode surface would stack two bars. So the crop declares its
+ * title + its "Use photo" action through `useSurfaceHeader` like every other
+ * screen, and keeps only its dark crop stage.
  */
 const HEADERLESS_ROUTES: ReadonlySet<RouteName> = new Set<RouteName>([
-  'AvatarCrop',
   'PaymentGateway',
   'WelcomeNewUser',
   'Profile',
@@ -209,18 +271,30 @@ const OWN_SCROLL_CONTAINER_ROUTES: ReadonlySet<RouteName> = new Set<RouteName>([
 ]);
 
 /**
- * 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, and every route that owns its own scroll container is
- * marked `scrollable: false`.
+ * Resolve the surface configuration for a route + props. Every route defaults to
+ * the responsive sheet and MORPHS in place when navigated to from within a surface
+ * (no route stacks — genuine overlays are Bloom-raw `surfaces.present`/`confirm`
+ * calls, outside this registry). The image-only FileManagement picker is a normal
+ * sheet that owns its own scroll + translucent bar (no Dialog nav header); every
+ * other own-scroller is marked `scrollable: false`.
  */
 export const getSurfaceConfig = (
   route: RouteName,
   props: Record<string, unknown>,
 ): SurfaceRouteConfig => {
   if (route === 'FileManagement' && isFileManagementImageOnlyPicker(props)) {
-    // The full-bleed image picker owns its own translucent top bar — no nav header.
-    return { ...DEFAULT_SURFACE_CONFIG, presentation: 'fullScreen', scrollable: false, header: false };
+    // The flagship photo picker MORPHS in place like every other screen. It is an
+    // own-scroller (`PhotoPickerView`'s FlatList) that paints its OWN full-bleed
+    // black canvas + translucent top bar INSIDE the themed panel, so it takes no
+    // Dialog nav header. It needs ROOM for the photo grid, so it declares an
+    // explicit LARGE morph target — the panel grows UP to a near-full-height,
+    // wider card on entry (and back down on pick→crop), the grid scrolling within.
+    return {
+      ...DEFAULT_SURFACE_CONFIG,
+      scrollable: false,
+      header: false,
+      frameSize: { heightRatio: 0.9, maxWidth: 640 },
+    };
   }
   if (HEADERLESS_ROUTES.has(route)) {
     return { ...DEFAULT_SURFACE_CONFIG, header: false };