npm package: @stake-sdk/ui
Description: Credit Builder Tracker widget for React Native (Expo) with Material Design 3 theming
Latest version: 1.0.6

# @stake-sdk/ui

Stake UI SDK for React Native (Expo): Credit Builder flow, Credit Builder Tracker, and shared Stake runtime helpers. Theming uses Material Design 3 via `react-native-paper`.

## Installation

```bash
npm install @stake-sdk/ui react-native-paper @tanstack/react-query axios
# or
yarn add @stake-sdk/ui react-native-paper @tanstack/react-query axios
```

**Peer dependencies** (must be present in your app): `react` (≥18), `react-native` (≥0.70), `react-native-paper` (≥5).

**Other runtime deps** used by this package: `@tanstack/react-query`, `axios`. The `CreditBuilder` entry point also uses `@expo/vector-icons` (standard in Expo apps).

## Setup

Call `Stake.open` once (e.g. in a root layout or screen `useEffect`) before widgets that hit Stake APIs:

```tsx
import { Stake } from "@stake-sdk/ui";

await Stake.open({
  environment: "development", // or your supported environment key
  clientId: "<client-id>",
  clientSecret: "<client-secret>",
});
```

## Usage

### Credit Builder Tracker

```tsx
import { CreditBuilderTracker } from "@stake-sdk/ui";
import { useTheme } from "react-native-paper";

function MyScreen() {
  const theme = useTheme();
  return (
    <CreditBuilderTracker theme={theme} residentId="<resident-id>" />
  );
}
```

Or with `withTheme`:

```tsx
import { CreditBuilderTracker } from "@stake-sdk/ui";
import { withTheme } from "react-native-paper";
import type { MD3Theme } from "react-native-paper";

function MyScreen({ theme }: { theme: MD3Theme }) {
  return <CreditBuilderTracker theme={theme} residentId="<resident-id>" />;
}

export default withTheme(MyScreen);
```

### Credit Builder (full flow)

```tsx
import { CreditBuilder } from "@stake-sdk/ui";

<CreditBuilder residentId="<resident-id>" />
```

### Theming helpers

```tsx
import { StakeLightTheme, StakeDarkTheme } from "@stake-sdk/ui";
```

## Exports

| Export | Description |
|--------|-------------|
| `Stake` | `Stake.open(config)` — initialize SDK / auth for the session |
| `StakeConfig` | Type for `Stake.open` configuration |
| `CreditBuilderTracker` | Tracker UI (requires `theme`, `residentId`) |
| `CreditBuilder` | Full credit-builder flow UI |
| `StakeLightTheme` / `StakeDarkTheme` | Paper-compatible theme objects |

## Props

### `CreditBuilderTracker`

| Prop        | Type       | Required | Description |
|------------|------------|----------|-------------|
| `theme`    | `MD3Theme` | Yes      | Material Design 3 theme from `react-native-paper` |
| `residentId` | `string` | Yes   | Resident identifier for API calls |

### `CreditBuilder`

| Prop         | Type     | Required | Description |
|--------------|----------|----------|-------------|
| `residentId` | `string` | Yes      | Resident identifier for API calls |

## Publishing (for maintainers)

Package name: **`@stake-sdk/ui`**. Source lives under **`packages/stake-sdk/`**.

From the **monorepo root**:

| Script | Description |
|--------|-------------|
| `npm run build:packages` | Build the UI package (output in `packages/stake-sdk/dist/`). |
| `npm run version:tracker:patch` | Bump patch version. Creates a git commit and tag in the workspace package. |
| `npm run version:tracker:minor` | Bump minor version. |
| `npm run version:tracker:major` | Bump major version. |
| `npm run publish:tracker` | Build and publish the current version to npm. |
| `npm run release:tracker:patch` | Build, bump patch, then publish. |
| `npm run release:tracker:minor` | Build, bump minor, then publish. |
| `npm run release:tracker:major` | Build, bump major, then publish. |

From **`packages/stake-sdk`**:

```bash
npm run build
npm run publish:package   # npm publish --access public
```

**One-step release from root (example — patch):**

```bash
npm run release:tracker:patch
```

Ensure you are logged in (`npm login`) with publish access to the **`@stake-sdk`** scope, and use `--access public` for the first scoped publish. To change the npm name or scope, edit `name` in `packages/stake-sdk/package.json`.