@zeno-lib/forms 0.2.0 → 0.2.2

package/dist/lib/use-rebased-default-values.mjs

@@ -0,0 +1,21 @@
+"use client";
+import { evaluate } from "@tanstack/react-form";
+import { useCallback, useRef } from "react";
+//#region src/lib/use-rebased-default-values.ts
+function useRebasedDefaultValues(callerDefaults) {
+	const liveForm = useRef(null);
+	const lastCallerDefaults = useRef(callerDefaults);
+	let defaultValues = callerDefaults;
+	if (evaluate(lastCallerDefaults.current, callerDefaults)) {
+		if (liveForm.current) defaultValues = liveForm.current.options.defaultValues;
+	} else lastCallerDefaults.current = callerDefaults;
+	const onMount = useCallback((props) => {
+		liveForm.current = props.formApi;
+	}, []);
+	return {
+		defaultValues,
+		onMount
+	};
+}
+//#endregion
+export { useRebasedDefaultValues };

package/dist/lib/use-unsaved-changes-warning.d.mts

@@ -0,0 +1,6 @@
+import { AnyFormApi } from "@tanstack/react-form";
+//#region src/lib/use-unsaved-changes-warning.d.ts
+type UnsavedChangesMode = "if-changed" | "if-touched";
+declare function useUnsavedChangesWarning(form: AnyFormApi, enabled: boolean | UnsavedChangesMode): void;
+//#endregion
+export { type UnsavedChangesMode, useUnsavedChangesWarning };

package/dist/lib/use-unsaved-changes-warning.mjs

@@ -0,0 +1,24 @@
+"use client";
+import { useSelector } from "@tanstack/react-form";
+import { useEffect } from "react";
+//#region src/lib/use-unsaved-changes-warning.ts
+function useUnsavedChangesWarning(form, enabled) {
+	let mode;
+	if (enabled === false) mode = null;
+	else if (enabled === true) mode = "if-changed";
+	else mode = enabled;
+	const dirty = useSelector(form.store, (state) => mode === "if-touched" ? state.isDirty : !state.isDefaultValue);
+	const isSubmitting = useSelector(form.store, (state) => state.isSubmitting);
+	const active = mode !== null && dirty && !isSubmitting;
+	useEffect(() => {
+		if (!active) return;
+		const handler = (event) => {
+			event.preventDefault();
+			event.returnValue = "";
+		};
+		window.addEventListener("beforeunload", handler);
+		return () => window.removeEventListener("beforeunload", handler);
+	}, [active]);
+}
+//#endregion
+export { useUnsavedChangesWarning };

package/dist/lib/validation-error.d.mts

@@ -0,0 +1,12 @@
+//#region src/lib/validation-error.d.ts
+type FieldMessage = string | readonly string[];
+declare class ValidationError extends Error {
+  readonly fields: Readonly<Record<string, FieldMessage>>;
+  readonly formError?: string;
+  constructor(fields: Readonly<Record<string, FieldMessage>>, options?: {
+    formError?: string;
+    message?: string;
+  });
+}
+//#endregion
+export { type FieldMessage, ValidationError };

package/dist/lib/validation-error.mjs

@@ -0,0 +1,11 @@
+//#region src/lib/validation-error.ts
+var ValidationError = class extends Error {
+	constructor(fields, options = {}) {
+		super(options.message ?? "Validation failed");
+		this.name = "ValidationError";
+		this.fields = fields;
+		this.formError = options.formError;
+	}
+};
+//#endregion
+export { ValidationError };

package/dist/lib/validation-logic.d.mts

@@ -0,0 +1,5 @@
+import { ValidationLogicFn } from "@tanstack/react-form";
+//#region src/lib/validation-logic.d.ts
+declare const blurThenChangeLogic: ValidationLogicFn;
+//#endregion
+export { blurThenChangeLogic };

package/dist/lib/validation-logic.mjs

@@ -0,0 +1,114 @@
+"use client";
+//#region src/lib/validation-logic.ts
+function pickLiveValidator(validators, isAsync) {
+	const fn = isAsync ? validators?.onChangeAsync ?? validators?.onBlurAsync : validators?.onChange ?? validators?.onBlur;
+	return fn ? {
+		cause: "change",
+		fn
+	} : void 0;
+}
+function shouldRunFormChange(form) {
+	if (form.state.submissionAttempts > 0) return true;
+	return Object.values(form.state.fieldMeta).some((meta) => meta?.isBlurred === true);
+}
+function fieldLevelLogic(props) {
+	const { event, validators, form } = props;
+	const run = props.runValidation;
+	if (!validators) return run({
+		form,
+		validators: []
+	});
+	const isAsync = event.async;
+	if (event.type === "mount") return run({
+		form,
+		validators: isAsync ? [] : [{
+			cause: "mount",
+			fn: validators.onMount
+		}]
+	});
+	if (event.type === "change") return run({
+		form,
+		validators: [{
+			cause: "change",
+			fn: isAsync ? validators.onChangeAsync : validators.onChange
+		}]
+	});
+	if (event.type === "blur") return run({
+		form,
+		validators: [{
+			cause: "blur",
+			fn: isAsync ? validators.onBlurAsync : validators.onBlur
+		}]
+	});
+	if (event.type === "submit") return run({
+		form,
+		validators: [
+			{
+				cause: "change",
+				fn: isAsync ? validators.onChangeAsync : validators.onChange
+			},
+			{
+				cause: "blur",
+				fn: isAsync ? validators.onBlurAsync : validators.onBlur
+			},
+			{
+				cause: "submit",
+				fn: isAsync ? validators.onSubmitAsync : validators.onSubmit
+			}
+		]
+	});
+	return run({
+		form,
+		validators: []
+	});
+}
+function buildSubmitValidators(validators, isAsync, liveValidator) {
+	return [
+		...liveValidator ? [liveValidator] : [],
+		{
+			cause: "submit",
+			fn: isAsync ? validators.onSubmitAsync : validators.onSubmit
+		},
+		...isAsync ? [] : [{
+			cause: "server",
+			fn: () => void 0
+		}]
+	];
+}
+function blurThenChangeLogicImpl(props) {
+	if (props.event.fieldName !== void 0) return fieldLevelLogic(props);
+	const { event, validators, form } = props;
+	const run = props.runValidation;
+	if (!validators) return run({
+		form,
+		validators: []
+	});
+	const isAsync = event.async;
+	const liveValidator = pickLiveValidator(validators, isAsync);
+	if (event.type === "mount") return run({
+		form,
+		validators: isAsync ? [] : [{
+			cause: "mount",
+			fn: validators.onMount
+		}]
+	});
+	if (event.type === "blur") return run({
+		form,
+		validators: liveValidator ? [liveValidator] : []
+	});
+	if (event.type === "change") return run({
+		form,
+		validators: liveValidator && shouldRunFormChange(form) ? [liveValidator] : []
+	});
+	if (event.type === "submit") return run({
+		form,
+		validators: buildSubmitValidators(validators, isAsync, liveValidator)
+	});
+	return run({
+		form,
+		validators: []
+	});
+}
+const blurThenChangeLogic = blurThenChangeLogicImpl;
+//#endregion
+export { blurThenChangeLogic };

package/dist/lib/validation-modes.d.mts

@@ -0,0 +1,16 @@
+import { AnyFormApi } from "@tanstack/react-form";
+//#region src/lib/validation-modes.d.ts
+type ValidationMode = "change" | "blur" | "submit" | "blur-then-change";
+declare const DEFAULT_VALIDATION_MODE: ValidationMode;
+type ZenoFormState = {
+  validation: ValidationMode;
+  hideFieldErrors: boolean;
+  requiredIndicator: boolean;
+  requiredFields: ReadonlySet<string>;
+};
+declare function setFormZenoState(form: AnyFormApi, state: Partial<ZenoFormState>): void;
+declare function getFormValidationMode(form: AnyFormApi): ValidationMode;
+declare function getFormHideFieldErrors(form: AnyFormApi): boolean;
+declare function isFieldRequired(form: AnyFormApi, name: string): boolean;
+//#endregion
+export { DEFAULT_VALIDATION_MODE, type ValidationMode, getFormHideFieldErrors, getFormValidationMode, isFieldRequired, setFormZenoState };

package/dist/lib/validation-modes.mjs

@@ -0,0 +1,38 @@
+"use client";
+import { toRequiredPathKey } from "./schema-required.mjs";
+//#region src/lib/validation-modes.ts
+const DEFAULT_VALIDATION_MODE = "blur-then-change";
+const DEFAULT_FORM_STATE = {
+	hideFieldErrors: false,
+	requiredFields: /* @__PURE__ */ new Set(),
+	requiredIndicator: true,
+	validation: DEFAULT_VALIDATION_MODE
+};
+const formZenoState = /* @__PURE__ */ new WeakMap();
+function stateKey(form) {
+	return form.store;
+}
+function setFormZenoState(form, state) {
+	const key = stateKey(form);
+	const current = formZenoState.get(key) ?? DEFAULT_FORM_STATE;
+	formZenoState.set(key, {
+		...current,
+		...state
+	});
+}
+function getFormZenoState(form) {
+	return formZenoState.get(stateKey(form)) ?? DEFAULT_FORM_STATE;
+}
+function getFormValidationMode(form) {
+	return getFormZenoState(form).validation;
+}
+function getFormHideFieldErrors(form) {
+	return getFormZenoState(form).hideFieldErrors;
+}
+function isFieldRequired(form, name) {
+	const state = getFormZenoState(form);
+	if (!state.requiredIndicator) return false;
+	return state.requiredFields.has(toRequiredPathKey(name));
+}
+//#endregion
+export { DEFAULT_VALIDATION_MODE, getFormHideFieldErrors, getFormValidationMode, isFieldRequired, setFormZenoState };

package/dist/tanstack.d.mts

@@ -0,0 +1 @@
+export * from "@tanstack/react-form";

package/dist/tanstack.mjs

@@ -0,0 +1,2 @@
+export * from "@tanstack/react-form";
+export {};

package/package.json

@@ -1,22 +1,51 @@
 {
   "name": "@zeno-lib/forms",
-  "version": "0.2.0",
+  "version": "0.2.2",
+  "repository": {
+    "url": "https://github.com/zeno-lib/zeno.git",
+    "directory": "packages/forms"
+  },
+  "type": "module",
   "exports": {
-    ".": "./src/index.ts",
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs",
+      "default": "./dist/index.mjs"
+    },
     "./create-form": "./src/create-form.tsx",
     "./form-dialog": "./src/form-dialog.tsx",
-    "./lib/*": "./src/lib/*.ts",
-    "./tanstack": "./src/tanstack.ts"
+    "./lib/*": {
+      "types": "./dist/lib/*.d.mts",
+      "import": "./dist/lib/*.mjs",
+      "default": "./dist/lib/*.mjs"
+    },
+    "./tanstack": {
+      "types": "./dist/tanstack.d.mts",
+      "import": "./dist/tanstack.mjs",
+      "default": "./dist/tanstack.mjs"
+    }
   },
   "files": [
+    "dist",
     "src"
   ],
-  "publishConfig": {
-    "access": "public"
+  "dependencies": {
+    "@tanstack/react-form": "1.33.5",
+    "@tanstack/react-form-nextjs": "1.33.5"
   },
-  "repository": {
-    "url": "https://github.com/zeno-lib/zeno.git",
-    "directory": "packages/forms"
+  "devDependencies": {
+    "@types/node": "26.6.4",
+    "@types/react": "19.3.0",
+    "@types/react-dom": "19.3.0",
+    "@zeno-lib/test": "^0.1.1",
+    "@zeno-lib/typescript": "^1.1.0",
+    "@zeno-lib/ui": "^0.0.1",
+    "lucide-react": "^1.52.0",
+    "tsdown": "^0.23.0",
+    "typescript": "7.0.2",
+    "vite": "8.3.3",
+    "vitest": "5.0.3",
+    "zod": "^4.6.5"
   },
   "peerDependencies": {
     "@tanstack/react-devtools": ">=0.10",
@@ -34,24 +63,12 @@
       "optional": true
     }
   },
-  "dependencies": {
-    "@tanstack/react-form": "1.33.5",
-    "@tanstack/react-form-nextjs": "1.33.5"
-  },
-  "devDependencies": {
-    "@types/node": "25.6.0",
-    "@types/react": "19.2.14",
-    "@types/react-dom": "19.2.3",
-    "lucide-react": "^1.23.0",
-    "typescript": "7.0.2",
-    "vite": "8.0.16",
-    "vitest": "4.1.11",
-    "zod": "^4.3.6",
-    "@zeno-lib/typescript": "^1.1.0",
-    "@zeno-lib/ui": "^0.0.1",
-    "@zeno-lib/test": "^0.1.0"
+  "publishConfig": {
+    "access": "public"
   },
   "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch --no-clean",
     "test": "vitest --run",
     "test:watch": "vitest watch",
     "types:check": "tsc --noEmit"

package/src/fields/combobox-field.tsx

@@ -124,7 +124,7 @@ function ComboboxField<T = string>({
         items={items}
         onInputValueChange={onInputValueChange}
         onValueChange={(next) => {
-          if (next == null) {
+          if (next === null) {
             field.handleChange(undefined)
             return
           }
@@ -143,7 +143,7 @@ function ComboboxField<T = string>({
           name={field.name}
           onBlur={field.handleBlur}
           placeholder={placeholder}
-          showClear={showClear && value != null && value !== "" && !loading}
+          showClear={showClear && value !== null && value !== "" && !loading}
         >
           {loading && (
             <InputGroupAddon align="inline-end">

package/src/fields/date-picker-field.tsx

@@ -68,7 +68,7 @@ function DatePickerField({
   const schemaRequired = useIsFieldRequired(field)
   const isRequired = required ?? schemaRequired
 
-  const value = field.state.value
+  const { value } = field.state
   const empty = !value
 
   return (

package/src/fields/number-field.tsx

@@ -11,7 +11,7 @@ type NumberFieldProps = Omit<
 
 function NumberField(props: NumberFieldProps) {
   const field = useFieldContext<number | undefined>()
-  const value = field.state.value
+  const { value } = field.state
   const inputValue =
     typeof value === "number" && !Number.isNaN(value) ? value : ""
 

package/src/fields/slider-field.tsx

@@ -51,12 +51,14 @@ function SliderField({
   const schemaRequired = useIsFieldRequired(field)
   const isRequired = required ?? schemaRequired
 
-  const value = field.state.value
+  const { value } = field.state
   const readout = formatValue && value !== undefined ? formatValue(value) : null
+  // Not a truthiness check: a formatter may return the number 0, which must still render.
+  const hasReadout = readout !== null && readout !== undefined
 
   return (
     <Field data-field={field.name} data-invalid={isInvalid}>
-      {(label || readout) && (
+      {(label || hasReadout) && (
         <FieldContent className="flex-row items-center justify-between">
           {label && (
             <FieldLabel htmlFor={field.name}>
@@ -64,7 +66,7 @@ function SliderField({
               {isRequired && <RequiredIndicator />}
             </FieldLabel>
           )}
-          {readout && (
+          {hasReadout && (
             <span className="text-muted-foreground text-sm tabular-nums">
               {readout}
             </span>
@@ -81,9 +83,9 @@ function SliderField({
         name={field.name}
         onBlur={field.handleBlur}
         onValueChange={(next) => {
-          const value: SliderValue =
+          const nextValue: SliderValue =
             typeof next === "number" ? next : Array.from(next)
-          field.handleChange(value)
+          field.handleChange(nextValue)
         }}
         value={value}
         {...props}

package/src/form-dialog.tsx

@@ -63,8 +63,8 @@ type DialogForm<TValues> = {
     }
   }
   readonly state: DialogFormState
-  handleSubmit(): unknown
-  reset(values?: TValues): void
+  handleSubmit: () => unknown
+  reset: (values?: TValues) => void
 }
 
 type FormDialogProps<TValues> = {

package/src/lib/formatted-number.ts

@@ -84,7 +84,7 @@ function formatNumber(
     useGrouping = true,
   }: FormatNumberOptions
 ): string {
-  if (value == null || !Number.isFinite(value)) {
+  if (value === null || value === undefined || !Number.isFinite(value)) {
     return ""
   }
   return normalizeMinus(
@@ -236,10 +236,10 @@ function parseLocaleNumber(text: string, locale?: string): number | null {
 // the same logical place after separators were inserted or removed.
 function countSignificant(text: string, end: number, decimal: string): number {
   let count = 0
-  for (let i = 0; i < end && i < text.length; i++) {
+  for (let i = 0; i < end && i < text.length; i += 1) {
     const char = text[i] as string
     if (DIGIT.test(char) || char === decimal || MINUS_SIGNS.test(char)) {
-      count++
+      count += 1
     }
   }
   return count
@@ -254,10 +254,10 @@ function caretForSignificant(
     return 0
   }
   let count = 0
-  for (let i = 0; i < text.length; i++) {
+  for (let i = 0; i < text.length; i += 1) {
     const char = text[i] as string
     if (DIGIT.test(char) || char === decimal || char === "-") {
-      count++
+      count += 1
       if (count === significant) {
         return i + 1
       }

package/src/lib/schema-defaults.ts

@@ -37,7 +37,7 @@ function getDef(node: SchemaNode | undefined): SchemaDef | undefined {
 
 function extractDefaultForField(node: SchemaNode): ExtractResult {
   let current: SchemaNode | undefined = node
-  for (let depth = 0; depth < MAX_WRAPPER_DEPTH; depth++) {
+  for (let depth = 0; depth < MAX_WRAPPER_DEPTH; depth += 1) {
     const def: SchemaDef | undefined = getDef(current)
     if (!def?.type) {
       return { ok: false }

package/src/lib/schema-required.test.ts

@@ -166,7 +166,7 @@ describe("getRequiredPaths", () => {
     const schema: StandardSchemaLike = {
       "~standard": {
         validate: (value) => {
-          const profile = (value as { profile?: unknown }).profile
+          const { profile } = value as { profile?: unknown }
           return profile === undefined
             ? { issues: [{ expected: "Object", path: [{ key: "profile" }] }] }
             : {

package/src/lib/schema-required.ts

@@ -50,6 +50,7 @@ const INDEX_SEGMENT = /^\d+$/
 const INDEX_IN_NAME = /\[\d+\]|\.(\d+)(?=\.|\[|$)/g
 
 function pathKey(part: PathPart): PropertyKey {
+  // biome-ignore lint/suspicious/noUnnecessaryConditions: issue paths come from third-party validators at runtime, and a non-conforming `null` segment would make `in` throw.
   if (typeof part === "object" && part !== null && "key" in part) {
     return part.key
   }
@@ -93,10 +94,7 @@ function probeContainer(expected: unknown): unknown {
   if (kind === "object") {
     return {}
   }
-  if (kind === "array") {
-    return [{}]
-  }
-  return
+  return kind === "array" ? [{}] : undefined
 }
 
 // Write `value` at `keys` inside `root`, only where nothing is set yet.
@@ -140,7 +138,7 @@ function validateSync(
 function getRequiredPaths(schema: StandardSchemaLike): Set<string> {
   const required = new Set<string>()
   const probe: Record<PropertyKey, unknown> = {}
-  for (let depth = 0; depth < MAX_PROBE_DEPTH; depth++) {
+  for (let depth = 0; depth < MAX_PROBE_DEPTH; depth += 1) {
     const issues = validateSync(schema, probe)
     if (!issues) {
       return required

package/src/lib/validation-logic.test.ts

@@ -32,7 +32,6 @@ function makeRun() {
   const runValidation = vi.fn(
     (props: { form: AnyFormApi; validators: ObservedValidator[] }) => {
       observed.push(props.validators)
-      return
     }
   )
   return { observed, runValidation }

package/src/slider-field.test.tsx

@@ -0,0 +1,30 @@
+import { cleanup, render, screen } from "@zeno-lib/test/testing-library"
+import { afterEach, describe, expect, test, vi } from "vitest"
+import { Form, FormProvider, useForm } from "./create-form"
+
+afterEach(() => {
+  cleanup()
+})
+
+describe("SliderField", () => {
+  function Harness() {
+    const form = useForm({ defaultValues: { volume: 0 }, onSubmit: vi.fn() })
+    const { SliderField } = form
+    return (
+      <FormProvider form={form}>
+        <Form>
+          <SliderField
+            formatValue={(value) => value}
+            label="Volume"
+            name="volume"
+          />
+        </Form>
+      </FormProvider>
+    )
+  }
+
+  test("renders a numeric readout of 0", () => {
+    render(<Harness />)
+    expect(screen.getByText("0").tagName).toBe("SPAN")
+  })
+})