tiny-electron-essentials
Version:
A lightweight and modular utility library for Electron apps, offering simplified window management, tray support, IPC channels, and custom frameless window styling.
220 lines • 11.1 kB
text/typescript
export default TinyWindowFrameManager;
/**
* TinyWindowFrameManager
*
* A powerful and fully customizable window frame manager for Electron applications
* that use frameless windows (`frame: false`). It replaces the native title bar with
* a fully configurable HTML/CSS/JS interface, allowing total control over window borders,
* title positioning, icons, menus, and control buttons (minimize, maximize, close).
*
* ✅ Features:
* - Fully draggable top bar and borders.
* - Highly customizable buttons: change order, position (left/right), and icons.
* - Configurable window title alignment: left, center, or right.
* - Dynamic menu sections on left and right, with support for custom elements and buttons.
* - Automatic handling of Electron window events: minimize, maximize, unmaximize, focus, blur, fullscreen.
* - Fully responsive to window state changes (maximized, fullscreen, focus).
* - Dynamic CSS styling with optional default styles, or supply your own CSS.
* - Change internal icons and class names via constructor or dynamically.
* - Clean, semantic, and framework-free: pure HTML, CSS, and JavaScript.
*
* 🚀 Usage example:
* ```js
* const frame = new TinyWindowFrameManager({
* client: myElectronClient,
* titlePosition: 'center',
* buttonsPosition: 'right',
* buttonsMap: ['minimize', 'maximize', 'close'],
* icons: { minimize: '-', maximize: '▢', unmaximize: '▣', close: '✖' },
* classes: { focus: 'win-focus', blur: 'win-blur', fullscreen: 'win-fullscreen', maximized: 'win-maximized' },
* });
*
* frame.setTitle('My Tiny App');
* frame.setIcon('icon.png');
* frame.addMenuButton('Settings', { onClick: () => openSettings(), position: 'right' });
* ```
*
* 🔧 Requirements:
* - Works only with Electron windows that are frameless (`frame: false`), transparent if desired, and `titleBarStyle: 'hidden'`.
* - Requires a client controller (like TinyElectronClient) that communicates with Electron's main process to handle window actions.
*
* 💡 Tip:
* You can completely replace or override the CSS with your own themes, animations, and layout changes.
*
* @class
*/
declare class TinyWindowFrameManager {
/**
* Creates an instance of the custom window frame with a draggable title bar,
* customizable buttons, class names, icons, and dynamic styling that integrates with Electron.
*
* @param {Object} [options] - Configuration options for the window frame.
* @param {boolean} [options.applyDefaultStyles=true] - If true, applies the default CSS styles automatically.
* @param {'left'|'right'} [options.buttonsPosition='right'] - Defines the position of the window control buttons (minimize, maximize, close).
* @param {'left'|'center'|'right'} [options.titlePosition='center'] - Defines the position of the window title in the top bar.
* @param {string[]} [options.buttonsMap=['minimize', 'maximize', 'close']] - Determines which buttons appear and their order. Valid values are 'minimize', 'maximize', and 'close'.
* @param {TinyElectronClient} [options.client] - The Electron client interface that handles window events like minimize, maximize, close, and focus.
* @param {string} [options.windowRoot='window-root'] - The ID for the root container.
* @param {Object} [options.icons] - Custom innerHTML icons for buttons.
* @param {string} [options.icons.minimize='🗕']
* @param {string} [options.icons.maximize='🗖']
* @param {string} [options.icons.unmaximize='🗗']
* @param {string} [options.icons.close='🗙']
* @param {Object} [options.classes] - Custom class names for window states.
* @param {string} [options.classes.blur='electron-blur']
* @param {string} [options.classes.focus='electron-focus']
* @param {string} [options.classes.fullscreen='electron-fullscreen']
* @param {string} [options.classes.maximized='electron-maximized']
*/
constructor({ applyDefaultStyles, buttonsPosition, titlePosition, buttonsMap, client, windowRoot, icons, classes, }?: {
applyDefaultStyles?: boolean | undefined;
buttonsPosition?: "left" | "right" | undefined;
titlePosition?: "left" | "right" | "center" | undefined;
buttonsMap?: string[] | undefined;
client?: TinyElectronClient | undefined;
windowRoot?: string | undefined;
icons?: {
minimize?: string | undefined;
maximize?: string | undefined;
unmaximize?: string | undefined;
close?: string | undefined;
} | undefined;
classes?: {
blur?: string | undefined;
focus?: string | undefined;
fullscreen?: string | undefined;
maximized?: string | undefined;
} | undefined;
});
/**
* Generates a formatted element name based on the given parameters.
*
* @param {string} [name=''] - The base name. If provided without leading space, a space will be prepended.
* @param {string} [extra=''] - Extra string appended after the window root (optional).
* @param {string} [extra2=''] - Extra string prepended at the beginning (optional).
* @returns {string} The fully formatted element name.
* @throws {TypeError} If any argument is not a string.
*/
getElementName(name?: string, extra?: string, extra2?: string): string;
/**
* Save CSS content into a .css file.
*
* @param {string} directory - The folder path where the file will be saved.
* @param {'default'|'root'} filename - The name of the css content.
* @returns {Promise<void>}
* @throws {TypeError} If directory is not a valid non-empty string.
* @throws {TypeError} If filename is not 'default' or 'root'.
* @throws {Error} If CSS content for the given filename does not exist.
* @throws {Error} If the file cannot be written.
*/
saveCssFileStructure(directory: string, filename: "default" | "root"): Promise<void>;
/**
* Get the HTML container element by its name.
*
* @param {'rootContent'|'root'|'frame'|'top'|'menuLeft'|'menuRight'|'icon'|'title'|'topLeft'|'topCenter'|'topRight'} name - The name of the element to retrieve.
* @returns {HTMLDivElement} - The corresponding HTMLDivElement.
* @throws {Error} If the element name is invalid.
*/
getHtml(name?: "rootContent" | "root" | "frame" | "top" | "menuLeft" | "menuRight" | "icon" | "title" | "topLeft" | "topCenter" | "topRight"): HTMLDivElement;
/**
* Get one of the window control buttons (minimize, maximize, close) or the buttons container.
*
* @param {'root'|'maximize'|'minimize'|'close'} name - The name of the button or container.
* @returns {HTMLButtonElement|HTMLDivElement} - The corresponding button or container.
* @throws {Error} If the button name is invalid.
*/
getButtonHtml(name: "root" | "maximize" | "minimize" | "close"): HTMLButtonElement | HTMLDivElement;
/**
* Add a custom HTML element to the left or right menu bar.
*
* @param {HTMLElement} element - The HTML element to add.
* @param {'left'|'right'} [position='left'] - The position of the menu to insert the element.
*/
addMenuCustomElement(element: HTMLElement, position?: "left" | "right"): void;
/**
* Show the menu bar (left or right) with a fade-in effect.
*
* @param {'left'|'right'} [position='left'] - The menu position to show.
*/
showMenu(position?: "left" | "right"): void;
/**
* Hide the menu bar (left or right) with a fade-out effect.
*
* @param {'left'|'right'} [position='left'] - Defines which menu to hide.
* @param {number} [fadeOutTime=200] - Duration of the fade-out effect in milliseconds. Must be a non-negative number.
* @throws {TypeError} If fadeOutTime is not a valid number.
* @throws {Error} If position is invalid.
*/
hideMenu(position?: "left" | "right", fadeOutTime?: number): void;
/**
* Get the menu DOM element (left or right).
*
* @param {'left'|'right'} [position='left'] - The position of the menu.
* @returns {HTMLDivElement} - The menu container element.
* @throws {Error} - If the position is invalid.
*/
getMenuElement(position?: "left" | "right"): HTMLDivElement;
/**
* Add a button to the menu bar with optional dropdown and submenus.
*
* @param {string} label - The text label of the button.
* @param {Object} [settings={}] - Button settings.
* @param {(this: GlobalEventHandlers, ev: MouseEvent) => any} [settings.onClick] - Click event handler for the button.
* @param {'left'|'right'} [settings.position='left'] - Menu position where the button will be placed.
* @param {string} [settings.id] - Optional identifier.
* @returns {HTMLButtonElement} - The created button element.
* @throws {TypeError} If label is not a string.
* @throws {TypeError} If onClick is not a function.
* @throws {Error} If position is invalid.
*/
addMenuButton(label: string, { onClick, position, id }?: {
onClick?: ((this: GlobalEventHandlers, ev: MouseEvent) => any) | undefined;
position?: "left" | "right" | undefined;
id?: string | undefined;
}): HTMLButtonElement;
/**
* Remove a menu button by its ID or by passing the HTMLElement itself.
*
* @param {string|HTMLElement} idOrElement - The button ID (from `data-menu-id`) or the button element itself.
* @param {'left'|'right'} [position='left'] - Menu position to target.
* @throws {TypeError} If idOrElement is not a string or HTMLElement.
* @throws {Error} If position is invalid.
*/
removeMenuButton(idOrElement: string | HTMLElement, position?: "left" | "right"): void;
/**
* Remove all elements from the menu bar (left or right).
*
* @param {'left'|'right'} [position='left'] - The menu position to clear.
* @throws {Error} If position is invalid.
*/
clearMenu(position?: "left" | "right"): void;
/**
* Change the window title text.
*
* @param {string} text - The new title to display.
* @throws {TypeError} If text is not a string.
*/
setTitle(text: string): void;
/**
* Set or update the window icon image.
*
* @param {string} url - The URL of the image to use as the icon. Pass an empty string to remove the icon.
* @throws {TypeError} If url is not a string.
*/
setIcon(url: string): void;
/**
* Remove the current window icon from the title bar.
*/
removeIcon(): void;
/**
* Apply custom CSS to the document.
*
* @param {string} css - The CSS rules as a string.
* @returns {HTMLStyleElement} - The created <style> element appended to the document head.
* @throws {TypeError} If css is not a string.
*/
applyCustomStyle(css: string): HTMLStyleElement;
#private;
}
import TinyElectronClient from './TinyElectronClient.mjs';
//# sourceMappingURL=TinyWindowFrameManager.d.mts.map