Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 7 additions & 0 deletions .changeset/bottom-sheet-pull-stretch.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
---
'@astryxdesign/core': patch
---

[fix] BottomSheet: a finger's pull up past the top stretches the sheet on every pull, on iOS's rubber band, with no 48 px cap, unless the caller sizes or styles the sheet (an inline block size, any `xstyle` or class name), which keeps it. The sheet keeps enough of its surface below the screen that the page never shows. A pull on the content stretches it too once the content has no room left to scroll: at once for content that fits, and after a long list reaches its end. A mouse or a pen keeps its current stretch.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"A mouse or a pen keeps its current stretch" holds on the grabber only: a stylus pull on the sheet's body takes the finger's band (useSheetGestures.ts:1207, :1319-1327), where on the base it moved nothing at the tallest detent. Fix the stylus path, or say "a mouse, or a pen on the grabber".

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The stylus path is fixed in c58330c, so the line now holds on the body too.


@vjeux
65 changes: 65 additions & 0 deletions apps/storybook/stories/BottomSheet.stories.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -590,6 +590,71 @@ export const HugHeight: Story = {
},
};

/**
* A sheet whose height the caller sets. It keeps a 48 px surface below the
* screen, so a pull past the top stretches it at most that far.
*/
export const CallerHeight: Story = {
name: 'Caller height (500 px)',
render: () => {
const [isOpen, setIsOpen] = useState(false);
return (
<>
<Button label="Open 500 px sheet" onClick={() => setIsOpen(true)} />
<BottomSheet
isOpen={isOpen}
onOpenChange={setIsOpen}
label="Caller height"
style={{height: 500}}>
<Section padding={4}>
<VStack gap={4}>
<Heading level={3}>Caller height</Heading>
<Text type="supporting" color="secondary">
The caller sets this sheet's height to 500 px.
</Text>
<Button label="Done" onClick={() => setIsOpen(false)} />
</VStack>
</Section>
</BottomSheet>
</>
);
},
};

const callerHeightStyles = stylex.create({
sheet: {height: 500},
});

export const CallerHeightXstyle: Story = {
name: 'Caller height through xstyle (500 px)',
render: () => {
const [isOpen, setIsOpen] = useState(false);
return (
<>
<Button
label="Open 500 px xstyle sheet"
onClick={() => setIsOpen(true)}
/>
<BottomSheet
isOpen={isOpen}
onOpenChange={setIsOpen}
label="Caller height through xstyle"
xstyle={callerHeightStyles.sheet}>
<Section padding={4}>
<VStack gap={4}>
<Heading level={3}>Caller height through xstyle</Heading>
<Text type="supporting" color="secondary">
The caller sets this sheet's height to 500 px through xstyle.
</Text>
<Button label="Done" onClick={() => setIsOpen(false)} />
</VStack>
</Section>
</BottomSheet>
</>
);
},
};

export const HugHeightWithLongContent: Story = {
name: 'Hug height — Long content',
render: () => {
Expand Down
25 changes: 23 additions & 2 deletions docs/specs/AST-094-touch-presentations/spec.md
Original file line number Diff line number Diff line change
Expand Up @@ -354,7 +354,10 @@ a measured, sourced difference exists.
the area sits at its edge and the drag moves toward that edge, the
surrounding surface (a sheet) takes the drag; otherwise the area keeps it for
the whole gesture and rubber-bands at its edge. The drag MUST NOT change
hands midway, in either direction. This amends `spec:AST-025` FR14 (scroll
hands midway, in either direction, with one exception (DEC-28). At a
sheet's tallest detent, a pull that carries its content past its end
continues as the sheet's stretch, and a reversal hands it back to the
content (`component:BottomSheet` FR18). This amends `spec:AST-025` FR14 (scroll
chaining by default) for touch presentations on every touch platform.
- **FR15 — Recognizers arbitrate like UIKit's.** Recognizers that see the
same touch sequence MUST be exclusive by default: the first to recognize
Expand Down Expand Up @@ -804,7 +807,13 @@ under a finger, and a mouse follows `module:DropdownMenu/useMenuPress` FR3 and
- `component:BottomSheet`: a `form` or `required` sheet rubber-bands past its
resting place under a finger as under a trackpad (FR3, FR43), with the same
stretch for the same travel; a mouse wheel scrolls its content and never
moves it. Implementation gap: a finger drags it one for one below rest.
moves it. Past its tallest detent, every finger's pull stretches it on FR3's
rubber band with no hold, over a reserve deep enough for the whole stretch
and the release. A pull on its content does so once the content cannot
Comment on lines +810 to +812

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Non-blocking: FR18 stops a sheet the caller sizes or styles at 48 px, so "every finger's pull stretches it on FR3's rubber band with no hold" reads wider than the component record. Adding "unless the caller sizes or styles it (FR18)" makes the two records read alike.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agreed. This head keeps its approvals, so the line gains "unless the caller sizes or styles it (FR18)" in a small follow-up after this merges.

scroll that way (`component:BottomSheet` FR18). Past its tallest detent, a
mouse and a pen keep FR18's resisted stretch of at most 48 px, an exception
to FR43's same rubber band (`spec:AST-017` FR59). Implementation gap: a
finger drags it one for one below rest.
- The shared pager (Carousel's paging presentation, Lightbox's viewer): a
trackpad swipe follows FR43's pager rule in Lightbox's viewer and in
Carousel's paging presentation, under every pointer (`component:Lightbox`
Expand Down Expand Up @@ -1302,6 +1311,18 @@ checks there.

Rejected: a physical Android phone as a gate or as a follow-up check.

### DEC-28 — Sheet stretch at the tallest detent

**Reference:** `spec:AST-094/DEC-28`
**Decider:** the owner, `2026-11-03`

Decided by the owner in a feel check on a phone: at a sheet's tallest detent,
a pull that carries its content past its end continues as the sheet's
stretch, and a reversal hands it back (FR14's one exception).

Rejected: keeping the whole gesture with the content (the strict nested-scroll
rule).

## Open questions

- **OQ1 — Scroll view bounce-back curve.** What curve brings a scroll view
Expand Down
25 changes: 24 additions & 1 deletion docs/specs/components/BottomSheet/BottomSheet.spec.md

Large diffs are not rendered by default.

162 changes: 162 additions & 0 deletions packages/core/src/BottomSheet/BottomSheetPanel.test.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,7 @@
* @position Internal presentation tests shared by standalone and switcher modes
*/

import * as stylex from '@stylexjs/stylex';
import {act, fireEvent, render, screen} from '@testing-library/react';
import {afterEach, beforeEach, describe, expect, it, vi} from 'vitest';
import {
Expand Down Expand Up @@ -42,6 +43,23 @@ afterEach(() => {
vi.unstubAllGlobals();
});

// A device with a touch pointer: only `(any-pointer: coarse)` matches.
function stubTouchPointer() {
vi.stubGlobal(
'matchMedia',
vi.fn((query: string) => ({
matches: query === '(any-pointer: coarse)',
media: query,
onchange: null,
addEventListener: vi.fn(),
removeEventListener: vi.fn(),
addListener: vi.fn(),
removeListener: vi.fn(),
dispatchEvent: vi.fn(),
})),
);
}

function renderPanel(
state: BottomSheetPanelState,
callbacks: {
Expand Down Expand Up @@ -74,7 +92,151 @@ function getPanel(): HTMLElement {
return panel;
}

const callerSizeStyles = stylex.create({
height: {height: 500},
maxHeight: {maxHeight: 500},
color: {color: 'rebeccapurple'},
});

describe('BottomSheetPanel', () => {
it('keeps 40% of the viewport of its surface below the screen, for the whole stretch past the top', () => {
stubTouchPointer();
renderPanel({kind: 'open', entering: false});
// A finger's rubber band over a sheet as tall as the viewport shows at
// most 35.5% of the viewport.
expect(getPanel().style.getPropertyValue('--_sheet-reserve')).toBe(
`${Math.ceil(window.innerHeight * 0.4)}px`,
);
});

it('keeps the smallest reserve, 48 px, under a height the caller sets, on a device with a touch pointer', () => {
// Nothing extends a caller's height by the reserve, so a deeper one would
// hide that much more of the sheet below the screen.
stubTouchPointer();
render(
<BottomSheetPanel
label="Sheet details"
state={{kind: 'open', entering: false}}
height="hug"
style={{...panelTransitionStyle, height: 500}}
onDismiss={() => {}}
onScrimOpacity={() => {}}>
Panel content
</BottomSheetPanel>,
);
expect(getPanel().style.getPropertyValue('--_sheet-reserve')).toBe('48px');
});

it('keeps the smallest reserve, 48 px, under a size the caller sets through xstyle, on a device with a touch pointer', () => {
stubTouchPointer();
render(
<BottomSheetPanel
label="Sheet details"
state={{kind: 'open', entering: false}}
height="hug"
style={panelTransitionStyle}
xstyle={callerSizeStyles.height}
onDismiss={() => {}}
onScrimOpacity={() => {}}>
Panel content
</BottomSheetPanel>,
);
expect(getPanel().style.getPropertyValue('--_sheet-reserve')).toBe('48px');
});

it('keeps the smallest reserve, 48 px, under a maximum size in an xstyle array, on a device with a touch pointer', () => {
stubTouchPointer();
render(
<BottomSheetPanel
label="Sheet details"
state={{kind: 'open', entering: false}}
height="hug"
style={panelTransitionStyle}
xstyle={[callerSizeStyles.color, callerSizeStyles.maxHeight]}
onDismiss={() => {}}
onScrimOpacity={() => {}}>
Panel content
</BottomSheetPanel>,
);
expect(getPanel().style.getPropertyValue('--_sheet-reserve')).toBe('48px');
});

it('keeps the smallest reserve, 48 px, under a class name the caller passes, on a device with a touch pointer', () => {
// A class name's rules can size the sheet, and nothing can read them.
stubTouchPointer();
render(
<BottomSheetPanel
label="Sheet details"
state={{kind: 'open', entering: false}}
height="hug"
className="caller-sheet"
style={panelTransitionStyle}
onDismiss={() => {}}
onScrimOpacity={() => {}}>
Panel content
</BottomSheetPanel>,
);
expect(getPanel().style.getPropertyValue('--_sheet-reserve')).toBe('48px');
});

it('keeps the smallest reserve, 48 px, under any xstyle, whose rules nothing can read, on a device with a touch pointer', () => {
stubTouchPointer();
render(
<BottomSheetPanel
label="Sheet details"
state={{kind: 'open', entering: false}}
height="hug"
style={panelTransitionStyle}
xstyle={callerSizeStyles.color}
onDismiss={() => {}}
onScrimOpacity={() => {}}>
Panel content
</BottomSheetPanel>,
);
expect(getPanel().style.getPropertyValue('--_sheet-reserve')).toBe('48px');
});

it('keeps the viewport reserve under an empty xstyle and a style that does not size the sheet, on a device with a touch pointer', () => {
stubTouchPointer();
render(
<BottomSheetPanel
label="Sheet details"
state={{kind: 'open', entering: false}}
height="hug"
style={{...panelTransitionStyle, color: 'rebeccapurple'}}
xstyle={[false, undefined]}
onDismiss={() => {}}
onScrimOpacity={() => {}}>
Panel content
</BottomSheetPanel>,
);
expect(getPanel().style.getPropertyValue('--_sheet-reserve')).not.toBe(
'48px',
);
});

it('keeps the smallest reserve, 48 px, on a device with no touch pointer', () => {
renderPanel({kind: 'open', entering: false});
expect(getPanel().style.getPropertyValue('--_sheet-reserve')).toBe('48px');
});

it('follows the viewport with its reserve while it is presented', () => {
const viewportHeight = window.innerHeight;
stubTouchPointer();
renderPanel({kind: 'open', entering: false});
try {
act(() => {
window.innerHeight = 1000;
window.dispatchEvent(new Event('resize'));
});
expect(getPanel().style.getPropertyValue('--_sheet-reserve')).toBe(
'400px',
);
} finally {
window.innerHeight = viewportHeight;
}
});

it('reports entrance completion only for the surface transform', () => {
const onMotionStart = vi.fn();
const onMotionComplete = vi.fn();
Expand Down
Loading
Loading