# CauseWise React components

`@razorsoft/causewise-react` displays analytics the host application has already loaded. It does not contain a management API key, call the CauseWise API, or import `@razorsoft/causewise`.

Install it with React 18 or newer:

```bash
npm install @razorsoft/causewise-react
```

Import the stylesheet once:

```tsx
import "@razorsoft/causewise-react/styles.css";
import { CauseWiseDashboard } from "@razorsoft/causewise-react";
```

These components do not call CauseWise and do not accept an API key.

## Component API

| Component | Data |
| --- | --- |
| `CauseWiseStats` | `pageviews`, `sessions`, `visitors` (`null` stays “Unavailable”) |
| `CauseWiseTrafficChart` | Overview `trend`: `{ label, count }[]`, where `count` is events in that bucket |
| `CauseWiseTopPages` | `{ path, count }[]` |
| `CauseWiseGoals` | Summary goal section, including `available: false` |
| `CauseWiseFunnel` | One summary funnel. Optional `steps` come from funnel analytics |
| `CauseWiseRecentEvents` | `id`, `type`, `path`, `timestamp` |
| `CauseWiseDashboard` | Composes the sections above |

Shared props: `theme` (`light`, `dark`, `system`), `state` (`ready`, `loading`, `error`), `error` (`{ code?, message }`), and `className`.

`CauseWiseDashboard` also accepts `sections` to hide a block, for example `sections={{ goals: false }}`. Omitted datasets are left out. Passing only `stats` and `trend` still renders a dashboard.

## Examples

```tsx
<CauseWiseStats
  stats={{
    pageviews: summary.pageviews,
    sessions: summary.sessions,
    sessionsNote: summary.sessionsNote,
    visitors: summary.visitors,
    visitorsNote: summary.visitorsNote,
  }}
/>

<CauseWiseTrafficChart series={{ trend: overview.trend, range: overview.range, seriesLabel: "Events" }} />

<CauseWiseDashboard
  period={summary.period}
  stats={summary}
  trend={{ trend: overview.trend, range: overview.range }}
  topPages={summary.topPages}
  goals={summary.goals}
  funnels={summary.funnels}
  recentEvents={summary.recentEvents}
/>
```

Overview `trend` counts every event in the bucket. The chart labels that series "Events". It is not a pageview or visitor series. The summary payload has no time series.

## Server-side SDK

```tsx
import { CauseWise } from "@razorsoft/causewise";
import { CauseWiseDashboard } from "@razorsoft/causewise-react";

export default async function Page() {
  const causewise = new CauseWise({ apiKey: process.env.CAUSEWISE_API_KEY! });
  const summary = await causewise.analytics.summary({ siteId: process.env.CAUSEWISE_SITE_ID!, range: "7d" });
  const overview = await causewise.analytics.overview({ siteId: process.env.CAUSEWISE_SITE_ID!, range: "7d" });
  return (
    <CauseWiseDashboard
      period={summary.period}
      stats={summary}
      trend={{ trend: overview.trend, range: overview.range }}
      topPages={summary.topPages}
      goals={summary.goals}
      funnels={summary.funnels}
      recentEvents={summary.recentEvents}
    />
  );
}
```

Run that in a Server Component or a route handler. Do not import `@razorsoft/causewise` from a client component.

For a client view, the browser calls your own authenticated route. That route checks the signed-in user, then uses the SDK. It returns the fields the components need and does not return the API key.

## Theme

Set `theme="dark"` or override the variables on `.cw-root`:

```css
.cw-root {
  --cw-bg: #f4f6f8;
  --cw-surface: #ffffff;
  --cw-text: #17202a;
  --cw-muted: #3e4c59;
  --cw-border: #d5dde6;
  --cw-accent: #0b4fad;
  --cw-font: ui-sans-serif, system-ui, sans-serif;
}
```

`theme="system"` follows `prefers-color-scheme`. Motion is removed when `prefers-reduced-motion` is set.

## Loading and errors

```tsx
<CauseWiseDashboard state="loading" />
<CauseWiseDashboard state="error" error={{ code: "subscription_required", message: "Subscription required." }} />
```

Empty arrays render an empty state. `visitors: null` and `conversionRate: null` stay unavailable. They are not shown as zero.

## Data the API does not include

- Summary responses have no traffic series. Use overview `trend`.
- Recent events omit properties.
- Summary top pages are capped at 8.
- Summary funnels do not include steps. Pass `steps` from funnel analytics to draw stages.
- Summary `conversionWindow` is the window length in seconds, such as `604800` for 7 days. `conversionWindowLabel` on funnel detail is the display text.
- There is no device, country, or browser breakdown.
- The goal summary rate is the dashboard rollup. The unique-visitor rate stays on goal analytics and is not recalculated here.

## Local demo

From the repository root, with sample data and no API key:

```bash
node packages/causewise-react/demo/serve.mjs
```

Open `http://127.0.0.1:4173`. The page shows each component, the full dashboard, light and dark themes, a narrow layout, and loading, empty, and error states.

## License

The CauseWise Client License lets you install this package, use it in commercial applications, modify the client code, and redistribute it as part of a compiled application. It does not include the CauseWise service or analytics engine. See `LICENSE`.