react-dockable-desktop 2.0.0 → 3.0.0

package/dist/index.d.cts

@@ -1,5 +1,4 @@
-import * as React$1 from 'react';
-import React__default, { ComponentType, ReactNode } from 'react';
+import React$1, { ComponentType, Context, Provider, ReactNode } from 'react';
 
 /**
  * @file WindowManager.tsx
@@ -10,9 +9,9 @@ import React__default, { ComponentType, ReactNode } from 'react';
 
 interface WindowManagerProps {
     skin?: string;
-    defaultPanelIcon?: React__default.ReactNode;
+    defaultPanelIcon?: React$1.ReactNode;
 }
-declare const WindowManager: React__default.FC<WindowManagerProps>;
+declare const WindowManager: React$1.FC<WindowManagerProps>;
 
 /**
  * Represents a registered component configuration template inside the panel catalog registry.
@@ -249,6 +248,15 @@ interface ContextMenuPredefinedMessage {
 type MessageFormatter = (msg: ContextMenuPredefinedMessage) => string;
 /** Orientation modifier indicating split directions. */
 type SplitOrientation = 'horizontal' | 'vertical';
+/** The four cardinal directions a panel can be docked relative to another. */
+type SplitDirection = 'left' | 'right' | 'top' | 'bottom';
+/** All possible drop positions — cardinal directions plus center (same group). */
+type DropPosition = SplitDirection | 'center';
+/** The target leaf and position for a drag-and-drop dock operation. */
+interface DropTarget {
+    leafId: string;
+    position: DropPosition;
+}
 /**
  * Grid layout branch node containing nested splits and relative flex sizes.
  */
@@ -488,8 +496,9 @@ interface WindowActions {
      * 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}.
+     * @returns `true` if the layout was successfully parsed and applied, `false` otherwise.
      */
-    loadLayout: (layoutJson: string) => void;
+    loadLayout: (layoutJson: string) => boolean;
     /**
      * Publishes an event to the inter-panel pub/sub event bus.
      * @param event - Event name string.
@@ -515,7 +524,7 @@ interface WindowActions {
      * @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;
+    dockPanelToGroup: (id: string, targetLeafId: string, position: DropPosition) => void;
     /**
      * Reorders a panel's tab index within a docked leaf group.
      * @param panelId - Panel instance ID to move.
@@ -568,7 +577,7 @@ interface WindowActions {
      * @param id - Panel instance ID.
      * @param position - Edge to dock to.
      */
-    dockPanelToWorkspaceEdge: (id: string, position: 'left' | 'right' | 'top' | 'bottom') => void;
+    dockPanelToWorkspaceEdge: (id: string, position: SplitDirection) => void;
     /**
      * Overrides the workspace layout direction.
      * @param dir - `'ltr'` or `'rtl'`.
@@ -604,7 +613,7 @@ declare const useStyleClasses: () => StyleClasses;
  */
 declare const useRegistry: () => PanelRegistryClass;
 interface WindowManagerProviderProps {
-    children: React__default.ReactNode;
+    children: React$1.ReactNode;
     /** WorkspaceClient instance created outside the React tree. When provided, its registry
      *  and config take precedence over the individual props below. */
     client?: WorkspaceClient;
@@ -618,26 +627,9 @@ interface WindowManagerProviderProps {
     windowClass?: string;
     windowBodyClass?: string;
 }
-declare const WindowManagerProvider: React__default.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 const WindowManagerProvider: React$1.FC<WindowManagerProviderProps>;
+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.
@@ -667,15 +659,45 @@ declare const formatLabel: (label: string | ContextMenuPredefinedMessage | undef
 /**
  * React hook providing pub-sub helper methods for inter-panel event messaging.
  */
-declare const usePanelContext: () => {
-    publish: (event: string, data: any) => void;
-    subscribe: (event: string, callback: (data: any) => void) => () => void;
-};
+declare const usePanelContext: () => Pick<WindowActions, "publish" | "subscribe">;
 /**
  * React hook to fetch the localizable predefined message map catalog.
  */
-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>;
+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>;
@@ -710,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' } },
@@ -735,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. */
@@ -743,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. */
@@ -754,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;
@@ -777,12 +799,37 @@ declare class WorkspaceClient {
     /** Returns the IDs of all currently open panels. */
     getOpenPanelIds(): string[];
     saveLayout(): string;
-    loadLayout(json: string): void;
+    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.
  */
@@ -827,8 +874,8 @@ interface FormContainerContract {
 /**
  * Context that supplies the {@link FormContainerContract} to panels inside the Window Manager.
  */
-declare const FormContainerContext: React$1.Context<FormContainerContract>;
-declare const FormContainerProvider: React$1.Provider<FormContainerContract>;
+declare const FormContainerContext: Context<FormContainerContract>;
+declare const FormContainerProvider: Provider<FormContainerContract>;
 /**
  * React hook to retrieve the current {@link FormContainerContract} from context.
  * Enables sub-forms to trigger close requests, mark themselves dirty, rename their tabs, or listen to resize events.
@@ -855,7 +902,7 @@ interface SidePanelOptions {
     /** Display title for the side-panel header. */
     title?: PanelTitle;
     /** Icon displayed next to the panel title. */
-    icon?: React__default.ReactNode;
+    icon?: React$1.ReactNode;
     /** Specific CSS width (e.g. 300, '40%') for the panel container. */
     width?: number | string;
 }
@@ -864,7 +911,7 @@ interface ModalOptions {
     /** Display title for the modal header. */
     title?: PanelTitle;
     /** Icon displayed in the modal title bar. */
-    icon?: React__default.ReactNode;
+    icon?: React$1.ReactNode;
     /** Size modifier affecting CSS max-width rules. */
     size?: 'small' | 'medium' | 'large' | 'fullscreen' | 'auto';
     /** If false, hides the modal backdrop exit click and header close button. */
@@ -927,7 +974,7 @@ interface PanelActions {
  * PanelProvider component manages the state and action handlers
  * for drawers (left/right) and active stacked modal overlays.
  */
-declare const PanelProvider: React__default.FC<{
+declare const PanelProvider: React$1.FC<{
     children: ReactNode;
 }>;
 /**
@@ -945,7 +992,7 @@ declare const usePanelActions: () => PanelActions;
  * ModalStackRenderer component acts as the global container rendering
  * all active stacked modal windows in the workspace.
  */
-declare const ModalStackRenderer: React__default.FC;
+declare const ModalStackRenderer: React$1.FC;
 
 interface SidePanelRendererProps {
     /**
@@ -959,15 +1006,15 @@ interface SidePanelRendererProps {
  * SidePanelRenderer component acts as the global container rendering both
  * left and right side drawers if they are currently active.
  */
-declare const SidePanelRenderer: React__default.FC<SidePanelRendererProps>;
+declare const SidePanelRenderer: React$1.FC<SidePanelRendererProps>;
 /**
  * LeftPanelRenderer component renders ONLY the left side drawer if it is currently active.
  */
-declare const LeftPanelRenderer: React__default.FC<SidePanelRendererProps>;
+declare const LeftPanelRenderer: React$1.FC<SidePanelRendererProps>;
 /**
  * RightPanelRenderer component renders ONLY the right side drawer if it is currently active.
  */
-declare const RightPanelRenderer: React__default.FC<SidePanelRendererProps>;
+declare const RightPanelRenderer: React$1.FC<SidePanelRendererProps>;
 
 /**
  * Props for the {@link ConfirmationForm} component.
@@ -1000,7 +1047,7 @@ interface ConfirmationFormProps {
  * ConfirmationForm component renders a standard dialog content layout,
  * allowing users to confirm actions or abort them. Exposes action callbacks.
  */
-declare const ConfirmationForm: React__default.FC<ConfirmationFormProps>;
+declare const ConfirmationForm: React$1.FC<ConfirmationFormProps>;
 
 /**
  * @file Sidebar.tsx
@@ -1014,7 +1061,7 @@ declare const ConfirmationForm: React__default.FC<ConfirmationFormProps>;
 interface SidebarTab {
     id: string;
     label: string;
-    icon: React__default.ReactNode;
+    icon: React$1.ReactNode;
     /**
      * Mount immediately when the Sidebar first renders, not on first user click.
      * Implies `preserveState: true`.
@@ -1038,7 +1085,7 @@ interface SidebarTab {
      * @param onOpen  - call to expand the drawer and select this tab programmatically
      *                  (useful when the panel itself detects it has new data to show)
      */
-    renderContent: (tabId: string, onClose: () => void, onOpen: () => void) => React__default.ReactNode;
+    renderContent: (tabId: string, onClose: () => void, onOpen: () => void) => React$1.ReactNode;
 }
 interface SidebarProps {
     /** Which side the tab strip and drawer appear on. Default: 'right' */
@@ -1051,7 +1098,7 @@ interface SidebarProps {
     /** Called when the active tab changes in uncontrolled mode. */
     onActiveTabChange?: (tabId: string | null) => void;
     /** Main workspace content, rendered between the strip and drawer (or around them). */
-    children?: React__default.ReactNode;
+    children?: React$1.ReactNode;
 }
 /**
  * Imperative handle exposed by `<Sidebar ref={...}>` via forwardRef.
@@ -1070,6 +1117,6 @@ interface SidebarHandle {
  * Sidebar component rendering a tab strip and a collapsible content drawer.
  * Supports imperative method bindings like openTab and closeDrawer via forwardRef.
  */
-declare const Sidebar: React__default.ForwardRefExoticComponent<SidebarProps & React__default.RefAttributes<SidebarHandle>>;
+declare const Sidebar: React$1.ForwardRefExoticComponent<SidebarProps & React$1.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 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 };
+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 };