@momo-kits/native-kits 0.162.49-debug → 0.162.50-debug

package/CLAUDE.md

@@ -71,7 +71,7 @@ Publishing is automated (`publish.sh` + GitLab CI on `[ci build]` / `main`). Do
 ## Screen layout / iPhone Duo (port of RN `useScreenLayout`, momo-kits !664)
 
 - `layout/ScreenLayout.kt`: `getScreenLayout()` returns window size, raw top/bottom + side insets, `contentWidth`, header geometry, the iPhone Duo `sideBar` and `duoTopInset`. `NavigationContainer` computes it once and provides `LocalScreenLayout`; reactive to fold/unfold and rotation (window size + `WindowInsets`). Metrics (`DuoMetrics`, 72pt iPhone header floor, 20pt status-bar threshold) mirror RN `Layout/utils.ts` — change both together.
-- iPhone-only: everything gates on `isPhoneIdiom()` (`platform/`), never on "iOS", so iPad windows keep the regular layout. Two detectors, as in RN: `isIPhoneDuo` (window aspect < 1.6 or asymmetric side insets) drives layout; `isIPhoneDuoDevice` (Apple's foldable check: a `.division` reserved region, queried with include-inactive; Swift also latches on `UIHingeInteraction`) drives popups, modal and bottom sheet.
+- iPhone-only: everything gates on `isPhoneIdiom()` (`platform/`), never on "iOS", so iPad windows keep the regular layout. Two detectors, as in RN: `isIPhoneDuo` (window aspect < 1.6 or asymmetric side insets) drives layout; `isIPhoneDuoDevice` (Apple's foldable check: a `.division` reserved region, queried with include-inactive; Swift also latches on `UIHingeInteraction`; or asymmetric side insets, since the outer display reports no hinge) drives popups, modal and bottom sheet.
 - Header height is `headerHeight` (not `AppStatusBar + HEADER_HEIGHT`); the bar row is `headerBarHeight` and starts `headerStatusBarHeight` below the window top. When the status bar is off the top edge (iPhone landscape, iPhone Duo) `headerStatusBarHeight` is 0 so the title stays centered — except on the Duo outer display: in portrait the header is 76pt and the row starts at 14pt so the title centers on the camera punchout; in landscape the row centers on the camera when it sits at the top end of the strip (else on the back button) and the header reaches 8pt below the back button.
 - iPhone Duo inner display in portrait (status bar on top): the header row shares the status bar band — `headerHeight` 94pt (2 × the clock digits' y 47), `headerStatusBarHeight` 0 — and `ScreenLayout.statusBarClearance` keeps it between the clock / battery clusters (from reserved regions, else 128pt on the right). Back and toolkit use the 48pt side bar controls laid out horizontally (`ToolkitLayout.SideBarRow`); the collapsed search and a centered title stay clear of the clusters. Port of momo-kits `90af33ba2`.
 - iPhone Duo with a side strip ≥ 60pt: back + toolkit leave the bar for `HeaderSideBar` (`navigation/component/SideBar.kt`, 48pt glass controls); custom header-right stays in the bar. `sideBar.top` is 170pt in portrait, 120pt on the inner display in landscape (height ≥ 600), 24pt on the outer display in landscape, or below the header when the status bar is on top; UIKit's `statusBarFrame` is useless on Duo. Unlike RN the column is clamped above footer (24pt gap) / rail (12pt gap).
@@ -80,8 +80,10 @@ Publishing is automated (`publish.sh` + GitLab CI on `[ci build]` / `main`). Do
 - Bar compression (`bottomtab/DuoBarCompression.kt`, HIG "Vertical controls"): when toolbar + rail don't fit in the strip, one is compressed — the toolkit into a `navigation_menu` button, the rail into one button showing the current tab — and tapping it swaps them; `BottomTab(compressionBehavior)` picks which starts compressed. If neither fits beside the other compressed, both rest compressed and a tap opens one for a moment. Side bar columns report their full height (0 when the screen puts nothing there) so the decision follows each screen's toolkit.
 - Glass header: on Duo with a side bar, Default/Extended headers without search and with a `ScrollState` let content scroll under the bar (`usesDuoGlassHeader`); the bar fades in a translucent surface + hairline over 16pt (Compose has no backdrop blur — RN's fallback look), the gradient leaves with the content.
 - Quick return header: glass headers and Animated headers (with a `ScrollState`) on the Duo side bar layout slide out with the content and back in on a reverse scroll; a half-shown header settles in or out once the scroll stops. The side bar is drawn apart from the header, so it stays put.
-- Overlays on Duo: popups cap at 440pt wide and the room between `duoTopInset` and the bottom inset (body scrolls, actions stay); modal centers inside that room; bottom sheet uses the window height, centers at width ≥ 600 and pads by side insets in landscape.
+- Overlays on Duo: the modal sits inside the safe area (all four insets, so clear of the side toolbar strip) and caps its content at `duoModalMaxWidth` / `duoModalMaxHeight` (440 × 640pt, at least XL off the safe area); popups fill that width with radius XL and drop their own side padding (body scrolls, actions stay). Snackbars keep clear of the strip.
+- Bottom sheet on Duo: radius XL, window height, centered at width ≥ 600 (inner display, buttons stay in the header row). Below that (outer display) it floats `Spacing.M` off the side edges, pads header/content/footer by `inset − M`, and a `Title` header moves back / close into 48pt side bar buttons on the strip part of the sheet (HIG: sheet controls go vertical on the outer display) when the strip fits one; they follow the header row while the sheet is short and stay below `sideBar.top` when it is tall. `BottomHeader.Title(onBack)` / `.title(onBack:)` closes the sheet, then runs (RN `leftOptions.onPressIconLeft`).
 - Font scale deliberately uses the short side (`min(w, h)`), unlike RN which reads the window width — landscape must not inflate every font.
+- Font scale measures the **window**, never `UIScreen.main`: on iPhone Duo the main screen stays on one display while the window follows the one in use. Compose iOS `getScreenDimensions()` reads `LocalWindowInfo.containerSize` (recomposes on fold/unfold); SwiftUI `DesignSystemKits` KVO-observes each `UIWindowScene.effectiveGeometry` and republishes `windowShortSide`.
 - `StackScreen` pads content/footer/search/FAB by the side insets and provides an inset-consumed layout to its content; a bottom-tab root stays full width (tab bar + each tab's StackScreen handle insets). Grid columns use `contentWidth`.
 
 ## i18n / Localize (port of RN `Localize`)

package/compose/build.gradle.kts

@@ -40,7 +40,7 @@ kotlin {
     }
 
     cocoapods {
-        version = "0.162.49-debug"
+        version = "0.162.50-debug"
         summary = "IOS Shared module"
         homepage = "https://momo.vn"
         ios.deploymentTarget = "15.0"

package/compose/compose.podspec

@@ -1,6 +1,6 @@
 Pod::Spec.new do |spec|
     spec.name                     = 'compose'
-    spec.version                  = '0.167.1-beta.22-debug'
+    spec.version                  = '0.168.1-beta.8-debug'
     spec.homepage                 = 'https://momo.vn'
     spec.source                   = { :http=> ''}
     spec.authors                  = ''

package/compose/src/commonMain/kotlin/vn/momo/kits/components/PopupNotify.kt

@@ -22,6 +22,8 @@ import vn.momo.kits.application.LocalLocalize
 import vn.momo.kits.const.*
 import vn.momo.kits.modifier.conditional
 import vn.momo.kits.modifier.setAutomationId
+import vn.momo.kits.layout.duoModalMaxHeight
+import vn.momo.kits.layout.duoModalMaxWidth
 import vn.momo.kits.layout.getScreenLayout
 import kotlin.math.min
 
@@ -36,22 +38,29 @@ enum class PopupActionDirection {
     AUTO
 }
 
-// Width of a system alert on the iPhone Duo inner display, in both orientations (RN Popup/utils.ts).
-private val DUO_POPUP_MAX_WIDTH = 440.dp
+// Card width cap on iPhone Duo (the modal bounds, RN Popup/utils.ts); unbounded elsewhere.
+@Composable
+internal fun popupMaxWidth(): Dp {
+    val layout = getScreenLayout()
+    return if (layout.isIPhoneDuoDevice) layout.duoModalMaxWidth else Dp.Unspecified
+}
 
-// Card width cap plus the popup's own side padding; unbounded off iPhone Duo.
+// The modal bounds already keep iPhone Duo popups off the edges, so their own side padding goes.
 @Composable
-internal fun popupMaxWidth(horizontalPadding: Dp): Dp =
-    if (getScreenLayout().isIPhoneDuoDevice) DUO_POPUP_MAX_WIDTH + horizontalPadding * 2 else Dp.Unspecified
+internal fun popupHorizontalPadding(padding: Dp): Dp =
+    if (getScreenLayout().isIPhoneDuoDevice) 0.dp else padding
 
-// Room left for a popup on iPhone Duo, where landscape is too short for it; null elsewhere.
+// Tallest a popup gets on iPhone Duo, landscape and the inner display included; null elsewhere.
 @Composable
 internal fun popupMaxHeight(): Dp? {
     val layout = getScreenLayout()
-    if (!layout.isIPhoneDuoDevice) return null
-    return layout.height - layout.duoTopInset - layout.insetBottom - Spacing.XL * 2
+    return if (layout.isIPhoneDuoDevice) layout.duoModalMaxHeight else null
 }
 
+// Rounder on iPhone Duo, closer to its system alerts.
+@Composable
+internal fun popupRadius(): Dp = if (getScreenLayout().isIPhoneDuoDevice) Radius.XL else Radius.L
+
 private fun heightForLines(
     layout: TextLayoutResult,
 ): Float {
@@ -145,20 +154,19 @@ fun PopupNotify(
 
     val maxHeight = popupMaxHeight()
     val bodyScrollState = rememberScrollState()
+    val horizontalPadding = popupHorizontalPadding(12.dp)
+    val shape = RoundedCornerShape(popupRadius())
 
     Box(
         Modifier.setAutomationId("popup_notify"), contentAlignment = Alignment.TopEnd
     ) {
         Column(
             modifier = Modifier
-                .widthIn(max = popupMaxWidth(horizontalPadding = 12.dp))
+                .widthIn(max = popupMaxWidth())
                 .fillMaxWidth()
-                .padding(horizontal = 12.dp)
-                .clip(RoundedCornerShape(Radius.L))
-                .background(
-                    AppTheme.current.colors.background.surface,
-                    RoundedCornerShape(Radius.L)
-                )
+                .padding(horizontal = horizontalPadding)
+                .clip(shape)
+                .background(AppTheme.current.colors.background.surface, shape)
                 .conditional(IsShowBaseLineDebug) {
                     border(1.dp, Colors.blue_03)
                 }
@@ -215,7 +223,8 @@ fun PopupNotify(
                 Modifier
                     .width(22.dp)
                     .height(22.dp)
-                    .offset(x = -(1).dp, y = (-11).dp)
+                    // centered on the card's top right corner
+                    .offset(x = 11.dp - horizontalPadding, y = (-11).dp)
                     .background(
                         color = AppTheme.current.colors.text.default,
                         shape = RoundedCornerShape(Radius.M)

package/compose/src/commonMain/kotlin/vn/momo/kits/components/PopupPromotion.kt

@@ -32,15 +32,15 @@ fun PopupPromotion(
     onClose: (() -> Unit) = {},
 ) {
     val maxHeight = popupMaxHeight()
-    var maxWidth = popupMaxWidth(horizontalPadding = Spacing.M)
+    var maxWidth = popupMaxWidth()
     if (maxHeight != null) {
         // fit the portrait image by height when iPhone Duo leaves too little room
-        maxWidth = minOf(maxWidth, (maxHeight - CLOSE_ROW_HEIGHT) * ASPECT_RATIO + Spacing.M * 2)
+        maxWidth = minOf(maxWidth, (maxHeight - CLOSE_ROW_HEIGHT) * ASPECT_RATIO)
     }
 
     Column(Modifier
         .widthIn(max = maxWidth)
-        .padding(horizontal = Spacing.M)
+        .padding(horizontal = popupHorizontalPadding(Spacing.M))
         .conditional(IsShowBaseLineDebug) {
             border(1.dp, Colors.blue_03)
         }

package/compose/src/commonMain/kotlin/vn/momo/kits/layout/ScreenLayout.kt

@@ -51,7 +51,8 @@ data class ScreenLayout(
     val headerStatusBarHeight: Dp,
     // iPhone Duo moves back and toolkit into a column in the side safe area; null while they stay in the bar.
     val sideBar: SideBarLayout? = null,
-    // The device has a hinge, folded or not, whatever the window size; drives popups, modal and bottom sheet.
+    // iPhone Duo folded or not, whatever the window size (its hinge, or the outer display's one-sided strip);
+    // drives popups, modal and bottom sheet.
     val isIPhoneDuoDevice: Boolean = isIPhoneDuo,
     // Portrait iPhone Duo puts the status bar in the side strip, about twice as tall as the strip is wide.
     // Stored so it survives consumeHorizontalInsets().
@@ -90,6 +91,11 @@ internal object DuoMetrics {
     val floatingTabBarHeight = 62.dp
     val floatingTabBarMargin = 20.dp
     val floatingTabBarInsetOverlap = 13.dp
+    // Width of a system alert on the inner display, in both orientations.
+    val modalMaxWidth = 440.dp
+    // Fits a PopupNotify with image, scrolled description and actions at the max width (RN
+    // Application/device.ts); taller content scrolls instead of filling the inner display.
+    val modalMaxHeight = 640.dp
 }
 
 private val IPHONE_HEADER_MIN_HEIGHT = 72.dp
@@ -152,6 +158,14 @@ internal fun calculateScreenLayout(topInset: Dp, parent: ScreenLayout? = null):
     }
 }
 
+// Room for a dialog on iPhone Duo: inside the safe area, so clear of the side toolbar strip, and
+// capped so it stays a dialog on the inner display.
+internal val ScreenLayout.duoModalMaxWidth: Dp
+    get() = minOf(width - insetLeft - insetRight - Spacing.XL * 2, DuoMetrics.modalMaxWidth)
+
+internal val ScreenLayout.duoModalMaxHeight: Dp
+    get() = minOf(height - insetTop - insetBottom - Spacing.XL * 2, DuoMetrics.modalMaxHeight)
+
 // Content inside the safe-area padding: the insets are spent and the side bar belongs to the screen.
 internal fun ScreenLayout.consumeHorizontalInsets(): ScreenLayout =
     copy(width = contentWidth, insetLeft = 0.dp, insetRight = 0.dp, sideBar = null)
@@ -299,7 +313,8 @@ private fun screenLayoutOf(
         headerHeight = headerHeight,
         headerStatusBarHeight = headerStatusBarHeight,
         sideBar = sideBar,
-        isIPhoneDuoDevice = isDuoDevice,
+        // the outer display reports no hinge; its one-sided strip still gives it away
+        isIPhoneDuoDevice = isDuoDevice || (isPhone && asymmetricInsets),
         duoTopInset = maxOf(topInset, if (height > width) sideInset * 2 else 0.dp),
         statusBarClearance = statusBarClearance,
     )

package/compose/src/commonMain/kotlin/vn/momo/kits/navigation/BottomSheet.kt

@@ -6,7 +6,9 @@ import androidx.compose.animation.core.tween
 import androidx.compose.foundation.background
 import androidx.compose.foundation.border
 import androidx.compose.foundation.gestures.detectDragGestures
+import androidx.compose.foundation.layout.Arrangement
 import androidx.compose.foundation.layout.Box
+import androidx.compose.foundation.layout.BoxScope
 import androidx.compose.foundation.layout.BoxWithConstraints
 import androidx.compose.foundation.layout.Column
 import androidx.compose.foundation.layout.Row
@@ -17,6 +19,7 @@ import androidx.compose.foundation.layout.fillMaxWidth
 import androidx.compose.foundation.layout.height
 import androidx.compose.foundation.layout.heightIn
 import androidx.compose.foundation.layout.offset
+import androidx.compose.foundation.layout.PaddingValues
 import androidx.compose.foundation.layout.padding
 import androidx.compose.foundation.layout.size
 import androidx.compose.foundation.layout.width
@@ -25,15 +28,22 @@ import androidx.compose.foundation.shape.RoundedCornerShape
 import androidx.compose.runtime.Composable
 import androidx.compose.runtime.DisposableEffect
 import androidx.compose.runtime.LaunchedEffect
+import androidx.compose.runtime.getValue
+import androidx.compose.runtime.mutableStateOf
 import androidx.compose.runtime.remember
+import androidx.compose.runtime.setValue
 import androidx.compose.runtime.rememberCoroutineScope
+import androidx.compose.ui.AbsoluteAlignment
 import androidx.compose.ui.Alignment
 import androidx.compose.ui.Modifier
 import androidx.compose.ui.graphics.Brush
 import androidx.compose.ui.graphics.Color
 import androidx.compose.ui.input.pointer.pointerInput
+import androidx.compose.ui.layout.layout
 import androidx.compose.ui.platform.LocalDensity
+import androidx.compose.ui.unit.Dp
 import androidx.compose.ui.unit.IntOffset
+import androidx.compose.ui.unit.constrainHeight
 import androidx.compose.ui.unit.dp
 import kotlinx.coroutines.launch
 import vn.momo.kits.components.Divider
@@ -52,11 +62,24 @@ import vn.momo.kits.modifier.conditional
 import vn.momo.kits.modifier.noFeedbackClickable
 import vn.momo.kits.platform.BackHandler
 import vn.momo.kits.platform.getScreenHeight
+import vn.momo.kits.layout.DuoMetrics
+import vn.momo.kits.layout.SideBarEdge
+import vn.momo.kits.layout.SideBarLayout
 import vn.momo.kits.layout.getScreenLayout
+import vn.momo.kits.modifier.setAutomationId
+import vn.momo.kits.navigation.component.HeaderType
+import vn.momo.kits.navigation.component.SideBarButton
+import vn.momo.kits.navigation.component.getHeaderColor
 
 // iPhone Duo inner display: center the sheet instead of spanning the width (RN BottomSheet).
 private val DUO_REGULAR_MIN_WIDTH = 600.dp
 
+private val INDICATOR_HEIGHT = 16.dp
+private val HEADER_ROW_HEIGHT = 56.dp
+
+// Side column controls line up with the header row while the sheet is short.
+private val SIDE_COLUMN_OFFSET = INDICATOR_HEIGHT + (HEADER_ROW_HEIGHT - DuoMetrics.controlSize) / 2
+
 @Composable
 internal fun BottomSheet(
     content: @Composable () -> Unit,
@@ -71,6 +94,22 @@ internal fun BottomSheet(
     val layout = getScreenLayout()
     val isDuo = layout.isIPhoneDuoDevice
     val isDuoCentered = isDuo && layout.width >= DUO_REGULAR_MIN_WIDTH
+    // outer display: the sheet floats Spacing.M off the side edges like system sheets, its content
+    // stays in the safe area and its buttons move to the side bar column (HIG)
+    val isDuoFloating = isDuo && !isDuoCentered
+    val title = header as? BottomHeader.Title
+    val sideColumn = layout.sideBar?.takeIf {
+        isDuoFloating && title != null && it.width - Spacing.M >= DuoMetrics.controlSize + Spacing.M
+    }
+    // the floating sheet spans the side safe area, its content stays clear of it
+    val sidePadding = if (isDuoFloating) {
+        PaddingValues.Absolute(
+            left = (layout.insetLeft - Spacing.M).coerceAtLeast(0.dp),
+            right = (layout.insetRight - Spacing.M).coerceAtLeast(0.dp),
+        )
+    } else {
+        PaddingValues()
+    }
     // the screen is the outer display on iPhone Duo, even when unfolded
     val screenHeightDp = if (isDuo) layout.height else getScreenHeight()
     val screenHeightPx = with(LocalDensity.current) { screenHeightDp.toPx() }
@@ -96,6 +135,11 @@ internal fun BottomSheet(
         onDispose { }
     }
 
+    // a closing sheet keeps going: a second close, the open slide or a drag would cancel its animation
+    var isClosing by remember { mutableStateOf(false) }
+    // runs once the sheet has closed itself, after its onDismiss
+    var afterDismiss by remember { mutableStateOf<(() -> Unit)?>(null) }
+
     suspend fun openEvent(){
         backgroundAlpha.animateTo(
             targetValue = 0.3f,
@@ -104,6 +148,7 @@ internal fun BottomSheet(
                 easing = CubicBezierEasing(0.05f, 0.7f, 0.1f, 1f)
             )
         )
+        if (isClosing) return
         sheetOffset.animateTo(
             targetValue = 0f,
             animationSpec = tween(
@@ -113,7 +158,9 @@ internal fun BottomSheet(
         )
     }
 
-    fun closeEvent(){
+    fun closeEvent(then: (() -> Unit)? = null){
+        if (isClosing) return
+        isClosing = true
         coroutineScope.launch {
             sheetOffset.animateTo(
                 targetValue = screenHeightPx,
@@ -129,10 +176,15 @@ internal fun BottomSheet(
                     easing = CubicBezierEasing(0.3f, 0.0f, 0.8f, 0.15f)
                 )
             )
+            // not reached when a newer overlay replaced this one, so its back is dropped
+            afterDismiss = then
             OverplayComponentRegistry.hardClearAfterDismiss()
         }
     }
 
+    // RN `leftOptions.onPressIconLeft`: the sheet closes first, then the back runs
+    val onBack = title?.onBack?.let { back -> { closeEvent(then = back) } }
+
     LaunchedEffect(Unit) {
         openEvent()
     }
@@ -141,6 +193,7 @@ internal fun BottomSheet(
         OverplayComponentRegistry.bindClose { closeEvent() }
         onDispose {
             onDismiss?.invoke()
+            afterDismiss?.invoke()
         }
     }
 
@@ -158,34 +211,34 @@ internal fun BottomSheet(
     ) {
         val parentHeight = with(LocalDensity.current) { constraints.maxHeight.toDp() }
         val maxHeight = if (isDuo) {
-            parentHeight - maxOf(layout.duoTopInset, Spacing.XL)
+            // with its buttons in the side column the sheet can pass the side status bar
+            parentHeight - maxOf(if (sideColumn != null) layout.insetTop else layout.duoTopInset, Spacing.XL)
         } else {
             parentHeight - 90.dp
         }
-        // landscape side buttons span the full height; in portrait the side status bar only covers the top
-        val sideInset = isDuo && !isDuoCentered && layout.width > layout.height
+        val radius = if (isDuo) Radius.XL else Radius.M
 
         Box(
             modifier = Modifier
                 .align(Alignment.BottomCenter)
                 .offset { IntOffset(x = 0, y = sheetOffset.value.toInt()) }
                 .then(
-                    if (isDuoCentered) {
+                    when {
                         // keeps the portrait width in landscape, like system sheets
-                        Modifier.width(
+                        isDuoCentered -> Modifier.width(
                             minOf(
                                 minOf(layout.width, layout.height) - Spacing.L * 2,
                                 layout.width - maxOf(layout.insetLeft, layout.insetRight, Spacing.L) * 2,
                             )
                         )
-                    } else {
-                        Modifier.fillMaxWidth()
+                        isDuoFloating -> Modifier.fillMaxWidth().padding(horizontal = Spacing.M)
+                        else -> Modifier.fillMaxWidth()
                     }
                 )
                 .heightIn(max = maxHeight)
                 .background(
                     color = if (isSurface) AppTheme.current.colors.background.surface else AppTheme.current.colors.background.default,
-                    shape = RoundedCornerShape(topStart = Radius.M, topEnd = Radius.M)
+                    shape = RoundedCornerShape(topStart = radius, topEnd = radius)
                 )
                 .conditional(IsShowBaseLineDebug) {
                     border(1.dp, Colors.blue_03)
@@ -196,28 +249,24 @@ internal fun BottomSheet(
             val bottomInset = if (useBottomInset) {
                 (AppNavigationBar.current - keyboardSizeState().value).coerceAtLeast(0.dp)
             } else 0.dp
-            Column(
-                Modifier
-                    .padding(bottom = bottomInset)
-                    .conditional(sideInset) {
-                        absolutePadding(left = layout.insetLeft, right = layout.insetRight)
-                    }
-            ) {
+            Column(Modifier.padding(bottom = bottomInset)) {
                 Box(
                     modifier = Modifier
-                        .height(72.dp)
+                        .height(INDICATOR_HEIGHT + HEADER_ROW_HEIGHT)
                         .fillMaxWidth()
                         .conditional(draggable) {
                             pointerInput(Unit) {
                                 detectDragGestures(
                                     onDrag = { change, dragAmount ->
                                         change.consume()
+                                        if (isClosing) return@detectDragGestures
                                         coroutineScope.launch {
                                             val newOffset = (sheetOffset.value + dragAmount.y).coerceAtLeast(0f)
                                             sheetOffset.snapTo(newOffset)
                                         }
                                     },
                                     onDragEnd = {
+                                        if (isClosing) return@detectDragGestures
                                         coroutineScope.launch {
                                             if (sheetOffset.value > sheetCloseOffset) {
                                                 closeEvent()
@@ -233,6 +282,7 @@ internal fun BottomSheet(
                     Column(
                         modifier = Modifier
                             .fillMaxSize()
+                            .padding(sidePadding)
                             .padding(horizontal = Spacing.M),
                         horizontalAlignment = Alignment.CenterHorizontally
                     ) {
@@ -247,29 +297,16 @@ internal fun BottomSheet(
                                 )
                         )
                         Spacer(Modifier.height(4.dp))
-                        Box(Modifier.fillMaxWidth().height(56.dp), contentAlignment = Alignment.Center){
+                        Box(Modifier.fillMaxWidth().height(HEADER_ROW_HEIGHT), contentAlignment = Alignment.Center){
                             when (header) {
-                                is BottomHeader.Title -> {
-                                    Row(modifier = Modifier.fillMaxSize(), verticalAlignment = Alignment.CenterVertically) {
-                                        Box(Modifier.size(24.dp))
-                                        Box(Modifier.fillMaxHeight().weight(1f), contentAlignment = Alignment.Center){
-                                            Text(
-                                                text = header.data,
-                                                color = Colors.black_17,
-                                                style = Typography.headerDefaultBold
-                                            )
-                                        }
-                                        Box(Modifier
-                                            .size(24.dp)
-                                            .noFeedbackClickable {
-                                                closeEvent()
-                                            },
-                                            contentAlignment = Alignment.Center
-                                        ){
-                                            Icon(source = "navigation_close")
-                                        }
-                                    }
-                                }
+                                is BottomHeader.Title -> BottomSheetTitle(
+                                    text = header.data,
+                                    backIcon = header.backIcon,
+                                    // the side column holds back and close, the row keeps only the title
+                                    showButtons = sideColumn == null,
+                                    onBack = onBack,
+                                    onClose = { closeEvent() },
+                                )
                                 is BottomHeader.Custom -> {
                                     header.content()
                                 }
@@ -277,27 +314,141 @@ internal fun BottomSheet(
                         }
                     }
                 }
-                Divider()
+                Box(Modifier.padding(sidePadding)) {
+                    Divider()
+                }
                 if (footerComponent != null) {
-                    Box(Modifier.weight(1f, fill = false)) {
+                    Box(Modifier.weight(1f, fill = false).padding(sidePadding)) {
                         content()
                     }
-                    BottomSheetFooter(footerComponent)
+                    BottomSheetFooter(footerComponent, sidePadding)
                 } else if (isDuo) {
                     // content shrinks so a tall sheet keeps its header
-                    Box(Modifier.weight(1f, fill = false)) {
+                    Box(Modifier.weight(1f, fill = false).padding(sidePadding)) {
                         content()
                     }
                 } else {
                     content()
                 }
             }
+            if (sideColumn != null && title != null) {
+                BottomSheetSideColumn(
+                    sideBar = sideColumn,
+                    parentHeight = parentHeight,
+                    backIcon = title.backIcon,
+                    onBack = onBack,
+                    onClose = { closeEvent() },
+                )
+            }
         }
     }
 }
 
 @Composable
-private fun BottomSheetFooter(footerComponent: @Composable () -> Unit) {
+private fun BottomSheetTitle(
+    text: String,
+    backIcon: String,
+    showButtons: Boolean,
+    onBack: (() -> Unit)?,
+    onClose: () -> Unit,
+) {
+    Row(modifier = Modifier.fillMaxSize(), verticalAlignment = Alignment.CenterVertically) {
+        if (showButtons) {
+            if (onBack != null) {
+                BottomSheetHeaderButton(icon = backIcon, automationId = "btn_bottom_sheet_back", onClick = onBack)
+            } else {
+                Box(Modifier.size(24.dp))
+            }
+        }
+        Box(
+            Modifier
+                .fillMaxHeight()
+                .weight(1f)
+                .conditional(!showButtons) { padding(horizontal = Spacing.M) },
+            contentAlignment = Alignment.Center
+        ) {
+            Text(
+                text = text,
+                color = Colors.black_17,
+                style = Typography.headerDefaultBold
+            )
+        }
+        if (showButtons) {
+            BottomSheetHeaderButton(icon = "navigation_close", automationId = "btn_bottom_sheet_close", onClick = onClose)
+        }
+    }
+}
+
+@Composable
+private fun BottomSheetHeaderButton(icon: String, automationId: String, onClick: () -> Unit) {
+    Box(
+        Modifier
+            .size(24.dp)
+            .noFeedbackClickable(onClick = onClick)
+            .setAutomationId(automationId),
+        contentAlignment = Alignment.Center
+    ) {
+        Icon(source = icon)
+    }
+}
+
+// iPhone Duo outer display: back and close sit on the part of the sheet under the side safe area,
+// 12pt from the strip's inner edge like the screen side bar. They follow the header row while the
+// sheet is short and stay below the status bar cluster while it is tall.
+@Composable
+private fun BoxScope.BottomSheetSideColumn(
+    sideBar: SideBarLayout,
+    parentHeight: Dp,
+    backIcon: String,
+    onBack: (() -> Unit)?,
+    onClose: () -> Unit,
+) {
+    val isRight = sideBar.edge == SideBarEdge.RIGHT
+    val headerColor = getHeaderColor(HeaderType.None, 1f, null, AppTheme.current.colors.text.default)
+
+    Box(Modifier.matchParentSize()) {
+        Column(
+            modifier = Modifier
+                .align(if (isRight) AbsoluteAlignment.TopRight else AbsoluteAlignment.TopLeft)
+                .width(sideBar.width - Spacing.M)
+                .layout { measurable, constraints ->
+                    val placeable = measurable.measure(constraints.copy(minHeight = 0))
+                    val sheetHeight = constraints.maxHeight
+                    // the sheet rests on the bottom of the overlay, which starts at the window top
+                    val sheetTop = parentHeight.roundToPx() - sheetHeight
+                    // clear of a camera at the bottom end of the strip when it can
+                    val lowest = sheetHeight - sideBar.bottom.roundToPx() - placeable.height
+                    val y = maxOf(sideBar.top.roundToPx() - sheetTop, SIDE_COLUMN_OFFSET.roundToPx())
+                        .coerceAtMost(lowest)
+                        .coerceAtLeast(0)
+                    layout(placeable.width, constraints.constrainHeight(y + placeable.height)) {
+                        placeable.place(0, y)
+                    }
+                }
+                .absolutePadding(left = if (isRight) Spacing.M else 0.dp, right = if (isRight) 0.dp else Spacing.M),
+            horizontalAlignment = if (isRight) AbsoluteAlignment.Left else AbsoluteAlignment.Right,
+            verticalArrangement = Arrangement.spacedBy(Spacing.M),
+        ) {
+            if (onBack != null) {
+                SideBarButton(
+                    icon = backIcon,
+                    headerColor = headerColor,
+                    automationId = "btn_bottom_sheet_back",
+                    onClick = onBack,
+                )
+            }
+            SideBarButton(
+                icon = "navigation_close",
+                headerColor = headerColor,
+                automationId = "btn_bottom_sheet_close",
+                onClick = onClose,
+            )
+        }
+    }
+}
+
+@Composable
+private fun BottomSheetFooter(footerComponent: @Composable () -> Unit, sidePadding: PaddingValues) {
     val shadowBrush = remember {
         Brush.verticalGradient(
             colors = listOf(Color.Transparent, Color.Black.copy(alpha = 0.05f))
@@ -312,6 +463,7 @@ private fun BottomSheetFooter(footerComponent: @Composable () -> Unit) {
                 .conditional(IsShowBaseLineDebug) {
                     border(1.dp, Colors.blue_03)
                 }
+                .padding(sidePadding)
                 .padding(vertical = Spacing.S)
         ) {
             footerComponent()
@@ -330,7 +482,19 @@ private fun BottomSheetFooter(footerComponent: @Composable () -> Unit) {
 sealed class BottomHeader {
     data class Title(
         val data: String = "Bottom Sheet Title",
-    ) : BottomHeader()
+    ) : BottomHeader() {
+        // Outside the primary constructor so code built against older kits keeps Title() and copy().
+        // onBack shows a back button: the sheet closes (onDismiss fires), then it runs.
+        var onBack: (() -> Unit)? = null
+            private set
+        var backIcon: String = "arrow-back"
+            private set
+
+        constructor(data: String, onBack: (() -> Unit)?, backIcon: String = "arrow-back") : this(data) {
+            this.onBack = onBack
+            this.backIcon = backIcon
+        }
+    }
 
     data class Custom(
         val content: @Composable () -> Unit