alepha 0.22.0 → 0.24.0

package/src/react/form/__tests__/useForm.browser.spec.tsx

@@ -1,5 +1,5 @@
 import { fireEvent, render } from "@testing-library/react";
-import { Alepha, t } from "alepha";
+import { Alepha, z } from "alepha";
 import { AlephaLogger } from "alepha/logger";
 import { AlephaContext } from "alepha/react";
 import type { ReactNode } from "react";
@@ -31,13 +31,13 @@ describe("useForm", () => {
     const Form = () => {
       const form = useForm({
         id: "test",
-        schema: t.object({
-          str: t.text(),
-          int: t.integer(),
-          nested: t.object({
-            str: t.text(),
-            another: t.object({
-              level: t.text(),
+        schema: z.object({
+          str: z.text(),
+          int: z.integer(),
+          nested: z.object({
+            str: z.text(),
+            another: z.object({
+              level: z.text(),
             }),
           }),
         }),
@@ -107,14 +107,14 @@ describe("useForm", () => {
     const Form = () => {
       const form = useForm({
         id: "types-test",
-        schema: t.object({
-          name: t.text(),
-          address: t.object({
-            street: t.text(),
-            city: t.text(),
-            country: t.object({
-              code: t.text(),
-              name: t.text(),
+        schema: z.object({
+          name: z.text(),
+          address: z.object({
+            street: z.text(),
+            city: z.text(),
+            country: z.object({
+              code: z.text(),
+              name: z.text(),
             }),
           }),
         }),
@@ -156,12 +156,12 @@ describe("useForm", () => {
     const Form = () => {
       const form = useForm({
         id: "array-test",
-        schema: t.object({
-          tags: t.array(t.text()),
-          contacts: t.array(
-            t.object({
-              name: t.text(),
-              email: t.text(),
+        schema: z.object({
+          tags: z.array(z.text()),
+          contacts: z.array(
+            z.object({
+              name: z.text(),
+              email: z.text(),
             }),
           ),
         }),
@@ -209,8 +209,8 @@ describe("useForm", () => {
     const Form = () => {
       const form = useForm({
         id: "array-set-test",
-        schema: t.object({
-          tags: t.array(t.text()),
+        schema: z.object({
+          tags: z.array(z.text()),
         }),
         handler: (values) => {
           calls.push(values);
@@ -251,11 +251,11 @@ describe("useForm", () => {
     const Form = () => {
       const form = useForm({
         id: "array-objects-test",
-        schema: t.object({
-          contacts: t.array(
-            t.object({
-              name: t.text(),
-              email: t.text(),
+        schema: z.object({
+          contacts: z.array(
+            z.object({
+              name: z.text(),
+              email: z.text(),
             }),
           ),
         }),
@@ -308,18 +308,18 @@ describe("useForm", () => {
     const Form = () => {
       const form = useForm({
         id: "complex-test",
-        schema: t.object({
-          company: t.object({
-            name: t.text(),
-            address: t.object({
-              street: t.text(),
-              city: t.text(),
+        schema: z.object({
+          company: z.object({
+            name: z.text(),
+            address: z.object({
+              street: z.text(),
+              city: z.text(),
             }),
           }),
-          employees: t.array(
-            t.object({
-              name: t.text(),
-              role: t.text(),
+          employees: z.array(
+            z.object({
+              name: z.text(),
+              role: z.text(),
             }),
           ),
         }),
@@ -401,8 +401,8 @@ describe("useForm", () => {
 
       const form = useForm({
         id: "reset-test",
-        schema: t.object({
-          name: t.text(),
+        schema: z.object({
+          name: z.text(),
         }),
         initialValues: saved,
         handler: async (values) => {
@@ -497,9 +497,9 @@ describe("useForm — initialValues stability", () => {
     const Form = () => {
       const form = useForm({
         id: "stability-test",
-        schema: t.object({
-          title: t.text(),
-          priority: t.text(),
+        schema: z.object({
+          title: z.text(),
+          priority: z.text(),
         }),
         // Fresh object reference every render, identical content.
         initialValues: {
@@ -564,7 +564,7 @@ describe("useForm — initialValues stability", () => {
     const Form = () => {
       const form = useForm({
         id: "stress-test",
-        schema: t.object({ value: t.text() }),
+        schema: z.object({ value: z.text() }),
         initialValues: { value: "" },
         handler: (values) => {
           calls.push(values);
@@ -618,9 +618,9 @@ describe("useForm — initialValues stability", () => {
     const Form = () => {
       const form = useForm({
         id: "nested-test",
-        schema: t.object({
-          title: t.text(),
-          meta: t.object({ priority: t.text(), difficulty: t.integer() }),
+        schema: z.object({
+          title: z.text(),
+          meta: z.object({ priority: z.text(), difficulty: z.integer() }),
         }),
         // Both the outer literal AND the nested `meta` are fresh references.
         initialValues: {
@@ -680,9 +680,9 @@ describe("useForm — initialValues stability", () => {
     const Form = () => {
       const form = useForm({
         id: "array-init-test",
-        schema: t.object({
-          title: t.text(),
-          tags: t.array(t.text()),
+        schema: z.object({
+          title: z.text(),
+          tags: z.array(z.text()),
         }),
         // Fresh empty array reference every render — the QuestCreate case
         // for `objectives: []`.
@@ -740,7 +740,7 @@ describe("useForm — initialValues stability", () => {
     const Form = ({ target }: { target: { name: string } }) => {
       const form = useForm({
         id: "swap-test",
-        schema: t.object({ name: t.text() }),
+        schema: z.object({ name: z.text() }),
         initialValues: target,
         handler: () => {},
       });
@@ -793,7 +793,7 @@ describe("useForm — initialValues stability", () => {
     const Form = ({ initial }: { initial?: { name: string } }) => {
       const form = useForm({
         id: "toggle-init-test",
-        schema: t.object({ name: t.text() }),
+        schema: z.object({ name: z.text() }),
         initialValues: initial,
         handler: () => {},
       });
@@ -856,7 +856,7 @@ describe("useForm — initialValues stability", () => {
     const Form = () => {
       const form = useForm({
         id: "burst-test",
-        schema: t.object({ value: t.text() }),
+        schema: z.object({ value: z.text() }),
         initialValues: {},
         handler: () => {},
       });

package/src/react/form/errors/FormValidationError.ts

@@ -10,8 +10,6 @@ export class FormValidationError extends TypeBoxError {
     super({
       message: options.message,
       instancePath: options.path,
-      schemaPath: "",
-      keyword: "not",
       params: {},
     });
   }

package/src/react/form/hooks/useForm.ts

@@ -10,12 +10,12 @@ import { type FormCtrlOptions, FormModel } from "../services/FormModel.ts";
  *
  * @example
  * ```tsx
- * import { t } from "alepha";
+ * import { z } from "alepha";
  *
  * const form = useForm({
- *   schema: t.object({
- *     username: t.text(),
- *     password: t.text(),
+ *   schema: z.object({
+ *     username: z.text(),
+ *     password: z.text(),
  *   }),
  *   handler: (values) => {
  *     console.log("Form submitted with values:", values);
@@ -62,6 +62,21 @@ export const useForm = <T extends TObject>(
     });
   }, deps);
 
+  // The model is memoized once, but callers' handlers close over
+  // render-scoped state ("const [rows, setRows] = useState(...)" then
+  // "handler: () => onNext(rows)"). Invoking the mount-time closure submits
+  // the INITIAL state — edits silently vanish. Keep the callbacks fresh on
+  // every commit so submit always sees the latest render's closures.
+  useEffect(() => {
+    Object.assign(form.options, {
+      handler: options.handler,
+      onError: options.onError,
+      onChange: options.onChange,
+      onReset: options.onReset,
+      onCreateField: options.onCreateField,
+    });
+  });
+
   useEffect(() => {
     // Reference inequality alone is unsafe: callers commonly build the
     // `initialValues` object inline at the top of their render, which yields

package/src/react/form/services/FormModel.ts

@@ -2,10 +2,11 @@ import type { TArray } from "alepha";
 import {
   $inject,
   Alepha,
+  coerceObject,
   type Static,
   type TObject,
   type TSchema,
-  t,
+  z,
 } from "alepha";
 import { $logger } from "alepha/logger";
 import type { InputHTMLAttributes } from "react";
@@ -27,10 +28,6 @@ export class FormModel<T extends TObject> {
 
   public input: SchemaToInput<T>;
 
-  public get submitting(): boolean {
-    return this.submitInProgress;
-  }
-
   constructor(
     public readonly id: string,
     public readonly options: FormCtrlOptions<T>,
@@ -49,7 +46,7 @@ export class FormModel<T extends TObject> {
       // run on whatever's provided; missing fields stay undefined and only the
       // full schema is enforced at submit time.
       const decoded = this.alepha.codec.decode(
-        t.partial(options.schema),
+        options.schema.partial(),
         options.initialValues,
       ) as Record<string, any>;
       Object.assign(this.values, decoded);
@@ -64,36 +61,48 @@ export class FormModel<T extends TObject> {
   }
 
   /**
-   * Extract default values from a TypeBox schema.
-   * Recursively handles nested objects.
+   * Extract default values from a zod object schema.
+   * Recursively handles nested objects, unwrapping optional/nullable/default.
    */
   protected extractSchemaDefaults(
     schema: TObject,
     prefix: string = "",
   ): Record<string, any> {
     const defaults: Record<string, any> = {};
+    const shape = (schema as any).shape as Record<string, any> | undefined;
 
-    if (!schema.properties) {
+    if (!shape) {
       return defaults;
     }
 
-    for (const [key, propSchema] of Object.entries(schema.properties)) {
+    for (const [key, propSchema] of Object.entries(shape)) {
       const fullKey = prefix ? `${prefix}.${key}` : key;
 
-      if ("default" in propSchema && propSchema.default !== undefined) {
-        defaults[fullKey] = propSchema.default;
-      } else if (
-        propSchema &&
-        "type" in propSchema &&
-        propSchema.type === "object" &&
-        "properties" in propSchema
-      ) {
+      // Unwrap optional / nullable / default wrappers to surface a default
+      // value and any nested object schema.
+      let inner: any = propSchema;
+      let defaultValue: unknown;
+      while (inner) {
+        if (z.schema.isDefault(inner)) {
+          const dv = inner._zod.def.defaultValue;
+          defaultValue = typeof dv === "function" ? dv() : dv;
+          break;
+        }
+        if (z.schema.isOptional(inner) || z.schema.isNullable(inner)) {
+          inner = inner.unwrap();
+          continue;
+        }
+        break;
+      }
+
+      if (defaultValue !== undefined) {
+        defaults[fullKey] = defaultValue;
+      } else if (z.schema.isObject(inner)) {
         // Recursively extract defaults from nested objects
-        const nestedDefaults = this.extractSchemaDefaults(
-          propSchema as TObject,
-          fullKey,
+        Object.assign(
+          defaults,
+          this.extractSchemaDefaults(inner as TObject, fullKey),
         );
-        Object.assign(defaults, nestedDefaults);
       }
     }
 
@@ -120,7 +129,7 @@ export class FormModel<T extends TObject> {
     // Same partial-decode rationale as the constructor — initial values may be
     // incomplete; full schema is enforced only at submit time.
     const decoded = this.alepha.codec.decode(
-      t.partial(this.options.schema),
+      this.options.schema.partial(),
       values,
     ) as Record<string, any>;
 
@@ -185,14 +194,22 @@ export class FormModel<T extends TObject> {
       return;
     }
 
-    // emit both action and form events
-    await this.alepha.events.emit("react:action:begin", {
-      type: "form",
-      id: this.id,
-    });
-    await this.alepha.events.emit("form:submit:begin", {
-      id: this.id,
-    });
+    // Lifecycle events are best-effort NOTIFICATIONS (loading spinners, toasts,
+    // analytics). A misbehaving listener must never break form state or reject
+    // submit() — hence `{ catch: true }` on every emit below. Without it, a
+    // throwing `react:action:error`/`form:submit:error` listener would skip the
+    // `form:submit:end` "loading off" signal and leave submit buttons stuck in
+    // their loading state forever.
+    await this.alepha.events.emit(
+      "react:action:begin",
+      { type: "form", id: this.id },
+      { catch: true },
+    );
+    await this.alepha.events.emit(
+      "form:submit:begin",
+      { id: this.id },
+      { catch: true },
+    );
 
     this.submitInProgress = true;
 
@@ -201,48 +218,65 @@ export class FormModel<T extends TObject> {
     try {
       let values: Record<string, any> = this.restructureValues(this.values);
 
-      if (t.schema.isSchema(options.schema)) {
-        values = this.alepha.codec.decode(options.schema, values) as Record<
-          string,
-          any
-        >;
+      if (z.schema.isSchema(options.schema)) {
+        // HTML form controls produce strings; coerce them to the schema's
+        // scalar types (number/boolean) at this string boundary before strict
+        // decoding — otherwise a `z.number()` field would reject its "42" input.
+        values = this.alepha.codec.decode(
+          options.schema,
+          coerceObject(options.schema, values),
+        ) as Record<string, any>;
       }
 
       await options.handler(values as any);
 
-      await this.alepha.events.emit("react:action:success", {
-        type: "form",
-        id: this.id,
-      });
-      await this.alepha.events.emit("form:submit:success", {
-        id: this.id,
-        values,
-      });
+      await this.alepha.events.emit(
+        "react:action:success",
+        { type: "form", id: this.id },
+        { catch: true },
+      );
+      await this.alepha.events.emit(
+        "form:submit:success",
+        { id: this.id, values },
+        { catch: true },
+      );
     } catch (error) {
       this.log.error("Form submission error:", error);
 
-      options.onError?.(error as Error);
-
-      await this.alepha.events.emit("react:action:error", {
-        type: "form",
-        id: this.id,
-        error: error as Error,
-      });
-      await this.alepha.events.emit("form:submit:error", {
-        error: error as Error,
-        id: this.id,
-      });
+      // A throwing onError callback must not abort the lifecycle either.
+      try {
+        options.onError?.(error as Error);
+      } catch (handlerError) {
+        this.log.error("Form onError handler threw:", handlerError);
+      }
+
+      await this.alepha.events.emit(
+        "react:action:error",
+        { type: "form", id: this.id, error: error as Error },
+        { catch: true },
+      );
+      await this.alepha.events.emit(
+        "form:submit:error",
+        { error: error as Error, id: this.id },
+        { catch: true },
+      );
     } finally {
       this.submitInProgress = false;
-    }
 
-    await this.alepha.events.emit("react:action:end", {
-      type: "form",
-      id: this.id,
-    });
-    await this.alepha.events.emit("form:submit:end", {
-      id: this.id,
-    });
+      // The "loading off" signals live in `finally` so they ALWAYS fire,
+      // even if something above threw — guaranteeing the begin/end pairing
+      // that drives submit-button loading state.
+      await this.alepha.events.emit(
+        "react:action:end",
+        { type: "form", id: this.id },
+        { catch: true },
+      );
+      await this.alepha.events.emit(
+        "form:submit:end",
+        { id: this.id },
+        { catch: true },
+      );
+    }
   };
 
   /**
@@ -303,13 +337,13 @@ export class FormModel<T extends TObject> {
     const parent = context.parent || "";
     return new Proxy<SchemaToInput<T>>({} as SchemaToInput<T>, {
       get: (_, prop: string) => {
-        if (!options.schema || !t.schema.isObject(schema)) {
+        if (!options.schema || !z.schema.isObject(schema)) {
           return {};
         }
 
         if (prop in schema.properties) {
           // // it's a nested object, create another proxy
-          // if (t.schema.isObject(schema.properties[prop])) {
+          // if (z.schema.isObject(schema.properties[prop])) {
           //   return this.createProxyFromSchema(
           //     options,
           //     schema.properties[prop],
@@ -324,7 +358,7 @@ export class FormModel<T extends TObject> {
             prop as keyof Static<T> & string,
             options,
             schema,
-            schema.required?.includes(prop as string) || false,
+            z.schema.requiredKeys(schema).includes(prop as string) || false,
             context,
           );
         }
@@ -343,8 +377,8 @@ export class FormModel<T extends TObject> {
     },
   ): BaseInputField {
     const parent = context.parent || "";
-    const field = schema.properties?.[name];
-    if (!field) {
+    const rawField = schema.properties?.[name];
+    if (!rawField) {
       return {
         path: "",
         required,
@@ -355,8 +389,12 @@ export class FormModel<T extends TObject> {
         form: this,
       };
     }
+    // Peel optional/nullable/default wrappers so the structural guards below
+    // (`isObject`/`isArray`/`isString`/…, `.maxLength`, format) see the real
+    // schema. Optionality is tracked separately via `isRequired`/`required`.
+    const field = z.schema.unwrap(rawField) as typeof rawField;
 
-    const isRequired = schema.required?.includes(name) ?? false;
+    const isRequired = z.schema.requiredKeys(schema).includes(name) ?? false;
     const key = parent ? `${parent}.${name}` : name;
     const path = `/${key.replaceAll(".", "/")}`;
 
@@ -383,7 +421,7 @@ export class FormModel<T extends TObject> {
     attr.id = `${this.id}-${key}`;
     (attr as any)["data-testid"] = attr.id;
 
-    if (t.schema.isString(field)) {
+    if (z.schema.isString(field)) {
       if (field.maxLength != null) {
         attr.maxLength = Number(field.maxLength);
       }
@@ -401,7 +439,7 @@ export class FormModel<T extends TObject> {
       attr["aria-label"] = field.description;
     }
 
-    if (t.schema.isInteger(field) || t.schema.isNumber(field)) {
+    if (z.schema.isInteger(field) || z.schema.isNumber(field)) {
       attr.type = "number";
     } else if (name === "password") {
       attr.type = "password";
@@ -409,19 +447,19 @@ export class FormModel<T extends TObject> {
       attr.type = "email";
     } else if (name === "url") {
       attr.type = "url";
-    } else if (t.schema.isString(field)) {
-      if (field.format === "binary") {
+    } else if (z.schema.isString(field)) {
+      if (z.schema.format(field) === "binary") {
         attr.type = "file";
-      } else if (field.format === "date") {
+      } else if (z.schema.format(field) === "date") {
         attr.type = "date";
-      } else if (field.format === "time") {
+      } else if (z.schema.format(field) === "time") {
         attr.type = "time";
-      } else if (field.format === "date-time") {
+      } else if (z.schema.format(field) === "date-time") {
         attr.type = "datetime-local";
       } else {
         attr.type = "text";
       }
-    } else if (t.schema.isBoolean(field)) {
+    } else if (z.schema.isBoolean(field)) {
       attr.type = "checkbox";
     }
 
@@ -431,7 +469,7 @@ export class FormModel<T extends TObject> {
     }
 
     // if type = object, add items: { [key: string]: InputField }
-    if (t.schema.isObject(field)) {
+    if (z.schema.isObject(field)) {
       return {
         path,
         props: attr,
@@ -448,7 +486,7 @@ export class FormModel<T extends TObject> {
     }
 
     // if type = array, add items: InputField[]
-    if (t.schema.isArray(field)) {
+    if (z.schema.isArray(field)) {
       return {
         path,
         props: attr,
@@ -488,14 +526,14 @@ export class FormModel<T extends TObject> {
     }
     if (input instanceof File) {
       // for file inputs, return the File object directly
-      if (t.schema.isString(schema) && schema.format === "binary") {
+      if (z.schema.isString(schema) && z.schema.format(schema) === "binary") {
         return input;
       }
       // for now, ignore other formats
       return null;
     }
 
-    if (t.schema.isBoolean(schema)) {
+    if (z.schema.isBoolean(schema)) {
       // Handle string representations from Select components (Yes/No dropdown)
       if (input === "true") return true;
       if (input === "false") return false;
@@ -505,19 +543,19 @@ export class FormModel<T extends TObject> {
       return !!input;
     }
 
-    if (t.schema.isNumber(schema)) {
+    if (z.schema.isNumber(schema)) {
       const num = Number(input);
       return Number.isNaN(num) ? null : num;
     }
 
-    if (t.schema.isString(schema)) {
-      if (schema.format === "date") {
+    if (z.schema.isString(schema)) {
+      if (z.schema.format(schema) === "date") {
         return new Date(input).toISOString().slice(0, 10); // For date input
       }
-      if (schema.format === "time") {
+      if (z.schema.format(schema) === "time") {
         return new Date(`1970-01-01T${input}`).toISOString().slice(11, 16); // For time input
       }
-      if (schema.format === "date-time") {
+      if (z.schema.format(schema) === "date-time") {
         return new Date(input).toISOString(); // For datetime-local input
       }
       return String(input);