diff --git a/README.md b/README.md index f65c77b..b970613 100644 --- a/README.md +++ b/README.md @@ -18,10 +18,7 @@ The `@formkit/inertia` plugin aims to seamlessly integrate Inertia.js with FormK 1. [Installation](#installation) 2. [Usage](#usage) - 1. [Method Calls](#method-calls) - 2. [States](#states) - 3. [Event Functions](#event-functions) -3. [Event Callback Manager](#event-callback-manager) +3. [Addons](#addons) 4. [Roadmap](#roadmap) 5. [Types](#types) @@ -37,17 +34,11 @@ npm install @formkit/inertia ## Usage -To use the Inertia plugin we need to import the `useForm` function from `@formkit/inertia`, call the `useForm` function to receive the `form`, it comes with Inertia method calls, reactive states, the plugin event system, and the FormKit plugin. +To use the Inertia plugin we need to import the `useForm` function from `@formkit/inertia`, call the `useForm` function to receive the `form`, it comes with Inertia's method calls, reactive states, the addons for extensions, and the FormKit plugin. -The `useForm` function can take one optional argument: +The `useForm` function takes one optional argument for the initial fields that will be passed to your form via plugin, it will also return methods like `submit`, `get`, `post`, `put`, `patch` and `delete`. All of these methods will return a suitable function for use as FormKit’s `@submit` handler. -- `initialFields`: The initial fields to be passed to your form. - -### Method Calls - -The `useForm()` composable returns the methods `get`, `post`, `put`, `patch` and `delete`. All of these methods will return a suitable function for use as FormKit’s `@submit` handler. - -The easiest way to use it is by creating a new `const` with the resulting method of your choice: +The easiest way to use it is by creating a new `const` with the resulting method of your choice, and adding the `form.plugin` to the FormKit form `:plugins`: ```html -``` - -The `combine()` function is just a easier way to add multiple events in a single place: - -```html - ``` -

(back to top)

- -## Event Callback Manager - -The `createEventCallbackManager()` composable returns 3 functions `on()`, `combine()` and `execute()`. The `on` function accepts these events `before`, `start`, `progress`, `success`, `error`, `cancel`, `finish`: - -```ts -import { createEventCallbackManager } from '@formkit/ineria' - -const event = createEventCallbackManager() -event.on('before', (visit) => { - console.log(visit) -}) -``` - -As you can see it only gets `visit` as a parameter because `createEventCallbackManager()` was not specified that its events will receive more than that, but you can extend by passing an array of types of parameters to it: - -```ts -import { createEventCallbackManager } from '@formkit/ineria' - -const event = createEventCallbackManager<[node: FormKitNode]>() -event.on('before', (visit, node) => { - console.log(visit, node) -}) -``` - -The `combine()` function allows you to define multiple events in a single block: +If you need a single event callback `useForm()` also returns `on()` directly: -```ts -// addon.ts -import { CombineFunction } from '@formkit/inertia' - -return (on) => { - on('before', (visit, node) => { - console.log(visit, node) - }) +```html + ```

(back to top)

@@ -249,86 +168,34 @@ console.log(result) // returns false ```ts export const useForm: (initialFields?: F | undefined) => { - on: OnFunction<[node: FormKitNode]>; - combine: CombineFunction<[node: FormKitNode]>; + on: (name: T, cb: EventCallback[T]) => void; + addon: (addons: AddonExtension | AddonExtension[]) => void; plugin: (node: FormKitNode) => false | undefined; - get: (url: URL | string, options?: Exclude) => (data: F, node: FormKitNode) => void; - post: (url: URL | string, options?: Exclude) => (data: F, node: FormKitNode) => void; - put: (url: URL | string, options?: Exclude) => (data: F, node: FormKitNode) => void; - patch: (url: URL | string, options?: Exclude) => (data: F, node: FormKitNode) => void; - delete: (url: URL | string, options?: Exclude) => (data: F, node: FormKitNode) => void; - cancel: () => void; node: Ref; dirty: Ref; errors: Ref; + valid: Ref; processing: Ref; progress: Ref; recentlySuccessful: Ref; - valid: Ref; wasSuccessful: Ref; + submit: (method: Method, url: URL | string, options?: Exclude) => (data: F, node: FormKitNode) => void; + get: (url: URL | string, options?: Exclude) => (data: F, node: FormKitNode) => void; + post: (url: URL | string, options?: Exclude) => (data: F, node: FormKitNode) => void; + put: (url: URL | string, options?: Exclude) => (data: F, node: FormKitNode) => void; + patch: (url: URL | string, options?: Exclude) => (data: F, node: FormKitNode) => void; + delete: (url: URL | string, options?: Exclude) => (data: F, node: FormKitNode) => void; + cancel: () => void; } ```
- createEventCallbackManager - -```ts -export const createEventCallbackManager: () => { - events: Partial<{ - [K in keyof EventCallback]: EventCallback[K][]; - }>; - on: >(eventName: T, callback: EventCallback[T]) => void; - combine: (combineCb: (cb: typeof on) => void | ((cb: typeof on) => void)[]) => void; - execute: >(eventName: T, ...params: Parameters[T]>) => ReturnType[T]> | undefined; -} -``` - -
- -
- EventCallback - -```ts -export type EventCallback = { - [K in keyof Omit] - : (...args: [...GlobalEventsMap[K]['parameters'], ...A]) - => K extends 'success' | 'error' - ? Promise | GlobalEventsMap[K]['result'] - : GlobalEventsMap[K]['result']; -} & { - cancelToken: (...args: [{ cancel: () => void }, ...A]) => void; -}; -``` - -
- -
- OnFunction - -```ts -export type OnFunction = ReturnType>['on']; -``` - -
- -
- CombineFunction - -```ts -export type CombineFunction = ReturnType>['combine']; -``` - -
- - - -
- ExecuteFunction + AddonExtension ```ts -export type ExecuteFunction = ReturnType>['execute']; +export type AddonExtension = (on: ReturnType['on']) => void; ```