1 | import { Component, ComponentClass, ComponentType, CSSProperties, FunctionComponent, Key, Ref } from "react";
|
2 |
|
3 | export type CSSDirection = "ltr" | "rtl";
|
4 | export type Direction = "vertical" | "horizontal"; // TODO: deprecate in favour of Layout
|
5 | export type Layout = "vertical" | "horizontal";
|
6 | export type ScrollDirection = "forward" | "backward";
|
7 | export type Align = "auto" | "smart" | "center" | "end" | "start";
|
8 |
|
9 | export interface ListChildComponentProps<T = any> {
|
10 | index: number;
|
11 | style: CSSProperties;
|
12 | data: T;
|
13 | isScrolling?: boolean | undefined;
|
14 | }
|
15 |
|
16 | export interface GridChildComponentProps<T = any> {
|
17 | columnIndex: number;
|
18 | rowIndex: number;
|
19 | style: CSSProperties;
|
20 | data: T;
|
21 | isScrolling?: boolean | undefined;
|
22 | }
|
23 |
|
24 | // This is supposed to represent the type of the first parameter to
|
25 | // React.createElement.
|
26 | export type ReactElementType =
|
27 | | FunctionComponent<any>
|
28 | | ComponentClass<any>
|
29 | | string;
|
30 |
|
31 | export interface CommonProps<T = any> {
|
32 | /**
|
33 | * Optional CSS class to attach to outermost <div> element.
|
34 | */
|
35 | className?: string | undefined;
|
36 | /**
|
37 | * Tag name passed to document.createElement to create the inner container element. This is an advanced property; in most cases, the default ("div") should be used.
|
38 | */
|
39 | innerElementType?: ReactElementType | undefined;
|
40 | /**
|
41 | * Ref to attach to the inner container element. This is an advanced property.
|
42 | */
|
43 | innerRef?: Ref<any> | undefined;
|
44 | /**
|
45 | * Tag name passed to document.createElement to create the inner container element. This is an advanced property; in most cases, the default ("div") should be used.
|
46 | *
|
47 | * @deprecated since 1.4.0
|
48 | */
|
49 | innerTagName?: string | undefined;
|
50 | /**
|
51 | * Contextual data to be passed to the item renderer as a data prop. This is a light-weight alternative to React's built-in context API.
|
52 | *
|
53 | * Item data is useful for item renderers that are class components.
|
54 | */
|
55 | itemData?: T | undefined;
|
56 | /**
|
57 | * Tag name passed to document.createElement to create the outer container element. This is an advanced property; in most cases, the default ("div") should be used.
|
58 | */
|
59 | outerElementType?: ReactElementType | undefined;
|
60 | /**
|
61 | * Ref to attach to the outer container element. This is an advanced property.
|
62 | */
|
63 | outerRef?: Ref<any> | undefined;
|
64 | /**
|
65 | * Tag name passed to document.createElement to create the outer container element. This is an advanced property; in most cases, the default ("div") should be used.
|
66 | *
|
67 | * @deprecated since 1.4.0
|
68 | */
|
69 | outerTagName?: string | undefined;
|
70 | /**
|
71 | * Optional inline style to attach to outermost <div> element.
|
72 | */
|
73 | style?: CSSProperties | undefined;
|
74 | /**
|
75 | * Adds an additional isScrolling parameter to the children render function. This parameter can be used to show a placeholder row or column while the list is being scrolled.
|
76 | *
|
77 | * Note that using this parameter will result in an additional render call after scrolling has stopped (when isScrolling changes from true to false).
|
78 | */
|
79 | useIsScrolling?: boolean | undefined;
|
80 | }
|
81 |
|
82 | export type ListItemKeySelector<T = any> = (index: number, data: T) => Key;
|
83 |
|
84 | export interface ListOnItemsRenderedProps {
|
85 | overscanStartIndex: number;
|
86 | overscanStopIndex: number;
|
87 | visibleStartIndex: number;
|
88 | visibleStopIndex: number;
|
89 | }
|
90 |
|
91 | export interface ListOnScrollProps {
|
92 | scrollDirection: ScrollDirection;
|
93 | scrollOffset: number;
|
94 | scrollUpdateWasRequested: boolean;
|
95 | }
|
96 |
|
97 | export interface ListProps<T = any> extends CommonProps<T> {
|
98 | /**
|
99 | * React component responsible for rendering the individual item specified by an index prop. This component also receives a style prop (used for positioning).
|
100 | *
|
101 | * If useIsScrolling is enabled for the list, the component also receives an additional isScrolling boolean prop.
|
102 | */
|
103 | children: ComponentType<ListChildComponentProps<T>>;
|
104 | /**
|
105 | * Height of the list.
|
106 | *
|
107 | * For vertical lists, this must be a number. It affects the number of rows that will be rendered (and displayed) at any given time.
|
108 | *
|
109 | * For horizontal lists, this can be a number or a string (e.g. "50%").
|
110 | */
|
111 | height: number | string;
|
112 | /**
|
113 | * Total number of items in the list. Note that only a few items will be rendered and displayed at a time.
|
114 | */
|
115 | itemCount: number;
|
116 | /**
|
117 | * Width of the list.
|
118 | *
|
119 | * For horizontal lists, this must be a number. It affects the number of columns that will be rendered (and displayed) at any given time.
|
120 | *
|
121 | * For vertical lists, this can be a number or a string (e.g. "50%").
|
122 | */
|
123 | width: number | string;
|
124 | /**
|
125 | * Determines the direction of text and horizontal scrolling.
|
126 | *
|
127 | * This property also automatically sets the CSS direction style for the list component.
|
128 | *
|
129 | * Specifying "horizontal" or "vertical" for this value is deprecated. Use "layout" prop instead.
|
130 | *
|
131 | * @default "ltr"
|
132 | */
|
133 | direction?: CSSDirection | Direction | undefined;
|
134 | /**
|
135 | * Layout/orientation of the list.
|
136 | *
|
137 | * Acceptable values are:
|
138 | * - "vertical" (default) - Up/down scrolling.
|
139 | * - "horizontal" - Left/right scrolling.
|
140 | *
|
141 | * Note that lists may scroll in both directions (depending on CSS) but content will only be windowed in the layout direction specified.
|
142 | */
|
143 | layout?: Layout | undefined;
|
144 | /**
|
145 | * Scroll offset for initial render.
|
146 | *
|
147 | * For vertical lists, this affects scrollTop. For horizontal lists, this affects scrollLeft.
|
148 | */
|
149 | initialScrollOffset?: number | undefined;
|
150 | /**
|
151 | * By default, lists will use an item's index as its key. This is okay if:
|
152 | *
|
153 | * - Your collections of items is never sorted or modified
|
154 | * - Your item renderer is not stateful and does not extend PureComponent
|
155 | *
|
156 | * If your list does not satisfy the above constraints, use the itemKey property to specify your own keys for items
|
157 | */
|
158 | itemKey?: ListItemKeySelector<T> | undefined;
|
159 | /**
|
160 | * The number of items (rows or columns) to render outside of the visible area. This property can be important for two reasons:
|
161 | *
|
162 | * - Overscanning by one row or column allows the tab key to focus on the next (not yet visible) item.
|
163 | * - Overscanning slightly can reduce or prevent a flash of empty space when a user first starts scrolling.
|
164 | *
|
165 | * Note that overscanning too much can negatively impact performance. By default, List overscans by one item.
|
166 | */
|
167 | overscanCount?: number | undefined;
|
168 | /**
|
169 | * Called when the items rendered by the list change.
|
170 | */
|
171 | onItemsRendered?: ((props: ListOnItemsRenderedProps) => any) | undefined;
|
172 | /**
|
173 | * Called when the list scroll positions changes, as a result of user scrolling or scroll-to method calls.
|
174 | */
|
175 | onScroll?: ((props: ListOnScrollProps) => any) | undefined;
|
176 | }
|
177 |
|
178 | export type GridItemKeySelector<T = any> = (params: {
|
179 | columnIndex: number;
|
180 | rowIndex: number;
|
181 | data: T;
|
182 | }) => Key;
|
183 |
|
184 | export interface GridOnItemsRenderedProps {
|
185 | overscanColumnStartIndex: number;
|
186 | overscanColumnStopIndex: number;
|
187 | overscanRowStartIndex: number;
|
188 | overscanRowStopIndex: number;
|
189 | visibleColumnStartIndex: number;
|
190 | visibleColumnStopIndex: number;
|
191 | visibleRowStartIndex: number;
|
192 | visibleRowStopIndex: number;
|
193 | }
|
194 |
|
195 | export interface GridOnScrollProps {
|
196 | horizontalScrollDirection: ScrollDirection;
|
197 | scrollLeft: number;
|
198 | scrollTop: number;
|
199 | scrollUpdateWasRequested: boolean;
|
200 | verticalScrollDirection: ScrollDirection;
|
201 | }
|
202 |
|
203 | export interface GridProps<T = any> extends CommonProps<T> {
|
204 | /**
|
205 | * React component responsible for rendering the individual item specified by an index prop. This component also receives a style prop (used for positioning).
|
206 | *
|
207 | * If useIsScrolling is enabled for the list, the component also receives an additional isScrolling boolean prop.
|
208 | */
|
209 | children: ComponentType<GridChildComponentProps<T>>;
|
210 | /**
|
211 | * Number of columns in the grid. Note that only a few columns will be rendered and displayed at a time.
|
212 | */
|
213 | columnCount: number;
|
214 | /**
|
215 | * Determines the direction of text and horizontal scrolling.
|
216 | *
|
217 | * This property also automatically sets the CSS direction style for the grid component.
|
218 | *
|
219 | * @default "ltr"
|
220 | */
|
221 | direction?: CSSDirection | undefined;
|
222 | /**
|
223 | * Height of the grid. This affects the number of rows that will be rendered (and displayed) at any given time.
|
224 | */
|
225 | height: number;
|
226 | /**
|
227 | * Horizontal scroll offset for initial render.
|
228 | */
|
229 | initialScrollLeft?: number | undefined;
|
230 | /**
|
231 | * Vertical scroll offset for initial render.
|
232 | */
|
233 | initialScrollTop?: number | undefined;
|
234 | /**
|
235 | * By default, grids will use an item's indices as its key. This is okay if:
|
236 | *
|
237 | * - Your collections of items is never sorted or modified
|
238 | * - Your item renderer is not stateful and does not extend PureComponent
|
239 | *
|
240 | * If your grid does not satisfy the above constraints, use the itemKey property to specify your own keys for items.
|
241 | */
|
242 | itemKey?: GridItemKeySelector<T> | undefined;
|
243 | /**
|
244 | * Called when the items rendered by the grid change.
|
245 | */
|
246 | onItemsRendered?: ((props: GridOnItemsRenderedProps) => any) | undefined;
|
247 | /**
|
248 | * Called when the grid scroll positions changes, as a result of user scrolling or scroll-to method calls.
|
249 | */
|
250 | onScroll?: ((props: GridOnScrollProps) => any) | undefined;
|
251 | /**
|
252 | * @deprecated since version 1.8.2, please use overscanColumnCount
|
253 | */
|
254 | overscanColumnsCount?: number | undefined;
|
255 | /**
|
256 | * The number of columns to render outside of the visible area. This property can be important for two reasons:
|
257 | *
|
258 | * - Overscanning by one row or column allows the tab key to focus on the next (not yet visible) item.
|
259 | * - Overscanning slightly can reduce or prevent a flash of empty space when a user first starts scrolling.
|
260 | *
|
261 | * Note that overscanning too much can negatively impact performance. By default, grid overscans by one item.
|
262 | */
|
263 | overscanColumnCount?: number | undefined;
|
264 | /**
|
265 | * @deprecated since version 1.8.2, please use overscanRowCount
|
266 | */
|
267 | overscanRowsCount?: number | undefined;
|
268 | /**
|
269 | * The number of rows to render outside of the visible area. This property can be important for two reasons:
|
270 | *
|
271 | * - Overscanning by one row or column allows the tab key to focus on the next (not yet visible) item.
|
272 | * - Overscanning slightly can reduce or prevent a flash of empty space when a user first starts scrolling.
|
273 | *
|
274 | * Note that overscanning too much can negatively impact performance. By default, grid overscans by one item.
|
275 | */
|
276 | overscanRowCount?: number | undefined;
|
277 | /**
|
278 | * The number of items (rows or columns) to render outside of the visible area. This property can be important for two reasons:
|
279 | *
|
280 | * - Overscanning by one row or column allows the tab key to focus on the next (not yet visible) item.
|
281 | * - Overscanning slightly can reduce or prevent a flash of empty space when a user first starts scrolling.
|
282 | *
|
283 | * Note that overscanning too much can negatively impact performance. By default, grid overscans by one item.
|
284 | *
|
285 | * @deprecated since version 1.4.0
|
286 | */
|
287 | overscanCount?: number | undefined;
|
288 | /**
|
289 | * Number of rows in the grid. Note that only a few rows will be rendered and displayed at a time.
|
290 | */
|
291 | rowCount: number;
|
292 | /**
|
293 | * Width of the grid. This affects the number of columns that will be rendered (and displayed) at any given time.
|
294 | */
|
295 | width: number;
|
296 | }
|
297 |
|
298 | export interface FixedSizeListProps<T = any> extends ListProps<T> {
|
299 | /**
|
300 | * Size of a item in the direction being windowed. For vertical lists, this is the row height. For horizontal lists, this is the column width.
|
301 | */
|
302 | itemSize: number;
|
303 | }
|
304 |
|
305 | export interface VariableSizeListProps<T = any> extends ListProps<T> {
|
306 | /**
|
307 | * Estimated size of a item in the direction being windowed. For vertical lists, this is the row height. For horizontal lists, this is the column width.
|
308 | *
|
309 | * This value is used to calculated the estimated total size of a list before its items have all been measured. The total size impacts user scrolling behavior.
|
310 | * It is updated whenever new items are measured.
|
311 | */
|
312 | estimatedItemSize?: number | undefined;
|
313 | /**
|
314 | * Returns the size of a item in the direction being windowed. For vertical lists, this is the row height. For horizontal lists, this is the column width.
|
315 | */
|
316 | itemSize: (index: number) => number;
|
317 | }
|
318 |
|
319 | export interface FixedSizeGridProps<T = any> extends GridProps<T> {
|
320 | /**
|
321 | * Width of an individual column within the grid.
|
322 | */
|
323 | columnWidth: number;
|
324 | /**
|
325 | * Height of an individual row within the grid.
|
326 | */
|
327 | rowHeight: number;
|
328 | }
|
329 |
|
330 | export interface VariableSizeGridProps<T = any> extends GridProps<T> {
|
331 | /**
|
332 | * Returns the width of the specified column.
|
333 | */
|
334 | columnWidth: (index: number) => number;
|
335 | /**
|
336 | * Average (or estimated) column width for unrendered columns.
|
337 | *
|
338 | * This value is used to calculated the estimated total width of a Grid before its columns have all been measured.
|
339 | * The estimated width impacts user scrolling behavior. It is updated whenever new columns are measured.
|
340 | */
|
341 | estimatedColumnWidth?: number | undefined;
|
342 | /**
|
343 | * Average (or estimated) row height for unrendered rows.
|
344 | *
|
345 | * This value is used to calculated the estimated total height of a Grid before its rows have all been measured.
|
346 | * The estimated height impacts user scrolling behavior. It is updated whenever new rows are measured.
|
347 | */
|
348 | estimatedRowHeight?: number | undefined;
|
349 | /**
|
350 | * Returns the height of the specified row.
|
351 | */
|
352 | rowHeight: (index: number) => number;
|
353 | }
|
354 |
|
355 | export class FixedSizeList<T = any> extends Component<FixedSizeListProps<T>> {
|
356 | /**
|
357 | * Scroll to the specified offset (scrollTop or scrollLeft, depending on the direction prop).
|
358 | */
|
359 | scrollTo(scrollOffset: number): void;
|
360 | /**
|
361 | * Scroll to the specified item.
|
362 | *
|
363 | * By default, the List will scroll as little as possible to ensure the item is visible.
|
364 | * You can control the alignment of the item though by specifying a second alignment parameter. Acceptable values are:
|
365 | *
|
366 | * - 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.)
|
367 | * - smart
|
368 | * - If the item is already visible, don't scroll at all.
|
369 | * - If it is less than one viewport away, scroll as little as possible so that it becomes visible.
|
370 | * - If it is more than one viewport away, scroll so that it is centered within the list.
|
371 | * - center - Center align the item within the list.
|
372 | * - end - Align the item to the end of the list (the bottom for vertical lists or the right for horizontal lists).
|
373 | * - start - Align the item to the beginning of the list (the top for vertical lists or the left for horizontal lists).
|
374 | */
|
375 | scrollToItem(index: number, align?: Align): void;
|
376 | }
|
377 |
|
378 | export class VariableSizeList<T = any> extends Component<VariableSizeListProps<T>> {
|
379 | /**
|
380 | * Scroll to the specified offset (scrollTop or scrollLeft, depending on the direction prop).
|
381 | */
|
382 | scrollTo(scrollOffset: number): void;
|
383 | /**
|
384 | * Scroll to the specified item.
|
385 | *
|
386 | * By default, the List will scroll as little as possible to ensure the item is visible.
|
387 | * You can control the alignment of the item though by specifying a second alignment parameter. Acceptable values are:
|
388 | *
|
389 | * - 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.)
|
390 | * - smart
|
391 | * - If the item is already visible, don't scroll at all.
|
392 | * - If it is less than one viewport away, scroll as little as possible so that it becomes visible.
|
393 | * - If it is more than one viewport away, scroll so that it is centered within the list.
|
394 | * - center - Center align the item within the list.
|
395 | * - end - Align the item to the end of the list (the bottom for vertical lists or the right for horizontal lists).
|
396 | * - start - Align the item to the beginning of the list (the top for vertical lists or the left for horizontal lists).
|
397 | */
|
398 | scrollToItem(index: number, align?: Align): void;
|
399 | /**
|
400 | * VariableSizeList caches offsets and measurements for each index for performance purposes.
|
401 | * This method clears that cached data for all items after (and including) the specified index.
|
402 | * It should be called whenever a item's size changes. (Note that this is not a typical occurrence.)
|
403 | *
|
404 | * By default the list will automatically re-render after the index is reset.
|
405 | * If you would like to delay this re-render until e.g. a state update has completed in the parent component,
|
406 | * specify a value of false for the second, optional parameter.
|
407 | */
|
408 | resetAfterIndex(index: number, shouldForceUpdate?: boolean): void;
|
409 | }
|
410 |
|
411 | export class FixedSizeGrid<T = any> extends Component<FixedSizeGridProps<T>> {
|
412 | /**
|
413 | * Scroll to the specified offsets.
|
414 | */
|
415 | scrollTo(params: { scrollLeft?: number; scrollTop?: number }): void;
|
416 | /**
|
417 | * Scroll to the specified item.
|
418 | *
|
419 | * By default, the Grid will scroll as little as possible to ensure the item is visible.
|
420 | * You can control the alignment of the item though by specifying an `align` property. Acceptable values are:
|
421 | *
|
422 | * - 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.)
|
423 | * - smart
|
424 | * - If the item is already visible, don't scroll at all.
|
425 | * - If it is less than one viewport away, scroll as little as possible so that it becomes visible.
|
426 | * - If it is more than one viewport away, scroll so that it is centered within the grid.
|
427 | * - center - Center align the item within the grid.
|
428 | * - end - Align the item to the bottom, right hand side of the grid.
|
429 | * - start - Align the item to the top, left hand of the grid.
|
430 | *
|
431 | * If either `columnIndex` or `rowIndex` are omitted, `scrollLeft` or `scrollTop` will be unchanged (respectively).
|
432 | */
|
433 | scrollToItem(params: {
|
434 | align?: Align | undefined;
|
435 | columnIndex?: number | undefined;
|
436 | rowIndex?: number | undefined;
|
437 | }): void;
|
438 | }
|
439 |
|
440 | export class VariableSizeGrid<T = any> extends Component<VariableSizeGridProps<T>> {
|
441 | /**
|
442 | * Scroll to the specified offsets.
|
443 | */
|
444 | scrollTo(params: { scrollLeft?: number; scrollTop?: number }): void;
|
445 | /**
|
446 | * Scroll to the specified item.
|
447 | *
|
448 | * By default, the Grid will scroll as little as possible to ensure the item is visible.
|
449 | * You can control the alignment of the item though by specifying an `align` property. Acceptable values are:
|
450 | *
|
451 | * - 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.)
|
452 | * - smart
|
453 | * - If the item is already visible, don't scroll at all.
|
454 | * - If it is less than one viewport away, scroll as little as possible so that it becomes visible.
|
455 | * - If it is more than one viewport away, scroll so that it is centered within the grid.
|
456 | * - center - Center align the item within the grid.
|
457 | * - end - Align the item to the bottom, right hand side of the grid.
|
458 | * - start - Align the item to the top, left hand of the grid.
|
459 | *
|
460 | * If either `columnIndex` or `rowIndex` are omitted, `scrollLeft` or `scrollTop` will be unchanged (respectively).
|
461 | */
|
462 | scrollToItem(params: {
|
463 | align?: Align | undefined;
|
464 | columnIndex?: number | undefined;
|
465 | rowIndex?: number | undefined;
|
466 | }): void;
|
467 | /**
|
468 | * VariableSizeGrid caches offsets and measurements for each column index for performance purposes.
|
469 | * This method clears that cached data for all columns after (and including) the specified index.
|
470 | * It should be called whenever a column's width changes. (Note that this is not a typical occurrence.)
|
471 | *
|
472 | * By default the grid will automatically re-render after the index is reset.
|
473 | * If you would like to delay this re-render until e.g. a state update has completed in the parent component,
|
474 | * specify a value of false for the second, optional parameter.
|
475 | */
|
476 | resetAfterColumnIndex(index: number, shouldForceUpdate?: boolean): void;
|
477 | /**
|
478 | * VariableSizeGrid caches offsets and measurements for each item for performance purposes.
|
479 | * This method clears that cached data for all items after (and including) the specified indices.
|
480 | * It should be called whenever an items size changes. (Note that this is not a typical occurrence.)
|
481 | *
|
482 | * By default the grid will automatically re-render after the index is reset.
|
483 | * If you would like to delay this re-render until e.g. a state update has completed in the parent component,
|
484 | * specify a value of false for the optional shouldForceUpdate parameter.
|
485 | */
|
486 | resetAfterIndices(params: {
|
487 | columnIndex: number;
|
488 | rowIndex: number;
|
489 | shouldForceUpdate?: boolean | undefined;
|
490 | }): void;
|
491 | /**
|
492 | * VariableSizeGrid caches offsets and measurements for each row index for performance purposes.
|
493 | * This method clears that cached data for all rows after (and including) the specified index.
|
494 | * It should be called whenever a row's height changes. (Note that this is not a typical occurrence.)
|
495 | *
|
496 | * By default the grid will automatically re-render after the index is reset.
|
497 | * If you would like to delay this re-render until e.g. a state update has completed in the parent component,
|
498 | * specify a value of false for the second, optional parameter.
|
499 | */
|
500 | resetAfterRowIndex(index: number, shouldForceUpdate?: boolean): void;
|
501 | }
|
502 |
|
503 | /**
|
504 | * Custom comparison function for React.memo().
|
505 | * It knows to compare individual style props and ignore the wrapper object.
|
506 | *
|
507 | * @see https://reactjs.org/docs/react-api.html#reactmemo
|
508 | */
|
509 | export function areEqual(
|
510 | prevProps: Readonly<object>,
|
511 | nextProps: Readonly<object>,
|
512 | ): boolean;
|
513 |
|
514 | /**
|
515 | * Custom shouldComponentUpdate for class components.
|
516 | * It knows to compare individual style props and ignore the wrapper object.
|
517 | *
|
518 | * @see https://reactjs.org/docs/react-component.html#shouldcomponentupdate
|
519 | */
|
520 | export function shouldComponentUpdate<P = {}, S = {}>(
|
521 | this: { props: P; state: S },
|
522 | nextProps: Readonly<P>,
|
523 | nextState: Readonly<S>,
|
524 | ): boolean;
|