@reopt-ai/opt-ui 1.4.1

package/dist/docs/05-migration/01-breaking-changes.md

@@ -0,0 +1,117 @@
+---
+title: "Breaking Changes"
+description: "opt-ui 버전별 Breaking/Deprecated 변경사항 레지스트리"
+---
+
+# Breaking Changes Registry
+
+버전별 Breaking/Deprecated 변경사항 레지스트리.
+
+## Registry Format
+
+각 변경은 다음 필드를 포함:
+
+```yaml
+- version: "X.Y.Z" # 변경이 포함된 버전
+  level: B | D | A | F # 분류 (Breaking, Deprecated, Added, Fixed)
+  component: "Component" # 영향받는 컴포넌트
+  change: "변경 요약"
+  scan: "grep 패턴" # 영향 스캔용 패턴
+  fix:
+    type: rename | retype | restructure | manual
+    from: "기존 패턴"
+    to: "새 패턴"
+```
+
+---
+
+## Version 1.2.0
+
+### Breaking
+
+- version: "1.2.0"
+  level: B
+  component: "ToolbarRoot"
+  change: "focusLoop prop 제거"
+  detail: "ToolbarRoot에서 focusLoop prop이 제거됨. 자동 포커스 루프 동작으로 변경"
+  scan: "focusLoop"
+  fix:
+  type: rename
+  from: "<ToolbarRoot focusLoop>"
+  to: "<ToolbarRoot>"
+
+- version: "1.2.0"
+  level: B
+  component: "DropdownContent"
+  change: "gutter prop 제거 (MenuPopoverProps 변경)"
+  detail: "DropdownContent(MenuPopover)에서 gutter prop이 제거됨"
+  scan: "gutter="
+  fix:
+  type: rename
+  from: '<DropdownContent gutter={4}>'
+  to: "<DropdownContent>"
+
+- version: "1.2.0"
+  level: B
+  component: "FormStore"
+  change: "useValidate/useSubmit 메서드 제거 -> useFormStore 옵션으로 이동"
+  detail: "form.useValidate(callback)과 form.useSubmit(callback)이 제거됨. useFormStore({ validate, onSubmit, validateOn }) 옵션으로 전달. validateOn 기본값이 change로 변경됨 -- 기존 useValidate는 submit 시에만 실행되었으므로 반드시 validateOn: 'submit' 명시 필요."
+  scan: "useValidate\\|useSubmit"
+  fix:
+  type: restructure
+  from: "form.useValidate(() => { ... }); form.useSubmit(() => { ... })"
+  to: "useFormStore({ validateOn: 'submit', validate: (values) => errors, onSubmit: (values) => { ... } })"
+
+- version: "1.2.0"
+  level: B
+  component: "TabsRoot"
+  change: "setSelectedId 콜백 타입 string|null -> string|undefined"
+  detail: "TabsRoot의 selectedId/setSelectedId가 null 대신 undefined 사용"
+  scan: "setSelectedId.\*null"
+  fix:
+  type: retype
+  from: "useState<string | null>"
+  to: "useState<string | undefined>"
+
+---
+
+## Version 1.1.1
+
+초기 릴리즈 이후 Breaking Change 없음 (Added만).
+
+### Added
+
+- version: "1.1.1"
+  level: A
+  component: ChatSidebar
+  change: "새 Shell -- AI 채팅 사이드바"
+
+- version: "1.1.1"
+  level: A
+  component: ChatInput
+  change: "새 Shell -- 채팅 입력 (자동 리사이즈, 모델/스타일 Select)"
+
+- version: "1.1.1"
+  level: A
+  component: ChatMessageList
+  change: "새 Shell -- 채팅 메시지 목록 (말풍선, 타이핑 인디케이터)"
+
+- version: "1.1.1"
+  level: A
+  component: ChatAssistant
+  change: "새 Surface -- AI 챗봇 어시스턴트 (ChatSidebar + ChatMessageList + ChatInput)"
+
+---
+
+## Scan Pattern Guide
+
+영향 분석에 사용할 grep 패턴 작성 규칙:
+
+| 변경 유형       | 스캔 패턴 예시                                               |
+| --------------- | ------------------------------------------------------------ |
+| Prop rename     | `propName.*=` 또는 `<Component[^>]*propName=`                |
+| Prop 값 변경    | `propName.*=.*["']oldValue["']`                              |
+| 컴포넌트 rename | `from ["']@reopt-ai/opt-ui["']` 후 import 이름 확인          |
+| 컴포넌트 삭제   | `import.*{[^}]*OldName[^}]*}.*from ["']@reopt-ai/opt-ui["']` |
+| CSS 토큰 변경   | `className.*oldToken`                                        |
+| 타입 변경       | `import type.*{[^}]*OldType[^}]*}`                           |

package/dist/docs/05-migration/02-formstore.md

@@ -0,0 +1,336 @@
+---
+title: "FormStore Migration"
+description: "opt-ui FormStore 마이그레이션 가이드 (1.1.x -> 1.2.0) — useValidate/useSubmit 제거, 제네릭 타입, 선언적 검증"
+related:
+  links:
+    - ../03-recipes/01-forms.md
+    - 01-breaking-changes.md
+---
+
+<!-- AI agent hint: useValidate(), useSubmit()를 발견하면 반드시 이 문서의 BEFORE/AFTER 패턴을 따라 useFormStore 옵션으로 변환할 것. as never 캐스트도 제거 대상. -->
+
+# FormStore Migration Guide (1.1.x -> 1.2.0)
+
+## Overview
+
+opt-ui 1.2.0 replaces the Ariakit-based form system with a self-contained `FormStore`.
+The new store is built on `useSyncExternalStore` with zero external dependencies,
+providing generic type inference, dirty tracking, async submit lifecycle,
+and pluggable schema validation.
+
+**Why the change:**
+
+- Ariakit's `useFormStore` returned an opaque store requiring `as never` casts for typed access.
+- `useValidate` / `useSubmit` were separate hooks that fragmented form logic across the component.
+- No built-in dirty tracking, async submit state, or schema adapter.
+- The new API consolidates everything into a single `useFormStore<V>(options)` call.
+
+---
+
+## Breaking Changes
+
+### 1. useValidate / useSubmit -> useFormStore options
+
+The two standalone hooks are removed. Pass `validate` and `onSubmit` directly to `useFormStore`.
+
+**BEFORE (1.1.x):**
+
+```tsx
+import { useFormStore, useValidate, useSubmit } from "@reopt-ai/opt-ui";
+
+function SettingsForm() {
+  const form = useFormStore({
+    defaultValues: { name: "", email: "" },
+  });
+
+  form.useValidate(() => {
+    if (!form.getValue("name")) {
+      form.setError("name", "Name is required");
+    }
+  });
+
+  form.useSubmit(() => {
+    console.log("Submitted:", form.getValues());
+  });
+
+  return <FormRoot store={form}>...</FormRoot>;
+}
+```
+
+**AFTER (1.2.0):**
+
+```tsx
+import { useFormStore, type FormErrors } from "@reopt-ai/opt-ui";
+
+function SettingsForm() {
+  const form = useFormStore({
+    defaultValues: { name: "", email: "" },
+    validate: (values) => {
+      const errors: FormErrors = {};
+      if (!values.name) errors.name = "Name is required";
+      return errors;
+    },
+    onSubmit: (values) => {
+      console.log("Submitted:", values);
+    },
+  });
+
+  return <FormRoot store={form}>...</FormRoot>;
+}
+```
+
+| Aspect        | 1.1.x                                        | 1.2.0                                    |
+| ------------- | -------------------------------------------- | ---------------------------------------- |
+| Validation    | `form.useValidate(callback)` hook            | `validate` option in `useFormStore`      |
+| Submit        | `form.useSubmit(callback)` hook              | `onSubmit` option in `useFormStore`      |
+| Error setting | Imperative `form.setError()` inside validate | Return `FormErrors` object from validate |
+| Location      | Scattered across component body              | Colocated in store config                |
+
+---
+
+### 2. Generic FormStore type
+
+**BEFORE (1.1.x):**
+
+```tsx
+const form = useFormStore({
+  defaultValues: { name: "", count: 0 },
+});
+
+const name = form.getValue(form.names.name) as string;
+form.setValue(form.names.count, 5 as never);
+```
+
+**AFTER (1.2.0):**
+
+```tsx
+interface MyFormValues {
+  name: string;
+  count: number;
+}
+
+const form = useFormStore<MyFormValues>({
+  defaultValues: { name: "", count: 0 },
+});
+
+const name = form.getValue("name"); // type: string
+form.setValue("count", 5); // type-checked
+```
+
+The generic parameter `V` flows through `defaultValues`, `validate`, `onSubmit`, `getValue`, and `setValue`.
+
+---
+
+### 3. validate function signature
+
+The validate function no longer mutates the store imperatively. Instead, it returns an errors object.
+
+**BEFORE (1.1.x):**
+
+```tsx
+form.useValidate(() => {
+  if (!form.getValue(form.names.email)) {
+    form.setError(form.names.email, "Required");
+  }
+});
+```
+
+**AFTER (1.2.0):**
+
+```tsx
+const form = useFormStore({
+  defaultValues: { email: "", age: 0 },
+  validate: (values) => {
+    const errors: FormErrors = {};
+    if (!values.email) errors.email = "Required";
+    if (!values.age) errors.age = "Required";
+    return errors;
+  },
+});
+```
+
+Rules:
+
+- Return `FormErrors` (`Partial<Record<string, string>>`) from `validate`.
+- Return `{}` or `undefined` for no errors.
+- Keys support dot-paths for nested fields: `"items.0.name"`.
+
+---
+
+### 4. async onSubmit
+
+**BEFORE (1.1.x):**
+
+```tsx
+const [loading, setLoading] = useState(false);
+const [error, setError] = useState<Error | null>(null);
+
+form.useSubmit(async () => {
+  setLoading(true);
+  setError(null);
+  try {
+    await api.save(form.getValues());
+  } catch (e) {
+    setError(e as Error);
+  } finally {
+    setLoading(false);
+  }
+});
+```
+
+**AFTER (1.2.0):**
+
+```tsx
+const form = useFormStore({
+  defaultValues: { name: "" },
+  onSubmit: async (values) => {
+    await api.save(values); // throw on failure
+  },
+});
+
+form.isSubmitting(); // true while Promise is pending
+form.getSubmitError(); // Error object if rejected
+```
+
+No manual `useState` for loading or error. The store handles the full async lifecycle.
+
+---
+
+## New APIs (Additive)
+
+These APIs are new in 1.2.0. Adopt when ready.
+
+### isDirty / isFieldDirty
+
+```tsx
+form.isDirty(); // true if any field differs from defaultValues
+form.isFieldDirty("email"); // true if "email" differs from its default
+```
+
+### resetField
+
+```tsx
+form.resetField("email"); // Reset single field to default, clear its error
+```
+
+### validateOn option
+
+```tsx
+const form = useFormStore({
+  defaultValues: { name: "" },
+  validateOn: "blur",    // "change" (default) | "blur" | "submit"
+  validate: (values) => { ... },
+});
+```
+
+| Value      | Behavior                                                        |
+| ---------- | --------------------------------------------------------------- |
+| `"change"` | Validate on every `setValue` call (default, immediate feedback) |
+| `"blur"`   | Validate when `setFieldTouched(name, true)` is called           |
+| `"submit"` | Validate only on `submit()` call (least intrusive)              |
+
+### schemaValidator adapter
+
+```tsx
+import { useFormStore, schemaValidator } from "@reopt-ai/opt-ui";
+import { z } from "zod";
+
+const schema = z.object({
+  email: z.string().email("Enter a valid email"),
+  age: z.number().min(1, "Age is required"),
+});
+
+const form = useFormStore({
+  defaultValues: { email: "", age: 0 },
+  validate: schemaValidator(schema),
+});
+```
+
+Works with any library exposing a `safeParse` method (Zod, Valibot, etc.).
+
+### useFieldValue hook
+
+```tsx
+import { useFieldValue } from "@reopt-ai/opt-ui";
+
+function EmailPreview({ form }) {
+  const email = useFieldValue<string>(form, "email");
+  return <p>Preview: {email}</p>;
+}
+```
+
+Re-renders only when that specific field changes.
+
+### FormProvider + useFormContext
+
+```tsx
+import { FormProvider, useFormContext, useFormStore } from "@reopt-ai/opt-ui";
+
+function MyForm() {
+  const form = useFormStore({ defaultValues: { name: "" } });
+  return (
+    <FormProvider store={form}>
+      <NameField />
+    </FormProvider>
+  );
+}
+
+function NameField() {
+  const form = useFormContext();
+  const name = useFieldValue<string>(form!, "name");
+  return (
+    <input
+      value={name}
+      onChange={(e) => form!.setValue("name", e.target.value)}
+    />
+  );
+}
+```
+
+`FormRoot` also wraps children with `FormProvider` automatically.
+
+---
+
+## Migration Checklist
+
+### Step 1: Identify affected files
+
+```bash
+grep -rn "\.useValidate\|\.useSubmit" --include="*.tsx" --include="*.ts" .
+grep -rn "as never" --include="*.tsx" --include="*.ts" . | grep -v node_modules
+grep -rn "form\.names\." --include="*.tsx" --include="*.ts" . | grep -v node_modules
+```
+
+### Step 2: Replace useValidate
+
+1. Extract the validation logic from the callback body.
+2. Convert imperative `form.setError()` calls to a returned `FormErrors` object.
+3. Move the logic to the `validate` option in `useFormStore()`.
+4. Remove the `form.useValidate(...)` call.
+
+### Step 3: Replace useSubmit
+
+1. Move the callback to the `onSubmit` option in `useFormStore()`.
+2. Replace `form.getValues()` with the `values` parameter.
+3. If async, remove manual `loading`/`error` state -- use `form.isSubmitting()` and `form.getSubmitError()`.
+4. Remove the `form.useSubmit(...)` call.
+
+### Step 4: Remove `as never` casts
+
+1. Add a type parameter to `useFormStore<MyValues>(...)`.
+2. Replace `form.getValue(form.names.fieldName)` with `form.getValue("fieldName")`.
+3. Remove `as never` from `form.setValue(...)` calls.
+
+### Step 5: Update imports
+
+```diff
+- import { useFormStore, useValidate, useSubmit } from "@reopt-ai/opt-ui";
++ import { useFormStore, type FormErrors } from "@reopt-ai/opt-ui";
+```
+
+### Step 6: Verify
+
+```bash
+npx tsc --noEmit
+bun vitest run
+```

package/dist/docs/06-troubleshooting.md

@@ -0,0 +1,119 @@
+---
+title: "Troubleshooting"
+description: "opt-ui 설치, 스타일, 테마, 빌드, CLI 관련 일반적인 문제와 해결 방법"
+related:
+  links:
+    - 01-getting-started.md
+    - 04-theming.md
+---
+
+# Troubleshooting
+
+## 1. Install Fails With 404
+
+패키지 이름, 버전 또는 프로젝트의 registry override를 확인합니다.
+
+확인 사항:
+
+1. 패키지 이름이 `@reopt-ai/opt-ui`인지 확인
+2. 요청한 버전이 npm에 공개되었는지 확인
+3. `.npmrc`에서 `@reopt-ai` scope를 사설 registry로 덮어쓰지 않는지 확인
+
+```bash
+npm view @reopt-ai/opt-ui version
+```
+
+## 2. Components Render Unstyled
+
+다음 중 하나가 누락된 경우입니다:
+
+- `@import "@reopt-ai/opt-ui/tailwind.css";`
+- 올바른 `@source` 경로
+- Tailwind CSS 자체
+
+Tailwind v4 패턴:
+
+```css
+@import "tailwindcss";
+@import "@reopt-ai/opt-ui/tailwind.css";
+@source "../node_modules/@reopt-ai/opt-ui/dist";
+```
+
+`@source` 경로는 CSS 파일 위치 기준 상대 경로입니다.
+
+## 3. Theme Does Not Switch Or `useOptTheme` Throws
+
+`OptThemeProvider`가 누락된 경우입니다.
+
+```tsx
+import { OptThemeProvider } from "@reopt-ai/opt-ui";
+
+<OptThemeProvider defaultPreset="default">{children}</OptThemeProvider>;
+```
+
+## 4. Next.js Build Problems
+
+Next.js에서 패키지 처리에 문제가 있으면 추가합니다:
+
+```ts
+const nextConfig = {
+  transpilePackages: ["@reopt-ai/opt-ui"],
+};
+
+export default nextConfig;
+```
+
+React 19과 최신 Next.js 버전도 확인합니다.
+
+## 5. Surface CLI Issues
+
+진단 시작:
+
+```bash
+npx @reopt-ai/opt-cli surface info
+npx @reopt-ai/opt-cli surface doctor
+```
+
+일반적인 원인:
+
+- `opt-ui.json` 없음
+- 잘못된 slug
+- global CSS import 누락
+- alias 불일치
+- 설치 후 대규모 로컬 수정
+
+자동 수정 시도:
+
+```bash
+npx @reopt-ai/opt-cli surface doctor --fix
+```
+
+## 6. Tailwind v3 Project
+
+Tailwind v3에서는 `@source` 대신 `content` 설정을 사용합니다:
+
+```ts
+// tailwind.config.ts
+content: [
+  // ... your paths
+  "./node_modules/@reopt-ai/opt-ui/dist/**/*.{js,mjs}",
+];
+```
+
+가능하면 v4로 업그레이드하는 것을 권장합니다.
+
+## 7. Common CSS Variable Issues
+
+스타일이 부분적으로만 적용되는 경우:
+
+- `[data-theme]` 속성이 `<html>` 또는 루트 요소에 설정되어 있는지 확인
+- `OptThemeProvider`가 렌더 트리의 최상단에 있는지 확인
+- 커스텀 프리셋 사용 시 모든 필수 CSS 변수가 정의되어 있는지 확인
+
+## 8. Dark Mode Not Working
+
+다크 모드는 `[data-theme="preset-dark"]` 셀렉터로 동작합니다:
+
+- `OptThemeProvider`의 mode가 `"dark"`으로 설정되어 있는지 확인
+- `@reopt-ai/opt-ui/tailwind.css`가 import되어 있는지 확인 (dark variant 정의 포함)
+- Tailwind `dark:` 클래스가 자동으로 동작합니다 (`@custom-variant dark` 포함)

package/dist/docs/index.md

@@ -0,0 +1,71 @@
+---
+title: "@reopt-ai/opt-ui Documentation"
+description: "opt-ui 디자인 시스템 패키지 문서 — Core/Shells/Surfaces 아키텍처, 설치, 레시피, 테마, 마이그레이션 가이드"
+related:
+  title: Start here
+  links:
+    - 01-getting-started.md
+    - 02-components/index.md
+    - 03-recipes/01-forms.md
+---
+
+<!-- AI agent hint: This is @reopt-ai/opt-ui documentation shipped with the package. Component API reference is in 02-components/ (auto-generated). For copy-paste recipes, see 03-recipes/. For version migration, see 05-migration/. For theming, see 04-theming.md. -->
+
+# @reopt-ai/opt-ui
+
+React 디자인 시스템 라이브러리. opt-ui-primitives 기반의 접근성 우선 컴포넌트, 비즈니스 로직 조합 Shell, 페이지 단위 Surface 템플릿을 제공합니다. 차트와 데이터 시각화는 `@reopt-ai/opt-charts` 패키지에서 제공합니다.
+
+## Architecture
+
+opt-ui는 Core/Shells/Surfaces 레이어를 소유하고, 차트는 opt-charts가 소유합니다.
+
+| Layer        | Role                                  | Count   |
+| ------------ | ------------------------------------- | ------- |
+| **Core**     | opt-ui-primitives 기반, 단일 책임     | 55      |
+| **Visuals**  | `@reopt-ai/opt-charts` 호환 re-export | 0 local |
+| **Shells**   | Core 조합 + 비즈니스 로직             | 79      |
+| **Surfaces** | Shells 조합, 페이지 템플릿 (CLI)      | 7       |
+
+- **Core**: Button, Input, Form, Dialog, Tabs, Select, Checkbox, RadioGroup 등 기본 UI
+- **Visuals**: LineChart, BarChart, PieChart, GaugeChart, SankeyChart 등 차트는 `@reopt-ai/opt-charts`에서 직접 import
+- **Shells**: DataTable, FilterBar, SettingsForm, CommandPalette, KanbanBoard 등 비즈니스 UI
+- **Surfaces**: 완성된 페이지 템플릿 (`npx @reopt-ai/opt-cli surface add <slug>`로 프로젝트에 복사)
+
+## Quick Install
+
+```bash
+bun add @reopt-ai/opt-ui @reopt-ai/opt-ui-primitives
+```
+
+공개 npm registry에서 별도 인증 없이 설치할 수 있습니다. 상세 설치 가이드는 [01-getting-started.md](./01-getting-started.md)를 참고하세요.
+
+## Docs Structure
+
+```
+docs/
+  index.md                      # 이 파일 — 개요 및 구조 안내
+  01-getting-started.md          # 설치, Next.js 설정, Tailwind 연동
+  02-components/                 # 컴포넌트 API 레퍼런스 (auto-generated)
+  03-recipes/
+    01-forms.md                  # FormStore 기반 폼 패턴 4종
+    02-dashboards.md             # 대시보드 조합 패턴 3종
+    03-layouts.md                # 레이아웃 조합 패턴 3종
+  04-theming.md                  # 5개 프리셋, CSS 변수, 커스텀 테마
+  05-migration/
+    01-breaking-changes.md       # 버전별 Breaking Change 레지스트리
+    02-formstore.md              # FormStore 마이그레이션 (1.1.x → 1.2.0)
+  06-troubleshooting.md          # 설치/스타일/테마/빌드 문제 해결
+```
+
+## Test Coverage Audit
+
+`bun run test`는 Vitest 이후 `scripts/validate-test-coverage.ts`를 실행합니다.
+이 감사는 opt-ui ComponentMeta 항목이 모두 `testDescribe`를 갖고, 같은 이름의
+`describe(...)` 블록이 테스트 파일에 존재하는지 확인합니다.
+
+## Key Dependencies
+
+- React 19+
+- Tailwind CSS v4
+- `@reopt-ai/opt-ui-primitives` (WAI-ARIA 패턴)
+- `@reopt-ai/opt-charts` (차트/데이터 시각화)