# API Reference

NidamJS exposes a carefully curated set of public functions and classes designed for interacting with its windowing system, desktop icons, and event delegation.

Initializes the NidamApp with an optional configuration object and returns the fully initialized app instance.

Note: NidamJS will automatically call initNidamApp() on script load unless you add a script tag with the [data-nd-init] attribute to your document to signify manual initialization.

Parameters:

• config (Object | string) (Optional): The NidamJS configuration object or JSON string.

Returns:

• NidamApp: The initialized application instance.

Example:

import { initNidamApp } from "nidamjs";

const app = initNidamApp({
  windowManager: { layoutStabilizationMs: 450 },
});

The main instance returned by initialization. It coordinates all modules in the NidamJS ecosystem.

Retrieves a specific initialized module by its registered name. This is the primary way to programmatically interact with NidamJS at runtime.

Parameters:

• name (string): The name of the module. Valid module names are "window", "delegator", "taskbar", "refresher", and "icon".

Returns:

• The requested module instance, or undefined if not found.

Example:

const app = initNidamApp();

// Access the window manager
const windowManager = app.getModule("window");
windowManager.open("my-settings-modal");

Retrieves all initialized modules.

Returns:

• Map<string, object>: A JavaScript Map containing all available module instances.

After initializing NidamJS, you can access the core modules to manually trigger actions like opening windows, refreshing content, or listening to global events.

Controls the lifecycle, focus, and state of windows/modals. Accessible via app.getModule("window").

• open(endpoint, force = false, focusSelector = null, activate = true) Opens a new window based on its endpoint or focuses an existing one. Returns a Promise tracking the DOM injection and initialization.

• close(winElement) Closes the specified window element. Triggered automatically by GUI buttons.

• closeTopmost() Closes the active (topmost/focused) window. Often mapped internally to the "Escape" key behavior.

• getWindows() Returns an array of [endpoint, winElement] pairs representing all currently open windows.

• focus(winElement) Brings the specified window to the front by updating its z-index position.

• toggleMaximize(winElement) Toggles the given window between its maximized state and its previous restored bounds.

• drag(e, winElement) Manually triggers a window drag operation, consuming a MouseEvent.

Handles centralized root-level HTML event delegation (like click, mousedown, keydown).

• on(eventType, selector, handler, options = { group }) Registers a delegated event handler on the app's root. If selector is null, it works as a global handler. Returns a handler reference object.

• off(eventType, ref) Removes a previously registered event handler using the reference object returned by .on().

Synchronizes the HTML taskbar layer functionality and icon rendering with the currently open modal instances. Interaction is primarily automatic across $window:opened and $window:closed events.

Controls desktop icon grid positioning constraints, snapping, and layout memory functionality on the DOM [nd-icons] container.