@playfast/reform-forms 1.0.1 → 1.1.1

package/src/formState.ts

@@ -0,0 +1,166 @@
+import { Function as Fn, Option, Record } from 'effect'
+import {
+  getNestedValue,
+  moveAt,
+  recalculateDirtyPaths,
+  replaceAt,
+  setNestedValue,
+} from './path'
+import type { FormState } from './formTypes'
+
+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
+}
+
+export const initialState = <Values>(initial: Values): FormState<Values> => ({
+  values: initial,
+  initialValues: initial,
+  touched: {},
+  errors: {},
+  dirtyPaths: [],
+  submitCount: 0,
+  validationCount: 0,
+  lastSubmittedValues: Option.none(),
+  arrayKeys: arrayKeysFor(initial),
+})
+
+export 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),
+})
+
+export 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) }
+}
+
+export const setAtPath = <Values>(input: SetPathInput<Values>): FormState<Values> =>
+  withValues(input.state, setNestedValue(input.state.values, input.path, input.value))
+
+export 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()]),
+  }
+}
+
+export 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),
+    ),
+  }
+}
+
+export 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)),
+  }
+}
+
+export 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(),
+      ),
+    ),
+  }
+}

package/src/formTypes.ts

@@ -0,0 +1,211 @@
+import { Context, Effect, Option, Schema as S } from 'effect'
+import type { AnySource, Event, Reducer, Source, State } from '@playfast/reform'
+import type {
+  ArrayItem,
+  ArrayPath,
+  FieldPath,
+  PathValue,
+  VariantPath,
+  VariantValue,
+} from './path'
+import type { FormError, FormErrors } from './validation'
+
+export type AnyValue = S.Schema.Type<S.Schema.Any>
+
+// Wire-serialized UI knobs: ExternalApi postfix allows optional fields (Option would break the contract).
+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>
+}
+
+export type InputRecord = Readonly<Record<string, AnySource>>
+
+// Structural `S['name']`: Source value param is invariant, so `Source<_, unknown>` erases keys to never.
+export type SourceName<S extends AnySource> = S['name']
+export type SourceValue<S> = S extends Source<string, infer A> ? A : never
+
+export type InputsObject<Inputs extends InputRecord> = {
+  readonly [K in keyof Inputs as SourceName<Inputs[K]>]: SourceValue<Inputs[K]>
+}
+
+export type InputStores<Inputs extends InputRecord> = {
+  [K in keyof Inputs]: Inputs[K] extends { readonly store: Context.Tag<infer Service, AnyValue> }
+    ? Service
+    : never
+}[keyof Inputs]
+
+export type ValuesOfSchema<S extends S.Schema.Any> = S.Schema.Encoded<S>
+export 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
+}
+
+export 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` inputs wildcard: config tag is invariant via InputsObject; InputRecord would reject concrete forms.
+export type AnyForm = FormClass<string, S.Schema.Any, AnyValue>
+
+export type Values<F extends AnyForm> = F extends FormClass<string, infer Schema, AnyValue>
+  ? ValuesOfSchema<Schema>
+  : never
+
+export type Decoded<F extends AnyForm> = F extends FormClass<string, infer Schema, AnyValue>
+  ? 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>>

package/src/formView.ts

@@ -0,0 +1,202 @@
+import {
+  Effect,
+  Either,
+  Function as Fn,
+  Option,
+  Record,
+  Runtime,
+  Schema as S,
+} from 'effect'
+import {
+  Bus,
+  CurrentTracker,
+  Event,
+  type Store,
+  type Trigger,
+} from '@playfast/reform'
+import type { AnySource } from '@playfast/reform'
+import { currentArray } from './formState'
+import { getNestedValue, isPathOrParentDirty } from './path'
+import type { ArrayItem, ArrayPath, FieldPath, PathValue } from './path'
+import { errorsToRecord, firstError, routeParseError } from './validation'
+import type {
+  AnyForm,
+  ArrayBinding,
+  Decoded,
+  FieldBinding,
+  FieldLimitations,
+  FormState,
+  InputRecord,
+  Inputs,
+  InputsObject,
+  InputStores,
+  Limitations,
+  RuntimeConfig,
+  SourceValue,
+  Values,
+  View,
+} from './formTypes'
+
+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
+    // AnyForm erases inputs to `any`; restate at concrete F so R keeps 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
+  })

package/src/path.ts

@@ -5,8 +5,7 @@ import { sort as sortArray } from 'effect/Array'
 const BRACKET_NOTATION_REGEX = /\[(\d+)\]/g
 const NO_INDEX = -1
 
-// `null` is a genuine leaf of arbitrary form values (JSON-shaped user data); it
-// is matched here to stop path recursion at primitive leaves.
+// JSON null is a real form-value leaf — stop path recursion here.
 export type Primitive =
   | string
   | number
@@ -83,8 +82,6 @@ export type VariantCase<V, Tag extends string> = Extract<V, { readonly _tag: Tag
 
 export type VariantBody<V, Tag extends string> = Omit<VariantCase<V, Tag>, '_tag'>
 
-// Typed view over an arbitrary object for string-keyed traversal of unknown form
-// values. `unsafeCoerce` is the Effect-blessed identity coercion (no `as`).
 const asRecord = (source: unknown): Record<string, unknown> => Fn.unsafeCoerce(source)
 
 export const schemaPathToFieldPath = (path: ReadonlyArray<PropertyKey>): string =>