@jupyterlab/ui-components 4.1.0-rc.0 → 4.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -21,11 +21,12 @@ import { ISignal, Signal } from '@lumino/signaling';
21
21
  import { PanelLayout, Widget } from '@lumino/widgets';
22
22
 
23
23
  /**
24
- * Maximal remaining time for idle callback
24
+ * For how long after the scroll request should the target position
25
+ * be corrected to account for resize of other widgets?
25
26
  *
26
- * Ref: https://developer.mozilla.org/en-US/docs/Web/API/Background_Tasks_API#getting_the_most_out_of_idle_callbacks
27
+ * The time is given in milliseconds.
27
28
  */
28
- const MAXIMUM_TIME_REMAINING = 50;
29
+ const MAXIMUM_TIME_REMAINING = 100;
29
30
 
30
31
  /*
31
32
  * Feature detection
@@ -292,13 +293,20 @@ export abstract class WindowedListModel implements WindowedList.IModel {
292
293
  /**
293
294
  * Get the scroll offset to display an item in the viewport.
294
295
  *
295
- * By default, the list will scroll as little as possible to ensure the item is fully visible. You can control the alignment of the item though by specifying a second alignment parameter. Acceptable values are:
296
+ * By default, the list will scroll as little as possible to ensure the item is fully visible (`auto`).
297
+ * You can control the alignment of the item though by specifying a second alignment parameter.
298
+ * Acceptable values are:
296
299
  *
297
- * auto (default) - Automatically align with the top or bottom minimising the amount scrolled; if item is smaller than the viewport and fully visible, do not scroll at all.
298
- * smart - If the item is significantly visible, don't scroll at all (regardless of whether it fits in the viewport). If it is less than one viewport away or exceeds viewport in height, scroll so that it becomes visible. If it is more than one viewport away and fits the viewport, scroll so that it is centered within the viewport.
299
- * center - Center align the item within the list.
300
- * end - Align the item to the end of the list
301
- * start - Align the item to the beginning of the list
300
+ * auto - Automatically align with the top or bottom minimising the amount scrolled,
301
+ * If `alignPreference` is given, follow such preferred alignment.
302
+ * If item is smaller than the viewport and fully visible, do not scroll at all.
303
+ * smart - If the item is significantly visible, don't scroll at all (regardless of whether it fits in the viewport).
304
+ * If the item is less than one viewport away, scroll so that it becomes fully visible (following the `auto` heuristics).
305
+ * If the item is more than one viewport away, scroll so that it is centered within the viewport (`center` if smaller than viewport, `top-center` otherwise).
306
+ * center - Align the middle of the item with the middle of the viewport (it only works well for items smaller than the viewport).
307
+ * top-center - Align the top of the item with the middle of the viewport (works well for items larger than the viewport).
308
+ * end - Align the bottom of the item to the bottom of the list.
309
+ * start - Align the top of item to the top of the list.
302
310
  *
303
311
  * An item is considered significantly visible if:
304
312
  * - it overlaps with the viewport by the amount specified by `scrollDownThreshold` when below the viewport
@@ -307,16 +315,26 @@ export abstract class WindowedListModel implements WindowedList.IModel {
307
315
  * @param index Item index
308
316
  * @param align Where to align the item in the viewport
309
317
  * @param margin The proportion of viewport to add when aligning with the top/bottom of the list.
318
+ * @param precomputed Precomputed values to use when windowing is disabled.
319
+ * @param alignPreference Allows to override the alignment of item when the `auto` heuristic decides that the item needs to be scrolled into view.
310
320
  * @returns The needed scroll offset
311
321
  */
312
322
  getOffsetForIndexAndAlignment(
313
323
  index: number,
314
324
  align: WindowedList.ScrollToAlign = 'auto',
315
- margin: number = 0
325
+ margin: number = 0,
326
+ precomputed?: {
327
+ totalSize: number;
328
+ itemMetadata: WindowedList.ItemMetadata;
329
+ currentOffset: number;
330
+ },
331
+ alignPreference?: WindowedList.BaseScrollToAlignment
316
332
  ): number {
317
333
  const boundedMargin = Math.min(Math.max(0.0, margin), 1.0);
318
334
  const size = this._height;
319
- const itemMetadata = this._getItemMetadata(index);
335
+ const itemMetadata = precomputed
336
+ ? precomputed.itemMetadata
337
+ : this._getItemMetadata(index);
320
338
 
321
339
  const scrollDownThreshold =
322
340
  this.scrollDownThreshold <= 1
@@ -327,9 +345,12 @@ export abstract class WindowedListModel implements WindowedList.IModel {
327
345
  ? itemMetadata.size * this.scrollUpThreshold
328
346
  : this.scrollUpThreshold;
329
347
 
330
- // Get estimated total size after ItemMetadata is computed,
331
- // To ensure it reflects actual measurements instead of just estimates.
332
- const estimatedTotalSize = this.getEstimatedTotalSize();
348
+ // When pre-computed values are not available (we are in windowing mode),
349
+ // `getEstimatedTotalSize` is called after ItemMetadata is computed
350
+ // to ensure it reflects actual measurements instead of just estimates.
351
+ const estimatedTotalSize = precomputed
352
+ ? precomputed.totalSize
353
+ : this.getEstimatedTotalSize();
333
354
 
334
355
  const topOffset = Math.max(
335
356
  0,
@@ -339,14 +360,21 @@ export abstract class WindowedListModel implements WindowedList.IModel {
339
360
  0,
340
361
  itemMetadata.offset - size + itemMetadata.size
341
362
  );
342
- const currentOffset = this._scrollOffset;
363
+ // Current offset (+/- padding) is the top edge of the viewport.
364
+ const currentOffset = precomputed
365
+ ? precomputed.currentOffset
366
+ : this._scrollOffset;
343
367
 
368
+ const viewportPadding = this._windowingActive ? this.paddingTop : 0;
344
369
  const itemTop = itemMetadata.offset;
345
370
  const itemBottom = itemMetadata.offset + itemMetadata.size;
346
- const bottomEdge = currentOffset - this.paddingTop + size;
347
- const topEdge = currentOffset - this.paddingTop;
371
+ const bottomEdge = currentOffset - viewportPadding + size;
372
+ const topEdge = currentOffset - viewportPadding;
348
373
  const crossingBottomEdge = bottomEdge > itemTop && bottomEdge < itemBottom;
349
374
  const crossingTopEdge = topEdge > itemTop && topEdge < itemBottom;
375
+
376
+ const isFullyWithinViewport = bottomEdge > itemBottom && topEdge < itemTop;
377
+
350
378
  if (align === 'smart') {
351
379
  const edgeLessThanOneViewportAway =
352
380
  currentOffset >= bottomOffset - size &&
@@ -356,19 +384,20 @@ export abstract class WindowedListModel implements WindowedList.IModel {
356
384
  const hiddenPartTop = topEdge - itemTop;
357
385
 
358
386
  if (
387
+ isFullyWithinViewport ||
359
388
  (crossingBottomEdge && visiblePartBottom >= scrollDownThreshold) ||
360
389
  (crossingTopEdge && hiddenPartTop < scrollUpThreshold)
361
390
  ) {
362
- return this._scrollOffset;
391
+ return currentOffset;
363
392
  } else if (edgeLessThanOneViewportAway) {
364
393
  // Possibly less than one viewport away, scroll so that it becomes visible (including the margin)
365
394
  align = 'auto';
366
395
  } else {
367
- // More than one viewport away, scroll so that it is centered within the list,
368
- // unless the widget is larger than the viewport, in which case only scroll to
369
- // align with the top or bottom edge (automatically)
396
+ // More than one viewport away, scroll so that it is centered within the list:
397
+ // - if the item is smaller than viewport align the middle of the item with the middle of the viewport
398
+ // - if the item is larger than viewport align the top of the item with the middle of the viewport
370
399
  if (itemMetadata.size > size) {
371
- align = 'auto';
400
+ align = 'top-center';
372
401
  } else {
373
402
  align = 'center';
374
403
  }
@@ -376,9 +405,11 @@ export abstract class WindowedListModel implements WindowedList.IModel {
376
405
  }
377
406
 
378
407
  if (align === 'auto') {
379
- if (bottomEdge > itemBottom && topEdge < itemTop) {
408
+ if (isFullyWithinViewport) {
380
409
  // No need to change the position, return the current offset.
381
- return this._scrollOffset;
410
+ return currentOffset;
411
+ } else if (alignPreference !== undefined) {
412
+ align = alignPreference;
382
413
  } else if (crossingBottomEdge || bottomEdge <= itemBottom) {
383
414
  align = 'end';
384
415
  } else {
@@ -388,13 +419,17 @@ export abstract class WindowedListModel implements WindowedList.IModel {
388
419
 
389
420
  switch (align) {
390
421
  case 'start':
391
- // Align to the top edge.
392
- return Math.max(0, topOffset - boundedMargin * size) + this.paddingTop;
422
+ // Align item top to the top edge.
423
+ return Math.max(0, topOffset - boundedMargin * size) + viewportPadding;
393
424
  case 'end':
394
- // Align to the bottom edge.
395
- return bottomOffset + boundedMargin * size + this.paddingTop;
425
+ // Align item bottom to the bottom edge.
426
+ return bottomOffset + boundedMargin * size + viewportPadding;
396
427
  case 'center':
397
- return Math.round(bottomOffset + (topOffset - bottomOffset) / 2);
428
+ // Align item centre to the middle of the viewport
429
+ return bottomOffset + (topOffset - bottomOffset) / 2;
430
+ case 'top-center':
431
+ // Align item top to the middle of the viewport
432
+ return topOffset - size / 2;
398
433
  }
399
434
  }
400
435
 
@@ -764,7 +799,7 @@ export class WindowedList<
764
799
  this._innerElement = innerElement;
765
800
  this._isScrolling = null;
766
801
  this._outerElement = outerElement;
767
- this._resizeObserver = null;
802
+ this._itemsResizeObserver = null;
768
803
  this._scrollbarElement = scrollbarElement;
769
804
  this._scrollToItem = null;
770
805
  this._scrollRepaint = null;
@@ -877,7 +912,7 @@ export class WindowedList<
877
912
  */
878
913
  scrollTo(scrollOffset: number): void {
879
914
  if (!this.viewModel.windowingActive) {
880
- this.node.scrollTo({ top: scrollOffset });
915
+ this._outerElement.scrollTo({ top: scrollOffset });
881
916
  return;
882
917
  }
883
918
 
@@ -894,35 +929,32 @@ export class WindowedList<
894
929
  /**
895
930
  * Scroll to the specified item.
896
931
  *
897
- * By default, the list will scroll as little as possible to ensure the item is visible. You can control the alignment of the item though by specifying a second alignment parameter. Acceptable values are:
932
+ * By default, the list will scroll as little as possible to ensure the item is fully visible (`auto`).
933
+ * You can control the alignment of the item though by specifying a second alignment parameter.
934
+ * Acceptable values are:
898
935
  *
899
- * auto (default) - Scroll as little as possible to ensure the item is visible. (If the item is already visible, it won't scroll at all.)
900
- * smart - If the item is already visible (including the margin), don't scroll at all. If it is less than one viewport away, scroll so that it becomes visible (including the margin). If it is more than one viewport away, scroll so that it is centered within the list.
901
- * center - Center align the item within the list.
902
- * end - Align the item to the end of the list
903
- * start - Align the item to the beginning of the list
936
+ * auto - Automatically align with the top or bottom minimising the amount scrolled,
937
+ * If `alignPreference` is given, follow such preferred alignment.
938
+ * If item is smaller than the viewport and fully visible, do not scroll at all.
939
+ * smart - If the item is significantly visible, don't scroll at all (regardless of whether it fits in the viewport).
940
+ * If the item is less than one viewport away, scroll so that it becomes fully visible (following the `auto` heuristics).
941
+ * If the item is more than one viewport away, scroll so that it is centered within the viewport (`center` if smaller than viewport, `top-center` otherwise).
942
+ * center - Align the middle of the item with the middle of the viewport (it only works well for items smaller than the viewport).
943
+ * top-center - Align the top of the item with the middle of the viewport (works well for items larger than the viewport).
944
+ * end - Align the bottom of the item to the bottom of the list.
945
+ * start - Align the top of item to the top of the list.
904
946
  *
905
947
  * @param index Item index to scroll to
906
948
  * @param align Type of alignment
907
949
  * @param margin In 'smart' mode the viewport proportion to add
950
+ * @param alignPreference Allows to override the alignment of item when the `auto` heuristic decides that the item needs to be scrolled into view.
908
951
  */
909
952
  scrollToItem(
910
953
  index: number,
911
954
  align: WindowedList.ScrollToAlign = 'auto',
912
- margin: number = 0.25
955
+ margin: number = 0.25,
956
+ alignPreference?: WindowedList.BaseScrollToAlignment
913
957
  ): Promise<void> {
914
- if (!this.viewModel.windowingActive) {
915
- const widget = this.layout.widgets[index];
916
- if (widget?.node.scrollIntoView) {
917
- widget.node.scrollIntoView({
918
- block: ['auto', 'smart'].includes(align)
919
- ? 'nearest'
920
- : (align as ScrollLogicalPosition)
921
- });
922
- }
923
- return Promise.resolve();
924
- }
925
-
926
958
  if (
927
959
  !this._isScrolling ||
928
960
  this._scrollToItem === null ||
@@ -934,15 +966,41 @@ export class WindowedList<
934
966
  }
935
967
 
936
968
  this._isScrolling = new PromiseDelegate<void>();
969
+ // Catch the internal reject, as otherwise this will
970
+ // result in an unhandled promise rejection in test.
971
+ this._isScrolling.promise.catch(console.debug);
937
972
  }
938
973
 
939
- this._scrollToItem = [index, align];
974
+ this._scrollToItem = [index, align, margin, alignPreference];
975
+
940
976
  this._resetScrollToItem();
977
+
978
+ let precomputed = undefined;
979
+ if (!this.viewModel.windowingActive) {
980
+ const item = this._innerElement.querySelector(
981
+ `[data-windowed-list-index="${index}"]`
982
+ );
983
+ if (!item || !(item instanceof HTMLElement)) {
984
+ // Note: this can happen when scroll is requested when a cell is getting added
985
+ console.debug(`Element with index ${index} not found`);
986
+ return Promise.resolve();
987
+ }
988
+ precomputed = {
989
+ totalSize: this._outerElement.scrollHeight,
990
+ itemMetadata: {
991
+ offset: item.offsetTop,
992
+ size: item.clientHeight
993
+ },
994
+ currentOffset: this._outerElement.scrollTop
995
+ };
996
+ }
941
997
  this.scrollTo(
942
998
  this.viewModel.getOffsetForIndexAndAlignment(
943
999
  Math.max(0, Math.min(index, this.viewModel.widgetCount - 1)),
944
1000
  align,
945
- margin
1001
+ margin,
1002
+ precomputed,
1003
+ alignPreference
946
1004
  )
947
1005
  );
948
1006
 
@@ -955,12 +1013,13 @@ export class WindowedList<
955
1013
  protected onAfterAttach(msg: Message): void {
956
1014
  super.onAfterAttach(msg);
957
1015
  if (this.viewModel.windowingActive) {
958
- this._addListeners();
1016
+ this._applyWindowingStyles();
959
1017
  } else {
960
1018
  this._applyNoWindowingStyles();
961
1019
  }
1020
+ this._addListeners();
962
1021
  this.viewModel.height = this.node.getBoundingClientRect().height;
963
- const style = window.getComputedStyle(this.node);
1022
+ const style = window.getComputedStyle(this._viewport);
964
1023
  this.viewModel.paddingTop = parseFloat(style.paddingTop);
965
1024
  this._scrollbarElement.addEventListener('pointerdown', this);
966
1025
  }
@@ -969,9 +1028,7 @@ export class WindowedList<
969
1028
  * A message handler invoked on an `'before-detach'` message.
970
1029
  */
971
1030
  protected onBeforeDetach(msg: Message): void {
972
- if (this.viewModel.windowingActive) {
973
- this._removeListeners();
974
- }
1031
+ this._removeListeners();
975
1032
  this._scrollbarElement.removeEventListener('pointerdown', this);
976
1033
  super.onBeforeDetach(msg);
977
1034
  }
@@ -1035,13 +1092,16 @@ export class WindowedList<
1035
1092
  ): void {
1036
1093
  switch (changes.name) {
1037
1094
  case 'windowingActive':
1095
+ this._removeListeners();
1038
1096
  if (this.viewModel.windowingActive) {
1039
- this._addListeners();
1097
+ this._applyWindowingStyles();
1040
1098
  this.onScroll({ currentTarget: this.node } as any);
1099
+ this._addListeners();
1041
1100
  // Bail as onScroll will trigger update
1042
1101
  return;
1043
1102
  } else {
1044
- this._removeListeners();
1103
+ this._applyNoWindowingStyles();
1104
+ this._addListeners();
1045
1105
  }
1046
1106
  break;
1047
1107
  }
@@ -1125,25 +1185,33 @@ export class WindowedList<
1125
1185
  * Add listeners for viewport, contents and the virtual scrollbar.
1126
1186
  */
1127
1187
  private _addListeners() {
1128
- if (!this._resizeObserver) {
1129
- this._resizeObserver = new ResizeObserver(
1130
- this._onWidgetResize.bind(this)
1131
- );
1132
- }
1133
- for (const widget of this.layout.widgets) {
1134
- this._resizeObserver.observe(widget.node);
1135
- widget.disposed.connect(
1136
- () => this._resizeObserver?.unobserve(widget.node)
1188
+ if (this.viewModel.windowingActive) {
1189
+ if (!this._itemsResizeObserver) {
1190
+ this._itemsResizeObserver = new ResizeObserver(
1191
+ this._onItemResize.bind(this)
1192
+ );
1193
+ }
1194
+ for (const widget of this.layout.widgets) {
1195
+ this._itemsResizeObserver.observe(widget.node);
1196
+ widget.disposed.connect(
1197
+ () => this._itemsResizeObserver?.unobserve(widget.node)
1198
+ );
1199
+ }
1200
+ this._outerElement.addEventListener('scroll', this, passiveIfSupported);
1201
+
1202
+ this._scrollbarResizeObserver = new ResizeObserver(
1203
+ this._adjustDimensionsForScrollbar.bind(this)
1137
1204
  );
1205
+ this._scrollbarResizeObserver.observe(this._outerElement);
1206
+ this._scrollbarResizeObserver.observe(this._scrollbarElement);
1207
+ } else {
1208
+ if (!this._areaResizeObserver) {
1209
+ this._areaResizeObserver = new ResizeObserver(
1210
+ this._onAreaResize.bind(this)
1211
+ );
1212
+ this._areaResizeObserver.observe(this._innerElement);
1213
+ }
1138
1214
  }
1139
- this._outerElement.addEventListener('scroll', this, passiveIfSupported);
1140
- this._viewport.style.position = 'absolute';
1141
-
1142
- this._scrollbarResizeObserver = new ResizeObserver(
1143
- this._adjustDimensionsForScrollbar.bind(this)
1144
- );
1145
- this._scrollbarResizeObserver.observe(this._outerElement);
1146
- this._scrollbarResizeObserver.observe(this._scrollbarElement);
1147
1215
  }
1148
1216
 
1149
1217
  /**
@@ -1153,17 +1221,24 @@ export class WindowedList<
1153
1221
  this._viewport.style.position = 'relative';
1154
1222
  this._viewport.style.top = '0px';
1155
1223
  }
1224
+ /**
1225
+ * Turn on windowing related styles in the viewport.
1226
+ */
1227
+ private _applyWindowingStyles() {
1228
+ this._viewport.style.position = 'absolute';
1229
+ }
1156
1230
 
1157
1231
  /**
1158
1232
  * Remove listeners for viewport and contents (but not the virtual scrollbar).
1159
1233
  */
1160
1234
  private _removeListeners() {
1161
1235
  this._outerElement.removeEventListener('scroll', this);
1162
- this._resizeObserver?.disconnect();
1163
- this._resizeObserver = null;
1236
+ this._areaResizeObserver?.disconnect();
1237
+ this._areaResizeObserver = null;
1238
+ this._itemsResizeObserver?.disconnect();
1239
+ this._itemsResizeObserver = null;
1164
1240
  this._scrollbarResizeObserver?.disconnect();
1165
1241
  this._scrollbarResizeObserver = null;
1166
- this._applyNoWindowingStyles();
1167
1242
  }
1168
1243
 
1169
1244
  /**
@@ -1190,17 +1265,19 @@ export class WindowedList<
1190
1265
  // Remove not needed widgets
1191
1266
  for (let itemIdx = nWidgets - 1; itemIdx >= 0; itemIdx--) {
1192
1267
  if (!toAdd.includes(this.layout.widgets[itemIdx])) {
1193
- this._resizeObserver?.unobserve(this.layout.widgets[itemIdx].node);
1268
+ this._itemsResizeObserver?.unobserve(
1269
+ this.layout.widgets[itemIdx].node
1270
+ );
1194
1271
  this.layout.removeWidget(this.layout.widgets[itemIdx]);
1195
1272
  }
1196
1273
  }
1197
1274
 
1198
1275
  for (let index = 0; index < toAdd.length; index++) {
1199
1276
  const item = toAdd[index];
1200
- if (this._resizeObserver && !this.layout.widgets.includes(item)) {
1201
- this._resizeObserver.observe(item.node);
1277
+ if (this._itemsResizeObserver && !this.layout.widgets.includes(item)) {
1278
+ this._itemsResizeObserver.observe(item.node);
1202
1279
  item.disposed.connect(
1203
- () => this._resizeObserver?.unobserve(item.node)
1280
+ () => this._itemsResizeObserver?.unobserve(item.node)
1204
1281
  );
1205
1282
  }
1206
1283
 
@@ -1256,9 +1333,16 @@ export class WindowedList<
1256
1333
  }
1257
1334
 
1258
1335
  /**
1259
- * Handle viewport content (e.g. widgets) resize.
1336
+ * Handle viewport area resize.
1260
1337
  */
1261
- private _onWidgetResize(entries: ResizeObserverEntry[]): void {
1338
+ private _onAreaResize(_entries: ResizeObserverEntry[]): void {
1339
+ this._scrollBackToItemOnResize();
1340
+ }
1341
+
1342
+ /**
1343
+ * Handle viewport content (i.e. items) resize.
1344
+ */
1345
+ private _onItemResize(entries: ResizeObserverEntry[]): void {
1262
1346
  this._resetScrollToItem();
1263
1347
 
1264
1348
  if (this.isHidden || this.isParentHidden) {
@@ -1283,17 +1367,39 @@ export class WindowedList<
1283
1367
 
1284
1368
  // If some sizes changed
1285
1369
  if (this.viewModel.setWidgetSize(newSizes)) {
1370
+ this._scrollBackToItemOnResize();
1286
1371
  // Update the list
1287
- if (this._scrollToItem) {
1288
- this.scrollToItem(...this._scrollToItem).catch(reason => {
1289
- console.log(reason);
1290
- });
1291
- }
1292
-
1293
1372
  this.update();
1294
1373
  }
1295
1374
  }
1296
1375
 
1376
+ /**
1377
+ * Scroll to the item which was most recently requested.
1378
+ *
1379
+ * This method ensures that the app scrolls to the item even if a resize event
1380
+ * occurs shortly after the scroll. Consider the following sequence of events:
1381
+ *
1382
+ * 1. User is at the nth cell, presses Shift+Enter (run current cell and
1383
+ * advance to next)
1384
+ * 2. App scrolls to the next (n+1) cell
1385
+ * 3. The nth cell finishes running and renders the output, pushing the
1386
+ * (n+1) cell down out of view
1387
+ * 4. This triggers the resize observer, which calls this method and scrolls
1388
+ * the (n+1) cell back into view
1389
+ *
1390
+ * On implementation level, this is ensured by scrolling to `this._scrollToItem`
1391
+ * which is cleared after a short timeout once the scrolling settles
1392
+ * (see `this._resetScrollToItem()`).
1393
+ */
1394
+ private _scrollBackToItemOnResize() {
1395
+ if (!this._scrollToItem) {
1396
+ return;
1397
+ }
1398
+ this.scrollToItem(...this._scrollToItem).catch(reason => {
1399
+ console.log(reason);
1400
+ });
1401
+ }
1402
+
1297
1403
  /**
1298
1404
  * Clear any outstanding timeout and enqueue scrolling to a new item.
1299
1405
  */
@@ -1358,11 +1464,19 @@ export class WindowedList<
1358
1464
  private _needsUpdate = false;
1359
1465
  private _outerElement: HTMLElement;
1360
1466
  private _resetScrollToItemTimeout: number | null;
1361
- private _resizeObserver: ResizeObserver | null;
1467
+ private _areaResizeObserver: ResizeObserver | null;
1468
+ private _itemsResizeObserver: ResizeObserver | null;
1362
1469
  private _scrollbarElement: HTMLElement;
1363
1470
  private _scrollbarResizeObserver: ResizeObserver | null;
1364
1471
  private _scrollRepaint: number | null;
1365
- private _scrollToItem: [number, WindowedList.ScrollToAlign] | null;
1472
+ private _scrollToItem:
1473
+ | [
1474
+ number,
1475
+ WindowedList.ScrollToAlign,
1476
+ number,
1477
+ WindowedList.BaseScrollToAlignment | undefined
1478
+ ]
1479
+ | null;
1366
1480
  private _scrollUpdateWasRequested: boolean;
1367
1481
  private _updater: Throttler;
1368
1482
  private _viewModel: T;
@@ -1582,23 +1696,38 @@ export namespace WindowedList {
1582
1696
  /**
1583
1697
  * Get the scroll offset to display an item in the viewport.
1584
1698
  *
1585
- * By default, the list will scroll as little as possible to ensure the item is visible. You can control the alignment of the item though by specifying a second alignment parameter. Acceptable values are:
1699
+ * By default, the list will scroll as little as possible to ensure the item is fully visible (`auto`).
1700
+ * You can control the alignment of the item though by specifying a second alignment parameter.
1701
+ * Acceptable values are:
1586
1702
  *
1587
- * auto (default) - Scroll as little as possible to ensure the item is visible. (If the item is already visible, it won't scroll at all.)
1588
- * smart - If the item is already visible (including the margin), don't scroll at all. If it is less than one viewport away, scroll so that it becomes visible (including the margin). If it is more than one viewport away, scroll so that it is centered within the list.
1589
- * center - Center align the item within the list.
1590
- * end - Align the item to the end of the list
1591
- * start - Align the item to the beginning of the list
1703
+ * auto - Automatically align with the top or bottom minimising the amount scrolled,
1704
+ * If `alignPreference` is given, follow such preferred alignment.
1705
+ * If item is smaller than the viewport and fully visible, do not scroll at all.
1706
+ * smart - If the item is significantly visible, don't scroll at all (regardless of whether it fits in the viewport).
1707
+ * If the item is less than one viewport away, scroll so that it becomes fully visible (following the `auto` heuristics).
1708
+ * If the item is more than one viewport away, scroll so that it is centered within the viewport (`center` if smaller than viewport, `top-center` otherwise).
1709
+ * center - Align the middle of the item with the middle of the viewport (it only works well for items smaller than the viewport).
1710
+ * top-center - Align the top of the item with the middle of the viewport (works well for items larger than the viewport).
1711
+ * end - Align the bottom of the item to the bottom of the list.
1712
+ * start - Align the top of item to the top of the list.
1592
1713
  *
1593
1714
  * @param index Item index
1594
1715
  * @param align Where to align the item in the viewport
1595
1716
  * @param margin In 'smart' mode the viewport proportion to add
1717
+ * @param precomputed Precomputed values to use when windowing is disabled.
1718
+ * @param alignPreference Allows to override the alignment of item when the `auto` heuristic decides that the item needs to be scrolled into view.
1596
1719
  * @returns The needed scroll offset
1597
1720
  */
1598
1721
  getOffsetForIndexAndAlignment(
1599
1722
  index: number,
1600
1723
  align?: ScrollToAlign,
1601
- margin?: number
1724
+ margin?: number,
1725
+ precomputed?: {
1726
+ totalSize: number;
1727
+ itemMetadata: WindowedList.ItemMetadata;
1728
+ currentOffset: number;
1729
+ },
1730
+ alignPreference?: WindowedList.BaseScrollToAlignment
1602
1731
  ): number;
1603
1732
 
1604
1733
  /**
@@ -1810,9 +1939,14 @@ export namespace WindowedList {
1810
1939
  };
1811
1940
 
1812
1941
  /**
1813
- * Type of scroll
1942
+ * Basic type of scroll alignment
1943
+ */
1944
+ export type BaseScrollToAlignment = 'center' | 'top-center' | 'start' | 'end';
1945
+
1946
+ /**
1947
+ * Type of scroll alignment including `auto` and `smart`
1814
1948
  */
1815
- export type ScrollToAlign = 'auto' | 'smart' | 'center' | 'start' | 'end';
1949
+ export type ScrollToAlign = 'auto' | 'smart' | BaseScrollToAlignment;
1816
1950
 
1817
1951
  /**
1818
1952
  * Widget range in view port