jtable-pro 1.0.0 → 1.0.2

package/README.md

@@ -1,221 +1,494 @@
 # jtable-pro
 
-A premium, app-like jQuery data-table plugin: a floating soft-shadow card,
-sticky blurred header, rounded controls and circular hover action buttons —
-with **global search**, **per-column search**, **column sorting**,
-**dropdown filters**, **client-side pagination** and **row selection**, all
-built in.
+<p align="center">
+  <strong>Powerful, lightweight and flexible JavaScript data table.</strong>
+</p>
 
-Ships as a single UMD file (no build step of its own) — works via a plain
-`<script>` tag, any bundler (Vite/webpack/Rollup), or AMD.
+<p align="center">
+  Sorting · Filtering · Pagination · Search · Responsive · Customizable
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/jtable-pro">
+    <img src="https://img.shields.io/npm/v/jtable-pro.svg" alt="npm version">
+  </a>
+  <a href="https://www.npmjs.com/package/jtable-pro">
+    <img src="https://img.shields.io/npm/dm/jtable-pro.svg" alt="npm downloads">
+  </a>
+  <a href="https://www.npmjs.com/package/jtable-pro">
+    <img src="https://img.shields.io/npm/l/jtable-pro.svg" alt="license">
+  </a>
+</p>
+
+---
+
+## ✨ What is jtable-pro?
+
+**jtable-pro** is a lightweight and flexible JavaScript table component designed for modern web applications.
+
+It provides common data-table functionality without forcing you to use a specific frontend framework.
+
+Whether you're building a simple HTML application, a Laravel admin panel, a Vue application, or a custom JavaScript project, jtable-pro can help you display and manage tabular data efficiently.
+
+### Why jtable-pro?
+
+* 🚀 Lightweight and fast
+* 🔍 Built-in search and filtering
+* ↕️ Column sorting
+* 📄 Pagination support
+* 📱 Responsive design
+* 🎨 Easy to customize
+* ⚡ Works with modern JavaScript
+* 🧩 Framework-friendly
+* 🔌 Easy API integration
+* 🛠️ Great for admin panels and dashboards
+
+---
+
+## 📦 Installation
+
+Install the package using npm:
+
+```bash
+npm install jtable-pro
+```
+
+Or with yarn:
+
+```bash
+yarn add jtable-pro
+```
+
+Or with pnpm:
+
+```bash
+pnpm add jtable-pro
+```
+
+---
+
+## 🚀 Quick Start
+
+Import `jtable-pro` into your JavaScript application:
+
+```javascript
+import JTable from 'jtable-pro';
+```
+
+Then initialize the table:
+
+```javascript
+const table = new JTable('#users-table', {
+    data: [
+        {
+            id: 1,
+            name: 'John Doe',
+            email: 'john@example.com'
+        },
+        {
+            id: 2,
+            name: 'Jane Doe',
+            email: 'jane@example.com'
+        }
+    ],
 
-```js
-$("#myTable").jtable({
     columns: [
-        { key: "name", label: "Name", sortable: true, columnSearch: true },
-        { key: "price", label: "Price", sortable: true, align: "right" },
+        {
+            key: 'id',
+            label: 'ID'
+        },
+        {
+            key: 'name',
+            label: 'Name'
+        },
+        {
+            key: 'email',
+            label: 'Email'
+        }
+    ]
+});
+```
+
+HTML:
+
+```html
+<div id="users-table"></div>
+```
+
+> The exact initialization options may vary depending on the version of jtable-pro you are using. See the API documentation below for the complete configuration.
+
+---
+
+# 🎯 Features
+
+## 🔍 Search
+
+Search through table data quickly.
+
+```javascript
+const table = new JTable('#users-table', {
+    searchable: true,
+    data: users
+});
+```
+
+---
+
+## ↕️ Sorting
+
+Enable column sorting:
+
+```javascript
+const table = new JTable('#users-table', {
+    sortable: true,
+    data: users
+});
+```
+
+---
+
+## 📄 Pagination
+
+Handle large datasets using pagination:
+
+```javascript
+const table = new JTable('#users-table', {
+    pagination: true,
+    pageSize: 20,
+    data: users
+});
+```
+
+---
+
+## 🎨 Custom Columns
+
+Define exactly how your columns should appear:
+
+```javascript
+const table = new JTable('#users-table', {
+    columns: [
+        {
+            key: 'name',
+            label: 'User Name'
+        },
+        {
+            key: 'email',
+            label: 'Email Address'
+        },
+        {
+            key: 'status',
+            label: 'Status'
+        }
     ],
-    data: rows, // or url: "/api/rows"
-    idField: "id",
+
+    data: users
 });
 ```
 
-## Requirements
-
-- **jQuery 3+** (peer dependency — bring your own, this package doesn't bundle it).
-- **Tailwind CSS**, v4-style (this plugin's markup uses opacity-modifier
-  classes like `bg-primary/10` and arbitrary-value classes like
-  `shadow-[0_1px_2px_rgba(16,24,40,0.04)]`).
-- A handful of **semantic design tokens** the rendered markup references by
-  name — these are not stock Tailwind colors/sizes, so add them to your
-  `@theme` (Tailwind v4) if they don't already exist in your project:
-
-  ```css
-  @theme {
-      --color-primary: #004ac6;
-      --color-on-primary: #ffffff;
-      --color-surface: #ffffff;
-      --color-surface-container-lowest: #ffffff;
-      --color-surface-container: #f3f4f6;
-      --color-surface-container-high: #e5e7eb;
-      --color-on-surface: #1f2937;
-      --color-on-surface-variant: #6b7280;
-      --color-outline-variant: #d1d5db;
-
-      --text-body-sm: 0.8125rem;
-      --text-body-md: 0.875rem;
-      --text-label-md: 0.75rem;
-  }
-  ```
-
-  Rename/retint these to match your own brand — jtable-pro only cares that
-  the token *names* resolve to something, not their exact values. (If your
-  project already has a Material-3-style semantic palette — `primary`,
-  `on-surface`, `surface-container*`, `outline-variant` — you very likely
-  already have all of these and can skip this step.)
+---
+
+# 🌐 API / Server-Side Data
+
+jtable-pro can be used with APIs and server-side applications.
+
+Example:
+
+```javascript
+const table = new JTable('#users-table', {
+    url: '/api/users',
+
+    pagination: true,
+    searchable: true,
+    sortable: true
+});
+```
+
+This makes jtable-pro suitable for applications where table data comes from a backend API.
+
+---
+
+# 🇱🇦 Laravel
+
+jtable-pro works well with Laravel applications and Laravel APIs.
 
 ## Install
 
 ```bash
-npm install jtable-pro jquery
+npm install jtable-pro
 ```
 
-```js
-import $ from "jquery";
-import "jtable-pro"; // registers $.fn.jtable
+Import it into your JavaScript:
 
-$("#myTable").jtable({ /* ... */ });
+```javascript
+import JTable from 'jtable-pro';
 ```
 
-Or a plain `<script>` tag, with jQuery loaded first:
+Example Laravel API:
 
-```html
-<script src="https://code.jquery.com/jquery-3.7.1.min.js"></script>
-<script src="https://unpkg.com/jtable-pro/src/jtable.js"></script>
-<script>
-    $("#myTable").jtable({ /* ... */ });
-</script>
+```php
+public function index()
+{
+    return response()->json([
+        'data' => User::paginate(20)
+    ]);
+}
+```
+
+Then use the endpoint:
+
+```javascript
+const table = new JTable('#users-table', {
+    url: '/api/users',
+    pagination: true,
+    searchable: true,
+    sortable: true
+});
 ```
 
-## Markup
+This makes jtable-pro a convenient option for:
 
-jtable-pro takes over an **empty container element** — a plain `<div>` —
-and renders the toolbar (search box, dropdown filters), the table, and the
-footer (summary + pagination) inside it:
+* Laravel Admin Panels
+* Laravel Dashboards
+* CRUD applications
+* User management systems
+* Product management
+* Order management
+* Reporting systems
 
-```html
-<div id="myTable"></div>
-```
-
-Don't hand-write `<table>`/`<thead>`/`<tbody>` — the plugin builds all of it.
-If the container already has children when `.jtable()` is called, they're
-replaced.
-
-## Options
-
-| Option | Type | Default | Description |
-|---|---|---|---|
-| `columns` | `Column[]` | `[]` | See **Column definition** below. |
-| `data` | `array` | `null` | Static array of row objects. Use this or `url`, not both. |
-| `url` | `string` | `null` | Fetched once via `$.ajax` on init and on `reload()`. The response is unwrapped by `responseAdapter` into a row array. |
-| `requestParams` | `object` | `{}` | Extra query params/body sent with the `url` request. |
-| `requestMethod` | `string` | `"GET"` | HTTP method for the `url` request. |
-| `responseAdapter` | `function(json) => array` | handles a plain array, `{data:[...]}`, `{data:{data:[...]}}` (Laravel paginator shape), `{items:[...]}`, `{data:{items:[...]}}` | Customize this if your API returns rows some other way. |
-| `idField` | `string` | `"id"` | Row identifier field (supports dot paths, e.g. `"product.id"`). Used by selection. |
-| `search` | `boolean` | `true` | Show the global search box. Matches any column not marked `searchable: false`. |
-| `searchPlaceholder` | `string` | `"Search..."` | |
-| `columnSearch` | `boolean` | `false` | Turns on a per-column filter-input row under the header for every column that has a `key` and hasn't opted out (`column.columnSearch: false`). A column can also opt **in** individually with `column.columnSearch: true` while this stays `false`. |
-| `filters` | `Filter[]` | `[]` | Toolbar dropdown filters (category/status-style selects). See below. |
-| `selectable` | `false \| "single" \| "multi"` | `false` | `"single"`: click a row to select it (one at a time, left accent bar). `"multi"`: adds a checkbox column with a header select-all. |
-| `onSelectionChange` | `function(rows, idSet)` | `null` | Fires after any selection change. |
-| `onRowClick` | `function(row, event)` | `null` | Fires on any row click (besides clicks on buttons/links/inputs inside the row), regardless of `selectable`. |
-| `pagination` | `boolean` | `true` | `false` renders every filtered row with no paging controls. |
-| `pageSize` | `number` | `10` | Rows per page. |
-| `pageSizes` | `number[]` | `null` | If set, renders a page-size `<select>` in the footer (e.g. `[10, 25, 50]`). |
-| `rowClass` | `function(row) => string` | `null` | Extra classes appended to a row's `<tr>`. |
-| `emptyText` / `loadingText` / `errorText` | `string` | English defaults | Shown in place of rows. |
-| `summaryTemplate` | `string` | `":count records"` | Footer left-hand text. `:count` is replaced with the filtered total. |
-| `pageTemplate` | `string` | `":page / :total"` | Footer page indicator. |
-| `prevLabel` / `nextLabel` | `string` | English defaults | `aria-label`s for the pagination buttons. |
-| `toolbar` | `function($slot, instance)` | `null` | Called once at init with a jQuery element appended to the toolbar row — use it to inject bespoke controls that don't fit the generic `filters` shape. |
-
-### Column definition
-
-```js
-{
-    key: "price",              // dot-path into the row object; omit for a pure render-only column (e.g. actions)
-    label: "Price",            // header text
-    sortable: true,            // default: true when `key` is set (unless options.sortable === false, or this column sets false)
-    searchable: true,          // default: true when `key` is set — whether the global search box matches this column
-    columnSearch: true,        // opt this column into (or out of, with false) the per-column filter row
-    align: "right",            // "left" (default) | "right" | "center"
-    sortValue: (row) => row.price_cents,  // optional: sort by a computed value instead of the raw `key` lookup
-    render: (row, value) => `<span class="...">${value}</span>`, // optional: custom cell HTML; omit to just escape-and-print `value`
-    cellClass: "whitespace-nowrap",
+---
+
+# 💚 Vue
+
+jtable-pro can also be integrated into Vue applications.
+
+```javascript
+import JTable from 'jtable-pro';
+
+const table = new JTable('#users-table', {
+    data: users,
+    pagination: true,
+    searchable: true
+});
+```
+
+---
+
+# ⚛️ React
+
+Because jtable-pro is JavaScript-based, it can also be integrated into React applications.
+
+Example:
+
+```javascript
+import { useEffect } from 'react';
+import JTable from 'jtable-pro';
+
+function UsersTable() {
+
+    useEffect(() => {
+        const table = new JTable('#users-table', {
+            data: users,
+            pagination: true,
+            searchable: true
+        });
+
+        return () => {
+            // Cleanup if required
+        };
+    }, []);
+
+    return (
+        <div id="users-table"></div>
+    );
 }
+
+export default UsersTable;
 ```
 
-`render` receives the **raw row** as well as the already-looked-up `value`,
-so a render function can pull in other fields too (e.g. a thumbnail column
-reading both `row.image` and `row.name`).
-
-**Action columns** (edit/delete buttons) are just a normal column with
-`sortable: false`, no `columnSearch`, and a `render` that returns whatever
-button markup you need — jtable-pro renders that HTML as-is and does
-**not** wire up clicks on it. Wire those yourself (e.g. `$(document).on("click", ".my-edit-btn", ...)`)
-against whatever stable class/attribute your `render` function emits.
-
-### Filter definition (toolbar dropdowns)
-
-```js
-filters: [
-    {
-        key: "category_id",        // matched with strict-string equality against getValue(row, key)
-        label: "Category",         // fallback text if allLabel is omitted
-        allLabel: "All categories",
-        options: [
-            { value: "3", label: "Dairy" },
-            { value: "7", label: "Produce" },
-        ],
-    },
-],
-```
-
-Selecting an option filters rows where `String(getValue(row, key)) ===
-String(option.value)`; selecting the "all" entry clears that filter.
-
-## Methods
-
-Call these the usual jQuery-plugin way — `$("#myTable").jtable("methodName", ...args)`:
-
-| Method | Description |
-|---|---|
-| `"setData"`, `data` | Replaces the row set and re-renders (resets to page 1). Use this after your own `$.ajax`/`fetch` call when you're not using the plugin's built-in `url` option. |
-| `"getData"` | Returns the current raw row array (unfiltered). |
-| `"reload"` | Re-runs the pipeline; if `url` was configured, re-fetches from the server first. |
-| `"getSelected"` | Returns the array of currently-selected row objects. |
-| `"clearSelection"` | Clears selection and re-renders. |
-| `"destroy"` | Unbinds events and empties the container. |
-
-```js
-// Fetch yourself and hand the plugin the rows:
-$.get("/api/products").done((response) => {
-    $("#myTable").jtable("setData", response.data);
+---
+
+# 📊 Example Use Cases
+
+jtable-pro is suitable for many types of web applications.
+
+### Admin Panels
+
+```text
+Users
+Products
+Orders
+Customers
+Invoices
+Payments
+```
+
+### Dashboards
+
+```text
+Analytics
+Reports
+Statistics
+Logs
+Transactions
+```
+
+### Business Applications
+
+```text
+Inventory
+Employees
+Customers
+Projects
+Tasks
+Orders
+```
+
+---
+
+# ⚙️ Configuration
+
+Example configuration:
+
+```javascript
+const table = new JTable('#users-table', {
+    data: users,
+
+    searchable: true,
+
+    sortable: true,
+
+    pagination: true,
+
+    pageSize: 20,
+
+    columns: [
+        {
+            key: 'id',
+            label: 'ID'
+        },
+        {
+            key: 'name',
+            label: 'Name'
+        },
+        {
+            key: 'email',
+            label: 'Email'
+        }
+    ]
 });
+```
+
+---
+
+# 🧩 Browser Support
+
+jtable-pro is designed for modern browsers that support modern JavaScript.
+
+Recommended browsers:
+
+* Google Chrome
+* Mozilla Firefox
+* Microsoft Edge
+* Safari
+
+---
+
+# 📚 Documentation
+
+Full documentation and examples:
+
+**Coming soon**
+
+---
+
+# 🖥️ Demo
+
+Try jtable-pro in your browser:
+
+**Coming soon**
+
+> A live demo is highly recommended so developers can see the component before installing it.
+
+---
+
+# 🤝 Contributing
 
-// Read the bulk-action selection:
-const selectedIds = $("#myTable").jtable("getSelected").map((row) => row.id);
+Contributions are welcome!
+
+If you find a bug or have an idea for a new feature:
+
+1. Fork the repository
+2. Create a new branch
+3. Make your changes
+4. Commit your changes
+5. Open a Pull Request
+
+Example:
+
+```bash
+git clone https://github.com/YOUR_USERNAME/jtable-pro.git
+
+cd jtable-pro
+
+npm install
+
+npm run dev
 ```
 
-## Selection & row identity
+---
+
+# 🐛 Bug Reports
+
+Found a bug?
+
+Please open an issue on GitHub and include:
+
+* Browser
+* Operating system
+* jtable-pro version
+* Steps to reproduce
+* Expected behavior
+* Actual behavior
+
+---
+
+# 🗺️ Roadmap
+
+Planned improvements may include:
+
+* [ ] Server-side pagination
+* [ ] Advanced filtering
+* [ ] Column resizing
+* [ ] Column visibility
+* [ ] Row selection
+* [ ] Export to CSV
+* [ ] Export to Excel
+* [ ] Custom cell rendering
+* [ ] Virtual scrolling
+* [ ] Better mobile support
+* [ ] Vue integration
+* [ ] React integration
+* [ ] TypeScript support
+
+---
+
+# 📄 License
+
+This project is licensed under the **MIT License**.
 
-Row identity for selection is always the **string** form of
-`getValue(row, idField)` (`idField` supports dot-paths, e.g.
-`"product.id"`). DOM reads use `.attr("data-jtable-id")` rather than
-jQuery's auto-coercing `.data()`, so a row's identity stays consistent
-whether real ids are numeric, UUIDs, or codes that merely *look* numeric
-(e.g. `"007"`, which jQuery's `.data()` would otherwise silently mis-coerce
-into the number `7`).
+See the `LICENSE` file for more information.
 
-## i18n
+---
 
-Every user-facing string is a plain option — `searchPlaceholder`,
-`emptyText`, `loadingText`, `errorText`, `summaryTemplate`, `prevLabel`,
-`nextLabel`, column `label`s, filter `label`/`allLabel`/option `label`s.
-There's no bundled translation system; pass whatever locale strings your own
-app already has.
+# ⭐ Support the Project
 
-## What it doesn't do
+If you find **jtable-pro** useful, consider giving the project a ⭐ on GitHub.
 
-- No CSS is bundled — you provide Tailwind. There's no fallback/plain-CSS
-  mode.
-- No server-side pagination/sorting/filtering — `url` mode fetches once and
-  everything after that runs client-side. For very large datasets, fetch a
-  bounded page yourself and call `setData()` again as the user paginates on
-  your end, or filter server-side and reload.
-- No built-in row-action wiring (edit/delete/etc.) — a render-only "actions"
-  column plus your own click handlers, same as any other column.
+Your support helps the project grow and motivates further development.
 
-## License
+---
 
-MIT
+<p align="center">
+  Made with ❤️ for JavaScript developers
+</p>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jtable-pro",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Premium, app-like jQuery data-table plugin: global search, per-column search, sortable columns, dropdown filters, client-side pagination and row selection — one file, no build step.",
   "main": "src/jtable.js",
   "module": "src/jtable.js",