@dxos/react-ui-masonry 0.10.0 → 0.11.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.
package/src/Masonry.tsx CHANGED
@@ -3,31 +3,41 @@
3
3
  //
4
4
 
5
5
  import { useArrowNavigationGroup } from '@fluentui/react-tabster';
6
- import { useComposedRefs } from '@radix-ui/react-compose-refs';
7
6
  import { createContext } from '@radix-ui/react-context';
8
- import { VirtuosoMasonry as NaturalVirtuosoMasonry, type VirtuosoMasonryProps } from '@virtuoso.dev/masonry';
9
7
  import React, {
10
8
  type ComponentType,
11
9
  type CSSProperties,
12
10
  type JSX,
11
+ type MouseEvent,
13
12
  type PropsWithChildren,
14
13
  type Ref,
14
+ useEffect,
15
15
  useMemo,
16
16
  useRef,
17
+ useState,
17
18
  } from 'react';
18
19
  import { useResizeDetector } from 'react-resize-detector';
19
20
 
20
21
  import { ScrollArea, ScrollAreaRootProps, ThemedClassName, usePx } from '@dxos/react-ui';
21
- import { composable, composableProps, scrollbar } from '@dxos/react-ui';
22
+ import { composable, composableProps } from '@dxos/react-ui';
22
23
  import { cardMaxInlineSize, cardMinInlineSize } from '@dxos/ui-theme';
23
24
 
25
+ import { prefersReducedMotion, useFlip } from './useFlip';
26
+ import { useMasonryLayout } from './useMasonryLayout';
27
+
28
+ /** Reveal the grid once the layout has been stable for this long (the initial reflow has settled). */
29
+ const REVEAL_SETTLE_MS = 80;
30
+
31
+ /** Reveal the grid no later than this after mount, so churning content never hides it indefinitely. */
32
+ const REVEAL_DEADLINE_MS = 1200;
33
+
24
34
  //
25
35
  // Context
26
36
  //
27
37
 
28
38
  type MasonryContextValue = {
29
- /** Render component for each masonry item. */
30
- Tile: ComponentType<{ data: any; index: number }>;
39
+ /** Render component for each masonry item. Receives `selected` when the grid is selectable. */
40
+ Tile: ComponentType<{ data: any; index: number; selected?: boolean }>;
31
41
  /** Override auto-calculated column count. */
32
42
  columns: number | undefined;
33
43
  /** Upper bound on number of columns. */
@@ -36,21 +46,26 @@ type MasonryContextValue = {
36
46
  minColumnWidth: number;
37
47
  /** Maximum column width in rem. */
38
48
  maxColumnWidth: number;
39
- /** Space between columns and rows in rem. */
40
- gutter: number;
49
+ /** Space applied uniformly between tiles and around the grid perimeter, in rem. */
50
+ gap: number;
51
+ /**
52
+ * Animate reflow when a small number of tiles are added or removed. Disabled, or on a
53
+ * bulk change (initial render, data swap) or resize, tiles snap to position instead.
54
+ */
55
+ animate: boolean;
56
+ /**
57
+ * Centre the columns when `maxColumnWidth` caps them narrower than the container. Off aligns them
58
+ * to the start instead, which reads better when the grid sits in a form or list flow whose other
59
+ * rows are start-aligned. Distinct from `Masonry.Content`'s `centered`, which is ScrollArea's
60
+ * scrollbar-padding balance and says nothing about column alignment.
61
+ */
62
+ centered: boolean;
41
63
  };
42
64
 
43
65
  const MASONRY_NAME = 'Masonry';
44
66
 
45
67
  const [MasonryProvider, useMasonryContext] = createContext<MasonryContextValue>(MASONRY_NAME);
46
68
 
47
- /** Content-scoped context: measured width of the ScrollArea.Root, shared with Viewport. */
48
- type MasonryContentContextValue = {
49
- width: number;
50
- };
51
-
52
- const [MasonryContentProvider, useMasonryContentContext] = createContext<MasonryContentContextValue>('Masonry.Content');
53
-
54
69
  //
55
70
  // Root
56
71
  //
@@ -64,7 +79,9 @@ const MasonryRoot = ({
64
79
  maxColumns = undefined,
65
80
  minColumnWidth = cardMinInlineSize,
66
81
  maxColumnWidth = cardMaxInlineSize,
67
- gutter = 0.75,
82
+ gap = 0.75,
83
+ animate = true,
84
+ centered = true,
68
85
  }: MasonryRootProps) => (
69
86
  <MasonryProvider
70
87
  Tile={Tile!}
@@ -72,7 +89,9 @@ const MasonryRoot = ({
72
89
  maxColumns={maxColumns}
73
90
  minColumnWidth={minColumnWidth}
74
91
  maxColumnWidth={maxColumnWidth}
75
- gutter={gutter}
92
+ gap={gap}
93
+ animate={animate}
94
+ centered={centered}
76
95
  >
77
96
  {children}
78
97
  </MasonryProvider>
@@ -83,9 +102,10 @@ MasonryRoot.displayName = 'Masonry.Root';
83
102
  //
84
103
  // Content
85
104
  //
86
- // The outer wrapper: renders the ScrollArea.Root, measures available width,
87
- // and publishes that width via context for Masonry.Viewport to consume.
88
- // Style this layer (centered/thin/padding) to control the scroll container.
105
+ // The outer wrapper: renders the ScrollArea.Root. Style this layer
106
+ // (centered/thin/padding) to control the scroll container; the Viewport measures
107
+ // its own content box, so scrollbar width and padding are accounted for whatever
108
+ // density is configured here.
89
109
  //
90
110
 
91
111
  type MasonryContentProps = ThemedClassName<
@@ -93,21 +113,23 @@ type MasonryContentProps = ThemedClassName<
93
113
  >;
94
114
 
95
115
  const MasonryContentInner = composable<HTMLDivElement, MasonryContentProps>(
96
- ({ children, scrollbars, centered, thin = true, padding = true, ...props }, forwardedRef) => {
97
- const rootRef = useRef<HTMLDivElement | null>(null);
98
- const composedRef = useComposedRefs(rootRef, forwardedRef);
99
- const { width = 0 } = useResizeDetector({ targetRef: rootRef });
100
-
116
+ ({ children, scrollbars, centered = true, thin = true, padding = true, ...props }, forwardedRef) => {
117
+ const { gap } = useMasonryContext('Masonry.Content');
101
118
  return (
102
119
  <ScrollArea.Root
103
- {...composableProps(props, { classNames: 'pt-trim-md' })}
120
+ // Drive the ScrollArea gutter to the grid gap so the left/right perimeter
121
+ // matches the inter-column gap: the centered+padding theme resolves this to
122
+ // pl = gap and pr = gap - scrollbar, keeping both sides symmetric with the
123
+ // scrollbar accounted for at any density. Cast: CSSProperties has no index
124
+ // signature for CSS custom properties, so `--gutter` cannot be typed directly.
125
+ {...composableProps(props, { style: { '--gutter': `${gap}rem` } as CSSProperties })}
104
126
  scrollbars={scrollbars}
105
127
  centered={centered}
106
128
  thin={thin}
107
129
  padding={padding}
108
- ref={composedRef}
130
+ ref={forwardedRef}
109
131
  >
110
- <MasonryContentProvider width={width}>{children}</MasonryContentProvider>
132
+ {children}
111
133
  </ScrollArea.Root>
112
134
  );
113
135
  },
@@ -124,9 +146,10 @@ const MasonryContent = MasonryContentInner as (
124
146
  //
125
147
  // Viewport
126
148
  //
127
- // The inner render layer: renders the ScrollArea.Viewport wrapped around
128
- // VirtuosoMasonry. Style this layer separately from Content to control
129
- // the tile grid (e.g. inner padding, alignment).
149
+ // The inner render layer: renders the ScrollArea.Viewport wrapped around the
150
+ // absolute layout engine. Each tile is positioned with translate(x, y) into a
151
+ // balanced (shortest-column-first) grid; reflow is animated with FLIP. Style
152
+ // this layer separately from Content to control the tile grid.
130
153
  //
131
154
 
132
155
  type MasonryViewportProps<Item> = ThemedClassName<{
@@ -134,81 +157,197 @@ type MasonryViewportProps<Item> = ThemedClassName<{
134
157
  items: readonly Item[];
135
158
  /** Extract a stable key from an item, aligned with react-ui-mosaic's getId. */
136
159
  getId?: (data: Item) => string;
160
+ /**
161
+ * Scope for remembering tile heights across mounts, e.g. the collection's URI. With one, a
162
+ * remount renders on the first frame instead of waiting for the layout to settle. Omit it when
163
+ * `getId` is omitted: the default index ids are not unique across grids.
164
+ */
165
+ cacheKey?: string;
166
+ /**
167
+ * Ids of the currently-selected tiles. When `onSelect` is also provided the grid becomes
168
+ * selectable: selected tiles render an outline + `aria-selected`, and clicking a tile emits
169
+ * {@link onSelect}. Selection STATE (single/multi semantics) is owned by the consumer — pair this
170
+ * with `useListSelection` from `@dxos/react-ui-list`.
171
+ */
172
+ selectedIds?: ReadonlySet<string>;
173
+ /** Emitted when a tile is clicked while selectable. The consumer toggles its own selection state. */
174
+ onSelect?: (id: string, event: MouseEvent) => void;
175
+ /**
176
+ * Whether this layer owns scrolling. Set `false` when an ancestor already scrolls (e.g. a form's
177
+ * viewport) to render the grid in a plain full-width block instead of a nested scroll container —
178
+ * the `ScrollArea.Root` that `Masonry.Content` provides is then not needed. Nesting scroll
179
+ * containers also risks collapsing the measured width to the scrollbar gutter, which would
180
+ * suppress the grid entirely (see the width gate below).
181
+ * @default true
182
+ */
183
+ scroll?: boolean;
137
184
  }>;
138
185
 
139
186
  const MasonryViewportInner = composable<HTMLDivElement, MasonryViewportProps<any>>(
140
- ({ items, getId, ...props }, forwardedRef) => {
141
- const { Tile, columns, maxColumns, minColumnWidth, maxColumnWidth, gutter } = useMasonryContext('Masonry.Viewport');
142
- const { width } = useMasonryContentContext('Masonry.Viewport');
143
- const columnCount = useColumnCount(
144
- width - (scrollbar.md.size + scrollbar.md.padding),
145
- columns,
146
- maxColumns,
147
- minColumnWidth,
148
- maxColumnWidth,
149
- gutter,
150
- );
151
-
152
- // Arrow-key navigation across tiles. Uses Tabster's `both` axis so all
153
- // four arrows move focus through the items. True 2D (grid) axis doesn't
154
- // work inside a masonry because VirtuosoMasonry lays items out column-
155
- // first in the DOM — tabster's Grid direction requires the next DOM
156
- // element to be to the right of the current for ArrowRight, which is
157
- // never the case between columns here. `both` treats the keys as flat
158
- // next/previous-focusable, which gives predictable wrap-around in DOM
159
- // order for all four directions.
187
+ ({ items, getId, cacheKey, selectedIds, onSelect, scroll = true, ...props }, forwardedRef) => {
188
+ const { Tile, columns, maxColumns, minColumnWidth, maxColumnWidth, gap, animate, centered } =
189
+ useMasonryContext('Masonry.Viewport');
190
+ const remInPx = usePx(1);
191
+ // Measure the viewport's own content box (net of padding and scrollbar) rather
192
+ // than deriving it from the root width, so the grid tracks the actual available
193
+ // width for any ScrollArea density (thin/scrollbars/padding) without duplicating
194
+ // the theme's gutter math.
195
+ const viewportRef = useRef<HTMLDivElement | null>(null);
196
+ // Throttle width changes: each update recomputes the column count and the full tile layout,
197
+ // so coalesce rapid resizes (drag, ScrollArea reflow) into at most one relayout per interval.
198
+ const { width: contentWidth = 0 } = useResizeDetector({
199
+ targetRef: viewportRef,
200
+ refreshMode: 'throttle',
201
+ refreshRate: 200,
202
+ });
203
+ const columnCount = useColumnCount(contentWidth, columns, maxColumns, minColumnWidth, maxColumnWidth, gap);
204
+
205
+ // The grid fills the measured content box; the layout caps columns at
206
+ // `maxColumnWidth` and centres them, so no scrollbar/padding math is duplicated here.
207
+ const gapPx = gap * remInPx;
208
+ const ids = useMemo(() => items.map((item, index) => getId?.(item) ?? String(index)), [items, getId]);
209
+ const { rects, columnWidth, height, getTileRef, nodes, measured, knownIds } = useMasonryLayout({
210
+ ids,
211
+ columnCount,
212
+ containerWidth: contentWidth,
213
+ gapPx,
214
+ maxColumnWidthPx: maxColumnWidth * remInPx,
215
+ centered,
216
+ cacheKey,
217
+ });
218
+ useFlip({ nodes, ids, rects, columnCount, containerWidth: contentWidth, enabled: animate });
219
+
220
+ // Hide the grid until the layout stops changing, then fade in; latch on so later edits never
221
+ // re-hide it. Revealing on the first measurement is not enough: tiles mount collapsed (their
222
+ // poster reserves height a frame later), so the first pass stacks them bunched at the top and
223
+ // only settles over the next few reflows. Debounce on `rects` identity — which changes on every
224
+ // relayout — and reveal once it has been stable for a beat, with a hard deadline as a backstop.
225
+ //
226
+ // None of that applies when every tile's height was already known on the first pass (the height
227
+ // cache is warm from an earlier mount): the layout is final before paint, so waiting for it to
228
+ // settle would just be a delay. That is the common case after the first visit.
229
+ const [revealed, setRevealed] = useState(false);
230
+ const firstPass = useRef(true);
231
+ useEffect(() => {
232
+ if (revealed) {
233
+ return;
234
+ }
235
+ // Nothing has been laid out until the viewport reports a width, so this does not count as the
236
+ // first pass — consuming it here would forfeit the fast path on every mount.
237
+ if (contentWidth <= 0) {
238
+ return;
239
+ }
240
+ if (!measured) {
241
+ firstPass.current = false;
242
+ return;
243
+ }
244
+ if (firstPass.current) {
245
+ setRevealed(true);
246
+ return;
247
+ }
248
+ const timer = setTimeout(() => setRevealed(true), REVEAL_SETTLE_MS);
249
+ return () => clearTimeout(timer);
250
+ }, [revealed, measured, rects, contentWidth]);
251
+ useEffect(() => {
252
+ const deadline = setTimeout(() => setRevealed(true), REVEAL_DEADLINE_MS);
253
+ return () => clearTimeout(deadline);
254
+ }, []);
255
+
256
+ // Arrow-key navigation across tiles. Uses Tabster's `both` axis so all four
257
+ // arrows move focus through the items as flat next/previous-focusable, giving
258
+ // predictable wrap-around in DOM order.
160
259
  const arrowNavigationAttrs = useArrowNavigationGroup({
161
260
  axis: 'both',
162
261
  memorizeCurrent: true,
163
262
  tabbable: true,
164
263
  });
165
264
 
166
- const TileAdapter = useMemo(() => {
167
- const Adapter = ({ data, index }: { data: any; index: number }) => (
168
- <div role='listitem' style={{ paddingBottom: `${gutter}rem` }}>
169
- <Tile index={index} data={data} />
170
- </div>
171
- );
172
- Adapter.displayName = 'Masonry.TileAdapter';
173
- return Adapter;
174
- }, [Tile, gutter]);
175
-
176
- if (width <= 0) {
177
- return null;
178
- }
265
+ // The viewport is the full-width scroll container; its centered+padded theme
266
+ // (with `--gutter` set to the gap) balances the scrollbar into symmetric inline
267
+ // gutters. The grid fills the content box and the layout centres capped columns,
268
+ // so nothing overflows and left/right spacing matches the gap. The viewport always
269
+ // renders so it can be measured; tiles render once a width is known.
270
+ const grid = (
271
+ <>
272
+ {contentWidth > 0 && (
273
+ <div
274
+ {...composableProps(props, {
275
+ classNames: 'relative',
276
+ style: {
277
+ width: `${contentWidth}px`,
278
+ height: `${height}px`,
279
+ opacity: revealed ? 1 : 0,
280
+ // Hidden (not just transparent) before reveal so the settling tiles are neither
281
+ // focusable nor hit-testable; the opacity fade only runs when motion is allowed.
282
+ visibility: revealed ? 'visible' : 'hidden',
283
+ transition: animate && !prefersReducedMotion() ? 'opacity 200ms cubic-bezier(0.2, 0, 0, 1)' : undefined,
284
+ },
285
+ })}
286
+ {...arrowNavigationAttrs}
287
+ role='list'
288
+ ref={forwardedRef}
289
+ >
290
+ {items.map((item, index) => {
291
+ const id = ids[index];
292
+ const rect = rects[index];
293
+ const selectable = !!onSelect;
294
+ const selected = selectedIds?.has(id) ?? false;
295
+ // A tile with no height at all — never measured, nothing remembered — is positioned by
296
+ // a guess. Painting that guess is what flashed a tile hundreds of pixels out of place
297
+ // when the item set was swapped wholesale. A remembered height from another width is
298
+ // close enough to paint, so a resize reflows in place instead of blanking.
299
+ // `visibility` rather than `display`, so the ResizeObserver can still measure it.
300
+ const estimated = !knownIds.has(id);
301
+ return (
302
+ <div
303
+ key={id}
304
+ // Let the tile clamp its card: a card's own min-width must not exceed
305
+ // the column, or a narrow (single-column, mobile) container overflows
306
+ // and shows a horizontal scrollbar.
307
+ className={[
308
+ '[&>*]:min-w-0!',
309
+ selectable && 'cursor-pointer',
310
+ selected && 'rounded-md ring-2 ring-inset ring-primary-500',
311
+ ]
312
+ .filter(Boolean)
313
+ .join(' ')}
314
+ ref={getTileRef(id)}
315
+ role='listitem'
316
+ aria-selected={selectable ? selected : undefined}
317
+ onClick={onSelect ? (event) => onSelect(id, event) : undefined}
318
+ style={{
319
+ position: 'absolute',
320
+ insetBlockStart: 0,
321
+ insetInlineStart: 0,
322
+ width: `${columnWidth}px`,
323
+ transform: rect ? `translate(${rect.x}px, ${rect.y}px)` : undefined,
324
+ visibility: estimated ? 'hidden' : undefined,
325
+ }}
326
+ >
327
+ <Tile index={index} data={item} selected={selected} />
328
+ </div>
329
+ );
330
+ })}
331
+ </div>
332
+ )}
333
+ </>
334
+ );
179
335
 
180
- // VirtuosoMasonry renders the scroller as a full-width flex row whose column children carry an
181
- // inline `flexGrow: 1`. Capping each column at `maxColumnWidth` lets the columns grow to fill the
182
- // row but stop at the natural card width; `justify-center` then distributes the remaining space as
183
- // symmetric margins so the grid stays centered without the scroll container leaving the far edge.
184
- return (
185
- <ScrollArea.Viewport asChild>
186
- <VirtuosoMasonry
187
- {...composableProps(props, {
188
- classNames: ['justify-center', '[&>div]:max-w-[var(--dx-masonry-column-max)]'],
189
- style: { 'gap': `${gutter}rem`, '--dx-masonry-column-max': `${maxColumnWidth}rem` } as CSSProperties,
190
- })}
191
- {...arrowNavigationAttrs}
192
- ItemContent={TileAdapter}
193
- columnCount={columnCount}
194
- data={items as any[]}
195
- // ref={forwardedRef}
196
- />
197
- </ScrollArea.Viewport>
336
+ // Not `dx-expander` in the non-scrolling case: the width gate needs a definite inline size
337
+ // (`w-full min-w-0`) without claiming the block axis, which would fight the surrounding flow —
338
+ // the grid's height comes from the computed layout.
339
+ return scroll ? (
340
+ <ScrollArea.Viewport ref={viewportRef}>{grid}</ScrollArea.Viewport>
341
+ ) : (
342
+ <div className='flex-1 w-full min-w-0' ref={viewportRef}>
343
+ {grid}
344
+ </div>
198
345
  );
199
346
  },
200
347
  );
201
348
 
202
349
  MasonryViewportInner.displayName = 'Masonry.Viewport';
203
350
 
204
- /**
205
- * NOTE: Required in order for our Viewport to take over the scroll area.
206
- * https://github.com/petyosi/react-virtuoso/issues/1305
207
- */
208
- const VirtuosoMasonry = composable<HTMLDivElement, VirtuosoMasonryProps<any, any>>(({ ...props }, _forwardedRef) => {
209
- return <NaturalVirtuosoMasonry {...props} />;
210
- });
211
-
212
351
  const MasonryViewport = MasonryViewportInner as <Item>(
213
352
  props: MasonryViewportProps<Item> & {
214
353
  ref?: Ref<HTMLDivElement | null>;
@@ -222,7 +361,7 @@ const useColumnCount = (
222
361
  maxColumns: number | undefined,
223
362
  minColumnWidth: number,
224
363
  maxColumnWidth: number,
225
- gutter: number,
364
+ gap: number,
226
365
  ) => {
227
366
  const remInPx = usePx(1);
228
367
  return useMemo(() => {
@@ -232,20 +371,21 @@ const useColumnCount = (
232
371
 
233
372
  const minColumnWidthPx = minColumnWidth * remInPx;
234
373
  const maxColumnWidthPx = maxColumnWidth * remInPx;
235
- const gutterPx = gutter * remInPx;
374
+ const gapPx = gap * remInPx;
236
375
  if (width <= 0 || minColumnWidthPx <= 0) {
237
376
  return 1;
238
377
  }
239
378
 
240
- // Each tile has paddingRight: gutter, so every slot (including the last) occupies
241
- // (colWidth + gutterPx). The container therefore fits floor(containerWidth / (colWidth + gutterPx)) columns.
242
- let cols = Math.floor(width / (minColumnWidthPx + gutterPx));
379
+ // `width` is the content box; the outer perimeter is owned by the scroll
380
+ // container, so only interior gaps count: N columns fit when
381
+ // N * colWidth + (N - 1) * gap <= width, i.e. N <= (width + gap) / (colWidth + gap).
382
+ let cols = Math.max(1, Math.floor((width + gapPx) / (minColumnWidthPx + gapPx)));
243
383
  if (maxColumnWidthPx > 0) {
244
- const effectiveColWidth = width / cols - gutterPx;
384
+ const effectiveColWidth = (width - (cols - 1) * gapPx) / cols;
245
385
  if (effectiveColWidth > maxColumnWidthPx) {
246
386
  // Try to add columns to keep cards below maxColumnWidth, but never violate minColumnWidth.
247
- const maxCols = Math.ceil(width / (maxColumnWidthPx + gutterPx));
248
- if (width / maxCols - gutterPx >= minColumnWidthPx) {
387
+ const maxCols = Math.ceil((width + gapPx) / (maxColumnWidthPx + gapPx));
388
+ if ((width - (maxCols - 1) * gapPx) / maxCols >= minColumnWidthPx) {
249
389
  cols = maxCols;
250
390
  }
251
391
  }
@@ -253,7 +393,7 @@ const useColumnCount = (
253
393
 
254
394
  const clamped = maxColumns != null ? Math.min(cols, maxColumns) : cols;
255
395
  return Math.max(1, clamped);
256
- }, [remInPx, width, columns, maxColumns, minColumnWidth, maxColumnWidth, gutter]);
396
+ }, [remInPx, width, columns, maxColumns, minColumnWidth, maxColumnWidth, gap]);
257
397
  };
258
398
 
259
399
  //
@@ -0,0 +1,108 @@
1
+ //
2
+ // Copyright 2026 DXOS.org
3
+ //
4
+
5
+ import { describe, test } from 'vitest';
6
+
7
+ import { getColumnWidth, layout } from './layout';
8
+
9
+ describe('layout', () => {
10
+ test('assigns each tile to the shortest column (not by index)', ({ expect }) => {
11
+ // With index-based placement item 2 would land in column 0; balancing puts it
12
+ // in column 1 because column 0 is still occupied by the tall first tile.
13
+ const { rects } = layout({ heights: [100, 10, 10, 10], columnCount: 2, containerWidth: 200, gapPx: 0 });
14
+ expect(rects.map((rect) => rect.column)).toEqual([0, 1, 1, 1]);
15
+ });
16
+
17
+ test('breaks ties toward the lowest column index', ({ expect }) => {
18
+ const { rects } = layout({ heights: [10, 10], columnCount: 2, containerWidth: 200, gapPx: 0 });
19
+ expect(rects.map((rect) => rect.column)).toEqual([0, 1]);
20
+ });
21
+
22
+ test('fills the width using interior gaps only, with a top perimeter gap', ({ expect }) => {
23
+ const { rects, columnWidth } = layout({ heights: [10, 10], columnCount: 2, containerWidth: 100, gapPx: 10 });
24
+ expect(columnWidth).toBe(45); // (100 - 1 * 10) / 2 — columns fill, no outer gap.
25
+ expect(rects[0]).toMatchObject({ x: 0, y: 10, column: 0 }); // flush left; top perimeter gap.
26
+ expect(rects[1]).toMatchObject({ x: 55, y: 10, column: 1 }); // 0 + 1 * (45 + 10).
27
+ });
28
+
29
+ test('caps column width and centres the leftover space', ({ expect }) => {
30
+ const { rects, columnWidth } = layout({
31
+ heights: [10, 10],
32
+ columnCount: 2,
33
+ containerWidth: 200,
34
+ gapPx: 10,
35
+ maxColumnWidthPx: 50,
36
+ });
37
+ expect(columnWidth).toBe(50); // capped below the 95 fill width.
38
+ // usedWidth = 2 * 50 + 10 = 110; sideInset = (200 - 110) / 2 = 45.
39
+ expect(rects[0]).toMatchObject({ x: 45, column: 0 });
40
+ expect(rects[1]).toMatchObject({ x: 105, column: 1 }); // 45 + (50 + 10).
41
+ });
42
+
43
+ test('stacks vertically in a single column with top and bottom perimeter gaps', ({ expect }) => {
44
+ const { rects, height } = layout({ heights: [30, 20], columnCount: 1, containerWidth: 100, gapPx: 10 });
45
+ expect(rects.map((rect) => rect.y)).toEqual([10, 50]); // 10 gap, then 10 + 30 + 10.
46
+ expect(height).toBe(80); // 10 + 30 + 10 + 20 + 10.
47
+ });
48
+
49
+ test('handles an empty input', ({ expect }) => {
50
+ const { rects, height } = layout({ heights: [], columnCount: 3, containerWidth: 300, gapPx: 8 });
51
+ expect(rects).toEqual([]);
52
+ expect(height).toBe(0);
53
+ });
54
+
55
+ test('clamps a non-positive column count to one', ({ expect }) => {
56
+ const { rects } = layout({ heights: [10, 10], columnCount: 0, containerWidth: 100, gapPx: 0 });
57
+ expect(rects.map((rect) => rect.column)).toEqual([0, 0]);
58
+ });
59
+
60
+ test('start-aligns columns when centring is off', ({ expect }) => {
61
+ const options = {
62
+ heights: [100, 100],
63
+ columnCount: 2,
64
+ containerWidth: 1000,
65
+ gapPx: 10,
66
+ maxColumnWidthPx: 200,
67
+ };
68
+
69
+ // Capped columns use 410 of 1000, so centring insets both sides by 295.
70
+ const centred = layout({ ...options, centered: true });
71
+ expect(centred.rects[0].x).toBe(295);
72
+
73
+ const startAligned = layout({ ...options, centered: false });
74
+ expect(startAligned.rects[0].x).toBe(0);
75
+ expect(startAligned.rects[1].x).toBe(210);
76
+
77
+ // Only the offset changes; the columns themselves are identical.
78
+ expect(startAligned.columnWidth).toBe(centred.columnWidth);
79
+ expect(startAligned.height).toBe(centred.height);
80
+ });
81
+
82
+ test('centres by default', ({ expect }) => {
83
+ const rects = layout({
84
+ heights: [100],
85
+ columnCount: 1,
86
+ containerWidth: 1000,
87
+ gapPx: 10,
88
+ maxColumnWidthPx: 200,
89
+ }).rects;
90
+ expect(rects[0].x).toBe(400);
91
+ });
92
+ });
93
+
94
+ describe('getColumnWidth', () => {
95
+ test('matches the width the layout resolves, so cache keys and rendering cannot disagree', ({ expect }) => {
96
+ const cases = [
97
+ { columnCount: 1, containerWidth: 300, gapPx: 8 },
98
+ { columnCount: 3, containerWidth: 1000, gapPx: 12 },
99
+ { columnCount: 4, containerWidth: 1600, gapPx: 12, maxColumnWidthPx: 320 },
100
+ // Degenerate: no width yet (the frame before the viewport is measured).
101
+ { columnCount: 2, containerWidth: 0, gapPx: 8 },
102
+ ];
103
+
104
+ for (const options of cases) {
105
+ expect(getColumnWidth(options), JSON.stringify(options)).toBe(layout({ ...options, heights: [] }).columnWidth);
106
+ }
107
+ });
108
+ });