feat(next): string validation

next/src/form.ts

@@ -1,5 +1,102 @@
-import type { JsfSchema } from './types'
+import type { JsfSchema, SchemaValue } from './types'
+import type { SchemaValidationErrorType } from './validation/schema'
+import { validateSchema } from './validation/schema'
 
-export function createHeadlessForm(_schema: JsfSchema): never {
-  throw new Error('Not implemented')
+interface FormResult {
+  fields: never[]
+  isError: boolean
+  error: string | null
+  handleValidation: (value: SchemaValue) => ValidationResult
+}
+
+/**
+ * Validation error for schema
+ */
+export interface ValidationError {
+  /**
+   * The path to the field that has the error
+   * @example
+   * ['address', 'street']
+   */
+  path: string[]
+  /**
+   * The type of validation error
+   * @example
+   * 'required'
+   */
+  validation: SchemaValidationErrorType
+  /**
+   * The message of the validation error
+   * @example
+   * 'is required'
+   */
+  message: string
+}
+
+export interface ValidationResult {
+  formErrors?: Record<string, string>
+}
+
+/**
+ * Validate a value against a schema
+ * @param value - The value to validate
+ * @param schema - The schema to validate against
+ * @returns The validation result
+ */
+function validate(value: SchemaValue, schema: JsfSchema): ValidationResult {
+  const result: ValidationResult = {}
+  const errors = validateSchema(value, schema)
+  const formErrors = validationErrorsToFormErrors(errors)
+
+  if (formErrors) {
+    result.formErrors = formErrors
+  }
+
+  return result
+}
+
+/**
+ * Transform validation errors into an object with the field names as keys and the error messages as values
+ * @param errors - The validation errors to transform
+ * @returns The transformed validation errors
+ * @description
+ * When multiple errors are present for a single field, the last error message is used.
+ * @example
+ * validationErrorsToFormErrors([
+ *   { path: ['address', 'street'], validation: 'required', message: 'is required' },
+ *   { path: ['address', 'street'], validation: 'type', message: 'must be a string' },
+ * ])
+ * // { '.address.street': 'must be a string' }
+ */
+function validationErrorsToFormErrors(errors: ValidationError[]): Record<string, string> | null {
+  if (errors.length === 0) {
+    return null
+  }
+
+  return errors.reduce((acc: Record<string, string>, error) => {
+    acc[error.path.join('')] = error.message
+    return acc
+  }, {})
+}
+
+interface CreateHeadlessFormOptions {
+  initialValues?: SchemaValue
+}
+
+export function createHeadlessForm(schema: JsfSchema, options: CreateHeadlessFormOptions = {}): FormResult {
+  const errors = validateSchema(options.initialValues, schema)
+  const validationResult = validationErrorsToFormErrors(errors)
+  const isError = validationResult !== undefined
+
+  const handleValidation = (value: SchemaValue) => {
+    const result = validate(value, schema)
+    return result
+  }
+
+  return {
+    fields: [],
+    isError,
+    error: null,
+    handleValidation,
+  }
 }

next/src/types.ts

@@ -1,10 +1,37 @@
 import type { JSONSchema } from 'json-schema-typed/draft-2020-12'
 
-export type JsfSchema = Exclude<JSONSchema, boolean> & {
-  'properties'?: Record<string, JsfSchema> | boolean
+/**
+ * Defines the type of a `Field` in the form.
+ */
+export type JsfSchemaType = Exclude<JSONSchema, boolean>['type']
+
+/**
+ * Defines the type of a value in the form that will be validated against the schema.
+ */
+export type SchemaValue = string | number | ObjectValue | undefined
+
+/**
+ * A nested object value.
+ */
+export interface ObjectValue {
+  [key: string]: SchemaValue
+}
+
+/**
+ * JSON Schema Form extending JSON Schema with additional JSON Schema Form properties.
+ */
+export type JsfSchema = JSONSchema & {
+  'properties'?: Record<string, JsfSchema>
   'x-jsf-logic'?: {
     validations: Record<string, object>
     computedValues: Record<string, object>
   }
   'x-jsf-order'?: string[]
 }
+
+/**
+ * JSON Schema Form type without booleans.
+ * This type is used for convenience in places where a boolean is not allowed.
+ * @see `JsfSchema` for the full schema type which allows booleans and is used for sub schemas.
+ */
+export type NonBooleanJsfSchema = Exclude<JsfSchema, boolean>

next/src/validation/object.ts

@@ -0,0 +1,34 @@
+import type { ValidationError } from '../form'
+import type { NonBooleanJsfSchema, SchemaValue } from '../types'
+import type { StringValidationErrorType } from './string'
+import { validateSchema } from './schema'
+
+export type ObjectValidationErrorType = StringValidationErrorType
+
+/**
+ * Validate an object against a schema
+ * @param value - The value to validate
+ * @param schema - The schema to validate against
+ * @returns An array of validation errors
+ * @description
+ * Validates each property of object against the schema while keeping track of the path to the property.
+ * Each property is validated with `validateSchema`.
+ */
+export function validateObject(value: SchemaValue, schema: NonBooleanJsfSchema): ValidationError[] {
+  if (typeof schema === 'object' && schema.properties && typeof value === 'object') {
+    const errors = []
+    for (const [key, propertySchema] of Object.entries(schema.properties)) {
+      const propertyValue = value[key]
+      const propertyIsRequired = schema.required?.includes(key)
+      const propertyErrors = validateSchema(propertyValue, propertySchema, propertyIsRequired)
+      const errorsWithPath = propertyErrors.map(error => ({
+        ...error,
+        path: [`.${key}`, ...error.path],
+      }))
+      errors.push(...errorsWithPath)
+    }
+    return errors
+  }
+
+  return []
+}

next/src/validation/schema.ts

@@ -0,0 +1,106 @@
+import type { ValidationError } from '../form'
+import type { JsfSchema, JsfSchemaType, SchemaValue } from '../types'
+import type { ObjectValidationErrorType } from './object'
+import { validateObject } from './object'
+import { validateString } from './string'
+
+export type SchemaValidationErrorType =
+  /**
+   * The value is not of the correct type
+   */
+  | 'type'
+  /**
+   * The value is required
+   */
+  | 'required'
+  /**
+   * The value fails validation due to boolean schema
+   */
+  | 'valid'
+  /**
+   * The value fails validation due to object schema
+   */
+  | ObjectValidationErrorType
+
+/**
+ * Get the type of a schema
+ * @param schema - The schema to get the type of
+ * @returns The type of the schema, or an array of types if the schema is an array. Will fallback to 'object' if no type is defined.
+ * @example
+ * getType(false) // 'boolean'
+ * getType(true) // 'boolean'
+ * getType({ type: 'string' }) // 'string'
+ * getType({ type: ['string', 'number'] }) // ['string', 'number']
+ * getType({}) // 'object'
+ */
+export function getSchemaType(schema: JsfSchema): JsfSchemaType | JsfSchemaType[] {
+  if (typeof schema === 'boolean') {
+    return 'boolean'
+  }
+
+  if (schema.type) {
+    return schema.type
+  }
+
+  return 'object'
+}
+
+/**
+ * Validate the type of a value against a schema
+ * @param value - The value to validate
+ * @param schema - The schema to validate against
+ * @returns An array of validation errors
+ * @description
+ * - If the schema type is an array, the value must be an instance of one of the types in the array.
+ * - If the schema type is a string, the value must be of the same type.
+ */
+function validateType(value: SchemaValue, schema: JsfSchema): ValidationError[] {
+  const schemaType = getSchemaType(schema)
+  const valueType = value === undefined ? 'undefined' : typeof value
+
+  if (Array.isArray(schemaType) ? !schemaType.includes(valueType) : valueType !== schemaType) {
+    return [{ path: [], validation: 'type', message: `should be ${schemaType}` }]
+  }
+
+  return []
+}
+
+/**
+ * Validate a value against a schema
+ * @param value - The value to validate
+ * @param schema - The schema to validate against
+ * @param required - Whether the value is required
+ * @returns An array of validation errors
+ * @description
+ * This function is the main validation function to validate a value against a schema.
+ * - It validates boolean schemas
+ * - It validates the `required` constraint
+ * - It validates the type of the value
+ * - It delegates to type specific validation functions such as `validateObject` and `validateString`
+ * @see `validateType` for type validation
+ */
+export function validateSchema(value: SchemaValue, schema: JsfSchema, required: boolean = false): ValidationError[] {
+  if (value === undefined && required) {
+    return [{ path: [], validation: 'required', message: 'is required' }]
+  }
+
+  if (value === undefined) {
+    return []
+  }
+
+  if (typeof schema === 'boolean') {
+    return schema ? [] : [{ path: [], validation: 'valid', message: 'always fails' }]
+  }
+
+  const typeValidationErrors = validateType(value, schema)
+  if (typeValidationErrors.length > 0) {
+    return typeValidationErrors
+  }
+
+  const errors = [
+    ...validateObject(value, schema),
+    ...validateString(value, schema),
+  ]
+
+  return errors
+}

next/src/validation/string.ts

@@ -0,0 +1,53 @@
+import type { ValidationError } from '../form'
+import type { NonBooleanJsfSchema, SchemaValue } from '../types'
+import { getSchemaType } from './schema'
+
+export type StringValidationErrorType =
+  /**
+   * The value is too short
+   */
+  | 'minLength'
+  /**
+   * The value is too long
+   */
+  | 'maxLength'
+  /**
+   * The value does not match the pattern
+   */
+  | 'pattern'
+
+/**
+ * Validate a string against a schema
+ * @param value - The value to validate
+ * @param schema - The schema to validate against
+ * @returns An array of validation errors
+ * @description
+ * - Validates the string length against the `minLength` and `maxLength` properties.
+ * - Validates the string pattern against a regular expression defined in the `pattern` property.
+ */
+export function validateString(value: SchemaValue, schema: NonBooleanJsfSchema): ValidationError[] {
+  const errors: ValidationError[] = []
+
+  if (getSchemaType(schema) === 'string' && typeof value === 'string') {
+    if (schema.minLength && value.length < schema.minLength) {
+      errors.push({ path: [], validation: 'minLength', message: 'must be at least 3 characters' })
+    }
+
+    if (schema.maxLength && value.length > schema.maxLength) {
+      errors.push({ path: [], validation: 'maxLength', message: 'must be at most 10 characters' })
+    }
+
+    if (schema.pattern) {
+      const pattern = new RegExp(schema.pattern)
+      if (!pattern.test(value)) {
+        errors.push({
+          path: [],
+          validation: 'pattern',
+          message: `must match the pattern '${schema.pattern}'`,
+        })
+      }
+    }
+  }
+
+  return errors
+}

next/test/form.test.ts

@@ -1,11 +1,18 @@
 import { describe, expect, it } from '@jest/globals'
 import { createHeadlessForm } from '../src'
 
-/**
- * Example test suite for V2
- */
 describe('createHeadlessForm', () => {
   it('should be a function', () => {
     expect(createHeadlessForm).toBeInstanceOf(Function)
   })
+
+  it('returns empty result given an empty schema', () => {
+    const result = createHeadlessForm({}, { initialValues: {} })
+
+    expect(result).toMatchObject({
+      fields: [],
+    })
+    expect(result.isError).toBe(false)
+    expect(result.error).toBeFalsy()
+  })
 })

next/test/validation/boolean_schema.test.ts

@@ -0,0 +1,18 @@
+import { describe, expect, it } from '@jest/globals'
+import { createHeadlessForm } from '../../src'
+
+describe('boolean schema validation', () => {
+  it('returns an error if the value is false', () => {
+    const form = createHeadlessForm({ properties: { name: false } })
+
+    expect(form.handleValidation({ name: 'anything' })).toMatchObject({ formErrors: { '.name': 'always fails' } })
+    expect(form.handleValidation({})).toMatchObject({ formErrors: undefined })
+  })
+
+  it('does not return an error if the value is true', () => {
+    const form = createHeadlessForm({ properties: { name: true } })
+
+    expect(form.handleValidation({ name: 'anything' })).toMatchObject({ formErrors: undefined })
+    expect(form.handleValidation({})).toMatchObject({ formErrors: undefined })
+  })
+})