## Overview [#overview]
Grid view components for displaying files with minimal OS-inspired design. `FileGridView` provides the complete grid with hover states, selection, and context menus while `FileGridItem` renders individual items for custom grid implementations.
### Usage [#usage]
```tsx
import { FileGridView } from "@tilt-legal/cubitt-components/composites";
```
```tsx
console.log("Open:", file)}
/>
```
***
## FileGridItem [#filegriditem]
Individual grid item component used internally by `FileGridView`. Use directly when building custom grid layouts or when you need more control over the grid structure.
### Usage [#usage-1]
```tsx
import { FileGridItem } from "@tilt-legal/cubitt-components/composites";
```
```tsx
{files.map((file) => (
handleSelect(file.id, event)}
onOpen={() => openFile(file)}
onCancelUpload={cancelUpload}
onStartRename={() => beginInlineRename(file)}
isRenaming={renamingId === file.id}
renameValue={renameValue}
onRenameChange={setRenameValue}
onRenameSubmit={submitRename}
onRenameCancel={cancelRename}
data-file-id={file.id}
/>
))}
```
***
## API Reference [#api-reference]
### FileGridView [#filegridview]
| Prop | Type | Default | Description |
| ---------------------------- | ----------------------------------------------------------------------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `files` | `DisplayFile[]` | **Required** | Files to display (already normalised). |
| `selectedIds` | `string[]` | `[]` | Controlled selection IDs. |
| `onSelectionChange` | `(ids: string[]) => void` | – | Called when selection changes. |
| `onOpen` | `(file: DisplayFile) => void` | – | Called when an item is opened (double-click). |
| `loading` | `boolean` | `false` | Shows loading skeletons. |
| `skeletonCount` | `number` | `30` | Number of skeleton placeholder items shown when loading. |
| `onFetchMore` | `() => void` | – | Infinite scroll sentinel handler. |
| `getContextMenuItems` | `(file: DisplayFile, selected: DisplayFile[]) => FileContextMenuItem[]` | – | Optional context menu generator. |
| `onCancelUpload` | `(id: string) => void` | – | Cancels an in-progress upload. |
| `onStartRename` | `(file: DisplayFile) => void` | – | Initiates inline rename. |
| `renamingId` | `string \| null` | – | ID currently being renamed. |
| `renameValue` | `string` | – | Inline rename input value. |
| `onRenameValueChange` | `(value: string) => void` | – | Handles input changes. |
| `onRenameSubmit` | `() => void` | – | Submits the rename. |
| `onRenameCancel` | `() => void` | – | Cancels rename. |
| `renamePending` | `boolean` | `false` | Shows pending state while rename resolves. |
| `onEnterRename` | `(file: DisplayFile) => void` | – | Optional callback invoked when Enter is pressed on a selected file. |
| `disableSelection` | `boolean` | `false` | When true, disables all selection functionality (both click and drag). |
| `disableContextMenu` | `boolean` | `false` | When true, disables the right-click context menu. |
| `selectionMode` | `'single' \| 'multiple'` | `'multiple'` | Selection cardinality. `'single'`: only one file at a time, disables drag-select and modifier keys. `'multiple'`: standard multi-select. |
| `selectionBehavior` | `'replace' \| 'toggle'` | `'replace'` | Click behavior. `'replace'`: click selects one file, Shift/Cmd for multi. `'toggle'`: every click adds/removes from selection. |
| `dragSelectContainerId` | `string` | – | Optional ID of container element to scope drag-select functionality. |
| `clickOutsideContainerId` | `string \| string[]` | – | Container ID(s) where clicks should not clear selection. |
| `disableDragSelect` | `boolean` | `false` | When true, disables drag-to-select functionality while keeping click selection enabled. |
| `disableClickOutsideToClear` | `boolean` | `false` | When true, clicking outside the file grid will not deselect files. |
| `sidebarOpen` | `boolean` | `false` | Whether the file panel sidebar is open. Used to adjust layout margins. |
### FileGridItem [#filegriditem-1]
| Prop | Type | Default | Description |
| ------------------- | --------------------------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `file` | `DisplayFile` | **Required** | File info to display. Indicator badges render automatically when `file.indicators` is non-empty (max 2). Optional when `loading` is `true`. |
| `selected` | `boolean` | `false` | Whether this item is selected. |
| `onSelect` | `(fileId: string, event: React.MouseEvent) => void` | – | Selection handler (receives file ID and click event). |
| `onOpen` | `(file: DisplayFile) => void` | – | Item double-click handler. |
| `onCancelUpload` | `(id: string) => void` | – | Cancels upload for this item. |
| `onStartRename` | `(file: DisplayFile) => void` | – | Begins inline rename. Receives the file. |
| `isRenaming` | `boolean` | `false` | Whether inline input is shown. |
| `renameValue` | `string` | – | Current rename value. |
| `renamePending` | `boolean` | `false` | Disables input while awaiting resolution. |
| `onRenameChange` | `(value: string) => void` | – | Rename input change handler. |
| `onRenameSubmit` | `() => void` | – | Rename submit handler. |
| `onRenameCancel` | `() => void` | – | Rename cancel handler. |
| `disableSelection` | `boolean` | `false` | When true, disables selection for this item. |
| `selectionBehavior` | `'replace' \| 'toggle'` | `'replace'` | Click behavior. Affects checkbox visibility in toggle mode. |
| `loading` | `boolean` | `false` | Shows a skeleton placeholder instead of file content. |
| `data-file-id` | `string` | – | Data attribute for drag selection (Selecto). |