Merge pull request #62 from x0k/create-sveltekit-form

Create sveltekit form API

Author: x0k

.changeset/gorgeous-forks-lie.md

@@ -0,0 +1,5 @@
+---
+"@sjsf/sveltekit": minor
+---
+
+Allow usage of separators in additional property key inputs

.changeset/pink-kiwis-fry.md

@@ -0,0 +1,5 @@
+---
+"docs": patch
+---
+
+Update SvelteKit integration guide

.changeset/popular-trainers-lick.md

@@ -0,0 +1,5 @@
+---
+"@sjsf/sveltekit": minor
+---
+
+Add `SvelteKitForm` component

.changeset/warm-actors-compare.md

@@ -0,0 +1,5 @@
+---
+"@sjsf/form": patch
+---
+
+Fix nested additional properties id's inference

.vscode/launch.json

@@ -30,18 +30,18 @@
         "<node_internals>/**",
         "**/node_modules/**"
       ],
-      "program": "${workspaceRoot}/packages/sveltekit-integration/node_modules/vitest/vitest.mjs",
+      "program": "${workspaceRoot}/packages/sveltekit/node_modules/vitest/vitest.mjs",
       "args": [
         "run",
         "../../${relativeFile}",
         "-r",
-        "${workspaceRoot}/packages/sveltekit-integration/"
+        "${workspaceRoot}/packages/sveltekit/"
       ],
       "env": {
         "NODE_ENV": "development",
         "VITE_TEST": "true"
       },
-      "cwd": "${workspaceRoot}/packages/sveltekit-integration",
+      "cwd": "${workspaceRoot}/packages/sveltekit",
       "smartStep": true,
       "console": "integratedTerminal"
     }

apps/docs/src/content/docs/integrations/_sveltekit-client.api.svelte

@@ -1,29 +1,20 @@
 <script lang="ts">
-  import { Content } from "@sjsf/form";
   import { createValidator2 } from "@sjsf/ajv8-validator";
   import { theme } from "@sjsf/form/basic-theme";
   import { translation } from "@sjsf/form/translations/en";
-  import { useSvelteKitForm, meta } from "@sjsf/sveltekit/client";
+  import { SvelteKitForm, createMeta } from "@sjsf/sveltekit/client";
 
   import type { PageData, ActionData } from "./$types";
 
-  const { form, enhance } = useSvelteKitForm(
-    meta<ActionData, PageData>(),
-    "form",
-    {
-      ...theme,
-      validator: createValidator2(),
-      translation,
-    }
-  );
+  const meta = createMeta<ActionData, PageData, "form">("form");
 </script>
 
-<form
-  use:enhance
-  method="POST"
-  novalidate
-  style="display: flex; flex-direction: column; gap: 1rem"
->
-  <Content {form} />
-  <button type="submit" style="padding: 0.5rem;">Submit</button>
-</form>
+<SvelteKitForm
+  {...theme}
+  {meta}
+  {translation}
+  validator={createValidator2()}
+  onSuccess={console.log}
+  onFailure={console.error}
+  onSubmitError={console.warn}
+/>

apps/docs/src/content/docs/integrations/_sveltekit-flex-client.api.svelte

@@ -0,0 +1,29 @@
+<script lang="ts">
+  import { RawForm, setFromContext } from "@sjsf/form";
+  import { createValidator2 } from "@sjsf/ajv8-validator";
+  import { theme } from "@sjsf/form/basic-theme";
+  import { translation } from "@sjsf/form/translations/en";
+  import {
+    createMeta,
+    createSvelteKitForm,
+    createSvelteKitRequest,
+  } from "@sjsf/sveltekit/client";
+
+  import type { PageData, ActionData } from "./$types.js";
+
+  const meta = createMeta<ActionData, PageData, "form">("form");
+  const request = createSvelteKitRequest(meta, {
+    onSuccess: console.log,
+    onFailure: console.error,
+  });
+  const form = createSvelteKitForm(meta, {
+    ...theme,
+    validator: createValidator2(),
+    translation,
+    onSubmit: request.run,
+    onSubmitError: console.warn,
+  });
+  setFromContext(form.context);
+</script>
+
+<RawForm {form} method="POST" />

apps/docs/src/content/docs/integrations/_sveltekit-server.api.ts

@@ -3,7 +3,7 @@ import { createValidator2 } from "@sjsf/ajv8-validator";
 import {
   initForm,
   makeFormDataParser,
-  validateForm,
+  validateForm2,
 } from "@sjsf/sveltekit/server";
 
 import type { Actions } from "./$types";
@@ -37,15 +37,16 @@ export const load = async () => {
 
 export const actions = {
   default: async ({ request }) => {
+    const data = await parseFormData({
+      schema,
+      request,
+    });
     return {
-      form: validateForm({
+      form: await validateForm2({
+        request,
         schema,
         validator,
-        data: await parseFormData({
-          schema,
-          request,
-        }),
-        sendData: true,
+        data,
       }),
     };
   },

apps/docs/src/content/docs/integrations/sveltekit.mdx

@@ -6,10 +6,12 @@ sidebar:
 
 import { Code, Tabs, TabItem } from "@astrojs/starlight/components";
 import { DEFAULT_ID_SEPARATOR, DEFAULT_PSEUDO_ID_SEPARATOR } from '@sjsf/form';
+import { IDENTIFIABLE_FIELD_ELEMENTS } from '@sjsf/sveltekit'
 
 import Npm from '@/components/npm.astro';
 
 import clientCode from './_sveltekit-client.api.svelte?raw';
+import clientFlexCode from './_sveltekit-flex-client.api.svelte?raw'
 import serverCode from './_sveltekit-server.api.ts?raw';
 
 :::caution
@@ -20,7 +22,7 @@ SvelteKit integration is experimental
 
 Since this is a `Svelte` library, you may want to use it with the `SvelteKit`.
 
-With this package you will be able to perform server-side validation of form data
+With this package you will be able to perform server-side validation of the form data
 even if the user has `JavaScript` disabled.
 
 ## Installation
@@ -29,6 +31,8 @@ even if the user has `JavaScript` disabled.
 
 ## Example
 
+See details in the sections below
+
 <Tabs>
   <TabItem label='+page.svelte' >
     <Code code={clientCode} lang='svelte' />
@@ -41,38 +45,11 @@ even if the user has `JavaScript` disabled.
 ## Server
 
 On the server side you should implement at least one [action](https://svelte.dev/docs/kit/form-actions)
-which will always return the result of `validateForm` function (`redirect` and `error` helpers are allowed).
+which will always return the result of `validateForm2` function (`redirect` and `error` helpers are allowed).
 
 If the form data is passed as `FormData`, you need to create a parser for it.
 
-```typescript
-import { makeFormDataParser, validateForm } from '@sjsf/sveltekit/server';
-
-const validator = createValidator();
-
-const parseFormData = makeFormDataParser({
-	validator
-});
-
-export const actions = {
-  default: async (event) => {
-    const form = validateForm({
-      schema,
-      validator,
-      data: await parseFormData({
-        schema,
-        request,
-      }),
-    })
-    if (!form.isValid) {
-      return fail(400, { form });
-    }
-    return {
-      form,
-    };
-  },
-} satisfies Actions;
-```
+<Code code={serverCode} lang="typescript" />
 
 :::note
 
@@ -101,46 +78,30 @@ The name of the `initForm` function result should match the name from the `actio
 
 ## Client
 
-On the client side you should call `useSvelteKitForm`.
-
-```typescript
-import { useSvelteKitForm, meta } from '@sjsf/sveltekit/client';
-
-import type { PageData, ActionData } from './$types';
+On the client side you can use `SvelteKitForm` component (see example).
+Or use more flexible solution:
 
-const { form, mutation, enhance } = useSvelteKitForm(
-  meta<ActionData, PageData>(), "form", { /* form options */ }
-);
-```
+<Code code={clientFlexCode} lang='svelte' />
 
 :::note
 
-The error type will be inferred from `ActionData` and the form data type from `PageData`.
+The error type will be inferred from the `ActionData` type and the form data type from the `PageData` type.
 
 If you did not use `initForm` in the `load` function,
-the third generic parameter of the `meta` function will be used as the form data type
-(the default is `SchemaValue`).
+the fourth generic parameter of the `createMeta` function will be used as the form data type
+(default type is `SchemaValue`).
 
 :::
 
 According to Svelte documentation your form should always use `POST` requests.
 
-```svelte
-<form use:enhance method="POST" novalidate style="display: flex; flex-direction: column; gap: 1rem">
-  <FormContent bind:value={form.formValue} />
-  <button type="submit" style="padding: 0.5rem;">Submit</button>
-</form>
-```
-
 ### Progressive enhancement
 
-You should always use `enhance` action on your forms.
-
-But if you really want the form to work with `JavaScript` disabled, you should consider the following limitation:
+By default, the form will work even with JavaScript disabled, but you should consider the following limitations of this mode of operation:
 
-- `validateForm` should be called with `sendData: true`
-- Form elements for `oneOf`, `anyOf`, `dependencies`, `additionalProperties` and `additionalItems`
-will not update their state.
+- `validateForm2` should be called with `sendData: true` to persist form data between page updates
+- Form fields for `oneOf`, `anyOf`, `dependencies`, `additionalProperties` and `additionalItems`
+will not expand/switch their state.
 - Some widgets (like multiselect, depends on the theme) may will not work, because they require `JavaScript`.
 - Conversion from `FormData` to `JSON` can happen with data loss.
 This conversion relies on the field names computation algorithm and
@@ -155,8 +116,12 @@ it may lead to ambiguous results if the following conditions are violated:
       - `isPseudoSeparator` - <code>{DEFAULT_PSEUDO_ID_SEPARATOR}</code>
   - If your schema contains `additionalProperties`:
     - Keys of initial object values must not contain the separators.
-    - If you provide some initial value for `additionalProperties` or `JavaScript` is enabled but the form is used without `enhance`:
+    - If you provide some initial value for `additionalProperties` or `JavaScript` is enabled but the raw `form` element is used (without `use:form.enhance`):
       - You should provide `additionalPropertyKeyValidationError` or `additionalPropertyKeyValidator` options to `useSvelteKitForm` for preventing the user to input invalid keys.
+      Additional property name is invalid if:
+        - `additionalProperties` schema is an object or an array schema and name contains `idSeparator`
+        - `additionalProperties` schema is neither an object schema nor an array schema and name has a suffix consisting of a `isPseudoSeparator`
+        and a keyword: {IDENTIFIABLE_FIELD_ELEMENTS.map(el => <><code>{el}</code><span> </span></>)}
   - You may produce these checks at runtime with the `staticAnalysis` and other functions from `@sjsf/form/static-analysis` submodule.
     Functions from this submodule returns an iterable of errors, so you can:
     - Throw an error on the first error or list all errors (in a dev environment)

apps/docs/src/content/docs/migration-guides/current.mdx

@@ -4,6 +4,8 @@ sidebar:
   order: 0
 ---
 
+### @sjsf/form
+
 - Replace `<FormContent bind:value={form.formValue} />` with `<Content {form} />` from `@sjsf/form` package
 
 - Replace `SimpleForm` with `RawForm` from `@sjsf/form` package
@@ -20,8 +22,19 @@ sidebar:
 - Replace `import { omitExtraData2 } from "@sjsf/form/legacy-omit-extra-data"`
   with `import { omitExtraData } from "@sjsf/form/omit-extra-data"`
 
+### @sjsf/sveltekit
+
+- Upgrade SvelteKit package at least up to `2.12.0`
+
+- Migrate from `meta` and `useSvelteKitForm` to `createMeta`, `createSvelteKitRequest` and `createSvelteKitForm`
+  - In simple cases you may use only `createMeta` and `SvelteKitForm` component
+
+- Migrate from `validateForm` to `validateForm2` (support async validators)
+
 ## 1.8.0
 
+### @sjsf/form
+
 - Replace `useForm2` with `createForm3`
 
 - If custom form is used it should call `setFormContext(form.context)`