@reopt-ai/opt-ui 1.13.0 → 1.15.0

package/dist/docs/02-components/01-core.md

@@ -1,7 +1,7 @@
 ---
 title: "Core Components"
 description: "74 Core layer components — props, examples, keyboard shortcuts."
-version: "1.13.0"
+version: "1.15.0"
 generated: true
 ---
 
@@ -95,6 +95,25 @@ const store = useFormStore({ defaultValues: { name: "" } });
 | `resize`    | `"none" \| "vertical" \| "horizontal" \| "both"` |          | "vertical" | 크기 조절 방향   |
 | `rows`      | `number`                                         |          | 4          | 표시 줄 수       |
 
+**Examples:**
+
+_설명 입력:_
+
+```tsx
+import { Textarea } from "@reopt-ai/opt-ui";
+export function Example() {
+  return (
+    <Textarea
+      label="변경 이유"
+      name="reason"
+      hint="검토자가 알아야 할 내용을 적어주세요"
+      rows={4}
+      resize="vertical"
+    />
+  );
+}
+```
+
 ### NumberInput
 
 > 숫자 입력 컴포넌트. +/- 버튼, nullable/clear, unit suffix, invalid draft alert, min/max, step, 키보드 화살표를 지원합니다.
@@ -154,6 +173,22 @@ const store = useFormStore({ defaultValues: { name: "" } });
 | `orientation`  | `"horizontal" \| "vertical"` |          | "vertical" | 레이아웃 방향                  |
 | `label`        | `string`                     |          |            | 그룹 레이블                    |
 
+**Examples:**
+
+_복수 선택 그룹:_
+
+```tsx
+import { Checkbox, CheckboxGroup } from "@reopt-ai/opt-ui";
+export function Example() {
+  return (
+    <CheckboxGroup label="알림 채널" defaultValue={["email"]}>
+      <Checkbox value="email" label="이메일" />
+      <Checkbox value="push" label="푸시" />
+    </CheckboxGroup>
+  );
+}
+```
+
 ### RadioGroup
 
 > 독립적인 라디오 그룹 컴포넌트. 그룹 설명과 항목별 설명을 분리 연결하고 다양한 크기를 지원합니다.
@@ -206,6 +241,27 @@ const store = useFormStore({ defaultValues: { name: "" } });
 | `size`           | `"sm" \| "md" \| "lg"`       |          | "md"    | 스위치 크기                                                                |
 | `disabled`       | `boolean`                    |          |         | 비활성화 상태                                                              |
 
+**Examples:**
+
+_제어되는 알림 설정:_
+
+```tsx
+"use client";
+import { useState } from "react";
+import { Switch } from "@reopt-ai/opt-ui";
+export function Example() {
+  const [enabled, setEnabled] = useState(false);
+  return (
+    <Switch
+      label="이메일 알림"
+      hint="새 댓글을 이메일로 받습니다"
+      checked={enabled}
+      onChange={setEnabled}
+    />
+  );
+}
+```
+
 ### Select
 
 > 드롭다운 선택 컴포넌트. 5-part anatomy: Root, Label, Trigger, Popover, Item.
@@ -241,7 +297,7 @@ const store = useFormStore({ defaultValues: { name: "" } });
 | ----------- | ----------- | -------- | ------- | ------------------------------------------------------------------------------ |
 | `children`  | `ReactNode` | Yes      |         | SelectItem 목록                                                                |
 | `sameWidth` | `boolean`   |          | true    | 트리거와 같은 너비                                                             |
-| `gutter`    | `number`    |          | 4       | 트리거와의 간격 (px) **⚠️ deprecated since 1.12.5 — use `sideOffset` instead** |
+| `gutter`    | `number`    |          | 4       | 트리거와의 간격 (px) **⚠️ deprecated since 1.13.0 — use `sideOffset` instead** |
 | `className` | `string`    |          |         | 기본 스타일 오버라이드                                                         |
 
 **SelectItem:**
@@ -295,7 +351,7 @@ import {
 
 | Prop               | Type                      | Required | Default | Description                                                                     |
 | ------------------ | ------------------------- | -------- | ------- | ------------------------------------------------------------------------------- |
-| `setValue`         | `(value: string) => void` |          |         | 입력값 변경 핸들러 **⚠️ deprecated since 1.12.5 — use `onValueChange` instead** |
+| `setValue`         | `(value: string) => void` |          |         | 입력값 변경 핸들러 **⚠️ deprecated since 1.13.0 — use `onValueChange` instead** |
 | `resetValueOnHide` | `boolean`                 |          | false   | 팝오버 닫힐 때 입력값 리셋                                                      |
 
 **ComboboxInput:**
@@ -312,7 +368,7 @@ import {
 | ----------- | ----------- | -------- | ------- | ---------------------------------------------------------------------------- |
 | `children`  | `ReactNode` | Yes      |         | ComboboxItem/Group 목록                                                      |
 | `sameWidth` | `boolean`   |          | true    | 입력과 같은 너비                                                             |
-| `gutter`    | `number`    |          | 4       | 입력과의 간격 (px) **⚠️ deprecated since 1.12.5 — use `sideOffset` instead** |
+| `gutter`    | `number`    |          | 4       | 입력과의 간격 (px) **⚠️ deprecated since 1.13.0 — use `sideOffset` instead** |
 | `className` | `string`    |          |         | 기본 스타일 오버라이드                                                       |
 
 **ComboboxItem:**
@@ -436,19 +492,20 @@ import {
 
 **Import:** `import { Slider } from "@reopt-ai/opt-ui"`
 
-| Prop           | Type                        | Required | Default | Description        |
-| -------------- | --------------------------- | -------- | ------- | ------------------ |
-| `value`        | `number`                    |          |         | 제어 모드 값       |
-| `defaultValue` | `number`                    |          | 0       | 비제어 모드 초기값 |
-| `onChange`     | `(value: number) => void`   |          |         | 값 변경 핸들러     |
-| `min`          | `number`                    |          | 0       | 최솟값             |
-| `max`          | `number`                    |          | 100     | 최댓값             |
-| `step`         | `number`                    |          | 1       | 증감 단위          |
-| `label`        | `string`                    |          |         | 레이블 텍스트      |
-| `showValue`    | `boolean`                   |          | false   | 현재 값 표시 여부  |
-| `formatValue`  | `(value: number) => string` |          |         | 값 포맷 함수       |
-| `disabled`     | `boolean`                   |          |         | 비활성화           |
-| `className`    | `string`                    |          |         | 최외곽 CSS 클래스  |
+| Prop            | Type                        | Required | Default | Description                                                       |
+| --------------- | --------------------------- | -------- | ------- | ----------------------------------------------------------------- |
+| `value`         | `number`                    |          |         | 제어 모드 값                                                      |
+| `defaultValue`  | `number`                    |          | 0       | 비제어 모드 초기값                                                |
+| `onChange`      | `(value: number) => void`   |          |         | 값 변경 핸들러                                                    |
+| `onValueCommit` | `(value: number) => void`   |          |         | 포인터·키보드 편집 완료 시 한 번 호출. 취소와 외부 값 갱신은 제외 |
+| `min`           | `number`                    |          | 0       | 최솟값                                                            |
+| `max`           | `number`                    |          | 100     | 최댓값                                                            |
+| `step`          | `number`                    |          | 1       | 증감 단위                                                         |
+| `label`         | `string`                    |          |         | 레이블 텍스트                                                     |
+| `showValue`     | `boolean`                   |          | false   | 현재 값 표시 여부                                                 |
+| `formatValue`   | `(value: number) => string` |          |         | 값 포맷 함수                                                      |
+| `disabled`      | `boolean`                   |          |         | 비활성화                                                          |
+| `className`     | `string`                    |          |         | 최외곽 CSS 클래스                                                 |
 
 ## Form Integration
 
@@ -491,12 +548,15 @@ import {
 
 **FormSelect:**
 
-| Prop          | Type        | Required | Default | Description                    |
-| ------------- | ----------- | -------- | ------- | ------------------------------ |
-| `name`        | `string`    | Yes      |         | 폼 필드 이름                   |
-| `children`    | `ReactNode` | Yes      |         | FormSelectPopover 등 자식 요소 |
-| `placeholder` | `string`    |          |         | 미선택 시 표시 텍스트          |
-| `className`   | `string`    |          |         | 추가 CSS 클래스                |
+| Prop               | Type        | Required | Default | Description                                |
+| ------------------ | ----------- | -------- | ------- | ------------------------------------------ |
+| `id`               | `string`    |          |         | 트리거 ID. 외부 FormLabel의 htmlFor와 연결 |
+| `aria-label`       | `string`    |          |         | 입력의 접근 가능한 이름                    |
+| `aria-describedby` | `string`    |          |         | 설명·오류 요소의 ID 목록                   |
+| `name`             | `string`    | Yes      |         | 폼 필드 이름                               |
+| `children`         | `ReactNode` | Yes      |         | FormSelectPopover 등 자식 요소             |
+| `placeholder`      | `string`    |          |         | 미선택 시 표시 텍스트                      |
+| `className`        | `string`    |          |         | 추가 CSS 클래스                            |
 
 **FormSelectPopover:**
 
@@ -504,7 +564,7 @@ import {
 | ----------- | ----------- | -------- | ------- | ------------------------------------------------------------------------------ |
 | `children`  | `ReactNode` | Yes      |         | FormSelectItem 목록                                                            |
 | `sameWidth` | `boolean`   |          | true    | 트리거와 같은 너비                                                             |
-| `gutter`    | `number`    |          | 4       | 트리거와의 간격 (px) **⚠️ deprecated since 1.12.5 — use `sideOffset` instead** |
+| `gutter`    | `number`    |          | 4       | 트리거와의 간격 (px) **⚠️ deprecated since 1.13.0 — use `sideOffset` instead** |
 
 **FormSelectItem:**
 
@@ -797,6 +857,21 @@ import { Button } from "@reopt-ai/opt-ui";
 | `progress`     | `number`                                                   |          |           | 원형 프로그레스 값 (0-100). 설정 시 dot 무시 |
 | `progressSize` | `number`                                                   |          | 16        | 프로그레스 링 SVG 크기 (px)                  |
 
+**Examples:**
+
+_텍스트가 있는 상태:_
+
+```tsx
+import { Badge } from "@reopt-ai/opt-ui";
+export function Example() {
+  return (
+    <Badge variant="success" dot>
+      동기화 완료
+    </Badge>
+  );
+}
+```
+
 ### Alert
 
 > 알림 메시지 컴포넌트. 4가지 변형(info, success, warning, error), 제목/본문/닫기 버튼 지원.
@@ -811,6 +886,21 @@ import { Button } from "@reopt-ai/opt-ui";
 | `dismissible` | `boolean`                                     |          | false   | 닫기 버튼 표시 여부                                   |
 | `onDismiss`   | `() => void`                                  |          |         | 닫기 버튼 클릭 핸들러                                 |
 
+**Examples:**
+
+_재시도 가능한 오류 안내:_
+
+```tsx
+import { Alert } from "@reopt-ai/opt-ui";
+export function Example() {
+  return (
+    <Alert variant="error" title="저장하지 못했습니다">
+      연결 상태를 확인한 뒤 다시 저장하세요.
+    </Alert>
+  );
+}
+```
+
 ### Spinner
 
 > 로딩 상태 표시 스피너. 3가지 크기와 장식용 aria-hidden 모드를 지원합니다.
@@ -821,6 +911,17 @@ import { Button } from "@reopt-ai/opt-ui";
 | ------ | ---------------------- | -------- | ------- | ----------- |
 | `size` | `"sm" \| "md" \| "lg"` |          | "md"    | 스피너 크기 |
 
+**Examples:**
+
+_이름 있는 로딩 표시:_
+
+```tsx
+import { Spinner } from "@reopt-ai/opt-ui";
+export function Example() {
+  return <Spinner size="sm" aria-label="검색 결과 불러오는 중" />;
+}
+```
+
 ### LoadingOverlay
 
 > 로딩 오버레이. 중복 status 없이 하나의 aria-busy 라이브 영역으로 콘텐츠 위 로딩 상태를 표시합니다.
@@ -834,6 +935,21 @@ import { Button } from "@reopt-ai/opt-ui";
 | `children` | `ReactNode` | Yes      |            | 감싸는 콘텐츠 |
 | `label`    | `string`    |          | "Loading…" | 로딩 텍스트   |
 
+**Examples:**
+
+_기존 결과를 유지하는 갱신 표시:_
+
+```tsx
+import { LoadingOverlay } from "@reopt-ai/opt-ui";
+export function Example() {
+  return (
+    <LoadingOverlay loading label="목록 새로고침 중">
+      <p>이전 조회 결과</p>
+    </LoadingOverlay>
+  );
+}
+```
+
 ### Progress
 
 > 진행률 표시. Linear/Circular, determinate/indeterminate 변형과 안전하게 보정된 ARIA 값을 지원합니다.
@@ -866,6 +982,17 @@ import { Button } from "@reopt-ai/opt-ui";
 | `label`         | `string`                                         |          |           | 접근성 레이블                        |
 | `indeterminate` | `boolean`                                        |          | false     | 값을 알 수 없는 진행 상태            |
 
+**Examples:**
+
+_업로드 진행률:_
+
+```tsx
+import { Progress } from "@reopt-ai/opt-ui";
+export function Example() {
+  return <Progress value={35} max={100} aria-label="파일 업로드" />;
+}
+```
+
 ### Avatar
 
 > 사용자 아바타. 이미지, 이니셜 자동 생성, 스크린 리더에 노출되는 상태 인디케이터, 그룹을 지원합니다.
@@ -891,6 +1018,22 @@ import { Button } from "@reopt-ai/opt-ui";
 | `size`     | `"xs" \| "sm" \| "md" \| "lg" \| "xl"` |          | "md"    | 아바타 크기    |
 | `children` | `ReactNode`                            | Yes      |         | Avatar 요소들  |
 
+**Examples:**
+
+_이미지 없이 사용자 표시:_
+
+```tsx
+import { Avatar, AvatarGroup } from "@reopt-ai/opt-ui";
+export function Example() {
+  return (
+    <AvatarGroup max={3}>
+      <Avatar name="김민수" />
+      <Avatar name="이지수" />
+    </AvatarGroup>
+  );
+}
+```
+
 ### Skeleton
 
 > 로딩 플레이스홀더. text/circular/rectangular 변형. 프리셋 컴포넌트 포함.
@@ -926,6 +1069,21 @@ import { Button } from "@reopt-ai/opt-ui";
 | `rows`    | `number` |          | 5       | 테이블 행 수 |
 | `columns` | `number` |          | 4       | 테이블 열 수 |
 
+**Examples:**
+
+_목록 로딩 자리 확보:_
+
+```tsx
+import { SkeletonTable } from "@reopt-ai/opt-ui";
+export function Example() {
+  return (
+    <section aria-label="목록 불러오는 중" aria-busy="true">
+      <SkeletonTable rows={3} columns={4} />
+    </section>
+  );
+}
+```
+
 ### Card
 
 > 범용 카드 컨테이너. Header, Title, Description, Content, Footer 하위 컴포넌트 포함.
@@ -1118,7 +1276,7 @@ import {
 | Prop        | Type        | Required | Default | Description                                                                    |
 | ----------- | ----------- | -------- | ------- | ------------------------------------------------------------------------------ |
 | `children`  | `ReactNode` | Yes      |         | MenuItem 목록                                                                  |
-| `gutter`    | `number`    |          | 8       | 트리거와의 간격 (px) **⚠️ deprecated since 1.12.5 — use `sideOffset` instead** |
+| `gutter`    | `number`    |          | 8       | 트리거와의 간격 (px) **⚠️ deprecated since 1.13.0 — use `sideOffset` instead** |
 | `className` | `string`    |          |         | 기본 스타일 오버라이드                                                         |
 
 **MenuItem:**
@@ -1176,7 +1334,7 @@ import {
 
 | Prop     | Type     | Required | Default | Description                                                                    |
 | -------- | -------- | -------- | ------- | ------------------------------------------------------------------------------ |
-| `gutter` | `number` |          | 4       | 트리거와의 간격 (px) **⚠️ deprecated since 1.12.5 — use `sideOffset` instead** |
+| `gutter` | `number` |          | 4       | 트리거와의 간격 (px) **⚠️ deprecated since 1.13.0 — use `sideOffset` instead** |
 
 **DropdownItem:**
 
@@ -1200,10 +1358,9 @@ import {
 
 **Import:** `import { PopoverRoot } from "@reopt-ai/opt-ui"`
 
-| Prop        | Type     | Required | Default | Description                                                                    |
-| ----------- | -------- | -------- | ------- | ------------------------------------------------------------------------------ |
-| `gutter`    | `number` |          | 8       | 트리거와의 간격 (px) **⚠️ deprecated since 1.12.5 — use `sideOffset` instead** |
-| `className` | `string` |          |         | 커스텀 CSS 클래스                                                              |
+| Prop        | Type     | Required | Default | Description       |
+| ----------- | -------- | -------- | ------- | ----------------- |
+| `className` | `string` |          |         | 커스텀 CSS 클래스 |
 
 **Keyboard Shortcuts:**
 
@@ -1212,6 +1369,30 @@ import {
 | `Esc`           | 팝오버 닫기   |
 | `Enter / Space` | 트리거 활성화 |
 
+**Examples:**
+
+_보조 설명 열고 닫기:_
+
+```tsx
+import {
+  PopoverRoot,
+  PopoverTrigger,
+  PopoverContent,
+  PopoverClose,
+} from "@reopt-ai/opt-ui";
+export function Example() {
+  return (
+    <PopoverRoot>
+      <PopoverTrigger>공유 안내</PopoverTrigger>
+      <PopoverContent>
+        <p>초대받은 사용자만 문서를 볼 수 있습니다.</p>
+        <PopoverClose>닫기</PopoverClose>
+      </PopoverContent>
+    </PopoverRoot>
+  );
+}
+```
+
 ### Tabs
 
 > 탭 패널 시스템. 4-part anatomy: Root, TabList, Tab, TabPanel.
@@ -1225,7 +1406,7 @@ import {
 | `variant`           | `"underline" \| "workspace"`   |          |         | 탭 프레임 형태. workspace는 편집기 탭(문서/쿼리처럼 열고 닫히며 상태를 갖는 작업 단위)      |
 | `defaultSelectedId` | `string`                       |          |         | 초기 선택된 탭 ID                                                                           |
 | `selectedId`        | `string \| null`               |          |         | 제어 모드: 선택된 탭 ID                                                                     |
-| `setSelectedId`     | `(id: string \| null) => void` |          |         | 제어 모드: 탭 변경 핸들러 **⚠️ deprecated since 1.12.5 — use `onSelectedIdChange` instead** |
+| `setSelectedId`     | `(id: string \| null) => void` |          |         | 제어 모드: 탭 변경 핸들러 **⚠️ deprecated since 1.13.0 — use `onSelectedIdChange` instead** |
 
 **TabList:**
 
@@ -1262,6 +1443,27 @@ import {
 | `Home` | 첫 번째 탭으로 이동 |
 | `End`  | 마지막 탭으로 이동  |
 
+**Examples:**
+
+_이름 있는 두 패널:_
+
+```tsx
+import { TabsRoot, TabList, Tab, TabPanel } from "@reopt-ai/opt-ui";
+
+export function Example() {
+  return (
+    <TabsRoot defaultSelectedId="overview">
+      <TabList aria-label="프로젝트 정보">
+        <Tab id="overview">개요</Tab>
+        <Tab id="activity">활동</Tab>
+      </TabList>
+      <TabPanel tabId="overview">프로젝트 요약</TabPanel>
+      <TabPanel tabId="activity">최근 활동</TabPanel>
+    </TabsRoot>
+  );
+}
+```
+
 ### Disclosure
 
 > 접기/펼치기 콘텐츠 영역. 3-part anatomy: Root, Trigger, Content.
@@ -1273,7 +1475,7 @@ import {
 | Prop          | Type                      | Required | Default | Description                                                                             |
 | ------------- | ------------------------- | -------- | ------- | --------------------------------------------------------------------------------------- |
 | `open`        | `boolean`                 |          |         | 제어 모드: 열림 상태                                                                    |
-| `setOpen`     | `(open: boolean) => void` |          |         | 제어 모드: 상태 변경 핸들러 **⚠️ deprecated since 1.12.5 — use `onOpenChange` instead** |
+| `setOpen`     | `(open: boolean) => void` |          |         | 제어 모드: 상태 변경 핸들러 **⚠️ deprecated since 1.13.0 — use `onOpenChange` instead** |
 | `defaultOpen` | `boolean`                 |          | false   | 비제어 모드: 초기 열림 상태                                                             |
 
 **DisclosureTrigger:**
@@ -1307,7 +1509,7 @@ import {
 | Prop      | Type                      | Required | Default | Description                                                                             |
 | --------- | ------------------------- | -------- | ------- | --------------------------------------------------------------------------------------- |
 | `open`    | `boolean`                 |          |         | 제어 모드: 열림 상태                                                                    |
-| `setOpen` | `(open: boolean) => void` |          |         | 제어 모드: 상태 변경 핸들러 **⚠️ deprecated since 1.12.5 — use `onOpenChange` instead** |
+| `setOpen` | `(open: boolean) => void` |          |         | 제어 모드: 상태 변경 핸들러 **⚠️ deprecated since 1.13.0 — use `onOpenChange` instead** |
 
 **DialogDisclosure:**
 
@@ -1667,18 +1869,19 @@ import {
 
 **Import:** `import { ConditionBuilder } from "@reopt-ai/opt-ui"`
 
-| Prop                  | Type                                    | Required | Default            | Description                            |
-| --------------------- | --------------------------------------- | -------- | ------------------ | -------------------------------------- |
-| `groups`              | `ConditionGroup[]`                      | Yes      |                    | 조건 그룹 배열                         |
-| `onChange`            | `(groups: ConditionGroup[]) => void`    | Yes      |                    | 그룹 변경 핸들러                       |
-| `properties`          | `string[]`                              |          |                    | 선택 가능한 속성 목록 (기본 10개 제공) |
-| `label`               | `string`                                |          |                    | 빌더 레이블                            |
-| `nested`              | `boolean`                               |          | false              | 중첩 AND/OR 그룹 활성화                |
-| `maxDepth`            | `number`                                |          | 3                  | 최대 중첩 깊이                         |
-| `conditionTypes`      | `Record<string, ConditionTypeRenderer>` |          |                    | 이질적 조건 타입 렌더러 레지스트리     |
-| `onPreview`           | `(groups: ConditionGroup[]) => void`    |          |                    | 조건 변경 시 미리보기 콜백             |
-| `previewCount`        | `number`                                |          |                    | 매치 카운트 표시 (toLocaleString 포맷) |
-| `addNestedGroupLabel` | `string`                                |          | "Add nested group" | 중첩 그룹 추가 버튼 텍스트             |
+| Prop                  | Type                                    | Required | Default            | Description                                                                    |
+| --------------------- | --------------------------------------- | -------- | ------------------ | ------------------------------------------------------------------------------ |
+| `groups`              | `ConditionGroup[]`                      | Yes      |                    | 조건 그룹 배열                                                                 |
+| `onChange`            | `(groups: ConditionGroup[]) => void`    | Yes      |                    | 그룹 변경 핸들러                                                               |
+| `properties`          | `string[]`                              |          |                    | 선택 가능한 속성 목록 (기본 10개 제공)                                         |
+| `label`               | `string`                                |          |                    | 빌더 레이블                                                                    |
+| `nested`              | `boolean`                               |          | false              | 중첩 AND/OR 그룹 활성화                                                        |
+| `maxDepth`            | `number`                                |          | 3                  | 최대 중첩 깊이                                                                 |
+| `conditionTypes`      | `Record<string, ConditionTypeRenderer>` |          |                    | 이질적 조건 타입 렌더러 레지스트리                                             |
+| `onPreview`           | `(groups: ConditionGroup[]) => void`    |          |                    | 조건 변경 시 미리보기 콜백                                                     |
+| `previewCount`        | `number`                                |          |                    | 매치 카운트 표시 (toLocaleString 포맷)                                         |
+| `labels`              | `ConditionBuilderLabels`                |          |                    | 미리보기 문구 오버라이드 (previewSuffix, formatPreview). 기본은 영어 "matches" |
+| `addNestedGroupLabel` | `string`                                |          | "Add nested group" | 중첩 그룹 추가 버튼 텍스트                                                     |
 
 ## Other
 
@@ -1879,19 +2082,19 @@ import {
 
 **Import:** `import { InlineEdit } from "@reopt-ai/opt-ui"`
 
-| Prop          | Type                                                            | Required | Default    | Description                                 |
-| ------------- | --------------------------------------------------------------- | -------- | ---------- | ------------------------------------------- |
-| `value`       | `string`                                                        | Yes      |            | 현재 값                                     |
-| `onSave`      | `(next: string) => boolean \| void \| Promise<boolean \| void>` | Yes      |            | 저장. false를 반환하면 거절하고 편집을 유지 |
-| `as`          | `"span" \| "h1" \| "h2" \| "h3" \| "h4"`                        |          | "span"     | 읽기 모드 요소                              |
-| `size`        | `"sm" \| "md" \| "lg" \| "xl"`                                  |          | "md"       | 타이포 크기                                 |
-| `placeholder` | `string`                                                        |          |            | 입력 자리표시자                             |
-| `emptyText`   | `string`                                                        |          | "Untitled" | 빈 값 표시                                  |
-| `disabled`    | `boolean`                                                       |          | false      | 편집 불가                                   |
-| `maxLength`   | `number`                                                        |          |            | 최대 길이                                   |
-| `suffix`      | `ReactNode`                                                     |          |            | 읽기 모드 텍스트 뒤 요소                    |
-| `labels`      | `InlineEditLabels`                                              |          |            | 지역화 문자열                               |
-| `className`   | `string`                                                        |          |            | 추가 CSS 클래스                             |
+| Prop          | Type                                                            | Required | Default    | Description                                                       |
+| ------------- | --------------------------------------------------------------- | -------- | ---------- | ----------------------------------------------------------------- |
+| `value`       | `string`                                                        | Yes      |            | 현재 값                                                           |
+| `onSave`      | `(next: string) => boolean \| void \| Promise<boolean \| void>` | Yes      |            | 저장. false 반환 또는 Promise 실패 시 입력을 유지하고 오류를 알림 |
+| `as`          | `"span" \| "h1" \| "h2" \| "h3" \| "h4"`                        |          | "span"     | 읽기 모드 요소                                                    |
+| `size`        | `"sm" \| "md" \| "lg" \| "xl"`                                  |          | "md"       | 타이포 크기                                                       |
+| `placeholder` | `string`                                                        |          |            | 입력 자리표시자                                                   |
+| `emptyText`   | `string`                                                        |          | "Untitled" | 빈 값 표시                                                        |
+| `disabled`    | `boolean`                                                       |          | false      | 편집 불가                                                         |
+| `maxLength`   | `number`                                                        |          |            | 최대 길이                                                         |
+| `suffix`      | `ReactNode`                                                     |          |            | 읽기 모드 텍스트 뒤 요소                                          |
+| `labels`      | `InlineEditLabels`                                              |          |            | 입력 이름(input), 편집·저장·취소·오류 안내 문자열                 |
+| `className`   | `string`                                                        |          |            | 추가 CSS 클래스                                                   |
 
 ### KeyPadMenu
 

package/dist/docs/02-components/02-visuals.md

@@ -1,7 +1,7 @@
 ---
 title: "Visual Components"
 description: "0 Visual layer components — props, examples, keyboard shortcuts."
-version: "1.13.0"
+version: "1.15.0"
 generated: true
 ---