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

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,102 @@ replacement and the version that removes the old API.
10
10
 
11
11
  ## [Unreleased]
12
12
 
13
+ ## [7.12.1] — 2026-11-21
14
+
15
+ A fix to pop-out windows. No API change.
16
+
17
+ ### Fixed
18
+
19
+ - **A pop-out from a click inside a pop-out window works.** `workspace.popOutPanel()` or a widget's
20
+ `popOut()` called from a click in one of the app's pop-out windows (a widget's "Open in new
21
+ window" item while its panel is in a window of its own, or a button in a popped-out panel that pops
22
+ out another panel) was refused with `'no-gesture'`: only the main page's click was looked for, and
23
+ the main page opened the window, which a browser blocks when the user clicked another window. Now
24
+ a click in any of the app's windows counts, and that window opens the new one. A relative
25
+ `popoutUrl` still means the main page's address. A widget's window also opens where it was, on its
26
+ owner's window's screen: it would have been placed from the main window's position.
27
+ - A widget can now pop out while its panel is in a window: it goes into its own window, and closing
28
+ that window puts it back into its panel there.
29
+
30
+ ### Docs
31
+
32
+ - **Pop-out Windows guide:** a click in any of the app's windows counts as the user's gesture. The
33
+ testing section adds that Playwright's `evaluate` and its waits count as a user activation for
34
+ about 5 seconds, which can hide a missing gesture in a test.
35
+
36
+ ## [7.12.0] — 2026-11-21
37
+
38
+ **Pop-out windows.** A panel, or a managed widget that left its panel, can move into its own browser
39
+ window, for a second monitor, and come back where it was, without its content remounting: its
40
+ state, scroll offsets and a canvas's WebGL context go with it. The window gets the page's styles and
41
+ theme; `popoutWrapper` points CSS-in-JS at it, `usePanelWindow()` gives panel code its window, and
42
+ toasts and menus show in the window the user is in. Off by default (`createWorkspace({ popOut: true })`
43
+ and `defaultOptions.canPopOut` per type): an app that doesn't turn it on sees no change. Guide:
44
+ [Pop-out Windows](https://felipecarrillo100.github.io/react-dockable-desktop/guide/popout-windows).
45
+
46
+ This release is the two pre-releases below, tried by a client in production code, plus a fix to the
47
+ timing of the pop-out events, a marker for the window's kind and a corrected testing tip. Coming
48
+ from 7.11.x, read both sections below: **7.12.0-next.0** for the feature and its **Upgrading** point
49
+ (five new message keys), and **7.12.0-next.1** for the fixes and additions that followed (its
50
+ **Changed** point: the return button has no text, only a tooltip and a name). The **Fixed** entry
51
+ below supersedes what those two sections say about when the pop-out events arrive.
52
+
53
+ In short, new:
54
+ - `createWorkspace({ popOut })`, and `canPopOut` on panel types' `defaultOptions`;
55
+ - on the workspace: `popOutPanel()`, `returnPanel()` and `focusPanelWindow()`; `focusPanel()` brings
56
+ a pop-out forward;
57
+ - on `<DockableDesktopProvider>`: `popoutUrl` and `popoutWrapper`;
58
+ - `usePanelWindow()` and `usePanel().isPoppedOut`; `PanelInfo.poppedOut`;
59
+ - for managed widgets: `useFloatingWidgets().popOut()`, `ManagedWidget.canPopOut`,
60
+ `useWidget().isPoppedOut`, and `canPopOut`, `isPoppedOut` and `popOut()` on `WidgetMenuContext`;
61
+ - events `panel:popping-out`, `panel:popped-out`, `panel:returning` and `panel:returned`;
62
+ - types `PopOutResult`, `PanelWindow` and `PopoutWrapperProps`;
63
+ - messages `popOutWindow`, `returnToDesktop`, `backIntoPanel`, `popOutBlocked` and `inOwnWindow`;
64
+ - CSS: `.rdd-popout-frame` (with `__header`, `__icon`, `__icon--menu`, `__title`, `__return`,
65
+ `__body`), `.rdd-taskbar-item--popout`, `.rdd-taskbar-item-popout-marker`, and the attributes
66
+ `data-rdd-popout`, `data-rdd-popout-kind` and `data-rdd-taskbar-popout`;
67
+ - the "Open in new window" menu item, toasts in the focused window, Escape per window, and pop-outs
68
+ in the taskbar.
69
+
70
+ ### Fixed
71
+
72
+ - **The pop-out events now come at the right moment for layout.** `panel:popping-out` is sent in the
73
+ user's click, while the panel is still in the page at its size. In next.1 it came after the panel
74
+ had left (0 × 0), and with `popoutUrl` only once the window's page had loaded. `panel:popped-out`
75
+ is now sent once the panel is in the window and laid out (a frame has passed), and
76
+ `panel:returned` once it is back in its place in the page and laid out, so a `resize()` there sees
77
+ the new size. In next.1 both came while the panel was still in its old place. `panel:returning`
78
+ is unchanged. If the window's frame never shows, they are sent anyway after about 4 seconds.
79
+
80
+ ### Changed
81
+
82
+ - **A window that fails after `panel:popping-out` sends `panel:returned`** (its page can't be read
83
+ or doesn't load in time, or the window is closed before the panel got there), so every
84
+ `panel:popping-out` is followed by `panel:popped-out` or `panel:returned`. There is no
85
+ `panel:returning` then. In next.1 such a window sent no event.
86
+
87
+ ### Added
88
+
89
+ - **`data-rdd-popout-kind="panel"` or `"widget"`** on the window's frame (`.rdd-popout-frame`), to
90
+ style a panel's window and a widget's apart, or find a widget's window in a test without relying
91
+ on its panel id.
92
+
93
+ ### Docs
94
+
95
+ - **Pop-out Windows, testing with Playwright, corrected:** turning Chrome's focus emulation off
96
+ doesn't decide which window a toast goes to (headless, nothing changes; headed, it depends on the
97
+ order of clicks and raises). The guide now stubs `document.hasFocus` in the page that should not
98
+ have focus, tests that `focusPanelWindow` is asked for, and leaves real focus to a check by hand.
99
+ - **Pop-out Windows:** when each event arrives, the window's kind, every public name in the API
100
+ summary.
101
+ - **Reviewed for the whole feature:** every guide page that touches pop-outs now says so or links
102
+ to the guide (Introduction, Quick Start, Layout, Panel Lifecycle & Forms, Modals & Side Panels,
103
+ Context Menus, Toolbar, Panel Contributions, Widgets Out of the Panel, Toast, Event Bus,
104
+ Workspace, Advanced, RTL, Theming, Best Practices); Migration has the full 7.11 → 7.12 section,
105
+ with what changed since the pre-releases; the home page, the README and the API comments
106
+ (`popOutPanel`, `PopOutResult`, the four events) describe the final behaviour. "Pop out" no
107
+ longer names floating a panel.
108
+
13
109
  ## [7.12.0-next.1] — 2026-11-21
14
110
 
15
111
  **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 +1644,9 @@ All of the above is additive and backward-compatible: every new field is optiona
1548
1644
 
1549
1645
  ---
1550
1646
 
1551
- [Unreleased]: https://github.com/felipecarrillo100/react-dockable-desktop/compare/v7.12.0-next.1...HEAD
1647
+ [Unreleased]: https://github.com/felipecarrillo100/react-dockable-desktop/compare/v7.12.1...HEAD
1648
+ [7.12.1]: https://github.com/felipecarrillo100/react-dockable-desktop/compare/v7.12.0...v7.12.1
1649
+ [7.12.0]: https://github.com/felipecarrillo100/react-dockable-desktop/compare/v7.11.0...v7.12.0
1552
1650
  [7.12.0-next.1]: https://github.com/felipecarrillo100/react-dockable-desktop/compare/v7.12.0-next.0...v7.12.0-next.1
1553
1651
  [7.12.0-next.0]: https://github.com/felipecarrillo100/react-dockable-desktop/compare/v7.11.0...v7.12.0-next.0
1554
1652
  [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.1-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 |