@hyperspan/framework 0.1.3 → 0.1.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperspan/framework",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "Hyperspan Web Framework",
   "main": "dist/server.js",
   "public": true,
@@ -9,15 +9,19 @@
   },
   "exports": {
     ".": {
-      "types": "./dist/server.d.ts",
+      "types": "./src/server.ts",
       "default": "./dist/server.js"
     },
     "./server": {
-      "types": "./dist/server.d.ts",
+      "types": "./src/server.ts",
       "default": "./dist/server.js"
     },
+    "./actions": {
+      "types": "./src/actions.ts",
+      "default": "./src/actions.ts"
+    },
     "./assets": {
-      "types": "./dist/assets.d.ts",
+      "types": "./src/assets.ts",
       "default": "./dist/assets.js"
     }
   },
@@ -59,7 +63,7 @@
     "typescript": "^5.0.0"
   },
   "dependencies": {
-    "@hyperspan/html": "^0.1.2",
+    "@hyperspan/html": "^0.1.4",
     "@preact/compat": "^18.3.1",
     "hono": "^4.7.4",
     "isbot": "^5.1.25",

package/src/actions.test.ts

@@ -0,0 +1,95 @@
+import z from 'zod';
+import { createAction, THSFormData } from './actions';
+import { describe, it, expect } from 'bun:test';
+import { html, render, type TmplHtml } from '@hyperspan/html';
+import type { Context } from 'hono';
+
+describe('createAction', () => {
+  const formWithNameOnly = ({ data }: THSFormData) => {
+    return html`
+      <form>
+        <p>
+          Name:
+          <input type="text" name="name" value="${data.name || ''}" />
+        </p>
+        <button type="submit">Submit</button>
+      </form>
+    `;
+  };
+
+  describe('with form content', () => {
+    it('should create an action with a form that renders provided data', async () => {
+      const schema = z.object({
+        name: z.string(),
+      });
+      const action = createAction(schema).form(formWithNameOnly);
+
+      const formResponse = render(action.render({ data: { name: 'John' } }) as TmplHtml);
+      expect(formResponse).toContain('value="John"');
+    });
+  });
+
+  describe('when data is valid', () => {
+    it('should run the handler and return the result', async () => {
+      const schema = z.object({
+        name: z.string().nonempty(),
+      });
+      const action = createAction(schema)
+        .form(formWithNameOnly)
+        .handler((c, { data }) => {
+          return html`<div>Thanks for submitting the form, ${data.name}!</div>`;
+        })
+        .error((c, { error }) => {
+          return html`<div>There was an error! ${error?.message}</div>`;
+        });
+
+      // Mock context to run action
+      const mockContext = {
+        req: {
+          formData: async () => {
+            const formData = new FormData();
+            formData.append('name', 'John');
+            return formData;
+          },
+        },
+      } as Context;
+
+      const response = await action.run('POST', mockContext);
+
+      const formResponse = render(response as TmplHtml);
+      expect(formResponse).toContain('Thanks for submitting the form, John!');
+    });
+  });
+
+  describe('when data is invalid', () => {
+    it('should return the content of the form with error', async () => {
+      const schema = z.object({
+        name: z.string().nonempty(),
+      });
+      const action = createAction(schema)
+        .form(formWithNameOnly)
+        .handler((c, { data }) => {
+          return html`<div>Thanks for submitting the form, ${data.name}!</div>`;
+        })
+        .error((c, { error }) => {
+          return html`<div>There was an error! ${error?.message}</div>`;
+        });
+
+      // Mock context to run action
+      const mockContext = {
+        req: {
+          formData: async () => {
+            const formData = new FormData();
+            formData.append('name', ''); // No name = error
+            return formData;
+          },
+        },
+      } as Context;
+
+      const response = await action.run('POST', mockContext);
+
+      const formResponse = render(response as TmplHtml);
+      expect(formResponse).toContain('There was an error!');
+    });
+  });
+});

package/src/actions.ts

@@ -0,0 +1,189 @@
+import { html } from '@hyperspan/html';
+import * as z from 'zod';
+import { HTTPException } from 'hono/http-exception';
+
+import type { THSResponseTypes } from './server';
+import type { Context } from 'hono';
+
+/**
+ * Actions = Form + route handler
+ * Automatically handles and parses form data
+ *
+ * INITIAL IDEA OF HOW THIS WILL WORK:
+ * ---
+ * 1. Renders component as initial form markup for GET request
+ * 2. Bind form onSubmit function to custom client JS handling
+ * 3. Submits form with JavaScript fetch()
+ * 4. Replaces form content with content from server
+ * 5. All validation and save logic is on the server
+ * 6. Handles any Exception thrown on server as error displayed in client
+ */
+export interface HSAction<T extends z.ZodTypeAny> {
+  _kind: string;
+  form(renderForm: (data: z.infer<T>) => THSResponseTypes): HSAction<T>;
+  handler(handler: (c: Context, { data }: { data: z.infer<T> }) => THSResponseTypes): HSAction<T>;
+  error(
+    handler: (
+      c: Context,
+      { data, error }: { data: z.infer<T>; error?: z.ZodError | Error }
+    ) => THSResponseTypes
+  ): HSAction<T>;
+  render(props?: { data: z.infer<T>; error?: z.ZodError | Error }): THSResponseTypes;
+  run(method: 'GET' | 'POST', c: Context): Promise<THSResponseTypes>;
+}
+
+export function createAction<T extends z.ZodTypeAny>(schema: T | null = null) {
+  let _handler: Parameters<HSAction<T>['handler']>[0] | null = null,
+    _form: Parameters<HSAction<T>['form']>[0] | null = null,
+    _errorHandler: Parameters<HSAction<T>['error']>[0] | null = null;
+
+  const api: HSAction<T> = {
+    _kind: 'hsAction',
+    form(renderForm) {
+      _form = renderForm;
+      return api;
+    },
+
+    /**
+     * Process form data
+     *
+     * Returns result from form processing if successful
+     * Re-renders form with data and error information otherwise
+     */
+    handler(handler) {
+      _handler = handler;
+      return api;
+    },
+
+    error(handler) {
+      _errorHandler = handler;
+      return api;
+    },
+
+    /**
+     * Get form renderer method
+     */
+    render(data) {
+      const form = _form ? _form(data || { data: {} }) : null;
+      return form ? html`<hs-action>${form}</hs-action>` : null;
+    },
+
+    /**
+     * Run action
+     *
+     * Returns result from form processing if successful
+     * Re-renders form with data and error information otherwise
+     */
+    async run(method: 'GET' | 'POST', c: Context) {
+      if (method === 'GET') {
+        return api.render();
+      }
+
+      if (method !== 'POST') {
+        throw new HTTPException(405, { message: 'Actions only support GET and POST requests' });
+      }
+
+      const formData = await c.req.formData();
+      const jsonData = formDataToJSON(formData);
+      const schemaData = schema ? schema.safeParse(jsonData) : null;
+      const data = schemaData?.success ? (schemaData.data as z.infer<T>) : {};
+      let error: z.ZodError | Error | null = null;
+
+      try {
+        if (schema && schemaData?.error) {
+          throw schemaData.error;
+        }
+
+        if (!_handler) {
+          throw new Error('Action handler not set! Every action must have a handler.');
+        }
+
+        return _handler(c, { data });
+      } catch (e) {
+        error = e as Error | z.ZodError;
+      }
+
+      if (error && _errorHandler) {
+        return _errorHandler(c, { data, error });
+      }
+
+      return api.render({ data, error });
+    },
+  };
+
+  return api;
+}
+
+/**
+ * Form route handler helper
+ */
+export type THSHandlerResponse = (context: Context) => THSResponseTypes | Promise<THSResponseTypes>;
+
+/**
+ * Return JSON data structure for a given FormData object
+ * Accounts for array fields (e.g. name="options[]" or <select multiple>)
+ *
+ * @link https://stackoverflow.com/a/75406413
+ */
+export function formDataToJSON(formData: FormData): Record<string, string | string[]> {
+  let object = {};
+
+  /**
+   * Parses FormData key xxx`[x][x][x]` fields into array
+   */
+  const parseKey = (key: string) => {
+    const subKeyIdx = key.indexOf('[');
+
+    if (subKeyIdx !== -1) {
+      const keys = [key.substring(0, subKeyIdx)];
+      key = key.substring(subKeyIdx);
+
+      for (const match of key.matchAll(/\[(?<key>.*?)]/gm)) {
+        if (match.groups) {
+          keys.push(match.groups.key);
+        }
+      }
+      return keys;
+    } else {
+      return [key];
+    }
+  };
+
+  /**
+   * Recursively iterates over keys and assigns key/values to object
+   */
+  const assign = (keys: string[], value: FormDataEntryValue, object: any): void => {
+    const key = keys.shift();
+
+    // When last key in the iterations
+    if (key === '' || key === undefined) {
+      return object.push(value);
+    }
+
+    if (Reflect.has(object, key)) {
+      // If key has been found, but final pass - convert the value to array
+      if (keys.length === 0) {
+        if (!Array.isArray(object[key])) {
+          object[key] = [object[key], value];
+          return;
+        }
+      }
+      // Recurse again with found object
+      return assign(keys, value, object[key]);
+    }
+
+    // Create empty object for key, if next key is '' do array instead, otherwise set value
+    if (keys.length >= 1) {
+      object[key] = keys[0] === '' ? [] : {};
+      return assign(keys, value, object[key]);
+    } else {
+      object[key] = value;
+    }
+  };
+
+  for (const pair of formData.entries()) {
+    assign(parseKey(pair[0]), pair[1], object);
+  }
+
+  return object;
+}

package/src/clientjs/hyperspan-client.ts

@@ -1,5 +1,5 @@
-import {html} from '@hyperspan/html';
-import {Idiomorph} from './idiomorph.esm';
+import { html } from '@hyperspan/html';
+import { Idiomorph } from './idiomorph.esm';
 
 /**
  * Used for streaming content from the server to the client.
@@ -20,7 +20,7 @@ function htmlAsyncContentObserver() {
       asyncContent.forEach((el: any) => {
         try {
           // Also observe child nodes for nested async content
-          asyncContentObserver.observe(el.content, {childList: true, subtree: true});
+          asyncContentObserver.observe(el.content, { childList: true, subtree: true });
 
           const slotId = el.id.replace('_content', '');
           const slotEl = document.getElementById(slotId);
@@ -41,10 +41,71 @@ function htmlAsyncContentObserver() {
         }
       });
     });
-    asyncContentObserver.observe(document.body, {childList: true, subtree: true});
+    asyncContentObserver.observe(document.body, { childList: true, subtree: true });
   }
 }
 htmlAsyncContentObserver();
 
+/**
+ * Server action component to handle the client-side form submission and HTML replacement
+ */
+class HSAction extends HTMLElement {
+  constructor() {
+    super();
+  }
+
+  // Element is mounted in the DOM
+  connectedCallback() {
+    const form = this.querySelector('form');
+
+    if (form) {
+      form.addEventListener('submit', (e) => {
+        formSubmitToRoute(e, form as HTMLFormElement);
+      });
+    }
+  }
+}
+window.customElements.define('hs-action', HSAction);
+
+/**
+ * Submit form data to route and replace contents with response
+ */
+function formSubmitToRoute(e: Event, form: HTMLFormElement) {
+  e.preventDefault();
+
+  const formUrl = form.getAttribute('action') || '';
+  const formData = new FormData(form);
+  const method = form.getAttribute('method')?.toUpperCase() || 'POST';
+
+  let response: Response;
+
+  fetch(formUrl, { body: formData, method })
+    .then((res: Response) => {
+      // @TODO: Handle redirects with some custom server thing?
+      // This... actually won't work, because fetch automatically follows all redirects (a 3xx response will never be returned to the client)
+      const isRedirect = [301, 302].includes(res.status);
+
+      // Is response a redirect? If so, let's follow it in the client!
+      if (isRedirect) {
+        const newUrl = res.headers.get('Location');
+        if (newUrl) {
+          window.location.assign(newUrl);
+        }
+        return '';
+      }
+
+      response = res;
+      return res.text();
+    })
+    .then((content: string) => {
+      // No content = DO NOTHING (redirect or something else happened)
+      if (!content) {
+        return;
+      }
+
+      Idiomorph.morph(form, content);
+    });
+}
+
 // @ts-ignore
 window.html = html;