@nqnmodernizacion/gestor-recibos

Librería de componentes React para consulta y pago de recibos tributarios municipales.

Requisitos

• Node.js 18+
• React 18+

Instalación

npm install @nqnmodernizacion/gestor-recibos

Importá el CSS en el entry point de tu app (ej: main.tsx):

import "@nqnmodernizacion/gestor-recibos/styles.css";

Uso

ReciboDialog — modal controlado

El componente principal. El consumidor controla cuándo abrir/cerrar el dialog.

import { useState } from "react";
import { ReciboDialog } from "@nqnmodernizacion/gestor-recibos";

function MiPagina() {
  const [open, setOpen] = useState(false);

  async function fetchRecibo(nro: string) {
    const res = await fetch(`/api/recibos/${nro}`);
    if (!res.ok) throw new Error("No se encontró el recibo");
    return res.json();
  }

  return (
    <>
      <button onClick={() => setOpen(true)}>Ver recibo</button>

      <ReciboDialog
        open={open}
        onOpenChange={setOpen}
        onFetchRecibo={fetchRecibo}
        onPagar={(medio, recibo) => {
          console.log("Pagar con", medio.nombre, "recibo", recibo.nroRecibo);
        }}
      />
    </>
  );
}

Con número de recibo pre-cargado (auto-fetch al abrir):

<ReciboDialog
  open={open}
  onOpenChange={setOpen}
  onFetchRecibo={fetchRecibo}
  initialNro="0002-63823753"
  title="Recibo de pago" // opcional, default: "Recibo de pago"
/>

ReciboFlow — sin modal

Si necesitás el flujo de búsqueda embebido directamente en una página:

import { ReciboFlow } from "@nqnmodernizacion/gestor-recibos";

<ReciboFlow
  onFetchRecibo={fetchRecibo}
  onPagar={(medio, recibo) => {
    /* ... */
  }}
/>;

Datos mock para desarrollo

import {
  MOCK_RECIBO_TRIBUTO,
  MOCK_RECIBO_VENCIDO,
  MOCK_RECIBO_PAGADO,
  MOCK_ERROR_NO_ENCONTRADO,
  mockFetch,
  mockFetchError,
} from "@nqnmodernizacion/gestor-recibos/src/mocks/recibo.mock";

// Simula una respuesta exitosa con delay de 800ms
<ReciboDialog
  open={open}
  onOpenChange={setOpen}
  onFetchRecibo={mockFetch(MOCK_RECIBO_TRIBUTO)}
  initialNro="0002-63823753"
/>

// Simula un error
<ReciboDialog
  open={open}
  onOpenChange={setOpen}
  onFetchRecibo={mockFetchError(MOCK_ERROR_NO_ENCONTRADO)}
/>

Personalización de estilos

Todos los valores visuales son CSS custom properties bajo :root. Sobreescribí los que necesites en el CSS global de tu app:

:root {
  --recibo-color-primary: #c0392b; /* color de botones y foco */
  --recibo-color-bg: #f8f9fa; /* fondo de paneles */
  --recibo-font-family-base: "Inter", sans-serif;
}

Tokens disponibles: ver src/styles/tokens.css.

API completa

Props de ReciboDialog

| Prop | Tipo | Requerido | Descripción | | --------------- | ------------------------------------------------ | --------- | ----------------------------------------------------- | | open | boolean | ✅ | Controla si el dialog está abierto | | onOpenChange | (open: boolean) => void | ✅ | Callback para cerrar el dialog | | onFetchRecibo | (nro: string) => Promise<ReciboData> | ✅ | Función para obtener los datos del recibo | | onPagar | (medio: MedioPago, recibo: ReciboData) => void | — | Callback al hacer clic en un medio de pago | | onError | (error: Error) => void | — | Callback para logging de errores | | initialNro | string | — | Número de recibo pre-cargado — dispara fetch al abrir | | title | string | — | Título del dialog (default: "Recibo de pago") |

Exports disponibles

// Componentes
ReciboDialog, ReciboFlow, ReciboView
ReciboHeader, ReciboTotales, MediosPago, ReciboPDF
ReciboSkeleton, ReciboError

// Hook
useReciboFlow

// Tipos
ReciboData, ReciboDialogProps, ReciboFlowProps, ReciboFlowStatus
EstadoRecibo, ReciboVencimiento, ReciboPdf, MedioPago
ReciboHeaderProps, ReciboTotalesProps, ReciboPDFProps
MediosPagoProps, ReciboViewProps, ReciboErrorProps, PlanPagoOpcion

Scripts

npm run dev     # tsup en watch — reconstruye dist/ en cada cambio
npm run build   # build de producción
npm run lint    # type-check (tsc --noEmit)