Skip to content
Merged
Show file tree
Hide file tree
Changes from 6 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/core-internal-entries-lab-scroll-edge.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
---
'@astryxdesign/core': patch
---

[chore] Internal: Core's internal touch entry also names, for Lab's NavigationStack, the gesture host and the coarse-pointer check. Its scroll edge effect reads the internal finger-scroll hook and its end call. Apps import nothing new.

@vjeux
7 changes: 7 additions & 0 deletions .changeset/finger-scroll-end.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
---
'@astryxdesign/core': patch
---

[chore] Internal: `useFingerScroll(scroller, {onEnd})` calls `onEnd` each time a finger's scroll on the scroller ends, and the hook is re-exported from the internal touch subpath for Lab components that watch a finger's scroll. Internal entries are outside the public API and its compatibility promise; the hook is not exported from the package entry point or the gestures barrel.

@cixzhang
78 changes: 78 additions & 0 deletions apps/storybook/stories/NavigationStack.stories.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -308,3 +308,81 @@ export const LargeTitle: Story = {
name: 'Large title',
render: () => <LargeTitleStack />,
};

// =============================================================================
// Scrolling — content passing under the bar
// =============================================================================

const MESSAGES = Array.from({length: 40}, (_, index) => `Message ${index + 1}`);

function MessageRows() {
const nav = useNavigationStack<string>();
return (
<List>
{MESSAGES.map(message => (
<ListItem
key={message}
label={message}
description="Tap to open; scroll the list under the bar."
endContent={
<Icon
icon="chevronRight"
color="secondary"
xstyle={rtlStyles.mirror}
/>
}
onClick={() => nav.push(message)}
/>
))}
</List>
);
}

function MessageBody({title}: {title: string}) {
return (
<List>
{Array.from({length: 30}, (_, index) => (
<ListItem
key={index}
label={`${title}, line ${index + 1}`}
description="Long content scrolls under the bar."
/>
))}
</List>
);
}

function ScrollingStack() {
const [path, setPath] = useState<string[]>([]);
return (
<div style={{height: '100vh'}}>
<NavigationStack
label="Mail"
root={
<NavigationScreen title="Inbox">
<MessageRows />
</NavigationScreen>
}
path={path}
onPathChange={setPath}
getKey={entry => entry}
renderScreen={entry => (
<NavigationScreen title={entry}>
<MessageBody title={entry} />
</NavigationScreen>
)}
data-testid="navigation-stack"
/>
</div>
);
}

/**
* Screens long enough to scroll under the bar. On a touch screen the bar
* paints no background. Once a screen's content has moved 10px under it, a
* veil of the body colour fades in, as iOS 26's scroll edge effect does.
* Each screen keeps its own veil through a push, a pop or a back swipe.
*/
export const Scrolling: Story = {
render: () => <ScrollingStack />,
};
4 changes: 3 additions & 1 deletion docs/architecture/react-component-runtime.md
Original file line number Diff line number Diff line change
Expand Up @@ -319,7 +319,9 @@ those contracts.
`@astryxdesign/core/internal/touch`, a subpath reserved for Astryx's own
packages: undocumented, outside the compatibility promise, versioned in
lockstep with Core, and limited by lint to Core and Lab (`spec:AST-017`
FR21).
FR21). The finger-scroll watch's hook, `useFingerScroll`, is on that
subpath: it reports whether a scroller's scroll is a finger's and, through
`onEnd`, when that scroll ends.
- **INV15 — The animator animates a number.** The animator has a value mode:
it plays a number, such as a count or a chart value, on the same timing as its property channels: theme motion tokens for a program-started change, and measured springs only where `spec:AST-094` FR45 keeps them, and hands the value to an `onUpdate`
callback each frame for the component to format and write. The component owns
Expand Down
5 changes: 4 additions & 1 deletion packages/core/src/gestures/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -75,7 +75,10 @@ function Sheet() {
while a finger that landed inside it is down, until its `scrollend` (the
momentum is still the finger's), or, where the browser fires none (mobile
Safari before 26), until its scroll events go quiet. Pass a ref, or the
document for the page. Outside React, `watchFingerScrolls(host, scroller)` and
document for the page. `options.onEnd` runs each time such a scroll ends,
once the reader says `false`; unmounting does not call it. It is
re-exported from `@astryxdesign/core/internal/touch` for Lab components
that watch a finger's scroll. Outside React, `watchFingerScrolls(host, scroller)` and
`isFingerScroll(host, scroller)` from `fingerScroll.ts` do the same; that
module adds passive scroll listeners only while something is watched.

Expand Down
138 changes: 135 additions & 3 deletions packages/core/src/gestures/__tests__/useFingerScroll.test.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -7,17 +7,18 @@
* @output A finger's scroll reads true until the scroller's scrollend; a
* scroll with no finger down reads false; the page's own scroll through
* the document; the watch follows the ref's node and ends on unmount, and
* lets go of a node it stops following
* lets go of a node it stops following; onEnd runs once per finger scroll
* on each end path, for each watcher, and never on unmount
* @position Unit tests of packages/core/src/gestures/useFingerScroll.ts
*/

import {render} from '@testing-library/react';
import {useRef} from 'react';
import {afterEach, beforeEach, describe, expect, it} from 'vitest';
import {afterEach, beforeEach, describe, expect, it, vi} from 'vitest';
import {isFingerScroll} from '../fingerScroll';
import {getGestureHost} from '../GestureHost';
import {useFingerScroll} from '../useFingerScroll';
import {coarsePrimaryPointer} from './pointerQuery';
import {coarsePrimaryPointer, pointerQuery} from './pointerQuery';

function touch(type: string, target: Element, down: boolean): void {
const event = new Event(type, {bubbles: true, cancelable: true});
Expand Down Expand Up @@ -71,6 +72,39 @@ function Follower() {
return null;
}

/** A list that counts its finger scrolls' ends, and what it read then. */
const ends: {count: number; readAtEnd: boolean[]} = {count: 0, readAtEnd: []};

function EndingList({watchers = 1}: {watchers?: number}) {
const ref = useRef<HTMLDivElement>(null);
const onEnd = () => {
ends.count += 1;
ends.readAtEnd.push(read());
};
read = useFingerScroll(ref, {onEnd});
// The second watcher renders after the list, so the list's ref is set
// when its attachment runs.
return (
<>
<div ref={ref} data-testid="list">
<p data-testid="row">row</p>
</div>
{watchers > 1 && <SecondWatcher scroller={ref} onEnd={onEnd} />}
</>
);
}

function SecondWatcher({
scroller,
onEnd,
}: {
scroller: {current: Element | null};
onEnd: () => void;
}) {
useFingerScroll(scroller, {onEnd});
return null;
}

function Page() {
read = useFingerScroll(document);
return <p data-testid="row">row</p>;
Expand Down Expand Up @@ -184,4 +218,102 @@ describe('useFingerScroll', () => {
second.element.remove();
}
});

describe('onEnd', () => {
beforeEach(() => {
ends.count = 0;
ends.readAtEnd = [];
});

it("runs once at the scroller's scrollend after the lift, with the reader already false", () => {
const {getByTestId} = render(<EndingList />);
const list = getByTestId('list');
fingerScroll(list, getByTestId('row'));
touch('touchend', getByTestId('row'), false);
list.dispatchEvent(new Event('scroll'));
expect(ends.count).toBe(0);
list.dispatchEvent(new Event('scrollend'));
expect(ends.count).toBe(1);
expect(ends.readAtEnd).toEqual([false]);
list.dispatchEvent(new Event('scrollend'));
expect(ends.count).toBe(1);
});

it('runs at the lift when the scroll ended under a resting finger', () => {
const {getByTestId} = render(<EndingList />);
const list = getByTestId('list');
fingerScroll(list, getByTestId('row'));
list.dispatchEvent(new Event('scrollend'));
expect(ends.count).toBe(0);
touch('touchend', getByTestId('row'), false);
expect(ends.count).toBe(1);
});

it('runs after the quiet fallback where the browser fires no scrollend', () => {
// A browser with no scrollend (mobile Safari before 26): take jsdom's
// handler slot away for this test.
let owner: object | null = window;
while (owner != null && !Object.hasOwn(owner, 'onscrollend')) {
owner = Object.getPrototypeOf(owner) as object | null;
}
const slot =
owner == null
? undefined
: Object.getOwnPropertyDescriptor(owner, 'onscrollend');
if (owner != null) {
delete (owner as Record<string, unknown>).onscrollend;
}
vi.useFakeTimers();
try {
expect('onscrollend' in window).toBe(false);
const {getByTestId} = render(<EndingList />);
const list = getByTestId('list');
fingerScroll(list, getByTestId('row'));
touch('touchend', getByTestId('row'), false);
vi.advanceTimersByTime(149);
expect(ends.count).toBe(0);
vi.advanceTimersByTime(1);
expect(ends.count).toBe(1);
expect(ends.readAtEnd).toEqual([false]);
} finally {
vi.useRealTimers();
if (owner != null && slot != null) {
Object.defineProperty(owner, 'onscrollend', slot);
}
}
});

it('runs when the primary pointer stops being coarse mid-scroll', () => {
restorePointer();
const pointer = pointerQuery(true);
restorePointer = pointer.restore;
const {getByTestId} = render(<EndingList />);
fingerScroll(getByTestId('list'), getByTestId('row'));
pointer.set(false);
expect(ends.count).toBe(1);
expect(ends.readAtEnd).toEqual([false]);
touch('touchend', getByTestId('row'), false);
});

it('gives two watchers of one scroller one call each per finger scroll', () => {
const {getByTestId} = render(<EndingList watchers={2} />);
const list = getByTestId('list');
fingerScroll(list, getByTestId('row'));
lift(list, getByTestId('row'));
expect(ends.count).toBe(2);
fingerScroll(list, getByTestId('row'));
lift(list, getByTestId('row'));
expect(ends.count).toBe(4);
});

it('does not run on unmount, even mid-scroll', () => {
const {getByTestId, unmount} = render(<EndingList />);
const row = getByTestId('row');
fingerScroll(getByTestId('list'), row);
unmount();
expect(ends.count).toBe(0);
touch('touchend', row, false);
expect(ends.count).toBe(0);
});
});
});
Loading