svelte-bricks 0.3.1 → 0.4.0

package/dist/Masonry.svelte

@@ -1,54 +1,221 @@
-<script lang="ts">import { flip } from 'svelte/animate';
+<script lang="ts" generics="Item">import { flip } from 'svelte/animate';
 import { fade } from 'svelte/transition';
-let { animate = true, calcCols = (masonryWidth, minColWidth, gap) => {
+// On non-primitive types, we need a property to tell masonry items apart. The name of this attribute can be customized with idKey which defaults to 'id'. See https://svelte.dev/docs/svelte/each#Keyed-each-blocks.
+let { animate = true, balance = true, calcCols = (masonryWidth, minColWidth, gap) => {
     return Math.min(items.length, Math.floor((masonryWidth + gap) / (minColWidth + gap)) || 1);
-}, columnClass = ``, duration = 200, gap = 20, getId = (item) => {
+}, duration = 200, gap = 20, getId = (item) => {
     if (typeof item === `number`)
         return item;
     if (typeof item === `string`)
         return item;
     return item[idKey];
-}, idKey = `id`, items, masonryHeight = $bindable(0), masonryWidth = $bindable(0), maxColWidth = 500, minColWidth = 330, style = ``, class: className = ``, children, div = $bindable(undefined), // TODO add unit test for this prop
- } = $props();
+}, idKey = `id`, items, masonryHeight = $bindable(0), masonryWidth = $bindable(0), maxColWidth = 500, minColWidth = 330, columnStyle = ``, columnClass = ``, children, div = $bindable(), 
+// Virtualization props
+virtualize = false, getEstimatedHeight = undefined, overscan = 5, height = undefined, ...rest } = $props();
+// Height tracking for column balancing and virtualization
+let item_heights = $state(new Map());
+let measured_count = $state(0); // trigger reactivity on height updates
+let measured_sum = $state(0); // running sum for average calculation
+let avg_measured_height = $derived(measured_count > 0 ? measured_sum / measured_count : null);
+// Clean up stale heights when items change (prevents memory leak)
+$effect(() => {
+    const current_ids = new Set(items.map(getId));
+    let removed_sum = 0;
+    for (const [id, height] of item_heights.entries()) {
+        if (!current_ids.has(id)) {
+            removed_sum += height;
+            item_heights.delete(id);
+        }
+    }
+    if (removed_sum > 0) {
+        measured_sum -= removed_sum;
+        measured_count = item_heights.size;
+    }
+});
+// Unified height getter with fallback chain
+const get_height = (item) => {
+    const id = getId(item);
+    // 1. Actual measured height (most accurate)
+    const measured = item_heights.get(id);
+    if (measured !== undefined)
+        return measured;
+    // 2. User-provided estimate (if custom function provided)
+    if (getEstimatedHeight)
+        return getEstimatedHeight(item);
+    // 3. Average of measured items
+    if (avg_measured_height)
+        return avg_measured_height;
+    // 4. Hard fallback
+    return 150;
+};
+// Measure item heights via ResizeObserver
+const measure_height = (node, item_id) => {
+    if (!balance && !virtualize)
+        return {};
+    const observer = new ResizeObserver(() => {
+        const new_height = node.offsetHeight;
+        if (new_height > 0 && item_heights.get(item_id) !== new_height) {
+            const old_height = item_heights.get(item_id) ?? 0;
+            measured_sum += new_height - old_height;
+            item_heights.set(item_id, new_height);
+            measured_count = item_heights.size;
+        }
+    });
+    observer.observe(node);
+    return { destroy: () => observer.disconnect() };
+};
+// Derive if we have enough measurements
+let can_balance = $derived(balance && measured_count >= items.length);
+// Distribute items to shortest column (uses get_height for estimates when not fully measured)
+function balance_to_cols(num_cols) {
+    const cols = Array.from({ length: num_cols }, () => []);
+    const heights = Array(num_cols).fill(0);
+    for (const [idx, item] of items.entries()) {
+        const shortest = heights.indexOf(Math.min(...heights));
+        cols[shortest].push([item, idx]);
+        heights[shortest] += get_height(item) + gap;
+    }
+    return cols;
+}
 $effect.pre(() => {
     if (maxColWidth < minColWidth) {
         console.warn(`svelte-bricks: maxColWidth (${maxColWidth}) < minColWidth (${minColWidth}).`);
     }
 });
-let nCols = $derived(calcCols(masonryWidth, minColWidth, gap));
-let itemsToCols = $derived(items.reduce((cols, item, idx) => {
-    cols[idx % cols.length].push([item, idx]);
-    return cols;
-}, Array(nCols).fill(null).map(() => [])));
+// CSS container queries hide excess columns for CLS-free SSR
+// When masonryWidth is 0 (SSR), calculate max cols for 1920px viewport
+let nCols = $derived(calcCols(masonryWidth || 1920, minColWidth, gap));
+// Container query rules: breakpoint(n) = (minColWidth + gap) * n - gap
+let container_query_css = $derived(Array.from({ length: nCols - 1 }, (_, idx) => {
+    const col = idx + 1;
+    const max_w = (minColWidth + gap) * (col + 1) - gap - 1;
+    const min_w = col === 1
+        ? ``
+        : `(min-width: ${(minColWidth + gap) * col - gap}px) and `;
+    return `@container ${min_w}(max-width: ${max_w}px) { .masonry > .col:nth-child(n+${col + 1}) { display: none; } }`;
+}).join(`\n`));
+// Balanced distribution when measured, naive round-robin for SSR
+let itemsToCols = $derived.by(() => {
+    if (can_balance)
+        return balance_to_cols(nCols);
+    // SSR/initial: round-robin distribution
+    return items.reduce((cols, item, idx) => (cols[idx % nCols].push([item, idx]), cols), Array.from({ length: nCols }, () => []));
+});
+// Virtualization logic
+// Warn if virtualize=true but no height provided (only once)
+let warned_missing_height = false;
+$effect.pre(() => {
+    if (virtualize && height === undefined && !warned_missing_height) {
+        warned_missing_height = true;
+        console.warn(`svelte-bricks: virtualize=true requires a height prop. Falling back to 400px.`);
+    }
+});
+// Binary search: find first index where arr[i] >= target
+function binary_search_ge(arr, target) {
+    let lo = 0;
+    let hi = arr.length;
+    while (lo < hi) {
+        const mid = (lo + hi) >>> 1;
+        if (arr[mid] < target)
+            lo = mid + 1;
+        else
+            hi = mid;
+    }
+    return lo;
+}
+// Prefix height arrays per column: prefix_heights[col][i] = cumulative height of items 0..i
+let prefix_heights = $derived(itemsToCols.map((col) => {
+    let sum = 0;
+    return col.map(([item]) => {
+        sum += get_height(item) + gap;
+        return sum;
+    });
+}));
+// Total height per column (for padding calculation)
+let col_total_heights = $derived(prefix_heights.map((ph) => ph.at(-1) ?? 0));
+// Scroll state with requestAnimationFrame throttling
+let scroll_top = $state(0);
+let ticking = false;
+function on_scroll(event) {
+    if (ticking)
+        return;
+    ticking = true;
+    requestAnimationFrame(() => {
+        scroll_top = event.target.scrollTop;
+        ticking = false;
+    });
+}
+// Container height for virtualization viewport
+// For numeric height, use directly; for string (CSS units like "80vh"), use measured clientHeight
+let container_height = $derived(typeof height === `number` ? height : masonryHeight || 400);
+// Only enable virtualization once we have a valid container height measurement
+// This prevents flicker when using CSS units like "80vh" that need DOM measurement
+let can_virtualize = $derived(virtualize && (typeof height === `number` || masonryHeight > 0));
+// Visible ranges per column: [start_idx, end_idx]
+let visible_ranges = $derived(can_virtualize
+    ? prefix_heights.map((ph) => {
+        const start = Math.max(0, binary_search_ge(ph, scroll_top) - 1 - overscan);
+        const end = Math.min(ph.length, binary_search_ge(ph, scroll_top + container_height) + overscan);
+        return [start, end];
+    })
+    : itemsToCols.map((col) => [0, col.length]));
+// Padding to replace culled items (only when actively virtualizing)
+const zero_padding = () => itemsToCols.map(() => 0);
+let col_padding_top = $derived(can_virtualize
+    ? visible_ranges.map(([start], idx) => (start > 0 ? prefix_heights[idx][start - 1] : 0))
+    : zero_padding());
+let col_padding_bottom = $derived(can_virtualize
+    ? visible_ranges.map(([, end], idx) => {
+        const visible_end = end > 0 ? (prefix_heights[idx][end - 1] ?? 0) : 0;
+        return Math.max(0, col_total_heights[idx] - visible_end);
+    })
+    : zero_padding());
+// Auto-disable animations when actively virtualizing (FLIP doesn't work well)
+let effective_animate = $derived(animate && !can_virtualize);
 </script>
 
+<!-- Dynamic container query styles for CLS-free SSR -->
+<svelte:element this={`style`}>{container_query_css}</svelte:element>
+
 <!-- deno-fmt-ignore -->
 <div
-  class="masonry {className}"
   bind:clientWidth={masonryWidth}
   bind:clientHeight={masonryHeight}
   bind:this={div}
-  style="gap: {gap}px; {style}"
+  onscroll={virtualize ? on_scroll : undefined}
+  style:gap="{gap}px"
+  style:overflow-y={virtualize ? `auto` : undefined}
+  style:height={virtualize ? (typeof height === `number` ? `${height}px` : height ?? `400px`) : undefined}
+  {...rest}
+  class="masonry {rest.class ?? ``}"
 >
-  {#each itemsToCols as col, idx}
-    <div class="col col-{idx} {columnClass}" style="gap: {gap}px; max-width: {maxColWidth}px;">
-      {#if animate}
-        {#each col as [item, idx] (getId(item))}
+  {#each itemsToCols as col, col_idx}
+    {@const [start, end] = visible_ranges[col_idx]}
+    {@const visible_items = col.slice(start, end)}
+    <div
+      class="col col-{col_idx} {columnClass}"
+      style="gap: {gap}px; max-width: {maxColWidth}px;{can_virtualize ? ` padding-top: ${col_padding_top[col_idx]}px; padding-bottom: ${col_padding_bottom[col_idx]}px;` : ``} {columnStyle}"
+    >
+      {#if effective_animate}
+        {#each visible_items as [item, item_idx] (getId(item))}
           <div
+            use:measure_height={getId(item)}
             in:fade={{ delay: 100, duration }}
             out:fade={{ delay: 0, duration }}
             animate:flip={{ duration }}
           >
-            {#if children}{@render children({ idx, item })}{:else}
+            {#if children}{@render children({ idx: item_idx, item })}{:else}
               <span>{item}</span>
             {/if}
           </div>
         {/each}
       {:else}
-        {#each col as [item, idx] (getId(item))}
-          {#if children}{@render children({ idx, item })}{:else}
-            <span>{item}</span>
-          {/if}
+        {#each visible_items as [item, item_idx] (getId(item))}
+          <div use:measure_height={getId(item)}>
+            {#if children}{@render children({ idx: item_idx, item })}{:else}
+              <span>{item}</span>
+            {/if}
+          </div>
         {/each}
       {/if}
     </div>
@@ -57,6 +224,7 @@ let itemsToCols = $derived(items.reduce((cols, item, idx) => {
 
 <style>
   :where(div.masonry) {
+    container-type: inline-size;
     display: flex;
     justify-content: center;
     overflow-wrap: anywhere;

package/dist/Masonry.svelte.d.ts

@@ -1,9 +1,10 @@
 import type { Snippet } from 'svelte';
-declare class __sveltets_Render<Item> {
-    props(): {
+import type { HTMLAttributes } from 'svelte/elements';
+declare function $$render<Item>(): {
+    props: Omit<HTMLAttributes<HTMLDivElement>, "children"> & {
         animate?: boolean;
+        balance?: boolean;
         calcCols?: (masonryWidth: number, minColWidth: number, gap: number) => number;
-        columnClass?: string;
         duration?: number;
         gap?: number;
         getId?: (item: Item) => string | number;
@@ -15,15 +16,28 @@ declare class __sveltets_Render<Item> {
         minColWidth?: number;
         style?: string;
         class?: string;
+        columnStyle?: string;
+        columnClass?: string;
         children?: Snippet<[{
             idx: number;
             item: Item;
         }]>;
         div?: HTMLDivElement;
+        virtualize?: boolean;
+        getEstimatedHeight?: (item: Item) => number;
+        overscan?: number;
+        height?: number | string;
     };
-    events(): {};
-    slots(): {};
-    bindings(): "div" | "masonryHeight" | "masonryWidth";
+    exports: {};
+    bindings: "masonryHeight" | "masonryWidth" | "div";
+    slots: {};
+    events: {};
+};
+declare class __sveltets_Render<Item> {
+    props(): ReturnType<typeof $$render<Item>>['props'];
+    events(): ReturnType<typeof $$render<Item>>['events'];
+    slots(): ReturnType<typeof $$render<Item>>['slots'];
+    bindings(): "masonryHeight" | "masonryWidth" | "div";
     exports(): {};
 }
 interface $$IsomorphicComponent {

package/package.json

@@ -1,40 +1,31 @@
 {
   "name": "svelte-bricks",
-  "description": "Simple masonry implementation without column balancing",
+  "description": "Svelte masonry component with SSR support and column balancing",
   "author": "Janosh Riebesell <janosh.riebesell@gmail.com>",
   "homepage": "https://janosh.github.io/svelte-bricks",
   "repository": "https://github.com/janosh/svelte-bricks",
   "license": "MIT",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "type": "module",
   "svelte": "./dist/index.js",
   "bugs": "https://github.com/janosh/svelte-bricks/issues",
-  "scripts": {
-    "dev": "vite dev",
-    "build": "vite build",
-    "preview": "vite preview",
-    "package": "svelte-package",
-    "serve": "vite build && vite preview",
-    "check": "svelte-check --ignore dist",
-    "test": "vitest test",
-    "changelog": "npx auto-changelog --package --output changelog.md --hide-credit --commit-limit false"
-  },
   "dependencies": {
-    "svelte": "^5.22.6"
+    "svelte": "^5.46.1"
   },
   "devDependencies": {
-    "@sveltejs/adapter-static": "^3.0.8",
-    "@sveltejs/kit": "^2.19.0",
-    "@sveltejs/package": "^2.3.10",
-    "jsdom": "^26.0.0",
-    "mdsvex": "^0.12.3",
-    "svelte-check": "^4.1.5",
+    "@sveltejs/adapter-static": "^3.0.10",
+    "@sveltejs/kit": "^2.49.3",
+    "@sveltejs/package": "^2.5.7",
+    "@vitest/coverage-v8": "^4.0.16",
+    "jsdom": "^27.4.0",
+    "mdsvex": "^0.12.6",
+    "svelte-check": "^4.3.5",
+    "svelte-multiselect": "^11.5.1",
     "svelte-preprocess": "^6.0.3",
-    "svelte-toc": "^0.5.9",
-    "svelte-zoo": "^0.4.16",
-    "svelte2tsx": "^0.7.35",
-    "vite": "^6.2.1",
-    "vitest": "^3.0.8"
+    "svelte-toc": "^0.6.2",
+    "svelte2tsx": "^0.7.46",
+    "vite": "^7.3.1",
+    "vitest": "^4.0.16"
   },
   "keywords": [
     "svelte",
@@ -57,6 +48,11 @@
       "default": "./dist/index.js"
     }
   },
+  "prettier": {
+    "semi": false,
+    "singleQuote": true,
+    "printWidth": 90
+  },
   "types": "./dist/index.d.ts",
   "files": [
     "dist"

package/readme.md

@@ -10,19 +10,18 @@
 [![Tests](https://github.com/janosh/svelte-bricks/actions/workflows/test.yml/badge.svg)](https://github.com/janosh/svelte-bricks/actions/workflows/test.yml)
 [![NPM version](https://img.shields.io/npm/v/svelte-bricks?color=blue&logo=NPM)](https://npmjs.com/package/svelte-bricks)
 [![GitHub Pages](https://github.com/janosh/svelte-bricks/actions/workflows/gh-pages.yml/badge.svg)](https://github.com/janosh/svelte-bricks/actions/workflows/gh-pages.yml)
-[![pre-commit.ci status](https://results.pre-commit.ci/badge/github/janosh/svelte-bricks/main.svg)](https://results.pre-commit.ci/latest/github/janosh/svelte-bricks/main)
 [![Open in StackBlitz](https://img.shields.io/badge/Open%20in-StackBlitz-darkblue?logo=stackblitz)](https://stackblitz.com/github/janosh/svelte-bricks)
 
 </h4>
 
-Naive implementation in Svelte without column balancing. **[Live demo](https://janosh.github.io/svelte-bricks)**
+Svelte masonry component with SSR support (via CSS container queries) and automatic column balancing. **[Live demo](https://janosh.github.io/svelte-bricks)**
 
 </div>
 
 ## Installation
 
 ```sh
-npm install --dev svelte-bricks
+pnpm add -D svelte-bricks
 ```
 
 ## Usage
@@ -47,7 +46,8 @@ Masonry size: <span>{width}px</span> &times; <span>{height}px</span> (w &times;
   {minColWidth}
   {maxColWidth}
   {gap}
-
+  style="padding: 20px;"
+  columnStyle="background-color: rgba(0, 0, 0, 0.1);"
   bind:masonryWidth={width}
   bind:masonryHeight={height}
 >
@@ -57,9 +57,7 @@ Masonry size: <span>{width}px</span> &times; <span>{height}px</span> (w &times;
 </Masonry>
 ```
 
-**Note**: If `items` is an array of objects, this component tries to access an `id` property on each item. This value is used to tell items apart in the keyed `{#each}` block that creates the masonry layout. Without it, Svelte could not avoid duplicates when new items are added or existing ones rearranged. Read the [Svelte docs](https://svelte.dev/tutorial/keyed-each-blocks) for details. To change the name of the identifier key, pass `idKey="some-uniq-key`. Or pass a function `getId = (item: Item) => string | number` that maps items to unique IDs.
-
-**Hint**: Balanced columns can be achieved even with this simple implementation if masonry items are allowed to stretch to the column height.
+**Note**: If `items` is an array of objects, this component tries to access an `id` property on each item. This value is used to tell items apart in the keyed `{#each}` block that creates the masonry layout. Without it, Svelte could not avoid duplicates when new items are added or existing ones rearranged. Read the [Svelte docs](https://svelte.dev/docs/svelte/each#Keyed-each-blocks) for details. To change the name of the identifier key, pass `idKey="some-uniq-key`. Or pass a function `getId = (item: Item) => string | number` that maps items to unique IDs.
 
 ## Props
 
@@ -71,7 +69,13 @@ Additional optional props are:
    animate: boolean = true
    ```
 
-   Whether to [FLIP-animate](https://svelte.dev/tutorial/animate) masonry items when viewport resizing or other events cause `items` to rearrange.
+   Whether to [FLIP-animate](https://svelte.dev/docs/svelte/svelte-animate) masonry items when viewport resizing or other events cause `items` to rearrange.
+
+1. ```ts
+   balance: boolean = true
+   ```
+
+   Enable height-based column balancing. Items are distributed to the shortest column for a more even layout. Set to `false` for simple round-robin distribution.
 
 1. ```ts
    calcCols = (
@@ -132,7 +136,7 @@ Additional optional props are:
    items: Item[]
    ```
 
-   The only required prop are the list of items to render where `Item = $$Generic` is a generic type which usually will be `object` but can also be simple types `string` or `number`.
+   The only required prop is the list of items to render where `Item` is a generic type (via `generics="Item"`) which usually will be `object` but can also be simple types `string` or `number`.
 
 1. ```ts
    masonryHeight: number = 0
@@ -164,6 +168,56 @@ Additional optional props are:
 
    Inline styles that will be applied to the top-level `div.masonry`.
 
+## Virtual Scrolling
+
+For large lists (1000+ items), enable virtual scrolling to render only visible items:
+
+```svelte
+<Masonry
+  {items}
+  virtualize={true}
+  height={600}
+  getEstimatedHeight={(item) => item.height ?? 150}
+  overscan={5}
+>
+  {#snippet children({ item })}
+    <Card {item} />
+  {/snippet}
+</Masonry>
+```
+
+### Virtualization Props
+
+1. ```ts
+   virtualize: boolean = false
+   ```
+
+   Enable virtual scrolling. When `true`, only visible items are rendered. Requires the `height` prop.
+
+1. ```ts
+   height: number | string
+   ```
+
+   Required when `virtualize=true`. Sets the scroll container height (e.g., `500` for pixels or `"80vh"`).
+
+1. ```ts
+   getEstimatedHeight?: (item: Item) => number
+   ```
+
+   Optional function that returns an estimated height for items before they're measured. Defaults to 150px if not provided. Better estimates = less layout shift.
+
+1. ```ts
+   overscan: number = 5
+   ```
+
+   Number of items to render above and below the visible area. Higher values reduce flicker during fast scrolling but render more items.
+
+**Notes:**
+
+- FLIP animations are automatically disabled when virtualizing
+- Balance mode works with estimated heights until items are measured
+- The masonry div becomes a scroll container (`overflow-y: auto`)
+
 ## Styling
 
 Besides inline CSS which you can apply through the `style` prop, the following `:global()` CSS selectors can be used for fine-grained control of wrapper and column styles: