@oxyhq/bloom 0.44.1 → 0.46.0

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;
+}

package/src/surfaces/types.ts

@@ -0,0 +1,156 @@
+import type { ReactNode } from 'react';
+import type { StyleProp, ViewStyle } from 'react-native';
+
+import type { DialogInset, ResponsiveDialogPlacement } from '../dialog/types';
+
+/**
+ * How a surface renders — the placement + the `Dialog` sizing/chrome options a
+ * surface needs. This is the CONTENT-AGNOSTIC presentation config: it never
+ * references a route or screen name (Bloom's stack knows nothing about routes;
+ * the SDK layers its route registry on top).
+ *
+ * The values map 1:1 onto the shared {@link ../dialog/types#DialogProps}, so a
+ * surface reads/behaves identically to a hand-mounted `<Dialog>` with the same
+ * props — only stacked/coordinated by {@link SurfaceHost}.
+ */
+export interface SurfacePresentation {
+  /**
+   * Surface anchor. Defaults to `{ base: 'bottom', md: 'center' }` — a bottom
+   * sheet on narrow viewports that becomes a centered modal on wide ones (the
+   * ecosystem's canonical responsive "sheet"). Pass `'center'` for a plain
+   * modal, `'left'`/`'right'` for a drawer, or any responsive placement map.
+   */
+  placement?: ResponsiveDialogPlacement;
+  /** Side-sheet width (px) on wide screens. Forwarded to `Dialog`. */
+  width?: number;
+  /** Centered-card max width (px). Forwarded to `Dialog`. */
+  maxWidth?: number;
+  /** Bottom-sheet max height as a fraction of the viewport height. */
+  maxHeightRatio?: number;
+  /** Side-sheet inset (px) from the root overlay's edges. */
+  inset?: DialogInset;
+  /** Whether to render the drag handle in bottom-sheet mode. */
+  showHandle?: boolean;
+  /**
+   * Whether tapping the backdrop / pressing Escape / Android-back dismisses the
+   * surface. Defaults to `true`. Set `false` for a blocking surface that must be
+   * dismissed programmatically (e.g. an unanswered required prompt).
+   */
+  dismissOnBackdrop?: boolean;
+  /** Inner padding (px) of the surface content container. Forwarded to `Dialog`. */
+  contentPadding?: number;
+  /** Style overrides applied to the inner content container. */
+  style?: StyleProp<ViewStyle>;
+  /** Style overrides for the side/bottom placement panel surface. */
+  panelStyle?: StyleProp<ViewStyle>;
+  /** NativeWind classes for the side/bottom placement panel surface. */
+  panelClassName?: string;
+  /** Style for the root overlay (theme-var scope, rail offset, etc.). */
+  containerStyle?: StyleProp<ViewStyle>;
+  /** NativeWind classes for the root overlay. */
+  containerClassName?: string;
+  /** Accessibility label applied to the surface's dialog role. */
+  label?: string;
+  /** Stable testID forwarded to the underlying `Dialog`. */
+  testID?: string;
+}
+
+/** Options accepted by `present` / `SurfaceControls.present`. */
+export type PresentOptions = SurfacePresentation;
+
+/**
+ * Controls handed to a presented surface — both as the argument to its render
+ * function AND via {@link ../surfaces/useSurface#useSurface}. This is the DEPTH
+ * axis only: a surface can dismiss ITSELF (resolving its own `present()`
+ * promise) or `present` a CHILD surface stacked above it. Navigation WITHIN a
+ * surface (route history / drill-in) is deliberately NOT here — that is the
+ * SDK's route layer, which composes on top of this stack.
+ */
+export interface SurfaceControls {
+  /**
+   * Dismiss THIS surface, resolving the promise returned by the `present` call
+   * that created it with `result` (or `undefined`). Resolves immediately; the
+   * exit animation is cosmetic.
+   */
+  dismiss: (result?: unknown) => void;
+  /**
+   * Stack a CHILD surface directly above this one. Resolves with the child's
+   * dismissal result. The child paints above (higher layer) and captures
+   * backdrop/Escape/back until it is dismissed.
+   */
+  present: <Result = unknown>(
+    render: SurfaceRenderFn,
+    opts?: PresentOptions,
+  ) => Promise<Result>;
+}
+
+/** A surface's content factory — receives its own {@link SurfaceControls}. */
+export type SurfaceRenderFn = (surface: SurfaceControls) => ReactNode;
+
+/** Lifecycle status of a stacked surface. */
+export type SurfaceStatus = 'open' | 'closing';
+
+/**
+ * One entry in the surface stack. `resolve` fulfils the `present()` promise; the
+ * `settled` guard makes resolution idempotent (resolve-once); `generation` is
+ * the per-entry stale-callback guard (carried from `BottomSheetBase`'s
+ * `closeGenerationRef`, keyed per entry id) so a completion callback from a
+ * superseded close cycle can never tear down the wrong state.
+ */
+export interface SurfaceEntry {
+  id: string;
+  render: SurfaceRenderFn;
+  presentation: SurfacePresentation;
+  status: SurfaceStatus;
+  resolve: (result: unknown) => void;
+  settled: boolean;
+  generation: number;
+}
+
+/** Options for the built-in {@link ../surfaces/prompts#confirm} surface. */
+export interface SurfaceConfirmOptions {
+  /** Headline. */
+  title: string;
+  /** Supporting copy. */
+  message?: string;
+  /** Confirm button label. Defaults to `'Confirm'`. */
+  confirmLabel?: string;
+  /** Cancel button label. Defaults to `'Cancel'`. */
+  cancelLabel?: string;
+  /** Style the confirm button as destructive (negative color). */
+  destructive?: boolean;
+  /** Hide the cancel button (a single-action acknowledgement). */
+  hideCancel?: boolean;
+  /**
+   * Backdrop / Escape / back dismiss (resolving `false`). Defaults to `true`;
+   * pass `false` for a blocking confirm that must be answered by a button.
+   */
+  dismissible?: boolean;
+  /** Placement override. Defaults to `'center'`. */
+  placement?: ResponsiveDialogPlacement;
+}
+
+/** Options for the built-in {@link ../surfaces/prompts#prompt} surface. */
+export interface SurfacePromptOptions {
+  /** Headline. */
+  title: string;
+  /** Supporting copy. */
+  message?: string;
+  /** Input placeholder. */
+  placeholder?: string;
+  /** Initial input value. */
+  defaultValue?: string;
+  /** Accessibility label for the input. Defaults to the `title`. */
+  inputLabel?: string;
+  /** Submit button label. Defaults to `'OK'`. */
+  confirmLabel?: string;
+  /** Cancel button label. Defaults to `'Cancel'`. */
+  cancelLabel?: string;
+  /**
+   * Backdrop / Escape / back dismiss (resolving `null`). Defaults to `true`;
+   * pass `false` for a blocking prompt.
+   */
+  dismissible?: boolean;
+  /** Placement override. Defaults to `'center'`. */
+  placement?: ResponsiveDialogPlacement;
+}

package/src/surfaces/useSurface.ts

@@ -0,0 +1,33 @@
+import { createContext, useContext } from 'react';
+
+import type { SurfaceControls } from './types';
+
+/**
+ * Context carrying the CURRENT surface's controls. The host wraps each presented
+ * surface's content in a provider bound to that entry's id, so a nested surface
+ * reads its OWN controls — `dismiss` targets this surface, `present` stacks a
+ * child above it.
+ */
+export const SurfaceContext = createContext<SurfaceControls | null>(null);
+SurfaceContext.displayName = 'BloomSurfaceContext';
+
+/**
+ * Read the current surface's {@link SurfaceControls} from inside a presented
+ * surface. Equivalent to the `surface` argument the render function receives —
+ * use whichever is convenient (props vs. context).
+ *
+ * DEPTH only: `dismiss` (resolve this surface's promise + close) and `present`
+ * (stack a child). Navigation within a surface is the SDK's route layer, not
+ * this hook.
+ *
+ * @throws if called outside a presented surface.
+ */
+export function useSurface(): SurfaceControls {
+  const controls = useContext(SurfaceContext);
+  if (!controls) {
+    throw new Error(
+      'useSurface must be called from within a presented surface (rendered by <SurfaceProvider>/<SurfaceHost>).',
+    );
+  }
+  return controls;
+}