react-dockable-desktop 3.2.0 → 4.0.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
 
 ---
 
@@ -150,6 +152,7 @@ Call these inside any component within the `DockableDesktopProvider` tree:
 | `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 +172,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)
@@ -260,19 +263,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 +313,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.
+
+### 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`.
+
 ### 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 +363,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 +386,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 |
 
 ---