jtable-pro 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hanifi Çorak
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,221 @@
+# 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.
+
+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.
+
+```js
+$("#myTable").jtable({
+    columns: [
+        { key: "name", label: "Name", sortable: true, columnSearch: true },
+        { key: "price", label: "Price", sortable: true, align: "right" },
+    ],
+    data: rows, // or url: "/api/rows"
+    idField: "id",
+});
+```
+
+## 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.)
+
+## Install
+
+```bash
+npm install jtable-pro jquery
+```
+
+```js
+import $ from "jquery";
+import "jtable-pro"; // registers $.fn.jtable
+
+$("#myTable").jtable({ /* ... */ });
+```
+
+Or a plain `<script>` tag, with jQuery loaded first:
+
+```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>
+```
+
+## Markup
+
+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:
+
+```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",
+}
+```
+
+`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);
+});
+
+// Read the bulk-action selection:
+const selectedIds = $("#myTable").jtable("getSelected").map((row) => row.id);
+```
+
+## Selection & row identity
+
+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`).
+
+## 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.
+
+## What it doesn't do
+
+- 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.
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "jtable-pro",
+  "version": "1.0.0",
+  "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",
+  "unpkg": "src/jtable.js",
+  "type": "commonjs",
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "jquery",
+    "jquery-plugin",
+    "table",
+    "datatable",
+    "data-table",
+    "grid",
+    "sort",
+    "filter",
+    "search",
+    "pagination",
+    "tailwind",
+    "tailwindcss"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "jquery": ">=3.0.0"
+  },
+  "engines": {
+    "node": ">=14"
+  }
+}

package/src/jtable.js

@@ -0,0 +1,861 @@
+/**
+ * jtable-pro — premium, app-like jQuery data-table plugin.
+ *
+ * A floating soft-shadow card, sticky blurred header and rounded, circular
+ * hover controls, wired up as a single drop-in plugin: global search,
+ * per-column search, column sorting, dropdown filters, client-side
+ * pagination and row selection.
+ *
+ * Requires Tailwind CSS (v4-style opacity-modifier/arbitrary-value classes,
+ * e.g. `bg-primary/10`, `shadow-[...]`) with a handful of semantic design
+ * tokens defined — see README.md "Requirements" for the exact `@theme`
+ * block to add if your project doesn't already have them.
+ *
+ * Usage: see README.md for the full option/method reference.
+ *
+ *   // Bundler (Vite/webpack/Rollup): CJS/ESM interop handles the import.
+ *   import $ from "jquery";
+ *   import "jtable-pro";
+ *   $("#myTable").jtable({ columns: [...], data: [...] });
+ *
+ *   // Or a plain <script> tag, after jQuery is already loaded:
+ *   //   <script src="https://.../jquery.min.js"></script>
+ *   //   <script src="https://.../jtable-pro/dist/jtable.js"></script>
+ *
+ * Ships as a single UMD file (like classic jQuery plugins — DataTables,
+ * Select2, etc.) so it works both ways above and via AMD, with no build
+ * step of its own required.
+ */
+(function (factory) {
+    if (typeof define === "function" && define.amd) {
+        define(["jquery"], factory);
+    } else if (typeof module === "object" && module.exports) {
+        module.exports = factory(require("jquery"));
+    } else {
+        factory(jQuery);
+    }
+})(function ($) {
+
+// -- Icons (inlined Heroicons-outline-style SVGs, no icon font/library needed) --
+
+const SEARCH_ICON =
+    '<svg class="h-4.5 w-4.5" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5">' +
+    '<path stroke-linecap="round" stroke-linejoin="round" d="m21 21-5.197-5.197m0 0A7.5 7.5 0 1 0 5.196 5.196a7.5 7.5 0 0 0 10.607 10.607Z" />' +
+    "</svg>";
+
+const CLEAR_ICON =
+    '<svg class="h-4 w-4" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">' +
+    '<path stroke-linecap="round" stroke-linejoin="round" d="M6 18 18 6M6 6l12 12" />' +
+    "</svg>";
+
+const CHEVRON_DOWN_ICON =
+    '<svg class="h-4 w-4 shrink-0" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5">' +
+    '<path stroke-linecap="round" stroke-linejoin="round" d="m19.5 8.25-7.5 7.5-7.5-7.5" />' +
+    "</svg>";
+
+const CHEVRON_LEFT_ICON =
+    '<svg class="h-4 w-4" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5">' +
+    '<path stroke-linecap="round" stroke-linejoin="round" d="M15.75 19.5 8.25 12l7.5-7.5" />' +
+    "</svg>";
+
+const CHEVRON_RIGHT_ICON =
+    '<svg class="h-4 w-4" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5">' +
+    '<path stroke-linecap="round" stroke-linejoin="round" d="m8.25 4.5 7.5 7.5-7.5 7.5" />' +
+    "</svg>";
+
+// Neutral "sortable, not currently sorted" indicator (chevron-up-down glyph).
+const SORT_NEUTRAL_ICON =
+    '<svg class="h-3.5 w-3.5 text-on-surface-variant/40 group-hover:text-on-surface-variant/70" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">' +
+    '<path stroke-linecap="round" stroke-linejoin="round" d="M8 9l4-4 4 4M8 15l4 4 4-4" />' +
+    "</svg>";
+
+const SORT_ASC_ICON =
+    '<svg class="h-3.5 w-3.5 text-primary" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5">' +
+    '<path stroke-linecap="round" stroke-linejoin="round" d="M5 12.5 12 6l7 6.5" />' +
+    "</svg>";
+
+const SORT_DESC_ICON =
+    '<svg class="h-3.5 w-3.5 text-primary" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5">' +
+    '<path stroke-linecap="round" stroke-linejoin="round" d="M5 11.5 12 18l7-6.5" />' +
+    "</svg>";
+
+// -- Small helpers --
+
+function escapeHtml(value) {
+    return $("<div>").text(value ?? "").html();
+}
+
+/** Reads `a.b.c` style dotted paths off a row object. */
+function getValue(row, key) {
+    if (!key) {
+        return undefined;
+    }
+    return key.split(".").reduce((acc, part) => (acc == null ? acc : acc[part]), row);
+}
+
+/** Locale/numeric-aware comparator used by default column sorting. */
+function compareValues(a, b) {
+    if (a == null && b == null) return 0;
+    if (a == null) return -1;
+    if (b == null) return 1;
+
+    if (typeof a === "number" && typeof b === "number") {
+        return a - b;
+    }
+
+    const na = Number(a);
+    const nb = Number(b);
+    if (a !== "" && b !== "" && !Number.isNaN(na) && !Number.isNaN(nb)) {
+        return na - nb;
+    }
+
+    return String(a).localeCompare(String(b), undefined, { sensitivity: "base", numeric: true });
+}
+
+/**
+ * Default `url`-mode response unwrapping: works out of the box for a plain
+ * array, `{ data: [...] }`, or a nested `{ data: { data: [...] } }` (the
+ * common shape of a Laravel paginator's JSON). Pass your own
+ * `responseAdapter` option if your API returns rows some other way.
+ */
+function defaultResponseAdapter(json) {
+    if (Array.isArray(json)) {
+        return json;
+    }
+    if (Array.isArray(json?.data)) {
+        return json.data;
+    }
+    if (Array.isArray(json?.data?.data)) {
+        return json.data.data;
+    }
+    if (Array.isArray(json?.items)) {
+        return json.items;
+    }
+    if (Array.isArray(json?.data?.items)) {
+        return json.data.items;
+    }
+    return [];
+}
+
+let instanceCounter = 0;
+
+// A single page-lifetime delegated listener (not one per instance) that
+// closes any open filter dropdown on an outside click.
+let outsideClickBound = false;
+function ensureOutsideClickHandler() {
+    if (outsideClickBound) {
+        return;
+    }
+    outsideClickBound = true;
+    $(document).on("click", (e) => {
+        if (!$(e.target).closest(".jtable-filter").length) {
+            $(".jtable-filter-panel").addClass("hidden");
+        }
+    });
+}
+
+const DEFAULTS = {
+    // Column definitions — see README.md for the full shape.
+    columns: [],
+
+    // Data source: pass one of these two.
+    data: null, // static array of row objects
+    url: null, // ajax endpoint, fetched once via $.ajax({ url, data: requestParams })
+    requestParams: {},
+    requestMethod: "GET",
+    responseAdapter: defaultResponseAdapter, // (json) => row array
+
+    // Unique row identifier field, used by selection.
+    idField: "id",
+
+    // Global search box (searches every column not explicitly excluded).
+    search: true,
+    searchPlaceholder: "Search...",
+
+    // Per-column search inputs under the header. `false` disables globally;
+    // individual columns can still opt in with `column.columnSearch: true`.
+    columnSearch: false,
+
+    // Dropdown filters rendered in the toolbar, e.g. category/status selects.
+    // [{ key, label, allLabel, options: [{ value, label }] }]
+    filters: [],
+
+    // 'single' (click a row to select it, one at a time) | 'multi' (checkbox
+    // column, multi-select) | false (no selection UI).
+    selectable: false,
+    onSelectionChange: null,
+
+    // Pagination (client-side). Set to false to render every filtered row.
+    pagination: true,
+    pageSize: 10,
+    pageSizes: null, // e.g. [10, 25, 50] to render a page-size <select>
+
+    // Row-level extras.
+    rowClass: null, // function(row) => extra class string
+    onRowClick: null, // function(row, event)
+
+    // Text — all user-facing strings are plain options, so you can localize
+    // them however your project already does (see README.md "i18n").
+    emptyText: "No records found",
+    loadingText: "Loading...",
+    errorText: "Failed to load data",
+    summaryTemplate: ":count records",
+    prevLabel: "Previous page",
+    nextLabel: "Next page",
+    pageTemplate: ":page / :total",
+
+    // Called once, right after the toolbar is built, with the toolbar's
+    // right-hand slot ($el) so callers can append their own extra controls.
+    toolbar: null,
+};
+
+const INTERACTIVE_SELECTOR = "button, a, input, select, textarea, label, .jtable-no-row-click";
+
+class JTable {
+    constructor(el, options) {
+        this.id = `jtable-${++instanceCounter}`;
+        this.$el = $(el);
+        this.options = $.extend(true, {}, DEFAULTS, options);
+        this.state = {
+            rawData: [],
+            search: "",
+            columnFilters: {},
+            activeFilters: {},
+            sortKey: null,
+            sortDir: null, // 'asc' | 'desc'
+            page: 1,
+            pageSize: this.options.pageSize,
+            selected: new Set(),
+            loading: false,
+            error: false,
+        };
+
+        this._buildSkeleton();
+        this._bindEvents();
+        this.reload();
+    }
+
+    // -- Rendering the static shell (toolbar + table + footer) --
+
+    _buildSkeleton() {
+        const o = this.options;
+        const hasToolbar = o.search || o.filters.length > 0 || typeof o.toolbar === "function";
+
+        let html = "";
+
+        if (hasToolbar) {
+            html += `
+                <div class="jtable-toolbar flex flex-col gap-3 rounded-2xl bg-surface-container-lowest p-4 shadow-[0_1px_2px_rgba(16,24,40,0.04),0_4px_24px_-8px_rgba(16,24,40,0.1)] ring-1 ring-black/[0.03] sm:flex-row sm:items-center">
+                    ${o.search ? this._searchBoxHtml() : ""}
+                    <div class="jtable-filters flex flex-wrap items-center gap-2"></div>
+                    <div class="jtable-toolbar-extra flex flex-wrap items-center gap-2"></div>
+                </div>
+            `;
+        }
+
+        html += `
+            <div class="jtable-card mt-6 overflow-hidden rounded-2xl bg-surface-container-lowest shadow-[0_1px_2px_rgba(16,24,40,0.04),0_4px_24px_-8px_rgba(16,24,40,0.1)] ring-1 ring-black/[0.03]">
+                <div class="jtable-scroll overflow-auto">
+                    <table class="w-full whitespace-nowrap text-left">
+                        <thead class="sticky top-0 z-10"></thead>
+                        <tbody class="jtable-body divide-y divide-outline-variant/40"></tbody>
+                    </table>
+                </div>
+                <div class="jtable-footer flex flex-wrap items-center justify-between gap-3 border-t border-outline-variant/60 px-4 py-3">
+                    <p class="jtable-summary text-body-sm text-on-surface-variant"></p>
+                    <div class="jtable-pagination flex items-center gap-1"></div>
+                </div>
+            </div>
+        `;
+
+        if (!hasToolbar) {
+            // Strip the leading margin the card would otherwise carry when
+            // it's the very first thing inside the container.
+            html = html.replace("jtable-card mt-6", "jtable-card");
+        }
+
+        this.$el.addClass("jtable").html(html);
+
+        this.$search = this.$el.find(".jtable-search-input");
+        this.$searchClear = this.$el.find(".jtable-search-clear");
+        this.$filters = this.$el.find(".jtable-filters");
+        this.$toolbarExtra = this.$el.find(".jtable-toolbar-extra");
+        this.$thead = this.$el.find("thead");
+        this.$tbody = this.$el.find(".jtable-body");
+        this.$summary = this.$el.find(".jtable-summary");
+        this.$pagination = this.$el.find(".jtable-pagination");
+
+        this._renderFilters();
+        this._renderHead();
+
+        if (typeof o.toolbar === "function") {
+            o.toolbar(this.$toolbarExtra, this);
+        }
+    }
+
+    _searchBoxHtml() {
+        return `
+            <div class="jtable-search relative flex-1">
+                <span class="pointer-events-none absolute inset-y-0 left-0 flex items-center pl-3 text-on-surface-variant">
+                    ${SEARCH_ICON}
+                </span>
+                <input
+                    type="text"
+                    class="jtable-search-input w-full rounded-xl border-0 bg-surface-container/60 py-2.5 pl-10 pr-9 text-body-sm text-on-surface placeholder:text-on-surface-variant transition-all duration-200 focus:bg-surface-container-lowest focus:shadow-[0_1px_2px_rgba(16,24,40,0.06)] focus:outline-none focus:ring-2 focus:ring-primary"
+                    placeholder="${escapeHtml(this.options.searchPlaceholder)}"
+                >
+                <button type="button" class="jtable-search-clear jtable-no-row-click absolute inset-y-0 right-0 hidden items-center pr-3 text-on-surface-variant transition hover:text-on-surface" aria-label="Clear">
+                    ${CLEAR_ICON}
+                </button>
+            </div>
+        `;
+    }
+
+    _renderFilters() {
+        const filters = this.options.filters || [];
+        if (!filters.length) {
+            return;
+        }
+
+        const html = filters
+            .map((filter) => {
+                const optionsHtml = [`<a href="#" data-value="" class="block px-3.5 py-2 text-body-sm text-on-surface-variant hover:bg-surface-container">${escapeHtml(filter.allLabel ?? filter.label)}</a>`]
+                    .concat(
+                        (filter.options || []).map(
+                            (opt) =>
+                                `<a href="#" data-value="${escapeHtml(opt.value)}" class="block px-3.5 py-2 text-body-sm text-on-surface-variant hover:bg-surface-container">${escapeHtml(opt.label)}</a>`
+                        )
+                    )
+                    .join("");
+
+                return `
+                    <div class="jtable-filter relative" data-filter-key="${escapeHtml(filter.key)}">
+                        <button type="button" class="jtable-filter-toggle flex items-center justify-between gap-2 rounded-xl bg-surface-container/60 px-3.5 py-2.5 text-body-sm font-medium text-on-surface transition-all duration-200 hover:bg-surface-container">
+                            <span class="jtable-filter-label truncate">${escapeHtml(filter.allLabel ?? filter.label)}</span>
+                            ${CHEVRON_DOWN_ICON}
+                        </button>
+                        <div class="jtable-filter-panel absolute left-0 right-0 z-20 mt-2 hidden max-h-64 min-w-[10rem] overflow-y-auto rounded-xl bg-surface-container-lowest py-1 shadow-[0_4px_24px_-4px_rgba(16,24,40,0.15)] ring-1 ring-black/[0.05]">
+                            ${optionsHtml}
+                        </div>
+                    </div>
+                `;
+            })
+            .join("");
+
+        this.$filters.html(html);
+    }
+
+    _renderHead() {
+        const o = this.options;
+        const columns = o.columns;
+        const anyColumnSearch = columns.some((c) => c.columnSearch === true) || (o.columnSearch && columns.some((c) => c.key && c.columnSearch !== false));
+
+        let headRow = "<tr>";
+        if (o.selectable === "multi") {
+            headRow += `<th class="w-10 py-3 pl-4"><input type="checkbox" class="jtable-select-all h-4 w-4 rounded border-outline-variant text-primary focus:ring-primary"></th>`;
+        }
+
+        columns.forEach((col, index) => {
+            const sortable = col.sortable !== false && col.key && o.sortable !== false;
+            const align = col.align === "right" ? "text-right justify-end" : col.align === "center" ? "text-center justify-center" : "text-left justify-start";
+            const padStart = index === 0 && o.selectable !== "multi" ? "pl-4" : "px-3";
+            const padEnd = index === columns.length - 1 ? "pr-4" : "";
+
+            headRow += `
+                <th class="${padStart} ${padEnd} py-3 text-label-md font-semibold uppercase tracking-wider text-on-surface-variant ${col.align === "right" ? "text-right" : ""}" data-col="${index}">
+                    ${
+                        sortable
+                            ? `<button type="button" class="jtable-sort-btn jtable-no-row-click group inline-flex items-center gap-1 ${align}" data-key="${escapeHtml(col.key)}">
+                                <span>${escapeHtml(col.label ?? "")}</span>
+                                <span class="jtable-sort-icon inline-flex">${SORT_NEUTRAL_ICON}</span>
+                            </button>`
+                            : `<span>${escapeHtml(col.label ?? "")}</span>`
+                    }
+                </th>
+            `;
+        });
+        headRow += "</tr>";
+
+        let filterRow = "";
+        if (anyColumnSearch) {
+            filterRow = "<tr class=\"jtable-filter-row border-b border-outline-variant/40 bg-surface-container/40\">";
+            if (o.selectable === "multi") {
+                filterRow += `<td class="py-2 pl-4"></td>`;
+            }
+            columns.forEach((col, index) => {
+                const enabled = col.columnSearch === true || (o.columnSearch && col.key && col.columnSearch !== false);
+                const padStart = index === 0 && o.selectable !== "multi" ? "pl-4" : "px-3";
+                filterRow += `<td class="${padStart} py-2">`;
+                if (enabled) {
+                    filterRow += `<input type="text" class="jtable-col-search w-full rounded-lg border-0 bg-surface-container-lowest px-2.5 py-1.5 text-body-sm text-on-surface placeholder:text-on-surface-variant/70 ring-1 ring-inset ring-outline-variant/60 focus:outline-none focus:ring-2 focus:ring-primary" data-key="${escapeHtml(col.key)}" placeholder="Filter...">`;
+                }
+                filterRow += "</td>";
+            });
+            filterRow += "</tr>";
+        }
+
+        this.$thead.html(headRow.replace("<tr>", '<tr class="border-b border-outline-variant/60 bg-surface-container/95 backdrop-blur">') + filterRow);
+    }
+
+    // -- Events (all scoped to this.$el — the whole subtree can simply be
+    // torn down/rebuilt by your own routing/navigation code with no extra
+    // cleanup, since jQuery's own cleanData runs on any removed descendant) --
+
+    _bindEvents() {
+        let searchTimer = null;
+        this.$el.on("input", ".jtable-search-input", (e) => {
+            const value = $(e.target).val();
+            this.$searchClear.toggleClass("hidden", !value);
+            clearTimeout(searchTimer);
+            searchTimer = setTimeout(() => {
+                this.state.search = value.trim().toLowerCase();
+                this.state.page = 1;
+                this._render();
+            }, 150);
+        });
+
+        this.$el.on("click", ".jtable-search-clear", () => {
+            this.$search.val("").trigger("focus");
+            this.$searchClear.addClass("hidden");
+            this.state.search = "";
+            this.state.page = 1;
+            this._render();
+        });
+
+        let colSearchTimer = null;
+        this.$el.on("input", ".jtable-col-search", (e) => {
+            const $input = $(e.target);
+            const key = $input.data("key");
+            const value = $input.val();
+            clearTimeout(colSearchTimer);
+            colSearchTimer = setTimeout(() => {
+                if (value) {
+                    this.state.columnFilters[key] = value.trim().toLowerCase();
+                } else {
+                    delete this.state.columnFilters[key];
+                }
+                this.state.page = 1;
+                this._render();
+            }, 150);
+        });
+
+        this.$el.on("click", ".jtable-sort-btn", (e) => {
+            const key = $(e.currentTarget).data("key");
+            if (this.state.sortKey !== key) {
+                this.state.sortKey = key;
+                this.state.sortDir = "asc";
+            } else if (this.state.sortDir === "asc") {
+                this.state.sortDir = "desc";
+            } else {
+                this.state.sortKey = null;
+                this.state.sortDir = null;
+            }
+            this._render();
+        });
+
+        // Dropdown filters (category/status style selects in the toolbar).
+        this.$el.on("click", ".jtable-filter-toggle", (e) => {
+            e.stopPropagation();
+            const $panel = $(e.currentTarget).siblings(".jtable-filter-panel");
+            const wasOpen = !$panel.hasClass("hidden");
+            this.$el.find(".jtable-filter-panel").addClass("hidden");
+            $panel.toggleClass("hidden", wasOpen);
+        });
+
+        this.$el.on("click", ".jtable-filter-panel a", (e) => {
+            e.preventDefault();
+            const $option = $(e.currentTarget);
+            const $filter = $option.closest(".jtable-filter");
+            const key = $filter.data("filter-key");
+            const value = $option.data("value");
+
+            $filter.find(".jtable-filter-label").text($option.text());
+            $filter.find(".jtable-filter-panel").addClass("hidden");
+
+            if (value === "" || value == null) {
+                delete this.state.activeFilters[key];
+            } else {
+                this.state.activeFilters[key] = String(value);
+            }
+            this.state.page = 1;
+            this._render();
+        });
+
+        ensureOutsideClickHandler();
+
+        // Row selection.
+        this.$tbody.on("click", "tr[data-jtable-id]", (e) => {
+            if ($(e.target).closest(INTERACTIVE_SELECTOR).length) {
+                return;
+            }
+            const $row = $(e.currentTarget);
+            const id = $row.attr("data-jtable-id");
+            const row = this.state.rawData.find((r) => this._rowId(r) === id);
+
+            if (this.options.selectable === "single") {
+                this.state.selected = this.state.selected.has(id) ? new Set() : new Set([id]);
+                this._updateSelectionUi();
+                this._fireSelectionChange();
+            }
+
+            if (typeof this.options.onRowClick === "function") {
+                this.options.onRowClick(row, e);
+            }
+        });
+
+        this.$tbody.on("change", ".jtable-row-check", (e) => {
+            const id = $(e.currentTarget).attr("data-jtable-id");
+            if (e.currentTarget.checked) {
+                this.state.selected.add(id);
+            } else {
+                this.state.selected.delete(id);
+            }
+            this._updateSelectionUi();
+            this._fireSelectionChange();
+        });
+
+        this.$thead.on("change", ".jtable-select-all", (e) => {
+            const checked = e.currentTarget.checked;
+            this._currentPageRows().forEach((row) => {
+                const id = this._rowId(row);
+                if (checked) {
+                    this.state.selected.add(id);
+                } else {
+                    this.state.selected.delete(id);
+                }
+            });
+            this._render();
+            this._fireSelectionChange();
+        });
+
+        // Pagination.
+        this.$pagination.on("click", "[data-page]", (e) => {
+            const action = $(e.currentTarget).data("page");
+            const totalPages = this._totalPages();
+            if (action === "prev") this.state.page = Math.max(1, this.state.page - 1);
+            else if (action === "next") this.state.page = Math.min(totalPages, this.state.page + 1);
+            this._render();
+        });
+
+        this.$pagination.on("change", ".jtable-page-size", (e) => {
+            this.state.pageSize = Number($(e.target).val());
+            this.state.page = 1;
+            this._render();
+        });
+    }
+
+    // -- Data loading --
+
+    reload() {
+        const o = this.options;
+
+        if (!o.url) {
+            this.state.rawData = Array.isArray(o.data) ? o.data : [];
+            this._render();
+            return;
+        }
+
+        this.state.loading = true;
+        this.state.error = false;
+        this._render();
+
+        $.ajax({ url: o.url, method: o.requestMethod, data: o.requestParams, dataType: "json" })
+            .done((response) => {
+                this.state.rawData = o.responseAdapter(response) || [];
+                this.state.loading = false;
+            })
+            .fail(() => {
+                this.state.rawData = [];
+                this.state.loading = false;
+                this.state.error = true;
+            })
+            .always(() => this._render());
+    }
+
+    setData(data) {
+        this.state.rawData = Array.isArray(data) ? data : [];
+        this.state.loading = false;
+        this.state.error = false;
+        this.state.page = 1;
+        this._render();
+    }
+
+    getData() {
+        return this.state.rawData;
+    }
+
+    // -- Filtering / sorting / pagination pipeline --
+
+    _matchesGlobalSearch(row) {
+        const term = this.state.search;
+        if (!term) {
+            return true;
+        }
+
+        return this.options.columns.some((col) => {
+            if (!col.key || col.searchable === false) {
+                return false;
+            }
+            const value = getValue(row, col.key);
+            return value != null && String(value).toLowerCase().includes(term);
+        });
+    }
+
+    _matchesColumnFilters(row) {
+        return Object.entries(this.state.columnFilters).every(([key, term]) => {
+            const value = getValue(row, key);
+            return value != null && String(value).toLowerCase().includes(term);
+        });
+    }
+
+    _matchesActiveFilters(row) {
+        return Object.entries(this.state.activeFilters).every(([key, value]) => String(getValue(row, key)) === value);
+    }
+
+    _filteredSorted() {
+        let rows = this.state.rawData.filter(
+            (row) => this._matchesGlobalSearch(row) && this._matchesColumnFilters(row) && this._matchesActiveFilters(row)
+        );
+
+        const { sortKey, sortDir } = this.state;
+        if (sortKey && sortDir) {
+            const column = this.options.columns.find((c) => c.key === sortKey);
+            const sortValue = column?.sortValue;
+            rows = rows.slice().sort((a, b) => {
+                const av = sortValue ? sortValue(a) : getValue(a, sortKey);
+                const bv = sortValue ? sortValue(b) : getValue(b, sortKey);
+                const result = compareValues(av, bv);
+                return sortDir === "asc" ? result : -result;
+            });
+        }
+
+        return rows;
+    }
+
+    _totalPages() {
+        if (this.options.pagination === false) {
+            return 1;
+        }
+        const total = this._filteredSorted().length;
+        return Math.max(1, Math.ceil(total / this.state.pageSize));
+    }
+
+    _currentPageRows() {
+        const filtered = this._filteredSorted();
+        if (this.options.pagination === false) {
+            return filtered;
+        }
+
+        const totalPages = Math.max(1, Math.ceil(filtered.length / this.state.pageSize));
+        this.state.page = Math.min(this.state.page, totalPages);
+        const start = (this.state.page - 1) * this.state.pageSize;
+        return filtered.slice(start, start + this.state.pageSize);
+    }
+
+    // -- Rendering rows / footer / sort indicators --
+
+    _render() {
+        this._renderSortIndicators();
+
+        if (this.state.loading) {
+            this._renderSkeleton();
+            this._renderFooter(0);
+            return;
+        }
+
+        if (this.state.error) {
+            this._renderMessageRow(this.options.errorText, "text-red-600");
+            this._renderFooter(0);
+            return;
+        }
+
+        const filtered = this._filteredSorted();
+        const pageRows = this._currentPageRows();
+
+        if (!filtered.length) {
+            this._renderMessageRow(this.options.emptyText);
+            this._renderFooter(0);
+            return;
+        }
+
+        this.$tbody.html(pageRows.map((row) => this._rowHtml(row)).join(""));
+        this._updateSelectionUi();
+        this._renderFooter(filtered.length);
+    }
+
+    _colSpan() {
+        return this.options.columns.length + (this.options.selectable === "multi" ? 1 : 0);
+    }
+
+    _renderMessageRow(text, extraClass = "") {
+        this.$tbody.html(
+            `<tr><td colspan="${this._colSpan()}" class="px-4 py-10 text-center text-body-sm text-on-surface-variant ${extraClass}">${escapeHtml(text)}</td></tr>`
+        );
+    }
+
+    _renderSkeleton() {
+        const cols = this._colSpan();
+        const rows = Array.from({ length: 5 })
+            .map(() => {
+                const cells = Array.from({ length: cols })
+                    .map(() => `<td class="px-3 py-3.5"><div class="h-3.5 w-full max-w-[10rem] animate-pulse rounded-full bg-surface-container"></div></td>`)
+                    .join("");
+                return `<tr>${cells}</tr>`;
+            })
+            .join("");
+        this.$tbody.html(rows);
+    }
+
+    _rowHtml(row) {
+        const o = this.options;
+        const id = this._rowId(row);
+        const isSelected = this.state.selected.has(id);
+        const extraClass = typeof o.rowClass === "function" ? o.rowClass(row) ?? "" : "";
+
+        let selectionClass = "border-l-transparent";
+        if (o.selectable === "single" && isSelected) {
+            selectionClass = "border-l-primary bg-primary/5";
+        }
+
+        let html = `<tr data-jtable-id="${escapeHtml(id)}" class="${o.selectable ? "cursor-pointer" : ""} border-l-2 ${selectionClass} transition-colors duration-150 hover:bg-surface-container/40 ${extraClass}">`;
+
+        if (o.selectable === "multi") {
+            html += `<td class="py-3 pl-4"><input type="checkbox" class="jtable-row-check jtable-no-row-click h-4 w-4 rounded border-outline-variant text-primary focus:ring-primary" data-jtable-id="${escapeHtml(id)}" ${isSelected ? "checked" : ""}></td>`;
+        }
+
+        o.columns.forEach((col, index) => {
+            const value = getValue(row, col.key);
+            const content = typeof col.render === "function" ? col.render(row, value) : escapeHtml(value ?? "—");
+            const padStart = index === 0 && o.selectable !== "multi" ? "pl-4" : "px-3";
+            const padEnd = index === o.columns.length - 1 ? "pr-4" : "";
+            const align = col.align === "right" ? "text-right" : col.align === "center" ? "text-center" : "";
+            html += `<td class="${padStart} ${padEnd} py-3 ${align} ${col.cellClass ?? ""}">${content}</td>`;
+        });
+
+        html += "</tr>";
+        return html;
+    }
+
+    _renderSortIndicators() {
+        this.$thead.find(".jtable-sort-btn").each((_, btn) => {
+            const $btn = $(btn);
+            const key = $btn.data("key");
+            const $icon = $btn.find(".jtable-sort-icon");
+            if (this.state.sortKey === key) {
+                $icon.html(this.state.sortDir === "asc" ? SORT_ASC_ICON : SORT_DESC_ICON);
+            } else {
+                $icon.html(SORT_NEUTRAL_ICON);
+            }
+        });
+    }
+
+    _updateSelectionUi() {
+        const o = this.options;
+        if (!o.selectable) {
+            return;
+        }
+
+        this.$tbody.find("tr[data-jtable-id]").each((_, tr) => {
+            const $row = $(tr);
+            const id = $row.attr("data-jtable-id");
+            const isSelected = this.state.selected.has(id);
+            if (o.selectable === "single") {
+                $row.toggleClass("border-l-primary bg-primary/5", isSelected).toggleClass("border-l-transparent", !isSelected);
+            }
+        });
+
+        if (o.selectable === "multi") {
+            const pageIds = this._currentPageRows().map((row) => this._rowId(row));
+            const allSelected = pageIds.length > 0 && pageIds.every((id) => this.state.selected.has(id));
+            const someSelected = pageIds.some((id) => this.state.selected.has(id));
+            const $selectAll = this.$thead.find(".jtable-select-all");
+            $selectAll.prop("checked", allSelected);
+            $selectAll.prop("indeterminate", !allSelected && someSelected);
+        }
+    }
+
+    _fireSelectionChange() {
+        if (typeof this.options.onSelectionChange === "function") {
+            this.options.onSelectionChange(this.getSelected(), this.state.selected);
+        }
+    }
+
+    // Selection state always keys on the String()-coerced id — DOM reads use
+    // .attr() (never jQuery's auto-coercing .data()) so a row's identity
+    // matches consistently whether ids are numeric or string-typed (UUIDs,
+    // zero-padded codes, etc.).
+    _rowId(row) {
+        return String(getValue(row, this.options.idField));
+    }
+
+    getSelected() {
+        return this.state.rawData.filter((row) => this.state.selected.has(this._rowId(row)));
+    }
+
+    clearSelection() {
+        this.state.selected = new Set();
+        this._render();
+        this._fireSelectionChange();
+    }
+
+    _renderFooter(count) {
+        this.$summary.text(this.options.summaryTemplate.replace(":count", count));
+
+        if (this.options.pagination === false) {
+            this.$pagination.empty();
+            return;
+        }
+
+        const totalPages = this._totalPages();
+        const pageText = this.options.pageTemplate.replace(":page", this.state.page).replace(":total", totalPages);
+
+        let html = "";
+        if (this.options.pageSizes) {
+            html += `
+                <select class="jtable-page-size mr-2 rounded-lg border-0 bg-surface-container/60 px-2 py-1.5 text-body-sm text-on-surface ring-1 ring-inset ring-outline-variant/60 focus:outline-none focus:ring-2 focus:ring-primary">
+                    ${this.options.pageSizes.map((size) => `<option value="${size}" ${size === this.state.pageSize ? "selected" : ""}>${size}</option>`).join("")}
+                </select>
+            `;
+        }
+
+        html += `
+            <button type="button" data-page="prev" class="flex h-8 w-8 items-center justify-center rounded-xl border border-outline-variant text-on-surface-variant transition hover:bg-surface-container disabled:cursor-not-allowed disabled:opacity-40" aria-label="${escapeHtml(this.options.prevLabel)}" ${this.state.page <= 1 ? "disabled" : ""}>
+                ${CHEVRON_LEFT_ICON}
+            </button>
+            <span class="px-2 text-body-sm font-medium text-on-surface">${escapeHtml(pageText)}</span>
+            <button type="button" data-page="next" class="flex h-8 w-8 items-center justify-center rounded-xl border border-outline-variant text-on-surface-variant transition hover:bg-surface-container disabled:cursor-not-allowed disabled:opacity-40" aria-label="${escapeHtml(this.options.nextLabel)}" ${this.state.page >= totalPages ? "disabled" : ""}>
+                ${CHEVRON_RIGHT_ICON}
+            </button>
+        `;
+
+        this.$pagination.html(html);
+    }
+
+    destroy() {
+        this.$el.off();
+        this.$el.removeData("jtable").empty().removeClass("jtable");
+    }
+}
+
+$.fn.jtable = function jtablePlugin(optionsOrMethod, ...args) {
+    if (typeof optionsOrMethod === "string") {
+        let result;
+        this.each(function () {
+            const instance = $(this).data("jtable");
+            if (instance && typeof instance[optionsOrMethod] === "function") {
+                result = instance[optionsOrMethod](...args);
+            }
+        });
+        return result !== undefined ? result : this;
+    }
+
+    return this.each(function () {
+        if ($(this).data("jtable")) {
+            return;
+        }
+        $(this).data("jtable", new JTable(this, optionsOrMethod));
+    });
+};
+
+return $.fn.jtable;
+});