@xsolla/xui-quest-card 0.118.0 → 0.119.0

package/README.md

@@ -1,6 +1,6 @@
 # QuestCard
 
-A cross-platform React card component for displaying quest or mission items with progress tracking, status indicators, and reward tags. Perfect for gamification systems, daily challenges, and achievement displays.
+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
 
@@ -23,135 +23,142 @@ export default function BasicQuestCard() {
   return (
     <QuestCard
       title="Play any game"
-      subtitle="0/12 hours"
+      description="With Play Time Rewards On"
+      caption="0/12 hours"
+      questState="default"
       icon={<Flag />}
     />
   );
 }
 ```
 
-### QuestCard with Status and Rewards
+### QuestCard States
 
 ```tsx
 import * as React from 'react';
 import { QuestCard } from '@xsolla/xui-quest-card';
 import { Tag } from '@xsolla/xui-tag';
-import { AlertCircle } from '@xsolla/xui-icons';
 import { Flag, CheckCr, Clock } from '@xsolla/xui-icons-base';
 import { XsollaPoint } from '@xsolla/xui-icons-currency';
 
-export default function QuestCardWithStatus() {
-  return (
-    <QuestCard
-      title="Play any game (with Play Time Rewards On)"
-      subtitle="0/12 hours"
-      icon={<Flag />}
-      status="alert"
-      statusIcon={<AlertCircle />}
-      trailing={
-        <Tag size="sm" tone="secondary" icon={<XsollaPoint />}>
-          5x
-        </Tag>
-      }
-    />
+export default function QuestCardStates() {
+  const reward = (
+    <Tag size="sm" tone="secondary" icon={<XsollaPoint />}>+50</Tag>
   );
-}
-```
-
-### QuestCard Status Variants
-
-```tsx
-import * as React from 'react';
-import { QuestCard } from '@xsolla/xui-quest-card';
-import { Tag } from '@xsolla/xui-tag';
-import { AlertCircle } from '@xsolla/xui-icons';
-import { Flag, CheckCr, Clock } from '@xsolla/xui-icons-base';
-import { XsollaPoint, XsollaTicket } from '@xsolla/xui-icons-currency';
 
-export default function QuestCardStatuses() {
   return (
     <div style={{ display: 'flex', flexDirection: 'column', gap: 8 }}>
-      {/* Alert Status */}
+      {/* Default — active quest */}
       <QuestCard
-        title="Urgent quest"
-        subtitle="Expires in 1 hour"
+        title="Play any game"
+        description="With Play Time Rewards On"
+        caption="0/12 hours"
+        questState="default"
         icon={<Flag />}
-        status="alert"
-        statusIcon={<AlertCircle />}
-        trailing={<Tag size="sm" tone="alert">Urgent</Tag>}
+        trailing={reward}
       />
 
-      {/* Warning Status */}
+      {/* Expiring — urgent quest with badge */}
       <QuestCard
-        title="Expiring soon"
-        subtitle="2 hours left"
-        icon={<Clock />}
-        status="warning"
-        statusIcon={<AlertCircle />}
-        trailing={<Tag size="sm" tone="warning">Soon</Tag>}
+        title="Reach level 10"
+        description="Level up to unlock rewards"
+        caption="7/10"
+        questState="expiring"
+        icon={<Flag />}
+        trailing={reward}
       />
 
-      {/* Success Status */}
+      {/* Completed — dimmed at 48% opacity */}
       <QuestCard
-        title="Completed quest"
-        subtitle="1/1 done"
+        title="Complete daily login"
+        description="Login every day"
+        caption="Completed"
+        questState="completed"
         icon={<CheckCr />}
-        status="success"
-        statusIcon={<CheckCr />}
-        trailing={<Tag size="sm" tone="success">Done</Tag>}
+        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 { AlertCircle } from '@xsolla/xui-icons';
-import { Flag, CheckCr } from '@xsolla/xui-icons-base';
-import { XsollaPoint, XsollaTicket } from '@xsolla/xui-icons-currency';
+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"
-        subtitle="0/12 hours"
+        description="With Play Time Rewards On"
+        caption="0/12 hours"
+        questState="default"
         icon={<Flag />}
-        status="alert"
-        statusIcon={<AlertCircle />}
-        trailing={<Tag size="sm" tone="secondary" icon={<XsollaPoint />}>5x</Tag>}
+        trailing={reward}
         onPress={() => console.log('Quest 1 clicked')}
       />
       <QuestCard
         title="Complete daily login"
-        subtitle="1/1 completed"
+        description="Login every day"
+        caption="Completed"
+        questState="completed"
         icon={<CheckCr />}
-        status="success"
-        statusIcon={<CheckCr />}
-        trailing={<Tag size="sm" tone="success">Done</Tag>}
+        trailing={reward}
       />
       <QuestCard
         title="Invite 3 friends"
-        subtitle="1/3 invited"
-        icon={<Flag />}
-        trailing={<Tag size="sm" tone="brand" icon={<XsollaTicket />}>500</Tag>}
-        onPress={() => console.log('Quest 3 clicked')}
+        description="Share your referral link"
+        caption="Expired"
+        questState="expired"
+        icon={<Clock />}
+        trailing={reward}
       />
       <QuestCard
         title="Reach level 10"
-        subtitle="Level 7/10"
+        description="Level up to unlock rewards"
+        caption="7/10"
+        questState="expiring"
         icon={<Flag />}
-        trailing={
-          <div style={{ display: 'flex', gap: 4 }}>
-            <Tag size="sm" tone="brand" icon={<XsollaPoint />}>100</Tag>
-            <Tag size="sm" tone="secondary">2x</Tag>
-          </div>
-        }
+        trailing={reward}
+        onPress={() => console.log('Quest 4 clicked')}
       />
     </div>
   );
@@ -166,13 +173,13 @@ Import the component and use it directly:
 import { QuestCard } from '@xsolla/xui-quest-card';
 
 <QuestCard
-  title="Quest Title"        // Required: Quest name
-  subtitle="0/10 progress"   // Optional: Progress text
-  icon={<Flag />}            // Optional: Quest icon
-  status="alert"             // Optional: Status indicator
-  statusIcon={<AlertCircle />} // Optional: Custom status icon
-  trailing={<Tag />}         // Optional: Reward/action content
-  onPress={() => {}}         // Optional: Card press handler
+  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
 />
 ```
 
@@ -187,43 +194,75 @@ A card component for displaying quest or mission items.
 | Prop | Type | Default | Description |
 | :--- | :--- | :------ | :---------- |
 | title | `string` | required | Quest title text. |
-| subtitle | `string` | - | Quest progress or description (e.g., "0/12 hours"). |
+| 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. |
-| status | `"default" \| "alert" \| "warning" \| "success"` | - | Status indicator type. |
-| statusIcon | `ReactNode` | - | Custom status icon (overrides default status indicator). |
 | 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. |
 
-**Status Types:**
+**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 |
 
-| Status | Description |
-| :----- | :---------- |
-| default | No special status styling |
-| alert | Red/alert color for urgent quests |
-| warning | Yellow/warning color for expiring quests |
-| success | Green/success color for completed quests |
+**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` |
 
 ## Theming
 
 QuestCard uses the design system theme for colors:
 
 ```typescript
-// Colors accessed via theme
-theme.colors.background.primary  // Card background
-theme.colors.content.primary     // Title text
-theme.colors.content.tertiary    // Subtitle text
-theme.colors.content.alert       // Alert status color
-theme.colors.content.warning     // Warning status color
-theme.colors.content.success     // Success status color
-theme.colors.overlay.mono        // Icon container background
+theme.colors.overlay.mono            // Card background
+theme.colors.border.secondary        // Card border (default/expiring only)
+theme.colors.content.primary         // Title text
+theme.colors.content.tertiary        // Description and caption text
+theme.colors.content.alert.secondary // Expiring badge color
+```
+
+## 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
-- Status icons provide visual feedback
+- Quest state visuals provide clear feedback (opacity, border, badge)
 - Supports custom `onPress` for full card interaction
 - Includes `testID` prop for testing

package/native/index.d.mts

@@ -1,17 +1,19 @@
 import React from 'react';
 
+/** @deprecated Use `QuestCardState` instead. */
 type QuestCardStatus = "default" | "alert" | "warning" | "success";
+type QuestCardState = "default" | "completed" | "expired" | "expiring";
 interface QuestCardProps {
     /** Quest title text */
     title: string;
-    /** Quest progress or description (e.g., "0/12 hours") */
-    subtitle?: string;
+    /** Secondary description text displayed below the title */
+    description?: string;
+    /** Bottom caption text (e.g. "0/100", "Completed", "Expired") */
+    caption?: string;
+    /** Visual quest state controlling opacity, border, and badge */
+    questState?: QuestCardState;
     /** Icon to display in the icon container */
     icon?: React.ReactNode;
-    /** Status indicator - shows an icon next to the title */
-    status?: QuestCardStatus;
-    /** Custom status icon (overrides default status icons) */
-    statusIcon?: React.ReactNode;
     /** Reward tag or custom trailing content */
     trailing?: React.ReactNode;
     /** Card press handler */
@@ -20,8 +22,21 @@ interface QuestCardProps {
     className?: string;
     /** Test ID for testing */
     testID?: string;
+    /**
+     * @deprecated Use `description` instead. Maps directly to `description`.
+     */
+    subtitle?: string;
+    /**
+     * @deprecated Use `questState` instead.
+     * "success" maps to "completed", "warning"/"alert" map to "expiring", "default" maps to "default".
+     */
+    status?: QuestCardStatus;
+    /**
+     * @deprecated No longer used in the redesigned component. Use `questState` to control visual state.
+     */
+    statusIcon?: React.ReactNode;
 }
 
 declare const QuestCard: React.FC<QuestCardProps>;
 
-export { QuestCard, type QuestCardProps, type QuestCardStatus };
+export { QuestCard, type QuestCardProps, type QuestCardState, type QuestCardStatus };

package/native/index.d.ts

@@ -1,17 +1,19 @@
 import React from 'react';
 
+/** @deprecated Use `QuestCardState` instead. */
 type QuestCardStatus = "default" | "alert" | "warning" | "success";
+type QuestCardState = "default" | "completed" | "expired" | "expiring";
 interface QuestCardProps {
     /** Quest title text */
     title: string;
-    /** Quest progress or description (e.g., "0/12 hours") */
-    subtitle?: string;
+    /** Secondary description text displayed below the title */
+    description?: string;
+    /** Bottom caption text (e.g. "0/100", "Completed", "Expired") */
+    caption?: string;
+    /** Visual quest state controlling opacity, border, and badge */
+    questState?: QuestCardState;
     /** Icon to display in the icon container */
     icon?: React.ReactNode;
-    /** Status indicator - shows an icon next to the title */
-    status?: QuestCardStatus;
-    /** Custom status icon (overrides default status icons) */
-    statusIcon?: React.ReactNode;
     /** Reward tag or custom trailing content */
     trailing?: React.ReactNode;
     /** Card press handler */
@@ -20,8 +22,21 @@ interface QuestCardProps {
     className?: string;
     /** Test ID for testing */
     testID?: string;
+    /**
+     * @deprecated Use `description` instead. Maps directly to `description`.
+     */
+    subtitle?: string;
+    /**
+     * @deprecated Use `questState` instead.
+     * "success" maps to "completed", "warning"/"alert" map to "expiring", "default" maps to "default".
+     */
+    status?: QuestCardStatus;
+    /**
+     * @deprecated No longer used in the redesigned component. Use `questState` to control visual state.
+     */
+    statusIcon?: React.ReactNode;
 }
 
 declare const QuestCard: React.FC<QuestCardProps>;
 
-export { QuestCard, type QuestCardProps, type QuestCardStatus };
+export { QuestCard, type QuestCardProps, type QuestCardState, type QuestCardStatus };