@janusui/janus-ui-library 0.0.1

package/types/janusui-janus-ui-library.d.ts

@@ -0,0 +1,468 @@
+import * as _angular_core from '@angular/core';
+import { Type, InjectionToken, Signal, WritableSignal, EnvironmentProviders, AfterViewInit, OnDestroy, ElementRef, OnInit } from '@angular/core';
+
+/**
+ * Predefined color groups for symbol linking across widgets.
+ * Works like IB's color-linked groups: changing the symbol in one "red" widget
+ * updates all other "red" widgets automatically.
+ */
+type ColorGroup = 'red' | 'green' | 'blue' | 'yellow' | 'orange' | 'purple' | 'cyan' | 'magenta' | 'lime' | 'pink';
+/** All available color groups for iterating in dropdowns / pickers. */
+declare const COLOR_GROUPS: ColorGroup[];
+/** CSS-friendly hex values for each color group. */
+declare const COLOR_GROUP_HEX: Record<ColorGroup, string>;
+
+/** Supported theme modes. */
+type Theme = 'light' | 'dark';
+
+/**
+ * Metadata that every widget panel registers at startup.
+ * Used by WidgetWindow to know default sizing and by WorkspaceService
+ * to reconstruct components from saved state.
+ */
+interface WidgetMeta {
+    /** Unique discriminator — matches WidgetPanelState.type. */
+    type: string;
+    /** The Angular standalone component class. */
+    component: Type<unknown>;
+    /** Display name shown in the "Add Widget" dropdown. */
+    label: string;
+    /** Default width in grid column units. */
+    defaultCols: number;
+    /** Default height in grid row units. */
+    defaultRows: number;
+    /** Minimum width in grid column units. */
+    minCols: number;
+    /** Minimum height in grid row units. */
+    minRows: number;
+}
+
+/**
+ * Serializable snapshot of a single widget panel within a WidgetWindow grid.
+ * Used for persistence to localStorage and cross-window state sync.
+ */
+interface WidgetPanelState {
+    /** Unique widget instance identifier. */
+    id: string;
+    /** Discriminator for component reconstruction (e.g. 'watchlist', 'portfolio'). */
+    type: string;
+    /** Gridstack column position. */
+    gridX: number;
+    /** Gridstack row position. */
+    gridY: number;
+    /** Width in grid column units. */
+    gridCols: number;
+    /** Height in grid row units. */
+    gridRows: number;
+    /** Color group this widget is linked to, if any. */
+    colorGroup?: ColorGroup;
+}
+
+/**
+ * Serializable snapshot of a single WidgetWindow.
+ * A workspace contains one or more WidgetWindows (for multi-monitor support).
+ */
+interface WidgetWindowState {
+    /** Unique window identifier. */
+    id: string;
+    /** Editable display title. */
+    title: string;
+    /** Screen position and size (for popup windows). */
+    bounds: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    /** Whether this window is minimized. */
+    minimized: boolean;
+    /** Current lifecycle state. */
+    state: 'open' | 'closed';
+    /** Gridstack layout — ordered array of widget panel placements. */
+    widgets: WidgetPanelState[];
+}
+
+/**
+ * Public API surface that the ScreenWidgetComponent wrapper exposes
+ * to the inner content component via dependency injection.
+ *
+ * Inject `SCREEN_WIDGET_API` in your widget component to communicate
+ * with the wrapper (e.g. read/publish linked data, change the title).
+ *
+ * The wrapper owns all WidgetLinkService interaction — individual
+ * widgets never need to know about the linking service directly.
+ *
+ * @example
+ * ```ts
+ * private readonly api = inject(SCREEN_WIDGET_API);
+ *
+ * // Read the current accumulated data reactively
+ * const d = this.api.data();
+ *
+ * // Cherry-pick fields your widget cares about
+ * const sym = d?.['symbol'] as string | undefined;
+ *
+ * // Publish partial data to all widgets in the same color group
+ * this.api.publishData({ symbol: 'AAPL' });
+ *
+ * // Override the titlebar text
+ * api.setTitle('AAPL – Apple Inc.');
+ * ```
+ */
+interface ScreenWidgetApi {
+    /** The unique widget instance ID. */
+    readonly widgetId: Signal<string>;
+    /** The parent window ID. */
+    readonly windowId: Signal<string>;
+    /** The color group this widget is linked to, or undefined if unlinked. */
+    readonly colorGroup: Signal<ColorGroup | undefined>;
+    /** The accumulated JSON data for this widget's color group (reactive). */
+    readonly data: Signal<Record<string, unknown>>;
+    /**
+     * Publish partial JSON data to all widgets sharing this widget's color group.
+     * Shallow-merged: keys you provide overwrite, keys you omit survive.
+     * Pass `null` as a value to remove a key.
+     */
+    publishData(partial: Record<string, unknown>): void;
+    /** Update the title displayed in the widget header. */
+    setTitle(title: string): void;
+}
+/** Injection token for the ScreenWidgetApi. Provided by ScreenWidgetComponent. */
+declare const SCREEN_WIDGET_API: InjectionToken<ScreenWidgetApi>;
+
+/**
+ * Multi-provider token. Each widget module provides its metadata via this token.
+ * WorkspaceService collects all provided values to populate the widget registry.
+ */
+declare const WIDGET_META: InjectionToken<WidgetMeta>;
+
+interface GridConfig {
+    columns: number;
+    cellWidth: number;
+    cellHeight: number;
+    gap: number;
+    containerWidth: number;
+}
+interface PixelRect {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+}
+/**
+ * Pure grid math engine. No DOM manipulation — just calculations.
+ * Angular owns all rendering via templates.
+ */
+declare class LayoutEngine {
+    private readonly TARGET_CELL_WIDTH;
+    readonly MIN_COLUMNS = 6;
+    readonly MAX_COLUMNS = 36;
+    readonly CELL_HEIGHT = 20;
+    readonly GAP = 4;
+    readonly observers: WeakMap<HTMLElement, () => void>;
+    /** Compute column count for a given container width. */
+    computeColumns(containerWidth: number): number;
+    /** Build full grid config from container width. */
+    getConfig(containerWidth: number): GridConfig;
+    /** Convert grid units to pixel rectangle. All units share the same uniform step. */
+    rectToPixel(cfg: GridConfig, col: number, row: number, w: number, h: number): PixelRect;
+    /** Snap pixel position to nearest uniform grid cell. */
+    snapToGrid(cfg: GridConfig, px: number, py: number): {
+        col: number;
+        row: number;
+    };
+    /** Snap pixel size to nearest uniform grid size. */
+    snapSize(cfg: GridConfig, pw: number, ph: number, minCols: number, minRows: number): {
+        w: number;
+        h: number;
+    };
+    /** Observe container resizes and call back with new config. */
+    observe(container: HTMLElement, onResize: (cfg: GridConfig) => void): void;
+    /** Stop observing a container. */
+    unobserve(container: HTMLElement): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<LayoutEngine, never>;
+    static ɵprov: _angular_core.ɵɵInjectableDeclaration<LayoutEngine>;
+}
+
+/**
+ * Central singleton that tracks arbitrary JSON payloads per color group.
+ *
+ * Widgets assigned to the same color group all see the same accumulated
+ * data. Each widget publishes partial JSON — the service shallow-merges
+ * it into the group state. Keys a widget doesn't touch are left intact.
+ *
+ * To remove a key you previously set, publish it as `null`.
+ *
+ * Persistence is handled by WorkspaceService via {@link getAllData} /
+ * {@link setAllData}. This service does not touch localStorage directly.
+ */
+declare class WidgetLinkService {
+    private readonly state;
+    constructor();
+    /** Get the reactive data signal for a color group. */
+    getData(color: ColorGroup): WritableSignal<Record<string, unknown>>;
+    /** Read the current data value (non-reactive snapshot). */
+    getDataSnapshot(color: ColorGroup): Record<string, unknown>;
+    /**
+     * Publish a partial JSON payload to a color group.
+     *
+     * Shallow-merged with the existing state:
+     * - New keys are added.
+     * - Existing keys the caller provides are overwritten.
+     * - Keys the caller does NOT provide survive untouched.
+     * - Keys with `null` or `undefined` values are removed.
+     */
+    publishData(color: ColorGroup, partial: Record<string, unknown>): void;
+    /** Reset all color groups to empty state. */
+    resetAll(): void;
+    /**
+     * Return a snapshot of all color group data for serialization.
+     * Called by WorkspaceService during save.
+     */
+    getAllData(): Record<string, Record<string, unknown>>;
+    /**
+     * Restore color group data from a previously saved snapshot.
+     * Called by WorkspaceService during load.
+     */
+    setAllData(data: Record<string, Record<string, unknown>>): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<WidgetLinkService, never>;
+    static ɵprov: _angular_core.ɵɵInjectableDeclaration<WidgetLinkService>;
+}
+
+/**
+ * Central singleton that owns the full workspace state:
+ * an array of WidgetWindows, each containing a grid of widget panels.
+ *
+ * All mutations flow through this service so that persistence and
+ * cross-window sync (BroadcastChannel) stay consistent.
+ */
+declare class WorkspaceService {
+    #private;
+    /** All windows in the workspace. */
+    readonly windows: _angular_core.WritableSignal<WidgetWindowState[]>;
+    /** Reactive list of registered widget type strings (for dropdowns). */
+    readonly widgetTypes: _angular_core.WritableSignal<string[]>;
+    /** Reactive list of widget labels (for dropdown display). */
+    readonly widgetLabels: _angular_core.WritableSignal<string[]>;
+    /** Registry mapping widget type strings to their metadata + component class. */
+    readonly widgetRegistry: Map<string, WidgetMeta>;
+    constructor();
+    /** Get metadata for a widget type. */
+    getWidgetMeta(type: string): WidgetMeta | undefined;
+    /** Create a new empty WidgetWindow and add it to the workspace. */
+    addWindow(title?: string): WidgetWindowState;
+    /** Remove a window by ID. The last remaining window cannot be removed. */
+    removeWindow(windowId: string): void;
+    /** Update a window's screen bounds (position / size). */
+    updateWindowBounds(windowId: string, bounds: WidgetWindowState['bounds']): void;
+    /** Toggle minimized state. */
+    toggleMinimize(windowId: string): void;
+    /** Set a window's lifecycle state ('open' or 'closed'). */
+    setWindowState(windowId: string, state: 'open' | 'closed'): void;
+    /** Set a window's display title. Empty / blank titles default to 'My Window'. */
+    setWindowTitle(windowId: string, title: string): void;
+    /**
+     * Add a widget panel to a specific window.
+     * Uses the widget's registered metadata for default sizing.
+     */
+    addWidget(windowId: string, type: string): WidgetPanelState | undefined;
+    /** Remove a widget panel by its ID. */
+    removeWidget(windowId: string, widgetId: string): void;
+    /** Update a widget's grid position and/or size. */
+    updateWidgetLayout(windowId: string, widgetId: string, patch: Partial<Pick<WidgetPanelState, 'gridX' | 'gridY' | 'gridCols' | 'gridRows'>>): void;
+    /** Set the color group for a widget panel. */
+    setWidgetColorGroup(windowId: string, widgetId: string, colorGroup: WidgetPanelState['colorGroup']): void;
+    /** Serialize the entire workspace to localStorage. */
+    save(): void;
+    /** Replace all windows with a previously saved snapshot. */
+    restore(snapshot: WidgetWindowState[]): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<WorkspaceService, never>;
+    static ɵprov: _angular_core.ɵɵInjectableDeclaration<WorkspaceService>;
+}
+
+/**
+ * Format a number to a fixed number of decimal places.
+ */
+declare function fmt(value: number, decimals?: number): string;
+
+/**
+ * Abstract base class for all screen widgets.
+ *
+ * Provides the shared state and logic that every widget needs:
+ * - Inputs: widgetId, windowId, meta
+ * - Reactive signals: title, colorGroup, data
+ * - Action methods: setTitle, publishData, onColorGroupChange, onRemove
+ * - Color picker data: colors, colorHex
+ *
+ * Concrete widgets extend this class and use {@link WidgetChromeComponent}
+ * in their template to render the common chrome (titlebar, color picker,
+ * remove button) while projecting their own content into the body slot.
+ *
+ * All members are `protected` so inheriting widgets can access them
+ * directly — no dependency injection token needed.
+ */
+declare abstract class ScreenWidgetBase {
+    #private;
+    /** Unique widget instance ID — provided by WidgetWindow. */
+    readonly widgetId: _angular_core.InputSignal<string>;
+    /** ID of the parent window — provided by WidgetWindow. */
+    readonly windowId: _angular_core.InputSignal<string>;
+    /** Widget metadata (type, label, default sizing, etc.). */
+    readonly meta: _angular_core.InputSignal<WidgetMeta>;
+    protected readonly workspace: WorkspaceService;
+    protected readonly widgetLink: WidgetLinkService;
+    /** Overridable title — starts from meta().label, settable via setTitle(). */
+    readonly title: Signal<string>;
+    /** The color group for this widget, read from the workspace state. */
+    readonly colorGroup: Signal<ColorGroup | undefined>;
+    /**
+     * The accumulated JSON data for this widget's color group.
+     * Automatically tracks the WidgetLinkService signal for whatever
+     * color group is currently assigned.
+     */
+    readonly data: Signal<Record<string, unknown>>;
+    protected readonly colors: ColorGroup[];
+    protected readonly colorHex: Record<ColorGroup, string>;
+    /** Allow the widget to override the header title at runtime. */
+    setTitle(title: string): void;
+    /**
+     * Publish partial JSON data to all widgets sharing this widget's color group.
+     * Shallow-merged: keys you provide overwrite, keys you omit survive.
+     * Pass `null` as a value to remove a key. No-op if no color group assigned.
+     *
+     * @example
+     * this.publishData({ symbol: 'AAPL' });
+     * this.publishData({ resistance: 543.21 });
+     */
+    publishData(partial: Record<string, unknown>): void;
+    /** Update the color group for this widget in the workspace. */
+    onColorGroupChange(cg: ColorGroup | undefined): void;
+    /** Remove this widget from its parent window. */
+    onRemove(): void;
+    /** Convenience alias for the color picker dropdown. */
+    selectColor(color: ColorGroup | undefined): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<ScreenWidgetBase, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<ScreenWidgetBase, never, never, { "widgetId": { "alias": "widgetId"; "required": true; "isSignal": true; }; "windowId": { "alias": "windowId"; "required": true; "isSignal": true; }; "meta": { "alias": "meta"; "required": true; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
+/**
+ * Register a widget via the WIDGET_META multi-provider token.
+ * Call this from a root-level provider factory to make the widget
+ * discoverable by WorkspaceService.
+ *
+ * The `component` field should point to the full widget component
+ * (the one that extends {@link ScreenWidgetBase} and includes
+ * the {@link WidgetChromeComponent} in its template).
+ *
+ * @example
+ * export function provideWatchlistWidget(): EnvironmentProviders {
+ *   return provideWidget({
+ *     type: 'watchlist',
+ *     component: Watchlist,
+ *     label: 'Watchlist',
+ *     defaultCols: 16,
+ *     defaultRows: 6,
+ *     minCols: 8,
+ *     minRows: 3,
+ *   });
+ * }
+ */
+declare function provideWidget(meta: WidgetMeta): EnvironmentProviders;
+
+/**
+ * Reusable widget chrome component that renders the common titlebar:
+ * color-group picker, dynamic title, and remove button.
+ *
+ * Uses `<ng-content>` to project the widget-specific body content.
+ *
+ * This component is **purely presentational** — all business logic
+ * (workspace mutations, symbol linking) lives in {@link ScreenWidgetBase}
+ * and is wired up by the concrete widget's template.
+ */
+declare class WidgetChromeComponent {
+    /** The current title text to display in the header. */
+    readonly title: _angular_core.InputSignal<string>;
+    /** The current color group, or undefined if unlinked. */
+    readonly colorGroup: _angular_core.InputSignal<ColorGroup | undefined>;
+    /** Emitted when the user selects a different color group (or "No link"). */
+    readonly colorChange: _angular_core.OutputEmitterRef<ColorGroup | undefined>;
+    /** Emitted when the user clicks the remove (×) button. */
+    readonly remove: _angular_core.OutputEmitterRef<void>;
+    protected readonly colors: ColorGroup[];
+    protected readonly colorHex: Record<ColorGroup, string>;
+    protected selectColor(color: ColorGroup | undefined): void;
+    protected onRemove(): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<WidgetChromeComponent, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<WidgetChromeComponent, "janus-widget-chrome", never, { "title": { "alias": "title"; "required": true; "isSignal": true; }; "colorGroup": { "alias": "colorGroup"; "required": false; "isSignal": true; }; }, { "colorChange": "colorChange"; "remove": "remove"; }, never, ["*"], true, never>;
+}
+
+declare class WidgetWindow implements AfterViewInit, OnDestroy {
+    readonly windowId: _angular_core.InputSignal<string>;
+    private readonly workspace;
+    private readonly engine;
+    readonly bodyEl: _angular_core.Signal<ElementRef<HTMLElement>>;
+    readonly availableTypes: _angular_core.WritableSignal<string[]>;
+    readonly availableLabels: _angular_core.WritableSignal<string[]>;
+    readonly cfg: _angular_core.WritableSignal<GridConfig>;
+    /** Active intervals for polling popup closure. */
+    private readonly popupIntervals;
+    /** Dynamic background grid that matches our uniform layout step. */
+    protected readonly gridBgSize: _angular_core.Signal<string>;
+    /** Offset the background so dots land at the center of gap intersections. */
+    protected readonly gridBgPosition: _angular_core.Signal<string>;
+    protected readonly widgets: _angular_core.Signal<WidgetPanelState[]>;
+    protected readonly widgetRects: _angular_core.Signal<Map<string, PixelRect>>;
+    /** All popup windows (open or closed), for the window dropdown. */
+    protected readonly popupWindows: _angular_core.Signal<WidgetWindowState[]>;
+    /** Popup windows the user has intentionally closed. */
+    protected readonly closedWindows: _angular_core.Signal<WidgetWindowState[]>;
+    /** Title of the current window (reactive). */
+    protected readonly windowTitle: _angular_core.Signal<string>;
+    /** Title text width estimate (14px font, ~8.4px avg char width, + 12px padding). */
+    protected readonly titleWidth: _angular_core.Signal<number>;
+    private editingTitle;
+    constructor();
+    ngAfterViewInit(): void;
+    ngOnDestroy(): void;
+    addWidget(type: string): void;
+    /** Create a new chromeless popup window containing a fresh WidgetWindow. */
+    protected openNewWindow(existingId?: string): void;
+    /** Reopen a previously closed popup window. */
+    protected reopenWindow(windowId: string): void;
+    /** Permanently discard a closed window and all its widgets. */
+    protected discardWindow(windowId: string): void;
+    /** Reopen all previously closed popup windows at once. */
+    protected reopenAllClosed(): void;
+    /**
+     * Handle popup closure: discard empty windows, keep windows with content
+     * saved in localStorage (hidden from the main workspace).
+     */
+    private closePopupWindow;
+    protected onTitleFocus(event: FocusEvent): void;
+    protected onTitleEnter(event: Event): void;
+    protected onTitleBlur(event: FocusEvent): void;
+    protected getMeta(type: string): WidgetMeta | undefined;
+    protected getRect(widgetId: string): PixelRect;
+    protected onDragStart(event: MouseEvent, w: WidgetPanelState): void;
+    protected onResizeStart(event: MouseEvent, w: WidgetPanelState): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<WidgetWindow, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<WidgetWindow, "janus-widget-window", never, { "windowId": { "alias": "windowId"; "required": true; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
+declare class WindowOutlet implements OnInit, OnDestroy {
+    private readonly route;
+    protected windowId: string;
+    private heartbeatInterval;
+    ngOnInit(): void;
+    ngOnDestroy(): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<WindowOutlet, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<WindowOutlet, "app-window-outlet", never, {}, {}, never, never, true, never>;
+}
+
+declare class Janusui {
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<Janusui, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<Janusui, "lib-janusui", never, {}, {}, never, never, true, never>;
+}
+
+export { COLOR_GROUPS, COLOR_GROUP_HEX, Janusui, LayoutEngine, SCREEN_WIDGET_API, ScreenWidgetBase, WIDGET_META, WidgetChromeComponent, WidgetLinkService, WidgetWindow, WindowOutlet, WorkspaceService, fmt, provideWidget };
+export type { ColorGroup, GridConfig, PixelRect, ScreenWidgetApi, Theme, WidgetMeta, WidgetPanelState, WidgetWindowState };