### Quick Start Guide

Source: https://github.com/yasanglass/kepko/blob/main/_autodocs/SUMMARY.txt

Instructions for adding Kepko dependencies, initializing the theme, using components, and accessing theme properties.

```APIDOC
## Quick Start Guide

### 1. Add dependencies:
```
implementation("glass.yasan.kepko:foundation:1.0.0")
implementation("glass.yasan.kepko:component:1.0.0")
```

### 2. Initialize theme:
```kotlin
KepkoTheme(palette = ColorPalette.LIGHT) {
    MyAppContent()
}
```

### 3. Use components:
```kotlin
Button(text = "Click", onClick = { }, leadingIcon = null)
```

### 4. Access theme:
```kotlin
Text(text = "Styled", color = KepkoTheme.colors.success)
```
```

--------------------------------

### Desktop Application Setup

Source: https://github.com/yasanglass/kepko/blob/main/_autodocs/configuration.md

Standard desktop application setup using `application` and `Window` from Compose for Desktop.

```kotlin
import androidx.compose.ui.window.Window
import androidx.compose.ui.window.application

fun main() = application {
    Window(onCloseRequest = ::exitApplication) {
        App()
    }
}
```

--------------------------------

### Android Application Setup

Source: https://github.com/yasanglass/kepko/blob/main/_autodocs/configuration.md

Standard Android application setup using `setContent` within `AppCompatActivity`.

```kotlin
// AndroidManifest.xml - No special configuration required
// Compose handles everything

// MainActivity.kt
class MainActivity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContent {
            App()
        }
    }
}
```

--------------------------------

### Subtitle Usage Example

Source: https://github.com/yasanglass/kepko/blob/main/_autodocs/api-reference/layouts-dialogs.md

Shows a basic example of using the Subtitle component with text.

```kotlin
Subtitle("Section Header")
```

--------------------------------

### Complete Settings Screen Example

Source: https://github.com/yasanglass/kepko/blob/main/_autodocs/api-reference/preferences.md

A full example of a settings screen using various preference components. It includes state management for dark mode, notifications, language, and text size.

```kotlin
@Composable
fun SettingsScreen(onBack: () -> Unit) {
    var darkMode by remember { mutableStateOf(false) }
    var notifications by remember { mutableStateOf(true) }
    var language by remember { mutableStateOf("en") }
    var textSize by remember { mutableStateOf(14f) }
    
    Scaffold(
        topBar = { TitleBar(title = "Settings") }
    ) { padding ->
        Column(Modifier.padding(padding).verticalScroll(rememberScrollState())) {
            PreferenceSwitch(
                title = "Dark Mode",
                checked = darkMode,
                onCheckedChange = { darkMode = it }
            )
            
            PreferenceCheckbox(
                title = "Notifications",
                checked = notifications,
                onCheckedChange = { notifications = it }
            )
            
            PreferenceSlider(
                title = "Text Size",
                value = textSize,
                onValueChange = { textSize = it },
                valueRange = 10f..24f
            )
            
            PreferenceRadioGroupPicker(
                title = "Language",
                items = listOf(
                    PreferenceRadioGroupItem("en", "English"),
                    PreferenceRadioGroupItem("es", "Spanish")
                ),
                selected = language,
                onSelectionChange = { language = it }
            )
        }
    }
}
```

--------------------------------

### SelectableChip Example

Source: https://github.com/yasanglass/kepko/blob/main/_autodocs/api-reference/preferences.md

Demonstrates how to use the SelectableChip component with state management for selection.

```kotlin
var selected by remember { mutableStateOf(false) }
SelectableChip(
    text = "Filter",
    selected = selected,
    onClick = { selected = !selected }
)
```

--------------------------------

### AlertDialog Usage Example

Source: https://github.com/yasanglass/kepko/blob/main/_autodocs/api-reference/components.md

Example demonstrating how to use the AlertDialog component with confirmation and dismissal buttons, a title, and text content. Ensure the `showDialog` state is managed appropriately.

```kotlin
AlertDialog(
    onDismissRequest = { showDialog = false },
    title = { Text("Confirm") },
    text = { Text("Are you sure?") },
    confirmButton = { Button(text = "Yes", onClick = { confirm() }, leadingIcon = null) },
    dismissButton = { Button(text = "No", onClick = { showDialog = false }, leadingIcon = null) },
)
```

--------------------------------

### iOS Application Setup

Source: https://github.com/yasanglass/kepko/blob/main/_autodocs/configuration.md

Basic iOS application structure using SwiftUI's `App` protocol and `WindowGroup`.

```kotlin
// iOS apps use standard Compose Multiplatform iOS framework
// No special Kepko configuration needed

@main
struct iOSApp: App {
    var body: some Scene {
        WindowGroup {
            MainScreenKt.MainScreen()
        }
    }
}
```

--------------------------------

### Surface Component Usage Example

Source: https://github.com/yasanglass/kepko/blob/main/_autodocs/api-reference/layouts-dialogs.md

An example demonstrating how to use the Surface composable with custom padding, shape, color, and elevation. This creates a card-like element with specific styling.

```kotlin
Surface(
    modifier = Modifier.padding(8.dp),
    shape = KepkoTheme.shapes.medium,
    color = KepkoTheme.colors.midground,
    tonalElevation = 4.dp,
) {
    Column(Modifier.padding(16.dp)) {
        Text("Card Content")
    }
}
```

--------------------------------

### Example Usage of TextButton

Source: https://github.com/yasanglass/kepko/blob/main/_autodocs/api-reference/additional-components.md

Demonstrates how to use the TextButton with custom text and content color.

```kotlin
TextButton(
    text = "Learn More",
    onClick = { openLink() },
    contentColor = KepkoTheme.colors.information
)
```

--------------------------------

### TitleBar Usage Example

Source: https://github.com/yasanglass/kepko/blob/main/_autodocs/api-reference/layouts-dialogs.md

Demonstrates how to use the TitleBar component with a title and a leading icon.

```kotlin
TitleBar(
    title = "Settings",
    leadingIcon = {
        Icon(
            painter = NamedIcon.CHEVRON_BACKWARD.painter(),
            contentDescription = "Back"
        )
    }
)
```

--------------------------------

### Icon Component Usage Example

Source: https://github.com/yasanglass/kepko/blob/main/_autodocs/api-reference/components.md

Demonstrates how to use the Icon component with a specific painter, content description, and tint color.

```kotlin
Icon(
    painter = NamedIcon.SETTINGS.painter(),
    contentDescription = "Settings",
    tint = KepkoTheme.colors.information,
)
```

--------------------------------

### ButtonPrimitive Usage Example

Source: https://github.com/yasanglass/kepko/blob/main/_autodocs/api-reference/additional-components.md

Example demonstrating how to use ButtonPrimitive with custom content, including an icon, spacer, and text.

```kotlin
ButtonPrimitive(
    onClick = { performAction() }
) {
    Icon(NamedIcon.SEND.painter(), "Send")
    Spacer(Modifier.width(8.dp))
    Text("Custom Layout")
}
```

--------------------------------

### KeyValue Usage Examples

Source: https://github.com/yasanglass/kepko/blob/main/_autodocs/api-reference/layouts-dialogs.md

Illustrates the usage of the KeyValue component for displaying different types of information, such as version and file size.

```kotlin
KeyValue(key = "Version", value = "1.0.0")
KeyValue(key = "Size", value = "2.5 MB")
```

--------------------------------

### Button Usage Example

Source: https://github.com/yasanglass/kepko/blob/main/_autodocs/api-reference/components.md

Demonstrates a practical example of how to use the Button component with custom text, an icon, and a specific background color. This snippet is useful for quickly integrating a styled button into your application.

```kotlin
Button(
    text = "Submit",
    onClick = { submitForm() },
    leadingIcon = NamedIcon.SEND.painter(),
    containerColor = KepkoTheme.colors.success,
)
```

--------------------------------

### ProgressIndicator Usage Example

Source: https://github.com/yasanglass/kepko/blob/main/_autodocs/api-reference/additional-components.md

Demonstrates how to use the ProgressIndicator composable with custom size and color.

```kotlin
ProgressIndicator(
    modifier = Modifier.size(48.dp),
    color = KepkoTheme.colors.success
)
```

--------------------------------

### PersistentKepkoTheme Usage Example (Singleton)

Source: https://github.com/yasanglass/kepko/blob/main/_autodocs/api-reference/persistence.md

Example of how to wrap your application content with PersistentKepkoTheme to automatically apply persisted theme preferences. No explicit persistence manager is needed here.

```kotlin
@OptIn(ExperimentalKepkoApi::class)
@Composable
fun MyApp() {
    PersistentKepkoTheme {
        Scaffold(
            topBar = { TitleBar(title = "My App") }
        ) {
            // Content automatically uses persisted theme
        }
    }
}
```

--------------------------------

### Initialize Basic KepkoTheme

Source: https://github.com/yasanglass/kepko/blob/main/_autodocs/configuration.md

Set up the basic Kepko theme in your Android application. This example uses a predefined light color palette.

```kotlin
// Android/Main.kt
import androidx.compose.runtime.Composable
import glass.yasan.kepko.foundation.theme.KepkoTheme
import glass.yasan.kepko.foundation.theme.ColorPalette

@Composable
fun App() {
    KepkoTheme(palette = ColorPalette.LIGHT) {
        MyAppContent()
    }
}
```

--------------------------------

### CheckboxText Example

Source: https://github.com/yasanglass/kepko/blob/main/_autodocs/api-reference/components.md

A basic example of how to use the CheckboxText component. It requires a text label, the current checked state, and a callback for state changes.

```kotlin
CheckboxText(
    text = "I agree to terms",
    checked = agreed,
    onCheckedChange = { agreed = it }
)
```

--------------------------------

### Example Usage of PersistentPreferenceThemeScreen

Source: https://github.com/yasanglass/kepko/blob/main/_autodocs/api-reference/persistence.md

Demonstrates how to integrate the PersistentPreferenceThemeScreen composable within a settings screen, providing the necessary back button callback.

```kotlin
@OptIn(ExperimentalKepkoApi::class)
@Composable
fun SettingsScreen(onBack: () -> Unit) {
    Scaffold(
        topBar = { TitleBar(title = "Theme Settings") },
    ) {
        Column(Modifier.padding(padding)) {
            PersistentPreferenceThemeScreen(
                onBackClick = onBack
            )
        }
    }
}
```

--------------------------------

### TextPill Usage Example

Source: https://github.com/yasanglass/kepko/blob/main/_autodocs/api-reference/layouts-dialogs.md

Demonstrates how to use the TextPill component with custom container color. Ensure KepkoTheme is applied.

```kotlin
TextPill(text = "New", containerColor = KepkoTheme.colors.success)
```

--------------------------------

### PersistentKepkoTheme Usage Example (Custom Manager)

Source: https://github.com/yasanglass/kepko/blob/main/_autodocs/api-reference/persistence.md

Example demonstrating how to use PersistentKepkoTheme with a custom PersistenceManager. A custom manager is created and passed as a parameter to control theme persistence.

```kotlin
val customManager = remember { PersistenceManagerImpl() }
PersistentKepkoTheme(persistenceManager = customManager) {
    // Custom persistence manager controls theme
}
```

--------------------------------

### Badge Usage Example in Button

Source: https://github.com/yasanglass/kepko/blob/main/_autodocs/api-reference/additional-components.md

Shows how to integrate a Badge with a notification count into a Button component.

```kotlin
Button(
    text = "Notifications",
    onClick = { },
    leadingIcon = NamedIcon.SEND.painter(),
    badge = Badge(text = "3", containerColor = KepkoTheme.colors.danger)
)
```

--------------------------------

### Complete Theme Customization Example

Source: https://github.com/yasanglass/kepko/blob/main/_autodocs/api-reference/colors-shapes-dimensions.md

Demonstrates how to create a fully custom theme by defining custom dimensions, shapes, and color palettes. All components within the theme will inherit these custom values.

```kotlin
@Composable
fun CustomThemeApp() {
    // Custom dimensions
    val customDimensions = dimensions(
        borderThickness = 2.dp,
        iconSize = 28.dp
    )
    
    // Custom shapes
    val customShapes = shapes(
        extraSmall = 2.dp,
        small = 6.dp,
        medium = 10.dp,
        large = 14.dp,
        extraLarge = 24.dp
    )
    
    // Custom colors
    val customColors = Colors(
        palette = ColorPalette.DARK,
        grayscale = false
    )
    
    KepkoTheme(
        colors = customColors,
        dimensions = customDimensions,
        shapes = customShapes
    ) {
        Scaffold {
            Column {
                // All components use custom theme
                Button(
                    text = "Styled Button",
                    onClick = { },
                    leadingIcon = NamedIcon.SEND.painter(),
                    containerColor = KepkoTheme.colors.success,
                    shape = KepkoTheme.shapes.large
                )
            }
        }
    }
}
```

--------------------------------

### AlertDialog Usage Example

Source: https://github.com/yasanglass/kepko/blob/main/_autodocs/api-reference/layouts-dialogs.md

Example of how to use the AlertDialog component to display a confirmation dialog with confirm and dismiss buttons. Ensure the 'showConfirm' state is managed to control dialog visibility.

```kotlin
var showConfirm by remember { mutableStateOf(false) }
if (showConfirm) {
    AlertDialog(
        onDismissRequest = { showConfirm = false },
        title = { Text("Confirm Action") },
        text = { Text("Are you sure you want to proceed?") },
        confirmButton = {
            Button(
                text = "Yes",
                onClick = {
                    performAction()
                    showConfirm = false
                },
                leadingIcon = null
            )
        },
        dismissButton = {
            Button(
                text = "No",
                onClick = { showConfirm = false },
                leadingIcon = null
            )
        }
    )
}
```

--------------------------------

### PreferenceRadioGroupPicker Example Usage

Source: https://github.com/yasanglass/kepko/blob/main/_autodocs/api-reference/preferences.md

Shows how to implement PreferenceRadioGroupPicker for language selection, using chip display mode and a list of predefined items.

```kotlin
PreferenceRadioGroupPicker(
    title = "Language",
    items = listOf(
        PreferenceRadioGroupItem("en", "English"),
        PreferenceRadioGroupItem("es", "Spanish"),
        PreferenceRadioGroupItem("fr", "French")
    ),
    selected = language,
    onSelectionChange = { language = it },
    displayMode = PreferenceRadioGroupPickerDisplayMode.CHIPS
)
```

--------------------------------

### TextField Usage Example

Source: https://github.com/yasanglass/kepko/blob/main/_autodocs/api-reference/components.md

Demonstrates basic usage of the TextField composable. Ensure you manage the state using remember and mutableStateOf.

```kotlin
var name by remember { mutableStateOf("") }
TextField(
    value = name,
    onValueChange = { name = it },
    label = { Text("Name") },
)
```

--------------------------------

### Scaffold Usage Example

Source: https://github.com/yasanglass/kepko/blob/main/_autodocs/api-reference/components.md

Illustrates the basic usage of the Scaffold composable, including setting a top bar and defining the page content which receives padding values.

```kotlin
Scaffold(
    topBar = { TitleBar(title = "App") },
) {
    padding ->
    Column(Modifier.padding(padding)) {
        // Page content
    }
}
```

--------------------------------

### PreferenceAppIdentity Example

Source: https://github.com/yasanglass/kepko/blob/main/_autodocs/api-reference/preferences.md

Shows how to implement the PreferenceAppIdentity component to display an application's name, version, and icon. This is typically used at the top of preference screens.

```kotlin
PreferenceAppIdentity(
    appName = "MyApp",
    appVersion = "1.2.3",
    appIcon = {
        Icon(
            painter = painterResource(Res.drawable.app_icon),
            contentDescription = "App Icon"
        )
    }
)
```

--------------------------------

### PreferenceSlider Example Usage

Source: https://github.com/yasanglass/kepko/blob/main/_autodocs/api-reference/preferences.md

Demonstrates how to use the PreferenceSlider to adjust a text size preference, with a defined value range and description.

```kotlin
var textSize by remember { mutableStateOf(14f) }
PreferenceSlider(
    title = "Text Size",
    value = textSize,
    onValueChange = { textSize = it },
    valueRange = 10f..24f,
    description = "Adjust font size"
)
```

--------------------------------

### Switch Usage Example

Source: https://github.com/yasanglass/kepko/blob/main/_autodocs/api-reference/components.md

Demonstrates basic usage of the Switch composable. The onCheckedChange lambda updates the state variable.

```kotlin
Switch(
    checked = darkMode,
    onCheckedChange = { darkMode = it }
)
```

--------------------------------

### Components

Source: https://github.com/yasanglass/kepko/blob/main/_autodocs/SUMMARY.txt

Detailed documentation for various UI components, including Button, Text, Checkbox, and more, with their parameters, returns, and examples.

```APIDOC
## Button Component

### Description
A versatile button component with over 30 documented parameters for customization.

### Method
Composable Function

### Endpoint
N/A

### Parameters
(Details for 30+ parameters available in source)

### Request Example
(Examples available in source)

### Response
(UI element rendered)

### Response Example
(Examples available in source)

## Text Component

### Description
A text component with multiple overloads for different text display needs.

### Method
Composable Function

### Endpoint
N/A

## Checkbox and CheckboxText Components

### Description
Components for rendering checkboxes and associated text labels.

### Method
Composable Functions

### Endpoint
N/A

## PreferenceContainer Component

### Description
A container component for preference items.

### Method
Composable Function

### Endpoint
N/A

## PreferenceSwitch Component

### Description
A switch component within a preference item.

### Method
Composable Function

### Endpoint
N/A

## ModalBottomSheet Component

### Description
A component for displaying bottom sheets.

### Method
Composable Function

### Endpoint
N/A

## AlertDialog Component

### Description
A component for displaying alert dialogs.

### Method
Composable Function

### Endpoint
N/A

## TextField / OutlinedTextField Components

### Description
Components for text input fields with standard and outlined styles.

### Method
Composable Functions

### Endpoint
N/A

## Switch Component

### Description
A toggle switch component.

### Method
Composable Function

### Endpoint
N/A

## Slider Component

### Description
A slider component for selecting a value from a range.

### Method
Composable Function

### Endpoint
N/A

## Scaffold Component

### Description
A foundational layout component for screens.

### Method
Composable Function

### Endpoint
N/A

## Badge Component

### Description
A component for displaying badges, often used for notifications or counts.

### Method
Composable Function

### Endpoint
N/A

## Icon Component

### Description
A component for displaying icons.

### Method
Composable Function

### Endpoint
N/A
```

--------------------------------

### PreferenceRadioButton Example

Source: https://github.com/yasanglass/kepko/blob/main/_autodocs/api-reference/preferences.md

Demonstrates how to use PreferenceRadioButton for individual option selection. Each button requires a title, a selected state, and an onClick callback.

```kotlin
var selectedTheme by remember { mutableStateOf("light") }
PreferenceRadioButton(
    title = "Light",
    selected = selectedTheme == "light",
    onClick = { selectedTheme = "light" }
)
PreferenceRadioButton(
    title = "Dark",
    selected = selectedTheme == "dark",
    onClick = { selectedTheme = "dark" }
)
```

--------------------------------

### Complete Settings Screen Setup

Source: https://github.com/yasanglass/kepko/blob/main/_autodocs/configuration.md

A complete Composable function for a settings screen, including dark mode toggle, notifications preference, and theme settings. Requires experimental Kepko API opt-in.

```kotlin
@OptIn(ExperimentalKepkoApi::class)
@Composable
fun SettingsScreen(onBack: () -> Unit) {
    var darkMode by remember { mutableStateOf(false) }
    var notifications by remember { mutableStateOf(true) }
    
    Scaffold(
        topBar = { TitleBar(title = "Settings") }
    ) {
        Column(
            modifier = Modifier
                .padding(it)
                .verticalScroll(rememberScrollState())
        ) {
            PreferenceAppIdentity(
                appName = "MyApp",
                appVersion = "1.0.0",
                appIcon = {
                    Icon(
                        painter = painterResource(Res.drawable.app_icon),
                        contentDescription = null
                    )
                }
            )
            
            PreferenceSwitch(
                title = "Dark Mode",
                checked = darkMode,
                onCheckedChange = { darkMode = it }
            )
            
            PreferenceCheckbox(
                title = "Notifications",
                checked = notifications,
                onCheckedChange = { notifications = it }
            )
            
            PersistentPreferenceThemeScreen(onBackClick = onBack)
        }
    }
}
```

--------------------------------

### Preferences

Source: https://github.com/yasanglass/kepko/blob/main/_autodocs/SUMMARY.txt

Comprehensive documentation for preference components, including containers, switches, checkboxes, radio buttons, and more, with a full screen example.

```APIDOC
## PreferenceContainer Component

### Description
A flexible container for preference items with over 30 parameters.

### Method
Composable Function

### Endpoint
N/A

### Parameters
(Details for 30+ parameters available in source)

## PreferenceContainerColors

### Description
Defines color customization options for `PreferenceContainer`.

### Method
Class/Data Class

### Endpoint
N/A

## PreferenceSwitch Component

### Description
A switch component specifically designed for preference screens.

### Method
Composable Function

### Endpoint
N/A

## PreferenceCheckbox Component

### Description
A checkbox component for preference screens.

### Method
Composable Function

### Endpoint
N/A

## PreferenceRadioButton Component

### Description
A radio button component for preference screens.

### Method
Composable Function

### Endpoint
N/A

## PreferenceRadioGroup<T> Component

### Description
A group of radio buttons for selecting one option from a list.

### Method
Composable Function

### Endpoint
N/A

## PreferenceRadioGroupItem<T> Component

### Description
An individual item within a `PreferenceRadioGroup`.

### Method
Composable Function

### Endpoint
N/A

## PreferenceSlider Component

### Description
A slider component for adjusting numerical preferences.

### Method
Composable Function

### Endpoint
N/A

## PreferenceRadioGroupPicker Component

### Description
A picker component for radio group selections.

### Method
Composable Function

### Endpoint
N/A

## PreferenceRadioGroupPickerDisplayMode Enum

### Description
Defines display modes for `PreferenceRadioGroupPicker`.

### Method
Enum

### Endpoint
N/A

## PreferenceRadioGroupSheet Component

### Description
A sheet-based component for radio group selections.

### Method
Composable Function

### Endpoint
N/A

## PreferenceAppIdentity Component

### Description
A component to display application identity information within preferences.

### Method
Composable Function

### Endpoint
N/A

## SegmentedPicker Component

### Description
A component for selecting from segmented options.

### Method
Composable Function

### Endpoint
N/A

## SelectableChip Component

### Description
A chip component that can be selected.

### Method
Composable Function

### Endpoint
N/A

## Complete preference screen example

### Description
Demonstrates how to assemble various preference components into a full settings screen.

### Method
Example Usage

### Endpoint
N/A
```

--------------------------------

### Example Usage of PreviewPersistentKepkoTheme

Source: https://github.com/yasanglass/kepko/blob/main/_autodocs/api-reference/persistence.md

Demonstrates how to use the PreviewPersistentKepkoTheme composable within a preview function. It shows how to set the dark theme state and configure preview manager properties like roundness and outline.

```kotlin
@Preview
@Composable
fun PreviewMyComponent() {
    PreviewPersistentKepkoTheme(
        isSystemInDarkTheme = true,
        configure = {
            roundness = 0.5f
            outline = 2.dp
        }
    ) {
        MyComponent()
    }
}
```

--------------------------------

### Serialization

Source: https://github.com/yasanglass/kepko/blob/main/_autodocs/SUMMARY.txt

Documentation for serialization utilities, including JSON schema, serializers for named colors and icons, and deserialization examples.

```APIDOC
## ContractButton Composable

### Description
A composable function related to button contracts, likely for serialization/deserialization.

### Method
Composable Function

### Endpoint
N/A

## ButtonContract Data Class

### Description
A data class representing a button contract with 13 properties, including its JSON schema definition.

### Method
Data Class

### Endpoint
N/A

### Properties
(13 properties documented in source)

## NamedColorSerializer

### Description
A serializer for the `NamedColor` enum (15 colors).

### Method
Serializer

### Endpoint
N/A

## NamedIconSerializer

### Description
A serializer for the `NamedIcon` enum (62 icons).

### Method
Serializer

### Endpoint
N/A

## KepkoJson Pre-configured Decoder

### Description
A pre-configured JSON decoder for Kepko objects.

### Method
Object/Configuration

### Endpoint
N/A

## PreferenceAnnotationContract

### Description
Contract related to annotations for preferences, likely used in serialization.

### Method
Class/Interface

### Endpoint
N/A

## Complete deserialization examples

### Description
Provides examples demonstrating how to deserialize various Kepko objects.

### Method
Example Usage

### Endpoint
N/A

## JSON schema validation

### Description
Information on how to validate JSON schemas within the Kepko system.

### Method
Documentation Section

### Endpoint
N/A

## Error handling patterns

### Description
Describes common error handling strategies for serialization and deserialization.

### Method
Documentation Section

### Endpoint
N/A
```

--------------------------------

### DragHandle Usage Example

Source: https://github.com/yasanglass/kepko/blob/main/_autodocs/api-reference/layouts-dialogs.md

Demonstrates how to use the DragHandle component within a Row layout alongside other elements.

```kotlin
Row {
    DragHandle()
    Text("Draggable Item")
}
```

--------------------------------

### PreferenceContainer Usage Example

Source: https://github.com/yasanglass/kepko/blob/main/_autodocs/api-reference/preferences.md

Demonstrates how to use the PreferenceContainer with a title, description, and a click handler. The content slot is used to display additional information.

```kotlin
PreferenceContainer(
    title = "Theme",
    description = "Customize appearance",
    onClick = { navigateToTheme() },
) {
    Text("Dark Mode", Modifier.padding(it))
}
```

--------------------------------

### Example Usage of Custom Dimensions

Source: https://github.com/yasanglass/kepko/blob/main/_autodocs/api-reference/colors-shapes-dimensions.md

Demonstrates how to apply custom dimensions, such as thicker borders and smaller icons, by providing specific values to the dimensions function.

```kotlin
KepkoTheme(
    dimensions = dimensions(
        borderThickness = 2.dp,
        iconSize = 20.dp
    )
) {
    // Thicker borders, smaller icons
}
```

--------------------------------

### Apply Kepko Theme to App

Source: https://github.com/yasanglass/kepko/blob/main/README.md

Wrap your application's content with the `KepkoTheme` composable to apply the design system's theming. This example also demonstrates using a `TextPill` component with a custom color.

```kotlin
KepkoTheme {
    Text("Hello, Kepko!")
    TextPill(
        text = "Yasan Glass",
        containerColor = KepkoTheme.colors.information,
    )
}
```

--------------------------------

### Example Usage of AnimatedPersistentKepkoTheme

Source: https://github.com/yasanglass/kepko/blob/main/_autodocs/api-reference/persistence.md

Shows how to use AnimatedPersistentKepkoTheme to wrap application content, enabling smooth theme change animations with a specified duration.

```kotlin
@OptIn(ExperimentalKepkoApi::class)
@Composable
fun MyApp() {
    AnimatedPersistentKepkoTheme(animationDurationMillis = 500) {
        // Theme changes animate smoothly
    }
}
```

--------------------------------

### Customizing Theme Shapes

Source: https://github.com/yasanglass/kepko/blob/main/_autodocs/README.md

Provides an example of creating and applying custom shape values (e.g., corner radii) to the Kepko theme.

```kotlin
val customShapes = shapes(
    extraSmall = 2.dp,
    small = 4.dp,
    medium = 8.dp,
    large = 12.dp,
    extraLarge = 20.dp
)
KepkoTheme(shapes = customShapes) { ... }
```

--------------------------------

### PreferenceContainer Example

Source: https://github.com/yasanglass/kepko/blob/main/_autodocs/api-reference/components.md

Demonstrates the PreferenceContainer for creating preference items. It supports a title, optional description, and click handling. The content lambda defines the inner UI elements.

```kotlin
PreferenceContainer(
    title = "Appearance",
    description = "Customize theme",
    onClick = { navigateToTheme() },
) {
    Text("Select a color palette", modifier = Modifier.padding(padding))
}
```

--------------------------------

### Scaffold Usage Example

Source: https://github.com/yasanglass/kepko/blob/main/_autodocs/api-reference/layouts-dialogs.md

Demonstrates how to use the Scaffold component with a top bar, bottom bar, and a LazyColumn for the main content. The paddingValues are applied to the content to handle insets from the bars.

```kotlin
Scaffold(
    topBar = { TitleBar(title = "Home") },
    bottomBar = { BottomNavigation() },
) {
    LazyColumn(
        modifier = Modifier.padding(paddingValues)
    ) {
        items(20) {
            Text("Item $index")
        }
    }
}
```

--------------------------------

### PreferenceSwitch Example

Source: https://github.com/yasanglass/kepko/blob/main/_autodocs/api-reference/preferences.md

Use PreferenceSwitch to create a toggleable preference item with a title, optional description, and a switch control. It requires the current checked state and a callback for state changes.

```kotlin
var isDarkMode by remember { mutableStateOf(false) }
PreferenceSwitch(
    title = "Dark Mode",
    checked = isDarkMode,
    onCheckedChange = { isDarkMode = it },
    description = "Enable dark theme"
)
```

--------------------------------

### Example of Custom Shapes Usage

Source: https://github.com/yasanglass/kepko/blob/main/_autodocs/api-reference/colors-shapes-dimensions.md

Shows how to apply custom corner radius values to the KepkoTheme. This enables fine-grained control over the rounding of elements throughout the application.

```kotlin
KepkoTheme(
    shapes = shapes(
        extraSmall = 2.dp,
        small = 4.dp,
        medium = 8.dp,
        large = 12.dp,
        extraLarge = 20.dp
    )
) {
    // Uses custom corner radius values throughout
}
```

--------------------------------

### ExpandableColumn Usage Example

Source: https://github.com/yasanglass/kepko/blob/main/_autodocs/api-reference/layouts-dialogs.md

Shows how to implement an ExpandableColumn with a title and content that can be expanded or collapsed. State management for the expanded property is handled using remember and mutableStateOf.

```kotlin
var expanded by remember { mutableStateOf(false) }
ExpandableColumn(
    title = "Advanced Options",
    expanded = expanded,
    onExpandedChange = { expanded = it } // Update state on change
) {
    Text("Option 1")
    Text("Option 2")
    Text("Option 3")
}
```

--------------------------------

### PreferenceRadioGroupSheet Example

Source: https://github.com/yasanglass/kepko/blob/main/_autodocs/api-reference/preferences.md

Demonstrates how to use PreferenceRadioGroupSheet to allow users to select an option from a list in a modal bottom sheet. The sheet is shown and hidden using a state variable.

```kotlin
var showSheet by remember { mutableStateOf(false) }
if (showSheet) {
    PreferenceRadioGroupSheet(
        title = "Select Theme",
        items = themeOptions,
        selected = selectedTheme,
        onSelectionChange = { theme ->
            selectedTheme = theme
            showSheet = false
        },
        onDismissRequest = { showSheet = false }
    )
}
```

--------------------------------

### IconButton Usage Example

Source: https://github.com/yasanglass/kepko/blob/main/_autodocs/api-reference/additional-components.md

Use this snippet to create a standalone icon button. Ensure you provide a Painter for the icon, an onClick lambda for the action, and a contentDescription for accessibility.

```kotlin
IconButton(
    painter = NamedIcon.SETTINGS.painter(),
    onClick = { openSettings() },
    contentDescription = "Settings"
)
```

--------------------------------

### Complete Dynamic Button Example

Source: https://github.com/yasanglass/kepko/blob/main/_autodocs/api-reference/serialization.md

A complete Composable function that deserializes a JSON string into a ButtonContract and renders a ContractButton. Includes error handling for invalid JSON and demonstrates usage within a Kepko theme.

```kotlin
@Composable
fun DynamicButtonFromJson(jsonString: String) {
    val json = Json(from = kepkoJson)
    try {
        val contract = json.decodeFromString<ButtonContract>(jsonString)
        ContractButton(
            contract = contract,
            onClick = { action ->
                println("Action received: $action")
            }
        )
    } catch (e: Exception) {
        Text("Invalid button JSON: ${e.message}")
    }
}

// Usage
@OptIn(ExperimentalKepkoApi::class)
@Composable
fun TestScreen() {
    KepkoTheme(palette = ColorPalette.DARK) {
        Column {
            DynamicButtonFromJson("""
            {
              "on_click": "submit",
              "text": "Submit",
              "container_color": "information",
              "leading_icon": "send",
              "enabled": true
            }
            """)
        }
    }
}
```

--------------------------------

### ModalBottomSheet Usage Example

Source: https://github.com/yasanglass/kepko/blob/main/_autodocs/api-reference/layouts-dialogs.md

Demonstrates how to use the ModalBottomSheet composable to display a sheet with a title, text, and a button. The sheet is controlled by a mutable state variable.

```kotlin
var showSheet by remember { mutableStateOf(false) }
if (showSheet) {
    ModalBottomSheet(onDismissRequest = { showSheet = false }) {
        Column(
            modifier = Modifier
                .fillMaxWidth()
                .padding(16.dp)
        ) {
            Text("Sheet Title", fontSize = 20.sp, fontWeight = FontWeight.Bold)
            Spacer(modifier = Modifier.height(8.dp))
            Button(
                text = "Action",
                onClick = {
                    performAction()
                    showSheet = false
                },
                leadingIcon = null
            )
        }
    }
}
```

--------------------------------

### ButtonContract JSON Example

Source: https://github.com/yasanglass/kepko/blob/main/_autodocs/README.md

Example JSON structure for defining a ButtonContract. This defines the properties for a button component, including its text, color, icon, and click action.

```json
{
  "on_click": "submit",
  "text": "Submit Form",
  "container_color": "success",
  "leading_icon": "send",
  "enabled": true
}
```

--------------------------------

### RadioButton Usage Example

Source: https://github.com/yasanglass/kepko/blob/main/_autodocs/api-reference/additional-components.md

This snippet demonstrates how to use the RadioButton component. It requires a 'selected' state and an 'onClick' lambda to handle selection changes. The 'option' variable should be managed to reflect the selected state.

```kotlin
RadioButton(
    selected = option == "a",
    onClick = { option = "a" }
)
```

--------------------------------

### Check Installed Kepko Version

Source: https://github.com/yasanglass/kepko/blob/main/_autodocs/configuration.md

There is no direct API to check the installed Kepko version. Consult build.gradle.kts, gradle dependencies, or Maven Central for version information.

```kotlin
// No direct API - check in build.gradle.kts or gradle dependencies
// Or check Maven Central for latest: https://central.sonatype.com/artifact/glass.yasan.kepko/foundation
```

--------------------------------

### Access SingletonPersistenceManager Instance

Source: https://github.com/yasanglass/kepko/blob/main/_autodocs/api-reference/persistence.md

Get the singleton instance of the persistence manager to access theme preferences.

```kotlin
val manager = SingletonPersistenceManager.instance
manager.paletteDark = ColorPalette.CATPPUCCIN_MOCHA
```

--------------------------------

### Creating a Custom Themed Component

Source: https://github.com/yasanglass/kepko/blob/main/_autodocs/README.md

Demonstrates how to build a custom composable component that utilizes Kepko theme's colors, shapes, and dimensions.

```kotlin
@Composable
fun CustomCard(
    title: String,
    content: @Composable () -> Unit
) {
    Surface(
        shape = KepkoTheme.shapes.medium,
        color = KepkoTheme.colors.foreground,
        border = BorderStroke(
            KepkoTheme.dimensions.borderThickness,
            KepkoTheme.colors.outline
        )
    ) {
        Column(Modifier.padding(16.dp)) {
            Text(title, color = KepkoTheme.colors.content)
            content()
        }
    }
}
```

--------------------------------

### Basic Text Component Usage

Source: https://github.com/yasanglass/kepko/blob/main/_autodocs/api-reference/components.md

Demonstrates how to use the Text component with custom color and font size. Ensure KepkoTheme is applied.

```kotlin
Text(
    text = "Hello, Kepko!",
    color = KepkoTheme.colors.foreground,
    fontSize = 18.sp
)
```

--------------------------------

### Preview Custom Theme Configuration

Source: https://github.com/yasanglass/kepko/blob/main/_autodocs/configuration.md

Configure a preview composable with specific light and dark color palettes using PreviewPersistentKepkoTheme.

```kotlin
@OptIn(ExperimentalKepkoApi::class)
@Preview
@Composable
fun MyComponentPreview() {
    PreviewPersistentKepkoTheme(
        isSystemInDarkTheme = false,
        configure = {
            paletteLight = ColorPalette.SOLARIZED_LIGHT
            paletteDark = ColorPalette.SOLARIZED_DARK
        }
    ) {
        MyComponent()
    }
}
```

--------------------------------

### Initialize Kepko Theme

Source: https://github.com/yasanglass/kepko/blob/main/_autodocs/SUMMARY.txt

Initialize the Kepko theme with a chosen color palette at the root of your application's content.

```kotlin
KepkoTheme(palette = ColorPalette.LIGHT) {
    MyAppContent()
}
```

--------------------------------

### NamedColor Usage Example

Source: https://github.com/yasanglass/kepko/blob/main/_autodocs/api-reference/colors-shapes-dimensions.md

Demonstrates how to use the NamedColor enum to retrieve a color and apply it to a UI element like a Button.

```APIDOC
## NamedColor Usage Example

### Description
Demonstrates how to use the NamedColor enum to retrieve a color and apply it to a UI element like a Button.

### Code
```kotlin
val namedColor = NamedColor.SUCCESS
val actualColor = namedColor.color(KepkoTheme.colors)
Button(
    text = "Success",
    onClick = { },
    leadingIcon = null,
    containerColor = actualColor
)
```
```

--------------------------------

### Initialize AnimatedPersistentKepkoTheme

Source: https://github.com/yasanglass/kepko/blob/main/_autodocs/configuration.md

Set up the animated persistent Kepko theme for smooth transitions between theme states. Customize the animation duration in milliseconds. Requires experimental API opt-in.

```kotlin
import glass.yasan.kepko.persistence.AnimatedPersistentKepkoTheme

@OptIn(ExperimentalKepkoApi::class)
@Composable
fun App() {
    AnimatedPersistentKepkoTheme(animationDurationMillis = 500) {
        MyAppContent()
    }
}
```

--------------------------------

### Manage User Profiles

Source: https://github.com/yasanglass/kepko/blob/main/_autodocs/configuration.md

Demonstrates creating, updating, listing, and deleting user profiles using the `profileManager`.

```kotlin
val manager = LocalKepkoPersistenceManager.current
val profileManager = manager.profileManager

// Create profile
val newProfile = profileManager.createProfile("John")

// Update profile preferences
manager.setPalettePrimary(profileId = newProfile.id, ColorPalette.DARK)

// List all profiles
val allProfiles = profileManager.listProfiles()

// Delete profile
profileManager.deleteProfile(newProfile.id)
```

--------------------------------

### ModalBottomSheetTitle Usage Example

Source: https://github.com/yasanglass/kepko/blob/main/_autodocs/api-reference/layouts-dialogs.md

Shows how to integrate the ModalBottomSheetTitle component within a ModalBottomSheet to provide a styled title for the sheet's content.

```kotlin
ModalBottomSheet(onDismissRequest = { showSheet = false }) {
    ModalBottomSheetTitle("Choose an Option")
    // ... sheet content
}
```

--------------------------------

### Deserialize Button Contract

Source: https://github.com/yasanglass/kepko/blob/main/README.md

Example of decoding a JSON string into a `ButtonContract` and using it with `ContractButton`. This is an alternative to using the `Button` composable directly.

```json
{
  "on_click": "on-click",
  "text": "Text Value",
  "leading_icon": "info"
}
```

```kotlin
val contract = Json(from = kepkoJson).decodeFromString<ButtonContract>(jsonString)

ContractButton(
    contract = contract,
    onClick = { action: String -> println(action) },
)
```

```kotlin
Button(
    text = "Text Value",
    onClick = { println("on-click") },
    leadingIcon = NamedIcon.INFO.painter(),
)
```

--------------------------------

### HorizontalDivider Usage Example

Source: https://github.com/yasanglass/kepko/blob/main/_autodocs/api-reference/layouts-dialogs.md

Demonstrates how to use HorizontalDivider within a Column to separate text elements. Padding can be applied to the divider's modifier.

```kotlin
Column {
    Text("Section 1")
    HorizontalDivider(modifier = Modifier.padding(vertical = 8.dp))
    Text("Section 2")
}
```

--------------------------------

### Slider Usage Example

Source: https://github.com/yasanglass/kepko/blob/main/_autodocs/api-reference/components.md

Demonstrates how to use the Slider composable to manage a float value. The state is remembered and updated via the onValueChange lambda.

```kotlin
var value by remember { mutableStateOf(50f) }
Slider(
    value = value,
    onValueChange = { value = it },
    valueRange = 0f..100f,
)
```

--------------------------------

### Initialize PersistentKepkoTheme

Source: https://github.com/yasanglass/kepko/blob/main/_autodocs/configuration.md

Initialize the persistent Kepko theme to automatically save and load theme preferences using platform-specific storage. Requires experimental API opt-in.

```kotlin
import glass.yasan.kepko.persistence.PersistentKepkoTheme
import glass.yasan.kepko.foundation.annotation.ExperimentalKepkoApi

@OptIn(ExperimentalKepkoApi::class)
@Composable
fun App() {
    PersistentKepkoTheme {
        MyAppContent()
    }
}
```

--------------------------------

### SegmentedPicker Usage Example

Source: https://github.com/yasanglass/kepko/blob/main/_autodocs/api-reference/preferences.md

Demonstrates how to use the SegmentedPicker to switch between 'grid' and 'list' views. The selected view is managed using remember and mutableStateOf.

```kotlin
var viewMode by remember { mutableStateOf("grid") }
SegmentedPicker(
    items = listOf(
        SegmentedPickerItem("grid", "Grid"),
        SegmentedPickerItem("list", "List")
    ),
    selected = viewMode,
    onSelectionChange = { viewMode = it }
)
```

--------------------------------

### PreferenceCheckbox Example

Source: https://github.com/yasanglass/kepko/blob/main/_autodocs/api-reference/preferences.md

Use PreferenceCheckbox for a checkbox-style preference with a title and optional description. It requires the current checked state and a callback for state changes.

```kotlin
PreferenceCheckbox(
    title = "Show Notifications",
    checked = showNotif,
    onCheckedChange = { showNotif = it }
)
```

--------------------------------

### Customizing Theme Colors

Source: https://github.com/yasanglass/kepko/blob/main/_autodocs/README.md

Shows how to create and apply a custom color scheme to the Kepko theme.

```kotlin
val customColors = Colors(palette = myCustomPalette)
KepkoTheme(colors = customColors) { ... }
```

--------------------------------

### Get Default Theme Snapshot

Source: https://github.com/yasanglass/kepko/blob/main/_autodocs/api-reference/persistence.md

Retrieves a snapshot object representing the default theme settings. This can be used to reset the theme or as a base for modifications.

```kotlin
public fun getDefaultSnapshot(): Snapshot
```

--------------------------------

### Get Content Colors from Colors

Source: https://github.com/yasanglass/kepko/blob/main/_autodocs/types.md

Retrieves an array of content colors (content, contentSubtle, contentDisabled) from the Colors object. This is a composable extension function.

```kotlin
public fun Colors.getContentColors(): Array<Color>
```

--------------------------------

### Custom Palette Initialization

Source: https://github.com/yasanglass/kepko/blob/main/_autodocs/configuration.md

Allows for the explicit initialization of the Kepko theme with a specific `ColorPalette` and grayscale setting. Set `grayscale` to `true` for accessibility.

```kotlin
KepkoTheme(
    palette = ColorPalette.CATPPUCCIN_MACCHIATO,
    grayscale = false  // Set to true for accessibility
) {
    MyAppContent()
}
```

--------------------------------

### Get Layer Colors from Colors

Source: https://github.com/yasanglass/kepko/blob/main/_autodocs/types.md

Retrieves an array of layer/surface colors (foreground, midground, background) from the Colors object. This is a composable extension function.

```kotlin
public fun Colors.getLayerColors(): Array<Color>
```

--------------------------------

### Using KepkoJson for Deserialization

Source: https://github.com/yasanglass/kepko/blob/main/_autodocs/api-reference/serialization.md

Demonstrates how to create a new Json instance based on the pre-configured kepkoJson and use it to decode a JSON string into a data class. This ensures custom serializers are applied.

```kotlin
val json = Json(from = kepkoJson)
val contract = json.decodeFromString<ButtonContract>(jsonString)
```

--------------------------------

### Get Primary Palette

Source: https://github.com/yasanglass/kepko/blob/main/_autodocs/api-reference/persistence.md

Retrieves the user-selected color palette for a specific profile. Returns null if the system's default selection should be used.

```kotlin
public fun getPalettePrimary(profileId: String?): ColorPalette?
```

--------------------------------

### Usage of Default Shapes

Source: https://github.com/yasanglass/kepko/blob/main/_autodocs/api-reference/colors-shapes-dimensions.md

Demonstrates how to use the default Shapes instance when setting up the KepkoTheme. This ensures that all components within the theme utilize the standard corner radii.

```kotlin
val standardShapes = shapes()
KepkoTheme(shapes = standardShapes) {
    // Content uses standard corner radii
}
```

--------------------------------

### Composable Helper for Theme Previews

Source: https://github.com/yasanglass/kepko/blob/main/_autodocs/configuration.md

A helper composable to preview components across multiple color palettes (Light, Dark, Black). It wraps content in KepkoTheme with different palettes and a styled Surface.

```kotlin
@Composable
fun <T> ThemePreview(
    content: @Composable () -> Unit
)
{
    val palettes = listOf(
        ColorPalette.LIGHT,
        ColorPalette.DARK,
        ColorPalette.BLACK,
    )
    
    Column {
        palettes.forEach { palette ->
            KepkoTheme(palette = palette) {
                Surface(
                    Modifier.padding(8.dp),
                    containerColor = KepkoTheme.colors.foreground
                ) {
                    content()
                }
            }
        }
    }
}
```

--------------------------------

### Decode ButtonContract from JSON String

Source: https://github.com/yasanglass/kepko/blob/main/_autodocs/api-reference/serialization.md

Use this snippet to decode a JSON string into a ButtonContract object. Ensure you have the necessary kotlinx.serialization setup and the `kepkoJson` instance.

```kotlin
val jsonString = """
{
  "on_click": "save-action",
  "text": "Save",
  "container_color": "success",
  "leading_icon": "save",
  "enabled": true
}
""".trimIndent()

val contract = Json(from = kepkoJson).decodeFromString<ButtonContract>(jsonString)

ContractButton(
    contract = contract,
    onClick = { action: String -> handleAction(action) }
)
```

--------------------------------

### Get Semantic Colors from Colors

Source: https://github.com/yasanglass/kepko/blob/main/_autodocs/types.md

Retrieves an array of semantic colors (success, information, caution, danger) from the Colors object. This is a composable extension function.

```kotlin
public fun Colors.getSemanticColors(): Array<Color>
```

--------------------------------

### Add Kepko Dependencies to Project

Source: https://github.com/yasanglass/kepko/blob/main/README.md

Include the Kepko component and foundation libraries in your project's build file. Replace `<version>` with the desired version.

```kotlin
implementation("glass.yasan.kepko:component:<version>")
implementation("glass.yasan.kepko:foundation:<version>")
```

--------------------------------

### Import Serialization Module and Dependencies

Source: https://github.com/yasanglass/kepko/blob/main/_autodocs/configuration.md

Add the Kepko serialization module and the kotlinx.serialization JSON dependency to your project. Ensure these are included in your build configuration.

```kotlin
implementation("glass.yasan.kepko:serialization:1.0.0")

// Also requires kotlinx.serialization
implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.6.0")
```

--------------------------------

### Create Theme Snapshot

Source: https://github.com/yasanglass/kepko/blob/main/_autodocs/api-reference/persistence.md

Captures the current theme settings into an immutable snapshot object. This snapshot can be used later to restore these exact settings.

```kotlin
public fun toSnapshot(): Snapshot
```

```kotlin
val snapshot = manager.toSnapshot()
// snapshot contains: palettePrimary, paletteLight, paletteDark, grayscale, outline, roundness
```