npm package: @huitzo/dashboard-sdk-react
Description: React hooks and components for Huitzo Dashboard SDK
Latest version: 2.0.1

# @huitzo/dashboard-sdk-react

React hooks and components for building Huitzo Dashboards. Wraps the core `@huitzo/dashboard-sdk` client with React context, command execution hooks, and reusable UI components.

Dashboards always run inside Huitzo Hub — the provider requires a mount context from Hub's `mount()` call.

## Installation

```bash
npm install @huitzo/dashboard-sdk @huitzo/dashboard-sdk-react
```

## Quick Start

```tsx
import type { HuitzoMountContext } from '@huitzo/dashboard-sdk-react';
import { HuitzoProvider } from '@huitzo/dashboard-sdk-react';
import { createRoot } from 'react-dom/client';
import { App } from './App';

export function mount(container: HTMLElement, context: HuitzoMountContext) {
  const root = createRoot(container);
  root.render(
    <HuitzoProvider context={context}>
      <App />
    </HuitzoProvider>
  );
}
```

## Hooks

### useHuitzo

Access the client instance and auth state.

Returns: `{ client, user, isAuthenticated, mountContext, isPackInstalled }`

```tsx
import { useHuitzo } from '@huitzo/dashboard-sdk-react';

function MyComponent() {
  const { client, user, isAuthenticated, mountContext, isPackInstalled } = useHuitzo();
}
```

### useCommand

Execute Intelligence Pack commands with loading/error state.

Returns: `{ execute, data, loading, error, reset, status, isIdle, isSuccess, isError }`

Options: `onSuccess`, `onError`, `cacheTime`, `initialArgs`

```tsx
import { useCommand } from '@huitzo/dashboard-sdk-react';

function ProcessClaim() {
  const { execute, data, loading, error } = useCommand<ClaimResult>(
    '@acme/claims/process-claim',
  );

  return (
    <button onClick={() => execute({ claimId: 'CLM-123' })} disabled={loading}>
      {loading ? 'Processing...' : 'Process Claim'}
    </button>
  );
}
```

### useHubContext

Read Hub environment info (theme, user, dashboard slug). Theme is reactive — updates when Hub toggles the theme.

Returns: `{ hubUrl, dashboardSlug, user, theme }`

```tsx
import { useHubContext } from '@huitzo/dashboard-sdk-react';

function Header() {
  const { dashboardSlug, theme } = useHubContext();
  return <span>Dashboard: {dashboardSlug} ({theme})</span>;
}
```

### useHubNavigation

Programmatic navigation within Hub.

Returns: `{ navigateToHub, navigateToDashboard, navigateToExplore, navigateToSettings, currentDashboard }`

```tsx
import { useHubNavigation } from '@huitzo/dashboard-sdk-react';

function BackButton() {
  const { navigateToHub, navigateToDashboard } = useHubNavigation();
  return <button onClick={navigateToHub}>Back to Hub</button>;
}
```

### usePacks

Query installed Intelligence Packs.

Returns: `{ packs, loading, error, isInstalled, refetch }`

```tsx
import { usePacks } from '@huitzo/dashboard-sdk-react';

function PackList() {
  const { packs, loading, error, isInstalled, refetch } = usePacks();

  if (loading) return <p>Loading packs...</p>;
  if (error) return <p>Error: {error.message}</p>;

  return (
    <ul>
      {packs.map(pack => (
        <li key={pack.id}>{pack.name} (v{pack.version})</li>
      ))}
    </ul>
  );
}
```

### Stub Hooks (not yet implemented)

These hooks are exported but throw `HuitzoError` on invocation. They will be implemented when their underlying SDK features are ready.

- **`useConnectionStatus`** — Track WebSocket connection status. Will return `{ status, isConnected, reconnect }`.
- **`useHubActions`** — Trigger Hub-level UI actions (notifications, dialogs, settings). Will return `{ showNotification, showConfirmDialog, openSettings }`.
- **`useHubBreadcrumbs`** — Communicate breadcrumb state to the Hub shell. Accepts `BreadcrumbItem[]`.
- **`useRealtime`** — Subscribe to real-time platform events. Accepts `(event, callback)`.

## Components

### DashboardInfoBlock

Displays a titled info block with optional description, icon, and metadata.

```tsx
import { DashboardInfoBlock } from '@huitzo/dashboard-sdk-react';

<DashboardInfoBlock
  title="Claims Overview"
  description="Real-time claims processing dashboard"
  icon="📊"
  metadata={[{ label: 'Status', value: 'Active' }]}
/>
```

### DashboardTile

A clickable tile for dashboard navigation or actions. Requires exactly one of `onClick` or `href`.

```tsx
import { DashboardTile } from '@huitzo/dashboard-sdk-react';

<DashboardTile
  name="Process Claims"
  description="Review and process pending claims"
  icon="📋"
  onClick={() => navigate('/claims')}
/>
```

## Design Tokens

Import the CSS tokens for Hub-consistent styling:

```css
@import '@huitzo/dashboard-sdk-react/styles';
```

## Development

```bash
npm run build     # Build ESM + CJS + DTS
npm run test      # Run unit tests
npm run lint      # Run biome
npm run dev       # Watch mode
```

## License

MIT