@jupyterlab/ui-components 4.1.0-alpha.4 → 4.1.0-beta.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.
@@ -204,7 +204,7 @@ export declare abstract class WindowedListModel implements WindowedList.IModel {
204
204
  /**
205
205
  * Windowed list widget
206
206
  */
207
- export declare class WindowedList<T extends WindowedList.IModel = WindowedList.IModel> extends Widget {
207
+ export declare class WindowedList<T extends WindowedList.IModel = WindowedList.IModel, U = any> extends Widget {
208
208
  /**
209
209
  * Default widget size
210
210
  */
@@ -214,7 +214,7 @@ export declare class WindowedList<T extends WindowedList.IModel = WindowedList.I
214
214
  *
215
215
  * @param options Constructor options
216
216
  */
217
- constructor(options: WindowedList.IOptions<T>);
217
+ constructor(options: WindowedList.IOptions<T, U>);
218
218
  /**
219
219
  * Whether the parent is hidden or not.
220
220
  *
@@ -227,10 +227,23 @@ export declare class WindowedList<T extends WindowedList.IModel = WindowedList.I
227
227
  * Widget layout
228
228
  */
229
229
  get layout(): WindowedLayout;
230
+ /**
231
+ * The outer container of the windowed list.
232
+ */
233
+ get outerNode(): HTMLElement;
230
234
  /**
231
235
  * Viewport
232
236
  */
233
- get viewportNode(): HTMLDivElement;
237
+ get viewportNode(): HTMLElement;
238
+ /**
239
+ * Flag to enable virtual scrollbar.
240
+ */
241
+ get scrollbar(): boolean;
242
+ set scrollbar(enabled: boolean);
243
+ /**
244
+ * The renderer for this windowed list. Set at instantiation.
245
+ */
246
+ protected renderer: WindowedList.IRenderer<U>;
234
247
  /**
235
248
  * Windowed list view model
236
249
  */
@@ -301,24 +314,58 @@ export declare class WindowedList<T extends WindowedList.IModel = WindowedList.I
301
314
  * The default implementation of this handler is a no-op.
302
315
  */
303
316
  protected onUpdateRequest(msg: Message): void;
317
+ /**
318
+ * A signal that emits the index when the virtual scrollbar jumps to an item.
319
+ */
320
+ protected jumped: Signal<this, number>;
321
+ private _adjustDimensionsForScrollbar;
322
+ /**
323
+ * Add listeners for viewport, contents and the virtual scrollbar.
324
+ */
304
325
  private _addListeners;
326
+ /**
327
+ * Turn off windowing related styles in the viewport.
328
+ */
305
329
  private _applyNoWindowingStyles;
330
+ /**
331
+ * Remove listeners for viewport and contents (but not the virtual scrollbar).
332
+ */
306
333
  private _removeListeners;
334
+ /**
335
+ * Update viewport and DOM state.
336
+ */
307
337
  private _update;
338
+ /**
339
+ * Handle viewport content (e.g. widgets) resize.
340
+ */
308
341
  private _onWidgetResize;
342
+ /**
343
+ * Clear any outstanding timeout and enqueue scrolling to a new item.
344
+ */
309
345
  private _resetScrollToItem;
310
- protected _viewModel: T;
346
+ /**
347
+ * Render virtual scrollbar.
348
+ */
349
+ private _renderScrollbar;
350
+ /**
351
+ * Handle `pointerdown` events on the virtual scrollbar.
352
+ */
353
+ private _evtPointerDown;
311
354
  private _innerElement;
312
355
  private _isParentHidden;
313
356
  private _isScrolling;
314
357
  private _needsUpdate;
315
- private _windowElement;
358
+ private _outerElement;
316
359
  private _resetScrollToItemTimeout;
317
360
  private _resizeObserver;
361
+ private _scrollbarElement;
362
+ private _scrollbarResizeObserver;
318
363
  private _scrollRepaint;
319
364
  private _scrollToItem;
320
365
  private _scrollUpdateWasRequested;
321
366
  private _updater;
367
+ private _viewModel;
368
+ private _viewport;
322
369
  }
323
370
  /**
324
371
  * Customized layout for windowed list container.
@@ -405,10 +452,35 @@ export declare class WindowedLayout extends PanelLayout {
405
452
  * A namespace for windowed list
406
453
  */
407
454
  export declare namespace WindowedList {
455
+ /**
456
+ * The default renderer class for windowed lists.
457
+ */
458
+ class Renderer<T = any> implements IRenderer<T> {
459
+ /**
460
+ * Create the outer, root element of the windowed list.
461
+ */
462
+ createOuter(): HTMLElement;
463
+ /**
464
+ * Create the virtual scrollbar element.
465
+ */
466
+ createScrollbar(): HTMLOListElement;
467
+ /**
468
+ * Create an individual item rendered in the scrollbar.
469
+ */
470
+ createScrollbarItem(_: WindowedList, index: number): HTMLLIElement;
471
+ /**
472
+ * Create the viewport element into which virtualized children are added.
473
+ */
474
+ createViewport(): HTMLElement;
475
+ }
476
+ /**
477
+ * The default renderer for windowed lists.
478
+ */
479
+ const defaultRenderer: Renderer<any>;
408
480
  /**
409
481
  * Windowed list model interface
410
482
  */
411
- interface IModel extends IDisposable {
483
+ interface IModel<T = any> extends IDisposable {
412
484
  /**
413
485
  * Provide a best guess for the widget size at position index
414
486
  *
@@ -475,6 +547,7 @@ export declare namespace WindowedList {
475
547
  * Items list to be rendered
476
548
  */
477
549
  itemsList: {
550
+ get?: (index: number) => T;
478
551
  length: number;
479
552
  changed: ISignal<any, IObservableList.IChangedArgs<any>>;
480
553
  } | null;
@@ -561,7 +634,7 @@ export declare namespace WindowedList {
561
634
  /**
562
635
  * Windowed list view constructor options
563
636
  */
564
- interface IOptions<T extends WindowedList.IModel = WindowedList.IModel> {
637
+ interface IOptions<T extends WindowedList.IModel = WindowedList.IModel, U = any> {
565
638
  /**
566
639
  * Windowed list model to display
567
640
  */
@@ -570,6 +643,35 @@ export declare namespace WindowedList {
570
643
  * Windowed list layout
571
644
  */
572
645
  layout?: WindowedLayout;
646
+ /**
647
+ * A renderer for the elements of the windowed list.
648
+ */
649
+ renderer?: IRenderer<U>;
650
+ /**
651
+ * Whether the windowed list should display a scrollbar UI.
652
+ */
653
+ scrollbar?: boolean;
654
+ }
655
+ /**
656
+ * A windowed list element renderer.
657
+ */
658
+ interface IRenderer<T = any> {
659
+ /**
660
+ * Create the outer, root element of the windowed list.
661
+ */
662
+ createOuter(): HTMLElement;
663
+ /**
664
+ * Create the virtual scrollbar element.
665
+ */
666
+ createScrollbar(): HTMLElement;
667
+ /**
668
+ * Create an individual item rendered in the scrollbar.
669
+ */
670
+ createScrollbarItem(list: WindowedList, index: number, item: T | undefined): HTMLElement;
671
+ /**
672
+ * Create the viewport element into which virtualized children are added.
673
+ */
674
+ createViewport(): HTMLElement;
573
675
  }
574
676
  /**
575
677
  * Item list metadata
@@ -564,27 +564,43 @@ export class WindowedList extends Widget {
564
564
  * @param options Constructor options
565
565
  */
566
566
  constructor(options) {
567
- var _a;
568
- // TODO probably needs to be able to customize outer HTML tag (could be ul / ol / table, ...)
567
+ var _a, _b;
568
+ const renderer = (_a = options.renderer) !== null && _a !== void 0 ? _a : WindowedList.defaultRenderer;
569
569
  const node = document.createElement('div');
570
- node.className = 'jp-WindowedPanel-outer';
571
- const innerElement = node.appendChild(document.createElement('div'));
570
+ node.className = 'jp-WindowedPanel';
571
+ const scrollbarElement = node.appendChild(document.createElement('div'));
572
+ scrollbarElement.classList.add('jp-WindowedPanel-scrollbar');
573
+ const list = scrollbarElement.appendChild(renderer.createScrollbar());
574
+ list.classList.add('jp-WindowedPanel-scrollbar-content');
575
+ const outerElement = node.appendChild(renderer.createOuter());
576
+ outerElement.classList.add('jp-WindowedPanel-outer');
577
+ const innerElement = outerElement.appendChild(document.createElement('div'));
572
578
  innerElement.className = 'jp-WindowedPanel-inner';
573
- const windowContainer = innerElement.appendChild(document.createElement('div'));
574
- windowContainer.className = 'jp-WindowedPanel-window';
579
+ const viewport = innerElement.appendChild(renderer.createViewport());
580
+ viewport.classList.add('jp-WindowedPanel-viewport');
575
581
  super({ node });
582
+ /**
583
+ * A signal that emits the index when the virtual scrollbar jumps to an item.
584
+ */
585
+ this.jumped = new Signal(this);
576
586
  this._needsUpdate = false;
577
- super.layout = (_a = options.layout) !== null && _a !== void 0 ? _a : new WindowedLayout();
578
- this._viewModel = options.model;
587
+ super.layout = (_b = options.layout) !== null && _b !== void 0 ? _b : new WindowedLayout();
588
+ this.renderer = renderer;
579
589
  this._innerElement = innerElement;
580
590
  this._isScrolling = null;
581
- this._windowElement = windowContainer;
591
+ this._outerElement = outerElement;
592
+ this._resizeObserver = null;
593
+ this._scrollbarElement = scrollbarElement;
582
594
  this._scrollToItem = null;
583
595
  this._scrollRepaint = null;
584
596
  this._scrollUpdateWasRequested = false;
585
597
  this._updater = new Throttler(() => this.update(), 50);
586
- this._resizeObserver = null;
587
- this._viewModel.stateChanged.connect(this.onStateChanged, this);
598
+ this._viewModel = options.model;
599
+ this._viewport = viewport;
600
+ if (options.scrollbar) {
601
+ node.classList.add('jp-mod-virtual-scrollbar');
602
+ }
603
+ this.viewModel.stateChanged.connect(this.onStateChanged, this);
588
604
  }
589
605
  /**
590
606
  * Whether the parent is hidden or not.
@@ -604,11 +620,33 @@ export class WindowedList extends Widget {
604
620
  get layout() {
605
621
  return super.layout;
606
622
  }
623
+ /**
624
+ * The outer container of the windowed list.
625
+ */
626
+ get outerNode() {
627
+ return this._outerElement;
628
+ }
607
629
  /**
608
630
  * Viewport
609
631
  */
610
632
  get viewportNode() {
611
- return this._windowElement;
633
+ return this._viewport;
634
+ }
635
+ /**
636
+ * Flag to enable virtual scrollbar.
637
+ */
638
+ get scrollbar() {
639
+ return this.node.classList.contains('jp-mod-virtual-scrollbar');
640
+ }
641
+ set scrollbar(enabled) {
642
+ if (enabled) {
643
+ this.node.classList.add('jp-mod-virtual-scrollbar');
644
+ }
645
+ else {
646
+ this.node.classList.remove('jp-mod-virtual-scrollbar');
647
+ }
648
+ this._adjustDimensionsForScrollbar();
649
+ this.update();
612
650
  }
613
651
  /**
614
652
  * Windowed list view model
@@ -630,6 +668,11 @@ export class WindowedList extends Widget {
630
668
  */
631
669
  handleEvent(event) {
632
670
  switch (event.type) {
671
+ case 'pointerdown':
672
+ event.preventDefault();
673
+ event.stopPropagation();
674
+ this._evtPointerDown(event);
675
+ break;
633
676
  case 'scroll':
634
677
  this.onScroll(event);
635
678
  break;
@@ -692,7 +735,7 @@ export class WindowedList extends Widget {
692
735
  }
693
736
  this._scrollToItem = [index, align];
694
737
  this._resetScrollToItem();
695
- this.scrollTo(this.viewModel.getOffsetForIndexAndAlignment(Math.max(0, Math.min(index, this._viewModel.widgetCount - 1)), align, margin));
738
+ this.scrollTo(this.viewModel.getOffsetForIndexAndAlignment(Math.max(0, Math.min(index, this.viewModel.widgetCount - 1)), align, margin));
696
739
  return this._isScrolling.promise;
697
740
  }
698
741
  /**
@@ -700,7 +743,7 @@ export class WindowedList extends Widget {
700
743
  */
701
744
  onAfterAttach(msg) {
702
745
  super.onAfterAttach(msg);
703
- if (this._viewModel.windowingActive) {
746
+ if (this.viewModel.windowingActive) {
704
747
  this._addListeners();
705
748
  }
706
749
  else {
@@ -709,14 +752,17 @@ export class WindowedList extends Widget {
709
752
  this.viewModel.height = this.node.getBoundingClientRect().height;
710
753
  const style = window.getComputedStyle(this.node);
711
754
  this.viewModel.paddingTop = parseFloat(style.paddingTop);
755
+ this._scrollbarElement.addEventListener('pointerdown', this);
712
756
  }
713
757
  /**
714
758
  * A message handler invoked on an `'before-detach'` message.
715
759
  */
716
760
  onBeforeDetach(msg) {
717
- if (this._viewModel.windowingActive) {
761
+ if (this.viewModel.windowingActive) {
718
762
  this._removeListeners();
719
763
  }
764
+ this._scrollbarElement.removeEventListener('pointerdown', this);
765
+ super.onBeforeDetach(msg);
720
766
  }
721
767
  /**
722
768
  * Callback on scroll event
@@ -753,6 +799,7 @@ export class WindowedList extends Widget {
753
799
  void this._updater.invoke();
754
800
  }
755
801
  super.onResize(msg);
802
+ void this._updater.invoke();
756
803
  }
757
804
  /**
758
805
  * Callback on view model change
@@ -783,6 +830,9 @@ export class WindowedList extends Widget {
783
830
  * The default implementation of this handler is a no-op.
784
831
  */
785
832
  onUpdateRequest(msg) {
833
+ if (this.scrollbar) {
834
+ this._renderScrollbar();
835
+ }
786
836
  if (this.viewModel.windowingActive) {
787
837
  // Throttle update request
788
838
  if (this._scrollRepaint === null) {
@@ -804,6 +854,46 @@ export class WindowedList extends Widget {
804
854
  this._update();
805
855
  }
806
856
  }
857
+ /*
858
+ * Hide the native scrollbar if necessary and update dimensions
859
+ */
860
+ _adjustDimensionsForScrollbar() {
861
+ const outer = this._outerElement;
862
+ const scrollbar = this._scrollbarElement;
863
+ if (this.scrollbar) {
864
+ // Query DOM
865
+ let outerScrollbarWidth = outer.offsetWidth - outer.clientWidth;
866
+ // Update DOM
867
+ // 1) The native scrollbar is hidden by shifting it out of view.
868
+ if (outerScrollbarWidth == 0) {
869
+ // If the scrollbar width is zero, one of the following is true:
870
+ // - (a) the content is not overflowing
871
+ // - (b) the browser uses overlay scrollbars
872
+ // In (b) the overlay scrollbars could show up even even if
873
+ // occluded by a child element; to prevent this resulting in
874
+ // double scrollbar we shift the content by an arbitrary offset.
875
+ outerScrollbarWidth = 1000;
876
+ outer.style.paddingRight = `${outerScrollbarWidth}px`;
877
+ outer.style.boxSizing = 'border-box';
878
+ }
879
+ else {
880
+ outer.style.paddingRight = '0';
881
+ }
882
+ outer.style.width = `calc(100% + ${outerScrollbarWidth}px)`;
883
+ // 2) The inner window is shrank to accommodate the virtual scrollbar
884
+ this._innerElement.style.marginRight = `${scrollbar.offsetWidth}px`;
885
+ }
886
+ else {
887
+ // Reset all styles that may have been touched.
888
+ outer.style.width = '100%';
889
+ this._innerElement.style.marginRight = '0';
890
+ outer.style.paddingRight = '0';
891
+ outer.style.boxSizing = '';
892
+ }
893
+ }
894
+ /**
895
+ * Add listeners for viewport, contents and the virtual scrollbar.
896
+ */
807
897
  _addListeners() {
808
898
  if (!this._resizeObserver) {
809
899
  this._resizeObserver = new ResizeObserver(this._onWidgetResize.bind(this));
@@ -812,20 +902,34 @@ export class WindowedList extends Widget {
812
902
  this._resizeObserver.observe(widget.node);
813
903
  widget.disposed.connect(() => { var _a; return (_a = this._resizeObserver) === null || _a === void 0 ? void 0 : _a.unobserve(widget.node); });
814
904
  }
815
- this.node.addEventListener('scroll', this, passiveIfSupported);
816
- this._windowElement.style.position = 'absolute';
905
+ this._outerElement.addEventListener('scroll', this, passiveIfSupported);
906
+ this._viewport.style.position = 'absolute';
907
+ this._scrollbarResizeObserver = new ResizeObserver(this._adjustDimensionsForScrollbar.bind(this));
908
+ this._scrollbarResizeObserver.observe(this._outerElement);
909
+ this._scrollbarResizeObserver.observe(this._scrollbarElement);
817
910
  }
911
+ /**
912
+ * Turn off windowing related styles in the viewport.
913
+ */
818
914
  _applyNoWindowingStyles() {
819
- this._windowElement.style.position = 'relative';
820
- this._windowElement.style.top = '0px';
915
+ this._viewport.style.position = 'relative';
916
+ this._viewport.style.top = '0px';
821
917
  }
918
+ /**
919
+ * Remove listeners for viewport and contents (but not the virtual scrollbar).
920
+ */
822
921
  _removeListeners() {
823
- var _a;
824
- this.node.removeEventListener('scroll', this);
922
+ var _a, _b;
923
+ this._outerElement.removeEventListener('scroll', this);
825
924
  (_a = this._resizeObserver) === null || _a === void 0 ? void 0 : _a.disconnect();
826
925
  this._resizeObserver = null;
926
+ (_b = this._scrollbarResizeObserver) === null || _b === void 0 ? void 0 : _b.disconnect();
927
+ this._scrollbarResizeObserver = null;
827
928
  this._applyNoWindowingStyles();
828
929
  }
930
+ /**
931
+ * Update viewport and DOM state.
932
+ */
829
933
  _update() {
830
934
  var _a;
831
935
  if (this.isDisposed || !this.layout) {
@@ -868,25 +972,25 @@ export class WindowedList extends Widget {
868
972
  this._innerElement.style.height = `${estimatedTotalHeight}px`;
869
973
  // Update position of window container
870
974
  const [top, minHeight] = this.viewModel.getSpan(startIndex, stopIndex);
871
- this._windowElement.style.top = `${top}px`;
872
- this._windowElement.style.minHeight = `${minHeight}px`;
975
+ this._viewport.style.top = `${top}px`;
976
+ this._viewport.style.minHeight = `${minHeight}px`;
873
977
  }
874
978
  else {
875
979
  // Update inner container height
876
980
  this._innerElement.style.height = `0px`;
877
- // Update position of window container
878
- this._windowElement.style.top = `0px`;
879
- this._windowElement.style.minHeight = `0px`;
981
+ // Update position of viewport node
982
+ this._viewport.style.top = `0px`;
983
+ this._viewport.style.minHeight = `0px`;
880
984
  }
881
985
  // Update scroll
882
986
  if (this._scrollUpdateWasRequested) {
883
- this.node.scrollTop = this.viewModel.scrollOffset;
987
+ this._outerElement.scrollTop = this.viewModel.scrollOffset;
884
988
  this._scrollUpdateWasRequested = false;
885
989
  }
886
990
  }
887
991
  }
888
992
  let index2 = -1;
889
- for (const w of this.viewportNode.children) {
993
+ for (const w of this._viewport.children) {
890
994
  const currentIdx = parseInt(w.dataset.windowedListIndex, 10);
891
995
  if (currentIdx < index2) {
892
996
  throw new Error('Inconsistent dataset index');
@@ -896,6 +1000,9 @@ export class WindowedList extends Widget {
896
1000
  }
897
1001
  }
898
1002
  }
1003
+ /**
1004
+ * Handle viewport content (e.g. widgets) resize.
1005
+ */
899
1006
  _onWidgetResize(entries) {
900
1007
  this._resetScrollToItem();
901
1008
  if (this.isHidden || this.isParentHidden) {
@@ -924,6 +1031,9 @@ export class WindowedList extends Widget {
924
1031
  this.update();
925
1032
  }
926
1033
  }
1034
+ /**
1035
+ * Clear any outstanding timeout and enqueue scrolling to a new item.
1036
+ */
927
1037
  _resetScrollToItem() {
928
1038
  if (this._resetScrollToItemTimeout) {
929
1039
  clearTimeout(this._resetScrollToItemTimeout);
@@ -938,6 +1048,42 @@ export class WindowedList extends Widget {
938
1048
  }, MAXIMUM_TIME_REMAINING);
939
1049
  }
940
1050
  }
1051
+ /**
1052
+ * Render virtual scrollbar.
1053
+ */
1054
+ _renderScrollbar() {
1055
+ var _a, _b;
1056
+ const { node, renderer, viewModel } = this;
1057
+ const content = node.querySelector('.jp-WindowedPanel-scrollbar-content');
1058
+ while (content.firstChild) {
1059
+ content.removeChild(content.firstChild);
1060
+ }
1061
+ const list = viewModel.itemsList;
1062
+ const count = (_a = list === null || list === void 0 ? void 0 : list.length) !== null && _a !== void 0 ? _a : viewModel.widgetCount;
1063
+ for (let index = 0; index < count; index += 1) {
1064
+ const item = (_b = list === null || list === void 0 ? void 0 : list.get) === null || _b === void 0 ? void 0 : _b.call(list, index);
1065
+ const element = renderer.createScrollbarItem(this, index, item);
1066
+ element.classList.add('jp-WindowedPanel-scrollbar-item');
1067
+ element.dataset.index = `${index}`;
1068
+ content.appendChild(element);
1069
+ }
1070
+ }
1071
+ /**
1072
+ * Handle `pointerdown` events on the virtual scrollbar.
1073
+ */
1074
+ _evtPointerDown(event) {
1075
+ let target = event.target;
1076
+ while (target && target.parentElement) {
1077
+ if (target.hasAttribute('data-index')) {
1078
+ const index = parseInt(target.getAttribute('data-index'), 10);
1079
+ return void (async () => {
1080
+ await this.scrollToItem(index);
1081
+ this.jumped.emit(index);
1082
+ })();
1083
+ }
1084
+ target = target.parentElement;
1085
+ }
1086
+ }
941
1087
  }
942
1088
  /**
943
1089
  * Default widget size
@@ -1067,4 +1213,45 @@ export class WindowedLayout extends PanelLayout {
1067
1213
  // This is a no-op.
1068
1214
  }
1069
1215
  }
1216
+ /**
1217
+ * A namespace for windowed list
1218
+ */
1219
+ (function (WindowedList) {
1220
+ /**
1221
+ * The default renderer class for windowed lists.
1222
+ */
1223
+ class Renderer {
1224
+ /**
1225
+ * Create the outer, root element of the windowed list.
1226
+ */
1227
+ createOuter() {
1228
+ return document.createElement('div');
1229
+ }
1230
+ /**
1231
+ * Create the virtual scrollbar element.
1232
+ */
1233
+ createScrollbar() {
1234
+ return document.createElement('ol');
1235
+ }
1236
+ /**
1237
+ * Create an individual item rendered in the scrollbar.
1238
+ */
1239
+ createScrollbarItem(_, index) {
1240
+ const li = document.createElement('li');
1241
+ li.appendChild(document.createTextNode(`${index}`));
1242
+ return li;
1243
+ }
1244
+ /**
1245
+ * Create the viewport element into which virtualized children are added.
1246
+ */
1247
+ createViewport() {
1248
+ return document.createElement('div');
1249
+ }
1250
+ }
1251
+ WindowedList.Renderer = Renderer;
1252
+ /**
1253
+ * The default renderer for windowed lists.
1254
+ */
1255
+ WindowedList.defaultRenderer = new Renderer();
1256
+ })(WindowedList || (WindowedList = {}));
1070
1257
  //# sourceMappingURL=windowedlist.js.map