# QuestCard

A cross-platform React card component for displaying quest or mission items with progress tracking, state-driven visuals, and reward tags. Perfect for gamification systems, daily challenges, and achievement displays.

## Installation

```bash
npm install @xsolla/xui-quest-card
```

## Demo

### Basic QuestCard

```tsx
import * as React from "react";
import { QuestCard } from "@xsolla/xui-quest-card";
import { Flag } from "@xsolla/xui-icons-base";

export default function BasicQuestCard() {
  return (
    <QuestCard
      title="Play any game"
      description="With Play Time Rewards On"
      caption="0/12 hours"
      questState="default"
      icon={<Flag />}
    />
  );
}
```

### QuestCard States

```tsx
import * as React from "react";
import { QuestCard } from "@xsolla/xui-quest-card";
import { Tag } from "@xsolla/xui-tag";
import { Flag, CheckCr, Clock } from "@xsolla/xui-icons-base";
import { XsollaPoint } from "@xsolla/xui-icons-currency";

export default function QuestCardStates() {
  const reward = (
    <Tag size="sm" tone="secondary" icon={<XsollaPoint />}>
      +50
    </Tag>
  );

  return (
    <div style={{ display: "flex", flexDirection: "column", gap: 8 }}>
      {/* Default — active quest */}
      <QuestCard
        title="Play any game"
        description="With Play Time Rewards On"
        caption="0/12 hours"
        questState="default"
        icon={<Flag />}
        trailing={reward}
      />

      {/* Expiring — urgent quest with badge */}
      <QuestCard
        title="Reach level 10"
        description="Level up to unlock rewards"
        caption="7/10"
        questState="expiring"
        icon={<Flag />}
        trailing={reward}
      />

      {/* Completed — dimmed at 48% opacity */}
      <QuestCard
        title="Complete daily login"
        description="Login every day"
        caption="Completed"
        questState="completed"
        icon={<CheckCr />}
        trailing={reward}
      />

      {/* Expired — dimmed at 48% opacity */}
      <QuestCard
        title="Invite 3 friends"
        description="Share your referral link"
        caption="Expired"
        questState="expired"
        icon={<Clock />}
        trailing={reward}
      />
    </div>
  );
}
```

### Without Description or Caption

```tsx
import * as React from "react";
import { QuestCard } from "@xsolla/xui-quest-card";
import { Flag } from "@xsolla/xui-icons-base";

export default function MinimalQuestCard() {
  return (
    <QuestCard title="Simple quest" questState="default" icon={<Flag />} />
  );
}
```

### Quest List

```tsx
import * as React from "react";
import { QuestCard } from "@xsolla/xui-quest-card";
import { Tag } from "@xsolla/xui-tag";
import { Flag, CheckCr, Clock } from "@xsolla/xui-icons-base";
import { XsollaPoint } from "@xsolla/xui-icons-currency";

export default function QuestList() {
  const reward = (
    <Tag size="sm" tone="secondary" icon={<XsollaPoint />}>
      +50
    </Tag>
  );

  return (
    <div style={{ display: "flex", flexDirection: "column", gap: 8 }}>
      <QuestCard
        title="Play any game"
        description="With Play Time Rewards On"
        caption="0/12 hours"
        questState="default"
        icon={<Flag />}
        trailing={reward}
        onPress={() => console.log("Quest 1 clicked")}
      />
      <QuestCard
        title="Complete daily login"
        description="Login every day"
        caption="Completed"
        questState="completed"
        icon={<CheckCr />}
        trailing={reward}
      />
      <QuestCard
        title="Invite 3 friends"
        description="Share your referral link"
        caption="Expired"
        questState="expired"
        icon={<Clock />}
        trailing={reward}
      />
      <QuestCard
        title="Reach level 10"
        description="Level up to unlock rewards"
        caption="7/10"
        questState="expiring"
        icon={<Flag />}
        trailing={reward}
        onPress={() => console.log("Quest 4 clicked")}
      />
    </div>
  );
}
```

## Anatomy

Import the component and use it directly:

```jsx
import { QuestCard } from "@xsolla/xui-quest-card";

<QuestCard
  title="Quest Title" // Required: Quest name
  description="Description" // Optional: Secondary text
  caption="0/100" // Optional: Progress or status text
  questState="default" // Optional: Visual state
  icon={<Flag />} // Optional: Quest icon
  trailing={<Tag />} // Optional: Reward/action content
  onPress={() => {}} // Optional: Card press handler
/>;
```

## API Reference

### QuestCard

A card component for displaying quest or mission items.

**QuestCard Props:**

| Prop        | Type                                                  | Default     | Description                                                                                                   |
| :---------- | :---------------------------------------------------- | :---------- | :------------------------------------------------------------------------------------------------------------ |
| `testID`    | `string`                                              | —           | Test ID for testing frameworks. On web this renders as `data-testid`; on React Native it renders as `testID`. |
| title       | `string`                                              | required    | Quest title text.                                                                                             |
| description | `string`                                              | -           | Secondary description text below the title.                                                                   |
| caption     | `string`                                              | -           | Bottom caption text (e.g. "0/100", "Completed", "Expired").                                                   |
| questState  | `"default" \| "completed" \| "expired" \| "expiring"` | `"default"` | Visual quest state controlling opacity, border, and badge.                                                    |
| icon        | `ReactNode`                                           | -           | Icon to display in the icon container.                                                                        |
| trailing    | `ReactNode`                                           | -           | Reward tag or custom trailing content.                                                                        |
| onPress     | `() => void`                                          | -           | Card press handler.                                                                                           |
| className   | `string`                                              | -           | Custom className for the container.                                                                           |
| testID      | `string`                                              | -           | Test ID for testing.                                                                                          |

**Quest States:**

| State     | Description                                                                   |
| :-------- | :---------------------------------------------------------------------------- |
| default   | Active quest with border, full opacity                                        |
| completed | Completed quest, 48% opacity, no border                                       |
| expired   | Expired quest, 48% opacity, no border                                         |
| expiring  | Urgent quest with border, full opacity, and a red lightning badge on the icon |

**Recommended icons per state:**

| State     | Icon                                        |
| :-------- | :------------------------------------------ |
| default   | `<Flag />` from `@xsolla/xui-icons-base`    |
| completed | `<CheckCr />` from `@xsolla/xui-icons-base` |
| expired   | `<Clock />` from `@xsolla/xui-icons-base`   |
| expiring  | `<Flag />` from `@xsolla/xui-icons-base`    |

### Deprecated Props

These props still work but will emit console warnings in development:

| Prop       | Replacement   | Mapping                                                                           |
| :--------- | :------------ | :-------------------------------------------------------------------------------- |
| subtitle   | `description` | Direct alias                                                                      |
| status     | `questState`  | "success" -> "completed", "warning"/"alert" -> "expiring", "default" -> "default" |
| statusIcon | `questState`  | No longer rendered; visual state driven by `questState`                           |

## Migration from v1

```diff
 <QuestCard
   title="Play any game"
-  subtitle="0/12 hours"
+  description="With Play Time Rewards On"
+  caption="0/12 hours"
   icon={<Flag />}
-  status="warning"
-  statusIcon={<AlertCircle />}
+  questState="expiring"
   trailing={<Tag>+50</Tag>}
 />
```

## Accessibility

- Uses semantic HTML structure
- Interactive cards support keyboard navigation
- Quest state visuals provide clear feedback (opacity, border, badge)
- Supports custom `onPress` for full card interaction
- Includes `testID` prop for testing