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.mdnew file mode 100644index 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.++@imdreamrunnerdiff --git a/packages/core/src/BottomSheet/BottomSheet.tsx b/packages/core/src/BottomSheet/BottomSheet.tsxindex 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.tsxnew file mode 100644index 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.tsxnew file mode 100644index 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.tsxindex 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>);