From ed01a9d49ac306923a55b28f955b35a76465c9f4 Mon Sep 17 00:00:00 2001 From: Chris Banes Date: Tue, 5 May 2020 15:56:07 +0100 Subject: [PATCH 1/3] Update READMEs --- README.md | 27 ++++++++------- mdc-theme/README.md | 80 +++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 95 insertions(+), 12 deletions(-) create mode 100644 mdc-theme/README.md diff --git a/README.md b/README.md index 3686cc385..abaa38a78 100644 --- a/README.md +++ b/README.md @@ -1,14 +1,8 @@ # Accompanist -[![Maven Central](https://maven-badges.herokuapp.com/maven-central/dev.chrisbanes/accompanist/badge.svg)](https://search.maven.org/search?q=g:dev.chrisbanes.accompanist) +Accompanist is a group of libraries which contains some utilities which I've found myself copying around projects which use [Jetpack Compose][compose]. Currently it contains: -TODO - -### Why the name? - -The library is all about adding some utilities which I need to Compose. Music composing is done by a -composer, and since this library is about supporting composition, the supporting role of an -[accompanist](https://en.wikipedia.org/wiki/Accompaniment) felt like a good name. + * [Material Design Components theme interoperability](./mdc-theme/README.md) ## Download @@ -18,12 +12,19 @@ repositories { } dependencies { - implementation "dev.chrisbanes.accompanist:TODO:" + implementation "dev.chrisbanes.accompanist:accompanist-mdc-theme:" } ``` -Snapshots of the development version are available in [Sonatype's `snapshots` repository][snap]. -These are updated on every commit. +Snapshots of the development version are available in [Sonatype's `snapshots` repository][snap]. These are updated on every commit. + + +--- + +#### Why the name? + +The library is all about adding some utilities around Compose. Music composing is done by a +composer, and since this library is about supporting composition, the supporting role of an [accompanist](https://en.wikipedia.org/wiki/Accompaniment) felt like a good name. ## Contributions @@ -51,4 +52,6 @@ License for the specific language governing permissions and limitations under the License. ``` -[snap]: https://oss.sonatype.org/content/repositories/snapshots/ \ No newline at end of file +[compose]: https://developer.android.com/jetpack/compose +[snap]: https://oss.sonatype.org/content/repositories/snapshots/ +[mdc]: https://material.io/develop/android/ \ No newline at end of file diff --git a/mdc-theme/README.md b/mdc-theme/README.md new file mode 100644 index 000000000..8c73beb8d --- /dev/null +++ b/mdc-theme/README.md @@ -0,0 +1,80 @@ +## Jetpack Compose + Material Design Components theme interoperability + +[![Maven Central](https://maven-badges.herokuapp.com/maven-central/dev.chrisbanes.accompanist/accompanist-mdc-theme/badge.svg)](https://search.maven.org/search?q=g:dev.chrisbanes.accompanist) + +The basis of theming in Compose comes through the [`MaterialTheme`][materialtheme] function, where you provide [`ColorPalette`](https://developer.android.com/reference/kotlin/androidx/ui/material/ColorPalette), [`Shapes`](https://developer.android.com/reference/kotlin/androidx/ui/material/Shapes) and [`Typography`](https://developer.android.com/reference/kotlin/androidx/ui/material/Typography) instances containing your styling parameters: + +``` kotlin +MaterialTheme( + typography = type, + colors = colors, + shapes = shapes +) { + // Surface, Scaffold, etc +} +``` + +If you're migrating an existing app though, you will likely already have your brand/design styling parameters declared in the [Android Themes and Styling](https://medium.com/androiddevelopers/android-styling-themes-vs-styles-ebe05f917578) system. Wouldn't it be nice if we could re-use them in our compose layouts? + +Enter the `accompanist-mdc-theme` library, which contains the `MaterialThemeFromAndroidMdcTheme` function. + +For times when you want to copy over your context's [Material Design Components][mdc] theme to your compose layouts, you can use it like so: + + +``` kotlin +MaterialThemeFromAndroidMdcTheme { + // MaterialTheme.colors, MaterialTheme.shapes, MaterialTheme.typography + // will now contain copies of the context theme +} +``` + +This is especially handy when you're migrating an existing app, a fragment (or other UI container) a piece at a time. + +### Customizing the theme + +The `MaterialThemeFromAndroidMdcTheme()` function will automatically read host context's MDC theme and pass them to [`MaterialTheme`][materialtheme] on your behalf, but if you want to customize the generated values, you can do so via the `generateMaterialThemeFromAndroidMdcTheme()` function: + +``` kotlin +var (colors, type, shapes) = generateMaterialThemeFromAndroidMdcTheme() + +// Modify colors, type or shapes are required. Then pass them +// through to MaterialTheme... + +MaterialTheme( + typography = type, + colors = colors, + shapes = shapes +) { + // rest of layout +} +``` + +## Download + +```groovy +repositories { + mavenCentral() +} + +dependencies { + implementation "dev.chrisbanes.accompanist:accompanist-mdc-theme:" +} +``` + +Snapshots of the development version are available in [Sonatype's `snapshots` repository][snap]. These are updated on every commit. + +[compose]: https://developer.android.com/jetpack/compose +[snap]: https://oss.sonatype.org/content/repositories/snapshots/ +[mdc]: https://material.io/develop/android/ + +## Limitations + +There are some known limitations with the implementation at the moment: + +* This relies on your Activity/Context theme extending one of the `Theme.MaterialComponents` themes. +* Text colors are not read from any text appearances by default. You can enable it via the `useTextColors` function parameter. +* `android:fontVariationSettings` is currently not used, due to variable fonts not being implemented in Compose yet. +* MDC `ShapeAppearances` allow setting of corner families (cut, rounded) per corner, whereas Compose's [Shapes][shapes] allows one type for the entire shape. This means that only the `app:cornerFamily` attribute is read, with the others (`app:cornerFamilyTopLeft`, etc) being ignored. + + [materialtheme]: https://developer.android.com/reference/kotlin/androidx/ui/material/MaterialTheme + [shapes]: https://developer.android.com/reference/kotlin/androidx/ui/material/Shapes \ No newline at end of file From 4083b0ae8d831e841f114f6b17e9ba713742376c Mon Sep 17 00:00:00 2001 From: Chris Banes Date: Tue, 5 May 2020 15:59:29 +0100 Subject: [PATCH 2/3] Don't run full CI suite for README changes --- .github/workflows/build.yml | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index 81730f0aa..320d7ee31 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -1,6 +1,12 @@ name: CI -on: [push, pull_request] +on: + push: + paths-ignore: + - '**.md' + pull_request: + paths-ignore: + - '**.md' jobs: build: From d312ad7c8b62253dea93b0139d70e75cbae047c4 Mon Sep 17 00:00:00 2001 From: Chris Banes Date: Tue, 5 May 2020 16:13:52 +0100 Subject: [PATCH 3/3] Rename function to be clearer --- mdc-theme/README.md | 8 ++++---- .../accompanist/mdctheme/MaterialThemeTest.kt | 6 +++--- ...eFromAndroidMdc.kt => MaterialThemeFromMdcTheme.kt} | 10 +++++++--- 3 files changed, 14 insertions(+), 10 deletions(-) rename mdc-theme/src/main/java/dev/chrisbanes/accompanist/mdctheme/{MaterialThemeFromAndroidMdc.kt => MaterialThemeFromMdcTheme.kt} (98%) diff --git a/mdc-theme/README.md b/mdc-theme/README.md index 8c73beb8d..85bf57d7b 100644 --- a/mdc-theme/README.md +++ b/mdc-theme/README.md @@ -16,13 +16,13 @@ MaterialTheme( If you're migrating an existing app though, you will likely already have your brand/design styling parameters declared in the [Android Themes and Styling](https://medium.com/androiddevelopers/android-styling-themes-vs-styles-ebe05f917578) system. Wouldn't it be nice if we could re-use them in our compose layouts? -Enter the `accompanist-mdc-theme` library, which contains the `MaterialThemeFromAndroidMdcTheme` function. +Enter the `accompanist-mdc-theme` library, which contains a number of functions to help inter-operate between the two. For times when you want to copy over your context's [Material Design Components][mdc] theme to your compose layouts, you can use it like so: ``` kotlin -MaterialThemeFromAndroidMdcTheme { +MaterialThemeFromMdcTheme { // MaterialTheme.colors, MaterialTheme.shapes, MaterialTheme.typography // will now contain copies of the context theme } @@ -32,10 +32,10 @@ This is especially handy when you're migrating an existing app, a fragment (or o ### Customizing the theme -The `MaterialThemeFromAndroidMdcTheme()` function will automatically read host context's MDC theme and pass them to [`MaterialTheme`][materialtheme] on your behalf, but if you want to customize the generated values, you can do so via the `generateMaterialThemeFromAndroidMdcTheme()` function: +The `MaterialThemeFromMdcTheme()` function will automatically read host context's MDC theme and pass them to [`MaterialTheme`][materialtheme] on your behalf, but if you want to customize the generated values, you can do so via the `generateMaterialThemeFromMdcTheme()` function: ``` kotlin -var (colors, type, shapes) = generateMaterialThemeFromAndroidMdcTheme() +var (colors, type, shapes) = generateMaterialThemeFromMdcTheme() // Modify colors, type or shapes are required. Then pass them // through to MaterialTheme... diff --git a/mdc-theme/src/androidTest/java/dev/chrisbanes/accompanist/mdctheme/MaterialThemeTest.kt b/mdc-theme/src/androidTest/java/dev/chrisbanes/accompanist/mdctheme/MaterialThemeTest.kt index 0cc1575b7..ef17827bd 100644 --- a/mdc-theme/src/androidTest/java/dev/chrisbanes/accompanist/mdctheme/MaterialThemeTest.kt +++ b/mdc-theme/src/androidTest/java/dev/chrisbanes/accompanist/mdctheme/MaterialThemeTest.kt @@ -53,7 +53,7 @@ class MaterialThemeTest { @Test fun colors() = composeTestRule.setContent { - MaterialThemeFromAndroidMdcTheme { + MaterialThemeFromMdcTheme { val color = MaterialTheme.colors assertEquals(colorResource(R.color.Aquamarine), color.primary) @@ -77,7 +77,7 @@ class MaterialThemeTest { @Test fun shapes() = composeTestRule.setContent { - MaterialThemeFromAndroidMdcTheme { + MaterialThemeFromMdcTheme { val shapes = MaterialTheme.shapes val density = DensityAmbient.current @@ -107,7 +107,7 @@ class MaterialThemeTest { @Test fun type() = composeTestRule.setContent { - MaterialThemeFromAndroidMdcTheme { + MaterialThemeFromMdcTheme { val typography = MaterialTheme.typography val density = DensityAmbient.current diff --git a/mdc-theme/src/main/java/dev/chrisbanes/accompanist/mdctheme/MaterialThemeFromAndroidMdc.kt b/mdc-theme/src/main/java/dev/chrisbanes/accompanist/mdctheme/MaterialThemeFromMdcTheme.kt similarity index 98% rename from mdc-theme/src/main/java/dev/chrisbanes/accompanist/mdctheme/MaterialThemeFromAndroidMdc.kt rename to mdc-theme/src/main/java/dev/chrisbanes/accompanist/mdctheme/MaterialThemeFromMdcTheme.kt index ccc01dad9..089fb6f45 100644 --- a/mdc-theme/src/main/java/dev/chrisbanes/accompanist/mdctheme/MaterialThemeFromAndroidMdc.kt +++ b/mdc-theme/src/main/java/dev/chrisbanes/accompanist/mdctheme/MaterialThemeFromMdcTheme.kt @@ -73,7 +73,7 @@ import kotlin.concurrent.getOrSet * theme. Defaults to `false` */ @Composable -fun MaterialThemeFromAndroidMdcTheme( +fun MaterialThemeFromMdcTheme( context: Context = ContextAmbient.current, readColors: Boolean = true, readTypography: Boolean = true, @@ -81,7 +81,7 @@ fun MaterialThemeFromAndroidMdcTheme( useTextColors: Boolean = false, children: @Composable() () -> Unit ) { - val (colors, type, shapes) = generateMaterialThemeFromAndroidMdcTheme( + val (colors, type, shapes) = generateMaterialThemeFromMdcTheme( context, readColors, readTypography, @@ -114,7 +114,7 @@ fun MaterialThemeFromAndroidMdcTheme( * theme. Defaults to `false` */ @Composable -fun generateMaterialThemeFromAndroidMdcTheme( +fun generateMaterialThemeFromMdcTheme( context: Context = ContextAmbient.current, readColors: Boolean = true, readTypography: Boolean = true, @@ -122,6 +122,10 @@ fun generateMaterialThemeFromAndroidMdcTheme( useTextColors: Boolean = false ): Triple { return context.obtainStyledAttributes(R.styleable.AccompanistMdcTheme).use { ta -> + require(ta.hasValue(R.styleable.AccompanistMdcTheme_colorPrimary)) { + "MaterialThemeUsingMdcTheme requires the host context's theme " + + "to extend Theme.MaterialComponents" + } val colors: ColorPalette = if (readColors) { /* First we'll read the Material color palette */