@g4rcez/components 4.0.1 → 4.1.1

package/ai/docs/Step.md

@@ -0,0 +1,159 @@
+---
+title: Step
+description: Animated multi-step progress indicator with status tracking for checkout flows, onboarding, and wizards.
+package: "@g4rcez/components"
+export: "{ Step }"
+import: "import { Steps, Step } from '@g4rcez/components'"
+category: display
+---
+
+# Step
+
+Animated multi-step progress indicator with status tracking for checkout flows, onboarding, and wizards.
+
+## Import
+
+```tsx
+import { Steps, Step } from "@g4rcez/components";
+```
+
+## Props
+
+### Steps (Container)
+
+| Prop          | Type              | Default | Description                        |
+| ------------- | ----------------- | ------- | ---------------------------------- |
+| `currentStep` | `number`          | —       | Index of the currently active step |
+| `steps`       | `number`          | —       | Total number of steps              |
+| `children`    | `React.ReactNode` | —       | `Step` components                  |
+
+### Step
+
+| Prop             | Type         | Default | Description                                                                   |
+| ---------------- | ------------ | ------- | ----------------------------------------------------------------------------- |
+| `step`           | `number`     | —       | Index of this step                                                            |
+| `currentStep`    | `number`     | —       | Index of the currently active step (usually from parent)                      |
+| `title`          | `Label`      | —       | Step label                                                                    |
+| `status`         | `StepStatus` | —       | Override automatic status (`"active" \| "inactive" \| "complete" \| "error"`) |
+| `titleClassName` | `string`     | —       | Additional classes for the title text                                         |
+
+Standard `<button>` props are also forwarded (e.g. `onClick`, `disabled`).
+
+## Step Statuses
+
+| Status     | Visual             | Icon                |
+| ---------- | ------------------ | ------------------- |
+| `active`   | Primary color ring | Step number         |
+| `inactive` | Muted border       | Step number         |
+| `complete` | Success color fill | Animated check mark |
+| `error`    | Danger color fill  | Animated X mark     |
+
+Status is derived automatically from `step` vs. `currentStep` unless overridden via `status`.
+
+## Design Tokens
+
+Tokens this component reads. Customize by overriding these CSS variables in your theme.
+
+| Token                                   | CSS Variable                          | Purpose                            |
+| --------------------------------------- | ------------------------------------- | ---------------------------------- |
+| `bg-primary` / `border-primary`         | `--primary-DEFAULT`                   | Active step fill and border        |
+| `text-primary-foreground`               | `--primary-foreground`                | Active step text                   |
+| `bg-success` / `border-success`         | `--success-DEFAULT`                   | Complete step fill and border      |
+| `text-success-foreground`               | `--success-foreground`                | Complete step check icon           |
+| `bg-danger` / `border-danger`           | `--danger-DEFAULT` / `--danger-hover` | Error step fill and border         |
+| `text-danger-foreground`                | `--danger-foreground`                 | Error step X icon                  |
+| `text-disabled`                         | `--disabled`                          | Inactive step text                 |
+| `bg-card-border` / `border-card-border` | `--card-border`                       | Connector line and inactive border |
+| `bg-background`                         | `--background`                        | Inactive step background           |
+
+## Examples
+
+### Basic Steps
+
+```tsx
+<Steps currentStep={2} steps={3}>
+    <Step step={1} currentStep={2} title="Account" />
+    <Step step={2} currentStep={2} title="Profile" />
+    <Step step={3} currentStep={2} title="Review" />
+</Steps>
+```
+
+### Interactive Wizard
+
+```tsx
+function Wizard() {
+    const [currentStep, setCurrentStep] = useState(1);
+
+    return (
+        <div className="space-y-8">
+            <Steps currentStep={currentStep} steps={4}>
+                <Step step={1} currentStep={currentStep} title="Account" onClick={() => setCurrentStep(1)} />
+                <Step step={2} currentStep={currentStep} title="Profile" onClick={() => setCurrentStep(2)} />
+                <Step step={3} currentStep={currentStep} title="Payment" onClick={() => setCurrentStep(3)} />
+                <Step step={4} currentStep={currentStep} title="Review" onClick={() => setCurrentStep(4)} />
+            </Steps>
+
+            <div className="p-6 rounded-card border border-card-border bg-card-background">
+                {currentStep === 1 && <AccountForm />}
+                {currentStep === 2 && <ProfileForm />}
+                {currentStep === 3 && <PaymentForm />}
+                {currentStep === 4 && <ReviewSummary />}
+            </div>
+        </div>
+    );
+}
+```
+
+### With Error State
+
+```tsx
+<Steps currentStep={2} steps={3}>
+    <Step step={1} currentStep={2} title="Identity" />
+    <Step step={2} currentStep={2} title="Payment" status="error" />
+    <Step step={3} currentStep={2} title="Finish" />
+</Steps>
+```
+
+### Checkout Flow
+
+```tsx
+function CheckoutSteps({ step }: { step: number }) {
+    return (
+        <Steps currentStep={step} steps={3}>
+            <Step step={1} currentStep={step} title="Cart" />
+            <Step step={2} currentStep={step} title="Shipping" />
+            <Step step={3} currentStep={step} title="Confirmation" />
+        </Steps>
+    );
+}
+```
+
+## Do
+
+- Provide clear, concise `title` labels for each step.
+- Keep the total number of steps manageable (3–5 is ideal).
+- Use `status="error"` to clearly indicate where a user needs to return and fix a problem.
+- Use `onClick` on `Step` to enable backward navigation in wizards.
+
+## Don't
+
+- Don't pass raw Tailwind color classes for step styling — the component derives colors from CSS variables.
+- Don't use arbitrary Tailwind values (`bg-[#abc]`) — override CSS variables in your `@theme` block.
+- Don't hide critical information in steps the user hasn't yet seen.
+- Don't use `Step` for non-linear navigation without a clear sequential intent.
+
+## Accessibility
+
+- Each `Step` renders as a `<button>` element, making it focusable and keyboard-operable.
+- Icons use `aria-hidden` to prevent redundant screen reader announcements.
+- The `Steps` container provides a logical visual grouping for the process.
+
+## Data Attributes
+
+- `data-step` — the step index number, applied to each step's `<button>`.
+
+## Notes
+
+- Connector lines between steps are shown only on `xl` breakpoints (hidden on smaller screens where steps stack vertically).
+- Animations use Framer Motion (`motion/react`): the step circle animates between status colors, and the check/X icons draw in with `pathLength`.
+- The `Steps` component tracks `previousStep` internally to orchestrate staggered transition delays when jumping multiple steps at once.

package/{dist/ai → ai}/docs/Switch.md

@@ -21,27 +21,27 @@ import { Switch } from "@g4rcez/components/switch";
 
 Inherits all standard HTML `input[type="checkbox"]` attributes, plus:
 
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `children` | `React.ReactNode` | — | Label text or element displayed next to the switch. |
-| `onCheck` | `(nextValue: boolean) => void` | — | Called with the new boolean value after toggling. |
-| `error` | `string` | — | Error message displayed below the switch. |
-| `loading` | `boolean` | `false` | Disables the switch and signals a pending operation. |
-| `container` | `string` | — | Additional CSS classes for the outer `<fieldset>`. |
+| Prop        | Type                           | Default | Description                                          |
+| ----------- | ------------------------------ | ------- | ---------------------------------------------------- |
+| `children`  | `React.ReactNode`              | —       | Label text or element displayed next to the switch.  |
+| `onCheck`   | `(nextValue: boolean) => void` | —       | Called with the new boolean value after toggling.    |
+| `error`     | `string`                       | —       | Error message displayed below the switch.            |
+| `loading`   | `boolean`                      | `false` | Disables the switch and signals a pending operation. |
+| `container` | `string`                       | —       | Additional CSS classes for the outer `<fieldset>`.   |
 
 ## Design Tokens
 
 Tokens this component reads. Customize by overriding these CSS variables in your theme.
 
-| Token | CSS Variable | Purpose |
-|-------|-------------|---------|
+| Token                | CSS Variable        | Purpose                         |
+| -------------------- | ------------------- | ------------------------------- |
 | `bg-input-switch-bg` | `--input-switch-bg` | Track background when unchecked |
-| `bg-primary` | `--primary` | Track background when checked |
-| `bg-disabled` | `--disabled` | Thumb fill when unchecked |
-| `bg-input-switch` | `--input-switch` | Thumb fill when checked |
-| `focus:ring-primary` | `--primary` | Focus ring on the toggle button |
-| `text-danger` | `--danger` | Error message color |
-| `text-foreground` | `--foreground` | Label text color |
+| `bg-primary`         | `--primary`         | Track background when checked   |
+| `bg-disabled`        | `--disabled`        | Thumb fill when unchecked       |
+| `bg-input-switch`    | `--input-switch`    | Thumb fill when checked         |
+| `focus:ring-primary` | `--primary`         | Focus ring on the toggle button |
+| `text-danger`        | `--danger`          | Error message color             |
+| `text-foreground`    | `--foreground`      | Label text color                |
 
 ## Themes
 
@@ -55,11 +55,11 @@ The switch appearance is driven entirely by design tokens. Override them in your
 import { Switch } from "@g4rcez/components/switch";
 
 export default function NotificationsToggle() {
-  return (
-    <Switch defaultChecked onChange={(e) => console.log(e.target.checked)}>
-      Enable notifications
-    </Switch>
-  );
+    return (
+        <Switch defaultChecked onChange={(e) => console.log(e.target.checked)}>
+            Enable notifications
+        </Switch>
+    );
 }
 ```
 
@@ -70,13 +70,13 @@ import { useState } from "react";
 import { Switch } from "@g4rcez/components/switch";
 
 export default function DarkModeToggle() {
-  const [enabled, setEnabled] = useState(false);
+    const [enabled, setEnabled] = useState(false);
 
-  return (
-    <Switch checked={enabled} onCheck={setEnabled}>
-      Dark mode
-    </Switch>
-  );
+    return (
+        <Switch checked={enabled} onCheck={setEnabled}>
+            Dark mode
+        </Switch>
+    );
 }
 ```
 
@@ -86,11 +86,7 @@ export default function DarkModeToggle() {
 import { Switch } from "@g4rcez/components/switch";
 
 export default function SyncSwitch() {
-  return (
-    <Switch loading>
-      Syncing data…
-    </Switch>
-  );
+    return <Switch loading>Syncing data…</Switch>;
 }
 ```
 
@@ -100,11 +96,7 @@ export default function SyncSwitch() {
 import { Switch } from "@g4rcez/components/switch";
 
 export default function TermsSwitch() {
-  return (
-    <Switch error="You must accept the terms to continue">
-      Accept terms and conditions
-    </Switch>
-  );
+    return <Switch error="You must accept the terms to continue">Accept terms and conditions</Switch>;
 }
 ```
 
@@ -114,19 +106,17 @@ export default function TermsSwitch() {
 import { Switch } from "@g4rcez/components/switch";
 
 export default function PrivacySettings() {
-  return (
-    <div className="flex flex-col gap-base">
-      <Switch defaultChecked onCheck={(v) => updateSetting("emails", v)}>
-        Receive marketing emails
-      </Switch>
-      <Switch onCheck={(v) => updateSetting("analytics", v)}>
-        Share analytics data
-      </Switch>
-      <Switch defaultChecked onCheck={(v) => updateSetting("notifications", v)}>
-        Push notifications
-      </Switch>
-    </div>
-  );
+    return (
+        <div className="flex flex-col gap-base">
+            <Switch defaultChecked onCheck={(v) => updateSetting("emails", v)}>
+                Receive marketing emails
+            </Switch>
+            <Switch onCheck={(v) => updateSetting("analytics", v)}>Share analytics data</Switch>
+            <Switch defaultChecked onCheck={(v) => updateSetting("notifications", v)}>
+                Push notifications
+            </Switch>
+        </div>
+    );
 }
 ```
 
@@ -154,11 +144,11 @@ export default function PrivacySettings() {
 
 ## Data Attributes
 
-| Attribute | Element | Value | Description |
-|-----------|---------|-------|-------------|
-| `data-component` | `fieldset` | `"switch"` | Identifies the component. |
-| `data-checked` | `input`, `button`, thumb `span` | `"true" \| "false"` | Reflects the checked state for CSS targeting. |
-| `data-trigger` | `input` | `"change"` | Used internally to track the synthetic change event. |
+| Attribute        | Element                         | Value               | Description                                          |
+| ---------------- | ------------------------------- | ------------------- | ---------------------------------------------------- |
+| `data-component` | `fieldset`                      | `"switch"`          | Identifies the component.                            |
+| `data-checked`   | `input`, `button`, thumb `span` | `"true" \| "false"` | Reflects the checked state for CSS targeting.        |
+| `data-trigger`   | `input`                         | `"change"`          | Used internally to track the synthetic change event. |
 
 ## Notes
 

package/ai/docs/Table.md

@@ -0,0 +1,286 @@
+---
+title: Table
+description: Virtualized, sortable, filterable data table with column reordering, grouping, and pagination.
+package: "@g4rcez/components"
+export: "{ Table, createColumns, useTablePreferences, ColType }"
+import: "import { Table, createColumns, useTablePreferences, ColType } from '@g4rcez/components/table'"
+category: table
+---
+
+# Table
+
+Virtualized, sortable, filterable data table with column reordering, grouping, and pagination.
+
+## Import
+
+```tsx
+import { Table, createColumns, useTablePreferences, ColType } from "@g4rcez/components/table";
+```
+
+## Props
+
+### Table
+
+| Prop           | Type                               | Default | Description                                                                      |
+| -------------- | ---------------------------------- | ------- | -------------------------------------------------------------------------------- |
+| `name`         | `string`                           | —       | Unique identifier used to persist user preferences in `localStorage`.            |
+| `cols`         | `Col<T>[]`                         | —       | Column definitions produced by `createColumns`.                                  |
+| `rows`         | `T[]`                              | —       | Data array to render. Each element maps to a table row.                          |
+| `loading`      | `boolean`                          | `false` | Replaces rows with animated skeleton cells while data loads.                     |
+| `loadingMore`  | `boolean`                          | `false` | Shows a pulse footer bar for infinite-scroll loading indicators.                 |
+| `operations`   | `boolean`                          | `true`  | Toggles the metadata bar (bulk filter, sort, group controls).                    |
+| `inlineFilter` | `boolean`                          | `true`  | Enables per-column filter dropdowns in the header row.                           |
+| `inlineSorter` | `boolean`                          | `true`  | Enables per-column sort toggles in the header row.                               |
+| `sticky`       | `number \| null`                   | —       | `top` offset in px for the sticky header. Pass `null` to disable stickiness.     |
+| `Aside`        | `React.FC<CellAsideElement<T>>`    | —       | Component rendered before the first cell in every row (e.g., row-level actions). |
+| `pagination`   | `TablePagination`                  | —       | Pagination configuration. When provided, a footer with page controls is shown.   |
+| `reference`    | `keyof T`                          | —       | Field used as the stable row key.                                                |
+| `useControl`   | `boolean`                          | `false` | When `true`, disables internal filtering/sorting so you can drive it externally. |
+| `onScrollEnd`  | `() => void`                       | —       | Called when the user scrolls to the last row (infinite scroll trigger).          |
+| `getScrollRef` | `() => HTMLElement \| undefined`   | —       | Returns a custom scroll container instead of `window`.                           |
+| `getRowProps`  | `(row: T) => ComponentProps<"tr">` | —       | Merge arbitrary `<tr>` props (e.g., `onClick`, `className`) per row.             |
+| `set`          | `(v: TableGetters<T>) => void`     | —       | External callback invoked whenever internal table state changes.                 |
+
+### createColumns
+
+```tsx
+createColumns<T>((c) => {
+  c.add(id, thead, options?)
+  c.remove(id)
+  c.filter(predicate)
+  c.getAll()
+})
+```
+
+| Builder method | Signature                                                                 | Description                               |
+| -------------- | ------------------------------------------------------------------------- | ----------------------------------------- |
+| `add`          | `(id: AllPaths<T>, thead: ReactNode, options?: ColOptions<T, K>) => void` | Registers a column.                       |
+| `remove`       | `(id: AllPaths<T>) => void`                                               | Removes a column by id.                   |
+| `filter`       | `(c: (col: Col<T>) => boolean) => Col<T>[]`                               | Filters the column list in-place.         |
+| `getAll`       | `() => Col<T>[]`                                                          | Returns a copy of all registered columns. |
+
+### ColOptions
+
+| Option        | Type                                   | Default        | Description                                                                  |
+| ------------- | -------------------------------------- | -------------- | ---------------------------------------------------------------------------- |
+| `type`        | `ColType`                              | `ColType.Text` | Data type (`Text`, `Number`, `Boolean`, `Select`). Affects filter operators. |
+| `allowSort`   | `boolean`                              | `true`         | Whether this column can be sorted.                                           |
+| `allowFilter` | `boolean`                              | `true`         | Whether this column shows a filter control.                                  |
+| `headerLabel` | `string`                               | —              | Overrides the column header text used in the filter/sort metadata bar.       |
+| `Element`     | `React.FC<CellPropsElement<T, K>>`     | —              | Custom cell renderer. Receives `{ row, value, rowIndex, matrix, col }`.      |
+| `thProps`     | `HTMLAttributes<HTMLTableCellElement>` | —              | Extra props forwarded to the `<th>` element.                                 |
+| `cellProps`   | `HTMLAttributes<HTMLTableCellElement>` | —              | Extra props forwarded to each `<td>` element.                                |
+
+### TablePagination
+
+| Field          | Type                                                                    | Description                                                               |
+| -------------- | ----------------------------------------------------------------------- | ------------------------------------------------------------------------- |
+| `size`         | `number`                                                                | Current page size.                                                        |
+| `pages`        | `number`                                                                | Total number of pages.                                                    |
+| `current`      | `number`                                                                | Current page index (1-based).                                             |
+| `hasNext`      | `boolean`                                                               | Whether a next page exists.                                               |
+| `hasPrevious`  | `boolean`                                                               | Whether a previous page exists.                                           |
+| `totalItems`   | `number`                                                                | Total row count across all pages.                                         |
+| `sizes`        | `number[]`                                                              | Optional list of selectable page sizes.                                   |
+| `onChangeSize` | `(size: number) => void`                                                | Called when the user selects a different page size.                       |
+| `asLink`       | `React.FC<{ href: number \| "previous" \| "next"; className: string }>` | Polymorphic page button — supply a router `Link` for deep-linkable pages. |
+
+### useTablePreferences
+
+Persists column order, active filters, sorters, and groups in `localStorage` keyed by `name`.
+
+```tsx
+const prefs = useTablePreferences("users-table", columns, options?);
+// Spread into <Table {...prefs} rows={data} />
+```
+
+| Parameter | Type                       | Description                                                                |
+| --------- | -------------------------- | -------------------------------------------------------------------------- |
+| `name`    | `string`                   | Storage key (`@components/table-{name}`).                                  |
+| `cols`    | `Col<T>[]`                 | Initial column definitions.                                                |
+| `options` | `Partial<TableGetters<T>>` | Optional initial state overrides for filters, sorters, groups, pagination. |
+
+## Design Tokens
+
+Tokens this component reads. Customize by overriding these CSS variables in your theme.
+
+| Token                 | CSS Variable         | Purpose                                 |
+| --------------------- | -------------------- | --------------------------------------- |
+| `bg-table-header`     | `--table-header`     | Column header background                |
+| `bg-table-background` | `--table-background` | Table body background                   |
+| `border-table-border` | `--table-border`     | Column separator and row divider color  |
+| `shadow-shadow-table` | `--shadow-table`     | Table card shadow                       |
+| `bg-card-background`  | `--card-background`  | Footer and loading-more bar background  |
+| `text-foreground`     | `--foreground`       | Default cell text color                 |
+| `text-primary`        | `--primary`          | Active filter / sort accent color       |
+| `bg-muted`            | `--muted`            | Hover background for metadata bar items |
+
+The `--table-cell-padding` CSS variable controls cell padding (default `0.75rem`). Override it via `className` on `<Table>`.
+
+## Column Types
+
+| `ColType`         | Enum value  | Filter operators available               |
+| ----------------- | ----------- | ---------------------------------------- |
+| `ColType.Text`    | `"text"`    | contains, equals, starts with, ends with |
+| `ColType.Number`  | `"number"`  | =, ≠, >, <, ≥, ≤                         |
+| `ColType.Boolean` | `"boolean"` | is true, is false                        |
+| `ColType.Select`  | `"select"`  | equals                                   |
+
+## Examples
+
+### Basic table
+
+```tsx
+import { Table, createColumns } from "@g4rcez/components/table";
+
+type User = { id: string; name: string; email: string };
+
+const columns = createColumns<User>((c) => {
+    c.add("id", "ID");
+    c.add("name", "Name");
+    c.add("email", "Email");
+});
+
+export function UsersTable({ users }: { users: User[] }) {
+    return <Table name="users" cols={columns} rows={users} />;
+}
+```
+
+### Custom cell renderer
+
+```tsx
+import { Table, createColumns, ColType } from "@g4rcez/components/table";
+import { Tag } from "@g4rcez/components/tag";
+
+type Product = { sku: string; name: string; price: number; active: boolean };
+
+const columns = createColumns<Product>((c) => {
+    c.add("sku", "SKU");
+    c.add("name", "Product Name", { allowFilter: true, allowSort: true });
+    c.add("price", "Price", {
+        type: ColType.Number,
+        Element: ({ value }) => (
+            <span className="font-mono tabular-nums">{value.toLocaleString("en-US", { style: "currency", currency: "USD" })}</span>
+        ),
+    });
+    c.add("active", "Status", {
+        type: ColType.Boolean,
+        Element: ({ value }) => (
+            <Tag theme={value ? "success" : "neutral"} size="small">
+                {value ? "Active" : "Inactive"}
+            </Tag>
+        ),
+    });
+});
+```
+
+### Persisted preferences
+
+```tsx
+import { Table, createColumns, useTablePreferences } from "@g4rcez/components/table";
+
+const baseColumns = createColumns<Order>((c) => {
+    c.add("id", "Order ID");
+    c.add("status", "Status");
+    c.add("total", "Total");
+});
+
+export function OrdersTable({ orders }: { orders: Order[] }) {
+    const prefs = useTablePreferences("orders-table", baseColumns);
+    return <Table {...prefs} rows={orders} />;
+}
+```
+
+### Server-side pagination
+
+```tsx
+<Table
+    name="invoices"
+    cols={columns}
+    rows={pageData}
+    useControl
+    pagination={{
+        current: page,
+        pages: totalPages,
+        size: pageSize,
+        totalItems: totalCount,
+        hasNext: page < totalPages,
+        hasPrevious: page > 1,
+        sizes: [10, 25, 50],
+        onChangeSize: setPageSize,
+        asLink: ({ href, className, children }) => (
+            <a href={`?page=${href}`} className={className}>
+                {children}
+            </a>
+        ),
+    }}
+/>
+```
+
+### Row-level actions with Aside
+
+```tsx
+import { TrashIcon, PencilIcon } from "@phosphor-icons/react";
+
+<Table
+    name="contacts"
+    cols={columns}
+    rows={contacts}
+    Aside={({ row }) => (
+        <div className="flex gap-1">
+            <button onClick={() => edit(row)} aria-label="Edit">
+                <PencilIcon size={14} />
+            </button>
+            <button onClick={() => remove(row)} aria-label="Delete" className="hover:text-danger">
+                <TrashIcon size={14} />
+            </button>
+        </div>
+    )}
+/>;
+```
+
+### Infinite scroll
+
+```tsx
+<Table name="feed" cols={columns} rows={items} loadingMore={isFetchingNextPage} onScrollEnd={fetchNextPage} />
+```
+
+## Do
+
+- Provide a unique `name` to ensure each table has its own isolated `localStorage` slot.
+- Use `createColumns` for full TypeScript path inference on deeply nested fields.
+- Supply a custom `Element` for cells that need formatting, interactive controls, or icons.
+- Use `useTablePreferences` when users should be able to persist their column arrangement across sessions.
+- Pass `useControl={true}` and manage data externally when filtering/sorting must happen server-side.
+- Use design-token classes for wrapper elements (`bg-table-header`, `bg-table-background`, `border-table-border`).
+
+## Don't
+
+- Don't pass raw Tailwind color classes (`bg-blue-500`, `text-white`, `border-gray-300`) — use design tokens instead.
+- Don't use arbitrary Tailwind values (`bg-[#abc]`, `bg-[--my-var]`) — override CSS variables in your `@theme` block instead.
+- Don't render `<Table>` without a `name` — preferences and DOM ids rely on it.
+- Don't put heavy rendering logic directly inside `rows` array transformation; use `Element` cells instead so virtualization can skip off-screen rows.
+- Don't use `Table` for single-row or trivial datasets — a plain list or card layout is more appropriate.
+
+## Accessibility
+
+- Renders `role="table"`, `role="rowgroup"`, `role="row"`, and `role="columnheader"` for screen-reader semantics.
+- Sort state is exposed via `aria-sort="ascending | descending | none"` on each `<th>`.
+- Column headers are keyboard-accessible drag targets; column resizing also supports `ArrowLeft`/`ArrowRight` keys (hold `Shift` for larger steps; double-click resets to auto width).
+- `aria-busy` on column headers signals loading state to assistive technologies.
+- Empty state renders the `Empty` component with a visible placeholder instead of an empty table body.
+- Virtualization uses `react-virtuoso` with `useWindowScroll` so native keyboard scrolling and focus management continue to work.
+
+## Data Attributes
+
+- `data-tableheader="{colId}"` — present on every `<th>`, used by the column-resizing logic to update `style.width`.
+- `data-resized="true"` — set on a `<th>` after the user manually resizes that column.
+- `data-type="resizer"` — identifies the drag handle element within each header cell.
+
+## Notes
+
+- Column reordering uses `motion/react`'s `Reorder.Group` / `Reorder.Item`, so columns animate smoothly to their new positions.
+- Internal filtering uses `linq-arrays`. Numeric filters operate on `Number.isNaN`-safe values; empty string filters are skipped.
+- `useTablePreferences` merges saved columns back against the current definition so new columns added in code always appear, even if a user has a stale snapshot in storage.
+- The `--table-cell-padding` variable can be set per breakpoint by adding it directly to `className`: `className="[--table-cell-padding:0.5rem] @md:[--table-cell-padding:1rem]"`.
+- Pass `getScrollRef={getModalScrollerRef}` (exported from the same subpath) when embedding a `Table` inside a `Modal` to fix virtualization scroll detection.