Move AniListDetailPaneScaffold to ui-adaptive and document it

app/shared/ui-adaptive/src/commonMain/kotlin/ui/adaptive/AdaptiveSearchBar.kt

@@ -11,7 +11,6 @@ package me.him188.ani.app.ui.adaptive
 
 import androidx.compose.foundation.layout.ColumnScope
 import androidx.compose.foundation.layout.WindowInsets
-import androidx.compose.material3.DockedSearchBar
 import androidx.compose.material3.SearchBar
 import androidx.compose.material3.SearchBarColors
 import androidx.compose.material3.SearchBarDefaults
@@ -25,7 +24,7 @@ import me.him188.ani.app.ui.foundation.layout.compareTo
 import me.him188.ani.utils.platform.isMobile
 
 /**
- * @see DockedSearchBar
+ * @see PopupSearchBar
  * @see SearchBar
  */
 @Composable

app/shared/ui-foundation/src/commonMain/kotlin/ui/foundation/layout/AniListDetailPaneScaffold.kt → app/shared/ui-adaptive/src/commonMain/kotlin/ui/adaptive/AniListDetailPaneScaffold.kt

@@ -7,7 +7,7 @@
  * https://github.com/open-ani/ani/blob/main/LICENSE
  */
 
-package me.him188.ani.app.ui.foundation.layout
+package me.him188.ani.app.ui.adaptive
 
 import androidx.compose.animation.AnimatedVisibilityScope
 import androidx.compose.animation.SharedTransitionLayout
@@ -35,11 +35,25 @@ import androidx.compose.ui.graphics.RectangleShape
 import androidx.compose.ui.graphics.Shape
 import androidx.compose.ui.unit.Dp
 import androidx.compose.ui.unit.dp
+import me.him188.ani.app.ui.foundation.layout.AnimatedPane1
+import me.him188.ani.app.ui.foundation.layout.paneHorizontalPadding
 import me.him188.ani.app.ui.foundation.navigation.BackHandler
 
 
 /**
  * 自动适应单页模式和双页模式的布局的 paddings
+ *
+ * Pane 内可以访问 [PaneScope]. 其中有几个非常实用的属性:
+ * - [PaneScope.paneContentPadding]: 用于为 pane 增加自动的 content padding. 通常你需要为 pane 的内容直接添加这个 modifier.
+ *   如果你不期望为整个容器添加 padding, 可以使用 [PaneScope.listDetailLayoutParameters] [ListDetailLayoutParameters.listPaneContentPaddingValues]
+ * - [PaneScope.listDetailLayoutParameters] 用于获取当前的布局参数.
+ *
+ * @param listPaneTopAppBar 通常可以放 [AniTopAppBar], 可以留空. 留空时不会占额外空间.
+ * @param listPaneContent 列表内容, 可以是 Column 或者 Grid. 需要自行实现 vertical scroll.
+ * @param detailPane 详情内容.
+ * @param listPanePreferredWidth See also [androidx.compose.material3.adaptive.layout.PaneScaffoldScope.preferredWidth]
+ * @param useSharedTransition 是否在[单页模式][ListDetailLayoutParameters.isSinglePane]时使用 Container Transform 等 [SharedTransitionLayout] 的动画.
+ * 启用后将会调整切换 pane 时的 fade 动画逻辑来适配 Container Transform.
  */
 @Composable
 fun <T> AniListDetailPaneScaffold(
@@ -112,11 +126,17 @@ fun <T> AniListDetailPaneScaffold(
 
 @Stable
 interface PaneScope : SharedTransitionScope {
+    /**
+     * 获取当前的布局参数.
+     *
+     * 若要为 pane 增加 padding, 可优先使用 [paneContentPadding].
+     */
     val listDetailLayoutParameters: ListDetailLayoutParameters
     val animatedVisibilityScope: AnimatedVisibilityScope
 
     /**
-     * 增加自动的 content padding
+     * 为 pane 增加自动的 content padding. 通常应用于 pane 的最外层容器:
+     * @sample me.him188.ani.app.ui.foundation.samples.paneContentPadding
      */
     @Stable
     fun Modifier.paneContentPadding(): Modifier

app/shared/ui-adaptive/src/commonMain/kotlin/ui/adaptive/AniTopAppBar.kt

@@ -50,13 +50,24 @@ import me.him188.ani.app.ui.foundation.layout.paneHorizontalPadding
 import me.him188.ani.app.ui.foundation.theme.AniThemeDefaults
 
 /**
- * 小屏幕上使用默认 TopAppBar 高度, 使用 36dp 头像; MEDIUM 及以上上增加额外 padding(all=8.dp), 并使用 48dp 头像
+ * 符合 Ani 设计风格的 TopAppBar: [NavigationSuiteScaffold on Figma](https://www.figma.com/design/LET1n9mmDa6npDTIlUuJjU/Main?node-id=15-605&t=gmFJS6LFQudIIXfK-4).
  *
- * Design: [NavigationSuiteScaffold on Figma](https://www.figma.com/design/LET1n9mmDa6npDTIlUuJjU/Main?node-id=15-605&t=gmFJS6LFQudIIXfK-4)
+ * ### search bar 布局
+ *
+ * - COMPACT: [searchIconButton], 这个按钮应该是一个搜索图标, 用于点击后展开搜索栏或进入搜索模式等.
+ * - MEDIUM: [searchBar], 外显的搜索栏, 通常可以采用 [AdaptiveSearchBar].
+ *
+ * ### 其他布局细节信息
+ *
+ * | 设备类型 | 高度 | 头像大小 |
+ * |----|----|-----|
+ * | COMPACT | 使用[默认][TopAppBarDefaults.TopAppBarExpandedHeight] TopAppBar [高度][expandedHeight] | 24dp |
+ * | MEDIUM+ | 默认高度以及额外 padding(all=8.dp) | 36.dp|
  *
  * 默认颜色为 [AniThemeDefaults.topAppBarColors]
  *
  * @param title use [AniTopAppBarDefaults.Title]
+ * @param avatar 头像. 应当为一个圆形的头像, 且使用 `Modifier.size(recommendedSize)`.
  *
  * @see TopAppBar
  */
@@ -94,7 +105,7 @@ fun AniTopAppBar(
                     horizontalArrangement = Arrangement.spacedBy(8.dp, alignment = Alignment.End),
                     verticalAlignment = Alignment.CenterVertically,
                 ) {
-                    AdaptiveSearchBar(
+                    AdaptiveSearchBarLayout(
                         windowSizeClass,
                         searchIconButton,
                         Modifier.weight(1f, fill = false),
@@ -145,8 +156,14 @@ object AniTopAppBarDefaults {
     }
 }
 
+/**
+ * 自适应搜索栏布局.
+ *
+ * @param searchIconButton 搜索按钮, 通常为一个搜索图标.
+ * @param searchBar 外显搜索栏. 可以是 [PopupSearchBar]
+ */
 @Composable
-fun AdaptiveSearchBar(
+private fun AdaptiveSearchBarLayout(
     windowSizeClass: WindowSizeClass,
     searchIconButton: @Composable (() -> Unit)?,
     modifier: Modifier = Modifier,

app/shared/ui-exploration/src/commonMain/kotlin/ui/exploration/search/SearchPage.kt

@@ -57,13 +57,13 @@ import kotlinx.coroutines.delay
 import kotlinx.coroutines.flow.collectLatest
 import kotlinx.coroutines.launch
 import me.him188.ani.app.navigation.LocalNavigator
+import me.him188.ani.app.ui.adaptive.AniListDetailPaneScaffold
 import me.him188.ani.app.ui.adaptive.AniTopAppBar
+import me.him188.ani.app.ui.adaptive.PaneScope
 import me.him188.ani.app.ui.foundation.animation.SharedTransitionKeys
 import me.him188.ani.app.ui.foundation.ifThen
 import me.him188.ani.app.ui.foundation.interaction.keyboardDirectionToSelectItem
 import me.him188.ani.app.ui.foundation.interaction.keyboardPageToScroll
-import me.him188.ani.app.ui.foundation.layout.AniListDetailPaneScaffold
-import me.him188.ani.app.ui.foundation.layout.PaneScope
 import me.him188.ani.app.ui.foundation.layout.compareTo
 import me.him188.ani.app.ui.foundation.layout.paneHorizontalPadding
 import me.him188.ani.app.ui.foundation.layout.paneVerticalPadding

app/shared/ui-foundation/src/commonTest/kotlin/package.kt

@@ -0,0 +1,10 @@
+/*
+ * Copyright (C) 2024 OpenAni and contributors.
+ *
+ * 此源代码的使用受 GNU AFFERO GENERAL PUBLIC LICENSE version 3 许可证的约束, 可以在以下链接找到该许可证.
+ * Use of this source code is governed by the GNU AGPLv3 license, which can be found at the following link.
+ *
+ * https://github.com/open-ani/ani/blob/main/LICENSE
+ */
+
+package me.him188.ani.app

app/shared/ui-settings/src/commonMain/kotlin/ui/settings/SettingsPage.kt

@@ -63,12 +63,12 @@ import androidx.compose.ui.graphics.vector.ImageVector
 import androidx.compose.ui.input.nestedscroll.nestedScroll
 import androidx.compose.ui.unit.Dp
 import androidx.compose.ui.unit.dp
+import me.him188.ani.app.ui.adaptive.AniListDetailPaneScaffold
 import me.him188.ani.app.ui.adaptive.AniTopAppBar
 import me.him188.ani.app.ui.adaptive.AniTopAppBarDefaults
+import me.him188.ani.app.ui.adaptive.ListDetailLayoutParameters
 import me.him188.ani.app.ui.foundation.LocalPlatform
 import me.him188.ani.app.ui.foundation.ifThen
-import me.him188.ani.app.ui.foundation.layout.AniListDetailPaneScaffold
-import me.him188.ani.app.ui.foundation.layout.ListDetailLayoutParameters
 import me.him188.ani.app.ui.foundation.layout.cardVerticalPadding
 import me.him188.ani.app.ui.foundation.layout.paneHorizontalPadding
 import me.him188.ani.app.ui.foundation.layout.paneVerticalPadding

app/shared/ui-settings/src/commonMain/kotlin/ui/settings/tabs/media/torrent/peer/PeerFilterSettings.kt

@@ -40,10 +40,10 @@ import androidx.compose.ui.platform.LocalSoftwareKeyboardController
 import androidx.compose.ui.text.input.ImeAction
 import androidx.compose.ui.unit.dp
 import androidx.lifecycle.compose.collectAsStateWithLifecycle
+import me.him188.ani.app.ui.adaptive.AniListDetailPaneScaffold
 import me.him188.ani.app.ui.adaptive.AniTopAppBar
 import me.him188.ani.app.ui.adaptive.AniTopAppBarDefaults
 import me.him188.ani.app.ui.foundation.IconButton
-import me.him188.ani.app.ui.foundation.layout.AniListDetailPaneScaffold
 import me.him188.ani.app.ui.foundation.navigation.BackHandler
 import me.him188.ani.app.ui.foundation.theme.AniThemeDefaults
 import me.him188.ani.app.ui.foundation.widgets.TopAppBarGoBackButton