@lostgradient/cinder 0.25.1 → 0.26.1

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 (285) hide show
  1. package/CHANGELOG.md +237 -0
  2. package/components.json +13 -6
  3. package/dist/components/alert-dialog/index.js +2 -2
  4. package/dist/components/approval-card/index.js +2 -2
  5. package/dist/components/area-chart/area-chart.css +23 -0
  6. package/dist/components/area-chart/index.js +2 -2
  7. package/dist/components/autocomplete/index.js +2 -2
  8. package/dist/components/avatar-group/index.js +2 -2
  9. package/dist/components/backdrop/index.js +2 -2
  10. package/dist/components/bar-chart/bar-chart.css +23 -0
  11. package/dist/components/bar-chart/index.js +2 -2
  12. package/dist/components/button/button.css +1 -1
  13. package/dist/components/checkbox/index.js +2 -2
  14. package/dist/components/code-block/index.js +2 -2
  15. package/dist/components/color-field/index.js +2 -2
  16. package/dist/components/combobox/index.js +2 -2
  17. package/dist/components/command-menu/index.js +2 -2
  18. package/dist/components/command-palette/command-palette.css +50 -46
  19. package/dist/components/command-palette/index.js +2 -2
  20. package/dist/components/confirm-dialog/index.js +2 -2
  21. package/dist/components/context-menu/index.js +2 -2
  22. package/dist/components/data-table/index.js +2 -2
  23. package/dist/components/date-picker/index.js +2 -2
  24. package/dist/components/date-range-field/index.js +2 -2
  25. package/dist/components/drawer/index.js +2 -2
  26. package/dist/components/dropdown/index.js +2 -2
  27. package/dist/components/dropdown-menu/index.js +2 -2
  28. package/dist/components/find-bar/find-bar.css +9 -1
  29. package/dist/components/focus-trap/index.js +2 -2
  30. package/dist/components/form-field/index.js +2 -2
  31. package/dist/components/guidance-region/index.css +1 -1
  32. package/dist/components/hover-card/index.js +2 -2
  33. package/dist/components/inline-confirm/index.js +2 -2
  34. package/dist/components/input/index.js +2 -2
  35. package/dist/components/input/input.css +95 -6
  36. package/dist/components/invocation-rule-builder/index.js +2 -2
  37. package/dist/components/json-editor/index.js +2 -2
  38. package/dist/components/json-schema-editor/index.js +4 -4
  39. package/dist/components/key-value-editor/index.css +1 -1
  40. package/dist/components/line-chart/index.js +2 -2
  41. package/dist/components/line-chart/line-chart.css +23 -0
  42. package/dist/components/matrix-chart/index.js +2 -2
  43. package/dist/components/mega-menu/mega-menu.css +7 -1
  44. package/dist/components/menu-bar/index.js +3 -3
  45. package/dist/components/modal/index.js +2 -2
  46. package/dist/components/modal-region/index.css +1 -1
  47. package/dist/components/multi-select/index.js +2 -2
  48. package/dist/components/navigation-bar/index.js +2 -2
  49. package/dist/components/parameter-field/index.js +2 -2
  50. package/dist/components/parameter-field/parameter-field.css +7 -1
  51. package/dist/components/permission-matrix/index.js +2 -2
  52. package/dist/components/policy-lock/index.js +2 -2
  53. package/dist/components/popover/index.js +2 -2
  54. package/dist/components/popover/popover.css +86 -0
  55. package/dist/components/radio-group/index.js +2 -2
  56. package/dist/components/resizable-panels/resizable-panels.css +10 -7
  57. package/dist/components/schedule-builder/index.js +2 -2
  58. package/dist/components/schema-form/index.js +2 -2
  59. package/dist/components/scroll-area/index.js +2 -2
  60. package/dist/components/select/index.js +2 -2
  61. package/dist/components/select/select.css +12 -2
  62. package/dist/components/selection-popover/index.js +2 -2
  63. package/dist/components/share-card/index.js +2 -2
  64. package/dist/components/sidebar/index.js +2 -2
  65. package/dist/components/slider/slider.css +7 -1
  66. package/dist/components/sortable-list/sortable-list.css +11 -7
  67. package/dist/components/speed-dial/index.js +2 -2
  68. package/dist/components/statistic-group/index.js +2 -2
  69. package/dist/components/statistic-group/statistic-group.css +116 -66
  70. package/dist/components/table/index.js +2 -2
  71. package/dist/components/textarea/index.js +2 -2
  72. package/dist/components/time-field/index.js +2 -2
  73. package/dist/components/time-field/time-field.css +9 -8
  74. package/dist/components/toast-region/index.js +2 -2
  75. package/dist/components/tooltip/index.js +2 -2
  76. package/dist/components/transfer-list/index.js +2 -2
  77. package/dist/components/virtual-list/_internal/adaptive-overscan.d.ts +87 -0
  78. package/dist/components/virtual-list/_internal/edge-proximity.d.ts +75 -0
  79. package/dist/components/virtual-list/_internal/frame-scheduler.d.ts +76 -0
  80. package/dist/components/virtual-list/_internal/geometry.d.ts +170 -0
  81. package/dist/components/virtual-list/_internal/list-semantics.d.ts +93 -0
  82. package/dist/components/virtual-list/_internal/measurement-window.d.ts +125 -0
  83. package/dist/components/virtual-list/_internal/reverse-order.d.ts +87 -0
  84. package/dist/components/virtual-list/_internal/scroll-restoration.d.ts +98 -0
  85. package/dist/components/virtual-list/_internal/sticky-items.d.ts +48 -0
  86. package/dist/components/virtual-list/_internal/virtual-list-measurement-store.svelte.d.ts +69 -0
  87. package/dist/components/virtual-list/index.d.ts +1 -1
  88. package/dist/components/virtual-list/index.js +2 -2
  89. package/dist/components/virtual-list/virtual-list.css +153 -0
  90. package/dist/components/virtual-list/virtual-list.schema.js +69 -6
  91. package/dist/components/virtual-list/virtual-list.svelte.d.ts +11 -8
  92. package/dist/components/virtual-list/virtual-list.types.d.ts +177 -4
  93. package/dist/index.browser.css +1 -1
  94. package/dist/index.d.ts +1 -1
  95. package/dist/index.js +18 -18
  96. package/dist/server/components/alert-dialog/index.js +1 -1
  97. package/dist/server/components/approval-card/index.js +1 -1
  98. package/dist/server/components/area-chart/index.js +1 -1
  99. package/dist/server/components/autocomplete/index.js +1 -1
  100. package/dist/server/components/avatar-group/index.js +1 -1
  101. package/dist/server/components/backdrop/index.js +1 -1
  102. package/dist/server/components/bar-chart/index.js +1 -1
  103. package/dist/server/components/checkbox/index.js +1 -1
  104. package/dist/server/components/code-block/index.js +1 -1
  105. package/dist/server/components/color-field/index.js +1 -1
  106. package/dist/server/components/combobox/index.js +1 -1
  107. package/dist/server/components/command-menu/index.js +1 -1
  108. package/dist/server/components/command-palette/index.js +2 -2
  109. package/dist/server/components/confirm-dialog/index.js +1 -1
  110. package/dist/server/components/context-menu/index.js +1 -1
  111. package/dist/server/components/data-table/index.js +1 -1
  112. package/dist/server/components/date-picker/index.js +1 -1
  113. package/dist/server/components/date-range-field/index.js +1 -1
  114. package/dist/server/components/drawer/index.js +1 -1
  115. package/dist/server/components/dropdown/index.js +1 -1
  116. package/dist/server/components/dropdown-menu/index.js +2 -2
  117. package/dist/server/components/focus-trap/index.js +1 -1
  118. package/dist/server/components/form-field/index.js +1 -1
  119. package/dist/server/components/hover-card/index.js +1 -1
  120. package/dist/server/components/inline-confirm/index.js +1 -1
  121. package/dist/server/components/input/index.js +1 -1
  122. package/dist/server/components/invocation-rule-builder/index.js +1 -1
  123. package/dist/server/components/json-editor/index.js +1 -1
  124. package/dist/server/components/json-schema-editor/index.js +1 -1
  125. package/dist/server/components/line-chart/index.js +1 -1
  126. package/dist/server/components/matrix-chart/index.js +1 -1
  127. package/dist/server/components/menu-bar/index.js +2 -2
  128. package/dist/server/components/modal/index.js +1 -1
  129. package/dist/server/components/multi-select/index.js +1 -1
  130. package/dist/server/components/navigation-bar/index.js +2 -2
  131. package/dist/server/components/parameter-field/index.js +1 -1
  132. package/dist/server/components/permission-matrix/index.js +1 -1
  133. package/dist/server/components/policy-lock/index.js +1 -1
  134. package/dist/server/components/popover/index.js +1 -1
  135. package/dist/server/components/radio-group/index.js +1 -1
  136. package/dist/server/components/schedule-builder/index.js +1 -1
  137. package/dist/server/components/schema-form/index.js +1 -1
  138. package/dist/server/components/scroll-area/index.js +1 -1
  139. package/dist/server/components/select/index.js +1 -1
  140. package/dist/server/components/selection-popover/index.js +1 -1
  141. package/dist/server/components/share-card/index.js +1 -1
  142. package/dist/server/components/sidebar/index.js +1 -1
  143. package/dist/server/components/speed-dial/index.js +2 -2
  144. package/dist/server/components/statistic-group/index.js +1 -1
  145. package/dist/server/components/table/index.js +1 -1
  146. package/dist/server/components/textarea/index.js +1 -1
  147. package/dist/server/components/time-field/index.js +1 -1
  148. package/dist/server/components/toast-region/index.js +1 -1
  149. package/dist/server/components/tooltip/index.js +1 -1
  150. package/dist/server/components/transfer-list/index.js +1 -1
  151. package/dist/server/components/virtual-list/index.js +2 -2
  152. package/dist/server/index.js +2 -2
  153. package/dist/server/{index.server-skq0f5sr.js → index.server-0jw25w9w.js} +1 -1
  154. package/dist/server/index.server-0kk20wvp.js +4 -0
  155. package/dist/server/{index.server-fzsqdajc.js → index.server-2awq6q9m.js} +1 -1
  156. package/dist/server/{index.server-e4hmhaeh.js → index.server-3xwvw6w2.js} +3 -3
  157. package/dist/server/{index.server-95h7xy01.js → index.server-428dh2t9.js} +2 -2
  158. package/dist/server/{index.server-jd88r74m.js → index.server-5dq66aja.js} +2 -2
  159. package/dist/server/{index.server-dvwfhf77.js → index.server-5s94r0kk.js} +2 -2
  160. package/dist/server/{index.server-qv6z5ta3.js → index.server-80qgcjnm.js} +1 -1
  161. package/dist/server/{index.server-7k2732ky.js → index.server-81abtrsw.js} +1 -1
  162. package/dist/server/{index.server-csmqnx5w.js → index.server-83q1gv2c.js} +1 -1
  163. package/dist/server/{index.server-qw8k9rjg.js → index.server-8fyav10d.js} +1 -1
  164. package/dist/server/{index.server-4dgjj4k1.js → index.server-8h5caecr.js} +2 -2
  165. package/dist/server/{index.server-emyqytmm.js → index.server-90n8sd9e.js} +1 -1
  166. package/dist/server/{index.server-0xrdyzvh.js → index.server-99penx1m.js} +1 -1
  167. package/dist/server/{index.server-p94j3jah.js → index.server-9g9d15z1.js} +1 -1
  168. package/dist/server/{index.server-xp9hkc81.js → index.server-9kbdx511.js} +1 -1
  169. package/dist/server/index.server-a2yhk45s.js +3 -0
  170. package/dist/server/{index.server-g8d2m2tk.js → index.server-acq55gjs.js} +1 -1
  171. package/dist/server/{index.server-ewze54tv.js → index.server-afjftjmr.js} +1 -1
  172. package/dist/server/{index.server-ejyye4gv.js → index.server-bfed6a8a.js} +1 -1
  173. package/dist/server/{index.server-z5ng08q2.js → index.server-c1746s0z.js} +1 -1
  174. package/dist/server/{index.server-gt1tfc1w.js → index.server-dmeztywe.js} +1 -1
  175. package/dist/server/{index.server-kzsppq0n.js → index.server-dyj3jdx9.js} +1 -1
  176. package/dist/server/index.server-dz92zvx6.js +4 -0
  177. package/dist/server/{index.server-3md8kdcr.js → index.server-e6682k08.js} +1 -1
  178. package/dist/server/{index.server-t1pshh65.js → index.server-ewkv461x.js} +1 -1
  179. package/dist/server/{index.server-zfgwhtmp.js → index.server-fa449wd3.js} +1 -1
  180. package/dist/server/{index.server-1kgwayct.js → index.server-fhfypmgw.js} +1 -1
  181. package/dist/server/{index.server-s4z8hsby.js → index.server-ge4adxs2.js} +1 -1
  182. package/dist/server/{index.server-68xyfsg3.js → index.server-gggkq22y.js} +2 -2
  183. package/dist/server/{index.server-acgwdamx.js → index.server-j52rbk57.js} +1 -1
  184. package/dist/server/{index.server-z0nwftx6.js → index.server-jm89hxfb.js} +1 -1
  185. package/dist/server/{index.server-xa98r8p2.js → index.server-jw0v64se.js} +1 -1
  186. package/dist/server/index.server-m321p69g.js +3 -0
  187. package/dist/server/{index.server-xyervw3d.js → index.server-m7q2tc41.js} +1 -1
  188. package/dist/server/{index.server-tnrxy86j.js → index.server-mak7dmj2.js} +1 -1
  189. package/dist/server/{index.server-n5g5h5k1.js → index.server-mw5r2524.js} +1 -1
  190. package/dist/server/{index.server-caf7s6m7.js → index.server-nwq1cg55.js} +1 -1
  191. package/dist/server/{index.server-3wdvs0wr.js → index.server-p423fy4q.js} +2 -2
  192. package/dist/server/{index.server-ks7fvwxt.js → index.server-prk5syj2.js} +1 -1
  193. package/dist/server/{index.server-6w9fp018.js → index.server-q4hytsq3.js} +1 -1
  194. package/dist/server/{index.server-5w2qw8fm.js → index.server-q597a1ck.js} +1 -1
  195. package/dist/server/{index.server-fz1pkvda.js → index.server-qgne9v2w.js} +1 -1
  196. package/dist/server/{index.server-1f2app32.js → index.server-rvdavf92.js} +1 -1
  197. package/dist/server/index.server-rwq20a22.js +3 -0
  198. package/dist/server/{index.server-0rvmnrw2.js → index.server-s9tjs45r.js} +1 -1
  199. package/dist/server/{index.server-cm2prec7.js → index.server-sqgxyfsw.js} +1 -1
  200. package/dist/server/{index.server-v6777tgn.js → index.server-t761nwvb.js} +1 -1
  201. package/dist/server/index.server-tbds8nwq.js +4 -0
  202. package/dist/server/index.server-tyhta5n3.js +3 -0
  203. package/dist/server/{index.server-yw7rah51.js → index.server-v5dxham4.js} +1 -1
  204. package/dist/server/index.server-va98cpyf.js +3 -0
  205. package/dist/server/index.server-vq1k69xt.js +3 -0
  206. package/dist/server/{index.server-egd355s6.js → index.server-wnf9btp7.js} +2 -2
  207. package/dist/server/{index.server-sjcbaztf.js → index.server-y3zgdtbv.js} +1 -1
  208. package/dist/server/{index.server-4tjtgzf9.js → index.server-y6vtbmyj.js} +1 -1
  209. package/dist/server/{index.server-2p2mjzzb.js → index.server-zff2qp1v.js} +1 -1
  210. package/dist/server/tokens/registry.generated.js +2 -2
  211. package/dist/tokens/registry.generated.js +2 -2
  212. package/package.json +2 -2
  213. package/src/_internal/form-field-frame.svelte +5 -0
  214. package/src/_internal/overlay.ts +14 -1
  215. package/src/components/_internal/create-command-list-state.svelte.ts +4 -0
  216. package/src/components/area-chart/area-chart.css +23 -0
  217. package/src/components/bar-chart/bar-chart.css +23 -0
  218. package/src/components/button/button.css +1 -1
  219. package/src/components/command-menu/command-menu.svelte +63 -7
  220. package/src/components/command-palette/command-palette.css +50 -46
  221. package/src/components/command-palette/command-palette.svelte +68 -78
  222. package/src/components/dropdown/dropdown.svelte +73 -18
  223. package/src/components/dropdown-menu/dropdown-menu.svelte +63 -7
  224. package/src/components/find-bar/find-bar.css +9 -1
  225. package/src/components/hover-card/hover-card.examples.json +11 -4
  226. package/src/components/input/input.css +95 -6
  227. package/src/components/input/input.svelte +44 -81
  228. package/src/components/line-chart/line-chart.css +23 -0
  229. package/src/components/mega-menu/mega-menu.css +7 -1
  230. package/src/components/menu-bar/menu-bar.svelte +12 -1
  231. package/src/components/multi-select/multi-select.svelte +7 -0
  232. package/src/components/navigation-bar/navigation-bar.svelte +82 -6
  233. package/src/components/parameter-field/parameter-field.css +7 -1
  234. package/src/components/popover/popover.css +86 -0
  235. package/src/components/resizable-panels/resizable-panels.css +10 -7
  236. package/src/components/select/select.css +12 -2
  237. package/src/components/selection-popover/selection-popover.svelte +24 -10
  238. package/src/components/share-card/share-card.svelte +24 -44
  239. package/src/components/slider/slider.css +7 -1
  240. package/src/components/sortable-list/sortable-list.css +11 -7
  241. package/src/components/speed-dial/speed-dial.svelte +23 -5
  242. package/src/components/statistic-group/statistic-group.css +116 -66
  243. package/src/components/statistic-group/statistic-group.examples.json +6 -0
  244. package/src/components/statistic-group/statistic-group.svelte +13 -1
  245. package/src/components/time-field/time-field.css +9 -8
  246. package/src/components/toast-region/toast-region.svelte +9 -0
  247. package/src/components/virtual-list/_internal/adaptive-overscan.ts +248 -0
  248. package/src/components/virtual-list/_internal/edge-proximity.ts +130 -0
  249. package/src/components/virtual-list/_internal/frame-scheduler.ts +136 -0
  250. package/src/components/virtual-list/_internal/geometry.ts +236 -0
  251. package/src/components/virtual-list/_internal/list-semantics.ts +151 -0
  252. package/src/components/virtual-list/_internal/measurement-window.ts +300 -0
  253. package/src/components/virtual-list/_internal/reverse-order.ts +146 -0
  254. package/src/components/virtual-list/_internal/scroll-restoration.ts +209 -0
  255. package/src/components/virtual-list/_internal/sticky-items.ts +111 -0
  256. package/src/components/virtual-list/_internal/virtual-list-measurement-store.svelte.ts +145 -0
  257. package/src/components/virtual-list/index.ts +7 -1
  258. package/src/components/virtual-list/virtual-list.css +153 -0
  259. package/src/components/virtual-list/virtual-list.examples.json +42 -0
  260. package/src/components/virtual-list/virtual-list.schema.json +53 -3
  261. package/src/components/virtual-list/virtual-list.schema.ts +64 -3
  262. package/src/components/virtual-list/virtual-list.svelte +1527 -36
  263. package/src/components/virtual-list/virtual-list.types.ts +181 -4
  264. package/src/index.ts +3 -0
  265. package/src/styles/tokens-base.css +29 -21
  266. package/src/tokens/cinder.resolver.json +8 -0
  267. package/src/tokens/index.json +1 -1
  268. package/src/tokens/registry.generated.json +29 -3
  269. package/src/tokens/registry.generated.ts +31 -3
  270. package/src/tokens/resolved/dark-reduced-motion.json +46 -16
  271. package/src/tokens/resolved/dark.json +46 -16
  272. package/src/tokens/resolved/light-reduced-motion.json +47 -17
  273. package/src/tokens/resolved/light.json +47 -17
  274. package/src/tokens/sets/semantic.tokens.json +120 -30
  275. package/src/tokens/themes/dark.tokens.json +115 -19
  276. package/src/tokens/themes/light.tokens.json +51 -3
  277. package/dist/server/index.server-191cnacw.js +0 -3
  278. package/dist/server/index.server-25dqx151.js +0 -3
  279. package/dist/server/index.server-77jyqvbv.js +0 -4
  280. package/dist/server/index.server-bgjrzr70.js +0 -3
  281. package/dist/server/index.server-khsp90vh.js +0 -3
  282. package/dist/server/index.server-ryk2pgbe.js +0 -4
  283. package/dist/server/index.server-tajr81bm.js +0 -3
  284. package/dist/server/index.server-vjzcrw3d.js +0 -4
  285. package/dist/server/index.server-zg3fx1n1.js +0 -3
@@ -1,32 +1,46 @@
1
1
  @layer cinder.tokens, cinder.foundation, cinder.components, cinder.utilities;
2
2
  @import '../statistic/statistic.css';
3
3
  @layer cinder.components {
4
+ /* The root is the query container; the grid is its child. An element can
5
+ never query itself -- a container query resolves against the nearest
6
+ ANCESTOR container -- so with `container-type` on the grid the collapse
7
+ rules below never fired for a standalone group (CIN-499). The container
8
+ sits on the public root, not on an extra wrapper around it, so the root
9
+ stays the element that receives a consumer's `class`, `style`, and
10
+ `...rest`: constraining the group's inline size constrains exactly what
11
+ the queries measure, and a group nested inside another group queries its
12
+ own width rather than the outer's (RESPONSIVE-POLICY.md).
13
+
14
+ A size query measures the container's CONTENT box. The `default` variant
15
+ pads its root, so its 30rem and 18rem thresholds are the width the cells
16
+ actually share, not the group's outer width. */
4
17
  .cinder-statistic-group {
5
- display: grid;
6
- gap: var(--cinder-statistic-group-gap, var(--cinder-space-4, 1rem));
7
- /* Query the group's own inline size so fixed column counts can collapse when
8
- the group is narrow — even inside a wide viewport (RESPONSIVE-POLICY.md). */
9
18
  container-type: inline-size;
10
19
  container-name: cinder-statistic-group;
11
20
  }
12
21
 
13
- .cinder-statistic-group[data-cinder-columns='auto'] {
22
+ .cinder-statistic-group__grid {
23
+ display: grid;
24
+ gap: var(--cinder-statistic-group-gap, var(--cinder-space-4, 1rem));
25
+ }
26
+
27
+ .cinder-statistic-group[data-cinder-columns='auto'] > .cinder-statistic-group__grid {
14
28
  grid-template-columns: repeat(auto-fit, minmax(min(16rem, 100%), 1fr));
15
29
  }
16
30
 
17
- .cinder-statistic-group[data-cinder-columns='1'] {
31
+ .cinder-statistic-group[data-cinder-columns='1'] > .cinder-statistic-group__grid {
18
32
  grid-template-columns: 1fr;
19
33
  }
20
34
 
21
- .cinder-statistic-group[data-cinder-columns='2'] {
35
+ .cinder-statistic-group[data-cinder-columns='2'] > .cinder-statistic-group__grid {
22
36
  grid-template-columns: repeat(2, minmax(0, 1fr));
23
37
  }
24
38
 
25
- .cinder-statistic-group[data-cinder-columns='3'] {
39
+ .cinder-statistic-group[data-cinder-columns='3'] > .cinder-statistic-group__grid {
26
40
  grid-template-columns: repeat(3, minmax(0, 1fr));
27
41
  }
28
42
 
29
- .cinder-statistic-group[data-cinder-columns='4'] {
43
+ .cinder-statistic-group[data-cinder-columns='4'] > .cinder-statistic-group__grid {
30
44
  grid-template-columns: repeat(4, minmax(0, 1fr));
31
45
  }
32
46
 
@@ -35,16 +49,16 @@
35
49
  under 18rem, so values never crush. The `auto` mode already self-collapses
36
50
  via auto-fit, so it is intentionally excluded. */
37
51
  @container cinder-statistic-group (max-width: 30rem) {
38
- .cinder-statistic-group[data-cinder-columns='3'],
39
- .cinder-statistic-group[data-cinder-columns='4'] {
52
+ .cinder-statistic-group[data-cinder-columns='3'] > .cinder-statistic-group__grid,
53
+ .cinder-statistic-group[data-cinder-columns='4'] > .cinder-statistic-group__grid {
40
54
  grid-template-columns: repeat(2, minmax(0, 1fr));
41
55
  }
42
56
  }
43
57
 
44
58
  @container cinder-statistic-group (max-width: 18rem) {
45
- .cinder-statistic-group[data-cinder-columns='2'],
46
- .cinder-statistic-group[data-cinder-columns='3'],
47
- .cinder-statistic-group[data-cinder-columns='4'] {
59
+ .cinder-statistic-group[data-cinder-columns='2'] > .cinder-statistic-group__grid,
60
+ .cinder-statistic-group[data-cinder-columns='3'] > .cinder-statistic-group__grid,
61
+ .cinder-statistic-group[data-cinder-columns='4'] > .cinder-statistic-group__grid {
48
62
  grid-template-columns: 1fr;
49
63
  }
50
64
  }
@@ -62,86 +76,119 @@
62
76
  * default-variant dividers
63
77
  *
64
78
  * A divider belongs BETWEEN two adjacent cells, so a divider rule is only correct
65
- * where the effective column count is knowable.
66
- *
67
- * For the fixed counts it is the declared count, at every width, for a STANDALONE
68
- * group. The collapse rules above (30rem, 18rem) look like they change that, but for
69
- * a standalone group they never fire: their subject is `.cinder-statistic-group`,
70
- * which is itself the named query container, and an element is never its own
71
- * container -- a container query resolves against the nearest ANCESTOR container.
72
- *
73
- * They are not universally inert, though: a group NESTED inside another
74
- * StatisticGroup does have an ancestor container, so there the collapse fires and
75
- * resolves against the OUTER group's width. See the note on the row-end rules below
76
- * for what that means for dividers. Either way this is a pre-existing layout defect,
77
- * tracked separately; fixing it needs a wrapper element so the group can query
78
- * something other than itself, which is a markup change this PR is not making.
79
- *
80
- * What matters here is that the dividers must describe the grid that actually
81
- * renders. An earlier revision of this block mirrored the collapse thresholds, so at
82
- * narrow widths it flipped to horizontal dividers while the grid was still showing
83
- * its full column count -- dividers drawn across a layout that had not changed. With
84
- * the thresholds gone, `nth-child(Nn)` needs no width bands at all.
79
+ * where the effective column count is knowable. For the fixed counts that is the
80
+ * declared count at wide widths, then the collapsed count under the same 30rem and
81
+ * 18rem thresholds the layout rules use above -- the dividers must describe the
82
+ * grid that actually renders, so they mirror those thresholds exactly.
85
83
  *
86
84
  * For `columns='auto'` the count is not knowable: `repeat(auto-fit, ...)` renders
87
85
  * however many 16rem tracks fit, without an upper bound, and CSS cannot select "the
88
- * last cell in a row" without that number. Enumerating width bands only moves the
89
- * failure outward -- a previous revision covered twelve columns and justified the cap
90
- * by claiming 203rem was past any real display, which is false. So `auto` carries no
91
- * per-cell dividers, keeping the variant's resting border, inset surface, and gap.
92
- * That is what makes `default` read as deliberate rather than unstyled (CIN-113); the
93
- * dividers are an enhancement applied where they can be drawn correctly.
86
+ * last cell in a row" without that number. So `auto` carries no per-cell dividers,
87
+ * keeping the variant's resting border, inset surface, and gap. That is what makes
88
+ * `default` read as deliberate rather than unstyled (CIN-113); the dividers are an
89
+ * enhancement applied where they can be drawn correctly.
94
90
  *
95
- * ORDER IS LOAD-BEARING. Every rule carries the same specificity, so source order
96
- * alone decides the cascade: the row-end and single-column resets must follow the
97
- * generic rule that turns `border-inline-end` on.
91
+ * SPECIFICITY IS LOAD-BEARING. Every enabler, row-end suppressor, and band rule
92
+ * in this section is written as
93
+ * `.cinder-statistic-group[data-cinder-variant='default'][data-cinder-columns='N']
94
+ * > .cinder-statistic-group__grid > .cinder-statistic:<one pseudo-class>` --
95
+ * exactly (0,6,0) -- so that among them source order alone decides the cascade
96
+ * and a later band can override an earlier one. The one exception is the
97
+ * final-cell reset at the end, which drops `[data-cinder-columns]` and is (0,5,0):
98
+ * it only ever matches `:last-child`, which every enabler excludes with
99
+ * `:not(:last-child)`, and the row-end suppressors that can also match the last
100
+ * cell set the same `none`, so it never competes with a higher-specificity rule.
101
+ * An earlier revision enabled dividers with ONE generic rule carrying two
102
+ * `:not([data-cinder-columns=...])` clauses, which out-ranked every row-end
103
+ * suppressor below it, so a multi-row group drew a divider at the end of every
104
+ * row but the last. Do not "simplify" the enablers back into one rule.
98
105
  * ---------------------------------------- */
99
106
 
100
- /* --- Fixed multi-column counts: vertical dividers --- */
107
+ /* --- Declared layout (wide): vertical dividers, row ends suppressed --- */
101
108
 
102
- .cinder-statistic-group[data-cinder-variant='default']:not([data-cinder-columns='1']):not(
103
- [data-cinder-columns='auto']
104
- )
109
+ .cinder-statistic-group[data-cinder-variant='default'][data-cinder-columns='2']
110
+ > .cinder-statistic-group__grid
111
+ > .cinder-statistic:not(:last-child),
112
+ .cinder-statistic-group[data-cinder-variant='default'][data-cinder-columns='3']
113
+ > .cinder-statistic-group__grid
114
+ > .cinder-statistic:not(:last-child),
115
+ .cinder-statistic-group[data-cinder-variant='default'][data-cinder-columns='4']
116
+ > .cinder-statistic-group__grid
105
117
  > .cinder-statistic:not(:last-child) {
106
118
  border-inline-end: 1px solid var(--cinder-border-muted);
107
119
  }
108
120
 
109
- /* Row ends: the last cell of each row has no neighbour to its right. No container
110
- query needed -- for a standalone group, a fixed count renders that many tracks at
111
- every width, because the collapse rules above never fire (see the note above).
112
-
113
- One case does diverge: a group nested INSIDE another StatisticGroup. The inner
114
- group still cannot query itself, but it now has an ancestor container, so the
115
- collapse rules DO resolve -- against the outer group's width. An inner
116
- `columns={3}` inside a 20rem outer group therefore renders two tracks while these
117
- rules still suppress every third divider. That is the same inert-collapse defect
118
- seen from the other side, and it cannot be fixed here: while the collapse fires for
119
- some groups and not others, no divider rule is correct for both. It resolves when
120
- the layout gets a wrapper element to query, tracked with that fix. */
121
121
  .cinder-statistic-group[data-cinder-variant='default'][data-cinder-columns='2']
122
+ > .cinder-statistic-group__grid
122
123
  > .cinder-statistic:nth-child(2n),
123
124
  .cinder-statistic-group[data-cinder-variant='default'][data-cinder-columns='3']
125
+ > .cinder-statistic-group__grid
124
126
  > .cinder-statistic:nth-child(3n),
125
127
  .cinder-statistic-group[data-cinder-variant='default'][data-cinder-columns='4']
128
+ > .cinder-statistic-group__grid
126
129
  > .cinder-statistic:nth-child(4n) {
127
130
  border-inline-end: none;
128
131
  }
129
132
 
130
- /* --- Single column: horizontal dividers --- */
133
+ /* --- Single column (declared): horizontal dividers --- */
131
134
 
132
135
  .cinder-statistic-group[data-cinder-variant='default'][data-cinder-columns='1']
136
+ > .cinder-statistic-group__grid
133
137
  > .cinder-statistic:not(:last-child) {
134
138
  border-block-end: 1px solid var(--cinder-border-muted);
135
139
  }
136
140
 
141
+ /* --- Collapsed to two tracks (<= 30rem): 3 and 4 behave as 2 --- */
142
+
143
+ @container cinder-statistic-group (max-width: 30rem) {
144
+ .cinder-statistic-group[data-cinder-variant='default'][data-cinder-columns='3']
145
+ > .cinder-statistic-group__grid
146
+ > .cinder-statistic:not(:last-child),
147
+ .cinder-statistic-group[data-cinder-variant='default'][data-cinder-columns='4']
148
+ > .cinder-statistic-group__grid
149
+ > .cinder-statistic:not(:last-child) {
150
+ border-inline-end: 1px solid var(--cinder-border-muted);
151
+ }
152
+
153
+ .cinder-statistic-group[data-cinder-variant='default'][data-cinder-columns='3']
154
+ > .cinder-statistic-group__grid
155
+ > .cinder-statistic:nth-child(2n),
156
+ .cinder-statistic-group[data-cinder-variant='default'][data-cinder-columns='4']
157
+ > .cinder-statistic-group__grid
158
+ > .cinder-statistic:nth-child(2n) {
159
+ border-inline-end: none;
160
+ }
161
+ }
162
+
163
+ /* --- Collapsed to one track (<= 18rem): 2, 3 and 4 behave as 1 --- */
164
+
165
+ @container cinder-statistic-group (max-width: 18rem) {
166
+ .cinder-statistic-group[data-cinder-variant='default'][data-cinder-columns='2']
167
+ > .cinder-statistic-group__grid
168
+ > .cinder-statistic:not(:last-child),
169
+ .cinder-statistic-group[data-cinder-variant='default'][data-cinder-columns='3']
170
+ > .cinder-statistic-group__grid
171
+ > .cinder-statistic:not(:last-child),
172
+ .cinder-statistic-group[data-cinder-variant='default'][data-cinder-columns='4']
173
+ > .cinder-statistic-group__grid
174
+ > .cinder-statistic:not(:last-child) {
175
+ border-inline-end: none;
176
+ border-block-end: 1px solid var(--cinder-border-muted);
177
+ }
178
+ }
179
+
137
180
  /* The final cell never has a neighbour in either axis, in any layout. */
138
- .cinder-statistic-group[data-cinder-variant='default'] > .cinder-statistic:last-child {
181
+ .cinder-statistic-group[data-cinder-variant='default']
182
+ > .cinder-statistic-group__grid
183
+ > .cinder-statistic:last-child {
139
184
  border-inline-end: none;
140
185
  border-block-end: none;
141
186
  }
142
187
 
143
188
  /* variant: cards — each stat gets a card-style border, background, and shadow */
144
- .cinder-statistic-group[data-cinder-variant='cards'] > .cinder-statistic {
189
+ .cinder-statistic-group[data-cinder-variant='cards']
190
+ > .cinder-statistic-group__grid
191
+ > .cinder-statistic {
145
192
  padding: var(--cinder-statistic-group-card-padding, var(--cinder-space-4, 1rem));
146
193
  background: var(--cinder-surface-raised);
147
194
  border: 1px solid var(--cinder-border);
@@ -150,9 +197,10 @@
150
197
  }
151
198
 
152
199
  /*
153
- * variant: shared-borders — outer border on the container; 1px gap filled by the
154
- * container background acts as the divider between cells. Children paint over the
155
- * gap with the surface color, avoiding nth-child math for any column count.
200
+ * variant: shared-borders — outer border on the root; the 1px grid gap is filled by
201
+ * the root's background and acts as the divider between cells (the grid element is
202
+ * transparent and inherits the gap token). Children paint over the gap with the
203
+ * surface color, avoiding nth-child math for any column count.
156
204
  */
157
205
  .cinder-statistic-group[data-cinder-variant='shared-borders'] {
158
206
  --cinder-statistic-group-gap: 1px;
@@ -162,7 +210,9 @@
162
210
  background: var(--cinder-border);
163
211
  }
164
212
 
165
- .cinder-statistic-group[data-cinder-variant='shared-borders'] > .cinder-statistic {
213
+ .cinder-statistic-group[data-cinder-variant='shared-borders']
214
+ > .cinder-statistic-group__grid
215
+ > .cinder-statistic {
166
216
  padding: var(--cinder-statistic-group-shared-cell-padding, var(--cinder-space-4, 1rem));
167
217
  background: var(--cinder-surface-raised);
168
218
  }
@@ -33,6 +33,12 @@
33
33
  "description": "A landing-page KPI band recipe: Container frames heading copy above StatisticGroup in the cards variant, with fully-worded change labels.",
34
34
  "code": "<script lang=\"ts\">\n import { Container } from '@lostgradient/cinder/container';\n import { StatisticGroup } from '@lostgradient/cinder/statistic-group';\n</script>\n\n<section style=\"padding-block: var(--cinder-space-10);\">\n <Container maxWidth=\"wide\">\n <div style=\"display: grid; gap: var(--cinder-space-6);\">\n <header style=\"display: grid; gap: var(--cinder-space-2); max-inline-size: 60ch;\">\n <h2 style=\"margin: 0;\">Outcomes teams achieve with Cinder</h2>\n <p style=\"margin: 0; color: var(--cinder-text-muted);\">\n Measured improvements after standardizing on shared UI patterns.\n </p>\n </header>\n\n <StatisticGroup label=\"Key metrics\" variant=\"cards\">\n <StatisticGroup.Statistic label=\"Uptime\" value=\"99.99%\" />\n <StatisticGroup.Statistic\n label=\"Deploys / month\"\n value={420}\n change={{\n value: '+18%',\n direction: 'up',\n description: 'vs last quarter',\n label: 'Up 18% versus last quarter',\n }}\n />\n <StatisticGroup.Statistic\n label=\"Mean time to ship\"\n value=\"2.4 days\"\n change={{\n value: '-11%',\n direction: 'down',\n description: 'vs last quarter',\n label: 'Down 11% versus last quarter',\n }}\n />\n </StatisticGroup>\n </div>\n </Container>\n</section>\n"
35
35
  },
36
+ {
37
+ "id": "multi-row",
38
+ "title": "Multi-row group",
39
+ "description": "More metrics than columns, so the grid wraps. The default variant draws a vertical divider between neighbours and suppresses it at the end of each row, and a fixed column count collapses as the group itself narrows.",
40
+ "code": "<script lang=\"ts\">\n import { StatisticGroup } from '@lostgradient/cinder/statistic-group';\n</script>\n\n<StatisticGroup label=\"Pipeline health\" columns={3}>\n <StatisticGroup.Statistic label=\"Builds\" value={412} />\n <StatisticGroup.Statistic label=\"Passed\" value={397} />\n <StatisticGroup.Statistic label=\"Failed\" value={15} />\n <StatisticGroup.Statistic label=\"Median duration\" value=\"6m 12s\" />\n <StatisticGroup.Statistic label=\"Cache hit rate\" value=\"91%\" />\n <StatisticGroup.Statistic label=\"Flaky reruns\" value={4} />\n</StatisticGroup>\n"
41
+ },
36
42
  {
37
43
  "id": "shared-borders-variant",
38
44
  "title": "Shared-borders variant",
@@ -9,6 +9,16 @@ const groupRole = $derived(label ? 'group' : role);
9
9
  const groupAriaLabel = $derived(label || ariaLabel);
10
10
  </script>
11
11
 
12
+ <!--
13
+ The root is the query container and the grid is its child. An element is
14
+ never its own container -- a container query resolves against the nearest
15
+ ANCESTOR container -- so with `container-type` on the grid itself the
16
+ collapse rules could never fire for a standalone group (CIN-499). The
17
+ container sits on the public root rather than on an extra wrapper around it
18
+ so that `class`, `style`, and `...rest` land on the element the queries
19
+ measure: a consumer that constrains the group's inline size constrains
20
+ exactly what collapses.
21
+ -->
12
22
  <div
13
23
  {...rest}
14
24
  role={groupRole}
@@ -17,5 +27,7 @@ const groupAriaLabel = $derived(label || ariaLabel);
17
27
  data-cinder-variant={variant}
18
28
  data-cinder-columns={String(columns)}
19
29
  >
20
- {@render children()}
30
+ <div class="cinder-statistic-group__grid">
31
+ {@render children()}
32
+ </div>
21
33
  </div>
@@ -29,14 +29,15 @@
29
29
  align-items: center;
30
30
  }
31
31
 
32
- /* TimeField now composes FormFieldFrame itself, which puts the nested
33
- Input inside a FormFieldContext. Since Input never receives its own
34
- label from TimeField, it renders bare (no `.cinder-input-field`
35
- wrapper) — so this sizing constraint targets `.cinder-time-field__input`
36
- (always present on the native control, wrapped or not) directly, rather
37
- than the wrapper class that may no longer exist. */
38
- .cinder-time-field__controls > .cinder-input-field,
39
- .cinder-time-field__controls > .cinder-time-field__input {
32
+ /* TimeField composes FormFieldFrame itself, which puts the nested Input
33
+ inside a FormFieldContext. Input always renders its own nested
34
+ FormFieldFrame there now (CIN-511: no more arm switch between a bare
35
+ control and a framed one — see input.svelte), with label/description/
36
+ error absent since TimeField never gives Input its own. That frame
37
+ always carries `.cinder-input-field` and is a direct child of this row,
38
+ so this single selector covers it regardless of whether a future
39
+ TimeField variant ever does pass Input its own label. */
40
+ .cinder-time-field__controls > .cinder-input-field {
40
41
  flex: 0 1 12rem;
41
42
  inline-size: auto;
42
43
  }
@@ -278,6 +278,14 @@ function beginDismiss(id, reason) {
278
278
  queueMicrotask(() => reallyRemove(id, generation));
279
279
  return;
280
280
  }
281
+ // OVERLAY-POLICY.md, "Transition lifecycle" > "The contract": the component
282
+ // renders data-cinder-closing on its animated element for the full duration
283
+ // of the exit transition while waitForTransitionCompletion detects
284
+ // completion. Toast keeps keying its exit CSS off the pre-existing
285
+ // data-cinder-presence="exiting" attribute (an accepted, additive naming
286
+ // difference — see the census entry for Toast); data-cinder-closing is
287
+ // purely additive so consumers and future migrations can rely on the
288
+ // canonical attribute name too.
281
289
  clearRemovalTimer(id);
282
290
  const cancelCompletion = waitForTransitionCompletion({
283
291
  element: shell,
@@ -508,6 +516,7 @@ onDestroy(() => {
508
516
  class="cinder-toast-shell"
509
517
  style={`--cinder-toast-stack-index: ${index};`}
510
518
  data-cinder-presence={toast.leaving ? 'exiting' : 'entered'}
519
+ data-cinder-closing={toast.leaving ? '' : undefined}
511
520
  >
512
521
  <div
513
522
  class="cinder-toast"
@@ -0,0 +1,248 @@
1
+ /**
2
+ * Velocity-adaptive overscan for the virtual list (CIN-203).
3
+ *
4
+ * Everything in this module is dependency-free arithmetic: no DOM, no runes,
5
+ * no `performance.now()`, no timers. It tracks scroll velocity from a stream
6
+ * of `(scrollOffset, timestamp)` samples the caller hands it — Svelte's
7
+ * `scroll` handler is the natural source, but nothing here reads it — and
8
+ * turns that velocity into extra rows of overscan so a fast fling has rows
9
+ * already mounted before they scroll into view. The configured `overscan`
10
+ * the consumer asked for is always the FLOOR: adaptation only ever adds rows
11
+ * on top of it, never renders fewer than the consumer's own request.
12
+ */
13
+
14
+ /**
15
+ * Smoothing factor for the exponential moving average `trackScrollVelocity`
16
+ * applies to each newly observed instantaneous velocity. Chosen low (0.3) so
17
+ * one anomalous frame — a layout hiccup that reports two samples 40ms apart
18
+ * instead of the usual ~16ms, briefly reading as a much larger delta over
19
+ * time — only pulls the smoothed velocity 30% of the way toward that spike
20
+ * rather than jumping there outright. High enough that a genuine, sustained
21
+ * velocity change still converges within a handful of frames (about 5
22
+ * samples closes 80% of the gap) instead of visibly lagging the reader's
23
+ * actual scroll speed.
24
+ */
25
+ const VELOCITY_SMOOTHING_FACTOR = 0.3;
26
+
27
+ /**
28
+ * Elapsed time, in milliseconds, beyond which two samples are treated as
29
+ * belonging to separate scroll gestures rather than one continuous scroll,
30
+ * resetting the tracked velocity to 0 instead of measuring a delta across
31
+ * the gap. Momentum/wheel scroll callbacks fire roughly every 16ms (one
32
+ * frame at 60Hz) while actively scrolling, so a gap this much larger than a
33
+ * frame can only mean the reader stopped. 250ms sits comfortably above the
34
+ * largest gap a live scroll should ever produce — even a dropped frame or
35
+ * two — while still being short enough that a reader who pauses mid-scroll
36
+ * and resumes quickly reads as having genuinely stopped, rather than
37
+ * smoothing a fast-then-idle-then-fast sequence into one continuous "fast"
38
+ * reading.
39
+ */
40
+ const IDLE_RESET_THRESHOLD_IN_MILLISECONDS = 250;
41
+
42
+ /**
43
+ * Immutable scroll-velocity state. Threaded through calls exactly like the
44
+ * offsets/measurement state elsewhere in `_internal`: `createVelocityTracker`
45
+ * produces the initial value, `trackScrollVelocity` takes one and returns a
46
+ * new one — the input is never mutated, so callers (an `$effect`, a test) can
47
+ * hold onto an old tracker and compare it against a new one safely.
48
+ */
49
+ export type VelocityTracker = {
50
+ /**
51
+ * The scroll offset and timestamp of the last sample folded in, or `null`
52
+ * before the first sample — `null` is what lets `trackScrollVelocity` tell
53
+ * "no previous sample to diff against" apart from "a previous sample that
54
+ * happened to sit at offset 0", which a sentinel number couldn't.
55
+ */
56
+ readonly lastScrollOffset: number;
57
+ readonly lastTimestamp: number | null;
58
+ /** Smoothed scroll speed, in pixels per millisecond. Always a magnitude — never negative. */
59
+ readonly velocityInPixelsPerMillisecond: number;
60
+ };
61
+
62
+ /** The tracker's initial state: no prior sample, so no velocity yet. */
63
+ export function createVelocityTracker(): VelocityTracker {
64
+ return { lastScrollOffset: 0, lastTimestamp: null, velocityInPixelsPerMillisecond: 0 };
65
+ }
66
+
67
+ /**
68
+ * Folds one `(scrollOffset, timestamp)` sample into `tracker`, returning a
69
+ * new tracker with an updated, EMA-smoothed velocity in pixels per
70
+ * millisecond. `tracker` itself is never mutated.
71
+ *
72
+ * Velocity is always a magnitude: scrolling up and scrolling down at the
73
+ * same speed produce the same value, because pop-in risk depends on how far
74
+ * the viewport is about to sweep, not which direction it sweeps in.
75
+ */
76
+ export function trackScrollVelocity(
77
+ tracker: VelocityTracker,
78
+ sample: { scrollOffset: number; timestamp: number },
79
+ ): VelocityTracker {
80
+ // No previous sample to diff against — reporting a delta over zero known
81
+ // elapsed time would be Infinity/NaN, not 0, if this fell through to the
82
+ // general branch below. Anchor here instead and let the NEXT sample
83
+ // produce the first real velocity reading.
84
+ if (tracker.lastTimestamp === null) {
85
+ return {
86
+ lastScrollOffset: sample.scrollOffset,
87
+ lastTimestamp: sample.timestamp,
88
+ velocityInPixelsPerMillisecond: 0,
89
+ };
90
+ }
91
+
92
+ const elapsedInMilliseconds = sample.timestamp - tracker.lastTimestamp;
93
+
94
+ // Two events stamped in the same millisecond, or a clock that went
95
+ // backwards, would divide by zero (or a negative number). Rather than
96
+ // advance the anchor on a degenerate sample — which would leave a later,
97
+ // valid sample computing its delta over a shorter elapsed time than
98
+ // actually passed, under-reporting velocity — leave the tracker exactly as
99
+ // it was. The next sample with a genuinely later timestamp measures the
100
+ // full delta over the full elapsed time since the last valid anchor, as if
101
+ // the degenerate sample had never arrived.
102
+ if (elapsedInMilliseconds <= 0) {
103
+ return tracker;
104
+ }
105
+
106
+ // A gap this large means the reader stopped and later resumed, not that
107
+ // they scrolled continuously very slowly. Without this reset, an EMA blend
108
+ // would still weight in whatever velocity was current before the gap —
109
+ // stale by definition, since it describes motion that ended long ago — and
110
+ // report it alongside a fresh sample as if the scroll had been continuous.
111
+ // Resetting treats the fresh sample as a new anchor, exactly like the
112
+ // first-sample case, so the gap costs one reading of 0 rather than a
113
+ // spurious blended spike.
114
+ if (elapsedInMilliseconds >= IDLE_RESET_THRESHOLD_IN_MILLISECONDS) {
115
+ return {
116
+ lastScrollOffset: sample.scrollOffset,
117
+ lastTimestamp: sample.timestamp,
118
+ velocityInPixelsPerMillisecond: 0,
119
+ };
120
+ }
121
+
122
+ const instantaneousVelocity =
123
+ Math.abs(sample.scrollOffset - tracker.lastScrollOffset) / elapsedInMilliseconds;
124
+ const smoothedVelocity =
125
+ VELOCITY_SMOOTHING_FACTOR * instantaneousVelocity +
126
+ (1 - VELOCITY_SMOOTHING_FACTOR) * tracker.velocityInPixelsPerMillisecond;
127
+
128
+ return {
129
+ lastScrollOffset: sample.scrollOffset,
130
+ lastTimestamp: sample.timestamp,
131
+ velocityInPixelsPerMillisecond: smoothedVelocity,
132
+ };
133
+ }
134
+
135
+ /**
136
+ * Assumed duration of one animation frame, in milliseconds, used to convert
137
+ * a velocity into "how far the list will travel before the next frame gets a
138
+ * chance to mount new rows." 60Hz (1000/60 ≈ 16.67ms) is the common
139
+ * denominator refresh rate. A higher-refresh display mounts more often than
140
+ * this assumes, which only makes overscan slightly more generous than
141
+ * strictly necessary there — harmless, since the floor/ceiling guarantees
142
+ * still hold either way. A lower-refresh or frame-dropping device is the
143
+ * case this constant actually protects: it travels FARTHER than one real
144
+ * frame implies, so erring toward this (rather than a shorter) frame
145
+ * duration keeps overscan from under-provisioning exactly when the risk of
146
+ * visible pop-in is highest.
147
+ */
148
+ const ASSUMED_FRAME_DURATION_IN_MILLISECONDS = 1000 / 60;
149
+
150
+ /**
151
+ * Default ceiling on adaptive overscan when the consumer does not supply
152
+ * `maximumOverscan`. Overscan that scaled with velocity unbounded would mount
153
+ * thousands of rows during a fast fling, defeating the point of virtualizing
154
+ * at all — this clamp is the whole safety property. 50 extra rows on each
155
+ * side comfortably covers a genuinely fast fling without bounding DOM size at
156
+ * a number a real consumer would consider unreasonable.
157
+ */
158
+ const DEFAULT_MAXIMUM_OVERSCAN = 50;
159
+
160
+ /**
161
+ * Resolves how many rows of overscan to render given the current scroll
162
+ * velocity. `baseOverscan` — the consumer's own configured `overscan`,
163
+ * default 5 — is always the floor: the result never drops below it,
164
+ * regardless of velocity. Extra rows are derived from velocity rather than a
165
+ * magic lookup table: roughly, however many whole item-heights the list will
166
+ * travel during one frame's worth of time at the current speed is how many
167
+ * additional rows need to already be mounted so they don't pop in.
168
+ */
169
+ export function resolveAdaptiveOverscan(options: {
170
+ baseOverscan: number;
171
+ velocityInPixelsPerMillisecond: number;
172
+ itemSize: number;
173
+ maximumOverscan?: number;
174
+ }): number {
175
+ // Matches resolveVirtualOverscan's own floor/clamp convention elsewhere in
176
+ // this component: an overscan the consumer configured is expected to
177
+ // already be a non-negative integer, and a non-finite or negative one is a
178
+ // caller bug this guards against rather than propagates.
179
+ const baseOverscan = Number.isFinite(options.baseOverscan)
180
+ ? Math.max(0, Math.floor(options.baseOverscan))
181
+ : 0;
182
+
183
+ // A zero (or negative) item size would divide by zero below, and a
184
+ // collapsed/unmeasured row gives no meaningful "rows per frame of travel"
185
+ // to derive — fall back to the floor rather than propagate NaN/Infinity.
186
+ if (!(options.itemSize > 0)) return baseOverscan;
187
+
188
+ const velocityInPixelsPerMillisecond = Number.isFinite(options.velocityInPixelsPerMillisecond)
189
+ ? Math.max(0, options.velocityInPixelsPerMillisecond)
190
+ : 0;
191
+
192
+ const maximumOverscanOption = options.maximumOverscan;
193
+ const resolvedMaximumOverscan =
194
+ maximumOverscanOption !== undefined &&
195
+ Number.isFinite(maximumOverscanOption) &&
196
+ maximumOverscanOption > 0
197
+ ? Math.floor(maximumOverscanOption)
198
+ : DEFAULT_MAXIMUM_OVERSCAN;
199
+
200
+ // Distance the list would travel in one frame at the current speed, in
201
+ // item-heights. Rounded up (not down) because even partial coverage into
202
+ // the next row means that row needs to be mounted for the frame it first
203
+ // becomes partially visible.
204
+ const extraRowsFromVelocity = Math.ceil(
205
+ (velocityInPixelsPerMillisecond * ASSUMED_FRAME_DURATION_IN_MILLISECONDS) / options.itemSize,
206
+ );
207
+
208
+ const overscan = baseOverscan + extraRowsFromVelocity;
209
+
210
+ // baseOverscan is the floor and resolvedMaximumOverscan the ceiling; the
211
+ // floor wins if the two ever conflict (e.g. a misconfigured maximumOverscan
212
+ // below baseOverscan), matching the acceptance criteria that adaptation
213
+ // never renders fewer rows than the consumer asked for. Every input to
214
+ // this expression is already an integer, so the result is too.
215
+ return Math.max(baseOverscan, Math.min(overscan, resolvedMaximumOverscan));
216
+ }
217
+
218
+ /**
219
+ * The row size adaptive overscan should convert a pixel velocity with.
220
+ *
221
+ * `estimateSize` is what the consumer guessed. In fixed mode that IS the row size and
222
+ * there is nothing to improve on. Under `dynamicSize` it is only a starting point, and
223
+ * the conversion from "pixels travelled this frame" to "rows to keep mounted" is
224
+ * exactly where being wrong hurts: with a 100px estimate over rows measuring 10px, a
225
+ * frame covering 100px reads as one row rather than the ten the viewport really
226
+ * crossed, so the window widens by a tenth of what the reader is outrunning.
227
+ *
228
+ * Averaged over the rows actually MEASURED, not over the whole collection. The offsets
229
+ * table's total blends measurements with estimates for every row not yet seen, and in
230
+ * a long list those estimates swamp the measurements — twenty measured rows of 10px
231
+ * among ten thousand estimated at 100px average out to 99.8px, which is the estimate
232
+ * again in all but name and leaves the ruler as wrong as it started.
233
+ *
234
+ * Falls back to the estimate until something has been measured, and if the measured
235
+ * average is not a usable positive number — a collection whose rows have all collapsed
236
+ * to zero, say.
237
+ */
238
+ export function resolveAdaptiveItemSize(options: {
239
+ dynamicSize: boolean;
240
+ measuredTotalSize: number;
241
+ measuredCount: number;
242
+ estimateSize: number;
243
+ }): number {
244
+ if (!options.dynamicSize) return options.estimateSize;
245
+ if (options.measuredCount <= 0) return options.estimateSize;
246
+ const average = options.measuredTotalSize / options.measuredCount;
247
+ return Number.isFinite(average) && average > 0 ? average : options.estimateSize;
248
+ }