@flamingo-stack/openframe-frontend-core 0.0.481 → 0.0.482

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

@@ -1,48 +1,63 @@
-<!-- source-hash: 3ff43cdc4cea745588c40e71214b7483 -->
-Renders the body of a `DataTable` component, handling three states: loading skeleton, empty state, and populated rows with optional padding placeholders.
+<!-- source-hash: 101c8dc656e99322ce64f23baac27a3e -->
+Renders the body of a `DataTable` component, handling three states: loading skeleton, empty state, and populated rows — with optional row padding to maintain stable table height.
 
 ## Key Components
 
-| Export | Type | Description |
-|--------|------|-------------|
-| `DataTableBody` | Component | Main body renderer consuming `DataTableContext` |
-| `DataTableBodyProps` | Interface | Props interface with generic row type `T` |
+### `DataTableBody<T>`
+The primary export. Consumes `DataTableContext` via `useDataTableContext` and conditionally renders one of three views:
 
-### Key Props
+- **Loading:** Displays `DataTableSkeleton` when `loading={true}` and rows are empty
+- **Empty:** Renders `DataTableEmpty` using `emptyState` props (or falls back to deprecated `emptyMessage`)
+- **Rows:** Maps each row to a `DataTableRow`, with optional sub-row expansion via `renderSubRow`
 
-| Prop | Type | Description |
-|------|------|-------------|
-| `loading` | `boolean` | Shows skeleton rows when `true` and data is empty |
-| `skeletonRows` | `number` | Number of skeleton rows to render (default: `10`) |
-| `emptyMessage` | `string` | Message shown when data is empty (default: `'No data available'`) |
-| `minRows` | `number` | Pads with invisible rows to maintain stable table height |
-| `onRowClick` | `(item: T) => void` | Click handler for entire row (skips `data-no-row-click` elements) |
-| `rowHref` | `(item: T) => string` | Converts rows to `next/link` anchors; ignored if `onRowClick` is set |
-| `rowClassName` | `string \| ((item, index) => string)` | Per-row class; use `useCallback` to preserve `React.memo` |
-| `compact` | `boolean` | Enables dense row height |
+### `DataTableBodyProps<T>`
+Full interface for configuring body behavior including:
+
+| Prop | Purpose |
+|---|---|
+| `loading` | Triggers skeleton display when data is empty |
+| `emptyState` | `NoDataProps` for rich empty state UI |
+| `emptyMessage` | ⚠️ Deprecated — use `emptyState` instead |
+| `skeletonRows` | Number of skeleton rows (default: `10`) |
+| `rowClassName` | Static string or per-row function |
+| `onRowClick` | Row click handler (memoize with `useCallback`) |
+| `rowHref` | Converts rows to Next.js links (ignored if `onRowClick` set) |
+| `minRows` | Pads with invisible rows to stabilize table height |
+| `renderSubRow` | Returns expandable content rendered below a row |
 
 ## Usage Example
 
 ```typescript
 import { DataTable } from './data-table'
 import { DataTableBody } from './data-table-body'
-
-const handleRowClick = useCallback((item: MyItem) => {
-  router.push(`/items/${item.id}`)
-}, [])
-
-const getRowHref = useCallback((item: MyItem) => `/items/${item.id}`, [])
-
-<DataTable columns={columns} data={data}>
-  <DataTableBody<MyItem>
-    loading={isLoading}
-    skeletonRows={10}
-    minRows={10}
-    emptyMessage="No items found"
-    onRowClick={handleRowClick}
-    compact={false}
-  />
-</DataTable>
+import { DataTableColumn } from './data-table-column'
+import { useCallback } from 'react'
+
+function UserTable({ users, isLoading }) {
+  const handleRowClick = useCallback((user) => {
+    router.push(`/users/${user.id}`)
+  }, [])
+
+  const rowClassName = useCallback(
+    (user, index) => (index % 2 === 0 ? 'bg-muted/30' : ''),
+    []
+  )
+
+  return (
+    <DataTable data={users} columns={columns}>
+      <DataTableBody<User>
+        loading={isLoading}
+        skeletonRows={8}
+        minRows={8}
+        compact
+        onRowClick={handleRowClick}
+        rowClassName={rowClassName}
+        emptyState={{ title: 'No users found', description: 'Try adjusting your filters.' }}
+        renderSubRow={(user) => user.notes ? <UserNotes notes={user.notes} /> : null}
+      />
+    </DataTable>
+  )
+}
 ```
 
-> **Performance tip:** Always memoize `onRowClick`, `rowHref`, and function-form `rowClassName` with `useCallback` to preserve `React.memo` optimization on `DataTableRow`.
+> **Performance note:** Always memoize `onRowClick`, `rowHref`, and function-form `rowClassName` with `useCallback` to preserve `React.memo` optimizations on `DataTableRow`.

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

@@ -1,47 +1,31 @@
-<!-- source-hash: f96e91397f5dd889c77eca76b3638ae9 -->
-Empty state for data tables. Renders the shared `NoData` empty state, centered, defaulting to a "no search results" message. Every field is overridable.
+<!-- source-hash: 163304355d3ebe8ec3a835034f1a3713 -->
+Renders the empty state for `DataTable.Body` when no rows are present, delegating to the shared `NoData` component with "no search results" defaults.
 
 ## Key Components
 
-### `DataTableEmptyProps`
-Extends `NoDataProps` — accepts any `NoData` prop. The most common:
-
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `icon` | `ReactNode` | `<SearchIcon />` | Leading glyph |
-| `title` | `ReactNode` | `'No results found'` | Primary line |
-| `description` | `ReactNode` | `'Try adjusting your search or filters'` | Secondary line |
-| `actions` | `NoDataActionProps[]` | — | Optional info blocks |
-| `buttonLabel` / `button` | `ReactNode` | — | Optional footer button |
-| `className` | `string` | — | Merged onto the `NoData` wrapper |
-
-### `DataTableEmpty`
-A client component that renders `NoData` with the defaults above. Pass any field to override it.
+- **`DataTableEmpty`** — Client component that wraps `NoData`, pre-configured with a `SearchIcon`, title `"No results found"`, and description `"Try adjusting your search or filters"`. Applies `py-[var(--spacing-system-xxl)]` vertical padding by default.
+- **`DataTableEmptyProps`** — Re-exports all `NoDataProps` fields, making every visual element overridable.
 
 ## Usage Example
 
 ```typescript
-// Default — search icon, "No results found", "Try adjusting your search or filters"
+// Default empty state (search icon + default copy)
 <DataTableEmpty />
 
-// Override the copy
-<DataTableEmpty title="No tickets found" description="Create your first ticket" />
+// Override title and description only
+<DataTableEmpty
+  title="No devices found"
+  description="Add a device to get started"
+/>
 
-// Full empty state with blocks + button (all NoData props are accepted)
+// Full override with custom icon and action
 <DataTableEmpty
-  title="No devices yet"
-  description="Connect your first device to get started"
-  buttonLabel="Add device"
-  onButtonClick={() => router.push('/devices/new')}
+  icon={<ServerIcon />}
+  title="No servers available"
+  description="Provision a server to see it here"
+  buttonLabel="Add Server"
+  onButtonClick={handleAdd}
 />
 ```
 
-Usually you don't render `DataTableEmpty` directly — configure it through `DataTable.Body`:
-
-```typescript
-// New: pass any NoData props via `emptyState`
-<DataTable.Body emptyState={{ title: 'No devices yet', description: 'Add your first device' }} />
-
-// Legacy (deprecated): `emptyMessage` maps to the empty state's title
-<DataTable.Body emptyMessage="No devices match your filters" />
-```
+All props are passed through to [`NoData`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/src/components/no-data), so any `NoDataProps` field (`icon`, `title`, `description`, `actions`, `buttonLabel`, etc.) can be used to fully customise the empty state. The `className` prop merges with the default padding class via `cn`.

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

@@ -1,55 +1,58 @@
-<!-- source-hash: 7af4501b2005cad2efd91858dbef4eba -->
-Renders the sticky-capable column header row for a data table, including sort indicators, column filters, and an optional right-side slot.
+<!-- source-hash: 979b80e9c2663735843d09def1e09d24 -->
+Renders the column header row for a TanStack React Table data table, handling sorting indicators, column filters, responsive visibility, sticky positioning, and an optional right-side slot.
 
 ## Key Components
 
-### `DataTableHeader`
-Main exported component. Reads the table instance from context, renders a single header group row, and handles:
-- **Sticky positioning** via `stickyHeader` / `stickyHeaderOffset` props
-- **Responsive visibility** — hidden on mobile, shown from `md` breakpoint up
-- **Right slot** — absolutely positioned when visible header cells exist, inline otherwise
+### Interfaces
 
-### `DataTableSortState`
-```typescript
-interface DataTableSortState {
-  id: string    // column ID being sorted
-  desc: boolean // true = descending
-}
-```
-Stateless descriptor — the consumer owns the sort cycle and passes the current state down.
+- **`DataTableSortState`** — Sort descriptor `{ id: string, desc: boolean }` consumed by the header to render directional icons.
+- **`DataTableHeaderProps`** — Props for the public `DataTableHeader` component.
+
+### Exports
+
+- **`DataTableHeader`** — Main header component. Reads table state via `useDataTableContext`, maps header groups to `HeaderCell` instances, and handles sticky positioning and the `rightSlot`.
 
 ### Internal Components
 
-| Component | Purpose |
-|-----------|---------|
-| `HeaderCell` | Renders one column header — either a `DataTableColumnFilter` or a sortable/plain label |
-| `HeaderLabel` | Renders string headers with ODS typography; delegates render-function headers to `flexRender` |
-| `SortIcon` | Displays `↑`, `↓`, or a neutral swap icon based on current sort direction |
+| Component | Role |
+|---|---|
+| `HeaderCell` | Renders a single column header — either a `DataTableColumnFilter` (filterable columns) or a clickable sort label. Handles tablet breakpoint visibility via `meta.filter` and `meta.alwaysShowHeader`. |
+| `HeaderLabel` | Renders string headers with ODS typography styles, or delegates to `flexRender` for render-function/ReactNode headers. |
+| `SortIcon` | Renders `Arrow01UpIcon`, `Arrow01DownIcon`, or `SwitchVrIcon` based on current sort direction. |
+| `resolveHeaderLabel` | Utility that extracts a plain string label from a column definition for filter placement. |
 
 ## Usage Example
 
 ```typescript
-// Consumer owns the sort state and toggle cycle
-const [sort, setSort] = useState<DataTableSortState | null>(null)
-
-function handleSortChange(columnId: string) {
-  setSort(prev =>
-    prev?.id === columnId
-      ? prev.desc ? null : { id: columnId, desc: true }
-      : { id: columnId, desc: false }
+import { DataTableHeader } from './data-table-header'
+import { useState } from 'react'
+
+function MyTable() {
+  const [sort, setSort] = useState<{ id: string; desc: boolean } | null>(null)
+
+  function handleSortChange(columnId: string) {
+    setSort(prev =>
+      prev?.id === columnId
+        ? prev.desc
+          ? null               // none → asc → desc → none cycle
+          : { id: columnId, desc: true }
+        : { id: columnId, desc: false }
+    )
+  }
+
+  return (
+    <DataTable data={rows} columns={columns}>
+      <DataTableHeader
+        stickyHeader
+        stickyHeaderOffset="top-[56px]"
+        sort={sort}
+        onSortChange={handleSortChange}
+        rightSlot={<DataTable.RowCount itemName="device" />}
+      />
+      <DataTableBody />
+    </DataTable>
   )
 }
-
-<DataTable table={table}>
-  <DataTable.Header
-    stickyHeader
-    stickyHeaderOffset="top-[56px]"
-    sort={sort}
-    onSortChange={handleSortChange}
-    rightSlot={<DataTable.RowCount itemName="device" />}
-  />
-  <DataTable.Body />
-</DataTable>
 ```
 
-> **Note:** Sorting is opt-in per column via `meta.sortable = true` in the column definition. The component never calls TanStack's built-in sort APIs — all sort logic lives in the consumer.
+> **Note:** Sorting state and cycle logic are fully consumer-owned. The header renders sort indicators from the `sort` prop and fires `onSortChange` on click — it does not call TanStack's internal sort APIs.

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

@@ -1,47 +1,47 @@
-<!-- source-hash: bcf36c7fa76e89e4c5f5a36b1b5b7494 -->
-Renders a single data table row as either a navigable `<Link>` or a clickable `<div>`, with built-in click-bubbling control for nested interactive elements.
+<!-- source-hash: 3180bdfee27f541cd2cbf5aafc31dc6b -->
+Renders a single data table row as a styled card, supporting click handlers, link navigation, compact/auto-height sizing, and optional expandable sub-row content.
 
 ## Key Components
 
-| Export | Type | Description |
-|--------|------|-------------|
-| `DataTableRow` | `React.memo` component | Memoized row renderer wrapping `DataTableRowImpl` |
-| `DataTableRowProps<T>` | Interface | Typed props for row data, click handler, href, compact mode, and className |
-| `CellContent` | Internal component | Wraps primitive string/number values in default truncated text styling |
+- **`DataTableRow`** — Memoized row component (wraps `DataTableRowImpl`) that renders TanStack Table cells inside a rounded card. Exported as `memo`-wrapped but typed as the original generic function.
+- **`DataTableRowProps<T>`** — Props interface supporting `row`, `onClick`, `href`, `compact`, `autoHeight`, `className`, and `subRow`.
+- **`CellContent`** — Internal helper that wraps primitive (`string` | `number`) cell values in truncated, styled `<span>` elements; passes React node children through unchanged.
+- **`handleClick`** — Memoized click handler implementing the click-bubbling protocol: ignores events from portaled descendants outside the row DOM subtree and short-circuits on `[data-no-row-click]` elements.
 
 ## Click-Bubbling Protocol
 
-The row implements a `data-no-row-click` attribute contract. Any cell element that should **not** trigger row navigation or `onClick` must carry this attribute:
-
-```tsx
-// Column definition with opt-out buttons
-{
-  id: 'actions',
-  cell: ({ row }) => (
-    <div data-no-row-click className="flex gap-2 justify-end">
-      <Button onClick={() => edit(row.original)}>Edit</Button>
-    </div>
-  ),
-}
-```
-
-Portaled descendants (tooltips, dropdowns via `FloatingPortal`) are also safely ignored — clicks whose DOM target falls outside the row's `containerRef` are suppressed without needing `stopPropagation` at the source.
+Any interactive element inside a cell that should not trigger row navigation or `onClick` must carry the `data-no-row-click` attribute.
 
 ## Usage Example
 
 ```typescript
-// Clickable row (div mode)
-<DataTableRow
-  row={row}
-  onClick={(item) => console.log('Selected:', item)}
-  compact={false}
-/>
+import { DataTableRow } from './data-table-row'
+
+// Basic click handler
+<DataTableRow row={row} onClick={(item) => console.log(item)} />
+
+// Link mode (full-card anchor)
+<DataTableRow row={row} href={`/items/${row.original.id}`} />
 
-// Link mode — enables browser-native behaviours (right-click, Cmd+click, :visited)
+// Link mode with sub-row (link wraps cells only)
 <DataTableRow
   row={row}
-  href={`/tickets/${row.original.id}`}
+  href={`/items/${row.original.id}`}
+  subRow={<ExpandedDetail item={row.original} />}
 />
+
+// Column with action buttons (opt out of row click)
+const columns = [{
+  id: 'actions',
+  cell: ({ row }) => (
+    <div data-no-row-click className="flex gap-2 justify-end">
+      <Button onClick={() => edit(row.original)}>Edit</Button>
+    </div>
+  ),
+  meta: { width: 'w-[160px] shrink-0', align: 'right' },
+}]
 ```
 
-> **Performance note:** Pass stable references for `onClick` and `className` via `useCallback` / `useMemo` in the parent to avoid unnecessary re-renders in long lists. `href` and string `className` are compared by value automatically.
+## Source
+
+[`data-table-row.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/data-table-row.tsx)

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

@@ -1,25 +1,27 @@
-<!-- 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.
+<!-- source-hash: 6efeba8f22609f4cc9f714e98d390080 -->
+Extends TanStack Table's `ColumnMeta` interface with Flamingo-specific column configuration options, and exports shared filter/breakpoint types used across the data table system.
 
 ## 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` |
+### Types & Interfaces
 
-### `ColumnMeta` Augmented Fields
+- **`TailwindBreakpoint`** — Union type of supported responsive breakpoints: `'md' | 'lg' | 'xl' | '2xl'`
+- **`DataTableFilterOption`** — Shape for individual filter dropdown options, containing `id`, `label`, and `value` fields
 
-| Field | Type | Description |
-|-------|------|-------------|
+### `ColumnMeta` Module Augmentation
+
+Extends `@tanstack/react-table`'s `ColumnMeta` with:
+
+| Property | 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 |
+| `align` | `'left' \| 'center' \| 'right'` | Cell/header horizontal alignment |
+| `hideAt` | `TailwindBreakpoint \| TailwindBreakpoint[]` | Hide column at/below specified breakpoints |
+| `alwaysShowHeader` | `boolean` | Keep header visible on tablet even without a filter |
+| `filter` | `{ options, placement? }` | Renders a filter dropdown with provided options |
+| `sortable` | `boolean` | Opt-in sort indicator on header (default `false`) |
+| `cellClassName` | `string` | Extra classes on the body cell wrapper |
+| `headerClassName` | `string` | Extra classes on the header cell wrapper |
 
 ## Usage Example
 
@@ -32,22 +34,15 @@ const statusOptions: DataTableFilterOption[] = [
   { 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'],
-    },
-  },
+const columns: ColumnDef<MyRow>[] = [
   {
     accessorKey: 'status',
     meta: {
-      width: 'w-40',
+      width: 'w-32',
+      align: 'center',
+      hideAt: 'md',
+      sortable: true,
       filter: { options: statusOptions, placement: 'bottom-start' },
-      cellClassName: 'font-medium',
     },
   },
 ]

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

@@ -1,40 +1,32 @@
-<!-- source-hash: 10ec2f9a1b5237b3543c1a35d4d9d860 -->
-Renders a navigable breadcrumb trail for a file manager UI, displaying a series of clickable path segments separated by chevron icons.
+<!-- source-hash: 9574783e479f4ebba0f4fa88058e32c3 -->
+Renders a navigable breadcrumb trail for the file manager, displaying hierarchical path segments as clickable buttons separated by chevron icons.
 
 ## Key Components
 
-- **`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
+- **`FileManagerBreadcrumb`** — Main export; a `<nav>`-based breadcrumb component that maps over `items` to render path segments with `ChevronRight` separators.
+- **`FileManagerBreadcrumbProps`** — Type contract imported from `./types`, defining `items`, `onItemClick`, and `className` props.
 
 ## Usage Example
 
 ```typescript
 import { FileManagerBreadcrumb } from './file-manager-breadcrumb'
 
-const breadcrumbs = [
-  { label: 'Home', path: '/' },
+const breadcrumbItems = [
+  { label: 'Root', path: '/' },
   { label: 'Documents', path: '/documents' },
   { label: 'Reports', path: '/documents/reports' },
 ]
 
 <FileManagerBreadcrumb
-  items={breadcrumbs}
+  items={breadcrumbItems}
   onItemClick={(path) => console.log('Navigate to:', path)}
-  className="px-4 py-2"
+  className="my-2"
 />
-```
+```
+
+## Behavior Notes
+
+- The **last item** receives `font-medium` styling to visually indicate the current location.
+- `onItemClick` is optional (`?.`), so the component renders safely without a click handler.
+- Chevron separators are suppressed for the first item (`index > 0` guard).
+- Layout uses `flex-wrap` with `break-words`/`break-all` to handle long paths gracefully on narrow viewports.

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

@@ -1,35 +1,43 @@
-<!-- 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.
+<!-- source-hash: c654fe192ed6ffc14cb84c82b7282c99 -->
+Empty state component for the FileManager, displayed when a folder contains no files or folders.
 
 ## Key Components
 
-- **`FileManagerEmpty`** — React component that renders a centered empty state with a folder icon, heading, description text, and an optional action button
+- **`FileManagerEmpty`** — A centered empty state UI with an icon, heading, description text, and an optional call-to-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 |
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `message` | `string` | `'No files or folders found'` | Primary heading text |
+| `description` | `string` | `'This folder is empty...'` | Secondary descriptive text |
+| `action` | `{ label: string; onClick: () => void }` | — | Optional CTA button |
+| `className` | `string` | — | Additional CSS classes |
 
 ## Usage Example
 
 ```typescript
 import { FileManagerEmpty } from './file-manager-empty'
 
-// Basic usage
+// Basic usage (defaults only)
 <FileManagerEmpty />
 
 // With custom message and action
 <FileManagerEmpty
-  message="No documents yet"
-  description="Upload your first document to get started."
+  message="No results found"
+  description="Try adjusting your search or filters."
   action={{
-    label: 'Upload File',
-    onClick: () => openUploadDialog()
+    label: 'Upload Files',
+    onClick: () => handleUpload(),
   }}
   className="min-h-[400px]"
 />
-```
+```
+
+## Notes
+
+- Renders a `FolderOpen` icon (Lucide) inside a circular surface background.
+- The `action` button uses the `accent` variant — omit the `action` prop to render a read-only empty state.
+- Styled with ODS design tokens (`ods-bg-surface`, `ods-text-primary`, etc.) ensuring theme consistency.
+
+**Source:** [`src/.../file-manager-empty.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/src/components/file-manager/file-manager-empty.tsx)

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

@@ -1,48 +1,46 @@
-<!-- source-hash: 05e59ea279144fca6adcd04242dcc8e9 -->
-A loading placeholder component that displays skeleton screens while file manager content loads, mimicking the layout and structure of a complete file management interface.
+<!-- source-hash: 8a43f94f3fffd8913ecdd7156f0dd6c9 -->
+Loading state skeleton component for a file manager UI, rendering placeholder shimmer elements that mirror the layout of breadcrumbs, search bar, table headers, and file rows.
 
 ## Key Components
 
-- **FileManagerSkeleton** - Main component that renders animated skeleton placeholders
-- **FileManagerSkeletonProps** - Interface defining customization options:
-  - `rows` - Number of file rows to display (default: 8)
-  - `showSearch` - Whether to show search bar skeleton (default: true)
-  - `showActions` - Whether to show action buttons skeleton (default: true)
+### `FileManagerSkeleton`
 
-The component renders skeleton placeholders for:
-- Breadcrumb navigation with separator icons
-- Action button toolbar (upload, create folder, etc.)
-- Search bar
-- Table header with column labels (NAME, SIZE, EDITED)
-- File/folder rows with checkboxes, icons, names, metadata, and action buttons
+Main exported component that composes multiple `Skeleton` primitives into a full file manager loading state.
+
+**Props (`FileManagerSkeletonProps`):**
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `rows` | `number` | `8` | Number of placeholder file rows to render |
+| `showSearch` | `boolean` | `true` | Toggles the search bar skeleton |
+| `showActions` | `boolean` | `true` | Toggles the action buttons skeleton in the toolbar |
+
+**Rendered regions:**
+- **Breadcrumb bar** — three path segment skeletons with separator dots
+- **Action buttons** — four button-sized skeletons (conditionally rendered)
+- **Search bar** — full-width rounded input skeleton (conditionally rendered)
+- **Table header** — checkbox, NAME, SIZE, and EDITED column labels
+- **Table rows** — `rows` × row with checkbox, file icon, name, size, modified date, and two icon-button skeletons
 
 ## Usage Example
 
 ```typescript
-import { FileManagerSkeleton } from './components/ui/file-manager-skeleton'
+import { FileManagerSkeleton } from '@/components/file-manager-skeleton'
 
-// Basic usage with defaults
-function LoadingFileManager() {
-  return <FileManagerSkeleton />
-}
+// Default: 8 rows, search and actions visible
+<FileManagerSkeleton />
 
-// Customized skeleton
-function CustomLoadingFileManager() {
-  return (
-    <FileManagerSkeleton 
-      rows={12}
-      showSearch={false}
-      showActions={true}
-    />
-  )
-}
+// Minimal: 5 rows, no search bar, no action buttons
+<FileManagerSkeleton rows={5} showSearch={false} showActions={false} />
 
-// Conditional loading state
-function FileManagerView({ isLoading, files }) {
-  if (isLoading) {
-    return <FileManagerSkeleton rows={files?.length || 8} />
-  }
-  
-  return <FileManager files={files} />
+// Typically used inside a Suspense boundary or conditional render
+function FileManagerPage() {
+  return isLoading
+    ? <FileManagerSkeleton rows={10} />
+    : <FileManager files={files} />
 }
-```
+```
+
+## Source
+
+[`file-manager-skeleton.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/file-manager-skeleton.tsx)