File Finder

# Brok UI: File Finder (`file-finder`)

A macOS Finder-style document browser with an expandable folder tree, breadcrumb navigation, and grid/list views.

Brok UI is a Laravel Blade component registry. Installed components are plain Blade files the app owns.

## Install

```bash
php artisan ui:add pro/file-finder
```

## Usage

```blade
@php
    $tree = [
        [
            'id' => 'contracts',
            'name' => 'Contracts',
            'type' => 'folder',
            'children' => [
                ['id' => 'msa', 'name' => 'Master Service Agreement.pdf', 'type' => 'file', 'mime' => 'application/pdf', 'size' => 248320, 'modified' => 'Mar 2'],
                ['id' => 'nda', 'name' => 'Mutual NDA.docx', 'type' => 'file', 'mime' => 'application/vnd.openxmlformats-officedocument.wordprocessingml.document', 'size' => 38912, 'modified' => 'Feb 18'],
                [
                    'id' => 'signed',
                    'name' => 'Signed',
                    'type' => 'folder',
                    'children' => [
                        ['id' => 'msa-signed', 'name' => 'MSA-signed.pdf', 'type' => 'file', 'mime' => 'application/pdf', 'size' => 261120, 'modified' => 'Mar 4'],
                    ],
                ],
            ],
        ],
        [
            'id' => 'invoices',
            'name' => 'Invoices',
            'type' => 'folder',
            'children' => [
                ['id' => 'inv-2024', 'name' => 'Invoices-2024.xlsx', 'type' => 'file', 'mime' => 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet', 'size' => 51200, 'modified' => 'Jan 9'],
                ['id' => 'inv-export', 'name' => 'export.csv', 'type' => 'file', 'mime' => 'text/csv', 'size' => 14336, 'modified' => 'Jan 9'],
                ['id' => 'inv-0042', 'name' => 'INV-0042.pdf', 'type' => 'file', 'mime' => 'application/pdf', 'size' => 88064, 'modified' => 'Dec 30'],
            ],
        ],
        [
            'id' => 'reports',
            'name' => 'Reports',
            'type' => 'folder',
            'children' => [
                ['id' => 'q4', 'name' => 'Q4-summary.pdf', 'type' => 'file', 'mime' => 'application/pdf', 'size' => 512000, 'modified' => 'Jan 15'],
                ['id' => 'chart', 'name' => 'revenue-chart.png', 'type' => 'file', 'mime' => 'image/png', 'size' => 204800, 'modified' => 'Jan 14'],
                ['id' => 'raw', 'name' => 'raw-data.zip', 'type' => 'file', 'mime' => 'application/zip', 'size' => 1572864, 'modified' => 'Jan 12'],
            ],
        ],
        ['id' => 'readme', 'name' => 'README.txt', 'type' => 'file', 'mime' => 'text/plain', 'size' => 2048, 'modified' => 'Today'],
    ];
@endphp

<div class="mx-auto h-[28rem] w-full max-w-4xl">
    <x-ui.file-finder :items="$tree" />
</div>
```

## Use when

- Use when users need to upload, inspect, edit, annotate, or sign real documents as part of the workflow.
- Browsing a hierarchical set of folders and files inside the app, such as a document library or asset manager.
- Needing a familiar Finder-style tree, breadcrumb, and grid/list toggle instead of a flat file list.

## Avoid when

- Do not use a heavy document interface when the same task can be completed more simply in structured product UI.
- Use search and filters for large document sets, but retain browse paths for users who do not know the exact filename.
- The set of files is flat with no folders; a simple list or table of file-thumbnail tiles is lighter weight.
- The files must be uploaded, not just browsed; pair this with a dedicated upload control.

## Anti-patterns

- Heavy document UI when structured fields are simpler

## Rules

- Use the `<brok:file-finder>` tag (or `<x-ui.file-finder>`) in Blade; do not rewrite the component.
- Prefer the documented props and variants over utility-class overrides; when a utility must win, use the `!` important modifier.
- Use semantic design tokens (`bg-primary`, `text-muted-foreground`), never raw colour utilities.
- Keep the `data-slot` attributes; they are the styling and test hooks.

## Links

- Docs: https://brokui.dev/docs/components/file-finder