Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

fix(BottomSheet): colour the iOS Safari toolbar strip under a non-modal sheet (#5342)

Xinzi Zhoub594d5c5fc4e
diff --git a/.changeset/bottom-sheet-noscrim-edge-tint.md b/.changeset/bottom-sheet-noscrim-edge-tint.md
new file mode 100644
index 0000000000..e043bd6b8c
--- /dev/null
+++ b/.changeset/bottom-sheet-noscrim-edge-tint.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/core': patch
+---
+
+[fix] 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.
+
+@imdreamrunner
diff --git a/packages/core/src/BottomSheet/BottomSheet.tsx b/packages/core/src/BottomSheet/BottomSheet.tsx
index efedb1b785..5105f2f8cb 100644
--- a/packages/core/src/BottomSheet/BottomSheet.tsx
+++ b/packages/core/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>
);
}
diff --git a/packages/core/src/BottomSheet/BottomSheetEdgeTint.test.tsx b/packages/core/src/BottomSheet/BottomSheetEdgeTint.test.tsx
new file mode 100644
index 0000000000..75c1c7f7dd
--- /dev/null
+++ b/packages/core/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'");
+ });
+ });
+});
diff --git a/packages/core/src/BottomSheet/BottomSheetEdgeTint.tsx b/packages/core/src/BottomSheet/BottomSheetEdgeTint.tsx
new file mode 100644
index 0000000000..19f18de7ae
--- /dev/null
+++ b/packages/core/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"
+ />
+ );
+}
diff --git a/packages/core/src/BottomSheet/BottomSheetSwitcher.tsx b/packages/core/src/BottomSheet/BottomSheetSwitcher.tsx
index 2e9fff96fa..5e07984d7c 100644
--- a/packages/core/src/BottomSheet/BottomSheetSwitcher.tsx
+++ b/packages/core/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>
);