alepha/react/form.d.ts

Alepha is a convention-driven TypeScript framework for building robust, end-to-end type-safe applications, from serverless APIs to full-stack React apps.

import * as _alepha_core0 from "alepha";
import { Static, TObject, TSchema } from "alepha";
import { InputHTMLAttributes } from "react";

//#region src/hooks/useForm.d.ts

/**
 * Custom hook to create a form with validation and field management.
 * This hook uses TypeBox schemas to define the structure and validation rules for the form.
 * It provides a way to handle form submission, field creation, and value management.
 *
 * @example
 * ```tsx
 * import { t } from "alepha";
 *
 * const form = useForm({
 *   schema: t.object({
 *     username: t.string(),
 *     password: t.string(),
 *   }),
 *   handler: (values) => {
 *     console.log("Form submitted with values:", values);
 *   },
 * });
 *
 * return (
 *   <form onSubmit={form.onSubmit}>
 *     <input {...form.input("username")} />
 *     <input {...form.input("password")} />
 *     <button type="submit">Submit</button>
 *   </form>
 * );
 * ```
 */
declare const useForm: <T extends TObject>(options: UseFormOptions<T>) => UseFormReturn<T>;
declare const getValueFromInput: (input: FormDataEntryValue, schema: TSchema) => any;
declare const valueToInputEntry: (value: any) => string | number;
type UseFormOptions<T extends TObject> = {
  /**
   * The schema defining the structure and validation rules for the form.
   * This should be a TypeBox schema object.
   */
  schema: T;
  /**
   * Callback function to handle form submission.
   * This function will receive the parsed and validated form values.
   */
  handler: (values: Static<T>, args: {
    form: HTMLFormElement;
  }) => unknown;
  /**
   * Optional initial values for the form fields.
   * This can be used to pre-populate the form with existing data.
   */
  initialValues?: Static<T>;
  /**
   * Optional function to create custom field attributes.
   * This can be used to add custom validation, styles, or other attributes.
   */
  onCreateField?: (name: keyof Static<T> & string, schema: TSchema) => InputHTMLAttributes<unknown>;
  /**
   * If defined, this will generate a unique ID for each field, prefixed with this string.
   *
   * > "username" with id="form-123" will become "form-123-username".
   *
   * If omitted, IDs will not be generated.
   */
  id?: string;
  onError?: (error: Error, args: {
    form: HTMLFormElement;
  }) => void;
  onChange?: (key: string, value: any, store: Record<string, any>) => void;
};
type UseFormReturn<T extends TObject> = {
  /**
   * Function to handle form submission.
   * This should be attached to the form's onSubmit event.
   *
   * @example
   * ```tsx
   * const form = useForm();
   *
   * return <form onSubmit={form.onSubmit}></form>;
   * ```
   */
  onSubmit?: (event: FormEventLike) => void;
  /**
   * Creates an input field for the specified schema property.
   */
  input: SchemaToInput<T>;
};
type SchemaToInput<T extends TObject> = { [K in keyof T["properties"]]: T["properties"][K] extends TObject ? SchemaToInput<T["properties"][K]> : InputField };
interface FormEventLike {
  currentTarget: HTMLFormElement;
  preventDefault: () => void;
}
interface InputField {
  path: string;
  props: InputHTMLAttributesLike;
  schema: TSchema;
  set: (value: any) => void;
}
type InputHTMLAttributesLike = Pick<InputHTMLAttributes<unknown>, "id" | "name" | "type" | "value" | "defaultValue" | "onChange" | "required" | "maxLength" | "minLength" | "aria-label"> & {
  value?: any;
  defaultValue?: any;
};
//# sourceMappingURL=useForm.d.ts.map
//#endregion
//#region src/index.d.ts
/**
 * React hooks for managing forms in Alepha applications.
 *
 * This module provides a set of hooks to simplify form handling, validation, and submission in React applications built with Alepha.
 *
 * It includes:
 * - `useForm`: A hook for managing form state, validation, and submission.
 *
 * @see {@link useForm}
 * @module alepha.react.form
 */
declare const AlephaReactForm: _alepha_core0.Service<_alepha_core0.Module>;
//# sourceMappingURL=index.d.ts.map

//#endregion
export { AlephaReactForm, FormEventLike, InputField, InputHTMLAttributesLike, SchemaToInput, UseFormOptions, UseFormReturn, getValueFromInput, useForm, valueToInputEntry };
//# sourceMappingURL=index.d.ts.map