react-dockable-desktop 2.1.0 → 3.1.0

package/dist/index.d.ts

@@ -1,4 +1,6 @@
 import React$1, { ComponentType, Context, Provider, ReactNode } from 'react';
+import { ContextMenuItem } from 'replace-react-contexify';
+export { ContextMenuItem, ContextMenuSeparator, ContextMenuSimpleItem, ContextMenuSubMenu } from 'replace-react-contexify';
 
 /**
  * @file WindowManager.tsx
@@ -10,6 +12,7 @@ import React$1, { ComponentType, Context, Provider, ReactNode } from 'react';
 interface WindowManagerProps {
     skin?: string;
     defaultPanelIcon?: React$1.ReactNode;
+    taskbarVisibility?: 'always' | 'compact' | 'autohide';
 }
 declare const WindowManager: React$1.FC<WindowManagerProps>;
 
@@ -628,25 +631,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 +667,61 @@ 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;
+/**
+ * React hook for injecting custom context menu items into a panel's context menu from inside the panel component.
+ * Items are dynamic — the array is re-read each time the menu opens, so state-driven changes (enable/disable, add/remove) work automatically.
+ * The hook reads the panel ID internally via {@link usePanelId} — no prop needed.
+ *
+ * @param items - Array of `ContextMenuItem` entries (simple items, separators, submenus).
+ * @example
+ * ```tsx
+ * import { usePanelContextMenu } from 'dockable-windows';
+ *
+ * function MyPanel() {
+ *   const [dirty, setDirty] = useState(false);
+ *   usePanelContextMenu([
+ *     { label: 'Save', action: () => save() },
+ *     { label: 'Revert', action: () => revert() },
+ *   ]);
+ *   return <Editor onChange={() => setDirty(true)} />;
+ * }
+ * ```
+ */
+declare function usePanelContextMenu(items: ContextMenuItem[]): void;
 
+/** 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 +756,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 +778,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 +786,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 +802,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 +825,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.
  */
@@ -1010,8 +1075,10 @@ declare const ConfirmationForm: React$1.FC<ConfirmationFormProps>;
 
 /**
  * @file Sidebar.tsx
- * @description Sidebar navigation strip and drawer container component.
- * Supports eager/lazy mounting, state preservation (display: none), and positioning (left/right).
+ * @description Sidebar activity bar (strip) and resizable content drawer.
+ * The strip and drawer are independently controllable via `visible` and
+ * `stripVisible`. Drawer width is pixel-based and user-draggable using the
+ * same pointer-capture interaction as the panel grid resizer.
  */
 
 /**
@@ -1024,16 +1091,12 @@ interface SidebarTab {
     /**
      * Mount immediately when the Sidebar first renders, not on first user click.
      * Implies `preserveState: true`.
-     * Use when other parts of the app need to interact with the panel before
-     * the user has opened it (e.g. push data into a context, warm up a WebGL map).
      * Default: false
      */
     eagerMount?: boolean;
     /**
-     * Once mounted for the first time, keep the component alive in the DOM
-     * behind `display: none` when closed instead of unmounting it.
-     * Use for panels with expensive local state (long forms, WebGL scenes, etc.).
-     * Ignored when `eagerMount` is true (eagerly mounted panels are always preserved).
+     * Keep the component alive behind `display: none` when closed instead of
+     * unmounting it. Use for panels with expensive local state.
      * Default: false
      */
     preserveState?: boolean;
@@ -1041,41 +1104,234 @@ interface SidebarTab {
      * Called to obtain the drawer content for this tab.
      * @param tabId   - the id of this tab
      * @param onClose - call to collapse the sidebar drawer
-     * @param onOpen  - call to expand the drawer and select this tab programmatically
-     *                  (useful when the panel itself detects it has new data to show)
+     * @param onOpen  - call to expand the drawer and select this tab
      */
     renderContent: (tabId: string, onClose: () => void, onOpen: () => void) => React$1.ReactNode;
 }
 interface SidebarProps {
-    /** Which side the tab strip and drawer appear on. Default: 'right' */
+    /** Which side the activity bar and drawer appear on. Default: 'right' */
     position?: 'left' | 'right';
     tabs: SidebarTab[];
-    /** Width of the open drawer. Default: '220px' */
-    drawerWidth?: string;
-    /** Controlled active tab id. Leave undefined to use internal state. */
+    /** Initial drawer width in pixels. Default: 220 */
+    defaultWidth?: number;
+    /** Minimum drawer width in pixels during drag-resize. Default: 150 */
+    minWidth?: number;
+    /** Maximum drawer width in pixels during drag-resize. Default: 600 */
+    maxWidth?: number;
+    /** Called during drag resize and on setWidth() with the new pixel width. */
+    onWidthChange?: (px: number) => void;
+    /** Controlled active tab id. Omit to use internal state. */
     activeTabId?: string | null;
-    /** Called when the active tab changes in uncontrolled mode. */
+    /** Called when the active tab changes. */
     onActiveTabChange?: (tabId: string | null) => void;
-    /** Main workspace content, rendered between the strip and drawer (or around them). */
+    /** Collapse the entire sidebar (strip + drawer). Default: true */
+    visible?: boolean;
+    /** Called when show/hide/toggle is invoked on the imperative handle. */
+    onVisibilityChange?: (visible: boolean) => void;
+    /** Collapse only the activity bar strip, leaving the drawer unaffected. Default: true */
+    stripVisible?: boolean;
+    /** Called when showStrip/hideStrip is invoked on the imperative handle. */
+    onStripVisibilityChange?: (visible: boolean) => void;
+    /** Main workspace content rendered alongside the sidebar. */
     children?: React$1.ReactNode;
+    /** @deprecated Use defaultWidth (number, pixels) instead. */
+    drawerWidth?: string;
 }
 /**
- * Imperative handle exposed by `<Sidebar ref={...}>` via forwardRef.
- * Allows external components (outside the sidebar tree) to control
- * which tab is open without prop drilling.
+ * Imperative handle exposed by `<Sidebar ref={...}>`.
  */
 interface SidebarHandle {
-    /** Expand the drawer and activate the tab with the given id. */
     openTab: (tabId: string) => void;
-    /** Collapse the drawer (equivalent to clicking the active tab icon). */
     closeDrawer: () => void;
-    /** Returns the currently active tab id, or null if the drawer is collapsed. */
+    getActiveTab: () => string | null;
+    show: () => void;
+    hide: () => void;
+    toggle: () => void;
+    showStrip: () => void;
+    hideStrip: () => void;
+    setWidth: (px: number) => void;
+    getWidth: () => number;
+}
+/**
+ * Value provided by `useSidebar()`. Available to any component inside the
+ * `<Sidebar>` React tree, including panels rendered via `{children}`.
+ */
+interface SidebarContextValue {
+    openTab: (tabId: string) => void;
+    closeDrawer: () => void;
     getActiveTab: () => string | null;
 }
 /**
- * Sidebar component rendering a tab strip and a collapsible content drawer.
- * Supports imperative method bindings like openTab and closeDrawer via forwardRef.
+ * Value provided by `useSidebarTab()`. Available only to components rendered
+ * inside a sidebar tab's `renderContent` tree.
  */
+interface SidebarTabContextValue {
+    tabId: string;
+    onOpen: () => void;
+    onClose: () => void;
+    openTab: (tabId: string) => void;
+}
 declare const Sidebar: React$1.ForwardRefExoticComponent<SidebarProps & React$1.RefAttributes<SidebarHandle>>;
+/**
+ * Returns sidebar control functions from anywhere inside a `<Sidebar>` tree,
+ * including floating panels rendered via `{children}`.
+ *
+ * Returns a no-op object with a console warning when called outside a Sidebar.
+ */
+declare function useSidebar(): SidebarContextValue;
+/**
+ * Returns tab-specific control functions for components rendered inside a
+ * sidebar tab's `renderContent` tree.
+ *
+ * Returns a no-op object with a console warning when called outside tab content.
+ */
+declare function useSidebarTab(): SidebarTabContextValue;
+
+/**
+ * @file ToolbarContext.tsx
+ * @description Toolbar state context — radio group selection and toggle modifier state.
+ * Provided by DockableDesktopProvider; consumed via useToolbar() from anywhere in the tree.
+ */
+
+interface ToolbarContextValue {
+    /** Returns the active item id in a radio group, or null if none. */
+    getActiveInGroup: (group: string) => string | null;
+    /** Set the active item in a radio group (pass null to deselect all). */
+    setActiveInGroup: (group: string, id: string | null) => void;
+    /** Returns whether a toggle modifier is currently active. */
+    isModifierActive: (id: string) => boolean;
+    /** Explicitly set a toggle modifier's active state. */
+    setModifierActive: (id: string, active: boolean) => void;
+    /** Flip a toggle modifier between active and inactive. */
+    toggleModifier: (id: string) => void;
+}
+declare const ToolbarProvider: React$1.FC<{
+    children: React$1.ReactNode;
+}>;
+/**
+ * Returns toolbar state and control functions from anywhere inside
+ * a `<DockableDesktopProvider>` tree.
+ *
+ * Returns a no-op object with a console warning when called outside the provider.
+ */
+declare function useToolbar(): ToolbarContextValue;
+
+/**
+ * @file Toolbar.tsx
+ * @description Vertical or horizontal toolbar strip hosting action buttons,
+ * mutually-exclusive radio tool groups, independent toggle modifiers,
+ * and collapsible sub-tool group flyouts.
+ * State is library-wide via DockableDesktopProvider / ToolbarContext.
+ */
+
+/** A one-shot action button. */
+interface ToolbarActionItem {
+    type: 'action';
+    id: string;
+    label: string;
+    icon: React$1.ReactNode;
+    onClick: () => void;
+    disabled?: boolean;
+}
+/** A mutually-exclusive radio button within a named group. */
+interface ToolbarRadioItem {
+    type: 'radio';
+    id: string;
+    group: string;
+    label: string;
+    icon: React$1.ReactNode;
+    /** Keyboard shortcut hint — displayed in the group flyout; reserved for future custom tooltip. */
+    shortcut?: string;
+    /** Called when this item becomes active. */
+    onActivate?: (id: string) => void;
+    disabled?: boolean;
+}
+/** An independent on/off toggle modifier (e.g. snap-to-grid). */
+interface ToolbarToggleItem {
+    type: 'toggle';
+    id: string;
+    label: string;
+    icon: React$1.ReactNode;
+    /** Keyboard shortcut hint — reserved for future custom tooltip. */
+    shortcut?: string;
+    /** Called after the toggle flips; receives the new active state. */
+    onToggle?: (active: boolean) => void;
+    disabled?: boolean;
+}
+/** A visual divider between button groups. */
+interface ToolbarSeparator {
+    type: 'separator';
+}
+/**
+ * A single selectable sub-tool inside a group flyout.
+ * All sub-items in the same ToolbarGroupItem share one radio group
+ * keyed by the parent ToolbarGroupItem's `id`.
+ */
+interface ToolbarGroupSubItem {
+    id: string;
+    label: string;
+    icon: React$1.ReactNode;
+    /** Keyboard shortcut displayed in the flyout panel. */
+    shortcut?: string;
+    disabled?: boolean;
+    /** Called when this sub-item is selected. */
+    onActivate?: (id: string) => void;
+}
+/** An entry inside a group flyout — either a sub-item or a separator. */
+type ToolbarGroupEntry = ToolbarGroupSubItem | {
+    type: 'separator';
+};
+/**
+ * A collapsed tool-family button that opens a flyout panel listing all
+ * sub-tools. Only one sub-tool may be active at a time (radio semantics).
+ * The parent button's icon morphs to show the currently active sub-tool.
+ *
+ * Supports both uncontrolled mode (omit activeItemId — state lives in
+ * ToolbarContext) and controlled mode (provide activeItemId — the caller
+ * is the single source of truth and must update the prop in response to
+ * onActiveItemChange).
+ */
+interface ToolbarGroupItem {
+    type: 'group';
+    /** Serves as both the button ID and the radio group key in ToolbarContext. */
+    id: string;
+    /** Tooltip / aria-label shown when no sub-item is active. */
+    label: string;
+    /** Icon shown when no sub-item is active. */
+    defaultIcon: React$1.ReactNode;
+    items: ToolbarGroupEntry[];
+    disabled?: boolean;
+    /**
+     * Controlled active sub-item id. When provided (even as null), the
+     * component reads this prop instead of ToolbarContext and fires
+     * onActiveItemChange on click instead of updating context.
+     * Omit (undefined) for uncontrolled behaviour.
+     */
+    activeItemId?: string | null;
+    /**
+     * Called when the user selects a sub-item in controlled mode.
+     * The toolbar does not update itself — the caller must update activeItemId.
+     */
+    onActiveItemChange?: (id: string) => void;
+}
+type ToolbarItem = ToolbarActionItem | ToolbarRadioItem | ToolbarToggleItem | ToolbarGroupItem | ToolbarSeparator;
+interface ToolbarProps {
+    /** Side the strip is attached to. Controls strip orientation. Default: 'left' */
+    position?: 'left' | 'right' | 'top' | 'bottom';
+    /** Ordered list of items to render. */
+    items: ToolbarItem[];
+    /** Collapse the strip to zero width/height. State is preserved — no unmount. */
+    visible?: boolean;
+    /** Called when show/hide/toggle is invoked on the imperative handle. */
+    onVisibilityChange?: (visible: boolean) => void;
+    className?: string;
+    style?: React$1.CSSProperties;
+}
+interface ToolbarHandle {
+    show(): void;
+    hide(): void;
+    toggle(): void;
+}
+declare const Toolbar: React$1.ForwardRefExoticComponent<ToolbarProps & React$1.RefAttributes<ToolbarHandle>>;
 
-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 SidebarContextValue, type SidebarHandle, type SidebarProps, type SidebarTab, type SidebarTabContextValue, type SplitDirection, type SplitOrientation, type StyleClasses, Toolbar, type ToolbarActionItem, type ToolbarContextValue, type ToolbarGroupEntry, type ToolbarGroupItem, type ToolbarGroupSubItem, type ToolbarHandle, type ToolbarItem, type ToolbarProps, ToolbarProvider, type ToolbarRadioItem, type ToolbarSeparator, type ToolbarToggleItem, type WindowActions, WindowManager, WindowManagerProvider, type WindowState, WorkspaceClient, type WorkspaceClientConfig, defaultPredefinedMessages, formatLabel, useFormContainer, useFormatMessage, usePanelActions, usePanelContext, usePanelContextMenu, usePanelId, usePanelState, usePredefinedMessages, useRegistry, useSidebar, useSidebarTab, useStyleClasses, useToolbar, useWindowManagerActions, useWindowManagerState };