@groupteknology/vuno 0.4.0 → 0.6.0

package/README.md

@@ -106,6 +106,87 @@ El slot `footer` recibe `formId`, necesario para enviar desde un botón propio:
 <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 `useVunoCrud`.
+
+#### 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
 
 `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).
@@ -241,6 +322,78 @@ const { data, status } = await useFetch('/api/products', {
 
 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 VunoTableDefinition<Product>
+```
+
+#### 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 :definition="definition" :data="rows">
+  <template #cell-stock="{ row, value }">
+    <span class="tabular-nums">{{ value }} uds.</span>
+    <UBadge 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.

package/dist/module.json

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

package/dist/runtime/app/components/Cell/CellBadge.d.vue.ts

@@ -0,0 +1,5 @@
+import type { VunoTableCellProps } from '#vuno/types/table';
+type __VLS_Props = VunoTableCellProps<'badge'>;
+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/Cell/CellBadge.vue

@@ -0,0 +1,24 @@
+<script setup>
+import { computed } from "vue";
+const props = defineProps({
+  column: { type: Object, required: true },
+  row: { type: Object, required: true },
+  value: { type: null, required: true }
+});
+const text = computed(() => props.value === null || props.value === void 0 ? "" : String(props.value));
+const badge = computed(() => {
+  const entry = props.column.map?.[text.value];
+  return {
+    color: entry?.color ?? props.column.color ?? "neutral",
+    label: entry?.label ?? text.value
+  };
+});
+</script>
+
+<template>
+    <UBadge
+        :color="badge.color"
+        :label="badge.label"
+        variant="subtle"
+    />
+</template>

package/dist/runtime/app/components/Cell/CellBadge.vue.d.ts

@@ -0,0 +1,5 @@
+import type { VunoTableCellProps } from '#vuno/types/table';
+type __VLS_Props = VunoTableCellProps<'badge'>;
+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/Cell/CellBoolean.d.vue.ts

@@ -0,0 +1,5 @@
+import type { VunoTableCellProps } from '#vuno/types/table';
+type __VLS_Props = VunoTableCellProps<'boolean'>;
+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/Cell/CellBoolean.vue

@@ -0,0 +1,21 @@
+<script setup>
+import { computed } from "vue";
+import { useVunoIcons } from "#vuno/composables/useVunoTheme";
+const props = defineProps({
+  column: { type: Object, required: true },
+  row: { type: Object, required: true },
+  value: { type: null, required: true }
+});
+const icons = useVunoIcons();
+const labelled = computed(() => Boolean(props.column.trueLabel || props.column.falseLabel));
+</script>
+
+<template>
+    <span v-if="labelled">{{ props.value ? props.column.trueLabel ?? "" : props.column.falseLabel ?? "" }}</span>
+
+    <UIcon
+        v-else
+        :class="props.value ? 'text-success' : 'text-muted'"
+        :name="props.value ? icons.booleanTrue : icons.booleanFalse"
+    />
+</template>

package/dist/runtime/app/components/Cell/CellBoolean.vue.d.ts

@@ -0,0 +1,5 @@
+import type { VunoTableCellProps } from '#vuno/types/table';
+type __VLS_Props = VunoTableCellProps<'boolean'>;
+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/Cell/CellCurrency.d.vue.ts

@@ -0,0 +1,5 @@
+import type { VunoTableCellProps } from '#vuno/types/table';
+type __VLS_Props = VunoTableCellProps<'currency'>;
+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/Cell/CellCurrency.vue

@@ -0,0 +1,14 @@
+<script setup>
+import { useLocale } from "@nuxt/ui/composables";
+import { formatCurrency } from "#vuno/utils/format";
+const props = defineProps({
+  column: { type: Object, required: true },
+  row: { type: Object, required: true },
+  value: { type: null, required: true }
+});
+const locale = useLocale();
+</script>
+
+<template>
+    <span class="tabular-nums">{{ formatCurrency(props.value, locale.code.value, props.column.currency, props.column.decimals) }}</span>
+</template>

package/dist/runtime/app/components/Cell/CellCurrency.vue.d.ts

@@ -0,0 +1,5 @@
+import type { VunoTableCellProps } from '#vuno/types/table';
+type __VLS_Props = VunoTableCellProps<'currency'>;
+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/Cell/CellDate.d.vue.ts

@@ -0,0 +1,5 @@
+import type { VunoTableCellProps } from '#vuno/types/table';
+type __VLS_Props = VunoTableCellProps<'date'>;
+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/Cell/CellDate.vue

@@ -0,0 +1,19 @@
+<script setup>
+import { computed } from "vue";
+import { useLocale } from "@nuxt/ui/composables";
+import { formatDate } from "#vuno/utils/format";
+const props = defineProps({
+  column: { type: Object, required: true },
+  row: { type: Object, required: true },
+  value: { type: null, required: true }
+});
+const locale = useLocale();
+const options = computed(() => ({
+  dateStyle: props.column.dateStyle ?? "medium",
+  ...props.column.timeStyle ? { timeStyle: props.column.timeStyle } : {}
+}));
+</script>
+
+<template>
+    <span class="tabular-nums">{{ formatDate(props.value, locale.code.value, options) }}</span>
+</template>

package/dist/runtime/app/components/Cell/CellDate.vue.d.ts

@@ -0,0 +1,5 @@
+import type { VunoTableCellProps } from '#vuno/types/table';
+type __VLS_Props = VunoTableCellProps<'date'>;
+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/Cell/CellImage.d.vue.ts

@@ -0,0 +1,5 @@
+import type { VunoTableCellProps } from '#vuno/types/table';
+type __VLS_Props = VunoTableCellProps<'image'>;
+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/Cell/CellImage.vue

@@ -0,0 +1,22 @@
+<script setup>
+import { computed } from "vue";
+import { getPath } from "#vuno/utils/path";
+const props = defineProps({
+  column: { type: Object, required: true },
+  row: { type: Object, required: true },
+  value: { type: null, required: true }
+});
+const src = computed(() => props.value === null || props.value === void 0 ? "" : String(props.value));
+const alt = computed(() => {
+  if (props.column.altKey) return String(getPath(props.row, props.column.altKey) ?? "");
+  return props.column.alt ?? "";
+});
+</script>
+
+<template>
+    <UAvatar
+        :alt="alt"
+        :size="props.column.size ?? 'md'"
+        :src="src"
+    />
+</template>

package/dist/runtime/app/components/Cell/CellImage.vue.d.ts

@@ -0,0 +1,5 @@
+import type { VunoTableCellProps } from '#vuno/types/table';
+type __VLS_Props = VunoTableCellProps<'image'>;
+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/Cell/CellNumber.d.vue.ts

@@ -0,0 +1,5 @@
+import type { VunoTableCellProps } from '#vuno/types/table';
+type __VLS_Props = VunoTableCellProps<'number'>;
+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/Cell/CellNumber.vue

@@ -0,0 +1,15 @@
+<script setup>
+import { useLocale } from "@nuxt/ui/composables";
+import { formatNumber } from "#vuno/utils/format";
+const props = defineProps({
+  column: { type: Object, required: true },
+  row: { type: Object, required: true },
+  value: { type: null, required: true }
+});
+const locale = useLocale();
+</script>
+
+<template>
+    <!-- `tabular-nums` alinea las cifras en columna; sin ello los dígitos bailan. -->
+    <span class="tabular-nums">{{ formatNumber(props.value, locale.code.value, props.column.decimals) }}</span>
+</template>

package/dist/runtime/app/components/Cell/CellNumber.vue.d.ts

@@ -0,0 +1,5 @@
+import type { VunoTableCellProps } from '#vuno/types/table';
+type __VLS_Props = VunoTableCellProps<'number'>;
+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/Cell/CellText.d.vue.ts

@@ -0,0 +1,5 @@
+import type { VunoTableCellProps } from '#vuno/types/table';
+type __VLS_Props = VunoTableCellProps<'text'>;
+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/Cell/CellText.vue

@@ -0,0 +1,13 @@
+<script setup>
+import { computed } from "vue";
+const props = defineProps({
+  column: { type: Object, required: true },
+  row: { type: Object, required: true },
+  value: { type: null, required: true }
+});
+const text = computed(() => props.value === null || props.value === void 0 ? "" : String(props.value));
+</script>
+
+<template>
+    <span :class="props.column.truncate ? 'block max-w-[32ch] truncate' : void 0">{{ text }}</span>
+</template>

package/dist/runtime/app/components/Cell/CellText.vue.d.ts

@@ -0,0 +1,5 @@
+import type { VunoTableCellProps } from '#vuno/types/table';
+type __VLS_Props = VunoTableCellProps<'text'>;
+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;