From af3e38710f9c045bd5229000fe1a94a8724dd349 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Wed, 5 Aug 2026 13:07:35 +0200
Subject: [PATCH] feat!: close part of the stack, not only all of it
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

closeAll() could only empty a group, so a sheet deep in a stack had no way to
say "close what is above me" or "close three". Both were expressible from the
store already — stackOrderByGroup is ordered and a sheet knows its own id — so
this is an API gap, not a missing capability.

  closeTo(id)        close down to a sheet, leaving it open
  closeDepth(n)      close n sheets from the top
  closeAbove()       from useBottomSheetContext: everything above me

All three route through closeAllAnimated with a resolved range, so stagger,
onBeforeClose interception and stoppedAt reporting behave exactly as before.
Passing both bounds takes whichever closes fewer sheets, so neither can widen
the other. An `until` naming a sheet outside the group closes nothing — for a
bounded call, silently emptying the stack is the worst possible fallback.

BREAKING: CloseAllResult.closedAll is now .completed. Bounded by until/depth it
means "closed the requested range", which the old name contradicted.
CloseAllOptions is replaced by CascadeOptions, exported from the store.

11 tests cover the boundaries: depth 0 and negative, depth past the stack, an
until that is the top sheet, an until that is absent, both bounds fighting in
either direction, and an interceptor stopping a bounded cascade.
---
 example/src/screens/HomeScreen.tsx        |   9 ++
 example/src/sheets/PartialCloseSheets.tsx | 158 ++++++++++++++++++++++
 example/src/sheets/index.ts               |   1 +
 src/__tests__/coordinator.test.ts         | 141 ++++++++++++++++++-
 src/bottomSheetCoordinator.ts             |  51 ++++++-
 src/index.tsx                             |   2 +-
 src/store/types.ts                        |  29 +++-
 src/useBottomSheetContext.ts              |  24 +++-
 src/useBottomSheetControl.ts              |   7 +-
 src/useBottomSheetManager.tsx             |  51 +++++--
 10 files changed, 443 insertions(+), 30 deletions(-)
 create mode 100644 example/src/sheets/PartialCloseSheets.tsx

diff --git a/example/src/screens/HomeScreen.tsx b/example/src/screens/HomeScreen.tsx
index 670e5ae..e2bc2dc 100644
--- a/example/src/screens/HomeScreen.tsx
+++ b/example/src/screens/HomeScreen.tsx
@@ -26,6 +26,7 @@ import {
 } from '../sheets';
 import { colors, sharedStyles } from '../styles/theme';
 import { CloseInterceptionDemo } from '../sheets/CloseInterceptionSheets';
+import { PartialCloseDemo } from '../sheets/PartialCloseSheets';
 
 export function HomeScreen() {
   const { top } = useSafeAreaInsets();
@@ -167,6 +168,14 @@ export function HomeScreen() {
               persistentWithPortalControl.open({ scaleBackground: true })
             }
           />
+          <DemoCard
+            title="Partial Close"
+            description="closeTo / closeDepth / closeAbove and every edge case"
+            color={colors.cyan}
+            onPress={() =>
+              open(<PartialCloseDemo />, { scaleBackground: true })
+            }
+          />
           <DemoCard
             title="Close Interception"
             description="onBeforeClose interceptors and closeAll() with cascade animation"
diff --git a/example/src/sheets/PartialCloseSheets.tsx b/example/src/sheets/PartialCloseSheets.tsx
new file mode 100644
index 0000000..ca0a54c
--- /dev/null
+++ b/example/src/sheets/PartialCloseSheets.tsx
@@ -0,0 +1,158 @@
+import type { BottomSheetMethods } from '@gorhom/bottom-sheet/lib/typescript/types';
+import { forwardRef, useState } from 'react';
+import { StyleSheet, Switch, Text, View } from 'react-native';
+import {
+  useBottomSheetContext,
+  useBottomSheetManager,
+  useOnBeforeClose,
+  type CloseAllResult,
+} from 'react-native-bottom-sheet-stack';
+
+import { Badge, Button, SecondaryButton, Sheet } from '../components';
+import { colors, sharedStyles } from '../styles/theme';
+
+/**
+ * Every bounded-cascade case in one stack.
+ *
+ * Each level knows its own depth and the ID of the bottom one, so an outcome is
+ * readable off the screen: close down to level 1 and everything above it goes
+ * while level 1 stays. The result of the last call is printed at the level that
+ * made it — the point is to see `completed` and `stoppedAt`, not just the
+ * animation.
+ */
+
+function formatResult(result: CloseAllResult): string {
+  const closed = result.closed.length ? result.closed.join(', ') : '(none)';
+  const stopped = result.stoppedAt ? `\nstoppedAt: ${result.stoppedAt}` : '';
+  return `completed: ${result.completed}\nclosed: [${closed}]${stopped}`;
+}
+
+export const PartialCloseDemo = forwardRef<BottomSheetMethods>((_, ref) => (
+  <PartialCloseLevel ref={ref} level={1} />
+));
+
+interface LevelProps {
+  level: number;
+  /** ID of level 1, threaded down so deeper levels can aim `closeTo` at it. */
+  rootId?: string;
+}
+
+const PartialCloseLevel = forwardRef<BottomSheetMethods, LevelProps>(
+  ({ level, rootId }, ref) => {
+    const { open, closeAll, closeTo, closeDepth } = useBottomSheetManager();
+    const { id, close, closeAbove } = useBottomSheetContext();
+
+    const [lastResult, setLastResult] = useState('no call yet');
+    const [inclusive, setInclusive] = useState(false);
+    const [blocking, setBlocking] = useState(false);
+
+    // Lets a level refuse, so a cascade can be stopped mid-way and `stoppedAt`
+    // observed rather than taken on faith.
+    useOnBeforeClose(({ onCancel, onConfirm }) =>
+      blocking ? onCancel() : onConfirm()
+    );
+
+    const target = rootId ?? id;
+
+    const report = async (call: Promise<CloseAllResult>) =>
+      setLastResult(formatResult(await call));
+
+    const pushLevel = () =>
+      open(<PartialCloseLevel level={level + 1} rootId={target} />, {
+        mode: 'push',
+        scaleBackground: true,
+      });
+
+    return (
+      <Sheet ref={ref}>
+        <View style={styles.badges}>
+          <Badge label={`level ${level}`} color={colors.primary} />
+          {blocking ? <Badge label="blocking" color={colors.warning} /> : null}
+        </View>
+
+        <Text style={sharedStyles.h1}>Partial close · level {level}</Text>
+        <Text style={sharedStyles.text}>
+          Push a few levels, then close part of the stack.
+        </Text>
+
+        <View style={sharedStyles.contextBox}>
+          <Text style={sharedStyles.contextTitle}>LAST RESULT</Text>
+          <Text style={sharedStyles.contextValue}>{lastResult}</Text>
+        </View>
+
+        <View style={styles.toggle}>
+          <Text style={sharedStyles.text}>Refuse to close (interceptor)</Text>
+          <Switch value={blocking} onValueChange={setBlocking} />
+        </View>
+        <View style={styles.toggle}>
+          <Text style={sharedStyles.text}>inclusive</Text>
+          <Switch value={inclusive} onValueChange={setInclusive} />
+        </View>
+
+        <Button title="Push next level" onPress={pushLevel} />
+
+        <Text style={sharedStyles.contextTitle}>FROM INSIDE THIS SHEET</Text>
+        <Button
+          title="closeAbove() — everything above me"
+          onPress={() => report(closeAbove({ stagger: 120, inclusive }))}
+        />
+
+        <Text style={sharedStyles.contextTitle}>BOUNDED BY ID</Text>
+        <Button
+          title="closeTo(level 1)"
+          onPress={() => report(closeTo(target, { stagger: 120, inclusive }))}
+        />
+        <Button
+          title="closeTo('missing') — unknown id closes nothing"
+          onPress={() => report(closeTo('missing', { stagger: 120 }))}
+        />
+
+        <Text style={sharedStyles.contextTitle}>BOUNDED BY COUNT</Text>
+        <Button
+          title="closeDepth(1)"
+          onPress={() => report(closeDepth(1, { stagger: 120 }))}
+        />
+        <Button
+          title="closeDepth(3)"
+          onPress={() => report(closeDepth(3, { stagger: 120 }))}
+        />
+        <Button
+          title="closeDepth(0) — closes nothing"
+          onPress={() => report(closeDepth(0, { stagger: 120 }))}
+        />
+        <Button
+          title="closeDepth(99) — clamps to the stack"
+          onPress={() => report(closeDepth(99, { stagger: 120 }))}
+        />
+
+        <Text style={sharedStyles.contextTitle}>BOTH BOUNDS</Text>
+        <Button
+          title="until level 1 + depth 1 — narrower wins"
+          onPress={() =>
+            report(closeAll({ stagger: 120, until: target, depth: 1 }))
+          }
+        />
+
+        <SecondaryButton
+          title="closeAll()"
+          onPress={() => report(closeAll({ stagger: 120 }))}
+        />
+        <SecondaryButton title="Close this one" onPress={close} />
+      </Sheet>
+    );
+  }
+);
+
+const styles = StyleSheet.create({
+  badges: {
+    flexDirection: 'row',
+    gap: 8,
+    marginBottom: 8,
+  },
+  toggle: {
+    flexDirection: 'row',
+    alignItems: 'center',
+    justifyContent: 'space-between',
+    paddingVertical: 6,
+  },
+});
diff --git a/example/src/sheets/index.ts b/example/src/sheets/index.ts
index 1805071..0e439fd 100644
--- a/example/src/sheets/index.ts
+++ b/example/src/sheets/index.ts
@@ -28,3 +28,4 @@ export {
   FormSheet,
   ReadOnlySheet,
 } from './CloseInterceptionSheets';
+export { PartialCloseDemo } from './PartialCloseSheets';
diff --git a/src/__tests__/coordinator.test.ts b/src/__tests__/coordinator.test.ts
index 53d1970..3822a1c 100644
--- a/src/__tests__/coordinator.test.ts
+++ b/src/__tests__/coordinator.test.ts
@@ -104,7 +104,7 @@ describe('closeAllAnimated', () => {
 
     const result = await closeAllAnimated('g1', { stagger: 0 });
 
-    expect(result).toEqual({ closedAll: true, closed: ['c', 'b', 'a'] });
+    expect(result).toEqual({ completed: true, closed: ['c', 'b', 'a'] });
     expect(statusOf('a')).toBe('closing');
     expect(statusOf('c')).toBe('closing');
   });
@@ -118,7 +118,7 @@ describe('closeAllAnimated', () => {
     const result = await closeAllAnimated('g1', { stagger: 0 });
 
     expect(result).toEqual({
-      closedAll: false,
+      completed: false,
       closed: ['c'],
       stoppedAt: 'b',
     });
@@ -127,6 +127,139 @@ describe('closeAllAnimated', () => {
     expect(statusOf('b')).toBe('open');
   });
 
+  describe('bounded cascades', () => {
+    it('closes down to `until`, leaving it and everything below open', async () => {
+      openAndSettle('a');
+      openAndSettle('b');
+      openAndSettle('c');
+
+      const result = await closeAllAnimated('g1', { stagger: 0, until: 'b' });
+
+      expect(result).toEqual({ completed: true, closed: ['c'] });
+      expect(statusOf('b')).toBe('open');
+      expect(statusOf('a')).toBe('open');
+    });
+
+    it('closes `until` itself when inclusive', async () => {
+      openAndSettle('a');
+      openAndSettle('b');
+      openAndSettle('c');
+
+      const result = await closeAllAnimated('g1', {
+        stagger: 0,
+        until: 'b',
+        inclusive: true,
+      });
+
+      expect(result).toEqual({ completed: true, closed: ['c', 'b'] });
+      expect(statusOf('a')).toBe('open');
+    });
+
+    it('closes nothing when `until` is the topmost sheet', async () => {
+      openAndSettle('a');
+      openAndSettle('b');
+
+      const result = await closeAllAnimated('g1', { stagger: 0, until: 'b' });
+
+      expect(result).toEqual({ completed: true, closed: [] });
+      expect(statusOf('b')).toBe('open');
+    });
+
+    // A bounded call that silently emptied the group would be the opposite of
+    // what it asked for — far worse than doing nothing.
+    it('closes nothing when `until` is not on the stack', async () => {
+      openAndSettle('a');
+      openAndSettle('b');
+
+      const result = await closeAllAnimated('g1', {
+        stagger: 0,
+        until: 'nope',
+      });
+
+      expect(result).toEqual({ completed: true, closed: [] });
+      expect(statusOf('a')).toBe('open');
+      expect(statusOf('b')).toBe('open');
+    });
+
+    it('closes `depth` sheets from the top', async () => {
+      openAndSettle('a');
+      openAndSettle('b');
+      openAndSettle('c');
+
+      const result = await closeAllAnimated('g1', { stagger: 0, depth: 2 });
+
+      expect(result).toEqual({ completed: true, closed: ['c', 'b'] });
+      expect(statusOf('a')).toBe('open');
+    });
+
+    it('empties the group when `depth` exceeds the stack', async () => {
+      openAndSettle('a');
+      openAndSettle('b');
+
+      const result = await closeAllAnimated('g1', { stagger: 0, depth: 99 });
+
+      expect(result).toEqual({ completed: true, closed: ['b', 'a'] });
+    });
+
+    it.each([0, -1])('closes nothing at depth %i', async (depth) => {
+      openAndSettle('a');
+      openAndSettle('b');
+
+      const result = await closeAllAnimated('g1', { stagger: 0, depth });
+
+      expect(result).toEqual({ completed: true, closed: [] });
+      expect(statusOf('b')).toBe('open');
+    });
+
+    // Neither bound may widen the other, so the narrower one has to win in
+    // both directions.
+    it('takes the narrower bound when depth is the tighter one', async () => {
+      openAndSettle('a');
+      openAndSettle('b');
+      openAndSettle('c');
+
+      const result = await closeAllAnimated('g1', {
+        stagger: 0,
+        until: 'a',
+        depth: 1,
+      });
+
+      expect(result).toEqual({ completed: true, closed: ['c'] });
+      expect(statusOf('b')).toBe('open');
+    });
+
+    it('takes the narrower bound when until is the tighter one', async () => {
+      openAndSettle('a');
+      openAndSettle('b');
+      openAndSettle('c');
+
+      const result = await closeAllAnimated('g1', {
+        stagger: 0,
+        until: 'b',
+        depth: 99,
+      });
+
+      expect(result).toEqual({ completed: true, closed: ['c'] });
+      expect(statusOf('b')).toBe('open');
+    });
+
+    it('reports the interceptor that stopped a bounded cascade', async () => {
+      openAndSettle('a');
+      openAndSettle('b');
+      openAndSettle('c');
+      setOnBeforeClose('c', ({ onCancel }) => onCancel());
+
+      const result = await closeAllAnimated('g1', { stagger: 0, depth: 2 });
+
+      expect(result).toEqual({
+        completed: false,
+        closed: [],
+        stoppedAt: 'c',
+      });
+      expect(statusOf('b')).toBe('open');
+    });
+  });
+
   // Regression: 'nothing to close' used to break the loop like a refusal,
   // stranding every sheet underneath one that had already settled.
   it('keeps going past a sheet that has nothing to close', async () => {
@@ -141,7 +274,7 @@ describe('closeAllAnimated', () => {
 
     const result = await closeAllAnimated('g1', { stagger: 0 });
 
-    expect(result.closedAll).toBe(true);
+    expect(result.completed).toBe(true);
     // 'b' is skipped rather than treated as a refusal, so 'a' below it still
     // gets closed.
     expect(result.closed).toEqual(['c', 'a']);
@@ -160,7 +293,7 @@ describe('closeAllAnimated', () => {
 
   it('is a no-op for an empty group', async () => {
     await expect(closeAllAnimated('nothing', { stagger: 0 })).resolves.toEqual({
-      closedAll: true,
+      completed: true,
       closed: [],
     });
   });
diff --git a/src/bottomSheetCoordinator.ts b/src/bottomSheetCoordinator.ts
index 40128ed..a9e9e33 100644
--- a/src/bottomSheetCoordinator.ts
+++ b/src/bottomSheetCoordinator.ts
@@ -1,6 +1,6 @@
 import type { SheetAdapterEvents } from './adapter.types';
 import { useBottomSheetStore } from './store';
-import type { CloseAllResult, CloseResult } from './store';
+import type { CascadeOptions, CloseAllResult, CloseResult } from './store';
 import { getOnBeforeClose } from './onBeforeCloseRegistry';
 import { getSheetRef } from './refsMap';
 
@@ -169,6 +169,40 @@ export async function requestClose(sheetId: string): Promise<CloseResult> {
   return { closed: false, reason: 'not-closable' };
 }
 
+/**
+ * The slice of `stack` a cascade should close, in bottom-to-top order.
+ *
+ * Both bounds only move the start later, so a `depth` cannot reach past an
+ * `until` and vice versa — whichever closes fewer sheets holds.
+ */
+function resolveCascadeRange(
+  stack: string[],
+  options?: CascadeOptions
+): string[] {
+  let from = 0;
+
+  if (options?.until !== undefined) {
+    const index = stack.indexOf(options.until);
+    if (index === -1) {
+      // Closing the whole group would be the opposite of what a bounded call
+      // asked for, so an unknown boundary closes nothing.
+      if (__DEV__) {
+        console.warn(
+          `[BottomSheetStack] closeAll: "${options.until}" is not on this group's stack — closing nothing.`
+        );
+      }
+      return [];
+    }
+    from = options.inclusive ? index : index + 1;
+  }
+
+  if (options?.depth !== undefined) {
+    from = Math.max(from, stack.length - Math.max(0, options.depth));
+  }
+
+  return stack.slice(from);
+}
+
 /**
  * Default stagger delay between cascading close animations (ms).
  */
@@ -183,21 +217,28 @@ const DEFAULT_STAGGER_MS = 100;
  * If a sheet has an `onBeforeClose` interceptor that rejects, the cascade
  * stops at that sheet — sheets below it remain open.
  *
+ * `until` and `depth` narrow the cascade to part of the stack; with both, the
+ * one that closes fewer sheets wins, so neither can be widened past the other.
+ *
  * @param groupId - The manager group to close sheets in.
  * @param options.stagger - Delay in ms between each close (default: 100).
+ * @param options.until - Stop at this sheet instead of emptying the group.
+ * @param options.inclusive - Whether `until` closes too (default: false).
+ * @param options.depth - Close at most this many sheets, counting from the top.
  * @returns A {@link CloseAllResult} naming what closed and, if the cascade was
  * stopped, which sheet stopped it. Without this a blocked cascade is
  * indistinguishable from one that closed everything.
  */
 export async function closeAllAnimated(
   groupId: string,
-  options?: { stagger?: number }
+  options?: CascadeOptions
 ): Promise<CloseAllResult> {
   const stagger = options?.stagger ?? DEFAULT_STAGGER_MS;
 
   const state = useBottomSheetStore.getState();
 
-  const reversed = [...(state.stackOrderByGroup[groupId] ?? [])].reverse();
+  const stack = state.stackOrderByGroup[groupId] ?? [];
+  const reversed = resolveCascadeRange(stack, options).reverse();
   const closed: string[] = [];
 
   for (const [index, sheetId] of reversed.entries()) {
@@ -218,7 +259,7 @@ export async function closeAllAnimated(
         continue;
       }
       // An interceptor declined — stop and report where.
-      return { closedAll: false, closed, stoppedAt: sheetId };
+      return { completed: false, closed, stoppedAt: sheetId };
     }
 
     closed.push(sheetId);
@@ -228,7 +269,7 @@ export async function closeAllAnimated(
     }
   }
 
-  return { closedAll: true, closed };
+  return { completed: true, closed };
 }
 
 /**
diff --git a/src/index.tsx b/src/index.tsx
index b83b4ae..d81ff28 100644
--- a/src/index.tsx
+++ b/src/index.tsx
@@ -42,7 +42,6 @@ export { useSetBackdrop, useSheetPreventDismiss } from './store';
 
 // Hooks
 export { useBottomSheetManager } from './useBottomSheetManager';
-export type { CloseAllOptions } from './useBottomSheetManager';
 export {
   useBottomSheetControl,
   type UseBottomSheetControlReturn,
@@ -66,6 +65,7 @@ export type {
   OpenRejectionReason,
   CloseResult,
   CloseRejectionReason,
+  CascadeOptions,
   CloseAllResult,
   PublicBottomSheetState as BottomSheetState,
 } from './store';
diff --git a/src/store/types.ts b/src/store/types.ts
index b68ecc9..61274cb 100644
--- a/src/store/types.ts
+++ b/src/store/types.ts
@@ -124,10 +124,35 @@ export type CloseResult =
   | { closed: true }
   | { closed: false; reason: CloseRejectionReason };
 
+/**
+ * How far a cascading close reaches.
+ *
+ * With no bound it empties the group. `until` and `depth` each narrow it, and
+ * combining them takes whichever closes fewer sheets.
+ */
+export interface CascadeOptions {
+  /** Delay in ms between each close animation. Default: 100. */
+  stagger?: number;
+  /**
+   * Stop the cascade at this sheet rather than emptying the group.
+   *
+   * Sheets below it stay open. A sheet that is not on this group's stack
+   * closes nothing — a bounded call must not fall back to closing everything.
+   */
+  until?: string;
+  /** Whether the `until` sheet closes as well. Default: `false`. */
+  inclusive?: boolean;
+  /** Close at most this many sheets, counting from the top of the stack. */
+  depth?: number;
+}
+
 /** Outcome of a cascading close. */
 export interface CloseAllResult {
-  /** Whether every sheet in the group closed. */
-  closedAll: boolean;
+  /**
+   * Whether the cascade closed everything it set out to. Bounded by `until` or
+   * `depth`, that is the requested range — not the whole group.
+   */
+  completed: boolean;
   /** IDs that closed, topmost first. */
   closed: string[];
   /**
diff --git a/src/useBottomSheetContext.ts b/src/useBottomSheetContext.ts
index 1653245..ee60a0e 100644
--- a/src/useBottomSheetContext.ts
+++ b/src/useBottomSheetContext.ts
@@ -1,11 +1,12 @@
 import { useMaybeBottomSheetContext } from './BottomSheet.context';
+import { useMaybeBottomSheetManagerContext } from './BottomSheetManager.context';
 import {
   useSheetParams,
   useSheetPreventDismiss,
   useStartClosing,
 } from './store';
-import type { CloseResult } from './store';
-import { requestClose } from './bottomSheetCoordinator';
+import type { CascadeOptions, CloseAllResult, CloseResult } from './store';
+import { closeAllAnimated, requestClose } from './bottomSheetCoordinator';
 import type {
   BottomSheetPortalId,
   BottomSheetPortalParams,
@@ -34,6 +35,18 @@ export interface UseBottomSheetContextReturn<TParams> {
    * naming why not (`'blocked'`, `'interceptor-error'`, `'not-closable'`).
    */
   close: () => Promise<CloseResult>;
+  /**
+   * Closes every sheet stacked above this one, leaving this one open.
+   *
+   * The common case for a sheet deep in a stack: finish here, then land back
+   * on this screen rather than on an empty one, without having to name your own
+   * ID or count how many sheets are above you.
+   *
+   * Pass `inclusive` to close this sheet as well.
+   */
+  closeAbove: (
+    options?: Omit<CascadeOptions, 'until'>
+  ) => Promise<CloseAllResult>;
   /**
    * Close the sheet, bypassing any onBeforeClose interceptor.
    * Useful for force-closing from within onBeforeClose confirmation flows.
@@ -57,6 +70,7 @@ export function useBottomSheetContext<
   const params = useSheetParams(id);
   const preventDismiss = useSheetPreventDismiss(id);
   const startClosing = useStartClosing();
+  const managerContext = useMaybeBottomSheetManagerContext();
 
   if (!context?.id) {
     throw new Error(
@@ -66,12 +80,18 @@ export function useBottomSheetContext<
 
   const close = () => requestClose(context.id);
   const forceClose = () => startClosing(context.id);
+  const closeAbove = (options?: Omit<CascadeOptions, 'until'>) =>
+    closeAllAnimated(managerContext?.groupId || 'default', {
+      ...options,
+      until: context.id,
+    });
 
   return {
     id: context.id,
     params: params as BottomSheetPortalParams<T>,
     preventDismiss,
     close,
+    closeAbove,
     forceClose,
   };
 }
diff --git a/src/useBottomSheetControl.ts b/src/useBottomSheetControl.ts
index e27c134..a5849f9 100644
--- a/src/useBottomSheetControl.ts
+++ b/src/useBottomSheetControl.ts
@@ -2,7 +2,7 @@ import React from 'react';
 import type { SheetAdapterRef } from './adapter.types';
 
 import { useOpen, useUpdateParams, type OpenMode } from './store';
-import type { CloseAllResult, CloseResult } from './store';
+import type { CascadeOptions, CloseAllResult, CloseResult } from './store';
 import { useMaybeBottomSheetManagerContext } from './BottomSheetManager.context';
 import { closeAllAnimated, requestClose } from './bottomSheetCoordinator';
 import type {
@@ -11,7 +11,6 @@ import type {
   HasParams,
 } from './portal.types';
 import { getSheetRef, setSheetRef } from './refsMap';
-import type { CloseAllOptions } from './useBottomSheetManager';
 
 interface BaseOpenOptions<TParams> {
   mode?: OpenMode;
@@ -57,7 +56,7 @@ export interface UseBottomSheetControlReturn<T extends BottomSheetPortalId> {
    * @returns A `CloseAllResult` — what closed, and which sheet stopped the
    * cascade if an interceptor did.
    */
-  closeAll: (options?: CloseAllOptions) => Promise<CloseAllResult>;
+  closeAll: (options?: CascadeOptions) => Promise<CloseAllResult>;
   updateParams: (params: BottomSheetPortalParams<T>) => void;
   resetParams: () => void;
 }
@@ -97,7 +96,7 @@ export function useBottomSheetControl<T extends BottomSheetPortalId>(
 
   const close = () => requestClose(id);
 
-  const closeAll = (options?: CloseAllOptions) => {
+  const closeAll = (options?: CascadeOptions) => {
     const groupId = bottomSheetManagerContext?.groupId || 'default';
     return closeAllAnimated(groupId, options);
   };
diff --git a/src/useBottomSheetManager.tsx b/src/useBottomSheetManager.tsx
index d22c4cd..c68d644 100644
--- a/src/useBottomSheetManager.tsx
+++ b/src/useBottomSheetManager.tsx
@@ -1,17 +1,12 @@
 import React from 'react';
 
 import { useOpen, useClearGroup, type OpenMode } from './store';
-import type { CloseResult } from './store';
+import type { CascadeOptions, CloseAllResult, CloseResult } from './store';
 import { useMaybeBottomSheetManagerContext } from './BottomSheetManager.context';
 import type { SheetAdapterRef } from './adapter.types';
 import { closeAllAnimated, requestClose } from './bottomSheetCoordinator';
 import { setSheetRef } from './refsMap';
 
-export interface CloseAllOptions {
-  /** Delay in ms between each cascading close animation. Default: 100 */
-  stagger?: number;
-}
-
 export const useBottomSheetManager = () => {
   const bottomSheetManagerContext = useMaybeBottomSheetManagerContext();
 
@@ -80,10 +75,41 @@ export const useBottomSheetManager = () => {
    */
   const close = (id: string): Promise<CloseResult> => requestClose(id);
 
-  const closeAll = (options?: CloseAllOptions) => {
-    const groupId = bottomSheetManagerContext?.groupId || 'default';
-    return closeAllAnimated(groupId, options);
-  };
+  const groupId = () => bottomSheetManagerContext?.groupId || 'default';
+
+  /**
+   * Closes the group's sheets from the top down, one after another.
+   *
+   * Pass `until` or `depth` to stop short of emptying the group — or reach for
+   * {@link closeTo} / {@link closeDepth}, which say the same thing in a name.
+   */
+  const closeAll = (options?: CascadeOptions) =>
+    closeAllAnimated(groupId(), options);
+
+  /**
+   * Closes sheets down to `id`, leaving it open — the stack equivalent of
+   * navigating back to a screen.
+   *
+   * Pass `inclusive` to close `id` too. An `id` that is not on this group's
+   * stack closes nothing, rather than falling through to closing everything.
+   */
+  const closeTo = (
+    id: string,
+    options?: Omit<CascadeOptions, 'until'>
+  ): Promise<CloseAllResult> =>
+    closeAllAnimated(groupId(), { ...options, until: id });
+
+  /**
+   * Closes at most `count` sheets, counting from the top of the stack.
+   *
+   * A count at or past the stack's height empties the group; zero or less
+   * closes nothing.
+   */
+  const closeDepth = (
+    count: number,
+    options?: Omit<CascadeOptions, 'depth'>
+  ): Promise<CloseAllResult> =>
+    closeAllAnimated(groupId(), { ...options, depth: count });
 
   /**
    * Removes every sheet in the group from the store immediately.
@@ -94,14 +120,15 @@ export const useBottomSheetManager = () => {
    * anything user-facing.
    */
   const destroyAll = () => {
-    const groupId = bottomSheetManagerContext?.groupId || 'default';
-    storeClearGroup(groupId);
+    storeClearGroup(groupId());
   };
 
   return {
     open: openBottomSheet,
     close,
     closeAll,
+    closeTo,
+    closeDepth,
     destroyAll,
   };
 };