@astryxdesign/core 0.4.6-canary.f30c604 → 0.4.7-canary.2ce1983

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # @xds/core
 
+# 0.4.7
+
+#### Fixes
+
+- BottomSheet: a non-modal sheet now colours the iOS 26 Safari toolbar strip with its own surface instead of letting the page show through behind the address bar (#5342).
+- BottomSheet: a tap inside the sheet is a tap, and the sheet leaves on an exit curve (#5326).
+  Two defects, both of which read as "the sheet closes with no animation" — reported against the touch DateInput picker, which is a Bottom Sheet.
+
+  **A tap inside the sheet started a one-pixel drag.** The sheet body carries the pull-to-dismiss handlers, and they promoted to a sheet drag on _any_ downward movement. A finger is never still, so the pixel or two a tap drifts began a drag — and a live drag suppresses the panel's transition, correctly, because a dragged sheet must track the finger rather than lag it. The close that the tap triggered landed inside that window, so the sheet jumped to its closed position with no transition. Tapping the picker's Save button hit this every time; tapping the scrim never did, because the scrim is the dialog itself and arms no gesture. Promotion now needs 8px of travel — the conventional tap slop, well under what a deliberate pull covers in its first frames — in both the pointer and touch paths. The gesture's transition suppression is also scoped to a sheet that is open, so it cannot straddle an exit.
+
+  **The exit ran on the entrance's curve.** `--ease-standard` is `cubic-bezier(0.24, 1, 0.4, 1)`, a decelerate curve: it spends its speed immediately and coasts. Right for an entrance, wrong for an exit. Measured on device (iPhone, real Safari), a scrim tap put the sheet half off-screen in 59ms of the 410ms transition and 90% off in 163ms, with the dim gone before it — so the close was over before the eye could follow it. The closing state now carries an accelerating curve of its own, `cubic-bezier(0.3, 0, 0.6, 0.6)`: away from rest, gathering speed, quickest as it leaves the screen, and moving within ~50ms so it reads as one departure rather than a hesitation and a snap. Only the curve changes — the exit keeps `--duration-medium`, the entrance's band, which is what keeps it legible under a theme that scales the motion scale down (neutral's medium is 300ms against the base 410ms).
+
+  The scrim leaves with the sheet: while closing, the dim runs `linear` rather than the decelerate token. A fade covers no distance, so front-loading its progress just ends it early — the reasoning the touch date picker's surface swap already carries. `BottomSheetSwitcher` gets the same treatment when its flow closes; a handoff between two sheets is not a close and is unchanged.
+- `useListFocus` no longer swallows Escape when no `onEscape` was supplied. The hook called `preventDefault()` on every Escape — a habit inherited from the arrow keys, which share the handler and need it to suppress page scroll — so a list with nothing to dismiss still marked the key handled, and a surrounding layer that defers to `defaultPrevented` (a focus trap, a native popover) never got its turn. Escape is now consumed only when an `onEscape` is passed. Arrow, Home and End handling is unchanged (#5346).
+  Behaviour change: `AvatarGroup`, `ButtonGroup`, `Outline`, `Pagination`, `SegmentedControl`, `TabList` and `Toolbar` pass no `onEscape`, so an Escape pressed inside one of them now reaches the surrounding layer and can dismiss it — the point of the fix, but a host that counted on the key stopping there will notice. `NavHeadingMenu` does the same when it renders without a menu close handler. Menus and flyouts that do pass `onEscape` are unaffected. `patch`, not `[breaking]`: the swallowing was never a contract — the hook documented Escape only as "custom callback", and no component advertised consuming the key.
+- TabList: the selected tab now carries `aria-current="true"` — ARIA's generic "current item within a set" — instead of `aria-current="page"`. The strip is a `<nav>` and stays one, but it is used to switch views in place at least as often as it is used to navigate, and on those uses `page` asserted a page change that never happened. Assistive tech announced the selected tab as the _current page_ even when nothing had navigated; it now announces it as the _current item_, which is true either way. A tab given an `href` still renders an anchor and still reads as a link — its current marker is just less specific than it was. No role changes and no new props. (#5347)
+
+#### Contributors
+
+Thanks to everyone who contributed to this release:
+
+- @cixzhang
+- @imdreamrunner
+
+---
+
 # 0.4.6
 
 #### New Features
@@ -22,6 +48,7 @@
   Nothing else is published, on purpose. There is no export that forces a surface: the touch picker is reachable by being on a touch device, which is the only place it is worth looking at. The media query the switch runs on is an internal constant, not an export — six other core components write `@media (pointer: coarse)` inline rather than sharing one, and nothing has asked to ask the same question. The picker's two sizes (the 44px day cell, the 28px wheel row) are compile-time constants rather than theme variables — the day size is an accessibility floor, and a variable a theme can quietly lower is not a floor. And the sheet's header button is addressed by a `data-` attribute rather than a theme target, because nothing has asked to restyle it. Each of those is additive later and awkward to withdraw once shipped.
 
   The wheels also answer a mouse now. A wheel is a scroll container, so a finger pans it for free; a mouse got nothing, because browsers do not drag-scroll an overflow container — pressing and pulling on the one control shaped like a thing you spin did nothing at all. Dragging with a mouse works, and fixes a related bug on the way: BottomSheet begins its own drag from a `pointerdown` on its body and captures the pointer for it, so a click on a wheel row that wobbled more than a pixel or two used to select nothing.
+
 - Export `useLocale` and `useCollator` for provider-backed formatting and comparison (#5194)
 - RadioListItem: the `radio-list-item` row theme target now carries `size`, `selected`, and `disabled` state variants (matching `multi-selector-option`), so themes can style selected or disabled rows (#5143).
 - RadioListItem: the `radio-list-item` theme target now rides the painting row element (converging with `list-item`), so a theme can style the row's hover background, padding, and border radius — previously it sat on a layout-only wrapper that painted nothing. The default (unthemed) row appearance is unchanged: it stays a bare surface with no row padding, radius, or hover/selected background (only the radio indicator tints on hover) (#5143).
@@ -42,6 +69,7 @@
   On `Section` the matching `--container-padding-*` custom property moves with the prop, so bleed children (`Table`, `Divider`, a nested `Section`) keep compensating against the padding actually applied.
 
   Existing code is unaffected: `padding`, `paddingInline` and `paddingBlock` behave exactly as before, and their generated class output is unchanged.
+
 - Selector: add the `selector-option-row` theme target on the dropdown option row, carrying `size` plus `selected`/`disabled` state — so a theme can restyle row padding and density directly (mirroring `multi-selector-option`), instead of reaching the bare `role="option"` element with a structural selector (#5179).
 - MediaTheme: add `mode="auto"` and `mode="off"` (#5299)
   A theme is free to define `--color-background-inverted` as something that is not inverted — and a component that hardcodes `mode="dark"` then paints white text on pale grey at 1.25:1. The surface color is a runtime value and the mode was a compile-time guess, so no amount of care in the component could catch it.
@@ -51,6 +79,7 @@
   When the backdrop is not knowable from CSS — during SSR, on the first client frame, and most often behind a `background-image`, whose pixels need sampling (see `useImageMode`) rather than a computed style — `auto` uses the new `fallback` prop instead of guessing.
 
   Toast now uses `mode="auto"`, with its previous rule kept only as that fallback. Every stock Astryx surface renders exactly as before.
+
 - Tooltip and HoverCard: tap to open where there is no hover (#5248)
   Hover is the one trigger a touch screen cannot express, and both components were answering that badly. `Tooltip` suppressed itself on any device reporting `(hover: none)`, so its content — often the only label an icon button has — was simply unreachable on a phone. `HoverCard` did nothing at all: the `mouseenter` a tap synthesizes opened the card on every tap of its trigger, over the control the user was aiming at, with no gesture that closed it again.
 
@@ -71,11 +100,13 @@
   The indicator also kept its negative overlap margin when it was the first child of a group, hanging 12px outside the group's own box. It now carries the same `:not(:first-child)` guard `Avatar` already had. And a negative `count` rendered the string `+-3` and announced "-3 more"; since the documented shape for the prop is `total - visibleCount`, which goes negative whenever the list is shorter than the slice, it now clamps at zero.
 
   Docs: the guidance told readers to "set max to limit visible avatars", and there is no `max` prop. The API is compositional on purpose, so the consumer slices; the guidance now says that. The keyboard behaviour names the APG roving tabindex technique it implements, and `size` now says that the group's value wins over each child avatar's own `size`, including when the group leaves it at the default.
+
 - Blockquote: the `cite` attribution renders as a bare `<cite>` instead of being wrapped in a `<footer>`, which was becoming a `contentinfo` document landmark. Also guards the slot with `isRenderable`, so `cite={condition && author}` no longer emits an empty `<cite>`, and wraps long unbroken words instead of overflowing (#5144).
 - Bottom Sheet: float the grab handle so content sits closer to the top (#5222)
   The drag area above the sheet's content was a 48px row in the sheet's flex column, pushing everything below it down by its full height and reading as an empty band above the first line of content.
 
   The bar is now 24px and floats over the content: the scrolling area starts at the sheet's top edge and rides up under the pill, so a heading sits 24px closer to the top. The pill is 4px tall centered in the band, so it occupies only 10-14px from the edge — inside the top padding a content wrapper already provides — and a surface gradient behind it keeps it legible over whatever sits or scrolls beneath.
+
 - BottomSheet: give the sheet one uniform edge against the scrim. Two things were wrong in dark mode. The sheet drew no edge of its own — surface and scrim sit a few RGB steps apart and the `--shadow-high` drop shadow is black on near-black, so the left and right edges were invisible (measured 1.16:1 boundary contrast in dark against 2.89:1 in light); it now carries a `--border-width` / `--color-border` hairline on its three scrim-facing edges, the same treatment MobileNav gives its scrim-facing edge. And under a theme that packs an inset ring into `--shadow-high` (every bundled theme adds one in dark mode) that ring was painted over by an opaque content wrapper such as `Section`, so it showed only in the gap below where the content ended and the side edges appeared to change width partway down; the scrolling body now paints the surface across the sheet's whole inner box, hiding the ring evenly (#5305).
 - Breadcrumbs: button crumbs keep the link's vertical padding, the variant reaches the item theme targets, and interactive crumbs paint the shared focus ring (#5332)
 - DateInput's touch calendar no longer rests between two months (#5319)
@@ -86,6 +117,7 @@
   The rest position is now corrected rather than trusted: once the gesture is genuinely over — touch released, the scroller quiet, AND its offset confirmed unchanged across a frame — a scroller that is off a pane boundary is moved to the nearest one. A scroller the browser snapped for itself is left alone, so nothing extra happens on Chrome, and sub-pixel drift on a fractional viewport is ignored.
 
   That last condition is what keeps the fix from becoming a worse bug than the one it fixes. A quiet period is not proof of rest: iOS runs its own snap animation for a few hundred milliseconds after the finger lifts and fires scroll events irregularly while it does, so a correction that trusts quiet alone can land mid-animation, round an offset still travelling toward next month back to the month it came from, and reverse the swipe.
+
 - A disabled element answers the pointer with `default`, never an interactive cursor. Every `cursor` in core and lab carries `':is(:disabled,[aria-disabled="true"])': 'default'`, and the reset gives the same cursor to any disabled element that declares none — `[aria-disabled]` included, which previously got nothing. A lint rule and a Chromium sweep over every story keep it that way. Disabled elements sealed behind `pointer-events: none` are unchanged: the pointer never reaches them, so their cursor comes from an ancestor — which is why the guarantee is `default` rather than a distinct disabled cursor the library could only paint on some of them (#5323).
 - Disabled elements no longer paint a hover state: every self-`:hover` in core and lab, and every `:hover` a theme authors, now carries the zero-specificity guard `:hover:where(:not(:disabled,[aria-disabled="true"]))`, so existing overrides weigh exactly what they weighed before. A lint rule and a Chromium sweep over every story keep it that way (#5247).
 - InputClearButton: the clear (✕) affordance now meets the WCAG 2.5.8 AA 24×24 minimum on touch. The shared button rendered a 20px glyph with a 20px tap target, so every input that clears through it — Typeahead, Tokenizer, FileInput and the rest of the family — was under the floor on a phone. An `::after` overlay now expands the tappable region to 24×24, gated behind `@media (pointer: coarse)`: on a fine pointer the overlay is not generated at all, because a mouse is precise enough, an unconditional overlay could overlap neighboring controls in dense desktop layouts, and an overlay covering the button would take hover away from the `astryx-input-clear-icon` theme target. The visual glyph is unchanged at every breakpoint, and the overlay stops at 24px so it stays clear of the 8px adornment gap and the input's own caret area (#4956).
@@ -97,6 +129,7 @@
   The reset now lives in one place (`overlayPaddingReset`, exported from `@astryxdesign/core/Layout`) instead of being hand-copied per overlay, and moved onto the `useLayer` root, which covers every layer surface at once. Values descendants subtract are zeroed; values they add are cleared to `initial` so readers fall through to their own default rather than losing their padding.
 
   Section's padding propagation moved from the public `--astryx-section-padding` token to a private `--_section-padding-propagated`. The two carried different authority under one name — a theme's value versus one ancestor's — and an overlay could not drop the inherited one without blanking the theme's. Propagated values still win over the theme for nested sections, so behavior is unchanged. Themes are unaffected: `--astryx-section-padding` remains the public token and still reaches inside overlays.
+
 - Theming: a physical `paddingTop`/`paddingBottom` now reaches the container padding expansion, so `card`, `dialog`, `section` and `number-input` track it the way they already track the logical spellings. A physical block longhand matched none of the padding property names the expansion recognizes, so it landed raw on the element while the component's internals kept reading the default — the NumberInput stepper column came up ~10px short of the field edges, and container bleed compensated by the wrong amount. Mixing spellings was worse than either alone: `padding: '10px'` plus `paddingTop: '14px'` published 10px in the tokens while the element painted 14px on top. `padding-top` and `padding-bottom` ARE the block edges in every horizontal writing mode, so this normalization assumes no direction. `paddingLeft`/`paddingRight` are deliberately unchanged: they are direction-relative — left is inline-start in LTR and inline-end in RTL — and the tokens are consumed by logical properties, so routing them would silently move the padding to the opposite edge under RTL. They keep their physical meaning, exactly as before (#5244).
 - `DateInput`, `DateTimeInput`, `DateRangeInput`, and `Calendar` now format and parse dates using the ambient `InternationalizationProvider` locale instead of the host/browser locale. `plainDateFormat` (backing `formatSharedDate`) previously called `Intl.DateTimeFormat(undefined, ...)`, and `dateParser`'s day/month disambiguation heuristic for ambiguous numeric input (e.g. `3/4/2026`) called `Intl.DateTimeFormat()` with no locale at all, so a tree wrapped in a non-English `locale` still formatted and parsed dates using the host locale (#5120).
 - Use the InternationalizationProvider locale for sorting, formatting, and speech defaults (#5195)
@@ -107,11 +140,13 @@
   Locking background scroll hides the document's scrollbar. Where that scrollbar takes layout space — Windows/Linux desktop, and macOS set to always show scroll bars — hiding it widened the layout viewport by its width (~15px), so the whole page reflowed sideways behind the overlay and back again on close.
 
   Both scroll locks now hold that gutter open with `scrollbar-gutter: stable` for the duration of the lock, which keeps `position: fixed` chrome (sticky headers, toast viewports) still as well as in-flow content. Pages with no space-taking scrollbar, and pages that already set `scrollbar-gutter` themselves, are left alone. Engines without `scrollbar-gutter` support fall back to padding the measured difference.
+
 - SegmentedControl: keep item labels on a single line, truncating overflow with an ellipsis instead of wrapping to multiple lines (#5035)
 - Selector: `SelectorOptionData` gains `description`, and the closed trigger now shows the selected option instead of just its label. The two-line option row `SelectorOption` draws was unreachable from the `options` prop — the data type carried only `value/label/disabled/icon` — so consumers kept a side map of descriptions keyed by value and re-rendered the row through `renderOption`. `description` now sits on the option data and `DefaultOption` forwards it. On the trigger, the selected option's own `icon` renders in the closed state (`startIcon` still wins when set, so a pinned field icon never doubles up), which retires the app-side `startIcon={value === 'x' ? … : …}` mirroring of state the component already knows. `renderValue` is the seam for drawing the selection yourself — the description included (#5202).
   [feat] Item: new `layout` prop — `'stacked'` (default, unchanged) or `'inline'`, which keeps the description on the label's line with the description ellipsizing first. The inline row centers its two lines rather than sharing a baseline: two font sizes on one baseline make a line box taller than either line, which would push a fixed-height host off its size token. Every row built on `Item` gets the axis, `SelectorOption` included.
 
   [fix] Selector: the trigger is sized by padding rather than a fixed height, so it is the `--size-element-*` token for a one-line value (28/32/36) and exactly one text line taller for a two-line one (48/52/56). The token and a text line are both multiples of 4, so every trigger lands on the 4px rhythm and lines up with the Buttons and inputs beside it — and no prop chooses the height, the content does. It previously swapped the fixed height for a minimum whenever `renderValue` was passed, keyed on the prop being present rather than on the content needing the room: a one-line value measured 39px and a two-line one 58px at _every_ size, so the `size` prop stopped affecting the trigger at all. Inside an `InputGroup`, where the group pins the row, the relaxed height did nothing and the content bled 4px through its own border. The group owns the row now and the trigger clamps its own value box to it, so nothing a caller draws can paint over the rows above and below: a `SelectorOption` folds onto one line and ellipsizes, and any other node is cut off at the row's edge. The trigger also stops asserting a height floor of its own there, so a control sized above its group — `<InputGroup size="md">` around a `size="lg"` control — sits in the group's row instead of growing it. The trigger's line box is pinned to that same token rather than a ratio, so the coarse-pointer font bump — and any theme that changes `--font-size-base` — grows the glyphs without moving the control off its size token.
+
 - `Slider` with `orientation="vertical"` now gets the same 24px touch hit area the horizontal one got: its track was still only 20px wide on coarse pointers, under the WCAG 2.5.8 AA minimum. The whole track is the tap target for both orientations — the fix that floored the horizontal track's block size did nothing for vertical, whose short axis is the inline one — so the inline size is now floored to 24px on touch, with the same `@media (pointer: coarse)` gate. The rail, fill, marks and thumb all center on the inline 50%, so nothing visible moves and desktop is untouched (#5173).
 - `@astryxdesign/core/theme/syntax` is importable from a server component again: the presets are data, not client references (#5076).
   The subpath's barrel carried `'use client'`, and it is the only entry point for the syntax module. React therefore replaced _every_ export with a client reference for a server importer — including `dracula`, `oneLight`, `allSyntaxPresets`, `syntaxTokenDefaults` and `defineSyntaxTheme`, none of which need a boundary. Reading a preset in a Next.js server module (deriving a code-block ground, emitting theme CSS at build time) got a proxy instead of data, so `preset.tokens` was `undefined` and the failure surfaced far from its cause — the same import under plain Node worked perfectly.

package/dist/BottomSheet/BottomSheet.d.ts

@@ -12,6 +12,7 @@
  *
  * SYNC: When modified, update these files to stay in sync:
  * - /packages/core/src/BottomSheet/BottomSheetPanel.tsx
+ * - /packages/core/src/BottomSheet/BottomSheetEdgeTint.tsx
  * - /packages/core/src/BottomSheet/BottomSheet.doc.mjs
  * - /packages/core/src/BottomSheet/BottomSheet.test.tsx
  * - /packages/core/src/BottomSheet/BottomSheetSwitcher.tsx

package/dist/BottomSheet/BottomSheet.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"BottomSheet.d.ts","sourceRoot":"","sources":["../../src/BottomSheet/BottomSheet.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAOL,KAAK,SAAS,EACf,MAAM,OAAO,CAAC;AAEf,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAC5C,OAAO,KAAK,EAAC,aAAa,EAAC,MAAM,WAAW,CAAC;AAc7C,YAAY,EAAC,iBAAiB,EAAE,oBAAoB,EAAC,MAAM,oBAAoB,CAAC;AAChF,OAAO,KAAK,EAAC,iBAAiB,EAAE,oBAAoB,EAAC,MAAM,oBAAoB,CAAC;AAyEhF,UAAU,sBAAuB,SAAQ,SAAS,CAAC,cAAc,CAAC;IAChE,qDAAqD;IACrD,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IAEhC,sCAAsC;IACtC,KAAK,EAAE,MAAM,CAAC;IAEd,0EAA0E;IAC1E,QAAQ,EAAE,SAAS,CAAC;IAEpB,wGAAwG;IACxG,MAAM,CAAC,EAAE,iBAAiB,GAAG,MAAM,GAAG,MAAM,CAAC;IAE7C;;;;;;;OAOG;IACH,UAAU,CAAC,EAAE,aAAa,CAAC,oBAAoB,CAAC,CAAC;IAEjD;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,aAAa,CAAC;CACzB;AAED,UAAU,0BAA2B,SAAQ,sBAAsB;IACjE,MAAM,EAAE,OAAO,CAAC;IAChB,YAAY,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;IACxC,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,OAAO,CAAC,EAAE,KAAK,CAAC;CACjB;AAED,UAAU,wBAAyB,SAAQ,sBAAsB;IAC/D,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,KAAK,CAAC;IACf,YAAY,CAAC,EAAE,KAAK,CAAC;IACrB,QAAQ,CAAC,EAAE,KAAK,CAAC;CAClB;AAED,MAAM,MAAM,gBAAgB,GAC1B,0BAA0B,GAAG,wBAAwB,CAAC;AA6WxD;;;GAGG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,gBAAgB,+BA6BlD;yBA7Be,WAAW"}
+{"version":3,"file":"BottomSheet.d.ts","sourceRoot":"","sources":["../../src/BottomSheet/BottomSheet.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EAOL,KAAK,SAAS,EACf,MAAM,OAAO,CAAC;AAEf,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAC5C,OAAO,KAAK,EAAC,aAAa,EAAC,MAAM,WAAW,CAAC;AAe7C,YAAY,EAAC,iBAAiB,EAAE,oBAAoB,EAAC,MAAM,oBAAoB,CAAC;AAChF,OAAO,KAAK,EAAC,iBAAiB,EAAE,oBAAoB,EAAC,MAAM,oBAAoB,CAAC;AAyEhF,UAAU,sBAAuB,SAAQ,SAAS,CAAC,cAAc,CAAC;IAChE,qDAAqD;IACrD,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IAEhC,sCAAsC;IACtC,KAAK,EAAE,MAAM,CAAC;IAEd,0EAA0E;IAC1E,QAAQ,EAAE,SAAS,CAAC;IAEpB,wGAAwG;IACxG,MAAM,CAAC,EAAE,iBAAiB,GAAG,MAAM,GAAG,MAAM,CAAC;IAE7C;;;;;;;OAOG;IACH,UAAU,CAAC,EAAE,aAAa,CAAC,oBAAoB,CAAC,CAAC;IAEjD;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,aAAa,CAAC;CACzB;AAED,UAAU,0BAA2B,SAAQ,sBAAsB;IACjE,MAAM,EAAE,OAAO,CAAC;IAChB,YAAY,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;IACxC,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,OAAO,CAAC,EAAE,KAAK,CAAC;CACjB;AAED,UAAU,wBAAyB,SAAQ,sBAAsB;IAC/D,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,KAAK,CAAC;IACf,YAAY,CAAC,EAAE,KAAK,CAAC;IACrB,QAAQ,CAAC,EAAE,KAAK,CAAC;CAClB;AAED,MAAM,MAAM,gBAAgB,GAC1B,0BAA0B,GAAG,wBAAwB,CAAC;AA+WxD;;;GAGG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,gBAAgB,+BA6BlD;yBA7Be,WAAW"}

package/dist/BottomSheet/BottomSheet.js

@@ -16,6 +16,7 @@
  *
  * SYNC: When modified, update these files to stay in sync:
  * - /packages/core/src/BottomSheet/BottomSheetPanel.tsx
+ * - /packages/core/src/BottomSheet/BottomSheetEdgeTint.tsx
  * - /packages/core/src/BottomSheet/BottomSheet.doc.mjs
  * - /packages/core/src/BottomSheet/BottomSheet.test.tsx
  * - /packages/core/src/BottomSheet/BottomSheetSwitcher.tsx
@@ -29,8 +30,9 @@ import "../theme/tokens.stylex.js";
 import { colorVars, durationVars, easeVars } from "../theme/tokens.stylex.js";
 import { useDevWarning, useScrollLock } from "../hooks/index.js";
 import { BottomSheetPanel } from "./BottomSheetPanel.js";
+import { BottomSheetEdgeTint } from "./BottomSheetEdgeTint.js";
 import { BottomSheetSwitcherContext } from "./BottomSheetSwitcherContext.js";
-import { jsx as _jsx } from "react/jsx-runtime";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 function panelStateForSwitcherPhase(phase, alignmentOffset) {
   switch (phase) {
     case 'active':
@@ -180,7 +182,7 @@ function StandaloneBottomSheet({
       dismissOnLightInteraction();
     }
   }, [dismissOnLightInteraction, hasScrim]);
-  return /*#__PURE__*/_jsx("dialog", {
+  return /*#__PURE__*/_jsxs("dialog", {
     ...{
       0: {
         className: "xixxii4 x10a8y8t x1o6l61p xtdtrs8 x1x1rfll x7ab17h x1ghz6dp x1717udv xjbqb8w x1rea2x4 x1s85apg x1a2a7pz"
@@ -240,7 +242,7 @@ function StandaloneBottomSheet({
     onCancel: handleCancel,
     onClick: handleClick,
     onKeyDown: handleKeyDown,
-    children: /*#__PURE__*/_jsx("div", {
+    children: [/*#__PURE__*/_jsx("div", {
       ...{
         className: "x10l6tqk x17y0mx6 x1ey2m1c x78zum5 xl56j7k x47corl"
       },
@@ -259,7 +261,7 @@ function StandaloneBottomSheet({
         onMotionComplete: handleMotionComplete,
         children: children
       })
-    })
+    }), hasScrim ? null : /*#__PURE__*/_jsx(BottomSheetEdgeTint, {})]
   });
 }
 function SwitcherBottomSheetItem({

package/dist/BottomSheet/BottomSheetEdgeTint.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Colours the iOS Safari toolbar strip below a non-modal sheet. Renders
+ * nothing visible; see the file header for why it exists.
+ */
+export declare function BottomSheetEdgeTint(): import("react").JSX.Element;
+//# sourceMappingURL=BottomSheetEdgeTint.d.ts.map

package/dist/BottomSheet/BottomSheetEdgeTint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BottomSheetEdgeTint.d.ts","sourceRoot":"","sources":["../../src/BottomSheet/BottomSheetEdgeTint.tsx"],"names":[],"mappings":"AAqEA;;;GAGG;AACH,wBAAgB,mBAAmB,gCAQlC"}

package/dist/BottomSheet/BottomSheetEdgeTint.js

@@ -0,0 +1,62 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file BottomSheetEdgeTint.tsx
+ * @input Uses StyleX and core color tokens
+ * @output Exports BottomSheetEdgeTint, an internal decorative element
+ * @position Private helper rendered inside a non-modal BottomSheet dialog
+ *
+ * iOS 26 Safari dropped `<meta name="theme-color">` and instead derives the
+ * colour it paints behind its translucent toolbars by sampling the page: it
+ * hit tests a point just inside each viewport edge, walks up to the nearest
+ * `fixed`/`sticky` ancestor, and extends that element's declared
+ * `background-color` into the browser chrome.
+ *
+ * A modal sheet is served by that heuristic already — WebKit has a dedicated
+ * branch for a dialog's `::backdrop`. A non-modal sheet is not: the nearest
+ * fixed ancestor of the panel is the sheet's own full-viewport `<dialog>`,
+ * which is transparent and viewport-sized, and WebKit answers a viewport-sized
+ * candidate by *keeping the colour it already had* — the host page's. The page
+ * then shows through behind the address bar while the sheet covers the screen
+ * above it.
+ *
+ * This element gives the heuristic something unambiguous to sample: fixed,
+ * full width, flush with the bottom edge, taller than WebKit's 10px minimum
+ * for reading a declared colour, and painted in the sheet's own surface
+ * colour. It is masked out so it never renders for the user; Safari reads the
+ * computed style, not the painted pixels.
+ *
+ * Everywhere else it is inert decoration.
+ *
+ * SYNC: When modified, update these files to stay in sync:
+ * - /packages/core/src/BottomSheet/BottomSheet.tsx
+ * - /packages/core/src/BottomSheet/BottomSheetSwitcher.tsx
+ * - /packages/core/src/BottomSheet/BottomSheetEdgeTint.test.tsx
+ */
+import * as stylex from '@stylexjs/stylex';
+import "../theme/tokens.stylex.js";
+import { colorVars } from "../theme/tokens.stylex.js";
+
+/**
+ * WebKit ignores the declared `background-color` of a sampled box thinner than
+ * 10px and falls back to sampling painted pixels, which a masked element has
+ * none of. 12px clears that floor with room to spare and is still far below
+ * the ~40px of chrome it colours.
+ */
+import { jsx as _jsx } from "react/jsx-runtime";
+const SAMPLE_HEIGHT_PX = 12;
+/**
+ * Colours the iOS Safari toolbar strip below a non-modal sheet. Renders
+ * nothing visible; see the file header for why it exists.
+ */
+export function BottomSheetEdgeTint() {
+  return /*#__PURE__*/_jsx("div", {
+    ...{
+      className: "xixxii4 x17y0mx6 x1ey2m1c x1kpxq89 x10xzikg xhtitgo x47corl x1cb67k9 xt2iwb0"
+    },
+    "data-sheet-edge-tint": "",
+    "aria-hidden": "true"
+  });
+}

package/dist/BottomSheet/BottomSheetSwitcher.d.ts

@@ -18,6 +18,7 @@
  *
  * SYNC: When modified, update these files to stay in sync:
  * - /packages/core/src/BottomSheet/BottomSheet.tsx
+ * - /packages/core/src/BottomSheet/BottomSheetEdgeTint.tsx
  * - /packages/core/src/BottomSheet/BottomSheetSwitcher.doc.mjs
  * - /packages/core/src/BottomSheet/BottomSheetSwitcher.test.tsx
  * - /packages/core/src/BottomSheet/index.ts

package/dist/BottomSheet/BottomSheetSwitcher.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"BottomSheetSwitcher.d.ts","sourceRoot":"","sources":["../../src/BottomSheet/BottomSheetSwitcher.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,EAQL,KAAK,SAAS,EACd,KAAK,cAAc,EACpB,MAAM,OAAO,CAAC;AAEf,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAmI5C,MAAM,WAAW,wBAAyB,SAAQ,SAAS,CAAC,iBAAiB,CAAC;IAC5E,iDAAiD;IACjD,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,iBAAiB,CAAC,CAAC;IAEnC,oEAAoE;IACpE,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,cAAc,CAAC,iBAAiB,CAAC,KAAK,IAAI,CAAC;IAE9D;;;;;OAKG;IACH,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAE3B,iEAAiE;IACjE,mBAAmB,EAAE,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,KAAK,IAAI,CAAC;IAEtD;;;;OAIG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IAEnB,0DAA0D;IAC1D,QAAQ,EAAE,SAAS,CAAC;CACrB;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,EAClC,WAAW,EACX,mBAAmB,EACnB,QAAe,EACf,QAAQ,EACR,GAAG,EACH,MAAM,EACN,SAAS,EACT,KAAK,EACL,QAAQ,EACR,OAAO,EACP,SAAS,EACT,GAAG,KAAK,EACT,EAAE,wBAAwB,+BA6Z1B;yBA1ae,mBAAmB"}
+{"version":3,"file":"BottomSheetSwitcher.d.ts","sourceRoot":"","sources":["../../src/BottomSheet/BottomSheetSwitcher.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,EAQL,KAAK,SAAS,EACd,KAAK,cAAc,EACpB,MAAM,OAAO,CAAC;AAEf,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAoI5C,MAAM,WAAW,wBAAyB,SAAQ,SAAS,CAAC,iBAAiB,CAAC;IAC5E,iDAAiD;IACjD,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,iBAAiB,CAAC,CAAC;IAEnC,oEAAoE;IACpE,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,cAAc,CAAC,iBAAiB,CAAC,KAAK,IAAI,CAAC;IAE9D;;;;;OAKG;IACH,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAE3B,iEAAiE;IACjE,mBAAmB,EAAE,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,KAAK,IAAI,CAAC;IAEtD;;;;OAIG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IAEnB,0DAA0D;IAC1D,QAAQ,EAAE,SAAS,CAAC;CACrB;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,EAClC,WAAW,EACX,mBAAmB,EACnB,QAAe,EACf,QAAQ,EACR,GAAG,EACH,MAAM,EACN,SAAS,EACT,KAAK,EACL,QAAQ,EACR,OAAO,EACP,SAAS,EACT,GAAG,KAAK,EACT,EAAE,wBAAwB,+BA+Z1B;yBA5ae,mBAAmB"}

package/dist/BottomSheet/BottomSheetSwitcher.js

@@ -22,6 +22,7 @@
  *
  * SYNC: When modified, update these files to stay in sync:
  * - /packages/core/src/BottomSheet/BottomSheet.tsx
+ * - /packages/core/src/BottomSheet/BottomSheetEdgeTint.tsx
  * - /packages/core/src/BottomSheet/BottomSheetSwitcher.doc.mjs
  * - /packages/core/src/BottomSheet/BottomSheetSwitcher.test.tsx
  * - /packages/core/src/BottomSheet/index.ts
@@ -34,8 +35,9 @@ import "../theme/tokens.stylex.js";
 import { colorVars, durationVars, easeVars } from "../theme/tokens.stylex.js";
 import { hasActiveFocusTrapEscape, isImeKeyEvent, useFocusTrap, useScrollLock } from "../hooks/index.js";
 import { composeEventHandlers, mergeProps, mergeRefs } from "../utils/index.js";
+import { BottomSheetEdgeTint } from "./BottomSheetEdgeTint.js";
 import { BottomSheetSwitcherContext } from "./BottomSheetSwitcherContext.js";
-import { jsx as _jsx } from "react/jsx-runtime";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 const styles = {
   dialog: {
     kVAEAm: "xixxii4",
@@ -395,7 +397,7 @@ export function BottomSheetSwitcher({
   const ariaLabel = props['aria-label'] ?? (props['aria-labelledby'] == null ? activeLabel : undefined);
   return /*#__PURE__*/_jsx(BottomSheetSwitcherContext, {
     value: contextValue,
-    children: /*#__PURE__*/_jsx("dialog", {
+    children: /*#__PURE__*/_jsxs("dialog", {
       ...props,
       ...dialogPresentationProps,
       ref: mergeRefs(ref, dialogRef, containerRef),
@@ -407,7 +409,7 @@ export function BottomSheetSwitcher({
       ...(activeSheetPurpose === 'required' ? {
         role: 'alertdialog'
       } : undefined),
-      children: children
+      children: [children, hasScrim ? null : /*#__PURE__*/_jsx(BottomSheetEdgeTint, {})]
     })
   });
 }

package/dist/astryx.css

@@ -548,6 +548,7 @@
   .xiy8rlo:not(#\#):not(#\#):not(#\#){-webkit-mask-image:linear-gradient(to bottom,transparent,black 24px)}
   .x1bv1mxo:not(#\#):not(#\#):not(#\#){-webkit-mask-image:linear-gradient(to bottom,transparent,black 36px)}
   .xo9xo30:not(#\#):not(#\#):not(#\#){-webkit-mask-image:linear-gradient(to bottom,transparent,black 48px)}
+  .xt2iwb0:not(#\#):not(#\#):not(#\#){-webkit-mask-image:linear-gradient(transparent,transparent)}
   .x5lxg6s:not(#\#):not(#\#):not(#\#){-webkit-overflow-scrolling:touch}
   .x1i10hfl:not(#\#):not(#\#):not(#\#){-webkit-tap-highlight-color:transparent}
   .xpdipgo:not(#\#):not(#\#):not(#\#){-webkit-touch-callout:none}
@@ -983,6 +984,7 @@
   .xtdd0ob:not(#\#):not(#\#):not(#\#){mask-image:linear-gradient(to left,transparent 0%,rgba(0,0,0,.3) 2px,black var(--spacing-1))}
   .x1b5cd1y:not(#\#):not(#\#):not(#\#){mask-image:linear-gradient(to right,transparent 0%,rgba(0,0,0,.3) 2px,black var(--spacing-1),black calc(100% - var(--spacing-1)),rgba(0,0,0,.3) calc(100% - 2px),transparent 100%)}
   .x1ujl4f5:not(#\#):not(#\#):not(#\#){mask-image:linear-gradient(to right,transparent 0%,rgba(0,0,0,.3) 2px,black var(--spacing-1))}
+  .x1cb67k9:not(#\#):not(#\#):not(#\#){mask-image:linear-gradient(transparent,transparent)}
   .xw4ya9i:not(#\#):not(#\#):not(#\#){mask-image:none}
   .x19kjcj4:not(#\#):not(#\#):not(#\#){object-fit:contain}
   .xl1xv1r:not(#\#):not(#\#):not(#\#){object-fit:cover}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astryxdesign/core",
-  "version": "0.4.6-canary.f30c604",
+  "version": "0.4.7-canary.2ce1983",
   "displayName": "Astryx Core",
   "description": "The component library. Accessible, themeable React components with built-in spacing, dark mode, and StyleX styling.",
   "author": "Meta Open Source",
@@ -656,7 +656,7 @@
     "react-dom": ">=19.0.0"
   },
   "devDependencies": {
-    "@astryxdesign/cli": "0.4.6-canary.f30c604",
+    "@astryxdesign/cli": "0.4.7-canary.2ce1983",
     "@babel/cli": "^8.0.4",
     "@babel/core": "^7.29.7",
     "@babel/preset-react": "^8.0.1",

package/src/BottomSheet/BottomSheet.tsx

@@ -16,6 +16,7 @@
  *
  * SYNC: When modified, update these files to stay in sync:
  * - /packages/core/src/BottomSheet/BottomSheetPanel.tsx
+ * - /packages/core/src/BottomSheet/BottomSheetEdgeTint.tsx
  * - /packages/core/src/BottomSheet/BottomSheet.doc.mjs
  * - /packages/core/src/BottomSheet/BottomSheet.test.tsx
  * - /packages/core/src/BottomSheet/BottomSheetSwitcher.tsx
@@ -43,6 +44,7 @@ import {
   type BottomSheetPanelMotion,
   type BottomSheetPanelState,
 } from './BottomSheetPanel';
+import {BottomSheetEdgeTint} from './BottomSheetEdgeTint';
 import {
   BottomSheetSwitcherContext,
   type BottomSheetSwitcherContextValue,
@@ -370,6 +372,8 @@ function StandaloneBottomSheet({
           {children}
         </BottomSheetPanel>
       </div>
+      {/* A modal sheet's ::backdrop already answers Safari's edge sampler. */}
+      {hasScrim ? null : <BottomSheetEdgeTint />}
     </dialog>
   );
 }

package/src/BottomSheet/BottomSheetEdgeTint.test.tsx

@@ -0,0 +1,225 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file BottomSheetEdgeTint.test.tsx
+ * @input Uses vitest, @testing-library/react, BottomSheet, BottomSheetSwitcher
+ * @output Tests which sheets carry the iOS Safari bottom edge tint, and pins
+ *   the declarations WebKit's edge sampler reads
+ * @position Core testing; validates BottomSheetEdgeTint.tsx and its two hosts
+ *
+ * SYNC: When modified, update these files to stay in sync:
+ * - /packages/core/src/BottomSheet/BottomSheetEdgeTint.tsx
+ */
+
+import {describe, it, expect, vi, beforeEach, afterEach} from 'vitest';
+import {render} from '@testing-library/react';
+import {BottomSheet} from './BottomSheet';
+import {BottomSheetSwitcher} from './BottomSheetSwitcher';
+
+// jsdom doesn't implement <dialog> open/close or pointer capture; stub them.
+beforeEach(() => {
+  HTMLDialogElement.prototype.showModal = vi.fn(function (
+    this: HTMLDialogElement,
+  ) {
+    this.setAttribute('open', '');
+  });
+  HTMLDialogElement.prototype.show = vi.fn(function (this: HTMLDialogElement) {
+    this.setAttribute('open', '');
+  });
+  HTMLDialogElement.prototype.close = vi.fn(function (this: HTMLDialogElement) {
+    this.removeAttribute('open');
+  });
+  if (!Element.prototype.setPointerCapture) {
+    Element.prototype.setPointerCapture = vi.fn();
+    Element.prototype.releasePointerCapture = vi.fn();
+  }
+  vi.stubGlobal(
+    'matchMedia',
+    vi.fn().mockReturnValue({
+      matches: false,
+      media: '',
+      onchange: null,
+      addEventListener: vi.fn(),
+      removeEventListener: vi.fn(),
+      addListener: vi.fn(),
+      removeListener: vi.fn(),
+      dispatchEvent: vi.fn(),
+    }),
+  );
+  vi.stubGlobal(
+    'requestAnimationFrame',
+    vi.fn((callback: FrameRequestCallback) => {
+      callback(0);
+      return 1;
+    }),
+  );
+  vi.stubGlobal('cancelAnimationFrame', vi.fn());
+});
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+});
+
+function tints(): ReadonlyArray<Element> {
+  return Array.from(document.querySelectorAll('[data-sheet-edge-tint]'));
+}
+
+async function edgeTintSource(): Promise<string> {
+  const tint = (await fullSource()).match(/\n {2}tint: \{([\s\S]*?)\n {2}\},/);
+  expect(tint).not.toBeNull();
+  return tint![1];
+}
+
+/** The tint's declarations with its explanatory comments stripped out. */
+async function edgeTintDeclarations(): Promise<string> {
+  return (await edgeTintSource())
+    .split('\n')
+    .filter(line => !line.trim().startsWith('//'))
+    .join('\n');
+}
+
+async function fullSource(): Promise<string> {
+  const fs = await import('fs');
+  const path = await import('path');
+  return fs.readFileSync(
+    path.resolve(__dirname, './BottomSheetEdgeTint.tsx'),
+    'utf-8',
+  );
+}
+
+describe('BottomSheetEdgeTint', () => {
+  it('gives a non-modal sheet an edge tint to colour the iOS toolbar strip', () => {
+    render(
+      <BottomSheet
+        isOpen
+        onOpenChange={() => {}}
+        hasScrim={false}
+        label="Place details">
+        Content
+      </BottomSheet>,
+    );
+    expect(tints()).toHaveLength(1);
+  });
+
+  // A modal sheet's ::backdrop is a case WebKit's sampler handles on its own,
+  // so a second sampling target there would only fight it.
+  it('leaves a modal sheet to its ::backdrop', () => {
+    render(
+      <BottomSheet isOpen onOpenChange={() => {}} label="Place details">
+        Content
+      </BottomSheet>,
+    );
+    expect(tints()).toHaveLength(0);
+  });
+
+  it('renders the tint inside the dialog, so it unmounts with the sheet', () => {
+    const {rerender} = render(
+      <BottomSheet
+        isOpen
+        onOpenChange={() => {}}
+        hasScrim={false}
+        label="Place details">
+        Content
+      </BottomSheet>,
+    );
+    const [tint] = tints();
+    expect(tint?.closest('dialog')).not.toBeNull();
+
+    rerender(<div />);
+    expect(tints()).toHaveLength(0);
+  });
+
+  // The switcher owns one shared dialog for the whole flow, so the tint
+  // belongs to that dialog and must not be minted per child sheet.
+  it('gives a non-modal switcher flow exactly one tint', () => {
+    render(
+      <BottomSheetSwitcher
+        activeSheet="comment"
+        hasScrim={false}
+        onActiveSheetChange={() => {}}>
+        <BottomSheet sheetId="comment" label="Add a comment">
+          Comment
+        </BottomSheet>
+        <BottomSheet sheetId="confirmation" label="Confirmation">
+          Confirmation
+        </BottomSheet>
+      </BottomSheetSwitcher>,
+    );
+    expect(tints()).toHaveLength(1);
+  });
+
+  it('leaves a modal switcher flow to its ::backdrop', () => {
+    render(
+      <BottomSheetSwitcher activeSheet="comment" onActiveSheetChange={() => {}}>
+        <BottomSheet sheetId="comment" label="Add a comment">
+          Comment
+        </BottomSheet>
+      </BottomSheetSwitcher>,
+    );
+    expect(tints()).toHaveLength(0);
+  });
+
+  it('keeps the tint out of the accessibility tree and out of hit testing', async () => {
+    render(
+      <BottomSheet
+        isOpen
+        onOpenChange={() => {}}
+        hasScrim={false}
+        label="Place details">
+        Content
+      </BottomSheet>,
+    );
+    const [tint] = tints();
+    expect(tint?.getAttribute('aria-hidden')).toBe('true');
+    expect(tint?.textContent).toBe('');
+    expect(await edgeTintSource()).toContain("pointerEvents: 'none'");
+  });
+
+  // Every declaration below is load-bearing for a heuristic that lives in
+  // WebKit, not in this repo, and none of it is observable in jsdom or in any
+  // engine without retractable browser chrome — so it is asserted on the style
+  // definition, the way BottomSheetPanel pins its handle gradient.
+  describe('the declarations WebKit samples', () => {
+    it('is fixed and flush with the bottom edge of the viewport', async () => {
+      const tint = await edgeTintSource();
+      // Only a fixed or sticky box is a candidate, and only a box flush with
+      // the edge is the one Safari hit tests.
+      expect(tint).toContain("position: 'fixed'");
+      expect(tint).toContain('insetBlockEnd: 0');
+      expect(tint).toContain('insetInline: 0');
+    });
+
+    it('clears the 10px floor below which WebKit ignores the declared colour', async () => {
+      const height = (await fullSource()).match(
+        /const SAMPLE_HEIGHT_PX = (\d+);/,
+      );
+      expect(height).not.toBeNull();
+      expect(Number(height![1])).toBeGreaterThan(10);
+      expect(await edgeTintSource()).toContain(
+        'height: `${SAMPLE_HEIGHT_PX}px`',
+      );
+    });
+
+    it('declares the sheet surface colour, so the strip matches the sheet', async () => {
+      expect(await edgeTintSource()).toContain(
+        "backgroundColor: colorVars['--color-background-surface']",
+      );
+    });
+
+    // visibility: hidden, display: none and a low opacity all disqualify the
+    // element from sampling. A mask does not, which is the only reason the
+    // strip can be both readable by Safari and invisible to the user.
+    it('hides itself with a mask rather than with visibility or opacity', async () => {
+      const tint = await edgeTintDeclarations();
+      expect(tint).toContain(
+        "maskImage: 'linear-gradient(transparent, transparent)'",
+      );
+      expect(tint).toContain(
+        "WebkitMaskImage: 'linear-gradient(transparent, transparent)'",
+      );
+      expect(tint).not.toContain('visibility');
+      expect(tint).not.toContain('opacity');
+      expect(tint).not.toContain("display: 'none'");
+    });
+  });
+});

package/src/BottomSheet/BottomSheetEdgeTint.tsx

@@ -0,0 +1,82 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file BottomSheetEdgeTint.tsx
+ * @input Uses StyleX and core color tokens
+ * @output Exports BottomSheetEdgeTint, an internal decorative element
+ * @position Private helper rendered inside a non-modal BottomSheet dialog
+ *
+ * iOS 26 Safari dropped `<meta name="theme-color">` and instead derives the
+ * colour it paints behind its translucent toolbars by sampling the page: it
+ * hit tests a point just inside each viewport edge, walks up to the nearest
+ * `fixed`/`sticky` ancestor, and extends that element's declared
+ * `background-color` into the browser chrome.
+ *
+ * A modal sheet is served by that heuristic already — WebKit has a dedicated
+ * branch for a dialog's `::backdrop`. A non-modal sheet is not: the nearest
+ * fixed ancestor of the panel is the sheet's own full-viewport `<dialog>`,
+ * which is transparent and viewport-sized, and WebKit answers a viewport-sized
+ * candidate by *keeping the colour it already had* — the host page's. The page
+ * then shows through behind the address bar while the sheet covers the screen
+ * above it.
+ *
+ * This element gives the heuristic something unambiguous to sample: fixed,
+ * full width, flush with the bottom edge, taller than WebKit's 10px minimum
+ * for reading a declared colour, and painted in the sheet's own surface
+ * colour. It is masked out so it never renders for the user; Safari reads the
+ * computed style, not the painted pixels.
+ *
+ * Everywhere else it is inert decoration.
+ *
+ * SYNC: When modified, update these files to stay in sync:
+ * - /packages/core/src/BottomSheet/BottomSheet.tsx
+ * - /packages/core/src/BottomSheet/BottomSheetSwitcher.tsx
+ * - /packages/core/src/BottomSheet/BottomSheetEdgeTint.test.tsx
+ */
+
+import * as stylex from '@stylexjs/stylex';
+import {colorVars} from '../theme/tokens.stylex';
+
+/**
+ * WebKit ignores the declared `background-color` of a sampled box thinner than
+ * 10px and falls back to sampling painted pixels, which a masked element has
+ * none of. 12px clears that floor with room to spare and is still far below
+ * the ~40px of chrome it colours.
+ */
+const SAMPLE_HEIGHT_PX = 12;
+
+const styles = stylex.create({
+  tint: {
+    position: 'fixed',
+    insetInline: 0,
+    insetBlockEnd: 0,
+    height: `${SAMPLE_HEIGHT_PX}px`,
+    backgroundColor: colorVars['--color-background-surface'],
+    // Above the panel so the edge hit test lands here, and never in the way of
+    // a touch that was meant for the sheet.
+    zIndex: 2,
+    pointerEvents: 'none',
+    // Invisible to the user. WebKit's sampler checks `visibility` and
+    // `opacity` — either would disqualify the element — but not `mask`, so
+    // this hides the strip while leaving the colour readable. Without it the
+    // strip would show as a hairline under the panel as the sheet slides out.
+    maskImage: 'linear-gradient(transparent, transparent)',
+    WebkitMaskImage: 'linear-gradient(transparent, transparent)',
+  },
+});
+
+/**
+ * Colours the iOS Safari toolbar strip below a non-modal sheet. Renders
+ * nothing visible; see the file header for why it exists.
+ */
+export function BottomSheetEdgeTint() {
+  return (
+    <div
+      {...stylex.props(styles.tint)}
+      data-sheet-edge-tint=""
+      aria-hidden="true"
+    />
+  );
+}

package/src/BottomSheet/BottomSheetSwitcher.tsx

@@ -22,6 +22,7 @@
  *
  * SYNC: When modified, update these files to stay in sync:
  * - /packages/core/src/BottomSheet/BottomSheet.tsx
+ * - /packages/core/src/BottomSheet/BottomSheetEdgeTint.tsx
  * - /packages/core/src/BottomSheet/BottomSheetSwitcher.doc.mjs
  * - /packages/core/src/BottomSheet/BottomSheetSwitcher.test.tsx
  * - /packages/core/src/BottomSheet/index.ts
@@ -51,6 +52,7 @@ import {
   useScrollLock,
 } from '../hooks';
 import {composeEventHandlers, mergeProps, mergeRefs} from '../utils';
+import {BottomSheetEdgeTint} from './BottomSheetEdgeTint';
 import {
   BottomSheetSwitcherContext,
   type BottomSheetSwitcherContextValue,
@@ -629,6 +631,8 @@ export function BottomSheetSwitcher({
           ? {role: 'alertdialog'}
           : undefined)}>
         {children}
+        {/* A modal flow's ::backdrop already answers Safari's edge sampler. */}
+        {hasScrim ? null : <BottomSheetEdgeTint />}
       </dialog>
     </BottomSheetSwitcherContext>
   );