# Component Reference

# Android SDK: Component Reference

Complete reference for all UI components available in the Digital Card Engine SDK through the `UILibrary` object.

## High-Level Components

### CardListView

Full-featured card list with built-in ViewModel, loading states, and error handling.

```kotlin
@Composable
fun UILibrary.CardListView(
    sdk: DigitalCardEngineSDK,
    onCardSelected: (CardListItem) -> Unit = {},
    onAddCard: (() -> Unit)? = null
)
```

**Parameters**:

| Parameter        | Type                     | Required | Description                                        |
| ---------------- | ------------------------ | -------- | -------------------------------------------------- |
| `sdk`            | `DigitalCardEngineSDK`   | Yes      | Initialized SDK instance                           |
| `onCardSelected` | `(CardListItem) -> Unit` | No       | Callback when card is tapped (default: no-op)      |
| `onAddCard`      | `(() -> Unit)?`          | No       | Callback for "Add Card" button (null hides button) |

**Features**:

* Automatic card fetching via `sdk.getCards()`
* Loading indicator during fetch
* Error state with retry button
* Empty state when no cards
* "Add Card" action button (optional)
* Sorting (primary cards first)

**Example**:

```kotlin
@Composable
fun CardsScreen(sdk: DigitalCardEngineSDK, navController: NavController) {
    UILibrary.CardListView(
        sdk = sdk,
        onCardSelected = { cardItem ->
            navController.navigate("card/${cardItem.card.receivedCard.giftCardId}")
        },
        onAddCard = {
            navController.navigate("addCard")
        }
    )
}
```

***

### CardPageView

Combined card overview and transactions view for a full card details screen.

```kotlin
@Composable
fun UILibrary.CardPageView(
    sdk: DigitalCardEngineSDK,
    card: CardEntity
)
```

**Parameters**:

| Parameter | Type                   | Required | Description                        |
| --------- | ---------------------- | -------- | ---------------------------------- |
| `sdk`     | `DigitalCardEngineSDK` | Yes      | SDK instance for MCD/data fetching |
| `card`    | `CardEntity`           | Yes      | Card to display                    |

**Includes**:

* `CardOverview` with secure fields (MCD)
* `TransactionsCardView` with recent transactions
* `EventList` with card events
* Loading and error states for all sections

**Example**:

```kotlin
@Composable
fun CardDetailsScreen(
    sdk: DigitalCardEngineSDK,
    cardId: String
) {
    val card = remember { /* fetch card by ID */ }
    
    if (card != null) {
        UILibrary.CardPageView(
            sdk = sdk,
            card = card
        )
    }
}
```

***

### CardOverview

Detailed card information card with optional secure fields and action buttons.

```kotlin
@Composable
fun UILibrary.CardOverview(
    card: CardEntity,
    properties: CardOverviewProperties = CardOverviewProperties(),
    style: CardOverviewStyleProperties = CardOverviewStyleProperties(),
    styleConfiguration: StyleConfiguration = LocalStyleConfiguration.current,
    isLoading: Boolean = false,
    errorMessage: String? = null,
    onRetry: (() -> Unit)? = null,
    onDetails: (() -> Unit)? = null,
    onLock: (() -> Unit)? = null,
    onManage: (() -> Unit)? = null,
    sdk: DigitalCardEngineSDK? = null
)
```

**Key Parameters**:

| Parameter    | Type                          | Description                                       |
| ------------ | ----------------------------- | ------------------------------------------------- |
| `card`       | `CardEntity`                  | Card to display                                   |
| `properties` | `CardOverviewProperties`      | Display configuration (info level, buttons, etc.) |
| `style`      | `CardOverviewStyleProperties` | Visual styling (padding, radius, etc.)            |
| `sdk`        | `DigitalCardEngineSDK?`       | Required for MCD secure fields                    |
| `onDetails`  | `(() -> Unit)?`               | "View Details" callback (toggles MCD view)        |
| `onLock`     | `(() -> Unit)?`               | "Lock Card" callback                              |
| `onManage`   | `(() -> Unit)?`               | "Manage Card" callback                            |

**CardOverviewProperties**:

```kotlin
data class CardOverviewProperties(
    val cardInfo: CardInfo = CardInfo.Detail,          // Brief | Detail
    val actionButton: Boolean = true,
    val cardStatus: CardStatus = CardStatus.Default,    // Default | Details | Locked
    val cardWidgetStyle: CardWidgetStyle = CardWidgetStyle.Default, // Default | Large | Minimal
    val slider: Boolean = false,
    val showCardDetails: Boolean = true,
    val showActions: Boolean = true,
    val currencySymbol: String? = null
)
```

**Example**:

```kotlin
@Composable
fun CustomCardOverview(card: CardEntity, sdk: DigitalCardEngineSDK) {
    var showingDetails by remember { mutableStateOf(false) }
    
    UILibrary.CardOverview(
        card = card,
        properties = CardOverviewProperties(
            cardInfo = CardInfo.Detail,
            cardWidgetStyle = CardWidgetStyle.Large,
            actionButton = true
        ),
        style = CardOverviewStyleProperties(
            externalPadding = 16f,
            radius = 16f
        ),
        sdk = sdk,
        onDetails = { showingDetails = !showingDetails },
        onLock = { /* lock card logic */ },
        onManage = { /* navigate to settings */ }
    )
}
```

***

### TransactionsCardView

Transactions summary with built-in ViewModel and data fetching.

```kotlin
@Composable
fun UILibrary.TransactionsCardView(
    sdk: DigitalCardEngineSDK,
    card: CardEntity,
    transactionLimit: Int = 5,
    onSeeMoreClick: (() -> Unit)? = null,
    onTransactionClick: ((Transaction) -> Unit)? = null
)
```

**Parameters**:

| Parameter            | Type                       | Description                                         |
| -------------------- | -------------------------- | --------------------------------------------------- |
| `sdk`                | `DigitalCardEngineSDK`     | SDK for fetching transactions                       |
| `card`               | `CardEntity`               | Card to fetch transactions for                      |
| `transactionLimit`   | `Int`                      | Max transactions to show (default: 5)               |
| `onSeeMoreClick`     | `(() -> Unit)?`            | "See More" callback (defaults to SDK activity)      |
| `onTransactionClick` | `((Transaction) -> Unit)?` | Transaction tap callback (defaults to SDK activity) |

**Example**:

```kotlin
@Composable
fun RecentTransactions(sdk: DigitalCardEngineSDK, card: CardEntity) {
    UILibrary.TransactionsCardView(
        sdk = sdk,
        card = card,
        transactionLimit = 10,
        onSeeMoreClick = { /* navigate to full list */ },
        onTransactionClick = { txn ->
            /* navigate to transaction details */
        }
    )
}
```

***

## Lower-Level Components

### DCECardListView

Customizable card list without built-in data fetching.

```kotlin
@Composable
fun UILibrary.DCECardListView(
    cards: List<CardListItem>,
    isLoading: Boolean = false,
    errorMessage: String? = null,
    properties: CardListViewProperties = CardListViewProperties(),
    style: CardListViewStyleProperties = CardListViewStyleProperties(),
    styleConfiguration: StyleConfiguration = LocalStyleConfiguration.current,
    onCardSelected: (CardListItem) -> Unit = {},
    onAddCard: (() -> Unit)? = null,
    onRetry: (() -> Unit)? = null
)
```

**Use when**: You want full control over data fetching and state management.

**Example**:

```kotlin
@Composable
fun CustomCardList(viewModel: MyCardViewModel) {
    val cards by viewModel.cards.collectAsState()
    val isLoading by viewModel.isLoading.collectAsState()
    
    UILibrary.DCECardListView(
        cards = cards,
        isLoading = isLoading,
        properties = CardListViewProperties(
            title = true,
            cardListStyle = CardListViewStyle.LargeStyle
        ),
        style = CardListViewStyleProperties(
            radius = 16f,
            externalPadding = 20f
        ),
        onCardSelected = { cardItem ->
            viewModel.selectCard(cardItem.card)
        },
        onRetry = {
            viewModel.loadCards()
        }
    )
}
```

***

### TransactionsCard

Standalone transactions card without data fetching.

```kotlin
@Composable
fun UILibrary.TransactionsCard(
    transactions: List<Transaction>,
    isLoading: Boolean = false,
    errorMessage: String? = null,
    onRetry: (() -> Unit)? = null,
    transactionLimit: Int = 10,
    hasMoreTransactions: Boolean = false,
    onSeeMore: (() -> Unit)? = null,
    properties: TransactionsCardProperties = TransactionsCardProperties(),
    style: TransactionsCardStyleProperties = TransactionsCardStyleProperties(),
    styleConfiguration: StyleConfiguration = LocalStyleConfiguration.current
)
```

**Example**:

```kotlin
@Composable
fun TransactionsSummary(transactions: List<Transaction>) {
    UILibrary.TransactionsCard(
        transactions = transactions,
        transactionLimit = 5,
        hasMoreTransactions = transactions.size > 5,
        properties = TransactionsCardProperties(
            title = "Recent Activity",
            showTitle = true
        ),
        style = TransactionsCardStyleProperties(
            externalPadding = 16f,
            radius = 12f
        ),
        onSeeMore = { /* navigate */ }
    )
}
```

***

### TransactionList

Pure transaction list without container card.

```kotlin
@Composable
fun UILibrary.TransactionList(
    transactions: List<Transaction>,
    isLoading: Boolean = false,
    currencySymbol: String? = null,
    itemLimit: Int = 10,
    hasMoreTransactions: Boolean = false,
    onSeeMore: (() -> Unit)? = null,
    styleConfiguration: StyleConfiguration = LocalStyleConfiguration.current
)
```

**Use when**: You want to embed transactions in a custom container.

**Example**:

```kotlin
@Composable
fun CustomTransactionSection(transactions: List<Transaction>) {
    Column {
        Text("Transactions", style = MaterialTheme.typography.titleLarge)
        
        UILibrary.TransactionList(
            transactions = transactions,
            currencySymbol = "$",
            itemLimit = 20,
            hasMoreTransactions = false
        )
    }
}
```

***

### EventList

Display card lifecycle events.

```kotlin
@Composable
fun UILibrary.EventList(
    events: List<CardEvent>,
    styleConfiguration: StyleConfiguration = LocalStyleConfiguration.current
)
```

**Example**:

```kotlin
@Composable
fun CardEventsSection(events: List<CardEvent>) {
    Column {
        Text("Card Activity", style = MaterialTheme.typography.titleMedium)
        
        UILibrary.EventList(
            events = events.take(10)
        )
    }
}
```

***

### CardCarousel

Horizontal scrolling card carousel.

```kotlin
@Composable
fun UILibrary.CardCarousel(
    cards: List<CardListItem>,
    selectedIndex: Int,
    onCardClicked: (Int) -> Unit,
    onCenteredIndexChanged: ((Int) -> Unit)? = null
)
```

**Parameters**:

| Parameter                | Type                 | Description                                     |
| ------------------------ | -------------------- | ----------------------------------------------- |
| `cards`                  | `List<CardListItem>` | Cards to display                                |
| `selectedIndex`          | `Int`                | Currently selected card index                   |
| `onCardClicked`          | `(Int) -> Unit`      | Callback with tapped card index                 |
| `onCenteredIndexChanged` | `((Int) -> Unit)?`   | Callback when centered card changes (scrolling) |

**Use when**: You want a horizontal card selector/viewer.

**Example**:

```kotlin
@Composable
fun HorizontalCardSelector(cards: List<CardListItem>) {
    var selectedIndex by remember { mutableStateOf(0) }
    
    Column {
        UILibrary.CardCarousel(
            cards = cards,
            selectedIndex = selectedIndex,
            onCardClicked = { index ->
                selectedIndex = index
            },
            onCenteredIndexChanged = { index ->
                // Update when user scrolls
                selectedIndex = index
            }
        )
        
        // Show details for selected card
        Text("Selected: ${cards[selectedIndex].card.receivedCard.cardLabel}")
    }
}
```

***

### CardListItemDefaultView

Individual card list item in compact style.

```kotlin
@Composable
fun UILibrary.CardListItemDefaultView(
    card: CardListItem,
    style: CardListViewStyleProperties,
    styleConfiguration: StyleConfiguration,
    onClick: (() -> Unit)? = null,
    showOverline: Boolean = false,
    overlineText: String = "Primary card"
)
```

**Use when**: Building a custom card list with individual items.

**Example**:

```kotlin
@Composable
fun CustomCardList(cards: List<CardListItem>) {
    LazyColumn {
        items(cards) { cardItem ->
            UILibrary.CardListItemDefaultView(
                card = cardItem,
                style = CardListViewStyleProperties(),
                styleConfiguration = LocalStyleConfiguration.current,
                showOverline = cardItem.card.receivedCard.cardLabel == "Primary",
                overlineText = "Primary Card",
                onClick = { /* handle click */ }
            )
            
            Divider()
        }
    }
}
```

***

## Component Comparison

### When to use which component?

| Component              | Use Case                              | Data Fetching | State Management |
| ---------------------- | ------------------------------------- | ------------- | ---------------- |
| `CardListView`         | Quick integration, standard card list | Built-in      | Built-in         |
| `DCECardListView`      | Custom data/state logic               | Manual        | Manual           |
| `CardPageView`         | Full card details screen              | Built-in      | Built-in         |
| `CardOverview`         | Custom card details layout            | Manual        | Manual           |
| `TransactionsCardView` | Quick transaction display             | Built-in      | Built-in         |
| `TransactionsCard`     | Custom transactions with own data     | Manual        | Manual           |
| `TransactionList`      | Embed in custom container             | Manual        | Manual           |
| `CardCarousel`         | Horizontal card browser               | Manual        | Manual           |

***

## Composition Patterns

### Pattern 1: Fully Managed

Use high-level components with built-in data fetching.

```kotlin
@Composable
fun EasyIntegration(sdk: DigitalCardEngineSDK) {
    Column {
        UILibrary.CardListView(
            sdk = sdk,
            onCardSelected = { /* ... */ }
        )
    }
}
```

**Pros**: Quick, minimal code
**Cons**: Less control over state/fetching

### Pattern 2: Custom ViewModel

Use lower-level components with your own ViewModel.

```kotlin
class CardViewModel(private val sdk: DigitalCardEngineSDK) : ViewModel() {
    var cards by mutableStateOf<List<CardListItem>>(emptyList())
    var isLoading by mutableStateOf(false)
    
    fun loadCards() {
        viewModelScope.launch {
            isLoading = true
            cards = sdk.getCards().map { /* map to CardListItem */ }
            isLoading = false
        }
    }
}

@Composable
fun CustomIntegration(viewModel: CardViewModel) {
    UILibrary.DCECardListView(
        cards = viewModel.cards,
        isLoading = viewModel.isLoading,
        onCardSelected = { /* ... */ },
        onRetry = { viewModel.loadCards() }
    )
}
```

**Pros**: Full control, testable
**Cons**: More boilerplate

### Pattern 3: Hybrid

Mix high and low-level components.

```kotlin
@Composable
fun HybridApproach(sdk: DigitalCardEngineSDK, card: CardEntity) {
    Column {
        // High-level component
        UILibrary.CardOverview(
            card = card,
            sdk = sdk
        )
        
        // Custom section
        CustomAnalyticsSection(card)
        
        // Low-level component with custom data
        val transactions = remember { /* custom fetch */ }
        UILibrary.TransactionList(
            transactions = transactions
        )
    }
}
```

***

## Styling All Components

Apply consistent styling globally:

```kotlin
@Composable
fun ThemedApp(sdk: DigitalCardEngineSDK) {
    CompositionLocalProvider(
        UILibrary.LocalStyleConfiguration provides sdk.styleConfiguration
    ) {
        // All components inherit styling
        NavHost(/*...*/) {
            composable("cards") {
                UILibrary.CardListView(sdk = sdk, /*...*/)
            }
            composable("details/{id}") {
                UILibrary.CardPageView(sdk = sdk, card = /*...*/)
            }
        }
    }
}
```

***

## See Also

* [Card List](card-list-1.md) - CardListView usage guide
* [Card Details](card-details.md) - CardOverview and CardPageView
* [Transaction History](transaction-history.md) - Transaction components
* [Styling & Theming](styling-theming.md) - Customizing component appearance
* [Data Models](data-models.md) - Understanding component parameters