react-dockable-desktop 7.7.4 → 7.9.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,117 @@ replacement and the version that removes the old API.
10
10
 
11
11
  ## [Unreleased]
12
12
 
13
+ ## [7.9.0] — 2026-10-06
14
+
15
+ Control over where users can move panels: per-panel-type rules and an app-wide veto, all opt-in.
16
+ Without them nothing changes, and the app's own API calls are never restricted.
17
+
18
+ ### Added
19
+
20
+ - **`canFloat` and `canDock` per panel type**, next to `canDrag`, `canMinimize` and `canClose`.
21
+ `canFloat: false` keeps a panel in the grid: a tab drag can't end in a floating window (dropped on
22
+ nothing or on a corner, it stays where it was), and "Float Window" and the taskbar's "Maximize" are
23
+ hidden. `canDock: false` keeps a panel floating: dragging it offers no group, tab or edge targets.
24
+ - **`canDrop`, an app-wide veto.** `createWorkspace({ canDrop: ({ panelId, component, to }) => boolean })`
25
+ is asked for every place a dragged panel could go, and for the "Float" and "Maximize" menu items.
26
+ `to` is a `PanelDropTarget`: a group (`leafId` and a `position`, `'center'` also covering a drop
27
+ between tabs), a workspace `edge`, or a `float` (a corner `anchor`, or `null` for a tab dropped on
28
+ nothing). A forbidden target isn't offered: its drop zone, edge or corner doesn't appear, and
29
+ releasing there does nothing. It's asked again at release, so a rule that changes mid-drag holds.
30
+ Positions are the ones the move applies: under RTL, the zone drawn on the screen's right is `'left'`.
31
+ If it throws, the move is allowed and the error is logged. New types: `PanelDrop`, `PanelDropTarget`.
32
+ - Both apply only to what the user does. `floatPanel`, `dockPanelToGroup`, `openPanel` and the other
33
+ calls always work.
34
+ - **`startPointerDrag` takes an optional `onCancel`**, called instead of `onEnd` when the drag is cut
35
+ short (see Fixed).
36
+
37
+ ### Fixed
38
+
39
+ - **A drag built on `startPointerDrag` could outlive its element.** It ended only on pointerup or
40
+ pointercancel, so a window losing focus mid-drag, or the dragged element being removed (an overlay
41
+ widget closed during its own drag, a panel closed during a splitter drag), left its listeners
42
+ attached and its classes on the page, such as the resize cursor. It now also ends on window blur
43
+ and on a lost pointer capture (listened for on the document, where browsers fire it when the
44
+ capturing element is removed). The built-in splitters, window resize handles, sidebar resizer and
45
+ overlay widgets all use it.
46
+ - **The API check missed part of the public API.** Types the API refers to without exporting
47
+ (the workspace config's own type behind `WorkspaceConfig`, among others) were left out of
48
+ `api/react-dockable-desktop.api.md`, so a member removed from them would not have failed CI. The
49
+ report now includes them (`includeForgottenExports`), and `scripts/api-check.mjs` compares them by
50
+ name: 172 declarations are tracked instead of 161. Found while checking that `canDrop` appeared
51
+ in the report.
52
+
53
+ ### Docs
54
+
55
+ - **`keepAlive: false`:** a guard the panel registered with `useBeforeClose` is not active while the
56
+ panel is unmounted (it goes with the component); its dirty flag still is, so closing a hidden
57
+ dirty panel still asks first. Now said in the Panel Registry guide and the option's TSDoc.
58
+
59
+ ### Tests
60
+
61
+ - `ReleaseB.test.tsx` (16 tests): `canFloat` (no float on nothing, no corners, no "Float Window", the
62
+ app's `floatPanel` still works), `canDock` (no group or edge targets, only corners; the app can
63
+ still dock it), `canDrop` (its argument, vetoed zones and edges not offered, RTL positions, tab
64
+ insertion into a vetoed group, a rule changed mid-drag in a tab drag and in a window drag, a
65
+ throwing `canDrop`, no rules meaning every target), and `startPointerDrag` ending on blur and on a
66
+ lost capture. Each rule was seen failing with it broken; the two safety layers (not offered while
67
+ hovering, asked again at release) are pinned separately.
68
+ - `dockZones.browser.ts` (18 tests, real Chrome): a tab dropped on each group zone and each workspace
69
+ edge lands where the user pointed, on screen, in LTR and RTL. With the RTL flip removed, exactly the
70
+ RTL left/right cases fail.
71
+ - `ReleaseA.test.tsx`: empty groups inside a split keep the built-in message; only the root group
72
+ shows the `emptyWorkspace` view. 7.8.0 behaved this way, but no test pinned it. A redundant
73
+ root-only check in `WorkspaceGrid` was removed: nested grids never receive the prop, which is
74
+ what the new test now proves. (Found while porting 7.8.0 to vdd.)
75
+
76
+ ## [7.8.0] — 2026-10-06
77
+
78
+ More control over how the desktop looks and where panels open, all opt-in: without the new options,
79
+ nothing changes. The API check confirms every change is an addition.
80
+
81
+ ### Added
82
+
83
+ - **Your own empty-workspace view.** `<RddDesktop emptyWorkspace={<Welcome />}>` shows your element
84
+ while no panel is docked, in place of the built-in "Empty Workspace Section" message: a welcome
85
+ screen, a logo, "Open a file" buttons. Floating windows still show over it, and a window can still
86
+ be dropped onto it to dock. Other empty groups in a split keep the built-in message.
87
+ - **Open a panel beside another.** `openPanel(id, component, { dockTo: { panel, position, size } })`
88
+ docks a new panel as a tab in that panel's group (`position: 'center'`) or in a new group split off
89
+ on one side, taking `size` (0.1–0.9) of the split. It wins over `initialTarget`. If the target
90
+ panel isn't docked, the new panel is placed as usual, with a development warning.
91
+ - **State attributes for your CSS.** Tabs carry `data-rdd-selected` (shown in their group),
92
+ `data-rdd-focused` (the workspace's active panel) and `data-rdd-dirty`; floating windows carry
93
+ `data-rdd-focused` and `data-rdd-maximized`. Each is present only while it is true, so
94
+ `[data-rdd-dirty]` styles unsaved panels without relying on internal class names. The existing
95
+ classes are unchanged.
96
+ - **Per-panel-type classes.** `className` and `tabClassName` in a panel type's `defaultOptions`
97
+ add your class to every panel of that type (on its content element, which moves with it) and to
98
+ its tab.
99
+ - **`keepAlive: false`**, per panel type: the component unmounts while the panel is an unselected
100
+ tab or minimized, and mounts afresh when shown, to free what a heavy, rarely shown panel holds.
101
+ Its own state is lost each time; its tab, title and lifecycle continue, and `onClose` is called
102
+ only when it is really closed. The taskbar shows a placeholder preview for it. The default is
103
+ unchanged: panels stay mounted and keep their state.
104
+
105
+ ### Docs
106
+
107
+ - New page, **[Using it with MUI, Bootstrap or Tailwind](https://felipecarrillo100.github.io/react-dockable-desktop/guide/ui-frameworks)**:
108
+ dark-mode bridging for each, the z-index of the library's layers next to the frameworks', why a
109
+ framework popup opened inside one of the library's modals appears behind it and the two fixes,
110
+ resets, and the order to try when overriding styles.
111
+ - Theming: **Styling by state and by panel type**. Layout: **Opening beside another panel**. Panel
112
+ Registry: **Freeing a hidden panel**. The `openPanel` options, `RddDesktop` props and
113
+ `defaultOptions` tables list the new options.
114
+
115
+ ### Tests
116
+
117
+ - `ReleaseA.test.tsx` (15 tests): the empty view (shown and gone as panels dock and close; a
118
+ floating window can still dock into it), the state attributes on tabs and windows, `dockTo`
119
+ (sides, centre, size clamping, winning over `initialTarget`, the fallback and its warning, no
120
+ effect on an open panel), the per-type classes (also after floating), and `keepAlive: false`
121
+ (unmount and fresh remount, no `onClose` on hide, the placeholder preview, the default
122
+ unchanged, and no leak over 50 hide/show cycles). Each was seen failing with its feature broken.
123
+
13
124
  ## [7.7.4] — 2026-10-06
14
125
 
15
126
  A written stability policy, and CI that enforces it. No API or behaviour change.
@@ -1058,7 +1169,9 @@ All of the above is additive and backward-compatible: every new field is optiona
1058
1169
 
1059
1170
  ---
1060
1171
 
1061
- [Unreleased]: https://github.com/felipecarrillo100/react-dockable-desktop/compare/v7.7.4...HEAD
1172
+ [Unreleased]: https://github.com/felipecarrillo100/react-dockable-desktop/compare/v7.9.0...HEAD
1173
+ [7.9.0]: https://github.com/felipecarrillo100/react-dockable-desktop/compare/v7.8.0...v7.9.0
1174
+ [7.8.0]: https://github.com/felipecarrillo100/react-dockable-desktop/compare/v7.7.4...v7.8.0
1062
1175
  [7.7.4]: https://github.com/felipecarrillo100/react-dockable-desktop/compare/v7.7.3...v7.7.4
1063
1176
  [7.7.3]: https://github.com/felipecarrillo100/react-dockable-desktop/compare/v7.7.2...v7.7.3
1064
1177
  [7.7.2]: https://github.com/felipecarrillo100/react-dockable-desktop/compare/v7.7.1...v7.7.2
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.7.4-blue.svg)](https://www.npmjs.com/package/react-dockable-desktop)
3
+ [![npm version](https://img.shields.io/badge/npm-v7.9.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)
@@ -25,15 +25,17 @@ serialised layout format**, so a layout saved by either library loads in the oth
25
25
 
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
+ - **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
28
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
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
30
31
  - **Touch & Mobile Ready** — full iPad and Android support: long-press to drag tabs, touch resize, 44px coarse-pointer targets throughout
31
- - **Zero-Unmount DOM Persistence** — panel DOM nodes are moved, never destroyed, across docking, floating, and tab-switching alike, all by default; WebGL, maps, terminals, and forms retain full state with zero integration work
32
+ - **Zero-Unmount DOM Persistence** — panel DOM nodes are moved, never destroyed, across docking, floating, and tab-switching alike, all by default; WebGL, maps, terminals, and forms retain full state with zero integration work (a heavy, rarely shown panel type can opt out with `keepAlive: false`)
32
33
  - **i18n & RTL** — full Right-to-Left layout support; `dir="rtl"` flips every control, tab order, and drop zone automatically
33
34
  - **Inter-Panel Pub/Sub** — lightweight typed event bus for decoupled panel-to-panel communication
34
- - **Imperative API** — the workspace from `createWorkspace()` opens, closes, focuses, and serializes panels from anywhere — inside or outside React
35
+ - **Imperative API** — the workspace from `createWorkspace()` opens, closes, focuses, and serializes panels from anywhere — inside or outside React; `dockTo` opens a panel beside another, on any side or as a tab
35
36
  - **Layout Serialization** — save and restore the full workspace as a JSON string; survives page reloads
36
37
  - **7 Built-in Skins** — VSCode, macOS, Chrome, Slate, Nord, Obsidian, Tokyo — all fully themeable via CSS variables
38
+ - **Works beside your UI framework** — MUI, Bootstrap, Tailwind and others: every class is `rdd-` prefixed, state attributes (`data-rdd-dirty`, `data-rdd-focused`, …) and per-panel-type classes to style against, and your own empty-workspace view ([guide →](https://felipecarrillo100.github.io/react-dockable-desktop/guide/ui-frameworks))
37
39
  - **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
38
40
  - **Drag-Resize Primitives** — `startPointerDrag()` and `computeResizedRect()`, the same pointer-capture mechanics and 8-directional resize math the built-in resizers use, exported for building custom resizable UI inside your own panel content ([guide →](https://felipecarrillo100.github.io/react-dockable-desktop/guide/advanced#building-custom-drag-resize-interactions))
39
41
  - **Zero extra dependencies** — no runtime dependencies beyond React itself; everything is bundled in
@@ -462,6 +464,7 @@ Complete guides, API reference, and interactive demo at:
462
464
  | [Panel Overlay](https://felipecarrillo100.github.io/react-dockable-desktop/guide/panel-overlay) | `RddPanelOverlay`, panel toolbars, `RddFloatingWidget`, `useFloatingWidgets` |
463
465
  | [Toast Notifications](https://felipecarrillo100.github.io/react-dockable-desktop/guide/toast) | `toast` singleton, `<RddToasts>`, queue behaviour, theming, `ToastAdapter` |
464
466
  | [Migration Guide](https://felipecarrillo100.github.io/react-dockable-desktop/guide/migration) | Upgrading across major versions |
467
+ | [UI Frameworks](https://felipecarrillo100.github.io/react-dockable-desktop/guide/ui-frameworks) | Using it with MUI, Bootstrap or Tailwind: dark mode, z-index, overrides |
465
468
  | [Stability & Versioning](https://felipecarrillo100.github.io/react-dockable-desktop/guide/stability) | What the public API is, deprecation and support periods |
466
469
  | [API Reference](https://felipecarrillo100.github.io/react-dockable-desktop/api/) | Full type-level reference for all exports |
467
470