react-dockable-desktop 4.3.0 → 5.0.0

package/dist/index.d.cts

@@ -90,6 +90,8 @@ interface WindowManagerProps {
     taskbarVisibility?: TaskbarVisibility;
     /** Custom context menu renderer. Defaults to the built-in `DefaultContextMenuAdapter`. */
     contextMenuAdapter?: ContextMenuAdapter;
+    /** Enables the library's own transitions/animations (tab hover, dock preview, etc.). Never affects the consumer's own page. @default true */
+    animations?: boolean;
 }
 declare const WindowManager: React$1.FC<WindowManagerProps>;
 
@@ -142,6 +144,13 @@ interface WorkspaceClientConfig {
      * outer edge. Range 0.1–0.9. Default: 0.2.
      */
     defaultEdgeSplitRatio?: number;
+    /**
+     * Starting z-index for floating windows and the library's own chrome overlays
+     * (context menu, toolbar flyout, modal stack, toast, workspace edge zones),
+     * all of which shift together via `--rdd-z-base`. Set this above/below a host
+     * app's own modal z-index range to control stacking against it. Default: 1000.
+     */
+    zIndexBase?: number;
 }
 /**
  * WorkspaceClient is the central configuration and imperative API object for
@@ -181,7 +190,7 @@ declare class WorkspaceClient<TUserEvents extends Record<string, unknown> = Reco
     /** 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' | 'defaultSplitRatio' | 'defaultEdgeSplitRatio'>;
+    readonly config: Pick<WorkspaceClientConfig, 'formatMessage' | 'predefinedMessages' | 'dir' | 'defaultSplitRatio' | 'defaultEdgeSplitRatio' | 'zIndexBase'>;
     private _actions;
     private _initialized;
     /** Calls queued before _connect() fires — replayed in order on first connect. */
@@ -222,6 +231,42 @@ declare class WorkspaceClient<TUserEvents extends Record<string, unknown> = Reco
     saveLayout(): string;
     loadLayout(json: string): boolean;
     setDirection(dir: 'ltr' | 'rtl'): void;
+    /** Updates the split-size fractions at the given grid path. */
+    updateSplitSizes(path: number[], sizes: number[]): void;
+    /** Updates position/size/anchor of a floating panel. */
+    updateFloatingPosition(id: string, updates: Partial<Pick<FloatingWindow, 'x' | 'y' | 'width' | 'height' | 'anchor'>>): void;
+    /** @internal Drives the drag-in-progress visual state; normally only the library's own drag UI calls this. */
+    setDraggedPanelId(id: string | null): void;
+    /** Docks a panel into an existing leaf group at the given drop position. */
+    dockPanelToGroup(id: string, targetLeafId: string, position: DropPosition): void;
+    /** Reorders a panel's tab within its leaf group. */
+    movePanelOrder(panelId: string, targetLeafId: string, targetIndex: number): void;
+    /** Closes an entire leaf group (all of its tabs) at once. */
+    closeLeafGroup(leafId: string): void;
+    /** Registers a guard that can veto closing the given panel. */
+    registerCloseGuard(id: string, guard: () => boolean | Promise<boolean>): void;
+    /** Removes a previously registered close guard. */
+    unregisterCloseGuard(id: string): void;
+    /** Sets/clears a panel's dirty (unsaved changes) flag. */
+    setPanelDirty(id: string, dirty: boolean, options?: DirtyStateOptions): void;
+    /** Updates a panel's displayed title. */
+    updatePanelTitle(id: string, title: string | ContextMenuPredefinedMessage): void;
+    /**
+     * Requests that a panel close, honoring its dirty flag and any registered close guard.
+     * Resolves once the close (or user cancellation) has been resolved.
+     *
+     * @remarks If called before the provider mounts, the request is queued and this
+     * returns an already-resolved promise immediately — the caller can't observe the
+     * eventual outcome of a queued call, only that the request was accepted.
+     */
+    requestClosePanel(id: string, options?: {
+        force?: boolean;
+        onConfirm?: (opts?: DirtyStateOptions) => Promise<boolean>;
+    }): Promise<void>;
+    /** Docks a panel to one of the workspace's outer edges. */
+    dockPanelToWorkspaceEdge(id: string, position: SplitDirection): void;
+    /** Shows a context menu using the app's configured ContextMenuAdapter. */
+    showContextMenu(options: ShowContextMenuOptions): 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. */
@@ -782,6 +827,19 @@ declare const useStyleClasses: () => StyleClasses;
  * ```
  */
 declare const useRegistry: () => PanelRegistryClass;
+/** The on-disk shape produced by `saveLayout()` and accepted by `loadLayout()`/`initialState`. */
+interface SerializedLayout {
+    /** Schema version — absent on layouts saved before this field was introduced (treated as 0). */
+    version?: number;
+    gridRoot: LayoutNode;
+    floating: FloatingWindow[];
+    minimized: {
+        id: string;
+        title: string | ContextMenuPredefinedMessage;
+        component: string;
+    }[];
+    panels: Record<string, PanelInfo>;
+}
 /**
  * Props for `<DockableDesktopProvider>` and `<WindowManagerProvider>`.
  * Also exported as `DockableDesktopProviderProps` for consumers who use
@@ -814,6 +872,13 @@ interface WindowManagerProviderProps {
     windowClass?: string;
     /** CSS class applied to the inner content area of floating panel windows. */
     windowBodyClass?: string;
+    /**
+     * Starting z-index for floating windows and the library's own chrome overlays
+     * (context menu, toolbar flyout, modal stack, toast, workspace edge zones),
+     * all of which shift together via `--rdd-z-base`. Set this above/below a host
+     * app's own modal z-index range to control stacking against it. @default 1000
+     */
+    zIndexBase?: number;
 }
 declare const WindowManagerProvider: React$1.FC<WindowManagerProviderProps>;
 declare function useWindowManagerState(): WindowState;
@@ -1073,6 +1138,17 @@ declare const FormContainerProvider: Provider<FormContainerContract>;
  * (resize, close, minimize, restore, activate, deactivate, container-type changes).
  */
 declare const useFormContainer: () => FormContainerContract;
+/**
+ * Reactive alternative to calling {@link FormContainerContract.getDimensions} yourself.
+ * Returns the panel's current `{ width, height }`, or `null` before it has been laid
+ * out, and re-renders whenever the panel's rendered box changes — including resizes
+ * caused by the workspace itself (a grid split being dragged, docking, floating, or
+ * tab activation), not just resizes of an element the panel created.
+ */
+declare const usePanelSize: () => {
+    width: number;
+    height: number;
+} | null;
 
 /** Unique string identifier for panel/modal instances. */
 type PanelInstanceId = string;
@@ -1280,7 +1356,7 @@ interface SidebarProps {
     /** Which side the activity bar and drawer appear on. Default: 'right' */
     position?: 'left' | 'right';
     tabs: SidebarTab[];
-    /** Initial drawer width in pixels. Default: 220 */
+    /** Initial drawer width in pixels. Default: 280 */
     defaultWidth?: number;
     /** Minimum drawer width in pixels during drag-resize. Default: 150 */
     minWidth?: number;
@@ -1302,8 +1378,6 @@ interface SidebarProps {
     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={...}>`.
@@ -1344,14 +1418,14 @@ declare const Sidebar: React$1.ForwardRefExoticComponent<SidebarProps & React$1.
  * 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.
+ * @throws Error if used outside of a {@link 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.
+ * @throws Error if used outside of a {@link Sidebar} tab's `renderContent` tree.
  */
 declare function useSidebarTab(): SidebarTabContextValue;
 
@@ -1380,7 +1454,7 @@ declare const ToolbarProvider: React$1.FC<{
  * 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.
+ * @throws Error if used outside of a {@link DockableDesktopProvider}.
  */
 declare function useToolbar(): ToolbarContextValue;
 
@@ -1417,8 +1491,8 @@ interface ToolbarRadioItem {
 /**
  * An independent on/off toggle modifier (e.g. snap-to-grid).
  *
- * Supports both uncontrolled mode (omit `active` — state lives in
- * ToolbarContext, keyed by `id`) and controlled mode (provide `active` —
+ * Supports both uncontrolled mode (omit `rdd-active` — state lives in
+ * ToolbarContext, keyed by `id`) and controlled mode (provide `rdd-active` —
  * the caller is the single source of truth and must update the prop in
  * response to `onToggle`). Controlled mode is what lets independent
  * instances of the same panel type report independent active state
@@ -1929,8 +2003,9 @@ declare const PanelContributionProvider: React$1.FC<{
  * `useMemo`/`useCallback`) to avoid republishing on every unrelated re-render.
  *
  * Contributions are only ever surfaced while this panel is `state.activePanelId` —
- * see `useActivePanelContribution()`. No-op outside a `PanelContributionProvider` tree.
+ * see `useActivePanelContribution()`.
  *
+ * @throws Error if used outside of a {@link PanelContributionProvider}.
  * @example
  * function MapPanel() {
  *   const [controller, setController] = useState<'pan' | 'draw' | 'measure'>('pan');
@@ -1950,6 +2025,8 @@ declare function usePanelContribution(contribution: PanelContribution): void;
  * via `usePanelContribution()`, or `null` if no panel is active or the active panel
  * hasn't contributed anything. Intended for the app shell to merge into its own
  * `<Toolbar items={...}>` / `<Sidebar tabs={...}>` calls.
+ *
+ * @throws Error if used outside of a {@link PanelContributionProvider}.
  */
 declare function useActivePanelContribution(): PanelContribution | null;
 /**
@@ -1975,4 +2052,83 @@ declare function useMergedToolbarItems(staticItems: ToolbarItem$1[]): ToolbarIte
  */
 declare function useMergedSidebarTabs(staticTabs: SidebarTab[], fallbackIcon?: React$1.ReactNode): SidebarTab[];
 
-export { type BuiltInPanelEvents, type ButtonVariant, type CloseOptions, ConfirmationForm, type ConfirmationFormProps, ContextMenu, type ContextMenuAdapter, type ContextMenuCheckbox, type ContextMenuHandle, type ContextMenuItem, type ContextMenuLabel, type ContextMenuPredefinedMessage, type ContextMenuProps, ContextMenuProvider, type ContextMenuSeparator, type ContextMenuSimpleItem, type ContextMenuSubMenu, DefaultContextMenuAdapter, DockableDesktopProvider, type DockableDesktopProviderProps, type DropPosition, type DropTarget, type FloatAnchor, type FloatingWindow, FormContainerContext, type FormContainerContract, FormContainerProvider, type LayoutGridNode, type LayoutLeafNode, type LayoutNode, LeftPanelRenderer, type ManagedWindowConfig, type MenuItemAction, type MessageFormatter, type ModalOptions, ModalStackRenderer, type PanelActions, type PanelContribution, PanelContributionProvider, type PanelDefinition, PanelFloatingWindow, type PanelFloatingWindowManagerHandle, type PanelFloatingWindowProps, type PanelInfo, type PanelInstance, type PanelInstanceId, PanelOverlayRoot, type PanelOverlayRootProps, PanelProvider, PanelRegistry, PanelRegistryClass, type PanelRegistryEntry, type PanelSidebarSection, type PanelState, type PanelTitle, PanelToolbar, ToolbarItem as PanelToolbarItem, type PanelToolbarProps, ToolbarSeparator as PanelToolbarSeparator, type PredefinedMessageKey, type ResolvedToastOptions, RightPanelRenderer, type SearchResult, type ShowContextMenuOptions, type SidePanelOptions, SidePanelRenderer, type SidePanelRendererProps, Sidebar, type SidebarContextValue, type SidebarHandle, type SidebarProps, type SidebarTab, type SidebarTabContextValue, type SplitDirection, type SplitOrientation, type StyleClasses, type TaskbarVisibility, type ToastAdapter, ToastContainer, type ToastContainerProps, type ToastFunction, type ToastOptions, type ToastPosition, type ToastPromiseMessages, type ToastType, Toolbar, type ToolbarActionItem, ToolbarButton, type ToolbarButtonProps, ToolbarCenter, type ToolbarContextValue, type ToolbarGroupEntry, type ToolbarGroupItem, type ToolbarGroupSubItem, type ToolbarHandle, type ToolbarItem$1 as ToolbarItem, type ToolbarPosition, type ToolbarProps, ToolbarProvider, type ToolbarRadioItem, ToolbarSearchInput, type ToolbarSearchInputProps, type ToolbarSeparator$1 as ToolbarSeparator, ToolbarSpacer, ToolbarToggle, type ToolbarToggleItem, type ToolbarToggleProps, type ToolbarVariant, type UsePanelFloatingWindowReturn, type WindowActions, WindowManager, type WindowManagerProps, WindowManagerProvider, type WindowManagerProviderProps, type WindowState, WorkspaceClient, type WorkspaceClientConfig, defaultPredefinedMessages, formatLabel, sidebarSectionToTab, toast, useActivePanelContribution, useFormContainer, useFormatMessage, useMergedSidebarTabs, useMergedToolbarItems, usePanelActions, usePanelContext, usePanelContextMenu, usePanelContribution, usePanelFloatingWindow, usePanelFloatingWindowManager, usePanelId, usePanelState, usePredefinedMessages, useRegistry, useShowContextMenu, useSidebar, useSidebarTab, useStyleClasses, useToolbar, useWindowManagerActions, useWindowManagerState };
+/**
+ * Shared pointer-drag-resize primitives.
+ *
+ * Extracted from four previously-independent implementations (the workspace grid
+ * split resizer, the sidebar drawer resizer, and two floating-window resize-handle
+ * implementations) that had quietly drifted apart in exactly the kind of detail
+ * (an inline-style property present in one and missing in the other) that once
+ * caused a real, user-visible bug. This file is the single place that mechanic now
+ * lives, so it can't drift again.
+ */
+interface PointerDragConfig<TStart> {
+    /** The element to capture the pointer on — normally the handle the user grabbed. */
+    element: HTMLElement;
+    pointerId: number;
+    /** The pointerdown event's clientX/clientY, used as the delta origin. */
+    startClientX: number;
+    startClientY: number;
+    /** Snapshot whatever state the caller needs at drag start (sizes, positions, ...). */
+    captureStart: () => TStart;
+    /** Called on every pointermove with the delta from the drag's start position. */
+    onMove: (dx: number, dy: number, start: TStart) => void;
+    /** Called once when the drag ends (pointerup or pointercancel). */
+    onEnd?: (start: TStart) => void;
+    /** Classes toggled on the given elements for the duration of the drag. */
+    activeClasses?: Array<{
+        el: HTMLElement;
+        classes: string[];
+    }>;
+}
+/**
+ * Starts a pointer-capture-based drag: captures the pointer on `element`, tracks
+ * movement via listeners scoped to that element's own lifetime (not `window`), and
+ * cleans up automatically on release or cancel.
+ */
+declare function startPointerDrag<TStart>(config: PointerDragConfig<TStart>): void;
+type ResizeDir = 'n' | 'ne' | 'e' | 'se' | 's' | 'sw' | 'w' | 'nw';
+interface ResizeRect {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+interface ResizeConstraints {
+    minW: number;
+    minH: number;
+    /** Upper bound on width — only applies to eastward growth (dir includes 'e'). */
+    maxW?: number;
+    /** Upper bound on height — only applies to southward growth (dir includes 's'). */
+    maxH?: number;
+    /** Lower bound on the resulting x — only applies to westward growth (dir includes 'w'). */
+    minX?: number;
+    /** Lower bound on the resulting y — only applies to northward growth (dir includes 'n'). */
+    minY?: number;
+}
+/**
+ * Pure function computing the new rect for an 8-directional resize handle drag.
+ *
+ * `maxW`/`maxH` and `minX`/`minY` are independent, direction-scoped constraints
+ * rather than one "container bound" — a resize toward the fixed edge (e/s) is
+ * naturally bounded by a maximum dimension, while a resize toward the moving edge
+ * (w/n) is naturally bounded by a minimum position, and the two calling sites this
+ * was extracted from need different subsets of these (see WindowManager.tsx's
+ * `startResize`, which omits all four and lets a window grow unbounded and be
+ * dragged fully off-screen, vs. PanelOverlay.tsx's `handleResizePointerDown`, which
+ * supplies all four to keep windows within their container).
+ */
+declare function computeResizedRect(dir: ResizeDir, dx: number, dy: number, start: ResizeRect, constraints: ResizeConstraints): ResizeRect;
+
+/**
+ * Reactively reads the workspace's current `data-color-scheme` attribute
+ * (set on `document.documentElement` by `<WindowManager />`), returning
+ * `'dark'` or `'light'` and re-rendering whenever it changes.
+ *
+ * Useful for panel content that needs to react to the same scheme the
+ * workspace itself is using — e.g. swapping a map's tile layer or an
+ * embedded editor's theme to match.
+ */
+declare function useColorScheme(): 'dark' | 'light';
+
+export { type BuiltInPanelEvents, type ButtonVariant, type CloseOptions, ConfirmationForm, type ConfirmationFormProps, ContextMenu, type ContextMenuAdapter, type ContextMenuCheckbox, type ContextMenuHandle, type ContextMenuItem, type ContextMenuLabel, type ContextMenuPredefinedMessage, type ContextMenuProps, ContextMenuProvider, type ContextMenuSeparator, type ContextMenuSimpleItem, type ContextMenuSubMenu, DefaultContextMenuAdapter, DockableDesktopProvider, type DockableDesktopProviderProps, type DropPosition, type DropTarget, type FloatAnchor, type FloatingWindow, FormContainerContext, type FormContainerContract, FormContainerProvider, type LayoutGridNode, type LayoutLeafNode, type LayoutNode, LeftPanelRenderer, type ManagedWindowConfig, type MenuItemAction, type MessageFormatter, type ModalOptions, ModalStackRenderer, type PanelActions, type PanelContribution, PanelContributionProvider, type PanelDefinition, PanelFloatingWindow, type PanelFloatingWindowManagerHandle, type PanelFloatingWindowProps, type PanelInfo, type PanelInstance, type PanelInstanceId, PanelOverlayRoot, type PanelOverlayRootProps, PanelProvider, PanelRegistry, PanelRegistryClass, type PanelRegistryEntry, type PanelSidebarSection, type PanelState, type PanelTitle, PanelToolbar, ToolbarItem as PanelToolbarItem, type PanelToolbarProps, ToolbarSeparator as PanelToolbarSeparator, type PointerDragConfig, type PredefinedMessageKey, type ResizeConstraints, type ResizeDir, type ResizeRect, type ResolvedToastOptions, RightPanelRenderer, type SearchResult, type SerializedLayout, type ShowContextMenuOptions, type SidePanelOptions, SidePanelRenderer, type SidePanelRendererProps, Sidebar, type SidebarContextValue, type SidebarHandle, type SidebarProps, type SidebarTab, type SidebarTabContextValue, type SplitDirection, type SplitOrientation, type StyleClasses, type TaskbarVisibility, type ToastAdapter, ToastContainer, type ToastContainerProps, type ToastFunction, type ToastOptions, type ToastPosition, type ToastPromiseMessages, type ToastType, Toolbar, type ToolbarActionItem, ToolbarButton, type ToolbarButtonProps, ToolbarCenter, type ToolbarContextValue, type ToolbarGroupEntry, type ToolbarGroupItem, type ToolbarGroupSubItem, type ToolbarHandle, type ToolbarItem$1 as ToolbarItem, type ToolbarPosition, type ToolbarProps, ToolbarProvider, type ToolbarRadioItem, ToolbarSearchInput, type ToolbarSearchInputProps, type ToolbarSeparator$1 as ToolbarSeparator, ToolbarSpacer, ToolbarToggle, type ToolbarToggleItem, type ToolbarToggleProps, type ToolbarVariant, type UsePanelFloatingWindowReturn, type WindowActions, WindowManager, type WindowManagerProps, WindowManagerProvider, type WindowManagerProviderProps, type WindowState, WorkspaceClient, type WorkspaceClientConfig, computeResizedRect, defaultPredefinedMessages, formatLabel, sidebarSectionToTab, startPointerDrag, toast, useActivePanelContribution, useColorScheme, useFormContainer, useFormatMessage, useMergedSidebarTabs, useMergedToolbarItems, usePanelActions, usePanelContext, usePanelContextMenu, usePanelContribution, usePanelFloatingWindow, usePanelFloatingWindowManager, usePanelId, usePanelSize, usePanelState, usePredefinedMessages, useRegistry, useShowContextMenu, useSidebar, useSidebarTab, useStyleClasses, useToolbar, useWindowManagerActions, useWindowManagerState };

package/dist/index.d.ts

@@ -90,6 +90,8 @@ interface WindowManagerProps {
     taskbarVisibility?: TaskbarVisibility;
     /** Custom context menu renderer. Defaults to the built-in `DefaultContextMenuAdapter`. */
     contextMenuAdapter?: ContextMenuAdapter;
+    /** Enables the library's own transitions/animations (tab hover, dock preview, etc.). Never affects the consumer's own page. @default true */
+    animations?: boolean;
 }
 declare const WindowManager: React$1.FC<WindowManagerProps>;
 
@@ -142,6 +144,13 @@ interface WorkspaceClientConfig {
      * outer edge. Range 0.1–0.9. Default: 0.2.
      */
     defaultEdgeSplitRatio?: number;
+    /**
+     * Starting z-index for floating windows and the library's own chrome overlays
+     * (context menu, toolbar flyout, modal stack, toast, workspace edge zones),
+     * all of which shift together via `--rdd-z-base`. Set this above/below a host
+     * app's own modal z-index range to control stacking against it. Default: 1000.
+     */
+    zIndexBase?: number;
 }
 /**
  * WorkspaceClient is the central configuration and imperative API object for
@@ -181,7 +190,7 @@ declare class WorkspaceClient<TUserEvents extends Record<string, unknown> = Reco
     /** 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' | 'defaultSplitRatio' | 'defaultEdgeSplitRatio'>;
+    readonly config: Pick<WorkspaceClientConfig, 'formatMessage' | 'predefinedMessages' | 'dir' | 'defaultSplitRatio' | 'defaultEdgeSplitRatio' | 'zIndexBase'>;
     private _actions;
     private _initialized;
     /** Calls queued before _connect() fires — replayed in order on first connect. */
@@ -222,6 +231,42 @@ declare class WorkspaceClient<TUserEvents extends Record<string, unknown> = Reco
     saveLayout(): string;
     loadLayout(json: string): boolean;
     setDirection(dir: 'ltr' | 'rtl'): void;
+    /** Updates the split-size fractions at the given grid path. */
+    updateSplitSizes(path: number[], sizes: number[]): void;
+    /** Updates position/size/anchor of a floating panel. */
+    updateFloatingPosition(id: string, updates: Partial<Pick<FloatingWindow, 'x' | 'y' | 'width' | 'height' | 'anchor'>>): void;
+    /** @internal Drives the drag-in-progress visual state; normally only the library's own drag UI calls this. */
+    setDraggedPanelId(id: string | null): void;
+    /** Docks a panel into an existing leaf group at the given drop position. */
+    dockPanelToGroup(id: string, targetLeafId: string, position: DropPosition): void;
+    /** Reorders a panel's tab within its leaf group. */
+    movePanelOrder(panelId: string, targetLeafId: string, targetIndex: number): void;
+    /** Closes an entire leaf group (all of its tabs) at once. */
+    closeLeafGroup(leafId: string): void;
+    /** Registers a guard that can veto closing the given panel. */
+    registerCloseGuard(id: string, guard: () => boolean | Promise<boolean>): void;
+    /** Removes a previously registered close guard. */
+    unregisterCloseGuard(id: string): void;
+    /** Sets/clears a panel's dirty (unsaved changes) flag. */
+    setPanelDirty(id: string, dirty: boolean, options?: DirtyStateOptions): void;
+    /** Updates a panel's displayed title. */
+    updatePanelTitle(id: string, title: string | ContextMenuPredefinedMessage): void;
+    /**
+     * Requests that a panel close, honoring its dirty flag and any registered close guard.
+     * Resolves once the close (or user cancellation) has been resolved.
+     *
+     * @remarks If called before the provider mounts, the request is queued and this
+     * returns an already-resolved promise immediately — the caller can't observe the
+     * eventual outcome of a queued call, only that the request was accepted.
+     */
+    requestClosePanel(id: string, options?: {
+        force?: boolean;
+        onConfirm?: (opts?: DirtyStateOptions) => Promise<boolean>;
+    }): Promise<void>;
+    /** Docks a panel to one of the workspace's outer edges. */
+    dockPanelToWorkspaceEdge(id: string, position: SplitDirection): void;
+    /** Shows a context menu using the app's configured ContextMenuAdapter. */
+    showContextMenu(options: ShowContextMenuOptions): 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. */
@@ -782,6 +827,19 @@ declare const useStyleClasses: () => StyleClasses;
  * ```
  */
 declare const useRegistry: () => PanelRegistryClass;
+/** The on-disk shape produced by `saveLayout()` and accepted by `loadLayout()`/`initialState`. */
+interface SerializedLayout {
+    /** Schema version — absent on layouts saved before this field was introduced (treated as 0). */
+    version?: number;
+    gridRoot: LayoutNode;
+    floating: FloatingWindow[];
+    minimized: {
+        id: string;
+        title: string | ContextMenuPredefinedMessage;
+        component: string;
+    }[];
+    panels: Record<string, PanelInfo>;
+}
 /**
  * Props for `<DockableDesktopProvider>` and `<WindowManagerProvider>`.
  * Also exported as `DockableDesktopProviderProps` for consumers who use
@@ -814,6 +872,13 @@ interface WindowManagerProviderProps {
     windowClass?: string;
     /** CSS class applied to the inner content area of floating panel windows. */
     windowBodyClass?: string;
+    /**
+     * Starting z-index for floating windows and the library's own chrome overlays
+     * (context menu, toolbar flyout, modal stack, toast, workspace edge zones),
+     * all of which shift together via `--rdd-z-base`. Set this above/below a host
+     * app's own modal z-index range to control stacking against it. @default 1000
+     */
+    zIndexBase?: number;
 }
 declare const WindowManagerProvider: React$1.FC<WindowManagerProviderProps>;
 declare function useWindowManagerState(): WindowState;
@@ -1073,6 +1138,17 @@ declare const FormContainerProvider: Provider<FormContainerContract>;
  * (resize, close, minimize, restore, activate, deactivate, container-type changes).
  */
 declare const useFormContainer: () => FormContainerContract;
+/**
+ * Reactive alternative to calling {@link FormContainerContract.getDimensions} yourself.
+ * Returns the panel's current `{ width, height }`, or `null` before it has been laid
+ * out, and re-renders whenever the panel's rendered box changes — including resizes
+ * caused by the workspace itself (a grid split being dragged, docking, floating, or
+ * tab activation), not just resizes of an element the panel created.
+ */
+declare const usePanelSize: () => {
+    width: number;
+    height: number;
+} | null;
 
 /** Unique string identifier for panel/modal instances. */
 type PanelInstanceId = string;
@@ -1280,7 +1356,7 @@ interface SidebarProps {
     /** Which side the activity bar and drawer appear on. Default: 'right' */
     position?: 'left' | 'right';
     tabs: SidebarTab[];
-    /** Initial drawer width in pixels. Default: 220 */
+    /** Initial drawer width in pixels. Default: 280 */
     defaultWidth?: number;
     /** Minimum drawer width in pixels during drag-resize. Default: 150 */
     minWidth?: number;
@@ -1302,8 +1378,6 @@ interface SidebarProps {
     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={...}>`.
@@ -1344,14 +1418,14 @@ declare const Sidebar: React$1.ForwardRefExoticComponent<SidebarProps & React$1.
  * 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.
+ * @throws Error if used outside of a {@link 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.
+ * @throws Error if used outside of a {@link Sidebar} tab's `renderContent` tree.
  */
 declare function useSidebarTab(): SidebarTabContextValue;
 
@@ -1380,7 +1454,7 @@ declare const ToolbarProvider: React$1.FC<{
  * 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.
+ * @throws Error if used outside of a {@link DockableDesktopProvider}.
  */
 declare function useToolbar(): ToolbarContextValue;
 
@@ -1417,8 +1491,8 @@ interface ToolbarRadioItem {
 /**
  * An independent on/off toggle modifier (e.g. snap-to-grid).
  *
- * Supports both uncontrolled mode (omit `active` — state lives in
- * ToolbarContext, keyed by `id`) and controlled mode (provide `active` —
+ * Supports both uncontrolled mode (omit `rdd-active` — state lives in
+ * ToolbarContext, keyed by `id`) and controlled mode (provide `rdd-active` —
  * the caller is the single source of truth and must update the prop in
  * response to `onToggle`). Controlled mode is what lets independent
  * instances of the same panel type report independent active state
@@ -1929,8 +2003,9 @@ declare const PanelContributionProvider: React$1.FC<{
  * `useMemo`/`useCallback`) to avoid republishing on every unrelated re-render.
  *
  * Contributions are only ever surfaced while this panel is `state.activePanelId` —
- * see `useActivePanelContribution()`. No-op outside a `PanelContributionProvider` tree.
+ * see `useActivePanelContribution()`.
  *
+ * @throws Error if used outside of a {@link PanelContributionProvider}.
  * @example
  * function MapPanel() {
  *   const [controller, setController] = useState<'pan' | 'draw' | 'measure'>('pan');
@@ -1950,6 +2025,8 @@ declare function usePanelContribution(contribution: PanelContribution): void;
  * via `usePanelContribution()`, or `null` if no panel is active or the active panel
  * hasn't contributed anything. Intended for the app shell to merge into its own
  * `<Toolbar items={...}>` / `<Sidebar tabs={...}>` calls.
+ *
+ * @throws Error if used outside of a {@link PanelContributionProvider}.
  */
 declare function useActivePanelContribution(): PanelContribution | null;
 /**
@@ -1975,4 +2052,83 @@ declare function useMergedToolbarItems(staticItems: ToolbarItem$1[]): ToolbarIte
  */
 declare function useMergedSidebarTabs(staticTabs: SidebarTab[], fallbackIcon?: React$1.ReactNode): SidebarTab[];
 
-export { type BuiltInPanelEvents, type ButtonVariant, type CloseOptions, ConfirmationForm, type ConfirmationFormProps, ContextMenu, type ContextMenuAdapter, type ContextMenuCheckbox, type ContextMenuHandle, type ContextMenuItem, type ContextMenuLabel, type ContextMenuPredefinedMessage, type ContextMenuProps, ContextMenuProvider, type ContextMenuSeparator, type ContextMenuSimpleItem, type ContextMenuSubMenu, DefaultContextMenuAdapter, DockableDesktopProvider, type DockableDesktopProviderProps, type DropPosition, type DropTarget, type FloatAnchor, type FloatingWindow, FormContainerContext, type FormContainerContract, FormContainerProvider, type LayoutGridNode, type LayoutLeafNode, type LayoutNode, LeftPanelRenderer, type ManagedWindowConfig, type MenuItemAction, type MessageFormatter, type ModalOptions, ModalStackRenderer, type PanelActions, type PanelContribution, PanelContributionProvider, type PanelDefinition, PanelFloatingWindow, type PanelFloatingWindowManagerHandle, type PanelFloatingWindowProps, type PanelInfo, type PanelInstance, type PanelInstanceId, PanelOverlayRoot, type PanelOverlayRootProps, PanelProvider, PanelRegistry, PanelRegistryClass, type PanelRegistryEntry, type PanelSidebarSection, type PanelState, type PanelTitle, PanelToolbar, ToolbarItem as PanelToolbarItem, type PanelToolbarProps, ToolbarSeparator as PanelToolbarSeparator, type PredefinedMessageKey, type ResolvedToastOptions, RightPanelRenderer, type SearchResult, type ShowContextMenuOptions, type SidePanelOptions, SidePanelRenderer, type SidePanelRendererProps, Sidebar, type SidebarContextValue, type SidebarHandle, type SidebarProps, type SidebarTab, type SidebarTabContextValue, type SplitDirection, type SplitOrientation, type StyleClasses, type TaskbarVisibility, type ToastAdapter, ToastContainer, type ToastContainerProps, type ToastFunction, type ToastOptions, type ToastPosition, type ToastPromiseMessages, type ToastType, Toolbar, type ToolbarActionItem, ToolbarButton, type ToolbarButtonProps, ToolbarCenter, type ToolbarContextValue, type ToolbarGroupEntry, type ToolbarGroupItem, type ToolbarGroupSubItem, type ToolbarHandle, type ToolbarItem$1 as ToolbarItem, type ToolbarPosition, type ToolbarProps, ToolbarProvider, type ToolbarRadioItem, ToolbarSearchInput, type ToolbarSearchInputProps, type ToolbarSeparator$1 as ToolbarSeparator, ToolbarSpacer, ToolbarToggle, type ToolbarToggleItem, type ToolbarToggleProps, type ToolbarVariant, type UsePanelFloatingWindowReturn, type WindowActions, WindowManager, type WindowManagerProps, WindowManagerProvider, type WindowManagerProviderProps, type WindowState, WorkspaceClient, type WorkspaceClientConfig, defaultPredefinedMessages, formatLabel, sidebarSectionToTab, toast, useActivePanelContribution, useFormContainer, useFormatMessage, useMergedSidebarTabs, useMergedToolbarItems, usePanelActions, usePanelContext, usePanelContextMenu, usePanelContribution, usePanelFloatingWindow, usePanelFloatingWindowManager, usePanelId, usePanelState, usePredefinedMessages, useRegistry, useShowContextMenu, useSidebar, useSidebarTab, useStyleClasses, useToolbar, useWindowManagerActions, useWindowManagerState };
+/**
+ * Shared pointer-drag-resize primitives.
+ *
+ * Extracted from four previously-independent implementations (the workspace grid
+ * split resizer, the sidebar drawer resizer, and two floating-window resize-handle
+ * implementations) that had quietly drifted apart in exactly the kind of detail
+ * (an inline-style property present in one and missing in the other) that once
+ * caused a real, user-visible bug. This file is the single place that mechanic now
+ * lives, so it can't drift again.
+ */
+interface PointerDragConfig<TStart> {
+    /** The element to capture the pointer on — normally the handle the user grabbed. */
+    element: HTMLElement;
+    pointerId: number;
+    /** The pointerdown event's clientX/clientY, used as the delta origin. */
+    startClientX: number;
+    startClientY: number;
+    /** Snapshot whatever state the caller needs at drag start (sizes, positions, ...). */
+    captureStart: () => TStart;
+    /** Called on every pointermove with the delta from the drag's start position. */
+    onMove: (dx: number, dy: number, start: TStart) => void;
+    /** Called once when the drag ends (pointerup or pointercancel). */
+    onEnd?: (start: TStart) => void;
+    /** Classes toggled on the given elements for the duration of the drag. */
+    activeClasses?: Array<{
+        el: HTMLElement;
+        classes: string[];
+    }>;
+}
+/**
+ * Starts a pointer-capture-based drag: captures the pointer on `element`, tracks
+ * movement via listeners scoped to that element's own lifetime (not `window`), and
+ * cleans up automatically on release or cancel.
+ */
+declare function startPointerDrag<TStart>(config: PointerDragConfig<TStart>): void;
+type ResizeDir = 'n' | 'ne' | 'e' | 'se' | 's' | 'sw' | 'w' | 'nw';
+interface ResizeRect {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+interface ResizeConstraints {
+    minW: number;
+    minH: number;
+    /** Upper bound on width — only applies to eastward growth (dir includes 'e'). */
+    maxW?: number;
+    /** Upper bound on height — only applies to southward growth (dir includes 's'). */
+    maxH?: number;
+    /** Lower bound on the resulting x — only applies to westward growth (dir includes 'w'). */
+    minX?: number;
+    /** Lower bound on the resulting y — only applies to northward growth (dir includes 'n'). */
+    minY?: number;
+}
+/**
+ * Pure function computing the new rect for an 8-directional resize handle drag.
+ *
+ * `maxW`/`maxH` and `minX`/`minY` are independent, direction-scoped constraints
+ * rather than one "container bound" — a resize toward the fixed edge (e/s) is
+ * naturally bounded by a maximum dimension, while a resize toward the moving edge
+ * (w/n) is naturally bounded by a minimum position, and the two calling sites this
+ * was extracted from need different subsets of these (see WindowManager.tsx's
+ * `startResize`, which omits all four and lets a window grow unbounded and be
+ * dragged fully off-screen, vs. PanelOverlay.tsx's `handleResizePointerDown`, which
+ * supplies all four to keep windows within their container).
+ */
+declare function computeResizedRect(dir: ResizeDir, dx: number, dy: number, start: ResizeRect, constraints: ResizeConstraints): ResizeRect;
+
+/**
+ * Reactively reads the workspace's current `data-color-scheme` attribute
+ * (set on `document.documentElement` by `<WindowManager />`), returning
+ * `'dark'` or `'light'` and re-rendering whenever it changes.
+ *
+ * Useful for panel content that needs to react to the same scheme the
+ * workspace itself is using — e.g. swapping a map's tile layer or an
+ * embedded editor's theme to match.
+ */
+declare function useColorScheme(): 'dark' | 'light';
+
+export { type BuiltInPanelEvents, type ButtonVariant, type CloseOptions, ConfirmationForm, type ConfirmationFormProps, ContextMenu, type ContextMenuAdapter, type ContextMenuCheckbox, type ContextMenuHandle, type ContextMenuItem, type ContextMenuLabel, type ContextMenuPredefinedMessage, type ContextMenuProps, ContextMenuProvider, type ContextMenuSeparator, type ContextMenuSimpleItem, type ContextMenuSubMenu, DefaultContextMenuAdapter, DockableDesktopProvider, type DockableDesktopProviderProps, type DropPosition, type DropTarget, type FloatAnchor, type FloatingWindow, FormContainerContext, type FormContainerContract, FormContainerProvider, type LayoutGridNode, type LayoutLeafNode, type LayoutNode, LeftPanelRenderer, type ManagedWindowConfig, type MenuItemAction, type MessageFormatter, type ModalOptions, ModalStackRenderer, type PanelActions, type PanelContribution, PanelContributionProvider, type PanelDefinition, PanelFloatingWindow, type PanelFloatingWindowManagerHandle, type PanelFloatingWindowProps, type PanelInfo, type PanelInstance, type PanelInstanceId, PanelOverlayRoot, type PanelOverlayRootProps, PanelProvider, PanelRegistry, PanelRegistryClass, type PanelRegistryEntry, type PanelSidebarSection, type PanelState, type PanelTitle, PanelToolbar, ToolbarItem as PanelToolbarItem, type PanelToolbarProps, ToolbarSeparator as PanelToolbarSeparator, type PointerDragConfig, type PredefinedMessageKey, type ResizeConstraints, type ResizeDir, type ResizeRect, type ResolvedToastOptions, RightPanelRenderer, type SearchResult, type SerializedLayout, type ShowContextMenuOptions, type SidePanelOptions, SidePanelRenderer, type SidePanelRendererProps, Sidebar, type SidebarContextValue, type SidebarHandle, type SidebarProps, type SidebarTab, type SidebarTabContextValue, type SplitDirection, type SplitOrientation, type StyleClasses, type TaskbarVisibility, type ToastAdapter, ToastContainer, type ToastContainerProps, type ToastFunction, type ToastOptions, type ToastPosition, type ToastPromiseMessages, type ToastType, Toolbar, type ToolbarActionItem, ToolbarButton, type ToolbarButtonProps, ToolbarCenter, type ToolbarContextValue, type ToolbarGroupEntry, type ToolbarGroupItem, type ToolbarGroupSubItem, type ToolbarHandle, type ToolbarItem$1 as ToolbarItem, type ToolbarPosition, type ToolbarProps, ToolbarProvider, type ToolbarRadioItem, ToolbarSearchInput, type ToolbarSearchInputProps, type ToolbarSeparator$1 as ToolbarSeparator, ToolbarSpacer, ToolbarToggle, type ToolbarToggleItem, type ToolbarToggleProps, type ToolbarVariant, type UsePanelFloatingWindowReturn, type WindowActions, WindowManager, type WindowManagerProps, WindowManagerProvider, type WindowManagerProviderProps, type WindowState, WorkspaceClient, type WorkspaceClientConfig, computeResizedRect, defaultPredefinedMessages, formatLabel, sidebarSectionToTab, startPointerDrag, toast, useActivePanelContribution, useColorScheme, useFormContainer, useFormatMessage, useMergedSidebarTabs, useMergedToolbarItems, usePanelActions, usePanelContext, usePanelContextMenu, usePanelContribution, usePanelFloatingWindow, usePanelFloatingWindowManager, usePanelId, usePanelSize, usePanelState, usePredefinedMessages, useRegistry, useShowContextMenu, useSidebar, useSidebarTab, useStyleClasses, useToolbar, useWindowManagerActions, useWindowManagerState };