@zeno-lib/forms 0.6.0 → 0.7.0

package/src/lib/form-disabled.ts

@@ -0,0 +1,95 @@
+"use client"
+
+import type { AnyFormApi } from "@tanstack/react-form"
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useLayoutEffect,
+  useSyncExternalStore,
+} from "react"
+
+import { formContext } from "./contexts"
+
+// `useForm({ disabled })`, per form. Keyed by `form.store`, as the rest of the
+// per-form Zeno state is (`validation-modes.ts`), and read through
+// `useSyncExternalStore`, so a toggle re-renders every field, a memoized one
+// or one with no provider above it included.
+const disabledOption = new WeakMap<object, boolean>()
+const listeners = new WeakMap<object, Set<() => void>>()
+
+function subscribe(key: object, listener: () => void): () => void {
+  let set = listeners.get(key)
+  if (!set) {
+    set = new Set()
+    listeners.set(key, set)
+  }
+  set.add(listener)
+  return () => {
+    set.delete(listener)
+  }
+}
+
+/** Apply `useForm({ disabled })` to `form`. */
+function useDisabledOption(form: AnyFormApi, disabled: boolean): void {
+  const key = form.store
+  // Seeded while rendering, so the first render, the server's included,
+  // already has it. A change lands on commit, so a render React drops (a
+  // suspended transition) never reaches the fields.
+  if (!disabledOption.has(key)) {
+    disabledOption.set(key, disabled)
+  }
+  useLayoutEffect(() => {
+    if (disabledOption.get(key) === disabled) {
+      return
+    }
+    disabledOption.set(key, disabled)
+    for (const listener of listeners.get(key) ?? []) {
+      listener()
+    }
+  }, [key, disabled])
+}
+
+type FormDisabledScope = {
+  readonly disabled: boolean
+  /** The `store` of the form it disables. */
+  readonly key: object
+}
+
+/**
+ * The disabled state `FormProvider` and `<Form>` give what they wrap, for
+ * their own form only: a field of another form rendered inside (a quick-add
+ * popover) keeps that form's state.
+ */
+const FormDisabledContext = createContext<FormDisabledScope | null>(null)
+
+/**
+ * Whether the form is disabled, by `useForm({ disabled })`,
+ * `<FormProvider disabled>`, `<Form disabled>` or `FormDialog`'s `disabled`.
+ * Every kit field reads it, so a control the fieldset of a disabled dialog
+ * can't reach (a checkbox, a switch, a radio, a slider) turns off too.
+ *
+ * Reads the form of the nearest provider; inside a field, pass `field.form`.
+ * `useForm({ disabled })` applies even where no provider of the form is
+ * mounted.
+ */
+function useIsFormDisabled(form?: AnyFormApi): boolean {
+  const scope = useContext(FormDisabledContext)
+  const contextForm = useContext(formContext) as AnyFormApi | null
+  const key = (form ?? contextForm)?.store
+  const subscribeToKey = useCallback(
+    (listener: () => void) => (key ? subscribe(key, listener) : () => null),
+    [key]
+  )
+  const getSnapshot = () => (key ? (disabledOption.get(key) ?? false) : false)
+  const byOption = useSyncExternalStore(
+    subscribeToKey,
+    getSnapshot,
+    getSnapshot
+  )
+  const byScope =
+    scope?.disabled === true && (key === undefined || scope.key === key)
+  return byScope || byOption
+}
+
+export { FormDisabledContext, useDisabledOption, useIsFormDisabled }

package/src/lib/item-options.test.ts

@@ -0,0 +1,11 @@
+import { describe, expect, test } from "vitest"
+
+import { valueKey } from "./item-options"
+
+describe("valueKey", () => {
+  test("keeps values that print alike apart, so React keys don't collide", () => {
+    expect(valueKey(1)).not.toBe(valueKey("1"))
+    expect(valueKey(null)).not.toBe(valueKey("null"))
+    expect(valueKey({ id: 1 })).not.toBe(valueKey('{"id":1}'))
+  })
+})

package/src/lib/item-options.ts

@@ -0,0 +1,165 @@
+// The items of `ComboboxField` and `MultiSelectField`: plain values, which
+// are their own label, `{ value, label }` objects, or `{ label, items }`
+// groups of either.
+
+/** An item whose value isn't its label. */
+type ItemObject<V> = { value: V; label: string }
+
+/** Items under a heading. */
+type ItemGroup<T> = { label: string; items: readonly T[] }
+
+/** An item of `items`, or of one of its groups. */
+type ItemOption<T> = T extends ItemGroup<infer I> ? I : T
+
+/** What picking an item stores: `item.value` for an object, else the item. */
+type ItemValue<T> =
+  T extends ItemGroup<infer I>
+    ? ItemValue<I>
+    : T extends ItemObject<infer V>
+      ? V
+      : T
+
+/** Whether an item's value is a stored one, as `isItemEqualToValue` says. */
+type ValueComparator = (itemValue: unknown, value: unknown) => boolean
+
+function isItemObject(item: unknown): item is ItemObject<unknown> {
+  return (
+    typeof item === "object" &&
+    item !== null &&
+    "value" in item &&
+    "label" in item
+  )
+}
+
+/** What Base UI takes for a group: an object with an `items` array. */
+function isItemGroup(item: unknown): item is ItemGroup<unknown> {
+  return (
+    typeof item === "object" &&
+    item !== null &&
+    Array.isArray((item as { items?: unknown }).items)
+  )
+}
+
+function itemValue(item: unknown): unknown {
+  return isItemObject(item) ? item.value : item
+}
+
+function itemLabel(item: unknown): string {
+  return isItemObject(item) ? item.label : String(item)
+}
+
+/** A React key per value: `1` and `"1"` get two, an object gets its JSON. */
+function valueKey(value: unknown): string {
+  if (typeof value !== "object" || value === null) {
+    return `${typeof value}:${String(value)}`
+  }
+  try {
+    return `object:${JSON.stringify(value)}`
+  } catch {
+    return `object:${String(value)}`
+  }
+}
+
+type ItemList<T> = {
+  /**
+   * `items` as Base UI takes them. It tells a grouped list by its first entry
+   * alone, so once there is a group, each run of plain items beside one goes
+   * under a group with no heading (`label: ""`).
+   */
+  readonly items: readonly T[]
+  /** Every option, the grouped ones included, in order. */
+  readonly options: readonly ItemOption<T>[]
+  /** The first option of each `valueKey`, so finding a value is no scan. */
+  readonly byKey: ReadonlyMap<string, ItemOption<T>>
+}
+
+function toItemList<T>(items: readonly T[]): ItemList<T> {
+  const hasGroup = items.some(isItemGroup)
+  const options: ItemOption<T>[] = []
+  const groups: ItemGroup<unknown>[] = []
+  let run: unknown[] | undefined
+  for (const item of items) {
+    if (isItemGroup(item)) {
+      for (const option of item.items) {
+        options.push(option as ItemOption<T>)
+      }
+      groups.push(item)
+      run = undefined
+    } else {
+      options.push(item as ItemOption<T>)
+      if (hasGroup && !run) {
+        run = []
+        groups.push({ items: run, label: "" })
+      }
+      run?.push(item)
+    }
+  }
+  const byKey = new Map<string, ItemOption<T>>()
+  for (const option of options) {
+    const key = valueKey(itemValue(option))
+    if (!byKey.has(key)) {
+      byKey.set(key, option)
+    }
+  }
+  return {
+    byKey,
+    items: hasGroup ? (groups as unknown as readonly T[]) : items,
+    options,
+  }
+}
+
+/**
+ * `Object.is`, then `isItemEqualToValue`, which never sees an empty value.
+ */
+function isSameValue(
+  a: unknown,
+  b: unknown,
+  isItemEqualToValue: ValueComparator | undefined
+): boolean {
+  if (Object.is(a, b)) {
+    return true
+  }
+  if (a === null || a === undefined || b === null || b === undefined) {
+    return false
+  }
+  return isItemEqualToValue?.(a, b) ?? false
+}
+
+/** The option whose value is `value`, if `items` has it. */
+function findOption<T>(
+  list: ItemList<T>,
+  value: unknown,
+  isItemEqualToValue: ValueComparator | undefined
+): ItemOption<T> | undefined {
+  const hit = list.byKey.get(valueKey(value))
+  if (
+    hit !== undefined &&
+    isSameValue(itemValue(hit), value, isItemEqualToValue)
+  ) {
+    return hit
+  }
+  // A comparator can match values whose keys differ (`{ id }` against
+  // `{ id, name }`).
+  return list.options.find((option) =>
+    isSameValue(itemValue(option), value, isItemEqualToValue)
+  )
+}
+
+export type {
+  ItemGroup,
+  ItemList,
+  ItemObject,
+  ItemOption,
+  ItemValue,
+  ValueComparator,
+}
+export {
+  findOption,
+  isItemGroup,
+  isItemObject,
+  isSameValue,
+  itemLabel,
+  itemValue,
+  toItemList,
+  valueKey,
+}

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

@@ -87,6 +87,15 @@ describe("getRequiredPaths", () => {
     expect(required.has("profile.bio")).toBe(false)
   })
 
+  test("a nullable object is not required, though its own fields are", () => {
+    const schema = z.object({
+      payer: z.object({ id: z.number(), kind: z.string().min(1) }).nullable(),
+    })
+    const required = getRequiredPaths(schema)
+    expect(required.has("payer")).toBe(false)
+    expect(required.has("payer.kind")).toBe(true)
+  })
+
   test("optional nested object is not descended into", () => {
     const schema = z.object({
       profile: z.object({ email: z.email() }).optional(),

package/src/lib/schema-required.ts

@@ -221,6 +221,38 @@ function settleEmptied(
   return { descended, next }
 }
 
+// The probe descends into a missing object with `{}`, so it never tries
+// `null` there. Try it on the side: a `.nullable()` object accepts it, so it
+// isn't required, though its own fields still are once it is set.
+function clearNullableObjects(
+  schema: StandardSchemaLike,
+  filled: readonly ProbeFill[],
+  probe: Record<PropertyKey, unknown>,
+  required: Set<string>,
+  cleared: Set<string>
+): void {
+  for (const fill of filled) {
+    if (isEmptyProbe(fill.value) || cleared.has(fill.path)) {
+      continue
+    }
+    fillAt(probe, fill.keys, null, true)
+    const issues = validateSync(schema, probe)
+    fillAt(probe, fill.keys, fill.value, true)
+    const rejected = issues?.some((issue) => {
+      const path = joinPath(issue.path?.map(pathKey) ?? [])
+      return (
+        path === fill.path ||
+        path.startsWith(`${fill.path}.`) ||
+        path.startsWith(`${fill.path}[`)
+      )
+    })
+    if (issues && !rejected) {
+      required.delete(fill.path)
+      cleared.add(fill.path)
+    }
+  }
+}
+
 function getRequiredPaths(schema: StandardSchemaLike): Set<string> {
   const required = new Set<string>()
   const cleared = new Set<string>()
@@ -234,6 +266,7 @@ function getRequiredPaths(schema: StandardSchemaLike): Set<string> {
       return required
     }
     const { failing, filled } = recordPass(issues, probe, required, cleared)
+    clearNullableObjects(schema, filled, probe, required, cleared)
     const settled = settleEmptied(emptied, failing, probe, required, cleared)
     emptied = [
       ...filled.filter(({ value }) => isEmptyProbe(value)),

package/src/lib/use-field-control.ts

@@ -6,6 +6,7 @@ import { type ReactNode, useCallback, useId } from "react"
 import { describedBy } from "./aria"
 import { useFieldContext } from "./contexts"
 import { emptyValueFor } from "./empty-value"
+import { useIsFormDisabled } from "./form-disabled"
 import {
   useHideFieldErrors,
   useIsFieldRequired,
@@ -20,6 +21,10 @@ type UseFieldControlOptions = {
    * it, and by the error while one shows.
    */
   description?: ReactNode
+  /**
+   * Disable the control. A disabled form (`useForm({ disabled })`,
+   * `<Form disabled>`, `FormDialog`'s `disabled`) disables it either way.
+   */
   disabled?: boolean
   /**
    * The label the field renders, if any. The control gets `aria-labelledby`,
@@ -40,6 +45,7 @@ type FieldControlProps<TValue = unknown> = {
   "aria-invalid": true | undefined
   "aria-labelledby": string | undefined
   "aria-required": true | undefined
+  /** The field's own `disabled`, or the form's. */
   disabled: boolean | undefined
   id: string
   name: string
@@ -71,6 +77,8 @@ type FieldControl<TValue = unknown> = {
   errors: AnyFieldMeta["errors"]
   /** The control's id, for the label's `htmlFor`. */
   id: string
+  /** The field is disabled, by its own `disabled` or the form's. */
+  isDisabled: boolean
   isInvalid: boolean
   /** The field requires a value, by the schema or `required`. */
   isRequired: boolean
@@ -125,6 +133,7 @@ function useFieldControl<TValue = unknown>({
   const schemaRequired = useIsFieldRequired(field)
   const schemaRequiresValue = useIsFieldRequiredBySchema(field)
   const isRequired = required ?? schemaRequiresValue
+  const isDisabled = useIsFormDisabled(field.form) || Boolean(disabled)
   // `field` is rebuilt on every value change; these members aren't, so a
   // control that memoizes on `onChange` doesn't see a new one each render.
   const { form, handleBlur, handleChange, name } = field
@@ -158,7 +167,7 @@ function useFieldControl<TValue = unknown>({
       "aria-invalid": isInvalid || undefined,
       "aria-labelledby": labelId,
       "aria-required": isRequired || undefined,
-      disabled,
+      disabled: isDisabled,
       id,
       name,
       onBlur: handleBlur,
@@ -169,6 +178,7 @@ function useFieldControl<TValue = unknown>({
     errorId,
     errors: showError ? field.state.meta.errors : [],
     id,
+    isDisabled,
     isInvalid,
     isRequired,
     labelId,

package/src/with-form.test-d.ts

@@ -0,0 +1,76 @@
+import { expectTypeOf, test } from "vitest"
+import { z } from "zod"
+import {
+  useAppFields,
+  useAppForm,
+  useForm,
+  withFieldGroup,
+  withForm,
+} from "./create-form"
+
+const schema = z.object({
+  address: z.object({ city: z.string(), street: z.string() }),
+  email: z.string(),
+})
+type Values = z.infer<typeof schema>
+const VALUES: Values = { address: { city: "", street: "" }, email: "" }
+
+// Typed by `defaultValues`, as in TanStack; `render` gets the kit's fields
+// through `useAppFields`.
+const EmailSection = withForm({
+  defaultValues: VALUES,
+  props: { title: "" },
+  render({ form, title }) {
+    expectTypeOf(title).toEqualTypeOf<string>()
+    expectTypeOf(form.state.values).toEqualTypeOf<Values>()
+    // biome-ignore lint/correctness/useHookAtTopLevel: `withForm` runs `render` inside a component; a .ts file can't return JSX to show it.
+    const { InputField } = useAppFields(form)
+    InputField({ name: "address.city" })
+    // @ts-expect-error — not a path of the form
+    InputField({ name: "phone" })
+    return null
+  },
+})
+
+const AddressGroup = withFieldGroup({
+  defaultValues: VALUES.address,
+  render: () => null,
+})
+
+test("withForm takes the form useForm returns, with a schema", () => {
+  const form = useForm({ onSubmit: () => undefined, schema })
+  EmailSection({ form, title: "Email" })
+  AddressGroup({ fields: "address", form })
+})
+
+test("withForm takes the form useForm returns, with a validation mode", () => {
+  const form = useForm({
+    onSubmit: () => undefined,
+    schema,
+    validators: "change",
+  })
+  EmailSection({ form, title: "Email" })
+})
+
+test("withForm takes the form useForm returns, without a schema", () => {
+  const form = useForm<Values>({
+    defaultValues: VALUES,
+    onSubmit: () => undefined,
+  })
+  EmailSection({ form, title: "Email" })
+  AddressGroup({ fields: "address", form })
+})
+
+test("withForm still takes the form useAppForm returns", () => {
+  const form = useAppForm({ defaultValues: VALUES, onSubmit: () => undefined })
+  EmailSection({ form, title: "Email" })
+})
+
+test("withForm rejects a form with other values", () => {
+  const form = useForm({
+    onSubmit: () => undefined,
+    schema: z.object({ name: z.string() }),
+  })
+  // @ts-expect-error — the section needs `email` and `address`
+  EmailSection({ form, title: "Email" })
+})

package/src/with-form.test.tsx

@@ -0,0 +1,60 @@
+import { cleanup, render, screen } from "@zeno-lib/test/testing-library"
+import userEvent from "@zeno-lib/test/user-event"
+import { afterEach, expect, test, vi } from "vitest"
+import { z } from "zod"
+import {
+  Form,
+  FormProvider,
+  useAppFields,
+  useForm,
+  withForm,
+} from "./create-form"
+
+const CITY = /City/
+
+afterEach(() => {
+  cleanup()
+})
+
+const schema = z.object({
+  address: z.object({ city: z.string().min(1, "Enter a city") }),
+  name: z.string(),
+})
+type Profile = z.infer<typeof schema>
+
+const AddressSection = withForm({
+  defaultValues: {} as Profile,
+  render: ({ form }) => {
+    const { InputField } = useAppFields(form)
+    return <InputField label="City" name="address.city" />
+  },
+})
+
+test("a withForm section edits and validates the parent's form", async () => {
+  const user = userEvent.setup()
+  const onSubmit = vi.fn()
+  function Profile() {
+    const form = useForm({ onSubmit: ({ value }) => onSubmit(value), schema })
+    const { SubmitButton } = form
+    return (
+      <FormProvider form={form}>
+        <Form>
+          <AddressSection form={form} />
+          <SubmitButton>Save</SubmitButton>
+        </Form>
+      </FormProvider>
+    )
+  }
+  render(<Profile />)
+
+  await user.click(screen.getByRole("button", { name: "Save" }))
+  expect(await screen.findByText("Enter a city")).toBeTruthy()
+  expect(document.activeElement).toBe(screen.getByLabelText(CITY))
+
+  await user.type(screen.getByLabelText(CITY), "Basel")
+  await user.click(screen.getByRole("button", { name: "Save" }))
+  expect(onSubmit).toHaveBeenCalledWith({
+    address: { city: "Basel" },
+    name: "",
+  })
+})