@hyperspan/framework 1.0.27 → 1.0.28

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperspan/framework",
-  "version": "1.0.27",
+  "version": "1.0.28",
   "description": "Hyperspan Web Framework",
   "main": "src/server.ts",
   "types": "src/server.ts",

package/src/client/_hs/hyperspan-actions.client.ts

@@ -1,5 +1,63 @@
 import { Idiomorph } from './idiomorph';
 import { lazyLoadScripts } from './hyperspan-scripts.client';
+import type { Hyperspan as HS } from '../../types';
+
+const HS_ACTION_BEFORE_FETCH: HS.ActionEventName = 'hs:action:before-fetch';
+const HS_ACTION_AFTER_FETCH: HS.ActionEventName = 'hs:action:after-fetch';
+const HS_ACTION_BEFORE_SWAP: HS.ActionEventName = 'hs:action:before-swap';
+const HS_ACTION_AFTER_SWAP: HS.ActionEventName = 'hs:action:after-swap';
+const HS_ACTION_BEFORE_NAVIGATE: HS.ActionEventName = 'hs:action:before-navigate';
+
+function dispatchActionEvent<T>(
+  target: EventTarget,
+  name: HS.ActionEventName,
+  detail: T,
+  cancelable = false
+): boolean {
+  return target.dispatchEvent(
+    new CustomEvent(name, {
+      detail,
+      bubbles: true,
+      cancelable,
+      composed: true,
+    })
+  );
+}
+
+/** No box by default (`display: contents`) — style `:has(hs-action-loading)` for loading UI. */
+function ensureActionLoadingStyles() {
+  if (document.getElementById('hs-action-loading-style')) {
+    return;
+  }
+  const style = document.createElement('style');
+  style.id = 'hs-action-loading-style';
+  style.textContent = 'hs-action-loading{display:contents}';
+  document.head.appendChild(style);
+}
+
+class HSActionLoading extends HTMLElement {
+  connectedCallback() {
+    ensureActionLoadingStyles();
+  }
+}
+
+if (!customElements.get('hs-action-loading')) {
+  customElements.define('hs-action-loading', HSActionLoading);
+}
+
+function setActionLoading(hsActionTag: HTMLElement | null, loading: boolean) {
+  if (!hsActionTag) {
+    return;
+  }
+  const existing = hsActionTag.querySelector('hs-action-loading');
+  if (loading) {
+    if (!existing) {
+      hsActionTag.appendChild(document.createElement('hs-action-loading'));
+    }
+  } else if (existing) {
+    existing.remove();
+  }
+}
 
 const actionFormObserver = new MutationObserver((list) => {
   list.forEach((mutation) => {
@@ -71,7 +129,24 @@ function formSubmitToRoute(e: Event, form: HTMLFormElement, opts: TFormSubmitOpt
     }
   }
 
-  const hsActionTag = form.closest('hs-action');
+  const hsActionTag = form.closest('hs-action') as HTMLElement | null;
+  const eventTarget: EventTarget = hsActionTag || document;
+  const fetchDetail: HS.ActionFetchDetail = {
+    form,
+    action: hsActionTag,
+    url: formUrl,
+    method,
+    loadingElement: true,
+  };
+
+  if (!dispatchActionEvent(eventTarget, HS_ACTION_BEFORE_FETCH, fetchDetail, true)) {
+    return;
+  }
+
+  if (fetchDetail.loadingElement) {
+    setActionLoading(hsActionTag, true);
+  }
+
   const submitBtn = form.querySelector('button[type=submit],input[type=submit]');
   if (submitBtn) {
     submitBtn.setAttribute('disabled', 'disabled');
@@ -82,6 +157,18 @@ function formSubmitToRoute(e: Event, form: HTMLFormElement, opts: TFormSubmitOpt
     if (isFullDocument) {
       html = html.replace(/^[\s\uFEFF]*<!DOCTYPE[^>]*>/i, '');
     }
+
+    const swapDetail: HS.ActionSwapDetail = {
+      form,
+      action: hsActionTag,
+      html,
+      fullDocument: isFullDocument,
+    };
+
+    if (!dispatchActionEvent(eventTarget, HS_ACTION_BEFORE_SWAP, swapDetail, true)) {
+      return;
+    }
+
     const target = isFullDocument ? window.document : hsActionTag || form;
     const options = isFullDocument ? undefined : { morphStyle: 'innerHTML' };
 
@@ -96,10 +183,42 @@ function formSubmitToRoute(e: Event, form: HTMLFormElement, opts: TFormSubmitOpt
 
     activateScriptsIn(isFullDocument ? document.body : (target as ParentNode));
 
+    dispatchActionEvent(eventTarget, HS_ACTION_AFTER_SWAP, swapDetail);
+
     opts.afterResponse && opts.afterResponse();
     lazyLoadScripts();
   }
 
+  async function navigateTo(url: string, preferHard: boolean) {
+    const navigateDetail: HS.ActionNavigateDetail = {
+      form,
+      action: hsActionTag,
+      url,
+      hard: preferHard,
+    };
+
+    if (!dispatchActionEvent(eventTarget, HS_ACTION_BEFORE_NAVIGATE, navigateDetail, true)) {
+      return;
+    }
+
+    if (navigateDetail.hard) {
+      window.location.assign(navigateDetail.url);
+      return;
+    }
+
+    // Soft morph requires same-origin (CORS / Idiomorph are not safe across domains).
+    const resolved = new URL(navigateDetail.url, window.location.href);
+    if (resolved.origin !== window.location.origin) {
+      window.location.assign(navigateDetail.url);
+      return;
+    }
+
+    const pageRes = await fetch(navigateDetail.url, {
+      headers: { Accept: 'text/html' },
+    });
+    await consumeStreamingHtmlResponse(pageRes, applyResponseHtml);
+  }
+
   fetch(formUrl, { body: formData, method, headers })
     .then(async (res: Response) => {
       // Look for special header that indicates a redirect.
@@ -109,21 +228,13 @@ function formSubmitToRoute(e: Event, form: HTMLFormElement, opts: TFormSubmitOpt
         if (newUrl) {
           const resolved = new URL(newUrl, window.location.href);
 
-          // Same-origin + same path: fetch updated HTML and morph in place. Cross-origin redirects
-          // must use full navigation (CORS and Idiomorph are not safe across domains).
-          if (
-            resolved.origin === window.location.origin &&
-            resolved.pathname === window.location.pathname
-          ) {
-            const pageRes = await fetch(resolved.href, {
-              headers: { Accept: 'text/html' },
-            });
-            await consumeStreamingHtmlResponse(pageRes, applyResponseHtml);
-            return;
-          }
-
-          // If the new URL is different, we need to redirect the user to the new URL
-          window.location.assign(newUrl);
+          // Default: same-origin + same path → soft morph; anything else → hard navigation.
+          // Listeners can flip detail.hard on hs:action:before-navigate to override.
+          const preferHard =
+            resolved.origin !== window.location.origin ||
+            resolved.pathname !== window.location.pathname;
+
+          await navigateTo(newUrl, preferHard);
         }
         return;
       }
@@ -132,6 +243,10 @@ function formSubmitToRoute(e: Event, form: HTMLFormElement, opts: TFormSubmitOpt
     })
     .catch((error) => {
       console.error('[Hyperspan] Error submitting form action:', error);
+    })
+    .finally(() => {
+      setActionLoading(hsActionTag, false);
+      dispatchActionEvent(eventTarget, HS_ACTION_AFTER_FETCH, fetchDetail);
     });
 }
 

package/src/types.ts

@@ -299,6 +299,56 @@ export namespace Hyperspan {
     fetch: (request: Request) => Promise<Response>;
   }
 
+  /**
+   * Client-side action lifecycle events (dispatched from `<hs-action>`, bubbles to document).
+   *
+   * - `hs:action:before-fetch` — before the action request starts (cancelable).
+   * - `hs:action:after-fetch` — after the action request finishes (success or error).
+   * - `hs:action:before-swap` — before HTML morph (cancelable). Close modals here.
+   * - `hs:action:after-swap` — after HTML morph.
+   * - `hs:action:before-navigate` — before redirect soft/hard navigation (cancelable).
+   *   Set `detail.hard = true` for a full page load, or `false` to fetch+morph in place.
+   */
+  export type ActionEventName =
+    | 'hs:action:before-fetch'
+    | 'hs:action:after-fetch'
+    | 'hs:action:before-swap'
+    | 'hs:action:after-swap'
+    | 'hs:action:before-navigate';
+
+  export type ActionFetchDetail = {
+    form: HTMLFormElement;
+    /** The current `<hs-action>` element, if present. */
+    action: HTMLElement | null;
+    url: string;
+    method: string;
+    /**
+     * Mutable. When `true` (default), appends `<hs-action-loading>` inside `<hs-action>` for the
+     * duration of the request. Set to `false` in `hs:action:before-fetch` to skip it.
+     */
+    loadingElement: boolean;
+  };
+
+  export type ActionSwapDetail = {
+    form: HTMLFormElement;
+    /** The current `<hs-action>` element, if present. */
+    action: HTMLElement | null;
+    html: string;
+    fullDocument: boolean;
+  };
+
+  export type ActionNavigateDetail = {
+    form: HTMLFormElement;
+    /** The current `<hs-action>` element, if present. */
+    action: HTMLElement | null;
+    url: string;
+    /**
+     * Mutable. Default is soft (false) for same-origin+same-path redirects, hard (true) otherwise.
+     * Set to `true` for `window.location.assign`, or `false` to fetch + morph in place.
+     */
+    hard: boolean;
+  };
+
   /**
    * Client JS Module = ESM Module + Public Path + Render Script Tag
    */
@@ -324,3 +374,20 @@ export namespace Hyperspan {
     formErrors: unknown[];
   }
 }
+
+declare global {
+  interface DocumentEventMap {
+    'hs:action:before-fetch': CustomEvent<Hyperspan.ActionFetchDetail>;
+    'hs:action:after-fetch': CustomEvent<Hyperspan.ActionFetchDetail>;
+    'hs:action:before-swap': CustomEvent<Hyperspan.ActionSwapDetail>;
+    'hs:action:after-swap': CustomEvent<Hyperspan.ActionSwapDetail>;
+    'hs:action:before-navigate': CustomEvent<Hyperspan.ActionNavigateDetail>;
+  }
+  interface HTMLElementEventMap {
+    'hs:action:before-fetch': CustomEvent<Hyperspan.ActionFetchDetail>;
+    'hs:action:after-fetch': CustomEvent<Hyperspan.ActionFetchDetail>;
+    'hs:action:before-swap': CustomEvent<Hyperspan.ActionSwapDetail>;
+    'hs:action:after-swap': CustomEvent<Hyperspan.ActionSwapDetail>;
+    'hs:action:before-navigate': CustomEvent<Hyperspan.ActionNavigateDetail>;
+  }
+}