nuxt-openapi-hyperfetch 0.3.8-beta → 1.0.0

package/docs/headless-composables-ui.md

@@ -1,569 +0,0 @@
-# Headless UI Composables — Feature Spec & Architecture
-
-> **Status**: Planned — Capa 2 del sistema de generación de componentes Vue  
-> **Dependencia**: Requiere que los composables `useAsyncData` estén generados previamente  
-> **Objetivo**: Exponer lógica CRUD de forma headless y framework-agnostic para que cualquier desarrollador pueda construir sus propios componentes UI sobre ella
-
----
-
-## Tabla de Contenidos
-
-- [Qué es esta feature](#qué-es-esta-feature)
-- [Motivación](#motivación)
-- [Arquitectura de 3 Capas](#arquitectura-de-3-capas)
-- [Diseño del Connector Unificado](#diseño-del-connector-unificado)
-- [Contratos de los Sub-Connectors](#contratos-de-los-sub-connectors)
-- [Validación con Zod](#validación-con-zod)
-- [Detección automática de campo tipo en formularios](#detección-automática-de-campo-tipo-en-formularios)
-- [Integración con paginación](#integración-con-paginación)
-- [Estructura de archivos a crear](#estructura-de-archivos-a-crear)
-- [Plan de implementación](#plan-de-implementación)
-- [Ejemplos de uso por el developer](#ejemplos-de-uso-por-el-developer)
-
----
-
-## Qué es esta feature
-
-El **Connector Generator** genera, por cada recurso detectado en el OpenAPI spec, un composable Vue 3 headless llamado `use{Resource}Connector.ts`.
-
-Este composable:
-- Encapsula toda la lógica de negocio (fetch, submit, estado, paginación, errores)
-- No tiene ningún template HTML — es 100% lógica reutilizable
-- Expone una API clara y fuertemente tipada
-- Es el puente entre los composables generados (`useAsyncDataGetPets`) y cualquier componente UI
-
-El developer puede:
-1. Usar el connector directamente para construir sus propios componentes
-2. Dejar que el generador de componentes (Capa 3) genere componentes `.vue` de NuxtUI/PrimeVue sobre él
-3. Usar solo una parte del connector (ej: solo `table`, ignorando los formularios)
-
----
-
-## Motivación
-
-Sin esta capa, cada adaptador UI (NuxtUI, PrimeVue, Vuetify…) tendría que reimplementar:
-- La lógica de fetch y re-fetch
-- El estado de loading, errores, datos
-- La gestión de paginación
-- La apertura de modales y estado de formularios
-- El pre-relleno de formulario de update con datos del get
-
-Con el Connector, esa lógica se escribe **una sola vez**. Los adaptadores solo añaden el template.
-
----
-
-## Arquitectura de 3 Capas
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│  CAPA 1 — Schema Analyzer  (src/generators/components/)     │
-│  Lee OpenAPI YAML/JSON directo                              │
-│  Detecta intents por HTTP method + path pattern + schema    │
-│  Agrupa en recursos por tag (prioridad) o path prefix       │
-│  Produce un ResourceMap tipado                              │
-└─────────────────────────────────────────────────────────────┘
-                           ↓ alimenta
-┌─────────────────────────────────────────────────────────────┐
-│  CAPA 2 — Connector Generator  (esta feature)               │
-│  Genera use{Resource}Connector.ts por recurso               │
-│  Composables headless — lógica sin template                 │
-│  Usa los composables useAsyncData ya generados              │
-│  Es consumido por Capa 3 o directamente por el developer    │
-└─────────────────────────────────────────────────────────────┘
-                           ↓ consume
-┌─────────────────────────────────────────────────────────────┐
-│  CAPA 3 — Component Generator  (ver generated-components.md)│
-│  Genera .vue por recurso (NuxtUI, PrimeVue, etc.)           │
-│  Importa use{Resource}Connector.ts                          │
-│  Solo contiene template + binding — cero lógica propia      │
-└─────────────────────────────────────────────────────────────┘
-```
-
----
-
-## Diseño del Connector Unificado
-
-Cada recurso produce **un único composable** con secciones independientes:
-
-```ts
-// composables/connectors/usePetsConnector.ts
-// AUTO-GENERATED — DO NOT EDIT
-// Generated by nxh — https://github.com/dmartindiaz/nuxt-openapi-hyperfetch
-
-import { useAsyncDataGetPets } from '../use-async-data/use-async-data-get-pets'
-import { useAsyncDataGetPet } from '../use-async-data/use-async-data-get-pet'
-import { useAsyncDataCreatePet } from '../use-async-data/use-async-data-create-pet'
-import { useAsyncDataUpdatePet } from '../use-async-data/use-async-data-update-pet'
-import { useAsyncDataDeletePet } from '../use-async-data/use-async-data-delete-pet'
-import { useListConnector } from '#nxh/runtime/useListConnector'
-import { useDetailConnector } from '#nxh/runtime/useDetailConnector'
-import { useFormConnector } from '#nxh/runtime/useFormConnector'
-import { useDeleteConnector } from '#nxh/runtime/useDeleteConnector'
-
-export function usePetsConnector() {
-  const table = useListConnector(useAsyncDataGetPets, {
-    paginated: true,
-  })
-
-  const detail = useDetailConnector(useAsyncDataGetPet)
-
-  const createForm = useFormConnector(useAsyncDataCreatePet, {
-    schema: PetCreateSchema,   // inferido del request body del POST
-  })
-
-  const updateForm = useFormConnector(useAsyncDataUpdatePet, {
-    schema: PetUpdateSchema,   // inferido del request body del PUT
-    loadWith: detail,         // pre-rellena con GET /pets/{id} si existe
-  })
-
-  const deleteAction = useDeleteConnector(useAsyncDataDeletePet)
-
-  return {
-    table,
-    detail,
-    createForm,
-    updateForm,
-    deleteAction,
-  }
-}
-```
-
-El connector **solo incluye las secciones que existen en el spec**. Si no hay `DELETE`, no se genera `deleteAction`. Si no hay `PUT`, no se genera `updateForm`.
-
----
-
-## Contratos de los Sub-Connectors
-
-### `useListConnector(composable, options)`
-
-Wrappea un composable GET que devuelve array:
-
-```ts
-interface ListConnectorReturn<T> {
-  // Estado
-  rows: ComputedRef<T[]>
-  columns: ComputedRef<ColumnDef[]>    // generado de response schema
-  loading: ComputedRef<boolean>
-  error: ComputedRef<any>
-
-  // Paginación (si paginated: true)
-  pagination: ComputedRef<PaginationState>
-  goToPage: (page: number) => void
-  nextPage: () => void
-  prevPage: () => void
-
-  // Acciones
-  refresh: () => void
-  selected: Ref<T[]>                  // filas seleccionadas
-  onRowSelect: (row: T) => void
-
-  // Para apertura de modales (coordinación con PetsCrud.vue)
-  openCreate: () => void
-  openUpdate: (row: T) => void
-  openDelete: (row: T) => void
-}
-
-interface ColumnDef {
-  key: string
-  label: string                       // viene de index.ts del developer (o key capitalizado)
-  sortable?: boolean
-  type: 'text' | 'number' | 'date' | 'boolean' | 'badge'
-}
-```
-
-### `useDetailConnector(composable)`
-
-Wrappea un composable GET que devuelve un objeto:
-
-```ts
-interface DetailConnectorReturn<T> {
-  item: Ref<T | null>
-  loading: ComputedRef<boolean>
-  error: ComputedRef<any>
-  load: (id: string | number) => Promise<void>
-  fields: ComputedRef<FieldDef[]>     // para vistas de detalle
-}
-```
-
-### `useFormConnector(composable, options)`
-
-```ts
-import type { ZodSchema } from 'zod'
-
-interface FormConnectorOptions<T> {
-  schema: ZodSchema                   // Zod schema generado del request body OpenAPI
-  loadWith?: DetailConnectorReturn<T> // pre-rellena desde detail si se pasa
-}
-
-interface FormConnectorReturn<T> {
-  // Estado del formulario
-  model: Ref<Partial<T>>
-  fields: ComputedRef<FormFieldDef[]>
-  loading: ComputedRef<boolean>
-  errors: ComputedRef<Record<string, string>>  // { name: 'Name is required' }
-  isValid: ComputedRef<boolean>
-
-  // Acciones
-  submit: () => Promise<void>          // valida con Zod antes de llamar al composable
-  reset: () => void
-  setValues: (data: Partial<T>) => void // llamado por loadWith automáticamente
-
-  // Callbacks
-  onSuccess: Ref<(result: T) => void>
-  onError: Ref<(error: any) => void>
-}
-
-interface FormFieldDef {
-  key: string
-  label: string
-  type: 'input' | 'textarea' | 'select' | 'checkbox' | 'datepicker' | 'number'
-  required: boolean
-  options?: { label: string; value: any }[]   // para type: 'select' (enum en OpenAPI)
-  placeholder?: string
-  hidden?: boolean        // readOnly: true del schema → hidden por defecto
-}
-```
-
-**Inferencia automática de tipo de campo** (del schema OpenAPI):
-
-| OpenAPI schema          | `FormFieldDef.type` generado |
-|-------------------------|------------------------------|
-| `type: string`          | `input`                      |
-| `type: string, format: date` | `datepicker`           |
-| `type: string, format: date-time` | `datepicker`      |
-| `type: string, maxLength > 200` | `textarea`          |
-| `type: integer / number` | `number`                    |
-| `type: boolean`         | `checkbox`                   |
-| `enum: [...]`           | `select`                     |
-| `readOnly: true`        | campo omitido del form (configurable) |
-
-El developer puede sobreescribir cualquier campo en `components/nxh/pets/index.ts`:
-
-```ts
-export const config = {
-  fields: {
-    bio: { type: 'textarea' },        // override de tipo de input
-    status: { type: 'select', options: [
-      { label: 'Active', value: 'active' },
-      { label: 'Inactive', value: 'inactive' },
-    ]},
-    id: { hidden: true },             // forzar oculto aunque no sea readOnly
-  }
-}
-```
-
-### `useDeleteConnector(composable)`
-
-```ts
-interface DeleteConnectorReturn<T> {
-  loading: ComputedRef<boolean>
-  error: ComputedRef<any>
-  target: Ref<T | null>                 // el item que se va a borrar
-  setTarget: (item: T) => void
-  confirm: () => Promise<void>
-  cancel: () => void
-  onSuccess: Ref<(item: T) => void>
-  onError: Ref<(error: any) => void>
-}
-```
-
----
-
-## Validación con Zod
-
-La validación ocurre en **tiempo de ejecución dentro de `useFormConnector`**, usando schemas Zod que fueron generados en **code-gen time** por el Schema Analyzer a partir del request body del OpenAPI spec.
-
-### Cómo funciona internamente `useFormConnector`
-
-```ts
-// src/generators/shared/runtime/useFormConnector.ts (runtime — se copia al proyecto)
-import { ref, computed } from 'vue'
-import type { ZodSchema } from 'zod'
-
-export function useFormConnector<T>(composable: Function, options: FormConnectorOptions<T>) {
-  const model = ref<Partial<T>>({})
-  const errors = ref<Record<string, string>>({})
-  const loading = ref(false)
-
-  async function submit() {
-    // 1. Validar con Zod antes de cualquier llamada HTTP
-    const result = options.schema.safeParse(model.value)
-
-    if (!result.success) {
-      // Zod devuelve errores por campo: { name: ['Required'], status: ['Invalid value'] }
-      const fieldErrors = result.error.flatten().fieldErrors
-      // Convertir array de mensajes a string único por campo
-      errors.value = Object.fromEntries(
-        Object.entries(fieldErrors).map(([key, msgs]) => [key, msgs?.[0] ?? 'Invalid'])
-      )
-      return  // No se hace la llamada HTTP
-    }
-
-    errors.value = {}
-    loading.value = true
-    try {
-      const response = await composable(result.data)
-      options.onSuccess?.(response)
-    } catch (err) {
-      options.onError?.(err)
-    } finally {
-      loading.value = false
-    }
-  }
-
-  return { model, errors, loading, submit, /* ... */ }
-}
-```
-
-### Cómo el Schema Analyzer genera el schema Zod
-
-El `schema-field-mapper.ts` convierte cada propiedad del request body OpenAPI a su equivalente Zod:
-
-| OpenAPI                            | Zod generado                                 |
-|------------------------------------|----------------------------------------------|
-| `type: string` + required          | `z.string().min(1)`                          |
-| `type: string` + opcional          | `z.string().optional()`                      |
-| `type: string, minLength: 3`       | `z.string().min(3)`                          |
-| `type: string, maxLength: 100`     | `z.string().max(100)`                        |
-| `type: string, format: email`      | `z.string().email()`                         |
-| `type: string, format: uri`        | `z.string().url()`                           |
-| `type: integer / number` + req.    | `z.number().int()` / `z.number()`            |
-| `type: boolean`                    | `z.boolean()`                                |
-| `enum: ['a','b']` + required       | `z.enum(['a', 'b'])`                         |
-| `enum: ['a','b']` + opcional       | `z.enum(['a', 'b']).optional()`              |
-| `type: array, items: { type: string }` | `z.array(z.string())`                   |
-| `type: array, minItems: 1`         | `z.array(z.string()).min(1)`                 |
-| `readOnly: true`                   | campo excluido del schema (no se valida)     |
-
-### Mensajes de error — 3 niveles
-
-**Nivel 1 — Mensajes por defecto de Zod** (en inglés, zero config):
-```
-{ name: 'String must contain at least 1 character(s)' }
-```
-
-**Nivel 2 — `errorMap` global** (traducciones genéricas para todo el proyecto):
-```ts
-// plugins/zod-i18n.ts  (el developer crea esto en su proyecto Nuxt)
-import { z } from 'zod'
-
-z.setErrorMap((issue, ctx) => {
-  switch (issue.code) {
-    case 'too_small':
-      if (issue.type === 'string' && issue.minimum === 1)
-        return { message: 'Este campo es obligatorio' }
-      return { message: `Mínimo ${issue.minimum} caracteres` }
-    case 'invalid_enum_value':
-      return { message: `Valor no válido` }
-    case 'invalid_type':
-      if (issue.received === 'undefined')
-        return { message: 'Este campo es obligatorio' }
-    default:
-      return { message: ctx.defaultError }
-  }
-})
-```
-
-**Nivel 3 — Mensajes por campo** (en `components/nxh/pets/index.ts`, máximo control):
-```ts
-export const config = {
-  fields: {
-    name: {
-      label: 'Nombre',
-      errors: {
-        required: 'El nombre es obligatorio',
-        min:      'El nombre debe tener al menos 1 carácter',
-        max:      'El nombre no puede superar 100 caracteres',
-      }
-    },
-    status: {
-      label: 'Estado',
-      errors: {
-        invalid_enum_value: 'Selecciona un estado válido',
-      }
-    }
-  }
-}
-```
-
-`useFormConnector` merge los mensajes del config sobre los de Zod: si el campo tiene `errors.required`, ese mensaje reemplaza al de Zod para ese campo. Los adaptadores UI (NuxtUI, PrimeVue) solo leen `errors.value[campo]` — framework-agnostic.
-
----
-
-## Integración con paginación
-
-Si el endpoint del list tiene respuesta paginada (detectada por el Schema Analyzer al ver campos como `total`, `totalPages` en la respuesta, o configuración en `nxh.config`), `useListConnector` activa automáticamente `paginated: true` en el composable `useAsyncData` correspondiente, reutilizando el sistema de paginación ya implementado en `src/generators/shared/runtime/pagination.ts`.
-
----
-
-## Estructura de archivos a crear
-
-### Archivos nuevos en `src/` (en el generador)
-
-```
-src/
-  generators/
-    components/                          ← NUEVO directorio
-      schema-analyzer/
-        index.ts                         ← entry point del analyzer
-        types.ts                         ← ResourceMap, Intent, FieldDef, etc.
-        intent-detector.ts               ← detecta intent por HTTP+path+schema
-        resource-grouper.ts              ← agrupa endpoints en recursos por tag/path
-        schema-field-mapper.ts           ← OpenAPI schema → FormFieldDef[]
-        openapi-reader.ts                ← lee y parsea el YAML/JSON del spec
-      connector-generator/
-        index.ts                         ← entry point del connector generator
-        types.ts                         ← ConnectorInfo, SubConnectorDef, etc.
-        templates.ts                     ← plantillas de texto para los .ts generados
-        generator.ts                     ← orquesta la generación de connectors
-      shared/
-        naming.ts                        ← convenciones de nombres (usePetsConnector, etc.)
-        paths.ts                         ← resolución de paths de output
-```
-
-### Archivos runtime nuevos en `src/generators/shared/runtime/`
-
-```
-src/generators/shared/runtime/
-  useListConnector.ts                    ← NUEVO — conector genérico para listas
-  useDetailConnector.ts                  ← NUEVO — conector genérico para detalle
-  useFormConnector.ts                    ← NUEVO — conector genérico para formularios (usa Zod)
-  useDeleteConnector.ts                  ← NUEVO — conector genérico para delete
-  zod-error-merger.ts                    ← NUEVO — merge errores Zod con config.fields.errors
-```
-
-Estos archivos son **runtime** — se copian al proyecto del usuario igual que `apiHelpers.ts` y `pagination.ts`.
-
-> **Dependencia de runtime:** `zod` debe estar instalado en el proyecto del usuario (`npm i zod`). Se añade como `peerDependency` en el package.json del generador.
-
-### Archivos que se generan en el proyecto del usuario
-
-```
-composables/
-  connectors/
-    usePetsConnector.ts                 ← AUTO-GENERATED, regenerable
-    useCategoryConnector.ts
-    useOrderConnector.ts
-    ...
-```
-
----
-
-## Plan de implementación
-
-### Fase 1 — Schema Analyzer
-
-**Archivos:** `src/generators/components/schema-analyzer/`
-
-1. `openapi-reader.ts` — Leer YAML/JSON con `js-yaml` o `@apidevtools/swagger-parser`. Producir el spec como objeto tipado
-2. `types.ts` — Definir `ResourceMap`, `ResourceInfo`, `EndpointInfo`, `Intent`, `FieldDef`, `ColumnDef`
-3. `intent-detector.ts` — Lógica de detección:
-   - Señal 1: HTTP method (`GET` → list/detail, `POST` → create, `PUT/PATCH` → update, `DELETE` → delete)
-   - Señal 2: Path pattern (`/pets` sin path params → list candidate, `/pets/{id}` → detail/update/delete)
-   - Señal 3: Response schema (array → `list`, object → `detail`)
-   - Override: `nxh.config.js` `components['GET /pets/search'] = { intent: 'list' }`
-4. `resource-grouper.ts` — Agrupa endpoints con el mismo tag (prioridad) o path prefix (fallback) en un `ResourceInfo`
-5. `schema-field-mapper.ts` — Convierte OpenAPI property schema → `FormFieldDef` Y genera el **string de código Zod** correspondiente (ver tabla de mapeo en la sección [Validación con Zod](#validación-con-zod))
-
-### Fase 2 — Runtime Connectors
-
-**Archivos:** `src/generators/shared/runtime/`
-
-1. `useListConnector.ts` — Recibe composable `useAsyncData` + opciones, devuelve `ListConnectorReturn`
-2. `useDetailConnector.ts` — Recibe composable `useAsyncData`, devuelve `DetailConnectorReturn`
-3. `useFormConnector.ts` — Recibe composable `useAsyncData` mutación + Zod schema + `loadWith` opcional:
-   - Llama `schema.safeParse(model.value)` en `submit()` antes de la llamada HTTP
-   - Convierte `error.flatten().fieldErrors` a `Record<string, string>`
-   - Merge con mensajes de `config.fields[key].errors` cuando existen
-   - Expone `errors: Ref<Record<string, string>>` — framework-agnostic
-4. `useDeleteConnector.ts` — Recibe composable `useAsyncData` delete, devuelve `DeleteConnectorReturn`
-5. `zod-error-merger.ts` — Helper que merge errores Zod con overrides del `config.fields.errors`
-
-### Fase 3 — Connector Generator
-
-**Archivos:** `src/generators/components/connector-generator/`
-
-1. `types.ts` — `ConnectorInfo` (todo lo necesario para generar el `.ts`)
-2. `templates.ts` — Funciones que producen el string del archivo `use{Resource}Connector.ts`
-3. `generator.ts` — Toma el `ResourceMap` de Fase 1, genera un archivo por recurso
-4. Integración en `src/index.ts` con nuevo comando/opción CLI
-
-### Fase 4 — Integración en CLI
-
-Nuevo flag en `nxh generate`:
-```
---components <type>   Generate UI components: connectors, nuxtui, primevue
-```
-
-O nuevo comando separado:
-```
-nxh components --input swagger.yaml --output ./components/nxh --ui nuxtui
-```
-
----
-
-## Ejemplos de uso por el developer
-
-### Uso básico — tabla simple
-
-```vue
-<!-- pages/pets.vue -->
-<script setup>
-import { usePetsConnector } from '~/composables/connectors/usePetsConnector'
-
-const { table } = usePetsConnector()
-</script>
-
-<template>
-  <!-- Con NuxtUI -->
-  <UTable :rows="table.rows.value" :columns="table.columns.value" :loading="table.loading.value" />
-</template>
-```
-
-### Uso avanzado — CRUD completo custom
-
-```vue
-<!-- pages/pets-admin.vue -->
-<script setup>
-import { usePetsConnector } from '~/composables/connectors/usePetsConnector'
-
-const { table, createForm, updateForm, deleteAction } = usePetsConnector()
-
-// Hook personalizado
-createForm.onSuccess.value = () => {
-  table.refresh()
-  useToast().add({ title: 'Pet created!' })
-}
-</script>
-
-<template>
-  <!-- El developer monta su propio HTML con la lógica del connector -->
-  <MyCustomTable v-bind="table" @edit="updateForm.setValues" @delete="deleteAction.setTarget" />
-  <MyCustomForm v-bind="createForm" />
-</template>
-```
-
-### Traducción de columnas mediante index.ts
-
-```ts
-// components/nxh/pets/index.ts  (generado una vez, editado por el developer)
-export const config = {
-  columns: {
-    name:      { label: 'Nombre' },
-    status:    { label: 'Estado' },
-    createdAt: { label: 'Fecha de creación' },
-  },
-  fields: {
-    status: {
-      type: 'select',
-      options: [
-        { label: 'Disponible', value: 'available' },
-        { label: 'Vendido',    value: 'sold' },
-      ]
-    }
-  },
-  showReadonlyFields: false,
-}
-```
-
-El generated `usePetsConnector.ts` importa este config y lo aplica sobre los `ColumnDef` y `FormFieldDef` antes de exponerlos.