Housekeeping

README.md

@@ -4,77 +4,67 @@
 
 <img alt="Jewel logo" src="art/jewel-logo.svg" width="20%"/>
 
-Jewel aims at recreating the _Darcula_ and _New UI_ Swing Look and Feels used on the IntelliJ Platform into Compose for
-Desktop.
+Jewel aims at recreating the IntelliJ Platform's _New UI_ Swing Look and Feel in Compose for Desktop, providing a
+desktop-optimized theme and set of components.
 
-> **Warning**
+> [!WARNING]
+>
 > This project is in very early development and is probably not ready to be used in production projects. You _can_, but
-> there
-> are no published snapshots, and you should expect APIs to break fairly often, things to move around, and all that
-> jazz.
+> you should expect APIs to change fairly often, things to move around and/or break, and all that jazz.
+>
 > Use at your risk!
 
+Jewel provides stand-alone implementations of the IntelliJ Platform themes that can be used in any Compose for Desktop
+application, and a Swing LaF Bridge that only works in the IntelliJ Platform (i.e., used to create IDE plugins), but
+automatically mirrors the current Swing LaF into Compose for a native-looking, consistent UI.
+
 ## Project structure
 
 The project is split in modules:
 
-1. `core` is the base Jewel library code (composables, interface definitions, etc.)
-2. `compose-utils` is a collection of utilities for dealing with Compose, and Swing interop
-3. `themes` are the two themes implemented by Jewel:
-    1. `darcula` is the old school Intellij LaF, called Darcula, which has two implementations:
-        1. `darcula-standalone` is the base theme and can be used in any Compose for Desktop project
-        2. `darcula-ide` is a version of the theme that can be used in an IDEA plugin, and integrates with the IDE's
-           Swing LaF and themes via a
-           bridge (more
-           on that later)
-    2. `new-ui` implements the new IntelliJ LaF, known as "new UI". This also has the same two implementations
-4. `samples` contains the example apps, which showcase the available components:
+1. `buildSrc` contains the build logic, including:
+    * The `jewel` and `jewel-publish` configuration plugins
+    * The Theme Palette generator plugin
+2. `core` contains the foundational Jewel functionality, including the components and their styling primitives
+3. `int-ui` implements the standalone version of the IntelliJ New UI, which implements the
+   ["Int UI" design system](https://www.figma.com/community/file/1227732692272811382/int-ui-kit), and can be used
+   anywhere
+4. `ide-laf-bridge` contains the Swing LaF bridge to use in IntelliJ Platform plugins (see more below)
+5. `samples` contains the example apps, which showcase the available components:
     1. `standalone` is a regular CfD app, using the predefined "base" theme definitions
-    2. `ide-plugin` is an IntelliJ plugin, adding some UI to the IDE, and showcasing the use of the bridge (see later)
-
-### Running the samples
+    2. `ide-plugin` is an IntelliJ plugin, adding some UI to the IDE, and showcasing the use of the Swing Bridge
 
-To run the stand-alone sample app, you can run the `:samples:standalone:run` Gradle task.
+### Int UI Standalone theme
 
-To run the IntelliJ IDEA plugin sample, you can run the `:samples:ide-plugin:runIde` Gradle task. This will download and
-run a copy of IJ Community
-with the plugin installed; you can check the additional panels in the IDE once it starts up (at the bottom, by default,
-in old UI; in the overflow
-in the new UI).
+The standalone theme can be used in any Compose for Desktop app. You use it as a normal theme, and you can customise it
+to your heart's content. By default, it matches the official Int UI specs.
 
-If you're using IntelliJ IDEA, you can use the "Stand-alone sample" and "IDE sample" run configurations.
+> [!WARNING]
+> Note that Jewel **requires** the JetBrains Runtime to work correctly. Some features like font loading depend on it,
+> as it has extra features and patches for UI functionalities that aren't available in other JDKs.
+> We **do not support** running Jewel on any other JDK.
 
 ### The Swing Bridge
 
-In the `*-ide` modules, there is a crucial element for proper integration with the IDE: a bridge between the Swing theme
-and LaF, and the Compose
-world.
+Jewel includes a crucial element for proper integration with the IDE: a bridge between the Swing components, theme
+and LaF, and the Compose world.
+
 This bridge ensures that we pick up the colours, typography, metrics, and images as defined in the current IntelliJ
-theme, and apply them to the
-Compose theme as well.
-
-The work of building this bridge is fairly complex as there isn't a good mapping between the IDE LaF properties, the
-Darcula design specs, and the
-Compose implementations. Sometimes, you will need to get a bit creative.
-
-When adding a new composable to the IJ theme, you need to make sure you also update the bridge to properly support it at
-runtime. You can refer to the
-[Darcula design specs](https://jetbrains.design/intellij) and
-corresponding [Figma specs](https://jetbrains.design/intellij/resources/UI_kit/), but
-the ultimate goal is consistency with the Swing implementation, so the ground truth of what you see in the IDE is the
-reference for any implementation
-and trumps the specs.
-
-To find the required values in the IDE, we recommend enabling
-the [IDE internal mode](https://plugins.jetbrains.com/docs/intellij/enabling-internal.html)
-and using the [UI Inspector](https://plugins.jetbrains.com/docs/intellij/internal-ui-inspector.html) and
-[LaF Defaults](https://plugins.jetbrains.com/docs/intellij/internal-ui-laf-defaults.html) tools to figure out the names
-of the parameters to use in
-the bridge.
-
-To see debug logs in the IDE, add these to __Help | Diagnostic Tools | Debug Log Settings__:
+theme, and apply them to the Compose components as well — at least for themes that use the
+standard [IntelliJ theming](https://plugins.jetbrains.com/docs/intellij/themes-getting-started.html) mechanisms.
 
-```
-#org.jetbrains.jewel.demo
-#org.jetbrains.jewel
+> [!NOTE]
+> IntelliJ themes that use non-standard mechanisms (such as providing custom UI implementations for Swing components)
+> are not, and will never, be supported.
+
+If you're writing an IntelliJ Platform plugin, you should use the `SwingBridgeTheme` instead of a standalone theme.
+
+#### Accessing icons
+
+When you want to draw an icon from the resources, you should use a `PainterProvider`. Reading an icon from the IDE is
+as easy as using the `retrieveStatefulIcon()` and `retrieveStatelessIcon()`:
+
+```kotlin
+val svgLoader = service<SwingBridgeService>().svgLoader
+val painterProvider = retrieveStatelessIcon("icons/bot-toolwindow.svg", svgLoader, iconData)
 ```

build.gradle.kts

@@ -11,10 +11,9 @@ val sarif: Configuration by configurations.creating {
 
 dependencies {
     sarif(projects.core)
-    sarif(projects.composeUtils)
     sarif(projects.samples.standalone)
-    sarif(projects.themes.intUi.intUiStandalone)
-    sarif(projects.themes.intUi.intUiCore)
+    sarif(projects.intUi.intUiStandalone)
+    sarif(projects.intUi.intUiCore)
 }
 
 tasks {

buildSrc/src/main/kotlin/jewel-publish.gradle.kts

@@ -1,9 +1,9 @@
 @file:Suppress("UnstableApiUsage")
 
 plugins {
+    kotlin("jvm")
     `maven-publish`
     id("org.jetbrains.dokka")
-    id("jewel")
 }
 
 val sourcesJar by tasks.registering(Jar::class) {

core/build.gradle.kts

@@ -1,10 +1,10 @@
 plugins {
+    jewel
     `jewel-publish`
     alias(libs.plugins.composeDesktop)
     alias(libs.plugins.kotlinSerialization)
 }
 
 dependencies {
-    api(projects.composeUtils)
-    api(compose.desktop.common)
+    api(compose.desktop.currentOs)
 }

core/src/main/kotlin/org/jetbrains/jewel/util/ModifierExtensions.kt

@@ -0,0 +1,6 @@
+package org.jetbrains.jewel.util
+
+import androidx.compose.ui.Modifier
+
+inline fun Modifier.appendIf(precondition: Boolean, action: Modifier.() -> Modifier) =
+    if (precondition) action() else this

ide-laf-bridge/build.gradle.kts

@@ -1,11 +1,11 @@
 plugins {
-    alias(libs.plugins.composeDesktop)
     jewel
     `jewel-publish`
+    alias(libs.plugins.composeDesktop)
 }
 
 dependencies {
-    api(projects.themes.intUi.intUiStandalone)
+    api(projects.intUi.intUiStandalone)
     compileOnly(libs.bundles.idea)
 
     testImplementation(compose.desktop.uiTestJUnit4)

themes/int-ui/int-ui-core/build.gradle.kts → int-ui/int-ui-core/build.gradle.kts

@@ -1,14 +1,14 @@
 @file:Suppress("UnstableApiUsage")
 
 plugins {
+    jewel
     `jewel-publish`
     alias(libs.plugins.composeDesktop)
     `intellij-theme-generator`
 }
 
 dependencies {
     api(projects.core)
-    api(projects.composeUtils)
 }
 
 intelliJThemeGenerator {
@@ -35,4 +35,3 @@ tasks {
         duplicatesStrategy = DuplicatesStrategy.EXCLUDE
     }
 }
-

themes/int-ui/int-ui-standalone/build.gradle.kts → int-ui/int-ui-standalone/build.gradle.kts

@@ -1,8 +1,9 @@
 plugins {
+    jewel
     `jewel-publish`
     alias(libs.plugins.composeDesktop)
 }
 
 dependencies {
-    api(projects.themes.intUi.intUiCore)
+    api(projects.intUi.intUiCore)
 }

samples/ide-plugin/build.gradle.kts

@@ -21,7 +21,5 @@ repositories {
 }
 
 dependencies {
-    implementation(compose.desktop.currentOs)
-    implementation(projects.themes.intUi.intUiStandalone)
     implementation(projects.ideLafBridge)
 }

samples/standalone/build.gradle.kts

@@ -8,7 +8,7 @@ plugins {
 }
 
 dependencies {
-    implementation(projects.themes.intUi.intUiStandalone)
+    implementation(projects.intUi.intUiStandalone)
 }
 
 compose.desktop {