jattac.libs.web.responsive-table 0.7.6 → 0.8.1

package/README.md

@@ -1,460 +1,58 @@
-# ResponsiveTable: A Modern and Flexible React Table Component
+# ResponsiveTable
+## Enterprise-Grade React Data Grid Component
 
-[![npm version](https://badge.fury.io/js/jattac.libs.web.responsive-table.svg)](https://badge.fury.io/js/jattac.libs.web.responsive-table)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+ResponsiveTable is a high-performance, type-safe React component designed for complex data visualization. It provides seamless layout transitions between desktop-optimized tabular displays and mobile-optimized card views, ensuring data integrity and accessibility across all device form factors.
 
-ResponsiveTable is a powerful, lightweight, and fully responsive React component for creating beautiful and functional tables. It’s designed to look great on any device, adapting from a traditional table layout on desktops to a clean, card-based view on mobile screens.
-
-## Features
-
-*   **Truly Responsive:** Automatically transforms from a traditional table to a card-based layout on mobile.
-*   **Extensible Plugin System:** Add features like sorting, filtering, selection, and infinite scroll with ease.
-*   **Type-Safe API:** Built with TypeScript for a great developer experience.
-*   **Highly Customizable:** Control the rendering of every part of the table.
-*   **Animations:** Built-in support for loading skeletons and row animations.
-*   **Small Bundle Size:** Lightweight and optimized for performance.
-
-## Table of Contents
-
-- [Installation](#installation)
-- [Getting Started](#getting-started)
-- [Core Concepts](#core-concepts)
-  - [Column Definitions](#column-definitions)
-  - [Responsive Behavior](#responsive-behavior)
-- [Advanced Guides](#advanced-guides)
-  - [Custom Cell Rendering](#custom-cell-rendering)
-  - [Clickable Rows and Headers](#clickable-rows-and-headers)
-  - [Dynamic and Conditional Columns](#dynamic-and-conditional-columns)
-  - [Advanced Footers](#advanced-footers)
-  - [Animations and Loading States](#animations-and-loading-states)
-- [Plugin System](#plugin-system)
-  - [Using Plugins](#using-plugins)
-  - [Built-in Plugins](#built-in-plugins)
-    - [SortPlugin](#sortplugin)
-    - [SelectionPlugin](#selectionplugin)
-    - [FilterPlugin](#filterplugin)
-    - [InfiniteScrollPlugin](#infinitescrollplugin)
-  - [Building a Custom Plugin](#building-a-custom-plugin)
-- [API Reference](#api-reference)
-  - [ResponsiveTable Props](#responsivetable-props)
-  - [ColumnDefinition Type](#columndefinition-type)
-  - [Footer Types](#footer-types)
-- [Performance Best Practices](#performance-best-practices)
-- [Troubleshooting / FAQ](#troubleshooting--faq)
-- [Contributing](#contributing)
-- [License](#license)
-
----
+## Core Capabilities
+*   **Dynamic Layout Orchestration:** Automated transformation between standard table structures and mobile-optimized interfaces based on configurable breakpoints.
+*   **Extensible Architecture:** A robust plugin system for implementing sorting, filtering, row selection, and asynchronous data fetching.
+*   **Intelligent Layout Scaling:** Automated recalculation of footer colSpan ranges to maintain structural alignment when columns are programmatically excluded.
+*   **Performance Optimized:** An atomized internal architecture that decouples state management from rendering, minimizing re-render cycles.
+*   **Type Safety:** Comprehensive TypeScript definitions for predictable implementation and robust development workflows.
 
 ## Installation
 
-Install the package using your favorite package manager:
-
 ```bash
 npm install jattac.libs.web.responsive-table
 ```
 
-or
+## Basic Implementation
 
-```bash
-yarn add jattac.libs.web.responsive-table
-```
-
-## Getting Started
+The following example demonstrates a standard implementation of the ResponsiveTable component:
 
-Here's a basic example to get you up and running with `ResponsiveTable`:
-
-```jsx
+```tsx
 import React from 'react';
-import ResponsiveTable, { IResponsiveTableColumnDefinition } from 'jattac.libs.web.responsive-table';
-
-// 1. Define your data structure
-interface User {
-  id: number;
-  name: string;
-  email: string;
-  role: string;
-}
+import ResponsiveTable from 'jattac.libs.web.responsive-table';
 
-// 2. Provide the data
-const users: User[] = [
-  { id: 1, name: 'Alice', email: 'alice@example.com', role: 'Admin' },
-  { id: 2, name: 'Bob', email: 'bob@example.com', role: 'User' },
-  { id: 3, name: 'Charlie', email: 'charlie@example.com', role: 'User' },
+const data = [
+  { id: 1, name: 'Administrative User' },
+  { id: 2, name: 'Standard User' }
 ];
 
-// 3. Define the column structure
-const columnDefinitions: IResponsiveTableColumnDefinition<User>[] = [
-  {
-    displayLabel: 'Name',
-    cellRenderer: (row) => row.name,
-  },
-  {
-    displayLabel: 'Email',
-    cellRenderer: (row) => row.email,
-  },
-  {
-    displayLabel: 'Role',
-    cellRenderer: (row) => row.role,
-  },
+const columns = [
+  { displayLabel: 'Identifier', cellRenderer: (row) => row.id },
+  { displayLabel: 'User Name', cellRenderer: (row) => row.name },
 ];
 
-// 4. Render the component
 const App = () => (
-  <div style={{ padding: '2rem' }}>
-    <h1>Users</h1>
-    <ResponsiveTable<User>
-      data={users}
-      columnDefinitions={columnDefinitions}
-    />
-  </div>
+  <ResponsiveTable 
+    data={data} 
+    columnDefinitions={columns} 
+  />
 );
-
-export default App;
 ```
 
 ---
 
-## Core Concepts
-
-### Column Definitions
-
-The `columnDefinitions` prop is the heart of the table. It's an array of objects where each object defines a column. The two most important properties are:
+## Documentation Directory
 
-*   `displayLabel`: The content of the header cell.
-*   `cellRenderer`: A function that receives the row data and returns the content of the cell.
+The following technical documentation provides comprehensive implementation guidance:
 
-### Responsive Behavior
-
-The table is responsive out of the box. It will render as a standard table on large screens and as a list of cards on small screens. You can control the breakpoint at which this change happens with the `mobileBreakpoint` prop.
+1.  **[Technical Implementation Guide](./docs/examples.md)** - Practical examples for core features, including infinite scroll and plugin integration.
+2.  **[Functional Capabilities](./docs/features.md)** - A high-level overview of the component's feature set.
+3.  **[API Reference](./docs/api.md)** - Technical specifications for props, interfaces, and type definitions.
+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.
 
 ---
-
-## Advanced Guides
-
-### Custom Cell Rendering
-
-You can render any React component in a cell using the `cellRenderer` function.
-
-```jsx
-const columnDefinitions: IResponsiveTableColumnDefinition<User>[] = [
-  {
-    displayLabel: 'Status',
-    cellRenderer: (row) => (
-      <span style={{
-        color: row.isActive ? 'green' : 'red',
-        fontWeight: 'bold',
-      }}>
-        {row.isActive ? 'Active' : 'Inactive'}
-      </span>
-    ),
-  },
-  {
-    displayLabel: 'Actions',
-    cellRenderer: (row) => (
-      <button onClick={() => alert(`Editing ${row.name}`)}>
-        Edit
-      </button>
-    ),
-  },
-];
-```
-
-### Clickable Rows and Headers
-
-*   **Rows:** Use the `onRowClick` prop to handle row clicks.
-*   **Headers:** Use the `interactivity` property in a column definition to handle header clicks.
-
-```jsx
-<ResponsiveTable
-  data={users}
-  columnDefinitions={[
-    {
-      displayLabel: 'Name',
-      cellRenderer: (row) => row.name,
-      interactivity: {
-        id: 'name-header',
-        onHeaderClick: (id) => alert(`Clicked ${id}`),
-      },
-    },
-    // ...
-  ]}
-  onRowClick={(row) => alert(`Clicked on ${row.name}`)}
-/>
-```
-
-### Dynamic and Conditional Columns
-
-The `columnDefinitions` prop can be a function that returns an array of column definitions. This allows you to dynamically change the columns based on the data.
-
-```jsx
-const getColumnDefinitions = (user: User): IResponsiveTableColumnDefinition<User>[] => {
-  const columns: IResponsiveTableColumnDefinition<User>[] = [
-    // ... common columns
-  ];
-
-  if (user.role === 'Admin') {
-    columns.push({
-      displayLabel: 'Admin Actions',
-      cellRenderer: () => <button>Delete User</button>,
-    });
-  }
-
-  return columns;
-};
-
-<ResponsiveTable
-  data={users}
-  columnDefinitions={getColumnDefinitions}
-/>
-```
-
-### Advanced Footers
-
-You can add footer rows to the table using the `footerRows` prop.
-
-```jsx
-const footerRows: IFooterRowDefinition[] = [
-  {
-    columns: [
-      {
-        colSpan: 2,
-        cellRenderer: () => <strong>Total Users:</strong>,
-      },
-      {
-        colSpan: 1,
-        cellRenderer: () => <strong>{users.length}</strong>,
-      },
-    ],
-  },
-];
-
-<ResponsiveTable
-  data={users}
-  columnDefinitions={columnDefinitions}
-  footerRows={footerRows}
-/>
-```
-
-### Animations and Loading States
-
-Use the `animationProps` prop to show a loading skeleton and animate rows on load.
-
-```jsx
-<ResponsiveTable
-  data={users}
-  columnDefinitions={columnDefinitions}
-  animationProps={{
-    isLoading: true, // Shows a skeleton loader
-    animateOnLoad: true, // Animates rows on initial render
-  }}
-/>
-```
-
----
-
-## Plugin System
-
-### Using Plugins
-
-To use a plugin, instantiate it and pass it to the `plugins` prop.
-
-```jsx
-import { SortPlugin } from 'jattac.libs.web.responsive-table';
-
-const sortPlugin = new SortPlugin<User>();
-
-<ResponsiveTable
-  data={users}
-  columnDefinitions={columnDefinitions}
-  plugins={[sortPlugin]}
-/>
-```
-
-### Built-in Plugins
-
-#### SortPlugin
-
-Enables column sorting.
-
-**Usage:**
-
-1.  Add a `columnId` to the columns you want to be sortable.
-2.  Provide a `sortComparer` or `getSortableValue` function in the column definition.
-3.  Add the `SortPlugin` to the `plugins` prop.
-
-```jsx
-const sortPlugin = new SortPlugin<User>({
-  initialSortColumn: 'name',
-  initialSortDirection: 'asc',
-});
-
-const columnDefinitions: IResponsiveTableColumnDefinition<User>[] = [
-  {
-    columnId: 'name',
-    displayLabel: 'Name',
-    cellRenderer: (row) => row.name,
-    sortComparer: sortPlugin.comparers.caseInsensitiveString('name'),
-  },
-  // ...
-];
-
-<ResponsiveTable
-  data={users}
-  columnDefinitions={columnDefinitions}
-  plugins={[sortPlugin]}
-/>
-```
-
-#### SelectionPlugin
-
-Enables row selection.
-
-**Usage:**
-
-The `SelectionPlugin` is automatically enabled when you provide the `selectionProps`.
-
-```jsx
-<ResponsiveTable
-  data={users}
-  columnDefinitions={columnDefinitions}
-  selectionProps={{
-    onSelectionChange: (selectedItems) => console.log(selectedItems),
-    rowIdKey: 'id',
-    mode: 'multiple', // or 'single'
-  }}
-/>
-```
-
-#### FilterPlugin
-
-Adds a client-side search input to filter the table.
-
-**Usage:**
-
-The `FilterPlugin` is automatically enabled when you provide the `filterProps`. Add a `getFilterableValue` function to the columns you want to be filterable.
-
-```jsx
-const columnDefinitions: IResponsiveTableColumnDefinition<User>[] = [
-  {
-    displayLabel: 'Name',
-    cellRenderer: (row) => row.name,
-    getFilterableValue: (row) => row.name,
-  },
-  // ...
-];
-
-<ResponsiveTable
-  data={users}
-  columnDefinitions={columnDefinitions}
-  filterProps={{
-    showFilter: true,
-    filterPlaceholder: 'Search users...',
-  }}
-/>
-```
-
-#### InfiniteScrollPlugin
-
-Enables infinite scrolling.
-
-**Usage:**
-
-```jsx
-import { InfiniteScrollPlugin } from 'jattac.libs.web.responsive-table';
-
-const onLoadMore = async (currentData) => {
-  // Fetch more data...
-  return moreData;
-};
-
-<ResponsiveTable
-  data={data}
-  columnDefinitions={columnDefinitions}
-  plugins={[new InfiniteScrollPlugin()]}
-  infiniteScrollProps={{
-    onLoadMore: onLoadMore,
-    hasMore: true,
-  }}
-  maxHeight="600px" // Requires a scrollable container
-/>
-```
-
-### Building a Custom Plugin
-
-Implement the `IResponsiveTablePlugin` interface to create your own plugin.
-
-```jsx
-import { IResponsiveTablePlugin } from 'jattac.libs.web.responsive-table';
-
-class MyCustomPlugin<TData> implements IResponsiveTablePlugin<TData> {
-  public id = 'my-custom-plugin';
-
-  public getRowProps = (row: TData) => {
-    if (row.isSpecial) {
-      return {
-        className: 'special-row',
-        style: { backgroundColor: 'lightblue' },
-      };
-    }
-    return {};
-  };
-}
-
-// Usage:
-// <ResponsiveTable plugins={[new MyCustomPlugin()]} ... />
-```
-
----
-
-## API Reference
-
-### ResponsiveTable Props
-
-| Prop                         | Type                                                              | Description                                                                                                                                |
-| ---------------------------- | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
-| `columnDefinitions`          | `ColumnDefinition<TData>[]`                                       | **Required.** An array of objects that define the columns of the table.                                                                    |
-| `data`                       | `TData[]`                                                         | **Required.** The array of data to be displayed in the table.                                                                              |
-| `noDataComponent`            | `ReactNode`                                                       | A custom component to display when there is no data.                                                                                       |
-| `maxHeight`                  | `string`                                                          | Sets a maximum height for the table, making the body scrollable. E.g., `'500px'`.                                                          |
-| `onRowClick`                 | `(item: TData) => void`                                           | A callback function that is triggered when a row is clicked.                                                                               |
-| `footerRows`                 | `IFooterRowDefinition[]`                                          | An array of objects that define the footer rows of the table.                                                                              |
-| `mobileBreakpoint`           | `number`                                                          | The viewport width (in pixels) at which the table switches to the mobile card view. Defaults to `600`.                                     |
-| `plugins`                    | `IResponsiveTablePlugin<TData>[]`                                 | An array of plugin instances to extend the table's functionality.                                                                          |
-| `enablePageLevelStickyHeader`| `boolean`                                                         | When `false`, disables the sticky behavior of the header at the page level. Defaults to `true`.                                            |
-| `animationProps`             | `{ isLoading?: boolean; animateOnLoad?: boolean; }`               | Props to control animations. `isLoading` shows a skeleton loader. `animateOnLoad` animates rows on initial render.                       |
-| `filterProps`                | `{ showFilter?: boolean; filterPlaceholder?: string; className?: string; }` | Props to configure the built-in filter functionality. `showFilter` enables the filter input.                                               |
-| `selectionProps`             | `{ onSelectionChange: (selectedItems: TData[]) => void; rowIdKey: keyof TData; mode?: 'single' \| 'multiple'; selectedItems?: TData[]; selectedRowClassName?: string; }` | Props to enable and configure row selection.                                                                                               |
-| `infiniteScrollProps`        | `{ onLoadMore: (currentData: TData[]) => Promise<TData[] \| null>; hasMore?: boolean; loadingMoreComponent?: ReactNode; noMoreDataComponent?: ReactNode; }` | Props to enable infinite scrolling.                                                                                                        |
-
-### ColumnDefinition Type
-
-`IResponsiveTableColumnDefinition<TData>` is a union type. See the source file for detailed information.
-
-### Footer Types
-
-`IFooterRowDefinition` and `IFooterColumnDefinition` are used to define the footer. See the source files for detailed information.
-
----
-
-## Performance Best Practices
-
-*   **Memoize `data` and `columnDefinitions`:** To prevent unnecessary re-renders, wrap `data` and `columnDefinitions` in `React.useMemo`.
-*   **Lightweight `cellRenderer`:** Keep your `cellRenderer` functions as simple as possible.
-*   **Server-side Operations:** For large datasets, perform sorting, filtering, and pagination on the server.
-
----
-
-## Troubleshooting / FAQ
-
-This section will be populated with common issues and their solutions as they arise.
-
----
-
-## Contributing
-
-Contributions are welcome! Please follow the guidelines in the `CONTRIBUTING.md` file.
-
-## License
-
-This project is licensed under the MIT License.
+**Next Step:** [Review the Technical Implementation Guide](./docs/examples.md)

package/dist/Context/TableContext.d.ts

@@ -0,0 +1,41 @@
+import React, { ReactNode } from 'react';
+import { IResponsiveTableColumnDefinition } from '../Data/IResponsiveTableColumnDefinition';
+import { IResponsiveTablePlugin } from '../Plugins/IResponsiveTablePlugin';
+export type ColumnDefinition<TData> = IResponsiveTableColumnDefinition<TData> | ((data: TData, rowIndex?: number) => IResponsiveTableColumnDefinition<TData>);
+interface TableContextValue<TData> {
+    data: TData[];
+    processedData: TData[];
+    currentData: TData[];
+    visibleColumns: ColumnDefinition<TData>[];
+    originalColumnDefinitions: ColumnDefinition<TData>[];
+    activePlugins: IResponsiveTablePlugin<TData>[];
+    onRowClick?: (item: TData) => void;
+    selectionProps?: {
+        onSelectionChange: (selectedItems: TData[]) => void;
+        rowIdKey: keyof TData;
+        mode?: 'single' | 'multiple';
+        selectedItems?: TData[];
+        selectedRowClassName?: string;
+    };
+    animationProps?: {
+        isLoading?: boolean;
+        animateOnLoad?: boolean;
+    };
+    getRawColumnDefinition: (colDef: ColumnDefinition<TData>) => IResponsiveTableColumnDefinition<TData>;
+    getColumnDefinition: (colDef: ColumnDefinition<TData>, rowIndex: number) => IResponsiveTableColumnDefinition<TData>;
+    onHeaderClickCallback: (colDef: ColumnDefinition<TData>) => ((id: string) => void) | undefined;
+    getClickableHeaderClassName: (onHeaderClick: ((id: string) => void) | undefined, colDef: ColumnDefinition<TData>) => string;
+    getHeaderProps: (colDef: ColumnDefinition<TData>) => React.HTMLAttributes<HTMLElement> & {
+        className?: string;
+    };
+    getRowProps: (row: TData) => React.HTMLAttributes<HTMLElement>;
+    getRowId: (row: TData, index: number) => string | number;
+    renderCell: (content: React.ReactNode, row: TData, colDef: IResponsiveTableColumnDefinition<TData>) => React.ReactNode;
+}
+export declare const useTableContext: <TData>() => TableContextValue<TData>;
+interface TableProviderProps<TData> {
+    children: ReactNode;
+    value: Omit<TableContextValue<TData>, 'currentData' | 'getRawColumnDefinition' | 'getColumnDefinition' | 'onHeaderClickCallback' | 'getClickableHeaderClassName' | 'getHeaderProps' | 'getRowProps' | 'getRowId' | 'renderCell'>;
+}
+export declare function TableProvider<TData>({ children, value }: TableProviderProps<TData>): React.JSX.Element;
+export {};

package/dist/Data/IResponsiveTableColumnDefinition.d.ts

@@ -3,6 +3,7 @@ export type SortDirection = 'asc' | 'desc';
 interface IResponsiveTableColumnDefinitionBase<TData> {
     displayLabel: ReactNode;
     cellRenderer: (data: TData) => ReactNode;
+    visible?: boolean;
     dataKey?: keyof TData;
     getFilterableValue?: (data: TData) => string | number;
     interactivity?: {

package/dist/Hooks/useResponsiveTable.d.ts

@@ -0,0 +1,14 @@
+interface UseResponsiveTableProps {
+    mobileBreakpoint?: number;
+    enablePageLevelStickyHeader?: boolean;
+    maxHeight?: string;
+    headerRef?: React.RefObject<HTMLElement>;
+    scrollableRef?: React.RefObject<HTMLElement>;
+}
+interface UseResponsiveTableReturn {
+    isMobile: boolean;
+    isHeaderSticky: boolean;
+    debouncedScrollHandler: (currentTarget: HTMLElement) => void;
+}
+export declare const useResponsiveTable: (props: UseResponsiveTableProps) => UseResponsiveTableReturn;
+export {};

package/dist/Hooks/useTablePlugins.d.ts

@@ -0,0 +1,39 @@
+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>[];
+    filterProps?: {
+        showFilter?: boolean;
+        filterPlaceholder?: string;
+        className?: string;
+    };
+    selectionProps?: {
+        onSelectionChange: (selectedItems: TData[]) => void;
+        rowIdKey: keyof TData;
+        mode?: 'single' | 'multiple';
+        selectedItems?: TData[];
+    };
+    sortProps?: {
+        initialSortColumn?: string;
+        initialSortDirection?: SortDirection;
+    };
+    columnDefinitions: (IResponsiveTableColumnDefinition<TData> | ((data: TData, rowIndex?: number) => IResponsiveTableColumnDefinition<TData>))[];
+    getScrollableElement: () => HTMLElement | null;
+    infiniteScrollProps?: IInfiniteScrollProps<TData>;
+}
+interface UseTablePluginsReturn<TData> {
+    processedData: TData[];
+    activePlugins: IResponsiveTablePlugin<TData>[];
+    visibleColumns: (IResponsiveTableColumnDefinition<TData> | ((data: TData, rowIndex?: number) => IResponsiveTableColumnDefinition<TData>))[];
+    forceUpdatePlugins: () => void;
+}
+export declare const useTablePlugins: <TData>(props: UseTablePluginsProps<TData>) => UseTablePluginsReturn<TData>;
+export {};

package/dist/UI/DesktopView.d.ts

@@ -0,0 +1,15 @@
+import React from 'react';
+import IFooterColumnDefinition from '../Data/IFooterColumnDefinition';
+interface DesktopViewProps {
+    maxHeight?: string;
+    isHeaderSticky: boolean;
+    tableContainerRef: React.RefObject<HTMLDivElement>;
+    headerRef: React.RefObject<HTMLTableSectionElement>;
+    footerRows?: {
+        columns: IFooterColumnDefinition[];
+    }[];
+    renderPluginFooters: () => React.ReactNode;
+    onScroll?: (e: React.UIEvent<HTMLDivElement>) => void;
+}
+declare function DesktopView<TData>(props: DesktopViewProps): React.JSX.Element;
+export default DesktopView;