

<Preview name="FileListViewExample" />

## Overview [#overview]

`Files.List` lays out `Files.Item` children in the same compact row treatment as the previous Files surface. Cubitt owns the row visuals, header, metadata columns, selection interaction, focus treatment, upload/error display, and file/folder icon rendering. Consumers own item data, filtering, sorting, folder navigation, upload state, and actions.

## Usage [#usage]

```tsx
import {
  Files,
  type FilesItem,
} from "@tilt-legal/cubitt-components/files";

function FileList({
  items,
  selectedIds,
  setSelectedIds,
}: {
  items: FilesItem[];
  selectedIds: string[];
  setSelectedIds: (ids: string[]) => void;
}) {
  return (
    <Files
      selectedIds={selectedIds}
      onSelectedIdsChange={setSelectedIds}
      selectionMode="multiple"
    >
      <Files.List>
        {items.map((item) => (
          <Files.Item
            item={item}
            key={item.id}
            onOpen={(openedItem) => {
              if (openedItem.kind === "folder") {
                navigateToFolder(openedItem.id);
              }
            }}
          />
        ))}
      </Files.List>
    </Files>
  );
}
```

## List Item [#list-item]

<Preview name="FileListItemStatesExample" />

`Files.Item` renders one file or folder row inside `Files.List`. Its `status`
value controls only file lifecycle display:

| Status      | Description                                                                                 |
| ----------- | ------------------------------------------------------------------------------------------- |
| omitted     | Normal folder, virtual file, or MIME icon display.                                          |
| `loading`   | Skeleton placeholder row for an item whose data is not ready yet.                           |
| `uploading` | Indeterminate icon only until positive progress is available, then `· n%` in the Name cell. |
| `error`     | Inline `· Upload failed` treatment in the Name cell.                                        |

Upload percentages use tabular numerals so changing values do not shift the
filename or status separator.

Selection, active highlight, inline rename, drag, drop-target, disabled,
hover, and focus are interaction states owned by `Files` and item props, not
`FilesItem.status` values.

## Columns [#columns]

`Files.Item` renders the stable default columns `Name`, `Type`, `Size`,
`Created by`, `Created`, and `Updated`. Uploading, loading, and error states do
not alter that schema or add a Status column. Rows render an empty cell when an
item does not yet have a configured metadata value.

`Files.List` uses `Files.metadataProperties` only for intentional metadata
column configuration. Omit a property from that root prop to hide it from the
list and from `Files.Details.Metadata`.

Use `Files.List.Header` when the list header needs to live outside the scrolling
list body, such as in a dialog header. It derives the same configured columns as
the list body; render the body with `showHeader={false}`.

## Props [#props]

### Files.List [#fileslist]

| Prop         | Type          | Default | Description                                                    |
| ------------ | ------------- | ------- | -------------------------------------------------------------- |
| `children`   | `ReactNode`   | -       | `Files.Item` rows.                                             |
| `items`      | `FilesItem[]` | -       | Optional visible item array used for range-selection metadata. |
| `showHeader` | `boolean`     | `true`  | Whether the default list header renders inside the list body.  |
| `className`  | `string`      | -       | Extends the list root.                                         |

Also accepts standard `div` props.

### Files.List.Header [#fileslistheader]

| Prop        | Type          | Default | Description                                                                |
| ----------- | ------------- | ------- | -------------------------------------------------------------------------- |
| `items`     | `FilesItem[]` | -       | Deprecated compatibility prop. Visible items no longer alter list columns. |
| `className` | `string`      | -       | Extends the detached header wrapper.                                       |

Also accepts standard `div` props.

### Files.Item [#filesitem]

| Prop        | Type                    | Default | Description                                                         |
| ----------- | ----------------------- | ------- | ------------------------------------------------------------------- |
| `item`      | `FilesItem`             | -       | File or folder display data.                                        |
| `onOpen`    | `(item, event) => void` | -       | Called on double click, or Enter when inline rename is unavailable. |
| `disabled`  | `boolean`               | `false` | Disables the item in addition to root and item data disabled state. |
| `className` | `string`                | -       | Extends the item root.                                              |

Selection is controlled by the root `Files` props: `selectedIds`,
`onSelectedIdsChange`, `selectionMode`, `selectionBehavior`, and optional
`canSelect`.