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

package/src/browser/style/index.css

@@ -142,3 +142,282 @@ body {
     box-shadow: 0 0 15px rgba(0, 0, 0, 0.4);
   }
 }
+
+/* Walkthrough styles */
+
+/* The cards form a quiet single column: card-like blocks, but without borders. */
+.gs-walkthrough-cards {
+  display: flex;
+  flex-direction: column;
+  gap: var(--theia-ui-padding);
+  margin-top: var(--theia-ui-padding);
+  max-width: 640px;
+}
+
+.gs-walkthrough-card {
+  padding: calc(var(--theia-ui-padding) * 1.5) calc(var(--theia-ui-padding) * 2);
+  border-radius: calc(var(--theia-ui-padding) / 2);
+  cursor: pointer;
+  background-color: var(--theia-walkthrough-card-background);
+  /* Only set in high contrast themes, where the card has no background to delimit it. */
+  border: var(--theia-border-width) solid var(--theia-contrastBorder);
+}
+
+/*
+ * High contrast themes define none of the `welcomePage`, `list` and `secondaryButton` hover colors, which
+ * leaves the hover feedback below inert. `contrastActiveBorder` is set in those themes only and is the
+ * established affordance for it, see `dockpanel.css` in `@theia/core`.
+ */
+.gs-walkthrough-card:hover {
+  background-color: var(--theia-welcomePage-buttonHoverBackground);
+  outline: var(--theia-border-width) dashed var(--theia-contrastActiveBorder);
+  outline-offset: calc(var(--theia-border-width) * -1);
+}
+
+.gs-walkthrough-card:focus {
+  outline: var(--theia-border-width) solid var(--theia-focusBorder);
+}
+
+.gs-walkthrough-card-header {
+  display: flex;
+  align-items: center;
+  gap: calc(var(--theia-ui-padding) / 2);
+  margin-bottom: calc(var(--theia-ui-padding) / 2);
+}
+
+.gs-walkthrough-card-title {
+  font-size: var(--theia-ui-font-size1);
+  font-weight: 600;
+  margin: 0;
+}
+
+.gs-walkthrough-icon {
+  font-size: var(--theia-ui-font-size1);
+  flex: 0 0 auto;
+}
+
+/* The extension icon is an image, so it needs an explicit box to sit in. */
+.gs-walkthrough-plugin-icon {
+  width: var(--theia-icon-size);
+  height: var(--theia-icon-size);
+  object-fit: contain;
+}
+
+/* Kept to a single line so that every card stays the same height. */
+.gs-walkthrough-card-description {
+  color: var(--theia-descriptionForeground);
+  font-size: var(--theia-ui-font-size0);
+  margin: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.gs-walkthrough-card-progress {
+  display: flex;
+  align-items: center;
+  gap: var(--theia-ui-padding);
+  margin-top: var(--theia-ui-padding);
+}
+
+.gs-walkthrough-progress-bar {
+  flex: 0 1 180px;
+  height: calc(var(--theia-ui-padding) / 3);
+  background-color: var(--theia-walkthrough-progress-background);
+  border-radius: calc(var(--theia-ui-padding) / 3);
+  overflow: hidden;
+}
+
+.gs-walkthrough-progress-fill {
+  height: 100%;
+  /* The fallback keeps the filled part visible should a theme leave `progressBar.background` unset. */
+  background-color: var(--theia-progressBar-background, var(--theia-focusBorder));
+  border-radius: calc(var(--theia-ui-padding) / 3);
+  transition: width 0.3s ease;
+}
+
+.gs-walkthrough-progress-text {
+  color: var(--theia-walkthrough-progress-foreground);
+  font-size: var(--theia-ui-font-size0);
+  white-space: nowrap;
+}
+
+.gs-walkthrough-more {
+  display: inline-block;
+  margin-top: calc(var(--theia-ui-padding) / 2);
+  padding-left: var(--theia-ui-padding);
+  cursor: pointer;
+}
+
+/* A selected walkthrough takes over the whole welcome view. */
+.gs-walkthrough-container {
+  padding: calc(var(--theia-ui-padding) * 6);
+  overflow: auto;
+}
+
+.gs-walkthrough-detail {
+  display: flex;
+  flex-direction: column;
+  height: 100%;
+}
+
+.gs-walkthrough-detail-header {
+  margin-bottom: calc(var(--theia-ui-padding) * 4);
+}
+
+.gs-walkthrough-detail-body {
+  display: flex;
+  flex: 1;
+  flex-wrap: wrap;
+  align-items: flex-start;
+  gap: calc(var(--theia-ui-padding) * 4);
+  min-height: 0;
+}
+
+.gs-walkthrough-back-link {
+  cursor: pointer;
+  display: inline-flex;
+  align-items: center;
+  gap: calc(var(--theia-ui-padding) / 2);
+  margin-bottom: calc(var(--theia-ui-padding) * 6);
+  font-weight: 500;
+  text-decoration: none;
+}
+
+/*
+ * The label carries the underline rather than the link itself: text decoration of a flex container is not
+ * propagated to its flex items, and underlining the arrow icon along with the label would look off anyway.
+ */
+.gs-walkthrough-back-link:hover .gs-walkthrough-back-label {
+  text-decoration: underline;
+}
+
+.gs-walkthrough-detail-title {
+  display: flex;
+  align-items: center;
+  gap: var(--theia-ui-padding);
+  font-size: var(--theia-ui-font-size3);
+  font-weight: 600;
+  margin: 0;
+}
+
+.gs-walkthrough-detail-title .gs-walkthrough-plugin-icon {
+  width: var(--theia-ui-font-size3);
+  height: var(--theia-ui-font-size3);
+}
+
+.gs-walkthrough-detail-description {
+  color: var(--theia-descriptionForeground);
+  margin: var(--theia-ui-padding) 0 0 0;
+}
+
+.gs-walkthrough-steps {
+  display: flex;
+  flex: 1 1 280px;
+  flex-direction: column;
+  gap: calc(var(--theia-ui-padding) / 2);
+  max-width: 420px;
+}
+
+.gs-walkthrough-step-item {
+  display: flex;
+  align-items: center;
+  gap: var(--theia-ui-padding);
+  padding: var(--theia-ui-padding);
+  border-radius: calc(var(--theia-ui-padding) / 2);
+  border-left: calc(var(--theia-border-width) * 2) solid transparent;
+  cursor: pointer;
+}
+
+.gs-walkthrough-step-item:hover {
+  background-color: var(--theia-list-hoverBackground);
+  outline: var(--theia-border-width) dashed var(--theia-contrastActiveBorder);
+  outline-offset: calc(var(--theia-border-width) * -1);
+}
+
+/*
+ * The selected step keeps the regular foreground colors: the active selection background does not
+ * guarantee readable contrast for the step title in every theme, so the selection is conveyed by a
+ * quiet background plus an accent border instead.
+ */
+.gs-walkthrough-step-item.selected {
+  background-color: var(--theia-list-inactiveSelectionBackground);
+  border-left-color: var(--theia-focusBorder);
+}
+
+.gs-walkthrough-step-item.completed .gs-walkthrough-step-icon {
+  color: var(--theia-walkthrough-stepCompleted-foreground);
+}
+
+.gs-walkthrough-step-item .gs-walkthrough-step-icon:hover {
+  color: var(--theia-focusBorder);
+}
+
+.gs-walkthrough-step-icon {
+  font-size: var(--theia-ui-font-size2);
+  cursor: pointer;
+}
+
+.gs-walkthrough-step-title {
+  color: var(--theia-walkthrough-stepTitle-foreground);
+  font-weight: 500;
+}
+
+.gs-walkthrough-step-content {
+  flex: 2 1 360px;
+  min-width: 0;
+  padding: calc(var(--theia-ui-padding) * 2);
+  border: var(--theia-border-width) solid var(--theia-panel-border);
+  border-radius: var(--theia-ui-padding);
+}
+
+.gs-walkthrough-step-detail h3 {
+  margin-top: 0;
+}
+
+.gs-walkthrough-step-detail p {
+  color: var(--theia-descriptionForeground);
+  line-height: var(--theia-content-line-height);
+}
+
+.gs-walkthrough-mark-all-done {
+  align-self: flex-start;
+  margin: var(--theia-ui-padding) 0 0 0;
+}
+
+/* `.theia-button` brings no hover state of its own. */
+.gs-walkthrough-mark-all-done:hover:not([disabled]) {
+  background-color: var(--theia-secondaryButton-hoverBackground);
+  outline: var(--theia-border-width) dashed var(--theia-contrastActiveBorder);
+}
+
+.gs-walkthrough-media-image {
+  max-width: 100%;
+  border-radius: calc(var(--theia-ui-padding) / 2);
+  margin-top: var(--theia-ui-padding);
+}
+
+.gs-walkthrough-media-markdown {
+  margin-top: var(--theia-ui-padding);
+}
+
+.gs-walkthrough-step-description {
+  line-height: var(--theia-content-line-height);
+}
+
+.gs-walkthrough-step-description a {
+  color: var(--theia-textLink-foreground);
+  text-decoration: none;
+}
+
+.gs-walkthrough-step-description a:hover {
+  text-decoration: underline;
+}
+
+.gs-walkthrough-step-description code {
+  font-family: var(--theia-code-font-family);
+  font-size: var(--theia-code-font-size);
+  background: var(--theia-textCodeBlock-background);
+  padding: 0 calc(var(--theia-ui-padding) / 2);
+  border-radius: calc(var(--theia-ui-padding) / 3);
+}

package/src/browser/walkthrough-card.spec.tsx

@@ -0,0 +1,247 @@
+// *****************************************************************************
+// 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
+// *****************************************************************************
+
+import * as assert from 'assert';
+import * as React from 'react';
+import { enableJSDOM } from '@theia/core/lib/browser/test/jsdom';
+
+let disableJSDOM = enableJSDOM();
+
+import { createRoot, Root } from 'react-dom/client';
+import { Walkthrough, WalkthroughStep } from '../common/walkthrough-types';
+import { WalkthroughCard } from './walkthrough-card';
+
+function createMockStep(overrides?: Partial<WalkthroughStep>): WalkthroughStep {
+    return {
+        id: 'step-1',
+        title: 'Test Step',
+        description: 'A test step description',
+        isComplete: false,
+        ...overrides
+    };
+}
+
+function createMockWalkthrough(overrides?: Partial<Walkthrough>): Walkthrough {
+    return {
+        id: 'test-walkthrough',
+        title: 'Test Walkthrough',
+        description: 'A test walkthrough description',
+        steps: [
+            createMockStep({ id: 'step-1', title: 'First Step' }),
+            createMockStep({ id: 'step-2', title: 'Second Step' }),
+            createMockStep({ id: 'step-3', title: 'Third Step' })
+        ],
+        pluginId: 'test.plugin',
+        ...overrides
+    };
+}
+
+describe('WalkthroughCard', () => {
+    let container: HTMLElement;
+    let root: Root;
+
+    before(() => disableJSDOM = enableJSDOM());
+    after(() => disableJSDOM());
+
+    beforeEach(() => {
+        container = document.createElement('div');
+        document.body.appendChild(container);
+        root = createRoot(container);
+    });
+
+    afterEach(() => {
+        root.unmount();
+        document.body.removeChild(container);
+    });
+
+    it('should render walkthrough title and description', done => {
+        const walkthrough = createMockWalkthrough({
+            title: 'My Walkthrough',
+            description: 'My description'
+        });
+
+        root.render(
+            <WalkthroughCard walkthrough={walkthrough} onSelect={() => { }} />
+        );
+
+        setTimeout(() => {
+            const title = container.querySelector('.gs-walkthrough-card-title');
+            assert.ok(title, 'Title element should exist');
+            assert.ok(title?.textContent?.includes('My Walkthrough'), 'Should contain the walkthrough title');
+
+            const description = container.querySelector('.gs-walkthrough-card-description');
+            assert.ok(description, 'Description element should exist');
+            assert.ok(description?.textContent?.includes('My description'), 'Should contain the walkthrough description');
+            done();
+        }, 50);
+    });
+
+    it('should display progress bar with correct percentage', done => {
+        const walkthrough = createMockWalkthrough({
+            steps: [
+                createMockStep({ id: 's1', isComplete: true }),
+                createMockStep({ id: 's2', isComplete: false }),
+                createMockStep({ id: 's3', isComplete: false })
+            ]
+        });
+
+        root.render(
+            <WalkthroughCard walkthrough={walkthrough} onSelect={() => { }} />
+        );
+
+        setTimeout(() => {
+            const progressFill = container.querySelector('.gs-walkthrough-progress-fill') as HTMLElement;
+            assert.ok(progressFill, 'Progress fill element should exist');
+            const expectedWidth = `${(1 / 3) * 100}%`;
+            assert.strictEqual(progressFill.style.width, expectedWidth, 'Progress fill should reflect 1 of 3 steps');
+
+            const progressText = container.querySelector('.gs-walkthrough-progress-text');
+            assert.ok(progressText, 'Progress text should exist');
+            assert.ok(progressText?.textContent?.includes('1'), 'Should show completed count');
+            assert.ok(progressText?.textContent?.includes('3'), 'Should show total count');
+            done();
+        }, 50);
+    });
+
+    it('should call onSelect when card is clicked', done => {
+        const walkthrough = createMockWalkthrough();
+        let selectedWalkthrough: Walkthrough | undefined;
+
+        root.render(
+            <WalkthroughCard walkthrough={walkthrough} onSelect={w => { selectedWalkthrough = w; }} />
+        );
+
+        setTimeout(() => {
+            const card = container.querySelector('.gs-walkthrough-card') as HTMLElement;
+            assert.ok(card, 'Card element should exist');
+            card.click();
+
+            setTimeout(() => {
+                assert.ok(selectedWalkthrough, 'onSelect should have been called');
+                assert.strictEqual(selectedWalkthrough?.id, walkthrough.id, 'Should pass the walkthrough to onSelect');
+                done();
+            }, 50);
+        }, 50);
+    });
+
+    it('should render icon when walkthrough.icon is provided', done => {
+        const walkthrough = createMockWalkthrough({ icon: 'play' });
+
+        root.render(
+            <WalkthroughCard walkthrough={walkthrough} onSelect={() => { }} />
+        );
+
+        setTimeout(() => {
+            const icon = container.querySelector('.gs-walkthrough-icon');
+            assert.ok(icon, 'Icon element should exist');
+            assert.ok(icon?.classList.contains('codicon-play'), 'Should have the codicon-play class');
+            done();
+        }, 50);
+    });
+
+    it('should not render icon when walkthrough.icon is not provided', done => {
+        const walkthrough = createMockWalkthrough({ icon: undefined });
+
+        root.render(
+            <WalkthroughCard walkthrough={walkthrough} onSelect={() => { }} />
+        );
+
+        setTimeout(() => {
+            const icon = container.querySelector('.gs-walkthrough-icon');
+            // eslint-disable-next-line no-null/no-null
+            assert.strictEqual(icon, null, 'Icon element should not exist');
+            done();
+        }, 50);
+    });
+
+    it('should show 0% progress when no steps are complete', done => {
+        const walkthrough = createMockWalkthrough();
+
+        root.render(
+            <WalkthroughCard walkthrough={walkthrough} onSelect={() => { }} />
+        );
+
+        setTimeout(() => {
+            const progressFill = container.querySelector('.gs-walkthrough-progress-fill') as HTMLElement;
+            assert.ok(progressFill, 'Progress fill element should exist');
+            assert.strictEqual(progressFill.style.width, '0%', 'Progress should be 0%');
+            done();
+        }, 50);
+    });
+
+    it('should show 100% progress when all steps are complete', done => {
+        const walkthrough = createMockWalkthrough({
+            steps: [
+                createMockStep({ id: 's1', isComplete: true }),
+                createMockStep({ id: 's2', isComplete: true }),
+            ]
+        });
+
+        root.render(
+            <WalkthroughCard walkthrough={walkthrough} onSelect={() => { }} />
+        );
+
+        setTimeout(() => {
+            const progressFill = container.querySelector('.gs-walkthrough-progress-fill') as HTMLElement;
+            assert.ok(progressFill, 'Progress fill element should exist');
+            assert.strictEqual(progressFill.style.width, '100%', 'Progress should be 100%');
+            done();
+        }, 50);
+    });
+    it('should fall back to the extension icon when the walkthrough contributes none', done => {
+        const walkthrough = createMockWalkthrough({ icon: undefined, pluginIcon: 'http://localhost/icon.png' });
+
+        root.render(
+            <WalkthroughCard walkthrough={walkthrough} onSelect={() => { }} />
+        );
+
+        setTimeout(() => {
+            const icon = container.querySelector('.gs-walkthrough-plugin-icon') as HTMLImageElement;
+            assert.ok(icon, 'The extension icon should be rendered');
+            assert.strictEqual(icon.getAttribute('src'), 'http://localhost/icon.png', 'It should use the resolved icon URL');
+            done();
+        }, 50);
+    });
+
+    it('should prefer a contributed codicon over the extension icon', done => {
+        const walkthrough = createMockWalkthrough({ icon: 'play', pluginIcon: 'http://localhost/icon.png' });
+
+        root.render(
+            <WalkthroughCard walkthrough={walkthrough} onSelect={() => { }} />
+        );
+
+        setTimeout(() => {
+            assert.ok(container.querySelector('.codicon-play'), 'The contributed codicon should win');
+            // eslint-disable-next-line no-null/no-null
+            assert.strictEqual(container.querySelector('.gs-walkthrough-plugin-icon'), null, 'The extension icon should be skipped');
+            done();
+        }, 50);
+    });
+
+    it('should render no icon when neither is available', done => {
+        const walkthrough = createMockWalkthrough({ icon: undefined, pluginIcon: undefined });
+
+        root.render(
+            <WalkthroughCard walkthrough={walkthrough} onSelect={() => { }} />
+        );
+
+        setTimeout(() => {
+            // eslint-disable-next-line no-null/no-null
+            assert.strictEqual(container.querySelector('.gs-walkthrough-icon'), null, 'No icon element should exist');
+            done();
+        }, 50);
+    });
+});

package/src/browser/walkthrough-card.tsx

@@ -0,0 +1,62 @@
+// *****************************************************************************
+// 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
+// *****************************************************************************
+
+import { nls } from '@theia/core/lib/common/nls';
+import * as React from '@theia/core/shared/react';
+import { Walkthrough } from '../common/walkthrough-types';
+import { WalkthroughIcon } from './walkthrough-icon';
+
+export interface WalkthroughCardProps {
+    walkthrough: Walkthrough;
+    onSelect: (walkthrough: Walkthrough) => void;
+}
+
+export function WalkthroughCard(props: WalkthroughCardProps): React.ReactElement {
+    const { walkthrough, onSelect } = props;
+    const completedSteps = walkthrough.steps.filter(s => s.isComplete).length;
+    const totalSteps = walkthrough.steps.length;
+
+    return (
+        <div
+            className='gs-walkthrough-card'
+            role='button'
+            tabIndex={0}
+            onClick={() => onSelect(walkthrough)}
+            onKeyDown={(e: React.KeyboardEvent) => {
+                if (e.key === 'Enter') {
+                    onSelect(walkthrough);
+                }
+            }}
+        >
+            <div className='gs-walkthrough-card-header'>
+                <WalkthroughIcon walkthrough={walkthrough} />
+                <h3 className='gs-walkthrough-card-title'>{walkthrough.title}</h3>
+            </div>
+            <p className='gs-walkthrough-card-description'>{walkthrough.description}</p>
+            <div className='gs-walkthrough-card-progress'>
+                <div className='gs-walkthrough-progress-bar'>
+                    <div
+                        className='gs-walkthrough-progress-fill'
+                        style={{ width: totalSteps > 0 ? `${(completedSteps / totalSteps) * 100}%` : '0%' }}
+                    ></div>
+                </div>
+                <span className='gs-walkthrough-progress-text'>
+                    {nls.localizeByDefault('{0} of {1}', String(completedSteps), String(totalSteps))}
+                </span>
+            </div>
+        </div>
+    );
+}