@playfast/reform-forms 1.2.1 → 1.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@playfast/reform-forms",
-  "version": "1.2.1",
+  "version": "1.4.0",
   "description": "Headless, schema-driven form state for reform — values, validation, field limitations, list operations, and submit flow, rendering nothing.",
   "keywords": [
     "effect",
@@ -21,15 +21,26 @@
     "directory": "packages/forms"
   },
   "files": [
+    "dist",
     "src",
     "README.md"
   ],
   "type": "module",
   "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
   "exports": {
     "./package.json": "./package.json",
-    ".": "./src/index.ts",
-    "./*": "./src/*.ts"
+    ".": {
+      "playfast-src": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./*": {
+      "playfast-src": "./src/*.ts",
+      "types": "./dist/*.d.ts",
+      "default": "./dist/*.js"
+    }
   },
   "publishConfig": {
     "access": "public"
@@ -37,12 +48,13 @@
   "scripts": {
     "clean": "rm -rf dist .tsbuildinfo",
     "check": "tsc --noEmit",
-    "build": "tsc -p tsconfig.build.json",
+    "build": "rm -rf dist .tsbuildinfo && tsc -p tsconfig.build.json && bun ../../scripts/fix-esm-extensions.ts dist",
     "test": "vitest run",
     "test:watch": "vitest",
     "coverage": "vitest run --coverage",
     "lint": "oxlint src",
-    "lint:fix": "oxlint --fix src"
+    "lint:fix": "oxlint --fix src",
+    "prepack": "bun run build"
   },
   "peerDependencies": {
     "@playfast/reform": "*",

package/src/formReindex.ts

@@ -0,0 +1,115 @@
+import { Match, Option, Record } from 'effect'
+import type { FormState } from './formTypes'
+
+// Every per-field record — `touched`, `errors`, and the nested `arrayKeys` of a
+// list inside an item — is addressed by a path that embeds the item's index.
+// A structural edit therefore has to carry that metadata with the item, or the
+// neighbour that slides into the vacated index inherits it: a removed row's
+// touched flag, or a reordered row's validation error, landing on someone else.
+type IndexMap = (index: number) => Option.Option<number>
+
+interface ReindexInput {
+  readonly key: string
+  readonly path: string
+  readonly moveIndex: IndexMap
+}
+
+// `members[2].tags` under path `members` → index 2, suffix `.tags`.
+const indexedSegment = /^\[(\d+)\]/
+
+const reindexedKey = ({ key, path, moveIndex }: ReindexInput): Option.Option<string> => {
+  const rest = key.slice(path.length)
+  return Option.match(Option.fromNullable(indexedSegment.exec(rest)), {
+    onNone: () => Option.some(key),
+    onSome: (found) => {
+      const index = Number(found[1])
+      if (!Number.isInteger(index)) {
+        return Option.some(key)
+      }
+      const suffix = rest.slice(found[0].length)
+      return Option.map(moveIndex(index), (next) => `${path}[${next}]${suffix}`)
+    },
+  })
+}
+
+interface ReindexPathsInput<V> {
+  readonly entries: Readonly<Record<string, V>>
+  readonly path: string
+  readonly moveIndex: IndexMap
+}
+
+const reindexPaths = <V>({
+  entries,
+  path,
+  moveIndex,
+}: ReindexPathsInput<V>): Readonly<Record<string, V>> => {
+  const prefix = `${path}[`
+  const moved = ([key, entry]: readonly [string, V]): ReadonlyArray<readonly [string, V]> =>
+    Option.match(reindexedKey({ key, path, moveIndex }), {
+      onNone: (): ReadonlyArray<readonly [string, V]> => [],
+      onSome: (nextKey) => [[nextKey, entry] as const],
+    })
+  return Record.fromEntries(
+    Record.toEntries(entries).flatMap((pair) =>
+      pair[0].startsWith(prefix) ? moved(pair) : [pair],
+    ),
+  )
+}
+
+// `arrayKeys[path]` itself is rewritten by `updateKeys`; only the entries nested
+// under an item (`members[0].tags`) need moving, and those start with the prefix.
+interface ReindexMetadataInput<Values> {
+  readonly state: FormState<Values>
+  readonly path: string
+  readonly moveIndex: IndexMap
+}
+
+export const reindexMetadata = <Values>({
+  state,
+  path,
+  moveIndex,
+}: ReindexMetadataInput<Values>): Pick<FormState<Values>, 'touched' | 'errors'> & {
+  readonly nestedKeys: Readonly<Record<string, ReadonlyArray<string>>>
+} => ({
+  touched: reindexPaths({ entries: state.touched, path, moveIndex }),
+  errors: reindexPaths({ entries: state.errors, path, moveIndex }),
+  nestedKeys: reindexPaths({ entries: state.arrayKeys, path, moveIndex }),
+})
+
+export const removedIndexMap =
+  (removed: number): IndexMap =>
+  (index) =>
+    index === removed ? Option.none() : Option.some(index > removed ? index - 1 : index)
+
+interface MoveRange {
+  readonly from: number
+  readonly to: number
+}
+
+export const movedIndexMap =
+  ({ from, to }: MoveRange): IndexMap =>
+  (index) => {
+    if (index === from) {
+      return Option.some(to)
+    }
+    if (from < to) {
+      return Option.some(index > from && index <= to ? index - 1 : index)
+    }
+    return Option.some(index >= to && index < from ? index + 1 : index)
+  }
+
+interface SwapPair {
+  readonly first: number
+  readonly second: number
+}
+
+export const swappedIndexMap =
+  ({ first, second }: SwapPair): IndexMap =>
+  (index) =>
+    Option.some(
+      Match.value(index).pipe(
+        Match.when(first, () => second),
+        Match.when(second, () => first),
+        Match.orElse(() => index),
+      ),
+    )

package/src/formState-array-keys.test.ts

@@ -0,0 +1,179 @@
+import { expect, it } from '@effect/vitest'
+import { Effect, Function as Fn, Layer, Schema as S } from 'effect'
+import { Engine } from '@playfast/reform'
+import * as Form from './form'
+import type { ArrayBinding, FieldBinding, FormView } from './formTypes'
+
+// Same polling idiom as the neighbouring suites: never wait a fixed duration.
+const waitUntil = <A, R>(
+  read: Effect.Effect<A, never, R>,
+  pred: (value: A) => boolean,
+  rounds = 100,
+): Effect.Effect<A, never, R> =>
+  Effect.flatMap(read, (value) =>
+    pred(value) || rounds <= 0
+      ? Effect.succeed(value)
+      : Effect.flatMap(Effect.yieldNow(), () => waitUntil(read, pred, rounds - 1)),
+  )
+
+const RosterSchema = S.Struct({
+  members: S.Array(S.Struct({ name: S.String, tags: S.Array(S.String) })),
+})
+
+type RosterValues = S.Schema.Encoded<typeof RosterSchema>
+
+class AppendKeysForm extends Form.make('FormsHuntAppendKeysForm', { schema: RosterSchema }) {}
+
+const rosterLayer = Form.live(AppendKeysForm, {
+  // `ada` comes from `initial`, so `initialState` seeds stable keys for her nested
+  // `tags` list. Every other member in these tests arrives through `append`.
+  initial: { members: [{ name: 'ada', tags: ['a1', 'a2'] }] },
+}).pipe(Layer.provideMerge(Engine))
+
+// A list nested inside an array item is addressed by an indexed runtime path
+// (`members[1].tags`). `ArrayPath<Values>` cannot spell one, so every renderer
+// reaches it the way `@playfast/reform-forms-react` does — through the erased
+// `RuntimeFormView` shape whose `array` takes a plain string.
+const nestedArray = (view: FormView<RosterValues>, path: string): ArrayBinding<string> => {
+  const runtimeArray: (candidate: string) => ArrayBinding<string> = Fn.unsafeCoerce(view.array)
+  return runtimeArray(path)
+}
+
+const nestedField = (
+  view: FormView<RosterValues>,
+  path: string,
+): FieldBinding<ReadonlyArray<string>> => {
+  const runtimeField: (candidate: string) => FieldBinding<ReadonlyArray<string>> = Fn.unsafeCoerce(
+    view.field,
+  )
+  return runtimeField(path)
+}
+
+const keysOf = (view: FormView<RosterValues>, path: string): ReadonlyArray<string> =>
+  nestedArray(view, path).items.map((item) => item.key)
+
+const tagCount = (values: RosterValues, index: number): number =>
+  values.members[index]?.tags.length ?? 0
+
+// ---------------------------------------------------------------------------
+// `appendAtPath` mints one key for the row it adds to `arrayKeys[path]`, but it
+// never derives keys for the arrays nested INSIDE the appended value the way
+// `initialState` does via `arrayKeysFor`. Those nested lists then fall through
+// `formView.array`'s positional fallback (`${path}-${index}`) until some later
+// edit lazily mints real keys — at which point every existing row of that list
+// changes identity and a renderer remounts rows the user never touched.
+// ---------------------------------------------------------------------------
+
+it.scopedLive('a nested list inside an appended item keeps its row keys when a row is added', () =>
+  Effect.gen(function* () {
+    const initial = yield* Form.view(AppendKeysForm)
+    initial.array('members').append({ name: 'zoe', tags: ['z1', 'z2'] })
+    const seeded = yield* waitUntil(
+      Form.view(AppendKeysForm),
+      (view) => view.values.members.length === 2,
+    )
+
+    const adaBefore = keysOf(seeded, 'members[0].tags')
+    const zoeBefore = keysOf(seeded, 'members[1].tags')
+    expect(adaBefore.length).toBe(2)
+    expect(zoeBefore.length).toBe(2)
+
+    nestedArray(seeded, 'members[0].tags').append('a3')
+    const adaGrown = yield* waitUntil(
+      Form.view(AppendKeysForm),
+      (view) => tagCount(view.values, 0) === 3,
+    )
+    nestedArray(adaGrown, 'members[1].tags').append('z3')
+    const grown = yield* waitUntil(
+      Form.view(AppendKeysForm),
+      (view) => tagCount(view.values, 1) === 3,
+    )
+
+    // CONTROL — appending a row to ada's list leaves the two existing rows' keys
+    // untouched, which is what "stable item keys" means.
+    expect(keysOf(grown, 'members[0].tags').slice(0, 2)).toEqual(adaBefore)
+    // SUBJECT — the same operation on zoe's list must be just as stable.
+    expect(keysOf(grown, 'members[1].tags').slice(0, 2)).toEqual(zoeBefore)
+
+    // Root cause, stated directly: ada's rows carry minted keys, zoe's carry the
+    // positional `${path}-${index}` fallback because `append` seeded none.
+    expect(adaBefore.every((key) => key.startsWith('form-item-'))).toBe(true)
+    expect(zoeBefore.every((key) => key.startsWith('form-item-'))).toBe(true)
+  }).pipe(Effect.provide(rosterLayer)),
+)
+
+it.scopedLive('a nested list inside an appended item keeps its row keys across a parent move', () =>
+  Effect.gen(function* () {
+    const initial = yield* Form.view(AppendKeysForm)
+    initial.array('members').append({ name: 'zoe', tags: ['z1', 'z2'] })
+    const seeded = yield* waitUntil(
+      Form.view(AppendKeysForm),
+      (view) => view.values.members.length === 2,
+    )
+
+    const adaBefore = keysOf(seeded, 'members[0].tags')
+    const zoeBefore = keysOf(seeded, 'members[1].tags')
+
+    // Reorder the OUTER list; neither nested row was edited.
+    seeded.array('members').move(1, 0)
+    const moved = yield* waitUntil(
+      Form.view(AppendKeysForm),
+      (view) => view.values.members[0]?.name === 'zoe',
+    )
+    expect(moved.values.members.map((member) => member.name)).toEqual(['zoe', 'ada'])
+
+    // CONTROL — ada's nested keys travel with her to index 1 (reindexMetadata).
+    expect(keysOf(moved, 'members[1].tags')).toEqual(adaBefore)
+    // SUBJECT — zoe's nested rows must likewise keep the identity they had at
+    // index 1 now that she sits at index 0.
+    expect(keysOf(moved, 'members[0].tags')).toEqual(zoeBefore)
+  }).pipe(Effect.provide(rosterLayer)),
+)
+
+// ---------------------------------------------------------------------------
+// `setAtPath` replaces the value at a path and never touches `arrayKeys`, so the
+// keys describing the rows it just discarded stay behind. The next mutation folds
+// over that stale array, and a freshly appended row inherits the identity of a row
+// the user removed.
+// ---------------------------------------------------------------------------
+
+class SetKeysForm extends Form.make('FormsHuntSetKeysForm', { schema: RosterSchema }) {}
+
+const setKeysLayer = Form.live(SetKeysForm, {
+  initial: { members: [{ name: 'ada', tags: ['a1', 'a2', 'a3'] }] },
+}).pipe(Layer.provideMerge(Engine))
+
+it.scopedLive('replacing an array wholesale does not leave a removed rowid behind', () =>
+  Effect.gen(function* () {
+    const initial = yield* Form.view(SetKeysForm)
+    const seeded = keysOf(initial, 'members[0].tags')
+    expect(seeded.length).toBe(3)
+
+    // CONTROL — appending to the list as seeded gives the new row an identity none
+    // of the existing rows holds.
+    nestedArray(initial, 'members[0].tags').append('a4')
+    const grown = yield* waitUntil(Form.view(SetKeysForm), (view) => tagCount(view.values, 0) === 4)
+    const grownKeys = keysOf(grown, 'members[0].tags')
+    expect(grownKeys.slice(0, 3)).toEqual(seeded)
+    expect(seeded).not.toContain(grownKeys[3])
+
+    // SUBJECT — replace the whole list with one row, then append. The three keys
+    // minted for the discarded rows are still in `arrayKeys`, so the appended row
+    // reads back the key of a row that no longer exists.
+    nestedField(grown, 'members[0].tags').set(['b1'])
+    const shrunk = yield* waitUntil(
+      Form.view(SetKeysForm),
+      (view) => tagCount(view.values, 0) === 1,
+    )
+    nestedArray(shrunk, 'members[0].tags').append('b2')
+    const regrown = yield* waitUntil(
+      Form.view(SetKeysForm),
+      (view) => tagCount(view.values, 0) === 2,
+    )
+
+    const regrownKeys = keysOf(regrown, 'members[0].tags')
+    expect(regrownKeys).toHaveLength(2)
+    expect(new Set(regrownKeys).size).toBe(2)
+    expect(seeded.slice(1)).not.toContain(regrownKeys[1])
+  }).pipe(Effect.provide(setKeysLayer)),
+)

package/src/formState-reindex.test.ts

@@ -0,0 +1,198 @@
+import { expect, it } from '@effect/vitest'
+import { Effect, Exit, Layer, Option, Schema as S } from 'effect'
+import { Engine, Event } from '@playfast/reform'
+import * as Form from './form'
+import * as FormState from './formState'
+import type { FormState as FormStateShape } from './formTypes'
+import { expect as proofExpect } from '../../proof/src/assert'
+
+// Same polling idiom as form.test.ts: never wait a fixed duration, yield until the
+// condition holds.
+const waitUntil = <A, R>(
+  read: Effect.Effect<A, never, R>,
+  pred: (value: A) => boolean,
+  rounds = 100,
+): Effect.Effect<A, never, R> =>
+  Effect.flatMap(read, (value) =>
+    pred(value) || rounds <= 0
+      ? Effect.succeed(value)
+      : Effect.flatMap(Effect.yieldNow(), () => waitUntil(read, pred, rounds - 1)),
+  )
+
+const RosterSchema = S.Struct({
+  members: S.Array(S.Struct({ name: S.String, tags: S.Array(S.String) })),
+})
+
+class RosterForm extends Form.make('HuntRosterForm', { schema: RosterSchema }) {}
+
+const rosterLayer = Form.live(RosterForm, {
+  initial: {
+    members: [
+      { name: 'ada', tags: ['ada-1', 'ada-2'] },
+      { name: 'bob', tags: ['bob-1'] },
+    ],
+  },
+  validate: ({ values }) =>
+    values.members.flatMap((member, index) =>
+      member.name === 'ada' ? [Form.error(`members[${index}].name`, 'ada is blocked')] : [],
+    ),
+}).pipe(Layer.provideMerge(Engine))
+
+// ---------------------------------------------------------------------------
+// forms: per-item state is addressed by index and never re-indexed when the
+// array is spliced or reordered, so it lands on a different item.
+// ---------------------------------------------------------------------------
+
+it.scopedLive('touched does not survive its item being removed from an array', () =>
+  Effect.gen(function* () {
+    const view = yield* Form.view(RosterForm)
+    // Blur ADA's name only. Bob's name is never touched by anybody.
+    yield* Event.dispatch(RosterForm.events.blur, { path: 'members[0].name' })
+    yield* waitUntil(RosterForm.state, (state) => state.touched['members[0].name'] === true)
+
+    view.array('members').remove(0)
+    const after = yield* waitUntil(RosterForm.state, (state) => state.values.members.length === 1)
+
+    expect(after.values.members[0]?.name).toBe('bob')
+    // The only touched field belonged to the removed item, so nothing is touched.
+    // Today `members[0].name` is still flagged, and index 0 is now Bob — a row the
+    // user never visited renders as touched (and therefore as "show my errors").
+    expect(after.touched).toEqual({})
+  }).pipe(Effect.provide(rosterLayer)),
+)
+
+it.scopedLive('a field error follows its item across a reorder', () =>
+  Effect.gen(function* () {
+    const view = yield* Form.view(RosterForm)
+    view.validate()
+    const invalid = yield* waitUntil(RosterForm.state, (state) => state.validationCount > 0)
+    expect(invalid.errors).toEqual({ 'members[0].name': 'ada is blocked' })
+
+    // Move Ada (index 0) to the end; Bob becomes index 0.
+    view.array('members').move(0, 1)
+    const after = yield* waitUntil(
+      RosterForm.state,
+      (state) => state.values.members[0]?.name === 'bob',
+    )
+
+    // Whatever the fix is — re-index the error onto Ada's new path, or drop stale
+    // errors on a structural change — Bob, who is now index 0, must not be wearing
+    // Ada's error message.
+    expect(after.errors['members[0].name']).toBe(undefined)
+  }).pipe(Effect.provide(rosterLayer)),
+)
+
+it.scopedLive('stable array keys of a nested list follow their parent item', () =>
+  Effect.gen(function* () {
+    const view = yield* Form.view(RosterForm)
+    const before = yield* RosterForm.state
+    const adaKey = before.arrayKeys['members']?.[0]
+    const bobKey = before.arrayKeys['members']?.[1]
+    const adaTagKeys = before.arrayKeys['members[0].tags']
+    const bobTagKeys = before.arrayKeys['members[1].tags']
+    expect(adaTagKeys?.length).toBe(2)
+    expect(bobTagKeys?.length).toBe(1)
+
+    view.array('members').move(0, 1)
+    const after = yield* waitUntil(
+      RosterForm.state,
+      (state) => state.values.members[0]?.name === 'bob',
+    )
+
+    // The item's OWN key is re-keyed correctly by moveAtPath ...
+    expect(after.arrayKeys['members']).toEqual([bobKey, adaKey])
+    // ... but the keys of the list nested INSIDE each item are not touched, so the
+    // key list at `members[0].tags` still describes Ada while index 0 holds Bob.
+    // Independent of which fix is chosen (carry the keys along, or regenerate them),
+    // a stable-key list must hand out exactly one key per item.
+    expect(after.values.members[0]?.tags.length).toBe(1)
+    expect(after.arrayKeys['members[0].tags']?.length).toBe(1)
+    expect(after.arrayKeys['members[1].tags']?.length).toBe(2)
+  }).pipe(Effect.provide(rosterLayer)),
+)
+
+// ---------------------------------------------------------------------------
+// proof: the harness compares values by a structural fingerprint string.
+// ---------------------------------------------------------------------------
+
+it('Proof.expect().toEqual() accepts a value that repeats a reference', () => {
+  const shared = { currency: 'USD' }
+  // `{ a: shared, b: shared }` is not cyclic — it is a DAG, and it is structurally
+  // equal to the literal on the right. The fingerprint's `seen` set is never
+  // unwound, so the second occurrence collapses to `[Circular]` and the assertion
+  // dies on two values that are equal.
+  const outcome = Effect.runSyncExit(
+    proofExpect({ a: shared, b: shared }).toEqual({
+      a: { currency: 'USD' },
+      b: { currency: 'USD' },
+    }),
+  )
+  expect(Exit.isSuccess(outcome)).toBe(true)
+})
+
+it('Proof.expect().toEqual() rejects a cyclic value against an acyclic one', () => {
+  const leaf = { currency: 'USD' }
+  const acyclic: Record<string, unknown> = { a: leaf, b: leaf }
+  const cyclic: Record<string, unknown> = { a: { currency: 'USD' } }
+  cyclic['b'] = cyclic
+
+  // Both fingerprint to `{a:{...},b:[Circular]}`, so the harness reports these two
+  // very different values as equal: an assertion that passes when it should fail.
+  const outcome = Effect.runSyncExit(proofExpect(acyclic).toEqual(cyclic))
+  expect(Exit.isFailure(outcome)).toBe(true)
+})
+
+it('Proof.expect().toEqual() ignores key insertion order', () => {
+  // Props built in a different key order than the literal in the proof body are
+  // structurally identical, but the fingerprint serialises `Reflect.ownKeys` in
+  // insertion order, so the assertion dies.
+  const outcome = Effect.runSyncExit(
+    proofExpect({ total: 3, label: 'x' }).toEqual({ label: 'x', total: 3 }),
+  )
+  expect(Exit.isSuccess(outcome)).toBe(true)
+})
+
+// `moveAt` accepts `to === elements.length` — "move it to the end" — but a move keeps
+// the array's length, so the item actually lands at `length - 1`. The index map has to
+// agree with where the value went, or the row's `touched` flag and validation error are
+// parked on an index that does not exist and the next `append` inherits them.
+interface Member {
+  readonly name: string
+  readonly tags: ReadonlyArray<string>
+}
+
+it('moving an item to the end carries its metadata to the index it landed on', () => {
+  const values = {
+    members: [
+      { name: 'a', tags: [] },
+      { name: 'b', tags: [] },
+      { name: 'c', tags: [] },
+    ],
+  } satisfies { readonly members: ReadonlyArray<Member> }
+  const state: FormStateShape<{ readonly members: ReadonlyArray<Member> }> = {
+    values,
+    initialValues: values,
+    touched: { 'members[0].name': true },
+    errors: { 'members[0].name': 'first is wrong' },
+    arrayKeys: {},
+    dirtyPaths: [],
+    submitCount: 0,
+    validationCount: 0,
+    lastSubmittedValues: Option.none(),
+  }
+  const names = (moved: FormStateShape<{ readonly members: ReadonlyArray<Member> }>) =>
+    moved.values.members.map((member: Member) => member.name)
+
+  // Control: the in-range form of the same move places the metadata correctly.
+  const inRange = FormState.moveAtPath({ state, path: 'members', from: 0, to: 2 })
+  expect(names(inRange)).toEqual(['b', 'c', 'a'])
+  expect(inRange.touched['members[2].name']).toBe(true)
+  expect(inRange.errors['members[2].name']).toBe('first is wrong')
+
+  // Subject: `to === length` is the same move, so the metadata must land in the same place.
+  const toEnd = FormState.moveAtPath({ state, path: 'members', from: 0, to: 3 })
+  expect(names(toEnd)).toEqual(['b', 'c', 'a'])
+  expect(toEnd.touched['members[2].name']).toBe(true)
+  expect(toEnd.errors['members[2].name']).toBe('first is wrong')
+  expect(toEnd.touched['members[3].name']).toBeUndefined()
+})