Request for the new API revision / comments / feedback #94
Description
Hi everyone, I need to implement new features to the DockSpawnTS for my projects. However it requires for me to reactor the codebase entirely. I will introduce a new set of APIs having new features. I include the new API design for revision and comments.
Simply said, every panel will have its type specified by a string. For each panel type there will be an interface required to be returned by the panel's factory method provided by the client code using DockSpawnTS. I am including the proposal for the API design in this issue.
New features include:
- allow the panel to configure its context menu
- allow the panel to configure its custom header buttons
- allow the panel to modify its title, icon or its "modified flag" by notifications
- persist its own state, for its the primary key of a document it displays
- allow to influence its minimum width and height programmatically
- and many others
Thank you for any feedback provided.
import { DockManager } from "../DockManager";
/**
* Interface for Options Container containing initial options for a panel type
*/
export interface IInitOptions {
getValue(key: string, defaultValue?: any): any;
}
/**
* Subscription Interface for events regarding a panel itself
*/
export interface ISubscriptionAPI {
unsubscribe(): void;
}
/**
* Every panel will have possibility to save and load its state
* It is important for panels of the same type to save the identity of its data
*/
export interface IPanelState {
getValue(key: string, defaultValue?: any): any;
setValue(key: string, value: any): void;
}
/**
* Configuration interface for panels to have the ability to influence its context menu
*/
export interface IMenuItem {
displayOrder: number;
icon?: string;
title?: string;
actionName?: string;
disabled?: boolean;
separator?: boolean;
}
/**
* Panels will have an ability to inject custom buttons into theirs panel header
*/
export interface IHeaderButton {
displayOrder: number;
icon: string;
title: string;
actionName: string;
visible: boolean;
}
/**
* Interface for method invoked when the user request to open a panel's context menu
*/
export interface IContextMenuAPI {
getMenuItems(): IMenuItem[];
appendMenuItem(item: IMenuItem): void;
removeMenuItem(item: IMenuItem): void;
}
/**
* Interface passed to the panel's factory method with the API to influence its state in runtime
*/
export interface IDockManagerAPI {
getDockManager(): DockManager;
setPanelIcon(html: string): void;
setPanelTitle(title: string): void;
notifyHasChanges(hasChanges: boolean): void;
addHeaderButton(button: IHeaderButton): void;
removeHeaderButton(actionName: string): void;
showHeaderButton(actionName: string, flag: boolean): void;
listenTo(eventName: string, handler: (payload?: any) => void): ISubscriptionAPI;
}
/**
* This is interface implemented by a panel's factory method to query its state
* The only required method is the factory method "initialize()" to create the panel's content
*/
export interface IPanelAPI {
initialize: (api: IDockManagerAPI, options: IInitOptions) => Promise<HTMLElement>;
canClose?: () => boolean;
getMinWidth?: () => number;
getMinHeight?: () => number;
onQueryContextMenu?: (contextMenu: IContextMenuAPI) => void;
loadState?: (state: IPanelState) => void;
saveState?: (state: IPanelState) => void;
onActionInvoked?: (actionName: string) => void;
}