@lostgradient/cinder 0.25.0 → 0.26.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +233 -0
- package/components.json +13 -6
- package/dist/components/accordion-item/accordion-item.css +0 -10
- package/dist/components/action-row/action-row.css +0 -9
- package/dist/components/alert/alert.css +0 -1
- package/dist/components/alert-dialog/index.js +2 -2
- package/dist/components/approval-card/index.js +2 -2
- package/dist/components/area-chart/index.js +2 -2
- package/dist/components/autocomplete/index.js +2 -2
- package/dist/components/avatar-group/avatar-group.css +0 -2
- package/dist/components/avatar-group/index.js +2 -2
- package/dist/components/backdrop/index.js +2 -2
- package/dist/components/bar-chart/index.js +2 -2
- package/dist/components/button/button.css +4 -4
- package/dist/components/button/button.variables.js +2 -2
- package/dist/components/card/card.css +0 -2
- package/dist/components/carousel/carousel.css +0 -5
- package/dist/components/checkbox/index.js +2 -2
- package/dist/components/code-block/code-block.css +0 -5
- package/dist/components/code-block/index.js +2 -2
- package/dist/components/color-field/index.js +2 -2
- package/dist/components/combobox/index.js +2 -2
- package/dist/components/command-menu/index.js +2 -2
- package/dist/components/command-palette/command-palette.css +50 -46
- package/dist/components/command-palette/index.js +2 -2
- package/dist/components/confirm-dialog/index.js +2 -2
- package/dist/components/context-menu/index.js +2 -2
- package/dist/components/data-table/data-table.css +0 -2
- package/dist/components/data-table/index.js +2 -2
- package/dist/components/date-picker/index.js +2 -2
- package/dist/components/date-range-field/index.js +2 -2
- package/dist/components/drawer/index.js +2 -2
- package/dist/components/dropdown/index.js +2 -2
- package/dist/components/dropdown-menu/index.js +2 -2
- package/dist/components/feed-event/feed-event.css +0 -2
- package/dist/components/file-upload/file-upload.css +0 -5
- package/dist/components/find-bar/find-bar.css +9 -1
- package/dist/components/focus-trap/index.js +2 -2
- package/dist/components/form-field/index.js +2 -2
- package/dist/components/guidance-region/index.css +1 -1
- package/dist/components/hover-card/index.js +2 -2
- package/dist/components/inline-confirm/index.js +2 -2
- package/dist/components/input/index.js +2 -2
- package/dist/components/input/input.css +95 -6
- package/dist/components/invocation-rule-builder/index.js +2 -2
- package/dist/components/json-editor/index.js +2 -2
- package/dist/components/json-schema-editor/index.js +4 -4
- package/dist/components/kanban-board/kanban-board.css +0 -10
- package/dist/components/key-value-editor/index.css +1 -1
- package/dist/components/line-chart/index.js +2 -2
- package/dist/components/marquee/marquee.css +0 -2
- package/dist/components/matrix-chart/index.js +2 -2
- package/dist/components/menu-bar/index.js +3 -3
- package/dist/components/modal/index.js +2 -2
- package/dist/components/modal/modal.css +0 -26
- package/dist/components/modal-region/index.css +1 -1
- package/dist/components/multi-select/index.js +2 -2
- package/dist/components/navigation-bar/index.js +2 -2
- package/dist/components/parameter-field/index.js +2 -2
- package/dist/components/permission-matrix/index.js +2 -2
- package/dist/components/policy-lock/index.js +2 -2
- package/dist/components/popover/index.js +2 -2
- package/dist/components/radio-group/index.js +2 -2
- package/dist/components/schedule-builder/index.js +2 -2
- package/dist/components/schema-form/index.js +2 -2
- package/dist/components/scroll-area/index.js +2 -2
- package/dist/components/select/index.js +2 -2
- package/dist/components/selectable-row/selectable-row.css +0 -6
- package/dist/components/selection-popover/index.js +2 -2
- package/dist/components/share-card/index.js +2 -2
- package/dist/components/side-navigation/side-navigation.css +0 -1
- package/dist/components/sidebar/index.js +2 -2
- package/dist/components/speed-dial/index.js +2 -2
- package/dist/components/statistic/statistic.css +0 -8
- package/dist/components/statistic-group/index.js +2 -2
- package/dist/components/statistic-group/statistic-group.css +116 -69
- package/dist/components/status-dot/status-dot.css +0 -3
- package/dist/components/table/index.js +2 -2
- package/dist/components/table-of-contents/table-of-contents.css +0 -4
- package/dist/components/textarea/index.js +2 -2
- package/dist/components/time-field/index.js +2 -2
- package/dist/components/time-field/time-field.css +9 -8
- package/dist/components/toast-region/index.js +2 -2
- package/dist/components/toggle/toggle.variables.js +2 -2
- package/dist/components/tooltip/index.js +2 -2
- package/dist/components/transfer-list/index.js +2 -2
- package/dist/components/tree/tree.css +0 -3
- package/dist/components/virtual-list/_internal/adaptive-overscan.d.ts +87 -0
- package/dist/components/virtual-list/_internal/edge-proximity.d.ts +75 -0
- package/dist/components/virtual-list/_internal/frame-scheduler.d.ts +76 -0
- package/dist/components/virtual-list/_internal/geometry.d.ts +170 -0
- package/dist/components/virtual-list/_internal/list-semantics.d.ts +93 -0
- package/dist/components/virtual-list/_internal/measurement-window.d.ts +125 -0
- package/dist/components/virtual-list/_internal/reverse-order.d.ts +87 -0
- package/dist/components/virtual-list/_internal/scroll-restoration.d.ts +98 -0
- package/dist/components/virtual-list/_internal/sticky-items.d.ts +48 -0
- package/dist/components/virtual-list/_internal/virtual-list-measurement-store.svelte.d.ts +69 -0
- package/dist/components/virtual-list/index.d.ts +1 -1
- package/dist/components/virtual-list/index.js +2 -2
- package/dist/components/virtual-list/virtual-list.css +153 -2
- package/dist/components/virtual-list/virtual-list.schema.js +69 -6
- package/dist/components/virtual-list/virtual-list.svelte.d.ts +11 -8
- package/dist/components/virtual-list/virtual-list.types.d.ts +177 -4
- package/dist/index.browser.css +1 -1
- package/dist/index.d.ts +1 -1
- package/dist/index.js +18 -18
- package/dist/server/components/alert-dialog/index.js +1 -1
- package/dist/server/components/approval-card/index.js +1 -1
- package/dist/server/components/area-chart/index.js +1 -1
- package/dist/server/components/autocomplete/index.js +1 -1
- package/dist/server/components/avatar-group/index.js +1 -1
- package/dist/server/components/backdrop/index.js +1 -1
- package/dist/server/components/bar-chart/index.js +1 -1
- package/dist/server/components/checkbox/index.js +1 -1
- package/dist/server/components/code-block/index.js +1 -1
- package/dist/server/components/color-field/index.js +1 -1
- package/dist/server/components/combobox/index.js +1 -1
- package/dist/server/components/command-menu/index.js +1 -1
- package/dist/server/components/command-palette/index.js +2 -2
- package/dist/server/components/confirm-dialog/index.js +1 -1
- package/dist/server/components/context-menu/index.js +1 -1
- package/dist/server/components/data-table/index.js +1 -1
- package/dist/server/components/date-picker/index.js +1 -1
- package/dist/server/components/date-range-field/index.js +1 -1
- package/dist/server/components/drawer/index.js +1 -1
- package/dist/server/components/dropdown/index.js +1 -1
- package/dist/server/components/dropdown-menu/index.js +2 -2
- package/dist/server/components/focus-trap/index.js +1 -1
- package/dist/server/components/form-field/index.js +1 -1
- package/dist/server/components/hover-card/index.js +1 -1
- package/dist/server/components/inline-confirm/index.js +1 -1
- package/dist/server/components/input/index.js +1 -1
- package/dist/server/components/invocation-rule-builder/index.js +1 -1
- package/dist/server/components/json-editor/index.js +1 -1
- package/dist/server/components/json-schema-editor/index.js +1 -1
- package/dist/server/components/line-chart/index.js +1 -1
- package/dist/server/components/matrix-chart/index.js +1 -1
- package/dist/server/components/menu-bar/index.js +2 -2
- package/dist/server/components/modal/index.js +1 -1
- package/dist/server/components/multi-select/index.js +1 -1
- package/dist/server/components/navigation-bar/index.js +2 -2
- package/dist/server/components/parameter-field/index.js +1 -1
- package/dist/server/components/permission-matrix/index.js +1 -1
- package/dist/server/components/policy-lock/index.js +1 -1
- package/dist/server/components/popover/index.js +1 -1
- package/dist/server/components/radio-group/index.js +1 -1
- package/dist/server/components/schedule-builder/index.js +1 -1
- package/dist/server/components/schema-form/index.js +1 -1
- package/dist/server/components/scroll-area/index.js +1 -1
- package/dist/server/components/select/index.js +1 -1
- package/dist/server/components/selection-popover/index.js +1 -1
- package/dist/server/components/share-card/index.js +1 -1
- package/dist/server/components/sidebar/index.js +1 -1
- package/dist/server/components/speed-dial/index.js +2 -2
- package/dist/server/components/statistic-group/index.js +1 -1
- package/dist/server/components/table/index.js +1 -1
- package/dist/server/components/textarea/index.js +1 -1
- package/dist/server/components/time-field/index.js +1 -1
- package/dist/server/components/toast-region/index.js +1 -1
- package/dist/server/components/tooltip/index.js +1 -1
- package/dist/server/components/transfer-list/index.js +1 -1
- package/dist/server/components/virtual-list/index.js +2 -2
- package/dist/server/index.js +2 -2
- package/dist/server/{index.server-skq0f5sr.js → index.server-0jw25w9w.js} +1 -1
- package/dist/server/index.server-0kk20wvp.js +4 -0
- package/dist/server/{index.server-fzsqdajc.js → index.server-2awq6q9m.js} +1 -1
- package/dist/server/{index.server-e4hmhaeh.js → index.server-3xwvw6w2.js} +3 -3
- package/dist/server/{index.server-95h7xy01.js → index.server-428dh2t9.js} +2 -2
- package/dist/server/{index.server-jd88r74m.js → index.server-5dq66aja.js} +2 -2
- package/dist/server/{index.server-dvwfhf77.js → index.server-5s94r0kk.js} +2 -2
- package/dist/server/{index.server-qv6z5ta3.js → index.server-80qgcjnm.js} +1 -1
- package/dist/server/{index.server-7k2732ky.js → index.server-81abtrsw.js} +1 -1
- package/dist/server/{index.server-csmqnx5w.js → index.server-83q1gv2c.js} +1 -1
- package/dist/server/{index.server-qw8k9rjg.js → index.server-8fyav10d.js} +1 -1
- package/dist/server/{index.server-4dgjj4k1.js → index.server-8h5caecr.js} +2 -2
- package/dist/server/{index.server-emyqytmm.js → index.server-90n8sd9e.js} +1 -1
- package/dist/server/{index.server-0xrdyzvh.js → index.server-99penx1m.js} +1 -1
- package/dist/server/{index.server-p94j3jah.js → index.server-9g9d15z1.js} +1 -1
- package/dist/server/{index.server-xp9hkc81.js → index.server-9kbdx511.js} +1 -1
- package/dist/server/index.server-a2yhk45s.js +3 -0
- package/dist/server/{index.server-g8d2m2tk.js → index.server-acq55gjs.js} +1 -1
- package/dist/server/{index.server-ewze54tv.js → index.server-afjftjmr.js} +1 -1
- package/dist/server/{index.server-ejyye4gv.js → index.server-bfed6a8a.js} +1 -1
- package/dist/server/{index.server-z5ng08q2.js → index.server-c1746s0z.js} +1 -1
- package/dist/server/{index.server-gt1tfc1w.js → index.server-dmeztywe.js} +1 -1
- package/dist/server/{index.server-kzsppq0n.js → index.server-dyj3jdx9.js} +1 -1
- package/dist/server/index.server-dz92zvx6.js +4 -0
- package/dist/server/{index.server-3md8kdcr.js → index.server-e6682k08.js} +1 -1
- package/dist/server/{index.server-t1pshh65.js → index.server-ewkv461x.js} +1 -1
- package/dist/server/{index.server-zfgwhtmp.js → index.server-fa449wd3.js} +1 -1
- package/dist/server/{index.server-1kgwayct.js → index.server-fhfypmgw.js} +1 -1
- package/dist/server/{index.server-s4z8hsby.js → index.server-ge4adxs2.js} +1 -1
- package/dist/server/{index.server-68xyfsg3.js → index.server-gggkq22y.js} +2 -2
- package/dist/server/{index.server-acgwdamx.js → index.server-j52rbk57.js} +1 -1
- package/dist/server/{index.server-z0nwftx6.js → index.server-jm89hxfb.js} +1 -1
- package/dist/server/{index.server-xa98r8p2.js → index.server-jw0v64se.js} +1 -1
- package/dist/server/index.server-m321p69g.js +3 -0
- package/dist/server/{index.server-xyervw3d.js → index.server-m7q2tc41.js} +1 -1
- package/dist/server/{index.server-tnrxy86j.js → index.server-mak7dmj2.js} +1 -1
- package/dist/server/{index.server-n5g5h5k1.js → index.server-mw5r2524.js} +1 -1
- package/dist/server/{index.server-caf7s6m7.js → index.server-nwq1cg55.js} +1 -1
- package/dist/server/{index.server-3wdvs0wr.js → index.server-p423fy4q.js} +2 -2
- package/dist/server/{index.server-ks7fvwxt.js → index.server-prk5syj2.js} +1 -1
- package/dist/server/{index.server-6w9fp018.js → index.server-q4hytsq3.js} +1 -1
- package/dist/server/{index.server-5w2qw8fm.js → index.server-q597a1ck.js} +1 -1
- package/dist/server/{index.server-fz1pkvda.js → index.server-qgne9v2w.js} +1 -1
- package/dist/server/{index.server-1f2app32.js → index.server-rvdavf92.js} +1 -1
- package/dist/server/index.server-rwq20a22.js +3 -0
- package/dist/server/{index.server-0rvmnrw2.js → index.server-s9tjs45r.js} +1 -1
- package/dist/server/{index.server-cm2prec7.js → index.server-sqgxyfsw.js} +1 -1
- package/dist/server/{index.server-v6777tgn.js → index.server-t761nwvb.js} +1 -1
- package/dist/server/index.server-tbds8nwq.js +4 -0
- package/dist/server/index.server-tyhta5n3.js +3 -0
- package/dist/server/{index.server-yw7rah51.js → index.server-v5dxham4.js} +1 -1
- package/dist/server/index.server-va98cpyf.js +3 -0
- package/dist/server/index.server-vq1k69xt.js +3 -0
- package/dist/server/{index.server-egd355s6.js → index.server-wnf9btp7.js} +2 -2
- package/dist/server/{index.server-sjcbaztf.js → index.server-y3zgdtbv.js} +1 -1
- package/dist/server/{index.server-4tjtgzf9.js → index.server-y6vtbmyj.js} +1 -1
- package/dist/server/{index.server-2p2mjzzb.js → index.server-zff2qp1v.js} +1 -1
- package/dist/server/tokens/registry.generated.js +2 -2
- package/dist/tokens/registry.generated.js +2 -2
- package/package.json +2 -2
- package/src/_internal/form-field-frame.svelte +5 -0
- package/src/_internal/overlay.ts +14 -1
- package/src/components/_internal/create-command-list-state.svelte.ts +4 -0
- package/src/components/accordion-item/accordion-item.css +0 -10
- package/src/components/action-row/action-row.css +0 -9
- package/src/components/alert/alert.css +0 -1
- package/src/components/avatar-group/avatar-group.css +0 -2
- package/src/components/button/button.css +4 -4
- package/src/components/button/button.variables.json +31 -1
- package/src/components/button/button.variables.ts +31 -1
- package/src/components/card/card.css +0 -2
- package/src/components/carousel/carousel.css +0 -5
- package/src/components/code-block/code-block.css +0 -5
- package/src/components/command-menu/command-menu.svelte +63 -7
- package/src/components/command-palette/command-palette.css +50 -46
- package/src/components/command-palette/command-palette.svelte +68 -78
- package/src/components/data-table/data-table.css +0 -2
- package/src/components/dropdown/dropdown.svelte +73 -18
- package/src/components/dropdown-menu/dropdown-menu.svelte +63 -7
- package/src/components/feed-event/feed-event.css +0 -2
- package/src/components/file-upload/file-upload.css +0 -5
- package/src/components/find-bar/find-bar.css +9 -1
- package/src/components/input/input.css +95 -6
- package/src/components/input/input.svelte +44 -81
- package/src/components/kanban-board/kanban-board.css +0 -10
- package/src/components/marquee/marquee.css +0 -2
- package/src/components/menu-bar/menu-bar.svelte +12 -1
- package/src/components/modal/modal.css +0 -26
- package/src/components/multi-select/multi-select.svelte +7 -0
- package/src/components/navigation-bar/navigation-bar.svelte +82 -6
- package/src/components/selectable-row/selectable-row.css +0 -6
- package/src/components/selection-popover/selection-popover.svelte +24 -10
- package/src/components/share-card/share-card.svelte +24 -44
- package/src/components/side-navigation/side-navigation.css +0 -1
- package/src/components/speed-dial/speed-dial.svelte +23 -5
- package/src/components/statistic/statistic.css +0 -8
- package/src/components/statistic-group/statistic-group.css +116 -69
- package/src/components/statistic-group/statistic-group.examples.json +6 -0
- package/src/components/statistic-group/statistic-group.svelte +13 -1
- package/src/components/status-dot/status-dot.css +0 -3
- package/src/components/table-of-contents/table-of-contents.css +0 -4
- package/src/components/time-field/time-field.css +9 -8
- package/src/components/toast-region/toast-region.svelte +9 -0
- package/src/components/toggle/toggle.variables.json +1 -1
- package/src/components/toggle/toggle.variables.ts +4 -1
- package/src/components/tree/tree.css +0 -3
- package/src/components/virtual-list/_internal/adaptive-overscan.ts +248 -0
- package/src/components/virtual-list/_internal/edge-proximity.ts +130 -0
- package/src/components/virtual-list/_internal/frame-scheduler.ts +136 -0
- package/src/components/virtual-list/_internal/geometry.ts +236 -0
- package/src/components/virtual-list/_internal/list-semantics.ts +151 -0
- package/src/components/virtual-list/_internal/measurement-window.ts +300 -0
- package/src/components/virtual-list/_internal/reverse-order.ts +146 -0
- package/src/components/virtual-list/_internal/scroll-restoration.ts +209 -0
- package/src/components/virtual-list/_internal/sticky-items.ts +111 -0
- package/src/components/virtual-list/_internal/virtual-list-measurement-store.svelte.ts +145 -0
- package/src/components/virtual-list/index.ts +7 -1
- package/src/components/virtual-list/virtual-list.css +153 -2
- package/src/components/virtual-list/virtual-list.examples.json +42 -0
- package/src/components/virtual-list/virtual-list.schema.json +53 -3
- package/src/components/virtual-list/virtual-list.schema.ts +64 -3
- package/src/components/virtual-list/virtual-list.svelte +1527 -36
- package/src/components/virtual-list/virtual-list.types.ts +181 -4
- package/src/index.ts +3 -0
- package/src/styles/tokens-base.css +57 -22
- package/src/tokens/cinder.resolver.json +8 -0
- package/src/tokens/index.json +1 -1
- package/src/tokens/registry.generated.json +30 -4
- package/src/tokens/registry.generated.ts +32 -4
- package/src/tokens/resolved/dark-reduced-motion.json +47 -17
- package/src/tokens/resolved/dark.json +47 -17
- package/src/tokens/resolved/light-reduced-motion.json +48 -18
- package/src/tokens/resolved/light.json +48 -18
- package/src/tokens/sets/components.tokens.json +1 -1
- package/src/tokens/sets/semantic.tokens.json +120 -30
- package/src/tokens/themes/dark.tokens.json +115 -19
- package/src/tokens/themes/light.tokens.json +51 -3
- package/dist/server/index.server-191cnacw.js +0 -3
- package/dist/server/index.server-25dqx151.js +0 -3
- package/dist/server/index.server-77jyqvbv.js +0 -4
- package/dist/server/index.server-bgjrzr70.js +0 -3
- package/dist/server/index.server-khsp90vh.js +0 -3
- package/dist/server/index.server-ryk2pgbe.js +0 -4
- package/dist/server/index.server-tajr81bm.js +0 -3
- package/dist/server/index.server-vjzcrw3d.js +0 -4
- package/dist/server/index.server-zg3fx1n1.js +0 -3
|
@@ -0,0 +1,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 {
|
|
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": "
|
|
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
|
|
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",
|