@zeno-lib/forms 0.1.0 → 0.2.1

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,13 +1,28 @@
 {
   "name": "@zeno-lib/forms",
-  "version": "0.1.0",
+  "version": "0.2.1",
+  "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",
-    "./lib/*": "./src/lib/*.ts",
-    "./tanstack": "./src/tanstack.ts"
+    "./form-dialog": "./src/form-dialog.tsx",
+    "./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": {
@@ -41,15 +56,18 @@
     "@types/node": "25.6.0",
     "@types/react": "19.2.14",
     "@types/react-dom": "19.2.3",
+    "lucide-react": "^1.23.0",
+    "tsdown": "^0.22.14",
     "typescript": "7.0.2",
     "vite": "8.0.16",
-    "vitest": "4.1.11",
+    "vitest": "5.0.2",
     "zod": "^4.3.6",
+    "@zeno-lib/test": "^0.1.0",
     "@zeno-lib/typescript": "^1.1.0",
-    "@zeno-lib/ui": "^0.0.1",
-    "@zeno-lib/test": "^0.1.0"
+    "@zeno-lib/ui": "^0.0.1"
   },
   "scripts": {
+    "build": "tsdown",
     "test": "vitest --run",
     "test:watch": "vitest watch",
     "types:check": "tsc --noEmit"

package/src/create-form.tsx

@@ -4,13 +4,17 @@
 import { createZenoForm } from "@zeno-lib/forms"
 
 import { CheckboxField } from "./fields/checkbox-field"
+import { CheckboxGroupField } from "./fields/checkbox-group-field"
 import { ComboboxField } from "./fields/combobox-field"
 import { DatePickerField } from "./fields/date-picker-field"
 import { EmailField } from "./fields/email-field"
 import { InputField } from "./fields/input-field"
+import { MoneyField } from "./fields/money-field"
+import { MultiSelectField } from "./fields/multi-select-field"
 import { NumberField } from "./fields/number-field"
 import { OtpField } from "./fields/otp-field"
 import { PasswordField } from "./fields/password-field"
+import { PercentageField } from "./fields/percentage-field"
 import { RadioGroupField } from "./fields/radio-group-field"
 import { ResetButton } from "./fields/reset-button"
 import { SelectField } from "./fields/select-field"
@@ -18,24 +22,30 @@ import { SliderField } from "./fields/slider-field"
 import { SubmitButton } from "./fields/submit-button"
 import { SwitchField } from "./fields/switch-field"
 import { TextAreaField } from "./fields/textarea-field"
+import { YearField } from "./fields/year-field"
 
 // Wire the dropped-in field components into the headless factory. Edit the
 // field files under `./fields` freely — they use your own shadcn primitives.
 const { useAppForm, useForm, withFieldGroup, withForm } = createZenoForm({
   fieldComponents: {
     CheckboxField,
+    CheckboxGroupField,
     ComboboxField,
     DatePickerField,
     EmailField,
     InputField,
+    MoneyField,
+    MultiSelectField,
     NumberField,
     OtpField,
     PasswordField,
+    PercentageField,
     RadioGroupField,
     SelectField,
     SliderField,
     SwitchField,
     TextAreaField,
+    YearField,
   },
   formComponents: {
     ResetButton,

package/src/fields/checkbox-group-field.tsx

@@ -0,0 +1,160 @@
+"use client"
+
+import { describedBy } from "@zeno-lib/forms/lib/aria"
+import { useFieldContext } from "@zeno-lib/forms/lib/contexts"
+import {
+  useHideFieldErrors,
+  useIsFieldRequired,
+  useIsInvalid,
+} from "@zeno-lib/forms/lib/use-is-invalid"
+import type { ReactNode } from "react"
+import { Checkbox } from "@/components/ui/checkbox"
+import {
+  Field,
+  FieldContent,
+  FieldDescription,
+  FieldError,
+  FieldGroup,
+  FieldLabel,
+  FieldLegend,
+  FieldSet,
+} from "@/components/ui/field"
+import { cn } from "@/lib/utils"
+import { RequiredIndicator } from "../lib/required-indicator"
+
+type CheckboxGroupOption<V> = {
+  value: V
+  label: ReactNode
+  description?: ReactNode
+  disabled?: boolean
+}
+
+type CheckboxGroupFieldProps<V = string> = {
+  /**
+   * The options. Pass plain strings or numbers (value === label), or
+   * `{ value, label, description?, disabled? }` objects. The form value is the
+   * array of checked values, in the order of `items`.
+   */
+  items: readonly (CheckboxGroupOption<V> | V)[]
+  description?: ReactNode
+  label?: ReactNode
+  /** Stack the options (`"vertical"`, default) or wrap them in a row. */
+  orientation?: "horizontal" | "vertical"
+  disabled?: boolean
+  className?: string
+  /** Force the required `*` indicator on or off. Defaults to schema-derived. */
+  required?: boolean
+}
+
+function toOption<V>(item: CheckboxGroupOption<V> | V): CheckboxGroupOption<V> {
+  if (typeof item === "object" && item !== null && "value" in item) {
+    return item as CheckboxGroupOption<V>
+  }
+  return { label: String(item), value: item as V }
+}
+
+/** A set of checkboxes bound to one array value (`[]` when none checked). */
+function CheckboxGroupField<V = string>({
+  className,
+  description,
+  disabled,
+  items,
+  label,
+  orientation = "vertical",
+  required,
+}: CheckboxGroupFieldProps<V>) {
+  const field = useFieldContext<V[] | null | undefined>()
+  const errorId = `${field.name}-error`
+  const descriptionId = `${field.name}-description`
+  const isInvalid = useIsInvalid(field)
+  const hideErrors = useHideFieldErrors(field)
+  const showError = isInvalid && !hideErrors
+  const schemaRequired = useIsFieldRequired(field)
+  const isRequired = required ?? schemaRequired
+
+  const options = items.map(toOption)
+  const checked = field.state.value ?? []
+
+  const toggle = (value: V, on: boolean) => {
+    const next = new Set(checked)
+    if (on) {
+      next.add(value)
+    } else {
+      next.delete(value)
+    }
+    // Keep the stored order stable: the order of `items`, not click order.
+    field.handleChange(
+      options.map((option) => option.value).filter((v) => next.has(v))
+    )
+  }
+
+  return (
+    <FieldSet
+      aria-describedby={describedBy(
+        [description, descriptionId],
+        [showError, errorId]
+      )}
+      aria-invalid={isInvalid || undefined}
+      className={className}
+      data-field={field.name}
+      data-invalid={isInvalid}
+      disabled={disabled}
+    >
+      {label && (
+        <FieldLegend variant="label">
+          {label}
+          {isRequired && <RequiredIndicator />}
+        </FieldLegend>
+      )}
+      {description && (
+        <FieldDescription id={descriptionId}>{description}</FieldDescription>
+      )}
+      <FieldGroup
+        className={cn(
+          orientation === "horizontal" && "flex-row flex-wrap gap-x-6 *:w-auto"
+        )}
+        data-slot="checkbox-group"
+      >
+        {options.map((option, index) => {
+          const id = `${field.name}-${index}`
+          return (
+            <Field
+              data-invalid={isInvalid}
+              key={String(option.value)}
+              orientation="horizontal"
+            >
+              <Checkbox
+                aria-invalid={isInvalid || undefined}
+                checked={checked.includes(option.value)}
+                disabled={disabled || option.disabled}
+                id={id}
+                name={field.name}
+                onBlur={field.handleBlur}
+                onCheckedChange={(on) => toggle(option.value, on === true)}
+                value={String(option.value)}
+              />
+              {option.description ? (
+                <FieldContent>
+                  <FieldLabel className="font-normal" htmlFor={id}>
+                    {option.label}
+                  </FieldLabel>
+                  <FieldDescription>{option.description}</FieldDescription>
+                </FieldContent>
+              ) : (
+                <FieldLabel className="w-auto font-normal" htmlFor={id}>
+                  {option.label}
+                </FieldLabel>
+              )}
+            </Field>
+          )
+        })}
+      </FieldGroup>
+      {showError && (
+        <FieldError errors={field.state.meta.errors} id={errorId} />
+      )}
+    </FieldSet>
+  )
+}
+
+export type { CheckboxGroupFieldProps, CheckboxGroupOption }
+export { CheckboxGroupField }

package/src/fields/index.ts

@@ -1,12 +1,16 @@
 /** biome-ignore-all lint/performance/noBarrelFile: single import surface for all field components */
 export * from "./checkbox-field"
+export * from "./checkbox-group-field"
 export * from "./combobox-field"
 export * from "./date-picker-field"
 export * from "./email-field"
 export * from "./input-field"
+export * from "./money-field"
+export * from "./multi-select-field"
 export * from "./number-field"
 export * from "./otp-field"
 export * from "./password-field"
+export * from "./percentage-field"
 export * from "./radio-group-field"
 export * from "./reset-button"
 export * from "./select-field"
@@ -14,3 +18,4 @@ export * from "./slider-field"
 export * from "./submit-button"
 export * from "./switch-field"
 export * from "./textarea-field"
+export * from "./year-field"

package/src/fields/money-field.tsx

@@ -0,0 +1,123 @@
+"use client"
+
+import { useFieldContext } from "@zeno-lib/forms/lib/contexts"
+import { useFormattedNumber } from "@zeno-lib/forms/lib/use-formatted-number"
+import { type ReactNode, useMemo } from "react"
+import { InputGroupAddon, InputGroupText } from "@/components/ui/input-group"
+import { InputField, type InputFieldProps } from "./input-field"
+
+type MoneyFieldProps = Omit<
+  InputFieldProps,
+  "defaultValue" | "inputMode" | "onChange" | "onPaste" | "type" | "value"
+> & {
+  /** ISO 4217 code shown as an add-on, e.g. `"CHF"`, `"EUR"`, `"USD"`. */
+  currency?: string
+  /** How the currency add-on reads. Defaults to `"symbol"`. */
+  currencyDisplay?: "code" | "name" | "narrowSymbol" | "symbol"
+  /**
+   * Which side the currency add-on sits on. Defaults to the locale's own
+   * convention (`CHF 1’234` in `de-CH`, `1.234 €` in `de-DE`).
+   */
+  currencyPosition?: "end" | "start"
+  /**
+   * BCP 47 locale driving the group/decimal separators (`de-CH` →
+   * `1’234.50`). Defaults to the runtime locale.
+   */
+  locale?: string
+  /**
+   * Digits allowed after the decimal separator. Defaults to the currency's
+   * minor units (2 for CHF, 0 for JPY), or 2 without a currency.
+   */
+  fractionDigits?: number
+  /** Accept negative amounts. Defaults to `false`. */
+  allowNegative?: boolean
+  /** Clamp the amount on blur. */
+  min?: number
+  /** Clamp the amount on blur. */
+  max?: number
+}
+
+type CurrencyParts = {
+  label: string
+  position: "end" | "start"
+  fractionDigits: number
+}
+
+function getCurrencyParts(
+  locale: string | undefined,
+  currency: string,
+  currencyDisplay: NonNullable<MoneyFieldProps["currencyDisplay"]>
+): CurrencyParts {
+  const format = new Intl.NumberFormat(locale, {
+    currency,
+    currencyDisplay,
+    style: "currency",
+  })
+  const parts = format.formatToParts(1)
+  const currencyIndex = parts.findIndex((part) => part.type === "currency")
+  const integerIndex = parts.findIndex((part) => part.type === "integer")
+  return {
+    fractionDigits: format.resolvedOptions().maximumFractionDigits ?? 2,
+    label: parts[currencyIndex]?.value ?? currency,
+    position: currencyIndex > integerIndex ? "end" : "start",
+  }
+}
+
+/**
+ * Amount input with locale-aware thousands separators and a currency add-on.
+ * The form value is `number | null` (empty input → `null`).
+ */
+function MoneyField({
+  allowNegative = false,
+  children,
+  currency,
+  currencyDisplay = "symbol",
+  currencyPosition,
+  fractionDigits,
+  locale,
+  max,
+  min,
+  ...props
+}: MoneyFieldProps) {
+  const field = useFieldContext<number | null | undefined>()
+  const parts = useMemo(
+    () =>
+      currency ? getCurrencyParts(locale, currency, currencyDisplay) : null,
+    [currency, currencyDisplay, locale]
+  )
+  const digits = fractionDigits ?? parts?.fractionDigits ?? 2
+  const position = currencyPosition ?? parts?.position ?? "end"
+
+  const inputProps = useFormattedNumber({
+    allowNegative,
+    locale,
+    max,
+    maximumFractionDigits: digits,
+    min,
+    onBlur: field.handleBlur,
+    onValueChange: (next) => field.handleChange(next),
+    padFraction: true,
+    value: field.state.value,
+  })
+
+  let addon: ReactNode = null
+  if (parts) {
+    addon = (
+      <InputGroupAddon
+        align={position === "start" ? "inline-start" : "inline-end"}
+      >
+        <InputGroupText>{parts.label}</InputGroupText>
+      </InputGroupAddon>
+    )
+  }
+
+  return (
+    <InputField {...props} {...inputProps}>
+      {addon}
+      {children}
+    </InputField>
+  )
+}
+
+export type { MoneyFieldProps }
+export { MoneyField }