@yourrealm/bottom-sheet 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,40 @@
+# Changelog
+
+## 0.2.0 (2026-11-02)
+
+### Breaking
+
+- The styled parts from `@yourrealm/bottom-sheet/styled` are now `StyledSheet` (they were a second `Sheet`, easy to
+  confuse with the headless one). Most code should use `BottomSheet`; for a close button inside it, `Sheet.Close`
+  becomes `BottomSheet.Close`. The headless `Sheet` from `@yourrealm/bottom-sheet` is unchanged.
+- `BottomSheet` needs a name: `title`, or `aria-label` for a sheet without a visible title. A `title` that may be
+  `undefined` needs a fallback (`title={q ?? 'Confirm'}`).
+
+### Added
+
+- `footer` (`Sheet.Footer` / `StyledSheet.Footer`): actions pinned to the bottom of the screen, also at partial
+  detents, reaching the sheet's edges, taking the home-bar safe area.
+- `BottomSheet.Edge` (`StyledSheet.Edge`): content in the body that reaches the sheet's edges, its contents kept in
+  line with the body. `--ybs-body-inset` is the side space in use.
+- `StyledSheet.Body`: the padded content area for parts users.
+- The `'header'` detent: a peek of exactly the header. A flick down from higher up lands on it instead of closing.
+- `onExitComplete`: called once the sheet has finished closing and left the page.
+- `closeButton` (a visible ✕) and `closeLabel`. Without `closeButton`, a dismissible sheet gets a close button only
+  screen readers announce.
+- `BottomSheet.Close`.
+- `eyebrow`: a small label above the title.
+- `--ybs-title-size` token.
+- A sheet without a visible title (`aria-label`): the header is just the grabber, without a title's space.
+- `data-ybs-more` on the root while content is hidden behind the footer.
+
+### Changed
+
+- `/styled`: the line under the header shows only while content is scrolled under it (it used to always show, and
+  content sat right on it). If you added top padding to work around that, you can drop it.
+- `/styled` `floating`: the side spacing includes the gap (24px instead of 16px), so text no longer sits 8px from the
+  visible edge at lower detents.
+- A pixel peek like `detents={['76px']}` that was meant to show just the header can become `['header']`.
+
+## 0.1.0 (2026-11-01)
+
+First release.

package/README.md

@@ -38,122 +38,210 @@ the preset. Opening a sheet without the CSS logs an error naming the import.
 
 ## Use
 
-The simple path, with the polished preset:
-
 ```tsx
 import { BottomSheet } from '@yourrealm/bottom-sheet/styled'
 
-<BottomSheet trigger="Filters" title="Filters" detents={[0.5]}>
+<BottomSheet
+  trigger={(props) => <Button {...props}>Filters</Button>} // your own button; or control it with open/onOpenChange
+  title="Filters"
+  detents={[0.5]}
+>
   …
 </BottomSheet>
 ```
 
-Headless parts, for your own look:
+Three ways in. **Use `BottomSheet`** unless you've been asked for something else:
+
+| | Import from | What it is |
+|---|---|---|
+| `BottomSheet` | `@yourrealm/bottom-sheet/styled` | The finished sheet. Everything you need hangs off it (`BottomSheet.Close`, `BottomSheet.Edge`). |
+| `StyledSheet` | `@yourrealm/bottom-sheet/styled` | The styled parts `BottomSheet` is built from, to arrange yourself. |
+| `Sheet` | `@yourrealm/bottom-sheet` | The parts with no look at all, only the behaviour. For a fully custom design. |
+
+`BottomSheet`'s options (`leading`, `trailing`, `eyebrow`, `headerExtra`, `footer`, `BottomSheet.Edge`) cover most
+layouts. Use the parts only when the person you're working for asks for them, or for a fully custom design (see
+"Building from parts" below).
+
+**Migrating an existing sheet or dialog?** Move its content into `BottomSheet`, and map its header to `title`,
+`description`, `leading`, `trailing` and its buttons to `footer`. Don't rebuild your old markup from parts to keep the
+diff small: you lose the screen-reader close button, the header layouts and the eyebrow, and your spacing drifts
+from the preset.
+
+### `BottomSheet`
 
 ```tsx
-import { Sheet } from '@yourrealm/bottom-sheet'
+import { BottomSheet } from '@yourrealm/bottom-sheet/styled'
 
-<Sheet.Root detents={[0.4]} onDetentChange={(d) => console.log(d)}>
-  <Sheet.Trigger>Up next</Sheet.Trigger>
-  <Sheet.Portal>
-    <Sheet.Backdrop className="backdrop" />
-    <Sheet.View>
-      <Sheet.Content className="sheet">
-        <Sheet.Header className="header">
-          <Sheet.Handle />
-          <Sheet.Title>Up next</Sheet.Title>
-          <Sheet.Close>Done</Sheet.Close>
-        </Sheet.Header>
-        …
-      </Sheet.Content>
-    </Sheet.View>
-  </Sheet.Portal>
-</Sheet.Root>
-```
+// A confirm sheet with actions pinned to the bottom
+<BottomSheet open={open} onOpenChange={setOpen} title="Delete this list?"
+  footer={<><BottomSheet.Close>Cancel</BottomSheet.Close><button onClick={remove}>Delete</button></>}>
+  This can't be undone.
+</BottomSheet>
+
+// Content that reaches the sheet's edges
+<BottomSheet open={open} onOpenChange={setOpen} title="Café Mollan" eyebrow="Gamla stan">
+  <BottomSheet.Edge className="photos">…</BottomSheet.Edge>
+</BottomSheet>
 
-### Options
+// An iOS page sheet: Cancel / title / Save
+<BottomSheet open={open} onOpenChange={setOpen} variant="page" title="New Note"
+  leading={<BottomSheet.Close>Cancel</BottomSheet.Close>} trailing={<button onClick={save}>Save</button>}>
+  …
+</BottomSheet>
 
-- `detents`: partial resting heights, as fractions of the height available to the sheet (`0.5`) or CSS lengths of visible sheet (`'76px'`,
-  `'40dvh'`). Full height is always included, and is the content's own height when the content is short. Default `[]`:
-  the sheet opens straight to full, like iOS. It opens at the smallest partial detent when you give some, or at
-  `initialDetent`.
+// No visible title: name it with aria-label (description, leading/trailing still work)
+<BottomSheet open={open} onOpenChange={setOpen} aria-label="Photo options">
+  …
+</BottomSheet>
+
+// A persistent result sheet: peeks with just its header, never closes by gesture
+<BottomSheet open={solved} modal={false} dismissible={false} detents={['header']} title="Solved">
+  …
+</BottomSheet>
+```
+
+- **A name is required:** `title` (visible, and it names the dialog for screen readers), or `aria-label` for a sheet
+  without a visible title (an action list, a photo viewer). TypeScript refuses a sheet with neither. A title that may
+  be missing needs a fallback: `title={pending?.question ?? 'Confirm'}`.
+- `eyebrow`: a small label above the title (a section, a category), read together with the title. Needs `title`.
+- `description`: a line under the title; it describes the dialog.
+- `leading` / `trailing`: header slots, iOS navigation-bar style (Cancel / title / Save, the title centred).
+- `headerExtra`: content in the sticky header under the title (a search field).
+- `footer`: actions pinned to the bottom of the screen (Cancel / Delete, Show results). They stay reachable while a
+  long sheet scrolls and at partial detents, reach the sheet's edges, and take the home-bar safe area. At a peek
+  too low for both, the footer stays tucked under the header and slides in as the sheet rises.
+- `closeButton`: a visible ✕ in the header's top right (off by default). Without it, a dismissible sheet still has a
+  close button that only screen readers announce (shown when focused by keyboard), because VoiceOver users can't swipe a
+  sheet away or tap the dimmed area. `closeLabel` names either one (default `'Close'`).
+- `BottomSheet.Close`: a button that closes the sheet (in `leading`, `footer`, or the content).
+- `BottomSheet.Edge`: content in the body that reaches the sheet's edges (a photo strip that scrolls sideways, a
+  full-width tappable row, a separator), its contents kept in line with the body. Right in every variant.
+- `trigger`: text or elements go inside a plain, unstyled `<button class="ybs-trigger">`. For a design-system button,
+  pass a function; it receives `type`, `onClick` and the ARIA state:
+  `trigger={(props) => <Button variant="outline" {...props}>Filters</Button>}`. Or leave `trigger` out and control `open`.
+- `variant="page"`: an iOS page sheet for a task: full width, the page behind recedes (`recede`), and the sheet fills
+  the screen at full even with short content.
+- `width`: `'card'` (default for sheets: at most 640px, centred) or `'full'` (default for pages: spans the window,
+  content in a centred 960px column).
+- `floating`: iOS 26 style, inset from the screen edges with large corners at lower detents, attaching as it reaches
+  full. Its side spacing includes the gap, so text keeps its distance from the visible edge.
+- `initialFocus`: see Options.
+- `className` / `contentProps`: go on the sheet element (`<section role="dialog">`).
+- Plus every option below.
+
+### Options (on `BottomSheet` and `Sheet.Root`)
+
+- `detents`: partial resting heights, as fractions of the height available to the sheet (`0.5`), CSS lengths of
+  visible sheet (`'76px'`, `'40dvh'`), or `'header'`: exactly the header, measured, for a peek that shows the title
+  and nothing under it. A `'header'` peek is a minimised state: a flick down from higher up lands on it, and only a
+  flick from the peek itself closes the sheet (with `dismissible={false}`, nothing does). Other partial detents let a
+  flick run past them. Full height (`'full'`) is always included, and is the content's own height when the content
+  is short. Default `[]`: the sheet opens straight to full, like iOS.
+- `initialDetent`: where it opens: `'full'` or one of your `detents`. Default: the smallest partial detent, else full.
+- `detent` / `onDetentChange`: the detent the sheet rests at, `'full'` or the value you passed in `detents`
+  (`0.5`, `'76px'`, `'header'`). Pass `detent` to control it (changing it moves the sheet). `onDetentChange` never
+  reports `'closed'` (closing is `onOpenChange(false)`), so `detent={d} onDetentChange={setD}` round-trips.
 - `open` / `defaultOpen` / `onOpenChange(open, { reason })`: controlled or uncontrolled. The reason is
   `'trigger' | 'close-button' | 'escape' | 'back' | 'outside-press' | 'swipe'`. Use `open` when a sheet has several
   openers, or opening runs your own logic.
-- `detent` / `onDetentChange`: the detent the sheet rests at. Pass `detent` to control it (changing it moves the
-  sheet); `onDetentChange` reports where it came to rest, never `'closed'` (closing is `onOpenChange(false)`), so
-  `detent={d} onDetentChange={setD}` round-trips.
-- `trigger` (`/styled`): text or elements go inside our trigger button; a function renders your own button (a
-  design-system `<Button>`), receiving `type`, `onClick` and the ARIA state:
-  `trigger={(props) => <Button variant="outline" {...props}>Filters</Button>}`. Headless: `<Sheet.Trigger render={…} />`.
-- `modal` (default `true`): `false` gives a sheet without a backdrop that leaves the page usable around it (no inert,
-  no scroll lock). It doesn't move focus unless you pass `initialFocus`, and Escape only acts on it while focus is
-  inside it. `modal` is read when the sheet opens; a change while it's open applies from the next open.
+- `onExitComplete`: called once the sheet has finished closing and left the page. See "Closing animates".
+- `modal` (default `true`): `false` leaves the page usable around the sheet: no backdrop (`BottomSheet` drops it), no
+  inert page, no scroll lock. It doesn't move focus unless you pass `initialFocus`, and Escape only acts on it while
+  focus is inside it. `modal` is read when the sheet opens; a change while it's open applies from the next open.
   On iOS, each direct child of a non-modal sheet becomes a 1px horizontal scroller (Safari needs a scroll container
-  under the finger to drag the sheet): keep sticky elements at the top level, like `Sheet.Header`, and render popovers
-  in a portal rather than inside the sheet's children.
+  under the finger to drag the sheet): keep sticky elements at the top level, like the header, and render popovers in
+  a portal rather than inside the sheet's children.
 - `initialFocus` (on `BottomSheet` / `Sheet.Content`, like Base UI's): where focus goes when the sheet opens. A ref,
   `false`, `true` (the sheet), or a function of how it was opened: `initialFocus={(type) => type !== 'touch' &&
   newBoardRef.current}` focuses a button for mouse and keyboard users only. Default: the sheet for a modal sheet,
   nothing for a non-modal one. A non-modal sheet that took focus gives it back when it closes.
 - `dismissible` (default `true`): `false` means a swipe down, Escape or an outside press drop the sheet to its lowest
-  detent instead of closing it. `open={false}` and `<Sheet.Close>` still close it.
+  detent instead of closing it. `open={false}` and a close button still close it.
 - `closeOnBack` (default: `modal`): the Android back button closes the top sheet, like a native sheet. Built on
   [`CloseWatcher`](https://developer.mozilla.org/en-US/docs/Web/API/CloseWatcher), so it adds no history entries and
   never touches your URLs or router. Works in Chrome and Firefox on Android; Safari has no `CloseWatcher` yet, and
   elsewhere it does nothing.
-- `fullscreen`: the full detent reaches the very top of the screen, and the sheet fills the screen there even with short
-  content. `/styled` squares off the corners as it arrives and pads the header by the top safe area.
-- `Sheet.Portal container`: render into an element other than `<body>`. A modal sheet still makes everything else on
-  the page inert.
-- `debug`: a function that receives the sheet's internal decision log, for testing gestures on a device.
+- `fullscreen`: the full detent reaches the very top of the screen, and the sheet fills the screen there even with
+  short content. `/styled` squares off the corners as it arrives and pads the header by the top safe area.
 - `recede`: the page behind scales back like iOS while the sheet covers the screen. Mark your app's wrapper with
   `data-ybs-background` and give it a background. While receding, `position: fixed` elements inside that wrapper are
-  positioned against it. Page sheets (`variant="page"`) recede by default.
-- `/styled` only:
-  - `title`, `description` (headless: `Sheet.Title`, `Sheet.Description`, which name and describe the dialog; without
-    a `Sheet.Title`, give `Sheet.Content` an `aria-label`), and `leading` / `trailing` header slots (Cancel / title / Save, title centred), plus
-    `headerExtra` for things under the title (a search field).
-  - `variant="page"`: an iOS page sheet for a task: full width, the page behind recedes, and the sheet fills the
-    screen at full. Leave `detents` out and it opens straight to full.
-  - `width`: `'card'` (at most 640px, centred) or `'full'` (spans the window, content in a centred 960px column).
-  - `floating`: iOS 26 style, inset from the screen edges with large corners at lower detents, attaching as it reaches
-    full (tokens `--ybs-float-gap`, `--ybs-float-radius`).
-
-  ```tsx
-  <BottomSheet variant="page" title="New Note" leading={<Sheet.Close>Cancel</Sheet.Close>} trailing={<button onClick={save}>Save</button>}>
-  ```
-
-A persistent "result" sheet that peeks at 76px and never closes by gesture:
+  positioned against it. Modal sheets only. On by default for `variant="page"`.
+- `debug`: a function that receives the sheet's internal decision log, for testing gestures on a device.
+
+### Closing animates
+
+A sheet animates out after `open` turns false, so **keep it rendered**. Don't write `{open && <BottomSheet … />}`:
+removing it skips the animation (it just vanishes). Whatever the content shows (the question in a confirm sheet,
+the item being shared) has to stay around until the sheet is gone. `onExitComplete` tells you when:
 
 ```tsx
-<BottomSheet open={solved} modal={false} dismissible={false} detents={['76px']} title="Solved">
-  …
-</BottomSheet>
+import { useState } from 'react'
+import { BottomSheet } from '@yourrealm/bottom-sheet/styled'
+
+function useConfirm() {
+  const [pending, setPending] = useState<{ question: string; onConfirm: () => void } | null>(null)
+  const [open, setOpen] = useState(false)
+  const confirm = (question: string, onConfirm: () => void) => {
+    setPending({ question, onConfirm })
+    setOpen(true)
+  }
+  const sheet = (
+    <BottomSheet
+      open={open}
+      onOpenChange={setOpen}
+      onExitComplete={() => setPending(null)} // the sheet is gone: now it's safe to clear
+      title={pending?.question ?? 'Confirm'}
+      footer={<>
+        <BottomSheet.Close>Cancel</BottomSheet.Close>
+        <button onClick={() => { pending?.onConfirm(); setOpen(false) }}>Confirm</button>
+      </>}
+    />
+  )
+  return { confirm, sheet } // render {sheet} once; call confirm('Delete this list?', remove)
+}
 ```
 
+`onOpenChange` fires for what the user does (a trigger click, a swipe, Escape, back, a tap outside, a close button),
+never when you change `open` yourself, so `onOpenChange={(o) => !o && onClose()}` can't loop.
+
 ### Styling
 
-- `/styled` light and dark follow your app's `color-scheme` (inherited from `<html>`), so a theme switch that sets it
-  gets a matching sheet. Set `html { color-scheme: light dark }` to follow the phone's setting; with no `color-scheme`
-  at all the sheet stays light. All colours are `--ybs-*` tokens.
-- One sheet in a fixed theme: set `color-scheme` on it, e.g. `className="[color-scheme:dark]"` or
-  `contentProps={{ style: { colorScheme: 'dark' } }}` (headless: on `Sheet.Content`).
-- The `/styled` body gets 16px side padding like the header (`--ybs-body-padding`; set it to `0` for edge-to-edge lists).
-- Headless `Sheet.View` passes its props (`className`, `style`, `ref`, `data-*`) to the scroller, the one scroll container.
-- CSS variables on `[data-ybs-root]`: `--ybs-progress` (0 to 1, closed to full) for your own backdrop or effects,
-  `--ybs-visible` (px of the sheet on screen), and `--ybs-sheet-bg` (the colour that continues behind the keyboard).
-  While the content is scrolled the root has `data-ybs-scrolled`.
-- Headless: content scrolling under a sticky `Sheet.Header` can show a 1px sliver above it; cover it with a
-  `box-shadow: 0 -2px 0 0 <sheet colour>` on the header (only while `data-ybs-scrolled` if your sheet has a border).
-- Don't put `touch-action` classes on `Sheet.Header` (Tailwind's utilities layer beats ours): the library turns it off
-  there while the content is scrolled, so that dragging the header moves the whole sheet.
+- Light and dark follow your app's `color-scheme` (inherited from `<html>`), so a theme switch that sets it gets a
+  matching sheet. Set `html { color-scheme: light dark }` to follow the phone's setting; with no `color-scheme` at all
+  the sheet stays light. One sheet in a fixed theme: `className="[color-scheme:dark]"` or
+  `contentProps={{ style: { colorScheme: 'dark' } }}`.
+- Tokens. Set them on `[data-ybs-root]`, and point them at your own variables to match your theme (dark mode then
+  comes with it): `[data-ybs-root] { --ybs-sheet-bg: var(--card); --ybs-sheet-fg: var(--card-foreground); }`.
+
+  | Token | Default (light / dark) | What it affects |
+  |---|---|---|
+  | `--ybs-sheet-bg` | `#fff` / `#1c1c1e` | Sheet background, also behind the keyboard |
+  | `--ybs-sheet-fg` | `#111` / `#f2f2f7` | Text colour |
+  | `--ybs-muted` | `#6b6b70` / `#98989f` | Description, eyebrow, the ✕ |
+  | `--ybs-handle` | grey, 30% | The grabber at the top |
+  | `--ybs-divider` | grey, 12% | Lines under the header and above the footer |
+  | `--ybs-backdrop` | `#000` | Colour of the dimmed page (a colour, no alpha) |
+  | `--ybs-backdrop-max` | `0.4` | How dark the dim gets at full. An `rgba(0,0,0,.5)` scrim is `#000` + `0.5` |
+  | `--ybs-radius` | `14px` | Top corners |
+  | `--ybs-title-size` | `17px` | Title |
+  | `--ybs-body-padding` | `16px` | Side space of the body and footer (`0` for edge-to-edge lists that pad their own rows) |
+  | `--ybs-max-width` | `640px` | Width of a `card` sheet |
+  | `--ybs-content-width` | `960px` | Content column of a `width="full"` sheet |
+  | `--ybs-float-gap` / `--ybs-float-radius` | `8px` / `32px` | `floating`: gap to the screen edges, corner size |
+  | `--ybs-inset` | safe area + 10px | Gap above the sheet at full (+22px for page sheets, `0` with `fullscreen`). Works headless too |
+
+- `--ybs-body-inset` (read it, don't set it) is the side space actually in use, larger on a wide `width="full"` sheet;
+  `BottomSheet.Edge` uses it.
+- The header draws its divider only while content is scrolled under it, and the footer only while content is hidden
+  behind it, so a sheet at rest has no lines splitting it.
+- The sheet already pads its bottom for the home bar (`safe-area-inset-bottom`, in the footer when there is one).
+  Don't add your own.
 
 ### Behaviour
 
 - Opening, closing and the other moves the library makes (a new `detent`, the keyboard appearing, wheel steps) animate
-  in about 400ms going up and 280ms going down (Material 3 emphasized easing), and are instant with reduced motion. Drags and flings are the
-  browser's own scrolling.
+  in about 400ms going up and 280ms going down (Material 3 emphasized easing), and are instant with reduced motion.
+  Drags and flings are the browser's own scrolling.
 - With the content scrolled, dragging the header moves the whole sheet and keeps the content where it is, like native.
 - A tap on content that is still scrolling only stops it, and a drag never presses what it started on.
 - Keys scroll the content but never move the sheet down or close it; closing by keyboard is Escape. Escape that ends
@@ -162,9 +250,88 @@ A persistent "result" sheet that peeks at 76px and never closes by gesture:
 - A sheet closes from a swipe, Escape, back, an outside press, a close button or `open={false}`, never from a scroll
   nobody asked for: one that lands at closed (the browser revealing a focused field, say) is undone.
 
+### Stacked sheets
+
+A sheet opened from inside another one stacks on top: with `/styled`, the one below recedes (scales back, like iOS)
+and comes forward again when the top one closes (parts: `data-ybs-covered`, see below). Escape, Android back and a tap on the dimmed area all close only the top sheet.
+The page stays inert until the last modal sheet closes. No setup: render the second `BottomSheet` inside the first.
+
+### Building from parts
+
+Not sure you need this? Go back to `BottomSheet`.
+
+`StyledSheet` (the preset look) and `Sheet` (no look) have the same parts; `StyledSheet` adds `Body` (the padded
+content area) and `Edge`. You assemble what `BottomSheet` does for you, so a few things are yours:
+
+```tsx
+import { Sheet } from '@yourrealm/bottom-sheet'
+
+<Sheet.Root detents={[0.4]}>
+  <Sheet.Trigger>Up next</Sheet.Trigger>
+  <Sheet.Portal>
+    <Sheet.Backdrop className="backdrop" />
+    <Sheet.View>
+      <Sheet.Content className="sheet">
+        <Sheet.Header className="header">
+          <Sheet.Handle />
+          <Sheet.Title>Up next</Sheet.Title>
+          <Sheet.Close>Done</Sheet.Close>
+        </Sheet.Header>
+        …
+        <Sheet.Footer className="footer">…</Sheet.Footer>
+      </Sheet.Content>
+    </Sheet.View>
+  </Sheet.Portal>
+</Sheet.Root>
+```
+
+- **With `StyledSheet`:** put your content in `StyledSheet.Body` after the `Header` (it's the padded area, and
+  `StyledSheet.Edge` lines up with it), add `StyledSheet.Backdrop` for a modal sheet, and lay out the header yourself
+  (the Cancel / title / Save row, the ✕ and the eyebrow are `BottomSheet` features).
+- **Naming:** `Sheet.Title` and `Sheet.Description` name and describe the dialog. Without a `Title`, give
+  `Sheet.Content` an `aria-label` (or `aria-labelledby` pointing at your own heading).
+- **Closing:** add your own `Sheet.Close`; there's no automatic screen-reader close button.
+- **Non-modal:** leave `Backdrop` out yourself (a rendered `Backdrop` still dims and closes on tap).
+- **`Sheet.Portal container`:** render into an element other than `<body>`. A modal sheet still makes everything else
+  on the page inert.
+- **`Sheet.View`** passes its props (`className`, `style`, `ref`, `data-*`) to the scroller, the one scroll
+  container; `bleedClassName` styles the layer that continues the sheet colour behind the keyboard.
+- **Set by the library on `[data-ybs-root]`**, for your own styling: `--ybs-progress` (0 to 1, closed to full),
+  `--ybs-visible` (px of the sheet on screen), and the attributes `data-ybs-scrolled` (content scrolled under the
+  header), `data-ybs-more` (content hidden behind the footer), `data-ybs-fit` (the sheet is shorter than the screen),
+  `data-ybs-fullscreen`, `data-ybs-modeless` (non-modal), and on the sheet below a stacked one `data-ybs-covered`
+  with `--ybs-covered` (0 to 1, following the top sheet).
+- **Recede headless:** style `html[data-ybs-recede] [data-ybs-background]` with `--ybs-recede` (0 to 1, how much of
+  the screen the sheet covers) and `--ybs-scroll-y` (for a `transform-origin` at the top of the screen).
+- **Headless sticky header:** content scrolling under it can show a 1px sliver above it; cover it with
+  `box-shadow: 0 -2px 0 0 <sheet colour>` on the header (only while `data-ybs-scrolled` if your sheet has a border).
+- Don't put `touch-action` classes on the header (Tailwind's utilities layer beats ours): the library turns it off
+  there while the content is scrolled, so that dragging the header moves the whole sheet.
+- **Types** for wrappers: `Detent`, `OpenChangeReason`, `OpenChangeDetails`, `RootProps`, `ContentProps`,
+  `InitialFocus` and the other part props from both entry points, and `BottomSheetProps` from `/styled`.
+
+### Replacing a `<dialog>`
+
+| `<dialog>` | bottom-sheet |
+|---|---|
+| `showModal()` / `close()` | `open` (keep the sheet rendered, see "Closing animates") |
+| `cancel` event (Escape) | `onOpenChange(false, { reason: 'escape' })` |
+| click where `target === currentTarget` (backdrop) | `onOpenChange(false, { reason: 'outside-press' })` |
+| `::backdrop` styling | `--ybs-backdrop` + `--ybs-backdrop-max` |
+| `autofocus` on a button inside | `initialFocus={ref}` |
+| `aria-labelledby` on the dialog | `title`, or `aria-label` for a sheet without one |
+
+### Testing
+
+- Press Escape with a real key press (Playwright's `page.keyboard.press('Escape')`). A sheet that listens for back
+  (`closeOnBack`, on for modal sheets) gets Escape from the browser where `CloseWatcher` exists (Chrome, Firefox), and
+  the browser ignores a dispatched `keydown`. A real key press works everywhere.
+- To know a sheet has fully closed, use `onExitComplete`, or wait for its dialog to leave the page
+  (`getByRole('dialog', { name: 'Share photo' })`), which also works with several sheets open.
+
 ## Status
 
-Early (0.x). Tested on Android in Chrome and Firefox (a gesture suite on a real phone) and in iOS Safari in the
+Early (0.x); see the [changelog](CHANGELOG.md) for what changed between versions. Tested on Android in Chrome and Firefox (a gesture suite on a real phone) and in iOS Safari in the
 simulator; a real iPhone is still to come. Desktop works with mouse, wheel, trackpad and keyboard.
 
 ## Found a problem?

package/dist/index.d.ts

@@ -1,3 +1,3 @@
 
-import { a as OpenChangeDetails, c as PortalProps, f as TriggerProps, g as Detent, h as sheet_d_exports, i as InteractionType, m as ViewProps, n as ContentProps, o as OpenChangeReason, p as TriggerRenderProps, r as InitialFocus, u as RootProps } from "./sheet-BOTt16RW.js";
+import { a as OpenChangeDetails, c as PortalProps, f as TriggerProps, g as Detent, h as sheet_d_exports, i as InteractionType, m as ViewProps, n as ContentProps, o as OpenChangeReason, p as TriggerRenderProps, r as InitialFocus, u as RootProps } from "./sheet-5lG9EBB5.js";
 export { type ContentProps, type Detent, type InitialFocus, type InteractionType, type OpenChangeDetails, type OpenChangeReason, type PortalProps, type RootProps, sheet_d_exports as Sheet, type TriggerProps, type TriggerRenderProps, type ViewProps };

package/dist/index.js

@@ -1,2 +1,2 @@
 'use client';
-export { f as Sheet } from "./sheet-BgvWfCR8.js";
+export { p as Sheet } from "./sheet-C1fUpy71.js";

package/dist/{sheet-BOTt16RW.d.ts → sheet-5lG9EBB5.d.ts}

@@ -4,11 +4,12 @@ import { ComponentPropsWithRef, MouseEvent, ReactElement, ReactNode, RefObject }
  * A resting position.
  * - `'closed'` and `'full'` are always available (`'closed'` only while the sheet is dismissible).
  * - A number is a fraction (0..1) of the available height that is visible, e.g. `0.5`.
+ * - `'header'` shows exactly the sheet's header (`Sheet.Header`), measured, e.g. a peek with just the title.
  * - Any other string is a CSS length of visible sheet, e.g. `'76px'`, `'40dvh'`, `'min(320px, 50dvh)'`.
  */
-type Detent = 'closed' | 'full' | number | (string & {});
+type Detent = 'closed' | 'full' | 'header' | number | (string & {});
 declare namespace sheet_d_exports {
-  export { Backdrop, Close, Content, ContentProps, Description, Handle, Header, InitialFocus, InteractionType, OpenChangeDetails, OpenChangeReason, Portal, PortalProps, Root, RootProps, Title, Trigger, TriggerProps, TriggerRenderProps, View, ViewProps };
+  export { Backdrop, Close, Content, ContentProps, Description, Footer, Handle, Header, InitialFocus, InteractionType, OpenChangeDetails, OpenChangeReason, Portal, PortalProps, Root, RootProps, Title, Trigger, TriggerProps, TriggerRenderProps, View, ViewProps };
 }
 /** Why the sheet is asking to open or close. */
 type OpenChangeReason = 'trigger' | 'close-button' | 'escape' | 'back' | 'outside-press' | 'swipe';
@@ -21,9 +22,16 @@ interface RootProps {
   defaultOpen?: boolean;
   /** Called when the user opens or closes the sheet (not when the `open` prop changes). */
   onOpenChange?: (open: boolean, details: OpenChangeDetails) => void;
+  /**
+   * Called once the sheet has finished closing (animation done, removed from the page). Keep the sheet rendered with
+   * `open={false}` so it can animate out, and clear what its content needs here, e.g. `() => setPending(null)`.
+   * Unmounting the sheet (`{open && <BottomSheet/>}`) skips the animation.
+   */
+  onExitComplete?: () => void;
   /**
    * Partial detents; `full` is always included. Default `[]`: the sheet opens straight to full (fit to short content).
-   * Each is a fraction of the available height (0.5) or a CSS length of visible sheet ('76px', '40dvh').
+   * Each is a fraction of the available height (0.5), a CSS length of visible sheet ('76px', '40dvh'), or `'header'`
+   * (exactly the header: a peek that shows the title and nothing under it).
    */
   detents?: readonly Detent[];
   /**
@@ -116,6 +124,11 @@ interface ContentProps extends ComponentPropsWithRef<'section'> {
 declare function Content({ ref, initialFocus, ...props }: ContentProps): import("react").JSX.Element;
 /** Sticky top part of the sheet. Mouse-draggable on desktop. */
 declare function Header(props: ComponentPropsWithRef<'div'>): import("react").JSX.Element;
+/**
+ * Sticky bottom part of the sheet, for actions. It stays at the bottom of the screen while the content scrolls, and at
+ * partial detents too. The controller sets `data-ybs-more` on the root while content is hidden behind it.
+ */
+declare function Footer(props: ComponentPropsWithRef<'div'>): import("react").JSX.Element;
 /** Visual grabber. Decorative; dragging works on the whole Header. */
 declare function Handle(props: ComponentPropsWithRef<'div'>): import("react").JSX.Element;
 declare function Title(props: ComponentPropsWithRef<'h2'>): import("react").JSX.Element;

package/dist/{sheet-BgvWfCR8.js → sheet-C1fUpy71.js}

@@ -163,6 +163,7 @@ function createSheetController(els, options) {
 	const closable = () => dismissible || closing;
 	let H = 0;
 	let full = 0;
+	let sheetH = 0;
 	let stops = [];
 	const markers = /* @__PURE__ */ new Map();
 	const closedMarker = makeMarker();
@@ -200,9 +201,26 @@ function createSheetController(els, options) {
 		if (d === "closed") return 0;
 		if (d === "full") return full;
 		if (typeof d === "number") return H * d;
-		probe.style.height = d;
+		probe.style.height = d === "header" ? `calc(${headerBottom()}px + var(--ybs-header-detent-offset, 0px))` : d;
 		return probe.getBoundingClientRect().height;
 	}
+	/**
+	* The `'header'` detent: how far the header reaches into the sheet (its bottom edge), so the peek shows exactly
+	* the header. Measured only while the header isn't stuck (content scrolled moves a sticky header down the sheet);
+	* otherwise the last measurement is kept. Styles can add to it with --ybs-header-detent-offset (/styled's floating
+	* adds its bottom gap).
+	*/
+	let headerPx = 0;
+	function headerBottom() {
+		const header = sheet.querySelector("[data-ybs-header]");
+		if (!header) return 0;
+		if (scroller.scrollTop <= full + 1) {
+			const box = sheet.getBoundingClientRect();
+			const scale = sheet.offsetHeight > 0 ? box.height / sheet.offsetHeight : 1;
+			headerPx = (header.getBoundingClientRect().bottom - box.top) / (scale || 1);
+		}
+		return headerPx;
+	}
 	const resolve = (d) => resolveStop(d, rawTop(d), stops);
 	const pos = (d) => resolve(d).top;
 	/** The lowest resting detent that isn't closed; also where open() goes by default. */
@@ -215,7 +233,7 @@ function createSheetController(els, options) {
 	}
 	function layout() {
 		H = scroller.clientHeight;
-		const sheetH = sheet.offsetHeight;
+		sheetH = sheet.offsetHeight;
 		full = Math.min(H, sheetH);
 		const partials = requested.filter((d) => d !== "closed" && d !== "full").map((d) => ({
 			detent: d,
@@ -223,6 +241,7 @@ function createSheetController(els, options) {
 		}));
 		stops = buildStops(partials, full, closable());
 		root.style.setProperty("--ybs-h", `${H}px`);
+		root.style.setProperty("--ybs-header-h", `${headerBottom()}px`);
 		const bleed = root.querySelector("[data-ybs-bleed]");
 		if (bleed) bleed.style.colorScheme = getComputedStyle(sheet).colorScheme;
 		root.toggleAttribute("data-ybs-fit", sheetH < H);
@@ -239,6 +258,7 @@ function createSheetController(els, options) {
 				markers.set(p.detent, m);
 			}
 			m.style.top = `${p.top}px`;
+			m.toggleAttribute("data-ybs-catch", p.detent === "header");
 			m.hidden = !stops.some((s) => s.detent === p.detent);
 		}
 	}
@@ -326,6 +346,7 @@ function createSheetController(els, options) {
 	* stays scrolled (see detachedDrag).
 	*/
 	let scrolled = false;
+	let more = false;
 	function paint(st, drop = 0) {
 		const shown = Math.max(Math.min(st, full) - drop, 0);
 		const progress = full > 0 ? Math.min(Math.max(shown / full, 0), 1) : 0;
@@ -338,6 +359,11 @@ function createSheetController(els, options) {
 			scrolled = s;
 			root.toggleAttribute("data-ybs-scrolled", s);
 		}
+		const m = sheetH > H + 1 && st < scroller.scrollHeight - scroller.clientHeight - 2;
+		if (m !== more) {
+			more = m;
+			root.toggleAttribute("data-ybs-more", m);
+		}
 	}
 	function onScroll() {
 		const st = scroller.scrollTop;
@@ -980,6 +1006,7 @@ var sheet_exports = /* @__PURE__ */ __exportAll({
 	Close: () => Close,
 	Content: () => Content,
 	Description: () => Description,
+	Footer: () => Footer,
 	Handle: () => Handle,
 	Header: () => Header,
 	Portal: () => Portal,
@@ -1030,7 +1057,7 @@ function initialFocusTarget(pref, modal, sheet) {
 /** Full only, like iOS (`[.large()]`), Base UI and Vaul. Partial detents are opt-in. */
 const DEFAULT_DETENTS = [];
 function Root(props) {
-	const { children, open: openProp, defaultOpen = false, onOpenChange, detents = DEFAULT_DETENTS, initialDetent, detent, onDetentChange, modal: modalProp = true, dismissible = true, fullscreen = false, recede = false, debug } = props;
+	const { children, open: openProp, defaultOpen = false, onOpenChange, detents = DEFAULT_DETENTS, initialDetent, detent, onDetentChange, modal: modalProp = true, dismissible = true, fullscreen = false, recede = false, debug, onExitComplete } = props;
 	const [openState, setOpenState] = useState(defaultOpen);
 	const open = openProp ?? openState;
 	const [mounted, setMounted] = useState(open);
@@ -1075,6 +1102,13 @@ function Root(props) {
 			else setMounted(false);
 		}
 	}, [open, mounted]);
+	const exitRef = useRef(onExitComplete);
+	exitRef.current = onExitComplete;
+	const wasMounted = useRef(mounted);
+	useEffect(() => {
+		if (wasMounted.current && !mounted) exitRef.current?.();
+		wasMounted.current = mounted;
+	}, [mounted]);
 	const onClosed = useCallback(() => {
 		debugRef.current?.(`onClosed (open=${open}, mounted=${mounted})`);
 		closing.current = false;
@@ -1369,6 +1403,16 @@ function Header(props) {
 		...props
 	});
 }
+/**
+* Sticky bottom part of the sheet, for actions. It stays at the bottom of the screen while the content scrolls, and at
+* partial detents too. The controller sets `data-ybs-more` on the root while content is hidden behind it.
+*/
+function Footer(props) {
+	return /* @__PURE__ */ jsx("div", {
+		"data-ybs-footer": "",
+		...props
+	});
+}
 /** Visual grabber. Decorative; dragging works on the whole Header. */
 function Handle(props) {
 	return /* @__PURE__ */ jsx("div", {
@@ -1401,4 +1445,4 @@ function Description(props) {
 		...props
 	});
 }
-export { Handle as a, Root as c, View as d, sheet_exports as f, Description as i, Title as l, Close as n, Header as o, checkCss as p, Content as r, Portal as s, Backdrop as t, Trigger as u };
+export { Footer as a, Portal as c, Trigger as d, View as f, Description as i, Root as l, checkCss as m, Close as n, Handle as o, sheet_exports as p, Content as r, Header as s, Backdrop as t, Title as u };

package/dist/styled.css

@@ -17,6 +17,7 @@
   --ybs-handle: light-dark(rgba(60, 60, 67, 0.3), rgba(235, 235, 245, 0.3));
   --ybs-divider: light-dark(rgba(60, 60, 67, 0.12), rgba(235, 235, 245, 0.12));
   --ybs-radius: 14px;
+  --ybs-title-size: 17px;
   /* Side padding of the body, matching the header. 0 for edge-to-edge lists that pad their own rows. */
   --ybs-body-padding: 16px;
   --ybs-backdrop: #000;
@@ -48,12 +49,16 @@
   padding-bottom: env(safe-area-inset-bottom, 0px);
   font-family: system-ui, -apple-system, sans-serif;
   max-width: var(--ybs-max-width); margin-inline: auto;
+  /* The body's real side inset, for content that reaches the edges (Sheet.Edge). The sheet is a size container so
+     a full-width sheet's inset (which depends on the sheet's width) resolves the same at any depth inside it. */
+  container-type: inline-size;
+  --ybs-body-inset: var(--ybs-body-padding);
 }
 /* Full width: the surface spans the window; header and body keep their full width (no corner seams) but pad
    their contents into a readable centred column. */
-.ybs-sheet.ybs-sheet-full { max-width: none; }
+.ybs-sheet.ybs-sheet-full { max-width: none; --ybs-body-inset: max(var(--ybs-body-padding), (100cqw - var(--ybs-content-width)) / 2); }
 .ybs-sheet-full > .ybs-header { padding-inline: max(16px, (100% - var(--ybs-content-width)) / 2); }
-.ybs-sheet-full > .ybs-body { padding-inline: max(var(--ybs-body-padding), (100% - var(--ybs-content-width)) / 2); }
+
 /* A page sheet sits lower than the receded page's top edge (+10px), so a strip of that page shows above it, like iOS. */
 [data-ybs-root]:has(.ybs-sheet-page):not([data-ybs-fullscreen]) { --ybs-inset: calc(env(safe-area-inset-top, 0px) + 22px); }
 /* A page sheet fills the screen at full even when its content is short (no fit-content). */
@@ -62,6 +67,26 @@
 .ybs-bar { display: grid; grid-template-columns: 1fr auto 1fr; align-items: center; gap: 12px; }
 .ybs-bar > .ybs-title { text-align: center; }
 .ybs-leading { justify-self: start; }
+/* Title with the ✕ beside it (closeButton without leading/trailing). */
+.ybs-title-row { display: flex; align-items: center; justify-content: space-between; gap: 12px; }
+.ybs-trailing:has(.ybs-close) { display: flex; align-items: center; gap: 8px; }
+/* The ✕: a soft filled 30px circle, with a 44px tap area. */
+.ybs-close {
+  flex: none; display: grid; place-items: center; width: 30px; height: 30px; margin: -7px -7px -7px 0; padding: 0;
+  border: 7px solid transparent; box-sizing: content-box; background: color-mix(in srgb, var(--ybs-muted) 18%, transparent);
+  background-clip: padding-box; border-radius: 50%; color: var(--ybs-muted); cursor: pointer;
+}
+.ybs-close:active { background-color: color-mix(in srgb, var(--ybs-muted) 30%, transparent); }
+.ybs-close svg { width: 12px; height: 12px; stroke: var(--ybs-muted); /* not currentColor: app button resets set color */ stroke-width: 1.8; stroke-linecap: round; fill: none; }
+/* Screen-reader close: off screen until focused (then a small pill in the header's corner). */
+.ybs-sr-close {
+  position: absolute; width: 1px; height: 1px; padding: 0; margin: -1px; overflow: hidden; clip-path: inset(50%);
+  white-space: nowrap; border: 0;
+}
+.ybs-sr-close:focus-visible {
+  top: 8px; right: 12px; width: auto; height: auto; margin: 0; padding: 4px 12px; overflow: visible; clip-path: none;
+  border-radius: 999px; background: var(--ybs-sheet-fg); color: var(--ybs-sheet-bg); font-size: 14px;
+}
 .ybs-trailing { justify-self: end; }
 /* Floating (iOS 26): at lower detents the sheet floats, inset from the sides and the bottom with large corners;
    over the last quarter of the travel to full it attaches (the gap closes, the bottom corners slide off-screen).
@@ -75,6 +100,8 @@
   clip-path: inset(0 var(--ybs-g) calc((100% - var(--ybs-visible, 0px)) * var(--ybs-float) + var(--ybs-g)) var(--ybs-g)
     round var(--ybs-rt) var(--ybs-rt) var(--ybs-rb) var(--ybs-rb));
 }
+/* A 'header' detent on a floating sheet: the clip lifts the bottom edge by the gap, so the peek grows by it. */
+[data-ybs-root]:has(.ybs-sheet-floating) { --ybs-header-detent-offset: var(--ybs-float-gap); }
 /* Fullscreen: square corners at the top (they would show the page through), header clear of the notch. */
 [data-ybs-fullscreen] .ybs-sheet, [data-ybs-fullscreen] .ybs-header {
   --ybs-r: calc(var(--ybs-radius) * (1 - var(--ybs-at-top)));
@@ -85,19 +112,47 @@
   background: var(--ybs-sheet-bg);
   border-radius: var(--ybs-radius) var(--ybs-radius) 0 0;
   padding: 6px 16px 12px;
-  border-bottom: 1px solid var(--ybs-divider);
+  /* The divider marks content scrolled under the header, so it only shows then (like iOS/Material bars);
+     at rest the header's bottom padding is the gap. data-ybs-scrolled is set by the controller. */
+  border-bottom: 1px solid transparent;
+  transition: border-bottom-color 150ms;
   /* Content scrolls under this sticky header; at fractional positions (device scaling, or a covered
      sheet's scale) a 1px sliver of it can show above. Cover it with the sheet colour. */
   box-shadow: 0 -2px 0 0 var(--ybs-sheet-bg);
 }
+[data-ybs-scrolled] .ybs-header { border-bottom-color: var(--ybs-divider); }
 .ybs-handle {
   width: 36px; height: 5px; border-radius: 3px;
   background: var(--ybs-handle);
   margin: 0 auto 10px;
 }
-.ybs-title { margin: 0; font-size: 17px; font-weight: 600; line-height: 1.3; }
+.ybs-eyebrow { display: block; margin-bottom: 2px; font-size: 13px; font-weight: 500; color: var(--ybs-muted); }
+.ybs-sr-only { position: absolute; width: 1px; height: 1px; overflow: hidden; clip-path: inset(50%); white-space: nowrap; }
+/* No title (a sheet named by aria-label): the header is just the grabber, without the space a title would need. */
+.ybs-header:has(> .ybs-handle:last-child), .ybs-header:has(> .ybs-handle + .ybs-sr-close:last-child) { padding-bottom: 0; }
+.ybs-title { margin: 0; font-size: var(--ybs-title-size); font-weight: 600; line-height: 1.3; }
 .ybs-description { margin: 4px 0 0; font-size: 14px; color: var(--ybs-muted); }
-.ybs-body { padding: 0 var(--ybs-body-padding) 12px; }
+.ybs-body { padding: 0 var(--ybs-body-inset) 12px; }
+/* Sheet.Edge: reaches the sheet's edges and pads its contents back in line with the body (a photo strip that
+   scrolls sideways, a full-width tappable row, a separator). */
+.ybs-edge { margin-inline: calc(-1 * var(--ybs-body-inset)); padding-inline: var(--ybs-body-inset); }
+/* Footer: actions pinned to the screen bottom. It takes the safe area from the sheet, and its line (like the
+   header's) shows only while content is hidden behind it (data-ybs-more, set by the controller). */
+.ybs-footer {
+  background: var(--ybs-sheet-bg);
+  padding: 12px var(--ybs-body-inset) calc(12px + env(safe-area-inset-bottom, 0px));
+  border-top: 1px solid transparent;
+  transition: border-top-color 150ms;
+  display: flex; gap: 8px; justify-content: flex-end; flex-wrap: wrap;
+}
+[data-ybs-more] .ybs-footer { border-top-color: var(--ybs-divider); }
+.ybs-sheet:has(> .ybs-footer) { padding-bottom: 0; }
+/* Floating: the clip lifts the bottom edge by the gap at lower detents; the footer stays above it. */
+.ybs-sheet-floating > .ybs-footer { bottom: var(--ybs-g); }
+/* Floating: the visible edge is the clip, a gap in from the sheet's box, so the side space adds the gap (fixed, not
+   following the float: padding that changed while dragging would reflow every frame). */
+.ybs-sheet.ybs-sheet-floating:not(.ybs-sheet-full) { --ybs-body-inset: calc(var(--ybs-body-padding) + var(--ybs-float-gap)); }
+.ybs-sheet-floating:not(.ybs-sheet-full) > .ybs-header { padding-inline: calc(16px + var(--ybs-float-gap)); }
 /* The page behind recedes (Sheet.Root recede + data-ybs-background on the app wrapper), like iOS: it scales back
    from the top of the screen, drops below the status bar and rounds its top corners over black. The wrapper needs
    its own background (html and body turn black). */

package/dist/styled.d.ts

@@ -1,8 +1,11 @@
 
-import { a as OpenChangeDetails, c as PortalProps, d as Trigger, f as TriggerProps, g as Detent, i as InteractionType, l as Root, m as ViewProps, n as ContentProps, o as OpenChangeReason, p as TriggerRenderProps, r as InitialFocus, s as Portal, t as Close, u as RootProps } from "./sheet-BOTt16RW.js";
+import { a as OpenChangeDetails, c as PortalProps, d as Trigger, f as TriggerProps, g as Detent, i as InteractionType, l as Root, m as ViewProps, n as ContentProps, o as OpenChangeReason, p as TriggerRenderProps, r as InitialFocus, s as Portal, t as Close, u as RootProps } from "./sheet-5lG9EBB5.js";
 import { ComponentPropsWithRef, ReactElement, ReactNode } from "react";
-/** Styled parts: same API as the headless `Sheet`, with the preset look. */
-export declare const Sheet: {
+/**
+ * Styled parts: the pieces `BottomSheet` is built from, with the preset look (same API as the headless `Sheet`).
+ * Prefer `BottomSheet`; use these only to arrange a sheet yourself.
+ */
+export declare const StyledSheet: {
   Root: typeof Root;
   Trigger: typeof Trigger;
   Close: typeof Close;
@@ -14,15 +17,24 @@ export declare const Sheet: {
   Handle: (p: import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>) => import("react").JSX.Element;
   Title: (p: import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLHeadingElement>, HTMLHeadingElement>) => import("react").JSX.Element;
   Description: (p: import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLParagraphElement>, HTMLParagraphElement>) => import("react").JSX.Element;
+  Footer: (p: import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>) => import("react").JSX.Element;
+  /** The padded content area, after `Header`: the same side space as the header, so text lines up with the title. */
+  Body: ({ className, ...p }: ComponentPropsWithRef<'div'>) => import("react").JSX.Element;
+  /**
+   * Content that reaches the sheet's edges, inside the body: a sideways photo strip, a full-width tappable row, a
+   * separator. Its contents stay lined up with the rest of the body. The inset is `--ybs-body-inset`.
+   */
+  Edge: ({ className, ...p }: ComponentPropsWithRef<'div'>) => import("react").JSX.Element;
 };
-export interface BottomSheetProps extends Omit<RootProps, 'children'> {
+interface BottomSheetBaseProps extends Omit<RootProps, 'children'> {
   /**
    * What opens the sheet. Content (text, elements) is placed inside our trigger button. A function renders your own
    * button instead: `trigger={(props) => <Button variant="paper" {...props}>Open</Button>}` (it receives `type`,
    * `onClick` and the ARIA state; put className, disabled, aria-label on your button).
    */
   trigger?: ReactNode | ((props: TriggerRenderProps) => ReactElement);
-  title: ReactNode;
+  /** A small label above the title (a section, a category). Part of the title, so screen readers read both. */
+  eyebrow?: ReactNode;
   description?: ReactNode;
   /**
    * - `'sheet'` (default): detents as given, a card-width sheet.
@@ -42,11 +54,25 @@ export interface BottomSheetProps extends Omit<RootProps, 'children'> {
    * reaches full. Tokens: --ybs-float-gap (8px), --ybs-float-radius (32px).
    */
   floating?: boolean;
-  /** Header bar slots, iOS navigation-bar style: e.g. `leading={<Sheet.Close>Cancel</Sheet.Close>}`. The title centres between them. */
+  /** Header bar slots, iOS navigation-bar style: e.g. `leading={<BottomSheet.Close>Cancel</BottomSheet.Close>}`. The title centres between them. */
   leading?: ReactNode;
   trailing?: ReactNode;
   /** Extra content placed in the sticky header under the title (e.g. a search field). */
   headerExtra?: ReactNode;
+  /**
+   * Actions pinned to the bottom of the screen (Cancel / Confirm, Show results). They stay reachable while a long
+   * sheet scrolls, reach the sheet's edges, and take the home-bar safe area. A line appears above them only while
+   * content is hidden behind them.
+   */
+  footer?: ReactNode;
+  /**
+   * A visible ✕ button in the header's top right that closes the sheet. Off by default. Without it, a dismissible
+   * sheet still has a close button that only screen readers announce (it shows when focused by keyboard), because
+   * swipes and the dimmed area aren't usable with VoiceOver.
+   */
+  closeButton?: boolean;
+  /** Accessible name of the close button (visible ✕ or screen-reader only). Default `'Close'`. */
+  closeLabel?: string;
   /**
    * Where focus goes when the sheet opens, like Base UI's: an element ref, `false`, `true` (the sheet), or a function
    * of how it was opened, e.g. `(type) => type !== 'touch' && saveRef.current`. Default: the sheet for a modal sheet,
@@ -57,9 +83,24 @@ export interface BottomSheetProps extends Omit<RootProps, 'children'> {
   className?: string;
   contentProps?: ComponentPropsWithRef<'section'>;
 }
+/**
+ * Every sheet needs a name for screen readers ("Share photo, dialog"): a visible `title`, or an `aria-label` for a
+ * sheet without one (an action list, a photo viewer). TypeScript refuses a sheet with neither.
+ */
+export type BottomSheetProps = BottomSheetBaseProps & ({
+  title: NonNullable<ReactNode>;
+  'aria-label'?: string;
+} | {
+  title?: undefined; /** Names a sheet that has no visible title. */
+  'aria-label': string;
+});
 /**
  * The simple path:
  *   <BottomSheet trigger="Open" title="Settings">…</BottomSheet>
  */
-export declare function BottomSheet({ trigger, title, description, variant, floating, width, leading, trailing, headerExtra, initialFocus, children, className, contentProps, ...rootProps }: BottomSheetProps): import("react").JSX.Element;
+export declare function BottomSheet({ trigger, title, eyebrow, description, variant, floating, width, leading, trailing, headerExtra, footer, closeButton, closeLabel, initialFocus, children, className, contentProps, 'aria-label': ariaLabel, ...rootProps }: BottomSheetProps): import("react").JSX.Element;
+export declare namespace BottomSheet {
+  var Edge: ({ className, ...p }: ComponentPropsWithRef<'div'>) => import("react").JSX.Element;
+  var Close: typeof Close;
+}
 export type { ContentProps, Detent, InitialFocus, InteractionType, OpenChangeDetails, OpenChangeReason, PortalProps, RootProps, TriggerProps, TriggerRenderProps, ViewProps };

package/dist/styled.js

@@ -1,5 +1,5 @@
 'use client';
-import { a as Handle, c as Root, d as View, i as Description, l as Title, n as Close, o as Header, p as checkCss, r as Content, s as Portal, t as Backdrop, u as Trigger } from "./sheet-BgvWfCR8.js";
+import { a as Footer, c as Portal, d as Trigger, f as View, i as Description, l as Root, m as checkCss, n as Close, o as Handle, r as Content, s as Header, t as Backdrop, u as Title } from "./sheet-C1fUpy71.js";
 import { useEffect } from "react";
 import { jsx, jsxs } from "react/jsx-runtime";
 // src/styled/index.tsx
@@ -10,8 +10,11 @@ function withClass(Comp, cls) {
 		className: cx(cls, p.className)
 	});
 }
-/** Styled parts: same API as the headless `Sheet`, with the preset look. */
-const Sheet = {
+/**
+* Styled parts: the pieces `BottomSheet` is built from, with the preset look (same API as the headless `Sheet`).
+* Prefer `BottomSheet`; use these only to arrange a sheet yourself.
+*/
+const StyledSheet = {
 	Root,
 	Trigger,
 	Close,
@@ -29,50 +32,94 @@ const Sheet = {
 	Header: withClass(Header, "ybs-header"),
 	Handle: withClass(Handle, "ybs-handle"),
 	Title: withClass(Title, "ybs-title"),
-	Description: withClass(Description, "ybs-description")
+	Description: withClass(Description, "ybs-description"),
+	Footer: withClass(Footer, "ybs-footer"),
+	/** The padded content area, after `Header`: the same side space as the header, so text lines up with the title. */
+	Body: ({ className, ...p }) => /* @__PURE__ */ jsx("div", {
+		...p,
+		className: cx("ybs-body", className)
+	}),
+	/**
+	* Content that reaches the sheet's edges, inside the body: a sideways photo strip, a full-width tappable row, a
+	* separator. Its contents stay lined up with the rest of the body. The inset is `--ybs-body-inset`.
+	*/
+	Edge: ({ className, ...p }) => /* @__PURE__ */ jsx("div", {
+		...p,
+		className: cx("ybs-edge", className)
+	})
 };
 /**
 * The simple path:
 *   <BottomSheet trigger="Open" title="Settings">…</BottomSheet>
 */
-function BottomSheet({ trigger, title, description, variant = "sheet", floating = false, width = variant === "page" ? "full" : "card", leading, trailing, headerExtra, initialFocus, children, className, contentProps, ...rootProps }) {
+function BottomSheet({ trigger, title, eyebrow, description, variant = "sheet", floating = false, width = variant === "page" ? "full" : "card", leading, trailing, headerExtra, footer, closeButton = false, closeLabel = "Close", initialFocus, children, className, contentProps, "aria-label": ariaLabel, ...rootProps }) {
 	const root = variant === "page" ? {
 		recede: true,
 		...rootProps
 	} : rootProps;
 	const bar = leading != null || trailing != null;
-	return /* @__PURE__ */ jsxs(Sheet.Root, {
+	const heading = title == null ? null : /* @__PURE__ */ jsxs(StyledSheet.Title, { children: [eyebrow != null && /* @__PURE__ */ jsxs("span", {
+		className: "ybs-eyebrow",
+		children: [eyebrow, /* @__PURE__ */ jsx("span", {
+			className: "ybs-sr-only",
+			children: ", "
+		})]
+	}), title] });
+	const close = closeButton ? /* @__PURE__ */ jsx(StyledSheet.Close, {
+		className: "ybs-close",
+		"aria-label": closeLabel,
+		children: /* @__PURE__ */ jsx("svg", {
+			viewBox: "0 0 12 12",
+			"aria-hidden": "true",
+			children: /* @__PURE__ */ jsx("path", { d: "M2 2l8 8M10 2l-8 8" })
+		})
+	}) : null;
+	const srClose = !closeButton && rootProps.dismissible !== false && /* @__PURE__ */ jsx(StyledSheet.Close, {
+		className: "ybs-sr-close",
+		children: closeLabel
+	});
+	return /* @__PURE__ */ jsxs(StyledSheet.Root, {
 		...root,
-		children: [typeof trigger === "function" ? /* @__PURE__ */ jsx(Sheet.Trigger, { render: trigger }) : trigger != null && /* @__PURE__ */ jsx(Sheet.Trigger, {
+		children: [typeof trigger === "function" ? /* @__PURE__ */ jsx(StyledSheet.Trigger, { render: trigger }) : trigger != null && /* @__PURE__ */ jsx(StyledSheet.Trigger, {
 			className: "ybs-trigger",
 			children: trigger
-		}), /* @__PURE__ */ jsxs(Sheet.Portal, { children: [root.modal !== false && /* @__PURE__ */ jsx(Sheet.Backdrop, {}), /* @__PURE__ */ jsx(Sheet.View, { children: /* @__PURE__ */ jsxs(Sheet.Content, {
+		}), /* @__PURE__ */ jsxs(StyledSheet.Portal, { children: [root.modal !== false && /* @__PURE__ */ jsx(StyledSheet.Backdrop, {}), /* @__PURE__ */ jsx(StyledSheet.View, { children: /* @__PURE__ */ jsxs(StyledSheet.Content, {
 			...contentProps,
+			"aria-label": ariaLabel ?? contentProps?.["aria-label"],
 			initialFocus,
 			className: cx(width === "full" && "ybs-sheet-full", variant === "page" && "ybs-sheet-page", floating && "ybs-sheet-floating", className, contentProps?.className),
-			children: [/* @__PURE__ */ jsxs(Sheet.Header, { children: [
-				/* @__PURE__ */ jsx(Sheet.Handle, {}),
-				bar ? /* @__PURE__ */ jsxs("div", {
-					className: "ybs-bar",
-					children: [
-						/* @__PURE__ */ jsx("div", {
-							className: "ybs-leading",
-							children: leading
-						}),
-						/* @__PURE__ */ jsx(Sheet.Title, { children: title }),
-						/* @__PURE__ */ jsx("div", {
-							className: "ybs-trailing",
-							children: trailing
-						})
-					]
-				}) : /* @__PURE__ */ jsx(Sheet.Title, { children: title }),
-				description != null && /* @__PURE__ */ jsx(Sheet.Description, { children: description }),
-				headerExtra
-			] }), /* @__PURE__ */ jsx("div", {
-				className: "ybs-body",
-				children
-			})]
+			children: [
+				/* @__PURE__ */ jsxs(StyledSheet.Header, { children: [
+					/* @__PURE__ */ jsx(StyledSheet.Handle, {}),
+					bar ? /* @__PURE__ */ jsxs("div", {
+						className: "ybs-bar",
+						children: [
+							/* @__PURE__ */ jsx("div", {
+								className: "ybs-leading",
+								children: leading
+							}),
+							heading ?? /* @__PURE__ */ jsx("span", {}),
+							/* @__PURE__ */ jsxs("div", {
+								className: "ybs-trailing",
+								children: [trailing, close]
+							})
+						]
+					}) : close ? /* @__PURE__ */ jsxs("div", {
+						className: "ybs-title-row",
+						children: [heading ?? /* @__PURE__ */ jsx("span", {}), close]
+					}) : heading,
+					description != null && /* @__PURE__ */ jsx(StyledSheet.Description, { children: description }),
+					headerExtra,
+					srClose
+				] }),
+				/* @__PURE__ */ jsx(StyledSheet.Body, { children }),
+				footer != null && /* @__PURE__ */ jsx(StyledSheet.Footer, { children: footer })
+			]
 		}) })] })]
 	});
 }
-export { BottomSheet, Sheet };
+/** Content that reaches the sheet's edges (see `StyledSheet.Edge`), for use inside `<BottomSheet>`. */
+BottomSheet.Edge = StyledSheet.Edge;
+/** Closes the sheet it's in, e.g. a Cancel button in `leading` or `footer`. */
+BottomSheet.Close = StyledSheet.Close;
+export { BottomSheet, StyledSheet };

package/dist/styles.css

@@ -60,12 +60,20 @@
   position: absolute; left: 0; width: 1px; height: 1px;
   scroll-snap-align: start; pointer-events: none;
 }
+/* The 'header' peek catches flings (like Material's collapsed state); other partial detents let a fling run past. */
+[data-ybs-marker][data-ybs-catch] { scroll-snap-stop: always; }
 /* scroll-snap-stop: a fling may not skip the full position, in either direction. This is the native
    way to stop momentum at the content top / full detent; the JS guard is only a fallback. (Firefox
    Android: the JS overflow toggle made the next touch get swallowed as a "stop the fling" tap.) */
 [data-ybs-sheet] { position: relative; scroll-snap-align: start; scroll-snap-stop: always; outline: none; }
 [data-ybs-root][data-ybs-fit] [data-ybs-sheet] { scroll-snap-align: end; }
 [data-ybs-header] { position: sticky; top: 0; z-index: 1; }
+[data-ybs-footer] {
+  position: sticky; bottom: 0; z-index: 1;
+  /* At a peek lower than header + footer, pinning the footer to the screen bottom would cover the header. Push it
+     down so it sits under the header instead (off screen at a header peek), and let it pin once there's room. */
+  translate: 0 max(0px, var(--ybs-header-h, 0px) + var(--ybs-header-detent-offset, 0px) + 100% - var(--ybs-visible, 100vh));
+}
 /* Content scrolled: a drag on the header moves the whole sheet (JS, "detached drag"), like native, instead of
    scrolling the content back first. */
 [data-ybs-root][data-ybs-scrolled] [data-ybs-drag] { touch-action: none; }
@@ -83,7 +91,7 @@
   }
   [data-ybs-root][data-ybs-modeless] [data-ybs-sheet] > *::-webkit-scrollbar { display: none; }
   /* 1px of horizontal overflow, measured from the padding box so side padding can't absorb it. */
-  [data-ybs-root][data-ybs-modeless] [data-ybs-sheet] > *:not([data-ybs-header]) { position: relative; }
+  [data-ybs-root][data-ybs-modeless] [data-ybs-sheet] > *:not([data-ybs-header], [data-ybs-footer]) { position: relative; }
   [data-ybs-root][data-ybs-modeless] [data-ybs-sheet] > *::after {
     content: ''; position: absolute; top: 0; left: 0; width: calc(100% + 1px); height: 1px; pointer-events: none;
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yourrealm/bottom-sheet",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Native-feeling bottom sheet for the web. One native scroller for sheet travel and content.",
   "license": "MIT",
   "repository": {
@@ -27,7 +27,8 @@
   "files": [
     "dist",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "CHANGELOG.md"
   ],
   "exports": {
     ".": {
@@ -59,7 +60,7 @@
     "build": "tsdown && node scripts/build-css.mjs",
     "test": "vitest run",
     "typecheck": "tsc -p .",
-    "pack:check": "node scripts/prepack.mjs && pnpm build && pnpm pack; rm -f README.md LICENSE",
-    "release": "node scripts/prepack.mjs && pnpm build && pnpm publish --access public; rm -f README.md LICENSE"
+    "pack:check": "node scripts/prepack.mjs && pnpm build && pnpm pack; rm -f README.md LICENSE CHANGELOG.md",
+    "release": "node scripts/prepack.mjs && pnpm build && pnpm publish --access public; rm -f README.md LICENSE CHANGELOG.md"
   }
 }