u

src/FillSpace.jsx

@@ -1,5 +1,7 @@
 import { Component } from 'react';
 import Box from '@mui/material/Box';
+import Pagination from '@mui/material/Pagination';
+import Typography from '@mui/material/Typography';
 import { alpha } from '@mui/material/styles';
 
 /**
@@ -18,6 +20,11 @@ import { alpha } from '@mui/material/styles';
  * @prop {number} [measureGap=0] - Vertical gap (px) between repeated `measureElement` units.
  * @prop {(count: number) => void} [onMeasurement] - Called whenever the number of `measureElement` units that would fit in the whole spacer height changes, as if there were no `children` (i.e. the total row count the space could hold). Fires once after mount with the initial count.
  * @prop {number} [minHeight=0] - Minimum spacer height in px.
+ * @prop {number} [minCount=0] - Minimum number of `measureElement` units the spacer must fit. When the viewport is too small, the spacer grows beyond the viewport so the page scrolls instead of clipping.
+ * @prop {Array} [items] - When provided, FillSpace paginates: it measures the page size, slices `items`, renders the current page via `renderPage`, and owns wheel-pagination plus the pagination header. Omit for legacy children mode.
+ * @prop {(pageItems: Array, page: {offset:number, pageSize:number, currentPage:number, pageCount:number, total:number}) => ReactNode} [renderPage] - Renders the current page slice (paginated mode).
+ * @prop {number} [minPageSize=10] - Minimum rows per page in paginated mode.
+ * @prop {(page: number) => void} [onPageChange] - Called when the current page changes (wheel or header).
  * @prop {number} [maxHeight] - Optional maximum spacer height in px.
  * @prop {boolean} [debug=false] - When true, draws a dashed outline around the spacer and a translucent overlay over the whole viewport so the measured bounds are visible.
  * @prop {ReactNode} [children] - Real content rendered at the top of the spacer. The repeated `measureElement` units (if any) fill the remaining space below it.
@@ -30,29 +37,46 @@ import { alpha } from '@mui/material/styles';
  * @behaviour Re-measures on window resize and whenever the observed refs or the content change size (ResizeObserver), throttled with requestAnimationFrame.
  * @behaviour `debug` draws a dashed primary outline around the spacer plus a translucent full-viewport overlay.
  */
+
+/** Minimum spacer height so at least `count` units fit (lets the page scroll on small windows). */
+function minHeightFromCount(count, unitHeight, gap) {
+  const n = Number(count) || 0;
+  if (n <= 0 || !(unitHeight > 0)) return 0;
+  return n * unitHeight + Math.max(0, n - 1) * (Number(gap) || 0);
+}
+
 class FillSpace extends Component {
   constructor(props) {
     super(props);
     this.state = {
-      height: 0,
+      // null = not measured yet: render at natural content height so the
+      // first visible frame is already full-size, no 0 → expanded jump.
+      height: null,
       unitHeight: 0,
       contentHeight: 0,
       totalCount: 0,
       fillCount: 0,
+      // Paginated mode (`items`): page size comes from the fit count.
+      pageSize: Number(props.minPageSize ?? props.minCount) || 10,
+      currentPage: 1,
+      measured: false,
     };
     this.lastTotalCount = null;
     this.ref = null;
     this.contentRef = null;
     this.unitRef = null;
+    this.paginationRef = null;
+    this.wheelAcc = 0;
     this.observer = null;
     this.raf = null;
   }
 
   componentDidMount() {
-    requestAnimationFrame(() => {
-      this._measure();
-      this._observe();
-    });
+    // Measure synchronously (no rAF): setState here is batched before the
+    // browser paints, so the first visible frame already has the full
+    // viewport height — no small-box → expanded-box layout shift.
+    this._measure();
+    this._observe();
     window.addEventListener('resize', this._onViewportChange);
   }
 
@@ -61,7 +85,10 @@ class FillSpace extends Component {
       prevProps.aboveRef !== this.props.aboveRef ||
       prevProps.belowRef !== this.props.belowRef ||
       prevProps.containerRef !== this.props.containerRef ||
+      prevProps.reserveBottom !== this.props.reserveBottom ||
       prevProps.minHeight !== this.props.minHeight ||
+      prevProps.minCount !== this.props.minCount ||
+      prevProps.minPageSize !== this.props.minPageSize ||
       prevProps.maxHeight !== this.props.maxHeight ||
       prevProps.measureElement !== this.props.measureElement ||
       prevProps.measureGap !== this.props.measureGap
@@ -69,6 +96,20 @@ class FillSpace extends Component {
       this._observe();
       this._measure();
     }
+    // Clamp current page when the item list shrinks (e.g. brand deleted).
+    if (
+      Array.isArray(this.props.items) &&
+      this.props.items !== prevProps.items
+    ) {
+      const pageCount = Math.max(
+        1,
+        Math.ceil(this.props.items.length / Math.max(1, this.state.pageSize)),
+      );
+      if (this.state.currentPage > pageCount) {
+        this.setState({ currentPage: pageCount });
+        this.props.onPageChange?.(pageCount);
+      }
+    }
   }
 
   componentWillUnmount() {
@@ -109,6 +150,7 @@ class FillSpace extends Component {
       ...belowList.map((r) => (r && 'current' in r ? r.current : r)),
       containerTarget,
       this.contentRef,
+      this.paginationRef,
     ];
     for (const el of targets) {
       if (el && el.offsetParent !== null) {
@@ -131,8 +173,11 @@ class FillSpace extends Component {
       measureElement,
       measureGap = 0,
       minHeight = 0,
+      minCount = 0,
+      minPageSize,
       maxHeight,
       onMeasurement,
+      items,
     } = this.props;
 
     // Distance from the document top to the spacer top — includes every
@@ -186,6 +231,18 @@ class FillSpace extends Component {
       if (h > 0) unitHeight = h;
     }
 
+    // Minimum rows: grow past the viewport so the page scrolls instead
+    // of clipping when the window is too small. Paginated mode uses
+    // minPageSize (fallback minCount).
+    const paginated = Array.isArray(items);
+    const minSize = Math.max(1, Number(minPageSize ?? minCount) || 10);
+    const effectiveMinCount = paginated ? Math.max(Number(minCount) || 0, minSize) : Number(minCount) || 0;
+    const minHeightForCount = minHeightFromCount(effectiveMinCount, unitHeight, measureGap);
+    const finalHeight = Math.min(
+      Math.max(clamped, minHeightForCount),
+      maxHeight ?? Infinity,
+    );
+
     // How many units would fit in the WHOLE spacer height, as if there were
     // no children — this is what onMeasurement reports.
     let totalCount = 0;
@@ -194,8 +251,8 @@ class FillSpace extends Component {
     // the space, none fit.
     let fillCount = 0;
     if (measureElement != null && unitHeight > 0) {
-      totalCount = Math.floor((clamped + measureGap) / (unitHeight + measureGap));
-      const fillHeight = Math.max(0, clamped - contentHeight);
+      totalCount = Math.floor((finalHeight + measureGap) / (unitHeight + measureGap));
+      const fillHeight = Math.max(0, finalHeight - contentHeight);
       fillCount = Math.floor((fillHeight + measureGap) / (unitHeight + measureGap));
     }
 
@@ -211,42 +268,121 @@ class FillSpace extends Component {
       onMeasurement(totalCount);
     }
 
+    // Paginated mode: fit count drives the page size (min minPageSize).
+    let nextPageSize = this.state.pageSize;
+    let measured = this.state.measured;
+    if (paginated && totalCount > 0) {
+      nextPageSize = Math.max(minSize, totalCount);
+      measured = true;
+    }
+
     if (
-      Math.abs(clamped - this.state.height) > 0.5 ||
+      Math.abs(finalHeight - this.state.height) > 0.5 ||
       Math.abs(unitHeight - this.state.unitHeight) > 0.5 ||
       Math.abs(contentHeight - this.state.contentHeight) > 0.5 ||
       totalCount !== this.state.totalCount ||
-      fillCount !== this.state.fillCount
+      fillCount !== this.state.fillCount ||
+      nextPageSize !== this.state.pageSize ||
+      measured !== this.state.measured
     ) {
-      this.setState({ height: clamped, unitHeight, contentHeight, totalCount, fillCount });
+      this.setState({
+        height: finalHeight,
+        unitHeight,
+        contentHeight,
+        totalCount,
+        fillCount,
+        pageSize: nextPageSize,
+        measured,
+      });
     }
   }
 
+  _handleWheel = (event) => {
+    const { items, onWheel } = this.props;
+    if (!Array.isArray(items)) {
+      onWheel?.(event);
+      return;
+    }
+    const { pageSize, currentPage } = this.state;
+    const pageCount = Math.max(1, Math.ceil(items.length / Math.max(1, pageSize)));
+    if (pageCount <= 1) return;
+    const delta = event.deltaY || 0;
+    if (delta === 0) return;
+    if (Math.sign(delta) !== Math.sign(this.wheelAcc || 0)) this.wheelAcc = 0;
+    this.wheelAcc = (this.wheelAcc || 0) + delta;
+    // Few pages → long scroll per page (slow); many pages → fast flipping.
+    const threshold = Math.max(50, 800 / pageCount);
+    if (Math.abs(this.wheelAcc) < threshold) return;
+    const dir = this.wheelAcc > 0 ? 1 : -1;
+    this.wheelAcc = 0;
+    const next = dir > 0
+      ? Math.min(pageCount, currentPage + 1)
+      : Math.max(1, currentPage - 1);
+    if (next === currentPage) return;
+    event.preventDefault();
+    this._goToPage(next);
+  };
+
+  _goToPage = (page) => {
+    const { items, onPageChange } = this.props;
+    const total = Array.isArray(items) ? items.length : 0;
+    const pageCount = Math.max(1, Math.ceil(total / Math.max(1, this.state.pageSize)));
+    const next = Math.min(Math.max(1, Number(page) || 1), pageCount);
+    if (next === this.state.currentPage) return;
+    this.setState({ currentPage: next });
+    onPageChange?.(next);
+  };
+
   render() {
     const {
       aboveRef,
       belowRef,
+      containerRef,
+      reserveBottom,
       onMeasurement,
+      onWheel,
+      onPageChange,
       minHeight = 0,
+      minCount,
+      minPageSize,
       maxHeight,
       debug = false,
       children,
+      items,
+      renderPage,
       measureElement,
       measureGap = 0,
       sx,
       ...rest
     } = this.props;
 
+    // Paginated mode: FillSpace owns page size (from fit), current page,
+    // wheel-pagination and the pagination header. Caller just feeds `items`
+    // and renders the slice via `renderPage`.
+    if (Array.isArray(items) && typeof renderPage === 'function') {
+      return this.renderPaginated({
+        minHeight,
+        maxHeight,
+        debug,
+        measureElement,
+        measureGap,
+        sx,
+        rest,
+      });
+    }
+
     const { height, fillCount } = this.state;
+    // Before the first measurement, let content size naturally (auto)
+    // instead of forcing height 0 — avoids the small-box flash.
 
     // Repeated measurement units fill only the leftover space below the real
     // children. fillCount (computed in _measure) starts at 0: if the content
     // already fills the space, no units are rendered.
     let fill = null;
     if (measureElement != null) {
-      const items = [];
+      const fillItems = [];
       for (let i = 0; i < fillCount; i++) {
-        items.push(
+        fillItems.push(
           <Box key={i} sx={{ width: '100%' }}>
             {measureElement}
           </Box>,
@@ -262,7 +398,7 @@ class FillSpace extends Component {
             overflow: 'hidden',
           }}
         >
-          {items}
+          {fillItems}
         </Box>
       );
     }
@@ -273,11 +409,12 @@ class FillSpace extends Component {
           ref={(el) => {
             this.ref = el;
           }}
+          onWheel={onWheel}
           {...rest}
           sx={[
             {
               position: 'relative',
-              height,
+              height: height ?? 'auto',
               minHeight,
               ...(maxHeight != null ? { maxHeight } : {}),
             },
@@ -333,6 +470,133 @@ class FillSpace extends Component {
       </>
     );
   }
+
+  /**
+   * Paginated mode: pagination header (hidden until measured) + exactly one
+   * page of `items` rendered via `renderPage`. Wheel over the list flips
+   * pages; effort scales with page count (slow for few pages).
+   */
+  renderPaginated({ minHeight, maxHeight, debug, measureElement, measureGap, sx, rest }) {
+    const { items, renderPage, onWheel } = this.props;
+    const { height, pageSize, currentPage, measured } = this.state;
+    const total = items.length;
+    const pageCount = Math.max(1, Math.ceil(total / Math.max(1, pageSize)));
+    const safePage = Math.min(Math.max(1, currentPage), pageCount);
+    const offset = (safePage - 1) * pageSize;
+    const pageItems = items.slice(offset, offset + pageSize);
+    // Hidden until the fit is measured — no "1–10" flash on load.
+    const showPagination = measured && total > pageSize;
+
+    return (
+      <>
+        <Box
+          ref={(el) => {
+            this.paginationRef = el;
+          }}
+          sx={{ mb: 1 }}
+        >
+          <Box
+            aria-hidden={!showPagination || undefined}
+            sx={{
+              display: 'flex',
+              justifyContent: 'space-between',
+              alignItems: 'center',
+              flexWrap: 'wrap',
+              gap: 1,
+              width: '100%',
+              visibility: showPagination ? 'visible' : 'hidden',
+              pointerEvents: showPagination ? 'auto' : 'none',
+            }}
+          >
+            <Typography variant="body2" color="text.secondary">
+              {showPagination ? offset + 1 : 1}–
+              {showPagination ? Math.min(offset + pageSize, total) : pageSize + 1} von{' '}
+              {showPagination ? total : pageSize + 1}
+            </Typography>
+            <Pagination
+              count={showPagination ? pageCount : 1}
+              page={showPagination ? safePage : 1}
+              onChange={(_e, page) => this._goToPage(page)}
+              color="primary"
+              size="large"
+              onMouseDown={(e) => e.preventDefault()}
+              sx={{
+                '& .MuiPaginationItem-root': {
+                  minWidth: 44,
+                  height: 44,
+                  fontSize: '1rem',
+                },
+              }}
+            />
+          </Box>
+        </Box>
+        <Box
+          ref={(el) => {
+            this.ref = el;
+          }}
+          onWheel={(e) => {
+            this._handleWheel(e);
+            onWheel?.(e);
+          }}
+          {...rest}
+          sx={[
+            {
+              position: 'relative',
+              height: height ?? 'auto',
+              minHeight,
+              ...(maxHeight != null ? { maxHeight } : {}),
+              overflow: 'hidden',
+              width: '100%',
+            },
+            debug
+              ? (theme) => ({
+                  outline: `2px dashed ${theme.palette.primary.main}`,
+                })
+              : undefined,
+            sx,
+          ]}
+        >
+          <Box
+            ref={(el) => {
+              this.contentRef = el;
+            }}
+            sx={{ width: '100%' }}
+          >
+            {renderPage(pageItems, { offset, pageSize, currentPage: safePage, pageCount, total })}
+          </Box>
+          {measureElement != null ? (
+            <Box
+              ref={(el) => {
+                this.unitRef = el;
+              }}
+              aria-hidden
+              sx={{
+                position: 'absolute',
+                left: 0,
+                top: 0,
+                width: '100%',
+                visibility: 'hidden',
+                pointerEvents: 'none',
+              }}
+            >
+              {measureElement}
+            </Box>
+          ) : null}
+        </Box>
+        {debug ? (
+          <Box
+            sx={(theme) => ({
+              position: 'fixed',
+              inset: 0,
+              pointerEvents: 'none',
+              background: alpha(theme.palette.primary.main, 0.08),
+              zIndex: 9999,
+            })}
+          />
+        ) : null}
+      </>
+    );
+  }
 }
 
 export default FillSpace;