jattac.libs.web.responsive-table 0.12.0-rc.4 → 0.12.0

package/README.md

@@ -144,38 +144,97 @@ For a deep dive into more complex scenarios, see the **[Handling Interactive Ele
 
 ## Expandable Rows
 
-Pass `expandRowRenderer` to reveal arbitrary content below any row. Return `null` or `undefined` for rows that should not be expandable — only those rows get a toggle.
+Pass `expandRowRenderer` to reveal arbitrary content below any row. Each expandable row gets a solid chevron toggle (▶ collapsed, ▾ expanded) on a muted blue bar. Returning `null` or `undefined` for a row suppresses its toggle entirely — that row renders flat with no visual affordance.
 
 ```tsx
 <ResponsiveTable
   data={orders}
   columnDefinitions={columns}
-  expandRowRenderer={(order) => (
-    <OrderLineItems orderId={order.id} />
-  )}
+  expandRowRenderer={(order) => <OrderLineItems orderId={order.id} />}
 />
 ```
 
-The renderer receives both the row and its display-order index:
+**Selectively expandable** — only rows where the renderer returns content get a toggle:
+
+```tsx
+expandRowRenderer={(order) =>
+  order.lineItems.length > 0
+    ? <OrderLineItems order={order} />
+    : null
+}
+```
+
+**Using `rowIndex`** — the renderer receives both the row object and its current display-order index. Useful for position-based formatting, alternating detail styles, or correlating with a parallel index-aligned array:
 
 ```tsx
 expandRowRenderer={(row, rowIndex) => (
-  <div>Row {rowIndex}: <pre>{JSON.stringify(row, null, 2)}</pre></div>
+  <DetailPanel row={row} zebra={rowIndex % 2 === 0} />
 )}
 ```
 
-Selectively expandable — rows where the renderer returns `null` render at zero height with no toggle:
+> `rowIndex` is the **display-order** index (post-sort, post-filter) — it changes when the user re-sorts. For stable data correlation across renders, use the row's own identifier field (`row.id`, etc.).
+
+**Customising the chevron** — override color, size, or any other style via `expandChevronClassName`:
 
 ```tsx
-expandRowRenderer={(row) =>
-  row.hasDetails ? <DetailPanel row={row} /> : null
+// Accent color from your design system
+<ResponsiveTable
+  expandChevronClassName="my-brand-chevron"
+  expandRowRenderer={(row) => <Detail row={row} />}
+  ...
+/>
+```
+
+```css
+/* your stylesheet */
+.my-brand-chevron {
+  color: #7c3aed;   /* purple accent */
+  font-size: 2rem;
 }
 ```
 
 **Recommendations**
-- Provide `selectionProps` with a `rowIdKey` when your data has a stable identifier. The expand state is keyed by row ID, so expand/collapse survives re-sorts and filter changes correctly.
-- `rowIndex` reflects the current **display order** (post-sort, post-filter). Use `row.id` or equivalent for stable cross-render correlation.
-- Detail content is lazy-mounted — the component only renders on first expand, then stays mounted so the collapse animation plays smoothly.
+- Provide `selectionProps` with a `rowIdKey` when your data has a stable identifier. Expand state is keyed by row ID, so open panels survive re-sorts and filter changes.
+- Detail content is **lazy-mounted** — the panel component is not created until first expand, then stays mounted so the collapse animation plays correctly. Heavy components are therefore only instantiated on demand.
+- Expand and `onRowClick` coexist safely — the chevron bar carries `data-rt-ignore-row-click` so tapping the toggle never fires the row click handler.
+- Works identically in both desktop (table row) and mobile (card) layouts.
+
+---
+
+## Row Interaction & Feedback
+
+When `onRowClick` or `selectionProps` is provided, the table delivers tactile interaction feedback at every phase of the click:
+
+| Phase | Desktop | Mobile |
+| :--- | :--- | :--- |
+| **Hover** | Subtle background lightening | Card lifts 4px with enhanced shadow |
+| **Press (`:active`)** | Background deepens — confirms the press registered | Card compresses back to 1px lift |
+| **Release / Selected** | Background sweeps to the selection tint (150ms transition) | Same tint + primary-color left border |
+| **Keyboard focus** | 2px primary-color outline (`:focus-visible` only — not shown on mouse click) | Same |
+
+**Rationale** — each phase is distinct so users receive unambiguous confirmation that their input was received, without animations that feel slow or decorative. The `:active` state is the most critical: it fires in the 80–150ms window of the press itself, before any state change, so even users on slow networks feel an immediate response.
+
+**Keyboard navigation** — all clickable rows and cards have `tabIndex=0` and a `:focus-visible` ring. Tab through rows; press Enter or Space to trigger `onRowClick`.
+
+**Combining with `onRowClick` and selection:**
+
+```tsx
+<ResponsiveTable
+  data={employees}
+  columnDefinitions={columns}
+  onRowClick={(employee) => navigate(`/employees/${employee.id}`)}
+  selectionProps={{
+    rowIdKey: 'id',
+    mode: 'multiple',
+    onSelectionChange: (selected) => setSelected(selected),
+  }}
+/>
+```
+
+**Best practices**
+- Always pair `onRowClick` with a visible hover state cue (the default cursor change handles this automatically).
+- If rows contain buttons or links, use `data-rt-ignore-row-click` on those elements so inner interactions don't also trigger the row handler.
+- For selection, always provide `rowIdKey` pointing to a stable unique field — this ensures expand state and selection state both survive sort/filter changes.
 
 ---
 

package/docs/api.md

@@ -36,6 +36,52 @@ This document contains the exhaustive technical specification for the Responsive
 | `onPageChange` | `(page: number) => void` | Callback fired when the current page changes. |
 | `onDataSourceError` | `(error: Error) => void` | Callback fired when a dataSource fetch fails. |
 | `expandRowRenderer` | `(row: TData, rowIndex: number) => ReactNode` | Renders collapsible detail content below a row. Return `null`/`undefined` for no toggle on that row. |
+| `expandChevronClassName` | `string` | Custom CSS class applied to the chevron icon `<span>`. Use to override color, size, or any other style. |
+
+### Row Interaction & Visual Feedback (`onRowClick`)
+
+When `onRowClick` or `selectionProps` is provided, the table applies a full interaction state machine to every clickable row — no additional configuration required.
+
+| State | Desktop (`<tr>`) | Mobile (card) |
+| :--- | :--- | :--- |
+| **Default** | Stripe / base background | Card with subtle shadow |
+| **Hover** | Background lightens (`--table-row-hover-bg`) | Card lifts 4px, shadow deepens |
+| **Active (press)** | Background deepens to `#dde3ea` (80ms) | Card compresses to 1px lift, shadow reduces |
+| **Selected** | Background sweeps to `#e7f1ff` (150ms transition) | Same tint + 4px primary-color left border |
+| **Focus (keyboard)** | 2px primary-color `outline` (`:focus-visible` only) | Same |
+
+All clickable rows and cards receive `tabIndex=0`, making the table fully keyboard-navigable. Press **Tab** to move between rows, **Enter** or **Space** to trigger `onRowClick`.
+
+**Use cases**
+- Navigation: `onRowClick={(row) => navigate(`/detail/${row.id}`)}`
+- Inline drawer or modal trigger
+- Combined with `selectionProps` for multi-select workflows
+
+```tsx
+// Navigation on click
+<ResponsiveTable
+  data={invoices}
+  columnDefinitions={columns}
+  onRowClick={(invoice) => router.push(`/invoices/${invoice.id}`)}
+/>
+
+// Selection + click
+<ResponsiveTable
+  data={employees}
+  columnDefinitions={columns}
+  selectionProps={{
+    rowIdKey: 'id',
+    mode: 'multiple',
+    onSelectionChange: (selected) => setSelected(selected),
+  }}
+  onRowClick={(employee) => setPreview(employee)}
+/>
+```
+
+**Best practices**
+- Use `data-rt-ignore-row-click` on buttons and links inside cells so inner interactions do not also fire the row handler — see [Handling Interactive Elements](./handling-interactive-elements.md).
+- Always provide `selectionProps.rowIdKey` pointing to a stable unique field when using selection — prevents state drift when rows are sorted or filtered.
+- The `:active` feedback is immediate by design (80ms transition-in). Do not suppress it via CSS — it is the primary signal that the press registered before any async work begins.
 
 ### IResponsiveTableColumnDefinition
 The primary configuration interface for defining column-level behavior and rendering logic.
@@ -83,13 +129,15 @@ interface IResponsiveTableColumnDefinition<TData> {
 />
 ```
 
-### Expandable Rows (`expandRowRenderer`)
+### Expandable Rows (`expandRowRenderer`, `expandChevronClassName`)
+
+#### `expandRowRenderer`
 
 ```typescript
 expandRowRenderer?: (row: TData, rowIndex: number) => ReactNode
 ```
 
-Attaches a collapsible detail panel below each row. The renderer is called for every row on each render — return `null` or `undefined` to suppress the toggle for that row; return a `ReactNode` to show a `+`/`−` toggle that animates the panel open and closed.
+Attaches a collapsible detail panel below each row. A solid chevron indicator (▶ collapsed, ▾ expanded) sits on a muted blue bar below the row. The renderer is called for every row — return `null` or `undefined` to suppress the toggle entirely for that row.
 
 ```tsx
 // All rows expandable
@@ -99,7 +147,7 @@ Attaches a collapsible detail panel below each row. The renderer is called for e
   expandRowRenderer={(order) => <OrderLineItems orderId={order.id} />}
 />
 
-// Selectively expandable
+// Selectively expandable — only rows with line items get a toggle
 <ResponsiveTable
   data={orders}
   columnDefinitions={columns}
@@ -108,21 +156,57 @@ Attaches a collapsible detail panel below each row. The renderer is called for e
   }
 />
 
-// Using rowIndex for position-based logic
+// rowIndex for position-based logic (zebra detail panels, animation offsets)
 <ResponsiveTable
-  data={rows}
+  data={employees}
   columnDefinitions={columns}
   expandRowRenderer={(row, rowIndex) => (
-    <DetailPanel row={row} position={rowIndex} />
+    <EmployeeDetail employee={row} zebra={rowIndex % 2 === 0} />
   )}
 />
 ```
 
+**Use cases**
+- Master–detail layouts (orders → line items, users → permissions, assets → history)
+- Inline editing panels without navigating away
+- Progressive disclosure of verbose data fields that would clutter the main row
+- Nested tables or charts scoped to a single row
+
 **Behaviour**
-- Detail content is **lazy-mounted**: the component is not rendered until first expand, then stays mounted so the collapse animation plays correctly.
-- Expand state is keyed by row ID (`selectionProps.rowIdKey` when provided, otherwise array index). Providing a stable `rowIdKey` ensures expand state survives re-sorts and filter changes.
-- `rowIndex` is the **display-order** index (post-sort, post-filter). Use the row object's own identifier for stable cross-render data correlation.
-- Works in both desktop (table) and mobile (card) layouts.
+- Detail content is **lazy-mounted**: the panel component is not created until first expand, then stays mounted so the collapse animation plays correctly. Heavy components are instantiated on demand.
+- Expand state is keyed by `selectionProps.rowIdKey` when provided, otherwise falls back to array index. A stable key survives re-sorts and filter changes.
+- `rowIndex` is the **display-order** index (post-sort, post-filter) — not a stable identifier. Use the row object's own field for cross-render correlation.
+- The chevron bar carries `data-rt-ignore-row-click` — tapping the toggle never fires `onRowClick`.
+- Works identically in desktop (table `<tr>`) and mobile (card) layouts.
+
+#### `expandChevronClassName`
+
+```typescript
+expandChevronClassName?: string
+```
+
+Custom CSS class applied to the chevron icon `<span>`. The chevron defaults to `2.2rem` in the primary color. Use this prop to override any style without forking the component.
+
+```tsx
+// Brand color override
+<ResponsiveTable
+  expandChevronClassName={styles.brandChevron}
+  expandRowRenderer={(row) => <Detail row={row} />}
+  ...
+/>
+```
+
+```css
+.brandChevron {
+  color: #7c3aed;    /* your design-system accent */
+  font-size: 1.8rem; /* smaller if the default is too prominent */
+}
+```
+
+**Best practices**
+- Override `color` to match your design token rather than using hardcoded hex — keeps theming consistent.
+- Avoid overriding `transform` or `transition` — these drive the collapse animation.
+- Pair with `--primary-color` CSS variable if your app uses it; the default chevron already respects it.
 
 ### DataSource Types
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jattac.libs.web.responsive-table",
-  "version": "0.12.0-rc.4",
+  "version": "0.12.0",
   "description": "A fully responsive, customizable, and lightweight React table component with a modern, mobile-first design and a powerful plugin system.",
   "author": {
     "name": "Nyingi Maina",