@slithy/react-grid-gallery 0.1.1

package/README.md

@@ -0,0 +1,214 @@
+# @slithy/react-grid-gallery
+
+React grid gallery component. Fixed columns, uniform cell size, optional virtualization and keyboard navigation.
+
+## Installation
+
+```bash
+npm install @slithy/react-grid-gallery
+```
+
+**Peer dependencies:** `react@^17 || ^18 || ^19`
+
+---
+
+## `GridGallery`
+
+Drop-in component. Pass items, tell it how to render each one.
+
+```tsx
+import { GridGallery } from '@slithy/react-grid-gallery'
+
+type Photo = { src: string; alt: string }
+
+const items = photos.map((p, i) => ({ ...p, key: i }))
+
+<GridGallery
+  items={items}
+  columns={4}
+  gap={8}
+  aspectRatio={1}
+  renderItem={(item, { loaded, focused }, { onLoad, onError }) => (
+    <img
+      src={item.src}
+      alt={item.alt}
+      onLoad={onLoad}
+      onError={onError}
+      style={{ width: '100%', height: '100%', objectFit: 'cover', opacity: loaded ? 1 : 0 }}
+    />
+  )}
+/>
+```
+
+### Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `items` | `GalleryItem<T>[]` | — | Items to display. Each must have a `key` property. |
+| `renderItem` | `(item, layout, handlers) => ReactNode` | — | Render function for each cell. See [renderItem](#renderitem). |
+| `scrollContainerRef` | `ScrollContainerRef` | — | Scroll container for virtualization. See [Virtualization](#virtualization). |
+| `columns` | `number \| (width) => number` | — | Column count. Pass a function for responsive columns. |
+| `gap` | `number \| (width) => number` | `0` | Gap between cells in pixels. |
+| `aspectRatio` | `number \| (width) => number` | `1` | Cell width ÷ height. `1` = square, `1.5` = landscape. |
+| `padding` | `number` | `0` | Padding around the grid in pixels. |
+| `virtualize` | `boolean` | `false` | Enable virtual rendering. Only renders visible rows. |
+| `overscan` | `number` | `cellHeight * 4` | Extra pixels to render above and below the viewport. |
+| `navigable` | `boolean` | `false` | Enable keyboard navigation with ARIA grid semantics. |
+| `onActivate` | `(index, shiftKey) => void` | — | Called when a cell is activated via Space or Enter. |
+
+### `renderItem`
+
+The render function receives three arguments:
+
+```tsx
+renderItem(
+  item,                       // GalleryItem<T>: your data + key
+  { loaded, focused },        // layout state
+  { onLoad, onError },        // pass to <img> (or equivalent)
+)
+```
+
+- `loaded` — `true` after `onLoad` fires; use to show a placeholder or fade in
+- `focused` — `true` when this cell has keyboard focus (only meaningful when `navigable` is set)
+- `onLoad` / `onError` — wire to your image element so the gallery tracks load state
+
+### Responsive columns
+
+Pass a function to `columns` (and `gap`) to change layout at different widths:
+
+```tsx
+<GridGallery
+  items={items}
+  columns={(w) => (w < 600 ? 2 : w < 1000 ? 3 : 4)}
+  gap={(w) => (w < 600 ? 4 : 8)}
+  aspectRatio={1}
+  renderItem={...}
+/>
+```
+
+---
+
+## Virtualization
+
+Enable with `virtualize`. Only rows near the viewport are rendered — the rest are replaced by spacer elements.
+
+```tsx
+const scrollRef = useRef<HTMLDivElement>(null)
+
+<div ref={scrollRef} style={{ height: 600, overflowY: 'auto' }}>
+  <GridGallery
+    items={items}
+    columns={4}
+    gap={8}
+    aspectRatio={1}
+    virtualize
+    scrollContainerRef={scrollRef}
+    renderItem={...}
+  />
+</div>
+```
+
+When no `scrollContainerRef` is provided, the gallery virtualizes against the window.
+
+`overscan` controls how much extra content to render beyond the visible area (default: 4× cell height). Increase it on slower devices to reduce blank-row flicker.
+
+---
+
+## Keyboard navigation
+
+Set `navigable` to add ARIA grid semantics and arrow-key navigation:
+
+```tsx
+<GridGallery
+  items={items}
+  columns={4}
+  aspectRatio={1}
+  navigable
+  onActivate={(index, shiftKey) => openLightbox(index, shiftKey)}
+  renderItem={(item, { focused }, handlers) => (
+    <img
+      src={item.src}
+      style={{ outline: focused ? '2px solid blue' : 'none' }}
+      {...handlers}
+    />
+  )}
+/>
+```
+
+| Key | Action |
+|---|---|
+| `ArrowRight` / `ArrowLeft` | Move one cell right / left |
+| `ArrowDown` / `ArrowUp` | Move one row down / up |
+| `Home` | First cell in row (`Ctrl+Home`: first cell) |
+| `End` | Last cell in row (`Ctrl+End`: last cell) |
+| `Space` / `Enter` | Activate cell (`onActivate`) |
+
+Arrow keys with `Meta` held are ignored (allows OS / browser shortcuts to pass through).
+
+---
+
+## `useGridGallery`
+
+Headless hook for building a custom renderer. Returns the same layout state `GridGallery` uses internally.
+
+```tsx
+import { useGridGallery } from '@slithy/react-grid-gallery'
+
+const {
+  containerRef,
+  rows,
+  cellWidth,
+  cellHeight,
+  gap,
+  columns,
+  onLoad,
+  onError,
+  virtualWindow,
+  focusedIndex,
+  handleItemFocus,
+  handleItemKeyDown,
+} = useGridGallery(items, options, scrollContainerRef)
+```
+
+`virtualWindow` is `null` when virtualization is off; otherwise `{ firstIndex, lastIndex, topSpacerHeight, bottomSpacerHeight }`.
+
+---
+
+## `computeGridLayout`
+
+Lower-level layout utility. Takes items, column count, and cell dimensions; returns rows.
+
+```tsx
+import { computeGridLayout } from '@slithy/react-grid-gallery'
+
+const rows = computeGridLayout(items, columns, cellWidth, cellHeight)
+// rows: GridLayoutRow<T>[]
+```
+
+---
+
+## Types
+
+```tsx
+import type {
+  GalleryItem,
+  GridOptions,
+  GridRow,
+  GridLayoutRow,
+  ScrollContainerRef,
+} from '@slithy/react-grid-gallery'
+```
+
+**`GalleryItem<T>`** — Your item type with a required `key`:
+
+```tsx
+type GalleryItem<T> = T & { key: string | number }
+```
+
+**`GridOptions`** — All options accepted by `GridGallery` and `useGridGallery`.
+
+**`ScrollContainerRef`** — `RefObject<HTMLElement | null> | HTMLElement | null`
+
+**`GridRow<T>`** — A rendered row with per-item `loaded` state.
+
+**`GridLayoutRow<T>`** — A computed layout row (output of `computeGridLayout`).

package/dist/index.d.ts

@@ -0,0 +1,70 @@
+import React, { RefObject, ReactEventHandler, ReactNode } from 'react';
+
+type ScrollContainerRef = RefObject<HTMLElement | null> | HTMLElement | null;
+type GridOptions = {
+    columns: number | ((containerWidth: number) => number);
+    gap?: number | ((containerWidth: number) => number);
+    aspectRatio?: number | ((containerWidth: number) => number);
+    padding?: number;
+    virtualize?: boolean;
+    overscan?: number;
+    navigable?: boolean;
+    focusedIndex?: number;
+    onFocusedIndexChange?: (index: number) => void;
+    onActivate?: (index: number, shiftKey: boolean) => void;
+};
+type GalleryItem<T> = T & {
+    key: string | number;
+};
+type GridLayoutRow<T> = {
+    items: GalleryItem<T>[];
+    width: number;
+    height: number;
+};
+type GridRow<T> = {
+    items: Array<{
+        item: GalleryItem<T>;
+        width: number;
+        height: number;
+        loaded: boolean;
+    }>;
+    height: number;
+};
+
+declare function computeGridLayout<T>(items: GalleryItem<T>[], columns: number, cellWidth: number, cellHeight: number): GridLayoutRow<T>[];
+
+type VirtualWindow = {
+    firstIndex: number;
+    lastIndex: number;
+    topSpacerHeight: number;
+    bottomSpacerHeight: number;
+};
+declare function useGridGallery<T>(items: GalleryItem<T>[], options: GridOptions, scrollContainerRef?: ScrollContainerRef): {
+    containerRef: RefObject<HTMLDivElement | null>;
+    rows: GridRow<T>[];
+    cellWidth: number;
+    cellHeight: number;
+    gap: number;
+    columns: number;
+    onLoad: (key: string | number) => void;
+    onError: (key: string | number) => void;
+    virtualWindow: VirtualWindow | null;
+    focusedIndex: number;
+    handleItemFocus: (index: number) => void;
+    handleItemKeyDown: (itemIndex: number, e: React.KeyboardEvent) => void;
+};
+
+type Props<T> = {
+    items: GalleryItem<T>[];
+    renderItem: (item: GalleryItem<T>, layout: {
+        loaded: boolean;
+        focused: boolean;
+    }, handlers: {
+        onLoad: ReactEventHandler<HTMLImageElement>;
+        onError: ReactEventHandler<HTMLImageElement>;
+    }) => ReactNode;
+    scrollContainerRef?: ScrollContainerRef;
+} & GridOptions;
+declare function GridGallery<T>({ items, renderItem, scrollContainerRef, ...options }: Props<T>): ReactNode;
+
+export { type GalleryItem, GridGallery, type GridLayoutRow, type GridOptions, type GridRow, type ScrollContainerRef, computeGridLayout, useGridGallery };

package/dist/index.js

@@ -0,0 +1,307 @@
+// src/computeGridLayout.ts
+function computeGridLayout(items, columns, cellWidth, cellHeight) {
+  if (items.length === 0 || columns <= 0 || cellWidth <= 0) return [];
+  const rows = [];
+  for (let i = 0; i < items.length; i += columns) {
+    rows.push({
+      items: items.slice(i, i + columns),
+      width: cellWidth,
+      height: cellHeight
+    });
+  }
+  return rows;
+}
+
+// src/useGridGallery.ts
+import { useCallback, useEffect as useEffect2, useLayoutEffect, useMemo, useRef as useRef2, useState as useState2 } from "react";
+
+// src/useVirtualWindow.ts
+import { useEffect, useRef, useState } from "react";
+function resolveScrollEl(ref) {
+  if (ref == null) return null;
+  if ("current" in ref) return ref.current;
+  return ref;
+}
+function useVirtualWindow(containerRef, enabled, scrollContainerRef) {
+  const [range, setRange] = useState(null);
+  const rafIdRef = useRef(null);
+  useEffect(() => {
+    if (!enabled) return;
+    const update = () => {
+      const el = containerRef.current;
+      if (!el) return;
+      const rect = el.getBoundingClientRect();
+      const sc = resolveScrollEl(scrollContainerRef);
+      if (sc) {
+        const scRect = sc.getBoundingClientRect();
+        const containerTop = 0 - (rect.top - scRect.top);
+        setRange({ top: containerTop, bottom: containerTop + sc.clientHeight });
+      } else {
+        const containerTop = 0 - rect.top;
+        setRange({ top: containerTop, bottom: containerTop + window.innerHeight });
+      }
+    };
+    const handleScroll = () => {
+      if (rafIdRef.current !== null) cancelAnimationFrame(rafIdRef.current);
+      rafIdRef.current = requestAnimationFrame(() => {
+        update();
+        rafIdRef.current = null;
+      });
+    };
+    update();
+    const target = resolveScrollEl(scrollContainerRef) ?? window;
+    target.addEventListener("scroll", handleScroll, { passive: true });
+    if (target === window) {
+      window.addEventListener("resize", handleScroll, { passive: true });
+    }
+    const ro = new ResizeObserver(update);
+    if (target !== window) ro.observe(target);
+    return () => {
+      target.removeEventListener("scroll", handleScroll);
+      if (target === window) window.removeEventListener("resize", handleScroll);
+      if (rafIdRef.current !== null) cancelAnimationFrame(rafIdRef.current);
+      ro.disconnect();
+    };
+  }, [enabled, containerRef, scrollContainerRef]);
+  return enabled ? range : null;
+}
+
+// src/useGridGallery.ts
+function useGridGallery(items, options, scrollContainerRef) {
+  const containerRef = useRef2(null);
+  const [containerWidth, setContainerWidth] = useState2(0);
+  const [focusedIndex, setFocusedIndex] = useState2(0);
+  const pendingFocusRef = useRef2(null);
+  const loadedSet = useRef2(/* @__PURE__ */ new Set());
+  const [loadedVersion, setLoadedVersion] = useState2(0);
+  const virtualRange = useVirtualWindow(containerRef, options.virtualize === true, scrollContainerRef);
+  useEffect2(() => {
+    const observer = new ResizeObserver((entries) => {
+      const width = entries[0]?.contentRect.width ?? 0;
+      if (width > 0) setContainerWidth(width);
+    });
+    const el = containerRef.current;
+    if (el) observer.observe(el);
+    return () => observer.disconnect();
+  }, []);
+  const onLoad = useCallback((key) => {
+    if (!loadedSet.current.has(key)) {
+      loadedSet.current.add(key);
+      setLoadedVersion((v) => v + 1);
+    }
+  }, []);
+  const onError = useCallback((_key) => {
+  }, []);
+  const resolvedColumns = Math.max(
+    1,
+    Math.round(typeof options.columns === "function" ? options.columns(containerWidth) : options.columns)
+  );
+  const resolvedGap = typeof options.gap === "function" ? options.gap(containerWidth) : options.gap ?? 0;
+  const resolvedAspectRatio = typeof options.aspectRatio === "function" ? options.aspectRatio(containerWidth) : options.aspectRatio ?? 1;
+  const cellWidth = containerWidth > 0 ? Math.floor((containerWidth - resolvedGap * (resolvedColumns - 1)) / resolvedColumns) : 0;
+  const cellHeight = cellWidth > 0 ? Math.round(cellWidth / resolvedAspectRatio) : 0;
+  const rows = useMemo(() => {
+    if (cellWidth === 0) return [];
+    const layoutRows = computeGridLayout(items, resolvedColumns, cellWidth, cellHeight);
+    return layoutRows.map((row) => ({
+      height: row.height,
+      items: row.items.map((item) => ({
+        item,
+        width: row.width,
+        height: row.height,
+        loaded: loadedSet.current.has(item.key)
+      }))
+    }));
+  }, [items, resolvedColumns, cellWidth, cellHeight, loadedVersion]);
+  const rowStride = cellHeight + resolvedGap;
+  let virtualWindow = null;
+  if (options.virtualize && virtualRange !== null && rows.length > 0) {
+    const totalRows = rows.length;
+    const overscan = options.overscan ?? cellHeight * 4;
+    const visibleTop = virtualRange.top - overscan;
+    const visibleBottom = virtualRange.bottom + overscan;
+    let firstIndex = Math.max(0, Math.floor(visibleTop / rowStride));
+    let lastIndex = Math.min(totalRows - 1, Math.ceil(visibleBottom / rowStride) - 1);
+    if (firstIndex > lastIndex) {
+      firstIndex = 0;
+      lastIndex = totalRows - 1;
+    }
+    const topSpacerHeight = firstIndex * rowStride;
+    const bottomSpacerHeight = (totalRows - 1 - lastIndex) * rowStride;
+    virtualWindow = { firstIndex, lastIndex, topSpacerHeight, bottomSpacerHeight };
+  }
+  const isControlled = options.focusedIndex !== void 0;
+  const padding = options.padding ?? 0;
+  function scrollToRow(rowIndex) {
+    const rowTop = padding + rowIndex * rowStride;
+    const rowBottom = rowTop + cellHeight;
+    const scrollEl = resolveScrollEl(scrollContainerRef);
+    if (scrollEl) {
+      if (rowTop < scrollEl.scrollTop) {
+        scrollEl.scrollTop = rowTop;
+      } else if (rowBottom > scrollEl.scrollTop + scrollEl.clientHeight) {
+        scrollEl.scrollTop = rowBottom - scrollEl.clientHeight;
+      }
+    } else {
+      const containerEl = containerRef.current;
+      if (!containerEl) return;
+      const absTop = containerEl.getBoundingClientRect().top + window.scrollY + rowTop;
+      const absBottom = absTop + cellHeight;
+      if (absTop < window.scrollY) {
+        window.scrollTo({ top: absTop });
+      } else if (absBottom > window.scrollY + window.innerHeight) {
+        window.scrollTo({ top: absBottom - window.innerHeight });
+      }
+    }
+  }
+  function navigateTo(newIndex) {
+    if (items.length === 0) return;
+    const clamped = Math.max(0, Math.min(newIndex, items.length - 1));
+    if (!isControlled) setFocusedIndex(clamped);
+    options.onFocusedIndexChange?.(clamped);
+    const target = containerRef.current?.querySelector(`[data-grid-index="${clamped}"]`);
+    if (target) {
+      target.focus();
+    } else {
+      scrollToRow(Math.floor(clamped / resolvedColumns));
+      pendingFocusRef.current = clamped;
+    }
+  }
+  function handleItemKeyDown(itemIndex, e) {
+    const col = itemIndex % resolvedColumns;
+    const rowStart = itemIndex - col;
+    const rowEnd = Math.min(rowStart + resolvedColumns - 1, items.length - 1);
+    switch (e.key) {
+      case "ArrowRight":
+        if (e.metaKey) break;
+        e.preventDefault();
+        navigateTo(itemIndex + 1);
+        break;
+      case "ArrowLeft":
+        if (e.metaKey) break;
+        e.preventDefault();
+        navigateTo(itemIndex - 1);
+        break;
+      case "ArrowDown":
+        if (e.metaKey) break;
+        e.preventDefault();
+        navigateTo(itemIndex + resolvedColumns);
+        break;
+      case "ArrowUp":
+        if (e.metaKey) break;
+        e.preventDefault();
+        navigateTo(itemIndex - resolvedColumns);
+        break;
+      case "Home":
+        e.preventDefault();
+        navigateTo(e.ctrlKey ? 0 : rowStart);
+        break;
+      case "End":
+        e.preventDefault();
+        navigateTo(e.ctrlKey ? items.length - 1 : rowEnd);
+        break;
+      case " ":
+      case "Enter":
+        e.preventDefault();
+        options.onActivate?.(itemIndex, e.shiftKey);
+        break;
+    }
+  }
+  useLayoutEffect(() => {
+    if (pendingFocusRef.current === null) return;
+    const target = containerRef.current?.querySelector(`[data-grid-index="${pendingFocusRef.current}"]`);
+    if (target) {
+      target.focus();
+      pendingFocusRef.current = null;
+    }
+  });
+  const effectiveFocusedIndex = isControlled ? options.focusedIndex : focusedIndex;
+  function handleItemFocus(index) {
+    if (!isControlled) setFocusedIndex(index);
+    options.onFocusedIndexChange?.(index);
+  }
+  return {
+    containerRef,
+    rows,
+    cellWidth,
+    cellHeight,
+    gap: resolvedGap,
+    columns: resolvedColumns,
+    onLoad,
+    onError,
+    virtualWindow,
+    focusedIndex: effectiveFocusedIndex,
+    handleItemFocus,
+    handleItemKeyDown
+  };
+}
+
+// src/GridGallery.tsx
+import { jsx, jsxs } from "react/jsx-runtime";
+function GridGallery({ items, renderItem, scrollContainerRef, ...options }) {
+  const { containerRef, rows, cellHeight, gap, columns, onLoad, onError, virtualWindow, focusedIndex, handleItemFocus, handleItemKeyDown } = useGridGallery(
+    items,
+    options,
+    scrollContainerRef
+  );
+  const firstIndex = virtualWindow?.firstIndex ?? 0;
+  const lastIndex = virtualWindow?.lastIndex ?? rows.length - 1;
+  const visibleRows = virtualWindow ? rows.slice(firstIndex, lastIndex + 1) : rows;
+  const padding = options.padding ?? 0;
+  const navigable = options.navigable === true;
+  return /* @__PURE__ */ jsxs(
+    "div",
+    {
+      ref: containerRef,
+      style: { display: "flex", flexDirection: "column", gap: `${gap}px`, padding: padding > 0 ? `${padding}px` : void 0 },
+      ...navigable ? { role: "grid", "aria-rowcount": rows.length, "aria-colcount": columns } : {},
+      children: [
+        virtualWindow && virtualWindow.topSpacerHeight > 0 && /* @__PURE__ */ jsx("div", { style: { height: virtualWindow.topSpacerHeight, contain: "layout" } }),
+        visibleRows.map((row, i) => {
+          const rowIndex = firstIndex + i;
+          return /* @__PURE__ */ jsx(
+            "div",
+            {
+              style: { display: "grid", gridTemplateColumns: `repeat(${columns}, 1fr)`, gap: `${gap}px`, contain: "layout" },
+              ...navigable ? { role: "row", "aria-rowindex": rowIndex + 1 } : {},
+              children: row.items.map(({ item, loaded }, colIdx) => {
+                const itemIndex = rowIndex * columns + colIdx;
+                const focused = navigable && focusedIndex === itemIndex;
+                return /* @__PURE__ */ jsx(
+                  "div",
+                  {
+                    style: { height: `${cellHeight}px` },
+                    ...navigable ? {
+                      role: "gridcell",
+                      "aria-colindex": colIdx + 1,
+                      tabIndex: focused ? 0 : -1,
+                      "data-grid-index": itemIndex,
+                      onKeyDown: (e) => handleItemKeyDown(itemIndex, e),
+                      onFocus: () => handleItemFocus(itemIndex)
+                    } : {},
+                    children: renderItem(
+                      item,
+                      { loaded, focused },
+                      {
+                        onLoad: () => onLoad(item.key),
+                        onError: () => onError(item.key)
+                      }
+                    )
+                  },
+                  item.key
+                );
+              })
+            },
+            rowIndex
+          );
+        }),
+        virtualWindow && virtualWindow.bottomSpacerHeight > 0 && /* @__PURE__ */ jsx("div", { style: { height: virtualWindow.bottomSpacerHeight, contain: "layout" } })
+      ]
+    }
+  );
+}
+export {
+  GridGallery,
+  computeGridLayout,
+  useGridGallery
+};

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@slithy/react-grid-gallery",
+  "version": "0.1.1",
+  "description": "React grid gallery component.",
+  "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-grid-gallery"
+  },
+  "author": "mjcampagna",
+  "license": "MIT",
+  "scripts": {
+    "sync": "rsync -a --delete ../../../react-grid-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"
+  }
+}