@zeroman.yang/react-auto-components 0.1.0

package/docs/i18n/pt-BR/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) | [한국어](../ko/auto-chat.md) | [Español](../es/auto-chat.md) | [Français](../fr/auto-chat.md) | [Deutsch](../de/auto-chat.md) | **Português (Brasil)** | [Русский](../ru/auto-chat.md)
+
+Um layout de conversa com compositor opcional, acompanhamento de streaming e carregamento de histórico anterior. O AutoChat não adiciona dependências de runtime e não faz requisições de rede, não persiste mensagens, não analisa Markdown, não executa saída de ferramentas nem renderiza HTML bruto.
+
+## Uso
+
+```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 },
+        ]);
+        // Chame seu serviço aqui e atualize messages.
+      }}
+    />
+  );
+}
+```
+
+## Traga seu próprio renderizador
+
+Passe nós React como `content`, ou estenda `AutoChatMessage` com os campos da sua aplicação e forneça `renderMessage(message, { index })`. Conecte aí um renderizador Markdown existente, visualizador de código, cartão de anexos ou componente de resultado de ferramenta. O AutoChat nunca interpreta esses formatos; uma string simples é renderizada como texto. O renderizador hospedeiro controla links, HTML e qualquer conteúdo interativo.
+
+Cada mensagem tem um `id` único e estável e um `role`: `user`, `assistant`, `system`, `tool` ou `error`. Os campos opcionais `author`, `avatar`, `meta` e `streaming` personalizam sua casca; `renderActions(message, context)` fornece ações por mensagem. Mantenha o mesmo ID ao atualizar uma resposta em streaming e substitua o array de messages de forma imutável.
+
+## Comportamento e props
+
+| Prop | Comportamento |
+| --- | --- |
+| `height` | Altura CSS, padrão `100%`. Dê ao pai uma altura definida ou passe um número como `600`. O histórico rola dentro do componente. |
+| `autoFollow` | Padrão `true`. Acompanha conteúdo novo e redimensionado no rodapé; pausa quando o leitor rola para cima. **Voltar ao mais recente** retoma o acompanhamento. |
+| `hasMore`, `onLoadOlder`, `loadingOlder` | Mostram um botão de histórico anterior. Antepõe mensagens com IDs estáveis; a mensagem visível permanece ancorada. As requisições são deduplicadas e uma requisição rejeitada pode ser repetida. |
+| `onSend(text)` | Habilita o compositor. Recebe o texto original não vazio; pode retornar uma promessa. Aceitar limpa esse rascunho; rejeitar o preserva e exibe um erro genérico. Um rascunho mais novo nunca é limpo por um envio mais antigo. |
+| `value`, `defaultValue`, `onValueChange` | Valor de compositor controlado ou local. Com valor controlado, aplique as mudanças no host. |
+| `generating`, `onStop` | Desativa envios durante a geração e expõe um botão de parar. O host deve cancelar seu próprio stream/requisição e atualizar `generating`. |
+| `sendOnEnter` | Padrão `true`; Shift+Enter insere nova linha. Eventos de composição e confirmação de IME nunca enviam. Use `false` para enviar apenas por botão. |
+| `disabled`, `composer` | Desativa o editor integrado ou o oculta (`composer={false}`) ao usar um editor externo. |
+| `conversationKey` | Redefine rascunho local, UI pendente e rolagem ao trocar de conversa. Valores controlados e cancelamento continuam pertencendo ao host. |
+| `header`, `footer`, `empty`, `composerExtra` | Slots de conteúdo React. |
+| `size`, `density` | Sobrescrevem as configurações globais do `AutoConfigProvider`. |
+| `labels` | Sobrescrevem os rótulos embutidos em inglês. O provider também traduz `chat.send`, `chat.latest` e outras chaves `chat.*`. |
+| `onSendError`, `onLoadError` | Recebem o erro original para logging da aplicação; detalhes internos do erro não são exibidos automaticamente. |
+
+Para históricos grandes, ative `virtual` para usar a dependência TanStack Virtual já existente no pacote. Somente mensagens visíveis e uma pequena janela de overscan são montadas; alturas dinâmicas de linha são medidas. Ajuste se necessário `estimatedMessageHeight` (padrão `120`) e `overscan` (padrão `6`). Mantenha IDs de mensagem estáveis ao antepor histórico. No modo virtual, mantenha no host o estado interativo que precise sobreviver a linhas desmontadas fora do viewport. Conversas comuns usam por padrão o layout não virtual.
+
+A demonstração de **Histórico grande** carrega 1.000, 10.000 ou 50.000 mensagens de altura variável, informa a contagem real de mensagens montadas e permite anexar 100 mensagens, streaming, carregar histórico anterior e saltar para qualquer extremo.
+
+O ref `AutoChatHandle` expõe `scrollToBottom()`, `scrollToMessage(id)` (retorna se o ID existe), `focusComposer()` e `getScrollElement()`. O histórico usa um registro focalizável por teclado; uma região de status separada anuncia o estado de envio/geração sem anunciar cada token do streaming.
+
+Veja [a demonstração executável](../../../test-project/src/examples/ChatDemo.tsx) para simulação local de streaming, cancelamento, um cartão de ferramenta personalizado, paginação, falhas de envio e interface em dez idiomas.
+
+## Renderização rica na demonstração
+
+O `test-project` privado instala [react-markdown](https://github.com/remarkjs/react-markdown) e [remark-gfm](https://github.com/remarkjs/remark-gfm). Essas dependências não fazem parte da biblioteca de componentes. Seu seletor de formatos insere Markdown (títulos, ênfase, listas de tarefas e tabelas GFM), código, JSON, tabelas de dados, uma imagem local ou um cartão React interativo de revisão.
+
+`ChatRenderers.tsx` escolhe componentes React a partir de dados estruturados de mensagem. `ChatTaskCard.tsx` demonstra estado interativo local. O Markdown usa `skipHtml` e o tratamento padrão de URLs da biblioteca; não compila JSX nem executa blocos de código. O mesmo renderizador Markdown exibe respostas em streaming. Componentes personalizados são fornecidos pela aplicação, nunca instanciados a partir de texto de mensagem executável.
+
+```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/pt-BR/migration.md

@@ -0,0 +1,71 @@
+# Guia de integração de componentes
+
+[English](../../migration.md) | [简体中文](../zh-CN/migration.md) | [繁體中文](../zh-TW/migration.md) | [日本語](../ja/migration.md) | [한국어](../ko/migration.md) | [Español](../es/migration.md) | [Français](../fr/migration.md) | [Deutsch](../de/migration.md) | **Português (Brasil)** | [Русский](../ru/migration.md)
+
+Configure componentes por meio de generics do React, callbacks e providers. A tabela a seguir mapeia necessidades comuns de aplicativos para as APIs públicas e exemplos executáveis.
+
+| Caso de uso original | API React | Exemplo executável / teste |
+| --- | --- | --- |
+| Campos de formulário e v-model | `fields: Field<T>[]`, `value/onChange` ou `defaultValue` | Página de formulários em `test-project/src/examples/FormDemo.tsx`; `tests/form*.test.tsx` |
+| Slots e conteúdo acrescentado | `render` do campo, `render/header` da coluna, ReactNode | Páginas de formulários/tabelas |
+| Operações na instância do formulário | `ref.validate/reset/getValues/setValue/focus` | `tests/form.test.tsx` |
+| Busca, condições relacionadas, RSQL | `buildQuery`, `matchesQuery`, `serializeRsql` | Página de busca; `tests/query.test.ts` |
+| Dados locais/remotos de tabelas | `data` ou `dataSource(query,{signal})` | Página de tabelas; `tests/table.test.tsx` |
+| Predefinições de layout/filtro/ordenação/exportação | Predefinições independentes no diálogo de configurações, invalidadas separadamente por `versions` | Página de tabelas; `tests/table-settings.test.ts` |
+| Árvores, detalhes, resumos, células mescladas | `getChildren/renderExpanded`, `summary/merge` da coluna | Exemplos de árvores e expansão; `tests/table-advanced.test.tsx` |
+| Adicionar, editar, excluir | `formFields` e `onAdd/onEdit/onDelete` | Testes de CRUD no navegador |
+| Diálogos imperativos | `AutoDialogProvider` + `useAutoDialog().open()` | Página de diálogos; `tests/dialog.test.tsx` |
+| Abas e abas aninhadas | Itens de `AutoTabs`, value/onChange, keepMounted | Página de abas; `tests/tabs.test.tsx` |
+| Listas de mensagens de chat e UI de conversa | `AutoChat`, `messages`, `onSend`, `renderMessage` | Páginas de chat em `test-project/src/examples/Chat*.tsx`; `tests/chat.test.tsx` |
+
+## Tipos de campo
+
+`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` virtualiza as opções. Intervalos de datas usam dois campos nativos com rótulos separados; `dateValue` escolhe entre strings e timestamps. Campos numéricos permitem estados intermediários de edição; use regras de campo para validar restrições de negócio no envio. `rules` oferece suporte à validação assíncrona, enquanto campos ocultos não passam pela validação. As opções preservam valores numéricos/booleanos em vez de convertê-los em strings.
+
+```tsx
+const fields: Field<User>[] = [
+  { name: 'name', label: 'Nome', required: true },
+  { name: 'note', label: 'Observação', hidden: values => !values.enabled,
+    render: ({ value, onChange, disabled }) =>
+      <textarea disabled={disabled} value={String(value ?? '')}
+        onChange={event => onChange(event.target.value)} /> },
+];
+```
+
+Consulte os tipos TypeScript exportados para conhecer a API completa. `Field<T>` se vincula às chaves reais de T; itens estruturais, como títulos e dicas, não precisam de uma propriedade de dados.
+
+## Fontes de dados no servidor
+
+```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('Falha ao carregar');
+  return response.json(); // { rows: User[], total: number }
+};
+```
+
+Os índices de página começam em 0. `sort` é um array ordenado de campos; `filter` é uma árvore estruturada de consulta. Os componentes cancelam solicitações antigas e impedem que respostas atrasadas sobrescrevam consultas mais recentes. Chame `ref.refresh()` da tabela quando condições de negócio externas à closure da fonte de dados mudarem. Mantenha a função da fonte de dados estável para evitar solicitações desnecessárias. A serialização RSQL é apenas um adaptador para backends que a exigem; ela não executa strings de consulta.
+
+## Uploads e persistência da aplicação
+
+O método `upload(files, signal)` de um campo retorna o valor do campo depois que a aplicação salva os arquivos. O componente exibe as falhas de upload; quem o utiliza fornece as URLs de upload, a autenticação e as políticas de armazenamento de objetos.
+
+```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>
+```
+
+Alterações locais são aplicadas imediatamente; salvamentos remotos são executados em série, com uma opção de nova tentativa após falhas. Ao alterar os formatos das configurações persistidas, use um novo id de tabela ou versão para evitar carregar configurações incompatíveis.

package/docs/i18n/ru/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)](../pt-BR/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 dependencies: 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/ru/CONTRIBUTING.md)
+- [История изменений](https://github.com/Zeroman/react-auto-components/blob/main/docs/i18n/ru/CHANGELOG.md)
+- [Настройка учётной записи и публикация](https://github.com/Zeroman/react-auto-components/blob/main/docs/i18n/ru/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. Тестовый проект содержит страницы для всех семи компонентов, локальные/серверные/древовидные таблицы и таблицы на 10 000 строк, CRUD, повторные попытки после неудачной отправки, черновики, вложенные вкладки и динамическую высоту строк.
+
+Демо автоматически определяет язык браузера, используя английский в качестве резервного. Выберите язык в шапке или в глобальных настройках; сделанный выбор сохраняется между перезагрузками страницы. Выберите «Авто», чтобы вновь следовать языку браузера. Поддерживается десять языков. Страницы заполняют область просмотра, при этом таблицы и длинные панели прокручиваются внутри собственных областей.
+
+На каждой странице примера есть кнопка **Просмотр кода**: она открывает настоящий исходный файл в диалоге — с вкладками файлов, копированием в один клик и ссылкой на 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`.
+
+## Поведение и соглашения
+
+- Это API, разработанный для React, а не слой совместимости с Vue, воспроизводящий каждое свойство или метод. См. [руководство по миграции](migration.md).
+- Данными управляет код приложения. Обработчики CRUD сохраняют изменения; исключение при ошибке сохраняет внесённые правки. После успеха компонент обновляет удалённые данные. Локальные данные должен обновить вызывающий код.
+- `id` таблицы должен быть уникален в её пространстве имён, а `rowKey` — среди всех страниц и узлов дерева. В серверном режиме явно задайте `columns`; источник данных возвращает общее количество записей.
+- При управляемых `query` / `value` родитель должен обрабатывать обратные вызовы и обновлять значение. Для неуправляемого использования эти пропсы можно опустить.
+- Объединённые ячейки используют невиртуализированную семантическую таблицу, подходящую для данных с пагинацией, чтобы избежать смещения rowSpan между виртуальными окнами.
+- Серверные итоги по всем отфильтрованным строкам передаются через `summaryValues`. Для отсутствующих итогов отображается `—`, а не сумма текущей страницы под видом общего итога. Задайте `summaryScope="page"`, чтобы явно вычислять итог текущей страницы.
+- Пока идёт загрузка файлов, отправка приостанавливается. Сброс, замена значений полей или размонтирование отменяют старые загрузки; запоздалые результаты не могут перезаписать новые значения.
+- При удалённом экспорте всех отфильтрованных результатов данные запрашиваются постранично. Крупные приложения могут реализовать собственный серверный экспорт.
+- Явно импортируйте браузерные стили из `style.css`. JavaScript-модули можно импортировать в Node без `window`.
+
+## Заполнение оставшейся высоты с помощью 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: 1; min-height: 0` во вложенных flex-контейнерах для передачи оставшегося пространства или `grid-template-rows: auto minmax(0, 1fr) auto` для grid-компоновки. Вычислять в 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>
+```
+
+Вложенные провайдеры объединяют настройки компоновки по отдельным свойствам. Явные пропсы компонента переопределяют окружающий провайдер. Например, можно сохранить верхние подписи в одной форме, используя подписи в строку глобально:
+
+```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"`; также допускается число пикселей или CSS-ширина, например `"6em"`. В автоматическом режиме каждая подпись поиска подстраивается под свой текст; обычные формы и формы диалогов используют общую ширину на основе видимых подписей для выравнивания элементов управления. Длинные подписи занимают не более 45 % ширины поля и затем переносятся, оставляя место элементам управления. На явно заданные фиксированные ширины это автоматическое ограничение не распространяется. Компактные области поиска располагают кнопки действий в той же строке, если места достаточно, и переносят их на узких экранах. Связи подписей с элементами сохраняются, ошибки и описания выравниваются по элементам управления, длинные подписи могут переноситься.
+
+В демо откройте **Глобальные настройки** через боковую панель или шестерёнку справа сверху, чтобы изменить компоновку, плотность, ширину подписей и тему. Изменения применяются сразу, не очищая текущий ввод. Страница формы поддерживает режим **Следовать глобальным настройкам** или локальные переопределения. Демо явно включает компактную компоновку с подписями в строку через свой провайдер.
+
+## Глобальные размер и плотность
+
+`AutoConfigProvider` поддерживает `size: "small" | "medium" | "large"` и `density: "compact" | "comfortable"`. Явные пропсы компонента имеют приоритет над настройками категории компонентов, а те — над глобальными значениями:
+
+```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` компонента имеет наивысший приоритет. Локальные размеры вложенных компонентов применяются независимо.
+
+Формы поддерживают `resetLabel`, `extraActions` и `onReset`; поисковые панели — `searchLabel`, `resetLabel` и `extraActions`; диалоги — `cancelLabel` и `extraActions`. Элементы `AutoTabs` могут задавать `badge`, а `AutoTable.empty` позволяет настроить содержимое пустого состояния.
+
+### AutoChat
+
+AutoChat предоставляет лёгкую компоновку диалога с отслеживанием потокового вывода, загрузкой истории и полем ввода. Для отображения сообщений передайте содержимое React или renderMessage; дополнительные runtime-зависимости не требуются.
+
+[AutoChat API](auto-chat.md)

package/docs/i18n/ru/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) | [한국어](../ko/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) | **Русский**
+
+Макет диалога с опциональным композером, следованием за потоком и загрузкой более ранней истории. 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` и `role`: `user`, `assistant`, `system`, `tool` или `error`. Необязательные `author`, `avatar`, `meta` и `streaming` настраивают оболочку; `renderActions(message, context)` добавляет действия для сообщения. При обновлении потокового ответа сохраняйте тот же ID и заменяйте массив messages неизменяемо.
+
+## Поведение и пропсы
+
+| Проп | Поведение |
+| --- | --- |
+| `height` | Высота в CSS, по умолчанию `100%`. Задайте родителю определённую высоту или передайте число, например `600`. История прокручивается внутри компонента. |
+| `autoFollow` | По умолчанию `true`. Следит за новым и изменившимся по высоте содержимым внизу; приостанавливается, когда читатель прокручивает вверх. **К последним** возобновляет слежение. |
+| `hasMore`, `onLoadOlder`, `loadingOlder` | Показывают кнопку более ранней истории. Сообщения добавляются в начало со стабильными ID; видимое сообщение остаётся на месте. Запросы дедуплицируются, отклонённый запрос можно повторить. |
+| `onSend(text)` | Включает композер. Получает исходный непустой текст; может вернуть промис. При принятии черновик очищается; при отклонении — сохраняется и показывается общая ошибка. Более новый черновик никогда не очищается более старой отправкой. |
+| `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` | Переопределяют встроенные английские подписи. Провайдер также переводит `chat.send`, `chat.latest` и другие ключи `chat.*`. |
+| `onSendError`, `onLoadError` | Получают исходную ошибку для журналирования приложения; внутренние детали ошибок автоматически не показываются. |
+
+Для больших историй включите `virtual`, чтобы использовать уже входящую в пакет зависимость TanStack Virtual. Монтируются только видимые сообщения и небольшое окно overscan; динамические высоты строк измеряются. При необходимости настройте `estimatedMessageHeight` (по умолчанию `120`) и `overscan` (по умолчанию `6`). При добавлении истории в начало сохраняйте стабильные ID сообщений. В виртуальном режиме храните в хосте интерактивное состояние, которое должно переживать размонтирование строк вне вьюпорта. Обычные диалоги по умолчанию используют невиртуальный макет.
+
+Демо **Большая история** загружает 1 000, 10 000 или 50 000 сообщений переменной высоты, сообщает фактическое число смонтированных сообщений и поддерживает добавление 100 сообщений, поток, загрузку более ранней истории и переход к любому концу.
+
+Реф `AutoChatHandle` предоставляет `scrollToBottom()`, `scrollToMessage(id)` (возвращает, существует ли ID), `focusComposer()` и `getScrollElement()`. История — фокусируемый с клавиатуры журнал; отдельная статусная область объявляет состояние отправки/генерации, не объявляя каждый токен потока.
+
+Локальную имитацию потока, отмену, пользовательскую карточку инструмента, пагинацию, ошибки отправки и интерфейс на десяти языках смотрите в [запускаемом демо](../../../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/ru/migration.md

@@ -0,0 +1,71 @@
+# Руководство по интеграции компонентов
+
+[English](../../migration.md) | [简体中文](../zh-CN/migration.md) | [繁體中文](../zh-TW/migration.md) | [日本語](../ja/migration.md) | [한국어](../ko/migration.md) | [Español](../es/migration.md) | [Français](../fr/migration.md) | [Deutsch](../de/migration.md) | [Português (Brasil)](../pt-BR/migration.md) | **Русский**
+
+Настройка компонентов выполняется через React-дженерики, колбэки и провайдеры. Приведённая ниже таблица сопоставляет типовые потребности приложений с публичными API и запускаемыми примерами.
+
+| Исходный сценарий | API React | Исполняемый пример / тест |
+| --- | --- | --- |
+| Поля формы и 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`, value/onChange, keepMounted | Страница вкладок; `tests/tabs.test.tsx` |
+| Списки сообщений чата и интерфейс диалога | `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` виртуализирует варианты выбора. Диапазоны дат используют два нативных поля ввода с отдельными подписями; `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>
+```
+
+Локальные изменения применяются сразу; удалённые сохранения выполняются последовательно, с возможностью повторной попытки после сбоя. При изменении форматов сохраняемых настроек используйте новый идентификатор таблицы или новую версию, чтобы избежать загрузки несовместимых настроек.