npm - @groupteknology/vuno - Versions diffs - 3.0.0 → 4.0.0 - Mend

@groupteknology/vuno 3.0.0 → 4.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (1244) hide show

package/README.md CHANGED Viewed

@@ -1,650 +1,44 @@
 # @groupteknology/vuno
-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 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 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
-El catálogo vive en **<https://groupteknology.github.io/vuno/>**: una ficha por componente, con la vista viva, los controles que la mueven, el código que produce cada combinación y las tablas de props, slots y emits al pie.
-Lo que hay aquí abajo es la referencia corta, para leerla sin salir del editor.
-## Instalación
-```bash
-pnpm add @groupteknology/vuno
-```
-```ts
-// nuxt.config.ts
-export default defineNuxtConfig({
-    modules: ['@groupteknology/vuno'],
-})
-```
-Eso es todo: el módulo registra sus componentes, su hoja de estilos, el compilador de Tailwind y `@nuxt/icon`, que es quien pinta los iconos.
-¿Vienes de la `0.6.1`? El [changelog](https://github.com/groupteknology/vuno/blob/main/packages/core/CHANGELOG.md) dice qué se rompe y qué mirar después.
-### Tailwind
-**El módulo registra el compilador de Tailwind** (`@tailwindcss/vite`). No es una comodidad: la hoja que empuja vuno empieza por `@import 'tailwindcss'`, y sin nadie que lo compile ese import no hace nada —las variables del tema llegan, porque son CSS normal, y ni una sola utilidad—. La aplicación se sirve, no falla nada y sale sin estilos, que es el peor modo de fallar.
-Si tu proyecto ya monta Tailwind, se detecta y no se duplica. Y si prefieres llevarlo tú:
-```ts
-export default defineNuxtConfig({
-    modules: ['@groupteknology/vuno'],
-    vuno: { tailwind: false },
-})
-```
-## Formularios
-Un formulario se declara como datos y se renderiza solo. El estado vive en un único objeto y cada campo lo lee y lo escribe por ruta, incluidas las anidadas.
-```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
-</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>
-</template>
-```
-### Tipos de campo
-`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.
-Cada uno declara sus propios props mediante una unión discriminada por `type`, así que el editor te avisa si a un `slug` le falta el `source` o si le pasas un `placeholder` a un `file`.
-### Campos obligatorios
-`required: true` hace tres cosas: pinta el asterisco en la etiqueta, pone el atributo `required` en el input —que es lo que anuncia el campo como obligatorio a un lector de pantalla y lo que permite estilar `:invalid`— y nada más. **Quien decide si el valor vale es el esquema.**
-El `<form>` lleva `novalidate`, así que el navegador no valida por su cuenta. Sin eso convivirían dos validaciones y ganaría la del navegador: cortaría el envío antes de que el esquema llegase a ejecutarse, y el usuario vería un globo del navegador, en su idioma y fuera del tema, en lugar del mensaje que tú escribiste.
-Conviene saberlo si vienes de otras librerías, donde `required` suele pintar el asterisco y no llegar al control. Aquí llega, a propósito y por accesibilidad, y por eso el `novalidate` es necesario y no una preferencia.
-### Campos repetibles
-`type: 'array'` repite un grupo de campos y genera rutas anidadas (`variants.0.sku`) que coinciden con las que produce la validación, de modo que cada campo muestra su propio error. Admite anidamiento.
-```ts
-{
-  name: 'variants',
-  type: 'array',
-  label: 'Variantes',
-  sortable: true,
-  fields: [
-    { name: 'sku',   type: 'text',   label: 'SKU',   columns: { xs: 12, md: 6 } },
-    { name: 'stock', type: 'number', label: 'Stock', columns: { xs: 12, md: 6 } },
-  ],
-}
-```
-Con `layout: 'tabs'`, cada pestaña muestra un contador de los campos con error que contiene, incluidos los anidados.
-### En un modal
-El slot `footer` recibe `formId`, necesario para enviar desde un botón propio: el pie vive fuera del `<form>`, así que la asociación se hace con el atributo nativo.
-```vue
-<VFormModal v-model:open="open" v-model:state="state" :definition="definition" :title="title">
-  <template #footer="{ close, formId, loading }">
-    <VButton label="Cancelar" variant="ghost" @click="close" />
-    <VButton :form="formId" :label="editando ? 'Guardar cambios' : 'Crear'" :loading="loading" type="submit" />
-  </template>
-</VFormModal>
-```
-`VFormModal` añade el diálogo, los botones y el ancho adecuado. Los botones van en el pie del modal —fijo mientras el cuerpo hace scroll— asociados al formulario por `id`.
-```vue
-<VFormModal v-model:open="open" v-model:state="state" :definition="definition" :schema="schema" title="Nuevo producto" close-on-submit @submit="guardar" />
-```
-### Un componente por formulario
-Un formulario largo no vive en la página. Se declara en su propio componente, que contiene **la definición, el esquema y los textos**, y nada más.
-Es la práctica recomendada y no es una cuestión de orden: el mismo formulario acaba abriéndose desde más de un sitio —la lista, la ficha, un atajo— y en el momento en que lleva dentro el guardado, ya no se puede reutilizar sin arrastrar consecuencias que no son suyas.
-La regla que lo resume: **el componente decide cómo es el formulario; quien lo usa decide qué pasa al enviarlo.**
-```vue
-<!-- app/components/Product/ProductForm.vue -->
-<script setup lang="ts">
-    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 emit = defineEmits<{ submit: [] }>()
-    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') })
-    const title = computed(() => (props.product ? `Editar ${props.product.sku}` : 'Nuevo producto'))
-    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')"
-    />
-</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" />
-```
-#### 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.                                                                       |
-| 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`.                                          |
-No es casualidad que encaje: son exactamente `state`, `formOpen`, `isSaving`, `editing` y `submit` de `useCrud`.
-#### Qué se queda fuera
-La petición, la mutación, invalidar la caché, los avisos y cerrar el modal al terminar. Todo eso es consecuencia del envío, y la consecuencia cambia según desde dónde se abra el formulario.
-Si el componente hace el `$fetch` dentro, el síntoma llega pronto: en cuanto haga falta abrirlo desde otra pantalla con otro destino, hay que copiarlo o llenarlo de condicionales.
-El estado tampoco se queda dentro. Si el formulario declara su propio `ref` en vez de recibir `v-model:state`, quien lo usa no ve lo que el usuario escribió y el guardado envía el estado inicial: falla en silencio y lejos de la causa.
-## Una pantalla de mantenimiento entera
-`useCrud` resuelve el ciclo completo: listar, dar de alta o editar en un modal, borrar con confirmación, invalidar la caché y avisar. Está construido sobre [TanStack Query](https://tanstack.com/query).
-```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' }),
-    })
-</script>
-```
-Solo `list` necesita `useRequestFetch()`: es la única que corre en servidor. El alta, la edición y el borrado salen siempre del navegador, donde `$fetch` lleva la cookie por su cuenta.
-La consulta forma parte de la clave de caché, así que cada página, filtro y orden se guarda por separado. Usa `placeholderData: keepPreviousData`, que mantiene en pantalla los datos anteriores mientras llega la nueva página: sin eso, cada cambio de filtro deja `data` en `undefined` un instante y la tabla parpadea enseñando su estado vacío. Los textos de los avisos salen de `vuno.messages` y se pueden afinar por pantalla con la opción `messages`.
-### Claves que dependen de estado reactivo
-`key` acepta un getter o un `computed`, no solo un valor fijo. Hace falta en cuanto la pantalla tiene un selector —empresa, tienda, almacén—: con una clave fija, cambiar de empresa seguiría enseñando los datos de la anterior sin dar ninguna señal de error.
-```ts
-const crud = useCrud({
-    key: () => ['products', selectedCompanyId.value],
-    // ...
-})
-```
-Un segmento `undefined` o `null` marca la clave como incompleta y **suspende la consulta**. En una clave de caché ese hueco nunca es un valor: es un dato que todavía no ha llegado, y consultar con él devolvería la lista de otro inquilino o una vacía que parecería legítima.
-Por eso no hace falta ni `?? ''` ni un `enabled` por pantalla:
-```ts
-// Sobra: el `?? ''` convierte «aún no sé la empresa» en una empresa válida.
-key: () => ['products', selectedCompanyId.value ?? '']
-// Basta: mientras la empresa no llegue, no se consulta.
-key: () => ['products', selectedCompanyId.value]
-```
-`0`, `''` y `false` sí son valores y no suspenden nada.
-Mientras la clave está incompleta, `isPending` sigue en `true`: la pantalla está esperando, y esa es la diferencia con un listado vacío. `isEnabled` dice si la consulta puede dispararse, e `invalidate()` no toca la caché con una clave a medias, porque invalidar por un prefijo incompleto alcanzaría a otras pantallas.
-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 /* ... */ })
-```
-### La clave de invalidación
-`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:
+Módulo Nuxt 4 que implementa el sistema de diseño Vuno con componentes Vue propios, contratos TypeScript y temas basados en tokens `--vuno-*`.
 ```ts
-key: () => productKeys.all() // un alta refresca todo el dominio
-key: () => productKeys.list(filtros) // solo refresca esa combinación de filtros
-```
-### Render en servidor
-`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.
-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.
-Si el proyecto ya aporta su propio `QueryClient`, desactiva el registro de Vuno y conserva esa configuración:
-```ts [nuxt.config.ts]
-export default defineNuxtConfig({
-    modules: ['@groupteknology/vuno'],
-    vuno: { vueQuery: false },
-})
+export default defineNuxtConfig({ modules: ['@groupteknology/vuno'] })
 ```
-**Si tu API tiene sesión, `list` tiene que usar `useRequestFetch()`.** Un `$fetch` pelado no reenvía la cookie de la petición entrante, así que durante el render en servidor la llamada sale sin autenticar y la ruta responde 401. Es el tropiezo más probable al estrenar esto, porque en cliente el mismo código funciona.
-Con la clave incompleta no se espera nada: la consulta está suspendida y esperarla colgaría el render entero, porque una consulta deshabilitada nunca se asienta.
-`server: false` desactiva la espera para lo que no se ve en la primera pintada —una lista dentro de un modal, una pestaña oculta—, donde solo retrasaría el HTML.
-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.
-## Migas de pan
-`VBreadcrumb` pinta la ruta de navegación sin imponer la cabecera ni el cuerpo de la pantalla:
-```vue
-<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` 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 { data, status } = await useFetch('/api/products', {
-        query: computed(() => ({ page: query.value.page, sort: query.value.sort?.column, ...query.value.filters })),
-    })
+    const name = ref('')
+    const active = ref(true)
 </script>
 <template>
-    <VDataTable
-        v-model:query="query"
-        :definition="definition"
-        :data="data?.data ?? []"
-        :total="data?.total ?? 0"
-        :loading="status === 'pending'"
-    />
+    <Form @submit.prevent>
+        <TextInput
+            v-model="name"
+            label-text="Nombre"
+        />
+        <Toggle
+            v-model="active"
+            label-text="Activo"
+        />
+        <Button type="submit">Guardar</Button>
+    </Form>
 </template>
 ```
-Con `url: true` los filtros, la página, la búsqueda y el orden viajan en la query string: el enlace es compartible y recargar conserva la vista.
-### Tipos de columna
-`text` · `number` · `currency` · `date` · `badge` · `boolean` · `image` · `actions` · `custom`
-Cada uno declara sus propios props en una unión discriminada por `type`, igual que los campos. `key` es la ruta del valor en la fila y admite anidado: `key: 'proveedor.nombre'`.
-```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' },
-    ],
-} 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:
-```ts
-{
-  key: 'role',
-  label: 'Rol',
-  type: 'badge',
-  map: {
-    user:  { color: 'neutral', label: 'Usuario' },
-    admin: { color: 'primary', label: 'Administrador' },
-  },
-}
-```
-Un valor sin entrada en el `map` se pinta tal cual, con el `color` de la columna o `neutral`. Es deliberado: si el servidor empieza a mandar un estado nuevo, verás el valor crudo en pantalla en lugar de una celda vacía que esconde que hay algo sin contemplar.
-#### Calcular el valor desde la fila
-Cuando lo que se muestra no está en una sola clave, o hay que derivarlo, toda columna acepta `value`:
-```ts
-{ key: 'role',  label: 'Rol',    type: 'text', value: (row) => traducirRol(row.role) }
-{ key: 'total', label: 'Total',  type: 'currency', value: (row) => row.precio * row.unidades }
-{ key: 'autor', label: 'Autor',  type: 'text', value: (row) => `${row.nombre} ${row.apellido}` }
-```
-Recibe la fila entera y está tipada: con `VunoTableDefinition<Product>`, `row` es un `Product`.
-**Sustituye de dónde sale el valor, no cómo se pinta.** Lo que devuelve sigue pasando por el formato de su tipo de columna, así que se combina con todo lo demás: en una columna `currency` se formatea como moneda, en una `date` como fecha, y en un `badge` pasa por su `map`.
-```ts
-// Deriva el valor, y el `map` lo traduce después.
-{ key: 'estado', type: 'badge', value: (row) => (row.stock > 0 ? 'disponible' : 'agotado'), map: { agotado: { color: 'error', label: 'Agotado' }, disponible: { color: 'success', label: 'Disponible' } } }
-```
-`key` sigue haciendo falta: nombra la columna para el orden y para el slot `cell-<key>`.
-Y un aviso al ordenar: `sortable` ordena **en servidor por `key`**, y el servidor no conoce esta función. Si el valor mostrado no se deriva de `key` de forma monótona —un nombre completo compuesto de dos campos, por ejemplo— el orden no coincidirá con lo que se ve. Para eso, ordena por la clave que de verdad manda o deja la columna sin `sortable`.
-`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: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" />
-  </template>
-</VTable>
-```
-El slot se llama `cell-<key>` y recibe `value` —el valor de esa columna, ya resuelto por su `key`— y `row` entera, directa y sin envolver.
-### Una tabla vacía no es una que falló
-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))
-```
-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`.
-Si vienes de componerlo a mano, cuenta con un efecto lateral: si tu proyecto tiene un test que sujeta esta invariante buscando el objeto en la pantalla, se pondrá **rojo** al mudar los textos, porque ahí ya no hay ningún `retry:` que encontrar. No es una regresión —la garantía sigue, solo que ahora la sostiene el tipo `VunoTableFailure`, cuyo `retry` es obligatorio y comprueba el typecheck— pero el test tiene que mirar otra cosa.
-El reintento va **dentro** del objeto para que no se pueda pintar un error sin ofrecer salida. Mientras hay fallo, la tabla no muestra filas ni paginación. El estado vacío se declara en la definición (`empty: { title, hint, icon }`) y tiene un slot `empty-actions` donde encaja el «crear el primero».
-Los dos estados existen además sueltos, para las pantallas que no son una tabla, y son **un solo componente con dos tonos**: `VState`. El tono no es un adjetivo sino el discriminante de una unión, así que `tone="failure"` exige el objeto del fallo y no hay forma de escribir un error sin su salida dentro:
-```vue
-<VState title="Todavía no hay pedidos" hint="Aparecerán aquí en cuanto entre el primero." icon="lucide:inbox">
-  <template #actions><VButton label="Crear pedido" /></template>
-</VState>
-<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
-`VConfirm` acepta `description` como texto plano y un slot por defecto para cuando el aviso es información que cambia la decisión:
-```vue
-<VConfirm v-model:open="open" :title="`¿Eliminar ${marca.nombre}?`" @confirm="borrar">
-  <p>Se eliminará <strong>{{ marca.nombre }}</strong>.</p>
-  <p class="text-vuno-warning">{{ marca.productos }} productos se quedarán sin marca.</p>
-</VConfirm>
-```
-No se cierra solo cuando recibe `loading`: así se espera a que la acción termine contra la API y se cierra desde fuera.
-## Modales del proyecto
-Un modal por componente, en `components/modal/`, abierto por su clave:
-```
-app/components/modal/ModalProduct.vue   ->   open('product')
-app/components/modal/ModalInvoice.vue   ->   open('invoice')
-```
-```ts
-const modal = useModal()
-const guardado = await modal.open<boolean>('product', { sku: row.sku })
-```
-No hay que registrarlo ni colocarlo en ninguna plantilla: el módulo marca esa carpeta como global, así que la clave **es** el nombre del componente y un modal que existe se puede abrir.
-El componente recibe `open` y los props que le pases, y resuelve la promesa emitiendo `close` con su resultado:
-```vue
-<script setup lang="ts">
-    const emit = defineEmits<{ close: [guardado: boolean] }>()
-    const open = defineModel<boolean>('open', { default: false })
-    function guardar() {
-        open.value = false
-        emit('close', true)
-    }
-</script>
-```
-Se pinta en `<VApp>` y no en la pantalla que lo abrió, así que navegar no lo desmonta a medias ni deja la promesa colgada. Cerrarlo con Escape o pulsando fuera resuelve sin valor.
-## 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`.                                         |
-| `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.** 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);
-}
-```
-Con esa línea cambian los botones sólidos, el anillo de foco de todos los campos, el enlace activo, la casilla marcada y el acento de las insignias: no hay un solo componente que escriba ese azul por su cuenta.
-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-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);
-}
-```
-### Los niveles de configuración
-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: {
-        components: {
-            formSection: { slots: { root: 'border-dashed' } },
-        },
-        icons: { slugEdit: 'lucide:wand-sparkles' },
-        locale: 'es-ES',
-        messages: { selectPlaceholder: 'Elige una opción' },
-        theme: { radius: 'md' },
-    },
-})
-```
-```vue
-<!-- prop `ui` — para una instancia -->
-<VForm :ui="{ sections: 'gap-8' }" ... />
-```
-Se funden en orden de especificidad creciente —tema por defecto, `app.config`, prop `ui`— y los conflictos los deshace `tailwind-merge`, así que la última clase gana de verdad y no depende del orden de la hoja.
-Los textos e iconos están todos en `vuno.messages` y `vuno.icons`: el paquete no impone idioma ni colección de iconos. El formato de fechas, números y monedas sale de `vuno.locale`, que se declara en vez de leerse del navegador —con render en servidor, adivinarlo da un número en el HTML y otro al hidratar—.
-## Estado
+Los componentes se consumen sin prefijo y los formularios usan composición Vue normal. No existe una definición de campos que renderice la interfaz.
-En desarrollo.
+## Temas
-### Nota sobre pruebas automatizadas
+Aplica `vuno--light`, `vuno--light-gray`, `vuno--dark-gray` o `vuno--dark` en la raíz correspondiente. Los componentes consumen tokens semánticos `--vuno-*`. La prop `ui` ajusta slots localmente y `app.config.ts` lo hace globalmente bajo la clave `vuno`.
-Dos trampas, las dos medidas aquí, que hacen que una comprobación afirme lo contrario de lo que pasa.
+## Datos, capas y shell
-**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.
+`DataTable` coordina filas, cabeceras, orden y selección. `Table`, `TableToolbar`, `TableBatchActions`, `Pagination` y sus piezas públicas componen la experiencia; la consulta y los estados de negocio pertenecen a la aplicación consumidora. `StructuredListWrapper` cubre relaciones simples sin convertirlas en una tabla de datos.
-**`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.
+La familia UI shell se compone con `Header`, `HeaderNavigation`, `HeaderGlobalBar`, `SideNav`, `SideNavItems`, `Switcher`, `SkipToContent` y `Content`. `Modal`, `Popover`, `Menu`, `Tooltip` y `Toggletip` mantienen sus propios contratos de foco e interacción.
-## Licencia
+Los tipos se exportan desde el paquete y los componentes se registran globalmente. `internal/` y `primitives/` son privados.
-[MIT](./LICENSE) © Diego Otayza
+Consulta el [README del repositorio](../../README.md), [DESIGN.md](../../DESIGN.md) y el catálogo de `apps/web`.