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

package/README.md

@@ -1,61 +1,59 @@
 # @tinya-code/gas-admin-ui
 
-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. El paquete dibuja
-vistas, campos, acciones, shell y rutas; vos no tocás componentes a mano.
+Angular rendering engine for the `@tinya-code` ecosystem. You declare your domain in typed schema files — the engine renders views, forms, lists, actions, shell, and routes. You never write components by hand.
 
-## Requisitos
+## Requirements
 
-| Requisito | Versión / detalle |
+| Requirement | Version / detail |
 | --- | --- |
 | 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 |
+| Angular peers | `@angular/{cdk,common,core,forms,platform-browser,router} ^22.2` |
+| Icons / charts | `@lucide/angular ^1.51`, `chart.js ^4.5` |
+| CSS | Tailwind v4 — with the engine's `@source` ([step 2](#2-declare-the-tailwind-source)) |
+| Backend | [`@tinya-code/gas-admin`](https://www.npmjs.com/package/@tinya-code/gas-admin) — its CLI generates and validates front-end schemas |
 
-## Camino rápido desde cero
+---
 
-### 1. Instalá el paquete
+## Quick start from scratch
+
+### 1. Install the package
 
 ```bash
 npm i @tinya-code/gas-admin-ui
 ```
 
-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).
+An Angular 22.2 project already has `@angular/*` — verify the remaining peers (`@lucide/angular`, `chart.js`).
 
-### 2. Declará el `@source` de Tailwind
+### 2. Declare the Tailwind source
 
-En `src/styles.css`:
+In `src/styles.css`:
 
 ```css
+/* Required: lets Tailwind scan the engine's templates for utility classes */
 @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
 
-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
+@import 'tailwindcss';
+@import './styles/theme.css';   /* your design tokens */
+@import './styles/base.css';    /* your base resets   */
 ```
 
-Escribe 9 ficheros en `src/app/schemas/` ([estructura](#estructura-generada-en-srcappschemas)).
-Si la carpeta ya tiene `*.ts` falla con exit 1; `--force` regenera.
+Without this the app compiles and tests pass, but the engine UI renders with no styles.
 
-### 4. Cableá el motor — `app.config.ts`
+### 3. Wire the engine — `app.config.ts`
 
 ```ts
+// src/app/app.config.ts
+import { ApplicationConfig, provideBrowserGlobalErrorListeners } from '@angular/core';
+import { provideRouter } from '@angular/router';
 import { API_URL, provideGasAdmin } from '@tinya-code/gas-admin-ui';
+import { routes } from './app.routes';
+import { schemas } from './schemas/registry';
+import { authSchema } from './schemas/auth.schema';
+import { environment } from '../environments/environment';
 
 export const appConfig: ApplicationConfig = {
   providers: [
+    provideBrowserGlobalErrorListeners(),
     provideRouter(routes),
     provideGasAdmin({ schemas, auth: authSchema }),
     { provide: API_URL, useValue: environment.apiUrl },
@@ -63,145 +61,568 @@ export const appConfig: ApplicationConfig = {
 };
 ```
 
-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.
+```ts
+// src/environments/environment.ts
+export const environment = {
+  production: false,
+  apiUrl: 'http://localhost:3000/api/v1',
+};
+```
 
-### 5. Rutas — `app.routes.ts`
+### 4. Declare routes — `app.routes.ts`
 
 ```ts
+// src/app/app.routes.ts
+import { Routes } from '@angular/router';
 import { authGuard, shellRoutes } from '@tinya-code/gas-admin-ui';
+import { schemas } from './schemas/registry';
+
+const firstResource = schemas[0]?.id || 'dashboard';
 
 export const routes: Routes = [
   { path: '', pathMatch: 'full', redirectTo: firstResource },
-  { path: 'login', loadComponent: () => import('@tinya-code/gas-admin-ui').then((m) => m.Login) },
-  { path: '', canActivate: [authGuard], loadChildren: () => shellRoutes },
+  {
+    path: 'login',
+    loadComponent: () => import('@tinya-code/gas-admin-ui').then((m) => m.Login),
+  },
+  {
+    path: '',
+    canActivate: [authGuard],
+    loadChildren: () => shellRoutes,
+  },
   { path: '**', redirectTo: firstResource },
 ];
 ```
 
-`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.
+`login` lives outside the shell on purpose — if it were inside, `authGuard` would block it.
+
+### 5. Declare auth — `auth.schema.ts`
+
+```ts
+// src/app/schemas/auth.schema.ts
+import type { AuthSchema } from '@tinya-code/gas-admin-ui';
+
+export const authSchema: AuthSchema = {
+  providers: ['password'],
+  loginFields: [
+    { key: 'email', type: 'email', required: true },
+    { key: 'password', type: 'password', required: true },
+  ],
+  redirectAfterLogin: '/dashboard',
+  rememberMe: false,
+};
+```
+
+### 6. Declare your schemas — `registry.ts`
 
-### 6. Revisá los labels de cada `*.schema.ts`
+```ts
+// src/app/schemas/registry.ts
+import type { ResourceSchema } from '@tinya-code/gas-admin-ui';
+import { dashboardSchema } from './dashboard.schema';
+import { businessSchema } from './business.schema';
+import { clientsSchema } from './clients.schema';
+import { ranksSchema } from './ranks.schema';
+import { rewardsSchema } from './rewards.schema';
+import { couponsSchema } from './coupons.schema';
+import { feedbackSchema } from './feedback.schema';
+
+export const schemas: ResourceSchema[] = [
+  dashboardSchema,
+  businessSchema,
+  clientsSchema,
+  ranksSchema,
+  rewardsSchema,
+  couponsSchema,
+  feedbackSchema,
+];
+```
 
-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.
+The array order determines both menu order and the default redirect route.
 
-### 7. Levantá la app
+### 7. Start the app
 
 ```bash
 npm start
 ```
 
-Verificación: el shell arranca en `/login` y, con sesión, muestra el menú y
-las vistas derivadas de tus schemas.
+The shell starts at `/login` and, once authenticated, shows the sidebar menu and views derived from your schemas.
 
-### 8. Validá el contrato back ↔ front
+---
 
-Sólo después de tener el back con el doc al día (`npx gas-admin doc`):
+## Schema examples (real implementations)
+
+The examples below are taken from a production consumer of this library.
+
+### Dashboard — `kind: 'dashboard'`
+
+A read-only panel with metric cards. No list, no form.
+
+```ts
+// src/app/schemas/dashboard.schema.ts
+import type { ResourceSchema } from '@tinya-code/gas-admin-ui';
+
+export const dashboardSchema: ResourceSchema = {
+  id: 'dashboard',
+  label: 'Panel',
+  labelPlural: 'Dashboard',
+  kind: 'dashboard',
+  uiViews: {
+    overview: { type: 'dashboard' },
+  },
+  endpoint: {
+    get: '/admin/dashboard',
+  },
+  keyField: 'id',
+  titleField: 'label',
+  listColumns: [],
+  fields: [],
+  widgets: [
+    { type: 'metric-card', key: 'totalClients',      label: 'Total Clients',       hint: 'Registered memberships',    width: 4 },
+    { type: 'metric-card', key: 'activeClients30d',  label: 'Active (30d)',         hint: 'Visited in last 30 days',   width: 4 },
+    { type: 'metric-card', key: 'visitsThisMonth',   label: 'Visits This Month',   hint: 'Current month',             width: 4 },
+    { type: 'metric-card', key: 'averageRating',     label: 'Average Rating',      hint: 'Historical satisfaction',   width: 4 },
+    { type: 'metric-card', key: 'issuedCoupons',     label: 'Issued Coupons',      hint: 'All time',                  width: 4 },
+    { type: 'metric-card', key: 'usedCoupons',       label: 'Redeemed Coupons',    hint: 'Effective rewards',         width: 4 },
+  ],
+};
+```
+
+---
+
+### Singleton — `kind: 'singleton'` with sections layout
+
+One record, no list. The form is divided into labelled sections.
+
+```ts
+// src/app/schemas/business.schema.ts
+import type { ResourceSchema } from '@tinya-code/gas-admin-ui';
+
+export const businessSchema: ResourceSchema = {
+  id: 'business',
+  label: 'My Business',
+  labelPlural: 'My Business',
+  kind: 'singleton',
+  uiViews: {
+    settings: { type: 'form' },
+  },
+  endpoint: {
+    get: '/admin/businesses/current',
+    update: '/admin/businesses/current',
+  },
+  keyField: 'key',
+  titleField: 'name',
+  listColumns: [],
+  layout: {
+    mode: 'sections',
+    sections: [
+      { id: 'general',  label: 'General' },
+      { id: 'branding', label: 'Design & Card' },
+      { id: 'social',   label: 'Social & Links' },
+    ],
+  },
+  fields: [
+    { key: 'name',     type: 'text',   label: 'Business Name', required: true, validators: { minLength: 2, maxLength: 120 }, section: 'general',  width: 6 },
+    { key: 'slug',     type: 'slug',   from: 'name', label: 'Slug', required: true, lockAfterCreate: true, section: 'general', width: 6 },
+    { key: 'timezone', type: 'text',   label: 'Timezone', required: true, help: 'e.g. America/Lima', section: 'general', width: 6 },
+    {
+      key: 'visitResetPolicy',
+      type: 'select',
+      label: 'Visit Reset Policy',
+      section: 'general',
+      width: 6,
+      options: [
+        { value: 'none',    label: 'None' },
+        { value: 'monthly', label: 'Monthly' },
+        { value: 'yearly',  label: 'Yearly' },
+      ],
+    },
+    { key: 'colorPrimary',   type: 'text',  label: 'Primary Color (HEX)',   placeholder: '#4A2C11', section: 'branding', width: 6 },
+    { key: 'colorSecondary', type: 'text',  label: 'Secondary Color (HEX)', placeholder: '#D4A373', section: 'branding', width: 6 },
+    { key: 'logoUrl',        type: 'image', label: 'Logo', readonly: true, section: 'branding', width: 12 },
+    { key: 'googleReviewUrl', type: 'url',  label: 'Google Reviews URL', section: 'social', width: 6 },
+    { key: 'instagramUrl',   type: 'url',   label: 'Instagram', section: 'social', width: 6 },
+  ],
+};
+```
+
+---
+
+### Collection with full CRUD — `kind: 'collection'`
+
+List + create + edit. Includes search, filters, and field validators.
+
+```ts
+// src/app/schemas/ranks.schema.ts
+import type { ResourceSchema } from '@tinya-code/gas-admin-ui';
+
+export const ranksSchema: ResourceSchema = {
+  id: 'ranks',
+  label: 'Rank',
+  labelPlural: 'Ranks',
+  kind: 'collection',
+  uiViews: {
+    list:   { type: 'list' },
+    create: { type: 'form', path: 'new' },
+    edit:   { type: 'form', path: ':key/edit' },
+  },
+  endpoint: {
+    list:   '/admin/businesses/current/ranks',
+    get:    '/admin/businesses/current/ranks/{key}',
+    create: '/admin/businesses/current/ranks',
+    update: '/admin/businesses/current/ranks/{key}',
+    remove: '/admin/businesses/current/ranks/{key}',
+  },
+  keyField: 'id',
+  titleField: 'name',
+  search: ['name'],
+  filters: [
+    { key: 'includeInactive', label: 'Include Inactive', type: 'boolean' },
+  ],
+  listColumns: [
+    { key: 'level',       label: 'Level' },
+    { key: 'name',        label: 'Name' },
+    { key: 'minVisits',   label: 'Min Visits' },
+    { key: 'benefitType', label: 'Benefit Type' },
+    { key: 'benefitValue',label: 'Value' },
+    { key: 'active',      label: 'Active', format: 'boolean' },
+  ],
+  fields: [
+    { key: 'name',     type: 'text',   label: 'Rank Name', required: true, validators: { minLength: 1, maxLength: 80 } },
+    { key: 'level',    type: 'number', label: 'Level', required: true, min: 1, help: 'Must be unique among active ranks' },
+    { key: 'minVisits',type: 'number', label: 'Minimum Visits', required: true, min: 0 },
+    {
+      key: 'benefitType',
+      type: 'select',
+      label: 'Benefit Type',
+      required: true,
+      options: [
+        { value: 'none',                label: 'None' },
+        { value: 'percentage_discount', label: 'Percentage Discount' },
+        { value: 'fixed_discount',      label: 'Fixed Discount' },
+        { value: 'free_item',           label: 'Free Item' },
+        { value: 'priority',            label: 'Priority Service' },
+      ],
+    },
+    { key: 'benefitValue',       type: 'number',   label: 'Benefit Value' },
+    { key: 'benefitDescription', type: 'textarea', label: 'Benefit Description', validators: { maxLength: 200 } },
+    { key: 'color',              type: 'text',     label: 'Color (HEX)', placeholder: '#CD7F32' },
+    { key: 'iconUrl',            type: 'image',    label: 'Icon', readonly: true },
+    { key: 'active',             type: 'boolean',  label: 'Active', readonlyOn: 'create' },
+  ],
+};
+```
+
+---
+
+### Read-only collection with detail view
+
+List + detail only — no create, no edit form.
+
+```ts
+// src/app/schemas/clients.schema.ts
+import type { ResourceSchema } from '@tinya-code/gas-admin-ui';
+
+export const clientsSchema: ResourceSchema = {
+  id: 'clients',
+  label: 'Client',
+  labelPlural: 'Clients',
+  kind: 'collection',
+  uiViews: {
+    list:   { type: 'list' },
+    detail: { type: 'detail', path: ':key' },
+    edit:   { type: 'form',   path: ':key/edit' },
+  },
+  endpoint: {
+    list:   '/admin/businesses/current/clients',
+    get:    '/admin/businesses/current/clients/{key}',
+    update: '/admin/businesses/current/clients/{key}/status',
+    // no create / remove → those actions won't appear in the UI
+  },
+  keyField: 'membershipId',
+  titleField: 'name',
+  search: ['name', 'phone'],
+  filters: [
+    { key: 'active', label: 'Active', type: 'boolean' },
+  ],
+  listColumns: [
+    { key: 'name',        label: 'Name' },
+    { key: 'phone',       label: 'Phone' },
+    { key: 'email',       label: 'Email' },
+    { key: 'totalVisits', label: 'Total Visits' },
+    { key: 'lastVisitAt', label: 'Last Visit' },
+    { key: 'active',      label: 'Active', format: 'boolean' },
+    { key: 'registeredAt',label: 'Registered' },
+  ],
+  detail: {
+    enabled: true,
+    headerFields: ['name', 'phone', 'active'],
+  },
+  fields: [
+    { key: 'membershipId',        type: 'readonly-text', label: 'Membership ID',     readonly: true },
+    { key: 'name',                type: 'text',          label: 'Name',              readonly: true },
+    { key: 'phone',               type: 'phone',         label: 'Phone',             readonly: true },
+    { key: 'email',               type: 'email',         label: 'Email',             readonly: true },
+    { key: 'active',              type: 'boolean',       label: 'Active Membership' },
+    { key: 'totalVisits',         type: 'number',        label: 'Total Visits',      readonly: true },
+    { key: 'currentPeriodVisits', type: 'number',        label: 'Period Visits',     readonly: true },
+    { key: 'registeredAt',        type: 'date',          label: 'Registered At',     readonly: true },
+    { key: 'lastVisitAt',         type: 'date',          label: 'Last Visit',        readonly: true },
+  ],
+};
+```
+
+---
+
+### Read-only collection with select filter
+
+```ts
+// src/app/schemas/coupons.schema.ts
+import type { ResourceSchema } from '@tinya-code/gas-admin-ui';
+
+export const couponsSchema: ResourceSchema = {
+  id: 'coupons',
+  label: 'Coupon',
+  labelPlural: 'Coupons',
+  kind: 'collection',
+  uiViews: {
+    list:   { type: 'list' },
+    detail: { type: 'detail', path: ':key' },
+  },
+  endpoint: {
+    list: '/admin/businesses/current/coupons',
+    get:  '/admin/businesses/current/coupons/{key}',
+  },
+  keyField: 'id',
+  titleField: 'code',
+  search: ['code'],
+  filters: [
+    {
+      key: 'status',
+      label: 'Status',
+      type: 'select',
+      options: [
+        { value: 'issued',  label: 'Issued' },
+        { value: 'used',    label: 'Redeemed' },
+        { value: 'expired', label: 'Expired' },
+      ],
+    },
+  ],
+  listColumns: [
+    { key: 'code',     label: 'Code' },
+    { key: 'status',   label: 'Status' },
+    { key: 'issuedAt', label: 'Issued' },
+    { key: 'expiresAt',label: 'Expires' },
+    { key: 'usedAt',   label: 'Redeemed' },
+  ],
+  detail: {
+    enabled: true,
+    headerFields: ['code', 'status', 'issuedAt'],
+  },
+  fields: [
+    { key: 'id',        type: 'readonly-text', label: 'ID',         readonly: true },
+    { key: 'code',      type: 'text',          label: 'Code',       readonly: true },
+    { key: 'status',    type: 'text',          label: 'Status',     readonly: true },
+    { key: 'issuedAt',  type: 'date',          label: 'Issued At',  readonly: true },
+    { key: 'expiresAt', type: 'date',          label: 'Expires At', readonly: true },
+    { key: 'usedAt',    type: 'date',          label: 'Redeemed At',readonly: true },
+  ],
+};
+```
+
+---
+
+## Firebase Auth
+
+The package supports federated authentication with Google and Firebase Email/Password via the decoupled `FirebaseAuthAdapter`. Firebase is declared as an optional `peerDependency` — the library does not bundle it.
+
+### 1. Install Firebase in the consumer app
 
 ```bash
-npx gas-admin validate --with-front
+npm i firebase
+```
+
+### 2. Declare providers in `AuthSchema`
+
+```ts
+// src/app/schemas/auth.schema.ts
+import type { AuthSchema } from '@tinya-code/gas-admin-ui';
+
+// Option A — password only (default, no Firebase required)
+export const authSchema: AuthSchema = {
+  providers: ['password'],
+  loginFields: [
+    { key: 'email',    type: 'email',    required: true },
+    { key: 'password', type: 'password', required: true },
+  ],
+  redirectAfterLogin: '/dashboard',
+  rememberMe: false,
+};
+
+// Option B — Google only
+export const authSchema: AuthSchema = {
+  providers: ['google'],
+  loginFields: [],
+  redirectAfterLogin: '/dashboard',
+  rememberMe: false,
+  firebase: { exchangeEndpoint: '/auth/firebase' },
+};
+
+// Option C — Google + Password (both)
+export const authSchema: AuthSchema = {
+  providers: ['google', 'password'],
+  loginFields: [
+    { key: 'email',    type: 'email',    required: true },
+    { key: 'password', type: 'password', required: true },
+  ],
+  redirectAfterLogin: '/dashboard',
+  rememberMe: false,
+  firebase: { exchangeEndpoint: '/auth/firebase' },
+};
 ```
 
-Corre el `contract-check` de `@tinya-code/gas-admin`: exit 0 = los schemas del
-front siguen coincidiendo con la proyección del back.
+### 3. Implement the adapter and wire it in `app.config.ts`
 
-## Requisitos especiales del consumidor
+```ts
+// src/app/app.config.ts
+import { initializeApp } from 'firebase/app';
+import {
+  getAuth,
+  GoogleAuthProvider,
+  signInWithPopup,
+  signInWithEmailAndPassword,
+  signOut,
+} from 'firebase/auth';
+import {
+  API_URL,
+  provideGasAdmin,
+  provideFirebaseAdapter,
+} from '@tinya-code/gas-admin-ui';
+import type { FirebaseAuthAdapter } from '@tinya-code/gas-admin-ui';
+import { environment } from '../environments/environment';
+
+const firebaseApp  = initializeApp(environment.firebase);
+const firebaseAuth = getAuth(firebaseApp);
+
+class AppFirebaseAuthAdapter implements FirebaseAuthAdapter {
+  async signInWithGoogle(): Promise<string> {
+    const cred = await signInWithPopup(firebaseAuth, new GoogleAuthProvider());
+    return cred.user.getIdToken();
+  }
+  async signInWithEmailAndPassword(email: string, password: string): Promise<string> {
+    const cred = await signInWithEmailAndPassword(firebaseAuth, email, password);
+    return cred.user.getIdToken();
+  }
+  async signOut(): Promise<void> {
+    await signOut(firebaseAuth);
+  }
+}
 
-### Tailwind v4 — `@source` obligatorio
+export const appConfig: ApplicationConfig = {
+  providers: [
+    provideRouter(routes),
+    provideGasAdmin({ schemas, auth: authSchema }),
+    provideFirebaseAdapter(new AppFirebaseAuthAdapter()),  // ← add this
+    { provide: API_URL, useValue: environment.apiUrl },
+  ],
+};
+```
 
-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.
+### 4. Backend endpoint — `POST /auth/firebase`
 
-### Tests del consumidor — desde `node_modules` (sin alias)
+The library sends the Firebase ID token using the **same envelope transport** as every other request. Your backend must:
 
-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.
+1. Receive `{ idToken: string }` in the payload.
+2. Verify it with the Firebase Admin SDK (`getAuth().verifyIdToken(idToken)`).
+3. Return `{ token, user }` — identical shape to `/auth/login`.
 
-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.
+```json
+// Request body (Content-Type: text/plain)
+{ "token": null, "method": "POST", "path": "/auth/firebase", "payload": { "idToken": "..." } }
 
-## Estructura generada en `src/app/schemas/`
+// Response
+{ "token": "<your-app-jwt>", "user": { "id": "...", "email": "...", "name": "...", "role": "..." }, "meta": {} }
+```
+
+For a full consumer integration guide including a backend handler example, environment config, and a pre-production checklist, see [`doc/firebase-consumer-example.md`](../../doc/firebase-consumer-example.md).
+
+---
+
+## Consumer requirements
+
+### Tailwind v4 — mandatory `@source`
+
+Tailwind generates utilities by scanning **your** source files. The engine lives in `node_modules` and is not scanned by default. The `@source` directive in `styles.css` (step 2) is required — without it the app compiles and tests pass green, but the engine UI renders without any styles.
 
-`npx gas-admin scaffold` aplaná la plantilla de las vitrinas (catálogo,
-agenda, panel) en una carpeta plana:
+### Tests — resolve from `node_modules` (no alias)
+
+Consumer specs must resolve `@tinya-code/gas-admin-ui` from `node_modules` (the published, compiled version), without `tsconfig.spec.json` aliases. This guarantees Angular is instantiated exactly once. To test a library change, publish an alpha and bump the dependency.
+
+---
+
+## Generated schema structure (`npx gas-admin scaffold`)
 
 ```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
+├── auth.schema.ts        # auth provider and login fields
+├── registry.ts           # ordered array that feeds the menu and routes
+├── seed-catalog.ts       # seeds the catalog for specs
+├── dashboard.schema.ts   # kind: dashboard
+├── business.schema.ts    # kind: singleton
+├── clients.schema.ts     # kind: collection (read-only with detail)
+├── ranks.schema.ts       # kind: collection (full CRUD)
+├── rewards.schema.ts     # kind: collection (full CRUD)
+├── coupons.schema.ts     # kind: collection (read-only with filters)
+└── feedback.schema.ts    # kind: collection (read-only with search)
 ```
 
-Por cada recurso, el `*.schema.ts` trae campos, validators, enums y endpoint
-derivados de la proyección back.
+`scaffold` fails with exit 1 if the target folder already contains `*.ts` files — use `--force` to regenerate.
 
-## API pública
+---
 
-Sólo lo exportado por `public-api.ts` es contrato; el resto es privado y
-puede cambiar entre alphas.
+## Public API
 
-| Grupo | Exportaciones |
+Only what `public-api.ts` exports is stable contract; everything else is private and may change between alphas.
+
+| Group | Exports |
 | --- | --- |
-| 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` |
+| Wiring & catalog | `provideGasAdmin`, `provideFirebaseAdapter`, `GAS_SCHEMAS`, `setSchemaCatalog`, `getSchema`, `allSchemas`, `getAuth`, type `GasAdminConfig` |
+| Tokens & adapters | `API_URL`, `FIREBASE_AUTH_ADAPTER`, type `FirebaseAuthAdapter` |
+| Routes & guard | `authGuard`, `shellRoutes`, `resourceRoutes` |
+| Pages | `Login`, `Dashboard`, `ListView`, `FormView`, `ResourcePage` |
+| Components | `Sidebar`, `ComposerHost`, `FieldHost`, `ConfirmDialog`, `Toast` |
+| Services | `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) |
+| Schema models | `ResourceSchema`, `AuthSchema`, `AuthProvider`, `FirebaseAuthConfig`, `ResourceAction`, `ApiError` and the full field/widget/view/layout vocabulary |
+| Render registries | `fieldDescriptors`, `columnFormatDescriptors`, `viewDescriptors`, `layoutDescriptors`, `renderKinds` |
+| Custom render | `registerRenderDescriptor`, `unregisterRenderDescriptor`, `provideRenderDescriptors`, `getRenderDescriptor`, `isSupported`, `isRenderSupported`, types `RenderKind`, `ComponentRenderKind` |
+| Composition | `validateComposition`, `MAX_DEPTH`, `SchemaCompositionError` |
+| Custom actions | `registerAction`, `getAction`, `actionsFor`, `actionType`, `actionTypes`, types `ActionDescriptor`, `ActionSurface`, `ActionContext`, `ActionResult` |
+| Validators | type `ValidatorName` |
+| Utilities | `interpolateTemplate` |
+
+---
+
+## See also
 
-## Ver también
+- **Backend** — domain declaration, `doc`, `validate`:
+  [`@tinya-code/gas-admin`](https://github.com/Tinya-Code/gas-admin) → `docs/guia-de-uso.md`.
+- **Firebase consumer guide** — full wiring, backend contract, pre-production checklist:
+  [`doc/firebase-consumer-example.md`](../../doc/firebase-consumer-example.md).
 
-- **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)
+## Development (this repo)
 
 ```bash
-ng build gas-admin-ui     # ng-packagr → dist/gas-admin-ui (fesm2022 + types)
-ng test gas-admin-ui      # vitest: tests del motor (fixtures congelados)
+ng build gas-admin-ui     # ng-packagr → dist/gas-admin-ui
+ng test gas-admin-ui      # vitest: engine tests
 ```
 
-Publicación (npm **exige** `--tag` explícito en prereleases):
+Publish (npm requires explicit `--tag` for pre-releases):
 
 ```bash
 npm publish ./dist/gas-admin-ui --tag alpha
 ```
 
-- `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.
+- `dist/` is gitignored — the build is always local and never committed.
+- Specs that render a consumer's real schemas live in the consumer repo, not here.