react-dockable-desktop 4.0.0 → 4.1.1

package/README.md

@@ -134,6 +134,50 @@ export default function EditorPanel() {
 }
 ```
 
+### Lifecycle callbacks
+
+`useFormContainer()` exposes a full push-based lifecycle API — no subscriptions to global state required:
+
+```tsx
+import { useFormContainer } from 'react-dockable-desktop';
+import { useEffect } from 'react';
+
+export default function MapPanel() {
+  const {
+    containerType,          // current container type at mount: 'dockable-panel' | 'floating-window'
+    onActivate,             // fires when this panel becomes the globally active panel
+    onDeactivate,           // fires when this panel loses active status (or is destroyed)
+    onContainerTypeChange,  // fires when the panel moves between docked and floating
+    onClose,                // fires just before the panel is destroyed
+    requestMinimize,        // imperatively minimize this panel to the taskbar
+    getDimensions,          // synchronously read current {width, height} — null until first layout
+  } = useFormContainer();
+
+  useEffect(() => {
+    const unsub = [
+      onActivate?.(() => {
+        // e.g. resume animation, reload data
+        const dims = getDimensions?.();
+        console.log('active, size:', dims);
+      }),
+      onDeactivate?.(() => {
+        // e.g. pause background work
+      }),
+      onContainerTypeChange?.((type) => {
+        // type === 'floating-window' | 'dockable-panel'
+        // e.g. trigger map.resize() after layout change
+      }),
+      onClose?.(() => {
+        // final cleanup — unsubscribe from external stores
+      }),
+    ];
+    return () => unsub.forEach(fn => fn?.());
+  }, []);
+
+  return <div>Map</div>;
+}
+```
+
 ---
 
 ## Hooks
@@ -146,7 +190,7 @@ Call these inside any component within the `DockableDesktopProvider` tree:
 | `useWindowManagerState(selector?)` | `WindowState` or selected slice | Read layout, floating windows, active panel ID |
 | `usePanelActions()` | `PanelActions` | Open modal overlays and left/right side drawers |
 | `usePanelContext()` | `{ publish, subscribe }` | Inter-panel typed event bus |
-| `useFormContainer()` | `FormContainerContract` | Dirty state, close guards, dynamic panel title/icon |
+| `useFormContainer()` | `FormContainerContract` | Dirty state, close guards, dynamic title/icon, lifecycle callbacks (activate, deactivate, container-type change), imperative minimize, sync dimensions |
 | `usePanelId()` | `string` | The panel's own instance ID — no prop drilling needed |
 | `useToolbar()` | `ToolbarContextValue` | Read/write Toolbar state (active tool, modifiers) from any panel |
 | `useSidebar()` | `SidebarContextValue` | Open/close Sidebar tabs from any component in the Sidebar tree |
@@ -203,6 +247,47 @@ workspace.setDirection('ltr' | 'rtl')
 
 ---
 
+## FormContainerContract Reference
+
+`useFormContainer()` returns a `FormContainerContract` with these members:
+
+| Member | Type | Description |
+| :--- | :--- | :--- |
+| `requestClose(options?)` | `(options?: CloseOptions) => void` | Request the container to close; respects dirty state and close guards |
+| `setDirty(dirty, options?)` | `(dirty: boolean) => void` | Mark unsaved changes; triggers confirmation dialog on close |
+| `onCloseRequested(handler)` | `(handler) => unsubscribe` | Register a close guard; return `false` to block the close |
+| `setTitle(title)` | `(title) => void` | Change the tab/window title dynamically |
+| `setIcon?(icon)` | `(icon: ReactNode) => void` | Change the tab/window icon dynamically |
+| `containerType?` | `ContainerType` | Container type **at mount time** — see `onContainerTypeChange` for live updates |
+| `instanceId` | `string` | The panel's instance ID |
+| `onClose?(handler)` | `(handler) => unsubscribe` | Subscribe to panel destruction |
+| `onMinimize?(handler)` | `(handler) => unsubscribe` | Subscribe to minimize events |
+| `onRestore?(handler)` | `(handler) => unsubscribe` | Subscribe to restore-from-taskbar events |
+| `onResize?(handler)` | `(handler) => unsubscribe` | Subscribe to resize events; handler receives `(width, height)` |
+| `requestMinimize?()` | `() => void` | Imperatively minimize this panel to the taskbar |
+| `getDimensions?()` | `() => {width, height} \| null` | Synchronously read the current rendered size; `null` until first layout |
+| `onActivate?(handler)` | `(handler) => unsubscribe` | Subscribe to this panel becoming the globally active panel |
+| `onDeactivate?(handler)` | `(handler) => unsubscribe` | Subscribe to this panel losing active status; also fires on destruction |
+| `onContainerTypeChange?(handler)` | `(handler) => unsubscribe` | Subscribe to dock↔float transitions; handler receives the new `ContainerType` |
+
+### ContainerType
+
+```ts
+type ContainerType =
+  | 'dockable-panel'   // panel is docked in the grid
+  | 'floating-window'  // panel is in a detached floating window
+  | 'left-panel'       // rendered inside the left side drawer
+  | 'right-panel'      // rendered inside the right side drawer
+  | 'modal'            // rendered inside a modal overlay
+  | 'standalone';      // rendered outside the Window Manager (default / no context)
+```
+
+`containerType` on the contract reflects the state **at mount time**. Subscribe to `onContainerTypeChange` to get notified whenever the panel moves between `'dockable-panel'` and `'floating-window'`. Minimize/restore cycles do **not** fire `onContainerTypeChange`; use `onMinimize`/`onRestore` for those.
+
+All `on*` subscribers return an unsubscribe function. Call it (or return it from `useEffect`) to avoid leaks.
+
+---
+
 ## Layout Persistence
 
 ```ts
@@ -313,25 +398,26 @@ All built-in skins include dark and light variants. Create your own skin by over
 
 ## What's New
 
-### v4.3.0
-- **Workspace corner anchor zones** — drag any panel (floating or docked tab) to a workspace corner to pin it there. Four 80×80 px snap zones appear during drag; same visual style as the inner panel drop zones. Anchored windows stack with 8 px gaps, uncapped, and reposition automatically on viewport resize.
-- **`anchor` option on `openPanel` and `floatPanel`** — spawn a new floating window pre-anchored: `openPanel('id', 'comp', { initialTarget: 'floating', anchor: 'top-right' })` or `floatPanel('id', undefined, 'bottom-left')`.
-- **`defaultAnchor` in panel registry** — set `defaultAnchor: 'top-left'` in `PanelRegistryEntry.defaultOptions` so every instance of that component opens anchored.
-- **Full RTL support** — floating window drop zones, edge triggers, and corner snap zones all mirror correctly when `dir="rtl"`.
-- **Removed:** `openPanel` options `stickyRight` / `stickyBottom` (replaced by `anchor`). Saved layouts are automatically migrated.
-
-### v4.2.0
-- **Toast Notifications** — zero-dependency `toast.info/success/warning/error/promise()` singleton. `<ToastContainer>` renders via `createPortal`; supports configurable position, width, max-visible queue, pause-on-hover, opt-in progress bar, and auto-dismiss. `ToastAdapter` lets you delegate to Ant Design, MUI, Sonner, or any other notification library without changing call sites. All colors inherit the active skin automatically.
-
 ### v4.1.0
-- **Panel Overlay system** — `PanelOverlayRoot`, `PanelToolbar`, `PanelFloatingWindow`, and `usePanelFloatingWindowManager` bring per-panel toolbars and dynamically-spawned corner-anchored floating info windows to any panel.
-- **`usePanelFloatingWindowManager()`** — imperative hook for opening N named floating windows from data or event handlers; all windows share z-ordering, drag, and corner-docking infrastructure.
-- **Toolbar primitives** — `ToolbarButton`, `ToolbarToggle`, `PanelToolbarSeparator`, `ToolbarSpacer`, `ToolbarCenter`, `ToolbarSearchInput` compose panel toolbar content.
+- **`onActivate` / `onDeactivate` on `FormContainerContract`** — push-based callbacks fired when a panel gains or loses globally active status; no need to subscribe to `useWindowManagerState` and diff `activePanelId` inside each panel.
+- **`onContainerTypeChange` on `FormContainerContract`** — fires with the new `ContainerType` (`'dockable-panel'` | `'floating-window'`) whenever the panel transitions between docked and floating; does not fire during minimize/restore cycles.
+- **`getDimensions()` on `FormContainerContract`** — synchronous getter returning the current `{width, height}` of the panel (or `null` before first layout); reads from the same `ResizeObserver` that drives `onResize`.
+- **`requestMinimize()` on `FormContainerContract`** — imperative counterpart to `requestClose()`; minimizes the panel without needing `useWindowManagerActions`.
+- **`'floating-window'` ContainerType value** — `containerType` now correctly reports `'dockable-panel'` for docked panels and `'floating-window'` for panels in detached floating windows.
 
 ### v4.0.0
 - **Built-in `<ContextMenu>`** — zero-dependency context menu, portal-rendered and styled with design tokens. No extra package or CSS import needed.
 - **`ContextMenuAdapter` interface** — swap the default menu for your own design-system implementation via `<WindowManager contextMenuAdapter={...} />`.
 - **New exports** — `ContextMenu`, `DefaultContextMenuAdapter`, `ContextMenuHandle`, `ContextMenuAdapter`, `ShowContextMenuOptions`.
+- **Panel Overlay system** — `PanelOverlayRoot`, `PanelToolbar`, `PanelFloatingWindow`, and `usePanelFloatingWindowManager` bring per-panel toolbars and dynamically-spawned corner-anchored floating info windows to any panel.
+- **`usePanelFloatingWindowManager()`** — imperative hook for opening N named floating windows from data or event handlers; all windows share z-ordering, drag, and corner-docking infrastructure.
+- **Toolbar primitives** — `ToolbarButton`, `ToolbarToggle`, `PanelToolbarSeparator`, `ToolbarSpacer`, `ToolbarCenter`, `ToolbarSearchInput` compose panel toolbar content.
+- **Toast Notifications** — zero-dependency `toast.info/success/warning/error/promise()` singleton. `<ToastContainer>` renders via `createPortal`; supports configurable position, width, max-visible queue, pause-on-hover, opt-in progress bar, and auto-dismiss. `ToastAdapter` lets you delegate to Ant Design, MUI, Sonner, or any other notification library without changing call sites.
+- **Workspace corner anchor zones** — drag any panel (floating or docked tab) to a workspace corner to pin it there. Four 80×80 px snap zones appear during drag; anchored windows stack with 8 px gaps and reposition automatically on viewport resize.
+- **`anchor` option on `openPanel` and `floatPanel`** — spawn a new floating window pre-anchored: `openPanel('id', 'comp', { initialTarget: 'floating', anchor: 'top-right' })` or `floatPanel('id', undefined, 'bottom-left')`.
+- **`defaultAnchor` in panel registry** — set `defaultAnchor: 'top-left'` in `PanelRegistryEntry.defaultOptions` so every instance of that component opens anchored.
+- **Full RTL support** — floating window drop zones, edge triggers, and corner snap zones all mirror correctly when `dir="rtl"`.
+- **Removed:** `openPanel` options `stickyRight` / `stickyBottom` (replaced by `anchor`). Saved layouts are automatically migrated.
 
 ### v3.2.0
 - **Per-skin active state design language** — Sidebar tabs and Toolbar buttons now use a per-skin visual pattern (transparent bar, floating chip, pill, line, neon glow), driven by new CSS design tokens — fully overridable in custom skins. CSS-only, no API changes.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-dockable-desktop",
-  "version": "4.0.0",
+  "version": "4.1.1",
   "description": "A premium, state-of-the-art window manager and dockable layout engine for React. Supports fluid grid splits, tabbed groups, floating resizable windows, zero-unmount state preservation, context menus, and internationalization.",
   "main": "dist/index.cjs",
   "module": "dist/index.js",