@phillipsharring/graspr-framework 0.1.0 → 0.2.1

package/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+## 0.2.0
+
+### Added
+- **Lifecycle hooks** — central hook registry for app and page scripts to register callbacks at key points in the page lifecycle. Avoids scattered `htmx:afterSwap` listeners across pages.
+  - `onAfterSwap(fn)` — runs after `#app` is swapped via boosted nav
+  - `onAfterSettle(fn)` — runs after HTMX settle phase (hx-trigger wired up on new elements)
+  - `onPageLoad(fn)` — runs on DOMContentLoaded (full page load only)
+  - `onHistoryRestore(fn)` — runs on browser back/forward (history cache restore)
+- Hooks are registered via the barrel export (`import { onAfterSwap } from '@phillipsharring/graspr-framework'`) or via the app namespace (`App.hooks.onAfterSwap(fn)`).
+- `hooks.js` is auto-loaded via `init.js` — no additional imports needed.
+
+## 0.1.0
+
+Initial release. Nothing changed, except everything.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@phillipsharring/graspr-framework",
-    "version": "0.1.0",
+    "version": "0.2.1",
     "description": "HTMX + Handlebars + Tailwind frontend framework",
     "type": "module",
     "exports": {

package/src/hooks.js

@@ -0,0 +1,69 @@
+// ---------------------------
+// Lifecycle Hooks
+// ---------------------------
+// Central hook registry for app and page scripts to register callbacks
+// that fire at key points in the page lifecycle. Avoids direct
+// htmx:afterSwap / DOMContentLoaded listeners scattered across pages.
+//
+// Usage from app code:
+//   import { onAfterSwap } from '@phillipsharring/graspr-framework';
+//   onAfterSwap(function(target) { initMyWidget(target); });
+//
+// Usage from inline page scripts:
+//   App.hooks.onAfterSwap(function(target) { ... });
+
+const hooks = {
+    afterSwap: [],
+    afterSettle: [],
+    pageLoad: [],
+    historyRestore: [],
+};
+
+var pageLoaded = document.readyState !== 'loading';
+
+/** Register a callback that runs after #app is swapped via boosted nav. */
+export function onAfterSwap(fn) {
+    hooks.afterSwap.push(fn);
+}
+
+/** Register a callback that runs after HTMX settle phase (hx-trigger wired up). */
+export function onAfterSettle(fn) {
+    hooks.afterSettle.push(fn);
+}
+
+/** Register a callback that runs on DOMContentLoaded (full page load only).
+ *  If DOMContentLoaded already fired, runs immediately. */
+export function onPageLoad(fn) {
+    hooks.pageLoad.push(fn);
+    if (pageLoaded) fn(document);
+}
+
+/** Register a callback that runs on browser back/forward (history restore). */
+export function onHistoryRestore(fn) {
+    hooks.historyRestore.push(fn);
+}
+
+// ── Wire up the actual event listeners (one each, calls all registered hooks) ──
+
+document.body.addEventListener('htmx:afterSwap', function(e) {
+    var target = e.detail?.target;
+    if (target && target.id === 'app') {
+        hooks.afterSwap.forEach(function(fn) { fn(target); });
+    }
+});
+
+document.body.addEventListener('htmx:afterSettle', function(e) {
+    var target = e.detail?.target;
+    if (target && target.id === 'app') {
+        hooks.afterSettle.forEach(function(fn) { fn(target); });
+    }
+});
+
+document.addEventListener('DOMContentLoaded', function() {
+    pageLoaded = true;
+    hooks.pageLoad.forEach(function(fn) { fn(document); });
+});
+
+document.body.addEventListener('htmx:historyRestore', function() {
+    hooks.historyRestore.forEach(function(fn) { fn(); });
+});

package/src/index.js

@@ -71,3 +71,6 @@ 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';
+
+// Lifecycle hooks
+export { onAfterSwap, onAfterSettle, onPageLoad, onHistoryRestore } from './hooks.js';

package/src/init.js

@@ -11,3 +11,4 @@ import './core/auth-state.js';
 import './core/forms.js';
 import './core/search.js';
 import './core/sortable.js';
+import './hooks.js';