@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.
Files changed (309) hide show
  1. package/CHANGELOG.md +233 -0
  2. package/components.json +13 -6
  3. package/dist/components/accordion-item/accordion-item.css +0 -10
  4. package/dist/components/action-row/action-row.css +0 -9
  5. package/dist/components/alert/alert.css +0 -1
  6. package/dist/components/alert-dialog/index.js +2 -2
  7. package/dist/components/approval-card/index.js +2 -2
  8. package/dist/components/area-chart/index.js +2 -2
  9. package/dist/components/autocomplete/index.js +2 -2
  10. package/dist/components/avatar-group/avatar-group.css +0 -2
  11. package/dist/components/avatar-group/index.js +2 -2
  12. package/dist/components/backdrop/index.js +2 -2
  13. package/dist/components/bar-chart/index.js +2 -2
  14. package/dist/components/button/button.css +4 -4
  15. package/dist/components/button/button.variables.js +2 -2
  16. package/dist/components/card/card.css +0 -2
  17. package/dist/components/carousel/carousel.css +0 -5
  18. package/dist/components/checkbox/index.js +2 -2
  19. package/dist/components/code-block/code-block.css +0 -5
  20. package/dist/components/code-block/index.js +2 -2
  21. package/dist/components/color-field/index.js +2 -2
  22. package/dist/components/combobox/index.js +2 -2
  23. package/dist/components/command-menu/index.js +2 -2
  24. package/dist/components/command-palette/command-palette.css +50 -46
  25. package/dist/components/command-palette/index.js +2 -2
  26. package/dist/components/confirm-dialog/index.js +2 -2
  27. package/dist/components/context-menu/index.js +2 -2
  28. package/dist/components/data-table/data-table.css +0 -2
  29. package/dist/components/data-table/index.js +2 -2
  30. package/dist/components/date-picker/index.js +2 -2
  31. package/dist/components/date-range-field/index.js +2 -2
  32. package/dist/components/drawer/index.js +2 -2
  33. package/dist/components/dropdown/index.js +2 -2
  34. package/dist/components/dropdown-menu/index.js +2 -2
  35. package/dist/components/feed-event/feed-event.css +0 -2
  36. package/dist/components/file-upload/file-upload.css +0 -5
  37. package/dist/components/find-bar/find-bar.css +9 -1
  38. package/dist/components/focus-trap/index.js +2 -2
  39. package/dist/components/form-field/index.js +2 -2
  40. package/dist/components/guidance-region/index.css +1 -1
  41. package/dist/components/hover-card/index.js +2 -2
  42. package/dist/components/inline-confirm/index.js +2 -2
  43. package/dist/components/input/index.js +2 -2
  44. package/dist/components/input/input.css +95 -6
  45. package/dist/components/invocation-rule-builder/index.js +2 -2
  46. package/dist/components/json-editor/index.js +2 -2
  47. package/dist/components/json-schema-editor/index.js +4 -4
  48. package/dist/components/kanban-board/kanban-board.css +0 -10
  49. package/dist/components/key-value-editor/index.css +1 -1
  50. package/dist/components/line-chart/index.js +2 -2
  51. package/dist/components/marquee/marquee.css +0 -2
  52. package/dist/components/matrix-chart/index.js +2 -2
  53. package/dist/components/menu-bar/index.js +3 -3
  54. package/dist/components/modal/index.js +2 -2
  55. package/dist/components/modal/modal.css +0 -26
  56. package/dist/components/modal-region/index.css +1 -1
  57. package/dist/components/multi-select/index.js +2 -2
  58. package/dist/components/navigation-bar/index.js +2 -2
  59. package/dist/components/parameter-field/index.js +2 -2
  60. package/dist/components/permission-matrix/index.js +2 -2
  61. package/dist/components/policy-lock/index.js +2 -2
  62. package/dist/components/popover/index.js +2 -2
  63. package/dist/components/radio-group/index.js +2 -2
  64. package/dist/components/schedule-builder/index.js +2 -2
  65. package/dist/components/schema-form/index.js +2 -2
  66. package/dist/components/scroll-area/index.js +2 -2
  67. package/dist/components/select/index.js +2 -2
  68. package/dist/components/selectable-row/selectable-row.css +0 -6
  69. package/dist/components/selection-popover/index.js +2 -2
  70. package/dist/components/share-card/index.js +2 -2
  71. package/dist/components/side-navigation/side-navigation.css +0 -1
  72. package/dist/components/sidebar/index.js +2 -2
  73. package/dist/components/speed-dial/index.js +2 -2
  74. package/dist/components/statistic/statistic.css +0 -8
  75. package/dist/components/statistic-group/index.js +2 -2
  76. package/dist/components/statistic-group/statistic-group.css +116 -69
  77. package/dist/components/status-dot/status-dot.css +0 -3
  78. package/dist/components/table/index.js +2 -2
  79. package/dist/components/table-of-contents/table-of-contents.css +0 -4
  80. package/dist/components/textarea/index.js +2 -2
  81. package/dist/components/time-field/index.js +2 -2
  82. package/dist/components/time-field/time-field.css +9 -8
  83. package/dist/components/toast-region/index.js +2 -2
  84. package/dist/components/toggle/toggle.variables.js +2 -2
  85. package/dist/components/tooltip/index.js +2 -2
  86. package/dist/components/transfer-list/index.js +2 -2
  87. package/dist/components/tree/tree.css +0 -3
  88. package/dist/components/virtual-list/_internal/adaptive-overscan.d.ts +87 -0
  89. package/dist/components/virtual-list/_internal/edge-proximity.d.ts +75 -0
  90. package/dist/components/virtual-list/_internal/frame-scheduler.d.ts +76 -0
  91. package/dist/components/virtual-list/_internal/geometry.d.ts +170 -0
  92. package/dist/components/virtual-list/_internal/list-semantics.d.ts +93 -0
  93. package/dist/components/virtual-list/_internal/measurement-window.d.ts +125 -0
  94. package/dist/components/virtual-list/_internal/reverse-order.d.ts +87 -0
  95. package/dist/components/virtual-list/_internal/scroll-restoration.d.ts +98 -0
  96. package/dist/components/virtual-list/_internal/sticky-items.d.ts +48 -0
  97. package/dist/components/virtual-list/_internal/virtual-list-measurement-store.svelte.d.ts +69 -0
  98. package/dist/components/virtual-list/index.d.ts +1 -1
  99. package/dist/components/virtual-list/index.js +2 -2
  100. package/dist/components/virtual-list/virtual-list.css +153 -2
  101. package/dist/components/virtual-list/virtual-list.schema.js +69 -6
  102. package/dist/components/virtual-list/virtual-list.svelte.d.ts +11 -8
  103. package/dist/components/virtual-list/virtual-list.types.d.ts +177 -4
  104. package/dist/index.browser.css +1 -1
  105. package/dist/index.d.ts +1 -1
  106. package/dist/index.js +18 -18
  107. package/dist/server/components/alert-dialog/index.js +1 -1
  108. package/dist/server/components/approval-card/index.js +1 -1
  109. package/dist/server/components/area-chart/index.js +1 -1
  110. package/dist/server/components/autocomplete/index.js +1 -1
  111. package/dist/server/components/avatar-group/index.js +1 -1
  112. package/dist/server/components/backdrop/index.js +1 -1
  113. package/dist/server/components/bar-chart/index.js +1 -1
  114. package/dist/server/components/checkbox/index.js +1 -1
  115. package/dist/server/components/code-block/index.js +1 -1
  116. package/dist/server/components/color-field/index.js +1 -1
  117. package/dist/server/components/combobox/index.js +1 -1
  118. package/dist/server/components/command-menu/index.js +1 -1
  119. package/dist/server/components/command-palette/index.js +2 -2
  120. package/dist/server/components/confirm-dialog/index.js +1 -1
  121. package/dist/server/components/context-menu/index.js +1 -1
  122. package/dist/server/components/data-table/index.js +1 -1
  123. package/dist/server/components/date-picker/index.js +1 -1
  124. package/dist/server/components/date-range-field/index.js +1 -1
  125. package/dist/server/components/drawer/index.js +1 -1
  126. package/dist/server/components/dropdown/index.js +1 -1
  127. package/dist/server/components/dropdown-menu/index.js +2 -2
  128. package/dist/server/components/focus-trap/index.js +1 -1
  129. package/dist/server/components/form-field/index.js +1 -1
  130. package/dist/server/components/hover-card/index.js +1 -1
  131. package/dist/server/components/inline-confirm/index.js +1 -1
  132. package/dist/server/components/input/index.js +1 -1
  133. package/dist/server/components/invocation-rule-builder/index.js +1 -1
  134. package/dist/server/components/json-editor/index.js +1 -1
  135. package/dist/server/components/json-schema-editor/index.js +1 -1
  136. package/dist/server/components/line-chart/index.js +1 -1
  137. package/dist/server/components/matrix-chart/index.js +1 -1
  138. package/dist/server/components/menu-bar/index.js +2 -2
  139. package/dist/server/components/modal/index.js +1 -1
  140. package/dist/server/components/multi-select/index.js +1 -1
  141. package/dist/server/components/navigation-bar/index.js +2 -2
  142. package/dist/server/components/parameter-field/index.js +1 -1
  143. package/dist/server/components/permission-matrix/index.js +1 -1
  144. package/dist/server/components/policy-lock/index.js +1 -1
  145. package/dist/server/components/popover/index.js +1 -1
  146. package/dist/server/components/radio-group/index.js +1 -1
  147. package/dist/server/components/schedule-builder/index.js +1 -1
  148. package/dist/server/components/schema-form/index.js +1 -1
  149. package/dist/server/components/scroll-area/index.js +1 -1
  150. package/dist/server/components/select/index.js +1 -1
  151. package/dist/server/components/selection-popover/index.js +1 -1
  152. package/dist/server/components/share-card/index.js +1 -1
  153. package/dist/server/components/sidebar/index.js +1 -1
  154. package/dist/server/components/speed-dial/index.js +2 -2
  155. package/dist/server/components/statistic-group/index.js +1 -1
  156. package/dist/server/components/table/index.js +1 -1
  157. package/dist/server/components/textarea/index.js +1 -1
  158. package/dist/server/components/time-field/index.js +1 -1
  159. package/dist/server/components/toast-region/index.js +1 -1
  160. package/dist/server/components/tooltip/index.js +1 -1
  161. package/dist/server/components/transfer-list/index.js +1 -1
  162. package/dist/server/components/virtual-list/index.js +2 -2
  163. package/dist/server/index.js +2 -2
  164. package/dist/server/{index.server-skq0f5sr.js → index.server-0jw25w9w.js} +1 -1
  165. package/dist/server/index.server-0kk20wvp.js +4 -0
  166. package/dist/server/{index.server-fzsqdajc.js → index.server-2awq6q9m.js} +1 -1
  167. package/dist/server/{index.server-e4hmhaeh.js → index.server-3xwvw6w2.js} +3 -3
  168. package/dist/server/{index.server-95h7xy01.js → index.server-428dh2t9.js} +2 -2
  169. package/dist/server/{index.server-jd88r74m.js → index.server-5dq66aja.js} +2 -2
  170. package/dist/server/{index.server-dvwfhf77.js → index.server-5s94r0kk.js} +2 -2
  171. package/dist/server/{index.server-qv6z5ta3.js → index.server-80qgcjnm.js} +1 -1
  172. package/dist/server/{index.server-7k2732ky.js → index.server-81abtrsw.js} +1 -1
  173. package/dist/server/{index.server-csmqnx5w.js → index.server-83q1gv2c.js} +1 -1
  174. package/dist/server/{index.server-qw8k9rjg.js → index.server-8fyav10d.js} +1 -1
  175. package/dist/server/{index.server-4dgjj4k1.js → index.server-8h5caecr.js} +2 -2
  176. package/dist/server/{index.server-emyqytmm.js → index.server-90n8sd9e.js} +1 -1
  177. package/dist/server/{index.server-0xrdyzvh.js → index.server-99penx1m.js} +1 -1
  178. package/dist/server/{index.server-p94j3jah.js → index.server-9g9d15z1.js} +1 -1
  179. package/dist/server/{index.server-xp9hkc81.js → index.server-9kbdx511.js} +1 -1
  180. package/dist/server/index.server-a2yhk45s.js +3 -0
  181. package/dist/server/{index.server-g8d2m2tk.js → index.server-acq55gjs.js} +1 -1
  182. package/dist/server/{index.server-ewze54tv.js → index.server-afjftjmr.js} +1 -1
  183. package/dist/server/{index.server-ejyye4gv.js → index.server-bfed6a8a.js} +1 -1
  184. package/dist/server/{index.server-z5ng08q2.js → index.server-c1746s0z.js} +1 -1
  185. package/dist/server/{index.server-gt1tfc1w.js → index.server-dmeztywe.js} +1 -1
  186. package/dist/server/{index.server-kzsppq0n.js → index.server-dyj3jdx9.js} +1 -1
  187. package/dist/server/index.server-dz92zvx6.js +4 -0
  188. package/dist/server/{index.server-3md8kdcr.js → index.server-e6682k08.js} +1 -1
  189. package/dist/server/{index.server-t1pshh65.js → index.server-ewkv461x.js} +1 -1
  190. package/dist/server/{index.server-zfgwhtmp.js → index.server-fa449wd3.js} +1 -1
  191. package/dist/server/{index.server-1kgwayct.js → index.server-fhfypmgw.js} +1 -1
  192. package/dist/server/{index.server-s4z8hsby.js → index.server-ge4adxs2.js} +1 -1
  193. package/dist/server/{index.server-68xyfsg3.js → index.server-gggkq22y.js} +2 -2
  194. package/dist/server/{index.server-acgwdamx.js → index.server-j52rbk57.js} +1 -1
  195. package/dist/server/{index.server-z0nwftx6.js → index.server-jm89hxfb.js} +1 -1
  196. package/dist/server/{index.server-xa98r8p2.js → index.server-jw0v64se.js} +1 -1
  197. package/dist/server/index.server-m321p69g.js +3 -0
  198. package/dist/server/{index.server-xyervw3d.js → index.server-m7q2tc41.js} +1 -1
  199. package/dist/server/{index.server-tnrxy86j.js → index.server-mak7dmj2.js} +1 -1
  200. package/dist/server/{index.server-n5g5h5k1.js → index.server-mw5r2524.js} +1 -1
  201. package/dist/server/{index.server-caf7s6m7.js → index.server-nwq1cg55.js} +1 -1
  202. package/dist/server/{index.server-3wdvs0wr.js → index.server-p423fy4q.js} +2 -2
  203. package/dist/server/{index.server-ks7fvwxt.js → index.server-prk5syj2.js} +1 -1
  204. package/dist/server/{index.server-6w9fp018.js → index.server-q4hytsq3.js} +1 -1
  205. package/dist/server/{index.server-5w2qw8fm.js → index.server-q597a1ck.js} +1 -1
  206. package/dist/server/{index.server-fz1pkvda.js → index.server-qgne9v2w.js} +1 -1
  207. package/dist/server/{index.server-1f2app32.js → index.server-rvdavf92.js} +1 -1
  208. package/dist/server/index.server-rwq20a22.js +3 -0
  209. package/dist/server/{index.server-0rvmnrw2.js → index.server-s9tjs45r.js} +1 -1
  210. package/dist/server/{index.server-cm2prec7.js → index.server-sqgxyfsw.js} +1 -1
  211. package/dist/server/{index.server-v6777tgn.js → index.server-t761nwvb.js} +1 -1
  212. package/dist/server/index.server-tbds8nwq.js +4 -0
  213. package/dist/server/index.server-tyhta5n3.js +3 -0
  214. package/dist/server/{index.server-yw7rah51.js → index.server-v5dxham4.js} +1 -1
  215. package/dist/server/index.server-va98cpyf.js +3 -0
  216. package/dist/server/index.server-vq1k69xt.js +3 -0
  217. package/dist/server/{index.server-egd355s6.js → index.server-wnf9btp7.js} +2 -2
  218. package/dist/server/{index.server-sjcbaztf.js → index.server-y3zgdtbv.js} +1 -1
  219. package/dist/server/{index.server-4tjtgzf9.js → index.server-y6vtbmyj.js} +1 -1
  220. package/dist/server/{index.server-2p2mjzzb.js → index.server-zff2qp1v.js} +1 -1
  221. package/dist/server/tokens/registry.generated.js +2 -2
  222. package/dist/tokens/registry.generated.js +2 -2
  223. package/package.json +2 -2
  224. package/src/_internal/form-field-frame.svelte +5 -0
  225. package/src/_internal/overlay.ts +14 -1
  226. package/src/components/_internal/create-command-list-state.svelte.ts +4 -0
  227. package/src/components/accordion-item/accordion-item.css +0 -10
  228. package/src/components/action-row/action-row.css +0 -9
  229. package/src/components/alert/alert.css +0 -1
  230. package/src/components/avatar-group/avatar-group.css +0 -2
  231. package/src/components/button/button.css +4 -4
  232. package/src/components/button/button.variables.json +31 -1
  233. package/src/components/button/button.variables.ts +31 -1
  234. package/src/components/card/card.css +0 -2
  235. package/src/components/carousel/carousel.css +0 -5
  236. package/src/components/code-block/code-block.css +0 -5
  237. package/src/components/command-menu/command-menu.svelte +63 -7
  238. package/src/components/command-palette/command-palette.css +50 -46
  239. package/src/components/command-palette/command-palette.svelte +68 -78
  240. package/src/components/data-table/data-table.css +0 -2
  241. package/src/components/dropdown/dropdown.svelte +73 -18
  242. package/src/components/dropdown-menu/dropdown-menu.svelte +63 -7
  243. package/src/components/feed-event/feed-event.css +0 -2
  244. package/src/components/file-upload/file-upload.css +0 -5
  245. package/src/components/find-bar/find-bar.css +9 -1
  246. package/src/components/input/input.css +95 -6
  247. package/src/components/input/input.svelte +44 -81
  248. package/src/components/kanban-board/kanban-board.css +0 -10
  249. package/src/components/marquee/marquee.css +0 -2
  250. package/src/components/menu-bar/menu-bar.svelte +12 -1
  251. package/src/components/modal/modal.css +0 -26
  252. package/src/components/multi-select/multi-select.svelte +7 -0
  253. package/src/components/navigation-bar/navigation-bar.svelte +82 -6
  254. package/src/components/selectable-row/selectable-row.css +0 -6
  255. package/src/components/selection-popover/selection-popover.svelte +24 -10
  256. package/src/components/share-card/share-card.svelte +24 -44
  257. package/src/components/side-navigation/side-navigation.css +0 -1
  258. package/src/components/speed-dial/speed-dial.svelte +23 -5
  259. package/src/components/statistic/statistic.css +0 -8
  260. package/src/components/statistic-group/statistic-group.css +116 -69
  261. package/src/components/statistic-group/statistic-group.examples.json +6 -0
  262. package/src/components/statistic-group/statistic-group.svelte +13 -1
  263. package/src/components/status-dot/status-dot.css +0 -3
  264. package/src/components/table-of-contents/table-of-contents.css +0 -4
  265. package/src/components/time-field/time-field.css +9 -8
  266. package/src/components/toast-region/toast-region.svelte +9 -0
  267. package/src/components/toggle/toggle.variables.json +1 -1
  268. package/src/components/toggle/toggle.variables.ts +4 -1
  269. package/src/components/tree/tree.css +0 -3
  270. package/src/components/virtual-list/_internal/adaptive-overscan.ts +248 -0
  271. package/src/components/virtual-list/_internal/edge-proximity.ts +130 -0
  272. package/src/components/virtual-list/_internal/frame-scheduler.ts +136 -0
  273. package/src/components/virtual-list/_internal/geometry.ts +236 -0
  274. package/src/components/virtual-list/_internal/list-semantics.ts +151 -0
  275. package/src/components/virtual-list/_internal/measurement-window.ts +300 -0
  276. package/src/components/virtual-list/_internal/reverse-order.ts +146 -0
  277. package/src/components/virtual-list/_internal/scroll-restoration.ts +209 -0
  278. package/src/components/virtual-list/_internal/sticky-items.ts +111 -0
  279. package/src/components/virtual-list/_internal/virtual-list-measurement-store.svelte.ts +145 -0
  280. package/src/components/virtual-list/index.ts +7 -1
  281. package/src/components/virtual-list/virtual-list.css +153 -2
  282. package/src/components/virtual-list/virtual-list.examples.json +42 -0
  283. package/src/components/virtual-list/virtual-list.schema.json +53 -3
  284. package/src/components/virtual-list/virtual-list.schema.ts +64 -3
  285. package/src/components/virtual-list/virtual-list.svelte +1527 -36
  286. package/src/components/virtual-list/virtual-list.types.ts +181 -4
  287. package/src/index.ts +3 -0
  288. package/src/styles/tokens-base.css +57 -22
  289. package/src/tokens/cinder.resolver.json +8 -0
  290. package/src/tokens/index.json +1 -1
  291. package/src/tokens/registry.generated.json +30 -4
  292. package/src/tokens/registry.generated.ts +32 -4
  293. package/src/tokens/resolved/dark-reduced-motion.json +47 -17
  294. package/src/tokens/resolved/dark.json +47 -17
  295. package/src/tokens/resolved/light-reduced-motion.json +48 -18
  296. package/src/tokens/resolved/light.json +48 -18
  297. package/src/tokens/sets/components.tokens.json +1 -1
  298. package/src/tokens/sets/semantic.tokens.json +120 -30
  299. package/src/tokens/themes/dark.tokens.json +115 -19
  300. package/src/tokens/themes/light.tokens.json +51 -3
  301. package/dist/server/index.server-191cnacw.js +0 -3
  302. package/dist/server/index.server-25dqx151.js +0 -3
  303. package/dist/server/index.server-77jyqvbv.js +0 -4
  304. package/dist/server/index.server-bgjrzr70.js +0 -3
  305. package/dist/server/index.server-khsp90vh.js +0 -3
  306. package/dist/server/index.server-ryk2pgbe.js +0 -4
  307. package/dist/server/index.server-tajr81bm.js +0 -3
  308. package/dist/server/index.server-vjzcrw3d.js +0 -4
  309. package/dist/server/index.server-zg3fx1n1.js +0 -3
@@ -0,0 +1,300 @@
1
+ /**
2
+ * Pure measurement/window engine for `dynamicSize` virtual-list mode.
3
+ *
4
+ * Everything in this module is dependency-free arithmetic: no DOM, no runes,
5
+ * no `ResizeObserver`. It is deliberately held to a 100%-lines/100%-functions
6
+ * coverage floor (see `coverage-ratchet.json`) because none of it needs a
7
+ * live browser to exercise every branch.
8
+ */
9
+
10
+ import type {
11
+ FixedVirtualWindow,
12
+ FixedVirtualWindowItem,
13
+ VirtualListKey,
14
+ } from '../../../utilities/fixed-virtual-window.ts';
15
+ import { resolveVirtualOverscan } from '../../../utilities/fixed-virtual-window.ts';
16
+
17
+ /**
18
+ * A cumulative offsets table for the dynamic-size engine, plus the total
19
+ * pixel size it sums to.
20
+ */
21
+ export type VirtualOffsets = {
22
+ /** offsets[i] = cumulative size of slots [0, i). Length itemCount + 1; offsets[itemCount] = totalSize. */
23
+ readonly offsets: readonly number[];
24
+ readonly totalSize: number;
25
+ };
26
+
27
+ /**
28
+ * Builds a fresh cumulative offsets table from the current item count and
29
+ * measurement cache. Rebuilds in full every call — `O(itemCount)` — rather
30
+ * than patching a dirty suffix, because a single measurement invalidates
31
+ * every later offset regardless, so an incremental patch's worst case is no
32
+ * better than a full rebuild. Callers are expected to memoize this behind a
33
+ * derived value keyed on item count and the measurement cache's version.
34
+ */
35
+ export function buildVirtualOffsets(options: {
36
+ itemCount: number;
37
+ estimateSize: number;
38
+ getKey: (index: number) => VirtualListKey;
39
+ measuredSizes: ReadonlyMap<VirtualListKey, number>;
40
+ }): VirtualOffsets {
41
+ const count = Math.max(0, Math.floor(options.itemCount));
42
+ const estimate = Math.max(1, options.estimateSize);
43
+ const offsets = Array.from({ length: count + 1 }, () => 0);
44
+ offsets[0] = 0;
45
+ for (let index = 0; index < count; index += 1) {
46
+ const size = options.measuredSizes.get(options.getKey(index)) ?? estimate;
47
+ offsets[index + 1] = offsets[index]! + size;
48
+ }
49
+ return { offsets, totalSize: offsets[count] ?? 0 };
50
+ }
51
+
52
+ /**
53
+ * Largest `i` such that `offsets[i] <= target`, found by binary search over
54
+ * an offsets table assumed sorted ascending (true by construction for any
55
+ * table `buildVirtualOffsets` produced). Returns 0 for an empty table.
56
+ */
57
+ export function findOffsetIndex(offsets: readonly number[], target: number): number {
58
+ const itemCount = Math.max(0, offsets.length - 1);
59
+ if (itemCount === 0) return 0;
60
+ let low = 0;
61
+ let high = itemCount - 1;
62
+ let result = 0;
63
+ while (low <= high) {
64
+ const middle = (low + high) >> 1;
65
+ if (offsets[middle]! <= target) {
66
+ result = middle;
67
+ low = middle + 1;
68
+ } else {
69
+ high = middle - 1;
70
+ }
71
+ }
72
+ return result;
73
+ }
74
+
75
+ /**
76
+ * Computes the windowed set of rows to mount for `dynamicSize` mode, given a
77
+ * cumulative offsets table.
78
+ *
79
+ * This is deliberately NOT numerically identical to
80
+ * `getFixedVirtualWindow` from `fixed-virtual-window.ts`. The fixed engine's
81
+ * `endIndex = startIndex + visibleCount + overscan * 2` formula effectively
82
+ * redistributes a start-side overscan budget "lost" to clamping at index 0
83
+ * onto the end side — an artifact of that formula, not a general
84
+ * virtualization requirement. This engine instead applies `overscan`
85
+ * symmetrically (subtracted from the visible start, added to the visible
86
+ * end, each independently clamped), which is simpler and independently
87
+ * correct. Do not "fix" this function to match the fixed engine's boundary
88
+ * behavior — the divergence is intentional and tested, not a regression.
89
+ */
90
+ export function getDynamicVirtualWindow(options: {
91
+ offsets: VirtualOffsets;
92
+ getKey: (index: number) => VirtualListKey;
93
+ scrollOffset: number;
94
+ viewportSize: number;
95
+ overscan: number;
96
+ }): FixedVirtualWindow {
97
+ const count = options.offsets.offsets.length - 1;
98
+ if (count <= 0) {
99
+ return { items: [], totalSize: 0, leadingSize: 0, trailingSize: 0, startIndex: 0, endIndex: 0 };
100
+ }
101
+
102
+ const { offsets, totalSize } = options.offsets;
103
+ const resolvedViewportSize =
104
+ Number.isFinite(options.viewportSize) && options.viewportSize > 0
105
+ ? options.viewportSize
106
+ : (totalSize / count) * 10;
107
+ const resolvedOverscan = resolveVirtualOverscan(options.overscan);
108
+ const maxScrollOffset = Math.max(0, totalSize - resolvedViewportSize);
109
+ const scrollOffset = Math.min(Math.max(0, options.scrollOffset), maxScrollOffset);
110
+
111
+ const visibleStartIndex = findOffsetIndex(offsets, scrollOffset);
112
+ const viewportEnd = scrollOffset + resolvedViewportSize;
113
+ let visibleEndIndex = visibleStartIndex;
114
+ while (visibleEndIndex < count - 1 && offsets[visibleEndIndex + 1]! < viewportEnd) {
115
+ visibleEndIndex += 1;
116
+ }
117
+
118
+ // Zero-height rows share an offset with their neighbour, and findOffsetIndex
119
+ // resolves a tie to the LAST such index — so a collapsed row sitting exactly at
120
+ // the window's leading edge falls outside it. With overscan 0 that row unmounts,
121
+ // loses its ResizeObserver, keeps its cached zero, and can never be remeasured
122
+ // to expand again. Extending the start back over zero-size siblings keeps them
123
+ // mounted and observable.
124
+ let leadingIndex = Math.max(0, visibleStartIndex - resolvedOverscan);
125
+ while (leadingIndex > 0 && offsets[leadingIndex] === offsets[leadingIndex - 1]) {
126
+ leadingIndex -= 1;
127
+ }
128
+ const startIndex = leadingIndex;
129
+ // +1: endIndex is exclusive.
130
+ let trailingIndex = Math.min(count, visibleEndIndex + 1 + resolvedOverscan);
131
+ // The mirror of the leading-edge walk below. A zero-height row sitting exactly at
132
+ // the trailing boundary is otherwise excluded, and with overscan 0 it unmounts,
133
+ // loses its ResizeObserver, and its cached zero keeps it out of every later
134
+ // window — so nothing can ever expand it again.
135
+ while (trailingIndex < count && offsets[trailingIndex] === offsets[trailingIndex + 1]) {
136
+ trailingIndex += 1;
137
+ }
138
+ const endIndex = trailingIndex;
139
+
140
+ const items: FixedVirtualWindowItem[] = [];
141
+ for (let index = startIndex; index < endIndex; index += 1) {
142
+ const start = offsets[index]!;
143
+ items.push({ index, key: options.getKey(index), start, size: offsets[index + 1]! - start });
144
+ }
145
+ const firstItem = items[0];
146
+ const lastItem = items.at(-1);
147
+
148
+ return {
149
+ items,
150
+ totalSize,
151
+ leadingSize: firstItem?.start ?? 0,
152
+ trailingSize: lastItem ? Math.max(0, totalSize - (lastItem.start + lastItem.size)) : 0,
153
+ startIndex,
154
+ endIndex,
155
+ };
156
+ }
157
+
158
+ /**
159
+ * Reads a single item's pixel `start`/`size` without requiring the caller to
160
+ * hand over an entire offsets table. `virtual-list.svelte` builds one
161
+ * implementation backed by `itemHeight * index` for fixed mode (`O(1)`, no
162
+ * offsets table needed) and one backed by the dynamic offsets table for
163
+ * `dynamicSize` mode (also `O(1)` once the table exists).
164
+ */
165
+ export type VirtualItemLocator = {
166
+ readonly getStart: (index: number) => number;
167
+ readonly getSize: (index: number) => number;
168
+ };
169
+
170
+ /** Alignment strategy for `scrollToIndex`. `'auto'` no-ops when the target is already fully within the viewport. */
171
+ export type VirtualListScrollAlign = 'start' | 'center' | 'end' | 'auto';
172
+
173
+ /**
174
+ * Computes the scroll offset that satisfies `scrollToIndex(index, { align })`
175
+ * for the given locator, clamped to `[0, totalSize - viewportSize]`.
176
+ */
177
+ export function computeScrollToIndexOffset(options: {
178
+ index: number;
179
+ itemCount: number;
180
+ locator: VirtualItemLocator;
181
+ totalSize: number;
182
+ viewportSize: number;
183
+ currentScrollOffset: number;
184
+ align: VirtualListScrollAlign;
185
+ /**
186
+ * Pixels of the leading edge covered by a sticky header. The reader's usable
187
+ * viewport starts below it, so a row aligned to the raw edge lands underneath it.
188
+ *
189
+ * This is the DESTINATION's header — the one that will cover the target row once it
190
+ * arrives — and it decides where the target goes.
191
+ */
192
+ leadingInset?: number;
193
+ /**
194
+ * Pixels covered at the leading edge RIGHT NOW, which is a different header whenever
195
+ * the target sits in another section. Only `align: 'auto'` uses it, to decide
196
+ * whether the row is already visible: a 20px header at the destination says nothing
197
+ * about the 100px one currently covering the row, and judging by the destination's
198
+ * made `scrollToIndex` conclude a hidden row was in view and do nothing at all.
199
+ *
200
+ * Defaults to `leadingInset`, which is right whenever both are the same header.
201
+ */
202
+ currentLeadingInset?: number;
203
+ /**
204
+ * Whether the target row is the sticky header currently held at the leading edge.
205
+ *
206
+ * It is fully visible there, but its logical `start` is somewhere above the scroll
207
+ * offset — that is what being stuck means — so the ordinary comparison reads it as
208
+ * overflowing above and `align: 'auto'` scrolls all the way back to its section, on
209
+ * a row the reader is already looking at.
210
+ */
211
+ targetIsStuckAtLeadingEdge?: boolean;
212
+ }): number {
213
+ // An empty list has no index to resolve, and clamping would hand the locator -1
214
+ // rounded up to 0 — making this helper depend on every caller's locator tolerating
215
+ // an out-of-range read rather than being safe on its own.
216
+ if (options.itemCount <= 0) return 0;
217
+ const clampedIndex = Math.max(0, Math.min(options.itemCount - 1, Math.floor(options.index)));
218
+ const start = options.locator.getStart(clampedIndex);
219
+ const size = options.locator.getSize(clampedIndex);
220
+ const maxScrollOffset = Math.max(0, options.totalSize - options.viewportSize);
221
+ // Clamped to the viewport. A header taller than the viewport would otherwise
222
+ // give a negative usable size and invert every comparison below.
223
+ const leadingInset = Math.min(Math.max(0, options.leadingInset ?? 0), options.viewportSize);
224
+ const usableViewportSize = options.viewportSize - leadingInset;
225
+ const currentLeadingInset = Math.min(
226
+ Math.max(0, options.currentLeadingInset ?? leadingInset),
227
+ options.viewportSize,
228
+ );
229
+
230
+ let target: number;
231
+ switch (options.align) {
232
+ case 'start':
233
+ target = start - leadingInset;
234
+ break;
235
+ case 'end':
236
+ // No inset: the trailing edge is the one nothing is covering.
237
+ target = start + size - options.viewportSize;
238
+ break;
239
+ case 'center':
240
+ // Centered in what the reader can see, which begins below the header.
241
+ target = start - leadingInset - (usableViewportSize - size) / 2;
242
+ break;
243
+ case 'auto':
244
+ default: {
245
+ // Stuck at the edge is as visible as a row gets, whatever its offset says.
246
+ if (options.targetIsStuckAtLeadingEdge) {
247
+ target = options.currentScrollOffset;
248
+ break;
249
+ }
250
+ // The top of what the reader can see, not the top of the scroll container: a row
251
+ // behind the sticky header is as good as offscreen. Measured with the header
252
+ // covering the edge NOW, since that is what decides whether the row is visible;
253
+ // where it then goes is still the destination header's business.
254
+ const viewportStart = options.currentScrollOffset + currentLeadingInset;
255
+ const viewportEnd = options.currentScrollOffset + options.viewportSize;
256
+ const overflowsAbove = start < viewportStart;
257
+ const overflowsBelow = start + size > viewportEnd;
258
+ if (size > usableViewportSize) {
259
+ // A row STRICTLY taller than the viewport can never satisfy both edge checks,
260
+ // so edge-preference alternates forever: align its start and the end now
261
+ // overflows, align its end and the start does. The loop would oscillate and
262
+ // the final position would depend on the attempt cap.
263
+ //
264
+ // Keyed on the row's SIZE rather than on both overflow flags, because at the
265
+ // exact boundary reached after scrolling to an initially offscreen row only
266
+ // one flag is true and the earlier both-flags form fell through to edge
267
+ // alignment again. Overlapping means the reader is already inside the row, so
268
+ // hold; otherwise bring its start into view, after which holding takes over.
269
+ // Strictly taller, not >=: a row exactly the viewport's height CAN be fully
270
+ // revealed, so holding it half-visible would break auto's own contract.
271
+ const overlapsViewport = start < viewportEnd && start + size > viewportStart;
272
+ target = overlapsViewport ? options.currentScrollOffset : start - leadingInset;
273
+ } else if (overflowsAbove) target = start - leadingInset;
274
+ else if (overflowsBelow) target = start + size - options.viewportSize;
275
+ else target = options.currentScrollOffset;
276
+ break;
277
+ }
278
+ }
279
+ return Math.min(Math.max(0, target), maxScrollOffset);
280
+ }
281
+
282
+ /** One queued measurement correction: the item at `index` changed size by `delta` pixels. */
283
+ export type MeasurementCorrection = { readonly index: number; readonly delta: number };
284
+
285
+ /**
286
+ * Sums the size deltas of every correction whose index is strictly before
287
+ * `anchorIndex` — these are exactly the deltas that shift the anchor's own
288
+ * pixel position, and therefore exactly what a scroll-offset correction
289
+ * must add back to keep the anchor visually stationary.
290
+ */
291
+ export function resolveMeasurementCorrectionDelta(
292
+ corrections: readonly MeasurementCorrection[],
293
+ anchorIndex: number,
294
+ ): number {
295
+ let delta = 0;
296
+ for (const correction of corrections) {
297
+ if (correction.index < anchorIndex) delta += correction.delta;
298
+ }
299
+ return delta;
300
+ }
@@ -0,0 +1,146 @@
1
+ /**
2
+ * Pure ordering/anchoring math for `reverse` virtual-list mode (chat
3
+ * transcripts). See CIN-194 for the decided semantics.
4
+ *
5
+ * `reverse` renders items in ordinary chronological order — oldest at index
6
+ * 0, newest at the last index — and is bottom-anchored: the newest item sits
7
+ * at the bottom of the viewport, and the list starts scrolled to the bottom.
8
+ * The name describes the anchoring, not the item order; nothing here
9
+ * reverses an array.
10
+ *
11
+ * `reverse` is deliberately distinct from `stickToBottom`. `stickToBottom`
12
+ * only pins on append when the reader is already at the bottom. `reverse`
13
+ * always pins on append, because a chat transcript's whole point is that new
14
+ * messages are the thing you came to see — the reader scrolling up to reread
15
+ * older history should not be interpreted as "let new messages pile up
16
+ * unseen," the way it would be in a general-purpose bottom-sticking list.
17
+ *
18
+ * Everything here is dependency-free arithmetic: no DOM, no runes, no
19
+ * globals. Held to the same 100%-lines/100%-functions coverage floor as
20
+ * `measurement-window.ts` (see `coverage-ratchet.json`).
21
+ */
22
+
23
+ import type { VirtualListKey } from '../../../utilities/fixed-virtual-window.ts';
24
+
25
+ /**
26
+ * How the item-key sequence changed between two renders of a `reverse` list.
27
+ * Anchoring decisions are keyed off this, not off item count alone, because
28
+ * a same-length reorder and a same-length no-op both need to be told apart
29
+ * from a genuine boundary change.
30
+ */
31
+ export type ItemGrowth =
32
+ | { readonly kind: 'appended'; readonly appendedCount: number }
33
+ | { readonly kind: 'prepended'; readonly prependedCount: number }
34
+ | { readonly kind: 'unchanged' }
35
+ | { readonly kind: 'replaced' };
36
+
37
+ function keysAreEqual(
38
+ firstKeys: readonly VirtualListKey[],
39
+ secondKeys: readonly VirtualListKey[],
40
+ ): boolean {
41
+ if (firstKeys.length !== secondKeys.length) return false;
42
+ for (let index = 0; index < firstKeys.length; index += 1) {
43
+ if (firstKeys[index] !== secondKeys[index]) return false;
44
+ }
45
+ return true;
46
+ }
47
+
48
+ /**
49
+ * Classifies how `nextKeys` relates to `previousKeys` for anchoring
50
+ * purposes.
51
+ *
52
+ * A real append leaves the FIRST key untouched and adds new keys at the END
53
+ * — so it is detected by `previousKeys` being a PREFIX of `nextKeys`. A
54
+ * prepend (loading older history above the top) leaves the LAST key
55
+ * untouched and adds new keys at the START — detected by `previousKeys`
56
+ * being a SUFFIX of `nextKeys`. Getting the prefix/suffix pairing backwards
57
+ * here would silently swap "new message arrived" for "older history
58
+ * loaded," which is exactly the kind of bug this module exists to prevent,
59
+ * so the two checks are kept explicit rather than merged into one
60
+ * direction-agnostic helper.
61
+ *
62
+ * `previousKeys` (length 0) is trivially both a prefix and a suffix of any
63
+ * `nextKeys`, so an empty-to-non-empty transition satisfies both checks —
64
+ * see the tie-break note below.
65
+ */
66
+ export function classifyItemGrowth(
67
+ previousKeys: readonly VirtualListKey[],
68
+ nextKeys: readonly VirtualListKey[],
69
+ ): ItemGrowth {
70
+ if (keysAreEqual(previousKeys, nextKeys)) {
71
+ return { kind: 'unchanged' };
72
+ }
73
+
74
+ // Only a strictly longer nextKeys can be an append or a prepend — a
75
+ // same-length or shorter change is a reorder, a removal, or some other
76
+ // rewrite the caller must re-render for, so it falls through to 'replaced'.
77
+ if (nextKeys.length > previousKeys.length) {
78
+ const isPrefixExtension = keysAreEqual(nextKeys.slice(0, previousKeys.length), previousKeys);
79
+ // Prefix wins when nextKeys satisfies BOTH checks (e.g. previousKeys
80
+ // ['a'], nextKeys ['a', 'a']). A chat transcript grows almost entirely by
81
+ // new messages arriving, so an ambiguous single-item growth should
82
+ // resolve to the far more common 'appended' case rather than
83
+ // 'prepended', which callers treat as a history page that must NOT
84
+ // disturb the reader's scroll position.
85
+ if (isPrefixExtension) {
86
+ return { kind: 'appended', appendedCount: nextKeys.length - previousKeys.length };
87
+ }
88
+
89
+ const isSuffixExtension = keysAreEqual(
90
+ nextKeys.slice(nextKeys.length - previousKeys.length),
91
+ previousKeys,
92
+ );
93
+ if (isSuffixExtension) {
94
+ return { kind: 'prepended', prependedCount: nextKeys.length - previousKeys.length };
95
+ }
96
+ }
97
+
98
+ return { kind: 'replaced' };
99
+ }
100
+
101
+ /**
102
+ * The scroll offset that puts the end of the content flush with the
103
+ * viewport's bottom edge — the resting position `reverse` mode starts at and
104
+ * snaps back to on every pinned append. Clamped to never go negative: when
105
+ * the content is shorter than the viewport, the only valid resting position
106
+ * is the top (offset 0), not a negative offset that would leave blank space
107
+ * above the content.
108
+ */
109
+ export function resolveReversePinTarget(options: {
110
+ totalSize: number;
111
+ viewportSize: number;
112
+ }): number {
113
+ return Math.max(0, options.totalSize - options.viewportSize);
114
+ }
115
+
116
+ /** Anchoring strategy a virtual list can run under. */
117
+ export type ReversePinMode = 'reverse' | 'stick-to-bottom' | 'none';
118
+
119
+ /**
120
+ * Decides whether a render should snap the scroll offset back to
121
+ * `resolveReversePinTarget`.
122
+ *
123
+ * Pinning only ever happens on `'appended'` growth. A `'prepended'` change
124
+ * (older history loaded above the top) must never pin to the end — doing so
125
+ * would yank a reader who just asked to see older messages straight back
126
+ * down to the newest one. `'unchanged'` and `'replaced'` never pin either:
127
+ * there is no new content at the end to reveal.
128
+ */
129
+ export function shouldPinToEnd(options: {
130
+ mode: ReversePinMode;
131
+ growth: ItemGrowth;
132
+ isAtEnd: boolean;
133
+ }): boolean {
134
+ if (options.growth.kind !== 'appended') return false;
135
+
136
+ switch (options.mode) {
137
+ case 'reverse':
138
+ // Always pins, regardless of where the reader is scrolled — this is
139
+ // the entire behavioral difference from 'stick-to-bottom'.
140
+ return true;
141
+ case 'stick-to-bottom':
142
+ return options.isAtEnd;
143
+ case 'none':
144
+ return false;
145
+ }
146
+ }
@@ -0,0 +1,209 @@
1
+ /**
2
+ * Pure scroll-position persistence for the virtual list's `scrollRestoration`
3
+ * option.
4
+ *
5
+ * Dependency-free: no DOM, no `sessionStorage` global. The virtual list
6
+ * mounts during server rendering, where `sessionStorage` does not exist, so
7
+ * every function here takes its storage as an explicit
8
+ * `ScrollRestorationStorage` parameter instead of reaching for the global
9
+ * directly. `virtual-list.svelte` is responsible for passing the real
10
+ * `sessionStorage` (or nothing, when `scrollRestoration` is off or the
11
+ * component is server-rendering) at the call site.
12
+ */
13
+
14
+ /**
15
+ * The minimal structural shape this module needs from a storage object.
16
+ * `sessionStorage` satisfies it, and so does an in-memory fake in tests —
17
+ * this module never names `Storage` or the global directly, so it stays
18
+ * importable anywhere, DOM or no DOM.
19
+ */
20
+ export type ScrollRestorationStorage = {
21
+ getItem(key: string): string | null;
22
+ setItem(key: string, value: string): void;
23
+ removeItem(key: string): void;
24
+ };
25
+
26
+ /** A saved scroll position: where the viewport was, and which row led it. */
27
+ export type ScrollRestorationPosition = {
28
+ readonly scrollOffset: number;
29
+ readonly startIndex: number;
30
+ /**
31
+ * How far into the anchor row the reader had scrolled.
32
+ *
33
+ * Optional because entries written before this field existed must still load —
34
+ * `sessionStorage` survives deploys, and a missing remainder simply means the row's
35
+ * start edge, which is what the previous version restored anyway.
36
+ */
37
+ readonly offsetWithinRow?: number;
38
+ /**
39
+ * The anchor row's key, when the list had one.
40
+ *
41
+ * An index alone stops describing the same row as soon as the collection changes
42
+ * while the list is unmounted — a feed that received older messages restores
43
+ * several rows off. The key survives that; the index remains as the fallback for
44
+ * a list without `getKey`, and for entries written before this field existed.
45
+ */
46
+ readonly anchorKey?: string | number;
47
+ };
48
+
49
+ const SCROLL_RESTORATION_KEY_PREFIX = 'cinder:virtual-list:';
50
+
51
+ /**
52
+ * Namespaces a consumer-provided id into a storage key, so one list's saved
53
+ * position can't collide with an unrelated `sessionStorage` entry sharing
54
+ * the same page.
55
+ *
56
+ * Returns `null` for an empty or whitespace-only id rather than falling
57
+ * back to the bare prefix — silently writing to a shared prefix key would
58
+ * make every un-id'd list on the page overwrite one another's saved
59
+ * position.
60
+ */
61
+ export function resolveScrollRestorationKey(id: string): string | null {
62
+ // Built from the TRIMMED id, which is what was validated. Keying on the raw value
63
+ // made ids differing only by surrounding whitespace resolve to different entries,
64
+ // so a caller who added a space silently lost their saved position.
65
+ const trimmed = id.trim();
66
+ return trimmed.length === 0 ? null : `${SCROLL_RESTORATION_KEY_PREFIX}${trimmed}`;
67
+ }
68
+
69
+ /**
70
+ * A saved `startIndex` must be a whole number: it is used to index `items` and is
71
+ * handed to `scrollToIndex`. A fractional value read back from storage — which is
72
+ * shared, user-writable, and survives deploys — would resolve to no row at all.
73
+ */
74
+ function isValidScrollRestorationIndex(value: unknown): value is number {
75
+ return typeof value === 'number' && Number.isInteger(value) && value >= 0;
76
+ }
77
+
78
+ /** Serializes a scroll position for storage. */
79
+ export function serializeScrollPosition(position: ScrollRestorationPosition): string {
80
+ return JSON.stringify(position);
81
+ }
82
+
83
+ type UnknownScrollRestorationPosition = {
84
+ offsetWithinRow?: unknown;
85
+ anchorKey?: unknown;
86
+ scrollOffset?: unknown;
87
+ startIndex?: unknown;
88
+ };
89
+
90
+ function isValidScrollRestorationField(value: unknown): value is number {
91
+ return typeof value === 'number' && Number.isFinite(value) && value >= 0;
92
+ }
93
+
94
+ /**
95
+ * Parses a previously-serialized scroll position. MUST be total: it never
96
+ * throws, and it never returns anything but a well-formed position or
97
+ * `null`.
98
+ *
99
+ * `sessionStorage` is shared with the rest of the page, user-writable via
100
+ * devtools, and outlives deploys where this shape may have changed
101
+ * underneath it. Every read is therefore untrusted input: malformed JSON, a
102
+ * JSON value that isn't an object, a missing or non-numeric field, and a
103
+ * non-finite or negative number are all treated as "nothing saved" rather
104
+ * than propagated as an error.
105
+ */
106
+ export function deserializeScrollPosition(raw: string | null): ScrollRestorationPosition | null {
107
+ if (raw === null) return null;
108
+
109
+ let parsed: unknown;
110
+ try {
111
+ parsed = JSON.parse(raw);
112
+ } catch {
113
+ return null;
114
+ }
115
+
116
+ // `Array.isArray` is deliberately not checked here: a JSON array destructures
117
+ // to `undefined` for both named fields below just as any other non-matching
118
+ // object would, so the field validation already rejects it — a redundant
119
+ // isArray branch would be dead weight no test could distinguish.
120
+ if (typeof parsed !== 'object' || parsed === null) return null;
121
+
122
+ const candidate = parsed as UnknownScrollRestorationPosition;
123
+ const { scrollOffset, startIndex } = candidate;
124
+ if (!isValidScrollRestorationField(scrollOffset) || !isValidScrollRestorationIndex(startIndex)) {
125
+ return null;
126
+ }
127
+
128
+ // Absent or malformed, the remainder is simply zero: the row's start edge, which
129
+ // is exactly what an entry from before this field existed meant.
130
+ const { offsetWithinRow, anchorKey } = candidate;
131
+ const isUsableKey = typeof anchorKey === 'string' || typeof anchorKey === 'number';
132
+ return {
133
+ scrollOffset,
134
+ startIndex,
135
+ offsetWithinRow: isValidScrollRestorationField(offsetWithinRow) ? offsetWithinRow : 0,
136
+ ...(isUsableKey ? { anchorKey } : {}),
137
+ };
138
+ }
139
+
140
+ /**
141
+ * Saves a scroll position under the consumer's id.
142
+ *
143
+ * A no-op when `storage` is undefined (server rendering, or a consumer who
144
+ * left `scrollRestoration` off) or when the id resolves to no usable key.
145
+ * Swallows a throwing `setItem`: Safari private browsing, and any browser at
146
+ * its storage quota, throw `QuotaExceededError` on write, and a component
147
+ * must not break navigation because it couldn't remember where the list was
148
+ * scrolled to.
149
+ */
150
+ export function saveScrollPosition(
151
+ storage: ScrollRestorationStorage | undefined,
152
+ id: string,
153
+ position: ScrollRestorationPosition,
154
+ ): void {
155
+ if (storage === undefined) return;
156
+ const key = resolveScrollRestorationKey(id);
157
+ if (key === null) return;
158
+
159
+ try {
160
+ storage.setItem(key, serializeScrollPosition(position));
161
+ } catch {
162
+ // Quota exceeded, or storage otherwise unwritable — losing a scroll
163
+ // offset is not worth breaking navigation over.
164
+ }
165
+ }
166
+
167
+ /**
168
+ * Loads a previously-saved scroll position for the consumer's id.
169
+ *
170
+ * A no-op returning `null` when `storage` is undefined or the id resolves
171
+ * to no usable key. Swallows a throwing `getItem`: some privacy modes throw
172
+ * on access itself, not only on write.
173
+ */
174
+ export function loadScrollPosition(
175
+ storage: ScrollRestorationStorage | undefined,
176
+ id: string,
177
+ ): ScrollRestorationPosition | null {
178
+ if (storage === undefined) return null;
179
+ const key = resolveScrollRestorationKey(id);
180
+ if (key === null) return null;
181
+
182
+ try {
183
+ return deserializeScrollPosition(storage.getItem(key));
184
+ } catch {
185
+ return null;
186
+ }
187
+ }
188
+
189
+ /**
190
+ * Clears a previously-saved scroll position for the consumer's id.
191
+ *
192
+ * Same guards as `saveScrollPosition`/`loadScrollPosition`: a no-op when
193
+ * `storage` is undefined or the id resolves to no usable key, and swallows
194
+ * a throwing `removeItem`.
195
+ */
196
+ export function clearScrollPosition(
197
+ storage: ScrollRestorationStorage | undefined,
198
+ id: string,
199
+ ): void {
200
+ if (storage === undefined) return;
201
+ const key = resolveScrollRestorationKey(id);
202
+ if (key === null) return;
203
+
204
+ try {
205
+ storage.removeItem(key);
206
+ } catch {
207
+ // Storage inaccessible — nothing to clean up if we can't reach it.
208
+ }
209
+ }