Wasee Gallery

Wasee is a reusable React library for the video pattern in this workspace: a large zoomable visual board, dense image/card clusters, and a contextual detail modal that keeps the gallery visible behind it.

It is meant to be dropped into existing web systems where a team needs “gallery + detail modal” without rebuilding pan, zoom, lazy rendering, keyboard navigation, and modal behavior every time.

Install

pnpm add wasee-gallery

import { WaseeGallery } from "wasee-gallery/react";
import "wasee-gallery/styles.css";

const items = [
  {
    id: "creative-1",
    title: "Instant Surf Hair Look",
    description: "Reference creative with product detail.",
    thumbnailSrc: "/thumbs/surf-hair.jpg",
    detailSrc: "/images/surf-hair.jpg",
    actionLabel: "Open",
  },
];

export function GalleryPage() {
  return (
    <WaseeGallery
      items={items}
      layout="tessellated"
      searchable
      detailMotion={{ maxTilt: 8, glare: true }}
      panSpeed={1.18}
      zoomSensitivity={0.0034}
      zoomStep={1.35}
      zoomOutStep={1.55}
      magnet={{ duration: 420, overshoot: 0.12 }}
      reveal
      height={720}
      onSelect={(item) => console.log(item.id)}
    />
  );
}

What It Provides

• Zoomable 2D gallery canvas with rAF-batched drag pan, middle-mouse-button pan, faster wheel/trackpad zoom, faster zoom-out, and visible +/- controls.
• Dense layouts through built-in cluster, grid, gap-consistent tessellated, and viewport-paged screenful layout engines.
• Viewport virtualization so only visible cards render.
• Optional staged card reveal animation for “new cards fly in from the edge” without replaying already-mounted center cards during pan.
• Controlled or uncontrolled selectedId, viewport, and searchQuery.
• Deferred, NFKC-normalized search so typing stays responsive, including Korean text.
• Magnet return animation when users pan or zoom into empty offscreen space, plus optional section snap for screen-sized gallery pages.
• Detail modal with dimmed/blurred background, close button, ESC, and optional previous/next navigation.
• Liquid-glass detail shell with pointer-reactive 3D tilt, glare, and expansion from the selected card. Disable tilt/glare with detailMotion={false}.
• Custom thumbnail and detail renderers for product cards, ads, portfolios, LMS assets, admin media, or any web app content.
• Core package exports for layout, viewport, and visibility helpers.

API Shape

<WaseeGallery
  items={items}
  layout="screenful"
  layoutOptions={{ itemWidth: 128, gap: 10, sectionItems: 54 }}
  panSpeed={1.18}
  zoomSensitivity={0.0034}
  zoomStep={1.35}
  zoomOutStep={1.55}
  magnet={{ mode: "section", idleDelay: 120, duration: 420, overshoot: 0.12 }}
  reveal={{ duration: 880, stagger: 18, maxDelay: 520 }}
  selectedId={selectedId}
  onSelect={(item) => setSelectedId(item.id)}
  onClose={() => setSelectedId(null)}
  viewport={viewport}
  onViewportChange={setViewport}
  renderThumbnail={({ item }) => <img src={item.thumbnailSrc} alt={item.title} />}
  renderDetail={({ item, close }) => <ProductDetail item={item} onClose={close} />}
/>

Screenful Layout And Section Snap

Use layout="screenful" when the board should feel like the reference video: each dense collage section is sized from the gallery viewport, only the nearest section fills the screen, and idle pan/zoom can snap to the closest section instead of fitting the entire dataset at once.

<WaseeGallery
  items={items}
  layout="screenful"
  layoutOptions={{ itemWidth: 126, gap: 10, sectionPadding: 52, sectionItems: 56 }}
  magnet={{ mode: "section", idleDelay: 110, duration: 460, overshoot: 0.1 }}
/>

Cinematic Prompt Wall Recipe

For the “canvas fills as you move” effect from the Wasee prompt gallery, combine tight virtualization, a slower reveal, and a visible magnetic overshoot. Existing cards stay mounted and stable while only newly visible edge cards animate in; zooming out reveals fresh cards in a staggered wave.

<WaseeGallery
  items={items}
  layout="tessellated"
  layoutOptions={{
    tileSize: 104,
    tileGap: 15,
    columns: 168,
    tessellationPattern: [
      { columns: 1, rows: 1 },
      { columns: 2, rows: 1 },
      { columns: 1, rows: 2 },
      { columns: 2, rows: 2 },
    ],
  }}
  defaultViewport={{ x: 26, y: 64, zoom: 0.88 }}
  overscan={180}
  searchable
  reveal={{
    duration: 1320,
    stagger: 24,
    maxDelay: 1120,
    cycle: 48,
    distanceX: 220,
    distanceY: 160,
    blur: 8,
    scale: 0.82,
  }}
  magnet={{
    idleDelay: 260,
    duration: 820,
    overshoot: 0.055,
    activationMargin: 1400,
  }}
  detailMotion={{ maxTilt: 8, glare: true }}
/>

Search input is intentionally separated from expensive filtering with React deferred rendering, so every keystroke stays responsive while the filtered board updates right after.

See docs/API.md and docs/VIDEO_ANALYSIS.md.

Local Development

pnpm install
pnpm dev
pnpm verify

pnpm verify runs typecheck, tests, library build, and npm pack --dry-run.

Publishing

The unscoped wasee name is already occupied on npm. This package is currently configured as wasee-gallery, which was available when checked on 2026-05-30. See docs/PUBLISHING.md before publishing.