Foundation Composables

/**
 * A layout composable that positions its children according to the Alignment.
 */
@Composable
fun Box(
    modifier: Modifier = Modifier,
    contentAlignment: Alignment = Alignment.TopStart,
    propagateMinConstraints: Boolean = false,
    content: @Composable BoxScope.() -> Unit
)

/**
 * Scope for the children of Box.
 */
interface BoxScope {
    /**
     * Align a child within the Box.
     */
    fun Modifier.align(alignment: Alignment): Modifier
    
    /**
     * Match the size of the Box's parent.
     */
    fun Modifier.matchParentSize(): Modifier
}

/**
 * A layout composable that places its children in a vertical sequence.
 */
@Composable
fun Column(
    modifier: Modifier = Modifier,
    verticalArrangement: Arrangement.Vertical = Arrangement.Top,
    horizontalAlignment: Alignment.Horizontal = Alignment.Start,
    content: @Composable ColumnScope.() -> Unit
)

/**
 * Scope for the children of Column.
 */
interface ColumnScope {
    /**
     * Align the element horizontally within the Column.
     */
    fun Modifier.align(alignment: Alignment.Horizontal): Modifier
    
    /**
     * Size the element's height to a fraction of the Column height.
     */
    fun Modifier.weight(
        weight: Float,
        fill: Boolean = true
    ): Modifier
}

/**
 * A layout composable that places its children in a horizontal sequence.
 */
@Composable
fun Row(
    modifier: Modifier = Modifier,
    horizontalArrangement: Arrangement.Horizontal = Arrangement.Start,
    verticalAlignment: Alignment.Vertical = Alignment.Top,
    content: @Composable RowScope.() -> Unit
)

/**
 * Scope for the children of Row.
 */
interface RowScope {
    /**
     * Align the element vertically within the Row.
     */
    fun Modifier.align(alignment: Alignment.Vertical): Modifier
    
    /**
     * Size the element's width to a fraction of the Row width.
     */
    fun Modifier.weight(
        weight: Float,
        fill: Boolean = true
    ): Modifier
    
    /**
     * Align the element vertically by its baseline.
     */
    fun Modifier.alignByBaseline(): Modifier
    
    /**
     * Align the element vertically by a custom baseline.
     */
    fun Modifier.alignBy(alignmentLineBlock: (Measured) -> Int): Modifier
}

/**
 * Arrangement options for distributing children within layout containers.
 */
object Arrangement {
    /**
     * Vertical arrangement options.
     */
    interface Vertical {
        fun arrange(totalSize: Int, sizes: IntArray, outPositions: IntArray)
    }
    
    /**
     * Horizontal arrangement options.
     */
    interface Horizontal {
        fun arrange(totalSize: Int, sizes: IntArray, layoutDirection: LayoutDirection, outPositions: IntArray)
    }
    
    // Vertical arrangements
    val Top: Vertical
    val Bottom: Vertical
    val Center: Vertical
    val SpaceEvenly: Vertical
    val SpaceBetween: Vertical
    val SpaceAround: Vertical
    
    // Horizontal arrangements
    val Start: Horizontal
    val End: Horizontal
    val Center: Horizontal
    val SpaceEvenly: Horizontal
    val SpaceBetween: Horizontal
    val SpaceAround: Horizontal
    
    /**
     * Arrange children with a specific spacing between them.
     */
    fun spacedBy(space: Dp): HorizontalOrVertical
    fun spacedBy(space: Dp, alignment: Alignment.Horizontal): Vertical
    fun spacedBy(space: Dp, alignment: Alignment.Vertical): Horizontal
}

// Basic layout containers
@Composable
fun LayoutExamples() {
    Column(
        modifier = Modifier.fillMaxSize(),
        verticalArrangement = Arrangement.spacedBy(16.dp),
        horizontalAlignment = Alignment.CenterHorizontally
    ) {
        // Box for overlapping content
        Box(
            modifier = Modifier.size(200.dp),
            contentAlignment = Alignment.Center
        ) {
            Box(
                modifier = Modifier
                    .fillMaxSize()
                    .background(Color.Blue)
            )
            Text(
                text = "Centered Text",
                color = Color.White
            )
        }
        
        // Row for horizontal layout
        Row(
            modifier = Modifier.fillMaxWidth(),
            horizontalArrangement = Arrangement.SpaceEvenly,
            verticalAlignment = Alignment.CenterVertically
        ) {
            Box(
                modifier = Modifier
                    .size(50.dp)
                    .background(Color.Red)
            )
            Box(
                modifier = Modifier
                    .size(50.dp)
                    .background(Color.Green)
            )
            Box(
                modifier = Modifier
                    .size(50.dp)
                    .background(Color.Blue)
            )
        }
        
        // Weighted elements
        Row(modifier = Modifier.fillMaxWidth()) {
            Box(
                modifier = Modifier
                    .weight(1f)
                    .height(50.dp)
                    .background(Color.Yellow)
            )
            Box(
                modifier = Modifier
                    .weight(2f)
                    .height(50.dp)
                    .background(Color.Orange)
            )
            Box(
                modifier = Modifier
                    .weight(1f)
                    .height(50.dp)
                    .background(Color.Purple)
            )
        }
    }
}

/**
 * A composable that displays text content.
 */
@Composable
fun Text(
    text: String,
    modifier: Modifier = Modifier,
    color: Color = Color.Unspecified,
    fontSize: TextUnit = TextUnit.Unspecified,
    fontStyle: FontStyle? = null,
    fontWeight: FontWeight? = null,
    fontFamily: FontFamily? = null,
    letterSpacing: TextUnit = TextUnit.Unspecified,
    textDecoration: TextDecoration? = null,
    textAlign: TextAlign? = null,
    lineHeight: TextUnit = TextUnit.Unspecified,
    overflow: TextOverflow = TextOverflow.Clip,
    softWrap: Boolean = true,
    maxLines: Int = Int.MAX_VALUE,
    minLines: Int = 1,
    onTextLayout: (TextLayoutResult) -> Unit = {},
    style: TextStyle = LocalTextStyle.current
)

/**
 * A composable that displays text with annotations and styling.
 */
@Composable
fun Text(
    text: AnnotatedString,
    modifier: Modifier = Modifier,
    color: Color = Color.Unspecified,
    fontSize: TextUnit = TextUnit.Unspecified,
    fontStyle: FontStyle? = null,
    fontWeight: FontWeight? = null,
    fontFamily: FontFamily? = null,
    letterSpacing: TextUnit = TextUnit.Unspecified,
    textDecoration: TextDecoration? = null,
    textAlign: TextAlign? = null,
    lineHeight: TextUnit = TextUnit.Unspecified,
    overflow: TextOverflow = TextOverflow.Clip,
    softWrap: Boolean = true,
    maxLines: Int = Int.MAX_VALUE,
    minLines: Int = 1,
    inlineContent: Map<String, InlineTextContent> = emptyMap(),
    onTextLayout: (TextLayoutResult) -> Unit = {},
    style: TextStyle = LocalTextStyle.current
)

/**
 * Basic text composable for selectable and clickable text.
 */
@Composable
fun BasicText(
    text: String,
    modifier: Modifier = Modifier,
    style: TextStyle = TextStyle.Default,
    onTextLayout: (TextLayoutResult) -> Unit = {},
    overflow: TextOverflow = TextOverflow.Clip,
    softWrap: Boolean = true,
    maxLines: Int = Int.MAX_VALUE,
    minLines: Int = 1
)

/**
 * Basic text composable for annotated strings.
 */
@Composable
fun BasicText(
    text: AnnotatedString,
    modifier: Modifier = Modifier,
    style: TextStyle = TextStyle.Default,
    onTextLayout: (TextLayoutResult) -> Unit = {},
    overflow: TextOverflow = TextOverflow.Clip,
    softWrap: Boolean = true,
    maxLines: Int = Int.MAX_VALUE,
    minLines: Int = 1,
    inlineContent: Map<String, InlineTextContent> = emptyMap()
)

// Text styling examples
@Composable
fun TextExamples() {
    Column(
        modifier = Modifier.padding(16.dp),
        verticalArrangement = Arrangement.spacedBy(8.dp)
    ) {
        // Basic text
        Text(text = "Hello, World!")
        
        // Styled text
        Text(
            text = "Styled Text",
            fontSize = 20.sp,
            fontWeight = FontWeight.Bold,
            color = Color.Blue,
            textAlign = TextAlign.Center,
            modifier = Modifier.fillMaxWidth()
        )
        
        // Text with overflow handling
        Text(
            text = "This is a very long text that will be truncated with ellipsis when it exceeds the available space",
            maxLines = 2,
            overflow = TextOverflow.Ellipsis,
            modifier = Modifier.width(200.dp)
        )
        
        // Rich text with annotations
        Text(
            text = buildAnnotatedString {
                append("This text has ")
                withStyle(style = SpanStyle(fontWeight = FontWeight.Bold)) {
                    append("bold")
                }
                append(" and ")
                withStyle(style = SpanStyle(fontStyle = FontStyle.Italic, color = Color.Red)) {
                    append("italic red")
                }
                append(" parts.")
            }
        )
    }
}

/**
 * Size modifier functions for constraining composable dimensions.
 */
fun Modifier.size(size: Dp): Modifier
fun Modifier.size(width: Dp, height: Dp): Modifier
fun Modifier.width(width: Dp): Modifier
fun Modifier.height(height: Dp): Modifier
fun Modifier.sizeIn(
    minWidth: Dp = Dp.Unspecified,
    minHeight: Dp = Dp.Unspecified,
    maxWidth: Dp = Dp.Unspecified,
    maxHeight: Dp = Dp.Unspecified
): Modifier

/**
 * Fill modifier functions for expanding to available space.
 */
fun Modifier.fillMaxSize(fraction: Float = 1.0f): Modifier
fun Modifier.fillMaxWidth(fraction: Float = 1.0f): Modifier
fun Modifier.fillMaxHeight(fraction: Float = 1.0f): Modifier

/**
 * Size constraints based on content.
 */
fun Modifier.wrapContentSize(
    align: Alignment = Alignment.Center,
    unbounded: Boolean = false
): Modifier
fun Modifier.wrapContentWidth(
    align: Alignment.Horizontal = Alignment.CenterHorizontally,
    unbounded: Boolean = false
): Modifier
fun Modifier.wrapContentHeight(
    align: Alignment.Vertical = Alignment.CenterVertically,
    unbounded: Boolean = false
): Modifier

/**
 * Default minimum size constraints.
 */
fun Modifier.defaultMinSize(
    minWidth: Dp = Dp.Unspecified,
    minHeight: Dp = Dp.Unspecified
): Modifier

/**
 * Required size modifiers that override parent constraints.
 */
fun Modifier.requiredSize(size: Dp): Modifier
fun Modifier.requiredSize(width: Dp, height: Dp): Modifier
fun Modifier.requiredWidth(width: Dp): Modifier
fun Modifier.requiredHeight(height: Dp): Modifier

/**
 * Padding modifier functions for adding space around content.
 */
fun Modifier.padding(all: Dp): Modifier
fun Modifier.padding(horizontal: Dp = 0.dp, vertical: Dp = 0.dp): Modifier
fun Modifier.padding(
    start: Dp = 0.dp,
    top: Dp = 0.dp,
    end: Dp = 0.dp,
    bottom: Dp = 0.dp
): Modifier
fun Modifier.padding(paddingValues: PaddingValues): Modifier

/**
 * Absolute padding (not affected by layout direction).
 */
fun Modifier.absolutePadding(
    left: Dp = 0.dp,
    top: Dp = 0.dp,
    right: Dp = 0.dp,
    bottom: Dp = 0.dp
): Modifier

/**
 * Offset modifier functions for positioning content.
 */
fun Modifier.offset(x: Dp = 0.dp, y: Dp = 0.dp): Modifier
fun Modifier.offset(offset: () -> IntOffset): Modifier
fun Modifier.absoluteOffset(x: Dp = 0.dp, y: Dp = 0.dp): Modifier

/**
 * Aspect ratio constraint.
 */
fun Modifier.aspectRatio(
    ratio: Float,
    matchHeightConstraintsFirst: Boolean = false
): Modifier

// Essential modifier examples
@Composable
fun ModifierExamples() {
    Column(
        modifier = Modifier
            .fillMaxSize()
            .padding(16.dp),
        verticalArrangement = Arrangement.spacedBy(16.dp)
    ) {
        // Size modifiers
        Box(
            modifier = Modifier
                .size(100.dp)
                .background(Color.Red)
        )
        
        Box(
            modifier = Modifier
                .size(width = 150.dp, height = 75.dp)
                .background(Color.Green)
        )
        
        // Fill modifiers
        Box(
            modifier = Modifier
                .fillMaxWidth()
                .height(50.dp)
                .background(Color.Blue)
        )
        
        // Padding variations
        Text(
            text = "Padded text",
            modifier = Modifier
                .background(Color.Yellow)
                .padding(all = 16.dp)
        )
        
        Text(
            text = "Asymmetric padding",
            modifier = Modifier
                .background(Color.Cyan)
                .padding(start = 32.dp, top = 8.dp, end = 16.dp, bottom = 24.dp)
        )
        
        // Offset positioning
        Box(modifier = Modifier.size(100.dp)) {
            Box(
                modifier = Modifier
                    .size(50.dp)
                    .background(Color.Red)
                    .offset(x = 25.dp, y = 25.dp)
            )
        }
        
        // Aspect ratio
        Box(
            modifier = Modifier
                .fillMaxWidth()
                .aspectRatio(16f / 9f)
                .background(Color.Gray)
        ) {
            Text(
                text = "16:9 Aspect Ratio",
                modifier = Modifier.align(Alignment.Center)
            )
        }
    }
}

/**
 * A composable that takes up space without drawing anything.
 */
@Composable
fun Spacer(modifier: Modifier)

// Using Spacer for layout spacing
@Composable
fun SpacerExample() {
    Column {
        Text("First item")
        
        // Add vertical space
        Spacer(modifier = Modifier.height(16.dp))
        
        Text("Second item")
        
        // Add flexible space that expands
        Spacer(modifier = Modifier.weight(1f))
        
        Text("Bottom item")
    }
    
    Row {
        Text("Left")
        
        // Add horizontal space
        Spacer(modifier = Modifier.width(24.dp))
        
        Text("Right")
        
        // Add flexible space
        Spacer(modifier = Modifier.weight(1f))
        
        Text("Far right")
    }
}

/**
 * Create a CompositionLocal with a default value.
 */
fun <T> staticCompositionLocalOf(defaultFactory: () -> T): ProvidableCompositionLocal<T>

/**
 * Create a CompositionLocal that triggers recomposition when changed.
 */
fun <T> compositionLocalOf(
    policy: SnapshotMutationPolicy<T> = structuralEqualityPolicy(),
    defaultFactory: () -> T
): ProvidableCompositionLocal<T>

/**
 * A CompositionLocal that can provide values.
 */
abstract class ProvidableCompositionLocal<T> : CompositionLocal<T> {
    /**
     * Provide a value for this CompositionLocal.
     */
    infix fun provides(value: T): ProvidedValue<T>
    
    /**
     * Provide a value for this CompositionLocal with a computation.
     */
    infix fun providesDefault(value: T): ProvidedValue<T>
}

/**
 * Provides values for CompositionLocals to the composition tree.
 */
@Composable
fun CompositionLocalProvider(
    vararg values: ProvidedValue<*>,
    content: @Composable () -> Unit
)

/**
 * Common CompositionLocals used throughout Compose UI.
 */
val LocalDensity: ProvidableCompositionLocal<Density>
val LocalLayoutDirection: ProvidableCompositionLocal<LayoutDirection>
val LocalTextStyle: ProvidableCompositionLocal<TextStyle>

// Creating and using CompositionLocals
val LocalCustomTheme = compositionLocalOf<CustomTheme> { 
    error("No CustomTheme provided") 
}

data class CustomTheme(
    val primaryColor: Color,
    val textColor: Color
)

@Composable
fun ThemedApp() {
    val theme = CustomTheme(
        primaryColor = Color.Blue,
        textColor = Color.Black
    )
    
    CompositionLocalProvider(LocalCustomTheme provides theme) {
        ThemedContent()
    }
}

@Composable
fun ThemedContent() {
    val theme = LocalCustomTheme.current
    val density = LocalDensity.current
    val layoutDirection = LocalLayoutDirection.current
    
    Column {
        Text(
            text = "Themed text",
            color = theme.textColor
        )
        
        Box(
            modifier = Modifier
                .size(100.dp)
                .background(theme.primaryColor)
        )
        
        Text("Layout direction: $layoutDirection")
        
        with(density) {
            Text("Density: ${density.density}")
        }
    }
}

/**
 * Vertically scrolling list that only composes and lays out currently visible items
 * @param modifier Modifier to be applied to the lazy column
 * @param state State object to control or observe the list's state
 * @param contentPadding Padding around the whole content
 * @param reverseLayout Whether to reverse the direction of scrolling and layout
 * @param verticalArrangement Vertical arrangement of the layout's children
 * @param horizontalAlignment Horizontal alignment of the layout's children
 * @param flingBehavior Logic describing fling behavior
 * @param userScrollEnabled Whether scroll with gestures or accessibility actions is allowed
 * @param content DSL for describing the lazy column's content
 */
@Composable
fun LazyColumn(
    modifier: Modifier = Modifier,
    state: LazyListState = rememberLazyListState(),
    contentPadding: PaddingValues = PaddingValues(0.dp),
    reverseLayout: Boolean = false,
    verticalArrangement: Arrangement.Vertical = if (!reverseLayout) Arrangement.Top else Arrangement.Bottom,
    horizontalAlignment: Alignment.Horizontal = Alignment.Start,
    flingBehavior: FlingBehavior = ScrollableDefaults.flingBehavior(),
    userScrollEnabled: Boolean = true,
    content: LazyListScope.() -> Unit
)

/**
 * Horizontally scrolling list that only composes and lays out currently visible items
 */
@Composable
fun LazyRow(
    modifier: Modifier = Modifier,
    state: LazyListState = rememberLazyListState(),
    contentPadding: PaddingValues = PaddingValues(0.dp),
    reverseLayout: Boolean = false,
    horizontalArrangement: Arrangement.Horizontal = if (!reverseLayout) Arrangement.Start else Arrangement.End,
    verticalAlignment: Alignment.Vertical = Alignment.Top,
    flingBehavior: FlingBehavior = ScrollableDefaults.flingBehavior(),
    userScrollEnabled: Boolean = true,
    content: LazyListScope.() -> Unit
)

/**
 * Lazy vertical grid layout composing and laying out only visible items
 */
@Composable
fun LazyVerticalGrid(
    columns: GridCells,
    modifier: Modifier = Modifier,
    state: LazyGridState = rememberLazyGridState(),
    contentPadding: PaddingValues = PaddingValues(0.dp),
    reverseLayout: Boolean = false,
    verticalArrangement: Arrangement.Vertical = if (!reverseLayout) Arrangement.Top else Arrangement.Bottom,
    horizontalArrangement: Arrangement.Horizontal = Arrangement.Start,
    flingBehavior: FlingBehavior = ScrollableDefaults.flingBehavior(),
    userScrollEnabled: Boolean = true,
    content: LazyGridScope.() -> Unit
)

/**
 * Defines the number of columns in lazy grids
 */
sealed class GridCells {
    /**
     * Fixed number of columns
     */
    class Fixed(val count: Int) : GridCells()
    
    /**
     * Adaptive columns based on minimum size
     */
    class Adaptive(val minSize: Dp) : GridCells()
    
    /**
     * Fixed size columns
     */
    class FixedSize(val size: Dp) : GridCells()
}

/**
 * DSL scope for LazyColumn and LazyRow content
 */
interface LazyListScope {
    /**
     * Add a single item to the lazy list
     */
    fun item(
        key: Any? = null,
        contentType: Any? = null,
        content: @Composable LazyItemScope.() -> Unit
    )
    
    /**
     * Add multiple items to the lazy list
     */
    fun items(
        count: Int,
        key: ((index: Int) -> Any)? = null,
        contentType: (index: Int) -> Any? = { null },
        itemContent: @Composable LazyItemScope.(index: Int) -> Unit
    )
    
    /**
     * Add items from a list
     */
    fun <T> items(
        items: List<T>,
        key: ((item: T) -> Any)? = null,
        contentType: (item: T) -> Any? = { null },
        itemContent: @Composable LazyItemScope.(item: T) -> Unit
    )
    
    /**
     * Add sticky header to the lazy list
     */
    fun stickyHeader(
        key: Any? = null,
        contentType: Any? = null,
        content: @Composable LazyItemScope.() -> Unit
    )
}

/**
 * State object for controlling lazy lists
 */
@Stable
interface LazyListState {
    val firstVisibleItemIndex: Int
    val firstVisibleItemScrollOffset: Int
    val layoutInfo: LazyListLayoutInfo
    val isScrollInProgress: Boolean
    val canScrollForward: Boolean
    val canScrollBackward: Boolean
    
    suspend fun animateScrollToItem(
        index: Int,
        scrollOffset: Int = 0
    )
    
    suspend fun scrollToItem(
        index: Int,
        scrollOffset: Int = 0
    )
}

/**
 * Remember a LazyListState
 */
@Composable
fun rememberLazyListState(
    initialFirstVisibleItemIndex: Int = 0,
    initialFirstVisibleItemScrollOffset: Int = 0
): LazyListState

// Basic lazy column with simple items
@Composable
fun SimpleLazyColumn() {
    val items = (1..1000).map { "Item $it" }
    
    LazyColumn {
        items(items) { item ->
            Text(
                text = item,
                modifier = Modifier
                    .fillMaxWidth()
                    .padding(16.dp)
            )
        }
    }
}

// Lazy column with different item types
@Composable
fun MixedContentLazyColumn() {
    LazyColumn {
        // Sticky header
        stickyHeader {
            Text(
                text = "Header",
                modifier = Modifier
                    .fillMaxWidth()
                    .background(Color.Gray)
                    .padding(16.dp),
                fontWeight = FontWeight.Bold
            )
        }
        
        // Individual items
        item {
            Text("Single item")
        }
        
        // Multiple items from data
        items(
            count = 100,
            key = { index -> "item_$index" }
        ) { index ->
            Card(
                modifier = Modifier
                    .fillMaxWidth()
                    .padding(horizontal = 16.dp, vertical = 4.dp)
            ) {
                Text(
                    text = "Card item $index",
                    modifier = Modifier.padding(16.dp)
                )
            }
        }
    }
}

// Lazy grid example
@Composable
fun PhotoGrid() {
    val photos = remember { (1..50).map { "Photo $it" } }
    
    LazyVerticalGrid(
        columns = GridCells.Adaptive(minSize = 128.dp),
        contentPadding = PaddingValues(8.dp),
        verticalArrangement = Arrangement.spacedBy(8.dp),
        horizontalArrangement = Arrangement.spacedBy(8.dp)
    ) {
        items(photos) { photo ->
            Card(
                modifier = Modifier
                    .fillMaxWidth()
                    .aspectRatio(1f)
            ) {
                Box(
                    modifier = Modifier.fillMaxSize(),
                    contentAlignment = Alignment.Center
                ) {
                    Text(photo)
                }
            }
        }
    }
}

// Lazy list with state control
@Composable
fun ControlledLazyColumn() {
    val listState = rememberLazyListState()
    val scope = rememberCoroutineScope()
    
    Column {
        Row {
            Button(
                onClick = {
                    scope.launch {
                        listState.animateScrollToItem(0)
                    }
                }
            ) {
                Text("Scroll to Top")
            }
            
            Button(
                onClick = {
                    scope.launch {
                        listState.animateScrollToItem(99)
                    }
                }
            ) {
                Text("Scroll to Bottom")
            }
        }
        
        LazyColumn(
            state = listState,
            modifier = Modifier.weight(1f)
        ) {
            items(100) { index ->
                Text(
                    text = "Item $index",
                    modifier = Modifier
                        .fillMaxWidth()
                        .padding(16.dp)
                )
            }
        }
    }
}