Apache Solr open-source search software
= Component Development
:toc: left
== Overview
The following list contains a possible approach for implementing a new UI component:
1. Create a new design or start with an existing design, see for example Figma
2. Validate the use case and analyze the components that may be used for the implementation
3. Create Composables that represent the UI component(s) and use placeholders for data population
4. Define the UI state class and the interactions of the UI component, and create a view model
(or a state holder) for them
5. Create previews with fake UI state to check the UI implementation
6. Create a repository for fetching resources and interacting with Solr backend, and use cases
for the logic on top of it
7. Create the component interface and implementation that provides the repository, the use cases
and the view model
8. Write tests and test the new component
9. If not already done, integrate the component in the existing application
10. If not already done, extract resources like texts to allow internationalization and localization
It is recommended to take a look at existing components, so that you get a better understanding
of how things are implemented, what they have in common, and how each technology is utilized.
== Component's Logic
=== Components
The component provides everything the UI needs to get started: the dependencies of the logic
(repositories and use cases) and factory methods for creating view models. The composables use
these factory methods to retrieve their view model:
[source,kotlin]
----
val viewModel = viewModel { component.createEnvironmentViewModel() }
val uiState by viewModel.uiState.collectAsState()
----
The component does not hold any state. This keeps components simple, and allows replacing
the dependencies with fake ones in tests and previews.
=== View Models and State Holders
The view model and the state holder manage the state of a screen or section. They "catch" user
inputs like clicks through function calls, for example `viewModel.connect()`. The state
holder handles them, may call a use case to send a request to the backend, and updates the UI
state. So once the state is updated, it will reflect the changes in the UI.
- The UI state is exposed as a `StateFlow` and is usually a single immutable data class
(`[Name]UiState`) that has default values for all properties.
- Events that are meant for the parent (like navigating away) are exposed as a `SharedFlow`.
Events are not part of the state, as they should be handled only once.
- Coroutines are launched in the provided scope. Blocking work like network requests is switched
to the IO dispatcher of the injected `AppDispatchers`, so that tests can replace it.
The logic lives in a plain state holder class that receives the coroutine scope as a parameter,
and a thin view model wraps it with `viewModelScope`. Keeping the logic out of the `ViewModel`
makes it possible to test it without any additional setup and to share it between view models.
=== Use Cases and Repositories
Repositories define the requests against the Solr API and return a `Result`. Use cases wrap a
single piece of logic on top of them, like validating an input, mapping errors or deciding what
to do with a response. State holders only depend on use case interfaces, which keeps the
state holders free of API details and easy to test with fake use cases.
== Component's Visuals
=== Composables
Composables are the UI elements that are defined and styled. They can be seen as boxes, rows and
columns that are nested and change their style and structure based on conditions, state and input.
There are many ways to get started, but the easiest way probably is to get familiar with the basics
and try things out. The Figma designs make use of almost the same elements for designing,
so the structure and configurations there may be mapped almost one-by-one in Compose code.
=== Styling
The styling in Compose is done via ``Modifier``s. Each composable should normally accept a modifier
as a parameter, so that the user can customize specific visual parameters of the composable like
width, height and alignment in the parent's composable.
Since we are using Material 3, you do not have to care much about colors, typography and shapes.
These are configured for the entire app, and you only have to make use of the right properties
that are provided by the theme.
=== Accessibility
Compose comes with many accessibility features that can be used to improve the user experience.
The simplest form of accessibility in a UI is probably the responsiveness of the UI. This is
realized with `WindowSizeClass`. Some composables may use a wrapper (usually suffixed with
`Content`) that checks the window size and loads different UI based on the dimensions of the
current window.
Another accessibility feature is the resource loading based on the system's locale or the user's
preference. This allows the UI to be displayed in the user's native language. For that, you have
to simply provide translations in the Compose resources.
Another accessibility feature often underestimated is coloring. Some people with color vision
deficiency may need a different theme, so that elements with problematic contrasts may be
better visible again.
Additional accessibility features like font scaling, semantics for screen readers may also
be considered. Jetpack Compose provides a https://developer.android.com/develop/ui/compose/accessibility[simplified overview]
and https://developer.android.com/codelabs/jetpack-compose-accessibility#0[Codelabs] for getting started.
=== Navigation and Child Components
Some components may have navigation elements and will load other components inside a frame layout.
The navigation state is a back stack that is owned by the view model of the component, and the
composable renders it with `NavDisplay`. Each destination is described by a serializable
navigation key that implements `NavKey`, for example:
[source,kotlin]
----
@Serializable
sealed interface MainScene : NavKey {
@Serializable
data object Cluster : MainScene
// ...
}
----
The composable maps each key to the content of the destination in the `entryProvider`. Use the
`ViewModel` scope of the navigation entry (`rememberViewModelStoreNavEntryDecorator()`), so that
the view models of a destination are cleared once it is removed from the back stack.
Components of child destinations are provided by the parent component, and the composables of the
children report what the parent needs to know via events (`SharedFlow`s) or callbacks. The parent
then handles these by updating its back stack, see `RootViewModel` for an example.
The
https://developer.android.com/guide/navigation/navigation-3[Navigation 3 documentation]
provides more details about the concepts and recipes for common navigation use cases.
== Additional Notes
=== Dependency Locking
When adding or changing dependencies, you typically run `./gradlew resolveAndLockAll --write-locks`.
Since we are building a web application from kotlin sources, we also have to update the JS lockfile
with `./gradlew kotlinUpgradeYarnLock`. This will update the lockfile found at `kotlin-js-store/yarn.lock`.
Some multiplatform libraries have platform-specific dependency resolution that will result in different
lockfiles being generated, based on the environment the lock task is executed. It is important to exclude
these platform-specific libraries from the lockfile to ensure a consistent lockfile generation across
different operating systems.
Platform-specific libraries come with a module name suffix that includes the platform name, like
in `org.jetbrains.compose.desktop:desktop-jvm-windows-x64`. To identify those, look into the
changes after updating the lockfile and add the necessary ignore-clause if such libraries
exist. These ignore-clauses should be added in `gradle/validation/dependencies.gradle` inside the
`allprojects.dependencyLocking` block.