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

package/README.md

@@ -18,6 +18,19 @@ npm install jattac.libs.web.responsive-table jattac.libs.web.zest-textbox react-
 
 ---
 
+## Table of Contents
+
+*   [Built-in Filter](#built-in-filter)
+*   [Delightful Data Fetching: Smart Data Source](#delightful-data-fetching-smart-data-source)
+*   [Basic Implementation](#basic-implementation)
+*   [Handling Interactive Elements](#handling-interactive-elements)
+*   [Expandable Rows](#expandable-rows)
+*   [Row Interaction & Feedback](#row-interaction--feedback)
+*   [Loading States & Animations](#loading-states--animations)
+*   [Documentation Directory](#documentation-directory)
+
+---
+
 ## Built-in Filter
 
 Enable the search box with one prop. A clear (×) button appears automatically when the field has text.
@@ -144,38 +157,102 @@ 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 chevron in a dedicated left column (▶ collapsed, ▾ expanded). 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`. Do not override `transform` or `transition` — these drive the rotation animation.
 
 ```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.
+**Behaviour**
+- Chevron sits in a dedicated 2rem left column — not as an overlay or pseudo-element — keeping the data columns aligned.
+- **Idle:** chevron at 25% opacity, rotates right (`-90deg`). Quiet, non-intrusive.
+- **Hover:** chevron smooths to 60% opacity, faint border accent on the row.
+- **Expanded:** chevron rotates down (`0deg`), full opacity. A toggle bar slides in (0→2rem) at the top of the detail pane.
+- **Greeting animation:** on mount, chevrons pop in with a staggered multi-pulse wave (2.2s), then settle to idle. Plays once per component lifecycle.
+- Expand and `onRowClick` coexist safely — the chevron carries `data-rt-ignore-row-click`.
+- Works identically in both desktop (table row) and mobile (card) layouts.
+
+For the full feature reference — expansion state keying, lazy mounting, keyboard accessibility, `dataSource` compatibility, common patterns, CSS customization, and pitfalls — see the **[Row Expansion and Collapse Guide](./docs/expand-collapse.md)**.
+
+---
+
+## 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.
 
 ---
 
@@ -208,6 +285,8 @@ The following technical documentation provides comprehensive implementation guid
 4.  **[Configuration Specification](./docs/configuration.md)** - Detailed guidance on performance tuning and UI customization.
 5.  **[Architecture and Contribution Guide](./docs/development.md)** - Internal system design and development environment setup.
 6.  **[Handling Interactive Elements](./docs/handling-interactive-elements.md)** - Guide on preventing row click bubbling for buttons and custom components.
+7.  **[Row Expansion and Collapse](./docs/expand-collapse.md)** - Comprehensive guide for expandable row detail panels.
+8.  **[Recommendations and Pitfalls](./docs/recommendations.md)** - Best practices, anti-patterns, and ESM/CJS module compatibility guide.
 
 ---
 **Next Step:** [Review the Technical Implementation Guide](./docs/examples.md)

package/dist/Hooks/useTablePlugins.d.ts

@@ -1,12 +1,5 @@
-import { ReactNode } from 'react';
 import { IResponsiveTablePlugin } from '../Plugins/IResponsiveTablePlugin';
 import { IResponsiveTableColumnDefinition, SortDirection } from '../Data/IResponsiveTableColumnDefinition';
-interface IInfiniteScrollProps<TData> {
-    onLoadMore: (currentData: TData[]) => Promise<TData[] | null>;
-    hasMore?: boolean;
-    loadingMoreComponent?: ReactNode;
-    noMoreDataComponent?: ReactNode;
-}
 interface UseTablePluginsProps<TData> {
     data: TData[];
     plugins?: IResponsiveTablePlugin<TData>[];
@@ -28,7 +21,6 @@ interface UseTablePluginsProps<TData> {
     };
     columnDefinitions: (IResponsiveTableColumnDefinition<TData> | ((data: TData, rowIndex?: number) => IResponsiveTableColumnDefinition<TData>))[];
     getScrollableElement: () => HTMLElement | null;
-    infiniteScrollProps?: IInfiniteScrollProps<TData>;
     onFilterChange?: (filterText: string) => void;
 }
 interface UseTablePluginsReturn<TData> {

package/dist/Plugins/IResponsiveTablePlugin.d.ts

@@ -18,12 +18,6 @@ export interface IPluginAPI<TData> {
     forceUpdate: () => void;
     columnDefinitions: ColumnDefinition<TData>[];
     getScrollableElement?: () => HTMLElement | null;
-    infiniteScrollProps?: {
-        onLoadMore: (currentData: TData[]) => Promise<TData[] | null>;
-        hasMore?: boolean;
-        loadingMoreComponent?: ReactNode;
-        noMoreDataComponent?: ReactNode;
-    };
     filterProps?: {
         showFilter?: boolean;
         filterPlaceholder?: string;

package/dist/UI/DetailRow.d.ts

@@ -6,7 +6,6 @@ interface DetailRowProps<TData> {
     expandRowRenderer: (row: TData, rowIndex: number) => React.ReactNode;
     isExpanded: boolean;
     onToggle: () => void;
-    expandChevronClassName?: string;
 }
-export declare function DetailRow<TData>({ row, rowIndex, colSpan, expandRowRenderer, isExpanded, onToggle, expandChevronClassName }: DetailRowProps<TData>): React.JSX.Element;
+export declare function DetailRow<TData>({ row, rowIndex, colSpan, expandRowRenderer, isExpanded, onToggle }: DetailRowProps<TData>): React.JSX.Element;
 export {};

package/dist/UI/ResponsiveTable.d.ts

@@ -10,12 +10,6 @@ export interface ResponsiveTableHandle<TData> {
     resetAndFetch: () => Promise<void>;
     getState: () => DataSourceState<TData>;
 }
-interface IInfiniteScrollProps<TData> {
-    onLoadMore: (currentData: TData[]) => Promise<TData[] | null>;
-    hasMore?: boolean;
-    loadingMoreComponent?: ReactNode;
-    noMoreDataComponent?: ReactNode;
-}
 interface ISortProps {
     initialSortColumn?: string;
     initialSortDirection?: SortDirection;
@@ -62,11 +56,6 @@ interface IProps<TData> {
     plugins?: IResponsiveTablePlugin<TData>[];
     /** If true, the header will stick to the top of the page when scrolling. */
     enablePageLevelStickyHeader?: boolean;
-    /**
-     * Props for manual infinite scroll handling.
-     * NOTE: Prefer using `dataSource` for a more seamless experience.
-     */
-    infiniteScrollProps?: IInfiniteScrollProps<TData>;
     /** Configuration for the built-in filter plugin. */
     filterProps?: {
         showFilter?: boolean;

package/dist/UI/TableBodyRow.d.ts

@@ -32,6 +32,12 @@ interface TableBodyRowProps<TData> {
         isLoading?: boolean;
         animateOnLoad?: boolean;
     };
+    /** Optional expand chevron cell rendered as the first column */
+    expandCell?: React.ReactNode;
+    /** Mouse enter handler for hover tracking */
+    onMouseEnter?: () => void;
+    /** Mouse leave handler for hover tracking */
+    onMouseLeave?: () => void;
 }
 export declare function TableBodyRow<TData>(props: TableBodyRowProps<TData>): React.JSX.Element;
 export {};

package/dist/index.d.ts

@@ -5,9 +5,8 @@ import ResponsiveTable, { ResponsiveTableHandle } from './UI/ResponsiveTable';
 import { ColumnDefinition, DataSource, IDataSourceParams, DataSourceResult, useTableContext } from './Context/TableContext';
 import { DataSourceState } from './Hooks/useTableDataSource';
 import { FilterPlugin } from './Plugins/FilterPlugin';
-import { InfiniteScrollPlugin } from './Plugins/InfiniteScrollPlugin';
 import { IResponsiveTablePlugin } from './Plugins/IResponsiveTablePlugin';
 import { SortPlugin } from './Plugins/SortPlugin';
 import { SelectionPlugin } from './Plugins/SelectionPlugin';
-export { SortDirection, IResponsiveTableColumnDefinition, ColumnDefinition, DataSource, IDataSourceParams, DataSourceResult, IFooterColumnDefinition, IFooterRowDefinition, FilterPlugin, InfiniteScrollPlugin, IResponsiveTablePlugin, SortPlugin, SelectionPlugin, ResponsiveTableHandle, DataSourceState, useTableContext, };
+export { SortDirection, IResponsiveTableColumnDefinition, ColumnDefinition, DataSource, IDataSourceParams, DataSourceResult, IFooterColumnDefinition, IFooterRowDefinition, FilterPlugin, IResponsiveTablePlugin, SortPlugin, SelectionPlugin, ResponsiveTableHandle, DataSourceState, useTableContext, };
 export default ResponsiveTable;