Merge pull request #1287 from google/av/adaptive-docs

[Adaptive] Miscellaneous doc updates

.github/ISSUE_TEMPLATE/adapative-bug-report.md

@@ -0,0 +1,16 @@
+---
+name: Adaptive bug report
+about: Create a report about adaptive
+title: "[Adaptive]"
+labels: adaptive
+assignees: alexvanyo
+
+---
+
+**Description**
+
+**Steps to reproduce**
+
+**Expected behavior** 
+
+**Additional context**

adaptive/src/main/java/com/google/accompanist/adaptive/TwoPane.kt

@@ -64,6 +64,8 @@ import kotlin.math.roundToInt
  * and the bottom-most in a vertical split based on the [SplitResult] of
  * [TwoPaneStrategy.calculateSplitResult]
  * @param strategy strategy of the two pane that controls the arrangement of the layout
+ * @param displayFeatures the list of known display features to automatically avoid
+ * @param foldAwareConfiguration the types of display features to automatically avoid
  * @param modifier an optional modifier for the layout
  */
 @Composable
@@ -278,9 +280,7 @@ private fun interface ConditionalTwoPaneStrategy {
 /**
  * Returns a [TwoPaneStrategy] that will place the slots horizontally.
  *
- * If there is a vertical fold, then the gap will be placed along the fold.
- *
- * Otherwise, the gap will be placed at the given [splitFraction] from start, with the given
+ * The gap will be placed at the given [splitFraction] from start, with the given
  * [gapWidth].
  */
 public fun HorizontalTwoPaneStrategy(
@@ -294,9 +294,7 @@ public fun HorizontalTwoPaneStrategy(
 /**
  * Returns a [TwoPaneStrategy] that will place the slots horizontally.
  *
- * If there is a vertical fold, then the gap will be placed along the fold.
- *
- * Otherwise, the gap will be placed at [splitOffset] either from the start or end based on
+ * The gap will be placed at [splitOffset] either from the start or end based on
  * [offsetFromStart], with the given [gapWidth].
  */
 public fun HorizontalTwoPaneStrategy(
@@ -312,9 +310,7 @@ public fun HorizontalTwoPaneStrategy(
 /**
  * Returns a [TwoPaneStrategy] that will place the slots horizontally.
  *
- * If there is a vertical fold, then the gap will be placed along the fold.
- *
- * Otherwise, the gap will be placed at the given [splitFraction] from top, with the given
+ * The gap will be placed at the given [splitFraction] from top, with the given
  * [gapHeight].
  */
 public fun VerticalTwoPaneStrategy(
@@ -328,9 +324,7 @@ public fun VerticalTwoPaneStrategy(
 /**
  * Returns a [TwoPaneStrategy] that will place the slots horizontally.
  *
- * If there is a vertical fold, then the gap will be placed along the fold.
- *
- * Otherwise, the gap will be placed at [splitOffset] either from the top or bottom based on
+ * The gap will be placed at [splitOffset] either from the top or bottom based on
  * [offsetFromTop], with the given [gapHeight].
  */
 public fun VerticalTwoPaneStrategy(

docs/adaptive.md

@@ -0,0 +1,45 @@
+# Adaptive utilities for Jetpack Compose
+
+[![Maven Central](https://img.shields.io/maven-central/v/com.google.accompanist/accompanist-adaptive)](https://search.maven.org/search?q=g:com.google.accompanist)
+
+A library providing a collection of utilities for adaptive layouts.
+
+## calculateDisplayFeatures
+
+[`calculateDisplayFeatures(activity)`](../api/adaptive/com.google.accompanist.adaptive/calculate-display-features.html) returns the current list of `DisplayFeature`s,
+as reported by the [Jetpack WindowManager library](https://developer.android.com/jetpack/androidx/releases/window).
+
+These contain the list of folds (if any), and can be used to drive components like [`TwoPane`](#TwoPane).
+
+## TwoPane
+
+[`TwoPane`](../api/adaptive/com.google.accompanist.adaptive/-two-pane.html) is a UI component that positions exactly two slots on the screen.
+
+The default positioning of these two slots is driven by a [`TwoPaneStrategy`](../api/adaptive/com.google.accompanist.adaptive/-two-pane-strategy.html),
+which can decide to orient the two slots side-by-side horizontally or vertically, and also configure the gap between them.
+
+The built-in [`HorizontalTwoPaneStrategy`](../api/adaptive/com.google.accompanist.adaptive/-horizontal-two-pane-strategy.html) and
+[`VerticalTwoPaneStrategy`](../api/adaptive/com.google.accompanist.adaptive/-vertical-two-pane-strategy.html) allow positioning the
+slots based on a fixed offset, or as some fraction of the space.
+
+[`TwoPane`](../api/adaptive/com.google.accompanist.adaptive/-two-pane.html) also requires a list of display features (to be retrieved with [`calculateDisplayFeatures`](#calculateDisplayFeatures)),
+and optionally a [`FoldAwareConfiguration`](../api/adaptive/com.google.accompanist.adaptive/-fold-aware-configuration.html) to determine which folds to handle automatically.
+
+When there is a fold that intersects with the [`TwoPane`](../api/adaptive/com.google.accompanist.adaptive/-two-pane.html) component that is obscuring or separating,
+the [`TwoPane`](../api/adaptive/com.google.accompanist.adaptive/-two-pane.html) will automatically place the slots to avoid the fold.
+
+When there is no fold, the default supplied strategy will be used instead.
+
+## Download
+
+[![Maven Central](https://img.shields.io/maven-central/v/com.google.accompanist/accompanist-adaptive)](https://search.maven.org/search?q=g:com.google.accompanist)
+
+```groovy
+repositories {
+    mavenCentral()
+}
+
+dependencies {
+    implementation "com.google.accompanist:accompanist-adaptive:<version>"
+}
+```