### Clone and Install Dependencies with Bun

Source: https://github.com/cminn10/react-trellis-gallery/blob/main/CONTRIBUTING.md

Clone the repository and install project dependencies using Bun. This is the initial setup step for development.

```bash
git clone https://github.com/cminn10/react-trellis-gallery.git
cd react-trellis-gallery
bun install
```

--------------------------------

### Quick Start with TrellisGallery

Source: https://github.com/cminn10/react-trellis-gallery/blob/main/README.md

Basic setup for TrellisGallery with pagination mode, auto layout, and custom item rendering. Ensure the parent container has explicit width and height.

```tsx
import { TrellisGallery } from 'react-trellis-gallery'

const items = Array.from({ length: 20 }, (_, i) => ({
  id: i,
  title: `Item ${i + 1}`,
}))

function App() {
  return (
    <div style={{ width: 800, height: 600 }}>
      <TrellisGallery
        items={items}
        mode="pagination"
        layout={{ type: 'auto', minItemWidth: 180, minItemHeight: 140 }}
        pagination={{ mode: 'uncontrolled' }}
        renderItem={(item) => <div>{item.title}</div>}
        renderExpandedItem={(item) => <div><h2>{item.title}</h2><p>Detail view</p></div>}
      />
    </div>
  )
}
```

--------------------------------

### Install react-trellis-gallery with Bun

Source: https://github.com/cminn10/react-trellis-gallery/blob/main/README.md

Use this command to add the package to your project if you are using Bun as your package manager.

```bash
bun add react-trellis-gallery
```

--------------------------------

### Run Playground Dev Server with Bun

Source: https://github.com/cminn10/react-trellis-gallery/blob/main/CONTRIBUTING.md

Start the playground development server using Bun. This allows for interactive testing of library changes.

```bash
bun run dev:playground
```

--------------------------------

### Install react-trellis-gallery with npm

Source: https://github.com/cminn10/react-trellis-gallery/blob/main/README.md

Use this command to add the package to your project if you are using npm as your package manager.

```bash
npm install react-trellis-gallery
```

--------------------------------

### Virtualized Scroll Mode Example

Source: https://github.com/cminn10/react-trellis-gallery/blob/main/README.md

Example of using TrellisGallery in 'scroll' mode for large datasets, utilizing react-window for virtualization. Adjust overscanCount for performance tuning.

```tsx
<TrellisGallery
  items={items}
  mode="scroll"
  layout={{ type: 'auto', minItemWidth: 200, minItemHeight: 150 }}
  overscanCount={2}
  renderItem={(item) => <div>{item.title}</div>}
  renderExpandedItem={(item) => <div>{item.title}</div>}
/>
```

--------------------------------

### Implement a Custom Task Board with useTrellisGallery

Source: https://context7.com/cminn10/react-trellis-gallery/llms.txt

This example demonstrates how to use the useTrellisGallery hook to create a paginated task board. It includes custom cell rendering and panel management.

```tsx
import { useTrellisGallery, useCellInteraction } from 'react-trellis-gallery'

interface Task {
  id: number
  title: string
  status: 'todo' | 'in-progress' | 'done'
}

const tasks: Task[] = [
  { id: 1, title: 'Design mockups', status: 'done' },
  { id: 2, title: 'Implement API', status: 'in-progress' },
  { id: 3, title: 'Write tests', status: 'todo' },
  { id: 4, title: 'Deploy to staging', status: 'todo' },
]

function TaskCell({ task, onOpen }: { task: Task; onOpen: () => void }) {
  const interaction = useCellInteraction({
    onActivate: onOpen,
    activationCallback: (event) => event.type === 'dblclick',
  })

  const statusColors = {
    'todo': '#e3e3e3',
    'in-progress': '#fff3cd',
    'done': '#d4edda',
  }

  return (
    <div
      {...interaction}
      style={{
        padding: 12,
        background: statusColors[task.status],
        height: '100%',
        borderRadius: 4,
        cursor: 'pointer',
      }}
    >
      <strong>{task.title}</strong>
      <div style={{ marginTop: 4, fontSize: 12, textTransform: 'uppercase' }}>{task.status}</div>
    </div>
  )
}

function CustomTaskBoard() {
  const { containerRef, layout, pagination, panels } = useTrellisGallery({
    items: tasks,
    mode: 'pagination',
    layout: { type: 'manual', rows: 2, cols: 2 },
    gap: 8,
    pagination: { mode: 'uncontrolled' },
    onPanelOpen: (index) => console.log('Opened task:', tasks[index]?.title),
    onPanelClose: (index) => console.log('Closed task:', tasks[index]?.title),
  })

  const pageItems = tasks.slice(pagination.startIndex, pagination.endIndex)

  return (
    <div
      ref={containerRef}
      style={{
        width: 500,
        height: 300,
        position: 'relative',
      }}
    >
      <div
        style={{
          display: 'grid',
          gridTemplateColumns: `repeat(${layout.cols}, ${layout.cellWidth}px)`,
          gridTemplateRows: `repeat(${layout.rows}, ${layout.cellHeight}px)`,
          gap: 8,
        }}
      >
        {pageItems.map((task, i) => (
          <TaskCell
            key={task.id}
            task={task}
            onOpen={() => panels.open(pagination.startIndex + i)}
          />
        ))}
      </div>

      {pagination.totalPages > 1 && (
        <div style={{ marginTop: 16, textAlign: 'center' }}>
          <button onClick={pagination.prev} disabled={!pagination.hasPrev}>Prev</button>
          <span style={{ margin: '0 16px' }}>
            Page {pagination.currentPage + 1} of {pagination.totalPages}
          </span>
          <button onClick={pagination.next} disabled={!pagination.hasNext}>Next</button>
        </div>
      )}

      {panels.openPanels.length > 0 && (
        <div style={{ position: 'fixed', top: 100, right: 100, background: '#fff', padding: 20, boxShadow: '0 4px 12px rgba(0,0,0,0.15)', borderRadius: 8 }}>
          <h3>{tasks[panels.openPanels[0]!.itemIndex]?.title}</h3>
          <p>Status: {tasks[panels.openPanels[0]!.itemIndex]?.status}</p>
          <button onClick={() => panels.close(panels.openPanels[0]!.id)}>Close</button>
        </div>
      )}
    </div>
  )
}

```

--------------------------------

### Imperative Panel Control Example

Source: https://context7.com/cminn10/react-trellis-gallery/llms.txt

Use `useRef` to get a handle on the `TrellisGalleryHandle` for imperative panel management. Methods like `open`, `close`, `closeAll`, and `isOpen` can be called on `galleryRef.current.panels` to control panel states based on item data.

```tsx
import { useRef } from 'react'
import { TrellisGallery, type TrellisGalleryHandle } from 'react-trellis-gallery'

interface Contact {
  id: number
  name: string
  email: string
  favorite: boolean
  department: string
}

const contacts: Contact[] = [
  { id: 1, name: 'Alice Johnson', email: 'alice@example.com', favorite: true, department: 'Engineering' },
  { id: 2, name: 'Bob Smith', email: 'bob@example.com', favorite: false, department: 'Marketing' },
  { id: 3, name: 'Carol Williams', email: 'carol@example.com', favorite: true, department: 'Engineering' },
  { id: 4, name: 'David Brown', email: 'david@example.com', favorite: false, department: 'Sales' },
  { id: 5, name: 'Eve Davis', email: 'eve@example.com', favorite: true, department: 'Engineering' },
  { id: 6, name: 'Frank Miller', email: 'frank@example.com', favorite: false, department: 'Marketing' },
]

function ContactsApp() {
  const galleryRef = useRef<TrellisGalleryHandle<Contact> | null>(null)

  const openFavorites = () => {
    galleryRef.current?.panels.open((contact) => contact.favorite)
  }

  const openByDepartment = (dept: string) => {
    galleryRef.current?.panels.open((contact) => contact.department === dept)
  }

  const closeNonFavorites = () => {
    galleryRef.current?.panels.close((contact) => !contact.favorite)
  }

  const closeAll = () => {
    galleryRef.current?.panels.closeAll()
  }

  const closeUnpinned = () => {
    galleryRef.current?.panels.closeUnpinned()
  }

  const checkIfOpen = (name: string) => {
    const isOpen = galleryRef.current?.panels.isOpen((contact) => contact.name === name)
    alert(`${name} panel is ${isOpen ? 'open' : 'closed'}`)
  }

  return (
    <div>
      <div style={{ marginBottom: 16, display: 'flex', gap: 8, flexWrap: 'wrap' }}>
        <button onClick={openFavorites}>Open Favorites</button>
        <button onClick={() => openByDepartment('Engineering')}>Open Engineering</button>
        <button onClick={closeNonFavorites}>Close Non-Favorites</button>
        <button onClick={closeUnpinned}>Close Unpinned</button>
        <button onClick={closeAll}>Close All</button>
        <button onClick={() => checkIfOpen('Alice Johnson')}>Check Alice</button>
      </div>

      <div style={{ width: '100%', height: 400 }}>
        <TrellisGallery
          ref={galleryRef}
          items={contacts}
          mode="pagination"
          layout={{ type: 'auto', minItemWidth: 200, minItemHeight: 100 }}
          gap={12}
          pagination={{ mode: 'uncontrolled' }}
          renderItem={(contact) => (
            <div style={{ padding: 12, height: '100%' }}>
              <div style={{ fontWeight: 600 }}>{contact.name} {contact.favorite && '⭐'}</div>
              <div style={{ color: '#666', fontSize: 12 }}>{contact.department}</div>
            </div>
          )}
          renderExpandedItem={(contact) => (
            <div style={{ padding: 20 }}>
              <h2>{contact.name}</h2>
              <p>Email: {contact.email}</p>
              <p>Department: {contact.department}</p>
              <p>{contact.favorite ? '⭐ Favorite contact' : ''}</p>
            </div>
          )}
        />
      </div>
    </div>
  )
}

```

--------------------------------

### Basic TrellisGallery with Pagination

Source: https://context7.com/cminn10/react-trellis-gallery/llms.txt

Demonstrates the basic setup of the TrellisGallery component in pagination mode. It includes defining item data, layout, pagination controls, and render functions for grid items and expanded panels. Ensure the parent container has defined dimensions.

```tsx
import { TrellisGallery } from 'react-trellis-gallery'

interface PhotoItem {
  id: number
  title: string
  thumbnail: string
  fullImage: string
  description: string
}

const photos: PhotoItem[] = Array.from({ length: 50 }, (_, i) => ({
  id: i,
  title: `Photo ${i + 1}`,
  thumbnail: `https://picsum.photos/seed/${i}/200/150`,
  fullImage: `https://picsum.photos/seed/${i}/800/600`,
  description: `A beautiful landscape photo number ${i + 1}`,
}))

function PhotoGallery() {
  return (
    <div style={{ width: '100%', height: 600 }}>
      <TrellisGallery
        items={photos}
        mode="pagination"
        layout={{ type: 'auto', minItemWidth: 200, minItemHeight: 150 }}
        gap={8}
        pagination={{
          mode: 'uncontrolled',
          position: 'bottom',
          align: 'center',
        }}
        panelDefaults={{
          size: { width: 700, height: 500 },
          minSize: { width: 400, height: 300 },
        }}
        renderItem={(photo) => (
          <div style={{ width: '100%', height: '100%', overflow: 'hidden' }}>
            <img
              src={photo.thumbnail}
              alt={photo.title}
              style={{ width: '100%', height: '100%', objectFit: 'cover' }}
            />
          </div>
        )}
        renderExpandedItem={(photo) => (
          <div style={{ padding: 16 }}>
            <img
              src={photo.fullImage}
              alt={photo.title}
              style={{ width: '100%', height: 'auto', borderRadius: 8 }}
            />
            <h3>{photo.title}</h3>
            <p>{photo.description}</p>
          </div>
        )}
        panelTitle={(photo) => photo.title}
        onPanelOpen={(photo, index) => console.log('Opened:', photo.title)}
        onPanelClose={(photo, index) => console.log('Closed:', photo.title)}
      />
    </div>
  )
}
```

--------------------------------

### Implement Controlled Pagination

Source: https://context7.com/cminn10/react-trellis-gallery/llms.txt

Use the `controlled` pagination mode to manage the page state externally. This example synchronizes the page with URL parameters and browser history.

```tsx
import { useState, useEffect } from 'react'
import { TrellisGallery } from 'react-trellis-gallery'

interface Article {
  id: number
  title: string
  excerpt: string
  date: string
}

const articles: Article[] = Array.from({ length: 30 }, (_, i) => ({
  id: i,
  title: `Article ${i + 1}: Important News`,
  excerpt: `This is the excerpt for article ${i + 1}. It contains a brief summary of the content.`,
  date: new Date(2024, 0, i + 1).toLocaleDateString(),
}))

function ArticleList() {
  const [page, setPage] = useState(() => {
    const params = new URLSearchParams(window.location.search)
    return parseInt(params.get('page') || '0', 10)
  })

  useEffect(() => {
    const url = new URL(window.location.href)
    url.searchParams.set('page', String(page))
    window.history.replaceState({}, '', url.toString())
  }, [page])

  return (
    <div style={{ width: '100%', height: 500 }}>
      <TrellisGallery
        items={articles}
        mode="pagination"
        layout={{ type: 'auto', minItemWidth: 300, minItemHeight: 120 }}
        gap={16}
        pagination={{
          mode: 'controlled',
          page,
          onPageChange: setPage,
          position: 'bottom',
          align: 'center',
          draggable: true,
        }}
        renderItem={(article) => (
          <div style={{ padding: 16, background: '#fff', border: '1px solid #eee', height: '100%' }}>
            <h3 style={{ margin: 0 }}>{article.title}</h3>
            <p style={{ color: '#666', fontSize: 14 }}>{article.excerpt}</p>
            <span style={{ color: '#999', fontSize: 12 }}>{article.date}</span>
          </div>
        )}
        renderExpandedItem={(article) => (
          <div style={{ padding: 24 }}>
            <h1>{article.title}</h1>
            <p style={{ color: '#666' }}>{article.date}</p>
            <p>{article.excerpt}</p>
            <p>Full article content would be displayed here...</p>
          </div>
        )}
      />
    </div>
  )
}

```

--------------------------------

### Custom Cell Activation Logic

Source: https://context7.com/cminn10/react-trellis-gallery/llms.txt

Implement the `cellActivation` callback to define custom interactions like double-clicks, shift-clicks, or keyboard shortcuts (Enter, Space) for opening panels. This example shows how to handle different event types and key presses.

```tsx
import { TrellisGallery, type CellActivationEvent } from 'react-trellis-gallery'

interface Note {
  id: number
  title: string
  content: string
  color: string
}

const notes: Note[] = [
  { id: 1, title: 'Meeting Notes', content: 'Discuss Q4 goals...', color: '#fff3cd' },
  { id: 2, title: 'Shopping List', content: 'Milk, eggs, bread...', color: '#d4edda' },
  { id: 3, title: 'Project Ideas', content: 'Build a React gallery...', color: '#cce5ff' },
  { id: 4, title: 'Reminders', content: 'Call mom, pay bills...', color: '#f8d7da' },
]

function NotesApp() {
  const handleCellActivation = (event: CellActivationEvent): boolean => {
    // Double-click to open
    if (event.type === 'dblclick') return true

    // Shift + Click to open
    if (event.type === 'click' && event.shiftKey) return true

    // Enter key to open (when focused)
    if (event.type === 'keydown' && 'key' in event && event.key === 'Enter') return true

    // Space key to open (when focused)
    if (event.type === 'keydown' && 'key' in event && event.key === ' ') return true

    return false
  }

  return (
    <div style={{ width: 600, height: 400 }}>
      <p style={{ marginBottom: 8, color: '#666', fontSize: 14 }}>
        Double-click, Shift+Click, or press Enter/Space on a focused note to expand
      </p>
      <TrellisGallery
        items={notes}
        mode="pagination"
        layout={{ type: 'manual', rows: 2, cols: 2 }}
        gap={12}
        pagination={{ mode: 'uncontrolled', renderControl: false }}
        cellActivation={handleCellActivation}
        cellIndicator={false}
        renderItem={(note) => (
          <div
            tabIndex={0}
            style={{
              padding: 16,
              height: '100%',
              background: note.color,
              borderRadius: 8,
              cursor: 'pointer',
            }}>
            <h3 style={{ margin: 0 }}>{note.title}</h3>
            <p style={{ color: '#666', marginTop: 8 }}>{note.content}</p>
          </div>
        )}
        renderExpandedItem={(note) => (
          <div style={{ padding: 24, background: note.color, minHeight: '100%' }}>
            <h1>{note.title}</h1>
            <textarea
              defaultValue={note.content}
              style={{ width: '100%', minHeight: 200, padding: 12, border: '1px solid #ddd', borderRadius: 4 }}
            />
          </div>
        )}
      />
    </div>
  )
}
```

--------------------------------

### Controlled Pagination Example

Source: https://github.com/cminn10/react-trellis-gallery/blob/main/README.md

Demonstrates controlled pagination where the parent component manages the current page state and handles page change events. Requires 'controlled' mode for pagination.

```tsx
const [page, setPage] = useState(0)

<TrellisGallery
  items={items}
  mode="pagination"
  layout={{ type: 'auto', minItemWidth: 200, minItemHeight: 150 }}
  pagination={{
    mode: 'controlled',
    page,
    onPageChange: setPage,
    position: 'bottom',
    align: 'center',
  }}
  renderItem={(item) => <div>{item.title}</div>}
  renderExpandedItem={(item) => <div>{item.title}</div>}
/>
```

--------------------------------

### Custom Panel Header with Item Controls

Source: https://context7.com/cminn10/react-trellis-gallery/llms.txt

Use `renderPanelHeader` to provide a custom header for each item. This function receives item data and a `PanelHeaderAPI` object for controlling panel state and accessibility. The example shows how to display item details and implement pin, maximize/restore, and close buttons.

```tsx
import { TrellisGallery, type PanelHeaderAPI } from 'react-trellis-gallery'

interface FileItem {
  id: number
  name: string
  type: 'image' | 'document' | 'video'
  size: string
}

const files: FileItem[] = [
  { id: 1, name: 'vacation-photo.jpg', type: 'image', size: '2.4 MB' },
  { id: 2, name: 'report-2024.pdf', type: 'document', size: '1.2 MB' },
  { id: 3, name: 'presentation.mp4', type: 'video', size: '45 MB' },
  { id: 4, name: 'profile.png', type: 'image', size: '340 KB' },
]

function FileExplorer() {
  return (
    <div style={{ width: 800, height: 400 }}>
      <TrellisGallery
        items={files}
        mode="pagination"
        layout={{ type: 'manual', rows: 2, cols: 2 }}
        gap={12}
        pagination={{ mode: 'uncontrolled' }}
        renderPanelHeader={(file, api: PanelHeaderAPI) => (
          <div style={{ 
            display: 'flex',
            alignItems: 'center',
            justifyContent: 'space-between',
            padding: '8px 12px',
            borderBottom: '1px solid #eee',
            background: '#f9f9f9',
          }}>
            <div style={{ display: 'flex', alignItems: 'center', gap: 8 }}>
              <span>{file.type === 'image' ? '🖼️' : file.type === 'document' ? '📄' : '🎬'}</span>
              <span {...api.titleProps} style={{ fontWeight: 600 }}>{file.name}</span>
              <span style={{ color: '#999', fontSize: 12 }}>{file.size}</span>
            </div>
            <div style={{ display: 'flex', gap: 4 }}>
              <button
                onClick={api.togglePin}
                style={{ 
                  background: api.isPinned ? '#0078d4' : 'transparent',
                  color: api.isPinned ? '#fff' : '#666',
                  border: '1px solid #ddd',
                  borderRadius: 4,
                  padding: '4px 8px',
                  cursor: 'pointer',
                }}
              >
                📌
              </button>
              <button
                onClick={api.isMaximized ? api.restore : api.maximize}
                style={{ background: 'transparent', border: '1px solid #ddd', borderRadius: 4, padding: '4px 8px', cursor: 'pointer' }}
              >
                {api.isMaximized ? '🗗' : '🗖'}
              </button>
              <button
                onClick={api.close}
                style={{ background: 'transparent', border: '1px solid #ddd', borderRadius: 4, padding: '4px 8px', cursor: 'pointer' }}
              >
                ✕
              </button>
            </div>
          </div>
        )}
        renderItem={(file) => (
          <div style={{ padding: 16, textAlign: 'center', height: '100%', display: 'flex', flexDirection: 'column', justifyContent: 'center' }}>
            <div style={{ fontSize: 48 }}>{file.type === 'image' ? '🖼️' : file.type === 'document' ? '📄' : '🎬'}</div>
            <div style={{ marginTop: 8, fontWeight: 500 }}>{file.name}</div>
            <div style={{ color: '#999', fontSize: 12 }}>{file.size}</div>
          </div>
        )}
        renderExpandedItem={(file) => (
          <div style={{ padding: 24, textAlign: 'center' }}>
            <div style={{ fontSize: 96 }}>{file.type === 'image' ? '🖼️' : file.type === 'document' ? '📄' : '🎬'}</div>
            <p>Preview for {file.name}</p>
            <p>Size: {file.size}</p>
          </div>
        )}
      />
    </div>
  )
}
```

--------------------------------

### Go To and Highlight by Callback

Source: https://github.com/cminn10/react-trellis-gallery/blob/main/README.md

Demonstrates how to use the `goToItem` method with a callback to find, navigate to, and highlight specific items within the gallery.

```APIDOC
## Go To and Highlight by Callback

Pass a callback to match items, navigate to the target match, and highlight all matches. Works in both pagination and scroll modes.

Call `goToItem` on the ref handle:

```tsx
import { useRef } from 'react'
import { TrellisGallery, type TrellisGalleryHandle } from 'react-trellis-gallery'

function SearchableGallery({ items }) {
  const galleryRef = useRef<TrellisGalleryHandle<typeof items[number]> | null>(null)

  const handleSearch = (query: string) => {
    const result = galleryRef.current?.goToItem(
      (item) => item.title.toLowerCase().includes(query.toLowerCase()),
      { highlightDuration: 5000 },
    )
    console.log(result) // { found, page, matchCount, matchIndices, targetIndex }
  }

  return (
    <>
      <input onChange={(e) => handleSearch(e.target.value)} placeholder="Search..." />
      <button onClick={() => galleryRef.current?.clearHighlights()}>Clear</button>
      <TrellisGallery ref={galleryRef} items={items} {...otherProps} />
    </>
  )
}
```

**Customizing the highlight appearance:**

```tsx
<TrellisGallery
  highlightColor="#10b981"
  highlightClassName="my-highlight"
  {...otherProps}
/>
```

You can also override the CSS custom properties or target the `data-rtg-highlighted` attribute directly:

```css
[data-rtg-cell][data-rtg-highlighted]::before {
  box-shadow: 0 0 0 3px hotpink;
}
```
```

--------------------------------

### Panel Boundary Set to Viewport in Trellis Gallery

Source: https://github.com/cminn10/react-trellis-gallery/blob/main/README.md

By default, panels are constrained to the viewport boundaries. This example shows the default `panelBoundary` setting.

```tsx
<TrellisGallery
  items={items}
  mode="scroll"
  layout={{ type: 'auto', minItemWidth: 200, minItemHeight: 150 }}
  panelBoundary="viewport" // default
  renderItem={(item) => <div>{item.title}</div>}
  renderExpandedItem={(item) => <div>{item.title}</div>}
/>
```

--------------------------------

### Go To and Highlight Item by Callback

Source: https://github.com/cminn10/react-trellis-gallery/blob/main/README.md

Use the `goToItem` method on the gallery's ref to find an item matching a callback, navigate to it, and highlight it. The callback receives the item and should return true if it's a match. Configuration options like `highlightDuration` can be passed.

```typescript
import { useRef } from 'react'
import { TrellisGallery, type TrellisGalleryHandle } from 'react-trellis-gallery'

function SearchableGallery({ items }) {
  const galleryRef = useRef<TrellisGalleryHandle<typeof items[number]> | null>(null)

  const handleSearch = (query: string) => {
    const result = galleryRef.current?.goToItem(
      (item) => item.title.toLowerCase().includes(query.toLowerCase()),
      { highlightDuration: 5000 },
    )
    console.log(result) // { found, page, matchCount, matchIndices, targetIndex }
  }

  return (
    <>
      <input onChange={(e) => handleSearch(e.target.value)} placeholder="Search..." />
      <button onClick={() => galleryRef.current?.clearHighlights()}>Clear</button>
      <TrellisGallery ref={galleryRef} items={items} {...otherProps} />
    </>
  )
}
```

--------------------------------

### Headless Usage with Hooks

Source: https://github.com/cminn10/react-trellis-gallery/blob/main/README.md

Illustrates how to use the `useTrellisGallery` and `useCellInteraction` hooks for a headless implementation, providing full control over rendering.

```APIDOC
## Headless Usage

Use the hooks directly for full control over rendering:

```tsx
import { useTrellisGallery, useCellInteraction } from 'react-trellis-gallery'

function Cell({ item, onOpen }) {
  const interaction = useCellInteraction({
    onActivate: onOpen,
    activationCallback: (event) => event.type === 'dblclick',
  })

  return <div {...interaction}>{item.title}</div>
}

function CustomGallery({ items }) {
  const { containerRef, layout, pagination, panels } = useTrellisGallery({
    items,
    mode: 'pagination',
    layout: { type: 'auto', minItemWidth: 200, minItemHeight: 150 },
    pagination: { mode: 'uncontrolled' },
  })

  const pageItems = items.slice(pagination.startIndex, pagination.endIndex)

  return (
    <div ref={containerRef} style={{ width: '100%', height: '100%' }}>
      <div style={{
        display: 'grid',
        gridTemplateColumns: `repeat(${layout.cols}, ${layout.cellWidth}px)`,
        gridTemplateRows: `repeat(${layout.rows}, ${layout.cellHeight}px)`,
      }}>
        {pageItems.map((item, i) => (
          <Cell
            key={i}
            item={item}
            onOpen={() => panels.open(pagination.startIndex + i)}
          />
        ))}
      </div>
    </div>
  )
}
```
```

--------------------------------

### Manual Layout Configuration

Source: https://github.com/cminn10/react-trellis-gallery/blob/main/README.md

Configures the gallery with fixed grid dimensions.

```typescript
{ type: 'manual', rows: 3, cols: 4 }
```

--------------------------------

### Go To Item Options

Source: https://github.com/cminn10/react-trellis-gallery/blob/main/README.md

Options for controlling item navigation, including highlighting duration and target selection.

```typescript
{
  highlightDuration?: number  // ms before auto-clear. 0 = keep indefinitely. Overrides the component prop.
  target?: 'first' | 'last' | number  // which match to navigate to (default: 'first')
}
```

--------------------------------

### Utility Functions

Source: https://github.com/cminn10/react-trellis-gallery/blob/main/README.md

Helper functions for layout calculation, pagination, and grid fitting.

```APIDOC
## Utility Functions

### `calculateLayout(width, height, itemCount, config, gap)`

**Description**: Pure function that computes grid layout. Returns `LayoutResult` with `rows`, `cols`, `cellWidth`, `cellHeight`, `itemsPerPage`, `totalPages`.

### `fitGrid(itemCount, maxRows, maxCols)`

**Description**: Finds the smallest grid (rows × cols) that fits `itemCount` items within bounds. Prefers fewer rows, then fewer columns.

### `clampPage(page, totalPages)`

**Description**: Clamps a page index to the valid range `[0, totalPages - 1]`.
```

--------------------------------

### GoToItemOptions and GoToItemResult

Source: https://github.com/cminn10/react-trellis-gallery/blob/main/README.md

Options for navigating to an item and the result returned after navigation.

```APIDOC
## GoToItemOptions and GoToItemResult

### GoToItemOptions
Configuration options for the `goToItem` method.

| Property | Type | Description | Default |
|---|---|---|---|
| `highlightDuration` | `number` | Duration in milliseconds to highlight the item. `0` means indefinite. Overrides component prop. | N/A |
| `target` | `'first' | 'last' | number` | Specifies which match to navigate to. | `'first'` |

### GoToItemResult
Result object returned by the `goToItem` method.

| Property | Type | Description |
|---|---|---|
| `found` | `boolean` | Indicates if any items matched the criteria. |
| `page` | `number` | The page index of the target item. |
| `matchIndices` | `number[]` | An array of indices for all matching items. |
| `matchCount` | `number` | The total number of items that matched. |
| `targetIndex` | `number` | The index of the item that was navigated to. `-1` if not found. |
```

--------------------------------

### Verify Code with Bun Scripts

Source: https://github.com/cminn10/react-trellis-gallery/blob/main/CONTRIBUTING.md

Before committing, run these Bun scripts to ensure code quality and correctness. This includes linting, formatting, and type checking.

```bash
bun run check && bun run typecheck && bun run build
```

--------------------------------

### Pagination Configuration

Source: https://github.com/cminn10/react-trellis-gallery/blob/main/README.md

Configuration for the gallery's pagination system.

```APIDOC
## Pagination Configuration

### Uncontrolled Mode
The component manages the page state internally.

```json
{
  "mode": "uncontrolled",
  "defaultPage": 0, // Initial page (0-indexed)
  "onPageChange": (page) => {},
  "renderControl": (vm) => {}, // Custom UI or false to hide
  "position": "bottom", // 'top' or 'bottom'
  "align": "center", // 'start', 'center', or 'end'
  "draggable": true,
  "label": "Page" // ReactNode or function returning ReactNode
}
```

### Controlled Mode
You manage the page state externally.

```json
{
  "mode": "controlled",
  "page": 0, // Current page (0-indexed)
  "onPageChange": (page) => {},
  // ... other options same as uncontrolled
}
```
```

--------------------------------

### Auto Layout Configuration

Source: https://github.com/cminn10/react-trellis-gallery/blob/main/README.md

Configures the gallery to automatically calculate grid dimensions based on minimum item size.

```typescript
{ type: 'auto', minItemWidth: 200, minItemHeight: 150 }
```

--------------------------------

### Manual Layout Configuration with Pagination

Source: https://context7.com/cminn10/react-trellis-gallery/llms.txt

Use this mode for precise control over grid dimensions with fixed rows and columns per page, ideal for dashboards or fixed displays. Configures pagination to be uncontrolled.

```tsx
import { TrellisGallery } from 'react-trellis-gallery'

interface DashboardCard {
  id: number
  title: string
  value: string
  trend: 'up' | 'down' | 'neutral'
}

const cards: DashboardCard[] = [
  { id: 1, title: 'Revenue', value: '$45,231', trend: 'up' },
  { id: 2, title: 'Users', value: '2,345', trend: 'up' },
  { id: 3, title: 'Orders', value: '1,234', trend: 'down' },
  { id: 4, title: 'Conversion', value: '3.2%', trend: 'neutral' },
  { id: 5, title: 'Sessions', value: '12,456', trend: 'up' },
  { id: 6, title: 'Bounce Rate', value: '42%', trend: 'down' },
]

function Dashboard() {
  return (
    <div style={{ width: 900, height: 400 }}>
      <TrellisGallery
        items={cards}
        mode="pagination"
        layout={{ type: 'manual', rows: 2, cols: 3 }}
        gap={16}
        pagination={{ mode: 'uncontrolled' }}
        cellIndicator={{
          borderColor: 'rgba(0, 120, 212, 0.3)',
          triangleColor: 'rgba(0, 120, 212, 0.2)',
          triangleSize: 24,
        }}
        renderItem={(card) => (
          <div style={{ padding: 16, background: '#f5f5f5', height: '100%', borderRadius: 8 }}>
            <div style={{ color: '#666', fontSize: 14 }}>{card.title}</div>
            <div style={{ fontSize: 28, fontWeight: 700, marginTop: 8 }}>{card.value}</div>
            <div style={{ color: card.trend === 'up' ? 'green' : card.trend === 'down' ? 'red' : '#666' }}>
              {card.trend === 'up' ? '↑' : card.trend === 'down' ? '↓' : '→'}
            </div>
          </div>
        )}
        renderExpandedItem={(card) => (
          <div style={{ padding: 24 }}>
            <h2>{card.title}</h2>
            <div style={{ fontSize: 48, fontWeight: 700 }}>{card.value}</div>
            <p>Detailed analytics and historical data for {card.title.toLowerCase()}.</p>
          </div>
        )}
      />
    </div>
  )
}
```

--------------------------------

### Layout Configuration

Source: https://github.com/cminn10/react-trellis-gallery/blob/main/README.md

Defines how the gallery items are arranged in a grid.

```APIDOC
## Layout Configuration

### Auto Layout
Calculates grid dimensions based on minimum item sizes.

```json
{ "type": "auto", "minItemWidth": 200, "minItemHeight": 150 }
```

### Manual Layout
Sets a fixed grid size.

```json
{ "type": "manual", "rows": 3, "cols": 4 }
```
```

--------------------------------

### Headless Gallery with Hooks

Source: https://github.com/cminn10/react-trellis-gallery/blob/main/README.md

Utilize `useTrellisGallery` and `useCellInteraction` hooks for complete control over rendering and interaction logic. This approach is suitable for custom gallery implementations.

```typescript
import { useTrellisGallery, useCellInteraction } from 'react-trellis-gallery'

function Cell({ item, onOpen }) {
  const interaction = useCellInteraction({
    onActivate: onOpen,
    activationCallback: (event) => event.type === 'dblclick',
  })

  return <div {...interaction}>{item.title}</div>
}

function CustomGallery({ items }) {
  const { containerRef, layout, pagination, panels } = useTrellisGallery({
    items,
    mode: 'pagination',
    layout: { type: 'auto', minItemWidth: 200, minItemHeight: 150 },
    pagination: { mode: 'uncontrolled' },
  })

  const pageItems = items.slice(pagination.startIndex, pagination.endIndex)

  return (
    <div ref={containerRef} style={{ width: '100%', height: '100%' }}>
      <div style={{
        display: 'grid',
        gridTemplateColumns: `repeat(${layout.cols}, ${layout.cellWidth}px)`,
        gridTemplateRows: `repeat(${layout.rows}, ${layout.cellHeight}px)`,
      }}>
        {pageItems.map((item, i) => (
          <Cell
            key={i}
            item={item}
            onOpen={() => panels.open(pagination.startIndex + i)}
          />
        ))}
      </div>
    </div>
  )
}
```

--------------------------------

### Manual Layout Configuration

Source: https://github.com/cminn10/react-trellis-gallery/blob/main/README.md

Configure TrellisGallery with a fixed grid layout of 3 columns and 2 rows per page. Specify the gap between items.

```tsx
<TrellisGallery
  items={items}
  mode="pagination"
  layout={{ type: 'manual', rows: 2, cols: 3 }}
  gap={8}
  pagination={{ mode: 'uncontrolled' }}
  renderItem={(item) => <div>{item.title}</div>}
  renderExpandedItem={(item) => <div>{item.title}</div>}
/>
```

--------------------------------

### Browser Support

Source: https://github.com/cminn10/react-trellis-gallery/blob/main/README.md

Information on browser compatibility and requirements.

```APIDOC
## Browser Support

Requires browsers with [ResizeObserver](https://caniuse.com/resizeobserver) support (all modern browsers). The library uses `useIsomorphicLayoutEffect` for SSR safety.
```

--------------------------------

### License

Source: https://github.com/cminn10/react-trellis-gallery/blob/main/README.md

Information about the software license.

```APIDOC
## License

[MIT](./LICENSE)
```

--------------------------------

### Implement Custom Pagination Component

Source: https://context7.com/cminn10/react-trellis-gallery/llms.txt

Create a React component that accepts a `PaginationVM` object to render custom pagination UI. This component should handle navigation logic using the provided `vm.prev`, `vm.next`, and `vm.goToPage` methods.

```tsx
import { TrellisGallery, type PaginationVM } from 'react-trellis-gallery'

interface ImageItem {
  id: number
  src: string
  alt: string
}

const images: ImageItem[] = Array.from({ length: 24 }, (_, i) => ({
  id: i,
  src: `https://picsum.photos/seed/img${i}/200/150`,
  alt: `Image ${i + 1}`,
}))

function CustomPaginationControl({ vm }: { vm: PaginationVM }) {
  return (
    <div style={{
      display: 'flex',
      alignItems: 'center',
      gap: 16,
      padding: '12px 20px',
      background: 'rgba(0, 0, 0, 0.8)',
      borderRadius: 24,
      color: '#fff',
    }}>
      <button
        onClick={vm.prev}
        disabled={!vm.hasPrev}
        style={{
          background: 'transparent',
          border: 'none',
          color: vm.hasPrev ? '#fff' : '#666',
          cursor: vm.hasPrev ? 'pointer' : 'not-allowed',
          fontSize: 18,
        }}>
        ←
      </button>

      <div style={{ display: 'flex', gap: 8 }}>
        {Array.from({ length: vm.totalPages }, (_, i) => (
          <button
            key={i}
            onClick={() => vm.goToPage(i)}
            style={{
              width: 32,
              height: 32,
              borderRadius: '50%',
              border: 'none',
              background: i === vm.currentPage ? '#0078d4' : 'transparent',
              color: '#fff',
              cursor: 'pointer',
            }}>
            {i + 1}
          </button>
        ))}
      </div>

      <button
        onClick={vm.next}
        disabled={!vm.hasNext}
        style={{
          background: 'transparent',
          border: 'none',
          color: vm.hasNext ? '#fff' : '#666',
          cursor: vm.hasNext ? 'pointer' : 'not-allowed',
          fontSize: 18,
        }}>
        →
      </button>

      <span style={{ marginLeft: 8, fontSize: 14, opacity: 0.8 }}>
        {vm.startIndex + 1}-{vm.endIndex} of {vm.totalItems}
      </span>
    </div>
  )
}

```