@hyperspan/framework 1.0.0-alpha.1 → 1.0.0-alpha.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperspan/framework",
-  "version": "1.0.0-alpha.1",
+  "version": "1.0.0-alpha.11",
   "description": "Hyperspan Web Framework",
   "main": "src/server.ts",
   "types": "src/server.ts",
@@ -10,8 +10,8 @@
   },
   "exports": {
     ".": {
-      "types": "./src/server.ts",
-      "default": "./src/server.ts"
+      "types": "./src/index.ts",
+      "default": "./src/index.ts"
     },
     "./server": {
       "types": "./src/server.ts",
@@ -21,10 +21,6 @@
       "types": "./src/middleware.ts",
       "default": "./src/middleware.ts"
     },
-    "./middleware/zod": {
-      "types": "./src/middleware/zod.ts",
-      "default": "./src/middleware/zod.ts"
-    },
     "./utils": {
       "types": "./src/utils.ts",
       "default": "./src/utils.ts"
@@ -44,6 +40,10 @@
     "./plugins": {
       "types": "./src/plugins.ts",
       "default": "./src/plugins.ts"
+    },
+    "./actions": {
+      "types": "./src/actions.ts",
+      "default": "./src/actions.ts"
     }
   },
   "author": "Vance Lucas <vance@vancelucas.com>",
@@ -76,7 +76,7 @@
     "typescript": "^5.9.3"
   },
   "dependencies": {
-    "@hyperspan/html": "0.2.0",
+    "@hyperspan/html": "^1.0.0-alpha",
     "zod": "^4.1.12"
   }
 }

package/src/actions.test.ts

@@ -0,0 +1,147 @@
+import { test, expect, describe } from 'bun:test';
+import { createAction } from './actions';
+import { html, render, type HSHtml } from '@hyperspan/html';
+import { createContext } from './server';
+import type { Hyperspan as HS } from './types';
+import * as z from 'zod/v4';
+
+describe('createAction', () => {
+  test('creates an action with a simple form and no schema', async () => {
+    const action = createAction({
+      name: 'test',
+      schema: z.object({
+        name: z.string().min(1, 'Name is required'),
+      }),
+    }).form((c) => {
+      return html`
+          <form>
+            <input type="text" name="name" />
+            <button type="submit">Submit</button>
+          </form>
+        `;
+    }).post(async (c, { data }) => {
+      return c.res.html(`
+          <p>Hello, ${data?.name}!</p>
+        `);
+    });
+
+    expect(action).toBeDefined();
+    expect(action._kind).toBe('hsAction');
+    expect(action._path()).toContain('/__actions/');
+
+    // Test render method
+    const request = new Request('http://localhost:3000/');
+    const context = createContext(request);
+    const rendered = render(action.render(context) as HSHtml);
+
+    expect(rendered).not.toBeNull();
+    const htmlString = rendered;
+    expect(htmlString).toContain('<hs-action');
+    expect(htmlString).toContain('name="name"');
+  });
+
+  test('creates an action with a Zod schema matching form inputs', async () => {
+    const schema = z.object({
+      name: z.string().min(1, 'Name is required'),
+      email: z.email('Invalid email address'),
+    });
+
+    const action = createAction({
+      name: 'test',
+      schema,
+    }).form((c, { data }) => {
+      return html`
+          <form>
+            <input type="text" name="name" />
+            <input type="email" name="email" />
+            <button type="submit">Submit</button>
+          </form>
+        `;
+    }).post(async (c, { data }) => {
+      return c.res.html(`
+        <p>Hello, ${data?.name}!</p>
+        <p>Your email is ${data?.email}.</p>
+      `);
+    });
+
+    expect(action).toBeDefined();
+    expect(action._kind).toBe('hsAction');
+    expect(action._path()).toContain('/__actions/');
+
+    // Test render method
+    const request = new Request('http://localhost:3000/');
+    const context = createContext(request);
+    const rendered = action.render(context);
+
+    expect(rendered).not.toBeNull();
+    const htmlString = render(rendered as unknown as HSHtml);
+    expect(htmlString).toContain('name="name"');
+    expect(htmlString).toContain('name="email"');
+
+    // Test fetch method with POST request to trigger validation
+    const formData = new FormData();
+    formData.append('name', 'John Doe');
+    formData.append('email', 'john@example.com');
+
+    const postRequest = new Request(`http://localhost:3000${action._path()}`, {
+      method: 'POST',
+      body: formData,
+    });
+
+    const response = await action.fetch(postRequest);
+    expect(response).toBeInstanceOf(Response);
+    expect(response.status).toBe(200);
+
+    const responseText = await response.text();
+    expect(responseText).toContain('Hello, John Doe!');
+    expect(responseText).toContain('Your email is john@example.com.');
+  });
+
+  test('re-renders form with error when schema validation fails', async () => {
+    const schema = z.object({
+      name: z.string().min(1, 'Name is required'),
+      email: z.email('Invalid email address'),
+    });
+
+    const action = createAction({
+      name: 'test',
+      schema,
+    }).form((c, { data, error }) => {
+      return html`
+          <form>
+            <input type="text" name="name" value="${data?.name || ''}" />
+            ${error ? html`<div class="error">Validation failed</div>` : ''}
+            <input type="email" name="email" value="${data?.email || ''}" />
+            <button type="submit">Submit</button>
+          </form>
+        `;
+    }).post(async (c, { data }) => {
+      return c.res.html(`
+        <p>Hello, ${data?.name}!</p>
+        <p>Your email is ${data?.email}.</p>
+      `);
+    });
+
+    // Test fetch method with invalid data (missing name, invalid email)
+    const formData = new FormData();
+    formData.append('email', 'not-an-email');
+
+    const postRequest = new Request(`http://localhost:3000${action._route}`, {
+      method: 'POST',
+      body: formData,
+    });
+
+    const response = await action.fetch(postRequest);
+    expect(response).toBeInstanceOf(Response);
+    expect(response.status).toBe(400);
+
+    const responseText = await response.text();
+    // Should re-render the form, not the post handler output
+    expect(responseText).toContain('name="name"');
+    expect(responseText).toContain('name="email"');
+    expect(responseText).toContain('Validation failed');
+    // Should NOT contain the success message from post handler
+    expect(responseText).not.toContain('Hello,');
+  });
+});
+

package/src/actions.ts

@@ -0,0 +1,118 @@
+import { html, HSHtml } from '@hyperspan/html';
+import { createRoute, returnHTMLResponse } from './server';
+import * as z from 'zod/v4';
+import type { Hyperspan as HS } from './types';
+import { assetHash, formDataToJSON } from './utils';
+import * as actionsClient from './client/_hs/hyperspan-actions.client';
+import { renderClientJS } from './client/js';
+
+/**
+ * Actions = Form + route handler
+ * Automatically handles and parses form data
+ *
+ * HOW THIS WORKS:
+ * ---
+ * 1. Renders in any template as initial form markup with action.render()
+ * 2. Binds form onSubmit function to custom client JS handling via <hs-action> web component
+ * 3. Submits form with JavaScript fetch() + FormData as normal POST form submission
+ * 4. All validation and save logic is run on the server
+ * 5. Replaces form content in place with HTML response content from server via the Idiomorph library
+ * 6. Handles any Exception thrown on server as error displayed back to user on the page
+ */
+export function createAction<T extends z.ZodTypeAny>(params: { name: string; schema?: T }): HS.Action<T> {
+  const { name, schema } = params;
+  const path = `/__actions/${assetHash(name)}`;
+
+  let _handler: Parameters<HS.Action<T>['post']>[0] | null = null;
+  let _errorHandler: Parameters<HS.Action<T>['errorHandler']>[0] | null = null;
+
+  const route = createRoute({ path, name })
+    .get((c: HS.Context) => api.render(c))
+    .post(async (c: HS.Context) => {
+      // Parse form data
+      const formData = await c.req.raw.formData();
+      const jsonData = formDataToJSON(formData) as Partial<z.infer<T>>;
+      const schemaData = schema ? schema.safeParse(jsonData) : null;
+      const data = schemaData?.success ? (schemaData.data as Partial<z.infer<T>>) : jsonData;
+      let error: z.ZodError | Error | null = null;
+
+      try {
+        if (schema && schemaData?.error) {
+          throw schemaData.error;
+        }
+
+        if (!_handler) {
+          throw new Error('Action POST handler not set! Every action must have a POST handler.');
+        }
+
+        const response = await _handler(c, { data });
+
+        if (response instanceof Response) {
+          // Replace redirects with special header because fetch() automatically follows redirects
+          // and we want to redirect the user to the actual full page instead
+          if ([301, 302, 307, 308].includes(response.status)) {
+            response.headers.set('X-Redirect-Location', response.headers.get('Location') || '/');
+            response.headers.delete('Location');
+          }
+        }
+
+        return response;
+      } catch (e) {
+        error = e as Error | z.ZodError;
+      }
+
+      if (error && _errorHandler) {
+        const errorHandler = _errorHandler; // Required for TypeScript to infer the correct type after narrowing
+        return await returnHTMLResponse(c, () => errorHandler(c, { data, error }), {
+          status: 400,
+        });
+      }
+
+      return await returnHTMLResponse(c, () => api.render(c, { data, error }), { status: 400 });
+    });
+
+  const api: HS.Action<T> = {
+    _kind: 'hsAction',
+    _config: route._config,
+    _path() {
+      return path;
+    },
+    _form: null,
+    /**
+     * Form to render
+     * This will be wrapped in a <hs-action> web component and submitted via fetch()
+     */
+    form(form: HS.ActionFormHandler<T>) {
+      api._form = form;
+      return api;
+    },
+    /**
+     * Process form data
+     *
+     * Returns result from form processing if successful
+     * Re-renders form with data and error information otherwise
+     */
+    post(handler) {
+      _handler = handler;
+      return api;
+    },
+    /**
+     * Get form renderer method
+     */
+    render(c: HS.Context, props?: HS.ActionProps<T>) {
+      const formContent = api._form ? api._form(c, props || {}) : null;
+      return formContent ? html`<hs-action url="${this._path()}">${formContent}</hs-action>${renderClientJS(actionsClient)}` : null;
+    },
+    errorHandler(handler) {
+      _errorHandler = handler;
+      return api;
+    },
+    middleware(middleware: Array<HS.MiddlewareFunction>) {
+      route.middleware(middleware);
+      return api;
+    },
+    fetch: route.fetch,
+  };
+
+  return api;
+}

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

@@ -0,0 +1,98 @@
+import { Idiomorph } from './idiomorph';
+import { lazyLoadScripts } from './hyperspan-scripts.client';
+
+const actionFormObserver = new MutationObserver((list) => {
+  list.forEach((mutation) => {
+    mutation.addedNodes.forEach((node) => {
+      if (node && ('closest' in node || node instanceof HTMLFormElement)) {
+        bindHSActionForm(
+          (node as HTMLElement).closest('hs-action') as HSAction,
+          node instanceof HTMLFormElement
+            ? node
+            : ((node as HTMLElement | HTMLFormElement).querySelector('form') as HTMLFormElement)
+        );
+      }
+    });
+  });
+});
+
+/**
+ * Server action component to handle the client-side form submission and HTML replacement
+ */
+class HSAction extends HTMLElement {
+  constructor() {
+    super();
+  }
+
+  connectedCallback() {
+    actionFormObserver.observe(this, { childList: true, subtree: true });
+    bindHSActionForm(this, this.querySelector('form') as HTMLFormElement);
+  }
+}
+window.customElements.define('hs-action', HSAction);
+
+/**
+ * Bind the form inside an hs-action element to the action URL and submit handler
+ */
+function bindHSActionForm(hsActionElement: HSAction, form: HTMLFormElement) {
+  if (!hsActionElement || !form) {
+    return;
+  }
+
+  form.setAttribute('action', hsActionElement.getAttribute('url') || '');
+  const submitHandler = (e: Event) => {
+    e.preventDefault();
+    formSubmitToRoute(e, form as HTMLFormElement, {
+      afterResponse: () => bindHSActionForm(hsActionElement, form),
+    });
+    form.removeEventListener('submit', submitHandler);
+  };
+  form.addEventListener('submit', submitHandler);
+}
+
+/**
+ * Submit form data to route and replace contents with response
+ */
+type TFormSubmitOptons = { afterResponse: () => any };
+function formSubmitToRoute(e: Event, form: HTMLFormElement, opts: TFormSubmitOptons) {
+  const formData = new FormData(form);
+  const formUrl = form.getAttribute('action') || '';
+  const method = form.getAttribute('method')?.toUpperCase() || 'POST';
+  const headers = {
+    Accept: 'text/html',
+    'X-Request-Type': 'partial',
+  };
+
+  const hsActionTag = form.closest('hs-action');
+  const submitBtn = form.querySelector('button[type=submit],input[type=submit]');
+  if (submitBtn) {
+    submitBtn.setAttribute('disabled', 'disabled');
+  }
+
+  fetch(formUrl, { body: formData, method, headers })
+    .then((res: Response) => {
+      // Look for special header that indicates a redirect.
+      // fetch() automatically follows 3xx redirects, so we need to handle this manually to redirect the user to the full page
+      if (res.headers.has('X-Redirect-Location')) {
+        const newUrl = res.headers.get('X-Redirect-Location');
+        if (newUrl) {
+          window.location.assign(newUrl);
+        }
+        return '';
+      }
+
+      return res.text();
+    })
+    .then((content: string) => {
+      // No content = DO NOTHING (redirect or something else happened)
+      if (!content) {
+        return;
+      }
+
+      const target = content.includes('<html') ? window.document.body : hsActionTag || form;
+
+      Idiomorph.morph(target, content);
+      opts.afterResponse && opts.afterResponse();
+      lazyLoadScripts();
+    });
+}

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

@@ -0,0 +1,31 @@
+/**
+ * Intersection observer for lazy loading <script> tags
+ */
+const lazyLoadScriptObserver = new IntersectionObserver(
+  (entries, observer) => {
+    entries
+      .filter((entry) => entry.isIntersecting)
+      .forEach((entry) => {
+        observer.unobserve(entry.target);
+        // @ts-ignore
+        if (entry.target.children[0]?.content) {
+          // @ts-ignore
+          entry.target.replaceWith(entry.target.children[0].content);
+        }
+      });
+  },
+  { rootMargin: '0px 0px -200px 0px' }
+);
+
+/**
+ * Lazy load <script> tags in the current document
+ */
+export function lazyLoadScripts() {
+  document
+    .querySelectorAll('div[data-loading=lazy]')
+    .forEach((el) => lazyLoadScriptObserver.observe(el));
+}
+
+window.addEventListener('load', () => {
+  lazyLoadScripts();
+});

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

@@ -0,0 +1,94 @@
+import { Idiomorph } from './idiomorph';
+import { lazyLoadScripts } from './hyperspan-scripts.client';
+
+/**
+ * Used for streaming content from the server to the client.
+ */
+function htmlAsyncContentObserver() {
+  if (typeof MutationObserver != 'undefined') {
+    // Hyperspan - Async content loader
+    // Puts streamed content in its place immediately after it is added to the DOM
+    const asyncContentObserver = new MutationObserver((list) => {
+      const asyncContent = list
+        .map((mutation) =>
+          Array.from(mutation.addedNodes).find((node: any) => {
+            if (!node || !node?.id || typeof node.id !== 'string') {
+              return false;
+            }
+            return node.id?.startsWith('async_loading_') && node.id?.endsWith('_content');
+          })
+        )
+        .filter((node: any) => node);
+
+      asyncContent.forEach((templateEl: any) => {
+        try {
+          // Also observe for content inside the template content (shadow DOM is separate)
+          asyncContentObserver.observe(templateEl.content, { childList: true, subtree: true });
+
+          const slotId = templateEl.id.replace('_content', '');
+          const slotEl = document.getElementById(slotId);
+
+          if (slotEl) {
+            // Content AND slot are present - let's insert the content into the slot
+            // Ensure the content is fully done streaming in before inserting it into the slot
+            waitForContent(templateEl.content, (el2) => {
+              return Array.from(el2.childNodes).find(
+                (node) => node.nodeType === Node.COMMENT_NODE && node.nodeValue === 'end'
+              );
+            })
+              .then((endComment) => {
+                templateEl.content.removeChild(endComment);
+                const content = templateEl.content.cloneNode(true);
+                Idiomorph.morph(slotEl, content);
+                templateEl.parentNode.removeChild(templateEl);
+                lazyLoadScripts();
+              })
+              .catch(console.error);
+          } else {
+            // Slot is NOT present - wait for it to be added to the DOM so we can insert the content into it
+            waitForContent(document.body, () => {
+              return document.getElementById(slotId);
+            }).then((slotEl) => {
+              Idiomorph.morph(slotEl, templateEl.content.cloneNode(true));
+              lazyLoadScripts();
+            });
+          }
+        } catch (e) {
+          console.error(e);
+        }
+      });
+    });
+    asyncContentObserver.observe(document.body, { childList: true, subtree: true });
+  }
+}
+htmlAsyncContentObserver();
+
+/**
+ * Wait until ALL of the content inside an element is present from streaming in.
+ * Large chunks of content can sometimes take more than a single tick to write to DOM.
+ */
+async function waitForContent(
+  el: HTMLElement,
+  waitFn: (
+    node: HTMLElement
+  ) => HTMLElement | HTMLTemplateElement | Node | ChildNode | null | undefined,
+  options: { timeoutMs?: number; intervalMs?: number } = { timeoutMs: 10000, intervalMs: 20 }
+): Promise<HTMLElement | HTMLTemplateElement | Node | ChildNode | null | undefined> {
+  return new Promise((resolve, reject) => {
+    let timeout: NodeJS.Timeout;
+    const interval = setInterval(() => {
+      const content = waitFn(el);
+      if (content) {
+        if (timeout) {
+          clearTimeout(timeout);
+        }
+        clearInterval(interval);
+        resolve(content);
+      }
+    }, options.intervalMs || 20);
+    timeout = setTimeout(() => {
+      clearInterval(interval);
+      reject(new Error(`[Hyperspan] Timeout waiting for end of streaming content ${el.id}`));
+    }, options.timeoutMs || 10000);
+  });
+}

package/src/client/js.ts

@@ -1,6 +1,4 @@
 import { html } from '@hyperspan/html';
-import type { Hyperspan as HS } from '../types';
-
 
 export const JS_PUBLIC_PATH = '/_hs/js';
 export const JS_ISLAND_PUBLIC_PATH = '/_hs/js/islands';
@@ -60,23 +58,4 @@ export function functionToString(fn: any) {
   }
 
   return str;
-}
-
-/**
- * Island defaults
- */
-export const ISLAND_DEFAULTS: () => HS.ClientIslandOptions = () => ({
-  ssr: true,
-  loading: undefined,
-});
-
-export function renderIsland(Component: any, props: any, options = ISLAND_DEFAULTS()) {
-  // Render island with its own logic
-  if (Component.__HS_ISLAND?.render) {
-    return html.raw(Component.__HS_ISLAND.render(props, options));
-  }
-
-  throw new Error(
-    `Module ${Component.name} was not loaded with an island plugin! Did you forget to install an island plugin and add it to the 'islandPlugins' option in your hyperspan.config.ts file?`
-  );
 }