@queelabs/ui

React primitives for payment-required, receipt, settlement, and checkout shell UI on top of @queelabs/sdk or direct /v1 calls. The bridge pattern (wallet/card slots) keeps your app in charge of wagmi, Stripe Elements, etc., while Quee stays headless.

Quee: https://quee.one

Layout follows a shadcn-style mental model: lib/ for shared utilities and types, components/ for one file per primitive (kebab-case filenames), and a single barrel export from @queelabs/ui.

Package layout

src/
  lib/
    utils.ts      # cx / cn (Tailwind class merging)
    theme.ts      # appearance presets, surface/button/badge classes, format helpers
    models.ts     # view-model types (bridges, 402-shaped props)
    checkout-config.ts # typed checkout presets/config helpers
  components/
    quee-checkout.tsx
    checkout-page-shell.tsx
    payment-method-picker.tsx
    payment-requirement-card.tsx
    receipt-card.tsx
    settlement-card.tsx
    listing-card.tsx
    checkout-panel.tsx
    transaction-timeline.tsx
    transaction-status-badge.tsx
    qhash-badge.tsx
    agent-payment-card.tsx
  index.ts        # public API

Imports

• Everything: import { QueeCheckout, defineCheckoutUi, cn } from "@queelabs/ui"
• Deep paths (optional, mirrors shadcn lib/utils):
  import { cn } from "@queelabs/ui/lib/utils"
import type { CheckoutSessionViewModel } from "@queelabs/ui/lib/models"

Integrator path (recommended)

Use a typed config file and one top-level component:

1. Add a route or modal in your app.
2. After purchase / startCheckout, map Quee data into the …ViewModel types.
3. Create a checkout-ui.ts file with defineCheckoutUi(...).
4. Render QueeCheckout and pass the session, bridges, and config.
5. Only drop down to the lower-level primitives if you truly need a custom composition.

What it is for

• Rendering payment requirements and method selection
• Wiring wallet and card bridge contracts into a branded checkout page
• Showing receipt details and qhash, settlement status, agent payment bundles
• Building transaction flows on top of @queelabs/sdk or the Quee HTTP API

What it is not for

• Owning your storefront, nav, or catalog UX
• Replacing your app shell

Primitives (components)

| File | Export | |------|--------| | quee-checkout | QueeCheckout | | listing-card | ListingCard | | checkout-panel | CheckoutPanel | | checkout-page-shell | CheckoutPageShell | | payment-method-picker | PaymentMethodPicker | | payment-requirement-card | PaymentRequirementCard | | receipt-card | ReceiptCard | | settlement-card | SettlementCard | | transaction-status-badge | TransactionStatusBadge | | transaction-timeline | TransactionTimeline | | qhash-badge | QhashBadge | | agent-payment-card | AgentPaymentCard |

lib exports (from @queelabs/ui)

• cx / cn — combine class names ( cn is an alias for shadcn familiarity).
• Theme: surfaceClass, insetClass, buttonClass, toneBadgeClass, textClass, mutedTextClass, …
• Helpers: humanize, shortHash, moneyLabel, readString, readRecord, …
• Checkout config: defineCheckoutUi, resolveCheckoutUiConfig
• Types: re-exported from root; see lib/models.ts for bridge and view-model definitions.

Visual presets (QueeAppearance)

neutral, accent, ghost, quee-glass — passed as appearance on components.

Recommended example

import {
  QueeCheckout,
  defineCheckoutUi,
  type CheckoutMethodOption,
  type CheckoutSessionViewModel,
} from "@queelabs/ui";

export const checkoutUi = defineCheckoutUi({
  preset: "storefront",
  sections: {
    challengeSummary: false,
    agent: false,
  },
  texts: {
    shellTitle: "Complete your order",
  },
});

const session: CheckoutSessionViewModel = {
  orderId: "ord_123",
  qtxId: "qtx_123",
  status: "payment_required",
  amountMinor: 2500,
  currency: "usd",
  selectedMethod: "wallet",
};
const methods: CheckoutMethodOption[] = [
  {
    id: "wallet",
    label: "Wallet",
    description: "Connect buyer wallet and pay with crypto rails.",
  },
];

<QueeCheckout
  config={checkoutUi}
  session={session}
  requirement={requirement}
  methodOptions={methods}
  selectedMethod="wallet"
  walletBridge={{
    kind: "wallet",
    provider: "tempo",
    label: "Tempo wallet bridge",
  }}
  receipt={receipt}
  settlement={settlement}
/>

When to use the lower-level primitives

Drop down from QueeCheckout only when you need one of these:

• a completely custom layout
• only one isolated card, such as ReceiptCard
• a split-screen or modal composition your app already owns
• custom timeline or action placement

Forking / vendoring

If you later copy primitives into your app (like shadcn “eject”), start from src/components/*.tsx and src/lib/*; keep models.ts types aligned with @queelabs/protocol / SDK view-models.