mirror of https://github.com/usememos/memos
feat: implement masonry layout with responsive columns and memo height tracking
Steven
3 weeks ago
parent
3245613a88
commit
435cc7b177
@ -0,0 +1,43 @@
|
||||
import { MasonryItem } from "./MasonryItem";
|
||||
import { MasonryColumnProps } from "./types";
|
||||
|
||||
/**
|
||||
* Column component for masonry layout
|
||||
*
|
||||
* Responsibilities:
|
||||
* - Render a single column in the masonry grid
|
||||
* - Display prefix element in the first column (e.g., memo editor)
|
||||
* - Render all assigned memo items in order
|
||||
* - Pass render context to items (includes compact mode flag)
|
||||
*/
|
||||
export function MasonryColumn({
|
||||
memoIndices,
|
||||
memoList,
|
||||
renderer,
|
||||
renderContext,
|
||||
onHeightChange,
|
||||
isFirstColumn,
|
||||
prefixElement,
|
||||
prefixElementRef,
|
||||
}: MasonryColumnProps) {
|
||||
return (
|
||||
<div className="min-w-0 mx-auto w-full max-w-2xl">
|
||||
{/* Prefix element (like memo editor) goes in first column */}
|
||||
{isFirstColumn && prefixElement && <div ref={prefixElementRef}>{prefixElement}</div>}
|
||||
|
||||
{/* Render all memos assigned to this column */}
|
||||
{memoIndices?.map((memoIndex) => {
|
||||
const memo = memoList[memoIndex];
|
||||
return memo ? (
|
||||
<MasonryItem
|
||||
key={`${memo.name}-${memo.displayTime}`}
|
||||
memo={memo}
|
||||
renderer={renderer}
|
||||
renderContext={renderContext}
|
||||
onHeightChange={onHeightChange}
|
||||
/>
|
||||
) : null;
|
||||
})}
|
||||
</div>
|
||||
);
|
||||
}
|
||||
@ -0,0 +1,45 @@
|
||||
import { useEffect, useRef } from "react";
|
||||
import { MasonryItemProps } from "./types";
|
||||
|
||||
/**
|
||||
* Individual item wrapper component for masonry layout
|
||||
*
|
||||
* Responsibilities:
|
||||
* - Render the memo using the provided renderer with context
|
||||
* - Measure its own height using ResizeObserver
|
||||
* - Report height changes to parent for redistribution
|
||||
*
|
||||
* The ResizeObserver automatically tracks dynamic content changes such as:
|
||||
* - Images loading
|
||||
* - Expanded/collapsed text
|
||||
* - Any other content size changes
|
||||
*/
|
||||
export function MasonryItem({ memo, renderer, renderContext, onHeightChange }: MasonryItemProps) {
|
||||
const itemRef = useRef<HTMLDivElement>(null);
|
||||
const resizeObserverRef = useRef<ResizeObserver | null>(null);
|
||||
|
||||
useEffect(() => {
|
||||
if (!itemRef.current) return;
|
||||
|
||||
const measureHeight = () => {
|
||||
if (itemRef.current) {
|
||||
const height = itemRef.current.offsetHeight;
|
||||
onHeightChange(memo.name, height);
|
||||
}
|
||||
};
|
||||
|
||||
// Initial measurement
|
||||
measureHeight();
|
||||
|
||||
// Set up ResizeObserver to track dynamic content changes
|
||||
resizeObserverRef.current = new ResizeObserver(measureHeight);
|
||||
resizeObserverRef.current.observe(itemRef.current);
|
||||
|
||||
// Cleanup on unmount
|
||||
return () => {
|
||||
resizeObserverRef.current?.disconnect();
|
||||
};
|
||||
}, [memo.name, onHeightChange]);
|
||||
|
||||
return <div ref={itemRef}>{renderer(memo, renderContext)}</div>;
|
||||
}
|
||||
@ -0,0 +1,11 @@
|
||||
/**
|
||||
* Minimum width required to show more than one column in masonry layout
|
||||
* When viewport is narrower, layout falls back to single column
|
||||
*/
|
||||
export const MINIMUM_MEMO_VIEWPORT_WIDTH = 512;
|
||||
|
||||
/**
|
||||
* Debounce delay for redistribution in milliseconds
|
||||
* Balances responsiveness with performance by batching rapid height changes
|
||||
*/
|
||||
export const REDISTRIBUTION_DEBOUNCE_MS = 100;
|
||||
@ -0,0 +1,94 @@
|
||||
import { Memo } from "@/types/proto/api/v1/memo_service";
|
||||
import { DistributionResult } from "./types";
|
||||
|
||||
/**
|
||||
* Distributes memos into columns using a height-aware greedy approach.
|
||||
*
|
||||
* Algorithm steps:
|
||||
* 1. Pin editor and first memo to the first column (keep feed stable)
|
||||
* 2. Place remaining memos into the currently shortest column
|
||||
* 3. Break height ties by preferring the column with fewer items
|
||||
*
|
||||
* @param memos - Array of memos to distribute
|
||||
* @param columns - Number of columns to distribute across
|
||||
* @param itemHeights - Map of memo names to their measured heights
|
||||
* @param prefixElementHeight - Height of prefix element (e.g., editor) in first column
|
||||
* @returns Distribution result with memo indices per column and column heights
|
||||
*/
|
||||
export function distributeItemsToColumns(
|
||||
memos: Memo[],
|
||||
columns: number,
|
||||
itemHeights: Map<string, number>,
|
||||
prefixElementHeight: number = 0,
|
||||
): DistributionResult {
|
||||
// Single column mode: all memos in one column
|
||||
if (columns === 1) {
|
||||
const totalHeight = memos.reduce((sum, memo) => sum + (itemHeights.get(memo.name) || 0), prefixElementHeight);
|
||||
return {
|
||||
distribution: [Array.from({ length: memos.length }, (_, i) => i)],
|
||||
columnHeights: [totalHeight],
|
||||
};
|
||||
}
|
||||
|
||||
// Initialize columns and their heights
|
||||
const distribution: number[][] = Array.from({ length: columns }, () => []);
|
||||
const columnHeights: number[] = Array(columns).fill(0);
|
||||
const columnCounts: number[] = Array(columns).fill(0);
|
||||
|
||||
// Add prefix element height to first column
|
||||
if (prefixElementHeight > 0) {
|
||||
columnHeights[0] = prefixElementHeight;
|
||||
}
|
||||
|
||||
let startIndex = 0;
|
||||
|
||||
// Pin the first memo to the first column to keep top-of-feed stable
|
||||
if (memos.length > 0) {
|
||||
const firstMemoHeight = itemHeights.get(memos[0].name) || 0;
|
||||
distribution[0].push(0);
|
||||
columnHeights[0] += firstMemoHeight;
|
||||
columnCounts[0] += 1;
|
||||
startIndex = 1;
|
||||
}
|
||||
|
||||
for (let i = startIndex; i < memos.length; i++) {
|
||||
const memo = memos[i];
|
||||
const height = itemHeights.get(memo.name) || 0;
|
||||
|
||||
// Find column with minimum height
|
||||
const shortestColumnIndex = findShortestColumnIndex(columnHeights, columnCounts);
|
||||
|
||||
distribution[shortestColumnIndex].push(i);
|
||||
columnHeights[shortestColumnIndex] += height;
|
||||
columnCounts[shortestColumnIndex] += 1;
|
||||
}
|
||||
|
||||
return { distribution, columnHeights };
|
||||
}
|
||||
|
||||
/**
|
||||
* Finds the index of the column with the minimum height
|
||||
* @param columnHeights - Array of column heights
|
||||
* @param columnCounts - Array of items per column (for tie-breaking)
|
||||
* @returns Index of the shortest column
|
||||
*/
|
||||
function findShortestColumnIndex(columnHeights: number[], columnCounts: number[]): number {
|
||||
let minIndex = 0;
|
||||
let minHeight = columnHeights[0];
|
||||
|
||||
for (let i = 1; i < columnHeights.length; i++) {
|
||||
const currentHeight = columnHeights[i];
|
||||
if (currentHeight < minHeight) {
|
||||
minHeight = currentHeight;
|
||||
minIndex = i;
|
||||
continue;
|
||||
}
|
||||
|
||||
// Tie-breaker: prefer column with fewer items to avoid stacking
|
||||
if (currentHeight === minHeight && columnCounts[i] < columnCounts[minIndex]) {
|
||||
minIndex = i;
|
||||
}
|
||||
}
|
||||
|
||||
return minIndex;
|
||||
}
|
||||
@ -1,3 +1,25 @@
|
||||
import MasonryView from "./MasonryView";
|
||||
// Main component
|
||||
export { default } from "./MasonryView";
|
||||
|
||||
export default MasonryView;
|
||||
// Sub-components (exported for testing or advanced usage)
|
||||
export { MasonryColumn } from "./MasonryColumn";
|
||||
export { MasonryItem } from "./MasonryItem";
|
||||
|
||||
// Hooks
|
||||
export { useMasonryLayout } from "./useMasonryLayout";
|
||||
|
||||
// Utilities
|
||||
export { distributeItemsToColumns } from "./distributeItems";
|
||||
|
||||
// Types
|
||||
export type {
|
||||
MasonryViewProps,
|
||||
MasonryItemProps,
|
||||
MasonryColumnProps,
|
||||
DistributionResult,
|
||||
MemoWithHeight,
|
||||
MemoRenderContext,
|
||||
} from "./types";
|
||||
|
||||
// Constants
|
||||
export { MINIMUM_MEMO_VIEWPORT_WIDTH, REDISTRIBUTION_DEBOUNCE_MS } from "./constants";
|
||||
|
||||
@ -0,0 +1,81 @@
|
||||
import { Memo } from "@/types/proto/api/v1/memo_service";
|
||||
|
||||
/**
|
||||
* Render context passed to memo renderer
|
||||
*/
|
||||
export interface MemoRenderContext {
|
||||
/** Whether to render in compact mode (automatically enabled for multi-column layouts) */
|
||||
compact: boolean;
|
||||
/** Current number of columns in the layout */
|
||||
columns: number;
|
||||
}
|
||||
|
||||
/**
|
||||
* Props for the main MasonryView component
|
||||
*/
|
||||
export interface MasonryViewProps {
|
||||
/** List of memos to display in masonry layout */
|
||||
memoList: Memo[];
|
||||
/** Render function for each memo. Second parameter provides layout context. */
|
||||
renderer: (memo: Memo, context?: MemoRenderContext) => JSX.Element;
|
||||
/** Optional element to display at the top of the first column (e.g., memo editor) */
|
||||
prefixElement?: JSX.Element;
|
||||
/** Force single column layout regardless of viewport width */
|
||||
listMode?: boolean;
|
||||
}
|
||||
|
||||
/**
|
||||
* Props for individual MasonryItem component
|
||||
*/
|
||||
export interface MasonryItemProps {
|
||||
/** The memo to render */
|
||||
memo: Memo;
|
||||
/** Render function for the memo */
|
||||
renderer: (memo: Memo, context?: MemoRenderContext) => JSX.Element;
|
||||
/** Render context for the memo */
|
||||
renderContext: MemoRenderContext;
|
||||
/** Callback when item height changes */
|
||||
onHeightChange: (memoName: string, height: number) => void;
|
||||
}
|
||||
|
||||
/**
|
||||
* Props for MasonryColumn component
|
||||
*/
|
||||
export interface MasonryColumnProps {
|
||||
/** Indices of memos in this column */
|
||||
memoIndices: number[];
|
||||
/** Full list of memos */
|
||||
memoList: Memo[];
|
||||
/** Render function for each memo */
|
||||
renderer: (memo: Memo, context?: MemoRenderContext) => JSX.Element;
|
||||
/** Render context for memos */
|
||||
renderContext: MemoRenderContext;
|
||||
/** Callback when item height changes */
|
||||
onHeightChange: (memoName: string, height: number) => void;
|
||||
/** Whether this is the first column (for prefix element) */
|
||||
isFirstColumn: boolean;
|
||||
/** Optional prefix element (only rendered in first column) */
|
||||
prefixElement?: JSX.Element;
|
||||
/** Ref for prefix element height measurement */
|
||||
prefixElementRef?: React.RefObject<HTMLDivElement>;
|
||||
}
|
||||
|
||||
/**
|
||||
* Result of the distribution algorithm
|
||||
*/
|
||||
export interface DistributionResult {
|
||||
/** Array of arrays, where each inner array contains memo indices for that column */
|
||||
distribution: number[][];
|
||||
/** Height of each column after distribution */
|
||||
columnHeights: number[];
|
||||
}
|
||||
|
||||
/**
|
||||
* Memo item with measured height
|
||||
*/
|
||||
export interface MemoWithHeight {
|
||||
/** Index of the memo in the original list */
|
||||
index: number;
|
||||
/** Measured height in pixels */
|
||||
height: number;
|
||||
}
|
||||
@ -0,0 +1,150 @@
|
||||
import { useCallback, useEffect, useRef, useState } from "react";
|
||||
import { Memo } from "@/types/proto/api/v1/memo_service";
|
||||
import { MINIMUM_MEMO_VIEWPORT_WIDTH, REDISTRIBUTION_DEBOUNCE_MS } from "./constants";
|
||||
import { distributeItemsToColumns } from "./distributeItems";
|
||||
|
||||
/**
|
||||
* Custom hook for managing masonry layout state and logic
|
||||
*
|
||||
* Responsibilities:
|
||||
* - Calculate optimal number of columns based on viewport width
|
||||
* - Track item heights and trigger redistribution
|
||||
* - Debounce redistribution to prevent excessive reflows
|
||||
* - Handle window resize events
|
||||
*
|
||||
* @param memoList - Array of memos to layout
|
||||
* @param listMode - Force single column mode
|
||||
* @param containerRef - Reference to the container element
|
||||
* @param prefixElementRef - Reference to the prefix element
|
||||
* @returns Layout state and handlers
|
||||
*/
|
||||
export function useMasonryLayout(
|
||||
memoList: Memo[],
|
||||
listMode: boolean,
|
||||
containerRef: React.RefObject<HTMLDivElement>,
|
||||
prefixElementRef: React.RefObject<HTMLDivElement>,
|
||||
) {
|
||||
const [columns, setColumns] = useState(1);
|
||||
const [itemHeights, setItemHeights] = useState<Map<string, number>>(new Map());
|
||||
const [distribution, setDistribution] = useState<number[][]>([[]]);
|
||||
|
||||
const redistributionTimeoutRef = useRef<number | null>(null);
|
||||
const itemHeightsRef = useRef<Map<string, number>>(itemHeights);
|
||||
|
||||
// Keep ref in sync with state
|
||||
useEffect(() => {
|
||||
itemHeightsRef.current = itemHeights;
|
||||
}, [itemHeights]);
|
||||
|
||||
/**
|
||||
* Calculate optimal number of columns based on container width
|
||||
* Uses a scale factor to determine column count
|
||||
*/
|
||||
const calculateColumns = useCallback(() => {
|
||||
if (!containerRef.current || listMode) return 1;
|
||||
|
||||
const containerWidth = containerRef.current.offsetWidth;
|
||||
const scale = containerWidth / MINIMUM_MEMO_VIEWPORT_WIDTH;
|
||||
return scale >= 2 ? Math.round(scale) : 1;
|
||||
}, [containerRef, listMode]);
|
||||
|
||||
/**
|
||||
* Recalculate memo distribution when layout changes
|
||||
*/
|
||||
const redistributeMemos = useCallback(() => {
|
||||
const prefixHeight = prefixElementRef.current?.offsetHeight || 0;
|
||||
setDistribution(() => {
|
||||
const { distribution: newDistribution } = distributeItemsToColumns(memoList, columns, itemHeightsRef.current, prefixHeight);
|
||||
return newDistribution;
|
||||
});
|
||||
}, [memoList, columns, prefixElementRef]);
|
||||
|
||||
/**
|
||||
* Debounced redistribution to batch multiple height changes and prevent excessive reflows
|
||||
*/
|
||||
const debouncedRedistribute = useCallback(
|
||||
(newItemHeights: Map<string, number>) => {
|
||||
// Clear any pending redistribution
|
||||
if (redistributionTimeoutRef.current) {
|
||||
clearTimeout(redistributionTimeoutRef.current);
|
||||
}
|
||||
|
||||
// Schedule new redistribution after debounce delay
|
||||
redistributionTimeoutRef.current = window.setTimeout(() => {
|
||||
const prefixHeight = prefixElementRef.current?.offsetHeight || 0;
|
||||
setDistribution(() => {
|
||||
const { distribution: newDistribution } = distributeItemsToColumns(memoList, columns, newItemHeights, prefixHeight);
|
||||
return newDistribution;
|
||||
});
|
||||
}, REDISTRIBUTION_DEBOUNCE_MS);
|
||||
},
|
||||
[memoList, columns, prefixElementRef],
|
||||
);
|
||||
|
||||
/**
|
||||
* Handle height changes from individual memo items
|
||||
*/
|
||||
const handleHeightChange = useCallback(
|
||||
(memoName: string, height: number) => {
|
||||
setItemHeights((prevHeights) => {
|
||||
const newItemHeights = new Map(prevHeights);
|
||||
const previousHeight = prevHeights.get(memoName);
|
||||
|
||||
// Skip if height hasn't changed (avoid unnecessary updates)
|
||||
if (previousHeight === height) {
|
||||
return prevHeights;
|
||||
}
|
||||
|
||||
newItemHeights.set(memoName, height);
|
||||
|
||||
// Use debounced redistribution to batch updates
|
||||
debouncedRedistribute(newItemHeights);
|
||||
|
||||
return newItemHeights;
|
||||
});
|
||||
},
|
||||
[debouncedRedistribute],
|
||||
);
|
||||
|
||||
/**
|
||||
* Handle window resize and calculate new column count
|
||||
*/
|
||||
useEffect(() => {
|
||||
const handleResize = () => {
|
||||
if (!containerRef.current) return;
|
||||
|
||||
const newColumns = calculateColumns();
|
||||
if (newColumns !== columns) {
|
||||
setColumns(newColumns);
|
||||
}
|
||||
};
|
||||
|
||||
handleResize();
|
||||
window.addEventListener("resize", handleResize);
|
||||
return () => window.removeEventListener("resize", handleResize);
|
||||
}, [calculateColumns, columns, containerRef]);
|
||||
|
||||
/**
|
||||
* Redistribute memos when columns or memo list change
|
||||
*/
|
||||
useEffect(() => {
|
||||
redistributeMemos();
|
||||
}, [columns, memoList, redistributeMemos]);
|
||||
|
||||
/**
|
||||
* Cleanup timeout on unmount
|
||||
*/
|
||||
useEffect(() => {
|
||||
return () => {
|
||||
if (redistributionTimeoutRef.current) {
|
||||
clearTimeout(redistributionTimeoutRef.current);
|
||||
}
|
||||
};
|
||||
}, []);
|
||||
|
||||
return {
|
||||
columns,
|
||||
distribution,
|
||||
handleHeightChange,
|
||||
};
|
||||
}
|
||||
Loading…
Reference in New Issue