@quadcore-lib/storefront-ui

Componentes React listos para un storefront: ProductCard, ProductGrid, CartDrawer, CheckoutForm, OrderTracker. Construidos sobre los hooks de @quadcore-lib/storefront-core — este paquete es opcional y opinado, para proyectos que quieran arrancar con UI en vez de armarla desde cero con los hooks solos.

Instalación

npm install @quadcore-lib/storefront-ui @quadcore-lib/storefront-core

Uso

import { useState } from "react";
import { ProductGrid, CartDrawer, CheckoutForm, OrderTracker } from "@quadcore-lib/storefront-ui";

const API_URL = "https://api.mitienda.com";

function Storefront() {
  const [cartOpen, setCartOpen] = useState(false);
  const [checkingOut, setCheckingOut] = useState(false);
  const [orderId, setOrderId] = useState<string>();

  if (orderId) return <OrderTracker apiUrl={API_URL} orderId={orderId} />;

  if (checkingOut) {
    return <CheckoutForm apiUrl={API_URL} onSuccess={(order) => setOrderId(order.id)} />;
  }

  return (
    <>
      <button onClick={() => setCartOpen(true)}>Ver carrito</button>
      <ProductGrid apiUrl={API_URL} />
      <CartDrawer
        open={cartOpen}
        onClose={() => setCartOpen(false)}
        onCheckout={() => setCheckingOut(true)}
      />
    </>
  );
}

API

| Componente | Props | Descripción | |---|---|---| | ProductCard | product, onAddToCart?, className? | Tarjeta de un producto; sin onAddToCart no muestra botón (catálogo solo-lectura) | | ProductGrid | apiUrl, params?, onAddToCart?, className? | Pide useProducts internamente y renderiza una grilla de ProductCard | | CartDrawer | open, onClose, onCheckout?, className? | Lee/escribe el carrito vía useCart() — no recibe items por props | | CheckoutForm | apiUrl, onSuccess?, className? | Toma los items de useCart(), llama useCheckout(apiUrl) y vacía el carrito al confirmar | | OrderTracker | apiUrl, orderId, options?, className? | Stepper con el estado de la orden vía useOrderStatus (polling) |

Estilos

Todos los elementos usan clases con el prefijo qc- (qc-product-card, qc-cart-drawer, qc-checkout-form, qc-order-tracker, etc., ver el código de cada componente para la lista completa de sub-clases) y no traen CSS propio — el proyecto consumidor las estiliza (con CSS plano, Tailwind, CSS Modules, lo que use). className en cada componente se combina con la clase base vía cn de @quadcore-lib/core (no hace tailwind-merge, ver su propio README).

Gap conocido: OrderTracker

Hereda el mismo gap que useOrderStatus en @quadcore-lib/storefront-core: GET /orders/:id es admin-only en orders-server hoy. Ver el README de ese paquete, sección "Gap conocido: seguimiento de orden", para las opciones de cómo resolverlo del lado del backend antes de usar OrderTracker con clientes no-admin.

Requisitos

• react >= 18, react-dom >= 18 (peer).
• @quadcore-lib/storefront-core ^0.1.0 (peer — provee los hooks que estos componentes consumen).
• @quadcore-lib/core ^0.1.5 (dependency — provee cn).