react-dockable-desktop 3.1.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
 
 ---
 
@@ -146,6 +148,11 @@ Call these inside any component within the `DockableDesktopProvider` tree:
 | `usePanelContext()` | `{ publish, subscribe }` | Inter-panel typed event bus |
 | `useFormContainer()` | `FormContainerContract` | Dirty state, close guards, dynamic panel title/icon |
 | `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 |
 
@@ -165,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)
@@ -256,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.
 
 ---
 
@@ -281,19 +297,56 @@ workspace.setDirection('rtl');
 <WindowManager skin="tokyo" />
 ```
 
-**Built-in skins:** `vscode` · `macos` · `chrome` · `slate` · `nord` · `obsidian` · `tokyo`
+| Skin | Character | Active state (Sidebar & Toolbar) |
+|------|-----------|----------------------------------|
+| `vscode` | VS Code dark (default) | Transparent fill, 2 px accent bar |
+| `macos` | Glass Chip — accent fill, rounded corners | 36 px floating chip, white inner ring |
+| `chrome` | Google Chrome tab geometry | Sidebar: half-pill bridge. Toolbar: 2 px bar |
+| `slate` | Fluent Slate — deep navy | Floating 36 px accent-tinted pill |
+| `nord` | Arctic Frost — muted Nord palette | Short horizontal line below icon |
+| `obsidian` | Vercel Midnight — pure black/white | Deep glow + icon drop-shadow |
+| `tokyo` | Tokyo Night — purple accent | Neon glow + vivid icon drop-shadow |
 
-Create your own skin by overriding CSS custom properties under a `[data-workspace-skin="myskin"]` selector. See the [Theming Guide](https://felipecarrillo100.github.io/react-dockable-desktop/guide/theming) for the full variable reference.
+All built-in skins include dark and light variants. Create your own skin by overriding CSS custom properties under a `[data-workspace-skin="myskin"]` selector. See the [Theming Guide](https://felipecarrillo100.github.io/react-dockable-desktop/guide/theming) for the full variable reference and the [Per-skin active state guide](https://felipecarrillo100.github.io/react-dockable-desktop/guide/theming#per-skin-active-state-design-language) to customise the Sidebar/Toolbar active indicator in your own skin.
 
 ---
 
 ## 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.
+
 ### v3.1.0
-- **Full touch & iPad/Android support** — Pointer Events API migration; long-press (300ms) activates tab drag; all drag/resize surfaces work with finger and Apple Pencil
-- **8-direction resize handles** — floating windows now have N, NE, E, SE, S, SW, W, NW resize handles
-- **Smart resizer hit areas** — horizontal resizer extends only upward into the safe content zone, preventing accidental activation when clicking tabs directly below
-- **Cursor bug fix** — cursor orientation during active resize drag now matches the visual handle correctly
+- **`<Toolbar>` component** — Vertical/horizontal strip hosting `action`, `radio`, `toggle`, `group`, and `separator` items. `useToolbar()` reads/writes state from any panel. `ToolbarGroupItem` adds a collapsed tool-family flyout with controlled mode support.
+- **`<WindowManager taskbarVisibility>`** — Three modes: `'always'` (permanent bar, new default), `'compact'` (shows only with minimized panels), `'autohide'` (overlay bar with 8 px peek strip).
+- **Sidebar resizable drawer** — Drag the drawer edge to resize. Props: `defaultWidth` (px), `minWidth`, `maxWidth`, `onWidthChange`. `drawerWidth` (string) deprecated.
+- **Sidebar `visible` / `stripVisible`** — `visible` collapses the entire sidebar; `stripVisible` collapses only the activity bar. New handle methods: `showStrip()`, `hideStrip()`, `setWidth(px)`, `getWidth()`.
+- **`useSidebar()` / `useSidebarTab()` hooks** — Programmatic Sidebar control from any component in the tree.
+- **`usePanelContextMenu()` hook** — Inject dynamic right-click context menu items from inside a panel component.
+- **Touch & iPad/Android support** — Pointer Events migration; long-press (300 ms) activates tab drag; taskbar chips support hover preview and long-press context menu on touch.
+- **8-direction resize handles** — Floating windows now have N, NE, E, SE, S, SW, W, NW resize handles.
+- **Skin scope fix** — `data-workspace-skin` now applied to `document.documentElement` so Toolbar and Sidebar always inherit the correct skin.
 
 ### v3.0.0
 - **`DockableDesktopProvider`** — single composite provider replaces the manual `WindowManagerProvider + PanelProvider` nesting
@@ -310,7 +363,7 @@ Create your own skin by overriding CSS custom properties under a `[data-workspac
 | `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).
 
 ---
 
@@ -333,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 |
 
 ---