Add more KDocs for Modifier.outerPadding about its UI issues when used with the Modifier.fillMax... modifiers

ShreckYe · ShreckYe · commit eb27f67300e2 · 2024-12-09T19:17:42.000+08:00
diff --git a/common/src/commonMain/kotlin/com/huanshankeji/compose/foundation/layout/ext/InnerPadding.kt b/common/src/commonMain/kotlin/com/huanshankeji/compose/foundation/layout/ext/InnerPadding.kt
@@ -6,6 +6,7 @@ import androidx.compose.ui.unit.dp
 import com.huanshankeji.compose.foundation.background
 import com.huanshankeji.compose.foundation.clickable
 import com.huanshankeji.compose.foundation.layout.PaddingValues
+import com.huanshankeji.compose.foundation.layout.padding
 import com.huanshankeji.compose.ui.Modifier
 
 /**
diff --git a/common/src/commonMain/kotlin/com/huanshankeji/compose/foundation/layout/ext/OuterPadding.kt b/common/src/commonMain/kotlin/com/huanshankeji/compose/foundation/layout/ext/OuterPadding.kt
@@ -5,7 +5,7 @@ import androidx.compose.ui.unit.Dp
 import androidx.compose.ui.unit.dp
 import com.huanshankeji.compose.foundation.background
 import com.huanshankeji.compose.foundation.clickable
-import com.huanshankeji.compose.foundation.layout.PaddingValues
+import com.huanshankeji.compose.foundation.layout.*
 import com.huanshankeji.compose.ui.Modifier
 
 /**
@@ -23,6 +23,52 @@ expect fun Modifier.outerPadding(horizontal: Dp = 0.dp, vertical: Dp = 0.dp): Mo
 /**
  * This delegates to the CSS `margin` property on JS DOM and adds the padding outside.
  * For consistency on different platforms, please use it as the **first** modifier **before** the other modifiers such as [background] and [clickable].
+ *
+ * However, as [CSS `box-sizing`](https://developer.mozilla.org/en-US/docs/Web/CSS/box-sizing) doesn't have a `margin-box` value, when this is used with [fillMaxSize]/[fillMaxWidth]/[fillMaxHeight] on JS DOM the visual result may be not what you expect.
+ * In such a case, either replace it with [fillMaxSizeStretch]/[fillMaxWidthStretch]/[fillMaxHeightStretch] or use [innerPadding] on an outer parent instead.
+ *
+ * Copy and render the following code to see the problem yourself:
+ *
+```html
+<!DOCTYPE html>
+<html>
+
+<head>
+<style>
+.inner-div {
+width: 100%;
+height: 64px;
+padding: 16px;
+margin: 16px;
+background: white;
+border: 2px solid yellow;
+box-sizing: border-box;
+}
+
+.outer-div {
+background: orange;
+border: 2px solid red;
+padding: 16px;
+}
+</style>
+</head>
+
+<body>
+
+<h1>box-sizing with margin</h1>
+<p>In <code>.inner-div</code>, either remove <code>margin</code> or set <code>width</code> to <code>-webkit-fill-available</code>.
+
+<br>
+<div class="outer-div">
+<div class="inner-div"></div>
+</div>
+<div>
+
+</body>
+
+</html>
+```
+ *
  * See the KDoc of the [padding] overload with one [Dp] parameter for more information.
  * @see innerPadding
  */
diff --git a/common/src/jsMain/kotlin/com/huanshankeji/compose/foundation/layout/ext/Size.js.kt b/common/src/jsMain/kotlin/com/huanshankeji/compose/foundation/layout/ext/Size.js.kt
@@ -10,7 +10,7 @@ import com.varabyte.kobweb.compose.ui.styleModifier
 import org.jetbrains.compose.web.css.StyleScope
 
 private const val CSS_STRETCH_VALUE = "stretch" // This does not work on Chrome.
-private const val CSS_WEBKIT_STRETCH_VALUE = "-webkit-fill-available"
+private const val CSS_WEBKIT_STRETCH_VALUE = "-webkit-fill-available" // This actually works on FireFox too as tested.
 private const val CSS_MOZ_STRETCH_VALUE = "-moz-available"
 val cssWidthStretchValueBrowserDependent =
     when (browser) {
