@kitr/forms 0.0.0-stage → 0.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Platon Podkopov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,15 @@
-# Temporary Holding Version
+# @kitr/forms
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**Forms.** Build forms with validation, and show server errors next to the right field.
+
+```sh
+pnpm kitr add forms
+```
+
+`kitr add` installs the package and wires it into your app: the provider in `kitrrc.ts`, its config file and its `AGENTS.md` section. Import it from `@kitr/forms`.
+
+Built on react-hook-form.
+
+Read the guide at https://kitr.dev/packages/forms.
+
+Part of [kitr](https://kitr.dev), the TypeScript framework where everything is an add-on. MIT licensed.

package/dist/index.d.ts

@@ -0,0 +1,96 @@
+import { FieldPath, FieldValues, Form as RhfForm, FormProps as RhfFormProps, UseFormProps, UseFormReturn } from "react-hook-form";
+import { StandardSchemaV1 } from "@kitr/core";
+import { ComponentProps, ReactNode } from "react";
+export * from "react-hook-form";
+/** Props of `<Form>`. Every other prop is passed to the `<form>` element. */
+interface FormProps<TIn extends FieldValues, TOut extends FieldValues> extends Omit<ComponentProps<'form'>, 'onSubmit' | 'onError'> {
+  /** The object returned by `useSchemaForm` or React Hook Form's `useForm`. */
+  form: UseFormReturn<TIn, unknown, TOut>;
+  /** Runs with validated values. A thrown KitrError with `fieldErrors` lands on fields. */
+  onSubmit: (values: TOut) => unknown | Promise<unknown>;
+  /** Runs after `onSubmit` resolves, with its return value and the submitted values. */
+  onSuccess?: (result: unknown, values: TOut) => void;
+  /** Runs after a thrown error has been mapped onto the fields; receives it as a `KitrError`. */
+  onError?: (error: unknown) => void;
+  /** Reset to default values after a successful submit. */
+  resetOnSuccess?: boolean;
+  /** The fields, buttons and anything else inside the form. */
+  children: ReactNode;
+}
+/**
+ * The kitr glue around React Hook Form: submit handling with pending state,
+ * server validation errors mapped onto fields, and a root error for everything else.
+ */
+export declare function Form<TIn extends FieldValues, TOut extends FieldValues>({ form, onSubmit, onSuccess, onError, resetOnSuccess, children, ...rest }: FormProps<TIn, TOut>): import("react").JSX.Element;
+/** `pending` is true while `onSubmit` runs. Use it on the submit button. */
+export declare function useFormStatus(): {
+  pending: boolean;
+  isValid: boolean;
+};
+/** The form-level error from the server (anything not mapped to a field). */
+export declare function useRootError(): string | undefined;
+/** Props of `<FormField>`: which field it wraps and the text around the input. */
+interface FormFieldProps<T extends FieldValues> {
+  /** The field path, dot-separated for nested fields (`'lines.0.quantity'`). */
+  name: FieldPath<T>;
+  /** Content of the `<label>`, which points at the input's generated id. */
+  label?: ReactNode;
+  /** Help text under the input, linked to it with `aria-describedby`. */
+  description?: ReactNode;
+  /** The input, or a function that receives `{ id, name, invalid, describedBy }` and renders it. */
+  children: ReactNode | ((field: {
+    id: string;
+    name: string;
+    invalid: boolean;
+    describedBy: string;
+  }) => ReactNode);
+  /** Class for the wrapper `<div data-kitr="field">`. */
+  className?: string;
+}
+/**
+ * Headless field wrapper: generates ids, wires `aria-describedby` and
+ * `aria-invalid`, shows the field's error. Style it with your own classes
+ * or pull the registry's `form` component for a styled version.
+ */
+export declare function FormField<T extends FieldValues>({ name, label, description, children, className }: FormFieldProps<T>): import("react").JSX.Element;
+/** Props to spread on the input inside a `<FormField>`: `{...useFieldProps()}` plus `form.register(name)`. */
+export declare function useFieldProps(): {
+  onChange: import("react-hook-form").ChangeHandler;
+  onBlur: import("react-hook-form").ChangeHandler;
+  ref: import("react-hook-form").RefCallBack;
+  name: string;
+  min?: string | number;
+  max?: string | number;
+  maxLength?: number;
+  minLength?: number;
+  pattern?: string;
+  required?: boolean;
+  disabled?: boolean;
+  id: string;
+  'aria-invalid': boolean | undefined;
+  'aria-describedby': string | undefined;
+};
+/** Convenience: an `<input>` already registered to the surrounding field. */
+export declare function FieldInput(props: Omit<ComponentProps<'input'>, 'name' | 'id'>): import("react").JSX.Element;
+/**
+ * A `type="submit"` button that is disabled and `aria-busy` while the form submits, and shows
+ * `pendingText` in that time. A `disabled` prop is combined with the pending state, never replaced.
+ */
+export declare function SubmitButton({ children, pendingText, disabled, ...props }: ComponentProps<'button'> & {
+  pendingText?: ReactNode;
+}): import("react").JSX.Element;
+/**
+ * Map kitr's `fieldErrors` onto React Hook Form fields. Unknown fields and
+ * `_root` go to `root.server`. Returns true if the error was a validation error.
+ */
+export declare function applyServerErrors<T extends FieldValues>(form: UseFormReturn<T>, error: unknown): boolean;
+/** Every React Hook Form `useForm` option except `resolver`, which `useSchemaForm` sets from the schema. */
+export type SchemaFormOptions<TIn extends FieldValues, TOut> = Omit<UseFormProps<TIn, unknown, TOut>, 'resolver'>;
+/**
+ * `useForm` with a Standard Schema resolver (zod, valibot, arktype). The full
+ * React Hook Form API is on the returned object; nothing is wrapped.
+ */
+export declare function useSchemaForm<TIn extends FieldValues, TOut extends FieldValues = TIn>(schema: StandardSchemaV1<TIn, TOut>, options?: SchemaFormOptions<TIn, TOut>): UseFormReturn<TIn, unknown, TOut>;
+/** Alias kept for people who think in zod. */
+export declare const useZodForm: typeof useSchemaForm;
+export { type FormFieldProps, type FormProps, RhfForm, type RhfFormProps };

package/dist/index.js

@@ -0,0 +1,183 @@
+import { Form as RhfForm, FormProvider, useForm, useFormContext } from "react-hook-form";
+import { isKitrError, toKitrError } from "@kitr/core";
+import { createContext, useContext, useId, useState } from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { standardSchemaResolver } from "@hookform/resolvers/standard-schema";
+export * from "react-hook-form";
+// src/server-errors.ts
+/**
+* Map kitr's `fieldErrors` onto React Hook Form fields. Unknown fields and
+* `_root` go to `root.server`. Returns true if the error was a validation error.
+*/
+function applyServerErrors(form, error) {
+	const err = toKitrError(error);
+	const fieldErrors = err.fieldErrors;
+	const known = new Set(Object.keys(form.getValues() ?? {}));
+	let applied = false;
+	if (fieldErrors) for (const [field, messages] of Object.entries(fieldErrors)) {
+		const first = messages[0] ?? "Invalid";
+		const top = field.split(".")[0] ?? field;
+		if (field !== "_root" && (known.has(top) || known.size === 0)) {
+			form.setError(field, {
+				type: "server",
+				message: first
+			});
+			applied = true;
+		} else form.setError("root.server", {
+			type: "server",
+			message: first
+		});
+	}
+	if (!applied && !fieldErrors) form.setError("root.server", {
+		type: "server",
+		message: err.message
+	});
+	return isKitrError(error) && err.code === "VALIDATION";
+}
+// src/form.tsx
+/**
+* The kitr glue around React Hook Form: submit handling with pending state,
+* server validation errors mapped onto fields, and a root error for everything else.
+*/
+function Form({ form, onSubmit, onSuccess, onError, resetOnSuccess, children, ...rest }) {
+	const [pending, setPending] = useState(false);
+	const submit = form.handleSubmit(async (values) => {
+		setPending(true);
+		form.clearErrors("root.server");
+		try {
+			const result = await onSubmit(values);
+			onSuccess?.(result, values);
+			if (resetOnSuccess) form.reset();
+		} catch (error) {
+			applyServerErrors(form, error);
+			onError?.(toKitrError(error));
+		} finally {
+			setPending(false);
+		}
+	});
+	return /* @__PURE__ */ jsx(FormProvider, {
+		...form,
+		children: /* @__PURE__ */ jsx(FormStatusContext.Provider, {
+			value: { pending },
+			children: /* @__PURE__ */ jsx("form", {
+				noValidate: true,
+				...rest,
+				onSubmit: submit,
+				children
+			})
+		})
+	});
+}
+const FormStatusContext = createContext({ pending: false });
+/** `pending` is true while `onSubmit` runs. Use it on the submit button. */
+function useFormStatus() {
+	const { pending } = useContext(FormStatusContext);
+	const form = useFormContext();
+	return {
+		pending: pending || form.formState.isSubmitting,
+		isValid: form.formState.isValid
+	};
+}
+/** The form-level error from the server (anything not mapped to a field). */
+function useRootError() {
+	return useFormContext().formState.errors?.root?.server?.message;
+}
+const FieldContext = createContext(null);
+/**
+* Headless field wrapper: generates ids, wires `aria-describedby` and
+* `aria-invalid`, shows the field's error. Style it with your own classes
+* or pull the registry's `form` component for a styled version.
+*/
+function FormField({ name, label, description, children, className }) {
+	const form = useFormContext();
+	const id = useId();
+	const error = form.getFieldState(name, form.formState).error?.message ?? void 0;
+	const describedBy = [description ? `${id}-description` : null, error ? `${id}-error` : null].filter(Boolean).join(" ");
+	const value = {
+		name,
+		id,
+		error,
+		describedBy
+	};
+	return /* @__PURE__ */ jsx(FieldContext.Provider, {
+		value,
+		children: /* @__PURE__ */ jsxs("div", {
+			className,
+			"data-kitr": "field",
+			"data-invalid": error ? "" : void 0,
+			children: [
+				label ? /* @__PURE__ */ jsx("label", {
+					htmlFor: id,
+					"data-kitr": "label",
+					children: label
+				}) : null,
+				typeof children === "function" ? children({
+					id,
+					name,
+					invalid: !!error,
+					describedBy
+				}) : children,
+				description ? /* @__PURE__ */ jsx("p", {
+					id: `${id}-description`,
+					"data-kitr": "description",
+					children: description
+				}) : null,
+				error ? /* @__PURE__ */ jsx("p", {
+					id: `${id}-error`,
+					role: "alert",
+					"data-kitr": "field-error",
+					children: error
+				}) : null
+			]
+		})
+	});
+}
+/** Props to spread on the input inside a `<FormField>`: `{...useFieldProps()}` plus `form.register(name)`. */
+function useFieldProps() {
+	const ctx = useContext(FieldContext);
+	if (!ctx) throw new Error("[@kitr/forms] useFieldProps() must be used inside <FormField>.");
+	const form = useFormContext();
+	return {
+		id: ctx.id,
+		"aria-invalid": ctx.error ? true : void 0,
+		"aria-describedby": ctx.describedBy || void 0,
+		...form.register(ctx.name)
+	};
+}
+/** Convenience: an `<input>` already registered to the surrounding field. */
+function FieldInput(props) {
+	const fieldProps = useFieldProps();
+	return /* @__PURE__ */ jsx("input", {
+		...props,
+		...fieldProps
+	});
+}
+/**
+* A `type="submit"` button that is disabled and `aria-busy` while the form submits, and shows
+* `pendingText` in that time. A `disabled` prop is combined with the pending state, never replaced.
+*/
+function SubmitButton({ children, pendingText, disabled, ...props }) {
+	const { pending } = useFormStatus();
+	return /* @__PURE__ */ jsx("button", {
+		type: "submit",
+		...props,
+		disabled: pending || disabled,
+		"aria-busy": pending,
+		children: pending && pendingText ? pendingText : children
+	});
+}
+// src/use-schema-form.ts
+/**
+* `useForm` with a Standard Schema resolver (zod, valibot, arktype). The full
+* React Hook Form API is on the returned object; nothing is wrapped.
+*/
+function useSchemaForm(schema, options = {}) {
+	return useForm({
+		mode: "onTouched",
+		...options,
+		resolver: standardSchemaResolver(schema)
+	});
+}
+/** Alias kept for people who think in zod. */
+const useZodForm = useSchemaForm;
+export { FieldInput, Form, FormField, RhfForm, SubmitButton, applyServerErrors, useFieldProps, useFormStatus, useRootError, useSchemaForm, useZodForm };

package/dist/kitr.d.ts

@@ -0,0 +1,28 @@
+/** `kitr add forms`: React Hook Form with Standard Schema resolvers, `<Form>` with server-error mapping. */
+declare const _default: {
+  readonly name: "forms";
+  readonly client: true;
+  readonly add: (ctx: import("@kitr/core/package").AddContext) => void;
+  readonly remove: (ctx: import("@kitr/core/package").AddContext) => void;
+  readonly generators: {
+    readonly form: {
+      readonly description: "Create a form component in app/components/forms";
+      readonly definition: "A component that owns one schema-validated form and its submit.";
+      readonly target: (name: string, project: import("@kitr/core/package").ProjectInfo) => {
+        file: string;
+        vars: Record<string, string>;
+      };
+      readonly stub: ({ name }: import("@kitr/core/package").GeneratorVars) => string;
+    };
+  };
+  readonly wraps: {
+    readonly 'react-hook-form': "@kitr/forms";
+  };
+  readonly eject: {
+    readonly '@kitr/forms': "react-hook-form + @hookform/resolvers";
+  };
+  readonly vite: {
+    readonly optimizeDeps: ["react-hook-form", "@hookform/resolvers/standard-schema"];
+  };
+};
+export { _default as default };

package/dist/kitr.js

@@ -0,0 +1,49 @@
+import { definePackage, generatorFile, naming } from "@kitr/core/package";
+// src/kitr.ts
+/** `kitr add forms`: React Hook Form with Standard Schema resolvers, `<Form>` with server-error mapping. */
+var kitr_default = definePackage({
+	name: "forms",
+	client: true,
+	add(ctx) {
+		ctx.deps.add("react-hook-form", "@hookform/resolvers", "zod");
+		ctx.agents.add("forms", `- Forms: \`const form = useSchemaForm(schema, { defaultValues })\` then \`<Form form={form} onSubmit={...}>\` from \`@kitr/forms\` (or the styled copy in \`app/components/ui/form.tsx\`).\n- Throw or reject with a KitrError carrying \`fieldErrors\` and the fields show the messages; anything else lands in \`useRootError()\`.`);
+	},
+	remove(ctx) {
+		ctx.deps.remove("react-hook-form", "@hookform/resolvers");
+		ctx.agents.remove("forms");
+	},
+	generators: { form: {
+		description: "Create a form component in app/components/forms",
+		definition: "A component that owns one schema-validated form and its submit.",
+		target: (name, project) => generatorFile(project, "components", "forms", name, {
+			suffix: "-form",
+			ext: ".tsx"
+		}),
+		stub: ({ name }) => `import { useSchemaForm } from '@kitr/forms'
+import { z } from 'zod'
+import { FieldInput, Form, FormField, FormMessage, SubmitButton } from '#components/ui/form'
+
+export const ${naming.camel(name)}Schema = z.object({
+  name: z.string().min(2, 'Name must be at least 2 characters'),
+})
+export type ${naming.pascal(name)}Values = z.infer<typeof ${naming.camel(name)}Schema>
+
+export function ${naming.pascal(name)}Form({ defaultValues, onSubmit }: { defaultValues?: Partial<${naming.pascal(name)}Values>; onSubmit: (values: ${naming.pascal(name)}Values) => Promise<unknown> }) {
+  const form = useSchemaForm(${naming.camel(name)}Schema, { defaultValues: { name: '', ...defaultValues } })
+  return (
+    <Form form={form} onSubmit={onSubmit} className="grid gap-4">
+      <FormMessage />
+      <FormField name="name" label="Name">
+        <FieldInput autoComplete="off" />
+      </FormField>
+      <SubmitButton>Save</SubmitButton>
+    </Form>
+  )
+}
+`
+	} },
+	wraps: { "react-hook-form": "@kitr/forms" },
+	eject: { "@kitr/forms": "react-hook-form + @hookform/resolvers" },
+	vite: { optimizeDeps: ["react-hook-form", "@hookform/resolvers/standard-schema"] }
+});
+export { kitr_default as default };

package/docs/api.md

@@ -0,0 +1,77 @@
+---
+title: API reference
+description: Every export of @kitr/forms.
+order: 2
+---
+
+# API reference
+
+`@kitr/forms` re-exports everything from `react-hook-form` (its `Form` as `RhfForm`) and adds the following.
+
+## useSchemaForm
+
+```ts
+function useSchemaForm<TIn, TOut = TIn>(
+  schema: StandardSchemaV1<TIn, TOut>,
+  options?: Omit<UseFormProps<TIn, unknown, TOut>, 'resolver'>,
+): UseFormReturn<TIn, unknown, TOut>
+```
+
+`useForm` with a Standard Schema resolver and `mode: 'onTouched'`. Every React Hook Form option is accepted. `useZodForm` is an alias.
+
+## Form
+
+```tsx
+<Form form={form} onSubmit={fn} onSuccess? onError? resetOnSuccess? {...formAttributes}>
+```
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `form` | `UseFormReturn` | From `useSchemaForm` or `useForm`. |
+| `onSubmit` | `(values: TOut) => unknown` | Runs with validated values. Throw or reject to report errors. |
+| `onSuccess` | `(result, values) => void` | Runs after `onSubmit` resolves. |
+| `onError` | `(error: KitrError) => void` | Runs after errors are applied to fields. |
+| `resetOnSuccess` | `boolean` | Reset to default values after success. |
+
+Any other prop goes to the `<form>` element, which always has `noValidate`.
+
+## FormField
+
+```tsx
+<FormField name="email" label="Email" description="We never share it." className="...">
+  {children | ({ id, name, invalid, describedBy }) => ReactNode}
+</FormField>
+```
+
+Renders a wrapper with `data-kitr="field"` (and `data-invalid` when it has an error), a `<label>`, the description and the error message with `role="alert"`. It is headless: style it with your own classes or the `data-kitr` attributes.
+
+## useFieldProps and FieldInput
+
+```ts
+useFieldProps(): { id, 'aria-invalid', 'aria-describedby', name, onChange, onBlur, ref }
+```
+
+Props for the input inside the nearest `<FormField>`, including `form.register(name)`. `<FieldInput {...inputProps} />` is an `<input>` with these applied.
+
+## SubmitButton
+
+```tsx
+<SubmitButton pendingText="Saving…">Save</SubmitButton>
+```
+
+A `type="submit"` button, disabled with `aria-busy` while the form submits.
+
+## useFormStatus and useRootError
+
+```ts
+useFormStatus(): { pending: boolean; isValid: boolean }
+useRootError(): string | undefined
+```
+
+## applyServerErrors
+
+```ts
+function applyServerErrors(form: UseFormReturn, error: unknown): boolean
+```
+
+Maps a `KitrError`'s `fieldErrors` onto fields and everything else to `root.server`. `<Form>` calls it for you; use it when submitting another way. Returns `true` for validation errors.