프레임워크가 달라도 같은 폼을 관찰할 수 있는 이유
작성일:2026.10.24|수정일:2026.11.03|조회수:5

React, Vue, Solid, Svelte용 폼 API는 겉모양이 다르다. React는 훅과 Props를 돌려주고, Vue는 컴포저블과 반응형 값을 사용하며, Solid는 시그널의 생명주기를 따르고, Svelte는 액션과 스토어를 내놓는다. 이 차이만 보고 Devtools를 만들면 네 프레임워크의 상태 표현을 모두 이해하는 네 개의 구현부터 떠올리게 된다.
그런데 @ilokesto/form에서 네 어댑터가 감싸는 대상은 서로 다른 상태 모델이 아니다. 모두 코어의 Form<TValues>를 사용하고, 반환값에도 원본 form을 남긴다. Devtools가 관찰해야 할 공통점은 React 훅과 Vue ref 사이가 아니라, 그 아래에 있는 Form의 공개 계약에 있었다.
네 어댑터 아래에는 같은 Form이 있다
@ilokesto/form@2.0.1의 프레임워크별 공개 타입에서 나머지 프로퍼티를 덜어 내면 공통점이 바로 보인다. useForm()에 이미 만든 Form을 전달할 수 있고, 반환 타입은 어느 프레임워크에서나 그 인스턴스를 form으로 노출한다.
type ReactForm<TValues> = { form: Form<TValues>; // React용 hook과 submit handler};declare function useForm<TValues>( form: Form<TValues>,): ReactForm<TValues>;type VueForm<TValues> = { form: Form<TValues>; // Vue용 composable과 submit handler};declare function useForm<TValues>( form: Form<TValues>,): VueForm<TValues>;type SolidForm<TValues> = { form: Form<TValues>; // Solid용 helper와 submit handler};declare function useForm<TValues>( form: Form<TValues>,): SolidForm<TValues>;type SvelteForm<TValues> = { form: Form<TValues>; // Svelte용 action, store, submit handler};declare function useForm<TValues>( form: Form<TValues>,): SvelteForm<TValues>;위 코드는 네 공개 타입에서 form과 해당 오버로드만 남긴 축약이다. React의 useRegister()와 Svelte의 register 액션은 같은 모양일 이유가 없다. 각 어댑터는 DOM 이벤트와 렌더 생명주기를 자기 프레임워크에 맞게 번역한다. 하지만 이미 만든 Form을 받았을 때 다른 상태 객체로 바꾸지 않으며, 반환한 .form도 Form<TValues>다.
로그인 폼을 예로 들면 권위 있는 상태의 출처는 다음 객체다. 이 객체는 React 컴포넌트가 아니고 Vue의 ref도 아니다. 프레임워크 어댑터가 바인딩을 붙이기 전부터 존재하는 TypeScript 객체다.
import { CreateForm } from '@ilokesto/form';const form = new CreateForm({ defaultValues: { email: '', password: '', },});각 어댑터는 옵션을 받아 이런 Form을 만들 수도 있고, 이미 만든 form을 받을 수도 있다. “같은 Form을 공유한다”는 말은 네 애플리케이션이 반드시 하나의 인스턴스를 동시에 붙잡아야 한다는 뜻이 아니다. 프레임워크마다 별도 상태 모델을 관찰하는 것이 아니라 같은 코어 타입과 공개 API를 관찰하며, 기존 인스턴스를 넘기면 그 객체가 그대로 어댑터와 Devtools 사이를 지난다는 뜻이다.
전체 Form은 관찰자에게 너무 넓다
Form<TValues>는 읽기 전용 인터페이스가 아니다. 상태를 읽는 메서드와 변경 알림을 받는 메서드뿐 아니라 필드 등록, 값 변경, 검증, 배열 조작, 초기화, 제출까지 한 계약에 모여 있다. 공개 타입의 역할을 줄여 옮기면 다음과 같다.
export type Form<TValues> = { getState(): Readonly<FormState<TValues>>; subscribe(listener: () => void): () => void; getFieldState(path: FieldPathInput): Readonly<FieldState>; getValue(path: FieldPathInput): unknown; getValues(): TValues; registerFieldSchema( path: FieldPathInput, options: FieldSchemaOptions, ): () => void; setValue( path: FieldPathInput, value: unknown, options?: SetValueOptions, ): void; blur(path: FieldPathInput): Promise<boolean>; focus(path: FieldPathInput): void; setErrors( path: FieldPathInput, errors: readonly FormError[], ): void; clearErrors(...paths: FieldPathInput[]): void; trigger(...paths: FieldPathInput[]): Promise<boolean>; array(path: FieldPathInput): FormArray; reset(values?: TValues, options?: ResetOptions): void; submit<TResult>( onValid: (values: TValues) => TResult | Promise<TResult>, onInvalid?: ( fields: Readonly<Record<PathKey, FieldState>>, ) => void, ): Promise<TResult | undefined>;};이 계약은 폼을 사용하는 화면에는 알맞다. 입력 이벤트가 들어오면 setValue()를 호출해야 하고, 포커스와 블러를 기록하며, 제출 버튼은 검증과 submit()을 실행해야 한다. 반면 첫 버전 Devtools가 하려는 일은 현재 상태를 읽고 바뀐 시점을 알아내 화면을 다시 그리는 것뿐이다. 전체 Form을 입력 타입으로 받으면 필요하지 않은 능력까지 Devtools의 정상적인 선택지로 들어온다.
처음에는 form: Form<unknown>으로 선언해도 된다고 생각할 수 있다. 실제로 CreateForm을 전달하므로 실행 자체는 된다. 문제는 “읽기 전용 도구”라는 설명과 타입이 서로 다른 말을 하게 된다는 데 있다. 설명은 값을 바꾸지 않는다고 하지만 구현 파일에서는 setValue(), reset(), trigger(), submit()을 모두 호출할 수 있다.
필요한 세 메서드만 남긴다
실제 @ilokesto/form-devtools의 src/types.ts는 별도 상태 추상화를 만들지 않는다. 원본 Form 타입에서 세 메서드만 고른다.
import type { Form } from '@ilokesto/form';/** Devtools가 form을 읽고 변경 알림을 받는 데 필요한 최소 계약이다. */export type FormDevtoolsSource<TValues = unknown> = Pick<Form<TValues>, 'getState' | 'getValues' | 'subscribe'>;Pick을 사용한 이유는 이름을 줄이기 위해서가 아니다. getState()의 반환 타입, getValues()의 TValues, subscribe()가 반환하는 구독 해제 함수는 여전히 원본 Form<TValues>가 정한다. Devtools가 손으로 비슷한 인터페이스를 다시 선언하고 두 타입의 변화가 어긋날 가능성을 만들지 않으면서도, 소비할 수 있는 능력은 세 개로 줄인다.
이 한 줄은 구현에도 제약을 건다. IlokestoFormDevtoolsElement.form의 타입은 FormDevtoolsSource이므로 this.form.setValue(...)를 추가하면 타입 검사가 실패한다. 값을 바꾸는 기능이 정말 필요해진다면 몰래 메서드 하나를 호출하는 것으로 끝낼 수 없다. 읽기 전용이라는 제품 범위를 다시 논의하고 입력 계약을 넓혀야 한다.
세 메서드는 각각 다른 질문에 답한다.
getState()는 필드 메타데이터와 제출 상태를 포함한 현재 스냅숏을 읽는다.getValues()는 내부 필드 저장 형태가 아니라 사용자가 기대하는TValues모양의 현재 값을 읽는다.subscribe()는 상태가 바뀐 시점을 알리고, 더 이상 관찰하지 않을 때 호출할 정리 함수를 반환한다.
이 목록에는 값을 쓰는 메서드가 없고, 내부 저장소 객체를 꺼내는 메서드도 없다. 관찰자가 알아야 하는 것은 현재 무엇이 보이는지와 언제 다시 읽어야 하는지까지다.
Pick은 런타임 보안 장치가 아니다
여기서 읽기 전용이라는 말은 Devtools 구현에 허용한 TypeScript 계약을 가리킨다. 실제로 전달되는 객체가 CreateForm이라면 JavaScript 런타임에는 setValue()와 reset()이 그대로 존재한다. 타입 단언이나 any로 우회하면 호출할 수도 있다. Pick은 객체에서 프로퍼티를 삭제하지 않는다.
런타임에서도 mutation API를 물리적으로 숨겨야 한다면 세 메서드만 가진 별도 파사드 객체를 만들어 전달해야 한다. 하지만 현재 첫 버전의 목표는 신뢰할 수 없는 코드를 격리하는 것이 아니라, 패키지 내부에서 관찰과 조작의 책임을 구분하는 것이다. 그 목적에는 원본 시그니처를 보존하면서 구현의 정상 경로를 제한하는 Pick이 맞았다.
getState()의 Readonly<FormState<TValues>>도 비슷하게 해석해야 한다. TypeScript가 소비 코드의 직접 대입을 막는 표시는 되지만, 그 표기 하나가 모든 중첩 객체를 런타임에서 동결한다는 뜻은 아니다. Devtools는 받은 스냅숏을 수정하지 않고, 변경 알림이 오면 다시 읽는다. 읽기 전용이라는 판단은 타입 이름보다 실제 데이터 흐름까지 함께 봐야 한다.
상태 스냅숏과 현재 값은 같은 질문이 아니다
getState()가 반환하는 FormState<TValues>에는 defaultValues, 경로별 fields, 제출 횟수와 진행 상태, 배열 키가 들어 있다. 각 필드에는 값과 오류뿐 아니라 touched, dirty, modified, isFocused가 있다. Devtools의 Overview와 Fields 화면은 이 스냅숏을 이용해 폼이 지금 어떤 상태인지뿐 아니라 어떤 과정을 지나왔는지 보여 준다.
export type FormState<TValues> = { defaultValues: TValues; fields: Record<PathKey, FieldState>; submitCount: number; isSubmitting: boolean; isSubmitted: boolean; isSubmitSuccessful: boolean; arrayKeys: ArrayKeys;};export type FieldState<TValue = unknown> = { value: TValue; errors: FormError[]; touched: boolean; dirty: boolean; modified: boolean; isFocused: boolean;};반면 Values 화면의 “현재 제출될 값”을 만들기 위해 fields를 직접 조립하지 않는다. 필드 상태는 정규화된 경로 키로 저장되고 배열에는 렌더링 정체성을 위한 별도 키가 있다. 이 내부 표현을 Devtools가 다시 해석하면 코어의 경로 복원 규칙을 복제하게 된다. 그래서 실제 구현은 현재 값이 필요할 때 공개 메서드인 getValues()를 호출한다.
private renderValues(snapshot: FormSnapshot): TemplateResult { const values = this.form?.getValues(); return html` <section class="section"> <h3>Current values</h3> <pre>${stringify(redact(values, this.maskPaths))}</pre> </section> <section class="section"> <h3>Default values</h3> <pre>${stringify(redact(snapshot.defaultValues, this.maskPaths))}</pre> </section> <section class="section"> <h3>Array keys</h3> <pre>${stringify(snapshot.arrayKeys)}</pre> </section> `;}이 코드는 src/IlokestoFormDevtoolsElement.ts의 실제 구현이다. 현재 값은 getValues()에서, 초기값과 배열 키는 공개 스냅숏에서 읽는다. 코어가 이미 구분한 책임을 Devtools가 다시 합치거나 추측하지 않는다.
구독 알림을 받으면 다시 읽는다
subscribe()의 리스너는 스냅숏을 인자로 받지 않는다. 변경이 일어났다는 알림만 받고, 리스너가 getState()를 호출해 최신 상태를 읽는다. 따라서 Devtools는 최초 연결 때 한 번 읽고, 이후 같은 읽기 함수를 구독에 전달해야 한다.
private connectForm(): void { this.disconnectForm(); if (!this.isConnected || !this.form) { this.snapshot = undefined; return; } const form = this.form; const readSnapshot = (): void => { this.snapshot = form.getState(); }; readSnapshot(); this.unsubscribe = form.subscribe(readSnapshot);}private disconnectForm(): void { this.unsubscribe?.(); this.unsubscribe = undefined;}이 역시 실제 엘리먼트 코드다. subscribe()가 현재 상태를 즉시 보내 준다고 가정하지 않고 readSnapshot()을 먼저 호출한다. Form이 교체되거나 엘리먼트가 DOM에서 분리될 때에는 반환받은 함수를 호출해 이전 구독을 끝낸다. 프레임워크의 반응성 API를 하나로 합치지 않아도, 읽기와 알림이라는 두 동작만으로 브라우저 엘리먼트를 외부 스토어에 연결할 수 있다.
React 어댑터가 useSyncExternalStore()를 사용하고 Vue가 반응형 참조를 갱신하며 Solid가 시그널, Svelte가 readable 스토어를 사용하더라도 이 아래의 규칙은 같다. 변경을 구독하고 최신 스냅숏을 다시 읽는다. Devtools도 이 규칙을 따른다. 변경 알림을 받으면 최신 스냅숏을 다시 읽고, 그 값을 화면에 반영한다. 이때 화면을 다시 그리는 구현에는 뒤에서 살펴볼 Lit을 사용한다.
관찰자가 값을 바꾸기 시작하면 원인을 흐린다
Devtools에 mutation API가 보이면 필드 값을 고치는 버튼이나 검증을 다시 돌리는 버튼을 붙이기 쉬워진다. 그런 도구가 언제나 나쁜 것은 아니다. 다만 읽기 전용 인스펙터와 상태 조작 도구는 디버깅할 때 다른 조건을 만든다. 관찰 중인 도구가 setValue()나 reset()을 호출하면 화면에서 본 상태가 애플리케이션 때문에 만들어졌는지 Devtools가 개입해 만들어졌는지 구분해야 한다.
다음 코드는 현재 저장소의 코드가 아니라, 전체 Form을 받았을 때 경계가 어떻게 흐려질 수 있는지 보여 주는 반례다.
// 반례: 현재 구현에는 없는 mutation UIclass FormDevtoolsElement extends HTMLElement { form?: Form<unknown>; clearForDebugging() { this.form?.reset(); } revalidateForDebugging() { void this.form?.trigger(); }}전체 Form 타입이라면 이 코드는 정상적으로 타입 검사를 통과한다. 그러나 실제 FormDevtoolsSource에는 reset과 trigger가 없으므로 같은 코드를 추가할 수 없다. 현재 저장소의 src에서 사용하는 Form API도 getState, getValues, subscribe뿐이다. mutation은 테스트가 관찰할 상태를 만들 때 실제 Form에 호출할 수 있지만, Devtools 구현 자신은 호출하지 않는다. 테스트의 행위자와 제품의 행위자를 섞지 않은 것이다.
읽기 전용 범위는 안전 기능 전체를 뜻하지도 않는다. Form 값에는 비밀번호나 토큰이 들어갈 수 있으므로 표시할 때 maskPaths가 필요하고, 프로덕션 번들에서 개발 도구를 빼는 판단도 별도로 해야 한다. “상태를 바꾸지 않는다”와 “상태를 노출하지 않는다”는 다른 문제다.
사설 상태를 읽지 않아야 공개 계약이 살아남는다
CreateForm<TValues> 내부에는 상태 저장, 검증, 제출, 배열 키 생성을 맡는 협력 객체가 있다. 이 구조를 알고 있다고 해서 Devtools가 그 객체를 가져와도 되는 것은 아니다. 사설 저장소를 직접 구독하면 당장은 같은 상태를 볼 수 있을지 몰라도, Devtools는 Form<TValues>가 아니라 특정 CreateForm 구현과 그 내부 배치에 의존하게 된다.
내부 접근을 허용했을 때의 반례는 이런 모양이다. 이것도 현재 저장소에는 없는 코드다.
// 반례: 공개 계약을 건너뛰고 구현 세부사항을 추측한다.const internalStore = ( form as unknown as { store: { getState(): FormState<unknown>; subscribe(listener: () => void): () => void; }; }).store;const snapshot = internalStore.getState();const unsubscribe = internalStore.subscribe(render);이 코드는 store라는 프로퍼티 이름과 그 안의 메서드 모양을 모두 알아야 한다. 코어가 저장소를 나누거나 합치고, 검증 상태를 다른 위치로 옮기거나, CreateForm이 아닌 다른 Form<TValues> 구현을 사용하면 깨진다. 더 나쁜 점은 타입 단언이 공개 타입의 경고까지 지워 버린다는 것이다.
실제 코드는 form.getState()와 form.subscribe()를 호출한다. 값 복원도 내부 fields를 조합하지 않고 form.getValues()에 맡긴다. 코어 내부가 바뀌더라도 이 세 공개 메서드의 의미가 유지되면 Devtools는 영향을 받지 않는다. 반대로 이 계약이 바뀐다면 타입 검사에서 변화가 드러나므로 어느 경계를 다시 검토해야 하는지도 분명하다.
사설 상태에 결합하지 않는 선택은 다른 Form 구현을 지원한다는 선언이기도 하다. FormDevtoolsSource는 구조적 타입이므로 CreateForm 클래스의 인스턴스인지 검사하지 않는다. 세 메서드를 올바른 시그니처와 의미로 제공하는 객체라면 Devtools의 입력이 될 수 있다. 중요한 것은 클래스의 출신보다 관찰 계약이다.
작은 계약은 테스트 대역도 작게 만든다
실제 엘리먼트 통합 테스트는 CreateForm을 사용해 값 변경이 Fields와 Overview에 반영되는지 확인한다. 한편 특정 렌더링과 마스킹만 검증하는 테스트에서는 전체 폼과 검증 엔진을 만들 필요가 없다. 저장소의 test/element.test.ts에는 세 메서드만 구현한 소스가 있다.
function createSource( values: unknown, fields: ReturnType<FormDevtoolsSource['getState']>['fields'],): FormDevtoolsSource { const snapshot = { defaultValues: values, fields, submitCount: 0, isSubmitting: false, isSubmitted: false, isSubmitSuccessful: false, arrayKeys: {}, }; return { getState: () => snapshot, getValues: () => values, subscribe: () => () => undefined, };}계약을 전체 Form으로 두었다면 이 테스트 대역은 사용하지 않는 setValue, reset, trigger, submit까지 채워야 한다. 빈 함수로 메우면 테스트가 요구하지 않는 능력이 있는 척하게 되고, 실제 구현을 가져오면 렌더링 테스트의 준비 범위가 커진다. 세 메서드 계약은 테스트가 통제해야 할 상태와 알림만 남긴다.
물론 작은 대역도 실제 의미를 지켜야 한다. 상태 갱신을 검사하는 테스트라면 subscribe()가 리스너를 저장하고 정리 함수가 이를 제거하도록 만들어야 한다. 메서드 수를 줄였다고 계약의 동작까지 대충 흉내 내도 된다는 뜻은 아니다.
프레임워크 독립성보다 먼저 정한 것
React, Vue, Solid, Svelte를 모두 지원한다고 해서 네 반응성 모델을 하나로 합치는 새 추상화가 필요한 것은 아니었다. 네 어댑터는 이미 같은 Form<TValues>를 공개하고 있었다. Devtools는 getState()로 스냅숏을 읽고, getValues()로 현재 값을 얻으며, subscribe()로 다시 읽어야 할 시점을 알면 됐다. 프레임워크와 무관한 UI의 출발점은 특정 UI 기술이 아니라 이 작은 관찰 계약이었다.
전체 Form을 받지 않으면서 mutation API는 관찰자의 책임 밖으로 밀려났다. 사설 저장소에 접근하지 않으면서 Devtools는 특정 구현 클래스의 내부 배치가 아니라 세 공개 메서드에만 의존하게 됐다. 프레임워크 독립성은 여러 환경을 모두 아는 데서 나오지 않았다. 환경이 달라도 유지되는 계약을 어디까지 줄일 수 있는지가 더 중요했다. 이제 남은 문제는 이 계약을 브라우저 엘리먼트에 전달하고, Form 교체와 DOM 연결·해제에 맞춰 구독을 관리하는 일이다.
댓글
댓글을 불러오는 중...