1// Copyright (C) 2024 The Android Open Source Project 2// 3// Licensed under the Apache License, Version 2.0 (the "License"); 4// you may not use this file except in compliance with the License. 5// You may obtain a copy of the License at 6// 7// http://www.apache.org/licenses/LICENSE-2.0 8// 9// Unless required by applicable law or agreed to in writing, software 10// distributed under the License is distributed on an "AS IS" BASIS, 11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12// See the License for the specific language governing permissions and 13// limitations under the License. 14 15// For now sections are fixed and cannot be extended by plugins. 16export const SIDEBAR_SECTIONS = { 17 navigation: { 18 title: 'Navigation', 19 summary: 'Open or record a new trace', 20 }, 21 current_trace: { 22 title: 'Current Trace', 23 summary: 'Actions on the current trace', 24 }, 25 convert_trace: { 26 title: 'Convert trace', 27 summary: 'Convert to other formats', 28 }, 29 example_traces: { 30 title: 'Example Traces', 31 summary: 'Open an example trace', 32 }, 33 support: { 34 title: 'Support', 35 summary: 'Documentation & Bugs', 36 }, 37} as const; 38 39export type SidebarSections = keyof typeof SIDEBAR_SECTIONS; 40 41export interface SidebarManager { 42 readonly enabled: boolean; 43 44 /** 45 * Adds a new menu item to the sidebar. 46 * All entries must map to a command. This will allow the shortcut and 47 * optional shortcut to be displayed on the UI. 48 */ 49 addMenuItem(menuItem: SidebarMenuItem): void; 50 51 /** 52 * Gets the current visibility of the sidebar. 53 */ 54 get visible(): boolean; 55 56 /** 57 * Toggles the visibility of the sidebar. Can only be called when 58 * `sidebarEnabled` returns `ENABLED`. 59 */ 60 toggleVisibility(): void; 61} 62 63export type SidebarMenuItem = { 64 readonly section: SidebarSections; 65 readonly sortOrder?: number; 66 67 // The properties below can be mutated by passing a callback rather than a 68 // direct value. The callback is invoked on every render frame, keep it cheap. 69 // readonly text: string | (() => string); 70 readonly icon?: string | (() => string); 71 readonly tooltip?: string | (() => string); 72 readonly cssClass?: string | (() => string); // Without trailing '.'. 73 74 // If false or omitted the item works normally. 75 // If true the item is striken through and the action/href will be a no-op. 76 // If a string, the item acts as disabled and clicking on it shows a popup 77 // that shows the returned text (the string has "disabled reason" semantic); 78 readonly disabled?: string | boolean | (() => string | boolean); 79 80 // One of the three following arguments must be specified. 81} & ( 82 | { 83 /** The text of the menu entry. Required. */ 84 readonly text: string | (() => string); 85 86 /** 87 * The URL to navigate to. It can be either: 88 * - A local route (e.g. ''#!/query'). 89 * - An absolute URL (e.g. 'https://example.com'). In this case the link will 90 * be open in a target=_blank new tag. 91 */ 92 readonly href: string; 93 } 94 | { 95 /** The text of the menu entry. Required. */ 96 readonly text: string | (() => string); 97 98 /** 99 * The function that will be invoked when clicking. If the function returns 100 * a promise, a spinner will be drawn next to the sidebar entry until the 101 * promise resolves. 102 */ 103 readonly action: () => unknown | Promise<unknown>; 104 105 /** Optional. If omitted href = '#'. */ 106 readonly href?: string; 107 } 108 | { 109 /** Optional. If omitted uses the command name. */ 110 readonly text?: string | (() => string); 111 112 /** The ID of the command that will be invoked when clicking */ 113 readonly commandId: string; 114 } 115); 116