@flamingo-stack/openframe-frontend-core 0.0.213 → 0.0.214-snapshot.20260528192313

package/src/components/ui/data-table/.types.md

@@ -0,0 +1,54 @@
+<!-- source-hash: 0bb70a064412065a884dd7759655fdc8 -->
+Augments TanStack React Table's `ColumnMeta` interface with Flamingo-specific display and behavior options, and exports shared filter/breakpoint types used across data table components.
+
+## Key Components
+
+| Export | Type | Description |
+|--------|------|-------------|
+| `TailwindBreakpoint` | Type alias | Union of responsive breakpoints: `'md' \| 'lg' \| 'xl' \| '2xl'` |
+| `DataTableFilterOption` | Interface | Shape for individual filter dropdown options (`id`, `label`, `value`) |
+| `ColumnMeta` (module augmentation) | Interface extension | Adds Flamingo-specific metadata fields to TanStack Table's `ColumnMeta` |
+
+### `ColumnMeta` Augmented Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `width` | `string` | Tailwind width class (e.g. `'w-40'`, `'flex-1 min-w-0'`) |
+| `align` | `'left' \| 'center' \| 'right'` | Horizontal alignment for cell and header |
+| `hideAt` | `TailwindBreakpoint \| TailwindBreakpoint[]` | Hides the column at/below specified breakpoint(s) |
+| `filter` | `{ options, placement? }` | Enables a filter dropdown in the header with provided options |
+| `sortable` | `boolean` | Opt-in sort indicator in header; defaults to `false` |
+| `cellClassName` | `string` | Extra class names for the body cell wrapper |
+| `headerClassName` | `string` | Extra class names for the header cell wrapper |
+
+## Usage Example
+
+```typescript
+import type { ColumnDef } from '@tanstack/react-table'
+import type { DataTableFilterOption } from './types'
+
+const statusOptions: DataTableFilterOption[] = [
+  { id: 'active', label: 'Active', value: 'active' },
+  { id: 'inactive', label: 'Inactive', value: 'inactive' },
+]
+
+const columns: ColumnDef<User>[] = [
+  {
+    accessorKey: 'name',
+    meta: {
+      width: 'flex-1 min-w-0',
+      align: 'left',
+      sortable: true,
+      hideAt: ['md', 'lg'],
+    },
+  },
+  {
+    accessorKey: 'status',
+    meta: {
+      width: 'w-40',
+      filter: { options: statusOptions, placement: 'bottom-start' },
+      cellClassName: 'font-medium',
+    },
+  },
+]
+```

package/src/components/ui/data-table/.use-data-table.md

@@ -0,0 +1,45 @@
+<!-- source-hash: 4c242f0aea85fea9fe359656cea3e3d5 -->
+A thin wrapper around TanStack's `useReactTable` with sensible defaults for server-driven (Relay/REST) pagination, sorting, and filtering. Row-model factories are instantiated once at module load to preserve internal TanStack caches across renders.
+
+## Key Components
+
+- **`UseDataTableOptions<T>`** — Extends TanStack's `TableOptions<T>` (omitting `getCoreRowModel`) with two additional flags:
+  - `clientSideSorting` — enables `getSortedRowModel` (default: `false`)
+  - `clientSideFiltering` — enables `getFilteredRowModel` (default: `false`)
+- **`useDataTable<T>`** — The main hook. Wraps `useReactTable` and automatically sets `manualSorting`/`manualFiltering` to the inverse of the client-side flags unless explicitly overridden.
+
+## Usage Example
+
+```typescript
+import { useMemo, useCallback } from 'react'
+import { useDataTable } from './use-data-table'
+import type { ColumnDef } from '@tanstack/react-table'
+
+// Stable references — required to avoid row-model rebuilds on every render
+const data = useMemo(() => rows.map(toUiRow), [rows])
+const columns = useMemo<ColumnDef<MyRow>[]>(() => [
+  { accessorKey: 'name', header: 'Name' },
+  { accessorKey: 'status', header: 'Status' },
+], [])
+const getRowId = useCallback((row: MyRow) => row.id, [])
+const sorting = useMemo(() => [{ id: sortKey, desc: sortDesc }], [sortKey, sortDesc])
+
+const table = useDataTable({
+  data,
+  columns,
+  getRowId,
+  state: { sorting },          // wrapper object can be inline
+  onSortingChange: handleSort, // callbacks can be inline
+  // clientSideSorting: true,  // opt-in for fully client-side tables
+})
+```
+
+## Reference-Stability Notes
+
+| Option | Safe inline? |
+|---|---|
+| `data`, `columns` | ❌ — must `useMemo` |
+| `state` (wrapper) | ✅ — build inline freely |
+| `state.sorting`, `state.pagination` | ❌ — must be stable refs |
+| `onXChange` callbacks | ✅ — invoked, never compared |
+| `meta`, `defaultColumn` | ⚠️ — recommended `useMemo` |

package/src/components/ui/data-table/.utils.md

@@ -0,0 +1,38 @@
+<!-- source-hash: 1499b2bf29298a7d9f4f5ec8c921eb3e -->
+Utility functions for TanStack React Table and Tailwind CSS column/cell rendering helpers.
+
+## Key Components
+
+| Export | Type | Description |
+|--------|------|-------------|
+| `getHideClasses` | `function` | Generates Tailwind responsive visibility classes from breakpoint config |
+| `alignJustify` | `function` | Maps column alignment metadata to Tailwind flex/text justify classes |
+| `multiSelectFilterFn` | `FilterFn<any>` | TanStack Table filter function for multi-select column filters |
+
+## Usage Example
+
+```typescript
+import { getHideClasses, alignJustify, multiSelectFilterFn } from './utils'
+import type { ColumnDef } from '@tanstack/react-table'
+
+// Responsive column visibility
+getHideClasses('md')           // 'hidden md:flex'
+getHideClasses(['md', 'lg'])   // 'md:hidden lg:hidden xl:flex'
+
+// Column alignment
+alignJustify('right')   // 'justify-end text-right'
+alignJustify('center')  // 'justify-center text-center'
+alignJustify()          // 'justify-start text-left' (default)
+
+// Multi-select client-side filtering
+const columns: ColumnDef<Device>[] = [
+  {
+    accessorKey: 'status',
+    header: 'Status',
+    filterFn: multiSelectFilterFn,
+    meta: { filter: { options: STATUS_OPTIONS } },
+  },
+]
+```
+
+> **Note on `multiSelectFilterFn`:** Only applies when `clientSideFiltering: true` is set on `useDataTable`. For server-side (Relay/REST) filtering, `manualFiltering` is enabled and TanStack never calls `filterFn` — translate `columnFilters` state into your backend query variables directly.

package/src/components/ui/file-manager/.file-manager-action-bar.md

@@ -1,39 +1,48 @@
-<!-- source-hash: 7f4091a6eea7a1623fd7eaf21bd6edb8 -->
-A React component that renders a file management toolbar with standard file operations like copy, cut, paste, upload, and folder creation.
+<!-- source-hash: 35fc4ad5dd56ef4d64fe4e521ab6318a -->
+A toolbar component for the File Manager that renders action buttons for common file operations.
 
 ## Key Components
 
-- **FileManagerActionBar**: Main component that renders action buttons for file management operations
-- **Button Integration**: Uses custom Button component with outline variant and small sizing
-- **Icon Integration**: Leverages Lucide React icons for visual button indicators
-- **Conditional States**: Handles disabled states for copy/cut (requires selection) and paste (requires clipboard content)
+### `FileManagerActionBar`
+A client-side React component that displays a responsive button bar with six file management actions.
+
+| Button | Icon | Disabled When |
+|--------|------|---------------|
+| New Folder | `FolderPlus` | Never |
+| Copy | `Copy` | `hasSelection = false` |
+| Cut | `Scissors` | `hasSelection = false` |
+| Paste | `Clipboard` | `canPaste = false` |
+| Upload | `Upload` | Never |
+| Select All | `CheckSquare` | Never |
+
+### Props (`FileManagerActionBarProps`)
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `canPaste` | `boolean` | `false` | Enables the Paste button |
+| `hasSelection` | `boolean` | `false` | Enables Copy and Cut buttons |
+| `onNewFolder` | `() => void` | — | Create folder handler |
+| `onPaste` | `() => void` | — | Paste handler |
+| `onCopy` | `() => void` | — | Copy handler |
+| `onCut` | `() => void` | — | Cut handler |
+| `onUpload` | `() => void` | — | Upload handler |
+| `onSelectAll` | `() => void` | — | Select all handler |
+| `className` | `string` | — | Additional CSS classes |
 
 ## Usage Example
 
 ```typescript
-import { FileManagerActionBar } from './file-manager-action-bar'
-
-function FileExplorer() {
-  const [selectedFiles, setSelectedFiles] = useState<string[]>([])
-  const [clipboardHasContent, setClipboardHasContent] = useState(false)
-
-  return (
-    <div>
-      <FileManagerActionBar
-        hasSelection={selectedFiles.length > 0}
-        canPaste={clipboardHasContent}
-        onNewFolder={() => console.log('Create new folder')}
-        onCopy={() => console.log('Copy selected files')}
-        onCut={() => console.log('Cut selected files')}
-        onPaste={() => console.log('Paste from clipboard')}
-        onUpload={() => console.log('Upload files')}
-        onSelectAll={() => console.log('Select all files')}
-        className="mb-4"
-      />
-      {/* File list components */}
-    </div>
-  )
-}
+<FileManagerActionBar
+  canPaste={clipboard !== null}
+  hasSelection={selectedItems.length > 0}
+  onNewFolder={() => setShowNewFolderModal(true)}
+  onCopy={() => setClipboard({ mode: 'copy', items: selectedItems })}
+  onCut={() => setClipboard({ mode: 'cut', items: selectedItems })}
+  onPaste={() => handlePaste(currentPath)}
+  onUpload={() => fileInputRef.current?.click()}
+  onSelectAll={() => setSelectedItems(allItems)}
+  className="px-4 py-2 border-b"
+/>
 ```
 
-The component provides a responsive toolbar with wrapped buttons, appropriate disabled states, and consistent styling using Tailwind classes and the cn utility for conditional styling.
+The bar is responsive — it wraps on small screens and right-aligns on `md` and above via `flex-wrap md:justify-end`.

package/src/components/ui/file-manager/.file-manager-breadcrumb.md

@@ -1,38 +1,40 @@
-<!-- source-hash: 7dbf1d4bdaf21bcabc561fc643fe10c4 -->
-A React component that renders a clickable breadcrumb navigation for file system hierarchies, displaying the path with chevron separators and hover interactions.
+<!-- source-hash: 10ec2f9a1b5237b3543c1a35d4d9d860 -->
+Renders a navigable breadcrumb trail for a file manager UI, displaying a series of clickable path segments separated by chevron icons.
 
 ## Key Components
 
-- **FileManagerBreadcrumb** - Main component that renders breadcrumb navigation
-- **Props Interface** - Accepts `items` array, `onItemClick` callback, and optional `className`
-- **Navigation Items** - Each breadcrumb segment is a clickable button with path and label
-- **Responsive Design** - Handles text wrapping and flexible layout for long paths
+- **`FileManagerBreadcrumb`** — Main exported component that maps over a `FileManagerBreadcrumbProps.items` array to render a `<nav>` with interactive path buttons
+- **`ChevronRight`** — Lucide icon injected as a separator between breadcrumb segments (omitted before the first item)
+- **`cn`** — Utility for conditional class merging
+
+## Props (`FileManagerBreadcrumbProps`)
+
+| Prop | Description |
+|------|-------------|
+| `items` | Array of breadcrumb segments, each with a `label` and `path` |
+| `onItemClick` | Optional callback invoked with the segment's `path` on click |
+| `className` | Optional additional class names applied to the `<nav>` element |
+
+## Behavior Notes
+
+- The **last item** receives `font-medium` styling to visually indicate the current location
+- All items use `break-all` to handle long path strings gracefully within wrapped layouts
+- Separators use `flex-shrink-0` to prevent chevrons from collapsing in tight spaces
 
 ## Usage Example
 
 ```typescript
 import { FileManagerBreadcrumb } from './file-manager-breadcrumb'
 
-const breadcrumbItems = [
-  { path: '/', label: 'Root' },
-  { path: '/documents', label: 'Documents' },
-  { path: '/documents/projects', label: 'Projects' }
+const breadcrumbs = [
+  { label: 'Home', path: '/' },
+  { label: 'Documents', path: '/documents' },
+  { label: 'Reports', path: '/documents/reports' },
 ]
 
-function FileExplorer() {
-  const handleBreadcrumbClick = (path: string) => {
-    // Navigate to the selected path
-    console.log('Navigating to:', path)
-  }
-
-  return (
-    <FileManagerBreadcrumb
-      items={breadcrumbItems}
-      onItemClick={handleBreadcrumbClick}
-      className="mb-4"
-    />
-  )
-}
-```
-
-The component features responsive text wrapping, hover states with color transitions, and highlights the current (last) item with bold text. Chevron separators between items provide clear visual hierarchy.
+<FileManagerBreadcrumb
+  items={breadcrumbs}
+  onItemClick={(path) => console.log('Navigate to:', path)}
+  className="px-4 py-2"
+/>
+```

package/src/components/ui/file-manager/.file-manager-context-menu.md

@@ -1,57 +1,53 @@
-<!-- source-hash: 5af3dcf0725a92a044da20c82a01d47a -->
-A React context menu component that provides standard file management operations like download, copy, rename, cut, and delete for file manager interfaces.
+<!-- source-hash: 2011101ea13458a40241b85da0182863 -->
+Context menu component for file manager operations, rendering a dropdown with context-sensitive actions based on file type and selection state.
 
 ## Key Components
 
-- **FileManagerContextMenu**: Main component that renders a dropdown menu with file operation actions
-- **menuItems**: Configuration array defining available actions with icons, labels, and visibility conditions
-- **Props Interface**: Accepts `FileManagerContextMenuProps` for customization and event handling
+**`FileManagerContextMenu`** — Main exported component that wraps a `DropdownMenu` with file-specific actions.
 
-## Features
+**Menu Actions** (conditionally shown):
 
-- **Dynamic Actions**: Shows/hides menu items based on file type and selection state
-- **Event Prevention**: Prevents menu clicks from bubbling up to parent elements
-- **Custom Trigger**: Supports custom trigger elements or defaults to a "more" icon button
-- **Conditional Rendering**: Filters menu items based on context (single file vs. multiple selection)
-- **Keyboard Accessible**: Built on shadcn/ui dropdown components with proper ARIA support
+| Action | Icon | Condition |
+|--------|------|-----------|
+| `download` | `Download` | File type or has selection |
+| `copy` | `Copy` | Always visible |
+| `rename` | `Edit2` | Single item only (no selection) |
+| `cut` | `Scissors` | Always visible |
+| `delete` | `Trash2` | Always visible (with separator) |
+
+**Props** (`FileManagerContextMenuProps`):
+
+| Prop | Description |
+|------|-------------|
+| `open` / `onOpenChange` | Controlled open state |
+| `onAction` | Callback receiving the action key |
+| `fileType` | `'file'` or `'folder'` — affects available actions |
+| `hasSelection` | Hides `rename`, shows `download` for multi-select |
+| `trigger` | Optional custom trigger element |
+| `className` | Additional classes for the dropdown content |
 
 ## Usage Example
 
 ```typescript
 import { FileManagerContextMenu } from './file-manager-context-menu'
 
-function FileItem({ file, isSelected }) {
-  const [menuOpen, setMenuOpen] = useState(false)
-
-  const handleAction = (action: string) => {
-    switch (action) {
-      case 'download':
-        downloadFile(file)
-        break
-      case 'copy':
-        copyToClipboard(file)
-        break
-      case 'rename':
-        setRenaming(true)
-        break
-      case 'delete':
-        deleteFile(file)
-        break
-    }
-    setMenuOpen(false)
-  }
+function FileRow({ file }) {
+  const [menuOpen, setMenuOpen] = React.useState(false)
 
   return (
-    <div className="file-item">
-      <span>{file.name}</span>
-      <FileManagerContextMenu
-        open={menuOpen}
-        onOpenChange={setMenuOpen}
-        onAction={handleAction}
-        fileType={file.type}
-        hasSelection={isSelected}
-      />
-    </div>
+    <FileManagerContextMenu
+      open={menuOpen}
+      onOpenChange={setMenuOpen}
+      fileType="file"
+      hasSelection={false}
+      onAction={(action) => {
+        if (action === 'delete') deleteFile(file.id)
+        if (action === 'rename') startRename(file.id)
+        if (action === 'download') downloadFile(file.id)
+      }}
+    />
   )
 }
-```
+```
+
+> The default trigger renders a `MoreHorizontal` icon button. Pass a custom `trigger` element to replace it. Click events use `stopPropagation` to prevent row selection conflicts.

package/src/components/ui/file-manager/.file-manager-empty.md

@@ -1,48 +1,35 @@
-<!-- source-hash: fc258d7342679da38471b42800515f84 -->
-A React component that displays an empty state UI for file manager interfaces when no files or folders are present.
+<!-- source-hash: fd21e114568a67d1874d4692f7a1d514 -->
+Empty state component for the File Manager UI, displaying a centered message with an icon when a folder contains no files or folders.
 
 ## Key Components
 
-- **FileManagerEmpty** - Main component that renders an empty state with icon, message, description, and optional action button
-- **Props Interface** - Uses `FileManagerEmptyProps` type for component configuration including custom messages and actions
-- **Styling** - Uses CSS utility classes with ODS (design system) tokens for consistent theming
-- **Icon Integration** - Leverages Lucide React's `FolderOpen` icon for visual context
+- **`FileManagerEmpty`** — React component that renders a centered empty state with a folder icon, heading, description text, and an optional action button
+
+### Props (`FileManagerEmptyProps`)
+
+| Prop | Default | Description |
+|------|---------|-------------|
+| `message` | `'No files or folders found'` | Primary heading text |
+| `description` | `'This folder is empty...'` | Secondary descriptive text |
+| `action` | `undefined` | Optional `{ label, onClick }` to render a call-to-action button |
+| `className` | `undefined` | Additional CSS classes for the wrapper |
 
 ## Usage Example
 
 ```typescript
 import { FileManagerEmpty } from './file-manager-empty'
 
-function FileExplorer() {
-  const handleCreateFolder = () => {
-    // Logic to create new folder
-    console.log('Creating new folder...')
-  }
-
-  return (
-    <div className="file-explorer">
-      <FileManagerEmpty
-        message="No documents found"
-        description="Upload your first document or create a new folder to organize your files."
-        action={{
-          label: "Create Folder",
-          onClick: handleCreateFolder
-        }}
-        className="min-h-96"
-      />
-    </div>
-  )
-}
-
-// Basic usage without action button
-function SimpleEmpty() {
-  return (
-    <FileManagerEmpty
-      message="Folder is empty"
-      description="No files have been uploaded to this location yet."
-    />
-  )
-}
-```
-
-The component provides a user-friendly empty state that guides users toward taking action, with customizable messaging and optional call-to-action buttons for improved user experience.
+// Basic usage
+<FileManagerEmpty />
+
+// With custom message and action
+<FileManagerEmpty
+  message="No documents yet"
+  description="Upload your first document to get started."
+  action={{
+    label: 'Upload File',
+    onClick: () => openUploadDialog()
+  }}
+  className="min-h-[400px]"
+/>
+```

package/src/components/ui/file-manager/.file-manager-table-row.md

@@ -1,49 +1,41 @@
-<!-- source-hash: 1d6639c72f3e41028b5b7f00d97ee6f4 -->
-A React component that renders a single row in a file manager table interface, displaying file/folder information with interactive capabilities like selection, context menus, and navigation.
+<!-- source-hash: 0825a14a4aea648af8873376f22c05eb -->
+A single table row component for the File Manager UI, rendering file/folder metadata with interactive selection, context menus, and navigation controls.
 
 ## Key Components
 
-- **FileManagerTableRow**: Main component that renders file/folder data in a table row format
-- **Interactive Elements**: Checkbox for selection, context menu button, and folder navigation chevron
-- **File Information Display**: Shows file icon, name, optional path, size, and modification date
-- **Event Handlers**: Manages clicks, double-clicks, context menu actions, and selection state
+### `FileManagerTableRow`
+The primary exported component that renders a horizontal row displaying:
+- **Checkbox** — optional selection toggle (guarded with `data-no-row-click`)
+- **FileIcon** — type/extension-aware icon with file name and optional path
+- **Metadata columns** — file size and last modified date
+- **Action controls** — `MoreHorizontal` context menu button (visible on hover) and a `ChevronRight` navigate-into button for folders
 
-## Usage Example
-
-```typescript
-import { FileManagerTableRow } from './file-manager-table-row'
+## Key Behaviors
 
-function FileList() {
-  const [selectedFiles, setSelectedFiles] = useState<string[]>([])
+| Behavior | Detail |
+|---|---|
+| `data-no-row-click` | Prevents checkbox and action buttons from bubbling clicks to the row handler |
+| Context menu | Managed via `contextMenuOpen` state; closes automatically after an action |
+| Folder vs file | Renders `ChevronRight` nav button for folders; renders an empty spacer `div` for files to preserve alignment |
+| File extension | Parsed from `file.name` for files; `undefined` for folders |
 
-  const handleFileSelect = (fileId: string, checked: boolean) => {
-    if (checked) {
-      setSelectedFiles(prev => [...prev, fileId])
-    } else {
-      setSelectedFiles(prev => prev.filter(id => id !== fileId))
-    }
-  }
+## Usage Example
 
-  return (
-    <div>
-      <FileManagerTableRow
-        file={{
-          id: '1',
-          name: 'document.pdf',
-          type: 'file',
-          size: '2.4 MB',
-          modified: '2024-01-15'
-        }}
-        isSelected={selectedFiles.includes('1')}
-        showCheckbox={true}
-        showPath={false}
-        onSelect={(checked) => handleFileSelect('1', checked)}
-        onClick={() => console.log('File clicked')}
-        onDoubleClick={() => console.log('File opened')}
-        onContextMenu={(e) => console.log('Context menu')}
-        onActionClick={(action) => console.log('Action:', action)}
-      />
-    </div>
-  )
-}
+```typescript
+<FileManagerTableRow
+  file={{
+    name: 'report.pdf',
+    type: 'file',
+    size: '2.4 MB',
+    modified: 'Jan 15, 2025',
+    path: '/documents/reports/report.pdf',
+  }}
+  isSelected={false}
+  showCheckbox={true}
+  showPath={true}
+  onSelect={(checked) => handleSelect(fileId, checked)}
+  onClick={() => handlePreview(file)}
+  onDoubleClick={() => handleOpen(file)}
+  onActionClick={(action) => handleFileAction(file, action)}
+/>
 ```

package/src/components/ui/file-manager/.file-manager.md

@@ -1,48 +1,52 @@
-<!-- source-hash: cfac1940c87a5497a0a75aa2796c2ab9 -->
-A comprehensive file manager component that provides a complete file browser interface with navigation, search, and file operations capabilities.
+<!-- source-hash: 1ed33038349c92c3847f382acdaaf4c5 -->
+A client-side React component that renders a full-featured file manager UI, combining breadcrumb navigation, an action bar, search input, and a file table into a single composable interface.
 
 ## Key Components
 
-- **FileManager** - Main component that orchestrates the file management interface
-- **Breadcrumb Navigation** - Cross-platform path handling (Windows/Unix) with clickable navigation
-- **Search Integration** - Built-in search bar with loading states and result counts
-- **File Operations** - Action bar with copy, cut, paste, upload, and new folder actions
-- **File Table** - Displays files with selection checkboxes and interactive operations
-- **Path Management** - Intelligent path handling for both Windows (`C:\path`) and Unix (`/path`) file systems
+- **`FileManager`** — Main exported component that orchestrates all sub-components
+- **`breadcrumbItems`** (`useMemo`) — Derives structured breadcrumb items from `currentPath`, handling both Unix (`/`) and Windows (`\`, drive letters) path formats
+- **`handleFolderOpen`** — Constructs the new navigation path when a folder is opened, respecting path separator conventions
+- **`handleBreadcrumbClick`** — Calls both `onBreadcrumbClick` and `onNavigate` callbacks on breadcrumb interaction
+- **Sub-components used:** `FileManagerBreadcrumb`, `FileManagerActionBar`, `FileManagerTable`, `Input`
+
+## Key Props
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `files` | `FileItem[]` | List of files/folders to display |
+| `currentPath` | `string` | Active directory path (Unix or Windows) |
+| `selectedFiles` | `string[]` | Array of selected file IDs |
+| `showCheckboxes` | `boolean` | Toggle selection checkboxes (default: `true`) |
+| `showSearch` | `boolean` | Toggle search input (default: `true`) |
+| `showActions` | `boolean` | Toggle action bar (default: `true`) |
+| `canPaste` | `boolean` | Enables paste action in action bar |
+| `onNavigate` | `(path: string) => void` | Called on folder open or breadcrumb click |
+| `onFileAction` | `(action: string) => void` | Handles copy, cut, paste, upload, new-folder |
 
 ## Usage Example
 
 ```typescript
 import { FileManager } from './file-manager'
 
-function App() {
-  const [files, setFiles] = useState([])
-  const [selectedFiles, setSelectedFiles] = useState<string[]>([])
-  const [currentPath, setCurrentPath] = useState('')
+function MyFileBrowser() {
+  const [currentPath, setCurrentPath] = useState('/')
+  const [selected, setSelected] = useState<string[]>([])
 
   return (
     <FileManager
-      files={files}
+      files={fileList}
       currentPath={currentPath}
-      selectedFiles={selectedFiles}
+      selectedFiles={selected}
       searchQuery=""
-      onNavigate={(path) => setCurrentPath(path)}
-      onSelectFile={(fileId, selected) => {
-        if (selected) {
-          setSelectedFiles(prev => [...prev, fileId])
-        } else {
-          setSelectedFiles(prev => prev.filter(id => id !== fileId))
-        }
-      }}
-      onFileAction={(action) => {
-        console.log('File action:', action)
-      }}
-      onSearch={(query) => {
-        // Implement search logic
-      }}
+      onNavigate={setCurrentPath}
+      onSelectFile={(id, checked) =>
+        setSelected(prev =>
+          checked ? [...prev, id] : prev.filter(f => f !== id)
+        )
+      }
+      onSelectAll={(all) => setSelected(all ? fileList.map(f => f.id) : [])}
+      onFileAction={(action) => console.log('Action:', action)}
     />
   )
 }
-```
-
-The component automatically generates breadcrumb navigation from the current path and handles both Windows drive letters and Unix-style paths. It provides a complete file management experience with customizable visibility for search, actions, and checkboxes.
+```