Skip to content

Latest commit

 

History

History
269 lines (190 loc) · 9.01 KB

index.md

File metadata and controls

269 lines (190 loc) · 9.01 KB

Nudge - Easy Snackbars for Compose

🛎️ Nudge simplifies snackbars, bringing quick, customizable notifications to your Compose apps!

Live Demo

Experience Nudge in action and see its features in real-time on our Live Demo.

Getting Started with Nudge

Adding Dependencies:

  • Manual Setup: This section guides you through adding Nudge dependencies directly to your project's build.gradle files. (Link to Manual Dependency Setup Section)
  • Version Catalog (Recommended): For a more streamlined approach, consider integrating a version catalog. This allows for centralized version management and easier updates. (Link to Version Catalog Section)

Note: If you prefer manual dependency setup, follow the instructions in the "Manual Setup" section. Otherwise, jump to the "Version Catalog" section for centralized management.

For information on using the KAPT plugin, see the KAPT documentation.
For information on using the KSP plugin, see the KSP quick-start documentation.
For more information about dependencies, see Add Build Dependencies.

Adding Nudge Dependencies Manually

To use Nudge in your app, add the following dependencies to your app's build.gradle file:

=== "Groovy"

```groovy title="build.gradle"
dependencies {
    def teogorNudge = "1.0.0-alpha01"
    
    implementation "dev.teogor.nudge:nudge-core:$teogorNudge"
}
```

=== "Kotlin"

```kotlin title="build.gradle.kts"
dependencies {
    val teogorNudge = "1.0.0-alpha01"
    
    implementation("dev.teogor.nudge:nudge-core:$teogorNudge")
}
```

Managing Nudge Versions with Version Catalog (Recommended)

This section guides you through utilizing a version catalog for centralized management of Nudge dependencies in your project. This approach simplifies updates and ensures consistency.

First, define the dependencies in the libs.versions.toml file:

  • Group-Name Based: This approach is used for declaring libraries referenced by group and artifact name.
  • Module Based: This approach is used for declaring libraries referenced by their module.

=== "Group-Name Based"

```toml title="gradle/libs.versions.toml"
[versions]
teogor-nudge = "1.0.0-alpha01"

[libraries]
teogor-nudge-core = { group = "dev.teogor.nudge", name = "nudge-core", version.ref = "teogor-nudge" }
```

=== "Module Based"

```toml title="gradle/libs.versions.toml"
[versions]
teogor-nudge = "1.0.0-alpha01"

[libraries]
teogor-nudge-core = { module = "dev.teogor.nudge:nudge-core", version.ref = "teogor-nudge" }
```

Then, add these dependencies in your app's build.gradle file:

=== "Groovy"

```groovy title="build.gradle"
dependencies {
    implementation libs.teogor.nudge.core
}
```

=== "Kotlin"

```kotlin title="build.gradle.kts"
dependencies {
    implementation(libs.teogor.nudge.core)
}
```

Basic Usage

Setup

To start using Nudge, you'll need to set up a NudgeState and integrate it into your Compose UI. Here's a step-by-step guide:

1. Create and Remember the NudgeState

Use rememberNudgeState to create and remember an instance of NudgeState. This should be done at the top level of your Composable function to ensure the state is preserved across recompositions.

@Composable
fun MyApp() {
  // Create and remember the NudgeState instance
  val nudgeState = rememberNudgeState(
    maxStack = 3,           // Maximum number of nudges that can be stacked
    animation = Animation.Bounce,  // Animation style for the nudge
    placement = Placement.BottomEnd  // Position of the nudge on the screen
  )
}

2. Integrate with Scaffold and Display Nudges

Once you have the NudgeState instance, integrate it into your Compose UI using the Scaffold and NudgeContainer. This ensures the nudges are displayed correctly within your app's layout.

@Composable
fun MyApp() {
  Scaffold(
    snackbarHost = {
      NudgeContainer(
        modifier = Modifier,
        state = nudgeState,
      )
    }
  ) {
    // Your screen content goes here
  }
}

Displaying a Nudge

To display a nudge, use the display extension method of NudgeState. This method provides a DSL-style API for configuring and customizing the nudge according to your needs.

Warning

Make sure to import the display extension to access the DSL features:

import dev.teogor.nudge.display

With the display method, you can adjust various aspects of the nudge, such as its title, description, duration, style, and more. Here’s an example of how to configure a nudge:

nudgeState.display {
  // Set the nudge type and its content
  success {
    setTitle("Operation Successful")
    setDescription("Your changes have been saved.")
  }

  // Configure the nudge duration
  duration(Duration.Short)

  // Add an action button
  button("OK") {
    // Define action to perform on button click
  }

  // Apply a style to the nudge
  style(Style.Default)
}

Customizing Your Nudge

To customize your nudge, you can use:

  • Nudge Types:

    • success { ... } for a success nudge
    • error { ... } for an error nudge
    • info { ... } for an informational nudge
    • warning { ... } for a warning nudge
    • loading { ... } for a loading nudge
    • content { dismiss -> ... } for a custom nudge

  • Duration:

    • Duration.Short for a brief display (4 seconds)
    • Duration.Medium for a moderate display (7 seconds)
    • Duration.Long for a longer display (10 seconds)
    • Duration.Persistent for an indefinite display until manually dismissed
    • Duration.Custom(duration) for a specific custom duration

  • Style:

    • Style.Default for the default appearance
    • Style.Inverse for an inverted color scheme

Certainly! Here's a dedicated section for the features table with the additional column for issue links:

Planned Features and Development Status

Below is a summary of the features planned or in progress for the Nudge library, along with their current development phase and links to related issues or tickets for more details, if available.

Feature Development Phase Issue Link
Button Action Return Value 🗓️ Planned Issue #1

Legend:

  • 🚧 Under Review: The feature is under review or in the testing phase.
  • 🛠️ In Progress: The feature is currently being worked on.
  • 🗓️ Planned: The feature is planned but not yet started.

Each issue link directs to the corresponding issue or ticket in your issue tracker, providing more details on the status and discussions around each feature.

Platform Compatibility

Below is a summary of the platform compatibility for the Nudge library, including its core module and related components:

Component Android Desktop Multiplatform
nudge-core ✅ ✅ ✅

Legend:

  • ✅ Supported: The component is fully supported on the platform.
  • ❌ Not Supported: The component is not supported on the platform.

Note

Multiplatform support includes iOS, WasmJS, JS, JVM, android, and macOS with configurations for iosX64, iosArm64, iosSimulatorArm64, browser, nodejs, macosX64, and macosArm64.

Additional Resources

For more detailed documentation and advanced usage, please refer to the Nudge Documentation.

Contributing

Contributions to Paletteon are welcome! If you have any ideas, bug reports, or feature requests, please open an issue or submit a pull request. For more information, please refer to our Contributing Guidelines.

Find this repository useful? ❤️

Support it by joining stargazers for this repository. ⭐
Also, follow me on GitHub for my next creations! 🤩

License

  Designed and developed by 2024 Teogor (Teodor Grigor)

  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.