Merge pull request #24 from x0k/async-action

Add `useMutation` API

.changeset/tender-terms-press.md

@@ -0,0 +1,5 @@
+---
+"docs": minor
+---
+
+Add generic backend integration guide

.changeset/yellow-horses-dance.md

@@ -0,0 +1,5 @@
+---
+"@sjsf/form": minor
+---
+
+Add `useAction` API

apps/docs/astro.config.mjs

@@ -29,6 +29,10 @@ export default defineConfig({
           label: "Themes",
           autogenerate: { directory: "themes" },
         },
+        {
+          label: "Integrations",
+          autogenerate: { directory: "integrations" },
+        },
         {
           label: "Advanced scenarios",
           autogenerate: { directory: "advanced" },

apps/docs/src/content/docs/guides/programmatic-control.mdx

@@ -6,13 +6,13 @@ sidebar:
 
 import { Code, Card } from '@astrojs/starlight/components';
 
-import BindForm from './_programmatic-control.svelte';
-import bindFormCode from './_programmatic-control.svelte?raw';
+import Form from './_programmatic-control.svelte';
+import formCode from './_programmatic-control.svelte?raw';
 
 You can bind to the from element to control it programmatically:
 
-<Code code={bindFormCode} lang="svelte" />
+<Code code={formCode} lang="svelte" />
 
 <Card>
-  <BindForm client:only="svelte" />
+  <Form client:only="svelte" />
 </Card>

apps/docs/src/content/docs/integrations/_generic-backend.svelte

@@ -0,0 +1,62 @@
+<script lang="ts">
+  import { FormContent, SubmitButton } from "@sjsf/form";
+  import { Status, useMutation } from "@sjsf/form/use-mutation.svelte";
+
+  import { useCustomForm } from "@/components/custom-form";
+
+  let isError = $state(false);
+  let duration = $state(0);
+  let data = $state<string>();
+
+  const mutation = useMutation({
+    mutate: (_signal, value: string | undefined = "") =>
+      new Promise<string>((resolve, reject) => {
+        data = undefined;
+        isError = Math.random() > 0.5;
+        duration = Math.random() * 5000;
+        setTimeout(() => {
+          if (isError) {
+            reject(value);
+          } else {
+            resolve(value);
+          }
+        }, duration);
+      }),
+    onSuccess(response) {
+      data = response;
+      form.reset();
+    },
+    onFailure: console.error,
+    delayedMs: 1000,
+    timeoutMs: 3000,
+  });
+
+  const form = useCustomForm({
+    schema: {
+      type: "string",
+    },
+    onSubmit: mutation.run,
+    get disabled() {
+      return mutation.isProcessed;
+    },
+  });
+</script>
+
+<p>
+  Reject: {isError}, delay: {(duration / 1000).toFixed(2)}sec
+</p>
+
+<form use:form.enhance style="display: flex; flex-direction: column; gap: 1rem">
+  <FormContent bind:value={form.formValue} />
+  {#if mutation.isDelayed}
+    <button style="padding: 0.5rem;" disabled>Processed...</button>
+  {:else}
+    <SubmitButton />
+  {/if}
+  {#if data !== undefined}
+    <p>Data: {data}</p>
+  {/if}
+  {#if mutation.state.status === Status.Failed}
+    <p class="text-red-500">Failed: {mutation.state.reason}</p>
+  {/if}
+</form>

apps/docs/src/content/docs/integrations/generic-backend.mdx

@@ -0,0 +1,18 @@
+---
+title: Generic backend
+sidebar:
+  order: 0
+---
+
+import { Card, Code } from '@astrojs/starlight/components'
+
+import Form from './_generic-backend.svelte';
+import formCode from './_generic-backend.svelte?raw';
+
+You can improve the experience of sending data to the server by using the `useAction` hook.
+
+<Code code={formCode} lang="svelte" />
+
+<Card>
+  <Form client:only="svelte" />
+</Card>

mkfile

@@ -24,7 +24,7 @@ f/:
   c:
     pnpm run check
   t:
-    pnpm run test
+    pnpm run test $@
   popd
 
 ds/:

packages/form/package.json

@@ -46,6 +46,7 @@
     "@types/json-schema": "^7.0.15",
     "@types/json-schema-merge-allof": "^0.6.5",
     "deep-freeze-es6": "^3.0.2",
+    "svelte": "catalog:",
     "svelte-check": "catalog:",
     "vite": "catalog:",
     "vitest": "catalog:"
@@ -88,6 +89,10 @@
     "./get-default-form-state": {
       "types": "./dist/get-default-form-state.d.ts",
       "default": "./dist/get-default-form-state.js"
+    },
+    "./use-mutation.svelte": {
+      "types": "./dist/use-mutation.svelte.d.ts",
+      "svelte": "./dist/use-mutation.svelte.js"
     }
   }
 }

packages/form/src/use-mutation.svelte.test.ts

@@ -0,0 +1,134 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { tick } from 'svelte';
+
+import {
+  abortPrevious,
+  forgetPrevious,
+  ignoreNewUntilPreviousIsFinished,
+  Status,
+  useMutation,
+} from "./use-mutation.svelte.js";
+
+describe("useMutation", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+  describe("Status", () => {
+    it("Should correctly update status during success flow", async () => {
+      const mutation = useMutation({
+        mutate: () => Promise.resolve(),
+        delayedMs: 50,
+        timeoutMs: 100,
+      });
+      const promise = mutation.run(undefined);
+      expect(mutation.status).toBe(Status.Processed);
+      await promise;
+      expect(mutation.status).toBe(Status.Success);
+      vi.advanceTimersByTime(50);
+      expect(mutation.status).toBe(Status.Success);
+      vi.advanceTimersByTime(50);
+      expect(mutation.status).toBe(Status.Success);
+    });
+    it("Should correctly update status during error flow", async () => {
+      const mutation = useMutation({
+        mutate: () => Promise.reject(),
+        delayedMs: 50,
+        timeoutMs: 100,
+      });
+      const promise = mutation.run(undefined);
+      expect(mutation.status).toBe(Status.Processed);
+      await promise;
+      expect(mutation.status).toBe(Status.Failed);
+      vi.advanceTimersByTime(50);
+      expect(mutation.status).toBe(Status.Failed);
+      vi.advanceTimersByTime(50);
+      expect(mutation.status).toBe(Status.Failed);
+    });
+    it("Should correctly update statuses: processed -> processed(delayed) -> failed(timeout)", async () => {
+      const mutation = useMutation({
+        mutate: () =>
+          new Promise((resolve) => {
+            setTimeout(() => {
+              resolve(0);
+            }, 100);
+          }),
+        delayedMs: 10,
+        timeoutMs: 50,
+      });
+      mutation.run(undefined);
+      expect(mutation.status).toBe(Status.Processed);
+      expect(mutation.isDelayed).toBe(false);
+      vi.advanceTimersByTime(10);
+      expect(mutation.status).toBe(Status.Processed);
+      expect(mutation.isDelayed).toBe(true);
+      vi.advanceTimersByTime(40);
+      if (mutation.state.status === Status.Failed) {
+        expect(mutation.state.reason).toBe("timeout");
+      } else {
+        expect.fail()
+      }
+      vi.advanceTimersByTime(50);
+      await tick();
+      expect(mutation.status).toBe(Status.Failed);
+    });
+  });
+  describe("Combinator", () => {
+    it("Should ignore new mutation until the previous mutation is completed", async () => {
+      const impl = vi.fn(
+        () =>
+          new Promise((resolve) => {
+            setTimeout(() => {
+              resolve(0);
+            }, 100);
+          })
+      );
+      const mutation = useMutation({
+        mutate: impl,
+        combinator: ignoreNewUntilPreviousIsFinished,
+      });
+      mutation.run(undefined);
+      mutation.run(undefined);
+      vi.advanceTimersByTime(100);
+      await tick();
+      mutation.run(undefined);
+      expect(impl).toBeCalledTimes(2);
+    });
+    it("Should forget previous mutation with 'forgetPrevious' combinator", async () => {
+      let count = 0;
+      const onSuccess = vi.fn();
+      const mutation = useMutation({
+        mutate: () => Promise.resolve(count++),
+        combinator: forgetPrevious,
+        onSuccess,
+      });
+      mutation.run(undefined);
+      await mutation.run(undefined);
+      expect(onSuccess).toBeCalledTimes(1);
+      expect(onSuccess).toBeCalledWith(1);
+    });
+    it("Should abort previous mutation with 'abortPrevious' combinator", async () => {
+      const onAbort = vi.fn();
+      let count = 0;
+      const impl = vi.fn((signal: AbortSignal) => {
+        signal.addEventListener("abort", onAbort);
+        return Promise.resolve(count++);
+      });
+      const onSuccess = vi.fn();
+      const mutation = useMutation({
+        mutate: impl,
+        combinator: abortPrevious,
+        onSuccess,
+      });
+      mutation.run(undefined);
+      mutation.run(undefined);
+      await mutation.run(undefined);
+      expect(onAbort).toBeCalledTimes(2);
+      expect(impl).toBeCalledTimes(3);
+      expect(onSuccess).toBeCalledTimes(1);
+      expect(onSuccess).toBeCalledWith(2);
+    });
+  });
+});