react-dockable-desktop 7.12.0-next.0 → 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,125 @@ 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
+
86
+ ## [7.12.0-next.1] — 2026-11-21
87
+
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
89
+ production builds, and small additions to pop-out windows only; nothing else changes. Additions
90
+ only.
91
+
92
+ ### Fixed
93
+
94
+ - **What the app hands the library is styled in a pop-out in production.** The app's
95
+ `popoutWrapper` was only around the panel's content. The window's frame (the panel's or widget's
96
+ `icon`, the title) and a context menu shown in the window were outside it, so with CSS-in-JS in a
97
+ production build (rules inserted with `insertRule`) their icons got no styles there: an MUI
98
+ `SvgIcon` measured 0 × 0 and couldn't be clicked, and menu icons were the browser's default
99
+ black. In a pop-out, the wrapper is now also rendered around the frame, a menu shown there and the
100
+ toasts shown there, with that window's `{ window, document }`. The main window is unchanged. The
101
+ wrapper is now rendered more than once per window, so keep one cache per document (the guide's
102
+ `WeakMap` recipe already does).
103
+
104
+ ### Added
105
+
106
+ - **Events `panel:popping-out { id }` and `panel:returning { id }`**, sent just before the panel's
107
+ element leaves the page (once the window's page is ready), and just before it leaves the window,
108
+ whatever brings it back. `panel:popped-out` and `panel:returned` follow. Not sent for a refused
109
+ pop-out, a panel closed while out, or for docking and floating.
110
+ - **Toasts show in the window the user is in.** A toast raised while a pop-out window has focus
111
+ shows in that window; otherwise in the main window, as before. It stays in the window it was shown
112
+ in, and goes when that window closes (its `onClose` runs). No new API. With a `ToastAdapter`, the
113
+ other library decides, as before.
114
+
115
+ ### Changed
116
+
117
+ - **The window's "Return to desktop" button is an icon button in the skin**, the same look as a
118
+ floating window's title-bar buttons (it is also `.rdd-custom-tab-btn`). Its label
119
+ (`returnToDesktop`, or `backIntoPanel` for a widget) is now its tooltip and accessible name, not
120
+ its text: a test that finds it by its text should use its role and name. The class
121
+ `.rdd-popout-frame__return` stays, as the styling hook.
122
+
123
+ ### Docs
124
+
125
+ - **Pop-out Windows:** the production warning also covers icons handed to the frame and menus; the
126
+ wrapper in a pop-out; the new events; testing pop-outs with Playwright; why `popoutUrl` (embeds
127
+ that refuse a blank window, such as a YouTube player); where `inOwnWindow` appears, for
128
+ translators; LuciadRIA's keyboard navigation beside Leaflet's drag; toasts in the focused window;
129
+ the return button. **Toast Notifications:** pop-out windows. **Event Bus** and **Workspace:** the
130
+ new events and `popoutUrl`.
131
+
13
132
  ## [7.12.0-next.0] — 2026-11-21
14
133
 
15
134
  **Pre-release** on npm's `next` tag (`npm install react-dockable-desktop@next`), for feedback before
@@ -1502,7 +1621,9 @@ All of the above is additive and backward-compatible: every new field is optiona
1502
1621
 
1503
1622
  ---
1504
1623
 
1505
- [Unreleased]: https://github.com/felipecarrillo100/react-dockable-desktop/compare/v7.12.0-next.0...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
1626
+ [7.12.0-next.1]: https://github.com/felipecarrillo100/react-dockable-desktop/compare/v7.12.0-next.0...v7.12.0-next.1
1506
1627
  [7.12.0-next.0]: https://github.com/felipecarrillo100/react-dockable-desktop/compare/v7.11.0...v7.12.0-next.0
1507
1628
  [7.11.0]: https://github.com/felipecarrillo100/react-dockable-desktop/compare/v7.10.1...v7.11.0
1508
1629
  [7.11.0-next.1]: https://github.com/felipecarrillo100/react-dockable-desktop/compare/v7.11.0-next.0...v7.11.0-next.1
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.0-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 |