@zeroman.yang/react-auto-components 0.1.0

package/docs/i18n/ko/README.md

@@ -0,0 +1,203 @@
+# React Auto Components
+
+[English](../../../README.md) | [简体中文](../zh-CN/README.md) | [繁體中文](../zh-TW/README.md) | [日本語](../ja/README.md) | **한국어** | [Español](../es/README.md) | [Français](../fr/README.md) | [Deutsch](../de/README.md) | [Português (Brasil)](../pt-BR/README.md) | [Русский](../ru/README.md)
+
+React 19를 위한 독립형 스키마 기반 컴포넌트 라이브러리로, 폼·표·채팅을 다룹니다. TypeScript, TanStack Table 9 / Form / Virtual, Radix, Floating UI로 구축되었으며 Ant Design, Element Plus, MUI는 사용하지 않습니다. 라이브러리 빌드에는 React Compiler를 사용합니다.
+
+[![Auto Studio 데모 미리보기](../../assets/demo.png)](https://zeroman.github.io/react-auto-components/)
+
+<p align="center">
+  <a href="https://zeroman.github.io/react-auto-components/"><strong>🚀 온라인 데모 (GitHub Pages)</strong></a> · <a href="#독립형-테스트-프로젝트-실행">로컬 실행</a> · <a href="#컴포넌트">컴포넌트</a>
+</p>
+
+## 프로젝트 상태
+
+현재 버전은 0.1.0이며 API는 아직 변경될 수 있습니다. React 19이 필요합니다. 이 패키지는 ESM 및 TypeScript 선언을 제공합니다. 내장 인터페이스 텍스트는 기본적으로 중국어이며 AutoConfigProvider.config.t를 통해 번역할 수 있습니다.
+
+`pnpm add @zeroman.yang/react-auto-components`로 설치합니다(npm과 yarn도 동일). peer dependency는 React 19와 react-dom 19입니다. 진입점에서 스타일시트를 한 번 불러오세요: `import "@zeroman.yang/react-auto-components/style.css"`.
+
+- [온라인 데모 (GitHub Pages)](https://zeroman.github.io/react-auto-components/)
+- [기여 안내](https://github.com/Zeroman/react-auto-components/blob/main/docs/i18n/ko/CONTRIBUTING.md)
+- [변경 기록](https://github.com/Zeroman/react-auto-components/blob/main/docs/i18n/ko/CHANGELOG.md)
+- [계정 설정 및 게시](https://github.com/Zeroman/react-auto-components/blob/main/docs/i18n/ko/publishing.md)
+- [MIT 라이선스](../../../LICENSE)
+
+## 독립형 테스트 프로젝트 실행
+
+Node.js >= 22.12와 pnpm 12.5가 필요합니다.
+
+```sh
+pnpm install --frozen-lockfile
+pnpm prepare:test-project
+pnpm --dir test-project dev
+```
+
+http://127.0.0.1:4173 을 엽니다. 테스트 프로젝트에는 7개 컴포넌트 모두의 페이지, 로컬/서버 측/10,000행/트리 테이블, CRUD, 제출 실패 후 재시도, 초안, 중첩 탭, 동적 행 높이 예제가 포함됩니다.
+
+데모는 브라우저 언어를 자동으로 감지하며, 기본값으로 영어를 사용합니다. 헤더 또는 전역 설정(Global settings)에서 언어를 선택할 수 있으며, 선택한 언어는 새로고침 후에도 유지됩니다. Auto를 선택하면 다시 브라우저 언어를 따릅니다. 10개 언어가 지원됩니다. 페이지는 뷰포트를 채우며, 표와 긴 패널은 각자의 영역 내부에서 스크롤됩니다.
+
+모든 예제 페이지에는 **코드 보기** 버튼이 있으며, 대화상자에서 실제 소스 파일을 엽니다. 파일 전환, 원클릭 복사, GitHub 링크를 지원합니다.
+
+`test-project`에는 자체 package.json과 잠금 파일이 있습니다. 소스 별칭 없이 `pnpm pack`의 실제 결과물을 설치합니다. 라이브러리를 변경한 후에는 `pnpm prepare:test-project`를 다시 실행하세요. 스크립트는 콘텐츠 해시가 포함된 파일 이름을 사용하여 오래된 tarball 캐시를 방지합니다.
+
+## 사용법
+
+```tsx
+import { useState } from 'react';
+import {
+  AutoConfigProvider, AutoDialogProvider, AutoTable,
+  type AutoColumn, type Field,
+} from '@zeroman.yang/react-auto-components';
+import '@zeroman.yang/react-auto-components/style.css';
+
+type Person = { id: number; name: string; enabled: boolean };
+const columns: AutoColumn<Person>[] = [
+  { key: 'name', label: '이름', sortable: true },
+  { key: 'enabled', label: '활성화됨', options: [
+    { label: '예', value: true }, { label: '아니요', value: false },
+  ] },
+];
+const fields: Field<Person>[] = [
+  { name: 'name', label: '이름', required: true },
+  { name: 'enabled', label: '활성화됨', type: 'switch', defaultValue: true },
+];
+export function App() {
+  const [rows, setRows] = useState<Person[]>([]);
+  return <AutoConfigProvider config={{ namespace: 'my-app' }}>
+    <AutoDialogProvider>
+      <AutoTable<Person> id="people" rowKey="id" data={rows}
+        columns={columns} formFields={fields} searchFields={fields}
+        onAdd={value => setRows(old => [...old, { ...value, id: Date.now() }])}
+        onEdit={(row, value) => setRows(old => old.map(item => item.id === row.id ? { ...row, ...value } : item))}
+        onDelete={selected => setRows(old => old.filter(item => !selected.some(row => row.id === item.id)))}
+      />
+    </AutoDialogProvider>
+  </AutoConfigProvider>;
+}
+```
+
+필드, 열, ref는 제네릭을 사용하므로 잘못된 필드 이름이나 기본값은 컴파일 시 오류를 발생시킵니다. 프로바이더는 네임스페이스, 권한, 필드 레이블 번역, 사용자 정의 필드, 알림, 영속화 어댑터를 지원합니다. 내장 레이블, 유효성 검사 메시지, 접근성 텍스트는 AutoConfigProvider.config.t를 사용하며, 명시적으로 지정된 컴포넌트 레이블이 우선합니다.
+
+t 콜백은 메시지 키와 폴백을 받습니다. 번역된 내장 메시지에서 {0}, {1}과 같은 번호가 매겨진 플레이스홀더는 그대로 유지해야 하며, 컴포넌트가 번역 후 값을 치환합니다.
+
+## 컴포넌트
+
+| 컴포넌트 | 기능 |
+| --- | --- |
+| AutoForm | 네이티브 필드 유형, 옵션 가상화, 계층형 선택, 업로드 어댑터, 사용자 정의 렌더링, 종속 필드, 조건부 표시, 비동기 유효성 검사, 제어 상태, 실패 후 입력 유지 |
+| AutoSearchPanel | 기본/고급 조건, 수동/즉시 검색, 초기화, 정렬 태그, 공유 쿼리 AST, RSQL 직렬화 |
+| AutoTable | 로컬/원격 데이터, 다중 열 정렬, 열 필터, 페이지 나누기, 안정적인 선택 상태, 가상화, 트리/상세 펼치기, 집계, 셀 병합, CRUD, 컨텍스트 메뉴, 복사 |
+| AutoDialog | 선언형/명령형 API, 격리된 프로바이더, 초안, 닫기 가드, 포커스 관리, 드래그, 전체 화면, 비동기 제출 |
+| AutoTabs | 가로/세로 레이아웃, 중첩, 권한, 탭 비활성화, 패널 상태 유지, 새로 고침 |
+| AutoMenu | 아이콘, 설명, 배지, 중첩 그룹, 권한, 접히는 아이콘 레일을 갖춘 사이드바 내비게이션 |
+| AutoChat | 호출부 정의 메시지 렌더링, 선택적 가상화, 스트리밍 따르기, 앵커 기반 이력 로딩, 전송/정지 입력창, 사용자 지정 액션 |
+
+테이블 레이아웃, 정렬, 필터링, 내보내기는 각각 이름이 있는 프리셋과 독립적인 버전을 지원합니다. 영속화는 기본적으로 localStorage를 사용하며 원격 어댑터를 주입할 수 있습니다. JSON/CSV 내보내기는 기본 제공됩니다. XLSX는 별도의 선택적 어댑터를 사용합니다.
+
+```tsx
+import { exportXlsx } from '@zeroman.yang/react-auto-components/xlsx';
+// <AutoTable ... exportXlsx={exportXlsx} />
+```
+
+ExcelJS는 어댑터를 처음 사용할 때 동적으로 로드되며 라이브러리의 기본 진입점에서 제외됩니다. CSV/JSON만 사용하는 애플리케이션은 설치 시 선택적 종속성을 생략할 수 있습니다.
+
+## 검증
+
+```sh
+pnpm typecheck
+pnpm test
+pnpm build
+pnpm prepare:test-project
+pnpm --dir test-project build
+pnpm exec playwright install chromium  # 첫 실행 시에만
+pnpm test:e2e
+```
+
+단위 테스트는 필드, 비동기 유효성 검사, 쿼리, 대화 상자, 가상화, 테이블, 설정 마이그레이션, 내보내기를 다룹니다. Playwright 테스트는 패키징된 공개 진입점을 통해 상호작용을 검사합니다. 데스크톱/모바일 스크린샷은 `test-project/test-results`에 저장됩니다.
+
+## 동작 및 규칙
+
+- React에 맞게 설계된 API이며 Vue의 속성이나 메서드를 하나씩 대응시키는 호환 계층이 아닙니다. [마이그레이션 가이드](migration.md)를 참고하세요.
+- 데이터는 애플리케이션 코드가 관리합니다. CRUD 콜백에서 변경 사항을 영속화하며, 실패 시 예외를 던지면 편집 내용이 유지됩니다. 성공 후 컴포넌트는 원격 데이터를 새로 고칩니다. 로컬 데이터는 호출자가 업데이트해야 합니다.
+- 테이블의 `id`는 네임스페이스 내에서 고유해야 하며, `rowKey`는 모든 페이지와 트리 노드에 걸쳐 고유해야 합니다. 서버 측 모드에서는 `columns`를 명시적으로 제공하며 데이터 소스는 전체 개수를 반환합니다.
+- `query` / `value`를 제어하는 경우 부모가 콜백을 처리하고 해당 값을 업데이트해야 합니다. 비제어 방식에서는 이 props를 생략할 수 있습니다.
+- 셀 병합은 가상 윈도 사이의 rowSpan 불일치를 방지하기 위해 가상화하지 않는 의미론적 테이블을 사용합니다. 페이지로 나눈 데이터에 적합합니다.
+- 필터링된 모든 행의 서버 측 집계는 `summaryValues`로 제공합니다. 집계가 없으면 현재 페이지 합계를 전체 합계로 표시하지 않고 `—`를 표시합니다. 현재 페이지를 명시적으로 계산하려면 `summaryScope="page"`를 설정하세요.
+- 업로드 중에는 제출을 일시 중지합니다. 초기화, 필드 값 교체, 마운트 해제 시 이전 업로드를 취소하며, 늦게 도착한 결과가 새 값을 덮어쓸 수 없습니다.
+- 필터링된 모든 결과를 원격으로 내보낼 때는 한 페이지씩 데이터를 요청합니다. 대규모 애플리케이션은 자체 서버 측 내보내기를 구현할 수 있습니다.
+- 브라우저 스타일은 `style.css`에서 명시적으로 가져오세요. JavaScript 모듈은 `window`가 없는 Node 환경에서도 가져올 수 있습니다.
+
+## AutoTable로 남은 높이 채우기
+
+`height={440}`은 기존처럼 데이터 스크롤 영역에 고정 높이를 설정합니다. `height="auto"`를 사용하면 테이블 전체가 부모 레이아웃이 할당한 높이를 채웁니다. 검색 영역, 도구 모음, 페이지 나누기는 자연스러운 높이를 차지하고, 데이터 영역이 남은 공간을 사용하여 독립적으로 스크롤됩니다.
+
+```tsx
+<div style={{ height: '100dvh', display: 'flex', flexDirection: 'column', gap: 12 }}>
+  <header>페이지 제목 및 설명</header>
+  <AutoTable<Person> id="people" rowKey="id" data={rows}
+    columns={columns} height="auto" />
+  <footer>페이지 푸터</footer>
+</div>
+```
+
+부모에는 확정된 높이가 있어야 합니다. 중첩 flex 컨테이너에서는 `flex: 1; min-height: 0`을 사용하여 남은 공간을 전달하고, grid 레이아웃에서는 `grid-template-rows: auto minmax(0, 1fr) auto`를 사용하세요. JavaScript로 뷰포트 높이에서 도구 모음 높이를 뺄 필요가 없습니다. 검색 필드 추가/제거, 도구 모음 줄바꿈, 부모 크기 변경은 레이아웃이 처리하며, 가상 목록은 스크롤 영역의 실제 크기를 따릅니다.
+
+이 설정은 행 수에 따라 테이블 크기를 조정하지 않습니다. 비어 있거나 작은 데이터셋도 사용 가능한 공간을 채웁니다. 부모는 적어도 검색 영역, 도구 모음, 페이지 나누기 자체를 수용할 수 있어야 합니다.
+
+테스트 프로젝트의 **AutoTable → 남은 높이** 탭에서 사이드바와 페이지 헤더를 유지하는 예제를 볼 수 있습니다. 기존 URL `http://127.0.0.1:4173/?demo=auto-height`은 해당 탭을 바로 선택합니다. 브라우저 테스트: `test-project/tests/auto-height.spec.ts`.
+
+## 전역 폼 레이아웃
+
+`AutoConfigProvider.config.form`으로 일반 폼, 검색 패널, 테이블 검색 영역, 대화 상자 폼을 일관되게 설정하세요. 레이블은 컨트롤 위나 왼쪽에 배치할 수 있으며 텍스트의 왼쪽/오른쪽 정렬을 독립적으로 지정할 수 있습니다. 기본값은 상단 레이블과 여유 있는 간격입니다.
+
+```tsx
+<AutoConfigProvider config={{
+  form: {
+    labelPosition: 'left', // 'top': 위쪽; 'left': 컨트롤 왼쪽
+    labelAlign: 'right',   // 텍스트는 오른쪽 정렬, 레이블은 컨트롤 왼쪽에 위치
+    labelWidth: 80,
+    density: 'compact',   // 'comfortable': 간격 넓힘
+  },
+}}>
+  <App />
+</AutoConfigProvider>
+```
+
+중첩된 프로바이더는 레이아웃 설정을 속성별로 병합합니다. 컴포넌트에 명시한 props가 바깥쪽 프로바이더보다 우선합니다. 예를 들어 전역에서는 인라인 레이블을 사용하면서 특정 폼에서는 상단 레이블을 유지할 수 있습니다.
+
+```tsx
+<AutoForm fields={fields} labelPosition="top" density="comfortable" />
+<AutoTable id="people" rowKey="id" data={rows} columns={columns}
+  searchFields={searchFields}
+  searchLayout={{ labelWidth: 100, columns: 3 }} />
+```
+
+`labelWidth`의 기본값은 `"auto"`이며 픽셀 숫자나 `"6em"` 같은 CSS 너비도 받습니다. 자동 모드에서는 각 검색 레이블이 텍스트에 맞는 너비를 사용하고, 일반 폼과 대화 상자 폼은 표시된 레이블을 기준으로 공통 너비를 사용하여 컨트롤을 정렬합니다. 긴 레이블은 필드 너비의 최대 45%를 차지하고 그 이상은 줄바꿈하여 컨트롤 공간을 확보합니다. 명시적으로 고정한 너비에는 이 자동 제한이 적용되지 않습니다. 조밀한 검색 영역에서는 공간이 허용되면 동작 버튼을 같은 줄에 배치하고 좁은 화면에서는 줄바꿈합니다. 레이블 연결이 유지되고 오류와 설명이 컨트롤에 정렬되며 긴 레이블은 줄바꿈할 수 있습니다.
+
+데모에서 사이드바 또는 오른쪽 위 톱니바퀴를 통해 **전역 설정** 을 열어 레이아웃, 밀도, 레이블 너비, 테마를 변경하세요. 현재 입력을 지우지 않고 변경 사항이 즉시 적용됩니다. 폼 페이지는 **전역 설정 따르기** 또는 로컬 재정의를 지원합니다. 데모는 프로바이더를 통해 조밀한 인라인 레이아웃을 명시적으로 활성화합니다.
+
+## 전역 크기 및 밀도
+
+`AutoConfigProvider`는 `size: "small" | "medium" | "large"`와 `density: "compact" | "comfortable"`을 지원합니다. 컴포넌트에 명시한 props가 컴포넌트 유형별 설정보다 우선하며, 유형별 설정은 전역 값보다 우선합니다.
+
+```tsx
+<AutoConfigProvider config={{
+  size: "medium",
+  density: "compact",
+  form: { labelPosition: "left", labelAlign: "right" },
+  table: { density: "compact" },
+  tabs: { density: "compact" },
+}}>
+  <AutoForm fields={fields} size="small" />
+</AutoConfigProvider>
+```
+
+테이블 밀도는 `normal`도 지원합니다. 테이블 설정 패널은 기본적으로 전역 설정을 따릅니다. 조밀함, 보통, 여유로운 간격을 선택하면 전역 밀도를 재정의하고 레이아웃 프리셋과 함께 저장합니다. 컴포넌트의 `density` prop이 가장 높은 우선순위를 갖습니다. 중첩 컴포넌트의 로컬 크기는 각각 독립적으로 적용됩니다.
+
+폼은 `resetLabel`, `extraActions`, `onReset`을 지원하고, 검색 패널은 `searchLabel`, `resetLabel`, `extraActions`를 지원하며, 대화 상자는 `cancelLabel`, `extraActions`를 지원합니다. `AutoTabs` 항목에는 `badge`를 정의할 수 있고, `AutoTable.empty`로 빈 상태 콘텐츠를 사용자 정의할 수 있습니다.
+
+### AutoChat
+
+AutoChat은 스트리밍 따라가기, 기록 불러오기, 작성기를 갖춘 가벼운 대화 레이아웃을 제공합니다. 메시지 렌더링을 위해 React 콘텐츠나 renderMessage를 전달하면 되며, 추가 런타임 의존성이 필요하지 않습니다.
+
+[AutoChat API](auto-chat.md)

package/docs/i18n/ko/auto-chat.md

@@ -0,0 +1,82 @@
+# AutoChat
+
+[English](../../auto-chat.md) | [简体中文](../zh-CN/auto-chat.md) | [繁體中文](../zh-TW/auto-chat.md) | [日本語](../ja/auto-chat.md) | **한국어** | [Español](../es/auto-chat.md) | [Français](../fr/auto-chat.md) | [Deutsch](../de/auto-chat.md) | [Português (Brasil)](../pt-BR/auto-chat.md) | [Русский](../ru/auto-chat.md)
+
+선택적 입력창, 스트리밍 따르기, 이전 이력 로딩을 갖춘 대화 레이아웃입니다. AutoChat은 런타임 의존성을 추가하지 않으며, 네트워크 요청, 메시지 영속화, Markdown 파싱, 도구 출력 실행, 원시 HTML 렌더링도 하지 않습니다.
+
+## 사용법
+
+```tsx
+import { useState } from "react";
+import { AutoChat, type AutoChatMessage } from "@zeroman.yang/react-auto-components";
+import "@zeroman.yang/react-auto-components/style.css";
+
+export function Conversation() {
+  const [messages, setMessages] = useState<AutoChatMessage[]>([]);
+  return (
+    <AutoChat
+      height={600}
+      messages={messages}
+      onSend={async (text) => {
+        setMessages((current) => [
+          ...current,
+          { id: crypto.randomUUID(), role: "user", content: text },
+        ]);
+        // 여기에서 서비스를 호출하고 messages를 업데이트하세요.
+      }}
+    />
+  );
+}
+```
+
+## 렌더러는 직접 제공
+
+React 노드를 `content`로 전달하거나, 애플리케이션 필드로 `AutoChatMessage`를 확장하고 `renderMessage(message, { index })`를 제공하세요. 기존 Markdown 렌더러, 코드 뷰어, 첨부 카드, 도구 결과 컴포넌트를 여기에 연결합니다. AutoChat은 이 형식을 해석하지 않으며, 일반 문자열은 텍스트로 렌더링됩니다. 링크, HTML, 상호작용 콘텐츠의 제어는 호스트에 있습니다.
+
+각 메시지는 안정적이고 고유한 `id`와 `user`, `assistant`, `system`, `tool`, `error` 중 하나의 `role`을 가집니다. 선택적 `author`, `avatar`, `meta`, `streaming`으로 껍데기를 커스터마이즈하고, `renderActions(message, context)`로 메시지 액션을 제공합니다. 스트리밍 응답을 갱신할 때는 같은 ID를 유지하고, messages 배열은 불변 방식으로 교체하세요.
+
+## 동작과 props
+
+| Prop | 동작 |
+| --- | --- |
+| `height` | CSS 높이, 기본 `100%`. 부모에 확정 높이를 주거나 `600` 같은 숫자를 전달하세요. 이력은 컴포넌트 내부에서 스크롤됩니다. |
+| `autoFollow` | 기본 `true`. 하단의 새 콘텐츠와 크기 변화를 따르고, 읽는 사람이 위로 스크롤하면 일시 중지합니다. **최신으로** 로 따르기를 재개합니다. |
+| `hasMore`, `onLoadOlder`, `loadingOlder` | 이전 이력 버튼을 표시합니다. 안정적 ID로 메시지를 앞에 추가하며 보이는 메시지는 고정됩니다. 요청은 중복 제거되고, 실패한 요청은 재시도할 수 있습니다. |
+| `onSend(text)` | 입력창을 활성화합니다. 원본의 공백 아닌 텍스트를 받고 Promise를 반환할 수 있습니다. 수락하면 임시글을 지우고, 거부하면 유지하며 일반 오류를 표시합니다. 최신 임시글이 이전 전송으로 지워지지 않습니다. |
+| `value`, `defaultValue`, `onValueChange` | 제어 또는 로컬 입력값. 제어 값을 사용할 때는 호스트에서 변경을 적용합니다. |
+| `generating`, `onStop` | 생성 중 전송을 비활성화하고 정지 버튼을 노출합니다. 호스트는 자체 스트림/요청을 취소하고 `generating`을 갱신해야 합니다. |
+| `sendOnEnter` | 기본 `true`. Shift+Enter는 줄바꿈입니다. IME 조합 이벤트와 확정은 제출하지 않습니다. `false`로 설정하면 버튼으로만 전송합니다. |
+| `disabled`, `composer` | 내장 에디터를 비활성화하거나, 외부 에디터 사용 시 숨깁니다(`composer={false}`). |
+| `conversationKey` | 대화를 전환하면 로컬 임시글, 진행 중 UI, 스크롤을 초기화합니다. 제어 값과 취소는 여전히 호스트 소유입니다. |
+| `header`, `footer`, `empty`, `composerExtra` | React 콘텐츠 슬롯입니다. |
+| `size`, `density` | 전역 `AutoConfigProvider` 설정을 덮어씁니다. |
+| `labels` | 내장 영어 라벨을 덮어씁니다. Provider는 `chat.send`, `chat.latest` 등 `chat.*` 키도 번역합니다. |
+| `onSendError`, `onLoadError` | 애플리케이션 로깅을 위해 원본 오류를 전달받습니다. 내부 오류 세부 정보는 자동 표시되지 않습니다. |
+
+대량 이력에서는 `virtual`을 설정해 패키지에 이미 있는 TanStack Virtual 의존성을 사용합니다. 보이는 메시지와 작은 overscan 창만 마운트되고, 동적 행 높이도 측정됩니다. 필요하면 `estimatedMessageHeight`(기본 `120`)와 `overscan`(기본 `6`)을 조정하세요. 이력을 앞에 추가할 때는 메시지 ID를 안정적으로 유지합니다. 가상 모드에서 뷰포트 밖 언마운트를 넘겨야 하는 상호작용 상태는 호스트에 보관하세요. 일반 대화는 기본적으로 비가상 레이아웃을 사용합니다.
+
+**대량 이력** 데모는 1,000/10,000/50,000개의 가변 높이 메시지를 로드하고 실제 마운트된 메시지 수를 표시하며, 100개 추가, 스트리밍, 이전 이력 로딩, 양 끝으로 이동을 지원합니다.
+
+`AutoChatHandle` ref는 `scrollToBottom()`, `scrollToMessage(id)`(ID 존재 여부 반환), `focusComposer()`, `getScrollElement()`를 노출합니다. 이력은 키보드로 포커스할 수 있는 로그이며, 별도 상태 영역이 전송/생성 상태를 알리고 스트리밍 토큰마다 알리지는 않습니다.
+
+로컬 스트리밍 시뮬레이션, 취소, 사용자 지정 도구 카드, 페이지네이션, 전송 실패, 10개 언어 UI는 [실행 가능한 데모](../../../test-project/src/examples/ChatDemo.tsx)를 참고하세요.
+
+## 데모의 풍부한 렌더링
+
+사유 `test-project`는 [react-markdown](https://github.com/remarkjs/react-markdown)과 [remark-gfm](https://github.com/remarkjs/remark-gfm)을 설치합니다. 이 의존성은 컴포넌트 라이브러리에 포함되지 않습니다. 형식 선택기는 Markdown(제목, 강조, 작업 목록, GFM 표), 코드, JSON, 데이터 표, 로컬 이미지, 상호작용형 React 리뷰 카드를 삽입할 수 있습니다.
+
+`ChatRenderers.tsx`는 구조화된 메시지 데이터에서 React 컴포넌트를 선택합니다. `ChatTaskCard.tsx`는 로컬 상호작용 상태를 보여줍니다. Markdown은 `skipHtml`과 라이브러리 기본 URL 처리를 사용하며 JSX를 컴파일하거나 코드 펜스를 실행하지 않습니다. 같은 Markdown 렌더러로 스트리밍 응답도 표시합니다. 사용자 지정 컴포넌트는 애플리케이션이 제공하며, 실행 가능한 메시지 텍스트에서 인스턴스화되지 않습니다.
+
+```tsx
+import Markdown from "react-markdown";
+import remarkGfm from "remark-gfm";
+
+<AutoChat
+  messages={messages}
+  renderMessage={(message) => (
+    <Markdown remarkPlugins={[remarkGfm]} skipHtml>
+      {String(message.content ?? "")}
+    </Markdown>
+  )}
+/>
+```

package/docs/i18n/ko/migration.md

@@ -0,0 +1,71 @@
+# 컴포넌트 통합 가이드
+
+[English](../../migration.md) | [简体中文](../zh-CN/migration.md) | [繁體中文](../zh-TW/migration.md) | [日本語](../ja/migration.md) | **한국어** | [Español](../es/migration.md) | [Français](../fr/migration.md) | [Deutsch](../de/migration.md) | [Português (Brasil)](../pt-BR/migration.md) | [Русский](../ru/migration.md)
+
+React 제네릭, 콜백, 프로바이더를 통해 컴포넌트를 구성합니다. 다음 표는 일반적인 애플리케이션 요구 사항을 공개 API와 실행 가능한 예제에 매핑합니다.
+
+| 기존 사용 사례 | React API | 실행 가능한 예제 / 테스트 |
+| --- | --- | --- |
+| 폼 필드 및 v-model | `fields: Field<T>[]`, `value/onChange` 또는 `defaultValue` | `test-project/src/examples/FormDemo.tsx`의 폼 페이지; `tests/form*.test.tsx` |
+| 슬롯 및 추가 콘텐츠 | 필드 `render`, 열 `render/header`, ReactNode | 폼/테이블 페이지 |
+| 폼 인스턴스 작업 | `ref.validate/reset/getValues/setValue/focus` | `tests/form.test.tsx` |
+| 검색, 연관 조건, RSQL | `buildQuery`, `matchesQuery`, `serializeRsql` | 검색 페이지; `tests/query.test.ts` |
+| 로컬/원격 테이블 데이터 | `data` 또는 `dataSource(query,{signal})` | 테이블 페이지; `tests/table.test.tsx` |
+| 레이아웃/필터/정렬/내보내기 프리셋 | 설정 대화 상자의 독립적인 프리셋, `versions`로 각각 무효화 | 테이블 페이지; `tests/table-settings.test.ts` |
+| 트리, 상세, 집계, 셀 병합 | `getChildren/renderExpanded`, 열 `summary/merge` | 트리 및 펼치기 예제; `tests/table-advanced.test.tsx` |
+| 추가, 편집, 삭제 | `formFields` 및 `onAdd/onEdit/onDelete` | 브라우저 CRUD 테스트 |
+| 명령형 대화 상자 | `AutoDialogProvider` + `useAutoDialog().open()` | 대화 상자 페이지; `tests/dialog.test.tsx` |
+| 탭 및 중첩 탭 | `AutoTabs` items, value/onChange, keepMounted | 탭 페이지; `tests/tabs.test.tsx` |
+| 채팅 메시지 목록과 대화 UI | `AutoChat`, `messages`, `onSend`, `renderMessage` | `test-project/src/examples/Chat*.tsx` 채팅 페이지; `tests/chat.test.tsx` |
+
+## 필드 유형
+
+`input/email/textarea/integer/float/percentage/progress/switch/select/select-v2/radio/checkbox/cascader/autocomplete/date/datetime/daterange/datetimerange/upload/text/title/tip/button/append/custom`.
+
+`select-v2`는 옵션을 가상화합니다. 날짜 범위는 각각 레이블이 있는 네이티브 입력 2개를 사용하며, `dateValue`로 문자열 또는 타임스탬프를 선택합니다. 숫자 입력은 편집 중간 상태를 허용합니다. 제출 시 비즈니스 제약 조건을 검증하려면 필드 규칙을 사용하세요. `rules`는 비동기 유효성 검사를 지원하며 숨겨진 필드는 검사를 건너뜁니다. 옵션은 숫자/불리언 값을 문자열로 강제 변환하지 않고 유지합니다.
+
+```tsx
+const fields: Field<User>[] = [
+  { name: 'name', label: '이름', required: true },
+  { name: 'note', label: '메모', hidden: values => !values.enabled,
+    render: ({ value, onChange, disabled }) =>
+      <textarea disabled={disabled} value={String(value ?? '')}
+        onChange={event => onChange(event.target.value)} /> },
+];
+```
+
+전체 API는 내보낸 TypeScript 타입을 참고하세요. `Field<T>`는 T의 실제 키에 연결되며, 제목과 도움말 같은 구조적 항목에는 데이터 속성이 필요하지 않습니다.
+
+## 서버 측 데이터 소스
+
+```tsx
+const dataSource: DataSource<User> = async (query, { signal }) => {
+  const response = await fetch('/api/users/search', {
+    method: 'POST', signal,
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(query),
+  });
+  if (!response.ok) throw new Error('로드 실패');
+  return response.json(); // { rows: User[], total: number }
+};
+```
+
+페이지 인덱스는 0부터 시작합니다. `sort`는 순서가 있는 필드 배열이며, `filter`는 구조화된 쿼리 트리입니다. 컴포넌트는 이전 요청을 취소하고 늦게 도착한 응답이 새 쿼리를 덮어쓰지 못하도록 합니다. 데이터 소스 클로저 외부의 비즈니스 조건이 변경되면 테이블의 `ref.refresh()`를 호출하세요. 불필요한 요청을 피하려면 데이터 소스 함수의 참조를 안정적으로 유지하세요. RSQL 직렬화는 이를 필요로 하는 백엔드용 어댑터일 뿐이며 쿼리 문자열을 실행하지 않습니다.
+
+## 애플리케이션 업로드 및 영속화
+
+필드의 `upload(files, signal)`은 애플리케이션이 파일을 저장한 후 필드 값을 반환합니다. 컴포넌트는 업로드 실패를 표시하며, 호출자는 업로드 URL, 인증, 객체 스토리지 정책을 제공합니다.
+
+```tsx
+<AutoConfigProvider config={{
+  namespace: 'tenant-admin',
+  canAccess: access => !access.permissions?.length || access.permissions.every(p => myPermissions.includes(p)),
+  settings: {
+    load: key => api.loadTableSettings(key),
+    save: (key, settings) => api.saveTableSettings(key, settings),
+  },
+  notify: (message, level) => showToast(message, level),
+}}>{children}</AutoConfigProvider>
+```
+
+로컬 변경 사항은 즉시 적용되며, 원격 저장은 순차적으로 실행되고 실패 시 재시도 옵션이 제공됩니다. 저장된 설정 형식을 변경할 때는 호환되지 않는 설정이 로드되는 것을 피하기 위해 새로운 table id 또는 version을 사용하세요.

package/docs/i18n/pt-BR/README.md

@@ -0,0 +1,203 @@
+# React Auto Components
+
+[English](../../../README.md) | [简体中文](../zh-CN/README.md) | [繁體中文](../zh-TW/README.md) | [日本語](../ja/README.md) | [한국어](../ko/README.md) | [Español](../es/README.md) | [Français](../fr/README.md) | [Deutsch](../de/README.md) | **Português (Brasil)** | [Русский](../ru/README.md)
+
+Uma biblioteca de componentes independente e orientada a esquemas para React 19, com formulários, tabelas e chat. Construída com TypeScript, TanStack Table 9 / Form / Virtual, Radix e Floating UI, sem Ant Design, Element Plus ou MUI. Os builds da biblioteca usam React Compiler.
+
+[![Auto Studio Demonstração](../../assets/demo.png)](https://zeroman.github.io/react-auto-components/)
+
+<p align="center">
+  <a href="https://zeroman.github.io/react-auto-components/"><strong>🚀 Demonstração Online (GitHub Pages)</strong></a> · <a href="#executar-o-projeto-de-testes-independente">Executar Localmente</a> · <a href="#componentes">Componentes</a>
+</p>
+
+## Estado do projeto
+
+A versão atual é 0.1.0 e as APIs ainda podem mudar. O React 19 é necessário. O pacote fornece declarações ESM e TypeScript. O texto integrado da interface tem como padrão o chinês e pode ser traduzido por meio de AutoConfigProvider.config.t.
+
+Instale com `pnpm add @zeroman.yang/react-auto-components` (npm e yarn funcionam da mesma forma). As peer dependencies são React 19 e react-dom 19. Importe a folha de estilo uma vez: `import "@zeroman.yang/react-auto-components/style.css"`.
+
+- [Demonstração Online (GitHub Pages)](https://zeroman.github.io/react-auto-components/)
+- [Como contribuir](https://github.com/Zeroman/react-auto-components/blob/main/docs/i18n/pt-BR/CONTRIBUTING.md)
+- [Histórico de alterações](https://github.com/Zeroman/react-auto-components/blob/main/docs/i18n/pt-BR/CHANGELOG.md)
+- [Configuração da conta e publicação](https://github.com/Zeroman/react-auto-components/blob/main/docs/i18n/pt-BR/publishing.md)
+- [Licença MIT](../../../LICENSE)
+
+## Executar o projeto de testes independente
+
+Requer Node.js >= 22.12 e pnpm 12.5.
+
+```sh
+pnpm install --frozen-lockfile
+pnpm prepare:test-project
+pnpm --dir test-project dev
+```
+
+Abra http://127.0.0.1:4173. O projeto de testes inclui páginas para todos os sete componentes, tabelas locais/no servidor/com 10.000 linhas/em árvore, CRUD, novas tentativas de envios com falha, rascunhos, abas aninhadas e alturas de linha dinâmicas.
+
+A demonstração detecta automaticamente o idioma do navegador, com o inglês como fallback. Escolha um idioma no cabeçalho ou nas Configurações globais; a seleção é lembrada entre recarregamentos da página. Selecione Auto para seguir novamente o navegador. Dez idiomas são suportados. As páginas preenchem a viewport, com tabelas e painéis longos rolando dentro de suas próprias áreas.
+
+Cada página de exemplo inclui um botão **Ver código** que abre seu arquivo-fonte real em um diálogo, com abas de arquivos, cópia em um clique e link para o GitHub.
+
+`test-project` tem seus próprios arquivos package.json e de lock. Ele instala a saída real de `pnpm pack`, sem aliases para o código-fonte. Execute `pnpm prepare:test-project` novamente após alterar a biblioteca; o script usa nomes de arquivo com hash do conteúdo para evitar caches de arquivos tarball desatualizados.
+
+## Uso
+
+```tsx
+import { useState } from 'react';
+import {
+  AutoConfigProvider, AutoDialogProvider, AutoTable,
+  type AutoColumn, type Field,
+} from '@zeroman.yang/react-auto-components';
+import '@zeroman.yang/react-auto-components/style.css';
+
+type Person = { id: number; name: string; enabled: boolean };
+const columns: AutoColumn<Person>[] = [
+  { key: 'name', label: 'Nome', sortable: true },
+  { key: 'enabled', label: 'Ativado', options: [
+    { label: 'Sim', value: true }, { label: 'Não', value: false },
+  ] },
+];
+const fields: Field<Person>[] = [
+  { name: 'name', label: 'Nome', required: true },
+  { name: 'enabled', label: 'Ativado', type: 'switch', defaultValue: true },
+];
+export function App() {
+  const [rows, setRows] = useState<Person[]>([]);
+  return <AutoConfigProvider config={{ namespace: 'my-app' }}>
+    <AutoDialogProvider>
+      <AutoTable<Person> id="people" rowKey="id" data={rows}
+        columns={columns} formFields={fields} searchFields={fields}
+        onAdd={value => setRows(old => [...old, { ...value, id: Date.now() }])}
+        onEdit={(row, value) => setRows(old => old.map(item => item.id === row.id ? { ...row, ...value } : item))}
+        onDelete={selected => setRows(old => old.filter(item => !selected.some(row => row.id === item.id)))}
+      />
+    </AutoDialogProvider>
+  </AutoConfigProvider>;
+}
+```
+
+Campos, colunas e referências usam genéricos: nomes de campo ou valores padrão inválidos geram erros em tempo de compilação. O provedor oferece suporte a namespaces, permissões, tradução de rótulos de campos, campos personalizados, notificações e adaptadores de persistência. Rótulos integrados, mensagens de validação e textos de acessibilidade usam AutoConfigProvider.config.t; rótulos explícitos de componentes têm precedência.
+
+O callback t recebe uma chave de mensagem e um fallback. Preserve os placeholders numerados, como {0} e {1}, nas mensagens integradas traduzidas; os componentes substituem seus valores após a tradução.
+
+## Componentes
+
+| Componente | Recursos |
+| --- | --- |
+| AutoForm | Tipos de campo nativos, opções virtualizadas, seleção em cascata, adaptadores de upload, renderização personalizada, campos dependentes, visibilidade condicional, validação assíncrona, estado controlado e preservação dos dados preenchidos após falhas |
+| AutoSearchPanel | Condições básicas/avançadas, busca manual/instantânea, redefinição, etiquetas de ordenação, AST de consulta compartilhada e serialização RSQL |
+| AutoTable | Dados locais/remotos, ordenação por várias colunas, filtros de coluna, paginação, seleção estável, virtualização, expansão de árvores/detalhes, resumos, células mescladas, CRUD, menus de contexto e cópia |
+| AutoDialog | APIs declarativas/imperativas, provedores isolados, rascunhos, proteção de fechamento, gerenciamento de foco, arraste, tela cheia e envio assíncrono |
+| AutoTabs | Layouts horizontal/vertical, aninhamento, permissões, abas desabilitadas, preservação do estado dos painéis e atualização |
+| AutoMenu | Navegação lateral com ícones, descrições, badges, grupos aninhados, permissões e uma barra de ícones recolhível |
+| AutoChat | Renderização de mensagens controlada pelo chamador, virtualização opcional, acompanhamento de streaming, carregamento de histórico ancorado, compositor com envio/parada e ações personalizadas |
+
+Layout da tabela, ordenação, filtragem e exportação oferecem, cada um, predefinições nomeadas e versões independentes. A persistência usa localStorage por padrão; adaptadores remotos podem ser injetados. A exportação JSON/CSV é integrada. XLSX usa um adaptador opcional separado:
+
+```tsx
+import { exportXlsx } from '@zeroman.yang/react-auto-components/xlsx';
+// <AutoTable ... exportXlsx={exportXlsx} />
+```
+
+ExcelJS é carregado dinamicamente no primeiro uso do adaptador e fica fora do ponto de entrada principal da biblioteca. Aplicações que usam apenas CSV/JSON podem omitir as dependências opcionais durante a instalação.
+
+## Verificação
+
+```sh
+pnpm typecheck
+pnpm test
+pnpm build
+pnpm prepare:test-project
+pnpm --dir test-project build
+pnpm exec playwright install chromium  # Somente na primeira execução
+pnpm test:e2e
+```
+
+Os testes unitários cobrem campos, validação assíncrona, consultas, diálogos, virtualização, tabelas, migrações de configuração e exportações. Os testes Playwright verificam interações por meio dos pontos de entrada públicos do pacote. Capturas de tela de desktop e dispositivos móveis são gravadas em `test-project/test-results`.
+
+## Comportamento e convenções
+
+- Esta é uma API nativa do React, não uma camada de compatibilidade com Vue propriedade por propriedade ou método por método. Consulte o [guia de migração](migration.md).
+- O código da aplicação é responsável pelos dados. Os callbacks de CRUD persistem as alterações; lançar uma exceção em caso de falha preserva as edições. Após o sucesso, o componente atualiza os dados remotos. Os dados locais devem ser atualizados por quem o utiliza.
+- O `id` de uma tabela deve ser único em seu namespace, e `rowKey` deve ser único em todas as páginas e nós da árvore. No modo de servidor, forneça `columns` explicitamente; a fonte de dados retorna a contagem total.
+- Quando `query` / `value` são controlados, o componente pai deve tratar os callbacks e atualizar o valor. Essas propriedades podem ser omitidas para uso não controlado.
+- As células mescladas usam uma tabela semântica não virtualizada, adequada a dados paginados, para evitar desalinhamento de rowSpan entre janelas virtuais.
+- Os resumos do servidor para todas as linhas filtradas são fornecidos por `summaryValues`. Resumos ausentes exibem `—` em vez de apresentar o total da página atual como total geral. Defina `summaryScope="page"` para calcular explicitamente a página atual.
+- O envio é pausado enquanto uploads estão em andamento. Redefinir ou substituir os valores dos campos, ou desmontar o componente, cancela os uploads antigos; resultados atrasados não podem sobrescrever valores mais recentes.
+- Exportações remotas de todos os resultados filtrados solicitam os dados uma página por vez. Aplicações grandes podem implementar sua própria exportação no servidor.
+- Importe explicitamente os estilos do navegador de `style.css`. Os módulos JavaScript podem ser importados no Node sem `window`.
+
+## Preencher a altura restante com AutoTable
+
+`height={440}` continua definindo uma altura fixa para a área de rolagem dos dados. Com `height="auto"`, a tabela inteira preenche a altura alocada pelo layout do elemento pai. Busca, barra de ferramentas e paginação mantêm suas alturas naturais; a área de dados usa o espaço restante e tem rolagem independente:
+
+```tsx
+<div style={{ height: '100dvh', display: 'flex', flexDirection: 'column', gap: 12 }}>
+  <header>Título e descrição da página</header>
+  <AutoTable<Person> id="people" rowKey="id" data={rows}
+    columns={columns} height="auto" />
+  <footer>Rodapé da página</footer>
+</div>
+```
+
+O elemento pai deve ter uma altura definida. Use `flex: 1; min-height: 0` em contêineres flex aninhados para repassar o espaço restante, ou `grid-template-rows: auto minmax(0, 1fr) auto` em layouts de grade. Não é necessário calcular em JavaScript a altura da janela menos a altura da barra de ferramentas: o layout lida com a adição e remoção de campos de busca, barras de ferramentas em várias linhas e redimensionamento do elemento pai; a lista virtual acompanha as dimensões reais da área de rolagem.
+
+Isso não dimensiona a tabela de acordo com o número de linhas. Conjuntos de dados vazios ou pequenos continuam preenchendo o espaço disponível. O elemento pai deve acomodar, no mínimo, a própria área de busca, a barra de ferramentas e a paginação.
+
+O projeto de testes demonstra esse comportamento na aba **AutoTable → Altura restante**, preservando a barra lateral e o cabeçalho da página. A URL legada `http://127.0.0.1:4173/?demo=auto-height` seleciona essa aba diretamente. Testes de navegador: `test-project/tests/auto-height.spec.ts`.
+
+## Layout global de formulários
+
+Use `AutoConfigProvider.config.form` para configurar de forma consistente formulários comuns, painéis de busca, áreas de busca de tabelas e formulários de diálogos. Os rótulos podem aparecer acima ou à esquerda dos controles, com alinhamento de texto à esquerda/direita independente. O padrão é usar rótulos acima e espaçamento confortável.
+
+```tsx
+<AutoConfigProvider config={{
+  form: {
+    labelPosition: 'left', // 'top': acima; 'left': à esquerda do controle
+    labelAlign: 'right',   // Texto alinhado à direita; o rótulo fica à esquerda do controle
+    labelWidth: 80,
+    density: 'compact',   // 'comfortable': mais espaçamento
+  },
+}}>
+  <App />
+</AutoConfigProvider>
+```
+
+Provedores aninhados mesclam as configurações de layout propriedade por propriedade. Propriedades explícitas dos componentes prevalecem sobre o provedor que os envolve. Por exemplo, mantenha os rótulos acima em um formulário enquanto usa rótulos na mesma linha globalmente:
+
+```tsx
+<AutoForm fields={fields} labelPosition="top" density="comfortable" />
+<AutoTable id="people" rowKey="id" data={rows} columns={columns}
+  searchFields={searchFields}
+  searchLayout={{ labelWidth: 100, columns: 3 }} />
+```
+
+`labelWidth` usa `"auto"` por padrão e também aceita um número de pixels ou uma largura CSS, como `"6em"`. No modo automático, cada rótulo de busca se ajusta ao texto; formulários comuns e formulários de diálogos compartilham uma largura baseada nos rótulos visíveis para alinhar os controles. Rótulos longos ocupam no máximo 45% da largura do campo e quebram em mais linhas a partir desse limite, preservando espaço para os controles. Larguras fixas explícitas não estão sujeitas a esse limite automático. Áreas de busca compactas colocam os botões de ação na mesma linha quando há espaço e quebram em mais linhas em telas estreitas. As associações dos rótulos permanecem intactas, erros e descrições se alinham aos controles, e rótulos longos podem quebrar em mais linhas.
+
+Na demonstração, abra **Configurações globais** pela barra lateral ou pela engrenagem no canto superior direito para alterar layout, densidade, largura dos rótulos e tema. As alterações entram em vigor imediatamente sem limpar os dados preenchidos. A página de formulários oferece **Seguir configurações globais** ou substituições locais. A demonstração ativa explicitamente o layout compacto na mesma linha por meio de seu provedor.
+
+## Tamanho e densidade globais
+
+`AutoConfigProvider` oferece suporte a `size: "small" | "medium" | "large"` e `density: "compact" | "comfortable"`. Propriedades explícitas dos componentes têm prioridade sobre as configurações da categoria do componente, que têm prioridade sobre os valores globais:
+
+```tsx
+<AutoConfigProvider config={{
+  size: "medium",
+  density: "compact",
+  form: { labelPosition: "left", labelAlign: "right" },
+  table: { density: "compact" },
+  tabs: { density: "compact" },
+}}>
+  <AutoForm fields={fields} size="small" />
+</AutoConfigProvider>
+```
+
+A densidade da tabela também aceita `normal`. Por padrão, o painel de configurações da tabela segue as configurações globais. Selecionar espaçamento compacto, normal ou confortável substitui a densidade global e é salvo com a predefinição de layout; a propriedade `density` do componente tem a maior prioridade. Tamanhos locais de componentes aninhados se aplicam de forma independente.
+
+Formulários oferecem suporte a `resetLabel`, `extraActions` e `onReset`; painéis de busca oferecem suporte a `searchLabel`, `resetLabel` e `extraActions`; diálogos oferecem suporte a `cancelLabel` e `extraActions`. Os itens de `AutoTabs` podem definir um `badge`, e `AutoTable.empty` personaliza o conteúdo do estado vazio.
+
+### AutoChat
+
+O AutoChat fornece um layout de conversa leve com acompanhamento de streaming, carregamento de histórico e um compositor. Forneça conteúdo React ou renderMessage para a renderização das mensagens; nenhuma dependência extra em tempo de execução é necessária.
+
+[AutoChat API](auto-chat.md)