react-dockable-desktop 2.1.0 → 3.0.0

package/dist/index.d.cts

@@ -628,25 +628,8 @@ interface WindowManagerProviderProps {
     windowBodyClass?: string;
 }
 declare const WindowManagerProvider: React$1.FC<WindowManagerProviderProps>;
-/**
- * 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;
+declare function useWindowManagerState(): WindowState;
+declare function useWindowManagerState<T>(selector: (state: WindowState) => T): T;
 /**
  * React hook to retrieve all layout mutation actions.
  * Returns the public {@link WindowActions} interface.
@@ -681,7 +664,40 @@ declare const usePanelContext: () => Pick<WindowActions, "publish" | "subscribe"
  * React hook to fetch the localizable predefined message map catalog.
  */
 declare const usePredefinedMessages: () => Record<PredefinedMessageKey, ContextMenuPredefinedMessage>;
+/**
+ * React hook to retrieve the panel instance ID for the component currently rendered inside
+ * the dockable desktop. Works for docked, floating, modal, and side-panel containers.
+ * Opt-in — components that don't need the ID require no changes.
+ *
+ * @group Hooks
+ * @returns The unique panel instance ID string.
+ * @example
+ * ```tsx
+ * function MyPanel() {
+ *   const panelId = usePanelId();
+ *   const { closePanel } = useWindowManagerActions();
+ *   return <button onClick={() => closePanel(panelId)}>Close</button>;
+ * }
+ * ```
+ */
+declare const usePanelId: () => string;
 
+/** Built-in lifecycle events always available on the WorkspaceClient event bus. */
+interface BuiltInPanelEvents {
+    'panel:opened': {
+        id: string;
+        component: string;
+    };
+    'panel:closed': {
+        id: string;
+    };
+    'panel:minimized': {
+        id: string;
+    };
+    'panel:restored': {
+        id: string;
+    };
+}
 /** Per-panel definition supplied to WorkspaceClient constructor. */
 interface PanelDefinition {
     component: ComponentType<any>;
@@ -716,15 +732,12 @@ interface WorkspaceClientConfig {
  *
  * @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.
+ * in order once `_connect()` fires. Duplicate `openPanel` calls for the same
+ * ID are deduplicated while queued. Subscriptions made before mount are
+ * buffered and re-registered on each connect/reconnect.
  *
  * @example
- * const workspace = new WorkspaceClient({
+ * const workspace = new WorkspaceClient<MyEvents>({
  *   panels: {
  *     map:    { component: MapPanel },
  *     editor: { component: EditorPanel, defaultOptions: { title: 'Code Editor' } },
@@ -741,7 +754,7 @@ interface WorkspaceClientConfig {
  * workspace.openPanel('map-1', 'map');
  * workspace.focusPanel('map-1');
  */
-declare class WorkspaceClient {
+declare class WorkspaceClient<TUserEvents extends Record<string, unknown> = Record<string, unknown>> {
     /** 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. */
@@ -749,9 +762,14 @@ declare class WorkspaceClient {
     /** Non-rendering configuration forwarded to the provider. */
     readonly config: Pick<WorkspaceClientConfig, 'formatMessage' | 'predefinedMessages' | 'dir'>;
     private _actions;
+    private _initialized;
     /** 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. */
+    /** Tracks openPanel IDs in the pending queue to prevent duplicates before mount. */
+    private _pendingOpenPanelIds;
+    /** Subscriptions buffered before connect — re-registered on every connect/reconnect. */
+    private _pendingSubscriptions;
+    /** Timer that emits an error if _connect() is never called with pending work. */
     private _disconnectedWarnTimer;
     constructor(config?: WorkspaceClientConfig);
     /** @internal Called by WindowManagerProvider after mount. */
@@ -760,11 +778,9 @@ declare class WorkspaceClient {
     _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 _startWarnTimer;
     private _dispatch;
+    private _subscribeRaw;
     openPanel(...args: Parameters<WindowActions['openPanel']>): void;
     closePanel(id: string): void;
     minimizePanel(id: string): void;
@@ -785,10 +801,35 @@ declare class WorkspaceClient {
     saveLayout(): string;
     loadLayout(json: string): boolean;
     setDirection(dir: 'ltr' | 'rtl'): void;
-    publish(event: string, data: unknown): void;
-    subscribe(event: string, callback: (data: unknown) => void): () => void;
+    publish<K extends keyof (TUserEvents & BuiltInPanelEvents)>(event: K, data: (TUserEvents & BuiltInPanelEvents)[K]): void;
+    subscribe<K extends keyof (TUserEvents & BuiltInPanelEvents)>(event: K, callback: (data: (TUserEvents & BuiltInPanelEvents)[K]) => void): () => void;
+    /** Subscribe to panel open events. Fires only for newly created panels. */
+    onPanelOpen(callback: (id: string, component: string) => void): () => void;
+    /** Subscribe to panel close events. */
+    onPanelClose(callback: (id: string) => void): () => void;
+    /** Subscribe to panel minimize events. */
+    onPanelMinimize(callback: (id: string) => void): () => void;
+    /** Subscribe to panel restore events. */
+    onPanelRestore(callback: (id: string) => void): () => void;
 }
 
+/**
+ * Composite provider that wraps both `WindowManagerProvider` and `PanelProvider`
+ * in the correct order. Drop-in replacement for manually nesting both providers.
+ *
+ * `WindowManagerProvider` and `PanelProvider` remain independently exported
+ * for cases that require custom nesting or separate configuration.
+ *
+ * @example
+ * ```tsx
+ * <DockableDesktopProvider client={workspace}>
+ *   <WindowManager />
+ *   <ModalStackRenderer />
+ * </DockableDesktopProvider>
+ * ```
+ */
+declare const DockableDesktopProvider: React$1.FC<WindowManagerProviderProps>;
+
 /**
  * Options used when requesting to close a container.
  */
@@ -1078,4 +1119,4 @@ interface SidebarHandle {
  */
 declare const Sidebar: React$1.ForwardRefExoticComponent<SidebarProps & React$1.RefAttributes<SidebarHandle>>;
 
-export { type CloseOptions, ConfirmationForm, type ConfirmationFormProps, type ContextMenuPredefinedMessage, type DropPosition, type DropTarget, 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 SplitDirection, 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 };
+export { type BuiltInPanelEvents, type CloseOptions, ConfirmationForm, type ConfirmationFormProps, type ContextMenuPredefinedMessage, DockableDesktopProvider, type DropPosition, type DropTarget, 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 SplitDirection, type SplitOrientation, type StyleClasses, type WindowActions, WindowManager, WindowManagerProvider, type WindowState, WorkspaceClient, type WorkspaceClientConfig, defaultPredefinedMessages, formatLabel, useFormContainer, useFormatMessage, usePanelActions, usePanelContext, usePanelId, usePanelState, usePredefinedMessages, useRegistry, useStyleClasses, useWindowManagerActions, useWindowManagerState };

package/dist/index.d.ts

@@ -628,25 +628,8 @@ interface WindowManagerProviderProps {
     windowBodyClass?: string;
 }
 declare const WindowManagerProvider: React$1.FC<WindowManagerProviderProps>;
-/**
- * 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;
+declare function useWindowManagerState(): WindowState;
+declare function useWindowManagerState<T>(selector: (state: WindowState) => T): T;
 /**
  * React hook to retrieve all layout mutation actions.
  * Returns the public {@link WindowActions} interface.
@@ -681,7 +664,40 @@ declare const usePanelContext: () => Pick<WindowActions, "publish" | "subscribe"
  * React hook to fetch the localizable predefined message map catalog.
  */
 declare const usePredefinedMessages: () => Record<PredefinedMessageKey, ContextMenuPredefinedMessage>;
+/**
+ * React hook to retrieve the panel instance ID for the component currently rendered inside
+ * the dockable desktop. Works for docked, floating, modal, and side-panel containers.
+ * Opt-in — components that don't need the ID require no changes.
+ *
+ * @group Hooks
+ * @returns The unique panel instance ID string.
+ * @example
+ * ```tsx
+ * function MyPanel() {
+ *   const panelId = usePanelId();
+ *   const { closePanel } = useWindowManagerActions();
+ *   return <button onClick={() => closePanel(panelId)}>Close</button>;
+ * }
+ * ```
+ */
+declare const usePanelId: () => string;
 
+/** Built-in lifecycle events always available on the WorkspaceClient event bus. */
+interface BuiltInPanelEvents {
+    'panel:opened': {
+        id: string;
+        component: string;
+    };
+    'panel:closed': {
+        id: string;
+    };
+    'panel:minimized': {
+        id: string;
+    };
+    'panel:restored': {
+        id: string;
+    };
+}
 /** Per-panel definition supplied to WorkspaceClient constructor. */
 interface PanelDefinition {
     component: ComponentType<any>;
@@ -716,15 +732,12 @@ interface WorkspaceClientConfig {
  *
  * @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.
+ * in order once `_connect()` fires. Duplicate `openPanel` calls for the same
+ * ID are deduplicated while queued. Subscriptions made before mount are
+ * buffered and re-registered on each connect/reconnect.
  *
  * @example
- * const workspace = new WorkspaceClient({
+ * const workspace = new WorkspaceClient<MyEvents>({
  *   panels: {
  *     map:    { component: MapPanel },
  *     editor: { component: EditorPanel, defaultOptions: { title: 'Code Editor' } },
@@ -741,7 +754,7 @@ interface WorkspaceClientConfig {
  * workspace.openPanel('map-1', 'map');
  * workspace.focusPanel('map-1');
  */
-declare class WorkspaceClient {
+declare class WorkspaceClient<TUserEvents extends Record<string, unknown> = Record<string, unknown>> {
     /** 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. */
@@ -749,9 +762,14 @@ declare class WorkspaceClient {
     /** Non-rendering configuration forwarded to the provider. */
     readonly config: Pick<WorkspaceClientConfig, 'formatMessage' | 'predefinedMessages' | 'dir'>;
     private _actions;
+    private _initialized;
     /** 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. */
+    /** Tracks openPanel IDs in the pending queue to prevent duplicates before mount. */
+    private _pendingOpenPanelIds;
+    /** Subscriptions buffered before connect — re-registered on every connect/reconnect. */
+    private _pendingSubscriptions;
+    /** Timer that emits an error if _connect() is never called with pending work. */
     private _disconnectedWarnTimer;
     constructor(config?: WorkspaceClientConfig);
     /** @internal Called by WindowManagerProvider after mount. */
@@ -760,11 +778,9 @@ declare class WorkspaceClient {
     _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 _startWarnTimer;
     private _dispatch;
+    private _subscribeRaw;
     openPanel(...args: Parameters<WindowActions['openPanel']>): void;
     closePanel(id: string): void;
     minimizePanel(id: string): void;
@@ -785,10 +801,35 @@ declare class WorkspaceClient {
     saveLayout(): string;
     loadLayout(json: string): boolean;
     setDirection(dir: 'ltr' | 'rtl'): void;
-    publish(event: string, data: unknown): void;
-    subscribe(event: string, callback: (data: unknown) => void): () => void;
+    publish<K extends keyof (TUserEvents & BuiltInPanelEvents)>(event: K, data: (TUserEvents & BuiltInPanelEvents)[K]): void;
+    subscribe<K extends keyof (TUserEvents & BuiltInPanelEvents)>(event: K, callback: (data: (TUserEvents & BuiltInPanelEvents)[K]) => void): () => void;
+    /** Subscribe to panel open events. Fires only for newly created panels. */
+    onPanelOpen(callback: (id: string, component: string) => void): () => void;
+    /** Subscribe to panel close events. */
+    onPanelClose(callback: (id: string) => void): () => void;
+    /** Subscribe to panel minimize events. */
+    onPanelMinimize(callback: (id: string) => void): () => void;
+    /** Subscribe to panel restore events. */
+    onPanelRestore(callback: (id: string) => void): () => void;
 }
 
+/**
+ * Composite provider that wraps both `WindowManagerProvider` and `PanelProvider`
+ * in the correct order. Drop-in replacement for manually nesting both providers.
+ *
+ * `WindowManagerProvider` and `PanelProvider` remain independently exported
+ * for cases that require custom nesting or separate configuration.
+ *
+ * @example
+ * ```tsx
+ * <DockableDesktopProvider client={workspace}>
+ *   <WindowManager />
+ *   <ModalStackRenderer />
+ * </DockableDesktopProvider>
+ * ```
+ */
+declare const DockableDesktopProvider: React$1.FC<WindowManagerProviderProps>;
+
 /**
  * Options used when requesting to close a container.
  */
@@ -1078,4 +1119,4 @@ interface SidebarHandle {
  */
 declare const Sidebar: React$1.ForwardRefExoticComponent<SidebarProps & React$1.RefAttributes<SidebarHandle>>;
 
-export { type CloseOptions, ConfirmationForm, type ConfirmationFormProps, type ContextMenuPredefinedMessage, type DropPosition, type DropTarget, 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 SplitDirection, 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 };
+export { type BuiltInPanelEvents, type CloseOptions, ConfirmationForm, type ConfirmationFormProps, type ContextMenuPredefinedMessage, DockableDesktopProvider, type DropPosition, type DropTarget, 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 SplitDirection, type SplitOrientation, type StyleClasses, type WindowActions, WindowManager, WindowManagerProvider, type WindowState, WorkspaceClient, type WorkspaceClientConfig, defaultPredefinedMessages, formatLabel, useFormContainer, useFormatMessage, usePanelActions, usePanelContext, usePanelId, usePanelState, usePredefinedMessages, useRegistry, useStyleClasses, useWindowManagerActions, useWindowManagerState };