@theia/getting-started 1.76.0-next.4 → 1.76.0-next.42

package/src/browser/style/index.css

@@ -53,8 +53,39 @@ body {
   height: 100%;
 }
 
+/*
+ * Centred in a readable measure instead of stretching across the whole view: with the side bars collapsed the
+ * welcome page is as wide as the window, and full-width content drifts apart towards the edges.
+ */
 .gs-content-container {
   padding: 20px;
+  box-sizing: border-box;
+  width: 100%;
+  max-width: 1400px;
+  margin: 0 auto;
+}
+
+/*
+ * The welcome content below the header: the regular sections on the left, the walkthroughs on the right.
+ * Both columns keep a sensible minimum width and wrap onto each other in a narrow window.
+ */
+.gs-columns {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: flex-start;
+  gap: calc(var(--theia-ui-padding) * 8);
+}
+
+/* Even shares, so that the walkthroughs sit next to the sections rather than pushed against the edge. */
+.gs-main-column,
+.gs-side-column {
+  flex: 1 1 340px;
+  min-width: 0;
+}
+
+/* Without a walkthrough to offer, the column must not hold on to its share of the width. */
+.gs-side-column:empty {
+  display: none;
 }
 
 .gs-content-container a {
@@ -116,46 +147,19 @@ body {
   align-items: center;
 }
 
-.gs-float {
-  float: right;
-  width: 50%;
-  margin-top: 100px;
-}
-
-.gs-container.gs-aifeature-container {
-  border: 1px solid var(--theia-focusBorder);
-  padding: 15px;
-}
-
-.shadow-pulse {
-  animation: shadowPulse 2s infinite ease-in-out;
-}
-
-@keyframes shadowPulse {
-
-  0%,
-  100% {
-    box-shadow: 0 0 0 rgba(0, 0, 0, 0);
-  }
-
-  50% {
-    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);
+  gap: calc(var(--theia-ui-padding) * 2);
+  margin-top: calc(var(--theia-ui-padding) * 2);
   max-width: 640px;
 }
 
 .gs-walkthrough-card {
-  padding: calc(var(--theia-ui-padding) * 1.5) calc(var(--theia-ui-padding) * 2);
+  padding: calc(var(--theia-ui-padding) * 2.5);
   border-radius: calc(var(--theia-ui-padding) / 2);
   cursor: pointer;
   background-color: var(--theia-walkthrough-card-background);
@@ -203,25 +207,31 @@ body {
   object-fit: contain;
 }
 
-/* Kept to a single line so that every card stays the same height. */
+/*
+ * Wraps, but no further than two lines, so that a description is readable in the narrow side column
+ * without any single card growing out of proportion.
+ */
 .gs-walkthrough-card-description {
   color: var(--theia-descriptionForeground);
   font-size: var(--theia-ui-font-size0);
   margin: 0;
+  display: -webkit-box;
+  -webkit-box-orient: vertical;
+  -webkit-line-clamp: 2;
+  line-clamp: 2;
   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);
+  margin-top: calc(var(--theia-ui-padding) * 2);
 }
 
+/* Uses whatever width the card offers rather than a fixed one, which would leave a gap in a wide card. */
 .gs-walkthrough-progress-bar {
-  flex: 0 1 180px;
+  flex: 1 1 auto;
   height: calc(var(--theia-ui-padding) / 3);
   background-color: var(--theia-walkthrough-progress-background);
   border-radius: calc(var(--theia-ui-padding) / 3);
@@ -242,6 +252,30 @@ body {
   white-space: nowrap;
 }
 
+/*
+ * A link that stands alone in its paragraph is an action rather than a reference, so a step can offer it as a
+ * button. Links inside a sentence keep reading as links, which is what the `:only-child` restriction buys.
+ */
+.gs-walkthrough-step-description p > a:only-child {
+  display: inline-block;
+  padding: calc(var(--theia-ui-padding) / 2) calc(var(--theia-ui-padding) * 2);
+  border: var(--theia-border-width) solid var(--theia-button-border);
+  border-radius: calc(var(--theia-ui-padding) / 2);
+  background-color: var(--theia-button-background);
+  color: var(--theia-button-foreground);
+  text-decoration: none;
+  cursor: pointer;
+}
+
+.gs-walkthrough-step-description p > a:only-child:hover {
+  background-color: var(--theia-button-hoverBackground);
+  text-decoration: none;
+}
+
+.gs-walkthrough-step-description p > a:only-child:focus {
+  outline: var(--theia-border-width) solid var(--theia-focusBorder);
+}
+
 .gs-walkthrough-more {
   display: inline-block;
   margin-top: calc(var(--theia-ui-padding) / 2);
@@ -397,12 +431,24 @@ body {
   outline: var(--theia-border-width) dashed var(--theia-contrastActiveBorder);
 }
 
-.gs-walkthrough-media-image {
+.gs-walkthrough-media-image,
+.gs-walkthrough-media-svg {
   max-width: 100%;
   border-radius: calc(var(--theia-ui-padding) / 2);
   margin-top: var(--theia-ui-padding);
 }
 
+.gs-walkthrough-media-svg svg {
+  max-width: 100%;
+  height: auto;
+  display: block;
+}
+
+.gs-walkthrough-media-svg a {
+  cursor: pointer;
+  outline: none;
+}
+
 .gs-walkthrough-media-markdown {
   margin-top: var(--theia-ui-padding);
 }

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

@@ -358,7 +358,95 @@ describe('WalkthroughDetail', () => {
         }, 50);
     });
 
-    it('should render SVG media for selected step', done => {
+    it('should render SVG media inline for selected step', done => {
+        const originalFetch = global.fetch;
+        const svgContent = '<svg viewBox="0 0 100 100"><rect width="100" height="100" fill="var(--vscode-foreground)" /></svg>';
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        (global as any).fetch = (url: string) => {
+            assert.ok(url.includes('graphic.svg'));
+            return Promise.resolve({ ok: true, text: () => Promise.resolve(svgContent) });
+        };
+
+        const selectedStep = createMockStep({
+            id: 's1',
+            media: { svg: '/path/to/graphic.svg', altText: 'SVG Graphic' }
+        });
+        const walkthrough = createMockWalkthrough({ steps: [selectedStep] });
+
+        root.render(
+            <WalkthroughDetail
+                logger={createMockLogger()}
+                themeService={createMockThemeService()}
+                walkthrough={walkthrough}
+                onStepSelect={() => { }}
+                onBack={() => { }}
+                selectedStep={selectedStep}
+                markdownRenderer={mockRenderer}
+            />
+        );
+
+        setTimeout(() => {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            (global as any).fetch = originalFetch;
+            const svgContainer = container.querySelector('.gs-walkthrough-media-svg') as HTMLElement;
+            assert.ok(svgContainer, 'SVG container element should exist');
+            assert.strictEqual(svgContainer.getAttribute('role'), 'img', 'Role should be img');
+            assert.strictEqual(svgContainer.getAttribute('aria-label'), 'SVG Graphic', 'aria-label should be set');
+            const svgElement = svgContainer.querySelector('svg');
+            assert.ok(svgElement, 'Inline SVG element should exist');
+            assert.strictEqual(svgElement?.getAttribute('viewBox'), '0 0 100 100');
+            const rectElement = svgContainer.querySelector('rect');
+            assert.strictEqual(rectElement?.getAttribute('fill'), 'var(--vscode-foreground)');
+            done();
+        }, 50);
+    });
+
+    it('should handle command links clicked inside rendered SVG media', done => {
+        const originalFetch = global.fetch;
+        const svgContent = '<svg><a xlink:href="command:my.extension.command"><circle cx="50" cy="50" r="40" /></a></svg>';
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        (global as any).fetch = () => Promise.resolve({ ok: true, text: () => Promise.resolve(svgContent) });
+
+        let clickedUrl = '';
+        const selectedStep = createMockStep({
+            id: 's1',
+            media: { svg: 'sample.svg' }
+        });
+        const walkthrough = createMockWalkthrough({ steps: [selectedStep] });
+
+        root.render(
+            <WalkthroughDetail
+                logger={createMockLogger()}
+                themeService={createMockThemeService()}
+                walkthrough={walkthrough}
+                onStepSelect={() => { }}
+                onBack={() => { }}
+                selectedStep={selectedStep}
+                markdownRenderer={mockRenderer}
+                onLinkClick={url => { clickedUrl = url; }}
+            />
+        );
+
+        setTimeout(() => {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            (global as any).fetch = originalFetch;
+            const circle = container.querySelector('.gs-walkthrough-media-svg circle') as HTMLElement;
+            assert.ok(circle, 'SVG circle should exist');
+            circle.dispatchEvent(new MouseEvent('click', { bubbles: true, cancelable: true }));
+
+            setTimeout(() => {
+                assert.strictEqual(clickedUrl, 'command:my.extension.command', 'Link click should route command URI');
+                done();
+            }, 50);
+        }, 50);
+    });
+
+    it('should omit aria-label on SVG media when altText is not provided', done => {
+        const originalFetch = global.fetch;
+        const svgContent = '<svg viewBox="0 0 100 100"><circle cx="50" cy="50" r="50" /></svg>';
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        (global as any).fetch = () => Promise.resolve({ ok: true, text: () => Promise.resolve(svgContent) });
+
         const selectedStep = createMockStep({
             id: 's1',
             media: { svg: '/path/to/graphic.svg' }
@@ -378,13 +466,115 @@ describe('WalkthroughDetail', () => {
         );
 
         setTimeout(() => {
-            const img = container.querySelector('.gs-walkthrough-media-image') as HTMLImageElement;
-            assert.ok(img, 'SVG image element should exist');
-            assert.strictEqual(img.getAttribute('src'), '/path/to/graphic.svg', 'SVG src should be set');
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            (global as any).fetch = originalFetch;
+            const svgContainer = container.querySelector('.gs-walkthrough-media-svg') as HTMLElement;
+            assert.ok(svgContainer, 'SVG container element should exist');
+            assert.strictEqual(svgContainer.getAttribute('role'), 'img');
+            assert.strictEqual(svgContainer.hasAttribute('aria-label'), false, 'aria-label attribute should be omitted');
+            done();
+        }, 50);
+    });
+
+    it('should render nothing when SVG media fetch fails', done => {
+        const originalFetch = global.fetch;
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        (global as any).fetch = () => Promise.resolve({ ok: false, text: () => Promise.resolve('') });
+
+        const selectedStep = createMockStep({
+            id: 's1',
+            media: { svg: '/path/to/missing.svg' }
+        });
+        const walkthrough = createMockWalkthrough({ steps: [selectedStep] });
+
+        root.render(
+            <WalkthroughDetail
+                logger={createMockLogger()}
+                themeService={createMockThemeService()}
+                walkthrough={walkthrough}
+                onStepSelect={() => { }}
+                onBack={() => { }}
+                selectedStep={selectedStep}
+                markdownRenderer={mockRenderer}
+            />
+        );
+
+        setTimeout(() => {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            (global as any).fetch = originalFetch;
+            const svgContainer = container.querySelector('.gs-walkthrough-media-svg');
+            assert.ok(!svgContainer, 'No SVG container should be rendered on failure');
+            const roleImg = container.querySelector('[role="img"]');
+            assert.ok(!roleImg, 'No empty role=img should be left behind on failure');
             done();
         }, 50);
     });
 
+    it('should clear previous SVG media when switching to another SVG step while loading', done => {
+        const originalFetch = global.fetch;
+        let resolveSecondFetch: (value: { ok: boolean; text: () => Promise<string> }) => void;
+        const secondFetchPromise = new Promise<{ ok: boolean; text: () => Promise<string> }>(resolve => {
+            resolveSecondFetch = resolve;
+        });
+
+        const firstSvg = '<svg id="first"><circle cx="10" cy="10" r="10" /></svg>';
+        const secondSvg = '<svg id="second"><circle cx="20" cy="20" r="20" /></svg>';
+
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        (global as any).fetch = (url: string) => {
+            if (url.includes('first.svg')) {
+                return Promise.resolve({ ok: true, text: () => Promise.resolve(firstSvg) });
+            }
+            return secondFetchPromise;
+        };
+
+        const step1 = createMockStep({ id: 's1', media: { svg: 'first.svg' } });
+        const step2 = createMockStep({ id: 's2', media: { svg: 'second.svg' } });
+        const walkthrough = createMockWalkthrough({ steps: [step1, step2] });
+
+        root.render(
+            <WalkthroughDetail
+                logger={createMockLogger()}
+                themeService={createMockThemeService()}
+                walkthrough={walkthrough}
+                onStepSelect={() => { }}
+                onBack={() => { }}
+                selectedStep={step1}
+                markdownRenderer={mockRenderer}
+            />
+        );
+
+        setTimeout(() => {
+            assert.ok(container.querySelector('#first'), 'First SVG should be rendered');
+
+            root.render(
+                <WalkthroughDetail
+                    logger={createMockLogger()}
+                    themeService={createMockThemeService()}
+                    walkthrough={walkthrough}
+                    onStepSelect={() => { }}
+                    onBack={() => { }}
+                    selectedStep={step2}
+                    markdownRenderer={mockRenderer}
+                />
+            );
+
+            setTimeout(() => {
+                assert.ok(!container.querySelector('#first'), 'First SVG should be cleared immediately upon step switch');
+                assert.ok(!container.querySelector('.gs-walkthrough-media-svg'), 'No SVG container should be visible while loading');
+
+                resolveSecondFetch({ ok: true, text: () => Promise.resolve(secondSvg) });
+
+                setTimeout(() => {
+                    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                    (global as any).fetch = originalFetch;
+                    assert.ok(container.querySelector('#second'), 'Second SVG should be rendered after fetch resolves');
+                    done();
+                }, 50);
+            }, 50);
+        }, 50);
+    });
+
     it('should turn single newlines in a description into Markdown hard breaks', done => {
         const renderedMarkdown: string[] = [];
         const recordingRenderer: MarkdownRenderer = {

package/src/browser/walkthrough-detail.tsx

@@ -14,6 +14,7 @@
 // SPDX-License-Identifier: EPL-2.0 OR GPL-2.0-only WITH Classpath-exception-2.0
 // *****************************************************************************
 
+import * as DOMPurify from '@theia/core/shared/dompurify';
 import { codicon } from '@theia/core/lib/browser';
 import { MarkdownRenderer, MarkdownRenderOptions, MarkdownRenderResult } from '@theia/core/lib/browser/markdown-rendering/markdown-renderer';
 import { ThemeService } from '@theia/core/lib/browser/theming';
@@ -264,7 +265,7 @@ function renderMedia(
         return <WalkthroughMedia src={media.markdown} markdownRenderer={markdownRenderer} logger={logger} onLinkClick={onLinkClick} />;
     }
     if ('svg' in media) {
-        return <WalkthroughMediaImage src={media.svg} altText={media.altText || ''} themeService={themeService} />;
+        return <WalkthroughMediaSvg src={media.svg} altText={media.altText || undefined} logger={logger} onLinkClick={onLinkClick} />;
     }
     if ('image' in media) {
         return <WalkthroughMediaImage src={media.image} altText={media.altText || ''} themeService={themeService} />;
@@ -345,3 +346,80 @@ function WalkthroughMedia(props: {
 
     return <div className='gs-walkthrough-media-markdown' ref={containerRef} />;
 }
+
+function WalkthroughMediaSvg(props: {
+    src: string;
+    altText?: string;
+    logger: ILogger;
+    onLinkClick?: (url: string) => void;
+}): React.ReactElement | undefined {
+    const [content, setContent] = React.useState<string | undefined>();
+    // eslint-disable-next-line no-null/no-null
+    const containerRef = React.useRef<HTMLDivElement>(null);
+    const onLinkClickRef = React.useRef(props.onLinkClick);
+    onLinkClickRef.current = props.onLinkClick;
+
+    React.useEffect(() => {
+        let cancelled = false;
+        setContent(undefined);
+        fetch(PluginSharedStyle.toExternalIconUrl(props.src))
+            .then(response => (!cancelled && response.ok ? response.text() : ''))
+            .then(text => {
+                if (cancelled) {
+                    return;
+                }
+                if (text) {
+                    const sanitized = DOMPurify.sanitize(text, {
+                        USE_PROFILES: { svg: true, svgFilters: true },
+                        ADD_TAGS: ['use', 'a'],
+                        ADD_ATTR: ['xlink:href', 'href', 'target'],
+                        ALLOW_UNKNOWN_PROTOCOLS: true
+                    });
+                    setContent(sanitized || undefined);
+                } else {
+                    setContent(undefined);
+                }
+            })
+            .catch(error => {
+                if (!cancelled) {
+                    setContent(undefined);
+                    props.logger.warn(`Could not load the walkthrough media '${props.src}'.`, error);
+                }
+            });
+
+        return () => {
+            cancelled = true;
+        };
+    }, [props.src, props.logger]);
+
+    const handleClick = React.useCallback((event: React.MouseEvent) => {
+        const target = event.target as Element | null;
+        const anchor = target?.closest('a');
+        if (!anchor || !containerRef.current?.contains(anchor)) {
+            return;
+        }
+        const href = anchor.getAttribute('href') || anchor.getAttribute('xlink:href');
+        if (href) {
+            event.preventDefault();
+            event.stopPropagation();
+            onLinkClickRef.current?.(href);
+        }
+    }, []);
+
+    if (!content) {
+        return undefined;
+    }
+
+    return (
+        <div
+            className='gs-walkthrough-media-svg'
+            ref={containerRef}
+            role='img'
+            aria-label={props.altText || undefined}
+            onClick={handleClick}
+            // eslint-disable-next-line react/no-danger
+            dangerouslySetInnerHTML={{ __html: content }}
+        />
+    );
+}
+

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

@@ -400,7 +400,9 @@ describe('WalkthroughSection', () => {
         }, 50);
     });
     it('should list at most WALKTHROUGH_LIST_LIMIT walkthroughs and delegate More... to the picker', done => {
-        const walkthroughs = [1, 2, 3, 4, 5].map(i => createMockWalkthrough({ id: `wt${i}`, title: `WT ${i}` }));
+        // One more than fits, so that the assertions hold whatever the limit is.
+        const walkthroughs = Array.from({ length: WALKTHROUGH_LIST_LIMIT + 1 },
+            (_, i) => createMockWalkthrough({ id: `wt${i}`, title: `WT ${i}` }));
         const mockService = createMockWalkthroughService(walkthroughs);
         let showAllCalled = false;
 
@@ -459,6 +461,32 @@ describe('WalkthroughSection', () => {
         }, 50);
     });
 
+    it('should render nothing once every walkthrough is complete', done => {
+        const walkthroughs = [createMockWalkthrough({
+            id: 'done',
+            title: 'Done',
+            steps: [createMockStep({ id: 's1', isComplete: true })]
+        })];
+        const mockService = createMockWalkthroughService(walkthroughs);
+
+        root.render(
+            <WalkthroughSection
+                walkthroughService={mockService as unknown as WalkthroughService}
+                markdownRenderer={mockRenderer}
+                themeService={createMockThemeService()}
+                logger={createMockLogger()}
+                onShowAll={() => { }}
+            />
+        );
+
+        setTimeout(() => {
+            // Not even the heading: the section must not hold on to its place in the welcome page.
+            // eslint-disable-next-line no-null/no-null
+            assert.strictEqual(container.querySelector('.gs-section'), null, 'Should not render the section');
+            done();
+        }, 50);
+    });
+
     it('should not offer More... when every walkthrough is listed', done => {
         const walkthroughs = [1, 2].map(i => createMockWalkthrough({ id: `wt${i}`, title: `WT ${i}` }));
         const mockService = createMockWalkthroughService(walkthroughs);

package/src/browser/walkthrough-section.tsx

@@ -35,8 +35,8 @@ export interface WalkthroughSectionProps {
     onShowAll?: () => void;
 }
 
-/** How many walkthroughs are listed on the welcome page. */
-export const WALKTHROUGH_LIST_LIMIT = 2;
+/** How many walkthroughs are listed on the welcome page; the rest stay behind `More...`. */
+export const WALKTHROUGH_LIST_LIMIT = 5;
 
 /**
  * Renders the list of contributed walkthroughs, or the currently selected walkthrough.
@@ -77,12 +77,14 @@ export function WalkthroughSection(props: WalkthroughSectionProps): React.ReactE
     }
 
     const walkthroughs = walkthroughService.getWalkthroughs();
-    if (walkthroughs.length === 0) {
+    // A finished walkthrough has nothing left to offer here; it stays reachable through the
+    // `walkthrough.open` command. Once none is pending the section renders nothing at all, so that it does not
+    // hold on to its place in the welcome page for an empty heading.
+    const pending = walkthroughs.filter(walkthrough => walkthrough.steps.some(step => !step.isComplete));
+    if (pending.length === 0) {
         return <React.Fragment />;
     }
 
-    // A finished walkthrough has nothing left to offer here; it stays reachable through `onShowAll`.
-    const pending = walkthroughs.filter(walkthrough => walkthrough.steps.some(step => !step.isComplete));
     const listed = pending.slice(0, WALKTHROUGH_LIST_LIMIT);
     return (
         <div className='gs-section'>