

<Preview name="FileListViewExample" />

## Overview [#overview]

List view components for displaying files in a table format. `FileListView` provides the complete table with OS-style selection, drag-to-select, and context menus, while `FileListItem` renders individual rows for custom table implementations.

### Usage [#usage]

```tsx
import { FileListView } from "@tilt-legal/cubitt-components/composites";
```

```tsx
<FileListView
  files={files}
  selectedIds={selectedIds}
  onSelectionChange={setSelectedIds}
  onOpen={(file) => console.log("Open:", file)}
  onStartRename={(file) => console.log("Inline rename", file)}
  renamingId={selectedIds[0]}
  renameValue={renameValue}
  onRenameValueChange={setRenameValue}
  onRenameSubmit={submitRename}
  onRenameCancel={cancelRename}
/>
```

***

## FileListItem [#filelistitem]

Individual table row component used internally by `FileListView`. Use directly when building custom table layouts or when you need more control over the table structure.

<Preview name="FileListItemStatesExample" />

### Usage [#usage-1]

```tsx
import { Table, TableBody } from "@tilt-legal/cubitt-components/primitives";
import { FileListItem } from "@tilt-legal/cubitt-components/composites";
```

```tsx
<Table>
  <TableBody>
    {files.map((file) => (
      <FileListItem
        key={file.id}
        file={file}
        selected={selectedIds.includes(file.id)}
        onSelect={(event) => 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}
      />
    ))}
  </TableBody>
</Table>
```

***

## API Reference [#api-reference]

### FileListView [#filelistview]

| Prop                         | Type                                                                    | Default      | Description                                                                                                                              |
| ---------------------------- | ----------------------------------------------------------------------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `files`                      | `DisplayFile[]`                                                         | **Required** | Files to display (derived from `FileAsset` via `mapFiles`).                                                                              |
| `selectedIds`                | `string[]`                                                              | `[]`         | Controlled selection IDs.                                                                                                                |
| `onSelectionChange`          | `(ids: string[]) => void`                                               | –            | Called when selection changes.                                                                                                           |
| `onOpen`                     | `(file: DisplayFile) => void`                                           | –            | Triggered when a file is opened (double-click).                                                                                          |
| `loading`                    | `boolean`                                                               | `false`      | Shows loading skeleton rows.                                                                                                             |
| `skeletonCount`              | `number`                                                                | `8`          | Number of skeleton placeholder rows shown when loading.                                                                                  |
| `onFetchMore`                | `() => void`                                                            | –            | Infinite scroll sentinel handler.                                                                                                        |
| `listViewColumns`            | `FileListColumns`                                                       | –            | Toggle default column visibility.                                                                                                        |
| `getContextMenuItems`        | `(file: DisplayFile, selected: DisplayFile[]) => FileContextMenuItem[]` | –            | Optional context menu factory.                                                                                                           |
| `onCancelUpload`             | `(id: string) => void`                                                  | –            | Cancels an in-progress upload when available.                                                                                            |
| `onStartRename`              | `(file: DisplayFile) => void`                                           | –            | Begins inline rename for the provided file.                                                                                              |
| `renamingId`                 | `string \| null`                                                        | –            | Controlled ID currently being renamed.                                                                                                   |
| `renameValue`                | `string`                                                                | –            | Controlled input value during inline rename.                                                                                             |
| `onRenameValueChange`        | `(value: string) => void`                                               | –            | Handles rename input changes.                                                                                                            |
| `onRenameSubmit`             | `() => void`                                                            | –            | Submits the current rename value.                                                                                                        |
| `onRenameCancel`             | `() => void`                                                            | –            | Cancels inline rename.                                                                                                                   |
| `renamePending`              | `boolean`                                                               | `false`      | Shows pending state while rename handler resolves.                                                                                       |
| `onEnterRename`              | `(file: DisplayFile) => void`                                           | –            | 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 list will not deselect files.                                                                       |
| `sidebarOpen`                | `boolean`                                                               | `false`      | Whether the file panel sidebar is open. Used to adjust layout margins.                                                                   |
| `compact`                    | `boolean`                                                               | `false`      | Reduces row padding for denser layouts.                                                                                                  |

### FileListItem [#filelistitem-1]

| Prop                | Type                                | Default      | Description                                                                                                                                                |
| ------------------- | ----------------------------------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `file`              | `DisplayFile`                       | **Required** | File metadata to render. Indicator badges render inline after the filename when `file.indicators` is non-empty (max 2). Optional when `loading` is `true`. |
| `selected`          | `boolean`                           | `false`      | Marks the row as selected.                                                                                                                                 |
| `onSelect`          | `(event: React.MouseEvent) => void` | –            | Selection handler (receives the originating click event).                                                                                                  |
| `onOpen`            | `() => void`                        | –            | Row double-click handler.                                                                                                                                  |
| `onContextMenu`     | `(event: React.MouseEvent) => void` | –            | Optional context menu trigger.                                                                                                                             |
| `onCancelUpload`    | `(id: string) => void`              | –            | Cancels upload when the row is in the uploading state.                                                                                                     |
| `onStartRename`     | `() => void`                        | –            | Begins inline rename for this file.                                                                                                                        |
| `isRenaming`        | `boolean`                           | `false`      | Whether inline rename input should be shown.                                                                                                               |
| `renameValue`       | `string`                            | –            | Current value of the inline rename input.                                                                                                                  |
| `renamePending`     | `boolean`                           | `false`      | Disables rename input while awaiting completion.                                                                                                           |
| `onRenameChange`    | `(value: string) => void`           | –            | Called when the rename input changes.                                                                                                                      |
| `onRenameSubmit`    | `() => void`                        | –            | Submits the rename value.                                                                                                                                  |
| `onRenameCancel`    | `() => void`                        | –            | Cancels inline rename.                                                                                                                                     |
| `listViewColumns`   | `FileListColumns`                   | –            | Toggle column visibility for this row.                                                                                                                     |
| `compact`           | `boolean`                           | `false`      | Reduces row padding.                                                                                                                                       |
| `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).                                                                                                               |