MyCuppa

Android Components Reference

Complete API reference for all Cuppa Android components and utilities.

Core Components

CuppaButton

A versatile button component with multiple variants and states.

Parameters:

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | text | String | required | Button label text | | onClick | () -> Unit | required | Click handler | | variant | ButtonVariant | .Primary | Visual variant | | size | ButtonSize | .Medium | Button size | | isLoading | Boolean | false | Show loading indicator | | enabled | Boolean | true | Enable/disable button | | icon | ImageVector? | null | Optional icon | | modifier | Modifier | Modifier | Compose modifier |

Variants:

  • .Primary - Filled button with primary color
  • .Secondary - Filled button with secondary color
  • .Outlined - Border-only button
  • .Text - Text-only button
  • .Destructive - Destructive action styling

Example:

CuppaButton(
    text = "Submit",
    onClick = { handleSubmit() },
    variant = ButtonVariant.Primary,
    size = ButtonSize.Large,
    icon = Icons.Default.Check
)

CuppaTextField

Text input field with validation and formatting.

Parameters:

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | value | String | required | Current text value | | onValueChange | (String) -> Unit | required | Value change callback | | label | String? | null | Field label | | placeholder | String | "" | Placeholder text | | keyboardType | KeyboardType | .Text | Keyboard type | | validation | ValidationRule? | null | Validation rule | | leadingIcon | ImageVector? | null | Leading icon | | trailingIcon | ImageVector? | null | Trailing icon | | enabled | Boolean | true | Enable/disable input | | modifier | Modifier | Modifier | Compose modifier |

Validation Rules:

  • ValidationRule.Email - Email format
  • ValidationRule.Phone - Phone number
  • ValidationRule.Url - URL format
  • ValidationRule.Required - Non-empty
  • ValidationRule.MinLength(Int) - Minimum length
  • ValidationRule.MaxLength(Int) - Maximum length
  • ValidationRule.Pattern(Regex) - Custom regex

Example:

var email by remember { mutableStateOf("") }

CuppaTextField(
    value = email,
    onValueChange = { email = it },
    label = "Email Address",
    placeholder = "Enter your email",
    keyboardType = KeyboardType.Email,
    validation = ValidationRule.Email,
    leadingIcon = Icons.Default.Email
)

CuppaLazyColumn

Enhanced lazy column with search, refresh, and empty states.

Parameters:

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | items | List<T> | required | List items | | key | ((T) -> Any)? | null | Item key function | | emptyState | @Composable (() -> Unit)? | null | Empty state content | | itemContent | @Composable (T) -> Unit | required | Item composable | | modifier | Modifier | Modifier | Compose modifier |

Example:

CuppaLazyColumn(
    items = items,
    key = { it.id },
    emptyState = {
        CuppaEmptyState(
            icon = Icons.Default.Inbox,
            title = "No items",
            message = "Add your first item"
        )
    }
) { item ->
    CuppaListItem(
        title = item.title,
        onClick = { navigate(item) }
    )
}

CuppaCard

Container with elevation and rounded corners.

Parameters:

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | modifier | Modifier | Modifier | Compose modifier | | elevation | Dp | 4.dp | Card elevation | | shape | Shape | RoundedCornerShape(12.dp) | Card shape | | backgroundColor | Color | MaterialTheme.colorScheme.surface | Background color | | content | @Composable (() -> Unit) | required | Card content |

Example:

CuppaCard(
    modifier = Modifier.padding(16.dp),
    elevation = 8.dp
) {
    Column(
        modifier = Modifier.padding(16.dp)
    ) {
        Text("Card Title")
        Text("Card content")
    }
}

Layout Components

CuppaGrid

Responsive grid layout.

Parameters:

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | items | List<T> | required | Grid items | | columns | Int | 2 | Number of columns | | spacing | Dp | 16.dp | Item spacing | | content | @Composable (T) -> Unit | required | Item content | | modifier | Modifier | Modifier | Compose modifier |

Example:

CuppaGrid(
    items = products,
    columns = 3,
    spacing = 12.dp
) { product ->
    ProductCard(product = product)
}

Navigation Components

CuppaBottomNavigationBar

Bottom tab navigation.

Parameters:

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | selectedIndex | Int | required | Selected tab index | | onTabSelected | (Int) -> Unit | required | Tab selection callback | | tabs | List<BottomNavTab> | required | Tab items | | modifier | Modifier | Modifier | Compose modifier |

Example:

CuppaBottomNavigationBar(
    selectedIndex = selectedTab,
    onTabSelected = { selectedTab = it },
    tabs = listOf(
        BottomNavTab("Home", Icons.Default.Home),
        BottomNavTab("Search", Icons.Default.Search),
        BottomNavTab("Profile", Icons.Default.Person)
    )
)

CuppaTopAppBar

Top app bar with navigation and actions.

Parameters:

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | title | String | required | Bar title | | navigationIcon | @Composable (() -> Unit)? | null | Navigation icon | | actions | @Composable (RowScope.() -> Unit)? | null | Action buttons | | modifier | Modifier | Modifier | Compose modifier |

Example:

CuppaTopAppBar(
    title = "My App",
    navigationIcon = {
        IconButton(onClick = { openDrawer() }) {
            Icon(Icons.Default.Menu, "Menu")
        }
    },
    actions = {
        IconButton(onClick = { openSettings() }) {
            Icon(Icons.Default.Settings, "Settings")
        }
    }
)

Modal Components

CuppaBottomSheet

Modal bottom sheet.

Parameters:

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | onDismiss | () -> Unit | required | Dismiss callback | | content | @Composable (() -> Unit) | required | Sheet content |

Example:

if (showSheet) {
    CuppaBottomSheet(
        onDismiss = { showSheet = false }
    ) {
        SheetContent()
    }
}

CuppaAlertDialog

Alert dialog.

Parameters:

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | isOpen | Boolean | required | Open state | | onDismiss | () -> Unit | required | Dismiss callback | | title | String | required | Dialog title | | message | String | required | Dialog message | | confirmButton | @Composable (() -> Unit) | required | Confirm button | | dismissButton | @Composable (() -> Unit)? | null | Dismiss button |

Example:

CuppaAlertDialog(
    isOpen = showDialog,
    onDismiss = { showDialog = false },
    title = "Confirm",
    message = "Are you sure?",
    confirmButton = {
        CuppaButton(
            text = "Yes",
            onClick = { confirm() }
        )
    }
)

Utilities

CuppaBridge

TypeScript ↔ Kotlin bridge.

Methods:

// Call TypeScript function
suspend fun <T> call(
    function: String,
    args: Map<String, Any> = emptyMap()
): T

// Register Kotlin function
fun register(
    name: String,
    handler: suspend (Map<String, Any>) -> Any
)

Example:

// Call TypeScript
val result = CuppaBridge.call<User>(
    function = "getUser",
    args = mapOf("id" to userId)
)

// Register Kotlin function
CuppaBridge.register("showToast") { args ->
    val message = args["message"] as String
    Toast.makeText(context, message, Toast.LENGTH_SHORT).show()
}

CuppaStorage

Persistent storage utilities.

Methods:

// Save data
suspend fun set(key: String, value: Any)

// Read data
suspend fun <T> get(key: String): T?

// Delete data
suspend fun remove(key: String)

// Clear all
suspend fun clear()

Example:

// Save
CuppaStorage.set("user", userData)

// Read
val user: User? = CuppaStorage.get("user")

// Delete
CuppaStorage.remove("user")

CuppaRouter

Navigation and routing.

Methods:

// Navigate to route
fun navigate(route: String, args: Map<String, Any> = emptyMap())

// Go back
fun goBack()

// Replace current route
fun replace(route: String)

Example:

// Navigate
CuppaRouter.navigate("/detail", mapOf("id" to itemId))

// Go back
CuppaRouter.goBack()

Theme

CuppaTheme

Customize appearance.

Example:

@Composable
fun MyApp() {
    CuppaTheme(
        colorScheme = customColorScheme,
        typography = customTypography
    ) {
        // App content
    }
}

Next Steps