@phillipsharring/graspr-framework 0.1.0

package/README.md

@@ -0,0 +1,119 @@
+# Graspr Framework
+
+A frontend framework for building server-driven web applications with **HTMX + Handlebars + Tailwind CSS**.
+
+Graspr handles the hard parts of HTMX-based apps: boosted navigation, auth-gated widgets, modal/toast systems, CSRF token management, form error handling, and client-side template rendering — so you can focus on your pages and domain logic.
+
+## Installation
+
+```bash
+npm install @phillipsharring/graspr-framework
+```
+
+Peer dependencies (your app must install these):
+```bash
+npm install htmx.org handlebars sortablejs
+```
+
+For a ready-to-go project structure, use the [Graspr App Skeleton](https://github.com/phillipsharring/graspr-app-skeleton).
+
+## What's Included
+
+### Core Infrastructure (`core/`)
+- **boosted-nav** — fixes HTMX boosted navigation edge cases (inherited targets, `hx-select` overrides, layout mismatch detection)
+- **csrf** — global `fetch()` interceptor + HTMX hook for automatic CSRF token headers
+- **auth-state** — auth-gated UI orchestration (`auth-load` events, permission gating, login modal, 401/403 handling)
+- **forms** — inline form error display, modal form lifecycle, success redirect/refresh patterns
+- **pagination** — paginated table controls with URL param syncing
+- **search** — debounced search input with HTMX integration
+- **sortable** — drag-and-drop reordering via SortableJS wrapper
+- **table-sort** — clickable column header sorting with URL persistence
+- **navigation** — URL helpers, active nav highlighting
+
+### UI Widgets (`ui/`)
+- **modal** — global modal state machine with focus management and overlay/escape handling
+- **modal-form** — modal form populator (set fields, method, clear errors, focus)
+- **toast** — toast notification system with auto-dismiss
+- **confirm-dialog** — confirmation dialog with optional progress mode for batch operations
+- **typeahead** — autocomplete widget factory with keyboard navigation
+- **click-burst** — visual click feedback animation
+
+### HTMX Extensions (`lib/`)
+- **json-enc** — JSON encoding extension for HTMX requests
+- **client-side-templates** — Handlebars template rendering for HTMX JSON responses
+
+### Helpers (`helpers/`)
+- **handlebars-helpers** — generic Handlebars helpers (eq, neq, and, or, truncate, timeAgo, formatDateTime, json, treeIndent, etc.)
+- **escape-html** — HTML escape utility
+- **populate-select** — `<select>` field populator
+- **route-params** — URL parameter extraction for dynamic routes (`[id]` patterns)
+- **debounce** — debounce utility + search input sanitization
+
+### Auth (`auth.js`)
+- Single `/api/auth/me` call per page load, cached
+- `checkAuth()` — returns `Promise<boolean>`
+- `getAuthData()` — returns full auth response with permissions
+- `refreshAuthData()` — invalidates cache and re-fetches
+
+### API Client (`fetch-client.js`)
+- `apiFetch(url, options)` — wraps `fetch()` with CSRF headers, JSON content type, body serialization
+
+### Styles (`styles/base.css`)
+- Form error styles, HTMX request dimming, modal/takeover animations, sortable drag-and-drop, table sort headers, confirm dialog, active nav highlighting
+
+## Usage
+
+### Import everything at once
+```js
+import {
+    GrasprToast, openFormModal, GrasprConfirm,
+    initPagination, initTableSort,
+    getRouteParams, escapeHtml,
+} from '@phillipsharring/graspr-framework';
+```
+
+### Side-effect initialization
+```js
+// Registers CSRF interceptors, boosted-nav handlers, auth-state listeners,
+// form error handling, search, and sortable — in the correct order.
+import '@phillipsharring/graspr-framework/init';
+```
+
+### HTMX extensions (import after setting window.Handlebars)
+```js
+import '@phillipsharring/graspr-framework/src/lib/json-enc.js';
+import '@phillipsharring/graspr-framework/src/lib/client-side-templates.js';
+```
+
+### Styles
+```css
+@import 'tailwindcss';
+@source "../../content/**/*.html";
+@source "../**/*.js";
+@import '@phillipsharring/graspr-framework/styles/base.css';
+```
+
+### Configurable auth permissions
+```js
+import { registerAdminPermissionPrefixes } from '@phillipsharring/graspr-framework';
+
+registerAdminPermissionPrefixes([
+    ['/admin/design/', 'design.access'],
+    ['/admin/story/', 'story.access'],
+    ['/admin/', 'admin.access'],
+]);
+```
+
+## Designed For
+
+Graspr is the frontend companion to [Handlr Framework](https://github.com/phillipsharring/handlr-framework) (PHP backend), but works with any backend that serves JSON APIs and HTML pages. The auth system expects a `/api/auth/me` endpoint; everything else is configurable.
+
+## Requirements
+
+- Vite 7+
+- Tailwind CSS 4+
+- Node.js 18+
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,19 @@
+{
+    "name": "@phillipsharring/graspr-framework",
+    "version": "0.1.0",
+    "description": "HTMX + Handlebars + Tailwind frontend framework",
+    "type": "module",
+    "exports": {
+        ".": "./src/index.js",
+        "./init": "./src/init.js",
+        "./styles/*": "./styles/*",
+        "./src/*": "./src/*"
+    },
+    "author": "Phillip Harrington <phillip@phillipharrington.com> (https://phillipharrington.com/)",
+    "license": "MIT",
+    "peerDependencies": {
+        "handlebars": "^4.7.0",
+        "htmx.org": "^2.0.0",
+        "sortablejs": "^1.15.0"
+    }
+}

package/src/auth.js

@@ -0,0 +1,47 @@
+// ---------------------------
+// Centralized Auth Check
+// ---------------------------
+// Makes a single /api/auth/me call per page load and caches the result.
+// Import `checkAuth` for a boolean, or `getAuthData` for the full response.
+// Call `refreshAuthData()` to invalidate the cache and re-fetch.
+
+function fetchAuthData() {
+    return fetch('/api/auth/me', { credentials: 'same-origin' })
+        .then(r => r.json())
+        .then(data => ({
+            authenticated: !!data.data?.authenticated,
+            username: data.data?.user?.username || null,
+            permissions: data.meta?.permissions || [],
+        }))
+        .catch(() => ({ authenticated: false, username: null, permissions: [] }));
+}
+
+let authPromise = fetchAuthData();
+
+/**
+ * Resolves with `true` when the user is authenticated, `false` otherwise.
+ * The check runs once per page load; subsequent calls return the cached result.
+ * @returns {Promise<boolean>}
+ */
+export function checkAuth() {
+    return authPromise.then(d => d.authenticated);
+}
+
+/**
+ * Resolves with the full auth data object: { authenticated, username, permissions }.
+ * Same cache as checkAuth — no extra network call.
+ * @returns {Promise<{authenticated: boolean, username: string|null, permissions: string[]}>}
+ */
+export function getAuthData() {
+    return authPromise;
+}
+
+/**
+ * Invalidates the cached auth data and re-fetches from /api/auth/me.
+ * Returns the fresh auth data promise.
+ * @returns {Promise<{authenticated: boolean, username: string|null, permissions: string[]}>}
+ */
+export function refreshAuthData() {
+    authPromise = fetchAuthData();
+    return authPromise;
+}

package/src/core/auth-state.js

@@ -0,0 +1,227 @@
+// ---------------------------
+// Auth-gated UI
+// ---------------------------
+// Manages authentication state visibility, auth-gated widget triggering,
+// admin permission checks, login modal, and 401 interception.
+// Fully self-registering — import for side effects only.
+
+import htmx from '../lib/htmx.js';
+import { checkAuth, getAuthData, refreshAuthData } from '../auth.js';
+import { isGlobalModalOpen } from '../ui/index.js';
+import { openFormModal } from '../ui/modal-form.js';
+import { GrasprToast } from '../ui/toast.js';
+
+// ---------------------------
+// Header widget refresh
+// ---------------------------
+
+function refreshHeaderWidgets({ selector = '[data-header-widget]', eventName = 'refresh' } = {}) {
+    // Header widgets live outside #app, so they won't be re-initialized by page swaps.
+    // Mark any widget with `data-header-widget` and give it `hx-trigger="auth-load, refresh"`.
+    if (typeof htmx?.trigger !== 'function') return;
+    document.querySelectorAll(selector).forEach((el) => {
+        if (el instanceof HTMLElement) {
+            htmx.trigger(el, eventName);
+        }
+    });
+}
+
+// ---------------------------
+// Auth state application
+// ---------------------------
+// Reveals auth-dependent elements. Idempotent — safe to call after every swap.
+
+const authPending = new WeakSet();
+
+function applyAuthState(authData) {
+    const authenticated = typeof authData === 'boolean' ? authData : authData.authenticated;
+    const username = typeof authData === 'object' ? authData.username : null;
+
+    // Auth links — both start hidden; reveal the correct one.
+    const loginLink = document.querySelector('[data-auth-login]');
+    const logoutLink = document.querySelector('[data-auth-logout]');
+
+    if (authenticated) {
+        logoutLink?.removeAttribute('hidden');
+        // Show username in the user menu button
+        const usernameEl = document.getElementById('user-menu-username');
+        if (usernameEl && username) {
+            usernameEl.textContent = username;
+        }
+    } else {
+        loginLink?.removeAttribute('hidden');
+    }
+
+    // Widgets that require an authenticated session.
+    // Track triggered elements in a WeakSet so each element only fires once,
+    // even if multiple afterSwap/afterSettle handlers call applyAuthState while
+    // requests are still in flight. New elements (e.g. after boosted nav swaps
+    // #app) won't be in the set and will be triggered normally.
+    if (authenticated && typeof htmx?.trigger === 'function') {
+        document.querySelectorAll('[data-requires-auth]').forEach(el => {
+            if (!el.children.length && !authPending.has(el)) {
+                authPending.add(el);
+                htmx.trigger(el, 'auth-load');
+            }
+        });
+    }
+
+    // Permission-gated elements — reveal if user has the required permission.
+    // Uses cached getAuthData(), no extra network call.
+    if (authenticated) {
+        applyPermissionGating();
+    }
+
+    // If not authenticated and the page has auth-required content inside #app,
+    // prompt the user to log in. (showLoginModal clears #app opacity itself.)
+    if (!authenticated && document.querySelector('#app [data-requires-auth]')) {
+        showLoginModal();
+        return;
+    }
+
+    // Clear auth opacity gate for non-admin layouts.
+    // Admin has its own permission-aware clearing in checkAdminPermissions().
+    const app = document.getElementById('app');
+    if (app && app.dataset?.layout !== 'admin') {
+        app.style.opacity = '';
+    }
+}
+
+// ---------------------------
+// Permission-gated elements
+// ---------------------------
+// Elements with data-requires-permission="some.permission" start hidden
+// and are revealed only if the user has that permission.
+
+function applyPermissionGating() {
+    const els = document.querySelectorAll('[data-requires-permission]');
+    if (!els.length) return;
+
+    getAuthData().then(({ permissions }) => {
+        els.forEach(el => {
+            if (permissions.includes(el.dataset.requiresPermission)) {
+                el.removeAttribute('hidden');
+            }
+        });
+    });
+}
+
+// Initial auth check + apply (pass full data for username).
+getAuthData().then(applyAuthState);
+
+// ---------------------------
+// Admin permission checks
+// ---------------------------
+// Derives required permission from URL prefix — no per-page attributes needed.
+// Apps register their own prefixes via registerAdminPermissionPrefixes().
+
+let adminPermissionPrefixes = [];
+
+/**
+ * Register URL-prefix → permission mappings for admin permission checks.
+ * More specific prefixes should come first (e.g. '/admin/design/' before '/admin/').
+ * @param {Array<[string, string]>} prefixes - Array of [urlPrefix, permissionName] pairs
+ */
+export function registerAdminPermissionPrefixes(prefixes) {
+    adminPermissionPrefixes = prefixes;
+}
+
+function checkAdminPermissions(appEl) {
+    if (appEl.dataset?.layout !== 'admin') return;
+
+    const path = window.location.pathname;
+    const required = adminPermissionPrefixes.find(([prefix]) => path.startsWith(prefix))?.[1];
+    if (!required) return;
+
+    getAuthData().then(({ authenticated, permissions }) => {
+        if (!authenticated) {
+            showLoginModal();
+        } else if (!permissions.includes(required)) {
+            window.location.href = '/game/';
+            return; // don't reveal — redirecting
+        }
+        appEl.style.opacity = '';
+    });
+}
+
+// ---------------------------
+// 401 / Unauthenticated → Login Modal
+// ---------------------------
+
+function showLoginModal() {
+    // Drop a login link into #app so there's something to click if the modal is dismissed
+    const app = document.getElementById('app');
+    if (app && !app.querySelector('[data-login-prompt]')) {
+        app.innerHTML = `
+            <div data-login-prompt class="flex items-center justify-center min-h-[60vh]">
+                <a href="/login/"
+                    class="rounded px-6 py-3 bg-slate-900 text-white hover:bg-slate-800 text-lg no-underline"
+                >Login</a>
+            </div>`;
+        app.style.opacity = '';
+    }
+
+    if (isGlobalModalOpen()) return;
+    openFormModal({
+        templateId: 'login-form-template',
+        title: 'Login',
+        size: 'sm',
+    });
+}
+
+// Catch 401/403 responses before swap
+document.body.addEventListener('htmx:beforeSwap', (e) => {
+    const xhr = e.detail?.xhr;
+    if (xhr?.status === 401) {
+        e.detail.shouldSwap = false;
+        showLoginModal();
+    } else if (xhr?.status === 403) {
+        // CSRF failure — the response includes a fresh token (captured by
+        // the htmx:afterRequest hook in csrf.js), so the next request will work.
+        e.detail.shouldSwap = false;
+        GrasprToast.show({ message: 'Session expired, please try again.', status: 'warning' });
+    }
+}, true); // Use capture to run before other beforeSwap handlers
+
+// ---------------------------
+// Self-registered lifecycle handlers
+// ---------------------------
+
+// Check admin permissions on full page load.
+document.addEventListener('DOMContentLoaded', () => {
+    const app = document.getElementById('app');
+    if (app) checkAdminPermissions(app);
+});
+
+// On #app swap: refresh header widgets + re-check admin permissions.
+document.body.addEventListener('htmx:afterSwap', (e) => {
+    const target = e.detail?.target;
+
+    if (target && target.id === 'app') {
+        checkAuth().then(auth => { if (auth) refreshHeaderWidgets(); });
+        // outerHTML swap detaches the old target — grab the live element from DOM
+        const app = document.getElementById('app');
+        if (app) checkAdminPermissions(app);
+    }
+});
+
+// Fire auth-load AFTER settle, not after swap.
+// HTMX lifecycle: beforeSwap → DOM swap → afterSwap → settle (processes hx-trigger
+// etc. on new elements) → afterSettle. Firing auth-load in afterSwap meant the
+// custom event fired before HTMX had wired up hx-trigger="auth-load" on the new
+// elements — so nothing was listening yet.
+document.body.addEventListener('htmx:afterSettle', (e) => {
+    const target = e.detail?.target;
+
+    // Skip widget responses — otherwise the first widget's afterSettle would
+    // re-trigger auth-load on sibling widgets that haven't loaded yet.
+    if (!target?.closest('[data-requires-auth]')) {
+        getAuthData().then(applyAuthState);
+    }
+});
+
+// Re-fetch /api/auth/me and re-apply auth state (updates header username, etc.).
+// Any code can fire this: document.body.dispatchEvent(new CustomEvent('auth-refresh'))
+document.body.addEventListener('auth-refresh', () => {
+    refreshAuthData().then(applyAuthState);
+});

package/src/core/boosted-nav.js

@@ -0,0 +1,94 @@
+// ----------------------------
+// Boosted-nav infrastructure
+// ----------------------------
+// Handles three concerns for HTMX apps with hx-boost="true" on <body>:
+//
+// 1. hx-select override: <body> has hx-select="#app" for boosted nav. Non-boosted
+//    elements (buttons, forms) inherit it, but their JSON/template responses don't
+//    contain #app — so hx-select filters everything out. Fix: clear inherited
+//    hx-select for non-boosted requests via selectOverride = 'unset'.
+//
+// 2. Inherited target fix: Self-loading elements (tbody, detail divs) use
+//    hx-target="this". Boosted <a> links inside them inherit that target, causing
+//    the next page to load inside the table/div. Detects and redirects to #app.
+//
+// 3. Layout mismatch: When boosted nav crosses layouts (e.g. game → admin), only
+//    #app swaps — the chrome stays wrong. Detects layout differences and forces a
+//    full page reload.
+
+/**
+ * Check if an element is a boosted page navigation link (not an explicit hx-get/hx-post).
+ */
+export function isBoostedPageNav(elt) {
+    return elt instanceof HTMLAnchorElement
+        && !elt.hasAttribute('hx-get')
+        && !elt.hasAttribute('hx-post');
+}
+
+function extractLayoutFromResponse(html) {
+    const match = html.match(/id=["']app["'][^>]*data-layout=["']([^"']+)["']/);
+    return match?.[1] ?? null;
+}
+
+// hx-select override for non-boosted elements
+document.body.addEventListener('htmx:beforeSwap', (e) => {
+    const elt = e.detail.requestConfig?.elt;
+    if (!elt || isBoostedPageNav(elt)) return;
+
+    // Don't override if already set by another handler or the server
+    if (e.detail.selectOverride) return;
+
+    // Don't override if the element explicitly declares hx-select
+    if (elt.hasAttribute('hx-select')) return;
+
+    e.detail.selectOverride = 'unset';
+});
+
+// Boosted-nav interceptor + Layout mismatch detection
+document.body.addEventListener('htmx:beforeSwap', (e) => {
+    const detail = e.detail || {};
+    const elt = detail.requestConfig?.elt;
+
+    if (!elt || !isBoostedPageNav(elt)) return;
+
+    const app = document.getElementById('app');
+    if (!app) return;
+
+    // --- Fix inherited target ---
+    if (detail.target !== app) {
+        const parser = new DOMParser();
+        const doc = parser.parseFromString(detail.serverResponse, 'text/html');
+        const newApp = doc.getElementById('app');
+
+        if (!newApp) return;
+
+        detail.target = app;
+        detail.serverResponse = newApp.outerHTML;
+        detail.swapOverride = 'outerHTML';
+    }
+
+    // --- Strip admin opacity gate ---
+    // Admin layout uses style="opacity: 0" on #app to prevent content flash before
+    // auth check on full page load. On boosted nav auth is already verified, so strip
+    // it from the response before HTMX swaps it in.
+    if (detail.serverResponse) {
+        detail.serverResponse = detail.serverResponse.replace(
+            /(<[^>]*id=["']app["'][^>]*)\s*style=["']opacity:\s*0["']/,
+            '$1'
+        );
+    }
+
+    // --- Layout mismatch detection ---
+    const currentLayout = app.dataset?.layout;
+    if (!currentLayout) return;
+
+    const incomingLayout = extractLayoutFromResponse(detail.serverResponse);
+
+    if (incomingLayout && incomingLayout !== currentLayout) {
+        detail.shouldSwap = false;
+        const path = detail.pathInfo?.requestPath || detail.xhr?.responseURL;
+        if (path) {
+            window.location.href = path;
+        }
+    }
+});

package/src/core/csrf.js

@@ -0,0 +1,63 @@
+// ---------------------------
+// CSRF Protection
+// ---------------------------
+// Self-registering module — import for side effects only.
+// Must be imported BEFORE auth.js so the fetch interceptor captures
+// the initial /api/auth/me request.
+//
+// Two layers:
+// 1. Global fetch() interceptor — protects all existing fetch() calls
+// 2. HTMX event hooks — protects all HTMX-driven requests
+//
+// Token is stored in a cookie (XSRF-TOKEN) set by the backend.
+// All tabs share the same cookie, preventing multi-tab desync.
+
+const CSRF_HEADER = 'X-CSRF-Token';
+const CSRF_COOKIE = 'XSRF-TOKEN';
+
+function readTokenFromCookie() {
+    const match = document.cookie.match(new RegExp(`(?:^|;\\s*)${CSRF_COOKIE}=([^;]*)`));
+    return match ? decodeURIComponent(match[1]) : null;
+}
+
+export function getCsrfToken() {
+    return readTokenFromCookie();
+}
+
+export function setCsrfToken(_token) {
+    // No-op — token is managed via Set-Cookie by the backend.
+    // Kept for API compatibility (fetch-client.js imports this).
+}
+
+// ---------------------------
+// Global fetch interceptor
+// ---------------------------
+// Patches window.fetch to inject CSRF header on /api/ requests.
+
+const originalFetch = window.fetch.bind(window);
+
+window.fetch = function (input, init = {}) {
+    const url = typeof input === 'string' ? input : input?.url || '';
+
+    if (url.startsWith('/api/')) {
+        const headers = new Headers(init.headers || {});
+        const token = readTokenFromCookie();
+        if (token) {
+            headers.set(CSRF_HEADER, token);
+        }
+        init = { ...init, headers };
+    }
+
+    return originalFetch(input, init);
+};
+
+// ---------------------------
+// HTMX hooks
+// ---------------------------
+
+document.body.addEventListener('htmx:configRequest', (e) => {
+    const token = readTokenFromCookie();
+    if (token) {
+        e.detail.headers[CSRF_HEADER] = token;
+    }
+});