@lostgradient/cinder 0.25.1 → 0.26.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +227 -0
- package/components.json +13 -6
- 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/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 +1 -1
- package/dist/components/checkbox/index.js +2 -2
- 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/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/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/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/key-value-editor/index.css +1 -1
- package/dist/components/line-chart/index.js +2 -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-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/selection-popover/index.js +2 -2
- package/dist/components/share-card/index.js +2 -2
- package/dist/components/sidebar/index.js +2 -2
- package/dist/components/speed-dial/index.js +2 -2
- package/dist/components/statistic-group/index.js +2 -2
- package/dist/components/statistic-group/statistic-group.css +116 -66
- package/dist/components/table/index.js +2 -2
- 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/tooltip/index.js +2 -2
- package/dist/components/transfer-list/index.js +2 -2
- 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 -0
- 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/button/button.css +1 -1
- 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/dropdown/dropdown.svelte +73 -18
- package/src/components/dropdown-menu/dropdown-menu.svelte +63 -7
- 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/menu-bar/menu-bar.svelte +12 -1
- package/src/components/multi-select/multi-select.svelte +7 -0
- package/src/components/navigation-bar/navigation-bar.svelte +82 -6
- package/src/components/selection-popover/selection-popover.svelte +24 -10
- package/src/components/share-card/share-card.svelte +24 -44
- package/src/components/speed-dial/speed-dial.svelte +23 -5
- package/src/components/statistic-group/statistic-group.css +116 -66
- package/src/components/statistic-group/statistic-group.examples.json +6 -0
- package/src/components/statistic-group/statistic-group.svelte +13 -1
- package/src/components/time-field/time-field.css +9 -8
- package/src/components/toast-region/toast-region.svelte +9 -0
- 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 -0
- 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 +29 -21
- package/src/tokens/cinder.resolver.json +8 -0
- package/src/tokens/index.json +1 -1
- package/src/tokens/registry.generated.json +29 -3
- package/src/tokens/registry.generated.ts +31 -3
- package/src/tokens/resolved/dark-reduced-motion.json +46 -16
- package/src/tokens/resolved/dark.json +46 -16
- package/src/tokens/resolved/light-reduced-motion.json +47 -17
- package/src/tokens/resolved/light.json +47 -17
- 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
|
@@ -11,6 +11,86 @@
|
|
|
11
11
|
contain: layout paint;
|
|
12
12
|
}
|
|
13
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
|
+
|
|
14
94
|
.cinder-virtual-list__spacer {
|
|
15
95
|
position: relative;
|
|
16
96
|
min-block-size: 100%;
|
|
@@ -25,4 +105,77 @@
|
|
|
25
105
|
.cinder-virtual-list__row {
|
|
26
106
|
overflow: hidden;
|
|
27
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
|
+
}
|
|
28
181
|
}
|
|
@@ -1,8 +1,71 @@
|
|
|
1
|
-
var __create=Object.create;var __getProtoOf=Object.getPrototypeOf;var __defProp=Object.defineProperty;var __getOwnPropNames=Object.getOwnPropertyNames;var __hasOwnProp=Object.prototype.hasOwnProperty;function __accessProp(key){return this[key]}var __toESMCache_node;var __toESMCache_esm;var __toESM=(mod,isNodeMode,target)=>{var canCache=mod!=null&&typeof mod==="object";if(canCache){var cache=isNodeMode?__toESMCache_node??=new WeakMap:__toESMCache_esm??=new WeakMap;var cached=cache.get(mod);if(cached)return cached}target=mod!=null?__create(__getProtoOf(mod)):{};const to=isNodeMode||!mod||!mod.__esModule?__defProp(target,"default",{value:mod,enumerable:true}):target;if(mod&&typeof mod==="object"||typeof mod==="function"){for(let key of __getOwnPropNames(mod))if(!__hasOwnProp.call(to,key))__defProp(to,key,{get:__accessProp.bind(mod,key),enumerable:true})}if(canCache)cache.set(mod,to);return to};var __commonJS=(cb,mod)=>()=>(mod||cb((mod={exports:{}}).exports,mod),mod.exports);var __returnValue=(v)=>v;function __exportSetter(name,newValue){this[name]=__returnValue.bind(null,newValue)}var __export=(target,all)=>{for(var name in all)__defProp(target,name,{get:all[name],enumerable:true,configurable:true,set:__exportSetter.bind(all,name)})};var __esm=(fn,res)=>()=>(fn&&(res=fn(fn=0)),res);var __require=((x)=>typeof require!=="undefined"?require:typeof Proxy!=="undefined"?new Proxy(x,{get:(a,b)=>(typeof require!=="undefined"?require:a)[b]}):x)(function(x){if(typeof require!=="undefined")return require.apply(this,arguments);throw Error('Dynamic require of "'+x+'" is not supported')});var schema={$schema:"https://json-schema.org/draft/2020-12/schema",type:"object",properties:{itemHeight:{type:"number",description
|
|
2
|
-
|
|
3
|
-
Defaults to 5.`},height:{type:"string",description:'CSS block-size for the native scroll container.\nDefaults to `"20rem"`.'},stickToBottom:{type:"boolean",description:`When true, appending items while the viewport is already at the bottom
|
|
1
|
+
var __create=Object.create;var __getProtoOf=Object.getPrototypeOf;var __defProp=Object.defineProperty;var __getOwnPropNames=Object.getOwnPropertyNames;var __hasOwnProp=Object.prototype.hasOwnProperty;function __accessProp(key){return this[key]}var __toESMCache_node;var __toESMCache_esm;var __toESM=(mod,isNodeMode,target)=>{var canCache=mod!=null&&typeof mod==="object";if(canCache){var cache=isNodeMode?__toESMCache_node??=new WeakMap:__toESMCache_esm??=new WeakMap;var cached=cache.get(mod);if(cached)return cached}target=mod!=null?__create(__getProtoOf(mod)):{};const to=isNodeMode||!mod||!mod.__esModule?__defProp(target,"default",{value:mod,enumerable:true}):target;if(mod&&typeof mod==="object"||typeof mod==="function"){for(let key of __getOwnPropNames(mod))if(!__hasOwnProp.call(to,key))__defProp(to,key,{get:__accessProp.bind(mod,key),enumerable:true})}if(canCache)cache.set(mod,to);return to};var __commonJS=(cb,mod)=>()=>(mod||cb((mod={exports:{}}).exports,mod),mod.exports);var __returnValue=(v)=>v;function __exportSetter(name,newValue){this[name]=__returnValue.bind(null,newValue)}var __export=(target,all)=>{for(var name in all)__defProp(target,name,{get:all[name],enumerable:true,configurable:true,set:__exportSetter.bind(all,name)})};var __esm=(fn,res)=>()=>(fn&&(res=fn(fn=0)),res);var __require=((x)=>typeof require!=="undefined"?require:typeof Proxy!=="undefined"?new Proxy(x,{get:(a,b)=>(typeof require!=="undefined"?require:a)[b]}):x)(function(x){if(typeof require!=="undefined")return require.apply(this,arguments);throw Error('Dynamic require of "'+x+'" is not supported')});var schema={$schema:"https://json-schema.org/draft/2020-12/schema",type:"object",properties:{itemHeight:{type:"number",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."},dynamicSize:{type:"boolean",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."},horizontal:{type:"boolean",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."},overscan:{type:"number",description:`Extra rows rendered before and after the visible window.
|
|
2
|
+
Defaults to 5.`},height:{type:"string",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"`.'},stickToBottom:{type:"boolean",description:`When true, appending items while the viewport is already at the bottom
|
|
4
3
|
keeps the newest item pinned in view. Appending while scrolled up leaves the
|
|
5
|
-
scroll position unchanged.`},
|
|
6
|
-
|
|
4
|
+
scroll position unchanged.`},reverse:{type:"boolean",description:`Chat-transcript behaviour: the list starts at its end and returns there on
|
|
5
|
+
every append.
|
|
7
6
|
|
|
8
|
-
|
|
7
|
+
Items stay in their natural order — oldest at index 0, newest last. \`reverse\`
|
|
8
|
+
names the anchoring, not the ordering, and the array is never flipped.
|
|
9
|
+
|
|
10
|
+
Deliberately distinct from \`stickToBottom\`, which pins only when the reader is
|
|
11
|
+
already at the bottom. \`reverse\` pins on every append regardless of where the
|
|
12
|
+
reader is. When both are set, \`reverse\` wins.
|
|
13
|
+
|
|
14
|
+
Prepending — loading a page of older history — never moves the reader: the row
|
|
15
|
+
they were looking at stays put while the list grows above it.
|
|
16
|
+
|
|
17
|
+
That last guarantee REQUIRES \`getKey\`. Telling a prepend from an append means
|
|
18
|
+
comparing key sequences, and without \`getKey\` the keys are array indexes: a
|
|
19
|
+
prepend turns \`[0, 1, 2]\` into \`[0, 1, 2, 3, 4]\`, which is indistinguishable
|
|
20
|
+
from an append and pins the reader to the end instead of holding their place.
|
|
21
|
+
Pass \`getKey\` whenever the list can grow at the front.
|
|
22
|
+
|
|
23
|
+
Defaults to false.`},scrollRestoration:{type:"boolean",description:`Remember the scroll position across navigation, keyed by
|
|
24
|
+
\`scrollRestorationId\`.
|
|
25
|
+
|
|
26
|
+
The position is written to \`sessionStorage\` when the list tears down, and read
|
|
27
|
+
back when it mounts. Deliberately not on every scroll: that would mean a
|
|
28
|
+
storage write per frame during a fling, and teardown is the last moment the
|
|
29
|
+
position is knowable anyway. The consequence is that a tab closed by a crash,
|
|
30
|
+
rather than by navigating away, will not have saved.
|
|
31
|
+
|
|
32
|
+
Storage failures are swallowed: a browser in private mode or at its quota throws
|
|
33
|
+
on write — and on read — and losing a remembered offset must not break the list.
|
|
34
|
+
|
|
35
|
+
Has no effect without a \`scrollRestorationId\` — see that prop for why.
|
|
36
|
+
|
|
37
|
+
Explicitly \`| undefined\`, like the other conditionally-supplied props: this
|
|
38
|
+
package compiles with \`exactOptionalPropertyTypes\`, under which optional and
|
|
39
|
+
undefined-valued differ, and \`scrollRestoration={enabled ? true : undefined}\`
|
|
40
|
+
would otherwise fail to typecheck.
|
|
41
|
+
|
|
42
|
+
Defaults to false.`},stickyItems:{type:"array",items:{type:"number"},description:`Item indexes that stay visible at the leading edge while the reader scrolls
|
|
43
|
+
past them — section headers in a grouped list, most often.
|
|
44
|
+
|
|
45
|
+
A sticky row is kept mounted even after its own index leaves the rendered
|
|
46
|
+
window, which is the part virtualization would otherwise break: unmounting it
|
|
47
|
+
would make the heading vanish exactly when it is meant to be pinned.
|
|
48
|
+
|
|
49
|
+
Indexes outside the list, duplicates, and non-integers are dropped rather than
|
|
50
|
+
throwing — a bad sticky index is a cosmetic problem, not a correctness one.`},smoothScroll:{type:"boolean",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."},adaptiveOverscan:{type:"boolean",description:`Grow \`overscan\` while the reader is scrolling fast, and shrink it back when
|
|
51
|
+
they slow down.
|
|
52
|
+
|
|
53
|
+
\`overscan\` becomes a floor rather than a fixed value: a fast fling renders
|
|
54
|
+
further ahead to cut pop-in, and a stationary list falls back to exactly what
|
|
55
|
+
was configured so the DOM stays small. The growth is bounded, because an
|
|
56
|
+
unbounded overscan during a fling would mount thousands of rows and defeat the
|
|
57
|
+
point of virtualizing at all.
|
|
58
|
+
|
|
59
|
+
Defaults to false.`},scrollRestorationId:{type:"string",description:`Stable id under which \`scrollRestoration\` saves this list's position.
|
|
60
|
+
|
|
61
|
+
Required for restoration to do anything. There is deliberately no default:
|
|
62
|
+
an implicit key derived from position or order would silently hand one
|
|
63
|
+
list's remembered offset to a different list after a refactor, and two lists
|
|
64
|
+
on one page would overwrite each other. Choose something tied to what the
|
|
65
|
+
list shows, such as a route or collection name.`},tabindex:{type:"number",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.'},class:{type:"string",description:"Additional class names merged with `.cinder-virtual-list`."}},additionalProperties:false,required:["itemHeight"],metadata:{unsupportedProps:[{name:"getKey",reason:"function-or-snippet",description:`Stable key extractor. Omit only when items are append-only and never
|
|
66
|
+
reordered; the component will fall back to full-array indexes.
|
|
67
|
+
|
|
68
|
+
Required in practice under \`dynamicSize\`: measured sizes are cached by key,
|
|
69
|
+
so index-derived keys will mis-attribute cached sizes if items ever reorder.`},{name:"items",reason:"generic-type-parameter",required:true,description:"Items in full logical order. Only the visible window is mounted."},{name:"onEndReached",reason:"function-or-snippet",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."},{name:"onStartReached",reason:"function-or-snippet",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."},{name:"ref",reason:"unknown-shape",description:"Typed programmatic handle. Use `bind:ref` to receive it."},{name:"row",reason:"function-or-snippet",required:true,description:"Rendered row snippet. Receives the item and its virtual row context."}]}};var virtual_list_schema_default=schema;export{virtual_list_schema_default as default};
|
|
70
|
+
|
|
71
|
+
//# debugId=89D8FE8F13E3A04B64756E2164756E21
|
|
@@ -2,24 +2,27 @@
|
|
|
2
2
|
* @cinder
|
|
3
3
|
* @category data-display
|
|
4
4
|
* @status beta
|
|
5
|
-
* @purpose
|
|
5
|
+
* @purpose Windowing primitive for long lists along either axis, rendering only the visible rows plus overscan, with fixed-height rows by default and opt-in measured rows.
|
|
6
6
|
* @tag list
|
|
7
7
|
* @tag virtualization
|
|
8
8
|
* @tag performance
|
|
9
|
-
* @useWhen Rendering thousands of
|
|
10
|
-
* @useWhen
|
|
11
|
-
* @
|
|
12
|
-
* @
|
|
9
|
+
* @useWhen Rendering thousands of rows: logs, event streams, activity feeds.
|
|
10
|
+
* @useWhen Rows vary in size because they wrap or embed media — dynamicSize measures each.
|
|
11
|
+
* @useWhen Windowing the inline axis — horizontal, which also resolves right-to-left.
|
|
12
|
+
* @useWhen A transcript anchored to its newest message, or paging in at either edge.
|
|
13
|
+
* @avoidWhen Two-dimensional grids, which need column virtualization and grid semantics. | data-grid
|
|
14
|
+
* @avoidWhen A native table or a hierarchy — data-table and tree window those already.
|
|
15
|
+
* @avoidWhen The collection is small enough to render in full.
|
|
13
16
|
* @related data-list, data-table, data-grid, load-more
|
|
14
17
|
*/
|
|
15
|
-
export type { VirtualListProps, VirtualListRowContext } from './virtual-list.types.ts';
|
|
18
|
+
export type { VirtualListProps, VirtualListRef, VirtualListRowContext, VirtualListScrollAlign, VirtualListScrollToIndexOptions, } from './virtual-list.types.ts';
|
|
16
19
|
export type { FixedVirtualWindow, FixedVirtualWindowItem, } from '../../utilities/fixed-virtual-window.ts';
|
|
17
20
|
export { getFixedVirtualWindow, parsePixelLength, resolveVirtualItemHeight, resolveVirtualOverscan, } from '../../utilities/fixed-virtual-window.ts';
|
|
18
21
|
import type { VirtualListProps } from './virtual-list.types.ts';
|
|
19
22
|
declare function $$render<Item>(): {
|
|
20
23
|
props: VirtualListProps<Item>;
|
|
21
24
|
exports: {};
|
|
22
|
-
bindings: "";
|
|
25
|
+
bindings: "ref";
|
|
23
26
|
slots: {};
|
|
24
27
|
events: {};
|
|
25
28
|
};
|
|
@@ -27,7 +30,7 @@ declare class __sveltets_Render<Item> {
|
|
|
27
30
|
props(): ReturnType<typeof $$render<Item>>['props'];
|
|
28
31
|
events(): ReturnType<typeof $$render<Item>>['events'];
|
|
29
32
|
slots(): ReturnType<typeof $$render<Item>>['slots'];
|
|
30
|
-
bindings(): "";
|
|
33
|
+
bindings(): "ref";
|
|
31
34
|
exports(): {};
|
|
32
35
|
}
|
|
33
36
|
interface $$IsomorphicComponent {
|
|
@@ -1,6 +1,8 @@
|
|
|
1
1
|
import type { Snippet } from 'svelte';
|
|
2
2
|
import type { HTMLAttributes } from 'svelte/elements';
|
|
3
3
|
import type { VirtualListKey } from '../../utilities/fixed-virtual-window.ts';
|
|
4
|
+
import type { VirtualListScrollAlign } from './_internal/measurement-window.ts';
|
|
5
|
+
export type { VirtualListScrollAlign };
|
|
4
6
|
export type VirtualListRowContext = {
|
|
5
7
|
/** Zero-based index of the item in the full items array. */
|
|
6
8
|
index: number;
|
|
@@ -8,24 +10,77 @@ export type VirtualListRowContext = {
|
|
|
8
10
|
key: VirtualListKey;
|
|
9
11
|
/** Pixel offset from the top of the full virtual list. */
|
|
10
12
|
start: number;
|
|
11
|
-
/** Pixel height of this
|
|
13
|
+
/** Pixel height of this row: the measured size under `dynamicSize`, otherwise `itemHeight`. */
|
|
12
14
|
size: number;
|
|
13
15
|
};
|
|
16
|
+
/** Options for `VirtualListRef.scrollToIndex`. */
|
|
17
|
+
export type VirtualListScrollToIndexOptions = {
|
|
18
|
+
/**
|
|
19
|
+
* Where the target row lands in the viewport. Defaults to `'auto'`, which
|
|
20
|
+
* leaves the scroll position alone when the row is already fully visible.
|
|
21
|
+
*/
|
|
22
|
+
align?: VirtualListScrollAlign;
|
|
23
|
+
/** Scroll behavior. Defaults to `'auto'`. */
|
|
24
|
+
behavior?: ScrollBehavior;
|
|
25
|
+
};
|
|
26
|
+
/**
|
|
27
|
+
* Programmatic VirtualList handle exposed through `bind:ref`.
|
|
28
|
+
*/
|
|
29
|
+
export type VirtualListRef = {
|
|
30
|
+
/**
|
|
31
|
+
* Scrolls the item at `index` into view. Under `dynamicSize` this accounts for
|
|
32
|
+
* the measured size of every row before the target, and re-settles if rows
|
|
33
|
+
* above it are measured for the first time mid-scroll. Out-of-range indexes
|
|
34
|
+
* are clamped to the list's bounds.
|
|
35
|
+
*/
|
|
36
|
+
scrollToIndex: (index: number, options?: VirtualListScrollToIndexOptions) => void;
|
|
37
|
+
};
|
|
14
38
|
export type VirtualListProps<Item = unknown> = Omit<HTMLAttributes<HTMLDivElement>, 'class' | 'tabindex'> & {
|
|
15
39
|
/** Items in full logical order. Only the visible window is mounted. */
|
|
16
40
|
items: readonly Item[];
|
|
17
41
|
/**
|
|
18
|
-
*
|
|
19
|
-
*
|
|
42
|
+
* Each item's extent in pixels along the axis being scrolled: its height by
|
|
43
|
+
* default, or its width under `horizontal`. By default every row is assumed to
|
|
44
|
+
* be exactly this size. When `dynamicSize` is true this becomes the initial
|
|
45
|
+
* estimate for rows that have not been measured yet.
|
|
20
46
|
*/
|
|
21
47
|
itemHeight: number;
|
|
48
|
+
/**
|
|
49
|
+
* Measure each rendered row with `ResizeObserver` and cache the result,
|
|
50
|
+
* instead of assuming every row is exactly `itemHeight` along the scrolled
|
|
51
|
+
* axis. Use this when rows wrap, contain images, or otherwise vary in size.
|
|
52
|
+
* Composes with `horizontal`, where each row is measured by its width.
|
|
53
|
+
*
|
|
54
|
+
* Defaults to `false`. While false, no row is measured, no size is cached,
|
|
55
|
+
* and no scroll correction runs — the fixed-height path stays the fast path.
|
|
56
|
+
* The component still observes its own scroll container to track viewport
|
|
57
|
+
* size, as it always has; that is independent of this prop.
|
|
58
|
+
*/
|
|
59
|
+
dynamicSize?: boolean;
|
|
60
|
+
/**
|
|
61
|
+
* Scrolls and lays rows out along the inline axis instead of the block axis.
|
|
62
|
+
*
|
|
63
|
+
* `itemHeight` and `height` are REINTERPRETED rather than renamed: `itemHeight`
|
|
64
|
+
* becomes each item's width in pixels along the main axis, and `height` becomes
|
|
65
|
+
* the container's inline-size. The `--cinder-virtual-list-height` custom property
|
|
66
|
+
* keeps its name too and switches to driving `inline-size`, so an existing theme
|
|
67
|
+
* override keeps working when this is turned on.
|
|
68
|
+
*
|
|
69
|
+
* Right-to-left is handled: the writing direction is resolved from the container's
|
|
70
|
+
* computed style at mount, and the scroll offset is read from the start (right)
|
|
71
|
+
* edge in that case.
|
|
72
|
+
*
|
|
73
|
+
* Defaults to false.
|
|
74
|
+
*/
|
|
75
|
+
horizontal?: boolean;
|
|
22
76
|
/**
|
|
23
77
|
* Extra rows rendered before and after the visible window.
|
|
24
78
|
* Defaults to 5.
|
|
25
79
|
*/
|
|
26
80
|
overscan?: number;
|
|
27
81
|
/**
|
|
28
|
-
* CSS
|
|
82
|
+
* CSS extent of the native scroll container across the axis it scrolls: its
|
|
83
|
+
* block-size by default, or its inline-size under `horizontal`.
|
|
29
84
|
* Defaults to `"20rem"`.
|
|
30
85
|
*/
|
|
31
86
|
height?: string;
|
|
@@ -35,6 +90,119 @@ export type VirtualListProps<Item = unknown> = Omit<HTMLAttributes<HTMLDivElemen
|
|
|
35
90
|
* scroll position unchanged.
|
|
36
91
|
*/
|
|
37
92
|
stickToBottom?: boolean;
|
|
93
|
+
/**
|
|
94
|
+
* Chat-transcript behaviour: the list starts at its end and returns there on
|
|
95
|
+
* every append.
|
|
96
|
+
*
|
|
97
|
+
* Items stay in their natural order — oldest at index 0, newest last. `reverse`
|
|
98
|
+
* names the anchoring, not the ordering, and the array is never flipped.
|
|
99
|
+
*
|
|
100
|
+
* Deliberately distinct from `stickToBottom`, which pins only when the reader is
|
|
101
|
+
* already at the bottom. `reverse` pins on every append regardless of where the
|
|
102
|
+
* reader is. When both are set, `reverse` wins.
|
|
103
|
+
*
|
|
104
|
+
* Prepending — loading a page of older history — never moves the reader: the row
|
|
105
|
+
* they were looking at stays put while the list grows above it.
|
|
106
|
+
*
|
|
107
|
+
* That last guarantee REQUIRES `getKey`. Telling a prepend from an append means
|
|
108
|
+
* comparing key sequences, and without `getKey` the keys are array indexes: a
|
|
109
|
+
* prepend turns `[0, 1, 2]` into `[0, 1, 2, 3, 4]`, which is indistinguishable
|
|
110
|
+
* from an append and pins the reader to the end instead of holding their place.
|
|
111
|
+
* Pass `getKey` whenever the list can grow at the front.
|
|
112
|
+
*
|
|
113
|
+
* Defaults to false.
|
|
114
|
+
*/
|
|
115
|
+
reverse?: boolean;
|
|
116
|
+
/**
|
|
117
|
+
* Called when the reader scrolls within `overscan` items of the end of the list.
|
|
118
|
+
*
|
|
119
|
+
* Explicitly `| undefined` rather than merely optional: this package compiles with
|
|
120
|
+
* `exactOptionalPropertyTypes`, under which the two differ, and a consumer writing
|
|
121
|
+
* `onEndReached={enabled ? load : undefined}` would otherwise fail to typecheck.
|
|
122
|
+
*
|
|
123
|
+
* Fires once per approach, not once per scroll event, and re-arms when the item
|
|
124
|
+
* count changes — so appending in response to it allows the next approach to fire
|
|
125
|
+
* while a source that returns nothing does not spin.
|
|
126
|
+
*/
|
|
127
|
+
onEndReached?: (() => void) | undefined;
|
|
128
|
+
/**
|
|
129
|
+
* Called when the reader scrolls within `overscan` items of the start of the
|
|
130
|
+
* list. Pair with `onEndReached` for bi-directional infinite scroll.
|
|
131
|
+
*
|
|
132
|
+
* Latched the same way as `onEndReached`. Prepending in response preserves the
|
|
133
|
+
* reader's position rather than jumping to the new start — but only with `getKey`,
|
|
134
|
+
* since index-derived keys make a prepend look exactly like an append.
|
|
135
|
+
*/
|
|
136
|
+
onStartReached?: (() => void) | undefined;
|
|
137
|
+
/**
|
|
138
|
+
* Remember the scroll position across navigation, keyed by
|
|
139
|
+
* `scrollRestorationId`.
|
|
140
|
+
*
|
|
141
|
+
* The position is written to `sessionStorage` when the list tears down, and read
|
|
142
|
+
* back when it mounts. Deliberately not on every scroll: that would mean a
|
|
143
|
+
* storage write per frame during a fling, and teardown is the last moment the
|
|
144
|
+
* position is knowable anyway. The consequence is that a tab closed by a crash,
|
|
145
|
+
* rather than by navigating away, will not have saved.
|
|
146
|
+
*
|
|
147
|
+
* Storage failures are swallowed: a browser in private mode or at its quota throws
|
|
148
|
+
* on write — and on read — and losing a remembered offset must not break the list.
|
|
149
|
+
*
|
|
150
|
+
* Has no effect without a `scrollRestorationId` — see that prop for why.
|
|
151
|
+
*
|
|
152
|
+
* Explicitly `| undefined`, like the other conditionally-supplied props: this
|
|
153
|
+
* package compiles with `exactOptionalPropertyTypes`, under which optional and
|
|
154
|
+
* undefined-valued differ, and `scrollRestoration={enabled ? true : undefined}`
|
|
155
|
+
* would otherwise fail to typecheck.
|
|
156
|
+
*
|
|
157
|
+
* Defaults to false.
|
|
158
|
+
*/
|
|
159
|
+
scrollRestoration?: boolean | undefined;
|
|
160
|
+
/**
|
|
161
|
+
* Item indexes that stay visible at the leading edge while the reader scrolls
|
|
162
|
+
* past them — section headers in a grouped list, most often.
|
|
163
|
+
*
|
|
164
|
+
* A sticky row is kept mounted even after its own index leaves the rendered
|
|
165
|
+
* window, which is the part virtualization would otherwise break: unmounting it
|
|
166
|
+
* would make the heading vanish exactly when it is meant to be pinned.
|
|
167
|
+
*
|
|
168
|
+
* Indexes outside the list, duplicates, and non-integers are dropped rather than
|
|
169
|
+
* throwing — a bad sticky index is a cosmetic problem, not a correctness one.
|
|
170
|
+
*/
|
|
171
|
+
stickyItems?: number[];
|
|
172
|
+
/**
|
|
173
|
+
* Animate `scrollToIndex` by default instead of jumping.
|
|
174
|
+
*
|
|
175
|
+
* Equivalent to passing `behavior: 'smooth'` on every call; an explicit
|
|
176
|
+
* `behavior` in the call's options still wins. Scroll corrections under
|
|
177
|
+
* `dynamicSize` are never animated whatever this is set to — a smooth
|
|
178
|
+
* correction would visibly perform the jump it exists to hide.
|
|
179
|
+
*
|
|
180
|
+
* Defaults to false.
|
|
181
|
+
*/
|
|
182
|
+
smoothScroll?: boolean;
|
|
183
|
+
/**
|
|
184
|
+
* Grow `overscan` while the reader is scrolling fast, and shrink it back when
|
|
185
|
+
* they slow down.
|
|
186
|
+
*
|
|
187
|
+
* `overscan` becomes a floor rather than a fixed value: a fast fling renders
|
|
188
|
+
* further ahead to cut pop-in, and a stationary list falls back to exactly what
|
|
189
|
+
* was configured so the DOM stays small. The growth is bounded, because an
|
|
190
|
+
* unbounded overscan during a fling would mount thousands of rows and defeat the
|
|
191
|
+
* point of virtualizing at all.
|
|
192
|
+
*
|
|
193
|
+
* Defaults to false.
|
|
194
|
+
*/
|
|
195
|
+
adaptiveOverscan?: boolean;
|
|
196
|
+
/**
|
|
197
|
+
* Stable id under which `scrollRestoration` saves this list's position.
|
|
198
|
+
*
|
|
199
|
+
* Required for restoration to do anything. There is deliberately no default:
|
|
200
|
+
* an implicit key derived from position or order would silently hand one
|
|
201
|
+
* list's remembered offset to a different list after a refactor, and two lists
|
|
202
|
+
* on one page would overwrite each other. Choose something tied to what the
|
|
203
|
+
* list shows, such as a route or collection name.
|
|
204
|
+
*/
|
|
205
|
+
scrollRestorationId?: string | undefined;
|
|
38
206
|
/**
|
|
39
207
|
* Override the default focus behavior. The component sets `tabindex="0"`
|
|
40
208
|
* by default so keyboard users can reach the native scroll container for
|
|
@@ -45,10 +213,15 @@ export type VirtualListProps<Item = unknown> = Omit<HTMLAttributes<HTMLDivElemen
|
|
|
45
213
|
/**
|
|
46
214
|
* Stable key extractor. Omit only when items are append-only and never
|
|
47
215
|
* reordered; the component will fall back to full-array indexes.
|
|
216
|
+
*
|
|
217
|
+
* Required in practice under `dynamicSize`: measured sizes are cached by key,
|
|
218
|
+
* so index-derived keys will mis-attribute cached sizes if items ever reorder.
|
|
48
219
|
*/
|
|
49
220
|
getKey?: (item: Item, index: number) => VirtualListKey;
|
|
50
221
|
/** Rendered row snippet. Receives the item and its virtual row context. */
|
|
51
222
|
row: Snippet<[Item, VirtualListRowContext]>;
|
|
52
223
|
/** Additional class names merged with `.cinder-virtual-list`. */
|
|
53
224
|
class?: string;
|
|
225
|
+
/** Typed programmatic handle. Use `bind:ref` to receive it. */
|
|
226
|
+
ref?: VirtualListRef | undefined;
|
|
54
227
|
};
|