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

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

@@ -1,41 +1,41 @@
-<!-- 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.
+<!-- source-hash: f3ccd540c7acf6c008d5b4be2c760260 -->
+Renders a single interactive row in a file manager table, displaying file/folder metadata with selection, context menu, and navigation controls.
 
 ## Key Components
 
-### `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
-
-## Key Behaviors
-
-| 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 |
+- **`FileManagerTableRow`** — Primary export; a client-side React component that renders a row with checkbox, file icon, name, optional path, size, modified date, and action controls
+- **`FileManagerContextMenu`** — Dropdown menu triggered by the `MoreHorizontal` button, scoped to the row's file type
+- **`FileIcon`** — Displays a type/extension-aware icon alongside the file name
+- **`data-no-row-click`** — Attribute used to prevent checkbox and action button clicks from bubbling to the row's `onClick` handler
 
 ## Usage Example
 
 ```typescript
+import { FileManagerTableRow } from './file-manager-table-row'
+
+const file = {
+  name: 'quarterly-report.pdf',
+  type: 'file',
+  size: '2.4 MB',
+  modified: 'Jan 15, 2025',
+  path: '/documents/reports/',
+}
+
 <FileManagerTableRow
-  file={{
-    name: 'report.pdf',
-    type: 'file',
-    size: '2.4 MB',
-    modified: 'Jan 15, 2025',
-    path: '/documents/reports/report.pdf',
-  }}
+  file={file}
   isSelected={false}
   showCheckbox={true}
   showPath={true}
-  onSelect={(checked) => handleSelect(fileId, checked)}
-  onClick={() => handlePreview(file)}
-  onDoubleClick={() => handleOpen(file)}
-  onActionClick={(action) => handleFileAction(file, action)}
+  onSelect={(checked) => console.log('selected:', checked)}
+  onClick={() => console.log('row clicked')}
+  onDoubleClick={() => console.log('open file')}
+  onContextMenu={(e) => console.log('context menu', e)}
+  onActionClick={(action) => console.log('action:', action)}
 />
-```
+```
+
+## Behavior Notes
+
+- Folder rows render a `ChevronRight` navigation button that triggers `onDoubleClick`; file rows render a spacer div to preserve column alignment
+- The context menu (`MoreHorizontal` button) is hidden by default and fades in on row hover via Tailwind's `group-hover:opacity-100`
+- Row background shifts to `ods-bg-surface` when `isSelected` is `true`

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

@@ -1,13 +1,29 @@
-<!-- source-hash: ad987af7f1e6c7d598ca698076c8ebdb -->
-A React component that renders a file browser table with selection, loading states, and responsive height management for file management interfaces.
+<!-- source-hash: 58a15193962e4b16a60c090f4b5422d2 -->
+A client-side React component that renders a file manager table with selection, loading skeleton states, and dynamic height calculation.
 
 ## Key Components
 
-- **FileManagerTable** - Main table component with header, rows, and selection controls
-- **Dynamic height calculation** - Uses `useLayoutEffect` to calculate optimal table height based on viewport
-- **Selection management** - Handles individual file selection and "select all" functionality with checkbox states
-- **Loading skeleton** - Renders skeleton placeholders during data fetching
-- **Responsive layout** - Fixed column widths with flexible name column and overflow handling
+- **`FileManagerTable`** — Main exported component that handles file listing, multi-select, and adaptive layout
+- **`allSelected` / `someSelected`** — Memoized booleans driving the header checkbox's checked/indeterminate state
+- **`useLayoutEffect` + `ResizeObserver`** — Dynamically calculates and updates the table height to fill available viewport space below its top offset
+- **Skeleton loading state** — Renders 8 placeholder rows with shimmer UI when `loading` is `true`
+- **`FileManagerEmpty`** — Rendered when `files.length === 0`
+- **`FileManagerTableRow`** — Per-row component receiving selection, click, double-click, and action handlers
+
+## Props (`FileManagerTableProps`)
+
+| Prop | Description |
+|---|---|
+| `files` | Array of file/folder items to display |
+| `selectedFiles` | Array of selected file IDs |
+| `showCheckboxes` | Toggle selection checkboxes (default: `true`) |
+| `loading` | Shows skeleton UI when `true` (default: `false`) |
+| `isSearchResult` | Renders file path subtitles and changes click behavior |
+| `onSelectFile` | Called with `(id, selected)` on row checkbox change |
+| `onSelectAll` | Called with `(checked)` on header checkbox change |
+| `onFileClick` | Called on single-click (search result mode) |
+| `onFolderOpen` | Called when a folder row is clicked or double-clicked |
+| `onFileAction` | Called with `(action, fileId)` on action button interaction |
 
 ## Usage Example
 
@@ -15,32 +31,31 @@ A React component that renders a file browser table with selection, loading stat
 import { FileManagerTable } from './file-manager-table'
 
 function MyFileManager() {
-  const [files, setFiles] = useState([])
   const [selectedFiles, setSelectedFiles] = useState<string[]>([])
-  const [loading, setLoading] = useState(true)
+
+  const handleSelectFile = (id: string, selected: boolean) => {
+    setSelectedFiles(prev =>
+      selected ? [...prev, id] : prev.filter(f => f !== id)
+    )
+  }
+
+  const handleSelectAll = (checked: boolean) => {
+    setSelectedFiles(checked ? files.map(f => f.id) : [])
+  }
 
   return (
     <FileManagerTable
       files={files}
       selectedFiles={selectedFiles}
-      loading={loading}
-      showCheckboxes={true}
+      loading={false}
       isSearchResult={false}
-      onSelectFile={(fileId, selected) => {
-        setSelectedFiles(prev => 
-          selected ? [...prev, fileId] : prev.filter(id => id !== fileId)
-        )
-      }}
-      onSelectAll={(checked) => {
-        setSelectedFiles(checked ? files.map(f => f.id) : [])
-      }}
-      onFileClick={(file) => console.log('File clicked:', file)}
-      onFolderOpen={(folder) => console.log('Folder opened:', folder)}
-      onFileAction={(action, fileId) => console.log(action, fileId)}
-      className="h-full"
+      onSelectFile={handleSelectFile}
+      onSelectAll={handleSelectAll}
+      onFolderOpen={(folder) => console.log('Open folder', folder.id)}
+      onFileAction={(action, id) => console.log(action, id)}
     />
   )
 }
 ```
 
-The component automatically handles responsive height calculations, skeleton loading states, and provides a clean table interface with NAME, SIZE, and EDITED columns.
+**Source:** [`file-manager-table.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/file-manager-table.tsx)

package/src/components/ui/no-data/.index.md

@@ -0,0 +1,22 @@
+<!-- source-hash: 6d0d61c6e67ca5c8a7f92541dd1a1831 -->
+Barrel export file that re-exports all public members from the `no-data` component module and its sub-modules.
+
+## Key Components
+
+| Export | Source |
+|---|---|
+| `no-data` | Core no-data component |
+| `no-data-message` | Message sub-component |
+| `no-data-actions` | Actions sub-component |
+| `no-data-styles` | Style utilities/constants |
+
+## Usage Example
+
+```typescript
+// Import any no-data exports from a single entry point
+import {
+  NoData,
+  NoDataMessage,
+  NoDataActions,
+} from "@/components/no-data"
+```

package/src/components/ui/no-data/.no-data-actions.md

@@ -0,0 +1,29 @@
+<!-- source-hash: fcf30ffdd2b06689272d48ed99f209b0 -->
+Renders a grouped panel of static info blocks for empty-state UI, each displaying an optional icon alongside a short label.
+
+## Key Components
+
+- **`NoDataAction`** — A single presentational info block with an optional leading icon and label. Lays out icon-beside-label on mobile and icon-above-label on `md+` screens. Capped at 224px wide on larger viewports.
+- **`NoDataActions`** — A container that groups multiple `NoDataAction` blocks into a shared bordered panel. Renders as a vertical stack on mobile (horizontal dividers) and a horizontal row on `md+` (vertical dividers). Accepts blocks via the `actions` prop or as `children`.
+- **`NoDataActionsVariant`** — Re-exported type controlling the surface treatment of the group panel (e.g. `"outline"`).
+
+## Usage Example
+
+```typescript
+// Using the `actions` prop
+<NoDataActions
+  variant="outline"
+  actions={[
+    { icon: <SearchIcon />, label: "No results found" },
+    { icon: <FilterIcon />, label: "Try adjusting your filters" },
+  ]}
+/>
+
+// Using children directly
+<NoDataActions variant="outline">
+  <NoDataAction icon={<SearchIcon />} label="No results found" />
+  <NoDataAction icon={<FilterIcon />} label="Try adjusting your filters" />
+</NoDataActions>
+```
+
+Both components forward refs and accept standard `HTMLDivElement` attributes. `NoDataAction` omits the native `title` attribute to avoid conflicts with the `label` prop.

package/src/components/ui/no-data/.no-data-message.md

@@ -0,0 +1,37 @@
+<!-- source-hash: c900a3b18fe6d2568dc0305630bbed03 -->
+Presentational component that renders a centered, muted empty-state block composed of an optional icon, title, and description.
+
+## Key Components
+
+- **`NoDataMessage`** — A `forwardRef` div that vertically stacks an icon, a primary title line, and a secondary description line. All three slots are optional, enabling reduced forms such as icon-only or title-only displays.
+- **`NoDataMessageProps`** — Extends `React.HTMLAttributes<HTMLDivElement>` (with `title` omitted to avoid conflicts) and adds `icon`, `title`, and `description` as optional `ReactNode` props.
+
+## Usage Example
+
+```typescript
+import { NoDataMessage } from "./no-data-message"
+import { SearchIcon } from "lucide-react"
+
+// Full form: icon + title + description
+<NoDataMessage
+  icon={<SearchIcon />}
+  title="No results found"
+  description="Try adjusting your filters or search query."
+/>
+
+// Reduced form: title only
+<NoDataMessage title="No data available" />
+
+// With additional className
+<NoDataMessage
+  icon={<SearchIcon />}
+  title="Nothing here yet"
+  className="my-8"
+/>
+```
+
+## Notes
+
+- Icon is wrapped in a `<span>` styled via `noDataIconClasses` (16px mobile / 24px md+).
+- Title renders at `text-h4`; description renders at `text-h6`; both use `break-words` to handle long strings gracefully.
+- The wrapper uses `text-ods-text-secondary` for muted gray coloring and accepts all standard `div` HTML attributes via prop spreading.

package/src/components/ui/no-data/.no-data-styles.md

@@ -0,0 +1,39 @@
+<!-- source-hash: d6a633bbb5664eb878fc526683cbcdda -->
+Shared style atoms for the `NoData` (empty-state) component family, providing a single source of truth for icon sizing and info-block container surface styles via CVA variants.
+
+## Key Components
+
+- **`noDataIconClasses`** — Static class string that sizes the leading icon glyph (`16px` mobile, `24px` on `md+`) using `[&_svg]` selectors. Color is intentionally omitted so the icon inherits the current text color.
+- **`noDataActionsVariants`** — CVA factory for the info-block group container. Currently exposes a single `outline` variant: a transparent, bordered, rounded panel with `overflow-hidden` to keep inner blocks square.
+- **`NoDataActionsVariant`** — Extracted union type of valid `variant` values for `noDataActionsVariants`, useful for prop typing in consumer components.
+
+## Usage Example
+
+```typescript
+import {
+  noDataIconClasses,
+  noDataActionsVariants,
+  type NoDataActionsVariant,
+} from "./no-data-styles"
+
+// Apply icon sizing to any SVG-bearing element
+<span className={noDataIconClasses}>
+  <SearchIcon />
+</span>
+
+// Resolve container classes (defaults to "outline" variant)
+<div className={noDataActionsVariants()}>
+  {/* info blocks */}
+</div>
+
+// Explicitly pass a variant
+const variant: NoDataActionsVariant = "outline"
+<div className={noDataActionsVariants({ variant })}>
+  {/* info blocks */}
+</div>
+```
+
+## Notes
+
+- The `outline` variant is the default; new surface looks (e.g. `ghost`, `filled`) can be added to the `variants` map without modifying consuming markup.
+- `overflow-hidden` on the container ensures only the outermost wrapper has rounded corners — inner sibling blocks remain square-cornered.

package/src/components/ui/no-data/.no-data.md

@@ -0,0 +1,59 @@
+<!-- source-hash: 3ac6cf66b806617bd33317e53dcb1dda -->
+Composable empty-state panel component that renders a centered layout combining an optional icon/title/description message, clickable action blocks, and a footer button — each region rendered only when its inputs are provided.
+
+## Key Components
+
+| Export | Type | Description |
+|--------|------|-------------|
+| `NoData` | `React.ForwardRefExoticComponent` | Main empty-state container component |
+| `NoDataProps` | `interface` | Props extending `HTMLDivElement` attributes |
+
+### Props
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `icon` | `React.ReactNode` | Leading glyph (16px mobile / 24px md+) |
+| `title` | `React.ReactNode` | Primary message line |
+| `description` | `React.ReactNode` | Secondary message line |
+| `actions` | `NoDataActionProps[]` | Clickable block items; hidden when empty |
+| `buttonLabel` | `React.ReactNode` | Footer button label text |
+| `buttonIcon` | `React.ReactNode` | Footer button leading icon |
+| `onButtonClick` | `ButtonProps["onClick"]` | Footer button click handler |
+| `buttonProps` | `Partial<ButtonProps>` | Extra props forwarded to the footer button |
+| `button` | `React.ReactNode` | Fully custom footer node; overrides `buttonLabel`/`buttonIcon` |
+
+## Usage Example
+
+```typescript
+import { NoData } from "./no-data"
+import { SearchIcon } from "lucide-react"
+
+// Minimal — message only
+<NoData
+  icon={<SearchIcon />}
+  title="No results found"
+  description="Try adjusting your search filters."
+/>
+
+// Full layout — message + actions + footer button
+<NoData
+  icon={<SearchIcon />}
+  title="No devices found"
+  description="Add a device to get started."
+  actions={[
+    { label: "Import CSV", onClick: handleImport },
+    { label: "Sync from RMM", onClick: handleSync },
+  ]}
+  buttonLabel="Add Device"
+  buttonIcon={<PlusIcon />}
+  onButtonClick={handleAdd}
+/>
+
+// Custom footer node
+<NoData
+  title="Nothing here yet"
+  button={<MyCustomButton />}
+/>
+```
+
+Regions are conditionally rendered — `hasMessage` and `hasActions` guards ensure no empty wrappers are mounted. The footer `button` prop takes full precedence over the `buttonLabel`/`buttonIcon` convenience path.

package/src/components/ui/page-actions.tsx

@@ -16,7 +16,8 @@ export type PageActionButton = {
   /** Click handler. Optional when `href` or `submenu` is provided. */
   onClick?: () => void
   icon?: React.ReactNode
-  variant?: ButtonProps['variant']
+  /** `overlay` is media chrome only — SplitButton has no divider colour for it. */
+  variant?: Exclude<ButtonProps['variant'], 'overlay' | 'glyph'>
   disabled?: boolean
   /**
    * For SplitButton actions (when `iconAction` is set): disables only the main

package/src/components/ui/query-report-table/.query-report-table-header.md

@@ -1,18 +1,18 @@
-<!-- source-hash: 51f59ce973c05b3bf63e194d662e8fdd -->
-Renders the header row for a query report table, displaying column names with overflow-aware tooltips for truncated labels.
+<!-- source-hash: b24897cd7f950e9b9cb94d49064c64a2 -->
+Renders the header row for a query report table, displaying column labels with truncation detection and tooltip support for overflowing text.
 
 ## Key Components
 
-- **`QueryReportTableHeader`** — Main exported component that renders a row of column header cells, supporting `default` and `compact` layout variants
-- **`TruncatedHeaderCell`** — Internal component that detects text overflow on hover and conditionally shows a tooltip with the full column name
+- **`QueryReportTableHeader`** — Primary exported component. Accepts a list of column names and renders them as a styled header row. Supports `default` and `compact` variants.
+- **`TruncatedHeaderCell`** *(internal)* — Renders an individual header cell that dynamically checks whether its text is truncated on hover, showing a tooltip with the full value when needed.
 
 ## Props (`QueryReportTableHeaderProps`)
 
 | Prop | Type | Description |
-|------|------|-------------|
-| `columns` | `string[]` | List of column names to render |
-| `columnWidth` | `number` | Fixed pixel width applied to each header cell |
-| `variant` | `'default' \| 'compact'` | Layout variant; `compact` adds vertical padding and a bottom border |
+|---|---|---|
+| `columns` | `string[]` | Column label strings to render |
+| `columnWidth` | `number` | Fixed pixel width for each header cell |
+| `variant` | `'default' \| 'compact'` | Controls padding and border styling |
 | `className` | `string` | Optional additional CSS classes |
 
 ## Usage Example
@@ -21,16 +21,16 @@ Renders the header row for a query report table, displaying column names with ov
 import { QueryReportTableHeader } from './query-report-table-header'
 
 <QueryReportTableHeader
-  columns={['hostname', 'ip_address', 'os_version', 'last_seen']}
+  columns={['Device Name', 'IP Address', 'Last Seen', 'Status']}
   columnWidth={160}
   variant="compact"
-  className="bg-ods-bg-surface"
 />
 ```
 
-## Behavior Notes
+## Notes
 
-- Column widths are fixed (`shrink-0`) to align with table body cells
-- Truncation is detected lazily on `mouseEnter` by comparing `scrollWidth` vs `clientWidth`, avoiding unnecessary DOM reads on render
-- Tooltips are suppressed (`open={false}`) when the text is not truncated, preventing empty tooltip flashes
-- Column labels are styled in uppercase monospace with secondary text color (`text-ods-text-secondary`)
+- Truncation is evaluated lazily on `mouseEnter` via `scrollWidth` vs `clientWidth` comparison — avoiding unnecessary layout reads on initial render.
+- Tooltip is only activated when truncation is detected; otherwise the `Tooltip` is forced closed (`open={false}`), preventing phantom popups on short labels.
+- Each cell uses `shrink-0` with a fixed `width` and `height: 48` to align with table body cells.
+
+**Source:** [`query-report-table-header.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/query-report-table-header.tsx)

package/src/components/ui/query-report-table/.query-report-table-row.md

@@ -1,40 +1,40 @@
-<!-- source-hash: 18d5b9d31dbc725bcee2ec71984e3fd7 -->
-Renders a single data row in a query report table, supporting `default` and `compact` visual variants with automatic tooltip display for truncated cell content.
+<!-- source-hash: ec4a69e77e3094a0c885d241053bbfce -->
+Renders a single data row in the `QueryReportTable`, supporting both `default` (card-style) and `compact` (flat list) visual variants with truncation-aware tooltips on overflow.
 
 ## Key Components
 
-- **`QueryReportTableRow`** — Main row component that maps over `columns` to render each cell with consistent width, spacing, and typography based on the active `variant`.
-- **`TruncatedCell`** — Internal component that detects text overflow on mouse enter and conditionally shows a tooltip with the full value when the content is truncated.
+- **`QueryReportTableRow`** — Primary export. Maps over `columns` to render each cell with a fixed `columnWidth`, handling `null`/`undefined` values as `'-'`. Applies variant-specific layout (`80px` height for `default`, `56px` for `compact`).
+- **`TruncatedCell`** *(internal)* — Wraps cell text in a `<span>` with CSS truncation. Uses `scrollWidth > clientWidth` detection on `mouseenter` to conditionally activate a tooltip showing the full value.
 
 ## Usage Example
 
 ```typescript
 import { QueryReportTableRow } from './query-report-table-row'
 
-const columns = ['name', 'status', 'ticket']
-const row = { name: 'Workstation backup failed', status: 'Open', ticket: 'TKT-4821' }
+const row = { name: 'Acme Corp', status: 'Active', tickets: 42 }
+const columns = ['name', 'status', 'tickets']
 
-// Default (card-style) variant
+// Default (card) variant
 <QueryReportTableRow
   row={row}
   columns={columns}
-  columnWidth="200px"
-  variant="default"
+  columnWidth="160px"
 />
 
-// Compact (table-row-style) variant
+// Compact (flat list) variant
 <QueryReportTableRow
   row={row}
   columns={columns}
-  columnWidth="200px"
+  columnWidth="160px"
   variant="compact"
-  className="my-custom-class"
 />
 ```
 
 ## Behavior Notes
 
-- `null` or `undefined` cell values render as `"-"`.
-- Truncation detection is lazy — checked only on `mouseEnter` to avoid unnecessary DOM reads on render.
-- Tooltip is suppressed entirely when text fits within its container (`open={false}`), preventing empty tooltip flashes.
-- Column widths are applied via inline `style` to support dynamic values from parent layout logic.
+| Concern | Detail |
+|---|---|
+| Null handling | `null` / `undefined` values render as `'-'` |
+| Tooltip activation | Only shown when text is actually truncated (lazy-checked on hover) |
+| Tooltip delay | 300 ms via `delayDuration` to avoid flicker on quick mouse passes |
+| Styling | Driven by `cn()` utility; accepts an optional `className` override |

package/src/components/ui/query-report-table/.query-report-table.md

@@ -1,47 +1,62 @@
-<!-- source-hash: bedf0eba103ca6d913d9e320399c3706 -->
+<!-- source-hash: a98f69d0dc6115c54bf6524937839699 -->
 A data table component for displaying query results with horizontal scrolling, CSV export, loading skeletons, and empty states.
 
 ## Key Components
 
-- **`QueryReportTable`** — Main export. Renders a full-featured data table driven by an array of row objects, with automatic column derivation from data keys.
-- **`deriveColumns`** — Utility that infers column definitions from data and an optional `columnOrder` array.
-- **`exportToCSV`** — Utility that serializes table data to a downloadable CSV file.
-- **`useHorizontalScrollbar`** — Hook providing custom scrollbar state and event handlers (thumb drag, track click, edge fades).
-- **`QueryReportTableHeader`** / **`QueryReportTableRow`** / **`QueryReportTableSkeleton`** — Sub-components for the header, data rows, and loading state respectively.
-
-## Props Overview
-
-| Prop | Default | Description |
-|------|---------|-------------|
-| `data` | — | Array of row objects to display |
-| `loading` | `false` | Shows skeleton rows when `true` |
-| `variant` | `'default'` | `'default'` or `'compact'` — hides title bar, scrollbar, and edge fades in compact mode |
-| `columnOrder` | — | Optional array to control column ordering |
-| `showExport` | `true` | Renders an "Export CSV" button |
-| `columnWidth` | `160` | Per-column width in pixels |
-| `headerActions` | — | Slot for additional header controls |
+- **`QueryReportTable`** — Main export. Renders a full-featured tabular report view driven by dynamic row data, with automatic column derivation.
+- **`deriveColumns`** — Utility that infers column definitions from data rows and optional `columnOrder`.
+- **`exportToCSV`** — Utility that serializes visible columns and rows to a downloadable CSV file.
+- **`useHorizontalScrollbar`** — Custom hook providing scroll position tracking, thumb/track refs, and pointer event handlers for a custom horizontal scrollbar.
+- **`QueryReportTableHeader`** / **`QueryReportTableRow`** / **`QueryReportTableSkeleton`** — Sub-components for header, body rows, and loading state respectively.
+
+## Props Summary
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `data` | `object[]` | — | Row data; columns auto-derived |
+| `loading` | `boolean` | `false` | Shows skeleton rows |
+| `variant` | `'default' \| 'compact'` | `'default'` | Compact hides title bar, scrollbar, and edge fades |
+| `showExport` | `boolean` | `true` | Renders "Export CSV" button when data exists |
+| `columnOrder` | `string[]` | — | Override auto-derived column order |
+| `columnWidth` | `number` | `160` | Per-column pixel width (also drives `minWidth`) |
+| `exportFilename` | `string` | `'query-results'` | Base filename for CSV download |
+| `onExport` | `() => void` | — | Callback fired after CSV export |
+| `headerActions` | `ReactNode` | — | Slot for custom controls in the title bar |
 
 ## Usage Example
 
 ```typescript
-import { QueryReportTable } from './query-report-table'
+import { QueryReportTable } from '@/components/query-report-table'
 
 const rows = [
-  { device: 'DESKTOP-01', os: 'Windows 11', status: 'Online' },
-  { device: 'LAPTOP-22',  os: 'macOS 14',   status: 'Offline' },
+  { device: 'DESKTOP-001', os: 'Windows 11', status: 'Online' },
+  { device: 'LAPTOP-042', os: 'macOS 14',   status: 'Offline' },
 ]
 
-export function ReportPage() {
+export function DeviceReport() {
   return (
     <QueryReportTable
-      title="Device Report"
+      title="Device Inventory"
       data={rows}
       columnOrder={['device', 'os', 'status']}
       exportFilename="device-report"
       onExport={() => console.log('exported')}
+      showExport
     />
   )
 }
 ```
 
-In `compact` mode the title bar, custom scrollbar, and edge-fade overlays are suppressed — useful for embedding the table inside a card or modal without extra chrome.
+**Compact mode** (no title bar, scrollbar, or edge gradients):
+
+```typescript
+<QueryReportTable
+  data={rows}
+  variant="compact"
+  showExport={false}
+/>
+```
+
+## Source
+
+[`query-report-table.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/query-report-table.tsx)

package/src/components/ui/table/.table-column-filter-dropdown.md

@@ -1,21 +1,23 @@
-<!-- source-hash: 24edd509d1d4422049647e46332e05ae -->
-A deprecated column-level filter dropdown component that renders a clickable label with a filter icon, wiring a `FiltersDropdown` to manage checkbox-based filter state for a single table column.
+<!-- source-hash: 25bda079705407fd6be62624468764ab -->
+Renders a deprecated column-level filter dropdown for tables, wrapping `FiltersDropdown` with a labeled trigger button and checkbox-based filter sections.
 
 ## Key Components
 
 ### `TableColumnFilterDropdownProps`
 | Prop | Type | Description |
-|------|------|-------------|
+|---|---|---|
 | `columnKey` | `string` | Key used to read/write filter state |
 | `columnLabel` | `string` | Display label and accessibility text |
-| `filterOptions` | `FilterOption[]` | Available checkbox options |
+| `filterOptions` | `FilterOption[]` | Available checkbox options for the column |
 | `filters` | `TableFilters` | Current filter state across all columns |
-| `onFilterChange` | `(filters: TableFilters) => void` | Callback fired on apply or reset |
-| `placement` | `'bottom-start' \| 'bottom-end' \| 'bottom'` | Dropdown anchor position |
-| `dropdownClassName` | `string` | Extra class on the dropdown panel |
+| `onFilterChange` | `(filters: TableFilters) => void` | Callback when filters are applied or reset |
+| `placement` | `'bottom-start' \| 'bottom-end' \| 'bottom'` | Dropdown anchor position (default: `'bottom-start'`) |
+| `dropdownClassName` | `string` | Extra class on the dropdown (default: `'min-w-[240px]'`) |
 
 ### `TableColumnFilterDropdown`
-Renders a trigger button (label + `Filter02Icon`) that turns accent-colored when filters are active (`activeCount > 0`). Delegates to `FiltersDropdown` with a single `checkbox` section, forwarding `onApply` and `onReset` handlers that merge or remove the column's filter entries from the shared `TableFilters` state.
+Renders a clickable label + `Filter02Icon` trigger. The icon turns accent-colored when one or more filters are active (`activeCount > 0`). Applies or resets filters scoped to the given `columnKey` without mutating other column filter state.
+
+> **Deprecated:** Use `DataTableColumnFilter` from `data-table` instead.
 
 ## Usage Example
 
@@ -37,4 +39,8 @@ const [filters, setFilters] = useState<TableFilters>({})
 />
 ```
 
-> **Deprecated:** Use `DataTableColumnFilter` from `data-table` instead.
+## Notes
+
+- Both the interface and the component are marked `@deprecated`. Migrate to `DataTableColumnFilter` from the `data-table` package.
+- Filter state is immutable per column: applying updates only `columnKey`'s values; resetting deletes the key without affecting sibling columns.
+- Source: [`table-column-filter-dropdown.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/table-column-filter-dropdown.tsx)