@codingame/monaco-vscode-api 20.1.1 → 20.2.0

package/vscode/src/vs/base/browser/ui/toggle/toggle.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-custom-toggle {
 	margin-left: 2px;
 	float: left;
@@ -12,21 +17,26 @@
 	user-select: none;
 	-webkit-user-select: none;
 }
+
 .monaco-custom-toggle:hover {
 	background-color: var(--vscode-inputOption-hoverBackground);
 }
+
 .hc-black .monaco-custom-toggle:hover,
 .hc-light .monaco-custom-toggle:hover {
 	border: 1px dashed var(--vscode-focusBorder);
 }
+
 .hc-black .monaco-custom-toggle,
 .hc-light .monaco-custom-toggle {
 	background: none;
 }
+
 .hc-black .monaco-custom-toggle:hover,
 .hc-light .monaco-custom-toggle:hover {
 	background: none;
 }
+
 .monaco-custom-toggle.monaco-checkbox {
 	height: 18px;
 	width: 18px;
@@ -38,18 +48,22 @@
 	opacity: 1;
 	background-size: 16px !important;
 }
+
 .monaco-action-bar .checkbox-action-item {
 	display: flex;
 	align-items: center;
 	border-radius: 2px;
 	padding-right: 2px;
 }
+
 .monaco-action-bar .checkbox-action-item:hover {
 	background-color: var(--vscode-toolbar-hoverBackground);
 }
+
 .monaco-action-bar .checkbox-action-item > .monaco-custom-toggle.monaco-checkbox {
 	margin-right: 4px;
 }
+
 .monaco-action-bar .checkbox-action-item > .checkbox-label {
 	font-size: 12px;
 }

package/vscode/src/vs/base/browser/ui/toolbar/toolbar.css

@@ -1,6 +1,12 @@
+/*---------------------------------------------------------------------------------------------
+ *  Copyright (c) Microsoft Corporation. All rights reserved.
+ *  Licensed under the MIT License. See License.txt in the project root for license information.
+ *--------------------------------------------------------------------------------------------*/
+
 .monaco-toolbar {
 	height: 100%;
 }
+
 .monaco-toolbar .toolbar-toggle-more {
 	display: inline-block;
 	padding: 0;

package/vscode/src/vs/base/browser/ui/toolbar/toolbar.d.ts

@@ -19,10 +19,22 @@ export interface IToolBarOptions {
     allowContextMenu?: boolean;
     skipTelemetry?: boolean;
     hoverDelegate?: IHoverDelegate;
+    /**
+     * If true, toggled primary items are highlighted with a background color.
+     */
     highlightToggledItems?: boolean;
+    /**
+     * Render action with icons (default: `true`)
+     */
     icon?: boolean;
+    /**
+     * Render action with label (default: `false`)
+     */
     label?: boolean;
 }
+/**
+ * A widget that combines an action bar for primary actions and a dropdown for secondary actions.
+ */
 export declare class ToolBar extends Disposable {
     private options;
     protected readonly actionBar: ActionBar;

package/vscode/src/vs/base/browser/ui/tree/abstractTree.d.ts

@@ -298,6 +298,10 @@ export interface IAbstractTreeOptions<T, TFilterData = void> extends IAbstractTr
     readonly stickyScrollDelegate?: IStickyScrollDelegate<any, TFilterData>;
     readonly disableExpandOnSpacebar?: boolean;
 }
+/**
+ * The trait concept needs to exist at the tree level, because collapsed
+ * tree nodes will not be known by the list.
+ */
 declare class Trait<T> {
     private getFirstViewElementWithTrait;
     private identityProvider?;
@@ -320,6 +324,10 @@ interface ITreeNodeListOptions<T, TFilterData, TRef> extends IListOptions<ITreeN
     readonly tree: AbstractTree<T, TFilterData, TRef>;
     readonly stickyScrollProvider: () => StickyScrollController<T, TFilterData, TRef> | undefined;
 }
+/**
+ * We use this List subclass to restore selection and focus as nodes
+ * get rendered in the list, possibly due to a node expand() call.
+ */
 declare class TreeNodeList<T, TFilterData, TRef> extends List<ITreeNode<T, TFilterData>> {
     private focusTrait;
     private selectionTrait;
@@ -449,6 +457,10 @@ export declare abstract class AbstractTree<T, TFilterData, TRef> implements IDis
     getStickyScrollFocus(): T[];
     getFocusedPart(): AbstractTreePart;
     reveal(location: TRef, relativeTop?: number): void;
+    /**
+     * Returns the relative position of an element rendered in the list.
+     * Returns `null` if the element isn't *entirely* in the visible viewport.
+     */
     getRelativeTop(location: TRef): number | null;
     getViewState(identityProvider?: IIdentityProvider<T> | undefined): AbstractTreeViewState;
     private onLeftArrow;

package/vscode/src/vs/base/browser/ui/tree/asyncDataTree.d.ts

@@ -32,9 +32,24 @@ export interface IAsyncFindResult<T> {
     isMatch(element: T): boolean;
 }
 export interface IAsyncFindProvider<T> {
+    /**
+     * `startSession` is called when the user enters the first character in the find widget.
+     * This can be used to allocate some state to preserve for the session.
+     */
     startSession?(): void;
+    /**
+     * `find` is called when the user types one or more character into the find input.
+     */
     find(pattern: string, toggles: IAsyncFindToggles, token: CancellationToken): Promise<IAsyncFindResult<T> | undefined>;
+    /**
+     * `isVisible` is called to check if an element should be visible.
+     * For an element to be visible, all its ancestors must also be visible and the label must match the find pattern.
+     */
     isVisible?(element: T): boolean;
+    /**
+     * End Session is called when the user either closes the find widget or has an empty find input.
+     * This can be used to deallocate any state that was allocated.
+     */
     endSession?(): Promise<void>;
 }
 export interface IAsyncDataTreeOptionsUpdate extends IAbstractTreeOptionsUpdate {
@@ -89,6 +104,10 @@ export declare class AsyncDataTree<TInput, T, TFilterData = void> implements IDi
     get onPointer(): Event<ITreeMouseEvent<T>>;
     get onDidFocus(): Event<void>;
     get onDidBlur(): Event<void>;
+    /**
+     * To be used internally only!
+     * @deprecated
+     */
     get onDidChangeModel(): Event<void>;
     get onDidChangeCollapseState(): Event<ICollapseStateChangeEvent<IAsyncDataTreeNode<TInput, T> | null, TFilterData>>;
     get onDidUpdateOptions(): Event<IAsyncDataTreeOptionsUpdate>;

package/vscode/src/vs/base/browser/ui/tree/indexTreeModel.d.ts

@@ -23,9 +23,27 @@ export interface IIndexTreeModelOptions<T, TFilterData> {
     readonly autoExpandSingleChildren?: boolean;
 }
 export interface IIndexTreeModelSpliceOptions<T, TFilterData> {
+    /**
+     * If set, child updates will recurse the given number of levels even if
+     * items in the splice operation are unchanged. `Infinity` is a valid value.
+     */
     readonly diffDepth?: number;
+    /**
+     * Identity provider used to optimize splice() calls in the IndexTree. If
+     * this is not present, optimized splicing is not enabled.
+     *
+     * Warning: if this is present, calls to `setChildren()` will not replace
+     * or update nodes if their identity is the same, even if the elements are
+     * different. For this, you should call `rerender()`.
+     */
     readonly diffIdentityProvider?: IIdentityProvider<T>;
+    /**
+     * Callback for when a node is created.
+     */
     onDidCreateNode?: (node: ITreeNode<T, TFilterData>) => void;
+    /**
+     * Callback for when a node is deleted.
+     */
     onDidDeleteNode?: (node: ITreeNode<T, TFilterData>) => void;
 }
 export declare class IndexTreeModel<T extends Exclude<any, undefined>, TFilterData = void> implements ITreeModel<T, TFilterData, number[]> {

package/vscode/src/vs/base/browser/ui/tree/media/tree.css

@@ -1,9 +1,15 @@
+/*---------------------------------------------------------------------------------------------
+ *  Copyright (c) Microsoft Corporation. All rights reserved.
+ *  Licensed under the MIT License. See License.txt in the project root for license information.
+ *--------------------------------------------------------------------------------------------*/
+
 .monaco-tl-row {
 	display: flex;
 	height: 100%;
 	align-items: center;
 	position: relative;
 }
+
 .monaco-tl-row.disabled {
 	cursor: default;
 }
@@ -14,9 +20,11 @@
 	left: 16px;
 	pointer-events: none;
 }
+
 .hide-arrows .monaco-tl-indent {
 	left: 12px;
 }
+
 .monaco-tl-indent > .indent-guide {
 	display: inline-block;
 	box-sizing: border-box;
@@ -24,13 +32,16 @@
 	border-left: 1px solid transparent;
 	opacity: 0;
 }
+
 .monaco-workbench:not(.reduce-motion) .monaco-tl-indent > .indent-guide {
 	transition: opacity 0.1s linear;
 }
+
 .monaco-tl-twistie,
 .monaco-tl-contents {
 	height: 100%;
 }
+
 .monaco-tl-twistie {
 	font-size: 10px;
 	text-align: right;
@@ -42,19 +53,25 @@
 	justify-content: center;
 	transform: translateX(3px);
 }
+
 .monaco-tl-contents {
 	flex: 1;
 	overflow: hidden;
 }
+
 .monaco-tl-twistie::before {
 	border-radius: 20px;
 }
+
 .monaco-tl-twistie.collapsed::before {
 	transform: rotate(-90deg);
 }
+
 .monaco-tl-twistie.codicon-tree-item-loading::before {
+	/* Use steps to throttle FPS to reduce CPU usage */
 	animation: codicon-spin 1.25s steps(30) infinite;
 }
+
 .monaco-tree-type-filter {
 	position: absolute;
 	top: 0;
@@ -68,62 +85,80 @@
 	border-bottom-left-radius: 4px;
 	border-bottom-right-radius: 4px;
 }
+
 .monaco-workbench:not(.reduce-motion) .monaco-tree-type-filter {
 	transition: top 0.3s;
 }
+
 .monaco-tree-type-filter.disabled {
 	top: -40px !important;
 }
+
 .monaco-tree-type-filter-input {
 	flex: 1;
 }
+
 .monaco-tree-type-filter-input .monaco-inputbox {
 	height: 23px;
 }
+
 .monaco-tree-type-filter-input .monaco-inputbox > .ibwrapper > .input,
 .monaco-tree-type-filter-input .monaco-inputbox > .ibwrapper > .mirror {
 	padding: 2px 4px;
 }
+
 .monaco-tree-type-filter-input .monaco-findInput > .controls {
 	top: 2px;
 }
+
 .monaco-tree-type-filter-actionbar {
 	margin-left: 4px;
 }
+
 .monaco-tree-type-filter-actionbar .monaco-action-bar .action-label {
 	padding: 2px;
 }
+
 .monaco-list .monaco-scrollable-element .monaco-tree-sticky-container{
 	position: absolute;
 	top: 0;
 	left: 0;
 	width: 100%;
 	height: 0;
-	z-index: 13;
+	z-index: 13; /* Settings editor uses z-index: 12 */
+
+	/* Backup color in case the tree does not provide the background color */
 	background-color: var(--vscode-sideBar-background);
 }
+
 .monaco-list .monaco-scrollable-element .monaco-tree-sticky-container .monaco-tree-sticky-row.monaco-list-row{
 	position: absolute;
 	width: 100%;
-	opacity: 1 !important;
+	opacity: 1 !important; /* Settings editor uses opacity < 1 */
 	overflow: hidden;
+
+	/* Backup color in case the tree does not provide the background color */
 	background-color: var(--vscode-sideBar-background);
 }
+
 .monaco-list .monaco-scrollable-element .monaco-tree-sticky-container .monaco-tree-sticky-row:hover{
 	background-color: var(--vscode-list-hoverBackground) !important;
 	cursor: pointer;
 }
+
 .monaco-list .monaco-scrollable-element .monaco-tree-sticky-container.empty,
 .monaco-list .monaco-scrollable-element .monaco-tree-sticky-container.empty .monaco-tree-sticky-container-shadow {
 	display: none;
 }
+
 .monaco-list .monaco-scrollable-element .monaco-tree-sticky-container .monaco-tree-sticky-container-shadow {
 	position: absolute;
 	bottom: -3px;
 	left: 0px;
-	height: 0px;
+	height: 0px; /* heigt is 3px and only set when there is a treeStickyScrollShadow color */
 	width: 100%;
 }
+
 .monaco-list .monaco-scrollable-element .monaco-tree-sticky-container[tabindex="0"]:focus{
 	outline: none;
 }

package/vscode/src/vs/base/browser/ui/tree/objectTree.d.ts

@@ -8,7 +8,19 @@ export interface IObjectTreeOptions<T, TFilterData = void> extends IAbstractTree
     readonly sorter?: ITreeSorter<T>;
 }
 export interface IObjectTreeSetChildrenOptions<T> {
+    /**
+     * If set, child updates will recurse the given number of levels even if
+     * items in the splice operation are unchanged. `Infinity` is a valid value.
+     */
     readonly diffDepth?: number;
+    /**
+     * Identity provider used to optimize splice() calls in the IndexTree. If
+     * this is not present, optimized splicing is not enabled.
+     *
+     * Warning: if this is present, calls to `setChildren()` will not replace
+     * or update nodes if their identity is the same, even if the elements are
+     * different. For this, you should call `rerender()`.
+     */
     readonly diffIdentityProvider?: IIdentityProvider<T>;
 }
 export declare class ObjectTree<T extends NonNullable<any>, TFilterData = void> extends AbstractTree<T | null, TFilterData, T | null> {

package/vscode/src/vs/base/browser/ui/tree/tree.d.ts

@@ -4,16 +4,53 @@ import { IListDragAndDrop, IListDragOverReaction, IListElementRenderDetails, ILi
 import { ListViewTargetSector } from "../list/listView.js";
 import { Event } from "../../../common/event.js";
 export declare enum TreeVisibility {
+    /**
+     * The tree node should be hidden.
+     */
     Hidden = 0,
+    /**
+     * The tree node should be visible.
+     */
     Visible = 1,
+    /**
+     * The tree node should be visible if any of its descendants is visible.
+     */
     Recurse = 2
 }
+/**
+ * A composed filter result containing the visibility result as well as
+ * metadata.
+ */
 export interface ITreeFilterDataResult<TFilterData> {
+    /**
+     * Whether the node should be visible.
+     */
     visibility: boolean | TreeVisibility;
+    /**
+     * Metadata about the element's visibility which gets forwarded to the
+     * renderer once the element gets rendered.
+     */
     data: TFilterData;
 }
+/**
+ * The result of a filter call can be a boolean value indicating whether
+ * the element should be visible or not, a value of type `TreeVisibility` or
+ * an object composed of the visibility result as well as additional metadata
+ * which gets forwarded to the renderer once the element gets rendered.
+ */
 export type TreeFilterResult<TFilterData> = boolean | TreeVisibility | ITreeFilterDataResult<TFilterData>;
+/**
+ * A tree filter is responsible for controlling the visibility of
+ * elements in a tree.
+ */
 export interface ITreeFilter<T, TFilterData = void> {
+    /**
+     * Returns whether this elements should be visible and, if affirmative,
+     * additional metadata which gets forwarded to the renderer once the element
+     * gets rendered.
+     *
+     * @param element The tree element.
+     */
     filter(element: T, parentVisibility: TreeVisibility): TreeFilterResult<TFilterData>;
 }
 export interface ITreeSorter<T> {
@@ -28,7 +65,13 @@ export interface ITreeElement<T> {
 export declare enum ObjectTreeElementCollapseState {
     Expanded = 0,
     Collapsed = 1,
+    /**
+     * If the element is already in the tree, preserve its current state. Else, expand it.
+     */
     PreserveOrExpanded = 2,
+    /**
+     * If the element is already in the tree, preserve its current state. Else, collapse it.
+     */
     PreserveOrCollapsed = 3
 }
 export interface IObjectTreeElement<T> {

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

@@ -92,6 +92,9 @@ export declare class ActionRunner extends Disposable implements IActionRunner {
     protected runAction(action: IAction, context?: unknown): Promise<void>;
 }
 export declare class Separator implements IAction {
+    /**
+     * Joins all non-empty lists of actions with separators.
+     */
     static join(...actionLists: readonly IAction[][]): IAction[];
     static readonly ID = "vs.actions.separator";
     readonly id: string;