@kaliber/forms 2.1.2 → 3.0.0-beta.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kaliber/forms",
-  "version": "2.1.2",
+  "version": "3.0.0-beta.0",
   "main": "index.js",
   "sideEffects": false,
   "publishConfig": {
@@ -25,7 +25,19 @@
   "private": false,
   "license": "MIT",
   "repository": "https://github.com/kaliberjs/forms.git",
+  "scripts": {
+    "postinstall": "if test -f ./scripts/install-peer-dependencies-for-typescript.js; then node ./scripts/install-peer-dependencies-for-typescript.js; fi",
+    "test.types": "tsc --project tsconfig.type.test.json"
+  },
   "dependencies": {
     "react-fast-compare": "^3.0.1"
+  },
+  "peerDependencies": {
+    "@types/react": "^18.0.0",
+    "react": "^18.3.1"
+  },
+  "devDependencies": {
+    "@types/node": "22",
+    "typescript": "^5.8.2"
   }
 }

package/src/components.js

@@ -2,22 +2,42 @@ import {
   useFormFieldValue, useFormFieldsValues,
   useFormFieldSnapshot
 } from './hooks'
+/** @import { Field } from './types.ts' */
 
+/**
+ * @template {Field} T
+ * @template {(value: ReturnType<typeof useFormFieldValue<T>>) => any} R
+ * @arg {{ field: T, render: R }} props
+ * @returns {null | ReturnType<R>}
+ */
 export function FormFieldValue({ field, render }) {
   const value = useFormFieldValue(field)
   return valueOrNull(render(value))
 }
 
+/**
+ * @template {[...Field[]]} const T
+ * @template {(values: ReturnType<typeof useFormFieldsValues<T>>) => any} R
+ * @arg {{ fields: T, render: R }} props
+ * @returns {null | ReturnType<R>}
+ */
 export function FormFieldsValues({ fields, render }) {
   const values = useFormFieldsValues(fields)
   return valueOrNull(render(values))
 }
 
+/**
+ * @template {Field} T
+ * @template {(valid: boolean) => any} R
+ * @arg {{ field: T, render: R }} props
+ * @returns {null | ReturnType<R>}
+ */
 export function FormFieldValid({ field, render }) {
   const { invalid } = useFormFieldSnapshot(field)
   return valueOrNull(render(!invalid))
 }
 
+/** @template T @arg {T} value @returns {T | null} */
 function valueOrNull(value) {
   return typeof value === 'undefined' ? null : value
-}
+}

package/src/components.type.test.ts

@@ -0,0 +1,74 @@
+import { FormFieldsValues, FormFieldValid, FormFieldValue } from './components'
+import { useForm } from './hooks'
+import { array, object } from './schema'
+import { expectAssignable, expectNotAny, expectNotNever, Prepared } from './type.test.helpers.ts'
+import { optionalT } from './validation'
+
+const { form } = useForm({
+  fields: {
+    a: optionalT('string'),
+    b: optionalT('number'),
+    c: optionalT('boolean'),
+    d: object({
+      a: optionalT('string'),
+      b: optionalT('number'),
+      c: optionalT('boolean'),
+    }),
+    e: array({
+      a: optionalT('string'),
+      b: optionalT('number'),
+      c: optionalT('boolean'),
+    })
+  },
+  onSubmit() {}
+})
+
+FormFieldValue({
+  field: form,
+  render(value) {
+    expectNotAny(value)
+    expectNotNever(value)
+    expectAssignable<
+      {
+        a: string
+        b: number
+        c: boolean
+        d: {
+            a: string
+            b: number
+            c: boolean
+        }
+        e: {
+            a: string
+            b: number
+            c: boolean
+        }[]
+      },
+      Prepared<typeof value>
+    >
+  }
+})
+
+FormFieldsValues({
+  fields: [form.fields.a, form.fields.b],
+  render(value) {
+    expectNotAny(value)
+    expectNotNever(value)
+    expectAssignable<
+      [string, number],
+      Prepared<typeof value>
+    >
+  }
+})
+
+FormFieldValid({
+  field: form.fields.a,
+  render(value) {
+    expectNotAny(value)
+    expectNotNever(value)
+    expectAssignable<
+      boolean,
+      Prepared<typeof value>
+    >
+  }
+})

package/src/fields.js

@@ -1,6 +1,7 @@
 import { normalize } from './normalize'
 import { createState, subscribeToAll, subscribeToChildren } from './state'
 import isEqual from 'react-fast-compare'
+/** @import { Falsy, Field, NormalizedField, PartialWithStringKey, State, Validate, ValidationContext, ValidationError, ValidationFunction } from './types.ts' */
 
 const constructors = {
   basic: createBasicFormField,
@@ -8,6 +9,15 @@ const constructors = {
   object: createObjectFormField,
 }
 
+/**
+ * @template {NormalizedField.Object} const T
+ *
+ * @arg {{
+ *   name?: string,
+ *   initialValue?: PartialWithStringKey<NormalizedField.ToValue<T>>,
+ *   field: T,
+ * }} props
+ */
 export function createObjectFormField({ name = '', initialValue = {}, field }) {
 
   const fields = createFormFields(initialValue, field.fields, name && `${name}.`)
@@ -17,18 +27,19 @@ export function createObjectFormField({ name = '', initialValue = {}, field }) {
   const internalState = createState(initialState)
   const validate = bindValidate(field.validate, internalState)
 
-  const value = {
-    get() { return mapValues(fields, child => child.value.get()) },
+  const value = /** @satisfies {State.Readonly} */ ({
+    get() { return mapValues(fields, /** @arg {Field} child */ child => child.value.get()) },
     subscribe(f) {
       return subscribeToChildren({
         children,
+        /** @arg {unknown} _ */
         notify: _ => f(value.get()),
         subscribeToChild: (x, f) => x.value.subscribe(f),
       })
     },
-  }
+  })
 
-  return {
+  return /** @type {Field.FromNormalizedField<T>} */ ({
     type: 'object',
     name,
     validate(context) {
@@ -49,15 +60,21 @@ export function createObjectFormField({ name = '', initialValue = {}, field }) {
     value,
     state: { get: internalState.get, subscribe: internalState.subscribe },
     fields,
-  }
+  })
 
+  /**
+   * @arg {any} initialValues
+   * @arg {T['fields']} fields
+   * @arg {string} namePrefix
+   */
   function createFormFields(initialValues, fields, namePrefix = '') {
     return mapValues(fields, (field, name) => {
       const fullName = `${namePrefix}${name}`
       const normalizedField = normalize(field, fullName)
-      const constructor = constructors[normalizedField.type]
-      return constructor({
+      const createFormField = constructors[normalizedField.type]
+      return createFormField({
         name: fullName,
+        // @ts-expect-error - If you know how to fix this, please let me know
         field: normalizedField,
         initialValue: initialValues[name]
       })
@@ -65,7 +82,15 @@ export function createObjectFormField({ name = '', initialValue = {}, field }) {
   }
 }
 
-function createArrayFormField({ name, initialValue = [], field }) {
+/**
+ * @arg {{
+ *   name?: string,
+ *   initialValue?: { [name: string]: any }[],
+ *   field: NormalizedField.Array,
+ * }} props
+ * @returns {Field.Array}
+ */
+function createArrayFormField({ name = '', initialValue = [], field }) {
 
   let index = 0
 
@@ -76,7 +101,7 @@ function createArrayFormField({ name, initialValue = [], field }) {
   const internalState = createState(initialState)
   const validate = bindValidate(field.validate, internalState)
 
-  const value = {
+  const value = /** @satisfies {State.Readonly} */ ({
     get() {
       const { children } = internalState.get()
       return children.map(child => child.value.get())
@@ -85,12 +110,12 @@ function createArrayFormField({ name, initialValue = [], field }) {
       return subscribeToAll({
         state: internalState,
         childrenFromState: x => x.children,
-        notify:_ => f(value.get()),
+        notify: _ => f(value.get()),
         subscribeToChild: (x, f) => x.value.subscribe(f),
         onlyNotifyOnChildChange: true,
       })
     },
-  }
+  })
 
   return {
     type: 'array',
@@ -128,6 +153,7 @@ function createArrayFormField({ name, initialValue = [], field }) {
     }
   }
 
+  /** @arg {{ [name: string]: any }} initialValue */
   function createFormField(initialValue) {
     const fullName = `${name}[${index++}]`
     const fields = typeof field.fields == 'function' ? field.fields(initialValue) : field.fields
@@ -139,13 +165,21 @@ function createArrayFormField({ name, initialValue = [], field }) {
   }
 }
 
+/**
+ * @arg {{
+ *   name: string,
+ *   initialValue?: any,
+ *   field: NormalizedField.Basic,
+ * }} props
+ * @returns {Field.Basic}
+ */
 function createBasicFormField({ name, initialValue, field }) {
 
   const initialFormFieldState = deriveFormFieldState({ value: initialValue })
   const internalState = createState(initialFormFieldState)
   const validate = bindValidate(field.validate, internalState)
 
-  const value = {
+  const value = /** @satisfies {State.ReadonlyWithHistory} */ ({
     get() { return internalState.get().value },
     subscribe(f) {
       return internalState.subscribe(({ value: newValue }, { value: oldValue }) => {
@@ -153,7 +187,7 @@ function createBasicFormField({ name, initialValue, field }) {
         f(newValue, oldValue)
       })
     },
-  }
+  })
 
   return {
     type: 'basic',
@@ -189,17 +223,41 @@ function createBasicFormField({ name, initialValue, field }) {
   }
 }
 
+/**
+ * @template {Record<string, any>} T1
+ * @template {Record<string, any>} T2
+ * @arg {T1} formFieldState
+ * @arg {T2} update
+ */
 function updateState(formFieldState, update) {
   return deriveFormFieldState({ ...formFieldState, ...update })
 }
 
+/**
+ * @template T
+ * @template {keyof T} K
+ * @arg {T} o
+ * @arg {K[]} properties
+ * @returns {Pick<T, K>}
+ */
 function pick(o, properties) {
+  // @ts-expect-error
   return properties.reduce(
     (result, property) => ({ ...result, [property]: o[property] }),
     {}
   )
 }
 
+/**
+ * @template {Record<string, any>} const T
+ * @arg {{
+ *   error?: Falsy | ValidationError,
+ *   isSubmitted?: boolean,
+ *   isVisited?: boolean,
+ *   hasFocus?: boolean,
+ * } & T} state
+ * @return {T & State.Common}
+ */
 function deriveFormFieldState({
   error = false,
   isSubmitted = false,
@@ -207,7 +265,7 @@ function deriveFormFieldState({
   hasFocus = false,
   ...rest
 }) {
-  return {
+  return /** @type {T & State.Common} */ ({
     ...rest,
     error,
     isSubmitted,
@@ -215,18 +273,38 @@ function deriveFormFieldState({
     hasFocus,
     invalid: !!error,
     showError: !!error && !hasFocus && (isVisited || isSubmitted)
-  }
+  })
 }
 
+/**
+ * @template {{ [key: string]: any }} O
+ * @template {(v: O[keyof O], k: keyof O & string, o: O) => any} F
+ *
+ * @param {O} o
+ * @param {F} f
+ * @returns {{ [key in keyof O]: ReturnType<F> }}
+ */
 function mapValues(o, f) {
+  // @ts-expect-error
   return Object.entries(o).reduce(
-    (result, [k, v]) => (result[k] = f(v, k), result),
+    // @ts-expect-error
+    (result, [k, v]) => (result[k] = f(v, k, o), result),
     {}
   )
 }
 
+/**
+ * @template T
+ * @template {State.ReadWrite} S
+ * @arg {null | ValidationFunction<T>} f
+ * @arg {S} state
+ */
 function bindValidate(f, state) {
   return f && (
+    /**
+     * @arg {Parameters<ValidationFunction<T>>} args
+     * @returns {S extends State.ReadWrite<infer X> ? X : never}
+     */
     (...args) => {
       const error = (f && f(...args)) || false
       return state.update(x => isEqual(error, x.error) ? x : updateState(x, { error }))
@@ -234,6 +312,10 @@ function bindValidate(f, state) {
   )
 }
 
+/**
+ * @arg {ValidationContext} context
+ * @arg {any} parent
+ */
 function addParent(context, parent) {
   return { ...context, parents: [...context.parents, parent] }
 }

package/src/fields.type.test.ts

@@ -0,0 +1,135 @@
+import { createObjectFormField } from './fields'
+import { normalize } from './normalize'
+import { array, object } from './schema'
+import { asConst } from './type-helpers'
+import { expectAssignable, expectNotAny, expectNotNever, Prepared } from './type.test.helpers.ts'
+import { Field, PartialWithStringKey, State, ValidationContext } from './types.ts'
+import { email, number, optional, required } from './validation'
+
+const simpleObjectInput = asConst({
+  noValidation: optional,
+  singleValidation: email,
+  multipleValidation: [required, number],
+})
+type SimpleObjectValueType = {
+  noValidation: unknown,
+  singleValidation: string,
+  multipleValidation: number,
+}
+type SimpleObjectFieldsType = {
+  noValidation: BasicFieldType<unknown>,
+  singleValidation: BasicFieldType<string>,
+  multipleValidation: BasicFieldType<number>,
+}
+const simpleObjectNormalizedField = normalize(object(simpleObjectInput))
+const simpleObjectWithValidationNormalizedField = normalize(object(validate, simpleObjectInput))
+
+type BasicFieldType<T> = {
+  type: 'basic',
+  name: string,
+  validate(context: ValidationContext): void,
+  setSubmitted(isSubmitted: boolean): void,
+  reset(): void,
+  value: State.Readonly<T>,
+  state: State.Readonly<State.Basic<T>>,
+  eventHandlers: {
+    onBlur(): void,
+    onFocus(): void,
+    onChange(eOrValue: Field.Event<T> | T): void,
+  }
+}
+
+type ObjectFieldType<Fields, Value> = {
+  type: 'object',
+  name: string,
+  validate(context: ValidationContext): void,
+  setSubmitted(isSubmitted: boolean): void,
+  reset(): void,
+  value: State.Readonly<Value>,
+  state: State.Readonly<State.Object>,
+  fields: Fields
+}
+
+type ArrayFieldType<Field, Value extends Array<any>> = {
+  type: 'array',
+  name: string,
+  validate(context: ValidationContext): void,
+  setSubmitted(isSubmitted: boolean): void,
+  reset(): void,
+  value: State.Readonly<Value>,
+  state: State.Readonly<State.Array<Field>>,
+  helpers: {
+    add(initialValue: PartialWithStringKey<Value extends Array<infer X> ? X : never>): void,
+    remove(entry: Field): void,
+  }
+}
+
+{
+  const simpleObjectField = createObjectFormField({ field: simpleObjectNormalizedField })
+  const simpleObjectWithValidationField = createObjectFormField({ field: simpleObjectWithValidationNormalizedField })
+  type SimpleObjectFields = (typeof simpleObjectField)['fields']
+
+  type NoValidationFieldType = SimpleObjectFields['noValidation']
+  expectAssignable<
+    BasicFieldType<unknown>,
+    Prepared<NoValidationFieldType>
+  >
+
+  type SingleValidationFieldType = SimpleObjectFields['singleValidation']
+  expectAssignable<
+    BasicFieldType<string>,
+    Prepared<SingleValidationFieldType>
+  >
+
+  type MultipleValidationFieldType = SimpleObjectFields['multipleValidation']
+  expectAssignable<
+    BasicFieldType<number>,
+    Prepared<MultipleValidationFieldType>
+  >
+
+  expectNotAny(simpleObjectField)
+  expectNotNever(simpleObjectField)
+  expectAssignable<
+    ObjectFieldType<SimpleObjectFieldsType, SimpleObjectValueType>,
+    Prepared<typeof simpleObjectField>
+  >
+  expectAssignable<
+    ObjectFieldType<SimpleObjectFieldsType, SimpleObjectValueType>,
+    Prepared<typeof simpleObjectWithValidationField>
+  >
+}
+
+{
+  const objectWithSubFields = createObjectFormField({
+    field: normalize(object({
+      object: simpleObjectNormalizedField,
+      array: array(simpleObjectInput)
+    }))
+  })
+
+  expectNotAny(objectWithSubFields)
+  expectNotNever(objectWithSubFields)
+  expectAssignable<
+    ObjectFieldType<
+      {
+        object: ObjectFieldType<
+          SimpleObjectFieldsType,
+          SimpleObjectValueType
+        >,
+        array: ArrayFieldType<
+          ObjectFieldType<
+            SimpleObjectFieldsType,
+            SimpleObjectValueType
+          >,
+          SimpleObjectValueType[]
+        >,
+      },
+      { object: SimpleObjectValueType, array: SimpleObjectValueType[] }
+    >,
+    Prepared<typeof objectWithSubFields>
+  >
+}
+
+function validate<T>(value: T) {
+  return value === 'failure' && { id: 'error' }
+}

package/src/hooks.js

@@ -2,14 +2,28 @@ import isEqual from 'react-fast-compare'
 import { createObjectFormField } from './fields'
 import { normalize } from './normalize'
 import * as snapshot from './snapshot'
+import React from 'react'
+import { asAny } from './type-helpers'
+/** @import { Validate, NormalizedField, Field, InitialValue, FieldInput, State, Snapshot, Expand, MapTuple } from './types.ts' */
 
 let formCounter = 0 // This will stop working when we need a number greater than 9007199254740991
 function useFormId() { return React.useMemo(() => `form${++formCounter}`, []) }
 
-
+/**
+ * @template {FieldInput.Object} const A
+ * @template {Validate<FieldInput.ObjectToValue<A>>} const C
+ *
+ * @arg {{
+ *   fields: A,
+ *   initialValues?: Expand<InitialValue<A>>,
+ *   validate?: C,
+ *   onSubmit: (snapshot: any) => void,
+ *   formId?: string,
+ * }} props
+ */
 export function useForm({ initialValues = undefined, fields, validate = undefined, onSubmit, formId = useFormId() }) {
-  const initialValuesRef = React.useRef(null)
-  const formRef = React.useRef(null)
+  const initialValuesRef = React.useRef(/** @type {InitialValue<A> | undefined} */ (asAny(null)))
+  const formRef = React.useRef(/** @type {Field.ObjectFromObjectInput<A>} */ (asAny(null)))
 
   if (!isEqual(initialValuesRef.current, initialValues)) {
     initialValuesRef.current = initialValues
@@ -28,6 +42,7 @@ export function useForm({ initialValues = undefined, fields, validate = undefine
 
   return { form: formRef.current, submit, reset }
 
+  /** @arg {React.FormEvent<HTMLFormElement>} e */
   function handleSubmit(e) {
     if (e) e.preventDefault()
     formRef.current.setSubmitted(true)
@@ -39,6 +54,11 @@ export function useForm({ initialValues = undefined, fields, validate = undefine
   }
 }
 
+/**
+ * @template {State.Readonly} T
+ * @arg {T} state
+ * @returns {T extends State.Readonly<infer X> ? X : never}
+ */
 function useFormFieldState(state) {
   const [formFieldState, setFormFieldState] = React.useState(state.get)
 
@@ -53,6 +73,10 @@ function useFormFieldState(state) {
   return formFieldState
 }
 
+/**
+ * @template {[...State.Readonly[]]} const T
+ * @arg {T} states
+ */
 function useFieldStates(states) {
   const [fieldStates, setFieldStates] = React.useState(getStates)
 
@@ -70,17 +94,24 @@ function useFieldStates(states) {
         () => {}
       )
     },
-    states // explanation below
+    states // explanation below on why we supply the array directly
   )
 
   return fieldStates
 
-  function getStates() { return states.map(x => x.get()) }
+  function getStates() {
+    return /** @type {State.StateTupleToValueTuple<T>}*/ (states.map(x => x.get()))
+  }
 }
 
+/**
+ * @template {Field} T
+ * @arg {T} field
+ * @returns {Expand<Snapshot.FromField<T>>}
+ */
 export function useFormFieldSnapshot(field) {
   const state = React.useMemo(
-    () => ({
+    () => /** @satisfies {State.Readonly} */ ({
       get() { return snapshot.get(field) },
       subscribe(f) { return snapshot.subscribe(field, f) }
     }),
@@ -89,14 +120,27 @@ export function useFormFieldSnapshot(field) {
   return useFormFieldState(state)
 }
 
+/**
+ * @template {Field} T
+ * @arg {T} field
+ * @returns {ReturnType<typeof useFormFieldState<T['value']>>}
+ */
 export function useFormFieldValue(field) {
   return useFormFieldState(field.value)
 }
 
+/**
+ * @template {[...Field[]]} const T
+ * @arg {T} fields
+ */
 export function useFormFieldsValues(fields) {
-  return useFieldStates(fields.map(x => x.value))
+  return useFieldStates(/** @type {MapTuple<T, 'value'>} */ (fields.map(x => x.value)))
 }
 
+/**
+ * @template T
+ * @arg {Field.Basic<T>} field
+ */
 export function useFormField(field) {
   if (!field) throw new Error('No field was passed in')
   const { name, eventHandlers } = field
@@ -105,12 +149,16 @@ export function useFormField(field) {
   return { name, state, eventHandlers }
 }
 
+/**
+ * @arg {Field.Basic<number | string>} field
+ */
 export function useNumberFormField(field) {
   const { name, state, eventHandlers: { onChange, ...originalEventHandlers } } = useFormField(field)
   const eventHandlers = { ...originalEventHandlers, onChange: handleChange }
 
   return { name, state, eventHandlers }
 
+  /** @arg {React.ChangeEvent<HTMLInputElement>} e */
   function handleChange(e) {
     const userValue = e.target.value
     const value = Number(userValue)
@@ -118,17 +166,23 @@ export function useNumberFormField(field) {
   }
 }
 
+/** @arg {Field.Basic<boolean>} field */
 export function useBooleanFormField(field) {
   const { name, state, eventHandlers: { onChange, ...originalEventHandlers } } = useFormField(field)
   const eventHandlers = { ...originalEventHandlers, onChange: handleChange }
 
   return { name, state, eventHandlers }
 
+  /** @arg {React.ChangeEvent<HTMLInputElement>} e */
   function handleChange(e) {
     onChange(e.target.checked)
   }
 }
 
+/**
+ * @template {Field.ObjectFields} T
+ * @arg {Field.Array<T>} field
+ */
 export function useArrayFormField(field) {
   const { name, helpers } = field
   const state = useFormFieldState(field.state)
@@ -136,6 +190,10 @@ export function useArrayFormField(field) {
   return { name, state, helpers }
 }
 
+/**
+ * @template {Field.ObjectFields} T
+ * @arg {Field.Object<T>} field
+ */
 export function useObjectFormField(field) {
   const { name, fields } = field
   const state = useFormFieldState(field.state)