@zeroman.yang/react-auto-components 0.1.0

package/docs/i18n/es/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** | [Français](../fr/README.md) | [Deutsch](../de/README.md) | [Português (Brasil)](../pt-BR/README.md) | [Русский](../ru/README.md)
+
+Una biblioteca de componentes independiente y basada en esquemas para React 19, con formularios, tablas y chat. Construida con TypeScript, TanStack Table 9 / Form / Virtual, Radix y Floating UI, sin Ant Design, Element Plus ni MUI. Las compilaciones de la biblioteca usan React Compiler.
+
+[![Auto Studio Demo](../../assets/demo.png)](https://zeroman.github.io/react-auto-components/)
+
+<p align="center">
+  <a href="https://zeroman.github.io/react-auto-components/"><strong>🚀 Demo en vivo (GitHub Pages)</strong></a> · <a href="#ejecutar-el-proyecto-de-pruebas-independiente">Ejecución local</a> · <a href="#componentes">Componentes</a>
+</p>
+
+## Estado del proyecto
+
+La versión actual es 0.1.0 y las API aún pueden cambiar. Se requiere React 19. El paquete proporciona declaraciones ESM y de TypeScript. El texto integrado de la interfaz tiene el chino como idioma predeterminado y puede traducirse mediante AutoConfigProvider.config.t.
+
+Instálalo con `pnpm add @zeroman.yang/react-auto-components` (npm y yarn funcionan igual). Las peer dependencies son React 19 y react-dom 19. Importa la hoja de estilos una vez: `import "@zeroman.yang/react-auto-components/style.css"`.
+
+- [Demo en vivo (GitHub Pages)](https://zeroman.github.io/react-auto-components/)
+- [Contribuir](https://github.com/Zeroman/react-auto-components/blob/main/docs/i18n/es/CONTRIBUTING.md)
+- [Registro de cambios](https://github.com/Zeroman/react-auto-components/blob/main/docs/i18n/es/CHANGELOG.md)
+- [Configuración de la cuenta y publicación](https://github.com/Zeroman/react-auto-components/blob/main/docs/i18n/es/publishing.md)
+- [Licencia MIT](../../../LICENSE)
+
+## Ejecutar el proyecto de pruebas independiente
+
+Requiere Node.js >= 22.12 y pnpm 12.5.
+
+```sh
+pnpm install --frozen-lockfile
+pnpm prepare:test-project
+pnpm --dir test-project dev
+```
+
+Abra http://127.0.0.1:4173. El proyecto de pruebas incluye páginas para los siete componentes, tablas locales/del lado del servidor/de 10 000 filas/en árbol, CRUD, reintentos de envíos fallidos, borradores, pestañas anidadas y alturas de fila dinámicas.
+
+La demo detecta automáticamente el idioma del navegador, con el inglés como alternativa predeterminada. Elija un idioma desde el encabezado o en la configuración global; la selección se recuerda entre recargas. Seleccione Auto para volver a seguir el idioma del navegador. Se admiten diez idiomas. Las páginas llenan el viewport, con tablas y paneles largos que se desplazan dentro de sus propias áreas.
+
+Cada página de ejemplo incluye un botón **Ver código** que abre su archivo fuente real en un diálogo, con pestañas de archivo, copia en un clic y un enlace a GitHub.
+
+`test-project` tiene sus propios archivos package.json y de bloqueo. Instala el resultado real de `pnpm pack`, sin alias al código fuente. Ejecute de nuevo `pnpm prepare:test-project` después de modificar la biblioteca; el script utiliza nombres de archivo con un hash del contenido para evitar cachés de archivos tarball obsoletos.
+
+## 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: 'Nombre', sortable: true },
+  { key: 'enabled', label: 'Activado', options: [
+    { label: 'Sí', value: true }, { label: 'No', value: false },
+  ] },
+];
+const fields: Field<Person>[] = [
+  { name: 'name', label: 'Nombre', required: true },
+  { name: 'enabled', label: 'Activado', 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>;
+}
+```
+
+Los campos, las columnas y las referencias utilizan genéricos: los nombres de campo o valores predeterminados no válidos producen errores en tiempo de compilación. El proveedor admite espacios de nombres, permisos, traducción de etiquetas de campos, campos personalizados, notificaciones y adaptadores de persistencia. Las etiquetas integradas, los mensajes de validación y el texto de accesibilidad usan AutoConfigProvider.config.t; las etiquetas explícitas de los componentes tienen prioridad.
+
+La función de devolución de llamada t recibe una clave de mensaje y un texto alternativo. Conserve los marcadores de posición numerados como {0} y {1} en los mensajes integrados traducidos; los componentes sustituyen sus valores después de la traducción.
+
+## Componentes
+
+| Componente | Capacidades |
+| --- | --- |
+| AutoForm | Tipos de campo nativos, opciones virtualizadas, selección en cascada, adaptadores de carga, renderizado personalizado, campos dependientes, visibilidad condicional, validación asíncrona, estado controlado y conservación de los datos introducidos tras errores |
+| AutoSearchPanel | Condiciones básicas/avanzadas, búsqueda manual/instantánea, restablecimiento, etiquetas de ordenación, un AST de consulta compartido y serialización RSQL |
+| AutoTable | Datos locales/remotos, ordenación por varias columnas, filtros de columna, paginación, selección estable, virtualización, expansión de árboles/detalles, resúmenes, celdas combinadas, CRUD, menús contextuales y copia |
+| AutoDialog | API declarativas/imperativas, proveedores aislados, borradores, protección de cierre, gestión del foco, arrastre, pantalla completa y envío asíncrono |
+| AutoTabs | Diseños horizontales/verticales, anidamiento, permisos, pestañas deshabilitadas, conservación del estado de los paneles y actualización |
+| AutoMenu | Navegación lateral con iconos, descripciones, insignias, grupos anidados, permisos y una barra de iconos plegable |
+| AutoChat | Renderizado de mensajes controlado por el llamador, virtualización opcional, seguimiento de streaming, carga de historial anclada, compositor con envío/detención y acciones personalizadas |
+
+El diseño de la tabla, la ordenación, el filtrado y la exportación admiten cada uno ajustes preestablecidos con nombre y versiones independientes. La persistencia utiliza localStorage de forma predeterminada; se pueden inyectar adaptadores remotos. La exportación JSON/CSV está integrada. XLSX utiliza un adaptador opcional e independiente:
+
+```tsx
+import { exportXlsx } from '@zeroman.yang/react-auto-components/xlsx';
+// <AutoTable ... exportXlsx={exportXlsx} />
+```
+
+ExcelJS se carga dinámicamente la primera vez que se utiliza el adaptador y queda excluido del punto de entrada principal de la biblioteca. Las aplicaciones que solo utilicen CSV/JSON pueden omitir las dependencias opcionales durante la instalación.
+
+## Verificación
+
+```sh
+pnpm typecheck
+pnpm test
+pnpm build
+pnpm prepare:test-project
+pnpm --dir test-project build
+pnpm exec playwright install chromium  # Solo en la primera ejecución
+pnpm test:e2e
+```
+
+Las pruebas unitarias cubren campos, validación asíncrona, consultas, diálogos, virtualización, tablas, migraciones de configuración y exportaciones. Las pruebas de Playwright comprueban las interacciones mediante los puntos de entrada públicos del paquete. Las capturas de pantalla de escritorio y móvil se guardan en `test-project/test-results`.
+
+## Comportamiento y convenciones
+
+- Esta es una API nativa de React, no una capa de compatibilidad con Vue propiedad por propiedad o método por método. Consulte la [guía de migración](migration.md).
+- El código de la aplicación es responsable de los datos. Las funciones de retorno de CRUD guardan los cambios; lanzar una excepción ante un error conserva las ediciones. Tras una operación correcta, el componente actualiza los datos remotos. Quien lo invoca debe actualizar los datos locales.
+- El `id` de una tabla debe ser único dentro de su espacio de nombres, y `rowKey` debe ser único en todas las páginas y nodos del árbol. En modo de servidor, proporcione `columns` explícitamente; la fuente de datos devuelve el recuento total.
+- Cuando `query` / `value` están controlados, el componente padre debe gestionar las funciones de retorno y actualizar su valor. Estas propiedades se pueden omitir para un uso no controlado.
+- Las celdas combinadas utilizan una tabla semántica no virtualizada, adecuada para datos paginados, para evitar desalineaciones de rowSpan entre ventanas virtuales.
+- Los resúmenes del servidor para todas las filas filtradas se proporcionan mediante `summaryValues`. Los resúmenes ausentes muestran `—` en lugar de presentar el total de la página actual como un total general. Establezca `summaryScope="page"` para calcular explícitamente la página actual.
+- El envío se pausa mientras hay cargas en curso. Restablecer o sustituir los valores de los campos, o desmontar el componente, cancela las cargas anteriores; los resultados tardíos no pueden sobrescribir valores más recientes.
+- Las exportaciones remotas de todos los resultados filtrados solicitan los datos de página en página. Las aplicaciones grandes pueden implementar su propia exportación del lado del servidor.
+- Importe explícitamente los estilos del navegador desde `style.css`. Los módulos JavaScript se pueden importar en Node sin `window`.
+
+## Ocupar la altura restante con AutoTable
+
+`height={440}` sigue estableciendo una altura fija para el área de desplazamiento de datos. Con `height="auto"`, la tabla completa ocupa la altura asignada por el diseño de su contenedor padre. La búsqueda, la barra de herramientas y la paginación mantienen sus alturas naturales; el área de datos utiliza el espacio restante y se desplaza de forma independiente:
+
+```tsx
+<div style={{ height: '100dvh', display: 'flex', flexDirection: 'column', gap: 12 }}>
+  <header>Título y descripción de la página</header>
+  <AutoTable<Person> id="people" rowKey="id" data={rows}
+    columns={columns} height="auto" />
+  <footer>Pie de página</footer>
+</div>
+```
+
+El contenedor padre debe tener una altura definida. Utilice `flex: 1; min-height: 0` en contenedores flex anidados para transmitir el espacio restante, o `grid-template-rows: auto minmax(0, 1fr) auto` en diseños de cuadrícula. No es necesario calcular en JavaScript la altura de la ventana menos la altura de la barra de herramientas: el diseño gestiona la adición y eliminación de campos de búsqueda, las barras de herramientas en varias líneas y los cambios de tamaño del contenedor padre; la lista virtual se adapta a las dimensiones reales del área de desplazamiento.
+
+Esto no ajusta el tamaño de la tabla al número de filas. Los conjuntos de datos vacíos o pequeños siguen ocupando el espacio disponible. El contenedor padre debe poder alojar como mínimo el área de búsqueda, la barra de herramientas y la paginación.
+
+El proyecto de pruebas lo muestra en la pestaña **AutoTable → Altura restante**, conservando la barra lateral y la cabecera de la página. La URL heredada `http://127.0.0.1:4173/?demo=auto-height` selecciona directamente esa pestaña. Pruebas del navegador: `test-project/tests/auto-height.spec.ts`.
+
+## Diseño global de formularios
+
+Utilice `AutoConfigProvider.config.form` para configurar de forma coherente los formularios normales, los paneles de búsqueda, las áreas de búsqueda de las tablas y los formularios de diálogo. Las etiquetas pueden aparecer encima o a la izquierda de los controles, con alineación de texto izquierda/derecha independiente. Los valores predeterminados son etiquetas superiores y espaciado cómodo.
+
+```tsx
+<AutoConfigProvider config={{
+  form: {
+    labelPosition: 'left', // 'top': arriba; 'left': a la izquierda del control
+    labelAlign: 'right',   // Texto alineado a la derecha; la etiqueta queda a la izquierda del control
+    labelWidth: 80,
+    density: 'compact',   // 'comfortable': más espaciado
+  },
+}}>
+  <App />
+</AutoConfigProvider>
+```
+
+Los proveedores anidados combinan los ajustes de diseño propiedad por propiedad. Las propiedades explícitas de los componentes prevalecen sobre el proveedor que los engloba. Por ejemplo, mantenga las etiquetas superiores en un formulario mientras utiliza etiquetas en línea 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` vale `"auto"` de forma predeterminada y también admite un número de píxeles o una anchura CSS como `"6em"`. En modo automático, cada etiqueta de búsqueda se adapta a su texto; los formularios normales y de diálogo comparten una anchura basada en las etiquetas visibles para alinear los controles. Las etiquetas largas ocupan como máximo el 45 % de la anchura del campo y pasan a varias líneas a partir de ahí, conservando espacio para los controles. Las anchuras fijas explícitas no están sujetas a este límite automático. Las áreas de búsqueda compactas colocan los botones de acción en la misma fila cuando hay espacio y los distribuyen en varias líneas en pantallas estrechas. Las asociaciones de etiquetas permanecen intactas, los errores y las descripciones se alinean con los controles, y las etiquetas largas pueden ocupar varias líneas.
+
+En la demostración, abra **Configuración global** desde la barra lateral o el engranaje de la esquina superior derecha para cambiar el diseño, la densidad, la anchura de las etiquetas y el tema. Los cambios surten efecto de inmediato sin borrar los datos introducidos. La página de formularios admite **Seguir la configuración global** o ajustes locales. La demostración activa explícitamente el diseño compacto en línea mediante su proveedor.
+
+## Tamaño y densidad globales
+
+`AutoConfigProvider` admite `size: "small" | "medium" | "large"` y `density: "compact" | "comfortable"`. Las propiedades explícitas de los componentes tienen prioridad sobre los ajustes de la categoría del componente, que a su vez tienen prioridad sobre los valores globales:
+
+```tsx
+<AutoConfigProvider config={{
+  size: "medium",
+  density: "compact",
+  form: { labelPosition: "left", labelAlign: "right" },
+  table: { density: "compact" },
+  tabs: { density: "compact" },
+}}>
+  <AutoForm fields={fields} size="small" />
+</AutoConfigProvider>
+```
+
+La densidad de la tabla también admite `normal`. El panel de ajustes de la tabla sigue la configuración global de forma predeterminada. Seleccionar un espaciado compacto, normal o cómodo sustituye la densidad global y se guarda con el ajuste preestablecido de diseño; la propiedad `density` del componente tiene la máxima prioridad. Los tamaños locales de los componentes anidados se aplican de forma independiente.
+
+Los formularios admiten `resetLabel`, `extraActions` y `onReset`; los paneles de búsqueda admiten `searchLabel`, `resetLabel` y `extraActions`; los diálogos admiten `cancelLabel` y `extraActions`. Los elementos de `AutoTabs` pueden definir un `badge`, y `AutoTable.empty` personaliza el contenido del estado vacío.
+
+### AutoChat
+
+AutoChat proporciona una disposición de conversación ligera con seguimiento automático del streaming, carga del historial y un área de redacción. Usa contenido de React o renderMessage para renderizar los mensajes; no se necesitan dependencias adicionales en tiempo de ejecución.
+
+[AutoChat API](auto-chat.md)

package/docs/i18n/es/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** | [Français](../fr/auto-chat.md) | [Deutsch](../de/auto-chat.md) | [Português (Brasil)](../pt-BR/auto-chat.md) | [Русский](../ru/auto-chat.md)
+
+Un diseño de conversación con compositor opcional, seguimiento de streaming y carga de historial anterior. AutoChat no añade dependencias en tiempo de ejecución y no realiza peticiones de red, ni persiste mensajes, ni analiza Markdown, ni ejecuta salida de herramientas, ni renderiza HTML sin procesar.
+
+## 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 },
+        ]);
+        // Llama aquí a tu servicio y actualiza messages.
+      }}
+    />
+  );
+}
+```
+
+## Trae tu propio renderizador
+
+Pasa nodos React como `content`, o amplía `AutoChatMessage` con los campos de tu aplicación y proporciona `renderMessage(message, { index })`. Conecta ahí un renderizador de Markdown existente, un visor de código, una tarjeta de adjuntos o un componente de resultado de herramientas. AutoChat nunca interpreta esos formatos; una cadena simple se renderiza como texto. El renderizador anfitrión controla los enlaces, el HTML y cualquier contenido interactivo.
+
+Cada mensaje tiene un `id` único y estable y un `role`: `user`, `assistant`, `system`, `tool` o `error`. Los campos opcionales `author`, `avatar`, `meta` y `streaming` personalizan su estructura; `renderActions(message, context)` aporta acciones por mensaje. Mantén el mismo ID al actualizar una respuesta en streaming y sustituye el array de mensajes de forma inmutable.
+
+## Comportamiento y props
+
+| Prop | Comportamiento |
+| --- | --- |
+| `height` | Altura CSS, por defecto `100%`. Da al contenedor padre una altura definida o pasa un número como `600`. El historial se desplaza dentro del componente. |
+| `autoFollow` | Por defecto `true`. Sigue el contenido nuevo y redimensionado al final; se pausa cuando el lector sube. **Volver al final** reanuda el seguimiento. |
+| `hasMore`, `onLoadOlder`, `loadingOlder` | Muestran un botón de historial anterior. Antepone mensajes con IDs estables; el mensaje visible permanece anclado. Las peticiones se deduplican y una petición rechazada puede reintentarse. |
+| `onSend(text)` | Habilita el compositor. Recibe el texto original no vacío; puede devolver una promesa. Al aceptar, limpia ese borrador; al rechazar, lo conserva y muestra un error genérico. Un borrador más nuevo nunca lo limpia un envío más antiguo. |
+| `value`, `defaultValue`, `onValueChange` | Valor del compositor controlado o local. Con un valor controlado, aplica los cambios en el host. |
+| `generating`, `onStop` | Desactiva envíos durante la generación y expone un botón de detención. El host debe cancelar su propio flujo/petición y actualizar `generating`. |
+| `sendOnEnter` | Por defecto `true`; Shift+Enter inserta un salto de línea. Los eventos de composición y la confirmación IME nunca envían. Ponlo en `false` para enviar solo con botón. |
+| `disabled`, `composer` | Desactiva el editor integrado o lo oculta (`composer={false}`) al usar un editor externo. |
+| `conversationKey` | Restablece borrador local, UI pendiente y scroll al cambiar de conversación. Los valores controlados y la cancelación siguen siendo del host. |
+| `header`, `footer`, `empty`, `composerExtra` | Slots de contenido React. |
+| `size`, `density` | Anulan los ajustes globales de `AutoConfigProvider`. |
+| `labels` | Anulan las etiquetas inglesas integradas. El provider también traduce `chat.send`, `chat.latest` y otras claves `chat.*`. |
+| `onSendError`, `onLoadError` | Reciben el error original para registro de la aplicación; los detalles internos del error no se muestran automáticamente. |
+
+Para historiales grandes, activa `virtual` para usar la dependencia TanStack Virtual ya incluida en el paquete. Solo se montan los mensajes visibles y una pequeña ventana de overscan; las alturas dinámicas se miden. Ajusta si hace falta `estimatedMessageHeight` (por defecto `120`) y `overscan` (por defecto `6`). Mantén IDs de mensaje estables al anteponer historial. En modo virtual, guarda en el host el estado interactivo que deba sobrevivir a filas desmontadas fuera del viewport. Las conversaciones normales usan por defecto el diseño no virtual.
+
+La demo de **Historial grande** carga 1.000, 10.000 o 50.000 mensajes de altura variable, informa del número real de mensajes montados y permite añadir 100 mensajes, streaming, cargar historial anterior y saltar a cualquiera de los extremos.
+
+El ref `AutoChatHandle` expone `scrollToBottom()`, `scrollToMessage(id)` (devuelve si el ID existe), `focusComposer()` y `getScrollElement()`. El historial usa un registro enfocable por teclado; una región de estado independiente anuncia el estado de envío/generación sin anunciar cada token del streaming.
+
+Consulta [la demo ejecutable](../../../test-project/src/examples/ChatDemo.tsx) para una simulación local de streaming, cancelación, una tarjeta de herramienta personalizada, paginación, fallos de envío y una interfaz en diez idiomas.
+
+## Renderizado enriquecido en la demo
+
+El `test-project` privado instala [react-markdown](https://github.com/remarkjs/react-markdown) y [remark-gfm](https://github.com/remarkjs/remark-gfm). Estas dependencias no forman parte de la biblioteca de componentes. Su selector de formatos inserta Markdown (encabezados, énfasis, listas de tareas y tablas GFM), código, JSON, tablas de datos, una imagen local o una tarjeta React interactiva de reseña.
+
+`ChatRenderers.tsx` elige componentes React a partir de datos de mensaje estructurados. `ChatTaskCard.tsx` demuestra estado interactivo local. Markdown usa `skipHtml` y el manejo de URLs por defecto de la biblioteca; no compila JSX ni ejecuta bloques de código. El mismo renderizador de Markdown muestra las respuestas en streaming. Los componentes personalizados los aporta la aplicación, no se instancian desde texto de mensaje ejecutable.
+
+```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/es/migration.md

@@ -0,0 +1,71 @@
+# Guía de integración de componentes
+
+[English](../../migration.md) | [简体中文](../zh-CN/migration.md) | [繁體中文](../zh-TW/migration.md) | [日本語](../ja/migration.md) | [한국어](../ko/migration.md) | **Español** | [Français](../fr/migration.md) | [Deutsch](../de/migration.md) | [Português (Brasil)](../pt-BR/migration.md) | [Русский](../ru/migration.md)
+
+Configura los componentes mediante generics, callbacks y providers de React. La siguiente tabla relaciona las necesidades comunes de las aplicaciones con las API públicas y los ejemplos ejecutables.
+
+| Caso de uso original | API de React | Ejemplo ejecutable / prueba |
+| --- | --- | --- |
+| Campos de formulario y v-model | `fields: Field<T>[]`, `value/onChange` o `defaultValue` | Página de formularios en `test-project/src/examples/FormDemo.tsx`; `tests/form*.test.tsx` |
+| Slots y contenido añadido | `render` del campo, `render/header` de la columna, ReactNode | Páginas de formularios/tablas |
+| Operaciones de instancia del formulario | `ref.validate/reset/getValues/setValue/focus` | `tests/form.test.tsx` |
+| Búsqueda, condiciones relacionadas, RSQL | `buildQuery`, `matchesQuery`, `serializeRsql` | Página de búsqueda; `tests/query.test.ts` |
+| Datos de tabla locales/remotos | `data` o `dataSource(query,{signal})` | Página de tablas; `tests/table.test.tsx` |
+| Ajustes preestablecidos de diseño/filtro/ordenación/exportación | Ajustes preestablecidos independientes en el diálogo de configuración, invalidados por separado mediante `versions` | Página de tablas; `tests/table-settings.test.ts` |
+| Árboles, detalles, resúmenes, celdas combinadas | `getChildren/renderExpanded`, `summary/merge` de la columna | Ejemplos de árboles y expansión; `tests/table-advanced.test.tsx` |
+| Añadir, editar, eliminar | `formFields` y `onAdd/onEdit/onDelete` | Pruebas de CRUD en el navegador |
+| Diálogos imperativos | `AutoDialogProvider` + `useAutoDialog().open()` | Página de diálogos; `tests/dialog.test.tsx` |
+| Pestañas y pestañas anidadas | Elementos de `AutoTabs`, value/onChange, keepMounted | Página de pestañas; `tests/tabs.test.tsx` |
+| Listas de mensajes de chat y UI de conversación | `AutoChat`, `messages`, `onSend`, `renderMessage` | Páginas de chat en `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 las opciones. Los intervalos de fechas utilizan dos campos nativos con etiquetas separadas; `dateValue` elige entre cadenas y marcas de tiempo. Los campos numéricos permiten estados intermedios de edición; utilice reglas de campo para validar las restricciones de negocio al enviar. `rules` admite validación asíncrona, mientras que los campos ocultos omiten la validación. Las opciones conservan los valores numéricos y booleanos en lugar de convertirlos en cadenas.
+
+```tsx
+const fields: Field<User>[] = [
+  { name: 'name', label: 'Nombre', required: true },
+  { name: 'note', label: 'Nota', hidden: values => !values.enabled,
+    render: ({ value, onChange, disabled }) =>
+      <textarea disabled={disabled} value={String(value ?? '')}
+        onChange={event => onChange(event.target.value)} /> },
+];
+```
+
+Consulte los tipos de TypeScript exportados para ver la API completa. `Field<T>` se vincula a claves reales de T; los elementos estructurales, como títulos y consejos, no necesitan una propiedad de datos.
+
+## Fuentes de datos del lado del 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('Error al cargar');
+  return response.json(); // { rows: User[], total: number }
+};
+```
+
+Los índices de página comienzan en 0. `sort` es un arreglo ordenado de campos; `filter` es un árbol de consulta estructurado. Los componentes cancelan las solicitudes antiguas e impiden que las respuestas tardías sobrescriban consultas más recientes. Llame a `ref.refresh()` de la tabla cuando cambien condiciones de negocio externas al cierre de la fuente de datos. Mantenga estable la función de la fuente de datos para evitar solicitudes innecesarias. La serialización RSQL es solo un adaptador para los servidores que la requieren; no ejecuta cadenas de consulta.
+
+## Cargas y persistencia de la aplicación
+
+El método `upload(files, signal)` de un campo devuelve el valor del campo después de que la aplicación guarde los archivos. El componente muestra los errores de carga; quien lo invoca proporciona las URL de carga, la autenticación y las políticas de almacenamiento 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>
+```
+
+Los cambios locales se aplican de inmediato; los guardados remotos se ejecutan en serie, con una opción de reintento tras los fallos. Al cambiar los formatos de las configuraciones persistidas, usa un nuevo id de tabla o versión para evitar cargar configuraciones incompatibles.

package/docs/i18n/fr/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** | [Deutsch](../de/README.md) | [Português (Brasil)](../pt-BR/README.md) | [Русский](../ru/README.md)
+
+Une bibliothèque de composants autonome et pilotée par schéma pour React 19, couvrant formulaires, tableaux et chat. Construite avec TypeScript, TanStack Table 9 / Form / Virtual, Radix et Floating UI, sans Ant Design, Element Plus ni MUI. Les builds de la bibliothèque utilisent React Compiler.
+
+[![Auto Studio Démo](../../assets/demo.png)](https://zeroman.github.io/react-auto-components/)
+
+<p align="center">
+  <a href="https://zeroman.github.io/react-auto-components/"><strong>🚀 Démo en direct (GitHub Pages)</strong></a> · <a href="#exécuter-le-projet-de-test-autonome">Exécution locale</a> · <a href="#composants">Composants</a>
+</p>
+
+## État du projet
+
+La version actuelle est 0.1.0 et les API peuvent encore évoluer. React 19 est requis. Le paquet fournit ESM et des déclarations TypeScript. Les textes d'interface intégrés sont en chinois par défaut et peuvent être traduits via AutoConfigProvider.config.t.
+
+Installez-le avec `pnpm add @zeroman.yang/react-auto-components` (npm et yarn conviennent aussi). Les peer dependencies sont React 19 et react-dom 19. Importez la feuille de style une fois : `import "@zeroman.yang/react-auto-components/style.css"`.
+
+- [Démo en direct (GitHub Pages)](https://zeroman.github.io/react-auto-components/)
+- [Contribuer](https://github.com/Zeroman/react-auto-components/blob/main/docs/i18n/fr/CONTRIBUTING.md)
+- [Journal des modifications](https://github.com/Zeroman/react-auto-components/blob/main/docs/i18n/fr/CHANGELOG.md)
+- [Configuration du compte et publication](https://github.com/Zeroman/react-auto-components/blob/main/docs/i18n/fr/publishing.md)
+- [Licence MIT](../../../LICENSE)
+
+## Exécuter le projet de test autonome
+
+Nécessite Node.js >= 22.12 et pnpm 12.5.
+
+```sh
+pnpm install --frozen-lockfile
+pnpm prepare:test-project
+pnpm --dir test-project dev
+```
+
+Ouvrez http://127.0.0.1:4173. Le projet de test comprend des pages pour les sept composants, des tableaux locaux/côté serveur/de 10 000 lignes/arborescents, les opérations CRUD, les nouvelles tentatives après un échec d’envoi, les brouillons, les onglets imbriqués et les hauteurs de ligne dynamiques.
+
+La démo détecte automatiquement la langue du navigateur, avec l'anglais comme solution de repli. Choisissez une langue dans l'en-tête ou dans les paramètres globaux ; votre sélection est conservée après rechargement. Sélectionnez Auto pour suivre à nouveau la langue du navigateur. Dix langues sont prises en charge. Les pages remplissent la fenêtre (viewport), les tableaux et les longs panneaux défilant à l'intérieur de leurs propres zones.
+
+Chaque page d'exemple inclut un bouton **Voir le code** qui ouvre son véritable fichier source dans une boîte de dialogue, avec onglets de fichiers, copie en un clic et lien GitHub.
+
+`test-project` possède ses propres fichiers package.json et de verrouillage. Il installe la sortie réelle de `pnpm pack`, sans alias vers les sources. Exécutez de nouveau `pnpm prepare:test-project` après avoir modifié la bibliothèque ; le script utilise des noms de fichiers contenant une empreinte du contenu pour éviter les caches d’archives tarball obsolètes.
+
+## Utilisation
+
+```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: 'Nom', sortable: true },
+  { key: 'enabled', label: 'Activé', options: [
+    { label: 'Oui', value: true }, { label: 'Non', value: false },
+  ] },
+];
+const fields: Field<Person>[] = [
+  { name: 'name', label: 'Nom', required: true },
+  { name: 'enabled', label: 'Activé', 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>;
+}
+```
+
+Les champs, les colonnes et les références utilisent des génériques : les noms de champ ou les valeurs par défaut non valides provoquent des erreurs à la compilation. Le fournisseur prend en charge les espaces de noms, les autorisations, la traduction des libellés de champ, les champs personnalisés, les notifications et les adaptateurs de persistance. Les libellés intégrés, les messages de validation et les textes d'accessibilité utilisent AutoConfigProvider.config.t ; les libellés explicites des composants ont la priorité.
+
+Le callback t reçoit une clé de message et un texte de repli. Conservez les espaces réservés numérotés tels que {0} et {1} dans les messages intégrés traduits ; les composants y substituent leurs valeurs après la traduction.
+
+## Composants
+
+| Composant | Fonctionnalités |
+| --- | --- |
+| AutoForm | Types de champ natifs, options virtualisées, sélection en cascade, adaptateurs de téléversement, rendu personnalisé, champs dépendants, visibilité conditionnelle, validation asynchrone, état contrôlé et conservation des saisies après un échec |
+| AutoSearchPanel | Conditions simples/avancées, recherche manuelle/instantanée, réinitialisation, étiquettes de tri, AST de requête partagé et sérialisation RSQL |
+| AutoTable | Données locales/distantes, tri multicolonne, filtres de colonne, pagination, sélection stable, virtualisation, dépliage d’arbres/de détails, synthèses, cellules fusionnées, CRUD, menus contextuels et copie |
+| AutoDialog | API déclaratives/impératives, fournisseurs isolés, brouillons, protection contre la fermeture, gestion du focus, déplacement par glisser, plein écran et envoi asynchrone |
+| AutoTabs | Dispositions horizontales/verticales, imbrication, autorisations, onglets désactivés, conservation de l’état des panneaux et actualisation |
+| AutoMenu | Navigation latérale avec icônes, descriptions, badges, groupes imbriqués, permissions et barre d'icônes repliable |
+| AutoChat | Rendu des messages contrôlé par l'appelant, virtualisation optionnelle, suivi de flux, chargement d'historique ancré, composeur envoi/arrêt et actions personnalisées |
+
+La disposition du tableau, le tri, le filtrage et l’exportation prennent chacun en charge des préréglages nommés et des versions indépendantes. La persistance utilise localStorage par défaut ; des adaptateurs distants peuvent être injectés. L’exportation JSON/CSV est intégrée. XLSX utilise un adaptateur facultatif séparé :
+
+```tsx
+import { exportXlsx } from '@zeroman.yang/react-auto-components/xlsx';
+// <AutoTable ... exportXlsx={exportXlsx} />
+```
+
+ExcelJS est chargé dynamiquement à la première utilisation de l’adaptateur et n’est pas inclus dans le point d’entrée principal de la bibliothèque. Les applications qui utilisent uniquement CSV/JSON peuvent omettre les dépendances facultatives lors de l’installation.
+
+## Vérification
+
+```sh
+pnpm typecheck
+pnpm test
+pnpm build
+pnpm prepare:test-project
+pnpm --dir test-project build
+pnpm exec playwright install chromium  # Première exécution uniquement
+pnpm test:e2e
+```
+
+Les tests unitaires couvrent les champs, la validation asynchrone, les requêtes, les boîtes de dialogue, la virtualisation, les tableaux, les migrations de configuration et les exportations. Les tests Playwright vérifient les interactions via les points d’entrée publics du paquet. Les captures d’écran pour ordinateur et mobile sont enregistrées dans `test-project/test-results`.
+
+## Comportement et conventions
+
+- Il s’agit d’une API native de React, et non d’une couche de compatibilité avec Vue propriété par propriété ou méthode par méthode. Consultez le [guide de migration](migration.md).
+- Le code de l’application est responsable des données. Les fonctions de rappel CRUD enregistrent les modifications ; lever une exception en cas d’échec préserve les éditions. Après un succès, le composant actualise les données distantes. Les données locales doivent être mises à jour par l’appelant.
+- L’`id` d’un tableau doit être unique dans son espace de noms, et `rowKey` doit être unique sur l’ensemble des pages et des nœuds de l’arbre. En mode serveur, fournissez explicitement `columns` ; la source de données renvoie le nombre total.
+- Lorsque `query` / `value` sont contrôlés, le parent doit gérer les fonctions de rappel et mettre à jour leur valeur. Ces propriétés peuvent être omises pour une utilisation non contrôlée.
+- Les cellules fusionnées utilisent un tableau sémantique non virtualisé, adapté aux données paginées, pour éviter les décalages de rowSpan entre les fenêtres virtuelles.
+- Les synthèses côté serveur de toutes les lignes filtrées sont fournies via `summaryValues`. Les synthèses manquantes affichent `—` au lieu de présenter le total de la page courante comme un total général. Définissez `summaryScope="page"` pour calculer explicitement la page courante.
+- L’envoi est suspendu pendant les téléversements. Réinitialiser ou remplacer les valeurs des champs, ou démonter le composant, annule les anciens téléversements ; les résultats tardifs ne peuvent pas écraser des valeurs plus récentes.
+- Les exportations distantes de tous les résultats filtrés demandent les données une page à la fois. Les grandes applications peuvent implémenter leur propre exportation côté serveur.
+- Importez explicitement les styles du navigateur depuis `style.css`. Les modules JavaScript peuvent être importés dans Node sans `window`.
+
+## Remplir la hauteur restante avec AutoTable
+
+`height={440}` continue de définir une hauteur fixe pour la zone de défilement des données. Avec `height="auto"`, le tableau entier remplit la hauteur attribuée par la disposition du parent. La recherche, la barre d’outils et la pagination conservent leur hauteur naturelle ; la zone de données occupe l’espace restant et défile indépendamment :
+
+```tsx
+<div style={{ height: '100dvh', display: 'flex', flexDirection: 'column', gap: 12 }}>
+  <header>Titre et description de la page</header>
+  <AutoTable<Person> id="people" rowKey="id" data={rows}
+    columns={columns} height="auto" />
+  <footer>Pied de page</footer>
+</div>
+```
+
+Le parent doit avoir une hauteur définie. Utilisez `flex: 1; min-height: 0` dans les conteneurs flex imbriqués pour transmettre l’espace restant, ou `grid-template-rows: auto minmax(0, 1fr) auto` pour les dispositions en grille. Il n’est pas nécessaire de calculer en JavaScript la hauteur de la fenêtre moins celle de la barre d’outils : la mise en page gère l’ajout et la suppression de champs de recherche, les barres d’outils sur plusieurs lignes et le redimensionnement du parent ; la liste virtuelle suit les dimensions réelles de la zone de défilement.
+
+Cela ne dimensionne pas le tableau selon le nombre de lignes. Les jeux de données vides ou de petite taille remplissent toujours l’espace disponible. Le parent doit au minimum pouvoir contenir la zone de recherche, la barre d’outils et la pagination.
+
+Le projet de test illustre ce fonctionnement dans l’onglet **AutoTable → Hauteur restante**, tout en conservant la barre latérale et l’en-tête de page. L’ancienne URL `http://127.0.0.1:4173/?demo=auto-height` sélectionne directement cet onglet. Tests dans le navigateur : `test-project/tests/auto-height.spec.ts`.
+
+## Disposition globale des formulaires
+
+Utilisez `AutoConfigProvider.config.form` pour configurer de manière cohérente les formulaires ordinaires, les panneaux de recherche, les zones de recherche des tableaux et les formulaires des boîtes de dialogue. Les libellés peuvent apparaître au-dessus ou à gauche des contrôles, avec un alignement du texte à gauche/à droite indépendant. Par défaut, les libellés sont au-dessus et l’espacement est confortable.
+
+```tsx
+<AutoConfigProvider config={{
+  form: {
+    labelPosition: 'left', // 'top' : au-dessus ; 'left' : à gauche du contrôle
+    labelAlign: 'right',   // Texte aligné à droite ; le libellé reste à gauche du contrôle
+    labelWidth: 80,
+    density: 'compact',   // 'comfortable' : espacement plus généreux
+  },
+}}>
+  <App />
+</AutoConfigProvider>
+```
+
+Les fournisseurs imbriqués fusionnent les paramètres de disposition propriété par propriété. Les propriétés explicites d’un composant ont priorité sur le fournisseur qui l’englobe. Par exemple, conservez les libellés au-dessus dans un formulaire tout en utilisant globalement des libellés sur la même ligne :
+
+```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` vaut `"auto"` par défaut et accepte aussi un nombre de pixels ou une largeur CSS telle que `"6em"`. En mode automatique, chaque libellé de recherche s’ajuste à son texte ; les formulaires ordinaires et les formulaires des boîtes de dialogue partagent une largeur fondée sur les libellés visibles afin d’aligner les contrôles. Les libellés longs occupent au plus 45 % de la largeur du champ et passent à la ligne au-delà, pour conserver de l’espace pour les contrôles. Les largeurs fixes explicites ne sont pas soumises à cette limite automatique. Les zones de recherche compactes placent les boutons d’action sur la même ligne si l’espace le permet et passent à la ligne sur les écrans étroits. Les associations entre libellés et contrôles restent intactes, les erreurs et les descriptions s’alignent avec les contrôles, et les libellés longs peuvent passer à la ligne.
+
+Dans la démonstration, ouvrez **Paramètres globaux** depuis la barre latérale ou la roue dentée en haut à droite pour modifier la disposition, la densité, la largeur des libellés et le thème. Les modifications prennent effet immédiatement sans effacer les saisies en cours. La page des formulaires permet de **Suivre les paramètres globaux** ou de les remplacer localement. La démonstration active explicitement une disposition compacte sur une même ligne via son fournisseur.
+
+## Taille et densité globales
+
+`AutoConfigProvider` prend en charge `size: "small" | "medium" | "large"` et `density: "compact" | "comfortable"`. Les propriétés explicites des composants ont priorité sur les paramètres de leur catégorie, qui ont eux-mêmes priorité sur les valeurs globales :
+
+```tsx
+<AutoConfigProvider config={{
+  size: "medium",
+  density: "compact",
+  form: { labelPosition: "left", labelAlign: "right" },
+  table: { density: "compact" },
+  tabs: { density: "compact" },
+}}>
+  <AutoForm fields={fields} size="small" />
+</AutoConfigProvider>
+```
+
+La densité du tableau accepte également `normal`. Par défaut, le panneau de paramètres du tableau suit les paramètres globaux. Choisir un espacement compact, normal ou confortable remplace la densité globale et est enregistré avec le préréglage de disposition ; la propriété `density` du composant a la priorité la plus élevée. Les tailles locales des composants imbriqués s’appliquent indépendamment.
+
+Les formulaires prennent en charge `resetLabel`, `extraActions` et `onReset` ; les panneaux de recherche prennent en charge `searchLabel`, `resetLabel` et `extraActions` ; les boîtes de dialogue prennent en charge `cancelLabel` et `extraActions`. Les éléments d’`AutoTabs` peuvent définir un `badge`, et `AutoTable.empty` personnalise le contenu de l’état vide.
+
+### AutoChat
+
+AutoChat fournit une mise en page de conversation légère avec suivi du streaming, chargement de l'historique et un composer. Fournissez du contenu React ou renderMessage pour le rendu des messages ; aucune dépendance d'exécution supplémentaire n'est requise.
+
+[AutoChat API](auto-chat.md)