@oxy.so/bloom 4.17.0 → 4.18.1

package/src/dialog/Dialog.tsx

@@ -28,6 +28,7 @@ import Animated, {
 import { BottomSheet, type BottomSheetRef } from '../bottom-sheet';
 import { Backdrop, OverlayRoot } from '../overlay';
 import { useTheme } from '../theme/use-theme';
+import { useIsRtl } from '../hooks/use-is-rtl';
 import { bloomShadowStyle } from '../design-tokens/shadows';
 import { StyledView } from '../styles/styled-primitives';
 import { SurfaceLevelProvider } from '../styles/surface-levels';
@@ -51,6 +52,8 @@ import {
   PANEL_RADIUS,
   SIDE_SHEET_MIN_GUTTER,
   useResolvedPlacement,
+  physicalDialogSide,
+  type DialogSidePlacement,
 } from './placement';
 import type {
   DialogAction,
@@ -137,9 +140,9 @@ function CenteredOrSideDialog({
   containerClassName,
   label,
   children,
-}: Omit<DialogProps, 'placement'> & { placement: 'center' | 'left' | 'right' }) {
+}: Omit<DialogProps, 'placement'> & { placement: 'center' | DialogSidePlacement }) {
   const isControlled = controlledOpen !== undefined;
-  const isSide = placement === 'left' || placement === 'right';
+  const isSide = placement !== 'center';
   const headerController = useDialogHeaderController();
   const scrollableResolved = scrollable ?? true;
   const { height: viewportHeight } = useWindowDimensions();
@@ -422,7 +425,7 @@ function SideSheet({
 }: {
   open: boolean;
   onDismiss: () => void;
-  side: 'left' | 'right';
+  side: DialogSidePlacement;
   width: number;
   inset?: DialogInset;
   dismissOnBackdrop: boolean;
@@ -453,8 +456,16 @@ function SideSheet({
   const insetBottom = inset?.bottom ?? 0;
   const insetLeft = inset?.left ?? 0;
   const insetRight = inset?.right ?? 0;
-  const anchorInset = side === 'left' ? insetLeft : insetRight;
-  const oppositeInset = side === 'left' ? insetRight : insetLeft;
+  // `start`/`end` resolve to the physical edge they land on for everything a
+  // layout engine does not mirror: the slide sign, and which `inset` applies.
+  const rtl = useIsRtl();
+  const edge = physicalDialogSide(side, rtl);
+  // The POSITION of a logical placement is a logical key, resolved by Yoga
+  // against `I18nManager` — a physical `left`/`right` here would be swapped by
+  // React Native's default `swapLeftAndRightInRTL` and land on the wrong edge.
+  const anchorKey = side === 'start' ? 'insetInlineStart' : side === 'end' ? 'insetInlineEnd' : side;
+  const anchorInset = edge === 'left' ? insetLeft : insetRight;
+  const oppositeInset = edge === 'left' ? insetRight : insetLeft;
 
   const sideWidth = useMemo(() => {
     const available = viewportWidth - anchorInset - oppositeInset - SIDE_SHEET_MIN_GUTTER;
@@ -491,7 +502,7 @@ function SideSheet({
     if (dismissOnBackdrop) onDismiss();
   }, [dismissOnBackdrop, onDismiss]);
 
-  const hiddenSign = side === 'left' ? -1 : 1;
+  const hiddenSign = edge === 'left' ? -1 : 1;
   const panelAnimatedStyle = useAnimatedStyle(() => {
     const hidden = 1 - progress.value;
     return {
@@ -513,11 +524,11 @@ function SideSheet({
       ({
         top: insetTop,
         bottom: insetBottom,
-        [side]: anchorInset,
+        [anchorKey]: anchorInset,
         width: sideWidth,
         borderRadius: PANEL_RADIUS,
       }),
-    [insetTop, insetBottom, side, anchorInset, sideWidth],
+    [insetTop, insetBottom, anchorKey, anchorInset, sideWidth],
   );
 
   if (!mounted) return null;
@@ -535,7 +546,15 @@ function SideSheet({
   return (
     // `OverlayRoot` takes this drawer's place in the open-order overlay stack.
     // It mounts here, past the `mounted` guard, so the rank tracks OPENING.
-    <OverlayRoot style={[sideStyles.root, containerStyle]} className={containerClassName}>
+    // `onRequestClose`: the drawer is not an RN `Modal`, so Android back would
+    // otherwise pass straight to the screen behind it. A drawer that refuses
+    // backdrop dismissal still swallows the press, and stays open.
+    <OverlayRoot
+      style={[sideStyles.root, containerStyle]}
+      className={containerClassName}
+      onRequestClose={handleBackdropPress}
+      modal
+    >
       <Backdrop
         testID={testID ? `${testID}-backdrop` : DIALOG_SHEET_BACKDROP_TESTID}
         accessibilityLabel={label ? `Dismiss ${label}` : 'Dismiss dialog'}

package/src/dialog/Dialog.web.tsx

@@ -45,6 +45,7 @@ import { Z_INDEX } from '../styles/z-index';
 import { WEB_POSITION_FIXED, type WebCssStyle } from '../styles/web-view-style';
 import { bloomShadowStyle } from '../design-tokens/shadows';
 import { useTheme } from '../theme/use-theme';
+import { useIsRtl } from '../hooks/use-is-rtl';
 import { Context, useDialogContext, useDialogControl } from './context';
 import { DialogBody } from './DialogContent';
 import { DialogBottomSheet } from './DialogBottomSheet';
@@ -69,6 +70,8 @@ import {
   PANEL_RADIUS,
   SIDE_SHEET_MIN_GUTTER,
   useResolvedPlacement,
+  physicalDialogSide,
+  type DialogSidePlacement,
 } from './placement';
 import type {
   DialogAction,
@@ -196,7 +199,7 @@ function CenterOrSideDialog({
   containerClassName,
   label,
   children,
-}: Omit<DialogProps, 'placement'> & { placement: 'center' | 'left' | 'right' }) {
+}: Omit<DialogProps, 'placement'> & { placement: 'center' | DialogSidePlacement }) {
   // Inject the required @keyframes on mount (before the panel ever appears —
   // this component renders once with `isOpen=false` prior to opening, so the
   // stylesheet is present by the time the animated surface mounts).
@@ -647,7 +650,7 @@ function SheetSurface({
   actions?: DialogAction[];
   header?: DialogProps['header'];
   scrollable?: boolean;
-  placement: 'left' | 'right';
+  placement: DialogSidePlacement;
   shown: boolean;
   width: number;
   inset?: DialogInset;
@@ -666,6 +669,7 @@ function SheetSurface({
   const descriptionId = useId();
   const headerController = useDialogHeaderController();
   const { width: viewportWidth } = useWindowDimensions();
+  const rtl = useIsRtl();
 
   // Defer the entry transition by a frame so the start state paints before the
   // browser animates to `shown`. `entered` is false on the first committed
@@ -707,22 +711,26 @@ function SheetSurface({
     const insetBottom = inset?.bottom ?? 0;
     const insetLeft = inset?.left ?? 0;
     const insetRight = inset?.right ?? 0;
-    const anchorInset = placement === 'left' ? insetLeft : insetRight;
-    const oppositeInset = placement === 'left' ? insetRight : insetLeft;
+    // `start`/`end` land on a physical edge read from `useIsRtl()`. The drawer
+    // is portaled outside any `dir` context, so react-native-web would resolve
+    // a logical key left-to-right; the physical edge is the one that is right.
+    const edge = physicalDialogSide(placement, rtl);
+    const anchorInset = edge === 'left' ? insetLeft : insetRight;
+    const oppositeInset = edge === 'left' ? insetRight : insetLeft;
     const available = viewportWidth - anchorInset - oppositeInset - SIDE_SHEET_MIN_GUTTER;
     const cappedWidth = Math.max(0, Math.min(width, available));
-    const hiddenSign = placement === 'left' ? '-100%' : '100%';
+    const hiddenSign = edge === 'left' ? '-100%' : '100%';
 
     return {
       top: insetTop,
       bottom: insetBottom,
-      [placement]: anchorInset,
+      [edge]: anchorInset,
       width: cappedWidth,
       borderRadius: PANEL_RADIUS,
       transform: [{ translateX: visible ? 0 : hiddenSign }],
       opacity: visible ? 1 : 0,
     };
-  }, [visible, placement, width, inset, viewportWidth]);
+  }, [visible, placement, rtl, width, inset, viewportWidth]);
 
   const handleBackdropPress = useCallback(() => {
     if (dismissOnBackdrop) onDismiss();

package/src/dialog/placement.ts

@@ -7,10 +7,27 @@ import { BREAKPOINTS } from '../styles/breakpoints';
  * Anchor a `<Dialog>` can render against.
  *
  * - `'center'` — the default centered modal card (current behavior).
- * - `'left'` / `'right'` — an anchored side-sheet / drawer.
+ * - `'left'` / `'right'` — an anchored side-sheet / drawer on that PHYSICAL edge.
+ * - `'start'` / `'end'` — the same drawer on the LOGICAL edge: `start` is the
+ *   left in a left-to-right layout and the right in a right-to-left one, and it
+ *   slides in from that edge. Resolved with `useIsRtl()`.
  * - `'bottom'` — a bottom-sheet (drag handle, slide-up).
  */
-export type DialogPlacement = 'center' | 'left' | 'right' | 'bottom';
+export type DialogPlacement = 'center' | 'left' | 'right' | 'start' | 'end' | 'bottom';
+
+/** The four side-sheet placements, physical and logical. */
+export type DialogSidePlacement = 'left' | 'right' | 'start' | 'end';
+
+/**
+ * The PHYSICAL edge a side placement lands on. `left`/`right` are themselves;
+ * `start` is `left` left-to-right and `right` right-to-left, `end` the reverse.
+ * The panel's `translateX` sign, which no layout engine mirrors, follows this.
+ */
+export function physicalDialogSide(side: DialogSidePlacement, rtl: boolean): 'left' | 'right' {
+  if (side === 'start') return rtl ? 'right' : 'left';
+  if (side === 'end') return rtl ? 'left' : 'right';
+  return side;
+}
 
 /**
  * A `<Dialog>` placement that may vary by viewport width.

package/src/dialog/types.ts

@@ -256,8 +256,9 @@ export type DialogProps = React.PropsWithChildren<{
   actions?: DialogAction[];
   /**
    * Surface anchor. Defaults to `'center'` (the centered modal — current
-   * behavior). `'left'`/`'right'` render an anchored side-sheet, `'bottom'` a
-   * bottom-sheet. A responsive map resolves by viewport width, e.g.
+   * behavior). `'left'`/`'right'` render an anchored side-sheet on that
+   * physical edge; `'start'`/`'end'` on the logical edge (mirrored, with its
+   * slide-in, in a right-to-left layout); `'bottom'` a bottom-sheet. A responsive map resolves by viewport width, e.g.
    * `{ base: 'bottom', md: 'left' }` (drawer on wide, sheet on narrow).
    */
   placement?: ResponsiveDialogPlacement;

package/src/loading/Loading.tsx

@@ -18,7 +18,7 @@ import { resolveBloomColors } from '../appearance/colors';
 import { useBloomAppearance } from '../appearance';
 import { animation } from '../styles/tokens';
 import { useTheme } from '../theme/use-theme';
-import { bindLoading, SIZE_CONFIG, styles } from './LoadingBase';
+import { bindLoading, LoadingRoot, SIZE_CONFIG, styles } from './LoadingBase';
 import { SpinnerIcon } from './SpinnerIcon';
 import type { TopLoadingProps } from './types';
 
@@ -31,6 +31,7 @@ const TopLoading: React.FC<TopLoadingProps> = ({
   iconSize,
   heightOffset = 0,
   spinnerIcon,
+  accessibilityLabel,
   testID,
 }) => {
   const theme = useTheme();
@@ -69,7 +70,10 @@ const TopLoading: React.FC<TopLoadingProps> = ({
   return (
     <Animated.View style={[styles.topContainer, containerAnimated]} testID={testID}>
       <Animated.View style={[styles.topLoadingView, { height: targetHeight }, innerAnimated, style]}>
-        {spinnerIcon ?? <SpinnerIcon size={effectiveIconSize} color={spinnerColor} />}
+        {/* Named only while it is showing: a collapsed bar is not a wait. */}
+        <LoadingRoot accessibilityLabel={showLoading ? accessibilityLabel : undefined}>
+          {spinnerIcon ?? <SpinnerIcon size={effectiveIconSize} color={spinnerColor} />}
+        </LoadingRoot>
       </Animated.View>
     </Animated.View>
   );

package/src/loading/Loading.web.tsx

@@ -16,7 +16,7 @@ import { useBloomAppearance } from '../appearance';
 import { animation } from '../styles/tokens';
 import type { WebCssStyle } from '../styles/web-view-style';
 import { useTheme } from '../theme/use-theme';
-import { bindLoading, SIZE_CONFIG, styles } from './LoadingBase';
+import { bindLoading, LoadingRoot, SIZE_CONFIG, styles } from './LoadingBase';
 import { SpinnerIcon } from './SpinnerIcon.web';
 import type { TopLoadingProps } from './types';
 
@@ -41,6 +41,7 @@ const TopLoading: React.FC<TopLoadingProps> = ({
   iconSize,
   heightOffset = 0,
   spinnerIcon,
+  accessibilityLabel,
   testID,
 }) => {
   const theme = useTheme();
@@ -84,7 +85,10 @@ const TopLoading: React.FC<TopLoadingProps> = ({
           style,
         ]}
       >
-        {spinnerIcon ?? <SpinnerIcon size={effectiveIconSize} color={spinnerColor} />}
+        {/* Named only while it is showing: a collapsed bar is not a wait. */}
+        <LoadingRoot accessibilityLabel={showLoading ? accessibilityLabel : undefined}>
+          {spinnerIcon ?? <SpinnerIcon size={effectiveIconSize} color={spinnerColor} />}
+        </LoadingRoot>
       </View>
     </View>
   );

package/src/loading/LoadingBase.tsx

@@ -23,7 +23,7 @@ import { normalizeBloomSize } from '../appearance/legacy';
 import { resolveBloomColors } from '../appearance/colors';
 import { useBloomAppearance } from '../appearance';
 import React, { memo } from 'react';
-import { View, Text, StyleSheet } from 'react-native';
+import { View, Text, StyleSheet, type StyleProp, type ViewStyle } from 'react-native';
 
 import { useTheme } from '../theme/use-theme';
 import type {
@@ -41,6 +41,54 @@ export const SIZE_CONFIG = {
   lg: { spinner: 44, text: 16 },
 } as const;
 
+/**
+ * The indicator's root: an indeterminate, NAMED `progressbar` when the caller
+ * gave `accessibilityLabel`, a plain view (today's behaviour) when not.
+ *
+ * Flat `aria-*` because react-native-web drops `accessibilityState` /
+ * `accessibilityValue`; React Native folds them back. `aria-valuenow` is
+ * deliberately absent (`undefined`): that is what makes a progressbar
+ * INDETERMINATE in ARIA, and a spinner has no amount done to report. The role
+ * is a literal on its own branch so `aria-state-source-census.test.ts` can read
+ * it; a computed role would be invisible to it.
+ */
+export function LoadingRoot({
+  accessibilityLabel,
+  style,
+  testID,
+  children,
+}: {
+  accessibilityLabel?: string;
+  style?: StyleProp<ViewStyle>;
+  testID?: string;
+  children: React.ReactNode;
+}) {
+  if (accessibilityLabel) {
+    return (
+      <View
+        role="progressbar"
+        accessible
+        accessibilityLabel={accessibilityLabel}
+        aria-valuemin={0}
+        aria-valuemax={100}
+        aria-valuenow={undefined}
+        aria-busy
+        style={style}
+        testID={testID}
+      >
+        {children}
+      </View>
+    );
+  }
+  // Nothing to carry (the `top` variant's inner slot): no extra node at all.
+  if (style === undefined && testID === undefined) return <>{children}</>;
+  return (
+    <View style={style} testID={testID}>
+      {children}
+    </View>
+  );
+}
+
 /** The two platform pieces a fork supplies. */
 export interface LoadingPlatform {
   /** Forked: react-native-svg on native, a DOM `<svg>` on web. */
@@ -61,6 +109,7 @@ export function bindLoading({ SpinnerIcon, TopLoading }: LoadingPlatform) {
     showText = true,
     iconSize,
     spinnerIcon,
+    accessibilityLabel,
     testID,
   }) => {
     const theme = useTheme();
@@ -71,7 +120,7 @@ export function bindLoading({ SpinnerIcon, TopLoading }: LoadingPlatform) {
     const textColor = color ?? theme.colors.textSecondary;
 
     return (
-      <View style={[styles.container, style]} testID={testID}>
+      <LoadingRoot accessibilityLabel={accessibilityLabel} style={[styles.container, style]} testID={testID}>
         {spinnerIcon ?? <SpinnerIcon size={effectiveIconSize} color={spinnerColor} className={className} />}
         {showText && text && (
           <Text
@@ -84,7 +133,7 @@ export function bindLoading({ SpinnerIcon, TopLoading }: LoadingPlatform) {
             {text}
           </Text>
         )}
-      </View>
+      </LoadingRoot>
     );
   };
 
@@ -96,6 +145,7 @@ export function bindLoading({ SpinnerIcon, TopLoading }: LoadingPlatform) {
     style,
     textStyle,
     spinnerIcon,
+    accessibilityLabel,
     testID,
   }) => {
     const theme = useTheme();
@@ -105,7 +155,7 @@ export function bindLoading({ SpinnerIcon, TopLoading }: LoadingPlatform) {
     const textColor = theme.colors.textSecondary;
 
     return (
-      <View style={[styles.inlineContainer, style]} testID={testID}>
+      <LoadingRoot accessibilityLabel={accessibilityLabel} style={[styles.inlineContainer, style]} testID={testID}>
         {spinnerIcon ?? <SpinnerIcon size={sizeConfig.spinner} color={spinnerColor} />}
         {text && (
           <Text
@@ -117,7 +167,7 @@ export function bindLoading({ SpinnerIcon, TopLoading }: LoadingPlatform) {
             {text}
           </Text>
         )}
-      </View>
+      </LoadingRoot>
     );
   };
 

package/src/loading/types.ts

@@ -20,6 +20,17 @@ interface BaseLoadingProps {
   style?: ViewStyle;
   /** Whether loading is active (for animated variants) */
   showLoading?: boolean;
+  /**
+   * Names the indicator and makes it an indeterminate `progressbar` to
+   * assistive technology (`role="progressbar"` with `aria-label` and
+   * `aria-busy` on web; the same role, label and busy state natively). A
+   * spinner draws no words, so nothing else can say what is loading.
+   *
+   * Opt-in: without it the indicator carries no role, as before — which is
+   * right when it sits INSIDE a named progressbar already (an upload overlay),
+   * where a second one would announce the same wait twice.
+   */
+  accessibilityLabel?: string;
   testID?: string;
 }
 

package/src/location-puck/LocationPuck.tsx

@@ -81,7 +81,7 @@ const PULSE_SCALE = 0.18;
 
 /** One full-size layer that centres whatever it holds on the box's centre. */
 const layerStyle: ViewStyle = {
-  ...StyleSheet.absoluteFillObject,
+  ...StyleSheet.absoluteFill,
   alignItems: 'center',
   justifyContent: 'center',
 };

package/src/mail-list/parts.tsx

@@ -77,7 +77,7 @@ export function MailRowLink({
   };
   const interactive = Boolean(onPress || href || onLongPress);
   const style: WebCssStyle = {
-    ...StyleSheet.absoluteFillObject,
+    ...StyleSheet.absoluteFill,
     borderRadius: MAIL_ROW_RADIUS,
     '--bloom-mail-ring': paint.accent,
   };

package/src/media-card/parts.tsx

@@ -287,7 +287,7 @@ export function CardLink({ name, onPress, href, onLongPress, selected = false, r
     if (!IS_WEB && href) void Linking.openURL(href).catch(() => undefined);
   };
   const style: WebCssStyle = {
-    ...StyleSheet.absoluteFillObject,
+    ...StyleSheet.absoluteFill,
     borderRadius: radius,
     '--bloom-media-card-ring': paint.ring,
   };

package/src/overlay/Overlay.tsx

@@ -57,6 +57,7 @@ import { WEB_POSITION_FIXED } from '../styles/web-view-style';
 import { StyledView } from '../styles/styled-primitives';
 import { SurfaceLevelProvider } from '../styles/surface-levels';
 import { layerForRank, type OverlayLayer } from './stack';
+import { useHardwareBack } from './use-hardware-back';
 import { useOverlayLayer } from './use-overlay-layer';
 import type { OverlayRootProps, BackdropProps } from './types';
 
@@ -109,32 +110,43 @@ export const BACKDROP_DIM_OPACITY = 0.28;
  * every Bloom surface already puts it. Descendants that need to order
  * themselves within the surface read `useOverlayLayerContext()`.
  */
-export function OverlayRoot({ children, className, style, testID, zIndex }: OverlayRootProps) {
+export function OverlayRoot({
+  children,
+  className,
+  style,
+  testID,
+  zIndex,
+  onRequestClose,
+  modal = false,
+}: OverlayRootProps) {
+  // On the root rather than in each surface: every portaled surface mounts one
+  // inside its open guard, so this is the one place that cannot be forgotten.
+  // The gallery once forgot it and Android back finished the whole activity.
+  useHardwareBack(onRequestClose);
   // Split into two components rather than branching on the hook: a pinned root
   // must not CONSUME a rank either. The toast host is pinned and mounts for the
   // whole life of the app, so holding a rank would keep the live set permanently
   // non-empty — the counter would never reset and depths would climb for the
   // rest of the session.
   return zIndex === undefined ? (
-    <StackedOverlayRoot className={className} style={style} testID={testID}>
+    <StackedOverlayRoot className={className} style={style} testID={testID} modal={modal}>
       {children}
     </StackedOverlayRoot>
   ) : (
-    <PinnedOverlayRoot zIndex={zIndex} className={className} style={style} testID={testID}>
+    <PinnedOverlayRoot zIndex={zIndex} className={className} style={style} testID={testID} modal={modal}>
       {children}
     </PinnedOverlayRoot>
   );
 }
 
-function StackedOverlayRoot({
-  children,
-  className,
-  style,
-  testID,
-}: Omit<OverlayRootProps, 'zIndex'>) {
+type OverlayRootViewProps = Pick<OverlayRootProps, 'children' | 'className' | 'style' | 'testID'> & {
+  modal: boolean;
+};
+
+function StackedOverlayRoot({ children, className, style, testID, modal }: OverlayRootViewProps) {
   const layer = useOverlayLayer();
   return (
-    <OverlayRootView layer={layer} className={className} style={style} testID={testID}>
+    <OverlayRootView layer={layer} className={className} style={style} testID={testID} modal={modal}>
       {children}
     </OverlayRootView>
   );
@@ -146,7 +158,8 @@ function PinnedOverlayRoot({
   style,
   testID,
   zIndex,
-}: OverlayRootProps & { zIndex: number }) {
+  modal,
+}: OverlayRootViewProps & { zIndex: number }) {
   // Outside the stack, so descendants must not read stack depths from it
   // either — every slot is the pinned depth.
   const layer = useMemo(
@@ -154,7 +167,7 @@ function PinnedOverlayRoot({
     [zIndex],
   );
   return (
-    <OverlayRootView layer={layer} className={className} style={style} testID={testID}>
+    <OverlayRootView layer={layer} className={className} style={style} testID={testID} modal={modal}>
       {children}
     </OverlayRootView>
   );
@@ -166,14 +179,19 @@ function OverlayRootView({
   style,
   testID,
   layer,
-}: Omit<OverlayRootProps, 'zIndex'> & { layer: OverlayLayer }) {
+  modal,
+}: OverlayRootViewProps & { layer: OverlayLayer }) {
   return (
     <OverlayLayerContext.Provider value={layer}>
       {/* `pointerEvents` stays a PROP: react-native-web resolves the RN-only
           `box-none` from the prop path only, and as a style entry it is silently
-          dropped — which makes the whole portaled surface click-through. */}
+          dropped — which makes the whole portaled surface click-through.
+          `accessibilityViewIsModal` sits HERE, not on the panel: iOS hides only
+          the modal view's SIBLINGS, and at the native outlet this root is the
+          sibling of the app content, where the panel is not. */}
       <StyledView
         pointerEvents="box-none"
+        accessibilityViewIsModal={modal && Platform.OS !== 'web' ? true : undefined}
         className={className}
         style={[styles.root, { zIndex: layer.root }, style]}
         testID={testID}

package/src/overlay/types.ts

@@ -23,6 +23,24 @@ export interface OverlayRootProps {
    * `./stack.ts` exists to remove.
    */
   zIndex?: number;
+  /**
+   * Android hardware back while this surface is open. A portaled surface is not
+   * an RN `Modal`, so nothing else consumes the press: without this the app's
+   * own back handling runs and, at the root of a stack, finishes the activity —
+   * the surface "closes" by closing the whole app. Called and consumed while the
+   * root is mounted; later-opened surfaces register later, and `BackHandler`
+   * runs the newest listener first, so the top surface closes first. A blocking
+   * surface still passes a handler (a no-op) so the press is swallowed rather
+   * than falling through to the screen underneath.
+   */
+  onRequestClose?: () => void;
+  /**
+   * The surface is modal: a screen reader must not wander into the app behind
+   * it. Native only — sets `accessibilityViewIsModal` on this root, which is the
+   * app content's sibling at the portal outlet (iOS confines VoiceOver to
+   * it). Web surfaces already carry `aria-modal` on their own dialog node.
+   */
+  modal?: boolean;
 }
 
 export interface BackdropProps {

package/src/overlay/use-hardware-back.ts

@@ -0,0 +1,27 @@
+import { useEffect, useRef } from 'react';
+import { BackHandler, Platform } from 'react-native';
+
+/**
+ * Consume Android's hardware back for as long as the caller is mounted with a
+ * handler, calling the CURRENT `onBack` (read through a ref, so a new closure
+ * each render does not re-register and lose its place in the LIFO order).
+ *
+ * `BackHandler` runs the newest listener first, so surfaces opened later close
+ * first. No-op off Android and when `BackHandler` is absent (web bundles, and
+ * some test environments' react-native mocks).
+ */
+export function useHardwareBack(onBack: (() => void) | undefined): void {
+  const onBackRef = useRef(onBack);
+  onBackRef.current = onBack;
+  const active = onBack !== undefined;
+
+  useEffect(() => {
+    if (!active || Platform.OS !== 'android') return;
+    if (typeof BackHandler?.addEventListener !== 'function') return;
+    const subscription = BackHandler.addEventListener('hardwareBackPress', () => {
+      onBackRef.current?.();
+      return true;
+    });
+    return () => subscription.remove();
+  }, [active]);
+}

package/src/price-breakdown/PriceSummary.tsx

@@ -82,6 +82,7 @@ function PriceSummaryComponent({
               label={line.label}
               sublabel={line.sublabel}
               amount={line.amount}
+              secondaryAmount={line.secondaryAmount}
               tone={line.tone}
               state={line.state}
               info={line.info}
@@ -137,6 +138,15 @@ function PriceSummaryComponent({
               >
                 {total.amount ?? pendingPlaceholder}
               </Text>
+              {total.secondaryAmount ? (
+                <Text
+                  variant="body-2-regular"
+                  testID={testID ? `${testID}-total-secondary-amount` : undefined}
+                  style={{ color: paint.textSecondary, fontVariant: ['tabular-nums'], textAlign: 'right' }}
+                >
+                  {total.secondaryAmount}
+                </Text>
+              ) : null}
               {totalCaveat ? (
                 <Text
                   variant="caption-1-regular"

package/src/price-breakdown/PriceSummaryLine.tsx

@@ -27,6 +27,8 @@ import type { PriceSummaryLineProps } from './types';
  *   state     "Estimated" / "Pending" in caption-1 under the amount, so the
  *             caveat travels with the NUMBER rather than with the label; the
  *             row keeps its own reading order for a screen reader
+ *   secondary `secondaryAmount` (a second currency) in body-2-regular
+ *             secondary under the amount, tabular, right-aligned
  *   info      a 32 round glyph after the label, opening a `Popover`
  *   height    32 minimum, whether or not the line has the info affordance
  *
@@ -38,6 +40,7 @@ function PriceSummaryLineComponent({
   label,
   sublabel,
   amount,
+  secondaryAmount,
   tone = 'default',
   state = 'final',
   info,
@@ -120,6 +123,15 @@ function PriceSummaryLineComponent({
         >
           {amount ?? pendingPlaceholder}
         </Text>
+        {secondaryAmount ? (
+          <Text
+            variant="body-2-regular"
+            testID={testID ? `${testID}-secondary-amount` : undefined}
+            style={{ color: paint.textSecondary, fontVariant: ['tabular-nums'], textAlign: 'right' }}
+          >
+            {secondaryAmount}
+          </Text>
+        ) : null}
         {caveat ? (
           <Text
             variant="caption-1-regular"