diff --git a/platform/jewel/ui/src/main/kotlin/org/jetbrains/jewel/ui/component/Banner.kt b/platform/jewel/ui/src/main/kotlin/org/jetbrains/jewel/ui/component/Banner.kt index 7ae154d77d38..48263fc5b50a 100644 --- a/platform/jewel/ui/src/main/kotlin/org/jetbrains/jewel/ui/component/Banner.kt +++ b/platform/jewel/ui/src/main/kotlin/org/jetbrains/jewel/ui/component/Banner.kt @@ -23,6 +23,44 @@ import org.jetbrains.jewel.ui.component.styling.DefaultBannerStyle import org.jetbrains.jewel.ui.icons.AllIconsKeys import org.jetbrains.jewel.ui.theme.defaultBannerStyle +/** + * Displays an informational editor banner providing a context-aware message to the user, styled with the default + * "information" theme. + * + * The banner includes an optional icon, customizable actions, and a text message. Its primary purpose is to provide + * non-intrusive, informative feedback in the editor area. + * + * @param text the main text content of the banner, succinctly describing the message or context. + * @param modifier a [Modifier] for customizing the layout and appearance of the banner. + * @param icon a composable representing an optional icon displayed on the left side of the banner, by default it shows + * the general "information" icon, in a 16x16 dp [Box]. Pass `null` to hide the icon. + * @param actions an optional row of clickable components (e.g., links or buttons) placed at the end of the banner. + * Useful for actions such as "learn more," "retry," or "dismiss." + * @param style defines the visual styling of the banner, adapting to the default "information" theme of the IJ UI. You + * can override it if needed by providing a custom [DefaultBannerStyle]. + * @param textStyle the styling applied to the banner's text content, using the default text style from the Jewel theme. + * This can be customized for specific typography needs. + * + * This banner is primarily used to display persistent messages without interrupting the workflow. + * + * **Guidelines:** [on IJP SDK webhelp](https://plugins.jetbrains.com/docs/intellij/banner.html) + * + * **Swing equivalent:** + * [`EditorNotificationProvider `](https://github.com/JetBrains/intellij-community/blob/master/platform/platform-api/src/com/intellij/ui/EditorNotificationProvider.java) + * + * **Usage example:** + * [`Banners.kt`](https://github.com/JetBrains/intellij-community/blob/master/platform/jewel/samples/showcase/src/main/kotlin/org/jetbrains/jewel/samples/showcase/components/Banners.kt) + * + * Example usage: + * ``` + * InformationDefaultBanner( + * text = "The file has been indexed successfully.", + * actions = { + * Link("Dismiss", onClick = { /* Handle dismiss action */ }) + * } + * ) + * ``` + */ @Composable public fun InformationDefaultBanner( text: String, @@ -42,6 +80,42 @@ public fun InformationDefaultBanner( ) } +/** + * Displays a success editor banner signaling a successful action, state, or process completion. + * + * The banner includes an optional icon, customizable actions, and a text message styled with the default "success" + * theme. + * + * @param text the main text content of the banner, briefly describing the successful state or process. + * @param modifier a [Modifier] for customizing the layout and appearance of the banner. + * @param icon a composable representing an optional icon displayed on the left of the banner, by default it shows the + * "success" icon, in a 16x16 dp [Box]. Pass `null` to hide the icon. + * @param actions an optional row of clickable components that can act as additional user actions, such as "view + * details" or "close." + * @param style defines the banner's appearance following the "success" theme of the Jewel UI, but can be overridden + * with custom styling. + * @param textStyle determines the typography of the banner's text, defaulting to the application's text style. + * + * Use this banner to provide clear, visual feedback of a completed or successful action. + * + * **Guidelines:** [on IJP SDK webhelp](https://plugins.jetbrains.com/docs/intellij/banner.html) + * + * **Swing equivalent:** + * [`EditorNotificationProvider `](https://github.com/JetBrains/intellij-community/blob/master/platform/platform-api/src/com/intellij/ui/EditorNotificationProvider.java) + * + * **Usage example:** + * [`Banners.kt`](https://github.com/JetBrains/intellij-community/blob/master/platform/jewel/samples/showcase/src/main/kotlin/org/jetbrains/jewel/samples/showcase/components/Banners.kt) + * + * Example usage: + * ``` + * SuccessDefaultBanner( + * text = "Backup completed successfully.", + * actions = { + * Link("View Logs", onClick = { /* Show logs */ }) + * } + * ) + * ``` + */ @Composable public fun SuccessDefaultBanner( text: String, @@ -61,6 +135,41 @@ public fun SuccessDefaultBanner( ) } +/** + * Displays a warning editor banner highlighting potential issues or a need for user attention. + * + * This banner visually distinguishes itself using the default "warning" theme, including optional icons and user + * actions. + * + * @param text the main text content of the banner, detailing the warning message or potential problem. + * @param modifier a [Modifier] for customizing the layout and appearance of the banner. + * @param icon a composable representing an icon displayed on the left of the banner, by default it shows a "warning" + * icon. Pass `null` to omit the icon. + * @param actions an optional row of clickable components allowing the user to resolve the warning or access more + * details. + * @param style defines the banner's appearance under the "warning" theme, or a custom [DefaultBannerStyle]. + * @param textStyle controls the typography of the warning message's text, based on the Jewel theme. + * + * Use this banner to make users aware of potential issues without stopping their flow. + * + * **Guidelines:** [on IJP SDK webhelp](https://plugins.jetbrains.com/docs/intellij/banner.html) + * + * **Swing equivalent:** + * [`EditorNotificationProvider `](https://github.com/JetBrains/intellij-community/blob/master/platform/platform-api/src/com/intellij/ui/EditorNotificationProvider.java) + * + * **Usage example:** + * [`Banners.kt`](https://github.com/JetBrains/intellij-community/blob/master/platform/jewel/samples/showcase/src/main/kotlin/org/jetbrains/jewel/samples/showcase/components/Banners.kt) + * + * Example usage: + * ``` + * WarningDefaultBanner( + * text = "Your license is expiring soon. Please renew to avoid service interruptions.", + * actions = { + * Link("Renew Now", onClick = { /* Trigger renewal flow */ }) + * } + * ) + * ``` + */ @Composable public fun WarningDefaultBanner( text: String, @@ -80,6 +189,40 @@ public fun WarningDefaultBanner( ) } +/** + * Displays an error editor banner indicating critical issues or failures that require user awareness. + * + * This banner draws attention using the default "error" theme and can optionally include user actions or icons. + * + * @param text the main text content of the banner, focusing on the error context or failure details. + * @param modifier a [Modifier] for customizing the layout and appearance of the banner. + * @param icon a composable representing an error icon to display on the left of the banner, by default it shows the + * "error" icon. Pass `null` to omit the icon. + * @param actions an optional row of interactive components for responding to the error, such as retrying or navigating + * to relevant settings. + * @param style the default "error" theme styling for the banner, or a custom one via [DefaultBannerStyle]. + * @param textStyle typography settings for the text content, defaulting to Jewel's text style. + * + * Use this banner to provide high-visibility error messages requiring immediate user attention. + * + * **Guidelines:** [on IJP SDK webhelp](https://plugins.jetbrains.com/docs/intellij/banner.html) + * + * **Swing equivalent:** + * [`EditorNotificationProvider `](https://github.com/JetBrains/intellij-community/blob/master/platform/platform-api/src/com/intellij/ui/EditorNotificationProvider.java) + * + * **Usage example:** + * [`Banners.kt`](https://github.com/JetBrains/intellij-community/blob/master/platform/jewel/samples/showcase/src/main/kotlin/org/jetbrains/jewel/samples/showcase/components/Banners.kt) + * + * Example usage: + * ``` + * ErrorDefaultBanner( + * text = "Failed to sync project files with the server.", + * actions = { + * Link("Retry", onClick = { /* Retry the action */ }) + * } + * ) + * ``` + */ @Composable public fun ErrorDefaultBanner( text: String, diff --git a/platform/jewel/ui/src/main/kotlin/org/jetbrains/jewel/ui/component/Checkbox.kt b/platform/jewel/ui/src/main/kotlin/org/jetbrains/jewel/ui/component/Checkbox.kt index 07158ba3c5eb..d8f2dc84f5cb 100644 --- a/platform/jewel/ui/src/main/kotlin/org/jetbrains/jewel/ui/component/Checkbox.kt +++ b/platform/jewel/ui/src/main/kotlin/org/jetbrains/jewel/ui/component/Checkbox.kt @@ -55,6 +55,33 @@ import org.jetbrains.jewel.ui.painter.hints.Stateful import org.jetbrains.jewel.ui.painter.rememberResourcePainterProvider import org.jetbrains.jewel.ui.theme.checkboxStyle +/** + * A checkbox component that follows the standard visual styling with customizable appearance and behavior. + * + * Provides a selectable component that can be either checked or unchecked. The checkbox supports various states + * including enabled/disabled, focused, and hovered, adapting its appearance accordingly. + * + * **Guidelines:** [on IJP SDK webhelp](https://plugins.jetbrains.com/docs/intellij/checkbox.html) + * + * **Usage example:** + * [`Checkboxes.kt`](https://github.com/JetBrains/intellij-community/blob/master/platform/jewel/samples/showcase/src/main/kotlin/org/jetbrains/jewel/samples/showcase/components/Checkboxes.kt) + * + * **Swing equivalent:** [`JCheckBox`](https://docs.oracle.com/javase/tutorial/uiswing/components/button.html#checkbox) + * + * @param checked The current state of the checkbox + * @param onCheckedChange Called when the checkbox is clicked, with the new checked state + * @param modifier Modifier to be applied to the checkbox + * @param enabled Controls the enabled state of the checkbox. When false, the checkbox cannot be checked/unchecked + * @param outline The outline style to be applied to the checkbox + * @param interactionSource Source of interactions for this checkbox + * @param colors The color styling configuration for the checkbox + * @param metrics The sizing and spacing configuration for the checkbox + * @param icons The icon configuration for the checkbox + * @param textStyle The typography style to be applied to the checkbox's text content + * @param verticalAlignment The vertical alignment of the checkbox relative to its text content + * @see javax.swing.JCheckBox + * @see com.intellij.ui.components.JBCheckBox + */ @Composable public fun Checkbox( checked: Boolean, @@ -87,6 +114,34 @@ public fun Checkbox( ) } +/** + * A three-state checkbox component that follows the standard visual styling with customizable appearance. + * + * Provides a selectable component that can be in one of three states: checked, unchecked, or indeterminate. This + * variant is particularly useful for representing partially selected states in hierarchical selections. + * + * **Guidelines:** [on IJP SDK webhelp](https://plugins.jetbrains.com/docs/intellij/checkbox.html#three-state-checkbox) + * + * **Usage example:** + * [`Checkboxes.kt`](https://github.com/JetBrains/intellij-community/blob/master/platform/jewel/samples/showcase/src/main/kotlin/org/jetbrains/jewel/samples/showcase/components/Checkboxes.kt) + * + * **Swing equivalent:** [`JCheckBox`](https://docs.oracle.com/javase/tutorial/uiswing/components/button.html#checkbox) + * with + * [setIndeterminate](https://docs.oracle.com/javase/8/docs/api/javax/swing/JCheckBox.html#setIndeterminate-boolean-) + * + * @param state The current state of the checkbox (On, Off, or Indeterminate) + * @param onClick Called when the checkbox is clicked + * @param modifier Modifier to be applied to the checkbox + * @param enabled Controls the enabled state of the checkbox. When false, the checkbox cannot be interacted with + * @param outline The outline style to be applied to the checkbox + * @param interactionSource Source of interactions for this checkbox + * @param colors The color styling configuration for the checkbox + * @param metrics The sizing and spacing configuration for the checkbox + * @param icons The icon configuration for the checkbox + * @param textStyle The typography style to be applied to the checkbox's text content + * @param verticalAlignment The vertical alignment of the checkbox relative to its text content + * @see javax.swing.JCheckBox + */ @Composable public fun TriStateCheckbox( state: ToggleableState, @@ -118,6 +173,37 @@ public fun TriStateCheckbox( ) } +/** + * A three-state checkbox with accompanying text, following the standard visual styling. + * + * Provides a horizontal layout combining a three-state checkbox with text content. The entire row is clickable, making + * it easier for users to interact with the checkbox. This variant is particularly useful for representing partially + * selected states in hierarchical selections with labels. + * + * **Guidelines:** [on IJP SDK webhelp](https://plugins.jetbrains.com/docs/intellij/checkbox.html#three-state-checkbox) + * + * **Usage example:** + * [`Checkboxes.kt`](https://github.com/JetBrains/intellij-community/blob/master/platform/jewel/samples/showcase/src/main/kotlin/org/jetbrains/jewel/samples/showcase/components/Checkboxes.kt) + * + * **Swing equivalent:** [`JCheckBox`](https://docs.oracle.com/javase/tutorial/uiswing/components/button.html#checkbox) + * with text constructor and + * [setIndeterminate](https://docs.oracle.com/javase/8/docs/api/javax/swing/JCheckBox.html#setIndeterminate-boolean-) + * + * @param text The text to be displayed next to the checkbox + * @param state The current state of the checkbox (On, Off, or Indeterminate) + * @param onClick Called when the checkbox or row is clicked + * @param modifier Modifier to be applied to the entire row + * @param textModifier Modifier to be applied to the text content + * @param enabled Controls the enabled state of the checkbox. When false, the row cannot be interacted with + * @param outline The outline style to be applied to the checkbox + * @param interactionSource Source of interactions for this checkbox + * @param colors The color styling configuration for the checkbox + * @param metrics The sizing and spacing configuration for the checkbox + * @param icons The icon configuration for the checkbox + * @param textStyle The typography style to be applied to the text content + * @param verticalAlignment The vertical alignment of the checkbox relative to its text content + * @see javax.swing.JCheckBox + */ @Composable public fun TriStateCheckboxRow( text: String, @@ -152,6 +238,35 @@ public fun TriStateCheckboxRow( } } +/** + * A checkbox with accompanying text, following the standard visual styling with customizable appearance. + * + * Provides a horizontal layout combining a checkbox with text content. The entire row is clickable, making it easier + * for users to interact with the checkbox. This component is commonly used in forms, settings panels, and option lists. + * + * **Guidelines:** [on IJP SDK webhelp](https://plugins.jetbrains.com/docs/intellij/checkbox.html) + * + * **Usage example:** + * [`Checkboxes.kt`](https://github.com/JetBrains/intellij-community/blob/master/platform/jewel/samples/showcase/src/main/kotlin/org/jetbrains/jewel/samples/showcase/components/Checkboxes.kt) + * + * **Swing equivalent:** [`JCheckBox`](https://docs.oracle.com/javase/tutorial/uiswing/components/button.html#checkbox) + * with text constructor + * + * @param text The text to be displayed next to the checkbox + * @param checked The current state of the checkbox + * @param onCheckedChange Called when the checkbox or row is clicked, with the new checked state + * @param modifier Modifier to be applied to the entire row + * @param textModifier Modifier to be applied to the text content + * @param enabled Controls the enabled state of the checkbox. When false, the row cannot be interacted with + * @param outline The outline style to be applied to the checkbox + * @param interactionSource Source of interactions for this checkbox + * @param colors The color styling configuration for the checkbox + * @param metrics The sizing and spacing configuration for the checkbox + * @param icons The icon configuration for the checkbox + * @param textStyle The typography style to be applied to the text content + * @param verticalAlignment The vertical alignment of the checkbox relative to its text content + * @see javax.swing.JCheckBox + */ @Composable public fun CheckboxRow( text: String, @@ -188,6 +303,34 @@ public fun CheckboxRow( } } +/** + * A checkbox with accompanying content, following the standard visual styling with customizable appearance. + * + * Provides a horizontal layout combining a checkbox with custom content. The entire row is clickable, making it easier + * for users to interact with the checkbox. This component is commonly used in forms, settings panels, and option lists + * where custom content layout is needed. + * + * **Guidelines:** [on IJP SDK webhelp](https://plugins.jetbrains.com/docs/intellij/checkbox.html) + * + * **Usage example:** + * [`Checkboxes.kt`](https://github.com/JetBrains/intellij-community/blob/master/platform/jewel/samples/showcase/src/main/kotlin/org/jetbrains/jewel/samples/showcase/components/Checkboxes.kt) + * + * **Swing equivalent:** [`JCheckBox`](https://docs.oracle.com/javase/tutorial/uiswing/components/button.html#checkbox) + * + * @param checked The current state of the checkbox + * @param onCheckedChange Called when the checkbox or row is clicked, with the new checked state + * @param modifier Modifier to be applied to the entire row + * @param enabled Controls the enabled state of the checkbox. When false, the row cannot be interacted with + * @param outline The outline style to be applied to the checkbox + * @param interactionSource Source of interactions for this checkbox + * @param colors The color styling configuration for the checkbox + * @param metrics The sizing and spacing configuration for the checkbox + * @param icons The icon configuration for the checkbox + * @param textStyle The typography style to be applied to the content + * @param verticalAlignment The vertical alignment of the checkbox relative to its content + * @param content Composable content to be displayed next to the checkbox + * @see javax.swing.JCheckBox + */ @Composable public fun CheckboxRow( checked: Boolean, @@ -220,6 +363,36 @@ public fun CheckboxRow( ) } +/** + * A three-state checkbox with accompanying content, following the standard visual styling. + * + * Provides a horizontal layout combining a three-state checkbox with custom content. The entire row is clickable, + * making it easier for users to interact with the checkbox. This variant is particularly useful for representing + * partially selected states in hierarchical selections with custom content. + * + * **Guidelines:** [on IJP SDK webhelp](https://plugins.jetbrains.com/docs/intellij/checkbox.html#three-state-checkbox) + * + * **Usage example:** + * [`Checkboxes.kt`](https://github.com/JetBrains/intellij-community/blob/master/platform/jewel/samples/showcase/src/main/kotlin/org/jetbrains/jewel/samples/showcase/components/Checkboxes.kt) + * + * **Swing equivalent:** [`JCheckBox`](https://docs.oracle.com/javase/tutorial/uiswing/components/button.html#checkbox) + * with + * [setIndeterminate](https://docs.oracle.com/javase/8/docs/api/javax/swing/JCheckBox.html#setIndeterminate-boolean-) + * + * @param state The current state of the checkbox (On, Off, or Indeterminate) + * @param onClick Called when the checkbox or row is clicked + * @param modifier Modifier to be applied to the entire row + * @param enabled Controls the enabled state of the checkbox. When false, the row cannot be interacted with + * @param outline The outline style to be applied to the checkbox + * @param interactionSource Source of interactions for this checkbox + * @param colors The color styling configuration for the checkbox + * @param metrics The sizing and spacing configuration for the checkbox + * @param icons The icon configuration for the checkbox + * @param textStyle The typography style to be applied to the content + * @param verticalAlignment The vertical alignment of the checkbox relative to its content + * @param content Composable content to be displayed next to the checkbox + * @see javax.swing.JCheckBox + */ @Composable public fun TriStateCheckboxRow( state: ToggleableState, diff --git a/platform/jewel/ui/src/main/kotlin/org/jetbrains/jewel/ui/component/InlineBanner.kt b/platform/jewel/ui/src/main/kotlin/org/jetbrains/jewel/ui/component/InlineBanner.kt index e5f2e7ae3caa..61e204bfe420 100644 --- a/platform/jewel/ui/src/main/kotlin/org/jetbrains/jewel/ui/component/InlineBanner.kt +++ b/platform/jewel/ui/src/main/kotlin/org/jetbrains/jewel/ui/component/InlineBanner.kt @@ -39,6 +39,44 @@ import org.jetbrains.jewel.ui.component.styling.InlineBannerStyle import org.jetbrains.jewel.ui.icons.AllIconsKeys import org.jetbrains.jewel.ui.theme.inlineBannerStyle +/** + * Displays an informational inline banner providing subtle, non-intrusive context or feedback within a particular UI + * section. + * + * The banner uses the inline "information" theme by default, featuring an optional icon, a context message, and + * optional actions. + * + * @param text the primary content of the banner, briefly describing the information it conveys. + * @param modifier a [Modifier] to customize the layout and appearance of the banner. + * @param icon a composable representation of an optional 16x16 dp "information" icon displayed to the left of the + * banner. Pass `null` to hide the icon. By default, it shows the "information" icon. + * @param actions a lambda defining optional interactive components (e.g., links, buttons) placed inside the banner for + * inline actions like "View More" or "Dismiss." + * @param actionIcons a lambda defining composable icons representing secondary or quick actions, such as closing the + * banner. Icons are placed on the right side of the banner. + * @param style a [InlineBannerStyle] that determines the visual styling of the banner, using the default “information” + * theme. This can be overridden for customization. + * @param textStyle typography settings applied to the banner text, based on the default Jewel theme. + * + * Use this banner to provide relevant, non-critical information in a compact layout. + * + * **Guidelines:** [on IntelliJ Platform SDK webhelp](https://plugins.jetbrains.com/docs/intellij/balloon.html) + * + * **Swing equivalent:** + * [`Notifications`](https://github.com/JetBrains/intellij-community/blob/idea/243.23654.153/platform/ide-core/src/com/intellij/notification/Notifications.java) + * + * **Usage example:** + * [`Banners.kt`](https://github.com/JetBrains/intellij-community/blob/master/platform/jewel/samples/showcase/src/main/kotlin/org/jetbrains/jewel/samples/showcase/components/Banners.kt) + * + * ```kotlin + * InformationInlineBanner( + * text = "Project indexed successfully.", + * actions = { + * Link("View Logs", onClick = { /* handle click */ }) + * } + * ) + * ``` + */ @Composable public fun InformationInlineBanner( text: String, @@ -60,6 +98,44 @@ public fun InformationInlineBanner( ) } +/** + * Displays an inline banner to confirm successful actions or state completions in compact UI sections without + * interrupting the workflow. + * + * The banner uses the inline "success" theme by default, featuring an optional icon, a success message, and optional + * user actions. + * + * @param text the main content of the banner, succinctly describing the successful operation or state. + * @param modifier a [Modifier] to customize the layout, padding, or size of the banner. + * @param icon a composable for an optional 16x16 dp "success" icon displayed on the left side of the banner. The + * success icon is shown by default. Pass `null` to hide the icon. + * @param actions a lambda defining optional interactive components, such as links or buttons, placed within the banner + * for additional user operations. + * @param actionIcons a lambda defining composable icons for quick or secondary operations, such as dismissing the + * banner, placed on the banner's right side. + * @param style a [InlineBannerStyle] defining the visual appearance of the banner. It uses the default "success" theme, + * but this can be customized if needed. + * @param textStyle the style of the banner text, controlled by the Jewel theme's typography. + * + * Use this banner to provide visual feedback for completed actions. + * + * **Guidelines:** [on IntelliJ Platform SDK webhelp](https://plugins.jetbrains.com/docs/intellij/balloon.html) + * + * **Swing equivalent:** + * [`Notifications`](https://github.com/JetBrains/intellij-community/blob/idea/243.23654.153/platform/ide-core/src/com/intellij/notification/Notifications.java) + * + * **Usage example:** + * [`Banners.kt`](https://github.com/JetBrains/intellij-community/blob/master/platform/jewel/samples/showcase/src/main/kotlin/org/jetbrains/jewel/samples/showcase/components/Banners.kt) + * + * ```kotlin + * SuccessInlineBanner( + * text = "Build completed successfully.", + * actions = { + * Link("Details", onClick = { /* handle link */ }) + * } + * ) + * ``` + */ @Composable public fun SuccessInlineBanner( text: String, @@ -81,6 +157,43 @@ public fun SuccessInlineBanner( ) } +/** + * Shows a warning inline banner to draw attention to non-critical issues that require user awareness or resolution. + * + * The banner applies the inline "warning" theme by default, including an optional icon, a warning message, and + * additional actions if provided. + * + * @param text the main content of the banner, describing the warning or potential issue. + * @param modifier a [Modifier] for applying layout modifications to the banner, such as padding or size changes. + * @param icon a composable element for an optional 16x16 dp "warning" icon displayed at the banner's left edge. The + * warning icon is shown by default. Set `null` to omit the icon. + * @param actions a lambda defining interactive elements such as links or buttons, which provide additional user + * operations related to the warning. + * @param actionIcons a lambda defining composable icons for secondary operations, like dismissing the banner, placed on + * the right side of the banner. + * @param style an [InlineBannerStyle] defining the warning theme of the banner. The default warning theme is applied by + * default, but this can be customized. + * @param textStyle typography used for the text content of the banner, inheriting from the Jewel theme. + * + * Use this banner for unobstructive warnings requiring user awareness. + * + * **Guidelines:** [on IntelliJ Platform SDK webhelp](https://plugins.jetbrains.com/docs/intellij/balloon.html) + * + * **Swing equivalent:** + * [`Notifications`](https://github.com/JetBrains/intellij-community/blob/idea/243.23654.153/platform/ide-core/src/com/intellij/notification/Notifications.java) + * + * **Usage example:** + * [`Banners.kt`](https://github.com/JetBrains/intellij-community/blob/master/platform/jewel/samples/showcase/src/main/kotlin/org/jetbrains/jewel/samples/showcase/components/Banners.kt) + * + * ```kotlin + * WarningInlineBanner( + * text = "This feature is deprecated and will be removed in the next version.", + * actions = { + * Link("Learn More", onClick = { /* handle action */ }) + * } + * ) + * ``` + */ @Composable public fun WarningInlineBanner( text: String, @@ -102,6 +215,42 @@ public fun WarningInlineBanner( ) } +/** + * Displays an inline banner highlighting critical errors or failures that require immediate user attention and action. + * + * This banner uses the inline "error" theme by default, featuring a message describing the error, and optional icons + * and actions to assist the user in resolving it. + * + * @param text the main content of the banner, describing the error context or failure details. + * @param modifier a [Modifier] for layout customization (e.g., padding, width). + * @param icon a composable that displays an optional 16x16 dp "error" icon at the banner's left side. The error icon is + * displayed by default and can be omitted by passing `null`. + * @param actions a lambda providing interactive options (e.g., retry, open settings) as part of the banner. + * @param actionIcons a lambda defining composable icons for secondary operations, such as closing or dismissing the + * banner, rendered on the banner's right side. + * @param style an [InlineBannerStyle] defining the banner's appearance under the error theme. It can be customized to + * override the default error styling. + * @param textStyle typography settings for the text content, based on the default Jewel theme. + * + * Use this banner to convey high-priority errors affecting application behavior. + * + * **Guidelines:** [on IntelliJ Platform SDK webhelp](https://plugins.jetbrains.com/docs/intellij/balloon.html) + * + * **Swing equivalent:** + * [`Notifications`](https://github.com/JetBrains/intellij-community/blob/idea/243.23654.153/platform/ide-core/src/com/intellij/notification/Notifications.java) + * + * **Usage example:** + * [`Banners.kt`](https://github.com/JetBrains/intellij-community/blob/master/platform/jewel/samples/showcase/src/main/kotlin/org/jetbrains/jewel/samples/showcase/components/Banners.kt) + * + * ```kotlin + * ErrorInlineBanner( + * text = "Connection to the server failed.", + * actions = { + * Link("Retry", onClick = { /* handle retry */ }) + * } + * ) + * ``` + */ @Composable public fun ErrorInlineBanner( text: String, diff --git a/platform/jewel/ui/src/main/kotlin/org/jetbrains/jewel/ui/component/LinearProgressBar.kt b/platform/jewel/ui/src/main/kotlin/org/jetbrains/jewel/ui/component/LinearProgressBar.kt index c50fe00c6e8d..d2d49c024203 100644 --- a/platform/jewel/ui/src/main/kotlin/org/jetbrains/jewel/ui/component/LinearProgressBar.kt +++ b/platform/jewel/ui/src/main/kotlin/org/jetbrains/jewel/ui/component/LinearProgressBar.kt @@ -26,9 +26,24 @@ import org.jetbrains.jewel.foundation.theme.JewelTheme import org.jetbrains.jewel.ui.component.styling.HorizontalProgressBarStyle import org.jetbrains.jewel.ui.theme.horizontalProgressBarStyle -// TODO implement green/red/yellow variants based on -// com.intellij.openapi.progress.util.ColorProgressBar - +/** + * A horizontal progress bar component that follows the standard visual styling. + * + * Provides a progress indicator that fills from left to right (or right to left in RTL layouts) to show the progress of + * an operation. The progress is represented as a filled portion of the bar, with customizable colors and styling. + * + * **Guidelines:** [on IJP SDK webhelp](https://plugins.jetbrains.com/docs/intellij/progress-bar.html) + * + * **Usage example:** + * [`ProgressBar.kt`](https://github.com/JetBrains/intellij-community/blob/master/platform/jewel/samples/showcase/src/main/kotlin/org/jetbrains/jewel/samples/showcase/components/ProgressBar.kt) + * + * **Swing equivalent:** [`JProgressBar`](https://docs.oracle.com/javase/tutorial/uiswing/components/progress.html) + * + * @param progress The current progress value between 0 and 1 + * @param modifier Modifier to be applied to the progress bar + * @param style The visual styling configuration for the progress bar + * @see javax.swing.JProgressBar + */ @Composable public fun HorizontalProgressBar( progress: Float, // from 0 to 1 @@ -56,6 +71,24 @@ public fun HorizontalProgressBar( ) } +/** + * An indeterminate horizontal progress bar component that follows the standard visual styling. + * + * Provides an animated progress indicator for operations where the progress cannot be determined. Displays a moving + * highlight that animates continuously to indicate ongoing activity. + * + * **Guidelines:** [on IJP SDK webhelp](https://plugins.jetbrains.com/docs/intellij/progress-bar.html) + * + * **Usage example:** + * [`ProgressBar.kt`](https://github.com/JetBrains/intellij-community/blob/master/platform/jewel/samples/showcase/src/main/kotlin/org/jetbrains/jewel/samples/showcase/components/ProgressBar.kt) + * + * **Swing equivalent:** [`JProgressBar`](https://docs.oracle.com/javase/tutorial/uiswing/components/progress.html) with + * [setIndeterminate(true)](https://docs.oracle.com/javase/8/docs/api/javax/swing/JProgressBar.html#setIndeterminate-boolean-) + * + * @param modifier Modifier to be applied to the progress bar + * @param style The visual styling configuration for the progress bar + * @see javax.swing.JProgressBar + */ @Composable public fun IndeterminateHorizontalProgressBar( modifier: Modifier = Modifier, diff --git a/platform/jewel/ui/src/main/kotlin/org/jetbrains/jewel/ui/component/Link.kt b/platform/jewel/ui/src/main/kotlin/org/jetbrains/jewel/ui/component/Link.kt index f1e637a585df..17b2a982e6f2 100644 --- a/platform/jewel/ui/src/main/kotlin/org/jetbrains/jewel/ui/component/Link.kt +++ b/platform/jewel/ui/src/main/kotlin/org/jetbrains/jewel/ui/component/Link.kt @@ -52,6 +52,31 @@ import org.jetbrains.jewel.ui.focusOutline import org.jetbrains.jewel.ui.icon.IconKey import org.jetbrains.jewel.ui.painter.hints.Stateful +/** + * A clickable text link that follows the standard visual styling with customizable appearance. + * + * Provides a text link that can be clicked to trigger an action. The link supports various states including + * enabled/disabled, focused, and hovered, with optional underline behavior based on the style configuration. + * + * **Guidelines:** [on IJP SDK webhelp](https://plugins.jetbrains.com/docs/intellij/link.html#link.md) + * + * **Usage example:** + * [`Links.kt`](https://github.com/JetBrains/intellij-community/blob/master/platform/jewel/samples/standalone/src/main/kotlin/org/jetbrains/jewel/samples/standalone/view/component/Links.kt) + * + * **Swing equivalent:** [`JLabel`](https://docs.oracle.com/javase/tutorial/uiswing/components/label.html) with HTML + * link styling. ALso see + * [`ActionLink`](https://github.com/JetBrains/intellij-community/blob/master/platform/platform-api/src/com/intellij/ui/components/ActionLink.kt) + * + * @param text The text to be displayed as a link + * @param onClick Called when the link is clicked + * @param modifier Modifier to be applied to the link + * @param enabled Controls whether the link can be interacted with + * @param textStyle The typography style to be applied to the link text + * @param overflow How the text should handle overflow + * @param interactionSource Source of interactions for this link + * @param style The visual styling configuration for the link + * @see javax.swing.JLabel + */ @Composable public fun Link( text: String, @@ -76,6 +101,31 @@ public fun Link( ) } +/** + * An external link that follows the standard visual styling, including an external link icon. + * + * Provides a text link with an external link icon that indicates the link leads to external content. The link supports + * various states including enabled/disabled, focused, and hovered, with optional underline behavior based on the style + * configuration. + * + * **Guidelines:** [on IJP SDK webhelp](https://plugins.jetbrains.com/docs/intellij/link.html#external-link-icon) + * + * **Usage example:** + * [`Links.kt`](https://github.com/JetBrains/intellij-community/blob/master/platform/jewel/samples/standalone/src/main/kotlin/org/jetbrains/jewel/samples/standalone/view/component/Links.kt) + * + * **Swing equivalent:** [`JLabel`](https://docs.oracle.com/javase/tutorial/uiswing/components/label.html) with HTML + * link styling and external link icon + * + * @param text The text to be displayed as a link + * @param onClick Called when the link is clicked + * @param modifier Modifier to be applied to the link + * @param enabled Controls whether the link can be interacted with + * @param textStyle The typography style to be applied to the link text + * @param overflow How the text should handle overflow + * @param interactionSource Source of interactions for this link + * @param style The visual styling configuration for the link + * @see javax.swing.JLabel + */ @Composable public fun ExternalLink( text: String, @@ -100,6 +150,33 @@ public fun ExternalLink( ) } +/** + * A dropdown link that follows the standard visual styling with customizable appearance and menu content. + * + * Provides a text link with a dropdown chevron that, when clicked, displays a popup menu. The link supports various + * states including enabled/disabled, focused, and hovered, with optional underline behavior based on the style + * configuration. + * + * **Guidelines:** [on IJP SDK webhelp](https://plugins.jetbrains.com/docs/intellij/link.html#drop-down-link) + * + * **Usage example:** + * [`Links.kt`](https://github.com/JetBrains/intellij-community/blob/master/platform/jewel/samples/standalone/src/main/kotlin/org/jetbrains/jewel/samples/standalone/view/component/Links.kt) + * + * **Swing equivalent:** + * [`DropDownLink`](https://github.com/JetBrains/intellij-community/blob/master/platform/platform-api/src/com/intellij/ui/components/DropDownLink.kt) + * + * @param text The text to be displayed as a link + * @param modifier Modifier to be applied to the link + * @param enabled Controls whether the link can be interacted with + * @param textStyle The typography style to be applied to the link text + * @param overflow How the text should handle overflow + * @param interactionSource Source of interactions for this link + * @param style The visual styling configuration for the link + * @param menuModifier Modifier to be applied to the popup menu + * @param menuStyle The visual styling configuration for the popup menu + * @param menuContent The content to be displayed in the popup menu when the link is clicked + * @see com.intellij.ui.components.DropDownLink + */ @Composable public fun DropdownLink( text: String, diff --git a/platform/jewel/ui/src/main/kotlin/org/jetbrains/jewel/ui/component/ListComboBox.kt b/platform/jewel/ui/src/main/kotlin/org/jetbrains/jewel/ui/component/ListComboBox.kt index 3ca6826d3583..c3081051c72e 100644 --- a/platform/jewel/ui/src/main/kotlin/org/jetbrains/jewel/ui/component/ListComboBox.kt +++ b/platform/jewel/ui/src/main/kotlin/org/jetbrains/jewel/ui/component/ListComboBox.kt @@ -39,6 +39,35 @@ import org.jetbrains.jewel.ui.Outline import org.jetbrains.jewel.ui.component.styling.ComboBoxStyle import org.jetbrains.jewel.ui.theme.comboBoxStyle +/** + * A non-editable dropdown list component that follows the standard visual styling. + * + * Provides a selectable list of items in a dropdown format. When clicked, displays a popup with the list of items. + * Supports keyboard navigation, item selection, and custom item rendering. The selected item is displayed in the main + * control. + * + * **Guidelines:** [on IJP SDK webhelp](https://plugins.jetbrains.com/docs/intellij/drop-down.html) + * + * **Usage example:** + * [`Dropdowns.kt`](https://github.com/JetBrains/intellij-community/blob/master/platform/jewel/samples/showcase/src/main/kotlin/org/jetbrains/jewel/samples/showcase/components/Dropdowns.kt) + * + * **Swing equivalent:** + * [`ComboBox`](https://github.com/JetBrains/intellij-community/blob/master/platform/platform-api/src/com/intellij/openapi/ui/ComboBox.java) + * + * @param items The list of items to display in the dropdown + * @param modifier Modifier to be applied to the combo box + * @param isEnabled Controls whether the combo box can be interacted with + * @param initialSelectedIndex The index of the initially selected item + * @param outline The outline style to be applied to the combo box + * @param maxPopupHeight The maximum height of the popup list + * @param interactionSource Source of interactions for this combo box + * @param style The visual styling configuration for the combo box + * @param textStyle The typography style to be applied to the items + * @param onSelectedItemChange Called when the selected item changes, with the new index and item + * @param onPopupVisibleChange Called when the popup visibility changes + * @param itemContent Composable content for rendering each item in the list + * @see com.intellij.openapi.ui.ComboBox + */ @Composable public fun ListComboBox( items: List, @@ -161,6 +190,36 @@ public fun ListComboBox( } } +/** + * An editable dropdown list component that follows the standard visual styling. + * + * Provides a text field with a dropdown list of suggestions. Users can either select from the list or type their own + * value. Supports keyboard navigation, item selection, and custom item rendering. The selected or entered text is + * displayed in the editable text field. + * + * **Guidelines:** [on IJP SDK webhelp](https://plugins.jetbrains.com/docs/intellij/drop-down.html) + * + * **Usage example:** + * [`Dropdowns.kt`](https://github.com/JetBrains/intellij-community/blob/master/platform/jewel/samples/showcase/src/main/kotlin/org/jetbrains/jewel/samples/showcase/components/Dropdowns.kt) + * + * **Swing equivalent:** + * [`ComboBox`](https://github.com/JetBrains/intellij-community/blob/master/platform/platform-api/src/com/intellij/openapi/ui/ComboBox.java) + * with [setEditable(true)](https://docs.oracle.com/javase/8/docs/api/javax/swing/JComboBox.html#setEditable-boolean-) + * + * @param items The list of items to display in the dropdown + * @param modifier Modifier to be applied to the combo box + * @param isEnabled Controls whether the combo box can be interacted with + * @param initialSelectedIndex The index of the initially selected item + * @param outline The outline style to be applied to the combo box + * @param maxPopupHeight The maximum height of the popup list + * @param interactionSource Source of interactions for this combo box + * @param style The visual styling configuration for the combo box + * @param textStyle The typography style to be applied to the items + * @param onSelectedItemChange Called when the selected item changes, with the new index and item + * @param onPopupVisibleChange Called when the popup visibility changes + * @param itemContent Composable content for rendering each item in the list + * @see com.intellij.openapi.ui.ComboBox + */ @Composable public fun EditableListComboBox( items: List, diff --git a/platform/jewel/ui/src/main/kotlin/org/jetbrains/jewel/ui/component/Menu.kt b/platform/jewel/ui/src/main/kotlin/org/jetbrains/jewel/ui/component/Menu.kt index 59cf183c9716..d9ba2d5d73bf 100644 --- a/platform/jewel/ui/src/main/kotlin/org/jetbrains/jewel/ui/component/Menu.kt +++ b/platform/jewel/ui/src/main/kotlin/org/jetbrains/jewel/ui/component/Menu.kt @@ -87,6 +87,24 @@ import org.jetbrains.jewel.ui.painter.hints.Stateful import org.jetbrains.jewel.ui.theme.menuStyle import org.jetbrains.skiko.hostOs +/** + * A popup menu component that follows the standard visual styling with customizable content. + * + * Provides a floating menu that can be used for context menus, dropdown menus, and other popup menu scenarios. The menu + * supports keyboard navigation, icons, keybindings, and nested submenus. + * + * **Guidelines:** [on IJP SDK webhelp](https://plugins.jetbrains.com/docs/intellij/popups-and-menus.html) + * + * **Swing equivalent:** [`JPopupMenu`](https://docs.oracle.com/javase/tutorial/uiswing/components/menu.html#popup) + * + * @param onDismissRequest Called when the menu should be dismissed, returns true if the dismissal was handled + * @param horizontalAlignment The horizontal alignment of the menu relative to its anchor point + * @param modifier Modifier to be applied to the menu container + * @param style The visual styling configuration for the menu and its items + * @param popupProperties Properties controlling the popup window behavior + * @param content The menu content builder using [MenuScope] + * @see javax.swing.JPopupMenu + */ @Composable public fun PopupMenu( onDismissRequest: (InputMode) -> Boolean, @@ -205,7 +223,45 @@ private fun ShowMenuItem(item: MenuItem, canShowIcon: Boolean = false, canShowKe } } +/** + * Scope interface for building menu content using a DSL-style API. + * + * This interface provides methods for adding various types of menu items: + * - Selectable items with optional icons and keybindings + * - Submenus for nested menu structures + * - Passive items for custom content + * - Separators for visual grouping + * + * **Usage example:** + * + * ```kotlin + * PopupMenu { + * selectableItem(selected = false, onClick = { /* handle click */ }) { + * Text("Menu Item") + * } + * separator() + * submenu(content = { Text("Submenu") }) { + * selectableItem(selected = true, onClick = { /* handle click */ }) { + * Text("Submenu Item") + * } + * } + * } + * ``` + */ public interface MenuScope { + /** + * Adds a selectable menu item with optional icon and keybinding. + * + * Creates a menu item that can be selected and clicked. The item supports an optional icon and keybinding display, + * and can be enabled or disabled. When clicked, the provided onClick handler is called. + * + * @param selected Whether this item is currently selected + * @param iconKey Optional icon key for displaying an icon before the content + * @param keybinding Optional set of strings representing the keybinding (e.g., ["Ctrl", "C"]) + * @param onClick Called when the item is clicked + * @param enabled Controls whether the item can be interacted with + * @param content The content to be displayed in the menu item + */ public fun selectableItem( selected: Boolean, iconKey: IconKey? = null, @@ -215,6 +271,18 @@ public interface MenuScope { content: @Composable () -> Unit, ) + /** + * Adds a submenu item that opens a nested menu when hovered or clicked. + * + * Creates a menu item that displays a nested menu when the user interacts with it. The submenu can have its own + * items and supports the same features as the parent menu. Submenus can be nested to create hierarchical menu + * structures. + * + * @param enabled Controls whether the submenu can be interacted with + * @param iconKey Optional icon key for displaying an icon before the content + * @param submenu Builder for the submenu content using the same [MenuScope] DSL + * @param content The content to be displayed in the submenu item + */ public fun submenu( enabled: Boolean = true, iconKey: IconKey? = null, @@ -222,9 +290,23 @@ public interface MenuScope { content: @Composable () -> Unit, ) + /** + * Adds a non-interactive item with custom content to the menu. + * + * Creates a menu item that displays custom content but does not respond to user interaction. This is useful for + * displaying informational content, headers, or other non-interactive elements within the menu. + * + * @param content The custom content to be displayed in the menu item + */ public fun passiveItem(content: @Composable () -> Unit) } +/** + * Adds a visual separator line between menu items. + * + * Creates a horizontal line that helps visually group related menu items. This is commonly used to separate different + * sections of a menu, making it easier for users to understand the menu's structure. + */ public fun MenuScope.separator() { passiveItem { MenuSeparator() } } @@ -643,6 +725,19 @@ internal fun Submenu( } } +/** + * State holder for menu items that tracks various interaction states. + * + * This class maintains the state of a menu item, including selection, enabled/disabled state, focus, hover, and press + * states. It implements both [SelectableComponentState] and [FocusableComponentState] for consistent behavior with + * other interactive components. + * + * The state is stored efficiently using a bit-masked value, where each bit represents a different state flag. + * + * @property state The raw bit-masked state value + * @see SelectableComponentState + * @see FocusableComponentState + */ @Immutable @JvmInline public value class MenuItemState(public val state: ULong) : SelectableComponentState, FocusableComponentState { diff --git a/platform/jewel/ui/src/main/kotlin/org/jetbrains/jewel/ui/component/RadioButton.kt b/platform/jewel/ui/src/main/kotlin/org/jetbrains/jewel/ui/component/RadioButton.kt index 6a299c91b3cf..6c7146a49aba 100644 --- a/platform/jewel/ui/src/main/kotlin/org/jetbrains/jewel/ui/component/RadioButton.kt +++ b/platform/jewel/ui/src/main/kotlin/org/jetbrains/jewel/ui/component/RadioButton.kt @@ -49,6 +49,32 @@ import org.jetbrains.jewel.ui.painter.hints.Stateful import org.jetbrains.jewel.ui.painter.rememberResourcePainterProvider import org.jetbrains.jewel.ui.theme.radioButtonStyle +/** + * A radio button component that follows the standard visual styling with customizable appearance. + * + * Provides a selectable component that can be either selected or unselected, typically used as part of a group where + * only one option can be selected at a time. The radio button supports various states including enabled/disabled, + * focused, and hovered. + * + * **Guidelines:** [on IJP SDK webhelp](https://plugins.jetbrains.com/docs/intellij/radio-button.html) + * + * **Usage example:** + * [`RadioButtons.kt`](https://github.com/JetBrains/intellij-community/blob/master/platform/jewel/samples/showcase/src/main/kotlin/org/jetbrains/jewel/samples/showcase/components/RadioButtons.kt) + * + * **Swing equivalent:** + * [`JRadioButton`](https://docs.oracle.com/javase/tutorial/uiswing/components/button.html#radiobutton) + * + * @param selected The current state of the radio button + * @param onClick Called when the radio button is clicked + * @param modifier Modifier to be applied to the radio button + * @param enabled Controls the enabled state of the radio button. When false, the radio button cannot be interacted with + * @param outline The outline style to be applied to the radio button + * @param interactionSource Source of interactions for this radio button + * @param style The visual styling configuration for the radio button + * @param textStyle The typography style to be applied to the radio button's text content + * @param verticalAlignment The vertical alignment of the radio button relative to its text content + * @see javax.swing.JRadioButton + */ @Composable public fun RadioButton( selected: Boolean, @@ -75,6 +101,34 @@ public fun RadioButton( ) } +/** + * A radio button with accompanying text, following the standard visual styling with customizable appearance. + * + * Provides a horizontal layout combining a radio button with text content. The entire row is clickable, making it + * easier for users to interact with the radio button. This component is commonly used in forms, settings panels, and + * option lists where multiple options are mutually exclusive. + * + * **Guidelines:** [on IJP SDK webhelp](https://plugins.jetbrains.com/docs/intellij/radio-button.html) + * + * **Usage example:** + * [`RadioButtons.kt`](https://github.com/JetBrains/intellij-community/blob/master/platform/jewel/samples/showcase/src/main/kotlin/org/jetbrains/jewel/samples/showcase/components/RadioButtons.kt) + * + * **Swing equivalent:** + * [`JRadioButton`](https://docs.oracle.com/javase/tutorial/uiswing/components/button.html#radiobutton) with text + * constructor + * + * @param text The text to be displayed next to the radio button + * @param selected The current state of the radio button + * @param onClick Called when the radio button or row is clicked + * @param modifier Modifier to be applied to the entire row + * @param enabled Controls the enabled state of the radio button. When false, the row cannot be interacted with + * @param outline The outline style to be applied to the radio button + * @param interactionSource Source of interactions for this radio button + * @param style The visual styling configuration for the radio button + * @param textStyle The typography style to be applied to the text content + * @param verticalAlignment The vertical alignment of the radio button relative to its text content + * @see javax.swing.JRadioButton + */ @Composable public fun RadioButtonRow( text: String, @@ -103,6 +157,34 @@ public fun RadioButtonRow( } } +/** + * A radio button with customizable content, following the standard visual styling. + * + * Provides a horizontal layout combining a radio button with custom content. The entire row is clickable, making it + * easier for users to interact with the radio button. This variant allows for more complex content layouts than the + * simple text variant. + * + * **Guidelines:** [on IJP SDK webhelp](https://plugins.jetbrains.com/docs/intellij/radio-button.html) + * + * **Usage example:** + * [`RadioButtons.kt`](https://github.com/JetBrains/intellij-community/blob/master/platform/jewel/samples/showcase/src/main/kotlin/org/jetbrains/jewel/samples/showcase/components/RadioButtons.kt) + * + * **Swing equivalent:** + * [`JRadioButton`](https://docs.oracle.com/javase/tutorial/uiswing/components/button.html#radiobutton) with custom + * component layout + * + * @param selected The current state of the radio button + * @param onClick Called when the radio button or row is clicked + * @param modifier Modifier to be applied to the entire row + * @param enabled Controls the enabled state of the radio button. When false, the row cannot be interacted with + * @param outline The outline style to be applied to the radio button + * @param interactionSource Source of interactions for this radio button + * @param style The visual styling configuration for the radio button + * @param textStyle The typography style to be applied to the content + * @param verticalAlignment The vertical alignment of the radio button relative to its content + * @param content The content to be displayed next to the radio button + * @see javax.swing.JRadioButton + */ @Composable public fun RadioButtonRow( selected: Boolean, diff --git a/platform/jewel/ui/src/main/kotlin/org/jetbrains/jewel/ui/component/ScrollableContainer.kt b/platform/jewel/ui/src/main/kotlin/org/jetbrains/jewel/ui/component/ScrollableContainer.kt index ea275d3220b5..137a59aa2445 100644 --- a/platform/jewel/ui/src/main/kotlin/org/jetbrains/jewel/ui/component/ScrollableContainer.kt +++ b/platform/jewel/ui/src/main/kotlin/org/jetbrains/jewel/ui/component/ScrollableContainer.kt @@ -48,6 +48,31 @@ private const val ID_CONTENT = "VerticallyScrollableContainer_content" private const val ID_VERTICAL_SCROLLBAR = "VerticallyScrollableContainer_verticalScrollbar" private const val ID_HORIZONTAL_SCROLLBAR = "VerticallyScrollableContainer_horizontalScrollbar" +/** + * A vertically scrollable container that follows the standard visual styling. + * + * Provides a container with a vertical scrollbar that matches the platform's native appearance. On macOS, the scrollbar + * appears next to the content, while on Windows/Linux it overlays the content. The scrollbar's visibility and behavior + * adapts to the platform conventions. + * + * **Guidelines:** [on IJP SDK webhelp](https://plugins.jetbrains.com/docs/intellij/scrollbar.html) + * + * **Usage example:** + * [`Scrollbars.kt`](https://github.com/JetBrains/intellij-community/blob/master/platform/jewel/samples/showcase/src/main/kotlin/org/jetbrains/jewel/samples/showcase/components/Scrollbars.kt) + * + * **Swing equivalent:** + * [`JBScrollBar`](https://github.com/JetBrains/intellij-community/blob/master/platform/platform-api/src/com/intellij/ui/components/JBScrollBar.java) + * + * @param modifier Modifier to be applied to the container + * @param scrollbarModifier Modifier to be applied to the scrollbar + * @param scrollState The state object to control and observe scrolling + * @param style The visual styling configuration for the scrollbar + * @param reverseLayout Whether the scrollbar should be displayed on the opposite side + * @param scrollbarEnabled Controls whether the scrollbar is enabled + * @param scrollbarInteractionSource Source of interactions for the scrollbar + * @param content The content to be displayed in the scrollable container + * @see com.intellij.ui.components.JBScrollBar + */ @Composable public fun VerticallyScrollableContainer( modifier: Modifier = Modifier, @@ -109,6 +134,31 @@ internal fun TextAreaScrollableContainer( } } +/** + * A vertically scrollable container that follows the standard visual styling. + * + * Provides a container with a vertical scrollbar that matches the platform's native appearance. On macOS, the scrollbar + * appears next to the content, while on Windows/Linux it overlays the content. The scrollbar's visibility and behavior + * adapts to the platform conventions. + * + * **Guidelines:** [on IJP SDK webhelp](https://plugins.jetbrains.com/docs/intellij/scrollbar.html) + * + * **Usage example:** + * [`Scrollbars.kt`](https://github.com/JetBrains/intellij-community/blob/master/platform/jewel/samples/showcase/src/main/kotlin/org/jetbrains/jewel/samples/showcase/components/Scrollbars.kt) + * + * **Swing equivalent:** + * [`JBScrollBar`](https://github.com/JetBrains/intellij-community/blob/master/platform/platform-api/src/com/intellij/ui/components/JBScrollBar.java) + * + * @param scrollState The state object to control and observe scrolling + * @param modifier Modifier to be applied to the container + * @param scrollbarModifier Modifier to be applied to the scrollbar + * @param style The visual styling configuration for the scrollbar + * @param reverseLayout Whether the scrollbar should be displayed on the opposite side + * @param scrollbarEnabled Controls whether the scrollbar is enabled + * @param scrollbarInteractionSource Source of interactions for the scrollbar + * @param content The content to be displayed in the scrollable container + * @see com.intellij.ui.components.JBScrollBar + */ @Composable public fun VerticallyScrollableContainer( scrollState: LazyListState, @@ -143,6 +193,31 @@ public fun VerticallyScrollableContainer( } } +/** + * A vertically scrollable container that follows the standard visual styling. + * + * Provides a container with a vertical scrollbar that matches the platform's native appearance. On macOS, the scrollbar + * appears next to the content, while on Windows/Linux it overlays the content. The scrollbar's visibility and behavior + * adapts to the platform conventions. + * + * **Guidelines:** [on IJP SDK webhelp](https://plugins.jetbrains.com/docs/intellij/scrollbar.html) + * + * **Usage example:** + * [`Scrollbars.kt`](https://github.com/JetBrains/intellij-community/blob/master/platform/jewel/samples/showcase/src/main/kotlin/org/jetbrains/jewel/samples/showcase/components/Scrollbars.kt) + * + * **Swing equivalent:** + * [`JBScrollBar`](https://github.com/JetBrains/intellij-community/blob/master/platform/platform-api/src/com/intellij/ui/components/JBScrollBar.java) + * + * @param scrollState The state object to control and observe scrolling + * @param modifier Modifier to be applied to the container + * @param scrollbarModifier Modifier to be applied to the scrollbar + * @param style The visual styling configuration for the scrollbar + * @param reverseLayout Whether the scrollbar should be displayed on the opposite side + * @param scrollbarEnabled Controls whether the scrollbar is enabled + * @param scrollbarInteractionSource Source of interactions for the scrollbar + * @param content The content to be displayed in the scrollable container + * @see com.intellij.ui.components.JBScrollBar + */ @Composable public fun VerticallyScrollableContainer( scrollState: LazyGridState, @@ -177,6 +252,31 @@ public fun VerticallyScrollableContainer( } } +/** + * A horizontally scrollable container that follows the standard visual styling. + * + * Provides a container with a horizontal scrollbar that matches the platform's native appearance. On macOS, the + * scrollbar appears below the content, while on Windows/Linux it overlays the content. The scrollbar's visibility and + * behavior adapts to the platform conventions. + * + * **Guidelines:** [on IJP SDK webhelp](https://plugins.jetbrains.com/docs/intellij/scrollbar.html) + * + * **Usage example:** + * [`Scrollbars.kt`](https://github.com/JetBrains/intellij-community/blob/master/platform/jewel/samples/showcase/src/main/kotlin/org/jetbrains/jewel/samples/showcase/components/Scrollbars.kt) + * + * **Swing equivalent:** + * [`JBScrollBar`](https://github.com/JetBrains/intellij-community/blob/master/platform/platform-api/src/com/intellij/ui/components/JBScrollBar.java) + * + * @param modifier Modifier to be applied to the container + * @param scrollbarModifier Modifier to be applied to the scrollbar + * @param scrollState The state object to control and observe scrolling + * @param style The visual styling configuration for the scrollbar + * @param reverseLayout Whether the scrollbar should be displayed on the opposite side + * @param scrollbarEnabled Controls whether the scrollbar is enabled + * @param scrollbarInteractionSource Source of interactions for the scrollbar + * @param content The content to be displayed in the scrollable container + * @see com.intellij.ui.components.JBScrollBar + */ @Composable public fun HorizontallyScrollableContainer( modifier: Modifier = Modifier, @@ -211,6 +311,31 @@ public fun HorizontallyScrollableContainer( } } +/** + * A horizontally scrollable container that follows the standard visual styling. + * + * Provides a container with a horizontal scrollbar that matches the platform's native appearance. On macOS, the + * scrollbar appears below the content, while on Windows/Linux it overlays the content. The scrollbar's visibility and + * behavior adapts to the platform conventions. + * + * **Guidelines:** [on IJP SDK webhelp](https://plugins.jetbrains.com/docs/intellij/scrollbar.html) + * + * **Usage example:** + * [`Scrollbars.kt`](https://github.com/JetBrains/intellij-community/blob/master/platform/jewel/samples/showcase/src/main/kotlin/org/jetbrains/jewel/samples/showcase/components/Scrollbars.kt) + * + * **Swing equivalent:** + * [`JBScrollBar`](https://github.com/JetBrains/intellij-community/blob/master/platform/platform-api/src/com/intellij/ui/components/JBScrollBar.java) + * + * @param modifier Modifier to be applied to the container + * @param scrollbarModifier Modifier to be applied to the scrollbar + * @param scrollState The state object to control and observe scrolling + * @param style The visual styling configuration for the scrollbar + * @param reverseLayout Whether the scrollbar should be displayed on the opposite side + * @param scrollbarEnabled Controls whether the scrollbar is enabled + * @param scrollbarInteractionSource Source of interactions for the scrollbar + * @param content The content to be displayed in the scrollable container + * @see com.intellij.ui.components.JBScrollBar + */ @Composable public fun HorizontallyScrollableContainer( scrollState: LazyListState, @@ -245,6 +370,31 @@ public fun HorizontallyScrollableContainer( } } +/** + * A horizontally scrollable container that follows the standard visual styling. + * + * Provides a container with a horizontal scrollbar that matches the platform's native appearance. On macOS, the + * scrollbar appears below the content, while on Windows/Linux it overlays the content. The scrollbar's visibility and + * behavior adapts to the platform conventions. + * + * **Guidelines:** [on IJP SDK webhelp](https://plugins.jetbrains.com/docs/intellij/scrollbar.html) + * + * **Usage example:** + * [`Scrollbars.kt`](https://github.com/JetBrains/intellij-community/blob/master/platform/jewel/samples/showcase/src/main/kotlin/org/jetbrains/jewel/samples/showcase/components/Scrollbars.kt) + * + * **Swing equivalent:** + * [`JBScrollBar`](https://github.com/JetBrains/intellij-community/blob/master/platform/platform-api/src/com/intellij/ui/components/JBScrollBar.java) + * + * @param modifier Modifier to be applied to the container + * @param scrollbarModifier Modifier to be applied to the scrollbar + * @param scrollState The state object to control and observe scrolling + * @param style The visual styling configuration for the scrollbar + * @param reverseLayout Whether the scrollbar should be displayed on the opposite side + * @param scrollbarEnabled Controls whether the scrollbar is enabled + * @param scrollbarInteractionSource Source of interactions for the scrollbar + * @param content The content to be displayed in the scrollable container + * @see com.intellij.ui.components.JBScrollBar + */ @Composable public fun HorizontallyScrollableContainer( scrollState: LazyGridState, @@ -543,11 +693,19 @@ private fun computeContentConstraints( } /** - * A content padding to apply when you want to ensure the content is not overlapped by scrollbars. This value can be - * used for both vertical and horizontal scrollbars. + * Calculates the safe padding needed to prevent content from being overlapped by scrollbars. This value can be used for + * both vertical and horizontal scrollbars. * - * When the [style] is [AlwaysVisible], this value is zero, since the various `ScrollableContainer`s will prevent - * overlapping anyway. If it is [WhenScrolling], this value will be the maximum thickness of the scrollbar. + * Returns a padding value that ensures content remains fully visible when scrollbars are present. The value depends on + * the platform (macOS vs Windows/Linux) and the scrollbar visibility style: + * - For macOS with always-visible scrollbars: returns 0 as the layout already accounts for the space + * - For macOS with auto-hiding scrollbars: returns the maximum scrollbar thickness + * - For Windows/Linux: returns the maximum scrollbar thickness as scrollbars overlay content + * + * @param style The scrollbar styling configuration to use for calculations. When the [style] is [AlwaysVisible], this + * value is zero, since the various `ScrollableContainer`s will prevent overlapping anyway. If it is [WhenScrolling], + * this value will be the maximum thickness of the scrollbar. + * @return The padding needed to prevent content overlap with scrollbars */ @Composable public fun scrollbarContentSafePadding(style: ScrollbarStyle = JewelTheme.scrollbarStyle): Dp = diff --git a/platform/jewel/ui/src/main/kotlin/org/jetbrains/jewel/ui/component/SegmentedControl.kt b/platform/jewel/ui/src/main/kotlin/org/jetbrains/jewel/ui/component/SegmentedControl.kt index 651023972db4..094c722c18f6 100644 --- a/platform/jewel/ui/src/main/kotlin/org/jetbrains/jewel/ui/component/SegmentedControl.kt +++ b/platform/jewel/ui/src/main/kotlin/org/jetbrains/jewel/ui/component/SegmentedControl.kt @@ -37,6 +37,36 @@ import org.jetbrains.jewel.ui.focusOutline import org.jetbrains.jewel.ui.theme.segmentedControlButtonStyle import org.jetbrains.jewel.ui.theme.segmentedControlStyle +/** + * A segmented control component that displays a horizontal group of mutually exclusive buttons. Each segment represents + * an option that can be selected, with only one segment being selected at a time. The control provides built-in + * keyboard navigation and focus management. + * + * Segmented controls are commonly used for: + * - Switching between different views + * - Selecting from a small set of mutually exclusive options + * - Filtering content with different criteria + * + * **Guidelines:** + * [on IJP SDK webhelp](https://plugins.jetbrains.com/docs/intellij/radio-button.html#5-and-more-options) + * + * **Example usage:** + * [`SegmentedControls`](https://github.com/JetBrains/intellij-community/blob/master/platform/jewel/samples/showcase/src/main/kotlin/org/jetbrains/jewel/samples/showcase/components/SegmentedControls.kt) + * + * **Swing equivalent:** + * [`JBRadioButton`](https://github.com/JetBrains/intellij-community/blob/master/platform/platform-api/src/com/intellij/ui/components/JBRadioButton.java) + * + * @param buttons List of [SegmentedControlButtonData] that define the segments to display. Each button contains its + * selection state, content, and selection callback. + * @param modifier Modifier to be applied to the control + * @param enabled Controls the enabled state of the entire control. When false, all segments become disabled + * @param style The [SegmentedControlStyle] that defines visual properties like colors and metrics for the control + * container + * @param buttonStyle The [SegmentedControlButtonStyle] that defines visual properties for individual segments + * @param textStyle The [TextStyle] to be applied to text content within the segments + * @param interactionSource The [MutableInteractionSource] that will be used to handle interactions with the control + * @see com.intellij.ui.components.JBRadioButton + */ @Composable public fun SegmentedControl( buttons: List, diff --git a/platform/jewel/ui/src/main/kotlin/org/jetbrains/jewel/ui/component/Slider.kt b/platform/jewel/ui/src/main/kotlin/org/jetbrains/jewel/ui/component/Slider.kt index 324f3a4aa1ff..4005527486ae 100644 --- a/platform/jewel/ui/src/main/kotlin/org/jetbrains/jewel/ui/component/Slider.kt +++ b/platform/jewel/ui/src/main/kotlin/org/jetbrains/jewel/ui/component/Slider.kt @@ -86,8 +86,39 @@ import org.jetbrains.jewel.ui.component.styling.SliderStyle import org.jetbrains.jewel.ui.focusOutline import org.jetbrains.jewel.ui.theme.sliderStyle -// Note: a lot of code in this file is from the Material 2 implementation - +/** + * A slider component that follows the standard visual styling. + * + * Provides a draggable thumb that moves along a track to select a value from a continuous range. Supports step + * intervals, keyboard navigation, and both mouse and touch input. The component includes visual feedback for hover, + * focus, and press states. + * + * Features: + * - Continuous or stepped value selection + * - Keyboard navigation with arrow keys, Home/End, and Page Up/Down + * - Mouse drag and click positioning + * - Touch input support + * - Optional tick marks for stepped values + * - RTL layout support + * + * This implementation is heavily based on the Material 2 slider implementation. + * + * **Usage example:** + * [`Slider.kt`](https://github.com/JetBrains/intellij-community/blob/master/platform/jewel/samples/showcase/src/main/kotlin/org/jetbrains/jewel/samples/showcase/components/Slider.kt) + * + * **Swing equivalent:** [`JSlider`](https://docs.oracle.com/javase/tutorial/uiswing/components/slider.html) + * + * @param value The current value of the slider + * @param onValueChange Called when the value changes as the user drags the thumb + * @param modifier Modifier to be applied to the slider + * @param enabled Controls whether the slider can be interacted with + * @param valueRange The range of values that the slider can take + * @param steps The number of discrete steps between valueRange.start and valueRange.endInclusive + * @param onValueChangeFinished Called when the user finishes moving the slider + * @param interactionSource Source of interactions for this slider + * @param style The visual styling configuration for the slider + * @see javax.swing.JSlider + */ @Composable public fun Slider( value: Float, diff --git a/platform/jewel/ui/src/main/kotlin/org/jetbrains/jewel/ui/component/TabStrip.kt b/platform/jewel/ui/src/main/kotlin/org/jetbrains/jewel/ui/component/TabStrip.kt index 72280dd82648..df034453e1e0 100644 --- a/platform/jewel/ui/src/main/kotlin/org/jetbrains/jewel/ui/component/TabStrip.kt +++ b/platform/jewel/ui/src/main/kotlin/org/jetbrains/jewel/ui/component/TabStrip.kt @@ -30,6 +30,26 @@ import org.jetbrains.jewel.foundation.state.CommonStateBitMask import org.jetbrains.jewel.foundation.state.FocusableComponentState import org.jetbrains.jewel.ui.component.styling.TabStyle +/** + * A horizontal strip of tabs that follows the standard visual styling with customizable appearance. + * + * Provides a scrollable container for displaying a row of tabs, with support for selection, hover effects, and + * automatic scrollbar visibility. The tabs can be closable or fixed, and support custom content layouts. + * + * **Guidelines:** [on IJP SDK webhelp](https://plugins.jetbrains.com/docs/intellij/tabs.html) + * + * **Usage example:** + * [`Tabs.kt`](https://github.com/JetBrains/intellij-community/blob/master/platform/jewel/samples/showcase/src/main/kotlin/org/jetbrains/jewel/samples/showcase/components/Tabs.kt) + * + * **Swing equivalent:** [`JTabbedPane`](https://docs.oracle.com/javase/tutorial/uiswing/components/tabbedpane.html) + * + * @param tabs The list of tab data objects defining the content and behavior of each tab + * @param style The visual styling configuration for the tab strip and its tabs + * @param modifier Modifier to be applied to the tab strip container + * @param enabled Controls the enabled state of the tab strip. When false, no tabs can be interacted with + * @see javax.swing.JTabbedPane + * @see com.intellij.ui.components.JBTabbedPane + */ @Composable public fun TabStrip(tabs: List, style: TabStyle, modifier: Modifier = Modifier, enabled: Boolean = true) { var tabStripState: TabStripState by remember { mutableStateOf(TabStripState.of(enabled = true)) } @@ -79,6 +99,18 @@ public sealed class TabData { public abstract val onClose: () -> Unit public abstract val onClick: () -> Unit + /** + * Standard tab implementation suitable for most use cases. + * + * This implementation provides the standard tab behavior and appearance, making it suitable for general-purpose + * tabs in dialogs, tool windows, and other UI components. + * + * @property selected Whether this tab is currently selected + * @property content The composable content to be displayed within the tab + * @property closable Whether this tab can be closed by the user (defaults to true) + * @property onClose Called when the user attempts to close the tab + * @property onClick Called when the user clicks the tab + */ @Immutable @GenerateDataFunctions public class Default( @@ -123,6 +155,18 @@ public sealed class TabData { } } + /** + * Editor-specific tab implementation with specialized styling and behavior. + * + * This implementation is specifically designed for editor tabs, providing the appropriate styling and behavior for + * displaying file editors. It matches the appearance of IDE editor tabs. + * + * @property selected Whether this tab is currently selected + * @property content The composable content to be displayed within the tab + * @property closable Whether this tab can be closed by the user (defaults to true) + * @property onClose Called when the user attempts to close the tab + * @property onClick Called when the user clicks the tab + */ @Immutable @GenerateDataFunctions public class Editor( @@ -168,6 +212,16 @@ public sealed class TabData { } } +/** + * State holder for the tab strip component that tracks various interaction states. + * + * This class maintains the state of a tab strip, including enabled/disabled state, focus, hover, and press states. It + * uses a bit-masked value for efficient state storage and implements [FocusableComponentState] for consistent behavior + * with other focusable components. + * + * @property state The raw bit-masked state value + * @see FocusableComponentState + */ @Immutable @JvmInline public value class TabStripState(public val state: ULong) : FocusableComponentState { diff --git a/platform/jewel/ui/src/main/kotlin/org/jetbrains/jewel/ui/component/TextArea.kt b/platform/jewel/ui/src/main/kotlin/org/jetbrains/jewel/ui/component/TextArea.kt index da17baf4d155..34e89842d256 100644 --- a/platform/jewel/ui/src/main/kotlin/org/jetbrains/jewel/ui/component/TextArea.kt +++ b/platform/jewel/ui/src/main/kotlin/org/jetbrains/jewel/ui/component/TextArea.kt @@ -50,6 +50,41 @@ import org.jetbrains.jewel.ui.component.styling.TextAreaStyle import org.jetbrains.jewel.ui.theme.scrollbarStyle import org.jetbrains.jewel.ui.theme.textAreaStyle +/** + * A multi-line text input component that follows the standard visual styling. + * + * Provides a scrollable text editing area that can display and edit multiple lines of text. The component includes + * standard text editing capabilities, scrollbars when needed, and platform-specific key bindings. + * + * **Guidelines:** [on IJP SDK webhelp](https://plugins.jetbrains.com/docs/intellij/text-area.html) + * + * **Usage example:** + * [`TextAreas.kt`](https://github.com/JetBrains/intellij-community/blob/master/platform/jewel/samples/showcase/src/main/kotlin/org/jetbrains/jewel/samples/showcase/components/TextAreas.kt) + * + * **Swing equivalent:** + * [`JBTextArea`](https://github.com/JetBrains/intellij-community/blob/master/platform/platform-api/src/com/intellij/ui/components/JBTextArea.java) + * + * @param state The state object controlling the text content and selection + * @param modifier Modifier to be applied to the text area + * @param enabled Controls whether the text area can be interacted with + * @param readOnly Controls whether the text can be modified + * @param inputTransformation Transforms text input before it appears in the text area + * @param textStyle The typography style to be applied to the text + * @param keyboardOptions Options controlling keyboard input behavior + * @param onKeyboardAction Handler for keyboard actions + * @param lineLimits Constraints on the number of lines allowed + * @param onTextLayout Callback for text layout changes + * @param interactionSource Source of interactions for this text area + * @param style The visual styling configuration for the text area + * @param outline The outline style to be applied to the text area + * @param placeholder Content to display when the text area is empty + * @param decorationBoxModifier Modifier to be applied to the decoration box + * @param outputTransformation Transforms text output for display + * @param undecorated Whether to show the text area without decorations + * @param scrollState The state object controlling scrolling behavior + * @param scrollbarStyle The visual styling configuration for the scrollbar + * @see com.intellij.ui.components.JBTextArea + */ @Composable public fun TextArea( state: TextFieldState, diff --git a/platform/jewel/ui/src/main/kotlin/org/jetbrains/jewel/ui/component/TextField.kt b/platform/jewel/ui/src/main/kotlin/org/jetbrains/jewel/ui/component/TextField.kt index 94a2646aa2f9..cb7d6741e409 100644 --- a/platform/jewel/ui/src/main/kotlin/org/jetbrains/jewel/ui/component/TextField.kt +++ b/platform/jewel/ui/src/main/kotlin/org/jetbrains/jewel/ui/component/TextField.kt @@ -41,6 +41,41 @@ import org.jetbrains.jewel.ui.Outline import org.jetbrains.jewel.ui.component.styling.TextFieldStyle import org.jetbrains.jewel.ui.theme.textFieldStyle +/** + * A single-line text input component that follows the standard visual styling. + * + * Provides a text input field for single-line text entry with optional leading and trailing icons, placeholder text, + * and various text input features. The component supports standard text editing capabilities and platform-specific key + * bindings. + * + * **Guidelines:** [on IJP SDK webhelp](https://plugins.jetbrains.com/docs/intellij/input-field.html) + * + * **Usage example:** + * [`TextFields.kt`](https://github.com/JetBrains/intellij-community/blob/master/platform/jewel/samples/showcase/src/main/kotlin/org/jetbrains/jewel/samples/showcase/components/TextFields.kt) + * + * **Swing equivalent:** + * [`JBTextField`](https://github.com/JetBrains/intellij-community/blob/master/platform/platform-api/src/com/intellij/ui/components/JBTextField.java) + * and [`JTextField`](https://docs.oracle.com/javase/tutorial/uiswing/components/textfield.html) + * + * @param state The state object controlling the text content and selection + * @param modifier Modifier to be applied to the text field + * @param enabled Controls whether the text field can be interacted with + * @param readOnly Controls whether the text can be modified + * @param inputTransformation Transforms text input before it appears in the field + * @param textStyle The typography style to be applied to the text + * @param keyboardOptions Options controlling keyboard input behavior + * @param onKeyboardAction Handler for keyboard actions + * @param onTextLayout Callback for text layout changes + * @param interactionSource Source of interactions for this text field + * @param style The visual styling configuration for the text field + * @param outline The outline style to be applied to the text field + * @param placeholder Content to display when the text field is empty + * @param leadingIcon Optional icon to display before the text + * @param trailingIcon Optional icon to display after the text + * @param outputTransformation Transforms text output for display + * @param undecorated Whether to show the text field without decorations + * @see com.intellij.ui.components.JBTextField + */ @Suppress("DuplicatedCode") // The dupe is scheduled for removal @Composable public fun TextField( diff --git a/platform/jewel/ui/src/main/kotlin/org/jetbrains/jewel/ui/component/Tooltip.kt b/platform/jewel/ui/src/main/kotlin/org/jetbrains/jewel/ui/component/Tooltip.kt index 95658440f161..286dd2507f65 100644 --- a/platform/jewel/ui/src/main/kotlin/org/jetbrains/jewel/ui/component/Tooltip.kt +++ b/platform/jewel/ui/src/main/kotlin/org/jetbrains/jewel/ui/component/Tooltip.kt @@ -31,15 +31,27 @@ import org.jetbrains.jewel.ui.theme.tooltipStyle import org.jetbrains.jewel.ui.util.isDark /** - * Shows a tooltip when the mouse pointer lingers on the [content] for long enough. Provides the styling for the tooltip - * container. + * A tooltip component that follows the standard visual styling. * - * @param tooltip The content of the tooltip. + * Provides a floating tooltip that appears when hovering over or focusing the target content. The tooltip follows + * platform conventions for timing, positioning, and appearance, supporting both mouse and keyboard navigation. + * + * **Guidelines:** [on IJP SDK webhelp](https://plugins.jetbrains.com/docs/intellij/tooltip.html) + * + * **Usage example:** + * [`Tooltips.kt`](https://github.com/JetBrains/intellij-community/blob/master/platform/jewel/samples/showcase/src/main/kotlin/org/jetbrains/jewel/samples/showcase/components/Tooltips.kt) + * + * **Swing equivalent:** + * [`HelpTooltip`](https://github.com/JetBrains/intellij-community/blob/master/platform/platform-api/src/com/intellij/ide/HelpTooltip.java) + * and [How to Use Tool Tips](https://docs.oracle.com/javase/tutorial/uiswing/components/tooltip.html) + * + * @param tooltip The content to be displayed in the tooltip * @param modifier Modifier to apply to the content's wrapper - * @param enabled When true, the tooltip can be shown. When false, it will never show. - * @param style The style to apply to the tooltip. - * @param tooltipPlacement The placement of the tooltip. - * @param content The component for which to show the tooltip on hover. + * @param enabled Controls whether the tooltip can be shown. When false, it will never show + * @param style The visual styling configuration for the tooltip + * @param tooltipPlacement The placement strategy for positioning the tooltip relative to the content + * @param content The component for which to show the tooltip on hover + * @see com.intellij.ide.HelpTooltip */ @Composable public fun Tooltip( @@ -87,12 +99,15 @@ private fun TooltipImpl(style: TooltipStyle, tooltip: @Composable () -> Unit) { } /** - * [TooltipPlacement] implementation for providing a [PopupPositionProvider] that calculates the position of the popup - * relative to the current mouse cursor position, but never changes it after showing the popup. + * A tooltip placement strategy that positions the tooltip relative to the cursor position. * - * @param offset [DpOffset] to be added to the position of the popup. - * @param alignment The alignment of the popup relative to the current cursor position. - * @param windowMargin Defines the area within the window that limits the placement of the popup. + * Provides a [PopupPositionProvider] that calculates the position of the tooltip relative to the current mouse cursor + * position, maintaining that position after showing the tooltip. This allows for stable tooltip positioning that + * doesn't follow cursor movement. + * + * @param offset Additional offset to be added to the tooltip position + * @param alignment The alignment of the tooltip relative to the cursor position + * @param windowMargin The minimum distance to maintain from window edges */ @ExperimentalJewelApi public class FixedCursorPoint( @@ -111,13 +126,17 @@ public class FixedCursorPoint( } /** - * A [PopupPositionProvider] that positions the popup at the given position relative to the anchor, but never updates it - * after showing the popup. + * Creates a position provider that maintains a fixed position relative to an anchor point. * - * @param positionPx the offset, in pixels, relative to the anchor, to position the popup at. - * @param offset [DpOffset] to be added to the position of the popup. - * @param alignment The alignment of the popup relative to desired position. - * @param windowMargin Defines the area within the window that limits the placement of the popup. + * Returns a [PopupPositionProvider] that positions the popup at the given position relative to the anchor, maintaining + * that position after showing the popup. This ensures stable positioning that doesn't update with subsequent anchor + * movement. + * + * @param positionPx The offset in pixels relative to the anchor + * @param offset Additional offset to be added to the popup position + * @param alignment The alignment of the popup relative to the desired position + * @param windowMargin The minimum distance to maintain from window edges + * @return A [PopupPositionProvider] that maintains the specified positioning */ @ExperimentalJewelApi @Composable