@phillipsharring/graspr-framework 0.1.0

package/src/core/forms.js

@@ -0,0 +1,290 @@
+// ---------------------------
+// Form error handling + modal form lifecycle
+// ---------------------------
+// Manages inline form errors, error response interception, form submission
+// tracking, modal auto-open on content swap, and modal close + refresh on success.
+// Fully self-registering — import for side effects only.
+
+import htmx from '../lib/htmx.js';
+import { GrasprToast } from '../ui/toast.js';
+import {
+    openGlobalModal,
+    closeGlobalModal,
+    isGlobalModalOpen,
+} from '../ui/index.js';
+
+// ---------------------------
+// Form inline error handling
+// ---------------------------
+
+/**
+ * Show inline errors on form fields.
+ * @param {HTMLFormElement} form - The form element
+ * @param {Object} errors - Object mapping field names to error messages
+ * @param {string} generalMessage - General error message for the form
+ */
+function showFormErrors(form, errors, generalMessage) {
+    if (!(form instanceof HTMLFormElement)) {
+        return;
+    }
+
+    // Show field-level errors
+    for (const [fieldName, errorMessage] of Object.entries(errors || {})) {
+        const input = form.querySelector(`[name="${fieldName}"]`);
+        if (!input) continue;
+
+        // Add error class to input
+        input.classList.add('field-error');
+
+        // Find or create error text element
+        let errorText = input.parentElement?.querySelector('.field-error-text');
+        if (!errorText) {
+            errorText = document.createElement('div');
+            errorText.className = 'field-error-text hidden';
+            input.parentElement?.appendChild(errorText);
+        }
+
+        errorText.textContent = errorMessage;
+        errorText.classList.remove('hidden');
+    }
+
+    // Show general error message at top of form
+    if (generalMessage) {
+        let errorBanner = form.querySelector('.form-error-banner');
+        if (!errorBanner) {
+            errorBanner = document.createElement('div');
+            errorBanner.className = 'form-error-banner';
+            form.insertBefore(errorBanner, form.firstChild);
+        }
+        errorBanner.textContent = generalMessage;
+    }
+}
+
+/**
+ * Clear all inline errors from a form.
+ * @param {HTMLFormElement} form - The form element
+ */
+function clearFormErrors(form) {
+    if (!(form instanceof HTMLFormElement)) return;
+
+    // Remove error classes from inputs
+    form.querySelectorAll('.field-error').forEach((input) => {
+        input.classList.remove('field-error');
+    });
+
+    // Hide error text elements
+    form.querySelectorAll('.field-error-text').forEach((errorText) => {
+        errorText.classList.add('hidden');
+        errorText.textContent = '';
+    });
+
+    // Remove error banner
+    form.querySelectorAll('.form-error-banner').forEach((banner) => {
+        banner.remove();
+    });
+}
+
+/**
+ * Clear error state for a specific field.
+ * @param {HTMLElement} input - The input element
+ */
+function clearFieldError(input) {
+    if (!(input instanceof HTMLElement)) return;
+
+    input.classList.remove('field-error');
+
+    const errorText = input.parentElement?.querySelector('.field-error-text');
+    if (errorText) {
+        errorText.classList.add('hidden');
+        errorText.textContent = '';
+    }
+}
+
+// Clear field errors when user interacts with the field
+document.addEventListener('focus', (e) => {
+    const input = e.target;
+    if (input instanceof HTMLElement && input.classList.contains('field-error')) {
+        clearFieldError(input);
+    }
+}, true);
+
+// ---------------------------
+// Form submission tracking
+// ---------------------------
+
+// Track the currently submitting form for error handling
+let currentSubmittingForm = null;
+
+document.body.addEventListener('htmx:beforeRequest', (e) => {
+    const elt = e.detail?.elt;
+    if (elt instanceof HTMLFormElement) {
+        currentSubmittingForm = elt;
+    } else if (elt instanceof Element) {
+        currentSubmittingForm = elt.closest('form');
+    }
+});
+
+// ---------------------------
+// Error response interception
+// ---------------------------
+
+// Intercept HTMX responses BEFORE swap to handle form errors (inline or toast)
+document.body.addEventListener('htmx:beforeSwap', (e) => {
+    const detail = e.detail || {};
+    const xhr = detail.xhr;
+    const elt = detail.elt;
+
+    // Try to parse JSON response
+    let responseData = null;
+    try {
+        const responseText = xhr?.responseText;
+        if (responseText) {
+            responseData = JSON.parse(responseText);
+        }
+    } catch {
+        // Not JSON or parsing failed
+        return;
+    }
+
+    // Check if this is an error response
+    const status = responseData?.status;
+    const message = responseData?.message;
+
+    if (status !== 'error' || !message) {
+        return; // Not an error response, let HTMX handle normally
+    }
+
+    // Find the form that triggered this request
+    // Use the tracked form first, then try to detect from the element
+    let form = currentSubmittingForm;
+
+    if (!form && elt instanceof HTMLFormElement) {
+        form = elt;
+    } else if (!form && elt instanceof Element) {
+        form = elt.closest('form');
+    }
+
+    // If elt is not inside a form (e.g., it's the toast target), look for forms in the modal
+    if (!form && isGlobalModalOpen()) {
+        form = document.querySelector('#global-modal-content form[data-form-errors="inline"]');
+    }
+
+    const useInlineErrors = form?.getAttribute('data-form-errors') === 'inline';
+    const hasFieldErrors = responseData.errors && typeof responseData.errors === 'object' && Object.keys(responseData.errors).length > 0;
+
+    // Handle error responses
+    if (useInlineErrors && hasFieldErrors) {
+        // Show inline errors on the form - prevent the swap to toast
+        detail.shouldSwap = false;
+        clearFormErrors(form);
+        showFormErrors(form, responseData.errors, message);
+    } else if (useInlineErrors && !hasFieldErrors) {
+        // Invariant/form-level errors on inline-error forms: show in form, not toast
+        detail.shouldSwap = false;
+        clearFormErrors(form);
+        showFormErrors(form, {}, message);
+    } else {
+        // Forms without inline errors: show toast
+        // Allow the swap if targeting toast, otherwise show manually
+        if (detail.target && detail.target.id === 'global-toast-content') {
+            detail.shouldSwap = true; // Allow HTMX to swap the error response into toast
+        } else {
+            detail.shouldSwap = false;
+            GrasprToast?.show?.({ message, status: 'error' });
+        }
+    }
+});
+
+// ---------------------------
+// Modal auto-open + close/refresh on success
+// ---------------------------
+
+// If an HTMX request swaps content into the modal container, auto-open it.
+document.body.addEventListener('htmx:afterSwap', (e) => {
+    const target = e.detail?.target;
+    if (target && target.id === 'global-modal-content') {
+        openGlobalModal();
+    }
+});
+
+// If an HTMX request is triggered from inside the global modal and succeeds,
+// automatically dismiss the modal.
+//
+// Example: POST /api/series from the "Create series" modal should close the modal on success.
+document.body.addEventListener('htmx:afterRequest', (e) => {
+    // Clear the tracked submitting form
+    currentSubmittingForm = null;
+
+    const detail = e.detail || {};
+    const xhr = detail.xhr;
+    const status = typeof xhr?.status === 'number' ? xhr.status : null;
+    const ok = status !== null ? status >= 200 && status < 300 : !!detail.successful;
+    if (!ok) return;
+    if (!isGlobalModalOpen()) return;
+
+    const elt = detail.elt;
+    if (!(elt instanceof Element)) return;
+
+    // Only close if the request originated inside the modal (not just targeting it).
+    if (elt.closest('#global-modal')) {
+        // Check for success redirect - first from response meta, then from data attribute
+        const form = elt.closest('form');
+        let successRedirect = form?.getAttribute('data-success-redirect');
+
+        // Try to get redirect from response meta
+        try {
+            const responseData = JSON.parse(xhr?.responseText || '{}');
+            if (responseData.meta?.redirect) {
+                successRedirect = responseData.meta.redirect;
+            }
+        } catch {
+            // Ignore parse errors
+        }
+
+        if (successRedirect) {
+            // If already on a real page (not landing/login), reload in place —
+            // auth-state.js handles permission checks after the page loads.
+            const currentPath = window.location.pathname;
+            if (currentPath !== '/' && !currentPath.startsWith('/login') && !currentPath.startsWith('/signup')) {
+                window.location.reload();
+            } else {
+                window.location.href = successRedirect;
+            }
+            return;
+        }
+
+        closeGlobalModal();
+
+        // Clear any form errors on successful submit
+        if (form instanceof HTMLFormElement) {
+            clearFormErrors(form);
+        }
+
+        // Optional: refresh something after a successful modal submit.
+        // Two patterns supported:
+        //
+        // 1. data-refresh-target="#some-element" — fires HTMX "refresh" trigger
+        //    on the element (used by list pages with hx-trigger="... refresh").
+        //
+        // 2. data-refresh-event="event-name" — dispatches a custom event on
+        //    document.body (used by detail pages where multiple elements listen
+        //    via hx-trigger="... event-name from:body").
+        //
+        // Both are read from the form first, then from the triggering element.
+
+        const refreshSelector = form?.getAttribute('data-refresh-target')
+            || elt.getAttribute('data-refresh-target')
+            || elt.getAttribute('data-refresh-click');
+        if (refreshSelector) {
+            const refreshEl = document.querySelector(refreshSelector);
+            if (refreshEl instanceof HTMLElement && typeof htmx?.trigger === 'function') {
+                htmx.trigger(refreshEl, 'refresh');
+            }
+        }
+
+        const refreshEvent = form?.getAttribute('data-refresh-event') || elt.getAttribute('data-refresh-event');
+        if (refreshEvent) {
+            document.body.dispatchEvent(new CustomEvent(refreshEvent, { bubbles: true }));
+        }
+    }
+});

package/src/core/navigation.js

@@ -0,0 +1,115 @@
+// ---------------------------
+// Navigation utilities + active nav highlighting
+// ---------------------------
+// URL helpers, active nav link highlighting, and history event handlers.
+// Self-registers afterSwap/afterSettle/pushedIntoHistory/popstate listeners.
+
+export function normalizePath(p) {
+    if (!p) return '/';
+    if (p === '/') return '/';
+    return p.endsWith('/') ? p : `${p}/`;
+}
+
+export function setActiveNav(pathOverride) {
+    const current = normalizePath(pathOverride ?? window.location.pathname);
+
+    // Subnav link highlighting (exact match, or prefix match via data-nav-match)
+    document.querySelectorAll('a[data-nav]').forEach((a) => {
+        const href = normalizePath(a.getAttribute('href'));
+        const matchPrefix = a.getAttribute('data-nav-match');
+        const isActive = href === current || (matchPrefix && current.startsWith(matchPrefix));
+
+        a.classList.toggle('active-nav', isActive);
+        a.classList.toggle('underline', isActive);
+    });
+
+    // Section tab highlighting (prefix match)
+    document.querySelectorAll('a[data-nav-section]').forEach((a) => {
+        const prefix = a.getAttribute('data-nav-section');
+        const isActive = current.startsWith(prefix);
+
+        a.classList.toggle('active-nav', isActive);
+        a.classList.toggle('underline', isActive);
+    });
+
+    // Subnav toggling — show the matching section, hide others
+    document.querySelectorAll('[data-subnav]').forEach((el) => {
+        const prefix = el.getAttribute('data-subnav');
+        const show = current.startsWith(prefix);
+        el.style.display = show ? '' : 'none';
+        el.classList.remove('hidden');
+    });
+}
+
+export function setUrlParam(key, value) {
+    try {
+        const url = new URL(window.location.href);
+        if (value === null || value === undefined || value === '') {
+            url.searchParams.delete(key);
+        } else {
+            url.searchParams.set(key, String(value));
+        }
+        history.pushState({}, '', url.pathname + url.search + url.hash);
+    } catch {
+        // ignore
+    }
+}
+
+export function getUrlParam(key) {
+    try {
+        return new URL(window.location.href).searchParams.get(key);
+    } catch {
+        return null;
+    }
+}
+
+export function mergeHxVals(el, vals) {
+    let existing = {};
+    try {
+        existing = JSON.parse(el.getAttribute('hx-vals') || '{}');
+    } catch { /* ignore */ }
+    el.setAttribute('hx-vals', JSON.stringify({ ...existing, ...vals }));
+}
+
+export function getUrlParamInt(key, fallback = 1) {
+    try {
+        const url = new URL(window.location.href);
+        const v = url.searchParams.get(key);
+        if (!v) return fallback;
+        const n = parseInt(v, 10);
+        return Number.isFinite(n) && n > 0 ? n : fallback;
+    } catch {
+        return fallback;
+    }
+}
+
+// ---------------------------
+// Self-registered lifecycle handlers
+// ---------------------------
+
+document.addEventListener('DOMContentLoaded', () => {
+    setActiveNav();
+});
+
+document.body.addEventListener('htmx:afterSwap', (e) => {
+    // Always update nav (nav elements are outside #app, so they persist across swaps)
+    setActiveNav();
+});
+
+// Update nav highlighting after HTMX pushes a new URL to history.
+// Use e.detail.path since window.location may not be updated yet.
+document.body.addEventListener('htmx:pushedIntoHistory', (e) => {
+    const newPath = e.detail?.path;
+    setActiveNav(newPath);
+});
+
+// Also try afterSettle as a fallback (with microtask delay to ensure URL is updated)
+document.body.addEventListener('htmx:afterSettle', (e) => {
+    queueMicrotask(() => {
+        setActiveNav();
+    });
+});
+
+window.addEventListener('popstate', () => {
+    setActiveNav();
+});

package/src/core/pagination.js

@@ -0,0 +1,94 @@
+// ---------------------------
+// Pagination controls
+// ---------------------------
+// Wires up paginated HTMX sources, prev/next buttons, goto-page forms,
+// and popstate re-sync. Self-registering — also exports initPagination()
+// for use in DOMContentLoaded/afterSwap orchestration.
+
+import htmx from '../lib/htmx.js';
+import { setUrlParam, getUrlParamInt, mergeHxVals } from './navigation.js';
+
+/**
+ * Wire paginated HTMX sources to read the current page from the URL.
+ * @param {Document|HTMLElement} root - The root to search within
+ */
+export function initPagination(root = document) {
+    root.querySelectorAll('[data-pagination-param]').forEach((el) => {
+        if (!(el instanceof HTMLElement)) return;
+        const param = el.getAttribute('data-pagination-param') || 'page';
+        const page = getUrlParamInt(param, 1);
+        mergeHxVals(el, { [param]: page });
+    });
+}
+
+// Pagination controls: Prev/Next
+// Buttons are rendered by the pagination component template and carry:
+// - data-page="N"
+// - data-pagination-source="#selector-for-hx-element"
+// - data-pagination-param="page"
+document.addEventListener('click', (e) => {
+    const btn = e.target.closest('[data-action="paginate-prev"], [data-action="paginate-next"]');
+    if (!(btn instanceof HTMLElement)) return;
+
+    const pageStr = btn.getAttribute('data-page') || '';
+    const page = parseInt(pageStr, 10);
+    if (!Number.isFinite(page) || page <= 0) return;
+
+    const sourceSel = btn.getAttribute('data-pagination-source') || '';
+    const param = btn.getAttribute('data-pagination-param') || 'page';
+    if (!sourceSel) return;
+
+    const sourceEl = document.querySelector(sourceSel);
+    if (!(sourceEl instanceof HTMLElement)) return;
+
+    mergeHxVals(sourceEl, { [param]: page });
+
+    // Update URL so pagination is shareable and back/forward works.
+    setUrlParam(param, page);
+
+    // Trigger the refresh request (and pagination will re-render from the response meta).
+    if (typeof htmx?.trigger === 'function') {
+        htmx.trigger(sourceEl, 'refresh');
+    }
+});
+
+// Pagination controls: Go to page
+document.addEventListener('submit', (e) => {
+    const form = e.target.closest('[data-action="paginate-goto"]');
+    if (!form) return;
+    e.preventDefault();
+
+    const input = form.querySelector('input[type="number"]');
+    if (!input) return;
+
+    const page = parseInt(input.value, 10);
+    const lastPage = parseInt(form.getAttribute('data-last-page') || '1', 10);
+    if (!Number.isFinite(page) || page < 1 || page > lastPage) return;
+
+    const sourceSel = form.getAttribute('data-pagination-source') || '';
+    const param = form.getAttribute('data-pagination-param') || 'page';
+    if (!sourceSel) return;
+
+    const sourceEl = document.querySelector(sourceSel);
+    if (!(sourceEl instanceof HTMLElement)) return;
+
+    mergeHxVals(sourceEl, { [param]: page });
+    setUrlParam(param, page);
+
+    if (typeof htmx?.trigger === 'function') {
+        htmx.trigger(sourceEl, 'refresh');
+    }
+});
+
+// Re-sync paginated sources on back/forward navigation.
+window.addEventListener('popstate', () => {
+    document.querySelectorAll('[data-pagination-param]').forEach((el) => {
+        if (!(el instanceof HTMLElement)) return;
+        const param = el.getAttribute('data-pagination-param') || 'page';
+        const page = getUrlParamInt(param, 1);
+        mergeHxVals(el, { [param]: page });
+        if (typeof htmx?.trigger === 'function') {
+            htmx.trigger(el, 'refresh');
+        }
+    });
+});

package/src/core/search.js

@@ -0,0 +1,77 @@
+// ---------------------------
+// Search input wiring (delegated)
+// ---------------------------
+// Debounced search: updates hx-get URL on target element and triggers refresh.
+// Usage: <input data-search-target="#some-htmx-element" data-search-endpoint="/api/foo" />
+// Fully self-registering — import for side effects only.
+
+import htmx from '../lib/htmx.js';
+import { debounce, scrubSearchInput } from '../helpers/index.js';
+import { setUrlParam, mergeHxVals } from './navigation.js';
+
+const searchDebouncers = new WeakMap();
+
+document.addEventListener('input', (e) => {
+    const input = e.target;
+    if (!(input instanceof HTMLInputElement)) return;
+    if (!input.dataset.searchTarget) return;
+
+    const targetSelector = input.dataset.searchTarget;
+    const baseEndpoint = input.dataset.searchEndpoint || '/api/series';
+
+    // Get or create debouncer for this input
+    let debouncedSearch = searchDebouncers.get(input);
+    if (!debouncedSearch) {
+        debouncedSearch = debounce((inp, sel, endpoint) => {
+            const target = document.querySelector(sel);
+            if (!(target instanceof HTMLElement)) return;
+
+            const rawValue = inp.value.trim();
+            const scrubbed = scrubSearchInput(rawValue);
+
+            // Detect UUID pattern
+            const uuidPattern = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+            const isUuid = uuidPattern.test(scrubbed);
+
+            let url = endpoint;
+            if (scrubbed) {
+                const paramKey = isUuid ? 'id' : 'search';
+                const params = new URLSearchParams({ [paramKey]: scrubbed });
+                url = `${endpoint}?${params.toString()}`;
+            }
+
+            // Reset pagination to page 1 so search results aren't empty on page N
+            const pageParam = target.getAttribute('data-pagination-param') || 'page';
+            mergeHxVals(target, { [pageParam]: 1 });
+            setUrlParam(pageParam, null);
+
+            // Show loading state, then trigger refresh after min visible duration
+            target.classList.add('search-loading');
+            setTimeout(() => {
+                target.setAttribute('hx-get', url);
+                htmx.process(target);
+
+                if (typeof htmx?.trigger === 'function') {
+                    htmx.trigger(target, 'refresh');
+                }
+            }, 100);
+        }, 350);
+        searchDebouncers.set(input, debouncedSearch);
+    }
+
+    debouncedSearch(input, targetSelector, baseEndpoint);
+});
+
+// Remove search loading state after swap completes
+document.body.addEventListener('htmx:afterSwap', (e) => {
+    const target = e.detail?.target;
+    if (target instanceof HTMLElement) {
+        target.classList.remove('search-loading');
+    }
+});
+
+// Re-init after HTMX history cache restoration (back/forward navigation)
+document.body.addEventListener('htmx:historyRestore', () => {
+    // No-op — search inputs are stateless (delegated input handler re-attaches automatically).
+    // Kept for documentation: if search inputs ever need re-initialization, add it here.
+});

package/src/core/sortable.js

@@ -0,0 +1,116 @@
+// ---------------------------
+// Drag-and-drop sorting (delegated)
+// ---------------------------
+// Initializes SortableJS on elements with [data-sortable] after HTMX swaps.
+// Sends PATCH with redistributed sort_order values on drag end.
+// Fully self-registering — import for side effects only.
+
+import Sortable from 'sortablejs';
+import htmx from '../lib/htmx.js';
+import { GrasprToast } from '../ui/toast.js';
+
+const instances = new WeakMap();
+
+function isSearchActive(container) {
+    const hxGet = container.getAttribute('hx-get') || '';
+    return hxGet.includes('search=');
+}
+
+function initSortable(container) {
+    // Tear down previous instance
+    const prev = instances.get(container);
+    if (prev) {
+        prev.destroy();
+        instances.delete(container);
+    }
+
+    // Disable when search is active
+    if (isSearchActive(container)) {
+        container.classList.add('sortable-disabled');
+        return;
+    }
+    container.classList.remove('sortable-disabled');
+
+    const endpoint = container.dataset.sortableEndpoint;
+    const key = container.dataset.sortableKey || 'locations';
+    if (!endpoint) return;
+
+    const sortable = new Sortable(container, {
+        handle: '.drag-handle',
+        animation: 150,
+        ghostClass: 'sortable-ghost',
+        chosenClass: 'sortable-chosen',
+        onEnd(evt) {
+            if (evt.oldIndex === evt.newIndex) return;
+
+            const rows = Array.from(container.querySelectorAll('tr[data-id]'));
+            if (rows.length === 0) return;
+
+            // Collect existing sort_order values and sort them numerically
+            const sortOrders = rows
+                .map((row) => parseInt(row.dataset.sortOrder, 10))
+                .filter((n) => !isNaN(n))
+                .sort((a, b) => a - b);
+
+            if (sortOrders.length !== rows.length) return;
+
+            // Redistribute: assign sorted values in new DOM order
+            const payload = rows.map((row, i) => {
+                const newOrder = sortOrders[i];
+                // Optimistic UI: update data attribute and visible display
+                row.dataset.sortOrder = String(newOrder);
+                const display = row.querySelector('[data-sort-order-display]');
+                if (display) display.textContent = String(newOrder);
+                return { id: row.dataset.id, sort_order: newOrder };
+            });
+
+            // Send to server
+            fetch(endpoint, {
+                method: 'PATCH',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ [key]: payload }),
+            })
+                .then((res) => {
+                    if (!res.ok) throw new Error(`HTTP ${res.status}`);
+                    return res.json();
+                })
+                .then(() => {
+                    GrasprToast?.show({ message: 'Sort order updated.', status: 'success' });
+                })
+                .catch(() => {
+                    GrasprToast?.show({ message: 'Failed to update sort order.', status: 'error' });
+                    // Reload server state
+                    if (typeof htmx?.trigger === 'function') {
+                        htmx.trigger(container, 'refresh');
+                    }
+                });
+        },
+    });
+
+    instances.set(container, sortable);
+}
+
+function initAllSortables(root) {
+    const containers = root.querySelectorAll
+        ? root.querySelectorAll('[data-sortable]')
+        : [];
+
+    // Also check if root itself is a sortable container
+    if (root instanceof HTMLElement && root.hasAttribute('data-sortable')) {
+        initSortable(root);
+    }
+
+    containers.forEach((el) => initSortable(el));
+}
+
+// Init on full page load
+document.addEventListener('DOMContentLoaded', () => {
+    initAllSortables(document);
+});
+
+// Re-init after HTMX swaps (covers self-loading tbody, boosted nav, search clear)
+document.body.addEventListener('htmx:afterSwap', (e) => {
+    const target = e.detail?.target;
+    if (!target) return;
+    initAllSortables(target);
+});