brkrelease-react

Widget de React para mostrar actualizaciones y changelog de BrkRelease en tu aplicación.

📋 Compatibilidad

• React: 16.9.x, 17.x, 18.x, 19.x
• React DOM: 16.9.x, 17.x, 18.x, 19.x

🚀 Instalación

npm install brkrelease-react

🎯 Uso Básico

import React from 'react';
import { BrkReleaseWidget } from 'brkrelease-react';

function App() {
  return (
    <div>
      {/* Tu aplicación */}
      
      <BrkReleaseWidget 
        projectId="tu-proyecto-id"
        apiUrl="https://api.brakodev.com"
      />
    </div>
  );
}

📋 Props Disponibles

| Prop | Tipo | Requerido | Descripción | |------|------|-----------|-------------| | projectId | string | ✅ | ID del proyecto de BrkRelease | | apiUrl | string | ✅ | URL base de la API de BrkRelease | | theme | 'light' \| 'dark' | ❌ | Tema del widget (por defecto: 'light') | | position | 'top-left' \| 'top-right' \| 'bottom-left' \| 'bottom-right' \| 'sidebar-left' \| 'sidebar-right' | ❌ | Posición del botón (por defecto: 'bottom-right') | | primaryColor | string | ❌ | Color primario del widget (CSS color) | | maxReleases | number | ❌ | Máximo número de releases a mostrar (por defecto: 10) | | publishedOnly | boolean | ❌ | Mostrar solo releases publicados (por defecto: true) | | buttonText | string | ❌ | Texto personalizado para el botón | | onOpen | () => void | ❌ | Callback cuando se abre el widget | | onClose | () => void | ❌ | Callback cuando se cierra el widget | | onReleaseClick | (release: Release) => void | ❌ | Callback cuando se hace clic en un release |

🎨 Ejemplos de Personalización

Tema Oscuro

<BrkReleaseWidget 
  projectId="tu-proyecto-id"
  apiUrl="https://api.brakodev.com"
  theme="dark"
/>

Color Personalizado

<BrkReleaseWidget 
  projectId="tu-proyecto-id"
  apiUrl="https://api.brakodev.com"
  primaryColor="#10B981"
/>

Posición Personalizada

<BrkReleaseWidget 
  projectId="tu-proyecto-id"
  apiUrl="https://api.brakodev.com"
  position="top-left"
/>

📱 Modo Sidebar

El widget ahora soporta un modo sidebar que ocupa todo el lateral de la pantalla, proporcionando una experiencia más inmersiva y siempre visible.

¿Qué es el Modo Sidebar?

A diferencia del modo modal tradicional que aparece como una ventana flotante, el modo sidebar:

• Ocupa todo el lateral izquierdo o derecho de la pantalla
• Empuja el contenido principal hacia el lado opuesto
• Proporciona más espacio para mostrar releases
• Ofrece una experiencia más inmersiva
• Es ideal para aplicaciones de escritorio y tablets

Configuración del Sidebar

Sidebar Izquierdo

<BrkReleaseWidget 
  projectId="tu-proyecto-id"
  apiUrl="https://api.brakodev.com"
  position="sidebar-left"
/>

Sidebar Derecho

<BrkReleaseWidget 
  projectId="tu-proyecto-id"
  apiUrl="https://api.brakodev.com"
  position="sidebar-right"
/>

Ajustando el Contenido Principal

Cuando uses el modo sidebar, es recomendable ajustar tu contenido principal para que se adapte correctamente:

/* Ajuste automático cuando el sidebar está abierto */
.main-content {
  transition: margin-left 0.3s ease, margin-right 0.3s ease;
}

/* El widget automáticamente añade estas clases al body */
body.brkrelease-sidebar-left-open .main-content {
  margin-left: 400px; /* Ancho del sidebar */
}

body.brkrelease-sidebar-right-open .main-content {
  margin-right: 400px; /* Ancho del sidebar */
}

/* Para dispositivos móviles, el sidebar ocupa toda la pantalla */
@media (max-width: 768px) {
  body.brkrelease-sidebar-left-open .main-content,
  body.brkrelease-sidebar-right-open .main-content {
    margin-left: 0;
    margin-right: 0;
  }
}

Ejemplo Completo con Sidebar

import React from 'react';
import { BrkReleaseWidget } from 'brkrelease-react';

function App() {
  return (
    <div className="app">
      <header className="header">
        <h1>Mi Aplicación</h1>
        {/* El botón del sidebar aparecerá aquí automáticamente */}
      </header>
      
      <main className="main-content">
        <h2>Contenido Principal</h2>
        <p>Este contenido se ajustará automáticamente cuando se abra el sidebar.</p>
      </main>
      
      <BrkReleaseWidget 
        projectId="tu-proyecto-id"
  apiUrl="https://api.brakodev.com"
  position="sidebar-right"
  theme="light"
        primaryColor="#3B82F6"
        onOpen={() => console.log('Sidebar abierto')}
        onClose={() => console.log('Sidebar cerrado')}
        onReleaseClick={(release) => {
          console.log('Release clickeado en sidebar:', release.title);
        }}
      />
    </div>
  );
}

Con Callbacks

<BrkReleaseWidget 
  projectId="tu-proyecto-id"
  apiUrl="https://api.brakodev.com"
  onOpen={() => console.log('Widget abierto')}
  onClose={() => console.log('Widget cerrado')}
  onReleaseClick={(release) => {
    console.log('Release clickeado:', release.title);
    // Abrir release en modal personalizado, analytics, etc.
  }}
/>

🧩 Uso Avanzado

Hook personalizado

Si necesitas más control, puedes usar el hook directamente:

import { useBrkReleaseWidget } from 'brkrelease-react';

function MyCustomComponent() {
  const {
    isOpen,
    isLoading,
    releases,
    project,
    error,
    hasNewReleases,
    openWidget,
    closeWidget,
    refresh
  } = useBrkReleaseWidget('tu-proyecto-id', 'https://api.brakodev.com');

  return (
    <div>
      <button onClick={openWidget}>
        Ver actualizaciones {hasNewReleases && '🔴'}
      </button>
      
      {isOpen && (
        <div>
          {/* Tu modal personalizado */}
          {releases.map(release => (
            <div key={release.id}>{release.title}</div>
          ))}
        </div>
      )}
    </div>
  );
}

API directa

También puedes usar la API directamente:

import { BrkReleaseAPI } from 'brkrelease-react';

const api = new BrkReleaseAPI('https://api.brakodev.com');

// Obtener releases
const releases = await api.getReleases('proyecto-id');

// Obtener proyecto
const project = await api.getProject('proyecto-id');

// Verificar nuevos releases
const { hasNew, count } = await api.hasNewReleases('proyecto-id', '2024-01-01');

🎭 Tipos TypeScript

import type { 
  Release, 
  Project, 
  ReleaseType, 
  WidgetTheme 
} from 'brkrelease-react';

const handleReleaseClick = (release: Release) => {
  console.log(`Tipo: ${release.type}, Título: ${release.title}`);
};

🔧 Configuración de Desarrollo

Para trabajar con el widget en modo desarrollo:

# Instalar dependencias
npm install

# Modo desarrollo
npm run dev

# Construir
npm run build

# Vista previa
npm run preview

📱 Responsive

El widget es completamente responsive y se adapta a:

• Dispositivos móviles
• Tablets
• Escritorio
• Diferentes orientaciones

♿ Accesibilidad

El widget incluye:

• Navegación por teclado
• ARIA labels
• Soporte para lectores de pantalla
• Contraste de colores adecuado

🌐 Internacionalización

Actualmente soporta:

• Español (por defecto)
• Fechas localizadas
• Fácil extensión para otros idiomas

🚨 Manejo de Errores

El widget maneja automáticamente:

• Errores de red
• APIs no disponibles
• Datos malformados
• Estados de carga

📄 Licencia

MIT License - Ver archivo LICENSE para más detalles.

🤝 Contribuir

¡Las contribuciones son bienvenidas! Ver CONTRIBUTING.md para más información.

🐛 Reportar Bugs

Usa GitHub Issues para reportar bugs o solicitar nuevas funcionalidades.