@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/dist/lib/index.mjs +482 -0
- package/dist/lib/index.mjs.map +1 -0
- package/dist/types/src/Masonry.d.ts +43 -6
- package/dist/types/src/Masonry.d.ts.map +1 -1
- package/dist/types/src/Masonry.stories.d.ts +9 -1
- package/dist/types/src/Masonry.stories.d.ts.map +1 -1
- package/dist/types/src/layout.d.ts +50 -0
- package/dist/types/src/layout.d.ts.map +1 -0
- package/dist/types/src/layout.test.d.ts +2 -0
- package/dist/types/src/layout.test.d.ts.map +1 -0
- package/dist/types/src/useFlip.d.ts +37 -0
- package/dist/types/src/useFlip.d.ts.map +1 -0
- package/dist/types/src/useFlip.test.d.ts +2 -0
- package/dist/types/src/useFlip.test.d.ts.map +1 -0
- package/dist/types/src/useMasonryLayout.d.ts +42 -0
- package/dist/types/src/useMasonryLayout.d.ts.map +1 -0
- package/dist/types/tsconfig.tsbuildinfo +1 -1
- package/package.json +21 -22
- package/src/Masonry.stories.tsx +149 -37
- package/src/Masonry.tsx +238 -98
- package/src/layout.test.ts +108 -0
- package/src/layout.ts +105 -0
- package/src/useFlip.test.ts +34 -0
- package/src/useFlip.ts +137 -0
- package/src/useMasonryLayout.ts +241 -0
- package/dist/lib/browser/index.mjs +0 -138
- package/dist/lib/browser/index.mjs.map +0 -7
- package/dist/lib/browser/meta.json +0 -1
- package/dist/lib/node-esm/index.mjs +0 -140
- package/dist/lib/node-esm/index.mjs.map +0 -7
- package/dist/lib/node-esm/meta.json +0 -1
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
|
|
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
|
|
40
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
87
|
-
//
|
|
88
|
-
//
|
|
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
|
|
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
|
-
|
|
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={
|
|
130
|
+
ref={forwardedRef}
|
|
109
131
|
>
|
|
110
|
-
|
|
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
|
-
//
|
|
129
|
-
//
|
|
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,
|
|
142
|
-
|
|
143
|
-
const
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
)
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
//
|
|
159
|
-
//
|
|
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
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
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
|
-
//
|
|
181
|
-
//
|
|
182
|
-
//
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
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
|
-
|
|
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
|
|
374
|
+
const gapPx = gap * remInPx;
|
|
236
375
|
if (width <= 0 || minColumnWidthPx <= 0) {
|
|
237
376
|
return 1;
|
|
238
377
|
}
|
|
239
378
|
|
|
240
|
-
//
|
|
241
|
-
//
|
|
242
|
-
|
|
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
|
|
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 +
|
|
248
|
-
if (width
|
|
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,
|
|
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
|
+
});
|