@oxyhq/bloom 0.45.0 → 0.46.0

package/src/surfaces/SurfaceHost.tsx

@@ -0,0 +1,207 @@
+import React, {
+  useCallback,
+  useEffect,
+  useMemo,
+  useSyncExternalStore,
+} from 'react';
+import { BackHandler, Platform } from 'react-native';
+
+import { useDialogControl } from '../dialog/context';
+import type { DialogProps } from '../dialog/types';
+import {
+  finalizeClose,
+  getSnapshot,
+  present,
+  requestDismiss,
+  resetSurfaces,
+  subscribe,
+} from './surfaceStore';
+import { SurfaceContext } from './useSurface';
+import type { SurfaceControls, SurfaceEntry, SurfacePresentation } from './types';
+
+type DialogComponent = React.ComponentType<DialogProps>;
+
+/** Default placement — the ecosystem's responsive "sheet" (bottom → centered). */
+const DEFAULT_PLACEMENT: SurfacePresentation['placement'] = {
+  base: 'bottom',
+  md: 'center',
+};
+
+/** Map a surface's presentation config onto the shared `Dialog` props. */
+function placementFor(p: SurfacePresentation): Partial<DialogProps> {
+  return {
+    placement: p.placement ?? DEFAULT_PLACEMENT,
+    width: p.width,
+    maxWidth: p.maxWidth,
+    maxHeightRatio: p.maxHeightRatio,
+    inset: p.inset,
+    showHandle: p.showHandle,
+    dismissOnBackdrop: p.dismissOnBackdrop,
+    contentPadding: p.contentPadding,
+    style: p.style,
+    panelStyle: p.panelStyle,
+    panelClassName: p.panelClassName,
+    containerStyle: p.containerStyle,
+    containerClassName: p.containerClassName,
+    label: p.label,
+    testID: p.testID,
+  };
+}
+
+/**
+ * Build the `<SurfaceHost>` + `<SurfaceProvider>` bound to a platform `Dialog`.
+ *
+ * `Dialog` is platform-forked (native `BottomSheet`-backed vs. pure-DOM web
+ * overlay), so — like `createAlertDialog` — the platform entry files
+ * (`index.ts` / `index.web.ts`) inject the correct one. The stack logic below is
+ * single-source, no duplication.
+ */
+export function createSurfaceHost(Dialog: DialogComponent) {
+  /**
+   * One stacked surface. Bridges a store entry onto an IMPERATIVE `Dialog`
+   * (`useDialogControl()` + `open()`/`close()`) — never the controlled
+   * `open`/`onClose` boolean path, which fires `onClose` synchronously as the
+   * dismiss REQUEST and has no post-exit callback, so it could never tell the
+   * store WHEN to splice the entry after the exit animation.
+   */
+  function SurfaceLayer({
+    entry,
+    index,
+  }: {
+    entry: SurfaceEntry;
+    index: number;
+  }) {
+    const control = useDialogControl();
+    const { id, status } = entry;
+
+    const controls = useMemo<SurfaceControls>(
+      () => ({
+        dismiss: (result?: unknown) => requestDismiss(id, result),
+        present: (render, opts) => present(render, opts),
+      }),
+      [id],
+    );
+
+    // Open imperatively on mount (mirrors `AlertDialog`'s canonical
+    // fresh-mount open-from-effect; `control` is stable for the layer's life).
+    useEffect(() => {
+      control.open();
+    }, [control]);
+
+    // When the store flips this entry to 'closing' (a programmatic dismiss,
+    // dismissAll, dismissToRoot, Escape, or Android-back), run the exit
+    // animation. A user backdrop/Escape handled by the Dialog itself instead
+    // drives its own internal close; either way `onClose` fires post-exit.
+    useEffect(() => {
+      if (status === 'closing') control.close();
+    }, [status, control]);
+
+    // Fires AFTER the exit animation settles (imperative mode), for ANY
+    // dismissal path — user backdrop/Escape/back OR a programmatic dismiss.
+    // `requestDismiss` resolves-once (a programmatic dismiss already resolved
+    // with its result; this is a no-op then), then `finalizeClose` splices the
+    // entry out. Guarded by unique ids + `'closing'` status in the store.
+    const handleClose = useCallback(() => {
+      requestDismiss(id);
+      finalizeClose(id);
+    }, [id]);
+
+    const placement = useMemo(
+      () => placementFor(entry.presentation),
+      [entry.presentation],
+    );
+
+    return (
+      <Dialog control={control} onClose={handleClose} layer={index} {...placement}>
+        <SurfaceContext.Provider value={controls}>
+          {entry.render(controls)}
+        </SurfaceContext.Provider>
+      </Dialog>
+    );
+  }
+
+  function SurfaceHost() {
+    const stack = useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+
+    useAndroidBackDismissesTop();
+    useEscapeDismissesTop();
+
+    return (
+      <>
+        {stack.map((entry, index) => (
+          <SurfaceLayer key={entry.id} entry={entry} index={index} />
+        ))}
+      </>
+    );
+  }
+  SurfaceHost.displayName = 'SurfaceHost';
+
+  /**
+   * Mount ONCE near your app root — renders `children` plus the stack host.
+   * Requires the Bloom Portal provider to be mounted too (same as any `<Dialog>`
+   * usage): on web the Portal auto-creates `#bloom-portal-root`; on native mount
+   * `<Provider>`/`<Outlet>` from `@oxyhq/bloom/portal`. Can equally be folded
+   * next to that Portal provider — `<SurfaceHost>` used directly does the same
+   * job without wrapping `children`.
+   */
+  function SurfaceProvider({ children }: { children: React.ReactNode }) {
+    // Resolve any pending awaiters if the provider unmounts so no `present()`
+    // promise is stranded.
+    useEffect(() => () => resetSurfaces(), []);
+    return (
+      <>
+        {children}
+        <SurfaceHost />
+      </>
+    );
+  }
+  SurfaceProvider.displayName = 'SurfaceProvider';
+
+  return { SurfaceHost, SurfaceProvider };
+}
+
+/**
+ * ONE Android hardware-back handler for the whole stack → dismiss the TOP
+ * surface. Reads the live top from the store so a single registration always
+ * targets the current top. Returns `false` when the stack is empty so app-level
+ * back navigation is untouched.
+ */
+function useAndroidBackDismissesTop(): void {
+  useEffect(() => {
+    if (Platform.OS !== 'android') return;
+    const sub = BackHandler.addEventListener('hardwareBackPress', () => {
+      const stack = getSnapshot();
+      const top = stack[stack.length - 1];
+      if (!top) return false;
+      if (top.presentation.dismissOnBackdrop === false) return true;
+      requestDismiss(top.id);
+      return true;
+    });
+    return () => sub.remove();
+  }, []);
+}
+
+/**
+ * Web-only: route Escape to the TOP surface only. A window-CAPTURE listener runs
+ * before each `Dialog`'s own document-level keydown, so `stopImmediatePropagation`
+ * prevents the lower stacked dialogs from ALSO handling Escape (they each add a
+ * document listener) — Escape dismisses strictly the top, LIFO. No-op on native.
+ */
+function useEscapeDismissesTop(): void {
+  useEffect(() => {
+    if (Platform.OS !== 'web') return;
+    if (typeof window === 'undefined' || typeof document === 'undefined') return;
+    const handler = (e: KeyboardEvent) => {
+      if (e.key !== 'Escape') return;
+      const stack = getSnapshot();
+      const top = stack[stack.length - 1];
+      if (!top) return;
+      if (top.presentation.dismissOnBackdrop === false) return;
+      e.stopImmediatePropagation();
+      e.preventDefault();
+      requestDismiss(top.id);
+    };
+    window.addEventListener('keydown', handler, true);
+    return () => window.removeEventListener('keydown', handler, true);
+  }, []);
+}

package/src/surfaces/api.ts

@@ -0,0 +1,55 @@
+import {
+  dismissAll,
+  dismissToRoot,
+  dismissTop,
+  present,
+  requestDismiss,
+} from './surfaceStore';
+import { confirm, prompt } from './prompts';
+import type { PresentOptions, SurfaceRenderFn } from './types';
+
+/**
+ * Dismiss the TOP surface, resolving its `present()` promise with `result`.
+ * The public counterpart of the store's `dismissTop`.
+ */
+function dismiss(result?: unknown): void {
+  dismissTop(result);
+}
+
+/**
+ * Dismiss a SPECIFIC surface by id, resolving its `present()` promise with
+ * `result`. Rarely needed — most call sites use `dismiss()` (top) or the
+ * per-surface `SurfaceControls.dismiss`.
+ */
+function dismissById(id: string, result?: unknown): void {
+  requestDismiss(id, result);
+}
+
+/**
+ * The shared imperative surface-stack API — a module singleton (mirrors
+ * `alert()`'s shape) so any consumer, in the SDK or an app, presents into the
+ * SAME coordinated Bloom stack from anywhere without threading a provider.
+ *
+ * Exposed at the package root as `surfaces` (avoids a bare `present`/`confirm`
+ * name clash with the existing `alert-dialog` `confirm`); the individual
+ * functions are also named exports of `@oxyhq/bloom/surfaces` for direct import.
+ */
+export const surfaces = {
+  /** Present a new surface on top. Resolves with the dismissal result. */
+  present: <Result = unknown>(render: SurfaceRenderFn, opts?: PresentOptions) =>
+    present<Result>(render, opts),
+  /** Dismiss the top surface. */
+  dismiss,
+  /** Dismiss a specific surface by id. */
+  dismissById,
+  /** Dismiss everything above the root surface. */
+  dismissToRoot,
+  /** Dismiss the entire stack (resolves pending awaiters with `undefined`). */
+  dismissAll,
+  /** Present a confirm surface; resolves `true`/`false`. */
+  confirm,
+  /** Present a prompt surface; resolves the string or `null`. */
+  prompt,
+} as const;
+
+export { confirm, dismiss, dismissAll, dismissById, dismissToRoot, present, prompt };

package/src/surfaces/index.ts

@@ -0,0 +1,38 @@
+import { Dialog } from '../dialog';
+import { createSurfaceHost } from './SurfaceHost';
+
+/**
+ * The shared, content-agnostic SURFACE STACK.
+ *
+ * `<SurfaceProvider>`/`<SurfaceHost>` render the coordinated stack; the
+ * imperative `surfaces` API (+ its named functions) present into it from
+ * anywhere; `useSurface()` gives a presented surface its own controls.
+ *
+ * `SurfaceHost`/`SurfaceProvider` are bound to the NATIVE `Dialog` here; the web
+ * fork (`./index.web`) binds the web `Dialog`. The store, imperative API, hook,
+ * and types are platform-agnostic and shared by both.
+ */
+const { SurfaceHost, SurfaceProvider } = createSurfaceHost(Dialog);
+
+export { SurfaceHost, SurfaceProvider };
+export {
+  surfaces,
+  present,
+  dismiss,
+  dismissById,
+  dismissToRoot,
+  dismissAll,
+  confirm,
+  prompt,
+} from './api';
+export { useSurface } from './useSurface';
+export type {
+  SurfacePresentation,
+  PresentOptions,
+  SurfaceControls,
+  SurfaceRenderFn,
+  SurfaceStatus,
+  SurfaceEntry,
+  SurfaceConfirmOptions,
+  SurfacePromptOptions,
+} from './types';

package/src/surfaces/index.web.ts

@@ -0,0 +1,33 @@
+import { Dialog } from '../dialog/index.web';
+import { createSurfaceHost } from './SurfaceHost';
+
+/**
+ * Web variant of the surface stack barrel. Identical surface area to the native
+ * `./index.ts` — it just binds the web-fork `Dialog` (`Dialog.web.tsx`, a
+ * pure-DOM overlay) instead of the native `BottomSheet`-backed one. The store,
+ * imperative API, hook, and types are shared, platform-agnostic modules.
+ */
+const { SurfaceHost, SurfaceProvider } = createSurfaceHost(Dialog);
+
+export { SurfaceHost, SurfaceProvider };
+export {
+  surfaces,
+  present,
+  dismiss,
+  dismissById,
+  dismissToRoot,
+  dismissAll,
+  confirm,
+  prompt,
+} from './api';
+export { useSurface } from './useSurface';
+export type {
+  SurfacePresentation,
+  PresentOptions,
+  SurfaceControls,
+  SurfaceRenderFn,
+  SurfaceStatus,
+  SurfaceEntry,
+  SurfaceConfirmOptions,
+  SurfacePromptOptions,
+} from './types';

package/src/surfaces/prompts.tsx

@@ -0,0 +1,178 @@
+import React, { useCallback, useState } from 'react';
+import { Text, View } from 'react-native';
+
+import { Button } from '../button';
+import { TextFieldInput } from '../text-field';
+import { useTheme } from '../theme/use-theme';
+import { present } from './surfaceStore';
+import type {
+  SurfaceConfirmOptions,
+  SurfaceControls,
+  SurfacePromptOptions,
+} from './types';
+
+/**
+ * Built-in `confirm` / `prompt` surfaces.
+ *
+ * They are implemented AS surfaces — each calls `present(...)` so it STACKS
+ * correctly above any open surface with the right layer/z (unlike Bloom's
+ * one-at-a-time `alert()` FIFO queue, which cannot layer over another surface).
+ * Their buttons resolve through the surface's own `dismiss(result)` (NOT the
+ * underlying `Dialog`'s close), so the value flows back through the `present()`
+ * promise.
+ */
+
+const TITLE_STYLE = { fontSize: 22, fontWeight: '600' as const, lineHeight: 30 };
+const MESSAGE_STYLE = { fontSize: 16, lineHeight: 22 };
+
+function ConfirmSurface({
+  options,
+  surface,
+}: {
+  options: SurfaceConfirmOptions;
+  surface: SurfaceControls;
+}) {
+  const theme = useTheme();
+  const onConfirm = useCallback(() => surface.dismiss(true), [surface]);
+  const onCancel = useCallback(() => surface.dismiss(false), [surface]);
+
+  return (
+    <View>
+      <Text
+        style={[
+          TITLE_STYLE,
+          {
+            color: theme.colors.text,
+            paddingBottom: options.message ? 4 : 16,
+          },
+        ]}
+      >
+        {options.title}
+      </Text>
+      {options.message ? (
+        <Text
+          style={[
+            MESSAGE_STYLE,
+            { color: theme.colors.textSecondary, paddingBottom: 16 },
+          ]}
+        >
+          {options.message}
+        </Text>
+      ) : null}
+      <View style={{ gap: 8 }}>
+        <Button
+          variant={options.destructive ? 'destructive' : 'primary'}
+          onPress={onConfirm}
+          testID="bloom-surface-confirm-confirm"
+        >
+          {options.confirmLabel ?? 'Confirm'}
+        </Button>
+        {options.hideCancel ? null : (
+          <Button
+            variant="secondary"
+            onPress={onCancel}
+            testID="bloom-surface-confirm-cancel"
+          >
+            {options.cancelLabel ?? 'Cancel'}
+          </Button>
+        )}
+      </View>
+    </View>
+  );
+}
+
+function PromptSurface({
+  options,
+  surface,
+}: {
+  options: SurfacePromptOptions;
+  surface: SurfaceControls;
+}) {
+  const theme = useTheme();
+  const [value, setValue] = useState(options.defaultValue ?? '');
+  const onSubmit = useCallback(() => surface.dismiss(value), [surface, value]);
+  const onCancel = useCallback(() => surface.dismiss(null), [surface]);
+
+  return (
+    <View>
+      <Text
+        style={[
+          TITLE_STYLE,
+          {
+            color: theme.colors.text,
+            paddingBottom: options.message ? 4 : 16,
+          },
+        ]}
+      >
+        {options.title}
+      </Text>
+      {options.message ? (
+        <Text
+          style={[
+            MESSAGE_STYLE,
+            { color: theme.colors.textSecondary, paddingBottom: 16 },
+          ]}
+        >
+          {options.message}
+        </Text>
+      ) : null}
+      <TextFieldInput
+        label={options.inputLabel ?? options.title}
+        placeholder={options.placeholder}
+        value={value}
+        onChangeText={setValue}
+        autoFocus
+        returnKeyType="done"
+        onSubmitEditing={onSubmit}
+        testID="bloom-surface-prompt-input"
+      />
+      <View style={{ gap: 8, paddingTop: 16 }}>
+        <Button
+          variant="primary"
+          onPress={onSubmit}
+          testID="bloom-surface-prompt-confirm"
+        >
+          {options.confirmLabel ?? 'OK'}
+        </Button>
+        <Button
+          variant="secondary"
+          onPress={onCancel}
+          testID="bloom-surface-prompt-cancel"
+        >
+          {options.cancelLabel ?? 'Cancel'}
+        </Button>
+      </View>
+    </View>
+  );
+}
+
+/**
+ * Present a confirm surface stacked on top of anything currently open. Resolves
+ * `true` on confirm, `false` on cancel OR on backdrop/Escape/back dismissal.
+ */
+export function confirm(options: SurfaceConfirmOptions): Promise<boolean> {
+  return present<unknown>(
+    (surface) => <ConfirmSurface options={options} surface={surface} />,
+    {
+      placement: options.placement ?? 'center',
+      dismissOnBackdrop: options.dismissible ?? true,
+      label: options.title,
+    },
+  ).then((result) => result === true);
+}
+
+/**
+ * Present a prompt surface stacked on top of anything currently open. Resolves
+ * the entered string on submit, or `null` on cancel OR backdrop/Escape/back
+ * dismissal.
+ */
+export function prompt(options: SurfacePromptOptions): Promise<string | null> {
+  return present<unknown>(
+    (surface) => <PromptSurface options={options} surface={surface} />,
+    {
+      placement: options.placement ?? 'center',
+      dismissOnBackdrop: options.dismissible ?? true,
+      label: options.title,
+    },
+  ).then((result) => (typeof result === 'string' ? result : null));
+}

package/src/surfaces/surfaceStore.ts

@@ -0,0 +1,168 @@
+import type {
+  PresentOptions,
+  SurfaceEntry,
+  SurfaceRenderFn,
+} from './types';
+
+/**
+ * The shared, content-agnostic SURFACE STACK.
+ *
+ * A module-singleton store (same pattern as `theme/ambient-store.ts` and
+ * `dialog/alert-store.ts`) holding an ordered stack of surfaces presented ON TOP
+ * of each other — bottom→top, the last entry is the top. One coordinated stack
+ * that the whole ecosystem (the SDK AND consumer apps) presents into, so
+ * overlays never clash: per-layer z, top-only interactivity, backdrop/Escape/
+ * back routed to the TOP surface, lower layers dimmed.
+ *
+ * It is CONTENT-AGNOSTIC: `present` takes a render function, not a route name.
+ * Bloom must never know about routes; the SDK layers its route registry on top.
+ *
+ * `getSnapshot` returns a STABLE reference while unchanged (the array identity
+ * only changes on a real mutation), so `useSyncExternalStore` — and the React
+ * Compiler — never see a silently-stale value.
+ */
+
+let idCounter = 0;
+function genId(): string {
+  idCounter += 1;
+  return `bloom-surface-${idCounter}`;
+}
+
+/** A single frozen "empty stack" snapshot returned by `getSnapshot` when idle. */
+const EMPTY: readonly SurfaceEntry[] = Object.freeze([]);
+
+let surfaces: readonly SurfaceEntry[] = EMPTY;
+const listeners = new Set<() => void>();
+
+function emit(): void {
+  for (const listener of listeners) listener();
+}
+
+/** Subscribe to stack changes. Returns an unsubscribe fn. */
+export function subscribe(listener: () => void): () => void {
+  listeners.add(listener);
+  return () => {
+    listeners.delete(listener);
+  };
+}
+
+/** Current stack snapshot (stable ref while unchanged). Bottom→top. */
+export function getSnapshot(): readonly SurfaceEntry[] {
+  return surfaces;
+}
+
+/**
+ * Present a new surface on TOP of the stack. Returns a promise that resolves
+ * with the value passed to `dismiss(result)` (or `undefined` when the surface is
+ * dismissed without a result / by a stack-wide clear).
+ */
+export function present<Result = unknown>(
+  render: SurfaceRenderFn,
+  opts?: PresentOptions,
+): Promise<Result> {
+  return new Promise<Result>((resolve) => {
+    const entry: SurfaceEntry = {
+      id: genId(),
+      render,
+      presentation: opts ?? {},
+      status: 'open',
+      resolve: resolve as (result: unknown) => void,
+      settled: false,
+      generation: 0,
+    };
+    surfaces = [...surfaces, entry];
+    emit();
+  });
+}
+
+/**
+ * Request dismissal of a surface. RESOLVES THE PROMISE IMMEDIATELY (the exit
+ * animation that follows is cosmetic) and flips the entry to `'closing'` so the
+ * host runs its exit animation. Resolution is resolve-once via the `settled`
+ * guard — a second request (or the host's post-exit `onClose`) never re-resolves
+ * with a different value. Bumps the entry `generation` so a completion callback
+ * from a superseded cycle is inert.
+ */
+export function requestDismiss(id: string, result?: unknown): void {
+  const entry = surfaces.find((e) => e.id === id);
+  if (!entry) return;
+
+  // Resolve-once. The mapped replacement below carries `settled: true`, so a
+  // later `requestDismiss(id)` reads the settled entry and skips this branch —
+  // no in-place mutation of the live entry is needed.
+  if (!entry.settled) {
+    entry.resolve(result);
+  }
+
+  if (entry.status === 'closing') return;
+
+  surfaces = surfaces.map((e) =>
+    e.id === id
+      ? { ...e, settled: true, status: 'closing', generation: e.generation + 1 }
+      : e,
+  );
+  emit();
+}
+
+/**
+ * Splice a surface out of the stack once its exit animation has settled. Called
+ * by the host from the `Dialog`'s post-exit `onClose`. Idempotent and gated on
+ * `'closing'` status: a stale/duplicate call — or one for an entry that is not
+ * actually closing — is a no-op, which (together with unique entry ids) is the
+ * stale-callback hygiene `BottomSheetBase`'s generation guard provides for its
+ * reused instance.
+ */
+export function finalizeClose(id: string): void {
+  const entry = surfaces.find((e) => e.id === id);
+  if (!entry || entry.status !== 'closing') return;
+  const next = surfaces.filter((e) => e.id !== id);
+  surfaces = next.length === 0 ? EMPTY : next;
+  emit();
+}
+
+/** Dismiss the TOP surface, resolving its promise with `result`. */
+export function dismissTop(result?: unknown): void {
+  const top = surfaces[surfaces.length - 1];
+  if (top) requestDismiss(top.id, result);
+}
+
+/**
+ * Dismiss every surface ABOVE the bottom-most one, keeping the root surface
+ * open. Pending awaiters of the dismissed surfaces resolve with `undefined` so
+ * they never hang. No-op with 0 or 1 surfaces.
+ */
+export function dismissToRoot(): void {
+  if (surfaces.length <= 1) return;
+  const above = surfaces.slice(1).map((e) => e.id);
+  for (const id of above) requestDismiss(id, undefined);
+}
+
+/**
+ * Dismiss the ENTIRE stack. Every pending awaiter resolves with `undefined` so
+ * none hang.
+ */
+export function dismissAll(): void {
+  const ids = surfaces.map((e) => e.id);
+  for (const id of ids) requestDismiss(id, undefined);
+}
+
+/**
+ * Hard-reset the stack synchronously (no exit animation), resolving all pending
+ * awaiters with `undefined`. Used when the host provider unmounts so no
+ * `present()` promise is stranded.
+ */
+export function resetSurfaces(): void {
+  if (surfaces.length === 0) return;
+  const pending = surfaces;
+  surfaces = EMPTY;
+  for (const entry of pending) {
+    if (!entry.settled) entry.resolve(undefined);
+  }
+  emit();
+}
+
+/** Test-only: hard-reset without notifying (drops listeners' work). */
+export function __resetSurfacesForTests(): void {
+  surfaces = EMPTY;
+  idCounter = 0;
+}