@theia/getting-started 1.75.0-next.21 → 1.75.0-next.28

package/src/browser/getting-started-contribution.ts

@@ -16,8 +16,8 @@
 
 import { injectable, inject } from '@theia/core/shared/inversify';
 import {
-    ArrayUtils, CommandRegistry, MenuModelRegistry, nls, PreferenceContribution,
-    PreferenceDataProperty, PreferenceSchemaService, PreferenceService
+    ArrayUtils, CommandRegistry, MenuModelRegistry, MessageService, nls, PreferenceContribution,
+    PreferenceDataProperty, PreferenceSchemaService, PreferenceService, QuickInputService, QuickPickItem
 } from '@theia/core/lib/common';
 import { CommonCommands, CommonMenus, AbstractViewContribution, FrontendApplicationContribution, FrontendApplication } from '@theia/core/lib/browser';
 import { EditorManager } from '@theia/editor/lib/browser/editor-manager';
@@ -27,6 +27,11 @@ import { FrontendApplicationStateService } from '@theia/core/lib/browser/fronten
 import { WorkspaceService } from '@theia/workspace/lib/browser';
 import { FrontendApplicationConfigProvider } from '@theia/core/lib/browser/frontend-application-config-provider';
 import { URI as VSCodeURI } from '@theia/core/shared/vscode-uri';
+import { ColorContribution } from '@theia/core/lib/browser/color-application-contribution';
+import { ColorRegistry } from '@theia/core/lib/browser/color-registry';
+import { Color } from '@theia/core/lib/common/color';
+import { WalkthroughService } from './walkthrough-service';
+import { WalkthroughCommands } from '../common/walkthrough-commands';
 
 /**
  * Triggers opening the `GettingStartedWidget`.
@@ -36,8 +41,16 @@ export const GettingStartedCommand = {
     label: GettingStartedWidget.LABEL
 };
 
+/**
+ * How a walkthrough can be referenced when opening it through a command.
+ * The object form is what VS Code's `workbench.action.openWalkthrough` accepts, e.g. from a `command:` link
+ * in a step description.
+ */
+export type WalkthroughReference = string | { category?: string; step?: string };
+
 @injectable()
-export class GettingStartedContribution extends AbstractViewContribution<GettingStartedWidget> implements FrontendApplicationContribution, PreferenceContribution {
+export class GettingStartedContribution extends AbstractViewContribution<GettingStartedWidget>
+    implements FrontendApplicationContribution, PreferenceContribution, ColorContribution {
 
     @inject(CommandRegistry)
     protected readonly commandRegistry: CommandRegistry;
@@ -57,6 +70,15 @@ export class GettingStartedContribution extends AbstractViewContribution<Getting
     @inject(WorkspaceService)
     protected readonly workspaceService: WorkspaceService;
 
+    @inject(WalkthroughService)
+    protected readonly walkthroughService: WalkthroughService;
+
+    @inject(QuickInputService)
+    protected readonly quickInputService: QuickInputService;
+
+    @inject(MessageService)
+    protected readonly messageService: MessageService;
+
     constructor() {
         super({
             widgetId: GettingStartedWidget.ID,
@@ -131,6 +153,71 @@ export class GettingStartedContribution extends AbstractViewContribution<Getting
         registry.registerCommand(GettingStartedCommand, {
             execute: () => this.openView({ reveal: true, activate: true }),
         });
+        registry.registerCommand(WalkthroughCommands.OPEN_WALKTHROUGH, {
+            execute: (walkthrough?: WalkthroughReference) => this.openWalkthrough(walkthrough)
+        });
+        registry.registerCommand(WalkthroughCommands.OPEN_WALKTHROUGH_VSCODE, {
+            execute: (walkthrough?: WalkthroughReference) => this.openWalkthrough(walkthrough)
+        });
+        registry.registerAlias(WalkthroughCommands.OPEN_WALKTHROUGH_VSCODE.id, WalkthroughCommands.OPEN_WALKTHROUGH.id);
+        registry.registerCommand(WalkthroughCommands.RESET_WALKTHROUGH_PROGRESS, {
+            execute: async (walkthroughId?: string) => {
+                const id = walkthroughId ?? await this.pickWalkthrough();
+                if (id) {
+                    await this.walkthroughService.resetProgress(id);
+                }
+            }
+        });
+    }
+
+    /**
+     * Open the welcome view and, if a walkthrough is given, select it.
+     * Accepts both a plain id and the argument object that VS Code's `workbench.action.openWalkthrough` uses.
+     * Without a walkthrough, the available ones are offered for selection.
+     */
+    protected async openWalkthrough(walkthrough?: WalkthroughReference): Promise<void> {
+        const requestedId = typeof walkthrough === 'string' ? walkthrough : walkthrough?.category;
+        const walkthroughId = requestedId ?? await this.pickWalkthrough();
+        if (!walkthroughId) {
+            return;
+        }
+        // The selection is applied before the view opens so that its first render already shows the
+        // walkthrough, instead of briefly showing the regular welcome content.
+        this.walkthroughService.selectWalkthrough(walkthroughId);
+        const stepId = typeof walkthrough === 'string' ? undefined : walkthrough?.step;
+        if (stepId) {
+            // VS Code qualifies step ids with the walkthrough they belong to.
+            this.walkthroughService.selectStep(stepId.substring(stepId.lastIndexOf('#') + 1));
+        }
+        await this.openView({ reveal: true, activate: true });
+    }
+
+    /**
+     * Let the user choose one of the available walkthroughs, completed ones included.
+     *
+     * @returns the id of the chosen walkthrough, or `undefined` if there is nothing to choose or the user cancelled.
+     */
+    protected async pickWalkthrough(): Promise<string | undefined> {
+        const walkthroughs = this.walkthroughService.getWalkthroughs();
+        if (walkthroughs.length === 0) {
+            this.messageService.info(nls.localize('theia/getting-started/noWalkthroughs', 'No walkthroughs are available.'));
+            return undefined;
+        }
+        const items: QuickPickItem[] = walkthroughs.map(walkthrough => {
+            const { completed, total } = this.walkthroughService.getStepProgress(walkthrough.id);
+            return {
+                id: walkthrough.id,
+                label: walkthrough.title,
+                description: completed === total
+                    ? nls.localizeByDefault('Completed')
+                    : nls.localizeByDefault('{0} of {1}', String(completed), String(total)),
+                detail: walkthrough.description
+            };
+        });
+        const picked = await this.quickInputService.showQuickPick(items, {
+            placeholder: nls.localizeByDefault('Select a walkthrough to open')
+        });
+        return picked?.id;
     }
 
     override registerMenus(menus: MenuModelRegistry): void {
@@ -140,4 +227,53 @@ export class GettingStartedContribution extends AbstractViewContribution<Getting
             order: 'a10'
         });
     }
+
+    registerColors(colors: ColorRegistry): void {
+        colors.register(
+            {
+                id: 'walkthrough.stepTitle.foreground',
+                defaults: { dark: 'foreground', light: 'foreground', hcDark: 'foreground', hcLight: 'foreground' },
+                description: 'Foreground color of walkthrough step titles.'
+            },
+            {
+                id: 'walkthrough.progress.foreground',
+                defaults: {
+                    dark: Color.transparent('foreground', 0.7),
+                    light: Color.transparent('foreground', 0.7),
+                    hcDark: 'foreground',
+                    hcLight: 'foreground'
+                },
+                description: 'Foreground color for walkthrough progress indicators.'
+            },
+            {
+                id: 'walkthrough.card.background',
+                defaults: {
+                    // A foreground tint stays subtle and lightens on dark themes instead of darkening them.
+                    dark: Color.transparent('foreground', 0.04),
+                    light: Color.transparent('foreground', 0.04)
+                },
+                description: 'Background color of the walkthrough cards on the Welcome page.'
+            },
+            {
+                id: 'walkthrough.progress.background',
+                defaults: {
+                    dark: Color.transparent('foreground', 0.2),
+                    light: Color.transparent('foreground', 0.2),
+                    hcDark: 'contrastBorder',
+                    hcLight: 'contrastBorder'
+                },
+                description: 'Background color of the walkthrough progress bar.'
+            },
+            {
+                id: 'walkthrough.stepCompleted.foreground',
+                defaults: {
+                    dark: 'successBackground',
+                    light: 'successBackground',
+                    hcDark: 'successBackground',
+                    hcLight: 'successBackground'
+                },
+                description: 'Foreground color of the indicator marking a walkthrough step as completed.'
+            }
+        );
+    }
 }

package/src/browser/getting-started-frontend-module.ts

@@ -18,17 +18,25 @@ import { GettingStartedContribution } from './getting-started-contribution';
 import { ContainerModule, interfaces } from '@theia/core/shared/inversify';
 import { GettingStartedWidget } from './getting-started-widget';
 import { WidgetFactory, FrontendApplicationContribution, bindViewContribution, noopWidgetStatusBarContribution, WidgetStatusBarContribution } from '@theia/core/lib/browser';
+import { ColorContribution } from '@theia/core/lib/browser/color-application-contribution';
 import { bindGettingStartedPreferences } from '../common/getting-started-preferences';
+import { WalkthroughPluginSupport, WalkthroughService, WalkthroughViewEventSource } from './walkthrough-service';
+import { HostedPluginSupport } from '@theia/plugin-ext/lib/hosted/browser/hosted-plugin';
+import { PluginViewRegistry } from '@theia/plugin-ext/lib/main/browser/view/plugin-view-registry';
 import '../../src/browser/style/index.css';
 
 export default new ContainerModule((bind: interfaces.Bind) => {
     bindViewContribution(bind, GettingStartedContribution);
     bind(FrontendApplicationContribution).toService(GettingStartedContribution);
+    bind(ColorContribution).toService(GettingStartedContribution);
     bind(WidgetStatusBarContribution).toConstantValue(noopWidgetStatusBarContribution(GettingStartedWidget));
     bind(GettingStartedWidget).toSelf();
     bind(WidgetFactory).toDynamicValue(context => ({
         id: GettingStartedWidget.ID,
         createWidget: () => context.container.get<GettingStartedWidget>(GettingStartedWidget),
     })).inSingletonScope();
+    bind(WalkthroughService).toSelf().inSingletonScope();
+    bind(WalkthroughPluginSupport).toService(HostedPluginSupport);
+    bind(WalkthroughViewEventSource).toService(PluginViewRegistry);
     bindGettingStartedPreferences(bind);
 });

package/src/browser/getting-started-widget.spec.tsx

@@ -0,0 +1,88 @@
+// *****************************************************************************
+// Copyright (C) 2026 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
+// *****************************************************************************
+
+/* eslint-disable @typescript-eslint/no-explicit-any */
+
+import * as assert from 'assert';
+import { enableJSDOM } from '@theia/core/lib/browser/test/jsdom';
+
+let disableJSDOM = enableJSDOM();
+
+import { FrontendApplicationConfigProvider } from '@theia/core/lib/browser/frontend-application-config-provider';
+
+/** The configuration lives on `window`, so it has to be set again for every fresh JSDOM instance. */
+function ensureFrontendConfig(): void {
+    try {
+        FrontendApplicationConfigProvider.get();
+    } catch {
+        FrontendApplicationConfigProvider.set({});
+    }
+}
+
+// Some of the modules loaded below read the configuration while they are being loaded.
+ensureFrontendConfig();
+
+import { Walkthrough } from '../common/walkthrough-types';
+import { GettingStartedWidget } from './getting-started-widget';
+
+describe('GettingStartedWidget', () => {
+
+    before(() => {
+        disableJSDOM = enableJSDOM();
+        ensureFrontendConfig();
+    });
+    after(() => disableJSDOM());
+
+    function createWidget(selectedWalkthrough?: Walkthrough): GettingStartedWidget {
+        const widget = new GettingStartedWidget();
+        (widget as any).walkthroughService = { selectedWalkthrough };
+        return widget;
+    }
+
+    function createWalkthrough(title: string): Walkthrough {
+        return { id: 'test.plugin.wt', title, description: 'desc', steps: [], pluginId: 'test.plugin' };
+    }
+
+    describe('title', () => {
+        it('should be the welcome label while no walkthrough is selected', () => {
+            const widget = createWidget();
+
+            (widget as any).updateTitle();
+
+            assert.strictEqual(widget.title.label, GettingStartedWidget.LABEL);
+            assert.strictEqual(widget.title.caption, GettingStartedWidget.LABEL);
+        });
+
+        it('should name the walkthrough that is shown', () => {
+            const widget = createWidget(createWalkthrough('Get Started with Python'));
+
+            (widget as any).updateTitle();
+
+            assert.strictEqual(widget.title.label, 'Walkthrough: Get Started with Python');
+            assert.strictEqual(widget.title.caption, 'Walkthrough: Get Started with Python');
+        });
+
+        it('should return to the welcome label once the walkthrough is closed', () => {
+            const widget = createWidget(createWalkthrough('Some Walkthrough'));
+            (widget as any).updateTitle();
+
+            (widget as any).walkthroughService = { selectedWalkthrough: undefined };
+            (widget as any).updateTitle();
+
+            assert.strictEqual(widget.title.label, GettingStartedWidget.LABEL);
+        });
+    });
+});

package/src/browser/getting-started-widget.tsx

@@ -22,11 +22,16 @@ import { ApplicationInfo, ApplicationServer } from '@theia/core/lib/common/appli
 import { EnvVariablesServer } from '@theia/core/lib/common/env-variables';
 import { nls } from '@theia/core/lib/common/nls';
 import URI from '@theia/core/lib/common/uri';
-import { inject, injectable, postConstruct } from '@theia/core/shared/inversify';
+import { inject, injectable, named, postConstruct } from '@theia/core/shared/inversify';
 import * as React from '@theia/core/shared/react';
 import { KeymapsCommands } from '@theia/keymaps/lib/browser';
 import { WorkspaceCommands, WorkspaceService } from '@theia/workspace/lib/browser';
 import { MarkdownRenderer } from '@theia/core/lib/browser/markdown-rendering/markdown-renderer';
+import { ThemeService } from '@theia/core/lib/browser/theming';
+import { ILogger } from '@theia/core/lib/common/logger';
+import { WalkthroughCommands } from '../common/walkthrough-commands';
+import { WalkthroughService } from './walkthrough-service';
+import { WalkthroughSection } from './walkthrough-section';
 
 /**
  * Default implementation of the `GettingStartedWidget`.
@@ -113,16 +118,28 @@ export class GettingStartedWidget extends ReactWidget {
     @inject(MarkdownRenderer)
     protected readonly markdownRenderer: MarkdownRenderer;
 
+    @inject(WalkthroughService)
+    protected readonly walkthroughService: WalkthroughService;
+
+    @inject(ThemeService)
+    protected readonly themeService: ThemeService;
+
+    @inject(ILogger) @named('getting-started:GettingStartedWidget')
+    protected readonly logger: ILogger;
+
     @postConstruct()
     protected init(): void {
+        // Subscribe before the asynchronous initialization so that a walkthrough selected right after
+        // the widget was created - e.g. by the `walkthrough.open` command - is not missed.
+        this.toDispose.push(this.walkthroughService.onDidChangeWalkthroughs(() => this.refresh()));
+        this.toDispose.push(this.walkthroughService.onDidChangeSelection(() => this.refresh()));
         this.doInit();
     }
 
     protected async doInit(): Promise<void> {
         this.id = GettingStartedWidget.ID;
-        this.title.label = GettingStartedWidget.LABEL;
-        this.title.caption = GettingStartedWidget.LABEL;
         this.title.closable = true;
+        this.updateTitle();
 
         this.applicationInfo = await this.appServer.getApplicationInfo();
         this.recentWorkspaces = await this.workspaceService.recentWorkspaces();
@@ -133,6 +150,24 @@ export class GettingStartedWidget extends ReactWidget {
         this.update();
     }
 
+    protected refresh(): void {
+        this.updateTitle();
+        this.update();
+    }
+
+    /**
+     * Name the widget after the walkthrough it currently shows, so that it can be told apart from the
+     * regular welcome content in the tab bar.
+     */
+    protected updateTitle(): void {
+        const walkthrough = this.walkthroughService.selectedWalkthrough;
+        const label = walkthrough
+            ? nls.localizeByDefault('Walkthrough: {0}', walkthrough.title)
+            : GettingStartedWidget.LABEL;
+        this.title.label = label;
+        this.title.caption = label;
+    }
+
     protected override onActivateRequest(msg: Message): void {
         super.onActivateRequest(msg);
         const elArr = this.node.getElementsByTagName('a');
@@ -145,6 +180,9 @@ export class GettingStartedWidget extends ReactWidget {
      * Render the content of the widget.
      */
     protected render(): React.ReactNode {
+        if (this.walkthroughService.selectedWalkthrough) {
+            return this.renderSelectedWalkthrough();
+        }
         return <div className='gs-container'>
             <div className='gs-content-container'>
                 {this.aiIsIncluded &&
@@ -176,6 +214,11 @@ export class GettingStartedWidget extends ReactWidget {
                         {this.renderSettings()}
                     </div>
                 </div>
+                <div className='flex-grid'>
+                    <div className='col'>
+                        {this.renderWalkthroughs()}
+                    </div>
+                </div>
                 <div className='flex-grid'>
                     <div className='col'>
                         {this.renderHelp()}
@@ -193,6 +236,20 @@ export class GettingStartedWidget extends ReactWidget {
         </div>;
     }
 
+    protected showAllWalkthroughs = () => {
+        this.commandRegistry.executeCommand(WalkthroughCommands.OPEN_WALKTHROUGH.id);
+    };
+
+    /**
+     * Render the selected walkthrough on its own, taking over the whole view.
+     * The regular welcome content is restored once the walkthrough is closed.
+     */
+    protected renderSelectedWalkthrough(): React.ReactNode {
+        return <div className='gs-container gs-walkthrough-container'>
+            {this.renderWalkthroughs()}
+        </div>;
+    }
+
     /**
      * Render the widget header.
      * Renders the title `{applicationName} Getting Started`.
@@ -350,6 +407,16 @@ export class GettingStartedWidget extends ReactWidget {
         </div>;
     }
 
+    protected renderWalkthroughs(): React.ReactNode {
+        return <WalkthroughSection
+            walkthroughService={this.walkthroughService}
+            markdownRenderer={this.markdownRenderer}
+            themeService={this.themeService}
+            logger={this.logger}
+            onShowAll={this.showAllWalkthroughs}
+        />;
+    }
+
     /**
      * Render the help section.
      */