@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,130 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Pure edge-proximity detection for bi-directional infinite scroll in a
|
|
3
|
+
* virtual list (CIN-195 `onEndReached`, CIN-196 `onStartReached`).
|
|
4
|
+
*
|
|
5
|
+
* Deciding "are we near an edge" is simple index arithmetic. The hard part —
|
|
6
|
+
* and the entire reason this module exists — is deciding WHEN to fire a
|
|
7
|
+
* callback for that proximity, so a reader who scrolls around near the same
|
|
8
|
+
* edge, or who simply triggers a re-render while still sitting there, does
|
|
9
|
+
* not retrigger a data fetch on every frame. `resolveEdgeFireDecision` is
|
|
10
|
+
* the latch that answers that question; `resolveEdgeProximity` only
|
|
11
|
+
* computes the raw boolean state the latch reacts to.
|
|
12
|
+
*
|
|
13
|
+
* Dependency-free by design, matching the rest of `_internal/`: no DOM, no
|
|
14
|
+
* runes, no timers. `virtual-list.svelte` is expected to call
|
|
15
|
+
* `resolveEdgeProximity` once per scroll/measurement update, feed the
|
|
16
|
+
* result into `resolveEdgeFireDecision` alongside the latch state carried
|
|
17
|
+
* from the previous call, and store `next` for the following call.
|
|
18
|
+
*/
|
|
19
|
+
|
|
20
|
+
/** Whether the current window sits close enough to either edge of the list to consider firing a load callback. */
|
|
21
|
+
export type EdgeProximity = {
|
|
22
|
+
readonly isNearStart: boolean;
|
|
23
|
+
readonly isNearEnd: boolean;
|
|
24
|
+
};
|
|
25
|
+
|
|
26
|
+
/**
|
|
27
|
+
* Anti-repeat latch state carried between calls to `resolveEdgeFireDecision`.
|
|
28
|
+
* A latched edge has already fired for the CURRENT approach and stays
|
|
29
|
+
* suppressed until either the reader scrolls away (proximity goes false) or
|
|
30
|
+
* `itemCount` moves away from `itemCountAtLatch` — new items arrived in
|
|
31
|
+
* response to whatever fired last time, so the next approach is treated as
|
|
32
|
+
* genuinely new.
|
|
33
|
+
*/
|
|
34
|
+
export type EdgeLatch = {
|
|
35
|
+
readonly startLatched: boolean;
|
|
36
|
+
readonly endLatched: boolean;
|
|
37
|
+
/** itemCount as of the call that produced the current startLatched/endLatched values. */
|
|
38
|
+
readonly itemCountAtLatch: number;
|
|
39
|
+
};
|
|
40
|
+
|
|
41
|
+
/** The initial, unlatched state — nothing has fired yet. */
|
|
42
|
+
export function createEdgeLatch(): EdgeLatch {
|
|
43
|
+
return { startLatched: false, endLatched: false, itemCountAtLatch: 0 };
|
|
44
|
+
}
|
|
45
|
+
|
|
46
|
+
/**
|
|
47
|
+
* Computes raw start/end proximity from the current window and list shape.
|
|
48
|
+
* This is pure index arithmetic with no memory of prior calls — repeat-fire
|
|
49
|
+
* suppression is `resolveEdgeFireDecision`'s job, not this function's.
|
|
50
|
+
*/
|
|
51
|
+
export function resolveEdgeProximity(options: {
|
|
52
|
+
/**
|
|
53
|
+
* Accepted for parity with the sibling window/geometry helpers' options
|
|
54
|
+
* shape — every one of them takes a scroll offset — but proximity here is
|
|
55
|
+
* decided entirely in item-index space, so this field is not read.
|
|
56
|
+
*/
|
|
57
|
+
scrollOffset: number;
|
|
58
|
+
viewportSize: number;
|
|
59
|
+
totalSize: number;
|
|
60
|
+
firstVisibleIndex: number;
|
|
61
|
+
lastVisibleIndex: number;
|
|
62
|
+
itemCount: number;
|
|
63
|
+
overscan: number;
|
|
64
|
+
}): EdgeProximity {
|
|
65
|
+
// An empty list has no edges to reach. Reporting proximity here would let a
|
|
66
|
+
// caller fire a load callback against a source that, by definition, just
|
|
67
|
+
// returned nothing — and nothing would ever stop it from firing again.
|
|
68
|
+
if (options.itemCount <= 0) {
|
|
69
|
+
return { isNearStart: false, isNearEnd: false };
|
|
70
|
+
}
|
|
71
|
+
|
|
72
|
+
// A negative overscan would make every index comparison below vacuously
|
|
73
|
+
// false; a non-finite one (NaN from a bad measurement, +/-Infinity) would
|
|
74
|
+
// make every comparison vacuously true, or produce NaN comparisons that are
|
|
75
|
+
// always false. Neither is a usable threshold, so both collapse to 0.
|
|
76
|
+
const resolvedOverscan = Number.isFinite(options.overscan) ? Math.max(0, options.overscan) : 0;
|
|
77
|
+
|
|
78
|
+
// The whole list is already on screen, so there is no further scroll
|
|
79
|
+
// gesture that could bring either edge "more" into view. Reporting both
|
|
80
|
+
// edges as near lets a short list (e.g. the very first page of a
|
|
81
|
+
// bi-directional feed) still request the next and previous pages, instead
|
|
82
|
+
// of being stuck because it never crosses an overscan threshold it is
|
|
83
|
+
// already past.
|
|
84
|
+
if (options.totalSize <= options.viewportSize) {
|
|
85
|
+
return { isNearStart: true, isNearEnd: true };
|
|
86
|
+
}
|
|
87
|
+
|
|
88
|
+
return {
|
|
89
|
+
isNearStart: options.firstVisibleIndex <= resolvedOverscan,
|
|
90
|
+
isNearEnd: options.lastVisibleIndex >= options.itemCount - 1 - resolvedOverscan,
|
|
91
|
+
};
|
|
92
|
+
}
|
|
93
|
+
|
|
94
|
+
/**
|
|
95
|
+
* Turns raw proximity into a fire/no-fire decision via rising-edge
|
|
96
|
+
* detection: an edge fires only on the call where its proximity flips from
|
|
97
|
+
* not-near to near, or where `itemCount` moved since the latch was last set
|
|
98
|
+
* — which counts as a fresh approach even though proximity never dropped to
|
|
99
|
+
* false in between. Never mutates `previous`; callers store the returned
|
|
100
|
+
* `next` for the following call.
|
|
101
|
+
*/
|
|
102
|
+
export function resolveEdgeFireDecision(options: {
|
|
103
|
+
proximity: EdgeProximity;
|
|
104
|
+
previous: EdgeLatch;
|
|
105
|
+
itemCount: number;
|
|
106
|
+
}): { fireStart: boolean; fireEnd: boolean; next: EdgeLatch } {
|
|
107
|
+
// itemCount changing since the latch was set is direct evidence a batch of
|
|
108
|
+
// items landed in response to whatever fired last time, so treat any latch
|
|
109
|
+
// recorded against the old count as already released rather than requiring
|
|
110
|
+
// proximity to first drop to false and back to true. Without this, a list
|
|
111
|
+
// sitting still near one edge while new items keep arriving there would
|
|
112
|
+
// fire exactly once and never again — which is the one case that makes
|
|
113
|
+
// infinite scroll actually work.
|
|
114
|
+
const itemCountChangedSinceLatch = options.itemCount !== options.previous.itemCountAtLatch;
|
|
115
|
+
const startWasLatched = options.previous.startLatched && !itemCountChangedSinceLatch;
|
|
116
|
+
const endWasLatched = options.previous.endLatched && !itemCountChangedSinceLatch;
|
|
117
|
+
|
|
118
|
+
const fireStart = options.proximity.isNearStart && !startWasLatched;
|
|
119
|
+
const fireEnd = options.proximity.isNearEnd && !endWasLatched;
|
|
120
|
+
|
|
121
|
+
return {
|
|
122
|
+
fireStart,
|
|
123
|
+
fireEnd,
|
|
124
|
+
next: {
|
|
125
|
+
startLatched: options.proximity.isNearStart,
|
|
126
|
+
endLatched: options.proximity.isNearEnd,
|
|
127
|
+
itemCountAtLatch: options.itemCount,
|
|
128
|
+
},
|
|
129
|
+
};
|
|
130
|
+
}
|
|
@@ -0,0 +1,136 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* A frame-scheduling port pair: `request` queues a callback for "the next
|
|
3
|
+
* frame" and returns an id `cancel` can later use to drop it before it
|
|
4
|
+
* fires. Shaped as data (not a class) so a test can hand `FrameBatcher` a
|
|
5
|
+
* fully deterministic fake instead of depending on real
|
|
6
|
+
* `requestAnimationFrame` timing.
|
|
7
|
+
*/
|
|
8
|
+
export type FrameScheduler = {
|
|
9
|
+
readonly request: (callback: (time: number) => void) => number;
|
|
10
|
+
readonly cancel: (id: number) => void;
|
|
11
|
+
};
|
|
12
|
+
|
|
13
|
+
/**
|
|
14
|
+
* Sentinel id returned by {@link rafFrameScheduler}'s `request` when no
|
|
15
|
+
* `requestAnimationFrame` exists in this environment (server rendering).
|
|
16
|
+
* `cancel` treats it as any other id — real `cancelAnimationFrame`
|
|
17
|
+
* implementations silently ignore an id they never issued, so no special
|
|
18
|
+
* case is needed there.
|
|
19
|
+
*/
|
|
20
|
+
const NO_ANIMATION_FRAME_ID = -1;
|
|
21
|
+
|
|
22
|
+
/**
|
|
23
|
+
* The real {@link FrameScheduler}, backed by `requestAnimationFrame` /
|
|
24
|
+
* `cancelAnimationFrame`.
|
|
25
|
+
*
|
|
26
|
+
* Both globals are looked up lazily, INSIDE `request`/`cancel`, never at
|
|
27
|
+
* module scope — referencing the bare identifier `requestAnimationFrame` at
|
|
28
|
+
* module scope throws a `ReferenceError` the instant this module is
|
|
29
|
+
* imported in a server-rendering environment, where no such global exists.
|
|
30
|
+
* CIN-205 requires the whole `virtual-list` module tree to import cleanly
|
|
31
|
+
* under SSR, so this module must not throw merely by being loaded, and
|
|
32
|
+
* `request`/`cancel` must not throw merely by being called there either —
|
|
33
|
+
* when `requestAnimationFrame` is absent, `request` reports
|
|
34
|
+
* {@link NO_ANIMATION_FRAME_ID} and never invokes the callback. Nothing on
|
|
35
|
+
* the server needs it to: Svelte does not run `$effect`s during SSR, so a
|
|
36
|
+
* `FrameBatcher` built on this scheduler never runs there either.
|
|
37
|
+
*
|
|
38
|
+
* Nothing in the component calls this today. It was written for the
|
|
39
|
+
* `windowScroll` adapter, which was split out of this work and is tracked as
|
|
40
|
+
* CIN-197; it stays here so that work does not start from nothing, but it
|
|
41
|
+
* describes a caller that does not exist yet rather than one that does.
|
|
42
|
+
*
|
|
43
|
+
* A `FrameBatcher` built on this fallback path stays permanently inert
|
|
44
|
+
* after its first `recordRead` — `request` returning without ever calling
|
|
45
|
+
* back means nothing clears the batcher's "a frame is already scheduled"
|
|
46
|
+
* flag, so later reads coalesce into a commit that never fires. This is the
|
|
47
|
+
* intended shape of "fall back safely": no throw, no leaked timer, at the
|
|
48
|
+
* cost of the batch simply never landing in an environment with no frames
|
|
49
|
+
* to schedule onto in the first place.
|
|
50
|
+
*/
|
|
51
|
+
export const rafFrameScheduler: FrameScheduler = {
|
|
52
|
+
request(callback) {
|
|
53
|
+
// Invoked through globalThis rather than copied into a local first: browsers
|
|
54
|
+
// that enforce the Web API receiver for Window methods throw "Illegal
|
|
55
|
+
// invocation" when one is called bare.
|
|
56
|
+
if (typeof globalThis.requestAnimationFrame === 'function') {
|
|
57
|
+
return globalThis.requestAnimationFrame(callback);
|
|
58
|
+
}
|
|
59
|
+
return NO_ANIMATION_FRAME_ID;
|
|
60
|
+
},
|
|
61
|
+
cancel(id) {
|
|
62
|
+
if (typeof globalThis.cancelAnimationFrame === 'function') {
|
|
63
|
+
globalThis.cancelAnimationFrame(id);
|
|
64
|
+
}
|
|
65
|
+
},
|
|
66
|
+
};
|
|
67
|
+
|
|
68
|
+
/** A `recordRead` call captured for the frame currently awaiting commit. */
|
|
69
|
+
type PendingRead<T> = {
|
|
70
|
+
readonly value: T;
|
|
71
|
+
};
|
|
72
|
+
|
|
73
|
+
/**
|
|
74
|
+
* Coalesces N calls to recordRead within one frame into a single onCommit call on the
|
|
75
|
+
* NEXT scheduled frame. This is CIN-202's mechanism for reads that Svelte's own
|
|
76
|
+
* $effect.pre/$effect ordering does NOT already cover — specifically, genuinely
|
|
77
|
+
* layout-forcing reads like getBoundingClientRect — which is what the `windowScroll`
|
|
78
|
+
* adapter will need, and why this exists ahead of it (CIN-197).
|
|
79
|
+
* Plain $state-driven scroll-offset correction uses the $effect.pre/$effect split
|
|
80
|
+
* instead (see "The engine" — CIN-202 interpretation).
|
|
81
|
+
*/
|
|
82
|
+
export class FrameBatcher<T> {
|
|
83
|
+
readonly #onCommit: (value: T) => void;
|
|
84
|
+
readonly #scheduler: FrameScheduler;
|
|
85
|
+
#pending: PendingRead<T> | null = null;
|
|
86
|
+
#frameId: number | null = null;
|
|
87
|
+
#disposed = false;
|
|
88
|
+
|
|
89
|
+
/**
|
|
90
|
+
* @param onCommit Called with the LAST value passed to `recordRead` since
|
|
91
|
+
* the previous commit, once per scheduled frame.
|
|
92
|
+
* @param scheduler Defaults to {@link rafFrameScheduler}. Tests inject a
|
|
93
|
+
* fake to make coalescing deterministic instead of depending on real
|
|
94
|
+
* frame timing.
|
|
95
|
+
*/
|
|
96
|
+
constructor(onCommit: (value: T) => void, scheduler: FrameScheduler = rafFrameScheduler) {
|
|
97
|
+
this.#onCommit = onCommit;
|
|
98
|
+
this.#scheduler = scheduler;
|
|
99
|
+
}
|
|
100
|
+
|
|
101
|
+
/**
|
|
102
|
+
* Records `value` as the pending read for the frame currently in flight,
|
|
103
|
+
* overwriting any value already recorded for that frame. Schedules a
|
|
104
|
+
* commit frame on the first call after a batch has committed (or after
|
|
105
|
+
* construction); every subsequent call before that frame fires just
|
|
106
|
+
* updates the pending value without scheduling a second frame. A no-op
|
|
107
|
+
* after {@link dispose}.
|
|
108
|
+
*/
|
|
109
|
+
recordRead(value: T): void {
|
|
110
|
+
if (this.#disposed) return;
|
|
111
|
+
this.#pending = { value };
|
|
112
|
+
if (this.#frameId !== null) return;
|
|
113
|
+
this.#frameId = this.#scheduler.request(() => {
|
|
114
|
+
this.#frameId = null;
|
|
115
|
+
const pending = this.#pending;
|
|
116
|
+
this.#pending = null;
|
|
117
|
+
if (this.#disposed || pending === null) return;
|
|
118
|
+
this.#onCommit(pending.value);
|
|
119
|
+
});
|
|
120
|
+
}
|
|
121
|
+
|
|
122
|
+
/**
|
|
123
|
+
* Cancels any frame currently scheduled — dropping its pending value
|
|
124
|
+
* without committing it — and makes every later `recordRead` inert.
|
|
125
|
+
* Idempotent.
|
|
126
|
+
*/
|
|
127
|
+
dispose(): void {
|
|
128
|
+
if (this.#disposed) return;
|
|
129
|
+
this.#disposed = true;
|
|
130
|
+
if (this.#frameId !== null) {
|
|
131
|
+
this.#scheduler.cancel(this.#frameId);
|
|
132
|
+
this.#frameId = null;
|
|
133
|
+
}
|
|
134
|
+
this.#pending = null;
|
|
135
|
+
}
|
|
136
|
+
}
|
|
@@ -0,0 +1,236 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Pure axis and writing-direction geometry for `horizontal` and RTL support
|
|
3
|
+
* (CIN-191, CIN-192).
|
|
4
|
+
*
|
|
5
|
+
* Everything below is dependency-free: no `ResizeObserver`, no runes, and —
|
|
6
|
+
* with the sole exception of {@link domWritingDirectionReader}'s two
|
|
7
|
+
* one-line DOM reads — no direct DOM access either. It is held to the
|
|
8
|
+
* 100%-lines/100%-functions coverage floor (see `coverage-ratchet.json`)
|
|
9
|
+
* because none of it needs live layout to exercise every branch; the reader
|
|
10
|
+
* indirection in {@link resolveWritingDirection} is exactly what makes that
|
|
11
|
+
* true for RTL detection too, despite happy-dom's `getComputedStyle` being
|
|
12
|
+
* blind to the `dir` attribute (see that function's doc comment).
|
|
13
|
+
*/
|
|
14
|
+
|
|
15
|
+
/** A CSS writing direction, resolved to exactly one of the two real values. */
|
|
16
|
+
export type WritingDirection = 'ltr' | 'rtl';
|
|
17
|
+
|
|
18
|
+
/**
|
|
19
|
+
* Reads the two direction signals {@link resolveWritingDirection} needs,
|
|
20
|
+
* behind an interface so a test can inject a fake instead of depending on a
|
|
21
|
+
* real, connected DOM tree and a browser that reflects `dir` through
|
|
22
|
+
* `getComputedStyle` — which happy-dom does not (see that function's doc
|
|
23
|
+
* comment).
|
|
24
|
+
*/
|
|
25
|
+
export type WritingDirectionReader = {
|
|
26
|
+
/** Should return the raw `getComputedStyle(element).direction` value in production. */
|
|
27
|
+
readonly getComputedDirection: (element: Element) => string;
|
|
28
|
+
/** Should return `element.closest('[dir]')?.getAttribute('dir') ?? null` in production. */
|
|
29
|
+
readonly closestDirAttribute: (element: Element) => string | null;
|
|
30
|
+
};
|
|
31
|
+
|
|
32
|
+
/**
|
|
33
|
+
* Resolves the writing direction that should govern scroll-offset reading
|
|
34
|
+
* for `element`.
|
|
35
|
+
*
|
|
36
|
+
* Reads the reader's computed-direction value FIRST — this is CIN-192's
|
|
37
|
+
* literal AC text ("RTL is detected via `getComputedStyle(element).direction`"),
|
|
38
|
+
* so computed style must genuinely be the primary source, not a fallback. If
|
|
39
|
+
* it reports `'rtl'`, that wins outright, with no further reads. If it
|
|
40
|
+
* reports `'ltr'`, this falls back to the nearest `[dir]` ancestor
|
|
41
|
+
* attribute — the seam that makes this function testable at all under
|
|
42
|
+
* happy-dom, whose `getComputedStyle` always answers `'ltr'` regardless of
|
|
43
|
+
* any `dir="rtl"` ancestor attribute.
|
|
44
|
+
*
|
|
45
|
+
* The injectable {@link WritingDirectionReader} is the whole point: it lets
|
|
46
|
+
* a test assert the PRIORITY RULE — computed style wins even over a
|
|
47
|
+
* conflicting `dir` attribute — which a hard-coded `getComputedStyle` call
|
|
48
|
+
* could never demonstrate under happy-dom, since there both signals would
|
|
49
|
+
* always agree.
|
|
50
|
+
*
|
|
51
|
+
* Accepted, documented gap: a real element with an explicit
|
|
52
|
+
* `direction: ltr` CSS override nested inside a `dir="rtl"` ancestor is
|
|
53
|
+
* misread as `rtl` by the fallback, because the fallback only looks at the
|
|
54
|
+
* attribute, never at computed style further up the tree. Narrow and
|
|
55
|
+
* disclosed, not silent — the AC's own detection mechanism is computed
|
|
56
|
+
* style on `element` itself, not on every ancestor.
|
|
57
|
+
*
|
|
58
|
+
* The attribute fallback is compared case-insensitively: HTML's `dir`
|
|
59
|
+
* attribute is defined case-insensitively (`dir="RTL"` is exactly as valid
|
|
60
|
+
* as `dir="rtl"`), matching this codebase's own `_internal/text-direction.ts`.
|
|
61
|
+
*/
|
|
62
|
+
export function resolveWritingDirection(
|
|
63
|
+
element: Element | null | undefined,
|
|
64
|
+
reader: WritingDirectionReader,
|
|
65
|
+
): WritingDirection {
|
|
66
|
+
if (!element) return 'ltr';
|
|
67
|
+
|
|
68
|
+
// Computed style is authoritative WHENEVER IT ANSWERS — including when it
|
|
69
|
+
// answers 'ltr'. An earlier version fell through to the `dir` attribute on
|
|
70
|
+
// anything that was not 'rtl', which inverted the priority CIN-192 asks for: an
|
|
71
|
+
// element carrying an explicit `direction: ltr` override inside a `dir="rtl"`
|
|
72
|
+
// ancestor was reported as rtl, contradicting what the browser actually renders.
|
|
73
|
+
const computed = reader.getComputedDirection(element)?.toLowerCase();
|
|
74
|
+
if (computed === 'rtl') return 'rtl';
|
|
75
|
+
if (computed === 'ltr') return 'ltr';
|
|
76
|
+
|
|
77
|
+
// Only when computed style yields nothing usable — a detached element, or an
|
|
78
|
+
// environment that does not compute style — does the attribute get a say.
|
|
79
|
+
return reader.closestDirAttribute(element)?.toLowerCase() === 'rtl' ? 'rtl' : 'ltr';
|
|
80
|
+
}
|
|
81
|
+
|
|
82
|
+
/**
|
|
83
|
+
* The real {@link WritingDirectionReader}, backed by `getComputedStyle` and
|
|
84
|
+
* `Element.closest`.
|
|
85
|
+
*
|
|
86
|
+
* Both lookups live inside the method bodies below — `getComputedStyle` is
|
|
87
|
+
* never referenced at module scope — so importing this module never
|
|
88
|
+
* touches it; it is only evaluated the first time a caller actually invokes
|
|
89
|
+
* `getComputedDirection`, which in `virtual-list.svelte` happens
|
|
90
|
+
* exclusively inside a mount `$effect`. That keeps this module safely
|
|
91
|
+
* importable during server rendering (CIN-205), where `getComputedStyle`
|
|
92
|
+
* does not exist. Under happy-dom both methods return a defined value for
|
|
93
|
+
* any real `Element` — `getComputedStyle` a direction string, `closest` a
|
|
94
|
+
* matching ancestor or `null` — so every line here is exercised by a plain
|
|
95
|
+
* Bun test, with no need to stub or delete either global.
|
|
96
|
+
*/
|
|
97
|
+
export const domWritingDirectionReader: WritingDirectionReader = {
|
|
98
|
+
getComputedDirection: (element) => getComputedStyle(element).direction,
|
|
99
|
+
closestDirAttribute: (element) => element.closest('[dir]')?.getAttribute('dir') ?? null,
|
|
100
|
+
};
|
|
101
|
+
|
|
102
|
+
/**
|
|
103
|
+
* The historical `scrollLeft` conventions browsers have used for
|
|
104
|
+
* right-to-left content. Irrelevant under `ltr`, where `scrollLeft` has
|
|
105
|
+
* always meant the same thing everywhere.
|
|
106
|
+
*/
|
|
107
|
+
export type RtlScrollType = 'default' | 'negative' | 'reverse';
|
|
108
|
+
|
|
109
|
+
/**
|
|
110
|
+
* Classifies which RTL `scrollLeft` convention a browser implements, from two
|
|
111
|
+
* probe readings taken on a throwaway right-to-left scroll container.
|
|
112
|
+
*
|
|
113
|
+
* Pure, so the classification is testable without a browser — the caller supplies
|
|
114
|
+
* the readings. The probe itself is a handful of DOM writes and lives in the
|
|
115
|
+
* component, because nothing in this module may touch the DOM.
|
|
116
|
+
*
|
|
117
|
+
* Detection rather than assumption is deliberate. The three conventions are told
|
|
118
|
+
* apart by observable behaviour, and picking one by name is how the sign silently
|
|
119
|
+
* inverts: `'default'` sounds safe and is in fact the legacy Edge/IE behaviour.
|
|
120
|
+
*
|
|
121
|
+
* @param startScrollLeft `scrollLeft` while scrolled to the start (right) edge.
|
|
122
|
+
* @param scrollLeftAfterWritingNegativeOne `scrollLeft` read back after writing -1.
|
|
123
|
+
*/
|
|
124
|
+
export function classifyRtlScrollType(
|
|
125
|
+
startScrollLeft: number,
|
|
126
|
+
scrollLeftAfterWritingNegativeOne: number,
|
|
127
|
+
): RtlScrollType {
|
|
128
|
+
// Only 'reverse' starts at a positive maximum rather than at 0.
|
|
129
|
+
if (startScrollLeft > 0) return 'reverse';
|
|
130
|
+
// Of the two that start at 0, only 'negative' accepts a negative write.
|
|
131
|
+
return scrollLeftAfterWritingNegativeOne < 0 ? 'negative' : 'default';
|
|
132
|
+
}
|
|
133
|
+
|
|
134
|
+
/**
|
|
135
|
+
* Converts a raw `element.scrollLeft` into a normalized "distance from the
|
|
136
|
+
* start edge": always `>= 0`, and increasing as the user scrolls away from
|
|
137
|
+
* the start, regardless of which of the three historical RTL `scrollLeft`
|
|
138
|
+
* conventions the current browser implements.
|
|
139
|
+
*
|
|
140
|
+
* Under `ltr` the raw value passes through unchanged — `rtlScrollType` is
|
|
141
|
+
* meaningless there — regardless of which convention was passed. Under
|
|
142
|
+
* `rtl`:
|
|
143
|
+
*
|
|
144
|
+
* - `'negative'` — **what current browsers do.** `scrollLeft` is 0 at the
|
|
145
|
+
* start (right) edge and grows NEGATIVE toward the end. Chrome aligned
|
|
146
|
+
* with Firefox and Safari on this in Chrome 85; it is the CSSOM-View
|
|
147
|
+
* behaviour. The normalized value is its negation.
|
|
148
|
+
* - `'default'` — 0 at the start edge, growing POSITIVE toward the end.
|
|
149
|
+
* Legacy Edge/IE. Already the normalized shape, so it passes through.
|
|
150
|
+
* - `'reverse'` — `scrollLeft` equals `scrollWidth - clientWidth` at the
|
|
151
|
+
* start edge and decreases to 0 at the end. Pre-85 Chrome and old
|
|
152
|
+
* WebKit. The normalized value is that maximum minus the raw value.
|
|
153
|
+
*
|
|
154
|
+
* The names are this module's own and do NOT rank the conventions: `'default'`
|
|
155
|
+
* is a legacy behaviour despite its name, and callers must not treat it as a
|
|
156
|
+
* safe default. Detect the convention rather than assuming one — pinning
|
|
157
|
+
* `'default'` would invert the sign in every browser shipping today.
|
|
158
|
+
*/
|
|
159
|
+
export function normalizeInlineScrollOffset(
|
|
160
|
+
rawScrollLeft: number,
|
|
161
|
+
scrollWidth: number,
|
|
162
|
+
clientWidth: number,
|
|
163
|
+
direction: WritingDirection,
|
|
164
|
+
rtlScrollType: RtlScrollType,
|
|
165
|
+
): number {
|
|
166
|
+
if (direction === 'ltr') return rawScrollLeft;
|
|
167
|
+
// `0 - rawScrollLeft` rather than `-rawScrollLeft`: negating a raw value of
|
|
168
|
+
// exactly 0 (the start edge) with unary minus produces IEEE-754 negative
|
|
169
|
+
// zero, which fails a strict `Object.is`-based equality check against `0`.
|
|
170
|
+
if (rtlScrollType === 'negative') return 0 - rawScrollLeft;
|
|
171
|
+
if (rtlScrollType === 'reverse') {
|
|
172
|
+
const maxScrollOffset = Math.max(0, scrollWidth - clientWidth);
|
|
173
|
+
return maxScrollOffset - rawScrollLeft;
|
|
174
|
+
}
|
|
175
|
+
return rawScrollLeft;
|
|
176
|
+
}
|
|
177
|
+
|
|
178
|
+
/** Which axis the list scrolls and lays rows out along. */
|
|
179
|
+
export type AxisMode = 'vertical' | 'horizontal';
|
|
180
|
+
|
|
181
|
+
/**
|
|
182
|
+
* The logical CSS property names that carry a row's size and offset along
|
|
183
|
+
* `axis`. Logical, not physical (`block-size`/`inset-block-start` rather
|
|
184
|
+
* than `height`/`top`), so RTL flips the inline axis correctly for free —
|
|
185
|
+
* no separate RTL branch is needed at the layout layer.
|
|
186
|
+
*/
|
|
187
|
+
export type RowLayoutDescriptor = {
|
|
188
|
+
readonly sizeProperty: 'block-size' | 'inline-size';
|
|
189
|
+
readonly offsetProperty: 'inset-block-start' | 'inset-inline-start';
|
|
190
|
+
};
|
|
191
|
+
|
|
192
|
+
/** Resolves the logical CSS property names a row on `axis` is sized and positioned with. */
|
|
193
|
+
export function resolveRowLayoutDescriptor(axis: AxisMode): RowLayoutDescriptor {
|
|
194
|
+
return axis === 'horizontal'
|
|
195
|
+
? { sizeProperty: 'inline-size', offsetProperty: 'inset-inline-start' }
|
|
196
|
+
: { sizeProperty: 'block-size', offsetProperty: 'inset-block-start' };
|
|
197
|
+
}
|
|
198
|
+
|
|
199
|
+
/**
|
|
200
|
+
* Returns one dynamic style string for a per-row-absolute row (Wave 4
|
|
201
|
+
* sticky mode only): the row's offset and size along `axis`, as logical CSS
|
|
202
|
+
* declarations.
|
|
203
|
+
*
|
|
204
|
+
* A single string, not per-property `style:` directives, because the CSS
|
|
205
|
+
* property NAME itself varies by axis (`inset-block-start` vs
|
|
206
|
+
* `inset-inline-start`, `block-size` vs `inline-size`) and Svelte's
|
|
207
|
+
* `style:prop={value}` directive requires a static property name — a
|
|
208
|
+
* computed string built from a function call is unambiguously dynamic
|
|
209
|
+
* instead. `position: absolute` is deliberately NOT included here: it is
|
|
210
|
+
* static across every row in this mode and lives in the CSS sidecar
|
|
211
|
+
* (`.cinder-virtual-list__row[data-cinder-absolute]`) rather than being
|
|
212
|
+
* repeated as an inline declaration on every row.
|
|
213
|
+
*/
|
|
214
|
+
export function resolveAbsoluteRowStyle(axis: AxisMode, start: number, size: number): string {
|
|
215
|
+
const { offsetProperty, sizeProperty } = resolveRowLayoutDescriptor(axis);
|
|
216
|
+
return `${offsetProperty}:${start}px;${sizeProperty}:${size}px;`;
|
|
217
|
+
}
|
|
218
|
+
|
|
219
|
+
/**
|
|
220
|
+
* The main-axis size of an observed row, from a `ResizeObserver` entry's two
|
|
221
|
+
* possible size sources.
|
|
222
|
+
*
|
|
223
|
+
* `borderBoxSize` is already writing-mode relative, so its `inlineSize` is the
|
|
224
|
+
* correct main-axis size under a horizontal list in both writing directions. The
|
|
225
|
+
* `contentRect` fallback is physical, so the axis has to be chosen by hand — and
|
|
226
|
+
* an older engine that reports only `contentRect` is exactly where picking the
|
|
227
|
+
* wrong one goes unnoticed.
|
|
228
|
+
*/
|
|
229
|
+
export function resolveObservedMainAxisSize(
|
|
230
|
+
borderBoxSize: { readonly blockSize: number; readonly inlineSize: number } | undefined,
|
|
231
|
+
contentRect: { readonly width: number; readonly height: number },
|
|
232
|
+
axis: AxisMode,
|
|
233
|
+
): number {
|
|
234
|
+
if (axis === 'horizontal') return borderBoxSize?.inlineSize ?? contentRect.width;
|
|
235
|
+
return borderBoxSize?.blockSize ?? contentRect.height;
|
|
236
|
+
}
|
|
@@ -0,0 +1,151 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Pure ARIA row-semantics and keyboard-navigation arithmetic for the virtual
|
|
3
|
+
* list. See CIN-201.
|
|
4
|
+
*
|
|
5
|
+
* A virtualized list only ever mounts a small window of rows, so assistive
|
|
6
|
+
* technology reading `aria-posinset`/`aria-setsize` off the mounted DOM
|
|
7
|
+
* alone would announce something like "3 of 12" for a list of 10,000 items
|
|
8
|
+
* — the window length, not the true list size. `resolveRowSemantics` exists
|
|
9
|
+
* to hand the component the FULL-list numbers to stamp onto each mounted
|
|
10
|
+
* row instead of that.
|
|
11
|
+
*
|
|
12
|
+
* `resolveKeyboardTargetIndex` is the companion arithmetic for arrow/Page/
|
|
13
|
+
* Home/End navigation: it resolves which index a keypress should move focus
|
|
14
|
+
* to, independent of which rows happen to be mounted right now, so
|
|
15
|
+
* navigation keeps working identically across mount and unmount cycles as
|
|
16
|
+
* the window scrolls past a given row.
|
|
17
|
+
*
|
|
18
|
+
* Dependency-free, matching the rest of `_internal/`: no DOM, no runes. The
|
|
19
|
+
* component owns reading the real `KeyboardEvent.key`, moving focus to the
|
|
20
|
+
* resolved index (mounting it first if it currently sits outside the
|
|
21
|
+
* window), and the actual scrolling.
|
|
22
|
+
*/
|
|
23
|
+
|
|
24
|
+
/** `aria-posinset`/`aria-setsize` values for one row of a virtualized list. */
|
|
25
|
+
export type RowSemantics = {
|
|
26
|
+
/** 1-based position within the FULL list — never the zero-based `index` passed in. */
|
|
27
|
+
readonly ariaPosInSet: number;
|
|
28
|
+
/** The FULL item count, not the length of the rendered window — see the module doc for why that distinction is the point. */
|
|
29
|
+
readonly ariaSetSize: number;
|
|
30
|
+
};
|
|
31
|
+
|
|
32
|
+
/**
|
|
33
|
+
* Resolves the `aria-posinset`/`aria-setsize` pair for the row at `index`.
|
|
34
|
+
*
|
|
35
|
+
* `aria-posinset` is 1-BASED: `index` is the zero-based array position, so
|
|
36
|
+
* this adds 1 rather than passing `index` straight through — passing the
|
|
37
|
+
* zero-based index through unchanged is the single most common way to get
|
|
38
|
+
* this attribute wrong.
|
|
39
|
+
*
|
|
40
|
+
* `aria-setsize` is `itemCount`, the FULL logical list size, not the number
|
|
41
|
+
* of rows currently mounted in the virtualization window. That distinction
|
|
42
|
+
* is the entire reason a virtualized list needs these attributes in the
|
|
43
|
+
* first place: without it, assistive technology would announce something
|
|
44
|
+
* like "3 of 12" for a list of 10,000 items, reading only what happens to
|
|
45
|
+
* be in the DOM right now.
|
|
46
|
+
*/
|
|
47
|
+
export function resolveRowSemantics(index: number, itemCount: number): RowSemantics {
|
|
48
|
+
return { ariaPosInSet: index + 1, ariaSetSize: itemCount };
|
|
49
|
+
}
|
|
50
|
+
|
|
51
|
+
/** Which axis `resolveKeyboardTargetIndex` treats as "forward"/"backward" for the Arrow keys. */
|
|
52
|
+
export type VirtualListOrientation = 'vertical' | 'horizontal';
|
|
53
|
+
|
|
54
|
+
/**
|
|
55
|
+
* Resolves the index a navigation keypress should move focus to.
|
|
56
|
+
*
|
|
57
|
+
* Returns `null` when `key` is not one of the keys this list handles, so
|
|
58
|
+
* the component can tell "not a navigation key, leave the event alone"
|
|
59
|
+
* apart from "navigation key, but the move happens to be a no-op." The
|
|
60
|
+
* latter still returns the (unchanged) index rather than `null` — the
|
|
61
|
+
* component still needs to consume the event (stopping it from scrolling
|
|
62
|
+
* the page via the browser's own default handling, for instance) even when
|
|
63
|
+
* the reader is already at the boundary they pressed toward.
|
|
64
|
+
*
|
|
65
|
+
* `Home` resolves to 0 and `End` to `itemCount - 1`. Every result is clamped
|
|
66
|
+
* to `[0, itemCount - 1]`; `itemCount <= 0` has no valid index to move to at
|
|
67
|
+
* all, so every key resolves to `null` in that case, including `Home` and
|
|
68
|
+
* `End`.
|
|
69
|
+
*
|
|
70
|
+
* `PageUp`/`PageDown` resolve to `null` here, deliberately. Paging is a PIXEL
|
|
71
|
+
* move of one uncovered viewport, which an index cannot express once rows vary
|
|
72
|
+
* in height — any row count this returned would be wrong at some boundary, in
|
|
73
|
+
* one direction or the other. The component scrolls for those keys directly.
|
|
74
|
+
*
|
|
75
|
+
* The horizontal arrow mapping DOES branch on writing direction, and has to.
|
|
76
|
+
* `KeyboardEvent.key` is derived from the physical key and the keyboard layout;
|
|
77
|
+
* it is not remapped by `dir`, so the right arrow reports `'ArrowRight'` in a
|
|
78
|
+
* right-to-left list exactly as it does in a left-to-right one. Meanwhile the
|
|
79
|
+
* component positions horizontal rows with logical properties, so under RTL a
|
|
80
|
+
* higher index sits visually to the LEFT. Mapping `'ArrowRight'` to "forward"
|
|
81
|
+
* there would walk the reader backwards from where they pressed.
|
|
82
|
+
*
|
|
83
|
+
* This is what the WAI-ARIA Authoring Practices mean by "if the direction is
|
|
84
|
+
* RTL, Right Arrow performs as Left Arrow and vice versa" — guidance that exists
|
|
85
|
+
* precisely because the reversal is not automatic. `writingDirection` is ignored
|
|
86
|
+
* for a vertical list, where the block axis does not flip.
|
|
87
|
+
*/
|
|
88
|
+
export function resolveKeyboardTargetIndex(options: {
|
|
89
|
+
key: string;
|
|
90
|
+
currentIndex: number;
|
|
91
|
+
itemCount: number;
|
|
92
|
+
orientation: VirtualListOrientation;
|
|
93
|
+
writingDirection?: 'ltr' | 'rtl';
|
|
94
|
+
/**
|
|
95
|
+
* Indexes rendered as sticky headers. Stepping keys move between content rows
|
|
96
|
+
* and pass over these.
|
|
97
|
+
*/
|
|
98
|
+
stickyIndexes?: ReadonlySet<number>;
|
|
99
|
+
}): number | null {
|
|
100
|
+
if (options.itemCount <= 0) return null;
|
|
101
|
+
|
|
102
|
+
const lastIndex = options.itemCount - 1;
|
|
103
|
+
const clampToListRange = (index: number): number => Math.max(0, Math.min(lastIndex, index));
|
|
104
|
+
|
|
105
|
+
/**
|
|
106
|
+
* Steps past sticky rows in the direction of travel.
|
|
107
|
+
*
|
|
108
|
+
* A sticky header is held at the leading edge for as long as its section is in
|
|
109
|
+
* view, so it is on screen already and scrolling to it moves nothing. Worse, it
|
|
110
|
+
* is the row a step lands on coming back UP to a section: the destination's
|
|
111
|
+
* inset is zero exactly there, so the target resolves to the position the reader
|
|
112
|
+
* is already at and the key does nothing at all.
|
|
113
|
+
*
|
|
114
|
+
* Running off the end means every row that way is sticky, so there is no content
|
|
115
|
+
* row to reach; the boundary itself is as close as the reader gets.
|
|
116
|
+
*/
|
|
117
|
+
const skipStickyRows = (index: number, direction: number): number => {
|
|
118
|
+
const sticky = options.stickyIndexes;
|
|
119
|
+
if (sticky === undefined || sticky.size === 0) return index;
|
|
120
|
+
let candidate = index;
|
|
121
|
+
while (candidate >= 0 && candidate <= lastIndex && sticky.has(candidate)) {
|
|
122
|
+
candidate += direction;
|
|
123
|
+
}
|
|
124
|
+
return candidate < 0 || candidate > lastIndex ? index : candidate;
|
|
125
|
+
};
|
|
126
|
+
|
|
127
|
+
// Home and End are absolute: they mean the ends of the list, sticky or not.
|
|
128
|
+
if (options.key === 'Home') return 0;
|
|
129
|
+
if (options.key === 'End') return lastIndex;
|
|
130
|
+
|
|
131
|
+
if (options.orientation === 'vertical') {
|
|
132
|
+
if (options.key === 'ArrowDown')
|
|
133
|
+
return skipStickyRows(clampToListRange(options.currentIndex + 1), 1);
|
|
134
|
+
if (options.key === 'ArrowUp')
|
|
135
|
+
return skipStickyRows(clampToListRange(options.currentIndex - 1), -1);
|
|
136
|
+
return null;
|
|
137
|
+
}
|
|
138
|
+
|
|
139
|
+
// Under RTL the inline axis runs right-to-left, so the arrow that moves the
|
|
140
|
+
// reader visually forward is the left one.
|
|
141
|
+
const isRightToLeft = options.writingDirection === 'rtl';
|
|
142
|
+
const forwardKey = isRightToLeft ? 'ArrowLeft' : 'ArrowRight';
|
|
143
|
+
const backwardKey = isRightToLeft ? 'ArrowRight' : 'ArrowLeft';
|
|
144
|
+
|
|
145
|
+
if (options.key === forwardKey)
|
|
146
|
+
return skipStickyRows(clampToListRange(options.currentIndex + 1), 1);
|
|
147
|
+
if (options.key === backwardKey)
|
|
148
|
+
return skipStickyRows(clampToListRange(options.currentIndex - 1), -1);
|
|
149
|
+
|
|
150
|
+
return null;
|
|
151
|
+
}
|