jattac.libs.web.responsive-table 0.10.0 → 0.11.1

package/README.md

@@ -13,45 +13,81 @@ ResponsiveTable is a high-performance, type-safe React component designed for co
 ## Installation
 
 ```bash
-npm install jattac.libs.web.responsive-table
+npm install jattac.libs.web.responsive-table jattac.libs.web.zest-textbox react-icons
 ```
 
 ---
 
+## Built-in Filter
+
+Enable the search box with one prop. A clear (×) button appears automatically when the field has text.
+
+**Client-side** — filters the in-memory `data` array and highlights matches:
+```tsx
+<ResponsiveTable
+  data={rows}
+  columnDefinitions={columns}
+  filterProps={{ showFilter: true }}
+/>
+```
+
+**Server-side** — when `dataSource` is present, server mode is automatic. The table resets to page 1 and calls your fetch function with the current `filter` string on every change:
+```tsx
+<ResponsiveTable
+  dataSource={async ({ page, pageSize, filter }) =>
+    api.getUsers({ page, pageSize, search: filter })
+  }
+  columnDefinitions={columns}
+  filterProps={{ showFilter: true }}
+/>
+```
+
+> To force client-side filtering even with a `dataSource`, pass `mode: 'client'`.
+
+---
+
 ## Delightful Data Fetching: Smart Data Source
 
-The new `dataSource` pattern makes handling large datasets, server-side sorting, and infinite scroll completely painless. You provide the fetch logic; we handle the bookkeeping.
+The `dataSource` pattern makes handling large datasets, server-side sorting, filtering, and infinite scroll completely painless. You provide the fetch logic; the table handles bookkeeping.
 
-### Basic Usage
+### Pagination only
 ```tsx
 <ResponsiveTable
   dataSource={async ({ page, pageSize }) => {
     const users = await api.getUsers({ page, pageSize });
-    return users; // Table automatically handles appending and hasMore detection!
+    return users; // hasMore is auto-detected from page size
   }}
   columnDefinitions={columns}
 />
 ```
 
-### With Sorting & Filtering
-The table tells you exactly what it needs based on user interaction:
+### Pagination + sorting + filtering
 ```tsx
 <ResponsiveTable
-  dataSource={async ({ page, pageSize, sort, filter }) => {
-    return await api.getUsers({
+  dataSource={async ({ page, pageSize, sort, filter }) =>
+    api.getUsers({
       page,
       limit: pageSize,
       sortBy: sort?.columnId,
       order: sort?.direction,
-      search: filter
-    });
-  }}
+      search: filter,
+    })
+  }
   columnDefinitions={columns}
   sortProps={{ initialSortColumn: 'name' }}
   filterProps={{ showFilter: true }}
 />
 ```
 
+### With total count (accurate hasMore)
+Return `{ items, totalCount }` instead of a plain array and the table derives `hasMore` precisely:
+```tsx
+dataSource={async ({ page, pageSize }) => {
+  const { data, total } = await api.getUsers({ page, pageSize });
+  return { items: data, totalCount: total };
+}}
+```
+
 ---
 
 ## Basic Implementation
@@ -106,6 +142,25 @@ For a deep dive into more complex scenarios, see the **[Handling Interactive Ele
 
 ---
 
+## Loading States & Animations
+
+Control skeleton loaders and entrance animations with `animationProps`:
+
+```tsx
+<ResponsiveTable
+  data={rows}
+  columnDefinitions={columns}
+  animationProps={{ isLoading: isFetching, animateOnLoad: true }}
+/>
+```
+
+| Prop | Type | Description |
+| :--- | :--- | :--- |
+| `isLoading` | `boolean` | Shows a skeleton loader while `true`. Merges with internal `dataSource` loading state. |
+| `animateOnLoad` | `boolean` | Animates rows in on initial mount with a staggered entrance effect. |
+
+---
+
 ## Documentation Directory
 
 The following technical documentation provides comprehensive implementation guidance:

package/dist/Plugins/FilterPlugin.d.ts

@@ -12,4 +12,5 @@ export declare class FilterPlugin<TData> implements IResponsiveTablePlugin<TData
     processData: (data: TData[]) => TData[];
     renderCell: (content: React.ReactNode, _row: TData, _column: IResponsiveTableColumnDefinition<TData>) => React.ReactNode;
     private handleFilterChange;
+    private handleClear;
 }

package/dist/UI/ResponsiveTable.d.ts

@@ -72,7 +72,7 @@ interface IProps<TData> {
         showFilter?: boolean;
         filterPlaceholder?: string;
         className?: string;
-        /** When 'server', filter changes trigger a dataSource re-fetch with the filter param instead of client-side filtering. Default: 'client'. */
+        /** Default: 'server' when dataSource is present, 'client' otherwise. Pass 'client' to force in-memory filtering even with a dataSource. */
         mode?: 'client' | 'server';
     };
     /** Configuration for row selection. */

package/dist/index.es.js

@@ -1,4 +1,6 @@
 import React, { createContext, useCallback, useMemo, useContext, useRef, useEffect, useState, forwardRef, useImperativeHandle } from 'react';
+import ZestTextbox from 'jattac.libs.web.zest-textbox';
+import { MdClose } from 'react-icons/md';
 
 function styleInject(css, ref) {
   if ( ref === void 0 ) ref = {};
@@ -484,16 +486,30 @@ class FilterPlugin {
             this.api = api;
         };
         this.renderHeader = () => {
-            var _a;
+            var _a, _b;
             if (!((_a = this.api.filterProps) === null || _a === void 0 ? void 0 : _a.showFilter)) {
                 return null;
             }
-            return (React.createElement("div", { style: { marginBottom: '1rem' } },
-                React.createElement("input", { type: "text", placeholder: this.api.filterProps.filterPlaceholder || "Search...", onChange: this.handleFilterChange, className: this.api.filterProps.className, style: {
-                        padding: '0.5rem',
-                        border: '1px solid #ccc',
-                        borderRadius: '4px',
-                    } })));
+            return (React.createElement("div", { style: { marginBottom: '1rem', display: 'flex', alignItems: 'center', gap: '0.5rem' } },
+                React.createElement(ZestTextbox, { value: this.filterText, placeholder: (_b = this.api.filterProps.filterPlaceholder) !== null && _b !== void 0 ? _b : 'Search...', onChange: this.handleFilterChange, className: this.api.filterProps.className, zest: { stretch: true } }),
+                React.createElement("button", { onClick: this.handleClear, "aria-label": "Clear filter", style: {
+                        display: 'flex',
+                        alignItems: 'center',
+                        justifyContent: 'center',
+                        minWidth: '2.75rem',
+                        minHeight: '2.75rem',
+                        padding: 0,
+                        border: 'none',
+                        borderRadius: '50%',
+                        background: 'transparent',
+                        cursor: 'pointer',
+                        color: '#666',
+                        opacity: this.filterText ? 1 : 0,
+                        pointerEvents: this.filterText ? 'auto' : 'none',
+                        transition: 'opacity 0.15s ease',
+                        flexShrink: 0,
+                    } },
+                    React.createElement(MdClose, { size: 20 }))));
         };
         this.processData = (data) => {
             var _a;
@@ -548,6 +564,15 @@ class FilterPlugin {
                 (_b = (_a = this.api).onFilterChange) === null || _b === void 0 ? void 0 : _b.call(_a, currentFilterText);
             }, 300);
         };
+        this.handleClear = () => {
+            var _a, _b;
+            if (this.debounceTimeout) {
+                clearTimeout(this.debounceTimeout);
+            }
+            this.filterText = '';
+            this.api.forceUpdate();
+            (_b = (_a = this.api).onFilterChange) === null || _b === void 0 ? void 0 : _b.call(_a, '');
+        };
     }
 }
 
@@ -1040,6 +1065,8 @@ const useTableDataSource = (props) => {
     const [isFetchingMore, setIsFetchingMore] = useState(false);
     const [error, setError] = useState(undefined);
     const isInitialMount = useRef(true);
+    const dataLengthRef = useRef(0);
+    dataLengthRef.current = data.length;
     const fetchData = useCallback((page, isAppend) => __awaiter(void 0, void 0, void 0, function* () {
         if (!dataSource)
             return;
@@ -1072,7 +1099,7 @@ const useTableDataSource = (props) => {
             setCurrentPage(page);
             // Intelligent hasMore detection
             if (newTotalCount !== undefined) {
-                const currentTotalLoaded = (isAppend ? data.length : 0) + newItems.length;
+                const currentTotalLoaded = (isAppend ? dataLengthRef.current : 0) + newItems.length;
                 setHasMore(currentTotalLoaded < newTotalCount);
             }
             else {
@@ -1089,7 +1116,7 @@ const useTableDataSource = (props) => {
             setIsLoading(false);
             setIsFetchingMore(false);
         }
-    }), [dataSource, pageSize, sort, filter, data.length]);
+    }), [dataSource, pageSize, sort, filter]);
     const loadNextPage = useCallback(() => __awaiter(void 0, void 0, void 0, function* () {
         if (isLoading || isFetchingMore || !hasMore || !dataSource)
             return;
@@ -1147,12 +1174,24 @@ function ResponsiveTableInner(props, ref) {
     const handleFilterChange = useCallback((text) => {
         setActiveFilter(text);
     }, []);
+    const isServerFilter = !!dataSource && !!(filterProps === null || filterProps === void 0 ? void 0 : filterProps.showFilter) && (filterProps === null || filterProps === void 0 ? void 0 : filterProps.mode) !== 'client';
+    const resolvedFilterProps = useMemo(() => {
+        var _a;
+        if (!filterProps)
+            return undefined;
+        return {
+            showFilter: filterProps.showFilter,
+            filterPlaceholder: filterProps.filterPlaceholder,
+            className: filterProps.className,
+            mode: isServerFilter ? 'server' : ((_a = filterProps.mode) !== null && _a !== void 0 ? _a : 'client'),
+        };
+    }, [filterProps === null || filterProps === void 0 ? void 0 : filterProps.showFilter, filterProps === null || filterProps === void 0 ? void 0 : filterProps.filterPlaceholder, filterProps === null || filterProps === void 0 ? void 0 : filterProps.className, filterProps === null || filterProps === void 0 ? void 0 : filterProps.mode, isServerFilter]);
     const { data: sourceData, isLoading: isSourceLoading, isFetchingMore, hasMore, totalCount, currentPage, loadNextPage, error, resetAndFetch, } = useTableDataSource({
         dataSource,
         pageSize,
         initialData,
         sort: activeSort,
-        filter: (filterProps === null || filterProps === void 0 ? void 0 : filterProps.mode) === 'server' ? activeFilter : undefined,
+        filter: isServerFilter ? activeFilter : undefined,
     });
     useImperativeHandle(ref, () => ({
         loadNextPage: () => loadNextPage(),
@@ -1171,8 +1210,8 @@ function ResponsiveTableInner(props, ref) {
     const { processedData, activePlugins, visibleColumns } = useTablePlugins({
         data: currentDataToProcess,
         plugins,
-        onFilterChange: (filterProps === null || filterProps === void 0 ? void 0 : filterProps.mode) === 'server' ? handleFilterChange : undefined,
-        filterProps,
+        onFilterChange: isServerFilter ? handleFilterChange : undefined,
+        filterProps: resolvedFilterProps,
         selectionProps,
         sortProps,
         columnDefinitions,
@@ -1265,10 +1304,14 @@ function ResponsiveTableInner(props, ref) {
             return null;
         });
     }, [plugins]);
+    const isLoading = (animationProps === null || animationProps === void 0 ? void 0 : animationProps.isLoading) || isSourceLoading;
+    const resolvedAnimationProps = useMemo(() => ({
+        animateOnLoad: animationProps === null || animationProps === void 0 ? void 0 : animationProps.animateOnLoad,
+        isLoading,
+    }), [animationProps === null || animationProps === void 0 ? void 0 : animationProps.animateOnLoad, animationProps === null || animationProps === void 0 ? void 0 : animationProps.isLoading, isLoading]);
     if (infiniteScrollProps) {
         return React.createElement(InfiniteTable, Object.assign({}, props));
     }
-    const isLoading = (animationProps === null || animationProps === void 0 ? void 0 : animationProps.isLoading) || isSourceLoading;
     if (isLoading && !hasData) {
         return React.createElement(SkeletonView, { isMobile: isMobile, columnDefinitions: visibleColumns });
     }
@@ -1305,7 +1348,7 @@ function ResponsiveTableInner(props, ref) {
             activePlugins,
             onRowClick,
             selectionProps,
-            animationProps: Object.assign(Object.assign({}, animationProps), { isLoading }),
+            animationProps: resolvedAnimationProps,
             dataSource,
             pagination: dataSource ? {
                 currentPage,