react-dockable-desktop 1.2.0 → 2.0.0

package/dist/index.d.ts

@@ -58,6 +58,7 @@ interface PanelRegistryEntry {
 /**
  * Registry mapping catalog entries to allow programmatic panel instantiation
  * inside dynamic layout cells or floating windows.
+ * Exported so WorkspaceClient can create scoped, per-instance registries.
  */
 declare class PanelRegistryClass {
     private registry;
@@ -89,7 +90,7 @@ declare const PanelRegistry: PanelRegistryClass;
  * define in their IntlProvider messages table. The `defaultMessage` is used
  * as a fallback when no external formatter is provided.
  *
- * Pass a partial or full override to <WindowManagerProvider predefinedMessages={…} />
+ * Pass a partial or full override to `<WindowManagerProvider predefinedMessages={…} />`
  * to customise labels without replacing the whole table.
  */
 declare const defaultPredefinedMessages: {
@@ -357,73 +358,221 @@ interface WindowState {
     isRtl: boolean;
 }
 /**
- * Interface mapping layout actions, event bus handles, and serialization methods.
+ * All layout mutation methods, event bus handles, and serialization methods
+ * exposed by the `WindowManagerProvider`.
+ *
+ * Obtain this object via {@link useWindowManagerActions} inside a component,
+ * or via {@link WorkspaceClient} methods from outside the React tree.
+ *
+ * @group Hooks
+ * @example
+ * ```tsx
+ * function MyToolbar() {
+ *   const actions = useWindowManagerActions();
+ *   return <button onClick={() => actions.openPanel('map-1', 'map')}>Open Map</button>;
+ * }
+ * ```
  */
 interface WindowActions {
-    /** Instantiates a registered panel into the workspace. */
+    /**
+     * Opens a registered panel into the workspace.
+     * If the panel ID is already open, the panel is focused instead of duplicated.
+     * @param id - Unique instance identifier for this panel.
+     * @param component - Component key registered in the panel catalog.
+     * @param options - Optional display and placement overrides.
+     * @example
+     * ```ts
+     * actions.openPanel('map-1', 'map', { title: 'Satellite View', initialTarget: 'floating' });
+     * ```
+     */
     openPanel: (id: string, component: string, options?: {
         title?: string | ContextMenuPredefinedMessage;
         initialTarget?: 'floating' | 'docked' | 'tabbed';
         stickyRight?: boolean;
         stickyBottom?: boolean;
     }) => void;
-    /** Directly closes a panel by ID, bypassing close confirmation dialogs. */
+    /**
+     * Closes a panel immediately, bypassing dirty-state close guards.
+     * For guarded close, use {@link requestClosePanel}.
+     * @param id - Panel instance ID.
+     */
     closePanel: (id: string) => void;
-    /** Minimizes a panel to the bottom taskbar, saving its current layout positioning. */
+    /**
+     * Minimizes a panel to the bottom taskbar dock, preserving its layout position.
+     * @param id - Panel instance ID.
+     */
     minimizePanel: (id: string) => void;
-    /** Restores a minimized panel back to its previous position in the grid or as a float. */
+    /**
+     * Restores a minimized panel back to its last docked or floating position.
+     * @param id - Panel instance ID.
+     */
     restorePanel: (id: string) => void;
-    /** Detaches a docked panel, turning it into a floating resizable window. */
+    /**
+     * Detaches a docked panel, converting it to a resizable floating window.
+     * @param id - Panel instance ID.
+     * @param rect - Optional initial position and size for the floating window.
+     */
     floatPanel: (id: string, rect?: {
         x: number;
         y: number;
         width: number;
         height: number;
     }) => void;
-    /** Returns a floating window back to a docked grid tab group. */
+    /**
+     * Returns a floating window to a docked grid tab group.
+     * @param id - Panel instance ID.
+     * @param targetLeafId - Target leaf group ID. Defaults to the panel's last leaf.
+     */
     dockPanel: (id: string, targetLeafId?: string) => void;
-    /** Maximizes a floating window to cover the entire layout screen boundaries. */
+    /**
+     * Maximizes a floating window to cover the entire workspace viewport.
+     * @param id - Panel instance ID.
+     */
     maximizePanel: (id: string) => void;
-    /** Resizes flex dimensions of children inside split layout rows/columns. */
+    /**
+     * Resizes the flex split proportions of a branch node's children.
+     * @param path - Index path from root to the branch node.
+     * @param sizes - New proportional sizes (must sum to 1.0).
+     */
     updateSplitSizes: (path: number[], sizes: number[]) => void;
-    /** Updates bounds or positioning attributes on a floating window. */
+    /**
+     * Updates the position or size of a floating window.
+     * @param id - Panel instance ID.
+     * @param updates - Partial update to `x`, `y`, `width`, `height`, `stickyRight`, or `stickyBottom`.
+     */
     updateFloatingPosition: (id: string, updates: Partial<Pick<FloatingWindow, 'x' | 'y' | 'width' | 'height' | 'stickyRight' | 'stickyBottom'>>) => void;
-    /** Pushes a floating window z-index layer to render on top of others. */
-    bringToFront: (id: string) => void;
-    /** Serializes the active grid node structures and panel targets to JSON. */
+    /**
+     * Activates the given panel regardless of its current state.
+     * - Floating panel: raises z-index so the window appears on top of others.
+     * - Docked panel: selects the tab within its leaf group.
+     * @param id - Panel instance ID.
+     * @example
+     * ```ts
+     * // Ensure a panel is visible before updating its content:
+     * if (actions.isOpen('map-1')) actions.focusPanel('map-1');
+     * ```
+     */
+    focusPanel: (id: string) => void;
+    /**
+     * Returns `true` if a panel with the given ID is currently open (docked, floating, or minimized).
+     * Uses a synchronous `stateRef` read — safe to call outside of render.
+     * @param id - Panel instance ID.
+     * @returns `true` if the panel is open.
+     * @example
+     * ```ts
+     * if (!actions.isOpen('map-1')) {
+     *   actions.openPanel('map-1', 'map');
+     * } else {
+     *   actions.focusPanel('map-1');
+     * }
+     * ```
+     */
+    isOpen: (id: string) => boolean;
+    /**
+     * Returns the IDs of all currently open panels (docked, floating, and minimized).
+     * Uses a synchronous `stateRef` read — safe to call outside of render.
+     * @returns Array of panel instance IDs.
+     */
+    getOpenPanelIds: () => string[];
+    /**
+     * Serializes the entire workspace state to a JSON string.
+     * Includes grid layout, floating window positions, minimized panels, and panel metadata.
+     * @returns JSON string suitable for storage and later restoration via {@link loadLayout}.
+     * @example
+     * ```ts
+     * localStorage.setItem('layout', actions.saveLayout());
+     * ```
+     */
     saveLayout: () => string;
-    /** Rebuilds the grid layouts and floating window placements from a JSON string. */
+    /**
+     * Restores a previously serialized workspace from a JSON string.
+     * Replaces the entire current layout — all panels not in the snapshot are closed.
+     * @param layoutJson - JSON string produced by {@link saveLayout}.
+     */
     loadLayout: (layoutJson: string) => void;
-    /** Publishes an event to the global inter-panel message bus. */
+    /**
+     * Publishes an event to the inter-panel pub/sub event bus.
+     * @param event - Event name string.
+     * @param data - Arbitrary payload passed to all subscribers.
+     */
     publish: (event: string, data: any) => void;
-    /** Subscribes callback listeners to inter-panel event messages. */
+    /**
+     * Subscribes a callback to the inter-panel pub/sub event bus.
+     * @param event - Event name string.
+     * @param callback - Function called with the event payload.
+     * @returns Unsubscribe function — call it to remove the listener.
+     * @example
+     * ```ts
+     * useEffect(() => actions.subscribe('map:zoom', ({ level }) => setZoom(level)), []);
+     * ```
+     */
     subscribe: (event: string, callback: (data: any) => void) => () => void;
-    /** Stores reference to the active tab ID being dragged. */
+    /** @internal Stores reference to the active tab ID being dragged. */
     setDraggedPanelId: (id: string | null) => void;
-    /** Splits an existing tab group to dock a dragged panel next to it. */
+    /**
+     * Splits an existing leaf group and docks a panel to the given side.
+     * @param id - Panel instance ID to dock.
+     * @param targetLeafId - Leaf group ID to split.
+     * @param position - Which side of the target to split and dock into.
+     */
     dockPanelToGroup: (id: string, targetLeafId: string, position: 'left' | 'right' | 'top' | 'bottom' | 'center') => void;
-    /** Reorders tab indices inside a docked leaf group. */
+    /**
+     * Reorders a panel's tab index within a docked leaf group.
+     * @param panelId - Panel instance ID to move.
+     * @param targetLeafId - Destination leaf group ID.
+     * @param targetIndex - New tab index within the target group.
+     */
     movePanelOrder: (panelId: string, targetLeafId: string, targetIndex: number) => void;
-    /** Closes an empty split group. */
+    /**
+     * Closes an empty leaf group (removes it from the grid tree).
+     * @param leafId - Leaf node ID to remove.
+     */
     closeLeafGroup: (leafId: string) => void;
-    /** Binds a close intercept confirmation guard. */
+    /**
+     * Registers a close guard that can intercept and cancel panel close requests.
+     * @param id - Panel instance ID to guard.
+     * @param guard - Function returning `true` (allow close) or `false` / `Promise<false>` (block).
+     */
     registerCloseGuard: (id: string, guard: () => boolean | Promise<boolean>) => void;
-    /** Removes close confirmation guards. */
+    /**
+     * Removes a previously registered close guard.
+     * @param id - Panel instance ID.
+     */
     unregisterCloseGuard: (id: string) => void;
-    /** Set panel dirty state flag. */
+    /**
+     * Marks a panel as dirty (has unsaved changes). Dirty panels show a visual indicator
+     * and the built-in close guard prompts the user before closing.
+     * @param id - Panel instance ID.
+     * @param dirty - `true` to mark dirty, `false` to clear.
+     * @param options - Custom confirmation dialog options.
+     */
     setPanelDirty: (id: string, dirty: boolean, options?: DirtyStateOptions) => void;
-    /** Change title header. */
+    /**
+     * Updates the display title of an open panel.
+     * @param id - Panel instance ID.
+     * @param title - New title string or localizable message descriptor.
+     */
     updatePanelTitle: (id: string, title: string | ContextMenuPredefinedMessage) => void;
-    /** Intercepts close panel requests, prompting warning dialogs if dirty. */
+    /**
+     * Closes a panel, first running any registered close guards.
+     * If the panel is dirty, shows the built-in unsaved-changes confirmation dialog.
+     * @param id - Panel instance ID.
+     * @param options - `force: true` bypasses guards; `onConfirm` provides a custom dialog.
+     */
     requestClosePanel: (id: string, options?: {
         force?: boolean;
         onConfirm?: (opts?: DirtyStateOptions) => Promise<boolean>;
     }) => Promise<void>;
-    /** Docks a panel directly to workspace edges. */
+    /**
+     * Docks a floating panel to a workspace edge, creating a full-width or full-height column/row.
+     * @param id - Panel instance ID.
+     * @param position - Edge to dock to.
+     */
     dockPanelToWorkspaceEdge: (id: string, position: 'left' | 'right' | 'top' | 'bottom') => void;
-    /** Update active focused tab reference. */
-    setActivePanel: (id: string | null) => void;
-    /** Explicitly set or override layout direction */
+    /**
+     * Overrides the workspace layout direction.
+     * @param dir - `'ltr'` or `'rtl'`.
+     */
     setDirection: (dir: 'ltr' | 'rtl') => void;
 }
 /** Represents custom CSS classes injected into layout parts. */
@@ -437,8 +586,28 @@ interface StyleClasses {
 }
 /** Custom hook to read configured style class contexts. */
 declare const useStyleClasses: () => StyleClasses;
+/**
+ * React hook to read the scoped {@link PanelRegistryClass} for the current provider.
+ * When the provider was created with a {@link WorkspaceClient}, this returns the client's
+ * private registry. Otherwise it returns the global `PanelRegistry` singleton.
+ *
+ * @group Hooks
+ * @returns The panel registry instance in scope.
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const registry = useRegistry();
+ *   const entry = registry.get('map');
+ *   return entry ? <entry.Component panelId="preview" /> : null;
+ * }
+ * ```
+ */
+declare const useRegistry: () => PanelRegistryClass;
 interface WindowManagerProviderProps {
     children: React__default.ReactNode;
+    /** WorkspaceClient instance created outside the React tree. When provided, its registry
+     *  and config take precedence over the individual props below. */
+    client?: WorkspaceClient;
     formatMessage?: MessageFormatter;
     predefinedMessages?: Record<string, ContextMenuPredefinedMessage>;
     dir?: 'ltr' | 'rtl';
@@ -451,13 +620,40 @@ interface WindowManagerProviderProps {
 }
 declare const WindowManagerProvider: React__default.FC<WindowManagerProviderProps>;
 /**
- * React hook to retrieve the active Window Manager layout state.
+ * React hook to subscribe to the live {@link WindowState} inside a component.
+ * The component re-renders whenever the state changes.
+ *
+ * For imperative reads without a subscription, use {@link WorkspaceClient} methods
+ * like `isOpen()` and `getOpenPanelIds()` instead.
+ *
+ * @group Hooks
+ * @returns The current workspace state tree.
  * @throws Error if used outside of a {@link WindowManagerProvider}.
+ * @example
+ * ```tsx
+ * function PanelList() {
+ *   const { panels } = useWindowManagerState();
+ *   return <ul>{Object.keys(panels).map(id => <li key={id}>{id}</li>)}</ul>;
+ * }
+ * ```
  */
 declare const useWindowManagerState: () => WindowState;
 /**
- * React hook to retrieve layouts mutation actions (dock, float, minimize, save/load).
+ * React hook to retrieve all layout mutation actions.
+ * Returns the public {@link WindowActions} interface.
+ *
+ * @group Hooks
+ * @returns The full set of workspace mutation methods.
  * @throws Error if used outside of a {@link WindowManagerProvider}.
+ * @example
+ * ```tsx
+ * function Toolbar() {
+ *   const actions = useWindowManagerActions();
+ *   return (
+ *     <button onClick={() => actions.openPanel('map-1', 'map')}>Open Map</button>
+ *   );
+ * }
+ * ```
  */
 declare const useWindowManagerActions: () => WindowActions;
 /**
@@ -480,6 +676,113 @@ declare const usePanelContext: () => {
  */
 declare const usePredefinedMessages: () => Record<"floatWindow" | "minimizePanel" | "closeTab" | "restorePanel" | "maximizePanel" | "closePanel" | "dockWindow" | "minimize" | "maximize" | "restoreSize" | "close" | "closeEmptyGroup" | "anchorToRightEdge" | "anchorToBottomEdge" | "windowAnchoringOptions" | "unsavedChangesTitle" | "unsavedChangesMessage" | "discardChanges" | "cancel" | "yes" | "no" | "ok" | "closePanelTooltip" | "closeTooltip", ContextMenuPredefinedMessage>;
 
+/** Per-panel definition supplied to WorkspaceClient constructor. */
+interface PanelDefinition {
+    component: ComponentType<any>;
+    defaultOptions?: PanelRegistryEntry['defaultOptions'];
+}
+/** Configuration object accepted by the WorkspaceClient constructor. */
+interface WorkspaceClientConfig {
+    /**
+     * Declarative panel catalog. Replaces imperative PanelRegistry.register() calls.
+     * Keys are the component identifiers used in openPanel() and serialised layouts.
+     */
+    panels?: Record<string, PanelDefinition>;
+    /**
+     * Serialised layout produced by a previous saveLayout() call.
+     * Pass null or omit to start with an empty canvas.
+     */
+    initialState?: string | null;
+    /** Custom i18n formatter for all internal strings. */
+    formatMessage?: MessageFormatter;
+    /** Override any subset of the built-in predefined message catalog. */
+    predefinedMessages?: Record<string, ContextMenuPredefinedMessage>;
+    /** Initial layout direction. */
+    dir?: 'ltr' | 'rtl';
+}
+/**
+ * WorkspaceClient is the central configuration and imperative API object for
+ * react-dockable-desktop. Create one instance outside the React tree and pass
+ * it to `<WindowManagerProvider client={client}>`.
+ *
+ * Pattern: TanStack QueryClient / Redux store — configuration and imperative
+ * access live on the client; rendering is delegated to the thin React provider.
+ *
+ * @remarks
+ * Calls made before the provider mounts are queued and replayed automatically
+ * in order once `_connect()` fires. If the client is never connected to a
+ * provider (e.g. `client={workspace}` was forgotten), a console warning is
+ * emitted in development after 1 second.
+ *
+ * `subscribe()` and `saveLayout()` return values immediately and cannot be
+ * queued — they return safe defaults (`() => {}` and `''`) when disconnected.
+ *
+ * @example
+ * const workspace = new WorkspaceClient({
+ *   panels: {
+ *     map:    { component: MapPanel },
+ *     editor: { component: EditorPanel, defaultOptions: { title: 'Code Editor' } },
+ *   },
+ *   initialState: localStorage.getItem('layout'),
+ * });
+ *
+ * <WindowManagerProvider client={workspace}>
+ *   <WindowManager />
+ * </WindowManagerProvider>
+ *
+ * // Imperative access from anywhere:
+ * workspace.saveLayout();
+ * workspace.openPanel('map-1', 'map');
+ * workspace.focusPanel('map-1');
+ */
+declare class WorkspaceClient {
+    /** Scoped panel registry — fully independent from the global singleton. */
+    readonly registry: PanelRegistryClass;
+    /** Serialised layout to restore on mount, or null to start with an empty canvas. */
+    readonly initialState: string | null;
+    /** Non-rendering configuration forwarded to the provider. */
+    readonly config: Pick<WorkspaceClientConfig, 'formatMessage' | 'predefinedMessages' | 'dir'>;
+    private _actions;
+    /** Calls queued before _connect() fires — replayed in order on first connect. */
+    private _pendingCalls;
+    /** DEV-only timer that warns if _connect() is never called within 1 second. */
+    private _disconnectedWarnTimer;
+    constructor(config?: WorkspaceClientConfig);
+    /** @internal Called by WindowManagerProvider after mount. */
+    _connect(actions: WindowActions): void;
+    /** @internal Called by WindowManagerProvider on unmount. */
+    _disconnect(): void;
+    /** True while the provider is mounted and React state is accessible. */
+    get isConnected(): boolean;
+    /**
+     * Dispatches a void action immediately if connected, or queues it for replay.
+     * In development, warns if the client is still not connected after 1 second.
+     */
+    private _dispatch;
+    openPanel(...args: Parameters<WindowActions['openPanel']>): void;
+    closePanel(id: string): void;
+    minimizePanel(id: string): void;
+    restorePanel(id: string): void;
+    floatPanel(...args: Parameters<WindowActions['floatPanel']>): void;
+    dockPanel(...args: Parameters<WindowActions['dockPanel']>): void;
+    maximizePanel(id: string): void;
+    /**
+     * Activates the given panel regardless of its current state.
+     * For floating panels: raises z-index so the window appears on top.
+     * For docked panels: selects the tab within its leaf group.
+     */
+    focusPanel(id: string): void;
+    /** Returns `true` if a panel with this ID is currently open. */
+    isOpen(id: string): boolean;
+    /** Returns the IDs of all currently open panels. */
+    getOpenPanelIds(): string[];
+    saveLayout(): string;
+    loadLayout(json: string): void;
+    setDirection(dir: 'ltr' | 'rtl'): void;
+    publish(event: string, data: unknown): void;
+    subscribe(event: string, callback: (data: unknown) => void): () => void;
+}
+
 /**
  * Options used when requesting to close a container.
  */
@@ -751,7 +1054,7 @@ interface SidebarProps {
     children?: React__default.ReactNode;
 }
 /**
- * Imperative handle exposed by <Sidebar ref={...}> via forwardRef.
+ * Imperative handle exposed by `<Sidebar ref={...}>` via forwardRef.
  * Allows external components (outside the sidebar tree) to control
  * which tab is open without prop drilling.
  */
@@ -769,4 +1072,4 @@ interface SidebarHandle {
  */
 declare const Sidebar: React__default.ForwardRefExoticComponent<SidebarProps & React__default.RefAttributes<SidebarHandle>>;
 
-export { type CloseOptions, ConfirmationForm, type ConfirmationFormProps, type ContextMenuPredefinedMessage, type FloatingWindow, FormContainerContext, type FormContainerContract, FormContainerProvider, type LayoutGridNode, type LayoutLeafNode, type LayoutNode, LeftPanelRenderer, type MessageFormatter, type ModalOptions, ModalStackRenderer, type PanelActions, type PanelInfo, type PanelInstance, type PanelInstanceId, PanelProvider, PanelRegistry, type PanelState, type PanelTitle, type PredefinedMessageKey, RightPanelRenderer, type SidePanelOptions, SidePanelRenderer, type SidePanelRendererProps, Sidebar, type SidebarHandle, type SidebarProps, type SidebarTab, type SplitOrientation, type StyleClasses, type WindowActions, WindowManager, WindowManagerProvider, type WindowState, defaultPredefinedMessages, formatLabel, useFormContainer, useFormatMessage, usePanelActions, usePanelContext, usePanelState, usePredefinedMessages, useStyleClasses, useWindowManagerActions, useWindowManagerState };
+export { type CloseOptions, ConfirmationForm, type ConfirmationFormProps, type ContextMenuPredefinedMessage, type FloatingWindow, FormContainerContext, type FormContainerContract, FormContainerProvider, type LayoutGridNode, type LayoutLeafNode, type LayoutNode, LeftPanelRenderer, type MessageFormatter, type ModalOptions, ModalStackRenderer, type PanelActions, type PanelDefinition, type PanelInfo, type PanelInstance, type PanelInstanceId, PanelProvider, PanelRegistry, PanelRegistryClass, type PanelRegistryEntry, type PanelState, type PanelTitle, type PredefinedMessageKey, RightPanelRenderer, type SidePanelOptions, SidePanelRenderer, type SidePanelRendererProps, Sidebar, type SidebarHandle, type SidebarProps, type SidebarTab, type SplitOrientation, type StyleClasses, type WindowActions, WindowManager, WindowManagerProvider, type WindowState, WorkspaceClient, type WorkspaceClientConfig, defaultPredefinedMessages, formatLabel, useFormContainer, useFormatMessage, usePanelActions, usePanelContext, usePanelState, usePredefinedMessages, useRegistry, useStyleClasses, useWindowManagerActions, useWindowManagerState };