jattac.libs.web.responsive-table 0.7.5 → 0.8.0

package/docs/development.md

@@ -0,0 +1,40 @@
+# Architecture and Contribution Guide
+## Internal System Design and Development Workflows
+
+The ResponsiveTable component is engineered using an **Atomized Architecture**. This design principle decouples logic orchestration from presentation units to ensure high reusability and predictable state transitions.
+
+## Table of Contents
+*   [Architectural Layers](#architectural-layers)
+*   [Development Environment Initialization](#development-environment-initialization)
+*   [Technical Command Reference](#technical-command-reference)
+
+---
+
+[← Previous: Configuration Specification](./configuration.md) | [Next: Version Transition Guide →](./breaking-changes.md)
+
+### Architectural Layers
+The system is partitioned into three distinct functional layers:
+1.  **Logic Orchestration (`useTablePlugins`)**: A centralized hook that manages the data processing pipeline, plugin lifecycle, and persistent state management using non-reactive references.
+2.  **Pure Presentation Components**:
+    *   `DesktopView`: Manages standard tabular rendering and intelligent footer scaling logic.
+    *   `MobileView`: Manages card-based interface generation.
+    *   `SkeletonView`: Unified structural placeholder logic.
+3.  **Shell Orchestrators**:
+    *   `ResponsiveTable`: The primary entry point for synchronous datasets.
+    *   `InfiniteTable`: A specialized orchestrator for asynchronous data streams and scroll event interception.
+
+### Development Environment Initialization
+To initialize the development environment, execute the following procedures:
+1.  Clone the source repository.
+2.  Install required dependencies: `npm install`
+3.  Initialize the visual development environment: `npm run storybook`
+4.  Execute the validation suite: `npm test`
+
+### Technical Command Reference
+*   `npm run build`: Generates production-ready distribution bundles via Rollup.
+*   `npm run lint`: Performs static analysis to ensure adherence to architectural standards.
+*   `npm test`: Executes the Jest-based unit and integration test suites.
+*   `npm run storybook`: Launches the component isolation and visual testing environment.
+
+---
+**Previous:** [Configuration Specification](./configuration.md) | **Next:** [Version Transition Guide](./breaking-changes.md)

package/docs/examples.md

@@ -0,0 +1,207 @@
+# Technical Implementation Guide
+## Implementation Patterns for the ResponsiveTable Component
+
+This guide details standard implementation patterns for the ResponsiveTable component, ordered by increasing complexity. Each section contains a production-ready example designed for integration into enterprise applications.
+
+## Table of Contents
+*   [Standard Tabular Implementation](#1-standard-tabular-implementation)
+*   [Implementing Sortable Columns](#2-implementing-sortable-columns)
+*   [Asynchronous Data Filtering](#3-asynchronous-data-filtering)
+*   [Row Selection Mechanisms](#4-row-selection-mechanisms)
+*   [Navigation and Master-Detail Patterns](#5-navigation-and-master-detail-patterns)
+*   [Programmatic Column Visibility Management](#6-programmatic-column-visibility-management)
+*   [Automated Footer Scaling Logic](#7-automated-footer-scaling-logic)
+*   [High-Volume Data: Asynchronous Infinite Scroll](#8-high-volume-data-asynchronous-infinite-scroll)
+*   [Internal Plugin Development](#9-internal-plugin-development)
+
+---
+
+[← Return to Overview](../README.md)
+
+### 1. Standard Tabular Implementation
+A baseline implementation for displaying structured data. The component will automatically transition to a card-based layout when the viewport width is less than 600px.
+
+```tsx
+import ResponsiveTable from 'jattac.libs.web.responsive-table';
+
+const data = [
+  { id: 1, name: 'Administrative User', role: 'Administrator' },
+  { id: 2, name: 'Standard User', role: 'User' },
+];
+
+const columns = [
+  { displayLabel: 'User Name', cellRenderer: (row) => row.name },
+  { displayLabel: 'Assigned Role', cellRenderer: (row) => row.role },
+];
+
+export const BasicTable = () => (
+  <ResponsiveTable data={data} columnDefinitions={columns} />
+);
+```
+
+### 2. Implementing Sortable Columns
+Enable sorting by defining a unique `columnId` and an associated sorting strategy via `getSortableValue` or a custom `sortComparer`.
+
+```tsx
+const columns = [
+  { 
+    columnId: 'name', 
+    displayLabel: 'Name', 
+    cellRenderer: (row) => row.name,
+    getSortableValue: (row) => row.name // Lexicographical sort
+  },
+  { 
+    columnId: 'date', 
+    displayLabel: 'Registration Date', 
+    cellRenderer: (row) => row.date.toLocaleDateString(),
+    sortComparer: (a, b, dir) => { // Chronological sort implementation
+      const diff = a.date.getTime() - b.date.getTime();
+      return dir === 'asc' ? diff : -diff;
+    }
+  },
+];
+```
+
+### 3. Asynchronous Data Filtering
+Implement client-side data filtering by providing the `filterProps` configuration object.
+
+```tsx
+const columns = [
+  { 
+    displayLabel: 'Name', 
+    cellRenderer: (row) => row.name,
+    getFilterableValue: (row) => row.name // Search target definition
+  },
+];
+
+<ResponsiveTable 
+  data={data} 
+  columnDefinitions={columns} 
+  filterProps={{ showFilter: true, filterPlaceholder: 'Filter by name...' }} 
+/>
+```
+
+### 4. Row Selection Mechanisms
+The component supports persistent row selection in both single and multiple selection modes. State is maintained across re-renders via internal plugin orchestration.
+
+```tsx
+<ResponsiveTable 
+  data={data} 
+  columnDefinitions={columns} 
+  selectionProps={{
+    mode: 'multiple',
+    rowIdKey: 'id',
+    onSelectionChange: (items) => console.info('Current Selection:', items)
+  }} 
+/>
+```
+
+### 5. Navigation and Master-Detail Patterns
+The `onRowClick` callback allows for the implementation of navigation patterns or detailed data inspection.
+
+```tsx
+<ResponsiveTable 
+  data={data} 
+  columnDefinitions={columns} 
+  onRowClick={(row) => navigateToDetail(row.id)} 
+/>
+```
+
+### 6. Programmatic Column Visibility Management
+Toggle column visibility dynamically. The component will automatically adjust the layout to reflect changes in the visible column set.
+
+```tsx
+const [isRoleVisible, setIsRoleVisible] = useState(false);
+
+const columns = [
+  { displayLabel: 'User Name', cellRenderer: (row) => row.name },
+  { 
+    displayLabel: 'Assigned Role', 
+    cellRenderer: (row) => row.role,
+    visible: isRoleVisible // State-driven visibility
+  },
+];
+```
+
+### 7. Automated Footer Scaling Logic
+When columns are programmatically hidden, the component automatically recalculates the `colSpan` of defined footer cells to maintain structural integrity.
+
+```tsx
+const footerRows = [
+  {
+    columns: [
+      { colSpan: 2, cellRenderer: () => <strong>Aggregate Totals</strong> },
+      { colSpan: 1, cellRenderer: () => <span>Count: {data.length}</span> },
+    ]
+  }
+];
+
+<ResponsiveTable 
+  data={data} 
+  columnDefinitions={columns} 
+  footerRows={footerRows} 
+/>
+```
+
+### 8. High-Volume Data: Asynchronous Infinite Scroll
+For datasets that exceed standard memory constraints, the infinite scroll feature allows for incremental data fetching during vertical scrolling.
+
+#### 1. Data Fetching Logic
+Define an asynchronous function to retrieve subsequent data increments.
+
+```tsx
+const fetchAdditionalData = async (currentDataset) => {
+  const pageIndex = Math.floor(currentDataset.length / 10) + 1;
+  const response = await api.users.get({ page: pageIndex });
+  return response.data; // Return null to indicate EOF
+};
+```
+
+#### 2. Component Configuration
+Enable the feature by providing the `infiniteScrollProps` configuration.
+
+```tsx
+import ResponsiveTable from 'jattac.libs.web.responsive-table';
+
+const UserManagementTable = () => {
+  return (
+    <ResponsiveTable
+      data={[]} 
+      columnDefinitions={columns}
+      maxHeight="600px" // Necessary for scroll event interception
+      infiniteScrollProps={{
+        onLoadMore: fetchAdditionalData,
+        hasMore: true,
+        loadingMoreComponent: <LoadingIndicator />,
+        noMoreDataComponent: <EndOfDataNotification />
+      }}
+    />
+  );
+};
+```
+
+### 9. Internal Plugin Development
+Extend the functional capabilities of the component by implementing the `IResponsiveTablePlugin` interface.
+
+```tsx
+import { IResponsiveTablePlugin } from 'jattac.libs.web.responsive-table';
+
+class CustomStylingPlugin<TData> implements IResponsiveTablePlugin<TData> {
+  public id = 'status-styler';
+
+  public getRowProps = (row: any) => {
+    if (row.isActive) return { className: 'row-active' };
+    return { className: 'row-inactive' };
+  };
+}
+
+// Integration
+<ResponsiveTable 
+  data={data} 
+  columnDefinitions={columns} 
+  plugins={[new CustomStylingPlugin()]} 
+/>
+```
+
+---
+**Previous:** [Overview](../README.md) | **Next:** [Functional Capabilities](./features.md)

package/docs/features.md

@@ -0,0 +1,33 @@
+# Functional Capabilities
+## Architectural Features of the ResponsiveTable Component
+
+This document provides a high-level overview of the technical capabilities and architectural patterns integrated into the ResponsiveTable component.
+
+## Table of Contents
+*   [Automated Layout Orchestration](#automated-layout-orchestration)
+*   [Asynchronous Data Stream Support](#asynchronous-data-stream-support)
+*   [Persistent Plugin Lifecycle](#persistent-plugin-lifecycle)
+*   [Structural Alignment Management](#structural-alignment-management)
+
+---
+
+[← Previous: Implementation Guide](./examples.md) | [Next: API Reference →](./api.md)
+
+### Automated Layout Orchestration
+ResponsiveTable performs real-time viewport analysis to transition between a standard tabular structure and an optimized card-based mobile interface. This ensures data density is managed appropriately for the available screen real estate.
+*   [Implementation Example: Standard Tabular Implementation](./examples.md#1-standard-tabular-implementation)
+
+### Asynchronous Data Stream Support
+Native integration for high-volume data sets via an infinite scrolling orchestrator. The component handles event interception, asynchronous state transitions, and subsequent data integration without disrupting the internal processing pipeline.
+*   [Implementation Example: Asynchronous Infinite Scroll](./examples.md#8-high-volume-data-asynchronous-infinite-scroll)
+
+### Persistent Plugin Lifecycle
+The component features a robust internal lifecycle management system for plugins. State for sorting, filtering, and selection is persisted across re-renders and data updates using non-reactive references, optimizing performance and ensuring data consistency.
+*   [Implementation Example: Sortable Columns](./examples.md#2-implementing-sortable-columns)
+
+### Structural Alignment Management
+Integrated logic for intelligent layout scaling automatically recalculates footer ranges. This ensures that column-level visibility toggles do not compromise the structural integrity or visual alignment of complex data grids.
+*   [Implementation Example: Column Visibility](./examples.md#6-programmatic-column-visibility-management)
+
+---
+**Previous:** [Implementation Guide](./examples.md) | **Next:** [API Reference](./api.md)

package/package.json

@@ -1,71 +1,117 @@
-{
-  "name": "jattac.libs.web.responsive-table",
-  "version": "0.7.5",
-  "description": "A fully responsive, customizable, and lightweight React table component with a modern, mobile-first design and a powerful plugin system.",
-  "main": "dist/index.js",
-  "module": "dist/index.es.js",
-  "types": "dist/index.d.ts",
-  "files": [
-    "dist"
-  ],
-  "scripts": {
-    "build": "rollup -c",
-    "watch": "rollup -c -w",
-    "lint": "eslint \"./{src,app}/**/*.{ts,tsx}\"",
-    "test": "jest",
-    "size": "size-limit",
-    "prepare": "npm run build"
-  },
-  "keywords": [
-    "react",
-    "typescript",
-    "table",
-    "responsive",
-    "component"
-  ],
-  "author": "Nyingi Maina",
-  "license": "MIT",
-  "peerDependencies": {
-    "react": ">=18.2.0",
-    "react-dom": ">=18.2.0",
-    "typescript": ">=3.7.0"
-  },
-  "devDependencies": {
-    "@rollup/plugin-commonjs": "^25.0.7",
-    "@rollup/plugin-node-resolve": "^15.2.3",
-    "@rollup/plugin-terser": "^0.4.4",
-    "@rollup/plugin-typescript": "^11.1.5",
-    "@size-limit/preset-small-lib": "^10.0.1",
-    "@testing-library/jest-dom": "^6.9.1",
-    "@testing-library/react": "^14.0.0",
-    "@types/jest": "^30.0.0",
-    "@types/react": "^18.2.33",
-    "@types/react-dom": "^18.2.14",
-    "@types/react-window": "^1.8.8",
-    "@typescript-eslint/eslint-plugin": "^6.9.1",
-    "@typescript-eslint/parser": "^6.9.1",
-    "eslint": "^8.52.0",
-    "eslint-config-prettier": "^9.0.0",
-    "eslint-plugin-prettier": "^5.0.1",
-    "eslint-plugin-react": "^7.33.2",
-    "identity-obj-proxy": "^3.0.0",
-    "jest": "^30.2.0",
-    "jest-environment-jsdom": "^30.2.0",
-    "postcss": "^8.4.31",
-    "prettier": "^3.0.3",
-    "react": "^18.2.0",
-    "react-dom": "^18.2.0",
-    "rollup": "^4.2.0",
-    "rollup-plugin-copy": "^3.5.0",
-    "rollup-plugin-delete": "^2.0.0",
-    "rollup-plugin-generate-package-json": "^3.2.0",
-    "rollup-plugin-peer-deps-external": "^2.2.4",
-    "rollup-plugin-postcss": "^4.0.2",
-    "size-limit": "^10.0.1",
-    "ts-jest": "^29.4.6",
-    "typescript": "^5.2.2"
-  },
-  "dependencies": {
-    "tslib": "^2.6.2"
-  }
-}
+{
+  "name": "jattac.libs.web.responsive-table",
+  "version": "0.8.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",
+    "email": "nyingi@jattac.com"
+  },
+  "license": "MIT",
+  "main": "./dist/index.js",
+  "module": "./dist/index.es.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.es.js",
+      "require": "./dist/index.js"
+    },
+    "./dist/*.css": "./dist/*.css"
+  },
+  "files": [
+    "dist",
+    "docs",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": [
+    "**/*.css",
+    "**/*.scss"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://nyingi.visualstudio.com/DefaultCollection/Jattac.Libs.Web.ResponsiveTable/_git/Jattac.Libs.Web.ResponsiveTable"
+  },
+  "bugs": {
+    "url": "https://nyingi.visualstudio.com/DefaultCollection/Jattac.Libs.Web.ResponsiveTable/_workitems"
+  },
+  "homepage": "https://nyingi.visualstudio.com/DefaultCollection/Jattac.Libs.Web.ResponsiveTable/_git/Jattac.Libs.Web.ResponsiveTable#readme",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "dev": "rollup -c -w",
+    "build": "rollup -c",
+    "lint": "eslint \"src/**/*.{ts,tsx}\"",
+    "lint:fix": "eslint \"src/**/*.{ts,tsx}\" --fix",
+    "format": "prettier --write \"src/**/*.{ts,tsx,css,md}\"",
+    "test": "jest",
+    "test:coverage": "jest --coverage",
+    "size": "size-limit",
+    "type-check": "tsc --noEmit",
+    "prepare": "npm run build",
+    "prepublishOnly": "npm run type-check && npm run lint && npm test"
+  },
+  "keywords": [
+    "react",
+    "typescript",
+    "table",
+    "datagrid",
+    "responsive",
+    "mobile-first",
+    "infinite-scroll",
+    "plugin-system"
+  ],
+  "peerDependencies": {
+    "react": ">=18.2.0",
+    "react-dom": ">=18.2.0"
+  },
+  "devDependencies": {
+    "@rollup/plugin-commonjs": "^25.0.7",
+    "@rollup/plugin-node-resolve": "^15.2.3",
+    "@rollup/plugin-terser": "^0.4.4",
+    "@rollup/plugin-typescript": "^11.1.5",
+    "@size-limit/preset-small-lib": "^10.0.1",
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "^14.0.0",
+    "@types/jest": "^30.0.0",
+    "@types/react": "^18.2.33",
+    "@types/react-dom": "^18.2.14",
+    "@types/react-window": "^1.8.8",
+    "@typescript-eslint/eslint-plugin": "^6.9.1",
+    "@typescript-eslint/parser": "^6.9.1",
+    "eslint": "^8.52.0",
+    "eslint-config-prettier": "^9.0.0",
+    "eslint-plugin-prettier": "^5.0.1",
+    "eslint-plugin-react": "^7.33.2",
+    "identity-obj-proxy": "^3.0.0",
+    "jest": "^30.2.0",
+    "jest-environment-jsdom": "^30.2.0",
+    "postcss": "^8.4.31",
+    "prettier": "^3.0.3",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "rollup": "^4.2.0",
+    "rollup-plugin-copy": "^3.5.0",
+    "rollup-plugin-delete": "^2.0.0",
+    "rollup-plugin-generate-package-json": "^3.2.0",
+    "rollup-plugin-peer-deps-external": "^2.2.4",
+    "rollup-plugin-postcss": "^4.0.2",
+    "size-limit": "^10.0.1",
+    "ts-jest": "^29.4.6",
+    "typescript": "^5.2.2"
+  },
+  "dependencies": {
+    "tslib": "^2.6.2"
+  },
+  "jest": {
+    "preset": "ts-jest",
+    "testEnvironment": "jsdom",
+    "moduleNameMapper": {
+      "\\.(css|less|sass|scss)$": "identity-obj-proxy"
+    },
+    "setupFilesAfterEnv": [
+      "<rootDir>/jest-setup.ts"
+    ]
+  }
+}