Contribución

¡Gracias por contribuir a lh-ui-plus! Este documento describe el proceso de contribución en detalle.

Requisitos previos

• Node.js 18+
• pnpm para instalar las dependencias
• Conocimientos básicos de Git

Instalar las dependencias

git clone https://github.com/lhgb-top/lh-ui-plus.git
cd lh-ui-plus
pnpm install

Flujo de desarrollo

1. Iniciar el servidor de desarrollo

pnpm dev

2. Ejecutar las pruebas

pnpm test:unit      # Pruebas unitarias de la capa Core
pnpm test:components  # Pruebas de integración de componentes
pnpm test            # Todas las pruebas

3. Comprobación de tipos

pnpm typecheck

4. Análisis de código

pnpm lint
pnpm lint:fix       # Corrección automática

5. Compilación

pnpm build

6. Consultar la documentación

pnpm docs:dev

Añadir un componente

El proceso completo se describe en AGENTS.md §"Adding or changing a component".

Pasos resumidos:

1. @lh-ui/share → src/core/<name>/ — lógica principal + pruebas unitarias (se completa en el repositorio share; este repositorio lo consume como dependencia npm)
2. packages/components/<name>/ — encapsulamiento del componente Vue
3. packages/components/index.ts — registro en lhComponents
4. src/index.ts — actualización de las exportaciones
5. tests/unit/components-registry.spec.ts — actualización del array de expectativas
6. tests/components/<name>.spec.ts — pruebas del componente
7. docs/components/<name>.md — página de documentación
8. docs/.vitepress/config.ts — navegación de la barra lateral

Comandos de verificación:

pnpm lint          # 0 errores, 0 advertencias
pnpm typecheck     # Sin salida
pnpm vitest run    # Todos los casos pasan
pnpm docs:build    # La compilación pasa

Despliegue del sitio de documentación

La ruta de despliegue del sitio de documentación se configura de forma centralizada en docs/.env.production (fuente única de datos); la compilación de producción se realiza directamente con:

pnpm docs:build

Variable de entorno	Descripción	Predeterminado	Ejemplo
DOCS_BASE	Ruta base del sitio; debe llevar barras al inicio y al final	/	/lhui/vue3/
DOCS_HOSTNAME	Dominio canónico del sitio, usado para el sitemap y las metaetiquetas SEO	https://www.lhgb.top	https://your-site.com

Estas dos variables afectan a la vez a las rutas de recursos, al sitemap, a las etiquetas SEO como og:url, y al robots.txt que se regenera al final de la compilación.

¿Por qué en un archivo .env y no en variables en línea? La carga de env integrada en Vite se produce después de evaluar la configuración de usuario, de modo que docs/.vitepress/config.ts debe invocar loadEnv explícitamente para poder leer estos valores durante la compilación de producción; además, el MSYS de Windows Git Bash convierte automáticamente el DOCS_BASE=/lhui/vue3/ escrito en línea en una ruta local absoluta. Para una anulación temporal se puede seguir usando una variable en línea (DOCS_BASE=/xxx/ pnpm docs:build), pero para el despliegue diario es más seguro modificar .env.production.

Convención de prefijo de despliegue unificado

El portal Fengmo (www.lhgb.top) organiza las páginas de navegación de las bibliotecas de componentes de LH-UI (/ui) con una convención unificada de rutas de despliegue /lhui/{nombre de la biblioteca}/, sin vincularlas al nombre del framework. Esta biblioteca (la versión de Vue 3) se despliega en /lhui/vue3/ (ya reflejado en docs/.env.production); el comando de compilación de producción es:

pnpm docs:build

Los artefactos de compilación se suben al servidor en /home/webuser/nginx/lh-ui/vue3/ (la copia de referencia autoritativa del fragmento de configuración de Nginx se encuentra en el archivo docs/部署/nginx-lhui.conf.md de la familia; la versión real y vigente está en el servidor, en /etc/nginx/conf.d/nginx.conf). Los ocho sitios de la familia ya están desplegados siguiendo esta convención:

Repositorio	base	Directorio alias	cleanUrls
lh-ui-plus (esta biblioteca)	/lhui/vue3/	/home/webuser/nginx/lh-ui/vue3/	No
lh-ui-vue2	/lhui/vue2/	/home/webuser/nginx/lh-ui/vue2/	No (VuePress 1.x)
lh-ui-react	/lhui/react/	/home/webuser/nginx/lh-ui/react/	No
lh-ui-uniapp	/lhui/uniapp/	/home/webuser/nginx/lh-ui/uniapp/	Sí
lh-ui-android	/lhui/android/	/home/webuser/nginx/lh-ui/android/	Sí
lh-ui-ios	/lhui/ios/	/home/webuser/nginx/lh-ui/ios/	Sí
lh-ui-harmony	/lhui/harmony/	/home/webuser/nginx/lh-ui/harmony/	Sí
lh-ui-windows	/lhui/windows/	/home/webuser/nginx/lh-ui/windows/	Sí

Los cuatro sitios del linaje nativo (android / ios / harmony / windows) son sitios VitePress con simuladores HTML estáticos integrados, y su método de despliegue es exactamente el mismo que el de los cuatro sitios del linaje web. Las bibliotecas nuevas siguen ampliando cada una su location y su .env.production bajo /lhui/{nombre de la biblioteca}/.

En los sitios cleanUrls (uniapp y los cuatro nativos), el try_files de Nginx debe incluir $uri.html; de lo contrario, las URL sin sufijo no resuelven el .html pre-renderizado. Los sitios no cleanUrls no necesitan este fragmento. Consulta la sección «tres contratos» de la copia de referencia.

Convenciones de código

• Las clases CSS usan el prefijo lh- (p. ej. lh-button__text--primary)
• Los composables deben llevar el prefijo Lh (p. ej. useLhConfigProvider)
• Los objetos constantes deben usar la nomenclatura SCREAMING_SNAKE_CASE (p. ej. LH_TYPES_CONST)
• Alias de rutas: ~/* → packages/* (este repositorio); la lógica y los estilos independientes del framework están en @lh-ui/share, y se importan a través de subrutas npm (@lh-ui/share/core/*, @lh-ui/share/styles/*)
• Formato: comillas simples, sin punto y coma, sangrado de 2 espacios, anchura de línea de 100 caracteres

Convenciones de commit

feat: añade el componente Select desplegable
fix: corrige la pérdida de foco de Input
docs: actualiza la documentación de instalación
test: añade pruebas de casos límite de Button
refactor: refactoriza la lógica reactiva de ConfigProvider

Convenciones para la asistencia con IA

El proyecto se mantiene con la asistencia de agents de IA. Los comandos de verificación los ejecuta manualmente el usuario; la IA no ejecuta pruebas ni compilaciones automáticamente.