@codingame/monaco-vscode-api 20.1.1 → 20.2.1

package/vscode/src/vs/platform/actionWidget/browser/actionWidget.css

@@ -1,3 +1,8 @@
+/*---------------------------------------------------------------------------------------------
+ *  Copyright (c) Microsoft Corporation. All rights reserved.
+ *  Licensed under the MIT License. See License.txt in the project root for license information.
+ *--------------------------------------------------------------------------------------------*/
+
 .action-widget {
 	font-size: 13px;
 	border-radius: 0;
@@ -13,6 +18,7 @@
 	padding: 4px;
 	box-shadow: 0 2px 8px var(--vscode-widget-shadow);
 }
+
 .context-view-block {
 	position: fixed;
 	cursor: initial;
@@ -22,6 +28,7 @@
 	height: 100%;
 	z-index: -1;
 }
+
 .context-view-pointerBlock {
 	position: fixed;
 	cursor: initial;
@@ -31,18 +38,23 @@
 	height: 100%;
 	z-index: 2;
 }
+
 .action-widget .monaco-list {
 	user-select: none;
 	-webkit-user-select: none;
 	border: none !important;
 	border-width: 0 !important;
 }
+
 .action-widget .monaco-list:focus:before {
 	outline: 0 !important;
 }
+
 .action-widget .monaco-list .monaco-scrollable-element {
 	overflow: visible;
 }
+
+/** Styles for each row in the list element **/
 .action-widget .monaco-list .monaco-list-row {
 	padding: 0 0 0 8px;
 	white-space: nowrap;
@@ -51,20 +63,24 @@
 	width: 100%;
 	border-radius: 4px;
 }
+
 .action-widget .monaco-list .monaco-list-row.action.focused:not(.option-disabled) {
 	background-color: var(--vscode-editorActionList-focusBackground) !important;
 	color: var(--vscode-editorActionList-focusForeground);
 	outline: 1px solid var(--vscode-menu-selectionBorder, transparent);
 	outline-offset: -1px;
 }
+
 .action-widget .monaco-list-row.group-header {
 	color: var(--vscode-descriptionForeground) !important;
 	font-weight: 600;
 	font-size: 12px;
 }
+
 .action-widget .monaco-list-row.group-header:not(:first-of-type) {
 	margin-top: 2px;
 }
+
 .action-widget .monaco-scrollable-element .monaco-list-rows .monaco-list-row.separator {
 	border-top: 1px solid var(--vscode-editorHoverWidget-border);
 	color: var(--vscode-descriptionForeground);
@@ -75,15 +91,18 @@
 	user-select: none;
 	border-radius: 0;
 }
+
 .action-widget .monaco-scrollable-element .monaco-list-rows .monaco-list-row.separator.focused {
 	outline: 0 solid;
 	background-color: transparent;
 	border-radius: 0;
 }
+
 .action-widget .monaco-list-row.separator:first-of-type {
 	border-top: none;
 	margin-top: 0;
 }
+
 .action-widget .monaco-list .group-header,
 .action-widget .monaco-list .option-disabled,
 .action-widget .monaco-list .option-disabled:before,
@@ -96,25 +115,31 @@
 	background-color: transparent !important;
 	outline: 0 solid !important;
 }
+
 .action-widget .monaco-list-row.action {
 	display: flex;
 	gap: 8px;
 	align-items: center;
 }
+
 .action-widget .monaco-list-row.action.option-disabled,
 .action-widget .monaco-list:focus .monaco-list-row.focused.action.option-disabled,
 .action-widget .monaco-list-row.action.option-disabled .codicon,
 .action-widget .monaco-list:not(.drop-target):not(.dragging) .monaco-list-row:hover:not(.selected):not(.focused).option-disabled {
 	color: var(--vscode-disabledForeground);
 }
+
+
 .action-widget .monaco-list-row.action:not(.option-disabled) .codicon {
 	color: inherit;
 }
+
 .action-widget .monaco-list-row.action .title {
 	flex: 1;
 	overflow: hidden;
 	text-overflow: ellipsis;
 }
+
 .action-widget .monaco-list-row.action .monaco-keybinding > .monaco-keybinding-key {
 		background-color: var(--vscode-keybindingLabel-background);
 		color: var(--vscode-keybindingLabel-foreground);
@@ -125,19 +150,25 @@
 		border-bottom-color: var(--vscode-keybindingLabel-bottomBorder);
 		box-shadow: inset 0 -1px 0 var(--vscode-widget-shadow);
 }
+
+/* Action bar */
+
 .action-widget .action-widget-action-bar {
 	background-color: var(--vscode-editorActionList-background);
 	border-top: 1px solid var(--vscode-editorHoverWidget-border);
 	margin-top: 2px;
 }
+
 .action-widget .action-widget-action-bar::before {
 	display: block;
 	content: "";
 	width: 100%;
 }
+
 .action-widget .action-widget-action-bar .actions-container {
 	padding: 3px 8px 0;
 }
+
 .action-widget-action-bar .action-label {
 	color: var(--vscode-textLink-activeForeground);
 	font-size: 12px;
@@ -145,16 +176,21 @@
 	padding: 0;
 	pointer-events: all;
 }
+
 .action-widget-action-bar .action-item {
 	margin-right: 16px;
 	pointer-events: none;
 }
+
 .action-widget-action-bar .action-label:hover {
 	background-color: transparent !important;
 }
+
 .monaco-action-bar .actions-container.highlight-toggled .action-label.checked {
+	/* The important gives this rule precedence over the hover rule. */
 	background: var(--vscode-actionBar-toggledBackground) !important;
 }
+
 .action-widget .monaco-list .monaco-list-row .description {
 	opacity: 0.7;
 	margin-left: 0.5em;

package/vscode/src/vs/platform/actions/browser/floatingMenu.d.ts

@@ -19,6 +19,7 @@ export declare abstract class AbstractFloatingClickMenu extends Disposable {
     protected readonly onDidRender: import("../../../base/common/event.js").Event<FloatingClickWidget>;
     private readonly menu;
     constructor(menuId: MenuId, menuService: IMenuService, contextKeyService: IContextKeyService);
+    /** Should be called in implementation constructors after they initialized */
     protected render(): void;
     protected abstract createWidget(action: IAction, disposables: DisposableStore): FloatingClickWidget;
     protected getActionArg(): unknown;
@@ -28,8 +29,11 @@ export declare class FloatingClickMenu extends AbstractFloatingClickMenu {
     private readonly options;
     private readonly instantiationService;
     constructor(options: {
+        /** Element the menu should be rendered into. */
         container: HTMLElement;
+        /** Menu to show. If no actions are present, the button is hidden. */
         menuId: MenuId;
+        /** Argument provided to the menu action */
         getActionArg: () => void;
     }, instantiationService: IInstantiationService, menuService: IMenuService, contextKeyService: IContextKeyService);
     protected createWidget(action: IAction, disposable: DisposableStore): FloatingClickWidget;

package/vscode/src/vs/platform/actions/browser/menuEntryActionViewItem.css

@@ -1,3 +1,8 @@
+/*---------------------------------------------------------------------------------------------
+ *  Copyright (c) Microsoft Corporation. All rights reserved.
+ *  Licensed under the MIT License. See License.txt in the project root for license information.
+ *--------------------------------------------------------------------------------------------*/
+
 .monaco-action-bar .action-item.menu-entry .action-label.icon {
 	width: 16px;
 	height: 16px;
@@ -5,25 +10,31 @@
 	background-position: 50%;
 	background-size: 16px;
 }
+
 .monaco-action-bar .action-item.menu-entry.text-only .action-label {
 	color: var(--vscode-descriptionForeground);
 	overflow: hidden;
 	border-radius: 2px;
 }
+
 .monaco-action-bar .action-item.menu-entry.text-only.use-comma:not(:last-of-type) .action-label::after {
 	content: ', ';
 }
+
 .monaco-action-bar .action-item.menu-entry.text-only + .action-item:not(.text-only) > .monaco-dropdown .action-label {
 	color: var(--vscode-descriptionForeground);
 }
+
 .monaco-dropdown-with-default {
 	display: flex !important;
 	flex-direction: row;
 	border-radius: 5px;
 }
+
 .monaco-dropdown-with-default > .action-container > .action-label {
 	margin-right: 0;
 }
+
 .monaco-dropdown-with-default > .action-container.menu-entry > .action-label.icon {
 	width: 16px;
 	height: 16px;
@@ -31,9 +42,11 @@
 	background-position: 50%;
 	background-size: 16px;
 }
+
 .monaco-dropdown-with-default:hover {
 	background-color: var(--vscode-toolbar-hoverBackground);
 }
+
 .monaco-dropdown-with-default > .dropdown-action-container > .monaco-dropdown > .dropdown-label .codicon[class*='codicon-'] {
 	font-size: 12px;
 	padding-left: 0px;
@@ -41,6 +54,7 @@
 	line-height: 16px;
 	margin-left: -3px;
 }
+
 .monaco-dropdown-with-default > .dropdown-action-container > .monaco-dropdown > .dropdown-label > .action-label {
 	display: block;
 	background-size: 16px;

package/vscode/src/vs/platform/actions/browser/menuEntryActionViewItem.d.ts

@@ -107,4 +107,7 @@ export declare class DropdownWithDefaultActionViewItem extends BaseActionViewIte
     blur(): void;
     setFocusable(focusable: boolean): void;
 }
+/**
+ * Creates action view items for menu actions or submenu actions.
+ */
 export declare function createActionViewItem(instaService: IInstantiationService, action: IAction, options: IDropdownMenuActionViewItemOptions | IMenuEntryActionViewItemOptions | undefined): undefined | MenuEntryActionViewItem | SubmenuEntryActionViewItem | BaseActionViewItem;

package/vscode/src/vs/platform/actions/browser/toolbar.d.ts

@@ -11,22 +11,58 @@ import { ITelemetryService } from "../../telemetry/common/telemetry.service.js";
 import { IActionViewItemService } from "./actionViewItemService.service.js";
 import { IInstantiationService } from "../../instantiation/common/instantiation.js";
 export declare enum HiddenItemStrategy {
+    /** This toolbar doesn't support hiding*/
     NoHide = -1,
+    /** Hidden items aren't shown anywhere */
     Ignore = 0,
+    /** Hidden items move into the secondary group */
     RenderInSecondaryGroup = 1
 }
 export type IWorkbenchToolBarOptions = IToolBarOptions & {
+    /**
+     * Items of the primary group can be hidden. When this happens the item can
+     * - move into the secondary popup-menu, or
+     * - not be shown at all
+     */
     hiddenItemStrategy?: HiddenItemStrategy;
+    /**
+     * Optional menu id which is used for a "Reset Menu" command. This should be the
+     * menu id that defines the contents of this workbench menu
+     */
     resetMenu?: MenuId;
+    /**
+     * Optional menu id which items are used for the context menu of the toolbar.
+     */
     contextMenu?: MenuId;
+    /**
+     * Optional options how menu actions are created and invoked
+     */
     menuOptions?: IMenuActionOptions;
+    /**
+     * When set the `workbenchActionExecuted` is automatically send for each invoked action. The `from` property
+     * of the event will the passed `telemetrySource`-value
+     */
     telemetrySource?: string;
+    /** This is controlled by the WorkbenchToolBar */
     allowContextMenu?: never;
+    /**
+     * Controls the overflow behavior of the primary group of toolbar. This isthe maximum number of items and id of
+     * items that should never overflow
+     *
+     */
     overflowBehavior?: {
         maxItems: number;
         exempted?: string[];
     };
 };
+/**
+ * The `WorkbenchToolBar` does
+ * - support hiding of menu items
+ * - lookup keybindings for each actions automatically
+ * - send `workbenchActionExecuted`-events for each action
+ *
+ * See {@link MenuWorkbenchToolBar} for a toolbar that is backed by a menu.
+ */
 export declare class WorkbenchToolBar extends ToolBar {
     private _options;
     private readonly _menuService;
@@ -39,19 +75,50 @@ export declare class WorkbenchToolBar extends ToolBar {
     setActions(_primary: readonly IAction[], _secondary?: readonly IAction[], menuIds?: readonly MenuId[]): void;
 }
 export interface IToolBarRenderOptions {
+    /**
+     * Determines what groups are considered primary. Defaults to `navigation`. Items of the primary
+     * group are rendered with buttons and the rest is rendered in the secondary popup-menu.
+     */
     primaryGroup?: string | ((actionGroup: string) => boolean);
+    /**
+     * Inlinse submenus with just a single item
+     */
     shouldInlineSubmenu?: (action: SubmenuAction, group: string, groupSize: number) => boolean;
+    /**
+     * Should the primary group allow for separators.
+     */
     useSeparatorsInPrimaryActions?: boolean;
+    /**
+     * Force a leading separator in the primary actions group.
+     */
     forceLeadingSeparatorInPrimaryActions?: boolean;
 }
 export interface IMenuWorkbenchToolBarOptions extends IWorkbenchToolBarOptions {
+    /**
+     * Optional options to configure how the toolbar renderes items.
+     */
     toolbarOptions?: IToolBarRenderOptions;
+    /**
+     * Only `undefined` to disable the reset command is allowed, otherwise the menus
+     * id is used.
+     */
     resetMenu?: undefined;
+    /**
+     * Customize the debounce delay for menu updates
+     */
     eventDebounceDelay?: number;
 }
+/**
+ * A {@link WorkbenchToolBar workbench toolbar} that is purely driven from a {@link MenuId menu}-identifier.
+ *
+ * *Note* that Manual updates via `setActions` are NOT supported.
+ */
 export declare class MenuWorkbenchToolBar extends WorkbenchToolBar {
     private readonly _onDidChangeMenuItems;
     readonly onDidChangeMenuItems: Event<this>;
     constructor(container: HTMLElement, menuId: MenuId, options: IMenuWorkbenchToolBarOptions | undefined, menuService: IMenuService, contextKeyService: IContextKeyService, contextMenuService: IContextMenuService, keybindingService: IKeybindingService, commandService: ICommandService, telemetryService: ITelemetryService, actionViewService: IActionViewItemService, instaService: IInstantiationService);
+    /**
+     * @deprecated The WorkbenchToolBar does not support this method because it works with menus.
+     */
     setActions(): void;
 }

package/vscode/src/vs/platform/actions/common/actions.d.ts

@@ -11,6 +11,9 @@ import { IKeybindingRule } from "../../keybinding/common/keybindingsRegistry.js"
 export interface IMenuItem {
     command: ICommandAction;
     alt?: ICommandAction;
+    /**
+     * Menu item is hidden if this expression returns false.
+     */
     when?: ContextKeyExpression;
     group?: "navigation" | string;
     order?: number;
@@ -240,8 +243,16 @@ export declare class MenuId {
     static readonly MultiDiffEditorFileToolbar: MenuId;
     static readonly DiffEditorHunkToolbar: MenuId;
     static readonly DiffEditorSelectionToolbar: MenuId;
+    /**
+     * Create or reuse a `MenuId` with the given identifier
+     */
     static for(identifier: string): MenuId;
     readonly id: string;
+    /**
+     * Create a new `MenuId` with the unique identifier. Will throw if a menu
+     * with the identifier already exists, use `MenuId.for(ident)` or a unique
+     * identifier
+     */
     constructor(identifier: string);
 }
 export interface IMenuActionOptions {
@@ -282,6 +293,10 @@ export interface IMenuRegistry {
     addCommand(userCommand: ICommandAction): IDisposable;
     getCommand(id: string): ICommandAction | undefined;
     getCommands(): ICommandsMap;
+    /**
+     * @deprecated Use `appendMenuItem` or most likely use `registerAction2` instead. There should be no strong
+     * reason to use this directly.
+     */
     appendMenuItems(items: Iterable<{
         id: MenuId;
         item: IMenuItem | ISubmenuItem;
@@ -319,18 +334,43 @@ export declare class MenuItemAction implements IAction {
 }
 type OneOrN<T> = T | T[];
 interface IAction2CommonOptions extends ICommandAction {
+    /**
+     * One or many menu items.
+     */
     menu?: OneOrN<{
         id: MenuId;
         precondition?: null;
     } & Omit<IMenuItem, "command">>;
+    /**
+     * One keybinding.
+     */
     keybinding?: OneOrN<Omit<IKeybindingRule, "id">>;
 }
 interface IBaseAction2Options extends IAction2CommonOptions {
+    /**
+     * This type is used when an action is not going to show up in the command palette.
+     * In that case, it's able to use a string for the `title` and `category` properties.
+     */
     f1?: false;
 }
 export interface ICommandPaletteOptions extends IAction2CommonOptions {
+    /**
+     * The title of the command that will be displayed in the command palette after the category.
+     *  This overrides {@link ICommandAction.title} to ensure a string isn't used so that the title
+     *  includes the localized value and the original value for users using language packs.
+     */
     title: ICommandActionTitle;
+    /**
+     * The category of the command that will be displayed in the command palette before the title suffixed.
+     * with a colon This overrides {@link ICommandAction.title} to ensure a string isn't used so that
+     * the title includes the localized value and the original value for users using language packs.
+     */
     category?: keyof typeof Categories | ILocalizedString;
+    /**
+     * Shorthand to add this command to the command palette. Note: this is not the only way to declare that
+     * a command should be in the command palette... however, enforcing ILocalizedString in the other scenarios
+     * is much more challenging and this gets us most of the way there.
+     */
     f1: true;
 }
 export type IAction2Options = ICommandPaletteOptions | IBaseAction2Options;

package/vscode/src/vs/platform/actions/common/actions.service.d.ts

@@ -3,12 +3,32 @@ import { MenuId, IMenuCreateOptions, IMenu, IMenuActionOptions, MenuItemAction,
 export declare const IMenuService: import("../../instantiation/common/instantiation.js").ServiceIdentifier<IMenuService>;
 export interface IMenuService {
     readonly _serviceBrand: undefined;
+    /**
+    * Consider using getMenuActions if you don't need to listen to events.
+    *
+    * Create a new menu for the given menu identifier. A menu sends events when it's entries
+    * have changed (placement, enablement, checked-state). By default it does not send events for
+    * submenu entries. That is more expensive and must be explicitly enabled with the
+    * `emitEventsForSubmenuChanges` flag.
+    */
     createMenu(id: MenuId, contextKeyService: IContextKeyService, options?: IMenuCreateOptions): IMenu;
+    /**
+    * Creates a new menu, gets the actions, and then disposes of the menu.
+    */
     getMenuActions(id: MenuId, contextKeyService: IContextKeyService, options?: IMenuActionOptions): [
         string,
         Array<MenuItemAction | SubmenuItemAction>
     ][];
+    /**
+    * Gets the names of the contexts that this menu listens on.
+    */
     getMenuContexts(id: MenuId): ReadonlySet<string>;
+    /**
+    * Reset **all** menu item hidden states.
+    */
     resetHiddenStates(): void;
+    /**
+    * Reset the menu's hidden states.
+    */
     resetHiddenStates(menuIds: readonly MenuId[] | undefined): void;
 }

package/vscode/src/vs/platform/clipboard/common/clipboardService.service.d.ts

@@ -2,14 +2,47 @@ import { URI } from "../../../base/common/uri.js";
 export declare const IClipboardService: import("../../instantiation/common/instantiation.js").ServiceIdentifier<IClipboardService>;
 export interface IClipboardService {
     readonly _serviceBrand: undefined;
+    /**
+    * Trigger the paste. Returns undefined if the paste was not triggered or a promise that resolves on paste end.
+    */
     triggerPaste(targetWindowId: number): Promise<void> | undefined;
+    /**
+    * Writes text to the system clipboard.
+    */
     writeText(text: string, type?: string): Promise<void>;
+    /**
+    * Reads the content of the clipboard in plain text
+    */
     readText(type?: string): Promise<string>;
+    /**
+    * Reads text from the system find pasteboard.
+    */
     readFindText(): Promise<string>;
+    /**
+    * Writes text to the system find pasteboard.
+    */
     writeFindText(text: string): Promise<void>;
+    /**
+    * Writes resources to the system clipboard.
+    */
     writeResources(resources: URI[]): Promise<void>;
+    /**
+    * Reads resources from the system clipboard.
+    */
     readResources(): Promise<URI[]>;
+    /**
+    * Find out if resources are copied to the clipboard.
+    */
     hasResources(): Promise<boolean>;
+    /**
+    * Resets the internal state of the clipboard (if any) without touching the real clipboard.
+    *
+    * Used for implementations such as web which do not always support using the real clipboard.
+    */
     clearInternalState?(): void;
+    /**
+    * Reads resources from the system clipboard as an image. If the clipboard does not contain an
+    * image, an empty buffer is returned.
+    */
     readImage(): Promise<Uint8Array>;
 }

package/vscode/src/vs/platform/commands/common/commands.d.ts

@@ -18,6 +18,13 @@ export interface ICommand {
     metadata?: ICommandMetadata | null;
 }
 export interface ICommandMetadata {
+    /**
+     * NOTE: Please use an ILocalizedString. string is in the type for backcompat for now.
+     * A short summary of what the command does. This will be used in:
+     * - API commands
+     * - when showing keybindings that have no other UX
+     * - when searching for commands in the Command Palette
+     */
     readonly description: ILocalizedString | string;
     readonly args?: ReadonlyArray<{
         readonly name: string;

package/vscode/src/vs/platform/configuration/common/configuration.d.ts

@@ -70,7 +70,13 @@ export declare function isConfigured<T>(configValue: IConfigurationValue<T>): co
     value: T;
 };
 export interface IConfigurationUpdateOptions {
+    /**
+     * If `true`, do not notifies the error to user by showing the message box. Default is `false`.
+     */
     donotNotifyError?: boolean;
+    /**
+     * How to handle dirty file when updating the configuration.
+     */
     handleDirtyFile?: "save" | "revert";
 }
 export interface IConfigurationModel {
@@ -110,6 +116,9 @@ export declare function toValuesTree(properties: {
 }, conflictReporter: (message: string) => void): any;
 export declare function addToValueTree(settingsTreeRoot: any, key: string, value: any, conflictReporter: (message: string) => void): void;
 export declare function removeFromValueTree(valueTree: any, key: string): void;
+/**
+ * A helper function to get the configuration value with a specific settings path (e.g. config.some.setting)
+ */
 export declare function getConfigurationValue<T>(config: any, settingPath: string): T | undefined;
 export declare function getConfigurationValue<T>(config: any, settingPath: string, defaultValue: T): T;
 export declare function merge(base: any, add: any, overwrite: boolean): void;

package/vscode/src/vs/platform/configuration/common/configuration.service.d.ts

@@ -6,10 +6,36 @@ export interface IConfigurationService {
     readonly _serviceBrand: undefined;
     onDidChangeConfiguration: Event<IConfigurationChangeEvent>;
     getConfigurationData(): IConfigurationData | null;
+    /**
+    * Fetches the value of the section for the given overrides.
+    * Value can be of native type or an object keyed off the section name.
+    *
+    * @param section - Section of the configuration. Can be `null` or `undefined`.
+    * @param overrides - Overrides that has to be applied while fetching
+    *
+    */
     getValue<T>(): T;
     getValue<T>(section: string): T;
     getValue<T>(overrides: IConfigurationOverrides): T;
     getValue<T>(section: string, overrides: IConfigurationOverrides): T;
+    /**
+    * Update a configuration value.
+    *
+    * Use `target` to update the configuration in a specific `ConfigurationTarget`.
+    *
+    * Use `overrides` to update the configuration for a resource or for override identifiers or both.
+    *
+    * Passing a resource through overrides will update the configuration in the workspace folder containing that resource.
+    *
+    * *Note 1:* Updating configuration to a default value will remove the configuration from the requested target. If not target is passed, it will be removed from all writeable targets.
+    *
+    * *Note 2:* Use `undefined` value to remove the configuration from the given target. If not target is passed, it will be removed from all writeable targets.
+    *
+    * Use `donotNotifyError` and set it to `true` to surpresss errors.
+    *
+    * @param key setting to be updated
+    * @param value The new value
+    */
     updateValue(key: string, value: any): Promise<void>;
     updateValue(key: string, value: any, target: ConfigurationTarget): Promise<void>;
     updateValue(key: string, value: any, overrides: IConfigurationOverrides | IConfigurationUpdateOverrides): Promise<void>;