Biblioteca de Web Components

Este proyecto es una biblioteca de Web Components reutilizables construida con Stencil, integrado con Storybook para la documentación y testing. Stencil compila TypeScript y JSX en standards-based Web Components, que pueden usarse en cualquier framework principal o de forma independiente. Storybook permite el desarrollo y la documentación de componentes interactivos. El objetivo principal es crear componentes web estándar que puedan ser utilizados en cualquier framework o aplicación web moderna.

📑 Índice

• Objetivos del Proyecto
• Tecnologías Principales
• Comenzando
• Guía de Desarrollo
• Construcción
• Testing
• Documentación
• Contribución
• Licencia
• Anexo

🎯 Objetivos del Proyecto

• Crear componentes web reutilizables y framework-agnostic
• Mantener una documentación clara y actualizada
• Seguir las mejores prácticas de Web Components
• Proporcionar una experiencia de desarrollo consistente
• Facilitar la integración en cualquier proyecto web

🛠 Tecnologías Principales

• Stencil: Framework para crear Web Components
• TypeScript: Para tipado estático y mejor DX
• Vite: Como bundler y servidor de desarrollo
• Vitest: Para testing
• Storybook: Para documentación

🚀 Comenzando

Prerrequisitos

• Node.js (versión 20 o superior)
• npm (incluido con Node.js)

Puesta en marcha

1. Clona el repositorio:

git clone https://github.com/profileit/web-components-lib.git
cd web-components-lib

2. Instala las dependencias:

npm install

Uso y desarrollo

Inicia el servidor de desarrollo de Stencil:

1. Ejecuta

npm run start

2. Abre http://localhost:3333 en el navegador

Para iniciar el servidor de Storybook:

1. Ejecuta

npm run storybook

2. Abre otra consola y ejecuta (para escuchar cambios en los componentes de Stencil):

npm run build:watch

3. Abre http://localhost:6006 en tu navegador para ver la documentación y ejemplos

✅ Instalación y uso de componentes

npm i web-components-libs

Uso en Angular

📝 Guía de Desarrollo

Estructura del Proyecto

src/
├── components/                          # Componentes individuales
│   ├─ component/                     # Componente de ejemplo: radio, input, checkbox...
│   │  ├─ test/
│   │  │  └─ pr-component.spec.tsx       # Archivo de tests unitarios
│   │  ├─ pr-component.scss              # Fichero de estilos SCSS
│   │  ├─ pr-component.model.ts          # Interfaces, constantes y enums del componente
│   │  ├─ pr-component.tsx               # Componente Stencil
│   │  └─ pr-component.stories.tsx       # Historia de Storybook del componente
│   │  └─ index.ts                       # Archivo de exportación
│   └─ ...
├── stories/                             # Páginas del Storybook
├── utils/                               # Utilidades compartidas
└── index.ts                             # Componente principal

• Stencil: Abre stencil.config.ts para configuración del proyecto.
• Storybook: Las stories se encuentran en src/components/*/*.stories.tsx y src/stories/.
• Testing: Los tests unitarios se encuentran en src/components/*/*.spec.ts y src/utils/utils.spec.ts.
• Build: Los archivos de distribución se generarán en el directorio www/build/ y dist.

Creando un Nuevo Componente

1. Crea un nuevo componente:

npm run generate

2. Especifica un nombre (dash-case), por ejemplo: my-component
3. En "Which Sass format would you like to use?" selecciona ".scss Format"
4. En "Which additional files do you want to generate?", desmarca "E2E Test (.e2e.ts)" y presiona Enter

Un ejemplo de componente sería el siguiente:

import { Component, Host, h } from "@stencil/core";

@Component({
  tag: "my-component",
  styleUrl: "my-component.scss",
  scoped: true,
})
export class MyComponent {
  render() {
    return (
      <Host>
        <slot></slot>
      </Host>
    );
  }
}

Nombre de componentes

Al crear nuevas etiquetas de componentes, recomendamos utilizar pr en el nombre del componente (por ejemplo: <pr-datepicker>).

Convenciones de Código

• Usa TypeScript para todo el código
• Sigue el estilo de código de Stencil y Storybook
• Documenta todas las propiedades y eventos
• Usa CSS custom properties para estilos personalizables
• Implementa tests para cada componente

Creación de historias de Storybook

Para crear una nueva historia (story) de Storybook se deberá de crear un fichero con el mismo nombre del componente con la terminación .stories.tsx dentro de la misma carpeta del componente.

components/
├─ my-button/
│  ├─ my-button.tsx
│  ├─ my-button.stories.tsx
│  └─ ...

Ejemplo de estructura básica de una historia de Storybook:

import type { Meta } from "@stencil/storybook-plugin";
import { h } from "@stencil/core";
import { MyButton } from "./my-button";

const meta: Meta<MyButton> = {
  title: "Test/MyButton",
  component: MyButton,
  tags: ["autodocs"],
  render: (args) => <my-button {...args} />,
};

export default meta;

Para más información sobre cómo crear historias y las posibles configuraciones visitar https://storybook.js.org/docs/writing-stories

🏗 Construcción

Para construir la librería para producción:

npm run build

Los archivos de distribución se generarán en el directorio www/build y dist. Para más información visitar la documentación.

Para construir la biblioteca (Storybook) para producción:

npm run build:storybook

Los archivos de distribución se generarán en el directorio storybook-static.

🧪 Testing

Para ejecutar los tests:

npm run test

Para el modo watch:

npm run test:watch

📚 Documentación

• La documentación vive tanto en el componente como en el Storybook
• Cada componente debe incluir:
  • Descripción general
  • Ejemplos de uso (.stories.tsx)
  • API (propiedades, eventos, slots)
  • Personalización con SCSS

🤝 Contribución

1. Crea una rama para tu feature: git checkout -b feature/nombre-feature
2. Haz commit de tus cambios: git commit -m 'feat: añade nuevo componente'
3. Empuja tus cambios: git push origin feature/nombre-feature
4. Crea un Pull Request

Convenciones de Commits

Seguimos Conventional Commits:

• feat: Nueva característica
• fix: Corrección de bug
• docs: Cambios en documentación
• style: Cambios de formato
• refactor: Refactorización de código
• test: Añade o modifica tests
• chore: Cambios en el proceso de build o herramientas

📄 Licencia

Este proyecto está bajo la Licencia MIT. Ver el archivo LICENSE para más detalles.

💼 Anexo

Lazy Loading

If your Stencil project is built with the dist output target, you can import a small bootstrap script that registers all components and allows you to load individual component scripts lazily.

For example, given your Stencil project namespace is called my-design-system, to use my-component on any website, inject this into your HTML:

<script type="module" src="https://unpkg.com/my-design-system"></script>
<!--
To avoid unpkg.com redirects to the actual file, you can also directly import:
https://unpkg.com/[email protected]/dist/foobar-design-system/foobar-design-system.esm.js
-->
<my-component
  first="Stencil"
  middle="'Don't call me a framework'"
  last="JS"
></my-component>

This will only load the necessary scripts needed to render <my-component />. Once more components of this package are used, they will automatically be loaded lazily.

You can also import the script as part of your node_modules in your applications entry file:

import "foobar-design-system/dist/foobar-design-system/foobar-design-system.esm.js";

Check out this Live Demo.

Standalone

If you are using a Stencil component library with dist-custom-elements, we recommend importing Stencil components individually in those files where they are needed.

To export Stencil components as standalone components make sure you have the dist-custom-elements output target defined in your stencil.config.ts.

For example, given you'd like to use <my-component /> as part of a React component, you can import the component directly via:

import "foobar-design-system/my-component";

function App() {
  return (
    <>
      <div>
        <my-component
          first="Stencil"
          middle="'Don't call me a framework'"
          last="JS"
        ></my-component>
      </div>
    </>
  );
}

export default App;

Check out this Live Demo.

CI/CD y Despliegue

Este proyecto utiliza GitHub Actions para la integración y el despliegue continuo. El pipeline compila automáticamente la aplicación y despliega la rama principal en Firebase Hosting.

Para obtener una explicación detallada del flujo de trabajo, las tareas y la configuración necesaria, consulte la Documentación de CI/CD.