@playfast/reform-forms 0.1.0 → 1.1.1

package/src/form.ts

@@ -1,415 +1,74 @@
 import {
   Context,
   Effect,
-  Either,
   Function as Fn,
   Layer,
   Option,
-  Record,
-  Runtime,
   Schema as S,
 } from 'effect'
 import {
   Bus,
-  CurrentTracker,
   Event,
   Reducer,
   Reducers,
   State,
   type Store,
-  type Trigger,
 } from '@playfast/reform'
-import type { AnySource, Source } from '@playfast/reform'
+import type {
+  AnyForm,
+  Decoded,
+  DecodedOfSchema,
+  FormClass,
+  FormEvents,
+  FormLiveConfig,
+  FormState,
+  InputRecord,
+  Inputs,
+  InputsObject,
+  RuntimeConfig,
+  Values,
+  ValuesOfSchema,
+} from './formTypes'
 import {
-  getNestedValue,
-  isPathOrParentDirty,
-  moveAt,
-  recalculateDirtyPaths,
-  replaceAt,
-  setNestedValue,
-  type ArrayItem,
-  type ArrayPath,
-  type FieldPath,
-  type PathValue,
-  type VariantPath,
-  type VariantValue,
-} from './path'
+  appendAtPath,
+  initialState,
+  markTouched,
+  moveAtPath,
+  removeAtPath,
+  setAtPath,
+  swapAtPath,
+} from './formState'
 import {
   error,
-  errorsToRecord,
-  firstError,
   normalizeErrors,
-  routeParseError,
-  type FormError,
   type FormErrors,
 } from './validation'
 
 export { error }
 
-// Plain-JSON UI-contract shape (flows into FieldBinding.limitations, serialized
-// over the wire): optional knobs are part of the external contract, so the
-// `ExternalApi` postfix opts this out of the Option-only field rule.
-export interface FieldLimitationsExternalApi<A = unknown> {
-  readonly required?: boolean
-  readonly disabled?: boolean
-  readonly readonly?: boolean
-  readonly visible?: boolean
-  readonly min?: number
-  readonly max?: number
-  readonly minLength?: number
-  readonly maxLength?: number
-  readonly minItems?: number
-  readonly maxItems?: number
-  readonly options?: ReadonlyArray<A>
-  readonly meta?: Readonly<Record<string, unknown>>
-}
-
-export type FieldLimitations<A = unknown> = FieldLimitationsExternalApi<A>
-
-export type Limitations = Readonly<Record<string, FieldLimitations>>
-
-export interface FormState<Values> {
-  readonly values: Values
-  readonly initialValues: Values
-  readonly touched: Readonly<Record<string, boolean>>
-  readonly errors: FormErrors
-  readonly dirtyPaths: ReadonlyArray<string>
-  readonly submitCount: number
-  readonly validationCount: number
-  readonly lastSubmittedValues: Option.Option<Values>
-  readonly arrayKeys: Readonly<Record<string, ReadonlyArray<string>>>
-}
-
-export interface FieldBinding<A> {
-  readonly path: string
-  readonly value: A
-  readonly set: (value: A | ((prev: A) => A)) => void
-  readonly blur: () => void
-  readonly error: Option.Option<string>
-  readonly dirty: boolean
-  readonly touched: boolean
-  readonly validating: boolean
-  readonly limitations: FieldLimitations<A>
-}
-
-export interface ArrayItemView<Item> {
-  readonly key: string
-  readonly index: number
-  readonly value: Item
-  readonly remove: () => void
-  readonly move: (to: number) => void
-}
-
-export interface ArrayBinding<Item> {
-  readonly path: string
-  readonly items: ReadonlyArray<ArrayItemView<Item>>
-  readonly append: (value?: Item) => void
-  readonly remove: (index: number) => void
-  readonly move: (from: number, to: number) => void
-  readonly swap: (a: number, b: number) => void
-  readonly limitations: FieldLimitations<ReadonlyArray<Item>>
-}
-
-export interface FormView<Values, Inputs = {}> {
-  readonly values: Values
-  readonly inputs: Inputs
-  readonly errors: FormErrors
-  readonly dirty: boolean
-  readonly canSubmit: boolean
-  readonly submitCount: number
-  readonly validationCount: number
-  readonly lastSubmittedValues: Option.Option<Values>
-  readonly submit: () => void
-  readonly reset: () => void
-  readonly validate: () => void
-  readonly field: <P extends FieldPath<Values>>(path: P) => FieldBinding<PathValue<Values, P>>
-  readonly array: <P extends ArrayPath<Values>>(path: P) => ArrayBinding<ArrayItem<Values, P>>
-  readonly variantValue: <P extends VariantPath<Values>>(path: P) => VariantValue<Values, P>
-}
-
-type InputRecord = Readonly<Record<string, AnySource>>
-
-// Extracted structurally (`S['name']`) rather than through a `Source<infer N,
-// unknown>` conditional: `Source`'s value parameter is invariant (`in out A`),
-// so a concrete `StateToken<'x', V>` never matches `Source<_, unknown>` and the
-// conditional would erase every input's key to `never`.
-type SourceName<S extends AnySource> = S['name']
-type SourceValue<S> = S extends Source<string, infer A> ? A : never
-
-type InputsObject<Inputs extends InputRecord> = {
-  readonly [K in keyof Inputs as SourceName<Inputs[K]>]: SourceValue<Inputs[K]>
-}
-
-type InputStores<Inputs extends InputRecord> = {
-  [K in keyof Inputs]: Inputs[K] extends { readonly store: Context.Tag<infer Service, any> }
-    ? Service
-    : never
-}[keyof Inputs]
-
-type ValuesOfSchema<S extends S.Schema.Any> = S.Schema.Encoded<S>
-type DecodedOfSchema<S extends S.Schema.Any> = S.Schema.Type<S>
-
-export interface RuntimeConfig<Values, Decoded, Inputs> {
-  readonly initial: Values
-  // oxlint-disable-next-line reform-rules/no-optional-fields -- optional Effect-returning config knob (not a serializable shape); Option would break external form definitions
-  readonly limit?: (ctx: {
-    readonly values: Values
-    readonly inputs: Inputs
-  }) => Limitations
-  readonly validate: (ctx: {
-    readonly values: Values
-    readonly decoded: Decoded
-    readonly inputs: Inputs
-  }) => Effect.Effect<ReadonlyArray<FormError>, never, never>
-  readonly submit: (ctx: {
-    readonly values: Values
-    readonly decoded: Decoded
-    readonly inputs: Inputs
-  }) => Effect.Effect<void, unknown, never>
-}
-
-export interface FormLiveConfig<Values, Decoded, Inputs, R = never> {
-  readonly initial: Values
-  // oxlint-disable-next-line reform-rules/no-optional-fields -- optional Effect-returning config knob; Option would break external form definitions
-  readonly limit?: (ctx: {
-    readonly values: Values
-    readonly inputs: Inputs
-  }) => Limitations
-  // oxlint-disable-next-line reform-rules/no-optional-fields -- optional Effect-returning config knob; Option would break external form definitions
-  readonly validate?: (ctx: {
-    readonly values: Values
-    readonly decoded: Decoded
-    readonly inputs: Inputs
-  }) =>
-    | void
-    | FormError
-    | ReadonlyArray<FormError>
-    | Effect.Effect<void | FormError | ReadonlyArray<FormError>, never, R>
-  // oxlint-disable-next-line reform-rules/no-optional-fields -- optional Effect-returning config knob; Option would break external form definitions
-  readonly submit?: (ctx: {
-    readonly values: Values
-    readonly decoded: Decoded
-    readonly inputs: Inputs
-  }) => void | Effect.Effect<unknown, unknown, R>
-}
-
-export interface FormManifest<N extends string, Schema extends S.Schema.Any, Inputs extends InputRecord> {
-  readonly kind: 'Form'
-  readonly name: N
-  readonly schema: Schema
-  readonly inputs: Inputs
-}
-
-interface FormEvents {
-  readonly set: Event.EventClass<string, { readonly path: string; readonly value: unknown }>
-  readonly blur: Event.EventClass<string, { readonly path: string }>
-  readonly reset: Event.EventClass<string, {}>
-  readonly validationFinished: Event.EventClass<string, { readonly errors: FormErrors }>
-  readonly submitAttempted: Event.EventClass<string, {}>
-  readonly submitSucceeded: Event.EventClass<string, { readonly values: unknown }>
-  readonly append: Event.EventClass<string, { readonly path: string; readonly value: unknown }>
-  readonly remove: Event.EventClass<string, { readonly path: string; readonly index: number }>
-  readonly move: Event.EventClass<string, { readonly path: string; readonly from: number; readonly to: number }>
-  readonly swap: Event.EventClass<string, { readonly path: string; readonly a: number; readonly b: number }>
-}
-
-export interface FormClass<
-  N extends string,
-  Schema extends S.Schema.Any,
-  Inputs extends InputRecord,
-> {
-  new (): {}
-  readonly manifest: FormManifest<N, Schema, Inputs>
-  readonly state: State.StateClass<`${N}/state`, FormState<ValuesOfSchema<Schema>>>
-  readonly config: Context.Tag<
-    RuntimeConfig<ValuesOfSchema<Schema>, DecodedOfSchema<Schema>, InputsObject<Inputs>>,
-    RuntimeConfig<ValuesOfSchema<Schema>, DecodedOfSchema<Schema>, InputsObject<Inputs>>
-  >
-  readonly events: FormEvents
-  readonly reducer: Reducer.StateReducerClass<
-    State.StateClass<`${N}/state`, FormState<ValuesOfSchema<Schema>>>,
-    ReadonlyArray<Event.AnyEvent>
-  >
-}
-
-// `any` (not `InputRecord`) in the inputs slot: the inputs type flows into the
-// invariant `config` tag (via `InputsObject`), so a wildcard there must be `any`
-// for a concrete form — whose inputs object has real keys — to remain assignable
-// to `AnyForm`. Same Schema-variance escape the schema slot already uses.
-export type AnyForm = FormClass<string, S.Schema.Any, any>
-
-export type Values<F extends AnyForm> = F extends FormClass<string, infer Schema, any>
-  ? ValuesOfSchema<Schema>
-  : never
-
-export type Decoded<F extends AnyForm> = F extends FormClass<string, infer Schema, any>
-  ? DecodedOfSchema<Schema>
-  : never
-
-export type Inputs<F extends AnyForm> = F extends FormClass<string, S.Schema.Any, infer Inputs>
-  ? InputsObject<Inputs>
-  : never
-
-export type View<F extends AnyForm> = FormView<Values<F>, Inputs<F>>
-
-const unknownSchema: S.Schema<any, any> = Fn.unsafeCoerce(S.Unknown)
-
-const arrayKeyCounter = { current: 0 }
-const makeArrayKey = (): string => `form-item-${arrayKeyCounter.current++}`
-
-export const arrayKeysFor = (source: unknown, path = ''): Record<string, ReadonlyArray<string>> => {
-  const out: Record<string, ReadonlyArray<string>> = {}
-  const visit = (node: KeyVisitNode): void => {
-    if (Array.isArray(node.current)) {
-      out[node.path] = node.current.map(() => makeArrayKey())
-      node.current.forEach((element, index) => visit({ current: element, path: `${node.path}[${index}]` }))
-      return
-    }
-    if (node.current !== null && typeof node.current === 'object') {
-      Record.toEntries(Fn.unsafeCoerce<unknown, Record<string, unknown>>(node.current)).forEach(([key, child]) =>
-        visit({ current: child, path: node.path.length === 0 ? key : `${node.path}.${key}` }),
-      )
-    }
-  }
-  visit({ current: source, path })
-  return out
-}
-
-const initialState = <Values>(initial: Values): FormState<Values> => ({
-  values: initial,
-  initialValues: initial,
-  touched: {},
-  errors: {},
-  dirtyPaths: [],
-  submitCount: 0,
-  validationCount: 0,
-  lastSubmittedValues: Option.none(),
-  arrayKeys: arrayKeysFor(initial),
-})
-
-const markTouched = (touched: Readonly<Record<string, boolean>>, path: string): Readonly<Record<string, boolean>> =>
-  ({ ...touched, [path]: true })
-
-interface ArrayLookup {
-  readonly source: unknown
-  readonly path: string
-}
-
-interface KeyVisitNode {
-  readonly current: unknown
-  readonly path: string
-}
-
-interface PathInput<Values> {
-  readonly state: FormState<Values>
-  readonly path: string
-}
-
-interface SetPathInput<Values> extends PathInput<Values> {
-  readonly value: unknown
-}
-
-interface RemovePathInput<Values> extends PathInput<Values> {
-  readonly index: number
-}
-
-interface MovePathInput<Values> extends PathInput<Values> {
-  readonly from: number
-  readonly to: number
-}
-
-interface SwapPathInput<Values> extends PathInput<Values> {
-  readonly first: number
-  readonly second: number
-}
-
-const withValues = <Values>(state: FormState<Values>, nextValues: Values): FormState<Values> => ({
-  ...state,
-  values: nextValues,
-  dirtyPaths: recalculateDirtyPaths(state.initialValues, nextValues),
-})
-
-const currentArray = (input: ArrayLookup): ReadonlyArray<unknown> => {
-  const current = getNestedValue(input.source, input.path)
-  return Array.isArray(current) ? current : []
-}
-
-const updateKeys = (
-  state: FormState<unknown>,
-  path: string,
-  transform: (keys: ReadonlyArray<string>) => ReadonlyArray<string>,
-): Readonly<Record<string, ReadonlyArray<string>>> => {
-  const existing = state.arrayKeys[path] ?? currentArray({ source: state.values, path }).map(() => makeArrayKey())
-  return { ...state.arrayKeys, [path]: transform(existing) }
-}
-
-const setAtPath = <Values>(input: SetPathInput<Values>): FormState<Values> =>
-  withValues(input.state, setNestedValue(input.state.values, input.path, input.value))
-
-const appendAtPath = <Values>(input: SetPathInput<Values>): FormState<Values> => {
-  const elements = currentArray({ source: input.state.values, path: input.path })
-  const nextValues = setNestedValue(input.state.values, input.path, [...elements, input.value])
-  return {
-    ...withValues(input.state, nextValues),
-    arrayKeys: updateKeys(Fn.unsafeCoerce(input.state), input.path, (keys) => [...keys, makeArrayKey()]),
-  }
-}
-
-const removeAtPath = <Values>(input: RemovePathInput<Values>): FormState<Values> => {
-  const elements = currentArray({ source: input.state.values, path: input.path })
-  if (input.index < 0 || input.index >= elements.length) {
-    return input.state
-  }
-  const nextValues = setNestedValue(
-    input.state.values,
-    input.path,
-    elements.filter((_, position) => position !== input.index),
-  )
-  return {
-    ...withValues(input.state, nextValues),
-    arrayKeys: updateKeys(Fn.unsafeCoerce(input.state), input.path, (keys) =>
-      keys.filter((_, position) => position !== input.index),
-    ),
-  }
-}
-
-const moveAtPath = <Values>(input: MovePathInput<Values>): FormState<Values> => {
-  const elements = currentArray({ source: input.state.values, path: input.path })
-  const next = moveAt(elements, input.from, input.to)
-  if (next === elements) {
-    return input.state
-  }
-  const nextValues = setNestedValue(input.state.values, input.path, next)
-  return {
-    ...withValues(input.state, nextValues),
-    arrayKeys: updateKeys(Fn.unsafeCoerce(input.state), input.path, (keys) => moveAt(keys, input.from, input.to)),
-  }
-}
-
-const swapAtPath = <Values>(input: SwapPathInput<Values>): FormState<Values> => {
-  const elements = currentArray({ source: input.state.values, path: input.path })
-  if (
-    input.first < 0 ||
-    input.second < 0 ||
-    input.first >= elements.length ||
-    input.second >= elements.length ||
-    input.first === input.second
-  ) {
-    return input.state
-  }
-  const swapped = replaceAt(replaceAt(elements, input.first, elements[input.second]), input.second, elements[input.first])
-  const nextValues = setNestedValue(input.state.values, input.path, swapped)
-  return {
-    ...withValues(input.state, nextValues),
-    arrayKeys: updateKeys(Fn.unsafeCoerce(input.state), input.path, (keys) =>
-      replaceAt(
-        replaceAt(keys, input.first, keys[input.second] ?? makeArrayKey()),
-        input.second,
-        keys[input.first] ?? makeArrayKey(),
-      ),
-    ),
-  }
-}
+export type {
+  AnyForm,
+  ArrayBinding,
+  ArrayItemView,
+  Decoded,
+  FieldBinding,
+  FieldLimitations,
+  FieldLimitationsExternalApi,
+  FormClass,
+  FormLiveConfig,
+  FormManifest,
+  FormState,
+  FormView,
+  Inputs,
+  Limitations,
+  RuntimeConfig,
+  Values,
+  View,
+} from './formTypes'
+
+const unknownSchema: S.Schema.AnyNoContext = Fn.unsafeCoerce(S.Unknown)
+
+export { arrayKeysFor } from './formState'
 
 interface MakeConfig<Schema extends S.Schema.Any, Inputs extends InputRecord> {
   readonly schema: Schema
@@ -571,169 +230,4 @@ export const live = <
   )
 }
 
-const readInput = <Source extends AnySource>(
-  source: Source,
-): Effect.Effect<SourceValue<Source>, never, Store<SourceValue<Source>>> =>
-  Fn.unsafeCoerce(
-    Effect.gen(function* () {
-      const store = yield* source.store
-      const tracker = yield* Effect.serviceOption(CurrentTracker)
-      if (Option.isSome(tracker)) {
-        tracker.value.add(store)
-      }
-      return store.getSnapshot()
-    }),
-  )
-
-const readInputs = <Inputs extends InputRecord>(
-  inputs: Inputs,
-): Effect.Effect<InputsObject<Inputs>, never, InputStores<Inputs>> =>
-  Fn.unsafeCoerce(
-    Effect.gen(function* () {
-      const pairs = yield* Effect.forEach(Object.values(inputs), (source) =>
-        Effect.map(readInput(source), (snapshot) => [source.name, snapshot] as const),
-      )
-      return Record.fromEntries(pairs)
-    }),
-  )
-
-const limitationsFor = <A>(
-  limitations: Limitations,
-  path: string,
-): FieldLimitations<A> =>
-  Fn.unsafeCoerce(Option.getOrElse(Option.fromNullable(limitations[path]), () => ({})))
-
-const trigger = <P>(eventTrigger: Effect.Effect<Trigger<P>, never, Bus>): Effect.Effect<Trigger<P>, never, Bus> =>
-  eventTrigger
-
-// oxlint-disable-next-line reform-rules/prefer-effect-fn -- public generic view: the explicit R (Store | RuntimeConfig | Bus | InputStores) must be preserved verbatim; Effect.fn would re-infer requirements off the erased AnyForm wildcard
-export const view = <F extends AnyForm>(
-  form: F,
-): Effect.Effect<View<F>, never, Store<FormState<Values<F>>> | RuntimeConfig<Values<F>, Decoded<F>, Inputs<F>> | Bus | InputStores<F['manifest']['inputs']>> =>
-  Effect.gen(function* () {
-    const state = yield* form.state
-    const runtimeConfig = yield* form.config
-    // Erased boundary (same shape as the coercions closing `live`/`readInputs`):
-    // under the `AnyForm` constraint `form.manifest.inputs` is the wildcard
-    // `any`, which would dissolve the generator's R to `unknown`; restate the
-    // call at the concrete `F`'s types so R keeps the declared input stores.
-    const inputs: Inputs<F> = Fn.unsafeCoerce(
-      yield* readInputs(Fn.unsafeCoerce<typeof form.manifest.inputs, InputRecord>(form.manifest.inputs)),
-    )
-    const limitations = Option.getOrElse(
-      Option.fromNullable(runtimeConfig.limit?.({ values: state.values, inputs })),
-      () => ({}),
-    )
-    const setField = yield* trigger(form.events.set.trigger)
-    const blurField = yield* trigger(form.events.blur.trigger)
-    const reset = yield* trigger(form.events.reset.trigger)
-    const append = yield* trigger(form.events.append.trigger)
-    const remove = yield* trigger(form.events.remove.trigger)
-    const move = yield* trigger(form.events.move.trigger)
-    const swap = yield* trigger(form.events.swap.trigger)
-    const runtime = yield* Effect.runtime<Bus>()
-
-    const schema: S.Schema<Decoded<F>, Values<F>, never> = Fn.unsafeCoerce(form.manifest.schema)
-    const decodeEither = S.decodeUnknownEither(schema, { errors: 'all' })(state.values)
-    const canSubmit = Either.isRight(decodeEither) && Record.keys(state.errors).length === 0
-
-    // oxlint-disable-next-line reform-rules/prefer-effect-fn -- local closure whose inferred R must flow into the parent view gen; Effect.fn would force an explicit Return annotation over the erased AnyForm requirements
-    const runValidation = (publishSubmitAttempt: boolean) =>
-      Effect.gen(function* () {
-        if (publishSubmitAttempt) {
-          yield* Event.dispatch(form.events.submitAttempted, {})
-        }
-        const decoded = S.decodeUnknownEither(schema, { errors: 'all' })(state.values)
-        if (Either.isLeft(decoded)) {
-          yield* Event.dispatch(form.events.validationFinished, { errors: routeParseError(decoded.left) })
-          return Option.none<Decoded<F>>()
-        }
-        const custom = yield* runtimeConfig.validate({ values: state.values, decoded: decoded.right, inputs })
-        const errors = errorsToRecord(custom)
-        yield* Event.dispatch(form.events.validationFinished, { errors })
-        return Record.keys(errors).length === 0
-          ? Option.some(Fn.unsafeCoerce<unknown, Decoded<F>>(decoded.right))
-          : Option.none<Decoded<F>>()
-      })
-
-    const submit = () => {
-      Runtime.runFork(runtime)(
-        Effect.gen(function* () {
-          const decoded = yield* runValidation(true)
-          if (Option.isNone(decoded)) {
-            return
-          }
-          yield* runtimeConfig.submit({ values: state.values, decoded: decoded.value, inputs })
-          yield* Event.dispatch(form.events.submitSucceeded, { values: state.values })
-        }).pipe(Effect.catchAllCause((cause) => Effect.logError('reform form submit failed', cause))),
-      )
-    }
-
-    const validate = () => {
-      Runtime.runFork(runtime)(runValidation(false))
-    }
-
-    const field = <P extends FieldPath<Values<F>>>(path: P): FieldBinding<PathValue<Values<F>, P>> => {
-      const fieldValue: PathValue<Values<F>, P> = Fn.unsafeCoerce(getNestedValue(state.values, path))
-      return {
-        path,
-        value: fieldValue,
-        set: (next) => {
-          if (typeof next === 'function') {
-            const updater = Fn.unsafeCoerce<typeof next, (prev: PathValue<Values<F>, P>) => PathValue<Values<F>, P>>(
-              next,
-            )
-            setField({ path, value: updater(fieldValue) })
-            return
-          }
-          setField({ path, value: next })
-        },
-        blur: () => blurField({ path }),
-        error: firstError(state.errors, path),
-        dirty: isPathOrParentDirty(state.dirtyPaths, path),
-        touched: state.touched[path] === true,
-        validating: false,
-        limitations: limitationsFor<PathValue<Values<F>, P>>(limitations, path),
-      }
-    }
-
-    const array = <P extends ArrayPath<Values<F>>>(path: P): ArrayBinding<ArrayItem<Values<F>, P>> => {
-      const arrayValues: ReadonlyArray<ArrayItem<Values<F>, P>> = Fn.unsafeCoerce(
-        currentArray({ source: state.values, path }),
-      )
-      const keys = state.arrayKeys[path] ?? arrayValues.map((_, index) => `${path}-${index}`)
-      return {
-        path,
-        items: arrayValues.map((element, index) => ({
-          value: element,
-          index,
-          key: keys[index] ?? `${path}-${index}`,
-          remove: () => remove({ path, index }),
-          move: (to) => move({ path, from: index, to }),
-        })),
-        append: (element) => append({ path, value: element }),
-        remove: (index) => remove({ path, index }),
-        move: (from, to) => move({ path, from, to }),
-        swap: (first, second) => swap({ path, a: first, b: second }),
-        limitations: limitationsFor<ReadonlyArray<ArrayItem<Values<F>, P>>>(limitations, path),
-      }
-    }
-
-    const formView: View<F> = Fn.unsafeCoerce({
-      values: state.values,
-      inputs,
-      errors: state.errors,
-      dirty: state.dirtyPaths.length > 0,
-      canSubmit,
-      submitCount: state.submitCount,
-      validationCount: state.validationCount,
-      lastSubmittedValues: state.lastSubmittedValues,
-      submit,
-      reset: () => reset({}),
-      validate,
-      field,
-      array,
-      variantValue: (path: string) => Fn.unsafeCoerce(getNestedValue(state.values, path)),
-    })
-    return formView
-  })
+export { view } from './formView'