vue-dockable-desktop 1.0.0

package/dist/composables/usePanel.d.ts

@@ -0,0 +1,82 @@
+import type { ComputedRef, InjectionKey, Ref } from 'vue';
+import type { ContainerType, DirtyStateOptions, Label } from '../types';
+/** What a panel's container tells it about itself. @internal */
+export interface PanelContext {
+    id: string;
+    containerType: Ref<ContainerType>;
+    /** Set by a container that is not the workspace (a modal, a side panel). */
+    close?: (options?: {
+        force?: boolean;
+    }) => void | Promise<void>;
+    setTitle?: (title: Label) => void;
+    setIcon?: (icon: unknown) => void;
+    setDirty?: (dirty: boolean, options?: DirtyStateOptions) => void;
+    size?: Ref<{
+        width: number;
+        height: number;
+    } | null>;
+}
+export declare const PANEL_KEY: InjectionKey<PanelContext>;
+/** @internal — used by containers to tell their content which panel it is. */
+export declare function providePanel(context: PanelContext): void;
+/** What {@link usePanel} returns. */
+export interface UsePanelReturn {
+    /** This panel's instance id. */
+    id: string;
+    /** Live title. */
+    title: ComputedRef<Label>;
+    /** Whether this is the globally active panel — the one contributions are read from. */
+    isActive: ComputedRef<boolean>;
+    /** Whether this panel is minimised. It is still mounted and still running. */
+    isMinimized: ComputedRef<boolean>;
+    /** Whether this panel is a floating window. */
+    isFloating: ComputedRef<boolean>;
+    /** Where this panel is rendered. */
+    containerType: ComputedRef<ContainerType>;
+    /** The panel's rendered size, or `null` before it has been laid out. */
+    size: ComputedRef<{
+        width: number;
+        height: number;
+    } | null>;
+    /** Unsaved changes. */
+    dirty: ComputedRef<boolean>;
+    setTitle: (title: Label) => void;
+    setIcon: (icon: unknown) => void;
+    setDirty: (dirty: boolean, options?: DirtyStateOptions) => void;
+    /** Close, honouring dirty state and any `onBeforeClose` guard. */
+    close: (options?: {
+        force?: boolean;
+    }) => void | Promise<void>;
+    minimize: () => void;
+    /**
+     * Veto a close. Return `false` (or a promise of it) to block.
+     * Registered in `setup` and disposed with the component — nothing to unsubscribe.
+     */
+    onBeforeClose: (guard: () => boolean | Promise<boolean>) => void;
+    /**
+     * Contribute this panel's live state to `saveLayout()`, pulled fresh on every save — for
+     * state that accumulates after opening and so cannot be captured by open-time props.
+     * Must be synchronous and JSON-serialisable. Disposed with the component.
+     */
+    onSaveState: (provider: () => unknown) => void;
+}
+/**
+ * A panel's view of itself and its container.
+ *
+ * Everything that describes *state* is a ref, so you react with the tools you already use:
+ *
+ * ```ts
+ * const { isActive, size } = usePanel()
+ * watch(isActive, active => active && editor.focus())
+ * watch(size, ({ width, height }) => chart.resize(width, height))
+ * ```
+ *
+ * react-dockable-desktop exposed six subscription methods plus two size APIs for this,
+ * because React cannot hand a component live state. Those are all refs here
+ * (docs/decisions/0006-refs-over-subscriptions.md).
+ *
+ * Works outside any container too: the refs then report a `'standalone'` panel and the
+ * actions are no-ops with a development warning, so a panel component can be rendered on
+ * its own — in a test, or a storybook — without special-casing.
+ */
+export declare function usePanel(): UsePanelReturn;

package/dist/composables/usePanelDom.d.ts

@@ -0,0 +1,7 @@
+import type { InjectionKey } from 'vue';
+import type { PanelDomCache } from '../core/panelDom';
+export declare const PANEL_DOM_KEY: InjectionKey<PanelDomCache>;
+/** @internal — `<VddDesktop>` owns the cache and shares it with the slots inside it. */
+export declare function providePanelDom(cache: PanelDomCache): void;
+/** @internal */
+export declare function usePanelDom(): PanelDomCache | null;

package/dist/composables/usePanelOverlay.d.ts

@@ -0,0 +1,35 @@
+import type { ComputedRef } from 'vue';
+import type { ManagedWidget, PanelOverlayStore } from '../core/overlayState';
+/**
+ * The overlay a widget or toolbar is inside.
+ *
+ * @throws if used outside a `<VddPanelOverlay>`.
+ * @internal — applications use {@link useFloatingWidgets}.
+ */
+export declare function usePanelOverlay(): PanelOverlayStore;
+/** Same, but `null` outside an overlay — for components that work either way. */
+export declare function usePanelOverlayOptional(): PanelOverlayStore | null;
+/**
+ * Open and close floating widgets by id, without declaring each one in the template.
+ *
+ * For widgets whose existence is data — one per selected feature, one per running job — where
+ * writing a `<VddFloatingWidget>` per case is not possible.
+ *
+ * ```ts
+ * const widgets = useFloatingWidgets()
+ * widgets.open('feature-42', {
+ *   title: 'Feature 42', component: FeatureInfo, props: { id: 42 }, anchor: 'top-right',
+ * })
+ * ```
+ *
+ * A widget placed in the template with `<VddFloatingWidget>` is the simpler option and
+ * behaves identically otherwise.
+ */
+export declare function useFloatingWidgets(): {
+    /** Ids of the currently open managed widgets, in the order they were opened. */
+    openIds: ComputedRef<string[]>;
+    open: (id: string, widget: ManagedWidget) => void;
+    close: (id: string) => void;
+    closeAll: () => void;
+    isOpen: (id: string) => boolean;
+};

package/dist/composables/useSidebar.d.ts

@@ -0,0 +1,15 @@
+import type { SidebarContext, SidebarTabContext } from '../core/sidebarTypes';
+/**
+ * Control the sidebar from anywhere inside it — including from a panel rendered in the
+ * workspace, since the workspace is the sidebar's own content.
+ *
+ * @throws if used outside a `<VddSidebar>`.
+ */
+export declare function useSidebar(): SidebarContext;
+/**
+ * Control scoped to the tab you are inside: close the drawer, re-open this tab, or switch to
+ * another one, without having to know which tab you are.
+ *
+ * @throws if used outside a sidebar tab's content.
+ */
+export declare function useSidebarTab(): SidebarTabContext;

package/dist/composables/useToolbar.d.ts

@@ -0,0 +1,9 @@
+import type { ToolbarState } from '../core/toolbarState';
+/**
+ * Toolbar selection state — which item is active in each radio group, and which toggles are
+ * on — for items the caller has not taken control of.
+ *
+ * Reachable anywhere `useWorkspace()` is, so a panel can read or set the active tool without
+ * the toolbar having to pass anything down. rdd needed a `<ToolbarProvider>` in the tree.
+ */
+export declare function useToolbar(): ToolbarState;

package/dist/composables/useWorkspace.d.ts

@@ -0,0 +1,18 @@
+import type { Workspace } from '../core/workspace';
+/**
+ * The workspace, from anywhere inside an app that has `app.use(workspace)`.
+ *
+ * Returns refs and functions, so destructuring keeps reactivity — the shape `storeToRefs`
+ * exists to produce in Pinia:
+ *
+ * ```ts
+ * const { activePanelId, panels, openPanel } = useWorkspace()
+ * ```
+ *
+ * There is no selector argument. react-dockable-desktop needed one to control re-renders;
+ * in Vue a `computed()` is both more capable and the idiom you already know.
+ *
+ * `subscribe()` is wrapped so a subscription made during `setup` is disposed with the
+ * component. Outside a scope it behaves exactly like `workspace.subscribe`.
+ */
+export declare function useWorkspace<TEvents extends Record<string, unknown> = Record<string, unknown>>(): Workspace<TEvents>;

package/dist/core/anchorGeometry.d.ts

@@ -0,0 +1,39 @@
+import type { FloatAnchor } from '../types';
+/**
+ * Mirrors a physical workspace corner to its horizontal opposite.
+ *
+ * Used only to translate a physically-hovered corner (raw pointer/screen
+ * position, which CSS cannot reason about) into the logical `FloatAnchor`
+ * value stored on a `FloatingWindow` under RTL. Render-time positioning
+ * should use CSS logical properties (`insetInlineStart`/`insetInlineEnd`)
+ * driven by the element's `dir` attribute instead of calling this.
+ */
+export declare function flipZoneHorizontal(zone: FloatAnchor): FloatAnchor;
+/** A floating window's stored box, as numbers. */
+export interface FloatingRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/** Smallest a clamp will shrink a window to, so it never becomes ungrabbable. */
+export declare const MIN_CLAMP_W = 200;
+export declare const MIN_CLAMP_H = 150;
+/**
+ * Where a floating window has to move to stay reachable inside a shrinking workspace.
+ *
+ * Returns the clamped rect, or the **same object** when nothing needed to change. That
+ * identity is the point: the caller watches the window list deeply and writes back to it, so
+ * writing on "a bound was exceeded" rather than on "a value changed" re-triggers the watcher
+ * forever. Both clamps have a floor, so in a workspace narrower than that floor the clamped
+ * value still fails its own condition — and the rewrite loop that produced was found by
+ * M13's browser tour as "Maximum recursive updates exceeded".
+ *
+ * Size is clamped for every window. Position is clamped only for a free-floating one: an
+ * anchored window is placed entirely by its anchor and reading direction, so its stored x/y
+ * do not affect where it appears.
+ */
+export declare function clampFloatingRect(rect: FloatingRect, view: {
+    width: number;
+    height: number;
+}, anchored: boolean): FloatingRect;

package/dist/core/contextMenu.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Context-menu item shapes.
+ *
+ * Names and fields are kept identical to react-dockable-desktop's, so menu definitions port
+ * across unchanged — a menu is data, and this is the one part of the API where a React
+ * app's arrays can be reused verbatim.
+ */
+import type { Component } from 'vue';
+import type { Label } from '../types';
+/** The optional checkbox column on a simple item. */
+export interface ContextMenuCheckbox {
+    /** Whether the checkbox column renders at all. @default true */
+    active?: boolean;
+    /** Whether the item is interactive. Prefer the item's own `disabled`. @default true */
+    enabled?: boolean;
+    /** Current checked state. */
+    value: boolean;
+}
+/** A normal menu item. */
+export interface ContextMenuSimpleItem {
+    label: Label;
+    icon?: Component;
+    /** Tooltip. */
+    title?: Label;
+    checkbox?: ContextMenuCheckbox;
+    action?: () => void;
+    /** Test hook, rendered as `data-cy-action`. */
+    cyAction?: string;
+    disabled?: boolean;
+}
+/** A divider. */
+export interface ContextMenuSeparator {
+    separator: true;
+}
+/** An item that opens a submenu. One level deep, as in rdd. */
+export interface ContextMenuSubMenu {
+    label: Label;
+    title?: Label;
+    items?: ContextMenuItem[];
+}
+export type ContextMenuItem = ContextMenuSimpleItem | ContextMenuSeparator | ContextMenuSubMenu;
+/** What to show, and where. */
+export interface ShowContextMenuOptions {
+    /** Position from an event. Takes precedence over `x`/`y`. */
+    event?: MouseEvent | PointerEvent | TouchEvent;
+    x?: number;
+    y?: number;
+    items: ContextMenuItem[];
+}
+export declare const isSeparator: (item: ContextMenuItem) => item is ContextMenuSeparator;
+export declare const isSubMenu: (item: ContextMenuItem) => item is ContextMenuSubMenu;
+/** Where a menu should open, from whatever the caller supplied. */
+export declare function menuPosition(options: ShowContextMenuOptions): {
+    x: number;
+    y: number;
+};
+/**
+ * Keep a menu inside the viewport.
+ *
+ * Pure, so the clamping is testable without layout: the caller measures, this decides.
+ */
+export declare function clampToViewport(position: {
+    x: number;
+    y: number;
+}, size: {
+    width: number;
+    height: number;
+}, viewport: {
+    width: number;
+    height: number;
+}, padding?: number): {
+    x: number;
+    y: number;
+};

package/dist/core/contributions.d.ts

@@ -0,0 +1,56 @@
+import type { Component, ComputedRef } from 'vue';
+import type { SidebarTab } from './sidebarTypes';
+import type { ToolbarItem } from './toolbarTypes';
+/** One named section a panel contributes to the app's sidebar while it is active. */
+export interface PanelSidebarSection {
+    id: string;
+    label: string;
+    icon?: Component;
+    /** Rendered as the section's content. */
+    component: Component;
+    props?: Record<string, unknown>;
+}
+/**
+ * What a panel publishes. Both fields are optional and independent — a panel may contribute
+ * only toolbar items, only sections, both, or nothing.
+ *
+ * The library assigns no meaning to either: what "a toolbar item" is for is the application's
+ * decision, and neither `<VddToolbar>` nor `<VddSidebar>` reads this on its own. The shell
+ * merges it into its own `items`/`tabs`.
+ */
+export interface PanelContribution {
+    toolbarItems?: ToolbarItem[];
+    sidebarSections?: PanelSidebarSection[];
+}
+export interface Contributions {
+    /**
+     * Publish for one panel, replacing anything it published before. The returned function
+     * withdraws it — but only if nothing has re-published for that id since, so a republish
+     * during a component update cannot be undone by the previous registration's cleanup.
+     */
+    publish(panelId: string, contribution: PanelContribution): () => void;
+    /** What one panel has published, or `null`. */
+    get(panelId: string): PanelContribution | null;
+    /** Every panel that has published something. */
+    ids(): string[];
+}
+export declare function createContributions(): Contributions;
+/**
+ * Turn a contributed section into a sidebar tab.
+ *
+ * `eagerMount` and `preserveState` are deliberately left unset: a contribution exists only
+ * while its panel is mounted *and* active, so neither has anything to mean here.
+ */
+export declare function sectionToTab(section: PanelSidebarSection, fallbackIcon?: Component): SidebarTab;
+/**
+ * Append the active panel's contributed items to a static list, behind a separator.
+ *
+ * A plain function of a `computed`, not a hook — the state is on the workspace, so there is
+ * nothing to subscribe to. rdd needed `useMergedToolbarItems()` because reading the store
+ * required `useSyncExternalStore`.
+ */
+export declare function mergeToolbarItems(staticItems: ToolbarItem[], contribution: PanelContribution | null): ToolbarItem[];
+/** Append the active panel's contributed sections to a static tab list. */
+export declare function mergeSidebarTabs(staticTabs: SidebarTab[], contribution: PanelContribution | null, fallbackIcon?: Component): SidebarTab[];
+/** @internal — used by the workspace to expose the active contribution as a ref. */
+export declare function activeContributionRef(contributions: Contributions, activePanelId: () => string | null): ComputedRef<PanelContribution | null>;

package/dist/core/dragResize.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Pointer-drag and resize primitives.
+ *
+ * Framework-agnostic on purpose: there is no Vue in this file, so the grid split resizer,
+ * the sidebar drawer resizer and both floating-window resize implementations share one
+ * mechanic that cannot drift apart. In react-dockable-desktop these had already drifted
+ * four ways, differing in exactly the kind of detail (an inline style present in one and
+ * missing in another) that caused a real user-visible bug.
+ *
+ * Exported publicly so applications can build their own resizable UI inside a panel with
+ * the same behaviour as the library's own.
+ */
+export 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.
+ */
+export declare function startPointerDrag<TStart>(config: PointerDragConfig<TStart>): void;
+export type ResizeDir = 'n' | 'ne' | 'e' | 'se' | 's' | 'sw' | 'w' | 'nw';
+export interface ResizeRect {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+export 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 (a workspace floating window omits all four, so it may grow unbounded and be dragged
+ * off-screen; a docked inner widget supplies all four to stay within its panel).
+ */
+export declare function computeResizedRect(dir: ResizeDir, dx: number, dy: number, start: ResizeRect, constraints: ResizeConstraints): ResizeRect;

package/dist/core/eventBus.d.ts

@@ -0,0 +1,73 @@
+/**
+ * The inter-panel event bus.
+ *
+ * Panels are deliberately unaware of each other; this is how they communicate. It is a
+ * domain feature, not DOM events, so it stays a workspace method rather than becoming
+ * component `emits`.
+ *
+ * Framework-agnostic: subscriptions made from a component are disposed by the composable
+ * that wraps this, not by the bus itself.
+ */
+/** Events the library publishes itself. An application's own events are merged with these. */
+export interface BuiltInEvents {
+    'panel:opened': {
+        id: string;
+        component: string;
+    };
+    'panel:closed': {
+        id: string;
+    };
+    'panel:minimized': {
+        id: string;
+    };
+    'panel:restored': {
+        id: string;
+    };
+    /** The globally active panel changed. The ordered channel for handing off between panels —
+     *  a watcher on `usePanel().isActive` sees the same change but not the ordering. */
+    'panel:activated': {
+        id: string | null;
+        previous: string | null;
+    };
+    /**
+     * Anything `saveLayout()` would capture has changed: open, close, minimise, restore, a
+     * dedupe redirect, and every placement change (dock, float, reorder, edge-dock, split
+     * resize). Coalesced so an autosave needs one subscription.
+     *
+     * Does **not** fire when an `onSaveState` provider's own return value changes — that is a
+     * pull, and nothing can observe it changing. Save on your own trigger too if it matters.
+     */
+    'layout:changed': Record<string, never>;
+    /**
+     * Fired from inside `saveLayout()`, only when that call excluded at least one panel whose
+     * current props failed the serialisability check. A passive flag is not enough: nobody may
+     * be looking at the moment something silently drops out of a snapshot.
+     */
+    'layout:panels-excluded': {
+        panels: {
+            id: string;
+            component: string;
+        }[];
+    };
+}
+export declare class EventBus<TEvents extends Record<string, unknown> = Record<string, unknown>> {
+    private listeners;
+    subscribe<K extends keyof (TEvents & BuiltInEvents) & string>(event: K, callback: (data: (TEvents & BuiltInEvents)[K]) => void): () => void;
+    publish<K extends keyof (TEvents & BuiltInEvents) & string>(event: K, data: (TEvents & BuiltInEvents)[K]): void;
+    /**
+     * Publish one of the library's own events.
+     *
+     * Separate from `publish` because `TEvents & BuiltInEvents` is not provably satisfied by a
+     * built-in payload: an application could declare its own narrower type for a built-in key.
+     * This path is typed against `BuiltInEvents` alone, so the library's own call sites are
+     * checked properly instead of being cast.
+     *
+     * @internal
+     */
+    emit<K extends keyof BuiltInEvents & string>(event: K, data: BuiltInEvents[K]): void;
+    private dispatch;
+    /** Listener count for an event — for tests and diagnostics. */
+    count(event: string): number;
+    /** Drop every listener. Called by `workspace.dispose()`. */
+    clear(): void;
+}

package/dist/core/layoutTree.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Pure operations on the layout tree.
+ *
+ * Every function here takes a tree and returns a new one — no mutation, no reactivity, no
+ * Vue. In react-dockable-desktop these lived as closures inside the provider and could
+ * only be tested through the rendered component; extracting them means the tree maths is
+ * directly testable, which is where the subtle bugs are (see `deriveActivePanelId`).
+ */
+import type { FloatingWindow, LayoutLeafNode, LayoutNode, PanelInfo, SplitDirection } from '../types';
+/** An empty workspace: one leaf, no panels. */
+export declare const EMPTY_LEAF: LayoutLeafNode;
+/** A fresh empty root, for when removing the last panel collapses the tree to nothing. */
+export declare const emptyRoot: () => LayoutLeafNode;
+/**
+ * Remove a panel from the tree.
+ *
+ * Returns `null` when the node itself should disappear — an emptied leaf without
+ * `keepOnEmpty`, or a branch left with no children. A branch left with one child collapses
+ * to that child, and surviving `sizes` are re-normalised to sum to 1.
+ *
+ * When the removed panel was its leaf's selected tab, selection moves to the next tab, then
+ * the previous, then the first — the order a user expects after closing a tab.
+ */
+export declare function removePanelFromTree(node: LayoutNode, id: string): LayoutNode | null;
+/**
+ * Add a panel to a leaf. A panel already in that leaf is not duplicated.
+ *
+ * `select: false` adds it **without** making it the leaf's selected tab — what "open in the
+ * background" has to mean. Selecting it anyway would make the newly added panel the visible
+ * tab while some other panel stayed globally active, which is precisely the disagreement
+ * between leaf selection and `activePanelId` that divergence D2 is about. (rdd's
+ * `focus: false` did exactly that.)
+ */
+export declare function addPanelToLeaf(node: LayoutNode, leafId: string, panelId: string, options?: {
+    select?: boolean;
+}): LayoutNode;
+/** Insert a panel into a leaf at a specific tab index, and select it. */
+export declare function insertPanelInLeaf(node: LayoutNode, leafId: string, panelId: string, index: number): LayoutNode;
+/** Default id scheme for leaves created by a split. Any string is valid; this one is legible. */
+export declare const defaultLeafId: (kind: "split" | "edge") => string;
+/**
+ * Split a leaf, putting `panelId` in a new leaf on the given side.
+ *
+ * `newLeafId` is injectable so tests can assert tree shape without a timestamp in it.
+ */
+export declare function splitLeafInTree(node: LayoutNode, leafId: string, panelId: string, position: SplitDirection, splitRatio: number, newLeafId?: string): LayoutNode;
+/** Wrap the whole tree in a branch, docking `panelId` as a full-width/height edge row. */
+export declare function dockToEdge(root: LayoutNode, panelId: string, position: SplitDirection, edgeRatio: number, newLeafId?: string): LayoutNode;
+/** Remove a leaf entirely, honouring its `canClose`. Collapses and re-normalises like removal. */
+export declare function removeLeafFromTree(node: LayoutNode, leafId: string): LayoutNode | null;
+/** Select a panel as its leaf's active tab, wherever it is. */
+export declare function selectPanelInTree(node: LayoutNode, id: string): LayoutNode;
+/** The first leaf in document order, depth-first. */
+export declare function findFirstLeafId(node: LayoutNode): string | null;
+/** The leaf containing a panel, or `null`. */
+export declare function findLeafForPanel(node: LayoutNode, id: string): string | null;
+/** A leaf by id, or `null`. */
+export declare function findLeaf(node: LayoutNode | null, leafId: string): LayoutLeafNode | null;
+/** Whether a leaf exists in the tree. */
+export declare function leafExists(node: LayoutNode, leafId: string): boolean;
+/** Update the sizes of the branch at `path` (a list of child indices from the root). */
+export declare function updateSizesAtPath(node: LayoutNode, path: number[], sizes: number[]): LayoutNode;
+/** The subset of a layout needed to reason about visibility. */
+export interface ActiveTargetScope {
+    gridRoot: LayoutNode | null;
+    floating: FloatingWindow[];
+    panels: Record<string, PanelInfo>;
+}
+/**
+ * Whether `id` names a panel the user can actually see, and which may therefore be the
+ * globally active one: the selected tab of some leaf, or a floating window.
+ *
+ * A minimised panel never qualifies. It stays mounted, so leaving it active would keep
+ * routing contributed controls to a panel that is not on screen — the defect family that
+ * cost react-dockable-desktop two releases.
+ *
+ * Used both to validate a persisted `activePanelId` on load and to guard the one written on
+ * save, so the two directions cannot disagree about what "active" is allowed to mean.
+ */
+export declare function isVisibleActiveTarget(id: string, scope: ActiveTargetScope): boolean;
+/**
+ * Derive the globally active panel, in order:
+ *
+ *   1. the first leaf in document order whose own selected tab is a valid target;
+ *   2. otherwise the frontmost (highest `z`) floating window, so a float-only layout does
+ *      not come back with nothing active;
+ *   3. otherwise `null`.
+ *
+ * **Depth-first, not breadth-first.** For a grid whose first child is itself a split, a
+ * level-by-level walk reaches the *second* child's leaf before the first child's own
+ * children, and picks the wrong tab. Mirrors `findFirstLeafId`'s traversal for that reason.
+ *
+ * Never an arbitrary entry in `panels`: that seed is what made a restored workspace come
+ * back with one panel visible and a different, invisible one marked active.
+ */
+export declare function deriveActivePanelId(scope: ActiveTargetScope): string | null;