From 82ee87f89b61eeff356ca6b7d344a0d171159c0a Mon Sep 17 00:00:00 2001 From: Gurupreet Singh Date: Mon, 21 Aug 2023 15:45:50 +0200 Subject: [PATCH 1/5] update readme for deprecation --- README.md | 27 ++++----------------------- 1 file changed, 4 insertions(+), 23 deletions(-) diff --git a/README.md b/README.md index d610a18..f5cd6ba 100644 --- a/README.md +++ b/README.md @@ -1,29 +1,10 @@ # MDC-Android Compose Theme Adapter +## Deprecated !!! warning - **These libraries are deprecated in favor of the new [Accompanist][accompanist] Theme Adapter artifacts. The migration guide and original documentation is below.** + **Material Theme Adapter is deprecated. Use the Material Theme Builder tool, to generate a matching XML and Compose theme implementation for your app. See [Migrating XML themes to Compose][migratexmltocompose] to learn more.** -## Migration - -MDC-Android Compose Theme Adapters have moved from: -* The `compose-theme-adapter` artifact to the [`accompanist/themeadapter-material`][themeadaptermateriallib] artifact -* The `compose-theme-adapter-3` artifact to the [`accompanist/themeadapter-material3`][themeadaptermaterial3lib] artifact -* The `compose-theme-adapter-core` artifact to the [`accompanist/themeadapter-core`][themeadaptercorelib] artifact - -The implementations are identical but the dependencies and import packages have changed. - -### Migration steps - -1. Change any dependencies from: - 1. `com.google.android.material:compose-theme-adapter:` to `com.google.accompanist:accompanist-themeadapter-material:` - 2. `com.google.android.material:compose-theme-adapter-3:` to `com.google.accompanist:accompanist-themeadapter-material3:` - 3. `com.google.android.material:compose-theme-adapter-core:` to `com.google.accompanist:accompanist-themeadapter-core:` -2. Change any imports from: - 1. `com.google.android.material.composethemeadapter.*` to `com.google.accompanist.themeadapter.material.*` - 2. `com.google.android.material.composethemeadapter3.*` to `com.google.accompanist.themeadapter.material3.*` - 3. `com.google.android.material.composethemeadapter.core.*` to `com.google.accompanist.themeadapter.core.*` - -## Original Docs +## Library Docs A library that enables reuse of [Material Components for Android][mdc] XML themes for theming in [Jetpack Compose][compose]. @@ -247,7 +228,7 @@ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. ``` - + [migratexmltocompose]: https://developer.android.com/jetpack/compose/designsystems/views-to-compose [compose]: https://developer.android.com/jetpack/compose [mdc]: https://github.com/material-components/material-components-android [appcompat]: https://developer.android.com/jetpack/androidx/releases/appcompat From 2581f47fd37476b42017de8cbec1f692f12e08be Mon Sep 17 00:00:00 2001 From: Gurupreet Singh Date: Mon, 21 Aug 2023 16:01:37 +0200 Subject: [PATCH 2/5] remove warning sign --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index f5cd6ba..a52ba81 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,8 @@ # MDC-Android Compose Theme Adapter ## Deprecated -!!! warning - **Material Theme Adapter is deprecated. Use the Material Theme Builder tool, to generate a matching XML and Compose theme implementation for your app. See [Migrating XML themes to Compose][migratexmltocompose] to learn more.** + +**Material Theme Adapter is deprecated. Use the Material Theme Builder tool, to generate a matching XML and Compose theme implementation for your app. See [Migrating XML themes to Compose][migratexmltocompose] to learn more.** ## Library Docs From 816dbc5195252908c6dad9b4d9dbce2176f9907d Mon Sep 17 00:00:00 2001 From: Gurupreet Singh Date: Thu, 24 Aug 2023 15:27:40 +0200 Subject: [PATCH 3/5] highlight deprecation and remove usage from readme --- README.md | 207 +------------------------------------------------- USAGE.md | 223 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 224 insertions(+), 206 deletions(-) create mode 100644 USAGE.md diff --git a/README.md b/README.md index a52ba81..d801a85 100644 --- a/README.md +++ b/README.md @@ -4,212 +4,7 @@ **Material Theme Adapter is deprecated. Use the Material Theme Builder tool, to generate a matching XML and Compose theme implementation for your app. See [Migrating XML themes to Compose][migratexmltocompose] to learn more.** -## Library Docs - -A library that enables reuse of [Material Components for Android][mdc] XML themes for theming in [Jetpack Compose][compose]. - -## Usage - -There are two artifacts available: - -* [`com.google.android.material:compose-theme-adapter`](#compose-material) - * Compatible with Compose Material - * Includes `MdcTheme` -* [`com.google.android.material:compose-theme-adapter-3`](#compose-material-3) - * Compatible with Compose Material 3 - * Includes `Mdc3Theme` - -```groovy -repositories { - google() -} - -dependencies { - // Compatible with Compose Material, includes MdcTheme - implementation "com.google.android.material:compose-theme-adapter:" - // Compatible with Compose Material 3, includes Mdc3Theme - implementation "com.google.android.material:compose-theme-adapter-3:" -} -``` - -See the [releases](https://github.com/material-components/material-components-android-compose-theme-adapter/releases) page for the latest versions. - ---- - -## Compose Material - -![MDC-Android Compose Theme Adapter header](docs/header.png) - -The basis of Material Design 2 theming in [Jetpack Compose][compose] is the [`MaterialTheme`][materialtheme] composable, where you provide [`Colors`][colors], [`Typography`][typography] and [`Shapes`][shapes] instances containing your styling parameters: - -``` kotlin -MaterialTheme( - colors = colors, - typography = type, - shapes = shapes -) { - // M2 Surface, Scaffold, etc. -} -``` - -[Material Components for Android][mdc] themes allow for similar theming for views via XML theme attributes, like so: - -``` xml - -``` - -This library attempts to bridge the gap between [Material Components for Android][mdc] M2 XML themes, and themes in [Jetpack Compose][compose], allowing your composable [`MaterialTheme`][materialtheme] to be based on the `Activity`'s XML theme: - - -``` kotlin -MdcTheme { - // MaterialTheme.colors, MaterialTheme.typography, MaterialTheme.shapes - // will now contain copies of the Context's theme -} -``` - -This is especially handy when you're migrating an existing app, a `Fragment` (or other UI container) at a time. - -!!! caution - If you are using an AppCompat (i.e. non-MDC) theme in your app, you should use - [AppCompat Compose Theme Adapter](https://github.com/google/accompanist/tree/main/appcompat-theme) - instead, as it attempts to bridge the gap between [AppCompat][appcompat] XML themes, and M2 themes in [Jetpack Compose][compose]. - -### Customizing the M2 theme - -The `MdcTheme()` function will automatically read the 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 `createMdcTheme()` function: - -``` kotlin -val context = LocalContext.current -val layoutDirection = LocalLayoutDirection.current -var (colors, typography, shapes) = createMdcTheme( - context = context, - layoutDirection = layoutDirection -) - -// Modify colors, typography or shapes as required. -// Then pass them through to MaterialTheme... - -MaterialTheme( - colors = colors, - typography = type, - shapes = shapes -) { - // Rest of M2 layout -} -``` - -### 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 the text appearances by default. You can enable it via the `setTextColors` function parameter. -* Variable fonts are not supported in Compose yet, meaning that the value of `android:fontVariationSettings` are currently ignored. -* MDC `ShapeAppearances` allow setting of different corner families (cut, rounded) on each corner, whereas Compose's [Shapes][shapes] allows only a single corner family for the entire shape. Therefore only the `app:cornerFamily` attribute is read, others (`app:cornerFamilyTopLeft`, etc) are ignored. -* You can modify the resulting `MaterialTheme` in Compose as required, but this _only_ works in Compose. Any changes you make will not be reflected in the `Activity` theme. - -## Compose Material 3 - -![MDC-Android Compose Theme Adapter header](docs/m3header.png) - -The basis of Material Design 3 theming in [Jetpack Compose][compose] is the [`MaterialTheme`][m3materialtheme] composable, where you provide [`ColorScheme`][m3colorscheme], [`Typography`][m3typography] and [`Shapes`][m3shapes] instances containing your styling parameters: - -``` kotlin -MaterialTheme( - colorScheme = colorScheme, - typography = typography, - shapes = shapes -) { - // M3 Surface, Scaffold, etc. -} -``` - -[Material Components for Android][mdc] themes allow for similar theming for views via XML theme attributes, like so: - -``` xml - -``` - -This library attempts to bridge the gap between [Material Components for Android][mdc] M3 XML themes, and themes in [Jetpack Compose][compose], allowing your composable [`MaterialTheme`][m3materialtheme] to be based on the `Activity`'s XML theme: - - -``` kotlin -Mdc3Theme { - // MaterialTheme.colorScheme, MaterialTheme.typography, MaterialTheme.shapes - // will now contain copies of the Context's theme -} -``` - -This is especially handy when you're migrating an existing app, a `Fragment` (or other UI container) at a time. - -### Customizing the M3 theme - -The `Mdc3Theme()` function will automatically read the host `Context`'s MDC theme and pass them to [`MaterialTheme`][m3materialtheme] on your behalf, but if you want to customize the generated values, you can do so via the `createMdc3Theme()` function: - -``` kotlin -val context = LocalContext.current -var (colorScheme, typography, shapes) = createMdc3Theme( - context = context -) - -// Modify colorScheme, typography or shapes as required. -// Then pass them through to MaterialTheme... - -MaterialTheme( - colorScheme = colorScheme, - typography = typography, - shapes = shapes -) { - // Rest of M3 layout -} -``` - -### Limitations - -There are some known limitations with the implementation at the moment: - -* This relies on your `Activity`/`Context` theme extending one of the `Theme.Material3` themes. -* Text colors are not read from the text appearances by default. You can enable it via the `setTextColors` function parameter. -* Variable fonts are not supported in Compose yet, meaning that the value of `android:fontVariationSettings` are currently ignored. -* MDC `ShapeAppearances` allow setting of different corner families (cut, rounded) on each corner, whereas Compose's [Shapes][m3shapes] allows only a single corner family for the entire shape. Therefore only the `app:cornerFamily` attribute is read, others (`app:cornerFamilyTopLeft`, etc) are ignored. -* You can modify the resulting `MaterialTheme` in Compose as required, but this _only_ works in Compose. Any changes you make will not be reflected in the `Activity` theme. - ---- - -### Library Snapshots - -Snapshots of the current development version of this library are available, which track the latest commit. See [here](./docs/using-snapshot-version.md) for more information on how to use them. - ---- - -## Contributions - -Please contribute! We will gladly review any pull requests. -Make sure to read the [Contributing](CONTRIBUTING.md) page first though. +for usage refer to [Usage][USAGE.md] doc. ## License diff --git a/USAGE.md b/USAGE.md new file mode 100644 index 0000000..4a0447e --- /dev/null +++ b/USAGE.md @@ -0,0 +1,223 @@ +## Library Docs + +A library that enables reuse of [Material Components for Android][mdc] XML themes for theming in [Jetpack Compose][compose]. + +## Usage + +There are two artifacts available: + +* [`com.google.android.material:compose-theme-adapter`](#compose-material) + * Compatible with Compose Material + * Includes `MdcTheme` +* [`com.google.android.material:compose-theme-adapter-3`](#compose-material-3) + * Compatible with Compose Material 3 + * Includes `Mdc3Theme` + +```groovy +repositories { + google() +} + +dependencies { + // Compatible with Compose Material, includes MdcTheme + implementation "com.google.android.material:compose-theme-adapter:" + // Compatible with Compose Material 3, includes Mdc3Theme + implementation "com.google.android.material:compose-theme-adapter-3:" +} +``` + +See the [releases](https://github.com/material-components/material-components-android-compose-theme-adapter/releases) page for the latest versions. + +--- + +## Compose Material + +![MDC-Android Compose Theme Adapter header](docs/header.png) + +The basis of Material Design 2 theming in [Jetpack Compose][compose] is the [`MaterialTheme`][materialtheme] composable, where you provide [`Colors`][colors], [`Typography`][typography] and [`Shapes`][shapes] instances containing your styling parameters: + +``` kotlin +MaterialTheme( + colors = colors, + typography = type, + shapes = shapes +) { + // M2 Surface, Scaffold, etc. +} +``` + +[Material Components for Android][mdc] themes allow for similar theming for views via XML theme attributes, like so: + +``` xml + +``` + +This library attempts to bridge the gap between [Material Components for Android][mdc] M2 XML themes, and themes in [Jetpack Compose][compose], allowing your composable [`MaterialTheme`][materialtheme] to be based on the `Activity`'s XML theme: + + +``` kotlin +MdcTheme { + // MaterialTheme.colors, MaterialTheme.typography, MaterialTheme.shapes + // will now contain copies of the Context's theme +} +``` + +This is especially handy when you're migrating an existing app, a `Fragment` (or other UI container) at a time. + +!!! caution +If you are using an AppCompat (i.e. non-MDC) theme in your app, you should use +[AppCompat Compose Theme Adapter](https://github.com/google/accompanist/tree/main/appcompat-theme) +instead, as it attempts to bridge the gap between [AppCompat][appcompat] XML themes, and M2 themes in [Jetpack Compose][compose]. + +### Customizing the M2 theme + +The `MdcTheme()` function will automatically read the 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 `createMdcTheme()` function: + +``` kotlin +val context = LocalContext.current +val layoutDirection = LocalLayoutDirection.current +var (colors, typography, shapes) = createMdcTheme( + context = context, + layoutDirection = layoutDirection +) + +// Modify colors, typography or shapes as required. +// Then pass them through to MaterialTheme... + +MaterialTheme( + colors = colors, + typography = type, + shapes = shapes +) { + // Rest of M2 layout +} +``` + +### 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 the text appearances by default. You can enable it via the `setTextColors` function parameter. +* Variable fonts are not supported in Compose yet, meaning that the value of `android:fontVariationSettings` are currently ignored. +* MDC `ShapeAppearances` allow setting of different corner families (cut, rounded) on each corner, whereas Compose's [Shapes][shapes] allows only a single corner family for the entire shape. Therefore only the `app:cornerFamily` attribute is read, others (`app:cornerFamilyTopLeft`, etc) are ignored. +* You can modify the resulting `MaterialTheme` in Compose as required, but this _only_ works in Compose. Any changes you make will not be reflected in the `Activity` theme. + +## Compose Material 3 + +![MDC-Android Compose Theme Adapter header](docs/m3header.png) + +The basis of Material Design 3 theming in [Jetpack Compose][compose] is the [`MaterialTheme`][m3materialtheme] composable, where you provide [`ColorScheme`][m3colorscheme], [`Typography`][m3typography] and [`Shapes`][m3shapes] instances containing your styling parameters: + +``` kotlin +MaterialTheme( + colorScheme = colorScheme, + typography = typography, + shapes = shapes +) { + // M3 Surface, Scaffold, etc. +} +``` + +[Material Components for Android][mdc] themes allow for similar theming for views via XML theme attributes, like so: + +``` xml + +``` + +This library attempts to bridge the gap between [Material Components for Android][mdc] M3 XML themes, and themes in [Jetpack Compose][compose], allowing your composable [`MaterialTheme`][m3materialtheme] to be based on the `Activity`'s XML theme: + + +``` kotlin +Mdc3Theme { + // MaterialTheme.colorScheme, MaterialTheme.typography, MaterialTheme.shapes + // will now contain copies of the Context's theme +} +``` + +This is especially handy when you're migrating an existing app, a `Fragment` (or other UI container) at a time. + +### Customizing the M3 theme + +The `Mdc3Theme()` function will automatically read the host `Context`'s MDC theme and pass them to [`MaterialTheme`][m3materialtheme] on your behalf, but if you want to customize the generated values, you can do so via the `createMdc3Theme()` function: + +``` kotlin +val context = LocalContext.current +var (colorScheme, typography, shapes) = createMdc3Theme( + context = context +) + +// Modify colorScheme, typography or shapes as required. +// Then pass them through to MaterialTheme... + +MaterialTheme( + colorScheme = colorScheme, + typography = typography, + shapes = shapes +) { + // Rest of M3 layout +} +``` + +### Limitations + +There are some known limitations with the implementation at the moment: + +* This relies on your `Activity`/`Context` theme extending one of the `Theme.Material3` themes. +* Text colors are not read from the text appearances by default. You can enable it via the `setTextColors` function parameter. +* Variable fonts are not supported in Compose yet, meaning that the value of `android:fontVariationSettings` are currently ignored. +* MDC `ShapeAppearances` allow setting of different corner families (cut, rounded) on each corner, whereas Compose's [Shapes][m3shapes] allows only a single corner family for the entire shape. Therefore only the `app:cornerFamily` attribute is read, others (`app:cornerFamilyTopLeft`, etc) are ignored. +* You can modify the resulting `MaterialTheme` in Compose as required, but this _only_ works in Compose. Any changes you make will not be reflected in the `Activity` theme. + +--- + +### Library Snapshots + +Snapshots of the current development version of this library are available, which track the latest commit. See [here](./docs/using-snapshot-version.md) for more information on how to use them. + +--- + +## Contributions + +Please contribute! We will gladly review any pull requests. +Make sure to read the [Contributing](CONTRIBUTING.md) page first though. + +[migratexmltocompose]: https://developer.android.com/jetpack/compose/designsystems/views-to-compose +[compose]: https://developer.android.com/jetpack/compose +[mdc]: https://github.com/material-components/material-components-android +[appcompat]: https://developer.android.com/jetpack/androidx/releases/appcompat +[materialtheme]: https://developer.android.com/reference/kotlin/androidx/compose/material/MaterialTheme +[colors]: https://developer.android.com/reference/kotlin/androidx/compose/material/Colors +[typography]: https://developer.android.com/reference/kotlin/androidx/compose/material/Typography +[shapes]: https://developer.android.com/reference/kotlin/androidx/compose/material/Shapes +[m3materialtheme]: https://developer.android.com/reference/kotlin/androidx/compose/material3/MaterialTheme +[m3colorscheme]: https://developer.android.com/reference/kotlin/androidx/compose/material3/ColorScheme +[m3shapes]: https://developer.android.com/reference/kotlin/androidx/compose/material3/Shapes +[m3typography]: https://developer.android.com/reference/kotlin/androidx/compose/material3/Typography +[accompanist]: https://github.com/google/accompanist +[themeadaptermateriallib]: https://google.github.io/accompanist/themeadapter-material +[themeadaptermaterial3lib]: https://google.github.io/accompanist/themeadapter-material3 +[themeadaptercorelib]: https://google.github.io/accompanist/themeadapter-core \ No newline at end of file From 0f93af95b29c0df690afd92698fff6aafdcaaa2b Mon Sep 17 00:00:00 2001 From: Gurupreet Singh Date: Thu, 24 Aug 2023 15:31:22 +0200 Subject: [PATCH 4/5] keep usage as a file --- README.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/README.md b/README.md index d801a85..d716332 100644 --- a/README.md +++ b/README.md @@ -4,8 +4,6 @@ **Material Theme Adapter is deprecated. Use the Material Theme Builder tool, to generate a matching XML and Compose theme implementation for your app. See [Migrating XML themes to Compose][migratexmltocompose] to learn more.** -for usage refer to [Usage][USAGE.md] doc. - ## License ``` From bae05ef953e0e912e40083154d7794e1668e8ff1 Mon Sep 17 00:00:00 2001 From: Gurupreet Singh Date: Thu, 24 Aug 2023 15:35:21 +0200 Subject: [PATCH 5/5] added license to usage file --- USAGE.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/USAGE.md b/USAGE.md index 4a0447e..4797be6 100644 --- a/USAGE.md +++ b/USAGE.md @@ -205,6 +205,23 @@ Snapshots of the current development version of this library are available, whic Please contribute! We will gladly review any pull requests. Make sure to read the [Contributing](CONTRIBUTING.md) page first though. +## License + +``` +Copyright 2020 The Android Open Source Project + +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + + https://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limit + [migratexmltocompose]: https://developer.android.com/jetpack/compose/designsystems/views-to-compose [compose]: https://developer.android.com/jetpack/compose [mdc]: https://github.com/material-components/material-components-android