npm - @formbox/htmx - Versions diffs - 0.4.0 → 0.4.2 - Mend

@formbox/htmx 0.4.0 → 0.4.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (4) hide show

package/README.md CHANGED Viewed

@@ -9,10 +9,10 @@ React, hydrate React, or manage MobX.
 The main API is built around a short-lived renderer instance:
 ```ts
-import { QuestionnaireRenderer, loadNativeTemplates } from "@formbox/htmx";
+import { QuestionnaireRenderer, loadDefaultTemplates } from "@formbox/htmx";
 const route = "/questionnaire";
-const templates = await loadNativeTemplates();
+const templates = await loadDefaultTemplates();
 const renderer = new QuestionnaireRenderer({
   token: "encounter-questionnaire",
   templates,
@@ -55,9 +55,9 @@ field encoding and parses the submitted payload in `renderer.process()`.
 ## Basic Integration
 ```ts
-import { QuestionnaireRenderer, loadNativeTemplates } from "@formbox/htmx";
+import { QuestionnaireRenderer, loadDefaultTemplates } from "@formbox/htmx";
-const templates = await loadNativeTemplates();
+const templates = await loadDefaultTemplates();
 async function renderQuestionnaire(request: Request): Promise<Response> {
   const route = "/questionnaire";
@@ -90,6 +90,72 @@ async function renderQuestionnaire(request: Request): Promise<Response> {
 }
 ```
+## HTMX Integration
+The renderer does not own your page shell. If a POST should update more than
+the form itself, such as a status label or a rendered `QuestionnaireResponse`
+preview beside the form, target an application-owned wrapper and return that
+same wrapper for HTMX requests.
+For dynamic questionnaires, prefer morphdom swaps so focus and nearby DOM state
+survive server-rendered updates better than plain `outerHTML` replacement:
+```ts
+import {
+  compileTemplates,
+  loadDefaultTemplates,
+  loadTemplates,
+} from "@formbox/htmx";
+const templates = {
+  ...(await loadDefaultTemplates()),
+  ...(await loadTemplates("./questionnaire-templates")),
+  ...compileTemplates({
+    Form: `
+      <form{{{attrs attributes}}} hx-target="#questionnaire-app" hx-swap="morphdom">
+        {{{fields}}}
+      </form>
+    `,
+  }),
+};
+async function handler(request: Request): Promise<Response> {
+  const rendered = await renderQuestionnaire(request);
+  const body =
+    request.headers.get("hx-request") === "true"
+      ? questionnaireApp(rendered)
+      : layout(questionnaireApp(rendered));
+  return html(body);
+}
+function questionnaireApp(rendered: {
+  form: string;
+  response: unknown;
+}): string {
+  return `
+    <div id="questionnaire-app">
+      ${rendered.form}
+      <pre>${JSON.stringify(rendered.response, null, 2)}</pre>
+    </div>
+  `;
+}
+```
+Include the HTMX morphdom extension in the application shell:
+```html
+<script src="https://unpkg.com/morphdom@2.7.8/dist/morphdom-umd.min.js"></script>
+<script src="https://unpkg.com/htmx-ext-morphdom-swap@2.0.0/morphdom-swap.js"></script>
+<body hx-ext="morphdom-swap">
+  <div id="questionnaire-app">...</div>
+</body>
+```
+Use the default form swap when the form is the only dynamic region. Use an
+application wrapper when the result of `renderer.process(formData)` affects
+nearby UI outside the form.
 ## Lifecycle
 Create one renderer instance for one request/render cycle:
@@ -129,8 +195,8 @@ const renderer = new QuestionnaireRenderer({
 `questionnaireResponse` is optional initial state.
 `token` is required and must be unique for each rendered form on the same page.
-`templates` is required; call `await loadNativeTemplates()` for the built-in
-file templates, or merge those templates with application overrides.
+`templates` is required; call `await loadDefaultTemplates()` for the package
+defaults, or merge those templates with application overrides.
 ### `renderer.process(formData)`
@@ -182,10 +248,10 @@ Use a custom `Form` template when the application needs to add shell markup or
 adjust attributes:
 ```ts
-import { compileTemplates, loadNativeTemplates } from "@formbox/htmx";
+import { compileTemplates, loadDefaultTemplates } from "@formbox/htmx";
 const templates = {
-  ...(await loadNativeTemplates()),
+  ...(await loadDefaultTemplates()),
   ...compileTemplates({
     Form: `
       <form{{{attrs attributes}}}>
@@ -245,22 +311,22 @@ const templates = compileTemplates({
 });
 ```
-Load the native templates explicitly:
+Load the default templates explicitly:
 ```ts
-import { loadNativeTemplates } from "@formbox/htmx";
+import { loadDefaultTemplates } from "@formbox/htmx";
-const templates = await loadNativeTemplates();
+const templates = await loadDefaultTemplates();
 ```
 If you prefer overrides as files, load a directory of `*.html.hbs` files and
-merge the result with the native templates:
+merge the result with the default templates:
 ```ts
-import { loadNativeTemplates, loadTemplates } from "@formbox/htmx";
+import { loadDefaultTemplates, loadTemplates } from "@formbox/htmx";
 const templates = {
-  ...(await loadNativeTemplates()),
+  ...(await loadDefaultTemplates()),
   ...(await loadTemplates("./questionnaire-templates")),
 };
 ```
@@ -285,7 +351,7 @@ Available Handlebars helpers:
 Use triple braces for renderer-provided HTML slots such as `fields`, `children`,
 `label`, `errors`, and `customOptionForm`.
-Native templates and user templates use the same data shape. The package does
+Default templates and user templates use the same data shape. The package does
 not keep a separate JSX fallback path.
 ### `renderer.getQuestionnaireResponse()`

package/dist/index.d.ts CHANGED Viewed

@@ -298,7 +298,7 @@ export declare type LinkTemplateProperties = Omit<TemplateBase<LinkProperties>,
     readonly children: string;
 };
-export declare function loadNativeTemplates(): Promise<RequiredTemplates>;
+export declare function loadDefaultTemplates(): Promise<RequiredTemplates>;
 export declare function loadTemplates(directory: string | URL): Promise<Templates>;

package/dist/index.js CHANGED Viewed

@@ -59781,7 +59781,7 @@ function compileTemplates(sources) {
     })
   );
 }
-async function loadNativeTemplates() {
+async function loadDefaultTemplates() {
   const templates = await loadTemplates(
     new URL(
       /* @vite-ignore */
@@ -59791,7 +59791,7 @@ async function loadNativeTemplates() {
   );
   const missing = templateNames.filter((name) => templates[name] === void 0);
   if (missing.length > 0) {
-    throw new Error(`Missing native template files: ${missing.join(", ")}`);
+    throw new Error(`Missing default template files: ${missing.join(", ")}`);
   }
   return templates;
 }
@@ -62382,6 +62382,6 @@ export {
   compileTemplate,
   compileTemplates,
   htmlAttributes,
-  loadNativeTemplates,
+  loadDefaultTemplates,
   loadTemplates
 };

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@formbox/htmx",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "description": "Server-rendered HTMX HTML renderer for Formbox FHIR Questionnaires",
   "private": false,
   "type": "module",