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

package/lib/browser/walkthrough-service.d.ts

@@ -0,0 +1,166 @@
+import { Emitter, Event } from '@theia/core/lib/common/event';
+import { Disposable, DisposableCollection } from '@theia/core/lib/common/disposable';
+import { StorageService } from '@theia/core/lib/browser/storage-service';
+import { CommandRegistry } from '@theia/core/lib/common/command';
+import { PreferenceService } from '@theia/core/lib/common/preferences';
+import { ContextKeyService } from '@theia/core/lib/browser/context-key-service';
+import { DeployedPlugin, PluginIdentifiers, PluginMetadata, WalkthroughContribution, WalkthroughStepContribution } from '@theia/plugin-ext/lib/common/plugin-protocol';
+import { OpenerService } from '@theia/core/lib/browser/opener-service';
+import { ILogger } from '@theia/core/lib/common/logger';
+import { MessageService } from '@theia/core/lib/common/message-service';
+import { Walkthrough, WalkthroughStep } from '../common/walkthrough-types';
+import { GettingStartedPreferences } from '../common/getting-started-preferences';
+export declare const WalkthroughViewEventSource: unique symbol;
+export interface WalkthroughViewEventSource {
+    readonly onDidExpandView: Event<string>;
+}
+export declare const WalkthroughPluginSupport: unique symbol;
+export interface WalkthroughPluginSupport {
+    readonly plugins: PluginMetadata[];
+    getPlugin(id: PluginIdentifiers.UnversionedId): DeployedPlugin | undefined;
+    /** The plugins that are not loaded because the workspace is not trusted. */
+    readonly disabledByTrust: ReadonlySet<string>;
+    readonly onDidChangePlugins: Event<void>;
+}
+interface WalkthroughProgressState {
+    completedSteps: {
+        [walkthroughId: string]: string[];
+    };
+}
+export declare class WalkthroughService implements Disposable {
+    protected readonly storageService: StorageService;
+    protected readonly commandRegistry: CommandRegistry;
+    protected readonly preferenceService: PreferenceService;
+    protected readonly contextKeyService: ContextKeyService;
+    protected readonly gettingStartedPreferences: GettingStartedPreferences;
+    protected readonly pluginSupport: WalkthroughPluginSupport;
+    protected readonly viewEventSource: WalkthroughViewEventSource;
+    protected readonly openerService: OpenerService;
+    protected readonly messageService: MessageService;
+    protected readonly logger: ILogger;
+    protected readonly walkthroughs: Map<string, Walkthrough>;
+    /** The definition each walkthrough was registered from, to detect a changed contribution. */
+    protected readonly contributionSignatures: Map<string, string>;
+    protected readonly toDispose: DisposableCollection;
+    protected readonly onDidChangeWalkthroughsEmitter: Emitter<void>;
+    readonly onDidChangeWalkthroughs: Event<void>;
+    protected readonly onDidChangeSelectionEmitter: Emitter<void>;
+    readonly onDidChangeSelection: Event<void>;
+    protected progressState: WalkthroughProgressState;
+    /** Resolves once the persisted progress has been read and the initial sync has run. */
+    protected progressReady: Promise<void>;
+    protected knownPluginIds: Set<string>;
+    protected pluginBaselineEstablished: boolean;
+    protected selectedWalkthroughId: string | undefined;
+    protected selectedStepId: string | undefined;
+    /** Cache of {@link getContextKeys}, invalidated whenever the set of walkthroughs changes. */
+    protected contextKeys: Set<string> | undefined;
+    protected init(): void;
+    protected handlePluginsChanged(): Promise<void>;
+    /**
+     * Complete every pending step whose `onContext:` expression currently holds.
+     */
+    protected completeMatchingContextSteps(): void;
+    /**
+     * The context keys that the `when` clauses and the `onContext:` completion events of all registered
+     * walkthroughs depend on.
+     *
+     * The set is cached because context keys change very frequently, while walkthroughs rarely do.
+     */
+    protected getContextKeys(): Set<string>;
+    /**
+     * Whether a `when` clause currently holds. A contribution without a `when` clause is always visible.
+     */
+    protected isVisible(when: string | undefined): boolean;
+    /**
+     * Restricts a walkthrough to the steps that are currently visible.
+     *
+     * Hidden steps also stay out of the progress, so that a walkthrough whose remaining steps do not apply to
+     * this platform or workspace can still be completed.
+     */
+    protected toVisibleWalkthrough(walkthrough: Walkthrough): Walkthrough;
+    protected handleVisibilityChanged(): void;
+    dispose(): void;
+    /**
+     * Remember the currently deployed plugins as the set that is not considered newly installed.
+     *
+     * Plugins are deployed asynchronously while the application starts, so the baseline can only be trusted
+     * once plugins have actually arrived. Without this, every plugin of a fresh session would look like a new
+     * installation and - with `workbench.welcomePage.walkthroughs.openOnInstall` enabled - open a walkthrough
+     * on startup.
+     */
+    protected establishPluginBaseline(): void;
+    protected loadProgress(): Promise<void>;
+    protected saveProgress(): Promise<void>;
+    protected syncWalkthroughsFromPlugins(): void;
+    protected registerWalkthrough(contribution: WalkthroughContribution): void;
+    protected toWalkthroughStep(step: WalkthroughStepContribution, completedSteps: string[]): WalkthroughStep;
+    /**
+     * All walkthroughs whose `when` clause currently holds, restricted to their currently visible steps.
+     */
+    getWalkthroughs(): Walkthrough[];
+    /**
+     * The walkthrough with the given id, or `undefined` if it is unknown or its `when` clause does not hold.
+     */
+    getWalkthrough(id: string): Walkthrough | undefined;
+    markStepComplete(walkthroughId: string, stepId: string): Promise<void>;
+    /**
+     * Take the completion mark off a step again, for example when it was completed by mistake.
+     */
+    markStepIncomplete(walkthroughId: string, stepId: string): Promise<void>;
+    protected setStepComplete(walkthroughId: string, stepId: string, isComplete: boolean): Promise<void>;
+    /**
+     * Mark every step of the given walkthrough as complete, persisting the progress once.
+     */
+    markAllStepsComplete(walkthroughId: string): Promise<void>;
+    resetProgress(walkthroughId: string): Promise<void>;
+    getStepProgress(walkthroughId: string): {
+        completed: number;
+        total: number;
+    };
+    /**
+     * The walkthrough that is currently opened in the welcome view, if any.
+     * While a walkthrough is selected, the welcome view renders it instead of its regular content.
+     */
+    get selectedWalkthrough(): Walkthrough | undefined;
+    /**
+     * The step of the {@link selectedWalkthrough} whose content is currently shown, if any.
+     */
+    get selectedStep(): WalkthroughStep | undefined;
+    /**
+     * Open the given walkthrough in the welcome view and preselect its first pending step.
+     * Does nothing if no walkthrough is registered under that id.
+     */
+    selectWalkthrough(walkthroughId: string): void;
+    /**
+     * Show the content of the given step of the currently selected walkthrough.
+     */
+    selectStep(stepId: string): void;
+    /**
+     * Close the currently selected walkthrough and return the welcome view to its regular content.
+     */
+    clearSelection(): void;
+    protected getFirstPendingStep(walkthrough: Walkthrough): WalkthroughStep | undefined;
+    /**
+     * VS Code refers to a walkthrough as `publisher.name#walkthroughId`, for example in the `command:` links of a
+     * step description, while the ids used here are fully dot-separated.
+     */
+    protected fromVSCodeWalkthroughId(walkthroughId: string): string;
+    /**
+     * Handle a link click from a walkthrough step description.
+     * Fires the `onLink:{url}` completion event and opens the link.
+     *
+     * Walkthroughs commonly link to `command:` URIs that Theia does not implement. Such a link must not
+     * reject unhandled, so the failure is reported to the user instead.
+     */
+    handleLinkClick(url: string): Promise<void>;
+    /**
+     * VS Code walkthroughs use `command:toSide:<commandId>` to open the result of a command beside the walkthrough.
+     * Theia has no generic equivalent, so the command is executed as usual rather than failing to resolve.
+     */
+    protected normalizeLinkUrl(url: string): string;
+    protected handleCompletionEvent(event: string): void;
+    protected handleExtensionInstalledAutoOpen(pluginId: string): void;
+}
+export {};
+//# sourceMappingURL=walkthrough-service.d.ts.map

package/lib/browser/walkthrough-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"walkthrough-service.d.ts","sourceRoot":"","sources":["../../src/browser/walkthrough-service.ts"],"names":[],"mappings":"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"}