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 { Alepha, Static, TObject, TSchema } from "alepha";
import { InputHTMLAttributes, ReactNode } from "react";
import * as _alepha_logger0 from "alepha/logger";

//#region src/services/FormModel.d.ts
declare class FormModel<T extends TObject> {
  readonly id: string;
  protected readonly options: FormCtrlOptions<T>;
  protected readonly log: _alepha_logger0.Logger;
  protected readonly alepha: Alepha;
  protected readonly values: Record<string, any>;
  input: SchemaToInput<T>;
  constructor(id: string, options: FormCtrlOptions<T>);
  readonly onSubmit: (event: FormEventLike) => Promise<void>;
  protected parseValuesFromFormElement<T extends TObject>(options: FormCtrlOptions<T>, store: Record<string, any>): Record<string, any>;
  protected getValueFromInputObject<T extends TObject>(options: FormCtrlOptions<T>, values: Record<string, any>, key: string, value: FormDataEntryValue): void;
  protected createProxyFromSchema<T extends TObject>(options: FormCtrlOptions<T>, schema: TSchema, context: {
    parent: string;
    store: Record<string, any>;
  }): SchemaToInput<T>;
  protected createInputFromSchema<T extends TObject>(name: keyof Static<T> & string, options: FormCtrlOptions<T>, schema: TObject, required: boolean, context: {
    parent: string;
    store: Record<string, any>;
  }): InputField;
  /**
   * Convert an input value from HTML to the correct type based on the schema.
   */
  protected getValueFromInput(input: FormDataEntryValue, schema: TSchema): any;
  protected valueToInputEntry(value: any): string | number | boolean;
}
type SchemaToInput<T extends TObject> = { [K in keyof T["properties"]]: T["properties"][K] extends TObject ? SchemaToInput<T["properties"][K]> : InputField };
interface FormEventLike {
  currentTarget: any;
  preventDefault: () => void;
  stopPropagation: () => void;
}
interface InputField {
  path: string;
  required: boolean;
  props: InputHTMLAttributesLike;
  schema: TSchema;
  set: (value: any) => void;
  form: FormModel<any>;
}
type InputHTMLAttributesLike = Pick<InputHTMLAttributes<unknown>, "id" | "name" | "type" | "value" | "defaultValue" | "required" | "maxLength" | "minLength" | "aria-label"> & {
  value?: any;
  defaultValue?: any;
  onChange?: (event: any) => void;
};
type FormCtrlOptions<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;
};
//#endregion
//#region src/components/FormState.d.ts
declare const FormState: <T extends TObject>(props: {
  form: FormModel<T>;
  children: (state: {
    loading: boolean;
    dirty: boolean;
  }) => ReactNode;
}) => ReactNode;
//#endregion
//#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: FormCtrlOptions<T>) => FormModel<T>;
//#endregion
//#region src/hooks/useFormState.d.ts
interface UseFormStateReturn<T extends TObject> {
  loading: boolean;
  dirty: boolean;
  values?: T;
  error?: Error;
}
type FormStateEvent = "change" | "submit" | "error";
declare const useFormState: <T extends TObject>(target: FormModel<T> | {
  form: FormModel<T>;
  path: string;
}, events?: FormStateEvent[]) => UseFormStateReturn<T>;
//#endregion
//#region src/index.d.ts
declare module "alepha" {
  interface Hooks {
    "form:change": {
      id: string;
      path: string;
    };
    "form:submit:begin": {
      id: string;
    };
    "form:submit:success": {
      id: string;
    };
    "form:submit:error": {
      id: string;
      error: Error;
    };
    "form:submit:end": {
      id: string;
    };
  }
}
/**
 * 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>;
//#endregion
export { AlephaReactForm, FormCtrlOptions, FormEventLike, FormModel, FormState, FormStateEvent, InputField, InputHTMLAttributesLike, SchemaToInput, UseFormStateReturn, useForm, useFormState };
//# sourceMappingURL=index.d.ts.map