react-dockable-desktop 7.12.0-next.1 → 7.12.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -10,6 +10,79 @@ replacement and the version that removes the old API.
10
10
 
11
11
  ## [Unreleased]
12
12
 
13
+ ## [7.12.0] — 2026-11-21
14
+
15
+ **Pop-out windows.** A panel, or a managed widget that left its panel, can move into its own browser
16
+ window, for a second monitor, and come back where it was, without its content remounting: its
17
+ state, scroll offsets and a canvas's WebGL context go with it. The window gets the page's styles and
18
+ theme; `popoutWrapper` points CSS-in-JS at it, `usePanelWindow()` gives panel code its window, and
19
+ toasts and menus show in the window the user is in. Off by default (`createWorkspace({ popOut: true })`
20
+ and `defaultOptions.canPopOut` per type): an app that doesn't turn it on sees no change. Guide:
21
+ [Pop-out Windows](https://felipecarrillo100.github.io/react-dockable-desktop/guide/popout-windows).
22
+
23
+ This release is the two pre-releases below, tried by a client in production code, plus a fix to the
24
+ timing of the pop-out events, a marker for the window's kind and a corrected testing tip. Coming
25
+ from 7.11.x, read both sections below: **7.12.0-next.0** for the feature and its **Upgrading** point
26
+ (five new message keys), and **7.12.0-next.1** for the fixes and additions that followed (its
27
+ **Changed** point: the return button has no text, only a tooltip and a name). The **Fixed** entry
28
+ below supersedes what those two sections say about when the pop-out events arrive.
29
+
30
+ In short, new:
31
+ - `createWorkspace({ popOut })`, and `canPopOut` on panel types' `defaultOptions`;
32
+ - on the workspace: `popOutPanel()`, `returnPanel()` and `focusPanelWindow()`; `focusPanel()` brings
33
+ a pop-out forward;
34
+ - on `<DockableDesktopProvider>`: `popoutUrl` and `popoutWrapper`;
35
+ - `usePanelWindow()` and `usePanel().isPoppedOut`; `PanelInfo.poppedOut`;
36
+ - for managed widgets: `useFloatingWidgets().popOut()`, `ManagedWidget.canPopOut`,
37
+ `useWidget().isPoppedOut`, and `canPopOut`, `isPoppedOut` and `popOut()` on `WidgetMenuContext`;
38
+ - events `panel:popping-out`, `panel:popped-out`, `panel:returning` and `panel:returned`;
39
+ - types `PopOutResult`, `PanelWindow` and `PopoutWrapperProps`;
40
+ - messages `popOutWindow`, `returnToDesktop`, `backIntoPanel`, `popOutBlocked` and `inOwnWindow`;
41
+ - CSS: `.rdd-popout-frame` (with `__header`, `__icon`, `__icon--menu`, `__title`, `__return`,
42
+ `__body`), `.rdd-taskbar-item--popout`, `.rdd-taskbar-item-popout-marker`, and the attributes
43
+ `data-rdd-popout`, `data-rdd-popout-kind` and `data-rdd-taskbar-popout`;
44
+ - the "Open in new window" menu item, toasts in the focused window, Escape per window, and pop-outs
45
+ in the taskbar.
46
+
47
+ ### Fixed
48
+
49
+ - **The pop-out events now come at the right moment for layout.** `panel:popping-out` is sent in the
50
+ user's click, while the panel is still in the page at its size. In next.1 it came after the panel
51
+ had left (0 × 0), and with `popoutUrl` only once the window's page had loaded. `panel:popped-out`
52
+ is now sent once the panel is in the window and laid out (a frame has passed), and
53
+ `panel:returned` once it is back in its place in the page and laid out, so a `resize()` there sees
54
+ the new size. In next.1 both came while the panel was still in its old place. `panel:returning`
55
+ is unchanged. If the window's frame never shows, they are sent anyway after about 4 seconds.
56
+
57
+ ### Changed
58
+
59
+ - **A window that fails after `panel:popping-out` sends `panel:returned`** (its page can't be read
60
+ or doesn't load in time, or the window is closed before the panel got there), so every
61
+ `panel:popping-out` is followed by `panel:popped-out` or `panel:returned`. There is no
62
+ `panel:returning` then. In next.1 such a window sent no event.
63
+
64
+ ### Added
65
+
66
+ - **`data-rdd-popout-kind="panel"` or `"widget"`** on the window's frame (`.rdd-popout-frame`), to
67
+ style a panel's window and a widget's apart, or find a widget's window in a test without relying
68
+ on its panel id.
69
+
70
+ ### Docs
71
+
72
+ - **Pop-out Windows, testing with Playwright, corrected:** turning Chrome's focus emulation off
73
+ doesn't decide which window a toast goes to (headless, nothing changes; headed, it depends on the
74
+ order of clicks and raises). The guide now stubs `document.hasFocus` in the page that should not
75
+ have focus, tests that `focusPanelWindow` is asked for, and leaves real focus to a check by hand.
76
+ - **Pop-out Windows:** when each event arrives, the window's kind, every public name in the API
77
+ summary.
78
+ - **Reviewed for the whole feature:** every guide page that touches pop-outs now says so or links
79
+ to the guide (Introduction, Quick Start, Layout, Panel Lifecycle & Forms, Modals & Side Panels,
80
+ Context Menus, Toolbar, Panel Contributions, Widgets Out of the Panel, Toast, Event Bus,
81
+ Workspace, Advanced, RTL, Theming, Best Practices); Migration has the full 7.11 → 7.12 section,
82
+ with what changed since the pre-releases; the home page, the README and the API comments
83
+ (`popOutPanel`, `PopOutResult`, the four events) describe the final behaviour. "Pop out" no
84
+ longer names floating a panel.
85
+
13
86
  ## [7.12.0-next.1] — 2026-11-21
14
87
 
15
88
  **Pre-release** on npm's `next` tag, from the first feedback on 7.12.0-next.0. A fix for CSS-in-JS in
@@ -1548,7 +1621,8 @@ All of the above is additive and backward-compatible: every new field is optiona
1548
1621
 
1549
1622
  ---
1550
1623
 
1551
- [Unreleased]: https://github.com/felipecarrillo100/react-dockable-desktop/compare/v7.12.0-next.1...HEAD
1624
+ [Unreleased]: https://github.com/felipecarrillo100/react-dockable-desktop/compare/v7.12.0...HEAD
1625
+ [7.12.0]: https://github.com/felipecarrillo100/react-dockable-desktop/compare/v7.11.0...v7.12.0
1552
1626
  [7.12.0-next.1]: https://github.com/felipecarrillo100/react-dockable-desktop/compare/v7.12.0-next.0...v7.12.0-next.1
1553
1627
  [7.12.0-next.0]: https://github.com/felipecarrillo100/react-dockable-desktop/compare/v7.11.0...v7.12.0-next.0
1554
1628
  [7.11.0]: https://github.com/felipecarrillo100/react-dockable-desktop/compare/v7.10.1...v7.11.0
package/README.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # React Dockable Desktop
2
2
 
3
- [![npm version](https://img.shields.io/badge/npm-v7.12.0--next.1-blue.svg)](https://www.npmjs.com/package/react-dockable-desktop)
3
+ [![npm version](https://img.shields.io/badge/npm-v7.12.0-blue.svg)](https://www.npmjs.com/package/react-dockable-desktop)
4
4
  [![TypeScript](https://img.shields.io/badge/TypeScript-first-3178c6.svg)](https://www.typescriptlang.org/)
5
5
  [![Touch Ready](https://img.shields.io/badge/touch-iPad%20%7C%20Android-success.svg)](#touch--mobile)
6
6
  [![license](https://img.shields.io/badge/license-MIT-green.svg)](#license)
@@ -26,7 +26,7 @@ serialised layout format**, so a layout saved by either library loads in the oth
26
26
  - **Split-Docking Grid** — drag panels to split any zone into rows/columns or group into tabbed containers
27
27
  - **Workspace Edge Docking** — drag to the outer edges to dock a panel as a full-width or full-height strip
28
28
  - **Docking Rules** — keep a panel type in the grid (`canFloat: false`) or floating (`canDock: false`), and veto any move with one `canDrop` function; forbidden targets simply aren't offered
29
- - **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
29
+ - **Floating Windows** — float panels as freely resizable 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
30
30
  - **Panel Overlay** — per-panel overlay layer with anchored toolbars (`RddPanelToolbar`, `RddToolbarButton`, `RddToolbarToggle`, async search) and corner-anchored floating windows that stack, drag, and dock; an axis can span the panel instead of carrying a fixed size, so a strip or column tracks the panel as it resizes — set declaratively or by dragging an edge out until it snaps; `useFloatingWidgets()` opens N named windows dynamically from data or event handlers, and can move one out of its panel (docked beside it, a tab, or floating) and back without remounting it
31
31
  - **Pop-out Windows** — a panel, or a managed widget out of its panel, moves into its own browser window for a second monitor and comes back where it was, without remounting: state, scroll and a WebGL context go with it. The window gets the page's styles and theme; opt-in with `createWorkspace({ popOut: true })` and `canPopOut` per type ([guide →](https://felipecarrillo100.github.io/react-dockable-desktop/guide/popout-windows))
32
32
  - **Touch & Mobile Ready** — full iPad and Android support: long-press to drag tabs, touch resize, 44px coarse-pointer targets throughout
@@ -182,7 +182,7 @@ Call these inside any component within the `DockableDesktopProvider` tree:
182
182
  | `useWorkspaceState(selector?)` | `WorkspaceState` or selected slice | Read layout, floating windows, active panel ID |
183
183
  | `useModals()` | `ModalsApi` | Open, close and track modal overlays |
184
184
  | `useSidePanels()` | `SidePanelsApi` | Open, close and track the left/right side drawers |
185
- | `usePanel()` | `PanelHandle` | Inside a panel: its `id`, live `containerType`, `isActive`, dirty state, dynamic title/icon, `close()`, `minimize()` |
185
+ | `usePanel()` | `PanelHandle` | Inside a panel: its `id`, live `containerType`, `isActive`, `isPoppedOut`, dirty state, dynamic title/icon, `close()`, `minimize()` |
186
186
  | `usePanelEvents(events)` | `void` | Inside a panel: activate, deactivate, minimize, restore, close, resize, container-type change |
187
187
  | `useBeforeClose(guard)` | `void` | Inside a panel: a close guard; resolve `false` to keep it open |
188
188
  | `useSaveState(getState)` | `void` | Inside a panel: state pulled fresh by every `saveLayout()` |
@@ -250,6 +250,7 @@ workspace.updatePanelProps(id, props | prev => next) // new props; re-checks wh
250
250
  workspace.popOutPanel(id) // → PopOutResult; into its own browser window, inside the user's click
251
251
  workspace.returnPanel(id) // → { ok }; back where it was
252
252
  workspace.focusPanelWindow(id) // → { ok }; bring the window that holds it forward, best effort
253
+ // Provider props: popoutUrl (the window's same-origin page), popoutWrapper (CSS-in-JS in the window)
253
254
 
254
255
  // Synchronous state queries (no hook needed)
255
256
  workspace.isOpen(id) // → boolean
@@ -269,6 +270,8 @@ workspace.onPanelMinimize(cb)
269
270
  workspace.onPanelRestore(cb)
270
271
  workspace.onLayoutChanged(cb)
271
272
  workspace.onPanelsExcluded(cb) // saveLayout() left out non-serializable panels
273
+ // Pop-out events: 'panel:popping-out' / 'panel:returning' just before a move,
274
+ // 'panel:popped-out' / 'panel:returned' once laid out in the new place
272
275
 
273
276
  // Direction and menus
274
277
  workspace.setDirection('ltr' | 'rtl')
@@ -327,6 +330,8 @@ createWorkspace({
327
330
  });
328
331
  ```
329
332
 
333
+ A panel in its own browser window is saved at the place it would come back to; no window reopens after a reload.
334
+
330
335
  ---
331
336
 
332
337
  ## Side Panels & Modals
@@ -477,8 +482,8 @@ Complete guides, API reference, and interactive demo at:
477
482
  | [Panel Overlay](https://felipecarrillo100.github.io/react-dockable-desktop/guide/panel-overlay) | `RddPanelOverlay`, panel toolbars, `RddFloatingWidget`, `useFloatingWidgets` |
478
483
  | [Widgets Out of the Panel](https://felipecarrillo100.github.io/react-dockable-desktop/guide/widgets-out-of-the-panel) | Dock, tab or float a managed widget beside its panel; `useWidget`, `placement`, `preserveEmbeds` |
479
484
  | [Pop-out Windows](https://felipecarrillo100.github.io/react-dockable-desktop/guide/popout-windows) | A panel or widget in its own browser window; `popOutPanel`, `popoutUrl`, `popoutWrapper` for CSS-in-JS, `usePanelWindow` |
480
- | [Toast Notifications](https://felipecarrillo100.github.io/react-dockable-desktop/guide/toast) | `toast` singleton, `<RddToasts>`, queue behaviour, theming, `ToastAdapter` |
481
- | [Migration Guide](https://felipecarrillo100.github.io/react-dockable-desktop/guide/migration) | Upgrading across major versions |
485
+ | [Toast Notifications](https://felipecarrillo100.github.io/react-dockable-desktop/guide/toast) | `toast` singleton, `<RddToasts>`, queue behaviour, theming, `ToastAdapter`, toasts in pop-out windows |
486
+ | [Migration Guide](https://felipecarrillo100.github.io/react-dockable-desktop/guide/migration) | Upgrading across major versions, and 7.11 → 7.12 (pop-out windows) |
482
487
  | [UI Frameworks](https://felipecarrillo100.github.io/react-dockable-desktop/guide/ui-frameworks) | Using it with MUI, Bootstrap or Tailwind: dark mode, z-index, overrides |
483
488
  | [Stability & Versioning](https://felipecarrillo100.github.io/react-dockable-desktop/guide/stability) | What the public API is, deprecation and support periods |
484
489
  | [API Reference](https://felipecarrillo100.github.io/react-dockable-desktop/api/) | Full type-level reference for all exports |