@tinya-code/gas-admin-ui 0.1.0-alpha.4 → 0.1.0-alpha.5

package/README.md

@@ -2,19 +2,54 @@
 
 Motor de render del ecosistema `@tinya-code`: el front que **sólo declara** su
 dominio (`schemas/*.schema.ts`) y consume el motor compilado — mismo contrato
-que `@tinya-code/gas-admin` en el back, pero para Angular.
+que `@tinya-code/gas-admin` en el back, pero para Angular. El paquete dibuja
+vistas, campos, acciones, shell y rutas; vos no tocás componentes a mano.
+
+## Requisitos
+
+| Requisito | Versión / detalle |
+| --- | --- |
+| Angular | `22.2` (standalone, signals) |
+| Peers de Angular | `@angular/{cdk,common,core,forms,platform-browser,router} ^22.2` |
+| Iconos / charts | `@lucide/angular ^1.51`, `chart.js ^4.5` |
+| CSS | Tailwind v4 — con el `@source` del motor ([paso 2](#2-declará-el-source-de-tailwind)) |
+| Back | [`@tinya-code/gas-admin`](https://www.npmjs.com/package/@tinya-code/gas-admin) — su CLI genera y valida los schemas del front |
+
+## Camino rápido desde cero
+
+### 1. Instalá el paquete
 
 ```bash
 npm i @tinya-code/gas-admin-ui
 ```
 
-**Peers:** `@angular/{cdk,common,core,forms,platform-browser,router} ^22.2`,
-`@lucide/angular ^1.51`, `chart.js ^4.5`.
+Un proyecto Angular 22.2 ya trae los `@angular/*`; verificá que estén los
+demás peers (`@lucide/angular`, `chart.js` y los `@angular/*` que falten).
+
+### 2. Declará el `@source` de Tailwind
+
+En `src/styles.css`:
+
+```css
+@source '../node_modules/@tinya-code/gas-admin-ui/fesm2022';
+```
+
+Sin esto la app compila pero la UI del motor sale sin clases (visual roto,
+tests en verde).
+
+### 3. Generá los schemas desde el back
 
-## Uso mínimo
+Con el CLI del back instalado en el proyecto (`npm i -D @tinya-code/gas-admin`)
+y el dominio declarado en `api/schema/resources/`:
+
+```bash
+npx gas-admin scaffold
+```
 
-**1. Wiring** — `app.config.ts` entrega el dominio al motor (catálogo +
-HTTP con interceptor del envelope + loaders de config/sesión):
+Escribe 9 ficheros en `src/app/schemas/` ([estructura](#estructura-generada-en-srcappschemas)).
+Si la carpeta ya tiene `*.ts` falla con exit 1; `--force` regenera.
+
+### 4. Cableá el motor — `app.config.ts`
 
 ```ts
 import { API_URL, provideGasAdmin } from '@tinya-code/gas-admin-ui';
@@ -28,7 +63,11 @@ export const appConfig: ApplicationConfig = {
 };
 ```
 
-**2. Rutas** — `app.routes.ts`:
+El motor absorbe HTTP (interceptor del envelope), los loaders de
+config/sesión y el catálogo de schemas; la app conserva router, environment
+y sus schemas de dominio.
+
+### 5. Rutas — `app.routes.ts`
 
 ```ts
 import { authGuard, shellRoutes } from '@tinya-code/gas-admin-ui';
@@ -41,84 +80,128 @@ export const routes: Routes = [
 ];
 ```
 
-**3. Dominio** — la carpeta `src/app/schemas/` se genera desde el back. Con
-el CLI del back instalado (`npm i -D @tinya-code/gas-admin`):
+`firstResource` lo definís en el archivo:
+`const firstResource = schemas[0].id;` (primer recurso del catálogo). El login
+queda fuera del shell a propósito: si viviera dentro, `authGuard` lo
+bloquearía a él mismo.
+
+### 6. Revisá los labels de cada `*.schema.ts`
+
+Los `label` salen de las keys: son copy de demo. Reemplazalos por los del
+dominio y sumá las vistas/filtros que quieras (el recorrido de capacidades
+está en la cabecera de `registry.ts`). También podés escribir toda la
+estructura a mano si preferís no usar el scaffold.
+
+### 7. Levantá la app
 
 ```bash
-npx gas-admin scaffold
+npm start
 ```
 
-Por cada recurso de `api/schema/resources/` escribe su `*.schema.ts`
-(campos, validators, enums y endpoint derivados de la proyección back), más
-`registry.ts` (el array ordenado que alimenta menú y rutas),
-`auth.schema.ts` (las claves exactas del `input` de `/auth/login`) y
-`seed-catalog.ts` (siembra el catálogo para los specs). Los `label` salen
-de las keys: reemplazá los placeholders por los del dominio y sumá las
-vistas/filtros que quieras (el recorrido de capacidades está en la
-cabecera de `registry.ts`). Estructura equivalente a mano si preferís
-escribirlo. La validación de que todo siga coincidiendo con el back la hace
-`gas-admin validate --with-front` (`contract-check` de
-`@tinya-code/gas-admin`).
-
-## Requisitos del consumidor
+Verificación: el shell arranca en `/login` y, con sesión, muestra el menú y
+las vistas derivadas de tus schemas.
 
-### Tailwind v4 — `@source` obligatorio
+### 8. Validá el contrato back ↔ front
 
-Tailwind genera utilities escaneando **tus** fuentes; el motor vive en
-`node_modules` y no lo escanea solo. Agregar en `styles.css`:
+Sólo después de tener el back con el doc al día (`npx gas-admin doc`):
 
-```css
-@source '../node_modules/@tinya-code/gas-admin-ui/fesm2022';
+```bash
+npx gas-admin validate --with-front
 ```
 
-Sin esto, la app compila pero la UI pierde las clases del motor (visual roto,
-tests en verde).
+Corre el `contract-check` de `@tinya-code/gas-admin`: exit 0 = los schemas del
+front siguen coincidiendo con la proyección del back.
+
+## Requisitos especiales del consumidor
+
+### Tailwind v4 — `@source` obligatorio
+
+Tailwind genera las utilities escaneando **tus** fuentes; el motor vive en
+`node_modules` y Tailwind no lo escanea solo. El `@source` del paso 2 es
+obligatorio: sin él la app compila y los tests quedan en verde, pero la UI
+del motor se renderiza sin estilos.
 
 ### Tests del consumidor — desde `node_modules` (sin alias)
 
-Los specs del consumidor resuelven `@tinya-code/gas-admin-ui` desde
-`node_modules` (la versión publicada en `dependencies`), sin alias de
-`tsconfig.spec.json` ni clone del repo como directorio hermano en CI: la
-app y los tests usan la MISMA copia compilada ⇒ Angular se instancia una
-sola vez (verificado en admin-schema: 116/116 sin alias). Para probar un
-cambio del motor en el consumidor: publicar un alpha y bumpear la
-dependencia.
+Los specs del consumidor deben resolver `@tinya-code/gas-admin-ui` desde
+`node_modules` (la versión publicada en `dependencies`), **sin** alias de
+`tsconfig.spec.json` ni clone del repo como directorio hermano en CI: la app
+y los tests usan la MISMA copia compilada ⇒ Angular se instancia una sola
+vez (verificado en `admin-schema`: 116/116 sin alias). Para probar un cambio
+del motor, publicá un alpha y bumpeá la dependencia.
+
+Si alguna combinación de versiones llegara a reproducir `NG0203`/`NG01908`
+(doble instancia de Angular: vitest prebundlea `@angular/*` pero la lib corre
+en ESM nativo), el workaround es compilar la lib desde source en el grafo de
+tests (`paths` en `tsconfig.spec.json` apuntando al source del paquete)
+junto con un clone del repo como directorio hermano en CI.
+
+## Estructura generada en `src/app/schemas/`
+
+`npx gas-admin scaffold` aplaná la plantilla de las vitrinas (catálogo,
+agenda, panel) en una carpeta plana:
+
+```text
+src/app/schemas/
+├── auth.schema.ts        # claves exactas del input de /auth/login
+├── registry.ts           # array ordenado que alimenta menú y rutas
+├── seed-catalog.ts       # siembra el catálogo para los specs
+├── productos.schema.ts   # vitrina catálogo
+├── categorias.schema.ts  # vitrina catálogo
+├── pedidos.schema.ts     # vitrina agenda
+├── dashboard.schema.ts   # vitrina panel
+├── usuarios.schema.ts    # vitrina panel
+└── sitio.schema.ts       # vitrina panel
+```
 
-Si una combinación de versiones llegara a reproducir `NG0203`/`NG01908`
-(doble instancia de Angular: vitest prebundlea `@angular/*` pero la lib
-corre en ESM nativo), el workaround es compilar la lib desde source en el
-grafo de tests (`paths` en `tsconfig.spec.json` apuntando al source del
-paquete) junto con un clone del repo como directorio hermano en CI.
+Por cada recurso, el `*.schema.ts` trae campos, validators, enums y endpoint
+derivados de la proyección back.
 
 ## API pública
 
 Sólo lo exportado por `public-api.ts` es contrato; el resto es privado y
-puede cambiar entre alphas. Superficie v1:
+puede cambiar entre alphas.
 
 | Grupo | Exportaciones |
 | --- | --- |
-| Wiring | `provideGasAdmin`, `GAS_SCHEMAS`, `setSchemaCatalog`, `getSchema`, `allSchemas`, `getAuth`, `API_URL` |
-| Rutas/guard | `authGuard`, `shellRoutes`, `resourceRoutes` |
-| Componentes | `Login`, `Sidebar`, `Dashboard`, `ListView`, `FormView`, `ResourcePage`, `ComposerHost`, `FieldHost`, `ConfirmDialog`, `Toast` |
-| Servicios | `ApiService`, `AuthService`, `NotificationService`, `DataSourceService`, `UploadService`, `ErrorMapperService`, `apiErrorInterceptor` |
-| Modelos | `ResourceSchema`, `AuthSchema`, `ResourceAction`, tipos de `views`/`columns`/`fields` |
-| Registros | `fieldDescriptors`, `columnFormatDescriptors`, `layoutDescriptors`, `viewDescriptors`, `registerRenderDescriptor`, `renderKinds`, `ValidatorName` |
+| Wiring y catálogo | `provideGasAdmin`, `GAS_SCHEMAS`, `setSchemaCatalog`, `getSchema`, `allSchemas`, `getAuth`, tipo `GasAdminConfig` |
+| Token | `API_URL` |
+| Rutas y guard | `authGuard`, `shellRoutes`, `resourceRoutes` |
+| Páginas | `Login`, `Dashboard`, `ListView`, `FormView`, `ResourcePage` |
+| Componentes | `Sidebar`, `ComposerHost`, `FieldHost`, `ConfirmDialog`, `Toast` |
+| Servicios | `ApiService`, `AuthService` (+ `SESSION_TOKEN_KEY`, `SESSION_USER_KEY`), `NotificationService`, `DataSourceService`, `UploadService`, `ErrorMapperService`, `apiErrorInterceptor` |
 | Forms | `buildFormSchema`, `seedModel`, `buildPayload` |
+| Modelos de schema | `ResourceSchema`, `AuthSchema`, `ResourceAction`, `ApiError` y todo el vocabulario de fields/widgets/views/layouts (`FieldSchema`, `FieldType`, `ListColumn`, `WidgetSchema`, `ResourceLayout`, `ViewDescriptor`, vistas tabs/calendar/kanban…) |
+| Registros de render | `fieldDescriptors`, `SUPPORTED_FIELD_TYPE_LIST`, `columnFormatDescriptors`, `COLUMN_FORMAT_TYPES`, `viewDescriptors`, `layoutDescriptors`, `renderKinds` |
+| Render custom | `registerRenderDescriptor`, `unregisterRenderDescriptor`, `provideRenderDescriptors`, `getRenderDescriptor`, `isSupported`, `isRenderSupported`, tipos `RenderKind`, `ComponentRenderKind` |
+| Composición | `validateComposition`, `MAX_DEPTH`, `SchemaCompositionError` |
+| Acciones custom | `registerAction`, `getAction`, `actionsFor`, `actionType`, `actionTypes`, tipos `ActionDescriptor`, `ActionSurface`, `ActionContext`, `ActionResult` |
+| Validadores | tipo `ValidatorName` (vocabulario del contract-check back ↔ front) |
+| Utilidades | `interpolateTemplate` (interpolación de templates en schemas) |
+
+## Ver también
+
+- **Back del ecosistema** — `init`, declaración de dominio, `doc`, `validate`:
+  guía de `@tinya-code/gas-admin` en
+  [`Tinya-Code/gas-admin`](https://github.com/Tinya-Code/gas-admin)
+  (`docs/guia-de-uso.md`).
+- **Consumidor de referencia** — `admin-schema`: declara el dominio e integra
+  este paquete (116 tests sin alias, specs de integración).
 
 ## Desarrollo (este repo)
 
 ```bash
 ng build gas-admin-ui     # ng-packagr → dist/gas-admin-ui (fesm2022 + types)
-ng test gas-admin-ui      # vitest: 489 tests del motor (fixtures congelados)
+ng test gas-admin-ui      # vitest: tests del motor (fixtures congelados)
 ```
 
-Publicación (tag `alpha` obligatorio en prereleases):
+Publicación (npm **exige** `--tag` explícito en prereleases):
 
 ```bash
 npm publish ./dist/gas-admin-ui --tag alpha
 ```
 
-Los specs que renderizan los schemas **reales** de un consumidor no viven
-acá (la lib no puede importar al consumidor): viven en el repo del
-consumidor importando desde este paquete — ver los 16 specs de
-integración de `admin-schema`.
+- `dist/` es gitignored: el build es siempre local y no se commitea.
+- Los specs que renderizan los schemas **reales** de un consumidor no viven
+  acá (la lib no puede importar al consumidor): viven en el repo del
+  consumidor importando desde este paquete.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tinya-code/gas-admin-ui",
-  "version": "0.1.0-alpha.4",
+  "version": "0.1.0-alpha.5",
   "description": "Motor de render Angular para admin CRUD: declará ResourceSchema y el motor dibuja vistas, campos y widgets.",
   "repository": {
     "type": "git",