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

package/package.json

@@ -1,42 +1,42 @@
 {
-    "name": "@desynth/web-components-react",
-    "sideEffects": false,
-    "version": "01.28.26-alpha.1",
-    "description": "React 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": "npm run tsc",
-        "tsc": "tsc -p ."
-    },
-    "main": "./dist/index.js",
-    "module": "./dist/index.js",
-    "types": "./dist/index.d.ts",
-    "files": [
-        "dist/"
-    ],
-    "type": "module",
-    "devDependencies": {
-        "@types/react": "19.2.4",
-        "@types/react-dom": "19.2.3"
-    },
-    "dependencies": {
-        "react": ">=19.2.0",
-        "react-dom": ">=19.2.0",
-        "typescript": "5.2.2"
-    },
-    "peerDependencies": {
-        "react": ">=19.2.0",
-        "react-dom": ">=19.2.0"
-    }
+  "name": "@desynth/web-components-react",
+  "sideEffects": false,
+  "version": "13.09.26-alpha.01",
+  "description": "React 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": "npm run tsc",
+    "tsc": "tsc -p ."
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist/"
+  ],
+  "type": "module",
+  "devDependencies": {
+    "@types/react": "19.2.4",
+    "@types/react-dom": "19.2.3"
+  },
+  "dependencies": {
+    "react": ">=19.2.0",
+    "react-dom": ">=19.2.0",
+    "typescript": "5.2.2"
+  },
+  "peerDependencies": {
+    "react": ">=19.2.0",
+    "react-dom": ">=19.2.0"
+  }
 }

package/readme.md

@@ -1,15 +1,229 @@
-# desynth-web-components - React Proxy
-This is the desynth utility Stencil web component library for general purposes
+# `@desynth/web-components-react`
+
+Wrappers React tipados para los Custom Elements de `@desynth/web-components`, generados por `@stencil/react-output-target`.
+
+## Requisitos e instalación
+
+El paquete declara `react >= 19.2.0` y `react-dom >= 19.2.0` como peer dependencies. Los wrappers importan las clases y tipos del paquete core, por lo que debe instalarse también:
 
 ```bash
-HTML Web Components
-Compatible with:
-ReactJS
-Vue
-Angular
-Svelte
-Ionic
+npm install @desynth/web-components-react @desynth/web-components react react-dom
+```
+
+Conviene mantener `@desynth/web-components-react` y `@desynth/web-components` en versiones compatibles, especialmente en versiones alpha.
+
+## Uso
+
+Todos los wrappers se exportan desde la entrada principal:
+
+```tsx
+import {
+  DesynthButton,
+  DesynthDataTable,
+} from '@desynth/web-components-react';
+
+export function Example() {
+  return (
+    <>
+      <DesynthButton buttonText="Guardar" variant="solid" />
+      <DesynthDataTable
+        columns={JSON.stringify([{ key: 'name', label: 'Nombre' }])}
+        rows={JSON.stringify([{ id: '1', name: 'Ada' }])}
+        emptyText="Sin resultados"
+      />
+    </>
+  );
+}
 ```
-## General Solution's Architecture Design
-![Architecture Diagram](https://github.com/desynth/desynth-java-utils/assets/61949272/474bf10f-73cf-474c-a34b-45269dc508a2)
 
+Las exportaciones usan nombres PascalCase derivados de las clases generadas: `DesynthButton`, `DesynthTextInput`, `HorizontalCards` y `HtmlEditor`, entre otras.
+
+## Registro de Custom Elements
+
+No llames a `defineCustomElements()` para usar estos wrappers. Cada wrapper generado recibe su propia función `defineCustomElement` desde `@desynth/web-components/dist/<tag>.js` y registra ese elemento al cargarse.
+
+El loader global solo es necesario si, además de los wrappers React, la aplicación renderiza etiquetas Custom Element directamente y quiere registrarlas en bloque:
+
+```ts
+import { defineCustomElements } from '@desynth/web-components/loader';
+
+defineCustomElements();
+```
+
+No mezcles ambos mecanismos por rutina: los registros individuales ya comprueban si el elemento existe y el loader global añade trabajo innecesario cuando toda la UI usa wrappers.
+
+## Propiedades y nombres
+
+En JSX se usan los nombres de propiedad de Stencil en camelCase, no los atributos HTML en kebab-case:
+
+| Web Component | React |
+| --- | --- |
+| `button-text` | `buttonText` |
+| `empty-text` | `emptyText` |
+| `preview-url` | `previewUrl` |
+| `button-id` | `buttonId` |
+
+Las propiedades booleanas reciben booleanos reales:
+
+```tsx
+<DesynthButton disabled={isSaving} full buttonText="Guardar" />
+```
+
+Los tipos de cada wrapper proceden del paquete core y están incluidos en `dist/components.d.ts`.
+
+## Datos JSON
+
+Varias propiedades complejas del core están declaradas como `string` y el componente ejecuta `JSON.parse` internamente. En esos casos hay que serializar arrays y objetos también desde React; pasar el objeto directamente contradice la API generada.
+
+```tsx
+import { DesynthDataTable } from '@desynth/web-components-react';
+
+type Row = {
+  id: string;
+  name: string;
+  status: 'active' | 'paused';
+};
+
+const columns = [
+  { key: 'name', label: 'Nombre' },
+  { key: 'status', label: 'Estado' },
+];
+
+const rows: Row[] = [
+  { id: 'usr-1', name: 'Ada', status: 'active' },
+];
+
+export function UsersTable() {
+  return (
+    <DesynthDataTable
+      columns={JSON.stringify(columns)}
+      rows={JSON.stringify(rows)}
+      badges={JSON.stringify({
+        status: { active: '#18864b', paused: '#8a6400' },
+      })}
+      actions={JSON.stringify([
+        { key: 'open', label: 'Abrir' },
+      ])}
+      onHandleAction={(event) => {
+        const { rowId, action } = event.detail;
+        console.log(rowId, action);
+      }}
+    />
+  );
+}
+```
+
+No todas las propiedades con datos son JSON. Revisa el tipo exportado o la referencia del componente core antes de serializar.
+
+## Eventos
+
+Los eventos de Stencil se convierten en props React con prefijo `on` y PascalCase:
+
+| Evento DOM | Prop React |
+| --- | --- |
+| `handleClick` | `onHandleClick` |
+| `handleChange` | `onHandleChange` |
+| `handleAction` | `onHandleAction` |
+| `htmlChanged` | `onHtmlChanged` |
+
+El callback recibe un `CustomEvent` tipado; la carga útil está en `event.detail`.
+
+```tsx
+import { DesynthTextInput } from '@desynth/web-components-react';
+
+export function Search() {
+  return (
+    <DesynthTextInput
+      inputId="search"
+      inputName="Buscar"
+      onHandleInput={(event) => {
+        console.log(event.detail.value);
+      }}
+    />
+  );
+}
+```
+
+Usa el nombre exacto expuesto por el wrapper. No lo sustituyas por `onClick` o `onChange` salvo que la API tipada del componente lo declare.
+
+## Slots y `children`
+
+El contenido hijo se proyecta al slot por defecto. Para un slot con nombre, añade `slot` al nodo hijo:
+
+```tsx
+import {
+  DesynthBookCard,
+  DesynthButton,
+} from '@desynth/web-components-react';
+
+export function Book() {
+  return (
+    <DesynthBookCard
+      title="Diseño de sistemas"
+      chapters={JSON.stringify(['Introducción', 'Arquitectura'])}
+    >
+      <div slot="actions">
+        <DesynthButton buttonText="Leer" size="xs" />
+      </div>
+    </DesynthBookCard>
+  );
+}
+```
+
+Los nombres de slot disponibles dependen del componente core; no existe una lista universal.
+
+## SSR y React Server Components
+
+El archivo generado comienza con `'use client'`. Los wrappers registran Custom Elements y están destinados al navegador:
+
+- impórtalos y renderízalos desde componentes cliente;
+- en Next.js App Router, coloca el uso detrás de un archivo con `'use client'`;
+- no dependas de que el Shadow DOM esté renderizado en el HTML del servidor;
+- si el bundler evalúa módulos DOM durante SSR, carga el componente cliente de forma dinámica con SSR desactivado.
+
+Ejemplo para Next.js:
+
+```tsx
+'use client';
+
+import { DesynthButton } from '@desynth/web-components-react';
+
+export function SaveButton() {
+  return <DesynthButton buttonText="Guardar" />;
+}
+```
+
+El paquete core genera una salida `dist/hydrate`, pero este paquete React no configura por sí mismo una integración SSR o de hidratación para el framework.
+
+## Tokens
+
+Carga el tema CSS una sola vez desde la hoja global de la aplicación:
+
+```css
+@import '@desynth/style-tokens/dist/assets/css/variables-all.css';
+```
+
+El CSS de tokens llega como dependencia transitiva del core, pero su importación es explícita. Consulta el README de `@desynth/web-components` para las variantes de tema publicadas.
+
+## Desarrollo local y sincronización
+
+`src/components.ts` es generado: no debe editarse a mano. El flujo local correcto, desde la raíz del monorepo, es:
+
+```bash
+npm run build --workspace=@desynth/web-components
+npm run build --workspace=@desynth/web-components-react
+```
+
+El build de Stencil ejecuta el React output target y vuelve a generar `packages/components-react/src`; después, el script del wrapper ejecuta TypeScript y sincroniza `dist/`. Si solo se compila este paquete sin regenerar primero el core, los proxies pueden quedar desalineados con el catálogo actual.
+
+El paquete React publica únicamente `dist/` y su script disponible es:
+
+```bash
+npm run build  # equivalente a: npm run tsc
+```
+
+No hay script de tests definido en este paquete.
+
+## Licencia
+
+MPL-2.0 según el manifiesto del paquete.

package/dist/react-component-lib/createComponent.d.ts

@@ -1,10 +0,0 @@
-import React from 'react';
-export interface HTMLStencilElement extends HTMLElement {
-    componentOnReady(): Promise<this>;
-}
-interface StencilReactInternalProps<ElementType> extends React.HTMLAttributes<ElementType> {
-    forwardedRef: React.RefObject<ElementType>;
-    ref?: React.Ref<any>;
-}
-export declare const createReactComponent: <PropType, ElementType extends HTMLStencilElement, ContextStateType = {}, ExpandedPropsTypes = {}>(tagName: string, ReactComponentContext?: React.Context<ContextStateType> | undefined, manipulatePropsFunction?: ((originalProps: StencilReactInternalProps<ElementType>, propsToPass: any) => ExpandedPropsTypes) | undefined, defineCustomElement?: () => void) => React.ForwardRefExoticComponent<React.PropsWithoutRef<import("./utils").StencilReactExternalProps<PropType, ElementType>> & React.RefAttributes<ElementType>>;
-export {};

package/dist/react-component-lib/createComponent.js

@@ -1,74 +0,0 @@
-var __rest = (this && this.__rest) || function (s, e) {
-    var t = {};
-    for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p) && e.indexOf(p) < 0)
-        t[p] = s[p];
-    if (s != null && typeof Object.getOwnPropertySymbols === "function")
-        for (var i = 0, p = Object.getOwnPropertySymbols(s); i < p.length; i++) {
-            if (e.indexOf(p[i]) < 0 && Object.prototype.propertyIsEnumerable.call(s, p[i]))
-                t[p[i]] = s[p[i]];
-        }
-    return t;
-};
-import React, { createElement } from 'react';
-import { attachProps, camelToDashCase, createForwardRef, dashToPascalCase, isCoveredByReact, mergeRefs } from './utils';
-export const createReactComponent = (tagName, ReactComponentContext, manipulatePropsFunction, defineCustomElement) => {
-    if (defineCustomElement !== undefined) {
-        defineCustomElement();
-    }
-    const displayName = dashToPascalCase(tagName);
-    const ReactComponent = class extends React.Component {
-        constructor(props) {
-            super(props);
-            this.setComponentElRef = (element) => {
-                this.componentEl = element;
-            };
-        }
-        componentDidMount() {
-            this.componentDidUpdate(this.props);
-        }
-        componentDidUpdate(prevProps) {
-            attachProps(this.componentEl, this.props, prevProps);
-        }
-        render() {
-            const _a = this.props, { children, forwardedRef, style, className, ref } = _a, cProps = __rest(_a, ["children", "forwardedRef", "style", "className", "ref"]);
-            let propsToPass = Object.keys(cProps).reduce((acc, name) => {
-                const value = cProps[name];
-                if (name.indexOf('on') === 0 && name[2] === name[2].toUpperCase()) {
-                    const eventName = name.substring(2).toLowerCase();
-                    if (typeof document !== 'undefined' && isCoveredByReact(eventName)) {
-                        acc[name] = value;
-                    }
-                }
-                else {
-                    // we should only render strings, booleans, and numbers as attrs in html.
-                    // objects, functions, arrays etc get synced via properties on mount.
-                    const type = typeof value;
-                    if (type === 'string' || type === 'boolean' || type === 'number') {
-                        acc[camelToDashCase(name)] = value;
-                    }
-                }
-                return acc;
-            }, {});
-            if (manipulatePropsFunction) {
-                propsToPass = manipulatePropsFunction(this.props, propsToPass);
-            }
-            const newProps = Object.assign(Object.assign({}, propsToPass), { ref: mergeRefs(forwardedRef, this.setComponentElRef), style });
-            /**
-             * We use createElement here instead of
-             * React.createElement to work around a
-             * bug in Vite (https://github.com/vitejs/vite/issues/6104).
-             * React.createElement causes all elements to be rendered
-             * as <tagname> instead of the actual Web Component.
-             */
-            return createElement(tagName, newProps, children);
-        }
-        static get displayName() {
-            return displayName;
-        }
-    };
-    // If context was passed to createReactComponent then conditionally add it to the Component Class
-    if (ReactComponentContext) {
-        ReactComponent.contextType = ReactComponentContext;
-    }
-    return createForwardRef(ReactComponent, displayName);
-};

package/dist/react-component-lib/createOverlayComponent.d.ts

@@ -1,21 +0,0 @@
-import React from 'react';
-import { OverlayEventDetail } from './interfaces';
-import { StencilReactForwardedRef } from './utils';
-interface OverlayElement extends HTMLElement {
-    present: () => Promise<void>;
-    dismiss: (data?: any, role?: string | undefined) => Promise<boolean>;
-}
-export interface ReactOverlayProps {
-    children?: React.ReactNode;
-    isOpen: boolean;
-    onDidDismiss?: (event: CustomEvent<OverlayEventDetail>) => void;
-    onDidPresent?: (event: CustomEvent<OverlayEventDetail>) => void;
-    onWillDismiss?: (event: CustomEvent<OverlayEventDetail>) => void;
-    onWillPresent?: (event: CustomEvent<OverlayEventDetail>) => void;
-}
-export declare const createOverlayComponent: <OverlayComponent extends object, OverlayType extends OverlayElement>(tagName: string, controller: {
-    create: (options: any) => Promise<OverlayType>;
-}, customElement?: any) => React.ForwardRefExoticComponent<React.PropsWithoutRef<OverlayComponent & ReactOverlayProps & {
-    forwardedRef?: StencilReactForwardedRef<OverlayType> | undefined;
-}> & React.RefAttributes<OverlayType>>;
-export {};

package/dist/react-component-lib/createOverlayComponent.js

@@ -1,95 +0,0 @@
-var __rest = (this && this.__rest) || function (s, e) {
-    var t = {};
-    for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p) && e.indexOf(p) < 0)
-        t[p] = s[p];
-    if (s != null && typeof Object.getOwnPropertySymbols === "function")
-        for (var i = 0, p = Object.getOwnPropertySymbols(s); i < p.length; i++) {
-            if (e.indexOf(p[i]) < 0 && Object.prototype.propertyIsEnumerable.call(s, p[i]))
-                t[p[i]] = s[p[i]];
-        }
-    return t;
-};
-import React from 'react';
-import ReactDOM from 'react-dom';
-import { attachProps, dashToPascalCase, defineCustomElement, setRef } from './utils';
-export const createOverlayComponent = (tagName, controller, customElement) => {
-    defineCustomElement(tagName, customElement);
-    const displayName = dashToPascalCase(tagName);
-    const didDismissEventName = `on${displayName}DidDismiss`;
-    const didPresentEventName = `on${displayName}DidPresent`;
-    const willDismissEventName = `on${displayName}WillDismiss`;
-    const willPresentEventName = `on${displayName}WillPresent`;
-    let isDismissing = false;
-    class Overlay extends React.Component {
-        constructor(props) {
-            super(props);
-            if (typeof document !== 'undefined') {
-                this.el = document.createElement('div');
-            }
-            this.handleDismiss = this.handleDismiss.bind(this);
-        }
-        static get displayName() {
-            return displayName;
-        }
-        componentDidMount() {
-            if (this.props.isOpen) {
-                this.present();
-            }
-        }
-        componentWillUnmount() {
-            if (this.overlay) {
-                this.overlay.dismiss();
-            }
-        }
-        handleDismiss(event) {
-            if (this.props.onDidDismiss) {
-                this.props.onDidDismiss(event);
-            }
-            setRef(this.props.forwardedRef, null);
-        }
-        shouldComponentUpdate(nextProps) {
-            // Check if the overlay component is about to dismiss
-            if (this.overlay && nextProps.isOpen !== this.props.isOpen && nextProps.isOpen === false) {
-                isDismissing = true;
-            }
-            return true;
-        }
-        async componentDidUpdate(prevProps) {
-            if (this.overlay) {
-                attachProps(this.overlay, this.props, prevProps);
-            }
-            if (prevProps.isOpen !== this.props.isOpen && this.props.isOpen === true) {
-                this.present(prevProps);
-            }
-            if (this.overlay && prevProps.isOpen !== this.props.isOpen && this.props.isOpen === false) {
-                await this.overlay.dismiss();
-                isDismissing = false;
-                /**
-                 * Now that the overlay is dismissed
-                 * we need to render again so that any
-                 * inner components will be unmounted
-                 */
-                this.forceUpdate();
-            }
-        }
-        async present(prevProps) {
-            const _a = this.props, { children, isOpen, onDidDismiss, onDidPresent, onWillDismiss, onWillPresent } = _a, cProps = __rest(_a, ["children", "isOpen", "onDidDismiss", "onDidPresent", "onWillDismiss", "onWillPresent"]);
-            const elementProps = Object.assign(Object.assign({}, cProps), { ref: this.props.forwardedRef, [didDismissEventName]: this.handleDismiss, [didPresentEventName]: (e) => this.props.onDidPresent && this.props.onDidPresent(e), [willDismissEventName]: (e) => this.props.onWillDismiss && this.props.onWillDismiss(e), [willPresentEventName]: (e) => this.props.onWillPresent && this.props.onWillPresent(e) });
-            this.overlay = await controller.create(Object.assign(Object.assign({}, elementProps), { component: this.el, componentProps: {} }));
-            setRef(this.props.forwardedRef, this.overlay);
-            attachProps(this.overlay, elementProps, prevProps);
-            await this.overlay.present();
-        }
-        render() {
-            /**
-             * Continue to render the component even when
-             * overlay is dismissing otherwise component
-             * will be hidden before animation is done.
-             */
-            return ReactDOM.createPortal(this.props.isOpen || isDismissing ? this.props.children : null, this.el);
-        }
-    }
-    return React.forwardRef((props, ref) => {
-        return React.createElement(Overlay, Object.assign({}, props, { forwardedRef: ref }));
-    });
-};

package/dist/react-component-lib/index.d.ts

@@ -1,2 +0,0 @@
-export { createReactComponent } from './createComponent';
-export { createOverlayComponent } from './createOverlayComponent';

package/dist/react-component-lib/index.js

@@ -1,2 +0,0 @@
-export { createReactComponent } from './createComponent';
-export { createOverlayComponent } from './createOverlayComponent';

package/dist/react-component-lib/interfaces.d.ts

@@ -1,29 +0,0 @@
-export interface EventEmitter<T = any> {
-    emit: (data?: T) => CustomEvent<T>;
-}
-export interface StyleReactProps {
-    class?: string;
-    className?: string;
-    style?: {
-        [key: string]: any;
-    };
-}
-export interface OverlayEventDetail<T = any> {
-    data?: T;
-    role?: string;
-}
-export interface OverlayInterface {
-    el: HTMLElement;
-    animated: boolean;
-    keyboardClose: boolean;
-    overlayIndex: number;
-    presented: boolean;
-    enterAnimation?: any;
-    leaveAnimation?: any;
-    didPresent: EventEmitter<void>;
-    willPresent: EventEmitter<void>;
-    willDismiss: EventEmitter<OverlayEventDetail>;
-    didDismiss: EventEmitter<OverlayEventDetail>;
-    present(): Promise<void>;
-    dismiss(data?: any, role?: string): Promise<boolean>;
-}

package/dist/react-component-lib/interfaces.js

@@ -1 +0,0 @@
-export {};

package/dist/react-component-lib/utils/attachProps.d.ts

@@ -1,16 +0,0 @@
-export declare const attachProps: (node: HTMLElement, newProps: any, oldProps?: any) => void;
-export declare const getClassName: (classList: DOMTokenList, newProps: any, oldProps: any) => string;
-/**
- * Transforms a React event name to a browser event name.
- */
-export declare const transformReactEventName: (eventNameSuffix: string) => string;
-/**
- * Checks if an event is supported in the current execution environment.
- * @license Modernizr 3.0.0pre (Custom Build) | MIT
- */
-export declare const isCoveredByReact: (eventNameSuffix: string) => boolean;
-export declare const syncEvent: (node: Element & {
-    __events?: {
-        [key: string]: ((e: Event) => any) | undefined;
-    } | undefined;
-}, eventName: string, newEventHandler?: ((e: Event) => any) | undefined) => void;