npm package: @qubiq/web
Description: Shared React components, hooks, and utilities for QubicKit web clients (coming soon).
Latest version: 0.0.0

# QubicKit Web Components

`@qubiq/web` provides React hooks and headless UI primitives built on top of `@qubiq/core`. It helps dashboards, operations consoles, and governance tools embed live balances, tick info, and CCF proposal data without rewriting the plumbing each time.

> **Status:** first toolkit release – API may evolve as we collect feedback from integrators.

## Installation

```bash
bun add @qubiq/web @qubiq/core react react-dom
```

The package ships ESM output (Node 18+/Bun-ready) and expects React 18+ as a peer dependency.

## Usage

```tsx
import { BalanceCard, TickInfoCard, ProposalList, QubiQProvider } from "@qubiq/web";

export function Dashboard({ identity }: { identity: string }) {
  return (
    <QubiQProvider>
      <div className="grid">
        <BalanceCard identity={identity} pollIntervalMs={15_000} />
        <TickInfoCard pollIntervalMs={10_000} />
        <ProposalList status="active" pollIntervalMs={60_000} />
      </div>
    </QubiQProvider>
  );
}
```

All components and hooks accept an optional `client` prop. Pass your own `LiveServiceClient` if you
don’t want to use the provider:

```tsx
import { LiveServiceClient } from "@qubiq/core";
import { useTickInfo } from "@qubiq/web";

const client = new LiveServiceClient({ baseUrl: "https://api.qubic.org" });
const state = useTickInfo({ client });
```

### Hooks

Prefer to build your own UI? Import the hooks directly:

- `useLiveBalance` – polls `/v1/balances/:identity` and returns the parsed `BalanceRecord`.
- `useTickInfo` – polls `/v1/tick-info`.
- `useBlockHeight` – watches `/v1/block-height` and exposes the latest height.
- `useIdentityAssets` – fetches issued/owned/possessed asset lists for a given identity.
- `useCcfProposals` – fetches the latest CCF proposals using the smart-contract helper from `@qubiq/core`.
- `useContractFunctionCall` – executes any smart contract function binding returned by `useContractBinding`.

Each hook exposes `{ data, loading, error, refresh, lastUpdated }` so you can render custom states.

### Provider & Contract Hooks

When you need smart contract helpers in React, wrap your app with the `QubiQProvider`. It wires up shared clients and the `ContractToolkit` from `@qubiq/sdk`, so your components can grab them via hooks. The provider also supplies the default `LiveServiceClient` for the hooks listed above.

```tsx
import { QubiQProvider, useContractBinding, useContractFunctionCall } from "@qubiq/web";
import type { ContractName } from "@qubiq/sdk";

function App() {
  return (
    <QubiQProvider>
      <ProposalInspector />
    </QubiQProvider>
  );
}

function ProposalInspector() {
  const ccf = useContractBinding("ComputorControlledFund");
  const { data, loading } = useContractFunctionCall({
    binding: ccf,
    functionName: "GetProposal",
    params: { proposalIndex: 1 },
  });

  if (loading) return <p>Loading…</p>;
  return <pre>{JSON.stringify(data, null, 2)}</pre>;
}
```

Available helpers:

- `QubiQProvider` / `useQubiQClients` – share configured Live/Archive/Query clients.
- `useContractToolkit` / `useContractBinding` – read contract metadata and bindings.
- `useContractFunctionCall` – call any contract function and track loading/error states.

### Components

All components are “unstyled” headless cards. They output semantic markup with `qubiq-*` class names so you can attach your own design system or utility classes:

- `BalanceCard`
- `TickInfoCard`
- `ProposalList`

Pass `render*` props to override the default layout, or use the exported hooks with your own design entirely.

## Development

```
bun install
bun run build
```

The build step runs `tsc` to emit `dist/`. Linting is handled via `biome check src`.

## Next steps

Upcoming iterations will add chart-ready primitives, wallet connect helpers, and storybook examples once the core API stabilizes. Contributions and issue reports are welcome!