Request for the new API revision / comments / feedback

[evonox]

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;
}

[jogibear9988]

Sorry for the late answer....
Don't know what you exactly mean with "every panel will have its type specified by a string"
but for me the refactor looks okay. I would love if we not create a fork. Breaking changes are okay, if we increase the majore, and there is a reason why we need to do them, and we have a path forward, means a small documentation what needs to be changed...

We for sure could discuss some of your thoughts if you'd like to.
I also could add you as a maintainer if you get forward with your changes.

I also have not so much time to help here. (too bussy in other projects)

[evonox]

Dear @jogibear9988 ,
I have migrated your code into a completely new architecture. I share my temporary repository of DockSpawnTS / DockerTS here:
https://github.com/evonox/docker for the public code review with a warning that it is the code under heavy development and everything is subject to change. When I will have finish the fork of DockSpawnTS it will be up to you if we will release it as the same library or create a new one. I am thinking also to create simple adapters over the new DockSpawnTS library for the backward compatibility.

[evonox]

What I have done the last week:

• I have created a new API over DOM events and operations supporting fluent interfaces. In the future it might support local caching of for instance the list of CSS classes to avoid unnecesarry DOM mutations
• For small UI widgets like context menus and header buttons I have introduced a very simple component framework with reactive properties with automatic DOM update
• I have introduced wrappers over DOM and Component Events for auto-cleanup purposes
• I have migrated almost the whole former code base. I am now writing unit tests for the core part

[evonox]

My intention now is to:

• write automatic unit tests where possible
• remove JS resizing computations as much as possible and delegate it to CSS engine using Flex / Grid layouts and CSS custom variables
• I have already fixed some UI bugs in the splitter panel for instance
• doing the initial manual testing a fixes to the codebase

I have noticed in the issues that you are busy on other projects therefore I have taken over the initiative to rework this project and maintain it

[evonox]

First I will welcome the public review of the lower level DOM / Event manipulation routines and the reactive component framework. Other features are still under developement and subject to change.

[jogibear9988]

You should fix your package.json, there are many non dev dependencies, I think they are wrong?

[evonox]

I have noticed now. Thank you for support. I will fix it ASAP. Feel free to provide any feedback to the project. Thank you for your support.

[evonox]

You should fix your package.json, there are many non dev dependencies, I think they are wrong?

It si FIXED.