@pylonsync/react 0.22.69 → 0.22.72
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/Link.d.ts +1 -1
- package/dist/linkIntent.d.ts +13 -0
- package/package.json +4 -4
- package/src/Link.tsx +12 -21
- package/src/linkIntent.test.ts +155 -0
- package/src/linkIntent.ts +98 -0
package/dist/Link.d.ts
CHANGED
|
@@ -4,7 +4,7 @@ declare global {
|
|
|
4
4
|
__pylon?: {
|
|
5
5
|
prefetch: (href: string, opts?: {
|
|
6
6
|
/** Also fetch the page payload. Costs a server render, so only on an
|
|
7
|
-
* intent signal
|
|
7
|
+
* intent signal (see ./linkIntent). */
|
|
8
8
|
document?: boolean;
|
|
9
9
|
}) => Promise<void>;
|
|
10
10
|
navigate: (href: string, opts?: {
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
/** A cursor crossing a link on its way elsewhere leaves it sooner than this. */
|
|
2
|
+
export declare const HOVER_INTENT_MS = 80;
|
|
3
|
+
/** A scroll moves the finger sooner than this; a tap lasts longer. */
|
|
4
|
+
export declare const TOUCH_INTENT_MS = 60;
|
|
5
|
+
export interface IntentTimers {
|
|
6
|
+
set(fn: () => void, ms: number): unknown;
|
|
7
|
+
clear(handle: unknown): void;
|
|
8
|
+
}
|
|
9
|
+
/**
|
|
10
|
+
* Call `onIntent` each time the user aims at `el`. Returns a function that
|
|
11
|
+
* removes the listeners and cancels a pending timer.
|
|
12
|
+
*/
|
|
13
|
+
export declare function watchLinkIntent(el: EventTarget, onIntent: () => void, timers?: IntentTimers): () => void;
|
package/package.json
CHANGED
|
@@ -3,7 +3,7 @@
|
|
|
3
3
|
"publishConfig": {
|
|
4
4
|
"access": "public"
|
|
5
5
|
},
|
|
6
|
-
"version": "0.22.
|
|
6
|
+
"version": "0.22.72",
|
|
7
7
|
"type": "module",
|
|
8
8
|
"main": "./src/index.ts",
|
|
9
9
|
"types": "./dist/index.d.ts",
|
|
@@ -14,9 +14,9 @@
|
|
|
14
14
|
"prepack": "bun run build"
|
|
15
15
|
},
|
|
16
16
|
"dependencies": {
|
|
17
|
-
"@pylonsync/realtime": "0.22.
|
|
18
|
-
"@pylonsync/sdk": "0.22.
|
|
19
|
-
"@pylonsync/sync": "0.22.
|
|
17
|
+
"@pylonsync/realtime": "0.22.72",
|
|
18
|
+
"@pylonsync/sdk": "0.22.72",
|
|
19
|
+
"@pylonsync/sync": "0.22.72"
|
|
20
20
|
},
|
|
21
21
|
"peerDependencies": {
|
|
22
22
|
"react": ">=19.0.0"
|
package/src/Link.tsx
CHANGED
|
@@ -16,13 +16,14 @@
|
|
|
16
16
|
// covers links off screen, such as a tab bar, so the first tap is warm
|
|
17
17
|
// too, without counting against this page's first paint. For a route
|
|
18
18
|
// that navigates with no page fetch (`navigation = "client"` or an
|
|
19
|
-
// offline route), the runtime also loads its entry then. On
|
|
20
|
-
//
|
|
21
|
-
//
|
|
22
|
-
//
|
|
23
|
-
//
|
|
24
|
-
//
|
|
25
|
-
//
|
|
19
|
+
// offline route), the runtime also loads its entry then. On intent it
|
|
20
|
+
// fetches the chunks at once and also fetches the page itself, which
|
|
21
|
+
// costs a server render, so that waits for a real signal rather than
|
|
22
|
+
// firing for a screenful of links. Intent is a cursor that stays on the
|
|
23
|
+
// link, a touch that stays down without moving, a mouse press, or focus
|
|
24
|
+
// (see ./linkIntent). A cursor crossing the link, or a touch that starts
|
|
25
|
+
// a scroll, fetches nothing. The runtime also keeps at most two page
|
|
26
|
+
// prefetches waiting on the server at a time.
|
|
26
27
|
// - Modifier keys (cmd/ctrl/shift/alt) or middle-click fall
|
|
27
28
|
// through to the browser's default behavior (open in new tab,
|
|
28
29
|
// etc.) — matches Next.js semantics.
|
|
@@ -34,6 +35,7 @@
|
|
|
34
35
|
// (HTML still prefetches) or by setting `target="_blank"`.
|
|
35
36
|
|
|
36
37
|
import React, { useEffect, useRef } from "react";
|
|
38
|
+
import { watchLinkIntent } from "./linkIntent";
|
|
37
39
|
|
|
38
40
|
declare global {
|
|
39
41
|
interface Window {
|
|
@@ -42,7 +44,7 @@ declare global {
|
|
|
42
44
|
href: string,
|
|
43
45
|
opts?: {
|
|
44
46
|
/** Also fetch the page payload. Costs a server render, so only on an
|
|
45
|
-
* intent signal
|
|
47
|
+
* intent signal (see ./linkIntent). */
|
|
46
48
|
document?: boolean;
|
|
47
49
|
},
|
|
48
50
|
) => Promise<void>;
|
|
@@ -167,24 +169,13 @@ export function Link({
|
|
|
167
169
|
io.observe(el);
|
|
168
170
|
}
|
|
169
171
|
|
|
170
|
-
el
|
|
171
|
-
el.addEventListener("touchstart", warmPage, { passive: true });
|
|
172
|
-
// A press starts ~100 ms before the click: enough to start the fetch.
|
|
173
|
-
el.addEventListener("pointerdown", warmPage);
|
|
174
|
-
// Focus is the keyboard's version of hover, and a stronger signal: a
|
|
175
|
-
// cursor slides across links it isn't aiming at, but nobody tabs onto one
|
|
176
|
-
// idly. Without it, tabbing to a link and pressing Enter took the cold
|
|
177
|
-
// path while a mouse user got the warm one — the wrong way round.
|
|
178
|
-
el.addEventListener("focus", warmPage);
|
|
172
|
+
const stopIntent = watchLinkIntent(el, warmPage);
|
|
179
173
|
|
|
180
174
|
return () => {
|
|
181
175
|
if (typeof window.cancelIdleCallback === "function") window.cancelIdleCallback(idle);
|
|
182
176
|
else window.clearTimeout(idle);
|
|
183
177
|
io?.disconnect();
|
|
184
|
-
|
|
185
|
-
el.removeEventListener("touchstart", warmPage);
|
|
186
|
-
el.removeEventListener("pointerdown", warmPage);
|
|
187
|
-
el.removeEventListener("focus", warmPage);
|
|
178
|
+
stopIntent();
|
|
188
179
|
};
|
|
189
180
|
}, [href, prefetch]);
|
|
190
181
|
|
|
@@ -0,0 +1,155 @@
|
|
|
1
|
+
// `<Link>` fetches the destination page on intent, and each fetch is a server
|
|
2
|
+
// render. These tests hold the rules that keep a scroll through a list of
|
|
3
|
+
// links from asking for one render per link.
|
|
4
|
+
|
|
5
|
+
import { describe, expect, test } from "bun:test";
|
|
6
|
+
import { HOVER_INTENT_MS, TOUCH_INTENT_MS, watchLinkIntent } from "./linkIntent";
|
|
7
|
+
|
|
8
|
+
function harness() {
|
|
9
|
+
let clock = 0;
|
|
10
|
+
let nextId = 1;
|
|
11
|
+
const scheduled = new Map<number, { at: number; fn: () => void }>();
|
|
12
|
+
const el = new EventTarget();
|
|
13
|
+
let intents = 0;
|
|
14
|
+
const stop = watchLinkIntent(
|
|
15
|
+
el,
|
|
16
|
+
() => {
|
|
17
|
+
intents++;
|
|
18
|
+
},
|
|
19
|
+
{
|
|
20
|
+
set: (fn, ms) => {
|
|
21
|
+
const id = nextId++;
|
|
22
|
+
scheduled.set(id, { at: clock + ms, fn });
|
|
23
|
+
return id;
|
|
24
|
+
},
|
|
25
|
+
clear: (id) => {
|
|
26
|
+
scheduled.delete(id as number);
|
|
27
|
+
},
|
|
28
|
+
},
|
|
29
|
+
);
|
|
30
|
+
return {
|
|
31
|
+
stop,
|
|
32
|
+
intents: () => intents,
|
|
33
|
+
pendingTimers: () => scheduled.size,
|
|
34
|
+
fire: (type: string, props: Record<string, unknown> = {}) => {
|
|
35
|
+
el.dispatchEvent(Object.assign(new Event(type), props));
|
|
36
|
+
},
|
|
37
|
+
advance: (ms: number) => {
|
|
38
|
+
clock += ms;
|
|
39
|
+
for (const [id, t] of [...scheduled]) {
|
|
40
|
+
if (t.at <= clock) {
|
|
41
|
+
scheduled.delete(id);
|
|
42
|
+
t.fn();
|
|
43
|
+
}
|
|
44
|
+
}
|
|
45
|
+
},
|
|
46
|
+
};
|
|
47
|
+
}
|
|
48
|
+
|
|
49
|
+
describe("link intent", () => {
|
|
50
|
+
test("a cursor that stays on the link is intent", () => {
|
|
51
|
+
const h = harness();
|
|
52
|
+
h.fire("mouseenter");
|
|
53
|
+
h.advance(HOVER_INTENT_MS - 1);
|
|
54
|
+
expect(h.intents()).toBe(0);
|
|
55
|
+
h.advance(1);
|
|
56
|
+
expect(h.intents()).toBe(1);
|
|
57
|
+
});
|
|
58
|
+
|
|
59
|
+
test("a cursor that crosses the link is not intent", () => {
|
|
60
|
+
const h = harness();
|
|
61
|
+
h.fire("mouseenter");
|
|
62
|
+
h.advance(HOVER_INTENT_MS - 1);
|
|
63
|
+
h.fire("mouseleave");
|
|
64
|
+
h.advance(1000);
|
|
65
|
+
expect(h.intents()).toBe(0);
|
|
66
|
+
});
|
|
67
|
+
|
|
68
|
+
test("a list scrolled under a resting cursor asks for nothing", () => {
|
|
69
|
+
const h = harness();
|
|
70
|
+
for (let card = 0; card < 26; card++) {
|
|
71
|
+
h.fire("mouseenter");
|
|
72
|
+
h.advance(30);
|
|
73
|
+
h.fire("mouseleave");
|
|
74
|
+
}
|
|
75
|
+
h.advance(1000);
|
|
76
|
+
expect(h.intents()).toBe(0);
|
|
77
|
+
});
|
|
78
|
+
|
|
79
|
+
test("a touch that moves is a scroll, not intent", () => {
|
|
80
|
+
const h = harness();
|
|
81
|
+
h.fire("pointerdown", { pointerType: "touch" });
|
|
82
|
+
h.fire("touchstart");
|
|
83
|
+
h.advance(16);
|
|
84
|
+
h.fire("touchmove");
|
|
85
|
+
h.advance(1000);
|
|
86
|
+
expect(h.intents()).toBe(0);
|
|
87
|
+
});
|
|
88
|
+
|
|
89
|
+
test("a touch the browser cancels is not intent", () => {
|
|
90
|
+
const h = harness();
|
|
91
|
+
h.fire("touchstart");
|
|
92
|
+
h.fire("touchcancel");
|
|
93
|
+
h.advance(1000);
|
|
94
|
+
expect(h.intents()).toBe(0);
|
|
95
|
+
});
|
|
96
|
+
|
|
97
|
+
test("a touch that lifts before the timer asks for nothing", () => {
|
|
98
|
+
// A page can cancel the tap, and then no click follows. A timer left
|
|
99
|
+
// running would fetch a page the user did not open.
|
|
100
|
+
const h = harness();
|
|
101
|
+
h.fire("touchstart");
|
|
102
|
+
h.advance(TOUCH_INTENT_MS - 1);
|
|
103
|
+
h.fire("touchend");
|
|
104
|
+
h.advance(1000);
|
|
105
|
+
expect(h.intents()).toBe(0);
|
|
106
|
+
});
|
|
107
|
+
|
|
108
|
+
test("a touch that stays down is intent", () => {
|
|
109
|
+
const h = harness();
|
|
110
|
+
h.fire("pointerdown", { pointerType: "touch" });
|
|
111
|
+
h.fire("touchstart");
|
|
112
|
+
expect(h.intents()).toBe(0);
|
|
113
|
+
h.advance(TOUCH_INTENT_MS);
|
|
114
|
+
expect(h.intents()).toBe(1);
|
|
115
|
+
});
|
|
116
|
+
|
|
117
|
+
test("a mouse press is intent at once", () => {
|
|
118
|
+
const h = harness();
|
|
119
|
+
h.fire("mouseenter");
|
|
120
|
+
h.fire("pointerdown", { pointerType: "mouse" });
|
|
121
|
+
expect(h.intents()).toBe(1);
|
|
122
|
+
// The hover timer the press replaced does not fire a second time.
|
|
123
|
+
h.advance(1000);
|
|
124
|
+
expect(h.intents()).toBe(1);
|
|
125
|
+
});
|
|
126
|
+
|
|
127
|
+
test("focus is intent at once", () => {
|
|
128
|
+
const h = harness();
|
|
129
|
+
h.fire("focus");
|
|
130
|
+
expect(h.intents()).toBe(1);
|
|
131
|
+
});
|
|
132
|
+
|
|
133
|
+
test("a click cancels a pending timer", () => {
|
|
134
|
+
// A quick tap: the browser sends mouseenter and click together after the
|
|
135
|
+
// finger lifts. The click fetches the page; a timer firing after it would
|
|
136
|
+
// render the page again.
|
|
137
|
+
const h = harness();
|
|
138
|
+
h.fire("touchstart");
|
|
139
|
+
h.advance(TOUCH_INTENT_MS - 1);
|
|
140
|
+
h.fire("mouseenter");
|
|
141
|
+
h.fire("click");
|
|
142
|
+
h.advance(1000);
|
|
143
|
+
expect(h.intents()).toBe(0);
|
|
144
|
+
});
|
|
145
|
+
|
|
146
|
+
test("stop cancels a pending timer and removes the listeners", () => {
|
|
147
|
+
const h = harness();
|
|
148
|
+
h.fire("mouseenter");
|
|
149
|
+
h.stop();
|
|
150
|
+
expect(h.pendingTimers()).toBe(0);
|
|
151
|
+
h.fire("focus");
|
|
152
|
+
h.advance(1000);
|
|
153
|
+
expect(h.intents()).toBe(0);
|
|
154
|
+
});
|
|
155
|
+
});
|
|
@@ -0,0 +1,98 @@
|
|
|
1
|
+
// Decides when a pointer, a finger, or the keyboard is aiming at a link.
|
|
2
|
+
//
|
|
3
|
+
// `<Link>` fetches the destination's page on intent, and each fetch is a
|
|
4
|
+
// server render. A cursor crosses links it is not aiming at, and a scroll
|
|
5
|
+
// starts with a touch on whatever is under the finger, so neither a bare
|
|
6
|
+
// mouseenter nor a bare touchstart is intent:
|
|
7
|
+
// - Hover counts once the cursor has stayed on the link for
|
|
8
|
+
// HOVER_INTENT_MS.
|
|
9
|
+
// - A touch counts once it has stayed down for TOUCH_INTENT_MS with no
|
|
10
|
+
// movement. A touch that moves is a scroll. A touch that lifts sooner
|
|
11
|
+
// is a tap, and the click fetches the page.
|
|
12
|
+
// - A mouse or pen press counts at once.
|
|
13
|
+
// - Focus counts at once.
|
|
14
|
+
//
|
|
15
|
+
// Kept apart from Link.tsx so the rules are unit-testable with a plain
|
|
16
|
+
// EventTarget and injected timers.
|
|
17
|
+
|
|
18
|
+
/** A cursor crossing a link on its way elsewhere leaves it sooner than this. */
|
|
19
|
+
export const HOVER_INTENT_MS = 80;
|
|
20
|
+
/** A scroll moves the finger sooner than this; a tap lasts longer. */
|
|
21
|
+
export const TOUCH_INTENT_MS = 60;
|
|
22
|
+
|
|
23
|
+
export interface IntentTimers {
|
|
24
|
+
set(fn: () => void, ms: number): unknown;
|
|
25
|
+
clear(handle: unknown): void;
|
|
26
|
+
}
|
|
27
|
+
|
|
28
|
+
const windowTimers: IntentTimers = {
|
|
29
|
+
set: (fn, ms) => setTimeout(fn, ms),
|
|
30
|
+
clear: (handle) => clearTimeout(handle as ReturnType<typeof setTimeout>),
|
|
31
|
+
};
|
|
32
|
+
|
|
33
|
+
/**
|
|
34
|
+
* Call `onIntent` each time the user aims at `el`. Returns a function that
|
|
35
|
+
* removes the listeners and cancels a pending timer.
|
|
36
|
+
*/
|
|
37
|
+
export function watchLinkIntent(
|
|
38
|
+
el: EventTarget,
|
|
39
|
+
onIntent: () => void,
|
|
40
|
+
timers: IntentTimers = windowTimers,
|
|
41
|
+
): () => void {
|
|
42
|
+
let pending: unknown = null;
|
|
43
|
+
const disarm = () => {
|
|
44
|
+
if (pending === null) return;
|
|
45
|
+
timers.clear(pending);
|
|
46
|
+
pending = null;
|
|
47
|
+
};
|
|
48
|
+
const arm = (ms: number) => {
|
|
49
|
+
disarm();
|
|
50
|
+
pending = timers.set(() => {
|
|
51
|
+
pending = null;
|
|
52
|
+
onIntent();
|
|
53
|
+
}, ms);
|
|
54
|
+
};
|
|
55
|
+
const now = () => {
|
|
56
|
+
disarm();
|
|
57
|
+
onIntent();
|
|
58
|
+
};
|
|
59
|
+
|
|
60
|
+
const onMouseEnter = () => arm(HOVER_INTENT_MS);
|
|
61
|
+
const onTouchStart = () => arm(TOUCH_INTENT_MS);
|
|
62
|
+
// A touch also fires pointerdown, before touchstart. The touch rules above
|
|
63
|
+
// decide for it.
|
|
64
|
+
const onPointerDown = (e: Event) => {
|
|
65
|
+
if ((e as PointerEvent).pointerType === "touch") return;
|
|
66
|
+
now();
|
|
67
|
+
};
|
|
68
|
+
|
|
69
|
+
// [event, handler, passive]
|
|
70
|
+
const listeners: Array<[string, (e: Event) => void, boolean]> = [
|
|
71
|
+
["mouseenter", onMouseEnter, false],
|
|
72
|
+
["mouseleave", disarm, false],
|
|
73
|
+
["touchstart", onTouchStart, true],
|
|
74
|
+
["touchmove", disarm, true],
|
|
75
|
+
["touchcancel", disarm, false],
|
|
76
|
+
// The finger lifted before the timer. A tap is followed by a click, which
|
|
77
|
+
// fetches the page. A page that cancels the tap gets no click, and then
|
|
78
|
+
// nothing should be fetched.
|
|
79
|
+
["touchend", disarm, false],
|
|
80
|
+
// A press starts ~100 ms before the click: enough to start the fetch.
|
|
81
|
+
["pointerdown", onPointerDown, false],
|
|
82
|
+
// Focus is the keyboard's version of hover, and a stronger signal: nobody
|
|
83
|
+
// tabs onto a link idly.
|
|
84
|
+
["focus", now, false],
|
|
85
|
+
// The click fetches the page itself. A timer that fired after it would
|
|
86
|
+
// render the same page a second time.
|
|
87
|
+
["click", disarm, false],
|
|
88
|
+
];
|
|
89
|
+
for (const [type, handler, passive] of listeners) {
|
|
90
|
+
el.addEventListener(type, handler, passive ? { passive: true } : undefined);
|
|
91
|
+
}
|
|
92
|
+
return () => {
|
|
93
|
+
disarm();
|
|
94
|
+
for (const [type, handler] of listeners) {
|
|
95
|
+
el.removeEventListener(type, handler);
|
|
96
|
+
}
|
|
97
|
+
};
|
|
98
|
+
}
|