p1: Add Gradle binary compatibility plugin

.github/workflows/lint.yml

@@ -49,8 +49,7 @@ jobs:
       - name: Run ktlint
         run: |
           cd android
-          ./gradlew lintKotlin --continue
-          ./gradlew :build-logic:convention:lint --continue
+          ./gradlew lint lintKotlin :build-logic:convention:lint --continue
 
   detekt:
     name: Detekt

README.md

@@ -10,8 +10,6 @@
 
 [Android library details and usage notes are here.](/android/README.md).
 
-[API documentation is here.](https://guardian.github.io/source-apps/android/docs/index.html).
-
 # iOS Usage 
 
 ## Adding the Swift Package To Xcode

android/README.md

@@ -7,12 +7,23 @@
 
 ## Add the library dependency
 
-Add the dependency to `build.gradle.kts` for the consuming module:
+Add the dependency to `build.gradle.kts` for the consuming module.
+
+In `build.gradle.kts`:
 
 ```kotlin
 implementation("com.gu.source:source-android:<version>")
 ```
 
+In version catalog:
+```toml
+[versions]
+source = "<version>"
+
+[libraries]
+source = { module = "com.gu.source:source-android", version.ref = "source" }
+```
+
 <!-- Alternatively, add it to your app's core design module as an `api` dependency. It will be transitively available to all other modules:
 
 ```kotlin
@@ -28,7 +39,9 @@ The library provides design presets and components.
 
 The design presets are available name spaced under the `com.gu.Source` object, e.g. `Source.Typography.HeadlineBold15`.
 
-[API documentation is here.](https://guardian.github.io/source-apps/android/docs/index.html).
+**[Full API documentation is available here.](https://guardian.github.io/source-apps/android/docs/index.html)**
+
+---
 
 ### Typography presets
 
@@ -61,98 +74,31 @@ Text(
 ```
 
 ---
+
 ### Buttons
 
 Four core button components are available - `SourceButton`, `SourceIconButton`, `PlainSourceButton` and `SourceBaseIconButton`.
 
-#### Themed buttons
-
-
-The first two source buttons have preset style and size variants corresponding to Source specifications. Both _Core_ and _Reader Revenue_ themes are provided. The latter two use Source defined sizing but can be used for custom colour schemes.
+[See here for full details of the button components.][buttons]
 
 | Core theme | Reader revenue theme |
 | --- | --- |
 | ![Core themed text only buttons](https://github.com/user-attachments/assets/e69393fb-675b-4f0e-9f52-62a28736bcfc) | ![Reader revenue themed text only buttons](https://github.com/user-attachments/assets/7ca3d409-252e-45e1-964f-efd03b1ebe39) |
 
-##### Usage examples
-
-Using `SourceButton`:
-```kotlin
-SourceButton(
-    text = "Sign in",
-    priority = SourceButton.Priority.PrimaryOnWhite,
-    onClick = {},
-    size = SourceButton.Size.Small,
-)
-```
-
-Using `SourceIconButton` with a Material Icon:
-```kotlin
-SourceIconButton(
-    icon = Icons.Default.Person,
-    priority = SourceButton.Priority.SecondaryOnBlue,
-    contentDescription = null,
-    onClick = {},
-    size = SourceButton.Size.Medium,
-)
-```
-
-Using `SourceIconButton` with a drawable resource:
-```kotlin
-SourceIconButton(
-    painter = painterResource(R.drawable.ic_person),
-    priority = SourceButton.Priority.SecondaryOnBlue,
-    contentDescription = null,
-    onClick = {},
-)
-```
-
-#### Base buttons
+---
 
-The plain and base buttons are intended for when custom colour schemes are needed. These do not use preconfigured `priority` or `theme`. They expect to be directly be provided with `ButtonColours`. (`PlainSourceButton` is available from version `0.2.1`, `SourceBaseIconButton` is available from `0.3.0`)
+### Chips
 
-##### Usage examples
+Chip components are typically used for filter, tags, or actions in a concise 
+format.
 
-```kotlin
-PlainSourceButton(
-    text = "Culture themed",
-    onClick = {},
-    modifier = Modifier.align(CenterHorizontally),
-    buttonColours = ButtonColours(
-        border = AppColour(
-            light = Source.Palette.Culture200,
-            dark = Source.Palette.Culture800,
-        ),
-        container = AppColour(
-            light = Source.Palette.Culture800,
-            dark = Source.Palette.Culture200,
-        ),
-        content = AppColour(
-            light = Source.Palette.Culture200,
-            dark = Source.Palette.Culture800,
-        ),
-    ),
-)
-```
-
-```kotlin
-SourceBaseIconButton(
-    buttonColours = buttonColours,
-    size = SourceButton.Size.Small,
-    onClick = { },
-) {
-    Icon(
-        imageVector = Source.Icons.Base.ChevronRight,
-        contentDescription = null,
-        modifier = it,
-    )
-}
-```
+[See here for full details of the chip components.][chips]
 
 ---
+
 ### Pager progress components
 
-There are three pager progress components available:
+Three pager progress components are available:
 
 1. `PagerProgressIndicator` - a set of indicators to signify progress as a user
 progresses through the items in the pager
@@ -161,87 +107,12 @@ in a pager
 3. `PagerProgressBar` - a higher level component that combines the above two
 and has different phone and tablet behaviour.
 
+[See here for more details on pager progress components.][pager]
 
-#### `PagerProgressBar`
-
-The `PagerProgressBar` component is used to signify progress as a user flips through the items in a `HorizontalPager`. It is typically used for image carousels.
-
-The progress bar is styled to match Source specifications. It is expected to be placed below the pager.
-
-On tablets, the bar also displays `PagerProgressButtons` to allow the user to go
-to next or previous pages.
-
-##### Usage example
 
 ![Progress bar for tablets](https://github.com/user-attachments/assets/ec1c2520-8c2c-42c0-9a8c-631054e77a67)
 
-
-```kotlin
-Column(
-    modifier = modifier .widthIn(max = 695.dp),
-) {
-    HorizontalPager(
-        state = pagerState,
-        modifier = Modifier
-            .aspectRatio(695 / 544f)
-            .clip(RoundedCornerShape(16.dp)),
-    ) { page ->
-        SampleImage(
-            randomKey = page,
-            modifier = Modifier.fillMaxWidth(),
-        )
-    }
-
-    // Place the bar below the pager
-    PagerProgressBar(pagerState = pagerState)
-}
-```
-
-#### Custom progress indicators
-
-`PagerProgressIndicator` is a lower level component used to signify progress in the bar. It provides a lot more options for customising appearance of the indicators.
-
-##### Usage example:
-
-![Custom indicator styling](https://github.com/user-attachments/assets/2d08a04d-a146-4ab0-a61c-5b8a89502cd1)
-
-
-```kotlin
-Column(modifier = Modifier.padding(8.dp)) {
-    HorizontalPager(state = pagerState) {
-        Box(
-            modifier = Modifier
-                .size(400.dp)
-                .background(Source.Palette.Neutral86, RoundedCornerShape(8.dp)),
-        ) {
-            Text(
-                text = (it + 1).toString(),
-                style = Source.Typography.Titlepiece70,
-                modifier = Modifier.align(Alignment.Center),
-                color = Source.Palette.Neutral46,
-            )
-        }
-    }
-
-    // Place indicator below the pager, style it and set alignment explicitly
-    PagerProgressIndicator(
-        pagerState = pagerState,
-        selectedIndicatorColour = Source.Palette.Sport500,
-        unSelectedIndicatorColour = Source.Palette.Sport500.copy(alpha = 0.3F),
-        indicatorShape = CutCornerShape(8.dp),
-        maxIndicatorCount = 7,
-        numberOfItemsToScale = 5,
-        modifier = Modifier
-            .padding(top = 8.dp)
-            .align(Alignment.CenterHorizontally),
-    )
-}
-```
-
-#### `PagerProgressButton`s
-
-A set of next & previous icon buttons to progress through the pages. The button
-enabled state depends on availability of a next/previous page.
+---
 
 ### Alert banners
 
@@ -305,4 +176,9 @@ AlertBanner(
 
 ### Other notes
 
-1. We use the `com.gu` package name and group id so we can use the Guardian's Sonatype infra for signing and publishing the library. See [this comment](https://github.com/guardian/source-android/pull/10/files?w=1#r1567071142) for reference. 
+1. We use the `com.gu` package name and group id so we can use the Guardian's Sonatype infra for signing and publishing the library. See [this comment](https://github.com/guardian/source-android/pull/10/files?w=1#r1567071142) for reference. 
+
+
+[buttons]: ./source/src/main/kotlin/com/gu/source/components/buttons/README.md
+[pager]: ./source/src/main/kotlin/com/gu/source/components/pager/README.md
+[chips]: ./source/src/main/kotlin/com/gu/source/components/chips/README.md

android/build-logic/convention/build.gradle.kts

@@ -50,11 +50,6 @@ gradlePlugin {
             implementationClass = "com.theguardian.convention.ComposeApplicationConventionPlugin"
             version = "1"
         }
-        register("guardianDetektPlugin") {
-            id = "com.theguardian.detekt"
-            implementationClass = "com.theguardian.convention.DetektPlugin"
-            version = "1"
-        }
         register("androidTestPlugin") {
             id = "com.theguardian.test.android"
             implementationClass = "com.theguardian.convention.AndroidTestConventionPlugin"

android/build-logic/convention/gradle-lint-baseline.xml

@@ -1,15 +1,26 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<issues format="6" by="lint 8.7.2" type="baseline" client="gradle" dependencies="false" name="AGP (8.7.2)" variant="all" version="8.7.2">
+<issues format="6" by="lint 8.7.3" type="baseline" client="gradle" dependencies="false" name="AGP (8.7.3)" variant="all" version="8.7.3">
 
     <issue
         id="GradleProjectIsolation"
         message="Avoid using method getRootProject"
-        errorLine1="            val rootProject = target.rootProject"
-        errorLine2="                                     ~~~~~~~~~~~">
+        errorLine1="                rootProject.layout.buildDirectory.file(&quot;reports/detekt/merge.sarif&quot;),"
+        errorLine2="                ~~~~~~~~~~~">
         <location
-            file="src/main/kotlin/com/theguardian/convention/DetektPlugin.kt"
-            line="23"
-            column="38"/>
+            file="src/main/kotlin/com/theguardian/convention/shared/SetupDetekt.kt"
+            line="20"
+            column="17"/>
+    </issue>
+
+    <issue
+        id="GradleProjectIsolation"
+        message="Avoid using method getRootProject"
+        errorLine1="            basePath = rootProject.projectDir.absolutePath"
+        errorLine2="                       ~~~~~~~~~~~">
+        <location
+            file="src/main/kotlin/com/theguardian/convention/shared/SetupDetekt.kt"
+            line="57"
+            column="24"/>
     </issue>
 
 </issues>

android/build-logic/convention/src/main/kotlin/com/theguardian/convention/AndroidApplicationConventionPlugin.kt

@@ -1,10 +1,7 @@
 package com.theguardian.convention
 
 import com.android.build.api.dsl.ApplicationExtension
-import com.theguardian.convention.shared.configureAndroidModule
-import com.theguardian.convention.shared.configureAndroidTests
-import com.theguardian.convention.shared.libs
-import com.theguardian.convention.shared.plugin
+import com.theguardian.convention.shared.*
 import org.gradle.api.Plugin
 import org.gradle.api.Project
 import org.gradle.kotlin.dsl.configure
@@ -29,6 +26,8 @@ class AndroidApplicationConventionPlugin : Plugin<Project> {
                 apply(libs.plugin("kotlinter").pluginId)
             }
 
+            setupDetekt()
+
             extensions.configure<ApplicationExtension> {
                 defaultConfig {
                     targetSdk = libs.findVersion("targetsdk").get().toString().toInt()

android/build-logic/convention/src/main/kotlin/com/theguardian/convention/AndroidLibraryConventionPlugin.kt

@@ -31,6 +31,8 @@ class AndroidLibraryConventionPlugin : Plugin<Project> {
                 apply(libs.plugin("kotlinter").pluginId)
             }
 
+            setupDetekt()
+
             extensions.configure<LibraryExtension> {
                 configureAndroidModule<KotlinAndroidProjectExtension>(this)
 

android/build-logic/convention/src/main/kotlin/com/theguardian/convention/AndroidTestConventionPlugin.kt

@@ -1,10 +1,7 @@
 package com.theguardian.convention
 
 import com.android.build.gradle.TestExtension
-import com.theguardian.convention.shared.configureAndroidModule
-import com.theguardian.convention.shared.configureAndroidTests
-import com.theguardian.convention.shared.libs
-import com.theguardian.convention.shared.plugin
+import com.theguardian.convention.shared.*
 import org.gradle.api.Plugin
 import org.gradle.api.Project
 import org.gradle.kotlin.dsl.configure
@@ -29,6 +26,8 @@ class AndroidTestConventionPlugin : Plugin<Project> {
                 apply(libs.plugin("kotlinter").pluginId)
             }
 
+            setupDetekt()
+
             extensions.configure<TestExtension> {
                 configureAndroidModule<KotlinAndroidProjectExtension>(this)