[docs] Add multiple forms guide

Author: x0k

.changeset/soft-rivers-hide.md

@@ -0,0 +1,5 @@
+---
+"docs": minor
+---
+
+Add multiple forms guide

apps/docs/src/content/docs/advanced/custom-form.mdx

@@ -24,9 +24,9 @@ Note that you can simplify the above code if certain restrictions are met:
 
 `Object.setPrototypeOf(options, defaults)`
 
-- If you are sure you will not use getters as options, then use a spread operator instead of `Proxy`:
+- If you are sure you will not use getters as options, then use `Object.assign` instead of `Proxy`:
 
-`{ ...defaults, ...options }`
+`Object.assign(defaults, options)`
 
 :::
 

apps/docs/src/content/docs/guides/_multiple-forms-form.svelte

@@ -0,0 +1,19 @@
+<script lang="ts" generics="T, E">
+  import type { HTMLFormAttributes } from "svelte/elements";
+  import { FormContent, setFromContext, SubmitButton, type FormAPI, type FormContext } from '@sjsf/form';
+
+  interface Props extends HTMLFormAttributes {
+    form: FormAPI<T, E>;
+    ctx: FormContext;
+  }
+
+  const { form, ctx, ...rest }: Props = $props();
+
+  setFromContext(ctx)
+</script>
+
+<form use:form.enhance {...rest}>
+  <!-- svelte-ignore ownership_invalid_binding -->
+  <FormContent bind:value={form.formValue} />
+  <SubmitButton />
+</form>

apps/docs/src/content/docs/guides/_multiple-forms.astro

@@ -0,0 +1,9 @@
+---
+import { ShadowHost } from '@/components/shadow';
+
+import Form from './_multiple-forms.svelte'
+---
+
+<ShadowHost client:only="svelte">
+  <Form client:only="svelte" />
+</ShadowHost>

apps/docs/src/content/docs/guides/_multiple-forms.svelte

@@ -0,0 +1,37 @@
+<script lang="ts">
+  import { createForm2, type Schema } from '@sjsf/form';
+  import { createValidator } from '@sjsf/ajv8-validator';
+  import { translation } from '@sjsf/form/translations/en';
+  import { theme } from '@sjsf/form/basic-theme';
+
+  import Form from './_multiple-forms-form.svelte';
+
+  const schema: Schema = {
+    type: "string"
+  }
+
+  const common = {
+    ...theme,
+    schema,
+    translation,
+    validator: createValidator(),
+    onSubmit: (v: string) => window.alert(v)
+  }
+
+  const [form1, form1Ctx] = createForm2({
+    ...common,
+    initialValue: "foo",
+    idPrefix: "form1",
+  })
+
+  const [form2, form2Ctx] = createForm2({
+    ...common,
+    initialValue: "bar",
+    idPrefix: "form2",
+  })
+</script>
+
+<div style="display: flex; gap: 1rem;">
+  <Form style="display: flex; flex-direction: column; gap: 1rem; flex-grow: 1;" form={form1} ctx={form1Ctx} />
+  <Form style="display: flex; flex-direction: column; gap: 1rem; flex-grow: 1;" form={form2} ctx={form2Ctx} />
+</div>

apps/docs/src/content/docs/guides/multiple-forms.mdx

@@ -0,0 +1,40 @@
+---
+title: Multiple forms
+sidebar:
+  order: 6
+---
+
+import { Code, Tabs, TabItem, Card } from '@astrojs/starlight/components';
+
+import { DEFAULT_ID_PREFIX } from '@sjsf/form'
+
+import Form from './_multiple-forms.astro';
+import formCode from './_multiple-forms.svelte?raw';
+import formComponentCode from './_multiple-forms-form.svelte?raw';
+
+There are a few rules to follow if you want to use multiple forms
+
+## On the same page
+
+You should provide custom `idPrefix` to avoid id collisions in the DOM
+
+The default value of `idPrefix` is <code>{DEFAULT_ID_PREFIX}</code>.
+
+## In one component
+
+Because `useForm2` internally calls `setFormContext`, you can't create multiple forms in one component with it.
+
+But if you really want to create multiple forms in one component, look at `createForm2`.
+
+<Tabs>
+  <TabItem label="_multiple-forms.svelte" >
+    <Code code={formCode} lang='svelte' />
+  </TabItem>
+  <TabItem label="_multiple-forms-form.svelte">
+    <Code code={formComponentCode} lang='svelte' />
+  </TabItem>
+</Tabs>
+
+<Card>
+  <Form />
+</Card>