oxform-react 0.1.0

package/export/index.ts

@@ -0,0 +1,3 @@
+export { useField } from '#use-field';
+export type { UseFieldReturn } from '#use-field';
+export { useForm } from '#use-form';

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "oxform-react",
+  "version": "0.1.0",
+  "description": "Oxform is a lean and flexible framework-agnostic form library.",
+  "author": "Frantss <frantss.bongiovanni@gmail.com>",
+  "license": "MIT",
+  "sideEffects": false,
+  "type": "module",
+  "main": "./dist/index.js",
+  "imports": {
+    "#*": [
+      "./src/*.ts",
+      "./src/**/*.ts"
+    ]
+  },
+  "exports": {
+    ".": "./dist/index.js",
+    "./package.json": "./package.json"
+  },
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "scripts": {
+    "build": "tsdown --config-loader unrun",
+    "test": "vitest",
+    "lint:types": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@standard-schema/spec": "catalog:oxform",
+    "@tanstack/react-store": "^0.8.0",
+    "oxform-core": "workspace:*"
+  },
+  "devDependencies": {
+    "@types/react": "^19.2.7",
+    "@types/react-dom": "^19.2.3",
+    "@vitejs/plugin-react": "^5.1.2",
+    "react": "19.2.3",
+    "react-dom": "19.2.3",
+    "tsdown": "catalog:oxform",
+    "typescript": "catalog:oxform",
+    "vitest": "catalog:oxform",
+    "vitest-browser-react": "^2.0.2",
+    "zod": "^4.2.1"
+  },
+  "peerDependencies": {
+    "react": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0",
+    "react-dom": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0"
+  }
+}

package/readme.md

@@ -0,0 +1,12 @@
+# Oxform React
+
+This package contains the React integration for Oxform.
+
+## Installation
+
+```bash
+npm install oxform-react
+yarn add oxform-react
+pnpm add oxform-react
+bun add oxform-react
+```

package/src/testing/performance.tsx

@@ -0,0 +1,59 @@
+// reference: https://stevekinney.com/courses/react-performance/performance-testing-strategy
+
+import { Profiler, type ProfilerOnRenderCallback } from 'react';
+import { expect } from 'vitest';
+import { render } from 'vitest-browser-react';
+
+interface RenderMetrics {
+  renderTime: number;
+  commitTime: number;
+  actualDuration: number;
+  baseDuration: number;
+  startTime: number;
+}
+
+export function measureRenderPerformance(component: React.ReactElement, testName: string): Promise<RenderMetrics> {
+  return new Promise(resolve => {
+    let metrics: RenderMetrics;
+
+    const onRender: ProfilerOnRenderCallback = (_, phase, actualDuration, baseDuration, startTime, commitTime) => {
+      if (phase === 'mount' || phase === 'update') {
+        metrics = {
+          renderTime: actualDuration,
+          commitTime,
+          actualDuration,
+          baseDuration,
+          startTime,
+        };
+      }
+    };
+
+    void render(
+      <Profiler id={testName} onRender={onRender}>
+        {component}
+      </Profiler>,
+    );
+
+    setTimeout(() => resolve(metrics), 0);
+  });
+}
+
+expect.extend({
+  toRenderWithinTime(received: RenderMetrics, maxTime: number) {
+    const pass = received.renderTime <= maxTime;
+
+    return {
+      message: () => `Expected component to render in ${maxTime}ms, but took ${received.renderTime.toFixed(2)}ms`,
+      pass,
+    };
+  },
+
+  toHaveMaxReRenders(received: number, maxRenders: number) {
+    const pass = received <= maxRenders;
+
+    return {
+      message: () => `Expected component to re-render at most ${maxRenders} times, but re-rendered ${received} times`,
+      pass,
+    };
+  },
+});

package/src/tests/use-field.spec.tsx

@@ -0,0 +1,116 @@
+import { useField } from '#use-field';
+import { FormApi } from 'oxform-core';
+import 'react';
+import { expect, it, test } from 'vitest';
+import { render } from 'vitest-browser-react';
+import { userEvent } from 'vitest/browser';
+import { z } from 'zod';
+
+const setup = async () => {
+  const form = new FormApi({
+    schema: z.object({
+      name: z.string(),
+      nested: z.object({
+        deep: z.object({
+          deeper: z.string().array(),
+        }),
+      }),
+    }),
+    defaultValues: {
+      name: 'John',
+      nested: {
+        deep: {
+          deeper: ['hello'],
+        },
+      },
+    },
+  });
+
+  const Component = () => {
+    const field = useField({ form, name: 'name' });
+
+    return (
+      <>
+        <input {...field.props} />
+        <button type='button'>outside</button>
+      </>
+    );
+  };
+
+  const utils = await render(<Component />);
+
+  const ui = {
+    input: utils.getByRole('textbox'),
+    outside: utils.getByRole('button'),
+  };
+
+  return { utils, ui, form };
+};
+
+it("should update the form's values on change", async () => {
+  const { form, ui } = await setup();
+
+  await userEvent.clear(ui.input);
+  await userEvent.type(ui.input, 'Jane');
+
+  expect(form.store.state.values.name).toBe('Jane');
+});
+
+it('should mark the field as touched on focus', async () => {
+  const { form, ui } = await setup();
+
+  await ui.input.click();
+
+  const meta = form.store.state.fields['name'];
+
+  expect(meta).toBeDefined();
+  expect(meta.touched).toBe(true);
+});
+
+it('should mark the fields as blurred on blur', async () => {
+  const { form, ui } = await setup();
+
+  await ui.input.click();
+  await ui.outside.click(); // blur the input
+
+  const meta = form.store.state.fields['name'];
+
+  expect(meta).toBeDefined();
+  expect(meta.blurred).toBe(true);
+});
+
+it('should keep the field as pristine when field is not dirty', async () => {
+  const { form, ui } = await setup();
+
+  await ui.input.click();
+  await ui.outside.click(); // blur the input
+
+  const meta = form.store.state.fields['name'];
+
+  expect(meta).toBeDefined();
+  expect(meta.pristine).toBe(true);
+});
+
+test('default is true when value is equal to default value', async () => {
+  const { form, ui } = await setup();
+
+  await userEvent.clear(ui.input);
+  await userEvent.type(ui.input, 'Jane');
+  await userEvent.clear(ui.input);
+  await userEvent.type(ui.input, 'John');
+
+  const meta = form.store.state.fields['name'];
+
+  expect(meta.default).toBe(true);
+});
+
+test('default is false when value is not equal to default value', async () => {
+  const { form, ui } = await setup();
+
+  await userEvent.clear(ui.input);
+  await userEvent.type(ui.input, 'Jane');
+
+  const meta = form.store.state.fields['name'];
+
+  expect(meta.default).toBe(false);
+});

package/src/use-field.ts

@@ -0,0 +1,81 @@
+import type { FieldMeta, FormIssue, FormResetFieldOptions, FormSetErrorsOptions, ValidateOptions } from 'oxform-core';
+import { FieldApi, type FieldOptions, type FieldProps } from 'oxform-core';
+
+import { useIsomorphicLayoutEffect } from '#use-isomorphic-layout-effect';
+import { useStore } from '@tanstack/react-store';
+import type { DeepKeys, DeepValue, EventLike } from 'oxform-core';
+import type { StandardSchema } from 'oxform-core/schema';
+import { useCallback, useMemo, useState } from 'react';
+
+export type UseFieldReturn<Value> = {
+  api: FieldApi<any, any, Value>;
+  value: Value;
+  change: (value: Value) => void;
+  blur: () => void;
+  focus: () => void;
+  register: () => void;
+  validate: (options?: ValidateOptions) => Promise<FormIssue[]>;
+  reset: (options?: FormResetFieldOptions<Value>) => void;
+  setErrors: (errors: FormIssue[], options?: FormSetErrorsOptions) => void;
+  props: FieldProps<Value>;
+  meta: FieldMeta;
+  errors: FormIssue[];
+};
+
+export const useField = <Schema extends StandardSchema, Name extends DeepKeys<StandardSchema.InferInput<Schema>>>(
+  options: FieldOptions<Schema, Name>,
+) => {
+  type Value = DeepValue<StandardSchema.InferInput<Schema>, Name>;
+
+  const [api] = useState(() => {
+    return new FieldApi({ ...options });
+  });
+
+  useIsomorphicLayoutEffect(api['~mount'], [api]);
+  useIsomorphicLayoutEffect(() => {
+    api['~update'](options);
+  });
+
+  const value = useStore(api.store, state => state.value);
+  const defaultValue = useStore(api.store, state => state.defaultValue);
+  const dirty = useStore(api.store, state => state.meta.dirty);
+  const touched = useStore(api.store, state => state.meta.touched);
+  const blurred = useStore(api.store, state => state.meta.blurred);
+  const pristine = useStore(api.store, state => state.meta.pristine);
+  const valid = useStore(api.store, state => state.meta.valid);
+  const isDefault = useStore(api.store, state => state.meta.default);
+  const errors = useStore(api.store, state => state.errors);
+
+  const onChange = useCallback((event: EventLike) => api.change(event.target?.value), [api]);
+
+  return useMemo(() => {
+    return {
+      api,
+      value,
+      blur: api.blur,
+      focus: api.focus,
+      change: api.change,
+      register: api.register,
+      validate: api.validate,
+      reset: api.reset,
+      setErrors: api.setErrors,
+      errors,
+      props: {
+        value,
+        defaultValue,
+        ref: api.register(),
+        onBlur: api.blur,
+        onFocus: api.focus,
+        onChange,
+      },
+      meta: {
+        dirty,
+        touched,
+        blurred,
+        pristine,
+        valid,
+        default: isDefault,
+      },
+    } satisfies UseFieldReturn<Value> as UseFieldReturn<Value>;
+  }, [api, errors, value, defaultValue, onChange, dirty, touched, blurred, pristine, valid, isDefault]);
+};

package/src/use-form-status.ts

@@ -0,0 +1,28 @@
+import { useStore } from '@tanstack/react-store';
+import type { FormApi, FormStatus } from 'oxform-core';
+import type { StandardSchema } from 'oxform-core/schema';
+import { useMemo } from 'react';
+
+export type UseFormStatusReturn = FormStatus;
+
+export const useFormStatus = <Schema extends StandardSchema>({ form }: { form: FormApi<Schema> }) => {
+  const dirty = useStore(form.store, state => state.status.dirty);
+  const valid = useStore(form.store, state => state.status.valid);
+  const submitting = useStore(form.store, state => state.status.submitting);
+  const successful = useStore(form.store, state => state.status.successful);
+  const validating = useStore(form.store, state => state.status.validating);
+  const submits = useStore(form.store, state => state.status.submits);
+  const submitted = useStore(form.store, state => state.status.submitted);
+
+  return useMemo(() => {
+    return {
+      dirty,
+      valid,
+      submitting,
+      successful,
+      validating,
+      submits,
+      submitted,
+    } satisfies UseFormStatusReturn as UseFormStatusReturn;
+  }, [dirty, valid, submitting, successful, validating, submits, submitted]);
+};

package/src/use-form.ts

@@ -0,0 +1,20 @@
+import { useIsomorphicLayoutEffect } from '#use-isomorphic-layout-effect';
+import type { FormOptions } from 'oxform-core';
+import { FormApi } from 'oxform-core';
+import type { StandardSchema } from 'oxform-core/schema';
+import { useState } from 'react';
+
+export type UseFormReturn<Schema extends StandardSchema> = FormApi<Schema>;
+
+export const useForm = <Schema extends StandardSchema>(options: FormOptions<Schema>) => {
+  const [api] = useState(() => {
+    return new FormApi({ ...options });
+  });
+
+  useIsomorphicLayoutEffect(api['~mount'], [api]);
+  useIsomorphicLayoutEffect(() => {
+    api['~update'](options);
+  });
+
+  return api satisfies UseFormReturn<Schema> as UseFormReturn<Schema>;
+};

package/src/use-isomorphic-layout-effect.ts

@@ -0,0 +1,3 @@
+import { useEffect, useLayoutEffect } from 'react';
+
+export const useIsomorphicLayoutEffect = typeof window !== 'undefined' ? useLayoutEffect : useEffect;

package/tsconfig.json

@@ -0,0 +1,6 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "jsx": "react-jsx"
+  }
+}

package/tsdown.config.ts

@@ -0,0 +1,9 @@
+import { defineConfig } from 'tsdown';
+import base from '../../tsdown.config';
+
+export default defineConfig({
+  ...base,
+  entry: {
+    index: 'export/index.ts',
+  },
+});

package/vitest.config.ts

@@ -0,0 +1,10 @@
+import react from '@vitejs/plugin-react';
+import { defineConfig, mergeConfig } from 'vitest/config';
+import base from '../../vitest.config';
+
+export default mergeConfig(
+  base,
+  defineConfig({
+    plugins: [react()],
+  }),
+);