react-dockable-desktop 3.2.0 → 4.1.0

package/README.md

@@ -1,6 +1,6 @@
-# React Dockable Desktop
+    # React Dockable Desktop
 
-[![npm version](https://img.shields.io/badge/npm-v3.1.0-blue.svg)](https://www.npmjs.com/package/react-dockable-desktop)
+[![npm version](https://img.shields.io/badge/npm-v4.0.0-blue.svg)](https://www.npmjs.com/package/react-dockable-desktop)
 [![TypeScript](https://img.shields.io/badge/TypeScript-first-3178c6.svg)](https://www.typescriptlang.org/)
 [![Touch Ready](https://img.shields.io/badge/touch-iPad%20%7C%20Android-success.svg)](#touch--mobile)
 [![license](https://img.shields.io/badge/license-MIT-green.svg)](#license)
@@ -19,7 +19,8 @@ A premium dockable layout engine for React. Build desktop-class applications wit
 
 - **Split-Docking Grid** — drag panels to split any zone into rows/columns or group into tabbed containers
 - **Workspace Edge Docking** — drag to the outer edges to dock a panel as a full-width or full-height strip
-- **Floating Windows** — pop panels into freely resizable floating windows; 8-direction resize handles (N/NE/E/SE/S/SW/W/NW), maximize, minimize
+- **Floating Windows** — pop panels into freely resizable floating windows; 8-direction resize handles (N/NE/E/SE/S/SW/W/NW), maximize, minimize; drag to a workspace corner to anchor it there — anchored windows stack with 8 px gaps and reposition when the viewport resizes
+- **Panel Overlay** — per-panel overlay layer with anchored toolbars (`PanelToolbar`, `ToolbarButton`, `ToolbarToggle`, async search) and corner-anchored floating windows that stack, drag, and dock; `usePanelFloatingWindowManager()` opens N named windows dynamically from data or event handlers
 - **Touch & Mobile Ready** — full iPad and Android support: long-press to drag tabs, touch resize, 44px coarse-pointer targets throughout
 - **Zero-Unmount DOM Persistence** — panel DOM nodes are moved, never destroyed; WebGL, maps, terminals, and forms retain full state
 - **i18n & RTL** — full Right-to-Left layout support; `dir="rtl"` flips every control, tab order, and drop zone automatically
@@ -27,6 +28,8 @@ A premium dockable layout engine for React. Build desktop-class applications wit
 - **Imperative API** — `WorkspaceClient` opens, closes, focuses, and serializes panels from anywhere — inside or outside React
 - **Layout Serialization** — save and restore the full workspace as a JSON string; survives page reloads
 - **7 Built-in Skins** — VSCode, macOS, Chrome, Slate, Nord, Obsidian, Tokyo — all fully themeable via CSS variables
+- **Toast Notifications** — imperative singleton `toast.info/success/warning/error/promise()` with queue, pause-on-hover, progress bar, and a `ToastAdapter` interface for delegating to a third-party notification library
+- **Zero extra dependencies** — no runtime dependencies beyond React itself; everything is bundled in
 - **TypeScript-first** — complete type definitions included; no separate `@types/` package needed
 
 ---
@@ -34,17 +37,16 @@ A premium dockable layout engine for React. Build desktop-class applications wit
 ## Installation
 
 ```bash
-npm install react-dockable-desktop replace-react-contexify
+npm install react-dockable-desktop
 ```
 
-Import styles in your app entry file. **Order matters** — the contexify sheet must come first:
+Import styles in your app entry file:
 
 ```ts
-import 'replace-react-contexify/styles.css';
 import 'react-dockable-desktop/styles.css';
 ```
 
-**Requirements:** React ≥ 16.8 · Node ≥ 18
+**Requirements:** React ≥ 16.8 · Node ≥ 18 · No other runtime dependencies
 
 ---
 
@@ -132,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
@@ -144,12 +190,13 @@ 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 |
 | `useSidebarTab()` | `SidebarTabContext` | Self-control for content inside a Sidebar tab |
 | `usePanelContextMenu(items)` | `void` | Inject dynamic context menu items into this panel's right-click menu |
+| `usePanelFloatingWindowManager()` | `PanelFloatingWindowManagerHandle` | Open/close N named floating windows inside a panel overlay at runtime; each independently anchored, dockable, and resizable |
 | `useRegistry()` | `PanelRegistryClass` | The scoped panel registry for the current provider |
 | `useFormatMessage()` | `MessageFormatter` | i18n formatter matching the current provider's locale |
 
@@ -169,10 +216,10 @@ const panelCount = useWindowManagerState(s => Object.keys(s.panels).length);
 const workspace = new WorkspaceClient({ panels, initialState?, formatMessage?, dir? });
 
 // Panel lifecycle
-workspace.openPanel(id, component, options?)   // options: title, initialTarget, stickyRight, stickyBottom
+workspace.openPanel(id, component, options?)   // options: title, initialTarget, anchor
 workspace.closePanel(id)
 workspace.focusPanel(id)                       // raises floating / selects tab for docked
-workspace.floatPanel(id, rect?)                // detach to a floating window
+workspace.floatPanel(id, rect?, anchor?)       // detach to a floating window; optional corner anchor
 workspace.dockPanel(id)                        // return floating to the grid
 workspace.minimizePanel(id)
 workspace.restorePanel(id)
@@ -200,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
@@ -260,19 +348,28 @@ Touch support is built in for v3.1.0+. No extra setup required:
 
 ## i18n & RTL
 
+The library does **not** auto-detect direction — the consuming app owns it. Two things must be wired together:
+
 ```tsx
+// 1. Keep html[dir] in sync for portals (ContextMenu, flyout, Toast)
+//    that render into document.body and need CSS direction inheritance.
+useEffect(() => {
+  document.documentElement.dir = isRtl ? 'rtl' : 'ltr';
+}, [isRtl]);
+
+// 2. Pass dir prop to the provider — controls workspace layout engine.
 <DockableDesktopProvider
-  dir="rtl"
+  dir={isRtl ? 'rtl' : 'ltr'}
   formatMessage={(msg) => intl.formatMessage({ id: msg.id, defaultMessage: msg.defaultMessage })}
   predefinedMessages={customMessages}
 >
 ```
 
-`dir` can be `'ltr'` (default) or `'rtl'`. All layout, split directions, tab ordering, drop zones, and context menus flip automatically. You can also switch at runtime:
+`dir` can be `'ltr'` (default) or `'rtl'`. All layout, split directions, tab ordering, floating window controls, drop zones, sidebars, and context menus flip automatically.
 
-```ts
-workspace.setDirection('rtl');
-```
+Direction is **independent of locale** — you can have Arabic translations with LTR layout, or RTL without locale changes.
+
+See the [RTL Support guide](https://felipecarrillo100.github.io/react-dockable-desktop/guide/rtl) for the complete wiring pattern and macOS skin notes.
 
 ---
 
@@ -301,6 +398,27 @@ All built-in skins include dark and light variants. Create your own skin by over
 
 ## What's New
 
+### v4.1.0
+- **`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.
 - **Documentation overhaul** — All guides updated to cover the full v3.1.0 API surface.
@@ -331,7 +449,7 @@ All built-in skins include dark and light variants. Create your own skin by over
 | `bringToFront(id)` | `focusPanel(id)` — works for both floating and docked panels |
 | `setActivePanel(id)` | `focusPanel(id)` |
 
-Full details in the [Migration Guide](https://felipecarrillo100.github.io/react-dockable-desktop/guide/migration).
+Full details in the [Migration Guide](https://felipecarrillo100.github.io/react-dockable-desktop/guide/migration) and the [Changelog](https://github.com/felipecarrillo100/react-dockable-desktop/releases).
 
 ---
 
@@ -354,7 +472,9 @@ Complete guides, API reference, and interactive demo at:
 | [Theming](https://felipecarrillo100.github.io/react-dockable-desktop/guide/theming) | CSS variables, custom skins, dark/light modes |
 | [Advanced Topics](https://felipecarrillo100.github.io/react-dockable-desktop/guide/advanced) | RTL, multiple workspaces, custom header actions |
 | [Best Practices](https://felipecarrillo100.github.io/react-dockable-desktop/guide/best-practices) | Patterns for production-ready implementations |
-| [Migration Guide](https://felipecarrillo100.github.io/react-dockable-desktop/guide/migration) | Upgrade from v1 → v2 → v3 |
+| [Panel Overlay](https://felipecarrillo100.github.io/react-dockable-desktop/guide/panel-overlay) | `PanelOverlayRoot`, panel toolbars, `PanelFloatingWindow`, `usePanelFloatingWindowManager` |
+| [Toast Notifications](https://felipecarrillo100.github.io/react-dockable-desktop/guide/toast) | `toast` singleton, `<ToastContainer>`, queue behaviour, theming, `ToastAdapter` |
+| [Migration Guide](https://felipecarrillo100.github.io/react-dockable-desktop/guide/migration) | Upgrade from v1 → v2 → v3 → v4 |
 | [API Reference](https://felipecarrillo100.github.io/react-dockable-desktop/api/) | Full type-level reference for all exports |
 
 ---