@zeno-lib/forms 0.1.0 → 0.2.0

package/src/lib/submit-action.test-d.ts

@@ -0,0 +1,83 @@
+import { expectTypeOf, test } from "vitest"
+import { z } from "zod"
+import { useForm } from "../create-form"
+import type { ActionResult } from "./action-result"
+import { submitAction } from "./submit-action"
+
+const schema = z.object({
+  name: z.string(),
+  percentage: z.string().transform(Number),
+})
+type Values = z.input<typeof schema>
+
+// What `defineFormAction` in `@zeno-lib/db/next` produces, restated here so
+// the structural contract is pinned without depending on that package.
+type ServerActionError = {
+  readonly fieldErrors: Record<string, string[]>
+  readonly formErrors: string[]
+}
+type ServerActionResult<T> =
+  | { readonly ok: true; readonly data: T }
+  | { readonly ok: false; readonly error: ServerActionError }
+
+declare function saveShare(input: {
+  name: string
+  percentage: number
+}): Promise<ServerActionResult<{ id: number }>>
+declare function saveRaw(input: Values): Promise<ServerActionResult<Values>>
+
+test("infers the data type from the action, with no explicit generics", () => {
+  useForm({
+    defaultValues: { name: "", percentage: "" },
+    onSubmit: async (submit) => {
+      const result = await submitAction(submit, saveShare, { schema })
+      expectTypeOf(result).toEqualTypeOf<ActionResult<{ id: number }>>()
+      if (result.ok) {
+        expectTypeOf(result.data).toEqualTypeOf<{ id: number }>()
+      }
+    },
+  })
+})
+
+test("without a schema the action must accept the form values", () => {
+  useForm({
+    defaultValues: { name: "", percentage: "" },
+    onSubmit: (submit) => submitAction(submit, saveRaw, { reset: true }),
+  })
+  useForm({
+    defaultValues: { name: "", percentage: "" },
+    // @ts-expect-error: the action wants `percentage: number`; pass `schema` to transform.
+    onSubmit: (submit) => submitAction(submit, saveShare),
+  })
+})
+
+test("with a schema the action receives the schema output", () => {
+  useForm({
+    defaultValues: { name: "", percentage: "" },
+    onSubmit: (submit) =>
+      // @ts-expect-error: the schema outputs `percentage: number`, the action wants a string.
+      submitAction(submit, saveRaw, { schema }),
+  })
+})
+
+test("reset: true is only offered when the data has the form's shape", () => {
+  useForm({
+    defaultValues: { name: "", percentage: "" },
+    onSubmit: (submit) =>
+      // @ts-expect-error: `{ id: number }` is not the form's values.
+      submitAction(submit, saveShare, { reset: true, schema }),
+  })
+  useForm({
+    defaultValues: { name: "", percentage: "" },
+    onSubmit: (submit) =>
+      submitAction(submit, saveShare, { reset: "values", schema }),
+  })
+  useForm({
+    defaultValues: { name: "", percentage: "" },
+    onSubmit: (submit) =>
+      submitAction(submit, saveShare, {
+        reset: (data) => ({ name: String(data.id), percentage: "" }),
+        schema,
+      }),
+  })
+})

package/src/lib/submit-action.ts

@@ -0,0 +1,178 @@
+import type { AnyFormApi } from "@tanstack/react-form"
+
+import {
+  type ActionError,
+  type ActionIssue,
+  type ActionResult,
+  toActionError,
+} from "./action-result"
+import { applyValidationError } from "./apply-validation-error"
+import { ValidationError } from "./validation-error"
+
+// Write an action's failure onto the form. Field messages go through
+// `applyValidationError`, so they live in `errorMap.onChange` and clear the
+// moment the user edits that field (other fields keep theirs). A message
+// keyed by a name no mounted field registered would be invisible yet still
+// mark the form invalid, so it is folded into the form-level message instead,
+// next to `formErrors` (one message per line).
+//
+// Why not `setErrorMap({ onServer: { form, fields } })`: the default
+// `blur-then-change` logic never clears `onServer` on an edit, only on the
+// next submit, and TanStack's `defaultValidationLogic` clears every field's
+// `onServer` error on any single edit. Neither matches "clears when this field
+// changes".
+function applyActionError(formApi: FormApiLike, error: ActionError): void {
+  const fields: Record<string, readonly string[]> = {}
+  const formErrors = [...error.formErrors]
+  const fieldInfo = formApi.fieldInfo as Record<
+    string,
+    { instance?: unknown } | undefined
+  >
+  for (const [name, messages] of Object.entries(error.fieldErrors)) {
+    if (messages.length === 0) {
+      continue
+    }
+    if (fieldInfo[name]?.instance) {
+      fields[name] = messages
+    } else {
+      formErrors.push(...messages)
+    }
+  }
+  applyValidationError(
+    formApi as AnyFormApi,
+    new ValidationError(
+      fields,
+      formErrors.length > 0 ? { formError: formErrors.join("\n") } : {}
+    )
+  )
+}
+
+type SchemaResult<TOutput> =
+  | { readonly value: TOutput; readonly issues?: undefined }
+  | { readonly issues: readonly ActionIssue[] }
+
+// The Standard Schema slice `submitAction` reads: `validate` (never throws)
+// and the output type. Zod 4, Valibot and ArkType schemas all fit.
+type SubmitActionSchema<TOutput> = {
+  readonly "~standard": {
+    readonly validate: (
+      value: unknown
+    ) => SchemaResult<TOutput> | Promise<SchemaResult<TOutput>>
+    readonly types?:
+      | { readonly input: unknown; readonly output: TOutput }
+      | undefined
+  }
+}
+
+// The members of a form API the helpers touch. Typed as a slice rather than
+// `AnyFormApi` so a concrete `FormApi<Values, …, never>` (what `onSubmit`
+// receives) is assignable without a cast.
+type FormApiLike = Pick<
+  AnyFormApi,
+  | "fieldInfo"
+  | "getFieldMeta"
+  | "getFieldValue"
+  | "setErrorMap"
+  | "setFieldMeta"
+  | "store"
+>
+
+type SubmitProps<TValues> = {
+  readonly value: TValues
+  readonly formApi: FormApiLike & {
+    reset: (values?: TValues, opts?: { keepDefaultValues?: boolean }) => void
+  }
+}
+
+type Action<TInput, TData> = (input: TInput) => Promise<ActionResult<TData>>
+
+// `true` rebases the form on the returned data (only offered when the data
+// has the form's shape), `"values"` on the values just submitted, and a
+// function on whatever it maps the data to.
+type ResetOption<TValues, TData> =
+  | "values"
+  | ((data: TData) => TValues)
+  | ([TData] extends [TValues] ? true : never)
+
+type SubmitActionOptions<TValues, TData> = {
+  /**
+   * After a successful action, `formApi.reset(...)` so the saved values
+   * become the pristine baseline (clears `isDirty` and the unsaved-changes
+   * warning). Off by default.
+   */
+  reset?: ResetOption<TValues, TData>
+}
+
+type SubmitActionSchemaOptions<TValues, TOutput, TData> = SubmitActionOptions<
+  TValues,
+  TData
+> & {
+  /**
+   * Parsed on the client before the call: `onSubmit` receives the form's
+   * input values, and the action gets the schema's output. A failure is
+   * applied to the form and the action is never called.
+   */
+  schema: SubmitActionSchema<TOutput>
+}
+
+/**
+ * Call a server action from `onSubmit` and route its result back into the
+ * form. Pass `onSubmit`'s own argument straight through:
+ *
+ * ```ts
+ * onSubmit: (submit) => submitAction(submit, saveProfile, { reset: true, schema })
+ * ```
+ *
+ * On `{ ok: false }` the field errors land on their fields (array paths like
+ * `owners[0].percentage` included) and clear as each field is edited. On
+ * `{ ok: true }` the form is optionally reset. Either way the result is
+ * returned, so the caller can redirect or toast on `result.ok`. A thrown
+ * error (network, auth, a bug) propagates unchanged.
+ */
+function submitAction<TValues, TOutput, TData>(
+  props: SubmitProps<TValues>,
+  action: Action<TOutput, TData>,
+  options: SubmitActionSchemaOptions<TValues, TOutput, TData>
+): Promise<ActionResult<TData>>
+function submitAction<TValues, TData>(
+  props: SubmitProps<TValues>,
+  action: Action<NoInfer<TValues>, TData>,
+  options?: SubmitActionOptions<TValues, TData>
+): Promise<ActionResult<TData>>
+async function submitAction(
+  props: SubmitProps<unknown>,
+  action: Action<unknown, unknown>,
+  options: { reset?: unknown; schema?: SubmitActionSchema<unknown> } = {}
+): Promise<ActionResult<unknown>> {
+  const { formApi, value } = props
+  let input: unknown = value
+
+  if (options.schema) {
+    const parsed = await options.schema["~standard"].validate(value)
+    if (parsed.issues) {
+      const error = toActionError(parsed.issues)
+      applyActionError(formApi, error)
+      return { error, ok: false }
+    }
+    input = parsed.value
+  }
+
+  const result = await action(input)
+  if (!result.ok) {
+    applyActionError(formApi, result.error)
+    return result
+  }
+
+  const { reset } = options
+  if (reset === true) {
+    formApi.reset(result.data)
+  } else if (reset === "values") {
+    formApi.reset(value)
+  } else if (typeof reset === "function") {
+    formApi.reset((reset as (data: unknown) => unknown)(result.data))
+  }
+  return result
+}
+
+export type { FormApiLike, SubmitActionOptions, SubmitActionSchema }
+export { applyActionError, submitAction }

package/src/lib/use-form-dialog.ts

@@ -0,0 +1,184 @@
+"use client"
+
+import { useCallback, useRef, useState } from "react"
+
+type FormDialogOpenOptions<TValues> = {
+  /**
+   * Values to edit in this session. Omit to start from the hook's
+   * `defaultValues` (a blank "create" form).
+   */
+  defaultValues?: TValues
+  /** Field `name` to focus once the dialog opens, e.g. `"email"`. */
+  focus?: string
+}
+
+type UseFormDialogOptions<TValues> = {
+  /** Values a session starts from when `open()` gets none. */
+  defaultValues?: TValues
+}
+
+type FormDialogController<TValues> = {
+  /** Whether the dialog is open. */
+  isOpen: boolean
+  /** Open a new editing session, optionally with its own values and focus. */
+  open: (options?: FormDialogOpenOptions<TValues>) => void
+  /**
+   * Close without the unsaved-changes prompt. Close affordances inside the
+   * dialog (Cancel, ×, Escape, outside press) go through the guard instead.
+   */
+  close: () => void
+  /**
+   * The current session's defaults. Pass them to `useForm({ defaultValues })`
+   * so the form's defaults follow the session (see the pitfall below).
+   */
+  defaultValues: TValues | undefined
+  /** Field to focus when the current session opened. */
+  focus: string | undefined
+  /** Increments on every `open()`; lets the dialog reset once per session. */
+  session: number
+}
+
+type SessionState<TValues> = {
+  isOpen: boolean
+  defaultValues: TValues | undefined
+  focus: string | undefined
+  session: number
+}
+
+/**
+ * Open/close state for a dialog-hosted form, one "session" per `open()`.
+ *
+ * Why the hook owns the defaults: TanStack Form ignores new `defaultValues`
+ * once the form is touched, and a `form.reset(values)` is undone on the next
+ * render when `useForm` still receives the old `defaultValues` (the form is
+ * untouched again after the reset, so TanStack re-applies its options).
+ * Passing `dialog.defaultValues` to `useForm` keeps the two in agreement;
+ * the `FormDialog` component then calls `form.reset(defaults)` at the start
+ * of every session.
+ */
+function useFormDialog<TValues>(
+  options: UseFormDialogOptions<TValues> = {}
+): FormDialogController<TValues> {
+  const latestDefaults = useRef(options.defaultValues)
+  latestDefaults.current = options.defaultValues
+
+  const [state, setState] = useState<SessionState<TValues>>(() => ({
+    defaultValues: options.defaultValues,
+    focus: undefined,
+    isOpen: false,
+    session: 0,
+  }))
+
+  const open = useCallback((openOptions?: FormDialogOpenOptions<TValues>) => {
+    setState((previous) => ({
+      defaultValues: openOptions?.defaultValues ?? latestDefaults.current,
+      focus: openOptions?.focus,
+      isOpen: true,
+      session: previous.session + 1,
+    }))
+  }, [])
+
+  const close = useCallback(() => {
+    setState((previous) =>
+      previous.isOpen ? { ...previous, isOpen: false } : previous
+    )
+  }, [])
+
+  return {
+    close,
+    defaultValues: state.defaultValues,
+    focus: state.focus,
+    isOpen: state.isOpen,
+    open,
+    session: state.session,
+  }
+}
+
+type UseLeaveGuardOptions = {
+  /** Whether leaving now would lose changes. */
+  hasUnsavedChanges: boolean
+}
+
+type LeaveGuard = {
+  /**
+   * Run `proceed` now when there's nothing to lose, otherwise hold it until
+   * the user confirms. A newer request replaces a held one.
+   */
+  requestLeave: (proceed: () => void) => void
+  /** Whether a leave is waiting on the user's answer (show your confirm UI). */
+  isConfirming: boolean
+  /** The user chose to discard: run the held leave. */
+  confirmLeave: () => void
+  /** The user chose to stay: drop the held leave. */
+  cancelLeave: () => void
+}
+
+/** Ask before a leave (close, navigate, switch record) drops unsaved changes. */
+function useLeaveGuard({
+  hasUnsavedChanges,
+}: UseLeaveGuardOptions): LeaveGuard {
+  const pending = useRef<(() => void) | null>(null)
+  const [isConfirming, setIsConfirming] = useState(false)
+
+  const requestLeave = useCallback(
+    (proceed: () => void) => {
+      if (!hasUnsavedChanges) {
+        proceed()
+        return
+      }
+      pending.current = proceed
+      setIsConfirming(true)
+    },
+    [hasUnsavedChanges]
+  )
+
+  const confirmLeave = useCallback(() => {
+    const proceed = pending.current
+    pending.current = null
+    setIsConfirming(false)
+    proceed?.()
+  }, [])
+
+  const cancelLeave = useCallback(() => {
+    pending.current = null
+    setIsConfirming(false)
+  }, [])
+
+  return { cancelLeave, confirmLeave, isConfirming, requestLeave }
+}
+
+const FOCUSABLE =
+  'input:not([type="hidden"]):not([disabled]), textarea:not([disabled]), select:not([disabled]), button:not([disabled]), [tabindex]:not([tabindex="-1"])'
+
+function attributeSelector(attribute: string, value: string): string {
+  return `[${attribute}="${value.replace(/["\\]/g, "\\$&")}"]`
+}
+
+/**
+ * Find the element to focus for field `name` inside `root`: the control with
+ * `id={name}` (what the shipped fields render), else the first focusable
+ * element inside the field root marked `data-field={name}`.
+ */
+function findFieldElement(
+  root: ParentNode | null | undefined,
+  name: string
+): HTMLElement | null {
+  if (!root) {
+    return null
+  }
+  const byId = root.querySelector<HTMLElement>(attributeSelector("id", name))
+  if (byId) {
+    return byId
+  }
+  const fieldRoot = root.querySelector(attributeSelector("data-field", name))
+  return fieldRoot?.querySelector<HTMLElement>(FOCUSABLE) ?? null
+}
+
+export type {
+  FormDialogController,
+  FormDialogOpenOptions,
+  LeaveGuard,
+  UseFormDialogOptions,
+  UseLeaveGuardOptions,
+}
+export { findFieldElement, useFormDialog, useLeaveGuard }

package/src/lib/use-formatted-number.ts

@@ -0,0 +1,235 @@
+"use client"
+
+import {
+  type ChangeEvent,
+  type ClipboardEvent,
+  useLayoutEffect,
+  useReducer,
+  useRef,
+  useState,
+} from "react"
+
+import {
+  formatNumber,
+  mapCaret,
+  parseLocaleNumber,
+  parseTypedNumber,
+  roundTo,
+} from "./formatted-number"
+
+type UseFormattedNumberOptions = {
+  /** The stored value. `null`/`undefined` renders an empty input. */
+  value: number | null | undefined
+  /** Called with the parsed value when the user types, pastes, or blurs. */
+  onValueChange: (value: number | null) => void
+  /** Called after the blur re-format (wire the field's `handleBlur` here). */
+  onBlur?: () => void
+  /** BCP 47 locale for separators. Defaults to the runtime locale. */
+  locale?: string
+  /** Digits allowed after the decimal separator. Defaults to `2`. */
+  maximumFractionDigits?: number
+  /**
+   * Pad a non-integer value to `maximumFractionDigits` on blur (`12.5` →
+   * `12.50`). Integers stay bare (`12`). Defaults to `false`.
+   */
+  padFraction?: boolean
+  /** Insert thousands separators. Defaults to `true`. */
+  useGrouping?: boolean
+  /** Accept a leading minus. Defaults to `true`. */
+  allowNegative?: boolean
+  /** Drop integer digits beyond this count while typing. */
+  maxIntegerDigits?: number
+  /** Clamp the stored value on blur. */
+  min?: number
+  /** Clamp the stored value on blur. */
+  max?: number
+  /**
+   * Map the stored value to the number shown in the input, e.g.
+   * `(v) => v * 100` to edit a `0–1` fraction as a percentage. Pair with
+   * `fromDisplay`.
+   */
+  toDisplay?: (value: number) => number
+  /** Inverse of `toDisplay`. */
+  fromDisplay?: (display: number) => number
+}
+
+type FormattedNumberInputProps = {
+  inputMode: "decimal" | "numeric"
+  onBlur: () => void
+  onChange: (event: ChangeEvent<HTMLInputElement>) => void
+  onPaste: (event: ClipboardEvent<HTMLInputElement>) => void
+  type: "text"
+  value: string
+}
+
+const identity = (value: number) => value
+
+function clamp(value: number, min?: number, max?: number): number {
+  let next = value
+  if (min !== undefined && next < min) {
+    next = min
+  }
+  if (max !== undefined && next > max) {
+    next = max
+  }
+  return next
+}
+
+/**
+ * Headless, locale-aware formatted number input.
+ *
+ * Keeps the input's text in local state so the user can type freely
+ * (`"1’2"`, `"12."`), re-inserting group separators as they type while
+ * holding the caret in place, and parses the text into a `number | null`
+ * for the form. Pasted text is parsed leniently (`"CHF 1'234.50"`,
+ * `"1.234,50"`). On blur the value is clamped to `min`/`max` and the text
+ * re-formatted. External value changes (e.g. `form.reset`) re-sync the text.
+ *
+ * Returns props to spread on an `<input>`; UI-free, so any input component
+ * can use it.
+ */
+function useFormattedNumber({
+  value,
+  onValueChange,
+  onBlur,
+  locale,
+  maximumFractionDigits = 2,
+  padFraction = false,
+  useGrouping = true,
+  allowNegative = true,
+  maxIntegerDigits,
+  min,
+  max,
+  toDisplay = identity,
+  fromDisplay = identity,
+}: UseFormattedNumberOptions): FormattedNumberInputProps {
+  const current = value ?? null
+
+  const display = (stored: number | null): string => {
+    if (stored === null) {
+      return ""
+    }
+    const shown = roundTo(toDisplay(stored), maximumFractionDigits)
+    return formatNumber(shown, {
+      locale,
+      maximumFractionDigits,
+      minimumFractionDigits:
+        padFraction && !Number.isInteger(shown) ? maximumFractionDigits : 0,
+      useGrouping,
+    })
+  }
+
+  const [text, setText] = useState(() => display(current))
+  // The value the text was last derived from or parsed into. When the prop
+  // drifts from it, something outside the input changed the value.
+  const [synced, setSynced] = useState<number | null>(current)
+  if (!Object.is(current, synced)) {
+    setSynced(current)
+    setText(display(current))
+  }
+
+  // Re-render even when the re-formatted text is unchanged (a rejected
+  // keystroke), so the layout effect can put the caret back after React
+  // restores the controlled value.
+  const [, forceRender] = useReducer((n: number) => n + 1, 0)
+  const pendingCaret = useRef<{ input: HTMLInputElement; at: number } | null>(
+    null
+  )
+  useLayoutEffect(() => {
+    const pending = pendingCaret.current
+    if (!pending) {
+      return
+    }
+    pendingCaret.current = null
+    if (pending.input.ownerDocument.activeElement === pending.input) {
+      pending.input.setSelectionRange(pending.at, pending.at)
+    }
+  })
+
+  const fromDisplayRounded = (shown: number) =>
+    fromDisplay === identity
+      ? shown
+      : roundTo(fromDisplay(shown), maximumFractionDigits + 4)
+
+  const commit = (nextText: string, nextValue: number | null) => {
+    setText(nextText)
+    setSynced(nextValue)
+    if (!Object.is(nextValue, current)) {
+      onValueChange(nextValue)
+    }
+  }
+
+  const onChange = (event: ChangeEvent<HTMLInputElement>) => {
+    const input = event.target
+    const raw = input.value
+    const typed = parseTypedNumber(raw, {
+      allowNegative,
+      locale,
+      maxIntegerDigits,
+      maximumFractionDigits,
+      useGrouping,
+    })
+    const caret = input.selectionStart ?? raw.length
+    pendingCaret.current = {
+      at: mapCaret(raw, caret, typed.text, locale),
+      input,
+    }
+    commit(
+      typed.text,
+      typed.value === null ? null : fromDisplayRounded(typed.value)
+    )
+    forceRender()
+  }
+
+  const onPaste = (event: ClipboardEvent<HTMLInputElement>) => {
+    const input = event.currentTarget
+    const replacesAll =
+      input.value === "" ||
+      (input.selectionStart === 0 && input.selectionEnd === input.value.length)
+    if (!replacesAll) {
+      return // partial paste: let the change handler re-format the result
+    }
+    const parsed = parseLocaleNumber(
+      event.clipboardData.getData("text"),
+      locale
+    )
+    if (parsed === null) {
+      return
+    }
+    const shown = roundTo(
+      allowNegative ? parsed : Math.abs(parsed),
+      maximumFractionDigits
+    )
+    if (
+      maxIntegerDigits !== undefined &&
+      Math.abs(Math.trunc(shown)) >= 10 ** maxIntegerDigits
+    ) {
+      return // too long: the change handler truncates the pasted digits
+    }
+    event.preventDefault()
+    const stored = fromDisplayRounded(shown)
+    commit(display(stored), stored)
+  }
+
+  const handleBlur = () => {
+    if (current === null) {
+      setText("")
+    } else {
+      const clamped = clamp(current, min, max)
+      commit(display(clamped), clamped)
+    }
+    onBlur?.()
+  }
+
+  return {
+    inputMode: maximumFractionDigits > 0 ? "decimal" : "numeric",
+    onBlur: handleBlur,
+    onChange,
+    onPaste,
+    type: "text",
+    value: text,
+  }
+}
+
+export type { FormattedNumberInputProps, UseFormattedNumberOptions }
+export { useFormattedNumber }