react-dockable-desktop 6.0.0 → 6.1.0

package/dist/index.d.cts

@@ -150,6 +150,10 @@ interface WorkspaceClientConfig {
     /**
      * Serialised layout produced by a previous saveLayout() call.
      * Pass null or omit to start with an empty canvas.
+     *
+     * Parsed synchronously before the first render. The restored `activePanelId` is the one the
+     * snapshot recorded, or — for layouts saved before that was persisted — the selected tab of
+     * the first leaf in the grid.
      */
     initialState?: string | null;
     /** Custom i18n formatter for all internal strings. */
@@ -641,7 +645,15 @@ interface WindowState {
     panels: Record<string, PanelInfo>;
     /** The ID of the panel tab currently being dragged. */
     draggedPanelId: string | null;
-    /** The ID of the active/focused panel. */
+    /**
+     * The ID of the active/focused panel — the one contributions are read from
+     * (see `useActivePanelContribution`) and the one drawn with focused chrome.
+     *
+     * Always a panel the user can actually see: the selected tab of its leaf, or a floating
+     * window. Never a minimized panel, except when an app explicitly calls `focusPanel()` on
+     * one. Restored layouts resolve it from the saved snapshot's own `activePanelId`, falling
+     * back to the first leaf's selected tab — never to an arbitrary entry in `panels`.
+     */
     activePanelId: string | null;
     /** Current layout direction ('ltr' or 'rtl') */
     dir: 'ltr' | 'rtl';
@@ -793,7 +805,8 @@ interface WindowActions {
     findPanelId: (component: string, dedupeKey: string) => string | null;
     /**
      * Serializes the entire workspace state to a JSON string.
-     * Includes grid layout, floating window positions, minimized panels, and panel metadata.
+     * Includes grid layout, floating window positions, minimized panels, panel metadata, and the
+     * globally active panel (see {@link SerializedLayout.activePanelId}).
      * @returns JSON string suitable for storage and later restoration via {@link loadLayout}.
      * @example
      * ```ts
@@ -804,6 +817,12 @@ interface WindowActions {
     /**
      * Restores a previously serialized workspace from a JSON string.
      * Replaces the entire current layout — all panels not in the snapshot are closed.
+     *
+     * `state.activePanelId` is resolved from the snapshot's own `activePanelId` when that panel is
+     * still visible in it, and otherwise from the first leaf's selected tab (which is also the path
+     * layouts saved before that field existed take). It is never seeded from an arbitrary entry in
+     * `panels`.
+     *
      * @param layoutJson - JSON string produced by {@link saveLayout}.
      * @returns `true` if the layout was successfully parsed and applied, `false` otherwise.
      */
@@ -948,6 +967,18 @@ declare const useRegistry: () => PanelRegistryClass;
 interface SerializedLayout {
     /** Schema version — absent on layouts saved before this field was introduced (treated as 0). */
     version?: number;
+    /**
+     * The globally active panel at save time — the one the user was actually looking at.
+     *
+     * Omitted when nothing was active, and when the active panel didn't survive this snapshot's
+     * serializability pruning (see {@link WindowActions.saveLayout}) — so it never names a panel
+     * absent from this payload's own `panels`. Absent on every layout saved before this field
+     * existed, in which case the restore derives it from `gridRoot`'s own per-leaf selection
+     * instead; a present-but-no-longer-valid value falls back to the same derivation. `version`
+     * is deliberately not bumped for this: the field is optional and its absence is a supported,
+     * fully-handled case rather than a schema a migration has to branch on.
+     */
+    activePanelId?: string | null;
     gridRoot: LayoutNode;
     floating: FloatingWindow[];
     minimized: {
@@ -2022,6 +2053,28 @@ declare function ToastContainer({ position, maxVisible, defaultDuration, default
 
 /** Edge of a panel to which a `PanelToolbar` attaches. */
 type ToolbarPosition = 'top' | 'bottom' | 'left' | 'right';
+/**
+ * Which of a docked widget's axes span the host panel instead of carrying a fixed size.
+ *
+ * A docked widget normally pins one end of each axis and carries an explicit size. A stretched
+ * axis pins **both** ends and carries no size at all, so the widget tracks the panel as it
+ * resizes — with no `ResizeObserver` and no JS, because CSS already does exactly this.
+ *
+ * - `'width'` — spans the panel's inline axis; height still fixed. A status or timeline strip.
+ * - `'height'` — spans the block axis; width still fixed. A full-height side column.
+ * - `'both'` — fills the panel, the inner-widget equivalent of maximizing a floating window.
+ */
+type Stretch = 'width' | 'height' | 'both';
+/**
+ * Where a docked widget sits: which corner it is anchored to, plus which axes (if any) span the
+ * panel. Reported as a unit because a single gesture can change both at once — dropping a
+ * full-width bottom strip onto the left edge flips the anchor *and* the stretched axis together,
+ * and reporting those separately would expose a state that is never actually valid.
+ */
+interface PanelFloatPlacement {
+    anchor: FloatAnchor;
+    stretch: Stretch | null;
+}
 /**
  * Configuration for a window spawned imperatively via `usePanelFloatingWindowManager().open()`.
  * @see usePanelFloatingWindowManager
@@ -2039,6 +2092,12 @@ interface ManagedWindowConfig {
     width?: number;
     /** Initial height in pixels. */
     height?: number;
+    /**
+     * Which axes span the panel instead of carrying a fixed size. `width`/`height` above still apply
+     * to any axis that isn't spanning, and are what a spanning axis returns to when released.
+     * @see Stretch
+     */
+    stretch?: Stretch;
 }
 /** Props for `<PanelOverlayRoot>`. */
 interface PanelOverlayRootProps {
@@ -2183,16 +2242,53 @@ interface PanelFloatingWindowProps {
     onClose(): void;
     /** Corner of the panel to dock to on first render. @see FloatAnchor */
     defaultAnchor: FloatAnchor;
-    /** Initial width in pixels. */
+    /** Initial width in pixels. Ignored on an axis that starts stretched, and restored to when that
+     *  axis is later released. */
     defaultWidth: number;
-    /** Initial height in pixels. */
+    /** Initial height in pixels. Ignored on an axis that starts stretched, and restored to when that
+     *  axis is later released. */
     defaultHeight: number;
+    /**
+     * Which axes span the panel on first render. Uncontrolled: gestures update it from here.
+     * @see Stretch
+     */
+    defaultStretch?: Stretch;
+    /**
+     * Controlled stretch state. When provided — **including as `null`** — the caller is the single
+     * source of truth: gestures report through {@link PanelFloatingWindowProps.onPlacementChange}
+     * instead of updating internally, and the caller must echo the new value back. Omit entirely
+     * (`undefined`) for uncontrolled behaviour, matching `ToolbarToggleItem.active` and
+     * `Sidebar.activeTabId`.
+     */
+    stretch?: Stretch | null;
+    /**
+     * Called whenever a gesture changes where the widget sits — a stretched axis released, a
+     * re-dock, or a detach. Reports anchor and stretch **together**, because one gesture can change
+     * both at once and reporting them separately would surface a state that is never valid.
+     *
+     * This is also the only way to persist placement: the library serialises nothing about inner
+     * widgets, so store what you receive here and feed it back via `defaultAnchor`/`stretch`.
+     */
+    onPlacementChange?: (placement: PanelFloatPlacement) => void;
+    /**
+     * Whether this widget may span the panel at all. `false` disables resize-to-stretch snapping,
+     * for content that only makes sense at a bounded size. Default `true`.
+     */
+    stretchable?: boolean;
     children?: React$1.ReactNode;
 }
 /**
  * Declarative floating window anchored inside a `PanelOverlayRoot`.
- * Supports 8-direction resize, drag-to-free, and drag-to-dock at any corner.
- * Multiple windows docked to the same corner stack vertically with animated offsets.
+ *
+ * Docks to any corner, drags free of it, and drops back onto one. Windows sharing a corner stack
+ * along the block axis with animated offsets. An axis can also **span the panel** instead of
+ * carrying a fixed size, so the window tracks the panel as it resizes — see
+ * {@link PanelFloatingWindowProps.defaultStretch} and {@link Stretch}.
+ *
+ * Resize handles follow what is actually movable: a free-floating window is pinned by nothing and
+ * offers all eight, while a docked one offers only its free edges — plus both ends of any spanning
+ * axis, either of which releases it.
+ *
  * @example
  * const info = usePanelFloatingWindow();
  * <PanelFloatingWindow
@@ -2202,6 +2298,18 @@ interface PanelFloatingWindowProps {
  * >
  *   <LayerInfoContent />
  * </PanelFloatingWindow>
+ *
+ * @example
+ * // A full-width status strip along the bottom, tracking the panel's width.
+ * // defaultHeight still applies; defaultWidth is what the inline axis returns to if released.
+ * <PanelFloatingWindow
+ *   id="timeline" title="Timeline"
+ *   open onClose={close}
+ *   defaultAnchor="bottom-left" defaultStretch="width"
+ *   defaultWidth={240} defaultHeight={120}
+ * >
+ *   <TimelineContent />
+ * </PanelFloatingWindow>
  */
 declare function PanelFloatingWindow(props: PanelFloatingWindowProps): React$1.ReactElement | null;
 /** Return type of `usePanelFloatingWindow`. @see usePanelFloatingWindow */
@@ -2240,13 +2348,18 @@ interface PanelFloatingWindowManagerHandle {
 }
 /**
  * Imperative hook for spawning N named floating windows at runtime from data or event handlers.
- * All windows share z-ordering, drag, and corner-docking infrastructure of the `PanelOverlayRoot`.
+ * All windows share z-ordering, drag, and corner-docking infrastructure of the `PanelOverlayRoot`,
+ * and accept the same placement options — including {@link ManagedWindowConfig.stretch} to span an
+ * axis of the panel.
  *
  * Must be called inside a **descendant** of `PanelOverlayRoot`, not in the component that renders the root.
  * @returns A stable `PanelFloatingWindowManagerHandle`.
  * @example
  * const manager = usePanelFloatingWindowManager();
  * manager.open('feature-42', { title: 'Feature 42', content: <FeatureDetail id={42} />, anchor: 'top-right' });
+ *
+ * // A full-width strip along the bottom edge:
+ * manager.open('timeline', { title: 'Timeline', content: <Timeline />, anchor: 'bottom-left', stretch: 'width', height: 120 });
  */
 declare function usePanelFloatingWindowManager(): PanelFloatingWindowManagerHandle;
 
@@ -2420,4 +2533,4 @@ declare function computeResizedRect(dir: ResizeDir, dx: number, dy: number, star
  */
 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 OpenPanelOptions, 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, SecondarySidebar, type SecondarySidebarProps, type SerializedLayout, type ShowContextMenuOptions, type SidePanelOptions, SidePanelRenderer, type SidePanelRendererProps, Sidebar, type SidebarContextValue, type SidebarHandle, type SidebarHeaderAction, type SidebarHeaderActionButton, type SidebarHeaderActionCustom, 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, isSerializable, 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 };
+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 OpenPanelOptions, type PanelActions, type PanelContribution, PanelContributionProvider, type PanelDefinition, type PanelFloatPlacement, 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, SecondarySidebar, type SecondarySidebarProps, type SerializedLayout, type ShowContextMenuOptions, type SidePanelOptions, SidePanelRenderer, type SidePanelRendererProps, Sidebar, type SidebarContextValue, type SidebarHandle, type SidebarHeaderAction, type SidebarHeaderActionButton, type SidebarHeaderActionCustom, type SidebarProps, type SidebarTab, type SidebarTabContextValue, type SplitDirection, type SplitOrientation, type Stretch, 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, isSerializable, 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

@@ -150,6 +150,10 @@ interface WorkspaceClientConfig {
     /**
      * Serialised layout produced by a previous saveLayout() call.
      * Pass null or omit to start with an empty canvas.
+     *
+     * Parsed synchronously before the first render. The restored `activePanelId` is the one the
+     * snapshot recorded, or — for layouts saved before that was persisted — the selected tab of
+     * the first leaf in the grid.
      */
     initialState?: string | null;
     /** Custom i18n formatter for all internal strings. */
@@ -641,7 +645,15 @@ interface WindowState {
     panels: Record<string, PanelInfo>;
     /** The ID of the panel tab currently being dragged. */
     draggedPanelId: string | null;
-    /** The ID of the active/focused panel. */
+    /**
+     * The ID of the active/focused panel — the one contributions are read from
+     * (see `useActivePanelContribution`) and the one drawn with focused chrome.
+     *
+     * Always a panel the user can actually see: the selected tab of its leaf, or a floating
+     * window. Never a minimized panel, except when an app explicitly calls `focusPanel()` on
+     * one. Restored layouts resolve it from the saved snapshot's own `activePanelId`, falling
+     * back to the first leaf's selected tab — never to an arbitrary entry in `panels`.
+     */
     activePanelId: string | null;
     /** Current layout direction ('ltr' or 'rtl') */
     dir: 'ltr' | 'rtl';
@@ -793,7 +805,8 @@ interface WindowActions {
     findPanelId: (component: string, dedupeKey: string) => string | null;
     /**
      * Serializes the entire workspace state to a JSON string.
-     * Includes grid layout, floating window positions, minimized panels, and panel metadata.
+     * Includes grid layout, floating window positions, minimized panels, panel metadata, and the
+     * globally active panel (see {@link SerializedLayout.activePanelId}).
      * @returns JSON string suitable for storage and later restoration via {@link loadLayout}.
      * @example
      * ```ts
@@ -804,6 +817,12 @@ interface WindowActions {
     /**
      * Restores a previously serialized workspace from a JSON string.
      * Replaces the entire current layout — all panels not in the snapshot are closed.
+     *
+     * `state.activePanelId` is resolved from the snapshot's own `activePanelId` when that panel is
+     * still visible in it, and otherwise from the first leaf's selected tab (which is also the path
+     * layouts saved before that field existed take). It is never seeded from an arbitrary entry in
+     * `panels`.
+     *
      * @param layoutJson - JSON string produced by {@link saveLayout}.
      * @returns `true` if the layout was successfully parsed and applied, `false` otherwise.
      */
@@ -948,6 +967,18 @@ declare const useRegistry: () => PanelRegistryClass;
 interface SerializedLayout {
     /** Schema version — absent on layouts saved before this field was introduced (treated as 0). */
     version?: number;
+    /**
+     * The globally active panel at save time — the one the user was actually looking at.
+     *
+     * Omitted when nothing was active, and when the active panel didn't survive this snapshot's
+     * serializability pruning (see {@link WindowActions.saveLayout}) — so it never names a panel
+     * absent from this payload's own `panels`. Absent on every layout saved before this field
+     * existed, in which case the restore derives it from `gridRoot`'s own per-leaf selection
+     * instead; a present-but-no-longer-valid value falls back to the same derivation. `version`
+     * is deliberately not bumped for this: the field is optional and its absence is a supported,
+     * fully-handled case rather than a schema a migration has to branch on.
+     */
+    activePanelId?: string | null;
     gridRoot: LayoutNode;
     floating: FloatingWindow[];
     minimized: {
@@ -2022,6 +2053,28 @@ declare function ToastContainer({ position, maxVisible, defaultDuration, default
 
 /** Edge of a panel to which a `PanelToolbar` attaches. */
 type ToolbarPosition = 'top' | 'bottom' | 'left' | 'right';
+/**
+ * Which of a docked widget's axes span the host panel instead of carrying a fixed size.
+ *
+ * A docked widget normally pins one end of each axis and carries an explicit size. A stretched
+ * axis pins **both** ends and carries no size at all, so the widget tracks the panel as it
+ * resizes — with no `ResizeObserver` and no JS, because CSS already does exactly this.
+ *
+ * - `'width'` — spans the panel's inline axis; height still fixed. A status or timeline strip.
+ * - `'height'` — spans the block axis; width still fixed. A full-height side column.
+ * - `'both'` — fills the panel, the inner-widget equivalent of maximizing a floating window.
+ */
+type Stretch = 'width' | 'height' | 'both';
+/**
+ * Where a docked widget sits: which corner it is anchored to, plus which axes (if any) span the
+ * panel. Reported as a unit because a single gesture can change both at once — dropping a
+ * full-width bottom strip onto the left edge flips the anchor *and* the stretched axis together,
+ * and reporting those separately would expose a state that is never actually valid.
+ */
+interface PanelFloatPlacement {
+    anchor: FloatAnchor;
+    stretch: Stretch | null;
+}
 /**
  * Configuration for a window spawned imperatively via `usePanelFloatingWindowManager().open()`.
  * @see usePanelFloatingWindowManager
@@ -2039,6 +2092,12 @@ interface ManagedWindowConfig {
     width?: number;
     /** Initial height in pixels. */
     height?: number;
+    /**
+     * Which axes span the panel instead of carrying a fixed size. `width`/`height` above still apply
+     * to any axis that isn't spanning, and are what a spanning axis returns to when released.
+     * @see Stretch
+     */
+    stretch?: Stretch;
 }
 /** Props for `<PanelOverlayRoot>`. */
 interface PanelOverlayRootProps {
@@ -2183,16 +2242,53 @@ interface PanelFloatingWindowProps {
     onClose(): void;
     /** Corner of the panel to dock to on first render. @see FloatAnchor */
     defaultAnchor: FloatAnchor;
-    /** Initial width in pixels. */
+    /** Initial width in pixels. Ignored on an axis that starts stretched, and restored to when that
+     *  axis is later released. */
     defaultWidth: number;
-    /** Initial height in pixels. */
+    /** Initial height in pixels. Ignored on an axis that starts stretched, and restored to when that
+     *  axis is later released. */
     defaultHeight: number;
+    /**
+     * Which axes span the panel on first render. Uncontrolled: gestures update it from here.
+     * @see Stretch
+     */
+    defaultStretch?: Stretch;
+    /**
+     * Controlled stretch state. When provided — **including as `null`** — the caller is the single
+     * source of truth: gestures report through {@link PanelFloatingWindowProps.onPlacementChange}
+     * instead of updating internally, and the caller must echo the new value back. Omit entirely
+     * (`undefined`) for uncontrolled behaviour, matching `ToolbarToggleItem.active` and
+     * `Sidebar.activeTabId`.
+     */
+    stretch?: Stretch | null;
+    /**
+     * Called whenever a gesture changes where the widget sits — a stretched axis released, a
+     * re-dock, or a detach. Reports anchor and stretch **together**, because one gesture can change
+     * both at once and reporting them separately would surface a state that is never valid.
+     *
+     * This is also the only way to persist placement: the library serialises nothing about inner
+     * widgets, so store what you receive here and feed it back via `defaultAnchor`/`stretch`.
+     */
+    onPlacementChange?: (placement: PanelFloatPlacement) => void;
+    /**
+     * Whether this widget may span the panel at all. `false` disables resize-to-stretch snapping,
+     * for content that only makes sense at a bounded size. Default `true`.
+     */
+    stretchable?: boolean;
     children?: React$1.ReactNode;
 }
 /**
  * Declarative floating window anchored inside a `PanelOverlayRoot`.
- * Supports 8-direction resize, drag-to-free, and drag-to-dock at any corner.
- * Multiple windows docked to the same corner stack vertically with animated offsets.
+ *
+ * Docks to any corner, drags free of it, and drops back onto one. Windows sharing a corner stack
+ * along the block axis with animated offsets. An axis can also **span the panel** instead of
+ * carrying a fixed size, so the window tracks the panel as it resizes — see
+ * {@link PanelFloatingWindowProps.defaultStretch} and {@link Stretch}.
+ *
+ * Resize handles follow what is actually movable: a free-floating window is pinned by nothing and
+ * offers all eight, while a docked one offers only its free edges — plus both ends of any spanning
+ * axis, either of which releases it.
+ *
  * @example
  * const info = usePanelFloatingWindow();
  * <PanelFloatingWindow
@@ -2202,6 +2298,18 @@ interface PanelFloatingWindowProps {
  * >
  *   <LayerInfoContent />
  * </PanelFloatingWindow>
+ *
+ * @example
+ * // A full-width status strip along the bottom, tracking the panel's width.
+ * // defaultHeight still applies; defaultWidth is what the inline axis returns to if released.
+ * <PanelFloatingWindow
+ *   id="timeline" title="Timeline"
+ *   open onClose={close}
+ *   defaultAnchor="bottom-left" defaultStretch="width"
+ *   defaultWidth={240} defaultHeight={120}
+ * >
+ *   <TimelineContent />
+ * </PanelFloatingWindow>
  */
 declare function PanelFloatingWindow(props: PanelFloatingWindowProps): React$1.ReactElement | null;
 /** Return type of `usePanelFloatingWindow`. @see usePanelFloatingWindow */
@@ -2240,13 +2348,18 @@ interface PanelFloatingWindowManagerHandle {
 }
 /**
  * Imperative hook for spawning N named floating windows at runtime from data or event handlers.
- * All windows share z-ordering, drag, and corner-docking infrastructure of the `PanelOverlayRoot`.
+ * All windows share z-ordering, drag, and corner-docking infrastructure of the `PanelOverlayRoot`,
+ * and accept the same placement options — including {@link ManagedWindowConfig.stretch} to span an
+ * axis of the panel.
  *
  * Must be called inside a **descendant** of `PanelOverlayRoot`, not in the component that renders the root.
  * @returns A stable `PanelFloatingWindowManagerHandle`.
  * @example
  * const manager = usePanelFloatingWindowManager();
  * manager.open('feature-42', { title: 'Feature 42', content: <FeatureDetail id={42} />, anchor: 'top-right' });
+ *
+ * // A full-width strip along the bottom edge:
+ * manager.open('timeline', { title: 'Timeline', content: <Timeline />, anchor: 'bottom-left', stretch: 'width', height: 120 });
  */
 declare function usePanelFloatingWindowManager(): PanelFloatingWindowManagerHandle;
 
@@ -2420,4 +2533,4 @@ declare function computeResizedRect(dir: ResizeDir, dx: number, dy: number, star
  */
 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 OpenPanelOptions, 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, SecondarySidebar, type SecondarySidebarProps, type SerializedLayout, type ShowContextMenuOptions, type SidePanelOptions, SidePanelRenderer, type SidePanelRendererProps, Sidebar, type SidebarContextValue, type SidebarHandle, type SidebarHeaderAction, type SidebarHeaderActionButton, type SidebarHeaderActionCustom, 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, isSerializable, 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 };
+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 OpenPanelOptions, type PanelActions, type PanelContribution, PanelContributionProvider, type PanelDefinition, type PanelFloatPlacement, 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, SecondarySidebar, type SecondarySidebarProps, type SerializedLayout, type ShowContextMenuOptions, type SidePanelOptions, SidePanelRenderer, type SidePanelRendererProps, Sidebar, type SidebarContextValue, type SidebarHandle, type SidebarHeaderAction, type SidebarHeaderActionButton, type SidebarHeaderActionCustom, type SidebarProps, type SidebarTab, type SidebarTabContextValue, type SplitDirection, type SplitOrientation, type Stretch, 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, isSerializable, 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 };