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

package/src/components/ui/table/.table-description-cell.md

@@ -1,18 +1,17 @@
-<!-- source-hash: 3f4c3ea11c22967d350372a28c7b33d3 -->
-A deprecated table cell component for displaying truncated description text with configurable line clamping. Use `data-table` instead.
+<!-- source-hash: 2746004dfdd4cd1e448e6edd26994e2f -->
+A deprecated React component for rendering truncated description text within table cells, supporting configurable line clamping from 1–6 lines.
 
 ## Key Components
 
-### `TableDescriptionCell` *(deprecated)*
-A React component that renders description text within a table cell, supporting multi-line truncation via CSS `line-clamp` utilities.
-
-### `TableDescriptionCellProps` *(deprecated)*
-
+### `TableDescriptionCellProps`
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
 | `text` | `string` | — | The description text to display |
 | `className` | `string` | — | Optional additional CSS classes |
-| `maxLines` | `1-6` | `3` | Maximum lines before truncating |
+| `maxLines` | `1–6` | `3` | Maximum lines before truncating |
+
+### `TableDescriptionCell`
+A client-side functional component that renders description text with Tailwind-based line clamping. Applies `truncate` for `maxLines=1` and `line-clamp-{n}` for values 2–6. Text uses `text-h6` and `text-ods-text-secondary` styling by default.
 
 ## Usage Example
 
@@ -21,16 +20,16 @@ import { TableDescriptionCell } from './table-description-cell'
 
 // Default 3-line clamp
 <TableDescriptionCell
-  text="This is a long description that may span multiple lines in the table cell."
+  text="This is a long description that will be clamped after three lines of text."
 />
 
 // Single-line truncation
 <TableDescriptionCell
-  text="Short truncated description"
+  text="Long description truncated to one line"
   maxLines={1}
 />
 
-// Custom styling with 2-line clamp
+// Custom class with 2-line clamp
 <TableDescriptionCell
   text="Custom styled description text"
   maxLines={2}
@@ -38,4 +37,6 @@ import { TableDescriptionCell } from './table-description-cell'
 />
 ```
 
-> **⚠️ Deprecated:** This component is deprecated. Migrate to `data-table` for new implementations.
+## Notes
+
+> ⚠️ **Deprecated:** This component is deprecated. Use [`data-table`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/src) instead.

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

@@ -1,37 +1,36 @@
-<!-- source-hash: 646e60a86ac75ae22a638fb221c00ad2 -->
-Renders a centered empty state UI within a table or data container, displaying an icon, message, and optional action button when no data is available.
+<!-- source-hash: 9f3cb8400bce287eb892324aeced9179 -->
+Deprecated empty state component for tables that renders a "no results" UI using the `NoData` base component.
 
 ## Key Components
 
-- **`TableEmptyState`** *(deprecated)* — Main exported component. Use `DataTableEmpty` from `data-table` instead.
+- **`TableEmptyState`** — Exported function component that wraps `NoData` with table-specific defaults. Marked as `@deprecated` in favour of `DataTableEmpty` from `data-table`.
 
-## Props (`TableEmptyStateProps`)
+### Props (`TableEmptyStateProps`)
 
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `message` | `string` | `'No data available'` | Text displayed below the icon |
-| `icon` | `ReactNode` | `<FileX2 />` | Custom icon override |
-| `action` | `{ label: string; onClick: () => void }` | `undefined` | Optional action button |
-| `className` | `string` | `undefined` | Additional CSS classes |
+| Prop | Description |
+|---|---|
+| `message` | Custom message shown as the title; defaults to `'No results found'` |
+| `icon` | Override icon; defaults to `<SearchIcon />` |
+| `action` | Optional `{ label, onClick }` for a call-to-action button |
+| `className` | Additional CSS classes merged via `cn()` |
 
 ## Usage Example
 
 ```typescript
-// ⚠️ Deprecated — prefer DataTableEmpty from data-table
 import { TableEmptyState } from './table-empty-state'
 
 // Basic usage
-<TableEmptyState message="No records found" />
+<TableEmptyState />
 
-// With custom icon and action
+// With custom message and action
 <TableEmptyState
-  message="No devices available"
-  icon={<ServerOff className="w-12 h-12" />}
-  action={{
-    label: "Add Device",
-    onClick: () => router.push('/devices/new')
-  }}
+  message="No tickets found"
+  action={{ label: 'Create Ticket', onClick: () => router.push('/tickets/new') }}
 />
 ```
 
-> **Deprecated:** This component is superseded by `DataTableEmpty` from the `data-table` package, which provides enhanced features and consistent data table integration. Migrate existing usages when possible.
+> **Deprecation notice:** Migrate to `DataTableEmpty` from the `data-table` package for new implementations.
+
+## Source
+
+[`table-empty-state.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/table-empty-state.tsx)

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

@@ -1,34 +1,44 @@
-<!-- source-hash: fc61b63b86b6a05d8f7ae1ddcc0dba93 -->
-A deprecated table row component that renders a single row in a tabular layout, supporting click handlers, link navigation, row selection, and dynamic cell rendering with nested property access.
+<!-- source-hash: 3f82dc8c648a34997fb9485fd51b9624 -->
+Deprecated row component for the legacy `Table` component, rendering a single data row with support for click handlers, link mode, selection checkboxes, nested property access, and optional FLIP animation via `framer-motion`.
 
 ## Key Components
 
-- **`TableRow<T>`** — Generic row component accepting typed `item` data, column definitions, and interaction callbacks. Marked `@deprecated` — use `DataTableRow` from `data-table` instead.
-- **`handleRowClick`** — Click handler that respects `[data-no-row-click]` elements (e.g., checkboxes), preventing event propagation to row-level handlers.
-- **`getCellValue`** — Resolves cell content via `column.renderCell` or dot-notation key traversal (e.g., `"user.address.city"`), with fallbacks for `null`, `boolean`, and `object` values.
-- **Link mode** — When `href` is provided without `onClick`, renders an absolutely-positioned `<Link>` overlay for full-row navigation while keeping inner elements pointer-event-safe.
+- **`TableRow<T>`** — Generic row component (deprecated; use `DataTableRow` from `data-table` instead)
+- **`getCellValue`** — Resolves cell content via `column.renderCell` or dot-notation key traversal with fallback formatting for `null`, `boolean`, and `object` values
+- **`handleRowClick`** — Click handler that respects `[data-no-row-click]` targets to prevent propagation from interactive inner elements
+- **`handleSelect`** — Checkbox selection callback forwarding the row item to `onSelect`
+- **FLIP animation** — Lazily upgrades the root element to a `motion.div` (only when `animateRowReorder` and `motionDiv` are both provided), keeping `framer-motion` out of the default bundle
 
 ## Usage Example
 
 ```typescript
+import { TableRow } from './table-row'
+
+const columns = [
+  { key: 'user.name', label: 'Name' },
+  { key: 'status', label: 'Status', renderCell: (item) => <Badge>{item.status}</Badge> },
+]
+
 <TableRow
-  item={user}
+  item={rowData}
+  columns={columns}
   index={0}
-  columns={[
-    { key: 'name', label: 'Name' },
-    { key: 'address.city', label: 'City' },
-    {
-      key: 'status',
-      label: 'Status',
-      renderCell: (item) => <StatusBadge status={item.status} />
-    }
-  ]}
-  href={`/users/${user.id}`}
+  compact={false}
+  href={`/users/${rowData.id}`}
   selectable
-  selected={selectedIds.has(user.id)}
+  selected={selectedIds.has(rowData.id)}
   onSelect={(item) => toggleSelection(item.id)}
-  compact={false}
+  animateRowReorder
+  motionDiv={MotionDiv}
 />
 ```
 
-> **Deprecation notice:** This component is superseded by `DataTableRow` from the `data-table` package, which provides improved composability and feature support.
+## Notes
+
+- **Link mode** activates when `href` is provided and `onClick` is absent — an absolutely-positioned `<Link>` covers the row while inner cells use `pointer-events-none`
+- `[data-no-row-click]` on any inner element (e.g., the checkbox wrapper) prevents the row click from firing
+- `className` accepts either a static string or a `(item, index) => string` function for per-row dynamic styles
+
+> **Deprecated:** Use `DataTableRow` from `data-table` instead.
+
+**Source:** [`table-row.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/table-row.tsx)

package/src/components/ui/table/.table-skeleton.md

@@ -1,45 +1,50 @@
-<!-- source-hash: 1ccd2771fe5f338fc464bca5ddb0e198 -->
-Renders animated loading skeleton rows for table/card layouts with responsive desktop and mobile variants.
+<!-- source-hash: cf0d76307d34f2cb3ba0d8a755fc3f81 -->
+Renders animated pulse skeleton rows for table/card lists while data loads, providing separate desktop and mobile layouts. Marked as deprecated in favor of `DataTableSkeleton` from `data-table`.
 
 ## Key Components
 
-- **`TableCardSkeleton`** *(deprecated)* — Main exported component. Renders `n` pulsing skeleton rows with configurable columns, optional action buttons, and optional chevron indicators. Use `DataTableSkeleton` from `data-table` instead.
-- **`ROW_HEIGHT_DESKTOP`** *(deprecated)* — Tailwind height class `h-[68px] md:h-[80px]` for desktop rows.
-- **`ROW_HEIGHT_MOBILE`** *(deprecated)* — Tailwind height class `h-[68px]` for mobile rows.
+### `TableCardSkeleton` *(deprecated)*
+Main export. Renders `n` skeleton card rows with responsive desktop (`md:flex`) and mobile (`flex md:hidden`) layouts.
 
-## Props (`TableCardSkeletonProps`)
+**Props** (`TableCardSkeletonProps`):
 
 | Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `columns` | `Column[]` | required | Column definitions with `key` and optional `width` |
+|---|---|---|---|
+| `columns` | `Column[]` | — | Column definitions with `key` and optional `width` (Tailwind class) |
 | `rows` | `number` | `10` | Number of skeleton rows to render |
-| `hasActions` | `boolean` | `false` | Show action button placeholders |
-| `hasChevron` | `boolean` | `false` | Show chevron placeholder |
-| `className` | `string` | — | Extra classes on each row wrapper |
-| `rowClassName` | `string` | — | Extra classes on the inner row layout |
+| `hasActions` | `boolean` | `false` | Renders action button placeholders |
+| `hasChevron` | `boolean` | `false` | Renders a chevron/navigate placeholder |
+| `className` | `string` | — | Extra classes on the row wrapper |
+| `rowClassName` | `string` | — | Extra classes on the inner flex row |
+
+### Constants *(deprecated)*
+- `ROW_HEIGHT_DESKTOP` — `'h-[68px] md:h-[80px]'`
+- `ROW_HEIGHT_MOBILE` — `'h-[68px]'`
+
+**Primary column detection:** The component automatically identifies the widest (`flex-1` or `flex-[n]`) column as "primary" and renders a second skeleton line on every other row to simulate multi-line content.
 
 ## Usage Example
 
 ```typescript
-import { TableCardSkeleton } from './table-skeleton'
+import { TableCardSkeleton } from '@openframe/ui/components/table-card-skeleton'
 
 const columns = [
-  { key: 'name', width: 'w-1/3' },
-  { key: 'status' },
-  { key: 'date' },
+  { key: 'avatar', width: 'w-10' },
+  { key: 'name',   width: 'flex-1' },
+  { key: 'status', width: 'w-24' },
 ]
 
 // While data is loading:
-if (isLoading) {
-  return (
-    <TableCardSkeleton
-      columns={columns}
-      rows={5}
-      hasActions
-      hasChevron
-    />
-  )
-}
+<TableCardSkeleton
+  columns={columns}
+  rows={5}
+  hasActions
+  hasChevron
+/>
 ```
 
-> **Deprecation notice:** `TableCardSkeleton` is deprecated. Migrate to `DataTableSkeleton` from the `data-table` package for new implementations.
+> **Deprecated:** Migrate to `DataTableSkeleton` from the `data-table` package.
+
+## Source
+
+[`table-skeleton.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/table-skeleton.tsx)

package/src/components/ui/table/.table-timestamp-cell.md

@@ -1,47 +1,48 @@
-<!-- source-hash: 7500f4530337c7688e67a30e99d9fabd -->
-Renders a two-line table cell displaying a formatted timestamp with an optional labeled ID beneath it.
+<!-- source-hash: 2b4c1503432027b2b294508069472c01 -->
+A deprecated table cell component that displays a timestamp with an optional ID label below it, designed for use in table rows.
 
 ## Key Components
 
 ### `TableTimestampCell` *(deprecated — use `data-table` instead)*
-A React client component that stacks a primary timestamp line and a secondary ID line within a flex column layout.
+
+The primary exported component renders a two-line cell: a formatted timestamp on top and an ID (with optional label) below.
 
 ### `TableTimestampCellProps` *(deprecated)*
+
 | Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `timestamp` | `string \| Date` | — | Timestamp to display; auto-formatted if ISO string or Date |
-| `id` | `string` | — | ID value shown below the timestamp |
-| `idLabel` | `string` | `undefined` | Optional label prefix (e.g. `"Log ID"`) |
-| `className` | `string` | `undefined` | Additional CSS classes for the container |
-| `formatTimestamp` | `boolean` | `true` | Disable to render the timestamp as-is |
+|---|---|---|---|
+| `timestamp` | `string \| Date` | — | Timestamp to display; accepts `Date`, ISO string, or pre-formatted string |
+| `id` | `string` | — | ID displayed below the timestamp |
+| `idLabel` | `string` | — | Optional label prefix (e.g. `"Log ID"`) |
+| `className` | `string` | — | Additional CSS classes for the container |
+| `formatTimestamp` | `boolean` | `true` | Auto-formats ISO strings and `Date` objects via `toLocaleString()` |
 
 ### `formatTimestampValue` *(internal)*
-Converts a `Date` or ISO string to a locale-formatted string. Already-formatted strings (containing `,` or `/` + `:`) are returned unchanged. Falls back to `String(timestamp)` if parsing fails.
+
+Formats a `string | Date` value for display:
+- `Date` instances → `toLocaleString()`
+- ISO strings → parsed and formatted via `toLocaleString()`
+- Already-formatted strings (containing `,` or `/` + `:`) → returned as-is
+- Unparseable values → returned as-is via `String()`
 
 ## Usage Example
 
 ```typescript
 import { TableTimestampCell } from './table-timestamp-cell'
 
-// With an ISO string and a labeled ID
+// With ISO string and a labeled ID
 <TableTimestampCell
-  timestamp="2024-06-15T14:30:00Z"
-  id="abc-123"
+  timestamp="2024-11-15T10:30:00.000Z"
+  id="log-abc-123"
   idLabel="Log ID"
 />
 
-// With a Date object, no label
-<TableTimestampCell
-  timestamp={new Date()}
-  id="xyz-789"
-/>
-
-// Skip auto-formatting (display raw value)
+// With a pre-formatted string and no label
 <TableTimestampCell
-  timestamp="Jun 15, 2024 2:30 PM"
-  id="xyz-789"
+  timestamp="11/15/2024, 10:30:00 AM"
+  id="chat-xyz-789"
   formatTimestamp={false}
 />
 ```
 
-> **Deprecated:** This component is marked for removal. Migrate to the `data-table` component for new implementations.
+> ⚠️ **Deprecated:** This component is superseded by the [`data-table`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/src) primitive. Migrate existing usages when possible.

package/src/components/ui/table/.table.md

@@ -1,47 +1,60 @@
-<!-- source-hash: ec4b9765ec4a72e85067393812e2e172 -->
-A deprecated generic `Table` component that renders a card-style data table with sorting, filtering, selection, pagination, and infinite scroll support.
+<!-- source-hash: d3651ba2596f8979ff27b1f6715a6879 -->
+A deprecated generic table component that renders tabular data with support for sorting, filtering, row selection, bulk actions, pagination (cursor and page-based), infinite scroll, and optional row-reorder animations via lazy-loaded Framer Motion.
 
 ## Key Components
 
-### `injectSyntheticColumns<T>`
-Internal helper that appends synthetic columns to the column definitions:
-- **`__actions__`** — renders row-level action buttons or a custom `renderRowActions` slot
-- **`__chevron__`** — renders a navigation chevron button when `rowHref` is provided
-
-### `Table<T>`
-The main exported component. **Marked `@deprecated`** — use `DataTable` from `data-table` instead.
-
-Key features:
-- **Loading state** — shows `TableCardSkeleton` while fetching with no data
-- **Empty state** — renders `TableEmptyState` with a configurable message
-- **Row selection** — checkbox-based with `selectable`, `selectedRows`, and `onSelectionChange`
-- **Bulk actions toolbar** — appears when rows are selected and `showToolbar` + `bulkActions` are set
-- **Sorting & filtering** — delegated to `TableHeader` via `sortBy`, `sortDirection`, `onSort`, `filters`
-- **Pagination** — supports cursor-based (`CursorPagination`) or page-based (`Pagination`)
-- **Infinite scroll** — uses `IntersectionObserver` on a sentinel `<div>` to trigger `onLoadMore`
-- **Sticky header** — controlled via `stickyHeader` and `stickyHeaderOffset`
-- **Placeholder rows** — invisible rows maintain consistent table height when data count is below `skeletonRows`
+| Export / Symbol | Description |
+|---|---|
+| `Table<T>` | Main generic table component (deprecated — use `DataTable` from `data-table` instead) |
+| `injectSyntheticColumns` | Internal helper that appends row-action buttons and/or chevron-link columns to the column definition array |
+| `TableProps<T>` | Type imported from `./types` that defines all accepted props |
+| `useTableMotion` | Hook that lazily loads Framer Motion for opt-in row-reorder FLIP animations |
 
 ## Usage Example
 
 ```typescript
-<Table
+import { Table } from './table'
+
+type User = { id: string; name: string; email: string }
+
+const columns = [
+  { key: 'name', label: 'Name', renderCell: (u: User) => u.name },
+  { key: 'email', label: 'Email', renderCell: (u: User) => u.email },
+]
+
+<Table<User>
   data={users}
+  columns={columns}
   rowKey="id"
-  columns={[
-    { key: 'name', label: 'Name', renderCell: (u) => u.name },
-    { key: 'email', label: 'Email', renderCell: (u) => u.email },
+  loading={isLoading}
+  emptyMessage="No users found"
+  skeletonRows={5}
+  onRowClick={(user) => console.log('clicked', user)}
+  rowActions={[
+    {
+      label: 'Delete',
+      onClick: (user) => deleteUser(user.id),
+    },
   ]}
-  rowActions={[{ label: 'Edit', icon: <EditIcon />, onClick: (u) => openEdit(u) }]}
-  rowHref={(u) => `/users/${u.id}`}
-  onRowClick={(u) => console.log(u)}
   cursorPagination={{
     hasNextPage: true,
     hasPreviousPage: false,
     onNext: fetchNext,
     onPrevious: fetchPrev,
+    onReset: resetCursor,
   }}
-  loading={isFetching}
-  skeletonRows={5}
+  selectable
+  selectedRows={selected}
+  onSelectionChange={setSelected}
+  animateRowReorder
 />
-```
+```
+
+## Notable Behaviors
+
+- **Synthetic columns** — `rowActions` / `renderRowActions` append an actions column; `rowHref` appends a chevron navigation column. Both use `data-no-row-click` to prevent event bubbling to the row click handler.
+- **Infinite scroll** — Uses an `IntersectionObserver` on a 1 px sentinel `div` with a `200px` root margin to call `onLoadMore` before the user hits the bottom.
+- **Height stability** — When infinite scroll is inactive, invisible placeholder rows fill the remaining `skeletonRows` quota to prevent layout shift.
+- **Framer Motion** — Loaded in its own lazy chunk only when `animateRowReorder` is `true`; rows are wrapped in a `LayoutGroup` for FLIP reorder transitions.
+
+> ⚠️ **Deprecated:** Prefer [`DataTable`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/src/components/data-table) for new implementations.

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

@@ -1,74 +1,78 @@
-<!-- source-hash: 808a537086105a4fbc3af48a2f6c9794 -->
-Legacy table component type definitions, all marked `@deprecated` in favor of the `data-table` module's types.
+<!-- source-hash: 08d57f62d79766ba8c518fb5cd2e217e -->
+Deprecated legacy table type definitions for the OpenFrame component library. All exports have been superseded by the `data-table` package and are retained only for backward compatibility.
+
+> ⚠️ **All types in this file are deprecated.** Migrate to the equivalent types exported from `data-table`.
 
 ## Key Components
 
-| Type | Kind | Description |
-|------|------|-------------|
-| `TableColumn<T>` | Interface | Column definition with sorting, filtering, rendering, and responsive visibility options |
-| `TableProps<T>` | Interface | Full table configuration including data, pagination, selection, sorting, filtering, and styling |
-| `CursorPagination` | Interface | Cursor-based pagination controls with next/previous navigation callbacks |
-| `PagePagination` | Interface | Page-number-based pagination with page change callback |
-| `InfiniteScrollConfig` | Interface | Infinite scroll configuration with load-more callback |
-| `FilterOption` | Interface | Single filter option with id, label, and value |
-| `FilterSection` | Interface | Grouped filter UI section supporting checkbox, radio, or select types |
-| `TableFilters` | Interface | Map of column keys to active filter values |
-| `BulkAction<T>` | Interface | Bulk action definition applied to selected rows |
-| `RowAction<T>` | Interface | Per-row action with label, icon, and click handler |
-| `TableHeaderProps<T>` | Interface | Props for the table header sub-component |
-| `TableRowProps<T>` | Interface | Props for an individual table row sub-component |
-| `TableCellProps` | Interface | Props for a single table cell |
-| `TableCardSkeletonProps` | Interface | Skeleton loader configuration for loading states |
-| `TableEmptyStateProps` | Interface | Empty state display with optional action button |
-| `TailwindBreakpoint` | Type | Responsive breakpoint union: `'md' \| 'lg' \| 'xl' \| '2xl'` |
+| Type | Description |
+|---|---|
+| `TailwindBreakpoint` | Union of responsive breakpoints (`'md' \| 'lg' \| 'xl' \| '2xl'`) |
+| `TableColumn<T>` | Column definition with sorting, filtering, responsive hiding, and custom cell/header renderers |
+| `FilterOption` | Single filter choice with `id`, `label`, and `value` |
+| `FilterSection` | Groups filter options by UI type (`checkbox`, `radio`, `select`) |
+| `TableFilters` | Map of column keys to arrays of active filter values |
+| `CursorPagination` | Cursor-based pagination config with navigation callbacks |
+| `PagePagination` | Page-number pagination config |
+| `InfiniteScrollConfig` | Infinite scroll trigger config with load-more callback |
+| `TableProps<T>` | Root table configuration — data, columns, sorting, filtering, selection, pagination, and animation |
+| `BulkAction<T>` | Action applied to all selected rows |
+| `RowAction<T>` | Per-row action with variant and mobile visibility control |
+| `TableHeaderProps<T>` | Props for the table header sub-component |
+| `TableRowProps<T>` | Props for individual row rendering, including optional FLIP reorder animation |
+| `TableCellProps` | Props for a single table cell |
+| `TableCardSkeletonProps` | Loading skeleton configuration |
+| `TableEmptyStateProps` | Empty state configuration with optional action |
 
 ## Usage Example
 
-> ⚠️ **Deprecated** — migrate to types from the `data-table` module instead.
-
 ```typescript
-import type { TableColumn, TableProps, CursorPagination } from './types'
+import type {
+  TableColumn,
+  TableProps,
+  CursorPagination,
+} from './types'
 
-interface User {
+// ⚠️ Deprecated — prefer imports from `data-table`
+interface Device {
   id: string
   name: string
-  email: string
+  status: 'online' | 'offline'
 }
 
-const columns: TableColumn<User>[] = [
+const columns: TableColumn<Device>[] = [
   {
     key: 'name',
-    label: 'Name',
+    label: 'Device Name',
     sortable: true,
-    hideAt: 'md',
-    renderCell: (user) => <span className="font-medium">{user.name}</span>,
+    width: 'flex-1',
   },
   {
-    key: 'email',
-    label: 'Email',
-    filterable: true,
-    filterKey: 'email',
+    key: 'status',
+    label: 'Status',
+    align: 'center',
+    hideAt: 'md',
+    renderCell: (item) => <StatusBadge status={item.status} />,
   },
 ]
 
 const pagination: CursorPagination = {
   hasNextPage: true,
   endCursor: 'cursor_abc123',
-  onNext: (cursor) => fetchUsers({ after: cursor }),
-  onReset: () => fetchUsers({}),
-  totalCount: 200,
-  showInfo: true,
+  onNext: (cursor) => fetchDevices({ after: cursor }),
+  itemName: 'devices',
 }
 
-const tableProps: TableProps<User> = {
-  data: users,
+const tableProps: TableProps<Device> = {
+  data: devices,
   columns,
   rowKey: 'id',
-  loading: false,
-  selectable: true,
   cursorPagination: pagination,
-  stickyHeader: true,
-  stickyHeaderOffset: 'top-[72px]',
-  onRowClick: (user) => router.push(`/users/${user.id}`),
+  onRowClick: (device) => router.push(`/devices/${device.id}`),
+  animateRowReorder: !prefersReducedMotion,
 }
-```
+```
+
+## Source
+
+[`types.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/types.ts)

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

@@ -0,0 +1,45 @@
+<!-- source-hash: e987f30323723ab5749093a8669f97f8 -->
+Lazy-loads `framer-motion` on demand to power optional row-reorder FLIP animations in table components, keeping the motion library out of the default bundle when the feature is unused.
+
+## Key Components
+
+### `TableMotionRuntime` (interface)
+Holds the resolved Framer Motion primitives needed for row-reorder animation:
+- `motionDiv` — `motion.div` component used to wrap animated table rows
+- `LayoutGroup` — coordinates FLIP animations across sibling rows
+
+### `useTableMotion(enabled)` (hook)
+Accepts a single boolean (`enabled`) and returns `TableMotionRuntime | null`.
+
+- Returns `null` immediately (and always) when `enabled` is `false` — no import is triggered
+- Fires a single dynamic `import('framer-motion')` when `enabled` becomes `true`
+- Returns `null` during the async load; callers render plain DOM so first paint is non-animated
+- Silently catches chunk-load failures and stays `null`, gracefully degrading to non-animated rows rather than throwing an unhandled rejection
+- Cleans up via an `active` flag to prevent state updates after unmount
+
+## Usage Example
+
+```typescript
+import { useTableMotion } from './use-table-motion'
+
+function TableRow({ reorderEnabled }: { reorderEnabled: boolean }) {
+  const motion = useTableMotion(reorderEnabled)
+
+  // Falls back to a plain <div> until framer-motion resolves
+  const Wrapper = motion?.motionDiv ?? 'div'
+
+  return (
+    <motion?.LayoutGroup>
+      <Wrapper layout>
+        {/* row content */}
+      </Wrapper>
+    </motion?.LayoutGroup>
+  )
+}
+```
+
+> **Bundle note:** Consumers that never pass `animateRowReorder={true}` will never load the `framer-motion` chunk, keeping the base `Table` path completely motion-free.
+
+## Source
+
+[`use-table-motion.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/use-table-motion.ts)