custom-electron-titlebar 4.2.8 → 4.4.1

package/index.d.mts

@@ -0,0 +1,684 @@
+import { Menu, MenuItem, NativeImage } from 'electron';
+
+declare class RGBA {
+    /**
+     * Red: integer in [0-255]
+     */
+    readonly r: number;
+    /**
+     * Green: integer in [0-255]
+     */
+    readonly g: number;
+    /**
+     * Blue: integer in [0-255]
+     */
+    readonly b: number;
+    /**
+     * Alpha: float in [0-1]
+     */
+    readonly a: number;
+    constructor(r: number, g: number, b: number, a?: number);
+    static equals(a: RGBA, b: RGBA): boolean;
+}
+declare class HSLA {
+    /**
+     * Hue: integer in [0, 360]
+     */
+    readonly h: number;
+    /**
+     * Saturation: float in [0, 1]
+     */
+    readonly s: number;
+    /**
+     * Luminosity: float in [0, 1]
+     */
+    readonly l: number;
+    /**
+     * Alpha: float in [0, 1]
+     */
+    readonly a: number;
+    constructor(h: number, s: number, l: number, a: number);
+    static equals(a: HSLA, b: HSLA): boolean;
+    /**
+     * Converts an RGB color value to HSL. Conversion formula
+     * adapted from http://en.wikipedia.org/wiki/HSL_color_space.
+     * Assumes r, g, and b are contained in the set [0, 255] and
+     * returns h in the set [0, 360], s, and l in the set [0, 1].
+     */
+    static fromRGBA(rgba: RGBA): HSLA;
+    private static _hue2rgb;
+    /**
+     * Converts an HSL color value to RGB. Conversion formula
+     * adapted from http://en.wikipedia.org/wiki/HSL_color_space.
+     * Assumes h in the set [0, 360] s, and l are contained in the set [0, 1] and
+     * returns r, g, and b in the set [0, 255].
+     */
+    static toRGBA(hsla: HSLA): RGBA;
+}
+declare class HSVA {
+    /**
+     * Hue: integer in [0, 360]
+     */
+    readonly h: number;
+    /**
+     * Saturation: float in [0, 1]
+     */
+    readonly s: number;
+    /**
+     * Value: float in [0, 1]
+     */
+    readonly v: number;
+    /**
+     * Alpha: float in [0, 1]
+     */
+    readonly a: number;
+    constructor(h: number, s: number, v: number, a: number);
+    static equals(a: HSVA, b: HSVA): boolean;
+    static fromRGBA(rgba: RGBA): HSVA;
+    static toRGBA(hsva: HSVA): RGBA;
+}
+declare class Color {
+    static fromHex(hex: string): Color;
+    readonly rgba: RGBA;
+    private _hsla?;
+    get hsla(): HSLA;
+    private _hsva?;
+    get hsva(): HSVA;
+    constructor(arg: RGBA | HSLA | HSVA);
+    equals(other: Color): boolean;
+    /**
+     * http://www.w3.org/TR/WCAG20/#relativeluminancedef
+     * Returns the number in the set [0, 1]. O => Darkest Black. 1 => Lightest white.
+     */
+    getRelativeLuminance(): number;
+    private static _relativeLuminanceForComponent;
+    /**
+     * http://www.w3.org/TR/WCAG20/#contrast-ratiodef
+     * Returns the contrast ration number in the set [1, 21].
+     */
+    getContrastRatio(another: Color): number;
+    /**
+     *	http://24ways.org/2010/calculating-color-contrast
+     *  Return 'true' if darker color otherwise 'false'
+     */
+    isDarker(): boolean;
+    /**
+     *	http://24ways.org/2010/calculating-color-contrast
+     *  Return 'true' if lighter color otherwise 'false'
+     */
+    isLighter(): boolean;
+    isLighterThan(another: Color): boolean;
+    isDarkerThan(another: Color): boolean;
+    lighten(factor: number): Color;
+    darken(factor: number): Color;
+    transparent(factor: number): Color;
+    isTransparent(): boolean;
+    isOpaque(): boolean;
+    opposite(): Color;
+    blend(c: Color): Color;
+    flatten(...backgrounds: Color[]): Color;
+    private static _flatten;
+    toString(): string;
+    static getLighterColor(of: Color, relative: Color, factor?: number): Color;
+    static getDarkerColor(of: Color, relative: Color, factor?: number): Color;
+    static readonly WHITE: Color;
+    static readonly BLACK: Color;
+    static readonly RED: Color;
+    static readonly BLUE: Color;
+    static readonly GREEN: Color;
+    static readonly CYAN: Color;
+    static readonly LIGHTGREY: Color;
+    static readonly TRANSPARENT: Color;
+}
+declare namespace Color {
+    namespace Format {
+        namespace CSS {
+            function formatRGB(color: Color): string;
+            function formatRGBA(color: Color): string;
+            function formatHSL(color: Color): string;
+            function formatHSLA(color: Color): string;
+            /**
+             * Formats the color as #RRGGBB
+             */
+            function formatHex(color: Color): string;
+            /**
+             * Formats the color as #RRGGBBAA
+             * If 'compact' is set, colors without transparancy will be printed as #RRGGBB
+             */
+            function formatHexA(color: Color, compact?: boolean): string;
+            /**
+             * The default format will use HEX if opaque and RGBA otherwise.
+             */
+            function format(color: Color): string | null;
+            /**
+             * Converts an Hex color value to a Color.
+             * returns r, g, and b are contained in the set [0, 255]
+             * @param hex string (#RGB, #RGBA, #RRGGBB or #RRGGBBAA).
+             */
+            function parseHex(hex: string): Color | null;
+        }
+    }
+}
+
+interface IDisposable {
+    dispose(): void;
+}
+declare abstract class Disposable implements IDisposable {
+    static None: Readonly<IDisposable>;
+    protected _toDispose: IDisposable[];
+    protected get toDispose(): IDisposable[];
+    private _lifecycle_disposable_isDisposed;
+    dispose(): void;
+    protected _register<T extends IDisposable>(t: T): T;
+}
+
+/**
+ * To an event a function with one or zero parameters
+ * can be subscribed. The event is the subscriber function itself.
+ */
+interface Event<T> {
+    (listener: (e: T) => any, thisArgs?: any, disposables?: IDisposable[]): IDisposable;
+}
+declare namespace Event {
+    const None: Event<any>;
+    /**
+     * Given an event, returns another event which only fires once.
+     */
+    function once<T>(event: Event<T>): Event<T>;
+    /**
+     * Given an event and a `map` function, returns another event which maps each element
+     * throught the mapping function.
+     */
+    function map<I, O>(event: Event<I>, map: (i: I) => O): Event<O>;
+    /**
+     * Given an event and an `each` function, returns another identical event and calls
+     * the `each` function per each element.
+     */
+    function forEach<I>(event: Event<I>, each: (i: I) => void): Event<I>;
+    /**
+     * Given an event and a `filter` function, returns another event which emits those
+     * elements for which the `filter` function returns `true`.
+     */
+    function filter<T>(event: Event<T>, filter: (e: T) => boolean): Event<T>;
+    function filter<T, R>(event: Event<T | R>, filter: (e: T | R) => e is R): Event<R>;
+    /**
+     * Given an event, returns the same event but typed as `Event<void>`.
+     */
+    function signal<T>(event: Event<T>): Event<void>;
+    /**
+     * Given a collection of events, returns a single event which emits
+     * whenever any of the provided events emit.
+     */
+    function any<T>(...events: Event<T>[]): Event<T>;
+    /**
+     * Given an event and a `merge` function, returns another event which maps each element
+     * and the cummulative result throught the `merge` function. Similar to `map`, but with memory.
+     */
+    function reduce<I, O>(event: Event<I>, merge: (last: O | undefined, event: I) => O, initial?: O): Event<O>;
+    /**
+     * Debounces the provided event, given a `merge` function.
+     *
+     * @param event The input event.
+     * @param merge The reducing function.
+     * @param delay The debouncing delay in millis.
+     * @param leading Whether the event should fire in the leading phase of the timeout.
+     * @param leakWarningThreshold The leak warning threshold override.
+     */
+    function debounce<T>(event: Event<T>, merge: (last: T, event: T) => T, delay?: number, leading?: boolean, leakWarningThreshold?: number): Event<T>;
+    function debounce<I, O>(event: Event<I>, merge: (last: O | undefined, event: I) => O, delay?: number, leading?: boolean, leakWarningThreshold?: number): Event<O>;
+    /**
+     * Given an event, it returns another event which fires only once and as soon as
+     * the input event emits. The event data is the number of millis it took for the
+     * event to fire.
+     */
+    function stopwatch<T>(event: Event<T>): Event<number>;
+    /**
+     * Given an event, it returns another event which fires only when the event
+     * element changes.
+     */
+    function latch<T>(event: Event<T>): Event<T>;
+    /**
+     * Buffers the provided event until a first listener comes
+     * along, at which point fire all the events at once and
+     * pipe the event from then on.
+     *
+     * ```typescript
+     * const emitter = new Emitter<number>();
+     * const event = emitter.event;
+     * const bufferedEvent = buffer(event);
+     *
+     * emitter.fire(1);
+     * emitter.fire(2);
+     * emitter.fire(3);
+     * // nothing...
+     *
+     * const listener = bufferedEvent(num => console.log(num));
+     * // 1, 2, 3
+     *
+     * emitter.fire(4);
+     * // 4
+     * ```
+     */
+    function buffer<T>(event: Event<T>, nextTick?: boolean, _buffer?: T[]): Event<T>;
+    /**
+     * Similar to `buffer` but it buffers indefinitely and repeats
+     * the buffered events to every new listener.
+     */
+    function echo<T>(event: Event<T>, nextTick?: boolean, buffer?: T[]): Event<T>;
+    interface IChainableEvent<T> {
+        event: Event<T>;
+        map<O>(fn: (i: T) => O): IChainableEvent<O>;
+        forEach(fn: (i: T) => void): IChainableEvent<T>;
+        filter(fn: (e: T) => boolean): IChainableEvent<T>;
+        reduce<R>(merge: (last: R | undefined, event: T) => R, initial?: R): IChainableEvent<R>;
+        latch(): IChainableEvent<T>;
+        on(listener: (e: T) => any, thisArgs?: any, disposables?: IDisposable[]): IDisposable;
+        once(listener: (e: T) => any, thisArgs?: any, disposables?: IDisposable[]): IDisposable;
+    }
+    function chain<T>(event: Event<T>): IChainableEvent<T>;
+    interface NodeEventEmitter {
+        on(event: string | symbol, listener: Function): this;
+        removeListener(event: string | symbol, listener: Function): this;
+    }
+    function fromNodeEventEmitter<T>(emitter: NodeEventEmitter, eventName: string, map?: (...args: any[]) => T): Event<T>;
+    function fromPromise<T = any>(promise: Promise<T>): Event<undefined>;
+    function toPromise<T>(event: Event<T>): Promise<T>;
+}
+
+interface MenuBarOptions {
+    /**
+     * Enable the mnemonics on menubar and menu items
+     * **The default is true**
+     */
+    enableMnemonics?: boolean;
+    /**
+     * The path of the icons of menubar.
+     */
+    icons?: string;
+    /**
+     * The background color when the mouse is over the item.
+     * **The default is undefined**
+     */
+    itemBackgroundColor?: Color;
+    /**
+     * The background color of the menu.
+     * **The default is automatic**
+     */
+    menuBarBackgroundColor?: Color;
+    /**
+     * The position of menubar on titlebar.
+     * **The default is left**
+     */
+    menuPosition?: 'left' | 'bottom';
+    /**
+     * The color of the menu separator.
+     * **The default is automatic**
+     */
+    menuSeparatorColor?: Color;
+    /**
+     * The menu container transparency
+     * **The default is 0 (not apply transparency)*
+     */
+    menuTransparency?: number;
+    /**
+     * Define if is only rendering the menubar without the titlebar.
+     * **The default is false**
+     */
+    onlyShowMenuBar?: boolean;
+    /**
+     * Define if MenuBar exists on TitleBar or not.
+     * **The default is false**
+     */
+    removeMenuBar?: boolean;
+    /**
+     * The color of the svg icons in the menu
+     * **The default is automatic**
+     */
+    svgColor?: Color;
+}
+
+interface IMenuStyle {
+    foregroundColor?: Color;
+    backgroundColor?: Color;
+    selectionForegroundColor?: Color;
+    selectionBackgroundColor?: Color;
+    separatorColor?: Color;
+    svgColor?: Color;
+}
+
+declare enum Direction {
+    Right = 0,
+    Left = 1
+}
+
+interface IMenuIcons {
+    readonly submenuIndicator: string;
+    readonly checkbox: string;
+    readonly radioChecked: string;
+    readonly radioUnchecked: string;
+}
+interface IMenuBarOptions {
+    enableMnemonics?: boolean;
+    disableAltFocus?: boolean;
+    visibility?: string;
+    alwaysOnMnemonics?: boolean;
+    compactMode?: Direction;
+}
+declare class MenuBar extends Disposable {
+    private container;
+    private menuIcons;
+    private currentOptions;
+    private options;
+    private closeMenu;
+    static readonly OVERFLOW_INDEX: number;
+    private menus;
+    private overflowMenu;
+    private focusedMenu;
+    private focusToReturn;
+    private menuUpdater;
+    private _mnemonicsInUse;
+    private openedViaKeyboard;
+    private awaitingAltRelease;
+    private ignoreNextMouseUp;
+    private mnemonics;
+    private updatePending;
+    private _focusState;
+    private readonly _onVisibilityChange;
+    private readonly _onFocusStateChange;
+    private numMenusShown;
+    private overflowLayoutScheduled;
+    private overflowLayoutPasses;
+    private menuStyle;
+    constructor(container: HTMLElement, menuIcons: IMenuIcons, currentOptions: MenuBarOptions, options: IMenuBarOptions, closeMenu?: () => void);
+    private registerListeners;
+    push(menu: Menu): void;
+    createOverflowMenu(): void;
+    setStyles(style: IMenuStyle): void;
+    updateMenu(menu: MenuItem): void;
+    dispose(): void;
+    blur(): void;
+    getWidth(): number;
+    getHeight(): number;
+    toggleFocus(): void;
+    private updateOverflowAction;
+    private updateLabels;
+    update(options?: IMenuBarOptions): void;
+    private registerMnemonic;
+    private hideMenubar;
+    private showMenubar;
+    private get focusState();
+    private set focusState(value);
+    get isVisible(): boolean;
+    private get isFocused();
+    private get isOpen();
+    private get hasOverflow();
+    private get isCompact();
+    private setUnfocusedState;
+    private focusPrevious;
+    private focusNext;
+    private updateMnemonicVisibility;
+    private get mnemonicsInUse();
+    private set mnemonicsInUse(value);
+    private get shouldAltKeyFocus();
+    get onVisibilityChange(): Event<boolean>;
+    get onFocusStateChange(): Event<boolean>;
+    private onMenuTriggered;
+    private onModifierKeyToggled;
+    private isCurrentMenu;
+    private cleanupMenu;
+    private showMenu;
+    private rebuildOverflowMenu;
+}
+
+interface TitlebarThemeColors {
+    titlebar?: string;
+    titlebarForeground?: string;
+    menuBar?: string;
+    menuItemSelection?: string;
+    menuSeparator?: string;
+    svg?: string;
+}
+interface TitlebarThemeConfig {
+    /**
+     * Theme schema version. Current supported version is 1.
+     */
+    version?: number;
+    fontFamily?: string;
+    fontSize?: number;
+    colors?: TitlebarThemeColors;
+}
+interface TitleBarOptions extends MenuBarOptions {
+    /**
+     * The background color of titlebar.
+     * **The default is `#ffffff`**
+     */
+    backgroundColor?: Color;
+    /**
+     * Sets the value for the overflow of the container after title bar.
+     * **The default value is auto**
+     */
+    containerOverflow?: 'auto' | 'hidden' | 'visible';
+    /**
+     * Define if the close button is enabled.
+     * **The default is true**
+     */
+    closeable?: boolean;
+    /**
+     * When the close button is clicked, the window is hidden instead of closed.
+     * **The default is false**
+     */
+    /**
+     * The icon shown on the left side of titlebar.
+     * **The default is the favicon of the index.html**
+     */
+    icon?: NativeImage | string;
+    /**
+     * The icon size of titlebar. Value between 16 and 24.
+     * **The default is 16**
+     */
+    iconSize?: number;
+    /**
+     * Define if the maximize and restore buttons are enabled.
+     * **The default is true**
+     */
+    maximizable?: boolean;
+    /**
+     * Define if the minimize button is enabled.
+     * **The default is true**
+     */
+    minimizable?: boolean;
+    /**
+     * Set the order of the elements on the title bar. You can use `inverted`, `first-buttons` or don't add for.
+     * **The default is undefined**
+     */
+    order?: 'inverted' | 'first-buttons';
+    /**
+     * Show shadow of titlebar.
+     * **The default is false*
+     */
+    shadow?: boolean;
+    /**
+     * Set horizontal alignment of the window title.
+     * **The default value is center**
+     */
+    titleHorizontalAlignment?: 'left' | 'center' | 'right';
+    /**
+     * Set the titles of controls of the window.
+     */
+    tooltips?: {
+        /**
+        * The tooltip of minimize button.
+        * **The default is "Minimize"**
+        */
+        minimize?: string;
+        /**
+         * The tooltip of maximize button.
+         * **The default is "Maximize"**
+         */
+        maximize?: string;
+        /**
+         * The tooltip of restore button.
+         * **The default is "Restore Down"**
+         */
+        restoreDown?: string;
+        /**
+         * The tooltip of close button.
+         * **The default is "Close"**
+         */
+        close?: string;
+    };
+    /**
+     * Enables or disables the blur option in titlebar.
+     * *The default is true*
+     */
+    unfocusEffect?: boolean;
+    /**
+    * Controls the Minimum Width the user is allowed to resize the window to.
+    * **The default is 400*
+    */
+    minWidth?: number;
+    /**
+    * Controls the Minimum Height the user is allowed to resize the window to.
+    * **The default is 270*
+    */
+    minHeight?: number;
+    /**
+     * In-memory theme configuration for titlebar and menubar (optional, for backwards compatibility).
+     * Note: Prefer using themeConfigPath in setupTitlebarAndAttachToWindow() in main process instead.
+     */
+    themeConfig?: TitlebarThemeConfig;
+}
+
+interface CssStyle {
+    addRule(rule: string): void;
+}
+interface Theme {
+    (collector: CssStyle): void;
+}
+declare class ThemingRegistry extends Disposable {
+    private readonly theming;
+    constructor();
+    protected onThemeChange(theme: Theme): IDisposable;
+    protected getTheming(): Theme[];
+}
+declare class ThemeBar extends ThemingRegistry {
+    constructor();
+    protected registerTheme(theme: Theme): void;
+    static get win(): Theme;
+    static get mac(): Theme;
+}
+
+declare class CustomTitlebar extends ThemeBar {
+    private titlebar;
+    private dragRegion;
+    private icon;
+    private menuBarContainer;
+    private title;
+    private controlsContainer;
+    private container;
+    private menuBar?;
+    private titleResizeListener?;
+    private forcedForegroundColor?;
+    private isInactive;
+    private controls;
+    private resizer;
+    private currentOptions;
+    private platformIcons;
+    private readonly onWindowMaximizeEvent;
+    private readonly onWindowFullscreenEvent;
+    private readonly onWindowFocusEvent;
+    /**
+     * Create a new TitleBar instance
+     * @param options The options for the title bar
+     */
+    constructor(options?: TitleBarOptions);
+    private loadIcons;
+    /**
+     * Setup the background color of the title bar
+     * By default, it will use the meta theme-color or msapplication-TileColor and if it doesn't exist, it will use white
+     */
+    private setupBackgroundColor;
+    /**
+     * Render the icon of the title bar, if is mac, it will not render
+     * By default, it will use the first icon found in the head of the document
+     */
+    private createIcon;
+    private setIconSize;
+    private setupMenubar;
+    private setupTitle;
+    private createControlButton;
+    private setupWindowControls;
+    private setupContainer;
+    private setupTitleBar;
+    private loadEvents;
+    private closeMenu;
+    private onBlur;
+    private onFocus;
+    private onMenuBarVisibilityChanged;
+    private onMenuBarFocusChanged;
+    private onDidChangeMaximized;
+    private updateMenu;
+    private applyThemeConfigFromSource;
+    private applyThemeConfig;
+    private parseThemeColor;
+    private updateStyles;
+    private canCenterTitle;
+    /**
+     * Update title bar styles based on focus state.
+     * @param hasFocus focus state of the window
+     */
+    onWindowFocus(focus: boolean): void;
+    /**
+     * Update the full screen state and hide or show the title bar.
+     * @param fullscreen Fullscreen state of the window
+     */
+    onWindowFullScreen(fullscreen: boolean): void;
+    /**
+     * Update the title of the title bar.
+     * You can use this method if change the content of `<title>` tag on your html.
+     * @param title The title of the title bar and document.
+     */
+    updateTitle(title: string): this;
+    /**
+     * It method set new icon to title-bar-icon of title-bar.
+     * @param path path to icon
+     */
+    updateIcon(path: string): this;
+    /**
+     * Horizontal alignment of the title.
+     * @param side `left`, `center` or `right`.
+     */
+    updateTitleAlignment(side: 'left' | 'center' | 'right'): this;
+    /**
+     * Update the background color of the title bar
+     * @param backgroundColor The color for the background
+     */
+    updateBackground(backgroundColor: Color): this;
+    /**
+     * Update the item background color of the menubar
+     * @param itemBGColor The color for the item background
+     */
+    updateItemBGColor(itemBGColor: Color): this;
+    /**
+     * Update the menu from Menu.getApplicationMenu()
+     */
+    refreshMenu(): Promise<this>;
+    /**
+     * Update the position of menubar.
+     * @param menuPosition The position of the menu `left` or `bottom`.
+     */
+    updateMenuPosition(menuPosition: 'left' | 'bottom'): this;
+    /**
+     * Remove the titlebar, menubar and all methods.
+     */
+    dispose(): void;
+    get titlebarElement(): HTMLElement;
+    get menubarElement(): MenuBar | undefined;
+    get containerElement(): HTMLElement;
+    get titleElement(): HTMLElement;
+}
+
+declare const createTitlebar: (options?: TitleBarOptions) => CustomTitlebar;
+declare const createTitlebarOnDOMContentLoaded: (options?: TitleBarOptions) => Promise<CustomTitlebar>;
+
+export { CustomTitlebar, type TitleBarOptions, CustomTitlebar as Titlebar, Color as TitlebarColor, type TitlebarThemeConfig, createTitlebar, createTitlebarOnDOMContentLoaded };