@zeno-lib/forms 0.0.1 → 0.2.0

package/src/lib/schema-required.ts

@@ -6,15 +6,29 @@
 // issue with a `path` we can record. Fields with defaults or `.optional()` stay
 // silent because the schema considers them satisfied.
 //
+// A missing parent hides its children (the schema stops at the missing key), so
+// the probe descends: when an issue says it expected an object or an array
+// (Zod and Valibot both put that on `issue.expected`), the next pass fills that
+// path with `{}` / `[{}]` and validates again. Array rows are probed through
+// index `0` and recorded index-agnostically, so `members[0].name` in the set
+// matches every row's `members[3].name` via `toRequiredPathKey`.
+//
+// Paths use TanStack Form's field-name syntax: dots for object keys, brackets
+// for array indices (`members[0].name`, not `members.0.name`).
+//
 // Limitations:
 //   - Async schemas are skipped (returns an empty set). Required-ness is a
 //     visual hint; the validator itself still runs at submit time.
-//   - Cross-field refinements that fail on `{}` may flag fields that aren't
-//     intrinsically required. In practice this is the same heuristic users
-//     would apply by eye.
+//   - Cross-field refinements that fail on the probe value may flag fields that
+//     aren't intrinsically required. In practice this is the same heuristic
+//     users would apply by eye.
+//   - Schemas whose issues carry no `expected` hint stop at the top level.
+
+type PathPart = PropertyKey | { readonly key: PropertyKey }
 
 type StandardIssue = {
-  readonly path?: ReadonlyArray<PropertyKey | { readonly key: PropertyKey }>
+  readonly path?: readonly PathPart[]
+  readonly expected?: unknown
 }
 
 type StandardSchemaLike = {
@@ -28,37 +42,127 @@ type StandardSchemaLike = {
   }
 }
 
-function pathSegment(
-  part: PropertyKey | { readonly key: PropertyKey }
-): string {
+const MAX_PROBE_DEPTH = 8
+
+const INDEX_SEGMENT = /^\d+$/
+
+// Matches `[3]` and `.3` index segments in a field name.
+const INDEX_IN_NAME = /\[\d+\]|\.(\d+)(?=\.|\[|$)/g
+
+function pathKey(part: PathPart): PropertyKey {
   if (typeof part === "object" && part !== null && "key" in part) {
-    return String(part.key)
+    return part.key
   }
-  return String(part)
+  return part
 }
 
-function getRequiredPaths(schema: StandardSchemaLike): Set<string> {
-  const required = new Set<string>()
+function isIndex(key: PropertyKey): boolean {
+  return (
+    typeof key === "number" ||
+    (typeof key === "string" && INDEX_SEGMENT.test(key))
+  )
+}
+
+// Render issue path segments as a TanStack field name, with every array index
+// normalised to `0` so one entry covers all rows.
+function joinPath(keys: readonly PropertyKey[]): string {
+  let out = ""
+  for (const key of keys) {
+    if (isIndex(key)) {
+      out += "[0]"
+    } else {
+      out += out === "" ? String(key) : `.${String(key)}`
+    }
+  }
+  return out
+}
+
+/**
+ * Normalise a field name (`members[3].name` or `members.3.name`) to the key
+ * `getRequiredPaths` records (`members[0].name`).
+ */
+function toRequiredPathKey(name: string): string {
+  return name.replace(INDEX_IN_NAME, "[0]")
+}
+
+function probeContainer(expected: unknown): unknown {
+  if (typeof expected !== "string") {
+    return
+  }
+  const kind = expected.toLowerCase()
+  if (kind === "object") {
+    return {}
+  }
+  if (kind === "array") {
+    return [{}]
+  }
+  return
+}
+
+// Write `value` at `keys` inside `root`, only where nothing is set yet.
+function fillAt(
+  root: Record<PropertyKey, unknown>,
+  keys: readonly PropertyKey[],
+  value: unknown
+): boolean {
+  let node: Record<PropertyKey, unknown> = root
+  for (const key of keys.slice(0, -1)) {
+    const next = node[key]
+    if (typeof next !== "object" || next === null) {
+      return false
+    }
+    node = next as Record<PropertyKey, unknown>
+  }
+  const last = keys.at(-1) as PropertyKey
+  if (node[last] !== undefined) {
+    return false
+  }
+  node[last] = value
+  return true
+}
+
+function validateSync(
+  schema: StandardSchemaLike,
+  value: unknown
+): readonly StandardIssue[] | undefined {
   let result: ReturnType<StandardSchemaLike["~standard"]["validate"]>
   try {
-    result = schema["~standard"].validate({})
+    result = schema["~standard"].validate(value)
   } catch {
-    return required
+    return
   }
   if (result instanceof Promise) {
-    return required
-  }
-  if (!("issues" in result && result.issues)) {
-    return required
+    return
   }
-  for (const issue of result.issues) {
-    const segments = issue.path?.map(pathSegment) ?? []
-    if (segments.length > 0) {
-      required.add(segments.join("."))
+  return "issues" in result && result.issues ? result.issues : []
+}
+
+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++) {
+    const issues = validateSync(schema, probe)
+    if (!issues) {
+      return required
+    }
+    let descended = false
+    for (const issue of issues) {
+      const keys = issue.path?.map(pathKey) ?? []
+      if (keys.length === 0) {
+        continue
+      }
+      required.add(joinPath(keys))
+      const container = probeContainer(issue.expected)
+      if (container !== undefined && fillAt(probe, keys, container)) {
+        descended = true
+      }
+    }
+    if (!descended) {
+      break
     }
   }
   return required
 }
 
 export type { StandardSchemaLike }
-export { getRequiredPaths }
+export { getRequiredPaths, toRequiredPathKey }

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 }