@facetui/react 1.0.0

package/LICENSE.md

@@ -0,0 +1,60 @@
+# License
+
+**FacetUI — Commercial License**
+
+Copyright © 2026 Cameron Gates. All rights reserved.
+
+This is a commercial software license. By purchasing, downloading, cloning, or otherwise obtaining a copy of this software and its associated source code (the "Software"), you ("Licensee") agree to be bound by the terms below. If you do not agree to these terms, do not use the Software.
+
+---
+
+## 1. Grant of License
+
+Subject to payment of any applicable license fee and compliance with this Agreement, the copyright holder ("Licensor") grants Licensee a non-exclusive, non-transferable, worldwide license to:
+
+- Use, modify, and integrate the Software into an unlimited number of personal or commercial end-products ("Projects") that Licensee builds;
+- Distribute the Software **only as compiled/bundled output** embedded within a Project (e.g., as part of a built web application), not as standalone or redistributable source code.
+
+Each individual developer requires their own license. A team or organizational license, if purchased, covers the number of seats specified at time of purchase.
+
+## 2. Restrictions
+
+Licensee may **not**, without prior written consent from Licensor:
+
+- Resell, sublicense, rent, lease, or otherwise redistribute the Software's source code, in whole or in part, whether modified or unmodified;
+- Publish the Software (or a derivative of it) to any public package registry (e.g., npm, GitHub Packages) in a way that makes the source code freely obtainable by third parties;
+- Use the Software to create a competing product — i.e., a data table component or library offered for sale, license, or free public distribution;
+- Remove, obscure, or alter any copyright, trademark, or attribution notices contained in the Software;
+- Claim authorship of the Software or represent it as your own original work.
+
+## 3. Ownership
+
+The Software is licensed, not sold. Licensor retains all right, title, and interest in and to the Software, including all intellectual property rights therein. This Agreement does not grant Licensee any rights to Licensor's trademarks, service marks, or trade names.
+
+## 4. Support & Updates
+
+Unless otherwise stated at the point of purchase, this license does not entitle Licensee to ongoing support or future version updates. Where support or updates are offered (e.g., for a limited period, or under a separate maintenance agreement), their scope is as described at the point of purchase.
+
+## 5. Warranty Disclaimer
+
+THE SOFTWARE IS PROVIDED "AS IS," WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT. LICENSOR DOES NOT WARRANT THAT THE SOFTWARE WILL BE ERROR-FREE OR UNINTERRUPTED.
+
+## 6. Limitation of Liability
+
+IN NO EVENT SHALL LICENSOR BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT, OR OTHERWISE, ARISING FROM, OUT OF, OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. LICENSOR'S TOTAL LIABILITY UNDER THIS AGREEMENT SHALL NOT EXCEED THE AMOUNT PAID BY LICENSEE FOR THE SOFTWARE.
+
+## 7. Termination
+
+This license terminates automatically if Licensee breaches any term of this Agreement. Upon termination, Licensee must cease all use of the Software and destroy all copies of the source code in their possession. Projects already distributed to end users prior to termination are not affected.
+
+## 8. Governing Law
+
+This Agreement is governed by the laws of **New South Wales, Australia**, without regard to conflict-of-law principles. The parties submit to the exclusive jurisdiction of the courts of New South Wales and the courts competent to hear appeals from them.
+
+## 9. Contact
+
+Questions about licensing terms, team/enterprise licensing, or requests for permissions beyond this license should be directed to **contact@redbeard.au**. See also `SECURITY.md` for vulnerability reports.
+
+---
+
+> **Note:** This document is a commercial license template, not a substitute for legal advice. Replace the bracketed placeholders above and have it reviewed by a lawyer licensed in your jurisdiction before relying on it for a paid marketplace listing.

package/README.md

@@ -0,0 +1,509 @@
+# FacetUI
+
+**FacetUI: The enterprise-grade, fully accessible React grid that replaces the sortable, filterable, paginated table you'd otherwise rebuild on every project** — headless architecture, conditional row selection, and a real controlled filtering pipeline, all styled natively in Tailwind with zero lock-in. Drop it in for a working table in one line, or drive the raw hook yourself when you need total control — same engine, three levels of abstraction. Built for teams who need WCAG-grade accessibility and server-side data out of the box, not bolted on after a support ticket.
+
+A production-ready, fully accessible data table component for React and Next.js. Built with TypeScript, [React Aria Components](https://react-spectrum.adobe.com/react-aria/) for the interactive primitives, [TanStack Table](https://tanstack.com/table) for the state engine, and Tailwind CSS v4 for styling. Follows the headless architecture pattern so every visual detail is customizable without forking the logic.
+
+---
+
+## Why FacetUI?
+
+Most table libraries force a trade-off: **feature-rich but rigid** (hard to restyle, locked into someone else's CSS framework) or **headless but primitive** (you re-implement sorting, pagination, and selection logic from scratch on every project).
+
+FacetUI is built to eliminate that trade-off — it ships as a complete, enterprise-grade data grid engine with the styling boundary drawn exactly where you want it.
+
+- **Headless architecture, batteries included.** Drop in `<DataTable>` for a fully working grid in one line, reach for the individual primitives to compose a custom layout, or drive the raw `useDataTable()` engine directly when you need total control over rendering. One state engine, three levels of abstraction — pick the altitude that fits the screen you're building.
+- **Conditional row selection, not just row selection.** Selection isn't a blunt on/off switch. Pass a predicate — `enableRowSelection={(row) => row.original.status === "active"}` — and the checkbox column, select-all logic, and keyboard interactions all automatically respect it. Locked, archived, or permission-gated rows simply can't be selected, in bulk or individually.
+- **A real controlled filtering pipeline.** Global search and per-column filters compose together, work identically whether the data source is a local array or a paginated API, and expose both controlled and uncontrolled state so you can wire them into a URL, a form, or React Query without fighting the component.
+- **Zero style lock-in.** Every element exposes a `classNames` override key with Tailwind-conflict-safe merging. Replace entire regions — toolbar, empty state, loading overlay — through render slots instead of forking component internals.
+- **Accessibility engineered in, not patched on.** WCAG 2.1 AA-targeted out of the box: correct grid semantics, `aria-sort`, live-region announcements, and React Aria-backed keyboard interaction on every interactive control. Ship accessible tables without becoming an accessibility expert.
+
+### Features at a Glance
+
+| Capability | What you get |
+|---|---|
+| **Sorting** | Client-side or server-driven (`manualSorting`), single or multi-column (`Shift`-click), full keyboard support |
+| **Pagination** | Client-side slicing or server-driven (`manualPagination` + `rowCount`), configurable page-size presets |
+| **Global search** | Case-insensitive substring match across all columns, controlled or uncontrolled, debounced-friendly API |
+| **Column filters** | Per-column filter state (`columnFilters`) that composes with global search — bring your own filter UI |
+| **Row selection** | Single or multi-select, bulk select-all, and a per-row predicate for conditional/locked rows |
+| **Column visibility** | Built-in toggle menu; hide, show, or lock columns per your `ColumnDef` |
+| **Styling** | Tailwind v4-native with `classNames` overrides at every element — no CSS-in-JS, no shadow DOM. Themed via ~16 semantic OKLCH tokens ([`THEMING.md`](./THEMING.md)) |
+| **Render slots** | Replace toolbar, empty state, loading overlay, or row wrapper without touching internals |
+| **Accessibility** | `role="grid"` semantics, `aria-sort`, `aria-live` filter/pagination announcements, full keyboard navigation |
+| **Framework fit** | Next.js App Router ready — every entry point ships `"use client"` out of the box |
+| **TypeScript** | Fully generic over your row shape — column defs, cell renderers, and the table instance are all type-safe |
+
+---
+
+## Installation
+
+Get FacetUI running in your project in under five minutes.
+
+**1. Copy the component folder into your project:**
+
+```
+src/components/data-table/
+```
+
+**2. Install peer dependencies:**
+
+```bash
+npm install react-aria-components @tanstack/react-table lucide-react clsx tailwind-merge
+```
+
+> Installing the published `@facetui/react` package pulls in `@tanstack/react-table` for you; the line above is the full list for the copy-the-folder route.
+
+**3. Tailwind CSS v4 — no config step.** The utility classes are auto-detected from your source; there is no `content` array to update. (Still on Tailwind v3? Add `"./src/components/data-table/**/*.{ts,tsx}"` to your `content` globs and treat the v3→v4 utility renames in the components — `shadow-xs`, `rounded-xs`, `outline-hidden` — accordingly.)
+
+**4. Provide the FacetUI token contract.** The components are written against ~16 semantic CSS custom properties (`--background`, `--foreground`, `--border`, `--primary`, `--primary-foreground`, `--muted`, `--muted-foreground`, `--accent`, `--popover`, `--destructive`, `--ring`, …). Copy the `:root` / `.dark` blocks and the `@theme inline` mapping from [`src/index.css`](./src/index.css) into your global stylesheet — or, if your project already uses a [shadcn/ui](https://ui.shadcn.com) **v4** theme, the tokens are identical and already in place. See [`THEMING.md`](./THEMING.md) for the full token reference, dark mode, and a walkthrough for building your own theme or presets.
+
+> **Next.js App Router note:** All files include `"use client"` — no extra configuration required.
+
+---
+
+## Usage
+
+### Basic example
+
+```tsx
+import { DataTable } from "@/components/data-table";
+import type { ColumnDef } from "@/components/data-table";
+
+interface User {
+  id: string;
+  name: string;
+  email: string;
+  role: "admin" | "editor" | "viewer";
+}
+
+const columns: ColumnDef<User>[] = [
+  { id: "name",  header: "Name",  accessorKey: "name"  },
+  { id: "email", header: "Email", accessorKey: "email" },
+  { id: "role",  header: "Role",  accessorKey: "role"  },
+];
+
+const data: User[] = [
+  { id: "1", name: "Alice Johnson", email: "alice@example.com", role: "admin"  },
+  { id: "2", name: "Bob Smith",     email: "bob@example.com",   role: "editor" },
+  { id: "3", name: "Carol White",   email: "carol@example.com", role: "viewer" },
+];
+
+export default function UsersPage() {
+  return (
+    <DataTable
+      data={data}
+      columns={columns}
+      aria-label="Users table"
+      getRowId={(row) => row.id}
+    />
+  );
+}
+```
+
+This gives you: global search, client-side sorting on every column, column visibility toggle, row-level pagination, and a loading state — all with keyboard navigation and screen-reader support.
+
+---
+
+### Advanced example — custom cells, row selection, server-side data, and style overrides
+
+```tsx
+"use client";
+
+import { useState } from "react";
+import { DataTable } from "@/components/data-table";
+import type {
+  ColumnDef,
+  PaginationState,
+  SortingState,
+} from "@/components/data-table";
+
+interface Product {
+  id: string;
+  name: string;
+  category: string;
+  price: number;
+  stock: number;
+  status: "in_stock" | "low_stock" | "out_of_stock";
+}
+
+// ── Column definitions ──────────────────────────────────────────────────────
+
+const columns: ColumnDef<Product>[] = [
+  {
+    id: "name",
+    header: "Product",
+    accessorKey: "name",
+    size: 220,
+  },
+  {
+    id: "category",
+    header: "Category",
+    accessorKey: "category",
+    size: 140,
+  },
+  {
+    id: "price",
+    header: "Price",
+    accessorKey: "price",
+    size: 100,
+    // Custom cell — format as currency
+    cell: ({ value }) => (
+      <span className="font-mono tabular-nums">
+        {new Intl.NumberFormat("en-US", {
+          style: "currency",
+          currency: "USD",
+        }).format(value as number)}
+      </span>
+    ),
+  },
+  {
+    id: "stock",
+    header: "Stock",
+    accessorKey: "stock",
+    size: 80,
+    cell: ({ value }) => (
+      <span className="tabular-nums">{(value as number).toLocaleString()}</span>
+    ),
+  },
+  {
+    id: "status",
+    header: "Status",
+    accessorKey: "status",
+    size: 120,
+    enableSorting: false,
+    // Custom cell — status badge
+    cell: ({ value }) => {
+      const label = String(value).replace(/_/g, " ");
+      const styles = {
+        in_stock:      "bg-green-100 text-green-800",
+        low_stock:     "bg-yellow-100 text-yellow-800",
+        out_of_stock:  "bg-red-100   text-red-800",
+      } as const;
+      return (
+        <span
+          className={`inline-flex items-center rounded-full px-2 py-0.5
+                      text-xs font-medium capitalize
+                      ${styles[value as Product["status"]]}`}
+        >
+          {label}
+        </span>
+      );
+    },
+  },
+];
+
+// ── Page component ──────────────────────────────────────────────────────────
+
+export default function ProductsPage() {
+  // Lift sort + pagination state so changes trigger your API
+  const [sorting, setSorting]       = useState<SortingState[]>([]);
+  const [pagination, setPagination] = useState<PaginationState>({
+    pageIndex: 0,
+    pageSize: 10,
+  });
+
+  // Replace with your real data-fetching hook (React Query, SWR, etc.)
+  const { data, rowCount, isLoading } = useProducts({ sorting, pagination });
+
+  return (
+    <DataTable
+      // ── Data ───────────────────────────────────────────────────────────
+      data={data}
+      columns={columns}
+      getRowId={(row) => row.id}
+      isLoading={isLoading}
+
+      // ── Server-side mode ───────────────────────────────────────────────
+      manualSorting
+      manualPagination
+      manualFiltering
+      rowCount={rowCount}
+      onSortingChange={setSorting}
+      onPaginationChange={setPagination}
+
+      // ── Row selection ─────────────────────────────────────────────────
+      enableRowSelection
+      enableMultiRowSelection
+      onRowSelectionChange={(selected) => {
+        console.log("Selected IDs:", Object.keys(selected));
+      }}
+
+      // ── Layout & density ──────────────────────────────────────────────
+      density="compact"
+      pageSizeOptions={[10, 25, 50]}
+      aria-label="Products inventory table"
+
+      // ── Tailwind class overrides ──────────────────────────────────────
+      classNames={{
+        root:    "rounded-xl shadow-sm",
+        th:      "text-xs uppercase tracking-wider",
+        tr:      "odd:bg-muted/30",
+        toolbar: "px-1",
+      }}
+
+      // ── Render slots ──────────────────────────────────────────────────
+      renderToolbar={(table) => (
+        <div className="flex items-center justify-between py-2">
+          <h2 className="text-lg font-semibold">
+            Products
+            <span className="ml-2 text-sm font-normal text-muted-foreground">
+              ({table.filteredRowCount.toLocaleString()} items)
+            </span>
+          </h2>
+          <div className="flex gap-2">
+            <input
+              type="search"
+              placeholder="Search products…"
+              onChange={(e) => table.setGlobalFilter(e.target.value)}
+              className="h-8 rounded-md border border-input bg-background px-3 text-sm"
+            />
+            <button
+              type="button"
+              onClick={() => alert(`Exporting ${Object.keys(table.rowSelection).length} rows`)}
+              className="rounded-md bg-primary px-3 py-1.5 text-sm text-primary-foreground"
+            >
+              Export selected
+            </button>
+          </div>
+        </div>
+      )}
+
+      renderEmpty={() => (
+        <div className="flex flex-col items-center gap-3 py-20">
+          <p className="text-base font-medium">No products found</p>
+          <p className="text-sm text-muted-foreground">
+            Try a different search term or clear your filters.
+          </p>
+        </div>
+      )}
+
+      // Make each row navigable — works with Next.js <Link> too
+      renderRowWrapper={(row, children) => (
+        <tr
+          key={row.id}
+          role="row"
+          tabIndex={0}
+          onClick={() => window.location.assign(`/products/${row.original.id}`)}
+          onKeyDown={(e) => {
+            if (e.key === "Enter" || e.key === " ")
+              window.location.assign(`/products/${row.original.id}`);
+          }}
+          className="cursor-pointer"
+          aria-label={`View details for ${row.original.name}`}
+        >
+          {children}
+        </tr>
+      )}
+    />
+  );
+}
+```
+
+---
+
+### Using the headless hook directly
+
+When you need a completely custom render layer, bypass all primitives and drive the table yourself:
+
+```tsx
+"use client";
+
+import { useDataTable } from "@/components/data-table";
+
+export function MyCustomTable() {
+  const table = useDataTable({ data, columns, enableRowSelection: true });
+
+  return (
+    <div>
+      <input
+        value={table.globalFilter}
+        onChange={(e) => table.setGlobalFilter(e.target.value)}
+      />
+      {table.rows.map((row) => (
+        <div key={row.id} onClick={() => row.toggleSelected()}>
+          {table.columns.map((col) => (
+            <span key={col.id}>{/* your own render logic */}</span>
+          ))}
+        </div>
+      ))}
+    </div>
+  );
+}
+```
+
+---
+
+## Props API
+
+### `<DataTable>` props
+
+All props from `ColumnDef`, `PaginationOptions`, `SortingOptions`, `FilteringOptions`, `RowSelectionOptions`, and `RenderSlots` are accepted at the top level.
+
+#### Core
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `data` | `TData[]` | **required** | The array of data records to display. |
+| `columns` | `ColumnDef<TData>[]` | **required** | Column definitions. See [ColumnDef](#columndef) below. |
+| `getRowId` | `(row: TData, index: number) => string` | Row array index | Derive a stable unique id for each row. Provide this whenever rows can be reordered or filtered to prevent selection state from drifting. |
+| `isLoading` | `boolean` | `false` | Displays an animated overlay above the table. Does not unmount existing rows. |
+| `density` | `"compact" \| "default" \| "comfortable"` | `"default"` | Controls cell padding across the entire table. |
+| `classNames` | `ClassNameOverrides` | `{}` | Tailwind class overrides per element. See [ClassNameOverrides](#classnameoverrides). |
+| `style` | `CSSProperties` | — | Inline styles applied to the root `<div>`. |
+| `aria-label` | `string` | — | Accessible label for the `<table>` element. Required for WCAG compliance when there is no visible caption. |
+| `aria-describedby` | `string` | — | ID of an element that describes the table's purpose. |
+
+#### Pagination options
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `manualPagination` | `boolean` | `false` | When `true`, the component renders `data` as-is and does not slice it. You must handle slicing in your data-fetching layer. |
+| `rowCount` | `number` | — | Total rows across all pages. **Required** when `manualPagination` is `true` so the page count can be calculated. |
+| `pageSizeOptions` | `number[]` | `[10, 25, 50, 100]` | The page-size choices rendered in the pagination bar's dropdown. |
+| `onPaginationChange` | `(state: PaginationState) => void` | — | Called whenever the page index or page size changes. Use this to re-fetch from your API. |
+
+#### Sorting options
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `manualSorting` | `boolean` | `false` | When `true`, disables client-side sorting. The component fires `onSortingChange` and waits for you to pass sorted data back via `data`. |
+| `enableMultiSort` | `boolean` | `false` | Allow multiple columns to be sorted simultaneously. Users hold `Shift` to add a secondary sort. |
+| `onSortingChange` | `(state: SortingState[]) => void` | — | Called whenever the sort state changes. Each entry is `{ id: string; desc: boolean }`. |
+
+#### Filtering options
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `manualFiltering` | `boolean` | `false` | When `true`, disables client-side filtering. The component fires `onGlobalFilterChange` and renders whatever is in `data`. |
+| `globalFilter` | `string` | — | Controlled global filter value. Provide this to sync the search input with external state (e.g., a URL search param). |
+| `onGlobalFilterChange` | `(value: string) => void` | — | Called on every keystroke in the search input. |
+| `columnFilters` | `ColumnFiltersState` (`Array<{ id: string; value: unknown }>`) | `[]` | Per-column filter values. Applied as a case-insensitive substring match, ANDed together and combined with `globalFilter`. Controlled if provided, uncontrolled otherwise — pair with `table.setColumnFilters` for imperative control. |
+| `onColumnFiltersChange` | `(filters: ColumnFiltersState) => void` | — | Called whenever column-level filters change. |
+
+#### Row selection options
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `enableRowSelection` | `boolean \| ((row: Row<TData>) => boolean)` | `undefined` | `true` (or a function) auto-injects the checkbox column — no manual column setup required. Pass a function to make selectability conditional per row (e.g., `(row) => !row.original.locked`); rows that fail the check can't be selected individually or via select-all. Pass `false` to disable row selection entirely. |
+| `enableMultiRowSelection` | `boolean` | `true` | When `false`, selecting a new row automatically deselects the previous one. |
+| `onRowSelectionChange` | `(state: RowSelectionState) => void` | — | Called whenever selection changes. State is a `Record<rowId, true>`. |
+
+#### Render slots
+
+| Prop | Type | Description |
+|---|---|---|
+| `renderToolbar` | `(table: TableInstance<TData>) => ReactNode` | Replaces the entire default toolbar (search input + column toggle). Receives the live `table` instance so you can call `table.setGlobalFilter`, `table.rowSelection`, etc. |
+| `renderEmpty` | `() => ReactNode` | Replaces the default empty state shown when `rows.length === 0` and `isLoading` is false. |
+| `renderLoading` | `() => ReactNode` | Replaces the default spinner overlay shown when `isLoading` is true. |
+| `renderRowWrapper` | `(row: Row<TData>, children: ReactNode) => ReactNode` | Wraps each `<tr>`. Use this to make rows into Next.js `<Link>` elements, add `onClick` handlers, or attach drag-and-drop attributes. The `children` are the rendered `<td>` elements — you must render them inside your wrapper. |
+
+---
+
+### `ColumnDef<TData>`
+
+Passed as an element of the `columns` array.
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `id` | `string` | **required** | Unique column identifier. Used as the sort key, visibility key, and React key. |
+| `header` | `ReactNode \| ((ctx: HeaderContext<TData>) => ReactNode)` | **required** | Column header content. Pass a plain string for simple labels or a render function for custom headers with sort indicators, tooltips, etc. |
+| `accessorKey` | `keyof TData` | — | Key on the data object to read the cell value from. Provide either this or `accessorFn`, not both. |
+| `accessorFn` | `(row: TData) => unknown` | — | Function to derive the cell value. Use for computed values or deeply nested fields (e.g., `row.address.city`). |
+| `cell` | `(ctx: CellContext<TData>) => ReactNode` | Raw string | Custom cell renderer. Receives `{ row, column, value, table }`. The pre-extracted `value` saves you from calling the accessor yourself. |
+| `enableSorting` | `boolean` | `true` | Show a sort toggle on this column's header. Set to `false` for columns where sorting is meaningless (e.g., action columns). |
+| `enableHiding` | `boolean` | `true` | Include this column in the column-visibility toggle. Set to `false` for columns that must always be visible (e.g., a primary name column). |
+| `enableResizing` | `boolean` | `false` | Reserved for a future column-resize implementation. |
+| `size` | `number` | `150` | Initial column width in pixels, applied as a CSS `width` on the `<th>` and `<td>`. |
+| `minSize` | `number` | — | Minimum column width. Enforced when column resizing is enabled. |
+| `maxSize` | `number` | — | Maximum column width. Enforced when column resizing is enabled. |
+| `meta` | `Record<string, unknown>` | — | Arbitrary metadata. Useful for passing flags into custom cell or header renderers without adding them to the data shape. |
+
+---
+
+### `ClassNameOverrides`
+
+Passed to the `classNames` prop. Every key is optional. Values are Tailwind class strings; conflicts are resolved by `tailwind-merge`.
+
+| Key | Targets |
+|---|---|
+| `root` | The outermost `<div>` wrapping the entire component. |
+| `table` | The `<table>` element. |
+| `thead` | The `<thead>` element. |
+| `theadRow` | The `<tr>` inside `<thead>`. |
+| `th` | Every `<th>` cell. |
+| `tbody` | The `<tbody>` element. |
+| `tr` | Every data `<tr>` in `<tbody>`. |
+| `td` | Every `<td>` cell. |
+| `toolbar` | The toolbar `<div>` (search + column toggle). |
+| `pagination` | The pagination `<div>` (rows-per-page + navigation). |
+
+---
+
+### `TableInstance<TData>`
+
+The live table object passed to all render slots and accessible via `useDataTableContext()` in any child component.
+
+| Member | Type | Description |
+|---|---|---|
+| `rows` | `Row<TData>[]` | The current page's rows after filtering and sorting. |
+| `columns` | `RuntimeColumn<TData>[]` | Column definitions augmented with live state methods. |
+| `pagination` | `PaginationState` | Current `{ pageIndex, pageSize }`. |
+| `sorting` | `SortingState[]` | Active sort entries: `[{ id, desc }]`. |
+| `rowSelection` | `RowSelectionState` | A `Record<rowId, true>` of selected rows. |
+| `globalFilter` | `string` | Current search input value. |
+| `columnFilters` | `ColumnFiltersState` | Active per-column filter values. |
+| `pageCount` | `number` | Total number of pages. |
+| `filteredRowCount` | `number` | Total rows after filtering — use for "N results" status text. |
+| `getIsAllRowsSelected()` | `() => boolean` | Returns `true` if every row on the current page is selected. |
+| `getIsSomeRowsSelected()` | `() => boolean` | Returns `true` if at least one (but not all) rows are selected. |
+| `toggleAllRowsSelected(value?)` | `(value?: boolean) => void` | Select or deselect all rows on the current page. |
+| `setSorting(updater)` | `(updater) => void` | Imperatively set sorting state. Accepts a value or an updater function. |
+| `setPagination(updater)` | `(updater) => void` | Imperatively set pagination state. Accepts a value or an updater function. |
+| `setGlobalFilter(value)` | `(value: string) => void` | Imperatively set the global search filter and reset to page 0. |
+| `setColumnFilters(updater)` | `(updater) => void` | Imperatively set per-column filters and reset to page 0. Accepts a value or an updater function. |
+
+---
+
+### Headless hooks (standalone)
+
+Each hook can be used independently of `<DataTable>` when building fully custom table layouts.
+
+| Hook | Purpose |
+|---|---|
+| `useDataTable(props)` | The complete table state engine. Returns a `TableInstance`. |
+| `useColumnSort(options?)` | Sort state with a three-state toggle cycle (none → asc → desc → none). |
+| `usePagination(options?)` | Pagination state with `goToPage`, `nextPage`, `previousPage`, and `setPageSize` helpers. |
+| `useRowSelection(options?)` | Row selection state with `toggleRow`, `toggleAllRows`, and `clearSelection`. |
+| `useColumnVisibility(columns)` | Column show/hide state with `toggleColumn`, `showAll`, and `hideAll`. |
+| `useGlobalFilter(columns, options?)` | Global filter state with a `filterData(data)` helper for client-side use. |
+| `useDataTableContext<TData>()` | Access the nearest `<DataTable>`'s `TableInstance` from any descendant component. |
+
+---
+
+## Accessibility
+
+FacetUI targets **WCAG 2.1 Level AA** compliance.
+
+| Requirement | Implementation |
+|---|---|
+| Grid semantics | `<table role="grid">` with `role="row"`, `role="columnheader"`, and `role="gridcell"` on all descendants. |
+| Column sort state | `aria-sort="ascending \| descending \| none"` on every sortable `<th>`. |
+| Row position | `aria-rowindex` on every `<tr>` so assistive technology can report position in the full dataset, not just the current page. |
+| Row count | `aria-rowcount` on `<table>` reflects the true total. |
+| Loading state | `aria-busy="true"` on `<table>` while `isLoading` is active; overlay has `role="status"`. |
+| Live regions | Filter result count and page info use `aria-live="polite" aria-atomic="true"`. |
+| Keyboard navigation | Sort triggers and nav buttons are plain `<button>`s; the page-size selector and column-visibility menu are React Aria Components `Select` / `Menu` — fully reachable and activatable via keyboard, with focus containment while open. |
+| Checkboxes | React Aria Components `Checkbox` provides `role="checkbox"`, correct checked / indeterminate state (`aria-checked="mixed"` for the select-all tri-state), and a focus ring. |
+| Focus indicators | All interactive elements have `focus-visible:ring-2 focus-visible:ring-ring` — compliant with WCAG 2.4.11. |
+| Icon-only buttons | All icon-only elements carry `aria-label` or `aria-hidden="true"` to prevent decoration from being announced. |
+
+---
+
+## License
+
+Commercial license — see [`LICENSE.md`](./LICENSE.md) for full terms. In short: use the Software freely inside your own projects; redistributing, reselling, or publishing the source code itself is not permitted without written consent.
+
+## Security
+
+Found a vulnerability? Please don't open a public issue — see [`SECURITY.md`](./SECURITY.md) for how to report it responsibly.