@desynth/web-components

v14.9.26-alpha.5

Published

a day ago

Desynth is a software producer for web components that helps people make SaaS faster

0High
0Medium
0Low

`@desynth/web-components`

Biblioteca de 86 Web Components de Desynth, compilada con Stencil. Puede usarse con HTML y JavaScript sin framework o integrarse en cualquier entorno compatible con Custom Elements.

Instalación

npm install @desynth/web-components

Los tokens de diseño son una dependencia del paquete, pero su CSS se consume de forma explícita. Consulta Tokens y estilos globales.

Registro de componentes

Registrar toda la biblioteca

El loader define todos los Custom Elements. Ejecútalo una sola vez en el punto de entrada del navegador:

import { defineCustomElements } from '@desynth/web-components/loader';

defineCustomElements();

Después se usan las etiquetas directamente:

<desynth-button button-text="Guardar" variant="solid"></desynth-button>

defineCustomElements() acepta las opciones publicadas por el loader, entre ellas exclude, resourcesUrl y syncQueue.

Registrar solo lo necesario

La salida dist-custom-elements permite importar y definir cada elemento por separado:

import {
  DesynthButton,
  defineCustomElement,
} from '@desynth/web-components/dist/desynth-button.js';

defineCustomElement();

const button: DesynthButton = document.querySelector('desynth-button')!;

Cada módulo dist/<tag>.js exporta la clase del elemento y defineCustomElement. Esta modalidad evita registrar el catálogo completo y favorece el tree shaking del consumidor.

Salidas publicadas

El paquete publica únicamente dist/ y loader/:

dist/index.js y dist/index.cjs.js: entradas ESM y CommonJS declaradas en el manifiesto.
dist/esm/ y dist/cjs/: bundles de distribución de Stencil.
dist/<tag>.js: Custom Elements individuales generados por dist-custom-elements.
dist/types/ y dist/index.d.ts: declaraciones TypeScript y API de componentes.
dist/collection/: colección y manifiesto de Stencil.
dist/desynth-components/: bundle lazy para navegador; es la entrada declarada en unpkg.
dist/hydrate/: runtime de hidratación generado por dist-hydrate-script.
loader/: defineCustomElements, setNonce y el loader ESM/CommonJS.

La configuración también genera www/ para desarrollo y demostración, pero ese directorio no forma parte de los archivos publicados.

Catálogo completo (86)

Los enlaces apuntan a la referencia de propiedades, eventos y dependencias generada desde cada componente.

Controles, formularios y entrada

La etiqueta real del editor es html-editor; no lleva el prefijo desynth-.

Navegación, estructura y layout

Tarjetas, contenido y comunicación

Datos, listas y visualización

Flujos, utilidades y composición

Convenciones de propiedades y datos

En HTML, las propiedades camelCase se expresan como atributos kebab-case: buttonText pasa a button-text y emptyText a empty-text.
Booleanos simples pueden declararse por presencia, por ejemplo disabled. Para actualizar valores desde JavaScript, asigna la propiedad del elemento.
Varias APIs de colecciones están tipadas como string y ejecutan JSON.parse: items, rows, columns, options, badges, actions, messages, sections y otras según el componente. En HTML deben recibir JSON válido.
No todas las propiedades con datos usan JSON. La referencia enlazada de cada componente es la fuente de verdad para su tipo y valor por defecto.

<desynth-data-table
  columns='[{"key":"name","label":"Nombre"}]'
  rows='[{"id":"1","name":"Ada"}]'
  empty-text="Sin resultados"
></desynth-data-table>

const table = document.querySelector('desynth-data-table')!;
table.columns = JSON.stringify([{ key: 'name', label: 'Nombre' }]);
table.rows = JSON.stringify([{ id: '1', name: 'Ada' }]);

Convenciones de eventos

Los componentes emiten CustomEvent. Escucha el nombre exacto documentado —por ejemplo handleClick, handleChange, handleAction o htmlChanged— y lee la carga útil en event.detail.

const table = document.querySelector('desynth-data-table')!;

table.addEventListener('handleAction', (event) => {
  const { rowId, action } = (event as CustomEvent<{
    rowId: string;
    action: string;
  }>).detail;

  console.log(rowId, action);
});

Los eventos no siguen una única carga útil universal: algunos entregan void, otros primitivas, objetos o archivos. Comprueba siempre la tabla Events de la referencia del componente.

Slots

Los slots siguen el estándar del navegador. El contenido sin atributo slot ocupa el slot por defecto; los slots con nombre se asignan explícitamente. Los nombres disponibles dependen de cada componente.

<desynth-book-card title="Diseño de sistemas">
  <div slot="actions">
    <desynth-button button-text="Leer"></desynth-button>
  </div>
</desynth-book-card>

Tokens y estilos globales

Los componentes consumen variables CSS de @desynth/style-tokens. La hoja global de la biblioteca evita redefinir los tokens --color-* deliberadamente, por lo que la aplicación debe cargar el tema que corresponda:

@import '@desynth/style-tokens/dist/assets/css/variables-all.css';

El paquete de tokens también publica variables.css, variables-dark.css, variables-hc.css y variables-hc-dark.css. Elige una estrategia y cárgala una sola vez para evitar cascadas contradictorias.

src/global/desynth.css se integra en la compilación de Stencil y contiene estilos base y variables de navegación. Incluye estilos para body; valida su efecto si la aplicación ya tiene un reset global. Los componentes pueden personalizarse sobrescribiendo variables CSS en :root, en un contenedor o en la propia etiqueta.

Desarrollo, build y tests

Desde packages/components:

npm run start       # desarrollo con watch y servidor de Stencil
npm run build       # genera dist, loader, hydrate, wrappers y documentación
npm test            # pruebas spec y e2e
npm run test.watch  # spec y e2e en modo watch
npm run generate    # scaffolding de Stencil

Los tests se detectan en src/**/*.spec.{ts,tsx} y src/**/*.e2e.{ts,tsx}. La configuración usa Jest y Puppeteer, con test/setup.ts como inicialización posterior del entorno.

Licencia

MIT.