@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,111 @@
1
+ /**
2
+ * Pure decision logic for `stickyItems` (CIN-199): which item indexes act as
3
+ * sticky headers/rows in a virtual list, which one is currently pinned to
4
+ * the leading edge, and which extra indexes the rendered window must keep
5
+ * mounted so a pinned row never disappears mid-scroll.
6
+ *
7
+ * `virtual-list.svelte` owns the DOM half of sticky positioning — applying
8
+ * sticky positioning to the active row and mounting whatever this module
9
+ * reports. Everything here is index arithmetic only: no DOM, no runes,
10
+ * dependency-free, matching the rest of `_internal/`.
11
+ */
12
+
13
+ /**
14
+ * Sanitizes a consumer-supplied `stickyItems` array into a sorted,
15
+ * de-duplicated list of valid item indexes in `[0, itemCount - 1]`.
16
+ *
17
+ * `stickyItems` comes straight from a consumer's prop, so it can hold
18
+ * anything: floats, negatives, out-of-range values, duplicates in any
19
+ * order, `NaN`, or `Infinity`. None of that is a reason to throw or to fail
20
+ * rendering — a bad sticky index is a cosmetic problem, not a correctness
21
+ * one — so invalid entries are silently dropped instead.
22
+ */
23
+ export function normalizeStickyIndexes(
24
+ stickyItems: readonly number[] | undefined,
25
+ itemCount: number,
26
+ ): readonly number[] {
27
+ if (stickyItems === undefined || stickyItems.length === 0) return [];
28
+
29
+ // A non-finite itemCount (NaN, +/-Infinity) has no meaningful "last valid
30
+ // index" — and NaN specifically is dangerous to fall through on, since
31
+ // EVERY comparison against it is false, which would make the `candidate <
32
+ // 0 || candidate > maximumIndex` guard below vacuously false and let bad
33
+ // candidates through instead of rejecting them. Treat it the same as an
34
+ // itemCount with no valid range at all: nothing normalizes.
35
+ if (!Number.isFinite(itemCount)) return [];
36
+
37
+ const maximumIndex = itemCount - 1;
38
+
39
+ const validIndexes = new Set<number>();
40
+ for (const candidate of stickyItems) {
41
+ // Number.isInteger rejects NaN, +/-Infinity, and any fractional value in
42
+ // one check — every "not really an index" shape a consumer array can hold.
43
+ if (!Number.isInteger(candidate)) continue;
44
+ if (candidate < 0 || candidate > maximumIndex) continue;
45
+ validIndexes.add(candidate);
46
+ }
47
+
48
+ return Array.from(validIndexes).sort((leftIndex, rightIndex) => leftIndex - rightIndex);
49
+ }
50
+
51
+ /**
52
+ * Binary search for the greatest position in `sortedValues` whose value is
53
+ * `<= target`. Returns `-1` when no such value exists — either the array is
54
+ * empty or every value exceeds `target`. Assumes `sortedValues` is sorted
55
+ * ascending, which holds for any array `normalizeStickyIndexes` produced.
56
+ */
57
+ function findGreatestIndexAtOrBefore(sortedValues: readonly number[], target: number): number {
58
+ let low = 0;
59
+ let high = sortedValues.length - 1;
60
+ let result = -1;
61
+ while (low <= high) {
62
+ const middle = (low + high) >> 1;
63
+ const value = sortedValues[middle]!;
64
+ if (value <= target) {
65
+ result = middle;
66
+ low = middle + 1;
67
+ } else {
68
+ high = middle - 1;
69
+ }
70
+ }
71
+ return result;
72
+ }
73
+ /**
74
+ * The sticky index currently pinned to the leading edge: the greatest entry
75
+ * in `stickyIndexes` that is at or before `firstVisibleIndex`. `null` when
76
+ * no sticky index qualifies — the reader has not yet scrolled to or past the
77
+ * first one.
78
+ *
79
+ * Uses a binary search rather than a linear scan because this runs on every
80
+ * scroll frame, and `stickyIndexes` can be long for a grouped list (one
81
+ * sticky entry per group, with many groups).
82
+ */
83
+ export function resolveActiveStickyIndex(
84
+ stickyIndexes: readonly number[],
85
+ firstVisibleIndex: number,
86
+ ): number | null {
87
+ const position = findGreatestIndexAtOrBefore(stickyIndexes, firstVisibleIndex);
88
+ return position === -1 ? null : stickyIndexes[position]!;
89
+ }
90
+
91
+ /**
92
+ * The sticky header that covers row `index` once that row reaches the leading
93
+ * edge, or `null` when nothing does.
94
+ *
95
+ * A sticky row covers nothing at its own index: it IS the header there, so there
96
+ * is no obstruction above it.
97
+ *
98
+ * This asks a different question from `resolveActiveStickyIndex`, which answers
99
+ * "what is pinned right now" from the current scroll position. Scroll destinations
100
+ * must not be keyed on the current position: the inset would change as the scroll
101
+ * moved, so a settle loop would recompute a different target on each pass and a
102
+ * header taller than a row makes it oscillate between the header's start and the
103
+ * row's, landing wherever the attempt cap happened to stop.
104
+ */
105
+ export function resolveObstructingStickyIndex(
106
+ stickyIndexes: readonly number[],
107
+ index: number,
108
+ ): number | null {
109
+ const header = resolveActiveStickyIndex(stickyIndexes, index);
110
+ return header === null || header === index ? null : header;
111
+ }
@@ -0,0 +1,145 @@
1
+ /**
2
+ * Smallest size change treated as a real resize rather than sub-pixel noise.
3
+ *
4
+ * Measurements are cached at full precision — quantizing them would make the
5
+ * error compound down the offsets table, so a list of 5,000 rows measured at
6
+ * 20.4px each would come out roughly 2,000px short and every `scrollToIndex`
7
+ * target past the top of the list would be wrong.
8
+ *
9
+ * The epsilon governs change DETECTION only. It is what stops the feedback loop
10
+ * where writing a scroll correction relayouts rows, whose `ResizeObserver`
11
+ * reports the same size back, which queues another correction. Because sizes are
12
+ * stored exactly, a re-report is normally bit-identical and would be caught even
13
+ * at zero; the epsilon is margin against float jitter from device-pixel-ratio
14
+ * rounding, not a substitute for exact storage.
15
+ */
16
+ const MEASUREMENT_EPSILON = 0.01;
17
+ /**
18
+ * Reactive cache of real, ResizeObserver-measured row sizes for `dynamicSize`
19
+ * VirtualList mode, plus a queue of the scroll corrections those
20
+ * measurements imply.
21
+ *
22
+ * Deliberately backed by a plain `Map`, not `SvelteMap`: consumers (the
23
+ * component's `offsets` `$derived`) drive their recomputation off the
24
+ * `version` counter below, so the map itself does not need per-key
25
+ * reactivity — and a plain `Map` avoids per-key subscription overhead on a
26
+ * list with tens of thousands of rows.
27
+ */
28
+ export class VirtualListMeasurementStore {
29
+ #sizes = new Map();
30
+ /**
31
+ * Running total of every cached size.
32
+ *
33
+ * Maintained here rather than summed on demand. The cache keeps every row the
34
+ * reader has visited, so re-summing it on each measurement makes scrolling through
35
+ * a long list cost O(n²) overall — and it is the fast-scroll path that pays, which
36
+ * is precisely the path adaptive overscan exists to protect.
37
+ */
38
+ #measuredTotalSize = 0;
39
+ #pendingCorrections = [];
40
+ #version = $state(0);
41
+ #pendingCorrectionsVersion = $state(0);
42
+ /** Bumped whenever a cached size actually changes. Drive buildVirtualOffsets's $derived off this. */
43
+ get version() {
44
+ return this.#version;
45
+ }
46
+ /** Bumped whenever a non-zero-delta correction is queued. Drive the anchor-correction $effect.pre off this. */
47
+ get pendingCorrectionsVersion() {
48
+ return this.#pendingCorrectionsVersion;
49
+ }
50
+ /**
51
+ * How many rows have been measured, read WITHOUT touching the version counter.
52
+ *
53
+ * Deliberately non-reactive: it exists so a caller can cheaply skip work when
54
+ * nothing has been measured yet. Reading {@link sizes} for that would register a
55
+ * dependency on every measurement and re-run the caller on each one, which is
56
+ * the opposite of the intent.
57
+ */
58
+ get measuredCount() {
59
+ return this.#sizes.size;
60
+ }
61
+ /**
62
+ * Sum of every cached size, kept in step with the cache rather than recomputed.
63
+ *
64
+ * Non-reactive for the same reason as {@link measuredCount}: a caller wanting to
65
+ * recompute when it changes reads {@link version}.
66
+ */
67
+ get measuredTotalSize() {
68
+ return this.#measuredTotalSize;
69
+ }
70
+ /** Live, read-only view of the measured-size cache, keyed by row key. */
71
+ get sizes() {
72
+ // Touch #version so a $derived that reads only `.sizes` (never `.version`
73
+ // directly) still re-runs whenever the cache mutates.
74
+ void this.#version;
75
+ return this.#sizes;
76
+ }
77
+ /**
78
+ * Records a ResizeObserver measurement. Sizes are stored at FULL PRECISION;
79
+ * nothing is rounded. A report within {@link MEASUREMENT_EPSILON} of the cached
80
+ * value is treated as unchanged and no-ops (no version bump, no queued
81
+ * correction) — which is what stops a measurement feedback loop, since writing
82
+ * the corrected scroll offset re-lays-out rows that then report the same size
83
+ * back. The epsilon governs change DETECTION only, never what is stored.
84
+ *
85
+ * The queued correction's delta is measured against whatever the offsets
86
+ * table already assumed for this row: `estimateSize` on a first
87
+ * measurement (nothing cached yet), or the previously cached size on a
88
+ * re-measurement.
89
+ */
90
+ record(key, index, size, estimateSize) {
91
+ const previousSize = this.#sizes.get(key);
92
+ if (previousSize !== undefined && Math.abs(previousSize - size) < MEASUREMENT_EPSILON)
93
+ return;
94
+ const previousBaseline = previousSize ?? estimateSize;
95
+ const delta = size - previousBaseline;
96
+ this.#sizes.set(key, size);
97
+ this.#measuredTotalSize += size - (previousSize ?? 0);
98
+ this.#version += 1;
99
+ if (Math.abs(delta) >= MEASUREMENT_EPSILON) {
100
+ this.#pendingCorrections.push({ index, delta });
101
+ this.#pendingCorrectionsVersion += 1;
102
+ }
103
+ }
104
+ /**
105
+ * Drains and returns every correction queued since the last call. Call
106
+ * ONLY from `$effect.pre` — a second call with no intervening `record()`
107
+ * returns an empty array.
108
+ */
109
+ consumePendingCorrections() {
110
+ const corrections = this.#pendingCorrections;
111
+ this.#pendingCorrections = [];
112
+ return corrections;
113
+ }
114
+ /**
115
+ * Drops cached sizes for keys no longer present (e.g. after items
116
+ * filters/reorders). Bumps `version` only when a size was actually
117
+ * removed.
118
+ */
119
+ prune(validKeys) {
120
+ const keysToRemove = [];
121
+ for (const key of this.#sizes.keys()) {
122
+ if (!validKeys.has(key))
123
+ keysToRemove.push(key);
124
+ }
125
+ if (keysToRemove.length === 0)
126
+ return;
127
+ for (const key of keysToRemove) {
128
+ this.#measuredTotalSize -= this.#sizes.get(key) ?? 0;
129
+ this.#sizes.delete(key);
130
+ }
131
+ this.#version += 1;
132
+ }
133
+ /**
134
+ * Clears every cached size and any undrained pending corrections. Bumps
135
+ * `version` only when there was a cached size to clear.
136
+ */
137
+ reset() {
138
+ if (this.#sizes.size > 0) {
139
+ this.#sizes.clear();
140
+ this.#measuredTotalSize = 0;
141
+ this.#version += 1;
142
+ }
143
+ this.#pendingCorrections = [];
144
+ }
145
+ }
@@ -12,5 +12,11 @@ export type {
12
12
  FixedVirtualWindow,
13
13
  FixedVirtualWindowItem,
14
14
  } from '../../utilities/fixed-virtual-window.ts';
15
- export type { VirtualListProps, VirtualListRowContext } from './virtual-list.types.ts';
15
+ export type {
16
+ VirtualListProps,
17
+ VirtualListRef,
18
+ VirtualListRowContext,
19
+ VirtualListScrollAlign,
20
+ VirtualListScrollToIndexOptions,
21
+ } from './virtual-list.types.ts';
16
22
  export { VirtualList };
@@ -2,8 +2,6 @@
2
2
 
3
3
  @layer cinder.components {
4
4
  .cinder-virtual-list {
5
- --cinder-virtual-list-height: 20rem;
6
-
7
5
  display: block;
8
6
  block-size: var(--cinder-virtual-list-height, 20rem);
9
7
  inline-size: 100%;
@@ -13,6 +11,86 @@
13
11
  contain: layout paint;
14
12
  }
15
13
 
14
+ /*
15
+ * Dynamic sizing anchors the viewport itself: when a measured row above the
16
+ * fold turns out to differ from its estimate, the component adds that delta to
17
+ * the scroll offset before paint.
18
+ *
19
+ * A browser with native scroll anchoring would ALSO adjust scrollTop to hold
20
+ * its own anchor when that row resizes, and the manual correction then applies
21
+ * the same delta on top of the browser's — over-scrolling by the row's size
22
+ * difference every time an image loads or a line wraps. Only one of the two can
23
+ * own the anchor, and this component owns it.
24
+ *
25
+ * Scoped to dynamic mode: fixed-height rows never resize, so native anchoring
26
+ * has nothing to act on there and the default is left alone.
27
+ */
28
+ .cinder-virtual-list[data-cinder-dynamic-size='true'] {
29
+ overflow-anchor: none;
30
+
31
+ /*
32
+ * Reserve the scrollbar gutter so the width available to rows does not depend
33
+ * on whether a scrollbar is currently showing.
34
+ *
35
+ * Without this, dynamic sizing oscillates on platforms with non-overlay
36
+ * scrollbars: measured rows overflow the estimated total, a scrollbar appears,
37
+ * the narrower content width invalidates every measurement, the estimated
38
+ * spacer shrinks below the viewport, the scrollbar disappears, the width grows
39
+ * back, and the cycle repeats — burning layout work and tripping
40
+ * ResizeObserver loop errors. A stable gutter removes the input to that loop
41
+ * instead of damping its output.
42
+ */
43
+ scrollbar-gutter: stable;
44
+ }
45
+
46
+ /*
47
+ * Horizontal mode swaps the scroll axis. `--cinder-virtual-list-height` keeps its
48
+ * name and drives inline-size here rather than block-size, so a consumer's
49
+ * existing theme override survives turning `horizontal` on — see the prop's
50
+ * JSDoc for why the name is reused instead of a second token being introduced.
51
+ */
52
+ .cinder-virtual-list[data-cinder-orientation='horizontal'] {
53
+ block-size: auto;
54
+ inline-size: var(--cinder-virtual-list-height, 20rem);
55
+ overflow-x: auto;
56
+ overflow-y: hidden;
57
+ }
58
+
59
+ /*
60
+ * The spacer carries the scroll extent on the inline axis instead of the block
61
+ * axis, so the base rule's `min-block-size: 100%` / `inline-size: 100%` pair is
62
+ * transposed. The inline size itself comes from the element's style attribute,
63
+ * which the component writes as a logical property.
64
+ */
65
+ .cinder-virtual-list[data-cinder-orientation='horizontal'] .cinder-virtual-list__spacer {
66
+ min-block-size: 0;
67
+ min-inline-size: 100%;
68
+ }
69
+
70
+ /*
71
+ * In flow, unlike the vertical case. A vertical list takes its block-size from
72
+ * the `height` prop, so an out-of-flow window costs nothing; horizontal
73
+ * reinterprets that prop as the inline size and leaves block-size `auto`, so an
74
+ * absolutely positioned window would leave the container with no content of any
75
+ * height and collapse it to zero. Relative positioning keeps the rows
76
+ * contributing their height while still shifting the window to the scroll offset.
77
+ *
78
+ * `inset-inline-end: auto` is load-bearing: the base rule pins both inline edges
79
+ * to stretch the window across a vertical list. Left in place, an over-constrained
80
+ * relative box drops whichever edge is the end one for the writing direction —
81
+ * which silently means the START edge under RTL, and the window would not move.
82
+ */
83
+ .cinder-virtual-list[data-cinder-orientation='horizontal'] .cinder-virtual-list__window {
84
+ position: relative;
85
+ display: flex;
86
+ inset-inline-end: auto;
87
+ }
88
+
89
+ /* Rows are sized along the inline axis; flex must not shrink them to fit. */
90
+ .cinder-virtual-list[data-cinder-orientation='horizontal'] .cinder-virtual-list__row {
91
+ flex: 0 0 auto;
92
+ }
93
+
16
94
  .cinder-virtual-list__spacer {
17
95
  position: relative;
18
96
  min-block-size: 100%;
@@ -27,4 +105,77 @@
27
105
  .cinder-virtual-list__row {
28
106
  overflow: hidden;
29
107
  }
108
+
109
+ /*
110
+ * The active sticky row once its own index has left the window.
111
+ *
112
+ * Absolute, so it does not displace the rows the window is laying out in flow —
113
+ * that displacement is why it cannot simply stay in place — and offset inline to
114
+ * track the viewport's leading edge, which is what `position: sticky` would have
115
+ * done for it had it still had a flow box nearby.
116
+ *
117
+ * It stays in the keyed `{#each}` rather than moving to an element of its own:
118
+ * Svelte cannot carry identity across that boundary, so a row with local state or
119
+ * a focused control would be destroyed and rebuilt every time it crossed.
120
+ *
121
+ * Both attributes are in the selector on purpose. A pinned row is always also the
122
+ * active one, so the sticky rule below matches it too — and carrying two attributes
123
+ * to that rule's one settles the cascade on specificity rather than on which is
124
+ * written first, which is how `position: sticky` quietly took this back once.
125
+ *
126
+ * It stays above the rows sliding under it by the `z-index: 1` the active rule
127
+ * supplies — a pinned row is always also the active one — rather than by DOM order.
128
+ * That combination is what the primitive-composition record describes.
129
+ */
130
+ .cinder-virtual-list__row[data-cinder-sticky='true'][data-cinder-sticky-pinned='true'] {
131
+ position: absolute;
132
+ inset-inline: 0;
133
+ }
134
+
135
+ /*
136
+ * Only the start edge, deliberately not `inset-block: 0`. Pinning both edges sizes
137
+ * the row to the window's block-size — which, now that the row is out of flow, is
138
+ * computed from the OTHER rows. A sticky row taller than its neighbours was squashed
139
+ * to their height and its content clipped, at the moment it crossed the window
140
+ * boundary and became pinned. Anchoring one edge leaves its own height alone.
141
+ */
142
+ .cinder-virtual-list[data-cinder-orientation='horizontal']
143
+ .cinder-virtual-list__row[data-cinder-sticky='true'][data-cinder-sticky-pinned='true'] {
144
+ inset-inline: auto;
145
+ inset-block-start: 0;
146
+ }
147
+
148
+ /*
149
+ * Only the ACTIVE row is held at the leading edge, and only it is raised.
150
+ *
151
+ * `z-index` was on every sticky row, on the reasoning that it is inert unless the
152
+ * element is positioned. That is true in block layout and false here: under
153
+ * `horizontal` the window is a flex container, and `z-index` applies to flex items
154
+ * whether or not they are positioned. An inactive header approaching the edge
155
+ * therefore entered the same stacking level as the held one and, being later in DOM
156
+ * order, painted straight over it — before it had become active.
157
+ *
158
+ * The pinned row is covered by this rule too, since it is always also the active
159
+ * one, and it is the `z-index` here that keeps it above the rows sliding under it
160
+ * rather than DOM order — which is what leaves the element free to sit in index
161
+ * order for assistive technology. Sticking every sticky row in
162
+ * the window put each header the reader had already passed at the same inset,
163
+ * stacked on top of one another — and a taller earlier header protruded below the
164
+ * current one, with anything focusable inside it still reachable while obscured.
165
+ * The overscanned window can hold several headers at once, so this is not rare.
166
+ *
167
+ * Offsets are relative to the scroll container, which is the element that scrolls,
168
+ * so the inset is 0 on the axis being scrolled.
169
+ */
170
+ .cinder-virtual-list__row[data-cinder-sticky-active='true'] {
171
+ position: sticky;
172
+ inset-block-start: 0;
173
+ z-index: 1;
174
+ }
175
+
176
+ .cinder-virtual-list[data-cinder-orientation='horizontal']
177
+ .cinder-virtual-list__row[data-cinder-sticky-active='true'] {
178
+ inset-block-start: auto;
179
+ inset-inline-start: 0;
180
+ }
30
181
  }
@@ -3,6 +3,48 @@
3
3
  "component": "virtual-list",
4
4
  "import": "@lostgradient/cinder/virtual-list",
5
5
  "examples": [
6
+ {
7
+ "id": "dynamic-sizing",
8
+ "title": "Variable-height rows with dynamicSize",
9
+ "description": "A 5,000 message transcript whose rows wrap to different heights. itemHeight is only the starting estimate; each row is measured once as it mounts and the scroll position is corrected so the viewport never jumps.",
10
+ "code": "<script lang=\"ts\">\n import { VirtualList } from '@lostgradient/cinder/virtual-list';\n\n type Message = {\n id: string;\n author: string;\n body: string;\n };\n\n const authors = ['ada', 'grace', 'alan', 'katherine', 'barbara'];\n\n // Deliberately uneven bodies: a fixed itemHeight cannot describe this list,\n // which is exactly the case dynamicSize exists for.\n const messages: Message[] = Array.from({ length: 5_000 }, (_, index) => ({\n id: `message-${index}`,\n author: authors[index % authors.length] ?? 'ada',\n body: `Message ${index.toLocaleString('en-US')}. ${'This sentence repeats to make the row wrap onto more lines. '.repeat((index % 5) + 1)}`,\n }));\n</script>\n\n<VirtualList\n items={messages}\n itemHeight={64}\n dynamicSize\n height=\"360px\"\n getKey={(message) => message.id}\n aria-label=\"Transcript\"\n>\n {#snippet row(message, context)}\n <div\n style=\"display: grid; grid-template-columns: 6rem minmax(0, 1fr); gap: 0.75rem; padding-block: 0.5rem; padding-inline: 0.75rem; border-block-end: 1px solid var(--cinder-border-muted); font-size: var(--cinder-text-sm);\"\n data-index={context.index}\n >\n <strong style=\"color: var(--cinder-text-muted);\">{message.author}</strong>\n <p style=\"margin: 0;\">{message.body}</p>\n </div>\n {/snippet}\n</VirtualList>\n"
11
+ },
12
+ {
13
+ "id": "horizontal-rtl",
14
+ "title": "Horizontal virtual list (RTL)",
15
+ "description": "The same horizontal windowing as the horizontal example, wrapped in a dir=\"rtl\" ancestor with Arabic row content. The component resolves a right-to-left writing direction from that ancestor and reads its scroll offset from the right edge of the container instead of the left.",
16
+ "code": "<script lang=\"ts\">\n import { VirtualList } from '@lostgradient/cinder/virtual-list';\n\n type Column = {\n id: string;\n label: string;\n };\n\n const columnWidth = 160;\n\n const columns: Column[] = Array.from({ length: 3_000 }, (_, index) => ({\n id: `column-${index}`,\n label: `عمود رقم ${index.toLocaleString('ar-EG')}`,\n }));\n</script>\n\n<div dir=\"rtl\">\n <VirtualList\n items={columns}\n itemHeight={columnWidth}\n horizontal\n height=\"480px\"\n overscan={4}\n getKey={(column) => column.id}\n aria-label=\"أعمدة قابلة للتمرير أفقيًا\"\n >\n {#snippet row(column, context)}\n <div\n style={`display: flex; flex-direction: column; align-items: center; justify-content: center; gap: 0.25rem; inline-size: ${columnWidth}px; block-size: 12rem; border-inline-end: 1px solid var(--cinder-border); font-size: var(--cinder-text-sm);`}\n data-index={context.index}\n >\n <strong>{column.label}</strong>\n <span style=\"color: var(--cinder-text-muted);\">الفهرس {context.index}</span>\n </div>\n {/snippet}\n </VirtualList>\n</div>\n"
17
+ },
18
+ {
19
+ "id": "horizontal-sticky-headers",
20
+ "title": "Horizontal sticky headers",
21
+ "description": "stickyItems along the inline axis. The pinned header holds at the leading edge exactly as it does vertically, and the list takes over the arrow keys — which are exchanged under a right-to-left writing direction, because KeyboardEvent.key is not remapped by dir.",
22
+ "code": "<script lang=\"ts\">\n import { VirtualList } from '@lostgradient/cinder/virtual-list';\n\n type Column = {\n id: string;\n label: string;\n isHeader: boolean;\n };\n\n const groupSize = 10;\n\n const columns: Column[] = Array.from({ length: 300 }, (_, index) => {\n const isHeader = index % groupSize === 0;\n return {\n id: `column-${index}`,\n label: isHeader ? `Group ${Math.floor(index / groupSize)}` : `Column ${index}`,\n isHeader,\n };\n });\n\n const stickyItems = columns.flatMap((column, index) => (column.isHeader ? [index] : []));\n</script>\n\n<VirtualList\n items={columns}\n itemHeight={120}\n height=\"720px\"\n horizontal\n {stickyItems}\n getKey={(column) => column.id}\n aria-label=\"Grouped columns with sticky headers\"\n>\n {#snippet row(item, context)}\n <div\n style={item.isHeader\n ? 'display: flex; align-items: center; justify-content: center; inline-size: 120px; block-size: 96px; padding-inline: 0.75rem; background: var(--cinder-surface-raised); font-weight: 600; border-inline-end: 1px solid var(--cinder-border);'\n : 'display: flex; align-items: center; justify-content: center; inline-size: 120px; block-size: 64px; padding-inline: 0.75rem; border-inline-end: 1px solid var(--cinder-border);'}\n data-index={context.index}\n >\n <span>{item.label}</span>\n </div>\n {/snippet}\n</VirtualList>\n"
23
+ },
24
+ {
25
+ "id": "horizontal",
26
+ "title": "Horizontal virtual list",
27
+ "description": "A native horizontally-scrolling container windowing 4,000 columns. When horizontal is set, itemHeight becomes each column's width in pixels and height becomes the container's inline-size instead of its block-size.",
28
+ "code": "<script lang=\"ts\">\n import { VirtualList } from '@lostgradient/cinder/virtual-list';\n\n type Column = {\n id: string;\n label: string;\n };\n\n const columnWidth = 160;\n\n const columns: Column[] = Array.from({ length: 4_000 }, (_, index) => ({\n id: `column-${index}`,\n label: `Column ${index.toLocaleString('en-US')}`,\n }));\n</script>\n\n<VirtualList\n items={columns}\n itemHeight={columnWidth}\n horizontal\n height=\"480px\"\n overscan={4}\n getKey={(column) => column.id}\n aria-label=\"Horizontally scrolling columns\"\n>\n {#snippet row(column, context)}\n <div\n style={`display: flex; flex-direction: column; align-items: center; justify-content: center; gap: 0.25rem; inline-size: ${columnWidth}px; block-size: 12rem; border-inline-end: 1px solid var(--cinder-border); font-size: var(--cinder-text-sm);`}\n data-index={context.index}\n >\n <strong>{column.label}</strong>\n <span style=\"color: var(--cinder-text-muted);\">index {context.index}</span>\n </div>\n {/snippet}\n</VirtualList>\n"
29
+ },
30
+ {
31
+ "id": "infinite-scroll",
32
+ "title": "Bi-directional infinite scroll",
33
+ "description": "onEndReached and onStartReached fire as the reader comes within overscan items of either edge. Each fires once per approach and re-arms when the item count changes, so a source that returns nothing does not spin.",
34
+ "code": "<script lang=\"ts\">\n import { VirtualList } from '@lostgradient/cinder/virtual-list';\n\n type Row = {\n id: number;\n label: string;\n };\n\n const pageSize = 50;\n\n let firstId = $state(0);\n let lastId = $state(100);\n let endLoads = $state(0);\n let startLoads = $state(0);\n\n let rows = $state<Row[]>(\n Array.from({ length: 100 }, (_, index) => ({\n id: index,\n label: `Row ${index}`,\n })),\n );\n\n function loadNewer() {\n endLoads += 1;\n const appended = Array.from({ length: pageSize }, (_, offset) => {\n const id = lastId + offset;\n return { id, label: `Row ${id}` };\n });\n lastId += pageSize;\n rows = [...rows, ...appended];\n }\n\n function loadOlder() {\n startLoads += 1;\n const prepended = Array.from({ length: pageSize }, (_, offset) => {\n const id = firstId - pageSize + offset;\n return { id, label: `Row ${id}` };\n });\n firstId -= pageSize;\n rows = [...prepended, ...rows];\n }\n</script>\n\n<div style=\"display: flex; flex-direction: column; gap: 0.75rem;\">\n <p style=\"color: var(--cinder-text-muted); font-size: var(--cinder-text-sm);\">\n {rows.length} rows loaded · {startLoads} older pages · {endLoads} newer pages\n </p>\n\n <VirtualList\n items={rows}\n itemHeight={40}\n height=\"320px\"\n overscan={5}\n onEndReached={loadNewer}\n onStartReached={loadOlder}\n getKey={(item) => item.id}\n aria-label=\"Infinitely scrolling feed\"\n >\n {#snippet row(item, context)}\n <div\n style=\"display: flex; align-items: center; gap: 0.75rem; block-size: 40px; padding-inline: 0.75rem; border-block-end: 1px solid var(--cinder-border);\"\n data-index={context.index}\n >\n <span>{item.label}</span>\n </div>\n {/snippet}\n </VirtualList>\n</div>\n"
35
+ },
36
+ {
37
+ "id": "reverse-transcript",
38
+ "title": "Reverse (chat transcript)",
39
+ "description": "A transcript that opens at its newest message and returns there whenever one arrives, however far the reader has scrolled back. Items stay in natural order — reverse names the anchoring, not the ordering. Prepending older history leaves the reader exactly where they were.",
40
+ "code": "<script lang=\"ts\">\n import { Button } from '@lostgradient/cinder/button';\n import { VirtualList } from '@lostgradient/cinder/virtual-list';\n\n type Message = {\n id: string;\n author: string;\n body: string;\n };\n\n const authors = ['ada', 'grace', 'alan', 'katherine', 'barbara'];\n\n let nextId = $state(400);\n let oldestId = $state(0);\n\n let messages = $state<Message[]>(\n Array.from({ length: 400 }, (_, index) => ({\n id: `message-${index}`,\n author: authors[index % authors.length] ?? 'ada',\n body: `Message ${index}. ${'This line repeats to give the row some height. '.repeat((index % 3) + 1)}`,\n })),\n );\n\n function appendMessage() {\n const index = nextId;\n nextId += 1;\n messages = [\n ...messages,\n {\n id: `message-${index}`,\n author: authors[index % authors.length] ?? 'ada',\n body: `Message ${index}. Just arrived — the transcript returns to the newest row.`,\n },\n ];\n }\n\n function prependHistory() {\n const older = Array.from({ length: 20 }, (_, offset) => {\n const index = oldestId - 20 + offset;\n return {\n id: `message-${index}`,\n author: authors[((index % authors.length) + authors.length) % authors.length] ?? 'ada',\n body: `Message ${index}. Older history, loaded above without moving the reader.`,\n };\n });\n oldestId -= 20;\n messages = [...older, ...messages];\n }\n</script>\n\n<div style=\"display: flex; flex-direction: column; gap: 0.75rem;\">\n <div style=\"display: flex; gap: 0.5rem;\">\n <Button variant=\"secondary\" onclick={prependHistory}>Load older history</Button>\n <Button onclick={appendMessage}>New message</Button>\n </div>\n\n <VirtualList\n items={messages}\n itemHeight={64}\n dynamicSize\n reverse\n height=\"320px\"\n getKey={(message) => message.id}\n aria-label=\"Chat transcript\"\n >\n {#snippet row(message, context)}\n <div\n style=\"display: flex; gap: 0.75rem; padding: 0.5rem 0.75rem; border-block-end: 1px solid var(--cinder-border);\"\n data-index={context.index}\n >\n <strong style=\"min-inline-size: 6rem;\">{message.author}</strong>\n <span>{message.body}</span>\n </div>\n {/snippet}\n </VirtualList>\n</div>\n"
41
+ },
42
+ {
43
+ "id": "sticky-headers",
44
+ "title": "Sticky section headers",
45
+ "description": "stickyItems names the indexes that pin to the leading edge while the reader scrolls past them. A sticky row stays mounted after its own index leaves the rendered window, which is the part plain virtualization would otherwise break: the heading would vanish exactly when it is meant to be pinned.",
46
+ "code": "<script lang=\"ts\">\n import { VirtualList } from '@lostgradient/cinder/virtual-list';\n\n type Row = {\n id: string;\n label: string;\n isHeader: boolean;\n };\n\n const sectionSize = 25;\n\n const rows: Row[] = Array.from({ length: 500 }, (_, index) => {\n const isHeader = index % sectionSize === 0;\n return {\n id: `row-${index}`,\n label: isHeader ? `Section ${Math.floor(index / sectionSize)}` : `Item ${index}`,\n isHeader,\n };\n });\n\n const stickyItems = rows.flatMap((row, index) => (row.isHeader ? [index] : []));\n</script>\n\n<VirtualList\n items={rows}\n itemHeight={36}\n height=\"360px\"\n {stickyItems}\n getKey={(row) => row.id}\n aria-label=\"Grouped list with sticky headers\"\n>\n {#snippet row(item, context)}\n <div\n style={item.isHeader\n ? 'display: flex; align-items: center; block-size: 36px; padding-inline: 0.75rem; background: var(--cinder-surface-raised); font-weight: 600; border-block-end: 1px solid var(--cinder-border);'\n : 'display: flex; align-items: center; block-size: 36px; padding-inline: 1.5rem; border-block-end: 1px solid var(--cinder-border);'}\n data-index={context.index}\n >\n <span>{item.label}</span>\n </div>\n {/snippet}\n</VirtualList>\n"
47
+ },
6
48
  {
7
49
  "id": "ten-thousand",
8
50
  "title": "10,000 item virtual list",
@@ -4,7 +4,15 @@
4
4
  "properties": {
5
5
  "itemHeight": {
6
6
  "type": "number",
7
- "description": "Fixed row height in pixels. Variable and measured row heights are out of\nscope for v1; pass the known or estimated fixed height for every row."
7
+ "description": "Each item's extent in pixels along the axis being scrolled: its height by\ndefault, or its width under `horizontal`. By default every row is assumed to\nbe exactly this size. When `dynamicSize` is true this becomes the initial\nestimate for rows that have not been measured yet."
8
+ },
9
+ "dynamicSize": {
10
+ "type": "boolean",
11
+ "description": "Measure each rendered row with `ResizeObserver` and cache the result,\ninstead of assuming every row is exactly `itemHeight` along the scrolled\naxis. Use this when rows wrap, contain images, or otherwise vary in size.\nComposes with `horizontal`, where each row is measured by its width.\n\nDefaults to `false`. While false, no row is measured, no size is cached,\nand no scroll correction runs — the fixed-height path stays the fast path.\nThe component still observes its own scroll container to track viewport\nsize, as it always has; that is independent of this prop."
12
+ },
13
+ "horizontal": {
14
+ "type": "boolean",
15
+ "description": "Scrolls and lays rows out along the inline axis instead of the block axis.\n\n`itemHeight` and `height` are REINTERPRETED rather than renamed: `itemHeight`\nbecomes each item's width in pixels along the main axis, and `height` becomes\nthe container's inline-size. The `--cinder-virtual-list-height` custom property\nkeeps its name too and switches to driving `inline-size`, so an existing theme\noverride keeps working when this is turned on.\n\nRight-to-left is handled: the writing direction is resolved from the container's\ncomputed style at mount, and the scroll offset is read from the start (right)\nedge in that case.\n\nDefaults to false."
8
16
  },
9
17
  "overscan": {
10
18
  "type": "number",
@@ -12,12 +20,39 @@
12
20
  },
13
21
  "height": {
14
22
  "type": "string",
15
- "description": "CSS block-size for the native scroll container.\nDefaults to `\"20rem\"`."
23
+ "description": "CSS extent of the native scroll container across the axis it scrolls: its\nblock-size by default, or its inline-size under `horizontal`.\nDefaults to `\"20rem\"`."
16
24
  },
17
25
  "stickToBottom": {
18
26
  "type": "boolean",
19
27
  "description": "When true, appending items while the viewport is already at the bottom\nkeeps the newest item pinned in view. Appending while scrolled up leaves the\nscroll position unchanged."
20
28
  },
29
+ "reverse": {
30
+ "type": "boolean",
31
+ "description": "Chat-transcript behaviour: the list starts at its end and returns there on\nevery append.\n\nItems stay in their natural order — oldest at index 0, newest last. `reverse`\nnames the anchoring, not the ordering, and the array is never flipped.\n\nDeliberately distinct from `stickToBottom`, which pins only when the reader is\nalready at the bottom. `reverse` pins on every append regardless of where the\nreader is. When both are set, `reverse` wins.\n\nPrepending — loading a page of older history — never moves the reader: the row\nthey were looking at stays put while the list grows above it.\n\nThat last guarantee REQUIRES `getKey`. Telling a prepend from an append means\ncomparing key sequences, and without `getKey` the keys are array indexes: a\nprepend turns `[0, 1, 2]` into `[0, 1, 2, 3, 4]`, which is indistinguishable\nfrom an append and pins the reader to the end instead of holding their place.\nPass `getKey` whenever the list can grow at the front.\n\nDefaults to false."
32
+ },
33
+ "scrollRestoration": {
34
+ "type": "boolean",
35
+ "description": "Remember the scroll position across navigation, keyed by\n`scrollRestorationId`.\n\nThe position is written to `sessionStorage` when the list tears down, and read\nback when it mounts. Deliberately not on every scroll: that would mean a\nstorage write per frame during a fling, and teardown is the last moment the\nposition is knowable anyway. The consequence is that a tab closed by a crash,\nrather than by navigating away, will not have saved.\n\nStorage failures are swallowed: a browser in private mode or at its quota throws\non write — and on read — and losing a remembered offset must not break the list.\n\nHas no effect without a `scrollRestorationId` — see that prop for why.\n\nExplicitly `| undefined`, like the other conditionally-supplied props: this\npackage compiles with `exactOptionalPropertyTypes`, under which optional and\nundefined-valued differ, and `scrollRestoration={enabled ? true : undefined}`\nwould otherwise fail to typecheck.\n\nDefaults to false."
36
+ },
37
+ "stickyItems": {
38
+ "type": "array",
39
+ "items": {
40
+ "type": "number"
41
+ },
42
+ "description": "Item indexes that stay visible at the leading edge while the reader scrolls\npast them — section headers in a grouped list, most often.\n\nA sticky row is kept mounted even after its own index leaves the rendered\nwindow, which is the part virtualization would otherwise break: unmounting it\nwould make the heading vanish exactly when it is meant to be pinned.\n\nIndexes outside the list, duplicates, and non-integers are dropped rather than\nthrowing — a bad sticky index is a cosmetic problem, not a correctness one."
43
+ },
44
+ "smoothScroll": {
45
+ "type": "boolean",
46
+ "description": "Animate `scrollToIndex` by default instead of jumping.\n\nEquivalent to passing `behavior: 'smooth'` on every call; an explicit\n`behavior` in the call's options still wins. Scroll corrections under\n`dynamicSize` are never animated whatever this is set to — a smooth\ncorrection would visibly perform the jump it exists to hide.\n\nDefaults to false."
47
+ },
48
+ "adaptiveOverscan": {
49
+ "type": "boolean",
50
+ "description": "Grow `overscan` while the reader is scrolling fast, and shrink it back when\nthey slow down.\n\n`overscan` becomes a floor rather than a fixed value: a fast fling renders\nfurther ahead to cut pop-in, and a stationary list falls back to exactly what\nwas configured so the DOM stays small. The growth is bounded, because an\nunbounded overscan during a fling would mount thousands of rows and defeat the\npoint of virtualizing at all.\n\nDefaults to false."
51
+ },
52
+ "scrollRestorationId": {
53
+ "type": "string",
54
+ "description": "Stable id under which `scrollRestoration` saves this list's position.\n\nRequired for restoration to do anything. There is deliberately no default:\nan implicit key derived from position or order would silently hand one\nlist's remembered offset to a different list after a refactor, and two lists\non one page would overwrite each other. Choose something tied to what the\nlist shows, such as a route or collection name."
55
+ },
21
56
  "tabindex": {
22
57
  "type": "number",
23
58
  "description": "Override the default focus behavior. The component sets `tabindex=\"0\"`\nby default so keyboard users can reach the native scroll container for\narrow-key scrolling. Pass `tabindex={-1}` when the viewport should be\nprogrammatically focusable without entering the tab order."
@@ -34,7 +69,7 @@
34
69
  {
35
70
  "name": "getKey",
36
71
  "reason": "function-or-snippet",
37
- "description": "Stable key extractor. Omit only when items are append-only and never\nreordered; the component will fall back to full-array indexes."
72
+ "description": "Stable key extractor. Omit only when items are append-only and never\nreordered; the component will fall back to full-array indexes.\n\nRequired in practice under `dynamicSize`: measured sizes are cached by key,\nso index-derived keys will mis-attribute cached sizes if items ever reorder."
38
73
  },
39
74
  {
40
75
  "name": "items",
@@ -42,6 +77,21 @@
42
77
  "required": true,
43
78
  "description": "Items in full logical order. Only the visible window is mounted."
44
79
  },
80
+ {
81
+ "name": "onEndReached",
82
+ "reason": "function-or-snippet",
83
+ "description": "Called when the reader scrolls within `overscan` items of the end of the list.\n\nExplicitly `| undefined` rather than merely optional: this package compiles with\n`exactOptionalPropertyTypes`, under which the two differ, and a consumer writing\n`onEndReached={enabled ? load : undefined}` would otherwise fail to typecheck.\n\nFires once per approach, not once per scroll event, and re-arms when the item\ncount changes — so appending in response to it allows the next approach to fire\nwhile a source that returns nothing does not spin."
84
+ },
85
+ {
86
+ "name": "onStartReached",
87
+ "reason": "function-or-snippet",
88
+ "description": "Called when the reader scrolls within `overscan` items of the start of the\nlist. Pair with `onEndReached` for bi-directional infinite scroll.\n\nLatched the same way as `onEndReached`. Prepending in response preserves the\nreader's position rather than jumping to the new start — but only with `getKey`,\nsince index-derived keys make a prepend look exactly like an append."
89
+ },
90
+ {
91
+ "name": "ref",
92
+ "reason": "unknown-shape",
93
+ "description": "Typed programmatic handle. Use `bind:ref` to receive it."
94
+ },
45
95
  {
46
96
  "name": "row",
47
97
  "reason": "function-or-snippet",