Skip to content

armgit / solr

Public Imported from GitHub
0

Apache Solr open-source search software

6.1 KB
Raw Blame
= Module Structure and Elements

== Module Structure

The `ui` module follows a quite simple structure. It is split in

- *components*, which covers the logic part of the frontend and therefore contains
the interfaces and implementations of them,
- the *UI* part, which covers the visual elements, styling and everything related to UI, and
- the *utils*, which contains various utilities used in both UI and logic.

In general, both UI and logic of the frontend are separated in "components" that follow similar,
if not the same, structure and files.

== Components (Logic)

The logical part of a simple component (`org/apache/solr/ui/components`) usually consists of:

- **The component interface** (`[ComponentName]Component.kt`), that provides the dependencies of
the component (repositories and use cases) and factory methods for creating its view models. It
does not hold any state itself,

- **The component implementation** (`integration/Default[ComponentName]Component.kt`), that
creates the dependencies lazily and passes them to the view models it creates. Some components
keep the interface and the implementation together in a `di` package instead (see `configsets`),

- **The repository interface** (`repository/[ComponentName]Repository.kt`), that defines the
requests that can be made against the (Solr) API, and its implementation (usually
`data/Http[ComponentName]Repository.kt`), that uses a preconfigured HTTP client,

- **The use cases** (`domain/*UseCase.kt`), that encapsulate a single piece of business logic like
loading, validating or mapping errors. They are defined as an interface and have a default
implementation (`Default[Name]UseCase`) that is using the repository,

- **The state holder** (`viewmodel/[ComponentName]StateHolder.kt`), a plain class that holds the
UI state as `StateFlow` and emits events as `SharedFlow`. It is created with a `CoroutineScope`,
so that it can be tested without Android or UI dependencies. The UI state class
(`[ComponentName]UiState`) is defined next to it,

- **The view model** (`viewmodel/[ComponentName]ViewModel.kt`), that is created by the component
implementation and provides the scope for the state holder. It exposes the state, the events and
the functions that the UI can call. Simple components may implement their state in the view model
directly,

- **Component-specific events** (`domain/*Event.kt`), that are emitted by the state holder to let
the parent (for example the screen that navigates) know that something happened,

- **Component-specific API classes** (`data/*`), that are used for representing API requests /
responses.

Some components may use multiple repositories to consume different API endpoints or none at all
if no API interaction is necessary. Multiple state holders may also be used to simplify the
complexity or separate the responsibilities into smaller UI elements, and can be shared between
view models (see `configsets`). The `auth` component, for example, uses one state holder per
authentication method and a parent state holder that holds the shared state.

Component data classes for API and internal use may also be merged and used interchangeably to
reduce overall complexity. However, this affects the separation of concerns and may require
in a later state the separation and mapping again.

=== Navigation

The screens and sections are navigated with Navigation 3. The navigation state is a back stack
of navigation keys (`RootScene`, `MainScene`, `ConfigsetsScene`) that is owned by a view model
(`RootViewModel`, `MainViewModel`, `ConfigsetsRouteViewModel`). The parent components provide the
components of the screens they display, like `RootComponent.createStartComponent()`.

Screens report user flows to their parent via events, like `StartEvent` or `AuthenticationEvent`.
The parent view model handles the event by changing the back stack.

== User Interface (UI)

Similar to the logical part, the UI classes are also separated in components under
`org.apache.solr.ui.views`.

Components may consist of one or multiple composables that make up a screen, section or
element. The composables may also be reused, which is why they may be moved at some point
during development to `.ui.components`.

Some vector assets like logos may be migrated to `ImageVector` and placed in `.ui.icons`
to later be used in the UI.

Theme-related classes, functions and variables are all placed inside `.ui.theme`. The UI
is making strong use of and customizes Material 3. You can find more information about
Compose and Material 3 at https://m3.material.io/develop/android/jetpack-compose[Material Design - Jetpack Compose].

Composables may accept a component, retrieve the view model from it and therefore be stateful, or
simply hoist the entire state via parameters and be stateless. A common approach is to provide both:
a stateful composable that connects the view model to a stateless composable of the same name that
takes the UI state and callbacks (for example `StartContent(component, onEvent)` and
`StartContent(uiState, onSolrUrlChange, onConnect)`). The stateless variants are used for
previews and UI tests, as they do not need any further setup. For more information about state
hoisting, you can have a look at https://developer.android.com/develop/ui/compose/state[Managing state].

=== Compose Resources

Compose Resources are similar to assets in a web app and can be found at
`commonMain/composeResources`. They contain files like fonts, translations, images,
raw files and more.

The resource directories can use "qualifiers" that allow files to have variants.
The most common use case is having translations for any text loaded. The directory
`values/strings.xml` is the default / fallback strings resource file, that holds all values
in english. If we would like to add translations for german now, we could use
`values-de/strings.xml` and translate individual strings to german. Any string that is used
and has no translation will automatically fall back to the value stored in `values/strings.xml`.

At the moment of writing, the language, theme and density qualifier are supported.

For more information about Compose Resources, see
https://www.jetbrains.com/help/kotlin-multiplatform-dev/compose-images-resources.html[Multiplatform Resources].