@reopt-ai/opt-ui 1.4.1

package/dist/docs/02-components/04-surfaces.md

@@ -0,0 +1,11 @@
+---
+title: "Surface Components"
+description: "0 Surface layer components — props, examples, keyboard shortcuts."
+version: "1.4.1"
+generated: true
+---
+
+# Surface Components (0)
+
+| Surface | Description | Key Props | Dependencies |
+| ------- | ----------- | --------- | ------------ |

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

@@ -0,0 +1,106 @@
+---
+title: "Component Reference"
+description: "Complete reference for 134 @reopt-ai/opt-ui components across 4 layers."
+version: "1.4.1"
+generated: true
+---
+
+# @reopt-ai/opt-ui Component Reference
+
+## Quick Stats
+
+| Layer     | Count   |
+| --------- | ------- |
+| Core      | 59      |
+| Visuals   | 0       |
+| Shells    | 75      |
+| Surfaces  | 0       |
+| **Total** | **134** |
+
+## Component Selection Guide
+
+| 요구사항            | 추천 컴포넌트                                      | 레이어       |
+| ------------------- | -------------------------------------------------- | ------------ |
+| 텍스트 입력         | Input                                              | Core         |
+| 멀티라인 텍스트     | Textarea                                           | Core         |
+| 숫자 입력           | NumberInput                                        | Core         |
+| 드롭다운 선택       | Select / StatusSelect / BranchSelect               | Core / Shell |
+| 검색 + 선택         | Combobox / SearchCombobox / AsyncCombobox          | Core / Shell |
+| 체크박스            | Checkbox / CheckboxGroup                           | Core         |
+| 라디오 버튼         | RadioGroup                                         | Core         |
+| 토글 스위치         | Switch                                             | Core         |
+| 날짜 범위 선택      | DateRangePicker                                    | Core         |
+| 태그 입력           | TagInput                                           | Core         |
+| 색상 선택           | ColorPicker                                        | Core         |
+| 아이콘 선택         | IconPicker                                         | Core         |
+| 데이터 테이블       | DataTable                                          | Shell        |
+| 인라인 편집 테이블  | InlineEditTable                                    | Shell        |
+| 트리/계층 테이블    | TreeTable                                          | Shell        |
+| 칸반 보드           | KanbanBoard                                        | Shell        |
+| 필터 바             | FilterBar                                          | Shell        |
+| 필터 프리셋 저장    | SavedFilters                                       | Shell        |
+| 일괄 작업           | BulkActions                                        | Shell        |
+| 컬럼 표시 토글      | ColumnToggler                                      | Shell        |
+| 시간 범위 선택      | TimeRangeSelector                                  | Shell        |
+| A/B 비교 선택       | ComparisonSelector                                 | Shell        |
+| 선 차트 / 영역 차트 | LineChart / AreaChart                              | Visual       |
+| 막대 차트           | BarChart                                           | Visual       |
+| 파이/도넛 차트      | PieChart                                           | Visual       |
+| 인라인 스파크라인   | Sparkline                                          | Visual       |
+| 흐름 다이어그램     | SankeyChart                                        | Visual       |
+| 퍼널 차트           | FunnelChart                                        | Visual       |
+| 리텐션 히트맵       | RetentionHeatmap                                   | Visual       |
+| 캘린더 히트맵       | CalendarHeatmap                                    | Visual       |
+| 폭포 차트           | WaterfallChart                                     | Visual       |
+| 버블 차트           | BubbleChart                                        | Visual       |
+| 게이지/미터         | GaugeChart                                         | Visual       |
+| KPI/통계 카드       | StatCard (Core) / MetricsCard / SummaryRow (Shell) | Core / Shell |
+| 모달 대화상자       | Dialog                                             | Core         |
+| 확인 대화상자       | ConfirmDialog                                      | Shell        |
+| 서랍 패널           | Drawer                                             | Core         |
+| 팝오버              | Popover                                            | Core         |
+| 드롭다운 메뉴       | DropdownMenu                                       | Core         |
+| 토스트 알림         | NotificationToast                                  | Shell        |
+| 알림 센터           | NotificationCenter                                 | Shell        |
+| 사이드바 내비게이션 | SidebarNav / Sidebar                               | Shell        |
+| 앱 레이아웃         | AppShell                                           | Shell        |
+| 탭 내비게이션       | Tabs (Core) / ContentTabs / VerticalTabs (Shell)   | Core / Shell |
+| 메뉴                | Menu (Core) / AppMenubar / MegaMenu (Shell)        | Core / Shell |
+| 커맨드 팔레트       | CommandPalette                                     | Shell        |
+| 아코디언            | Disclosure (Core) / FaqAccordion (Shell)           | Core / Shell |
+| 설정 폼             | SettingsForm                                       | Shell        |
+| 로그인 폼           | AuthForm                                           | Shell        |
+| 다단계 폼           | WizardForm                                         | Shell        |
+| 동적 필드 폼        | DynamicFieldForm                                   | Shell        |
+| 파일 업로드 폼      | FileUploadForm                                     | Shell        |
+| SQL 에디터          | SqlEditor                                          | Shell        |
+| 코드 표시           | CodeSnippetViewer                                  | Shell        |
+| 코드 비교           | CodeDiffViewer                                     | Shell        |
+| 리치 텍스트 에디터  | RichTextEditor                                     | Shell        |
+| 단계 빌더           | StepBuilder                                        | Core         |
+| 조건 빌더           | ConditionBuilder                                   | Core         |
+| 경로 탐색           | Breadcrumb                                         | Core         |
+| 빈 상태 표시        | EmptyState                                         | Core         |
+| 로딩 스피너         | Spinner / LoadingOverlay                           | Core         |
+| 프로그레스 바       | Progress                                           | Core         |
+| 아바타              | Avatar                                             | Core         |
+| 페이지네이션        | Pagination                                         | Core         |
+| 가상 목록           | VirtualList                                        | Core         |
+| 리사이즈 패널       | Resizable                                          | Core         |
+| 페이지 헤더         | PageHeader                                         | Core         |
+| 테마 전환           | ThemeSwitcher                                      | Shell        |
+| 데이터 내보내기     | ExportButton                                       | Shell        |
+| 데이터 임포트       | DataImportWizard                                   | Shell        |
+| 웹훅 설정           | WebhookConfig                                      | Shell        |
+| 피처 플래그         | FeatureFlagPanel                                   | Shell        |
+| 감사 로그           | AuditLog                                           | Shell        |
+| 워크플로우 에디터   | WorkflowCanvas                                     | Shell        |
+| 인사이트/이상탐지   | InsightsPanel                                      | Shell        |
+| 프롬프트 템플릿     | PromptTemplate                                     | Shell        |
+
+## Per-Layer Reference
+
+- [Core Components](./01-core.md)
+- [Visual Components](./02-visuals.md)
+- [Shell Components](./03-shells.md)
+- [Surface Components](./04-surfaces.md)

package/dist/docs/03-recipes/01-forms.md

@@ -0,0 +1,471 @@
+---
+title: "Form Recipes"
+description: "opt-ui FormStore 기반 폼 패턴 4종"
+related:
+  links:
+    - ../02-components/01-core.md
+    - ../05-migration/02-formstore.md
+---
+
+<!-- AI agent hint: opt-ui 1.2.0부터 useValidate/useSubmit 훅이 제거됨. 반드시 useFormStore({ validate, onSubmit }) 옵션 패턴을 사용할 것. 이전 API는 05-migration/02-formstore.md 참조. -->
+
+# Form Recipes
+
+Copy-paste-ready form patterns using the FormStore API.
+All imports from `@reopt-ai/opt-ui`.
+
+## 1. Basic Settings Form
+
+Standard settings page with text, select, switch, and textarea inputs.
+
+```tsx
+"use client";
+
+import {
+  SurfaceLayout,
+  PageHeader,
+  FormRoot,
+  FormField,
+  FormLabel,
+  FormControl,
+  FormSelect,
+  FormSelectPopover,
+  FormSelectItem,
+  FormSwitch,
+  FormTextarea,
+  FormSubmit,
+  FormDescription,
+  useFormStore,
+} from "@reopt-ai/opt-ui";
+
+interface ProfileValues {
+  displayName: string;
+  language: string;
+  bio: string;
+  emailNotifications: boolean;
+}
+
+export function ProfileSettings() {
+  const form = useFormStore<ProfileValues>({
+    defaultValues: {
+      displayName: "",
+      language: "ko",
+      bio: "",
+      emailNotifications: true,
+    },
+    onSubmit: async (values) => {
+      await fetch("/api/profile", {
+        method: "PUT",
+        body: JSON.stringify(values),
+      });
+    },
+  });
+
+  return (
+    <SurfaceLayout>
+      <PageHeader
+        title="프로필 설정"
+        description="기본 프로필 정보를 수정합니다"
+      />
+
+      <FormRoot store={form}>
+        <FormField name="displayName">
+          <FormLabel>이름</FormLabel>
+          <FormControl name="displayName" placeholder="홍길동" />
+        </FormField>
+
+        <FormField name="language">
+          <FormLabel>언어</FormLabel>
+          <FormSelect name="language" placeholder="언어 선택">
+            <FormSelectPopover>
+              <FormSelectItem value="ko">한국어</FormSelectItem>
+              <FormSelectItem value="en">English</FormSelectItem>
+              <FormSelectItem value="ja">日本語</FormSelectItem>
+            </FormSelectPopover>
+          </FormSelect>
+        </FormField>
+
+        <FormField name="bio">
+          <FormLabel>소개</FormLabel>
+          <FormTextarea name="bio" placeholder="간단한 자기소개" rows={3} />
+        </FormField>
+
+        <FormField name="emailNotifications">
+          <div className="gap-group flex items-center">
+            <FormSwitch name="emailNotifications" />
+            <div>
+              <FormLabel>이메일 알림</FormLabel>
+              <FormDescription>새 소식을 이메일로 받습니다</FormDescription>
+            </div>
+          </div>
+        </FormField>
+
+        <FormSubmit>저장</FormSubmit>
+      </FormRoot>
+    </SurfaceLayout>
+  );
+}
+```
+
+## 2. Form with Validation
+
+Synchronous validation with `validate` option and error display.
+
+```tsx
+"use client";
+
+import {
+  SurfaceLayout,
+  PageHeader,
+  FormRoot,
+  FormField,
+  FormLabel,
+  FormControl,
+  FormError,
+  FormSubmit,
+  FormReset,
+  useFormStore,
+  type FormErrors,
+} from "@reopt-ai/opt-ui";
+
+interface SignupValues {
+  email: string;
+  password: string;
+  passwordConfirm: string;
+}
+
+function validateSignup(values: SignupValues): FormErrors {
+  const errors: FormErrors = {};
+
+  if (!values.email) {
+    errors.email = "이메일을 입력하세요";
+  } else if (!/^[^@]+@[^@]+\.[^@]+$/.test(values.email)) {
+    errors.email = "올바른 이메일 형식이 아닙니다";
+  }
+
+  if (!values.password) {
+    errors.password = "비밀번호를 입력하세요";
+  } else if (values.password.length < 8) {
+    errors.password = "8자 이상 입력하세요";
+  }
+
+  if (values.password !== values.passwordConfirm) {
+    errors.passwordConfirm = "비밀번호가 일치하지 않습니다";
+  }
+
+  return errors;
+}
+
+export function SignupForm() {
+  const form = useFormStore<SignupValues>({
+    defaultValues: { email: "", password: "", passwordConfirm: "" },
+    validate: validateSignup,
+    validateOn: "blur",
+    onSubmit: async (values) => {
+      await fetch("/api/signup", {
+        method: "POST",
+        body: JSON.stringify(values),
+      });
+    },
+  });
+
+  return (
+    <SurfaceLayout>
+      <PageHeader title="회원가입" />
+
+      <FormRoot store={form}>
+        <FormField name="email">
+          <FormLabel>이메일</FormLabel>
+          <FormControl
+            name="email"
+            type="email"
+            placeholder="user@example.com"
+          />
+          <FormError name="email" />
+        </FormField>
+
+        <FormField name="password">
+          <FormLabel>비밀번호</FormLabel>
+          <FormControl name="password" type="password" placeholder="8자 이상" />
+          <FormError name="password" />
+        </FormField>
+
+        <FormField name="passwordConfirm">
+          <FormLabel>비밀번호 확인</FormLabel>
+          <FormControl name="passwordConfirm" type="password" />
+          <FormError name="passwordConfirm" />
+        </FormField>
+
+        <div className="gap-element flex">
+          <FormSubmit>가입</FormSubmit>
+          <FormReset>초기화</FormReset>
+        </div>
+      </FormRoot>
+    </SurfaceLayout>
+  );
+}
+```
+
+## 3. Multi-Step Wizard
+
+Step navigation with FormStore state and per-step validation.
+
+```tsx
+"use client";
+
+import { useState } from "react";
+import {
+  SurfaceLayout,
+  PageHeader,
+  FormRoot,
+  FormField,
+  FormLabel,
+  FormControl,
+  FormSelect,
+  FormSelectPopover,
+  FormSelectItem,
+  FormError,
+  FormSubmit,
+  Button,
+  Progress,
+  useFormStore,
+  type FormErrors,
+} from "@reopt-ai/opt-ui";
+
+interface WizardValues {
+  name: string;
+  email: string;
+  plan: string;
+  cardNumber: string;
+}
+
+const STEPS = ["기본 정보", "플랜 선택", "결제 정보"] as const;
+
+function validateStep(values: WizardValues, step: number): FormErrors {
+  const errors: FormErrors = {};
+  if (step === 0) {
+    if (!values.name) errors.name = "이름을 입력하세요";
+    if (!values.email) errors.email = "이메일을 입력하세요";
+  } else if (step === 1) {
+    if (!values.plan) errors.plan = "플랜을 선택하세요";
+  } else if (step === 2) {
+    if (!values.cardNumber) errors.cardNumber = "카드 번호를 입력하세요";
+  }
+  return errors;
+}
+
+export function OnboardingWizard() {
+  const [step, setStep] = useState(0);
+
+  const form = useFormStore<WizardValues>({
+    defaultValues: { name: "", email: "", plan: "", cardNumber: "" },
+    onSubmit: async (values) => {
+      await fetch("/api/onboarding", {
+        method: "POST",
+        body: JSON.stringify(values),
+      });
+    },
+  });
+
+  const handleNext = () => {
+    const values = form.getValues() as WizardValues;
+    const errors = validateStep(values, step);
+    Object.entries(errors).forEach(([k, v]) => {
+      if (v) form.setError(k, v);
+    });
+    if (Object.values(errors).some(Boolean)) return;
+    setStep((s) => Math.min(s + 1, STEPS.length - 1));
+  };
+
+  const progress = ((step + 1) / STEPS.length) * 100;
+
+  return (
+    <SurfaceLayout>
+      <PageHeader title="온보딩" description={STEPS[step]} />
+      <Progress value={progress} aria-label="온보딩 진행률" />
+
+      <FormRoot store={form}>
+        {step === 0 && (
+          <div className="gap-group flex flex-col">
+            <FormField name="name">
+              <FormLabel>이름</FormLabel>
+              <FormControl name="name" placeholder="홍길동" />
+              <FormError name="name" />
+            </FormField>
+            <FormField name="email">
+              <FormLabel>이메일</FormLabel>
+              <FormControl name="email" type="email" />
+              <FormError name="email" />
+            </FormField>
+          </div>
+        )}
+
+        {step === 1 && (
+          <FormField name="plan">
+            <FormLabel>플랜</FormLabel>
+            <FormSelect name="plan" placeholder="플랜 선택">
+              <FormSelectPopover>
+                <FormSelectItem value="free">Free</FormSelectItem>
+                <FormSelectItem value="pro">Pro</FormSelectItem>
+                <FormSelectItem value="enterprise">Enterprise</FormSelectItem>
+              </FormSelectPopover>
+            </FormSelect>
+            <FormError name="plan" />
+          </FormField>
+        )}
+
+        {step === 2 && (
+          <FormField name="cardNumber">
+            <FormLabel>카드 번호</FormLabel>
+            <FormControl name="cardNumber" placeholder="1234-5678-9012-3456" />
+            <FormError name="cardNumber" />
+          </FormField>
+        )}
+
+        <div className="gap-element flex">
+          {step > 0 && (
+            <Button variant="secondary" onClick={() => setStep((s) => s - 1)}>
+              이전
+            </Button>
+          )}
+          {step < STEPS.length - 1 ? (
+            <Button onClick={handleNext}>다음</Button>
+          ) : (
+            <FormSubmit>완료</FormSubmit>
+          )}
+        </div>
+      </FormRoot>
+    </SurfaceLayout>
+  );
+}
+```
+
+## 4. Dynamic Fields
+
+Add and remove array items with FormPush and FormRemove.
+
+```tsx
+"use client";
+
+import {
+  SurfaceLayout,
+  PageHeader,
+  FormRoot,
+  FormField,
+  FormLabel,
+  FormControl,
+  FormPush,
+  FormRemove,
+  FormError,
+  FormSubmit,
+  useFormStore,
+  useFieldValue,
+  type FormErrors,
+} from "@reopt-ai/opt-ui";
+
+interface EnvItem {
+  key: string;
+  value: string;
+}
+
+interface EnvFormValues {
+  projectName: string;
+  envVars: EnvItem[];
+}
+
+function validateEnv(values: EnvFormValues): FormErrors {
+  const errors: FormErrors = {};
+  if (!values.projectName) errors.projectName = "프로젝트 이름 필수";
+  values.envVars.forEach((item, i) => {
+    if (!item.key) errors[`envVars.${i}.key`] = "키 필수";
+    if (!item.value) errors[`envVars.${i}.value`] = "값 필수";
+  });
+  return errors;
+}
+
+function EnvVarRows({ form }: { form: ReturnType<typeof useFormStore> }) {
+  const envVars = (useFieldValue(form, "envVars") as EnvItem[]) ?? [];
+
+  return (
+    <div className="gap-group flex flex-col">
+      {envVars.map((_, index) => (
+        <div key={index} className="gap-element flex items-end">
+          <FormField name={`envVars.${index}.key`} className="flex-1">
+            <FormLabel>Key</FormLabel>
+            <FormControl name={`envVars.${index}.key`} placeholder="API_KEY" />
+            <FormError name={`envVars.${index}.key`} />
+          </FormField>
+
+          <FormField name={`envVars.${index}.value`} className="flex-1">
+            <FormLabel>Value</FormLabel>
+            <FormControl name={`envVars.${index}.value`} placeholder="sk-..." />
+            <FormError name={`envVars.${index}.value`} />
+          </FormField>
+
+          <FormRemove name="envVars" index={index}>
+            삭제
+          </FormRemove>
+        </div>
+      ))}
+
+      <FormPush name="envVars" value={{ key: "", value: "" }}>
+        + 환경변수 추가
+      </FormPush>
+    </div>
+  );
+}
+
+export function EnvVarEditor() {
+  const form = useFormStore<EnvFormValues>({
+    defaultValues: {
+      projectName: "",
+      envVars: [{ key: "", value: "" }],
+    },
+    validate: validateEnv,
+    onSubmit: async (values) => {
+      await fetch("/api/env", {
+        method: "POST",
+        body: JSON.stringify(values),
+      });
+    },
+  });
+
+  return (
+    <SurfaceLayout>
+      <PageHeader
+        title="환경변수 설정"
+        description="프로젝트 환경변수를 관리합니다"
+      />
+
+      <FormRoot store={form}>
+        <FormField name="projectName">
+          <FormLabel>프로젝트 이름</FormLabel>
+          <FormControl name="projectName" placeholder="my-app" />
+          <FormError name="projectName" />
+        </FormField>
+
+        <EnvVarRows form={form} />
+
+        <FormSubmit>저장</FormSubmit>
+      </FormRoot>
+    </SurfaceLayout>
+  );
+}
+```
+
+## Key API Notes
+
+| API                               | Purpose                                                                |
+| --------------------------------- | ---------------------------------------------------------------------- |
+| `useFormStore<V>(options)`        | Create a typed form store with `defaultValues`, `validate`, `onSubmit` |
+| `validate` option                 | `(values: V) => FormErrors` — return `{}` for no errors                |
+| `validateOn`                      | `"change"` (default) \| `"blur"` \| `"submit"`                         |
+| `FormRoot store={form}`           | Binds store and wraps with FormProvider automatically                  |
+| `FormField name="x"`              | Field wrapper (adds `gap-element` spacing)                             |
+| `FormControl name="x"`            | Text input bound to store                                              |
+| `FormError name="x"`              | Shows validation error for field                                       |
+| `FormPush name="arr" value={v}`   | Append item to array field                                             |
+| `FormRemove name="arr" index={i}` | Remove item from array field                                           |
+| `useFieldValue(form, name)`       | Subscribe to a single field value                                      |
+| `form.isDirty()`                  | Check if any field changed from defaults                               |
+| `form.isSubmitting()`             | True while async `onSubmit` is running                                 |