@lostgradient/cinder 0.25.0 → 0.26.0
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/CHANGELOG.md +233 -0
- package/components.json +13 -6
- package/dist/components/accordion-item/accordion-item.css +0 -10
- package/dist/components/action-row/action-row.css +0 -9
- package/dist/components/alert/alert.css +0 -1
- package/dist/components/alert-dialog/index.js +2 -2
- package/dist/components/approval-card/index.js +2 -2
- package/dist/components/area-chart/index.js +2 -2
- package/dist/components/autocomplete/index.js +2 -2
- package/dist/components/avatar-group/avatar-group.css +0 -2
- package/dist/components/avatar-group/index.js +2 -2
- package/dist/components/backdrop/index.js +2 -2
- package/dist/components/bar-chart/index.js +2 -2
- package/dist/components/button/button.css +4 -4
- package/dist/components/button/button.variables.js +2 -2
- package/dist/components/card/card.css +0 -2
- package/dist/components/carousel/carousel.css +0 -5
- package/dist/components/checkbox/index.js +2 -2
- package/dist/components/code-block/code-block.css +0 -5
- package/dist/components/code-block/index.js +2 -2
- package/dist/components/color-field/index.js +2 -2
- package/dist/components/combobox/index.js +2 -2
- package/dist/components/command-menu/index.js +2 -2
- package/dist/components/command-palette/command-palette.css +50 -46
- package/dist/components/command-palette/index.js +2 -2
- package/dist/components/confirm-dialog/index.js +2 -2
- package/dist/components/context-menu/index.js +2 -2
- package/dist/components/data-table/data-table.css +0 -2
- package/dist/components/data-table/index.js +2 -2
- package/dist/components/date-picker/index.js +2 -2
- package/dist/components/date-range-field/index.js +2 -2
- package/dist/components/drawer/index.js +2 -2
- package/dist/components/dropdown/index.js +2 -2
- package/dist/components/dropdown-menu/index.js +2 -2
- package/dist/components/feed-event/feed-event.css +0 -2
- package/dist/components/file-upload/file-upload.css +0 -5
- package/dist/components/find-bar/find-bar.css +9 -1
- package/dist/components/focus-trap/index.js +2 -2
- package/dist/components/form-field/index.js +2 -2
- package/dist/components/guidance-region/index.css +1 -1
- package/dist/components/hover-card/index.js +2 -2
- package/dist/components/inline-confirm/index.js +2 -2
- package/dist/components/input/index.js +2 -2
- package/dist/components/input/input.css +95 -6
- package/dist/components/invocation-rule-builder/index.js +2 -2
- package/dist/components/json-editor/index.js +2 -2
- package/dist/components/json-schema-editor/index.js +4 -4
- package/dist/components/kanban-board/kanban-board.css +0 -10
- package/dist/components/key-value-editor/index.css +1 -1
- package/dist/components/line-chart/index.js +2 -2
- package/dist/components/marquee/marquee.css +0 -2
- package/dist/components/matrix-chart/index.js +2 -2
- package/dist/components/menu-bar/index.js +3 -3
- package/dist/components/modal/index.js +2 -2
- package/dist/components/modal/modal.css +0 -26
- package/dist/components/modal-region/index.css +1 -1
- package/dist/components/multi-select/index.js +2 -2
- package/dist/components/navigation-bar/index.js +2 -2
- package/dist/components/parameter-field/index.js +2 -2
- package/dist/components/permission-matrix/index.js +2 -2
- package/dist/components/policy-lock/index.js +2 -2
- package/dist/components/popover/index.js +2 -2
- package/dist/components/radio-group/index.js +2 -2
- package/dist/components/schedule-builder/index.js +2 -2
- package/dist/components/schema-form/index.js +2 -2
- package/dist/components/scroll-area/index.js +2 -2
- package/dist/components/select/index.js +2 -2
- package/dist/components/selectable-row/selectable-row.css +0 -6
- package/dist/components/selection-popover/index.js +2 -2
- package/dist/components/share-card/index.js +2 -2
- package/dist/components/side-navigation/side-navigation.css +0 -1
- package/dist/components/sidebar/index.js +2 -2
- package/dist/components/speed-dial/index.js +2 -2
- package/dist/components/statistic/statistic.css +0 -8
- package/dist/components/statistic-group/index.js +2 -2
- package/dist/components/statistic-group/statistic-group.css +116 -69
- package/dist/components/status-dot/status-dot.css +0 -3
- package/dist/components/table/index.js +2 -2
- package/dist/components/table-of-contents/table-of-contents.css +0 -4
- package/dist/components/textarea/index.js +2 -2
- package/dist/components/time-field/index.js +2 -2
- package/dist/components/time-field/time-field.css +9 -8
- package/dist/components/toast-region/index.js +2 -2
- package/dist/components/toggle/toggle.variables.js +2 -2
- package/dist/components/tooltip/index.js +2 -2
- package/dist/components/transfer-list/index.js +2 -2
- package/dist/components/tree/tree.css +0 -3
- package/dist/components/virtual-list/_internal/adaptive-overscan.d.ts +87 -0
- package/dist/components/virtual-list/_internal/edge-proximity.d.ts +75 -0
- package/dist/components/virtual-list/_internal/frame-scheduler.d.ts +76 -0
- package/dist/components/virtual-list/_internal/geometry.d.ts +170 -0
- package/dist/components/virtual-list/_internal/list-semantics.d.ts +93 -0
- package/dist/components/virtual-list/_internal/measurement-window.d.ts +125 -0
- package/dist/components/virtual-list/_internal/reverse-order.d.ts +87 -0
- package/dist/components/virtual-list/_internal/scroll-restoration.d.ts +98 -0
- package/dist/components/virtual-list/_internal/sticky-items.d.ts +48 -0
- package/dist/components/virtual-list/_internal/virtual-list-measurement-store.svelte.d.ts +69 -0
- package/dist/components/virtual-list/index.d.ts +1 -1
- package/dist/components/virtual-list/index.js +2 -2
- package/dist/components/virtual-list/virtual-list.css +153 -2
- package/dist/components/virtual-list/virtual-list.schema.js +69 -6
- package/dist/components/virtual-list/virtual-list.svelte.d.ts +11 -8
- package/dist/components/virtual-list/virtual-list.types.d.ts +177 -4
- package/dist/index.browser.css +1 -1
- package/dist/index.d.ts +1 -1
- package/dist/index.js +18 -18
- package/dist/server/components/alert-dialog/index.js +1 -1
- package/dist/server/components/approval-card/index.js +1 -1
- package/dist/server/components/area-chart/index.js +1 -1
- package/dist/server/components/autocomplete/index.js +1 -1
- package/dist/server/components/avatar-group/index.js +1 -1
- package/dist/server/components/backdrop/index.js +1 -1
- package/dist/server/components/bar-chart/index.js +1 -1
- package/dist/server/components/checkbox/index.js +1 -1
- package/dist/server/components/code-block/index.js +1 -1
- package/dist/server/components/color-field/index.js +1 -1
- package/dist/server/components/combobox/index.js +1 -1
- package/dist/server/components/command-menu/index.js +1 -1
- package/dist/server/components/command-palette/index.js +2 -2
- package/dist/server/components/confirm-dialog/index.js +1 -1
- package/dist/server/components/context-menu/index.js +1 -1
- package/dist/server/components/data-table/index.js +1 -1
- package/dist/server/components/date-picker/index.js +1 -1
- package/dist/server/components/date-range-field/index.js +1 -1
- package/dist/server/components/drawer/index.js +1 -1
- package/dist/server/components/dropdown/index.js +1 -1
- package/dist/server/components/dropdown-menu/index.js +2 -2
- package/dist/server/components/focus-trap/index.js +1 -1
- package/dist/server/components/form-field/index.js +1 -1
- package/dist/server/components/hover-card/index.js +1 -1
- package/dist/server/components/inline-confirm/index.js +1 -1
- package/dist/server/components/input/index.js +1 -1
- package/dist/server/components/invocation-rule-builder/index.js +1 -1
- package/dist/server/components/json-editor/index.js +1 -1
- package/dist/server/components/json-schema-editor/index.js +1 -1
- package/dist/server/components/line-chart/index.js +1 -1
- package/dist/server/components/matrix-chart/index.js +1 -1
- package/dist/server/components/menu-bar/index.js +2 -2
- package/dist/server/components/modal/index.js +1 -1
- package/dist/server/components/multi-select/index.js +1 -1
- package/dist/server/components/navigation-bar/index.js +2 -2
- package/dist/server/components/parameter-field/index.js +1 -1
- package/dist/server/components/permission-matrix/index.js +1 -1
- package/dist/server/components/policy-lock/index.js +1 -1
- package/dist/server/components/popover/index.js +1 -1
- package/dist/server/components/radio-group/index.js +1 -1
- package/dist/server/components/schedule-builder/index.js +1 -1
- package/dist/server/components/schema-form/index.js +1 -1
- package/dist/server/components/scroll-area/index.js +1 -1
- package/dist/server/components/select/index.js +1 -1
- package/dist/server/components/selection-popover/index.js +1 -1
- package/dist/server/components/share-card/index.js +1 -1
- package/dist/server/components/sidebar/index.js +1 -1
- package/dist/server/components/speed-dial/index.js +2 -2
- package/dist/server/components/statistic-group/index.js +1 -1
- package/dist/server/components/table/index.js +1 -1
- package/dist/server/components/textarea/index.js +1 -1
- package/dist/server/components/time-field/index.js +1 -1
- package/dist/server/components/toast-region/index.js +1 -1
- package/dist/server/components/tooltip/index.js +1 -1
- package/dist/server/components/transfer-list/index.js +1 -1
- package/dist/server/components/virtual-list/index.js +2 -2
- package/dist/server/index.js +2 -2
- package/dist/server/{index.server-skq0f5sr.js → index.server-0jw25w9w.js} +1 -1
- package/dist/server/index.server-0kk20wvp.js +4 -0
- package/dist/server/{index.server-fzsqdajc.js → index.server-2awq6q9m.js} +1 -1
- package/dist/server/{index.server-e4hmhaeh.js → index.server-3xwvw6w2.js} +3 -3
- package/dist/server/{index.server-95h7xy01.js → index.server-428dh2t9.js} +2 -2
- package/dist/server/{index.server-jd88r74m.js → index.server-5dq66aja.js} +2 -2
- package/dist/server/{index.server-dvwfhf77.js → index.server-5s94r0kk.js} +2 -2
- package/dist/server/{index.server-qv6z5ta3.js → index.server-80qgcjnm.js} +1 -1
- package/dist/server/{index.server-7k2732ky.js → index.server-81abtrsw.js} +1 -1
- package/dist/server/{index.server-csmqnx5w.js → index.server-83q1gv2c.js} +1 -1
- package/dist/server/{index.server-qw8k9rjg.js → index.server-8fyav10d.js} +1 -1
- package/dist/server/{index.server-4dgjj4k1.js → index.server-8h5caecr.js} +2 -2
- package/dist/server/{index.server-emyqytmm.js → index.server-90n8sd9e.js} +1 -1
- package/dist/server/{index.server-0xrdyzvh.js → index.server-99penx1m.js} +1 -1
- package/dist/server/{index.server-p94j3jah.js → index.server-9g9d15z1.js} +1 -1
- package/dist/server/{index.server-xp9hkc81.js → index.server-9kbdx511.js} +1 -1
- package/dist/server/index.server-a2yhk45s.js +3 -0
- package/dist/server/{index.server-g8d2m2tk.js → index.server-acq55gjs.js} +1 -1
- package/dist/server/{index.server-ewze54tv.js → index.server-afjftjmr.js} +1 -1
- package/dist/server/{index.server-ejyye4gv.js → index.server-bfed6a8a.js} +1 -1
- package/dist/server/{index.server-z5ng08q2.js → index.server-c1746s0z.js} +1 -1
- package/dist/server/{index.server-gt1tfc1w.js → index.server-dmeztywe.js} +1 -1
- package/dist/server/{index.server-kzsppq0n.js → index.server-dyj3jdx9.js} +1 -1
- package/dist/server/index.server-dz92zvx6.js +4 -0
- package/dist/server/{index.server-3md8kdcr.js → index.server-e6682k08.js} +1 -1
- package/dist/server/{index.server-t1pshh65.js → index.server-ewkv461x.js} +1 -1
- package/dist/server/{index.server-zfgwhtmp.js → index.server-fa449wd3.js} +1 -1
- package/dist/server/{index.server-1kgwayct.js → index.server-fhfypmgw.js} +1 -1
- package/dist/server/{index.server-s4z8hsby.js → index.server-ge4adxs2.js} +1 -1
- package/dist/server/{index.server-68xyfsg3.js → index.server-gggkq22y.js} +2 -2
- package/dist/server/{index.server-acgwdamx.js → index.server-j52rbk57.js} +1 -1
- package/dist/server/{index.server-z0nwftx6.js → index.server-jm89hxfb.js} +1 -1
- package/dist/server/{index.server-xa98r8p2.js → index.server-jw0v64se.js} +1 -1
- package/dist/server/index.server-m321p69g.js +3 -0
- package/dist/server/{index.server-xyervw3d.js → index.server-m7q2tc41.js} +1 -1
- package/dist/server/{index.server-tnrxy86j.js → index.server-mak7dmj2.js} +1 -1
- package/dist/server/{index.server-n5g5h5k1.js → index.server-mw5r2524.js} +1 -1
- package/dist/server/{index.server-caf7s6m7.js → index.server-nwq1cg55.js} +1 -1
- package/dist/server/{index.server-3wdvs0wr.js → index.server-p423fy4q.js} +2 -2
- package/dist/server/{index.server-ks7fvwxt.js → index.server-prk5syj2.js} +1 -1
- package/dist/server/{index.server-6w9fp018.js → index.server-q4hytsq3.js} +1 -1
- package/dist/server/{index.server-5w2qw8fm.js → index.server-q597a1ck.js} +1 -1
- package/dist/server/{index.server-fz1pkvda.js → index.server-qgne9v2w.js} +1 -1
- package/dist/server/{index.server-1f2app32.js → index.server-rvdavf92.js} +1 -1
- package/dist/server/index.server-rwq20a22.js +3 -0
- package/dist/server/{index.server-0rvmnrw2.js → index.server-s9tjs45r.js} +1 -1
- package/dist/server/{index.server-cm2prec7.js → index.server-sqgxyfsw.js} +1 -1
- package/dist/server/{index.server-v6777tgn.js → index.server-t761nwvb.js} +1 -1
- package/dist/server/index.server-tbds8nwq.js +4 -0
- package/dist/server/index.server-tyhta5n3.js +3 -0
- package/dist/server/{index.server-yw7rah51.js → index.server-v5dxham4.js} +1 -1
- package/dist/server/index.server-va98cpyf.js +3 -0
- package/dist/server/index.server-vq1k69xt.js +3 -0
- package/dist/server/{index.server-egd355s6.js → index.server-wnf9btp7.js} +2 -2
- package/dist/server/{index.server-sjcbaztf.js → index.server-y3zgdtbv.js} +1 -1
- package/dist/server/{index.server-4tjtgzf9.js → index.server-y6vtbmyj.js} +1 -1
- package/dist/server/{index.server-2p2mjzzb.js → index.server-zff2qp1v.js} +1 -1
- package/dist/server/tokens/registry.generated.js +2 -2
- package/dist/tokens/registry.generated.js +2 -2
- package/package.json +2 -2
- package/src/_internal/form-field-frame.svelte +5 -0
- package/src/_internal/overlay.ts +14 -1
- package/src/components/_internal/create-command-list-state.svelte.ts +4 -0
- package/src/components/accordion-item/accordion-item.css +0 -10
- package/src/components/action-row/action-row.css +0 -9
- package/src/components/alert/alert.css +0 -1
- package/src/components/avatar-group/avatar-group.css +0 -2
- package/src/components/button/button.css +4 -4
- package/src/components/button/button.variables.json +31 -1
- package/src/components/button/button.variables.ts +31 -1
- package/src/components/card/card.css +0 -2
- package/src/components/carousel/carousel.css +0 -5
- package/src/components/code-block/code-block.css +0 -5
- package/src/components/command-menu/command-menu.svelte +63 -7
- package/src/components/command-palette/command-palette.css +50 -46
- package/src/components/command-palette/command-palette.svelte +68 -78
- package/src/components/data-table/data-table.css +0 -2
- package/src/components/dropdown/dropdown.svelte +73 -18
- package/src/components/dropdown-menu/dropdown-menu.svelte +63 -7
- package/src/components/feed-event/feed-event.css +0 -2
- package/src/components/file-upload/file-upload.css +0 -5
- package/src/components/find-bar/find-bar.css +9 -1
- package/src/components/input/input.css +95 -6
- package/src/components/input/input.svelte +44 -81
- package/src/components/kanban-board/kanban-board.css +0 -10
- package/src/components/marquee/marquee.css +0 -2
- package/src/components/menu-bar/menu-bar.svelte +12 -1
- package/src/components/modal/modal.css +0 -26
- package/src/components/multi-select/multi-select.svelte +7 -0
- package/src/components/navigation-bar/navigation-bar.svelte +82 -6
- package/src/components/selectable-row/selectable-row.css +0 -6
- package/src/components/selection-popover/selection-popover.svelte +24 -10
- package/src/components/share-card/share-card.svelte +24 -44
- package/src/components/side-navigation/side-navigation.css +0 -1
- package/src/components/speed-dial/speed-dial.svelte +23 -5
- package/src/components/statistic/statistic.css +0 -8
- package/src/components/statistic-group/statistic-group.css +116 -69
- package/src/components/statistic-group/statistic-group.examples.json +6 -0
- package/src/components/statistic-group/statistic-group.svelte +13 -1
- package/src/components/status-dot/status-dot.css +0 -3
- package/src/components/table-of-contents/table-of-contents.css +0 -4
- package/src/components/time-field/time-field.css +9 -8
- package/src/components/toast-region/toast-region.svelte +9 -0
- package/src/components/toggle/toggle.variables.json +1 -1
- package/src/components/toggle/toggle.variables.ts +4 -1
- package/src/components/tree/tree.css +0 -3
- package/src/components/virtual-list/_internal/adaptive-overscan.ts +248 -0
- package/src/components/virtual-list/_internal/edge-proximity.ts +130 -0
- package/src/components/virtual-list/_internal/frame-scheduler.ts +136 -0
- package/src/components/virtual-list/_internal/geometry.ts +236 -0
- package/src/components/virtual-list/_internal/list-semantics.ts +151 -0
- package/src/components/virtual-list/_internal/measurement-window.ts +300 -0
- package/src/components/virtual-list/_internal/reverse-order.ts +146 -0
- package/src/components/virtual-list/_internal/scroll-restoration.ts +209 -0
- package/src/components/virtual-list/_internal/sticky-items.ts +111 -0
- package/src/components/virtual-list/_internal/virtual-list-measurement-store.svelte.ts +145 -0
- package/src/components/virtual-list/index.ts +7 -1
- package/src/components/virtual-list/virtual-list.css +153 -2
- package/src/components/virtual-list/virtual-list.examples.json +42 -0
- package/src/components/virtual-list/virtual-list.schema.json +53 -3
- package/src/components/virtual-list/virtual-list.schema.ts +64 -3
- package/src/components/virtual-list/virtual-list.svelte +1527 -36
- package/src/components/virtual-list/virtual-list.types.ts +181 -4
- package/src/index.ts +3 -0
- package/src/styles/tokens-base.css +57 -22
- package/src/tokens/cinder.resolver.json +8 -0
- package/src/tokens/index.json +1 -1
- package/src/tokens/registry.generated.json +30 -4
- package/src/tokens/registry.generated.ts +32 -4
- package/src/tokens/resolved/dark-reduced-motion.json +47 -17
- package/src/tokens/resolved/dark.json +47 -17
- package/src/tokens/resolved/light-reduced-motion.json +48 -18
- package/src/tokens/resolved/light.json +48 -18
- package/src/tokens/sets/components.tokens.json +1 -1
- package/src/tokens/sets/semantic.tokens.json +120 -30
- package/src/tokens/themes/dark.tokens.json +115 -19
- package/src/tokens/themes/light.tokens.json +51 -3
- package/dist/server/index.server-191cnacw.js +0 -3
- package/dist/server/index.server-25dqx151.js +0 -3
- package/dist/server/index.server-77jyqvbv.js +0 -4
- package/dist/server/index.server-bgjrzr70.js +0 -3
- package/dist/server/index.server-khsp90vh.js +0 -3
- package/dist/server/index.server-ryk2pgbe.js +0 -4
- package/dist/server/index.server-tajr81bm.js +0 -3
- package/dist/server/index.server-vjzcrw3d.js +0 -4
- package/dist/server/index.server-zg3fx1n1.js +0 -3
|
@@ -0,0 +1,248 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Velocity-adaptive overscan for the virtual list (CIN-203).
|
|
3
|
+
*
|
|
4
|
+
* Everything in this module is dependency-free arithmetic: no DOM, no runes,
|
|
5
|
+
* no `performance.now()`, no timers. It tracks scroll velocity from a stream
|
|
6
|
+
* of `(scrollOffset, timestamp)` samples the caller hands it — Svelte's
|
|
7
|
+
* `scroll` handler is the natural source, but nothing here reads it — and
|
|
8
|
+
* turns that velocity into extra rows of overscan so a fast fling has rows
|
|
9
|
+
* already mounted before they scroll into view. The configured `overscan`
|
|
10
|
+
* the consumer asked for is always the FLOOR: adaptation only ever adds rows
|
|
11
|
+
* on top of it, never renders fewer than the consumer's own request.
|
|
12
|
+
*/
|
|
13
|
+
|
|
14
|
+
/**
|
|
15
|
+
* Smoothing factor for the exponential moving average `trackScrollVelocity`
|
|
16
|
+
* applies to each newly observed instantaneous velocity. Chosen low (0.3) so
|
|
17
|
+
* one anomalous frame — a layout hiccup that reports two samples 40ms apart
|
|
18
|
+
* instead of the usual ~16ms, briefly reading as a much larger delta over
|
|
19
|
+
* time — only pulls the smoothed velocity 30% of the way toward that spike
|
|
20
|
+
* rather than jumping there outright. High enough that a genuine, sustained
|
|
21
|
+
* velocity change still converges within a handful of frames (about 5
|
|
22
|
+
* samples closes 80% of the gap) instead of visibly lagging the reader's
|
|
23
|
+
* actual scroll speed.
|
|
24
|
+
*/
|
|
25
|
+
const VELOCITY_SMOOTHING_FACTOR = 0.3;
|
|
26
|
+
|
|
27
|
+
/**
|
|
28
|
+
* Elapsed time, in milliseconds, beyond which two samples are treated as
|
|
29
|
+
* belonging to separate scroll gestures rather than one continuous scroll,
|
|
30
|
+
* resetting the tracked velocity to 0 instead of measuring a delta across
|
|
31
|
+
* the gap. Momentum/wheel scroll callbacks fire roughly every 16ms (one
|
|
32
|
+
* frame at 60Hz) while actively scrolling, so a gap this much larger than a
|
|
33
|
+
* frame can only mean the reader stopped. 250ms sits comfortably above the
|
|
34
|
+
* largest gap a live scroll should ever produce — even a dropped frame or
|
|
35
|
+
* two — while still being short enough that a reader who pauses mid-scroll
|
|
36
|
+
* and resumes quickly reads as having genuinely stopped, rather than
|
|
37
|
+
* smoothing a fast-then-idle-then-fast sequence into one continuous "fast"
|
|
38
|
+
* reading.
|
|
39
|
+
*/
|
|
40
|
+
const IDLE_RESET_THRESHOLD_IN_MILLISECONDS = 250;
|
|
41
|
+
|
|
42
|
+
/**
|
|
43
|
+
* Immutable scroll-velocity state. Threaded through calls exactly like the
|
|
44
|
+
* offsets/measurement state elsewhere in `_internal`: `createVelocityTracker`
|
|
45
|
+
* produces the initial value, `trackScrollVelocity` takes one and returns a
|
|
46
|
+
* new one — the input is never mutated, so callers (an `$effect`, a test) can
|
|
47
|
+
* hold onto an old tracker and compare it against a new one safely.
|
|
48
|
+
*/
|
|
49
|
+
export type VelocityTracker = {
|
|
50
|
+
/**
|
|
51
|
+
* The scroll offset and timestamp of the last sample folded in, or `null`
|
|
52
|
+
* before the first sample — `null` is what lets `trackScrollVelocity` tell
|
|
53
|
+
* "no previous sample to diff against" apart from "a previous sample that
|
|
54
|
+
* happened to sit at offset 0", which a sentinel number couldn't.
|
|
55
|
+
*/
|
|
56
|
+
readonly lastScrollOffset: number;
|
|
57
|
+
readonly lastTimestamp: number | null;
|
|
58
|
+
/** Smoothed scroll speed, in pixels per millisecond. Always a magnitude — never negative. */
|
|
59
|
+
readonly velocityInPixelsPerMillisecond: number;
|
|
60
|
+
};
|
|
61
|
+
|
|
62
|
+
/** The tracker's initial state: no prior sample, so no velocity yet. */
|
|
63
|
+
export function createVelocityTracker(): VelocityTracker {
|
|
64
|
+
return { lastScrollOffset: 0, lastTimestamp: null, velocityInPixelsPerMillisecond: 0 };
|
|
65
|
+
}
|
|
66
|
+
|
|
67
|
+
/**
|
|
68
|
+
* Folds one `(scrollOffset, timestamp)` sample into `tracker`, returning a
|
|
69
|
+
* new tracker with an updated, EMA-smoothed velocity in pixels per
|
|
70
|
+
* millisecond. `tracker` itself is never mutated.
|
|
71
|
+
*
|
|
72
|
+
* Velocity is always a magnitude: scrolling up and scrolling down at the
|
|
73
|
+
* same speed produce the same value, because pop-in risk depends on how far
|
|
74
|
+
* the viewport is about to sweep, not which direction it sweeps in.
|
|
75
|
+
*/
|
|
76
|
+
export function trackScrollVelocity(
|
|
77
|
+
tracker: VelocityTracker,
|
|
78
|
+
sample: { scrollOffset: number; timestamp: number },
|
|
79
|
+
): VelocityTracker {
|
|
80
|
+
// No previous sample to diff against — reporting a delta over zero known
|
|
81
|
+
// elapsed time would be Infinity/NaN, not 0, if this fell through to the
|
|
82
|
+
// general branch below. Anchor here instead and let the NEXT sample
|
|
83
|
+
// produce the first real velocity reading.
|
|
84
|
+
if (tracker.lastTimestamp === null) {
|
|
85
|
+
return {
|
|
86
|
+
lastScrollOffset: sample.scrollOffset,
|
|
87
|
+
lastTimestamp: sample.timestamp,
|
|
88
|
+
velocityInPixelsPerMillisecond: 0,
|
|
89
|
+
};
|
|
90
|
+
}
|
|
91
|
+
|
|
92
|
+
const elapsedInMilliseconds = sample.timestamp - tracker.lastTimestamp;
|
|
93
|
+
|
|
94
|
+
// Two events stamped in the same millisecond, or a clock that went
|
|
95
|
+
// backwards, would divide by zero (or a negative number). Rather than
|
|
96
|
+
// advance the anchor on a degenerate sample — which would leave a later,
|
|
97
|
+
// valid sample computing its delta over a shorter elapsed time than
|
|
98
|
+
// actually passed, under-reporting velocity — leave the tracker exactly as
|
|
99
|
+
// it was. The next sample with a genuinely later timestamp measures the
|
|
100
|
+
// full delta over the full elapsed time since the last valid anchor, as if
|
|
101
|
+
// the degenerate sample had never arrived.
|
|
102
|
+
if (elapsedInMilliseconds <= 0) {
|
|
103
|
+
return tracker;
|
|
104
|
+
}
|
|
105
|
+
|
|
106
|
+
// A gap this large means the reader stopped and later resumed, not that
|
|
107
|
+
// they scrolled continuously very slowly. Without this reset, an EMA blend
|
|
108
|
+
// would still weight in whatever velocity was current before the gap —
|
|
109
|
+
// stale by definition, since it describes motion that ended long ago — and
|
|
110
|
+
// report it alongside a fresh sample as if the scroll had been continuous.
|
|
111
|
+
// Resetting treats the fresh sample as a new anchor, exactly like the
|
|
112
|
+
// first-sample case, so the gap costs one reading of 0 rather than a
|
|
113
|
+
// spurious blended spike.
|
|
114
|
+
if (elapsedInMilliseconds >= IDLE_RESET_THRESHOLD_IN_MILLISECONDS) {
|
|
115
|
+
return {
|
|
116
|
+
lastScrollOffset: sample.scrollOffset,
|
|
117
|
+
lastTimestamp: sample.timestamp,
|
|
118
|
+
velocityInPixelsPerMillisecond: 0,
|
|
119
|
+
};
|
|
120
|
+
}
|
|
121
|
+
|
|
122
|
+
const instantaneousVelocity =
|
|
123
|
+
Math.abs(sample.scrollOffset - tracker.lastScrollOffset) / elapsedInMilliseconds;
|
|
124
|
+
const smoothedVelocity =
|
|
125
|
+
VELOCITY_SMOOTHING_FACTOR * instantaneousVelocity +
|
|
126
|
+
(1 - VELOCITY_SMOOTHING_FACTOR) * tracker.velocityInPixelsPerMillisecond;
|
|
127
|
+
|
|
128
|
+
return {
|
|
129
|
+
lastScrollOffset: sample.scrollOffset,
|
|
130
|
+
lastTimestamp: sample.timestamp,
|
|
131
|
+
velocityInPixelsPerMillisecond: smoothedVelocity,
|
|
132
|
+
};
|
|
133
|
+
}
|
|
134
|
+
|
|
135
|
+
/**
|
|
136
|
+
* Assumed duration of one animation frame, in milliseconds, used to convert
|
|
137
|
+
* a velocity into "how far the list will travel before the next frame gets a
|
|
138
|
+
* chance to mount new rows." 60Hz (1000/60 ≈ 16.67ms) is the common
|
|
139
|
+
* denominator refresh rate. A higher-refresh display mounts more often than
|
|
140
|
+
* this assumes, which only makes overscan slightly more generous than
|
|
141
|
+
* strictly necessary there — harmless, since the floor/ceiling guarantees
|
|
142
|
+
* still hold either way. A lower-refresh or frame-dropping device is the
|
|
143
|
+
* case this constant actually protects: it travels FARTHER than one real
|
|
144
|
+
* frame implies, so erring toward this (rather than a shorter) frame
|
|
145
|
+
* duration keeps overscan from under-provisioning exactly when the risk of
|
|
146
|
+
* visible pop-in is highest.
|
|
147
|
+
*/
|
|
148
|
+
const ASSUMED_FRAME_DURATION_IN_MILLISECONDS = 1000 / 60;
|
|
149
|
+
|
|
150
|
+
/**
|
|
151
|
+
* Default ceiling on adaptive overscan when the consumer does not supply
|
|
152
|
+
* `maximumOverscan`. Overscan that scaled with velocity unbounded would mount
|
|
153
|
+
* thousands of rows during a fast fling, defeating the point of virtualizing
|
|
154
|
+
* at all — this clamp is the whole safety property. 50 extra rows on each
|
|
155
|
+
* side comfortably covers a genuinely fast fling without bounding DOM size at
|
|
156
|
+
* a number a real consumer would consider unreasonable.
|
|
157
|
+
*/
|
|
158
|
+
const DEFAULT_MAXIMUM_OVERSCAN = 50;
|
|
159
|
+
|
|
160
|
+
/**
|
|
161
|
+
* Resolves how many rows of overscan to render given the current scroll
|
|
162
|
+
* velocity. `baseOverscan` — the consumer's own configured `overscan`,
|
|
163
|
+
* default 5 — is always the floor: the result never drops below it,
|
|
164
|
+
* regardless of velocity. Extra rows are derived from velocity rather than a
|
|
165
|
+
* magic lookup table: roughly, however many whole item-heights the list will
|
|
166
|
+
* travel during one frame's worth of time at the current speed is how many
|
|
167
|
+
* additional rows need to already be mounted so they don't pop in.
|
|
168
|
+
*/
|
|
169
|
+
export function resolveAdaptiveOverscan(options: {
|
|
170
|
+
baseOverscan: number;
|
|
171
|
+
velocityInPixelsPerMillisecond: number;
|
|
172
|
+
itemSize: number;
|
|
173
|
+
maximumOverscan?: number;
|
|
174
|
+
}): number {
|
|
175
|
+
// Matches resolveVirtualOverscan's own floor/clamp convention elsewhere in
|
|
176
|
+
// this component: an overscan the consumer configured is expected to
|
|
177
|
+
// already be a non-negative integer, and a non-finite or negative one is a
|
|
178
|
+
// caller bug this guards against rather than propagates.
|
|
179
|
+
const baseOverscan = Number.isFinite(options.baseOverscan)
|
|
180
|
+
? Math.max(0, Math.floor(options.baseOverscan))
|
|
181
|
+
: 0;
|
|
182
|
+
|
|
183
|
+
// A zero (or negative) item size would divide by zero below, and a
|
|
184
|
+
// collapsed/unmeasured row gives no meaningful "rows per frame of travel"
|
|
185
|
+
// to derive — fall back to the floor rather than propagate NaN/Infinity.
|
|
186
|
+
if (!(options.itemSize > 0)) return baseOverscan;
|
|
187
|
+
|
|
188
|
+
const velocityInPixelsPerMillisecond = Number.isFinite(options.velocityInPixelsPerMillisecond)
|
|
189
|
+
? Math.max(0, options.velocityInPixelsPerMillisecond)
|
|
190
|
+
: 0;
|
|
191
|
+
|
|
192
|
+
const maximumOverscanOption = options.maximumOverscan;
|
|
193
|
+
const resolvedMaximumOverscan =
|
|
194
|
+
maximumOverscanOption !== undefined &&
|
|
195
|
+
Number.isFinite(maximumOverscanOption) &&
|
|
196
|
+
maximumOverscanOption > 0
|
|
197
|
+
? Math.floor(maximumOverscanOption)
|
|
198
|
+
: DEFAULT_MAXIMUM_OVERSCAN;
|
|
199
|
+
|
|
200
|
+
// Distance the list would travel in one frame at the current speed, in
|
|
201
|
+
// item-heights. Rounded up (not down) because even partial coverage into
|
|
202
|
+
// the next row means that row needs to be mounted for the frame it first
|
|
203
|
+
// becomes partially visible.
|
|
204
|
+
const extraRowsFromVelocity = Math.ceil(
|
|
205
|
+
(velocityInPixelsPerMillisecond * ASSUMED_FRAME_DURATION_IN_MILLISECONDS) / options.itemSize,
|
|
206
|
+
);
|
|
207
|
+
|
|
208
|
+
const overscan = baseOverscan + extraRowsFromVelocity;
|
|
209
|
+
|
|
210
|
+
// baseOverscan is the floor and resolvedMaximumOverscan the ceiling; the
|
|
211
|
+
// floor wins if the two ever conflict (e.g. a misconfigured maximumOverscan
|
|
212
|
+
// below baseOverscan), matching the acceptance criteria that adaptation
|
|
213
|
+
// never renders fewer rows than the consumer asked for. Every input to
|
|
214
|
+
// this expression is already an integer, so the result is too.
|
|
215
|
+
return Math.max(baseOverscan, Math.min(overscan, resolvedMaximumOverscan));
|
|
216
|
+
}
|
|
217
|
+
|
|
218
|
+
/**
|
|
219
|
+
* The row size adaptive overscan should convert a pixel velocity with.
|
|
220
|
+
*
|
|
221
|
+
* `estimateSize` is what the consumer guessed. In fixed mode that IS the row size and
|
|
222
|
+
* there is nothing to improve on. Under `dynamicSize` it is only a starting point, and
|
|
223
|
+
* the conversion from "pixels travelled this frame" to "rows to keep mounted" is
|
|
224
|
+
* exactly where being wrong hurts: with a 100px estimate over rows measuring 10px, a
|
|
225
|
+
* frame covering 100px reads as one row rather than the ten the viewport really
|
|
226
|
+
* crossed, so the window widens by a tenth of what the reader is outrunning.
|
|
227
|
+
*
|
|
228
|
+
* Averaged over the rows actually MEASURED, not over the whole collection. The offsets
|
|
229
|
+
* table's total blends measurements with estimates for every row not yet seen, and in
|
|
230
|
+
* a long list those estimates swamp the measurements — twenty measured rows of 10px
|
|
231
|
+
* among ten thousand estimated at 100px average out to 99.8px, which is the estimate
|
|
232
|
+
* again in all but name and leaves the ruler as wrong as it started.
|
|
233
|
+
*
|
|
234
|
+
* Falls back to the estimate until something has been measured, and if the measured
|
|
235
|
+
* average is not a usable positive number — a collection whose rows have all collapsed
|
|
236
|
+
* to zero, say.
|
|
237
|
+
*/
|
|
238
|
+
export function resolveAdaptiveItemSize(options: {
|
|
239
|
+
dynamicSize: boolean;
|
|
240
|
+
measuredTotalSize: number;
|
|
241
|
+
measuredCount: number;
|
|
242
|
+
estimateSize: number;
|
|
243
|
+
}): number {
|
|
244
|
+
if (!options.dynamicSize) return options.estimateSize;
|
|
245
|
+
if (options.measuredCount <= 0) return options.estimateSize;
|
|
246
|
+
const average = options.measuredTotalSize / options.measuredCount;
|
|
247
|
+
return Number.isFinite(average) && average > 0 ? average : options.estimateSize;
|
|
248
|
+
}
|
|
@@ -0,0 +1,130 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Pure edge-proximity detection for bi-directional infinite scroll in a
|
|
3
|
+
* virtual list (CIN-195 `onEndReached`, CIN-196 `onStartReached`).
|
|
4
|
+
*
|
|
5
|
+
* Deciding "are we near an edge" is simple index arithmetic. The hard part —
|
|
6
|
+
* and the entire reason this module exists — is deciding WHEN to fire a
|
|
7
|
+
* callback for that proximity, so a reader who scrolls around near the same
|
|
8
|
+
* edge, or who simply triggers a re-render while still sitting there, does
|
|
9
|
+
* not retrigger a data fetch on every frame. `resolveEdgeFireDecision` is
|
|
10
|
+
* the latch that answers that question; `resolveEdgeProximity` only
|
|
11
|
+
* computes the raw boolean state the latch reacts to.
|
|
12
|
+
*
|
|
13
|
+
* Dependency-free by design, matching the rest of `_internal/`: no DOM, no
|
|
14
|
+
* runes, no timers. `virtual-list.svelte` is expected to call
|
|
15
|
+
* `resolveEdgeProximity` once per scroll/measurement update, feed the
|
|
16
|
+
* result into `resolveEdgeFireDecision` alongside the latch state carried
|
|
17
|
+
* from the previous call, and store `next` for the following call.
|
|
18
|
+
*/
|
|
19
|
+
|
|
20
|
+
/** Whether the current window sits close enough to either edge of the list to consider firing a load callback. */
|
|
21
|
+
export type EdgeProximity = {
|
|
22
|
+
readonly isNearStart: boolean;
|
|
23
|
+
readonly isNearEnd: boolean;
|
|
24
|
+
};
|
|
25
|
+
|
|
26
|
+
/**
|
|
27
|
+
* Anti-repeat latch state carried between calls to `resolveEdgeFireDecision`.
|
|
28
|
+
* A latched edge has already fired for the CURRENT approach and stays
|
|
29
|
+
* suppressed until either the reader scrolls away (proximity goes false) or
|
|
30
|
+
* `itemCount` moves away from `itemCountAtLatch` — new items arrived in
|
|
31
|
+
* response to whatever fired last time, so the next approach is treated as
|
|
32
|
+
* genuinely new.
|
|
33
|
+
*/
|
|
34
|
+
export type EdgeLatch = {
|
|
35
|
+
readonly startLatched: boolean;
|
|
36
|
+
readonly endLatched: boolean;
|
|
37
|
+
/** itemCount as of the call that produced the current startLatched/endLatched values. */
|
|
38
|
+
readonly itemCountAtLatch: number;
|
|
39
|
+
};
|
|
40
|
+
|
|
41
|
+
/** The initial, unlatched state — nothing has fired yet. */
|
|
42
|
+
export function createEdgeLatch(): EdgeLatch {
|
|
43
|
+
return { startLatched: false, endLatched: false, itemCountAtLatch: 0 };
|
|
44
|
+
}
|
|
45
|
+
|
|
46
|
+
/**
|
|
47
|
+
* Computes raw start/end proximity from the current window and list shape.
|
|
48
|
+
* This is pure index arithmetic with no memory of prior calls — repeat-fire
|
|
49
|
+
* suppression is `resolveEdgeFireDecision`'s job, not this function's.
|
|
50
|
+
*/
|
|
51
|
+
export function resolveEdgeProximity(options: {
|
|
52
|
+
/**
|
|
53
|
+
* Accepted for parity with the sibling window/geometry helpers' options
|
|
54
|
+
* shape — every one of them takes a scroll offset — but proximity here is
|
|
55
|
+
* decided entirely in item-index space, so this field is not read.
|
|
56
|
+
*/
|
|
57
|
+
scrollOffset: number;
|
|
58
|
+
viewportSize: number;
|
|
59
|
+
totalSize: number;
|
|
60
|
+
firstVisibleIndex: number;
|
|
61
|
+
lastVisibleIndex: number;
|
|
62
|
+
itemCount: number;
|
|
63
|
+
overscan: number;
|
|
64
|
+
}): EdgeProximity {
|
|
65
|
+
// An empty list has no edges to reach. Reporting proximity here would let a
|
|
66
|
+
// caller fire a load callback against a source that, by definition, just
|
|
67
|
+
// returned nothing — and nothing would ever stop it from firing again.
|
|
68
|
+
if (options.itemCount <= 0) {
|
|
69
|
+
return { isNearStart: false, isNearEnd: false };
|
|
70
|
+
}
|
|
71
|
+
|
|
72
|
+
// A negative overscan would make every index comparison below vacuously
|
|
73
|
+
// false; a non-finite one (NaN from a bad measurement, +/-Infinity) would
|
|
74
|
+
// make every comparison vacuously true, or produce NaN comparisons that are
|
|
75
|
+
// always false. Neither is a usable threshold, so both collapse to 0.
|
|
76
|
+
const resolvedOverscan = Number.isFinite(options.overscan) ? Math.max(0, options.overscan) : 0;
|
|
77
|
+
|
|
78
|
+
// The whole list is already on screen, so there is no further scroll
|
|
79
|
+
// gesture that could bring either edge "more" into view. Reporting both
|
|
80
|
+
// edges as near lets a short list (e.g. the very first page of a
|
|
81
|
+
// bi-directional feed) still request the next and previous pages, instead
|
|
82
|
+
// of being stuck because it never crosses an overscan threshold it is
|
|
83
|
+
// already past.
|
|
84
|
+
if (options.totalSize <= options.viewportSize) {
|
|
85
|
+
return { isNearStart: true, isNearEnd: true };
|
|
86
|
+
}
|
|
87
|
+
|
|
88
|
+
return {
|
|
89
|
+
isNearStart: options.firstVisibleIndex <= resolvedOverscan,
|
|
90
|
+
isNearEnd: options.lastVisibleIndex >= options.itemCount - 1 - resolvedOverscan,
|
|
91
|
+
};
|
|
92
|
+
}
|
|
93
|
+
|
|
94
|
+
/**
|
|
95
|
+
* Turns raw proximity into a fire/no-fire decision via rising-edge
|
|
96
|
+
* detection: an edge fires only on the call where its proximity flips from
|
|
97
|
+
* not-near to near, or where `itemCount` moved since the latch was last set
|
|
98
|
+
* — which counts as a fresh approach even though proximity never dropped to
|
|
99
|
+
* false in between. Never mutates `previous`; callers store the returned
|
|
100
|
+
* `next` for the following call.
|
|
101
|
+
*/
|
|
102
|
+
export function resolveEdgeFireDecision(options: {
|
|
103
|
+
proximity: EdgeProximity;
|
|
104
|
+
previous: EdgeLatch;
|
|
105
|
+
itemCount: number;
|
|
106
|
+
}): { fireStart: boolean; fireEnd: boolean; next: EdgeLatch } {
|
|
107
|
+
// itemCount changing since the latch was set is direct evidence a batch of
|
|
108
|
+
// items landed in response to whatever fired last time, so treat any latch
|
|
109
|
+
// recorded against the old count as already released rather than requiring
|
|
110
|
+
// proximity to first drop to false and back to true. Without this, a list
|
|
111
|
+
// sitting still near one edge while new items keep arriving there would
|
|
112
|
+
// fire exactly once and never again — which is the one case that makes
|
|
113
|
+
// infinite scroll actually work.
|
|
114
|
+
const itemCountChangedSinceLatch = options.itemCount !== options.previous.itemCountAtLatch;
|
|
115
|
+
const startWasLatched = options.previous.startLatched && !itemCountChangedSinceLatch;
|
|
116
|
+
const endWasLatched = options.previous.endLatched && !itemCountChangedSinceLatch;
|
|
117
|
+
|
|
118
|
+
const fireStart = options.proximity.isNearStart && !startWasLatched;
|
|
119
|
+
const fireEnd = options.proximity.isNearEnd && !endWasLatched;
|
|
120
|
+
|
|
121
|
+
return {
|
|
122
|
+
fireStart,
|
|
123
|
+
fireEnd,
|
|
124
|
+
next: {
|
|
125
|
+
startLatched: options.proximity.isNearStart,
|
|
126
|
+
endLatched: options.proximity.isNearEnd,
|
|
127
|
+
itemCountAtLatch: options.itemCount,
|
|
128
|
+
},
|
|
129
|
+
};
|
|
130
|
+
}
|
|
@@ -0,0 +1,136 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* A frame-scheduling port pair: `request` queues a callback for "the next
|
|
3
|
+
* frame" and returns an id `cancel` can later use to drop it before it
|
|
4
|
+
* fires. Shaped as data (not a class) so a test can hand `FrameBatcher` a
|
|
5
|
+
* fully deterministic fake instead of depending on real
|
|
6
|
+
* `requestAnimationFrame` timing.
|
|
7
|
+
*/
|
|
8
|
+
export type FrameScheduler = {
|
|
9
|
+
readonly request: (callback: (time: number) => void) => number;
|
|
10
|
+
readonly cancel: (id: number) => void;
|
|
11
|
+
};
|
|
12
|
+
|
|
13
|
+
/**
|
|
14
|
+
* Sentinel id returned by {@link rafFrameScheduler}'s `request` when no
|
|
15
|
+
* `requestAnimationFrame` exists in this environment (server rendering).
|
|
16
|
+
* `cancel` treats it as any other id — real `cancelAnimationFrame`
|
|
17
|
+
* implementations silently ignore an id they never issued, so no special
|
|
18
|
+
* case is needed there.
|
|
19
|
+
*/
|
|
20
|
+
const NO_ANIMATION_FRAME_ID = -1;
|
|
21
|
+
|
|
22
|
+
/**
|
|
23
|
+
* The real {@link FrameScheduler}, backed by `requestAnimationFrame` /
|
|
24
|
+
* `cancelAnimationFrame`.
|
|
25
|
+
*
|
|
26
|
+
* Both globals are looked up lazily, INSIDE `request`/`cancel`, never at
|
|
27
|
+
* module scope — referencing the bare identifier `requestAnimationFrame` at
|
|
28
|
+
* module scope throws a `ReferenceError` the instant this module is
|
|
29
|
+
* imported in a server-rendering environment, where no such global exists.
|
|
30
|
+
* CIN-205 requires the whole `virtual-list` module tree to import cleanly
|
|
31
|
+
* under SSR, so this module must not throw merely by being loaded, and
|
|
32
|
+
* `request`/`cancel` must not throw merely by being called there either —
|
|
33
|
+
* when `requestAnimationFrame` is absent, `request` reports
|
|
34
|
+
* {@link NO_ANIMATION_FRAME_ID} and never invokes the callback. Nothing on
|
|
35
|
+
* the server needs it to: Svelte does not run `$effect`s during SSR, so a
|
|
36
|
+
* `FrameBatcher` built on this scheduler never runs there either.
|
|
37
|
+
*
|
|
38
|
+
* Nothing in the component calls this today. It was written for the
|
|
39
|
+
* `windowScroll` adapter, which was split out of this work and is tracked as
|
|
40
|
+
* CIN-197; it stays here so that work does not start from nothing, but it
|
|
41
|
+
* describes a caller that does not exist yet rather than one that does.
|
|
42
|
+
*
|
|
43
|
+
* A `FrameBatcher` built on this fallback path stays permanently inert
|
|
44
|
+
* after its first `recordRead` — `request` returning without ever calling
|
|
45
|
+
* back means nothing clears the batcher's "a frame is already scheduled"
|
|
46
|
+
* flag, so later reads coalesce into a commit that never fires. This is the
|
|
47
|
+
* intended shape of "fall back safely": no throw, no leaked timer, at the
|
|
48
|
+
* cost of the batch simply never landing in an environment with no frames
|
|
49
|
+
* to schedule onto in the first place.
|
|
50
|
+
*/
|
|
51
|
+
export const rafFrameScheduler: FrameScheduler = {
|
|
52
|
+
request(callback) {
|
|
53
|
+
// Invoked through globalThis rather than copied into a local first: browsers
|
|
54
|
+
// that enforce the Web API receiver for Window methods throw "Illegal
|
|
55
|
+
// invocation" when one is called bare.
|
|
56
|
+
if (typeof globalThis.requestAnimationFrame === 'function') {
|
|
57
|
+
return globalThis.requestAnimationFrame(callback);
|
|
58
|
+
}
|
|
59
|
+
return NO_ANIMATION_FRAME_ID;
|
|
60
|
+
},
|
|
61
|
+
cancel(id) {
|
|
62
|
+
if (typeof globalThis.cancelAnimationFrame === 'function') {
|
|
63
|
+
globalThis.cancelAnimationFrame(id);
|
|
64
|
+
}
|
|
65
|
+
},
|
|
66
|
+
};
|
|
67
|
+
|
|
68
|
+
/** A `recordRead` call captured for the frame currently awaiting commit. */
|
|
69
|
+
type PendingRead<T> = {
|
|
70
|
+
readonly value: T;
|
|
71
|
+
};
|
|
72
|
+
|
|
73
|
+
/**
|
|
74
|
+
* Coalesces N calls to recordRead within one frame into a single onCommit call on the
|
|
75
|
+
* NEXT scheduled frame. This is CIN-202's mechanism for reads that Svelte's own
|
|
76
|
+
* $effect.pre/$effect ordering does NOT already cover — specifically, genuinely
|
|
77
|
+
* layout-forcing reads like getBoundingClientRect — which is what the `windowScroll`
|
|
78
|
+
* adapter will need, and why this exists ahead of it (CIN-197).
|
|
79
|
+
* Plain $state-driven scroll-offset correction uses the $effect.pre/$effect split
|
|
80
|
+
* instead (see "The engine" — CIN-202 interpretation).
|
|
81
|
+
*/
|
|
82
|
+
export class FrameBatcher<T> {
|
|
83
|
+
readonly #onCommit: (value: T) => void;
|
|
84
|
+
readonly #scheduler: FrameScheduler;
|
|
85
|
+
#pending: PendingRead<T> | null = null;
|
|
86
|
+
#frameId: number | null = null;
|
|
87
|
+
#disposed = false;
|
|
88
|
+
|
|
89
|
+
/**
|
|
90
|
+
* @param onCommit Called with the LAST value passed to `recordRead` since
|
|
91
|
+
* the previous commit, once per scheduled frame.
|
|
92
|
+
* @param scheduler Defaults to {@link rafFrameScheduler}. Tests inject a
|
|
93
|
+
* fake to make coalescing deterministic instead of depending on real
|
|
94
|
+
* frame timing.
|
|
95
|
+
*/
|
|
96
|
+
constructor(onCommit: (value: T) => void, scheduler: FrameScheduler = rafFrameScheduler) {
|
|
97
|
+
this.#onCommit = onCommit;
|
|
98
|
+
this.#scheduler = scheduler;
|
|
99
|
+
}
|
|
100
|
+
|
|
101
|
+
/**
|
|
102
|
+
* Records `value` as the pending read for the frame currently in flight,
|
|
103
|
+
* overwriting any value already recorded for that frame. Schedules a
|
|
104
|
+
* commit frame on the first call after a batch has committed (or after
|
|
105
|
+
* construction); every subsequent call before that frame fires just
|
|
106
|
+
* updates the pending value without scheduling a second frame. A no-op
|
|
107
|
+
* after {@link dispose}.
|
|
108
|
+
*/
|
|
109
|
+
recordRead(value: T): void {
|
|
110
|
+
if (this.#disposed) return;
|
|
111
|
+
this.#pending = { value };
|
|
112
|
+
if (this.#frameId !== null) return;
|
|
113
|
+
this.#frameId = this.#scheduler.request(() => {
|
|
114
|
+
this.#frameId = null;
|
|
115
|
+
const pending = this.#pending;
|
|
116
|
+
this.#pending = null;
|
|
117
|
+
if (this.#disposed || pending === null) return;
|
|
118
|
+
this.#onCommit(pending.value);
|
|
119
|
+
});
|
|
120
|
+
}
|
|
121
|
+
|
|
122
|
+
/**
|
|
123
|
+
* Cancels any frame currently scheduled — dropping its pending value
|
|
124
|
+
* without committing it — and makes every later `recordRead` inert.
|
|
125
|
+
* Idempotent.
|
|
126
|
+
*/
|
|
127
|
+
dispose(): void {
|
|
128
|
+
if (this.#disposed) return;
|
|
129
|
+
this.#disposed = true;
|
|
130
|
+
if (this.#frameId !== null) {
|
|
131
|
+
this.#scheduler.cancel(this.#frameId);
|
|
132
|
+
this.#frameId = null;
|
|
133
|
+
}
|
|
134
|
+
this.#pending = null;
|
|
135
|
+
}
|
|
136
|
+
}
|