0
# Foundation Composables
1

2
Essential building blocks for creating user interfaces including layout containers, text display, interactive components, and essential modifiers for common UI patterns.
3

4
## Capabilities
5

6
### Layout Composables
7

8
Core layout containers for organizing UI elements in different arrangements.
9

10
```kotlin { .api }
11
/**
12
 * A layout composable that positions its children according to the Alignment.
13
 */
14
@Composable
15
fun Box(
16
    modifier: Modifier = Modifier,
17
    contentAlignment: Alignment = Alignment.TopStart,
18
    propagateMinConstraints: Boolean = false,
19
    content: @Composable BoxScope.() -> Unit
20
)
21

22
/**
23
 * Scope for the children of Box.
24
 */
25
interface BoxScope {
26
    /**
27
     * Align a child within the Box.
28
     */
29
    fun Modifier.align(alignment: Alignment): Modifier
30
    
31
    /**
32
     * Match the size of the Box's parent.
33
     */
34
    fun Modifier.matchParentSize(): Modifier
35
}
36

37
/**
38
 * A layout composable that places its children in a vertical sequence.
39
 */
40
@Composable
41
fun Column(
42
    modifier: Modifier = Modifier,
43
    verticalArrangement: Arrangement.Vertical = Arrangement.Top,
44
    horizontalAlignment: Alignment.Horizontal = Alignment.Start,
45
    content: @Composable ColumnScope.() -> Unit
46
)
47

48
/**
49
 * Scope for the children of Column.
50
 */
51
interface ColumnScope {
52
    /**
53
     * Align the element horizontally within the Column.
54
     */
55
    fun Modifier.align(alignment: Alignment.Horizontal): Modifier
56
    
57
    /**
58
     * Size the element's height to a fraction of the Column height.
59
     */
60
    fun Modifier.weight(
61
        weight: Float,
62
        fill: Boolean = true
63
    ): Modifier
64
}
65

66
/**
67
 * A layout composable that places its children in a horizontal sequence.
68
 */
69
@Composable
70
fun Row(
71
    modifier: Modifier = Modifier,
72
    horizontalArrangement: Arrangement.Horizontal = Arrangement.Start,
73
    verticalAlignment: Alignment.Vertical = Alignment.Top,
74
    content: @Composable RowScope.() -> Unit
75
)
76

77
/**
78
 * Scope for the children of Row.
79
 */
80
interface RowScope {
81
    /**
82
     * Align the element vertically within the Row.
83
     */
84
    fun Modifier.align(alignment: Alignment.Vertical): Modifier
85
    
86
    /**
87
     * Size the element's width to a fraction of the Row width.
88
     */
89
    fun Modifier.weight(
90
        weight: Float,
91
        fill: Boolean = true
92
    ): Modifier
93
    
94
    /**
95
     * Align the element vertically by its baseline.
96
     */
97
    fun Modifier.alignByBaseline(): Modifier
98
    
99
    /**
100
     * Align the element vertically by a custom baseline.
101
     */
102
    fun Modifier.alignBy(alignmentLineBlock: (Measured) -> Int): Modifier
103
}
104

105
/**
106
 * Arrangement options for distributing children within layout containers.
107
 */
108
object Arrangement {
109
    /**
110
     * Vertical arrangement options.
111
     */
112
    interface Vertical {
113
        fun arrange(totalSize: Int, sizes: IntArray, outPositions: IntArray)
114
    }
115
    
116
    /**
117
     * Horizontal arrangement options.
118
     */
119
    interface Horizontal {
120
        fun arrange(totalSize: Int, sizes: IntArray, layoutDirection: LayoutDirection, outPositions: IntArray)
121
    }
122
    
123
    // Vertical arrangements
124
    val Top: Vertical
125
    val Bottom: Vertical
126
    val Center: Vertical
127
    val SpaceEvenly: Vertical
128
    val SpaceBetween: Vertical
129
    val SpaceAround: Vertical
130
    
131
    // Horizontal arrangements
132
    val Start: Horizontal
133
    val End: Horizontal
134
    val Center: Horizontal
135
    val SpaceEvenly: Horizontal
136
    val SpaceBetween: Horizontal
137
    val SpaceAround: Horizontal
138
    
139
    /**
140
     * Arrange children with a specific spacing between them.
141
     */
142
    fun spacedBy(space: Dp): HorizontalOrVertical
143
    fun spacedBy(space: Dp, alignment: Alignment.Horizontal): Vertical
144
    fun spacedBy(space: Dp, alignment: Alignment.Vertical): Horizontal
145
}
146
```
147

148
**Usage Examples:**
149

150
```kotlin
151
// Basic layout containers
152
@Composable
153
fun LayoutExamples() {
154
    Column(
155
        modifier = Modifier.fillMaxSize(),
156
        verticalArrangement = Arrangement.spacedBy(16.dp),
157
        horizontalAlignment = Alignment.CenterHorizontally
158
    ) {
159
        // Box for overlapping content
160
        Box(
161
            modifier = Modifier.size(200.dp),
162
            contentAlignment = Alignment.Center
163
        ) {
164
            Box(
165
                modifier = Modifier
166
                    .fillMaxSize()
167
                    .background(Color.Blue)
168
            )
169
            Text(
170
                text = "Centered Text",
171
                color = Color.White
172
            )
173
        }
174
        
175
        // Row for horizontal layout
176
        Row(
177
            modifier = Modifier.fillMaxWidth(),
178
            horizontalArrangement = Arrangement.SpaceEvenly,
179
            verticalAlignment = Alignment.CenterVertically
180
        ) {
181
            Box(
182
                modifier = Modifier
183
                    .size(50.dp)
184
                    .background(Color.Red)
185
            )
186
            Box(
187
                modifier = Modifier
188
                    .size(50.dp)
189
                    .background(Color.Green)
190
            )
191
            Box(
192
                modifier = Modifier
193
                    .size(50.dp)
194
                    .background(Color.Blue)
195
            )
196
        }
197
        
198
        // Weighted elements
199
        Row(modifier = Modifier.fillMaxWidth()) {
200
            Box(
201
                modifier = Modifier
202
                    .weight(1f)
203
                    .height(50.dp)
204
                    .background(Color.Yellow)
205
            )
206
            Box(
207
                modifier = Modifier
208
                    .weight(2f)
209
                    .height(50.dp)
210
                    .background(Color.Orange)
211
            )
212
            Box(
213
                modifier = Modifier
214
                    .weight(1f)
215
                    .height(50.dp)
216
                    .background(Color.Purple)
217
            )
218
        }
219
    }
220
}
221
```
222

223
### Text Display
224

225
Text rendering composable with comprehensive styling and configuration options.
226

227
```kotlin { .api }
228
/**
229
 * A composable that displays text content.
230
 */
231
@Composable
232
fun Text(
233
    text: String,
234
    modifier: Modifier = Modifier,
235
    color: Color = Color.Unspecified,
236
    fontSize: TextUnit = TextUnit.Unspecified,
237
    fontStyle: FontStyle? = null,
238
    fontWeight: FontWeight? = null,
239
    fontFamily: FontFamily? = null,
240
    letterSpacing: TextUnit = TextUnit.Unspecified,
241
    textDecoration: TextDecoration? = null,
242
    textAlign: TextAlign? = null,
243
    lineHeight: TextUnit = TextUnit.Unspecified,
244
    overflow: TextOverflow = TextOverflow.Clip,
245
    softWrap: Boolean = true,
246
    maxLines: Int = Int.MAX_VALUE,
247
    minLines: Int = 1,
248
    onTextLayout: (TextLayoutResult) -> Unit = {},
249
    style: TextStyle = LocalTextStyle.current
250
)
251

252
/**
253
 * A composable that displays text with annotations and styling.
254
 */
255
@Composable
256
fun Text(
257
    text: AnnotatedString,
258
    modifier: Modifier = Modifier,
259
    color: Color = Color.Unspecified,
260
    fontSize: TextUnit = TextUnit.Unspecified,
261
    fontStyle: FontStyle? = null,
262
    fontWeight: FontWeight? = null,
263
    fontFamily: FontFamily? = null,
264
    letterSpacing: TextUnit = TextUnit.Unspecified,
265
    textDecoration: TextDecoration? = null,
266
    textAlign: TextAlign? = null,
267
    lineHeight: TextUnit = TextUnit.Unspecified,
268
    overflow: TextOverflow = TextOverflow.Clip,
269
    softWrap: Boolean = true,
270
    maxLines: Int = Int.MAX_VALUE,
271
    minLines: Int = 1,
272
    inlineContent: Map<String, InlineTextContent> = emptyMap(),
273
    onTextLayout: (TextLayoutResult) -> Unit = {},
274
    style: TextStyle = LocalTextStyle.current
275
)
276

277
/**
278
 * Basic text composable for selectable and clickable text.
279
 */
280
@Composable
281
fun BasicText(
282
    text: String,
283
    modifier: Modifier = Modifier,
284
    style: TextStyle = TextStyle.Default,
285
    onTextLayout: (TextLayoutResult) -> Unit = {},
286
    overflow: TextOverflow = TextOverflow.Clip,
287
    softWrap: Boolean = true,
288
    maxLines: Int = Int.MAX_VALUE,
289
    minLines: Int = 1
290
)
291

292
/**
293
 * Basic text composable for annotated strings.
294
 */
295
@Composable
296
fun BasicText(
297
    text: AnnotatedString,
298
    modifier: Modifier = Modifier,
299
    style: TextStyle = TextStyle.Default,
300
    onTextLayout: (TextLayoutResult) -> Unit = {},
301
    overflow: TextOverflow = TextOverflow.Clip,
302
    softWrap: Boolean = true,
303
    maxLines: Int = Int.MAX_VALUE,
304
    minLines: Int = 1,
305
    inlineContent: Map<String, InlineTextContent> = emptyMap()
306
)
307
```
308

309
**Usage Examples:**
310

311
```kotlin
312
// Text styling examples
313
@Composable
314
fun TextExamples() {
315
    Column(
316
        modifier = Modifier.padding(16.dp),
317
        verticalArrangement = Arrangement.spacedBy(8.dp)
318
    ) {
319
        // Basic text
320
        Text(text = "Hello, World!")
321
        
322
        // Styled text
323
        Text(
324
            text = "Styled Text",
325
            fontSize = 20.sp,
326
            fontWeight = FontWeight.Bold,
327
            color = Color.Blue,
328
            textAlign = TextAlign.Center,
329
            modifier = Modifier.fillMaxWidth()
330
        )
331
        
332
        // Text with overflow handling
333
        Text(
334
            text = "This is a very long text that will be truncated with ellipsis when it exceeds the available space",
335
            maxLines = 2,
336
            overflow = TextOverflow.Ellipsis,
337
            modifier = Modifier.width(200.dp)
338
        )
339
        
340
        // Rich text with annotations
341
        Text(
342
            text = buildAnnotatedString {
343
                append("This text has ")
344
                withStyle(style = SpanStyle(fontWeight = FontWeight.Bold)) {
345
                    append("bold")
346
                }
347
                append(" and ")
348
                withStyle(style = SpanStyle(fontStyle = FontStyle.Italic, color = Color.Red)) {
349
                    append("italic red")
350
                }
351
                append(" parts.")
352
            }
353
        )
354
    }
355
}
356
```
357

358
### Essential Modifier Functions
359

360
Core modifier functions for common UI patterns and behaviors.
361

362
```kotlin { .api }
363
/**
364
 * Size modifier functions for constraining composable dimensions.
365
 */
366
fun Modifier.size(size: Dp): Modifier
367
fun Modifier.size(width: Dp, height: Dp): Modifier
368
fun Modifier.width(width: Dp): Modifier
369
fun Modifier.height(height: Dp): Modifier
370
fun Modifier.sizeIn(
371
    minWidth: Dp = Dp.Unspecified,
372
    minHeight: Dp = Dp.Unspecified,
373
    maxWidth: Dp = Dp.Unspecified,
374
    maxHeight: Dp = Dp.Unspecified
375
): Modifier
376

377
/**
378
 * Fill modifier functions for expanding to available space.
379
 */
380
fun Modifier.fillMaxSize(fraction: Float = 1.0f): Modifier
381
fun Modifier.fillMaxWidth(fraction: Float = 1.0f): Modifier
382
fun Modifier.fillMaxHeight(fraction: Float = 1.0f): Modifier
383

384
/**
385
 * Size constraints based on content.
386
 */
387
fun Modifier.wrapContentSize(
388
    align: Alignment = Alignment.Center,
389
    unbounded: Boolean = false
390
): Modifier
391
fun Modifier.wrapContentWidth(
392
    align: Alignment.Horizontal = Alignment.CenterHorizontally,
393
    unbounded: Boolean = false
394
): Modifier
395
fun Modifier.wrapContentHeight(
396
    align: Alignment.Vertical = Alignment.CenterVertically,
397
    unbounded: Boolean = false
398
): Modifier
399

400
/**
401
 * Default minimum size constraints.
402
 */
403
fun Modifier.defaultMinSize(
404
    minWidth: Dp = Dp.Unspecified,
405
    minHeight: Dp = Dp.Unspecified
406
): Modifier
407

408
/**
409
 * Required size modifiers that override parent constraints.
410
 */
411
fun Modifier.requiredSize(size: Dp): Modifier
412
fun Modifier.requiredSize(width: Dp, height: Dp): Modifier
413
fun Modifier.requiredWidth(width: Dp): Modifier
414
fun Modifier.requiredHeight(height: Dp): Modifier
415

416
/**
417
 * Padding modifier functions for adding space around content.
418
 */
419
fun Modifier.padding(all: Dp): Modifier
420
fun Modifier.padding(horizontal: Dp = 0.dp, vertical: Dp = 0.dp): Modifier
421
fun Modifier.padding(
422
    start: Dp = 0.dp,
423
    top: Dp = 0.dp,
424
    end: Dp = 0.dp,
425
    bottom: Dp = 0.dp
426
): Modifier
427
fun Modifier.padding(paddingValues: PaddingValues): Modifier
428

429
/**
430
 * Absolute padding (not affected by layout direction).
431
 */
432
fun Modifier.absolutePadding(
433
    left: Dp = 0.dp,
434
    top: Dp = 0.dp,
435
    right: Dp = 0.dp,
436
    bottom: Dp = 0.dp
437
): Modifier
438

439
/**
440
 * Offset modifier functions for positioning content.
441
 */
442
fun Modifier.offset(x: Dp = 0.dp, y: Dp = 0.dp): Modifier
443
fun Modifier.offset(offset: () -> IntOffset): Modifier
444
fun Modifier.absoluteOffset(x: Dp = 0.dp, y: Dp = 0.dp): Modifier
445

446
/**
447
 * Aspect ratio constraint.
448
 */
449
fun Modifier.aspectRatio(
450
    ratio: Float,
451
    matchHeightConstraintsFirst: Boolean = false
452
): Modifier
453
```
454

455
**Usage Examples:**
456

457
```kotlin
458
// Essential modifier examples
459
@Composable
460
fun ModifierExamples() {
461
    Column(
462
        modifier = Modifier
463
            .fillMaxSize()
464
            .padding(16.dp),
465
        verticalArrangement = Arrangement.spacedBy(16.dp)
466
    ) {
467
        // Size modifiers
468
        Box(
469
            modifier = Modifier
470
                .size(100.dp)
471
                .background(Color.Red)
472
        )
473
        
474
        Box(
475
            modifier = Modifier
476
                .size(width = 150.dp, height = 75.dp)
477
                .background(Color.Green)
478
        )
479
        
480
        // Fill modifiers
481
        Box(
482
            modifier = Modifier
483
                .fillMaxWidth()
484
                .height(50.dp)
485
                .background(Color.Blue)
486
        )
487
        
488
        // Padding variations
489
        Text(
490
            text = "Padded text",
491
            modifier = Modifier
492
                .background(Color.Yellow)
493
                .padding(all = 16.dp)
494
        )
495
        
496
        Text(
497
            text = "Asymmetric padding",
498
            modifier = Modifier
499
                .background(Color.Cyan)
500
                .padding(start = 32.dp, top = 8.dp, end = 16.dp, bottom = 24.dp)
501
        )
502
        
503
        // Offset positioning
504
        Box(modifier = Modifier.size(100.dp)) {
505
            Box(
506
                modifier = Modifier
507
                    .size(50.dp)
508
                    .background(Color.Red)
509
                    .offset(x = 25.dp, y = 25.dp)
510
            )
511
        }
512
        
513
        // Aspect ratio
514
        Box(
515
            modifier = Modifier
516
                .fillMaxWidth()
517
                .aspectRatio(16f / 9f)
518
                .background(Color.Gray)
519
        ) {
520
            Text(
521
                text = "16:9 Aspect Ratio",
522
                modifier = Modifier.align(Alignment.Center)
523
            )
524
        }
525
    }
526
}
527
```
528

529
### Spacer Composable
530

531
Utility composable for adding empty space in layouts.
532

533
```kotlin { .api }
534
/**
535
 * A composable that takes up space without drawing anything.
536
 */
537
@Composable
538
fun Spacer(modifier: Modifier)
539
```
540

541
**Usage Examples:**
542

543
```kotlin
544
// Using Spacer for layout spacing
545
@Composable
546
fun SpacerExample() {
547
    Column {
548
        Text("First item")
549
        
550
        // Add vertical space
551
        Spacer(modifier = Modifier.height(16.dp))
552
        
553
        Text("Second item")
554
        
555
        // Add flexible space that expands
556
        Spacer(modifier = Modifier.weight(1f))
557
        
558
        Text("Bottom item")
559
    }
560
    
561
    Row {
562
        Text("Left")
563
        
564
        // Add horizontal space
565
        Spacer(modifier = Modifier.width(24.dp))
566
        
567
        Text("Right")
568
        
569
        // Add flexible space
570
        Spacer(modifier = Modifier.weight(1f))
571
        
572
        Text("Far right")
573
    }
574
}
575
```
576

577
### CompositionLocal System
578

579
System for passing data down the composition tree without explicit parameter passing.
580

581
```kotlin { .api }
582
/**
583
 * Create a CompositionLocal with a default value.
584
 */
585
fun <T> staticCompositionLocalOf(defaultFactory: () -> T): ProvidableCompositionLocal<T>
586

587
/**
588
 * Create a CompositionLocal that triggers recomposition when changed.
589
 */
590
fun <T> compositionLocalOf(
591
    policy: SnapshotMutationPolicy<T> = structuralEqualityPolicy(),
592
    defaultFactory: () -> T
593
): ProvidableCompositionLocal<T>
594

595
/**
596
 * A CompositionLocal that can provide values.
597
 */
598
abstract class ProvidableCompositionLocal<T> : CompositionLocal<T> {
599
    /**
600
     * Provide a value for this CompositionLocal.
601
     */
602
    infix fun provides(value: T): ProvidedValue<T>
603
    
604
    /**
605
     * Provide a value for this CompositionLocal with a computation.
606
     */
607
    infix fun providesDefault(value: T): ProvidedValue<T>
608
}
609

610
/**
611
 * Provides values for CompositionLocals to the composition tree.
612
 */
613
@Composable
614
fun CompositionLocalProvider(
615
    vararg values: ProvidedValue<*>,
616
    content: @Composable () -> Unit
617
)
618

619
/**
620
 * Common CompositionLocals used throughout Compose UI.
621
 */
622
val LocalDensity: ProvidableCompositionLocal<Density>
623
val LocalLayoutDirection: ProvidableCompositionLocal<LayoutDirection>
624
val LocalTextStyle: ProvidableCompositionLocal<TextStyle>
625
```
626

627
**Usage Examples:**
628

629
```kotlin
630
// Creating and using CompositionLocals
631
val LocalCustomTheme = compositionLocalOf<CustomTheme> { 
632
    error("No CustomTheme provided") 
633
}
634

635
data class CustomTheme(
636
    val primaryColor: Color,
637
    val textColor: Color
638
)
639

640
@Composable
641
fun ThemedApp() {
642
    val theme = CustomTheme(
643
        primaryColor = Color.Blue,
644
        textColor = Color.Black
645
    )
646
    
647
    CompositionLocalProvider(LocalCustomTheme provides theme) {
648
        ThemedContent()
649
    }
650
}
651

652
@Composable
653
fun ThemedContent() {
654
    val theme = LocalCustomTheme.current
655
    val density = LocalDensity.current
656
    val layoutDirection = LocalLayoutDirection.current
657
    
658
    Column {
659
        Text(
660
            text = "Themed text",
661
            color = theme.textColor
662
        )
663
        
664
        Box(
665
            modifier = Modifier
666
                .size(100.dp)
667
                .background(theme.primaryColor)
668
        )
669
        
670
        Text("Layout direction: $layoutDirection")
671
        
672
        with(density) {
673
            Text("Density: ${density.density}")
674
        }
675
    }
676
}
677
```
678

679
### Lazy Layouts
680

681
High-performance lazy loading composables for displaying large datasets efficiently with on-demand composition and virtualization.
682

683
```kotlin { .api }
684
/**
685
 * Vertically scrolling list that only composes and lays out currently visible items
686
 * @param modifier Modifier to be applied to the lazy column
687
 * @param state State object to control or observe the list's state
688
 * @param contentPadding Padding around the whole content
689
 * @param reverseLayout Whether to reverse the direction of scrolling and layout
690
 * @param verticalArrangement Vertical arrangement of the layout's children
691
 * @param horizontalAlignment Horizontal alignment of the layout's children
692
 * @param flingBehavior Logic describing fling behavior
693
 * @param userScrollEnabled Whether scroll with gestures or accessibility actions is allowed
694
 * @param content DSL for describing the lazy column's content
695
 */
696
@Composable
697
fun LazyColumn(
698
    modifier: Modifier = Modifier,
699
    state: LazyListState = rememberLazyListState(),
700
    contentPadding: PaddingValues = PaddingValues(0.dp),
701
    reverseLayout: Boolean = false,
702
    verticalArrangement: Arrangement.Vertical = if (!reverseLayout) Arrangement.Top else Arrangement.Bottom,
703
    horizontalAlignment: Alignment.Horizontal = Alignment.Start,
704
    flingBehavior: FlingBehavior = ScrollableDefaults.flingBehavior(),
705
    userScrollEnabled: Boolean = true,
706
    content: LazyListScope.() -> Unit
707
)
708

709
/**
710
 * Horizontally scrolling list that only composes and lays out currently visible items
711
 */
712
@Composable
713
fun LazyRow(
714
    modifier: Modifier = Modifier,
715
    state: LazyListState = rememberLazyListState(),
716
    contentPadding: PaddingValues = PaddingValues(0.dp),
717
    reverseLayout: Boolean = false,
718
    horizontalArrangement: Arrangement.Horizontal = if (!reverseLayout) Arrangement.Start else Arrangement.End,
719
    verticalAlignment: Alignment.Vertical = Alignment.Top,
720
    flingBehavior: FlingBehavior = ScrollableDefaults.flingBehavior(),
721
    userScrollEnabled: Boolean = true,
722
    content: LazyListScope.() -> Unit
723
)
724

725
/**
726
 * Lazy vertical grid layout composing and laying out only visible items
727
 */
728
@Composable
729
fun LazyVerticalGrid(
730
    columns: GridCells,
731
    modifier: Modifier = Modifier,
732
    state: LazyGridState = rememberLazyGridState(),
733
    contentPadding: PaddingValues = PaddingValues(0.dp),
734
    reverseLayout: Boolean = false,
735
    verticalArrangement: Arrangement.Vertical = if (!reverseLayout) Arrangement.Top else Arrangement.Bottom,
736
    horizontalArrangement: Arrangement.Horizontal = Arrangement.Start,
737
    flingBehavior: FlingBehavior = ScrollableDefaults.flingBehavior(),
738
    userScrollEnabled: Boolean = true,
739
    content: LazyGridScope.() -> Unit
740
)
741

742
/**
743
 * Defines the number of columns in lazy grids
744
 */
745
sealed class GridCells {
746
    /**
747
     * Fixed number of columns
748
     */
749
    class Fixed(val count: Int) : GridCells()
750
    
751
    /**
752
     * Adaptive columns based on minimum size
753
     */
754
    class Adaptive(val minSize: Dp) : GridCells()
755
    
756
    /**
757
     * Fixed size columns
758
     */
759
    class FixedSize(val size: Dp) : GridCells()
760
}
761

762
/**
763
 * DSL scope for LazyColumn and LazyRow content
764
 */
765
interface LazyListScope {
766
    /**
767
     * Add a single item to the lazy list
768
     */
769
    fun item(
770
        key: Any? = null,
771
        contentType: Any? = null,
772
        content: @Composable LazyItemScope.() -> Unit
773
    )
774
    
775
    /**
776
     * Add multiple items to the lazy list
777
     */
778
    fun items(
779
        count: Int,
780
        key: ((index: Int) -> Any)? = null,
781
        contentType: (index: Int) -> Any? = { null },
782
        itemContent: @Composable LazyItemScope.(index: Int) -> Unit
783
    )
784
    
785
    /**
786
     * Add items from a list
787
     */
788
    fun <T> items(
789
        items: List<T>,
790
        key: ((item: T) -> Any)? = null,
791
        contentType: (item: T) -> Any? = { null },
792
        itemContent: @Composable LazyItemScope.(item: T) -> Unit
793
    )
794
    
795
    /**
796
     * Add sticky header to the lazy list
797
     */
798
    fun stickyHeader(
799
        key: Any? = null,
800
        contentType: Any? = null,
801
        content: @Composable LazyItemScope.() -> Unit
802
    )
803
}
804

805
/**
806
 * State object for controlling lazy lists
807
 */
808
@Stable
809
interface LazyListState {
810
    val firstVisibleItemIndex: Int
811
    val firstVisibleItemScrollOffset: Int
812
    val layoutInfo: LazyListLayoutInfo
813
    val isScrollInProgress: Boolean
814
    val canScrollForward: Boolean
815
    val canScrollBackward: Boolean
816
    
817
    suspend fun animateScrollToItem(
818
        index: Int,
819
        scrollOffset: Int = 0
820
    )
821
    
822
    suspend fun scrollToItem(
823
        index: Int,
824
        scrollOffset: Int = 0
825
    )
826
}
827

828
/**
829
 * Remember a LazyListState
830
 */
831
@Composable
832
fun rememberLazyListState(
833
    initialFirstVisibleItemIndex: Int = 0,
834
    initialFirstVisibleItemScrollOffset: Int = 0
835
): LazyListState
836
```
837

838
**Usage Examples:**
839

840
```kotlin
841
// Basic lazy column with simple items
842
@Composable
843
fun SimpleLazyColumn() {
844
    val items = (1..1000).map { "Item $it" }
845
    
846
    LazyColumn {
847
        items(items) { item ->
848
            Text(
849
                text = item,
850
                modifier = Modifier
851
                    .fillMaxWidth()
852
                    .padding(16.dp)
853
            )
854
        }
855
    }
856
}
857

858
// Lazy column with different item types
859
@Composable
860
fun MixedContentLazyColumn() {
861
    LazyColumn {
862
        // Sticky header
863
        stickyHeader {
864
            Text(
865
                text = "Header",
866
                modifier = Modifier
867
                    .fillMaxWidth()
868
                    .background(Color.Gray)
869
                    .padding(16.dp),
870
                fontWeight = FontWeight.Bold
871
            )
872
        }
873
        
874
        // Individual items
875
        item {
876
            Text("Single item")
877
        }
878
        
879
        // Multiple items from data
880
        items(
881
            count = 100,
882
            key = { index -> "item_$index" }
883
        ) { index ->
884
            Card(
885
                modifier = Modifier
886
                    .fillMaxWidth()
887
                    .padding(horizontal = 16.dp, vertical = 4.dp)
888
            ) {
889
                Text(
890
                    text = "Card item $index",
891
                    modifier = Modifier.padding(16.dp)
892
                )
893
            }
894
        }
895
    }
896
}
897

898
// Lazy grid example
899
@Composable
900
fun PhotoGrid() {
901
    val photos = remember { (1..50).map { "Photo $it" } }
902
    
903
    LazyVerticalGrid(
904
        columns = GridCells.Adaptive(minSize = 128.dp),
905
        contentPadding = PaddingValues(8.dp),
906
        verticalArrangement = Arrangement.spacedBy(8.dp),
907
        horizontalArrangement = Arrangement.spacedBy(8.dp)
908
    ) {
909
        items(photos) { photo ->
910
            Card(
911
                modifier = Modifier
912
                    .fillMaxWidth()
913
                    .aspectRatio(1f)
914
            ) {
915
                Box(
916
                    modifier = Modifier.fillMaxSize(),
917
                    contentAlignment = Alignment.Center
918
                ) {
919
                    Text(photo)
920
                }
921
            }
922
        }
923
    }
924
}
925

926
// Lazy list with state control
927
@Composable
928
fun ControlledLazyColumn() {
929
    val listState = rememberLazyListState()
930
    val scope = rememberCoroutineScope()
931
    
932
    Column {
933
        Row {
934
            Button(
935
                onClick = {
936
                    scope.launch {
937
                        listState.animateScrollToItem(0)
938
                    }
939
                }
940
            ) {
941
                Text("Scroll to Top")
942
            }
943
            
944
            Button(
945
                onClick = {
946
                    scope.launch {
947
                        listState.animateScrollToItem(99)
948
                    }
949
                }
950
            ) {
951
                Text("Scroll to Bottom")
952
            }
953
        }
954
        
955
        LazyColumn(
956
            state = listState,
957
            modifier = Modifier.weight(1f)
958
        ) {
959
            items(100) { index ->
960
                Text(
961
                    text = "Item $index",
962
                    modifier = Modifier
963
                        .fillMaxWidth()
964
                        .padding(16.dp)
965
                )
966
            }
967
        }
968
    }
969
}
970
```