react-dockable-desktop 6.0.0 → 6.0.1

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: {

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: {