@groupteknology/vuno 0.1.0 → 0.4.0

package/README.md

@@ -1,215 +1,330 @@
-# @groupteknology/vuno
-
-Formularios, tablas y diálogos declarativos para Nuxt 4, construidos sobre [Nuxt UI](https://ui.nuxt.com).
-
-El módulo **no aporta estética**. Todo lo que pinta sale del tema del proyecto que lo instala: usa las utilidades semánticas de Nuxt UI (`bg-default`, `text-muted`, `border-default`), su escala de radios y sus colores. Si cambias `primary` o `--ui-radius`, los componentes de vuno cambian contigo.
-
-## Instalación
-
-```bash
-pnpm add @groupteknology/vuno
-```
-
-```ts
-// nuxt.config.ts
-export default defineNuxtConfig({
-  modules: ['@nuxt/ui', '@groupteknology/vuno'],
-})
-```
-
-## 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 }">
-      <UButton :disabled="!dirty" label="Descartar" variant="ghost" @click="reset" />
-      <UButton label="Guardar" type="submit" />
-    </template>
-  </VForm>
-</template>
-```
-
-### Tipos de campo
-
-`text` · `email` · `password` · `textarea` · `number` · `select` · `radio` · `checkbox` · `color` · `slug` · `file` · `array`
-
-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 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
-
-`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" />
-```
-
-## Una pantalla de mantenimiento entera
-
-`useVunoCrud` 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">
-const query = useVunoTableQuery({ sort: 'sku', url: true })
-
-const { items, total, failure, isPending, isSaving, isDeleting,
-        formOpen, editing, state, submit, openCreate, openEdit,
-        confirmOpen, deleting, askDelete, confirmDelete } = useVunoCrud<Product, ProductForm>({
-  key: 'products',
-  query,
-  emptyForm: () => ({ name: '', sku: '' }),
-  list:   (q)        => $fetch('/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>
-```
-
-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`.
-
-`@tanstack/vue-query` es una dependencia opcional: solo hace falta si usas este composable.
-
-## Páginas
-
-`VPage` pone la estructura que repite cualquier pantalla de mantenimiento:
-
-```vue
-<VPage title="Productos" description="Catálogo completo." :breadcrumb="[{ label: 'Inicio', to: '/' }, { label: 'Productos' }]">
-  <template #actions>
-    <UButton icon="lucide:plus" label="Nuevo producto" @click="openCreate" />
-  </template>
-
-  <VTable ... />
-</VPage>
-```
-
-## Tablas
-
-`VTable` funciona en modo servidor: emite el estado de consulta y tú devuelves la página.
-
-```vue
-<script setup lang="ts">
-const query = useVunoTableQuery({ 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 })),
-})
-</script>
-
-<template>
-  <VTable v-model:query="query" :definition="definition" :data="data?.data ?? []" :total="data?.total ?? 0" :loading="status === 'pending'" />
-</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.
-
-### 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)
-```
-
-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 como componentes sueltos, para las pantallas que no son una tabla:
-
-```vue
-<VEmptyState title="Todavía no hay pedidos" hint="Aparecerán aquí en cuanto entre el primero." icon="lucide:inbox">
-  <template #actions><UButton label="Crear pedido" /></template>
-</VEmptyState>
-
-<VFailureState :failure="failure" />
-```
-
-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.
-
-## Personalización
-
-Tres niveles, de más global a más concreto:
-
-```ts
-// app.config.ts — para toda la aplicación
-export default defineAppConfig({
-  ui: { colors: { primary: 'indigo' } },
-  vuno: {
-    formSection: { slots: { root: 'border-dashed' } },
-    icons: { slugEdit: 'lucide:wand-sparkles' },
-    messages: { selectPlaceholder: 'Elige una opción' },
-  },
-})
-```
-
-```vue
-<!-- prop `ui` — para una instancia -->
-<VForm :ui="{ sections: 'gap-8' }" ... />
-```
-
-Los textos e iconos están todos en `vuno.messages` y `vuno.icons`: el paquete no impone idioma ni colección de iconos.
-
-## Estado
-
-En desarrollo.
-
-### Nota sobre pruebas automatizadas
-
-Al comprobar los diálogos con un navegador controlado por automatización, el nodo del modal puede seguir en el DOM después de cerrarlo. No es un fallo: Chrome congela las animaciones CSS en pestañas ocultas y Reka UI espera el evento `animationend` para desmontar el diálogo. El componente ya está cerrado —lo indica su `data-state="closed"`—, solo falta la limpieza.
-
-Comprueba la visibilidad real (`opacity`, `data-state`) en lugar de la existencia del nodo, o haz la prueba con la pestaña en primer plano.
-
-## Licencia
-
-[MIT](./LICENSE) © Diego Otayza
+# @groupteknology/vuno
+
+Formularios, tablas y diálogos declarativos para Nuxt 4, construidos sobre [Nuxt UI](https://ui.nuxt.com).
+
+El módulo **no aporta estética**. Todo lo que pinta sale del tema del proyecto que lo instala: usa las utilidades semánticas de Nuxt UI (`bg-default`, `text-muted`, `border-default`), su escala de radios y sus colores. Si cambias `primary` o `--ui-radius`, los componentes de vuno cambian contigo.
+
+## Instalación
+
+```bash
+pnpm add @groupteknology/vuno
+```
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+  modules: ['@nuxt/ui', '@groupteknology/vuno'],
+})
+```
+
+## 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 }">
+      <UButton :disabled="!dirty" label="Descartar" variant="ghost" @click="reset" />
+      <UButton label="Guardar" type="submit" />
+    </template>
+  </VForm>
+</template>
+```
+
+### Tipos de campo
+
+`text` · `email` · `password` · `textarea` · `number` · `select` · `radio` · `checkbox` · `switch` · `color` · `slug` · `file` · `array`
+
+`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 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 }">
+    <UButton label="Cancelar" variant="ghost" @click="close" />
+    <UButton :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" />
+```
+
+## Una pantalla de mantenimiento entera
+
+`useVunoCrud` 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 = useVunoTableQuery({ sort: 'sku', url: true })
+
+const { items, total, failure, isPending, isSaving, isDeleting,
+        formOpen, editing, state, submit, openCreate, openEdit,
+        confirmOpen, deleting, askDelete, confirmDelete } = useVunoCrud<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 = useVunoCrud({
+  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
+useVunoCrud({ 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:
+
+```ts
+key: () => productKeys.all()        // un alta refresca todo el dominio
+key: () => productKeys.list(filtros) // solo refresca esa combinación de filtros
+```
+
+### Render en servidor
+
+`useVunoCrud` 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()
+
+  nuxtApp.vueApp.use(VueQueryPlugin, { queryClient })
+
+  if (import.meta.server) nuxtApp.hooks.hook('app:rendered', () => { state.value = dehydrate(queryClient) })
+  if (import.meta.client) hydrate(queryClient, state.value)
+})
+```
+
+**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.
+
+`@tanstack/vue-query` es una dependencia opcional: solo hace falta si usas este composable.
+
+## Páginas
+
+`VPage` pone la estructura que repite cualquier pantalla de mantenimiento:
+
+```vue
+<VPage title="Productos" description="Catálogo completo." :breadcrumb="[{ label: 'Inicio', to: '/' }, { label: 'Productos' }]">
+  <template #actions>
+    <UButton icon="lucide:plus" label="Nuevo producto" @click="openCreate" />
+  </template>
+
+  <VTable ... />
+</VPage>
+```
+
+## Tablas
+
+`VTable` funciona en modo servidor: emite el estado de consulta y tú devuelves la página.
+
+```vue
+<script setup lang="ts">
+const query = useVunoTableQuery({ 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 })),
+})
+</script>
+
+<template>
+  <VTable v-model:query="query" :definition="definition" :data="data?.data ?? []" :total="data?.total ?? 0" :loading="status === 'pending'" />
+</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.
+
+### 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)
+```
+
+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 como componentes sueltos, para las pantallas que no son una tabla:
+
+```vue
+<VEmptyState title="Todavía no hay pedidos" hint="Aparecerán aquí en cuanto entre el primero." icon="lucide:inbox">
+  <template #actions><UButton label="Crear pedido" /></template>
+</VEmptyState>
+
+<VFailureState :failure="failure" />
+```
+
+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-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.
+
+## Composables
+
+| Composable | Para qué |
+|---|---|
+| `useVunoCrud` | El ciclo de mantenimiento entero sobre TanStack Query. |
+| `useVunoTableQuery` | Estado de consulta de una tabla, opcionalmente sincronizado con la query string. |
+| `useVunoForm` | Contexto del `VForm` que envuelve al componente: estado, `dirty`, `reset`. |
+| `useVunoField` | Lee y escribe un campo por su ruta; para construir campos propios. |
+| `useVunoTheme` | Resuelve los slots de un componente cruzando tema, `app.config` y prop `ui`. |
+| `useVunoIcons` | Los iconos configurados en `vuno.icons`. |
+| `useVunoMessages` | 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.
+
+## Personalización
+
+Tres niveles, de más global a más concreto:
+
+```ts
+// app.config.ts — para toda la aplicación
+export default defineAppConfig({
+  ui: { colors: { primary: 'indigo' } },
+  vuno: {
+    formSection: { slots: { root: 'border-dashed' } },
+    icons: { slugEdit: 'lucide:wand-sparkles' },
+    messages: { selectPlaceholder: 'Elige una opción' },
+  },
+})
+```
+
+```vue
+<!-- prop `ui` — para una instancia -->
+<VForm :ui="{ sections: 'gap-8' }" ... />
+```
+
+Los textos e iconos están todos en `vuno.messages` y `vuno.icons`: el paquete no impone idioma ni colección de iconos.
+
+## Estado
+
+En desarrollo.
+
+### Nota sobre pruebas automatizadas
+
+Al comprobar los diálogos con un navegador controlado por automatización, el nodo del modal puede seguir en el DOM después de cerrarlo. No es un fallo: Chrome congela las animaciones CSS en pestañas ocultas y Reka UI espera el evento `animationend` para desmontar el diálogo. El componente ya está cerrado —lo indica su `data-state="closed"`—, solo falta la limpieza.
+
+Comprueba la visibilidad real (`opacity`, `data-state`) en lugar de la existencia del nodo, o haz la prueba con la pestaña en primer plano.
+
+## Licencia
+
+[MIT](./LICENSE) © Diego Otayza

package/dist/module.json

@@ -1,7 +1,7 @@
 {
   "name": "vuno",
   "configKey": "vuno",
-  "version": "0.1.0",
+  "version": "0.4.0",
   "builder": {
     "@nuxt/module-builder": "1.0.3",
     "unbuild": "unknown"

package/dist/runtime/app/components/Confirm/Confirm.d.vue.ts

@@ -4,11 +4,19 @@ type __VLS_Props = VunoConfirmOptions & {
     loading?: boolean;
     ui?: VunoFieldSlots;
 };
+type __VLS_Slots = {
+    /**
+     * Sustituye a `description`. Para cuando el aviso es información que
+     * cambia la decisión —cuántos hijos quedan huérfanos, qué se pierde—
+     * y aplanarlo a una frase la escondería.
+     */
+    default?: () => unknown;
+};
 type __VLS_ModelProps = {
     'open'?: boolean;
 };
 type __VLS_PublicProps = __VLS_Props & __VLS_ModelProps;
-declare const __VLS_export: import("vue").DefineComponent<__VLS_PublicProps, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
+declare const __VLS_base: import("vue").DefineComponent<__VLS_PublicProps, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
     "update:open": (value: boolean) => any;
     confirm: () => any;
     cancel: () => any;
@@ -17,5 +25,11 @@ declare const __VLS_export: import("vue").DefineComponent<__VLS_PublicProps, {},
     onConfirm?: (() => any) | undefined;
     onCancel?: (() => any) | undefined;
 }>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const __VLS_export: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;
 declare const _default: typeof __VLS_export;
 export default _default;
+type __VLS_WithSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};

package/dist/runtime/app/components/Confirm/Confirm.vue

@@ -12,6 +12,7 @@ const props = defineProps({
   ui: { type: Object, required: false }
 });
 const emit = defineEmits(["cancel", "confirm"]);
+defineSlots();
 const open = defineModel("open", { type: Boolean, ...{ default: false } });
 const icons = useVunoIcons();
 const messages = useVunoMessages();
@@ -29,37 +30,39 @@ function onConfirm() {
 </script>
 
 <template>
-    <UModal
-        v-model:open="open"
-        :dismissible="!props.loading"
-        scrollable
-        :title="props.title ?? messages.confirmTitle"
-        :ui="modalUi"
-    >
-        <template #body>
-            <div :class="ui.body">
-                <UIcon
-                    :class="[ui.icon, `text-${color}`]"
-                    :name="props.icon ?? icons.confirm"
-                />
-                <p>{{ props.description ?? messages.confirmDescription }}</p>
-            </div>
-        </template>
-
-        <template #footer>
-            <UButton
-                color="neutral"
-                :disabled="props.loading"
-                :label="props.cancelLabel ?? messages.cancel"
-                variant="ghost"
-                @click="onCancel"
-            />
-            <UButton
-                :color="color"
-                :label="props.confirmLabel ?? messages.confirm"
-                :loading="props.loading"
-                @click="onConfirm"
-            />
-        </template>
-    </UModal>
+    <UModal
+        v-model:open="open"
+        :dismissible="!props.loading"
+        scrollable
+        :title="props.title ?? messages.confirmTitle"
+        :ui="modalUi"
+    >
+        <template #body>
+            <div :class="ui.body">
+                <UIcon
+                    :class="[ui.icon, `text-${color}`]"
+                    :name="props.icon ?? icons.confirm"
+                />
+                <div :class="ui.description">
+                    <slot>{{ props.description ?? messages.confirmDescription }}</slot>
+                </div>
+            </div>
+        </template>
+
+        <template #footer>
+            <UButton
+                color="neutral"
+                :disabled="props.loading"
+                :label="props.cancelLabel ?? messages.cancel"
+                variant="ghost"
+                @click="onCancel"
+            />
+            <UButton
+                :color="color"
+                :label="props.confirmLabel ?? messages.confirm"
+                :loading="props.loading"
+                @click="onConfirm"
+            />
+        </template>
+    </UModal>
 </template>

package/dist/runtime/app/components/Confirm/Confirm.vue.d.ts

@@ -4,11 +4,19 @@ type __VLS_Props = VunoConfirmOptions & {
     loading?: boolean;
     ui?: VunoFieldSlots;
 };
+type __VLS_Slots = {
+    /**
+     * Sustituye a `description`. Para cuando el aviso es información que
+     * cambia la decisión —cuántos hijos quedan huérfanos, qué se pierde—
+     * y aplanarlo a una frase la escondería.
+     */
+    default?: () => unknown;
+};
 type __VLS_ModelProps = {
     'open'?: boolean;
 };
 type __VLS_PublicProps = __VLS_Props & __VLS_ModelProps;
-declare const __VLS_export: import("vue").DefineComponent<__VLS_PublicProps, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
+declare const __VLS_base: import("vue").DefineComponent<__VLS_PublicProps, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
     "update:open": (value: boolean) => any;
     confirm: () => any;
     cancel: () => any;
@@ -17,5 +25,11 @@ declare const __VLS_export: import("vue").DefineComponent<__VLS_PublicProps, {},
     onConfirm?: (() => any) | undefined;
     onCancel?: (() => any) | undefined;
 }>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const __VLS_export: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;
 declare const _default: typeof __VLS_export;
 export default _default;
+type __VLS_WithSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};

package/dist/runtime/app/components/Field/FieldSwitch.d.vue.ts

@@ -0,0 +1,5 @@
+import type { VunoFieldSwitch } from '#vuno/types/field';
+type __VLS_Props = Omit<VunoFieldSwitch, 'class' | 'columns'>;
+declare const __VLS_export: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const _default: typeof __VLS_export;
+export default _default;

package/dist/runtime/app/components/Field/FieldSwitch.vue

@@ -0,0 +1,27 @@
+<script setup>
+import { useVunoField } from "#vuno/composables/useVunoField";
+import { useVunoTheme } from "#vuno/composables/useVunoTheme";
+const props = defineProps({
+  name: { type: String, required: true },
+  description: { type: String, required: false },
+  disabled: { type: Boolean, required: false },
+  help: { type: String, required: false },
+  hint: { type: String, required: false },
+  label: { type: String, required: false },
+  required: { type: Boolean, required: false },
+  size: { type: String, required: false },
+  ui: { type: Object, required: false }
+});
+const { value } = useVunoField(() => props.name);
+const ui = useVunoTheme("fieldSwitch", () => props.ui);
+</script>
+
+<template>
+    <USwitch
+        v-model="value"
+        :disabled="props.disabled"
+        :name="props.name"
+        :size="props.size"
+        :ui="ui"
+    />
+</template>

package/dist/runtime/app/components/Field/FieldSwitch.vue.d.ts

@@ -0,0 +1,5 @@
+import type { VunoFieldSwitch } from '#vuno/types/field';
+type __VLS_Props = Omit<VunoFieldSwitch, 'class' | 'columns'>;
+declare const __VLS_export: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const _default: typeof __VLS_export;
+export default _default;

package/dist/runtime/app/components/Form/Form.vue

@@ -101,6 +101,7 @@ defineExpose({ dirty, errors: errorNames, isDirty, reset, resetField, submit: ()
             :size="size"
             :ui="{ root: ui.tabs, content: ui.tabsContent }"
             :unmountOnHide="false"
+            variant="link"
         >
             <template #content="{ item }">
                 <FormSection

package/dist/runtime/app/components/Form/FormField.vue

@@ -12,6 +12,7 @@ import FieldPassword from "#vuno/components/Field/FieldPassword.vue";
 import FieldRadio from "#vuno/components/Field/FieldRadio.vue";
 import FieldSelect from "#vuno/components/Field/FieldSelect.vue";
 import FieldSlug from "#vuno/components/Field/FieldSlug.vue";
+import FieldSwitch from "#vuno/components/Field/FieldSwitch.vue";
 import FieldText from "#vuno/components/Field/FieldText.vue";
 import FieldTextarea from "#vuno/components/Field/FieldTextarea.vue";
 const props = defineProps({
@@ -28,6 +29,7 @@ const components = {
   radio: FieldRadio,
   select: FieldSelect,
   slug: FieldSlug,
+  switch: FieldSwitch,
   text: FieldText,
   textarea: FieldTextarea
 };
@@ -42,20 +44,20 @@ const fieldProps = computed(() => {
 </script>
 
 <template>
-    <UFormField
-        :class="props.field.class"
-        :description="props.field.description"
-        :help="props.field.help"
-        :hint="props.field.hint"
-        :label="props.field.label"
-        :name="props.field.name"
-        :required="props.field.required"
-        :size="size"
-        :ui="ui"
-    >
-        <component
-            :is="component"
-            v-bind="fieldProps"
-        />
-    </UFormField>
+    <UFormField
+        :class="props.field.class"
+        :description="props.field.description"
+        :help="props.field.help"
+        :hint="props.field.hint"
+        :label="props.field.label"
+        :name="props.field.name"
+        :required="props.field.required"
+        :size="size"
+        :ui="ui"
+    >
+        <component
+            :is="component"
+            v-bind="fieldProps"
+        />
+    </UFormField>
 </template>

package/dist/runtime/app/components/Form/FormModal.d.vue.ts

@@ -32,8 +32,14 @@ declare const __VLS_export: <TState extends VunoFormState>(__VLS_props: NonNulla
     expose: (exposed: {}) => void;
     attrs: any;
     slots: {
+        /**
+         * `formId` es imprescindible, no un extra: el pie del modal vive fuera
+         * del `<form>`, así que un botón propio solo puede enviarlo con
+         * `:form="formId"`. Sin exponerlo, cualquier pie a medida queda mudo.
+         */
         footer?: (props: {
             dirty: boolean;
+            formId: string;
             loading: boolean;
             close: () => void;
             reset: () => void;

package/dist/runtime/app/components/Form/FormModal.vue

@@ -33,50 +33,51 @@ function onSubmit(event) {
 </script>
 
 <template>
-    <UModal
-        v-model:open="open"
-        :description="props.description"
-        :dismissible="!props.loading"
-        scrollable
-        :title="props.title"
-        :ui="modalUi"
-    >
-        <slot name="trigger" />
-
-        <template #body>
-            <Form
-                :id="formId"
-                ref="form"
-                v-model:state="state"
-                :definition="props.definition"
-                :schema="props.schema"
-                :ui="props.formUi"
-                @submit="onSubmit"
-            />
-        </template>
-
-        <template #footer>
-            <slot
-                :close="close"
-                :dirty="form?.dirty ?? false"
-                :loading="props.loading ?? false"
-                name="footer"
-                :reset="() => form?.reset?.()"
-            >
-                <UButton
-                    color="neutral"
-                    :disabled="props.loading"
-                    :label="messages.cancel"
-                    variant="ghost"
-                    @click="close"
-                />
-                <UButton
-                    :form="formId"
-                    :label="messages.save"
-                    :loading="props.loading"
-                    type="submit"
-                />
-            </slot>
-        </template>
-    </UModal>
+    <UModal
+        v-model:open="open"
+        :description="props.description"
+        :dismissible="!props.loading"
+        scrollable
+        :title="props.title"
+        :ui="modalUi"
+    >
+        <slot name="trigger" />
+
+        <template #body>
+            <Form
+                :id="formId"
+                ref="form"
+                v-model:state="state"
+                :definition="props.definition"
+                :schema="props.schema"
+                :ui="props.formUi"
+                @submit="onSubmit"
+            />
+        </template>
+
+        <template #footer>
+            <slot
+                :close="close"
+                :dirty="form?.dirty ?? false"
+                :formId="formId"
+                :loading="props.loading ?? false"
+                name="footer"
+                :reset="() => form?.reset?.()"
+            >
+                <UButton
+                    color="neutral"
+                    :disabled="props.loading"
+                    :label="messages.cancel"
+                    variant="ghost"
+                    @click="close"
+                />
+                <UButton
+                    :form="formId"
+                    :label="messages.save"
+                    :loading="props.loading"
+                    type="submit"
+                />
+            </slot>
+        </template>
+    </UModal>
 </template>

package/dist/runtime/app/components/Form/FormModal.vue.d.ts

@@ -32,8 +32,14 @@ declare const __VLS_export: <TState extends VunoFormState>(__VLS_props: NonNulla
     expose: (exposed: {}) => void;
     attrs: any;
     slots: {
+        /**
+         * `formId` es imprescindible, no un extra: el pie del modal vive fuera
+         * del `<form>`, así que un botón propio solo puede enviarlo con
+         * `:form="formId"`. Sin exponerlo, cualquier pie a medida queda mudo.
+         */
         footer?: (props: {
             dirty: boolean;
+            formId: string;
             loading: boolean;
             close: () => void;
             reset: () => void;

package/dist/runtime/app/composables/useVunoCrud.js

@@ -1,7 +1,8 @@
 import { keepPreviousData, useMutation, useQuery, useQueryClient } from "@tanstack/vue-query";
 import { useToast } from "@nuxt/ui/composables";
-import { computed, ref, shallowRef } from "vue";
+import { computed, onServerPrefetch, ref, shallowRef, toValue } from "vue";
 import { getPath } from "#vuno/utils/path";
+import { resolveQueryKey } from "#vuno/utils/query-key";
 import { useVunoMessages } from "./useVunoTheme.js";
 import { useVunoTableQuery } from "./useVunoTableQuery.js";
 export function useVunoCrud(options) {
@@ -9,7 +10,9 @@ export function useVunoCrud(options) {
   const queryClient = useQueryClient();
   const messages = useVunoMessages();
   const query = options.query ?? useVunoTableQuery();
-  const baseKey = computed(() => Array.isArray(options.key) ? options.key : [options.key]);
+  const resolvedKey = computed(() => resolveQueryKey(toValue(options.key)));
+  const baseKey = computed(() => resolvedKey.value.segments);
+  const isEnabled = computed(() => resolvedKey.value.ready && (toValue(options.enabled) ?? true));
   const rowKey = options.rowKey ?? "id";
   const text = computed(() => ({
     created: options.messages?.created ?? messages.value.created,
@@ -19,20 +22,38 @@ export function useVunoCrud(options) {
     updated: options.messages?.updated ?? messages.value.updated,
     updateFailed: options.messages?.updateFailed ?? messages.value.saveFailed
   }));
-  const { data, isError, isPending, refetch } = useQuery({
+  const { data, isError, isPending, refetch, suspense } = useQuery({
     // Sin esto, cambiar de filtro o de página deja `data` en undefined
     // mientras llega la respuesta y la tabla parpadea enseñando su estado
     // vacío. Con los datos anteriores en pantalla, el cambio no salta.
+    enabled: isEnabled,
     placeholderData: keepPreviousData,
     queryKey: computed(() => [...baseKey.value, query.value]),
     // La consulta forma parte de la clave: otra página u otro filtro es otra
     // consulta, y así cada una se cachea por separado.
     queryFn: () => options.list(query.value)
   });
+  onServerPrefetch(async () => {
+    if (options.server === false) return;
+    if (!isEnabled.value) return;
+    try {
+      await suspense();
+    } catch {
+    }
+  });
   const items = computed(() => data.value?.data ?? []);
   const total = computed(() => data.value?.total ?? 0);
-  const failure = computed(() => isError.value ? { retry: () => void refetch() } : void 0);
+  const failure = computed(
+    () => isError.value ? {
+      // Sin valor propio los deja en `undefined` y el estado de
+      // fallo cae a los textos globales de `vuno.messages`.
+      hint: options.messages?.listFailedHint,
+      title: options.messages?.listFailed,
+      retry: () => void refetch()
+    } : void 0
+  );
   function invalidate() {
+    if (!resolvedKey.value.ready) return;
     void queryClient.invalidateQueries({ queryKey: baseKey.value });
   }
   const formOpen = ref(false);
@@ -100,6 +121,7 @@ export function useVunoCrud(options) {
     formOpen,
     invalidate,
     isDeleting: remove.isPending,
+    isEnabled,
     isPending,
     isSaving: save.isPending,
     items,

package/dist/runtime/app/theme/index.js

@@ -3,6 +3,7 @@ export const defaultTheme = {
     slots: {
       body: "flex items-start gap-3",
       content: "max-w-md",
+      description: "min-w-0 space-y-1",
       footer: "justify-end",
       icon: "shrink-0 size-5"
     }
@@ -49,6 +50,9 @@ export const defaultTheme = {
   fieldSlug: {
     slots: { root: "w-full", trailing: "pe-1" }
   },
+  fieldSwitch: {
+    slots: { root: "w-full" }
+  },
   fieldText: {
     slots: { root: "w-full" }
   },

package/dist/runtime/app/types/crud.d.ts

@@ -1,4 +1,4 @@
-import type { ComputedRef, Ref } from 'vue';
+import type { ComputedRef, MaybeRefOrGetter, Ref } from 'vue';
 import type { VunoTableFailure, VunoTableQuery, VunoTableRow } from './table.js';
 /** Respuesta de un listado paginado en servidor. */
 export type VunoCrudPage<TRow> = {
@@ -10,26 +10,68 @@ export type VunoCrudMessages = {
     createFailed: string;
     deleted: string;
     deleteFailed: string;
+    /** Título cuando falla el listado. Por defecto, el de `vuno.messages`. */
+    listFailed: string;
+    /**
+     * Pista bajo ese título. Es el sitio para lo que evita un error a quien
+     * mira una tabla que no cargó: «no des una de alta sin verlas, puede
+     * existir ya».
+     */
+    listFailedHint: string;
     updated: string;
     updateFailed: string;
 };
 export type VunoCrudOptions<TRow extends VunoTableRow, TForm> = {
+    /**
+     * Condición extra para consultar, además de que la clave esté completa.
+     * Para lo que no se deduce de la clave: un permiso, una pestaña oculta.
+     */
+    enabled?: MaybeRefOrGetter<boolean>;
     /**
      * Clave base de la caché. La consulta se añade automáticamente, así que
      * cada página, filtro y orden se cachean por separado.
+     *
+     * Admite un getter o un `computed` para las claves que dependen de estado
+     * reactivo —la empresa, la tienda o el almacén seleccionados—: sin eso la
+     * clave se congelaría en su valor inicial y la pantalla seguiría enseñando
+     * los datos del anterior sin dar señal de error.
+     *
+     * ```ts
+     * key: () => ['products', selectedCompanyId.value]
+     * ```
+     *
+     * Un segmento `undefined` o `null` significa que la clave aún no está
+     * lista y suspende la consulta, así que no hace falta `?? ''` ni un
+     * `enabled` por pantalla.
      */
-    key: readonly unknown[] | string;
+    key: MaybeRefOrGetter<null | readonly unknown[] | string | undefined>;
     messages?: Partial<VunoCrudMessages>;
     /** Estado de consulta compartido con la tabla. */
     query?: Ref<VunoTableQuery>;
     /** Campo que identifica la fila. Por defecto `id`. */
     rowKey?: string;
+    /**
+     * Resolver el listado durante el render en servidor. Por defecto `true`.
+     *
+     * Ponlo en `false` para lo que no se ve en la primera pintada —una lista
+     * dentro de un modal, una pestaña oculta—: ahí esperar solo retrasa el
+     * HTML sin que nadie lo aproveche.
+     */
+    server?: boolean;
     create?: (form: TForm) => Promise<unknown>;
     /** Estado inicial del formulario al dar de alta. */
     emptyForm: () => TForm;
     list: (query: VunoTableQuery) => Promise<VunoCrudPage<TRow>>;
     remove?: (row: TRow) => Promise<unknown>;
-    /** Convierte una fila en el estado del formulario al editar. */
+    /**
+     * Convierte una fila en el estado del formulario al editar.
+     *
+     * Es opcional solo mientras la fila y el formulario tengan la misma forma.
+     * En cuanto la fila traiga campos que no son del formulario —un contador,
+     * una fecha de alta— hace falta: sin él se copia la fila entera al estado
+     * y esos campos acaban viajando en el guardado, que es donde se nota, lejos
+     * de aquí.
+     */
     toForm?: (row: TRow) => TForm;
     update?: (id: number | string, form: TForm) => Promise<unknown>;
 };
@@ -46,6 +88,8 @@ export type VunoCrud<TRow extends VunoTableRow, TForm> = {
     failure: ComputedRef<undefined | VunoTableFailure>;
     formOpen: Ref<boolean>;
     isDeleting: Ref<boolean>;
+    /** La clave está completa y la consulta puede dispararse. */
+    isEnabled: ComputedRef<boolean>;
     isPending: Ref<boolean>;
     isSaving: Ref<boolean>;
     items: ComputedRef<TRow[]>;

package/dist/runtime/app/types/field.d.ts

@@ -52,6 +52,13 @@ export type VunoFieldArray = VunoFieldBase & {
 export type VunoFieldCheckbox = VunoFieldBase & {
     indeterminate?: boolean;
 };
+/**
+ * Interruptor para un booleano que es un estado encendido o apagado, no una
+ * opción que se marca. La diferencia con `checkbox` es de lectura, no de dato:
+ * en una pantalla de ajustes el interruptor dice «esto está activo» y la
+ * casilla dice «esto queda seleccionado».
+ */
+export type VunoFieldSwitch = VunoFieldBase;
 export type VunoFieldColor = VunoFieldBase & {
     placeholder?: string;
 };
@@ -112,7 +119,7 @@ export type VunoFieldTextarea = VunoFieldBase & {
  * Unión discriminada por `type`. Es lo que consume `VunoFormDefinition`, de modo
  * que cada campo de la definición queda tipado con sus propios props.
  */
-export type VunoField = WithType<VunoFieldArray, 'array'> | WithType<VunoFieldCheckbox, 'checkbox'> | WithType<VunoFieldColor, 'color'> | WithType<VunoFieldEmail, 'email'> | WithType<VunoFieldFile, 'file'> | WithType<VunoFieldNumber, 'number'> | WithType<VunoFieldPassword, 'password'> | WithType<VunoFieldRadio, 'radio'> | WithType<VunoFieldSelect, 'select'> | WithType<VunoFieldSlug, 'slug'> | WithType<VunoFieldText, 'text'> | WithType<VunoFieldTextarea, 'textarea'>;
+export type VunoField = WithType<VunoFieldArray, 'array'> | WithType<VunoFieldCheckbox, 'checkbox'> | WithType<VunoFieldColor, 'color'> | WithType<VunoFieldEmail, 'email'> | WithType<VunoFieldFile, 'file'> | WithType<VunoFieldNumber, 'number'> | WithType<VunoFieldPassword, 'password'> | WithType<VunoFieldRadio, 'radio'> | WithType<VunoFieldSelect, 'select'> | WithType<VunoFieldSlug, 'slug'> | WithType<VunoFieldSwitch, 'switch'> | WithType<VunoFieldText, 'text'> | WithType<VunoFieldTextarea, 'textarea'>;
 export type VunoFieldType = VunoField['type'];
 /** Extrae los props de un tipo concreto de campo: `VunoFieldOf<'slug'>`. */
 export type VunoFieldOf<TType extends VunoFieldType> = Extract<VunoField, {

package/dist/runtime/app/utils/query-key.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Clave base de la caché ya resuelta.
+ *
+ * `ready` en `false` significa que la clave todavía no se puede construir
+ * —falta la empresa, la tienda o el almacén que la pantalla está resolviendo—
+ * y que la consulta no debe dispararse.
+ */
+export type VunoResolvedKey = {
+    ready: boolean;
+    segments: readonly unknown[];
+};
+/**
+ * Normaliza la clave base a segmentos y dice si está completa.
+ *
+ * Un segmento `undefined` o `null` marca la clave como no lista. En una clave
+ * de caché ese hueco nunca es un valor: es un dato que aún no ha llegado, y
+ * consultar con él devolvería la lista de otro inquilino o una vacía. Tratarlo
+ * como «todavía no» evita que cada pantalla repita su propio `enabled`.
+ */
+export declare function resolveQueryKey(key: null | readonly unknown[] | string | undefined): VunoResolvedKey;

package/dist/runtime/app/utils/query-key.js

@@ -0,0 +1,7 @@
+export function resolveQueryKey(key) {
+  if (key === null || key === void 0) return { ready: false, segments: [] };
+  const segments = Array.isArray(key) ? key : [key];
+  if (segments.length === 0) return { ready: false, segments };
+  const complete = segments.every((segment) => segment !== null && segment !== void 0);
+  return { ready: complete, segments };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@groupteknology/vuno",
-  "version": "0.1.0",
+  "version": "0.4.0",
   "type": "module",
   "exports": {
     ".": {