HorizontalOverflowArrowsDirective

Documento de la librería HorizontalOverflowArrowsDirective (español).

Descripción

HorizontalOverflowArrowsDirective es una directiva pensada para añadir controles (flechas) que facilitan el desplazamiento horizontal en contenedores con overflow. Es útil en listas horizontales, galerías o tablas con scroll horizontal, y puede integrarse con estilos de Tailwind u otras utilidades CSS.

Características principales

• Muestra flechas izquierda/derecha cuando el contenido desborda horizontalmente.
• Soporta ocultado automático cuando no hay overflow.
• Personalizable mediante clases CSS e inputs (tamaño, posición, umbral).
• Pensada para librerías Angular (se puede empaquetar y publicar como paquete npm).

Instalación

Si la librería está publicada en npm, instálala con:

npm install @cbm-common/horizontal-overflow-arrows-directive

Si trabajas localmente dentro de este monorepo, incluye la librería en tu proyecto Angular importando su módulo (ver sección "Uso").

Compatibilidades y dependencias

• Angular: compatible con Angular 20.x (esta colección usa Angular 20.1.x como objetivo).
• Tailwind CSS: funciona con cualquier sistema de estilos; si usas Tailwind, puedes aplicar clases utilitarias a las flechas.

Uso

1. Importa el módulo de la librería en el módulo de tu aplicación o del feature:

// Suponiendo que la librería exporta un módulo llamado HorizontalOverflowArrowsModule
import { HorizontalOverflowArrowsModule } from 'horizontal-overflow-arrows-directive';

@NgModule({
   imports: [HorizontalOverflowArrowsModule]
})
export class AppModule {}

2. Añade la directiva al contenedor scrollable en la plantilla:

<div class="relative">
   <div class="overflow-x-auto whitespace-nowrap" appHorizontalOverflowArrows>
      <!-- contenido horizontal aquí -->
   </div>
</div>

Ejemplo con Tailwind:

<div class="relative">
   <div class="overflow-x-auto whitespace-nowrap px-2" appHorizontalOverflowArrows>
      <div class="inline-block mr-4">Item 1</div>
      <div class="inline-block mr-4">Item 2</div>
      <div class="inline-block mr-4">Item 3</div>
      <!-- ... -->
   </div>
</div>

API (suposiciones razonables)

Nota: la implementación real puede usar nombres distintos. A continuación se documentan las propiedades/inputs que suelen ofrecer este tipo de directivas; si prefieres, puedo inspeccionar el código y ajustar la documentación a la API exacta.

• Selector: appHorizontalOverflowArrows (atributo/directiva)

• Inputs (ejemplos comunes):

  • arrowSize?: string | number — tamaño de las flechas (p. ej. '24px' o 24).
  • arrowClass?: string — clases CSS adicionales que se aplicarán a los botones de flecha.
  • threshold?: number — margen en píxeles para considerar que existe overflow (por defecto 1 o 2).
  • autoHide?: boolean — si true, oculta las flechas cuando no hay overflow.
  • scrollAmount?: number — cantidad de píxeles a desplazar cuando se pulsa una flecha.

• Eventos (opcional):

  • @Output() scrolled = new EventEmitter<{ direction: 'left' | 'right'; distance: number }>() — notifica desplazamientos si la implementación ofrece salidas.

Ejemplo de uso con inputs:

<div class="overflow-x-auto" appHorizontalOverflowArrows [arrowSize]="32" arrowClass="text-slate-700" [autoHide]="true"></div>

Consideraciones de accesibilidad

• Asegúrate de que los botones de flecha tengan atributos aria-label adecuados (p. ej. "Desplazar a la izquierda").
• Permite el uso por teclado: Enter/Space para activar, y tabindex para foco si procede.

Estilos y personalización

La directiva sólo inyecta/controla los botones y su comportamiento; deja los estilos a tu CSS o Tailwind. Ejemplo rápido de clases para flechas usando Tailwind:

.hf-arrow {
   @apply absolute top-1/2 -translate-y-1/2 bg-white rounded-full shadow-md p-1;
}
.hf-arrow-left { left: 0.25rem; }
.hf-arrow-right { right: 0.25rem; }

Construir, test y publicar

Construir la librería dentro del workspace:

ng build horizontal-overflow-arrows-directive

Ejecutar tests unitarios (si están configurados en la librería):

ng test horizontal-overflow-arrows-directive

Publicar (desde dist/ después de un build exitoso):

cd dist/horizontal-overflow-arrows-directive
npm publish

Notas de migración (mf-common → mf-cbm-common)

Si migras desde mf-common, recuerda:

• Actualizar package.json de la librería con el prefijo de paquete deseado (por ejemplo @cbm-common/horizontal-overflow-arrows-directive).
• Ajustar peerDependencies a @angular/common y @angular/core 20.1.5 si el workspace objetivo usa Angular 20.1.5.
• Copiar la carpeta lib existente y verificar public-api.ts para exportaciones correctas.

Suposiciones y acciones recomendadas

• He supuesto nombres y API comunes para este tipo de librerías. Si quieres, puedo:
  1. Leer el código fuente real y sincronizar esta documentación con la API exacta.
  2. Añadir ejemplos de tests unitarios y un pequeño Storybook/demo.

Contribuir

Si quieres mejorar la librería o la documentación dentro de este repo:

1. Crea una rama con tu cambio.
2. Añade tests si modificas comportamiento.
3. Abre un pull request describiendo los cambios.

Licencia

Incluye la licencia del monorepo o la licencia que prefieras en el package.json antes de publicar.

Si quieres, ahora procedo a:

• Inspeccionar el código real de la directiva y reemplazar la sección "API (suposiciones razonables)" con la documentación exacta.
• Añadir ejemplos de tests unitarios para la directiva.