Skip to content

πŸ“ Visualize the dimensions of your composables on a blueprint!

License

Notifications You must be signed in to change notification settings

popovanton0/Blueprint

Folders and files

NameName
Last commit message
Last commit date

Latest commit

Β 

History

20 Commits
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 

Repository files navigation

πŸ“ Blueprint

Release Introductory Medium Article License

Visualize the dimensions of your composables on a blueprint

Blueprint Usage Example Blueprint Usage Example

Introductory Medium Article

The Problem

Have you ever desired to see, what exactly is that padding's value while looking at the composable preview window? Especially when you are developing a button with 5 color styles, 3 sizes, and 2 optional icons; and each combination of these parameters has different paddings?

Combinatorial explosion of UI components in design systems requires having a lot of context about paddings, dp's, sizes, corner radiuses, and other dimensional information in your head at the same time.

Many combinations of buttons Many combinations of buttons

In addition, code to produce those combinations can get tricky to analyze. So, verification also becomes hard: you make screenshots, move them to Figma, overlay them on top, and try to see the difference. Tedious 😩!

The Solution

The Blueprint library provides a way to visualize dimensional information in your UI using a simple DSL-based definition:

  1. Just wrap your target UI in a Blueprint composable
  2. Mark children with Modifier.blueprintId(id: String) modifier
  3. Write the blueprint definition
Blueprint(
    blueprintBuilder = {
        widths {
            group {
                "item0".right lineTo "item1".left
                "item0" lineTo "item0"
                "item2" lineTo "item3"
            }
        }
        heights {
            group { "item0Icon" lineTo "item0Text" }
            group { "item0" lineTo "item0" }
            group(End) { "item3Icon".bottom lineTo "item3Text".top }
        }
    }
) {
    val items = remember { listOf("Songs", "Artists", "Playlists", "Settings") }
    NavigationBar {
        items.forEachIndexed { index, item ->
            NavigationBarItem(
                modifier = Modifier.blueprintId("item$index"),
                icon = { Icon(Modifier.blueprintId("item${index}Icon"), TODO()) },
                label = { Text(Modifier.blueprintId("item${index}Text"), TODO()) },
                selected = index == 0,
                onClick = { TODO() }
            )
        }
    }
}

Preview

Blueprint Usage Example Blueprint Usage Example

And another example:

Blueprint Usage Example Blueprint Usage Example

Correct arrow padding rendering animation

arrow-angle-anim.mp4
Debug
arrow-angle-anim-debug.mp4
More examples
These are snapshots from snapshot testing:
almost_none_space_to_draw no_blueprint_if_globally_disabled
arrow_customization 0 not_enough_space_to_draw
arrow_customization 15 padding_not_applied
arrow_customization 45 reacts_to_blueprint_builder_update_(with_green)
arrow_customization 90 reacts_to_blueprint_builder_update_(without_green)
basicTest size_labels
correct_line_widths_and_alignments when_blueprint_is_disabled_it_is_not_shown
customFontSizeAndColor when_specifying_blueprint_ids_that_are_not_referenced_in_the_composable_no_dimensions_are_shown
emptyBlueprint when_specifying_blueprint_ids_that_are_then_removed_from_the_composition_dimensions_are_shown_and_then_hidden_(with_green)
fractional_dp_values_rendering when_specifying_blueprint_ids_that_are_then_removed_from_the_composition_dimensions_are_shown_and_then_hidden_(without_green)

Features

You can customize

  1. Line and border strokes (width and color)
  2. Font size and color
  3. Arrow style (length, angle, round or square cap)
  4. Decimal precision of the dimensional values

Of course, Blueprint works in Android Studio's Preview✨!

Also, you can disable all the overhead of this library in your release builds by either:

  1. Disabling blueprint rendering using blueprintEnabled property.
  2. Using the no-op version of the library:
    dependencies {
        debugImplementation("com.github.popovanton0.blueprint:blueprint:1.0.0-alpha05")
        releaseImplementation("com.github.popovanton0.blueprint:blueprint-no-op:1.0.0-alpha05")
    }

Getting Started

Release

Groovy

Add the following code to your project's root build.gradle file:

repositories {
    maven { url "https://jitpack.io" }
}

Next, add the dependency below to your module's build.gradle file:

dependencies {
    implementation "com.github.popovanton0.blueprint:blueprint:1.0.0-alpha05"
}
Kotlin

Add the following code to your project's root settings.gradle.kts file:

dependencyResolutionManagement {
    // ...
    repositories {
        // ...
        maven { url = uri("https://jitpack.io") }
    }
}

Next, add the dependency below to your module's build.gradle.kts file:

dependencies {
    implementation("com.github.popovanton0.blueprint:blueprint:1.0.0-alpha05")
}

Or using Gradle Version Catalog:

[versions]
blueprint = "1.0.0-alpha05"

[libraries]
blueprint = { module = "com.github.popovanton0.blueprint:blueprint", version.ref = "blueprint" }

Warning

Do not use this dependency notation: com.github.popovanton0:blueprint:1.0.0-alpha05. It doesn't work!

Licence

Copyright 2023 Anton Popov

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

http://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
limitations under the License.