@stone_djjh/react-ui

Librería de componentes UI moderna, autónoma y accesible para React 19 construida con TypeScript y CSS Modules.

• Cero Dependencias de Frameworks CSS: Estilos scoped en CSS Modules puros gobernados por tokens CSS nativos (tokens.css). Sin Tailwind ni librerías CSS-in-JS en runtime.
• Arquitectura Desacoplada y Autónoma: Cada componente opera con sus propios estilos, contratos de tipos e internacionalización modular (ES / EN).
• Mobile-First y Accesible: Cumplimiento con estándares WCAG y WAI-ARIA, áreas táctiles mínimas de 44px para móviles y navegación completa por teclado.

📦 Instalación

npm install @stone_djjh/react-ui

Importación de Estilos

Importa la hoja de estilos unificada una sola vez en el punto de entrada de tu aplicación (main.tsx o index.tsx):

import '@stone_djjh/react-ui/style.css';

🎨 Catálogo de Componentes

1. Elementos Base y Formularios

• Button: Variantes semánticas (primary, secondary, outline, ghost, danger), tamaños (sm, md, lg), estado de carga animado (loading) e iconos adjuntos (iconLeft, iconRight).
• Input: Campo de entrada con etiquetas flotantes accesibles (label), mensajes de validación reactivos (error), textos de ayuda (helperText) e iconos contextuales (leadingIcon, trailingIcon).
• Card: Contenedor modular con subcomponentes compuestos (Card.Header, Card.Body, Card.Footer).
• Badge: Etiquetas de estado semánticas (primary, neutral, success, danger, outline) y tamaños (sm, md).

2. Layouts y Estructura de Aplicación

• DashboardLayout: Shell administrativo con barra superior, selector de tema, soporte responsivo y sidebar colapsable.
• SidebarNav: Navegación jerárquica con control de acceso por roles (RBAC recursivo), submenús anidados tipo acordeón y menús flotantes emergentes (flyouts) en modo colapsado.
• EcommerceLayout: Estructura de tienda digital con catálogo en rejilla fluida, panel de filtros y carrito drawer accesible con cálculo de subtotal.
• AuthLayout: Vistas completas y centradas/divididas para inicio de sesión, registro y recuperación de contraseña con i18n nativo.
• ErrorPage: Páginas de estado y error para códigos HTTP 404, 403, 401 y 500, disponibles tanto en modo pantalla completa (full) como embebidas dentro de dashboards (embedded).

3. Diálogos, Notificaciones y Feedback

• ToastProvider / useToast / toast: Sistema de notificaciones en tiempo real a 60/120fps (requestAnimationFrame), pausa en hover, halo semántico y API programática directa.
• Alert: Banners de notificación en línea con 5 variantes semánticas y cierre accesible.
• ConfirmDialog / useConfirm: Diálogo de confirmación modal controlado por Promesas asíncronas (const ok = await confirm({ ... })) con halos luminosos semánticos.
• Modal / Dialog: Ventana modal accesible compuesta (Modal.Header, Modal.Body, Modal.Footer), portal directo a document.body, atajo de teclado Escape y bloqueo dinámico de scroll.

4. Navegación, Datos y Multimedia

• DataTable: Tabla de datos tipada genérica (<TData>) con ordenamiento interactivo por columnas, selección de filas con casillas checkbox, estados de carga esqueleto (skeleton shimmer) y estado vacío personalizable.
• Pagination: Paginación con cálculo algorítmico inteligente de elipsis (...), selector de registros por página, resumen informativo y soporte bilingüe (ES/EN).
• Dropdown: Menú flotante contextual de tres puntos (⋮) o triggers personalizados con asChild, atajos de teclado (shortcut), variantes destructivas (danger) y elevación con desenfoque de fondo.
• Carousel: Carrusel y galería multimedia con soporte táctil (swipe), autoplay con pausa al pasar el cursor (pauseOnHover), indicadores de puntos, flechas laterales y modo galería con miniaturas.
• Timeline: Línea de tiempo secuencial con orientación vertical y horizontal (stepper de seguimiento para tracking de pedidos en vivo), badges de estado y animación de pulso luminosa.
• ProductCard: Tarjeta de producto comercial con proporción 1:1, badges de stock trifásicos, metadatos, rating, precios tachados y cálculo automático de porcentaje de ahorro.

🚀 Ejemplos Rápidos de Uso

DataTable con Paginación y Dropdown

import React, { useState } from 'react';
import { DataTable, Pagination, Dropdown, ColumnDef } from '@stone_djjh/react-ui';

interface Product {
  id: string;
  sku: string;
  name: string;
  price: number;
}

export const InventoryTable = () => {
  const [data] = useState<Product[]>([
    { id: '1', sku: 'BRK-001', name: 'Pastillas Brembo', price: 68.5 },
    { id: '2', sku: 'CLT-042', name: 'Kit Embrague Luk', price: 145.0 },
  ]);

  const columns: ColumnDef<Product>[] = [
    { key: 'sku', header: 'SKU', sortable: true },
    { key: 'name', header: 'Producto', sortable: true },
    {
      key: 'price',
      header: 'Precio',
      align: 'right',
      render: (row) => `$${row.price.toFixed(2)}`,
    },
    {
      key: 'actions',
      header: 'Acciones',
      align: 'center',
      render: (row) => (
        <Dropdown align="end">
          <Dropdown.Trigger asChild>
            <button type="button">⋮</button>
          </Dropdown.Trigger>
          <Dropdown.Menu>
            <Dropdown.Item icon="✏️" onClick={() => console.log('Editar', row.id)}>
              Editar
            </Dropdown.Item>
            <Dropdown.Divider />
            <Dropdown.Item variant="danger" icon="🗑️" onClick={() => console.log('Borrar', row.id)}>
              Eliminar
            </Dropdown.Item>
          </Dropdown.Menu>
        </Dropdown>
      ),
    },
  ];

  return (
    <div>
      <DataTable
        columns={columns}
        data={data}
        selectable
        striped
        hoverable
      />
      <Pagination
        currentPage={1}
        totalPages={10}
        totalItems={100}
        pageSize={10}
        showSummary
      />
    </div>
  );
};

Diálogo Modal Compuesto

import React, { useState } from 'react';
import { Modal, Button, Input } from '@stone_djjh/react-ui';

export const CreateBrandModal = () => {
  const [isOpen, setIsOpen] = useState(false);

  return (
    <>
      <Button onClick={() => setIsOpen(true)}>Crear Fabricante</Button>

      <Modal isOpen={isOpen} onClose={() => setIsOpen(false)} size="md">
        <Modal.Header
          title="Nuevo Fabricante"
          description="Ingresa los datos del fabricante autorizado."
        />
        <Modal.Body>
          <Input label="Nombre de la Marca" placeholder="Ej: Bosch" />
        </Modal.Body>
        <Modal.Footer align="end">
          <Button variant="ghost" onClick={() => setIsOpen(false)}>Cancelar</Button>
          <Button variant="primary" onClick={() => setIsOpen(false)}>Guardar</Button>
        </Modal.Footer>
      </Modal>
    </>
  );
};

🎨 Personalización con Tokens CSS

La librería se adapta a cualquier identidad visual mediante variables nativas CSS (tokens.css). Puedes sobreescribirlas en tu hoja de estilos principal:

:root {
  --rui-primary: #6366f1;
  --rui-primary-hover: #4f46e5;
  --rui-surface: #0f172a;
  --rui-surface-card: #1e293b;
  --rui-border: rgba(255, 255, 255, 0.12);
  --rui-text: #f8fafc;
  --rui-text-muted: #94a3b8;
  --rui-radius: 0.75rem;
}

🧪 Pruebas y Calidad de Código

Toda la librería cuenta con una suite completa de pruebas unitarias escritas con Vitest:

npm test

Salida actual:

Test Files  17 passed (17)
     Tests  64 passed (64)

📄 Licencia

Distribuido bajo la Licencia MIT. Consulta LICENSE para más información.