wefix-sort-grid
v1.0.0
Published
A powerful JavaScript datagrid library with Redux-powered state management, providing advanced sorting, filtering, and pagination through a declarative control system
Maintainers
envindavsorgReadme
@wefix/sort-grid
A powerful and flexible JavaScript datagrid library providing advanced sorting, filtering, and pagination capabilities through a declarative control system. Built with Redux for predictable state management and Immer for efficient immutable updates.
Features
- 🎛️ Declarative Control System - Register custom controls through a simple, extensible API
- 🔄 Redux-Powered State Management - Predictable, centralized state with time-travel debugging support
- ⚡ Immutable Updates with Immer - Efficient state updates using copy-on-write semantics
- 🔍 Advanced Filtering - Button filters with toggle states and customizable logic
- 📊 Sorting Capabilities - Multi-column sorting with configurable directions
- 📄 Pagination - Built-in pagination controls for large datasets
- 💾 State Persistence - Automatic state restoration from deep links, storage, or HTML attributes
- 🎯 Memoized Selectors - Optimized performance with Reselect for derived state
Installation
npm install @wefix/sort-gridOr using yarn:
yarn add @wefix/sort-gridQuick Start
Basic Usage
<!DOCTYPE html>
<html>
<head>
<title>DataGrid Example</title>
</head>
<body>
<!-- Include the library -->
<script src="node_modules/@wefix/sort-grid/datagrid.min.js"></script>
<!-- Define your grid controls -->
<button class="filter-control"
data-id="status-filter"
data-checked="false">
Active Items
</button>
<script>
// Your grid initialization code here
</script>
</body>
</html>Creating Custom Controls
Register custom controls by extending the global window.datagridControls object:
window.datagridControls['my-custom-control'] = function(control, store, rootSlice) {
var $control = control.$control;
// Get control configuration from data attributes
var dataID = $control.getAttribute('data-id');
// Subscribe to store updates for reactive behavior
store.subscribe(function() {
var state = store.getState();
var action = state.actions[dataID];
// Update control based on state
if (action) {
// Update UI based on action state
}
});
// Add event listeners
$control.addEventListener('click', function(evt) {
evt.preventDefault();
// Dispatch actions to update state
store.dispatch({
type: 'UPDATE_ACTION',
payload: { /* your data */ }
});
});
};Built-in Control Types
Button Filter
Toggle filter control with checked state management:
<button class="dg-button-filter"
data-id="my-filter"
data-checked="true">
Filter Name
</button>Features:
- Automatic checked state toggle
- CSS class management (
dg-checked) - State restoration from store or HTML attributes
Pagination
Page navigation controls for dataset pagination:
<div class="dg-pagination"
data-id="main-pagination">
<!-- Pagination controls -->
</div>Architecture
State Management
The library uses Redux with the following state structure:
{
actions: {
'control-id': {
path: 'filter.value',
// ... other action properties
}
},
// ... other state slices
}Control Lifecycle
- Initialization - Controls are registered on
window.datagridControls - Store Subscription - Each control subscribes to relevant state changes
- State Restoration - State is restored from:
- Redux store (priority)
- Deep links / localStorage
- Initial HTML attributes (fallback)
- Event Handling - User interactions dispatch Redux actions
- Reactive Updates - Store subscribers update UI based on new state
API Reference
Control Registration
window.datagridControls[controlType] = function(control, store, rootSlice)Parameters:
control- Control configuration object containing$controlDOM elementstore- Redux store instance withgetState(),dispatch(), andsubscribe()methodsrootSlice- Root state slice for scoped state access
Control Properties
Access control properties via the $control DOM element:
var $control = control.$control;
$control.control // Reference back to control object
$control.store // Redux store instance
$control.rootSlice // Root state slice
$control.dataID // Control identifier from data-id attribute
$control.checked // Boolean checked state (for filters)State Restoration
Controls automatically restore their state from multiple sources in priority order:
- Redux Store - Existing state from
store.getState().actions[dataID] - Deep Links - URL parameters or browser history
- Local Storage - Persisted state from previous sessions
- HTML Attributes - Initial state from
data-*attributes
Performance Optimizations
- Memoized Selectors - Reselect library prevents unnecessary recomputations
- Immutable Updates - Immer ensures efficient structural sharing
- Middleware Pipeline - Redux Thunk for async operations
- Development/Production Builds - Optimized minified build for production
Browser Support
The library works in all modern browsers that support:
- ES5+ JavaScript
- Redux (included)
- Proxies (for Immer, with ES5 fallback)
Development
This repository contains the distribution build. To use in development:
<!-- Development build with source maps -->
<script src="node_modules/@wefix/sort-grid/datagrid.js"></script>
<!-- Production build (minified) -->
<script src="node_modules/@wefix/sort-grid/datagrid.min.js"></script>File Structure
@wefix/sort-grid/
├── datagrid.js # Development build with source maps (~185KB)
├── datagrid.min.js # Production minified build (~47KB)
├── datagrid.js.map # Source map for debugging
├── package.json # Package metadata
├── license # ISC License
└── README.md # This fileBuilt With
- Redux - Predictable state container
- Immer - Immutable state updates
- Reselect - Memoized selectors
- Redux Toolkit - Modern Redux utilities
- Redux Thunk - Async middleware
Based on JSOcean DataGrid v2.0.1
Authors
- Cuzeac Florin - [email protected]
- Thomas Boual - [email protected]
License
This project is licensed under the ISC License - see the license file for details.
Keywords
wefix sort grid datagrid redux filter pagination immutable state-management
Note: This package contains the distribution build only. For source code access or contributions, please contact the maintainers.