sh-ui-cli 0.112.0 → 0.114.0

package/data/changelog/versions.json

@@ -2,6 +2,31 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$description": "sh-ui 릴리즈 노트 단일 소스. docs(React)와 showcase(Flutter)가 함께 읽는다. 새 릴리즈마다 맨 앞에 추가.",
   "versions": [
+    {
+      "version": "0.114.0",
+      "date": "2026-05-27",
+      "title": "form — render prop 통일 + useReactHookFormAdapter hook + onChange chain merge",
+      "type": "minor",
+      "highlights": [
+        "**`<Form.Field>` render prop 패턴** — children 을 함수로 받으면 `field` API 객체를 노출 (TanStack Form / RHF Controller 와 같은 idiom). `field.value` 읽고 `field.handleChange(next)` / `field.handleBlur()` 호출 — 이전 cloneElement 의 함정 (자식 onChange 무시, `Children.only` 제한, `valueAs` enum 한계) 가 사라진다. input/select/checkbox/custom 컴포넌트가 같은 패턴으로 결선되어 학습 비용 1. `field` 객체: `value`, `errors`, `error`, `hasError`, `touched`, `isValidating`, `handleChange(next)`, `handleBlur()`, `name`, `id`, `ariaInvalid`, `ariaDescribedBy`, `disabled`, `readOnly`, `required`. 함수가 아닌 children 경로는 기존 div wrap + Form.Control 흐름 그대로 유지.",
+        "**`useReactHookFormAdapter` hook 신규** (form-rhf) — 기존 `adaptReactHookForm` 함수가 매 렌더 새 store 인스턴스를 만들던 함정 회피. `useRef` 로 mount 시점에 한 번만 어댑터 생성. 큰 폼에서 register/unregister storm + 잠재 race 가 사라진다. 일반 사용은 hook 변종, 저레벨 함수는 그대로 export.",
+        "**`Form.Control` onChange/onBlur chain merge** — 이전엔 cloneElement 가 자식의 기존 `onChange`/`onBlur` 를 silent override. v0.114 부터 store sync 와 자식 핸들러 둘 다 호출. 단 신규 코드는 render prop 권장 — Form.Control 은 한 메이저 release 뒤 제거 예정 (deprecated 마킹).",
+        "**`useShUiForm` jsdoc 명시** — options 가 첫 마운트에만 캡처된다는 점, dynamic schema 가 필요하면 Form 자체를 key 로 리마운트하라는 안내. RHF 사용 시엔 `useReactHookFormAdapter` 가 더 적합하다는 cross-reference."
+      ],
+      "url": "https://github.com/sanghyeonKim0201/sh-ui/releases/tag/v0.114.0"
+    },
+    {
+      "version": "0.113.0",
+      "date": "2026-05-26",
+      "title": "components — Separator label 슬롯 + align",
+      "type": "minor",
+      "highlights": [
+        "**`Separator` 라벨 슬롯 신규** — `<Separator />` 는 기존처럼 가로/세로 1px 선이지만, `<Separator>섹션 라벨</Separator>` 처럼 children 을 넘기면 가운데 라벨이 있는 `──── label ────` 형식으로 렌더. 라벨이 있을 땐 horizontal 로 강제되고 `align` prop(`start`/`center`/`end`) 으로 라벨 위치를 정한다. 기존 사용처는 그대로 — children 없는 호출은 동작 변화 없음.",
+        "**디자인 토큰 활용** — 선 색은 `--border`, 라벨은 `--foreground-subtle` + uppercase + tracking-wide 가 기본. 시안 빈도 높은 \"섹션 라벨 양옆 1px 선\" 패턴 (login OAuth 구분, 워크스페이스 스위처 invite 섹션 등) 을 1줄로 줄여준다. `className` 으로 라벨 컨테이너의 typography·spacing 도 override 가능.",
+        "**Tailwind / CSS Modules / plain CSS 세 변종 모두 갱신** — 라벨이 있을 때만 `flex items-center gap` 컨테이너로 전환되고 plain 변종은 컨테이너 자체에 background 를 두지 않아 visual side effect 없음."
+      ],
+      "url": "https://github.com/sanghyeonKim0201/sh-ui/releases/tag/v0.113.0"
+    },
     {
       "version": "0.112.0",
       "date": "2026-05-22",

package/data/registry/react/components/form/field.test.tsx

@@ -1,4 +1,4 @@
-import { describe, it, expect } from "vitest";
+import { describe, it, expect, vi } from "vitest";
 import { render, screen } from "@testing-library/react";
 import userEvent from "@testing-library/user-event";
 import * as React from "react";
@@ -228,3 +228,108 @@ describe("validateOn blur → change on error", () => {
     expect(screen.queryByText("bad")).not.toBeInTheDocument();
   });
 });
+
+// ─────────────────────────────────────────────
+// Render prop (function-as-child) — v0.114+
+// ─────────────────────────────────────────────
+describe("Form.Field render prop", () => {
+  it("passes field API to function children + wires handleChange", async () => {
+    const user = userEvent.setup();
+    let receivedField: any = null;
+
+    render(
+      <Form>
+        <Field name="email">
+          {(field) => {
+            receivedField = field;
+            return (
+              <input
+                data-testid="i"
+                value={(field.value as string) ?? ""}
+                onChange={(e) => field.handleChange(e.target.value)}
+                onBlur={field.handleBlur}
+              />
+            );
+          }}
+        </Field>
+      </Form>
+    );
+
+    expect(receivedField).toBeTruthy();
+    expect(receivedField.name).toBe("email");
+    expect(typeof receivedField.handleChange).toBe("function");
+    expect(typeof receivedField.handleBlur).toBe("function");
+
+    const input = screen.getByTestId("i") as HTMLInputElement;
+    await user.type(input, "kim@studio");
+    expect(input.value).toBe("kim@studio");
+  });
+
+  it("ariaInvalid + ariaDescribedBy reflect error state", async () => {
+    const user = userEvent.setup();
+
+    render(
+      <Form>
+        <Field name="email" validate={(v) => (String(v).includes("@") ? undefined : "bad")}>
+          {(field) => (
+            <>
+              <input
+                data-testid="i"
+                value={(field.value as string) ?? ""}
+                onChange={(e) => field.handleChange(e.target.value)}
+                onBlur={field.handleBlur}
+                aria-invalid={field.ariaInvalid}
+                aria-describedby={field.ariaDescribedBy}
+              />
+              <FormError />
+            </>
+          )}
+        </Field>
+      </Form>
+    );
+
+    const input = screen.getByTestId("i") as HTMLInputElement;
+    await user.type(input, "abc");
+    input.blur();
+    await screen.findByText("bad");
+    expect(input.getAttribute("aria-invalid")).toBe("true");
+    expect(input.getAttribute("aria-describedby")).toContain("error");
+  });
+
+  it("does not wrap in sh-ui-form-field div when using render prop", () => {
+    const { container } = render(
+      <Form>
+        <Field name="email">
+          {() => <input data-testid="i" />}
+        </Field>
+      </Form>
+    );
+    expect(container.querySelector(".sh-ui-form-field")).toBeNull();
+  });
+});
+
+// ─────────────────────────────────────────────
+// Form.Control — chain merge (v0.114+: 자식 onChange 보존)
+// ─────────────────────────────────────────────
+describe("Form.Control chain merge", () => {
+  it("preserves child onChange while syncing store", async () => {
+    const user = userEvent.setup();
+    const childOnChange = vi.fn();
+
+    render(
+      <Form>
+        <Field name="email">
+          <FormControl>
+            <input data-testid="i" onChange={childOnChange} />
+          </FormControl>
+        </Field>
+      </Form>
+    );
+
+    const input = screen.getByTestId("i") as HTMLInputElement;
+    await user.type(input, "x");
+    expect(childOnChange).toHaveBeenCalled();
+    // store sync 도 작동 (입력값이 input 에 반영)
+    expect(input.value).toBe("x");
+  });
+});

package/data/registry/react/components/form/field.tsx

@@ -10,9 +10,51 @@ import {
   DisabledContext,
   useFormField,
 } from "./context";
-import type { FieldValidate, ValidateOn } from "./types";
+import type { FieldError, FieldValidate, ValidateOn } from "./types";
 import { scopedPath } from "./utils";
 
+// ─────────────────────────────────────────────
+// FieldRenderProps — render prop 으로 노출되는 필드 API
+// ─────────────────────────────────────────────
+
+/**
+ * <Form.Field name="x">{(field) => ...}</Form.Field> 의 `field` 객체.
+ *
+ * 값/상태 + 액션 + a11y 메타. 사용자는 `field.value` 읽고
+ * `field.handleChange(next)` / `field.handleBlur()` 호출, 필요하면
+ * `field.id` / `field.name` / `field.ariaInvalid` / `field.ariaDescribedBy`
+ * 를 자체 input element 에 spread.
+ *
+ * `handleChange` 는 **next value 자체** 를 받는다 (event 객체 아님) — input,
+ * select, checkbox, custom (color picker · emoji picker 등) 모두 같은 시그니처.
+ * input 의 경우 사용자가 `onChange={(e) => field.handleChange(e.target.value)}`
+ * 로 wire.
+ */
+export interface FieldRenderProps {
+  // ── 값/상태 ──────────────────────────────
+  value: unknown;
+  errors: FieldError[];
+  /** 첫 에러 (편의). 여러 에러면 errors 배열을 직접 사용. */
+  error: FieldError | undefined;
+  hasError: boolean;
+  touched: boolean;
+  isValidating: boolean;
+
+  // ── 액션 ────────────────────────────────
+  /** next value 자체를 받는다. event 객체 아님. */
+  handleChange: (next: unknown) => void;
+  handleBlur: () => void;
+
+  // ── a11y / DOM 메타 ──────────────────────
+  name: string;
+  id: string;
+  ariaInvalid: true | undefined;
+  ariaDescribedBy: string | undefined;
+  disabled: boolean | undefined;
+  readOnly: boolean | undefined;
+  required: boolean | undefined;
+}
+
 // ─────────────────────────────────────────────
 // Field
 // ─────────────────────────────────────────────
@@ -25,7 +67,15 @@ export interface FieldProps
   required?: boolean;
   disabled?: boolean;
   readOnly?: boolean;
-  children?: React.ReactNode;
+  /**
+   * children. 함수면 render prop 으로 호출되어 `field` API 노출 (TanStack /
+   * RHF Controller 와 같은 패턴). 함수가 아니면 일반 children 으로 렌더 +
+   * div wrap.
+   *
+   * 권장: render prop 통일 — 입력 종류 무관 동일 패턴.
+   * 단순 input 한 칸도 `{(field) => <Input value={field.value} ... />}` 로.
+   */
+  children?: React.ReactNode | ((field: FieldRenderProps) => React.ReactNode);
 }
 
 export function Field({
@@ -59,23 +109,41 @@ export function Field({
       sectionPath: section.path || undefined,
       required,
     });
-  // eslint-disable-next-line react-hooks/exhaustive-deps
+    // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [store, path]);
 
   const effectiveDisabled = disabled || formDisabled;
 
+  const ctxValue = React.useMemo(
+    () => ({
+      path,
+      id,
+      descId,
+      errorId,
+      disabled: effectiveDisabled,
+      readOnly,
+      required,
+    }),
+    [path, id, descId, errorId, effectiveDisabled, readOnly, required]
+  );
+
+  // children 이 함수면 render prop 패턴 — FieldContext 만 제공하고 wrap 없음.
+  // 사용자가 JSX 모양 (label/input/error 배치, wrapper 등) 을 100% 결정.
+  if (typeof children === "function") {
+    return (
+      <FieldContext.Provider value={ctxValue}>
+        <FieldRenderBridge>
+          {(field) =>
+            (children as (f: FieldRenderProps) => React.ReactNode)(field)
+          }
+        </FieldRenderBridge>
+      </FieldContext.Provider>
+    );
+  }
+
+  // 일반 children — 기존 div wrap (cloneElement 기반 Form.Control 경로용).
   return (
-    <FieldContext.Provider
-      value={{
-        path,
-        id,
-        descId,
-        errorId,
-        disabled: effectiveDisabled,
-        readOnly,
-        required,
-      }}
-    >
+    <FieldContext.Provider value={ctxValue}>
       <div
         className={`sh-ui-form-field${className ? ` ${className}` : ""}`}
         data-disabled={effectiveDisabled || undefined}
@@ -88,6 +156,51 @@ export function Field({
   );
 }
 
+// Render prop bridge — FieldContext 안에서 store/field state 를 읽어 `field`
+// 객체 구성. 별도 컴포넌트로 분리하는 이유: store subscribe 가 hook 이라
+// Field 본체에서 conditional 호출 불가 (Rules of Hooks).
+function FieldRenderBridge({
+  children,
+}: {
+  children: (field: FieldRenderProps) => React.ReactNode;
+}) {
+  const ctx = React.useContext(FieldContext);
+  if (!ctx) return null;
+  const store = React.useContext(FormContext)!;
+  const state = useFormField(ctx.path);
+
+  const describedBy =
+    cn(ctx.descId, state.hasError ? ctx.errorId : null) || undefined;
+
+  const field: FieldRenderProps = {
+    value: state.value,
+    errors: state.errors,
+    error: state.error,
+    hasError: state.hasError,
+    touched: state.touched,
+    isValidating: state.isValidating,
+    handleChange: (next) => {
+      store.setFieldValue(ctx.path, next);
+      if (store.getState().revalidateOnChange.has(ctx.path)) {
+        void store.validateField(ctx.path);
+      }
+    },
+    handleBlur: () => {
+      store.setFieldTouched(ctx.path, true);
+      void store.validateField(ctx.path);
+    },
+    name: ctx.path,
+    id: ctx.id,
+    ariaInvalid: state.hasError ? true : undefined,
+    ariaDescribedBy: describedBy,
+    disabled: ctx.disabled,
+    readOnly: ctx.readOnly,
+    required: ctx.required,
+  };
+
+  return <>{children(field)}</>;
+}
+
 // ─────────────────────────────────────────────
 // Label
 // ─────────────────────────────────────────────
@@ -161,7 +274,7 @@ export function FormError({
 }
 
 // ─────────────────────────────────────────────
-// Control
+// Control (DEPRECATED — render prop 사용 권장)
 // ─────────────────────────────────────────────
 
 export interface ControlProps {
@@ -169,7 +282,9 @@ export interface ControlProps {
   name: string;
   value?: unknown;
   checked?: boolean;
-  onChange: (e: React.ChangeEvent<HTMLInputElement | HTMLTextAreaElement | HTMLSelectElement>) => void;
+  onChange: (
+    e: React.ChangeEvent<HTMLInputElement | HTMLTextAreaElement | HTMLSelectElement>
+  ) => void;
   onBlur: () => void;
   "aria-invalid"?: true;
   "aria-describedby"?: string;
@@ -185,6 +300,24 @@ export interface FormControlProps {
   render?: (ctrl: ControlProps) => React.ReactElement;
 }
 
+/**
+ * @deprecated v0.114+ 부터는 `<Form.Field>` 의 render prop 패턴을 권장한다.
+ *
+ *   // 권장 (TanStack / RHF Controller 와 같은 idiom):
+ *   <Form.Field name="email">
+ *     {(field) => (
+ *       <Input
+ *         value={field.value as string}
+ *         onChange={(e) => field.handleChange(e.target.value)}
+ *         onBlur={field.handleBlur}
+ *       />
+ *     )}
+ *   </Form.Field>
+ *
+ * 본 Form.Control 은 cloneElement 패턴 잔존성 호환 — 자식 1개 제한, custom
+ * value (event 객체 외) 미지원, 자식의 기존 onChange/onBlur 가 chain merge
+ * 됨 (이전엔 override). 한 메이저 release 뒤 제거 예정.
+ */
 export function FormControl({
   children,
   valueAs = "value",
@@ -198,7 +331,7 @@ export function FormControl({
   const describedBy =
     cn(ctx.descId, field.hasError ? ctx.errorId : null) || undefined;
 
-  const ctrl: ControlProps = {
+  const baseCtrl: ControlProps = {
     id: ctx.id,
     name: ctx.path,
     onChange: (e) => {
@@ -219,17 +352,40 @@ export function FormControl({
     required: ctx.required,
   };
 
-  if (field.hasError) ctrl["aria-invalid"] = true;
-  if (ctx.required) ctrl["aria-required"] = true;
+  if (field.hasError) baseCtrl["aria-invalid"] = true;
+  if (ctx.required) baseCtrl["aria-required"] = true;
 
   if (valueAs === "checked") {
-    ctrl.checked = Boolean(field.value);
+    baseCtrl.checked = Boolean(field.value);
   } else {
-    ctrl.value = field.value ?? "";
+    baseCtrl.value = field.value ?? "";
   }
 
-  if (render) return render(ctrl);
+  if (render) return render(baseCtrl);
   if (!children) return null;
   const child = React.Children.only(children);
-  return React.cloneElement(child, ctrl as unknown as Record<string, unknown>);
+
+  // chain merge — 자식의 기존 onChange/onBlur 가 있으면 store sync 와 함께
+  // 둘 다 호출 (이전 버전의 silent override 함정 fix).
+  const childProps = (child.props ?? {}) as Partial<ControlProps> & {
+    onChange?: ControlProps["onChange"];
+    onBlur?: ControlProps["onBlur"];
+  };
+
+  const mergedCtrl: ControlProps = {
+    ...baseCtrl,
+    onChange: (e) => {
+      baseCtrl.onChange(e);
+      childProps.onChange?.(e);
+    },
+    onBlur: () => {
+      baseCtrl.onBlur();
+      childProps.onBlur?.();
+    },
+  };
+
+  return React.cloneElement(
+    child,
+    mergedCtrl as unknown as Record<string, unknown>
+  );
 }

package/data/registry/react/components/form/use-sh-ui-form.ts

@@ -4,6 +4,20 @@ import * as React from "react";
 import { createFormStore, type CreateFormStoreOptions } from "./store";
 import type { FormStore } from "./types";
 
+/**
+ * useShUiForm — sh-ui 자체 store 를 mount 시점에 한 번만 생성 (RHF 안 쓸 때).
+ *
+ * **중요**: `options` 는 **첫 마운트 시점에만 캡처** 된다. 매 렌더 다른
+ * `schema` / `defaultValues` / `onSubmit` 을 넘겨도 무시. 동적으로 schema 가
+ * 바뀌어야 하면:
+ *  - i18n 메시지: schema 를 useMemo 로 메모 + locale 변경 시 Form 자체를
+ *    `key` prop 으로 리마운트
+ *  - 또는 `<Form schema={...}>` prop 으로 — Form 컴포넌트가 매 렌더 prop 으로
+ *    읽음 (단 이 경로도 첫 schema 만 사용한다는 점 동일)
+ *
+ * RHF 와 함께 쓸 때는 본 hook 대신 `useReactHookFormAdapter(rhf)` 를
+ * `form-rhf` 패키지에서 import.
+ */
 export function useShUiForm<T = unknown>(
   options?: CreateFormStoreOptions<T>
 ): FormStore<T> {

package/data/registry/react/components/form-rhf/README.md

@@ -9,19 +9,149 @@ npm i react-hook-form
 sh-ui add form-rhf
 ```
 
-## 사용
+## 사용 — `useReactHookFormAdapter` (권장)
 
 ```tsx
 import { useForm } from "react-hook-form";
-import { adaptReactHookForm } from "@/components/ui/form-rhf";
+import { zodResolver } from "@hookform/resolvers/zod";
+import { z } from "zod";
+import { useReactHookFormAdapter } from "@/components/ui/form-rhf";
 import { Form } from "@/components/ui/form";
+import { Input } from "@/components/ui/input";
 
-const rhf = useForm({ defaultValues, mode: "onBlur" });
-const form = adaptReactHookForm(rhf);
+const schema = z.object({
+  email: z.string().email("이메일 형식이 아닙니다"),
+  name: z.string().min(1, "이름을 입력하세요"),
+});
+type Values = z.infer<typeof schema>;
 
-<Form form={form}>
-  <Form.Field name="email">...</Form.Field>
-</Form>
+function MyForm() {
+  const rhf = useForm<Values>({
+    resolver: zodResolver(schema),
+    defaultValues: { email: "", name: "" },
+    mode: "onBlur",
+  });
+  const form = useReactHookFormAdapter<Values>(rhf);
+
+  return (
+    <Form form={form} onSubmit={(values) => console.log(values)}>
+      <Form.Field name="email">
+        {(field) => (
+          <>
+            <Form.Label>이메일</Form.Label>
+            <Input
+              id={field.id}
+              name={field.name}
+              type="email"
+              value={field.value as string}
+              onChange={(e) => field.handleChange(e.target.value)}
+              onBlur={field.handleBlur}
+              aria-invalid={field.ariaInvalid}
+              aria-describedby={field.ariaDescribedBy}
+            />
+            <Form.Error />
+          </>
+        )}
+      </Form.Field>
+
+      <Form.Field name="name">
+        {(field) => (
+          <>
+            <Form.Label>이름</Form.Label>
+            <Input
+              id={field.id}
+              name={field.name}
+              value={field.value as string}
+              onChange={(e) => field.handleChange(e.target.value)}
+              onBlur={field.handleBlur}
+            />
+            <Form.Error />
+          </>
+        )}
+      </Form.Field>
+
+      <button type="submit">제출</button>
+    </Form>
+  );
+}
+```
+
+## API
+
+### `useReactHookFormAdapter<T>(rhf, config?)` (v0.114+)
+
+Hook 변종. **`useRef` 로 어댑터 인스턴스를 mount 시점에 안정화** — 매 렌더 새
+store 함정 회피.
+
+### `adaptReactHookForm<T>(rhf, config?)` (저레벨)
+
+순수 함수. 호출자가 `useMemo` 등으로 직접 안정화 책임. **일반 사용에선 hook
+변종을 권장.**
+
+## 패턴
+
+### 권장 — render prop (`<Form.Field>{(field) => ...}</Form.Field>`)
+
+`field` 객체:
+
+| key | 설명 |
+|---|---|
+| `value` | 현재 값 |
+| `errors` / `error` / `hasError` | 검증 에러 (배열 / 첫 에러 / boolean) |
+| `touched` / `isValidating` | 상태 |
+| `handleChange(next)` | **next value 자체** 받음 (event 아님) — input/select/checkbox/custom 통일 |
+| `handleBlur()` | blur 처리 + 검증 트리거 |
+| `name` / `id` | path / element id |
+| `ariaInvalid` / `ariaDescribedBy` / `disabled` / `readOnly` / `required` | a11y · DOM 메타 |
+
+### 다른 입력 종류
+
+```tsx
+{/* Checkbox */}
+<Form.Field name="agreed">
+  {(field) => (
+    <Checkbox
+      checked={field.value as boolean}
+      onCheckedChange={(v) => field.handleChange(v === true)}
+    />
+  )}
+</Form.Field>
+
+{/* Select */}
+<Form.Field name="role">
+  {(field) => (
+    <Select
+      value={field.value as string}
+      onValueChange={(v) => field.handleChange(v ?? "")}
+    >
+      ...
+    </Select>
+  )}
+</Form.Field>
+
+{/* Custom (직접 만든 입력) */}
+<Form.Field name="emoji">
+  {(field) => (
+    <EmojiPicker
+      value={field.value as string}
+      onChange={field.handleChange}
+    />
+  )}
+</Form.Field>
+```
+
+### Legacy — `Form.Control` (v0.114 deprecated)
+
+cloneElement 기반의 단순 케이스 helper. 자식 1개 제한, custom value 미지원,
+한 메이저 release 뒤 제거 예정. 신규 코드는 render prop 사용.
+
+```tsx
+<Form.Field name="email">
+  <Form.Label>이메일</Form.Label>
+  <Form.Control><Input /></Form.Control>  {/* deprecated */}
+  <Form.Error />
+</Form.Field>
 ```
 
-어댑터 모드에선 sh-ui 의 `validateOn` / `schema` prop 은 무시된다. 검증 규칙은 RHF 쪽 `resolver`/`register` 옵션에 둔다.
+검증 규칙은 RHF 쪽 `resolver` 에서 일괄 관리. sh-ui 의 `schema` / `validateOn`
+prop 은 어댑터 모드에서 무시된다.

package/data/registry/react/components/form-rhf/index.tsx

@@ -1,3 +1,6 @@
+"use client";
+
+import * as React from "react";
 import type { UseFormReturn, FieldValues } from "react-hook-form";
 import type {
   FormStore,
@@ -287,3 +290,75 @@ export function adaptReactHookForm<T extends FieldValues>(
 
   return store;
 }
+
+/**
+ * useReactHookFormAdapter — `adaptReactHookForm` 의 hook 변종.
+ *
+ * 어댑터는 호출마다 새 `FormStore` 인스턴스 (listeners Set, snapshot cache 등)
+ * 를 만들기 때문에, 컴포넌트 body 에서 직접 호출하면 매 렌더 새 store →
+ * `<Form form={...}>` 의 context value 가 매 렌더 바뀜 → 자식
+ * `<Form.Field>` 가 매번 register/unregister → perf hit + 잠재 race.
+ *
+ * 본 hook 은 `useRef` 로 첫 마운트에 한 번만 어댑터를 생성해 안정화한다.
+ * RHF 인스턴스 (`rhf`) 자체가 `useForm` 결과라 mount 후 안정 → ref 도 안전.
+ *
+ *   const rhf = useForm<FormValues>({ resolver: zodResolver(schema) });
+ *   const form = useReactHookFormAdapter<FormValues>(rhf);
+ *
+ *   return <Form form={form}>...</Form>;
+ *
+ * `config` 의 onSubmit 은 초기 캡처 — 매 렌더 다른 함수 넘기면 무시. 동적
+ * 콜백이 필요하면 `<Form onSubmit={...}>` prop 으로 (Form 컴포넌트가 매
+ * 렌더 capture).
+ */
+export function useReactHookFormAdapter<T extends FieldValues>(
+  rhf: UseFormReturn<T>,
+  config: AdapterConfig<T> = {}
+): FormStore<T> {
+  // 1) adapter 인스턴스 안정화 (mount 시 한 번 생성).
+  const ref = React.useRef<FormStore<T> | null>(null);
+  if (!ref.current) {
+    ref.current = adaptReactHookForm<T>(rhf, config);
+  }
+
+  // 2) RHF 의 form state 변경을 React render path 에 명시적으로 결선.
+  //
+  // 어댑터 내부의 `rhf.subscribe` 만으로는 React `useSyncExternalStore` 의
+  // listener 가 useFormField 에서 호출되긴 하지만, **자식 컴포넌트 (Field /
+  // FieldRenderBridge)** 가 부모로부터 props · context 변경 신호를 못 받아
+  // 재렌더 안 되는 케이스가 있다 (특히 어댑터를 useRef 로 안정화한 경우
+  // FormContext value 가 동일 reference 라 React 가 sub-tree 를 skip).
+  //
+  // 본 컴포넌트에서 useReducer 로 force update 를 발화해 트리 전체가 재평가
+  // 되게 한다 — `rhf.watch(...)` 같은 hook 을 외부에서 쓰는 부담을 hook 자체에
+  // 흡수.
+  const [, forceUpdate] = React.useReducer((x: number) => x + 1, 0);
+  React.useEffect(() => {
+    if (typeof (rhf as unknown as { subscribe?: unknown }).subscribe !== "function") {
+      return;
+    }
+    let unsub: (() => void) | undefined;
+    try {
+      unsub = (rhf as unknown as {
+        subscribe: (opts: {
+          formState: Record<string, boolean>;
+          callback: () => void;
+        }) => () => void;
+      }).subscribe({
+        formState: { values: true, errors: true, isSubmitting: true, touchedFields: true },
+        callback: () => forceUpdate(),
+      });
+    } catch {
+      // 구버전 RHF (< 7.50) 의 subscribe 미지원 — fallback 없음.
+    }
+    return () => {
+      try {
+        unsub?.();
+      } catch {
+        // ignore
+      }
+    };
+  }, [rhf]);
+
+  return ref.current;
+}