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