@alepha/react 0.11.11 → 0.12.0

package/dist/form/index.d.ts

@@ -0,0 +1,211 @@
+import * as alepha0 from "alepha";
+import { Alepha, Static, TObject, TSchema } from "alepha";
+import * as alepha_logger0 from "alepha/logger";
+import { InputHTMLAttributes, ReactNode } from "react";
+
+//#region src/form/services/FormModel.d.ts
+
+/**
+ * FormModel is a dynamic form handler that generates form inputs based on a provided TypeBox schema.
+ * It manages form state, handles input changes, and processes form submissions with validation.
+ *
+ * It means to be injected and used within React components to provide a structured way to create and manage forms.
+ *
+ * @see {@link useForm}
+ */
+declare class FormModel<T extends TObject> {
+  readonly id: string;
+  readonly options: FormCtrlOptions<T>;
+  protected readonly log: alepha_logger0.Logger;
+  protected readonly alepha: Alepha;
+  protected readonly values: Record<string, any>;
+  protected submitInProgress: boolean;
+  input: SchemaToInput<T>;
+  get submitting(): boolean;
+  constructor(id: string, options: FormCtrlOptions<T>);
+  get element(): HTMLFormElement;
+  get currentValues(): Record<string, any>;
+  get props(): {
+    id: string;
+    noValidate: boolean;
+    onSubmit: (ev?: FormEventLike) => void;
+    onReset: (event: FormEventLike) => Promise<void>;
+  };
+  readonly reset: (event: FormEventLike) => Promise<void>;
+  readonly submit: () => Promise<void>;
+  /**
+   * Restructures flat keys like "address.city" into nested objects like { address: { city: ... } }
+   * Values are already typed from onChange, so no conversion is needed.
+   */
+  protected restructureValues(store: Record<string, any>): Record<string, any>;
+  /**
+   * Helper to restructure a flat key like "address.city" into nested object structure.
+   * The value is already typed, so we just assign it to the nested path.
+   */
+  protected restructureNestedValue(values: Record<string, any>, key: string, value: any): 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 to the correct type based on the schema.
+   * Handles raw DOM values (strings, booleans from checkboxes, Files, etc.)
+   */
+  protected getValueFromInput(input: any, 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 {
+  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" | "autoComplete"> & {
+  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?: Partial<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;
+  onReset?: () => void;
+};
+//#endregion
+//#region src/form/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/form/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.text(),
+ *     password: t.text(),
+ *   }),
+ *   handler: (values) => {
+ *     console.log("Form submitted with values:", values);
+ *   },
+ * });
+ *
+ * return (
+ *   <form {...form.props}>
+ *     <input {...form.input.username.props} />
+ *     <input {...form.input.password.props} />
+ *     <button type="submit">Submit</button>
+ *   </form>
+ * );
+ * ```
+ */
+declare const useForm: <T extends TObject>(options: FormCtrlOptions<T>, deps?: any[]) => FormModel<T>;
+//#endregion
+//#region src/form/hooks/useFormState.d.ts
+interface UseFormStateReturn {
+  loading: boolean;
+  dirty: boolean;
+  values?: Record<string, any>;
+  error?: Error;
+}
+declare const useFormState: <T extends TObject, Keys extends keyof UseFormStateReturn>(target: FormModel<T> | {
+  form: FormModel<T>;
+  path: string;
+}, _events?: Keys[]) => Pick<UseFormStateReturn, Keys>;
+//#endregion
+//#region src/form/index.d.ts
+declare module "alepha" {
+  interface Hooks {
+    "form:change": {
+      id: string;
+      path: string;
+      value: any;
+    };
+    "form:reset": {
+      id: string;
+      values: Record<string, any>;
+    };
+    "form:submit:begin": {
+      id: string;
+    };
+    "form:submit:success": {
+      id: string;
+      values: Record<string, any>;
+    };
+    "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: alepha0.Service<alepha0.Module>;
+//#endregion
+export { AlephaReactForm, FormCtrlOptions, FormEventLike, FormModel, FormState, InputField, InputHTMLAttributesLike, SchemaToInput, UseFormStateReturn, useForm, useFormState };
+//# sourceMappingURL=index.d.ts.map

package/dist/form/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/form/services/FormModel.ts","../../src/form/components/FormState.tsx","../../src/form/hooks/useForm.ts","../../src/form/hooks/useFormState.ts","../../src/form/index.ts"],"sourcesContent":[],"mappings":"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"}