@groupteknology/vuno 1.0.1 → 3.0.0

package/README.md

@@ -2,9 +2,9 @@
 
 Formularios, tablas y diálogos declarativos para Nuxt 4, con componentes propios y sin librería de interfaz por debajo.
 
-El módulo **trae su propia estética, y se sobreescribe entera desde el proyecto**. Todo lo que pinta se deriva de un puñado de variables CSS —los tokens `--vuno-*`—, así que redefinir una cambia vuno entero sin tocar un solo componente. Lo que necesita comportamiento difícil —combobox, menú, pestañas, tooltip, campo numérico— lleva su patrón ARIA y su teclado escritos aquí, con [Floating UI](https://floating-ui.com) para colocar lo que flota y nada más; el resto son elementos nativos.
+El módulo **trae su propia estética, y se sobreescribe desde el proyecto**. Los colores, superficies y tipografía se derivan de variables CSS —los tokens `--vuno-*`—; la curvatura usa directamente la escala predeterminada de Tailwind. Lo que necesita comportamiento difícil —combobox, menú, pestañas, tooltip, campo numérico— lleva su patrón ARIA y su teclado escritos aquí, con [Floating UI](https://floating-ui.com) para colocar lo que flota y nada más; el resto son elementos nativos.
 
-Un color o un radio escrito a mano dentro de un componente es un error: si algo no se puede cambiar desde los tokens, falta un token.
+Un color literal dentro de un componente es un error: si algo no se puede cambiar desde los tokens, falta un token. Para radios se usan las utilidades estándar de Tailwind.
 
 ## Documentación
 
@@ -21,7 +21,7 @@ pnpm add @groupteknology/vuno
 ```ts
 // nuxt.config.ts
 export default defineNuxtConfig({
-  modules: ['@groupteknology/vuno'],
+    modules: ['@groupteknology/vuno'],
 })
 ```
 
@@ -37,8 +37,8 @@ Si tu proyecto ya monta Tailwind, se detecta y no se duplica. Y si prefieres lle
 
 ```ts
 export default defineNuxtConfig({
-  modules: ['@groupteknology/vuno'],
-  vuno: { tailwind: false },
+    modules: ['@groupteknology/vuno'],
+    vuno: { tailwind: false },
 })
 ```
 
@@ -48,46 +48,75 @@ Un formulario se declara como datos y se renderiza solo. El estado vive en un ú
 
 ```vue
 <script setup lang="ts">
-import type { VunoFormDefinition } from '@groupteknology/vuno'
-import * as z from 'zod'
-
-const schema = z.object({
-  sku: z.string().min(1, 'El SKU es requerido'),
-  name: z.string().min(1, 'El nombre es requerido'),
-})
-
-const state = ref({ sku: '', name: '', slug: '' })
-
-const definition = {
-  layout: 'tabs',            // 'sections' (por defecto) | 'tabs'
-  sections: [
-    {
-      id: 'general',
-      title: 'Datos generales',
-      icon: 'lucide:info',
-      fields: [
-        { name: 'sku',  type: 'text', label: 'SKU',    columns: { xs: 12, lg: 6 }, required: true },
-        { name: 'name', type: 'text', label: 'Nombre', columns: { xs: 12, lg: 6 }, required: true },
-        { name: 'slug', type: 'slug', label: 'Slug',   source: 'name' },
-      ],
-    },
-  ],
-} satisfies VunoFormDefinition
+    import type { VunoFormDefinition } from '@groupteknology/vuno'
+    import * as z from 'zod'
+
+    const schema = z.object({
+        sku: z.string().min(1, 'El SKU es requerido'),
+        name: z.string().min(1, 'El nombre es requerido'),
+    })
+
+    const state = ref({ sku: '', name: '', slug: '' })
+
+    const definition = {
+        layout: 'tabs', // 'sections' (por defecto) | 'tabs'
+        sections: [
+            {
+                id: 'general',
+                title: 'Datos generales',
+                icon: 'lucide:info',
+                fields: [
+                    { name: 'sku', type: 'text', label: 'SKU', columns: { xs: 12, lg: 6 }, required: true },
+                    { name: 'name', type: 'text', label: 'Nombre', columns: { xs: 12, lg: 6 }, required: true },
+                    { name: 'slug', type: 'slug', label: 'Slug', source: 'name' },
+                ],
+            },
+        ],
+    } satisfies VunoFormDefinition
 </script>
 
 <template>
-  <VForm v-model:state="state" :definition="definition" :schema="schema" @submit="guardar">
-    <template #footer="{ dirty, reset }">
-      <VButton :disabled="!dirty" label="Descartar" variant="ghost" @click="reset" />
-      <VButton label="Guardar" type="submit" />
-    </template>
-  </VForm>
+    <VForm
+        v-model:state="state"
+        :definition="definition"
+        :schema="schema"
+        @submit="guardar"
+    >
+        <template #footer="{ dirty, reset }">
+            <VButton
+                :disabled="!dirty"
+                label="Descartar"
+                variant="ghost"
+                @click="reset"
+            />
+            <VButton
+                label="Guardar"
+                type="submit"
+            />
+        </template>
+    </VForm>
 </template>
 ```
 
 ### Tipos de campo
 
-`text` · `email` · `password` · `textarea` · `number` · `select` · `radio` · `checkbox` · `switch` · `color` · `slug` · `file` · `array`
+`text` · `search` · `email` · `password` · `textarea` · `number` · `select` · `radio` · `checkbox` · `switch` · `color` · `slug` · `file` · `array`
+
+Los mismos campos son componentes públicos y ya incluyen etiqueta, descripción, ayuda y error. Dentro de `VForm` leen y escriben por `name`; fuera usan su propio `v-model`:
+
+```vue
+<VFieldInput name="name" label="Nombre" />
+
+<VFieldInput v-model="name" label="Nombre" />
+```
+
+La etiqueta va arriba por defecto. `orientation="horizontal"` la coloca al costado del control:
+
+```vue
+<VFieldSelect v-model="role" label="Rol" orientation="horizontal" :items="roles" />
+```
+
+Los controles básicos son implementación interna. Para campos propios, `VFormField` sigue disponible y puede envolver cualquier control; un `VField*` colocado dentro reconoce ese envoltorio y no crea uno duplicado.
 
 `source` del campo `slug` es el **nombre** del campo del que deriva, no su valor.
 
@@ -150,65 +179,59 @@ La regla que lo resume: **el componente decide cómo es el formulario; quien lo
 ```vue
 <!-- app/components/Product/ProductForm.vue -->
 <script setup lang="ts">
-import type { VunoFormDefinition } from '@groupteknology/vuno'
-import * as z from 'zod'
+    import type { VunoFormDefinition } from '@groupteknology/vuno'
+    import * as z from 'zod'
 
-const props = defineProps<{
-  /** La fila en edición. Sin ella, el formulario es de alta. */
-  product?: null | Product
-  loading?: boolean
-}>()
+    const props = defineProps<{
+        /** La fila en edición. Sin ella, el formulario es de alta. */
+        product?: null | Product
+        loading?: boolean
+    }>()
 
-const emit = defineEmits<{ submit: [] }>()
+    const emit = defineEmits<{ submit: [] }>()
 
-const open = defineModel<boolean>('open', { default: false })
-const state = defineModel<ProductFormState>('state', { required: true })
+    const open = defineModel<boolean>('open', { default: false })
+    const state = defineModel<ProductFormState>('state', { required: true })
 
-// Lo propio del formulario: su forma, sus reglas y sus textos.
-const schema = z.object({ sku: z.string().min(1, 'El SKU es requerido') })
+    // Lo propio del formulario: su forma, sus reglas y sus textos.
+    const schema = z.object({ sku: z.string().min(1, 'El SKU es requerido') })
 
-const title = computed(() => (props.product ? `Editar ${props.product.sku}` : 'Nuevo producto'))
+    const title = computed(() => (props.product ? `Editar ${props.product.sku}` : 'Nuevo producto'))
 
-const definition = {
-  layout: 'tabs',
-  sections: [/* ... */],
-} satisfies VunoFormDefinition
+    const definition = {
+        layout: 'tabs',
+        sections: [/* ... */],
+    } satisfies VunoFormDefinition
 </script>
 
 <template>
-  <VFormModal
-    v-model:open="open"
-    v-model:state="state"
-    :definition="definition"
-    :loading="props.loading"
-    :schema="schema"
-    :title="title"
-    @submit="emit('submit')"
-  />
+    <VFormModal
+        v-model:open="open"
+        v-model:state="state"
+        :definition="definition"
+        :loading="props.loading"
+        :schema="schema"
+        :title="title"
+        @submit="emit('submit')"
+    />
 </template>
 ```
 
 Y la página queda sin saber nada de los campos:
 
 ```vue
-<ProductForm
-  v-model:open="formOpen"
-  v-model:state="state"
-  :loading="isSaving"
-  :product="editing"
-  @submit="submit"
-/>
+<ProductForm v-model:open="formOpen" v-model:state="state" :loading="isSaving" :product="editing" @submit="submit" />
 ```
 
 #### Qué expone
 
-| | |
-|---|---|
-| `v-model:state` | El estado del formulario. Obligatorio: lo posee quien lo usa, no el formulario. |
-| `v-model:open` | Solo si es modal. |
-| `:loading` | Si se está guardando, para bloquear el botón. |
+|                    |                                                                                                                     |
+| ------------------ | ------------------------------------------------------------------------------------------------------------------- |
+| `v-model:state`    | El estado del formulario. Obligatorio: lo posee quien lo usa, no el formulario.                                     |
+| `v-model:open`     | Solo si es modal.                                                                                                   |
+| `:loading`         | Si se está guardando, para bloquear el botón.                                                                       |
 | La fila en edición | Un prop —`product`, `brand`, lo que sea— que vale `null` en el alta. De él salen el título y la etiqueta del botón. |
-| `@submit` | Significa «el usuario confirmó», nada más. Sin datos: ya están en `state`. |
+| `@submit`          | Significa «el usuario confirmó», nada más. Sin datos: ya están en `state`.                                          |
 
 No es casualidad que encaje: son exactamente `state`, `formOpen`, `isSaving`, `editing` y `submit` de `useCrud`.
 
@@ -226,23 +249,21 @@ El estado tampoco se queda dentro. Si el formulario declara su propio `ref` en v
 
 ```vue
 <script setup lang="ts">
-// En SSR, `$fetch` no reenvía la cookie de la petición y una ruta con sesión
-// responde 401 durante el render. `useRequestFetch()` sí la lleva.
-const request = useRequestFetch()
-
-const query = useTableQuery({ sort: 'sku', url: true })
-
-const { items, total, failure, isPending, isSaving, isDeleting,
-        formOpen, editing, state, submit, openCreate, openEdit,
-        confirmOpen, deleting, askDelete, confirmDelete } = useCrud<Product, ProductForm>({
-  key: 'products',
-  query,
-  emptyForm: () => ({ name: '', sku: '' }),
-  list:   (q)        => request('/api/products', { query: q }),
-  create: (form)     => $fetch('/api/products', { body: form, method: 'POST' }),
-  update: (id, form) => $fetch(`/api/products/${id}`, { body: form, method: 'PATCH' }),
-  remove: (row)      => $fetch(`/api/products/${row.id}`, { method: 'DELETE' }),
-})
+    // En SSR, `$fetch` no reenvía la cookie de la petición y una ruta con sesión
+    // responde 401 durante el render. `useRequestFetch()` sí la lleva.
+    const request = useRequestFetch()
+
+    const query = useTableQuery({ sort: 'sku', url: true })
+
+    const { items, total, failure, isPending, isSaving, isDeleting, formOpen, editing, state, submit, openCreate, openEdit, confirmOpen, deleting, askDelete, confirmDelete } = useCrud<Product, ProductForm>({
+        key: 'products',
+        query,
+        emptyForm: () => ({ name: '', sku: '' }),
+        list: (q) => request('/api/products', { query: q }),
+        create: (form) => $fetch('/api/products', { body: form, method: 'POST' }),
+        update: (id, form) => $fetch(`/api/products/${id}`, { body: form, method: 'PATCH' }),
+        remove: (row) => $fetch(`/api/products/${row.id}`, { method: 'DELETE' }),
+    })
 </script>
 ```
 
@@ -256,8 +277,8 @@ La consulta forma parte de la clave de caché, así que cada página, filtro y o
 
 ```ts
 const crud = useCrud({
-  key: () => ['products', selectedCompanyId.value],
-  // ...
+    key: () => ['products', selectedCompanyId.value],
+    // ...
 })
 ```
 
@@ -280,7 +301,7 @@ Mientras la clave está incompleta, `isPending` sigue en `true`: la pantalla est
 Para lo que no se deduce de la clave —un permiso, una pestaña que no está a la vista— está la opción `enabled`, que se suma a la condición anterior.
 
 ```ts
-useCrud({ key: () => ['products', companyId.value], enabled: () => canRead.value, /* ... */ })
+useCrud({ key: () => ['products', companyId.value], enabled: () => canRead.value /* ... */ })
 ```
 
 ### La clave de invalidación
@@ -288,7 +309,7 @@ useCrud({ key: () => ['products', companyId.value], enabled: () => canRead.value
 `invalidate()` invalida **por prefijo**, usando la clave base que le des. Pásale el prefijo más ancho del dominio y deja que vuno añada el estado de consulta como último segmento:
 
 ```ts
-key: () => productKeys.all()        // un alta refresca todo el dominio
+key: () => productKeys.all() // un alta refresca todo el dominio
 key: () => productKeys.list(filtros) // solo refresca esa combinación de filtros
 ```
 
@@ -296,18 +317,14 @@ key: () => productKeys.list(filtros) // solo refresca esa combinación de filtro
 
 `useCrud` resuelve el listado durante el render en servidor, así que el HTML sale con las filas puestas y no aparecen al hidratar. Nuxt renderiza en servidor por defecto, de modo que esto no hay que activarlo.
 
-Para que además viaje en el payload y el cliente no vuelva a pedirlo, el plugin de vue-query del proyecto tiene que deshidratar. Es responsabilidad del consumidor, no del módulo:
-
-```ts
-// app/plugins/vue-query.ts
-export default defineNuxtPlugin((nuxtApp) => {
-  const state = useState<DehydratedState | null>('vue-query', () => null)
-  const queryClient = new QueryClient()
+Vuno registra TanStack Query y deshidrata su caché en el payload de Nuxt, de modo que el cliente hidrata lo resuelto en servidor sin repetir la primera consulta. No hace falta instalar ni configurar `@tanstack/vue-query` en el proyecto consumidor.
 
-  nuxtApp.vueApp.use(VueQueryPlugin, { queryClient })
+Si el proyecto ya aporta su propio `QueryClient`, desactiva el registro de Vuno y conserva esa configuración:
 
-  if (import.meta.server) nuxtApp.hooks.hook('app:rendered', () => { state.value = dehydrate(queryClient) })
-  if (import.meta.client) hydrate(queryClient, state.value)
+```ts [nuxt.config.ts]
+export default defineNuxtConfig({
+    modules: ['@groupteknology/vuno'],
+    vuno: { vueQuery: false },
 })
 ```
 
@@ -319,45 +336,39 @@ Con la clave incompleta no se espera nada: la consulta está suspendida y espera
 
 Si compruebas esto con un test, **mira el HTML renderizado, no el payload**. El payload lleva la consulta resuelta aunque el prefetch esté apagado, porque la consulta se asienta después del render y el plugin deshidrata lo que encuentra: un assert sobre el payload pasa en las dos direcciones y no mide nada.
 
-**`@tanstack/vue-query` lo instala el proyecto**, y solo hace falta si usas este composable:
+## Migas de pan
 
-```bash
-pnpm add @tanstack/vue-query
-```
-
-No se declara como dependencia opcional del módulo a propósito. npm instala igualmente los `peerDependencies` marcados como opcionales, y como los de vue-query admiten Vue 2, acababa colocando `vue@2.6.14` en la raíz y chocando con el `vue@^3.5.0` que pide vuno: `npm install @groupteknology/vuno` fallaba con `ERESOLVE` en un proyecto Nuxt que no declarara `vue` por su cuenta. Con pnpm no ocurría, que es por lo que tardó en verse.
-
-## Páginas
-
-`VPage` pone la estructura que repite cualquier pantalla de mantenimiento:
+`VBreadcrumb` pinta la ruta de navegación sin imponer la cabecera ni el cuerpo de la pantalla:
 
 ```vue
-<VPage title="Productos" description="Catálogo completo." :breadcrumb="[{ label: 'Inicio', to: '/' }, { label: 'Productos' }]">
-  <template #actions>
-    <VButton icon="lucide:plus" label="Nuevo producto" @click="openCreate" />
-  </template>
-
-  <VTable ... />
-</VPage>
+<VBreadcrumb :items="[{ label: 'Inicio', to: '/' }, { label: 'Productos' }]" />
 ```
 
+En rutas largas oculta los segmentos más antiguos antes de `sm`; con `loading` conserva el nombre accesible del segmento actual y muestra un esqueleto.
+
 ## Tablas
 
-`VTable` funciona en modo servidor: emite el estado de consulta y tú devuelves la página.
+`VTable` se limita a renderizar filas y columnas. `VDataTable` lo compone con búsqueda, filtros, estados y `VPagination` para trabajar en modo servidor: emite el estado de consulta y tú devuelves la página.
 
 **`query` es obligatorio.** No es un `v-model` opcional: sin él la tabla no compila, y el error de tipos que sale encabeza con el objeto `definition`, así que manda a mirar el sitio equivocado.
 
 ```vue
 <script setup lang="ts">
-const query = useTableQuery({ sort: 'sku', url: true, history: 'push', filterKeys: ['status'] })
+    const query = useTableQuery({ sort: 'sku', url: true, history: 'push', filterKeys: ['status'] })
 
-const { data, status } = await useFetch('/api/products', {
-  query: computed(() => ({ page: query.value.page, sort: query.value.sort?.column, ...query.value.filters })),
-})
+    const { data, status } = await useFetch('/api/products', {
+        query: computed(() => ({ page: query.value.page, sort: query.value.sort?.column, ...query.value.filters })),
+    })
 </script>
 
 <template>
-  <VTable v-model:query="query" :definition="definition" :data="data?.data ?? []" :total="data?.total ?? 0" :loading="status === 'pending'" />
+    <VDataTable
+        v-model:query="query"
+        :definition="definition"
+        :data="data?.data ?? []"
+        :total="data?.total ?? 0"
+        :loading="status === 'pending'"
+    />
 </template>
 ```
 
@@ -371,16 +382,33 @@ Cada uno declara sus propios props en una unión discriminada por `type`, igual
 
 ```ts
 const definition = {
-  searchable: false,   // el endpoint no busca: no se pinta la barra
-  paginated: false,    // ni pagina: el pie dice cuántos hay y nada más
-  columns: [
-    { key: 'sku', label: 'SKU', type: 'text', sortable: true },
-    { key: 'price', label: 'Precio', type: 'currency', currency: 'EUR', align: 'end' },
-    { key: 'createdAt', label: 'Alta', type: 'date' },
-  ],
+    searchable: false, // el endpoint no busca: no se pinta la barra
+    paginated: false, // ni pagina: el pie dice cuántos hay y nada más
+    columns: [
+        { key: 'sku', label: 'SKU', type: 'text', sortable: true },
+        { key: 'price', label: 'Precio', type: 'currency', currency: 'EUR', align: 'end' },
+        { key: 'createdAt', label: 'Alta', type: 'date' },
+    ],
+} satisfies VunoDataTableDefinition<Product>
+```
+
+La misma definición controla las capacidades de disposición que dependen del caso real:
+
+```ts
+const definition = {
+    caption: 'Inventario disponible',
+    density: 'compact',
+    interactive: true,
+    stickyHeader: true,
+    columns: [
+        { key: 'sku', label: 'SKU', type: 'text', sticky: 'start' },
+        { key: 'stock', label: 'Stock', type: 'number', sticky: 'end' },
+    ],
 } satisfies VunoTableDefinition<Product>
 ```
 
+`caption` nombra la tabla con HTML nativo; si el título ya existe fuera, usa `labelledBy` con su `id` en vez de repetirlo. `stickyHeader` necesita una altura limitada en `ui.tableRoot`. Las columnas usan bordes lógicos (`start` y `end`) para conservar el comportamiento en interfaces RTL. Cuando `interactive` está activo, una fila emite `rowClick` tanto con puntero como con Enter o Espacio y recibe un nombre accesible a partir de `rowLabel`.
+
 #### Traducir un valor a una etiqueta
 
 La columna `badge` tiene `map`, que convierte el valor crudo que llega del servidor en la etiqueta y el color que ve el usuario. Es lo que evita enseñar `user` o `published` en pantalla:
@@ -425,7 +453,7 @@ Y un aviso al ordenar: `sortable` ordena **en servidor por `key`**, y el servido
 `map` es solo de `badge`. Para traducir en otro tipo de columna, o para componer algo que no es una etiqueta, está `type: 'custom'` con su slot:
 
 ```vue
-<VTable v-model:query="query" :definition="definition" :data="rows">
+<VTable v-model:sort="sort" :definition="definition" :data="rows">
   <template #cell-stock="{ row, value }">
     <span class="tabular-nums">{{ value }} uds.</span>
     <VBadge v-if="row.stock === 0" color="error" label="Agotado" />
@@ -440,9 +468,7 @@ El slot se llama `cell-<key>` y recibe `value` —el valor de esa columna, ya re
 Son dos estados distintos y se pintan distinto. Sin separarlos, una consulta que falla se normaliza a lista vacía (`data ?? []`) y la tabla dice «No hay resultados»: afirma que no hay nada cuando lo cierto es que no se pudo saber.
 
 ```ts
-const failure = computed(() => isError.value
-  ? { title: 'No pudimos cargar los productos', hint: 'Puede ser algo temporal.', retry: () => void refetch() }
-  : undefined)
+const failure = computed(() => (isError.value ? { title: 'No pudimos cargar los productos', hint: 'Puede ser algo temporal.', retry: () => void refetch() } : undefined))
 ```
 
 Con `useCrud` no hace falta escribirlo: el objeto lo construye él, y el título y la pista se declaran en `messages` con `listFailed` y `listFailedHint`.
@@ -461,6 +487,14 @@ Los dos estados existen además sueltos, para las pantallas que no son una tabla
 <VState tone="failure" :failure="failure" />
 ```
 
+Un aviso que acompaña contenido existente usa `VAlert`. Es persistente, toma los mismos colores semánticos del tema y usa `role="status"` por defecto; `role="alert"` queda para lo urgente:
+
+```vue
+<VAlert color="warning" title="Faltan datos de facturación" description="Completa la dirección fiscal antes de emitir una factura.">
+  <template #actions><VButton label="Completar datos" variant="outline" /></template>
+</VAlert>
+```
+
 Tipos de columna: `text` · `number` · `currency` · `date` · `boolean` · `badge` · `image` · `custom` · `actions`. Trae búsqueda con antirrebote, paginación, selección múltiple, panel lateral de filtros y menú de acciones por fila.
 
 ## Diálogos de confirmación
@@ -497,13 +531,13 @@ El componente recibe `open` y los props que le pases, y resuelve la promesa emit
 
 ```vue
 <script setup lang="ts">
-const emit = defineEmits<{ close: [guardado: boolean] }>()
-const open = defineModel<boolean>('open', { default: false })
+    const emit = defineEmits<{ close: [guardado: boolean] }>()
+    const open = defineModel<boolean>('open', { default: false })
 
-function guardar() {
-  open.value = false
-  emit('close', true)
-}
+    function guardar() {
+        open.value = false
+        emit('close', true)
+    }
 </script>
 ```
 
@@ -511,27 +545,34 @@ Se pinta en `<VApp>` y no en la pantalla que lo abrió, así que navegar no lo d
 
 ## Composables
 
-| Composable | Para qué |
-|---|---|
-| `useCrud` | El ciclo de mantenimiento entero sobre TanStack Query. |
-| `useTableQuery` | Estado de consulta de una tabla, opcionalmente sincronizado con la query string. |
-| `useForm` | Contexto del `VForm` que envuelve al componente: estado, `dirty`, `reset`. |
-| `useField` | Lee y escribe un campo por su ruta; para construir campos propios. |
-| `useTheme` | Resuelve los slots de un componente cruzando tema, `app.config` y prop `ui`. |
-| `useIcons` | Los iconos configurados en `vuno.icons`. |
-| `useMessages` | Los textos configurados en `vuno.messages`. |
-
-Los tres últimos existen para que un componente tuyo pueda usar los mismos iconos, textos y reglas de tema que los de vuno sin duplicar la configuración.
+| Composable        | Para qué                                                                         |
+| ----------------- | -------------------------------------------------------------------------------- |
+| `useCrud`         | El ciclo de mantenimiento entero sobre TanStack Query.                           |
+| `useTableQuery`   | Estado de consulta de una tabla, opcionalmente sincronizado con la query string. |
+| `useForm`         | Contexto del `VForm` que envuelve al componente: estado, `dirty`, `reset`.       |
+| `useField`        | Lee y escribe un campo por su ruta; para construir campos propios.               |
+| `useTheme`        | Resuelve los slots de un componente cruzando tema, `app.config` y prop `ui`.     |
+| `useIcons`        | Los iconos configurados en `vuno.icons`.                                         |
+| `useLocale`       | El idioma configurado para fechas, números y monedas.                            |
+| `useMessages`     | Los textos configurados en `vuno.messages`.                                      |
+| `useToast`        | Notificaciones globales que no interrumpen.                                      |
+| `useConfirm`      | Confirmación global que devuelve la respuesta como promesa.                      |
+| `useOverlay`      | Abre componentes como capas globales desde código.                               |
+| `useModal`        | Resuelve y abre los modales del proyecto por nombre.                             |
+| `useContext`      | Acceso de bajo nivel al contexto provisto por `VApp`.                            |
+| `defineShortcuts` | Declara atajos de teclado reactivos y ligados al ciclo de vida.                  |
+
+`useTheme`, `useIcons`, `useLocale` y `useMessages` existen para que un componente tuyo pueda usar la misma configuración visual y regional que los de vuno sin duplicarla.
 
 ## Personalización
 
 ### Los tokens
 
-**Es el primer sitio al que hay que ir, y casi siempre el único.** Todo el color, el radio y la jerarquía de texto de vuno salen de variables CSS que se redefinen desde el proyecto. El caso mínimo, en cualquier hoja que cargue tu aplicación:
+**Es el primer sitio al que hay que ir, y casi siempre el único.** El color y la jerarquía de texto de vuno salen de variables CSS que se redefinen desde el proyecto. El caso mínimo, en cualquier hoja que cargue tu aplicación:
 
 ```css
 :root {
-  --vuno-primary: var(--color-indigo-600);
+    --vuno-primary: var(--color-indigo-600);
 }
 ```
 
@@ -539,42 +580,47 @@ Con esa línea cambian los botones sólidos, el anillo de foco de todos los camp
 
 Los que hay:
 
-| Token | Para qué |
-| --- | --- |
-| `--vuno-primary` · `--vuno-secondary` · `--vuno-neutral` | Los tres acentos de marca. |
-| `--vuno-success` · `--vuno-info` · `--vuno-warning` · `--vuno-error` | Los cuatro de estado. |
-| `--vuno-*-contrast` | El texto que va **encima** de cada acento en su variante sólida. |
-| `--vuno-font-sans` · `--vuno-font-mono` | La tipografía. El módulo **nombra** la familia y no la carga: un `@import` a un servidor de fuentes convertiría cada visita de tu proyecto en una petición a un tercero. Cárgala tú —con `@nuxt/fonts` o con tu propio `@font-face`—; si no está, la pila de respaldo se encarga. |
-| `--vuno-surface` · `--vuno-surface-1` · `--vuno-surface-2` · `--vuno-surface-inverse` | La escala de elevación: **cada cosa sube un escalón sobre lo que la sostiene**. La página es la base —blanco en claro, negro en oscuro—, lo que se levanta de ella es el 1 y lo que se levanta dentro de algo ya levantado es el 2. |
-| `--vuno-text-strong` · `-body` · `-muted` · `-subtle` · `-inverse` | El texto por jerarquía, no por color. |
-| `--vuno-border` · `--vuno-border-strong` | El borde que decora y el que delimita un control. |
-| `--vuno-radius` | La curvatura de todo. |
-| `--vuno-backdrop` | El velo que oscurece detrás de un diálogo. |
+| Token                                                                                 | Para qué                                                                                                                                                                                                                                                                          |
+| ------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--vuno-primary` · `--vuno-secondary` · `--vuno-neutral`                              | Los tres acentos de marca.                                                                                                                                                                                                                                                        |
+| `--vuno-success` · `--vuno-info` · `--vuno-warning` · `--vuno-error`                  | Los cuatro de estado.                                                                                                                                                                                                                                                             |
+| `--vuno-*-contrast`                                                                   | El texto que va **encima** de cada acento en su variante sólida.                                                                                                                                                                                                                  |
+| `--vuno-font-sans` · `--vuno-font-mono`                                               | La tipografía. El módulo **nombra** la familia y no la carga: un `@import` a un servidor de fuentes convertiría cada visita de tu proyecto en una petición a un tercero. Cárgala tú —con `@nuxt/fonts` o con tu propio `@font-face`—; si no está, la pila de respaldo se encarga. |
+| `--vuno-surface` · `--vuno-surface-1` · `--vuno-surface-2` · `--vuno-surface-inverse` | La escala de elevación: **cada cosa sube un escalón sobre lo que la sostiene**. La página es la base —blanco en claro, negro en oscuro—, lo que se levanta de ella es el 1 y lo que se levanta dentro de algo ya levantado es el 2.                                               |
+| `--vuno-text-strong` · `-body` · `-muted` · `-subtle` · `-inverse`                    | El texto por jerarquía, no por color.                                                                                                                                                                                                                                             |
+| `--vuno-border` · `--vuno-border-strong`                                              | El borde que decora y el que delimita un control.                                                                                                                                                                                                                                 |
+| `--vuno-backdrop`                                                                     | El velo que oscurece detrás de un diálogo.                                                                                                                                                                                                                                        |
 
 Dos cosas que ahorran un rato:
 
+- **La curvatura usa Tailwind directamente.** El tema predeterminado usa `rounded-sm` y la prop `radius` admite `xs`, `sm`, `md`, `lg`, `xl`, `2xl`, `3xl`, `4xl` y `full`.
 - **El tema oscuro se redefine aparte**, bajo `.dark`. Si solo cambias `:root`, el modo oscuro se queda con el valor de serie.
 - **Cada acento sólido necesita su contraste.** Un `--vuno-warning` claro con texto blanco no se lee; por eso el ámbar de serie trae texto oscuro.
 
 ```css
 .dark {
-  --vuno-primary: var(--color-indigo-400);
+    --vuno-primary: var(--color-indigo-400);
 }
 ```
 
-### Los tres niveles del resto
+### Los niveles de configuración
 
-Para lo que no es color: la forma de un componente concreto, sus iconos y sus textos.
+Los defaults visuales compartidos viven en `vuno.theme`; las entradas de cada
+componente, en `vuno.components`. Los iconos, textos e idioma permanecen al
+nivel de `vuno` porque no son temas de un componente.
 
 ```ts
 // app.config.ts — para toda la aplicación
 export default defineAppConfig({
-  vuno: {
-    formSection: { slots: { root: 'border-dashed' } },
-    icons: { slugEdit: 'lucide:wand-sparkles' },
-    locale: 'es-ES',
-    messages: { selectPlaceholder: 'Elige una opción' },
-  },
+    vuno: {
+        components: {
+            formSection: { slots: { root: 'border-dashed' } },
+        },
+        icons: { slugEdit: 'lucide:wand-sparkles' },
+        locale: 'es-ES',
+        messages: { selectPlaceholder: 'Elige una opción' },
+        theme: { radius: 'md' },
+    },
 })
 ```
 
@@ -593,14 +639,12 @@ En desarrollo.
 
 ### Nota sobre pruebas automatizadas
 
-Tres trampas, las tres medidas aquí, que hacen que una comprobación afirme lo contrario de lo que pasa.
+Dos trampas, las dos medidas aquí, que hacen que una comprobación afirme lo contrario de lo que pasa.
 
 **Una pestaña oculta no pinta.** Con la ventana de fondo, `document.visibilityState` es `hidden`, `requestAnimationFrame` **no dispara nunca** y con él se paran las transiciones: un diálogo puede no llegar a abrirse y una captura caducar. El DOM y las medidas de disposición sí funcionan, así que se puede comprobar casi todo; lo que no se puede es dar por cerrado un componente porque su nodo siga ahí. Mira el estado (`opacity`, `data-state`) y no la existencia del nodo, o haz la prueba con la pestaña delante.
 
 **`getComputedStyle` se queda con el valor viejo tras cambiar un token.** Si redefines `--vuno-primary` y vuelves a leer un elemento que ya existía, puede devolverte el color anterior aunque la variable ya valga otra cosa. Se nota porque el valor sale en `oklab` en vez de en `oklch`. Lee sobre un elemento **creado después** del cambio —o sobre un clon del que te interesa— y el valor es el nuevo.
 
-**Un control de Reka no responde a un clic sintético.** Sus botones actúan en `pointerdown`, no en `click`, y las flechas necesitan foco de verdad: un `.click()` o un `.focus()` desde el script no disparan nada y parece que el componente está roto. Los controles nativos —casilla, interruptor, radio— sí responden a `click()`, así que ahí el clic sintético vale.
-
 ## Licencia
 
 [MIT](./LICENSE) © Diego Otayza

package/dist/module.d.mts

@@ -5,6 +5,8 @@ interface ModuleOptions {
     prefix?: string;
     /** Registrar el compilador de Tailwind. Ponlo en `false` si ya lo monta el proyecto. */
     tailwind?: boolean;
+    /** Registrar TanStack Query con hidratación SSR. Ponlo en `false` si el proyecto ya aporta su propio cliente. */
+    vueQuery?: boolean;
 }
 declare const module$1: NuxtModule<ModuleOptions>;