@slithy/react-tessera-gallery 0.1.0

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Matthew Campagna
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,111 @@
+# @slithy/react-tessera-gallery
+
+React photo gallery with optimal justified layout. Uses a Knuth-Plass dynamic programming algorithm to break items into rows that minimize deviation from a target row height. Supports incremental loading, unknown aspect ratios, and append-only rendering to prevent layout jumps as new images load.
+
+## Installation
+
+```bash
+npm install @slithy/react-tessera-gallery
+```
+
+**Peer dependencies:** `react@^17 || ^18 || ^19`
+
+---
+
+## `<TesseraGallery>`
+
+The main component. Accepts a list of items and a `renderItem` function; handles all layout and loading state internally.
+
+```tsx
+import { TesseraGallery } from '@slithy/react-tessera-gallery'
+
+<TesseraGallery
+  items={photos}
+  rowHeight={200}
+  gap={4}
+  renderItem={(item, { width, height, loaded }, handlers) => (
+    <img
+      key={item.key}
+      src={item.src}
+      width={width}
+      height={height}
+      onLoad={handlers.onLoad}
+      style={{ opacity: loaded ? 1 : 0 }}
+    />
+  )}
+/>
+```
+
+**Props:**
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `items` | `GalleryItem<T>[]` | — | Items to display. Each must have a `key`. `aspectRatio` is optional — see below. |
+| `renderItem` | `(item, layout, handlers) => ReactNode` | — | Render function called for each item |
+| `rowHeight` | `number` | — | Target row height in pixels |
+| `gap` | `number` | `0` | Gap between items and rows in pixels |
+| `lastRow` | `'left' \| 'center' \| 'right' \| 'justify' \| 'hide'` | `'left'` | Alignment of the last (partial) row |
+| `maxShrink` | `number` | `0.75` | Minimum row height as a fraction of `rowHeight` |
+| `maxStretch` | `number` | `1.5` | Maximum row height as a multiple of `rowHeight` |
+| `justifyThreshold` | `number` | `1` | Justify the last row if its natural fill ratio meets this threshold (0–1) |
+
+**`renderItem` arguments:**
+
+| Argument | Type | Description |
+|---|---|---|
+| `item` | `GalleryItem<T>` | The original item |
+| `layout.width` | `number` | Computed pixel width for this item |
+| `layout.height` | `number` | Computed pixel height for this item |
+| `layout.loaded` | `boolean` | Whether the browser has confirmed this image loaded via `handlers.onLoad` |
+| `handlers.onLoad` | `ReactEventHandler<HTMLImageElement>` | Pass to `<img onLoad={...}>` to track load state |
+
+---
+
+## `GalleryItem<T>`
+
+Items passed to `TesseraGallery` must satisfy `GalleryItem<T>`:
+
+```ts
+type GalleryItem<T> = T & {
+  key: string | number
+  aspectRatio?: number  // optional — discovered via onLoad if omitted
+}
+```
+
+Items with a known `aspectRatio` are laid out immediately. Items without one are held out of the layout until `handlers.onLoad` fires, at which point their aspect ratio is derived from `naturalWidth / naturalHeight` and they enter the layout with `loaded: true`.
+
+---
+
+## `useTesseraGallery`
+
+The hook underlying `<TesseraGallery>`. Use this directly for custom rendering or when you need lower-level control.
+
+```ts
+import { useTesseraGallery } from '@slithy/react-tessera-gallery'
+
+const { containerRef, rows, onLoad } = useTesseraGallery(items, options)
+```
+
+**Returns:**
+
+| Property | Type | Description |
+|---|---|---|
+| `containerRef` | `RefObject<HTMLDivElement \| null>` | Attach to your container element to observe its width |
+| `rows` | `ResolvedRow<T>[]` | Computed layout rows, each with `height` and `items` |
+| `onLoad` | `(key, naturalWidth, naturalHeight) => void` | Call when an image loads |
+
+---
+
+## `computeTesseraLayout`
+
+The pure layout function. Takes items with known aspect ratios, a container width, and options; returns row data with pixel dimensions. No React dependency.
+
+```ts
+import { computeTesseraLayout } from '@slithy/react-tessera-gallery'
+
+const rows = computeTesseraLayout(
+  [{ aspectRatio: 1.5 }, { aspectRatio: 1 }, { aspectRatio: 2 }],
+  600,
+  { rowHeight: 200, gap: 4 },
+)
+```

package/dist/index.d.ts

@@ -0,0 +1,55 @@
+import { RefObject, ReactEventHandler, ReactNode } from 'react';
+
+type LayoutOptions = {
+    rowHeight: number;
+    gap?: number;
+    lastRow?: 'justify' | 'left' | 'center' | 'right' | 'hide';
+    maxShrink?: number;
+    maxStretch?: number;
+    justifyThreshold?: number;
+};
+type LayoutRow = {
+    items: Array<{
+        aspectRatio: number;
+        width: number;
+        height: number;
+    }>;
+    height: number;
+};
+type GalleryItem<T> = T & {
+    key: string | number;
+    aspectRatio?: number;
+};
+type ResolvedRow<T> = {
+    items: Array<{
+        item: GalleryItem<T>;
+        width: number;
+        height: number;
+        loaded: boolean;
+    }>;
+    height: number;
+};
+
+declare function computeTesseraLayout(items: {
+    aspectRatio: number;
+}[], containerWidth: number, options: LayoutOptions): LayoutRow[];
+
+declare function useTesseraGallery<T>(items: GalleryItem<T>[], options: LayoutOptions): {
+    containerRef: RefObject<HTMLDivElement | null>;
+    rows: ResolvedRow<T>[];
+    onLoad: (key: string | number, naturalWidth: number, naturalHeight: number) => void;
+};
+
+type Props<T> = {
+    items: GalleryItem<T>[];
+    renderItem: (item: GalleryItem<T>, layout: {
+        width: number;
+        height: number;
+        loaded: boolean;
+    }, handlers: {
+        onLoad: ReactEventHandler<HTMLImageElement>;
+    }) => ReactNode;
+} & LayoutOptions;
+declare function TesseraGallery<T>({ items, renderItem, ...options }: Props<T>): ReactNode;
+
+export { type GalleryItem, type LayoutOptions, type LayoutRow, type ResolvedRow, TesseraGallery, computeTesseraLayout, useTesseraGallery };

package/dist/index.js

@@ -0,0 +1,251 @@
+// src/computeTesseraLayout.ts
+var BADNESS_POWER = 3;
+function computeTesseraLayout(items, containerWidth, options) {
+  const {
+    rowHeight: idealHeight,
+    gap = 0,
+    lastRow = "left",
+    maxShrink = 0.75,
+    maxStretch = 1.5,
+    justifyThreshold = 1
+  } = options;
+  const n = items.length;
+  if (n === 0 || containerWidth <= 0) return [];
+  const minHeight = idealHeight * maxShrink;
+  const maxHeight = idealHeight * maxStretch;
+  const prefixAR = new Array(n + 1);
+  prefixAR[0] = 0;
+  for (let i = 0; i < n; i++) {
+    prefixAR[i + 1] = prefixAR[i] + items[i].aspectRatio;
+  }
+  function rowHeightFor(start2, end) {
+    const totalAR = prefixAR[end] - prefixAR[start2];
+    const numGaps = end - start2 - 1;
+    return (containerWidth - gap * numGaps) / totalAR;
+  }
+  function badness(h) {
+    if (h >= idealHeight) {
+      const range2 = maxHeight - idealHeight;
+      return range2 === 0 ? Infinity : (h - idealHeight) ** BADNESS_POWER / range2 ** BADNESS_POWER;
+    }
+    const range = idealHeight - minHeight;
+    return range === 0 ? Infinity : (idealHeight - h) ** BADNESS_POWER / range ** BADNESS_POWER;
+  }
+  const dp = new Array(n + 1).fill(Infinity);
+  const pred = new Array(n + 1).fill(-1);
+  dp[0] = 0;
+  for (let i = 0; i < n; i++) {
+    if (dp[i] === Infinity) continue;
+    for (let j = i + 1; j <= n; j++) {
+      const h = rowHeightFor(i, j);
+      if (h > maxHeight) continue;
+      if (h < minHeight) break;
+      const cost = dp[i] + badness(h);
+      if (cost < dp[j]) {
+        dp[j] = cost;
+        pred[j] = i;
+      }
+    }
+  }
+  const breaks = [];
+  if (dp[n] < Infinity) {
+    let cur = n;
+    while (cur > 0) {
+      breaks.unshift(cur);
+      cur = pred[cur];
+    }
+  } else {
+    let last = n - 1;
+    while (last > 0 && dp[last] === Infinity) last--;
+    let cur = last;
+    while (cur > 0) {
+      breaks.unshift(cur);
+      cur = pred[cur];
+    }
+    if (last < n) breaks.push(n);
+  }
+  const rows = [];
+  let start = 0;
+  for (let r = 0; r < breaks.length; r++) {
+    const end = breaks[r];
+    const isLastRow = r === breaks.length - 1;
+    const numGaps = end - start - 1;
+    const totalAR = prefixAR[end] - prefixAR[start];
+    let actualHeight;
+    let justify;
+    if (isLastRow) {
+      if (lastRow === "hide") {
+        start = end;
+        continue;
+      }
+      const naturalWidth = totalAR * idealHeight + gap * numGaps;
+      const fillRatio = naturalWidth / containerWidth;
+      const shouldJustify = lastRow === "justify" || fillRatio >= justifyThreshold;
+      if (shouldJustify) {
+        actualHeight = rowHeightFor(start, end);
+        justify = true;
+      } else {
+        actualHeight = idealHeight;
+        justify = false;
+      }
+    } else {
+      actualHeight = rowHeightFor(start, end);
+      justify = true;
+    }
+    rows.push(buildRow(items, start, end, actualHeight, justify, containerWidth, gap));
+    start = end;
+  }
+  return rows;
+}
+function buildRow(items, start, end, height, justify, containerWidth, gap) {
+  const count = end - start;
+  const numGaps = count - 1;
+  if (!justify) {
+    return {
+      height,
+      items: items.slice(start, end).map((item) => ({
+        aspectRatio: item.aspectRatio,
+        width: item.aspectRatio * height,
+        height
+      }))
+    };
+  }
+  const targetTotal = containerWidth - gap * numGaps;
+  const naturalWidths = items.slice(start, end).map((item) => item.aspectRatio * height);
+  const rawTotal = naturalWidths.reduce((s, w) => s + w, 0);
+  const scale = targetTotal / rawTotal;
+  const scaled = naturalWidths.map((w) => w * scale);
+  const floored = scaled.map(Math.floor);
+  const remainder = Math.round(targetTotal - floored.reduce((s, w) => s + w, 0));
+  const order = scaled.map((w, i) => ({ i, frac: w - Math.floor(w) })).sort((a, b) => b.frac - a.frac);
+  const finalWidths = [...floored];
+  for (let k = 0; k < remainder; k++) finalWidths[order[k].i]++;
+  return {
+    height,
+    items: items.slice(start, end).map((item, idx) => ({
+      aspectRatio: item.aspectRatio,
+      width: finalWidths[idx],
+      height
+    }))
+  };
+}
+
+// src/useTesseraGallery.ts
+import { useCallback, useEffect, useReducer, useRef, useState } from "react";
+function toResolvedRow(row, loadedSet) {
+  return {
+    height: row.height,
+    items: row.items.map(({ item, width, height }) => ({
+      item,
+      width,
+      height,
+      loaded: loadedSet.has(item.key)
+    }))
+  };
+}
+function useTesseraGallery(items, options) {
+  const containerRef = useRef(null);
+  const [containerWidth, setContainerWidth] = useState(0);
+  const aspectRatioCache = useRef(/* @__PURE__ */ new Map());
+  const loadedSet = useRef(/* @__PURE__ */ new Set());
+  const [, rerender] = useReducer((n) => n + 1, 0);
+  const committedRowsRef = useRef([]);
+  const committedItemCountRef = useRef(0);
+  const committedContainerWidthRef = useRef(0);
+  const committedOptionsKeyRef = useRef("");
+  for (const item of items) {
+    if (item.aspectRatio !== void 0) {
+      aspectRatioCache.current.set(item.key, item.aspectRatio);
+    }
+  }
+  useEffect(() => {
+    const observer = new ResizeObserver((entries) => {
+      const width = entries[0]?.contentRect.width ?? 0;
+      setContainerWidth(width);
+    });
+    const el = containerRef.current;
+    if (el) observer.observe(el);
+    return () => observer.disconnect();
+  }, []);
+  const onLoad = useCallback(
+    (key, naturalWidth, naturalHeight) => {
+      if (naturalWidth <= 0 || naturalHeight <= 0) return;
+      let changed = false;
+      if (!aspectRatioCache.current.has(key)) {
+        aspectRatioCache.current.set(key, naturalWidth / naturalHeight);
+        changed = true;
+      }
+      if (!loadedSet.current.has(key)) {
+        loadedSet.current.add(key);
+        changed = true;
+      }
+      if (changed) rerender();
+    },
+    []
+  );
+  const resolvedItems = items.filter((item) => aspectRatioCache.current.has(item.key));
+  const optionsKey = `${options.rowHeight}|${options.gap ?? 0}|${options.maxShrink ?? 0.75}|${options.maxStretch ?? 1.5}`;
+  if (containerWidth !== committedContainerWidthRef.current || optionsKey !== committedOptionsKeyRef.current || resolvedItems.length < committedItemCountRef.current) {
+    committedRowsRef.current = [];
+    committedItemCountRef.current = 0;
+    committedContainerWidthRef.current = containerWidth;
+    committedOptionsKeyRef.current = optionsKey;
+  }
+  const frontierItems = resolvedItems.slice(committedItemCountRef.current);
+  const frontierLayout = containerWidth > 0 && frontierItems.length > 0 ? computeTesseraLayout(
+    frontierItems.map((item) => ({
+      aspectRatio: aspectRatioCache.current.get(item.key)
+    })),
+    containerWidth,
+    options
+  ) : [];
+  const frontierRows = [];
+  let itemIdx = 0;
+  for (const layoutRow of frontierLayout) {
+    frontierRows.push({
+      height: layoutRow.height,
+      items: layoutRow.items.map((layoutItem) => ({
+        item: frontierItems[itemIdx++],
+        width: layoutItem.width,
+        height: layoutItem.height
+      }))
+    });
+  }
+  if (frontierRows.length > 1) {
+    for (let i = 0; i < frontierRows.length - 1; i++) {
+      committedRowsRef.current.push(frontierRows[i]);
+      committedItemCountRef.current += frontierRows[i].items.length;
+    }
+  }
+  const rows = committedRowsRef.current.map((row) => toResolvedRow(row, loadedSet.current));
+  const lastFrontierRow = frontierRows[frontierRows.length - 1];
+  if (lastFrontierRow) {
+    rows.push(toResolvedRow(lastFrontierRow, loadedSet.current));
+  }
+  return { containerRef, rows, onLoad };
+}
+
+// src/TesseraGallery.tsx
+import { jsx } from "react/jsx-runtime";
+function TesseraGallery({ items, renderItem, ...options }) {
+  const { containerRef, rows, onLoad } = useTesseraGallery(items, options);
+  const { gap = 0, lastRow = "left" } = options;
+  return /* @__PURE__ */ jsx("div", { ref: containerRef, style: { display: "flex", flexDirection: "column", gap: `${gap}px` }, children: rows.map((row, rowIndex) => {
+    const isLastRow = rowIndex === rows.length - 1;
+    const justifyContent = isLastRow && lastRow === "center" ? "center" : isLastRow && lastRow === "right" ? "flex-end" : "flex-start";
+    return /* @__PURE__ */ jsx("div", { style: { display: "flex", gap: `${gap}px`, justifyContent }, children: row.items.map(
+      ({ item, width, height, loaded }) => renderItem(
+        item,
+        { width, height, loaded },
+        {
+          onLoad: (e) => onLoad(item.key, e.currentTarget.naturalWidth, e.currentTarget.naturalHeight)
+        }
+      )
+    ) }, rowIndex);
+  }) });
+}
+export {
+  TesseraGallery,
+  computeTesseraLayout,
+  useTesseraGallery
+};

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@slithy/react-tessera-gallery",
+  "version": "0.1.0",
+  "description": "React justified gallery with optimal line-breaking layout.",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "peerDependencies": {
+    "react": "^17 || ^18 || ^19"
+  },
+  "devDependencies": {
+    "@testing-library/jest-dom": "^6",
+    "@testing-library/react": "^16",
+    "@types/react": "^19",
+    "@vitejs/plugin-react": "^6",
+    "@vitest/coverage-v8": "^4.1.2",
+    "jsdom": "^29.0.1",
+    "react": "^19",
+    "react-dom": "^19",
+    "tsup": "^8",
+    "typescript": "^5",
+    "vitest": "^4.1.2",
+    "@slithy/tsconfig": "0.0.0",
+    "@slithy/eslint-config": "0.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mjcampagna/react-tessera-gallery"
+  },
+  "author": "mjcampagna",
+  "license": "MIT",
+  "scripts": {
+    "sync": "rsync -a --delete ../../../react-tessera-gallery/src/ ./src/",
+    "clean": "rm -rf dist",
+    "build": "rm -rf dist && tsup src/index.ts --format esm --dts",
+    "dev": "tsup src/index.ts --format esm --dts --watch",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint .",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}