@theia/core 1.67.0-next.3 → 1.67.0-next.59

package/src/browser/markdown-rendering/markdown.tsx

@@ -0,0 +1,282 @@
+// *****************************************************************************
+// Copyright (C) 2025 EclipseSource and others.
+//
+// This program and the accompanying materials are made available under the
+// terms of the Eclipse Public License v. 2.0 which is available at
+// http://www.eclipse.org/legal/epl-2.0.
+//
+// This Source Code may also be made available under the following Secondary
+// Licenses when the conditions for such availability set forth in the Eclipse
+// Public License v. 2.0 are satisfied: GNU General Public License, version 2
+// with the GNU Classpath Exception which is available at
+// https://www.gnu.org/software/classpath/license.html.
+//
+// SPDX-License-Identifier: EPL-2.0 OR GPL-2.0-only WITH Classpath-exception-2.0
+// *****************************************************************************
+
+import * as React from 'react';
+import { MarkdownRenderer, MarkdownRenderResult } from './markdown-renderer';
+import { MarkdownString, MarkdownStringImpl } from '../../common/markdown-rendering/markdown-string';
+import { nls } from '../../common/nls';
+import { FormatType } from '../../common/i18n/localization';
+
+export interface MarkdownProps {
+    /**
+     * The markdown content to render. Can be a string, a MarkdownString, or undefined.
+     * If undefined or empty, an empty div will be rendered.
+     */
+    markdown?: string | MarkdownString;
+
+    /**
+     * The MarkdownRenderer instance to use for rendering.
+     */
+    markdownRenderer: MarkdownRenderer;
+
+    /**
+     * Additional CSS class name(s) to apply to the container element.
+     */
+    className?: string;
+
+    /**
+     * Options to pass to MarkdownStringImpl if markdown is a string.
+     * Common options include:
+     * - supportHtml: Allow HTML in markdown (default: false)
+     * - supportThemeIcons: Allow theme icons (default: false)
+     * - isTrusted: Trust level for command execution (default: false)
+     */
+    markdownOptions?: {
+        supportHtml?: boolean;
+        supportThemeIcons?: boolean;
+        isTrusted?: boolean | { enabledCommands: string[] };
+    };
+
+    /**
+     * Optional callback that receives the rendered HTML element.
+     * Useful for post-processing or adding event listeners.
+     * Receives undefined when content is empty.
+     */
+    onRender?: (element: HTMLElement | undefined) => void;
+}
+
+/**
+ * A React component for rendering markdown content.
+ *
+ * @example Basic usage
+ * ```tsx
+ * const MyComponent = ({ markdownRenderer }: { markdownRenderer: MarkdownRenderer }) => {
+ *   return (
+ *     <Markdown
+ *       markdown="Hello **World**!"
+ *       markdownRenderer={markdownRenderer}
+ *       className="my-content"
+ *       markdownOptions={{ supportHtml: true }}
+ *     />
+ *   );
+ * };
+ * ```
+ *
+ * @example With localized content
+ * ```tsx
+ * const MyComponent = ({ markdownRenderer }: { markdownRenderer: MarkdownRenderer }) => {
+ *   const content = nls.localize('my.key', 'Hello **{0}**!', 'World');
+ *
+ *   return (
+ *     <Markdown
+ *       markdown={content}
+ *       markdownRenderer={markdownRenderer}
+ *       className="my-content"
+ *     />
+ *   );
+ * };
+ * ```
+ *
+ * @example With command links
+ * ```tsx
+ * const content = nls.localize(
+ *   'my.key',
+ *   'Open [settings]({0}) to configure.',
+ *   `command:${CommonCommands.OPEN_PREFERENCES.id}`
+ * );
+ *
+ * return (
+ *   <Markdown
+ *     markdown={content}
+ *     markdownRenderer={markdownRenderer}
+ *     markdownOptions={{
+ *       isTrusted: { enabledCommands: [CommonCommands.OPEN_PREFERENCES.id] }
+ *     }}
+ *   />
+ * );
+ * ```
+ */
+const MarkdownComponent: React.FC<MarkdownProps> = ({
+    markdown,
+    markdownRenderer,
+    className,
+    markdownOptions,
+    onRender
+}) => {
+    const ref = useMarkdown(markdown, markdownRenderer, markdownOptions, onRender);
+    return <div className={className} ref={ref} />;
+};
+MarkdownComponent.displayName = 'Markdown';
+
+export const Markdown = React.memo(MarkdownComponent);
+
+/**
+ * A React hook for rendering markdown content.
+ *
+ * This hook integrates MarkdownRenderer with React's lifecycle,
+ * ensuring that:
+ * - Markdown is rendered only when content or renderer changes
+ * - MarkdownRenderResult is properly disposed when component unmounts
+ * - DOM elements are correctly managed by React
+ * - Event listeners and other imperative DOM operations are preserved
+ *
+ * Returns a ref that should be attached to a DOM element.
+ *
+ * @example Basic usage
+ * ```tsx
+ * const MyComponent = ({ markdownRenderer }: { markdownRenderer: MarkdownRenderer }) => {
+ *   const ref = useMarkdown('Hello **World**!', markdownRenderer, { supportHtml: true });
+ *   return <div className="my-content" ref={ref} />;
+ * };
+ * ```
+ *
+ * @example With localized content
+ * ```tsx
+ * const MyComponent = ({ markdownRenderer }: { markdownRenderer: MarkdownRenderer }) => {
+ *   const content = nls.localize('my.key', 'Hello **{0}**!', 'World');
+ *   const ref = useMarkdown(content, markdownRenderer);
+ *   return <div className="my-content" ref={ref} />;
+ * };
+ * ```
+ */
+export function useMarkdown(
+    markdown: string | MarkdownString | undefined,
+    markdownRenderer: MarkdownRenderer,
+    markdownOptions?: MarkdownProps['markdownOptions'],
+    onRender?: (element: HTMLElement | undefined) => void
+): React.RefObject<HTMLDivElement> {
+    // eslint-disable-next-line no-null/no-null
+    const containerRef = React.useRef<HTMLDivElement>(null);
+    const renderResultRef = React.useRef<MarkdownRenderResult | undefined>();
+
+    const renderedElement = React.useMemo(() => {
+        renderResultRef.current?.dispose();
+        renderResultRef.current = undefined;
+
+        if (!markdown || (typeof markdown === 'string' && markdown.trim() === '')) {
+            return undefined;
+        }
+
+        const markdownString = typeof markdown === 'string'
+            ? new MarkdownStringImpl(markdown, markdownOptions)
+            : markdown;
+
+        const rendered = markdownRenderer.render(markdownString);
+        renderResultRef.current = rendered;
+
+        return rendered.element;
+    }, [markdown, markdownRenderer, markdownOptions]);
+
+    React.useEffect(() => {
+        if (containerRef.current && renderedElement) {
+            containerRef.current.replaceChildren(renderedElement);
+            onRender?.(renderedElement);
+        } else if (containerRef.current && !renderedElement) {
+            containerRef.current.replaceChildren();
+            onRender?.(undefined);
+        }
+    }, [renderedElement, onRender]);
+
+    React.useEffect(() => () => {
+        renderResultRef.current?.dispose();
+    }, []);
+
+    return containerRef;
+}
+
+export interface LocalizedMarkdownProps extends MarkdownProps {
+    /**
+     * The localization key for the markdown content.
+     */
+    localizationKey: string;
+
+    /**
+     * The default markdown content (in English) with placeholders.
+     * Use {0}, {1}, etc. for parameter substitution.
+     */
+    defaultMarkdown: string;
+
+    /**
+     * Arguments to substitute into the markdown template.
+     * Can be strings, numbers, booleans, or undefined.
+     */
+    args?: FormatType[];
+}
+
+/**
+ * A React component that combines localization with markdown rendering.
+ *
+ * This component automatically handles the localization of markdown content using `nls.localize`
+ * and then renders it using the Markdown component.
+ *
+ * @example Basic usage
+ * ```tsx
+ * <LocalizedMarkdown
+ *   localizationKey="theia/mypackage/welcome"
+ *   defaultMarkdown="Welcome to **Theia**!"
+ *   markdownRenderer={this.markdownRenderer}
+ *   className="welcome-message"
+ * />
+ * ```
+ *
+ * @example With parameters
+ * ```tsx
+ * <LocalizedMarkdown
+ *   localizationKey="theia/mypackage/greeting"
+ *   defaultMarkdown="Hello **{0}**! You have {1} new messages."
+ *   args={['Alice', 5]}
+ *   markdownRenderer={this.markdownRenderer}
+ * />
+ * ```
+ *
+ * @example With command links
+ * ```tsx
+ * <LocalizedMarkdown
+ *   localizationKey="theia/mypackage/settings"
+ *   defaultMarkdown="Open [settings]({0}) to configure."
+ *   args={[`command:${CommonCommands.OPEN_PREFERENCES.id}`]}
+ *   markdownRenderer={this.markdownRenderer}
+ *   markdownOptions={{
+ *     isTrusted: { enabledCommands: [CommonCommands.OPEN_PREFERENCES.id] }
+ *   }}
+ * />
+ * ```
+ */
+export const LocalizedMarkdown: React.FC<LocalizedMarkdownProps> = ({
+    localizationKey,
+    defaultMarkdown,
+    args = [],
+    markdownRenderer,
+    className,
+    markdownOptions,
+    onRender
+}) => {
+    const localizedMarkdown = React.useMemo(
+        () => nls.localize(localizationKey, defaultMarkdown, ...args),
+        [localizationKey, defaultMarkdown, ...args]
+    );
+
+    return (
+        <Markdown
+            markdown={localizedMarkdown}
+            markdownRenderer={markdownRenderer}
+            className={className}
+            markdownOptions={markdownOptions}
+            onRender={onRender}
+        />
+    );
+};
+LocalizedMarkdown.displayName = 'LocalizedMarkdown';

package/src/browser/shell/tab-bars.ts

@@ -183,11 +183,9 @@ export class TabBarRenderer extends TabBar.Renderer {
             ? nls.localizeByDefault('Unpin')
             : nls.localizeByDefault('Close');
 
-        const hover = isHorizontal && this.corePreferences?.['window.tabbar.enhancedPreview'] === 'classic'
-            ? { title: title.caption }
-            : {
-                onmouseenter: this.handleMouseEnterEvent
-            };
+        const hover = {
+            onmouseenter: this.handleMouseEnterEvent
+        };
 
         const tabLabel = h.div(
             { className: 'theia-tab-icon-label' },
@@ -550,7 +548,7 @@ export class TabBarRenderer extends TabBar.Renderer {
         return h.div({ className: baseClassName, style }, data.title.iconLabel);
     }
 
-    protected renderEnhancedPreview = (title: Title<Widget>) => {
+    protected renderEnhancedPreview(title: Title<Widget>): HTMLDivElement {
         const hoverBox = document.createElement('div');
         hoverBox.classList.add('theia-horizontal-tabBar-hover-div');
         const labelElement = document.createElement('p');
@@ -625,26 +623,26 @@ export class TabBarRenderer extends TabBar.Renderer {
     }
 
     protected handleMouseEnterEvent = (event: MouseEvent) => {
-        if (this.tabBar && this.hoverService && event.currentTarget instanceof HTMLElement) {
-            const id = event.currentTarget.id;
-            const title = this.tabBar.titles.find(t => this.createTabId(t) === id);
-            if (title) {
-                if (this.tabBar.orientation === 'horizontal') {
-                    this.hoverService.requestHover({
-                        content: this.renderEnhancedPreview(title),
-                        target: event.currentTarget,
-                        position: 'bottom',
-                        cssClasses: ['extended-tab-preview'],
-                        visualPreview: this.corePreferences?.['window.tabbar.enhancedPreview'] === 'visual' ? width => this.renderVisualPreview(width, title) : undefined
-                    });
-                } else if (title.caption) {
-                    this.hoverService.requestHover({
-                        content: title.caption,
-                        target: event.currentTarget,
-                        position: 'right'
-                    });
-                }
-            }
+        if (!this.tabBar || !this.hoverService || !(event.currentTarget instanceof HTMLElement)) { return; }
+        const id = event.currentTarget.id;
+        const title = this.tabBar.titles.find(t => this.createTabId(t) === id);
+        if (!title) { return; }
+        if (this.tabBar.orientation === 'horizontal' && this.corePreferences?.['window.tabbar.enhancedPreview'] !== 'classic' && EnhancedPreviewWidget.is(title.owner)) {
+            this.hoverService.requestHover({
+                content: this.renderEnhancedPreview(title),
+                target: event.currentTarget,
+                position: 'bottom',
+                cssClasses: ['extended-tab-preview'],
+                visualPreview: this.corePreferences?.['window.tabbar.enhancedPreview'] === 'visual' ? width => this.renderVisualPreview(width, title) : undefined
+            });
+        } else if (title.caption) {
+            const position = this.tabBar.orientation === 'horizontal' ? 'bottom' : 'right';
+            const tooltip = ArrayUtils.coalesce([title.caption, ...this.getDecorationData(title, 'tooltip')]).join(' - ');
+            this.hoverService.requestHover({
+                content: tooltip,
+                target: event.currentTarget,
+                position
+            });
         }
     };
 

package/src/browser/widgets/select-component.tsx

@@ -266,7 +266,7 @@ export class SelectComponent extends React.Component<SelectComponentProps, Selec
                 this.selectOption(selected, this.props.options[selected]);
             }
         } else if (ev.key === 'Escape' || ev.key === 'Tab') {
-            this.hide();
+            this.hide(undefined, true);
         }
         ev.stopPropagation();
         ev.nativeEvent.stopImmediatePropagation();
@@ -290,7 +290,7 @@ export class SelectComponent extends React.Component<SelectComponentProps, Selec
         }
     }
 
-    protected hide(index?: number): void {
+    protected hide(index?: number, releaseFocus = false): void {
         const selectedIndex = index === undefined ? this.state.original : index;
         this.setState({
             dimensions: undefined,
@@ -298,6 +298,10 @@ export class SelectComponent extends React.Component<SelectComponentProps, Selec
             original: selectedIndex,
             hover: selectedIndex
         });
+        // Force releasing focus of the select element to allow closing via escape later on
+        if (releaseFocus && document.activeElement && document.activeElement === this.fieldRef.current) {
+            this.fieldRef.current.blur();
+        }
     }
 
     protected renderDropdown(): React.ReactNode {

package/src/browser/widgets/widget.ts

@@ -121,6 +121,12 @@ export class BaseWidget extends Widget implements PreviewableWidget {
         super(options);
     }
 
+    override get isVisible(): boolean {
+        // Reverted to @lumino/widgets pre-2.7.0 behavior using the IsVisible flag instead of the recursive parent check.
+        // Theia relies on this flag-based implementation and we need to transition to the new behavior in a follow-up (GH-16585)
+        return this.testFlag(Widget.Flag.IsVisible);
+    }
+
     override dispose(): void {
         if (this.isDisposed) {
             return;

package/src/common/markdown-rendering/markdown-string.ts

@@ -57,7 +57,7 @@ export class MarkdownStringImpl implements MarkdownString {
 
     constructor(
         value: string = '',
-        isTrustedOrOptions: boolean | { isTrusted?: boolean; supportThemeIcons?: boolean; supportHtml?: boolean } = false,
+        isTrustedOrOptions: boolean | { isTrusted?: boolean | MarkdownStringTrustedOptions; supportThemeIcons?: boolean; supportHtml?: boolean } = false,
     ) {
         this.value = value;
         if (typeof this.value !== 'string') {

package/src/common/theme.ts

@@ -47,11 +47,24 @@ export interface ThemeColor {
     readonly id: string;
 }
 
+// Copied from https://github.com/microsoft/vscode/blob/1.106.1/src/vs/base/common/themables.ts
+export function isThemeColor(obj: unknown): obj is ThemeColor {
+    return !!obj && typeof obj === 'object' && typeof (<ThemeColor>obj).id === 'string';
+}
+
 export interface ThemeIcon {
     readonly id: string;
     readonly color?: ThemeColor;
 }
 
+// Copied and modified from https://github.com/microsoft/vscode/blob/1.106.1/src/vs/base/common/themables.ts
+export function isThemeIcon(obj: unknown): obj is ThemeIcon {
+    return !!obj &&
+        typeof obj === 'object' &&
+        typeof (<ThemeIcon>obj).id === 'string' &&
+        (typeof (<ThemeIcon>obj).color === 'undefined' || isThemeColor((<ThemeIcon>obj).color));
+}
+
 export interface IconDefinition {
     font?: IconFontContribution; // undefined for the default font (codicon)
     fontCharacter: string;