@lostgradient/cinder 0.25.1 → 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.
Files changed (263) hide show
  1. package/CHANGELOG.md +227 -0
  2. package/components.json +13 -6
  3. package/dist/components/alert-dialog/index.js +2 -2
  4. package/dist/components/approval-card/index.js +2 -2
  5. package/dist/components/area-chart/index.js +2 -2
  6. package/dist/components/autocomplete/index.js +2 -2
  7. package/dist/components/avatar-group/index.js +2 -2
  8. package/dist/components/backdrop/index.js +2 -2
  9. package/dist/components/bar-chart/index.js +2 -2
  10. package/dist/components/button/button.css +1 -1
  11. package/dist/components/checkbox/index.js +2 -2
  12. package/dist/components/code-block/index.js +2 -2
  13. package/dist/components/color-field/index.js +2 -2
  14. package/dist/components/combobox/index.js +2 -2
  15. package/dist/components/command-menu/index.js +2 -2
  16. package/dist/components/command-palette/command-palette.css +50 -46
  17. package/dist/components/command-palette/index.js +2 -2
  18. package/dist/components/confirm-dialog/index.js +2 -2
  19. package/dist/components/context-menu/index.js +2 -2
  20. package/dist/components/data-table/index.js +2 -2
  21. package/dist/components/date-picker/index.js +2 -2
  22. package/dist/components/date-range-field/index.js +2 -2
  23. package/dist/components/drawer/index.js +2 -2
  24. package/dist/components/dropdown/index.js +2 -2
  25. package/dist/components/dropdown-menu/index.js +2 -2
  26. package/dist/components/find-bar/find-bar.css +9 -1
  27. package/dist/components/focus-trap/index.js +2 -2
  28. package/dist/components/form-field/index.js +2 -2
  29. package/dist/components/hover-card/index.js +2 -2
  30. package/dist/components/inline-confirm/index.js +2 -2
  31. package/dist/components/input/index.js +2 -2
  32. package/dist/components/input/input.css +95 -6
  33. package/dist/components/invocation-rule-builder/index.js +2 -2
  34. package/dist/components/json-editor/index.js +2 -2
  35. package/dist/components/json-schema-editor/index.js +4 -4
  36. package/dist/components/key-value-editor/index.css +1 -1
  37. package/dist/components/line-chart/index.js +2 -2
  38. package/dist/components/matrix-chart/index.js +2 -2
  39. package/dist/components/menu-bar/index.js +3 -3
  40. package/dist/components/modal/index.js +2 -2
  41. package/dist/components/modal-region/index.css +1 -1
  42. package/dist/components/multi-select/index.js +2 -2
  43. package/dist/components/navigation-bar/index.js +2 -2
  44. package/dist/components/parameter-field/index.js +2 -2
  45. package/dist/components/permission-matrix/index.js +2 -2
  46. package/dist/components/policy-lock/index.js +2 -2
  47. package/dist/components/popover/index.js +2 -2
  48. package/dist/components/radio-group/index.js +2 -2
  49. package/dist/components/schedule-builder/index.js +2 -2
  50. package/dist/components/schema-form/index.js +2 -2
  51. package/dist/components/scroll-area/index.js +2 -2
  52. package/dist/components/select/index.js +2 -2
  53. package/dist/components/selection-popover/index.js +2 -2
  54. package/dist/components/share-card/index.js +2 -2
  55. package/dist/components/sidebar/index.js +2 -2
  56. package/dist/components/speed-dial/index.js +2 -2
  57. package/dist/components/statistic-group/index.js +2 -2
  58. package/dist/components/statistic-group/statistic-group.css +116 -66
  59. package/dist/components/table/index.js +2 -2
  60. package/dist/components/textarea/index.js +2 -2
  61. package/dist/components/time-field/index.js +2 -2
  62. package/dist/components/time-field/time-field.css +9 -8
  63. package/dist/components/toast-region/index.js +2 -2
  64. package/dist/components/tooltip/index.js +2 -2
  65. package/dist/components/transfer-list/index.js +2 -2
  66. package/dist/components/virtual-list/_internal/adaptive-overscan.d.ts +87 -0
  67. package/dist/components/virtual-list/_internal/edge-proximity.d.ts +75 -0
  68. package/dist/components/virtual-list/_internal/frame-scheduler.d.ts +76 -0
  69. package/dist/components/virtual-list/_internal/geometry.d.ts +170 -0
  70. package/dist/components/virtual-list/_internal/list-semantics.d.ts +93 -0
  71. package/dist/components/virtual-list/_internal/measurement-window.d.ts +125 -0
  72. package/dist/components/virtual-list/_internal/reverse-order.d.ts +87 -0
  73. package/dist/components/virtual-list/_internal/scroll-restoration.d.ts +98 -0
  74. package/dist/components/virtual-list/_internal/sticky-items.d.ts +48 -0
  75. package/dist/components/virtual-list/_internal/virtual-list-measurement-store.svelte.d.ts +69 -0
  76. package/dist/components/virtual-list/index.d.ts +1 -1
  77. package/dist/components/virtual-list/index.js +2 -2
  78. package/dist/components/virtual-list/virtual-list.css +153 -0
  79. package/dist/components/virtual-list/virtual-list.schema.js +69 -6
  80. package/dist/components/virtual-list/virtual-list.svelte.d.ts +11 -8
  81. package/dist/components/virtual-list/virtual-list.types.d.ts +177 -4
  82. package/dist/index.browser.css +1 -1
  83. package/dist/index.d.ts +1 -1
  84. package/dist/index.js +18 -18
  85. package/dist/server/components/alert-dialog/index.js +1 -1
  86. package/dist/server/components/approval-card/index.js +1 -1
  87. package/dist/server/components/area-chart/index.js +1 -1
  88. package/dist/server/components/autocomplete/index.js +1 -1
  89. package/dist/server/components/avatar-group/index.js +1 -1
  90. package/dist/server/components/backdrop/index.js +1 -1
  91. package/dist/server/components/bar-chart/index.js +1 -1
  92. package/dist/server/components/checkbox/index.js +1 -1
  93. package/dist/server/components/code-block/index.js +1 -1
  94. package/dist/server/components/color-field/index.js +1 -1
  95. package/dist/server/components/combobox/index.js +1 -1
  96. package/dist/server/components/command-menu/index.js +1 -1
  97. package/dist/server/components/command-palette/index.js +2 -2
  98. package/dist/server/components/confirm-dialog/index.js +1 -1
  99. package/dist/server/components/context-menu/index.js +1 -1
  100. package/dist/server/components/data-table/index.js +1 -1
  101. package/dist/server/components/date-picker/index.js +1 -1
  102. package/dist/server/components/date-range-field/index.js +1 -1
  103. package/dist/server/components/drawer/index.js +1 -1
  104. package/dist/server/components/dropdown/index.js +1 -1
  105. package/dist/server/components/dropdown-menu/index.js +2 -2
  106. package/dist/server/components/focus-trap/index.js +1 -1
  107. package/dist/server/components/form-field/index.js +1 -1
  108. package/dist/server/components/hover-card/index.js +1 -1
  109. package/dist/server/components/inline-confirm/index.js +1 -1
  110. package/dist/server/components/input/index.js +1 -1
  111. package/dist/server/components/invocation-rule-builder/index.js +1 -1
  112. package/dist/server/components/json-editor/index.js +1 -1
  113. package/dist/server/components/json-schema-editor/index.js +1 -1
  114. package/dist/server/components/line-chart/index.js +1 -1
  115. package/dist/server/components/matrix-chart/index.js +1 -1
  116. package/dist/server/components/menu-bar/index.js +2 -2
  117. package/dist/server/components/modal/index.js +1 -1
  118. package/dist/server/components/multi-select/index.js +1 -1
  119. package/dist/server/components/navigation-bar/index.js +2 -2
  120. package/dist/server/components/parameter-field/index.js +1 -1
  121. package/dist/server/components/permission-matrix/index.js +1 -1
  122. package/dist/server/components/policy-lock/index.js +1 -1
  123. package/dist/server/components/popover/index.js +1 -1
  124. package/dist/server/components/radio-group/index.js +1 -1
  125. package/dist/server/components/schedule-builder/index.js +1 -1
  126. package/dist/server/components/schema-form/index.js +1 -1
  127. package/dist/server/components/scroll-area/index.js +1 -1
  128. package/dist/server/components/select/index.js +1 -1
  129. package/dist/server/components/selection-popover/index.js +1 -1
  130. package/dist/server/components/share-card/index.js +1 -1
  131. package/dist/server/components/sidebar/index.js +1 -1
  132. package/dist/server/components/speed-dial/index.js +2 -2
  133. package/dist/server/components/statistic-group/index.js +1 -1
  134. package/dist/server/components/table/index.js +1 -1
  135. package/dist/server/components/textarea/index.js +1 -1
  136. package/dist/server/components/time-field/index.js +1 -1
  137. package/dist/server/components/toast-region/index.js +1 -1
  138. package/dist/server/components/tooltip/index.js +1 -1
  139. package/dist/server/components/transfer-list/index.js +1 -1
  140. package/dist/server/components/virtual-list/index.js +2 -2
  141. package/dist/server/index.js +2 -2
  142. package/dist/server/{index.server-skq0f5sr.js → index.server-0jw25w9w.js} +1 -1
  143. package/dist/server/index.server-0kk20wvp.js +4 -0
  144. package/dist/server/{index.server-fzsqdajc.js → index.server-2awq6q9m.js} +1 -1
  145. package/dist/server/{index.server-e4hmhaeh.js → index.server-3xwvw6w2.js} +3 -3
  146. package/dist/server/{index.server-95h7xy01.js → index.server-428dh2t9.js} +2 -2
  147. package/dist/server/{index.server-jd88r74m.js → index.server-5dq66aja.js} +2 -2
  148. package/dist/server/{index.server-dvwfhf77.js → index.server-5s94r0kk.js} +2 -2
  149. package/dist/server/{index.server-qv6z5ta3.js → index.server-80qgcjnm.js} +1 -1
  150. package/dist/server/{index.server-7k2732ky.js → index.server-81abtrsw.js} +1 -1
  151. package/dist/server/{index.server-csmqnx5w.js → index.server-83q1gv2c.js} +1 -1
  152. package/dist/server/{index.server-qw8k9rjg.js → index.server-8fyav10d.js} +1 -1
  153. package/dist/server/{index.server-4dgjj4k1.js → index.server-8h5caecr.js} +2 -2
  154. package/dist/server/{index.server-emyqytmm.js → index.server-90n8sd9e.js} +1 -1
  155. package/dist/server/{index.server-0xrdyzvh.js → index.server-99penx1m.js} +1 -1
  156. package/dist/server/{index.server-p94j3jah.js → index.server-9g9d15z1.js} +1 -1
  157. package/dist/server/{index.server-xp9hkc81.js → index.server-9kbdx511.js} +1 -1
  158. package/dist/server/index.server-a2yhk45s.js +3 -0
  159. package/dist/server/{index.server-g8d2m2tk.js → index.server-acq55gjs.js} +1 -1
  160. package/dist/server/{index.server-ewze54tv.js → index.server-afjftjmr.js} +1 -1
  161. package/dist/server/{index.server-ejyye4gv.js → index.server-bfed6a8a.js} +1 -1
  162. package/dist/server/{index.server-z5ng08q2.js → index.server-c1746s0z.js} +1 -1
  163. package/dist/server/{index.server-gt1tfc1w.js → index.server-dmeztywe.js} +1 -1
  164. package/dist/server/{index.server-kzsppq0n.js → index.server-dyj3jdx9.js} +1 -1
  165. package/dist/server/index.server-dz92zvx6.js +4 -0
  166. package/dist/server/{index.server-3md8kdcr.js → index.server-e6682k08.js} +1 -1
  167. package/dist/server/{index.server-t1pshh65.js → index.server-ewkv461x.js} +1 -1
  168. package/dist/server/{index.server-zfgwhtmp.js → index.server-fa449wd3.js} +1 -1
  169. package/dist/server/{index.server-1kgwayct.js → index.server-fhfypmgw.js} +1 -1
  170. package/dist/server/{index.server-s4z8hsby.js → index.server-ge4adxs2.js} +1 -1
  171. package/dist/server/{index.server-68xyfsg3.js → index.server-gggkq22y.js} +2 -2
  172. package/dist/server/{index.server-acgwdamx.js → index.server-j52rbk57.js} +1 -1
  173. package/dist/server/{index.server-z0nwftx6.js → index.server-jm89hxfb.js} +1 -1
  174. package/dist/server/{index.server-xa98r8p2.js → index.server-jw0v64se.js} +1 -1
  175. package/dist/server/index.server-m321p69g.js +3 -0
  176. package/dist/server/{index.server-xyervw3d.js → index.server-m7q2tc41.js} +1 -1
  177. package/dist/server/{index.server-tnrxy86j.js → index.server-mak7dmj2.js} +1 -1
  178. package/dist/server/{index.server-n5g5h5k1.js → index.server-mw5r2524.js} +1 -1
  179. package/dist/server/{index.server-caf7s6m7.js → index.server-nwq1cg55.js} +1 -1
  180. package/dist/server/{index.server-3wdvs0wr.js → index.server-p423fy4q.js} +2 -2
  181. package/dist/server/{index.server-ks7fvwxt.js → index.server-prk5syj2.js} +1 -1
  182. package/dist/server/{index.server-6w9fp018.js → index.server-q4hytsq3.js} +1 -1
  183. package/dist/server/{index.server-5w2qw8fm.js → index.server-q597a1ck.js} +1 -1
  184. package/dist/server/{index.server-fz1pkvda.js → index.server-qgne9v2w.js} +1 -1
  185. package/dist/server/{index.server-1f2app32.js → index.server-rvdavf92.js} +1 -1
  186. package/dist/server/index.server-rwq20a22.js +3 -0
  187. package/dist/server/{index.server-0rvmnrw2.js → index.server-s9tjs45r.js} +1 -1
  188. package/dist/server/{index.server-cm2prec7.js → index.server-sqgxyfsw.js} +1 -1
  189. package/dist/server/{index.server-v6777tgn.js → index.server-t761nwvb.js} +1 -1
  190. package/dist/server/index.server-tbds8nwq.js +4 -0
  191. package/dist/server/index.server-tyhta5n3.js +3 -0
  192. package/dist/server/{index.server-yw7rah51.js → index.server-v5dxham4.js} +1 -1
  193. package/dist/server/index.server-va98cpyf.js +3 -0
  194. package/dist/server/index.server-vq1k69xt.js +3 -0
  195. package/dist/server/{index.server-egd355s6.js → index.server-wnf9btp7.js} +2 -2
  196. package/dist/server/{index.server-sjcbaztf.js → index.server-y3zgdtbv.js} +1 -1
  197. package/dist/server/{index.server-4tjtgzf9.js → index.server-y6vtbmyj.js} +1 -1
  198. package/dist/server/{index.server-2p2mjzzb.js → index.server-zff2qp1v.js} +1 -1
  199. package/dist/server/tokens/registry.generated.js +2 -2
  200. package/dist/tokens/registry.generated.js +2 -2
  201. package/package.json +2 -2
  202. package/src/_internal/form-field-frame.svelte +5 -0
  203. package/src/_internal/overlay.ts +14 -1
  204. package/src/components/_internal/create-command-list-state.svelte.ts +4 -0
  205. package/src/components/button/button.css +1 -1
  206. package/src/components/command-menu/command-menu.svelte +63 -7
  207. package/src/components/command-palette/command-palette.css +50 -46
  208. package/src/components/command-palette/command-palette.svelte +68 -78
  209. package/src/components/dropdown/dropdown.svelte +73 -18
  210. package/src/components/dropdown-menu/dropdown-menu.svelte +63 -7
  211. package/src/components/find-bar/find-bar.css +9 -1
  212. package/src/components/input/input.css +95 -6
  213. package/src/components/input/input.svelte +44 -81
  214. package/src/components/menu-bar/menu-bar.svelte +12 -1
  215. package/src/components/multi-select/multi-select.svelte +7 -0
  216. package/src/components/navigation-bar/navigation-bar.svelte +82 -6
  217. package/src/components/selection-popover/selection-popover.svelte +24 -10
  218. package/src/components/share-card/share-card.svelte +24 -44
  219. package/src/components/speed-dial/speed-dial.svelte +23 -5
  220. package/src/components/statistic-group/statistic-group.css +116 -66
  221. package/src/components/statistic-group/statistic-group.examples.json +6 -0
  222. package/src/components/statistic-group/statistic-group.svelte +13 -1
  223. package/src/components/time-field/time-field.css +9 -8
  224. package/src/components/toast-region/toast-region.svelte +9 -0
  225. package/src/components/virtual-list/_internal/adaptive-overscan.ts +248 -0
  226. package/src/components/virtual-list/_internal/edge-proximity.ts +130 -0
  227. package/src/components/virtual-list/_internal/frame-scheduler.ts +136 -0
  228. package/src/components/virtual-list/_internal/geometry.ts +236 -0
  229. package/src/components/virtual-list/_internal/list-semantics.ts +151 -0
  230. package/src/components/virtual-list/_internal/measurement-window.ts +300 -0
  231. package/src/components/virtual-list/_internal/reverse-order.ts +146 -0
  232. package/src/components/virtual-list/_internal/scroll-restoration.ts +209 -0
  233. package/src/components/virtual-list/_internal/sticky-items.ts +111 -0
  234. package/src/components/virtual-list/_internal/virtual-list-measurement-store.svelte.ts +145 -0
  235. package/src/components/virtual-list/index.ts +7 -1
  236. package/src/components/virtual-list/virtual-list.css +153 -0
  237. package/src/components/virtual-list/virtual-list.examples.json +42 -0
  238. package/src/components/virtual-list/virtual-list.schema.json +53 -3
  239. package/src/components/virtual-list/virtual-list.schema.ts +64 -3
  240. package/src/components/virtual-list/virtual-list.svelte +1527 -36
  241. package/src/components/virtual-list/virtual-list.types.ts +181 -4
  242. package/src/index.ts +3 -0
  243. package/src/styles/tokens-base.css +29 -21
  244. package/src/tokens/cinder.resolver.json +8 -0
  245. package/src/tokens/index.json +1 -1
  246. package/src/tokens/registry.generated.json +29 -3
  247. package/src/tokens/registry.generated.ts +31 -3
  248. package/src/tokens/resolved/dark-reduced-motion.json +46 -16
  249. package/src/tokens/resolved/dark.json +46 -16
  250. package/src/tokens/resolved/light-reduced-motion.json +47 -17
  251. package/src/tokens/resolved/light.json +47 -17
  252. package/src/tokens/sets/semantic.tokens.json +120 -30
  253. package/src/tokens/themes/dark.tokens.json +115 -19
  254. package/src/tokens/themes/light.tokens.json +51 -3
  255. package/dist/server/index.server-191cnacw.js +0 -3
  256. package/dist/server/index.server-25dqx151.js +0 -3
  257. package/dist/server/index.server-77jyqvbv.js +0 -4
  258. package/dist/server/index.server-bgjrzr70.js +0 -3
  259. package/dist/server/index.server-khsp90vh.js +0 -3
  260. package/dist/server/index.server-ryk2pgbe.js +0 -4
  261. package/dist/server/index.server-tajr81bm.js +0 -3
  262. package/dist/server/index.server-vjzcrw3d.js +0 -4
  263. 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
+ }