import type { Primitive } from 'utility-types' import type { Expression, TemplateExpression } from '@sourcegraph/template-parser' /** * A key path that refers to a location in a JSON document. * * Each successive array element specifies an index in an object or array to descend into. For example, in the * object `{"a": ["x", "y"]}`, the key path `["a", 1]` refers to the value `"y"`. */ export type KeyPath = (string | number)[] /** * The given contribution type as it's specified in a package.json (expressions as strings) */ export type Raw = { [K in keyof TContribution]: RawValue } // need a type alias so union types (including undefined for optional properties) distribute type RawValue = V extends Expression ? string : V extends Primitive | null | undefined ? V : Raw /** * The given contribution type after being evaluated (all expressions replaced with their value) */ export type Evaluated = { [K in keyof TContribution]: EvaluatedValue } // need a type alias so union types (including undefined for optional properties) distribute type EvaluatedValue = V extends Expression ? T : V extends Primitive | null | undefined ? V : Evaluated /** * Describes the functionality provided by an extension. */ export interface Contributions { /** Actions contributed by the extension. */ actions?: ActionContribution[] /** Menu items contributed by the extension. */ menus?: MenuContributions /** Search filters contributed by the extension */ searchFilters?: SearchFilters[] } /** * An action contribution describes a command that can be invoked, along with a title, description, icon, etc. */ export interface ActionContribution { /** * The identifier for this action, which must be unique among all contributed actions. * * Extensions: By convention, this is a dotted string of the form `myExtensionName.myActionName`. It is common * to use the same values for `id` and `command` (for the common case where the command has only one action * that mentions it). */ id: string /** * The command that this action invokes. It can refer to a command registered by the same * extension or any other extension, or to a builtin command. If it is undefined, the action is * a noop. * * See "[Builtin commands](../../../../doc/extensions/authoring/builtin_commands.md)" (online at * https://sourcegraph.com/docs/extensions/authoring/builtin_commands) for documentation on * builtin client commands. * * Extensions: The command must be registered (unless it is a builtin command). Extensions can * register commands using {@link sourcegraph.commands.registerCommand}. * * Clients: All clients must implement the builtin commands as specified in the documentation * above. If the command is undefined (which means the action is a noop), the action should be * displayed in such a way that avoids suggesting it can be clicked/activated (e.g., there * should not be any hover or active state on the button). * * @see ActionContributionClientCommandOpen * @see ActionContributionClientCommandUpdateConfiguration */ command?: string /** * Optional arguments to pass to the extension when the action is invoked. * Strings are interpreted as template strings, any other value is taken as-is. */ commandArguments?: (TemplateExpression | number | boolean | null | object | any[])[] /** The title that succinctly describes what this action does. The question * mark '?' renders the MDI HelpCircleOutline icon. */ title?: TemplateExpression /** The title that succinctly describes what this action is even though it's disabled. */ disabledTitle?: TemplateExpression /** * The category that describes the group of related actions of which this action is a member. * * Clients: When displaying this action's title alongside titles of actions from other groups, the client * should display each action as "${category}: ${title}" if the prefix is set. */ category?: TemplateExpression /** * A longer description of the action taken by this action. * * Extensions: The description should not be unnecessarily repetitive with the title. * * Clients: If the description is shown, the title must be shown nearby. */ description?: TemplateExpression /** * A URL to an icon for this action (data: URIs are OK). * * Clients: The client should show this icon before the title, proportionally scaling the dimensions as * necessary to avoid unduly enlarging the item beyond the dimensions necessary to render the text. The client * should assume the icon is square (or roughly square). The client must not display a border around the icon. * The client may choose not to display this icon. */ iconURL?: TemplateExpression /** * A specification of how to display this action as a button on a toolbar. The client is responsible for * displaying contributions and defining which parts of its interface are considered to be toolbars. Generally, * items on a toolbar are always visible and, compared to items in a dropdown menu or list, are expected to be * smaller and to convey information (in addition to performing an action). * * For example, a "Toggle code coverage" action may prefer to display a summarized status (such as "Coverage: * 77%") on a toolbar instead of the full title. * * Clients: If the label is empty and only an iconURL is set, and the client decides not to display the icon * (e.g., because the client is not graphical), then the client may hide the item from the toolbar. */ actionItem?: ActionItem /** * Properties to enable event telemetry to be recorded when an action is executed. */ telemetryProps: { /** * feature must be camelCase and '.'-delimited, e.g. 'myFeature.subFeature'. * * Most ActionContribution features should be prefixed with 'blob.' to indicate that they are actions * that occur on text blobs. */ feature: string // No `action` prop is provided, because action items only log telemetry when executed (and thus use an // 'executed' action. privateMetadata?: { [key: string]: any } } } /** * Narrows the type of {@link ActionContribution} for actions that invoke the `open` client command. */ export interface ActionContributionClientCommandOpen extends ActionContribution { command: 'open' /** * The arguments for the `open` client command, which can either have one or two elements. * * - The first array element is always a string with the destination URL, * which populates the `href` attribute of the link. * - When defined, the second array element is an `(event: MouseEvent | KeyboardEvent) => boolean` * handler that fires `onSelect`. The handler is responsible for handling low-level details like whether * the user is holding down modifier keys, or if `event.preventDefault()` should be triggered. The handler * can return `false` to fallback to the default event handler. */ commandArguments: [TemplateExpression] | [TemplateExpression, TemplateExpression] } /** * Narrows the type of {@link ActionContribution} for actions that invoke the `updateConfiguration` client command. */ export interface ActionContributionClientCommandUpdateConfiguration extends ActionContribution { command: 'updateConfiguration' /** * The arguments for the `updateConfiguration` client command: * * 1. The key path of the value (in the configuration settings) to update * 2. The value to insert at the key path * 3. Optional: reserved for future use (must always be `null`) * 4. Optional: 'json' if the client should parse the 2nd argument using JSON.parse before inserting the value */ commandArguments: | [KeyPath, TemplateExpression | number | boolean | object | any[] | null] | [KeyPath, TemplateExpression, null, TemplateExpression<'json'>] } /** * A description of how to display an {@link ActionContribution} on a toolbar, * with all template properties interpolated, and all expression properties replaced * by their evaluated value. * * This value is set on the {@link ActionContribution#actionItem} interface field * (it always is directly associated with an {@link ActionContribution}). * * It is necessary because an action's ({@link ActionContribution}'s) fields are intended for display in a command * palette or list, not in a button. The {@link ActionContribution} fields usually have long, descriptive text * values, and it does not make sense for them to show an icon. When the action is displayed as a button, however, * it needs to have a much shorter text label and it often does make sense to show an icon. Therefore, the action's * representation as a command in a list ({@link ActionContribution}) is separate from its representation as a * button (in this type, {@link ActionItem}). * * Example: Consider a code coverage extension that adds an action to toggle showing coverage overlays on a file. * The command title ({@link ActionContribution#title}) might be "Show/hide code coverage overlays", and the button * label ({@link ActionItem#label}) would be "Coverage: 78%" (where the "78%" is the live coverage ratio). * * It is convenient to be able to specify both the command and button display representations of an action * together, which is why {@link ActionItem} is in the field {@link ActionContribution#actionItem} instead of being * listed as a separate contribution. They share most behavior and many other fields, so it reduces the amount of * duplicate code to combine them. Also, some clients may not be able to display buttons and need to display the * more verbose command form of an action, which is possible when they are combined. */ export interface ActionItem { /** The text label for this item. */ label?: Expression /** * A description associated with this action item. * * Clients: The description should be shown in a tooltip when the user focuses or hovers this toolbar item. */ description?: Expression /** * The icon URL for this action (data: URIs are OK). * * Clients: The client should this icon before the label (if any), proportionally scaling the dimensions as * necessary to avoid unduly enlarging the toolbar item beyond the dimensions necessary to show the label. * In space-constrained situations, the client should show only the icon and omit the label. The client * must not display a border around the icon. The client may choose not to display this icon. */ iconURL?: Expression /** * A description of the information represented by the icon. * * Clients: The client should not display this text directly. Instead, the client should use the * accessibility facilities of the client's platform (such as the attribute) to make it available * to users needing the textual description. */ iconDescription?: Expression /** * Whether the action item should be rendered as a pressed button. */ pressed?: Expression } export enum ContributableMenu { /** The global navigation bar in the application. */ GlobalNav = 'global/nav', /** The title bar for the current document. */ EditorTitle = 'editor/title', /** A directory page (including for the root directory of a repository). */ DirectoryPage = 'directory/page', /** The hover tooltip. */ Hover = 'hover', /** The panel toolbar. */ PanelToolbar = 'panel/toolbar', /** The search results toolbar. */ SearchResultsToolbar = 'search/results/toolbar', /** The help menu in the application. */ Help = 'help', } /** * MenuContributions describes the menu items contributed by an extension. */ export interface MenuContributions extends Partial> {} /** * MenuItemContribution is a menu item contributed by an extension. */ export interface MenuItemContribution { /** * The action to invoke when the item is selected. The value refers to a {@link ActionContribution#id} value. */ action: string /** * An alternative action to invoke when the item is selected while pressing the Option/Alt/Meta/Ctrl/Cmd keys * or using the middle mouse button. The value refers to a {@link ActionContribution#id} value. */ alt?: string /** * An expression that, if given, must evaluate to true (or a truthy value) for this contribution to be * displayed. The expression may use values from the context in which the contribution would be displayed. */ when?: Expression /** * An expression that, if given, must evaluate to true (or a truthy value) for this contribution to be * disabled. The expression may use values from the context in which the contribution would be displayed. */ disabledWhen?: Expression /** * The group in which this item is displayed. This defines the sort order of menu items. The group value is an * opaque string (it is just compared relative to other items' group values); there is no specification set of * expected or supported values. * * Clients: On a toolbar, the client should sort toolbar items by (group, action), with toolbar items lacking a * group sorting last. The client must not display the group value. */ group?: string } /** * A search filters interface with `name` and `value` to display on a filter chip * in the search results filters bar. */ export interface SearchFilters { /** * The name to be displayed on the search filter chip. */ name: string /** * The value of the search filter chip (i.e. the literal search query string). */ value: string }