Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

SOLR-14414: Introduce new UI (SIP-7) #2605

Merged
merged 73 commits into from
Feb 8, 2025
Merged
Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
73 commits
Select commit Hold shift + click to select a range
f68e210
Introduce libs.versions.toml
malliaridis Jun 28, 2024
5308579
Add basic Compose integration example for webapp
malliaridis Jun 29, 2024
3cb969d
Add Solr initial theme colors
malliaridis Jul 4, 2024
8febc99
Add main navigation UI composables (without components)
malliaridis Jul 5, 2024
104f70a
Add advanced example with query parameter navigation for Web
malliaridis Jul 5, 2024
0db70c6
Add example implementation for environment section
malliaridis Jul 10, 2024
c58ab93
Add vertical scrolling to navigation sidebar
malliaridis Jul 10, 2024
3d433ae
Allow special floating point values in JSON serialization
malliaridis Jul 10, 2024
d95ffd4
Remove invalid JS dependency from WasmJS target
malliaridis Jul 10, 2024
08413a7
Undo temporary forced light theme change
malliaridis Jul 10, 2024
4423402
Update Ktor to EAP version to build WasmJS target
malliaridis Jul 10, 2024
0a0cdea
Add README.md for compose-ui module
malliaridis Jul 10, 2024
9bc5c89
Add missing Raleway font license
malliaridis Jul 10, 2024
682da1f
Use correct name for environment store instance
malliaridis Jul 10, 2024
c487ebe
Remove unused EnvironmentComponent state values
malliaridis Jul 10, 2024
2d608af
Add documentation to environment classes
malliaridis Jul 10, 2024
e41d8db
Add reference button for new UI in java-properties.html
malliaridis Jul 15, 2024
78625c6
Add additional information to README.md
malliaridis Jul 15, 2024
02dd043
Add dev-docs for UI development with Kotlin/Compose
malliaridis Jul 27, 2024
ef275b7
Introduce ExtendedTypography
malliaridis Jul 28, 2024
a35e223
Add ExtendedColorScheme to SolrTheme
malliaridis Jul 28, 2024
b515718
Cleanup code and add documentation
malliaridis Jul 28, 2024
17836c0
Add missing copyright headers
malliaridis Jul 30, 2024
89796e6
Add copyright header to compose-ui/README.md
malliaridis Aug 9, 2024
7cf132f
Update UI dependencies
malliaridis Oct 19, 2024
b40058a
Provide default values in data classes
malliaridis Oct 19, 2024
dd0d0e7
Remove maven repositories for experimental versions
malliaridis Oct 19, 2024
ce166df
Improve documentation grammar
malliaridis Oct 19, 2024
32caeea
Remove custom fonts
malliaridis Oct 19, 2024
5329a57
Merge branch 'refs/heads/main' into composeui
malliaridis Oct 24, 2024
9ad0019
Optimize responsiveness of EnvironmentContent
malliaridis Oct 24, 2024
3b77548
Collapse footer on breakpoint
malliaridis Oct 24, 2024
7abd211
Cleanup dependencies
malliaridis Oct 24, 2024
e2c7a4a
Update Decompose and Essenty
malliaridis Oct 24, 2024
9805dc3
Cleanup imports
malliaridis Oct 24, 2024
7860a35
Merge remote-tracking branch 'apache/main' into composeui
malliaridis Oct 24, 2024
674d008
Update gradle.properties template for Compose builds
malliaridis Oct 29, 2024
d0223d4
Add information about the gradle.properties changes
malliaridis Oct 29, 2024
65bb0ac
Remove duplicate request execution
malliaridis Oct 30, 2024
a166ca5
Merge remote-tracking branch 'apache/main' into composeui
malliaridis Nov 15, 2024
6bfb05f
Merge remote-tracking branch 'apache/main' into composeui
malliaridis Nov 15, 2024
e796a95
Format version catalogs
malliaridis Nov 15, 2024
704c6e2
Include multiplatform dependencies for version locking
malliaridis Nov 16, 2024
d026f31
Remove desktop configurations from version locking
malliaridis Nov 16, 2024
25be6b1
Fix turbocharge and dummy outputs hacks
malliaridis Nov 16, 2024
f96590c
Update UI related dependencies
malliaridis Nov 16, 2024
8fee6aa
Override LocalContentColor for FooterAction
malliaridis Nov 16, 2024
16d32b8
Replace deprecated id with threadId
malliaridis Nov 16, 2024
5d161f5
Disable hints for Compose assets
malliaridis Nov 28, 2024
e445364
Distinguish between development and production builds
malliaridis Nov 28, 2024
60211f2
Increase reserved code cache size
malliaridis Nov 28, 2024
97fb1c3
Improve build times via development flag
malliaridis Dec 6, 2024
517ed98
Merge branch 'main' into composeui
malliaridis Dec 7, 2024
2a04a7e
Merge branch 'main' into composeui
malliaridis Jan 24, 2025
e08d4fd
Fix issue where projects.configure does not exist
malliaridis Jan 24, 2025
c8f1f5b
Update compose-ui dependencies and fix lock state issues
malliaridis Jan 24, 2025
4496ffb
Swap development property with production property
malliaridis Jan 25, 2025
f17a013
Update renovate.json to execute kotlinUpgradeYarnLock
malliaridis Jan 25, 2025
9d66866
Update and add missing documentation
malliaridis Jan 25, 2025
54168a4
Cleanup redundant gradle configurations
malliaridis Jan 25, 2025
bd582cd
Update custom compose tasks with description and group
malliaridis Jan 26, 2025
8f11d09
Update SolrLogo to use SVGs
malliaridis Jan 27, 2025
9c23bbc
Improve app colors
malliaridis Jan 27, 2025
96b4765
Update Solr desktop distribution data
malliaridis Jan 27, 2025
d8e0da4
Add unit and UI test samples
malliaridis Jan 27, 2025
19ac4f0
Add missing license header
malliaridis Jan 27, 2025
f8fa8fe
Fix the flow collection and timeouts in tests
malliaridis Jan 28, 2025
28ae113
Fix xml server files selection based build variants
malliaridis Jan 28, 2025
b894da9
Move New UI button to left navigation menu
malliaridis Jan 28, 2025
cd94908
Add compose-ui module to labeler
malliaridis Jan 29, 2025
fdf91de
Merge remote-tracking branch 'apache/main' into composeui
malliaridis Jan 29, 2025
b8be6c2
Add change entry for new UI
malliaridis Jan 29, 2025
23e53d2
Remove "compose" from packages, paths and names
malliaridis Feb 4, 2025
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
Update and add missing documentation
  • Loading branch information
malliaridis committed Jan 25, 2025
commit 9d66866456f56165a552d0c83bf07be96477df46
25 changes: 22 additions & 3 deletions dev-docs/ui/component-development.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -12,8 +12,8 @@ The following list contains a possible approach for implementing a new UI compon
5. Create previews with preview component implementations to check the UI implementation
6. Create a store and store provider for fetching resources and interacting with Solr backend
7. Implement the client used by the store provider
8. Write test and test the new component
9. If not already done, integrate component in the existing application
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
Expand All @@ -26,7 +26,7 @@ of how things are implemented, what they have in common, and how each technology
The component integration interacts with the UI composables and the state store.

The implementation of the component interface "catches" user inputs like clicks and passes them
to the store as `Intent`s. The intents are then handled by the store implementation and
to the store as ``Intent``s. The intents are then handled by the store implementation and
may send a request to the backend and / or update the store state. The component is consuming
and mapping the store state to the UI state. So once the store state is updated, it will
reflect the changes in the UI.
Expand Down Expand Up @@ -96,3 +96,22 @@ Since components hold a hierarchical context that needs to be managed somehow, c

Decompose provides https://arkivanov.github.io/Decompose/navigation/overview/[a few examples]
and details of the process behind the navigation and child components.

== 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.
5 changes: 3 additions & 2 deletions dev-docs/ui/module-structure.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -40,7 +40,7 @@ if no API interaction is necessary. Multiple components may also be used to simp
or separate the responsibilities into smaller UI elements.

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

This structure is strongly inspired by Decompose's https://arkivanov.github.io/Decompose/samples/[samples].
Expand All @@ -51,7 +51,8 @@ Similar to the logical part, the UI classes are also separated in components und
`org.apache.solr.composeui.ui`.

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 to `.ui.components`.
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.
Expand Down
129 changes: 127 additions & 2 deletions dev-docs/ui/testing-and-deployment.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -2,18 +2,143 @@

== Testing

=== Local Environment
Thanks to the abstraction and separation of concerns, UI and logic can be tested and previewed
independently and in combination.

=== Composable Previews

In the local environment, you can use the
https://plugins.jetbrains.com/plugin/16541-compose-multiplatform-ide-support[Compose Multiplatform plugin]
for IntelliJ to render previews in the IDE. These previews are stored in `desktopMain` and
are simple composables marked with `@Preview`.

Note that UI component previews come with many limitations. They work only with static data,
have limited interaction support and do not have an environment context. They are only useful
for previewing how a component will be rendered with fake data, so bear that in mind while
using previews.

=== Execution

You can always run the new UI as a standalone client or in web. When working on the UI,
the web is not very flexible, as you have to stop any running Solr instance, build the entire
project, and then restart the Solr instance. There are options to launch the web UI separately,
but you will likely run into CORS issues.

For this reason, it is recommended to always use the JVM client for development and have a Solr
instance running in the background. This way, you can apply changes and restart the UI without
restarting the Solr server.

To launch the JVM client, you can use:

[source,bash]
----
./gradlew :solr:compose-ui:run
----

To run the app on the web, you can launch the web target with:

[source,bash]
----
# not recommended for the above reasons
./gradlew :solr:compose-ui:wasmJsBrowserRun
----

Build times may be a bit longer than with the standalone JVM build.

=== Integration Tests

The integration tests of the module focus on testing the implementation found in
`org.apache.solr.composeui.ui`. That includes all UI elements / composables. Integration tests
may test entire flows as well, but require a suitable testing environment.

Since UI tests require a more complex and platform-specific testing environment, they are disabled
by default in the automation pipelines, and only unit tests are executed. Once we have meaningful
UI tests and a suitable testing environment for them, we may run these tests in the pipelines.

=== Unit Tests

Unit tests test the implementation found in `org.apache.solr.compose.components`. That package
includes the logical part of the new UI and does not have any constraints to the UI part.
Therefore, they can be executed in the automation pipelines easily.

The unit tests use mocks for the API and test mainly the behavior and state changes of the
components to confirm correct component state transitions with specific inputs.

== Deployment

The `compose-ui` module is configured to build artifacts for `WebAssembly` and `JVM`.

=== Packaging

The module `compose-ui` can be built and packaged for two targets (wasmJs / JVM) with two
variants each, development and production.

To package the JVM target for development and generate a distribution (DEB, MSI or DMG file),
you can use:

[source,bash]
----
./gradlew :solr:compose-ui:packageDistributionForCurrentOS
----

The distribution can be found at `solr/compose-ui/build/compose/binaries/main/[deb|msi|dmg]/`.

To build the JVM target for production, you can use:

[source,bash]
----
./gradlew :solr:compose-ui:packageReleaseDistributionForCurrentOS
----

Platform-specific gradle tasks exist as well, but you cannot build for a
platform other than the current one.

If the client machine has Java installed, you can also generate an UberJar:

[source,bash]
----
# for development
./gradlew :solr:compose-ui:packageUberJarForCurrentOs

# for production
./gradlew :solr:compose-ui:packageReleaseUberJarForCurrentOs
----

When building the entire Solr project, the wasmJs target is included in the build artifacts.
If no configuration is provided, it will automatically use the development variant. This is
the default configuration to avoid any long-lasting production builds in the automation pipelines.
To tell the build process to use the production variant instead, you have ot pass
`production=true` in the `gradle.properties`.

=== Targets

=== CI/CD Pipelines
==== wasmJs

The WebAssembly (wasmJs) target is used to generate artifacts that can be hosted together
with our current webapp. The `server` that hosts the webapp is configured to host the new UI
as a module that is available under the URL path `/solr/compose`.

For that, two configuration files are added, one for development (`jetty-new-ui-dev.xml`) and
one for production (`jetty-new-ui.xml`). The module configuration for development is less strict,
as it enables specific debugging options important for development.

When packaging the project for production, the development configuration is replaced with the
more secure production configuration.

Like other modules, the new UI is enabled with the jetty module parameter `--module=new-ui`.
When using the Solr CLI, users can disable the new UI with
`SOLR_ADMIN_UI_EXPERIMENTAL_DISABLED=true` or by disabling the entire UI with
`SOLR_ADMIN_UI_DISABLED=true`.

==== JVM

The JVM target packages the UI into a standalone desktop application. This allows the execution
on all JVM-supported platforms, including Windows, Linux and MacOS.

=== Artifacts

The wasmJs artifacts are shipped with new Solr releases starting at v10. Therefore, wasmJs
artifacts have relatively longer release cycles compared to the JVM artifacts.

The JVM artifacts are shipped independently of Solr releases to allow more frequent
releases during the experimental phase. They are generated and published on GitHub.