sh-ui-cli 0.113.0 → 0.114.0

package/data/changelog/versions.json

@@ -2,6 +2,19 @@
   "$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",

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;
+}

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

@@ -6,7 +6,7 @@ import { useForm } from "react-hook-form";
 import { Form } from "../form";
 import { Field } from "../form/field";
 import { FormControl, FormError } from "../form/field";
-import { adaptReactHookForm } from "./index";
+import { adaptReactHookForm, useReactHookFormAdapter } from "./index";
 
 function TestForm() {
   const rhf = useForm({ defaultValues: { email: "" }, mode: "onBlur" });
@@ -40,3 +40,55 @@ describe("adaptReactHookForm", () => {
     await screen.findByText("bad");
   });
 });
+
+// ─────────────────────────────────────────────
+// useReactHookFormAdapter — v0.114+ (안정화 hook)
+// ─────────────────────────────────────────────
+describe("useReactHookFormAdapter", () => {
+  it("returns same store instance across re-renders", () => {
+    const stores: any[] = [];
+    function Probe() {
+      const rhf = useForm({ defaultValues: { x: "" } });
+      const form = useReactHookFormAdapter(rhf);
+      stores.push(form);
+      const [, force] = React.useReducer((s: number) => s + 1, 0);
+      return <button onClick={force as any} data-testid="rerender">rerender</button>;
+    }
+    const { getByTestId } = render(<Probe />);
+    // 강제 re-render 3회
+    for (let i = 0; i < 3; i++) {
+      getByTestId("rerender").click();
+    }
+    // 최초 + re-render 들 모두 같은 인스턴스
+    expect(stores.length).toBeGreaterThanOrEqual(2);
+    for (const s of stores) {
+      expect(s).toBe(stores[0]);
+    }
+  });
+
+  it("works with render prop and propagates value through RHF", async () => {
+    const user = userEvent.setup();
+    function HookForm() {
+      const rhf = useForm({ defaultValues: { email: "" }, mode: "onBlur" });
+      const form = useReactHookFormAdapter(rhf);
+      return (
+        <Form form={form}>
+          <Field name="email">
+            {(field) => (
+              <input
+                data-testid="i"
+                value={(field.value as string) ?? ""}
+                onChange={(e) => field.handleChange(e.target.value)}
+                onBlur={field.handleBlur}
+              />
+            )}
+          </Field>
+        </Form>
+      );
+    }
+    render(<HookForm />);
+    const input = screen.getByTestId("i") as HTMLInputElement;
+    await user.type(input, "kim@studio");
+    expect(input.value).toBe("kim@studio");
+  });
+});

package/data/registry/react/components/label/index.tailwind.tsx

@@ -17,7 +17,11 @@ export const Label = React.forwardRef<HTMLLabelElement, LabelProps>(
     <label
       ref={ref}
       className={cn(
-        "flex flex-col gap-0.5 text-[length:var(--text-sm)] font-medium leading-snug text-foreground cursor-pointer select-none not-has-[[data-sh-ui-label-part]]:block",
+        // 기본 — typography + 인터랙션만. display 는 label 의 native(inline) 유지.
+        // sub-part(LabelTitle/Subtitle/Description/Caption) 가 자식에 있을 때만
+        // 자동으로 flex-col stack — 사용자가 가로 정렬(inline-flex items-center)
+        // 을 명시할 수 있도록 기본 display 를 강제하지 않는다.
+        "text-[length:var(--text-sm)] font-medium leading-snug text-foreground cursor-pointer select-none has-[[data-sh-ui-label-part]]:flex has-[[data-sh-ui-label-part]]:flex-col has-[[data-sh-ui-label-part]]:gap-0.5",
         // 필수 표시 — title 이 있으면 title 뒤, 없으면 label 뒤에 * 부착
         isRequired &&
           "has-[[data-sh-ui-label-part='title']]:[&>[data-sh-ui-label-part='title']]:after:content-['_*'] has-[[data-sh-ui-label-part='title']]:[&>[data-sh-ui-label-part='title']]:after:text-danger has-[[data-sh-ui-label-part='title']]:[&>[data-sh-ui-label-part='title']]:after:font-semibold not-has-[[data-sh-ui-label-part='title']]:after:content-['_*'] not-has-[[data-sh-ui-label-part='title']]:after:text-danger not-has-[[data-sh-ui-label-part='title']]:after:font-semibold",

package/data/registry/react/components/label/styles.css

@@ -1,7 +1,6 @@
+/* 기본 — typography + 인터랙션만. display 는 label 의 native (inline) 유지.
+   사용자가 `inline-flex items-center gap-2` 같이 가로 정렬을 명시할 수 있다. */
 .sh-ui-label {
-  display: flex;
-  flex-direction: column;
-  gap: 0.125rem;
   font-size: var(--text-sm);
   font-weight: var(--weight-medium);
   line-height: 1.4;
@@ -10,8 +9,13 @@
   user-select: none;
 }
 
-.sh-ui-label:not(:has(.sh-ui-label__title, .sh-ui-label__subtitle, .sh-ui-label__description, .sh-ui-label__caption)) {
-  display: block;
+/* sub-part (Title/Subtitle/Description/Caption) 가 자식에 있을 때만 세로 stack.
+   사용자가 `<Label><LabelTitle .../><LabelDescription .../></Label>` 형태로
+   쓸 때 자동으로 정렬. */
+.sh-ui-label:has(.sh-ui-label__title, .sh-ui-label__subtitle, .sh-ui-label__description, .sh-ui-label__caption) {
+  display: flex;
+  flex-direction: column;
+  gap: 0.125rem;
 }
 
 /* ───── 텍스트 계층 ───── */

package/data/registry/react/components/label/styles.module.css

@@ -1,7 +1,6 @@
+/* 기본 — typography + 인터랙션만. display 는 label 의 native (inline) 유지.
+   사용자가 `inline-flex items-center gap-2` 같이 가로 정렬을 명시할 수 있다. */
 .label {
-  display: flex;
-  flex-direction: column;
-  gap: 0.125rem;
   font-size: var(--text-sm);
   font-weight: var(--weight-medium);
   line-height: 1.4;
@@ -10,8 +9,11 @@
   user-select: none;
 }
 
-.label:not(:has(.label__title, .label__subtitle, .label__description, .label__caption)) {
-  display: block;
+/* sub-part (Title/Subtitle/Description/Caption) 가 자식에 있을 때만 세로 stack. */
+.label:has(.label__title, .label__subtitle, .label__description, .label__caption) {
+  display: flex;
+  flex-direction: column;
+  gap: 0.125rem;
 }
 
 /* ───── 텍스트 계층 ───── */

package/data/registry/react/components/sidebar/index.module.tsx

@@ -743,6 +743,63 @@ export const SidebarMenuButton = React.forwardRef<HTMLButtonElement, SidebarMenu
   }
 );
 
+/* ───────────── Menu trailing slots (badge / action) ─────────────
+ * SidebarMenuButton 의 `> span { flex: 1 }` 흐름 밖(absolute)에 위치해 라벨을
+ * 밀어내지 않는다. SidebarMenuItem 이 trailing 슬롯 존재를 :has() 로 감지해
+ * 내부 button/anchor 에 우측 패딩을 확보한다 (styles.module.css 참고). */
+
+/**
+ * SidebarMenuItem 의 우측 trailing 배지 (안 읽음 수 등). SidebarMenuButton 의
+ * 형제로 둔다 — absolute 라 라벨을 밀어내지 않고, pointer-events:none 으로 클릭은
+ * 행 전체 button 으로 통과한다.
+ *
+ *   <SidebarMenuItem>
+ *     <SidebarMenuButton render={<Link href='/x'>채팅</Link>} />
+ *     <SidebarMenuBadge>8</SidebarMenuBadge>
+ *   </SidebarMenuItem>
+ */
+export function SidebarMenuBadge({ className, ...props }: React.HTMLAttributes<HTMLDivElement>) {
+  return (
+    <div
+      data-sidebar="menu-badge"
+      className={cn(styles["sidebar__menu-badge"], className)}
+      {...props}
+    />
+  );
+}
+
+export interface SidebarMenuActionProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
+  /** 행 hover/포커스 시에만 노출. 기본은 항상 표시. */
+  showOnHover?: boolean;
+}
+
+/**
+ * SidebarMenuItem 의 우측 trailing 액션 버튼 (… 메뉴, 추가 등). badge 와 달리
+ * 클릭 가능. `showOnHover` 면 행 hover/포커스 시에만 노출 (CSS 부모 hover 셀렉터).
+ *
+ *   <SidebarMenuItem>
+ *     <SidebarMenuButton render={<Link href='/x'>채널</Link>} />
+ *     <SidebarMenuAction showOnHover aria-label='채널 설정'><MoreIcon /></SidebarMenuAction>
+ *   </SidebarMenuItem>
+ */
+export const SidebarMenuAction = React.forwardRef<HTMLButtonElement, SidebarMenuActionProps>(
+  function SidebarMenuAction({ className, showOnHover, ...props }, ref) {
+    return (
+      <button
+        ref={ref}
+        type="button"
+        data-sidebar="menu-action"
+        className={cn(
+          styles["sidebar__menu-action"],
+          showOnHover && styles["sidebar__menu-action--hover"],
+          className,
+        )}
+        {...props}
+      />
+    );
+  }
+);
+
 /* ───────────── Sub menu ───────────── */
 
 /** 메뉴 항목 내부의 서브 메뉴 리스트. SidebarMenuItem 안에 둔다. */

package/data/registry/react/components/sidebar/index.tailwind.tsx

@@ -445,7 +445,18 @@ export function SidebarMenu({ className, ...props }: React.HTMLAttributes<HTMLUL
 }
 
 export function SidebarMenuItem({ className, ...props }: React.HTMLAttributes<HTMLLIElement>) {
-  return <li className={cn("relative m-0", className)} {...props} />;
+  return (
+    <li
+      className={cn(
+        // group/menu-item — SidebarMenuAction 의 showOnHover hover 타겟.
+        // trailing slot(badge/action)이 있으면 내부 button/anchor 에 우측 패딩을
+        // 확보해 라벨이 trailing 요소 밑으로 들어가지 않게 한다.
+        "group/menu-item relative m-0 has-[[data-sidebar=menu-badge]]:[&>a]:pr-8 has-[[data-sidebar=menu-badge]]:[&>button]:pr-8 has-[[data-sidebar=menu-action]]:[&>a]:pr-8 has-[[data-sidebar=menu-action]]:[&>button]:pr-8",
+        className,
+      )}
+      {...props}
+    />
+  );
 }
 
 export interface SidebarMenuButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
@@ -509,6 +520,62 @@ export const SidebarMenuButton = React.forwardRef<HTMLButtonElement, SidebarMenu
   }
 );
 
+/**
+ * SidebarMenuItem 의 우측 trailing 배지 (안 읽음 수 등). SidebarMenuButton 의
+ * 형제로 둔다 — button 의 `[&>span]:flex-1` 흐름 밖(absolute)이라 라벨을 밀어내지
+ * 않는다. 클릭 통과(pointer-events-none) — 행 전체 클릭이 button 으로 간다.
+ *
+ *   <SidebarMenuItem>
+ *     <SidebarMenuButton render={<Link href='/x'>채팅</Link>} />
+ *     <SidebarMenuBadge>8</SidebarMenuBadge>
+ *   </SidebarMenuItem>
+ */
+export function SidebarMenuBadge({ className, ...props }: React.HTMLAttributes<HTMLDivElement>) {
+  return (
+    <div
+      data-sidebar="menu-badge"
+      className={cn(
+        "pointer-events-none absolute right-[var(--space-2)] top-1/2 flex h-5 min-w-5 -translate-y-1/2 select-none items-center justify-center px-1 text-[length:var(--text-xs)] font-medium tabular-nums text-[var(--sidebar-fg)] [[data-state=collapsed][data-collapsible=icon]_&]:hidden",
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+/**
+ * SidebarMenuItem 의 우측 trailing 액션 버튼 (… 메뉴, 추가 등). badge 와 달리
+ * 클릭 가능. `showOnHover` 면 행 hover/포커스 시에만 노출.
+ *
+ *   <SidebarMenuItem>
+ *     <SidebarMenuButton render={<Link href='/x'>채널</Link>} />
+ *     <SidebarMenuAction showOnHover aria-label='채널 설정'><MoreIcon /></SidebarMenuAction>
+ *   </SidebarMenuItem>
+ */
+export interface SidebarMenuActionProps
+  extends React.ButtonHTMLAttributes<HTMLButtonElement> {
+  showOnHover?: boolean;
+}
+
+export const SidebarMenuAction = React.forwardRef<HTMLButtonElement, SidebarMenuActionProps>(
+  function SidebarMenuAction({ className, showOnHover, ...props }, ref) {
+    return (
+      <button
+        ref={ref}
+        type="button"
+        data-sidebar="menu-action"
+        className={cn(
+          "absolute right-[var(--space-1)] top-1/2 flex h-6 w-6 -translate-y-1/2 items-center justify-center rounded-[calc(var(--radius)-2px)] border-none bg-transparent text-[var(--foreground-muted)] cursor-pointer transition-[background-color,color] duration-[var(--duration-fast)] hover:bg-[var(--sidebar-accent)] hover:text-[var(--sidebar-accent-fg)] focus-visible:outline-[length:var(--border-width-strong)] focus-visible:outline-ring [&>svg]:h-4 [&>svg]:w-4 [&>svg]:shrink-0 [[data-state=collapsed][data-collapsible=icon]_&]:hidden motion-reduce:transition-none",
+          showOnHover &&
+            "opacity-0 focus-visible:opacity-100 group-focus-within/menu-item:opacity-100 group-hover/menu-item:opacity-100 data-[active]:opacity-100",
+          className,
+        )}
+        {...props}
+      />
+    );
+  }
+);
+
 export function SidebarMenuSub({ className, ...props }: React.HTMLAttributes<HTMLUListElement>) {
   return (
     <ul

package/data/registry/react/components/sidebar/index.tsx

@@ -790,6 +790,63 @@ export const SidebarMenuButton = React.forwardRef<HTMLButtonElement, SidebarMenu
   }
 );
 
+/* ───────────── Menu trailing slots (badge / action) ─────────────
+ * SidebarMenuButton 의 `> span { flex: 1 }` 흐름 밖(absolute)에 위치해 라벨을
+ * 밀어내지 않는다. SidebarMenuItem 이 trailing 슬롯 존재를 :has() 로 감지해
+ * 내부 button/anchor 에 우측 패딩을 확보한다 (styles.css 참고). */
+
+/**
+ * SidebarMenuItem 의 우측 trailing 배지 (안 읽음 수 등). SidebarMenuButton 의
+ * 형제로 둔다 — absolute 라 라벨을 밀어내지 않고, pointer-events:none 으로 클릭은
+ * 행 전체 button 으로 통과한다.
+ *
+ *   <SidebarMenuItem>
+ *     <SidebarMenuButton render={<Link href='/x'>채팅</Link>} />
+ *     <SidebarMenuBadge>8</SidebarMenuBadge>
+ *   </SidebarMenuItem>
+ */
+export function SidebarMenuBadge({ className, ...props }: React.HTMLAttributes<HTMLDivElement>) {
+  return (
+    <div
+      data-sidebar="menu-badge"
+      className={cn("sh-ui-sidebar__menu-badge", className)}
+      {...props}
+    />
+  );
+}
+
+export interface SidebarMenuActionProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
+  /** 행 hover/포커스 시에만 노출. 기본은 항상 표시. */
+  showOnHover?: boolean;
+}
+
+/**
+ * SidebarMenuItem 의 우측 trailing 액션 버튼 (… 메뉴, 추가 등). badge 와 달리
+ * 클릭 가능. `showOnHover` 면 행 hover/포커스 시에만 노출 (CSS 부모 hover 셀렉터).
+ *
+ *   <SidebarMenuItem>
+ *     <SidebarMenuButton render={<Link href='/x'>채널</Link>} />
+ *     <SidebarMenuAction showOnHover aria-label='채널 설정'><MoreIcon /></SidebarMenuAction>
+ *   </SidebarMenuItem>
+ */
+export const SidebarMenuAction = React.forwardRef<HTMLButtonElement, SidebarMenuActionProps>(
+  function SidebarMenuAction({ className, showOnHover, ...props }, ref) {
+    return (
+      <button
+        ref={ref}
+        type="button"
+        data-sidebar="menu-action"
+        className={cn(
+          "sh-ui-sidebar__menu-action",
+          showOnHover && "sh-ui-sidebar__menu-action--hover",
+          className,
+        )}
+        {...props}
+      />
+    );
+  }
+);
+
 /* ───────────── Sub menu ───────────── */
 
 /** 메뉴 항목 내부의 서브 메뉴 리스트. SidebarMenuItem 안에 둔다. */

package/data/registry/react/components/sidebar/styles.css

@@ -433,6 +433,15 @@
   margin: 0;
 }
 
+/* trailing 슬롯(badge/action)이 있으면 내부 button/anchor 에 우측 패딩을 확보해
+ * 라벨이 trailing 요소 밑으로 들어가지 않게 한다. */
+.sh-ui-sidebar__menu-item:has(.sh-ui-sidebar__menu-badge) > a,
+.sh-ui-sidebar__menu-item:has(.sh-ui-sidebar__menu-badge) > button,
+.sh-ui-sidebar__menu-item:has(.sh-ui-sidebar__menu-action) > a,
+.sh-ui-sidebar__menu-item:has(.sh-ui-sidebar__menu-action) > button {
+  padding-inline-end: 2rem;
+}
+
 .sh-ui-sidebar__menu-button {
   display: flex;
   width: 100%;
@@ -499,6 +508,73 @@
   font-size: 0.9375rem;
 }
 
+/* ───────────── Menu trailing slots (badge / action) ───────────── */
+.sh-ui-sidebar__menu-badge {
+  position: absolute;
+  right: var(--space-2);
+  top: 50%;
+  transform: translateY(-50%);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  height: 1.25rem;
+  min-width: 1.25rem;
+  padding: 0 0.25rem;
+  font-size: var(--text-xs);
+  font-weight: var(--weight-medium);
+  font-variant-numeric: tabular-nums;
+  color: var(--sidebar-fg);
+  pointer-events: none;
+  user-select: none;
+}
+
+.sh-ui-sidebar__menu-action {
+  position: absolute;
+  right: var(--space-1);
+  top: 50%;
+  transform: translateY(-50%);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 1.5rem;
+  height: 1.5rem;
+  border: none;
+  border-radius: calc(var(--radius) - 2px);
+  background: transparent;
+  color: var(--foreground-muted);
+  cursor: pointer;
+  transition: background-color var(--duration-fast), color var(--duration-fast), opacity var(--duration-fast);
+}
+.sh-ui-sidebar__menu-action > svg {
+  width: 1rem;
+  height: 1rem;
+  flex-shrink: 0;
+}
+.sh-ui-sidebar__menu-action:hover {
+  background: var(--sidebar-accent);
+  color: var(--sidebar-accent-fg);
+}
+.sh-ui-sidebar__menu-action:focus-visible {
+  outline: var(--border-width-strong) solid var(--ring);
+}
+
+/* showOnHover — 행 hover/포커스 시에만 노출. 부모 menu-item hover/focus-within 셀렉터. */
+.sh-ui-sidebar__menu-action--hover {
+  opacity: 0;
+}
+.sh-ui-sidebar__menu-item:hover .sh-ui-sidebar__menu-action--hover,
+.sh-ui-sidebar__menu-item:focus-within .sh-ui-sidebar__menu-action--hover,
+.sh-ui-sidebar__menu-action--hover:focus-visible,
+.sh-ui-sidebar__menu-action--hover[data-active] {
+  opacity: 1;
+}
+
+/* collapsed=icon 모드에서는 trailing 슬롯 숨김 (라벨도 숨겨지므로) */
+.sh-ui-sidebar[data-state="collapsed"][data-collapsible="icon"] .sh-ui-sidebar__menu-badge,
+.sh-ui-sidebar[data-state="collapsed"][data-collapsible="icon"] .sh-ui-sidebar__menu-action {
+  display: none;
+}
+
 /* ───────────── Sub menu ───────────── */
 .sh-ui-sidebar__menu-sub {
   list-style: none;
@@ -607,6 +683,7 @@
   .sh-ui-sidebar__trigger,
   .sh-ui-sidebar__menu-button,
   .sh-ui-sidebar__menu-sub-button,
+  .sh-ui-sidebar__menu-action,
   .sh-ui-sidebar__panel-close,
   .sh-ui-sidebar__chevron,
   .sh-ui-sidebar__collapsible-content {

package/data/registry/react/components/sidebar/styles.module.css

@@ -412,6 +412,15 @@
   margin: 0;
 }
 
+/* trailing 슬롯(badge/action)이 있으면 내부 button/anchor 에 우측 패딩을 확보해
+ * 라벨이 trailing 요소 밑으로 들어가지 않게 한다. */
+.sidebar__menu-item:has(.sidebar__menu-badge) > a,
+.sidebar__menu-item:has(.sidebar__menu-badge) > button,
+.sidebar__menu-item:has(.sidebar__menu-action) > a,
+.sidebar__menu-item:has(.sidebar__menu-action) > button {
+  padding-inline-end: 2rem;
+}
+
 .sidebar__menu-button {
   display: flex;
   width: 100%;
@@ -478,6 +487,73 @@
   font-size: 0.9375rem;
 }
 
+/* ───────────── Menu trailing slots (badge / action) ───────────── */
+.sidebar__menu-badge {
+  position: absolute;
+  right: var(--space-2);
+  top: 50%;
+  transform: translateY(-50%);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  height: 1.25rem;
+  min-width: 1.25rem;
+  padding: 0 0.25rem;
+  font-size: var(--text-xs);
+  font-weight: var(--weight-medium);
+  font-variant-numeric: tabular-nums;
+  color: var(--sidebar-fg);
+  pointer-events: none;
+  user-select: none;
+}
+
+.sidebar__menu-action {
+  position: absolute;
+  right: var(--space-1);
+  top: 50%;
+  transform: translateY(-50%);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 1.5rem;
+  height: 1.5rem;
+  border: none;
+  border-radius: calc(var(--radius) - 2px);
+  background: transparent;
+  color: var(--foreground-muted);
+  cursor: pointer;
+  transition: background-color var(--duration-fast), color var(--duration-fast), opacity var(--duration-fast);
+}
+.sidebar__menu-action > svg {
+  width: 1rem;
+  height: 1rem;
+  flex-shrink: 0;
+}
+.sidebar__menu-action:hover {
+  background: var(--sidebar-accent);
+  color: var(--sidebar-accent-fg);
+}
+.sidebar__menu-action:focus-visible {
+  outline: var(--border-width-strong) solid var(--ring);
+}
+
+/* showOnHover — 행 hover/포커스 시에만 노출. 부모 menu-item hover/focus-within 셀렉터. */
+.sidebar__menu-action--hover {
+  opacity: 0;
+}
+.sidebar__menu-item:hover .sidebar__menu-action--hover,
+.sidebar__menu-item:focus-within .sidebar__menu-action--hover,
+.sidebar__menu-action--hover:focus-visible,
+.sidebar__menu-action--hover[data-active] {
+  opacity: 1;
+}
+
+/* collapsed=icon 모드에서는 trailing 슬롯 숨김 (라벨도 숨겨지므로) */
+.sidebar[data-state="collapsed"][data-collapsible="icon"] .sidebar__menu-badge,
+.sidebar[data-state="collapsed"][data-collapsible="icon"] .sidebar__menu-action {
+  display: none;
+}
+
 /* ───────────── Sub menu ───────────── */
 .sidebar__menu-sub {
   list-style: none;
@@ -575,6 +651,7 @@
   .sidebar__trigger,
   .sidebar__menu-button,
   .sidebar__menu-sub-button,
+  .sidebar__menu-action,
   .sidebar__panel-close,
   .sidebar__chevron {
     transition: none;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sh-ui-cli",
-  "version": "0.113.0",
+  "version": "0.114.0",
   "description": "sh-ui CLI — 프로젝트 스캐폴드(create) + 컴포넌트 추가(add/list/remove) + IDE-내 AI용 MCP 서버",
   "license": "MIT",
   "repository": {