jattac.libs.web.responsive-table 0.1.6 → 0.2.0

package/README.md

@@ -11,6 +11,7 @@ ResponsiveTable is a powerful, lightweight, and fully responsive React component
 - **Interactive Elements**: Easily add click handlers for rows, headers, and footer cells.
 - **Performant**: Built with performance in mind, including debounced resize handling.
 - **Easy to Use**: A simple and intuitive API for quick integration.
+- **Extensible Plugin System**: Easily add new functionalities like filtering, infinite scrolling, or custom behaviors.
 
 ## Installation
 
@@ -229,6 +230,306 @@ const TableWithFooter = () => {
 
 ---
 
+## Plugin System
+
+ResponsiveTable is designed with an extensible plugin system, allowing developers to easily add new functionalities or modify existing behaviors without altering the core component. Plugins can interact with the table's data, render custom UI elements (like headers or footers), and respond to table events.
+
+### How to Use Plugins
+
+Plugins are passed to the `ResponsiveTable` component via the `plugins` prop, which accepts an array of `IResponsiveTablePlugin` instances. Some common functionalities, like filtering and infinite scrolling, are provided as built-in plugins that can be enabled via specific props (`filterProps` and `infiniteScrollProps`). When these props are used, the corresponding built-in plugins are automatically initialized if not already provided in the `plugins` array.
+
+```jsx
+import React from 'react';
+import ResponsiveTable from 'jattac.libs.web.responsive-table';
+import { FilterPlugin } from 'jattac.libs.web.responsive-table/dist/Plugins/FilterPlugin'; // Adjust path as needed
+
+const MyTableWithPlugins = () => {
+  const columns = [
+    { displayLabel: 'Name', dataKey: 'name', cellRenderer: (row) => row.name, getFilterableValue: (row) => row.name },
+    { displayLabel: 'Age', dataKey: 'age', cellRenderer: (row) => row.age, getFilterableValue: (row) => row.age.toString() },
+  ];
+
+  const data = [
+    { name: 'Alice', age: 32 },
+    { name: 'Bob', age: 28 },
+    { name: 'Charlie', age: 45 },
+  ];
+
+  return (
+    <ResponsiveTable
+      columnDefinitions={columns}
+      data={data}
+      // Enable built-in filter plugin via props
+      filterProps={{ showFilter: true, filterPlaceholder: "Search by name or age..." }}
+      // Or provide a custom instance of the plugin
+      // plugins={[new FilterPlugin()]}
+    />
+  );
+};
+```
+
+### Built-in Plugins
+
+#### `FilterPlugin`
+
+Provides a search input to filter table data. It can be enabled by setting `filterProps.showFilter` to `true` on the `ResponsiveTable` component. For columns to be filterable, you must provide a `getFilterableValue` function in their `IResponsiveTableColumnDefinition`.
+
+**Props for `FilterPlugin` (via `filterProps` on `ResponsiveTable`):**
+
+| Prop              | Type     | Description                                                                 |
+| ----------------- | -------- | --------------------------------------------------------------------------- |
+| `showFilter`      | `boolean`| If `true`, displays a filter input field above the table.                   |
+| `filterPlaceholder`| `string` | Placeholder text for the filter input. Defaults to "Search...".           |
+
+**Example with `FilterPlugin`:**
+
+```jsx
+import React, { useState } from 'react';
+import ResponsiveTable from 'jattac.libs.web.responsive-table';
+
+const FilterableTable = () => {
+  const initialData = [
+    { id: 1, name: 'Alice', email: 'alice@example.com' },
+    { id: 2, name: 'Bob', email: 'bob@example.com' },
+    { id: 3, name: 'Charlie', email: 'charlie@example.com' },
+    { id: 4, name: 'David', email: 'david@example.com' },
+  ];
+
+  const columns = [
+    { displayLabel: 'ID', cellRenderer: (row) => row.id, getFilterableValue: (row) => row.id.toString() },
+    { displayLabel: 'Name', cellRenderer: (row) => row.name, getFilterableValue: (row) => row.name },
+    { displayLabel: 'Email', cellRenderer: (row) => row.email, getFilterableValue: (row) => row.email },
+  ];
+
+  return (
+    <ResponsiveTable
+      columnDefinitions={columns}
+      data={initialData}
+      filterProps={{ showFilter: true, filterPlaceholder: "Filter users..." }}
+    />
+  );
+};
+```
+
+#### `InfiniteScrollPlugin`
+
+Enables infinite scrolling for the table, loading more data as the user scrolls to the bottom. This plugin requires the `maxHeight` prop to be set on the `ResponsiveTable` to define a scrollable area.
+
+**Props for `InfiniteScrollPlugin` (via `infiniteScrollProps` on `ResponsiveTable`):**
+
+| Prop                  | Type                                 | Description                                                                 |
+| --------------------- | ------------------------------------ | --------------------------------------------------------------------------- |
+| `enableInfiniteScroll`| `boolean`                            | If `true`, enables infinite scrolling.                                      |
+| `onLoadMore`          | `(currentData: TData[]) => Promise<TData[] | null>` | Callback function to load more data. Should return a Promise resolving to new data or `null`. |
+| `hasMore`             | `boolean`                            | Indicates if there is more data to load.                                    |
+| `loadingMoreComponent`| `ReactNode`                          | Custom component to display while loading more data. Defaults to "Loading more...". |
+| `noMoreDataComponent` | `ReactNode`                          | Custom component to display when no more data is available. Defaults to "No more data.". |
+
+**Example with `InfiniteScrollPlugin`:**
+
+```jsx
+import React, { useState, useEffect } from 'react';
+import ResponsiveTable from 'jattac.libs.web.responsive-table';
+
+const InfiniteScrollTable = () => {
+  const [data, setData] = useState([]);
+  const [hasMore, setHasMore] = useState(true);
+  const [page, setPage] = useState(0);
+
+  const fetchData = async (currentPage) => {
+    // Simulate API call
+    return new Promise((resolve) => {
+      setTimeout(() => {
+        const newData = [];
+        for (let i = 0; i < 10; i++) {
+          newData.push({ id: currentPage * 10 + i, value: `Item ${currentPage * 10 + i}` });
+        }
+        resolve(newData);
+      }, 500);
+    });
+  };
+
+  useEffect(() => {
+    fetchData(0).then(initialData => {
+      setData(initialData);
+      setPage(1);
+    });
+  }, []);
+
+  const onLoadMore = async (currentData) => {
+    if (!hasMore) return null;
+
+    const newItems = await fetchData(page);
+    if (newItems.length === 0) {
+      setHasMore(false);
+      return null;
+    }
+    setData((prevData) => [...prevData, ...newItems]);
+    setPage((prevPage) => prevPage + 1);
+    return newItems; // Return new items for the plugin to know data was loaded
+  };
+
+  const columns = [
+    { displayLabel: 'ID', cellRenderer: (row) => row.id },
+    { displayLabel: 'Value', cellRenderer: (row) => row.value },
+  ];
+
+  return (
+    <div style={{ height: '300px' }}> {/* Container for scrollable table */}
+      <ResponsiveTable
+        columnDefinitions={columns}
+        data={data}
+        maxHeight="100%"
+        infiniteScrollProps={{
+          enableInfiniteScroll: true,
+          onLoadMore: onLoadMore,
+          hasMore: hasMore,
+          loadingMoreComponent: <div>Loading more items...</div>,
+          noMoreDataComponent: <div>All items loaded.</div>,
+        }}
+      />
+    </div>
+  );
+};
+```
+
+### Extending Functionality with Custom Plugins
+
+Developers can create their own custom plugins to add unique features to the `ResponsiveTable`. This is achieved by implementing the `IResponsiveTablePlugin` interface.
+
+**`IResponsiveTablePlugin<TData>` Interface:**
+
+| Property       | Type                                 | Description                                                                 |
+| -------------- | ------------------------------------ | --------------------------------------------------------------------------- |
+| `id`           | `string`                             | A unique identifier for the plugin.                                         |
+| `renderHeader?`| `() => ReactNode`                    | Optional. A function that returns a React component to be rendered above the table. |
+| `renderFooter?`| `() => ReactNode`                    | Optional. A function that returns a React component to be rendered below the table. |
+| `processData?` | `(data: TData[]) => TData[]`         | Optional. A function that processes the table data before it is rendered. Useful for sorting, filtering, or transforming data. |
+| `onPluginInit?`| `(api: IPluginAPI<TData>) => void`   | Optional. A callback function that provides the plugin with an API to interact with the `ResponsiveTable` component. |
+
+**`IPluginAPI<TData>` Interface:**
+
+This interface provides methods and properties for plugins to interact with the `ResponsiveTable` component.
+
+| Property             | Type                                 | Description                                                                 |
+| -------------------- | ------------------------------------ | --------------------------------------------------------------------------- |
+| `getData`            | `() => TData[]`                      | Returns the current raw data array being used by the table.                 |
+| `forceUpdate`        | `() => void`                         | Forces the `ResponsiveTable` component to re-render. Useful after a plugin modifies internal state that affects rendering. |
+| `columnDefinitions`  | `ColumnDefinition<TData>[]`          | Provides access to the table's column definitions.                          |
+| `getScrollableElement?`| `() => HTMLElement | null`         | Optional. Returns the HTML element that is scrollable, if `maxHeight` is set. Useful for implementing scroll-based features. |
+| `infiniteScrollProps?`| `object`                            | Optional. Provides access to the `infiniteScrollProps` passed to the `ResponsiveTable`. |
+| `filterProps?`       | `object`                            | Optional. Provides access to the `filterProps` passed to the `ResponsiveTable`. |
+
+**Example: Custom Sorting Plugin**
+
+This example demonstrates a simple sorting plugin that allows sorting by a specified column.
+
+```typescript
+// src/Plugins/SortPlugin.ts
+import React from 'react';
+import { IResponsiveTablePlugin, IPluginAPI } from './IResponsiveTablePlugin';
+import IResponsiveTableColumnDefinition from '../Data/IResponsiveTableColumnDefinition';
+
+export class SortPlugin<TData> implements IResponsiveTablePlugin<TData> {
+  public id = 'sort';
+  private api!: IPluginAPI<TData>;
+  private sortColumn: string | null = null;
+  private sortDirection: 'asc' | 'desc' = 'asc';
+
+  public onPluginInit = (api: IPluginAPI<TData>) => {
+    this.api = api;
+  };
+
+  public renderHeader = () => {
+    return (
+      <div style={{ marginBottom: '1rem' }}>
+        Sort by:
+        <select onChange={this.handleColumnChange} style={{ marginLeft: '0.5rem' }}>
+          <option value="">None</option>
+          {this.api.columnDefinitions.map((colDef) => {
+            const rawColDef = colDef as IResponsiveTableColumnDefinition<TData>;
+            if (rawColDef.dataKey) {
+              return <option key={rawColDef.dataKey} value={rawColDef.dataKey}>{rawColDef.displayLabel}</option>;
+            }
+            return null;
+          })}
+        </select>
+        {this.sortColumn && (
+          <button onClick={this.toggleSortDirection} style={{ marginLeft: '0.5rem' }}>
+            {this.sortDirection === 'asc' ? 'Ascending' : 'Descending'}
+          </button>
+        )}
+      </div>
+    );
+  };
+
+  public processData = (data: TData[]): TData[] => {
+    if (!this.sortColumn) {
+      return data;
+    }
+
+    const sortedData = [...data].sort((a, b) => {
+      const aValue = a[this.sortColumn as keyof TData];
+      const bValue = b[this.sortColumn as keyof TData];
+
+      if (aValue < bValue) return this.sortDirection === 'asc' ? -1 : 1;
+      if (aValue > bValue) return this.sortDirection === 'asc' ? 1 : -1;
+      return 0;
+    });
+
+    return sortedData;
+  };
+
+  private handleColumnChange = (e: React.ChangeEvent<HTMLSelectElement>) => {
+    this.sortColumn = e.target.value || null;
+    this.api.forceUpdate();
+  };
+
+  private toggleSortDirection = () => {
+    this.sortDirection = this.sortDirection === 'asc' ? 'desc' : 'asc';
+    this.api.forceUpdate();
+  };
+}
+
+// Usage in your component:
+```jsx
+import React from 'react';
+import ResponsiveTable from 'jattac.libs.web.responsive-table';
+import { SortPlugin } from './SortPlugin'; // Assuming SortPlugin.ts is in the same directory
+
+const SortableTable = () => {
+  const data = [
+    { id: 1, name: 'Alice', age: 30 },
+    { id: 2, name: 'Bob', age: 25 },
+    { id: 3, name: 'Charlie', age: 35 },
+  ];
+
+  const columns = [
+    { displayLabel: 'ID', dataKey: 'id', cellRenderer: (row) => row.id },
+    { displayLabel: 'Name', dataKey: 'name', cellRenderer: (row) => row.name },
+    { displayLabel: 'Age', dataKey: 'age', cellRenderer: (row) => row.age },
+  ];
+
+  return (
+    <ResponsiveTable
+      columnDefinitions={columns}
+      data={data}
+      plugins={[new SortPlugin()]}
+    />
+  );
+};
+```
+
+**Other Plugin Ideas (beyond Filtering and Infinite Scroll):**
+
+-   **Column Resizing Plugin:** Allows users to drag column headers to resize columns.
+-   **Row Selection Plugin:** Adds checkboxes to rows for multi-row selection.
+-   **Export Data Plugin:** Provides buttons to export table data to CSV, Excel, or PDF.
+-   **Drag-and-Drop Reordering Plugin:** Enables reordering of rows or columns via drag and drop.
+-   **Column Visibility Toggle Plugin:** Allows users to show/hide specific columns.
+
+---
+
 ## API Reference
 
 ### `ResponsiveTable` Props
@@ -244,6 +545,9 @@ const TableWithFooter = () => {
 | `noDataComponent`   | `ReactNode`                          | No       | A custom component to display when there is no data.                                |
 | `maxHeight`         | `string`                             | No       | Sets a maximum height for the table body, making it scrollable.                     |
 | `mobileBreakpoint`  | `number`                             | No       | The pixel width at which the table switches to the mobile view. Defaults to `600`.  |
+| `plugins`           | `IResponsiveTablePlugin<TData>[]`    | No       | An array of plugin instances to extend table functionality.                         |
+| `infiniteScrollProps`| `object`                            | No       | Configuration for the built-in infinite scroll plugin.                              |
+| `filterProps`       | `object`                            | No       | Configuration for the built-in filter plugin.                                       |
 
 ### `IResponsiveTableColumnDefinition`
 
@@ -253,6 +557,7 @@ const TableWithFooter = () => {
 | `cellRenderer`  | `(row: TData) => ReactNode` | Yes      | A function that returns the content to be rendered in the cell.                |
 | `dataKey`       | `string`                    | No       | A key to match the column to a property in the data object (optional).         |
 | `interactivity` | `object`                    | No       | An object to define header interactivity (`onHeaderClick`, `id`, `className`). |
+| `getFilterableValue`| `(row: TData) => string`  | No       | A function that returns the string value to be used for filtering this column. Required for `FilterPlugin`. |
 
 ### `IFooterRowDefinition`
 
@@ -272,4 +577,4 @@ const TableWithFooter = () => {
 
 ## License
 
-This project is licensed under the MIT License.
+This project is licensed under the MIT License.

package/dist/Data/IResponsiveTableColumnDefinition.d.ts

@@ -7,4 +7,5 @@ export default interface IResponsiveTableColumnDefinition<TData> {
         onHeaderClick?: (id: string) => void;
         className?: string;
     };
+    getFilterableValue?: (data: TData) => string | number;
 }

package/dist/Plugins/FilterPlugin.d.ts

@@ -0,0 +1,12 @@
+import React from 'react';
+import { IResponsiveTablePlugin, IPluginAPI } from './IResponsiveTablePlugin';
+export declare class FilterPlugin<TData> implements IResponsiveTablePlugin<TData> {
+    id: string;
+    private filterText;
+    private api;
+    constructor();
+    onPluginInit: (api: IPluginAPI<TData>) => void;
+    renderHeader: () => React.JSX.Element | null;
+    processData: (data: TData[]) => TData[];
+    private handleFilterChange;
+}

package/dist/Plugins/IResponsiveTablePlugin.d.ts

@@ -0,0 +1,26 @@
+import { ReactNode } from 'react';
+import { ColumnDefinition } from '../UI/ResponsiveTable';
+export interface IResponsiveTablePlugin<TData> {
+    id: string;
+    renderHeader?: () => ReactNode;
+    renderFooter?: () => ReactNode;
+    processData?: (data: TData[]) => TData[];
+    onPluginInit?: (api: IPluginAPI<TData>) => void;
+}
+export interface IPluginAPI<TData> {
+    getData: () => TData[];
+    forceUpdate: () => void;
+    columnDefinitions: ColumnDefinition<TData>[];
+    getScrollableElement?: () => HTMLElement | null;
+    infiniteScrollProps?: {
+        enableInfiniteScroll?: boolean;
+        onLoadMore?: (currentData: TData[]) => Promise<TData[] | null>;
+        hasMore?: boolean;
+        loadingMoreComponent?: ReactNode;
+        noMoreDataComponent?: ReactNode;
+    };
+    filterProps?: {
+        showFilter?: boolean;
+        filterPlaceholder?: string;
+    };
+}

package/dist/Plugins/InfiniteScrollPlugin.d.ts

@@ -0,0 +1,13 @@
+import React from 'react';
+import { IResponsiveTablePlugin, IPluginAPI } from './IResponsiveTablePlugin';
+export declare class InfiniteScrollPlugin<TData> implements IResponsiveTablePlugin<TData> {
+    id: string;
+    private api;
+    private isLoadingMore;
+    constructor();
+    onPluginInit: (api: IPluginAPI<TData>) => void;
+    private attachScrollListener;
+    private handleScroll;
+    processData: (data: TData[]) => TData[];
+    renderFooter: () => string | number | true | Iterable<React.ReactNode> | React.JSX.Element | null;
+}

package/dist/UI/ResponsiveTable.d.ts

@@ -1,6 +1,7 @@
 import React, { Component, ReactNode } from 'react';
 import IResponsiveTableColumnDefinition from '../Data/IResponsiveTableColumnDefinition';
 import IFooterRowDefinition from '../Data/IFooterRowDefinition';
+import { IResponsiveTablePlugin } from '../Plugins/IResponsiveTablePlugin';
 export type ColumnDefinition<TData> = IResponsiveTableColumnDefinition<TData> | ((data: TData, rowIndex?: number) => IResponsiveTableColumnDefinition<TData>);
 interface IProps<TData> {
     columnDefinitions: ColumnDefinition<TData>[];
@@ -10,14 +11,31 @@ interface IProps<TData> {
     onRowClick?: (item: TData) => void;
     footerRows?: IFooterRowDefinition[];
     mobileBreakpoint?: number;
-    isLoading?: boolean;
-    animateOnLoad?: boolean;
+    plugins?: IResponsiveTablePlugin<TData>[];
+    infiniteScrollProps?: {
+        enableInfiniteScroll?: boolean;
+        onLoadMore?: (currentData: TData[]) => Promise<TData[] | null>;
+        hasMore?: boolean;
+        loadingMoreComponent?: ReactNode;
+        noMoreDataComponent?: ReactNode;
+    };
+    filterProps?: {
+        showFilter?: boolean;
+        filterPlaceholder?: string;
+    };
+    animationProps?: {
+        isLoading?: boolean;
+        animateOnLoad?: boolean;
+    };
 }
-interface IState {
+interface IState<TData> {
     isMobile: boolean;
+    processedData: TData[];
+    isLoadingMore: boolean;
 }
-declare class ResponsiveTable<TData> extends Component<IProps<TData>, IState> {
+declare class ResponsiveTable<TData> extends Component<IProps<TData>, IState<TData>> {
     private debouncedResize;
+    private tableContainerRef;
     constructor(props: IProps<TData>);
     private get mobileBreakpoint();
     private debounce;
@@ -27,6 +45,9 @@ declare class ResponsiveTable<TData> extends Component<IProps<TData>, IState> {
     private get noDataComponent();
     componentDidMount(): void;
     componentWillUnmount(): void;
+    componentDidUpdate(prevProps: IProps<TData>): void;
+    private initializePlugins;
+    private processData;
     handleResize: () => void;
     private getColumnDefinition;
     private getRawColumnDefinition;
@@ -39,6 +60,8 @@ declare class ResponsiveTable<TData> extends Component<IProps<TData>, IState> {
     private get skeletonView();
     private get mobileView();
     private get largeScreenView();
-    render(): React.ReactNode;
+    private renderPluginHeaders;
+    private renderPluginFooters;
+    render(): string | number | boolean | Iterable<React.ReactNode> | React.JSX.Element | null | undefined;
 }
 export default ResponsiveTable;

package/dist/index.d.ts

@@ -2,5 +2,8 @@ import IFooterColumnDefinition from './Data/IFooterColumnDefinition';
 import IFooterRowDefinition from './Data/IFooterRowDefinition';
 import IResponsiveTableColumnDefinition from './Data/IResponsiveTableColumnDefinition';
 import ResponsiveTable, { ColumnDefinition } from './UI/ResponsiveTable';
-export { IResponsiveTableColumnDefinition, ColumnDefinition, IFooterColumnDefinition, IFooterRowDefinition };
+import { FilterPlugin } from './Plugins/FilterPlugin';
+import { InfiniteScrollPlugin } from './Plugins/InfiniteScrollPlugin';
+import { IResponsiveTablePlugin } from './Plugins/IResponsiveTablePlugin';
+export { IResponsiveTableColumnDefinition, ColumnDefinition, IFooterColumnDefinition, IFooterRowDefinition, FilterPlugin, InfiniteScrollPlugin, IResponsiveTablePlugin };
 export default ResponsiveTable;