@genesis-community/golden-layout 2.6.0

package/src/ts/utils/event-emitter.ts

@@ -0,0 +1,275 @@
+import { BrowserPopout } from '../controls/browser-popout';
+import { Tab } from '../controls/tab';
+import { ComponentItem } from '../items/component-item';
+
+/**
+ * A generic and very fast EventEmitter implementation. On top of emitting the actual event it emits an
+ * {@link (EventEmitter:namespace).ALL_EVENT} event for every event triggered. This allows to hook into it and proxy events forwards
+ * @public
+ */
+export class EventEmitter {
+    /** @internal */
+    private _allEventSubscriptions: EventEmitter.UnknownCallback[] = [];
+    /** @internal */
+    private _subscriptionsMap = new Map<string, EventEmitter.UnknownCallback[]>();
+
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    tryBubbleEvent(name: string, args: unknown[]): void {
+        // overridden by ContentItem
+    }
+
+    /**
+     * Emit an event and notify listeners
+     *
+     * @param eventName - The name of the event
+     * @param args - Additional arguments that will be passed to the listener
+     */
+    emit<K extends keyof EventEmitter.EventParamsMap>(eventName: K, ...args: EventEmitter.EventParamsMap[K]): void {
+        let subcriptions = this._subscriptionsMap.get(eventName);
+
+        if (subcriptions !== undefined) {
+            subcriptions = subcriptions.slice();
+            for (let i = 0; i < subcriptions.length; i++) {
+                const subscription = subcriptions[i];
+                subscription(...args);
+            }
+        }
+
+        this.emitAllEvent(eventName, args);
+        this.tryBubbleEvent(eventName, args);
+    }
+
+    /** @internal */
+    emitUnknown(eventName: string, ...args: EventEmitter.UnknownParams): void {
+        let subs = this._subscriptionsMap.get(eventName);
+
+        if (subs !== undefined) {
+            subs = subs.slice();
+            for (let i = 0; i < subs.length; i++) {
+                subs[i](...args);
+            }
+        }
+
+        this.emitAllEvent(eventName, args);
+        this.tryBubbleEvent(eventName, args);
+    }
+
+    /* @internal **/
+    emitBaseBubblingEvent<K extends keyof EventEmitter.EventParamsMap>(eventName: K): void {
+        const event = new EventEmitter.BubblingEvent(eventName, this);
+        this.emitUnknown(eventName, event);
+    }
+
+    /** @internal */
+    emitUnknownBubblingEvent(eventName: string): void {
+        const event = new EventEmitter.BubblingEvent(eventName, this);
+        this.emitUnknown(eventName, event);
+    }
+
+    /**
+     * Removes a listener for an event.
+     * @param eventName - The name of the event
+     * @param callback - The previously registered callback method (optional)
+     */
+    removeEventListener<K extends keyof EventEmitter.EventParamsMap>(eventName: K, callback: EventEmitter.Callback<K>): void {
+        const unknownCallback = callback as EventEmitter.UnknownCallback;
+        this.removeUnknownEventListener(eventName, unknownCallback);
+    }
+
+    off<K extends keyof EventEmitter.EventParamsMap>(eventName: K, callback: EventEmitter.Callback<K>): void {
+        this.removeEventListener(eventName, callback);
+    }
+
+    /**
+     * Alias for off
+     */
+    unbind = this.removeEventListener;
+
+    /**
+     * Alias for emit
+     */
+    trigger = this.emit;
+
+    /**
+     * Listen for events
+     *
+     * @param eventName - The name of the event to listen to
+     * @param callback - The callback to execute when the event occurs
+     */
+    addEventListener<K extends keyof EventEmitter.EventParamsMap>(eventName: K, callback: EventEmitter.Callback<K>): void {
+        const unknownCallback = callback as EventEmitter.UnknownCallback;
+        this.addUnknownEventListener(eventName, unknownCallback);
+    }
+
+    on<K extends keyof EventEmitter.EventParamsMap>(eventName: K, callback: EventEmitter.Callback<K>): void {
+        this.addEventListener(eventName, callback);
+    }
+
+    /** @internal */
+    private addUnknownEventListener(eventName: string, callback: EventEmitter.UnknownCallback): void {
+        if (eventName === EventEmitter.ALL_EVENT) {
+            this._allEventSubscriptions.push(callback);
+        } else {
+            let subscriptions = this._subscriptionsMap.get(eventName);
+            if (subscriptions !== undefined) {
+                subscriptions.push(callback);
+            } else {
+                subscriptions = [callback];
+                this._subscriptionsMap.set(eventName, subscriptions);
+            }
+        }
+    }
+
+    /** @internal */
+    private removeUnknownEventListener(eventName: string, callback: EventEmitter.UnknownCallback): void {
+        if (eventName === EventEmitter.ALL_EVENT) {
+            this.removeSubscription(eventName, this._allEventSubscriptions, callback);
+        } else {
+            const subscriptions = this._subscriptionsMap.get(eventName);
+            if (subscriptions === undefined) {
+                throw new Error('No subscribtions to unsubscribe for event ' + eventName);
+            } else {
+                this.removeSubscription(eventName, subscriptions, callback);
+            }
+        }
+    }
+
+    /** @internal */
+    private removeSubscription(eventName: string, subscriptions: EventEmitter.UnknownCallback[], callback: EventEmitter.UnknownCallback) {
+        const idx = subscriptions.indexOf(callback);
+        if (idx < 0) {
+            throw new Error('Nothing to unbind for ' + eventName);
+        } else {
+            subscriptions.splice(idx, 1);
+        }
+    }
+
+    /** @internal */
+    private emitAllEvent(eventName: string, args: unknown[]) {
+        const allEventSubscriptionsCount = this._allEventSubscriptions.length;
+        if (allEventSubscriptionsCount > 0) {
+            const unknownArgs = args.slice() as EventEmitter.UnknownParams;
+            unknownArgs.unshift(eventName);
+
+            const allEventSubcriptions = this._allEventSubscriptions.slice();
+
+            for (let i = 0; i < allEventSubscriptionsCount; i++) {
+                allEventSubcriptions[i](...unknownArgs);
+            }
+        }
+    }
+}
+
+/** @public */
+export namespace EventEmitter {
+    /**
+     * The name of the event that's triggered for every event
+     */
+    export const ALL_EVENT = '__all';
+
+    export const headerClickEventName = 'stackHeaderClick';
+    export const headerTouchStartEventName = 'stackHeaderTouchStart';
+
+    /** @internal */
+    export type UnknownCallback = (this: void, ...args: UnknownParams) => void;
+    export type Callback<K extends keyof EventEmitter.EventParamsMap> = (this: void, ...args: EventParamsMap[K]) => void;
+
+    export interface EventParamsMap {
+        "__all": UnknownParams;
+        "activeContentItemChanged": ComponentItemParam;
+        "close": NoParams;
+        "closed": NoParams;
+        "destroy": NoParams;
+        "drag": DragParams;
+        "dragStart": DragStartParams;
+        "dragStop": DragStopParams;
+        "hide": NoParams;
+        "initialised": NoParams;
+        "itemDropped": ComponentItemParam;
+        "maximised": NoParams;
+        "minimised": NoParams;
+        "open": NoParams;
+        "popIn": NoParams;
+        "resize": NoParams;
+        "show": NoParams;
+        /** @deprecated - use show instead */
+        "shown": NoParams;
+        "stateChanged": NoParams;
+        "tab": TabParam;
+        "tabCreated": TabParam;
+        "titleChanged": StringParam;
+        "windowClosed": PopoutParam;
+        "windowOpened": PopoutParam;
+        "beforeComponentRelease": BeforeComponentReleaseParams;
+        "beforeItemDestroyed": BubblingEventParam;
+        "itemCreated": BubblingEventParam;
+        "itemDestroyed": BubblingEventParam;
+        "focus": BubblingEventParam;
+        "blur": BubblingEventParam;
+        "stackHeaderClick": ClickBubblingEventParam;
+        "stackHeaderTouchStart": TouchStartBubblingEventParam;
+        "userBroadcast": UnknownParams;
+    }
+
+    export type UnknownParams = unknown[];
+    export type NoParams = [];
+    export type UnknownParam = [unknown];
+    export type PopoutParam = [BrowserPopout];
+    export type ComponentItemParam = [ComponentItem];
+    export type TabParam = [Tab];
+    export type BubblingEventParam = [EventEmitter.BubblingEvent]
+    export type StringParam = [string];
+    export type DragStartParams = [originalX: number, originalY: number];
+    export type DragStopParams = [event: PointerEvent | undefined];
+    export type DragParams = [offsetX: number, offsetY: number, event: PointerEvent];
+    export type BeforeComponentReleaseParams = [component: unknown];
+    export type ClickBubblingEventParam = [ClickBubblingEvent];
+    export type TouchStartBubblingEventParam = [TouchStartBubblingEvent];
+
+    export class BubblingEvent {
+        /** @internal */
+        private _isPropagationStopped = false;
+
+        get name(): string { return this._name; }
+        get target(): EventEmitter { return this._target; }
+        /** @deprecated Use {@link (EventEmitter:namespace).(BubblingEvent:class).target} instead */
+        get origin(): EventEmitter { return this._target; }
+        get isPropagationStopped(): boolean { return this._isPropagationStopped; }
+
+        /** @internal */
+        constructor(
+            /** @internal */
+            private readonly _name: string,
+            /** @internal */
+            private readonly _target: EventEmitter) {
+        }
+
+        stopPropagation(): void {
+            this._isPropagationStopped = true;
+        }
+    }
+
+    export class ClickBubblingEvent extends BubblingEvent {
+        get mouseEvent(): MouseEvent { return this._mouseEvent; }
+
+        /** @internal */
+        constructor(name: string, target: EventEmitter,
+            /** @internal */
+            private readonly _mouseEvent: MouseEvent
+        ) {
+            super(name, target);
+        }
+    }
+
+    export class TouchStartBubblingEvent extends BubblingEvent {
+        get touchEvent(): TouchEvent { return this._touchEvent; }
+
+        /** @internal */
+        constructor(name: string, target: EventEmitter,
+            /** @internal */
+            private readonly _touchEvent: TouchEvent
+        ) {
+            super(name, target);
+        }
+    }
+}

package/src/ts/utils/event-hub.ts

@@ -0,0 +1,163 @@
+import { UnexpectedNullError } from '../errors/internal-error';
+import { LayoutManager } from '../layout-manager';
+import { EventEmitter } from './event-emitter';
+
+// Add our ChildEvent to WindowEventMap for type safety
+/** @public */
+declare global {
+    interface WindowEventMap {
+        [EventHub.ChildEventName]: CustomEvent<EventHub.ChildEventDetail>;
+    }
+}
+
+/**
+ * An EventEmitter singleton that propagates events
+ * across multiple windows. This is a little bit trickier since
+ * windows are allowed to open childWindows in their own right.
+ *
+ * This means that we deal with a tree of windows. Therefore, we do the event propagation in two phases:
+ *
+ * - Propagate events from this layout to the parent layout
+ *   - Repeat until the event arrived at the root layout
+ * - Propagate events to this layout and to all children
+ *   - Repeat until all layouts got the event
+ *
+ * **WARNING**: Only userBroadcast events are propagated between windows.
+ * This means the you have to take care of propagating state changes between windows yourself.
+ *
+ * @public
+ */
+export class EventHub extends EventEmitter {
+
+    /** @internal */
+    private _childEventListener = (childEvent: CustomEvent<EventHub.ChildEventDetail>) => this.onEventFromChild(childEvent);
+
+    /**
+     * Creates a new EventHub instance
+     * @param _layoutManager - the layout manager to synchronize between the windows
+     * @internal
+     */
+    constructor(
+        /** @internal */
+        private _layoutManager: LayoutManager
+    ) {
+        super();
+        globalThis.addEventListener(EventHub.ChildEventName, this._childEventListener, { passive: true });
+    }
+
+    /**
+     * Emit an event and notify listeners
+     *
+     * @param eventName - The name of the event
+     * @param args - Additional arguments that will be passed to the listener
+     * @public
+     */
+    override emit<K extends keyof EventEmitter.EventParamsMap>(eventName: K, ...args: EventEmitter.EventParamsMap[K]): void {
+        if (eventName === 'userBroadcast') {
+            // Explicitly redirect the user broadcast to our overridden method.
+            this.emitUserBroadcast(...args);
+        } else {
+            super.emit(eventName, ...args);
+        }
+    }
+
+    /**
+     * Broadcasts a message to all other currently opened windows.
+     * @public
+     */
+    emitUserBroadcast(...args: EventEmitter.UnknownParams): void {
+        // Step 1: Bubble up the event
+        this.handleUserBroadcastEvent('userBroadcast', args);
+    }
+
+    /**
+     * Destroys the EventHub
+     * @internal
+     */
+    destroy(): void {
+        globalThis.removeEventListener(EventHub.ChildEventName, this._childEventListener);
+    }
+
+    /**
+     * Internal processor to process local events.
+     * @internal
+     */
+    private handleUserBroadcastEvent(eventName: string, args: unknown[]) {
+        if (this._layoutManager.isSubWindow) {
+            // We are a sub window and received an event from one of our children.
+            // So propagate it to the Root.
+            this.propagateToParent(eventName, args);
+        } else {
+            // We are the root window, propagate it to the subtree below us.
+            this.propagateToThisAndSubtree(eventName, args);
+        }
+    }
+
+    /**
+     * Callback for child events raised on the window
+     * @internal
+     */
+    private onEventFromChild(event: CustomEvent<EventHub.ChildEventDetail>) {
+        const detail = event.detail;
+        this.handleUserBroadcastEvent(detail.eventName, detail.args);
+    }
+
+    /**
+     * Propagates the event to the parent by emitting
+     * it on the parent's DOM window
+     * @internal
+     */
+    private propagateToParent(eventName: string, args: unknown[]) {
+        const detail: EventHub.ChildEventDetail = {
+            layoutManager: this._layoutManager,
+            eventName,
+            args: args,
+        }
+
+        const eventInit: EventHub.ChildEventInit = {
+            bubbles: true,
+            cancelable: true,
+            detail,
+        };
+
+        const event = new CustomEvent<EventHub.ChildEventDetail>(EventHub.ChildEventName, eventInit);
+        const opener = globalThis.opener;
+        if (opener === null) {
+            throw new UnexpectedNullError('EHPTP15778')
+        }
+
+        opener.dispatchEvent(event);
+    }
+
+    /**
+     * Propagate events to the whole subtree under this event hub.
+     * @internal
+     */
+    private propagateToThisAndSubtree(eventName: string, args: unknown[]) {
+        this.emitUnknown(eventName, ...args);
+        for (let i = 0; i < this._layoutManager.openPopouts.length; i++) {
+            const childGl = this._layoutManager.openPopouts[i].getGlInstance();
+
+            if (childGl) {
+                childGl.eventHub.propagateToThisAndSubtree(eventName, args);
+            }
+        }
+    }
+}
+
+/** @public */
+export namespace EventHub {
+
+    /** @internal */
+    export const ChildEventName = 'gl_child_event';
+
+    /** @internal */
+    export type ChildEventDetail = {
+        layoutManager: LayoutManager;
+        eventName: string;
+        args: unknown[];
+    };
+
+    /** @internal */
+    export type ChildEventInit = CustomEventInit<ChildEventDetail>;
+}

package/src/ts/utils/i18n-strings.ts

@@ -0,0 +1,96 @@
+import { AssertError } from '../errors/internal-error';
+
+/** @public */
+export const enum I18nStringId {
+    PopoutCannotBeCreatedWithGroundItemConfig,
+    PleaseRegisterAConstructorFunction,
+    ComponentTypeNotRegisteredAndBindComponentEventHandlerNotAssigned,
+    ComponentIsAlreadyRegistered,
+    ComponentIsNotVirtuable,
+    VirtualComponentDoesNotHaveRootHtmlElement,
+    ItemConfigIsNotTypeComponent,
+    InvalidNumberPartInSizeString,
+    UnknownUnitInSizeString,
+    UnsupportedUnitInSizeString,
+}
+
+/** @public */
+export namespace I18nStrings {
+    /** @internal */
+    let initialised = false;
+
+    /** @internal */
+    interface Info {
+        readonly id: I18nStringId;
+        readonly default: string;
+    }
+
+    /** @internal */
+    type InfosObject = { [id in keyof typeof I18nStringId]: Info };
+
+    /** @internal */
+    const infosObject: InfosObject = {
+        PopoutCannotBeCreatedWithGroundItemConfig: {
+            id: I18nStringId.PopoutCannotBeCreatedWithGroundItemConfig,
+            default: 'Popout cannot be created with ground ItemConfig'
+        },
+        PleaseRegisterAConstructorFunction: {
+            id: I18nStringId.PleaseRegisterAConstructorFunction,
+            default: 'Please register a constructor function'
+        },
+        ComponentTypeNotRegisteredAndBindComponentEventHandlerNotAssigned: {
+            id: I18nStringId.ComponentTypeNotRegisteredAndBindComponentEventHandlerNotAssigned,
+            default: 'Component type not registered and BindComponentEvent handler not assigned',
+        },
+        ComponentIsAlreadyRegistered: {
+            id: I18nStringId.ComponentIsAlreadyRegistered,
+            default: 'Component is already registered',
+        },
+        ComponentIsNotVirtuable: {
+            id: I18nStringId.ComponentIsNotVirtuable,
+            default: 'Component is not virtuable. Requires rootHtmlElement field/getter',
+        },
+        VirtualComponentDoesNotHaveRootHtmlElement: {
+            id: I18nStringId.VirtualComponentDoesNotHaveRootHtmlElement,
+            default: 'Virtual component does not have getter "rootHtmlElement"',
+        },
+        ItemConfigIsNotTypeComponent: {
+            id: I18nStringId.ItemConfigIsNotTypeComponent,
+            default: 'ItemConfig is not of type component',
+        },
+
+        InvalidNumberPartInSizeString: {
+            id: I18nStringId.InvalidNumberPartInSizeString,
+            default: 'Invalid number part in size string',
+        },
+        UnknownUnitInSizeString: {
+            id: I18nStringId.UnknownUnitInSizeString,
+            default: 'Unknown unit in size string',
+        },
+        UnsupportedUnitInSizeString: {
+            id: I18nStringId.UnsupportedUnitInSizeString,
+            default: 'Unsupported unit in size string',
+        },
+    }
+
+    export const idCount = Object.keys(infosObject).length;
+    /** @internal */
+    const infos = Object.values(infosObject);
+
+    export function checkInitialise(): void {
+        if (!initialised) {
+            for (let i = 0; i < idCount; i++) {
+                const info = infos[i];
+                if (info.id !== i) {
+                    throw new AssertError('INSI00110', `${i}: ${info.id}`);
+                } else {
+                    i18nStrings[i] = info.default;
+                }
+            }
+        }
+        initialised = true;
+    }
+}
+
+/** @public */
+export const i18nStrings = new Array<string>(I18nStrings.idCount);

package/src/ts/utils/jquery-legacy.ts

@@ -0,0 +1,12 @@
+import { LeftAndTop } from './types';
+import { pixelsToNumber } from './utils';
+
+/** @internal */
+export function getJQueryLeftAndTop(element: HTMLElement): LeftAndTop {
+    const style = getComputedStyle(element, null);
+    const leftAndTop: LeftAndTop = {
+        left: pixelsToNumber(style.left),
+        top: pixelsToNumber(style.top),
+    }
+    return leftAndTop;
+}

package/src/ts/utils/style-constants.ts

@@ -0,0 +1,6 @@
+/** @public */
+export namespace StyleConstants {
+    export const defaultComponentBaseZIndex = 'auto';
+    export const defaultComponentDragZIndex = '32';
+    export const defaultComponentStackMaximisedZIndex = '41';
+}

package/src/ts/utils/types.ts

@@ -0,0 +1,145 @@
+import { UnreachableCaseError } from '../errors/internal-error';
+import { StyleConstants } from './style-constants';
+
+/** @internal */
+export type WidthOrHeightPropertyName = 'width' | 'height';
+
+/** @internal */
+export namespace WidthOrHeightPropertyName {
+    export const width = 'width';
+    export const height = 'height';
+}
+
+/** @internal */
+export interface WidthAndHeight {
+    width: number;
+    height: number;
+}
+
+/** @internal */
+export interface LeftAndTop {
+    left: number;
+    top: number;
+}
+
+/** @public */
+export type Side = 'top' | 'left' | 'right' | 'bottom';
+/** @public */
+export namespace Side {
+    export const top = 'top';
+    export const left = 'left';
+    export const right = 'right';
+    export const bottom = 'bottom';
+}
+
+/** @public */
+export type LogicalZIndex = 'base' | 'drag' | 'stackMaximised';
+/** @public */
+export namespace LogicalZIndex {
+    export const base = 'base';
+    export const drag = 'drag';
+    export const stackMaximised = 'stackMaximised';
+}
+
+/** @public */
+export const LogicalZIndexToDefaultMap = {
+    base: StyleConstants.defaultComponentBaseZIndex,
+    drag: StyleConstants.defaultComponentDragZIndex,
+    stackMaximised: StyleConstants.defaultComponentStackMaximisedZIndex,
+}
+
+/** @internal */
+export interface Rect {
+    left: number,
+    top: number,
+    width: number,
+    height: number,
+}
+
+/** @internal */
+export interface AreaLinkedRect {
+    x1: number, // left
+    x2: number, // nextLeft
+    y1: number, // top
+    y2: number, // nextTop
+}
+
+/** @public */
+// eslint-disable-next-line @typescript-eslint/ban-types
+export type JsonValue = string | number | boolean | null | Json | object | JsonValueArray;
+/** @public */
+export interface Json {
+    [name: string]: JsonValue;
+}
+/** @public */
+export type JsonValueArray = Array<JsonValue>
+/** @public */
+export namespace JsonValue {
+    export function isJson(value: JsonValue): value is Json {
+        return isJsonObject(value);
+    }
+
+    // eslint-disable-next-line @typescript-eslint/ban-types
+    export function isJsonObject(value: JsonValue): value is Json | object {
+        return !Array.isArray(value) && value !== null && typeof value === 'object';
+    }
+}
+
+/** @public */
+export type ItemType = 'ground' | 'row' | 'column' | 'stack' | 'component';
+
+/** @public */
+export namespace ItemType {
+    export const ground = 'ground';
+    export const row = 'row';
+    export const column = 'column';
+    export const stack = 'stack';
+    export const component = 'component';
+}
+
+/** @public */
+export type ResponsiveMode = 'none' | 'always' | 'onload';
+/** @public */
+export namespace ResponsiveMode {
+    export const none = 'none';
+    export const always = 'always';
+    export const onload = 'onload';
+}
+
+/**
+ * Length units which can specify the size of a Component Item
+ * @public
+ */
+export type SizeUnit = 'px' | '%' | 'fr' | 'em';
+
+/** @public */
+export enum SizeUnitEnum {
+    Pixel = 'px',
+    Percent = '%',
+    Fractional = 'fr',
+    Em = 'em',
+}
+
+/** @public */
+export namespace SizeUnitEnum {
+    export function tryParse(value: string) {
+        switch (value) {
+            case SizeUnitEnum.Pixel: return SizeUnitEnum.Pixel;
+            case SizeUnitEnum.Percent: return SizeUnitEnum.Percent;
+            case SizeUnitEnum.Fractional: return SizeUnitEnum.Fractional;
+            case SizeUnitEnum.Em: return SizeUnitEnum.Em;
+            default: return undefined;
+        }
+    }
+
+    export function format(value: SizeUnitEnum) {
+        switch (value) {
+            case SizeUnitEnum.Pixel: return SizeUnitEnum.Pixel;
+            case SizeUnitEnum.Percent: return SizeUnitEnum.Percent;
+            case SizeUnitEnum.Fractional: return SizeUnitEnum.Fractional;
+            case SizeUnitEnum.Em: return SizeUnitEnum.Em;
+            default:
+                throw new UnreachableCaseError('SUEF44998', value);
+        }
+    }
+}