react-dockable-desktop 3.0.0 → 3.2.0

package/dist/index.d.cts

@@ -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>;
 
@@ -681,6 +684,27 @@ declare const usePredefinedMessages: () => Record<PredefinedMessageKey, ContextM
  * ```
  */
 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 {
@@ -1051,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.
  */
 
 /**
@@ -1065,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;
@@ -1082,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;
 }
 /**
- * Sidebar component rendering a tab strip and a collapsible content drawer.
- * Supports imperative method bindings like openTab and closeDrawer via forwardRef.
+ * 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;
+}
+/**
+ * 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 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 };
+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 };

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>;
 
@@ -681,6 +684,27 @@ declare const usePredefinedMessages: () => Record<PredefinedMessageKey, ContextM
  * ```
  */
 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 {
@@ -1051,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.
  */
 
 /**
@@ -1065,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;
@@ -1082,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;
 }
 /**
- * Sidebar component rendering a tab strip and a collapsible content drawer.
- * Supports imperative method bindings like openTab and closeDrawer via forwardRef.
+ * 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;
+}
+/**
+ * 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 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 };
+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 };