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

package/src/components/ui/button/.button-styles.md

@@ -0,0 +1,35 @@
+<!-- source-hash: de008cac6e8735331504b8c3add5fdc8 -->
+Shared Tailwind class constants for button surface colors, outline borders, and split-divider colors — consumed by both `Button` and `SplitButton` components as a single source of truth.
+
+## Key Components
+
+- **`buttonSurfaceClasses`** — Object map of Tailwind classes per visual variant (`accent`, `outline`, `transparent`, `destructive`), covering base, hover, active, `disabled:`, and `aria-disabled:` states.
+- **`outlineBorderClasses`** — Shared border string applied to `outline` variant buttons across all states.
+- **`splitDividerColorClasses`** — Per-variant border color for the vertical seam dividing main and icon halves in split-button layouts.
+- **`ButtonSurfaceVariant`** — Derived union type (`"accent" | "outline" | "transparent" | "destructive"`) inferred from `buttonSurfaceClasses` keys.
+
+## Usage Example
+
+```typescript
+import {
+  buttonSurfaceClasses,
+  outlineBorderClasses,
+  splitDividerColorClasses,
+  type ButtonSurfaceVariant,
+} from "./button-styles"
+
+const variant: ButtonSurfaceVariant = "accent"
+
+// Apply surface classes to a button element
+const surfaceClass = buttonSurfaceClasses[variant]
+// → "bg-ods-accent text-ods-text-on-accent hover:bg-ods-accent-hover ..."
+
+// Combine with border classes for the outline variant
+const outlineButtonClass = `${buttonSurfaceClasses.outline} ${outlineBorderClasses}`
+
+// Resolve divider color for a SplitButton
+const dividerClass = splitDividerColorClasses[variant]
+// → "border-ods-accent-active"
+```
+
+> **Note:** Both `disabled:` and `aria-disabled:` states are included in every variant because `<a>` elements don't support the native `:disabled` pseudo-class — use `aria-disabled` on anchor-based buttons.

package/src/components/ui/button/.button.md

@@ -0,0 +1,53 @@
+<!-- source-hash: e6cbc38937ee7e5569d78f2d7f50de6f -->
+A polymorphic, variant-aware button component built on `class-variance-authority` and Radix UI's `Slot`, supporting standard buttons, link navigation, split-icon layouts, and loading states.
+
+## Key Components
+
+- **`Button`** — Primary export; a `forwardRef` component that renders as `<button>`, `<Link>`, or a custom element (`asChild`).
+- **`buttonVariants`** — CVA config for the standard single-content layout; drives `variant`, `size`, `fullWidth`, and `noPaddingX` props.
+- **`splitShellVariants` / `splitSlotVariants`** — CVA configs for the split layout (triggered by `splitIcon`), where a vertical divider separates content from a trailing icon area.
+- **`Spinner`** — Internal animated SVG displayed during the `loading` state; absolutely positioned to avoid layout shift.
+- **`ButtonProps`** — Full interface including `href`, `linkProps`, `leftIcon`, `rightIcon`, `splitIcon`, `loading`, and deprecated `size="small-legacy"`.
+
+## Usage Example
+
+```typescript
+// Standard accent button
+<Button variant="accent" size="default" onClick={handleClick}>
+  Save
+</Button>
+
+// Link button with new-tab navigation
+<Button href="https://flamingo.run" openInNewTab>
+  Learn More
+</Button>
+
+// Loading state (preserves button width)
+<Button loading disabled>
+  Submitting...
+</Button>
+
+// Split layout with trailing icon
+<Button splitIcon={<ChevronDownIcon />} variant="outline">
+  Actions
+</Button>
+
+// Pre-resolved nav link (from useNavLink)
+<Button linkProps={{ href: "/dashboard", target: "_blank", rel: "noopener noreferrer" }}>
+  Dashboard
+</Button>
+
+// Render as child (asChild pattern)
+<Button asChild variant="destructive">
+  <a href="/delete">Delete Account</a>
+</Button>
+```
+
+### Variants
+
+| Prop | Options |
+|---|---|
+| `variant` | `accent` · `outline` · `transparent` · `destructive` |
+| `size` | `default` · `small` · `icon` · `small-legacy` *(deprecated)* |
+| `fullWidth` | `true` / `false` |
+| `noPaddingX` | `true` / `false` |

package/src/components/ui/button/.split-button.md

@@ -0,0 +1,48 @@
+<!-- source-hash: ae09312a4100bb1a98fd84f799794547 -->
+A compound button component with two independently interactive halves — a main action area and a trailing icon action area — separated by a 1px variant-colored divider seam.
+
+## Key Components
+
+- **`SplitButton`** — Primary exported component (`React.forwardRef<HTMLDivElement, SplitButtonProps>`). Renders a `role="group"` div containing two `Half` instances sharing the same variant and size.
+- **`Half`** — Internal helper that renders either a `<button>` or a Next.js `<Link>` depending on whether an `href` is provided, applying `splitHalfVariants` classes.
+- **`splitHalfVariants`** — `cva`-powered class builder with `variant` (`accent` | `outline` | `transparent` | `destructive`), `size` (`default` | `small`), and `side` (`main` | `icon`) axes. Compound variants handle rounded corners, divider borders, and icon-half width overrides.
+- **`SplitButtonIconAction`** — Interface describing the icon half: requires `icon` and `aria-label`; optionally accepts `onClick`, `href`, `openInNewTab`, `prefetch`, and `disabled`.
+- **`SplitButtonProps`** — Full prop surface for `SplitButton`, including `fullWidth`, `mainDisabled` (disables only the main half), `groupAriaLabel`, and the required `iconAction`.
+
+## Usage Example
+
+```typescript
+import { SplitButton } from "./split-button"
+import { ChevronDownIcon, PlusIcon } from "lucide-react"
+
+// Accent split button: main action navigates, icon half opens a dropdown
+<SplitButton
+  variant="accent"
+  size="default"
+  href="/tickets/new"
+  leftIcon={<PlusIcon />}
+  groupAriaLabel="Create ticket actions"
+  iconAction={{
+    icon: <ChevronDownIcon />,
+    "aria-label": "More create options",
+    onClick: () => setDropdownOpen(true),
+  }}
+>
+  New Ticket
+</SplitButton>
+
+// Destructive split with main disabled independently
+<SplitButton
+  variant="destructive"
+  mainDisabled
+  iconAction={{
+    icon: <ChevronDownIcon />,
+    "aria-label": "Delete options",
+    onClick: handleIconClick,
+  }}
+>
+  Delete
+</SplitButton>
+```
+
+> **Accessibility note:** The icon half has no visible text, so `iconAction["aria-label"]` is required. Use `groupAriaLabel` to label the wrapping `role="group"` when both halves share a semantic context.

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

@@ -0,0 +1,48 @@
+<!-- source-hash: 3ff43cdc4cea745588c40e71214b7483 -->
+Renders the body of a `DataTable` component, handling three states: loading skeleton, empty state, and populated rows with optional padding placeholders.
+
+## Key Components
+
+| Export | Type | Description |
+|--------|------|-------------|
+| `DataTableBody` | Component | Main body renderer consuming `DataTableContext` |
+| `DataTableBodyProps` | Interface | Props interface with generic row type `T` |
+
+### Key Props
+
+| 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 |
+
+## 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>
+```
+
+> **Performance tip:** Always memoize `onRowClick`, `rowHref`, and function-form `rowClassName` with `useCallback` to preserve `React.memo` optimization on `DataTableRow`.

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

@@ -0,0 +1,45 @@
+<!-- source-hash: 7328c0a6f65fd12c32856a3433715721 -->
+A React component that wraps `FiltersDropdown` to provide column-level filter UI for TanStack Table, reading and writing filter state directly on a `Column` instance.
+
+## Key Components
+
+### `DataTableColumnFilter`
+The primary export — a client-side dropdown filter trigger rendered inside a table column header.
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `column` | `Column<unknown, unknown>` | — | TanStack column instance (source of filter state) |
+| `options` | `DataTableFilterOption[]` | — | Checkbox options shown in the dropdown |
+| `placement` | `'bottom-start' \| 'bottom-end' \| 'bottom'` | `'bottom-start'` | Dropdown placement |
+| `label` | `string` | — | Column label shown in the trigger and dropdown header |
+| `align` | `'left' \| 'center' \| 'right'` | `'left'` | Horizontal alignment of the trigger content |
+
+### `DataTableColumnFilterProps`
+TypeScript interface describing all accepted props.
+
+### `EMPTY_ARRAY`
+Module-level stable reference used to prevent unnecessary `useMemo` invalidations when no filter is active.
+
+## Usage Example
+
+```typescript
+import { DataTableColumnFilter } from './data-table-column-filter'
+
+// Inside a TanStack Table column header definition:
+{
+  header: ({ column }) => (
+    <DataTableColumnFilter
+      column={column}
+      label="Status"
+      options={[
+        { label: 'Active', value: 'active' },
+        { label: 'Inactive', value: 'inactive' },
+      ]}
+      placement="bottom-start"
+      align="left"
+    />
+  ),
+}
+```
+
+> **Note:** `column.setFilterValue(undefined)` is used instead of `[]` on reset/clear, keeping TanStack Table's `getIsFiltered()` accurate. The `activeCount > 0` check on the `Filter02Icon` highlights the icon in the accent color when a filter is applied.

package/src/components/ui/data-table/.data-table-cursor-footer.md

@@ -0,0 +1,45 @@
+<!-- source-hash: baf395d8adb0995e4c693186e2740b56 -->
+Cursor-based pagination footer component for `DataTable`, wrapping `CursorPagination` with a top-border separator styled to match the legacy `Table` appearance.
+
+## Key Components
+
+### `DataTableCursorFooter`
+A thin wrapper around `<CursorPagination>` that automatically reads the current row count from the `DataTable` context via `useDataTableContext()`.
+
+**Props (`DataTableCursorFooterProps`):**
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `currentCount` | `number` (optional) | Overrides the auto-detected row count from the table instance |
+| `showInfo` | inherited | Defaults to `true` if not provided |
+| `...rest` | `CursorPaginationProps` | All `CursorPagination` props except `currentCount` |
+
+**Automatic behavior:**
+- Reads `table.getRowModel().rows.length` as the default `currentCount`
+- Applies `border-t`, spacing tokens, and supports `className` override
+
+## Usage Example
+
+```typescript
+<DataTable data={rows} columns={columns}>
+  <DataTable.Body />
+  <DataTableCursorFooter
+    hasNextPage={pageInfo.hasNextPage}
+    hasPreviousPage={pageInfo.hasPreviousPage}
+    onNextPage={() => fetchNextPage()}
+    onPreviousPage={() => fetchPreviousPage()}
+  />
+</DataTable>
+```
+
+Override the displayed count manually:
+
+```typescript
+<DataTableCursorFooter
+  hasNextPage={true}
+  onNextPage={handleNext}
+  currentCount={filteredCount}
+/>
+```
+
+> **Note:** Must be placed after `<DataTable.Body>` and rendered inside a `DataTable` context. Uses `useDataTableContext()` internally — rendering outside a `DataTable` will throw.

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

@@ -0,0 +1,43 @@
+<!-- source-hash: f96e91397f5dd889c77eca76b3638ae9 -->
+Empty state component for data tables, displaying a message, optional icon, and optional action button when no data is available.
+
+## Key Components
+
+### `DataTableEmptyProps`
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `message` | `string` | `'No data available'` | Text shown below the icon |
+| `icon` | `ReactNode` | `<FileX2 />` | Custom icon; falls back to `FileX2` from lucide-react |
+| `action` | `{ label: string; onClick: () => void }` | — | Optional CTA button rendered below the message |
+| `className` | `string` | — | Additional CSS classes for the wrapper |
+
+### `DataTableEmpty`
+A client component that renders a centered empty state card using ODS design tokens for spacing, colors, and borders.
+
+## Usage Example
+
+```typescript
+// Basic usage
+<DataTableEmpty />
+
+// With custom message
+<DataTableEmpty message="No tickets found" />
+
+// With custom icon and action
+<DataTableEmpty
+  message="No devices registered"
+  icon={<ServerOff className="w-12 h-12" />}
+  action={{
+    label: "Add Device",
+    onClick: () => router.push("/devices/new"),
+  }}
+/>
+
+// Inside a table when rows are empty
+{rows.length === 0 && (
+  <DataTableEmpty
+    message="No results match your filters"
+    action={{ label: "Clear Filters", onClick: resetFilters }}
+  />
+)}
+```

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

@@ -0,0 +1,55 @@
+<!-- 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.
+
+## 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
+
+### `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.
+
+### 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 |
+
+## 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 }
+  )
+}
+
+<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.

package/src/components/ui/data-table/.data-table-infinite-footer.md

@@ -0,0 +1,44 @@
+<!-- source-hash: 718cfa113d039df6d7ab2e0e2bb64de9 -->
+Infinite-scroll footer component for `DataTable` that uses an `IntersectionObserver` sentinel to automatically trigger data loading when the user scrolls near the bottom of the table.
+
+## Key Components
+
+- **`DataTableInfiniteFooter`** — Main component that renders a 1px sentinel `<div>` and optional skeleton rows
+- **`DataTableInfiniteFooterProps`** — Interface defining control props for pagination state and load behavior
+- **Sentinel element** — A hidden `h-1` div observed by `IntersectionObserver`; fires `onLoadMore` when it enters the viewport
+- **`DataTableSkeleton`** — Rendered during active fetch to provide loading feedback
+
+## Usage Example
+
+```typescript
+import { DataTableInfiniteFooter } from './data-table-infinite-footer'
+
+function MyTable() {
+  const { data, hasNextPage, isFetchingNextPage, fetchNextPage } = useInfiniteQuery(...)
+
+  return (
+    <table>
+      <tbody>
+        {data.map(row => <tr key={row.id}>...</tr>)}
+      </tbody>
+      <DataTableInfiniteFooter
+        hasNextPage={hasNextPage}
+        isFetchingNextPage={isFetchingNextPage}
+        onLoadMore={fetchNextPage}
+        skeletonRows={5}
+        rootMargin="300px"
+      />
+    </table>
+  )
+}
+```
+
+## Notes
+
+| Prop | Default | Description |
+|------|---------|-------------|
+| `skeletonRows` | `3` | Number of skeleton rows shown while fetching |
+| `rootMargin` | `'200px'` | `IntersectionObserver` margin, controls how early loading triggers |
+
+- `onLoadMore` is stored in a ref to avoid stale closure issues in the observer callback
+- The observer disconnects and re-attaches whenever `hasNextPage`, `isFetchingNextPage`, or `rootMargin` changes

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

@@ -0,0 +1,43 @@
+<!-- source-hash: 95233cb5edc63b60b1c188abbbdfc1dc -->
+Renders a row count label (e.g., "8 devices") for a data table, pulling the count from the table context or an explicit override.
+
+## Key Components
+
+- **`DataTableRowCount`** — Functional component that displays a formatted count with a singular/plural item label
+- **`DataTableRowCountProps`** — Interface defining configuration options for the count display
+- **`useDataTableContext`** — Hook consumed internally to read the current row model length
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `itemName` | `string` | `'result'` | Singular noun; auto-pluralized by appending `"s"` |
+| `totalCount` | `number` | row model length | Override for server-paginated tables |
+| `pluralize` | `(count, itemName) => string` | — | Custom pluralizer for irregular nouns |
+| `hideWhenEmpty` | `boolean` | `true` | Hides the element when count is zero |
+| `className` | `string` | — | Additional CSS classes |
+
+## Usage Example
+
+```typescript
+// Basic usage — count from table context
+<DataTable.RowCount itemName="device" />
+
+// Server-paginated — pass total explicitly
+<DataTable.Header
+  rightSlot={
+    <DataTable.RowCount
+      itemName="device"
+      totalCount={pageInfo.total}
+    />
+  }
+/>
+
+// Irregular pluralization
+<DataTable.RowCount
+  itemName="person"
+  pluralize={(count, name) => count === 1 ? name : 'people'}
+/>
+```
+
+> For server-paginated tables, always pass `totalCount` — the table context only tracks loaded rows, not the full dataset total.

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

@@ -0,0 +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.
+
+## 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 |
+
+## 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.
+
+## Usage Example
+
+```typescript
+// Clickable row (div mode)
+<DataTableRow
+  row={row}
+  onClick={(item) => console.log('Selected:', item)}
+  compact={false}
+/>
+
+// Link mode — enables browser-native behaviours (right-click, Cmd+click, :visited)
+<DataTableRow
+  row={row}
+  href={`/tickets/${row.original.id}`}
+/>
+```
+
+> **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.

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

@@ -0,0 +1,42 @@
+<!-- source-hash: c772b3ac402db602bd1473a8927ce650 -->
+Renders animated skeleton placeholder rows for a `DataTable` during loading states, matching the visual structure of real rows (desktop multi-column and mobile single-column layouts).
+
+## Key Components
+
+| Export | Type | Description |
+|--------|------|-------------|
+| `DataTableSkeleton` | Component | Animated pulse skeleton rows mirroring visible table columns |
+| `DataTableSkeletonProps` | Interface | Props: `rows` (count), `className`, `rowClassName` |
+| `ROW_HEIGHT_DESKTOP` | Constant | Shared row height class for desktop (`h-[68px] md:h-[80px]`) |
+| `ROW_HEIGHT_MOBILE` | Constant | Shared row height class for mobile (`h-[68px]`) |
+
+## Usage Example
+
+```typescript
+import {
+  DataTableSkeleton,
+  DataTableSkeletonProps,
+} from './data-table-skeleton'
+
+// Inside a DataTable context, shown while data is loading
+function MyTableContent({ isLoading }: { isLoading: boolean }) {
+  if (isLoading) {
+    return (
+      <DataTableSkeleton
+        rows={5}
+        className="my-2"
+        rowClassName="opacity-80"
+      />
+    )
+  }
+  return <DataTableRows />
+}
+```
+
+## Behavior Notes
+
+- Reads visible columns via `useDataTableContext()` to match real column widths and layout
+- **Desktop**: renders one placeholder block per column, respecting `meta.width` or `flex-1`
+- **Mobile**: renders a simplified two-line placeholder (title + subtitle)
+- Every other row (`index % 2 === 0`) adds a secondary line on the first column, mimicking subtitle density variation
+- Uses `animate-pulse` for the loading animation and ODS design tokens for consistent theming

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

@@ -0,0 +1,47 @@
+<!-- source-hash: 6a7ddf5f10f15bad8596c7908f4f597c -->
+Provides the root context and container for a composable `DataTable` component, supplying a TanStack Table instance via React context to all child components.
+
+## Key Components
+
+| Export | Type | Description |
+|--------|------|-------------|
+| `DataTableRoot` | Component | Root wrapper that provides the table instance via context |
+| `useDataTableContext` | Hook | Consumes the table context; throws if used outside `DataTableRoot` |
+| `DataTableContext` | Context | Internal React context holding the `Table<any>` instance |
+| `DataTableProps` | Interface | Props for `DataTableRoot`: `table`, `children`, `className` |
+
+## Usage Example
+
+```typescript
+import { useReactTable } from '@tanstack/react-table'
+import { DataTableRoot, useDataTableContext } from './data-table'
+
+// Compose child components that consume the context
+function MyTableBody<T>() {
+  const table = useDataTableContext<T>()
+  return (
+    <tbody>
+      {table.getRowModel().rows.map(row => (
+        <tr key={row.id}>...</tr>
+      ))}
+    </tbody>
+  )
+}
+
+// Wrap with DataTableRoot to provide context
+function MyTable() {
+  const table = useReactTable({ data, columns, getCoreRowModel })
+
+  return (
+    <DataTableRoot table={table} className="rounded-lg border">
+      <MyTableBody />
+    </DataTableRoot>
+  )
+}
+```
+
+## Notes
+
+- `DataTableRoot` renders a full-width `flex flex-col` container; additional layout classes can be passed via `className`.
+- `useDataTableContext` is generic — pass the row type `T` for full type safety on the returned `Table<T>` instance.
+- All sub-components (`Header`, `Body`, etc.) **must** be rendered inside `DataTableRoot`; otherwise `useDataTableContext` will throw a descriptive error.

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

@@ -0,0 +1,55 @@
+<!-- source-hash: fda76a4590fc216e2e89f36db86ddeba -->
+Public API barrel for the `DataTable` compound component. Assembles all sub-components into a single composable primitive, re-exports named pieces, utility hooks, constants, and proxied TanStack Table primitives so consumers need only one import path.
+
+## Key Components
+
+| Export | Description |
+|---|---|
+| `DataTable` | Compound component (`DataTableRoot` + `Header`, `Body`, `Row`, `Skeleton`, `Empty`, `InfiniteFooter`, `CursorFooter`, `RowCount`) |
+| `useDataTable` | Hook to build the TanStack `Table` instance passed to `<DataTable>` |
+| `useDataTableContext` | React context accessor for nested sub-components |
+| `alignJustify` / `getHideClasses` / `multiSelectFilterFn` | Column layout and filtering utilities |
+| `ROW_HEIGHT_DESKTOP` / `ROW_HEIGHT_MOBILE` | Skeleton row height constants |
+| TanStack re-exports | `flexRender`, `createColumnHelper`, `getCoreRowModel`, and all standard row model getters |
+
+## Usage Example
+
+```typescript
+import {
+  DataTable,
+  useDataTable,
+  createColumnHelper,
+  getCoreRowModel,
+} from '@/components/data-table'
+
+const col = createColumnHelper<Device>()
+const columns = [
+  col.accessor('name', { header: 'Name' }),
+  col.accessor('status', { header: 'Status' }),
+]
+
+function DeviceTable({ data, hasNext, loadNext, isLoading }) {
+  const table = useDataTable({
+    data,
+    columns,
+    getCoreRowModel: getCoreRowModel(),
+  })
+
+  return (
+    <DataTable table={table}>
+      <DataTable.Header stickyHeader stickyHeaderOffset="top-[56px]" />
+      <DataTable.Body
+        loading={isLoading}
+        rowHref={d => `/devices/${d.id}`}
+      />
+      <DataTable.InfiniteFooter
+        hasNextPage={hasNext}
+        isFetchingNextPage={isLoading}
+        onLoadMore={() => loadNext(50)}
+      />
+    </DataTable>
+  )
+}
+```
+
+> Both compound (`DataTable.Header`) and named (`DataTableHeader`) import styles are supported — use whichever fits your codebase conventions.