alepha 0.15.1 → 0.15.3

package/src/react/core/index.ts

@@ -0,0 +1,90 @@
+import { $module } from "alepha";
+
+// ---------------------------------------------------------------------------------------------------------------------
+
+export type * from "./components/ClientOnly.tsx";
+export { default as ClientOnly } from "./components/ClientOnly.tsx";
+export type * from "./components/ErrorBoundary.tsx";
+export { default as ErrorBoundary } from "./components/ErrorBoundary.tsx";
+export * from "./contexts/AlephaContext.ts";
+export * from "./contexts/AlephaProvider.tsx";
+export * from "./hooks/useAction.ts";
+export * from "./hooks/useAlepha.ts";
+export * from "./hooks/useClient.ts";
+export * from "./hooks/useEvents.ts";
+export * from "./hooks/useInject.ts";
+export * from "./hooks/useStore.ts";
+
+// ---------------------------------------------------------------------------------------------------------------------
+
+declare module "alepha" {
+  interface Hooks {
+    /**
+     * Fires when a user action is starting.
+     * Action can be a form submission, a route transition, or a custom action.
+     */
+    "react:action:begin": {
+      type: string;
+      id?: string;
+    };
+    /**
+     * Fires when a user action has succeeded.
+     * Action can be a form submission, a route transition, or a custom action.
+     */
+    "react:action:success": {
+      type: string;
+      id?: string;
+    };
+    /**
+     * Fires when a user action has failed.
+     * Action can be a form submission, a route transition, or a custom action.
+     */
+    "react:action:error": {
+      type: string;
+      id?: string;
+      error: Error;
+    };
+    /**
+     * Fires when a user action has completed, regardless of success or failure.
+     * Action can be a form submission, a route transition, or a custom action.
+     */
+    "react:action:end": {
+      type: string;
+      id?: string;
+    };
+  }
+}
+
+// ---------------------------------------------------------------------------------------------------------------------
+
+/**
+ * | type | quality | stability |
+ * |------|---------|-----------|
+ * | frontend | epic | stable |
+ *
+ * Full-stack React framework with server-side rendering.
+ *
+ * **Features:**
+ * - React page routes with type-safe params
+ * - Async action handler with loading/error/cancel states
+ * - Type-safe HTTP client access
+ * - Dependency injection in components
+ * - Global state management
+ * - Router navigation methods
+ * - Current route state access
+ * - Check if path is active
+ * - URL query parameters
+ * - Access route schema
+ * - Subscribe to Alepha events
+ * - Type-safe form handling with validation
+ * - Error handling wrapper component
+ * - Client-side only rendering component
+ * - Server-side rendering with hydration
+ * - Automatic code splitting
+ * - Event system for action tracking
+ *
+ * @module alepha.react
+ */
+export const AlephaReact = $module({
+  name: "alepha.react.core",
+});

package/src/react/form/components/FormState.tsx

@@ -0,0 +1,17 @@
+import type { TObject } from "alepha";
+import type { ReactNode } from "react";
+import { useFormState } from "../hooks/useFormState.ts";
+import type { FormModel } from "../services/FormModel.ts";
+
+const FormState = <T extends TObject>(props: {
+  form: FormModel<T>;
+  children: (state: { loading: boolean; dirty: boolean }) => ReactNode;
+}) => {
+  const formState = useFormState(props.form);
+  return props.children({
+    loading: formState.loading,
+    dirty: formState.dirty,
+  });
+};
+
+export default FormState;

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

@@ -0,0 +1,18 @@
+import { TypeBoxError } from "alepha";
+
+export class FormValidationError extends TypeBoxError {
+  readonly name = "ValidationError";
+
+  constructor(options: {
+    message: string;
+    path: string;
+  }) {
+    super({
+      message: options.message,
+      instancePath: options.path,
+      schemaPath: "",
+      keyword: "not",
+      params: {},
+    });
+  }
+}

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

@@ -0,0 +1,366 @@
+import { fireEvent, render } from "@testing-library/react";
+import { Alepha, t } from "alepha";
+import { AlephaLogger } from "alepha/logger";
+import { AlephaContext } from "alepha/react";
+import type { ReactNode } from "react";
+import { describe, it } from "vitest";
+import { useForm } from "../index.ts";
+
+describe("useForm", () => {
+  const renderWithAlepha = (alepha: Alepha, element: ReactNode) => {
+    return render(
+      <AlephaContext.Provider value={alepha}>{element}</AlephaContext.Provider>,
+    );
+  };
+
+  it("should run handler on submit", async ({ expect }) => {
+    const alepha = Alepha.create().with(AlephaLogger);
+    const calls: Array<any> = [];
+    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(),
+            }),
+          }),
+        }),
+        handler: (values, args) => {
+          calls.push(values);
+        },
+      });
+
+      return (
+        <form {...form.props} data-testid="test-form">
+          <input {...form.input.str.props} />
+          <input {...form.input.int.props} />
+          <input {...form.input.nested.items.str.props} />
+          <input {...form.input.nested.items.another.items.level.props} />
+          <button type="submit">Submit</button>
+        </form>
+      );
+    };
+
+    await alepha.start();
+
+    const ui = renderWithAlepha(alepha, <Form />);
+
+    fireEvent.change(ui.getByTestId("test-str"), {
+      target: { value: "testuser" },
+    });
+
+    fireEvent.change(ui.getByTestId("test-int"), {
+      target: { value: "123" },
+    });
+
+    fireEvent.change(ui.getByTestId("test-nested.str"), {
+      target: { value: "nestedvalue" },
+    });
+
+    fireEvent.change(ui.getByTestId("test-nested.another.level"), {
+      target: { value: "anothervalue" },
+    });
+
+    fireEvent.submit(ui.getByText("Submit"));
+
+    await new Promise((resolve) => setTimeout(resolve, 100));
+
+    expect(calls[0]).toEqual({
+      str: "testuser",
+      int: 123,
+      nested: {
+        str: "nestedvalue",
+        another: {
+          level: "anothervalue",
+        },
+      },
+    });
+  });
+
+  it("should provide correct InputField types for nested objects", async ({
+    expect,
+  }) => {
+    const alepha = Alepha.create().with(AlephaLogger);
+
+    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(),
+            }),
+          }),
+        }),
+        handler: () => {},
+      });
+
+      // Verify nested object InputFields have items property
+      const addressInput = form.input.address;
+      const streetInput = addressInput.items.street;
+      const countryInput = addressInput.items.country;
+      const countryCodeInput = countryInput.items.code;
+
+      return (
+        <div data-testid="type-check">
+          <span data-testid="has-items">
+            {addressInput.items ? "true" : "false"}
+          </span>
+          <span data-testid="street-path">{streetInput.path}</span>
+          <span data-testid="country-code-path">{countryCodeInput.path}</span>
+        </div>
+      );
+    };
+
+    await alepha.start();
+    const ui = renderWithAlepha(alepha, <Form />);
+
+    expect(ui.getByTestId("has-items").textContent).toBe("true");
+    expect(ui.getByTestId("street-path").textContent).toBe("/address/street");
+    expect(ui.getByTestId("country-code-path").textContent).toBe(
+      "/address/country/code",
+    );
+  });
+
+  it("should provide ArrayInputField with items array for arrays", async ({
+    expect,
+  }) => {
+    const alepha = Alepha.create().with(AlephaLogger);
+
+    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(),
+            }),
+          ),
+        }),
+        handler: () => {},
+      });
+
+      // Verify array InputFields have items property (initially empty)
+      const tagsInput = form.input.tags;
+      const contactsInput = form.input.contacts;
+
+      return (
+        <div data-testid="array-check">
+          <span data-testid="tags-has-items">
+            {Array.isArray(tagsInput.items) ? "true" : "false"}
+          </span>
+          <span data-testid="tags-items-length">{tagsInput.items.length}</span>
+          <span data-testid="contacts-has-items">
+            {Array.isArray(contactsInput.items) ? "true" : "false"}
+          </span>
+          <span data-testid="contacts-items-length">
+            {contactsInput.items.length}
+          </span>
+          <span data-testid="tags-path">{tagsInput.path}</span>
+          <span data-testid="contacts-path">{contactsInput.path}</span>
+        </div>
+      );
+    };
+
+    await alepha.start();
+    const ui = renderWithAlepha(alepha, <Form />);
+
+    // Arrays have items property as array (initially empty)
+    expect(ui.getByTestId("tags-has-items").textContent).toBe("true");
+    expect(ui.getByTestId("tags-items-length").textContent).toBe("0");
+    expect(ui.getByTestId("contacts-has-items").textContent).toBe("true");
+    expect(ui.getByTestId("contacts-items-length").textContent).toBe("0");
+    expect(ui.getByTestId("tags-path").textContent).toBe("/tags");
+    expect(ui.getByTestId("contacts-path").textContent).toBe("/contacts");
+  });
+
+  it("should update array values via set method", async ({ expect }) => {
+    const alepha = Alepha.create().with(AlephaLogger);
+    const calls: Array<any> = [];
+
+    const Form = () => {
+      const form = useForm({
+        id: "array-set-test",
+        schema: t.object({
+          tags: t.array(t.text()),
+        }),
+        handler: (values) => {
+          calls.push(values);
+        },
+      });
+
+      return (
+        <form {...form.props} data-testid="array-form">
+          <button
+            type="button"
+            data-testid="set-tags"
+            onClick={() => form.input.tags.set(["tag1", "tag2", "tag3"])}
+          >
+            Set Tags
+          </button>
+          <button type="submit">Submit</button>
+        </form>
+      );
+    };
+
+    await alepha.start();
+    const ui = renderWithAlepha(alepha, <Form />);
+
+    fireEvent.click(ui.getByTestId("set-tags"));
+    fireEvent.submit(ui.getByText("Submit"));
+
+    await new Promise((resolve) => setTimeout(resolve, 100));
+
+    expect(calls[0]).toEqual({
+      tags: ["tag1", "tag2", "tag3"],
+    });
+  });
+
+  it("should update array of objects via set method", async ({ expect }) => {
+    const alepha = Alepha.create().with(AlephaLogger);
+    const calls: Array<any> = [];
+
+    const Form = () => {
+      const form = useForm({
+        id: "array-objects-test",
+        schema: t.object({
+          contacts: t.array(
+            t.object({
+              name: t.text(),
+              email: t.text(),
+            }),
+          ),
+        }),
+        handler: (values) => {
+          calls.push(values);
+        },
+      });
+
+      return (
+        <form {...form.props} data-testid="array-objects-form">
+          <button
+            type="button"
+            data-testid="set-contacts"
+            onClick={() =>
+              form.input.contacts.set([
+                { name: "Alice", email: "alice@example.com" },
+                { name: "Bob", email: "bob@example.com" },
+              ])
+            }
+          >
+            Set Contacts
+          </button>
+          <button type="submit">Submit</button>
+        </form>
+      );
+    };
+
+    await alepha.start();
+    const ui = renderWithAlepha(alepha, <Form />);
+
+    fireEvent.click(ui.getByTestId("set-contacts"));
+    fireEvent.submit(ui.getByText("Submit"));
+
+    await new Promise((resolve) => setTimeout(resolve, 100));
+
+    expect(calls[0]).toEqual({
+      contacts: [
+        { name: "Alice", email: "alice@example.com" },
+        { name: "Bob", email: "bob@example.com" },
+      ],
+    });
+  });
+
+  it("should handle complex nested structures with objects and arrays", async ({
+    expect,
+  }) => {
+    const alepha = Alepha.create().with(AlephaLogger);
+    const calls: Array<any> = [];
+
+    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(),
+            }),
+          }),
+          employees: t.array(
+            t.object({
+              name: t.text(),
+              role: t.text(),
+            }),
+          ),
+        }),
+        handler: (values) => {
+          calls.push(values);
+        },
+      });
+
+      return (
+        <form {...form.props} data-testid="complex-form">
+          <input {...form.input.company.items.name.props} />
+          <input {...form.input.company.items.address.items.street.props} />
+          <input {...form.input.company.items.address.items.city.props} />
+          <button
+            type="button"
+            data-testid="set-employees"
+            onClick={() =>
+              form.input.employees.set([
+                { name: "Alice", role: "Engineer" },
+                { name: "Bob", role: "Designer" },
+              ])
+            }
+          >
+            Set Employees
+          </button>
+          <button type="submit">Submit</button>
+        </form>
+      );
+    };
+
+    await alepha.start();
+    const ui = renderWithAlepha(alepha, <Form />);
+
+    fireEvent.change(ui.getByTestId("complex-test-company.name"), {
+      target: { value: "Acme Corp" },
+    });
+    fireEvent.change(ui.getByTestId("complex-test-company.address.street"), {
+      target: { value: "123 Main St" },
+    });
+    fireEvent.change(ui.getByTestId("complex-test-company.address.city"), {
+      target: { value: "New York" },
+    });
+    fireEvent.click(ui.getByTestId("set-employees"));
+    fireEvent.submit(ui.getByText("Submit"));
+
+    await new Promise((resolve) => setTimeout(resolve, 100));
+
+    expect(calls[0]).toEqual({
+      company: {
+        name: "Acme Corp",
+        address: {
+          street: "123 Main St",
+          city: "New York",
+        },
+      },
+      employees: [
+        { name: "Alice", role: "Engineer" },
+        { name: "Bob", role: "Designer" },
+      ],
+    });
+  });
+});

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

@@ -0,0 +1,47 @@
+import type { TObject } from "alepha";
+import { useAlepha } from "alepha/react";
+import { useId, useMemo } from "react";
+import { type FormCtrlOptions, FormModel } from "../services/FormModel.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>
+ * );
+ * ```
+ */
+export const useForm = <T extends TObject>(
+  options: FormCtrlOptions<T>,
+  deps: any[] = [],
+): FormModel<T> => {
+  const alepha = useAlepha();
+  const formId = useId();
+
+  return useMemo(() => {
+    return alepha.inject(FormModel<T>, {
+      lifetime: "transient",
+      args: [options.id || formId, options],
+    });
+  }, deps);
+};

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

@@ -0,0 +1,130 @@
+import { type TObject, TypeBoxError } from "alepha";
+import { useAlepha } from "alepha/react";
+import { useEffect, useState } from "react";
+import type { FormModel } from "../services/FormModel.ts";
+
+export interface UseFormStateReturn {
+  loading: boolean;
+  dirty: boolean;
+  values?: Record<string, any>;
+  error?: Error;
+}
+
+export const useFormState = <
+  T extends TObject,
+  Keys extends keyof UseFormStateReturn,
+>(
+  target: FormModel<T> | { form: FormModel<T>; path: string },
+  _events: Keys[] = ["loading", "dirty", "error"] as Keys[],
+): Pick<UseFormStateReturn, Keys> => {
+  const alepha = useAlepha();
+  const events = _events as string[];
+
+  const [dirty, setDirty] = useState(false);
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState<Error | undefined>(undefined);
+  const [values, setValues] = useState<Record<string, any> | undefined>(
+    undefined,
+  );
+
+  const form = "form" in target ? target.form : target;
+  const path = "path" in target ? target.path : undefined;
+
+  const hasValues = events.includes("values");
+  const hasErrors = events.includes("error");
+  const hasDirty = events.includes("dirty");
+  const hasLoading = events.includes("loading");
+
+  useEffect(() => {
+    const listeners: Function[] = [];
+
+    if (hasErrors || hasValues || hasDirty) {
+      listeners.push(
+        alepha.events.on("form:change", (event) => {
+          if (event.id === form.id) {
+            if (!path || event.path === path) {
+              if (hasDirty) {
+                setDirty(true);
+              }
+              if (hasErrors) {
+                setError(undefined);
+              }
+            }
+            if (hasValues) {
+              setValues(form.currentValues);
+            }
+          }
+        }),
+      );
+    }
+
+    if (hasValues) {
+      listeners.push(
+        alepha.events.on("form:reset", (event) => {
+          if (event.id === form.id) {
+            setValues(event.values);
+          }
+        }),
+      );
+    }
+
+    if (hasLoading) {
+      listeners.push(
+        alepha.events.on("form:submit:begin", (event) => {
+          if (event.id === form.id) {
+            setLoading(true);
+          }
+        }),
+        alepha.events.on("form:submit:end", (event) => {
+          if (event.id === form.id) {
+            setLoading(false);
+          }
+        }),
+      );
+    }
+
+    if (hasValues || hasDirty) {
+      listeners.push(
+        alepha.events.on("form:submit:success", (event) => {
+          if (event.id === form.id) {
+            if (hasValues) {
+              setValues(event.values);
+            }
+            if (hasDirty) {
+              setDirty(false);
+            }
+          }
+        }),
+      );
+    }
+
+    if (hasErrors) {
+      listeners.push(
+        alepha.events.on("form:submit:error", (event) => {
+          if (event.id === form.id) {
+            if (
+              !path ||
+              (event.error instanceof TypeBoxError &&
+                event.error.value.path === path)
+            ) {
+              setError(event.error);
+            }
+          }
+        }),
+      );
+    }
+
+    return () => {
+      for (const unsub of listeners) {
+        unsub();
+      }
+    };
+  }, []);
+
+  return {
+    dirty,
+    loading,
+    error,
+    values,
+  } as Pick<UseFormStateReturn, Keys>;
+};