@desynth/web-components-angular 1.28.26-alpha.1 → 13.9.26-alpha.1

package/package.json

@@ -1,64 +1,64 @@
 {
-    "name": "@desynth/web-components-angular",
-    "sideEffects": false,
-    "version": "01.28.26-alpha.1",
-    "description": "Angular proxy for @desynth/web-components",
-    "license": "MPL-2.0",
-    "homepage": "https://github.com/desynth/desynth-web-components#readme",
-    "repository": {
-        "type": "git",
-        "url": "git+https://github.com/desynth/desynth-web-components.git"
+  "name": "@desynth/web-components-angular",
+  "sideEffects": false,
+  "version": "13.09.26-alpha.01",
+  "description": "Angular proxy for @desynth/web-components",
+  "license": "MPL-2.0",
+  "homepage": "https://github.com/desynth/desynth-web-components#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/desynth/desynth-web-components.git"
+  },
+  "bugs": {
+    "url": "https://github.com/desynth/desynth-web-components/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "ng build stencil-wrapper"
+  },
+  "files": [
+    "dist/"
+  ],
+  "module": "dist/fesm2022/stencil-wrapper.mjs",
+  "typings": "dist/index.d.ts",
+  "exports": {
+    "./package.json": {
+      "default": "./package.json"
     },
-    "bugs": {
-        "url": "https://github.com/desynth/desynth-web-components/issues"
-    },
-    "publishConfig": {
-        "access": "public"
-    },
-    "scripts": {
-        "build": "ng build stencil-wrapper"
-    },
-    "files": [
-        "dist/"
-    ],
-    "module": "dist/fesm2022/stencil-wrapper.mjs",
-    "typings": "dist/index.d.ts",
-    "exports": {
-        "./package.json": {
-            "default": "./package.json"
-        },
-        "./dist": {
-            "types": "./dist/index.d.ts",
-            "esm2022": "./dist/esm2022/stencil-wrapper.mjs",
-            "esm": "./dist/esm2022/stencil-wrapper.mjs",
-            "default": "./dist/fesm2022/stencil-wrapper.mjs"
-        }
-    }, 
-    "dependencies": {
-        "@angular/animations": "~19.0.5",
-        "@angular/common": "~19.0.5",
-        "@angular/compiler": "~19.0.5",
-        "@angular/core": "~19.0.5",
-        "@angular/forms": "~19.0.5",
-        "@angular/platform-browser": "~19.0.5",
-        "@angular/platform-browser-dynamic": "~19.0.5",
-        "@angular/router": "~19.0.5",
-        "ng-packagr": "~19.0.1",
-        "rxjs": "~7.8.1",
-        "tslib": "^2.8.1",
-        "zone.js": "~0.15.0"
-    },
-    "devDependencies": {
-        "@angular-devkit/build-angular": "19.0.6",
-        "@angular/cli": "19.0.6",
-        "@angular/compiler-cli": "19.0.5",
-        "@types/jasmine": "5.1.5",
-        "jasmine-core": "5.5.0",
-        "karma": "6.4.4",
-        "karma-chrome-launcher": "3.2.0",
-        "karma-coverage": "2.2.1",
-        "karma-jasmine": "5.1.0",
-        "karma-jasmine-html-reporter": "2.1.0",
-        "typescript": "~5.6.2"
+    "./dist": {
+      "types": "./dist/index.d.ts",
+      "esm2022": "./dist/esm2022/stencil-wrapper.mjs",
+      "esm": "./dist/esm2022/stencil-wrapper.mjs",
+      "default": "./dist/fesm2022/stencil-wrapper.mjs"
     }
+  },
+  "dependencies": {
+    "@angular/animations": "~19.0.5",
+    "@angular/common": "~19.0.5",
+    "@angular/compiler": "~19.0.5",
+    "@angular/core": "~19.0.5",
+    "@angular/forms": "~19.0.5",
+    "@angular/platform-browser": "~19.0.5",
+    "@angular/platform-browser-dynamic": "~19.0.5",
+    "@angular/router": "~19.0.5",
+    "ng-packagr": "~19.0.1",
+    "rxjs": "~7.8.1",
+    "tslib": "^2.8.1",
+    "zone.js": "~0.15.0"
+  },
+  "devDependencies": {
+    "@angular-devkit/build-angular": "19.0.6",
+    "@angular/cli": "19.0.6",
+    "@angular/compiler-cli": "19.0.5",
+    "@types/jasmine": "5.1.5",
+    "jasmine-core": "5.5.0",
+    "karma": "6.4.4",
+    "karma-chrome-launcher": "3.2.0",
+    "karma-coverage": "2.2.1",
+    "karma-jasmine": "5.1.0",
+    "karma-jasmine-html-reporter": "2.1.0",
+    "typescript": "~5.6.2"
+  }
 }

package/readme.md

@@ -1,15 +1,237 @@
-# desynth-web-components - React Proxy
-This is the desynth utility Stencil web component library for general purposes
+# `@desynth/web-components-angular`
+
+Proxies Angular standalone para los Custom Elements de `@desynth/web-components`, generados por `@stencil/angular-output-target`.
+
+## Compatibilidad e instalación
+
+El workspace compila el paquete con Angular 19.0.x. El artefacto generado declara peer dependencies de `@angular/core` y `@angular/common` `^17.0.0`; valida la combinación concreta con la versión de Angular de la aplicación.
+
+Los proxies importan tipos y módulos Custom Element desde el paquete core, por lo que ambas bibliotecas deben estar disponibles:
+
+```bash
+npm install @desynth/web-components-angular @desynth/web-components
+```
+
+El manifiesto raíz expone actualmente la librería compilada mediante el subpath `./dist`. Por tanto, los imports de consumo se hacen desde:
+
+```ts
+import { DesynthButton } from '@desynth/web-components-angular/dist';
+```
+
+No se documenta un import desde la raíz porque el mapa `exports` publicado no define `.`.
+
+## Componentes standalone
+
+Cada proxy generado tiene `standalone: true`, usa `ChangeDetectionStrategy.OnPush` y registra su propio Custom Element mediante el módulo individual de `@desynth/web-components/dist`. No es necesario llamar a `defineCustomElements()`.
+
+```ts
+import { Component } from '@angular/core';
+import {
+  DesynthButton,
+  DesynthTextInput,
+} from '@desynth/web-components-angular/dist';
+
+@Component({
+  selector: 'app-profile-form',
+  standalone: true,
+  imports: [DesynthButton, DesynthTextInput],
+  template: `
+    <desynth-text-input
+      inputId="display-name"
+      inputName="Nombre"
+      [inputValue]="name"
+      (handleInput)="updateName($event)"
+    />
+
+    <desynth-button
+      buttonText="Guardar"
+      variant="solid"
+      [disabled]="saving"
+      (handleClick)="save()"
+    />
+  `,
+})
+export class ProfileFormComponent {
+  name = '';
+  saving = false;
+
+  updateName(event: CustomEvent<HTMLInputElement>): void {
+    this.name = event.detail.value;
+  }
+
+  save(): void {
+    // Persistencia de la aplicación.
+  }
+}
+```
+
+Los selectores conservan las etiquetas originales: por ejemplo `desynth-button`, `desynth-data-table`, `horizontal-cards` y `html-editor`.
+
+## Módulo de compatibilidad
+
+El paquete también exporta `StencilWrapperModule`, pero el módulo mantenido en el repositorio solo agrupa un subconjunto de los proxies. Para código nuevo, importa directamente las clases standalone que use cada componente; es explícito, permite tree shaking y evita asumir que el módulo contiene los 86 elementos.
+
+Si una aplicación basada en NgModules usa únicamente ese subconjunto, puede importar:
+
+```ts
+import { NgModule } from '@angular/core';
+import { StencilWrapperModule } from '@desynth/web-components-angular/dist';
+
+@NgModule({
+  imports: [StencilWrapperModule],
+})
+export class SharedUiModule {}
+```
+
+## Inputs y bindings
+
+Los nombres de `@Input` son las propiedades camelCase de Stencil. Usa property binding para valores dinámicos o no string:
+
+```html
+<desynth-button
+  [buttonText]="submitLabel"
+  [disabled]="form.invalid"
+  [full]="true"
+></desynth-button>
+```
+
+En una plantilla, un atributo literal sigue siendo texto. Por eso `[disabled]="false"` y `disabled="false"` no son equivalentes para una entrada booleana.
+
+Los proxies trasladan las asignaciones a la propiedad del Custom Element fuera de la zona de Angular. No hay `ControlValueAccessor` configurado: la lista `valueAccessorConfigs` del output target está vacía. En consecuencia, no asumas compatibilidad automática con `[(ngModel)]` o `formControlName`; conecta el valor y el evento explícitamente.
+
+## Propiedades JSON
+
+En el paquete core, numerosas colecciones están tipadas como `string` y se parsean con `JSON.parse`. Serializa esos valores antes de enlazarlos:
+
+```ts
+import { Component } from '@angular/core';
+import { DesynthDataTable } from '@desynth/web-components-angular/dist';
+
+@Component({
+  selector: 'app-users-table',
+  standalone: true,
+  imports: [DesynthDataTable],
+  template: `
+    <desynth-data-table
+      [columns]="columnsJson"
+      [rows]="rowsJson"
+      [actions]="actionsJson"
+      emptyText="Sin resultados"
+      (handleAction)="handleAction($event)"
+    />
+  `,
+})
+export class UsersTableComponent {
+  readonly columnsJson = JSON.stringify([
+    { key: 'name', label: 'Nombre' },
+  ]);
+
+  readonly rowsJson = JSON.stringify([
+    { id: 'usr-1', name: 'Ada' },
+  ]);
+
+  readonly actionsJson = JSON.stringify([
+    { key: 'open', label: 'Abrir' },
+  ]);
+
+  handleAction(
+    event: CustomEvent<{ rowId: string; action: string }>,
+  ): void {
+    console.log(event.detail.rowId, event.detail.action);
+  }
+}
+```
+
+No serialices a ciegas: utiliza los tipos de los proxies y la referencia del componente core como fuente de verdad.
+
+## Outputs y eventos
+
+Los eventos del Custom Element se exponen con el mismo nombre como outputs Angular: `(handleClick)`, `(handleChange)`, `(handleAction)`, `(htmlChanged)`, etc. El valor recibido sigue siendo un `CustomEvent`; la carga útil está en `$event.detail`.
+
+```html
+<desynth-tabs
+  [items]="tabsJson"
+  (handleChange)="selectTab($event)"
+></desynth-tabs>
+```
+
+```ts
+selectTab(event: CustomEvent<{ id: string; index: number }>): void {
+  console.log(event.detail.id, event.detail.index);
+}
+```
+
+La utilidad generada crea los outputs con `fromEvent`. Aunque las declaraciones usan `EventEmitter<CustomEvent<...>>`, no debes llamar a `.emit()` desde la aplicación: trata esos miembros como salidas del componente.
+
+## Proyección de contenido y slots
+
+Los proxies usan `<ng-content>`, por lo que Angular proyecta el contenido al Custom Element. El atributo estándar `slot` selecciona slots con nombre:
+
+```ts
+import { Component } from '@angular/core';
+import {
+  DesynthBookCard,
+  DesynthButton,
+} from '@desynth/web-components-angular/dist';
+
+@Component({
+  selector: 'app-book-card',
+  standalone: true,
+  imports: [DesynthBookCard, DesynthButton],
+  template: `
+    <desynth-book-card
+      title="Diseño de sistemas"
+      [chapters]="chaptersJson"
+    >
+      <div slot="actions">
+        <desynth-button buttonText="Leer" size="xs" />
+      </div>
+    </desynth-book-card>
+  `,
+})
+export class BookCardComponent {
+  readonly chaptersJson = JSON.stringify([
+    'Introducción',
+    'Arquitectura',
+  ]);
+}
+```
+
+Los nombres de slot son específicos de cada componente.
+
+## SSR
+
+El decorador generado intenta definir cada Custom Element al importar el proxy, pero comprueba `typeof customElements !== 'undefined'` antes de acceder al registro. Aun así, el renderizado interno del Web Component ocurre en el navegador: no asumas que Angular SSR produce su Shadow DOM completo en el HTML del servidor. Prueba la hidratación y cualquier acceso directo a `window`, archivos o APIs del navegador de los componentes usados.
+
+## Tokens
+
+Carga las variables CSS globalmente, por ejemplo en `styles.css`:
+
+```css
+@import '@desynth/style-tokens/dist/assets/css/variables-all.css';
+```
+
+El paquete core utiliza esos tokens, pero no los inyecta como tema global del consumidor.
+
+## Build y regeneración local
+
+Los archivos `lib/src/directives/proxies.ts` y `proxies-list.tsx` son generados por el build de Stencil; no deben editarse manualmente. Desde la raíz del monorepo:
+
+```bash
+npm run build --workspace=@desynth/web-components
+npm run build --workspace=@desynth/web-components-angular
+```
+
+El primer comando sincroniza los proxies Angular con los componentes actuales. El segundo ejecuta:
 
 ```bash
-HTML Web Components
-Compatible with:
-ReactJS
-Vue
-Angular
-Svelte
-Ionic
+ng build stencil-wrapper
 ```
-## General Solution's Architecture Design
-![Architecture Diagram](https://github.com/desynth/desynth-java-utils/assets/61949272/474bf10f-73cf-474c-a34b-45269dc508a2)
 
+y `ng-packagr` escribe el paquete en `packages/components-angular/dist` usando `lib/index.ts` como entrada pública.
+
+No hay script de tests definido en el manifiesto de este paquete. Aunque `angular.json` contiene una configuración Karma, sus rutas apuntan a `libs/stencil-wrapper`, mientras la librería real vive en `lib`; corrige esa configuración antes de presentarla como un comando de test soportado.
+
+## Licencia
+
+MPL-2.0 según el manifiesto raíz del paquete.