Copiar para IA

React e Next.js

Primitivas headless poderosas e componentes pré-estilizados para o seu frontend React.

Instalação

Verifique se você instalou o pacote no seu projeto.

npm install @flouviahq/elements

O provider: <CordProvider>

Para usar qualquer componente ou hook de React fornecido pelo SDK, a sua aplicação (ou a parte do seu app que usa o gerador de orçamentos) precisa estar envolvida em um CordProvider.

Existem dois modos de segurança para inicializar o provider: Publishable e Proxy. Esses modos são mutuamente exclusivos; você não pode passar as duas propriedades ao mesmo tempo.

Modo Publishable (frontend direto)

Use este modo se quiser que o cliente React se comunique diretamente com a API do Cord. As chaves publicáveis (pk_live_... / pk_test_...) são bastante limitadas por segurança: podem criar orçamentos e ler o catálogo de produtos (omitindo o seu custo), mas nunca poderão ler o seu cadastro de clientes do CRM.

// app/layout.tsx
import { CordProvider } from '@flouviahq/elements/react';

export default function Layout({ children }) {
  return (
    <CordProvider publishableKey={process.env.NEXT_PUBLIC_CORD_PUBLISHABLE_KEY!}>
      {children}
    </CordProvider>
  );
}

Modo Proxy (backend intermediário)

Use este modo se não quiser expor nenhuma chave no seu cliente ou se precisar de funcionalidades que exigem chaves secretas (como ler o CRM). O SDK enviará as requisições para a rota de proxy que você indicar, e o seu backend se encarregará de reencaminhá-las para a API do Cord com a chave secreta (sk_live_...).

<CordProvider proxyUrl="/api/cord/proxy">
  {children}
</CordProvider>

---

<CordCotizador>: visualizador em iframe

Se você já tem o token de um orçamento e só quer mostrá-lo para que o cliente o aprove e o pague, use o visualizador nativo. Este componente renderiza com segurança um iframe injetado com a sua marca.

import { CordCotizador } from '@flouviahq/elements/react';

function QuotePage({ token }: { token: string }) {
  return (
    <CordCotizador
      token={token}
      onApproved={(detail) => console.log('Approved by', detail.signed_by)}
      onPay={(detail) => console.log('Payment opened at', detail.url)}
    />
  );
}

<CordInvoice>

O mesmo para uma fatura (/i/{token}). Aceita as mesmas props e acrescenta onPaid:

import { CordInvoice } from '@flouviahq/elements/react';

<CordInvoice token={invoiceToken} onPaid={(d) => console.log('Paid', d.folio)} />

No Vue, CordInvoice de @flouviahq/elements/vue emite paid.

---

<CordBuilder>: criador de orçamentos (compound)

Se você quer construir uma interface para montar novos orçamentos e aproveitar a interface padronizada do SDK, use o CordBuilder. Ele usa um padrão de componentes compostos (compound pattern), então você pode reordenar ou dispensar partes do formulário.

import { CordBuilder } from '@flouviahq/elements/react';

function NewQuote() {
  return (
    <CordBuilder onQuoteCreated={(q) => console.log('Created:', q.folio)}>
      <CordBuilder.Header />
      <CordBuilder.Items className="my-tailwind-class" />
      <CordBuilder.Summary />
      <CordBuilder.SubmitButton className="btn btn-primary" />
    </CordBuilder>
  );
}

Os componentes injetam classes CSS estáveis (.cord-*) para facilitar a sua modificação. No entanto, o Cord nunca aplica inline styles, garantindo que o seu CSS personalizado (como Tailwind ou CSS Modules) sempre tenha precedência sem precisar usar !important.

---

useQuoteBuilder: UI headless

Se o <CordBuilder> não se adaptar às necessidades exatas de design da sua interface, você pode extrair todo o motor de estado com o hook useQuoteBuilder e renderizar os botões, inputs e tabelas inteiramente por conta própria.

import { useQuoteBuilder } from '@flouviahq/elements/react';

function MyOwnBuilder() {
  const {
    items, updateItem, removeItem, subtotal, iva, total,
    cliente, setCliente, notas, setNotas,
    handleSubmit, isLoading
  } = useQuoteBuilder({
    catalog: myLocalProducts, 
    onQuoteCreated: (q) => console.log('Link:', q.link_publico),
  });

  return (
    <form onSubmit={handleSubmit}>
      {/* Construa uma interface 100% sua usando o estado do Cord */}
      <h2>Total: ${total}</h2>
      <button type="submit" disabled={isLoading}>Create</button>
    </form>
  );
}