@pstdio/workbench 0.5.0 → 0.6.0

package/dist/index.d.ts

@@ -176,6 +176,70 @@ declare interface CommandRegistryStoreState {
     commands: Record<string, RegisteredCommand>;
 }
 
+export declare interface CompositionDiagnostic {
+    code: "extension_resource_kind_missing" | "extension_resource_slot_missing" | "extension_resource_slot_closed" | "extension_panel_missing" | "extension_panel_placement_unresolvable" | "extension_mode_resource_unsupported" | "extension_placement_required_invalid" | "extension_resource_primary_invalid";
+    message: string;
+    panelId?: string;
+    slot?: string;
+}
+
+export declare interface CompositionModeDefinition {
+    id: string;
+    extensionId?: string;
+    resources?: Record<string, CompositionModeRecipe>;
+    modePanels?: Record<string, CompositionPlacementPolicy>;
+}
+
+export declare interface CompositionModeRecipe {
+    slots?: Record<string, CompositionPlacementPolicy>;
+    panels?: Record<string, CompositionPlacementPolicy>;
+}
+
+export declare interface CompositionPanelDefinition {
+    id: string;
+    extensionId: string;
+    title: string;
+    icon?: string;
+    show?: CompositionPanelPlacement | readonly CompositionPanelPlacement[];
+}
+
+declare interface CompositionPanelPlacement extends CompositionPlacementPolicy {
+    resourceKind?: string;
+}
+
+export declare interface CompositionPlacementPolicy {
+    region: DockedCompositionRegion;
+    allowedRegions?: readonly DockedCompositionRegion[];
+    required?: boolean;
+    defaultOpen?: boolean;
+    pinned?: boolean;
+}
+
+declare interface CompositionResolutionContext {
+    modeId: string;
+    resourceKind?: string;
+}
+
+export declare interface CompositionResourceKindDefinition {
+    id: string;
+    extensionId: string;
+    surface: "primary" | "secondary" | "attached";
+    slots: Record<string, CompositionSlotDefinition>;
+}
+
+export declare interface CompositionResourcePanelEdge {
+    id: string;
+    extensionId: string;
+    resourceKind: string;
+    panel: string;
+    slot: string;
+}
+
+export declare interface CompositionSlotDefinition {
+    cardinality: "one" | "many";
+    external: boolean;
+}
+
 export declare interface ContextKeyScope extends Disposable_2 {
     ownerId: string;
     set(key: string, value: ContextKeyValue): void;
@@ -373,7 +437,7 @@ export declare interface DataTableRendererContribution {
     emptyDescription?: string;
     executeQuery(context: DataTableRendererQueryContext): Promise<DataTableRendererQueryResult> | DataTableRendererQueryResult;
     subscribe?: (listener: () => void) => Disposable_2 | (() => void);
-    onRowClick?: (row: DataTableRendererRow) => void;
+    onRowActivate?: (row: DataTableRendererRow) => Promise<void> | void;
 }
 
 export declare type DataTableRendererImplementation = (input: WorkbenchPanelRenderInput & {
@@ -444,6 +508,10 @@ declare interface Disposable_2 {
 }
 export { Disposable_2 as Disposable }
 
+export declare type DockedCompositionRegion = (typeof dockedCompositionRegions)[number];
+
+export declare const dockedCompositionRegions: readonly ["sidenav", "main", "secondary", "side"];
+
 export declare interface EnumOption {
     value: string;
     label: string;
@@ -503,6 +571,8 @@ export declare interface FileRendererContent {
     content?: string;
     dataUrl?: string;
     placeholder?: string;
+    /** Ordered backing-store revision when one is available. */
+    revision?: string;
 }
 
 export declare interface FileRendererContribution {
@@ -512,35 +582,53 @@ export declare interface FileRendererContribution {
     /** Resolve the file's content (and identity) for the bound resource. */
     load(resource: ResourceRef | undefined): Promise<FileRendererContent> | FileRendererContent;
     /** Persist edited text. Absent ⇒ read-only. Never called for images. */
-    save?(resource: ResourceRef | undefined, content: string): Promise<void> | void;
+    save?(resource: ResourceRef | undefined, content: string, origin?: FileRendererRefreshOrigin): Promise<FileRendererSaveResult | undefined> | FileRendererSaveResult | void;
 }
 
 export declare type FileRendererImplementation = (input: WorkbenchPanelRenderInput & {
     fileRendererId: string;
 }) => unknown;
 
-declare interface FileRendererRefreshEvent {
+export declare interface FileRendererRefreshEnvelope {
+    resourceUri?: string;
+    origin?: FileRendererRefreshOrigin;
+    revision?: string;
+}
+
+export declare interface FileRendererRefreshEvent extends FileRendererRefreshEnvelope {
     fileRendererId: string;
 }
 
 declare type FileRendererRefreshListener = (event: FileRendererRefreshEvent) => void;
 
+export declare interface FileRendererRefreshOrigin {
+    rendererId: string;
+    instanceId: string;
+    operationId: string;
+}
+
 export declare interface FileRendererRegistry {
     fileRendererStore: WorkbenchStore<FileRendererStoreState>;
     registerFileRenderer(contribution: FileRendererContribution, metadata?: ContributionMetadata): Disposable_2;
     setFileRendererImplementation(impl: FileRendererImplementation): void;
     getFileRenderer(id: string): RegisteredFileRendererContribution | undefined;
     listFileRenderers(): RegisteredFileRendererContribution[];
-    refreshFileRenderer(id: string): void;
+    refreshFileRenderer(id: string, event?: FileRendererRefreshEnvelope): void;
     onDidRefreshFileRenderer(listener: FileRendererRefreshListener): Disposable_2;
 }
 
+export declare interface FileRendererSaveResult {
+    revision?: string;
+}
+
 declare interface FileRendererStoreState {
     renderers: Record<string, RegisteredFileRendererContribution>;
 }
 
 export declare const getKeybindingSteps: (keybinding: KeybindingSequence) => string[];
 
+export declare const getSwitchModeNavigationTargetModeId: (target: NavigationTarget) => string | undefined;
+
 export declare const getWorkbenchModePanelForRegion: (region: WorkbenchRegion) => "main" | "secondary" | "side" | undefined;
 
 export declare const getWorkbenchSelectionResourceUris: (resource: ResourceRef | undefined) => string[];
@@ -551,6 +639,8 @@ export declare const headerTrailingMenuPath: (region: string) => MenuPath;
 
 export declare interface HistoryController {
     store: WorkbenchStore<HistoryStoreState>;
+    /** Snapshot the history for a compound navigation; the returned function restores it. */
+    createCheckpoint(): () => void;
     goBack(): HistoryEntry | undefined;
     goForward(): HistoryEntry | undefined;
     goPrevious(): HistoryEntry | undefined;
@@ -578,6 +668,8 @@ export declare interface KanbanRendererContribution<TRow extends KanbanRendererR
     id: string;
     title: string;
     resourceKind?: string;
+    /** Host-owned scope for persisted display settings. */
+    storageScope?: string;
     /**
      * Declarative attribute schema. The renderer dispatches filter / group /
      * sort / display / inline-edit behavior on each descriptor's `type.kind`.
@@ -605,8 +697,8 @@ export declare interface KanbanRendererContribution<TRow extends KanbanRendererR
      */
     executeQuery(state: KanbanRendererQueryState): Promise<TRow[]> | TRow[];
     subscribe?: (listener: () => void) => Disposable_2 | (() => void);
-    /** Row interactions surfaced by the renderer (mirrored from <KanbanRenderer>). */
-    onRowClick?: (row: TRow) => void;
+    /** Row activation surfaced by the renderer (mirrored from <KanbanRenderer>). */
+    onRowActivate?: (row: TRow) => Promise<void> | void;
     /** Per-row right-click context menu actions (mirrored from <KanbanRenderer>). */
     getRowContextMenuActions?: (row: TRow) => ResourceContextAction[];
     /**
@@ -700,7 +792,7 @@ export declare interface KanbanRendererRow {
     title: string;
     /**
      * Optional navigation handle. When set, the renderer's default click handler
-     * routes through the contribution's onRowClick (which typically opens the
+     * routes through the contribution's onRowActivate (which typically opens the
      * resource via the workbench).
      */
     resource?: unknown;
@@ -810,6 +902,16 @@ declare interface LayoutModel {
         carryRegionState?: readonly WorkbenchRegion[];
     }): void;
     getPersistenceScope(): LayoutScope | undefined;
+    /** True when the current persistence scope already stores a layout. A new scope returns false. */
+    /** Whether anything is stored for the active scope right now. */
+    hasPersistedLayout(): boolean;
+    /**
+     * Whether the active scope was entered with a layout the user already had. Unlike
+     * `hasPersistedLayout`, writes made while entering a mode do not change the answer.
+     */
+    enteredWithPersistedLayout(): boolean;
+    /** Moves owned panel menus beside their owner's current region and removes orphan menus. */
+    reconcilePanelMenus(): void;
     onWillChangePersistenceScope(listener: (scope: LayoutScope | undefined) => void): {
         dispose(): void;
     };
@@ -946,6 +1048,7 @@ declare interface OpenWidgetInput {
     resource?: ResourceRef;
     title?: string;
     region?: WorkbenchRegion;
+    role?: WorkbenchWidgetRole;
     ownerId?: string;
     source?: ContributionSource;
     pinned?: boolean;
@@ -963,13 +1066,24 @@ export declare interface OpenWorkbenchPanelInput {
     resource?: ResourceRef;
     title?: string;
     region?: WorkbenchRegion;
+    role?: WorkbenchWidgetRole;
     pinned?: boolean;
+    closable?: boolean;
     mountStrategy?: WorkbenchPanelMountStrategy;
     hiddenByDefault?: boolean;
     tab?: WorkbenchPanelTab;
     strategy?: WorkbenchPanelOpenStrategy;
 }
 
+export declare interface PersistedCompositionLayout {
+    regions: Partial<Record<DockedCompositionRegion, PersistedCompositionRegionState>>;
+}
+
+declare interface PersistedCompositionRegionState {
+    order: readonly string[];
+    activePanelId?: string;
+}
+
 export declare interface PersistedTreeRendererStates {
     statesByTreeId: Record<string, TreeRendererState>;
 }
@@ -1092,7 +1206,6 @@ declare type RegisteredWidgetContribution = Omit<WidgetContribution, "priority"
     ownedPanelMenuIds?: readonly string[];
     singleton: boolean;
     reuse: WidgetReusePolicy;
-    role: WorkbenchWidgetRole;
 } & RegisteredContributionMetadata;
 
 declare interface RegisteredWorkbenchNotification extends RegisteredContributionMetadata {
@@ -1108,6 +1221,44 @@ declare interface RegisteredWorkbenchNotification extends RegisteredContribution
 
 export declare const resolveAnchorRegion: (anchorId: AnchorId) => "status" | "nav" | "activity" | "sidenav-header" | "sidenav" | "main-header" | "main-left-menu" | "main" | "main-right-menu" | "secondary-header" | "secondary-left-menu" | "secondary" | "secondary-right-menu" | "side-header" | "side-left-menu" | "side" | "side-right-menu" | "overlay";
 
+export declare const resolveComposition: (input: ResolveCompositionInput) => ResolvedComposition;
+
+declare interface ResolveCompositionInput {
+    context: CompositionResolutionContext;
+    mode: CompositionModeDefinition;
+    composition: WorkbenchComposition;
+    persisted?: PersistedCompositionLayout;
+}
+
+export declare interface ResolvedComposition {
+    placements: readonly ResolvedCompositionPlacement[];
+    regionOrder: Partial<Record<DockedCompositionRegion, readonly string[]>>;
+    activePanelIds: Partial<Record<DockedCompositionRegion, string>>;
+    addablePanels: readonly ResolvedCompositionAddablePanel[];
+    diagnostics: readonly CompositionDiagnostic[];
+    requiredFallback?: {
+        panelId: string;
+    };
+}
+
+export declare interface ResolvedCompositionAddablePanel {
+    panelId: string;
+    region: DockedCompositionRegion;
+    allowedRegions: readonly DockedCompositionRegion[];
+    pinned?: boolean;
+}
+
+export declare interface ResolvedCompositionPlacement {
+    panelId: string;
+    region: DockedCompositionRegion;
+    slot?: string;
+    required: boolean;
+    defaultOpen: boolean;
+    pinned?: boolean;
+    allowedRegions: readonly DockedCompositionRegion[];
+    origin: "persisted" | "required" | "default";
+}
+
 declare type ResolvedResourceHierarchyProvider = Required<ResourceHierarchyProvider>;
 
 declare type ResolvedResourcePresenter = Required<ResourcePresenter>;
@@ -1134,6 +1285,14 @@ export declare interface ResourceContextAction {
 
 export declare const resourceContextMenuPath: (resourceKind: string) => MenuPath;
 
+export declare interface ResourceHierarchyCycle {
+    code: typeof resourceHierarchyCycleCode;
+    path: ResourceRef[];
+    repeatedUri: string;
+}
+
+export declare const resourceHierarchyCycleCode = "resource_hierarchy_cycle";
+
 export declare interface ResourceHierarchyProvider {
     id: string;
     priority?: number;
@@ -1197,6 +1356,7 @@ export declare interface ResourceRegistry {
     registerHierarchyProvider(provider: ResourceHierarchyProvider): Disposable_2;
     listHierarchyProviders(): ResolvedResourceHierarchyProvider[];
     walkHierarchy(resource: ResourceRef | undefined): ResourceRef[];
+    onDidDetectHierarchyCycle(listener: (cycle: ResourceHierarchyCycle) => void): Disposable_2;
     isOpeningResource(): boolean;
     openResource(resource: ResourceRef, input?: OpenResourceInput): Promise<WorkbenchPanelInstance>;
     onDidOpenResource(listener: (resource: ResourceRef) => void): Disposable_2;
@@ -1483,7 +1643,6 @@ declare interface WidgetContribution {
     priority?: number;
     rendererId: string;
     openCommandId?: string;
-    role?: WorkbenchWidgetRole;
     eligibleLocations?: WorkbenchLocationEligibility;
     panelMenuOwner?: WorkbenchPanelMenuOwner;
     tab?: WorkbenchWidgetTab;
@@ -1583,6 +1742,26 @@ declare interface WorkbenchCommandParamsRequest {
     context?: WorkbenchCommandExecutionContext;
 }
 
+export declare interface WorkbenchComposition {
+    resourceKinds: readonly CompositionResourceKindDefinition[];
+    panels: readonly CompositionPanelDefinition[];
+    resourcePanels: readonly CompositionResourcePanelEdge[];
+}
+
+declare interface WorkbenchCompositionAddablePanel extends WorkbenchModeAddablePanel {
+    contribution: RegisteredWidgetContribution;
+}
+
+declare interface WorkbenchCompositionController {
+    panelsFor(region: WorkbenchPanelRegion): WorkbenchCompositionRegionPanels;
+}
+
+declare interface WorkbenchCompositionRegionPanels {
+    open: readonly WorkbenchWidgetPlacement[];
+    addable: readonly WorkbenchCompositionAddablePanel[];
+    closable: readonly string[];
+}
+
 export declare interface WorkbenchCore extends WorkbenchCoreContributionContext {
     host: WorkbenchHost;
     registerModule(module: WorkbenchModuleContribution): Disposable_2;
@@ -1594,6 +1773,7 @@ declare interface WorkbenchCoreContributionContext {
     commandPalette: WorkbenchCommandPaletteController;
     commandPaletteResources: CommandPaletteResourceRegistry;
     commands: CommandRegistry;
+    composition: WorkbenchCompositionController;
     context: ContextKeyService;
     focus: WorkbenchFocusController;
     history: HistoryController;
@@ -1602,6 +1782,7 @@ declare interface WorkbenchCoreContributionContext {
     layout: WorkbenchLayoutModel;
     modes: WorkbenchModeRegistry;
     navigation: NavigationRegistry;
+    navigator: WorkbenchNavigator;
     notifications: NotificationRegistry;
     panels: WorkbenchPanelsController;
     preferences: PreferenceRegistry;
@@ -1679,7 +1860,7 @@ declare interface WorkbenchLayoutStoreState {
     placeholders: Partial<Record<WorkbenchRegion, RegisteredPlaceholderContribution>>;
 }
 
-declare type WorkbenchLocationContribution = Omit<WidgetContribution, "role"> & WorkbenchPanelMenusContribution;
+declare type WorkbenchLocationContribution = WidgetContribution & WorkbenchPanelMenusContribution;
 
 export declare interface WorkbenchLocationEligibility {
     modeIds?: string[];
@@ -1701,15 +1882,31 @@ export declare type WorkbenchModeActivationContext = WorkbenchCoreContributionCo
 
 export declare type WorkbenchModeActivationResult = Disposable_2 | readonly Disposable_2[] | undefined;
 
+export declare interface WorkbenchModeAddablePanel {
+    panelId: string;
+    region: WorkbenchPanelRegion;
+    allowedRegions?: readonly WorkbenchRegion[];
+    pinned?: boolean;
+}
+
+export declare interface WorkbenchModeAddablePanelContext {
+    layout: WorkbenchLayout;
+    resource?: ResourceRef;
+}
+
 declare type WorkbenchModeChangeListener = () => void;
 
 export declare interface WorkbenchModeContribution {
     id: string;
     label?: string;
     panels?: readonly WorkbenchPanelRegion[];
+    resourceKinds?: readonly string[];
+    defaultResource?: ResourceRef | (() => Promise<ResourceRef | undefined> | ResourceRef | undefined);
+    listAddablePanels?(context: WorkbenchModeAddablePanelContext): readonly WorkbenchModeAddablePanel[];
     activate(ctx: WorkbenchModeActivationContext): WorkbenchModeActivationResult;
     seed?(ctx: WorkbenchModeActivationContext): void;
     enter?(ctx: WorkbenchModeActivationContext): WorkbenchModeActivationResult;
+    reconcile?(ctx: WorkbenchModeActivationContext): void;
 }
 
 export declare interface WorkbenchModeRegistry {
@@ -1745,6 +1942,14 @@ export declare interface WorkbenchModuleContribution {
 
 export declare type WorkbenchModuleContributionContext = WorkbenchModuleContext;
 
+declare interface WorkbenchNavigationCommit {
+    modeId: string | undefined;
+    resource: ResourceRef | undefined;
+    replaceActive: boolean;
+}
+
+declare type WorkbenchNavigationDiagnosticCode = "navigation_mode_missing" | "navigation_resource_missing" | "navigation_resource_incompatible" | "navigation_default_missing" | "navigation_target_stale";
+
 declare interface WorkbenchNavigationEntry {
     entryId: string;
     recordedAt: number;
@@ -1759,6 +1964,53 @@ declare interface WorkbenchNavigationEntry {
     closedSubPanel?: WorkbenchClosedSubPanel;
 }
 
+declare type WorkbenchNavigationResult = {
+    ok: true;
+    modeId: string | undefined;
+    resource: ResourceRef | undefined;
+} | {
+    ok: false;
+    code: WorkbenchNavigationDiagnosticCode;
+    message: string;
+};
+
+declare interface WorkbenchNavigationTarget {
+    modeId?: string;
+    resource?: ResourceRef;
+    replaceActive?: boolean;
+}
+
+declare interface WorkbenchNavigator {
+    configure(hooks: WorkbenchNavigatorHostHooks): void;
+    getSelectedResource(): ResourceRef | undefined;
+    open(target: WorkbenchNavigationTarget): Promise<WorkbenchNavigationResult>;
+    commitContext(input: WorkbenchNavigatorCommitInput): WorkbenchNavigationResult;
+    getLastResource(projectId: string | undefined, modeId: string): ResourceRef | undefined;
+    forgetResource(uri: string): void;
+    onDidCommit(listener: (commit: WorkbenchNavigationCommit) => void): {
+        dispose(): void;
+    };
+}
+
+declare interface WorkbenchNavigatorCommitInput {
+    modeId?: string | null;
+    resource?: ResourceRef | null;
+    replaceActive?: boolean;
+    present?: boolean;
+}
+
+declare interface WorkbenchNavigatorHostHooks {
+    getProjectId?(): string | undefined;
+    getSelectedResource?(): ResourceRef | undefined;
+    interpretSelection?(resource: ResourceRef): ResourceRef | undefined;
+    applySelection?(resource: ResourceRef | undefined): void;
+    applyScope?(commit: WorkbenchNavigationCommit): void;
+    applyBreadcrumb?(resource: ResourceRef | undefined): void;
+    presentResource?(resource: ResourceRef, input: {
+        replaceActive: boolean;
+    }): Promise<unknown> | unknown;
+}
+
 export declare interface WorkbenchNotification {
     id?: string;
     level: WorkbenchNotificationLevel;
@@ -1800,7 +2052,6 @@ export declare interface WorkbenchPanelContribution {
     region: WorkbenchRegion;
     fallbackRegion?: WorkbenchRegion;
     rendererId: string;
-    closable: boolean;
     singleton?: boolean;
     reuse?: WorkbenchPanelReusePolicy;
     mountStrategy?: WorkbenchPanelMountStrategy;
@@ -1839,7 +2090,7 @@ export declare interface WorkbenchPanelInstance {
     tab?: WorkbenchPanelTab;
 }
 
-declare type WorkbenchPanelMenuContribution = Omit<WidgetContribution, "region" | "fallbackRegion" | "role"> & {
+declare type WorkbenchPanelMenuContribution = Omit<WidgetContribution, "region" | "fallbackRegion"> & {
     region: WorkbenchPanelMenuRegion;
     fallbackRegion?: WorkbenchPanelMenuRegion;
 };
@@ -1908,9 +2159,9 @@ export declare type WorkbenchPanelOpenStrategy = {
     position?: WorkbenchTabPosition;
 };
 
-declare type WorkbenchPanelRegion = (typeof workbenchPanelRegions)[number];
+export declare type WorkbenchPanelRegion = (typeof workbenchPanelRegions)[number];
 
-declare const workbenchPanelRegions: readonly ["main", "secondary", "side"];
+export declare const workbenchPanelRegions: readonly ["main", "secondary", "side"];
 
 export declare interface WorkbenchPanelRenderInput {
     workbench: WorkbenchCore;
@@ -2070,7 +2321,7 @@ declare type WorkbenchStoreSelector<TState, TValue> = (state: TState) => TValue;
 
 declare type WorkbenchStoreSelectorListener<TValue> = (value: TValue, previousValue: TValue) => void;
 
-declare type WorkbenchSubPanelContribution = Omit<WidgetContribution, "region" | "fallbackRegion" | "role"> & {
+declare type WorkbenchSubPanelContribution = Omit<WidgetContribution, "region" | "fallbackRegion"> & {
     region: WorkbenchPanelRegion;
     fallbackRegion?: WorkbenchPanelRegion;
 } & WorkbenchPanelMenusContribution;
@@ -2081,6 +2332,8 @@ declare interface WorkbenchSubPanelRef {
     instanceKey?: string;
 }
 
+export declare const workbenchSwitchModeCommandId = "workbench.action.switchMode";
+
 export declare type WorkbenchTabPosition = "start" | "end" | {
     beforeWidgetId: string;
 } | {