@phillipsharring/graspr-framework 0.1.0

package/src/core/table-sort.js

@@ -0,0 +1,111 @@
+// ---------------------------
+// Table column sorting (delegated)
+// ---------------------------
+// Clickable <th data-sort="column"> headers that toggle asc/desc sorting.
+// Sort state is persisted in URL query params (?sort=col&dir=asc).
+// Fully self-registering — import for side effects only.
+// Also exports initTableSort() for use in DOMContentLoaded/afterSwap orchestration.
+
+import htmx from '../lib/htmx.js';
+import { setUrlParam, getUrlParam, mergeHxVals } from './navigation.js';
+
+/**
+ * Apply sort indicator classes to th[data-sort] headers based on current sort state.
+ * @param {Document|HTMLElement} root
+ */
+export function initTableSort(root = document) {
+    const sortCol = getUrlParam('sort');
+    const sortDir = getUrlParam('dir');
+
+    root.querySelectorAll('th[data-sort]').forEach((th) => {
+        th.classList.remove('sort-asc', 'sort-desc');
+        if (sortCol && th.dataset.sort === sortCol) {
+            th.classList.add(sortDir === 'desc' ? 'sort-desc' : 'sort-asc');
+        }
+    });
+
+    // Set hx-vals on sortable tbody elements so the initial API request includes sort params
+    if (sortCol) {
+        root.querySelectorAll('th[data-sort]').forEach((th) => {
+            const tbody = th.closest('table')?.querySelector('tbody');
+            if (tbody instanceof HTMLElement && !tbody.dataset.sortInit) {
+                mergeHxVals(tbody, { sort: sortCol, dir: sortDir || 'asc' });
+                tbody.dataset.sortInit = '1';
+            }
+        });
+    }
+}
+
+// Delegated click handler for sort headers
+document.addEventListener('click', (e) => {
+    const th = e.target.closest('th[data-sort]');
+    if (!th) return;
+
+    const column = th.dataset.sort;
+    const tbody = th.closest('table')?.querySelector('tbody');
+    if (!(tbody instanceof HTMLElement)) return;
+
+    // Determine new direction: toggle if same column, else default to asc
+    const currentSort = getUrlParam('sort');
+    const currentDir = getUrlParam('dir');
+    let newDir = 'asc';
+    if (column === currentSort) {
+        newDir = currentDir === 'asc' ? 'desc' : 'asc';
+    }
+
+    // Update sort indicator classes on all sibling headers
+    const thead = th.closest('thead');
+    if (thead) {
+        thead.querySelectorAll('th[data-sort]').forEach((sibling) => {
+            sibling.classList.remove('sort-asc', 'sort-desc');
+        });
+    }
+    th.classList.add(newDir === 'desc' ? 'sort-desc' : 'sort-asc');
+
+    // Reset pagination to page 1
+    const pageParam = tbody.getAttribute('data-pagination-param') || 'page';
+    mergeHxVals(tbody, { sort: column, dir: newDir, [pageParam]: 1 });
+    setUrlParam(pageParam, null);
+
+    // Update URL for bookmarkability
+    setUrlParam('sort', column);
+    setUrlParam('dir', newDir);
+
+    // Trigger refresh
+    htmx.process(tbody);
+    if (typeof htmx?.trigger === 'function') {
+        htmx.trigger(tbody, 'refresh');
+    }
+});
+
+// Re-sync sort state on back/forward navigation
+window.addEventListener('popstate', () => {
+    const sortCol = getUrlParam('sort');
+    const sortDir = getUrlParam('dir');
+
+    document.querySelectorAll('th[data-sort]').forEach((th) => {
+        th.classList.remove('sort-asc', 'sort-desc');
+        if (sortCol && th.dataset.sort === sortCol) {
+            th.classList.add(sortDir === 'desc' ? 'sort-desc' : 'sort-asc');
+        }
+    });
+
+    // Update hx-vals on tbody elements
+    document.querySelectorAll('th[data-sort]').forEach((th) => {
+        const tbody = th.closest('table')?.querySelector('tbody');
+        if (tbody instanceof HTMLElement) {
+            if (sortCol) {
+                mergeHxVals(tbody, { sort: sortCol, dir: sortDir || 'asc' });
+            } else {
+                // Remove sort params from hx-vals when URL has none
+                let existing = {};
+                try {
+                    existing = JSON.parse(tbody.getAttribute('hx-vals') || '{}');
+                } catch { /* ignore */ }
+                delete existing.sort;
+                delete existing.dir;
+                tbody.setAttribute('hx-vals', JSON.stringify(existing));
+            }
+        }
+    });
+});

package/src/fetch-client.js

@@ -0,0 +1,46 @@
+// ---------------------------
+// API Client
+// ---------------------------
+// Convenience wrapper around fetch for /api/ calls.
+// Auto-handles CSRF headers, JSON content type, and body serialization.
+// New code should use this; existing inline fetch() calls are protected
+// by the global interceptor in core/csrf.js.
+
+import { getCsrfToken, setCsrfToken } from './core/csrf.js';
+
+const CSRF_HEADER = 'X-CSRF-Token';
+
+/**
+ * Fetch wrapper for API calls.
+ * @param {string} url - The API URL (e.g. '/api/users')
+ * @param {RequestInit & { body?: object | string }} [options={}]
+ * @returns {Promise<Response>}
+ */
+export function apiFetch(url, options = {}) {
+    const headers = new Headers(options.headers || {});
+    const token = getCsrfToken();
+
+    if (token) {
+        headers.set(CSRF_HEADER, token);
+    }
+
+    headers.set('Accept', 'application/json');
+
+    const method = (options.method || 'GET').toUpperCase();
+
+    if (method !== 'GET' && method !== 'HEAD') {
+        if (!headers.has('Content-Type')) {
+            headers.set('Content-Type', 'application/json');
+        }
+
+        if (options.body && typeof options.body === 'object' && !(options.body instanceof FormData)) {
+            options = { ...options, body: JSON.stringify(options.body) };
+        }
+    }
+
+    return fetch(url, { ...options, headers, credentials: 'same-origin' }).then(response => {
+        const newToken = response.headers.get(CSRF_HEADER);
+        if (newToken) setCsrfToken(newToken);
+        return response;
+    });
+}

package/src/helpers/debounce.js

@@ -0,0 +1,48 @@
+/**
+ * Creates a debounced version of a function.
+ * @param {Function} fn - The function to debounce
+ * @param {number} delay - Delay in milliseconds
+ * @returns {Function} - Debounced function with a .cancel() method
+ */
+export function debounce(fn, delay) {
+    let timeoutId = null;
+
+    const debounced = (...args) => {
+        if (timeoutId !== null) {
+            clearTimeout(timeoutId);
+        }
+        timeoutId = setTimeout(() => {
+            timeoutId = null;
+            fn(...args);
+        }, delay);
+    };
+
+    debounced.cancel = () => {
+        if (timeoutId !== null) {
+            clearTimeout(timeoutId);
+            timeoutId = null;
+        }
+    };
+
+    return debounced;
+}
+
+/**
+ * Scrub user input for safe use in search queries.
+ * Removes potentially dangerous characters while preserving search functionality.
+ * @param {string} input - Raw user input
+ * @returns {string} - Scrubbed input
+ */
+export function scrubSearchInput(input) {
+    if (typeof input !== 'string') return '';
+
+    return input
+        // Remove HTML/script injection characters
+        .replace(/[<>]/g, '')
+        // Remove potential SQL injection characters (belt-and-suspenders with BE)
+        .replace(/[;'"\\]/g, '')
+        // Collapse multiple spaces into one
+        .replace(/\s+/g, ' ')
+        // Trim whitespace
+        .trim();
+}

package/src/helpers/escape-html.js

@@ -0,0 +1,10 @@
+/**
+ * Escape a string for safe insertion into HTML.
+ * @param {string} str
+ * @returns {string}
+ */
+export function escapeHtml(str) {
+    var div = document.createElement('div');
+    div.textContent = str;
+    return div.innerHTML;
+}

package/src/helpers/handlebars-helpers.js

@@ -0,0 +1,171 @@
+/**
+ * Register generic/reusable Handlebars helpers.
+ * @param {typeof import('handlebars')} Handlebars
+ */
+export function registerHandlebarsHelpers(Handlebars) {
+    // ─── Partials ───
+
+    Handlebars.registerPartial('formButtons', `<div class="flex justify-end gap-3 pt-2">
+    <button type="button" class="border rounded px-3 py-2 hover:bg-slate-50" data-modal-close>
+        Cancel
+    </button>
+    <button type="submit" class="rounded px-3 py-2 bg-slate-900 text-white hover:bg-slate-800">
+        {{label}}
+    </button>
+</div>`);
+
+    Handlebars.registerPartial('copyIdBtn', `<button
+        type="button"
+        class="copy-id-btn p-1 rounded hover:bg-slate-200 text-slate-400 hover:text-slate-600"
+        data-copy-value="{{id}}"
+        title="Copy ID"
+    >
+        <svg class="copy-icon w-3.5 h-3.5" fill="none" stroke="currentColor" stroke-width="2" viewBox="0 0 24 24">
+            <rect x="9" y="9" width="13" height="13" rx="2" ry="2"></rect>
+            <path d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1"></path>
+        </svg>
+        <svg class="check-icon w-3.5 h-3.5 hidden text-green-600" fill="none" stroke="currentColor" stroke-width="2" viewBox="0 0 24 24">
+            <polyline points="20 6 9 17 4 12"></polyline>
+        </svg>
+    </button>`);
+
+    // ─── Utilities ───
+
+    // Parse a timestamp as UTC. MySQL datetimes arrive as "2026-03-11 14:30:00"
+    // with no timezone indicator — JS Date parsing is ambiguous without one.
+    // This normalizes to ISO 8601 with Z suffix so it's unambiguously UTC.
+    function parseUtcDate(value) {
+        if (value === null || value === undefined) return null;
+        const s = String(value).trim();
+        if (!s) return null;
+        // If it already has a timezone indicator (Z, +, -) leave it alone,
+        // otherwise treat as UTC by appending Z after converting space to T
+        const normalized = /[Z+\-]\d{0,4}:?\d{0,2}$/.test(s) ? s : s.replace(' ', 'T') + 'Z';
+        const d = new Date(normalized);
+        return Number.isNaN(d.getTime()) ? null : d;
+    }
+
+    // ─── Helpers ───
+
+    // Equality comparison helper
+    Handlebars.registerHelper('eq', (a, b) => a === b);
+
+    // Inequality comparison helper
+    Handlebars.registerHelper('neq', (a, b) => a !== b);
+
+    // Logical AND helper
+    Handlebars.registerHelper('and', function(...args) {
+        args.pop(); // Remove Handlebars options object
+        return args.every(Boolean);
+    });
+
+    // Logical OR helper
+    Handlebars.registerHelper('or', function(...args) {
+        args.pop(); // Remove Handlebars options object
+        return args.some(Boolean);
+    });
+
+    Handlebars.registerHelper('notin', function(value, ...rest) {
+        const options = rest.pop(); // Remove Handlebars options object
+        let listArgs = rest;
+
+        // If a single array was provided from context, use it
+        if (listArgs.length === 1 && Array.isArray(listArgs[0])) {
+            listArgs = listArgs[0];
+        }
+
+        if (!listArgs || !Array.isArray(listArgs)) {
+            return true; // treat missing list as "not in"
+        }
+
+        return listArgs.indexOf(value) === -1;
+    });
+
+    // Truncate a string to a max length, adding ellipsis if truncated.
+    Handlebars.registerHelper('truncate', (value, length) => {
+        if (value === null || value === undefined) return '';
+        const s = String(value);
+        if (s.length <= length) return s;
+        return s.slice(0, length) + '…';
+    });
+
+    // Make a string all upper case
+    Handlebars.registerHelper('upper', (value) => {
+        if (value === null || value === undefined) return '';
+        const s = String(value);
+        return s.toUpperCase();
+    });
+
+    // Convert snake_case to human-readable text: "on_pack_open" → "on pack open"
+    Handlebars.registerHelper('humanize', (value) => {
+        if (value === null || value === undefined) return '';
+        return String(value).replace(/_/g, ' ');
+    });
+
+    // Convert snake_case to Title Case: "level_up" → "Level Up"
+    Handlebars.registerHelper('titleHumanize', (value) => {
+        if (value === null || value === undefined) return '';
+        return String(value).replace(/_/g, ' ').replace(/\b\w/g, c => c.toUpperCase());
+    });
+
+    // Tree indent indicator — shows depth via left margin + ↳ arrow.
+    // sort_key format: "00" (root), "00.01" (depth 1), "00.01.ff" (depth 2), etc.
+    Handlebars.registerHelper('treeIndent', (sortKey) => {
+        if (!sortKey) return '';
+        const depth = (String(sortKey).match(/\./g) || []).length;
+        if (depth === 0) return '';
+        const ml = depth * 16;
+        return new Handlebars.SafeString(
+            `<span class="text-slate-300 inline-block" style="margin-left:${ml}px">↳</span> `
+        );
+    });
+
+    // Serialize a value to a JSON string (safe for embedding in HTML attributes).
+    Handlebars.registerHelper('json', (value) => {
+        if (value === null || value === undefined) return 'null';
+        return JSON.stringify(value);
+    });
+
+    // Relative time helper: "3 minutes ago", "2 days ago", etc.
+    Handlebars.registerHelper('timeAgo', (value) => {
+        const d = parseUtcDate(value);
+        if (!d) return '';
+
+        const seconds = Math.floor((Date.now() - d.getTime()) / 1000);
+        if (seconds < 0) return 'just now';
+
+        const intervals = [
+            [60, 'second'],
+            [60, 'minute'],
+            [24, 'hour'],
+            [30, 'day'],
+            [12, 'month'],
+            [Infinity, 'year'],
+        ];
+
+        let remaining = seconds;
+        for (const [divisor, unit] of intervals) {
+            if (remaining < divisor) {
+                if (unit === 'second' && remaining < 10) return 'just now';
+                const n = Math.floor(remaining);
+                return n + ' ' + unit + (n !== 1 ? 's' : '') + ' ago';
+            }
+            remaining /= divisor;
+        }
+        return '';
+    });
+
+    // Format a UTC timestamp to the user's local timezone as a readable datetime string.
+    Handlebars.registerHelper('formatDateTime', (value) => {
+        const d = parseUtcDate(value);
+        if (!d) return '';
+
+        return new Intl.DateTimeFormat(undefined, {
+            year: 'numeric',
+            month: 'short',
+            day: '2-digit',
+            hour: '2-digit',
+            minute: '2-digit',
+        }).format(d);
+    });
+}

package/src/helpers/index.js

@@ -0,0 +1,6 @@
+export { registerHandlebarsHelpers } from './handlebars-helpers.js';
+export { debounce, scrubSearchInput } from './debounce.js';
+export { initCopyIdHandler } from './utils.js';
+export { escapeHtml } from './escape-html.js';
+export { populateSelect } from './populate-select.js';
+export { getRouteParams } from './route-params.js';

package/src/helpers/populate-select.js

@@ -0,0 +1,21 @@
+/**
+ * Populate a <select> from a JSON API endpoint.
+ * Fetches { data: [{ id, name }, ...] } and appends <option> elements.
+ * @param {HTMLSelectElement} select
+ * @param {string} endpoint
+ * @param {string} [selectedId]
+ */
+export function populateSelect(select, endpoint, selectedId) {
+    fetch(endpoint)
+        .then(function(r) { return r.json(); })
+        .then(function(json) {
+            if (json.status !== 'success' || !json.data) return;
+            json.data.forEach(function(item) {
+                var opt = document.createElement('option');
+                opt.value = item.id;
+                opt.textContent = item.name;
+                if (selectedId && item.id === selectedId) opt.selected = true;
+                select.appendChild(opt);
+            });
+        });
+}

package/src/helpers/route-params.js

@@ -0,0 +1,50 @@
+import { normalizePath } from '../core/navigation.js';
+
+/**
+ * Extract route parameters from the current URL based on a route pattern.
+ * @param {string} pattern - Route pattern with [param] placeholders (e.g., '/series/[seriesId]/collections/')
+ * @param {string} [url] - URL to extract from (defaults to current pathname)
+ * @returns {Object} - Object mapping parameter names to values
+ *
+ * @example
+ * // On page /series/abc123/collections/
+ * getRouteParams('/series/[seriesId]/collections/')
+ * // Returns: { seriesId: 'abc123' }
+ *
+ * @example
+ * // Multiple params
+ * getRouteParams('/series/[seriesId]/collections/[collectionId]/')
+ * // On /series/abc123/collections/xyz789/
+ * // Returns: { seriesId: 'abc123', collectionId: 'xyz789' }
+ */
+export function getRouteParams(pattern, url = window.location.pathname) {
+    const params = {};
+
+    const urlNorm = normalizePath(url);
+    const patternNorm = normalizePath(pattern);
+
+    const urlSegments = urlNorm.replace(/^\/|\/$/g, '').split('/').filter(Boolean);
+    const patternSegments = patternNorm.replace(/^\/|\/$/g, '').split('/').filter(Boolean);
+
+    if (urlSegments.length !== patternSegments.length) {
+        return params; // Pattern doesn't match, return empty object
+    }
+
+    for (let i = 0; i < patternSegments.length; i++) {
+        const urlSeg = urlSegments[i];
+        const patternSeg = patternSegments[i];
+
+        // Check if this is a parameter segment
+        if (patternSeg.startsWith('[') && patternSeg.endsWith(']')) {
+            const paramName = patternSeg.slice(1, -1); // Remove [ and ]
+            params[paramName] = urlSeg;
+        } else {
+            // Static segment should match exactly
+            if (patternSeg !== urlSeg) {
+                return {}; // Mismatch, return empty object
+            }
+        }
+    }
+
+    return params;
+}

package/src/helpers/utils.js

@@ -0,0 +1,27 @@
+/**
+ * Initialize copy-to-clipboard button handler (delegated).
+ * Buttons should have class `.copy-id-btn` and `data-copy-value` attribute.
+ * Icons inside: `.copy-icon` (clipboard) and `.check-icon` (checkmark, hidden).
+ */
+export function initCopyIdHandler() {
+    document.addEventListener('click', (e) => {
+        const btn = e.target.closest('.copy-id-btn');
+        if (!btn) return;
+
+        const value = btn.dataset.copyValue;
+        if (!value) return;
+
+        navigator.clipboard.writeText(value).then(() => {
+            const copyIcon = btn.querySelector('.copy-icon');
+            const checkIcon = btn.querySelector('.check-icon');
+            if (copyIcon && checkIcon) {
+                copyIcon.classList.add('hidden');
+                checkIcon.classList.remove('hidden');
+                setTimeout(() => {
+                    copyIcon.classList.remove('hidden');
+                    checkIcon.classList.add('hidden');
+                }, 1500);
+            }
+        });
+    });
+}

package/src/index.js

@@ -0,0 +1,73 @@
+// ---------------------------
+// Graspr Framework — barrel export
+// ---------------------------
+// Public API for apps to import from '@phillipsharring/graspr-framework'.
+// Side-effect modules (csrf, boosted-nav, auth-state, forms, search, sortable)
+// are NOT imported here — use '@phillipsharring/graspr-framework/init' for those.
+
+// Auth
+export { checkAuth, getAuthData, refreshAuthData } from './auth.js';
+
+// API client
+export { apiFetch } from './fetch-client.js';
+
+// Core — pagination & table sort (init functions)
+export { initPagination } from './core/pagination.js';
+export { initTableSort } from './core/table-sort.js';
+
+// Core — auth-state (configurable)
+export { registerAdminPermissionPrefixes } from './core/auth-state.js';
+
+// Core — navigation utilities
+export {
+    normalizePath,
+    setActiveNav,
+    setUrlParam,
+    getUrlParam,
+    getUrlParamInt,
+    mergeHxVals,
+} from './core/navigation.js';
+
+// Core — CSRF token access
+export { getCsrfToken, setCsrfToken } from './core/csrf.js';
+
+// UI — toast
+export {
+    GrasprToast,
+    registerToastHelpers,
+    initToastEventHandlers,
+    openToast,
+    closeToast,
+} from './ui/toast.js';
+
+// UI — modal
+export {
+    setOnModalCloseWithConfirm,
+    getGlobalModal,
+    getGlobalModalDialog,
+    getGlobalModalHeader,
+    getGlobalModalCloseButton,
+    isGlobalModalOpen,
+    openGlobalModal,
+    closeGlobalModal,
+} from './ui/modal.js';
+
+// UI — modal form
+export { openFormModal } from './ui/modal-form.js';
+
+// UI — confirm dialog
+export { GrasprConfirm } from './ui/confirm-dialog.js';
+
+// UI — click burst
+export { createBurst, attachClickBurst, initClickBurst } from './ui/click-burst.js';
+
+// UI — typeahead
+export { createTypeahead } from './ui/typeahead.js';
+
+// Helpers
+export { registerHandlebarsHelpers } from './helpers/handlebars-helpers.js';
+export { initCopyIdHandler } from './helpers/utils.js';
+export { escapeHtml } from './helpers/escape-html.js';
+export { populateSelect } from './helpers/populate-select.js';
+export { getRouteParams } from './helpers/route-params.js';
+export { debounce, scrubSearchInput } from './helpers/debounce.js';

package/src/init.js

@@ -0,0 +1,13 @@
+// ---------------------------
+// Graspr Framework initialization (side effects)
+// ---------------------------
+// Import this module to register all framework event listeners,
+// CSRF interceptors, boosted-nav handlers, form error handling, etc.
+// Order matters: csrf must be before auth-state.
+
+import './core/csrf.js';
+import './core/boosted-nav.js';
+import './core/auth-state.js';
+import './core/forms.js';
+import './core/search.js';
+import './core/sortable.js';

package/src/lib/client-side-templates.js

@@ -0,0 +1,75 @@
+import htmx from './htmx.js';
+import Handlebars from 'handlebars';
+
+htmx.defineExtension('client-side-templates', {
+    transformResponse(text, xhr, elt) {
+        const tplHost = htmx.closest(elt, '[handlebars-template], [handlebars-array-template]');
+        if (!tplHost) return text;
+
+        // Boosted <a> links inside a template-attributed container inherit the
+        // attribute, but their responses are full HTML pages — not JSON.
+        // Skip transformation so the beforeSwap handler can fix the target.
+        if (elt instanceof HTMLAnchorElement && !elt.hasAttribute('hx-get') && !elt.hasAttribute('hx-post')) {
+            return text;
+        }
+
+        const isArray = tplHost.hasAttribute('handlebars-array-template');
+        const templateId = tplHost.getAttribute(isArray ? 'handlebars-array-template' : 'handlebars-template');
+
+        const templateEl = htmx.find('#' + templateId);
+        if (!templateEl) throw new Error('Unknown handlebars template: ' + templateId);
+
+        let data;
+        try {
+            data = JSON.parse(text);
+        } catch {
+            throw new Error('Response was not valid JSON for handlebars template: ' + templateId);
+        }
+
+        // innerHTML escapes ">" to "&gt;" in text nodes (per the HTML serialization
+        // spec), which mangles Handlebars partial calls: {{> partial}} → {{&gt; partial}}.
+        // Reverse this specific escaping before compiling.
+        const render = Handlebars.compile(templateEl.innerHTML.replaceAll('{{&gt;', '{{>'));
+
+        // Object templates: spread `data` into the top level so templates can use
+        // both {{message}}/{{status}} (for toasts) and {{name}}/{{id}} (for entities).
+        // Envelope props (status, message) overlay record props — toasts need
+        // {{status}} = "success"/"error". Entity templates that collide with envelope
+        // keys (e.g. a `status` column) should use {{data.status}} instead.
+        if (!isArray) {
+            const hasDataObject = data && typeof data === 'object' && 'data' in data &&
+                typeof data.data === 'object' && !Array.isArray(data.data);
+            const renderData = hasDataObject
+                ? { ...data.data, ...data, data: data.data }  // spread data props, then overlay top-level (status/message win)
+                : data;
+            return render(renderData);
+        }
+
+        // Array templates: normalize to { data: Array, meta?: Object }
+        // Supports both raw arrays and { data: [...], meta: {...} } responses
+        const isArrayResponse = Array.isArray(data);
+        const rows = isArrayResponse ? data : Array.isArray(data?.data) ? data.data : [];
+        const meta = !isArrayResponse && data && typeof data === 'object' ? data.meta ?? null : null;
+
+        // Stash table sort meta on the element for the table-sort module
+        if (meta?.table_sorts) {
+            tplHost.dataset.tableSorts = JSON.stringify(meta.table_sorts);
+        }
+
+        // Optional: render pagination from meta as a side effect
+        const pagTargetSel = tplHost.getAttribute('data-pagination-target');
+        const pagTemplateId = tplHost.getAttribute('data-pagination-template');
+        const pagSource = tplHost.getAttribute('data-pagination-source') || '';
+        const pagParam = tplHost.getAttribute('data-pagination-param') || 'page';
+        if (pagTargetSel && pagTemplateId) {
+            const targetEl = document.querySelector(pagTargetSel);
+            const tpl = document.getElementById(pagTemplateId);
+            if (targetEl instanceof HTMLElement && tpl instanceof HTMLTemplateElement) {
+                const pagRender = Handlebars.compile(tpl.innerHTML.replaceAll('{{&gt;', '{{>'));
+                targetEl.innerHTML = pagRender({ meta, source: pagSource, param: pagParam });
+            }
+        }
+
+        return render({ data: rows, meta });
+    },
+});

package/src/lib/htmx.js

@@ -0,0 +1,7 @@
+import htmx from 'htmx.org';
+
+// Ensure there's exactly one shared HTMX instance, available both as an ES module
+// import and as a global for any inline scripts / extensions that expect `window.htmx`.
+window.htmx = window.htmx || htmx;
+
+export default window.htmx;